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>
196 lines
11 KiB
Cheetah
196 lines
11 KiB
Cheetah
<!-- 项目名 --> — AI Agent 上下文
|
||
|
||
> 本文件遵循 [AGENTS.md 开放规范](https://agents.md/)，供 Claude Code、Qwen Code、Cursor、Copilot 等 AI 工具读取。
|
||
> 由炼境接入包分发。请按项目实际补全下方 TODO 段落。
|
||
> `ONBOARDING_MANAGED` 标记块由炼境版本化管理（重跑接入包可原位升级），块外内容永不触碰。
|
||
|
||
## 项目概况
|
||
|
||
<!-- TODO: 一句话描述项目 + 技术栈。例：pnpm monorepo，React 19 + TypeScript 前端 + Hono API。 -->
|
||
<!-- TODO: 在 .blueprint/manifest.yaml 顶层补 agent_button_carrier（tauri/http/cli/playwright），
|
||
splitter 生成任务卡时直接从此字段继承验证载体。参考 .blueprint/CONVENTIONS.md §manifest.yaml规范。 -->
|
||
|
||
## 架构与模块
|
||
|
||
<!-- TODO: 列出主要目录/模块及职责，帮助 AI 快速定位「改哪里」。 -->
|
||
|
||
## 关键文档索引
|
||
|
||
<!-- TODO: 列出 README / ARCHITECTURE.md / 其他关键文档及用途。 -->
|
||
|
||
<!-- ONBOARDING_MANAGED_START version="1.10.0" -->
|
||
> ⚠️ 本块由炼境版本化托管，升级时**整块原位覆盖**——项目定制请写到块外，块内手改必丢（2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示）。
|
||
|
||
## 核心开发约束
|
||
|
||
### 包管理
|
||
- **pnpm 唯一**：禁止 npm / yarn / npx / bun
|
||
- lock 文件只有 `pnpm-lock.yaml`，不生成其他
|
||
|
||
### 代码规范
|
||
- TypeScript 优先，避免 `any`
|
||
- 函数/变量 camelCase；组件 PascalCase
|
||
- 异步统一 `async/await`，不用裸 Promise 链
|
||
- 错误处理明确 `try/catch`，不吞异常
|
||
- 优先编辑现有文件，避免创建不必要的新文件
|
||
- **Playwright 版本固定**：`package.json` 里的 `playwright` 锁死版本号，去掉 `^`；
|
||
另建 `test:install` 脚本显式安装浏览器（`playwright install --with-deps`），
|
||
升级时有意识操作，避免 pnpm install 静默触发 ~200MB 的浏览器重下
|
||
|
||
## 需求对齐协议
|
||
|
||
开始写代码前，先判断改动类型：
|
||
|
||
**Bug Fix**（当前行为与预期的意外偏差）
|
||
→ 建任务卡，直接执行，无需等确认词。
|
||
|
||
**Feature / 行为变更**（新增能力或主动改变已有行为）
|
||
→ 必须先输出确认卡，等用户说「确认」再动手：
|
||
|
||
- **S 级**（单文件、行为对外无变化，任务卡 complexity=S）：输出三行轻量卡
|
||
```
|
||
改哪：<文件或模块>
|
||
改什么：<一句话>
|
||
验收：<agent_verify 路径>
|
||
```
|
||
- **M / L 级**：输出完整任务卡（含 `files` + `acceptance` + `complexity`），等确认
|
||
|
||
**边界模糊时**：保守判断，按 Feature 处理，走完整确认卡。
|
||
|
||
**提交时**：`feat:` 提交须在 commit message 末尾加 `Feature-Confirmed: true` trailer（lefthook commit-msg 强制检查）。这是确认卡已输出的机器层存证。
|
||
|
||
> ⚠️ Session 结束汇总补录 ≠ 确认卡替代——补录仅适用于漂移检测触发后用户主动选择补录的场景，不得作为「先做再补」的通道。
|
||
|
||
## Git 工作流
|
||
|
||
见 `docs/ai-context/git-workflow.md`（分支策略 + Conventional Commits + Rules-Applied trailer + PR 规范）。
|
||
**commit 必须符合 Conventional Commits**（lefthook 强制），炼境据此采集飞轮数据。
|
||
|
||
## 炼境项目上下文与能力包
|
||
|
||
- `.lian-jing/context.json` 是项目 `project_id` 的工具无关单一事实来源；不要从客户端项目 UI、用户级插件或全局配置推断项目身份。
|
||
- `.claude/liangjing.json` 只是旧项目的 Claude 兼容投影。只发现它时，调用 `inject_mcp(project_id)` 迁移，而不是手工复制或猜测 ID。
|
||
- `.lian-jing/capability-packs.json` 记录炼境托管基线的版本。`verify_onboarding(project_id)` 报告 `legacy`、`version_mismatch` 等状态时，按其 `detail` 中的升级提示处理。
|
||
- `apply_onboarding_pack(project_id)` 只更新炼境明确托管的接入包文件；项目自己的业务规则、测试、部署声明和手工定义的同名 MCP server 仍归项目所有，不能被升级覆盖。
|
||
- 遇到炼境分发的模板、约定或 MCP 工具的摩擦，或验证出跨项目可复用的实践时，调用 `report_envoy_return` 回传炼境（只追加信号，不必逐条征得用户同意；Claude 会话结束时也可跑 `/envoy`）；何时回传、字段怎么填见 lian-jing skill「遇到摩擦时回传炼境」一节。
|
||
|
||
### Node/pnpm 工具链
|
||
|
||
- Node 精确版本以 `.nvmrc` 为事实源，pnpm 精确版本以 `package.json#packageManager` 为事实源；不要追随 IDE、Codex 或全局 PATH 的 bundled runtime。
|
||
- Node+pnpm 项目由炼境分发最小 `mise.toml`，只启用上述标准声明，不重复保存版本；已有手写 `mise.toml` 永不覆盖。
|
||
- 开始运行 pnpm 命令前调用 `get_toolchain_status(project_id)`。返回 `ready_managed` 时使用 `mise exec -- pnpm ...`；`mismatch/conflict/unavailable` 时先报告证据。
|
||
- `prepare_toolchain(project_id, confirmed=true)` 会下载/安装项目声明版本，只有用户明确确认本次机器状态变更后才能调用；不得为消除告警而修改项目版本或 lockfile。
|
||
|
||
## agent 按钮与验证路径
|
||
|
||
功能的本体是代码层的能力；UI 按钮是它给人的投影，**agent 按钮**是给 agent 的投影
|
||
（可发现 + 可调用 + 有边界的能力声明）。**任何功能 = 一个本体 + 两个投影，同源同边界**；
|
||
设计交付时先定本体后盖投影（原型探索不受此序约束，交付前本体归位）。开发任何功能时遵守：
|
||
|
||
1. **边界单点实现**：业务校验只写在能力本体层（API/command），UI 只呈现不复制逻辑——
|
||
否则人与 agent 的验证路径会分裂。同源的直接推论：**人的操作序列 agent 皆可复刻**——
|
||
人报障即复现路径（操作 + 状态），agent 重放至同一状态定位病灶。
|
||
三分定位启发式：本体重放正常 → 优先怀疑投影层（接线/渲染/状态同步）→ 再查环境差异
|
||
（安全上下文/网络/OS）；重放失败先怀疑初始状态差异，而非否定问题存在
|
||
2. **载体就近选择**（本项目的 agent 按钮是什么，按项目类型对号入座）：
|
||
| 项目类型 | agent 按钮载体 |
|
||
|---------|---------------|
|
||
| Web 服务 | HTTP API 本身（前端按钮与 curl 调同一 endpoint，天然双投影） |
|
||
| CLI/脚本 | 命令与 npm scripts |
|
||
| 桌面应用 | 测试直接调用 command 函数 |
|
||
| UI 呈现层 | Playwright 驱动真界面（最后手段，仅关键路径） |
|
||
3. **完成的定义**：功能实现后，由 agent 沿投影路径真实走通一次（起服务 → 调接口 →
|
||
断言行为），再交人做 UI 终验——不许绕过功能手改产物冒充验证
|
||
4. **侦察 → 驻军**：agent 走通的关键路径，顺手固化为一条测试（桌面应用用 cargo test；Web 项目纯逻辑层用 vitest）；
|
||
一次性验收不固化（少而稳 > 多而脆）
|
||
5. **acceptance 可执行化**：`/splitter` 生成任务卡时，`acceptance` 字段必须是可执行验证路径，
|
||
格式：`[载体] 调用/运行什么(参数) → 断言什么`。
|
||
- 正例：`[Tauri command] apply_onboarding_pack(project_id) → written≥1，文件在磁盘存在`
|
||
- 正例：`[HTTP API] POST /api/users → 201，body.id 非空`
|
||
- 反例：`功能正常可用`（模糊，agent 无法自验）
|
||
|
||
**分层原则**：凡含 UI 操作路径的 acceptance，必须拆成两段：
|
||
- `agent_verify:` — 机器可断言（HTTP 状态码、数据库记录、函数返回值）；stop hook / CI 只验此段
|
||
- `human_verify:` — 需人眼判断（视觉效果、拖拽手势、30 秒浏览器终验）
|
||
纯 API / 命令行任务可省略 `human_verify:`；UI 拖拽 / 动画 / 视觉类必须拆，否则 stop hook 无法收敛。
|
||
human_verify 的否决理由值得记录——它是把体感转译成可断言规则的原料。
|
||
6. **自验报告纪律**：交人终验前的反馈必须含「**没验什么**」一节（未覆盖的路径、依赖的
|
||
假设、不确定的地方）；自修过程中改了断言/验收标准必须显式声明理由（改功能让测试过是
|
||
常规，改测试让功能过需报备）；agent 自验对 acceptance，人终验对意图——acceptance
|
||
可能继承需求理解偏差，两把尺子不可合一
|
||
|
||
> 收束：**本体先行，边界一次，操作同语——人指的问题 agent 走得到，人在意的点 agent 读得懂。**
|
||
> 后半句分两个时间尺度：当下会话由同源路径即时对称（反馈天然绑定双方走过的路径）；
|
||
> 跨会话靠否决理由落账（→ 复盘笔记）积累，人反复在意的维度逐步迁移进可断言规则——
|
||
> 人裁决区是飞轮推进的前线，不是墙上的洞。
|
||
|
||
## 多 AI CLI 协作
|
||
|
||
本项目可由多个 AI CLI 协同。交接时把结果总结成 3 条传给下一个：
|
||
|
||
```
|
||
1. 已完成：<改了哪些文件 + 核心决策>
|
||
2. 待验证：<需要确认的地方>
|
||
3. 约束继承：<影响后续的关键限制>
|
||
```
|
||
<!-- ONBOARDING_MANAGED_END -->
|
||
|
||
---
|
||
|
||
## 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（外部行为不变）、测试文件、临时脚本。
|
||
|
||
---
|
||
|
||
## 文档防腐铁律
|
||
|
||
- 文档只写稳定的：为什么、铁律、意图、架构决策。
|
||
- 易变的（端口、路由、表名、命令清单）交给工具自省，不写死进常驻文档。写死 = 定时炸弹。
|
||
- 单一事实来源：两处说同一事时，删掉派生的那处。
|
||
- 两份文档打架时，信代码，不信文档。
|
||
|
||
---
|
||
|
||
## 定期防腐自查
|
||
|
||
每隔一阵或大改后，对照以下清单：
|
||
|
||
- [ ] AGENTS.md 里的技术栈声明还和代码一致吗？
|
||
- [ ] `docs/ai-context/project-brief.md` 最近 30 天有没有随架构改动更新？
|
||
- [ ] 有没有两份文档说同一件事且打架？
|
||
- [ ] `docs/ai-context/project-context.yaml` 的契约路径还准确吗？
|