Skill Runtime v1 设计草案

本文档定义 Skill 在 Chameleon 中的统一能力模型，用于把当前分散的工具能力、策略能力与可复用执行逻辑，以可管理、可审计、可版本化的方式挂载到 Agent。

文档状态：Implemented (v1)
更新时间：2026-03-04

0. 实现状态（v1）

当前版本已完成以下后端能力：

Skill 资产模型：skills
Skill 版本模型：skill_versions（发布后不可原地修改）
Agent Skill 挂载：agent_skill_links
Skill 审计：skill_execution_audits
API：/skills、/skills/{skill_id}/versions、/agents/{agent_id}/skill-mounts、/sessions/{session_id}/skill-calls
编排器：Skill 链路优先执行，MCP 链路作为补充，双链路失败互不阻断主回复

1. 设计目标

1.1 业务目标

明确 Skill 与 MCP 是两个独立能力层。
同一个 Agent 可同时使用 Skill 和 MCP，按策略并行生效。
Skill 负责能力资产化与治理，MCP 负责外部工具协议连接。
给管理员提供统一的启停、授权、审计和评测入口。

1.2 工程目标

兼容现有 MCP 运行链路，避免一次性重构风险。
Skill 执行必须具备超时、预算、权限与审计闭环。
Skill 的发布与回滚必须可追踪到 agent_id、skill_id、skill_version、trace_id。

1.3 非目标

v1 不做可视化编排器。
v1 不做跨租户 Skill Marketplace。
v1 不支持用户在线编写任意代码型 Skill。

2. 核心概念

概念	定义	说明
`Skill`	能力资产主对象	例如 `shipment_tracking`、`rate_quote`
`SkillVersion`	Skill 的不可变版本	配置、策略、执行后端快照
`SkillBinding`	Agent 与 SkillVersion 的挂载关系	含优先级、开关、调用策略
`SkillExecution`	单次执行记录	输入、输出、状态、耗时、错误
`SkillBackend`	Skill 执行后端类型	`mcp`、`builtin`、`workflow`

3. 功能设计

3.1 Skill 资产管理

创建 Skill：定义能力名称、用途、责任边界。
发布版本：每次变更形成新 SkillVersion，旧版本可回滚。
生命周期：draft、active、deprecated、disabled。
元数据：owner、标签、风险等级、依赖项。

3.2 Agent 挂载与策略控制

Agent 挂载目标为 SkillVersion，不直接挂执行细节。
每条挂载支持：is_active、priority、timeout_ms、max_calls_per_turn、tool_allowlist、input_schema_guard。

3.3 运行时执行链路

编排器按 agent_id 解析有效 Skill 挂载，按优先级排序。
每个 Skill 执行前执行策略校验：预算、白名单、输入校验。
执行成功后将结果注入上下文，失败则写审计并继续后续策略。
回答阶段只消费“通过策略校验的 Skill 输出”。

3.4 审计与可观测

每次执行落 skill_execution_audits。
审计维度：session_id、agent_id、skill_id、skill_version、status、latency_ms。
对敏感字段统一脱敏，禁止明文 secret 回传。

4. Skill 与 MCP 的独立并行模型

4.1 关系定义

Skill 是能力与治理层：负责版本、发布、策略、评测、审计聚合。
MCP 是协议与连接层：负责发现工具、调用工具、处理凭据和传输。
两者独立建模、独立 API、独立生命周期。

4.2 Agent 使用方式

同一个 Agent 可以同时挂载 Skill 与 MCP。
典型模式：
通过 Skill 调用标准化业务能力。
通过 MCP 直接调用临时或底层工具能力。

4.3 兼容性策略

保留现有 mcp-servers、mcp-credentials、agent_mcp_links。
新增 skills、skill_versions、agent_skill_links，不替换现有 MCP 资源。
迁移期允许两条链路长期共存。

4.4 执行优先级与冲突规则

默认优先级：Skill 路径优先，MCP 直连路径作为补充。
若同名工具同时出现在 Skill 和 MCP 直连中：
通过 Skill 触发时，使用 Skill 侧策略。
通过 MCP 直连触发时，使用 MCP 挂载策略。
两条链路都必须落审计，且共享 trace_id 便于关联追踪。

5. 数据模型草案

erDiagram
  AGENT ||--o{ AGENT_SKILL_LINK : mounts_skill
  AGENT ||--o{ AGENT_MCP_LINK : mounts_mcp
  SKILL ||--o{ SKILL_VERSION : has
  SKILL_VERSION ||--o{ AGENT_SKILL_LINK : mounted_by
  AGENT_SKILL_LINK ||--o{ SKILL_EXECUTION_AUDIT : logs
  MCP_SERVER ||--o{ AGENT_MCP_LINK : bound_by
  MCP_SERVER ||--o{ SKILL_VERSION : backend_ref_optional

5.1 `skills`

id varchar(64) PK
name varchar(128) unique
display_name varchar(256)
description text
category varchar(64)
risk_level varchar(32) 例如 low medium high
owner varchar(128)
status varchar(32) 例如 draft active disabled
created_at timestamptz
updated_at timestamptz

5.2 `skill_versions`

id varchar(64) PK
skill_id FK -> skills.id
version varchar(32) 例如 v1.0.0
backend_type varchar(32) 例如 mcp builtin workflow
backend_ref_id varchar(64) 指向 MCP Server 或内置执行器标识
runtime_config_json text
policy_config_json text
input_schema_json text
output_schema_json text
is_released bool
created_at timestamptz

5.3 `agent_skill_links`

id varchar(64) PK
agent_id FK -> agents.id
skill_version_id FK -> skill_versions.id
is_active bool
priority int
timeout_ms int
max_calls_per_turn int
tool_allowlist_json text
created_at timestamptz
updated_at timestamptz
唯一索引：agent_id + skill_version_id

5.4 `skill_execution_audits`

id varchar(64) PK
session_id FK -> sessions.id
agent_id FK -> agents.id
skill_id FK -> skills.id
skill_version varchar(32)
request_payload_json text
response_payload_json text
status varchar(32) 例如 success timeout error blocked
latency_ms int
error_message text
created_at timestamptz

6. API 草案

6.1 Skill 资产

POST /skills
GET /skills
GET /skills/{skill_id}
PATCH /skills/{skill_id}

6.2 Skill 版本

POST /skills/{skill_id}/versions
GET /skills/{skill_id}/versions
POST /skills/{skill_id}/versions/{version_id}/release

6.3 Agent Skill 挂载

POST /agents/{agent_id}/skill-mounts
GET /agents/{agent_id}/skill-mounts
PATCH /agents/{agent_id}/skill-mounts/{mount_id}
DELETE /agents/{agent_id}/skill-mounts/{mount_id}

6.4 Skill 审计

GET /sessions/{session_id}/skill-calls
GET /agents/{agent_id}/skill-calls

6.5 挂载请求示例

{
  "skill_version_id": "sv_001",
  "is_active": true,
  "priority": 80,
  "timeout_ms": 8000,
  "max_calls_per_turn": 2,
  "tool_allowlist": ["query_tracking", "get_eta"]
}

7. 编排器集成草案

flowchart LR
  UserReq[User Request]
  ResolveSkill[Resolve Agent Skills]
  ResolveMcp[Resolve Agent MCP Mounts]
  SkillPolicy[Skill Policy Guard]
  McpPolicy[MCP Policy Guard]
  SkillExec[Execute Skill Backend]
  McpExec[Execute MCP Tools]
  SkillAudit[Write Skill Audit]
  McpAudit[Write MCP Audit]
  Merge[Merge Context]
  LLM[Generate Final Answer]

  UserReq --> ResolveSkill
  UserReq --> ResolveMcp
  ResolveSkill --> SkillPolicy
  ResolveMcp --> McpPolicy
  SkillPolicy --> SkillExec
  McpPolicy --> McpExec
  SkillExec --> SkillAudit
  McpExec --> McpAudit
  SkillAudit --> Merge
  McpAudit --> Merge
  Merge --> LLM

运行约束：

Skill 链路只返回 is_active=true 且版本已发布的挂载。
MCP 链路只返回 is_active=true 且 server 状态可用的挂载。
两条链路都必须先做策略校验再执行。
任意失败都要产出对应审计记录，不得静默吞错。

8. 安全与治理

Secret 仍由凭据系统管理，不进入 Skill 明文字段。
高风险 Skill 必须要求显式 allowlist 和更低调用预算。
提供 kill switch，可按 skill_id 全局禁用。
支持按团队或租户隔离 Skill 可见性。

9. 迭代计划

P0 - 抽象层落地

新增 Skill 与 SkillVersion 数据模型。
新增 Agent Skill 挂载 API。
编排器支持 mcp 后端 Skill 解析与执行。
审计链路打通。

P1 - 治理增强

发布流 draft -> release -> rollback。
Skill 级评测与门禁。
前端管理页增加 Skill 资产视图。

P2 - 生态扩展

内置 builtin 后端执行器。
组合 Skill 和跨 Skill 依赖。
租户级 Skill 模板市场。

10. 验收标准

可以创建 Skill 并发布至少一个版本。
可以将 SkillVersion 挂载到 Agent 并在对话中被执行。
每次执行都有可查询审计记录。
故障时不影响主会话回复链路。
旧 MCP 挂载仍可工作。

11. 风险与待决策项

版本粒度：是否允许热更新已发布版本配置。
计费口径：按 Skill 调用还是按后端工具调用。
策略归属：策略配置应在 SkillVersion 还是 Agent 绑定侧优先。
迁移策略：agent_mcp_links 是否提供自动迁移脚本。

Skill Runtime v1 设计草案

0. 实现状态（v1）

1. 设计目标

1.1 业务目标

1.2 工程目标

1.3 非目标

2. 核心概念

3. 功能设计

3.1 Skill 资产管理

3.2 Agent 挂载与策略控制

3.3 运行时执行链路

3.4 审计与可观测

4. Skill 与 MCP 的独立并行模型

4.1 关系定义

4.2 Agent 使用方式

4.3 兼容性策略

4.4 执行优先级与冲突规则

5. 数据模型草案

5.1 skills

5.2 skill_versions

5.3 agent_skill_links

5.4 skill_execution_audits

6. API 草案

6.1 Skill 资产

6.2 Skill 版本

6.3 Agent Skill 挂载

6.4 Skill 审计

6.5 挂载请求示例

7. 编排器集成草案

8. 安全与治理

9. 迭代计划

P0 - 抽象层落地

P1 - 治理增强

P2 - 生态扩展

10. 验收标准

11. 风险与待决策项

5.1 `skills`

5.2 `skill_versions`

5.3 `agent_skill_links`

5.4 `skill_execution_audits`