StaleDocs

StaleDocs

原名 aidoc。

StaleDocs 会读取代码，在拉取请求中查找公共 API 变更，并指出哪些文档章节仍描述旧行为。

网站 · GitHub Action 设置

只需一个文件即可添加到代码仓库

name: StaleDocs review
on: {pull_request: {types: [opened, synchronize, reopened]}}
permissions: {contents: read, pull-requests: write}
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
        with: {fetch-depth: 0}
      - uses: mr-min-max/[email protected]
        with:
          mode: review
          fail-on: none

评论包含的内容

• 变更的符号及变更前后的签名。
• 提及这些符号但尚未更新的章节。
• 适用时添加 breaking-change 和 docs-stale 标签。

无需模型、无需 API 密钥、不会写入文件。它采用确定性的 AST 分析。

在终端中使用

安装命令：

npm install -g staledocs@beta

staledocs review 会报告拉取请求对文档的影响。

staledocs plan 会打印受影响的文档目标。

如果提及已变更公共符号的章节未更新，staledocs check 会以代码 1 退出；否则以代码 0 退出。

一次性审计代码仓库

staledocs audit 会列出 Markdown 仍在提及、但代码中已不存在的包脚本、代码仓库路径和公共类成员，包括 AGENTS.md、CLAUDE.md，以及 .github 下的 copilot-instructions.md 文件——这些是编码 Agent 首先会读取的文件。它不需要拉取请求。此命令在 0.5.0-beta.1 中新增。

npm install -g staledocs@beta
staledocs audit

在一个小型测试代码仓库中的输出：

README.md > Usage: member-missing "Client.fetchAll"
README.md > Usage: path-missing "src/core/old.ts"
README.md > Usage: script-missing "npm run bulid" (closest: build)

3 findings across 1 Markdown file: script-missing 1, path-missing 1, member-missing 1.

使用助手修正文档

Claude Code 插件

在 Git 工作树中启动 Claude Code，然后运行：

/plugin marketplace add mr-min-max/staledocs
/plugin install staledocs@staledocs

使用 /staledocs:check 获取偏差提示，使用 /staledocs:review 获取拉取请求报告，或使用 /staledocs:maintain-documentation 生成经过验证的草稿。需要 Node.js >=22.12.0 和 npm/npx。本代码仓库托管自己的插件市场；它不属于 Anthropic 批准的目录列表。

Codex 插件

在 Git 工作树中启动 Codex，然后运行：

codex plugin marketplace add mr-min-max/staledocs
codex plugin add staledocs@staledocs

在新会话中输入 $，然后选择 staledocs:check、staledocs:review 或 staledocs:maintain-documentation（也可以打开 /skills）。需要 Node.js >=22.12.0 和 npm/npx。本代码仓库托管自己的插件市场；它未列入 OpenAI 的插件目录。

手动配置 MCP

codex mcp add staledocs -- staledocs --mcp

prepare_documentation_update 会向助手提供准确的章节及变更前后的签名。

StaleDocs 会验证候选内容，然后由助手应用获批的 Markdown。

请参阅 Codex 指南 和 Claude 指南。

语言

支持 TypeScript、JavaScript 和 Python。公共符号是指可从包入口访问的符号；请参阅 LIMITATIONS.md。

有关语法和发现方面的注意事项，请参阅 LIMITATIONS.md。

旧版生成器

readme、api、changelog、diagram 和 annotate 仍可用于生成初始文档。它们需要提供方密钥或 Ollama，并非 StaleDocs 的重点。请参阅 CLI 目录。

状态和链接

候选版本 0.5.0-beta.1 尚未发布。在此之前，npm latest、npm beta 和 GitHub Action v0 标签仍指向上一个已发布的 beta 版本，而上方和插件中的 v0.5.0-beta.1 固定版本号只有在发布后才会生效。

• 参与贡献
• 安全
• 限制
• 更新日志
• GitHub Action Marketplace
• 评估