用途
Package Scribe 用于在 TypeScript monorepo 中系统性地添加或改进文档，既可以针对单个包，也可以对整个 monorepo 进行文档扫描。典型触发场景包括：为所有包补充文档、改进某个包的文档、为包内所有公共导出添加 TSDoc、重写某个包的 README、对 monorepo 执行一次文档整理、审查某个包的 TSDoc 质量。隐式触发场景包括：包存在缺失或占位 TSDoc 的公共导出、README 过时或不一致或缺少标准章节、计划对多个包进行文档扫描。
该技能为实验性，尚未稳定，行为、结构和输出可能随版本变化。
主要能力
- 发现仓库自身的文档标准，包括 .github/instructions/ 下的适用文件、CONTRIBUTING.md、contribute/、tsconfig.json、biome.json 或等效 linter 配置，以及可选的 fusion-code-conventions 技能。仓库级标准优先于内置默认值。
- 发现包：单包模式验证路径存在且包含 TypeScript 源文件；扫描模式读取根 package.json 或工作区配置（pnpm-workspace.yaml、lerna.json、turbo.json）查找所有包，按 glob/列表过滤，按文件数量估算大小并排序。
- 扫描公共 API 表面：查找 barrel 导出文件（index.ts、index.tsx 或 package.json 的 main 字段），追踪所有重导出，将导出分类为函数、类、类型/接口、常量、hooks、枚举，优先处理 barrel 导出。
- 生成或改进 TSDoc：阅读实现以理解意图、参数、返回值、错误路径和副作用；在已有 TSDoc 基础上改进而非替换；应用 TSDoc 检查清单，包括摘要行、@param、@returns、@template、@throws、@example、@deprecated，并标记和重写“名称回声”模式。
- 重写或改进 README：保留现有有价值内容，应用仓库指令或内置模板的结构，包括包名与描述、功能/关键导出、安装、带代码示例的用法、API 参考、配置（如适用），并优化检索适配度。
- 审查委员会：每个包处理后运行，按意图提取、代码理解、面向用户质量、检索适配度四项标准给出通过/失败，失败则回到处理步骤。
- 提交与报告：仅暂存文档文件，使用仓库约定提交格式（默认 docs(<package-name>): improve TSDoc and README documentation），不推送；生成 .tmp/ 下的摘要报告，并在提供跟踪 issue 时更新。
使用方式
必需输入：范围（monorepo 根路径或特定包路径）、模式（single 单包或 sweep 多包扫描）。条件输入：包过滤器（glob 或列表）、README 模板路径、跟踪 issue 编号、提交风格、批大小（默认 5）。默认值：单包路径时模式为 single，提交前缀为 docs(<package-name>):，批大小为 5，README 结构使用内置模板，审查委员会启用。
执行流程：发现仓库标准 → 发现包 → 规划执行（仅扫描模式）→ 逐包处理（扫描 API、生成/改进 TSDoc、重写/改进 README）→ 审查委员会 → 提交 → 报告。单代理运行时，编排者、文档编写者、审查者三个角色按顺序内联运行。
适用场景
适用于 TypeScript/TSX 包的文档整理，包括单包文档改进和 monorepo 范围的文档扫描。
限制
不适用于修改运行时代码（仅文档注释和 README 文件）、生成 API 参考站点或 TypeDoc 输出、非 TypeScript 语言、自动合并 PR 或绕过审查流程、安全漏洞扫描或性能分析、替代现有基于 CI 的文档生成流水线。该技能具备变更能力，仓库本地工作流指令在冲突时优先。不得推送提交，不得自动合并 PR，不得编造 API 行为，不得删除或替换现有有价值文档而不保留其内容，引用跟踪 issue 时仅在明确确认后更新，需遵守 .gitignore 且不提交 .tmp/ 中的临时文件。若审查委员会对某包两次失败，则标记为人工审查而非无限循环。