技术写作者 AI 流水线

这个 pack 包含什么

你是技术写作者或 DevRel。日常输出是 API reference、上手指南、tutorial、三种语言的代码示例、一份没人读的 style guide。AI 终于能帮你了 — 但市场上 700+ 工具大部分是给营销文案用的通用 chat 工具。

这个 pack 是专为技术写作工作流挑的 9 件套：审计现有内容、起 AI 一稿、从 OpenAPI spec 生代码示例、强制 prose + Markdown 风格、渲染不像 2014 年的 API reference、最后让你的文档能被用户在 Cursor / Claude Code 里直接当 context 拉走。

全部开源或有真正能用的免费档。没有一个是「用 AI 写博客」那种通用工具。安装顺序很关键 — 每一步喂给下一步。

推荐安装顺序（审计 → 一稿 → 风格 → 站点 → 发布）

1. Skill Seekers — Convert Docs/Repos/PDFs to Skills（审计）— 从这里开始。把你现有的文档、代码库、内部 PDF 喂进去，输出结构化 skill 给下游 agent 加载。这是一次性的「我们已经有什么」审计，agent 在写任何一段之前先有上下文。
2. Claude Code Agent: Technical Writer（一稿）— Anthropic 风格的 subagent，专门为 API reference / 用户指南 / SDK 文档 / 上手流程调过。扔进 .claude/agents/，指一个主题，得到一份你只需要编辑而不需要重写的初稿。
3. Claude Code Agent: Api Documenter（API 专用一稿）— #2 的姊妹 agent，专攻 OpenAPI / endpoint 形态。喂一份 spec 或路由处理器，得到带正确动词、状态码、示例 payload 的 reference 文本。
4. OpenAPI Generator — 从 spec 生 Client SDK + Server Stub（代码示例）— 从一份 OpenAPI YAML 在 50+ 种语言里生可用 SDK 代码。这是你停止在每个页面手写 curl / Python / Node / Go 示例的方式。spec 改了？重跑一遍，示例自动新鲜。
5. Scalar — 开源 API 平台 + 漂亮的 Reference 渲染（reference 渲染）— 把 OpenAPI 渲染成不像 2014 年 Swagger UI 的现代 reference 页面。可自托管、可嵌入、可换主题。用户从 Google 搜进来落地的页面就是它。
6. Vale — 面向技术写作的语法感知散文 lint（风格强制）— 杀手锏：lint Markdown / RST / AsciiDoc 对照你的 style guide，不会误伤代码块。内置 Microsoft、Google、Write the Docs 三套 style 包。CI 友好。自动抓 utilize → use、e.g., → for example。
7. Markdownlint — Lint Markdown for AI Content Quality（格式强制）— 机械的 Markdown 检查（标题层级、行尾空格、列表一致性、链接语法）。配合 Vale：Vale 管 prose 风格，Markdownlint 管文件结构。两个一起在 pre-commit 跑。
8. Starlight — Astro 文档框架（文档站）— 文档站本体。Astro 原生、快、深色模式默认、移动端 sidebar 能用。和前面 agent + linter 输出的 Markdown 无缝对接。别陷入静态站选型大战 — 新站 Starlight 是无聊但正确的答案。
9. Context7 — 给 AI 编辑器的最新文档 MCP（发布）— 没人讲的发布步骤。文档上线后，你希望用户在 Cursor / Claude Code / Codex 里写代码时，AI 能拉到你的最新文档作为 context（而不是幻觉你的 API）。Context7 给你的文档建索引、通过 MCP 提供。闭环：AI 帮你写文档，AI 再帮你的用户用文档。

它们怎么协同

现有文档 / 代码库
   │
Skill Seekers (#1) ── 审计，输出 agent 能加载的 skill
   │
   ├─→ Technical Writer agent (#2) ── 散文初稿
   │       │
   │       └─→ Markdown 文件
   │
   └─→ Api Documenter agent (#3) ←── OpenAPI spec
           │
           ├─→ OpenAPI Generator (#4) ── 代码示例（Python/Go/Node/curl）
           └─→ Scalar (#5) ── 渲染的 API reference
                   │
Vale (#6) + Markdownlint (#7)
   │
   └─ 每次 commit 都跑，风格/格式不过关直接挡 merge
         │
Starlight (#8) ── 编译文档站
   │
   └─ 部署 → Context7 (#9) 建索引 → AI 编辑器作为 context 拉走

承重三件套是 Skill Seekers + Technical Writer agent + Vale：审计、起稿、强制。没有审计 agent 会幻觉；没有 linter 一稿每次发版都偏离风格。其他 6 个是绕这个脊柱的生活质量升级。

你会遇到的取舍

• Technical Writer agent (#2) vs Api Documenter (#3) — 确实重叠。Technical Writer 干整篇文档（intro、tutorial、概念章节）。Api Documenter 是 endpoint 级（reference 行）。/getting-started 页用 #2；/reference/users/create 用 #3。如果你 80% 是 reference，就把 #3 顶上。
• Scalar (#5) vs Swagger UI / Redoc — 三个都渲染 OpenAPI。Swagger UI 是每个后端框架的默认但视觉老。Redoc 漂亮但配置重。Scalar 是新选手，开箱视觉最好、纯 OSS、不会有许可坑。如果你已经用 Swagger UI 在跑、用户没抱怨，不要为了好看迁移 — Scalar 是新项目的正解。
• Vale (#6) vs 语法检查器 — Vale 对照明确的 style guide（Microsoft / Google / 自定义）lint。Grammarly / LanguageTool 是猜的。文档量大就要明确 > 隐式 — 你要 CI 因为 utilize 直接 fail，让 agent 学会，而不是发布三周后看到一条波浪线。
• Starlight (#8) vs 静态站文档生成器 pack — 现有的 static-site-docs pack 覆盖 VitePress / Astro / Mintlify / Docusaurus / Slidev。Starlight 是 Astro-based 但专为文档预设主题。新项目直接上 Starlight；Docusaurus 已经跑了就别迁。
• Context7 (#9) — 是不是杀鸡用牛刀？ — 如果你的用户不用 AI 编辑器才是。他们用。

常见踩坑（尤其是 AI 幻觉 API 参数）

• 别让 agent 编 endpoint 参数 — #2 和 #3 会很开心地编一个不存在的 ?include= query param。修法：把真实的 OpenAPI spec 作为 context 喂进去（通过 #4 或直接贴文件），并在 agent 的 CLAUDE.md 里加一条规则「如果 spec 里没有这个参数，标 [verify] 而不是当成事实陈述」。
• Vale 多套 style 互打架 — 不要同时开 Microsoft + Google + Write-the-Docs。它们对牛津逗号、缩写、which vs that 的看法不一致。选一套 base，叠一套自定义。配置冲突的 PR 一周内会让团队崩溃。
• OpenAPI Generator 模板漂移 — 开箱模板生的 SDK 正确但难看。要发布到文档里，一次性 override 模板（半天工作量），把 override 提交到文档仓库。否则每次 spec 改都回退你的样式。
• Markdownlint 默认规则会拦正常 Markdown — MD013 line-length 和 MD041 first-line-heading 会对完全合规的文件咆哮。第一天就用项目级 .markdownlint.json，别用默认。
• Context7 索引延迟 — 部署后给最多 24 小时让新页面进索引。新发的 tutorial 没出现别立刻排查集成，明天再看。