上个月有个一起搞开发的朋友看到我显示器边框上贴着一张密密麻麻的小卡片问我是不是已经把 Pi Coding Agent 的所有参数都背进脑子了。我说恰恰相反——正因为记不住我才把它做成了一张速查表信息卡。这张 A6 大小的卡片不到两百克却写满了这个编程代理最高频的指令、提示词模板、配置项和排错备注。遇到临时状况时扭头扫一眼两秒内就能找回上下文不用再翻几十页文档。这个思路其实很朴素本地编程代理这类工具每天都在迭代参数、工具、提示词写法都不算少但真正每天用的只有一小部分。把这部分提取出来做成一张可以随时扫视的信息卡省下的不只是时间还有思路被打断之后重新接续的代价。这篇文章会把 Pi Coding Agent 速查表信息卡从选题、内容分层、排版设计到维护更新的完整过程拆开讲一遍。无论你是刚上手这类本地编程代理的新手还是在长期维护自己 Agent 配置的老手都可以直接参考这套方法来沉淀自己的速查卡。1. 为什么我要给 Pi Coding Agent 做一张实体速查卡1.1 记不住参数的真相问题在信息结构不在记忆力很多人觉得用了半年 Agent 还记不住参数是自己没用心。我观察下来这跟记忆力关系不大而是 Agent 的信息体量已经超过人脑工作记忆的合理上限。配置项几十个工具命令十几个提示词模板但凡沉淀下来就是三五十条每一条还带着参数规则和上下文边界。这些信息散落在 README、历史对话、示例项目里平时用不到一旦用到就要花五分钟去翻、去试试错了代价更大。打个比方这就像你常用的工具箱工具本身不多但每个工具的使用说明、维护频率、注意事项加起来就成手册了。你不会把手册背下来你只需要在不常见故障发生时知道去哪一页找答案。速查卡干的就是这个事把手册里才有的答案压缩到一瞥范围内。我在实际使用中最典型的场景就是修改配置文件有一条参数老是记混曾经连续两次因为记错参数名导致启动失败每次排查十分钟起步。后来卡片上把这条单独用粗体列出来问题直接消失。1.2 速查表信息卡要覆盖的四种阅读场景设计这张卡片之前我先想清楚它到底在哪些时刻会被用到然后按场景倒推内容。第一种是编码中断后的上下文找回。刚才还在专注写代码被人打断回来之后忘记当前会话指定工作目录的写法卡片扫一眼就续上。第二种是新终端窗口的起步清单。机器重装环境后第一次启动 Agent 要检查哪些配置、用什么命令验证服务状态照着卡片走一遍不需要临时翻文档。第三种是异常报错时的快速定位。代理突然说某个工具被禁用或者会话上下文超限很多人第一反应是去网上搜索其实多半是配置里的老问题排错区直接给出最快修复路径。第四种是团队协作时统一操作口径。如果你的 Agent 配置要分给其他人用一张卡比一堆聊天记录截图高效太多大家对着同一份速查卡提问和回答都有共同基础。这几种场景的共同特点是时间压力大、上下文零散、操作频率低。越是这类场景越不适合去翻长文档。速查卡的信息组织方式天然适配扫一眼—想起来—操作这么短的反应链路。1.3 这张卡适合谁不适合谁先说适合的第一类是刚接触本地编程代理的开发者最容易把命令敲错、把上下文搞丢有一张卡能大幅降低初期挫败感第二类是带团队的人需要把常用操作固化下来做内部分享第三类是喜欢信息密度高、一屏可查这种沉淀方式的人哪怕不打印做成数字版也有用。不适合的也有两类完全不用 Agent 的人当然用不上还有一类是已经把所有流程写进脚本、自动化程度非常高的人Agent 只是后台服务从不手动操作那速查卡的意义确实不大。但从我自己的经验看就算自动化了你依然需要一张人工介入维护清单否则某天脚本坏了你连从哪儿下手都不知道。所以我的结论是这张卡对每个实际使用者都值得做差别只是版本不同。2. 先想清楚往里放什么四层内容分区2.1 高频指令区给肌肉记忆兜底一张速查卡最先放进去的应该是每天都在用、但偶尔会在参数上卡住的指令。我整理出的核心指令长期稳定在十条以内包括开启对话、批量执行任务、代码评审、跑测试、查看日志、停止当前会话这几类。每一条统一写成最短可用形式后面只跟一个高频参数示例。我常用的格式是/run task_description --scope模块名把任务限定在某个模块避免代理扫全仓库浪费时间。/review file_or_range评审指定文件通常配合提示词模板区里的评审标准一起用。/history file查看文件修改记录适合回看某段代码为什么变成现在这样。/stop无条件中断等待中的任务。这些指令我实操下来发现一个隐藏问题平时最常用的是前两三个后几个一个月也用不到一次可真的要用时根本想不起参数格式。所以高频区不是按我最熟排而是按正被我遗忘但很重要来排。整个分区控制在十五条以内再多就失去速查意义。2.2 提示词模板区把调试过的经验固化下来很多人以为速查卡只记命令其实最有价值的部分往往是提示词模板。我这个 Agent 支持用自然语言描述任务但不同的描述差异巨大。同样说帮我看一下这个文件有没有问题泛泛的提问拿回来的是泛泛的答案按固定模板去问输出质量立刻上一个台阶。问题在于模板不是凭空想出来的是在一次次不满意输出中打磨出来的这种经验特别值得固化。我的卡片上只保留了三组模板摘要代码评审组先给整体结论再按文件分组严重程度分四级每条附行号与修复建议。Bug 定位组先复现步骤再列出可疑模块给出三条假设最后用日志或测试逐个排除。重构组保持外部行为不变先列出覆盖性测试用例再分步修改每步跑一次测试。每条模板在卡片上只写五个以内的关键字加一个示例保证扫一眼就能想起来完整版。如果你也做这件事建议把完整模板放在文档里、摘要放在卡片上当作默认原则这样卡片不会被长文本淹没。2.3 配置与环境参数区只在出问题时才翻配置区的定位跟前面两个区不同——它不是每天用的而是在启动失败、行为异常、更新升级这三个时刻才需要。我的做法是把配置文件里的关键项列成一张小表每项只写默认值、我的当前值以及一条踩坑备注。参数常见值备注model默认模型名换模型后需重跑一遍冒烟测试context_window64k超限时先缩小检索范围再考虑加大max_steps20任务太复杂建议拆成两步tool_allowlistread, write, shell, test新工具不生效先查这里working_dir项目根目录必须写绝对路径这张表看起来很简单但它是实测之后总结出来的。我记得最早把 model 参数写错时Agent 一直报认证错误我以为是 token 过期折腾半天才发现是指向了错误的模型服务地址。这种低级错误写进卡片之后就再也不会犯。2.4 排错区把重复三次的坑写上去排错区遵循一个门槛同一个错误出现过两次以上必须上卡只出现一次先记到备选清单。我汇总下来真正常见的也就六七个挑最典型的几个说明报错现象判断方法最快的修复上下文超限日志提示 context 相关字样缩小检索范围不急着加配额工具被拒绝提示 tool not allowed检查 tool_allowlist 是否包含该工具认证过期偶发 401 错误重新登录并确认模型服务地址端口被占用启动日志显示 bind 失败换端口或先查占用进程任务执行过长卡在同一个步骤反复重试手动中断把任务拆细再跑排错区的写法有个要点不要照抄文档原话要用自己的话写清楚什么时候发生、怎么判断、最快怎么解。报错时的上下文每次都不同官方描述是通用的而速查卡要的是定位链路的快捷键。这个区域的价值增速惊人每补一条后续排障时间就缩短一截是整张卡回报率最高的部分。3. 一页纸的信息设计卡片不是文档的缩印件3.1 索引式排版关键词在前面解释跟着走速查卡最常见的失败是把文档直接缩印到一张纸上。字变小、行变密看起来塞满了知识实际上一眼扫过去什么都抓不住。文档和信息卡的阅读逻辑完全不同文档是线性的从头往后读卡片是索引式的眼睛自己找目标。所以每条内容都要遵循同样的句式关键词在最前最短示例紧随其后提醒信息放最后。我举个例子。文档里的写法是运行测试套件时请在 /test 指令后附上目标测试文件的相对路径并确保路径从项目根目录开始计算否则代理可能找不到文件。卡片上的写法是/test 相对路径注意路径从项目根算起。信息量一样但卡片写法在扫视时第一眼就能定位到指令和参数格式。同时卡片上每一条都应该能独立成立不要出现参数说明见下方这类互指内容。实在放不下就删掉或者干脆做成两张卡别用互相引用来节省空间。3.2 视觉层级几条硬规则排版上我踩过不少坑最后固定下来几条规则直接照着做基本不会出错。第一分区固定且带边框。四个区在卡上的位置永远不变黑白打印时靠边框识别不依赖底色。第二指令和参数用等宽字体跟终端里的写法保持一致减少转换误差。第三危险项加[!]标记比如[!] 必须写绝对路径[!] 换模型前先备份配置这类信息用粗体加标记不能用颜色区分因为打印出来可能变成一片灰。第四每区不超过十五条超过后不是缩字号而是做减法字小于 9 磅后在显示器边上的阅读距离根本看不清。第五底部留白一行防止裁切偏差切掉内容。这些规则看着琐碎但每一条都是实际打印和贴墙使用后才总结出来的。花花绿绿的卡片在屏幕上看很漂亮到了黑白打印机上就是灾难分区不画边框的卡片在强光下几乎分不清区块要凑近找边界。3.3 实体卡与数字版Markdown 是源打印卡是镜像做这张卡的时候我坚持一个原则内容源文件必须用 Markdown 维护实体卡只是它的打印镜像数字版也只是同一份源文件的渲染结果。选 Markdown 是因为它能进 git 做版本管理每次改动都能看到 diff改坏了还能回滚。实体卡和数字版的取舍也值得说一下。实体卡的优势是零成本唤起注意贴在显示器边框上每次扫视都是一种被动复习数字版则方便携带和搜索手机里也能看但不打开就想不起来看。我建议两套都要实体卡负责日常最高频的几十条数字版放完整版包括更全的模板和排错长文。源文件采用一个文件多区块的结构打印时用 CSS 的media print控制只输出纸张需要的区块数字版直接渲染完整文件。4. 制作流程实录从零散笔记到一张能用的卡片4.1 素材收集连续记录两周的高频动作制作速查卡最容易犯的错误是凭印象写内容写完才发现一条都没用到。我推荐的做法是连续记录两周的使用日志只做一件事每当自己不得不翻文档、翻历史聊天记录或者在终端里执行 help 命令就在一个笔记文件里记一笔记下当时想做什么、卡在哪一步。两周后统计触发次数这就是内容取舍的客观依据。我随手列一个统计形态方便你理解待上卡候选两周触发次数场景/run 加模块范围参数7任务限定模块时想不起来tool_allowlist 配置项5新装工具不生效上下文超限修复流程4长对话跑到一半报错重构提示词模板3做重构任务时临时拼提示词统计的时候注意一个反直觉现象触发次数多不一定代表值得上卡要结合查询成本判断。如果某个操作翻文档只要十秒卡片位可能留给更贵的项如果翻文档要五分钟还容易翻错哪怕只出现两次也值得上。两周的记录期我后来放宽到二十天样本量越大卡片的可信度越高。4.2 逐条实测每条内容都在真实任务里跑过素材整理完成后真正的筛选环节才开始。我会给每个候选条目做一次实测再决定是否上卡。实测分三层第一层是命令本身能不能跑通有些提示词模板还停留在旧版本测试时用的命令已经不存在了这种直接淘汰。第二层是输出结果好不好用跑通的命令如果输出太长还得加上过滤参数把输出压到能一眼看懂的程度。第三层是看它对今天的项目是否还有价值有些模板之前写得很顺手但项目风格变了现在根本不适用这类也要果断拿下。这个环节绝对不能省。我见过直接把网上的速查卡拿来打印的十有八九会踩到版本或环境差异的坑。每一张合格的速查卡都应该是自己环境的真实镜像而不是通用知识的搬运稿。4.3 排版、打印、上墙做完筛选信息内容就定了排版反而很快。我用一个 HTML 模板做打印版用 CSS 控制成三栏布局纸张设成 A6。关键样式贴一下page { size: 105mm 148mm; margin: 8mm; } .card-grid { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 3mm; font-family: 等宽字体, monospace; font-size: 9.5pt; }打印时注意几个环节等宽字体要确认生效网格间隙留够先用普通 A4 纸试打印一次检查各区块有没有溢出。试打印没问题再上 A6 纸或者直接打在 A4 上裁成合适大小也可以。我后来一直用不干胶纸打印剪裁后直接贴在显示器边框上不占桌面空间也不容易丢。4.4 第一次真实使用就发现的问题卡片贴上墙并不代表完工。我印象最深刻的是第一周就发现字还是偏小。屏幕上的 9pt 字体观感还行但贴在显示器边上要从坐姿距离扫视9pt 需要微微前倾才看得清。后来我把核心指令区单独加大到 10.5pt其他区保持 9.5pt才算找到平衡点。第二个问题更隐蔽分区在彩色屏幕上界限清晰但黑白打印后靠底色区分完全无效必须靠边框线。我第一次打印出来的卡片四个区块混在一起一眼扫过去像一团文字。重新加了边框后才彻底解决。这两个问题如果不实测光靠预览根本发现不了。所以我的建议是第一版卡片只当测试版贴上一周边用边改第二版才是正式版。5. 半年维护下来的真实心得5.1 速查卡必须跟着版本走本地编程代理这类工具迭代速度很快参数改名、工具范围调整、默认值变化都是家常便饭。我遇到过一个具体案例某个配置项在两轮更新后改了名字官方文档更新了但旧教程还留在网上。如果卡片不及时同步下次排错时就会照着旧名字填Agent 识别不了报一个完全看不懂的错。这之后我定了规矩每次代理大版本更新后第一时间把速查卡源文件打开全量 review 一遍对照改动日志逐条检查受影响内容。这个流程大概十分钟但能避免之后无数次按错误信息操作。提示词模板也会过期。随着底层模型能力提升原来为了稳定输出而设计的长模板可能变成累赘反而妨碍新能力发挥。我会在大版本更新后做一次模板演算挑几个典型任务跑一遍对比新旧模板的输出质量不行的就换掉。5.2 定期做减法没被查阅的内容就是在占地方速查卡的容量是硬约束所以维护的本质不是往里加东西而是持续删除用不到的东西。我的淘汰标准很直接连续三十天没有主动查阅过的条目要么移到扩展文档要么直接删除。刚开始执行时有点舍不得总觉得以后会用到但事实证明真正会在事故中救命的条目在事故发生前也处于偶尔能用上的状态并不会在三十天内完全沉寂。删除时我做了点技巧处理不是直接抹掉内容而是把删除的条目放进一个下卡记录区块等满三个月没回来再彻底清掉。这样既满足容量约束又保留回滚渠道。每两周固定做一次减法比一个月做一次更轻松因为每次要判断的条目数量少很多。5.3 扩展成一套卡片集核心卡、排错卡、模板卡用久了之后单张卡渐渐不够装我已经扩展成三张一套的卡片集核心卡负责每天最高频的指令和配置摘要常驻手边排错卡只在出问题时拿出来内容可以比核心卡更详细模板卡放那些较长但有效的提示词模板适合做复杂任务前对照使用。三张卡用同一个源文件的不同区块维护版本号保持一致每次改完任何一张都要同步更新时间。如果你在团队里分享还可以把整套卡片做成 A3 大小的桌面版贴在工作区墙面让所有人都能快速查阅统一的操作口径。我发现一个意外的好处速查卡让新手熟悉 Agent 的教学成本大幅下降新成员不再需要追着老同事问参数自己看卡就能解决八成问题。这也是整套卡片最有价值的地方。最后说一点我自己的体会。速查表信息卡做出来之后最大收获反而不是查起来快而是整理素材的过程中被迫把 Agent 的用法整体过了一遍发现了几个平时总在误用或理解有偏差的参数。制作卡片的过程本身就是一次完整的能力校准。如果你也养着一个编程代理不妨先记录两周使用日志再动手做一张属于自己的卡片。当你能把整个工作流浓缩到一张纸上并让它持续有效时对工具的掌控感和之前完全不同。