diff --git a/.blueprint/catalog.md b/.blueprint/catalog.md new file mode 100644 index 0000000..8392d18 --- /dev/null +++ b/.blueprint/catalog.md @@ -0,0 +1,34 @@ +# 意图目录 +> catalog_version: 1.0 | 前言 → path:AGENTS.md#项目定位 | 语法 → path:docs/ai-context/intent-catalog-guide.md + +## 书签 +- 当前 → path:docs/tasks/2026-10-03-coordination.md#0. 方针与本阶段终点 + +## INT-01 一键接入三端可用 +- rev: 1.0 +- 意图: 新建或添加子项目后一次确认,即可在 Claude Code、Codex、DSH 三端开工 +- 人看: 三端桌面 GUI 新开会话即能调用炼境工具,无需手工配置 +- 机器: card:agent-client-parity#P8;card:agent-client-parity#P8g +- 不做: 不替 agent 选模型;不让子项目依赖炼境在线;不改写客户端的信任表 +- 墙: W12,W13 + +## INT-02 意图编译为可判定终点 +- rev: 1.0 +- 意图: 人给出意图或模糊轮廓,agent 编译出可判定的 /goal:定型章编交付终点,探索章编每轮试验终点,人粘贴即确认 +- 人看: 定型章粘贴 /goal 后一次判对;探索章在预算内收敛为定型章 +- 机器: card:intent-catalog#IC5;card:intent-catalog#IC13 +- 不做: 炼境不编译 goal、不判定完成;目录不存状态与进度 +- 假设: card:intent-catalog#IC13 +- 墙: W1,W4,W7 + +## INT-03 摩擦驱动沉淀与退出 +- rev: 1.0 +- 意图: agent 反复摩擦之处经准入沉淀为跨 agent 能力,实测无收益就撤销 +- 人看: 每条使者回传都有处置回执,撤销的能力在决策记录里查得到理由 +- 机器: module:governance-feedback-loop;cmd:list_envoy_returns +- 不做: 不替 agent 思考或调度;不接管子项目自有事实;不因已经做了而保留 +- 墙: W11,W14 + +## 附录 +- 承重墙 → path:.blueprint/modules/intent-catalog.md#承重墙 +- 决策与否决 → 各模块「决策记录」;终验否决理由 → 卡上 `- 终验:` 行 diff --git a/.blueprint/manifest.yaml b/.blueprint/manifest.yaml index 4f17982..f2e15e6 100644 --- a/.blueprint/manifest.yaml +++ b/.blueprint/manifest.yaml @@ -529,7 +529,7 @@ modules: name: 意图目录 area: backend status: in_progress - progress: 15 + progress: 23 updated: 2026-10-04 note: "两层模型(人持有的意图目录 .blueprint/catalog.md + 蓝图正文),书装意图、指向事实;卡侧 intent 钉版,agent 编译可判定 /goal,确认卡兼作最小任务简报,回执写进提交。IC1 设计已确认(最小文件优先方案);IC2–IC4 只新增文档、可与 P8 并行,门控与接线等 P8 收口后做,IC13 按实测数据决定去留。" position: [4000, 950] diff --git a/.blueprint/modules/intent-catalog.md b/.blueprint/modules/intent-catalog.md index 7a80251..7a110e0 100644 --- a/.blueprint/modules/intent-catalog.md +++ b/.blueprint/modules/intent-catalog.md @@ -1,6 +1,6 @@ # 意图目录(intent-catalog) -> status: in_progress | created: 2026-10-04 | 设计:docs/tasks/2026-10-04-intent-catalog-design.md(IC1 ✅,用户 2026-10-04 确认)| 指南:docs/ai-context/intent-catalog-guide.md(IC2 ✅)| 下一步:IC3(首批章节由用户定稿) +> status: in_progress | created: 2026-10-04 | 设计:docs/tasks/2026-10-04-intent-catalog-design.md(IC1 ✅,用户 2026-10-04 确认)| 指南:docs/ai-context/intent-catalog-guide.md(IC2 ✅)| 目录:.blueprint/catalog.md 1.0(IC3 ✅)| 下一步:IC4(跨 agent 纸面编译) > 来源:2026-10-03~04 与用户讨论(/goal 与 Loop Engineering 操作手册、目录/正文模型、承重墙),以及侦察工作流 wf_6dc3756a-b72 的重叠与冲突扫描。 ## 概述 @@ -42,7 +42,7 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题 | W5 注意力稀缺 | 统筹三类找人;pending_user;回传只列待处置 | 跨章的「待人裁决」视图;书签由人确认 | | W6 理解债 | 决策记录;复盘笔记;架构速查;导师上下文 | 从代码或模块反查「服务哪条意图」;关键决策摘要推送给人 | | W7 自评偏差 | 两把尺子;「没验什么」;证据等级;独立/对抗审查;CI 兜底 | 章坐标标注证据等级;章完成只能推导,不能手动切换 | -| W8 不确定性 | R10 先实测;P4-0 假设证伪;三闸门 | 章上挂假设登记与证伪状态,指向既有落点 | +| W8 不确定性 | R10 先实测;P4-0 假设证伪;三闸门 | 探索章(轮廓、试探、预算、收敛信号)→ 结晶为定型章;「假设:」指向既有的证伪落点(2026-10-04 修订) | | W9 并发冲突 | 🔵 执行锁;每卡独立 worktree;串行队列;plan→digest→apply | 目录本身成为争用点;版本钉住复用 digest 语义 | | W10 风险不对称 | 计划→确认→应用;confirmed=true;破坏性标注;凭据边界 | 目录大版本与书签切换的「提案 + digest + 人确认」;章级风险等级 | | W11 资源有限 | L0/L1/L3 分层;风险预测;提交飞轮指标 | 按章、按 goal 记账(只记账不分配,不替 agent 选模型) | @@ -91,7 +91,7 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题 ## 收益度量与退出条件 -- 度量:/goal 一次判对率、人工介入次数、续接所需的上下文量、方向返工与 human_verify 否决率、每阶段 token 用量。 +- 度量:/goal 一次判对率、人工介入次数、续接所需的上下文量、方向返工与 human_verify 否决率、每阶段 token 用量;探索章另看收敛轮数、是否守住预算、否决理由是否逐轮减少。 - 退出:实测无收益、已被 agent 原生能力覆盖,或维护成本超过收益时撤销(管家准入与退出)。 ## 任务卡 @@ -110,8 +110,8 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题 - depends: IC1 - acceptance: "agent_verify: [CLI] grep -cE '^## (目录语法|修订与钉版|goal 编译|确认卡与回执|离线检查)' docs/ai-context/intent-catalog-guide.md → 5;grep -ciE 'opus|sonnet|haiku|gpt-|deepseek-' 该文件 → 0;/architect 只以「可选包装」出现;git status --porcelain → 只有该文件新增。" -### 📋 IC3 — 新增 .blueprint/catalog.md:1.0 骨架与首批 2–4 章,书签只指向 coordination §0 -- status: todo +### ✅ IC3 — 新增 .blueprint/catalog.md:1.0 骨架与首批 2–4 章,书签只指向 coordination §0 +- status: done - complexity: S - files: .blueprint/catalog.md - depends: IC2 @@ -136,7 +136,7 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题 - complexity: M - files: .claude/hooks/intent-gate.cjs - depends: IC3, P8 收口 -- acceptance: "agent_verify: [gate 脚本] node .claude/hooks/intent-gate.cjs --self-test → exit 0 且输出 self-test ok,内置 5 类坏样例(悬空 path:、未知 INT、超长字段、status: 键、card: 指向不存在的卡)各恰好 1 条警告;node .claude/hooks/intent-gate.cjs → exit 0、真实目录 0 警告;INTENT_CATALOG=/nonexistent → 无输出、exit 0。" +- acceptance: "agent_verify: [gate 脚本] node .claude/hooks/intent-gate.cjs --self-test → exit 0 且输出 self-test ok,内置 6 类坏样例(悬空 path:、未知 INT、超长字段、status: 键、card: 指向不存在的卡、探索章缺预算或收敛信号)各恰好 1 条警告;node .claude/hooks/intent-gate.cjs → exit 0、真实目录 0 警告;INTENT_CATALOG=/nonexistent → 无输出、exit 0。" ### 📋 IC7 — 门控只读视图 --report/--impact/--pending 与目录提交审计 - status: todo @@ -199,3 +199,10 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题 - 炼境 1.0 首批章节方向为「一键接入三端可用 / 意图编译为可判定终点 / 摩擦驱动沉淀与退出」,在 IC3 逐章定稿; - 去留阈值初定为样本 ≥5、一次判对率 ≥60%、人工介入不高于基线、每阶段改目录 ≤1 次,IC13 前可以调整; - 接受在 AGENTS.md 块外常驻约 10 行「启动读目录引言和书签」。 +- 2026-10-04 修订(用户提出,采纳推荐):增加探索章,让意图可以从迭代中结晶。起因是很多需求一开始只有模糊轮廓,甚至没有意图,要靠 MVP 反复试用才慢慢说清。原设计默认自上而下,是盲区。具体做法: + - 章新增可选字段「形态: 定型(缺省)|探索」。它是人对意图清晰度的声明,不是任务进度,因此不违反「目录不存状态」,并且只能由人确认修改。 + - 探索章必填 轮廓、试探、不做、预算、收敛信号。 + - 探索期的 goal 只编译本轮试验的终点;人的试用反馈记成终验行(保留/否决 + 理由),作为结晶原料。 + - 收敛或预算用完时,agent 起草意图提炼,人确认后转为定型(小版本)。未收敛时由人三选一:追加预算、换方向、撤销留墓碑;agent 不得自行延长预算。 + - 修修补补和直接做 MVP 不必开章,目录与卡侧 intent 一律可选。 + - 同步:INT-02 措辞覆盖定型和探索两种形态;指南新增「探索章与结晶」一节和离线检查第 11 条;IC6 坏样例增至 6 类;W8 有了实质承重件;度量增加探索章三项。 diff --git a/docs/ai-context/intent-catalog-guide.md b/docs/ai-context/intent-catalog-guide.md index c17beb6..c58f9b3 100644 --- a/docs/ai-context/intent-catalog-guide.md +++ b/docs/ai-context/intent-catalog-guide.md @@ -50,6 +50,9 @@ | 假设 | 否 | 指向既有的证伪落点(某张 spike 卡或复盘),目录里不存证伪状态 | | 证据 | 否 | 指向已有证据(卡上的 verify 记录、PR) | | 墙 | 否 | 关联的承重墙编号,例如 `W12,W13` | +| 形态 | 否 | `定型`(缺省)或 `探索`;只能由人确认修改,见「探索章与结晶」 | + +**不必开章的情况**:只是修修补补的卡,照常做,不写 intent;属于某个已有章的,就挂上去,算补丁级。完全没有意图、直接做 MVP 的,先不开章,做两三轮以后再从试用反馈里提炼。目录和卡侧 intent 都是可选的,不会挡住任何工作。 **防膨胀(硬限制)**: @@ -119,6 +122,45 @@ git rev-parse --short HEAD:.blueprint/catalog.md **在制品保护**:钉旧版的 🔵 卡照常做完,只复核 acceptance。章被撤销,或新的「不做」覆盖了这张卡时,停下找人。任何情况下都不自动改写卡。 +## 探索章与结晶 + +意图常常不是一开始就清楚的,而是做 MVP、反复试用以后才长出来。探索章就是给这种情况用的:先写下在找什么、找多久,等意图结晶出来再改成定型章。 + +```markdown +## INT-04 <轮廓名> +- rev: 1.1 +- 形态: 探索 +- 轮廓: <人的原话,模糊也可以> +- 试探: <这一阶段想弄清的问题,例如「哪种交互最顺手」> +- 不做: <再模糊也要有的边界> +- 预算: <最多 N 轮 MVP 或 N 天> +- 收敛信号: <出现什么就说明方向定了,例如「连续两轮不再想改核心交互」> +- 证据: <各轮试验卡的指针> +``` + +| | 定型章 | 探索章 | +|---|---|---| +| 必填 | rev、意图、人看、机器、不做 | rev、形态: 探索、轮廓、试探、不做、预算、收敛信号 | +| 回答 | 做到什么样算对 | 我们在找什么、找多久 | +| goal 终点 | 交付终点 | 每轮试验的终点 | +| 度量 | goal 一次判对率 | 几轮收敛、是否守住预算、否决理由是否越来越少 | + +**每轮试验**: +- 拆一张试验卡,挂到探索章上:`- intent: INT-NN@X.Y`。 +- 人试用后,agent 把反应记成卡上的终验行:`- 终验: YYYY-MM-DD 保留|否决:<理由>`。 +- 这些保留和否决的理由,就是结晶的原料。 + +**结晶(探索 → 定型)**: +- 收敛信号出现,或预算用完时,agent 汇总各轮终验行,起草「意图提炼」:建议的意图、人看、机器、不做,以及依据(哪几轮保留、哪几轮否决、为什么)。 +- 人确认后,形态改为定型,按小版本修订:Y+1,本章 rev 更新,轮廓、试探、预算、收敛信号几行换成意图、人看、机器。 + +**预算用完仍未收敛**:由人三选一: +- 追加预算继续,小版本; +- 换方向重写轮廓,小版本; +- 放弃,大版本,留墓碑。 + +agent 不得自行延长预算。 + ## goal 编译 本流程只依赖读文件和 git,不依赖任何特定客户端或模型。Claude 的 /architect 只是可选包装,任何 agent 都可以照着手工执行。产出是一张目标确认卡加一段 /goal 文本。 @@ -136,6 +178,12 @@ git rev-parse --short HEAD:.blueprint/catalog.md - 取各卡 agent_verify 的合取,改写成在会话里能判定的形式:贴出命令和预期输出、纳入卡前缀都是 ✅、回执已写入。 - human_verify 不进终点,单列为终验待办。 - 过程词黑名单命中数必须为 0:「按方针」「符合设计」「设计已完成」「基本完成」,以及任何无法从会话输出判定的形容词。 + - **探索章**不编译「意图的终点」,只编译本轮试验的终点: + - 做出可试用的 MVP 变体,写明最小动作和可演示方式; + - 校验命令通过; + - 试验卡为 ✅ 且已写回执。 + - 人的试用反馈作为终验待办,记到终验行。 + - 确认卡写明这是第几轮、共几轮预算;超出预算就不编译,转入结晶或请人三选一。 6. **写停止条件**:遇到以下任一情况必须停下找人: - human_verify; - 写运行中的数据库; @@ -155,6 +203,7 @@ git rev-parse --short HEAD:.blueprint/catalog.md [INT-NN@X.Y#] 目标确认卡 项目: | 分支/worktree: @ | HEAD: 章意图: <一句> | 不做: <…> +形态: 定型 | 探索(第 k/N 轮;收敛信号: <…>) 纳入卡: <卡键>(来源 agent_verify 原文)、<卡键>(…) 终点(合取): 1) <命令> → <预期输出> 2) … 3) 纳入卡均 ✅ 且已写 Goal-Receipt 终验待办: <各卡 human_verify> @@ -207,6 +256,8 @@ awk '/^## INT-[0-9]{2} /{c=$2} /^- rev:/{print c, $3}' .blueprint/catalog.md cat .blueprint/modules/*.md | grep -c '^### ' # 10. goal 文本的过程词黑名单(把 /goal 文本存成临时文件后检查) grep -cE '按方针|符合设计|设计已完成|基本完成' # → 0 +# 11. 探索章的必填字段齐全(没有输出即通过) +awk '/^## /{if(e&&!(b&&s))print "缺预算或收敛信号: "c; c=$2;e=0;b=0;s=0} /^- 形态: 探索/{e=1} /^- 预算:/{b=1} /^- 收敛信号:/{s=1} END{if(e&&!(b&&s))print "缺预算或收敛信号: "c}' .blueprint/catalog.md ``` card: 指针目前只能人工核对,到模块文件里搜索卡键,Phase 4 后由门控自动校验。指针中带 `#标题` 的部分,也是同样的人工核对方式。 diff --git a/docs/tasks/2026-10-04-intent-catalog-design.md b/docs/tasks/2026-10-04-intent-catalog-design.md index d000d3c..438929b 100644 --- a/docs/tasks/2026-10-04-intent-catalog-design.md +++ b/docs/tasks/2026-10-04-intent-catalog-design.md @@ -1,6 +1,7 @@ # 设计决策:意图目录(intent-catalog)· IC1 > status: 已确认(2026-10-04,五项待拍板全部采纳推荐)| complexity: L(本文只到设计,实现拆为 IC2–IC13)| created: 2026-10-04 | blueprint: intent-catalog +> 修订 2026-10-04:增加探索章(意图从迭代中结晶),见模块决策记录与指南「探索章与结晶」;本文未逐节同步。 > ⚠️ 处置条款:用户确认后,稳定结论回写 `.blueprint/modules/intent-catalog.md`(决策记录与任务卡),本文件在 IC3 完成后 24h 内删除,不做第二事实来源。 > 产出方式:/architect 评审团工作流 wf_60e4c430-bb1。3 个独立方案(最小文件优先、结构化优先、最大化复用)交 2 位评委(agent 友好度与成本、治理与风险)打分,由综合者定稿;关键代码事实已由主会话复核。