c9b951dd30
P10 审查核实的三处缺陷： - 块外比较原先逐行 trim_end 并丢弃全部空行，项目在块外删空行（Markdown 两段 并成一段）或加行尾空格（硬换行）时判为无改动，升级后不预警却产生混合文件。 改为 CRLF 统一为 LF、托管块原位换成占位符，只把文末占位符连同其前空白按 trim_end 归一（正好抵消炼境追加托管块时的 trim_end + 空行）；文中托管块两侧 的空行与行尾空格照常比较——炼境只原位替换文中的块，不碰两侧。 - dispatch_templates_with_mixed_file_check 先 `then()?` 后标注：buff 先同步蓝图 规则改写了 AGENTS.md/CLAUDE.md、再写 DB 失败时，预警随 Err 一起丢失。改为 无论成败先标注，失败时把混合文件名并入错误信息；无混合文件则原样返回错误。 - 「块外有未提交改动但托管块已是最新、本次不改写」组合没有测试，删掉 annotate 的改写判断测试照样全绿。主场景测试补情形三。 测试：新增 outside_managed_whitespace_edits_count_as_changes、 mixed_file_warning_survives_failure_after_write，主场景补情形三；纯函数测试的 期望值随归一化收窄更新（"# 标题\n项目内容" → "# 标题\n\n项目内容"，保留「之前 追加的块尚未提交、只多出块前空行」不算改动的断言）。变异自检：三处修复逐一回退， 对应测试各自失败，已还原。cargo test --locked：lib 272 passed / 5 ignored，0 failed； pnpm typecheck 通过。契约文档 project-context.yaml 与蓝图 P10 卡同步。 Rules-Applied: R07,R12 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
44 lines
8.0 KiB
YAML
44 lines
8.0 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"
|
||
- "src-tauri/src/envoy.rs"
|
||
doc: "工具 schema、dispatch 与调用说明必须同步；使者回传三件套：report_envoy_return 为项目级（三端在 scoped 地址可用；kind/confidence/suggestion/client 为枚举，scope 为 this_project|all_projects|project_type:<类型> 格式校验，content 压成单行且限长；无凭据字段，服务端对私钥头与常见令牌前缀做兜底拒绝，其余靠描述约束——内容会双写进子项目 .blueprint/notes-archive.jsonl 随项目进 Git；同项目同内容未处置时幂等返回原编号），resolve_envoy_return 与 list_envoy_returns 仅控制面（全局地址），子项目 agent 只回传不处置；list 默认只列未处置并报告已处置计数，include_resolved=true 附列回执，超出展示上限须明说不得静默截断，回传格式首行前缀【炼境使者回传】保持兼容（B4 沉默项目统计按前缀匹配）；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 身份替代项目根目录上下文。apply_onboarding_pack 的模板结果 TemplateResult 可带 warning（混合文件预警）：写入前 AGENTS.md、docs/ai-context/git-workflow.md 或 CLAUDE.md 在 git 中已有托管块（ONBOARDING_MANAGED / BLUEPRINT_MANAGED）之外的未提交改动（未跟踪文件带块外内容也算；比较只忽略 CRLF/LF 与文末托管块连同其前空白——即炼境追加托管块带来的差异，块外空行增删与行尾空格均算改动），且本次确实改写了该文件时给出；只提示不阻断、块外内容不动，非 git 仓库或 git 不可用时静默。CLAUDE.md 只由蓝图规则同步改写，仅在预警时补一条结果。模板分发之后的步骤（lefthook 激活、buff）报错时，已改写的混合文件名并入错误信息返回。"
|
||
|
||
- 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"
|