3095df3d2a
回传只进不出：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>
162 lines
7.6 KiB
Markdown
162 lines
7.6 KiB
Markdown
---
|
||
version: 1.2.0
|
||
updated: 2026-09-21
|
||
usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标准内容
|
||
---
|
||
|
||
# Agent 友好工程元规则
|
||
|
||
> 本节由炼境接入包分发，规则技术栈无关，适用于所有项目和所有 AI 工具。
|
||
> 项目特定的路径映射见 `docs/ai-context/project-context.yaml`。
|
||
|
||
## 炼境项目上下文与能力包
|
||
|
||
- 项目根目录 `.lian-jing/context.json` 是工具无关的 `project_id` 单一事实来源；客户端项目 UI、用户级插件和全局配置都不能替代它。
|
||
- `.claude/liangjing.json` 仅用于兼容已接入的旧 Claude 项目；发现 legacy-only 状态时，应通过炼境迁移，不应复制或猜测 ID。
|
||
- `.lian-jing/capability-packs.json` 仅描述炼境托管基线的版本与自检。升级必须显式报告版本不符，并且不能覆盖项目自己的业务规则、测试、部署声明或手工 MCP 配置。
|
||
- 子项目 agent（Claude、Codex、DSH）遇到炼境分发物的摩擦或验证出跨项目实践时，经同一 MCP 入口 `report_envoy_return` 回传；何时回传与字段规范只写在 lian-jing skill，AGENTS 托管块只留一行指路（skill 按需加载，AGENTS 三端必读）。
|
||
|
||
---
|
||
|
||
## Agent 友好工程四支柱
|
||
|
||
修改代码前，确认这个项目满足四支柱：
|
||
|
||
**可导航**：凭文件名/目录名可在 30 秒内定位某功能的代码。通用能力有独立家，不寄生在业务模块下。
|
||
|
||
**可推理**：公共类型只在一处定义。改一个接口，类型检查能报出所有受影响处。
|
||
|
||
**可验证**：typecheck / lint / test 各有一条命令真能跑。关键路径有冒烟测试。
|
||
|
||
**可记忆**：规则按场景注入（不是一份巨型文档）。决策只写"为什么"，代码自己回答"是什么"。
|
||
|
||
---
|
||
|
||
## 文档防腐元规则
|
||
|
||
做任何改动时，判断它属于哪类变更：
|
||
|
||
### T1 外部契约变更（最高优先级）
|
||
其他代码、服务、或 agent 依赖的定义——接口、共享类型、数据结构、配置键名、环境变量名。
|
||
→ 查 `docs/ai-context/project-context.yaml` 找到记录该契约的文档，检查并同步更新。
|
||
|
||
### T2 架构边界变更
|
||
模块划分、目录结构、依赖方向、包边界调整。
|
||
→ 检查架构文档是否需要同步。
|
||
|
||
### T3 工具链变更
|
||
引入或替换库、框架、构建工具。
|
||
→ 更新 AGENTS.md 技术栈声明；通知炼境重新扫描并更新 `project-context.yaml`。
|
||
|
||
### T4 常驻上下文过期
|
||
AGENTS.md 或 `docs/ai-context/project-brief.md` 描述的现实已经改变。
|
||
→ 立即更新。这两份文档常驻 agent 上下文，过期危害最大。
|
||
|
||
### 不触发检查
|
||
内部重构、性能优化、bug fix（外部行为不变）、测试文件、临时脚本。
|
||
|
||
---
|
||
|
||
## 文档防腐铁律
|
||
|
||
- 文档只写稳定的：为什么、铁律、意图、架构决策。
|
||
- 易变的（端口、路由、表名、命令清单）交给工具自省，不写死进常驻文档。写死 = 定时炸弹。
|
||
- 单一事实来源：两处说同一事时，删掉派生的那处。
|
||
- 两份文档打架时，信代码，不信文档。
|
||
|
||
---
|
||
|
||
## 跨 AI 工具交接模板
|
||
|
||
完成一段工作并交接给下一个 agent 时，附上：
|
||
|
||
```
|
||
已完成：<修改了哪些文件 + 核心决策>
|
||
待验证：<需要对方确认的地方>
|
||
约束继承：<影响对方工作的关键限制>
|
||
```
|
||
|
||
---
|
||
|
||
## 定期防腐自查
|
||
|
||
每隔一阵或大改后，对照以下清单：
|
||
|
||
- [ ] AGENTS.md 里的技术栈声明还和代码一致吗？
|
||
- [ ] `project-brief.md` 最近 30 天有没有随架构改动更新？
|
||
- [ ] 有没有两份文档说同一件事且打架？
|
||
- [ ] `project-context.yaml` 的契约路径还准确吗？
|
||
|
||
---
|
||
|
||
## Agent 按钮体系
|
||
|
||
> 让 AI agent 具备无人值守执行能力的工程方针。随炼境接入包分发，适用于所有项目和所有 AI 工具。
|
||
|
||
### 分工原则
|
||
|
||
```
|
||
人定目标 → agent执行 → agent自验（走agent按钮） → 人终验
|
||
```
|
||
|
||
人只保留两件事：**需求澄清（目标定义权）** 和 **目标验收（终验权）**。中间的执行与验证环路在 agent 内部闭合。
|
||
|
||
### Agent 按钮清单（接入时必填）
|
||
|
||
在项目 AGENTS.md 中声明本项目的 agent 按钮，让 agent 知道有哪些能力可调用：
|
||
|
||
```markdown
|
||
## Agent 按钮（可调用能力）
|
||
| 能力 | 调用方式 | 通过标准 |
|
||
|------|---------|---------|
|
||
| 类型检查 | `<填入命令>` | `<填入通过标准>` |
|
||
| 测试运行 | `<填入命令>` | `<填入通过标准>` |
|
||
| 核心功能验证 | `<填入命令>` | `<填入通过标准>` |
|
||
```
|
||
|
||
三要素缺一不可：**可发现**（清单里有）、**可调用**（结构化命令）、**边界清晰**（通过标准明确）。
|
||
|
||
### 同源同边界（设计原则，v1.7.0 起）
|
||
|
||
**任何功能 = 一个本体 + 两个投影**：本体是能力层实现（API/command/服务函数），人按钮（UI）与 agent 按钮都是它的投影。同源 = 两投影走同一代码路径；同边界 = 业务校验只在本体层砌一次墙。设计交付时先定本体后盖投影（原型探索豁免此序，交付前本体归位）。
|
||
|
||
同源的直接推论：**人的操作序列 agent 皆可复刻**——人报障即复现路径（操作 + 状态），agent 重放至同一状态定位病灶。三分定位启发式：本体重放正常 → 优先怀疑投影层 → 再查环境差异；重放失败先怀疑初始状态差异，而非否定问题存在。
|
||
|
||
效果分两层：**防御**——人指的问题即复现路径，agent 走得到；**进攻**——操作成为人机共同语言，人的验收反馈天然绑定双方走过的路径，需求信息对称。对称有两个时间尺度：当下会话由同源结构直接保证（无需额外机制）；跨会话需反馈落账（human_verify 否决理由 → 复盘笔记 → 梦核蒸馏），人反复在意的维度逐步迁移为可断言规则——人裁决区是飞轮推进的前线，不是墙上的洞。
|
||
|
||
> 收束：**本体先行，边界一次，操作同语——人指的问题 agent 走得到，人在意的点 agent 读得懂。**
|
||
|
||
### Acceptance 写法规范
|
||
|
||
acceptance 是 agent 自验的唯一判断依据，必须是**可执行断言**，不能是描述性语句：
|
||
|
||
```
|
||
❌ "功能正常运行"（描述性，agent 无法判断完成）
|
||
❌ "代码正确"（主观，无可执行路径）
|
||
✅ "pnpm test 通过"
|
||
✅ "curl /api/xxx 返回 200，body.id 非空"
|
||
✅ "pnpm typecheck 无报错"
|
||
✅ "[命令] 运行什么 → 断言什么"
|
||
```
|
||
|
||
含 acceptance 的任务卡才可派发；acceptance 可执行，自验才是真自验——这是整个体系的核心关节。
|
||
|
||
### 自验报告纪律
|
||
|
||
- 交人终验前的反馈必须含「**没验什么**」一节：未覆盖的路径、依赖的假设、不确定的地方
|
||
- 自修过程中改了断言/验收标准必须显式声明理由（改功能让测试过是常规，改测试让功能过需报备）
|
||
- agent 自验对 acceptance，人终验对**意图**——acceptance 可能继承需求理解偏差，两把尺子不可合一
|
||
|
||
> 为什么：自验的结构性盲区是"验证代码与功能代码共享同一份理解偏差"，负面披露收窄已知盲区，
|
||
> 人终验（对意图、带意外感触发的深查）兜底未知盲区。两者互补，缺一另一超载。
|
||
|
||
### 自验失败降级约定
|
||
|
||
- **失败 2 次内**：自行修正，继续自验
|
||
- **失败 3 次**：停止执行，输出以下内容后等待人工介入：
|
||
1. 失败原因（具体报错或不通过的断言）
|
||
2. 已尝试的修正路径
|
||
3. 需要人决策的具体问题
|
||
|
||
> 无人值守不是消灭人工介入，而是把人从"执行路径"移到"降级路径"。降级时主动升级，比静默卡死更重要。
|