---
title: Skill Runtime 执行体系
created: 2026-05-02
updated: 2026-05-07
type: concept
tags: [skill, runtime, agent, backend, config]
sources: [docs/superpowers/specs/2026-04-27-skill-system-evolution-design.md, packages/backend/src/modules/netaclaw/service/skill_config.ts, packages/backend/src/modules/netaclaw/service/skill_executor.ts, packages/backend/src/modules/netaclaw/service/skill_secret.ts, packages/backend/src/modules/netaclaw/tools/builtin/execute_skill.ts, packages/shared/types/skill.types.ts]
---

# Skill Runtime 执行体系

Skill Runtime 是 2026-04-27 后对 [[skill-system]] 的一次架构升级：Skill 不再只是 `SKILL.md` prompt 指令，还可以声明运行时、入口脚本、依赖、环境变量和必读 references。它把 prompt skill、compute-entry skill、compute-toolkit skill 区分开，并由 [[tool-system]] 注入不同工具执行。

## 三种分类

分类由 `service/skill_config.ts` 根据 `skill.config.yaml` 推导：

| 分类 | 判定 | Agent 使用方式 | 例子 |
| --- | --- | --- | --- |
| `prompt` | 无 `skill.config.yaml`，或 config 无 runtime/entrypoint | `read_skill` 读取完整指令 | `llm-wiki` |
| `compute-entry` | config 有 `entrypoint` | `execute_skill` 直接执行 stdin/stdout JSON 协议 | OCR/API 封装类 skill |
| `compute-toolkit` | config 有 `runtime` 但无 `entrypoint` | `read_skill` 后按指令用 `bash` 执行脚本 | `minimax-pdf`、`minimax-xlsx`、`minimax-docx` |

`buildSkillsPrompt()` 会在 `<available_skills>` 中输出 `type`，compute-entry 还会摘要 `interface.input`，让模型知道何时可以直接调用 `execute_skill`。

## skill.config.yaml

`skill.config.yaml` 当前支持：

- `runtime`: `python`、`node`、`bash`、`dotnet`
- `entrypoint`: compute-entry 的执行入口
- `timeout`: 子进程超时
- `env`: skill scoped 环境变量 schema
- `dependencies`: system/python/node/dotnet 依赖声明
- `setup`: posix/win32 安装脚本
- `interface`: 输入输出字段说明
- `references`: required / optional / routes

这些字段同步到 `packages/shared/types/skill.types.ts`，供前后端共享。

## execute_skill

`tools/builtin/execute_skill.ts` 注册 `execute_skill` 工具。`tool_resolver.ts` 只在 Agent 有 skills 且包含 compute-entry skill 时注入它，避免没有执行型 skill 的 Agent 暴露多余工具。

执行链路：

```text
LLM -> execute_skill({ name, input })
  -> SkillExecutorService.execute()
  -> SkillConfigService 读取 runtime/entrypoint/interface
  -> SkillSecretService.resolveEnv() 注入 skill scoped env
  -> spawn skill 子进程，stdin 写 JSON
  -> stdout 解析 JSON，返回工具结果
```

Python skill 需要先有 `.venv`；执行器会检查 venv 目录，缺失时返回诊断性错误。

2026-05-07 后，`execute_skill` 还支持桥接 compute-entry 子进程发出的 [[runtime-process-events]]。长耗时 Skill 可以在最终 JSON 之前持续输出阶段进度；运行时会做 payload 脱敏、采样和 JSONL 落盘。

## 密钥与环境变量

`service/skill_secret.ts` 负责 skill scoped secrets：

- `netaclaw_skill.secrets` 存 AES-256-GCM 加密后的 JSON。
- `netaclaw_skill.envSchema` 存环境变量声明。
- `resolveEnv(skillName)` 合并 env 默认值和已配置 secrets。
- `saveSecrets()` 只保存加密结果，前端不回显明文。

bash 工具还支持 `createSkillBashEnvProvider()`：当 cwd 落在某个 skill 目录内时，自动把该 skill 的 env 注入命令环境。这样 compute-toolkit 不需要把 API key 写入 prompt 或脚本参数。

## 诊断与兼容

`SkillLoaderService` 现在会收集诊断：

- `NAME_INVALID`、`NAME_MISMATCH`、`NAME_COLLISION`
- `DESC_MISSING`、`DESC_TOO_LONG`
- `CONFIG_PARSE_ERROR`
- `VENV_MISSING`
- `ENV_NOT_CONFIGURED`

`/admin/netaclaw/skill/diagnostics` 给前端技能页展示。旧的纯 prompt skill 不需要迁移；没有 config 的 skill 仍按原逻辑加载。

## 新增 compute-entry 示例

[[vehicle-damage-skill]] 是当前最典型的 compute-entry 示例：它通过 Node 脚本抽取汽车环车视频帧、调用视觉模型检测旧伤候选、定位标注、复核放大图并输出最终证据。该 Skill 同时验证了 `skill.config.yaml`、scoped env、过程事件和前端时间线展示的完整闭环。

## 相关页面

- [[skill-system]]
- [[document-skills]]
- [[vehicle-damage-skill]]
- [[runtime-process-events]]
- [[tool-system]]
- [[tool-governance]]
- [[frontend-architecture]]