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 暴露多余工具。

执行链路：

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、过程事件和前端时间线展示的完整闭环。

4.4 KiB Raw Permalink Blame History Unescape Escape