Magent 过程展示改进计划
状态：已实施并完成确定性验证。最后更新：2026-09-21。
已确定的方向
以用户提供的 Codex / agent-shell 截图为参照：
- 简短的进度正文直接显示，说明已发现的事实和下一步。
- 活动分组、标题、展开与折叠完全由 agent-shell 控制，沿用用户现有配置。 Magent 只负责提供类型正确、顺序完整的正文、思考和工具事件。
- 最终答复独立保留。第一版采用主模型自然输出进度的路线；模型未输出 进度正文时展示实际活动状态，不增加额外摘要模型或强制阶段请求。
- 进度采用里程碑节奏：获得影响结论、改变方向、开始修改或验证失败时 更新一至两句；没有新结论时不逐条播报工具调用，但连续六次工具调用 仍无正文时应补充一次真实的阶段进度。
- 任何需要调用工具的任务都先输出一句简短开场，说明首先要确认什么； 即使只需一次读取也保留开场。无需工具的纯问答不强制开场进度。
- 工具或测试失败仅在改变判断、改变后续方案或形成阻塞时立即说明。 可预期的探测失败等形成结论后再更新，避免把试探过程写成流水账。
- 进度正文只包含影响判断的关键对象、事实和下一步，不复述完整命令、 参数或工具输出；这些执行细节继续由 agent-shell 的活动组展示。
- 进度正文作为正常 assistant 消息持久化；恢复会话时按原始顺序重放。 活动细节及其折叠仍由 agent-shell 管理。
- 进度正文固定使用无标题、无项目符号的普通短段落，通常一至两句； 即使同时有多个要点也不改成列表，保持连续的阅读节奏。
- 一至两句是提示词约束和测试目标。模型偶尔输出更长内容时，Magent 原样保留，不在运行时截断或改写；若实际长期偏长，再根据观察收紧提示。
- 用户在执行中改变要求且影响当前方案时，下一次工具调用前先用一句正文 确认新方向；不影响方案的补充信息并入下一次自然进度。
- “连续六次工具调用内更新”是对主模型的提示目标，不是运行时硬保证。 模型未输出正文时不伪造进度，也不增加补写请求；agent-shell 仍显示 真实活动状态。
- 模型暂时没有输出正文、但工具活动仍在继续时，界面显示固定文案 “进行中”。这是运行状态提示，不作为模型进度正文，也不冒充新结论； Magent 只提供准确的生命周期状态，具体呈现仍由 agent-shell 负责。 该提示只在运行期间存在，任务完成、失败或取消后立即消失，不进入 会话历史。
用户已明确：本任务不设计或修改 agent-shell 展示偏好，也不添加 Magent 专属的折叠配置。截图用于说明进度正文与执行细节分离后的阅读体验。
已核实的依据
DeepSeek 支持正文与工具调用并存
官方 Thinking Mode 文档
的工具示例在同一 assistant 消息中返回 reasoning_content~、~content 和
tool_calls~，也展示了 ~content 为空的工具步骤。支持这类输出不等于
每一步都会生成进度正文。
DeepSeek-V4-Pro 官方解析实现
分别提取思考、工具调用前的正文和工具调用。当前文档的示例模型是
deepseek-flash~；用户当前 ~deepseek-v4-pro 路由的实际行为仍需实测。
思考折叠只改变展示。带 tools 的后续请求必须遵守服务端对
reasoning_content 完整回传的要求。
本地已有基础
prompts/system.org已要求开场与阶段进度，强调正文和思考分离。magent-agent.el将工具调用前的助手消息归为 ~commentary~。magent-acp.el将正文和思考分别发为agent_message_chunk和 ~agent_thought_chunk~。- 当前 agent-shell 已提供活动分组、描述性标题和
latest自动折叠行为。 - 只读检查时，思考、工具与活动组的展开默认值均为 nil；没有活动的 agent-shell buffer，尚未获得问题会话的现场输出证据。
已确认并修复的适配缺口
当前 gptel OpenAI 流式解析器在保存工具调用 assistant 消息时使用 ~:content :null~，导致同轮生成的进度正文不进入原生续传历史。Magent 现在 在 gptel 适配边界把已经流向界面的真实正文写回该消息；不生成、截断或改写 正文。真实 gptel 流解析回归测试覆盖了这个缺口。
实施顺序
- 用确定性流式样例覆盖“思考 → 正文 → 工具 → 思考 → 正文 → 工具 → 最终答复”，另覆盖工具步骤无正文的情形。检查实时展示和续传历史。
- 在隔离 Emacs daemon 中，通过现有 gptel 路由测试 ~deepseek-v4-pro~， 区分模型没有生成正文、适配层丢失正文、ACP 消息边界不完整三种情况。
- 依据复现修正必要边界：传输适配留在 ~magent-sampling-gptel.el~， ACP 投影留在 ~magent-acp.el~，由 agent-shell 按现有配置负责展示。 保留 ~gptel-request~，不重写 HTTP/SSE 或新增渲染层。
- 若需调整提示词，仅强化有证据的简短进度和输出位置。配置加载时需
检查
magent-system-prompt是旧的已加载默认值还是用户定制值， 避免覆盖用户定制。 - 验证流式输出、续传、历史恢复、错误、取消与普通无工具问答；运行 与改动相称的 ERT、编译、lint 和隔离 live smoke，更新用户文档。
验收标准
- 正文按时间顺序直接可见，不混入 Thinking 块、不重复、不丢失。
- 正文、思考与工具事件保持正确类型和顺序，供 agent-shell 原生展示。
- 不修改 agent-shell 展示配置；不改变权限、工具执行次数或最终完成判断。
- 对无正文的工具步骤不伪造模型进度，不增加补写请求。
- 工具运行且暂无进度正文时可见“进行中”，并且它不进入 assistant 历史。
- 恢复会话保持消息和活动顺序；失败或取消仍有可检查的状态。
- 明确区分确定性测试通过与当前 DeepSeek 路由的实际观察结果。
后续调查
当前没有未决的产品选择。确定性复现确认：gptel 的 OpenAI-compatible Chat 流会把工具调用前正文发给界面，但在原生 assistant tool-call 续接消息里固定 保存为 null。Magent 现已在适配边界把模型真实输出写回该消息，并用真实 gptel 流解析器覆盖“正文 → 工具调用”的回归测试。
隔离 agent-shell/ACP smoke 已通过。隔离 daemon 中配置的 deepseek-v4-pro 真实请求在 sampling 开始前即被现有诊断环境标为失败，没有产生 assistant、 tool 或 provider 事件，因此该次运行不能用于判断模型是否遵守进度提示；没有 把这一环境问题归因于本次改动。