96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
---
|
||
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]]
|