docs: add execution foundation design
This commit is contained in:
kris
@@ -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` 的最小接入设计。
|
||||
Reference in New Issue
Block a user