@ganziliang/zhizh-pi-skillhub 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ganziliang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# @ganziliang/zhizh-pi-skillhub
+
+在 pi 的对话窗口里，用**自然语言**搜索公司内部 SkillHub（`https://skillhub.zhizhengroup.com`）、安装技能、发布技能。不用切浏览器，也不用猜关键词。
+
+```
+> /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 个工具，模型可以自己搜索、安装、发布 |
+| 降级保护 | 模型不可用时自动回退到关键词检索，不会卡死 |
+
+## 安装
+
+```bash
+# 持久安装（写入 ~/.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 或临时切换）：
+
+```powershell
+$env:SKILLHUB_TOKEN="sk_xxxxxxxxxxxxxxxx"
+```
+
+```bash
+export SKILLHUB_TOKEN="sk_xxxxxxxxxxxxxxxx"
+```
+
+随时用 `/skillhub status` 查看当前认证状态，`/skillhub logout` 清除本地 token。
+
+> **发布技能需要额外权限**：token 所属账号必须对目标 namespace 有发布权限，否则发布会被服务端拒绝。
+
+## 命令参考
+
+所有功能都在 `/skillhub` 下。
+
+| 命令 | 说明 |
+| --- | --- |
+| `/skillhub` | 显示帮助 |
+| `/skillhub help` | 显示帮助 |
+| `/skillhub search <自然语言需求>` | **AI 语义搜索**，结果以 Markdown 输出，并弹出选择器可直接安装 |
+| `/skillhub all` | 列出仓库全部技能（按 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]` | 查看或指定用于分析的模型 |
+
+### 常用参数
+
+```bash
+# 搜索
+/skillhub search 有没有能检查代理 IP 的技能
+/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。
+
+## 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 结果 + 交互式安装选择器
+```
+
+**降级行为**：如果没有可用模型、模型调用失败或返回的 JSON 解析不了，会自动退回关键词检索结果，并在输出里标注「未使用 AI 语义排序」，不会报错中断。
+
+## 配置文件
+
+```
+~/.pi/agent/skillhub.json
+```
+
+```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 和可见性。
+
+## 开发
+
+```bash
+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/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