@eggjs/skills 0.0.0 → 4.1.2-beta.5

package/PLAN.md

@@ -0,0 +1,396 @@
+# Skills 评测方案设计
+
+## 目标
+
+为 `packages/skills/` 设计一套评测体系，覆盖两个层面：
+
+1. **静态校验** — 验证 Skill 文件的结构正确性、引用完整性
+2. **动态评测** — 用 LLM-as-Judge 评估 AI 基于 Skill 生成回答的质量
+
+全部手动触发运行，不集成 CI。
+
+---
+
+## 目录结构
+
+```
+packages/skills/
+├── egg/
+├── controller/
+├── tegg-core/
+├── eval/                          # 新增：评测目录
+│   ├── static/
+│   │   └── validate.test.ts       # 静态校验测试
+│   ├── dynamic/
+│   │   ├── routing.eval.ts        # 入口路由评测
+│   │   └── quality.eval.ts        # 内容质量评测
+│   ├── fixtures/
+│   │   ├── routing-cases.ts       # 路由测试用例
+│   │   └── quality-cases.ts       # 质量测试用例
+│   └── lib/
+│       ├── skill-loader.ts        # Skill 文件加载器
+│       ├── judge.ts               # LLM-as-Judge 核心逻辑
+│       └── types.ts               # 共享类型定义
+├── vitest.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## 第一部分：静态校验
+
+### 校验项
+
+| 校验项               | 说明                                                          |
+| -------------------- | ------------------------------------------------------------- |
+| **Frontmatter 格式** | 每个 SKILL.md 必须包含 `name`、`description`、`allowed-tools` |
+| **引用文件存在性**   | SKILL.md 中提到的 `references/*.md` 文件必须存在              |
+| **交叉引用一致性**   | 入口 skill 提到的子 skill 目录必须存在且包含 SKILL.md         |
+| **Markdown 结构**    | 标题层级合理（以 `# ` 开头，不跳级）                          |
+| **决策表完整性**     | 入口 skill 的路由表中每个 skill 都有对应目录                  |
+
+### 实现方式
+
+使用 vitest + node:assert 编写测试，通过 Node.js fs API 读取文件并解析：
+
+```typescript
+// eval/static/validate.test.ts
+import { describe, it } from 'vitest';
+import assert from 'node:assert/strict';
+import { loadAllSkills } from '../lib/skill-loader.ts';
+
+describe('Skill 静态校验', () => {
+  describe('Frontmatter', () => {
+    it('每个 SKILL.md 包含必填字段: name, description, allowed-tools', ...);
+  });
+
+  describe('引用完整性', () => {
+    it('SKILL.md 中引用的 references/ 文件均存在', ...);
+    it('入口 skill 引用的子 skill 目录均存在', ...);
+  });
+
+  describe('Markdown 结构', () => {
+    it('标题层级不跳级', ...);
+  });
+});
+```
+
+---
+
+## 第二部分：动态评测（LLM-as-Judge）
+
+### 评测维度
+
+动态评测分为两个子场景：
+
+#### 2.1 路由评测 — 入口 Skill 是否正确路由
+
+测试 `egg/SKILL.md` 的决策逻辑：给定用户查询，判断 AI 是否路由到正确的子 skill。
+
+**测试用例结构：**
+
+```typescript
+// eval/fixtures/routing-cases.ts
+export const routingCases: RoutingCase[] = [
+  {
+    query: '如何创建 HTTP controller？',
+    expectedSkill: 'controller',
+    reason: '明确提到 controller，属于协议实现',
+  },
+  {
+    query: '@SingletonProto 和 @ContextProto 有什么区别？',
+    expectedSkill: 'tegg-core',
+    reason: '关于对象生命周期，属于核心概念',
+  },
+  {
+    query: '我需要创建一个可以被 HTTP 控制器使用的服务',
+    expectedSkill: 'tegg-core',
+    reason: '模糊意图，按规则 1（基础优先）应路由到 core',
+  },
+  // ... 更多用例
+];
+```
+
+**测试实现：**
+
+```typescript
+// eval/dynamic/routing.eval.ts
+import { describe, it } from 'vitest';
+import assert from 'node:assert/strict';
+import Anthropic from '@anthropic-ai/sdk';
+import { loadSkillContent } from '../lib/skill-loader.ts';
+import { routingCases } from '../fixtures/routing-cases.ts';
+
+const client = new Anthropic();
+const AVAILABLE_SKILLS = ['controller', 'tegg-core'];
+
+describe('路由评测', () => {
+  // 加载入口 skill 作为 system prompt
+  const entrySkillContent = loadSkillContent('egg');
+
+  for (const { query, expectedSkill, reason } of routingCases) {
+    it(`"${query}" → ${expectedSkill}`, async () => {
+      // 1. 将 SKILL.md 作为 system prompt，发送用户查询
+      const response = await client.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 1024,
+        system: [
+          entrySkillContent,
+          // 约束输出格式，让 AI 只做路由决策
+          `你是 EGG 框架技能路由器。根据上面的决策指南，分析用户查询并选择应该加载的技能。`,
+          `可选技能: ${AVAILABLE_SKILLS.join(', ')}`,
+          `只输出 JSON: {"skill": "<技能名>", "reason": "<简要理由>"}`,
+        ].join('\n\n'),
+        messages: [{ role: 'user', content: query }],
+      });
+
+      // 2. 解析 AI 回答中的路由选择
+      const text = response.content[0].type === 'text' ? response.content[0].text : '';
+      const parsed = JSON.parse(text);
+
+      // 3. 断言路由正确性
+      assert.equal(parsed.skill, expectedSkill,
+        `路由错误: 期望 "${expectedSkill}" 但得到 "${parsed.skill}"` +
+        `\n  用例理由: ${reason}` +
+        `\n  AI 理由: ${parsed.reason}`
+      );
+    });
+  }
+});
+```
+
+#### 2.2 内容质量评测 — 子 Skill 回答质量
+
+测试各子 skill 对领域问题的回答质量。
+
+**测试用例结构：**
+
+```typescript
+// eval/fixtures/quality-cases.ts
+export const qualityCases: QualityCase[] = [
+  {
+    skill: 'controller',
+    query: '如何创建一个 POST 接口接收 JSON body？',
+    criteria: [
+      '使用 @HTTPController 装饰器',
+      '使用 @HTTPMethod 且 method 为 POST',
+      '使用 @HTTPBody() 获取请求体',
+      '包含完整可运行的代码示例',
+    ],
+    references: ['references/http-controller.md'],  // 需要加载的参考文档
+  },
+  {
+    skill: 'tegg-core',
+    query: '如何让一个服务可以被其他模块访问？',
+    criteria: [
+      '提到 AccessLevel.PUBLIC',
+      '使用 @SingletonProto 装饰器',
+      '解释跨模块访问机制',
+    ],
+    references: [],
+  },
+  // ... 更多用例
+];
+```
+
+**测试实现：**
+
+```typescript
+// eval/dynamic/quality.eval.ts
+import { describe, it } from 'vitest';
+import assert from 'node:assert/strict';
+import Anthropic from '@anthropic-ai/sdk';
+import { loadSkillContent, loadReference } from '../lib/skill-loader.ts';
+import { qualityCases } from '../fixtures/quality-cases.ts';
+import { judge } from '../lib/judge.ts';
+
+const client = new Anthropic();
+
+describe('内容质量评测', () => {
+  for (const testCase of qualityCases) {
+    describe(`[${testCase.skill}] ${testCase.query}`, () => {
+      let aiResponse: string;
+
+      // Step 1: 加载 skill 内容作为 system prompt，向被测 LLM 提问
+      it('生成回答', async () => {
+        const skillContent = loadSkillContent(testCase.skill);
+        const refContents = testCase.references
+          .map(ref => loadReference(testCase.skill, ref));
+
+        const systemPrompt = [skillContent, ...refContents].join('\n\n---\n\n');
+
+        const response = await client.messages.create({
+          model: 'claude-sonnet-4-20250514',
+          max_tokens: 2048,
+          system: systemPrompt,
+          messages: [{ role: 'user', content: testCase.query }],
+        });
+
+        aiResponse = response.content[0].type === 'text' ? response.content[0].text : '';
+        assert.ok(aiResponse.length > 0, 'AI 应该返回非空回答');
+      });
+
+      // Step 2: 用 Judge LLM 对回答逐项评分
+      it('通过质量评审', async () => {
+        const result = await judge(client, {
+          query: testCase.query,
+          response: aiResponse,
+          criteria: testCase.criteria,
+        });
+
+        // 输出详细评分到 console 供人工查看
+        console.log(`    得分: ${result.totalScore} (${result.passed}/${result.total})`);
+        for (const item of result.details) {
+          const icon = item.score === 1 ? '✓' : '✗';
+          console.log(`      ${icon} ${item.criterion}: ${item.reason}`);
+        }
+
+        // 断言：所有 criteria 都应满足
+        assert.ok(result.totalScore >= 0.8,
+          `质量不达标: ${result.totalScore} < 0.8\n` +
+          result.details
+            .filter(d => d.score === 0)
+            .map(d => `  ✗ ${d.criterion}: ${d.reason}`)
+            .join('\n')
+        );
+      });
+    });
+  }
+});
+```
+
+### LLM-as-Judge 实现
+
+```typescript
+// eval/lib/judge.ts
+import type Anthropic from '@anthropic-ai/sdk';
+import type { JudgeInput, JudgeResult, JudgeDetail } from './types.ts';
+
+export async function judge(
+  client: Anthropic,
+  input: JudgeInput,
+): Promise<JudgeResult> {
+  const criteriaList = input.criteria
+    .map((c, i) => `${i + 1}. ${c}`)
+    .join('\n');
+
+  const response = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 1024,
+    system: '你是 AI 回答质量评估专家。严格按照 JSON 格式输出评分结果。',
+    messages: [{
+      role: 'user',
+      content: `请根据评分标准，对以下 AI 回答逐项评分。
+
+## 评分标准
+${criteriaList}
+
+## 用户问题
+${input.query}
+
+## AI 回答
+${input.response}
+
+## 输出格式（严格 JSON）
+{
+  "details": [
+    { "criterion": "标准内容", "score": 0 或 1, "reason": "简要理由" }
+  ]
+}`,
+    }],
+  });
+
+  const text = response.content[0].type === 'text' ? response.content[0].text : '';
+  const parsed = JSON.parse(text);
+  const details: JudgeDetail[] = parsed.details;
+  const passed = details.filter(d => d.score === 1).length;
+
+  return {
+    details,
+    passed,
+    total: details.length,
+    totalScore: passed / details.length,
+  };
+}
+```
+
+### 评测报告
+
+运行评测后生成 JSON 报告：
+
+```json
+{
+  "timestamp": "2026-02-05T10:00:00Z",
+  "routing": {
+    "total": 10,
+    "correct": 9,
+    "accuracy": 0.9,
+    "failures": [
+      {
+        "query": "...",
+        "expected": "tegg-core",
+        "actual": "controller",
+        "reason": "..."
+      }
+    ]
+  },
+  "quality": {
+    "controller": {
+      "cases": 5,
+      "avg_score": 0.85,
+      "details": [...]
+    },
+    "tegg-core": {
+      "cases": 5,
+      "avg_score": 0.90,
+      "details": [...]
+    }
+  }
+}
+```
+
+---
+
+## 第三部分：技术选型与依赖
+
+| 组件                  | 选型               | 理由                           |
+| --------------------- | ------------------ | ------------------------------ |
+| 测试框架              | vitest             | 遵循 monorepo 标准             |
+| 断言库                | node:assert/strict | Node.js 内置，零依赖           |
+| YAML frontmatter 解析 | gray-matter        | 成熟的 frontmatter 解析库      |
+| LLM 调用              | @anthropic-ai/sdk  | 使用 Claude API 做评测和 Judge |
+| 报告输出              | JSON 文件          | 简单可读，方便后续扩展为可视化 |
+
+### package.json scripts
+
+```json
+{
+  "scripts": {
+    "test": "vitest run --config vitest.config.ts eval/static/",
+    "eval": "vitest run --config vitest.config.ts eval/dynamic/",
+    "eval:routing": "vitest run --config vitest.config.ts eval/dynamic/routing.eval.ts",
+    "eval:quality": "vitest run --config vitest.config.ts eval/dynamic/quality.eval.ts"
+  }
+}
+```
+
+- `test` — 运行静态校验（快速，无 API 调用）
+- `eval` — 运行全部动态评测
+- `eval:routing` — 仅运行路由评测
+- `eval:quality` — 仅运行内容质量评测
+
+动态评测需设置 `ANTHROPIC_API_KEY` 环境变量。
+
+---
+
+## 实施步骤
+
+1. 在 worktree (`egg-skills-eval`) 中添加依赖：vitest、gray-matter、@anthropic-ai/sdk
+2. 添加 `vitest.config.ts` 和更新 `package.json` scripts
+3. 创建 `eval/lib/` 基础工具：skill-loader、types、judge
+4. 实现 `eval/static/validate.test.ts` 静态校验
+5. 编写路由测试用例 `eval/fixtures/routing-cases.ts`
+6. 实现 `eval/dynamic/routing.eval.ts` 路由评测
+7. 编写质量测试用例 `eval/fixtures/quality-cases.ts`
+8. 实现 `eval/dynamic/quality.eval.ts` 内容质量评测

package/egg/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: egg
+description: 本技能用于处理 EGG 框架。它提供基于用户意图在核心概念和控制器之间做选择的决策指导。作为所有 EGG 相关问题的入口点使用。
+allowed-tools: Read
+---
+
+# EGG 决策指南
+
+## 概述
+
+本技能帮助根据用户意图和任务类型确定使用哪个专用的 EGG 技能。EGG 文档组织为两个主要领域：
+
+1. **核心概念**（`egg-core` skill）：模块架构、依赖注入、对象生命周期
+2. **控制器**（`egg-controller` skill）：用于 API 端点的各种协议特定控制器
+
+## 技能选择逻辑
+
+### 使用 `egg-core` skill 当用户询问：
+
+**用户询问关于：**
+
+- 模块架构和组织
+- `@SingletonProto` vs `@ContextProto` 的使用
+- 使用 `@Inject` 的依赖注入
+- 对象生命周期和实例化
+- 模块之间的访问控制（`AccessLevel`）
+- 模块配置（`module.yml`、`package.json`）
+- 使用限定符解决命名冲突
+
+**触发关键词：**
+
+- module、workspace、modules
+- singleton、单例、@SingletonProto
+- context、request context、@ContextProto
+- inject、injection、dependency injection、@Inject
+- prototype、lifecycle、实例化
+- access level、private、public、@ModuleQualifier
+- configuration、module config
+
+**示例查询：**
+
+- "如何在 EGG 中创建模块？"
+- "SingletonProto 和 ContextProto 有什么区别？"
+- "如何注入服务？"
+- "如何访问其他模块的对象？"
+- "EGG 中的 AccessLevel 是什么？"
+
+### 使用 `egg-controller` skill 当用户询问：
+
+**用户询问关于：**
+
+- 创建 API 端点或接口
+- 实现特定协议处理器（HTTP、MCP 等）
+- 连接到外部系统或客户端
+- 处理传入的请求/响应
+- 控制器级别的装饰器和模式
+
+**触发关键词：**
+
+- controller、控制器
+- HTTP、API、REST、endpoint
+- MCP、LLM、AI、tool
+- schedule、timer、cron、scheduled、定时
+- SSE、streaming、server-sent events
+
+**示例查询：**
+
+- "如何创建 HTTP controller？"
+- "如何实现 MCP 接口？"
+- "怎么实现定时任务？"
+
+---
+
+## 决策框架
+
+### 步骤 1：识别意图类型
+
+询问：**用户是在询问构建块/框架内部 OR 实现特定接口？**
+
+**构建块/框架内部** → 使用 `egg-core` skill
+
+- 理解 EGG 如何工作
+- 组织代码结构
+- 管理对象生命周期
+- 设置模块
+
+**实现特定接口** → 使用 `egg-controller` skill
+
+- 创建 API/端点
+- 处理不同协议
+- 处理请求/响应
+
+### 步骤 2：检查模糊意图
+
+如果用户的意图可能是核心 OR 控制器（例如，"如何实现一个需要跨模块访问的服务？"）：
+
+**决策优先级**：核心概念优先
+
+理由：即使服务将在控制器中使用，关于跨模块访问（`AccessLevel`）的基本问题是一个核心概念。一旦理解了核心结构，用户就可以在控制器中应用它。
+
+**行动**：
+
+1. 使用 `egg-core` skill
+2. 解释概念（例如，`AccessLevel.PUBLIC`）
+3. 核心解释后，建议："如果你需要在特定控制器中使用它，请使用 `egg-controller` skill
+
+### 步骤 3：协议/用例特定指示器
+
+| 协议/用例              | 主要技能         | 次要技能 |
+| ---------------------- | ---------------- | -------- |
+| HTTP API               | `egg-controller` | -        |
+| MCP                    | `egg-controller` | -        |
+| Scheduled Tasks        | `egg-controller` | -        |
+| Cross-module injection | `egg-core`       | -        |
+| Module structure       | `egg-core`       | -        |
+| Object lifecycle       | `egg-core`       | -        |
+
+## 冲突解决规则
+
+### 规则 1：基础优先
+
+当问题同时涉及核心概念 AND 控制器实现时：
+
+- **示例**："如何实现一个 HTTP 控制器可以使用的单例服务？"
+- **决策**：从 `egg-core` skill 开始解释 SingletonProto 和 AccessLevel
+- **后续**："现在你理解了服务定义，使用 `egg-controller` skill 实现注入此服务的 HTTP 控制器。"
+
+### 规则 2：显式覆盖
+
+如果用户明确提及特定控制器类型：
+
+- **示例**："如何使用 HTTPController 配合 ContextProto 服务？"
+- **决策**：使用 `egg-controller` skill（HTTPController 是显式的）
+- **后续**：解释 HTTPController 实现，如果需要简要提及来自核心概念的 ContextProto
+
+### 规则 3：学习语境
+
+如果用户问"什么是 X？"或"Y 如何工作？"：
+
+- **核心概念问题** → 使用 `egg-core` skill
+- **控制器类型问题** → 使用 `egg-controller` skill
+- **一般 EGG 问题** → 使用本技能的决策框架
+
+如果用户问"如何实现 X？"或"给我看 Y 的代码？"：
+
+- **实现特定问题** → 根据决策框架加载特定 skill
+
+## 快速参考表
+
+| 用户意图             | 关键词                          | 使用技能               |
+| -------------------- | ------------------------------- | ---------------------- |
+| Module architecture  | module、workspace、organization | `egg-core` skill       |
+| Object lifecycle     | singleton、context、lifecycle   | `egg-core` skill       |
+| Dependency injection | inject、@Inject、dependency     | `egg-core` skill       |
+| Access control       | private、public、cross-module   | `egg-core` skill       |
+| HTTP endpoints       | HTTP、API、REST                 | `egg-controller` skill |
+| LLM/AI integration   | MCP、tool、prompt               | `egg-controller` skill |
+| Scheduling           | schedule、cron、timer           | `egg-controller` skill |
+
+---
+
+## 示例
+
+### 示例 1：明确的核心意图
+
+**用户**："@SingletonProto 和 @ContextProto 有什么区别？"
+
+**分析**：问题关于核心装饰器和对象生命周期
+**决策**：使用 `egg-core` skill
+
+**用户**："如何在 EGG 中创建模块？"
+
+**分析**：问题关于模块架构（核心概念）
+**决策**：使用 `egg-core` skill
+
+### 示例 2：明确的控制器意图
+
+**用户**："如何创建返回 JSON 的 HTTP controller？"
+
+**分析**：问题关于实现特定协议（HTTP）
+**决策**：使用 `egg-controller` skill
+
+### 示例 3：模糊意图（核心 > 控制器）
+
+**用户**："我需要创建一个可以被 HTTP 控制器使用的服务。如何实现？"
+
+**分析**：用户需要理解核心概念（跨模块访问）AND 控制器实现
+**决策**：首先使用 `egg-core` skill（基础）
+
+**响应**：
+
+1. 解释 `@SingletonProto` 配合 `AccessLevel.PUBLIC` 使服务可访问
+2. 展示如何注入服务：`@Inject() myService: MyService`
+3. 后续："现在你可以在 HTTPController 中注入此服务。实现详情请使用 `egg-controller` skill。"
+
+### 示例 4：显式控制器加上核心知识
+
+**用户**："如何在 HTTPController 中使用 @Inject 访问用户服务？"
+
+**分析**：用户明确提及 HTTPController（控制器类型）但询问 @Inject（核心概念）
+**决策**：使用 `egg-controller` skill（HTTPController 是明确意图）
+
+**响应**：
+
+1. 展示配合 `@Inject` 的 HTTPController 实现
+2. 简要解释 @Inject 如何工作（核心概念摘要）
+3. 注意："包含限定符的详细 @Inject 使用，请使用 `egg-core` skill"
+
+## 路由最佳实践
+
+1. **优先考虑显式控制器提及**：如果用户命名特定控制器（HTTP），即使涉及核心概念也使用控制器技能
+
+2. **基础先行**：如果实现前需要理解核心概念，先解释核心概念
+
+3. **简短上下文可以接受**：当路由到一个技能时，提及另一个技能的存在以供后续问题
+
+4. **混合响应可接受**：当意图真正混合时，提供两个技能的简短上下文但专注于主要意图
+
+5. **渐进式披露**：除非明确要求，不要同时加载两个技能。让用户引导探索
+
+---
+
+## 技能交互
+
+本技能（`egg` skill）应该：
+
+- 为框架内部概念路由到 `egg-core` skill
+- 为协议特定实现路由到 `egg-controller` skill
+- 当意图模糊时提供决策指导
+- 当存在有用的上下文时交叉引用技能

package/egg-controller/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: egg-controller
+description: Use when creating API endpoints, implementing protocol handlers, or exposing interfaces for specific clients. Covers HTTP, MCP and Schedule controllers for EGG framework applications.
+allowed-tools: Read
+---
+
+# EGG 控制器
+
+---
+
+## 控制器选择决策树
+
+```
+需要暴露什么接口/客户端协议？
+
+1. HTTP 接口？例如 HTML/JSON/SSR/SSE，可以使用 HTTPController，参考 `references/http-controller.md`
+
+2. 定时任务，可以使用 Schedule，参考 `references/schedule.md`
+
+3. MCP 接口，可以使用 MCPController，参考 `references/mcp-controller.md`
+```
+
+---
+
+## 控制器快速参考
+
+### HTTPController
+
+- **装饰器**：`@HTTPController`、`@HTTPMethod`
+- **参数**：`@HTTPParam`、`@HTTPQuery`、`@HTTPBody`、`@HTTPHeaders`、`@Cookies`、`@Request`、`@Context`
+- **详细文档**：`references/http-controller.md`
+
+### MCPController
+
+- **装饰器**：`@MCPController`、`@MCPTool`、`@MCPPrompt`、`@MCPResource`
+- **特点**：集成 LLM、Zod 验证、登录态支持
+- **详细文档**：`references/mcp-controller.md`
+
+### Schedule
+
+- **装饰器**：`@Schedule<T>`
+- **模式**：Worker/All
+- **详细文档**：`references/schedule.md`
+
+---
+
+## 常见问题排查
+
+| 现象                   | 原因                     | 解决方案                                                           |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------ |
+| MCP 装饰器 import 报错 | 从 `'egg'` 导入          | MCP 装饰器从 `'@eggjs/tegg'` 导入，zod 从 `'@eggjs/tegg/zod'` 导入 |
+| MCP Schema 报错        | 用了 `z.object()` 包装   | 直接用普通对象 `{ name: z.string() }`                              |
+| 定时任务不生效         | 放在 `app/schedule` 目录 | 放在模块目录中，避免和 egg 默认扫描冲突                            |
+
+---
+
+## 最佳实践
+
+- **控制器精简**：业务逻辑委托给 Service 层
+- **参数验证**：使用装饰器和类型定义
+- **错误处理**：根据协议转换错误和响应码
+- **RESTful 设计**：遵循 HTTP 方法和资源命名
+- **响应一致性**：统一响应格式
+
+---
+
+## 参考资料
+
+详细的控制器开发文档：
+
+- `references/http-controller.md` - HTTP 接口完整指南
+- `references/mcp-controller.md` - MCP 接口开发
+- `references/schedule.md` - 定时任务
+
+核心概念（`egg-core` skill）：模块、依赖注入、对象生命周期