GPU_GUARD_MONOREPO/docs/superpowers/plans/2026-04-27-p2-standard-compat.md

# P2: Agent Skills 标准兼容 + References 加载 实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 兼容 Agent Skills 社区标准（名称验证、hidden skill、字段映射），改造 prompt 索引区分三种 skill 类型，改造 read_skill 返回格式强制 Agent 读取 required references。

**Architecture:** 新增 `validateSkillName()` 验证函数。`buildSkillsPrompt()` 输出增加 type 属性和 compute-entry 的 interface 摘要。`read_skill` 工具返回区分 `<skill_required_references>` 和 `<skill_optional_references>`。基础设施文件从 collectFiles 中过滤。

**Tech Stack:** TypeBox, XML 模板, Midway.js

**Spec:** `docs/superpowers/specs/2026-04-27-skill-system-evolution-design.md` Section 5 + 10.5-10.7 + 10.10

**Depends on:** P1 (SkillConfigService, SkillClassification must be integrated into SkillLoaderService before P2 Task 2 can work. Execute P1 Tasks 1-2 first.)

---

### Task 1: 名称验证函数（无依赖，可独立执行）

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/service/skill_loader.ts`

- [ ] **Step 1: 在 skill_loader.ts 顶部新增 validateSkillName 函数**

在 class 定义之前添加：

```typescript
const MAX_NAME_LENGTH = 64;

export function validateSkillName(name: string, parentDirName?: string): string[] {
  const errors: string[] = [];
  if (!name) { errors.push('name is required'); return errors; }
  if (name.length > MAX_NAME_LENGTH) errors.push(`name exceeds ${MAX_NAME_LENGTH} characters`);
  if (!/^[a-z0-9-]+$/.test(name)) errors.push('name must be lowercase a-z, 0-9, hyphens only');
  if (name.startsWith('-') || name.endsWith('-')) errors.push('name must not start or end with hyphen');
  if (name.includes('--')) errors.push('name must not contain consecutive hyphens');
  if (parentDirName && name !== parentDirName) errors.push(`name "${name}" does not match directory "${parentDirName}"`);
  return errors;
}
```

- [ ] **Step 2: 在 parseSkillMd 中调用验证（warning 级别，不阻塞加载）**

在 `parseSkillMd` 方法中，解析出 name 后添加：

```typescript
const nameErrors = validateSkillName(name);
if (nameErrors.length > 0) {
  this.logger.warn('[SkillLoader] Skill "%s" name validation: %s', name, nameErrors.join(', '));
}
```

- [ ] **Step 3: 在 skill_manage.ts 和 skill_installer.ts 的创建/安装流程中调用验证（error 级别，阻塞）**

在 `skill_manage.ts` 的 `execute` 方法中，`create` 分支的 `parseSkillMd` 之后添加：

```typescript
const nameErrors = validateSkillName(parsed.name, params.name);
if (nameErrors.length > 0) {
  return textResult(`名称不合规: ${nameErrors.join('; ')}`);
}
```

在 `skill_installer.ts` 的 `installFromGitHub` 和 `installFromZip` 中，`parseSkillMd` 之后添加类似校验。

- [ ] **Step 4: Commit**

```bash
git add packages/backend/src/modules/netaclaw/service/skill_loader.ts \
       packages/backend/src/modules/netaclaw/tools/builtin/skill_manage.ts \
       packages/backend/src/modules/netaclaw/service/skill_installer.ts
git commit -m "feat(skill): add Agent Skills standard name validation"
```

---

### Task 2: buildSkillsPrompt 输出改造

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/service/skill_loader.ts`

- [ ] **Step 1: 改造 buildSkillsPrompt 方法**

替换现有 `buildSkillsPrompt` 方法：

```typescript
buildSkillsPrompt(skillNames: string[], availableTools: string[]): string {
  const filtered = this.filterByConditions(skillNames, availableTools);
  if (filtered.length === 0) return '';

  const lines: string[] = [];
  let totalChars = 0;

  for (const s of filtered) {
    // 跳过 hidden skill
    const fm = s.metadata as any;
    if (fm?.['disable-model-invocation'] === true) continue;

    const classification = this.skillConfig.classify(s.name);
    const category = fm?.category || '通用';
    const tags = Array.isArray(fm?.tags) ? fm.tags.join(',') : '';

    let body = `    ${s.description}`;

    // compute-entry: 附带 interface.input 摘要
    if (classification === 'compute-entry') {
      const config = this.skillConfig.getConfig(s.name);
      if (config?.interface?.input) {
        const inputDesc = Object.entries(config.interface.input)
          .map(([k, v]) => `${k}(${v.type}${v.required ? ',必填' : ''}${v.default ? ',默认' + v.default : ''})`)
          .join(', ');
        body += `\n    输入: ${inputDesc}`;
      }
    }

    const line = `  <skill name="${s.name}" type="${classification}" category="${category}" tags="${tags}">\n${body}\n  </skill>`;
    if (totalChars + line.length > SkillLoaderService.MAX_SKILLS_PROMPT_CHARS) break;
    lines.push(line);
    totalChars += line.length;
  }

  if (lines.length === 0) return '';

  return `\n\n## 技能（必须扫描）\n回复前，扫描以下技能列表。prompt 类型用 read_skill 加载指令，compute-entry 类型用 execute_skill 直接调用，compute-toolkit 类型用 read_skill 加载指令后通过 bash 执行。\n读取 skill 后，如果返回中包含 <skill_required_references>，你必须在执行任何操作前先用 read_skill_file 逐一读取列出的所有文档。这不是建议，是强制要求。\n\n<available_skills>\n${lines.join('\n')}\n</available_skills>`;
}
```

- [ ] **Step 2: 验证编译通过**

Run: `cd packages/backend && npx tsc --noEmit`

- [ ] **Step 3: Commit**

```bash
git add packages/backend/src/modules/netaclaw/service/skill_loader.ts
git commit -m "feat(skill): enhance buildSkillsPrompt with type classification and required references guidance"
```

---

### Task 3: read_skill 返回格式改造

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/tools/builtin/read_skill.ts`

- [ ] **Step 1: 改造 read_skill 的 execute 方法**

替换现有 `execute` 方法体：

```typescript
async execute(_id, params) {
  const skill = skillLoader.getSkill(params.name);
  if (!skill) {
    return textResult(`未找到名为 "${params.name}" 的 skill`);
  }

  let result = skill.content;

  // 获取 references 配置
  const config = skillLoader.getSkillConfig(params.name);
  const configRefs = config?.references;
  const fmRefs = (skill.metadata as any)?.references;
  const refs = configRefs || fmRefs || null;

  const requiredRefs: string[] = refs?.required || [];
  const allFiles = skill.files || [];

  // 基础设施文件过滤
  const INFRA_FILES = new Set([
    'skill.config.yaml', 'requirements.txt', 'package.json',
    'package-lock.json', 'tsconfig.json', '.env',
  ]);
  const referenceFiles = allFiles.filter(f => !INFRA_FILES.has(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 (referenceFiles.length > 0) {
    result += `\n\n<skill_optional_references>`;
    result += `\n以下文档可按需读取（用 read_skill_file 工具）：`;
    for (const ref of referenceFiles) {
      result += `\n- ${ref}`;
    }
    result += `\n</skill_optional_references>`;
  }

  return textResult(result);
},
```

- [ ] **Step 2: 验证编译通过**

Run: `cd packages/backend && npx tsc --noEmit`

- [ ] **Step 3: Commit**

```bash
git add packages/backend/src/modules/netaclaw/tools/builtin/read_skill.ts
git commit -m "feat(skill): enhance read_skill with required/optional references separation"
```

---

### Task 4: collectFiles 基础设施文件过滤

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/service/skill_loader.ts`

- [ ] **Step 1: 在 collectFiles 方法中过滤基础设施文件**

在 `collectFiles` 方法的 `else if (entry.name !== 'SKILL.md')` 条件中，增加过滤：

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

// 在 else if 分支中
} else if (entry.name !== 'SKILL.md' && !INFRA_FILES.has(entry.name)) {
  const rel = path.relative(baseDir, fullPath).replace(/\\/g, '/');
  results.push(rel);
}
```

- [ ] **Step 2: Commit**

```bash
git add packages/backend/src/modules/netaclaw/service/skill_loader.ts
git commit -m "feat(skill): filter infrastructure files from skill file listing"
```

---

### Task 5: read_skill task 参数与 routes 匹配（Spec 10.10）

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/tools/builtin/read_skill.ts`

- [ ] **Step 1: 给 ReadSkillParams 新增可选 task 参数**

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

- [ ] **Step 2: 在 execute 方法中实现 routes 匹配**

在获取 `requiredRefs` 之后、构建返回结果之前，添加 routes 匹配逻辑：

```typescript
// routes 匹配：如果传入了 task 且 config 有 routes，尝试关键词匹配
let routeMatchedRefs: string[] = [];
if (params.task && refs?.routes) {
  const taskLower = params.task.toLowerCase();
  for (const route of refs.routes) {
    if (route.match.some(keyword => taskLower.includes(keyword.toLowerCase()))) {
      routeMatchedRefs.push(...route.required_refs);
    }
  }
  routeMatchedRefs = [...new Set(routeMatchedRefs)]; // 去重
}

// 合并 required + route matched
const allRequired = [...new Set([...requiredRefs, ...routeMatchedRefs])];
```

如果 `routeMatchedRefs` 命中了文档，尝试直接读取并拼接到返回结果中（减少 Agent 二次调用）：

```typescript
if (routeMatchedRefs.length > 0) {
  result += `\n\n<skill_route_matched_references>`;
  for (const ref of routeMatchedRefs) {
    const filePath = skillLoader.getSkillFilePath(params.name, ref);
    if (filePath) {
      try {
        const content = await fs.readFile(filePath, 'utf-8');
        result += `\n\n--- ${ref} ---\n${content}`;
      } catch { /* skip unreadable */ }
    }
  }
  result += `\n</skill_route_matched_references>`;
}
```

- [ ] **Step 3: Commit**

```bash
git add packages/backend/src/modules/netaclaw/tools/builtin/read_skill.ts
git commit -m "feat(skill): add task parameter and routes matching to read_skill tool"
```

---

### Task 6: Agent 分配 skill 时的类型校验（Spec 10.6）

**Files:**
- Modify: `packages/frontend/src/modules/agent/views/agent-edit.vue`
- Modify: `packages/backend/src/modules/netaclaw/controller/agent.ts`

- [ ] **Step 1: metas 端点返回 classification 字段**

在 `SkillLoaderService.getSkillMetas()` 中，返回对象添加（如果 P3 Task 5 尚未添加）：

```typescript
classification: this.skillConfig.classify(fs.name),
```

- [ ] **Step 2: 前端 skill 选择器显示分类标签**

在 `agent-edit.vue` 的可选 Skill 列表项中（约 line 38），在现有 `skillType` 标签旁新增分类标签：

```vue
<el-tag v-if="sk.classification" size="small"
  :type="sk.classification === 'compute-entry' ? 'success' : sk.classification === 'compute-toolkit' ? '' : 'info'">
  {{ sk.classification }}
</el-tag>
```

已选择列表中同样添加：

```vue
<span class="item-main">{{ getSkillLabel(name) }}</span>
<el-tag size="small" :type="getSkillClassification(name) === 'compute-entry' ? 'success' : 'info'">
  {{ getSkillClassification(name) }}
</el-tag>
```

新增辅助函数：

```typescript
function getSkillClassification(name: string): string {
  const meta = skillMetas.value.find((s) => s.name === name);
  return meta?.classification || 'prompt';
}
```

- [ ] **Step 3: 前端选择 compute skill 时显示工具权限 warning**

在 `addSkill` 函数中添加校验：

```typescript
function addSkill(name: string) {
  if (!form.value.skills.includes(name)) {
    form.value.skills.push(name);
    // 校验工具权限
    const classification = getSkillClassification(name);
    if (classification === 'compute-entry') {
      ElMessage.warning(`"${name}" 是 compute-entry 类型，请确保该 Agent 已启用 execute_skill 工具`);
    } else if (classification === 'compute-toolkit') {
      ElMessage.warning(`"${name}" 是 compute-toolkit 类型，请确保该 Agent 已启用 bash 工具`);
    }
  }
}
```

- [ ] **Step 4: 后端保存时返回 warnings**

在 `controller/agent.ts` 的 `update` 方法中，注入 `SkillLoaderService`，保存前校验：

```typescript
@Inject()
skillLoader: SkillLoaderService;

@Post('/update')
async update(@Body() body: any) {
  const warnings: string[] = [];
  if (body.skills?.length) {
    for (const skillName of body.skills) {
      const classification = this.skillLoader.getSkillClassification(skillName);
      if (classification === 'compute-entry') {
        warnings.push(`Skill "${skillName}" 需要 execute_skill 工具`);
      } else if (classification === 'compute-toolkit') {
        warnings.push(`Skill "${skillName}" 需要 bash 工具`);
      }
    }
  }
  await this.agentService.update(body);
  return { code: 1000, message: 'success', warnings };
}
```

- [ ] **Step 5: Commit**

```bash
git add packages/frontend/src/modules/agent/views/agent-edit.vue \
       packages/backend/src/modules/netaclaw/controller/agent.ts
git commit -m "feat(skill): add skill classification display and tool permission warnings in agent editor"
```

---

### Task 7: skill_context.ts 废弃标记（Spec 10.12）

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/service/skill_context.ts`

- [ ] **Step 1: 添加 @deprecated 注释**

在 `buildSkillContext` 函数上方添加：

```typescript
/**
 * @deprecated 使用 tool_resolver.ts 中的 skill 工具注入逻辑替代。
 * 此函数不再被主链路调用，保留仅为兼容可能的外部引用。
 */
```

- [ ] **Step 2: Commit**

```bash
git add packages/backend/src/modules/netaclaw/service/skill_context.ts
git commit -m "chore(skill): mark buildSkillContext as deprecated"
```