# Zhizh Pi Plugin Setup

用于引导安装团队常用的 Pi Agent 插件、MCP 包和主题。

## 安装引导器

首次只需要手动安装一次引导器：

```bash
pi install npm:@ganziliang/zhizh-pi-plugin-setup
```

启动 Pi 后执行：

```text
/pi-setup
```

在交互菜单中可以选择单个插件、主题、`配置 Bash 环境`、`配置 SkillHub Token`、`配置 Skills 路径` 或“全部推荐插件和主题”。配置 Bash 时，引导器会询问 `bash.exe` 路径，验证文件存在后写入全局 `~/.pi/agent/settings.json` 的 `shellPath` 字段。选择安装 `pi-subagents` 后，引导器会询问是否配置 subagent 默认模型；输入 `provider/model`（例如 `openai-codex/gpt-5.6-sol`）即可写入全局 `~/.pi/agent/settings.json` 的 `subagents.defaultModel`。如果只想给某个角色指定模型，可按提示参考 `subagents.agentOverrides.<name>.model` 配置。选择 `配置 Skills 路径` 后，引导器会反复询问技能目录或 `SKILL.md` 文件路径（一次可输入多个，用 `;` 分隔），校验路径、统计预计发现的技能数量，最后写入 `settings.json` 的 `skills` 数组（可选择追加或覆盖）。安装完成或修改配置后执行 `/reload`，或者重启 Pi。Token Leaderboard 首次打开时只需粘贴包含 `apiId` 的完整排行榜页面 URL，安装引导器不会保存或询问 API Key。AA Speed Overlay 不需要任何配置，装完直接 `/aa-speed` 即可（数据来自 Artificial Analysis 首页内嵌数据，无需 API key）。GitHub Trending Overlay 同样不需要配置，装完执行 `/github-trending` 即可浏览 Trending 并获取 AI 归纳。

也可以直接查看状态：

```text
/pi-setup status
```

## Skills 路径配置

选择菜单里的 `配置 Skills 路径`（或直接执行 `/pi-setup skills`）可以引导配置全局 `~/.pi/agent/settings.json` 的 `skills` 数组：

1. 输入技能目录或单个 `SKILL.md` 文件路径，支持一次输入多个路径（用 `;`、`；` 或换行分隔）；直接回车结束输入；
2. 引导器会逐个校验路径：目录存在则递归统计预计能发现的技能数量，`~` 会展开为用户主目录，反斜杠会归一化成 `/`；路径不存在时会询问是否仍然写入（Pi 启动时忽略无效路径）；
3. 如果已有 `skills` 配置，可选择**追加**（保留现有条目）或**覆盖**（只保留本次输入）；
4. 确认后写入配置文件，写入完成后会重新读取 `settings.json` 做一次校验并报告结果。

常见用法：把 Claude Code / Codex 的技能目录接进来。

```json
{
  "skills": [
    "C:/Users/me/.claude/skills",
    "C:/Users/me/.codex/skills"
  ]
}
```

生效方式：执行 `/reload` 或重启 Pi。启动时 Pi 会扫描这些目录，把每个技能注册成 `/skill:<name>` 命令并显示在启动头部；`/pi-setup status` 也会列出当前配置的 skills 条目。注意全局 `settings.json` 里的相对路径以 `~/.pi/agent` 为基准解析，建议直接使用绝对路径或 `~`。

## 当前插件清单

| 组件 | 实际安装包 | 包含内容 |
| --- | --- | --- |
| Zhizh Agent HUD | `npm:@ganziliang/zhizh-pi-agent-hud` | `agent-hud`、`model-usage.ts`、`/usage`；安装后默认启用 bubble 输入框 |
| Zhizh Model Setup | `npm:@ganziliang/zhizh-pi-model-setup` | `model-setup.ts`、`/model-setup` |
| Zhizh Token Leaderboard | `npm:@ganziliang/zhizh-pi-token-leaderboard` | `/token-leaderboard`；昨日/当天/周/月排行榜 overlay |
| Pi Attention | `npm:@ganziliang/pi-attention` | Windows 托盘提醒、`/attention`、`/attention:setup`、`/attention:check`、`/attention:reset`、`/attention:ack` |
| MCP Adapter | `npm:pi-mcp-adapter` | MCP 适配能力 |
| Web Access | `npm:pi-web-access` | 网页访问能力 |
| Awesome Pi Themes | `npm:awesome-pi-themes` | 38 套深色主题、在线预览 |
| pi-subagents | `npm:pi-subagents` | subagent 委派工具、内置 `scout`/`reviewer`/`worker`/`oracle` 等角色；安装后引导配置默认模型 |
| Pi Loading Message | `npm:@ganziliang/pi-loading-message` | `/loading-config`、自定义工作中提示语 |
| AA Speed Overlay | `npm:@ganziliang/pi-aa-speed-overlay` | `/aa-speed` 榜单面板（速度/智能/词量/成本/耗时/知识/办公/执行/财务/职业/图像/语音 共 12 个榜）、`aa_leaderboard` 工具；无需 API key |
| GitHub Trending Overlay | `npm:@ganziliang/pi-github-trending-overlay` | `/github-trending` 自适应 overlay：浏览 GitHub Trending，并用当前会话模型归纳每个项目的概述/功能/场景；结果缓存 7 天 |
| **Zhizh AI2Image** | `npm:@ganziliang/zhizh-pi-ai2image` | **`generate_image` 工具（文生图 / 图生图 / 局部改图 / 多变体），生成的图会回灌给模型自我验收；复用 Pi 已配的公司网关凭据，无需额外密钥、无需 Python** |
| Zhizh SkillHub | `npm:@ganziliang/zhizh-pi-skillhub` | `/skillhub search/all/namespaces/install/list/remove/publish/login/logout/status/model`；团队技能仓库的 AI 语义搜索与发布；安装后引导配置 access token |

安装 `pi-subagents` 后，也可以在 `~/.pi/agent/settings.json` 中为单个角色指定模型：

```json
{
  "subagents": {
    "defaultModel": "provider/default-model",
    "agentOverrides": {
      "reviewer": {
        "model": "provider/reviewer-model"
      }
    }
  }
}
```

模型配置优先级和 `/subagents-models` 查看命令详见官方文档：<https://github.com/nicobailon/pi-subagents/blob/main/docs/models.md>。

`agent-hud` 和 `model-usage.ts` 是同一个 npm 包中的两个 Pi 扩展入口，不是两个独立的 npm 包；引导器因此安装整个 HUD 包，避免产生不完整安装。

## SkillHub 配置

选择安装 `Zhizh SkillHub`（或菜单里的 `配置 SkillHub Token`）后，引导器会引导填写 access token：

1. 到 <https://skillhub.zhizhengroup.com> 登录 → 个人设置 → 创建 access token（`sk_` 开头）；
2. 回到 Pi 粘贴 token，引导器会调用 `GET /api/cli/v1/auth/whoami` 在线校验，通过后显示账号名；校验失败也会询问是否仍然保存；
3. 写入全局 `~/.pi/agent/skillhub.json`（权限 0600，保留 `registry`、`defaultNamespace` 等已有字段），不修改 `settings.json`。

也可以跳过引导，在 Pi 里执行：

```text
/skillhub login <token>     # 写入配置
/skillhub status            # 查看当前 token / registry / 默认 namespace
/skillhub search 想要一个能处理 PDF 的技能
/skillhub all               # 按 namespace 浏览全部技能
```

Token 也可以放在环境变量 `SKILLHUB_TOKEN`，其优先级高于配置文件；引导器检测到该变量时会提示无需写入。

发布技能需要账号对目标 namespace 有写权限，首次发布成功后 `defaultNamespace` 会被自动记住。

引导器安装 HUD 成功后，会在全局 `pi-agent-hud.json` 中保留原有配置并设置 `editor: "bubble"`。如果已有项目级配置，项目级配置仍可覆盖全局设置。

## Zhizh AI2Image（生图 / 改图）

选中 `Zhizh AI2Image` 会安装 `npm:@ganziliang/zhizh-pi-ai2image`，装完 `/reload` 或重启 Pi 即可。

安装后 Pi 会多出一个 `generate_image` 工具和一个 `/imagegen` 诊断命令。**不需要额外配置任何东西**：扩展默认直接复用 Pi 自己已配好的公司网关凭据（provider `company-gpt`），所以只要之前用 `/model-setup` 配过公司网关，生图就能开箱可用。

直接用自然语言驱动，无需斜杠命令：

```text
画一张小红书封面，1080x1440 竖版，一只穿奶油黄洞洞鞋的胖橘猫在打太极拳，暖色调
```

改图接着上一版说就行：

```text
背景再暗一点，其他不动
```

要确认当前生效的网关和模型：

```text
/imagegen
```

需要覆盖配置时可用环境变量：

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `PI_IMAGEGEN_PROVIDER` | `company-gpt` | 换一个 Pi provider 取网关凭据 |
| `IMAGEGEN_MODEL` | `gpt-image-2` | 生图模型 |
| `IMAGEGEN_FALLBACK_MODELS` | 空（关闭） | 备用模型，逗号分隔 |
| `IMAGEGEN_BASE_URL` + `IMAGEGEN_API_KEY` | — | 完全绕过 Pi provider，直连指定网关 |

完整用法、尺寸预设、提示词模板和排障说明见包内 README：<https://www.npmjs.com/package/@ganziliang/zhizh-pi-ai2image>

## GitHub Trending Overlay（Trending 浏览 + AI 归纳）

选中 `GitHub Trending Overlay` 会安装 `npm:@ganziliang/pi-github-trending-overlay`，装完 `/reload` 或重启 Pi 即可，**不需要任何安装后配置**。

```text
/github-trending                 # 今日全部语言
/github-trending typescript      # 今日 TypeScript
/github-trending python weekly   # Python 本周趋势
/github-trending go --no-ai      # 跳过 AI 分析，只显示页面原始简介
```

每个仓库展示三段由当前会话模型现场归纳的中文内容（概述 / 功能 / 场景），依据是仓库名称 + 页面简介 + 语言/star + README 摘要，而不是让模型照抄 README。

常用快捷键：`↑`/`↓`（或 `j`/`k`）切换仓库、`PgUp`/`PgDn`（或 `u`/`d`）翻页、`Home`/`End`（或 `g`/`G`）跳首尾、`Enter` 把选中仓库 URL 填入输入框、`r` 重新抓取、`Esc`/`q` 关闭。overlay 顶部对齐、底部固定留 8 行给输入框和状态栏，缩放窗口后自动重排。

可选环境变量：

| 变量 | 作用 |
| --- | --- |
| `PI_TRENDING_MODEL` | 指定分析用模型，格式 `provider/modelId`；不设时优先用轻量模型，最后回退到当前会话模型 |
| `PI_TRENDING_CACHE` | 覆盖分析缓存文件路径（默认 `~/.pi/agent/cache/github-trending-analysis.json`，7 天有效） |
| `PI_TRENDING_BG` | 设为 `off` 关闭项目/条目底色（`NO_COLOR` 同样生效） |

完整用法和实现说明见包内 README：<https://www.npmjs.com/package/@ganziliang/pi-github-trending-overlay>

## 安全说明

引导器只会执行 Pi 官方包管理命令 `pi install <package>`；配置 `pi-subagents` 时只更新 `settings.json` 中的 `subagents.defaultModel`，会保留其他已有配置。不会读取或保存 API Key，也不会覆盖 `models.json`。安装第三方 Pi 包前，请先确认包来源和代码可信，因为扩展具有执行本机代码的权限。

## 发布

在本目录执行：

```bash
npm version patch
npm publish --access public
```

## 本地检查

```bash
npm install
npm run check
```