Instruction file imported from jijingkun-commits/fastapi (.cursor/rules/doc_sync.mdc). Copyright stays with the author.

文档同步规则

文档结构统一原则

核心理念: 需求、设计、测试文档按功能模块对应，形成可追溯的文档矩阵。 2026-02-02 更新: 产品文档与需求文档已合并，统一放在 产品文档/ 目录。

功能模块对应关系

目录结构规范

docs/
├── 产品文档/                # 需求与产品说明（单一真理来源）
│   ├── 系统需求.md          # 全局功能列表 + 产品概述
│   ├── 待办助手需求.md
│   ├── 聊天系统需求.md
│   ├── 问数助手需求.md
│   ├── 管理后台需求.md
│   ├── 用户管理需求.md
│   └── 模型路由需求.md
├── 开发文档/
│   ├── 架构设计/            # 设计文档
│   └── 测试管理/
│       ├── 测试用例库.md    # 按功能模块组织的用例
│       ├── 测试指南与环境配置.md
│       └── {模块}测试案例.md # 详细用例
├── 内部参考/              # 长期有效的内部知识
│   ├── 决策记录.md
│   ├── AI技能库.md
│   └── 数据资料/
└── ...

过程层的 canonical 根目录为仓库根的 workdocs/；运行态产物的 canonical 根目录为仓库根的 .artifacts/。
workdocs/设计/ 是新的设计过程入口，历史方案设计已归档到 workdocs/归档/正文/设计/；docs/内部参考/ 下只保留少量旧入口说明页与历史材料。task_split 的 canonical 根目录已切到 workdocs/任务拆解/。

命名规范

• 统一使用中文命名
• 测试案例: {模块名}测试案例.md
• 测试报告: {模块名}测试报告.md 或 {模块名}测试报告_YYYYMMDD_{主题}.md 或 {模块名}测试报告_YYYY-MM-DD_{主题}.md
• 禁止新增旧命名：测试报告_{场景}_{日期}.md 或仅日期无主题后缀

主文档动态融合治理（强制）

文档角色

主文档强制规则

1. 主文档禁止新增 增量需求、实现进展、已执行、XX补充 一类历史性标题；新事实必须合并进原功能位。
2. 命中已污染的主文档时，执行 touch-once merge：本次触达范围内必须完成融合并删除旧增量段，禁止“再补一段”。
3. 新的设计推导、实施拆解、测试证据与执行报告统一写入 workdocs/** 或 .artifacts/**；docs/内部参考/ 下的旧入口页只保留历史追溯，不再新增同类产物。
4. 主文档头部必须维护 > 更新时间：YYYY-MM-DD，用于标识当前真相最近一次收敛时间。
5. 主文档中的日期只允许作为当前契约的背景注记，不得形成独立变更日志章节。
6. 过程文档与运行态产物必须分层：workdocs/ 是 canonical 过程层，.artifacts/ 是 canonical 运行态根；task_split 的 canonical 根目录固定为 workdocs/任务拆解/，旧任务拆解入口页不再承载机器契约或过程 JSON。
7. docs/** 禁止新增真实 .state/ 目录、.jsonl、.lock 等运行态文件；命中存量债务时只允许通过受控 allowlist 短时放行，并保留 warning 可见性。
8. 本规则由 scripts/docs_guard.py 与 scripts/check_doc_sync.sh 联合执行：本地 check_doc_sync.sh 默认告警不阻断，显式 --strict 与 CI 仍保持阻断语义。

何时更新文档

涉及以下任务时，先更新文档，再修改代码：

• 架构变更
• 新增功能/模块
• API 接口变更
• 数据库表结构变更
• 新增或调整特殊处理（兜底逻辑、兼容补丁、临时绕过、历史债务）

文档正文编辑策略（强制）

默认策略：原位修改，不做重复追加

对以下真理源文档，默认必须在对应章节原位修改，禁止在文末、章节末尾或平行新增“补充说明 / 更新记录 / 变更备注 / 临时口径”来重复描述同一主题：

• docs/产品文档/**
• docs/开发文档/**
• docs/API文档/**
• workdocs/需求/*/requirements.md
• workdocs/设计/*/design.md
• workdocs/任务拆解/*/contracts/implementation_plan.md
• workdocs/任务拆解/*/contracts/uat_cases.md

编辑前定位（强制）

修改正文前，必须先定位以下信息：

1. 目标文件；
2. 目标章节标题；
3. 目标段落 / 表格 / 清单；
4. 该位置是否已存在旧描述、旧示例、旧口径。

若已存在对应章节，必须在原章节内替换、删改、合并；禁止平行新增同主题章节。

允许追加的例外白名单

仅以下内容允许采用追加写法：

1. 审批记录、批准元数据；
2. Changelog、变更日志、发布记录；
3. 巡检记录、运行日志、归档记录；
4. 模板明确要求的附录、自检卡、WS 协作者回填区；
5. 防屎山记录手册中按 SP 编号保留的历史记录。

除白名单外，凡属正文语义、接口说明、配置说明、架构说明、需求口径、测试矩阵，均必须原位收敛，禁止追加重复内容。

找不到位置时的处理顺序（强制）

1. 先判断现有章节是否命名不准但职责正确；若是，直接在原章节收敛；
2. 若文档结构缺章，先补齐合理章节结构，再把内容写入新章节；
3. 禁止以“先追加，后续再整理”替代当前收敛；
4. 禁止新增与既有章节职责重叠的“补充说明 / 临时方案 / 更新备注”类平行章节。

完成后自检（强制）

完成文档修改后必须确认：

1. 无同主题重复标题；
2. 无同主题重复段落或重复表格；
3. 无与旧口径并存的冲突描述；
4. workdocs/需求/*/requirements.md、workdocs/设计/*/design.md、workdocs/任务拆解/*/contracts/{implementation_plan.md,uat_cases.md} 仅保留当前收口版本，不保留并行方案残片；
5. 新增内容若属于例外追加，必须能明确归类到白名单。

交付说明（强制）

交付时必须说明：

1. 修改了哪个文件；
2. 修改了哪个章节；
3. 属于“原位替换 / 原位增删 / 例外追加”哪一种；
4. 若为例外追加，必须说明命中的白名单条目。

文档映射

设计文档映射

需求文档映射

产品运行时 Skill 专项映射（强制）

强制动作：

1. 命中上表任一项时，禁止只更新单份文档、只补测试报告，或只回填内部参考文档。
2. 涉及 definition/version/user_binding 真理源、load_skills、catalog_* 字段、additional_kwargs.skill_runtime canonical 时，必须同步更新 docs/产品文档/技能系统需求.md 与 docs/内部参考/AI技能库.md。
3. 涉及技能导入来源、初始化策略、上线巡检或回滚步骤时，必须同步更新 docs/开发文档/快速入门/安装部署.md 与 docs/开发文档/快速入门/生产部署手册.md。

测试文档映射

特殊处理记录映射（防屎山）

强制门禁（新增）：

• 当变更命中手册中已登记的“涉及文件”时，必须同步修改 docs/开发文档/架构设计/防屎山记录手册.md。
• 本地提交门禁：python3 scripts/check_special_doc_sync.py --cached --strict
• CI 门禁：python3 scripts/check_special_doc_sync.py --diff-range origin/<base>...HEAD --strict

测试脚本双向同步规则

核心原则: 测试案例文档 ↔ E2E 脚本必须双向追溯。

脚本模板规范（每个新测试脚本必须包含）:

/**
 * [功能描述]
 * 
 * @test-case TC-XXX-01 [用例名称]
 * @test-case TC-XXX-02 [用例名称]
 * @see docs/开发文档/测试管理/[模块]测试案例.md
 */

脚本与文档位置对应:

跳过条件

• 用户说"直接改代码"
• 纯格式化/重构（不改功能）
• 简单 Bug 修复（不涉及设计）

跳过条件例外（强制）

命中以下任一场景时，禁止套用“跳过条件”，必须同步更新 design/requirements/implementation 三件套：

1. 变更命中 app/ai/**（含 workflow、state、contracts、prompts）。
2. 变更命中跨端事件契约（如 app/ai/events.py、app/services/chat_service.py、web/src/types/**）。
3. 涉及状态字段迁移、契约字段新增/删除、路由门禁语义变化。
4. 涉及灰度开关、回滚策略、验收口径（TC/命令）调整。
5. 涉及产品运行时 Skill（如 app/ai/skills/**、app/data/skills/**、app/services/skill_service.py、app/services/skill_bootstrap_service.py、app/main.py、app/api/v1/endpoints/skill_admin_api.py、app/api/v1/endpoints/user_skill_api.py、app/models/agent_skill.py、app/schemas/user_skill.py、scripts/data/import_skills.py）的真理源、导入、检索、绑定、runtime canonical 或运维口径变化。

配置参数同步门禁（新增）

当变更命中以下任一项时，必须同步更新配置说明文档，禁止只改代码不改文档：

• app/core/config.py
• app/core/config_contract.py
• app/services/config_resolver.py
• install/scripts/init_system_config.py
• scripts/config_doctor.py
• t_system_config 相关初始化/迁移脚本（含 install/**、scripts/**）

强制动作：

1. 更新 docs/开发文档/快速入门/配置说明.md 对应章节（新增键、默认值、读取优先级、运维检查命令）。
2. 涉及 db-dynamic 配置键时，确认 DB 存在主键或兼容别名键，并写明回退口径（DB -> ENV -> 默认值）。
3. 执行 python scripts/config_doctor.py --strict 进行对账，若有缺失项需先补齐再结束任务。

执行流程

分析需求 -> 识别文档 -> 更新文档 -> 确认 -> 编写代码