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

56 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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`)与回传炼境(`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、凭证或远端状态。