企业官网建设流程全解析

Pi实战 01：配置篇——把 Pi 调教成你的主力

来源：Pi 官方 Settings / Models / Providers / Themes 文档，以及 deepakness、torchtree、dalenguyen 等开发者的实战配置。

Pi 的配置文件不多，但每一个都直接决定"它有多懂你"。核心文件就这几个：

下面逐个给可复制的例子。

一、settings.json：一次配好默认行为

这是最该先配的文件。官方给出的完整示例：

{"defaultProvider":"anthropic","defaultModel":"claude-sonnet-4-20250514","defaultThinkingLevel":"medium","modelThinkingLevels":{"anthropic/claude-sonnet-4-20250514":"high"},"theme":"dark","compaction":{"enabled":true,"reserveTokens":16384,"keepRecentTokens":20000},"retry":{"enabled":true,"maxRetries":3},"enabledModels":["claude-","gpt-4o"],"warnings":{"anthropicExtraUsage":true}}

几个关键字段的实战用法：

1. 给不同模型设不同思考等级（modelThinkingLevels）
默认defaultThinkingLevel是全局的，但你可以对特定模型单独覆盖。比如日常用low省钱，只在某个强模型上开high：

"modelThinkingLevels":{"anthropic/claude-sonnet-4-20250514":"high","openai/gpt-5-codex":"medium"}

2. 控制Ctrl+P循环哪些模型（enabledModels）
格式和 CLI 的--models一致，用前缀匹配：

"enabledModels":["claude-","gpt-4o","gemini-2"]

配好后，会话里按Ctrl+P就只在这几个之间循环，不会在一堆用不到的模型里翻。

3. 上下文压缩（compaction）

• reserveTokens：给压缩后保留的"系统区"留多少 token（默认 16384）。
• keepRecentTokens：压缩时强制保留最近多少 token 的对话（默认 20000），避免把刚说的关键上下文压掉。

调大keepRecentTokens适合"最近几轮很重要"的场景；想更省 token 就调小。

4. 重试（retry）
本地模型或不稳定端点建议开重试。完整示例：

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

配完不用重启 Pi，会话里敲/reload即可生效。

二、models.json：接上你的本地模型（或任意自定义端点）

这是 Pi 区别于 Claude Code（只能 Anthropic）的关键。本地 Ollama / LM Studio / vLLM，或任何 OpenAI 兼容端点，都能塞进来。

本地 Ollama 示例（dalenguyen 实测）：

{"providers":{"ollama":{"baseUrl":"http://localhost:11434/v1","api":"openai-completions","apiKey":"ollama","models":[{"id":"qwen3-coder:30b","contextWindow":262144,"compat":{"supportsDeveloperRole":false,"supportsReasoningEffort":false}}]}}}

极简写法：本地模型其实只要id就够了。比如跑 gpt-oss 并开启推理：

{"providers":{"ollama":{"baseUrl":"http://localhost:11434/v1","api":"openai-completions","apiKey":"ollama","models":[{"id":"gpt-oss:20b","reasoning":true}]}}}

⚠️一个常见坑：apiKey对本地 Ollama 是占位符（Ollama 会忽略它），但 Pi 仍认为"需要鉴权才会在/model里显示"。所以keyless 的本地服务要保留一个 dummy 值（如"ollama"），或用/login存个 key，或选模型时传--api-key。

覆盖内置提供商 / 自定义模型参数（官方 full example）：

{"providers":{"openrouter":{"modelOverrides":{"anthropic/claude-sonnet-4":{"name":"Claude Sonnet 4 (Bedrock Route)","compat":{"openRouterRouting":{"only":["amazon-bedrock"]}}}}}}}

⚠️另一个坑（ofox 实测）：没在models.json列出的模型 id，Pi 会报警告Model not found for provider然后按自定义模型跑，但会继承默认值（128k context、16384 max output）。所以一个 1M context 的模型如果不列出来，会在远早于必要的時候就触发压缩。→大上下文模型务必显式列出contextWindow和maxTokens。

配好后，/model里就能选到你刚加的本地模型了。

三、AGENTS.md：给 Pi 装一个"项目大脑"

AGENTS.md是项目/全局指令，启动时自动加载。加载顺序：全局~/.pi/agent/→ 父目录 → 当前目录，后加载的覆盖先加载的。

TorchTree 的分工建议：

• 全局~/.pi/agent/AGENTS.md：写你日常通用的技术栈偏好、代码规范（跨项目适用）。
• 项目级AGENTS.md（仓库根目录）：写这个具体项目的约束、构建命令、目录约定。

一个项目级AGENTS.md长这样（结构参考社区通用写法）：

# Project: foo-service ## Stack - Node.js 20 + TypeScript, Fastify, Prisma + PostgreSQL ## Build & Test - Install: `npm install` - Typecheck: `npm run typecheck` - Test: `npm test` - Run dev: `npm run dev` ## Conventions - 新代码用 ESM，`import` 而非 `require` - 数据库改动必须带 migration 文件 - API 错误统一用 `ApiError` 抛出 ## Gotchas - `npm run dev` 前必须先 `npm run prisma:generate` - 测试用 `vitest`，不要碰真实数据库（用 testcontainers）

四、APPEND_SYSTEM.md：比 AGENTS.md 更高优先级的全局行为规则

这是 deepakness 强烈推荐的用法。APPEND_SYSTEM.md放在~/.pi/agent/APPEND_SYSTEM.md，内容直接追加到系统提示词末尾，因此它的指令比AGENTS.md优先级更高，对所有项目生效。

deepakness 实际放的内容（可直接抄）：

- If the default provider doesn't have vision capabilities, use pi-vision-handoff for images. - Read relevant local files first when the answer is available in the codebase. If not, research online via pi-web-access. Before making a big change based on online research findings, confirm with me first. - Explain risky file edits and destructive commands before executing. - Write simply. Avoid AI-slop language – no flowery adjectives, unnecessary adverbs, or overly formal phrasing.

翻译成中文就是四条黄金规则：

1. 没视觉能力就用pi-vision-handoff处理图片。
2. 答案在代码库里就先读本地文件；不在再联网查（pi-web-access）。基于联网结果做大改动前，先跟我确认。
3. 执行危险文件编辑/破坏性命令前，先解释清楚。
4. 写得简单点，杜绝 AI 腔（不要华丽形容词、多余副词、过度正式）。

这就是把"你的工作习惯"固化成 Agent 的默认行为。把它配好，Pi 立刻从"通用助手"变成"懂你脾气的助手"。

五、web-search.json：配联网搜索（默认 Exa，免 API key）

Pi 本身不带联网搜索，装pi-web-access后默认用 Exa（免 key）。deepakness 通过~/.pi/agent/web-search.json固定用 Exa：

{"provider":"exa","allowBrowserCookies":false,"summaryModel":"opencode-go/deepseek-v4-flash","workflow":"none","curatorTimeoutSeconds":20}

也可以换成 Perplexity / Gemini（需各自 API key）。summaryModel是用于总结抓取内容的模型——用一个便宜模型即可省钱。

六、themes：给终端换个配色

Pi 的 TUI 几乎每个颜色都能改。主题文件放~/.pi/agent/themes/，编辑当前主题会自动热重载。

mkdir-p~/.pi/agent/themesvim~/.pi/agent/themes/my-theme.json

{"$schema":"https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/theme-schema.json","name":"my-theme","vars":{"primary":"#00aaff","secondary":242},"colors":{"accent":"primary","border":"primary","borderAccent":"#00ffff","borderMuted":"secondary","success":"#00ff00","error":"#ff0000","warning":"#ffff00","muted":"secondary","dim":240,"text":"","thinkingText":"secondary","selectedBg":"#2d2d30","scrollbarThumb":"#555566","searchMatchBg":"#2d2d30"}}

配色建议（官方）：

• 从一套基础 palette（Nord / Gruvbox / Tokyo Night / Catppuccin）起步，在vars里定义，再在colors里引用，保持一致性。
• 浅色终端用更暗、更低对比的颜色。
• VS Code 里设terminal.integrated.minimumContrastRatio: 1才能看到准确颜色。
• 主题用 51 个颜色 token，社区已有 Catppuccin 四味现成主题可直接装。

七、一个"抄完即用"的完整配置清单

把上面串起来，新手可以直接照抄的最小可用组合：

1. ~/.pi/agent/settings.json—— 设好defaultModel、defaultThinkingLevel、enabledModels。
2. ~/.pi/agent/APPEND_SYSTEM.md—— 放那 4 条全局行为规则。
3. ~/.pi/agent/AGENTS.md—— 放你的通用技术栈偏好。
4. 想省成本/要隐私 →~/.pi/agent/models.json接本地 Ollama（见第二节）。
5. 想换肤 →~/.pi/agent/themes/my-theme.json。

每改完一个，会话里/reload，立刻生效。

下一篇：02 · 提示词与技能篇 —— 把重复工作固化为/xxx命令和技能。