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-addSYS_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 21 sleep 1 done # 如果是 Java 进程补 jstack if ps -p $PID -o cmd | grep -q java; then jstack $PID $OUTDIR/jstack.txt 21 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.shchmod 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(rThread \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-addSYS_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 进程名通常带 javaGo 进程可以用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 实际根因”的对比后你就知道在什么场景下该信模型、什么场景下该自己判断。这种校准是任何提示词工程都替代不了的只能靠实践积累。最后分享一个小技巧如果你经常需要分析同类进程可以针对这类进程写一个专用的提示词模板把业务背景、正常表现、常见问题都写进去。这样每次分析时模型都能带着上下文准确率会明显提升。模板不用一次写完美用一次改一次几次之后就顺手了。