安装与个人配置迁移

MorseWayne2026/5/25...大约 9 分钟

安装与个人配置迁移：复刻我的 Pi 工作台

这一篇把我的个人配置迁移指南整合进专题，目标是在新机器上快速复刻一套可用的 Pi Coding Agent 环境。

安全提醒：Pi 扩展拥有较高系统权限。只安装可信来源的扩展；不要把 API Key、登录凭据、浏览器授权状态写入公开文档或仓库。

1. 前置条件

已安装并能正常运行 pi
Node.js 建议 >= 22.20.0（Pi 源码当前要求 Node >= 22.19.0）
已配置至少一个模型 Provider

当前机器基线如下（2026-05-29 校准）：

Pi CLI：@earendil-works/pi-coding-agent@0.77.0
安装位置：~/.nvm/versions/node/v24.15.0/bin/pi
全局配置目录：~/.pi/agent

当前模型偏好：

{
  "defaultProvider": "openai-codex",
  "defaultModel": "gpt-5.5",
  "defaultThinkingLevel": "high"
}

如果另一台机器没有这些模型，启动 Pi 后用 /model 重新选择可用模型即可。

2. 安装 Pi

官方推荐 npm 安装：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Linux / macOS 也可以使用安装脚本：

curl -fsSL https://pi.dev/install.sh | sh

启动：

cd /path/to/project
pi

认证方式有两种：

订阅账号：进入 Pi 后执行 /login，支持 Claude Pro/Max、ChatGPT Plus/Pro（Codex）、GitHub Copilot 等；
API Key：设置环境变量，例如 ANTHROPIC_API_KEY，或在 /login 中写入 ~/.pi/agent/auth.json。

3. 安装推荐扩展包

在新机器上执行：

pi install npm:pi-subagents
pi install npm:@gotgenes/pi-permission-system
pi install npm:@narumitw/pi-retry
pi install npm:pi-extmgr
pi install npm:pi-mcp-adapter
pi install npm:@juicesharp/rpiv-todo
pi install npm:@juicesharp/rpiv-ask-user-question
pi install npm:context-mode
pi install npm:pi-simplify
pi install npm:@samfp/pi-memory
pi install npm:pi-neat-ui@0.3.4
pi install npm:@juicesharp/rpiv-web-tools
pi install npm:pi-agent-flow
pi install npm:pi-markdown-preview

安装后在 Pi 内执行：

/reload

或者直接重启 Pi。

检查已安装包：

pi list

这些包分别解决：

包	作用
`pi-subagents`	子代理编排：scout、planner、worker、reviewer 等
`@gotgenes/pi-permission-system`	权限策略：路径、命令、外部目录访问控制
`@narumitw/pi-retry`	Provider 空错误、流卡住时自动重试
`pi-extmgr`	交互式扩展管理器
`pi-mcp-adapter`	MCP server 集成与按需工具访问
`@juicesharp/rpiv-todo`	任务清单（todo）管理，支持 `/todos`、依赖关系追踪
`@juicesharp/rpiv-ask-user-question`	缺少上下文时发起结构化澄清问题
`context-mode`	降低上下文占用，并提供沙箱执行与 `ctx_*` 工具
`pi-simplify`	最近改动后的代码可读性与一致性审查 (`/simplify`)
`@samfp/pi-memory`	会话级持久记忆，支持偏好/纠正历史查询
`pi-neat-ui`	更简洁的 TUI 呈现（本文固定为 `0.3.4`）
`@juicesharp/rpiv-web-tools`	Web 搜索与网页读取工具
`pi-agent-flow`	`trace` / `flow` 等轻量任务流工具
`pi-markdown-preview`	在 Pi 内预览 Markdown 内容

4. settings.json packages 片段

如果想直接写入 ~/.pi/agent/settings.json，至少需要包含：

{
  "packages": [
    "npm:pi-subagents",
    "npm:@gotgenes/pi-permission-system",
    "npm:@narumitw/pi-retry",
    "npm:pi-extmgr",
    "npm:pi-mcp-adapter",
    "npm:@juicesharp/rpiv-todo",
    "npm:@juicesharp/rpiv-ask-user-question",
    "npm:context-mode",
    "npm:pi-simplify",
    "npm:@samfp/pi-memory",
    "npm:pi-neat-ui@0.3.4",
    "npm:@juicesharp/rpiv-web-tools",
    "npm:pi-agent-flow",
    "npm:pi-markdown-preview"
  ]
}

更推荐使用 pi install ... 命令，避免覆盖新机器已有设置。

5. 全局 AGENTS.md：固化执行偏好

settings.json 适合迁移模型、扩展包和 UI 选项；真正想让 Pi 在另一台机器上“按同一种方式做事”，应该把长期工作流偏好写进全局上下文文件：

~/.pi/agent/AGENTS.md

Pi 启动时会加载全局 AGENTS.md，再加载当前项目及父目录中的 AGENTS.md / CLAUDE.md。因此全局文件适合写个人默认偏好，项目文件适合写团队约定或仓库专属规则。

我当前建议写入的核心偏好是：默认精简执行，只有高风险任务才启用完整安全流程。

# Global Pi Agent Instructions

## Execution preference: lean by default

Default to lean execution unless the user explicitly asks for a full safety/review workflow or the task is clearly high-risk.

- Classify work before execution:
  - Level 0: answer, read-only inspection, or simple command; no todo, ledger, subagent, or broad validation.
  - Level 1: small, clearly scoped edit; use minimal tracking and targeted validation only.
  - Level 2: standard coding/documentation task; use todo plus focused validation, and update persistent project ledgers only when required.
  - Level 3: risky, multi-file architecture/refactor/release work; use the full workflow, review, broad validation, and index refresh where required.
- Avoid subagent fanout for small or clearly scoped tasks; delegate only when it materially improves correctness, parallelism, or risk management.
- Batch CodeGraph/GitNexus/context gathering when possible instead of repeated exploratory round trips.
- During iteration, prefer targeted tests/checks. Reserve full test suites, clippy/lint-all, reviewer passes, and index refreshes for high-risk changes, release prep, or pre-commit checkpoints.
- Keep project ledgers concise: record durable recovery state and validation outcomes, not process logs.

如果还安装了 pi-subagents，可以在同一个文件后面保留子代理规则，但要明确它是 Level 3 或收益明显时才使用，而不是所有任务默认 fanout。

迁移到新机器时，把这个文件放入 dotfiles 管理，例如：

mkdir -p ~/.pi/agent
ln -sf ~/dotfiles/pi/AGENTS.md ~/.pi/agent/AGENTS.md

也可以只复制一次：

install -D ~/dotfiles/pi/AGENTS.md ~/.pi/agent/AGENTS.md

这种方式比只依赖持久记忆更可重复：持久记忆是某台机器上的运行状态，而 AGENTS.md 是可以审查、版本化和同步的配置。

6. 权限系统配置

创建配置目录：

mkdir -p ~/.pi/agent/extensions/pi-permission-system

写入默认权限配置：

cat > ~/.pi/agent/extensions/pi-permission-system/config.json <<'JSON'
{
  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
  "debugLog": false,
  "permissionReviewLog": true,
  "yoloMode": false,
  "permission": {
    "*": "allow",
    "path": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow",
      "~/.ssh/*": "deny"
    },
    "bash": {
      "rm -rf *": "deny",
      "sudo *": "ask",
      "chmod *": "ask",
      "chown *": "ask",
      "kill *": "ask",
      "git *": "allow",
      "npm *": "ask",
      "pnpm *": "ask",
      "yarn *": "ask",
      "bun *": "ask"
    },
    "external_directory": "ask"
  }
}
JSON

策略含义：

默认允许普通工具操作；
禁止读取或修改 .env、.env.*、~/.ssh/*；
禁止 rm -rf *；
对 sudo、chmod、chown、kill、包管理器命令进行确认；
访问当前项目目录外部路径时询问确认。

验证：

/permission-system show
/permission-system path

修改配置后记得：

/reload

7. 可选：Web 搜索与网页读取（@juicesharp/rpiv-web-tools）

当前机器使用 @juicesharp/rpiv-web-tools，提供通用的 Web 搜索与网页读取工具。安装后可以直接用自然语言调用，也可以在需要时指定工具名。

自然语言用法示例：

帮我用 web_search 搜索 React 19 的最新官方文档，总结要点并给出处

用 web_fetch 读取这个链接并总结：https://example.com/article

如果你的机器更偏好本地 Ollama，也可以改装 @ollama/pi-web-search；但本文配置以当前本机实际安装包为准。

8. 可选：MCP 与外部工具（pi-mcp-adapter）

pi-mcp-adapter 让 Pi 以较低上下文成本接入 MCP server。

常用命令：

/mcp
/mcp setup

默认通过单入口 mcp tool 与服务器交互，开启 directTools 后可直接暴露部分 MCP 工具。

当前机器的 ~/.pi/agent/mcp.json 结构如下（已移除凭据）：

{
  "imports": ["claude-code"],
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve", "--mcp"],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "directTools": true
    },
    "gitnexus": {
      "command": "/home/quzhihao/.nvm/versions/node/v24.15.0/bin/gitnexus",
      "args": ["mcp"],
      "directTools": true
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "<redacted>"
      },
      "directTools": true
    }
  }
}

迁移时只复制 server 结构，不要复制 Authorization 等凭据；新机器重新完成 GitHub / Copilot 登录后再写入本地私有配置。

9. 子代理 pi-subagents 用法

无需手动调用工具，可以直接自然语言让 Pi 使用子代理：

用 scout 先帮我理解这个代码库

让 planner 给我制定实现计划

让 worker 根据计划实现

让 reviewer 审查刚才的改动

并行运行三个 reviewer：一个看正确性，一个看测试，一个看复杂度

常用命令：

/subagents-doctor
/run reviewer "审查当前 diff"
/parallel reviewer "检查正确性" -> reviewer "检查测试覆盖" -> reviewer "检查复杂度"

当前机器还在 ~/.pi/agent/extensions/subagent/config.json 中限制并发，避免子代理过度占用资源：

{
  "parallel": {
    "maxTasks": 12,
    "concurrency": 4
  },
  "maxSubagentDepth": 2,
  "asyncByDefault": true
}

对于 Level 3 或收益明显的复杂任务，可以使用完整子代理流程：

scout/context-builder -> planner -> worker -> reviewer

小任务仍建议按全局 AGENTS.md 的 lean-by-default 规则直接处理，避免为了流程完整而牺牲吞吐。

10. 插件管理 pi-extmgr

打开插件管理器：

/extensions

常用命令：

/extensions list
/extensions search web
/extensions update
/extensions install npm:包名
/extensions remove npm:包名
/extensions history

11. 自动重试 pi-retry

@narumitw/pi-retry 安装后自动生效，用于处理模型 Provider 的空错误或流卡住问题。

可选环境变量：

PI_RETRY_STALL_TIMEOUT_MS=120000 pi

禁用卡住检测：

PI_RETRY_STALL_TIMEOUT_MS=0 pi

12. UI 与 Markdown 预览

当前机器没有继续安装 @narumitw/pi-statusline，而是保留 Pi 默认状态栏，并叠加两个轻量 UI 包：

包	作用
`pi-neat-ui@0.3.4`	优化默认 TUI 呈现，保持界面更简洁
`pi-markdown-preview`	在 Pi 内预览 Markdown，适合写博客、文档时快速查看渲染效果

如果你更需要增强状态栏，也可以额外安装：

pi install npm:@narumitw/pi-statusline

13. 模型与 subagents 偏好

如果新机器模型名称一致，可以参考下面配置；否则建议通过 /model 重新选择。

{
  "defaultProvider": "openai-codex",
  "defaultModel": "gpt-5.5",
  "defaultThinkingLevel": "high",
  "hideThinkingBlock": false,
  "retry": {
    "enabled": true
  },
  "autocompleteMaxVisible": 5,
  "terminal": {
    "showTerminalProgress": true
  },
  "followUpMode": "one-at-a-time",
  "transport": "auto",
  "enableInstallTelemetry": false,
  "treeFilterMode": "default",
  "theme": "dark",
  "subagents": {
    "agentOverrides": {
      "scout": {
        "model": "openai-codex/gpt-5.3-codex-spark",
        "thinking": "medium",
        "fallbackModels": ["openai-codex/gpt-5.4-mini"]
      },
      "context-builder": {
        "model": "openai-codex/gpt-5.4-mini",
        "thinking": "high",
        "fallbackModels": ["openai-codex/gpt-5.3-codex-spark"]
      },
      "planner": {
        "model": "openai-codex/gpt-5.5",
        "thinking": "xhigh",
        "fallbackModels": ["openai-codex/gpt-5.4", "openai-codex/gpt-5.3-codex"]
      },
      "worker": {
        "model": "openai-codex/gpt-5.5",
        "thinking": "high",
        "fallbackModels": ["openai-codex/gpt-5.4", "openai-codex/gpt-5.3-codex"]
      },
      "reviewer": {
        "model": "openai-codex/gpt-5.5",
        "thinking": "high",
        "fallbackModels": ["openai-codex/gpt-5.4", "openai-codex/gpt-5.3-codex"]
      },
      "oracle": {
        "model": "openai-codex/gpt-5.5",
        "thinking": "xhigh",
        "fallbackModels": ["openai-codex/gpt-5.4"]
      },
      "researcher": {
        "model": "openai-codex/gpt-5.3-codex-spark",
        "thinking": "high",
        "fallbackModels": ["openai-codex/gpt-5.4-mini"]
      }
    }
  }
}

14. 验证清单

新机器完成后，依次检查：

pi list
test -f ~/.pi/agent/AGENTS.md && sed -n '1,80p' ~/.pi/agent/AGENTS.md

Pi 内执行：

/reload
/permission-system show
/extensions list
/subagents-doctor

再测试自然语言能力：

帮我用 web_search 搜索 Pi coding agent extensions 的资料，并总结

用 reviewer 检查当前项目是否有明显问题

15. 日常维护

更新扩展：

pi update --extensions

更新 Pi 本体：

pi update --self

全部更新：

pi update

迁移时最容易踩的坑

复制 settings.json 覆盖了新机器已有配置：优先用 pi install。
模型不可用：换机器后先跑 /model，不要硬套旧模型 ID。
扩展权限过大：第三方 Pi Package 等同于本地代码执行，要审查来源。
忘记 /reload：新增扩展、技能、权限文件后先 reload。
把密钥写进文档：只迁移配置结构，不迁移凭据。

下一篇：日常工作流