1. 项目缘起与整体设计思路
1.1 这个标题到底在说什么
“pstack-claude”这个名字，第一次看到的人大概率会愣一下。pstack 在传统运维语境里是一个打印进程调用栈的诊断工具，而 claude 是当下热度极高的 AI 编程助手。把这两个词拼在一起，直觉告诉我这不是简单的工具组合，而是有人想把“进程级诊断能力”和“AI 辅助编程能力”缝合成一条工作流——用 pstack 抓取运行时状态，再把状态喂给 claude 做分析、定位、甚至生成修复建议。
我拿到这个标题之后，先做了一轮拆解。核心领域落在三个交叉点上：Linux 系统诊断、AI 编程助手集成、自动化工作流编排。潜在需求也很明确——开发者遇到线上进程卡死、CPU 飙高、死锁这类问题时，传统做法是手动 pstack、手动看栈、手动搜索，效率低且依赖经验；如果能把这一串动作交给一个可复用的脚本或工具链，让 claude 参与解读，就能把“老师傅的直觉”变成“可复制的流程”。
适合谁来参考？三类人：一是经常和 Linux 服务打交道的后端与运维工程师；二是正在探索 AI 辅助调试的开发者；三是想把 claude 接入自有工具链、做二次封装的技术爱好者。哪怕你只是刚装好 claude code 的新手，这篇文章里的思路和踩坑记录也能帮你少走弯路。
1.2 为什么选择“诊断+AI”这条路线
传统诊断流程有个很现实的痛点：pstack 输出的栈信息是给“懂行的人”看的。一个 Java 进程的线程栈、一个 C++ 服务的调用栈，几百上千行，新手看了头大，老手也要花时间比对。而 claude 这类模型最擅长的恰恰是“读大量结构化文本并给出归纳”。把两者结合，逻辑上非常顺。
我在设计这套方案时，刻意避开了“全自动无人值守”的诱惑。原因很简单：诊断这件事，误判成本很高。如果让 AI 直接下结论“这是死锁”，而实际是 IO 阻塞，可能把排查方向带偏。所以我的设计原则是——pstack 负责采集事实，claude 负责归纳线索，人负责最终判断。这个分工是整套方案的地基，后面所有脚本和提示词都围绕它展开。
另一个考量是工具选型。为什么用 pstack 而不是 gdb、perf 或者 eBPF？因为 pstack 的门槛最低、依赖最少、输出最直观。它本质是对 gdb 的一层封装，一条命令就能打印指定进程所有线程的栈，不需要 attach 交互、不需要编译调试符号（有更好，没有也能看个大概）。对于“快速抓现场”这个场景，pstack 的性价比最高。当然它也有局限，比如对某些语言运行时支持一般，这个后面会专门讲。
1.3 整体架构长什么样
整套 pstack-claude 的思路可以拆成四层。第一层是采集层，用 pstack 加一些辅助命令（top、ps、jstack 等）把进程现场固定下来。第二层是整理层，把原始输出做清洗、去重、截断，变成适合喂给模型的文本。第三层是分析层，通过 claude 的接口或 claude code 把整理后的内容送进去，配合精心设计的提示词拿到分析结果。第四层是归档层，把现场数据和分析结论一起存下来，方便复盘和对比。
这四层里，最容易被人忽略的是第二层“整理层”。很多人直接把几千行 pstack 输出丢给模型，结果要么超长被截断，要么模型被噪声干扰给出泛泛而谈的结论。我实测下来，整理层的质量直接决定分析层的效果。所以后面我会花不少篇幅讲怎么清洗、怎么截断、怎么保留关键上下文。
提示：整套方案不依赖任何特定网络环境，所有命令和脚本都在本地或自有服务器上完成，采集与分析环节可以完全离线，只有调用模型接口那一步需要你已有的正常访问方式。
2. 核心细节解析与实操要点
2.1 pstack 到底能抓到什么
先把 pstack 讲透。它的基本用法是pstack <pid>，输出是该进程每个线程的调用栈，格式大致是线程号加一串函数调用，从当前执行点一路回溯到线程入口。比如一个卡住的进程，你能看到它停在pthread_cond_wait还是read还是某个锁上，这直接决定了排查方向。
但 pstack 有几个必须知道的特性。第一，它默认抓的是“当前瞬间”，如果进程在快速变化，你抓到的可能只是某一帧，所以建议连续抓 3 到 5 次，间隔 1 到 2 秒，对比栈有没有变化。第二，pstack 依赖 ptrace 权限，普通用户抓别的用户的进程会失败，通常需要 root 或同用户。第三，某些进程（比如被 seccomp 限制的容器内进程）可能抓不到，这时候要换 nsenter 进命名空间再抓。
我踩过的一个坑是：在容器里直接 pstack，报ptrace: Operation not permitted。后来发现是容器的 seccomp 策略挡了 ptrace 系统调用。解决办法是加--cap-add=SYS_PTRACE启动容器，或者用docker exec进容器后以 root 执行。这个细节很多教程不会提，但实际生产环境里非常常见。
2.2 采集脚本怎么写才靠谱
单条 pstack 命令不够，我一般会写一个采集脚本，把现场一次性打包。脚本的核心逻辑是：接收 pid 和输出目录，依次执行一组命令，把结果分别落盘。下面是我常用的一个简化版本。
#!/bin/bash PID=$1 OUTDIR=${2:-./diag_$(date +%Y%m%d_%H%M%S)} mkdir -p "$OUTDIR" echo "采集进程 $PID 现场到 $OUTDIR" # 基础信息 ps -p "$PID" -o pid,ppid,user,%cpu,%mem,etime,cmd > "$OUTDIR/ps.txt" top -b -n 1 -H -p "$PID" > "$OUTDIR/top_threads.txt" 2>/dev/null # 连续抓栈 for i in 1 2 3; do pstack "$PID" > "$OUTDIR/pstack_$i.txt" 2>&1 sleep 1 done # 如果是 Java 进程，补 jstack if ps -p "$PID" -o cmd= | grep -q java; then jstack "$PID" > "$OUTDIR/jstack.txt" 2>&1 fi echo "采集完成"这个脚本有几个设计点值得说。连续抓三次栈是为了看变化，如果三次栈完全一样，基本可以判定是稳定阻塞；如果栈在变，说明进程在跑，问题可能在别处。top -H是为了看线程级 CPU 占用，能快速定位是哪个线程在烧 CPU，再和 pstack 里的线程号对应。jstack 的补充是因为 pstack 对 JVM 的栈解析不够友好，jstack 能给出更清晰的 Java 层调用。
注意：采集脚本本身要尽量轻量，别在进程已经卡死的时候再给它加压。top 用
-n 1只采一次，避免长时间占用。
2.3 整理层：把原始输出变成模型能吃的格式
采集完的原始文件直接丢给模型，效果往往不好。原因有三个：一是 pstack 输出里大量重复的线程栈会稀释关键信息；二是文件之间缺乏关联，模型不知道哪个线程对应哪个 CPU 占用；三是总长度可能超出上下文窗口。
我的整理策略是“先关联，再压缩，后标注”。关联是指把 top 里的高 CPU 线程号和 pstack 里的线程号对上，把 jstack 里的线程名和 pstack 的线程号对上。压缩是指对重复的栈做归并，比如 50 个线程都停在同一个等待点，就合并成一条并标注数量。标注是指在文本里加上人类可读的提示，比如“以下线程 CPU 占用最高”“以下线程栈连续三次无变化”。
整理后的文本大概长这样：
[进程概况] PID 12345, 用户 app, CPU 320%, 内存 12%, 运行 3天2小时 [高CPU线程] 线程 12350: CPU 98%, 栈顶函数 do_compress 线程 12351: CPU 95%, 栈顶函数 do_compress [稳定阻塞线程] 线程 12360-12410 (共51个): 三次抓栈均停在 pthread_cond_wait 线程 12420: 三次抓栈均停在 read [关键栈片段] 线程 12350: do_compress -> compress_block -> ...这样一份文本，长度可能只有原始的十分之一，但信息密度高得多。模型拿到之后，很容易就能看出“两个线程在压缩、一堆线程在等条件变量、一个线程在等 IO”这个全局图景。
2.4 提示词怎么设计才不跑偏
提示词是整套方案里最需要打磨的部分。我试过很多版本，最后稳定下来的结构是“角色+任务+约束+输出格式”四段式。角色让模型进入状态，任务说清楚要干什么，约束防止它乱猜，输出格式保证结果可读。
一个我常用的提示词骨架：
你是一名资深 Linux 性能诊断工程师。下面是一个进程的现场采集数据， 包含进程概况、线程 CPU 占用、连续三次的调用栈。 请完成以下任务： 1. 归纳进程当前的整体状态（正常/阻塞/死锁/CPU密集/IO等待） 2. 指出最可疑的线程和函数，说明理由 3. 给出下一步排查建议，按优先级排序 约束： - 只基于提供的数据推断，数据不足时明确说“无法判断” - 不要编造未出现的函数名或线程号 - 如果多个线程栈相同，合并分析 输出格式： ## 整体状态 ## 可疑点 ## 排查建议这里最关键的是“数据不足时明确说无法判断”这条约束。没有它，模型很容易为了给出答案而强行编造，这在诊断场景里是致命的。我实测下来，加上这条约束后，模型说“无法判断”的比例明显上升，但给出的判断准确率也明显提升。
3. 实操过程与核心环节实现
3.1 从零搭一套可复用的诊断流程
假设你现在有一台 Linux 服务器，上面跑着一个疑似卡住的服务，你想用 pstack-claude 这套思路排查。完整流程分六步。
第一步，定位进程。用ps aux | grep 服务名或者systemctl status找到 pid。如果服务是多进程的，先确认你要查的是哪个，通常是 CPU 或内存占用最高的那个。
第二步，跑采集脚本。把上面的脚本存成collect.sh，chmod +x，然后sudo ./collect.sh <pid>。等它跑完，你会得到一个带时间戳的目录。
第三步，人工粗看。别急着喂模型，先自己cat一下 ps.txt 和 top_threads.txt，对进程状态有个基本判断。这一步能帮你发现一些明显问题，比如进程其实已经 OOM 快挂了，或者 CPU 占用根本不高，那排查方向就完全不同。
第四步，整理数据。如果采集量不大，手动整理也行；如果线程多，建议写个小脚本做归并。我一般用 Python 快速处理，核心逻辑是按栈内容分组计数。
import re from collections import Counter def parse_pstack(path): stacks = {} current_tid = None with open(path) as f: for line in f: m = re.match(r'Thread \d+ \(Thread (\d+)\)', line) if m: current_tid = m.group(1) stacks[current_tid] = [] elif current_tid and line.strip(): stacks[current_tid].append(line.strip()) return stacks def summarize(stacks): sig = Counter() for tid, frames in stacks.items(): key = frames[0] if frames else 'unknown' sig[key] += 1 return sig这段代码把每个线程的栈顶函数作为签名，统计出现次数。跑完你就能看到“有多少线程卡在同一个点”，这是判断死锁或资源耗尽的关键依据。
第五步，调用模型分析。把整理后的文本和提示词一起发给 claude。如果你用的是 claude code，可以直接在项目目录里让它读文件分析；如果走 API，就把文本拼进 prompt。
第六步，归档。把原始采集、整理文本、模型输出三样东西存在一起，命名带上时间戳和 pid。下次再出问题，可以对比两次的差异，很多时候问题的根因就藏在“这次和上次哪里不一样”里。
3.2 一次真实的排查记录
说个我实际遇到的案例。一个数据处理服务，运行几天后响应变慢，最后完全卡住。按流程走一遍。
采集阶段，ps 显示进程 CPU 只有 5%，内存正常，运行时间 3 天。top -H 显示所有线程 CPU 都不高。连续三次 pstack，发现 200 多个线程里有 180 个停在pthread_cond_wait，剩下 20 个停在read，只有 2 个在真正干活。
整理后喂给模型，提示词里我特意加了一句“这是一个数据处理服务，正常应该有较高 CPU 占用”。模型给出的归纳是：进程处于“生产者-消费者”模型下的消费者饥饿状态，大量工作线程在等条件变量，少数线程卡在 IO 读，怀疑上游数据源没有数据产出，或者数据管道某处断了。
这个判断和我的直觉一致，但模型把它说得更结构化。顺着“上游没数据”这个方向查，最后发现是上游一个消息队列的连接断了，消费者线程全在等，而重连逻辑有 bug 没触发。整个排查从采集到定位，不到 20 分钟。如果没有这套流程，光看 200 多个线程的栈就要花不少时间。
3.3 参数选择与阈值设定
这套流程里有几个参数需要根据实际情况调。抓栈次数，我默认 3 次，间隔 1 秒。如果进程变化很快，可以加到 5 次、间隔 0.5 秒；如果进程很稳定，2 次就够。线程归并的粒度，我一般按栈顶函数归并，但如果栈顶都是通用函数（比如epoll_wait），就要往下多看几层，按第二、第三个函数归并。
喂给模型的文本长度，这个要看你用的模型上下文窗口。我的经验是控制在 8000 到 15000 字符之间比较合适，太短信息不够，太长模型注意力会分散。如果原始数据超了，优先保留高 CPU 线程、稳定阻塞线程的代表栈，以及进程概况，把大量重复的栈压缩成计数。
提示词里的约束强度，这个需要根据你对模型输出的信任度调整。初期建议约束严一点，宁可它说“无法判断”，也不要它乱猜。用熟了之后可以适当放宽，让它给出更多推测性建议。
提示：不同模型对提示词的敏感度不一样，同一套提示词在 A 模型上效果好，在 B 模型上可能就跑偏。建议固定用一个模型，把提示词当成代码一样版本管理，每次调整都记录效果。
4. 常见问题与排查技巧实录
4.1 pstack 抓不到栈怎么办
这是最高频的问题。表现是执行 pstack 后输出ptrace: Operation not permitted或者干脆没输出。原因通常有三类。
第一类是权限问题。pstack 需要 ptrace 权限，普通用户只能抓自己的进程。解决方法是加 sudo，或者用同用户执行。如果进程是 root 起的，你也得用 root。
第二类是容器限制。容器默认的 seccomp 策略会拦截 ptrace。解决方法是启动容器时加--cap-add=SYS_PTRACE，或者用--privileged（不推荐，权限太大）。已经在跑的容器没法改，只能进容器内部以 root 抓，或者用nsenter -t <pid> -p进命名空间。
第三类是内核参数。有些系统开了kernel.yama.ptrace_scope，限制 ptrace 只能抓子进程。临时解决是echo 0 > /proc/sys/kernel/yama/ptrace_scope，但重启会失效，要持久化得改 sysctl.conf。
4.2 模型分析结果不靠谱怎么调
模型给出离谱结论，通常不是模型的问题，是输入的问题。我总结了几种典型情况和对应处理。
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 结论泛泛而谈 | 输入信息太少或太杂 | 补充进程概况，压缩重复栈 |
| 编造不存在的函数 | 约束不够强 | 提示词加“不得编造” |
| 判断方向完全错 | 缺少业务上下文 | 提示词里补充服务类型和正常表现 |
| 输出格式混乱 | 格式要求不明确 | 给出明确的输出模板 |
| 忽略关键线程 | 关键信息被淹没 | 把可疑线程单独提到文本开头 |
我个人的经验是，输入质量占七成，提示词占三成。与其反复调提示词，不如先把采集和整理做扎实。一份干净、有重点、带标注的输入，配一个简单的提示词，效果往往好过一份杂乱输入配一个精心设计的提示词。
4.3 采集本身会不会影响线上服务
这是很多人担心的点。pstack 的原理是 attach 到目标进程然后读内存，attach 的瞬间目标进程会暂停。对于大多数服务，这个暂停是毫秒级的，基本无感。但如果进程本身已经濒临崩溃，或者对延迟极度敏感（比如高频交易），attach 可能触发超时或雪崩。
我的建议是：生产环境采集前先评估风险。如果服务有健康检查，attach 导致的短暂暂停可能触发健康检查失败，进而被重启。这种情况要么在低峰期采集，要么先摘掉流量。另外，连续抓多次栈意味着多次 attach，累积影响会放大，所以抓栈次数别贪多，3 次足够。
还有一个替代方案是gdb -p <pid> -batch -ex "thread apply all bt"，效果类似，但 gdb 更重。如果只是快速看，pstack 更轻。如果进程对暂停极度敏感，可以考虑用 perf 或 eBPF 做无侵入采样，但那是另一套技术栈了，门槛更高。
4.4 怎么把这套流程沉淀成团队资产
一个人用和团队用，差别很大。团队用需要解决三个问题：标准化、可追溯、可复用。
标准化是指采集脚本、整理脚本、提示词模板都固定下来，放进代码仓库，谁用都跑同一套。可追溯是指每次诊断都归档，带上时间、pid、操作人、结论，形成知识库。可复用是指把常见问题的分析结论沉淀成检查清单，下次遇到类似现象可以直接对照。
我见过做得好的团队，会把 pstack-claude 这套流程封装成一个内部命令，比如diag <service>，自动完成采集、整理、分析、归档，最后输出一份报告。新人遇到问题，跑一条命令就能拿到初步分析，再结合自己的判断深入。这比口口相传“遇到卡死先 pstack”要靠谱得多。
提示：归档时建议把原始采集文件也保留，不要只存整理后的文本。因为整理策略可能会变，原始数据是唯一的真相来源，将来想用新方法重新分析还有得查。
5. 工具链扩展与进阶玩法
5.1 和 claude code 结合的正确姿势
如果你已经在用 claude code，这套流程可以更顺。做法是在项目目录里建一个diag/文件夹，把采集脚本和整理脚本放进去，然后直接在 claude code 里让它执行脚本、读取输出、给出分析。这样省去了手动复制粘贴的步骤。
具体操作是：在 claude code 的对话里说“运行 diag/collect.sh 抓取 pid 12345 的现场，然后分析 diag 目录下的输出”。claude code 会调用终端执行脚本，读取生成的文件，然后基于文件内容分析。这里的关键是让 claude code 读文件而不是把内容贴进对话，因为文件内容可能很长，贴进对话会占用上下文，而读文件是按需加载的。
我实测下来，这种方式比手动复制粘贴效率高很多，尤其是在需要反复采集、对比多次结果的时候。你可以让它“对比 diag_001 和 diag_002 两次采集的差异”，它会自动读两个目录做对比，这是手动操作很难快速做到的。
5.2 多语言进程的适配
pstack 对 C/C++ 进程最友好，对 Java、Go、Python 这些有运行时或 GC 的语言，栈信息会夹杂大量运行时函数，可读性下降。这时候需要配合语言专属工具。
Java 用 jstack，输出的是 Java 层线程栈，比 pstack 清晰得多。Go 可以用kill -QUIT <pid>触发 goroutine dump，或者用dlvattach。Python 可以用py-spy dump --pid <pid>，能直接给出 Python 层的调用栈。这些工具的输出格式不同，整理层需要做相应适配，但整体思路一致——采集、整理、喂模型、分析。
我的做法是在采集脚本里根据进程类型自动选择工具。判断方式很简单，看进程名或者/proc/<pid>/exe指向什么。Java 进程名通常带 java，Go 进程可以用go version -m /proc/<pid>/exe判断，Python 进程看 cmdline 里有没有 python。这样一套脚本能覆盖大部分场景。
5.3 从单次诊断到持续观测
单次诊断解决的是“已经出问题了怎么办”。更进一步是“在出问题之前发现苗头”。做法是把采集脚本做成定时任务，每隔一段时间抓一次关键指标和栈快照，存起来。当指标异常时，自动触发完整采集和分析。
这个思路本质是把 pstack-claude 从“急救工具”变成“体检工具”。比如你可以每小时抓一次线程数和栈顶分布，画成趋势图。当某个等待点的线程数持续上升，就说明资源在慢慢耗尽，这时候介入比等到完全卡死要好得多。
实现上，定时采集用 cron 或 systemd timer，存储用简单的文件加时间戳，分析可以定期跑一次模型做趋势归纳。这套东西不复杂，但需要坚持跑一段时间才能积累出有价值的基线数据。有了基线，异常检测就有了参照，模型分析也能结合历史给出更准的判断。
6. 我踩过的坑和几条实在建议
6.1 别把模型当神，也别当摆设
我见过两种极端。一种是完全不信模型，觉得 AI 分析栈信息就是瞎猜；另一种是完全依赖模型，模型说什么就是什么。这两种都不可取。
模型的价值在于快速归纳和提供线索，它能在几秒内读完几百行栈并给出结构化总结，这是人做不到的速度。但它缺乏业务上下文，不知道你的服务正常应该是什么样，也不知道最近有没有改过代码。所以正确的用法是：模型给线索，人做判断，两者互补。
我自己的习惯是，模型给出分析后，我会问自己三个问题：这个结论和我的直觉一致吗？如果不一致，是模型错了还是我漏了什么？模型提到的可疑点，我能用其他证据验证吗？这三个问题过一遍，基本能过滤掉大部分误判。
6.2 采集时机比采集工具更重要
很多人纠结用什么工具采集，却忽略了什么时候采集。进程卡死是一个动态过程，你在不同时间点采集，拿到的现场可能完全不同。刚卡住时采集，能看到卡住的瞬间状态；卡了很久再采集，可能已经被各种超时和重试搅乱了。
我的建议是一旦发现异常，尽快采集，别等。如果条件允许，在服务里预埋一个信号处理，收到特定信号就自动采集现场，这样能在问题发生的第一时间抓到数据。很多疑难问题之所以难查，就是因为现场没保住，等人工介入时已经时过境迁。
6.3 归档和复盘是被低估的环节
诊断做完，问题解决，很多人就把数据删了。这是巨大的浪费。每一次诊断都是一次宝贵的样本，归档下来，积累多了就是团队的诊断知识库。
我自己的做法是，每次诊断后写一段简短的复盘：现象是什么、采集到了什么、模型分析是什么、最终根因是什么、模型判断对不对。这段复盘和采集数据存在一起。时间长了，你会发现某些问题反复出现，某些模型的判断模式有规律，这些都是可以沉淀成经验的。
复盘还有一个好处是能校准模型。当你积累了几十次“模型判断 vs 实际根因”的对比后，你就知道在什么场景下该信模型、什么场景下该自己判断。这种校准是任何提示词工程都替代不了的，只能靠实践积累。
最后分享一个小技巧：如果你经常需要分析同类进程，可以针对这类进程写一个专用的提示词模板，把业务背景、正常表现、常见问题都写进去。这样每次分析时模型都能带着上下文，准确率会明显提升。模板不用一次写完美，用一次改一次，几次之后就顺手了。
