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

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

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

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

### 1.1 核心原则

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

### 1.2 推荐目录结构

```bash
/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`：迭代记录模板