@agentdock/wire

协议定义层 — 系统的「宪法」。所有组件通过这里定义的格式通信。

概述

wire 是 AgentDock monorepo 的最底层包，零运行时依赖（仅 Zod + cuid2）。它定义了：

• 会话事件（agent 产生的文本、工具调用、文件变更等）
• 信封（给事件加上 id/时间戳/角色/turn 等元数据）
• 消息格式（加密后的消息结构）
• RPC 方法（客户端与服务端的远程调用协议）
• 同步协议（增量更新、版本控制、冲突解决）
• 元数据（权限模式、CLI 类型、控制深度等级）

所有 schema 使用 Zod 定义，提供编译时类型推断 + 运行时验证双重保障。

在架构中的位置

wire ← crypto ← sdk ← web
wire ← server
wire ← crypto ← daemon

wire 被所有其他包依赖，是唯一的零依赖底层包。

模块结构

src/
├── events.ts          # 12 种会话事件 schema（text/service/tool-call/file/turn/start/stop/question/permission/answer）
├── interactionEvents.ts # 交互事件（question/permission-request/answer）
├── envelope.ts        # SessionEnvelope — 事件 + 元数据封装（superRefine 交叉约束）
├── messages.ts        # SessionMessage — 加密消息格式 + SessionProtocolMessage
├── messageMeta.ts     # MessageMeta — 权限模式、CLI 类型、代价等元数据
├── rpc.ts             # RPC 方法/参数/返回值 schema（daemon ↔ server ↔ client）
├── sync.ts            # CoreUpdate — 增量同步协议 + VersionedEncryptedValue
├── legacyProtocol.ts  # 旧版协议兼容（SessionProtocolMessage 转换）
├── controlLevel.ts    # ControlLevel 枚举（L0-L3 控制深度）+ CLI 类型定义
├── pairing.ts         # 设备配对协议 schema（PairingRequest/Response/Status）
├── utils.ts           # createId (cuid2)、Unix 时间戳工具
└── index.ts           # Barrel exports

API 参考

会话事件 (events.ts)

12 种事件类型，通过 t 字段的 discriminated union 区分：

| 事件 | t 值 | 关键字段 | 说明 | | ------------- | -------------------- | ------------------------------------------------ | --------------------------------- | | Text | text | text, thinking? | AI 输出文本（含思考模式标记） | | Service | service | text | 系统服务消息 | | ToolCallStart | tool-call-start | call, name, title, description, args | 工具调用开始 | | ToolCallEnd | tool-call-end | call | 工具调用结束 | | File | file | ref, name, size, image? | 文件变更 | | TurnStart | turn-start | — | 对话轮次开始 | | TurnEnd | turn-end | status: completed\|failed\|cancelled, usage? | 对话轮次结束（含可选 token 用量） | | Start | start | title? | 会话开始 | | Stop | stop | — | 会话结束 | | Question | question | requestId, text, questionType? | Agent 向用户提问 | | PermRequest | permission-request | requestId, toolName, toolCallId, args | 工具权限请求 | | Answer | answer | requestId, text | 用户回答 |

import { SessionEventSchema } from '@agentdock/wire';

const result = SessionEventSchema.safeParse({
  t: 'text',
  text: 'Hello world',
  thinking: false,
});
// result.success === true

信封 (envelope.ts)

SessionEnvelope 将事件包装为可传输的完整消息单元：

import { createEnvelope } from '@agentdock/wire';

const envelope = createEnvelope(
  'agent',
  { t: 'text', text: 'Hello' },
  {
    turn: 'turn-001',
    // id 和 time 自动生成
  },
);
// { id: 'cuid2...', time: 1709..., role: 'agent', turn: 'turn-001', ev: { t: 'text', text: 'Hello' } }

superRefine 约束：service/start/stop 事件的 role 必须为 'agent'。

消息 (messages.ts)

import type { SessionMessage } from '@agentdock/wire';

// SessionMessage = 加密后的消息格式
// content: { c: string (密文), n: string (nonce) }
// createdAt / updatedAt: Unix timestamp (number)

RPC (rpc.ts)

定义 daemon ↔ server ↔ client 之间的远程调用方法：

import { RpcMethodSchema } from '@agentdock/wire';
// 包含方法名、参数 schema、返回值 schema

同步协议 (sync.ts)

import type { CoreUpdate } from '@agentdock/wire';
// CoreUpdate: 增量更新载体
// VersionedEncryptedValue: 带版本号的加密值（乐观锁）

控制深度 (controlLevel.ts)

import { ControlLevelSchema, CliTypeSchema } from '@agentdock/wire';

// ControlLevel: 0(最低) | 1(仅监控) | 2(高控制) | 3(完全控制)
// CliType: 'claude' | 'copilot' | 'opencode' | 'codex' | 'gemini' | 'qwen'

开发

# 运行测试（300 tests）
pnpm --filter @agentdock/wire test

# 覆盖率（目标 95%+）
pnpm --filter @agentdock/wire test:coverage

# 类型检查
pnpm --filter @agentdock/wire typecheck

设计决策

• 字段名对齐 Happy：call/name/args（非 toolId/toolName/params），确保协议兼容
• cuid2 作为 ID：subagent 字段用 cuid2 验证，id 用 createId() 生成
• Unix number 时间戳：time/createdAt/updatedAt 都是 Unix 毫秒数，非 ISO string
• discriminated union：SessionEventSchema 用 t 字段做类型判别，而非 type