@namewta/speculo 0.1.8 → 0.1.10

package/template/skills/agents-md-builder/SKILL.md

@@ -0,0 +1,117 @@
+---
+id: agents-md-builder
+type: skill
+name: AGENTS.md Builder
+description: 为任意项目扫描 manifest 目录、判定角色、收集证据并生成极简 AGENTS.md 与 CLAUDE.md 重定向文件，形成完整父子导航树；当用户要求为项目生成/刷新 AGENTS.md、构建模块文档导航树、初始化 AI 代理可读的项目导读文档时使用。
+---
+
+# AGENTS.md Builder
+
+## 何时使用
+
+当用户要求为项目生成或维护 `AGENTS.md` 文档时使用。典型触发：
+
+- “为这个项目生成 AGENTS.md”
+- “构建项目的模块文档导航树”
+- “刷新所有模块的 AGENTS.md”
+- “为 src/ 下每个目录生成 AI 可读的导读文档”
+- “初始化项目的 agent 文档”
+
+## 设计理念
+
+每个 AGENTS.md 是一个**模块导读**，不是目录卡片。它回答：这个模块是什么、如何工作、从哪里开始读、看完之后去哪里。
+
+每一行必须通过**删除测试**：*“删除这一行会导致 AI 代理犯错吗？”* 如果不会，就删掉。
+
+## 输入
+
+- 项目根路径（默认当前工作目录）
+- 可选：目标子目录（只处理该子树）
+- 可选：manifest 类型过滤（只处理特定生态，如 `package.json`）
+- 可选：AGENTS.md 语言偏好（默认中文）
+
+本 skill 自带全部规范，**不外读仓库 `docs/`**。
+
+## 输出
+
+- 每个 manifest 目录的 `AGENTS.md`（模块导读）
+- 每个 manifest 目录的 `CLAUDE.md`（一行重定向至 AGENTS.md）
+- 生成清单与变更统计
+- 已清理的非法 AGENTS.md 清单（若有）
+
+## 执行步骤
+
+### 步骤 1：确定扫描范围
+
+1. 确认项目根路径。若用户未指定，使用当前工作目录。
+2. 若用户指定了目标子目录，仅处理该子树。
+3. 若用户指定了 manifest 类型过滤（如“只看 package.json”），仅匹配该类型。
+
+### 步骤 2：发现 manifest 目录
+
+1. 读取 `references/manifest-discovery.md`，确认支持的 manifest 文件列表与忽略目录。
+2. 从项目根递归扫描（排除忽略目录），找到所有含 manifest 文件的目录。
+3. 一个目录有多个 manifest 时，按优先级选主 manifest。
+4. 构建 manifest 目录的父子树：子目录的 manifest 继承最近的祖先 manifest 目录。
+5. 标记无 manifest 但已存在 AGENTS.md 的目录（待清理）。
+
+### 步骤 3：清理非法文档
+
+1. 无 manifest 目录下的 AGENTS.md → 列出并删除。
+2. 无 manifest 目录下的 CLAUDE.md → 列出并删除。
+
+### 步骤 4：判定角色
+
+1. 读取 `references/role-classification.md`。
+2. 按 6 种角色的优先级顺序，为每个 manifest 目录判定唯一角色。
+3. 命中即停止，不继续匹配。
+
+### 步骤 5：收集证据
+
+1. 读取 `references/evidence-collection.md`。
+2. 对每个 manifest 目录，按角色对应的取证顺序收集：
+   - Manifest 文件内容
+   - 关键目录结构
+   - 关键入口文件
+   - 依赖与消费关系
+   - 测试入口
+3. 遵循证据转写原则：结论必须被文件支撑，禁止虚构。
+
+### 步骤 6：生成 AGENTS.md
+
+1. 读取 `references/content-contract.md` 确认必填章节与禁止项。
+2. 读取 `references/writing-style.md` 确认排版、长度与语气。
+3. 读取 `references/templates/` 中对应角色的模板作为骨架。
+4. 自底向上（子 → 父）生成每个 AGENTS.md：
+   - 先写子级 → 父级的 Routing 可引用已确定的子级路径
+   - 每个 AGENTS.md 只负责自己所在模块
+   - 不重复父级或子级已说明的内容
+5. 每个 AGENTS.md 生成后执行删除测试：逐行检查是否冗余。
+
+### 步骤 7：生成 CLAUDE.md
+
+1. 读取 `references/claude-redirect.md`。
+2. 对每个已生成 AGENTS.md 的目录，生成 CLAUDE.md。
+3. CLAUDE.md 只有一行：`读取同层级的AGENTS.md文档。`
+
+### 步骤 8：报告
+
+1. 列出所有生成/更新的 AGENTS.md 路径。
+2. 列出所有生成的 CLAUDE.md 路径。
+3. 列出所有清理的非法文档路径。
+4. 按角色统计：根 x1、聚合 xN、可运行 xN、能力模块 xN、契约模块 xN。
+
+## 渐进披露
+
+- `references/manifest-discovery.md`：扫描项目确定 manifest 目录列表时读取。
+- `references/role-classification.md`：为每个 manifest 目录判定角色时读取。
+- `references/evidence-collection.md`：按角色收集证据时读取。
+- `references/content-contract.md`：生成 AGENTS.md 必填章节与禁止项时读取。
+- `references/claude-redirect.md`：生成 CLAUDE.md 重定向文件时读取。
+- `references/writing-style.md`：确认中文排版、长度密度、语气要求时读取。
+- `references/templates/repo-root-AGENTS.md`：角色为 `repo-root` 时读取。
+- `references/templates/aggregator-AGENTS.md`：角色为 `aggregator` 时读取。
+- `references/templates/runnable-app-AGENTS.md`：角色为 `runnable-app` 时读取。
+- `references/templates/capability-module-AGENTS.md`：角色为 `capability-module` 时读取。
+- `references/templates/contract-module-AGENTS.md`：角色为 `contract-module` 时读取。
+- `references/templates/scripts-docs-AGENTS.md`：角色为 `scripts-docs` 时读取。

package/template/skills/agents-md-builder/references/claude-redirect.md

@@ -0,0 +1,43 @@
+# CLAUDE.md Redirect Contract
+
+## 规则
+
+每个 manifest 目录的 `CLAUDE.md` **有且只有一行**：
+
+```
+读取同层级的AGENTS.md文档。
+```
+
+## 设计缘由
+
+- Claude Code 会读取 `CLAUDE.md` 获取项目/模块级指令。
+- 如果 `CLAUDE.md` 已有内容，不应覆盖。
+- 如果 `CLAUDE.md` 不存在，生成一行重定向。
+- 内容全部在 `AGENTS.md` 中，`CLAUDE.md` 只是入口指针。
+- 零维护成本：`AGENTS.md` 更新时不需要同步 `CLAUDE.md`。
+
+## 生成条件
+
+- 目录有 manifest 文件 → 生成 `CLAUDE.md`
+- 目录是 scripts-docs → 生成 `CLAUDE.md`
+- 目录已有 `CLAUDE.md` 且内容 > 1 行 → **不覆盖**，汇报用户
+- 目录已有 `CLAUDE.md` 且内容 = 1 行重定向 → 可覆盖（保持最新）
+
+## 不生成 CLAUDE.md 的目录
+
+- 无 manifest 目录 → 这些目录本就不该有 AGENTS.md
+- 忽略目录（`node_modules` 等）
+- `.git` 目录
+- 任何已在 `.gitignore` 中的目录
+
+## 文件格式
+
+```
+读取同层级的AGENTS.md文档。
+```
+
+- 无 frontmatter
+- 无标题
+- 无额外内容
+- 无换行（只有一行文本）
+- 文件以换行符结尾（POSIX 约定）

package/template/skills/agents-md-builder/references/content-contract.md

@@ -0,0 +1,213 @@
+# 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/agents-md-builder/references/evidence-collection.md

@@ -0,0 +1,184 @@
+# 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/agents-md-builder/references/manifest-discovery.md

@@ -0,0 +1,131 @@
+# Manifest Discovery
+
+## 核心规则
+
+目录中存在任一 manifest 文件 → **允许且必须有** `AGENTS.md`。
+目录中不存在任何 manifest 文件 → 已存在的 `AGENTS.md` 必须删除，**禁止创建**。
+
+## 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. **跳过忽略目录**：以下目录不进入、不扫描、不处理：
+   - `.git`、`node_modules`、`dist`、`target`、`.turbo`
+   - `coverage`、`__pycache__`、`.idea`、`.vscode`
+   - `build`、`out`、`.next`、`.nuxt`
+   - `vendor`、`bower_components`
+   - 任何在 `.gitignore` 中且非被跟踪的目录
+4. **检测 manifest**：对每个非忽略目录，检查是否存在任何 manifest 文件。
+5. **选择主 manifest**：按优先级选择。
+6. **应用过滤**：若用户指定了 `manifest_filter`，仅保留匹配该类型的目录。
+
+### 构建父子树
+
+1. 所有 manifest 目录按路径深度排序。
+2. 每个目录的**父 manifest 目录** = 路径上最近的祖先 manifest 目录。
+3. 项目根目录（`repo-root`）的父级为 `null`。
+
+## 特批例外：scripts-docs 目录
+
+某些目录虽无 manifest 但值得保留 AGENTS.md，需用户显式指定或按约定自动检测：
+
+### 自动检测条件
+
+- 目录名匹配 `script`、`scripts`、`docs`、`docker`、`deploy`
+- 且父目录是 manifest 目录
+- 且目录内不含任何 manifest 文件
+
+### 用户显式指定
+
+用户可在调用时声明额外的 scripts-docs 目录，格式：相对于项目根的路径。
+
+## 清理规则
+
+### 必须清理（删除 AGENTS.md 和 CLAUDE.md）
+
+- 任何无 manifest 目录下的 `AGENTS.md`
+- 任何无 manifest 目录下的 `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
+```
+
+若用户项目有特定忽略需求，以用户说明为准。