@eggjs/skills 0.0.0 → 4.1.2-beta.10

package/egg-controller/references/mcp-controller.md

@@ -0,0 +1,293 @@
+# MCPController 开发指南
+
+## 常见错误
+
+生成 MCPController 代码时，**必须**注意以下易错点：
+
+| 错误写法                         | 正确写法                              | 说明                                     |
+| -------------------------------- | ------------------------------------- | ---------------------------------------- |
+| `from 'egg'`                     | `from '@eggjs/tegg'`                  | 所有 MCP 装饰器和类型来自 `@eggjs/tegg`  |
+| `import z from 'zod'`            | `import { z } from '@eggjs/tegg/zod'` | 框架内置 zod，必须使用具名导入           |
+| `z.object({ name: z.string() })` | `{ name: z.string() }`                | Schema 使用普通对象，不要用 `z.object()` |
+| `args: ToolArgs<MySchema>`       | `args: ToolArgs<typeof MySchema>`     | 类型参数必须用 `typeof`                  |
+| `@MCPController` 不加括号        | `@MCPController()`                    | 装饰器必须带括号调用                     |
+
+---
+
+## 文件约定
+
+### 文件位置与命名
+
+MCPController 放在 module 的 `controller/` 目录下，命名规则为 `{Name}MCPController.ts`：
+
+```
+app/module-name/
+├── controller/
+│   ├── PackageMCPController.ts    ← MCP 控制器
+│   └── PackageHTTPController.ts   ← 同模块可共存 HTTP 控制器
+└── service/
+    └── PackageService.ts
+```
+
+### 插件配置
+
+在 `config/plugin.ts` 中启用：
+
+```typescript
+plugin.mcpProxy = true;
+```
+
+### 路径配置
+
+在 `config/config.default.ts` 中配置 MCP 路径（通常不需要修改，以下为默认值）：
+
+```typescript
+import { randomUUID } from 'node:crypto';
+
+export default () => {
+  const config = {
+    mcp: {
+      sseInitPath: '/mcp/sse',
+      sseMessagePath: '/mcp/message',
+      streamPath: '/mcp/stream',
+      statelessStreamPath: '/mcp/stateless/stream',
+      sessionIdGenerator: randomUUID,
+    },
+  };
+  return config;
+};
+```
+
+当使用 `@MCPController({ name: 'myServer' })` 声明命名服务时，路径自动变为：
+
+- `/mcp/myServer/sse`
+- `/mcp/myServer/message`
+- `/mcp/myServer/stream`
+- `/mcp/myServer/stateless/stream`
+
+### AccessLevel
+
+`@MCPController` 装饰器内部已默认设置 AccessLevel（PUBLIC），不需要再手动声明。
+
+---
+
+## 场景决策树
+
+```
+用户需要什么？
+
+├─ "让 AI 能查数据 / 执行操作"
+│  └─ → @MCPTool + @Inject Service 处理业务
+│
+├─ "给 AI 一个提示词模板"
+│  └─ → @MCPPrompt
+│
+├─ "让 AI 读取某类资源数据"
+│  ├─ 资源地址固定 → @MCPResource({ uri: '...' })
+│  └─ 资源地址动态 → @MCPResource({ template: [...] })
+│
+├─ "Tool 执行中要推送进度"
+│  └─ → @MCPTool + @Extra() 获取 sendNotification（见下方 @Extra 章节）
+│
+└─ "Tool 中需要读取自定义请求头"
+   └─ → @MCPTool + @Extra() 获取 requestInfo.headers
+```
+
+---
+
+## 端到端完整示例
+
+以下展示一个完整的 MCP 功能从配置到测试的所有文件：
+
+### 1. 插件配置 — `config/plugin.ts`
+
+```typescript
+plugin.mcpProxy = true;
+```
+
+### 2. 控制器 — `app/npm/controller/PackageMCPController.ts`
+
+```typescript
+import {
+  MCPController,
+  MCPTool,
+  MCPToolResponse,
+  MCPPrompt,
+  MCPPromptResponse,
+  MCPResource,
+  MCPResourceResponse,
+  ToolArgs,
+  ToolArgsSchema,
+  PromptArgs,
+  PromptArgsSchema,
+  Inject,
+} from '@eggjs/tegg';
+import { z } from '@eggjs/tegg/zod';
+
+import { PackageService } from '../service/PackageService.ts';
+
+const SearchSchema = {
+  name: z.string({ description: 'npm package name' }),
+};
+
+const SummarySchema = {
+  name: z.string(),
+};
+
+@MCPController()
+export class PackageMCPController {
+  @Inject()
+  private readonly packageService: PackageService;
+
+  @MCPTool({ description: 'Search npm package info' })
+  async searchPackage(@ToolArgsSchema(SearchSchema) args: ToolArgs<typeof SearchSchema>): Promise<MCPToolResponse> {
+    const pkg = await this.packageService.findByName(args.name);
+    if (!pkg) {
+      return { content: [{ type: 'text', text: `Package ${args.name} not found` }] };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(pkg) }] };
+  }
+
+  @MCPPrompt({ description: 'Generate package summary' })
+  async summarize(@PromptArgsSchema(SummarySchema) args: PromptArgs<typeof SummarySchema>): Promise<MCPPromptResponse> {
+    return {
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Summarize the npm package: ${args.name}`,
+          },
+        },
+      ],
+    };
+  }
+
+  @MCPResource({
+    template: ['npm://{name}/{?version}', { list: undefined }],
+  })
+  async getPackageReadme(uri: URL): Promise<MCPResourceResponse> {
+    const name = uri.hostname;
+    const readme = await this.packageService.getReadme(name);
+    return { contents: [{ uri: uri.toString(), text: readme }] };
+  }
+}
+```
+
+### 3. Service — `app/npm/service/PackageService.ts`
+
+```typescript
+import { SingletonProto } from 'egg';
+
+@SingletonProto()
+export class PackageService {
+  async findByName(name: string) {
+    // 业务逻辑
+  }
+
+  async getReadme(name: string): Promise<string> {
+    // 业务逻辑
+  }
+}
+```
+
+### 4. 单元测试 — `test/npm/controller/PackageMCPController.test.ts`
+
+```typescript
+import assert from 'node:assert';
+import { app } from 'egg-mock/bootstrap';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+describe('PackageMCPController', () => {
+  it('should search package via tool', async () => {
+    app.mockCsrf();
+    const client: Client = await app.mcpClient();
+
+    const tools = await client.listTools();
+    assert(tools.tools.some((t) => t.name === 'searchPackage'));
+
+    const res = await client.callTool({
+      name: 'searchPackage',
+      arguments: { name: 'egg' },
+    });
+    assert(res.content[0].type === 'text');
+  });
+
+  it('should get prompt', async () => {
+    app.mockCsrf();
+    const client: Client = await app.mcpClient();
+
+    const res = await client.getPrompt({
+      name: 'summarize',
+      arguments: { name: 'egg' },
+    });
+    assert(res.messages.length > 0);
+  });
+
+  it('should read resource', async () => {
+    app.mockCsrf();
+    const client: Client = await app.mcpClient();
+
+    const res = await client.readResource({
+      uri: 'npm://egg?version=4.0.0',
+    });
+    assert(res.contents.length > 0);
+  });
+});
+```
+
+---
+
+## @Extra() 的使用场景
+
+`@Extra()` 装饰器注入 `ToolExtra` 对象，提供两个能力：
+
+### 发送通知（长任务进度推送）
+
+```typescript
+@MCPTool()
+async longTask(
+  @ToolArgsSchema(Schema) args: ToolArgs<typeof Schema>,
+  @Extra() extra: ToolExtra,
+): Promise<MCPToolResponse> {
+  const { sendNotification } = extra;
+  for (let i = 0; i < 10; i++) {
+    await sendNotification({
+      method: 'notifications/message',
+      params: { level: 'info', data: `Step ${i + 1}/10` },
+    });
+    // ... 执行步骤
+  }
+  return { content: [{ type: 'text', text: 'Done' }] };
+}
+```
+
+### 读取自定义请求头
+
+```typescript
+@MCPTool()
+async myTool(
+  @ToolArgsSchema(Schema) args: ToolArgs<typeof Schema>,
+  @Extra() extra: ToolExtra,
+): Promise<MCPToolResponse> {
+  const headers = extra.requestInfo?.headers;
+  // 处理自定义 header
+}
+```
+
+---
+
+## 装饰器参考
+
+| 装饰器                | 用途         | 常用参数                                   | 返回类型              |
+| --------------------- | ------------ | ------------------------------------------ | --------------------- |
+| `@MCPController()`    | 声明控制器   | `{ name?: string }`                        | -                     |
+| `@MCPTool()`          | 声明工具     | `{ name?: string, description?: string }`  | `MCPToolResponse`     |
+| `@MCPPrompt()`        | 声明提示词   | `{ name?: string, description?: string }`  | `MCPPromptResponse`   |
+| `@MCPResource()`      | 声明资源     | `{ uri: string }` 或 `{ template: [...] }` | `MCPResourceResponse` |
+| `@ToolArgsSchema()`   | Tool 参数    | Zod Schema 普通对象                        | -                     |
+| `@PromptArgsSchema()` | Prompt 参数  | Zod Schema 普通对象                        | -                     |
+| `@Extra()`            | 额外上下文   | -                                          | `ToolExtra`           |
+| `@Inject()`           | 注入 Service | -                                          | -                     |
+
+**注意**：`@MCPController` 的 `version`、`timeout` 等参数通常不需要配置。

package/egg-controller/references/middleware.md

@@ -0,0 +1,133 @@
+# Middleware 中间件指南
+
+## 常见错误
+
+| 错误写法                                   | 正确写法                           | 说明                                            |
+| ------------------------------------------ | ---------------------------------- | ----------------------------------------------- |
+| `import { Middleware } from '@eggjs/tegg'` | `import { Middleware } from 'egg'` | Middleware 从 `egg` 导入                        |
+| `import { Advice } from 'egg'`             | `import { Advice } from 'egg/aop'` | AOP 装饰器从 `egg/aop` 导入                     |
+| `@Middleware(funcMw, AdviceClass)`         | 分开写两个 `@Middleware`           | 同一个 `@Middleware()` 中不能混用函数式和 AOP   |
+| AOP Advice 中用实例属性存请求级状态        | 使用 `ctx.set()`/`ctx.get()`       | Advice 默认 Singleton，实例属性会被并发请求共享 |
+| 把中间件文件放在 `app/middleware/`         | 放在模块目录下                     | 函数式中间件放在模块中，通过 import 引用        |
+
+---
+
+## 两种中间件模式
+
+Egg 的 `@Middleware` 装饰器支持两种中间件写法，根据传入参数类型自动识别：
+
+- **AOP 写法（推荐）**：使用 `@Advice` 类，支持 `@Inject` 注入 Proto 依赖，拥有丰富的生命周期钩子
+- **函数式写法（旧版兼容）**：标准 Koa 中间件函数，需要从 `ctx` 对象上手动获取依赖
+
+新项目应优先使用 AOP 写法。函数式写法主要用于兼容旧的 egg 中间件或非常简单的场景。
+
+---
+
+## 实现中间件
+
+### AOP 写法（推荐）
+
+使用 `@Advice()` 装饰器定义类，实现 `IAdvice` 的 `around` 方法，写法与 Koa 中间件一致（`next` 调用目标方法）。Advice 本身是 Proto，支持 `@Inject` 注入依赖。`around` 中可以修改入参（`ctx.args`）和返回值：
+
+```typescript
+// app/modules/foo/advice/LogAdvice.ts
+import { AccessLevel, Inject, Logger } from 'egg';
+import { Advice, IAdvice, AdviceContext } from 'egg/aop';
+
+// 跨模块使用时需设置 accessLevel: AccessLevel.PUBLIC
+@Advice({ accessLevel: AccessLevel.PUBLIC })
+export class LogAdvice implements IAdvice {
+  @Inject()
+  logger: Logger;
+
+  async around(ctx: AdviceContext, next: () => Promise<any>): Promise<any> {
+    // 修改入参：ctx.args 对应控制器方法的参数列表
+    // ctx.args[0] = sanitize(ctx.args[0]);
+
+    const start = Date.now();
+    const result = await next();
+    this.logger.info('%s cost %dms', ctx.method, Date.now() - start);
+
+    // 修改返回值：直接返回新的值即可
+    return { success: true, data: result };
+  }
+}
+```
+
+### 函数式写法（旧版兼容）
+
+标准 Koa 中间件函数，签名为 `(ctx: Context, next: Next) => Promise<void>`。旧版 egg 写法，无法使用 `@Inject`，需要从 `ctx` 对象上手动获取依赖：
+
+```typescript
+// app/modules/foo/middleware/count.ts
+import type { Context, Next } from 'egg';
+
+export async function countMw(ctx: Context, next: Next): Promise<void> {
+  const start = Date.now();
+  await next();
+  ctx.set('X-Response-Time', `${Date.now() - start}ms`);
+}
+```
+
+---
+
+## 应用中间件
+
+通过 `@Middleware()` 装饰器将中间件应用到控制器，支持类级别和方法级别：
+
+```typescript
+// app/modules/foo/FooController.ts
+import { HTTPController, HTTPMethod, HTTPMethodEnum, Middleware } from 'egg';
+import { LogAdvice } from '../common/advice/LogAdvice.ts';
+import { countMw } from './middleware/count.ts';
+
+@HTTPController({ path: '/api' })
+@Middleware(LogAdvice) // 类级别：所有方法都会执行
+export class FooController {
+  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/profile' })
+  @Middleware(countMw) // 方法级别：仅此方法执行
+  async getProfile() {
+    return { name: 'test' };
+  }
+}
+```
+
+---
+
+## 执行顺序
+
+遵循洋葱模型，类级别先执行，方法级别后执行：
+
+```typescript
+@Middleware(globalMw)
+export class FooController {
+  // 进：globalMw → methodMw → hello()
+  // 出：hello() → methodMw → globalMw
+  @Middleware(methodMw)
+  async hello() {}
+
+  // 多个 @Middleware 从下往上执行（靠近方法的先注册）
+  // 进：globalMw → mw3 → mw2 → mw1 → multiple()
+  // 出：multiple() → mw1 → mw2 → mw3 → globalMw
+  @Middleware(mw1)
+  @Middleware(mw2)
+  @Middleware(mw3)
+  async multiple() {}
+}
+```
+
+**若混用函数式和 AOP 中间件，所有函数式中间件（无论类级别还是方法级别）会先于所有 AOP 中间件执行。** 即函数式和 AOP 分属两个独立的执行阶段，函数式阶段在前，AOP 阶段在后：
+
+```typescript
+@Middleware(countMw) // 函数式 - 类级别
+@Middleware(LogAdvice) // AOP - 类级别
+export class FooController {
+  @Middleware(timeMw) // 函数式 - 方法级别
+  @Middleware(AuthAdvice) // AOP - 方法级别
+  async hello() {}
+}
+
+// 实际执行顺序：
+// countMw → timeMw → LogAdvice → AuthAdvice → hello()
+// （先所有函数式，再所有 AOP；各阶段内类级别先于方法级别）
+```

package/egg-controller/references/schedule.md

@@ -0,0 +1,110 @@
+# 定时任务开发指南
+
+## 注意事项
+
+- **不要将代码放在 `app/schedule` 目录下**，egg 默认会扫描该路径注册定时任务，会和装饰器方式冲突
+- 定时任务类必须包含一个 `subscribe` 方法，框架调度时会调用该方法
+- import 路径是 `egg/schedule`，不是 `egg`
+
+## Step 1: 创建定时任务
+
+使用 `@Schedule` 装饰器标识一个类为定时任务，支持 interval 和 cron 两种调度模式。
+
+### interval 模式
+
+按固定间隔执行。`interval` 支持毫秒数或 [ms](https://github.com/vercel/ms) 格式字符串（如 `'5s'`、`'1m'`）。
+
+```typescript
+// app/{moduleName}/schedule/Demo.ts
+import { Inject, Logger } from 'egg';
+import { IntervalParams, Schedule, ScheduleType } from 'egg/schedule';
+
+@Schedule<IntervalParams>({
+  type: ScheduleType.WORKER,
+  scheduleData: {
+    interval: '5s',
+  },
+})
+export class DemoScheduler {
+  @Inject()
+  private logger: Logger;
+
+  async subscribe() {
+    this.logger.info('schedule called');
+  }
+}
+```
+
+### cron 模式
+
+按 cron 表达式执行，格式参考 [cron-parser](https://github.com/harrisiirak/cron-parser)：
+
+```text
+*    *    *    *    *    *
+┬    ┬    ┬    ┬    ┬    ┬
+│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
+│    │    │    │    └───── month (1 - 12)
+│    │    │    └────────── day of month (1 - 31)
+│    │    └─────────────── hour (0 - 23)
+│    └──────────────────── minute (0 - 59)
+└───────────────────────── second (0 - 59, optional)
+```
+
+```typescript
+// app/{moduleName}/schedule/CronDemo.ts
+import { Inject, Logger } from 'egg';
+import { CronParams, Schedule, ScheduleType } from 'egg/schedule';
+
+@Schedule<CronParams>({
+  type: ScheduleType.WORKER,
+  scheduleData: {
+    cron: '0 0 3 * * *', // 每日 3 点执行
+  },
+})
+export class CronScheduler {
+  @Inject()
+  private logger: Logger;
+
+  async subscribe() {
+    this.logger.info('schedule called');
+  }
+}
+```
+
+## Step 2: 选择工作模式
+
+| 模式                  | 说明                                     | 使用场景                             |
+| --------------------- | ---------------------------------------- | ------------------------------------ |
+| `ScheduleType.WORKER` | 每台机器只有一个 worker 执行（随机选择） | 大多数场景，如数据同步、缓存刷新     |
+| `ScheduleType.ALL`    | 每台机器的所有 worker 都执行             | 需要每个 worker 都更新本地状态的场景 |
+
+## Step 3: 配置运行参数
+
+`@Schedule` 装饰器支持第二个参数，控制定时任务的运行行为：
+
+```typescript
+@Schedule<IntervalParams>(
+  {
+    type: ScheduleType.WORKER,
+    scheduleData: {
+      interval: '1m',
+    },
+  },
+  {
+    immediate: true, // 应用启动后立即执行一次
+    // disable: true,           // 禁用该定时任务
+    env: ['devserver', 'test'], // 仅在指定环境下启动
+  },
+)
+export class MyScheduler {
+  async subscribe() {
+    // ...
+  }
+}
+```
+
+| 参数        | 类型     | 说明                            |
+| ----------- | -------- | ------------------------------- |
+| `immediate` | boolean  | 应用启动并 ready 后立即执行一次 |
+| `disable`   | boolean  | 设为 true 时不启动该定时任务    |
+| `env`       | string[] | 仅在指定环境下启动              |