Tools
Typesafe Catalog Router
By typesafe jev openclaw plugins
Install
npm install &&README
# TypeSafe Catalog Router（OpenClaw）
用 [TypeSafe](https://docs.typesafe.ai) Jev（System One）给 OpenClaw 的 **Skills + MCP** 做目录路由：混合打分、默认给出 Top 5，再用稳定 ID 让用户确认后才加载——避免 Agent「猜技能」或口头编号对不上号。
仓库：[https://github.com/dgyun-ai/openclaw-typesafe-catalog-router](https://github.com/dgyun-ai/openclaw-typesafe-catalog-router)
本插件只做 **catalog routing**，不抢基建能力。
## 项目优点
- **Skill + MCP 一起荐**：同一候选池打分，Top N 可同时给出两种 `kind`，一次看清该用技能还是 MCP。
- **TypeSafe 门控 + 短名单**：按官方 Skill suggestion 思路（门控 → skim → 精读），默认 Top 5 交用户确认后再加载。
- **ID 确认，防选错**：`choiceSetId` + `optionId` 双键确认，口头序号只能展示、不能当确认凭证。
- **一次性 choiceSet**：确认即废、带 TTL，降低误用过期推荐。
- **独立可装**：直连 `@typesafe-ai/sdk`，配好 `apiKey`（或 `TYPESAFE_API_KEY`）即可；可选 `baseUrl` 接本地 System One。
- **跟当前 Gateway 对齐**：运行时扫描 skill 根目录与 `mcp.servers`，支持增删与 MCP 粒度配置。
- **可控延迟与费用**：超时、熔断、可选 LRU 缓存；异常明确报错。
- **职责单一**：仅 catalog routing；斜杠 `/suggest-tools` 或主动调工具才触发，不抢其他基建能力。
## 何时会调用
本插件**不会**默认每条消息自动跑。常见触发：
| 方式 | 说明 |
| ------------------ | ------------------------------- |
| `/suggest-tools …` | 用户斜杠命令（`user-invocable` skill） |
| 用户明确点名 / Agent 决定 | 例如「用 suggest_tools 分析…」后模型自行调工具 |
普通闲聊或直接干活时，模型可能完全不调本插件——这是当前设计，不是安装失败。
## 安装
路径安装前请保持**干净目录**：不要带 `node_modules`（OpenClaw 会安装运行时依赖并链接 peer）。需已有构建产物 `dist/`（开发时本地 `npm install && npm run build`）。
```bash
# 干净目录 / 清掉 node_modules 后
openclaw plugins install ./openclaw-typesafe-catalog-router
# 或从 Git
# openclaw plugins install git+ssh://git@github.com:dgyun-ai/openclaw-typesafe-catalog-router.git
# 从ClawHub 安装
# openclaw plugins install clawhub:@dgyun-ai/openclaw-typesafe-catalog-router
```
配置示例：
```json5
{
plugins: {
entries: {
"typesafe-catalog-router": {
enabled: true,
config: {
apiKey: "ts_live_...",
model: "jev-latest",
timeoutMs: 1500,
shortlistSize: 5,
choiceTtlMs: 900000,
mcpGranularity: "tool"
}
}
}
}
}
```
- `apiKey` 也可来自环境变量 `TYPESAFE_API_KEY`
- 可选 `baseUrl` 指向本地 System One
## 工具
| 工具 | 作用 |
| --------------------- | ------------------------------------------------------- |
| `suggest_tools` | 门控 → **混合** skill+MCP shortlist → Top N + `choiceSetId` |
| `confirm_tool_choice` | 用 `choiceSetId` + `optionId` 确认（一次性，带 TTL） |
配套 Skill：`/suggest-tools`（见 `skills/suggest-tools/SKILL.md`）。
## 推荐流程
1. Agent 调用 `suggest_tools({ query })`
2. 向用户展示 `options`（标明 `kind`；展示序号 `1/2/3` 时，确认须映射到对应 `optionId`）
3. 用户选定后，调用 `confirm_tool_choice({ choiceSetId, optionId })`
4. 仅在确认成功后，按 `entry.howToUse` 加载 skill 或调用 MCP
## 开发
```bash
npm install
npm run build
npm test
```
**注意：** 本地 `npm install` 会拉起 peer/dev 的 `openclaw`，调试完路径安装前请删掉 `node_modules`，否则可能挡住 peer 链接。
## 许可证
MIT
tools
Comments
Sign in to leave a comment