docs(blueprint/intent-catalog): 立意图目录 concept 模块——目录/正文两层模型与 W1–W14 承重墙纲目,并入 handoff 试点的信息归属与任务简报
All checks were successful
Push & PR Check / check (push) Successful in 1m4s

- 新增 .blueprint/modules/intent-catalog.md:为什么(含 09-30 /goal 被提前判达成的实证)、两层模型、承重墙表(指向已有机制,只列待补)、并入与依赖、13 个待设计问题、不做什么、分阶段、收益度量与退出条件、IC1 设计卡、4 条决策记录
- manifest 追加 intent-catalog(concept,backend)与 3 条边(blueprint-governance、agent-client-capability-packs 为依赖,governance-feedback-loop 为相关);updated 改为 2026-10-04
- 只做蓝图同步,不改代码、模板与分发层;与 P8 并行,不碰其热点文件

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
lanrtop 2026-10-04 01:19:48 +09:00
parent 23c50eccca
commit aaabd0b231
2 changed files with 124 additions and 1 deletions

View File

@ -6,7 +6,7 @@ description: >
项目自身保留业务规则、测试、部署声明与交付决策。炼境本身亦被纳入其中, 项目自身保留业务规则、测试、部署声明与交付决策。炼境本身亦被纳入其中,
形成可自我进化的开发智能闭环。 形成可自我进化的开发智能闭环。
iteration: 1 iteration: 1
updated: 2026-10-03 updated: 2026-10-04
agent_button_carrier: tauri agent_button_carrier: tauri
@ -525,6 +525,15 @@ modules:
note: "技术栈评估:Tauri v2 + Rust + React/TS 适合管家方针,不换栈。按收益排序的结构改进:A1 本体与投影分离(2026-10-03 改写为三段——A1a 随 agent-client-parity P8b 落地的投影无关适应度测试、A1b 按需 CLI 薄客户端、A1c 触发式拆 core crate;P4/P8 不再依赖拆 crate)、A2 前后端类型契约生成、A3 配置文本模板化、A4 MCP 改用官方 rmcp SDK(P4b 轨迹环排在其后)。" note: "技术栈评估:Tauri v2 + Rust + React/TS 适合管家方针,不换栈。按收益排序的结构改进:A1 本体与投影分离(2026-10-03 改写为三段——A1a 随 agent-client-parity P8b 落地的投影无关适应度测试、A1b 按需 CLI 薄客户端、A1c 触发式拆 core crate;P4/P8 不再依赖拆 crate)、A2 前后端类型契约生成、A3 配置文本模板化、A4 MCP 改用官方 rmcp SDK(P4b 轨迹环排在其后)。"
position: [3750, 950] position: [3750, 950]
- id: intent-catalog
name: 意图目录
area: backend
status: concept
progress: 0
updated: 2026-10-04
note: "目录层(人持有的意图、方向、验收坐标、不做什么)与正文层(蓝图)两层模型;定位为全生命周期信息的骨架与索引,书装意图、指向事实;以 W1–W14 承重墙为设计纲目。并入 handoff 试点的信息归属与最小任务简报;安全派发与状态语义收敛留在 blueprint-governance 作前置。下一步 IC1 设计文档,与 P8 并行只写文档,实现等 P8 收口。"
position: [4000, 950]
edges: edges:
- from: project-resource-broker - from: project-resource-broker
to: project-dev-variables to: project-dev-variables
@ -867,3 +876,13 @@ edges:
- from: architecture-evolution - from: architecture-evolution
to: agent-client-parity to: agent-client-parity
type: dependency type: dependency
# 意图目录:安全派发与状态语义收敛(blueprint-governance 前置)、版本化 pack 机制在先;修订历史与否决理由回流复用治理反馈闭环。
- from: blueprint-governance
to: intent-catalog
type: dependency
- from: agent-client-capability-packs
to: intent-catalog
type: dependency
- from: governance-feedback-loop
to: intent-catalog
type: related

View File

@ -0,0 +1,104 @@
# 意图目录(intent-catalog)
> status: concept | created: 2026-10-04 | 下一步:/architect 出设计文档(IC1),用户确认后转 planned
> 来源:2026-10-03~04 与用户讨论(/goal 与 Loop Engineering 操作手册、目录/正文模型、承重墙),以及侦察工作流 wf_6dc3756a-b72 的重叠与冲突扫描。
## 为什么
- 用户能给的是需求、意图方向和已知现状,不是评估器能判定的条件。/goal 这类无人值守 loop 需要可判定的终点,这一步翻译应由 agent 完成,但 agent 需要一个人持有、稳定的意图来源。
- 现状:意图散在 AGENTS.md「项目定位」、统筹文档 §0、设计文档的决策节、manifest description 和私有记忆里;manifest 的 areas 按技术层分区,不按意图方向。
- 实证:2026-09-30 的 `/goal 按照方针设计方向走,直到符合设计要求` 跑了 3 轮,评估器就以「设计已完成」为由判定达成并解除了 goal。评估器不读文件,条件只能写成可判定的终点。
- 与 `docs/tasks/2026-09-23-blueprint-agent-handoff-pilot.md` 的「项目工作账本 + 信息归属 + 最小任务简报」同构,应合并推进,不能分两处做。
## 模型(概念,待设计确认)
- **两层**:目录层由人持有,保持稳定;正文层是蓝图模块与任务卡,由 agent 维护。
- **书的比喻**:
- 前言是长期方针,只指向 AGENTS.md「项目定位」,不另抄一份。
- 每一章是一个意图方向。
- 章首导语写意图、双坐标(人看的投影坐标 + agent 可断言的坐标)和「不做什么」。
- 附录放现状指针、约束、决策与否决理由(勘误表)。
- 索引是稳定 ID,书签标出当前阶段。
- **定位**:它是全生命周期信息的骨架与索引,不是容器——**书装意图,指向事实**。代码、CI、状态、会话、凭据和环境都留在原生位置,书里只放可机器校验的指针;意图由人写,现状由机器采。
- **迭代**:
- 修订分三级:补丁指正文内的改动,agent 自主完成;小版本指调整章首坐标或由正文反推修改目录,agent 提案、人确认;大版本指增删章节或调整方向,由人主导。
- 配套机制:沿 ID 做影响分析;版本钉住,卡和 goal 记录自己编译自哪一版目录;保护在制品;修订历史回流飞轮。
- **/goal 的来源**:由架构 agent 从「当前章的验收坐标 + 本阶段卡的完成判定」编译,人确认后粘贴,粘贴这一下即确认。
## 承重墙(设计纲目)
agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题:落在书的哪个部位、靠什么机制承重、怎样用机器检查它生效、什么情况下算拆除(拆除即撤销对应机制)。原则是能指向已有机制的,就不新建。
| 墙 | 已有承重机制(指向) | 待补 |
|---|---|---|
| W1 迭代 | 模块迭代记录与决策记录;能力包、托管块、模板指纹三重版本 | 目录版本层、修订分级、版本钉住;与 manifest.iteration 语义分开 |
| W2 遗忘 | 启动读蓝图;catchup/taskify;统筹文档 §0;复盘笔记 | 稳定入口回答「整体方向走到哪」;书签载体;方向与卡的双向索引 |
| W3 熵增 | 文档防腐 T1–T4;模板指纹测试;blueprint-gate;梦核蒸馏 | 指针可解析门控(只警告);禁止索引膨胀成正文 |
| W4 意图鸿沟 | 需求对齐协议与确认卡;Feature-Confirmed;双尺子;辩证收缩 | 章级意图与「不做什么」;卡挂回意图章 |
| W5 注意力稀缺 | 统筹三类找人;pending_user;回传只列待处置 | 跨章的「待人裁决」视图;书签由人确认 |
| W6 理解债 | 决策记录;复盘笔记;架构速查;导师上下文 | 从代码或模块反查「服务哪条意图」;关键决策摘要推送给人 |
| W7 自评偏差 | 两把尺子;「没验什么」;证据等级;独立/对抗审查;CI 兜底 | 章坐标标注证据等级;章完成只能推导,不能手动切换 |
| W8 不确定性 | R10 先实测;P4-0 假设证伪;三闸门 | 章上挂假设登记与证伪状态,指向既有落点 |
| W9 并发冲突 | 🔵 执行锁;每卡独立 worktree;串行队列;plan→digest→apply | 目录本身成为争用点;版本钉住复用 digest 语义 |
| W10 风险不对称 | 计划→确认→应用;confirmed=true;破坏性标注;凭据边界 | 目录大版本与书签切换的「提案 + digest + 人确认」;章级风险等级 |
| W11 资源有限 | L0/L1/L3 分层;风险预测;提交飞轮指标 | 按章、按 goal 记账(只记账不分配,不替 agent 选模型) |
| W12 环境漂移 | 工具链状态;诊断;verify_onboarding;L1 对等检查 | 基本齐全,目录只放工具指针 |
| W13 异构 agent | canonical context;AGENTS.md 跨端单一来源;三端对等 | 模型无关的 goal 编译流程(/architect 只有 Claude 有) |
| W14 摩擦重复 | 使者回传闭环;梦核;Rules-Applied;管家准入 | 修订历史与否决理由回流(复用 envoy 与复盘笔记,不新建账本) |
## 并入与依赖
- **并入**:handoff 试点中的「信息归属与同步契约」和「最小任务简报的按需读取与回执」两项。
- **留在 blueprint-governance 作为前置**:「安全派发 + blueprint-baseline 能力包」和「任务状态语义收敛」。
- **依赖**:blueprint-governance(安全派发)、agent-client-capability-packs(版本化 pack 机制)。
- **相关**:governance-feedback-loop(修订历史与否决理由回流)。
## 待设计问题(IC1 须逐条化解)
1. 「意图层」现有三处归属:CONVENTIONS「蓝图定位(意图层)」、agent-button-system「意图层 — AGENTS.md」,以及本模型。设计时需先定死术语映射,并且只在一处改名。
2. 红线:章的完成只能从卡状态加 human_verify 推导,不能做成人手动切换(AGENTS.md 设计红线)。
3. 前置:CONVENTIONS 中 in_progress/done 一处说从 Git 推断、另一处说手标,影响分析不能建立在未收敛的状态语义上。
4. 分类轴对应:修订分级、需求对齐协议(Bug/Feature × S/M/L)、文档元规则 T1–T4、manifest.iteration 之间的对应关系;考虑新增 T5「意图变更」,避免另起一套。
5. ID 前缀:承重墙用 W1–W14,章用 INT-xx,卡用 IC(2026-10-04 用 git grep 确认均未被占用)。
6. 「goal 级确认可代替逐卡确认」:起草立法提案,边界是写运行中的 DB、删除、human_verify、超出当前章的工作仍须找人。等 P8 跑完、用实测数据再定。
7. W11 只记账、不分配;CONVENTIONS 复杂度表把复杂度映射到模型名,与 handoff 的「不映射模型名」矛盾,交给前置一起收敛。
8. 防止容器化:目录只放 ID、一句话意图和指针(参照 project-context.yaml 的 label/paths,但禁止长 doc 字段),并配一个只警告的指针可解析门控。
9. 书签与统筹文档 §0 的交接:P8 期间只做指向;之后改为 agent 起草书签、人确认,统筹文档只管派单与交接。
10. 离线与降级:目录放在项目 Git 中、离线可读;影响分析与跨项目索引走 MCP 查询,并保留直接读文件的降级路径。
11. 跨 agent:goal 编译流程写成模型无关的形式(CONVENTIONS「复杂功能分析流程」),不能只靠 Claude 的 /architect。
12. 子项目已有的意图载体(例如 enterprise 的 `.specify/specs/.../spec.md`)只做指向,不复制。
13. 目录的物理位置与前言的归属(例如 `.blueprint/catalog.md`、`docs/intent/`,或放在 AGENTS.md 块外)。
## 不做什么
- 设计确认且 P8 收口之前,不写代码,不改接入包模板、CONVENTIONS、AGENTS.md、分发层和 P8 热点文件。
- 不给存量卡回填 `intent:`;试用阶段只在新卡上可选填写。
- 炼境不替 agent 编译 goal、选模型或判定完成;炼境只提供结构、校验、现状采集与查询。
- 不把蓝图的版本化事实源搬进炼境 DB,不让子项目依赖炼境在线,不建派发调度器。
## 分阶段
1. 立 concept 模块(本次)。
2. IC1 设计文档,与 P8 并行,只写文档。
3. 在炼境自身试用:新增目录文件,新卡可选 `intent:`。
4. P8 收口后:补前置,加只读校验与影响分析。
5. enterprise 隔离试点。
6. 按实测结果决定:并入能力包分发,或撤销。
## 收益度量与退出条件
- 度量:/goal 一次判对率、人工介入次数、续接所需的上下文量、方向返工与 human_verify 否决率、每阶段 token 用量。
- 退出:实测无收益、已被 agent 原生能力覆盖,或维护成本超过收益时撤销(管家准入与退出)。
## 任务卡
### 💭 IC1 — 意图目录设计文档(/architect)
- status: concept
- notes: 产出 `docs/tasks/<日期>-intent-catalog-design.md`,以 W1–W14 为纲、书模型为体,逐条化解上面的待设计问题,写明收益度量与退出条件;完成后交用户确认,确认后模块转 planned,再用 /splitter 拆成 S/M 卡。
## 决策记录
- 2026-10-04 归属:新建本模块,并入 handoff 试点的「信息归属 + 任务简报」部分;不做 blueprint-governance 的新迭代。理由:目录层叠在蓝图之上,需要独立的家;governance 已 done,开新迭代会改变全局 iteration 口径;独立模块也便于按退出条款整体撤销。
- 2026-10-04 时机:与 P8 并行做设计,只写文档、在独立 worktree 中进行;实现等 P8 收口后再做。理由:改动的文件与 P8 不重叠,设计也需要时间,等 P8 收口正好衔接。
- 2026-10-04 试点范围:先在炼境自身试用。理由:先在自己身上踩坑成本最低;enterprise 主工作区有他人的在制品,分发机制也尚未安全化。
- 2026-10-04 立法:「goal 级确认代替逐卡确认」只在设计中起草提案,P8 之后再定。理由:先用 P8 的实测数据说话;这条规则依赖「章」的定义;现在改托管块会和 P8 撞车。