Dev

.agents/notes/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — Agent Notes
+
+Agent Note 实质是 agent 撰写的 RFC：保留依据、替代方案、后果与必需验证的持久提案与决策记录。遵循[文档标准](../../docs/AGENTS.md)与 [Agent Note 规则](README.md)。
+
+**每份新增 Agent Note 都触发一次取代检查。** 在活跃目录树中搜索覆盖同一决策或机制的旧记录，判定是完整取代还是部分取代，并在同一 PR 中归档每一组符合条件的已实施记录。部分取代的记录保持活跃并互相链接。
+
+[`archived/`](archived/AGENTS.md) 下的文件是冻结的历史快照：永不编辑，也不得将其视为当前权威依据。

.agents/notes/README.md

@@ -0,0 +1,146 @@
+# Agent Notes
+
+这里存放一类设计文档。**Agent Note** 记录影响本代码库的决策或提案：代码和文档无法承载的*为什么*以及*放弃了什么*。本文件规定 Agent Note 存放在哪里、何时需要写一份，以及[文件内格式](#the-file-format)。
+
+<a id="layout-and-naming"></a>
+
+## 布局与命名
+
+每份 Agent Note 有两个维度，都编码在其**路径**中：`{lifecycle}/{class}/yyyy-mm-dd-topic-title.md`。
+
+- **生命周期**（顶层文件夹）是 Agent Note 的状态，Agent Note 随状态变化在文件夹之间移动：
+  - **`proposed/`**：实施前评审的提案；尚未构建（或仅部分构建）。
+  - **`implemented/`**：决策已交付。文件记录做了什么决定、否决了什么，并**与实际交付的内容保持同步**：当代码后续移动文件、重命名包或更改键名/默认值时，Agent Note 在同一个变更中同步更新（仅限事实——路径、名称、结构——而非决策本身）。见 [implemented/AGENTS.md](implemented/AGENTS.md)。
+  - **`rejected/`**：提案经过讨论后被否决。仅当其决策依据仍能避免一种诱人且影响重大的错误时保留；否则删除整份记录。
+- **类别**（嵌套文件夹）是决策的*种类*——见下方[分类](#classification)。
+
+文件名中的日期是该主题**首次提出**的时间（以 git 历史为准）。Agent Note 之间的交叉引用使用相对 Markdown 链接（`[topic](../../implemented/architecture/2026-…-….md)`），从不使用纯文字或编号，这样既可机械检查，也能在文件夹间移动时保持有效。
+
+活跃生命周期目录树就是工作清单：浏览其生命周期/类别文件夹，或搜索仓库即可。请勿添加集中式 `INDEX.md`：它重复路径元数据，并让无关记录的变更争用同一个生成文件。具有历史决策价值但未来指导价值较低的已实施记录会移至下文所述、单独冻结的 [`archived/`](archived/AGENTS.md) 目录树。
+
+<a id="classification"></a>
+
+## 分类
+
+每份 Agent Note 属于 `scripts/agent-note-tree.ts` 中封闭集合里的一个路径编码类别；分类门禁拒绝其他文件夹。新增类别需要同时更新规范集合与本节。
+
+| 类别             | 覆盖范围                                                                        |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `feature`        | 面向用户或模型的新能力。                                                        |
+| `bug-fix`        | 修正缺陷或弥补事故复盘（postmortem）发现的缺口。                                |
+| `simplification` | 在不增加能力的前提下移除代码、行为或对外范围。                                  |
+| `architecture`   | 关于**交付源码**的结构性决策：包之间的关系、运行时词汇。                        |
+| `process`        | 代码**周边**的工具、策略或工作流——门禁、包管理器、vendor 化——不涉及运行时行为。 |
+| `testing`        | 测试基础设施与策略。                                                            |
+
+`architecture` 与 `process` 的界线：**architecture** 关乎我们交付的源码；**process** 关乎围绕源码的工具与工作流。（`refactor` 被有意排除：它与 `simplification` 重叠，而后者的判别标准「可观察行为是否改变」已经覆盖了它。）
+
+<a id="archiving-and-deletion"></a>
+
+## 归档与删除
+
+仅描述小型 UI 调整或纯机械变更的 implemented Agent Note 直接删除，并修复或移除入站链接。局部 bug 修复、性能变更、新能力或实质行为决策，不会仅因实现规模小就符合删除条件。其他已实施记录只有在交付决策完整落地、其依据不太可能再指导未来工作，但仍具有历史决策价值时才归档。如果其中的备选方案、归属边界、否定性保证、持久化语义或协议语义、安全规则，或者重新引入条件仍有价值，则继续作为活跃记录保留。绝不归档 proposed Agent Note：过时的提案应转为 rejected。仅当 rejected Agent Note 仍能避免一种可能发生的错误时保留；否则一并删除该文件。不要根据字数、存续时间或目标配额来判断。
+
+归档路径编码为 `archived/{class}/yyyy-mm-dd-topic-title.md`；其中有意省略 `implemented`，因为只有 implemented Agent Note 可以进入归档。归档变更只移动该文件、保留 `Status: implemented`、紧接该状态行插入 `Archived: YYYY-MM-DD` 行，并修复或删除入站链接。归档时只允许对内容做这些更改。既有标题标点与空行布局不阻止归档；与正文一起保留。
+
+封存后，每组归档文件都永久冻结。禁止编辑、翻译、重新格式化、更新、移动或删除，也不得将其视为当前行为的权威依据。文档门禁会跳过归档源文件，包括其中的出站链接；当活跃文档有意引用历史时，仍可链接到归档 Agent Note。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 强制执行封闭的类别目录树、归档元数据，以及仅追加的冻结内容 manifest（元数据清单），但[归档说明](archived/AGENTS.md)中记录的精确封存哈希转换除外。归档政策 Agent Note 记录了设计依据。
+
+<a id="when-to-write-one"></a>
+
+## 何时需要写一份
+
+只有代码、测试和现有文档未能解释的决策理由具有长期价值时，才在同一 PR（Pull Request）中新增或更新 Agent Note。对未来重大工作的提案从 `proposed/` 开始；已经做出的决策从 `implemented/` 开始。选择与决策匹配的类别文件夹（见[分类](#classification)）。
+
+更新已经拥有该决策的 Agent Note 即可满足规则；不要创建重复记录。机械性或局部编辑均可豁免，包括局部 UI 展示和交互调整。Agent Note 永远不会被编辑为一个*不同的决策*：用新 Agent Note 取代旧记录，并让两个记录保持互相链接，除非后续依据下方规则完全合并旧记录。编辑 `implemented/` Agent Note 以跟踪其现有决策的所在位置是必需的，而非禁止的；见 [implemented/AGENTS.md](implemented/AGENTS.md)。
+
+被完全取代的 implemented Agent Note 可以合并到当前持有该决策的记录中，并删除原文件。删除前，当前记录必须保存所有独有的决策依据、备选方案、影响、必需的验证和明确指出的覆盖缺口；修复所有入站链接；并在同一变更中删除该文件。仅部分被取代的记录不符合此条件：保留两个记录并让它们互相链接，同时更新所有仍然适用的事实。合并不得将旧文件改写成与其相反的决策，也不得让 git 历史成为决策依据的唯一副本。
+
+只有当一项功能已从生产代码、配置、schema、持久化格式或协议格式、迁移和兼容行为中完全消失，当前文档不再将其描述为可用，且没有测试把它作为受支持行为来执行时，新增该功能的 Agent Note 才可合并进后续的移除记录。移除决策的依据和验证该功能已不存在的测试可以保留。移除决策的持有记录必须保留最初动机、为什么该动机已不足以证明保留该功能的合理性、完全移除之外的备选方案、放弃的能力、重新引入的条件，以及证明已彻底移除的验证。过时的实现清单和只验证已删除行为的测试不属于当前验证证据。仅移除一种传输、默认值、实现或展示属于部分取代；仍有任何持久数据或兼容处理也同样如此。
+
+<a id="the-file-format"></a>
+
+## 文件格式
+
+每份活跃 Agent Note 遵循统一的文件内格式，由 `pnpm run verify-agent-note-format`（[scripts/verify-agent-note-format.ts](../../scripts/verify-agent-note-format.ts)，`verify-all`（文档同步门禁）的一环）强制执行；该格式的设计动机及其否决的替代方案见已归档的统一格式 Agent Note。归档记录保留封存时的格式，并增加上述归档日期行。
+
+<a id="the-header-block"></a>
+
+### 头部块
+
+每份 Agent Note 的前三行严格为：
+
+```markdown
+# Agent Note: <title>
+
+Status: <status>
+```
+
+后跟一个空行。`Status:` 的值有三种形式，且必须与文件所在的生命周期文件夹一致——门禁会交叉检查：
+
+- `Status: proposed`
+- `Status: implemented`
+- `Status: rejected — <why, in one line>`
+
+状态行不带日期、不带括号补充说明：文件名记录首次提出日期，git 记录其余一切；「以修订形式接受」之类的说明属于正文内容（在陈述决策的地方说明修订）。拒绝原因是唯一带内容的状态，因为读者查阅被否决的 Agent Note 时，结论正是他们要找的。
+
+<a id="the-body-skeleton"></a>
+
+### 正文骨架
+
+每份 Agent Note 的正文以 `## Problem` 开头：动机，写法上不依赖解决方案即可独立成文。后续内容取决于生命周期；固定章节使用以下规范名称且仅限这些名称，而真正独特的技术章节（包拓扑、协议约定、schema 等）在必需章节之间可自由组织。
+
+#### `proposed/`
+
+```markdown
+## Problem
+
+## Proposal
+
+…bespoke sections…
+
+## Alternatives considered
+
+## Acceptance criteria
+
+## Risks
+```
+
+`## Proposal` 描述拟议的变更，可以合理地使用将来时态——计划、迁移步骤和待解决问题在工作尚未完成时属于此处。`## Acceptance criteria` 说明什么可观察状态意味着完成。`## Risks` 涵盖可能出错的事项以及该变更有意放弃的东西。
+
+#### `implemented/`
+
+```markdown
+## Problem
+
+## Decision
+
+…bespoke sections…
+
+## Alternatives considered
+
+## Consequences
+```
+
+`## Decision` 以现在时态描述已交付的现实，整个文件按 [implemented/AGENTS.md](implemented/AGENTS.md) 的要求与之保持同步。`## Consequences` 记录权衡的代价**与**收益。提案阶段的标题在此属于规格用语，门禁会拒绝它们：`## Proposal`、`## Plan`、`## Migration plan` 和 `## Acceptance criteria` 不得出现在 implemented Agent Note 中（原因见 [slop 检查清单](../../docs/AGENTS.md)）。`## Testing`、`## Deferred` 或 `## Related` 章节在陈述现在时态的事实时是允许的。
+
+#### `rejected/`
+
+被否决的 Agent Note 是冻结的提案：保留提案时的所有章节（包括 `## Acceptance criteria` 或 `## Plan`），结论写在 `Status:` 行上。仅头部块、`## Problem` 开头、`## Proposal` 章节以及下方的「曾考虑的替代方案」强制要求适用。
+
+<a id="alternatives-considered--mandatory"></a>
+
+### 曾考虑的替代方案——必需
+
+每份 Agent Note 都必须包含 `## Alternatives considered` 章节：每个真实的替代方案及其落选原因，每个替代方案用一个加粗引导的段落，或对争议较大的替代方案用 `### Why not <X>?` 子节。记录决策时不记录它击败了什么，就是在邀请反复争论——这正是 Agent Note 旨在防止的问题。
+
+替代方案是记录下来的，不是凭空编造的。日期早于 2026-07-05 且替代方案无法从记录中重建的 Agent Note，用以下精确注释代替该章节，门禁仅对格式规范之前的文件接受此注释：
+
+```markdown
+<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->
+```
+
+<a id="moving-between-lifecycles"></a>
+
+### 在生命周期之间移动
+
+将文件在生命周期文件夹之间移动意味着在同一个变更中更新 `Status:` 行并满足目标文件夹的骨架要求——否则门禁会失败。具体而言，`proposed/` → `implemented/` 将 `## Proposal` 改写为现在时态的 `## Decision`，将 `## Acceptance criteria` 和 `## Risks` 折入 `## Consequences`（或折入一个现在时态的 `## Testing`/`## Verification` 章节，用于描述现在锁定该行为的内容），并用实际交付的内容替换计划——也就是将 [implemented/AGENTS.md](implemented/AGENTS.md) 所要求的改写变成可机械检查的规则。`proposed/` → `rejected/` 仅在 `Status:` 行添加原因并冻结文件。

.agents/notes/archived/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — 归档 Agent Note
+
+各类别目录下的归档 Agent Note 是冻结的历史快照，不是当前权威依据。对已封存制品永不编辑、重新格式化、翻译、修复、删除或移动；新的决策与事实请写入活跃 Agent Note 或当前文档。
+
+归档变更只允许：移动该记录，在 `Status: implemented` 行下方插入 `Archived: YYYY-MM-DD` 行，并修复或删除入站链接。不要检查、校验或修复归档记录向外的链接。
+
+用 `pnpm run verify-archived-agent-notes --write` 追加新的制品哈希。常规校验会拒绝被改动或缺失的已封存制品、未知的类别目录以及非法的归档元数据。

.agents/notes/archived/manifest.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "files": {}
+}

.agents/notes/implemented/AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md — 已实施 Agent Note
+
+这些 Agent Note 描述已交付的决策。遵循根指令、[文档标准](../../../docs/AGENTS.md)与 [Agent Note 格式](../README.md#the-file-format)；`verify-agent-note-format` 门禁校验各生命周期专属的结构。
+
+<a id="keep-an-implemented-agent-note-current-with-what-actually-shipped"></a>
+
+## 让已实施的 Agent Note 与实际交付内容保持同步
+
+在改动路径、符号、默认值或机制的同一个变更中让它们保持最新。就地改写过时事实；不要追加变更历史。
+
+当一份已交付记录不太可能再指导未来工作时，把它归档，而不是继续维护它。
+
+<a id="this-is-not-a-license-to-rewrite-the-decision"></a>
+
+### 这不是重写*决策*的许可
+
+就地更新事实层面的实现。推翻决策或其依据需要新的 Agent Note 并互相链接；只有通过 [Agent Note 规则](../README.md)中的合并规则，才能删除被完全取代的旧记录。

.agents/notes/implemented/process/2026-10-31-duplication-gate.md

@@ -0,0 +1,46 @@
+# Agent Note: 重复代码门禁
+
+Status: implemented
+
+<a id="problem"></a>
+
+## Problem
+
+`src/` 下的重复片段没有可执行的判定。评审者只能凭印象指出相似代码，同一处重复是否已存在、新增了多少，都没有稳定的答案；重构或搬移文件后，更难分辨重复是变多还是变少。
+
+<a id="decision"></a>
+
+## Decision
+
+`scripts/verify-duplication.ts` 用 jscpd 扫描 `src/`，把结果与 `duplication-baseline.json` 逐条比对，出现基线之外的克隆即以退出码 1 失败。门禁注册在 `pnpm run verify-all` 的注册表里，与文档门禁同一入口。
+
+- **指纹**由文件对、片段行数与片段内容摘要构成，不含行号。文件对按字典序拼接，两侧片段摘要也按字节序拼接，因此指纹与 A/B 归属无关，无关改动不会让基线失效。
+- **片段摘要**先归一化行尾再计算，同一片段在 CRLF 与 LF 检出上得到同一指纹。
+- **行数**取两侧跨度的较小值并取绝对值，jscpd 对跨嵌套结构的克隆会给出两端倒置的行号。
+- **比对按出现次数**而非存在与否。jscpd 把一处重复按相邻窗口拆成多条克隆，只比对存在与否会让基线随首处重复的克隆条数变化而误判。
+- **扫描格式**同时列 `typescript` 与 `tsx`。`.tsx` 不属于 `typescript` 格式，只列前者时组件文件整体不参与比对。
+- **基线只允许调低。** 无法消除的重复用 `pnpm run verify-duplication -- --update` 调高，并在提交信息里说明理由；改扫描参数会让既有基线整体失效，脚本遇到参数不符即失败并要求重写。
+
+<a id="baseline-state"></a>
+
+## 基线现状
+
+基线为空，`src/` 当前没有任何达到阈值的重复，门禁在 `verify-all` 中通过。新增重复会直接失败，没有可落进去的既有指纹。
+
+<a id="alternatives-considered"></a>
+
+## Alternatives considered
+
+**按百分比阈值判定。** 克隆占比随文件量变化而漂移，一处真实的重复可能被总量稀释到阈值以下；阈值本身也没有可复核的来源。
+
+**只列 `typescript` 格式。** 少配一项就少覆盖全部组件文件，门禁对 `.tsx` 静默失明，且不产生任何提示。
+
+**把基线一次性冻结成引入时的 29 处重复。** 门禁立刻变绿，但 29 处重复同时被登记为可接受，后续新增的重复只要落在这些指纹里就无人追问。
+
+<a id="consequences"></a>
+
+## Consequences
+
+门禁需要 `jscpd` 作为开发依赖，扫描 `src/` 全量，随文件数增长而变慢。
+
+基线为空时，任何一处新增重复都会失败且必须就地消除：这是最严格的状态，也让 `--update` 的正当用途只剩"确认无法消除后冻结残余"。

.agents/skills/agent-experience/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: agent-experience
+description: 用于编写或修改面向模型的工具定义（名称、描述、参数 schema，或它在系统提示词中的章节），以及设计技能、上下文加载或多步工作流时，使信息可被发现并高效使用上下文。
+---
+
+- **从最小上下文开始：** 先暴露目的、可用操作与约束，需要时再加载详细指令。
+- **让发现路径显式：** 每个延后加载的资源都要有明确描述，以及可靠获取它的方式。
+- **让关键约束可见：** 权限、破坏性影响与必需的校验应出现在相关操作之前。
+- **优先有界输出：** 返回简洁结果，并附上可用于取回细节的标识符或路径；不要倾倒完整日志或文档。
+- **利用就近性：** 在操作结果中附带有限量的、可能需要的相邻上下文，例如返回帖子回复时带上几条前置消息。显式标注省略与截断，并给出获取更多内容的方式。
+- **评估总工作量：** 节省上下文只有在不引发更多搜索、重复读取或错误时才有价值。
+
+<a id="tool-definitions"></a>
+
+## 工具定义
+
+- **删除显然的约束。** 省略模型能从调用结果中学到的规则，例如文件不存在导致读取失败，或发送失败未送达。
+- **描述行为，而非实现。** 说明工具做什么、返回什么；省略内部机制、模型在结果中看到的输出标记，以及强制执行细节。
+- **把参数规则放在参数上。** 默认值、取值范围、配对关系与何时设置的规则，属于该参数的描述或 schema；随配置变化的描述通常意味着变化的那部分应归属于某个参数。
+- **每个事实只说一次。** 不要在系统提示词章节里重复工具定义，不要在工具描述里重复参数描述，也不要在一个工具里重复另一个工具的规则。
+- **度量改动。** 比较工具定义改动前后的首轮提示词 token。