@eggjs/skills 0.0.0 → 4.1.2-beta.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/egg/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: egg
+description: 本技能用于处理 EGG 框架。它提供基于用户意图在核心概念、控制器和单元测试之间做选择的决策指导。作为所有 EGG 相关问题的入口点使用。覆盖模块架构、依赖注入、后台任务、EventBus 事件总线、AOP 切面编程、HTTP/MCP/Schedule 控制器、Ajv 参数校验、单元测试等。
+allowed-tools: Read
+---
+
+# EGG 决策指南
+
+## 概述
+
+本技能帮助根据用户意图和任务类型确定使用哪个专用的 EGG 技能。EGG 文档组织为两个主要领域：
+
+1. **核心概念**（`egg-core` skill）：模块架构、依赖注入、对象生命周期、EventBus 事件总线、AOP 切面编程
+2. **控制器**（`egg-controller` skill）：用于 API 端点的各种协议特定控制器
+3. **单元测试**（`egg-unittest` skill）：HTTP 接口测试、Service/DI 对象测试、Mock 模拟、BackgroundTask 和 EventBus 测试
+
+## 技能选择逻辑
+
+### 使用 `egg-core` skill 当用户询问：
+
+**用户询问关于：**
+
+- 模块架构和组织
+- `@SingletonProto` vs `@ContextProto` 的使用
+- 使用 `@Inject` 的依赖注入
+- 对象生命周期和实例化
+- 模块之间的访问控制（`AccessLevel`）
+- 模块配置（`module.yml`、`package.json`）
+- 使用限定符解决命名冲突
+- 请求返回后执行异步任务（BackgroundTaskHelper）
+- 事件驱动架构（EventBus、@Event）
+- AOP 切面编程（@Advice、@Pointcut、@Crosscut）
+
+**触发关键词：**
+
+- module、workspace、modules
+- singleton、单例、@SingletonProto
+- context、request context、@ContextProto
+- inject、injection、dependency injection、@Inject
+- prototype、lifecycle、实例化
+- background task、异步任务、后台任务、BackgroundTaskHelper
+- eventbus、event bus、事件总线、事件驱动、@Event、emit、发布订阅、解耦
+- aop、切面、aspect、advice、pointcut、crosscut、拦截器、横切关注点
+- access level、private、public、@ModuleQualifier
+- configuration、module config
+
+**示例查询：**
+
+- "如何在 EGG 中创建模块？"
+- "SingletonProto 和 ContextProto 有什么区别？"
+- "如何注入服务？"
+- "如何访问其他模块的对象？"
+- "EGG 中的 AccessLevel 是什么？"
+- "如何用 EventBus 解耦异步任务？"
+- "EventBus 和 BackgroundTaskHelper 有什么区别？"
+- "如何用 AOP 给所有 Service 加日志？"
+
+### 使用 `egg-controller` skill 当用户询问：
+
+**用户询问关于：**
+
+- 创建 API 端点或接口
+- 实现特定协议处理器（HTTP、MCP 等）
+- 连接到外部系统或客户端
+- 处理传入的请求/响应
+- 控制器级别的装饰器和模式
+- 参数校验（Ajv + TypeBox）
+- 控制器中间件（Middleware，函数式或 AOP 写法）
+
+**触发关键词：**
+
+- controller、控制器
+- HTTP、API、REST、endpoint
+- MCP、LLM、AI、tool
+- schedule、timer、cron、scheduled、定时
+- SSE、streaming、server-sent events
+- validate、校验、参数校验、ajv、typebox、schema
+- middleware、中间件、拦截器、洋葱模型、@Middleware
+
+**示例查询：**
+
+- "如何创建 HTTP controller？"
+- "如何实现 MCP 接口？"
+- "怎么实现定时任务？"
+- "帮我给接口加上参数校验"
+- "如何给控制器加中间件？"
+- "怎么写一个鉴权中间件？"
+
+### 使用 `egg-unittest` skill 当用户询问：
+
+**用户询问关于：**
+
+- 编写单元测试或集成测试
+- 使用 @eggjs/mock 进行测试
+- 测试 HTTP 接口（app.httpRequest）
+- 测试 Service/DI 对象
+- Mock 数据或依赖
+- 测试 BackgroundTaskHelper 或 EventBus
+
+**触发关键词：**
+
+- test、测试、单测、单元测试、unittest、unit test
+- mock、mm、@eggjs/mock、mockCsrf、mockHttpclient、mockSession、mockContext
+- httpRequest、supertest
+- getEggObject、mockModuleContextScope
+- eventWaiter、BackgroundTaskHelper 测试
+- vitest、describe、it、beforeAll
+
+**示例查询：**
+
+- "如何写单元测试？"
+- "如何测试 HTTP 接口？"
+- "如何 mock 一个 Service？"
+- "POST 请求测试报 CSRF 错误"
+- "如何测试 ContextProto 的 Service？"
+- "怎么测试后台任务是否执行完成？"
+- "怎么测试 EventBus 事件是否被正确处理？"
+
+---
+
+## 决策框架
+
+### 步骤 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` | -        |
+| Parameter validation    | `egg-controller` | -        |
+| Controller Middleware   | `egg-controller` | -        |
+| Background tasks        | `egg-core`       | -        |
+| Event-driven / EventBus | `egg-core`       | -        |
+| AOP / 切面编程          | `egg-core`       | -        |
+| Cross-module injection  | `egg-core`       | -        |
+| Module structure        | `egg-core`       | -        |
+| Object lifecycle        | `egg-core`       | -        |
+| Unit Testing            | `egg-unittest`   | -        |
+| Mock / Test helpers     | `egg-unittest`   | -        |
+
+## 冲突解决规则
+
+### 规则 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       |
+| Background tasks     | background task、异步任务、后台任务     | `egg-core` skill       |
+| Event-driven         | eventbus、事件总线、@Event、emit        | `egg-core` skill       |
+| AOP 切面编程         | aop、切面、advice、pointcut、crosscut   | `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 |
+| Param validation     | validate、校验、ajv、typebox、schema    | `egg-controller` skill |
+| Middleware 中间件    | middleware、中间件、拦截器、@Middleware | `egg-controller` skill |
+| Unit testing         | test、mock、unittest、单测              | `egg-unittest` skill   |
+| Mock dependencies    | mock、mm、mockCsrf、mockHttpclient      | `egg-unittest` 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"
+
+### 示例 5：测试相关
+
+**用户**："帮我写个 UserController 的单元测试"
+
+**分析**：问题关于编写测试代码
+**决策**：使用 `egg-unittest` skill
+
+**用户**："POST 请求测试报 403 错误"
+
+**分析**：测试中遇到 CSRF 问题
+**决策**：使用 `egg-unittest` skill
+
+## 路由最佳实践
+
+1. **优先考虑显式控制器提及**：如果用户命名特定控制器（HTTP），即使涉及核心概念也使用控制器技能
+
+2. **基础先行**：如果实现前需要理解核心概念，先解释核心概念
+
+3. **简短上下文可以接受**：当路由到一个技能时，提及另一个技能的存在以供后续问题
+
+4. **混合响应可接受**：当意图真正混合时，提供两个技能的简短上下文但专注于主要意图
+
+5. **渐进式披露**：除非明确要求，不要同时加载两个技能。让用户引导探索
+
+---
+
+## 技能交互
+
+本技能（`egg` skill）应该：
+
+- 为框架内部概念路由到 `egg-core` skill
+- 为协议特定实现路由到 `egg-controller` skill
+- 为测试相关问题路由到 `egg-unittest` skill
+- 当意图模糊时提供决策指导
+- 当存在有用的上下文时交叉引用技能

package/egg-controller/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: egg-controller
+description: Use when creating API endpoints, implementing protocol handlers, exposing interfaces for specific clients, adding parameter validation, or applying middleware to controllers. Covers HTTP, MCP and Schedule controllers, Ajv/TypeBox parameter validation, and Middleware (function-style and AOP) 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`
+
+需要做参数校验？
+
+4. 使用 Ajv + TypeBox 做入参校验，参考 `references/ajv-validate.md`
+
+需要给控制器加中间件（日志、鉴权、耗时统计等横切逻辑）？
+
+5. 使用 Middleware，支持函数式写法和 AOP 写法，参考 `references/middleware.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`
+
+### Ajv 参数校验
+
+- **导入**：`import { Ajv, Type, Static } from 'egg/ajv'`
+- **方式**：`@Inject() ajv: Ajv`，调用 `ajv.validate(schema, data)`
+- **特点**：TypeBox 定义一次 Schema，同时获得校验和 TypeScript 类型
+- **详细文档**：`references/ajv-validate.md`
+
+### Middleware 中间件
+
+- **导入**：`import { Middleware } from 'egg'`（AOP 类从 `import { Advice } from 'egg/aop'`）
+- **写法**：函数式（Koa 中间件函数）和 AOP（@Advice 类），通过 `@Middleware()` 应用
+- **特点**：支持类级别和方法级别，函数式和 AOP 不能在同一个 `@Middleware()` 中混用
+- **详细文档**：`references/middleware.md`
+
+---
+
+## 常见问题排查
+
+| 现象                   | 原因                                     | 解决方案                                                           |
+| ---------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
+| MCP 装饰器 import 报错 | 从 `'egg'` 导入                          | MCP 装饰器从 `'@eggjs/tegg'` 导入，zod 从 `'@eggjs/tegg/zod'` 导入 |
+| MCP Schema 报错        | 用了 `z.object()` 包装                   | 直接用普通对象 `{ name: z.string() }`                              |
+| 定时任务不生效         | 放在 `app/schedule` 目录                 | 放在模块目录中，避免和 egg 默认扫描冲突                            |
+| Ajv 校验 import 报错   | 从 `typebox` 或 `ajv` 导入               | 统一从 `'egg/ajv'` 导入 Type、Static、Ajv 等                       |
+| type 推导不完整        | 用 `type` 定义                           | 用 `interface Foo extends Static<typeof Schema> {}` 代替           |
+| Middleware 混用报错    | 函数和 Advice 类放同一个 `@Middleware()` | 分开写多个 `@Middleware()`，每个内部类型一致                       |
+| AOP Middleware 不生效  | Advice 类没加 `@Advice()` 装饰器         | 必须同时有 `@Advice()` 装饰器才能被识别为 AOP                      |
+
+---
+
+## 最佳实践
+
+- **控制器精简**：业务逻辑委托给 Service 层
+- **参数验证**：使用装饰器和类型定义
+- **错误处理**：根据协议转换错误和响应码
+- **RESTful 设计**：遵循 HTTP 方法和资源命名
+- **响应一致性**：统一响应格式
+
+---
+
+## 参考资料
+
+详细的控制器开发文档：
+
+- `references/http-controller.md` - HTTP 接口完整指南
+- `references/mcp-controller.md` - MCP 接口开发
+- `references/schedule.md` - 定时任务
+- `references/ajv-validate.md` - Ajv 参数校验
+- `references/middleware.md` - Middleware 中间件（函数式 + AOP）
+
+核心概念（`egg-core` skill）：模块、依赖注入、对象生命周期
+
+单元测试（`egg-unittest` skill）：HTTP 接口测试、Service 测试、Mock

package/egg-controller/references/ajv-validate.md

@@ -0,0 +1,140 @@
+# Ajv 参数校验指南
+
+## 常见错误
+
+| 错误写法                         | 正确写法                          | 说明                                           |
+| -------------------------------- | --------------------------------- | ---------------------------------------------- |
+| `import { Type } from 'typebox'` | `import { Type } from 'egg/ajv'`  | 必须从 `egg/ajv` 导入，内部已封装 typebox      |
+| `import { Ajv } from 'ajv'`      | `import { Ajv } from 'egg/ajv'`   | Ajv 实例通过 `egg/ajv` 导出                    |
+| `new Ajv()` 手动创建实例         | `@Inject() ajv: Ajv` 注入全局单例 | 框架已配置好 formats 和 keywords，不要自行创建 |
+| 在 Service 中做参数校验          | 在 Controller 中做参数校验        | 入参校验应在 Controller 层完成                 |
+
+---
+
+## 核心概念
+
+Egg 通过 `@eggjs/typebox-validate` 插件集成 Ajv（JSON Schema 校验库）和 TypeBox（TypeScript-first 的 JSON Schema 构建器）。**定义一次 Schema，同时获得参数校验和 TypeScript 类型推导。**
+
+### 导入路径
+
+```typescript
+// 所有 Ajv/TypeBox 相关导入统一从 egg/ajv
+import { Ajv, Type, Static, TransformEnum } from 'egg/ajv';
+```
+
+---
+
+## 使用方式
+
+通过 `@Inject()` 注入全局 Ajv 单例，在 Controller 方法中调用 `ajv.validate()` 进行校验。
+
+### 完整示例
+
+```typescript
+// app/userModule/UserController.ts
+import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPBody, Inject } from 'egg';
+import { Ajv, Type, Static, TransformEnum } from 'egg/ajv';
+
+// 1. 定义 Schema
+const CreateUserSchema = Type.Object({
+  name: Type.String({
+    transform: [TransformEnum.trim],
+    minLength: 1,
+    maxLength: 50,
+  }),
+  email: Type.String({ format: 'email' }),
+  age: Type.Optional(Type.Integer({ minimum: 0, maximum: 150 })),
+});
+
+// 2. 从 Schema 推导类型
+type CreateUserParams = Static<typeof CreateUserSchema>;
+
+// 3. 在 Controller 中注入 Ajv 并校验
+@HTTPController()
+export class UserController {
+  @Inject()
+  private readonly ajv: Ajv;
+
+  @HTTPMethod({
+    method: HTTPMethodEnum.POST,
+    path: '/api/users',
+  })
+  async create(@HTTPBody() body: CreateUserParams) {
+    // 校验失败自动抛出 AjvInvalidParamError
+    this.ajv.validate(CreateUserSchema, body);
+
+    // 校验通过，body 已经有完整类型提示
+    return { name: body.name, email: body.email };
+  }
+}
+```
+
+---
+
+## Schema 定义
+
+### 常用类型
+
+```typescript
+import { Type } from 'egg/ajv';
+
+Type.String(); // string
+Type.Number(); // number
+Type.Integer(); // 整数
+Type.Boolean(); // boolean
+Type.Optional(Type.String()); // string | undefined
+Type.Array(Type.String()); // string[]
+Type.Object({ name: Type.String() }); // { name: string }
+Type.Union([Type.String(), Type.Number()]); // string | number
+Type.Literal('admin'); // 'admin'
+```
+
+完整的 TypeBox JSON Schema 类型定义参考：https://github.com/sinclairzx81/typebox#json-types
+
+### 内置 format 校验
+
+框架通过 `ajv-formats` 预注册了以下格式：
+
+| format      | 说明       | 示例                                   |
+| ----------- | ---------- | -------------------------------------- |
+| `email`     | 邮箱       | `user@example.com`                     |
+| `uri`       | URI        | `https://example.com`                  |
+| `uuid`      | UUID       | `550e8400-e29b-41d4-a716-446655440000` |
+| `date`      | 日期       | `2024-01-01`                           |
+| `date-time` | 日期时间   | `2024-01-01T00:00:00Z`                 |
+| `time`      | 时间       | `12:00:00`                             |
+| `ipv4`      | IPv4       | `192.168.1.1`                          |
+| `ipv6`      | IPv6       | `::1`                                  |
+| `hostname`  | 主机名     | `example.com`                          |
+| `regex`     | 正则表达式 | `^\\d+$`                               |
+
+```typescript
+Type.String({ format: 'email' });
+Type.String({ format: 'uuid' });
+Type.String({ format: 'date-time' });
+```
+
+### transform 预处理
+
+通过 `ajv-keywords` 的 `transform` 关键字，在校验前对字符串做预处理：
+
+```typescript
+import { TransformEnum } from 'egg/ajv';
+
+Type.String({
+  transform: [TransformEnum.trim], // 去除首尾空格
+});
+
+Type.String({
+  transform: [TransformEnum.trim, TransformEnum.toLowerCase], // 去空格 + 转小写
+});
+```
+
+---
+
+## 最佳实践
+
+- **Schema 与 Controller 同文件** — Schema 定义放在使用它的 Controller 文件中，保持就近原则
+- **校验在 Controller 层** — 不要在 Service 层做入参校验，Service 信任上层传入的数据
+- **善用 Optional** — 非必填字段用 `Type.Optional()` 包装，避免前端遗漏字段导致校验失败
+- **善用 transform** — 对用户输入做 trim 预处理，减少脏数据