@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Agent/SkillSelector/README.md

@@ -0,0 +1,344 @@
+# SkillSelector — SKILL 选择器 ReAct Agent
+
+根据一个具体事项（任务）和 SKILL 筛选目录，自动选出最适合的 SKILL。
+
+采用 **ReAct（Reason + Act）** 设计模式，通过 LLM 推理 + 双通道 BM25 模糊匹配的三步编排完成选择。
+
+## 职责
+
+在给定 SKILL 筛选目录下，根据一个具体事项（任务），选出最适合的 SKILL。
+
+采用 **ReAct（Reason + Act）** 设计模式，分三步完成：
+
+1. **Reason #1 — 任务拆解**：LLM（百炼 / glm-5-1）分析任务，产出 `keywords / intent / constraints / techStack / whenToUse`，作为模糊匹配的输入。prompt 强制保留"准出审核/验收测试"等动作类型词，避免被技术细节淹没。
+2. **Act — 模糊匹配**：本地模糊匹配工具根据上一步输出，采用**双通道多路召回融合**（动作通道 + 领域通道 + 原文兜底通道），在候选 SKILL 池中召回最匹配的 topK。SKILL 文档索引 = metadata×3 + 正文前 2500 字符 + useWhen。
+3. **Reason #2 — 排序筛选**：LLM 对 topK 候选 SKILL 评分排序，选出最佳 SKILL。
+
+## 架构
+
+```mermaid
+flowchart TD
+    Input["输入: task + skillDirectory"]
+    Input --> Scan["skillScanner 扫描目录"]
+    Scan -->|SkillMeta[]| R1
+
+    subgraph R1["Reason #1 — 任务拆解"]
+        R1a["llmClient 调用 glm-5-1"]
+        R1b["输出 TaskAnalysis: keywords / intent / constraints / techStack / whenToUse"]
+        R1a --> R1b
+    end
+
+    R1 --> Act["Act — fuzzyMatch 双通道多路召回融合"]
+    Scan --> Act
+    Act -->|"动作路 + 领域路 + 原文路融合"| TopK["topK 候选 SKILL"]
+    TopK --> R2
+
+    subgraph R2["Reason #2 — 排序筛选"]
+        R2a["llmClient 调用 glm-5-1"]
+        R2b["输出 ranked: 每项含 score + reason"]
+        R2a --> R2b
+    end
+
+    R2 --> Output["返回 SkillSelection: best + ranked + analysis + trace"]
+```
+
+## 目录结构
+
+```
+SkillSelector/
+├── index.js              # 模块统一导出
+├── types.js              # 数据结构 JSDoc 契约（本地保留，不提交远端，已加入 .gitignore）
+├── core/
+│   └── Agent.js          # 对外导出的 Agent 类，selectSkill(task, skillDirectory) 主入口
+├── llm/
+│   ├── llmClient.js      # LLM 客户端（百炼 OpenAI 兼容，glm-5-1），提供 chat() / chatJSON()
+│   ├── prompts.js        # prompt 模板 + renderTemplate（TASK_ANALYSIS_PROMPT 含动作词/领域词约束）
+│   └── reactSteps.js     # 两个 Reason 步骤封装（analyzeTask / rankSkills）
+├── matcher/
+│   └── fuzzyMatcher.js   # 模糊匹配工具（分词器 + 纯 JS BM25 + 双通道多路召回融合）
+│                          # 动作通道加权 + 领域通道 + 原文兜底 + legacy fallback
+├── utils/
+│   └── actionWords.js    # 动作词表 + 领域词表（ACTION_WORDS / DOMAIN_WORDS / isActionWord / isDomainWord）
+│                          # 供 fuzzyMatcher.js 加权、prompts.js 示例共用
+├── scanner/
+│   └── skillScanner.js   # SKILL 目录扫描 + frontmatter 解析 → SkillMeta[]
+│                          # searchableText = metadata×3 + 正文前 2500 字符 + useWhen
+└── __tests__/
+    ├── run-sample.js      # 端到端自测脚本
+    └── test-pure-logic.js # 纯逻辑单测（不依赖 LLM/网络）
+```
+
+## 模块组成
+
+| 文件 | 职责 |
+|------|------|
+| [core/Agent.js](core/Agent.js) | 对外导出的 `Agent` 类，`selectSkill(task, skillDirectory)` 主入口，编排 ReAct 流程 |
+| [index.js](index.js) | 模块统一导出 |
+| [llm/llmClient.js](llm/llmClient.js) | LLM 客户端（百炼 OpenAI 兼容，glm-5-1），提供 `chat()` / `chatJSON()` |
+| [scanner/skillScanner.js](scanner/skillScanner.js) | 扫描 SKILL 目录，解析 `SKILL.md` frontmatter，产出 `SkillMeta[]` |
+| [matcher/fuzzyMatcher.js](matcher/fuzzyMatcher.js) | 模糊匹配工具（合并模块）：分词器 + 纯 JS BM25 + 双通道多路召回融合 + legacy fallback |
+| [utils/actionWords.js](utils/actionWords.js) | 动作词表 + 领域词表（`ACTION_WORDS` / `DOMAIN_WORDS`），供 fuzzyMatcher 加权与 prompts 示例共用 |
+| [llm/reactSteps.js](llm/reactSteps.js) | 两个 Reason 步骤封装：`analyzeTask` / `rankSkills` |
+| [llm/prompts.js](llm/prompts.js) | prompt 模板 + `renderTemplate` 占位符替换（`TASK_ANALYSIS_PROMPT` 含动作词/领域词提取约束） |
+| [types.js](types.js) | 数据结构 JSDoc 契约（`SkillMeta` / `TaskAnalysis` / `SkillSelection`；本地保留，不提交远端） |
+| [__tests__/](__tests__/) | 自测脚本 |
+
+## 工作流
+
+### 步骤 0：扫描 SKILL 目录
+
+`skillScanner.scanSkills(skillDirectory)` 遍历目录下每个子目录，读取 `SKILL.md`，解析 YAML frontmatter（`name` / `description` / `metadata` 含 `version` / `category` / `language` 等），产出 `SkillMeta[]`。每个 `SkillMeta` 含 `searchableText`（= name + description + category + language 等 metadata 字段×3 + 正文前 2500 字符 + useWhen 拼成的小写串），供 BM25 打分用。metadata 权重放大保证 frontmatter 匹配占主导，正文纳入覆盖 description 未提及的语义，useWhen 让"什么场景下调用"这一语义信号进入召回。
+
+### Reason #1：LLM 拆解任务
+
+`reactSteps.analyzeTask(llm, task)` 调用 glm-5-1，将具体事项拆解为结构化的 `TaskAnalysis`。`TASK_ANALYSIS_PROMPT` 通过规则化约束 + few-shot 示例，强制 LLM 保留**动作类型词**（如"准出审核/验收测试/可行性分析/代码生成"）与**领域/产出物特征词**（如"接口规格/接口签名/方法签名/导出链"），并让 `intent` 以动词开头点明动作类型：
+
+```json
+{
+  "intent": "扫描源码提取方法级接口规格并输出文档",
+  "keywords": ["接口规格", "接口签名", "方法签名", "方法级接口", "扫描", "文档生成", "arkts", "fastble"],
+  "constraints": ["C++ 开源库", "鸿蒙平台", "输出可行性报告"],
+  "techStack": ["ArkTS"],
+  "whenToUse": "从源码提取方法级接口规格时"
+}
+```
+
+### Act：模糊匹配召回（双通道多路融合）
+
+`fuzzyMatcher.fuzzyMatch(analysis, skills, { topK, task, weights })` 采用**双通道 + 多路召回融合**，对每个 SKILL 的 `searchableText` 做 BM25 打分，按分数降序取 topK 候选。
+
+三路召回：
+
+- **动作通道（路 A）**：仅用 `keywords + intent` 中的**动作类 token** 做 BM25 打分。动作词加权只对真动作词生效，避免领域词混入动作词表稀释信号。
+- **领域通道（路 B）**：用 `keywords` 中的**领域/产出物特征词** + `whenToUse` 分词做 BM25 打分，直接匹配文档侧已索引的 `useWhen` 与 searchableText 中的领域词。这是召回稳定性的关键信号。
+- **原文兜底通道（路 C）**：用**原始任务描述 task 全文**分词做 BM25 打分，覆盖 keywords 提取偏差导致的语义漂移。
+
+融合公式：`score = wA·bm25A + wB·bm25B + wC·bm25C`（归一化后加权，默认 `wA=0.4, wB=0.4, wC=0.2`）。
+
+关键打分策略：
+
+- **分数归一化**：raw 分 ÷ max(3, 单路实际参与 token 数)，使分数跨查询可比、阈值判定稳定，且避免多路融合/动作词展开导致分母虚高。
+- **name 精确匹配 bonus**：query keywords 中任一词与 skill.name 精确匹配时 score ×1.15。
+- **动作词加权**：query 侧的动作类型词（`utils/actionWords.js` 的 `ACTION_WORDS`，如"准出审核/验收测试"）会被重复 `ACTION_WORD_WEIGHT`（默认 3）次，等价于打分时权重×3，使意向词主导排名。
+
+融合后全零分（无任何 token 重叠）时，回退到 legacy 子串匹配，保证不返回空。
+
+### Reason #2：LLM 排序筛选
+
+`reactSteps.rankSkills(llm, task, analysis, candidates)` 把 topK 候选的简表（id / name / description / category / language / useWhen）发给 glm-5-1，让 LLM 按规则化评分（意图 40 / 技术栈 30 / 约束 20 / 关键词 10 + 硬否决规则）打分排序，选出最佳 SKILL。`Agent` 会对返回结果做稳定降序排序，确保 `topScore` 判定不依赖 LLM 的返回顺序。
+
+### 返回结果
+
+```js
+{
+  best: SkillMeta|null,        // 最佳 SKILL（未命中阈值/分差过小时为 null）
+  skillPath: string|null,      // best 的绝对目录路径（未命中为 null）
+  hit: boolean,                // 检索是否命中（top1>=阈值 且 top1-top2 分差>=10）
+  topScore: number,            // top1 分数
+  scoreGap: number,            // top1-top2 分差（<10 时判定不确定，hit=false）
+  ranked: [{ skill, score, dimensions, reason }],  // topK 排序结果
+  analysis: TaskAnalysis,       // 任务拆解
+  trace: [...]                 // ReAct 每步留痕（含 act:fuzzyMatch 每路分数明细）
+}
+```
+
+> `act:fuzzyMatch` 的 trace 会记录每路分数明细（`routes: { action, domain, raw }`），便于定位偶发未命中。
+
+## 快速开始
+
+### 1. 配置环境变量
+
+在 `Server/.env` 中配置：
+
+```env
+DASHSCOPE_API_KEY=your_api_key_here
+LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+LLM_MODEL=glm-5-1
+```
+
+### 2. 安装依赖
+
+```bash
+cd Server
+npm install
+```
+
+### 3. 使用
+
+```js
+import { Agent } from './Agent/SkillSelector/index.js';
+
+const agent = new Agent();
+const result = await agent.selectSkill(
+  '分析 libcurl 这个 C++ 开源库能否移植到鸿蒙平台',
+  'D:/code/AIWeb/Server/Skills'
+);
+
+console.log(result.best.dirName);   // 'CPPAnalysisSkill'
+console.log(result.best.name);      // 'cpp-porting-analysis'
+console.log(result.ranked);        // 5 项排序，每项 { skill, score, reason }
+console.log(result.analysis);      // 任务拆解
+console.log(result.trace);         // ReAct 每步留痕
+```
+
+### 4. 运行自测
+
+```bash
+# 纯逻辑自测（不调用 LLM，不依赖网络）
+node Agent/SkillSelector/__tests__/test-pure-logic.js
+
+# 完整 ReAct 自测（调用真实 LLM，需配置 API Key）
+node Agent/SkillSelector/__tests__/run-sample.js
+```
+
+## 对外接口
+
+### `Agent` 类
+
+```js
+import { Agent } from './Agent/SkillSelector/index.js';
+
+const agent = new Agent();
+// task: 具体事项；skillDirectory: SKILL 筛选目录绝对路径
+const result = await agent.selectSkill('分析 libcurl 的鸿蒙化可行性', 'D:/code/AIWeb/Server/Skills');
+
+console.log(result.best.name);       // 最佳 SKILL 名称（未命中时 best 为 null）
+console.log(result.best.dirName);     // 最佳 SKILL 目录名
+console.log(result.hit);            // 检索是否命中（top1>=阈值 且 top1-top2 分差>=10）
+console.log(result.skillPath);       // best 的绝对目录路径
+console.log(result.topScore);        // top1 分数
+console.log(result.scoreGap);        // top1-top2 分差（<10 时判定不确定）
+console.log(result.ranked);          // 排序列表 [{ skill, score, dimensions, reason }]
+console.log(result.analysis);        // 任务拆解
+console.log(result.trace);           // ReAct 每步留痕
+```
+
+### `Agent` 构造选项（可选，用于测试 / 自定义）
+
+```js
+new Agent({
+  llm: new LLMClient({ model: 'glm-5-1' }),  // 注入自定义 LLM 客户端
+  matcher: customMatcher,                      // 注入自定义模糊匹配实现
+  topK: 5,                                     // 召回候选数量
+  hitThreshold: 60,                            // 命中阈值
+  weights: { action: 0.4, domain: 0.4, raw: 0.2 },  // 多路召回融合权重
+});
+```
+
+## SKILL 目录格式
+
+参考 `D:\code\AIWeb\Server\Skills`，每个 SKILL 是一个目录：
+
+```
+<skillDirectory>/
+├── SomeSkill/
+│   ├── SKILL.md          # 必须存在，含 YAML frontmatter
+│   ├── references/        # 可选
+│   └── scripts/           # 可选
+└── AnotherSkill/
+    └── SKILL.md
+```
+
+`SKILL.md` 的 frontmatter 示例：
+
+```yaml
+---
+name: cpp-porting-analysis
+description: 对 C++ 开源库进行鸿蒙化可行性分析...
+license: MIT
+metadata:
+  author: lalhan
+  version: "2.2.0"
+  category: harmonyos-porting
+  language: C/C++
+  useWhen: 从鸿蒙原生库源码提取方法级接口规格时   # 可选，领域通道匹配的关键信号
+compatibility: 适用于任意托管在 Git 仓库的 C/C++ 开源库。
+---
+```
+
+## 高级用法
+
+### 注入自定义 LLM 客户端
+
+```js
+import { Agent, LLMClient } from './Agent/SkillSelector/index.js';
+
+const customLLM = new LLMClient({
+  model: 'glm-5-1',
+  temperature: 0.1,
+});
+const agent = new Agent({ llm: customLLM });
+```
+
+### 注入自定义模糊匹配算法
+
+`fuzzyMatch` 默认用 BM25，可通过构造函数注入自定义实现（如向量检索）：
+
+```js
+const agent = new Agent({
+  matcher: async (analysis, skills, options) => {
+    // 自定义匹配逻辑，返回 [{ skill, score }]
+    return myVectorSearch(analysis, skills, options.topK);
+  },
+});
+```
+
+### 调整召回数量
+
+```js
+const agent = new Agent({ topK: 10 });  // 召回 10 个候选
+```
+
+或在 `.env` 中配置：
+
+```env
+SELECTOR_TOP_K=10
+```
+
+## 配置项
+
+`Server/.env` 支持的环境变量：
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `DASHSCOPE_API_KEY` | 百炼平台 API Key（必填） | — |
+| `LLM_BASE_URL` | OpenAI 兼容端点 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| `LLM_MODEL` | 模型名 | `glm-5-1` |
+| `LLM_TEMPERATURE` | 采样温度 | `0.2` |
+| `LLM_MAX_TOKENS` | 最大 token 数 | `2048` |
+| `LLM_ENABLE_THINKING` | 是否开启 GLM 思考模式 | `false` |
+| `SELECTOR_TOP_K` | 模糊匹配召回数量 | `5` |
+| `SELECTOR_HIT_THRESHOLD` | 命中阈值（top1>=此值且分差>=10 才命中） | `60` |
+| `SELECTOR_WEIGHT_ACTION` | 动作通道融合权重 | `0.4` |
+| `SELECTOR_WEIGHT_DOMAIN` | 领域通道融合权重 | `0.4` |
+| `SELECTOR_WEIGHT_RAW` | 原文兜底通道融合权重 | `0.2` |
+| `FALLBACK_MODEL` | 连续 3 次 529 过载时切换的备用模型 | — |
+
+## 设计原则
+
+- **高内聚低耦合**：每个文件单一职责，`core/Agent.js` 只做编排，prompt / fs / LLM / 匹配各自独立
+- **可替换**：`LLMClient` 和 `matcher` 均支持注入 mock / 自定义实现
+- **可测试**：纯逻辑自测不依赖 LLM 和网络，完整自测验证端到端流程
+- **零原生依赖**：BM25 用纯 JS 实现，不依赖 SQLite / 原生编译模块
+- **动作/领域词分离管理**：动作类型词与领域/产出物词分别在 `utils/actionWords.js` 的 `ACTION_WORDS` / `DOMAIN_WORDS`，prompt 示例与 BM25 加权共用同一来源，避免词表漂移
+
+## 匹配质量优化（演进记录）
+
+SKILL 召回经历了以下演进，共同保证验收测试、接口规格等动作/领域匹配类 SKILL 能被精准召回：
+
+1. **提示词保留动作词**（`TASK_ANALYSIS_PROMPT`）：强制 LLM 拆解时保留"准出审核/验收测试"等意向关键词，解决任务描述冗长时丢词问题。
+2. **searchableText 文档侧加权**（`skillScanner._buildSearchableText`）：索引 = metadata 字段×3 + 正文前 2500 字符 + useWhen，提升 SKILL 文档匹配质量。
+3. **BM25 分数归一化 + name bonus**（`fuzzyMatcher`）：raw 分 ÷ max(3, 原始 query token 数) 使跨查询可比、阈值判定稳定；query 关键词与 skill.name 精确匹配时 ×1.15。
+4. **BM25 query 侧动作词加权**（`fuzzyMatcher`）：动作类型词权重×3，解决动作词被高频技术词淹没、目标 SKILL 被挤出 TopK 的问题。
+5. **动作/领域词表纯净化**（`utils/actionWords.js`）：将语义非动作的产出物/领域词（接口规格/接口签名/方法签名/导出链/覆盖率等）从 `ACTION_WORDS` 移入独立的 `DOMAIN_WORDS`，避免"堆词"式打补丁稀释真正的动作信号。
+6. **双通道多路召回融合**（`fuzzyMatcher`）：动作通道 + 领域通道 + 原文兜底通道，弱化对 LLM keywords 提取的单点依赖，目标 SKILL 即使 keywords 有偏差也能稳定进入 topK，解决偶现未命中问题。
+7. **ranked 稳定降序排序**（`core/Agent.js`）：LLM 返回结果做稳定降序排序，确保 `topScore` 判定不依赖 LLM 的返回顺序。
+
+## 匹配质量优化注意点
+
+- **提示词保留动作词**：`TASK_ANALYSIS_PROMPT` 强制 LLM 拆解时保留"准出审核/验收测试"等意向关键词，避免冗长任务描述导致丢词。
+- **searchableText 文档侧加权**：`skillScanner._buildSearchableText` 构建索引 = metadata 字段×3 + 正文前 2500 字符 + useWhen，保证 frontmatter 匹配主导，正文补充语义。
+- **BM25 分数归一化 + name bonus**：`fuzzyMatcher` raw 分 ÷ max(3, 单路实际参与 token 数)，跨查询可比、阈值判定稳定；query 关键词与 skill.name 精确匹配时 ×1.15。
+- **BM25 动作词加权**：`fuzzyMatcher` query 侧对动作词重复 `ACTION_WORD_WEIGHT` 次（默认 3），归一化分母用展开前原始 token 数，使动作词主导排名，避免被高频技术词挤出 TopK。
+- **新增动作词**：匹配新动作类型时，把词加入 `utils/actionWords.js` 的 `ACTION_WORDS`，并同步 `TASK_ANALYSIS_PROMPT` 的动作词示例，确保 LLM 产出能被 `isActionWord` 识别。
+- **新增领域词**：新增产出物/领域特征词时，把词加入 `utils/actionWords.js` 的 `DOMAIN_WORDS`（同步 `TASK_ANALYSIS_PROMPT` 的领域词示例），确保 LLM 产出能被 `isDomainWord` 识别，供领域通道召回。

package/vendor/Server/Agent/SkillSelector/core/Agent.js

@@ -0,0 +1,207 @@
+/**
+ * Agent.js — SKILL 选择器 ReAct Agent（对外导出）
+ *
+ * 设计模式：ReAct（Reason + Act）
+ *   - Reason #1：LLM 拆解任务 → 生成模糊匹配输入（keywords/intent/techStack）
+ *   - Act     ：调用模糊匹配工具，召回 top5 候选 SKILL
+ *   - Reason #2：LLM 对 top5 评分排序 → 选出最佳 SKILL
+ *
+ * 对外导出 Agent 类，核心方法：
+ *   async selectSkill(task, skillDirectory) -> SkillSelection
+ *
+ * 使用示例：
+ *   import { Agent } from './Agent/SkillSelector/index.js';
+ *   const agent = new Agent();
+ *   const result = await agent.selectSkill('分析 libcurl 的鸿蒙化可行性', 'D:/code/AIWeb/Server/Skills');
+ *   console.log(result.best.name);
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+
+import { LLMClient } from '../llm/llmClient.js';
+import { scanSkills } from '../scanner/skillScanner.js';
+import { fuzzyMatch, createFuzzyMatcher } from '../matcher/fuzzyMatcher.js';
+import { analyzeTask, rankSkills } from '../llm/reactSteps.js';
+import { createLogger } from '../../../Routes/library/logger.js';
+
+const log = createLogger('SkillSelector');
+
+// 加载 Server/.env（本文件在 core/ 下，上三级目录为 Server/）
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.resolve(__dirname, '..', '..', '..', '.env') });
+
+const DEFAULT_TOP_K = 5;
+const DEFAULT_HIT_THRESHOLD = 60;
+
+// 多路召回融合权重（默认：动作 0.4 / 领域 0.4 / 原文 0.2）
+const DEFAULT_WEIGHTS = { action: 0.4, domain: 0.4, raw: 0.2 };
+
+export class Agent {
+  /**
+   * @param {object} [options]
+   * @param {LLMClient} [options.llm]      - 注入自定义 LLM 客户端（用于测试）
+   * @param {Function} [options.matcher]   - 注入自定义模糊匹配实现
+   * @param {number} [options.topK]        - 召回候选数量，默认 5 或读 SELECTOR_TOP_K
+   * @param {number} [options.hitThreshold] - 命中阈值，默认 60 或读 SELECTOR_HIT_THRESHOLD
+   */
+  constructor(options = {}) {
+    this.llm = options.llm || new LLMClient();
+    this.matcher = createFuzzyMatcher(options.matcher);
+    this.topK = options.topK ?? _envInt('SELECTOR_TOP_K', DEFAULT_TOP_K);
+    this.hitThreshold = options.hitThreshold ?? _envInt('SELECTOR_HIT_THRESHOLD', DEFAULT_HIT_THRESHOLD);
+    this.weights = {
+      action: options.weights?.action ?? _envFloat('SELECTOR_WEIGHT_ACTION', DEFAULT_WEIGHTS.action),
+      domain: options.weights?.domain ?? _envFloat('SELECTOR_WEIGHT_DOMAIN', DEFAULT_WEIGHTS.domain),
+      raw: options.weights?.raw ?? _envFloat('SELECTOR_WEIGHT_RAW', DEFAULT_WEIGHTS.raw),
+    };
+  }
+
+  /**
+   * 选择最适合的 SKILL（ReAct 主流程）
+   * @param {string} task             - 具体事项
+   * @param {string} skillDirectory  - SKILL 筛选目录绝对路径
+   * @returns {Promise<import('../types.js').SkillSelection>}
+   */
+  async selectSkill(task, skillDirectory) {
+    if (!task) throw new Error('Agent.selectSkill: task 不能为空');
+
+    if (!skillDirectory) throw new Error('Agent.selectSkill: skillDirectory 不能为空');
+
+    log.debug('selectSkill 入参', { task, skillDirectory });
+
+    const trace = [];
+
+    // ─── 步骤 0：扫描 SKILL 目录，构建候选池 ───
+    const skills = await scanSkills(skillDirectory);
+    if (skills.length === 0) {
+      throw new Error(`Agent.selectSkill: SKILL 目录 ${skillDirectory} 下未找到任何有效 SKILL`);
+    }
+    trace.push({ step: 'scan', output: { totalSkills: skills.length } });
+
+    // ─── Reason #1：LLM 拆解任务 ───
+    const analysis = await analyzeTask(this.llm, task);
+    trace.push({ step: 'reason-1:analyzeTask', input: { task }, output: analysis });
+
+    // ─── Act：调用模糊匹配工具，召回 topK（双通道多路融合） ───
+    const matched = await this.matcher(analysis, skills, { topK: this.topK, task, weights: this.weights });
+    if (matched.length === 0) {
+      throw new Error('Agent.selectSkill: 模糊匹配未召回任何 SKILL');
+    }
+    // trace 留痕：记录每路分数（动作/领域/原文），便于定位偶发未命中
+    trace.push({
+      step: 'act:fuzzyMatch',
+      output: {
+        topK: matched.length,
+        weights: this.weights,
+        scores: matched.map((m) => m.score),
+        routes: matched.map((m) => m.routes || null),
+      },
+    });
+
+    // ─── Reason #2：LLM 对候选评分排序 ───
+    const rankResult = await rankSkills(this.llm, task, analysis, matched);
+    trace.push({ step: 'reason-2:rankSkills', output: rankResult });
+
+    // ─── 组装返回：把 ranked 的 id 映射回完整 SkillMeta ───
+    const skillMap = new Map(skills.map((s) => [s.dirName, s]));
+    // fuzzyMatch 已产出的 score 作为回退
+    const matchScoreMap = new Map(matched.map((m) => [m.skill.dirName, m.score]));
+
+    let ranked = rankResult.ranked.map((r) => {
+      const skill = skillMap.get(r.id) || matched.find((m) => m.skill.dirName === r.id)?.skill;
+      if (!skill) return null;
+      return {
+        skill,
+        score: r.score,
+        // 携带 LLM 的分维度分数（容错：rankSkills 已保证 dimensions 为对象）
+        dimensions: r.dimensions || {},
+        reason: r.reason || `模糊匹配原始分：${matchScoreMap.get(r.id) ?? 0}`,
+      };
+    }).filter(Boolean);
+
+    // 兜底：若 LLM 排序结果为空（模型未按格式返回），用模糊匹配原始召回结果填充
+    if (ranked.length === 0) {
+      ranked = matched.map((m) => ({
+        skill: m.skill,
+        score: m.score,
+        dimensions: {},
+        reason: `模糊匹配原始分：${m.score}`,
+      }));
+      trace[trace.length - 1] = {
+        ...trace[trace.length - 1],
+        note: 'rankSkills 返回为空，已用模糊匹配结果兜底',
+      };
+    }
+
+    // 稳定降序排序：topScore 判定依赖 ranked[0]，不能信任 LLM 的返回顺序（偶现不严格降序）
+    ranked = ranked.sort((a, b) => b.score - a.score);
+
+    // ─── 命中阈值判定：top1 分数 >= 阈值即命中 ───
+    // ranked 已按 score 降序，ranked[0] 是最高分候选
+    const topScore = ranked.length > 0 ? ranked[0].score : 0;
+    const secondScore = ranked.length > 1 ? ranked[1].score : 0;
+    // top1-top2 分差仅作参考信息保留，不参与命中判定：
+    // 高分 top1（>=阈值）已明确是最佳选择，即使 top2 分数接近也不应判为"不确定"
+    const scoreGap = topScore - secondScore;
+    const hit = topScore >= this.hitThreshold;
+
+    // 确定 best：命中时取最高分 SKILL，未命中时为 null（调用方据此走兜底流程）
+    let best = null;
+    if (hit) {
+      // 命中：优先用 LLM 的 bestId，否则取 ranked[0]
+      if (rankResult.bestId) {
+        best = skillMap.get(rankResult.bestId) || (ranked[0] && ranked[0].skill);
+      }
+      if (!best && ranked.length > 0) {
+        best = ranked[0].skill;
+      }
+      if (!best) {
+        throw new Error('Agent.selectSkill: 命中但无法确定最佳 SKILL');
+      }
+    }
+    // 未命中时 best 保持 null，skillPath 也为 null
+
+    const result = {
+      best,
+      // SKILL 绝对目录（命中时为 best.skillPath，未命中为 null）
+      skillPath: best ? best.skillPath : null,
+      // 检索是否命中阈值
+      hit,
+      // top1 分数（便于调用方了解置信度，未召回为 0）
+      topScore,
+      // top1-top2 分差（仅参考信息，不参与命中判定）
+      scoreGap,
+      ranked,
+      analysis,
+      trace,
+    };
+
+    log.debug('selectSkill 输出', {
+      hit: result.hit,
+      topScore: result.topScore,
+      best: result.best ? result.best.dirName : null,
+      skillPath: result.skillPath,
+      rankedCount: result.ranked.length,
+    });
+
+    return result;
+  }
+}
+
+function _envInt(key, def) {
+  const v = process.env[key];
+  if (v === undefined || v === '') return def;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? n : def;
+}
+
+function _envFloat(key, def) {
+  const v = process.env[key];
+  if (v === undefined || v === '') return def;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : def;
+}
+
+export default Agent;

package/vendor/Server/Agent/SkillSelector/index.js

@@ -0,0 +1,14 @@
+/**
+ * index.js — SkillSelector 模块统一导出
+ *
+ * 外部使用：
+ *   import { Agent } from './Agent/SkillSelector/index.js';
+ *   const agent = new Agent();
+ *   const result = await agent.selectSkill(task, skillDirectory);
+ */
+
+export { Agent } from './core/Agent.js';
+export { LLMClient } from './llm/llmClient.js';
+export { scanSkills, parseFrontmatter } from './scanner/skillScanner.js';
+export { fuzzyMatch, createFuzzyMatcher } from './matcher/fuzzyMatcher.js';
+export { analyzeTask, rankSkills } from './llm/reactSteps.js';