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 逐阶段实施与验收。完成后按处置条款清理本简报。