文档拆分与知识库发布流程规范

为确保技术文档的工程化管理与高效迭代，本规范定义从本地开发到知识库发布的完整生命周期。通过标准化的命名规则、REST API 自动化部署以及严格的质量门禁，实现 Docs as Code 的治理目标。

1. 文件命名与目录结构规范

合理的目录结构是知识库可维护性的基石。采用“按专题拆分”的策略，确保物理文件结构与业务模块对齐。

1.1 核心原则

• 专题化拆分：将单体文档拆解为总体架构、多库规范、RAG、爬取与同步、安全与性能等独立模块。
• 文件名与标题一致：物理文件名(去除扩展名与前缀)必须与文档内 H1 标题对应，避免索引歧义。
• 编号前缀：文件名使用递增编号(如 01-xx/20-xx)，与目录清单保持一致。

1.2 推荐目录结构

/docs
├── 01-product-requirements.md # 对应 H1: 产品需求文档
├── 08-system-architecture.md # 对应 H1: 总体架构
├── 19-graphrag-searxng.md # 对应 H1: 自动进化方案
├── 24-rag-regional-inheritance-llm-logic.md # 对应 H1: RAG 交互逻辑
├── 30-deployment-ops.md # 对应 H1: 部署与运维最佳实践
└── resources/ # 静态资源目录
    ├── images/
    └── charts/

2. 发布与迭代流程

文档发布与迭代统一使用知识库文档系统接口，避免重复维护说明：

• 发布接口与鉴权：docs/18-docs-rest-api.md
• 迭代记录模板：docs/21-iteration-template.md
• 文档管理规范：docs/17-docs-management.md

3. 审批与质量门禁建议

为保证知识库权威性，所有文档必须经过“自动化校验”与“人工评审”双重门禁。

3.1 流程步骤

1. 提交草稿(Draft)：本地完成 Markdown 编写，并运行 Lint 工具进行格式检查。
2. 自动化流水线(CI Guard)：提交 PR 时触发 CI 检查。
3. 人工评审(Review)：由架构师或技术负责人审核，重点关注准确性与脱敏合规。
4. 发布上架(Publish)：合并主干代码，自动触发 REST 发布脚本推送到生产知识库。

3.2 准入标准 checklist

• 结构合规：必须遵循 H1-H2-H3 层级结构，禁止跳级。
• 代码可运行：代码片段必须经过测试，禁止伪代码。
• 无敏感信息：严禁包含真实 AK/SK、内网 IP 或客户隐私数据。

4. 关联文档

• docs/17-docs-management.md：文档管理流程
• docs/18-docs-rest-api.md：文档系统 REST API
• docs/21-iteration-template.md：迭代记录模板