# 四维配置重构方案

## 1. 问题：当前四维架构的配置膨胀

当前架构的四维是 **实现者视角**（协议 / 传输 / 生命周期 / 身份），导致：

- 10 个 launcher（kimi-local / claude-local / kimi-docker / claude-docker / kimi-bridge / ...）
- 4 个 cliBackend（claude-cli / gemini-cli / kimi-cli / codex-cli）
- 20 个 agent（同一个 coder prompt 因为 launcher × 部署方式排列组合出 7 个变体）

根本原因：**客户端 × 部署方式被混在了 launcher 一个维度里，没有真正正交。**

---

## 2. 目标：用户视角的四维配置

| 维度       | 用户问题       | 配置字段 | 配置值                                                 |
| ---------- | -------------- | -------- | ------------------------------------------------------ |
| **角色**   | 我是什么类型？ | type     | executor / validator / master / gateway / orchestrator |
| **能力**   | 我会什么？     | prompt   | ./agents/coder.md / ./agents/verifier.md / ...         |
| **客户端** | 用什么 AI？    | client   | kimi / claude / gemini / codex                         |
| **部署**   | 在哪跑？       | deploy   | local / docker / remote                                |

加一个可选维度：

| 维度     | 说明     | 配置值                               |
| -------- | -------- | ------------------------------------ |
| **模式** | 通信方式 | cli（简单调用）/ acp（长连接双向流） |

### 推断规则（系统内部，用户不需要配）

```
protocol  = client.acp_protocol   (claude → claude-stream, 其余 → acp)
transport = deploy === 'local' ? 'pipe' : 'websocket'
launcher  = { local: 'process', docker: 'docker', remote: 'none' }[deploy]
```

### 重构后的 Agent 定义

```jsonc
// 之前 — 7 个 agent 做同一件事
{
  "kimi-coder":           { "type": "executor", "protocol": "acp", "transport": "pipe", "launcher": "kimi-local", "prompt": "./agents/coder.md" },
  "claude-coder":         { "type": "executor", "protocol": "claude-stream", "transport": "pipe", "launcher": "claude-local", "prompt": "./agents/coder.md" },
  "kimi-docker-coder":    { "type": "executor", "protocol": "acp", "transport": "websocket", "launcher": "kimi-docker", "prompt": "./agents/coder.md" },
  "claude-engine-coder":  { "type": "executor", "cliBackend": "claude-cli", "prompt": "./agents/coder.md" },
  "kimi-engine-coder":    { "type": "executor", "cliBackend": "kimi-cli", "prompt": "./agents/coder.md" },
  // ... 还有更多变体
}

// 之后 — 1 个 agent，想换 AI 或部署方式只改一个字段
{
  "coder": {
    "type": "executor",
    "client": "kimi",       // 换成 "claude" 就用 Claude
    "deploy": "local",      // 换成 "docker" 就跑容器
    "mode": "cli",          // 换成 "acp" 就走长连接
    "prompt": "./agents/coder.md",
    "description": "程序员"
  }
}
```

---

## 3. 新 DB Schema

### 3.1 删除旧表（破坏性）

```sql
DROP TABLE IF EXISTS agent_launchers CASCADE;
DROP TABLE IF EXISTS agent_cli_backends CASCADE;
```

### 3.2 新建 `agent_clients` 表

一个 client = 一个 AI 工具（kimi / claude / gemini / codex）的全部运行配置。

```sql
CREATE TABLE agent_clients (
    name            VARCHAR(100) PRIMARY KEY,   -- 'kimi', 'claude', 'gemini', 'codex'
    command         VARCHAR(200) NOT NULL,       -- CLI 命令: 'kimi', 'claude', 'gemini', 'codex'

    -- ═══ ACP 模式配置（mode=acp 时使用）═══
    acp_args        JSONB DEFAULT '[]',          -- ['acp'] / ['--input-format', 'stream-json', ...]
    acp_protocol    VARCHAR(30) DEFAULT 'acp',   -- 推断用: 'acp' | 'claude-stream'

    -- ═══ CLI 模式配置（mode=cli 时使用）═══
    cli_args            JSONB DEFAULT '[]',      -- ['--print', '--output-format', 'json', ...]
    cli_resume_args     JSONB,                   -- 恢复执行参数
    cli_input           VARCHAR(20) DEFAULT 'arg',
    cli_output          VARCHAR(20) DEFAULT 'text',
    cli_resume_output   VARCHAR(20),
    cli_model_arg       VARCHAR(50),
    cli_session_id_fields JSONB,
    cli_system_prompt_arg VARCHAR(50),
    cli_system_prompt_when VARCHAR(20),
    cli_session_mode    VARCHAR(20) DEFAULT 'none',
    cli_image_arg       VARCHAR(50),
    cli_image_mode      VARCHAR(20),

    -- ═══ Docker 部署配置（deploy=docker 时使用）═══
    docker_image    VARCHAR(200),
    docker_port     INTEGER DEFAULT 9001,
    docker_env_file VARCHAR(500),
    docker_volumes  JSONB DEFAULT '[]',

    -- ═══ Remote 部署配置（deploy=remote 时使用）═══
    remote_url      VARCHAR(500),

    -- ═══ 通用 ═══
    reliability     JSONB DEFAULT '{}',
    is_builtin      BOOLEAN DEFAULT false,
    created_at      TIMESTAMP DEFAULT NOW(),
    updated_at      TIMESTAMP DEFAULT NOW()
);
```

### 3.3 修改 `agent_definitions`

```sql
-- 删除旧列
ALTER TABLE agent_definitions DROP COLUMN IF EXISTS protocol;
ALTER TABLE agent_definitions DROP COLUMN IF EXISTS transport;
ALTER TABLE agent_definitions DROP COLUMN IF EXISTS launcher;
ALTER TABLE agent_definitions DROP COLUMN IF EXISTS cli_backend;

-- 新增列
ALTER TABLE agent_definitions ADD COLUMN IF NOT EXISTS client VARCHAR(100) REFERENCES agent_clients(name);
ALTER TABLE agent_definitions ADD COLUMN IF NOT EXISTS deploy VARCHAR(20) DEFAULT 'local'
    CHECK (deploy IN ('local', 'docker', 'remote'));
ALTER TABLE agent_definitions ADD COLUMN IF NOT EXISTS mode VARCHAR(10) DEFAULT 'cli'
    CHECK (mode IN ('cli', 'acp'));

-- 约束：非 orchestrator 必须有 client
ALTER TABLE agent_definitions DROP CONSTRAINT IF EXISTS agent_exec_mode;
ALTER TABLE agent_definitions ADD CONSTRAINT agent_client_required
    CHECK (client IS NOT NULL OR type = 'orchestrator');
```

### 3.4 Seed 数据

**4 个 Client：**

| name   | command | acp_protocol  | 关键 CLI 配置                                                                     |
| ------ | ------- | ------------- | --------------------------------------------------------------------------------- |
| kimi   | kimi    | acp           | `--print --yolo`, sessionMode=none                                                |
| claude | claude  | claude-stream | `--print --output-format json --dangerously-skip-permissions`, sessionMode=always |
| gemini | gemini  | acp           | `-p`, sessionMode=none                                                            |
| codex  | codex   | acp           | `exec --json --full-auto`, sessionMode=existing                                   |

**6 个 Agent：**

| name     | type      | client | deploy | mode | prompt               |
| -------- | --------- | ------ | ------ | ---- | -------------------- |
| gateway  | gateway   | kimi   | local  | acp  | ./agents/gateway.md  |
| master   | master    | kimi   | local  | acp  | ./agents/master.md   |
| coder    | executor  | kimi   | local  | cli  | ./agents/coder.md    |
| verifier | validator | kimi   | local  | cli  | ./agents/verifier.md |
| writer   | executor  | kimi   | local  | cli  | ./agents/writer.md   |
| editor   | validator | kimi   | local  | cli  | ./agents/editor.md   |

> 用户想用 Claude？→ 改 coder 的 client 为 "claude"。想跑 Docker？→ 改 deploy 为 "docker"。不需要新建 Agent。

---

## 4. 代码改动清单

### Phase 1: DB Schema 演进

- [x] 重写 `db/schema-agents.sql` — DROP 旧表 + CREATE agent_clients + ALTER agent_definitions
- [x] 重写 `db/seed-agents.js` — 4 client + 9 agent

### Phase 2: 推断引擎

- [x] 新建 `server/src/core/runtime-resolver.js`
  - `resolve(agent, client)` → `{ protocol, transport, launcherType, command, args }`
  - 纯函数，无状态，无 DB 依赖

### Phase 3: 数据层重写

- [x] `services/agent-queries.js`
  - 删除全部 Launcher CRUD（6 个方法）
  - 删除全部 CliBackend CRUD（6 个方法）
  - 新增 Client CRUD（getClient / listClients / createClient / updateClient / deleteClient）
  - 修改 getAgent — 返回 `{ agent, client }`
  - 修改 getFullConfig — 输出 `{ agents, clients, agentGroups, settings }`
  - 删除 `_rowToLauncherConfig` / `_rowToCliBackendConfig`
  - 新增 `_rowToClientConfig`

### Phase 4: Registry 重写

- [x] `src/core/registry/index.js`
  - 删除 `listLaunchers()` / `listCliBackends()` / `listCli()`
  - 新增 `listClients()` / `getClient(name)`
  - `getAgent()` 返回 `{ agent, client }` 而非 `{ agent, launcher, cliBackend }`
  - `getFullConfig()` 输出新结构

### Phase 5: agent-manager.js 重构

- [x] `getAgentConfig()` — 返回 `{ agent, client }`
- [x] `callAgent()` — 使用 `runtime-resolver` 推断，2 分支替代 4 分支：
  ```
  if (mode === 'cli')  → _runViaCliBackend(agent, client, ..., resolved)
  if (mode === 'acp')  → runAcpAgent(agent, client, ..., resolved)
  ```
- [x] `_runOneshotWithGuard` 不再被主路径调用（保留但不引用）
- [x] `agent-config-builder.js` — applyAgentOverrides 改为切 client 而非 cliBackend

### Phase 6: API Routes

- [x] `routes/agents.js`
  - 删除 `/backends` 全部路由
  - 新增 `/clients` CRUD 路由
  - `/clients/health` — 对每个 client 检测 `which <command>`
  - Agent 创建/更新接口改为 `{ client, deploy, mode }` 字段

### Phase 7: 前端

- [x] `api/index.js`
  - 删除 Backend 相关函数
  - 新增 Client 相关函数
- [x] `AgentFormDrawer.vue` — 表单改为 Client 下拉 + Deploy 下拉 + Mode 选择
- [x] `BackendPanel.vue` → 新建 `ClientPanel.vue`，展示 4 个 client + 健康状态
- [x] `AgentRegistry.vue` — 统计数据更新、Tab 从 backends → clients

### Phase 8: 测试

- [x] 重写 `test/registry-db.test.js`
- [x] 重写 `test/api-agents-crud.test.js`
- [x] 重写 `test/registry-integration.test.js`
- [x] 重写 `test/e2e-registry-full.test.js`
- [x] 重写 `test/e2e-orchestrator-dynamic.test.js`
- [x] 前端 vite build 通过 ✅

### Phase 9: 文档更新

- [x] 更新 `docs/agent-network/04-四维正交架构.md` → 新四维配置架构（角色 × 能力 × 客户端 × 部署）
- [x] 更新迁移文档 `web/docs/agent-registry-db-migration.md` → 添加重构状态说明

---

## 5. 前端 UI 效果

### Agent 编辑表单（重构后）

```
┌─────────────────────────────────────┐
│  新建 Agent                         │
├─────────────────────────────────────┤
│  名称      [  coder            ]    │
│  类型      [  executor       ▼ ]    │
│  客户端    [  kimi           ▼ ]    │  ← 只有 4 个选项
│  部署方式  [  local          ▼ ]    │  ← 只有 3 个选项
│  模式      [  cli            ▼ ]    │  ← cli / acp
│  Prompt    [  ./agents/coder.md  ]  │
│  描述      [  程序员            ]    │
├─────────────────────────────────────┤
│              [取消]  [创建]          │
└─────────────────────────────────────┘
```

### 之前 vs 之后

| 指标             | 之前                                          | 之后                       |
| ---------------- | --------------------------------------------- | -------------------------- |
| Launcher 数量    | 10                                            | 0（概念删除）              |
| CLI Backend 数量 | 4                                             | 0（概念删除）              |
| Client 数量      | —                                             | **4**                      |
| Agent 数量       | 20                                            | **6**                      |
| 用户需要配的字段 | protocol + transport + launcher 或 cliBackend | **client + deploy + mode** |
| 换一个 AI 的操作 | 新建一个 Agent                                | **改一个字段**             |