工程实践:Sphinx文档工程AI技能包系统设计思路

工程实践:Sphinx文档工程AI技能包系统设计思路 | 技术传播

▶ 本文内容完全由作者撰写，无任何AI辅助创作

大家好，我是沉溺于逻辑推演，但实践稍显不足的睿齐。

昨天开源了一个技能包的试水之作——【见睿思齐Obsidian实践（bgrichi-obsidian-practice）】，貌似反响还不错？

其实，【见睿思齐Obsidian实践技能包】还只能算是个【基本可以说明问题】的小Case——毕竟，日常生活中需要AI参与的场景小且有限，也并非必须；真正需要AI大规模参与投入的大Case，最终还是要回到工作场景中。

最近，手头上另外一个正在开发的技能包【Sphinx文档工程（sphinx-doc-project-skills）】也完成了系统设计，并基于已有积累，进行了初步填充和构建。

这个技能包对基于【Sphinx】的文档工程构建、技术文档开发流程规范定义，典型场景技术文档内容模板和写作说明、技术文档开发全流程实施和管理，以及自动化部署等场景进行的系统化梳理和封装，目的是，指导AI全面参与技术文档开发与质量保证。

虽然，技能包开发仍主要处于【沙盘推演】阶段（仅部分经过实践验证），从实现的角度来看，完成度还不是很高，后续仍需在实践过程中不断迭代完善；但是，特别感谢卷王小姐姐的一路以来的花式鼓励，不断推动我将想法一寸一寸地实现落地，因此——

仅作为里程碑节点的复盘总结，简单分享一下技能包的基本构建思路，希望可以给到有需要的朋友，一点启发。

系统架构

这套系统采用最基本的“分层解耦 +闭环协同”的构建思路：

分层解耦：指将相关资源拆分为最小可用单元，以便灵活组织复用，降低维护成本；
闭环协同：指在技能包范围内，通过相对路径进行信息关联，最终充分且必要地指导AI完成任务。

目录结构如下：

0 元指令

提供针对当前技能包开发的元规则。目前主要包含：

分组	文件	说明
基本规则	AI指令写作风格说明	确保技能包中的AI指令结构稳定，且质量可靠
内容模板开发说明	确保内容模板和写作说明可复用、可扩展
操作指令通用规则	确保操作指令默认包含路径有效性校验、优先级冲突处理、强执行动作等通用操作
提交技能包源码前检查	在技能包提交源码库前进行常见问题例行排查
知识管理	知识笔记通用规则	在技能包开发过程中，将相关实践经验和问题处理，及时复盘总结，并整理输出为特定结构的知识笔记
实践场景复盘总结内容模板
整理输出实践场景复盘总结

1 基本定义

提供技能包中涉及的基本定义，确保AI可以正确理解相关含义。目前主要包含：

分组	说明
DITA架构	继承DITA原理，说明内容类型（Concept/Task/Reference）及基本结构。说明根据AI确认，采用DITA架构的技术文档，不仅适合人类读者阅读，亦可更好地被AI阅读和理解。
角色定义	明确文档开发全流程中涉及的角色职责边界，以便把全流程任务拆解为多Agent可并行协作的角色单元。目前主要包含：文档开发工程师：负责项目评审、文档工程构建、各类技术文档开发、文档发布归档等操作；文档测试工程师：负责技术文档测试验证；项目团队：负责技术文档评审。

2 流程规范

提供明确的文档工程规则、文法规则、语法规则、术语规则，确保文档开发过程可校验、可追溯、可复用。目前主要包含：

分组	文件	说明
–	流程规范总览	提供规则分层关系与使用入口，作为流程规范的总导航文件。
编码规则	RestructureText编码规则	约束工程规则与编码规则，保证RST内容可构建、可维护。
C与Doxygen编码规则	约束 C 注释与 Doxygen 文档写法，保证源码注释可解析、可生成文档。
Python编码规则	约束 Python场景下注释和接口文档写法，保证源码注释可解析、可生成文档。
工程规范	Sphinx文档工程规范	约束工程目录、命名、构建、发布等工程层规则，保证文档工程可持续维护。
文法规范	技术文档文法规范	约束说明句、操作句、限制句与信息组织方式，保证技术文档表达清晰且用户友好。
术语规范	约束术语定义、写法一致性、单源维护与冲突处理，保证跨文档术语统一。
检查清单	提交前快速检查清单	在文档工程发布前，进行常见问题例行排查
结构化写作适配检查清单	承接文法规则与语法规则，提供可执行检查项。
语法问题规则映射与落地清单	建立历史问题到规则条目的映射，支持问题驱动回写与追溯。

3 工程模板

提供Sphinx文档工程模板，包含可直接复用的目录结构、共用信息（如【前言】等）及通用配置，确保文档工程从初始化开始就具备统一结构和可发布能力。

4 内容模板

典型场景技术文档的标准内容架构和写作说明，确保输出结果在结构完整性与表达一致性上可稳定复现；通过“内容模板 + 写作说明”双文件模式实现结构与写法分治：

内容模板：定义“文档应该写成什么结构”，用于统一章节骨架与信息顺序。
写作说明：定义“文档应该怎么写”，用于约束表达方式、边界口径与质量标准。

目前主要包含：

用户指南内容模板+写作说明；
API接口说明内容模板+写作说明；
DITA主题分型写作说明：依据DITA定义的内容类型（说明类 / 操作类 / 参考类）分别给出共性写法规则，保证跨模板一致性与可复用性。

5 指令模板

提供典型业务场景任务执行编排，基于角色职责映射为可落地的步骤化动作，确保项目评审、文档开发、文档测试、文档评审、发布归档可以按统一SOP连续执行。目前主要包含：

角色	任务	说明
文档工程师	评审概要设计文档	固化概要设计评审流程与核查要点。
文档工程师	开发用户指南	固化开发过程中的执行顺序与输出要求。
文档工程师	提交文档工程源码前检查	固化提交流程门禁。
测试工程师	执行文档发布前测试	定义发布前验证范围与执行动作。
测试工程师	执行文档发布后测试	定义发布后验证路径与 SMOKE 优先级。
项目团队	文档评审	定义跨角色协同评审动作与结论收敛方式。

6 执行脚本

提供常用自动化工具，用于将构建、导入导出、批量处理等重复动作脚本化，确保流程执行效率与结果一致性同步提升。目前包含：

buildd：文档自动化构建与归档。
termsd：术语数据批量导入/导出与处理，以及YAML<>Excel转换。

7 工作流程

提供流程编排与运行机制，用于承接跨角色、跨步骤的流程串联与自动化沉淀，确保系统能力可以从“规则存在”走向“流程可运行”。目前暂无内容。

8 参考资料

外部资料输入接口。（略）

9 知识积累

基于当前技能包开发过程中的实践经验和问题排查进行的知识管理。用于把阶段实践、关键决策和可复用方法沉淀为可检索知识，确保相关经验可跨任务、跨周期持续复用，目前个人认为比较有价值的积累是：

文档问题反馈与规则沉淀工作流
技能包目录分层设计与扩展策略
技能包版本管理
开源技能包适配个性化应用场景
术语规则单源治理、分片组织与发布链路建设

10 任务计划

用于进行任务分解、任务跟踪、任务归档，确保技能包开发过程可追踪、可交接、可复盘。其中主要包含：

文件/目录	说明
任务计划说明	定义任务新建、归档、维护的统一规则。
\根目录	承接未完成任务并维护完成归档，保证迭代过程可追踪、可交接。
archive\目录	已完成的任务归档。

当前实现状况与后续迭代计划

当前实现状况（阶段性成果）

全流程框架已建立：项目输入、开发、测试验证、评审、发布归档已在体系中有对应规则与入口。
核心能力已进行沙箱验证：角色定义、流程规范、内容模板、指令模板、执行脚本形成协同链路。
【用户指南开发】【概要设计评审】场景已实践验证可用。
质量门禁已完成初步定义：检查清单与规则映射可用于过程校验与提交收口。
经验机制已上线：知识积累与任务计划并行运行，支持持续回写与迭代治理。

后续迭代计划（面向产品化）

近期计划：

完成规范收敛后的统一回写：同步更新开发规则与验证目标，消除执行断点。
固化全流程阶段门禁：为每一阶段补齐输入、输出、通过条件与异常处理策略。
引入最小指标体系（流程通过率、返工率、检查命中率）进行效果跟踪。

中期计划：

推进工作流编排化，提升多Agent自动串联能力，减少人工调度。
形成标准化案例集与验证样例库，支持跨项目复制与快速落地。
建立发布归档后的自动复盘回写机制，闭环驱动下一轮规则优化。

我认为，sphinx-doc-project-skills的核心价值，不在于“多写了多少文档”，而在于把文档开发全流程系统化为一套可被AI执行的标准运行体系。目前，它已经可以初步用于指导AI尝试参与“项目输入 → 文档开发 → 测试验证 → 评审 → 发布归档”全流程任务，并确保内容质量稳定——一个小小的成就感。

当然，在实践过程中，也少不了需要对已有内容进行长时间地打磨和优化。Anyway，

今天的分享，就是这些内容。如果你喜欢这篇文章，觉得有所启发和帮助，记得点赞和分享；如果你有想法想要与我讨论，欢迎留言给我。