π pi 使用指南:极小内核,一切皆扩展

# 最短上手:装好、进项目、开聊
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
cd /path/to/project && pi

# npm(推荐;--ignore-scripts 跳过依赖的生命周期脚本)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 或者一键脚本
curl -fsSL https://pi.dev/install.sh | sh

# 验证
pi --version   # → 0.85.1

npm uninstall -g @earendil-works/pi-coding-agent

// 全局:~/.pi/agent/settings.json
{ "compaction": { "enabled": true, "reserveTokens": 16384 } }

// 项目:.pi/settings.json —— 只覆盖一个字段
{ "compaction": { "reserveTokens": 8192 } }

// 生效结果:enabled=true(承自全局) + reserveTokens=8192(项目)

// ~/.pi/agent/settings.json
{
  "defaultModel": "deepseek-flash",
  "defaultProvider": "senv-deepseek",
  "packages": [ "npm:pi-mcp-adapter" ],
  "lastChangelogVersion": "0.85.1",
  "theme": "dark"
}

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  // ① 事件:拦下 rm -rf,先问人
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

  // ② 自定义工具:LLM 可直接调用
  pi.registerTool({
    name: "greet",
    description: "Greet someone by name",
    parameters: Type.Object({ name: Type.String({ description: "Name to greet" }) }),
    async execute(toolCallId, params) {
      return { content: [{ type: "text", text: `Hello, ${params.name}!` }], details: {} };
    },
  });

  // ③ 斜杠命令:/hello
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => { ctx.ui.notify(`Hello ${args || "world"}!`, "info"); },
  });
}

# 临时加载试跑(不落任何配置)
pi -e ./my-extension.ts

// package.json
{
  "name": "my-package",
  "keywords": ["pi-package"],   // ← 打上这个标签才能进官方画廊
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}
// 没有 pi 键时,约定目录 extensions/ skills/ prompts/ themes/ 自动发现

pi install npm:@foo/bar@1.0.0      # 装(写进全局 settings)
pi install -l git:github.com/u/r   # -l = 写进项目 .pi/settings.json
pi remove npm:@foo/bar             # 卸(uninstall 同义)
pi list                            # 看 settings 里已登记的包
pi config                          # TUI 逐项开关包里的资源,Tab 切全局/项目
pi -e npm:@foo/bar                 # 试用:临时目录,只在本次运行存活

{
  "packages": [
    "npm:simple-pkg",                          // 字符串形式:全量加载
    {
      "source": "npm:my-package",
      "skills": ["brave-search", "transcribe"], // 只要这两个 skill
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"] // glob + 排除
    }
  ]
}

// ~/.pi/agent/mcp.json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"]
    },
    "web-reader": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

# 画廊卡片上的安装命令,复制即用
pi install npm:pi-web-access

# 按关键字搜(与画廊同一收录条件)
npm search pi-package

# 装前验明正身:关键字、README、最近发布
npm view pi-mcp-adapter keywords description
npm view pi-mcp-adapter time.modified

#!/usr/bin/env bash
set -euo pipefail

# 1) pi 本体
command -v pi >/dev/null || npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 2) 全局档案(仓库内 pi-agent/ ↔ ~/.pi/agent/,凭据除外)
mkdir -p ~/.pi/agent
rsync -a --exclude='auth.json' --exclude='sessions/' \
      --exclude='npm/' --exclude='git/' \
      "$(dirname "$0")/pi-agent/" ~/.pi/agent/

# 3) 起一次 pi(非交互)触发补装,然后对清单
pi --no-session -p "reply ok" >/dev/null
pi list

── 生命周期 ──────────────────────────────────────────
npm i -g --ignore-scripts @earendil-works/pi-coding-agent   # 安装
pi update --all            # 升级 pi + 包 + 收敛 git ref
pi update --self           # 只升级 pi
npm uninstall -g @earendil-works/pi-coding-agent   # 卸载(数据保留)

── 扩展与包 ──────────────────────────────────────────
pi install npm:pkg@1.2.3   # 安装(全局);-l → 项目级
pi install git:github.com/u/r@v1
pi -e ./ext.ts             # 临时加载,当次有效
pi remove npm:pkg          # 卸载
pi list                    # 已装清单
pi config                  # TUI 开关包内资源(Tab 切作用域)
pi update --extensions     # 只升级包

── 会话内 ────────────────────────────────────────────
/reload                    # 热重载扩展/技能/上下文
/trust                     # 保存项目信任决定
/model  /thinking          # 切模型/思考等级;Ctrl+S 存默认
/settings                  # 交互改配置

── 常用旗标 ──────────────────────────────────────────
-p 非交互一炮   -c 续最近会话   -r 选会话恢复
-a / -na   单次信任/忽略项目资源   --offline 跳过启动网络