dev-manager-tauri/src-tauri/resources/onboarding/.agents/skills/lian-jing/SKILL.md
lanrtop 3095df3d2a feat(mcp/envoy): 使者回传闭环——回执 + 三端回传入口
回传只进不出:list_envoy_returns 无处置状态、LIMIT 50 把更早的回传静默挤掉;
入口只有 Claude /envoy,08-23 后 enterprise 主力转 DSH/Codex 即零回传。

- envoy.rs 业务本体(连接注入)+ envoy_dispositions 回执表(migrate 补表)
- report_envoy_return(项目级,Claude/Codex/DSH 在项目地址均可用):字段枚举校验、
  内容压单行限长、兜底拒绝明显凭据;同项目 1 天内同内容未处置幂等返回原编号
  (IMMEDIATE 事务防并发重复);复用 append_project_note 的档案双写
- resolve_envoy_return(控制面):landed/carded 必填落点、reason 必填、允许更正
- list_envoy_returns 默认只列未处置(带编号),附已处置计数,超出展示上限明说;
  LEFT JOIN 不再丢掉登记已删项目的回传;include_resolved 可审计回执
- lian-jing skill 新增「遇到摩擦时回传炼境」;/envoy 改为指向该入口的薄指引
  (保留扫描与分类硬门槛,炼境分发物出错免门槛,身份改读 .lian-jing/context.json);
  AGENTS 托管块加一行指路(1.9.0→1.10.0),能力包 base-onboarding 1.6.0→1.7.0
- 删除炼境仓库内 Codex 迁移遗留的 source-command-envoy 技能(读旧身份文件、走旧写入路径)
- 契约与架构文档同步:project-context.yaml、project-brief.md、AGENTS.md、agents-meta-rules.md

Rules-Applied: R05,R06,R12
Feature-Confirmed: true

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 01:15:40 +09:00

6.3 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:

  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、凭证或远端状态。