three-dim-refactor.md 11.9 KB

Edit Raw Blame History


四维配置重构方案
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 定义
// 之前 — 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 删除旧表（破坏性）
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）的全部运行配置。
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
-- 删除旧列
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
改一个字段