bbdc98b93f
All checks were successful
Push & PR Check / check (push) Successful in 1m14s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
92 lines
7.4 KiB
Markdown
92 lines
7.4 KiB
Markdown
---
|
||
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/<project_id>`；全局 `/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/<name>/SKILL.md` 能被无头会话发现。
|
||
- **H4 Codex**：`http_headers_helper` 中 `%LOCALAPPDATA%` 能被 `cmd /C` 展开（源码推断，未实测）。
|
||
|
||
任一假设不成立：回到设计，不退回写静态 token 或本机绝对路径。
|
||
|
||
### 假设实测结果（2026-09-30，Workflow 并行实验 + 独立对抗复核）
|
||
|
||
- **H1 ✅ 成立（复核未推翻）**：DSH `--patch` 叠加层即可，不改 `~/.dsh`。`!!js` 在主进程加载时求值，`require` 不可用但 `process.getBuiltinModule('fs'|'path'|'crypto'|'child_process')` 可用；`process.cwd()` = 启动目录，向上查找 `.lian-jing/context.json` 算项目路由（子目录启动亦可）；`execFileSync` 直接执行 helper（不经 shell）生成 Authorization；`disabled: !!js` 在项目外不挂载且不求值 config。helper 失败时安全降级（只写一行 stderr、读取 403、会话不崩）。**限制**：桌面 GUI 模式下 cwd 不随工作区切换，本方案目前只证实适用于在项目目录启动的 headless/CLI。
|
||
- **H3 ✅ 成立（复核未推翻）**：Claude 发现 `<项目>/.claude/skills/<name>/SKILL.md`（向上查找到 git 根为止，git 根以上不加载）；**不读 `.agents/skills`**，所以必须投影一份到 `.claude/skills`。`-p` 模式下目录 trust 不影响 skill 加载。
|
||
- **H4 ⚠️ 未证实（复核判定证据不足）**：只在 cmd 层模拟证实 `%VAR%` 会展开，但模拟用了 `windowsVerbatimArguments:true`，恰好预设了"Codex 原样传参"这一待证前提；Codex 端到端未跑成。
|
||
- **H2 ❌ 无结果**：实验 agent 连续 6 次卡死。H3 实验发现在 Claude 会话里嵌套 `claude -p` 须先去掉父会话注入的 `CLAUDECODE`、`CLAUDE_CODE_*` 环境变量，疑为卡死原因。
|
||
|
||
### 实验附带发现
|
||
|
||
- **服务端缺陷**：`/mcp/projects/<任意字符串>` 都返回完整 32 个项目工具，不校验项目是否存在；应对未知 project_id 明确拒绝。
|
||
- **零凭据验证法**（后续实验与 P4 探针采用）：认证链路用 `read_project_test_account(name="LJ_PROBE_NONEXISTENT")` 判定——认证通过返回"开发需求未登记"，失败返回 403，凭据不进任何会话；客户端 helper 机制用"哑 helper（写运行标记 + 输出假请求头）+ 本地 HTTP 记录器"判定，全程不碰真 token。
|
||
- 模型自报的工具数量不可靠（同一路由报出 27～38 个），计数以 `curl tools/list` 真值为准（项目路由 32、全局 35）。
|
||
- 在 Claude 会话中嵌套无头 Claude、在 Git Bash 中传 `/斜杠命令` 需设 `MSYS_NO_PATHCONV=1`，否则提示词被改写成 Windows 路径导致误判。
|
||
|
||
## 任务拆解
|
||
|
||
### 📋 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`；落地不返回值、无需认证，是三端都可用的兜底路径。
|