Pi Agent 配置进阶：AGENTS.md、模型切换与 Thinking Level 实战指南

在《Pi Coding Agent 实战配置：从安装到日常使用的完整指南》一文中，我们介绍了 Pi 的安装、首次配置和核心扩展包。那些内容让初学者能快速上手，但 Pi 的真正灵活性藏在它的配置文件里。

Pi 的核心只有 418 行 TypeScript，默认只给模型四个工具（read、write、edit、bash）。它的所有高级行为，包括用什么模型、用多大的上下文、以什么样的思考深度执行任务，都通过外部配置文件控制。理解这些配置文件之间的关系和优先级，是把 Pi 从"能用"推向"好用"的关键一步。

Pi 的配置文件分几层？每层管什么？

Pi 的配置体系采用分层叠加的设计。理解每一层的职责范围和优先级顺序，就不会出现"改了没生效"的情况。

全局配置放在 ~/.pi/agent/ 目录下，影响所有项目。项目配置放在项目目录的 .pi/settings.json 中，只覆盖当前项目。项目配置中的嵌套对象会与全局配置合并，而非整体替换。

除了两层 settings.json，Pi 还使用了四种专门化的配置文件，各有不同的用途：

以下逐层拆解每一份配置的最佳实践。

AGENTS.md 怎么写才有效？

AGENTS.md 是 Pi 理解项目上下文的主要入口。Pi 启动时，会从多个位置查找并拼接内容注入 system prompt：先加载 ~/.pi/agent/AGENTS.md（全局指令），然后向上遍历父目录，最后加载当前目录的 AGENTS.md。

换句话说，全局的 AGENTS.md 定义你作为开发者常用的技术栈和通用规范，项目的 AGENTS.md 定义这个特定项目的约束和流程。

全局 AGENTS.md 写什么

全局 ~/.pi/agent/AGENTS.md 适合记录你日常使用的技术栈偏好。DeepakNess 在他的博客中分享的全局 AGENTS.md 是一个很好的参考案例：

# Global Pi Instructions

- Projects commonly use Laravel (PHP/Inertia/React), Next.js
  (TypeScript/Tailwind), or Astro. Check the project-root AGENTS.md for
  stack-specific rules — if none exists, ask.

这段内容来自 DeepakNess 的 Setting Up and Using the Pi Coding Agent 一文。它没有写得过于具体，而是给出宽泛的技术栈提示，同时要求 Pi 优先参考项目级别的 AGENTS.md。

项目 AGENTS.md 怎么组织

项目级别的 AGENTS.md 需要更精确。以下是一个针对 TypeScript 项目的模板，基于 Pi 官方文档 的建议整理：

# Project Instructions

## 技术栈

- TypeScript + Node.js 22

- 使用 pnpm 管理依赖

- 测试框架：vitest

## 编码规范

- 使用 ESLint + Prettier

- 函数命名使用 camelCase

- 文件命名使用 kebab-case

- 类型定义写在 src/types/ 目录下

## 测试命令

- 运行所有测试：pnpm test

- 类型检查：pnpm typecheck

- 代码检查：pnpm lint

## 注意事项

- 不要在本地运行生产环境的数据库迁移

- 使用 src/errors/ 中已有的错误处理模式

- PR 描述使用中文，commit message 使用英文

如果你管理多个项目，建议为每种项目类型维护一份模板。每次新建项目时复制过去，修改技术栈相关字段即可。

修改后记得重载

每次修改 AGENTS.md，需要执行 /reload 或重启 Pi 才能生效。这个操作的触发频率不高，但容易忘记。建议写完一段新规则后立即测试，确认 Pi 的行为如预期变化。

APPEND_SYSTEM.md 控制什么行为？

~/.pi/agent/APPEND_SYSTEM.md 追加到 system prompt 的末尾，优先级高于 AGENTS.md。这意味着它的指令会覆盖前面的内容。

它适合定义那些跨项目通用的行为准则，尤其是关于代理如何工作、如何与用户交互的约束。参考官方的建议和社区实践，一个典型的 APPEND_SYSTEM.md 内容如下：

# 全局行为规则

- 优先读取本地文件，只在代码库中找不到答案时才联网搜索

- 执行高风险编辑或命令前先解释原因

- 写作简洁，不用 AI 腔

- 代码注释使用英文

- 提交信息使用英文，格式遵循 Conventional Commits

这些规则确保 Pi 在各种项目中保持一致的工作方式，不必在每次对话开头重新交代。

settings.json：常用选项详解

settings.json 有两层：全局（~/.pi/agent/settings.json）和项目（.pi/settings.json）。项目层的嵌套对象会与全局层合并。参考 Pi 官方 Settings 文档 的内容，以下是最值得关注的配置项：

模型与思考级别

{
  "defaultProvider": "deepseek",
  "defaultModel": "deepseek-v4-pro",
  "defaultThinkingLevel": "high",
  "enabledModels": ["deepseek-*", "claude-sonnet-4-*", "kimi-k3*"],
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768,
    "xhigh": 65536
  }
}

defaultProvider 和 defaultModel 控制 Pi 启动时默认使用的模型。defaultThinkingLevel 设置思考深度，可选项包括 off、minimal、low、medium、high、xhigh、max。

enabledModels 是一个高性能设置。它定义了 Ctrl+P 循环切换时的模型列表，支持通配符。如果不定这个值，Ctrl+P 会遍历该 provider 下所有可用模型，使用体验会大打折扣。

thinkingBudgets 可自定义每个思考级别的 token 预算。上面的数值参考了 Pi 官方文档中给出的默认值。是否调整取决于你的模型和任务：预算越高，思考越深，token 消耗也越大。

上下文压缩（Compaction）

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

Compaction 是 Pi 处理长上下文的核心机制。当会话长度接近上下文限制时，Pi 自动将旧消息摘要压缩，为后续对话腾出空间。

• reserveTokens：为 LLM 响应保留的 token 数（默认 16384）。这个值越小，压缩发生得越早。
• keepRecentTokens：保留不被摘要的近期 token 数（默认 20000）。被保留的消息保持原样，保证最近讨论的内容不会丢失。

如果你常处理长会话，可以调大 keepRecentTokens。但要注意，这会降低压缩效率，可能更早达到模型上下文窗口上限。

重试策略

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

retry 配置分两层：agent 级别的重试（Pi 自己处理）和 provider 级别的重试（由 API SDK 处理）。官方文档建议将 retry.provider.maxRetries 保持为 0，因为 provider 层的重试可能在看见 rate limit 错误前就已经消耗了配额。

baseDelayMs 控制指数退避的初始延迟：2 秒 → 4 秒 → 8 秒。对于需要长时间稳定运行的任务（例如批量数据抓取），可以适当调大这个值。

项目信任模式

Pi 在项目中首次启动时，会询问是否信任该项目的 .pi/ 目录。这个机制的目的是防止恶意项目插件自动加载。

{
  "defaultProjectTrust": "ask"
}

可选值包括 ask（每次询问，默认）、always（自动信任）、never（从不信任）。在 CI 或自动化场景中，可以用 -a / --approve 参数跳过询问。

models.json 添加自定义模型

如果你的模型不在 Pi 内置的 20 多个 Provider 中，可以通过 ~/.pi/agent/models.json 添加。这个文件支持 Ollama、LM Studio、vLLM、OpenRouter、Cloudflare AI Gateway，以及任何 OpenAI 兼容 API 端点。

参考 Pi 官方 Models 文档 的完整配置说明，以下是最常见的三种场景：

场景一：Ollama 本地模型

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        { "id": "llama3.1:8b", "name": "Llama 3.1 8B (Local)" },
        { "id": "qwen2.5-coder:7b", "name": "Qwen 2.5 Coder 7B (Local)" }
      ]
    }
  }
}

apiKey 写 "ollama" 只是一个占位符。Ollama 并不验证 API Key，但 Pi 需要 auth 才会在 /model 中显示模型。compat 中的两个开关针对 Ollama 的特点：它不支持 developer role 和 reasoning_effort 参数。

以 name 字段给出人类可读的标签。Pi 在模型选择器中和 --model 模式匹配时都会用到这个值。

场景二：OpenRouter 路由配置

OpenRouter 允许你在多个 API 提供商之间设置路由偏好。以下配置参考了 Pi 官方文档中的 OpenRouter 示例：

{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "$OPENROUTER_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "openrouter/anthropic/claude-sonnet-4",
          "name": "OpenRouter Claude Sonnet 4",
          "compat": {
            "openRouterRouting": {
              "allow_fallbacks": true,
              "order": ["anthropic", "amazon-bedrock", "google-vertex"],
              "data_collection": "deny"
            }
          }
        }
      ]
    }
  }
}

openRouterRouting 对象会被原样传递给 OpenRouter API 的 provider 字段。order 指定提供商优先级，data_collection: "deny" 拒绝数据用于训练。

场景三：代理中转 Anthropic API

如果你通过第三方代理使用 Anthropic Messages API，可以这样配置：

{
  "providers": {
    "custom-proxy": {
      "baseUrl": "https://proxy.example.com/v1",
      "api": "anthropic-messages",
      "apiKey": "$MY_API_KEY",
      "headers": {
        "x-portkey-api-key": "$PORTKEY_API_KEY"
      },
      "models": [
        {
          "id": "claude-sonnet-4-20250514",
          "name": "Claude Sonnet 4 (Via Proxy)",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 200000
        }
      ]
    }
  }
}

在 models.json 中，apiKey 和 headers 支持三种值解析方式：直接字面量、$ENV_VAR 环境变量插值、!command 命令执行。Bitdoze 在 Pi Coding Agent Setup Guide 中评价：Pi 支持 Ollama、LM Studio、vLLM、任何 OpenAI 兼容端点。这个扩展能力是它相较同类工具的重要优势。

auth.json 管理 API 凭据

~/.pi/agent/auth.json 存储所有 Provider 的 API Key 和 OAuth Token。它的权限被设置为 0600，只允许当前用户读写。

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

auth.json 支持三种 key 解析方式：

• 字面量：直接用 API Key 字符串
• 环境变量插值："$MY_KEY" 或 "${KEY_PREFIX}_${KEY_SUFFIX}"
• Shell 命令："!security find-generic-password -ws 'anthropic'"

官方文档指出，auth.json 的优先级高于环境变量。这意味着如果你同时设置了 DEEPSEEK_API_KEY 环境变量和 auth.json 中的 deepseek 条目，后者会覆盖前者。

一个实用技巧是使用 shell 命令从系统密钥链中读取凭据，避免将 API Key 明文写入任何文件：

{
  "anthropic": {
    "type": "api_key",
    "key": "!security find-generic-password -ws 'anthropic'"
  }
}

模型切换策略：什么时候用什么模型

Pi 的一个核心优势是模型无关性。你可以为不同的任务选择不同的模型，切换在瞬间完成。

切换方式

快捷键部分参考了 Pi Agent 中文指南 和 DeepakNess 的设置文章。

推荐的分层策略

多位社区用户的经验指向同一个模式：分层使用模型，按任务复杂度匹配对应能力。以下整理自 DeepakNess 和 Bitdoze 的文章：

DeepakNess 在他的文章中提供了一个具体的数据点：用 DeepSeek V4 Flash 抓取 28.5 万个 URL，耗时约 1.5 小时，总费用 1 美元。这体现了低思考级别 + 低成本模型在批量任务上的性价比。

enabledModels 通配符

为了让 Ctrl+P 切换更高效，建议在 settings.json 中设置 enabledModels 列表：

{
  "enabledModels": ["deepseek-*", "claude-sonnet-4-*", "kimi-k3*"]
}

通配符匹配所有符合条件的模型。如果你只需特定的两三个模型，也可以写成精确 ID：

{
  "enabledModels": ["deepseek-v4-pro", "deepseek-v4-flash", "claude-sonnet-4-20250514"]
}

Thinking Level 如何影响输出质量

Pi 的 thinking level 是一个分层参数，控制模型在回答前的推理深度。参考 pi.dev 官方 Settings 文档和 models.md 中的 thinkingLevelMap 说明，不同级别对应不同的行为特征：

个级别之间的差异不是线性的。从 low 到 medium，输出质量提升最明显；从 high 到 xhigh，边际收益递减。实际使用中，80% 的日常任务在 medium 级别就能得到满意结果。

对于支持 thinkingLevelMap 的模型，你可以在 models.json 中精细控制每个级别映射到 provider 端的具体参数。例如某个模型可能只需要 high 和 max 两级，中间级别可以跳过：

{
  "thinkingLevelMap": {
    "off": "disabled",
    "high": { "budget_tokens": 16000 },
    "max": { "budget_tokens": 32000 }
  }
}

这个机制来自 Pi Models 文档中的 thinkingLevelMap 说明。当模型不支持某些级别时，Pi 会自动跳到相邻的支持级别。

上下文管理：Compaction、会话树与手动控制

长会话是编码代理的常态。Pi 提供了三层上下文管理机制。

自动压缩（Compaction）

Compaction 在后台运行。当上下文长度接近模型窗口上限时，Pi 自动对旧消息进行摘要。compaction.reserveTokens 控制压缩触发时机：当剩余 token 少于这个值时触发。compaction.keepRecentTokens 确保最近的消息不被摘要。

如果希望更精细地控制，可以手动触发 /compact，Pi 会立即压缩当前会话。

会话树管理

/tree 命令显示会话历史树形结构。每个分支代表一次对话路线。Pi 支持：

• /resume：恢复之前的会话继续工作
• /new：新建会话
• /fork：从当前会话分支，开始一条新的对话线

这个设计让用户可以在不丢失上下文的情况下尝试不同的解决方案路径。

一套完整的配置模板

结合以上所有内容，以下是一套可以投入日常使用的完整配置。

全局 settings.json

{
  "defaultProvider": "deepseek",
  "defaultModel": "deepseek-v4-pro",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000
  },
  "enabledModels": ["deepseek-*", "claude-sonnet-4-*", "kimi-k3*"],
  "warnings": {
    "anthropicExtraUsage": true
  }
}

全局 APPEND_SYSTEM.md

# 全局行为规则

- 优先读取本地文件，只在代码库中找不到答案时才联网搜索

- 执行高风险编辑或命令前先解释原因

- 写作简洁，避免冗长

- 代码注释使用英文

- 提交信息使用英文，格式遵循 Conventional Commits

项目 .pi/settings.json（覆盖全局压缩策略）

{
  "compaction": {
    "reserveTokens": 8192
  }
}

这个覆盖让需要频繁压缩的短会话项目更早触发压缩，避免浪费上下文窗口。

总结

Pi 的配置文件体系围绕一个核心原则：层层叠加，精确控制。全局配置定义通用行为，项目配置覆盖特定需求，AGENTS.md 传递项目上下文，APPEND_SYSTEM.md 约束代理行为模式。

当你理解了每一层配置的职责和优先级，Pi 的"最小核心 + 外部配置"设计哲学就不再是"功能少"的缺点，而变成"你控制一切"的优势。每天面对不同任务时，只需通过 Ctrl+P 切换模型、Shift+Tab 调整思考深度，就能在不同工作模式之间快速切换。

如果你的配置已经覆盖了本文提到的主要文件，下一步可以关注扩展系统：通过 pi install 添加 pi-web-access（网页搜索）、pi-codex-goal（任务追踪）、pi-vision-proxy（视觉代理）等包，逐步搭建完全适合自己工作流的 Pi 环境。

参考来源：

• Pi 官方文档
• Pi 官方 Settings 文档
• Pi 官方 Providers 文档
• Pi 官方 Models 文档
• DeepakNess: Setting Up and Using the Pi Coding Agent
• Bitdoze: Pi Coding Agent Setup Guide
• Pi Agent 中文指南