docs(skills): add troubleshooting tables based on eval results

- egg-core SKILL.md: add common issues table (naming, AccessLevel, interface type, mixed inject, optional)
- egg-controller SKILL.md: add troubleshooting table (MCP imports, z.object, schedule directory)
- mcp-controller.md: expand decision tree with @extra use cases

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gxkl

packages/skills/egg-controller/SKILL.md

@@ -38,8 +38,19 @@ allowed-tools: Read
 
 ### Schedule
 
-- **装饰器**：`@Schedule<T>`、配置
+- **装饰器**：`@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 默认扫描冲突                            |
 
 ---
 

packages/skills/egg-controller/references/mcp-controller.md

@@ -86,8 +86,11 @@ export default () => {
 │  ├─ 资源地址固定 → @MCPResource({ uri: '...' })
 │  └─ 资源地址动态 → @MCPResource({ template: [...] })
 │
-└─ "Tool 执行中要推送进度"
-   └─ → @MCPTool + @Extra() 获取 sendNotification
+├─ "Tool 执行中要推送进度"
+│  └─ → @MCPTool + @Extra() 获取 sendNotification（见下方 @Extra 章节）
+│
+└─ "Tool 中需要读取自定义请求头"
+   └─ → @MCPTool + @Extra() 获取 requestInfo.headers
 ```
 
 ---

packages/skills/egg-core/SKILL.md

@@ -174,6 +174,16 @@ export class HelloService {
 | 使用自定义名称注入               | `@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`