@ganziliang/zhizh-pi-skillhub

在 pi 的对话窗口里，用自然语言搜索公司内部 SkillHub（https://skillhub.zhizhengroup.com）、安装技能、发布技能。不用切浏览器，也不用猜关键词。

子命令可以整个省掉：/skillhub <自然语言> 等价于 /skillhub search <自然语言>。 子命令拼错时（如 serch）也会提示并照常搜索，不会直接报错。

> /skillhub search 我想把 figma 设计稿变成代码

### SkillHub 智能搜索
**原始需求**：我想把 figma 设计稿变成代码
**意图理解**：把 Figma 设计稿自动转换为前端代码（设计稿转代码）
**AI 检索词**：`Figma` · `设计稿转代码` · `design to code` · `D2C` · `UI 代码生成`

**AI 结论**：最匹配的是 figma-batch-implement（直接把 Figma 设计实现为 Swift/UIKit
代码）；如果目标是先转成可评审的规格再实现，figma-to-openspec 更合适，但它只产出
spec 文档、不落盘代码。注意候选中没有覆盖 Web/React 方向的「Figma 直出代码」技能……

#### 推荐结果（4）
**1. `global/figma-batch-implement`** `v20260608.062928` · 相关度 90
> 能把 Figma 设计稿按共享组件优先、页面其次的顺序批量实现为 Swift/UIKit 代码……

为什么需要它

公司 SkillHub 自带的 CLI 只做字面关键词匹配。你知道「有个技能能提取网页设计规范」，但仓库里那个技能叫 web-design-extractor、描述里写的是「逆向分析网站的视觉系统」——搜「提取设计」就是搜不到。

这个扩展把检索交给大模型：

1. 理解意图 — 把「我想把设计稿变成代码」拆成 Figma / 设计稿转代码 / design to code / D2C 等 4-10 个中英文检索词，覆盖同义词和技术术语。
2. 并行召回 — 每个检索词打一次 registry，同时拉全量目录兜底，合并去重。
3. 语义重排 — 把候选交给模型打分排序，每条给出具体的推荐理由和一段横向对比结论，告诉你哪个更合适、哪个只沾边。

全部过程在 pi 窗口内完成，平均 5-8 秒。

功能

能力	说明
AI 语义搜索	自然语言 → 检索词改写 → 并行召回 → 模型重排 → 带理由的推荐
全量浏览	一次列出仓库里全部可见技能，按 namespace 分组
安装	下载 zip、解压到 pi 技能目录，写入来源 metadata 便于追溯
卸载	清理本地安装（可指定范围）
发布	打包目录为 zip、读 SKILL.md 元数据、上传，支持 --dry-run 先做服务端校验
Agent 工具	暴露 4 个工具，模型可以自己搜索、安装、发布
降级保护	模型不可用时自动回退到关键词检索，不会卡死

安装

# 持久安装（写入 ~/.pi/agent/settings.json）
pi install npm:@ganziliang/zhizh-pi-skillhub

# 或只试用一次
pi -e npm:@ganziliang/zhizh-pi-skillhub

# 或从本地目录安装
pi install /path/to/pi-skillhub

安装后运行 /reload 生效。

配置 Access Token

扩展第一次使用时需要配置 token（仓库地址已硬编码，不用填）。

第 1 步：浏览器打开 https://skillhub.zhizhengroup.com，登录后进入个人设置 / API Token，创建一个 access token。它长这样：sk_xxxxxxxxxxxxxxxx。

第 2 步：在 pi 里执行

/skillhub login

会弹出输入框，粘贴 token 回车。扩展会立刻调用 /auth/whoami 校验，成功后显示你的用户名和邮箱，并把 token 写入 ~/.pi/agent/skillhub.json（POSIX 下权限 0600）。

也可以直接带上 token：

/skillhub login sk_xxxxxxxxxxxxxxxx

或者用环境变量（优先级高于配置文件，适合 CI 或临时切换）：

$env:SKILLHUB_TOKEN="sk_xxxxxxxxxxxxxxxx"

export SKILLHUB_TOKEN="sk_xxxxxxxxxxxxxxxx"

随时用 /skillhub status 查看当前认证状态，/skillhub logout 清除本地 token。

发布技能需要额外权限：token 所属账号必须对目标 namespace 有发布权限，否则发布会被服务端拒绝。用 /skillhub namespaces 查看有哪些 namespace 可填。

Namespace 是什么，怎么查

namespace 是技能仓库里的分组，相当于技能归属的团队或项目。一个技能的完整引用是 <namespace>/<slug>，例如 global/git-worktree-manager 里的 global 就是 namespace。

发布时必须指定 namespace，决定了技能发到哪个分组、谁能看到：

namespace	是什么
global	平台级公共命名空间，全公司可见。绝大多数技能都在这里
zhiai	某个团队/项目的命名空间，非成员只能安装、看不到详情

查当前有哪些 namespace：

/skillhub namespaces

输出：

### SkillHub Namespace

| namespace | 技能数 | 类型 | 说明 |
| --- | --- | --- | --- |
| `global` | 26 | `GLOBAL` | Platform-level public namespace |
| `zhiai` | 7 | 未公开 | 该账号无权查看详情（仍可安装其中的技能） |

这张表同时合并了两个来源：registry 的 namespace 接口（能看到 slug、类型、描述）和技能目录（能看到每个 namespace 下有多少技能）。有些 namespace 你无权查看详情，但只要它下面有你能看到的技能，就会出现在表里——这比单看 namespace 接口更完整。

/skillhub all 的输出也是按 namespace 分组的，同样可以用来参考。

发布时填哪个：写你自己团队的 namespace；如果没有团队 namespace，就填 global。首次成功发布后会自动记到配置文件里，之后不用再指定。

命令参考

所有功能都在 /skillhub 下。

命令	说明
/skillhub	显示帮助
/skillhub help	显示帮助
/skillhub search <自然语言需求>	AI 语义搜索，结果以 Markdown 输出，并弹出选择器可直接安装
/skillhub <自然语言需求>	同上，search 可以省略
/skillhub all	列出仓库全部技能（按 namespace 分组）
/skillhub namespaces	列出可用的 namespace（发布时填这里面的值）
/skillhub install <ns>/<slug>	安装技能
/skillhub list	列出本地已安装技能
/skillhub remove <ns>/<slug>	卸载技能
/skillhub publish <路径>	发布技能
/skillhub login [token]	配置 access token
/skillhub logout	清除本地 token
/skillhub status	查看 registry / token / 目录 / 模型状态
/skillhub model [provider/modelId]	查看或指定用于分析的模型

常用参数

# 搜索
/skillhub search 有没有能检查代理 IP 的技能
/skillhub 有没有能检查代理 IP 的技能         # search 可以省略
/skillhub search 数字人怎么记住人设 --limit 5
/skillhub search 性能审计 --fresh          # 忽略目录缓存，强制重新拉取

# 安装
/skillhub install global/git-worktree-manager
/skillhub install global/git-worktree-manager --project      # 装到当前项目 .pi/skills
/skillhub install zhiai/image-analyzer --version 1.1.0

# 发布
/skillhub publish ./my-skill --namespace global
/skillhub publish ./my-skill --namespace global --dry-run    # 只做服务端校验，不真的发布
/skillhub publish ./my-skill --visibility private            # public | namespace-only | private

不带参数运行时（如 /skillhub install）会弹出可搜索的列表让你挑，无需记 slug。

取值参数 --key value 和 --key=value 两种写法都支持；--fresh、--project、--user、--dry-run 是不带值的开关，写在最后或中间都可以。

Agent 工具

扩展同时注册了 4 个工具，模型可以自主调用：

工具	用途
skillhub_search	语义搜索，参数 query（自然语言）、limit
skillhub_install	安装，参数 ref、scope（user/project）、version
skillhub_list	浏览，参数 source（remote/local/both）
skillhub_publish	发布，参数 path、namespace、visibility、validateOnly

所以你可以直接对 agent 说：

帮我找找有没有处理 PDF 的技能，找到就装到当前项目里

agent 会调用 skillhub_search 拿到排序结果，再用 skillhub_install 装上。

搜索是怎么工作的

用户输入（自然语言）
      │
      ▼
[1] 意图理解 + 检索词改写            ← 模型调用
      │  产出 { intent, keywords: [4-10 个中英文词] }
      ▼
[2] 并行召回                        ← 网络
      │  · 每个 keyword 打一次 /skills/search
      │  · 同时拉全量目录（缓存 3 分钟）兜底
      │  · 合并去重，记录每条命中了哪些检索词
      ▼
[3] 候选裁剪（仅在候选 > 160 条时）
      │  关键词命中优先于目录兜底，其余按词法打分排序
      ▼
[4] 语义重排 + 解释                  ← 模型调用
      │  产出 { overview, results: [{ ref, score, reason }] }
      ▼
Markdown 结果 + 交互式安装选择器

整个流程要调两次模型，通常几秒到十几秒。为了避免「发出去之后屏幕完全没反应」，命令会在编辑器上方实时显示进度 widget：

skillhub 智能检索中 4.6s
  ⠹ 检索仓库…  deepseek/deepseek-flash
  检索词  PPT · 幻灯片 · 演示文稿 · presentation · slides · deck
  候选  42 个

它随着阶段更新（理解需求 → 检索仓库 → AI 排序候选），每 120ms 刷新 spinner 和耗时，完成后自动清除。模型不可用时就地显示降级原因。

当模型自己调 skillhub_search 工具时（而不是你手敲斜杠命令），这些阶段会以流式文本出现在工具调用里。

降级行为：如果没有可用模型、模型调用失败或返回的 JSON 解析不了，会自动退回关键词检索结果，并在输出里标注「未使用 AI 语义排序」，不会报错中断。

配置文件

~/.pi/agent/skillhub.json

{
  "token": "sk_xxxxxxxxxxxx",
  "registry": "https://skillhub.zhizhengroup.com",
  "defaultNamespace": "global",
  "defaultScope": "user",
  "aiModel": "company-anthropic/deepseek-flash"
}

字段	说明
token	access token（也可用 SKILLHUB_TOKEN 环境变量覆盖）
registry	默认硬编码为公司仓库，留空即可
defaultNamespace	发布时默认的 namespace，首次成功发布后自动记住
defaultScope	默认安装范围，user（全局）或 project（项目）
aiModel	指定分析用模型，留空则跟随当前会话模型

安装位置

范围	目录	生效方式
user（默认）	~/.pi/agent/skills/<namespace>--<slug>/	所有项目可用
project	<项目>/.pi/skills/<namespace>--<slug>/	仅当前项目，可随仓库提交

每个安装目录里会写入 .skillhub/metadata.json，记录 registry、namespace、version、fingerprint 和安装时间，/skillhub list 依赖它展示来源。发布打包时会自动排除这个目录。

安装完成后需要 /reload 让 pi 加载新技能。

常见问题

/skillhub search 说「没有可用的已授权模型」

扩展需要调用模型做语义理解。要么当前会话没选模型，要么模型没有配置 API key。用 /model 选一个可用模型，或 /skillhub model <provider>/<modelId> 指定一个。

搜索很慢 / 想更快

一次完整搜索包含 2 次模型调用 + N 次并行搜索，通常 5-8 秒。--limit 调小、--fresh 只在怀疑缓存过期时使用，都能省一点时间。

发布失败：403 / 无权限

token 所属账号对目标 namespace 没有发布权限。先在浏览器里确认你有该 namespace 的写权限，或换一个 namespace。

安装后技能没生效

运行 /reload。如果还不生效，用 /skillhub list 确认路径，并检查该技能是否真的有 SKILL.md。

提示 token 无效

在浏览器里重新创建 token，然后 /skillhub login。环境变量 SKILLHUB_TOKEN 优先级最高，如果设过旧值记得清掉。

发布时哪些文件会被排除

node_modules/、.git/、.github/、.idea/、.vscode/、__pycache__/、.skillhub/、.DS_Store、Thumbs.db，以及 .zip / .tgz / .log 文件。单个文件超过 8MB 或总量超过 32MB 会被跳过并在结果里列出。

安全说明

• token 只写入 ~/.pi/agent/skillhub.json，POSIX 下自动设为 0600；不会写进任何项目文件。
• 用 /skillhub login <token> 直接带参数会把 token 留在 shell history 里，建议用交互式输入或环境变量。
• 扩展以你的完整权限运行。发布是不可逆的写操作，skillhub_publish 工具的行为准则要求模型先向你确认 namespace 和可见性。

开发

git clone <repo> && cd pi-skillhub
npm install

# 类型检查
npx tsc --noEmit

# 本地加载
pi -e ./extensions/skillhub/index.ts

结构

extensions/skillhub/index.ts   入口：注册命令、工具、事件
src/api.ts                     SkillHub HTTP 客户端（/api/cli/v1）
src/ai.ts                      意图理解、召回、重排、降级
src/installer.ts               下载、安全解压、安装/卸载/扫描
src/publisher.ts               打包、SKILL.md 解析、发布
src/ui.ts                      结果渲染、交互式选择器
src/config.ts                  token 与配置读写
src/constants.ts               registry 地址、阈值、枚举

接口

扩展直接对接官方 CLI 使用的 HTTP 接口：

方法	路径
GET	/api/cli/v1/auth/whoami
GET	/api/cli/v1/skills/search?q=&limit=
GET	/api/web/namespaces?page=&size=
GET	/api/cli/v1/skills/<ns>/<slug>/resolve[?version=]
GET	/api/v1/skills/<ns>/<slug>/versions/<v>/download
POST	/api/cli/v1/skills/<ns>/publish（multipart：file、visibility）
POST	/api/cli/v1/skills/<ns>/publish/validate
DELETE	/api/cli/v1/skills/<ns>/<slug>

License

MIT