docs(blueprint/dev-variables): V17+V18 合并设计——稳定 helper 入口与各客户端认证
All checks were successful
Push & PR Check / check (push) Successful in 1m4s
All checks were successful
Push & PR Check / check (push) Successful in 1m4s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
lanrtop
parent
9aa70eefd9
commit
487ea86806
@ -219,18 +219,46 @@ progress: 91
|
|||||||
- 设计与卡片草案：`docs/tasks/2026-09-30-dev-variables-materialize.md`（落地本体 / MCP 投影 / Enterprise worktree 试点）；开工前需用户确认设计。
|
- 设计与卡片草案：`docs/tasks/2026-09-30-dev-variables-materialize.md`（落地本体 / MCP 投影 / Enterprise worktree 试点）；开工前需用户确认设计。
|
||||||
- 为什么：agent 读到明文后仍需自行 export 或写 `.env.agent` 才能喂给 `agent-auth.mjs`，明文过一手会话且每个新 worktree 重复。
|
- 为什么：agent 读到明文后仍需自行 export 或写 `.env.agent` 才能喂给 `agent-auth.mjs`，明文过一手会话且每个新 worktree 重复。
|
||||||
|
|
||||||
### 📋 V17 — 非 Codex 客户端的项目认证取值
|
## 设计决策：各客户端稳定携带项目认证（V17+V18 合并，2026-09-30，待用户确认）
|
||||||
- status: todo
|
|
||||||
- complexity: M
|
|
||||||
- files: src-tauri/src/mcp_inject.rs, docs/ai-context/agent-button-system.md
|
|
||||||
- depends: V13
|
|
||||||
- acceptance: "agent_verify: [真实 Claude Code 会话 + 合成账户] 经客户端动态请求头机制携带项目 bearer → read_project_test_account 成功；无认证 → 403。先调研 Claude Code / DeepSeek harness 是否支持动态请求头；不支持则如实记录并在 skill 中保持降级指引，不以静态 token 写入配置绕过。"
|
|
||||||
- 为什么：用户同时使用 Claude、Codex、DeepSeek；当前仅 Codex 经 helper 验证可读，是跨 agent 准入的最大缺口。
|
|
||||||
|
|
||||||
### 📋 V18 — helper 本机路径移出受 Git 跟踪的项目配置
|
### 调研事实
|
||||||
|
|
||||||
|
| 客户端 | 动态请求头 | 不进仓库的按项目配置 | 现状 |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| Codex 0.155 | `http_headers_helper`：经 `%COMSPEC% /Q /D /C` 执行，env_clear 后只留白名单（含 LOCALAPPDATA）；10s 超时；连接时调用，401/403 刷新一次 | 无：user config 的 `[projects]` 只有 trust_level；项目 `.codex/config.toml` 仅 trusted 项目加载，与 user 层递归深合并 | 受跟踪项目文件写入本机 exe 绝对路径 |
|
||||||
|
| Claude Code | `headersHelper`：stdout JSON；每次连接调用，401/403 重试；10s | local scope（`~/.claude.json` 按项目条目），优先级 local > project > user，整条替换不合并 | 仅 user scope 注册全局 `/mcp`（SSE），敏感读取被拒 |
|
||||||
|
| DSH 0.1.5-rc.2 | 仅静态 `headers` | 仅机器级 `~/.dsh/cordis.patch.yml`，无按项目 | 连全局 `/mcp`，敏感读取被拒 |
|
||||||
|
|
||||||
|
### 方案
|
||||||
|
|
||||||
|
1. **稳定 helper 入口（解 V18 根因）**：炼境每次启动（debug 或安装版）重写 `%LOCALAPPDATA%\lian-jing\bin\lianjing-mcp-header.cmd` 指向当前 exe。Codex 项目配置改为 `http_headers_helper = '"%LOCALAPPDATA%\lian-jing\bin\lianjing-mcp-header.cmd" <digest>'`——digest = sha256(project_id) 非秘密，整行在任何机器、任何构建下相同，可安全提交；换构建无需逐项目重注入。
|
||||||
|
2. **Claude（V17 主体）**：inject_mcp 在项目目录以 local scope 写入 `lian-jing`（scoped url + headersHelper 指向同一 shim；local 条目不进仓库，可用绝对路径）；保留 user scope 全局注册作兜底。
|
||||||
|
3. **DSH：不写静态 token**。静态 header 意味着 bearer 明文落在用户目录配置文件，且 DSH 配置无法按项目拆分；DSH 取值改走 V14–V16 落地路径（写入被忽略文件、不返回值、无需认证），待 dsh-mcp-client 支持动态 header 再评估。
|
||||||
|
4. **推论：V14–V16 是唯一全客户端通用的路径**（落地不返回值，无需认证）；读取明文的有界例外只服务支持动态 header 的客户端。
|
||||||
|
|
||||||
|
### 风险与闸门
|
||||||
|
|
||||||
|
- `%LOCALAPPDATA%` 在 Codex helper 中可展开属源码推断（白名单含该变量），实施首步须真实 Codex 会话实测；不成立则回到设计，不退回写绝对路径。
|
||||||
|
- Claude `headersHelper` 在 Windows 的执行 shell（cmd 或 Git Bash）文档未写明，须实测 shim 调用写法。
|
||||||
|
- shim 位于用户可写目录：同一 Windows 用户进程可替换它——与既有威胁模型一致（不提供同用户隔离），不宣称增强。
|
||||||
|
- 已接入项目需一次迁移：重新 inject_mcp 后 `.codex/config.toml` 托管块变化，由项目自行提交。
|
||||||
|
|
||||||
|
### 📋 V18 — 稳定 helper 入口，项目配置去本机路径
|
||||||
- status: todo
|
- status: todo
|
||||||
- complexity: M
|
- complexity: M
|
||||||
- files: src-tauri/src/mcp_inject.rs, src-tauri/src/commands/onboarding.rs
|
- files: src-tauri/src/mcp_inject.rs, src-tauri/src/lib.rs, src-tauri/src/commands/onboarding.rs
|
||||||
- depends: V13
|
- depends: V13
|
||||||
- acceptance: "agent_verify: [cargo test] 注入后项目受跟踪文件不含本机绝对路径；炼境从 debug 换到安装版后无需逐项目重注入即可取值。先设计：候选为稳定 helper 入口（如用户级 shim）或客户端用户级配置，需验证 Codex 项目级配置与用户级配置的合并语义。"
|
- acceptance: "agent_verify: [cargo test] 炼境启动写/更新 shim 指向当前 exe；inject 后 .codex/config.toml 不含任何本机绝对路径或用户名；verify_onboarding 对旧绝对路径 helper 报告可升级。[真实 Codex 会话] Enterprise 经 %LOCALAPPDATA% shim 读取成功；换另一构建目录启动炼境后无需重注入仍成功。"
|
||||||
- 为什么：2026-09-30 实测 Enterprise `.codex/config.toml` 受 Git 跟踪，注入写入 `E:\...\target\debug\dev-manager-tauri.exe` 绝对路径——换构建即失效、换机器即错，且会被提交进业务仓库。
|
|
||||||
|
### 📋 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、改走落地路径。"
|
||||||
|
|
||||||
|
### 调研来源
|
||||||
|
|
||||||
|
- Claude Code：code.claude.com/docs/en/mcp（Dynamic headers、Environment variable expansion、installation scopes、Trust a folder before headersHelper runs）
|
||||||
|
- Codex：learn.chatgpt.com/docs/extend/mcp、config-basic、config-reference；源码 openai/codex tag rust-v0.155.0-alpha.9 的 rmcp-client/src/http_headers.rs、config/src/merge.rs、config/src/config_toml.rs、codex-mcp/src/runtime.rs、cli/src/mcp_cmd.rs
|
||||||
|
- DSH：本机 dsh-mcp-client@0.1.5-rc.2 类型定义（`headers: Record<string,string>`）与 ~/.dsh/cordis.patch.yml
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user