From 7907793f1931a766b286b70e12e92b9eb81ffe34 Mon Sep 17 00:00:00 2001 From: lanrtop Date: Sun, 4 Oct 2026 15:34:40 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20MVP=20=E6=94=B6=E5=8F=A3=20M3/M4?= =?UTF-8?q?=E2=80=94=E2=80=94=E5=B8=B8=E9=A9=BB=E6=96=87=E6=A1=A3=E6=BC=82?= =?UTF-8?q?=E7=A7=BB=E4=BA=94=E5=A4=84=E4=BF=AE=E5=A4=8D=EF=BC=8C=E6=8C=89?= =?UTF-8?q?=E9=92=AE=E6=B8=85=E5=8D=95=E6=94=B6=E6=95=9B=E5=88=B0=20AGENTS?= =?UTF-8?q?.md=EF=BC=8Cagents-meta-rules=20=E5=AF=B9=E9=BD=90=E6=89=98?= =?UTF-8?q?=E7=AE=A1=E5=9D=97=201.10.0=20=E5=B9=B6=E9=99=84=E9=80=90?= =?UTF-8?q?=E8=8A=82=E5=AF=B9=E7=85=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- .blueprint/modules/mvp-closure.md | 12 ++--- AGENTS.md | 2 + docs/ai-context/agent-button-system.md | 17 ++----- docs/ai-context/project-brief.md | 2 + .../2026-09-30-dev-variables-materialize.md | 4 +- docs/templates/agents-meta-rules.md | 45 ++++++++++++++----- 6 files changed, 51 insertions(+), 31 deletions(-) diff --git a/.blueprint/modules/mvp-closure.md b/.blueprint/modules/mvp-closure.md index daa8ebe..be0753e 100644 --- a/.blueprint/modules/mvp-closure.md +++ b/.blueprint/modules/mvp-closure.md @@ -26,21 +26,23 @@ - acceptance: "agent_verify: [shell] grep -cE '^### (📋|🔵|💭|🔴)' .blueprint/modules/blueprint-buff.md → 0 且 grep -c '^### ✅' 同文件 → 8；git -C 主仓库 log 中 2026-10-04 的 ff 合并后 git status --porcelain -- .blueprint/modules 为空（零误标）并写入 B2 卡 human_verify 证据；manifest blueprint-buff 为 status: done、progress: 100，模块决策记录写明「剩余 14% 为未更新的进度数字，核心卡已全部完成」。" - 为什么：manifest 记 86%，但模块 8 张卡全 ✅；唯一缺 B2 终验记录，而 2026-10-04 主仓库 6 次快进合并后 .blueprint/modules 零误标，正是 B2 的终验现象。 -### 🔵 M3 — 本轮临时项目与 worktree 清理 -- status: in_progress +### ✅ M3 — 本轮临时项目与 worktree 清理 +- status: done - complexity: S - intent: INT-04@2.0 - files: docs/tasks/2026-10-03-coordination.md - acceptance: "agent_verify: [shell] git worktree list 不含 tmp-p7skill-review、tmp-delivery-status-review、tmp-p10-verify-mut、dev-manager-tauri-wt-p8、dev-manager-tauri-wt-intent、dev-manager-tauri-wt-p8g；[MCP] list_all_projects 不含路径带 lj-p8 的登记。human_verify: 用户手动删除统筹文档 §5「待你手动删除」所列目录与文件。" -- 进展：2026-10-04 agent 侧已执行（unregister 2 条、worktree remove 6 个），待 goal 内复核后标 ✅。 +- verification: "2026-10-04（INT-04 goal）：git worktree list 按六个已清理名称计数 → 0；全局 MCP list_all_projects 完整输出（29 个项目）中 lj-p8 → 0。human_verify（手动删除 §5 所列目录与文件）待用户。顺带发现：list_all_projects 中 dev-manager-tauri 出现两条（组 f2418a3b 与 ffa9e42d），超出本卡范围，未处理。" -### 🔵 M4 — 常驻文档漂移修复 -- status: in_progress +### ✅ M4 — 常驻文档漂移修复 +- status: done - complexity: S - intent: INT-04@2.0 - files: docs/ai-context/project-brief.md, AGENTS.md, docs/ai-context/agent-button-system.md, docs/templates/agents-meta-rules.md, docs/tasks/2026-09-30-dev-variables-materialize.md - acceptance: "agent_verify: [shell] ① grep -c 'onboard/' docs/ai-context/project-brief.md → ≥1；② grep -lE '^#+ 炼境自己的 Agent 按钮清单' AGENTS.md docs/ai-context/agent-button-system.md → 恰好 1 个文件，另一处改为指针；③ grep -c '1.10.0' docs/templates/agents-meta-rules.md → ≥1，且其规则正文与 src-tauri/resources/onboarding/AGENTS.md.tmpl 的 ONBOARDING_MANAGED 块逐节对照无缺漏（差异写进卡片）；④ grep -c '未合入 master' docs/tasks/2026-09-30-dev-variables-materialize.md → 0；⑤ grep -c '\\.agent/task\\.md' docs/ai-context/agent-button-system.md → 0 或改为与现行做法一致的说明；pnpm typecheck exit 0。" - 说明：只改文档，不动 resources/onboarding/ 模板（模板改动会触发指纹测试与版本升级，超出本卡）。 +- verification: "2026-10-04（INT-04 goal）：① project-brief 架构速查补 mcp_inject.rs 与 onboard/ 两行；② 按钮清单以 AGENTS.md 块外区为单一来源（并入 agent-button-system 版多出的 pnpm test 与一键接入两行），agent-button-system 原节改为「按钮清单的位置」指针；③ agents-meta-rules 头部改 version 1.10.0 + aligned_with，能力包五条同步为模板原文、T1/T3/T4/自查措辞同步；④ dev-variables 简报头部改为 frozen、模块已在 master；⑤ agent-button-system 持久层去掉不存在的最小接入文件，改为与单档接入一致。" +- 差异清单（agents-meta-rules ↔ AGENTS.md.tmpl ONBOARDING_MANAGED 1.10.0，全文见 meta-rules「与分发模板的对照」节）: "托管块 7 节中，核心开发约束、需求对齐协议、Git 工作流三节 meta-rules 无、以模板为准不复制；能力包一节已同步，Node/pnpm 工具链只留指针；agent 按钮与验证路径——meta-rules 缺载体就近选择表、完成的定义、侦察→驻军、agent_verify/human_verify 分层与三分定位启发式，多出分工原则、按钮清单模板、降级约定（已不在托管块内）；多 AI CLI 协作与交接模板内容等价。托管块外四支柱、T1–T4、铁律、自查已同步。" ### 📋 M5 — enterprise-system 实战验证四条能力 - status: todo diff --git a/AGENTS.md b/AGENTS.md index d5781a1..e0c25db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -321,8 +321,10 @@ docs/templates/ 炼境接入包模板草案（设计层） | 能力 | 调用方式 | 通过标准 | |------|---------|---------| | TypeScript 类型检查 | `pnpm typecheck` | 无输出，exit 0 | +| 前端单元测试 | `pnpm test` | exit 0，无 FAILED | | Rust 单元测试 | `cargo test`（src-tauri/ 目录） | 无 FAILED | | MCP 工具调用 | 见 `src-tauri/src/mcp_tools.rs` 工具列表 | 返回 JSON，无 error 字段 | +| 一键接入子项目 | MCP `plan_onboarding(project_id)` → 计划给用户看、用户确认 → `onboard_project(project_id, expected_digest=<计划 digest>, confirmed=true)`（两次选项相同；UI 投影为同名 Tauri command，同一本体） | 计划 `blocked` 为空；报告 `status=done`（`partial` 按 `steps`、`completion`、`next_actions` 修复后重跑即收敛；再跑一次全部 `converged`） | | 蓝图状态读取 | 读 `.blueprint/manifest.yaml` | 文件可解析，字段完整 | | 蓝图状态更新 | 编辑 `.blueprint/modules/.md` | 文件写入成功，格式合法 | diff --git a/docs/ai-context/agent-button-system.md b/docs/ai-context/agent-button-system.md index 259d887..2527898 100644 --- a/docs/ai-context/agent-button-system.md +++ b/docs/ai-context/agent-button-system.md @@ -88,9 +88,8 @@ acceptance 是 agent 自验的唯一判断依据，必须是可执行断言： ### 持久层 — 目标持久化 让 agent 跨会话续接，不靠对话记忆： -- 炼境项目：蓝图（`.blueprint/`） -- 子项目完整接入：随炼境分发的蓝图规范 -- 子项目最小接入：`.agent/task.md` +- 炼境与已接入子项目：蓝图（`.blueprint/`），规范随接入包分发 +- 接入包只有一档（见下文「分发给子项目的方案」），不设「最小接入」，也不另设轻量任务文件 蓝图在体系里的三个角色： 1. **目标的结构化载体** — 把自然语言目标翻译成带 acceptance 的可执行任务卡 @@ -179,17 +178,9 @@ Gitea PR 继续使用既有 `create_pull_request` 有界操作；Windows 本机 ### 原则三：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` 工具列表 | 返回 JSON，无 error 字段 | -| 一键接入子项目 | MCP `plan_onboarding(project_id)` → 计划给用户看、用户确认 → `onboard_project(project_id, expected_digest=<计划 digest>, confirmed=true)`（两次选项相同；UI 投影为同名 Tauri command，同一本体） | 计划 `blocked` 为空；报告 `status=done`（`partial` 按 `steps`、`completion`、`next_actions` 修复后重跑即收敛；再跑一次全部 `converged`） | -| 蓝图状态读取 | 读 `.blueprint/manifest.yaml` | 文件可解析，字段完整 | -| 蓝图状态更新 | 编辑 `.blueprint/modules/.md` | 文件写入成功，格式合法 | +单一来源在 AGENTS.md「炼境自己的 Agent 按钮清单」节（常驻上下文，跨工具读取），此处不复制。 ## 分发给子项目的方案 diff --git a/docs/ai-context/project-brief.md b/docs/ai-context/project-brief.md index a480146..c57c701 100644 --- a/docs/ai-context/project-brief.md +++ b/docs/ai-context/project-brief.md @@ -30,6 +30,8 @@ src-tauri/src/credential_store.rs Windows 本机凭证引用、校验与兼容 src-tauri/src/mcp_server.rs MCP Server（agent 调用炼境的入口） src-tauri/src/mcp_tools.rs MCP tool schema 与 dispatch src-tauri/src/envoy.rs 使者回传本体（三端回传写入、处置回执、待处置列表） +src-tauri/src/mcp_inject.rs 接入注入与三端适配（canonical context、Codex 项目配置、Claude local 条目、DSH 托管块、稳定 helper 入口） +src-tauri/src/onboard/ 一键接入本体（客户端适配器注册表、写入前计划、编排与报告、L1 三端检查；不依赖 Tauri、连接注入） src-tauri/src/commands/dev_variables.rs 项目开发变量本体（Agent 登记、人填写、受认证单项读取） src-tauri/src/commands/delivery_status.rs 项目交付信号聚合（Git / Gitea / 部署证据） src-tauri/resources/onboarding/ 接入包分发模板 diff --git a/docs/tasks/2026-09-30-dev-variables-materialize.md b/docs/tasks/2026-09-30-dev-variables-materialize.md index 5dcdba5..5378a76 100644 --- a/docs/tasks/2026-09-30-dev-variables-materialize.md +++ b/docs/tasks/2026-09-30-dev-variables-materialize.md @@ -1,8 +1,8 @@ # 测试账户落地到被忽略文件（project-dev-variables 增量） -> status: todo | complexity: L（拆为 3 张 M 卡）| created: 2026-09-30 | blueprint: project-dev-variables（该模块尚在 `feat/project-dev-variables` 分支，V7 blocked，未合入 master） +> status: frozen（2026-10-04 MVP 收口期冻结为扩展，见统筹文档 §3）| complexity: L（拆为 3 张 M 卡）| created: 2026-09-30 | blueprint: project-dev-variables（模块已在 master；对应卡 V14–V16 为 📋） > ⚠️ 处置条款：本简报 done 后 24h 内删除；结论并入 `project-dev-variables` 模块的决策与任务卡，不让简报成为第二事实来源。 -> 类型：Feature。开工前需用户确认本设计；且须等 `project-dev-variables` 合入 master 后在其模块内立卡。 +> 类型：Feature。解冻后开工前需用户确认本设计（卡已在模块内立为 V14–V16）。 ## 为什么（压缩背景 + 证据） diff --git a/docs/templates/agents-meta-rules.md b/docs/templates/agents-meta-rules.md index c1a293d..c2f333e 100644 --- a/docs/templates/agents-meta-rules.md +++ b/docs/templates/agents-meta-rules.md @@ -1,6 +1,7 @@ --- -version: 1.2.0 -updated: 2026-09-21 +version: 1.10.0 +aligned_with: src-tauri/resources/onboarding/AGENTS.md.tmpl ONBOARDING_MANAGED 1.10.0 +updated: 2026-10-04 usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标准内容 --- @@ -9,12 +10,34 @@ usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标 > 本节由炼境接入包分发，规则技术栈无关，适用于所有项目和所有 AI 工具。 > 项目特定的路径映射见 `docs/ai-context/project-context.yaml`。 +## 与分发模板的对照（ONBOARDING_MANAGED 1.10.0，2026-10-04 逐节核对） + +分发实体是 `src-tauri/resources/onboarding/AGENTS.md.tmpl`，措辞以模板为准；本文件是设计层，补「为什么」，不重复模板全文。 + +| 模板小节（托管块内） | 本文件 | 差异 | +|---|---|---| +| 核心开发约束（包管理、代码规范、Playwright 版本固定） | 无 | 不复制，以模板为准 | +| 需求对齐协议（Bug/Feature 分流、S 级三行卡、M/L 完整卡、Feature-Confirmed、补录≠确认卡） | 无 | 不复制，以模板为准 | +| Git 工作流（git-workflow.md、Conventional Commits） | 无 | 不复制，以模板为准 | +| 炼境项目上下文与能力包 | 同名小节 | 五条已同步为模板原文；Node/pnpm 工具链小节只留指针 | +| agent 按钮与验证路径（1–6 条 + 收束） | 「Agent 按钮体系」 | 本文件有同源同边界、acceptance 写法、自验报告纪律及其「为什么」；缺载体就近选择表、完成的定义、侦察→驻军、agent_verify/human_verify 分层与三分定位启发式（以模板为准）；本文件多出的分工原则、按钮清单模板、自验失败降级约定已不在托管块内（炼境自身见 AGENTS.md 块外区） | +| 多 AI CLI 协作 | 「跨 AI 工具交接模板」 | 内容等价，模板为编号三条 | + +| 模板小节（托管块外） | 本文件 | 差异 | +|---|---|---| +| 四支柱、文档防腐 T1–T4、铁律、定期防腐自查 | 同名小节 | 已同步：T1 补「（若存在）」、T3/T4 改指「本文件（AGENTS.md）」、自查路径写全 `docs/ai-context/` | + ## 炼境项目上下文与能力包 -- 项目根目录 `.lian-jing/context.json` 是工具无关的 `project_id` 单一事实来源；客户端项目 UI、用户级插件和全局配置都不能替代它。 -- `.claude/liangjing.json` 仅用于兼容已接入的旧 Claude 项目；发现 legacy-only 状态时，应通过炼境迁移，不应复制或猜测 ID。 -- `.lian-jing/capability-packs.json` 仅描述炼境托管基线的版本与自检。升级必须显式报告版本不符，并且不能覆盖项目自己的业务规则、测试、部署声明或手工 MCP 配置。 -- 子项目 agent（Claude、Codex、DSH）遇到炼境分发物的摩擦或验证出跨项目实践时，经同一 MCP 入口 `report_envoy_return` 回传；何时回传与字段规范只写在 lian-jing skill，AGENTS 托管块只留一行指路（skill 按需加载，AGENTS 三端必读）。 +- `.lian-jing/context.json` 是项目 `project_id` 的工具无关单一事实来源；不要从客户端项目 UI、用户级插件或全局配置推断项目身份。 +- `.claude/liangjing.json` 只是旧项目的 Claude 兼容投影。只发现它时，调用 `inject_mcp(project_id)` 迁移，而不是手工复制或猜测 ID。 +- `.lian-jing/capability-packs.json` 记录炼境托管基线的版本。`verify_onboarding(project_id)` 报告 `legacy`、`version_mismatch` 等状态时，按其 `detail` 中的升级提示处理。 +- `apply_onboarding_pack(project_id)` 只更新炼境明确托管的接入包文件；项目自己的业务规则、测试、部署声明和手工定义的同名 MCP server 仍归项目所有，不能被升级覆盖。 +- 遇到炼境分发的模板、约定或 MCP 工具的摩擦，或验证出跨项目可复用的实践时，调用 `report_envoy_return` 回传炼境（只追加信号，不必逐条征得用户同意；Claude 会话结束时也可跑 `/envoy`）；何时回传、字段怎么填见 lian-jing skill「遇到摩擦时回传炼境」一节。 + +### Node/pnpm 工具链 + +见模板同名小节（.nvmrc / packageManager 为版本事实源、mise 最小声明、get_toolchain_status 先查、prepare_toolchain 须用户确认）；措辞以模板为准。 --- @@ -38,7 +61,7 @@ usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标 ### T1 外部契约变更（最高优先级） 其他代码、服务、或 agent 依赖的定义——接口、共享类型、数据结构、配置键名、环境变量名。 -→ 查 `docs/ai-context/project-context.yaml` 找到记录该契约的文档，检查并同步更新。 +→ 查 `docs/ai-context/project-context.yaml`（若存在）找到记录该契约的文档，检查并同步更新。 ### T2 架构边界变更 模块划分、目录结构、依赖方向、包边界调整。 @@ -46,10 +69,10 @@ usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标 ### T3 工具链变更 引入或替换库、框架、构建工具。 -→ 更新 AGENTS.md 技术栈声明；通知炼境重新扫描并更新 `project-context.yaml`。 +→ 更新本文件（AGENTS.md）技术栈声明；通知炼境重新扫描并更新 `project-context.yaml`。 ### T4 常驻上下文过期 -AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 +本文件（AGENTS.md）或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 → 立即更新。这两份文档常驻 agent 上下文，过期危害最大。 ### 不触发检查 @@ -83,9 +106,9 @@ AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 每隔一阵或大改后，对照以下清单： - [ ] AGENTS.md 里的技术栈声明还和代码一致吗？ -- [ ] `project-brief.md` 最近 30 天有没有随架构改动更新？ +- [ ] `docs/ai-context/project-brief.md` 最近 30 天有没有随架构改动更新？ - [ ] 有没有两份文档说同一件事且打架？ -- [ ] `project-context.yaml` 的契约路径还准确吗？ +- [ ] `docs/ai-context/project-context.yaml` 的契约路径还准确吗？ ---