fusion-package-scribe

Package Scribe

实验性说明

此技能处于实验阶段，尚未稳定。其行为、结构和输出可能会随版本变化。

使用时机

当你需要系统地为 TypeScript 包添加或改进文档时使用——无论是全面检查整个 monorepo，还是仅处理单个包。

常见触发条件：

• “为所有包编写文档”
• “改进 packages/utils/observable 的文档”
• “为此包的所有公开导出添加 TSDoc”
• “重写此包的 README”
• “对 monorepo 进行一轮文档检查”
• “检查此包的 TSDoc 质量”

隐式触发条件：

• 某个包有缺少 TSDoc 或仅包含占位内容的公开导出
• 某个包的 README 已过时、内容不一致，或缺少标准章节
• 计划对多个包进行文档检查

不适用场景

• 修改运行时代码（仅处理文档注释和 README 文件）
• 生成 API 参考网站或 TypeDoc 输出
• 非 TypeScript 语言（初始范围仅包括 TS/TSX）
• 自动合并 PR 或绕过审查工作流
• 扫描安全漏洞或分析性能
• 替代现有基于 CI 的文档生成流水线

必需输入

如果缺少必需输入或输入含糊不清，请先询问再继续。

• 范围：monorepo 根路径或特定包路径
• 模式：single（单个包）或 sweep（多个包）

条件输入

• 包筛选器：处理部分包时使用的 glob 模式或列表
• README 模板路径：不使用内置默认模板时提供的仓库专用模板（例如位于 .github/instructions/ 下）
• 跟踪 issue：用于生命周期更新（分配、更新状态、关闭）的 issue 编号
• 提交规范：仓库专用的 Conventional Commit 格式（默认为 docs(<package>): ）
• 批次大小：sweep 模式下每批处理的包数（默认为 5）

默认值

• 模式：single（仅提供一个包路径时）
• 提交前缀：docs(<package-name>):
• 批次大小：每个 sweep 批次 5 个包
• README 结构：来自 references/readme-template.md 的内置模板
• 审查委员会：已启用（每个包处理完后运行）

优先级与规范发现

此技能会发现并遵循目标仓库自身的规范：

1. 仓库说明 — .github/instructions/ 下适用的文件、CONTRIBUTING.md、contribute/
2. 工具配置 — tsconfig.json、biome.json、.editorconfig
3. 配套技能 — fusion-code-conventions（适用于 TSDoc 规则、命名规范和意图质量；如果已安装）
4. 内置默认值 — references/tsdoc-checklist.md 和 references/readme-template.md

仓库级规范始终优先。如果仓库没有相关规范，则采用内置默认值。

Agent 模式

Agent	角色	启用场景
agents/orchestrator.agent.md	批次协调员	Sweep 模式——规划批次、管理 token 预算、跟踪进度
agents/documenter.agent.md	单包文档撰写者	每个包——扫描 API 范围、生成 TSDoc、重写 README
agents/reviewer.agent.md	审查委员会	每个包处理完后——验证意图、可理解性和检索适用性

在单 Agent 运行环境中，三个角色会依次以内联方式运行。

说明

第 1 步 — 发现仓库规范

生成任何文档之前：

1. 搜索仓库级文档说明：
   • .github/instructions/ 下适用的文件
   • CONTRIBUTING.md、contribute/
2. 阅读 tsconfig.json，了解模块结构、路径别名和严格模式设置
3. 阅读 biome.json 或同类 Linter 配置，了解代码风格要求
4. 检查是否有 fusion-code-conventions 可用——如果有，请遵循其 references/typescript.conventions.md 中的 TSDoc 规则
5. 如果不存在仓库级规范，则使用 references/tsdoc-checklist.md 作为质量基准

步骤 2 — 发现软件包

1. 对于单软件包模式：验证提供的软件包路径是否存在，并且其中包含 TypeScript 源文件
2. 对于扫描模式：
   • 读取根目录的 package.json 或工作区配置（pnpm-workspace.yaml、lerna.json、turbo.json），查找所有软件包
   • 根据提供的 glob/列表进行筛选
   • 按估算大小（文件数）对软件包排序，以便规划批次
   • 将发现摘要写入 .tmp/scribe-discovery-<context>.md

步骤 3 — 规划执行（仅扫描模式）

激活 agents/orchestrator.agent.md（或内联运行）：

1. 按配置的批次大小将软件包分组
2. 对批次排序：先处理较小的软件包（源文件较少），以尽早提高吞吐量
3. 估算每个软件包的 token 预算：每个源文件约 100 个 token 用于阅读，每个导出约 200 个 token 用于生成 TSDoc
4. 如果单个软件包超过估算上下文窗口的 60%，则标记为需要特殊处理（先处理 barrel 导出，延后处理内部模块）
5. 将执行计划写入 .tmp/scribe-plan-<context>.md

步骤 4 — 处理每个软件包

为每个软件包激活 agents/documenter.agent.md（或内联运行）：

4a — 扫描公共 API

1. 查找 barrel 导出文件（index.ts、index.tsx 或 package.json 中的 main 字段）
2. 跟踪所有重新导出，以识别完整的公共 API
3. 对导出内容分类：函数、类、类型/接口、常量、钩子、枚举
4. 确定优先级：先处理 barrel 导出，然后处理直接公共导出，最后处理内部使用但对外导出的项目

4b — 生成或改进 TSDoc

对于每个公共导出：

1. 阅读现有实现，了解其意图、参数、返回值、错误路径和副作用
2. 检查现有 TSDoc；如有，则改进而不是替换
3. 应用 TSDoc 检查清单（仓库规范或 references/tsdoc-checklist.md）：
   • 摘要行：说明为什么以及它解决了什么问题，而不只是说明它做什么
   • 每个参数都使用 @param，并提供有意义的描述
   • 每个非 void 函数都使用 @returns
   • 每个泛型类型参数都使用 @template
   • 对有意义的错误路径使用 @throws
   • 对面向用户且非简单的公共 API 使用 @example
   • 适用时使用 @deprecated 并提供替代方案指引
4. 标记并改写“名称复述”模式（例如 /** Gets the value. */ getValue()）
5. 不要修改运行时代码——仅修改文档注释

4c — 重写或改进 README

1. 阅读现有 README（如有），保留有价值的内容
2. 按照仓库说明或 references/readme-template.md 中的 README 结构编写：
   • 软件包名称和描述
   • 功能/主要导出
   • 安装
   • 带代码示例的用法
   • API 参考（通过链接或内联文档概述主要导出）
   • 配置（如适用）
3. 确保 README 能帮助首次发现该软件包的开发者
4. 优化检索效果：使用清晰的标题、包含关键词的描述和具体示例

步骤 5 — 审查评审

在处理完每个软件包后，激活 agents/reviewer.agent.md（或内联运行）：

1. 意图提取 — TSDoc 是否准确描述了代码的作用和原因？标记任何只是复述函数/类型名称的注释。
2. 代码理解 — 是否解释了复杂算法、状态机或副作用？新开发者能否仅凭文档理解代码？
3. 面向用户的质量 — README 是否对首次发现该软件包的用户有帮助？示例是否可运行？
4. 检索适用性 — 文档能否在 RAG/语义搜索中获得良好匹配？标题和摘要中是否包含关键术语？

评审者会针对每项标准给出通过/失败结果。未通过的项目会返回步骤 4，对相应软件包进行处理。

步骤 6 — 提交

某个包通过评审委员会审查后：

1. 仅暂存文档文件（TSDoc 修改对应的 .ts/.tsx 文件，以及 README.md）
2. 使用仓库的约定式提交格式，默认为：

   docs(<package-name>): improve TSDoc and README documentation
   

3. 不要推送，推送操作留给用户或 PR 工作流

步骤 7 — 报告

处理完所有包后：

1. 将摘要写入 .tmp/scribe-report-<context>.md：
   • 已处理的包及其状态（通过／失败／跳过）
   • 已编写文档的导出项总数
   • 各项评审标准的评审委员会通过率
   • 被标记为需要人工审查的包
   • 创建的提交
2. 如果提供了跟踪问题，则使用摘要更新该问题

预期输出

• 已处理包中所有公开导出项的 TSDoc 注释
• 每个已处理包均有一致的 README
• 每个包各有一个仅包含文档变更的提交
• .tmp/ 中的摘要报告
• 更新跟踪问题（提供问题编号时）

安全与约束

此技能可修改文件。如仓库本地工作流说明与行内指导相冲突，以仓库本地工作流说明为准。

• 仅修改文档注释和 README 文件，切勿触碰运行时代码
• 不要推送提交；是否推送由用户决定
• 不要自动合并 PR，也不要绕过审查工作流
• 不要臆造 API 行为，只记录代码实际执行的行为
• 不要删除或替换现有的有价值文档，除非保留其内容
• 引用了跟踪问题时，仅在获得明确确认后才更新
• 遵守 .gitignore，不要提交 .tmp/ 中的临时文件
• 如果某个包连续两次未通过评审委员会审查，则将其标记为需要人工审查，不要无限循环