docs(skills): add message controller reference and skill writing guid…

packages/skills/controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use when creating API endpoints, implementing protocol handlers, or exposing interfaces for specific clients. Covers HTTP, MCP, Schedule and Message controllers for EGG framework applications.
 allowed-tools: Read
 ---
 
@@ -18,6 +18,8 @@ allowed-tools: Read
 2. 定时任务，可以使用 Schedule，参考 `references/schedule.md`
 
 3. AI集成 MCP，可以使用 MCPController，参考 `references/mcp-controller.md`
+
+4. 消息订阅（sofamq/sofamqx/msgbroker），可以使用 MessageController，参考 `references/message-controller.md`
 ```
 
 ---
@@ -40,6 +42,13 @@ allowed-tools: Read
 - **装饰器**：`@Schedule<T>`、配置
 - **模式**：Worker/All
 
+### MessageController
+
+- **装饰器**：`@MessageController`、`@MessageMethod`
+- **参数**：MessageRequest（消息元数据）
+- **特点**：支持 sofamq/sofamqx/msgbroker 三种消息类型
+- **详细文档**：`references/message-controller.md`
+
 ---
 
 ## 最佳实践
@@ -59,5 +68,6 @@ allowed-tools: Read
 - `references/http-controller.md` - HTTP 接口完整指南
 - `references/mcp-controller.md` - MCP/LLM 集成
 - `references/schedule.md` - 定时任务
+- `references/message-controller.md` - 消息订阅
 
 核心概念（@eggjs/skills-core）：模块、依赖注入、对象生命周期

packages/skills/controller/references/message-controller.md

@@ -0,0 +1,163 @@
+# MessageController 开发指南
+
+## 常见错误
+
+| 错误写法 | 正确写法 | 说明 |
+|---------|---------|------|
+| `from 'egg'` | `from '@eggjs/tegg'` | 所有装饰器来自 `@eggjs/tegg` |
+| 多个 `@MessageMethod` | 一个 `@MessageMethod` | 一个 MessageController 只能有一个处理方法 |
+| msgbroker 缺少 eventCode | 必须指定 eventCode | msgbroker 类型必须同时指定 topic + eventCode + group |
+
+---
+
+## 文件约定
+
+### 文件位置与命名
+
+MessageController 放在 module 的 `controller/` 目录下，命名规则为 `{Name}MessageController.ts`：
+
+```
+app/module-name/
+├── controller/
+│   ├── OrderMessageController.ts    ← 消息控制器
+│   └── OrderHTTPController.ts       ← 同模块可共存 HTTP 控制器
+└── service/
+    └── OrderService.ts
+```
+
+---
+
+## 场景决策树
+
+```
+需要订阅什么类型的消息？
+
+├─ sofamq / sofamqx 消息
+│  └─ → @MessageController({ type: MessageType.SOFAMQ, topic, group })
+│     └─ 可选：tags 过滤
+│
+├─ msgbroker 消息（仅函数应用）
+│  └─ → @MessageController({ type: MessageType.MSGBROKER, topic, eventCode, group })
+│
+└─ 需要获取消息元数据（id 等）
+   └─ → @MessageMethod() 第二个参数 MessageRequest
+```
+
+---
+
+## 端到端完整示例
+
+### SofaMQ 消息订阅
+
+```typescript
+import { Inject, Logger, MessageController, MessageMethod, MessageType } from '@eggjs/tegg';
+
+interface OrderPayload {
+  orderId: string;
+  status: string;
+}
+
+@MessageController({
+  type: MessageType.SOFAMQ,
+  topic: 'TP_ORDER_STATUS',
+  group: 'GID_ORDER_CONSUMER',
+  // tags: ['created', 'paid'],  // 可选：按 tag 过滤
+})
+export class OrderMessageController {
+  @Inject()
+  private readonly logger: Logger;
+
+  @MessageMethod()
+  async handle(data: OrderPayload): Promise<void> {
+    this.logger.info('receive order message', data);
+  }
+}
+```
+
+### MsgBroker 消息订阅（函数应用）
+
+```typescript
+import { Inject, Logger, MessageController, MessageMethod, MessageType } from '@eggjs/tegg';
+
+@MessageController({
+  type: MessageType.MSGBROKER,
+  topic: 'TP_EVENT_TOPIC',
+  eventCode: 'EC_USER_REGISTER',
+  group: 'S_myapp_service',
+})
+export class UserEventMessageController {
+  @Inject()
+  private readonly logger: Logger;
+
+  @MessageMethod()
+  async handle(data: object): Promise<void> {
+    this.logger.info('receive user event', data);
+  }
+}
+```
+
+### 获取消息元数据
+
+```typescript
+import { Inject, Logger, MessageController, MessageMethod, MessageRequest, MessageType } from '@eggjs/tegg';
+
+@MessageController({
+  type: MessageType.SOFAMQ,
+  topic: 'TP_SOME_TOPIC',
+  group: 'GID_SOME_GROUP',
+})
+export class MetadataMessageController {
+  @Inject()
+  private readonly logger: Logger;
+
+  @MessageMethod()
+  async handle(data: object, request: MessageRequest): Promise<void> {
+    this.logger.info('message id: %s, payload: %j', request.id, data);
+    // 更多元数据：request.metadata
+  }
+}
+```
+
+---
+
+## 参数说明
+
+### 通用参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | `MessageType` | 是 | 消息类型：SOFAMQ / SOFAMQX / MSGBROKER |
+| `topic` | `string` | 是 | 消息 topic |
+| `group` | `string` | 是 | 订阅方 group（sofamq: GID_xxx, msgbroker: S_xxx_service） |
+| `eventCode` | `string` | msgbroker 必填 | msgbroker 事件码 |
+| `tags` | `string[]` | 否 | sofamq/sofamqx 按 tag 过滤 |
+
+### 函数应用专属参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `timeout` | `number` | 消息超时时间，超时后消息中心重新投递 |
+| `tps` | `number` | 消息限流 TPS |
+
+### 标准应用专属参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `ldcSubmode` | `'LOCAL' \| 'GZONE' \| 'RZONE' \| 'CZONE'` | sofamq 订阅 zone，默认 LOCAL |
+| `endpoint` | `string` | sofamqx 必填，站点端点 |
+| `concurrent` | `string` | 并发数，默认 20（注意：以 group 维度生效） |
+
+---
+
+## 装饰器参考
+
+| 装饰器 | 用途 | 常用参数 |
+|--------|------|----------|
+| `@MessageController()` | 声明消息控制器 | `{ type, topic, group, eventCode?, tags? }` |
+| `@MessageMethod()` | 声明消息处理方法 | - |
+| `@Inject()` | 注入 Service | - |
+
+**注意**：
+- 一个 `@MessageController` 只能有一个 `@MessageMethod`
+- 标准应用暂不支持订阅 msgbroker 消息
+- 函数应用中 sofamq/sofamqx 消息暂无法获取元数据