npm - @namewta/speculo - Versions diffs - 1.0.24 → 2.0.1 - Mend

@namewta/speculo 1.0.24 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1045) hide show

package/template/skills/docs-sync/assets/report-template.md DELETED Viewed

@@ -1,46 +0,0 @@
----
-command: docs-sync
-mode: <bootstrap|incremental|no-op>
-handbook_mode: <incremental|rebuild>
-scope: <workspace|multi-workflow|workflow>
-workflows: []
-changes: []
-generated_at: <ISO-8601>
----
-# Docs Sync Report
-## Git Range
-- From: `<FROM_SHA|null>`
-- To: `<INPUT_HEAD>`
-- Replay: `git diff <FROM_SHA>..<INPUT_HEAD>` 或 `bootstrap current facts`
-## Workspace Cleanup
-[记录 checkpoint commit、显式文件清单和运行前验证；无需 checkpoint 时写 `none`。]
-## Confirmed Scopes
-[记录全局 project targets、各 workflow project/state targets、scope revision 和本次确认变化。]
-## Evidence And Lifecycle
-| Target | Action | Evidence | Result |
-|---|---|---|---|
-## Workflow Sources
-[按 workflow 记录读取的 WORKFLOW/PERSISTENCE、archive、声明 store 和受保护候选；空集合写 `[]`。]
-## Synced Assets
-[列出实际新增、修改、合并或删除的文档与知识资产；no-op 写 `[]`。]
-## Verification
-[记录实际运行的命令、结果与未运行原因。]
-## State
-[记录全局 state 与 sidecar 的 schema、revision、pending 迁移项和原子写入结果。]

package/template/skills/docs-sync/references/agents/agent-writing.md DELETED Viewed

@@ -1,75 +0,0 @@
-# Agent 文档写作
-任何由 agent 消费的文档的撰写参考——一份 skill、一个 `AGENTS.md` / `CLAUDE.md`、一份通过指针到达的文档。包装形式不同，撰写之道相同：同样的杠杆让每一份文档都可预测——agent 每次都走相同的*流程*，而不是产出相同的输出。
-## 上下文指针
-**上下文指针（context pointer）** 是 agent 上下文中持有的一条引用，它指明某份上下文之外的资料，并编码了到达它的条件。一份 skill 的 description 是指针；`AGENTS.md` 中一行指向某文档的引用，也是同一个东西。决定 agent 何时——以及多可靠地——到达该资料的，是指针的*措辞*，而不是它的目标。一个措辞薄弱的指针指向一份必读资料，就是一个变异 bug：先打磨措辞；只有打磨失败时，才把资料内联进来。
-指针承担两项工作——说明资料是什么，并列出应触发到达它的**分支**（branch 是文档处理的某个不同情况，因此不同运行会走不同的路径）。一个始终加载的指针，每个字都要在每一轮对话中付出成本，所以它比正文更需要被毫不留情地精简：
-- **前置引导词**——触发工作是在指针上完成的。
-- **每个分支一个触发器。** 只是给同一分支换了个说法的同义词，等于把同一个分支写了两遍；把它们合并，只保留真正不同的分支。
-- **删掉正文已经承载的身份信息。**
-## 两种负载
-你添加的每份文档和每个指针，都要花掉两种预算之一：
-- **上下文负载（context load）**——始终加载的资料对 agent 窗口的代价：`AGENTS.md` 里的一行、一份 skill 描述、任何每轮对话都待在上下文里的东西，无论是否触发，都在消耗 token 和注意力。
-- **认知负载（cognitive load）**——对人类的代价：存在哪些文档、何时该去取哪一份。人类就是索引。这不是需要最小化的成本——它是人类主动性的价格；在人类判断重要的地方花它，在无关紧要的地方拿掉它。
-只通过指针到达的资料，免去了上下文负载，代价是指针自身的那一行；完全没有指针的资料，则完全压在认知负载上。
-## 信息层级
-一份文档由两种内容类型构成——**步骤**（agent 执行的有序操作）和**参考**（按需查阅的定义、规则、事实）——两者自由混合：全是步骤（一份菜谱）、全是参考（一次 review 的规则、本技能），或两者兼有。核心决策是每一块内容在**信息层级**上所处的位置，这是一把按 agent 需要资料的即时程度排序的梯子：
-1. **文件内步骤**——第一层级：agent 做什么，按顺序。
-2. **文件内参考**——按需查阅。它常常是一个合理扁平的并列集合（一次 review 的全部规则在同一条横档上）——这没什么不好，不是坏味道。
-3. **外置参考（disclosed reference）**——推到独立文件里，通过上下文指针到达，只在指针触发时加载。从同一文件夹的兄弟文件，一直到住在任何地方、任何文档都能指向的完全外部参考。
-推得太少，顶层会臃肿；推得太多，你会把 agent 真正需要的资料藏起来。这个张力就是全部决策所在。
-**渐进式披露（progressive disclosure）** 是沿梯子向下的移动——从主文件中移出、放到指针后面——让顶层保持可读。它首先不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：每个分支都要用到的内容内联保留，只有部分分支会碰到的内容推到指针后面。当一份文档有步骤时，本应披露的文件内参考会埋没这些步骤，让"照做"变成抛硬币——这不只是可读性杠杆，而是变异杠杆。
-**就近放置（co-location）** 是文件内部的伴侣：梯子决定一块内容*下探多深*，就近放置决定它落到那里后*旁边放着什么*。把一个概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样读到一部分时，相邻部分也随之而来。判断标准：文档读起来应该像专门写给 agent 的文档——归组的内容如此，散落的内容则不然。（它与重复不同：重复是在两个地方重述同一层含义；散落是把一层含义打碎到多处。）
-**臃肿（sprawl）** 是这里的失败模式：一份文档单纯地太长，即使每一行都是活的、独一无二的。注意力在过剩内容中变薄，而每一行额外的内容都是又多一条需要保持相关的东西。解药就是那把梯子：把参考披露到指针后面，并按分支或序列拆分，让每条路径只携带它需要的东西。
-## 步骤与完成标准
-每个步骤都以一个**完成标准（completion criterion）** 收尾——告诉 agent 工作已完成的条件。两个属性使它成为杠杆：
-- **清晰度**——agent 能否区分"完成"与"未完成"？一个模糊的边界（"已达成理解"）会招致**提前完成（premature completion）**：在步骤真正完成之前就结束它，注意力滑向*看起来完成了*。仍可见的后续步骤——**完成后的步骤（post-completion steps）**——提供拉力；标准的清晰度是阻力。按顺序防御：**先磨利边界**（局部且廉价）；只有当边界不可约地模糊*且*你观察到赶工行为时，才通过拆分序列隐藏后续步骤——而隐藏只在真正的上下文边界处有效（一次交接或一个 subagent 派遣；内联调用会让后续步骤留在上下文中，什么也清不掉）。
-- **要求强度（demand）**——它要求多少。"每个修改过的模型都被说明"逼出彻底的工作，而"生成一份变更清单"不会。要求强度驱动**苦功（legwork）**——agent 在工作内部做的挖掘，它藏在措辞里而不是写成独立步骤——并且它不绑定步骤："每条规则都适用"绑定一整个扁平的参考集合，正如"每个步骤都完成"绑定一条序列，这正是一份纯参考文档仍然带着穷尽性门槛的方式。
-最强的标准既可核查又穷尽。
-## 何时拆分
-把一份文档拆成两份，要花掉两种负载之一，所以只有在切口值得时才拆：
-- **按序列拆分**——拆分一段步骤序列，此时完成后的步骤会诱使 agent 赶工眼前的步骤。让它们不可见，会驱动当前任务上更多的苦功。当心反向情况：合并序列会让每个步骤都暴露在后续步骤面前，招致提前完成。
-## 引导词
-**引导词（leading word）** 是一个早已存在于模型预训练中的紧凑概念，agent 在运行文档时用它思考（_lesson_、_fog of war_、_tracer bullets_）。以 token 形式重复、永不用句子重述，它累积出一个分布式的定义，并以最少的 token 锚定一整个行为区域——通过征用模型已有的先验。自己造词也行，只要定义清楚，但一个生造的词征用不到任何先验——你在定义 token 上付出的，正是预训练词免费给予的；先用已有的词。
-它双重锚定。在正文里是*执行*：每次该词出现，agent 都伸手取同样的行为；在扁平参考内部，它把注意力聚焦到要找的一类事物上。在指针里是*调用*：当同一个词同时存在于你的 prompts、你的文档和你的代码库时，agent 会把这份共享语言与资料联系起来，更可靠地到达它。
-寻找用引导词重构的机会。一个在三个地方展开的三件套、一个花一句话指向同一个概念的指针——每一处都是渴望塌缩成单个 token 的段落：
-- "fast, deterministic, low-overhead" → _tight_（一个 _tight_ 循环）。
-- "a loop you believe in" → _red_——一个模糊的闸门变成二元的可观察状态（遇到 bug 循环变 _red_，或不变）。
-你赢两次：更少的 token，以及一个更锋利的钩子让 agent 挂上它的思考。假设每份文档都携带着引导词可以退役的重述——去把它们找出来。
-**否定式表述（negation）** 是这个杠杆旁边的失败模式：用禁止来引导，会把被禁止的行为拖进上下文，让它变得*更容易*被激活，而不是更难。_不要想大象_，然后脑子里就全是大象；否定是一个脆弱的修饰符，会被强激活的概念碾过去，于是禁令有一半读起来像是在指示去做那件事。用**肯定式**提示——陈述目标行为（"写一行注释"），让被禁止的行为永远不被说出来。只有当你实在无法用肯定句式表达时，一条禁令才配占有一席之地；即使如此，也要配上肯定的目标，让注意力落在"做什么"上。
-## 精简
-- 让每个含义都有**单一事实来源（single source of truth）**：一个权威的位置，这样改变行为就是改一处。**重复（duplication）**——同一含义出现在多个地方——耗费维护成本和 token，并把一个含义在梯子上的显著性抬到超过它实际等级的高度。（它是引导词的意外反面：引导词是有意重复一个 token，从来不是重复含义。）
-- **环境（environment）** 也是事实来源——`package.json` 脚本、配置文件、目录布局、`--help` 输出——而重述环境的文档就是一份**缓存（cache）**：一次查询的副本，只有当查询本身昂贵时才值得负担这份负载。只缓存 agent 无法通过查找得到的东西：不成文的约定、选择背后的原因、任何配置文件都不会招认的坑。把"一个文件一条命令"式的查找留给环境，在那里它们不会过期。
-- 逐行检查**相关性（relevance）**：它是否仍然与文档所做的事有关？一行内容失去相关性，要么因为从未作用于任务（纯叙述，或一个本应披露的分支），要么因为行为或世界变化而过期。更短的文档更容易保持相关。没有精简纪律，默认的归宿是**沉积（sediment）**：一层层过期的内容沉淀下来——因为添加感觉安全、删除感觉冒险——直到你必须钻穿它们才能找到仍然活着的东西。
-- 逐句猎杀**无效指令（no-ops）**：一句模型本来就默认遵守的指令，花了负载却没说出任何东西。判断标准——它是否改变了相对默认的行为？——是模型相对的，不是读者相对的：两个人争论一句无效指令，争论的是默认是什么，而且要靠运行文档来裁决，不是靠辩论。当一句指令不合格时，删除整句，而不是从里面删词。这个判断标准也给引导词打分：一个弱到打不过默认的词（在 agent 已经够"be thorough"的地方写*要彻底*）就是无效指令，修法是换一个更强的词（*毫不留情*），而不是换一种技巧。

package/template/skills/docs-sync/references/agents/claude-redirect.md DELETED Viewed

@@ -1,39 +0,0 @@
-# CLAUDE.md Redirect Contract
-## 规则
-需要 Claude 适配且有独立 AGENTS 作用域的目录使用轻量导入文件，新增或明确归工具所有的 `CLAUDE.md` 内容为：
-```
-# CLAUDE.md
-@AGENTS.md
-```
-此格式与 [`../agents-contract.md`](../agents-contract.md) 的规定一致（该契约为权威）：`AGENTS.md` 始终是唯一的权威代理手册，`CLAUDE.md` 永远只是宿主导入入口。
-## 设计缘由
-- Claude Code 会读取 `CLAUDE.md` 获取项目/模块级指令。
-- 内容全部在 `AGENTS.md` 中，`CLAUDE.md` 只是入口指针。
-- 零维护成本：`AGENTS.md` 更新时不需要同步 `CLAUDE.md`。
-## 生成条件
-- 目录有独立手册且需要 Claude 适配 → 生成 `CLAUDE.md`
-- scripts-docs 同样按独立作用域和 Claude 适配需求判断，不无条件生成
-- 目录已有多行非重定向 `CLAUDE.md` → 向用户确认后改写为重定向，原内容全量迁移到 `AGENTS.md`（处置与 agents-contract 一致）
-- 目录已有精确匹配的工具生成桥接 → 可更新导入；用户修改或 owner 不明时保留并报告差异
-## 不生成 CLAUDE.md 的目录
-- 没有独立作用域约束且无需手册的目录
-- 忽略目录（`node_modules` 等）
-- `.git` 目录
-- 任何已在 `.gitignore` 中的目录
-## 文件格式
-- 三行：`# CLAUDE.md` 标题、空行、@AGENTS.md 导入
-- 无 frontmatter、无额外内容
-- 文件以换行符结尾（POSIX 约定）

package/template/skills/docs-sync/references/agents/content-contract.md DELETED Viewed

@@ -1,213 +0,0 @@
-# Content Contract
-所有 AGENTS.md 都必须写成**模块导读**，不能退化成目录卡片。每个章节都要回答明确问题。
-## 必填章节
-每个 AGENTS.md 必须包含以下章节。章节名称保留英文，正文使用中文。
-### 1. `Scope`
-回答：
-- 这个文件覆盖哪些目录？
-- 哪些更深层 manifest 会接管说明？
-- 哪些内容明确不覆盖？
-写法：2-4 句话，边界清晰。
-### 2. `Module Positioning`
-回答：
-- 当前目录是什么角色？
-- 它在整个项目中承担什么位置？
-- 为什么它存在？
-写法：标记角色（如 `capability-module`），点出它在项目分层中的坐标。
-### 3. `Directory Structure`
-回答：
-- 直接子目录有哪些？各自承担什么？
-- 关键文件有哪些？它们为什么重要？
-- 主要实现区在哪？测试区在哪？
-写法：只列 5-10 项对排查问题有用的目录和文件，不做全量目录树。
-### 4. `Responsibilities`
-回答：
-- 当前模块负责什么？
-- 明确不负责什么？
-写法：用列表承载 3-6 条职责。负面影响（不负责什么）同样重要。
-### 5. `Core Logic`
-回答：
-- 模块如何工作？
-- 关键装配顺序、处理链路或数据流是什么？
-- 它的核心机制是什么？
-写法：3-6 句话解释主干逻辑。不要展开每个文件的细节。
-### 6. `Key Entry Points`
-回答：
-- 先看哪些具体文件？
-- 从哪个目录开始依次下钻？
-写法：**必须点名具体文件、类、目录或测试入口**。禁止只写 `src/`、`api/`、`controller/` 这类空泛词。
-好例子：
-- `src/main.ts` — 应用启动入口
-- `src/router/index.ts` — 路由注册
-- `src/api/user.ts` — 用户相关接口封装
-- `tests/user.spec.ts` — 用户模块测试
-差例子：
-- `src/` — 主实现
-- `api/` — 接口层
-### 7. `Usage And Change Notes`
-回答：
-- 典型使用入口是什么？
-- 修改时优先检查哪些配置、依赖或调用链？
-- 最容易误改的边界在哪里？
-写法：2-4 条高信息量可执行提醒。禁止写成“修改时注意兼容性”“按需查看相关代码”这类空话。
-好例子：
-- “新增接口时先确认 controller 所属归档单元，再同步检查 bo/vo 和前端接口契约。”
-- “改请求层时先检查 `packages/core`、环境变量和下载链路。”
-差例子：
-- “修改时注意兼容性。”
-- “需要时查看相关代码。”
-### 8. `Dependencies And Collaboration`
-回答：
-- 直接依赖了哪些项目/仓库内部模块？
-- 被哪些兄弟模块消费？
-- 模块间如何协作？
-写法：列表形式。区分“我依赖谁”和“谁依赖我”。
-### 9. `Investigation Rule`
-回答：
-- 当本文件不够时，按什么顺序继续读源码？
-- 文档与代码冲突时怎么办？
-写法：**必须写成可执行顺序**。每一步点名具体文件或目录。
-好例子：
-```
-1. 先读 pom.xml 了解依赖和模块声明。
-2. 再读 src/main/java/.../Application.java 了解启动装配。
-3. 然后按 controller → service → domain → mapper 顺序下钻。
-4. 仍不够时，读 src/test/ 了解预期行为。
-5. 文档与代码冲突时以代码事实为准。
-```
-差例子：
-- “需要时查看源码。”
-- “先看 controller、service、domain。”
-### 10. `Core Commands`
-回答：
-- 当前模块最常用的构建/测试/运行命令是什么？
-- 哪些命令是非标准的、AGENTS 无法从 manifest 推断的？
-写法：只写 AGENTS 猜不到的命令。从 `package.json` scripts 或 `pom.xml` 插件显而易见的命令不用写。
-### 11. `Verification`
-回答：
-- 最小可执行验证是什么？
-- 如何确认模块正常工作？
-写法：1-2 条具体命令。
-### 12. `Routing`
-回答：
-- 上级 manifest 在哪？
-- 子级 manifest 有哪些？
-写法：
-```
-- 上级：[../AGENTS.md](../AGENTS.md)
-- 子级：
-  - [子模块A](./子模块A/AGENTS.md) — 一句话定位
-  - [子模块B](./子模块B/AGENTS.md) — 一句话定位
-```
-每个子级链接后附一句话定位。`repo-root` 无上级，不写上级行。
-### 13. `References`
-回答：
-- 关键 manifest、配置、源码入口、测试入口在哪？
-写法：用相对路径列出 3-8 个关键引用。只列对 AGENTS 有用的，不做全文索引。
-## 禁止项
-以下内容**一律禁止**出现在 AGENTS.md 中：
-| 禁止 | 原因 |
-|------|------|
-| 逐文件的结构列表 | AGENTS 可通过阅读代码库发现 |
-| 标准语言约定 | AGENTS 已知（如“React 是声明式 UI 库”） |
-| 通用建议 | “编写干净的代码”“处理错误”等无操作价值 |
-| 从 manifest 显而易见的命令 | 如 `npm test`、`mvn clean install` |
-| 经常变化的信息 | 版本号、日期、人员名单——用路径引用源文件 |
-| 长教程或演练 | 移到 references 中 |
-| `Key Entry Points` 中只写目录名 | 必须点名具体文件、类 |
-| `Usage And Change Notes` 中的空话 | 必须可执行 |
-| `Investigation Rule` 中的空话 | 必须有具体文件和顺序 |
-| 复制大段源码或配置全文 | 引用路径即可 |
-| 宣传性语言 | “业界领先的”“强大的”“优雅的” |
-## 角色额外要求
-### `repo-root`
-- 解释顶层分层理由，不只列模块名
-- 写清“从根级定位问题后，下一步怎么进入子模块”
-- `Usage And Change Notes` 要提醒：根级改动容易联动 workspace 配置、顶层 scripts 和索引
-### `scripts-docs`
-- 说明独有规则的实际作用域；没有 manifest 时不虚构模块信息
-- 概括各类子树各自承载什么
-- 区分“可直接执行的脚本”“SQL 资产”“配置模板”“运行时数据目录”
-- 明确“只到根目录这一层”，不为子目录生成子级文档
-- `Usage And Change Notes` 必须写清：哪些可运行、哪些只是资产索引
-### `aggregator`
-- 解释当前聚合为什么存在
-- 给出子模块的分组逻辑，不只是列模块名
-- 写清“哪些问题必须进入哪个子模块继续调查”
-### `runnable-app`
-- 写清启动入口、运行时装配
-- 写清内部依赖模块如何接入
-- `Usage And Change Notes` 要提醒：运行时改动应先看哪些入口、哪些配置联动最易漏
-### `capability-module`
-- 写清导出面、核心分层
-- 写清内部依赖与上游消费方
-- `Usage And Change Notes` 要提醒：新增接口/类型/配置时优先检查的层次
-### `contract-module`
-- 写清约束了什么、被谁消费
-- 没有 `src/` 时显式说明这是约束层
-- `Usage And Change Notes` 要提醒：改约束会影响哪些消费方

package/template/skills/docs-sync/references/agents/evidence-collection.md DELETED Viewed

@@ -1,184 +0,0 @@
-# Evidence Collection
-## 原则
-写 AGENTS.md 之前，先收集证据，再落结论。不允许在没有文件支撑的情况下写结论。
-**核心铁律**：
-- 结论必须能被文件直接支撑
-- 允许总结实现机制，禁止虚构业务语义
-- 当证据不足以支撑强结论时，退回到“入口 + 调查顺序”的写法
-## 通用证据收集顺序
-适用于所有角色，在角色专属取证之前执行。
-### 1. Manifest 文件
-读取主 manifest 文件的以下内容：
-| 生态 | 关键字段 |
-|------|---------|
-| Node.js / TypeScript | `name`、`description`、`scripts`、`dependencies`、`devDependencies`、`main`、`exports`、`bin`、`workspaces` |
-| Java / Maven | `artifactId`、`description`、`packaging`、`<modules>`、`<dependencies>`、插件配置 |
-| Rust | `[package]` name/description、`[dependencies]`、`[[bin]]`、`[lib]`、`[workspace]` |
-| Go | `module` 路径、`require`/`replace` 指令 |
-| Python | `[project]` name/description、`[project.scripts]`、`[project.dependencies]` |
-| CMake | `project()`、`add_executable()`、`add_library()`、`target_link_libraries()` |
-| 通用 | 任何描述当前模块定位、边界和依赖的声明 |
-### 2. 关键目录结构
-列出直接子目录，跳过忽略目录。粗略统计：
-- 源码主目录（如 `src/`、`lib/`、`app/`）
-- 资源/配置目录（如 `resources/`、`config/`、`assets/`）
-- 测试目录（如 `test/`、`tests/`、`spec/`、`__tests__/`）
-- 文档目录（如 `docs/`）
-不超过 10 项。不要穷举，只列对定位问题有用的。
-### 3. 关键入口文件
-至少找到 3-6 个最能代表模块职责的文件：
-- 入口/启动文件
-- 导出索引文件
-- 核心业务/能力文件
-- 关键配置文件
-- 测试入口
-### 4. 依赖与消费关系
-- 项目/仓库内部依赖了哪些兄弟模块
-- 被哪些兄弟模块依赖（反向消费方）
-- 若有外部关键依赖需要说明，只提 AGENTS 无法从 manifest 推断的
-### 5. 测试入口
-- 测试目录路径
-- 测试运行命令（如果非标准）
-- 测试覆盖范围简述
-## 各角色专属取证重点
-### `repo-root`
-**优先读**：
-- 顶层 manifest 的 workspace/multi-module 声明
-- 顶层直接子目录的 manifest 清单
-- 根级 CI/CD 配置（如 `.github/workflows/`）
-- 根级工具链配置（如 `turbo.json`、`nx.json`、`lerna.json`）
-**重点关注**：
-- 顶层分层理由：为什么这样拆 apps/libs/modules
-- 根级命令与任务编排
-- 哪些是聚合层，哪些是叶子层
-### `scripts-docs`
-**优先读**：
-- 脚本根目录下的直接子目录
-- 根级读写脚本/管理脚本
-- 配置文件与模板
-**至少抽看**：
-- 每个一级子目录的 1-2 个代表性文件
-- 明确哪些子目录是运行时数据、初始化脚本、人工样例或环境配置
-**重点关注**：
-- 五类子树覆盖：脚本、SQL/迁移、配置、任务清单、样例数据
-- 不需要穷举所有文件，但必须覆盖各类子树的职责和继续下钻入口
-### `aggregator`
-**优先读**：
-- 父 manifest 的子模块声明（`<modules>`、`workspaces`、`members`）
-- 子模块名称列表与各自 manifest 的关键字段
-**至少抽看**：
-- 1-2 个代表性子模块的 manifest 或源码入口
-- 子模块之间的分组逻辑（BOM 组 / 核心能力组 / 应用组 / 业务域组）
-**重点关注**：
-- 为什么需要这个聚合层
-- 子模块的分组逻辑，避免聚合描述空泛
-- 不展开子模块实现细节
-### `runnable-app`
-**优先读**：
-- 启动入口文件（如 `main.ts`、`Application.java`、`main.rs`）
-- 路由/控制器入口
-- 中间件/插件装配
-- 运行时配置（如 `application.yml`、`.env`、`vite.config.ts`）
-**至少抽看**：
-- 请求/响应链路：路由 → 控制器 → 服务 → 数据层
-- store / 状态管理入口（前端）
-- 核心业务子树
-**重点关注**：
-- 启动链路与运行时装配方式
-- 内部依赖模块如何组装进应用
-- 不要把应用写成纯目录列表
-### `capability-module`
-**优先读**：
-- 导出入口文件（如 `src/index.ts`、`mod.rs`、`__init__.py`）
-- 主包路径下的核心分层目录
-**至少抽看**：
-- 最能代表模块职责的 3-6 个关键文件或子目录
-- 如果存在明确的请求处理链路（controller → service → domain → mapper），写成排查路径
-- 如果更偏框架扩展，重点看 config / plugin / utils / factory
-**重点关注**：
-- 它是能力模块、业务模块还是集成模块
-- 被哪些兄弟模块消费
-- 上下游依赖链
-### `contract-module`
-**优先读**：
-- manifest 的依赖管理、导出声明
-- 若存在类型文件/配置文件的目录
-**重点关注**：
-- 约束了什么：版本对齐、依赖传递、配置契约、类型契约、接口契约
-- 由谁引用、为什么需要独立出来
-- 没有 `src/` 时要显式说明这是约束层
-**不需要**：
-- 查运行时代码（它没有）
-- 虚构消费链路
-## 证据记录格式
-收集证据时，在心里或临时笔记中这样组织：
-```
-[目录路径] <角色>
-  Manifest: <关键字段摘要>
-  关键目录: <3-6个>
-  入口文件: <3-6个>
-  内部依赖: <列表>
-  消费方: <列表>
-  测试: <目录或入口>
-  定位: <一句话模块定位>
-  核心逻辑: <2-3句话>
-```
-这是内部工作格式，不写入 AGENTS.md。目的是确保有足够证据支撑每个章节。
-## 证据不足时的处理
-当某个章节找不到足够证据时：
-1. **Module Positioning**：退回到“目录位置 + manifest 声明”，不臆断定位。
-2. **Core Logic**：退回到“入口文件 + 阅读顺序”，不虚构工作流。
-3. **Dependencies**：只写 manifest 中直接看到的依赖，不推断传递依赖。
-4. **Usage Notes**：只写可直接验证的提醒，不写猜测。
-总之：宁愿留白，不造假。

package/template/skills/docs-sync/references/agents/manifest-discovery.md DELETED Viewed

@@ -1,126 +0,0 @@
-# Manifest Discovery
-## 核心规则
-按真实作用域和独有约束决定是否需要手册；manifest 是定位证据，不是唯一许可或强制创建条件。没有 manifest 不能成为删除用户手册的理由。
-## Manifest 文件注册表
-一个目录可能同时存在多个 manifest 文件。按优先级选择**主 manifest**，其余作为辅助参考。
-| 优先级 | 生态 | Manifest 文件 |
-|--------|------|--------------|
-| 1 | Node.js / TypeScript | `package.json` |
-| 1 | Java / Maven | `pom.xml` |
-| 2 | Java / Gradle | `build.gradle`、`build.gradle.kts` |
-| 1 | Rust | `Cargo.toml` |
-| 1 | Go | `go.mod` |
-| 1 | Python | `pyproject.toml` |
-| 2 | Python（旧） | `setup.py`、`setup.cfg` |
-| 1 | C / C++ / CMake | `CMakeLists.txt` |
-| 3 | C / C++ / 通用 | `Makefile` |
-| 1 | Ruby | `Gemfile` |
-| 1 | Elixir | `mix.exs` |
-| 1 | Dart / Flutter | `pubspec.yaml` |
-| 1 | PHP | `composer.json` |
-| 1 | Zig | `build.zig` |
-| 1 | .NET | `*.csproj`、`*.fsproj` |
-| 1 | Swift | `Package.swift` |
-| 1 | Haskell | `*.cabal`、`stack.yaml` |
-| 1 | Nix | `flake.nix`、`default.nix` |
-### 多 manifest 选择规则
-同一目录存在多个 manifest 时，按优先级选主 manifest：
-```
-目录有 package.json + Makefile → 主 manifest = package.json（优先级1 > 3）
-目录有 pom.xml + build.gradle → 主 manifest = pom.xml（优先级1 > 2）
-目录有 CMakeLists.txt + Makefile → 主 manifest = CMakeLists.txt（优先级1 > 3）
-```
-主 manifest 决定角色判定的主要依据；辅助 manifest 在证据收集时补充参考。
-## 扫描算法
-### 输入
-- `root`: 项目根目录
-- `target_subdir`（可选）：仅扫描该子树
-- `manifest_filter`（可选）：仅匹配指定 manifest 文件类型
-### 扫描步骤
-1. **确定扫描起点**：`scan_root = root / target_subdir`，若未指定则为 `root`。
-2. **递归遍历**：从 `scan_root` 递归遍历所有子目录。
-3. **跳过忽略目录**：见文末「忽略目录完整清单」；另跳过任何在 `.gitignore` 中且非被跟踪的目录。
-4. **检测 manifest**：对每个非忽略目录，检查是否存在任何 manifest 文件。
-5. **选择主 manifest**：按优先级选择。
-6. **应用过滤**：若用户指定了 `manifest_filter`，仅保留匹配该类型的目录。
-7. **补充作用域边界**：检查已定位的嵌套手册、独立测试/生成物约束、部署与安全边界；即使无 manifest，有真实独有约束仍可纳入。候选目录只有在减少歧义或提供独有规则时才生成手册，不按 manifest 数量机械铺开。
-### 构建父子树
-1. 所有 manifest 目录按路径深度排序。
-2. 每个目录的**父 manifest 目录** = 路径上最近的祖先 manifest 目录。
-3. 项目根目录（`repo-root`）的父级为 `null`。
-## 无 manifest 的作用域
-scripts-docs 是常见例子，不是唯一合法例外；按实际规则作用域保留或创建手册，不需要仅因无 manifest 另设批准门：
-### 自动检测条件
-- 目录名匹配 `script`、`scripts`、`docs`、`docker`、`deploy`
-- 且父目录是 manifest 目录
-- 且目录内不含任何 manifest 文件
-### 用户显式指定
-用户可在调用时声明额外的 scripts-docs 目录，格式：相对于项目根的路径。
-## 清理规则
-### 仅提出清理候选（按已确认范围和所有权执行）
-- 已证实过期且不再有独有作用域约束的 AGENTS.md
-- 对应手册已确认移除且由调用方拥有的 CLAUDE.md
-- 忽略目录（`node_modules` 等）下的任何 `AGENTS.md` 或 `CLAUDE.md`
-### 不清理
-- 有 manifest 目录下的 `AGENTS.md`（将被刷新）
-- 有 manifest 目录下的 `CLAUDE.md`（将被刷新）
-- 用户显式指定的 scripts-docs 目录下的文档
-### 清理后处理
-- 删除文档后若目录变空且需要保留，使用 `.gitkeep` 留存。
-- 不要用 README 或 AGENTS 占位。
-## 忽略目录完整清单
-```
-.git
-node_modules
-dist
-target
-.turbo
-coverage
-__pycache__
-.idea
-.vscode
-build
-out
-.next
-.nuxt
-vendor
-bower_components
-.cache
-*.egg-info
-.venv
-venv
-env
-```
-若用户项目有特定忽略需求，以用户说明为准。