跳到主要内容

SayClaw 仓库收敛计划（v1）

1. 目标​

在不影响线上稳定性的前提下，完成以下收敛：

  • 明确 8 仓职责边界，消除重复实现。
  • 统一认证、配置、调度与发布规范。
  • 建立“计划-提交-验收”闭环，避免口径漂移。

2. 当前仓库（基线）​

  1. sayclaw/sayclaw（主仓）
  2. sayclaw/sayclaw-docs（文档）
  3. sayclaw/sayclaw-infra（基础设施）
  4. sayclaw/sayclaw-ops（运维脚本）
  5. sayclaw/sayclaw-admin（后台前端）
  6. sayclaw/sayclaw-backend（Admin API + Portal API）
  7. sayclaw/sayclaw-app（Portal 前端 SPA）
  8. sayclaw/sayclaw-portal（Portal API Go）

3. 收敛原则​

  1. 单一事实源：每一类能力只允许 1 个“主实现仓”。
  2. 安全优先：先完成密钥/鉴权/CORS整改。
  3. 可回滚：每次合并都可独立回退。
  4. 分支约束：AI 改动统一先在 wangcai 分支提交。

4. 决策待办（D0 必须拍板）​

  • Portal API 以 sayclaw-backend/portal-api 还是 sayclaw-portal 为主？
  • Portal 前端以 sayclaw-app 还是 sayclaw/apps/sayclaw-portal-frontend 为主？
  • 队列表标准名：task_queue 还是 admin_tasks？
  • 认证统一入口：Google IAP / OIDC 验签实现位置。

5. 两周执行路线​

Week 1：安全与边界冻结​

  • D1-D2：冻结主实现仓（写 ADR）
  • D2-D3：移除硬编码 secrets（改 Secret Manager / CI Variables）
  • D3-D4：统一鉴权中间件（admin + portal）
  • D4-D5：统一 CORS 白名单与环境配置

交付物：

  • ADR 文档
  • 安全整改 MR
  • 鉴权统一 MR

Week 2：代码收敛与发布闭环​

  • D6-D8：重复模块归并（Portal API/Portal FE）
  • D8-D9：调度模型与任务状态机统一
  • D9-D10：补回归矩阵 + 发布清单 + 回滚演练

交付物：

  • 收敛 MR（含迁移说明）
  • 回归报告
  • 发布与回滚手册

6. 风险与应对​

  • 风险：收敛导致短期开发停滞

    • 应对：双轨制（维护分支 + 收敛分支）

  • 风险：接口变更影响前端

    • 应对：先适配层，后替换主链路

  • 风险：文档落后于代码

    • 应对：MR 模板增加“文档变更检查项”

7. 完成定义（DoD）​

  • 每个能力只有 1 个主实现仓。
  • 无生产可用默认密钥。
  • 统一鉴权与 CORS 生效。
  • 发布流程具备可验证回滚。
  • 文档与代码一致性通过抽检。