fusion-package-scribe

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Package Scribe

Experimental caveat

实验性说明

This skill is experimental and not yet stable. Behavior, structure, and outputs may change between versions.

本技能处于实验阶段，尚未稳定。不同版本间的行为、结构和输出可能会有所变化。

When to use

使用时机

Use this skill when you need to systematically add or improve documentation across TypeScript packages — whether a full monorepo sweep or a single package.

Typical triggers:

"document all packages"
"improve docs for
```
packages/utils/observable
```
"
"add TSDoc to all public exports in this package"
"rewrite the README for this package"
"run a documentation pass on the monorepo"
"review the TSDoc quality in this package"

Implicit triggers:

A package has public exports with missing or stub TSDoc
A package README is outdated, inconsistent, or missing standard sections
A documentation sweep is planned across multiple packages

当你需要系统性地为TypeScript包添加或改进文档时（无论是全monorepo扫描还是单包处理），可以使用本技能。

典型触发指令：

"为所有包生成文档"
"改进
```
packages/utils/observable
```
的文档"
"为本包所有公共导出添加TSDoc注释"
"重写本包的README"
"对monorepo进行文档梳理"
"检查本包的TSDoc质量"

隐含触发场景：

包的公共导出缺少TSDoc注释或仅有占位符注释
包的README过时、格式不一致或缺少标准章节
计划对多个包进行文档全面梳理

When not to use

不适用场景

Do not use this skill for:

Modifying runtime code (only doc comments and README files)
Generating API reference sites or TypeDoc output
Non-TypeScript languages (initial scope is TS/TSX only)
Auto-merging PRs or bypassing review workflows
Security vulnerability scanning or performance profiling
Replacing existing CI-based doc generation pipelines

请勿将本技能用于以下场景：

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

Required inputs

必填输入

If required inputs are missing or ambiguous, ask before proceeding.

Scope: monorepo root path or specific package path(s)
Mode:
```
single
```
(one package) or
```
sweep
```
(multiple packages)

如果必填输入缺失或不明确，请先询问用户再继续。

范围：monorepo根路径或特定包路径
模式：
```
single
```
（单包）或
```
sweep
```
（多包扫描）

Conditional inputs

条件输入

Package filter: glob or list when processing a subset of packages
README template path: repo-specific template if not using the built-in default (for example under
```
.github/instructions/
```
)
Tracking issue: issue number for lifecycle updates (assign, status, close)
Commit style: repo-specific conventional commit format (defaults to
```
docs(<package>): 
```
)
Batch size: number of packages per batch for sweep mode (defaults to 5)

包过滤器：处理部分包时使用的glob表达式或列表
README模板路径：仓库自定义模板（例如
```
.github/instructions/
```
下的文件），若不使用内置默认模板
跟踪议题：用于生命周期更新的议题编号（分配、状态更新、关闭）
提交风格：仓库自定义的规范提交格式（默认格式为
```
docs(<package>): 
```
）
批量大小：扫描模式下每批处理的包数量（默认值为5）

Defaults

默认设置

Mode:
```
single
```
(if only one package path provided)
Commit prefix:
```
docs(<package-name>):
```
Batch size: 5 packages per sweep batch
README structure: built-in template from
```
references/readme-template.md
```
Review council: enabled (runs after every package)

模式：
```
single
```
（仅提供单个包路径时）
提交前缀：
```
docs(<package-name>):
```
批量大小：每批扫描处理5个包
README结构：来自
```
references/readme-template.md
```
的内置模板
评审委员会：启用状态（每个包处理完成后运行）

Precedence and standards discovery

优先级与标准识别

This skill discovers and follows the target repository's own standards:

Repository instructions — applicable files under
```
.github/instructions/
```
,
```
CONTRIBUTING.md
```
,
```
contribute/
```
Tooling configuration —
```
tsconfig.json
```
,
```
biome.json
```
,
```
.editorconfig
```
Companion skill —
```
fusion-code-conventions
```
for TSDoc rules, naming conventions, and intent quality (when installed)

Built-in defaults —

references/tsdoc-checklist.md

and

references/readme-template.md

Repository-level standards always win. When no repo standards exist, the built-in defaults apply.

本技能会自动识别并遵循目标仓库自身的标准，优先级如下：

仓库说明文档 —

.github/instructions/

、

CONTRIBUTING.md

、

contribute/

下的相关文件

工具配置 —
```
tsconfig.json
```
、
```
biome.json
```
、
```
.editorconfig
```
配套技能 — 若已安装
```
fusion-code-conventions
```
，则遵循其
```
references/typescript.conventions.md
```
中的TSDoc规则、命名规范和质量要求

内置默认值 —

references/tsdoc-checklist.md

和

references/readme-template.md

仓库级标准始终优先。当不存在仓库标准时，使用内置默认值。

Agent modes

Agent模式

Agent	Role	Activated for
`agents/orchestrator.agent.md`	Batch coordinator	Sweep mode — plans batches, manages token budgets, tracks progress
`agents/documenter.agent.md`	Per-package writer	Every package — scans API surface, generates TSDoc, rewrites README
`agents/reviewer.agent.md`	Review council	After each package — verifies intent, comprehension, retrieval fitness

In single-agent runtimes, all three roles run inline sequentially.

Agent	角色	激活场景
`agents/orchestrator.agent.md`	批量协调器	扫描模式 — 规划批量处理、管理令牌预算、跟踪进度
`agents/documenter.agent.md`	单包文档编写器	每个包处理 — 扫描API表面、生成TSDoc注释、重写README
`agents/reviewer.agent.md`	评审委员会	每个包处理完成后 — 验证意图、理解度、检索适配性

在单Agent运行环境中，三个角色会按顺序依次执行。

Instructions

操作步骤

Step 1 — Discover repository standards

步骤1 — 识别仓库标准

Before generating any documentation:

Search for repo-level documentation instructions:
- applicable files under
```
.github/instructions/
```
- ```
CONTRIBUTING.md
```
  ,
```
contribute/
```
Read
```
tsconfig.json
```
to understand module structure, path aliases, and strict mode settings
Read
```
biome.json
```
or equivalent linter config for style expectations
Check if
```
fusion-code-conventions
```
is available — if so, defer to its TSDoc rules from
```
references/typescript.conventions.md
```
If no repo-level standards exist, use
```
references/tsdoc-checklist.md
```
as the quality baseline

在生成任何文档之前：

搜索仓库级文档说明：
- ```
.github/instructions/
```
  下的相关文件
- ```
CONTRIBUTING.md
```
  、
```
contribute/
```
  目录
读取
```
tsconfig.json
```
以了解模块结构、路径别名和严格模式设置
读取
```
biome.json
```
或等效的代码检查器配置以了解风格要求
检查是否可用
```
fusion-code-conventions
```
— 若可用，则遵循其
```
references/typescript.conventions.md
```
中的TSDoc规则
若不存在仓库级标准，则使用
```
references/tsdoc-checklist.md
```
作为质量基准

Step 2 — Discover packages

步骤2 — 识别包

For single mode: validate the provided package path exists and has TypeScript source files
For sweep mode:
- Read the root
```
package.json
```
  or workspace config (
```
pnpm-workspace.yaml
```
  ,
```
lerna.json
```
  ,
```
turbo.json
```
  ) to find all packages
- Filter by any provided glob/list
- Sort packages by estimated size (file count) for batch planning
- Write the discovery summary to
```
.tmp/scribe-discovery-<context>.md
```

单包模式：验证提供的包路径是否存在且包含TypeScript源文件
扫描模式：
- 读取根目录的
```
package.json
```
  或工作区配置文件（
```
pnpm-workspace.yaml
```
  、
```
lerna.json
```
  、
```
turbo.json
```
  ）以找到所有包
- 根据提供的glob表达式/列表进行过滤
- 按预估大小（文件数量）对包进行排序，用于批量规划
- 将识别结果写入
```
.tmp/scribe-discovery-<context>.md
```

Step 3 — Plan execution (sweep mode only)

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

Activate

agents/orchestrator.agent.md

(or run inline):

Group packages into batches of the configured batch size
Order batches: smaller packages (fewer source files) first to maximize early throughput
Estimate token budget per package: ~100 tokens per source file for reading, ~200 tokens per export for TSDoc generation
If a single package exceeds 60% of the estimated context window, flag it for special handling (barrel exports first, defer internal modules)
Write the execution plan to
```
.tmp/scribe-plan-<context>.md
```

激活

agents/orchestrator.agent.md

（或内联运行）：

按配置的批量大小将包分组
排序批次：先处理较小的包（源文件更少），以最大化早期处理效率
预估每个包的令牌预算：读取文件约每源文件100令牌，生成TSDoc注释约每导出项200令牌
若单个包超出预估上下文窗口的60%，标记为需特殊处理（先处理桶导出，延后处理内部模块）
将执行计划写入
```
.tmp/scribe-plan-<context>.md
```

Step 4 — Process each package

步骤4 — 处理每个包

Activate

agents/documenter.agent.md

(or run inline) for each package:

为每个包激活

agents/documenter.agent.md

（或内联运行）：

4a — Scan public API surface

4a — 扫描公共API表面

Find the barrel export file (
```
index.ts
```
,
```
index.tsx
```
, or
```
main
```
field in
```
package.json
```
)
Trace all re-exports to identify the full public API surface
Categorize exports: functions, classes, types/interfaces, constants, hooks, enums
Prioritize: barrel exports first, then direct public exports, then internally-consumed-but-exported items

找到桶导出文件（
```
index.ts
```
、
```
index.tsx
```
或
```
package.json
```
中的
```
main
```
字段指定的文件）
追踪所有重导出以识别完整的公共API表面
对导出项分类：函数、类、类型/接口、常量、钩子、枚举
优先级：桶导出优先，然后是直接公共导出，最后是内部使用但被导出的项

4b — Generate or improve TSDoc

4b — 生成或优化TSDoc注释

For each public export:

Read the existing implementation to understand intent, parameters, return values, error paths, and side effects
Check for existing TSDoc — improve rather than replace when present
Apply the TSDoc checklist (repo standards or
```
references/tsdoc-checklist.md
```
):
- Summary line: explain why and what problem it solves, not just what it does
- ```
@param
```
  for every parameter with meaningful descriptions
- ```
@returns
```
  for every non-void function
- ```
@template
```
  for every generic type parameter
- ```
@throws
```
  for meaningful error paths
- ```
@example
```
  for user-facing and non-trivial public APIs
- ```
@deprecated
```
  with replacement guidance when applicable
Flag and rewrite "name-echo" patterns (for example
```
/** Gets the value. */ getValue()
```
)
Do not modify runtime code — only doc comments

针对每个公共导出项：

读取现有实现以理解意图、参数、返回值、错误路径和副作用
检查现有TSDoc注释 — 若存在则优化而非替换
应用TSDoc检查清单（仓库标准或
```
references/tsdoc-checklist.md
```
）：
- 摘要行：解释为什么需要它以及解决了什么问题，而不仅仅是它做了什么
- 每个参数都要有
```
@param
```
  并附带有意义的描述
- 每个非void函数都要有
```
@returns
```
- 每个泛型类型参数都要有
```
@template
```
- 有意义的错误路径要添加
```
@throws
```
- 用户可见的非 trivial 公共API要添加
```
@example
```
- 适用时添加
```
@deprecated
```
  并提供替代方案指引
标记并重写“名称重复”模式（例如
```
/** 获取值。 */ getValue()
```
）
不得修改运行时代码 — 仅处理文档注释

4c — Rewrite or improve README

4c — 重写或优化README

Read the existing README (if any) to preserve valuable content
Apply the README structure from repo instructions or
```
references/readme-template.md
```
:
- Package name and description
- Features / key exports
- Installation
- Usage with code examples
- API reference (summary of key exports with links or inline docs)
- Configuration (if applicable)
Ensure the README is useful to a developer discovering the package for the first time
Optimize for retrieval: use clear headings, keyword-rich descriptions, and concrete examples

读取现有README（若存在）以保留有价值的内容
应用仓库说明或
```
references/readme-template.md
```
中的README结构：
- 包名称和描述
- 特性 / 核心导出项
- 安装方法
- 用法及代码示例
- API参考（核心导出项摘要，附带链接或内联文档）
- 配置（若适用）
确保README对首次发现该包的开发者有用
优化检索性：使用清晰的标题、富含关键词的描述和具体示例

Step 5 — Review council

步骤5 — 评审委员会

Activate

agents/reviewer.agent.md

(or run inline) after each package:

Intent extraction — Does the TSDoc accurately describe what the code does and why? Flag any comment that merely restates the function/type name.
Code comprehension — Are complex algorithms, state machines, or side effects explained? Would a new developer understand the code from the docs alone?
User-facing quality — Is the README useful to someone discovering the package for the first time? Does it have working examples?
Retrieval fitness — Will the documentation produce good hits in RAG / semantic search? Are key terms present in headings and summaries?

The reviewer produces a pass/fail per criterion. Failures loop back to Step 4 for the specific package.

每个包处理完成后激活

agents/reviewer.agent.md

（或内联运行）：

意图提取 — TSDoc注释是否准确描述了代码的功能和设计意图？标记任何仅重复函数/类型名称的注释。
代码理解度 — 复杂算法、状态机或副作用是否有解释？新开发者仅通过文档能否理解代码？
用户体验质量 — README对首次发现该包的人是否有用？是否包含可运行的示例？
检索适配性 — 文档在RAG/语义搜索中能否产生良好的检索结果？标题和摘要中是否包含关键术语？

评审员会针对每个标准给出通过/不通过的结果。未通过的包会回到步骤4重新处理。

Step 6 — Commit

步骤6 — 提交

After the review council passes for a package:

Stage only documentation files (
```
.ts
```
/
```
.tsx
```
files for TSDoc changes,
```
README.md
```
)
Commit using the repo's conventional commit format, defaulting to:
```
docs(<package-name>): improve TSDoc and README documentation
```
Do not push — leave that to the user or a PR workflow

当评审委员会通过某个包的处理后：

仅暂存文档文件（
```
.ts
```
/
```
.tsx
```
文件的TSDoc更改、
```
README.md
```
）
使用仓库的规范提交格式进行提交，默认格式为：
```
docs(<package-name>): improve TSDoc and README documentation
```
不要推送提交 — 留待用户或PR流程处理

Step 7 — Report

步骤7 — 报告

After all packages are processed:

Write a summary to
```
.tmp/scribe-report-<context>.md
```
:
- Packages processed and status (pass/fail/skipped)
- Total exports documented
- Review council pass rates per criterion
- Any packages flagged for manual review
- Commits created
If a tracking issue was provided, update it with the summary

所有包处理完成后：

将摘要写入
```
.tmp/scribe-report-<context>.md
```
：
- 已处理包及其状态（通过/未通过/跳过）
- 已添加文档的导出项总数
- 各评审标准的通过率
- 需人工评审的标记包
- 创建的提交记录
若提供了跟踪议题，将摘要更新到该议题中

Expected output

预期输出

TSDoc comments on all public exports in processed packages
Consistent README for each processed package
One commit per package with documentation-only changes
Summary report in
```
.tmp/
```
Tracking issue update (when issue number provided)

已处理包中所有公共导出项的TSDoc注释
每个已处理包的统一格式README
每个包对应一条仅包含文档更改的提交记录
```
.tmp/
```
目录中的摘要报告
更新跟踪议题（若提供议题编号）

Safety & constraints

安全与约束

This skill is mutation-capable. Repository-local workflow instructions take precedence over inline guidance when they conflict.

Only modify doc comments and README files — never touch runtime code
Do not push commits; leave push decisions to the user
Do not auto-merge PRs or bypass review workflows
Do not invent API behavior — document only what the code actually does
Do not delete or replace existing valuable documentation without preserving its content
When a tracking issue is referenced, update it only after explicit confirmation
Respect
```
.gitignore
```
and do not commit temporary files from
```
.tmp/
```
If the review council fails a package twice, flag it for manual review instead of looping indefinitely

本技能具备修改能力。当仓库本地工作流说明与内置指南冲突时，仓库本地说明优先。

仅修改文档注释和README文件 — 绝不触碰运行时代码
不要推送提交；将推送决策交给用户
不要自动合并PR或绕过评审流程
不要虚构API行为 — 仅记录代码实际的功能
不要删除或替换现有有价值的文档，需保留其内容
当引用跟踪议题时，仅在明确确认后更新
遵守
```
.gitignore
```
，不要提交
```
.tmp/
```
中的临时文件
若某个包两次未通过评审委员会检查，标记为需人工评审，而非无限循环处理