InsForge 文档维护实践面向 Agent 的仓库文档工程与多语言发布指南【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge导读本文介绍如何在 InsForge 开源仓库中维护产品文档体系。InsForge 是一个面向 Agent 编程场景的一体化后端平台其文档仓库同时承载三类读者人类开发者、接入 InsForge 的编码 Agent、以及维护平台的工程师。围绕.agents/skills/insforge-dev/docs/SKILL.md定义的文档维护规则你将掌握文档面的划分方法、面向不同读者的写作风格、防止文档与实现漂移的变更流程以及 OpenAPI 契约与 Markdown 文档的交叉校验方法并了解仓库内置的多语言i18n文档体系与校验脚本。仓库中的文档工程全貌InsForge 仓库将文档视为一等公民而不是代码的附属品。整个文档工程由四部分构成面向用户的公共文档位于 docs/core-concepts 及各相关公共文档目录在公开文档站点Mintlify发布面向 Agent 的指令文档位于 .agents/docs例如deployment.md、real-time.md、payments.md、payments-stripe.md、payments-razorpay.md、insforge-instructions-sdk.md各框架的 SDK 集成指南位于 docs/sdks覆盖typescript、rest、swift、kotlin四种语言/风格OpenAPI 契约文件位于 openapi包含auth.yaml、storage.yaml、payments.yaml、realtime.yaml、ai.yaml等 18 个接口契约。站点本身由 docs/docs.json 驱动采用 Mintlify 的theme: mint主题主色调为绿色系#07C983默认深色外观。导航通过navigation.languages数组管理多语言入口默认语言为英语。把每篇文档放进正确的文档面SKILL.md 的第一条工作规则强调文档必须落在正确的文档面documentation surface上。放错位置的文档既无法被目标读者发现也会破坏仓库的组织约定。具体映射关系如下文档类型归属位置说明面向人类的公共文档docs/core-concepts/ 及相关公共目录在公开文档站点发布实现细节较重的公共文档对应域目录下的architecture.md例如docs/core-concepts/domain/architecture.md仅面向 Agent 的指令.agents/docs/指令优先、面向执行各框架 SDK 集成指南docs/sdks/按框架目录组织OpenAPI 契约变更openapi/ 对应文件与 API 行为变更同步修改从仓库结构看docs/core-concepts/下按产品域组织了完整的目录树database含overview、migrations、backups、pgvector、authentication、storage、realtime、functions、ai、sites、messaging含custom-smtp、payments含stripe、razorpay、analytics、compute、webscraper。每个域一个目录正是为了让实现细节较重的文档可以在域内就近放置architecture.md。这一划分在顶层 skill.agents/skills/insforge-dev/SKILL.md中有对应呼应文档改动属于docsskill 的职责边界而backend、dashboard、ui、shared-schemas等 skill 各有自己的包边界。先识别包边界再决定改动落在哪个层是仓库的核心规则。写作风格必须匹配读者SKILL.md 的第二条规则是风格与受众匹配这决定了文档面的内容形态公共文档面向人类读者要人类友好且把实现讲清楚。文档站点上的docs/*.mdx只使用title和description两种 frontmatter 字段不添加icon、sidebarTitle等扩展键参数说明不使用ParamField组件而是统一写成### Parameters标题下的普通 Markdown 项目符号列表SDK 安装片段一律通过import Installation from /snippets/sdk-installation.mdx复用共享片段而不是逐页内联参见 .claude/skills/doc-author/INSFORGE.md。architecture.md页面要详细解释功能的内部工作原理服务实现者阅读。Agent 文档.agents/docs/要求指令优先、面向执行删除解释性填充聚焦 Agent 完成任务所需的确切步骤。风格上还明确要求听起来像人而不是像 AI 生成的内容避免使用破折号插入语、三连排比fast, reliable, and scalable、not just X but Y式否定平行结构、夸大其词plays a vital role、含糊归因studies show以及 delve、leverage、underscore、seamless、robust 等 AI 高频词。写作语气采用第二人称祈使句直接对读者说话docs/quickstart.mdx 是权威范本。用同步变更流程防止文档漂移文档漂移documentation drift指实现变了、文档没跟上或契约改了、SDK 指南还是旧写法。SKILL.md 的第三条规则把防漂移固化为每次实现变更的必经步骤改实现之前先查阅该功能的现有用户文档改完实现之后在同一个提交里同步更新对应的 Markdown 文档和 OpenAPI YAML 文件契约或行为变了OpenAPI 和 Markdown 不能当作可选的后续工作影响 Agent 工作流更新 .agents/docs/ 中对应文件影响公共产品认知更新 docs/core-concepts/ 对应页面实现细节变化时还要更新architecture.md影响 SDK 集成指引更新 docs/sdks/ 中对应框架指南。这套流程与仓库的变更分层规则一致契约变更先改 packages/shared-schemas 再改消费方后端行为变更按 route - service - provider/infra 的层次推进。文档变更被明确视为实现变更的一部分而不是收尾时的附加动作。验证让文档可核查、可执行SKILL.md 的 Validation 部分要求三层验证逐条重读文档中记录的每个命令、路径、路由和 payload确认与实现一致交叉核对OpenAPI YAML 与 Markdown 文档确认与已实现行为一致如实声明无法直接验证的内容而不是含糊带过。仓库把这种验证进一步工程化。多语言一致性由 scripts/check-docs-i18n-parity.sh 自动化完成该脚本做了两类检查遍历 docs/docs.json 中navigation.languages的每个语言条目验证每条导航路径都能解析到真实文件且非英语条目的路径都以对应语言前缀开头避免静默回落到英语页面遍历英语导航的所有页面验证在zh、zh-Hant、es三个语言目录下都有对应的翻译文件缺任一语言即报错退出。除此之外仓库还提供scripts/build-docs-langs.py用于在增删英语页面后重新生成导航自动加语言前缀并应用标签映射以及scripts/check-setup-sh.sh、scripts/sync-skills.sh、scripts/update-mintlify-skill.sh等配套维护脚本。多语言文档体系Mintlify i18n 的落地方式SKILL.md 所属的 docs skill 还包含一份 .agents/skills/insforge-dev/docs/DOCS_I18N.md规定了多语言文档的具体机制这是维护公共文档时无法绕开的部分支持语言英语默认、简体中文zh、繁体中文zh-Hant、西班牙语es。注意zh-TW不被 Mintlify CLI 接受繁体必须用zh-Hant目录镜像每个非默认语言一个目录docs/zh/、docs/zh-Hant/、docs/es/与英语树保持相同文件名和结构导航由 docs.json 驱动navigation.languages数组中每个语言一个条目各持完整的tabs/groups树。英语页面用裸路径如introduction本地化页面用带前缀路径如zh/introduction。只有翻译文件而没有languages条目该语言不会出现在站点上路径唯一性绝不跨语言复用页面路径zh/前缀保证唯一翻译边界代码块、行内代码、MDX/JSX 组件名、URL 与文件路径、API/SQL/环境变量名、品牌名、CLI 命令、OpenAPI 规范以及data-for-agents块一律不翻译只翻译自然语言文本片段不本地化snippets/*.mdx被各页面按绝对路径/snippets/x.mdx引用始终解析到英语因此不建立逐语言的片段副本验证命令npx mint broken-links检查坏链scripts/check-docs-i18n-parity.sh检查导航与翻译文件的一致性。从仓库现状看多语言体系已经完整落地docs/zh/、docs/zh-Hant/、docs/es/三个目录均镜像了英语文档树且三个语言的sdks子目录都包含了与英语一致的 32 个文件。与仓库开发流程的衔接文档维护不是孤立工作。顶层 skill.agents/skills/insforge-dev/SKILL.md把docs列为 insforge-dev skill 集合的五个子技能之一另有backend、dashboard、ui、shared-schemas并规定跨包改动必须运行仓库级校验npx turbo run typecheck、npx turbo run lint、npx turbo run test、npx turbo run build这些命令通过 Turborepo 覆盖包括packages/dashboard/与packages/shared-schemas/在内的所有工作区。PR 前的强制清单要求任何失败的检查都不能带着提交若失败是 main 分支上预先存在的、与本次改动无关则需要用npx eslint changed-files限定检查范围并在 PR 描述中说明。这保证了文档改动与代码改动共享同一套质量门槛。小结InsForge 的文档工程可以概括为四条原则按文档面归类公共文档、Agent 文档、SDK 指南、OpenAPI 契约各归其位、按读者调整风格人类友好 vs 指令优先、变更同步防漂移实现、Markdown、OpenAPI 一次改齐、验证自动化交叉核对加 i18n 校验脚本。对于希望参与 InsForge 文档贡献的开发者正确起点是阅读 .agents/skills/insforge-dev/docs/SKILL.md 和 .agents/skills/insforge-dev/docs/DOCS_I18N.md再对照 docs/core-concepts、docs/sdks 与 openapi 中的真实文档确认风格与结构最后用npx mint broken-links与scripts/check-docs-i18n-parity.sh完成验证。【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考