f21345bf1a
DSH 桌面版只有一个 Host 进程、启动目录固定，托管块的 !!js 只在启动时求值，拿不到会话信息； web/acp 同样一个进程服务多个工作区。改由炼境分发一个会话级插件：会话创建（agent/created）时 按会话工作目录匹配炼境登记的项目白名单，命中才在该会话作用域挂连项目专用地址的 mcp-client， 同名工具覆盖全局 lian-jing，其他会话不受影响。 - 插件随二进制打包（resources/dsh/lianjing-session-mcp.v1.mjs），刷新 DSH 托管块时写到 %USERPROFILE%\.lian-jing\dsh\；文件名带版本号（Node 按 URL 缓存 ESM） - 托管块在全局行之后追加插件条目（port、shim、roots 以 JSON 写入）；插件文件写失败时只保留全局行 - 插件防御：headless 交给全局行；特性探测不符即降级为全局；取认证 ≤3 秒、整次挂载 ≤5 秒； 所有回调吞掉异常（Host 对未处理异常会崩溃，agent/created 串行失败会让会话创建失败） - 块外手写的 lianjing-session-mcp 条目同样拒绝覆盖 验证：cargo test 246 passed；vitest 插件用例 6 条通过、typecheck 通过；端到端在 DSH 0.2.0-rc.2 与 0.1.5-rc.2 上，项目会话经真实稳定入口带认证连上项目地址，其他会话无请求。 Feature-Confirmed: true Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
43 lines
6.4 KiB
YAML
43 lines
6.4 KiB
YAML
# 项目契约路径映射
|
||
# 由炼境根据技术栈扫描生成，技术栈变更后重新运行接入包生成
|
||
# 供 AGENTS.md 元规则 T1 查询：「哪个文件是这个项目的外部契约？」
|
||
|
||
contracts:
|
||
- label: API 接口（Axum）
|
||
paths:
|
||
- "src-tauri/src/mcp_server.rs"
|
||
doc: "MCP 仅监听 127.0.0.1；新项目使用 /mcp/projects/<project_id> scoped route，连接 scope 拒绝跨项目参数和全局管理写工具。scoped route 只服务已登记项目，未知 project_id 返回 404（数据库不可用同样拒绝）。各客户端经 %USERPROFILE%/.lian-jing/bin/lianjing-mcp-header.cmd 稳定入口取认证头（炼境每次启动指向当前 exe；入口不放 AppData，因炼境若在 MSIX 应用的进程树里启动（如由 Claude 桌面版里的 agent 启动），AppData 下新建的目录会被重定向到该应用的私有目录，其他客户端看不到，用户目录根不受此影响；旧 %LOCALAPPDATA% 入口在迁移期同步保留，verify_onboarding 报 Legacy 引导重注入）：Codex 写项目 .codex/config.toml，Claude 写 local 条目（优先于 user 级全局；一律经 claude CLI、cwd=项目目录写入，项目键推导、文件锁与配置路径交给 Claude 自身，不直接编辑 ~/.claude.json；项目根或其祖先键下已有一致的托管条目则不起 CLI，否则以项目目录下 claude mcp get 的实际生效条目为准：本项目托管条目刷新/移除，他项目托管条目与手写条目不碰，无法确认现状一律不写；项目目录已不存在时只记录残留不写入），DSH 写 ~/.dsh/cordis.patch.yml 托管块（内嵌炼境登记的「项目根目录→project_id」白名单，仅 headless profile 由 !!js 从启动目录向上精确匹配根目录才选项目地址并取认证，web/acp/tui/桌面版一个进程可服务多个工作区，全局行一律走全局以防跨项目带认证；这些模式由同一托管块引用的会话级插件（随炼境打包，写到 %USERPROFILE%/.lian-jing/dsh/，文件名带版本号）在每个会话创建时按会话工作目录匹配白名单，命中才在该会话作用域挂项目地址并经稳定入口取认证，其他会话不受影响；任意目录里的 context.json 不作授权依据；未命中回退全局；项目增删与端口变更时重写）。Claude local 条目与 DSH 块只替换炼境托管的条目，手写同名配置不覆盖；移除项目时一并清理。旧 /mcp 只作兼容迁移。read_project_dev_variable 与 read_project_test_account 是两种有界开发值读取：仅 scoped 路由、匹配项目的本机 bearer 认证后单项读取；认证失败在 dispatch 前拒绝。路由变更需同步 Agent 按钮体系文档。"
|
||
|
||
- label: MCP 工具接口
|
||
paths:
|
||
- "src-tauri/src/mcp_tools.rs"
|
||
- "src-tauri/src/commands/delivery_status.rs"
|
||
- "src-tauri/src/commands/toolchain.rs"
|
||
- "src-tauri/src/commands/cicd.rs"
|
||
- "src-tauri/src/commands/gitea.rs"
|
||
- "src-tauri/src/commands/dev_variables.rs"
|
||
doc: "工具 schema、dispatch 与调用说明必须同步；get_project_resource_status 为项目 scoped 只读状态，仅返回 Gitea PR/webhook 的状态与来源，不返回凭证、引用、URL；旧凭证未迁移时返回 pending_migration，不提前宣称 configured。MCP 不提供 reveal_api_key、get_secret 或任意 HTTP/SSH/SQL/部署代理。明文例外只限 read_project_dev_variable 的单项标量与 read_project_test_account 的单张非生产测试账户；均须匹配 scoped 项目及本机认证。register_project_test_account 只写非秘密需求元数据；列表不返回值，禁止批量导出。production delivery profile 由项目维护，炼境只读 Gitea 部署 context 与公开版本探针，双证据相符才能报告 deployed。外部来源不可用时返回显式降级状态，不得伪造成功。verify_onboarding 必须同时返回静态接入 checks 与 configured/reachable/handshake/tools_ready/reload_required 运行态证据，配置存在不得替代运行可用。CI workflow 使用 plan_cicd_workflow 只读预览，用户确认相同 digest 后方可 apply_cicd_workflow 写入；该接口不接收凭证值且不触发 CI 或部署。"
|
||
|
||
- label: 被管理项目身份上下文
|
||
paths:
|
||
- "src-tauri/src/mcp_inject.rs"
|
||
- "src-tauri/src/commands/onboarding.rs"
|
||
- ".lian-jing/context.json"
|
||
- ".lian-jing/capability-packs.json"
|
||
- ".claude/liangjing.json"
|
||
doc: "`.lian-jing/context.json` 是 project_id 的工具无关单一事实来源；`.claude/liangjing.json` 仅为兼容投影；`.lian-jing/capability-packs.json` 是炼境分发基线的版本描述。lian-jing skill 以同一模板双投影：`.agents/skills/lian-jing/`（Codex、DSH 读取）与 `.claude/skills/lian-jing/`（Claude Code 不读 .agents/skills），两份内容必须一致。context.json 可选字段 mcp_scope=global 声明控制面项目（如炼境自身）：Claude 不写 local 条目、DSH 不入白名单，保留全局地址与跨项目工具。迁移必须保留未知字段；验证必须返回显式状态与 upgrade_hint；升级仅覆盖炼境托管文件，绝不覆盖项目定制或手工 MCP 配置，且不得以客户端全局配置或项目 UI 身份替代项目根目录上下文。"
|
||
|
||
- label: Tauri command 接口（前后端契约）
|
||
paths:
|
||
- "src-tauri/src/commands/**/*.rs"
|
||
- "src/lib/commands.ts"
|
||
doc: "新增 command 时前后端必须同步。Gitea/API Key 普通 DTO 不含原始凭证；API Key 仅本机 UI 显式 reveal，get_project_resource_status 仅返回非秘密状态；项目开发需求列表 DTO 仅含名称、类型、目标系统、环境、用途、configured 与时间。本机 UI 对 test_account 一次提交账号/密码到同一受保护引用，允许修改或撤销；列表常态不含值，仅人显式点「修改」时经 reveal_project_dev_variable 取回原值（密码默认遮罩），该 command 不进 MCP；旧 scalar 保持兼容。旧 SQLite 明文列按 write→verify→事务切换引用并清除的顺序兼容迁移，失败需可恢复，不能降级明文。Agent readiness 必须保留 configured/reachable/handshake/tools_ready/reload_required 分层；Windows autostart 默认关闭，只允许正式安装版，debug/target 构建必须拒绝启用。"
|
||
|
||
architecture_docs:
|
||
- "AGENTS.md"
|
||
- "docs/ai-context/agent-button-system.md"
|
||
|
||
agent_docs:
|
||
- "AGENTS.md"
|
||
- "docs/ai-context/project-brief.md"
|