skill-auto-loader-hook-paperfly777 0.1.2 → 0.1.3

package/README.md

@@ -86,6 +86,148 @@ openclaw plugins install skill-auto-loader-hook-paperfly777
 2. `skillsScanDirs` 如果写相对路径，也相对于插件目录解析。
 3. `openclawConfigPath` 建议使用 `~/.openclaw/openclaw.json`。
 
+## 使用说明（重点）
+
+### 1) 怎么使用
+
+1. 安装插件后，确保 `plugins.entries.skill-auto-loader-hook.enabled=true`。
+2. 配置好 `routerConfigPath` 指向 `skill-router.config.json`。
+3. 重启 gateway：`openclaw gateway restart`。
+4. 之后每次用户发消息，插件会在 `before_prompt_build` 自动执行 skill 路由判断。
+
+### 2) 配置文件在哪里
+
+- OpenClaw 主配置：`~/.openclaw/openclaw.json`
+- 插件路由配置：`skill-router.config.json`（默认按插件目录相对路径读取）
+
+### 3) 自定义 Prompt 怎么配
+
+在 `skill-router.config.json` 的每条 `rules[*].prompt` 里写即可，例如：
+
+```json
+{
+  "id": "company-kb",
+  "keywords": ["知识库", "查文档", "公司规定"],
+  "preferSkills": ["company-knowledge-base"],
+  "excludeSkills": [],
+  "scopeNote": "仅限内部文档检索与制度问题",
+  "prompt": "先检索知识库再回答；若涉及删除/覆盖写入，必须二次确认。"
+}
+```
+
+推荐写法：
+
+1. 先写使用范围（`scopeNote`）
+2. 再写执行约束（`prompt`）
+3. 避免只写关键词，不写动作规则
+
+### 4) 白名单和黑名单怎么配
+
+- 全局白名单：`includeSkills`
+- 全局黑名单：`excludeSkills`
+- 规则级白名单倾向：`rules[*].preferSkills`
+- 规则级黑名单：`rules[*].excludeSkills`
+
+示例：
+
+```json
+{
+  "includeSkills": ["company-knowledge-base", "daily-report", "openclaw-feishu-plugin"],
+  "excludeSkills": ["remotion"],
+  "rules": [
+    {
+      "id": "daily-report",
+      "keywords": ["日报", "工时", "工作记录"],
+      "preferSkills": ["daily-report"],
+      "excludeSkills": ["company-knowledge-base"],
+      "prompt": "优先处理日报，不要误路由到知识库。"
+    }
+  ]
+}
+```
+
+说明：
+
+1. `includeSkills` 不为空时，候选技能会先被限制在白名单内。
+2. `excludeSkills` 会在全局层面直接排除。
+3. 规则命中后会叠加 `preferSkills/excludeSkills` 做本轮精细路由。
+
+## 参数说明（完整）
+
+### A. `openclaw.json -> plugins.entries.skill-auto-loader-hook`
+
+| 参数 | 类型 | 可选值/示例 | 默认值 | 作用 |
+|---|---|---|---|---|
+| `enabled` | boolean | `true/false` | `true` | 是否启用这个插件入口。 |
+| `config.enabled` | boolean | `true/false` | `true` | 插件运行时开关。关闭后插件不做任何注入。 |
+| `config.injectMode` | string | `prependContext` / `prependSystemContext` / `appendSystemContext` | `prependContext` | 选择把路由提示注入到哪里。 |
+| `config.routerConfigPath` | string | `./skill-router.config.json` | `./skill-router.config.json` | 独立路由配置文件路径。相对路径按插件目录解析。 |
+| `config.openclawConfigPath` | string | `~/.openclaw/openclaw.json` | `~/.openclaw/openclaw.json` | 读取默认模型信息的配置文件路径。 |
+
+`injectMode` 选择建议：
+
+1. `prependContext`：推荐。影响最小，兼容性最好。
+2. `prependSystemContext`：约束最强，适合必须遵守路由的场景。
+3. `appendSystemContext`：权重相对弱，适合补充说明。
+
+`injectMode` 详细解释（这三个参数到底什么意思）：
+
+1. `prependContext`
+   - 含义：把插件生成的路由提示，放到“普通上下文”的前面。
+   - 特点：不会强压系统提示，兼容性最好，不容易和其他系统规则冲突。
+   - 适合：大多数场景，尤其是你只希望“引导模型优先用某些 skill”。
+
+2. `prependSystemContext`
+   - 含义：把路由提示放到“系统上下文”最前面。
+   - 特点：约束力最强，模型更容易优先执行这段规则。
+   - 风险：如果规则写得太死，可能压过原有系统策略，导致回答风格变硬。
+   - 适合：强流程场景（例如必须先知识库检索、必须二次确认写操作）。
+
+3. `appendSystemContext`
+   - 含义：把路由提示放到“系统上下文”末尾。
+   - 特点：仍在系统层，但通常权重低于前置系统上下文。
+   - 适合：你想补充一层路由提醒，但不想强覆盖原系统策略时使用。
+
+### B. `skill-router.config.json` 顶层参数
+
+| 参数 | 类型 | 可选值/示例 | 默认值 | 作用 |
+|---|---|---|---|---|
+| `enabled` | boolean | `true/false` | `true` | 路由配置总开关。 |
+| `defaultBehavior` | string | `no-op` / `advisory` | `no-op` | 未命中规则时是否注入提示。 |
+| `skillsScanDirs` | string[] | `["~/.openclaw/workspace/skills"]` | 自动推断目录 | 扫描已安装 skill 的目录列表。 |
+| `includeSkills` | string[] | `["company-knowledge-base"]` | `[]` | 全局白名单。非空时仅这些 skill 参与候选。 |
+| `excludeSkills` | string[] | `["remotion"]` | `[]` | 全局黑名单。始终排除这些 skill。 |
+| `maxSkillsInPrompt` | number | `10` / `20` | `20` | 注入提示中最多携带多少个候选 skill。 |
+| `defaultScopeNote` | string | `"仅限公司知识库场景"` | 空 | 规则缺少 `scopeNote` 时的默认范围说明。 |
+| `rules` | array | 见下方规则参数 | `[]` | 场景路由规则集合。 |
+
+`defaultBehavior` 选择建议：
+
+1. `no-op`：推荐。未命中规则就不注入，避免“每轮追加”。
+2. `advisory`：未命中也注入轻量提示，适合想保留弱引导的场景。
+
+### C. `rules[*]` 规则参数
+
+| 参数 | 类型 | 可选值/示例 | 是否必填 | 作用 |
+|---|---|---|---|---|
+| `id` | string | `"daily-report"` | 是 | 规则唯一标识，便于日志排障。 |
+| `enabled` | boolean | `true/false` | 否 | 单条规则开关。 |
+| `description` | string | `"日报相关路由"` | 否 | 规则说明文字。 |
+| `keywords` | string[] | `["日报","工时"]` | 否 | 任意关键词命中即可。 |
+| `allKeywords` | string[] | `["报销","流程"]` | 否 | 要求全部命中。 |
+| `regexes` | string[] | `["(?i)日报.*提交"]` | 否 | 正则命中条件。 |
+| `preferSkills` | string[] | `["daily-report"]` | 否 | 命中后优先的 skill。 |
+| `excludeSkills` | string[] | `["company-knowledge-base"]` | 否 | 命中后排除的 skill。 |
+| `scopeNote` | string | `"仅日报场景"` | 否 | 这条规则的适用范围说明。 |
+| `prompt` | string | `"先确认草稿再上传"` | 否 | 规则级自定义提示词。 |
+
+规则命中逻辑（重要）：
+
+1. `keywords`：满足“任意一个”即可。
+2. `allKeywords`：要求“全部”出现。
+3. `regexes`：任意一个正则匹配即可。
+4. 三类条件会组合判断，最终命中后才进入 `preferSkills/excludeSkills` 处理。
+
 ### 1. `openclaw.json` 中的插件入口配置
 
 ```json

package/index.ts

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { definePluginEntry } from "openclaw/plugin-sdk/core";
 
+// 插件固定 ID：对应 openclaw.json 里的 plugins.entries.<id>
 const PLUGIN_ID = "skill-auto-loader-hook";
 
 type RoutingRule = {
@@ -20,6 +21,7 @@ type RoutingRule = {
 
 type RouterFileConfig = {
   enabled?: boolean;
+  defaultBehavior?: "no-op" | "advisory";
   skillsScanDirs?: string[];
   includeSkills?: string[];
   excludeSkills?: string[];
@@ -41,10 +43,12 @@ type SkillMeta = {
   skillPath: string;
 };
 
+// 工具函数：把任意输入安全转换为字符串
 function safeString(value: unknown): string {
   return typeof value === "string" ? value : "";
 }
 
+// 工具函数：把 "~/" 展开为用户 home 目录绝对路径
 function expandHome(inputPath: string): string {
   if (!inputPath) {
     return inputPath;
@@ -55,6 +59,7 @@ function expandHome(inputPath: string): string {
   return inputPath;
 }
 
+// 工具函数：把相对路径解析为基于 baseDir 的绝对路径
 function resolvePath(inputPath: string, baseDir: string): string {
   const expanded = expandHome(inputPath);
   if (!expanded) {
@@ -66,6 +71,7 @@ function resolvePath(inputPath: string, baseDir: string): string {
   return path.resolve(baseDir, expanded);
 }
 
+// 安全读取 JSON：文件不存在或格式错误时返回 null，不抛异常
 function readJsonFile(filePath: string): any {
   try {
     const raw = fs.readFileSync(filePath, "utf8");
@@ -75,6 +81,7 @@ function readJsonFile(filePath: string): any {
   }
 }
 
+// 从 OpenClaw 消息 content 结构中抽取纯文本
 function extractTextFromContent(content: unknown): string {
   if (typeof content === "string") {
     return content;
@@ -102,6 +109,7 @@ function extractTextFromContent(content: unknown): string {
   return "";
 }
 
+// 提取“最后一条用户消息”作为本轮路由判断输入
 function extractLatestUserText(event: unknown): string {
   if (!event || typeof event !== "object") {
     return "";
@@ -128,6 +136,7 @@ function extractLatestUserText(event: unknown): string {
   return fallbackPrompt.trim();
 }
 
+// 从 openclaw.json 读取插件级配置（plugins.entries.<id>.config）
 function normalizePluginConfig(api: any): PluginConfig {
   const pluginCfg =
     api?.config?.plugins?.entries?.[PLUGIN_ID]?.config ??
@@ -146,6 +155,7 @@ function normalizePluginConfig(api: any): PluginConfig {
   };
 }
 
+// 从独立配置文件读取路由规则（skill-router.config.json）
 function readRouterConfig(configPath: string, baseDir: string): RouterFileConfig {
   const config = readJsonFile(resolvePath(configPath, baseDir));
   if (!config || typeof config !== "object") {
@@ -154,6 +164,7 @@ function readRouterConfig(configPath: string, baseDir: string): RouterFileConfig
   return config as RouterFileConfig;
 }
 
+// 从 openclaw.json 读取默认模型信息，用于注入上下文
 function getDefaultModelInfo(openclawConfigPath: string): string {
   const cfg = readJsonFile(expandHome(openclawConfigPath));
   if (!cfg || typeof cfg !== "object") {
@@ -173,6 +184,7 @@ function getDefaultModelInfo(openclawConfigPath: string): string {
   return "openclaw.json 中未显式配置默认模型";
 }
 
+// 解析 SKILL.md 头部 frontmatter（name/description）
 function parseYamlLikeFrontmatter(raw: string): { name: string; description: string } {
   const result = { name: "", description: "" };
   if (!raw.startsWith("---")) {
@@ -216,6 +228,7 @@ function parseYamlLikeFrontmatter(raw: string): { name: string; description: str
   return result;
 }
 
+// frontmatter 缺失时，退化为读取 markdown 一级标题作为名称
 function extractHeadingFallback(raw: string): string {
   const lines = raw.split(/\r?\n/);
   for (const line of lines) {
@@ -226,6 +239,7 @@ function extractHeadingFallback(raw: string): string {
   return "";
 }
 
+// 从一个 skill 目录提取技能元信息
 function extractSkillMeta(skillDir: string): SkillMeta | null {
   const skillMdPath = path.join(skillDir, "SKILL.md");
   if (!fs.existsSync(skillMdPath)) {
@@ -244,6 +258,7 @@ function extractSkillMeta(skillDir: string): SkillMeta | null {
   };
 }
 
+// 扫描配置的技能目录，收集“已安装 skill”列表
 function scanInstalledSkills(scanDirs: string[]): SkillMeta[] {
   const results: SkillMeta[] = [];
   const visited = new Set<string>();
@@ -274,6 +289,7 @@ function scanInstalledSkills(scanDirs: string[]): SkillMeta[] {
   return results.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// 规则匹配器：支持 keywords / allKeywords / regexes
 function matchesRule(text: string, rule: RoutingRule): boolean {
   const normalized = text.toLowerCase();
   const keywords = Array.isArray(rule.keywords) ? rule.keywords : [];
@@ -302,6 +318,7 @@ function matchesRule(text: string, rule: RoutingRule): boolean {
   return hasMatcher && anyKeywordMatched && allKeywordMatched && regexMatched;
 }
 
+// 先应用全局白名单/黑名单，再应用规则级偏好与排除
 function applyRuleFiltering(skills: SkillMeta[], routerCfg: RouterFileConfig, matchedRules: RoutingRule[]): SkillMeta[] {
   let filtered = [...skills];
 
@@ -334,15 +351,15 @@ function applyRuleFiltering(skills: SkillMeta[], routerCfg: RouterFileConfig, ma
   return filtered.slice(0, maxSkills);
 }
 
+// 生成精简版技能列表，避免注入内容过长
 function renderSkillList(skills: SkillMeta[]): string {
   if (skills.length === 0) {
     return "当前未扫描到可用 skill。";
   }
-  return skills
-    .map((skill, index) => `${index + 1}. ${skill.name}\n说明：${skill.description}\n路径：${skill.skillPath}`)
-    .join("\n\n");
+  return skills.map((skill, index) => `${index + 1}. ${skill.name}（${skill.description.slice(0, 80)}）`).join("\n");
 }
 
+// 渲染命中规则说明，供模型做本轮技能路由判断
 function renderRuleHints(matchedRules: RoutingRule[], routerCfg: RouterFileConfig): string {
   if (matchedRules.length === 0) {
     return routerCfg.defaultScopeNote ? `默认范围提示：${routerCfg.defaultScopeNote}` : "未命中任何自定义规则。";
@@ -372,6 +389,7 @@ function renderRuleHints(matchedRules: RoutingRule[], routerCfg: RouterFileConfi
     .join("\n\n");
 }
 
+// 构造最终注入 payload（用于 before_prompt_build）
 function buildRoutingPrompt(
   userText: string,
   defaultModel: string,
@@ -386,7 +404,7 @@ function buildRoutingPrompt(
   lines.push("");
   lines.push("请结合以下信息判断本轮是否需要优先使用某个 skill。");
   lines.push("");
-  lines.push("一、当前可用 skill 列表");
+  lines.push("一、候选 skill（已过滤）");
   lines.push(renderSkillList(scannedSkills));
   lines.push("");
   lines.push("二、本轮命中的自定义规则");
@@ -413,6 +431,7 @@ export default definePluginEntry({
     api.on(
       "before_prompt_build",
       (event: unknown) => {
+        // 步骤 1：读取插件配置与独立路由配置
         const cfg = normalizePluginConfig(api);
         if (!cfg.enabled) {
           return undefined;
@@ -423,11 +442,13 @@ export default definePluginEntry({
           return undefined;
         }
 
+        // 步骤 2：提取本轮用户输入
         const userText = extractLatestUserText(event);
         if (!userText) {
           return undefined;
         }
 
+        // 步骤 3：扫描并收集可用 skill
         const scanDirs =
           Array.isArray(routerCfg.skillsScanDirs) && routerCfg.skillsScanDirs.length > 0
             ? routerCfg.skillsScanDirs.map((dir) => resolvePath(dir, __dirname))
@@ -435,6 +456,12 @@ export default definePluginEntry({
 
         const allSkills = scanInstalledSkills(scanDirs);
         const matchedRules = (routerCfg.rules || []).filter((rule) => rule.enabled !== false && matchesRule(userText, rule));
+        const defaultBehavior = routerCfg.defaultBehavior || "no-op";
+        // 步骤 4：默认 no-op 时，未命中规则就不注入（避免每轮追加）
+        if (matchedRules.length === 0 && defaultBehavior === "no-op") {
+          return undefined;
+        }
+        // 步骤 5：过滤候选 skill，并构造注入内容
         const candidateSkills = applyRuleFiltering(allSkills, routerCfg, matchedRules);
         const defaultModel = getDefaultModelInfo(cfg.openclawConfigPath!);
         const payload = buildRoutingPrompt(userText, defaultModel, candidateSkills, matchedRules, routerCfg);
@@ -443,12 +470,18 @@ export default definePluginEntry({
           `skill-auto-loader-hook: before_prompt_build matchedRules=${matchedRules.length} candidateSkills=${candidateSkills.length}`,
         );
 
+        // injectMode = prependSystemContext:
+        // 注入到系统上下文最前面，约束最强，优先级通常最高。
         if (cfg.injectMode === "prependSystemContext") {
           return { prependSystemContext: payload };
         }
+        // injectMode = appendSystemContext:
+        // 注入到系统上下文末尾，仍属于系统层，但权重通常弱于前置系统上下文。
         if (cfg.injectMode === "appendSystemContext") {
           return { appendSystemContext: payload };
         }
+        // injectMode = prependContext（默认）:
+        // 注入到普通上下文前部，影响适中，兼容性最好，推荐默认使用。
         return { prependContext: payload };
       },
       { priority: 50 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-auto-loader-hook-paperfly777",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "OpenClaw hook plugin that routes each user message to the most relevant installed skill.",
   "license": "MIT",
   "type": "module",

package/skill-router.config.json

@@ -1,5 +1,6 @@
 {
   "enabled": true,
+  "defaultBehavior": "no-op",
   "skillsScanDirs": [
     "./skills",
     "./openclaw-skills/skills",