自动化 API 文档生成

把源代码转化为可维护的文档。OpenCode 会读取你的模块、提取公开 API，并撰写可直接放入文档站的参考文档。

何时使用此案例

• API 参考文档总是滞后于代码。
• 新人文档需要反映当前模块结构。
• 希望大量文档页保持格式统一。

前置配置

• 带类型函数/类的代码库（TypeScript、Go 等），以确保准确性。
• 在项目中配置好 OpenCode。

步骤

1. 指向源码

   告诉 OpenCode 要为哪些模块生成文档，以及输出位置。

   为 src/services/ 中每个导出函数写文档。每个函数写一节，包含签名、参数、返回类型和一行示例。输出到 docs/reference/services.mdx。

2. 设定格式

   指定 frontmatter 和结构，让输出匹配你的文档系统。

   ---
   title: Services Reference
   description: API reference for the services module.
   ---

3. 审查准确性

   OpenCode 可能推断出不真实的行为——逐条对照代码核对描述，尤其是边界情况。

4. 接入构建

   把生成的页面加入侧边栏/文档流水线，使其发布。

5. 安排刷新

   重大变更后用相同的提示词重新运行，保持文档同步。

关键提示词

读取 src/services/ 中每个导出符号，生成 Markdown 参考文档。包含签名、参数说明、返回类型和具体示例。不要编造行为——如果不确定，标注为”待审查”。

常见坑点

• 编造的行为：始终将生成的描述与实际实现交叉核对。
• 过时的文档：生成的文档很快腐化——把提示词纳入发布流程。
• 私有内部细节：明确排除内部/非导出符号，避免泄露实现细节。

相关文档

• 规则 — OpenCode 在每个任务中遵循的项目级指令
• 智能体 — 为重复工作流配置自定义智能体

相关案例

• slide-generation — reason.doc.to-slide
• explore-unfamiliar-codebase — reason.doc.to-explore
• custom-skill — reason.doc.to-skill

相关文档

• 智能体
• 工具
• 配置

下一步

• slide-generation — next.doc.to-slide