1e3989d0d7
Enterprise 2026-10-03 实测：为避开主工作区里其他会话的在制品，在独立 worktree
分支上开 PR 交付时，get_delivery_status 只读主工作区当前分支，返回「当前分支没有
开放 PR」、CI 停在主工作区 HEAD，传 pr_number 也被忽略，只能用 git ls-remote 与
get_ci_status(commit_sha) 兜底。
- MCP schema 新增可选 pr_number（优先）与 branch；都不给时保持原行为
- pr_number：GET /pulls/{n} 取 head 分支与 head SHA，CI 与 review 均绑定该 PR；
PR 不存在（404）返回 not_found，与 Gitea 不可达（unavailable）区分；
同时传 branch 且与 PR head 分支不一致时以 pr_number 为准并在 detail 提示
- branch：匹配该分支的开放 PR 并以其 head SHA 查 CI；无开放 PR 时取 Gitea 上
该分支 head SHA；远端分支不存在时 CI 为 unknown
- 顶层新增 target（mode/pr_number/branch/head_sha/source/detail），
pull_request.data 增 head_sha；git 字段仍反映主工作区，既有字段兼容
- 取值校验在能力本体 DeliveryQuery 单点实现，MCP 只解析 JSON 类型；显式给出的
非法值直接报错，不静默回退主工作区
- Gitea 读取拆为本地/PR/分支三种目标，凭证存储注入以便合成 Gitea 测试；
merge_pull_request 门禁代码未改
- lian-jing skill 第 6 条改为 get_delivery_status(project_id, pr_number)，
base-onboarding 1.8.0→1.9.0（BASE_ONBOARDING_PACK_VERSION、模板
capability-packs.json、TEMPLATE_FINGERPRINTS）；Codex 插件 skill 同步
- 契约说明同步 docs/ai-context/project-context.yaml；蓝图 P3-F 标 ✅
Feature-Confirmed: true
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
56 lines
7.2 KiB
Markdown
56 lines
7.2 KiB
Markdown
---
|
||
name: lian-jing
|
||
description: 读取炼境项目健康状态，并使用炼境 MCP 的项目管理、Gitea 与交付能力；遇到炼境模板、约定或工具的摩擦时回传炼境。
|
||
---
|
||
|
||
# 炼境项目技能
|
||
|
||
开始项目工作时，先读取根 `AGENTS.md` 与 `.lian-jing/context.json` 取得 `project_id`。`.claude/liangjing.json` 仅为旧项目的 Claude 兼容投影，不能作为长期身份来源。
|
||
|
||
如果当前客户端已发现 `lian-jing` MCP，所有调用都遵守两条通用边界（与炼境 MCP 服务器说明一致）：
|
||
|
||
- 只读查询、登记不含秘密的开发需求元数据（`register_project_test_account`、`register_project_dev_variable`）与回传炼境（`report_envoy_return`）可直接调用；其他写操作仅在用户明确确认目标与影响后调用，下文安装工具链、合并 PR、生成 CI workflow 是它的具体场景。
|
||
- 状态 `unavailable` / `unknown` 不得当作成功：如实报告实际状态，不据此宣称完成。
|
||
|
||
具体用法：
|
||
|
||
1. scoped MCP 连接已由 URL 绑定当前 `project_id`，项目级调用可省略 `project_id`；若 server initialize 明确报告 legacy，迁移前才显式传入 canonical `project_id`，绝不传其他项目 ID。
|
||
2. 优先调用 `get_diagnostics`，将其作为当前项目健康状态的事实来源。
|
||
3. 在 Node/pnpm 项目运行包管理命令前调用 `get_toolchain_status(project_id)`；`ready_managed` 时通过 `mise exec -- pnpm ...` 执行，其他状态先报告实际版本与 executable 证据。
|
||
4. 只有用户明确确认本次下载安装后，才可调用 `prepare_toolchain(project_id, confirmed=true)`；不得为适配客户端 bundled runtime 而修改项目版本或 lockfile。
|
||
5. 交付、Gitea、CI、蓝图等平台状态优先通过 MCP 查询，不凭静态文档猜测。
|
||
6. 合并 PR 前调用 `get_delivery_status(project_id, pr_number)`，按 PR 编号读取：head 分支与 head SHA 以 Gitea 为准，不受主工作区当前分支影响，在独立 worktree 分支上交付同样适用（不传 `pr_number` 时只看主工作区当前分支）。向用户展示 PR 编号、完整 head SHA、CI 与 review。只有当前用户明确确认该 PR 与 SHA 后，才调用 `merge_pull_request(project_id, pr_number, expected_head_sha, confirmed=true)`；合并后再次读取交付状态。不得自行推断确认。
|
||
7. 生成 CI workflow 时先调用 `plan_cicd_workflow(project_id, workflow_type)`，向用户展示目标文件、变更类型、`content_digest`、工具链来源与所需 secret 名称；只有用户明确确认这份摘要后，才以同一 digest 调用 `apply_cicd_workflow(..., confirmed=true)`。该流程只写项目 workflow，不配置 secret、不触发 CI 或部署；不得通过 MCP 传服务器地址、命令、路径或 secret 值，部署类配置先由用户在炼境 UI 保存。
|
||
8. 需要测试账号或开发变量（登录自验、沙箱 key 等）时，先调用 `list_project_dev_variables` 查找：已配置则用 `read_project_test_account` / `read_project_dev_variable` 单项读取；没有则先登记需求——测试账号用 `register_project_test_account` 登记名称、目标系统、非生产环境与用途，开发变量用 `register_project_dev_variable` 登记名称与用途——再请用户在炼境项目 UI「开发变量」中填写。不得在对话中向用户索要明文密码，不得登记生产账号，不得把读到的值写入受 Git 跟踪的文件。读取因缺少项目认证被拒时，如实报告并改用项目原有配置方式，不得绕过认证。若 lian-jing 工具中根本没有 `list_project_dev_variables`，说明当前客户端连的是全局地址 `/mcp` 而非本项目地址，按下方 `configured` 一步处理。
|
||
9. 遇到体系级摩擦时，按下方「遇到摩擦时回传炼境」调用 `report_envoy_return`。
|
||
|
||
## 遇到摩擦时回传炼境
|
||
|
||
炼境根据各项目回传的摩擦改进分发给所有项目的模板、约定与工具。Claude Code、Codex、DSH（DeepSeek Harness）都用同一个入口：`report_envoy_return`。回传只追加一条信号，不改任何代码或配置，所以不必逐条征得用户同意；回传后在给用户的总结里列出编号即可。
|
||
|
||
以下情况直接回传：
|
||
|
||
- 炼境分发的东西出错或碍事：AGENTS.md 托管块、本技能、`/envoy`、lefthook、CONVENTIONS、MCP 工具的行为或返回。即使只在本项目复现也要回传，`scope` 填 `this_project`
|
||
- 用户说「回传」「告诉炼境」「记给炼境」
|
||
|
||
以下情况先过硬门槛：有经验的工程师会不会事先想到这一点？会，或者只在本项目的特定组合下才成立，就不回传，留在本项目处理。
|
||
|
||
- 某种做法有具体代价或验证结果，并且换个项目也成立
|
||
- 会影响多个项目的体系改进假设（即使还没验证）
|
||
|
||
回传方法：
|
||
|
||
1. 每条洞察单独调用一次 `report_envoy_return`：`kind`（template_bug / validated_practice / workflow_hypothesis）、`confidence`、`scope`（this_project / all_projects / project_type:<类型>，按复现范围填）、`content`（一句话写清现象和证据）、`suggestion`（fix_template / update_convention / log_for_review）、`client`（claude=Claude Code，codex=Codex，dsh=DeepSeek Harness，其他填 other）。项目地址已绑定 `project_id`，可以省略；只连到全局地址时，显式传 `.lian-jing/context.json` 里的 `project_id`。
|
||
2. 只有能说出至少一条具体代价或验证结果（如「返工 2 轮」「在 X 场景实测有效」）时，`confidence` 才填 `confirmed`；否则填 `under_validation`。
|
||
3. 不得写入凭据、密钥、账号、内网地址或生产数据：回传内容会同时写进本项目的 `.blueprint/notes-archive.jsonl`，随项目进入 Git。
|
||
4. 同一会话里已经回传过的洞察，不要换个说法再报一次。把返回的编号 `#note_id` 写进给用户的总结，例如「已回传炼境 N 条（#编号）」。
|
||
5. 子项目只回传、不处置：`resolve_envoy_return`、`list_envoy_returns` 属于炼境控制面会话，即使在工具列表里看到也不要调用。
|
||
6. 工具列表里没有 `report_envoy_return` 时，按下方降级顺序排查。仍不可用，就把待回传内容按上述字段整理成文本交给用户，由用户转交炼境会话；不要改用 `append_project_note` 等其他写入工具代替。
|
||
|
||
如果 MCP 未出现，按以下顺序降级，不猜测状态：
|
||
|
||
1. `configured`：确认当前客户端的 `lian-jing` 指向 `http://127.0.0.1:<port>/mcp/projects/<canonical project_id>`——Codex 看项目 `.codex/config.toml`，Claude Code 看 `~/.claude.json` 中本项目的 local 条目（优先于 user 级全局条目），DSH 看 `~/.dsh/cordis.patch.yml`。缺失或仍指向全局 `/mcp` 时通过炼境重新 `inject_mcp`，手工同名 server 不覆盖。
|
||
2. `reachable`：配置正确后检查 loopback 服务；连接拒绝表示炼境未运行，先启动正式安装版并保持托盘进程。
|
||
3. `reload`：服务可达但当前会话看不到工具时，新建会话或重载客户端；不要反复改配置或复制凭证。
|
||
4. 仍不可用时，明确报告停在哪一层，继续完成不依赖 MCP 的本地工作；不得伪造诊断、项目 ID、凭证或远端状态。
|