AgentSpace 源码深度解析 · Agent Infrastructure Teardown

01问题域：为什么需要 Agent 工作空间

大多数 Agent 框架面向单人 terminal，AgentSpace 要解决的是团队级协作与治理问题。

现有框架的三大断层

① Agent 能力私有化——Agent 藏在个人 terminal 里，团队不可见；② 上下文分散——消息、文档、审批、截图、runtime 文件散落在各处，没有共同 home；③ 治理缺失——凭证、文档权限、工具调用、对外操作几乎无法集中审计。

团队级缺失

AgentSpace 的回答

把 Agent 从个人工具升格为数字员工（Digital Employee）：有角色定义、有 owner、有权限边界、可被借用/转让/审计。人类负责方向与授权，Agent 负责执行与协调——在同一套工作空间里。

组织级抽象

四大核心能力

🗓 调度（Scheduling）——AgentRouter 统一路由；🧑‍💼 能力（Capability）——数字员工看板；🤝 协作（Collaboration）——多 Agent 协调 + 人工审批门；🔐 安全（Security）——完整治理控制面。

四层能力矩阵

技术选型

Next.js 14 App Router（apps/web）+ Node.js CLI（apps/cli）+ TypeScript monorepo（npm workspaces）+ PostgreSQL + Docker Compose。远程 Daemon 独立部署，通过 HTTPS + token 与 Web 实例通信。

Next.js + PostgreSQL

02全局架构

AgentSpace 由 5 个 npm workspace 包组成，Web/CLI 共用同一服务层和数据层。

┌─────────────────────────────────────────────────────────────────┐
│                        AgentSpace 架构                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────┐        ┌──────────────────────────────────┐  │
│   │  Human User  │◄──────►│     Next.js Web App (apps/web)    │  │
│   └──────────────┘        │  React 18 + App Router            │  │
│        │                  │  Channel docs / Knowledge base      │  │
│        │                  │  Permission center / Audit logs     │  │
│        │                  └──────────────┬─────────────────────┘  │
│        │                                 │                        │
│   ┌────┴────────────┐                    │                        │
│   │  agent-space   │                    │                        │
│   │  CLI (apps/cli) │◄───────────────────┤                        │
│   │  Node.js TS CLI │                   │                        │
│   └────┬───────────┘                   │                        │
│        │                               │                        │
│        └───────────┬───────────────────┤                        │
│                    │                   │                        │
│         ┌──────────┴───────────────────┴──────┐                  │
│         │    @agent-space/services (101 files) │                  │
│         │    Workspace / Agent / Channel /      │                  │
│         │    Knowledge / Document / Cost /     │                  │
│         │    Notification services             │                  │
│         └──────────┬───────────────────┬───────┘                  │
│                    │                   │                         │
│         ┌──────────┴───────┐ ┌────────┴────────┐                │
│         │ @agent-space/db   │ │ @agent-space/   │                │
│         │ PostgreSQL 16+     │ │ domain (types)  │                │
│         │ Schema: workspace,  │ │ Types: Agent,   │                │
│         │ employee, channel,  │ │ Channel,        │                │
│         │ document, knowledge │ │ Workspace,      │                │
│         │                     │ │ DaemonProvider  │                │
│         └─────────────────────┘ └────────────────┘                │
│                                                                  │
│   ┌───────────────────────────────────────────────────────────┐  │
│   │           @agent-space/daemon (remote daemon)             │  │
│   │  Stateful long-running process on remote host               │  │
│   │  Heartbeat polling → Web server                            │  │
│   │  ProviderRuntime: Claude Code / Codex / OpenCode /        │  │
│   │                    OpenClaw / Hermes                       │  │
│   └────────────────────────┬──────────────────────────────────┘  │
│                            │                                     │
│         ┌──────────────────┼──────────────────┐                 │
│         │                  │                  │                 │
│   ┌─────┴─────┐     ┌──────┴──────┐  ┌──────┴──────┐           │
│   │AgentRouter │     │ Legacy      │  │ @agent-space│           │
│   │(normalize  │     │ ProviderRT  │  │ /sandbox    │           │
│   │ 5 runtimes)│     │(Gemini/Nano)│  │ (Cube/Local)│           │
│   └────────────┘     └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘

apps/web

Next.js 14 App Router workspace UI。认证（Google OAuth）、频道文档、知识库、权限中心、审批流、任务面板、成本仪表盘。端口 1455。

Next.js 14

apps/cli

Node.js CLI（node --experimental-strip-types），本地控制 AgentSpace 实例。doctor / workspace status / channel list / task list / daemon status 等命令。

Node.js TS CLI

packages/domain

11 个共享类型文件。核心类型：Workspace / Channel / Message / AgentTemplate / DaemonProvider / RuntimeOutput。纯类型定义，无运行时依赖。

11 TS files

packages/services

101 个 TypeScript 文件的业务服务层。AgentAccessRequests / Workspace / Knowledge / Documents / RuntimeAccess / Notifications / Costs / Audit。所有业务逻辑的核心。

101 TS files

packages/daemon

48 个 TypeScript 文件。RemoteDaemon 主循环、AgentRouter（多运行时统一抽象）、ProviderRuntime、TaskContext、RuntimeOutput、CLI 入口。核心创新所在。

48 TS files

packages/sandbox

12 个 TypeScript 文件。沙箱抽象层：LocalSandbox（本地）和 CubeSandbox（远程）两种 adapter。Factory 模式创建沙箱实例。

12 TS files

03核心创新：AgentRouter

AgentRouter 是 AgentSpace 最关键的技术设计——一条统一执行管线，把 Claude Code / Codex / OpenCode / OpenClaw / Hermes 五种异构运行时压成统一接口。

设计动机：每种 Agent CLI 都有各自的 CLI 参数格式、会话模型、事件流结构和诊断输出。换 runtime 必须重建完整上下文。AgentRouter 把这些差异封装在 harness 层之后，对上层暴露完全一致的 JSON 事件流、会话 ID 和诊断结构。

支持的运行时

Provider	Execution Path	Diagnostics	Session
`Claude Code`	AgentRouter	stream-json events, session fallback, tool approval bridge	✅
`Codex CLI`	AgentRouter	JSON events, session fallback, runtime tool capability diagnostics	✅
`OpenCode`	AgentRouter	JSON events, session propagation, timeout/nonzero/empty diagnostics	✅
`OpenClaw`	AgentRouter	health/preflight, auth/profile/model/tool/protocol diagnostics	⚠️ fallback
`Hermes Agent`	AgentRouter	text output, executable compatibility checks, timeout/empty diagnostics	✅
`Gemini CLI`	legacy provider-runtime	one-shot CLI	❌

核心类型定义

// packages/domain/src/daemon-api.ts
export type RuntimeOnlineStatus = "online" | "offline";
export type ProviderHealthStatus = "unknown" | "healthy" | "degraded" | "broken";
export type ProviderErrorCode =
  | "provider.cli_missing"
  | "provider.auth_invalid"
  | "provider.profile_missing"
  | "provider.rate_limited"
  | "provider.model_unavailable"
  | "provider.session_invalid"
  | "provider.tool_missing"
  | "provider.tool_unauthorized"
  | "provider.timeout"
  | "provider.runtime_generic_failure";

export interface ProviderStructuredError {
  code: ProviderErrorCode;
  category?: ProviderErrorCategory;
  provider?: DaemonProvider;
  message?: string;
  rawProviderMessage?: string;
}

export interface ProviderHealthSnapshot {
  status: ProviderHealthStatus;
  detected: DetectedProvider[];
  harnesses: HarnessRecord[];
}

Harness 检测与 Smoke Test

// packages/daemon/src/agent-router.test.ts
test("listAgentRouterHarnesses exposes the MVP native harnesses", () => {
  assert.deepEqual(listAgentRouterHarnesses(), [
    { id: "claude",   label: "Claude Code"    },
    { id: "codex",    label: "Codex CLI"     },
    { id: "opencode", label: "OpenCode"      },
    { id: "openclaw", label: "OpenClaw"      },
    { id: "hermes",   label: "Hermes Agent"  },
  ]);
});

test("detectAgentRouterHarnesses reports available and missing CLIs", async () => {
  const detected = await detectAgentRouterHarnesses();
  assert.deepEqual(
    detected.harnesses.map(h => ({ id: h.id, status: h.status })),
    [
      { id: "claude",   status: "available" },
      { id: "codex",    status: "available" },
      { id: "opencode", status: "available" },
      { id: "openclaw", status: "missing"   },
      { id: "hermes",   status: "available" },
    ]
  );
});

Smoke Test 命令：每种 harness 都可通过标准 CLI 直接测试：
agent-router run --harness claude --cwd /workspace/project "summarize this repo"
agent-router run --harness codex --cwd /workspace/project --model gpt-5.1 "fix tests"

04数字员工看板

数字员工看板（Digital Employee Board）是 AgentSpace 的资源管理层——把私有 Agent 变成全组织可见、可申请、可复用的共享资产。

👤

Agent 身份档案

每个 Agent 有 role / summary / owner / readiness / status / 绑定的 runtime 和 harness / 已分配的 skills 和 knowledge / 常用频道和可用性状态。

🔄

Agent Fork / Copy

通过 AgentAccessRequest 申请借用或复制一个 Agent。Owner 审批通过后，Agent 的完整上下文（skills、knowledge、instructions）被 fork 到目标 workspace。

👥

Channel 协作

Agent 参与飞书风格的频道协作：@agentMention 触发执行，运行时输出文件、执行事件和任务历史附着在频道上下文中，不丢失在 terminal 里。

📋

Agent 模板

三种开箱即用模板：finance-analyst（财务分析）、product-manager（产品经理）、product-designer（产品设计）。每个模板定义了 role、instructions、skill recommendations 和适用场景。

AgentTemplate 核心字段

// packages/domain/src/agent-templates.ts
export type AgentTemplateId = "finance-analyst" | "product-manager" | "product-designer";

export interface SystemAgentTemplatePreset {
  id: AgentTemplateId;
  version: number;
  category: "finance" | "product" | "design";
  displayName: string;
  shortDescription: string;
  defaultAgentName: string;
  traits: string[];
  instructions: string;
  skillRecommendations: AgentTemplateSkillRecommendation[];
}

export interface AgentTemplateSkillRecommendation {
  key: string;
  label: string;
  requirement: "required" | "recommended" | "optional";
  sourceType: "skills.sh" | "clawhub" | "github";
  sourceUrl: string;
  description: string;
}

AgentAccessRequest 流程：request_type 分为 fork_copy（复制完整上下文）和 channel_use（仅在频道中使用）。requester 发起请求 → Owner/Admin 审批 → 创建 AgentForkInvitation → 目标 workspace 获得 Agent 副本。

05Remote Daemon 架构

Remote Daemon 是 AgentSpace 的执行引擎，独立部署在远程机器上，通过 HTTPS 心跳轮询与 Web 实例通信。

┌─────────────────────────────────────────────────────────────────┐
│              RemoteDaemon 主循环 (packages/daemon)               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. registerDaemon() ──► POST /daemon/register ──► Web Server  │
│     获取 daemonToken（后续认证用）                              │
│                                                                  │
│  2. 主循环: while(true) {                                        │
│       heartbeat() ──► POST /daemon/heartbeat                    │
│       claimTask()  ──► GET  /daemon/tasks/claim                │
│                                                                  │
│       if (task) {                                                │
│         runProviderTask(task)  ──► AgentRouter / LegacyRT       │
│         uploadOutput()   ──► POST /daemon/output               │
│       }                                                          │
│                                                                  │
│       sleep(heartbeatIntervalMs)                                 │
│  }                                                               │
│                                                                  │
│  心跳间隔: DEFAULT_HEARTBEAT_INTERVAL_MS = 10s                   │
│  任务轮询: DEFAULT_TASK_POLL_INTERVAL_MS = 5s                    │
│  任务超时: configurable via --task-timeout (default: 43.2s)     │
└─────────────────────────────────────────────────────────────────┘

RemoteDaemonConfig 关键配置

// packages/daemon/src/remote-daemon.ts
export interface RemoteDaemonConfig {
  stateDir: string;           // ~/.agent-space-daemon 状态目录
  daemonKey: string;          // daemon 唯一标识
  deviceName: string;         // 机器名
  runtimeName: string;        // 显示名
  heartbeatIntervalMs: number;
  taskPollIntervalMs: number;
  taskTimeoutMs: number;      // 单任务超时
  serverUrl?: string;          // Web 实例地址
  daemonToken?: string;       // 注册时获取的认证 token
}

启动命令

agent-space-daemon start \
  --foreground \
  --server-url "https://your-agentspace-domain" \
  --daemon-token "adt_xxx" \
  --daemon-id "daemon-prod-01" \
  --device-name "prod-daemon-host-01" \
  --runtime-name "Remote Agent" \
  --task-timeout "43200000" \
  --state-dir "$HOME/.agent-space-daemon"

06治理控制面

AgentSpace 的权限模型围绕资源（Resource）× 参与者（Actor）× 能力（Capability）× 外部委托（Delegation）四个维度展开。

Workspace 成员

owner / admin / member 三级角色。邀请链接、加入码、邀请历史追踪。

owner / admin / member

Channel Access

加入权限、频道邀请、访问请求、读写断言。Agent 也需要 channel 成员资格才能参与协作。

channel ACL

Runtime Grants

用户级运行时授权、运行时共享、绑定/解绑、runtime provider 健康状态追踪。

runtime 授权

Document Permissions

owner / editor / viewer 三级角色。Agent 访问需要单独授权。文档版本回滚。

文档权限

Google Workspace

OAuth 凭证 owner、Agent 粒度的 Google Workspace 委托（Scoped Delegation）、外部文档请求。

Google OAuth 2.0

Daemon Security

API token 创建/撤销、远程 Daemon 注册、runtime 显示名管理。

daemon token

Provider 错误分类

// packages/domain/src/daemon-api.ts
export type ProviderErrorCategory =
  | "provider"      // Agent CLI 本身问题
  | "runtime"       // 执行环境问题
  | "configuration" // 配置缺失
  | "auth"          // 认证失败
  | "profile"       // Profile 不存在/无效
  | "model"         // 模型不可用
  | "tool"          // 工具缺失/无权限
  | "protocol";      // 协议解析失败

07代码规模速览

Package	TS Files	核心模块	职责
`packages/domain`	11	workspace.ts, agent-templates.ts, daemon-api.ts, channel-document-collab.ts	共享类型定义
`packages/services`	101	agent-access-requests, workspace, knowledge, documents, runtime-access, notifications	业务逻辑层
`packages/daemon`	48	agent-router, remote-daemon, provider-runtime, task-context, runtime-output	远程执行引擎
`packages/sandbox`	12	factory, local-sandbox, cube-sandbox	沙箱抽象
`apps/cli`	32	daemon-client, channel-documents, daemon-task-context, skill-imports	本地控制 CLI
`apps/web`	Next.js	App Router + React 18 + 26 feature 模块	Web UI

技术栈总结：TypeScript monorepo（npm workspaces）+ Next.js 14 + PostgreSQL 16 + Docker Compose + Node.js 24 + AgentRouter（多运行时统一抽象层）。

08快速启动

# 1. 克隆安装
git clone https://github.com/HKUDS/AgentSpace.git
cd AgentSpace

# 2. 安装依赖（Web + CLI + DB + Services + Daemon）
npm run setup

# 3. 配置环境变量
cp .env.example .env

# 4. 启动 PostgreSQL
docker compose -f deploy/postgres/docker-compose.yml up -d

# 5. 初始化数据库
npm run db:pg:init

# 6. 启动 Web
npm run dev:web
# → http://127.0.0.1:1455

# CLI 用法
npm run cli -- doctor --json
npm run cli -- workspace status --json
npm run cli -- daemon status --json

AgentSpace · Human + Agents.One Team. One Workspace.

01问题域：为什么需要 Agent 工作空间

现有框架的三大断层

AgentSpace 的回答

四大核心能力

技术选型

02全局架构

apps/web

apps/cli

packages/domain

packages/services

packages/daemon

packages/sandbox

03核心创新：AgentRouter

支持的运行时

核心类型定义

Harness 检测与 Smoke Test

04数字员工看板

Agent 身份档案

Agent Fork / Copy

Channel 协作

Agent 模板

AgentTemplate 核心字段

05Remote Daemon 架构

RemoteDaemonConfig 关键配置

启动命令

06治理控制面

Workspace 成员

Channel Access

Runtime Grants

Document Permissions

Google Workspace

Daemon Security

Provider 错误分类

07代码规模速览

08快速启动

AgentSpace · Human + Agents.
One Team. One Workspace.