性能、上下文与稳定性经验¶

一次阶段运行二十到四十分钟是否正常¶

业务复杂度会影响工具、Checker 和文档生成时间，但仅靠时长不能判断正常。有效长任务会持续产生不同工具调用、文件变化或逐步缩小失败集合；无效长任务通常反复读取相同大文件、重复全量检查、连续压缩或在无状态变化时重述结论。

记录阶段开始时间、最近五次工具调用、目标文件 mtime、失败次数和压缩发生时间，比观察 TUI 画面更可靠。

机制：压缩只总结已有历史。如果压缩后任务提示立即要求全文读取大量报告、契约、docs 和源码，新上下文会很快再次超限，Agent可能一直建立认识而没有修改。

处理：把评估和增量任务改成索引优先、责任队列、每次一个目标、证据落盘。压缩摘要保存当前 id、已读索引、待处理项和下一动作，不重复塞入全文。GuideDoc 提供短执行版，详细契约按问题定向读取。

预防：限制单次工具输出，使用行范围和结构化查询；不要把“完整了解流程”解释为逐字读完所有文件。

该异常表示 HTTP 流在完整响应结束前被对端关闭。可能涉及模型服务、代理、网络链路、超时或大请求下的连接稳定性。它不是业务文件被锁定直接造成的 Python 文件写错误。

如果异常总在读取某个文件后发生，文件可能只是下一次模型请求的最后一个工具结果，并不证明读取动作本身崩溃。应比较请求上下文大小、是否连续发生在模型节点、短请求能否成功、不同代理路径和服务端日志。一次性编辑内容过多会增大生成时长和响应体，是风险因素，但仅凭堆栈不能确认是唯一原因。

UCAgent 历史快照可能改变权限，或另一个进程正在处理同一工作区。文件锁/只读与模型流中断是不同层面。检查 stat、进程、历史权限守护和实际写入错误。Makefile 已负责恢复历史与 workflow 可写状态；增量部署使用原子替换，不依赖原文件原地写。

UI 自动验证退出时，浏览器会删除 profile 中的 lock，清理线程同时遍历可能得到 ENOENT。如果只是 tmp 下 lock 消失且验证返回码正常，这是清理竞态警告。清理器应忽略已不存在路径，并在停止 UI 验证后一次删除整个 tmp/ui_validation/。

模型流异常的堆栈通常停在 httpx/openai streaming；业务错误通常由 Tool 或 Checker结构化返回；本地文件权限错误会出现具体 PermissionError 或 replace 失败。记录异常发生节点、请求前最后工具结果大小和自动 retry 后行为。

短请求稳定而携带大文档的同阶段反复断流，说明上下文或响应规模是高概率因素，但仍需比较代理和服务端限制。换网络后仍失败只能排除部分链路，不能证明唯一根因。

第一轮只读取 manifest、目录和目标索引；每个问题读取直接源码及一层依赖；工具结果限制行数；证据及时写结构化报告；压缩摘要保存已完成 id 和下一动作。不要在每次 stage prompt 中内嵌 300 行评估契约。

生成十份文档时先写完本批，再一次 make check_docs。失败后只修失败文件并运行专项检查，阶段结束前再跑全量。Tool 和 Checker独立源码可并行准备，共享 config/spec 必须串行提交。这能减少模型轮次，又不牺牲最终证据。

至少记录 stage、开始时间、最近变化时间、调用数量、失败次数、压缩次数、目标文件数和最终返回码。跨业务比较这些数据，才能判断新规则是否真的改善速度，而不是只凭一次主观体验。