控制台与端口问题¶
Address already in use¶
现象：启动 eval-ui 时提示 127.0.0.1:8765 已被使用。
原因：同一端口已经有控制台或其他程序监听。HTTP 服务不能重复绑定同一地址端口。
确认：
如果已有正确工作区的控制台，直接打开它；如果需要并行控制台，设置 EVAL_UI_PORT=8766。不要让 Makefile自动杀死未知进程。
审批完成后怎样释放端口¶
回到启动 make ... eval-ui 的终端按 Ctrl+C。服务退出后再次用 ss 确认。若终端已经丢失，先根据 PID 确认进程确实是本项目控制台，再发送正常终止信号。
找不到计划或报告¶
控制台以启动时传入的 WS 为根，读取 wfgen/workflow_implementation_plan.md、三个 YAML manifest、eval/incremental_report.json 和 eval/applied_changes.json。不要从 Workflow Builder 源码目录或生成工作流内部寻找这些构建设计文件。
构建设计页面结构不正确¶
固定格式 YAML/JSON 使用结构解析，Markdown 计划按阶段标记和标题解析；没有固定格式的文件显示全文。解析失败时应显示错误和原始文本，不能渲染成空页面。导航属于当前文档，应位于固定基本信息下方，正文独立滚动。
删除版本记录提示不可变¶
版本记录默认不可被 Agent 静默修改，但用户在版本管理界面发起的显式删除应被允许。后端需要校验用户动作、记录 id 和引用关系，删除索引及无人引用的备份。仅改前端隐藏错误不会改变后端不可变策略。
结构化编辑怎样生效¶
页面编辑的是允许字段的草稿，只有点击保存才发送。后端重新校验类型、正文长度、引用、计算字段和并发版本，再原子写入。未保存离开页面应提示，原始文件不能通过通用文本接口任意改写。
页面空白或数据来自错误工作区¶
先请求 /api/meta，核对返回 workspace 与启动命令。浏览器旧标签可能仍连接另一个端口；控制台名字相同不代表工作区相同。再检查 /api/state 和后台 HTTP 状态。不要通过修改前端标题掩盖后端根路径错误。
revision conflict¶
用户打开设计文件后，后台 Agent可能更新同一文件。保存时 revision/hash 不一致应拒绝，并要求重新加载合并。直接覆盖会丢失 Agent新阶段记录。确认冲突时保存当前草稿到用户可见区域，但不能绕过校验写原始文件。
筛选和批量操作¶
筛选只影响展示，不改变状态。批量审批必须使用当前筛选后用户显式选择的 id，不能把隐藏记录一并提交。批准、暂缓、拒绝和未审批是互斥视图维度，已审批是上层集合。操作后刷新并核对每项 source id。
后台进程管理¶
启动终端按 Ctrl+C 是首选退出方式。终端丢失时用 ss 找 PID，再核对命令行和 workspace 后发送 TERM。不要使用宽泛 pkill python。服务退出后确认端口释放，并检查没有残留浏览器验证进程。