docs(blueprint/agent-client-parity): 定位为 agent 客户端兼容层，立卡 P6/P7

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.blueprint/modules/agent-client-parity.md

@@ -9,8 +9,30 @@ progress: 0
 
 子项目在 Claude Code、Codex、DSH（DeepSeek Harness 桌面版）三端都能继续开发：项目状态只存在于 Git 与炼境，客户端是可替换的投影。炼境适配的是**客户端层**（规则文件、skill 位置、MCP 连接、认证、无头模式），不是模型层——在某客户端内切换 DeepSeek 等模型属 `codex-model-switch`，与本模块正交。
 
+## 定位：agent 客户端兼容层（类比 Web 框架之于浏览器）
+
+炼境对 agent 客户端的角色，如同 Web 框架对浏览器：内容按开放标准写一次（AGENTS.md、MCP、SKILL.md），各客户端私有机制的差异由炼境的适配层吸收，并持续实测"这些机制此刻是否仍有效"。
+
+| Web 世界 | 炼境 |
+| --- | --- |
+| 浏览器 | agent 客户端（Claude Code、Codex、DSH） |
+| Web 标准 | AGENTS.md、MCP、SKILL.md 格式 |
+| 浏览器私有实现差异 | skill 目录、MCP 配置位置、helper 执行 shell、DSH `!!js` 等 |
+| 框架兼容层 / polyfill | 炼境各客户端适配器（skill 双投影、统一 shim、各端注入） |
+| Can I Use 兼容性表 | 三端对等矩阵（A–F） |
+| 跨浏览器自动化测试 | 三端无头探针（P4） |
+
+skill 只是五个接入面之一，兼容层覆盖全部五面。
+
+类比不成立处（也是本模块的特殊难点）：agent 客户端迭代远快于浏览器且机制常无文档，所以更依赖持续实测而非读规范；"浏览器"本身是智能的，部分兼容可用 skill 里的降级说明解决，但可靠性低于代码适配，只作兜底。
+
 ## 设计原则
 
+- **标准优先，私有机制只进适配层**：项目内容只写标准形态，客户端差异不得渗入项目内容。
+- **检测行为而非嗅探版本**：用无头实测判定机制是否有效，不凭版本号或文档推断（H1–H4 即此法）。
+- **兼容性表必须可自动重跑**：客户端几乎每周更新，人工结论很快过期。
+- **polyfill 可退役**：客户端原生支持标准后撤掉对应适配（例如 Claude 若开始读 `.agents/skills`，即撤 `.claude/skills` 投影）——对应 AGENTS.md「管家准入与退出」的退出规则。
+- **渐进增强**：核心能力在最弱客户端也可用（落地文件兜底），高级能力只在支持的客户端启用（明文读取有界例外）。
 - **五个接入面**逐一对齐：① 项目规则（AGENTS.md）② 工作流 skill ③ MCP 连接炼境 ④ 敏感取值 ⑤ 交付信号（Git + lefthook + Gitea，已与客户端无关）。
 - **先路由、后认证**：客户端必须连项目专用地址 `/mcp/projects/<project_id>`；全局 `/mcp` 只作兼容，且暴露跨项目管理工具，不应作为子项目日常入口（最小权限）。
 - **无头模式 = 各客户端的 agent 按钮**：`claude -p`、`codex exec`、`dsh headless`。对等性用同一任务、同一断言在三端无头实测，不靠文档推断。
@@ -74,8 +96,8 @@ progress: 0
 - acceptance: "agent_verify: [cargo test onboarding] 接入包同时写 .claude/skills/lian-jing/SKILL.md，内容与 .agents/skills 单一来源一致；[Claude 无头探针] B 项看到 lian-jing。"
 - verification: "2026-10-01：同一模板双投影到 .agents/skills 与 .claude/skills；verify_onboarding 新增「Claude 炼境技能已分发」（检查链 12 项）；base-onboarding 升至 1.6.0，supported_clients 增 dsh；skill 降级步骤改为三端通用并提示「无开发变量工具即连的是全局地址」。新增测试 skill_is_projected_to_codex_and_claude_from_one_source；cargo test --locked 229 passed / 5 ignored。Enterprise 分发后 verify_onboarding 14/14，两份 skill 逐字节一致；Claude 无头会话 init 事件 skills 与 slash_commands 均含 lian-jing（基线探针时为不存在）。"
 
-### 📋 P3 — 稳定 helper 入口，项目配置去本机路径
+### 🔵 P3 — 稳定 helper 入口，项目配置去本机路径
-- status: todo
+- status: in_progress
 - complexity: M
 - files: src-tauri/src/mcp_inject.rs, src-tauri/src/lib.rs, src-tauri/src/commands/onboarding.rs
 - depends: H4
@@ -93,3 +115,20 @@ progress: 0
 - status: todo
 - complexity: M×3
 - 见 project-dev-variables V14–V16 与 `docs/tasks/2026-09-30-dev-variables-materialize.md`；落地不返回值、无需认证，是三端都可用的兜底路径。
+
+### 📋 P6 — 技能能力包：通用 skill 单一来源、三端投影
+- status: todo
+- complexity: M
+- files: src-tauri/src/commands/onboarding.rs, src-tauri/resources/（实现时定）
+- depends: P2
+- acceptance: "agent_verify: [cargo test] 通用 skill（architect、splitter、code-review 等）由一处模板按版本投影到各客户端目录（Claude user/project skills、Codex/DSH 的 .agents/skills）；[三端无头探针] B 项三端看到同一组 skill 且内容一致。"
+- 为什么：2026-09-30 探针显示同一批 skill 在三端各维护一份（Claude `~/.claude/skills`、Codex `source-command-*` 副本、DSH 手写 `.dsh/skills`），是实际的重复与漂移源。先把 skill 中的确定性步骤下沉为炼境 MCP 工具，让 skill 变薄，再做投影。
+- 不做：炼境不执行推理类 skill（无模型、会丢失会话代码上下文、越过「不替 agent 思考」边界）；不以运行时拉取 skill 正文作为主路径（炼境离线即失效、脱离 Git 分支）。
+
+### 📋 P7 — MCP 服务器说明的三端支持验证
+- status: todo
+- complexity: S
+- files: src-tauri/src/mcp_server.rs, docs/ai-context/agent-button-system.md
+- depends: P1
+- acceptance: "agent_verify: [三端无头探针] 在 initialize 下发唯一标记的 instructions，判定三端是否把它带入模型上下文。全部支持则把引导提示迁到服务器说明，本地 skill 只保留 MCP 不可达时的排障步骤；部分支持则如实记录、保留 skill 引导。"
+- 为什么：Claude 已实证会把 lian-jing 的服务器说明带入上下文；若三端皆支持，引导提示可由炼境集中维护。