Skip to content

Project First Refactor Log

Jump to bottom
uplusplus edited this page Apr 14, 2026 · 3 revisions

Project-First Refactor Log

最后更新: 2026-04-14 14:27 GMT+8

重构目标

把 Catown 从以 chatroom/message + pipeline 为中心的旧架构，重构为以 Project / Asset / Decision / StageRun 为中心的新内核。

核心目标：

  • 让 Project 成为真正的业务主语
  • 让 Asset 承载核心产出和上下文
  • 让 Decision 成为显式 gate
  • 让 StageRun 成为统一的推进记录
  • 让旧 chatroom 和 pipeline 降级为协作层/执行层，而不是产品主骨架

当前状态

已完成

  • 完成现状审计，确认旧系统主轴仍是 chatroom/message + pipeline
  • 形成完整 ADR 链，锁定新核心模型、主 API、迁移映射、Schema、服务层拆分方向
  • 在后端新增 /api/v2，与 legacy API 并行
  • 在数据库中补齐项目优先的核心模型与关系模型
  • 跑通最小可运行主链：
    • 创建项目
    • 生成 project_brief
    • scope_confirmation
    • product_definition
    • build_execution
    • qa_validation
    • release_preparation
    • release_approval
    • released
  • 持久化资产、阶段、决策之间的关系：
    • StageRunAsset
    • DecisionAsset
    • AssetLink
  • 补齐 v2 读模型：
    • GET /api/v2/dashboard
    • GET /api/v2/projects/{id}/overview
    • GET /api/v2/assets/{id}
    • GET /api/v2/stage-runs/{id}
  • 标准化 dashboard 卡片协议：
    • project_cards.release_readiness
    • release_readiness.next_gate
    • awaiting_release_approval 等更明确状态
  • 抽出第一批 coordinator / read-model builder：
    • backend/orchestration/project_flow_coordinator.py
    • backend/orchestration/decision_effects.py
    • backend/read_models/project_views.py
  • 抽出初始项目启动 coordinator：
    • backend/orchestration/project_bootstrap_coordinator.py
    • create_project() 的首轮 briefing -> project_brief -> scope_confirmation 初始化不再内联在 ProjectService
  • 统一 stage lifecycle 基础语义：
    • phase
    • is_active
    • is_terminal
    • requires_attention
  • 收紧 v2 资产依赖链：
    • build_artifact <- prd + ux_blueprint + tech_spec
    • release_pack <- build_artifact + test_report
  • 建立新的 project-first execution kernel：
    • backend/execution/stage_execution_kernel.py
    • backend/execution/bootstrap_stage_executor.py
  • 明确 legacy_pipeline_adapter 不再是默认路线；旧 pipeline/ 改为待审查资产
  • 完成 pipeline 文件级去留审计：保留 / 改造 / 废弃
  • 抽出第一批 runtime primitive：
    • backend/execution/workspace_guard.py
    • backend/execution/event_log.py
  • 为新内核补最小执行 contract：StageExecutionResult
  • 为 StageRun 补最小事件/指令入口：
    • GET /api/v2/stage-runs/{id}/events
    • POST /api/v2/stage-runs/{id}/instructions
  • 让 Event 初步挂到 project-first 语义：
    • project_id
    • stage_run_id
    • asset_id

进行中

  • 继续把可复用 runtime primitive 从 backend/pipeline/engine.py 抽成独立薄模块
  • 明确 autopilot / checkpoint 在新 kernel 层的分流点
  • 为真实 stage executor 设计完整输入/输出 contract
  • 为新内核补 tasks / agent_runs / audit 的挂接策略
  • 前端逐步去 pipeline 化，Mission Board 替代旧 pipeline dashboard 主视图

当前阻塞

  • 本地环境缺少完整运行依赖，无法做完整回归：
    • pytest: command not found
    • /usr/bin/python3: No module named pytest
    • ModuleNotFoundError: No module named 'openai'
  • 当前主要依赖静态校验：python3 -m py_compile ...

最新关键提交

  • 1e4a9aa Tighten asset dependency flow for v2 stages
  • 3640d19 Introduce a project-first stage execution kernel
  • 056b5d8 Audit legacy pipeline and extract workspace guards
  • 541d17e Add project-first stage events and executor contract
  • e58539e Log refactor progress and extract shared event sink
  • 3935398 Standardize v2 dashboard cards and extract flow coordinator
  • 97e87fd Extract decision effects and normalize stage lifecycle
  • 2381a45 Extract stage execution and project read models
  • 40ca886 Extract initial project bootstrap coordinator

这些提交意味着：

  • 新主轴已经从“给旧 pipeline 做桥”切换到“建设新的 stage execution kernel”
  • stage 执行、资产关系、事件记录已经开始围绕 Project / Asset / Decision / StageRun 重新组织
  • 旧 pipeline/engine.py 正在被拆成可回收的薄能力，而不是继续作为默认继承对象
  • continue_project() 已不再直接把推进逻辑塞在 ProjectService 中
  • resolve_decision() 的 scope/release 副作用已经拆进独立 coordinator
  • create_project() 的首轮 bootstrap 也已经拆进独立 coordinator
  • stage bootstrap / asset generation 已经从 service 主体中抽离
  • dashboard / overview 聚合已经转入 read-model builder

关键文档

  • docs/ADR-015-current-architecture-gap-analysis.md
  • docs/ADR-020-service-layer-and-implementation-plan.md
  • docs/ADR-021-pipeline-disposition-and-stage-execution-kernel.md
  • docs/pipeline-file-audit.md
  • docs/worklog-2026-04-14-project-first-refactor.md

P0 - 当前主线

  • 新建 asset_service，下沉：
    • 资产创建/换版
    • 资产依赖链接
    • 审批状态更新
  • 新建 decision_service，下沉：
    • 决策创建
    • 决策读取
    • resolve 前置校验
  • 新建 stage_run_service，下沉：
    • stage run 排队
    • stage run 状态迁移
    • stage input/output 关系补写
  • 继续把 create_project / continue_project / resolve_decision 三条主路径收束成更薄的 application service 入口

P1 - 连接旧能力

  • 评估旧 pipeline 执行引擎中可复用能力
  • 设计 legacy_pipeline_adapter / stage_execution_adapter
  • 把 bootstrap 产物生成逐步替换为真实执行接线
  • 先把 bootstrap_stage_executor.py 内联的阶段产物描述拆成更清晰的 stage spec / asset recipe

P1 - 前端契约

  • 固化 project_cards 字段集，避免继续漂移
  • 固化 overview 中：
    • release_readiness
    • recommended_next_action
    • stage_summary
    • recent_activity
  • 规划前端主入口从 legacy 项目壳迁移到 v2 项目中心视图

P2 - 迁移与验证

  • 设计 legacy 数据到新模型的迁移脚本
  • 在依赖补齐后运行真实 route/API 测试
  • 增加更细的 service/coordinator 层回归测试
  • 当前环境恢复 pytest 后，补一次 backend/tests/test_api_routes.py 的完整回归

当前判断

这次重构最重要的进展，不只是“多了几个接口”，而是业务骨架已经开始真正脱离旧 chatroom/pipeline 世界观。

当前状态可以概括为：

  • 新内核已立住
  • 最小闭环已能跑
  • 执行层边界开始清晰
  • 当前重点转为：继续抽离旧 runtime primitive，补真实 executor contract，并逐步去 pipeline 化前端主视图

Clone this wiki locally