dev-manager-tauri/docs/tasks/2026-09-23-blueprint-agent-handoff-pilot.md

蓝图规则安全派发与 Agent 分工试点

status: todo | complexity: L | created: 2026-09-23 | blueprint: blueprint-governance（待确认新迭代或独立模块） ⚠️ 处置条款：本文件 done 后 24h 内删除；稳定结论沉淀到蓝图决策与复盘，不让简报成为第二事实来源。 类型：Feature / 工作流行为变更。开工前按 AGENTS.md 输出 L 级确认卡，用户确认设计后再拆 S/M 任务卡。本次仅保存讨论，尚未确认实施或修改规则。

为什么（压缩背景 + 证据）

• 来源讨论：codex://threads/01a0c8e3-56a6-79a0-b3f8-0fb3322746b2 提议强模型规划、经济模型执行。该任务可读取的核心回复确认 Codex 支持不同模型的子 Agent 配置，但蓝图复杂度驱动的完整工作流并非原生一键能力；其后数轮正文当时未能读取，勿假定整段会话已核验。官方参考：https://learn.chatgpt.com/docs/agent-configuration/subagents 。
• 当前共识：默认单 Agent 端到端；仅当任务边界清楚、子任务独立、验收可执行且规划成果可复用时试拆分。比较总耗时、使用量、返工、漏验和人工介入，不以单次模型价格判断收益；复杂度单一字段不足以判断风险。
• 炼境负责版本化蓝图基线、派发、自检、采集执行信号；子项目拥有业务规格、项目规则、测试和交付决策。见 AGENTS.md:5、AGENTS.md:287、docs/ai-context/agent-button-system.md:162。Enterprise 新功能规格唯一来源是 E:/code-project/enterprise-system/AGENTS.md:122 指向的 .specify/specs/.../spec.md，蓝图应引用而非复制。
• 安全派发的实锤阻碍：src-tauri/src/commands/blueprint.rs:1434 的 save_user_conventions 保存后自动遍历所有项目同步；:1291 的 sync_blueprint_rules 直接整文件写入项目 .blueprint/CONVENTIONS.md，并更新 AGENTS.md / CLAUDE.md 托管块。当前行为不能安全地“先炼境、再单个 Enterprise 试点、最后推广”。
• 状态语义需收敛：.blueprint/CONVENTIONS.md:25 说 in_progress/done 由 Git 信号推断，同文件 :50 又要求任务卡标 🔵/✅。Git/CI 应给事实证据，Agent 负责完成语义判断，人负责目标终验。src-tauri/src/commands/blueprint.rs:1191 的 synced 主要依据规则版本及 manifest 时间，不能证明蓝图与代码一致。
• 现有 MCP src-tauri/src/mcp_tools.rs:27 可读蓝图，:38 可读项目文件；不必先造调度服务。get_blueprint 在 src-tauri/src/commands/blueprint.rs:304 读路径中追加 usage 快照，可能产生 Git 工作区噪声，应列为治理时的分离候选。
• Enterprise 已有双层验收实例：E:/code-project/enterprise-system/.blueprint/modules/enterprise-company.md:29 的 T3 分列 SQL agent_verify 和页面 human_verify，适合作为任务卡契约样本，但生产 migration 不应成为低成本模型试验任务。
• 2026-09-23 后续讨论澄清了“蓝图”的目标：它不只是静态架构图或模型路由表，更是持续记录方向、任务安排、阻碍、执行反馈和下一步的项目工作账本；炼境是持有账本并为开发 Agent 提供上下文、环境诊断和受限能力的经纪人／管家。人保留目标定义与终验，读过代码的 Agent 保留实现和完成语义判断，炼境负责协调与采集信号。
• 这不等于把 .blueprint/ 全部搬入炼境：项目业务规则、已确认的架构决策、验收契约须随 Git 分支/worktree 与代码同行；日常安排、可重建统计、跨项目索引和按任务提取的上下文更适合由炼境提供。Enterprise 当前 .blueprint/modules/ 有 101 个文件，manifest.yaml 约 43 KB、CONVENTIONS.md 约 46 KB、usage.json 约 611 KB；usage.json 会产生工作区噪声。可用 Get-Item .blueprint/manifest.yaml,.blueprint/CONVENTIONS.md,.blueprint/usage.json | Select-Object Name,Length 和 (Get-ChildItem .blueprint/modules -File | Measure-Object).Count 复核，不应让新会话每次通读全部材料。
• 可验证的收益假设：炼境按当前 project_id、分支/worktree 和任务交付“少而准”的任务简报（目标、相关规则/文件、依赖、可执行验收、现有证据、阻碍及可调用能力），Agent 独立定位、实施、自验后回传证据；与现有方式对照人工解围次数、上下文量、完成至终验耗时、漏验/返工。方向有潜力，尚无实测收益，不能宣称已实现。

改什么（按依赖顺序，非已批准任务卡）

• ⛔ 先向用户提交 L 级设计确认卡，确定本工作是 blueprint-governance 新迭代还是独立模块；确认前不改蓝图基线、不派发 Enterprise。
• 设计安全派发：保存草稿与项目同步解耦，提供目标项目与差异预览；先单项目试点，再显式批量推广。先审 src-tauri/src/commands/blueprint.rs、src-tauri/src/mcp_tools.rs、src/lib/commands.ts、设置/蓝图 UI。
  • 2026-09-30 补充目标：蓝图规则并入能力包范式——登记为 capability-packs.json 中的版本化 pack（如 blueprint-baseline，含 self_check / upgrade_hint），从整文件覆盖 CONVENTIONS.md 改为托管块，与接入包、工具链包同一套机制（依据 AGENTS.md「管家准入与退出」的「分发 vs 查询」）。
  • 同时瘦身分发内容：子项目只留稳定最小核心（状态语义、任务契约格式、复杂度流程）+ 指向 MCP 按需取详细章节的指针；usage.json 等可重建数据移出项目 Git，由炼境持有。
• 统一 .blueprint/CONVENTIONS.md 中任务状态、synced 状态、可执行验收、风险/升级条件和模型无关角色表述；维护版本与兼容旧项目。项目任务卡不写死模型名。
• 设计蓝图信息归属与同步契约：区分炼境的动态工作账本/跨项目视图与项目 Git 中随分支变化的业务决策/验收事实；定义 project_id + 分支/worktree + 任务的定位方式、过期/冲突提示，以及炼境不可用时直接读项目文件的降级路径。先设计，不迁移现有 Enterprise 蓝图。
• 设计最小任务简报的按需读取与回执：Agent 只取本任务相关上下文、能力入口和未验项；回执包含实际验证证据、阻碍与人工终验待办，不能仅凭 Git/CI 信号自动标 ✅。优先复用现有 get_project_blueprint、get_project_file 和项目能力工具，不先造完整调度器。
• 在炼境自己的真实任务卡自测规则；再于 Enterprise 的干净隔离分支/worktree 指定项目试点。先检查 Git 工作区与派发 diff，保留托管块外内容、.blueprint/rules.md、spec 和现有业务任务。
• 先用 Enterprise 与一个轻量项目的低风险真实任务测试“任务简报 → Agent 定位/自验 → 证据回执”，记录接入至首次验证时间、人工解围次数、上下文量、返工和漏验；再在边界稳定的任务上比较单 Agent 与分工模式的总耗时和用量。用失败案例收窄规则；只有效果稳定才考虑结构化任务包/模型建议产品化。

不做什么（边界 + 已否决方案）

• 不把蓝图 complexity 直接映射为模型名——文件数和任务尺寸不等于数据库、权限、生产风险；模型选择留在 Codex/Claude adapter 与当前会话，可被人覆盖。
• 不一开始建设炼境自动派发/执行调度器——现有读取入口已足够试跑，调度和多 Agent 交接成本尚无收益证据。
• 不通过保存规则立即广播所有项目；不覆盖 Enterprise 主工作区既有改动；不自动执行 migration、合并或部署。
• 不把 Enterprise .specify 业务规格再复制进蓝图；蓝图只维护结构、执行拆解、验证证据指针。
• 本次试点暂不把项目蓝图的版本化事实源整体移入炼境数据库，也不让生产项目运行依赖炼境在线——否则分支/worktree 与蓝图可能错位，项目离开平台难以独立开发。可重建统计和任务视图可以中心化，但须可追溯来源并提供导出/降级；长期归属仍待设计确认与实测。
• 不把炼境做成自动裁决代码质量或业务优先级的“上级 Agent”；它是管家与协调者。凭证只通过受限能力按需代办，不把原文、整份 .env、生产 SSH/DB 权限塞进任务简报；凭证代理若成为试点，先审计现有 API Key/Gitea Token 暴露边界，另行确认安全设计。

验收

agent_verify（方案获确认、实施后）：

• [Rust test] 预览项目 A 的蓝图规则升级 → 返回目标版本与差异；项目文件字节不变。
• [Rust test] 保存用户版规则草稿 → 所有已注册项目文件字节不变；显式同步项目 A → 项目 B 字节不变，项目 A 的非托管内容与私有规则不变。
• [CLI] 在炼境与 Enterprise 试点工作区分别检查派发前后 Git diff → 仅预期托管文件变化；未触及已有未提交内容。
• [任务试跑记录] 每张卡可追溯单/分工模式、验收路径、未验项、返工与人工介入；不足数据明确标为未验证，不宣称节省。
• [任务简报对照] Enterprise 与轻量项目各选一张低风险卡 → Agent 只读取相关规则/文件即可定位并复述验收路径；简报标明 project_id、分支/worktree、证据来源，切换分支后不得沿用旧分支的任务事实。
• [降级与噪声] 关闭炼境后 Agent 仍能从项目文件取得业务规则与验收契约；仅查询/查看任务不应新增无关 Git 改动；简报与回执均不含凭证原文。

human_verify（实施后）：

• [UI] 预览差异 → 选择 Enterprise 试点项目 → 明确确认派发 → 能看到目标版本与自检结果；批量推广需另行显式操作。
• Enterprise 会话从项目自己的 spec/蓝图任务卡独立完成一次低风险任务，并由人确认意图与页面结果。

关联（指针，不复制）

• 炼境：AGENTS.md、.blueprint/CONVENTIONS.md、.blueprint/modules/blueprint-governance.md、.blueprint/modules/blueprint-flywheel.md、docs/ai-context/agent-button-system.md。
• Enterprise：E:/code-project/enterprise-system/AGENTS.md、E:/code-project/enterprise-system/.blueprint/modules/enterprise-company.md、适用的 .specify/specs/.../spec.md。
• 蓝图事实与现有入口：src-tauri/src/commands/blueprint.rs:244、src-tauri/src/mcp_tools.rs:27、E:/code-project/enterprise-system/.blueprint/manifest.yaml、E:/code-project/enterprise-system/.blueprint/CONVENTIONS.md。
• Codex 官方模型与子 Agent 文档：https://learn.chatgpt.com/docs/model-selection 、https://learn.chatgpt.com/docs/agent-configuration/subagents 。

新会话启动方式

先读本文件及其关联指针，核对最新 Git 状态和同步代码；不要重做已完成的讨论。优先澄清“动态工作账本 vs 项目版本化事实”的归属与最小任务简报，再审安全派发和模型分工，避免把三者一次性实现。先输出 L 级设计确认卡并等待用户确认，再标本简报 in_progress、拆 S/M 卡，按 checklist 逐阶段实施与验收。完成后按处置条款清理本简报。