Factory V3 → Main 分批搬运计划

源分支：public-factory-v3 · 策略：新旧并存，不删除旧模块

核心原则

不删除任何旧模块（host/src/blade_agent/host/software_factory/、host/src/blade_agent/host/software_factory_v2/、host/src/blade_agent/host/vibe_coding/）及旧 Solution（host/src/blade_agent/host/solutions/builtin/software_factory/、host/src/blade_agent/host/solutions/builtin/vibe-coding-v2/）
不 rename 旧数据库表 —— AgentBoard 用全新表名，software_factory_v2_* 旧表不动
不移除旧路由（/api/software-factory/*、/api/factory-v2/*、/api/vibe-coding/*）和旧前端页面（/factory/*、/factory-v2/*），新路由并行注册
/chat 页面切到 V3 后端，旧页面保留可访问
不能直接 cherry-pick 整文件：source 分支已删旧代码，并存时必须手工合并，只追加新内容
如果 rest.ts 等类型文件是由 OpenAPI 生成的，新增并存路由后需重新生成，不能直接搬 source 版本（source 已删旧 API paths）

低风险第 1 批：基础协议与数据层

纯新增，无破坏。包含 AgentBoard 数据层、全局依赖注入、聊天协议扩展、Solution 热重载

改动	说明	并存注意
`host/src/blade_agent/host/agent_board/` 数据层	新模块，新表名	必须删除 `schema.py` 中的 `_rename_legacy_tables()` 调用和 rename 映射；增加测试证明 `software_factory_v2_*` 旧表不被改名
`deps.py`	新增 `AgentBoardStore`、`get_agent_board_store()`、`set_socketio_server`、`get_socketio_server()`	必须保留 main 已有的 `get_software_factory_store()`、`get_factory_v2_store()`、`get_vibe_coding_store()` 和 `set_network_env_getter`
`bridge.py` 新增 `create_socket_bridge`	工厂函数	无冲突
`ChatRequest.display_message` 字段	可选字段，默认 None	链路横跨 `chat_types.py`、`_chat_service.py`、`orchestrator/chat.py`、`socket_schemas/__init__.py`、`socketio_handlers.py` 和 AgentBoard route，需一并搬运
`Engine.reload_solution_registry()`	新增方法，支持 Solution 热重载	无冲突
还需搬运的支撑文件：`orchestrator/headless_setup.py`、`tool_host/headless.py`（submit_result 增强）、`projections/_history_dispatch.py`、`fork_resume.py`、`tool_host/fork.py`、`_engine_session_create.py`

低风险第 2 批：`app-dev` Solution + PromptBuilder + 新 Skills

新增 Solution 目录，PromptBuilder 增加 Solution 分支逻辑。需紧跟第 1 批，不能晚于第 3 批验收

改动	说明	并存注意
`host/src/blade_agent/host/solutions/builtin/app-dev/` 整个目录	新 Solution	保留 `vibe-coding-v2/` 和 `software_factory/` 不动
新增 skills（agent_board、agent_native_app_guide 等）	新 skill 文档	无冲突
`prompt.py` 新增 `has_solution_prompt` 分支	Solution 走精简路径，非 Solution 走原路径	保留 `agent_name` / `agent_identity` 参数，仅在非 Solution 路径使用
`_wrap_solution_agents_md` / `_wrap_context_agents_md`	新增静态方法	无冲突
`MEDIA:` 语法	不删除	旧会话可能依赖
`engine.py`	不删除 `agent_name` / `agent_identity` 传参	保持原样
headless `submit_result.description` 提示词增强	兼容增强	无冲突
需补齐测试：`host/tests/test_engine_solution_hot_reload.py`、`host/tests/test_prompt_builder_solution.py`

中风险第 3 批：AgentBoard REST/Socket 路由层（并行注册）

新增路由，不替换旧路由。依赖第 1 批数据层、Socket.IO 基础，以及第 2 批的 app-dev solution id 可解析（否则项目初始化 session 会失败）

改动	说明	并存注意
`server/src/blade_agent/server/routes/agent_board.py`	新路由 `/api/agent-board/*`	保留旧路由文件 `software_factory.py`、`factory_v2.py`、`vide_coding.py`（文件名是 vide，API 前缀是 `/api/vibe-coding`）
`routes/agent_board_changes.py`	变更事件流	同上
`routes/agent_board_git.py`	Git 操作路由	同上
`routes/_agent_board_messages.py`、`_agent_board_runtime.py`	辅助模块，必须一起搬	无冲突
`routes/gitea_client.py`	Gitea API 封装，位于 `server/routes/` 下，不在项目根或 service 层	无冲突
`server/src/blade_agent/server/socket_schemas/__init__.py`	新增 agent-board socket schema	无冲突
`agent_board_socket.py`	新增	无冲突
`app.py` 路由注册	手工追加 3 个 agent_board router	不能 cherry-pick 整文件（source 已删旧 import），须保留 `software_factory`、`factory_v2`、`vide_coding` 的 include_router
`socketio_handlers.py`	新增 agent-board 事件	不删除 V2 socket 事件
`sandbox_port_pool.py`	不改	保留端口回收逻辑
需补齐测试：`tests/test_agent_board_schema.py`、`tests/test_agent_board_archive.py`、`tests/test_server_session_file_routes.py`；并新增旧路由仍可访问、旧表未 rename 的回归测试

低风险第 4 批：CLI `blade kanban`

纯新增命令。代码可先搬，但功能验收依赖第 3 批的 /api/agent-board/* 路由

改动	说明
`kanban.go` + `kanban_project.go` + 测试	新命令组：list / get / create / update / project
`client.go` 新增 `Patch()`	向后兼容
`root.go` 注册	一行注册

高风险第 5 批：前端并存

最复杂的一批，依赖第 2、3 批同时可用。不能套用 source 分支的删除式 diff，必须手工保留旧页面、路由和 SDK exports

改动	说明	并存注意
新增 `AgentBoardPage.tsx`、`AgentBoardProjectPage.tsx`	新页面	无冲突
新增 `agent-board-api.ts`	新 API 层	无冲突
`App.tsx` 新增路由	实际路由包括：`/projects/new`、`/studio/app-dev` → `/projects/new`、`/p/:projectId/tasks...`、`/p/:projectId/chat...`、`/p/:projectId/git/pulls...`、`/p/:projectId/files`、`/p/:projectId/publish`、`/p/:projectId/service(s)` → publish，以及兼容的 `/agent-board/:projectId...`	保留 `/factory/`、`/factory-v2/` 旧路由
`/chat` 页面后端切换	不是简单的切换：`/chat` 仍路由到 `HomePage`，实际需改的是 `HomePage`、`HomeInput.tsx`、`HomeSidebar.tsx`、`GlobalHeader.tsx`、`SolutionShell.tsx`、`ChatRouteBridge.tsx`，将 `vibe-coding-v2` / `factory-v2` 桥接改为 `app-dev` / `agent-board`	核心切换点，需逐文件确认
`SubmitResultRenderer.tsx`	新增工具渲染组件	无冲突
agent-kit 改动	涉及 `client/types/rest.ts`、`client/types/socket-events.ts`、`react/sockets/event-bridge.ts`、`react/stores/chat-store.ts`、`react/stores/ui-store.ts`、`react/components/chat/tool-renderers/registry.ts`、`react/components/workspace/*`、`react/schemas/session.ts`	不能删除 `software-factory` 和 `vibe-coding` 的 resource exports
还需搬运的前端文件：`app.css`、`RightPanel.tsx`、`LeftPanel.tsx`、`WorkspaceFilesPanel.tsx`、`AgentBoardHeader.tsx`、`AppDevBoardPanel.tsx`、`AppDevPreviewPanel.tsx`、`AccessUrlPanel.tsx`、`components/ui/button.tsx`、`components/ui/tooltip.tsx`；并新增旧 agent-kit exports 仍存在的回归测试
旧页面和 client	不删除	保留 `/factory/*` 可访问

高风险第 6 批：沙盒持久化改造

独立批次，涉及 persistent container 的生命周期、挂载和 label，需高风险验收。是否最后做取决于 app-dev 项目是否必须依赖新的持久容器语义

改动	说明	并存注意
persistent session 沙盒路径	新分支逻辑	只在 `is_persistent=True` 时激活
沙盒核心文件	实际涉及 `host/src/blade_agent/host/sandbox/docker.py`、`docker_container_create.py`、`_docker_reaper.py`、`_docker_mount_validation.py` 和 `server/src/blade_agent/services/sandbox_port_pool.py`	涉及 persistent container 的生命周期、挂载和 label，改动范围大于预期
Blade CLI 陈旧检测	增强	无冲突
`PortChangeNotificationHook`	不动	旧路径仍需要
`ChatOrchestrator.set_port_allocator`	不动	旧路径仍需要
验收覆盖：端口回收、session 删除、容器重启后恢复、Blade CLI stale rebuild。需补齐测试 `host/tests/test_docker_persistent.py`

明确不搬的东西

删除 TemplateId.VIBE_CODING
删除 software_factory/、software_factory_v2/、vibe_coding/ 模块
删除旧路由（/api/software-factory/*、/api/factory-v2/*、/api/vibe-coding/*）
删除旧前端页面和路由（/factory/*、/factory-v2/*）
API key 前缀从 v3 回退到 v2
删除 MEDIA: 语法
FileCardComponent.tsx 删除
AgentBoard schema 里的旧表 rename 逻辑
删除 agent-kit 中 software-factory / vibe-coding 的 resource exports

批次依赖关系

第 1 批 (基础协议与数据)
  ├── 第 2 批 (app-dev Solution + PromptBuilder) ── 紧跟第 1 批
  │     └── 第 3 批 (AgentBoard REST/Socket) ── 依赖第 1 批数据层 + 第 2 批 solution id
  │           └── 第 5 批 (前端并存) ── 依赖第 2、3 批同时可用
  └── 第 4 批 (CLI kanban) ── 代码可先搬，功能验收依赖第 3 批

第 6 批 (沙盒持久化) ── 独立，高风险验收
  取决于 app-dev 是否必须依赖持久容器语义

Factory V3 → Main 分批搬运计划

核心原则

低风险 第 1 批：基础协议与数据层

低风险 第 2 批：app-dev Solution + PromptBuilder + 新 Skills

中风险 第 3 批：AgentBoard REST/Socket 路由层（并行注册）

低风险 第 4 批：CLI blade kanban

高风险 第 5 批：前端并存

高风险 第 6 批：沙盒持久化改造