aps-agent/docs/adr/0001-tech-stack-and-repo.md

ADR-0001：采用原地重写 + 孤儿分支，历史从零开始

• 状态：已接受
• 日期：2026-09-22
• 决策人：
• 相关：任务表 A0.1、A0.2；设计文档《架构设计》第 2 节

背景

现有仓库是「APS 产品 + 内嵌智能体层」的混合实现：网关一个文件 5232 行、数据库 18 张表混装平台与 APS 数据、APS 领域有 14 个文件反向依赖智能体层。重构的目标是把平台与 APS 拆开，平台从零重写。

同时有两项硬约束：APS 的求解依赖 Python 生态（OR-Tools CP-SAT 在 TS 侧没有等价实现），所以 APS 只能搬迁适配、不能重写；旧系统仍在生产使用，切换必须可回退。

选项

选项	做法	代价	不选的理由
A 新仓库重写	另建仓库写新平台	历史干净、体积归零	issue、CI、权限、制品发布都要重搭，两仓库协同复杂
B 原地重写，继承历史	从 main 切分支继续写	切换简单	git log 与 blame 混着旧历史，"从零"名不副实
C 原地重写，孤儿分支	同一仓库，新分支无父提交	切换需强推，回退依赖备份分支	选定

结论

选 C。同一仓库建孤儿分支 rewrite/platform：工作区从 main 的内容出发，但提交历史从首个提交 b878fd6 开始，不继承旧历史。切换时以本分支强推覆盖 main（--force-with-lease），切换前把 main 备份为 legacy/main 并设为只读。

理由是两条同时满足：既保留原仓库的 issue、CI、权限与制品通道，又让新分支的历史真正从零开始。

影响

• 对代码：新分支只保留工程配置（.gitignore、.dockerignore、.env.example），目录按 client/、server/、providers/、contracts/ 重建
• 对任务：A1.1 脚手架与 A1.6 CI 基线都依赖 A0.2 的分支与 CI 分流规则；A0.10 的设计文档随本分支首个提交入库
• 对文档：设计文档第 2 节的项目结构以此为准
• 不这么做的后果：选 A 会把管理成本前移且长期并行两套仓库；选 B 会让新代码的每一行 blame 都落在不该负责的旧提交上

遗留

• legacy/main 备份分支的创建与只读设置：切换前执行，见 A0.2
• 孤儿历史不会减小仓库体积（旧对象仍在对象库）；要体积归零只能另立仓库，本次不做
• 移植旧逻辑时在提交信息里写明 移植自 main:<path>，否则 git blame 追不到来源