public-factory-v3 分支 / 简化终稿

12,000 行变更的简化方案

综合三份设计文档的分析，形成本终稿。目标：将 Factory V2 / Factory V3 / Vibe Coding V2 三套并行实现收敛为一套通用 Agent Board 机制， 分 4 个 PR 阶段交付，每个 PR 可独立验证。

三份方案排名

1

agent-board-branch-simplification-plan.html

最务实可执行。 优势：硬编码清单具体到代码行号；7 阶段拆分粒度适合 PR；明确提出"先冻结决策再动手"；PR 边界清晰（第一个 PR 只做命名边界，不碰 UI 大重构）。 劣势：篇幅较长，部分阶段可以合并以减少交付次数。

2

factory-v3-simplification-plan.html（我的原方案）

分析详尽，执行粒度太粗。 优势：有量化数据（3500 行可删、30 个文件）；表格对比清晰；决策问题提得好。 劣势：三步走粒度太大，每步都是 2000+ 行变更的 PR，不适合 review 和验证。

3

agent-board-design-plan.html

架构愿景好，缺乏落地细节。 优势：模块边界定义清晰（Board Domain / TaskRunner / Repo Provider / Entry Adapter）；目标目录结构直观。 劣势：没有识别具体硬编码问题；没有 PR 拆分计划；不了解当前代码的重复细节。

一、前置决策（需确认）

D1: SQLite board-tasks 是唯一主看板

Gitea Issue 不再作为主看板数据源。Gitea 仅保留 Repo Provider 角色（clone / PR / diff / merge / webhook）。 V3 的 Gitea Issue 看板链路（factory_v3.py 的 board CRUD + webhook + label 状态同步）全部删除。

D2: Agent Board 支持非代码任务

Task result 不强制 pr_url。通用结果只需 summary + err_msg；代码任务可额外返回 pr_url、branch 等。 HEADLESS_TASK_OUTPUT_SCHEMA 改为可扩展。

D3: 单工作台入口，删除重复页面

保留一个统一的项目工作台（/projects/:projectId），删除 /factory-v2、/factory-v3 路由。 Vibe Coding V2 作为入口配置（提供默认 Agent、文案），不拥有专属看板实现。

D4: 命名策略

代码层：agent_board。API：/api/agent-board。 数据库表名第一阶段保留 software_factory_v2_*（避免 migration 风险），后续再改。 模型类名立即改：BoardProject / BoardTask / BoardTaskEvent / BoardAgent。

二、硬编码清单（必须处理）

类型 位置 硬编码值 处理方式
Solution ID factory_v3.py (6处)
factory_v2.py (8处)
kanban.go		 "software_factory_v3"
"vibe-coding-v2"		 从 Agent Config / session 参数传入，路由层不绑定
Role ID factory_v3.py 多处 "butler", "default", "sf_manager" 随 V3 Solution 删除一并消失；通用层只读 Agent Config
状态枚举 gitea_client.py:133-140
前端 BoardPanel.tsx:26-34		 status/unassigned ... status/done 删除 Gitea 状态映射；统一用 BoardTaskStatus 枚举
Webhook URL factory_v3.py:222 http://host.docker.internal:8020 随 Gitea Issue 看板链路一并删除
人员列表 FactoryV2BoardPanel.tsx:149 11 个团队成员姓名 改为前端自由输入 + 历史记录
默认 Agent store.py:78 ("default", "Vibe Coding", "vibe-coding-v2", "default", 0) 去 "Vibe Coding" 绑定，改为通用默认名
输出 Schema _factory_v2_runtime.py pr_url 强制字段 改为可选：通用 summary + 可选 pr_url
Autorun 提示词 factory_v3.py:301-317 固定引用 blade skill use git_guide 模板参数化，由 Agent Config 决定工作流步骤
Socket 事件 factory_v2_socket.py
factory_v3.py		 factory-v2:board-task:changed
board:updated		 统一为 agent-board:task:changed

三、执行计划（4 个 PR）

采用 #1 方案的"先确认再动手"策略 + 合并部分阶段以减少交付次数。每个 PR 独立可验证。

1

后端 Agent Board 命名边界 + 删除 Gitea Issue 看板

预计 -900 行 / +200 行（净删 ~700）

动作

  • 新建 host/agent_board/ 目录，将 software_factory_v2/ 的 models/schema/store 迁移过去并改名
  • 新建 server/routes/agent_board.py，从 factory_v2.py 迁移看板 CRUD + autorun
  • 删除 factory_v3.py 整个文件（542 行）
  • 精简 gitea_client.py：删除 Issue/Label 相关方法，保留 Repo/PR 部分 → 改名 gitea_provider.py
  • 删除 factory_v2_socket.py（66 行），Socket 事件统一到 agent_board
  • API prefix 切换：/api/agent-board

验证

uv run pytest 全绿 + 前端 pnpm typecheck 通过 + 手动验证看板 CRUD 和 headless autorun。

2

前端 AgentBoardPanel + 路由收敛

预计 -1400 行 / +100 行（净删 ~1300）

动作

  • FactoryV2BoardPanel.tsx → components/agent-board/AgentBoardPanel.tsx，去硬编码人员名
  • 删除整个 components/factory-v3/ 目录（BoardPanel + ButlerBubble + ButlerProvider + CreateProjectFlow = 913 行）
  • 删除 FactoryV3ProjectPage.tsx + FactoryV3ListPage.tsx（170 行）
  • 路由统一：/factory-v2/:projectId → /projects/:projectId
  • VibeCodingWorkbenchLayout.tsx 改名 → ProjectWorkbenchLayout.tsx，去 "Vibe" 文案
  • 前端 API client 统一指向 /api/agent-board

验证

pnpm lint && pnpm typecheck + 浏览器手动测试看板拖拽、任务创建、autorun 触发。

3

Solution/Skill 合并 + CLI 迁移

预计 -1500 行 / +100 行（净删 ~1400）

动作

  • 删除整个 solutions/builtin/software_factory_v3/ 目录（4 个 role + 16 个 skill）
  • 合并重复 Skill：sf_prd_guide → prd_guide，sf_ui_design_guide → ui_design_guide，sf_tech_design_guide → tech_design_guide
  • Vibe Coding V2 的 factory_v3 Skill → 改为通用 agent_board Skill（描述看板 CLI 用法）
  • blade kanban CLI：API 指向 /api/agent-board，去掉 solution_id 硬编码
  • 创建通用 agent_board Skill（供所有 Solution 引用）

验证

make test (CLI) + uv run pytest + 手动测试 blade kanban 命令在沙盒内可用。

4

TaskRunner 通用化 + 消灭硬编码残留

预计 -300 行 / +150 行（净删 ~150）

动作

  • 从 agent_board.py 抽出 task_runner.py：统一 headless session 创建 → 事件同步 → 状态回写 → 结果解析
  • Autorun 提示词模板参数化：接收 agent_config.prompt_template 或使用默认通用模板
  • 输出 Schema 改为可扩展：基础 {summary, err_msg} + 可选扩展字段
  • 清理残留 _factory_v2_runtime.py、_factory_v2_messages.py
  • Socket 事件名最终统一确认

验证

端到端测试：创建看板任务 → 分配 Agent → 自动触发 headless → 结果回写到卡片 → 前端实时更新。

四、目标目录结构

后端

host/src/blade_agent/host/agent_board/
  models.py            # BoardProject, BoardTask, BoardTaskStatus, BoardTaskEvent, BoardAgent
  schema.py            # SQLite schema (表名暂保留 software_factory_v2_*)
  store.py             # AgentBoardStore
  task_runner.py       # card -> headless session -> events -> result

host/src/blade_agent/host/agent_board/
  gitea_provider.py    # Repo/PR/diff/merge (无 Issue/Label)

server/src/blade_agent/server/routes/
  agent_board.py       # 统一 /api/agent-board 路由
  agent_board_changes.py  # PR 回流 + 代码变更

前端

web/apps/web/src/components/agent-board/
  AgentBoardPanel.tsx      # 通用看板面板
  AgentBoardTaskDialog.tsx # 任务详情
  AgentBoardEvents.tsx     # 事件时间线
  agent-board-api.ts       # API client

web/apps/web/src/layouts/
  ProjectWorkbenchLayout.tsx  # 统一工作台壳

web/apps/web/src/pages/
  ProjectWorkbenchPage.tsx    # /projects/:projectId

五、删除清单

文件/目录 行数 原因 PR
server/routes/factory_v3.py542Gitea Issue 看板主路由#1
server/factory_v2_socket.py66并入统一 socket#1
server/routes/_factory_v2_runtime.py152合并到 task_runner#4
server/routes/_factory_v2_messages.py55合并到 agent_board#4
server/vibe_log_socket.py136并入统一 socket#1
web/components/factory-v3/ (整目录)913Gitea 看板 UI#2
web/pages/FactoryV3ProjectPage.tsx79V3 入口#2
web/pages/FactoryV3ListPage.tsx91V3 列表#2
solutions/builtin/software_factory_v3/ (整目录)~1500V3 Solution#3
合计~3,500

六、量化预估

~3,500

行代码净删除

~30

个文件删除/合并

3 → 1

API prefix 收敛

16 → 8

Skill 去重

待确认

  1. Q1: 决策 D1-D4 是否都同意？有哪条需要调整？
  2. Q2: 普通 Chat 会话是否也可以创建 Board Project？还是仅限工作台入口？
  3. Q3: Butler 角色删除后，V3 的"管家对话 → 创建项目 → 管理看板"这个用户旅程是否需要迁移到主对话？
  4. Q4: 4 个 PR 的顺序是否 OK？还是希望调整优先级？