skill-auto-loader-hook-paperfly777 0.1.0

package/README.md

@@ -0,0 +1,191 @@
+# skill-auto-loader-hook
+
+这是一个 OpenClaw 钩子插件，用来在每次用户发送消息时，自动判断是否需要优先使用某个 skill，并把“本轮应优先考虑哪些 skill、适用范围是什么”注入到 prompt 构建阶段。
+
+## 这个插件解决什么问题
+
+适合下面这类需求：
+
+1. 用户一发消息，就自动判断要不要优先走某个 skill。
+2. 不同场景要命中不同 skill。
+3. skill 的“适用范围”需要自定义，而不是全局写死。
+4. 规则应该放在一个单独配置文件里，而不是挤在 `openclaw.json` 里。
+5. 插件要自动读取本地已安装 skill 的 `name` 和 `description`。
+6. 插件要自动读取 `~/.openclaw/openclaw.json` 中的默认模型信息。
+
+例如：
+
+1. 用户提到“知识库、公司规定、查文档”，优先用 `company-knowledge-base`
+2. 用户提到“日报、工时、工作记录”，优先用 `daily-report`
+3. 用户提到“飞书插件、飞书配置”，优先用 `openclaw-feishu-plugin`
+
+## 官方设计依据
+
+根据 OpenClaw 官方插件文档：
+
+1. 原生插件通过 `openclaw.plugin.json` + 运行时模块工作。
+2. 这类“每次消息到来时做动态判断”的需求，最合适的钩子是 `before_prompt_build`。
+3. 该钩子运行时已经拿得到 `messages`，适合做本轮 skill 路由判断。
+
+## 插件目录结构
+
+```text
+skill-auto-loader-hook/
+├── openclaw.plugin.json
+├── index.ts
+├── skill-router.config.json
+└── README.md
+```
+
+## 安装方式
+
+本地开发推荐：
+
+```bash
+openclaw plugins install -l D:/project/openclaw-skill-2/openclaw-skills/plugins/skill-auto-loader-hook
+```
+
+安装后重启 Gateway。
+
+如果你已经发布到 npm，则可以直接安装：
+
+```bash
+openclaw plugins install skill-auto-loader-hook-paperfly777
+```
+
+## 发布方式
+
+发布前先在插件目录执行：
+
+```bash
+npm install
+npm run build
+```
+
+然后登录 npm 并发布：
+
+```bash
+npm login
+npm publish --access public
+```
+
+发布成功后，就可以用：
+
+```bash
+openclaw plugins install @applesay/skill-auto-loader-hook
+```
+
+说明：
+
+1. 当前包名我先给你定成了 `skill-auto-loader-hook-paperfly777`，如果你后面有自己的 npm scope，再改 `package.json` 即可。
+2. `openclaw.plugin.json` 已经指向 `dist/index.js`，所以发布前必须先构建。
+
+## 配置方式
+
+这个插件分两层配置：
+
+1. `openclaw.json` 里只放插件基础入口配置
+2. `skill-router.config.json` 里放独立的技能路由规则
+
+路径说明：
+
+1. `routerConfigPath` 如果写相对路径，则相对于插件目录解析。
+2. `skillsScanDirs` 如果写相对路径，也相对于插件目录解析。
+3. `openclawConfigPath` 建议使用 `~/.openclaw/openclaw.json`。
+
+### 1. `openclaw.json` 中的插件入口配置
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "skill-auto-loader-hook": {
+        "enabled": true,
+        "hooks": {
+          "allowPromptInjection": true
+        },
+        "config": {
+          "enabled": true,
+          "injectMode": "prependContext",
+          "routerConfigPath": "./skill-router.config.json",
+          "openclawConfigPath": "~/.openclaw/openclaw.json"
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. 独立路由配置文件 `skill-router.config.json`
+
+```json
+{
+  "enabled": true,
+  "skillsScanDirs": [
+    "./skills",
+    "./openclaw-skills/skills",
+    "~/.openclaw/workspace/skills"
+  ],
+  "includeSkills": [],
+  "excludeSkills": [],
+  "maxSkillsInPrompt": 20,
+  "defaultScopeNote": "只在当前业务强相关的已安装 skill 范围内做判断，不要为了使用 skill 而使用 skill。",
+  "rules": [
+    {
+      "id": "company-kb",
+      "enabled": true,
+      "description": "公司知识库问答、制度查询、内部文档处理",
+      "keywords": ["知识库", "查文档", "公司规定", "制度", "技术方案"],
+      "preferSkills": ["company-knowledge-base"],
+      "excludeSkills": [],
+      "scopeNote": "仅适用于公司知识库、内部文档、流程制度相关问题。",
+      "prompt": "优先判断是否需要先检索知识库，再决定是否回答或执行文档操作。"
+    }
+  ]
+}
+```
+
+## 运行逻辑
+
+每次用户发消息时：
+
+1. `before_prompt_build` 读取本轮用户消息。
+2. 自动读取 `skill-router.config.json`。
+3. 自动扫描本地已安装的 skill，提取 `SKILL.md` 里的 `name` 和 `description`。
+4. 自动读取 `~/.openclaw/openclaw.json`，拿到当前默认模型信息。
+5. 用自定义规则先做范围收缩。
+6. 把“用户消息 + 候选 skills + 规则提示 + 默认模型”一起注入当前轮 prompt。
+7. 再由当前默认大模型判断：本轮是否需要 skill、优先用哪个 skill。
+
+## 这个插件和大模型的关系
+
+这个插件不是自己在本地写死判断逻辑，而是：
+
+1. 插件负责收集上下文
+2. 插件负责收窄可选 skill 范围
+3. 最终由当前默认大模型完成本轮 skill 路由判断
+
+这样后面你增加新 skill，不需要改核心判断逻辑，只要：
+
+1. skill 已安装
+2. skill 有 `name` 和 `description`
+3. 在独立配置文件里补规则
+
+## 重要边界
+
+这个插件做的是“动态路由和提示注入”，不是“运行时热安装 skill”。
+
+也就是说：
+
+1. 它可以引导 OpenClaw 本轮优先考虑哪些已安装 skill。
+2. 它不能替代 skill 本身的安装和发现机制。
+3. 所有要被路由的 skill，仍然需要先安装到 OpenClaw 可发现的位置。
+4. 它当前做的是“把 skill 判断交给默认模型”，不是在插件里直接调用第二个独立模型 API。
+
+## 推荐下一步
+
+如果你准备把它真正用到你的项目里，下一步最值得做的是：
+
+1. 先把 `company-knowledge-base`、`daily-report`、`openclaw-feishu-plugin` 三个规则配起来。
+2. 再补一个“电商虾 skill 路由规则集”。
+3. 最后再加一个后台管理页或配置文件生成器，避免手改 `skill-router.config.json`。

package/dist/index.js

@@ -0,0 +1,346 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const PLUGIN_ID = "skill-auto-loader-hook";
+function safeString(value) {
+    return typeof value === "string" ? value : "";
+}
+function expandHome(inputPath) {
+    if (!inputPath) {
+        return inputPath;
+    }
+    if (inputPath.startsWith("~/")) {
+        return path.join(os.homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+}
+function resolvePath(inputPath, baseDir) {
+    const expanded = expandHome(inputPath);
+    if (!expanded) {
+        return expanded;
+    }
+    if (path.isAbsolute(expanded)) {
+        return expanded;
+    }
+    return path.resolve(baseDir, expanded);
+}
+function readJsonFile(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function extractTextFromContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        return content
+            .map((item) => {
+            if (typeof item === "string") {
+                return item;
+            }
+            if (item && typeof item === "object") {
+                const obj = item;
+                if (typeof obj.text === "string") {
+                    return obj.text;
+                }
+                if (typeof obj.input === "string") {
+                    return obj.input;
+                }
+            }
+            return "";
+        })
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+function extractLatestUserText(event) {
+    if (!event || typeof event !== "object") {
+        return "";
+    }
+    const eventObj = event;
+    const messages = Array.isArray(eventObj.messages) ? eventObj.messages : [];
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        if (!msg || typeof msg !== "object") {
+            continue;
+        }
+        const msgObj = msg;
+        if (safeString(msgObj.role) !== "user") {
+            continue;
+        }
+        const content = extractTextFromContent(msgObj.content);
+        if (content.trim()) {
+            return content.trim();
+        }
+    }
+    const fallbackPrompt = safeString(eventObj.userPrompt);
+    return fallbackPrompt.trim();
+}
+function normalizePluginConfig(api) {
+    const pluginCfg = api?.config?.plugins?.entries?.[PLUGIN_ID]?.config ??
+        api?.config?.plugins?.entries?.[PLUGIN_ID] ??
+        {};
+    return {
+        enabled: pluginCfg.enabled !== false,
+        injectMode: pluginCfg.injectMode || "prependContext",
+        routerConfigPath: safeString(pluginCfg.routerConfigPath) ||
+            path.join(__dirname, "skill-router.config.json"),
+        openclawConfigPath: safeString(pluginCfg.openclawConfigPath) ||
+            path.join(os.homedir(), ".openclaw", "openclaw.json"),
+    };
+}
+function readRouterConfig(configPath, baseDir) {
+    const config = readJsonFile(resolvePath(configPath, baseDir));
+    if (!config || typeof config !== "object") {
+        return {};
+    }
+    return config;
+}
+function getDefaultModelInfo(openclawConfigPath) {
+    const cfg = readJsonFile(expandHome(openclawConfigPath));
+    if (!cfg || typeof cfg !== "object") {
+        return "未读取到 OpenClaw 默认模型配置";
+    }
+    const root = cfg;
+    const directModel = safeString(root.model);
+    const channelsModel = safeString(root.channels?.model);
+    if (directModel) {
+        return directModel;
+    }
+    if (channelsModel) {
+        return channelsModel;
+    }
+    return "openclaw.json 中未显式配置默认模型";
+}
+function parseYamlLikeFrontmatter(raw) {
+    const result = { name: "", description: "" };
+    if (!raw.startsWith("---")) {
+        return result;
+    }
+    const endIndex = raw.indexOf("\n---", 3);
+    if (endIndex === -1) {
+        return result;
+    }
+    const frontmatter = raw.slice(3, endIndex).split(/\r?\n/);
+    let inDescription = false;
+    const descriptionLines = [];
+    for (const line of frontmatter) {
+        if (line.startsWith("name:")) {
+            result.name = line.slice(5).trim();
+            inDescription = false;
+            continue;
+        }
+        if (line.startsWith("description:")) {
+            const remainder = line.slice("description:".length).trim();
+            inDescription = true;
+            if (remainder && remainder !== "|") {
+                descriptionLines.push(remainder);
+                inDescription = false;
+            }
+            continue;
+        }
+        if (inDescription) {
+            if (/^\S/.test(line)) {
+                inDescription = false;
+            }
+            else {
+                descriptionLines.push(line.trim());
+            }
+        }
+    }
+    result.description = descriptionLines.join(" ").trim();
+    return result;
+}
+function extractHeadingFallback(raw) {
+    const lines = raw.split(/\r?\n/);
+    for (const line of lines) {
+        if (line.startsWith("# ")) {
+            return line.slice(2).trim();
+        }
+    }
+    return "";
+}
+function extractSkillMeta(skillDir) {
+    const skillMdPath = path.join(skillDir, "SKILL.md");
+    if (!fs.existsSync(skillMdPath)) {
+        return null;
+    }
+    const raw = fs.readFileSync(skillMdPath, "utf8");
+    const fm = parseYamlLikeFrontmatter(raw);
+    const name = fm.name || path.basename(skillDir);
+    const description = fm.description || extractHeadingFallback(raw) || "无描述";
+    return {
+        name,
+        description,
+        skillPath: skillDir,
+    };
+}
+function scanInstalledSkills(scanDirs) {
+    const results = [];
+    const visited = new Set();
+    for (const dir of scanDirs) {
+        const resolved = expandHome(dir);
+        if (!resolved || !fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+            continue;
+        }
+        const entries = fs.readdirSync(resolved, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const fullPath = path.join(resolved, entry.name);
+            if (visited.has(fullPath)) {
+                continue;
+            }
+            const meta = extractSkillMeta(fullPath);
+            if (meta) {
+                visited.add(fullPath);
+                results.push(meta);
+            }
+        }
+    }
+    return results.sort((a, b) => a.name.localeCompare(b.name));
+}
+function matchesRule(text, rule) {
+    const normalized = text.toLowerCase();
+    const keywords = Array.isArray(rule.keywords) ? rule.keywords : [];
+    const allKeywords = Array.isArray(rule.allKeywords) ? rule.allKeywords : [];
+    const regexes = Array.isArray(rule.regexes) ? rule.regexes : [];
+    const anyKeywordMatched = keywords.length === 0 ||
+        keywords.some((keyword) => normalized.includes(keyword.toLowerCase()));
+    const allKeywordMatched = allKeywords.length === 0 ||
+        allKeywords.every((keyword) => normalized.includes(keyword.toLowerCase()));
+    const regexMatched = regexes.length === 0 ||
+        regexes.some((pattern) => {
+            try {
+                return new RegExp(pattern, "i").test(text);
+            }
+            catch {
+                return false;
+            }
+        });
+    const hasMatcher = keywords.length > 0 || allKeywords.length > 0 || regexes.length > 0;
+    return hasMatcher && anyKeywordMatched && allKeywordMatched && regexMatched;
+}
+function applyRuleFiltering(skills, routerCfg, matchedRules) {
+    let filtered = [...skills];
+    const includeSkills = new Set((routerCfg.includeSkills || []).filter(Boolean));
+    const excludeSkills = new Set((routerCfg.excludeSkills || []).filter(Boolean));
+    if (includeSkills.size > 0) {
+        filtered = filtered.filter((skill) => includeSkills.has(skill.name));
+    }
+    if (excludeSkills.size > 0) {
+        filtered = filtered.filter((skill) => !excludeSkills.has(skill.name));
+    }
+    const preferred = new Set();
+    const excludedByRule = new Set();
+    for (const rule of matchedRules) {
+        (rule.preferSkills || []).forEach((name) => preferred.add(name));
+        (rule.excludeSkills || []).forEach((name) => excludedByRule.add(name));
+    }
+    filtered = filtered.filter((skill) => !excludedByRule.has(skill.name));
+    if (preferred.size > 0) {
+        const preferredSkills = filtered.filter((skill) => preferred.has(skill.name));
+        const remainingSkills = filtered.filter((skill) => !preferred.has(skill.name));
+        filtered = [...preferredSkills, ...remainingSkills];
+    }
+    const maxSkills = routerCfg.maxSkillsInPrompt && routerCfg.maxSkillsInPrompt > 0 ? routerCfg.maxSkillsInPrompt : 20;
+    return filtered.slice(0, maxSkills);
+}
+function renderSkillList(skills) {
+    if (skills.length === 0) {
+        return "当前未扫描到可用 skill。";
+    }
+    return skills
+        .map((skill, index) => `${index + 1}. ${skill.name}\n说明：${skill.description}\n路径：${skill.skillPath}`)
+        .join("\n\n");
+}
+function renderRuleHints(matchedRules, routerCfg) {
+    if (matchedRules.length === 0) {
+        return routerCfg.defaultScopeNote ? `默认范围提示：${routerCfg.defaultScopeNote}` : "未命中任何自定义规则。";
+    }
+    return matchedRules
+        .map((rule, index) => {
+        const lines = [];
+        lines.push(`${index + 1}. 规则ID：${rule.id}`);
+        if (rule.description) {
+            lines.push(`描述：${rule.description}`);
+        }
+        if ((rule.preferSkills || []).length > 0) {
+            lines.push(`优先技能：${rule.preferSkills.join("、")}`);
+        }
+        if ((rule.excludeSkills || []).length > 0) {
+            lines.push(`排除技能：${rule.excludeSkills.join("、")}`);
+        }
+        if (rule.scopeNote) {
+            lines.push(`适用范围：${rule.scopeNote}`);
+        }
+        if (rule.prompt) {
+            lines.push(`提示：${rule.prompt}`);
+        }
+        return lines.join("\n");
+    })
+        .join("\n\n");
+}
+function buildRoutingPrompt(userText, defaultModel, scannedSkills, matchedRules, routerCfg) {
+    const lines = [];
+    lines.push("【Skill Auto Loader Hook】请在正式回答前，先完成本轮 skill 路由判断。");
+    lines.push(`当前 OpenClaw 默认模型：${defaultModel}`);
+    lines.push(`本轮用户消息：${userText}`);
+    lines.push("");
+    lines.push("请结合以下信息判断本轮是否需要优先使用某个 skill。");
+    lines.push("");
+    lines.push("一、当前可用 skill 列表");
+    lines.push(renderSkillList(scannedSkills));
+    lines.push("");
+    lines.push("二、本轮命中的自定义规则");
+    lines.push(renderRuleHints(matchedRules, routerCfg));
+    lines.push("");
+    lines.push("三、判断要求");
+    lines.push("1. 先判断本轮是否明显需要 skill。");
+    lines.push("2. 如果需要，只选择最相关的 1-3 个 skill 作为优先候选。");
+    lines.push("3. 若没有合适 skill，就按常规对话处理，不要强行套 skill。");
+    lines.push("4. 不要使用被规则排除的 skill。");
+    lines.push("5. 你的判断依据必须来自：用户消息、skill 描述、自定义 scope。");
+    lines.push("");
+    lines.push("四、执行方式");
+    lines.push("请把路由判断体现在你后续的实际执行中：若需要 skill，则优先按判断结果使用；若不需要，则正常回答。");
+    return lines.join("\n");
+}
+export default function register(api) {
+    api.on("before_prompt_build", (event) => {
+        const cfg = normalizePluginConfig(api);
+        if (!cfg.enabled) {
+            return undefined;
+        }
+        const routerCfg = readRouterConfig(cfg.routerConfigPath, __dirname);
+        if (routerCfg.enabled === false) {
+            return undefined;
+        }
+        const userText = extractLatestUserText(event);
+        if (!userText) {
+            return undefined;
+        }
+        const scanDirs = Array.isArray(routerCfg.skillsScanDirs) && routerCfg.skillsScanDirs.length > 0
+            ? routerCfg.skillsScanDirs.map((dir) => resolvePath(dir, __dirname))
+            : [path.join(process.cwd(), "skills"), path.join(process.cwd(), "openclaw-skills", "skills")];
+        const allSkills = scanInstalledSkills(scanDirs);
+        const matchedRules = (routerCfg.rules || []).filter((rule) => rule.enabled !== false && matchesRule(userText, rule));
+        const candidateSkills = applyRuleFiltering(allSkills, routerCfg, matchedRules);
+        const defaultModel = getDefaultModelInfo(cfg.openclawConfigPath);
+        const payload = buildRoutingPrompt(userText, defaultModel, candidateSkills, matchedRules, routerCfg);
+        if (cfg.injectMode === "prependSystemContext") {
+            return { prependSystemContext: payload };
+        }
+        if (cfg.injectMode === "appendSystemContext") {
+            return { appendSystemContext: payload };
+        }
+        return { prependContext: payload };
+    }, { priority: 50 });
+}

package/openclaw.plugin.json

@@ -0,0 +1,47 @@
+{
+  "id": "skill-auto-loader-hook",
+  "name": "Skill Auto Loader Hook",
+  "description": "Intercept each user turn, match custom routing rules, and inject skill selection guidance into prompt build.",
+  "version": "0.1.0",
+  "entry": "./dist/index.js",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "injectMode": {
+        "type": "string",
+        "enum": [
+          "prependContext",
+          "prependSystemContext",
+          "appendSystemContext"
+        ],
+        "default": "prependContext"
+      },
+      "routerConfigPath": {
+        "type": "string",
+        "default": "./skill-router.config.json"
+      },
+      "openclawConfigPath": {
+        "type": "string"
+      }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "启用自动 Skill 路由"
+    },
+    "injectMode": {
+      "label": "Prompt 注入位置"
+    },
+    "routerConfigPath": {
+      "label": "独立路由配置文件路径"
+    },
+    "openclawConfigPath": {
+      "label": "OpenClaw 配置文件路径"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "skill-auto-loader-hook-paperfly777",
+  "version": "0.1.0",
+  "description": "OpenClaw hook plugin that routes each user message to the most relevant installed skill.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "skill-router.config.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "hook",
+    "skill",
+    "router"
+  ]
+}

package/skill-router.config.json

@@ -0,0 +1,34 @@
+{
+  "enabled": true,
+  "skillsScanDirs": [
+    "./skills",
+    "./openclaw-skills/skills",
+    "~/.openclaw/workspace/skills"
+  ],
+  "includeSkills": [],
+  "excludeSkills": [],
+  "maxSkillsInPrompt": 20,
+  "defaultScopeNote": "只在当前业务强相关的已安装 skill 范围内做判断，不要为了使用 skill 而使用 skill。",
+  "rules": [
+    {
+      "id": "company-kb",
+      "enabled": true,
+      "description": "公司知识库问答、制度查询、内部文档处理",
+      "keywords": ["知识库", "查文档", "公司规定", "制度", "技术方案"],
+      "preferSkills": ["company-knowledge-base"],
+      "excludeSkills": [],
+      "scopeNote": "仅适用于公司知识库、内部文档、流程制度相关问题。",
+      "prompt": "优先判断是否需要先检索知识库，再决定是否回答或执行文档操作。"
+    },
+    {
+      "id": "daily-report",
+      "enabled": true,
+      "description": "日报生成、草稿整理、上传提交",
+      "keywords": ["日报", "工时", "工作记录", "提交日报"],
+      "preferSkills": ["daily-report"],
+      "excludeSkills": ["company-knowledge-base"],
+      "scopeNote": "仅适用于日报草稿生成、日报上传、日报修订场景。",
+      "prompt": "先判断是需要生成新草稿，还是基于已有文件进行上传。"
+    }
+  ]
+}