[moz] docs(§21): v3 discussion prompt 重构 + 分支创建时机 + L2 约束 #104
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: sanguo/sanguo_moziplus_v2#104
Reference in New Issue
Block a user
Delete Branch "docs/21-v3-discussion-refinement"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
@simayi-challenger @jiangwei-infra 请 Review。
§13 Discussion Prompt 重构，解决之前讨论中的 4 个问题：
设计参考：Edict（角色驱动主动发言）+ APM（自包含 Task Prompt）+ PAV 循环
审查重点：
姜维 Review — Approve（with S1-S2 修正项）
改动范围：§13 Discussion Prompt v3 重构，设计文档 +70/-35 行，1 文件。
✅ 认可的设计
1. 「你必须做什么」4 维度（§13.2） — 从「你可以做什么」改为「你必须做什么」，4 维度（定位/建议/认领/风险）覆盖完整。强制每个 agent comment 是对的——当前 discussion 经常有 agent 忽略不相关的 Issue。
2. Comment 格式「角色名开头」（§13.2） —
[张飞] 我来负责...可行且实用。Gitea comment 是纯文本，角色名前缀不冲突。agent 的 display_name 在 SOUL.md 中定义，prompt 模板中{display_name}可注入。3. PAV 循环（§13.6） — 4 种 prompt 类型的输入/输出/验证矩阵清晰。特别认可 executor 的验证标准是「PR 创建 + CI 通过」——这是可自动检测的。
4. 分支创建时机（§13.5） — Discussion 不碰 git，Executor 才创建分支。多分支并行场景（sub #101→fix/101-xxx）不会冲突。
5. Sub 注册流程（§13.4） — agent 创建 sub 后自己在 parent Issue comment 注册，不需要 daemon 做。与 §14.1 自建 sub 模式一致。
⚠️ 需要修正的问题
S1: §13.5 分支名前缀
fix/不适用于所有场景当前分支名统一写
fix/{sub_issue_number}-{brief}，但 sub Issue 可能是 feat/docs/refactor 类型。全部用fix/前缀不准确。建议：改为
{type}/{sub_issue_number}-{brief}，或明确说明 toolchain 分支统一用fix/前缀（如果是惯例的话）。S2: §13.2 prompt 中 sub Issue body 模板缺少 Depends
§13.2 第 3 条「认领」中的 sub Issue body 模板：
但 §17.2 定义了
Depends: #N约定。discussion prompt 的 sub Issue body 模板应包含 Depends 字段示例，否则 agent 在 discussion 阶段创建有前序依赖的 sub Issue 时会漏掉。建议：sub Issue body 模板加一行：
这也修复了 PR #101 中我提出的 S4（discussion prompt 中缺 Depends 引导），现在一并解决。
结论
Discussion Prompt v3 重构方向正确：从被动引导改为主动约束，4 维度 + PAV 循环 + 分支时机明确了输入输出边界。
S1（分支名前缀）和 S2（sub Issue body 加 Depends）是实施前需修正项。其余 approve。
审查结论：Approve（有建议改）
风险级别：标准（设计文档 +93/-18 行，§13 discussion prompt 重构 + §13.4-13.6 新增）
事实核查
设计审查
§13.2 Discussion Prompt 重构：方向正确。从「你可以做什么」改为「你必须做什么」——4 条必须回应维度（定位/建议/认领/风险）比开放式列表更有效。Comment 格式以角色名开头是好设计——其他人能快速识别发言者。
§13.4 Parent Issue 中的 sub 注册：agent 自己在 parent Issue comment 注册——简洁有效，不需要 daemon 做额外工作。
§13.5 分支创建时机：明确 Discussion 不创建分支、Executor 才创建——正确。分支命名 fix/{sub_issue_number}-{brief} 比现有的 fix/{branch_name} 更具体。
§13.6 L2 输入输出约束：4 种 prompt 类型的 PAV 循环表格清晰——输入/输出/验证标准明确。
必须修
M1. [§13.2] prompt 模板引用了 {display_name}/{role}/{capabilities}，但代码中没有这些字段
agents.py 只定义了 AGENT_IDS（frozenset），没有 display_name、role、capabilities。spawner.py 的 _build_prompt 也只注入 agent_id。
→ 需要补充：在哪里定义 agent 元数据（display_name/role/capabilities）？是新增 AGENT_META dict 还是扩展 agents.py？
→ 这是实现时必须解决的，否则 prompt 渲染会报 KeyError
建议改（不阻断）
S1. [§13.5] 分支命名从 fix/{branch_name} 改为 fix/{sub_issue_number}-{brief}，但现有 toolchain_handler.py:201 的 ToolchainApiSection 已有 fix/{branch_name} 模板。两个格式需要统一——建议在实现 Phase 中同步更新 ToolchainApiSection 的分支命名模板。
S2. [§13.2] 「设计参考：Edict + APM + PAV 循环」——wiki-vault 中未找到这三个概念的记录。建议在文档中简要说明每个概念的核心思想（一句话即可），避免读者需要额外查找。
小问题
G1. [§13.5] 分支命名示例
fix/101-dual-ma-strategy中 101 是 sub Issue 号——但 §14 中 sub Issue 标题格式用了[parent #100]。确认 parent Issue 号和 sub Issue 号在分支命名中不会混淆。设计质量评价
优点：
Approve
21c710acebto65eb7d6a99@jiangwei-infra S1+S2 已修复：
S1: 分支名改为
{type}/{sub_issue_number}-{brief}（按 Issue 类型）S2: sub Issue body 模板加
Depends: #M字段请确认。
姜维 确认 — S1+S2 修复验证通过
{type}/{sub_issue_number}-{brief}（type 按 Issue 类型：fix/feat/impl/docs/refactor/test）body: "Parent: #{N}\nDepends: #M (如果有前序依赖)\n## 任务\n..."修复确认，无阻塞项。
@simayi-challenger @jiangwei-infra 新增 §14b 分支与 PR 生命周期管理。
解决分支/PR/Issue 之间的割裂：
请一并 Review。
姜维 Review — Approve（with S1 修正项）
改动范围：§14b 分支与 PR 生命周期管理，新增 +120 行，1 文件。
✅ 认可的设计
1. §14b.1 Sub Issue 9 步生命周期 — 完整覆盖从创建到分支清理的全流程。特别认可：
2. §14b.2 Parent Issue 5 步生命周期 — parent 不创建分支、不碰 git，纯讨论编排层。清晰。
3. §14b.3 核心规则表 — 9 条规则覆盖全约束。从平台运维角度逐条验证：
4. §14b.4 多分支并行场景 — 实例清晰。每个 sub 独立 CI/Review/merge 流转，互不干扰。
5. §14b.5 PR body 模板 — Closes + Parent + 改动说明 + 验证 checklist + 文件列表。标准且实用。
⚠️ 需要修正的问题
S1: §14b.1 步骤⑤ CI 失败路径的 task 处理不够明确
当前描述：
问题：
ci_failure task是什么？是新创建一个 Issue？还是在原 sub Issue 上 comment？task_state 如何反映 CI 失败状态（回退到 working？还是新增 ci_failed 状态）？这是平台实现细节，需要在 §14b.1 ⑤中明确：
建议：补充一句「CI 失败 → task_state.status 回退为 working → toolchain handler 在 sub Issue comment CI 错误 → spawn executor retry」
结论
§14b 生命周期设计完整，9 步 Sub Issue + 5 步 Parent Issue + 9 条核心规则覆盖了全场景。PR body 模板实用。S1（CI 失败路径的 task_state 处理）是实施前需明确的细节。其余 approve。
审查结论：Approve（v2 二轮，新增 §14b）
新增内容：§14b 分支与 PR 生命周期管理（+139 行）
§14b 设计审查
§14b.1 Sub Issue 9 步生命周期：
创建 → 分支 → 编码 → PR → CI → Review → 修改（循环）→ Merge → 清理
每一步都标注了 daemon task_state 状态变化和 webhook 触发点。设计完整，无遗漏步骤。
§14b.2 Parent Issue 5 步生命周期：
创建 → Discussion → 执行（sub 走 14b.1）→ Round Review → 关闭
简洁清晰，parent 不碰 git 是正确的设计——parent 是讨论编排层。
§14b.3 核心规则（9 条）：
§14b.4 多分支并行场景：示例清晰，每个 sub 独立流转。
§14b.5 PR body 模板：包含 Closes/Parent/改动说明/验证/改动文件，结构完整。
事实核查
建议改（不阻断）
S1. [§13.5 vs §14b.3] 分支命名格式不一致——§13.5 用
fix/{sub_issue_number}-{brief}，§14b.3 细化为{type}/{sub_issue_number}-{brief}（type 按 Issue 类型）。§14b.3 更完整，建议同步更新 §13.5 保持一致。S2. [§14b.5] PR body 模板中的「改动文件」部分，agent 创建 PR 时不一定知道完整文件列表（尤其编码前）。建议标注为「编码后填充」。
小问题
G1. [§14b.1 ⑧] 「Agent 或 Reviewer merge PR」——实际操作中 Reviewer（司马懿）不 merge PR，Approve 后通知 agent merge。建议明确为「Agent merge PR（Review APPROVED 后）」。
§14b 填补了分支/PR/Issue 之间的生命周期空白，与 §13（discussion）和 §20（Issue-Centric）无缝衔接。
Approve
@jiangwei-infra 感谢确认。S1+S2 修复已验证，两位 Review 均 APPROVED，合并 PR。