diff --git a/.blueprint/CONVENTIONS.md b/.blueprint/CONVENTIONS.md index 9fdae84..641daf9 100644 --- a/.blueprint/CONVENTIONS.md +++ b/.blueprint/CONVENTIONS.md @@ -121,6 +121,27 @@ modules/.md 中的每个二级标题（`###`）是一张任务卡： 不满足条件的 todo 任务保持无前缀，说明还需补充信息。 +### Acceptance 写法规范 + +acceptance 是 agent 自验的唯一判断依据，必须是**可执行断言**，禁止描述性语句： + +``` +❌ "功能正常运行"（描述性，agent 无法判断完成） +❌ "代码正确"（主观，无可执行路径） +✅ "pnpm typecheck 无报错" +✅ "cargo test 通过（src-tauri/）" +✅ "MCP tool list_projects 返回新增项目名" +✅ "pnpm test <测试文件> 全绿" +``` + +最小结构：`[载体] 调用/运行什么(参数) → 断言什么`。 + +含 Rust 业务逻辑的 M/L 卡，acceptance 还须包含（详见 Rust 代码可测试性规范）： +- `cargo test 通过` + 依赖注入写法确认 + +> acceptance 是整个 agent 按钮体系的核心关节。可执行 = 真自验；描述性 = 假闭合。 +> 完整体系见 `docs/ai-context/agent-button-system.md`。 + ### 💭 concept 卡的极简写法 concept 卡是想法 inbox，**不要求 files / acceptance / complexity**，随想随记： diff --git a/AGENTS.md b/AGENTS.md index 76d7218..ca17f58 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -204,7 +204,7 @@ docs/templates/ 炼境接入包模板草案（设计层） | TypeScript 类型检查 | `pnpm typecheck` | 无输出，exit 0 | | 前端单元测试 | `pnpm test` | exit 0，无 FAILED | | Rust 单元测试 | `cargo test`（src-tauri/ 目录） | 无 FAILED | -| MCP 工具调用 | 见 `src-tauri/src/mcp_server.rs` 工具列表 | 返回 JSON，无 error 字段 | +| MCP 工具调用 | 见 `src-tauri/src/mcp_tools.rs` 工具列表 | 返回 JSON，无 error 字段 | | 蓝图状态读取 | 读 `.blueprint/manifest.yaml` | 文件可解析，字段完整 | | 蓝图状态更新 | 编辑 `.blueprint/modules/.md` | 文件写入成功，格式合法 | diff --git a/docs/ai-context/agent-button-system.md b/docs/ai-context/agent-button-system.md new file mode 100644 index 0000000..9dcda00 --- /dev/null +++ b/docs/ai-context/agent-button-system.md @@ -0,0 +1,201 @@ +--- +version: 1.0.0 +updated: 2026-07-03 +usage: 炼境 agent 按钮体系的完整设计文档，供 Claude 理解体系全貌和设计意图；也是分发给子项目的方针来源 +--- + +# Agent 按钮体系 + +> 炼境的核心设计理念：让 AI agent 具备无人值守执行能力的工程基础设施。 + +## 核心命题 + +> 功能只有一份实现，但有两种投影：UI 按钮是给人的，agent 按钮是同一个功能给 AI agent 的投影。 +> 当 agent 按钮完备，验证环路就能在 agent 内部闭合，人不再是执行链的瓶颈。 + +## 双投影设计 + +``` +功能本体（单一实现） + ├── UI 按钮 → 人操作 + └── agent 按钮 → agent 调用 + ├── 可发现（agent 知道它存在） + ├── 可调用（结构化接口） + └── 边界清晰（调的是同一条路径，不是捷径） +``` + +"调同一条路径"是关键：agent 走的验证路径和人走的一致，终验才有意义。 + +## 分工重构 + +没有 agent 按钮时，人卡在验证环节，成为执行链瓶颈： + +``` +人定目标 → agent执行 → 人验证 → 人反馈 → ...（人是瓶颈） +``` + +有了 agent 按钮后，中间的验证环路在 agent 内部闭合： + +``` +人定目标 → agent执行 → agent自验（走agent按钮） → 人终验 +``` + +人只保留两件事： +- **需求澄清**（目标定义权） +- **目标验收**（终验权） + +**人在目标层，agent 在执行层，层间边界清晰，各自自洽。** + +## 四层体系 + +### 意图层 — AGENTS.md +声明方针 + agent 按钮清单。agent 进来第一件事：知道这个项目有哪些 agent 按钮可以调用。 + +### 执行层 — agent 按钮本体 +按项目类型就近选择载体： + +| 项目类型 | agent 按钮载体 | +|---------|---------------| +| Web 服务 | HTTP API（前端按钮与 curl 调同一 endpoint，天然双投影） | +| CLI/脚本 | 命令与 npm scripts | +| 桌面应用 | 测试直接调用 command 函数 | +| UI 呈现层 | Playwright（最后手段，仅关键路径） | + +### 验证层 — acceptance + 可执行断言 +acceptance 是 agent 自验的唯一判断依据，必须是可执行断言： + +``` +❌ "功能正常运行"（描述性，agent 无法执行） +❌ "代码正确"（主观，无可执行路径） +✅ "pnpm typecheck 无报错" +✅ "cargo test 通过（src-tauri/）" +✅ "MCP tool list_projects 返回新增项目名" +✅ "pnpm test import-project 全绿" +``` + +最小结构：`<可执行命令>` + `<通过标准>` = 一条合格的 acceptance。 + +验证层的触发机制，按优先级（模型无关性递减）： + +| 机制 | 触发时机 | 模型无关 | +|------|---------|---------| +| git hooks（lefthook） | commit 时 | ✅ 最强 | +| CI/CD（Gitea Actions） | push 后 | ✅ | +| .claude/settings.json hooks | Claude Code 专属 | ❌ | +| AGENTS.md 约定 | 靠 agent 主动调用 | 语言约束 | + +> `.claude/settings.json` hooks 是 Claude Code 专属的，Cursor / Qwen 等其他工具不会读这个文件。模型无关的验证层靠 git hooks + CI，不能靠 Claude 专属配置。 + +### 持久层 — 目标持久化 +让 agent 跨会话续接，不靠对话记忆： +- 炼境项目：蓝图（`.blueprint/`） +- 子项目完整接入：随炼境分发的蓝图规范 +- 子项目最小接入：`.agent/task.md` + +蓝图在体系里的三个角色： +1. **目标的结构化载体** — 把自然语言目标翻译成带 acceptance 的可执行任务卡 +2. **跨会话共享状态** — agent 跨对话续接的记忆 +3. **自验的判断依据** — acceptance 字段告诉 agent "走到什么状态算通过" + +## 消费者驱动验证 + +普通应用的验证在自身边界内，一个角色（实现者）够用。 + +当产品的产出要被"圈外"消费时（工具、平台、SDK、炼境这类跨 APP 产品），验证必须出圈，天然产生两个角色： + +``` +实现者角色 → "我跑通了"（项目内部视角） +消费者角色 → "你的产出我真的能用"（圈外消费视角） +``` + +两个角色博弈，才能覆盖完整目标。 + +**判断是否需要双角色**：你的产出，有没有圈外消费者？ + +| 产品类型 | 消费者在哪 | 需要几个角色 | +|---------|-----------|------------| +| 普通业务应用 | 圈内（用户即使用者） | 1 个 | +| SDK / 工具 / 平台 | 圈外（其他项目） | 2 个 | +| 炼境 | 圈外（被管理的子项目） | 2 个 | + +> **验证边界要跟着目标边界走，不是跟着实现边界走。** + +炼境的双角色示例： +- 实现者角色：炼境开发角度（导入新项目、跑通接入包分发流程） +- 消费者角色：被管理项目角度（接入包能否真的在子项目里用起来） + +## 三条设计原则 + +辩证结论，缺一会让体系在现实中碎裂。 + +### 原则一：无人值守 ≠ 消灭人工介入 +人工介入是设计内的降级路径，不是体系失败。体系的目标是把人从"执行路径"移到"降级路径"。 + +**自验失败降级约定**： +- 失败 2 次内：自行修正，继续自验 +- 失败 3 次：停止执行，输出以下内容后等待人工介入： + 1. 失败原因（具体报错或不通过的断言） + 2. 已尝试的修正路径 + 3. 需要人决策的具体问题 + +### 原则二：框架由炼境保证，内容由子项目填 +炼境能分发的是结构（AGENTS.md 模板、蓝图规范、lefthook、CI 配置），不能替子项目实现 agent 按钮。 + +分发的最高价值物是 **acceptance 写法规范**——让子项目知道怎么写才算可执行断言，而不是描述性语句。 + +### 原则三：acceptance 是体系的核心关节 +体系其他部分都能降级，acceptance 不能将就。acceptance 写得可执行，自验才是真自验；写得模糊，整个环路是假闭合，无人值守名存实亡。 + +## 炼境自己的 Agent 按钮清单 + +| 能力 | 调用方式 | 通过标准 | +|------|---------|---------| +| TypeScript 类型检查 | `pnpm typecheck` | 无输出，exit 0 | +| 前端单元测试 | `pnpm test` | exit 0，无 FAILED | +| Rust 单元测试 | `cargo test`（src-tauri/ 目录） | 无 FAILED | +| MCP 工具调用 | 见 `src-tauri/src/mcp_tools.rs` 工具列表（21 个工具） | 返回 JSON，无 error 字段 | +| 蓝图状态读取 | 读 `.blueprint/manifest.yaml` | 文件可解析，字段完整 | +| 蓝图状态更新 | 编辑 `.blueprint/modules/.md` | 文件写入成功，格式合法 | + +## 分发给子项目的方案 + +### 完整接入（长期项目推荐） + +``` +接入包 +├── AGENTS.md 模板 ← 含方针 + 按钮清单占位 + 降级约定 +├── .blueprint/CONVENTIONS.md ← 含 acceptance 写法规范 +├── lefthook.yml ← git hooks（模型无关验证层） +└── .gitea/workflows/ci.yml ← CI/CD（模型无关验证层） +``` + +### 最小接入（轻量项目） + +``` +接入包 +├── AGENTS.md 模板 ← 含方针 + 降级约定 +├── .agent/task.md 模板 ← 最小目标持久化（跨会话续接） +└── lefthook.yml ← 最小验证层 +``` + +`.agent/task.md` 格式： + +```markdown +## 当前目标 +<人填写> + +## Acceptance +- <可执行断言 1> +- <可执行断言 2> + +## 状态 +in_progress / blocked / done + +## 阻塞原因（blocked 时填） +自验失败 N 次，具体问题：<描述> +需要人决策：<具体问题> +``` + +子项目只需填入： +- AGENTS.md 里 agent 按钮清单的具体命令 +- 任务卡 acceptance 字段的可执行断言 diff --git a/docs/templates/agents-meta-rules.md b/docs/templates/agents-meta-rules.md index cbea47b..ee64c7f 100644 --- a/docs/templates/agents-meta-rules.md +++ b/docs/templates/agents-meta-rules.md @@ -1,6 +1,6 @@ --- -version: 1.0.0 -updated: 2026-06-29 +version: 1.1.0 +updated: 2026-07-03 usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标准内容 --- @@ -79,3 +79,57 @@ AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 - [ ] `project-brief.md` 最近 30 天有没有随架构改动更新？ - [ ] 有没有两份文档说同一件事且打架？ - [ ] `project-context.yaml` 的契约路径还准确吗？ + +--- + +## Agent 按钮体系 + +> 让 AI agent 具备无人值守执行能力的工程方针。随炼境接入包分发，适用于所有项目和所有 AI 工具。 + +### 分工原则 + +``` +人定目标 → agent执行 → agent自验（走agent按钮） → 人终验 +``` + +人只保留两件事：**需求澄清（目标定义权）** 和 **目标验收（终验权）**。中间的执行与验证环路在 agent 内部闭合。 + +### Agent 按钮清单（接入时必填） + +在项目 AGENTS.md 中声明本项目的 agent 按钮，让 agent 知道有哪些能力可调用： + +```markdown +## Agent 按钮（可调用能力） +| 能力 | 调用方式 | 通过标准 | +|------|---------|---------| +| 类型检查 | `<填入命令>` | `<填入通过标准>` | +| 测试运行 | `<填入命令>` | `<填入通过标准>` | +| 核心功能验证 | `<填入命令>` | `<填入通过标准>` | +``` + +三要素缺一不可：**可发现**（清单里有）、**可调用**（结构化命令）、**边界清晰**（通过标准明确）。 + +### Acceptance 写法规范 + +acceptance 是 agent 自验的唯一判断依据，必须是**可执行断言**，不能是描述性语句： + +``` +❌ "功能正常运行"（描述性，agent 无法判断完成） +❌ "代码正确"（主观，无可执行路径） +✅ "pnpm test 通过" +✅ "curl /api/xxx 返回 200，body.id 非空" +✅ "pnpm typecheck 无报错" +✅ "[命令] 运行什么 → 断言什么" +``` + +含 acceptance 的任务卡才可派发；acceptance 可执行，自验才是真自验——这是整个体系的核心关节。 + +### 自验失败降级约定 + +- **失败 2 次内**：自行修正，继续自验 +- **失败 3 次**：停止执行，输出以下内容后等待人工介入： + 1. 失败原因（具体报错或不通过的断言） + 2. 已尝试的修正路径 + 3. 需要人决策的具体问题 + +> 无人值守不是消灭人工介入，而是把人从"执行路径"移到"降级路径"。降级时主动升级，比静默卡死更重要。