dev-manager-tauri/src-tauri/resources/onboarding/.agents/skills/lian-jing/SKILL.md
lanrtop e13599fbbd
All checks were successful
Push & PR Check / check (push) Successful in 59s
Push & PR Check / check (pull_request) Successful in 1m0s
feat(onboarding/parity): lian-jing skill 补写操作确认与 unavailable/unknown 两条通用边界,接入包升至 1.8.0
P7 实测 Codex 不把 MCP 服务器说明带入模型上下文,服务器说明里的「其他写操作
须用户明确确认」「unavailable/unknown 不得当作成功」在 skill 中只有分场景表述。
现把两条作为通用边界写进 lian-jing skill 模板开头(同一模板双投影到 .agents
与 .claude),措辞与服务器说明一致;只读查询、登记开发需求元数据、回传炼境
列为无需确认的例外,与 skill「回传不必逐条征得同意」相容。

- base-onboarding 1.7.0→1.8.0(BASE_ONBOARDING_PACK_VERSION、模板
  capability-packs.json、TEMPLATE_FINGERPRINTS 指纹)
- mcp_server 新增 server_instruction_universal_rules_are_in_skill:服务器说明与
  skill 任一侧缺这两条即失败
- 蓝图 agent-client-parity P7 known_limits 记录已补齐

Feature-Confirmed: true
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 05:25:18 +09:00

6.8 KiB
Raw Blame History

name description
lian-jing 读取炼境项目健康状态,并使用炼境 MCP 的项目管理、Gitea 与交付能力;遇到炼境模板、约定或工具的摩擦时回传炼境。

炼境项目技能

开始项目工作时,先读取根 AGENTS.md 与 .lian-jing/context.json 取得 project_id。.claude/liangjing.json 仅为旧项目的 Claude 兼容投影,不能作为长期身份来源。

如果当前客户端已发现 lian-jing MCP,所有调用都遵守两条通用边界(与炼境 MCP 服务器说明一致):

  • 只读查询、登记不含秘密的开发需求元数据(register_project_test_account)与回传炼境(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 编号、完整 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 登记名称、目标系统、非生产环境与用途,并请用户在炼境项目 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、凭证或远端状态。