# Skill 系统演进设计

> 日期：2026-04-27
> 状态：Draft
> 范围：P0 密钥管理 · P1 运行时执行器 · P2 标准兼容 · P3 碰撞检测与诊断

## 1. 背景与目标

当前 Neta 的 Skill 系统以 SKILL.md 为载体，支持 GitHub/ZIP/本地安装，具备条件激活和附属文件读取能力。但存在以下架构缺口：

- Skill 的 API Key / 密钥无归属，混在主系统环境变量或 prompt 硬编码中
- Skill 自有代码（Python/Node/.NET 脚本）的执行完全依赖 Agent 通过 bash 间接调用，无标准化执行器
- 与 Agent Skills 社区标准（agentskills.io）不完全兼容，社区 skill 安装后可能缺少字段映射
- 多来源安装缺少碰撞检测和诊断，同名冲突无预警
- Agent 读完 SKILL.md 后经常不读 references/ 子文档，导致执行质量下降

### 参考项目

- **pi-mono-main**：纯 prompt skill 系统，多层级发现、碰撞检测、诊断系统、名称规范验证
- **skills-main**（MiniMax Skills）：18 个生产级 skill，涵盖 PDF/DOCX/XLSX/PPTX 文档处理、多模态 API 调用，混合运行时（Python + Node + .NET + bash），系统级依赖（ffmpeg/LibreOffice）

## 2. Skill 分类体系

### 2.1 三种 Skill 类型

| 类型 | 判断条件 | Agent 交互方式 | 典型场景 |
|------|----------|---------------|---------|
| **prompt** | 只有 SKILL.md，无 skill.config.yaml | `read_skill` → 遵循指令 | llm-wiki、社区标准 skill |
| **compute-entry** | config 有 `entrypoint` | `execute_skill` 工具 | OCR 接口封装、单一 API 调用 |
| **compute-toolkit** | config 有 `runtime` 但无 `entrypoint` | `read_skill` → bash 执行脚本 | minimax-pdf、minimax-xlsx |

### 2.2 目录结构

**prompt skill（标准兼容）：**

```
skills/llm-wiki/
├── SKILL.md
└── references/
```

**compute-entry skill：**

```
skills/ocr-reader/
├── SKILL.md
├── skill.config.yaml
├── src/ocr.py
├── requirements.txt
└── .venv/                  ← 安装时自动创建
```

**compute-toolkit skill：**

```
skills/minimax-pdf/
├── SKILL.md
├── skill.config.yaml
├── scripts/
│   ├── palette.py
│   ├── render_cover.js
│   └── make.sh
├── design/
│   └── design.md
├── references/
│   └── *.md
├── requirements.txt
└── .venv/
```

### 2.3 skill.config.yaml 完整 Schema

```yaml
# --- 运行时声明 ---
runtime: python | node | bash | dotnet    # 主运行时
entrypoint: src/ocr.py                    # 可选，有则为 compute-entry，无则为 compute-toolkit
timeout: 30000                            # 执行超时 ms，默认 30s

# --- 环境变量声明 ---
env:
  - name: OCR_API_KEY
    required: true
    description: "OCR 服务 API Key"
  - name: OCR_ENDPOINT
    required: false
    default: "https://api.ocr.com/v1"

# --- 依赖声明 ---
dependencies:
  system:                                 # 系统级依赖
    - name: ffmpeg
      check: "ffmpeg -version"            # 检测命令
    - name: libreoffice
      check: "soffice --version"
  python:
    source: requirements.txt              # 或 inline: ["httpx>=0.27", "pillow"]
  node:
    packages: ["pptxgenjs"]               # npm install 到 skill 目录
  dotnet:
    project: scripts/dotnet/MyProject.Cli # dotnet restore 路径

# --- 安装钩子 ---
setup:
  posix: scripts/setup.sh                 # macOS/Linux
  win32: scripts/setup.ps1                # Windows

# --- compute-entry 专用：接口声明 ---
interface:
  input:
    image_path: { type: string, required: true, description: "图片路径" }
    language: { type: string, default: "auto" }
  output:
    text: { type: string }
    confidence: { type: number }

# --- references 加载策略 ---
references:
  required:                               # 执行前必须读取
    - references/create.md
    - references/format.md
  optional:                               # 按需读取
    - references/tracing.md
  routes:                                 # 任务路由 → 文档映射
    - match: ["create", "generate", "new"]
      required_refs: ["references/create.md", "references/format.md"]
    - match: ["edit", "modify", "fill"]
      required_refs: ["references/edit.md"]
```

## 3. P0：Skill-Scoped 密钥管理

### 3.1 数据层

`netaclaw_skill` 表新增两个字段：

```typescript
// entity/skill.ts
@Column({ type: 'text', comment: 'AES-256-GCM 加密的 secrets JSON', nullable: true })
secrets: string;

@Column({ type: 'json', comment: 'env 声明 schema', nullable: true })
envSchema: Array<{ name: string; required: boolean; description?: string; default?: string }>;
```

### 3.2 新增服务：SkillSecretService

```typescript
// service/skill_secret.ts
@Provide()
@Scope(ScopeEnum.Singleton)
export class SkillSecretService {
  // AES-256-GCM 加密，密钥来自 process.env.SKILL_SECRET_KEY || process.env.APP_SECRET
  encrypt(plainObj: Record<string, string>): string;
  decrypt(cipherText: string): Record<string, string>;

  // 合并 DB secrets + envSchema defaults，返回完整 env map
  async resolveEnv(skillName: string): Promise<Record<string, string>>;

  // 保存 secrets（加密后写入 DB）
  async saveSecrets(skillName: string, secrets: Record<string, string>): Promise<void>;

  // 获取已配置的 key 列表（不返回明文）
  async getConfiguredKeys(skillName: string): Promise<Array<{ name: string; hasValue: boolean }>>;
}
```

### 3.3 API 变更

Admin controller 新增：

```
GET  /admin/netaclaw/skill/envSchema?name=ocr-reader
  → 返回 envSchema 声明 + 每个 key 的 hasValue 状态

POST /admin/netaclaw/skill/secrets
  body: { name: "ocr-reader", secrets: { "OCR_API_KEY": "sk-xxx" } }
  → 加密后存入 DB，不返回明文
```

### 3.4 前端变更

`skill-detail.vue` 抽屉新增"配置"区域：

- 读取 envSchema 展示每个变量的 name、description、required 标记
- 已配置的显示 `[********]` + 修改按钮
- 未配置且 required 的显示红色提示
- 保存时调用 `/secrets` 接口

### 3.5 运行时 env 注入

**compute-entry 模式：** `SkillExecutorService.execute()` 调用 `resolveEnv(skillName)` 注入到子进程 env。

**compute-toolkit 模式：** bash 工具执行时，检查脚本路径是否落在某个 skill 目录下。如果是，自动从 `SkillSecretService.resolveEnv()` 获取对应 env 注入到子进程。判断逻辑：

```typescript
// tools/builtin/bash.ts execute 方法内
const skillName = skillLoader.resolveSkillByPath(cwd || scriptPath);
if (skillName) {
  const skillEnv = await skillSecretService.resolveEnv(skillName);
  Object.assign(processEnv, skillEnv);
}
```

`SkillLoaderService` 新增 `resolveSkillByPath(absPath)` 方法：检查路径是否以某个 skill 目录为前缀，返回 skill name 或 null。

## 4. P1：Skill Runtime Executor

### 4.1 新增服务：SkillExecutorService

```typescript
// service/skill_executor.ts
interface SkillExecuteParams {
  skillName: string;
  input: Record<string, unknown>;
}

interface SkillExecuteResult {
  success: boolean;
  output?: Record<string, unknown>;
  error?: string;
  duration: number;  // ms
}

@Provide()
@Scope(ScopeEnum.Singleton)
export class SkillExecutorService {
  async execute(params: SkillExecuteParams): Promise<SkillExecuteResult>;
}
```

### 4.2 执行流程

```
Agent 调用 execute_skill({ name: "ocr-reader", input: { image_path: "/tmp/a.png" } })
  → SkillExecutorService.execute()
    → 1. 从 SkillLoaderService 获取 skillMeta，确认是 compute-entry
    → 2. 读取 skill.config.yaml：runtime / entrypoint / timeout / interface
    → 3. 验证 input 满足 interface.input（宽松模式：缺少 optional 字段不报错）
    → 4. SkillSecretService.resolveEnv(skillName) 获取 env map
    → 5. 根据 runtime 构建命令：
         python  → {skillDir}/.venv/bin/python {entrypoint}  (win: .venv\Scripts\python)
         node    → node {entrypoint}
         bash    → bash {entrypoint}
         dotnet  → dotnet run --project {entrypoint}
    → 6. spawn 子进程：
         cwd = skillDir
         env = { ...process.env（白名单）, ...skill-scoped env }
         stdin = JSON.stringify(input)
         timeout = config.timeout || 30000
    → 7. 收集 stdout（期望 JSON），stderr 作为日志
    → 8. 解析 stdout JSON → output，返回 SkillExecuteResult
```

### 4.3 新增 Agent 工具：execute_skill

```typescript
// tools/builtin/execute_skill.ts
const ExecuteSkillParams = Type.Object({
  name: Type.String({ description: 'compute skill 名称' }),
  input: Type.Record(Type.String(), Type.Unknown(), { description: '输入参数 JSON' }),
});
```

注册到 catalog：

```typescript
registerSchema({
  name: 'execute_skill',
  toolset: 'skill',
  description: '执行 compute skill',
  capability: 'compute',
  visibility: 'skill',
});
```

工具注入条件：`buildSkillContext()` 检查 Agent 配置的 skills 中是否存在 compute-entry 类型，有则注入 `execute_skill` 工具。

### 4.4 Skill 端协议

entrypoint 脚本遵循 stdin/stdout JSON 协议：

- 从 stdin 读取 JSON 输入
- 环境变量中获取 secrets（如 `os.environ["OCR_API_KEY"]`）
- 将 JSON 结果写入 stdout
- 非零退出码 = 失败，stderr 内容作为错误信息

Python 示例：

```python
import sys, json, os

def main():
    data = json.loads(sys.stdin.read())
    api_key = os.environ["OCR_API_KEY"]
    # ... 业务逻辑 ...
    print(json.dumps({"text": "识别结果", "confidence": 0.95}))

if __name__ == "__main__":
    main()
```

### 4.5 依赖安装改造

`SkillInstallerService.installDependencies()` 重构：

| 依赖类型 | 当前行为 | 改造后 |
|---------|---------|--------|
| `python` | `uv tool install` 全局 | skill 目录下 `uv venv .venv && uv pip install -r requirements.txt` |
| `node` | `pnpm add` 到主项目 | skill 目录下 `npm install` |
| `dotnet` | 不支持 | skill 目录下 `dotnet restore` |
| `system` | 不支持 | 执行 `check` 命令检测，未安装则报诊断 warning |
| `setup` | 不支持 | 首次安装后执行 `setup.posix` 或 `setup.win32` 脚本 |

### 4.6 环境变量白名单

spawn 子进程时不继承完整 `process.env`，只传递白名单：

```typescript
const ENV_WHITELIST = [
  'PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'TZ',
  'TEMP', 'TMP', 'TMPDIR',
  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
];
```

加上 skill-scoped env，确保主系统的敏感变量（DB 密码等）不泄露给 skill 代码。

## 5. P2：Agent Skills 标准兼容

### 5.1 字段映射

| Agent Skills 标准字段 | Neta 映射 | 说明 |
|---|---|---|
| `name` | 直接使用 | 新增命名规范验证 |
| `description` | 直接使用 | 最大 1024 字符 |
| `disable-model-invocation` | 新增支持 | hidden skill，不进入 prompt 索引 |
| `allowed-tools` | → `metadata.conditions.requires_tools` | 语义等价 |
| `compatibility` | → `metadata.compatibility` | 环境要求声明 |
| `license` | → `metadata.license` | 直接存储 |

### 5.2 名称规范验证

新增 `validateSkillName(name: string)` 函数，对齐 Agent Skills 标准：

- 只允许 `[a-z0-9-]`
- 1-64 字符
- 不允许首尾连字符、连续连字符
- 名称必须匹配父目录名

验证时机：安装（GitHub/ZIP）、创建（skill_manage 工具 / REST API）。不合规则拒绝并返回具体错误。已存在的不合规 skill 在 scanSkills 时产生 warning 诊断但仍加载。

### 5.3 Prompt 索引变更

`buildSkillsPrompt()` 输出区分 skill 类型：

```xml
<available_skills>
  <skill name="llm-wiki" type="prompt" category="知识库">
    知识库管理（用 read_skill 加载完整指令）
  </skill>
  <skill name="ocr-reader" type="compute-entry" category="多模态">
    OCR 图片识别（用 execute_skill 调用）
    输入: image_path(string,必填), language(string,默认auto)
  </skill>
  <skill name="minimax-pdf" type="compute-toolkit" category="文档生成">
    PDF 生成/填表/重排版（用 read_skill 加载指令后通过 bash 执行脚本）
  </skill>
</available_skills>
```

compute-entry 的索引包含 `interface.input` 摘要，Agent 无需 read_skill 即可直接调用 execute_skill。

hidden skill（`disable-model-invocation: true`）不出现在索引中，但仍可通过 `read_skill` 显式加载。

### 5.4 `read_skill` 返回格式改造

```typescript
// tools/builtin/read_skill.ts
async execute(_id, params) {
  const skill = skillLoader.getSkill(params.name);
  let result = skill.content;

  // 附属文件：区分必读和可选
  const config = skillLoader.getSkillConfig(params.name);
  const requiredRefs = config?.references?.required || [];
  const optionalRefs = (skill.files || []).filter(f => !requiredRefs.includes(f));

  if (requiredRefs.length > 0) {
    result += `\n\n<skill_required_references>`;
    result += `\n⚠️ 执行此 skill 的任务前，你必须先用 read_skill_file 读取以下文档：`;
    for (const ref of requiredRefs) {
      result += `\n- ${ref}`;
    }
    result += `\n未读取这些文档就执行操作会导致错误。`;
    result += `\n</skill_required_references>`;
  }

  if (optionalRefs.length > 0) {
    result += `\n\n<skill_optional_references>`;
    result += `\n以下文档可按需读取：`;
    for (const ref of optionalRefs) {
      result += `\n- ${ref}`;
    }
    result += `\n</skill_optional_references>`;
  }

  return textResult(result);
}
```

### 5.5 references 声明优先级

references 可以在两个位置声明：

1. `skill.config.yaml` 的 `references` 字段（compute skill）
2. SKILL.md frontmatter 的 `metadata.references` 字段（prompt skill 兼容）

优先级：`skill.config.yaml` > `SKILL.md frontmatter`。如果两者都存在，以 config 为准。对于纯 prompt skill（无 config），从 frontmatter 读取。如果两者都没有，fallback 到现有行为（列出所有附属文件为 optional）。

### 5.6 系统 prompt 层面的约束

`buildSkillsPrompt()` 的引导文本增加：

```
读取 skill 后，如果返回中包含 <skill_required_references>，你必须在执行任何操作前
先用 read_skill_file 逐一读取列出的所有文档。这不是建议，是强制要求。
```

## 6. P3：碰撞检测与诊断系统

### 6.1 诊断数据结构

```typescript
// service/skill_diagnostic.ts
interface SkillDiagnostic {
  level: 'error' | 'warning' | 'info';
  code: string;           // 机器可读的诊断码
  skillName: string;
  message: string;
  path?: string;
  detail?: Record<string, unknown>;
}
```

### 6.2 诊断码清单

| code | level | 触发条件 |
|------|-------|---------|
| `NAME_COLLISION` | warning | 两个 skill 目录解析出相同 name |
| `NAME_INVALID` | warning | 名称不符合 `[a-z0-9-]` 规范 |
| `NAME_MISMATCH` | warning | frontmatter name 与目录名不一致 |
| `DESC_MISSING` | error | 缺少 description，skill 不加载 |
| `DESC_TOO_LONG` | warning | description 超过 1024 字符 |
| `FINGERPRINT_CHANGED` | info | 文件内容变更但未通过正式更新流程 |
| `ENV_NOT_CONFIGURED` | warning | compute skill 声明了 required env 但 DB 无对应 secret |
| `RUNTIME_UNAVAILABLE` | error | 声明 python/node/dotnet 但系统未安装 |
| `SYSTEM_DEP_MISSING` | warning | 系统依赖（ffmpeg 等）check 命令失败 |
| `VENV_MISSING` | warning | Python skill 缺少 .venv 目录 |
| `CONFIG_PARSE_ERROR` | error | skill.config.yaml 解析失败 |

### 6.3 碰撞检测

在 `scanSkills()` 中实现，逻辑参考 pi-mono：

- 维护 `Map<name, skillPath>` 和 `Set<realPath>`
- 同名 skill：保留先发现的（winner），后发现的记录 `NAME_COLLISION` 诊断
- symlink 去重：通过 `fs.realpath` 追踪，同一物理文件不重复加载

### 6.4 诊断收集与暴露

`SkillLoaderService` 新增：

```typescript
private diagnostics: SkillDiagnostic[] = [];

getDiagnostics(): SkillDiagnostic[] { return this.diagnostics; }

// scanSkills() 执行时清空并重新收集
async scanSkills(): Promise<void> {
  this.diagnostics = [];
  // ... 扫描过程中 push 诊断 ...
}
```

### 6.5 API

```
GET /admin/netaclaw/skill/diagnostics
  → 返回当前所有诊断信息列表
  → 支持 ?level=error 过滤
```

### 6.6 前端展示

`skills.vue` 页面顶部新增诊断横幅：

- error 级别：红色警告条，显示数量和摘要
- warning 级别：黄色提示条
- 点击展开查看详细诊断列表（skill 名称 + 诊断码 + 消息）

`skill-detail.vue` 抽屉新增"诊断"区域：只显示该 skill 相关的诊断。

## 7. 对现有系统的兼容性影响

### 7.1 skill_manage 工具

- 创建 skill 时新增名称规范验证，不合规则拒绝
- 如果 content 的 frontmatter 包含 `metadata.env`，自动在 DB 创建 envSchema 记录
- 不影响现有 create/edit/delete 流程

### 7.2 skill 管理页面

- 卡片新增 type 标签（prompt / compute-entry / compute-toolkit）
- 详情抽屉新增"配置"tab（env secrets 管理）
- 详情抽屉新增"诊断"tab
- 安装对话框不变

### 7.3 Agent 运行时

- `buildSkillsPrompt()` 输出格式微调（增加 type 属性），向后兼容
- `buildSkillContext()` 返回的 `skillTools` 条件性新增 `execute_skill`
- hidden skill 不进入 prompt 索引
- bash 工具执行 skill 目录下脚本时自动注入 skill-scoped env

### 7.4 现有 skill 零迁移

- `playwright-cli` 和 `llm-wiki` 没有 `skill.config.yaml`，自动识别为 prompt skill，行为不变
- skills-main 的 skill（minimax-pdf 等）安装后，如果没有 skill.config.yaml 也按 prompt skill 处理；后续可逐步补充 config 文件升级为 compute-toolkit

## 8. 新增文件清单

| 文件 | 说明 |
|------|------|
| `service/skill_secret.ts` | P0：密钥加密存储与解析 |
| `service/skill_executor.ts` | P1：compute-entry 执行器 |
| `service/skill_config.ts` | skill.config.yaml 解析器 |
| `tools/builtin/execute_skill.ts` | P1：Agent 工具 |
| `service/skill_diagnostic.ts` | P3：诊断收集（可合并到 skill_loader） |

## 9. 修改文件清单

| 文件 | 变更 |
|------|------|
| `entity/skill.ts` | 新增 secrets、envSchema 字段 |
| `service/skill_loader.ts` | 加载 skill.config.yaml、碰撞检测、诊断收集、resolveSkillByPath |
| `service/skill_installer.ts` | 依赖安装改造（skill 级 venv/node_modules）、setup 脚本执行 |
| `service/tool_resolver.ts` | execute_skill 工具实例化与条件注入（替代 skill_context.ts） |
| `tools/builtin/read_skill.ts` | 返回格式改造（required/optional references） |
| `tools/builtin/bash.ts` | 重构 createLocalBashOperations 增加 envOverride 参数，skill 路径检测注入 env |
| `controller/admin/skill.ts` | 新增 envSchema/secrets/diagnostics 端点 |
| `service/skill_loader.ts:buildSkillsPrompt` | 输出格式调整（type 属性、required references 提示） |
| `frontend: skills.vue` | 诊断横幅、type 标签 |
| `frontend: skill-detail.vue` | 重构为 tab 布局（基本信息 / 配置 / 诊断） |
| `shared/types/skill.types.ts` | 新增 SkillConfig、SkillDiagnostic，扩展 runtime 枚举 |

## 10. 架构评审补充

### 10.1 工具注入链路修正

`execute_skill` 的注入目标从 `skill_context.ts` 改为 `tool_resolver.ts`。在 `resolve()` 方法中，当检测到 Agent 配置的 skills 包含 compute-entry 类型时，实例化 `execute_skill` 工具并加入工具列表。逻辑位置在现有 `read_skill` 注入点（约 line 603）之后。

`skill_context.ts` 的 `buildSkillContext()` 函数标记为 deprecated，后续迁移到 tool_resolver 内部。

### 10.2 bash 工具 env 注入重构

`bash.ts` 的 `createLocalBashOperations()` 需要重构：

```typescript
// 当前签名
function createLocalBashOperations(shellConfig: ShellConfig): BashOperations

// 改造后
interface BashEnvProvider {
  getAdditionalEnv(cwd: string): Promise<Record<string, string>>;
}

function createLocalBashOperations(
  shellConfig: ShellConfig,
  envProvider?: BashEnvProvider,
): BashOperations
```

`SkillLoaderService` 实现 `BashEnvProvider` 接口：根据 cwd 判断是否在 skill 目录下，是则返回 skill-scoped env。判断策略：严格前缀匹配 `skillsDir + sep + skillName + sep`，不做模糊匹配。

### 10.3 加密方案细化

secrets 字段的线格式：`base64(IV:16bytes || ciphertext || authTag:16bytes)`

```typescript
class SkillSecretService {
  private readonly algorithm = 'aes-256-gcm';
  private readonly ivLength = 16;

  encrypt(plainObj: Record<string, string>): string {
    const iv = crypto.randomBytes(this.ivLength);
    const cipher = crypto.createCipheriv(this.algorithm, this.deriveKey(), iv);
    const encrypted = Buffer.concat([cipher.update(JSON.stringify(plainObj), 'utf8'), cipher.final()]);
    const authTag = cipher.getAuthTag();
    return Buffer.concat([iv, encrypted, authTag]).toString('base64');
  }

  private deriveKey(): Buffer {
    const raw = process.env.SKILL_SECRET_KEY || process.env.APP_SECRET;
    if (!raw) throw new Error('SKILL_SECRET_KEY or APP_SECRET must be set');
    return crypto.createHash('sha256').update(raw).digest(); // 32 bytes
  }
}
```

密钥轮换：提供 `POST /admin/netaclaw/skill/rotateSecrets` 端点，用旧 key 解密所有 secrets 后用新 key 重新加密。密钥丢失时所有 secrets 不可恢复，需管理员重新配置。

### 10.4 DB 迁移

项目使用 TypeORM `synchronize: true`（开发环境）自动同步 entity 变更到数据库。生产环境通过数据库 MCP 工具直接操作，不需要编写 migration SQL 脚本。

实施时只需：
1. 在 `entity/skill.ts` 中添加新字段（`secrets`、`envSchema`、`skillTypeV2`）
2. 开发环境重启后 TypeORM 自动同步表结构
3. 生产环境通过 MCP `execute` 工具执行 ALTER TABLE（如需要）

现有行新字段为 NULL，不影响现有功能。`skillTypeV2` 在 scanSkills 时根据有无 skill.config.yaml 自动填充。

### 10.5 类型同步

`shared/types/skill.types.ts` 更新：

```typescript
export type SkillRuntime = 'node' | 'python' | 'bash' | 'dotnet';
export type SkillClassification = 'prompt' | 'compute-entry' | 'compute-toolkit';
```

DB 的 `skillType` 字段（compute/llm/multimodal）保留不变，它描述的是 skill 的能力类别。新增 `skill_type_v2` 字段存储三分类，两者正交。

### 10.6 Agent 分配 skill 时的类型校验

Agent 编辑页（`agent-edit.vue`）的 skill 选择器改造：

**前端改造：**
- 可选 Skill 列表中每个 skill 显示分类标签（prompt / compute-entry / compute-toolkit）
- 已选择列表中同样显示分类标签
- 当选择 compute-entry 或 compute-toolkit skill 时，如果该 Agent 缺少对应工具权限，显示黄色 warning 提示

**后端校验：**

在 Agent 保存接口（`POST /admin/netaclaw/agent/update`）中新增校验逻辑：

```typescript
// controller/agent.ts 的 update 方法中
if (body.skills?.length) {
  const warnings: string[] = [];
  for (const skillName of body.skills) {
    const classification = this.skillLoader.getSkillClassification(skillName);
    if (classification === 'compute-entry') {
      // 检查 Agent 的 tool governance 是否允许 execute_skill
      // 通过 tool_resolver 的 catalog 检查 execute_skill 是否在 Agent 可用工具列表中
      const toolNames = collectToolNames({ hasSkills: true });
      if (!toolNames.includes('execute_skill')) {
        warnings.push(`Skill "${skillName}" 是 compute-entry 类型，但 execute_skill 工具未启用`);
      }
    }
    if (classification === 'compute-toolkit') {
      const toolNames = collectToolNames({ hasSkills: true });
      if (!toolNames.includes('bash')) {
        warnings.push(`Skill "${skillName}" 是 compute-toolkit 类型，但 bash 工具未启用`);
      }
    }
  }
  // warnings 不阻塞保存，随响应返回
}
```

`/admin/netaclaw/skill/metas` 端点返回数据新增 `classification` 字段，前端据此渲染标签。

### 10.7 基础设施文件过滤

`collectFiles()` 新增排除列表：

```typescript
const INFRA_FILES = new Set([
  'skill.config.yaml', 'requirements.txt', 'package.json',
  'package-lock.json', 'tsconfig.json', '.env',
]);
```

这些文件不出现在 `read_skill` 返回的 `<skill_files>` 列表中，Agent 不会误读。

### 10.8 Skill 执行审计日志

`SkillExecutorService.execute()` 执行完成后写入结构化日志：

```typescript
this.logger.info('[SkillExecutor] %s executed by agent=%s duration=%dms success=%s',
  params.skillName, agentId, result.duration, result.success);
```

失败时额外记录 stderr 摘要（截断到 500 字符）。

### 10.9 setup 脚本安全约束

安装时执行 setup 脚本增加限制：

**后端（skill_installer.ts）：**
- timeout: 120s
- 只允许 `source === 'github'` 或 `source === 'zip'`（管理员手动上传）的 skill 执行 setup
- `source === 'local'`（通过 skill_manage 工具创建）的 skill 不允许 setup 脚本
- 执行前检查 setup 脚本路径不包含 `..`（路径穿越防护）

```typescript
// skill_installer.ts installDependencies 中
const setupKey = process.platform === 'win32' ? 'win32' : 'posix';
const setupScript = config?.setup?.[setupKey];
if (setupScript) {
  const origin = await this.registry.readOrigin(skillName);
  const allowedSources = ['github', 'zip'];
  if (!origin || !allowedSources.includes(origin.source)) {
    logs.push(`[setup] 跳过: 仅 GitHub/ZIP 安装的 skill 允许执行 setup 脚本`);
  } else if (setupScript.includes('..')) {
    logs.push(`[setup] 跳过: setup 脚本路径包含路径穿越`);
  } else {
    // 执行 setup，timeout 120s
  }
}
```

**前端（skills.vue 安装对话框）：**
- 安装完成后，如果 skill 包含 setup 脚本，弹出确认对话框：
  "此 Skill 包含安装脚本（{scriptName}），是否执行？"
- 用户确认后才调用 `/installDeps` 端点

### 10.10 references.routes 的实现策略

routes 匹配在 server 端执行。`read_skill` 工具新增可选参数 `task`：

```typescript
const ReadSkillParams = Type.Object({
  name: Type.String(),
  task: Type.Optional(Type.String({ description: '当前任务描述，用于自动匹配需要读取的文档' })),
});
```

server 端对 `task` 做关键词匹配（`match` 数组中的词是否出现在 task 中），命中则将对应 `required_refs` 的内容直接拼接到返回结果中，Agent 无需二次调用 `read_skill_file`。未命中则 fallback 到 `<skill_required_references>` 列表提示。

### 10.11 Symlink 去重

`scanSkills()` 中维护 `Set<string>` 存储已加载 skill 的 realpath。对每个 skill 目录调用 `fs.realpath()` 获取真实路径，如果已在 set 中则跳过（不产生碰撞诊断，因为是同一物理目录）。

```typescript
const realPathSet = new Set<string>();
// 在加载每个 skill 时
const realPath = await fs.realpath(path.join(this.skillsDir, entry.name)).catch(() => null);
if (realPath && realPathSet.has(realPath)) continue; // 静默跳过 symlink 重复
if (realPath) realPathSet.add(realPath);
```

### 10.12 skill_context.ts 废弃

`skill_context.ts` 的 `buildSkillContext()` 函数标记为 `@deprecated`，添加注释指向 `tool_resolver.ts` 中的新实现。不删除文件，避免破坏可能存在的外部引用。后续版本清理。

```typescript
/**
 * @deprecated 使用 tool_resolver.ts 中的 skill 工具注入逻辑替代。
 * 此函数不再被主链路调用。
 */
export function buildSkillContext(...) { ... }
```