pi-kit

Pi（earendil-works/pi）的开箱即用封装包：把模型配置、skills、prompt 模板、extensions 打包在一起，安装后即可直接使用，无需手动配置。

目录结构

pi-kit/
├── install.sh              # 一键安装器（pi 运行时 + 配置 + 资源）
├── keys.sh                 # API key 批量配置工具（交互/粘贴/文件导入）
├── package.json            # pi-package manifest（支持 pi install 分发）
├── config/
│   └── models.json         # 模型模板：7 个 provider，key 走环境变量
├── skills/                 # Agent Skills（SKILL.md 标准）
│   ├── git-commit/         # Git 提交助手
│   ├── code-review/        # P1/P2/P3 代码审查
│   ├── brainstorming/      # 创意/功能设计前的需求探索
│   ├── grill-me/           # 方案拷问打磨
│   └── anysearch/          # 实时联网搜索（需自备 ANYSEARCH_API_KEY，见其 README）
├── prompts/                # prompt 模板，/name 展开
│   └── review.md
└── extensions/             # TypeScript 扩展
    └── hello.ts

快速开始

前提：Node.js ≥ 22（brew install node 或官网安装器）。

推荐：npm 全局安装（最简，免 git）

npm install -g @kenzone/pi-kit
pi-kit              # 安装 pi 运行时 + 模型配置 + skills，结尾引导配 key
pi                  # 新开终端即可使用，/model 选择模型

pi-kit 常用命令：

pi-kit install [-y]  # 一键安装（-y 跳过 key 交互）
pi-kit keys          # 批量配置 API key（交互/粘贴/导入，见下文）
pi-kit help          # 查看全部用法

备选：git clone（想改配置/跟源码）

git clone git@gitee.com:kenzone/pi-kit.git && cd pi-kit
./install.sh && ./keys.sh

安装器做的事：检查 Node → 安装 @earendil-works/pi-coding-agent（已装则跳过）→ 备份并合并 ~/.pi/agent/models.json → skills 增量拷贝到 ~/.agents/skills/（标准目录）、prompts/extensions 到 ~/.pi/agent/ → 引导运行 keys.sh 批量配置 key。

平台支持

平台	pi 运行时	pi-kit 脚本	说明
macOS	✅	✅	实测环境，全功能
Linux	✅	✅	脚本纯 POSIX 命令，无平台专属依赖
Windows	✅（需 bash）	⚠️ 需 Git Bash / WSL	见下

• pi 官方支持三平台，但 Windows 上 pi 本身就需要 bash shell（官方文档：Git Bash / MSYS2 / WSL / Cygwin，推荐 Git for Windows）。
• pi-kit 脚本只依赖 npm/node/git 等 POSIX 命令，macOS/Linux 开箱即用；Windows 先装 Git for Windows，再在 Git Bash 里运行（或直接用 npm install -g @kenzone/pi-kit，npm 会自动包装 bash 入口）。
• pi 官方 curl install.sh 仅支持 macOS/Linux；Windows 请走 npm 安装（pi-kit 默认就是 npm 路线，天然兼容）。

三种分发方式

A. npm 全局安装（推荐）：npm install -g @kenzone/pi-kit 后用 pi-kit CLI 一键安装，自动获得模型配置合并与 keys.sh，见快速开始。

B. git clone + install.sh（可定制）：拉源码后运行 ./install.sh，适合需要改 models.json 模板或增删 skills 的场景。

C. pi 官方包机制（仅资源层）：package.json 已带 pi-package 标记，pi 内一条命令装 skills/prompts/extensions：

pi install npm:@kenzone/pi-kit
pi install git:gitee.com/kenzone/pi-kit
pi update --extensions   # 后续升级

注意：pi install 只分发 skills/prompts/extensions/themes，models.json 仍需 pi-kit / install.sh 或手动拷贝。

模型配置

config/models.json 使用环境变量插值，不存明文 key：

• OpenRouter：export OPENROUTER_API_KEY=... 后即可在 /model 中选择全部 OpenRouter 模型。
• NVIDIA NIM：已预置 nvidia/nemotron-3.5-lightning-30b-a3b、deepseek-ai/deepseek-v4-flash-0731、minimaxai/minimax-m3、z-ai/glm-5.2 四个模型，export NVIDIA_API_KEY=... 后在 /model 中选 nvidia-nim。若某模型开启 reasoning 后请求报错，可在该模型条目加 "compat": { "supportsReasoningEffort": false }，或按需设置 "thinkingFormat": "deepseek" / "zai"；想用思考能力就在模型条目加 "reasoning": true。
• SenseNova：已预置 deepseek-v4-flash、sensenova-6.7-flash-lite，export SENSENOVA_API_KEY=... 后在 /model 中选 sensenova。注意：token.sensenova.cn 在阿里内网会被云壳安全策略拦截（403），需先在"云壳 → 防护记录 → 域名拦截"加白，或换网络使用。
• Agnes：已预置 agnes-2.5-flash，export AGNES_API_KEY=... 后在 /model 中选 agnes。
• AChai：已预置 deepseek-v4-flash、grok-4.5、mimo-v2.5，export ACHAI_API_KEY=... 后在 /model 中选 achai。
• OpenCode Zen：已预置 deepseek-v4-flash-free、mimo-v2.5-free、hy3-free 三个免费模型，export OPENCODE_API_KEY=... 后在 /model 中选 opencode。pi 也内置了 OpenCode Zen provider，可用 /login 走官方 OAuth，两种方式二选一。
• 本地 Ollama：默认列出 qwen2.5-coder:7b、llama3.1:8b，按需增删；端口非 11434 时改 baseUrl。
• 自建网关 / 其他 OpenAI 兼容端点：在 providers 中追加：

"my-gateway": {
  "baseUrl": "https://gateway.example.com/v1",
  "api": "openai-completions",
  "apiKey": "$MY_GATEWAY_KEY",
  "models": [{ "id": "your-model-id", "reasoning": true }]
}

apiKey 还支持 "!command" 形式从命令取值（如 !op read ...、!security find-generic-password ...），便于接入密钥管理器。

Key 批量配置（keys.sh）

安装后运行 ./keys.sh 一键设置所有 provider 的 key，支持四种方式：

./keys.sh              # 交互式：逐个输入（显示申请入口，回车=保留已有/跳过）
./keys.sh --paste      # 粘贴批量配置：每行 NAME=value，Ctrl-D 结束
./keys.sh --import f   # 从文件导入（支持 NAME=value / export NAME=value / NAME: value）
./keys.sh --list       # 查看当前配置（脱敏显示）
./keys.sh --unset K    # 删除指定 key

行为约定：

• key 统一写入 ~/.pi/agent/keys.env（权限 600），shell rc 只添加一行带标记的 source，重复运行不会产生重复行。
• 幂等且保留式：再次运行只更新你输入的项，已有配置不丢；每次写入前自动备份旧文件。
• 只接受白名单内的 key 名（6 个 provider + anysearch skill 的 ANYSEARCH_API_KEY），其他行会警告并跳过。
• 新终端自动生效；当前终端可 source ~/.zshrc 后立即用 pi --list-models 验证。

安全约定

• 任何明文 API key 不得提交进仓库；模板一律用 $ENV_VAR 或 !command 插值。
• install.sh 对已有 models.json 先备份再合并（不覆盖已有 provider）；写 shell rc 前同样备份。
• pi 包（extensions/skills）以用户权限运行，内部分发前请先 review 代码。

常用操作

操作	命令
升级 pi 本体	pi update --self
升级包资源	pi update --extensions
刷新模型目录	pi update --models
启停资源项	pi config
项目级配置	项目内 .pi/settings.json + .pi/skills/（首次需 /trust）
发布新版本	./release.sh [patch|minor|major]（bump → 发 npm → 打 tag → 推 Gitee；--dry-run 只检查不发布）

FAQ

• skills 装在哪里 / 会不会 collision：install.sh 把 skills 装到跨工具标准目录 ~/.agents/skills/（pi、QoderWork 等共读），不在 ~/.pi/agent/skills/ 放副本，天然无跨目录冲突；同名已存在则跳过不覆盖。prompts/extensions/themes 因 pi 只认 ~/.pi/agent/ 全局位置，仍装在那里。历史版本若曾在 ~/.pi/agent/skills/ 留下副本，手动删除即可。
• 启动提示 name contains invalid characters：skill 的 SKILL.md name: 字段必须全小写字母/数字/连字符，大写或下划线会被 pi 拒载，改成小写即可。
• 已经装过 pi / 改过配置，重复运行 install.sh 会怎样？ 完全幂等，可放心重跑：pi 已存在则跳过安装（npm 装的、官方 install.sh 装的二进制都能识别）；models.json 先备份再按 provider 级合并——你已有的 provider 配置原样保留，只补缺失的；skills/prompts/extensions 同名已存在则跳过不覆盖；API key 已配置则跳过。想强制更新某个资源项，先手动删除 ~/.pi/agent/ 下对应文件再重跑即可。
• 启动提示 project trust：项目目录含 .pi/ 或 .agents/skills/ 时 pi 会先征求信任，确认一次即可。
• 公司内网：npm 源可换内网 registry；pi update 联网行为可用 PI_OFFLINE=1 关闭。
• 配置目录：默认 ~/.pi/agent，可用环境变量 PI_CODING_AGENT_DIR 覆盖（install.sh 已兼容）。