@vintmd/cos-vectors 1.0.0

package/README.md

@@ -0,0 +1,305 @@
+# vintmd-cos-vectors
+
+[OpenClaw](https://github.com/openclaw/openclaw) 插件，集成 **腾讯云 COS 向量数据库**，实现**逐轮动态 Skill 路由**。
+
+每次对话时，用户的消息会被向量化，并自动将 **top-k 最相关的 skill** 注入到 system prompt 中 —— 无需重启会话，下一条消息即时生效。
+
+---
+
+## 工作原理
+
+```
+用户消息（每轮触发）
+        │
+        ▼
+  Embedding API（兼容 OpenAI 接口）
+        │  对消息文本做向量化
+        ▼
+  COS Vectors（QueryVectors）
+        │  返回 top-k 最相似的 skill（按 minScore 过滤）
+        ▼
+  appendSystemContext  ──►  LLM
+```
+
+1. Skill 以向量形式存储在 **腾讯云 COS 向量数据库**中，通过 `cos-vectors-proxy` HTTP API 操作。
+2. 每个 skill 使用任意 **兼容 OpenAI 接口的 Embedding API** 进行向量化（支持 OpenAI、混元、Azure、本地模型等）。
+3. `before_prompt_build` hook 在**每次 LLM 调用前**触发（而非仅在 session 初始化时），查询 top-k 相关 skill 并注入到可缓存的 system prompt 后缀中。
+
+> **核心优势**：hook 每轮都会触发，因此通过 `skill_add` / `skill_remove` 添加或删除的 skill，在**下一条消息**即可生效，无需重开会话或重启 OpenClaw。
+
+---
+
+## 前置条件
+
+| 依赖 | 说明 |
+|---|---|
+| OpenClaw ≥ 3.22 | 使用 `plugin-sdk` hook API |
+| [cos-vectors-proxy](https://github.com/tencentyun/cos-vectors-proxy) | 本地或远程运行，提供 `PutVectors` / `QueryVectors` / `DeleteVectors` 接口 |
+| 腾讯云账号 | 需要有 COS 向量数据库权限的 SecretId / SecretKey |
+| 已存在的向量桶 + 索引 | **不要新建向量桶**，绑定已有的桶（如广州区 `test-12345678`） |
+| 兼容 OpenAI 接口的 Embedding API | OpenAI / 混元 / Azure / 本地模型服务均可 |
+
+---
+
+## 安装
+
+### 方式一：通过 npm 安装（推荐）
+
+```bash
+openclaw plugins install @vintmd/cos-vectors
+```
+
+OpenClaw 会优先从 ClawHub 查找，找不到时自动回退到 npm。安装完成后重启 Gateway 即可。
+
+### 方式二：本地路径安装（开发 / 自定义）
+
+将本目录放置（或软链接）到 OpenClaw 的 extensions 目录下，然后在 OpenClaw 配置文件中启用：
+
+```jsonc
+// openclaw.config.json
+{
+  "plugins": [
+    {
+      "id": "vintmd-cos-vectors",
+      "path": "./extensions/vintmd-cos-vectors"
+    }
+  ]
+}
+```
+
+无需执行 `npm install` —— 插件没有外部依赖，仅使用 Node.js 内置的 `crypto` 和 `fetch`。
+
+---
+
+## 配置
+
+所有选项可在插件的 `config` 块中设置，**也可通过环境变量**配置。配置文件中的值优先级高于环境变量。
+
+### 配置项说明
+
+| 字段 | 类型 | 默认值 | 环境变量 | 说明 |
+|---|---|---|---|---|
+| `proxyEndpoint` | string | `http://127.0.0.1:8080` | `COSVECTORS_ENDPOINT` | cos-vectors-proxy 的访问地址 |
+| `vectorBucketName` | string | `openclaw-skills` | `COSVECTORS_BUCKET` | COS 向量桶名称（必须已存在） |
+| `indexName` | string | `skills` | `COSVECTORS_INDEX` | 向量桶内的索引名称（必须已存在） |
+| `secretId` | string | — | `COSVECTORS_SECRET_ID` | 腾讯云 SecretId |
+| `secretKey` | string | — | `COSVECTORS_SECRET_KEY` | 腾讯云 SecretKey |
+| `topK` | number | `5` | — | 每轮最多注入的 skill 数量 |
+| `minScore` | number | `0.5` | — | 最低相似度阈值（0~1），越低召回越多 |
+| `embeddingModel` | string | `text-embedding-3-small` | `SKILL_ROUTER_EMBEDDING_MODEL` | Embedding 模型名称 |
+| `embeddingBaseUrl` | string | `https://api.openai.com/v1` | `SKILL_ROUTER_EMBEDDING_BASE_URL` | Embedding API 的 base URL |
+| `embeddingApiKey` | string | — | `SKILL_ROUTER_EMBEDDING_API_KEY` / `OPENAI_API_KEY` | Embedding API 密钥 |
+
+### 配置示例 — 使用混元 Embedding
+
+```jsonc
+{
+  "plugins": [
+    {
+      "id": "vintmd-cos-vectors",
+      "path": "./extensions/vintmd-cos-vectors",
+      "config": {
+        "proxyEndpoint": "http://<cos-vectors-proxy地址>:<端口>",
+        "vectorBucketName": "your-bucket-name",
+        "indexName": "skills",
+        "secretId": "<your-secret-id>",
+        "secretKey": "<your-secret-key>",
+        "topK": 5,
+        "minScore": 0.3,
+        "embeddingModel": "hunyuan-embedding",
+        "embeddingBaseUrl": "https://api.hunyuan.cloud.tencent.com/v1",
+        "embeddingApiKey": "<your-api-key>"
+      }
+    }
+  ]
+}
+```
+
+### 配置示例 — 环境变量方式
+
+```bash
+export COSVECTORS_ENDPOINT=http://<cos-vectors-proxy地址>:<端口>
+export COSVECTORS_BUCKET=your-bucket-name
+export COSVECTORS_INDEX=skills
+export COSVECTORS_SECRET_ID=<your-secret-id>
+export COSVECTORS_SECRET_KEY=<your-secret-key>
+export SKILL_ROUTER_EMBEDDING_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
+export SKILL_ROUTER_EMBEDDING_MODEL=hunyuan-embedding
+export OPENAI_API_KEY=<your-api-key>   # 作为 embeddingApiKey 的兜底
+```
+
+---
+
+## 工具（Tools）
+
+插件注册了四个工具，可由 LLM 调用，也可通过 OpenClaw tool API 直接调用：
+
+### `skill_add`
+
+将 skill 向量化后写入 COS Vectors（upsert）。**下一条消息**即可生效。
+
+```json
+{
+  "name": "python-debugging",
+  "content": "调试 Python 时，优先查看 traceback 最后一行。交互式调试使用 pdb.set_trace()..."
+}
+```
+
+### `skill_remove`
+
+按名称删除 skill。**下一条消息**即可生效。
+
+```json
+{ "name": "python-debugging" }
+```
+
+### `skill_list`
+
+列出**本地内存缓存**中的 skill（仅包含当前进程启动后通过 `skill_add` 添加的条目）。
+
+> ⚠️ 此工具**不会**查询 COS Vectors 服务端，只反映当前进程生命周期内的操作记录。如需发现已有 skill，请使用 `skill_search`。
+
+```json
+{}
+```
+
+### `skill_search`
+
+按查询文本搜索相关 skill，适合调试路由逻辑。
+
+```json
+{
+  "query": "如何修复 C++ 中的段错误",
+  "topK": 3
+}
+```
+
+---
+
+## Skill ID 命名规则
+
+Skill 名称会被规范化为稳定的向量 key，作为 COS Vectors 的文档键：
+
+```
+"Python Debugging"  →  "skill-python-debugging"
+"SQL Optimization"  →  "skill-sql-optimization"
+"deploy-k8s"        →  "skill-deploy-k8s"
+```
+
+注意：`skill_add("Python Debugging", ...)` 和 `skill_add("python-debugging", ...)` 会映射到**同一个** key，后者会覆盖前者。
+
+---
+
+## 相似度分数与调优
+
+COS Vectors 对归一化向量使用**内积（IP）距离**计算余弦相似度。插件将其转换为 `[0, 1]` 分数：
+
+```
+score = 1 - distance   （截断到 [0, 1]）
+```
+
+只有 `score >= minScore` 的 skill 才会被注入。调优参考：
+
+| `minScore` | 行为 |
+|---|---|
+| `0.7+` | 高精度，只注入非常相关的 skill |
+| `0.5` | 均衡（默认值） |
+| `0.3` | 高召回，注入更多 skill，可能包含弱相关内容 |
+| `0.0` | 始终注入 top-k，不过滤 |
+
+Embedding 模型的选择同样重要：
+- **混元 Embedding**（`hunyuan-embedding`）：**1024 维**，中英文混合内容效果好
+- **OpenAI `text-embedding-3-small`**：**1536 维**，英文内容效果更佳
+
+---
+
+## 动态 Skill 更新（核心特性）
+
+与静态 system prompt 不同，本插件**逐轮**更新注入的 skill：
+
+```
+第 1 轮：用户问 git 相关 → 注入 git-commit skill
+第 2 轮：用户问 SQL 相关 → 注入 sql-optimize skill（git-commit 不注入）
+第 3 轮：调用 skill_add("new-skill", ...) → 从第 4 轮起可用
+第 4 轮：用户问 new-skill 相关话题 → new-skill 立即被注入
+```
+
+这解决了"skill 只在新开会话时才更新"的经典问题。
+
+---
+
+## Token 节省效果
+
+与将所有 skill 全量注入 system prompt 相比：
+
+| 方案 | 注入 skill 数 | 估算 token（10 个 skill） |
+|---|---|---|
+| 静态全量注入 | 10 / 10 | ~450 |
+| 动态 top-k=3 | 3 / 10 | ~165 |
+| **节省** | — | **~63%** |
+
+skill 数量越多，节省效果越显著。
+
+---
+
+## 快速开始
+
+1. 确保 `cos-vectors-proxy` 已启动并可访问。
+2. 确认 COS 向量桶和索引已存在（可用 `list-indexes.mjs` 验证）。
+3. 填写配置文件或设置环境变量。
+4. 在 `openclaw.config.json` 中启用插件，启动 OpenClaw。
+5. 让 LLM 添加一个 skill：
+   > "添加一个名为 'git-rebase' 的 skill，内容：合并前始终使用 `git rebase -i` 整理提交记录。"
+6. 在**同一个会话**中，问任何与 git rebase 相关的问题 —— skill 会自动注入。
+
+---
+
+## 验证连通性
+
+在接入 OpenClaw 前，可用内置脚本验证环境：
+
+```bash
+# 列出向量桶中的所有索引（验证桶和索引是否存在）
+node list-indexes.mjs
+
+# 运行完整 E2E 测试：添加 skill、查询、删除、token 对比
+node test-real.mjs
+```
+
+`test-real.mjs` 预期输出：
+```
+✅ PASS: git-commit skill found in results
+✅ PASS: git-commit skill successfully removed
+✅ PASS: deploy-k8s skill found
+📊 Token reduction: ~63% (saved ~285 tokens)
+```
+
+---
+
+## 常见问题
+
+### Skill 没有出现在回复中
+
+- 检查 `minScore` 是否过高 —— 调低到 `0.3` 看是否有 skill 被过滤掉。
+- 用 `skill_search` 加上你的查询文本，查看实际返回的分数。
+- 确认添加 skill 时使用的 Embedding 模型与当前查询时一致，且向量桶/索引名称匹配。
+
+### `skill_list` 返回空列表
+
+- `skill_list` 只显示**当前进程**通过 `skill_add` 添加的 skill，不查询 COS Vectors 服务端。如需发现已有 skill，请用 `skill_search` 进行宽泛查询。
+
+### COS Vectors 鉴权失败
+
+- 检查 `secretId` / `secretKey` 是否正确，且具有 COS 向量数据库操作权限。
+- 确认 `proxyEndpoint` 从当前机器可以访问。
+- 签名使用 HMAC-SHA1，请确保系统时钟准确（误差在 ±5 分钟以内）。
+
+### Embedding API 报错
+
+- 使用混元时：base URL 必须为 `https://api.hunyuan.cloud.tencent.com/v1`，模型名为 `hunyuan-embedding`。
+- API key 读取优先级：`config.embeddingApiKey` → `SKILL_ROUTER_EMBEDDING_API_KEY` 环境变量 → `OPENAI_API_KEY` 环境变量。
+
+### 索引维度不匹配
+
+- 同一个索引内所有向量的维度必须一致。切换 Embedding 模型后，需要重建索引或使用新索引。
+- 混元 Embedding：**1024 维**；OpenAI `text-embedding-3-small`：**1536 维**。

package/index.ts

@@ -0,0 +1,203 @@
+import type { OpenClawPluginApi, OpenClawPluginToolFactory } from "openclaw/plugin-sdk/core";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { SkillRouter } from "./src/skill-router.js";
+
+export default definePluginEntry({
+  id: "vintmd-cos-vectors",
+  name: "Vintmd COS Vectors",
+  description: "Vintmd COS Vectors-backed dynamic skill routing with embedding similarity search",
+  register(api: OpenClawPluginApi) {
+    const cfg = (api.pluginConfig ?? {}) as {
+      proxyEndpoint?: string;
+      vectorBucketName?: string;
+      indexName?: string;
+      secretId?: string;
+      secretKey?: string;
+      topK?: number;
+      minScore?: number;
+      embeddingModel?: string;
+      embeddingBaseUrl?: string;
+      embeddingApiKey?: string;
+    };
+
+    const router = new SkillRouter({
+      proxyEndpoint:
+        cfg.proxyEndpoint ?? process.env.COSVECTORS_ENDPOINT ?? "http://127.0.0.1:8080",
+      vectorBucketName: cfg.vectorBucketName ?? process.env.COSVECTORS_BUCKET ?? "openclaw-skills",
+      indexName: cfg.indexName ?? process.env.COSVECTORS_INDEX ?? "skills",
+      secretId: cfg.secretId ?? process.env.COSVECTORS_SECRET_ID ?? "",
+      secretKey: cfg.secretKey ?? process.env.COSVECTORS_SECRET_KEY ?? "",
+      topK: cfg.topK ?? 5,
+      minScore: cfg.minScore ?? 0.5,
+      embeddingModel:
+        cfg.embeddingModel ?? process.env.SKILL_ROUTER_EMBEDDING_MODEL ?? "text-embedding-3-small",
+      embeddingBaseUrl:
+        cfg.embeddingBaseUrl ??
+        process.env.SKILL_ROUTER_EMBEDDING_BASE_URL ??
+        "https://api.openai.com/v1",
+      embeddingApiKey:
+        cfg.embeddingApiKey ??
+        process.env.SKILL_ROUTER_EMBEDDING_API_KEY ??
+        process.env.OPENAI_API_KEY ??
+        "",
+      logger: api.logger,
+    });
+
+    // ── Hook: inject relevant skills before each prompt build ──────────────
+    api.on(
+      "before_prompt_build",
+      async (event) => {
+        try {
+          const skills = await router.queryTopK(event.prompt);
+          if (skills.length === 0) return;
+
+          const skillContext = skills
+            .map((s) => `## Skill: ${s.name}\n${s.content}`)
+            .join("\n\n---\n\n");
+
+          return {
+            // appendSystemContext goes into the cacheable system prompt suffix,
+            // so providers like Anthropic can cache it across turns.
+            appendSystemContext: `\n\n# Relevant Skills (auto-selected by SkillRouter)\n\n${skillContext}`,
+          };
+        } catch (err) {
+          api.logger.warn(`[vintmd-cos-vectors] before_prompt_build error: ${err}`);
+          return;
+        }
+      },
+      { priority: 5 },
+    );
+
+    // ── Tool: add a skill ──────────────────────────────────────────────────
+    api.registerTool(((_ctx) => ({
+      name: "skill_add",
+      label: "Add Skill",
+      description:
+        "Add or update a skill in the SkillRouter. The skill will be embedded and stored in COS Vectors, and will be automatically injected into future conversations when relevant.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Unique skill name (e.g. 'python-debugging', 'sql-optimization')",
+          },
+          content: {
+            type: "string",
+            description: "Full skill content / instructions in Markdown",
+          },
+        },
+        required: ["name", "content"],
+      },
+      async execute(_id: string, params: Record<string, unknown>) {
+        const name = typeof params.name === "string" ? params.name.trim() : "";
+        const content = typeof params.content === "string" ? params.content.trim() : "";
+        if (!name) throw new Error("name is required");
+        if (!content) throw new Error("content is required");
+        await router.addSkill(name, content);
+        return {
+          content: [{ type: "text", text: `Skill "${name}" added/updated successfully.` }],
+          details: { ok: true, name },
+        };
+      },
+    })) as unknown as OpenClawPluginToolFactory);
+
+    // ── Tool: remove a skill ───────────────────────────────────────────────
+    api.registerTool(((_ctx) => ({
+      name: "skill_remove",
+      label: "Remove Skill",
+      description: "Remove a skill from the SkillRouter by name.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "Skill name to remove",
+          },
+        },
+        required: ["name"],
+      },
+      async execute(_id: string, params: Record<string, unknown>) {
+        const name = typeof params.name === "string" ? params.name.trim() : "";
+        if (!name) throw new Error("name is required");
+        await router.removeSkill(name);
+        return {
+          content: [{ type: "text", text: `Skill "${name}" removed successfully.` }],
+          details: { ok: true, name },
+        };
+      },
+    })) as unknown as OpenClawPluginToolFactory);
+
+    // ── Tool: list skills ──────────────────────────────────────────────────
+    api.registerTool(((_ctx) => ({
+      name: "skill_list",
+      label: "List Skills",
+      description: "List all skills currently stored in the SkillRouter.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+      async execute(_id: string, _params: Record<string, unknown>) {
+        const skills = await router.listSkills();
+        const text =
+          skills.length === 0
+            ? "No skills registered yet."
+            : skills
+                .map(
+                  (s) =>
+                    `- **${s.name}**: ${s.content.slice(0, 80)}${s.content.length > 80 ? "..." : ""}`,
+                )
+                .join("\n");
+        return {
+          content: [{ type: "text", text }],
+          details: { skills: skills.map((s) => s.name) },
+        };
+      },
+    })) as unknown as OpenClawPluginToolFactory);
+
+    // ── Tool: search skills (debug/test) ───────────────────────────────────
+    api.registerTool(((_ctx) => ({
+      name: "skill_search",
+      label: "Search Skills",
+      description:
+        "Search for relevant skills by query text (for debugging/testing the SkillRouter).",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Query text to search for relevant skills",
+          },
+          topK: {
+            type: "number",
+            description: "Number of results to return (default: 5)",
+          },
+        },
+        required: ["query"],
+      },
+      async execute(_id: string, params: Record<string, unknown>) {
+        const query = typeof params.query === "string" ? params.query.trim() : "";
+        if (!query) throw new Error("query is required");
+        const k = typeof params.topK === "number" ? Math.floor(params.topK) : undefined;
+        const skills = await router.queryTopK(query, k);
+        const text =
+          skills.length === 0
+            ? "No relevant skills found."
+            : skills
+                .map(
+                  (s, i) =>
+                    `${i + 1}. **${s.name}** (score: ${s.score?.toFixed(3) ?? "n/a"})\n${s.content.slice(0, 120)}${s.content.length > 120 ? "..." : ""}`,
+                )
+                .join("\n\n");
+        return {
+          content: [{ type: "text", text }],
+          details: { skills },
+        };
+      },
+    })) as unknown as OpenClawPluginToolFactory);
+
+    api.logger.info(
+      "[vintmd-cos-vectors] registered: before_prompt_build hook + skill_add/remove/list/search tools",
+    );
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,69 @@
+{
+  "id": "vintmd-cos-vectors",
+  "name": "Vintmd COS Vectors",
+  "description": "Dynamic skill routing via COS Vectors embedding similarity search. Automatically selects top-k relevant skills per conversation turn to reduce token usage.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "proxyEndpoint": {
+        "type": "string",
+        "description": "COS Vectors proxy endpoint, e.g. http://127.0.0.1:8080"
+      },
+      "vectorBucketName": {
+        "type": "string",
+        "description": "COS Vectors bucket name"
+      },
+      "indexName": {
+        "type": "string",
+        "description": "COS Vectors index name for skills"
+      },
+      "secretId": {
+        "type": "string",
+        "description": "Tencent Cloud SecretId for COS Vectors auth"
+      },
+      "secretKey": {
+        "type": "string",
+        "description": "Tencent Cloud SecretKey for COS Vectors auth"
+      },
+      "topK": {
+        "type": "number",
+        "description": "Number of top similar skills to inject per turn (default: 5)"
+      },
+      "minScore": {
+        "type": "number",
+        "description": "Minimum similarity score threshold 0~1 (default: 0.5)"
+      },
+      "embeddingModel": {
+        "type": "string",
+        "description": "OpenAI-compatible embedding model to use (default: text-embedding-3-small)"
+      },
+      "embeddingBaseUrl": {
+        "type": "string",
+        "description": "Base URL for embedding API (default: https://api.openai.com/v1)"
+      },
+      "embeddingApiKey": {
+        "type": "string",
+        "description": "API key for embedding service"
+      }
+    }
+  },
+  "uiHints": {
+    "proxyEndpoint": {
+      "label": "COS Vectors Proxy Endpoint",
+      "placeholder": "http://127.0.0.1:8080"
+    },
+    "vectorBucketName": { "label": "Vector Bucket Name" },
+    "indexName": { "label": "Index Name", "placeholder": "skills" },
+    "secretId": { "label": "SecretId", "sensitive": true },
+    "secretKey": { "label": "SecretKey", "sensitive": true },
+    "topK": { "label": "Top-K Skills", "placeholder": "5" },
+    "minScore": { "label": "Min Similarity Score", "placeholder": "0.5" },
+    "embeddingModel": { "label": "Embedding Model", "placeholder": "text-embedding-3-small" },
+    "embeddingBaseUrl": {
+      "label": "Embedding API Base URL",
+      "placeholder": "https://api.openai.com/v1"
+    },
+    "embeddingApiKey": { "label": "Embedding API Key", "sensitive": true }
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@vintmd/cos-vectors",
+  "version": "1.0.0",
+  "description": "OpenClaw plugin: dynamic per-turn skill routing via COS Vectors embedding similarity search",
+  "keywords": [
+    "cos-vectors",
+    "embedding",
+    "openclaw",
+    "openclaw-plugin",
+    "rag",
+    "skill-router",
+    "tencent"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/skill-router.ts

@@ -0,0 +1,337 @@
+/**
+ * SkillRouter — COS Vectors-backed dynamic skill store.
+ *
+ * Architecture:
+ *   1. Skills are stored as vectors in COS Vectors (cos-vectors-proxy HTTP API).
+ *   2. Each skill is embedded via an OpenAI-compatible embedding API.
+ *   3. On every before_prompt_build hook, the current user prompt is embedded
+ *      and the top-k most similar skills are retrieved and injected into the
+ *      system prompt suffix (appendSystemContext) for prompt caching.
+ *
+ * COS Vectors HTTP API (cos-vectors-proxy):
+ *   POST /:methodName  — method names: PutVectors, QueryVectors, DeleteVectors
+ *   Auth: HMAC-SHA256 signature (simplified: SecretId/SecretKey in header)
+ *
+ * Embedding API: OpenAI-compatible  POST /embeddings
+ */
+
+import crypto from "node:crypto";
+
+/** Minimal logger interface (mirrors openclaw/plugin-sdk/core PluginLogger) */
+export type PluginLogger = {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type Skill = {
+  id: string;
+  name: string;
+  content: string;
+  score?: number;
+};
+
+export type SkillRouterConfig = {
+  /** COS Vectors proxy endpoint, e.g. http://127.0.0.1:8080 */
+  proxyEndpoint: string;
+  /** COS Vectors bucket name */
+  vectorBucketName: string;
+  /** COS Vectors index name */
+  indexName: string;
+  /** Tencent Cloud SecretId */
+  secretId: string;
+  /** Tencent Cloud SecretKey */
+  secretKey: string;
+  /** Number of top-k skills to return per query */
+  topK: number;
+  /** Minimum similarity score threshold (0~1, cosine similarity) */
+  minScore: number;
+  /** OpenAI-compatible embedding model */
+  embeddingModel: string;
+  /** Base URL for embedding API */
+  embeddingBaseUrl: string;
+  /** API key for embedding service */
+  embeddingApiKey: string;
+  logger?: PluginLogger;
+};
+
+// ── In-memory skill cache (name → Skill) ──────────────────────────────────
+
+type SkillCacheEntry = {
+  id: string;
+  name: string;
+  content: string;
+};
+
+// ── SkillRouter ────────────────────────────────────────────────────────────
+
+export class SkillRouter {
+  private cfg: SkillRouterConfig;
+  private log: PluginLogger;
+  // Local cache: skill name → entry (for list/delete by name)
+  private skillCache = new Map<string, SkillCacheEntry>();
+
+  constructor(cfg: SkillRouterConfig) {
+    this.cfg = cfg;
+    this.log = cfg.logger ?? {
+      info: (m) => console.info(m),
+      warn: (m) => console.warn(m),
+      error: (m) => console.error(m),
+    };
+  }
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  /**
+   * Add or update a skill. Embeds the skill text and upserts into COS Vectors.
+   */
+  async addSkill(name: string, content: string): Promise<void> {
+    const id = this.nameToId(name);
+    const text = `${name}: ${content}`;
+    const embedding = await this.embed(text);
+
+    await this.putVectors([
+      {
+        key: id,
+        data: { float32: embedding },
+        metadata: { name, content },
+      },
+    ]);
+
+    this.skillCache.set(name, { id, name, content });
+    this.log.info(`[skill-router] addSkill: "${name}" (id=${id})`);
+  }
+
+  /**
+   * Remove a skill by name.
+   */
+  async removeSkill(name: string): Promise<void> {
+    const id = this.nameToId(name);
+    await this.deleteVectors([id]);
+    this.skillCache.delete(name);
+    this.log.info(`[skill-router] removeSkill: "${name}" (id=${id})`);
+  }
+
+  /**
+   * Query top-k skills most similar to the given query text.
+   */
+  async queryTopK(query: string, topK?: number): Promise<Skill[]> {
+    const k = topK ?? this.cfg.topK;
+    const embedding = await this.embed(query);
+    const results = await this.queryVectors(embedding, k);
+    return results.filter((s) => (s.score ?? 1) >= this.cfg.minScore);
+  }
+
+  /**
+   * List all skills from local cache (populated on add/remove).
+   * For a full server-side list, use listVectors API.
+   */
+  async listSkills(): Promise<Skill[]> {
+    return Array.from(this.skillCache.values()).map((e) => ({
+      id: e.id,
+      name: e.name,
+      content: e.content,
+    }));
+  }
+
+  // ── Embedding ─────────────────────────────────────────────────────────────
+
+  private async embed(text: string): Promise<number[]> {
+    const url = `${this.cfg.embeddingBaseUrl.replace(/\/$/, "")}/embeddings`;
+    const body = JSON.stringify({
+      model: this.cfg.embeddingModel,
+      input: text,
+    });
+
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.cfg.embeddingApiKey}`,
+      },
+      body,
+    });
+
+    if (!resp.ok) {
+      const errText = await resp.text().catch(() => "");
+      throw new Error(`[skill-router] embed failed: ${resp.status} ${errText}`);
+    }
+
+    const json = (await resp.json()) as {
+      data?: Array<{ embedding?: number[] }>;
+    };
+    const embedding = json.data?.[0]?.embedding;
+    if (!Array.isArray(embedding) || embedding.length === 0) {
+      throw new Error("[skill-router] embed: empty embedding returned");
+    }
+    return embedding;
+  }
+
+  // ── COS Vectors HTTP API ──────────────────────────────────────────────────
+
+  /**
+   * PUT (upsert) vectors into COS Vectors.
+   * POST /<endpoint>/PutVectors
+   */
+  private async putVectors(
+    vectors: Array<{
+      key: string;
+      data: { float32: number[] };
+      metadata?: Record<string, unknown>;
+    }>,
+  ): Promise<void> {
+    const body = JSON.stringify({
+      vectorBucketName: this.cfg.vectorBucketName,
+      indexName: this.cfg.indexName,
+      vectors: vectors.map((v) => ({
+        key: v.key,
+        data: { float32: v.data.float32.map((f) => f) },
+        metadata: v.metadata,
+      })),
+    });
+
+    await this.cosRequest("PutVectors", body);
+  }
+
+  /**
+   * Query top-k similar vectors from COS Vectors.
+   * POST /<endpoint>/QueryVectors
+   */
+  private async queryVectors(queryEmbedding: number[], topK: number): Promise<Skill[]> {
+    const body = JSON.stringify({
+      vectorBucketName: this.cfg.vectorBucketName,
+      indexName: this.cfg.indexName,
+      queryVector: { float32: queryEmbedding },
+      topK,
+      returnMetadata: true,
+      returnDistance: true,
+    });
+
+    const resp = await this.cosRequest("QueryVectors", body);
+    const json = resp as {
+      vectors?: Array<{
+        key: string;
+        distance?: number;
+        metadata?: { name?: string; content?: string };
+      }>;
+    };
+
+    if (!json.vectors) return [];
+
+    return json.vectors.map((v) => ({
+      id: v.key,
+      name: v.metadata?.name ?? v.key,
+      content: v.metadata?.content ?? "",
+      // COS Vectors returns L2/IP distance; convert to similarity score (0~1)
+      // For IP (inner product / cosine on normalized vectors): score = distance
+      // For L2: score = 1 / (1 + distance)
+      score: v.distance !== undefined ? this.distanceToScore(v.distance) : undefined,
+    }));
+  }
+
+  /**
+   * Delete vectors by key from COS Vectors.
+   * POST /<endpoint>/DeleteVectors
+   */
+  private async deleteVectors(keys: string[]): Promise<void> {
+    const body = JSON.stringify({
+      vectorBucketName: this.cfg.vectorBucketName,
+      indexName: this.cfg.indexName,
+      keys,
+    });
+
+    await this.cosRequest("DeleteVectors", body);
+  }
+
+  // ── COS Vectors request helper ────────────────────────────────────────────
+
+  private async cosRequest(method: string, body: string): Promise<unknown> {
+    const url = `${this.cfg.proxyEndpoint.replace(/\/$/, "")}/${method}`;
+    const date = new Date().toUTCString();
+
+    // Simple HMAC-SHA1 signature for COS-style auth
+    // Format: q-sign-algorithm=sha1&q-ak=<SecretId>&q-sign-time=<epoch>;<epoch+3600>
+    // For internal/dev use, we support both signed and unsigned modes.
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Date: date,
+    };
+
+    if (this.cfg.secretId && this.cfg.secretKey) {
+      const now = Math.floor(Date.now() / 1000);
+      const expires = now + 3600;
+      const signTime = `${now};${expires}`;
+      const signature = this.buildCosSignature(method, signTime, body);
+      headers["Authorization"] = [
+        "q-sign-algorithm=sha1",
+        `q-ak=${this.cfg.secretId}`,
+        `q-sign-time=${signTime}`,
+        `q-key-time=${signTime}`,
+        `q-header-list=content-type;date`,
+        `q-url-param-list=`,
+        `q-signature=${signature}`,
+      ].join("&");
+    }
+
+    const resp = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+    });
+
+    if (!resp.ok) {
+      const errText = await resp.text().catch(() => "");
+      throw new Error(`[skill-router] COS Vectors ${method} failed: ${resp.status} ${errText}`);
+    }
+
+    // PutVectors / DeleteVectors return empty body on success
+    const text = await resp.text();
+    if (!text.trim()) return {};
+    return JSON.parse(text);
+  }
+
+  /**
+   * Build COS HMAC-SHA1 signature.
+   * Simplified version for internal proxy usage.
+   */
+  private buildCosSignature(method: string, signTime: string, body: string): string {
+    // Step 1: SignKey = HMAC-SHA1(SecretKey, signTime)
+    const signKey = crypto.createHmac("sha1", this.cfg.secretKey).update(signTime).digest("hex");
+
+    // Step 2: HttpString = method\npath\nparams\nheaders\n
+    const path = `/${method}`;
+    const httpString = `post\n${path}\n\ncontent-type=application%2Fjson&date=${encodeURIComponent(new Date().toUTCString())}\n`;
+
+    // Step 3: StringToSign = sha1\nsignTime\nSHA1(HttpString)\n
+    const httpStrHash = crypto.createHash("sha1").update(httpString).digest("hex");
+    const stringToSign = `sha1\n${signTime}\n${httpStrHash}\n`;
+
+    // Step 4: Signature = HMAC-SHA1(SignKey, StringToSign)
+    return crypto.createHmac("sha1", signKey).update(stringToSign).digest("hex");
+  }
+
+  // ── Helpers ───────────────────────────────────────────────────────────────
+
+  /** Convert skill name to a stable vector key */
+  private nameToId(name: string): string {
+    return `skill-${name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "")}`;
+  }
+
+  /**
+   * Convert COS Vectors distance to a 0~1 similarity score.
+   * COS Vectors uses IP (inner product) distance for cosine similarity on normalized vectors.
+   * IP distance = 1 - cosine_similarity, so score = 1 - distance.
+   * For L2 distance: score = 1 / (1 + distance).
+   */
+  private distanceToScore(distance: number): number {
+    // Assume IP distance (cosine on normalized vectors): score = 1 - distance
+    // Clamp to [0, 1]
+    return Math.max(0, Math.min(1, 1 - distance));
+  }
+}