@eggjs/skills 0.0.0 → 4.1.2-beta.5

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

@@ -0,0 +1,289 @@
+# 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/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[] | 仅在指定环境下启动              |

package/egg-core/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: egg-core
+description: 本技能用于处理 EGG 基础核心概念，包括模块架构、@SingletonProto、@ContextProto、@Inject 装饰器和动态注入。用于理解 EGG 的基础构建块、依赖注入、对象生命周期管理和运行时多实现动态选择。
+allowed-tools: Read
+---
+
+# egg 核心概念
+
+## Step 1: 代码写在 module 中
+
+### 什么是模块？
+
+模块是 EGG 中基础的代码组织单元。只有模块内的代码会被框架扫描和加载。模块之间相互独立，但可以通过 `@Inject` 装饰器访问其他模块的对象。
+
+### 定义 module
+
+在目录中添加包含 `eggModule.name` 字段的 `package.json` 文件来声明该目录为模块：
+
+```json
+{
+  "name": "foo",
+  "eggModule": {
+    "name": "foo"
+  }
+}
+```
+
+**重要提示**：模块名称不能包含 `-` 或其他特殊字符；使用驼峰命名规则。
+
+#### 正确示例
+
+```
+app/
+└── userModule/           ✅ 驼峰命名
+    ├── package.json
+    │   └── { "eggModule": { "name": "userModule" } }
+    └── service.ts        ✅ 会被框架加载
+```
+
+#### 错误示例
+
+```
+app/
+├── user-module/          ❌ 名称包含 `-`
+│   └── package.json
+│       └── { "eggModule": { "name": "user-module" } }
+│
+└── common/               ❌ 缺少 package.json（不是 module）
+    └── utils.ts          ❌ 不会被框架加载
+```
+
+#### 模块配置
+
+在模块根目录创建 `module.yml` 用于模块特定配置：
+
+```yaml
+foo: bar
+```
+
+通过 `@Inject()` 注入配置，使用 `moduleConfig`：
+
+```typescript
+import { SingletonProto, Inject } from 'egg';
+
+interface ModuleConfig {
+  foo: string;
+}
+
+@SingletonProto()
+export class ConfigService {
+  @Inject()
+  private readonly moduleConfig: ModuleConfig;
+
+  async hello(): Promise<string> {
+    return `hello ${this.moduleConfig.foo}`;
+  }
+}
+```
+
+#### 模块组织最佳实践
+
+- 新应用：按功能在 `app/` 目录中组织
+- 存量应用：保留老的 egg 代码在 `app/controller`/`app/service`，将新增的 module 代码放在 `app/module/`
+- 可以在 `dependencies` 中导入 npm 包作为额外模块
+
+## Step 2: 用 Proto 实现 Service
+
+### SingletonProto
+
+应用启动时立即创建，整个应用生命周期内只有一个实例，性能更好，应该作为默认选择。
+
+```typescript
+import { SingletonProto } from 'egg';
+
+@SingletonProto()
+export class HelloService {
+  async hello(): Promise<string> {
+    return 'hello';
+  }
+}
+```
+
+### ContextProto
+
+请求到达时按需创建，每个请求一个实例，请求结束自动销毁。仅在需要隔离不同请求的上下文信息时使用。
+
+```typescript
+import { ContextProto } from 'egg';
+
+@ContextProto()
+export class RequestContext {
+  userId: string;
+}
+```
+
+**重要提示**：大多数服务应该使用 `SingletonProto` 以获得更好的性能。只有当请求上下文必须在服务之间共享以确保请求之间隔离时，才使用 `ContextProto`。
+
+### AccessLevel
+
+proto 对象默认 accessLevel 为 `AccessLevel.PRIVATE`，仅在当前 module 内使用。可以设置为 `AccessLevel.PUBLIC`，进行跨模块访问。
+
+```typescript
+import { AccessLevel, ContextProto, SingletonProto } from 'egg';
+
+@SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+export class SharedService {}
+
+@ContextProto({ accessLevel: AccessLevel.PUBLIC })
+export class SharedContextService {}
+```
+
+## Step 3: 通过 Inject 使用 Service
+
+### 基本用法
+
+使用 `@Inject()` 注入其他 Proto 或 Egg 对象：
+
+```typescript
+import { Inject, Logger, SingletonProto } from 'egg';
+import { FooService } from './FooService.ts';
+
+@SingletonProto()
+export class HelloService {
+  @Inject()
+  fooService: FooService;  // 注入另一个 Proto
+
+  @Inject()
+  logger: Logger;  // 注入 Egg 对象
+
+  async hello(): Promise<string> {
+    this.logger.info(`[HelloService] ${this.fooService.hello()}`);
+  }
+}
+```
+
+### 动态注入
+
+当同一个抽象有多种实现，需要在运行时动态选择时，通过 `EggObjectFactory` 按类型获取实现，无需 if/else。详见 `references/dynamic-inject.md`。
+
+### 重要约束
+
+- **不能有循环依赖**：Proto 或模块之间都不能有循环依赖
+- **不能有同名对象**：一个模块不能有相同名称和初始化类型的 Proto
+- **按需注入**：不要直接注入 `app` 或 `ctx`，按需注入特定对象
+
+## 快速决策指南
+
+| 场景                             | 使用装饰器                                             |
+| -------------------------------- | ------------------------------------------------------ |
+| 无状态服务                       | `@SingletonProto()`                                    |
+| 跨服务共享的请求级状态           | `@ContextProto()`                                      |
+| 需要跨模块访问                   | `@SingletonProto({ accessLevel: AccessLevel.PUBLIC })` |
+| 注入依赖                         | `@Inject()`                                            |
+| 使用自定义名称注入               | `@Inject({ name: 'customName' })`                      |
+| 同一抽象多种实现，运行时动态选择 | `QualifierImplDecoratorUtil` + `EggObjectFactory`      |
+
+## 常见问题排查
+
+| 现象                   | 原因                                       | 解决方案                                     |
+| ---------------------- | ------------------------------------------ | -------------------------------------------- |
+| 模块没被加载           | `eggModule.name` 包含 `-` 等特殊字符       | 改为驼峰命名                                 |
+| `EggPrototypeNotFound` | 跨模块注入但 accessLevel 为 PRIVATE        | 改为 `AccessLevel.PUBLIC`                    |
+| 注入对象不对           | 类型为 `interface`/`any`，回退到属性名匹配 | 改用 class 类型或 `@Inject({ name: 'xxx' })` |
+| 混用注入方式报错       | 属性注入和构造函数注入不能混用             | 统一使用一种方式                             |
+| 可选依赖启动报错       | 缺少 optional 标记                         | `@Inject({ optional: true })`                |
+
+## 参考资料
+
+- 详细的 module 文档，请参阅：`references/module.md`
+- Inject 装饰器使用，请参阅：`references/inject.md`
+- SingletonProto 和 ContextProto 详情，请参阅：`references/proto.md`
+- 动态注入（Qualifier 动态注入），请参阅：`references/dynamic-inject.md`

package/egg-core/references/dynamic-inject.md

@@ -0,0 +1,91 @@
+# 动态注入开发指南
+
+## 何时使用
+
+- **用动态注入**：同一抽象有多种实现，运行时按参数选择（如多种支付方式、多种存储后端）
+- **用普通 `@Inject()`**：依赖只有一个实现，编译时就能确定
+
+## Step 1: 定义抽象类和类型枚举
+
+```typescript
+// AbstractHello.ts
+export abstract class AbstractHello {
+  abstract hello(): string;
+}
+
+// HelloType.ts
+export enum HelloType {
+  FOO = 'FOO',
+  BAR = 'BAR',
+}
+```
+
+如果类型是无限扩展的，没有固定枚举，可以用 `Record<string, string>` 代替：
+
+```typescript
+type AnyEnum = Record<string, string>;
+```
+
+## Step 2: 创建自定义装饰器
+
+```typescript
+// decorator/Hello.ts
+import { ImplDecorator, QualifierImplDecoratorUtil } from 'egg';
+import { HelloType } from '../HelloType.ts';
+import { AbstractHello } from '../AbstractHello.ts';
+
+export const HELLO_ATTRIBUTE = Symbol('HELLO_ATTRIBUTE');
+
+export const Hello: ImplDecorator<AbstractHello, typeof HelloType> =
+  QualifierImplDecoratorUtil.generatorDecorator(AbstractHello, HELLO_ATTRIBUTE);
+```
+
+**注意事项：**
+
+- **ATTRIBUTE（Symbol）不要重复**，重复会导致实现被覆盖
+- **抽象类不要指定错**，否则可能导致实现被覆盖
+
+## Step 3: 实现抽象类
+
+每个实现加上 `@SingletonProto()`（或 `@ContextProto()`）和自定义装饰器：
+
+```typescript
+// impl/FooHello.ts
+import { SingletonProto } from 'egg';
+import { Hello } from '../decorator/Hello.ts';
+import { HelloType } from '../HelloType.ts';
+import { AbstractHello } from '../AbstractHello.ts';
+
+@SingletonProto()
+@Hello(HelloType.FOO)
+export class FooHello extends AbstractHello {
+  hello(): string {
+    return 'hello, foo';
+  }
+}
+```
+
+## Step 4: 动态获取实现
+
+通过 `EggObjectFactory` 在运行时按类型获取对应实现：
+
+```typescript
+// HelloService.ts
+import { EggObjectFactory, SingletonProto, Inject } from 'egg';
+import { HelloType } from './HelloType.ts';
+import { AbstractHello } from './AbstractHello.ts';
+
+@SingletonProto()
+export class HelloService {
+  @Inject()
+  private eggObjectFactory: EggObjectFactory;
+
+  async hello(type: HelloType): Promise<string> {
+    const helloImpl = await this.eggObjectFactory.getEggObject(
+      AbstractHello,
+      type,
+    );
+    return helloImpl.hello();
+  }
+}
+```