0 前言

这篇笔记记录我现在使用的 Pi Agent 配置. 目标不是介绍所有功能, 而是在系统重装后, 能按顺序恢复到当前可用状态.

本文参考如下内容:

1 安装 Pi Agent

1.1 安装主程序

使用 pnpm 安装:

pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
mkdir -p ~/.pi/agent
chmod 700 ~/.pi/agent

1.2 settings.json

创建 ~/.pi/agent/settings.json, 内容如下:

{
  "theme": "dark",
  "defaultProvider": "lvbibir-newapi",
  "defaultModel": "gpt-5.6-sol",
  "defaultThinkingLevel": "high",
  "outputPad": 0,
  "treeFilterMode": "default",
  "tuiMode": "fullscreen"
}

1.3 SYSTEM.md

~/.pi/agent/SYSTEM.md 是当前全局提示词, 它会替换 Pi 内置的默认系统提示词. 项目自己的 AGENTS.md 仍会作为上下文继续补充规则;

1.4 skills

参考

2 配置扩展

# AGENT 全局配置

## 1. 基础设置

环境: WSL2 Ubuntu (无 GUI)
语言: 中文回复, 英文标点

## 2. 工作流程

### 预检查 (3 个问题)
1. **Real?** - 这是真实问题还是过度设计?
2. **Reuse?** - 有现成代码可以复用吗?
3. **Risk?** - 可能会破坏什么? 谁依赖它?

### 任务级别
| 级别 | 标准 | 行动 |
|-------|----------|--------|
| Simple | 1 个文件, <20 行 | 直接执行 |
| Medium | 2-5 个文件 | 简短计划 → 实现 |
| Complex | 架构变更 | 研究 → 提案 (等待) → 实现 → 验证 |

### 编码原则
- **KISS**: 简单优先
- **DRY**: 消除重复
- **Read before write**: 理解后再修改

### 红线
- 不复制粘贴重复代码
- 不破坏现有行为 (除非明确重构)
- 关键路径必须有错误处理
- 不盲目实现, 必须先理解

## 3. 开发环境

### Python
- **必需**: `uv` (不使用 pip/venv/virtualenv)
- 如不可用: 停止并询问用户

### Node.js
- 版本: `fnm` (遵循 `.nvmrc`)
- 包管理: 优先使用 `pnpm`

### Shell
- 默认: WSL2 上的 Bash
- Windows 路径: `/mnt/c/...`

## 4. 安全规范

- 不硬编码 secrets/passwords/tokens
- 不提交 `.env` 或 credentials
- 在信任边界验证输入

## 5. 版本控制

使用 git commit skill

## 6. 工具与搜索

### 搜索优先原则
- **有任何不确定的内容必须先进行搜索, 不猜测**
- 使用工具: 首选 smart-search-cli skill
- 优先级: 官方文档 > Changelog > GitHub > 社区
- 版本敏感: 先检查 lockfile/config, 然后搜索该版本

### 工具优先级
- 保持工具调用叙述简短。
- 优先选择专用工具而不是 shell 等效工具:
  - 使用 "read" 来检查文件内容, 而不是 "cat" 或 "sed -n"
  - 使用 "ffgrep" 而不是 "grep" 来搜索文件内容
  - 使用 "fffind" 按名称或概念查找相关文件, 而不是 "find"

2.1 安装扩展

pi install npm:@narumitw/pi-goal
pi install npm:@narumitw/pi-plan-mode
pi install npm:@juicesharp/rpiv-ask-user-question
pi install npm:@juicesharp/rpiv-todo
pi install npm:pi-mcp-adapter
pi install npm:@ff-labs/pi-fff
pi install npm:pi-cache-optimizer
pi install npm:pi-add-dir
pi install npm:pi-workspace-history
pi install npm:@narumitw/pi-caffeinate
pi install npm:@tmustier/pi-raw-paste
pi install npm:pi-open-tui
pi install npm:pi-provider-newapi
pi install npm:@gotgenes/pi-permission-system
pi install npm:pi-tool-display
pi install npm:pi-hosts

后续使用 pi update --extensions 更新全部扩展.

扩展	用途
`pi-goal`	提供 `/goal`, 适合需要持续推进到完成或确认阻塞的任务
`pi-plan-mode`	提供只读 `/plan` 模式, 先讨论方案再动手
`rpiv-ask-user-question`	让 Agent 用结构化选项提问, 适合需要用户决策的场景
`rpiv-todo`	提供持久化任务清单, 并在 TUI 中显示进度
`pi-mcp-adapter`	按需发现, 描述和调用 MCP 工具, 减少常驻工具定义占用
`pi-fff`	提供快速文件名搜索和内容搜索
`pi-cache-optimizer`	优化 prompt cache 命中率, 降低重复上下文成本
`pi-add-dir`	把工作区外目录加入当前 session, 自动加载其中的 `AGENTS.md`, `CLAUDE.md` 和 Skills
`pi-workspace-history`	记录工作区变更, 提供撤销和恢复能力
`pi-caffeinate`	Agent 运行时阻止系统休眠, 适合长时间任务
`pi-raw-paste`	使用 `/paste` 做一次性原样粘贴
`pi-open-tui`	自定义 TUI 顶部, 编辑器, Footer 和遥测显示
`pi-provider-newapi`	动态发现 NewAPI 网关中的模型
`pi-permission-system`	对 bash, 路径, 外部目录等操作做权限控制
`pi-tool-display`	工具输出降噪
`pi-hosts`	远程连接服务器

2.2 tool-display

mkdir -p ~/.pi/agent/extensions/pi-tool-display
vim ~/.pi/agent/extensions/pi-tool-display/config.json

写入如下内容

{
  "enabled": true,
  "registerToolOverrides": {
    "read": true,
    "grep": true,
    "find": true,
    "ls": true,
    "bash": true,
    "edit": true,
    "write": true
  },
  "customToolOverrides": {
    "ffgrep": {
      "enabled": true,
      "kind": "generic",
      "outputMode": "summary"
    },
    "fffind": {
      "enabled": true,
      "kind": "generic",
      "outputMode": "summary"
    },
    "fff-multi-grep": {
      "enabled": true,
      "kind": "generic",
      "outputMode": "summary"
    },
    "rg": {
      "enabled": true,
      "kind": "generic",
      "outputMode": "summary"
    }
  },
  "enableNativeUserMessageBox": true,
  "readOutputMode": "summary",
  "searchOutputMode": "count",
  "mcpOutputMode": "summary",
  "previewLines": 8,
  "expandedPreviewMaxLines": 4000,
  "bashOutputMode": "summary",
  "bashCollapsedLines": 10,
  "diffViewMode": "auto",
  "diffIndicatorMode": "bars",
  "diffSplitMinWidth": 120,
  "diffCollapsedLines": 24,
  "diffWordWrap": true,
  "showTruncationHints": false,
  "showRtkCompactionHints": false
}

2.3 permission-system

参考资料

mkdir -p ~/.pi/agent/extensions/pi-permission-system/
vim ~/.pi/agent/extensions/pi-permission-system/config.json

写入如下内容:

{
  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/refs/heads/main/packages/pi-permission-system/schemas/permissions.schema.json",
  "debugLog": false,
  "permissionReviewLog": false,
  "yoloMode": false,

  "permission": {
    "*": "allow",
    "grep": "deny",
    "find": "deny",
    "external_directory": {
      "*": "allow"
    },
    "path": {
      "*": "allow",
      "~/.pi/agent/settings.json": "ask",
      "~/.pi/agent/trust.json": "ask",
      "~/.pi/agent/SYSTEM.md": "ask",
      "~/.pi/agent/APPEND_SYSTEM.md": "ask",
      "~/.pi/agent/npm/package.json": "ask",
      "~/.pi/agent/npm/package-lock.json": "ask",
      "~/.pi/agent/extensions/pi-permission-system/config.json": "ask"
    },
    "bash": {
      "*": "allow",
      
      "grep *": "deny",
      "find *": "deny"

      "rm *": "ask",
      "del *": "ask",
      "erase *": "ask",
      "rd *": "ask",
      "rmdir *": "ask",
      "mv *": "ask",

      "git clean *": "ask",
      "git reset --hard *": "ask",
      "git checkout -- *": "ask",
      "git restore *": "ask",
      "git branch -D *": "ask",
      "git stash drop *": "ask",
      "git stash clear *": "ask",
      "git push *": "ask",
    }
  }
}

2.4 MCP

当前没有配置 MCP Server, ~/.pi/agent/mcp.json 只有空对象:

{
  "mcpServers": {}
}

后续优先把跨工具共用的 MCP 放到 ~/.config/mcp/mcp.json, 项目自己的 MCP 放到 .mcp.json. Pi 专用覆盖再放到 ~/.pi/agent/mcp.json 或 .pi/mcp.json.

2.5 newapi-provider

添加 Provider

启动 Pi 后执行:

/newapi-provider-add lvbibir-newapi

Base URL 输入 NewAPI 根地址, 不要带 /v1:

https://example.lvbibir.com

然后录入 API Key:

/login lvbibir-newapi

API Key 由 Pi 保存到 auth.json, 不要写进 Provider 配置, models.json, 环境变量示例或这篇笔记.

模型覆盖

当前只覆盖两个模型的上下文和最大输出长度. ~/.pi/agent/models.json 内容如下:

{
  "providers": {
    "lvbibir-newapi": {
      "modelOverrides": {
        "gpt-5.5": {
          "contextWindow": 1050000,
          "maxTokens": 128000
        },
        "gpt-5.6-sol": {
          "contextWindow": 1050000,
          "maxTokens": 128000
        }
      }
    }
  }
}

刷新动态模型目录:

pi update --models

也可以启动 Pi, 打开 /model 触发刷新. 刷新结果会写到 models-store.json, 这个文件是缓存, 不需要手动维护.

最后在 /model 中选择 lvbibir-newapi/gpt-5.6-sol. settings.json 中的默认 Provider 和默认模型只有在模型已经成功发现后才能正常工作.

2.6 排查扩展启动耗时

扩展安装多了以后可能会导致 pi 启动很慢, 可以通过如下命令排查每个扩展的启动耗时

PI_TIMING=1 PI_OFFLINE=1 pi -p >/tmp/pi.out 2>/tmp/pi.timing

perl -ne '
if (/^  (.+?) (module import|factory): (\d+)ms$/) {
  my ($path,$phase,$ms)=($1,$2,$3);
  my $pkg=$path;
  $pkg=$1 if $path =~ m#(?:^|/)node_modules/(@[^/]+/[^/]+|[^/]+)#;
  $sum{$pkg}+=$ms;
  $count{$pkg}++;
}
END {
  for my $pkg (sort { $sum{$b}<=>$sum{$a} } keys %sum) {
    printf "%6dms  %2d  %s\n", $sum{$pkg}, $count{$pkg}, $pkg
  }
}
' /tmp/pi.timing

以上.

0 前言#

1 安装 Pi Agent#

1.1 安装主程序#

1.2 settings.json#

1.3 SYSTEM.md#

1.4 skills#

2 配置扩展#

2.1 安装扩展#

2.2 tool-display#

2.3 permission-system#

2.4 MCP#

2.5 newapi-provider#

2.6 排查扩展启动耗时#