From d1e75d2270ca55ae047df41fe290fd0690a86cfc Mon Sep 17 00:00:00 2001 From: lanrtop Date: Wed, 30 Sep 2026 19:12:03 +0900 Subject: [PATCH] =?UTF-8?q?docs(blueprint):=20=E6=96=B0=E5=BB=BA=20agent-c?= =?UTF-8?q?lient-parity=20=E6=A8=A1=E5=9D=97=EF=BC=8C=E8=AE=B0=E5=BD=95?= =?UTF-8?q?=E4=B8=89=E7=AB=AF=E6=97=A0=E5=A4=B4=E5=9F=BA=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 三端（Claude Code / Codex / DSH 桌面版）同一只读任务的 A–F 矩阵作为基线证据 - 立 P1–P5：统一项目专用地址、Claude skill 投影、稳定 helper 入口、 探针固化、落地兜底；原 V17/V18 迁入 P1/P3 - manifest 项目描述同步为「管家」定位 Co-Authored-By: Claude Opus 5.5 --- .blueprint/manifest.yaml | 22 +++++- .blueprint/modules/agent-client-parity.md | 77 +++++++++++++++++++++ .blueprint/modules/project-dev-variables.md | 16 +---- 3 files changed, 99 insertions(+), 16 deletions(-) create mode 100644 .blueprint/modules/agent-client-parity.md diff --git a/.blueprint/manifest.yaml b/.blueprint/manifest.yaml index c052959..ce7abe4 100644 --- a/.blueprint/manifest.yaml +++ b/.blueprint/manifest.yaml @@ -1,12 +1,12 @@ version: 1 name: 炼境 description: > - Git 多空间开发管理器与项目 Agent 化的本地控制面。以蓝图为神经系统， - 为 Codex、Claude 等可替换客户端 adapter 分发基线、发现状态并采集交付信号； + Agent 开发子项目的管家：agent（Claude、Codex、DSH 等）反复摩擦之处， + 沉淀为跨 agent 可调用的结构化能力（项目身份、环境就绪、验证资源、任务上下文、证据采集）； 项目自身保留业务规则、测试、部署声明与交付决策。炼境本身亦被纳入其中， 形成可自我进化的开发智能闭环。 iteration: 1 -updated: 2026-09-28 +updated: 2026-09-30 agent_button_carrier: tauri @@ -507,6 +507,15 @@ modules: note: "V1–V11 agent_verify 全部通过；V7 于 2026-09-30 以真实 Codex CLI 三会话完成登记→填写→跨会话读取→撤销后读取失败（单次 --approve-for-me，仅登记写调用）。待人终验真实桌面 UI 与日常便利；仅非生产开发用途。运行时落地增量见 docs/tasks/2026-09-30-dev-variables-materialize.md。" position: [3250, 950] + - id: agent-client-parity + name: 三端客户端对等 + area: infra + status: in_progress + progress: 0 + updated: 2026-09-30 + note: "目标：子项目在 Claude Code、Codex、DSH 三端都能继续开发。2026-09-30 无头基线探针：Codex 全绿；Claude 与 DSH 连全局 /mcp、看不到开发变量工具；Claude 缺 lian-jing skill。先统一连接地址，再处理认证与 skill 投影，并把探针固化为可重跑检查。" + position: [3500, 950] + edges: - from: project-resource-broker to: project-dev-variables @@ -838,3 +847,10 @@ edges: - from: agent-access-reliability to: project-resource-broker type: dependency + # 三端对等建立在已完成的客户端能力包与开发变量本体之上。 + - from: agent-client-capability-packs + to: agent-client-parity + type: dependency + - from: project-dev-variables + to: agent-client-parity + type: dependency diff --git a/.blueprint/modules/agent-client-parity.md b/.blueprint/modules/agent-client-parity.md new file mode 100644 index 0000000..f778b9f --- /dev/null +++ b/.blueprint/modules/agent-client-parity.md @@ -0,0 +1,77 @@ +--- +id: agent-client-parity +name: 三端客户端对等 +status: in_progress +progress: 0 +--- + +## 概述 + +子项目在 Claude Code、Codex、DSH（DeepSeek Harness 桌面版）三端都能继续开发：项目状态只存在于 Git 与炼境，客户端是可替换的投影。炼境适配的是**客户端层**（规则文件、skill 位置、MCP 连接、认证、无头模式），不是模型层——在某客户端内切换 DeepSeek 等模型属 `codex-model-switch`，与本模块正交。 + +## 设计原则 + +- **五个接入面**逐一对齐：① 项目规则（AGENTS.md）② 工作流 skill ③ MCP 连接炼境 ④ 敏感取值 ⑤ 交付信号（Git + lefthook + Gitea，已与客户端无关）。 +- **先路由、后认证**：客户端必须连项目专用地址 `/mcp/projects/`；全局 `/mcp` 只作兼容，且暴露跨项目管理工具，不应作为子项目日常入口（最小权限）。 +- **无头模式 = 各客户端的 agent 按钮**：`claude -p`、`codex exec`、`dsh headless`。对等性用同一任务、同一断言在三端无头实测，不靠文档推断。 +- 不写静态 token 进任何配置文件；认证靠各客户端的动态机制或不需认证的落地路径。 + +## 基线证据（2026-09-30，enterprise-system，三端无头同一只读任务） + +| 检查项 | Codex 0.155 | Claude Code 2.1.173 | DSH 桌面版 0.2.0-rc.2 | +| --- | --- | --- | --- | +| A 加载项目规则 | ✅ 摘录 AGENTS.md | ✅ CLAUDE.md 经 `@AGENTS.md` 引用 | ✅ 原生读取 AGENTS.md | +| B lian-jing skill | ✅ | ❌ 看不到（未投影到 `.claude/skills/`） | ✅ 读取 `.agents/skills`，与 Codex 共用 | +| C MCP 工具 | ✅ 32 个，含敏感读取 | ⚠️ 35 个全局工具，无开发变量工具 | ⚠️ 35 个全局工具，无开发变量工具 | +| D get_diagnostics | ✅ | ✅ | ✅ | +| E 列出开发变量 | ✅ | ❌ 工具不存在 | ❌ 工具不存在 | +| F 敏感读取 | ✅ | ❌ 工具不存在 | ❌ 工具不存在 | +| 耗时 | 56 s | 138 s | 25 s | + +三端均未泄露凭据。连接现状：Codex 用项目 `.codex/config.toml`（项目地址 + helper）；Claude 仅在 `~/.claude.json` user scope 注册全局 `/mcp`（SSE）；DSH 在机器级 `~/.dsh/cordis.patch.yml` 注册全局 `/mcp`，配置无法按项目拆分，但支持 `!!js` 求值与每次调用的 `--patch` 叠加层。 + +## 实施前待验证假设（闸门） + +- **H1 DSH**：`!!js` 能否在加载时读取当前目录的 `.lian-jing/context.json` 算出项目地址，并执行 helper 生成认证头。 +- **H2 Claude**：Windows 上 `headersHelper` 的执行方式与调用写法；local scope 条目覆盖 user scope 全局注册。 +- **H3 Claude skill**：项目 `.claude/skills//SKILL.md` 能被无头会话发现。 +- **H4 Codex**：`http_headers_helper` 中 `%LOCALAPPDATA%` 能被 `cmd /C` 展开（源码推断，未实测）。 + +任一假设不成立：回到设计，不退回写静态 token 或本机绝对路径。 + +## 任务拆解 + +### 📋 P1 — 统一连接项目专用地址（Claude + DSH） +- status: todo +- complexity: M +- files: src-tauri/src/mcp_inject.rs, docs/ai-context/agent-button-system.md +- depends: H1, H2 +- acceptance: "agent_verify: [三端无头探针] 在 enterprise 目录 Claude 与 DSH 的 C 项均看到开发变量工具（项目工具集），E 项成功；项目目录外的会话不获得他项目工具。" +- 注：吸收原 project-dev-variables V17（Claude 以 local scope + headersHelper 取值）。 + +### 📋 P2 — Claude skill 投影 +- status: todo +- complexity: S +- files: src-tauri/src/commands/onboarding.rs, src-tauri/resources/onboarding/ +- depends: H3 +- acceptance: "agent_verify: [cargo test onboarding] 接入包同时写 .claude/skills/lian-jing/SKILL.md，内容与 .agents/skills 单一来源一致；[Claude 无头探针] B 项看到 lian-jing。" + +### 📋 P3 — 稳定 helper 入口，项目配置去本机路径 +- status: todo +- complexity: M +- files: src-tauri/src/mcp_inject.rs, src-tauri/src/lib.rs, src-tauri/src/commands/onboarding.rs +- depends: H4 +- acceptance: "agent_verify: [cargo test] 炼境启动写/更新 %LOCALAPPDATA% 下 shim 指向当前 exe；inject 后受跟踪文件不含本机绝对路径或用户名；[Codex 无头探针] F 项经 shim 成功；换构建目录启动后无需重注入仍成功。" +- 注：即原 project-dev-variables V18；Claude headersHelper 与 DSH 共用同一 shim。 + +### 📋 P4 — 三端对等探针固化为炼境能力 +- status: todo +- complexity: M +- files: scripts/ 或 src-tauri/src/commands/（实现时定）, docs/ai-context/agent-button-system.md +- depends: P1, P2, P3 +- acceptance: "agent_verify: [CLI] 一条命令对指定项目依次跑三端无头探针，输出 A–F × 三端矩阵与耗时，断言无凭据泄露；接入包升级后重跑结果可比对。" + +### 📋 P5 — 测试账户落地到被 Git 忽略文件 +- status: todo +- complexity: M×3 +- 见 project-dev-variables V14–V16 与 `docs/tasks/2026-09-30-dev-variables-materialize.md`；落地不返回值、无需认证，是三端都可用的兜底路径。 diff --git a/.blueprint/modules/project-dev-variables.md b/.blueprint/modules/project-dev-variables.md index 80db347..f0c7904 100644 --- a/.blueprint/modules/project-dev-variables.md +++ b/.blueprint/modules/project-dev-variables.md @@ -243,19 +243,9 @@ progress: 91 - shim 位于用户可写目录：同一 Windows 用户进程可替换它——与既有威胁模型一致（不提供同用户隔离），不宣称增强。 - 已接入项目需一次迁移：重新 inject_mcp 后 `.codex/config.toml` 托管块变化，由项目自行提交。 -### 📋 V18 — 稳定 helper 入口，项目配置去本机路径 -- status: todo -- complexity: M -- files: src-tauri/src/mcp_inject.rs, src-tauri/src/lib.rs, src-tauri/src/commands/onboarding.rs -- depends: V13 -- acceptance: "agent_verify: [cargo test] 炼境启动写/更新 shim 指向当前 exe；inject 后 .codex/config.toml 不含任何本机绝对路径或用户名；verify_onboarding 对旧绝对路径 helper 报告可升级。[真实 Codex 会话] Enterprise 经 %LOCALAPPDATA% shim 读取成功；换另一构建目录启动炼境后无需重注入仍成功。" - -### 📋 V17 — Claude 以 local scope + headersHelper 取值 -- status: todo -- complexity: M -- files: src-tauri/src/mcp_inject.rs, docs/ai-context/agent-button-system.md, src-tauri/resources/onboarding/.agents/skills/lian-jing/SKILL.md -- depends: V18 -- acceptance: "agent_verify: [cargo test] 生成的 local scope 条目含 scoped url 与指向 shim 的 headersHelper，且不写仓库文件；[真实 Claude Code 会话 + 合成账户] 在项目目录 read_project_test_account 成功，项目外会话仍连全局且敏感读取被拒。skill 降级指引注明 DSH 不写静态 token、改走落地路径。" +### ➡️ V17、V18 — 已迁至 `agent-client-parity`（2026-09-30） +- V18 → P3（稳定 helper 入口）；V17 → P1（Claude 连项目专用地址 + headersHelper）。 +- 为什么迁移：三端无头基线探针表明 Claude 与 DSH 的首要缺口是连全局 `/mcp`、看不到开发变量工具（路由问题），而非认证本身；这属于跨客户端对等问题，单独建模块统一推进，本模块不再重复描述。 ### 调研来源