Zhizh Pi Plugin Setup

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

安装引导器

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

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

启动 Pi 后执行：

/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 归纳。

也可以直接查看状态：

/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 的技能目录接进来。

{
  "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 中为单个角色指定模型：

{
  "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 里执行：

/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 配过公司网关，生图就能开箱可用。

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

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

改图接着上一版说就行：

背景再暗一点，其他不动

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

/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 即可，不需要任何安装后配置。

/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 包前，请先确认包来源和代码可信，因为扩展具有执行本机代码的权限。

发布

在本目录执行：

npm version patch
npm publish --access public

本地检查

npm install
npm run check