第十六章 新手常见问题与学习路线
16.1 启动、鉴权与模型先逐项确认
排错最有效的方式，是先确定失败发生在哪一层。如果终端根本找不到 pi，先检查安装方式与命令搜索路径；如果运行后提示 JavaScript 语法或运行时不支持，先检查 node --version。当前工程要求 Node.js 22.19.0 或更新版本。源码版还需要已准备的依赖和源码解析入口，不应把缺少模块直接解释为模型服务故障。
程序能启动却不能回答时，再区分鉴权与模型选择。模型负责生成内容，provider 是接入该模型的服务或账号。同一个模型名称可能由多个 provider 提供；拥有其中一个账号的密钥，不代表其他入口也有权限。先在交互界面使用 /login，再通过 /model 选择这个账号可用的模型，通常比同时修改多个 JSON 文件更容易定位。
命令行有 pi auth check --provider openai --json 这样的状态检查方式。这里的 provider 只是文档中的具体示例，应替换为自己实际使用的服务。检查返回的状态与错误比反复复制密钥更有用；不要为了排错把打印密钥的命令输出粘贴到聊天或公开问题里。
API 密钥、浏览器登录和云平台环境凭据是不同来源。/logout 移除保存的凭据，不会自动清除进程环境变量，也不会撤销服务端令牌。远程无界面机器的 OAuth 回调可能无法到达本地进程，当前文档允许按提示粘贴最终跳转地址或授权码。遇到这类问题，应先阅读对应 provider 的配置说明。
16.2 文件与工具问题先看工作目录
“读不到我明明看到的文件”常常与模型无关。工作目录决定相对路径从哪里计算，也影响项目配置、资源发现和会话分组。例如，你在仓库上一级启动 Pi，输入 @src/index.ts，它寻找的是上一级目录下的文件。先确认界面显示的当前目录，再给出明确路径，比要求模型“再试一次”更有效。
工具是代理执行具体操作的接口。默认启用 read、bash、edit 和 write，搜索与列目录等工具也有实现，但是否启用取决于配置。--tools 可以改变提供给模型的工具列表。对初学者来说，先理解某项工具有没有启用，再研究扩展工具与 MCP 的额外规则，不必一次掌握所有匹配语法。
如果 shell 命令失败，应看退出码、工作目录和输出；如果编辑失败，应查看目标文件是否变化、原文本是否精确匹配；如果输出被截断，就缩小查询或分段读取。工具错误是执行阶段的证据，不能因为模型回答流畅就忽略它。让代理汇报实际完成、失败与未验证事项，也有助于区分计划和结果。
Pi 工具使用启动进程的操作系统权限，普通配置不会自动变成文件系统沙箱。练习可以在独立目录或可丢弃项目中进行，重要文件用版本控制保留修改前状态。这个措施解决的是操作失误的可恢复性，而不是要求每一项小练习都先搭建复杂基础设施。
资源没有加载时，先区分用户目录和项目目录。用户资源通常在 ~/.pi/agent/，项目资源通常在当前目录的 .pi/。项目设置和可执行资源受项目信任控制；上下文指令文件有单独的发现规则。手工改完设置、指令或资源后，可按当前文档使用 /reload，同时留意启动或重载时报告的路径与错误。
开发者还应注意资源定位。源码、npm 安装包与独立二进制的主题、图片、HTML 模板位置不相同。packages/coding-agent/src/config.ts 提供统一路径辅助函数。新增功能时应使用这些函数，不能假定工作目录就是包目录，也不能在其他模块随意照搬某个源码相对路径。
16.3 历史还在，为什么模型像是忘了
会话记录是保存下来的完整历史；上下文是这一次真正发给模型的材料。二者并不相等。Pi 会话是树，当前分支决定采用哪条历史路径；系统提示、指令文件、工具定义和技能描述也会占用上下文。切换分支后，另一条分支里的全部细节不会自动进入当前请求。
token 是模型处理文本的计量单位，不等于汉字数或字节数。上下文接近模型上限时，Pi 通常压缩较早历史，保留摘要和近期消息。原始会话条目仍在文件里，但摘要可能没有保留你在意的某个细节。可用 /compact 附加保留重点，也可以把关键约束写入明确指令，而不是只依靠很早的一句话。
如果压缩失败，应先修复 provider 或请求限制，再尝试。关闭自动压缩不会扩大模型本身的上下文容量。需要查历史时，/session 可帮助确认当前会话文件、消息和消耗；/tree 用于查看或切换分支。不要因为模型没复述某句话，就马上认定磁盘历史已经被删除。
默认情况下，pi --continue 继续当前工作目录最近的会话，pi --resume 打开选择器。默认存储位于 ~/.pi/agent/sessions/，还可以配置其他目录；使用过 --no-session 的临时运行无法在退出后恢复。换工作目录或换会话目录，也会影响查找结果。恢复历史之后，仍应核对当前文件和正在运行的外部程序状态。
16.4 用七天建立可验证的经验
下面的路线不要求每天安装一个新工具。每次只增加一种能力，并把观察写成两三句话。涉及真实模型的练习由读者自行选择账号、模型和预算，可能产生费用；本书没有替读者运行这些步骤。
第一天，确认安装版本和 pi --help，在练习目录启动，观察当前目录、模型和会话位置。第二天，让 Pi 解释一个短文本文件，核对它读取的路径以及答案是否有出处。第三天，给出一个小编辑任务，再用文件差异检查改了什么，区分请求、工具结果和最终回答。
第四天，命名一次会话，退出后继续，再比较 /tree 与新会话的区别。第五天，为练习目录写一条简短指令，重载后验证是否生效；不要同时安装大量扩展。第六天，阅读一个 faux provider 测试，写出它模拟的输入、预设回答和验证行为，无需连接真实模型。
第七天，选择自己真正需要的一条进阶路线：只想重复提问就研究模板；需要任务说明和资料就研究技能；需要工具或事件处理就研究扩展；要做应用才继续读 SDK、Durable、Chord 与远程环境。最终产物可以是一页“我的 Pi 工作流程”，记录入口、配置位置、检查方式及仍不确定的边界。
16.5 小结与练习
本章小结：先定位启动、鉴权、目录、工具、上下文和存储中的哪一层出了问题，再改动最相关的一项。书中的命令以固定源码为依据，安装版本和扩展可能改变接口；执行前用最新 --help 与随包文档核对。
练习一：换目录后 --continue 没找到昨天的会话，先检查什么？参考答案：检查工作目录与会话存储配置，再使用选择器定位旧会话，不要立即认为数据丢失。
练习二：增加上下文摘要长度，能解决密钥无效吗？参考答案：不能。摘要影响发送内容，密钥属于鉴权层，两者应分别处理。
练习三：模板、技能和扩展如何选？参考答案：先明确缺的是重复文本、按需说明，还是可执行能力，再选满足需求的最简单机制。