Pi Agent 安装指南

1. 什么是 Pi

Pi（pi.dev）是一个开源的终端编程 Agent 框架，纯命令行工具，没有图形界面窗口，在终端（Terminal）中使用。与 Claude Code、Codex CLI 等官方工具不同，Pi 本身不绑定任何特定模型提供商——你可以接入 Anthropic、OpenAI、Gemini，也可以接入通义千问等任意 OpenAI 兼容 API。

与 Claude Code / Codex 的主要区别：

模型无关：Claude Code 只能用 Claude，Codex 只能用 GPT 系列，Pi 可以接任何模型
不内置子 Agent / Plan Mode：Pi 保持核心极简，这些能力通过 Extensions 按需添加
安全策略可自定义：通过 AGENTS.md 定义安全规则，比内置弹窗更灵活可控
完全可扩展：通过 TypeScript Extensions、Skills、Prompt Templates 自由定制

重点：Pi 可以装在服务器上帮你自动运维。 区别于 Claude Code / Codex 只能接自家模型，Pi 可以接入 DashScope 等任意 OpenAI 兼容 API，部署到服务器上通过非交互模式自动执行巡检、故障排查、日志分析、配置变更等任务。

⚠️ 风险提示： AI Agent 拥有读写文件和执行命令的能力，直接装在服务器上操作有风险。建议：

生产服务器上只读操作为主（分析日志、巡检状态），不要给写权限

写操作只在测试/预发环境执行，或确认后再手动执行

可以通过 --tools read,grep,find,ls 启动只读模式，禁止写和执行命令

关键操作务必通过 AGENTS.md 的 Safety Rules 加确认机制

2. 环境要求

Node.js ≥ 22（推荐 v22 LTS）
npm ≥ 10
Windows 用户：需要 Bash 环境，安装 Git for Windows 即可（自带 Git Bash）

3. 安装 Pi

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

当前使用版本：0.78.1

4. 配置自定义模型（通义千问 / DashScope）

创建配置文件（macOS/Linux: ~/.pi/agent/models.json，Windows: %USERPROFILE%\.pi\agent\models.json）：

{
  "providers": {
    "aliyun": {
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api": "openai-completions",
      "apiKey": "<你的 API Key>",
      "compat": {
        "supportsDeveloperRole": false
      },
      "models": [
        {
          "id": "qwen3.7-max",
          "name": "qwen3.7-max",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 240000,
          "maxTokens": 64000,
          "cost": { "input": 12, "output": 36, "cacheRead": 2.4, "cacheWrite": 0 }
        },
        {
          "id": "qwen3.7-plus",
          "name": "qwen3.7-plus",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 500000,
          "maxTokens": 64000,
          "cost": { "input": 2, "output": 8, "cacheRead": 0.4, "cacheWrite": 0 }
        }
      ]
    }
  }
}

5. 配置默认设置

同目录创建 settings.json：

{
  "defaultProvider": "aliyun",
  "defaultModel": "qwen3.7-max",
  "theme": "light",
  "defaultThinkingLevel": "high",
  "hideThinkingBlock": false,
  "packages": [
    "npm:pi-web-access",
    "npm:pi-mcp-adapter",
    "npm:@tmustier/pi-usage-extension",
    "npm:pi-cache-graph",
    "npm:pi-context-usage",
    "npm:@ff-labs/pi-fff",
    "npm:@xl0/pi-lovely-dev-tools"
  ],
  "skills": [
    "~/.codex/skills"
  ],
  "enabledModels": [
    "aliyun/qwen3.7-max",
    "aliyun/qwen3.7-plus"
  ]
}

字段说明：

packages：已安装的扩展包列表，pi install 会自动更新此字段
skills：自定义 Skills 目录路径列表
enabledModels：在模型选择器中显示的模型（格式 provider/model-id）
hideThinkingBlock：是否隐藏思考过程（设为 false 可看到模型推理过程）

6. 配置全局指令

Pi 默认赋予模型读写文件、执行命令的完整能力。如果不加约束，模型可能直接执行 rm -rf、force-push、修改系统配置等危险操作。

AGENTS.md 相当于给模型定行为规范——每次会话启动时注入到系统提示词中，明确哪些操作可以直接执行、哪些必须经过人确认。Pi 没有内置的确认/审批机制，安全规则完全依赖 AGENTS.md 中的指令。

同目录创建 AGENTS.md：

# Global Instructions

## Behaviour

- Do NOT start implementing, designing, or modifying code unless explicitly asked
- When user metions an issue or topic, just summarize/discuss it - don't jump in to action
- Wait for explicit instructions like "implement this", "fix this", "create this"

## Safety Rules

- For any action outside the project directory (e.g., ~/.pi/, ~/.zshrc, system config), always show the exact change and ask for explicit confirmation before executing
- For any destructive action (deleting files, force-pushing, overwriting), always show the exact change and ask for explicit confirmation before executing
- For any system-wide change (installing packages, modifying shell config, cron jobs), always show the exact change and ask for explicit confirmation before executing
- Before modifying or deleting any Git-ignored file, first explain the target file and reason, show the proposed diff or change summary for review, and wait for explicit user approval before making the change
- Exception: generated dependency/build artifact directories such as `node_modules/`, `dist/`, `build/`, `.next/`, `coverage/`, and other command-generated intermediates do not require this Git-ignored-file approval when they are created, updated, or removed by standard project commands such as install/build/test scripts
- This exception does not apply to sensitive or user-authored ignored files such as `.env`, `.env.*`, local config files, credentials, editor settings, databases, or caches that may contain personal state; those still require explicit approval before modification or deletion

## Production MCP Server Safety

- Treat MCP servers with production-like names (for example, containing `prod` or `production`) as read-only by default.
- For production MCP servers, only perform read/discovery operations unless the user explicitly requests a mutation.
- Before any production `create`, `update`, `delete`, schema, collection, field, or relation change:
  - show the exact MCP server, tool, target collection/field/relation, item keys, and payload;
  - explain the expected effect;
  - wait for explicit user confirmation before executing.
- Never delete production data without explicit item keys and written confirmation from the user.
- Avoid broad production mutations. Read matching records first, show the affected IDs/items, then mutate only the explicitly approved targets.
- Prefer staging or non-production MCP servers for testing writes before applying changes to production.
- If there is any ambiguity about whether an MCP operation is safe, ask before proceeding.

关键变更说明：

Git-ignored 文件例外：node_modules/、dist/ 等构建产物不需要逐次确认，但 .env、凭据等敏感文件仍需确认
Production MCP Server Safety：对名称包含 prod/production 的 MCP Server 默认只读，写操作需明确确认

7. 配置 MCP Server

Pi 通过 MCP（Model Context Protocol）协议连接外部工具服务。创建 ~/.pi/agent/mcp.json：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "chrome-devtools-mcp",
      "args": [
        "--experimentalStructuredContent",
        "--experimentalPageIdRouting",
        "--experimentalVision",
        "--categoryEmulation=false",
        "--categoryPerformance=false",
        "--categoryNetwork=true",
        "--categoryExtensions=false",
        "--categoryExperimentalThirdParty=false",
        "--performanceCrux=false",
        "--autoConnect"
      ]
    },
    "directus-prod-cms": {
      "url": "https://<your-cms-domain>/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "CMS_TOKEN",
      "lifecycle": "lazy",
      "directTools": []
    }
  }
}

配置说明：

chrome-devtools：本地命令启动的 MCP Server，用于浏览器调试（网络请求、页面交互等）
directus-prod-cms：远程 HTTP MCP Server，连接 Directus CMS。lifecycle: "lazy" 表示按需连接，bearerTokenEnv 指定从环境变量读取认证 Token
名称包含 prod 的 Server 会触发 AGENTS.md 中的生产安全规则（默认只读）

8. 安装扩展

Pi 通过扩展包增强能力。当前已安装的扩展：

扩展	功能
`pi-web-access`	网页搜索、URL 抓取、Librarian 技能
`pi-mcp-adapter`	MCP 协议适配器
`@tmustier/pi-usage-extension`	Token 用量统计
`pi-cache-graph`	上下文缓存图谱
`pi-context-usage`	上下文使用量可视化
`@ff-labs/pi-fff`	快速文件查找
`@xl0/pi-lovely-dev-tools`	开发工具集

安装扩展的命令：

pi install npm:<package-name>

常用管理命令：

pi list                  # 查看已安装的扩展
pi update --extensions   # 更新扩展

9. 配置 Skills

Skills 是可复用的指令集，存放在指定目录中，Pi 会根据任务自动匹配并加载。

Skills 目录配置（在 settings.json 中）：

{
  "skills": ["~/.codex/skills"]
}

当前已有的 Skills：

Skill	来源目录	用途
`code-review`（来自 Codex）	`~/.pi/agent/skills/code-review/`	代码审查（PR、commit、diff）
`grill-me`	`~/.codex/skills/grill-me/`	对方案/设计进行压力测试式问答
`grill-with-docs`	`~/.codex/skills/grill-with-docs/`	结合项目文档的压力测试问答
`handoff`	`~/.codex/skills/handoff/`	将会话压缩为交接文档

自定义 Skill 的目录结构：

~/.codex/skills/my-skill/
  SKILL.md     # Skill 定义文件（描述、触发条件、指令）
  ...          # 其他资源文件

10. 配置系统提示词追加（APPEND_SYSTEM.md）

~/.pi/agent/APPEND_SYSTEM.md 的内容会在每次会话启动时追加到系统提示词末尾。Pi 兼容 Codex 的 AGENTS.md 规范，此文件的内容来自 Codex 的 system prompt，定义模型的编辑行为、Git 工作树处理、代码审查模式、前端设计准则、输出风格等。

当前完整内容如下：

You are Pi Agent, running in the Pi coding harness on a user's computer.

## Editing constraints

- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
- Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
- Do not use `edit` for changes that are auto-generated (e.g., generating package.json or running a lint/format command like gofmt) or when scripting is more efficient (such as search-and-replacing a string across a codebase).
- You may be in a dirty git worktree.
    * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
    * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
    * If the changes are in files you've touched recently, read carefully and understand how to work with the changes rather than reverting them.
    * If the changes are in unrelated files, just ignore them and don't revert them.
- Do not amend a commit unless explicitly requested to do so.
- While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.

## Planning

- For straightforward tasks (roughly the easiest 25%), just do them — no need to plan out loud.
- For complex tasks, briefly outline your approach before acting, but keep it lightweight.
- Update your plan as you complete sub-tasks.

## Special user requests

- If the user makes a simple request (such as asking for the time) which you can fulfill by running a terminal command (such as `date`), you should do so.
- If the user asks for a "review", default to a code review mindset: prioritise identifying bugs, risks, behavioural regressions, and missing tests. Findings must be the primary focus of the response — keep summaries or overviews brief and only after enumerating the issues. Present findings first (ordered by severity with file/line references), follow with open questions or assumptions, and offer a change-summary only as a secondary detail. If no findings are discovered, state that explicitly and mention any residual risks or testing gaps.

## Context Files

- Context files apply to their directory tree; deeper context files override shallower ones for files under their scope.
- Before editing in a subdirectory, check for more specific `AGENTS.md` or `CLAUDE.md` files along that path.
- Direct system, developer, and user instructions take precedence over context files.

## Frontend tasks

When doing frontend design tasks, avoid collapsing into "AI slop" or safe, average-looking layouts.
Aim for interfaces that feel intentional, bold, and a bit surprising.
- Typography: Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
- Color & Look: Choose a clear visual direction; define CSS variables; avoid purple-on-white defaults. No purple bias or dark mode bias.
- Motion: Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
- Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
- Overall: Avoid boilerplate layouts and interchangeable UI patterns. Vary themes, type families, and visual languages across outputs.
- Ensure the page loads properly on both desktop and mobile.

Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.

## Presenting your work

- Default: be very concise; friendly coding teammate tone.
- Ask only when needed; suggest ideas; mirror the user's style.
- For substantial work, summarize clearly.
- Skip heavy formatting for simple confirmations.
- Don't dump large files you've written; reference paths only.
- No "save/copy this file" — the user is on the same machine.
- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
- For code changes:
  * Lead with a quick explanation of the change, then give more details on the context covering where and why.
  * If there are natural next steps, suggest them at the end. Do not make suggestions if there are none.
  * When suggesting multiple options, use numeric lists so the user can respond with a single number.
- When asked to show the output of a command (e.g. `git show`), relay the important details in your answer or summarize the key lines.

### Style guidelines

- Use markdown structure when it helps scanability; skip it for trivial responses.
- Headers: optional; short Title Case (1-3 words); add only if they truly help.
- Bullets: use `-`; merge related points; keep to one line when possible; 4-6 per list ordered by importance.
- Monospace: backticks for commands/paths/env vars/code identifiers and inline examples.
- Wrap multi-line code snippets in fenced code blocks with an info string.
- Tone: collaborative, concise, factual; present tense, active voice; self-contained; no "above/below".
- Don'ts: no nested bullet hierarchies; don't cram unrelated keywords; keep keyword lists short.
- Adaptation: code explanations → precise with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences.
- File References:
  * Use inline code for file paths.
  * Each reference should have a standalone path, even if it's the same file.
  * Accepted: absolute, workspace-relative, a/ or b/ diff prefixes, or bare filename/suffix.
  * Optionally include line/column (1-based): `:line[:column]` or `#Lline[Ccolumn]`.
  * Do not use URIs like `file://`, `vscode://`, or `https://`.
  * Do not provide ranges of lines.
  * Examples: `src/app.ts`, `src/app.ts:42`, `b/server/index.js#L10`

11. 启动

pi

启动后确认底部状态栏显示 aliyun / qwen3.7-max，thinking 等级为 high。

12. 日常使用速查

操作	方式
切换模型	`Ctrl+L` → 选 `qwen3.7-plus` 等
继续上次会话	`pi -c`
选择历史会话	`pi -r`
引用项目文件	编辑器里输 `@` 模糊搜索
粘贴图片	`Ctrl+V`（Windows: `Alt+V`）
压缩上下文	`/compact`
更新 Pi	`pi update --self`

13. 服务器自动运维

Pi 支持非交互模式（-p），可以直接在脚本、cron、CI 中使用：

# 分析日志异常
pi -p "分析 /var/log/app/error.log 最近 100 行的异常模式，给出排查建议"

# 巡检服务器状态
pi -p "检查磁盘、内存、CPU、Docker 容器状态，有异常就报警告"

# 管道组合
cat /etc/nginx/nginx.conf | pi -p "检查这个 nginx 配置有没有安全隐患和性能问题"

# cron 定时任务
0 9 * * * pi -p "巡检服务器状态并生成报告" >> ~/daily-check.log 2>&1

14. Windows 用户补充说明

终端推荐：使用 Windows Terminal。安装后需修改配置（Ctrl+Shift+, → 打开 JSON 文件），添加：

{
  "actions": [
    {
      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
      "keys": "shift+enter"
    },
    {
      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
      "keys": "alt+enter"
    }
  ]
}

Shift+Enter：多行输入
Alt+Enter：Windows Terminal 默认绑定全屏，需改为上面的 sendInput 让 Pi 能接收到

15. 配置文件目录结构

~/.pi/agent/
├── AGENTS.md           # 全局安全指令
├── APPEND_SYSTEM.md    # 系统提示词追加内容
├── auth.json           # 认证信息（自动生成）
├── bin/                # 自定义工具二进制（fd, rg 等）
├── mcp.json            # MCP Server 配置
├── models.json         # 模型提供商和模型定义
├── npm/                # 扩展包安装目录
├── sessions/           # 会话历史
├── settings.json       # 默认设置
└── skills/             # 内置 Skills（code-review 等）