docs: add execution foundation design

2026-04-02 20:12:26 +08:00
parent 22442979fe
commit 3a45e41b1b
1 changed files with 537 additions and 0 deletions
--- a/docs/superpowers/specs/2026-04-02-boss-execution-foundation-design.md
+++ b/docs/superpowers/specs/2026-04-02-boss-execution-foundation-design.md
@@ -0,0 +1,537 @@
+# Boss 执行底座抽象层重构设计
+
+## 背景
+
+当前 Boss 已经有一条真实可运行的执行链：
+
+- `Web / Android -> /api/v1/projects/[projectId]/messages`
+- `boss-master-agent.ts`
+- `master-agent task queue`
+- `local-agent/server.mjs`
+- `codex exec resume`
+- `/api/v1/master-agent/tasks/[taskId]/complete`
+- 回写消息账本与聚合投影
+
+同时，Boss 已经具备这些上层业务能力：
+
+- 多租户
+- 会话 / 群聊 / 审批
+- 设备导入
+- 主控切换
+- 提示词 / 记忆
+- 附件与分析
+
+但当前执行链存在一个结构性问题：
+
+1. 执行逻辑主要分散在：
+   - `src/lib/boss-master-agent.ts`
+   - `local-agent/server.mjs`
+   - `src/app/api/v1/projects/[projectId]/messages/route.ts`
+   - `src/app/api/v1/master-agent/tasks/[taskId]/complete/route.ts`
+2. 不同执行后端的职责边界不够清晰：
+   - `master-codex-node`
+   - `openai-api`
+   - `aliyun-qwen-api`
+3. 审批、权限、提示词组装、远程执行适配等能力，已经在逻辑上出现，但还没有明确的稳定抽象层。
+4. 后续如果要接入：
+   - `claw-code`
+   - `oh-my-codex`
+   就会面临“边接边重构”的高风险。
+
+因此，Boss 必须先完成一次**执行底座抽象层重构**，把现有生产主链保留下来，同时把执行层拆成稳定接口。
+
+## 目标
+
+本轮目标不是替换任何现有执行后端，而是：
+
+1. 在 Boss 内部定义稳定的执行抽象层
+2. 把现有执行主链映射到这些抽象层上
+3. 保持当前生产主链继续可用
+4. 为后续接入：
+   - `ClawBackendAdapter`
+   - `OmxTeamBackendAdapter`
+   做准备
+
+## 非目标
+
+本轮不做：
+
+- 不直接接入 `claw-code`
+- 不直接接入 `oh-my-codex`
+- 不替换当前 `local-agent -> codex exec resume` 主链
+- 不改 Web / Android 的产品交互
+- 不修改群聊、审批、设备导入的业务语义
+- 不做运行时协议大迁移
+
+## 设计总览
+
+本轮会在 Boss 现有业务层与现有执行实现之间，增加一层稳定接口：
+
+```text
+Boss Product / Domain Layer
+  -> Execution Foundation Layer
+    -> Current Backends
+      -> MasterCodexNodeBackend
+      -> OpenAIBackend
+      -> AliyunQwenBackend
+      -> BossNativeOrchestrator
+```
+
+这层抽象的目标不是把系统复杂化，而是让当前已经存在的能力有清晰边界，避免后续所有能力都继续堆在 `boss-master-agent.ts` 和 `local-agent/server.mjs` 里。
+
+## 需要新增的抽象
+
+### 1. `ExecutionBackend`
+
+职责：
+
+- 统一描述“谁来执行一个实际任务”
+
+适用对象：
+
+- 主 Agent 单聊回复
+- 普通线程单聊回复
+- 附件分析
+- 未来 `claw-code` 单次执行
+
+建议接口：
+
+```ts
+interface ExecutionBackend {
+  backendId: string;
+  canHandle(input: ExecutionRequest): Promise<boolean> | boolean;
+  execute(input: ExecutionRequest): Promise<ExecutionQueuedResult | ExecutionImmediateResult>;
+  describe(input: ExecutionRequest): Promise<ExecutionBackendDescription>;
+}
+```
+
+说明：
+
+- 当前阶段不强制所有 backend 都支持 `cancel` / `resume`
+- 先统一最核心的 `canHandle + execute + describe`
+
+当前映射：
+
+- `MasterCodexNodeBackend`
+- `OpenAIBackend`
+- `AliyunQwenBackend`
+
+### 2. `ExecutionBackendSelector`
+
+职责：
+
+- 根据当前任务上下文选择执行后端
+
+必须考虑：
+
+- 当前主控身份
+- 当前对话模型 / 推理强度覆盖
+- 当前后端健康状态
+- 是否允许回退到备用链
+
+当前映射来源：
+
+- `getMasterAgentRuntimeAccount`
+- `updateAiAccountHealth`
+- `resolveMasterAgentExecutionConfig`
+
+说明：
+
+- 这层只负责“选择谁执行”，不负责组装 prompt，也不负责审批和业务决策
+
+### 3. `SessionRuntime`
+
+职责：
+
+- 统一描述一次执行会话的运行态
+
+当前 Boss 里已经隐式存在这些语义：
+
+- queued
+- running
+- completed
+- failed
+- timeout
+- retry-waiting
+
+本轮不需要引入重型 session store，但要统一成明确结构。
+
+建议接口：
+
+```ts
+interface SessionRuntime {
+  create(input: RuntimeSessionCreateInput): Promise<RuntimeSessionRecord>;
+  markRunning(sessionId: string): Promise<void>;
+  markCompleted(sessionId: string, payload: RuntimeCompletionPayload): Promise<void>;
+  markFailed(sessionId: string, error: RuntimeFailurePayload): Promise<void>;
+  get(sessionId: string): Promise<RuntimeSessionRecord | null>;
+}
+```
+
+说明：
+
+- 当前底层仍可继续落在 `boss-state.json`
+- 本轮重点是统一语义，而不是换存储
+
+### 4. `PermissionPolicy`
+
+职责：
+
+- 统一描述执行权限与审批门槛
+
+当前 Boss 已经有这些隐式能力：
+
+- `approval_required`
+- 群聊是否可直接协作
+- 群聊是否允许直接下发
+- 设备写接口鉴权
+
+这层需要明确回答：
+
+- 当前任务是否允许直接执行
+- 是否必须先确认
+- 允许哪些工具类型
+- 是否允许跨线程直接对话
+
+建议接口：
+
+```ts
+interface PermissionPolicy {
+  evaluate(input: PermissionCheckInput): Promise<PermissionCheckResult>;
+}
+```
+
+其中 `PermissionCheckResult` 至少包含：
+
+- `allowed`
+- `requiresApproval`
+- `reason`
+- `toolPolicy`
+- `collaborationPolicy`
+
+### 5. `ToolRegistry`
+
+职责：
+
+- 统一声明 Boss 可以下发和使用的工具能力
+
+当前不要求真正把工具全部重构出来，但必须定义 registry 层，避免工具能力继续散落在多个 backend 分支里。
+
+建议接口：
+
+```ts
+interface ToolRegistry {
+  list(): Promise<ToolDefinition[]>;
+  get(toolName: string): Promise<ToolDefinition | null>;
+}
+```
+
+说明：
+
+- 本轮可以先只注册最基础的执行工具描述
+- 先不追求完整 MCP / plugin 化
+
+### 6. `PromptAssembler`
+
+职责：
+
+- 统一组装主 Agent 和线程执行时真正输入模型/执行引擎的内容
+
+必须覆盖：
+
+- 管理员全局主提示词
+- 用户私有主提示词
+- 当前对话附加提示词
+- 用户通用记忆
+- 项目记忆
+- 当前运行时上下文
+- 当前消息
+
+说明：
+
+- 当前已有相关逻辑在 `resolveMasterAgentExecutionConfig` 和 `buildMasterAgentExecutionPrompt`
+- 本轮要把它从 backend 逻辑里抽出来，变成独立模块
+
+### 7. `MemoryResolver`
+
+职责：
+
+- 从用户记忆与项目记忆中选出当前真正相关的那一批
+
+这层与 `PromptAssembler` 协作：
+
+- `MemoryResolver` 负责挑选
+- `PromptAssembler` 负责拼装
+
+### 8. `RemoteRuntimeAdapter`
+
+职责：
+
+- 统一连接设备上的远程执行能力
+
+当前来源：
+
+- `local-agent -> codex exec resume`
+
+未来来源：
+
+- `claw remote runtime`
+- `omx team runtime`
+
+建议接口：
+
+```ts
+interface RemoteRuntimeAdapter {
+  claimTask(input: RemoteTaskClaimInput): Promise<RemoteClaimResult>;
+  executeTask(input: RemoteTaskExecutionInput): Promise<RemoteExecutionResult>;
+  completeTask(input: RemoteTaskCompletionInput): Promise<void>;
+  health(): Promise<RemoteRuntimeHealth>;
+}
+```
+
+说明：
+
+- 当前本轮不改变 `local-agent` API 主链
+- 只是让它开始按 adapter 视角组织
+
+### 9. `OrchestrationBackend`
+
+职责：
+
+- 统一描述多线程 / 多 worker / 群聊分发级别的编排能力
+
+当前来源：
+
+- Boss 自己已有的群聊 dispatch / approval / execution 逻辑
+
+未来候选：
+
+- `BossNativeOrchestrator`
+- `OmxTeamBackendAdapter`
+
+说明：
+
+- 这层只负责编排，不负责底层单次执行
+- 与 `ExecutionBackend` 明确分层
+
+## 当前代码的映射关系
+
+### 1. 现有保留不动的主链
+
+这些主链行为本轮必须保持不变：
+
+- `POST /api/v1/projects/[projectId]/messages`
+- `master-agent` 单聊快速入队 + 异步回流
+- 普通线程单聊 `conversation_reply`
+- 群聊 `dispatch_execution`
+- `/api/v1/master-agent/tasks/claim`
+- `/api/v1/master-agent/tasks/[taskId]/complete`
+- `local-agent` 的 `codex exec resume`
+
+### 2. 主要重构落点
+
+首批落点文件预计包括：
+
+- `src/lib/boss-master-agent.ts`
+- `src/lib/boss-data.ts`
+- `local-agent/server.mjs`
+- `src/app/api/v1/projects/[projectId]/messages/route.ts`
+- `src/app/api/v1/master-agent/tasks/[taskId]/complete/route.ts`
+
+新增模块建议集中放在：
+
+- `src/lib/execution/`
+
+建议初始文件：
+
+- `src/lib/execution/types.ts`
+- `src/lib/execution/execution-backend.ts`
+- `src/lib/execution/backend-selector.ts`
+- `src/lib/execution/prompt-assembler.ts`
+- `src/lib/execution/memory-resolver.ts`
+- `src/lib/execution/permission-policy.ts`
+- `src/lib/execution/tool-registry.ts`
+- `src/lib/execution/remote-runtime-adapter.ts`
+- `src/lib/execution/orchestration-backend.ts`
+
+### 3. 适配策略
+
+本轮不要求一次性把所有旧逻辑迁完。
+
+建议策略：
+
+1. 先新增抽象层与默认实现
+2. 先让 `master-agent` 单聊走新抽象
+3. 再把普通线程单聊映射进去
+4. 再把群聊 dispatch 的底层执行链映射进去
+
+也就是说：
+
+- **先平移，不先改行为**
+
+## 数据与状态设计
+
+### 1. 执行请求
+
+建议定义统一执行输入：
+
+```ts
+type ExecutionRequestKind =
+  | "master_agent_reply"
+  | "thread_reply"
+  | "dispatch_execution"
+  | "attachment_analysis";
+
+interface ExecutionRequest {
+  kind: ExecutionRequestKind;
+  projectId: string;
+  requestMessageId: string;
+  requestedByAccount?: string;
+  requestedByLabel?: string;
+  taskId?: string;
+  targetThreadId?: string;
+  targetProjectId?: string;
+  body: string;
+  modelOverride?: string;
+  reasoningEffortOverride?: "low" | "medium" | "high";
+}
+```
+
+### 2. 执行结果
+
+建议统一执行结果：
+
+```ts
+type ExecutionResultStatus = "queued" | "running" | "completed" | "failed";
+
+interface ExecutionQueuedResult {
+  status: "queued" | "running";
+  taskId: string;
+  backendId: string;
+  sessionId?: string;
+}
+
+interface ExecutionImmediateResult {
+  status: "completed" | "failed";
+  backendId: string;
+  output?: string;
+  error?: string;
+}
+```
+
+### 3. 权限结果
+
+```ts
+interface PermissionCheckResult {
+  allowed: boolean;
+  requiresApproval: boolean;
+  reason?: string;
+  toolPolicy: {
+    allowedTools: string[];
+    deniedTools: string[];
+  };
+  collaborationPolicy: {
+    mode: "development" | "approval_required";
+    canDispatchDirectly: boolean;
+    canCrossThreadTalk: boolean;
+  };
+}
+```
+
+## 分期落地
+
+### Phase 1：抽象定义 + 默认实现
+
+输出：
+
+- 所有接口定义
+- 当前 Boss 原生执行链的默认实现
+
+要求：
+
+- 行为不变
+- 现有测试继续通过
+
+### Phase 2：主 Agent 单聊迁移到新抽象
+
+输出：
+
+- `master-agent` 单聊通过 `ExecutionBackendSelector + PromptAssembler + PermissionPolicy`
+
+要求：
+
+- 前台行为不变
+- 仍然快速入队 + 异步回流
+
+### Phase 3：普通线程与群聊底层执行迁移
+
+输出：
+
+- 普通线程单聊
+- 群聊 dispatch execution
+
+要求：
+
+- 不破坏 approval_required
+- 不破坏群聊修复成员主链
+
+### Phase 4：为外部 adapter 预留接入点
+
+输出：
+
+- `ClawBackendAdapter` 所需 contract ready
+- `OmxTeamBackendAdapter` 所需 contract ready
+
+本轮仍然不要求实际接入。
+
+## 风险
+
+### 1. 结构重构风险
+
+如果一口气把所有旧逻辑迁完，极容易破坏：
+
+- 主 Agent 单聊
+- 普通线程回复
+- 群聊 dispatch
+- 设备导入
+
+因此必须采用：
+
+- 先定义抽象
+- 再做行为等价迁移
+
+### 2. 语义混淆风险
+
+最大的风险不是代码量，而是把两类后端混在一起：
+
+- `ExecutionBackend`
+- `OrchestrationBackend`
+
+这两类必须严格分层。
+
+### 3. 文档和实现偏离风险
+
+如果文档只写“以后会有抽象层”，但实现不跟进，后面再接 `claw-code` 和 `oh-my-codex` 时仍然会重新失控。
+
+因此本 spec 的验收必须以“接口和默认实现真正落地”为准。
+
+## 验收标准
+
+只有满足下面条件，才算这轮抽象层重构设计正确：
+
+1. Boss 现有生产主链不被替换
+2. `master-agent`、普通线程、群聊 dispatch 都能映射到统一执行抽象
+3. 提示词、记忆、权限、远程执行不再继续散在单个大文件里
+4. 单线程执行与多线程编排分层明确
+5. 后续接 `claw-code` 与 `oh-my-codex` 时，不需要再先重做 Boss 主链
+
+## 下一步
+
+这份 spec 之后，下一份实现计划建议拆成 4 个任务：
+
+1. 抽 `ExecutionBackend / ExecutionBackendSelector`
+2. 抽 `PromptAssembler / MemoryResolver`
+3. 抽 `PermissionPolicy / ToolRegistry`
+4. 抽 `RemoteRuntimeAdapter / OrchestrationBackend`
+
+只有这 4 步完成后，才建议开始 `ClawBackendAdapter` 的最小接入设计。