01 - QwenPaw 底座：实例运行时解析

一句话：实例是一个自带 Runtime Token 校验中间件的单进程 FastAPI，Agent 记忆、Skill 池、MCP 客户端、ACP 执行体全落在本地目录与 SQLite 里；控制面对它的唯一杠杆是原生 API 面，因此企业化只能靠外部编排与拉起预置来维持权威配置，代价是通道被收敛成 console 单入站，平台能从外部覆盖写回配置，却改不动实例把一切状态落在本地文件的存储形态。

本章回答：一个 QwenPaw 实例内部长什么样？Agent、Skill、MCP、ACP 如何工作？控制面需要管理哪些内部状态？

一、实例进程架构

每个员工实例是一个独立的 QwenPaw 进程，运行在 K8s Pod 中。下图展示实例内部的模块组成：

二、工作区目录结构

实例的 data 卷（挂载到 /app/working）内部布局如下：

/app/working/
├── config.json                  # 实例配置（channels/mcp/tools/agents/security/acp）
├── settings.json                # UI 偏好（语言/主题，员工可改）
├── qwenpaw.log                  # 运行日志
├── skill_pool/                  # 已安装 Skill 池
│   ├── tavily/
│   │   └── SKILL.md
│   └── ...
├── workspaces/                  # Agent 工作区
│   ├── default/                 # 默认 Agent
│   │   ├── chats/               # 会话历史
│   │   ├── memory/              # 记忆（embedding）
│   │   └── projects/            # 执行产物
│   │       └── {task_id}/       # 按任务隔离
│   └── {agent_id}/              # 其他 Agent
│       ├── chats/
│       ├── memory/
│       └── projects/
└── governance/                  # 治理配置

三、Agent 与多 Agent 架构

QwenPaw 实例支持运行多个 Agent，每个 Agent 拥有独立的运行时上下文：

属性	说明
`agent_id`	唯一标识（如 `default`、`qa_assistant`）
系统提示词	Agent 角色定义（编码助手、QA 助手等）
会话列表	独立的多轮对话历史
记忆	独立的知识记忆（embedding 向量）
技能绑定	该 Agent 启用的 Skill 子集
工作区	`workspaces/{agent_id}/` 下的产物和配置

企业场景默认配置：平台预置一个 default Agent（通用助手），员工可通过 Skill 扩展能力。多 Agent 场景（如专门的编码 Agent、文档 Agent）由管理员按角色模板预置。

四、Skill 体系

Skill 是 Agent 的能力扩展包，每个 Skill 包含一个 SKILL.md 文件描述其能力和使用方式。

Skill 生命周期：市场搜索 → 安装到 skill_pool → 启用/禁用 → Agent 会话中生效

安装方式：

方式	端点	说明
市场安装	`POST /api/skills/hub/install/start`	从市场异步安装，任务化/可取消
同步导入	`POST /api/skills/pool/import`	从 URL 同步导入 bundle 包
本地上传	`POST /api/skills/pool/upload-zip`	上传 zip 包直接安装

启用控制：安装后 Skill 进入 skill_pool，需要显式启用才在 Agent 会话中生效。启用粒度为 Agent 级别——同一个 Skill 可以在不同 Agent 中有不同的启用状态。

五、MCP 客户端

MCP（Model Context Protocol）是连接外部工具的标准协议。实例作为 MCP Client，连接外部 MCP Server 获取工具能力。

传输协议	场景	配置要素
`stdio`	本地命令行工具	`command` 字段指定启动命令
`streamable_http`	远程 HTTP 服务	`url` + `headers`（含认证信息）
`sse`	远程 SSE 服务	`url` + `headers`

工具白名单：创建 MCP Client 后，通过 PUT /api/mcp/tools/{client} 设置该 Client 可用的工具子集。未列入白名单的工具即使 Server 端存在也不可调用的。白名单按 Agent 粒度控制。

六、ACP 协议（Agent Communication Protocol）

ACP 是 QwenPaw 的 Agent 间通信协议。主 Agent 可以将任务委托给专门的执行体（如 opencode、claude_code），执行体通过 stdio 返回结果。

默认执行体配置：

执行体	命令	工具解析模式	说明
`opencode`	`opencode acp`	`update_detail`	编码任务执行
`qwen_code`	`qwen --acp`	`call_detail`	通义编码执行
`claude_code`	`npx -y @zed-industries/claude-agent-acp`	`update_detail`	Claude 编码执行
`codex`	`npx -y @zed-industries/codex-acp`	`call_detail`	Codex 编码执行

激活条件：执行体必须在实例镜像中预装（二进制存在），且 config 中 enabled=True。平台在 post-init 阶段校验执行体可用性。

七、通道配置

实例支持多种消息通道（channel），每个通道是一个消息入站方式。企业场景下，实例仅启用 console 通道：

QWENPAW_ENABLED_CHANNELS=console

所有外部消息（IM、Web、定时任务）统一通过 POST /api/console/chat 入站。飞书/企微/钉钉等 IM 通道由平台级渠道聚合器处理，实例不直接对接 IM。

这样做的原因：

原因	说明
凭证集中	IM 应用凭证只在聚合器持有，不分散到每个实例
消息聚合	一个聚合器服务全企业员工，而非每实例一个 IM 机器人
统一管控	消息归一化、会话映射、审计都在聚合器层完成

八、配置结构

实例核心配置 config.json 的顶层结构：

json

{
  "channels": {
    "console": {"enabled": true}
  },
  "agents": {
    "default": {
      "system_prompt": "你是一个专业的企业助手...",
      "skills": ["tavily-search", "code-review"]
    }
  },
  "mcp": {
    "clients": {
      "enterprise_kb": {
        "transport": "streamable_http",
        "url": "https://mcp.internal/search"
      }
    }
  },
  "security": {
    "sandbox": true,
    "deny_paths": ["/etc", "/root", "/var"]
  },
  "acp": {
    "agents": {
      "opencode": {"enabled": true, "command": "opencode", "args": ["acp"]},
      "qwen_code": {"enabled": true, "command": "qwen", "args": ["--acp"]}
    }
  },
  "skill_paths": ["skill_pool/"],
  "plugins": {}
}

控制面管理范围：

配置段	管理方	员工可改
`channels`	平台预置（权威）	否
`security`	平台预置（权威）	否
`acp`	平台预置（权威）	否
`agents`	平台预置 + 员工可调	部分（偏好设置）
`mcp`	平台预置 + 员工可启用	部分（订阅范围内）
`skill_paths`	平台分发 + 员工可启用	部分（订阅范围内）

九、关键 API 端点一览

端点	方法	用途	控制面是否调用
`/api/healthz`	GET	健康探针	是（探活 + 就绪判定）
`/api/console/chat`	POST	对话入站（SSE）	是（任务下发）
`/api/backups`	POST	创建备份	是（暂存前备份）
`/api/backups/{id}/restore`	POST	恢复备份	是（恢复时调用）
`/api/skills/hub/search`	GET	搜索市场 Skill	是（分发时查询）
`/api/skills/hub/install/start`	POST	安装市场 Skill	是（分发时安装）
`/api/skills/pool/import`	POST	导入 Skill 包	是（分发时导入）
`/api/skills/{id}/enable`	POST	启用 Skill	是（预置时启用）
`/api/mcp`	POST	创建 MCP Client	是（分发时创建）
`/api/mcp/tools/{client}`	PUT	设置工具白名单	是（分发时配置）
`/api/providers`	GET/PUT	模型 Provider 管理	是（预置时写入）
`/api/agents/{id}/memory/runtime_status`	GET	记忆状态	是（监控采集）
`/api/revoke-all-tokens`	POST	吊销所有 Token	是（回收时调用）

01 - QwenPaw 底座：实例运行时解析 ​

一、实例进程架构 ​

二、工作区目录结构 ​

三、Agent 与多 Agent 架构 ​

四、Skill 体系 ​

五、MCP 客户端 ​

六、ACP 协议（Agent Communication Protocol） ​

七、通道配置 ​

八、配置结构 ​

九、关键 API 端点一览 ​