www
4.2 KiB
4.2 KiB
Work 与代码同步协议 V1
目标：让 Work 的设计世界持续认识 Git + Codex 的代码现实，同时避免把源码和敏感信息塞进知识库。
1. 权责划分
Work 负责
- 产品定位和业务规则。
- 新功能讨论、替代方案和优先级。
- 跨模块架构决策。
- 用户体验、质量标准和未来路线。
- 形成
FEATURE_*.md、ADR 和验收口径。
Git + Codex 负责
- 当前源码和数据库迁移。
- 实现细节和接口事实。
- 自动测试、构建和部署状态。
- 当前生产配置与运行验证。
- 生成状态快照和同步包。
2. 文档层级
L0 PROJECT_STATUS：不可变事实快照
L1 SYSTEM/ENGINE/PIPELINE/DATABASE：当前有效设计
L2 FEATURE/ADR：未来设计和决策
L3 CHANGELOG：已发生变化
L4 历史设计/讨论记录：仅供追溯
L2 不能在代码完成前冒充 L1；L4 不能覆盖 L0。
3. 标准闭环
flowchart LR
Idea[想法] --> Work[Work 讨论]
Work --> Feature[FEATURE/ADR]
Feature --> Codex[Codex 实现]
Codex --> Verify[测试/构建/部署验证]
Verify --> Change[更新 CHANGELOG]
Change --> Domain[更新领域文档]
Domain --> Status[必要时生成新状态快照]
Status --> Upload[上传同步包]
4. 何时更新哪些文档
| 变化 | 必须更新 |
|---|---|
| 小缺陷修复，不改变契约 | CHANGELOG |
| API、状态或领域规则变化 | CHANGELOG + 对应领域文档 |
| 新功能设计、尚未实现 | 新建 FEATURE 文档 |
| 跨模块技术决策 | 新建 ADR |
| Prisma schema 变化 | DATABASE + CHANGELOG + 迁移 |
| Provider/队列/Prompt 机制变化 | AI_PIPELINE + CHANGELOG |
| 小说生产逻辑变化 | NOVEL_ENGINE + CHANGELOG |
| 短剧/视频/合成逻辑变化 | DRAMA_ENGINE + CHANGELOG |
| 架构、部署、测试或风险显著变化 | 新建 PROJECT_STATUS_Vn |
5. 版本规则
- 状态快照：
PROJECT_STATUS_V1.md、V2.md，发布后不可改写事实。 - 当前设计：结构性改变升 V2；旧版本移入历史区或保留只读。
- FEATURE/ADR：决策变化升版本，不覆盖已评审版本。
- CHANGELOG：只追加，不回写历史结论；错误修正新增一条说明。
- 同步批次：
WORK_SYNC_YYYY-MM-DD_Vn。
6. 上传前检查
- 文件只包含当前项目必要信息。
- 没有
.env值、API Key、JWT、密码、签名 URL 和个人数据。 - 状态、数量和测试结果标注采集日期。
- “已实现”“部分实现”“待实现”区分清楚。
- 文档中的模型、路由和队列说法与源码一致。
- 所有文件列入
SYNC_MANIFEST.md并生成 SHA-256。 CHANGELOG.md已追加本批次。- 上传后在 Work 标记批次号和生效日期。
7. Work 讨论新功能的输入模板
当前基线：WORK_SYNC_YYYY-MM-DD_Vn
关联现状：PROJECT_STATUS_Vn
关联领域：<领域文档>
目标：
非目标：
业务规则：
现有约束：
预期用户流程：
数据影响：
API/队列/Provider 影响：
成本与安全：
验收标准：
回滚条件：
8. 交给 Codex 的实现包
Work 讨论结束后，交付内容应至少包括：
- 已确认的 FEATURE/ADR 文件。
- 关联的当前状态和领域文档版本。
- 明确的验收标准。
- 不允许改变的现有行为。
- 是否允许数据库迁移、付费调用和生产重启。
不要只复制一段没有上下文的聊天结论。
9. 冲突处理
文档与代码冲突
先审计源码、迁移和运行状态；确认代码现实后更新状态快照。若代码本身是错误实现，再通过 FEATURE/修复任务改变代码，不能为了让文档“看起来一致”而掩盖差异。
Work 与最新设计冲突
保留两个方案，形成 ADR，记录为什么更改。未经确认的 Work 建议不得直接覆盖当前有效文档。
数据与文档冲突
实时业务数量以数据库只读查询为准；文档快照必须标注日期。
10. 建议节奏
- 每个已上线功能：立即追加 CHANGELOG。
- 每周或每个开发批次：更新受影响领域文档。
- 每次结构性发布：生成新状态快照和同步清单。
- 每月至少一次：检查备份、状态漂移、失败任务和敏感信息。