Save this content to: .claude/skills/swoole-chain-trace/SKILL.md

# Swoole 链路追踪

## 概览

在修改现有行为之前先使用这个 skill。默认原则是：在完整上下游链路没有弄清楚之前，不要直接修表象。

## 作用范围

除非用户明确允许扩展范围，否则只在这些目录内工作：

- `/Users/lanhai/projects/swoole/scf`
- `/Users/lanhai/projects/swoole/apps/<app>`
- `/Users/lanhai/projects/vue-admin/<frontend-app>`
- `/Users/lanhai/projects/vue-admin/crawler`
- `/Users/lanhai/projects/vue-admin/dashboard`

如果依赖继续指向范围外目录，先暂停并征求确认。

## 必走流程

### 1. 先确认完整链路

在提出改动前，至少把下面 5 层串起来：

1. 用户侧入口
2. 后端/API/Controller 入口
3. 分发、IPC、Socket、队列或进程交接点
4. 真正执行动作的执行器
5. 结果、超时、回调或状态回传路径

### 2. 把症状放回链路里定位

必须明确回答：

- 具体是哪一步在阻塞或失败
- 为什么这一步会失败
- 上游有哪些行为依赖这一步
- 修复后会影响哪些下游行为

不要把“慢”“超时”“没响应”当成根因。

### 3. 证据优先，不靠猜测

优先做快速、针对性的代码扫描：

- 用 `rg` 查入口、路由、方法名、错误文本、队列名、Socket 事件
- 小范围读关键文件，不做大面积无差别扫描
- 以现有运行链路、注解和项目约定为准

### 4. 只改最小正确点

不要默认先做这些动作：

- 改成异步
- 调大或调小超时
- 加缓存或兜底
- 提前返回
- 加重试

只有在完整链路已经证明这是正确修复点时，才允许这样改。

## 输出要求

在进行较大改动前，先总结：

1. 完整链路是什么
2. 真正阻塞或失败的是哪一步
3. 最小正确改动点在哪
4. 预期副作用是什么

如果链路还不完整，就继续追踪，不要先补丁。

真实项目入口索引请看 `references/entrypoints.md`。