neo-skill 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neo-skill",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "A multi-assistant skill generator (Claude/Windsurf/Cursor/GitHub Skills) driven by a canonical SkillSpec.",
   "license": "MIT",
   "bin": {

package/skills/skill-finder/README.md

@@ -0,0 +1,52 @@
+# skill-finder
+
+发现/匹配/安装第三方 skill 库。
+
+## 功能
+
+- **主动搜索**：通过两级提问收集需求，匹配第三方能力单元
+- **被动推荐**：供 skill-creator 调用，推荐高置信度第三方 unit
+- **两种安装模式**：自动安装（默认）/ 手动安装（仅输出命令）
+- **可追溯性**：所有安装行为记录到 `~/.omni-skill/install_records.json`
+- **诊断工具**：提供匹配 trace 和安装记录分析
+
+## 触发方式
+
+- "找第三方 skill"
+- "有没有现成的工具"
+- "推荐一个能力库"
+- "安装第三方能力"
+- "search for third-party skill"
+
+## 使用方式
+
+### CLI 模式
+
+```bash
+python -m skill_finder.cli
+```
+
+### 编程接口
+
+```python
+from skill_finder.recommender import Recommender
+from skill_finder.models import SearchQuery
+
+recommender = Recommender()
+query = SearchQuery(goal="AI 代码编辑", tags=["code-generation"], ide="windsurf")
+result = recommender.recommend(query)
+```
+
+## 设计原则
+
+- **宁缺毋滥**：置信度 < 60% 必须拒绝
+- **诚实反馈**：明确告知拒绝原因（4 种分类）
+- **可追溯**：install_record 记录所有安装行为
+- **轻量集成**：skill-creator 集成不打断主流程
+
+## 详细文档
+
+参见：
+- `DESIGN_SKILL_FINDER.md` - 完整设计文档
+- `SKILL_FINDER_USAGE.md` - 使用指南
+- `references/matching-algorithm.md` - 匹配算法详解

package/skills/skill-finder/references/install-modes.md

@@ -0,0 +1,13 @@
+# skill-finder 安装模式
+
+## 两种安装模式
+
+### 模式 1: 自动安装（默认）
+- 执行 `package.install.auto_install_cmd`
+- 捕获输出并记录结果
+- 写入 install_record (executed=true)
+
+### 模式 2: 手动安装
+- 输出 `package.install.manual_install_cmd`
+- 记录指令 (executed=false, result=skipped)
+- 任务结束，不执行安装

package/skills/skill-finder/references/matching-algorithm.md

@@ -0,0 +1,172 @@
+# skill-finder 匹配算法
+
+## 一、两阶段匹配流程
+
+### 阶段 1: 粗筛（Coarse Filtering）
+**目标**: 快速缩小候选范围
+
+**输入**: SearchQuery (goal, tags, keywords, ide, env, constraints)
+
+**方法**: 倒排索引命中
+1. **Tag 倒排**: 从 `indexes/units.by_tag.json` 查找匹配 `query.tags` 的 unit_id
+2. **Keyword 倒排**: 从 `indexes/units.by_keyword.json` 查找匹配 `query.keywords` 的 unit_id
+3. **IDE 倒排**: 从 `indexes/units.by_ide.json` 查找匹配 `query.ide` 的 unit_id
+4. **合并**: 取并集（tag OR keyword）与 IDE 交集
+
+**输出**: 候选 unit_id 列表
+
+**拒绝条件**: 若候选为空，返回 `no_candidates_by_tag`
+
+---
+
+### 阶段 2: 精排（Fine Ranking）
+**目标**: 计算置信度分数，过滤低质量匹配
+
+**评分公式**:
+```
+score = tag_coverage * 0.6 + keyword_match * 0.3 + ide_bonus * 0.1
+```
+
+**评分细节**:
+
+1. **Tag 覆盖率** (权重 0.6)
+   ```
+   tag_coverage = len(matched_tags) / len(query.tags)
+   matched_tags = set(query.tags) ∩ set(unit.capability_tags)
+   ```
+
+2. **Keyword 匹配** (权重 0.3)
+   ```
+   keyword_match = len(matched_keywords) / len(query.keywords)
+   matched_keywords = set(query.keywords) ∩ set(unit.keywords)
+   ```
+
+3. **IDE 支持** (权重 0.1)
+   - 支持: +0.1
+   - 不支持: score *= 0.2 (显著降权)
+
+4. **约束过滤** (降权因子)
+   - **env 冲突**: 若 `unit.conflicts` 提及 `query.env` → score *= 0.3
+   - **constraints 违反**: 若 unit 描述与约束冲突 → score *= 0.5
+     - 示例: `no-network` 约束 + unit 描述含 "network" → 降权
+
+**输出**: 按 score 降序排列的 MatchResult 列表
+
+---
+
+## 二、置信门槛与拒绝策略
+
+### 置信门槛
+```python
+MIN_SCORE = 0.6  # 60%
+```
+
+**规则**:
+- `score >= 0.6`: 返回 Top 1-3
+- `score < 0.6`: **必须拒绝**，不得返回低质量结果
+
+---
+
+### 拒绝原因分类
+
+#### 1. `no_candidates_by_tag`
+**条件**: 粗筛阶段无候选
+**原因**: 未找到匹配的能力标签或关键词
+**建议**: 补充更多标签/关键词，或使用 skill-creator 创建自研 skill
+
+#### 2. `candidates_but_no_ide_support`
+**条件**: 有候选但所有 unit 均不支持目标 IDE
+**原因**: 找到候选能力，但均不支持 {query.ide}
+**建议**: 更换 IDE 或使用 generic 模式
+
+#### 3. `candidates_but_incompatible_env`
+**条件**: 有候选但所有 unit 均因 env/constraints 被降权至 < 0.6
+**原因**: 找到候选能力，但均不满足环境或约束条件
+**建议**: 放宽约束或调整环境
+
+#### 4. `insufficient_info`
+**条件**: 有候选但最高分 < 0.6，且无明确冲突
+**原因**: 候选能力置信度不足（< 60%），建议补充更多需求信息
+**建议**: 回答 Level 2 问题，提供更多细节
+
+---
+
+## 三、匹配示例
+
+### 示例 1: 高置信匹配
+```
+Query:
+  goal: "AI 辅助多文件代码重构"
+  tags: ["code-refactoring", "multi-file-editing"]
+  ide: "windsurf"
+
+候选: gh:aider-chat/aider#code-edit
+  capability_tags: ["code-generation", "code-refactoring", "multi-file-editing"]
+  ide_support: ["windsurf", "cursor"]
+
+评分:
+  tag_coverage = 2/2 = 1.0 → 0.6
+  keyword_match = 0 (未提供) → 0
+  ide_bonus = 0.1
+  score = 0.7 ✓ (通过)
+
+结果: 返回 Top 1
+```
+
+### 示例 2: IDE 不支持拒绝
+```
+Query:
+  goal: "生成 commit message"
+  tags: ["git-commit"]
+  ide: "vscode"
+
+候选: gh:aider-chat/aider#git-commit
+  capability_tags: ["git-commit"]
+  ide_support: ["windsurf", "cursor", "generic"]
+
+评分:
+  tag_coverage = 1/1 = 1.0 → 0.6
+  ide_bonus = 0 (不支持 vscode)
+  降权: score *= 0.2 → 0.12 ✗
+
+拒绝原因: candidates_but_no_ide_support
+```
+
+### 示例 3: 约束冲突拒绝
+```
+Query:
+  goal: "自动化代码编辑"
+  tags: ["code-generation"]
+  constraints: ["no-network"]
+  ide: "windsurf"
+
+候选: gh:aider-chat/aider#code-edit
+  description: "AI-powered ... (需要 LLM API)"
+  conflicts: "需要网络访问 LLM provider"
+
+评分:
+  tag_coverage = 1/1 = 1.0 → 0.6
+  ide_bonus = 0.1
+  约束冲突: score *= 0.5 → 0.35 ✗
+
+拒绝原因: candidates_but_incompatible_env
+```
+
+---
+
+## 四、实现要点
+
+### 宁缺毋滥原则
+- **禁止强行匹配**: 低于阈值必须拒绝
+- **禁止虚构结果**: 不得返回不存在的 unit
+- **诚实反馈**: 明确告知拒绝原因与缺口信息
+
+### 性能优化
+- **按需加载**: 粗筛仅加载索引，精排才加载完整 unit/package 数据
+- **Top-K 限制**: 最多返回 Top 3，避免信息过载
+- **索引预构建**: 使用 `build_third_party_indexes.py` 预生成倒排索引
+
+### 可扩展性
+- **插件化评分**: 可新增评分因子（如 popularity, last_updated）
+- **动态阈值**: 可根据 query 复杂度调整 MIN_SCORE
+- **多语言支持**: 索引构建时归一化大小写，支持中英文关键词

package/skills/skill-finder/skillspec.json

@@ -0,0 +1,77 @@
+{
+  "version": 1,
+  "name": "skill-finder",
+  "description": "发现/匹配/安装第三方 skill 库。支持两种模式：(1) 主动搜索（最小两级提问）；(2) 被动推荐（skill-creator 集成）。宁缺毋滥，未达阈值必须拒绝并说明原因。",
+  "primary_target": "windsurf",
+  "backward_compat": ["claude", "cursor", "github"],
+  "questions": [
+    "你想实现什么目标？（一句话描述任务）",
+    "输入是什么？（文件/代码/数据/命令等）",
+    "运行环境？（OS/Shell/Runtime）",
+    "使用哪个 IDE/编辑器？（windsurf/cursor/vscode/generic）"
+  ],
+  "triggers": [
+    "找第三方 skill",
+    "有没有现成的工具",
+    "推荐一个能力库",
+    "安装第三方能力",
+    "search for third-party skill",
+    "find existing tools"
+  ],
+  "freedom_level": "low",
+  "workflow": {
+    "type": "sequential",
+    "steps": [
+      {
+        "id": "interview",
+        "title": "两级提问收集需求",
+        "kind": "action",
+        "commands": [],
+        "notes": "Level 1 固定 3-4 问（goal/input/env/ide）；Level 2 仅不确定时追问 1-2 个。详见 references/interview-protocol.md"
+      },
+      {
+        "id": "match",
+        "title": "匹配第三方 unit",
+        "kind": "action",
+        "commands": [],
+        "notes": "两阶段：粗筛（倒排索引）+ 精排（tag 覆盖率 + 约束过滤）。置信度 < 60% 必须拒绝并说明原因。详见 references/matching-algorithm.md"
+      },
+      {
+        "id": "present",
+        "title": "展示结果（Top 1-3 或拒绝）",
+        "kind": "gate",
+        "commands": [],
+        "notes": "命中：列出 unit + package + 匹配原因 + README 链接 + 使用方式。未命中：明确拒绝原因分类（no_candidates_by_tag/no_ide_support/incompatible_env/insufficient_info）"
+      },
+      {
+        "id": "install",
+        "title": "安装（默认自动/可选手动）",
+        "kind": "action",
+        "commands": [],
+        "notes": "默认：执行 auto_install_cmd 并记录。手动：输出 manual_install_cmd 并记录（executed=false）。详见 references/install-modes.md"
+      },
+      {
+        "id": "record",
+        "title": "记录安装行为",
+        "kind": "action",
+        "commands": [],
+        "notes": "写入 ~/.omni-skill/install_records.json（或配置路径）。字段：timestamp/unit_id/package_id/mode/executed/result/error_summary/docs_links"
+      },
+      {
+        "id": "output",
+        "title": "输出使用方式",
+        "kind": "action",
+        "commands": [],
+        "notes": "展示 unit.entrypoints（原生命令/参数/示例）+ README 链接 + usage_notes"
+      }
+    ]
+  },
+  "references": [
+    "references/matching-algorithm.md",
+    "references/install-modes.md",
+    "references/interview-protocol.md",
+    "references/registry-schema.md"
+  ],
+  "scripts": [],
+  "assets": []
+}

package/src/skill_finder/__init__.py

@@ -0,0 +1,21 @@
+"""skill-finder - 发现/匹配/安装第三方 skill 库"""
+
+__version__ = "1.0.0"
+
+from .models import (
+    SkillPackage,
+    SkillUnit,
+    SearchQuery,
+    SearchResult,
+    MatchResult,
+    InstallRecord,
+)
+
+__all__ = [
+    "SkillPackage",
+    "SkillUnit",
+    "SearchQuery",
+    "SearchResult",
+    "MatchResult",
+    "InstallRecord",
+]

package/src/skill_finder/cli.py

@@ -0,0 +1,106 @@
+"""主动搜索入口 - CLI 接口"""
+
+import sys
+from typing import Optional
+from .interview import Interview
+from .registry import Registry
+from .matcher import Matcher
+from .installer import Installer
+from .doctor import Doctor
+
+
+class SkillFinderCLI:
+    """skill-finder CLI 主入口"""
+    
+    def __init__(self):
+        self.registry = Registry()
+        self.matcher = Matcher(self.registry)
+        self.installer = Installer()
+        self.doctor = Doctor(self.registry)
+    
+    def run(self):
+        """主流程"""
+        print("=== skill-finder ===")
+        print("发现/匹配/安装第三方 skill 库\n")
+        
+        interview = Interview()
+        query = interview.collect()
+        
+        print("\n=== 匹配结果 ===")
+        result = self.matcher.match(query)
+        
+        if not result.matches:
+            print(f"✗ 未找到匹配的第三方能力\n")
+            print(f"拒绝原因: {result.rejection_reason}")
+            print(f"建议: 尝试使用 skill-creator 创建自研 skill")
+            return
+        
+        print(f"找到 {len(result.matches)} 个匹配的能力：\n")
+        
+        for i, match in enumerate(result.matches, 1):
+            print(f"【{i}】{match.unit.name} ({match.package.name})")
+            print(f"- 描述: {match.unit.description}")
+            print(f"- 匹配原因: {'; '.join(match.reasons)}")
+            print(f"- 置信度: {match.score:.2f}")
+            print(f"- README: {match.package.docs.readme}")
+            
+            if match.warnings:
+                print(f"- ⚠ 警告: {'; '.join(match.warnings)}")
+            print()
+        
+        choice = input("选择要安装的能力 [1]: ").strip() or "1"
+        
+        try:
+            idx = int(choice) - 1
+            if idx < 0 or idx >= len(result.matches):
+                print("无效选择")
+                return
+        except ValueError:
+            print("无效选择")
+            return
+        
+        selected = result.matches[idx]
+        
+        print("\n=== 安装方式 ===")
+        print("[1] 自动安装（默认）")
+        print("[2] 手动安装（仅输出命令）")
+        
+        mode_choice = input("选择 [1]: ").strip() or "1"
+        mode = "manual" if mode_choice == "2" else "auto"
+        
+        record = self.installer.install(selected, mode=mode)
+        
+        if record.result == "success" or record.result == "skipped":
+            print("\n=== 使用方式 ===")
+            for ep in selected.unit.entrypoints:
+                print(f"命令: {ep.command}")
+                if ep.args:
+                    print(f"参数: {ep.args}")
+                if ep.cwd:
+                    print(f"工作目录: {ep.cwd}")
+                if ep.examples:
+                    print("示例:")
+                    for example in ep.examples:
+                        print(f"  {example}")
+                print()
+            
+            print(f"详细文档: {selected.package.docs.readme}")
+            
+            if selected.unit.usage_notes:
+                print(f"\n使用说明:\n{selected.unit.usage_notes}")
+
+
+def main():
+    """CLI 入口"""
+    if len(sys.argv) > 1 and sys.argv[1] == "doctor":
+        from .models import SearchQuery
+        doctor = Doctor()
+        query = SearchQuery(goal="测试", ide="windsurf")
+        print(doctor.show_install_records())
+    else:
+        cli = SkillFinderCLI()
+        cli.run()
+
+
+if __name__ == "__main__":
+    main()

package/src/skill_finder/doctor.py

@@ -0,0 +1,105 @@
+"""诊断与 trace"""
+
+from typing import Optional
+from .models import SearchQuery, SearchResult
+from .registry import Registry
+from .matcher import Matcher
+from .install_record import InstallRecordManager
+
+
+class Doctor:
+    """诊断工具 - 提供匹配 trace 和安装记录分析"""
+    
+    def __init__(self, registry: Optional[Registry] = None, 
+                 record_manager: Optional[InstallRecordManager] = None):
+        if registry is None:
+            registry = Registry()
+        if record_manager is None:
+            record_manager = InstallRecordManager()
+        
+        self.registry = registry
+        self.matcher = Matcher(registry)
+        self.record_manager = record_manager
+    
+    def trace_match(self, query: SearchQuery) -> str:
+        """输出匹配 trace"""
+        output = ["=== skill-finder Doctor Trace ===\n"]
+        
+        output.append("【匹配 Trace】")
+        output.append(f"- Query: goal=\"{query.goal}\", tags={query.tags}, ide=\"{query.ide}\"")
+        
+        candidates = self.matcher._coarse_filter(query)
+        output.append(f"- 粗筛命中: {len(candidates)} 个候选")
+        
+        if candidates:
+            for tag in (query.tags or []):
+                units = self.registry.search_by_tag(tag)
+                if units:
+                    output.append(f"  - Tag '{tag}': {len(units)} 个 unit")
+        
+        result = self.matcher.match(query)
+        
+        if result.matches:
+            output.append("- 精排结果:")
+            for i, match in enumerate(result.matches[:3], 1):
+                output.append(f"  {i}. {match.unit.unit_id} (score={match.score:.2f})")
+                output.append(f"     - {', '.join(match.reasons)}")
+            output.append(f"- 最终返回: Top {len(result.matches)}")
+        else:
+            output.append(f"- 拒绝原因: {result.rejection_reason}")
+            output.append(f"- 拒绝分类: {result.rejection_category}")
+        
+        return "\n".join(output)
+    
+    def show_install_records(self, n: int = 5) -> str:
+        """显示最近的安装记录"""
+        output = ["\n【安装记录（最近 {} 条）】".format(n)]
+        
+        records = self.record_manager.get_recent(n)
+        
+        if not records:
+            output.append("- 暂无安装记录")
+            return "\n".join(output)
+        
+        for i, record in enumerate(records, 1):
+            status_icon = "✓" if record.result == "success" else "✗" if record.result == "failed" else "○"
+            output.append(f"{i}. {record.timestamp[:10]} {record.timestamp[11:19]} | {record.unit_id} | {record.install_mode} | {status_icon} {record.result}")
+            
+            if record.result == "failed" and record.error_summary:
+                error_preview = record.error_summary[:100].replace("\n", " ")
+                output.append(f"   错误: {error_preview}...")
+        
+        return "\n".join(output)
+    
+    def suggest_fix(self, package_id: str) -> str:
+        """针对安装失败提供修复建议"""
+        output = ["\n【冲突/异常建议】"]
+        
+        records = self.record_manager.filter_by_package(package_id)
+        failed = [r for r in records if r.result == "failed"]
+        
+        if not failed:
+            output.append(f"- Package {package_id} 无失败记录")
+            return "\n".join(output)
+        
+        last_failed = failed[-1]
+        
+        package = self.registry.get_package(package_id)
+        if package and package.install.uninstall_cmd:
+            output.append(f"- 若安装失败，尝试重装:")
+            output.append(f"  {package.install.uninstall_cmd} && {package.install.auto_install_cmd}")
+        else:
+            output.append(f"- 建议手动检查错误信息并重试安装")
+        
+        if last_failed.error_summary:
+            output.append(f"\n最近错误摘要:")
+            output.append(f"  {last_failed.error_summary[:200]}")
+        
+        return "\n".join(output)
+    
+    def full_report(self, query: SearchQuery) -> str:
+        """完整诊断报告"""
+        output = []
+        output.append(self.trace_match(query))
+        output.append(self.show_install_records())
+        return "\n".join(output)

package/src/skill_finder/install_record.py

@@ -0,0 +1,58 @@
+"""安装记录管理"""
+
+import json
+from pathlib import Path
+from typing import List, Optional
+from datetime import datetime
+from .models import InstallRecord
+
+
+class InstallRecordManager:
+    """安装记录管理器"""
+    
+    def __init__(self, record_path: Optional[Path] = None):
+        if record_path is None:
+            record_path = Path.home() / ".omni-skill" / "install_records.json"
+        
+        self.record_path = Path(record_path)
+        self.record_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        if not self.record_path.exists():
+            self._save_records([])
+    
+    def add(self, record: InstallRecord):
+        """添加安装记录"""
+        records = self.load_all()
+        records.append(record.dict())
+        self._save_records(records)
+    
+    def load_all(self) -> List[dict]:
+        """加载所有记录"""
+        try:
+            with open(self.record_path, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except Exception:
+            return []
+    
+    def get_recent(self, n: int = 10) -> List[InstallRecord]:
+        """获取最近 N 条记录"""
+        records = self.load_all()
+        recent = records[-n:] if len(records) > n else records
+        return [InstallRecord(**r) for r in reversed(recent)]
+    
+    def filter_by_package(self, package_id: str) -> List[InstallRecord]:
+        """按 package_id 过滤"""
+        records = self.load_all()
+        filtered = [r for r in records if r.get("package_id") == package_id]
+        return [InstallRecord(**r) for r in filtered]
+    
+    def filter_by_unit(self, unit_id: str) -> List[InstallRecord]:
+        """按 unit_id 过滤"""
+        records = self.load_all()
+        filtered = [r for r in records if r.get("unit_id") == unit_id]
+        return [InstallRecord(**r) for r in filtered]
+    
+    def _save_records(self, records: List[dict]):
+        """保存记录"""
+        with open(self.record_path, 'w', encoding='utf-8') as f:
+            json.dump(records, f, indent=2, ensure_ascii=False)

package/src/skill_finder/installer.py

@@ -0,0 +1,117 @@
+"""安装执行器"""
+
+import subprocess
+from datetime import datetime
+from typing import Literal, Optional
+from .models import MatchResult, InstallRecord
+from .install_record import InstallRecordManager
+
+
+class Installer:
+    """安装执行器 - 支持自动/手动两种模式"""
+    
+    def __init__(self, record_manager: Optional[InstallRecordManager] = None):
+        if record_manager is None:
+            record_manager = InstallRecordManager()
+        self.record_manager = record_manager
+    
+    def install(self, match: MatchResult, mode: Literal["auto", "manual"] = "auto") -> InstallRecord:
+        """执行安装"""
+        package = match.package
+        unit = match.unit
+        
+        if mode == "manual":
+            return self._manual_install(package, unit)
+        else:
+            return self._auto_install(package, unit)
+    
+    def _manual_install(self, package, unit) -> InstallRecord:
+        """手动安装模式 - 仅输出命令"""
+        print(f"\n=== 手动安装 {package.name} ===")
+        print(package.install.manual_install_cmd)
+        
+        if package.install.notes:
+            print(f"\n注意事项：\n{package.install.notes}")
+        
+        print("\n已记录安装指令。请手动执行上述命令。")
+        
+        record = InstallRecord(
+            timestamp=datetime.now().isoformat(),
+            unit_id=unit.unit_id,
+            package_id=package.package_id,
+            install_mode="manual",
+            executed=False,
+            method=package.install.method,
+            commands=package.install.manual_install_cmd,
+            result="skipped",
+            error_summary=None,
+            docs_links=package.docs
+        )
+        
+        self.record_manager.add(record)
+        return record
+    
+    def _auto_install(self, package, unit) -> InstallRecord:
+        """自动安装模式 - 执行命令"""
+        print(f"\n=== 自动安装 {package.name} ===")
+        
+        if package.install.notes:
+            print(f"注意事项: {package.install.notes}")
+        
+        print(f"\n执行命令：\n{package.install.auto_install_cmd}\n")
+        
+        try:
+            result = subprocess.run(
+                package.install.auto_install_cmd,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=300
+            )
+            
+            if result.returncode == 0:
+                print("✓ 安装成功")
+                record = InstallRecord(
+                    timestamp=datetime.now().isoformat(),
+                    unit_id=unit.unit_id,
+                    package_id=package.package_id,
+                    install_mode="auto",
+                    executed=True,
+                    method=package.install.method,
+                    commands=package.install.auto_install_cmd,
+                    result="success",
+                    error_summary=None,
+                    docs_links=package.docs
+                )
+            else:
+                print(f"✗ 安装失败\n{result.stderr}")
+                record = InstallRecord(
+                    timestamp=datetime.now().isoformat(),
+                    unit_id=unit.unit_id,
+                    package_id=package.package_id,
+                    install_mode="auto",
+                    executed=True,
+                    method=package.install.method,
+                    commands=package.install.auto_install_cmd,
+                    result="failed",
+                    error_summary=result.stderr[:500] if result.stderr else None,
+                    docs_links=package.docs
+                )
+        
+        except Exception as e:
+            print(f"✗ 安装异常：{e}")
+            record = InstallRecord(
+                timestamp=datetime.now().isoformat(),
+                unit_id=unit.unit_id,
+                package_id=package.package_id,
+                install_mode="auto",
+                executed=True,
+                method=package.install.method,
+                commands=package.install.auto_install_cmd,
+                result="failed",
+                error_summary=str(e)[:500],
+                docs_links=package.docs
+            )
+        
+        self.record_manager.add(record)
+        return record

package/src/skill_finder/interview.py

@@ -0,0 +1,101 @@
+"""两级提问逻辑"""
+
+from typing import Dict, List, Optional
+from .models import SearchQuery
+
+
+class Interview:
+    """最小两级提问收集需求"""
+    
+    LEVEL1_QUESTIONS = [
+        {
+            "id": "goal",
+            "text": "你想实现什么目标？（一句话描述任务）",
+            "required": True
+        },
+        {
+            "id": "input",
+            "text": "输入是什么？（文件/代码/数据/命令等）",
+            "required": False,
+            "default": "任意"
+        },
+        {
+            "id": "env",
+            "text": "运行环境？（OS/Shell/Runtime，如 Windows/Linux/Python/Node）",
+            "required": False,
+            "default": "通用"
+        },
+        {
+            "id": "ide",
+            "text": "使用哪个 IDE/编辑器？（windsurf/cursor/vscode/generic）",
+            "required": True
+        }
+    ]
+    
+    def collect(self) -> SearchQuery:
+        """收集需求"""
+        answers = {}
+        
+        print("=== 需求收集（Level 1）===\n")
+        for q in self.LEVEL1_QUESTIONS:
+            if q["required"]:
+                answer = input(f"{q['text']}: ").strip()
+                while not answer:
+                    answer = input(f"{q['text']}（必填）: ").strip()
+                answers[q["id"]] = answer
+            else:
+                default_hint = f" [默认: {q.get('default', '跳过')}]" if q.get('default') else ""
+                answer = input(f"{q['text']}{default_hint}: ").strip()
+                answers[q["id"]] = answer if answer else q.get("default")
+        
+        if self._needs_clarification(answers):
+            print("\n=== 补充信息（Level 2）===\n")
+            
+            if len(answers["goal"].split()) < 3:
+                detail = input("能否详细描述一下具体要做什么？: ").strip()
+                if detail:
+                    answers["goal"] += f" - {detail}"
+            
+            constraints = input("有什么硬约束吗？（如不可联网/必须离线/不可修改文件等，无则回车）: ").strip()
+            if constraints:
+                answers["constraints"] = [c.strip() for c in constraints.split(",")]
+        
+        return SearchQuery(
+            goal=answers["goal"],
+            input_type=answers.get("input"),
+            env=answers.get("env"),
+            ide=answers["ide"],
+            constraints=answers.get("constraints"),
+            tags=self._extract_tags(answers["goal"]),
+            keywords=self._extract_keywords(answers["goal"])
+        )
+    
+    def _needs_clarification(self, answers: Dict) -> bool:
+        """判断是否需要 Level 2"""
+        return len(answers["goal"].split()) < 5
+    
+    def _extract_tags(self, goal: str) -> List[str]:
+        """从 goal 提取 tags（简单关键词映射）"""
+        tag_map = {
+            "代码": "code-generation",
+            "生成": "code-generation",
+            "重构": "code-refactoring",
+            "git": "git-integration",
+            "commit": "git-commit",
+            "多文件": "multi-file-editing",
+            "测试": "testing",
+            "文档": "documentation",
+            "编辑": "code-generation",
+        }
+        tags = []
+        goal_lower = goal.lower()
+        for keyword, tag in tag_map.items():
+            if keyword in goal_lower:
+                if tag not in tags:
+                    tags.append(tag)
+        return tags
+    
+    def _extract_keywords(self, goal: str) -> List[str]:
+        """提取关键词"""
+        words = goal.split()
+        return [w.strip() for w in words if len(w.strip()) > 2]

package/src/skill_finder/matcher.py

@@ -0,0 +1,159 @@
+"""匹配算法实现 - 两阶段匹配"""
+
+from typing import List, Dict, Set
+from .models import SearchQuery, SearchResult, MatchResult
+from .registry import Registry
+
+
+class Matcher:
+    """匹配器 - 两阶段匹配算法"""
+    
+    def __init__(self, registry: Registry, min_score: float = 0.6):
+        self.registry = registry
+        self.min_score = min_score
+    
+    def match(self, query: SearchQuery) -> SearchResult:
+        """执行两阶段匹配"""
+        candidates = self._coarse_filter(query)
+        
+        if not candidates:
+            return SearchResult(
+                query=query,
+                matches=[],
+                rejection_reason="未找到匹配的能力标签或关键词",
+                rejection_category="no_candidates_by_tag"
+            )
+        
+        scored = self._fine_rank(candidates, query)
+        filtered = [m for m in scored if m.score >= self.min_score]
+        
+        if not filtered:
+            rejection = self._analyze_rejection(candidates, query)
+            return SearchResult(
+                query=query,
+                matches=[],
+                rejection_reason=rejection["reason"],
+                rejection_category=rejection["category"]
+            )
+        
+        return SearchResult(
+            query=query,
+            matches=filtered[:3],
+            rejection_reason=None,
+            rejection_category=None
+        )
+    
+    def _coarse_filter(self, query: SearchQuery) -> List[str]:
+        """阶段 1: 粗筛 - 倒排索引命中"""
+        unit_ids = set()
+        
+        if query.tags:
+            for tag in query.tags:
+                unit_ids.update(self.registry.search_by_tag(tag))
+        
+        if query.keywords:
+            for kw in query.keywords:
+                unit_ids.update(self.registry.search_by_keyword(kw))
+        
+        if query.ide:
+            ide_units = set(self.registry.search_by_ide(query.ide))
+            if unit_ids:
+                unit_ids &= ide_units
+            else:
+                unit_ids = ide_units
+        
+        return list(unit_ids)
+    
+    def _fine_rank(self, unit_ids: List[str], query: SearchQuery) -> List[MatchResult]:
+        """阶段 2: 精排 - 计算置信度分数"""
+        results = []
+        
+        for uid in unit_ids:
+            unit = self.registry.get_unit(uid)
+            if not unit:
+                continue
+            
+            package = self.registry.get_package(unit.package_id)
+            if not package:
+                continue
+            
+            score = 0.0
+            reasons = []
+            warnings = []
+            
+            if query.tags:
+                matched_tags = set(t.lower() for t in query.tags) & set(t.lower() for t in unit.capability_tags)
+                if matched_tags:
+                    tag_coverage = len(matched_tags) / len(query.tags)
+                    score += tag_coverage * 0.6
+                    reasons.append(f"匹配标签: {', '.join(matched_tags)}")
+            
+            if query.keywords:
+                matched_kw = set(kw.lower() for kw in query.keywords) & set(kw.lower() for kw in unit.keywords)
+                if matched_kw:
+                    kw_score = len(matched_kw) / len(query.keywords)
+                    score += kw_score * 0.3
+                    reasons.append(f"匹配关键词: {', '.join(matched_kw)}")
+            
+            if query.ide:
+                if query.ide.lower() in [ide.lower() for ide in unit.ide_support]:
+                    score += 0.1
+                    reasons.append(f"支持 {query.ide}")
+                else:
+                    score *= 0.2
+                    warnings.append(f"不支持 {query.ide}（仅支持 {', '.join(unit.ide_support)}）")
+            
+            if query.env and unit.conflicts:
+                if query.env.lower() in unit.conflicts.lower():
+                    score *= 0.3
+                    warnings.append(f"可能与 {query.env} 环境冲突")
+            
+            if query.constraints:
+                for constraint in query.constraints:
+                    if "no-network" in constraint.lower() and "network" in unit.description.lower():
+                        score *= 0.5
+                        warnings.append("可能需要网络访问，与约束冲突")
+            
+            results.append(MatchResult(
+                unit=unit,
+                package=package,
+                score=score,
+                reasons=reasons,
+                warnings=warnings if warnings else None
+            ))
+        
+        results.sort(key=lambda x: x.score, reverse=True)
+        return results
+    
+    def _analyze_rejection(self, candidates: List[str], query: SearchQuery) -> Dict:
+        """分析拒绝原因"""
+        if not candidates:
+            return {
+                "reason": "未找到匹配的能力标签或关键词",
+                "category": "no_candidates_by_tag"
+            }
+        
+        if query.ide:
+            ide_supported = False
+            for uid in candidates:
+                unit = self.registry.get_unit(uid)
+                if unit and query.ide.lower() in [ide.lower() for ide in unit.ide_support]:
+                    ide_supported = True
+                    break
+            
+            if not ide_supported:
+                return {
+                    "reason": f"找到候选能力，但均不支持 {query.ide}",
+                    "category": "candidates_but_no_ide_support"
+                }
+        
+        if query.env or query.constraints:
+            return {
+                "reason": "找到候选能力，但均不满足环境或约束条件",
+                "category": "candidates_but_incompatible_env"
+            }
+        
+        return {
+            "reason": "候选能力置信度不足（< 60%），建议补充更多需求信息",
+            "category": "insufficient_info"
+        }

package/src/skill_finder/models.py

@@ -0,0 +1,117 @@
+"""skill-finder 核心数据结构定义"""
+
+from typing import Literal, Optional, List, Dict
+from pydantic import BaseModel, Field
+
+
+class InstallerSpec(BaseModel):
+    """安装器规范"""
+    method: Literal["git", "pip", "npm", "release_asset"]
+    auto_install_cmd: str = Field(..., description="自动安装执行的命令（可多行）")
+    manual_install_cmd: str = Field(..., description="手动安装给用户的命令（可多行）")
+    uninstall_cmd: Optional[str] = Field(None, description="卸载命令（可选）")
+    notes: Optional[str] = Field(None, description="安装注意事项")
+
+
+class SourceSpec(BaseModel):
+    """源信息"""
+    type: Literal["git", "pip", "npm", "release_asset"]
+    repo: Optional[str] = None
+    url: Optional[str] = None
+    package: Optional[str] = None
+    ref: Optional[str] = None
+    tag: Optional[str] = None
+    commit: Optional[str] = None
+    version: Optional[str] = None
+
+
+class DocsSpec(BaseModel):
+    """文档链接"""
+    readme: str = Field(..., description="README 链接（必须）")
+    homepage: Optional[str] = None
+    issues: Optional[str] = None
+
+
+class SkillPackage(BaseModel):
+    """Package 定义（安装载体）"""
+    package_id: str = Field(..., description="唯一标识：gh:owner/repo | pip:pkg | npm:pkg")
+    name: str
+    description: str
+    source: SourceSpec
+    docs: DocsSpec
+    supported_ides: List[str] = Field(..., description="包级 IDE 支持")
+    install: InstallerSpec
+    units: List[str] = Field(..., description="包含的 unit_id 列表")
+    trust_level: Optional[Literal["trusted", "experimental", "deprecated"]] = "trusted"
+    notes: Optional[str] = None
+
+
+class EntrypointSpec(BaseModel):
+    """使用入口"""
+    command: str = Field(..., description="原生命令")
+    args: Optional[str] = Field(None, description="参数说明")
+    cwd: Optional[str] = Field(None, description="工作目录要求")
+    examples: Optional[List[str]] = Field(None, description="使用示例")
+
+
+class SkillUnit(BaseModel):
+    """Unit 定义（能力单元，匹配维度）"""
+    unit_id: str = Field(..., description="唯一标识：gh:owner/repo#skill-a")
+    package_id: str = Field(..., description="所属 package")
+    name: str
+    description: str
+    capability_tags: List[str] = Field(..., description="能力标签")
+    keywords: List[str] = Field(..., description="关键词")
+    ide_support: List[str] = Field(..., description="IDE 支持列表")
+    entrypoints: List[EntrypointSpec] = Field(..., description="使用入口")
+    docs_override: Optional[DocsSpec] = None
+    usage_notes: Optional[str] = Field(None, description="10-20 行微摘要")
+    conflicts: Optional[str] = Field(None, description="已知冲突/注意事项")
+
+
+class SearchQuery(BaseModel):
+    """搜索查询"""
+    goal: str
+    input_type: Optional[str] = None
+    output_type: Optional[str] = None
+    env: Optional[str] = None
+    ide: Optional[str] = None
+    constraints: Optional[List[str]] = None
+    tags: Optional[List[str]] = None
+    keywords: Optional[List[str]] = None
+
+
+class MatchResult(BaseModel):
+    """匹配结果"""
+    unit: SkillUnit
+    package: SkillPackage
+    score: float
+    reasons: List[str] = Field(..., description="匹配原因")
+    warnings: Optional[List[str]] = None
+
+
+class SearchResult(BaseModel):
+    """搜索结果"""
+    query: SearchQuery
+    matches: List[MatchResult]
+    rejection_reason: Optional[str] = None
+    rejection_category: Optional[Literal[
+        "no_candidates_by_tag",
+        "candidates_but_no_ide_support",
+        "candidates_but_incompatible_env",
+        "insufficient_info"
+    ]] = None
+
+
+class InstallRecord(BaseModel):
+    """安装记录"""
+    timestamp: str
+    unit_id: str
+    package_id: str
+    install_mode: Literal["auto", "manual"]
+    executed: bool
+    method: str
+    commands: str
+    result: Literal["success", "failed", "skipped"]
+    error_summary: Optional[str] = None
+    docs_links: DocsSpec

package/src/skill_finder/recommender.py

@@ -0,0 +1,51 @@
+"""被动推荐接口 - 供 skill-creator 调用"""
+
+from typing import Optional
+from .models import SearchQuery, SearchResult
+from .registry import Registry
+from .matcher import Matcher
+
+
+class Recommender:
+    """推荐器 - 被动推荐接口"""
+    
+    def __init__(self, registry: Optional[Registry] = None, min_score: float = 0.7):
+        """
+        初始化推荐器
+        
+        Args:
+            registry: Registry 实例（可选）
+            min_score: 最小置信度（推荐模式使用更高阈值 0.7）
+        """
+        if registry is None:
+            registry = Registry()
+        
+        self.registry = registry
+        self.matcher = Matcher(registry, min_score=min_score)
+    
+    def recommend(self, query: SearchQuery) -> SearchResult:
+        """
+        推荐第三方 unit（高置信度）
+        
+        Args:
+            query: 搜索查询
+            
+        Returns:
+            SearchResult: 仅返回高置信度结果（>= 0.7），否则返回空
+        """
+        result = self.matcher.match(query)
+        
+        if result.matches and result.matches[0].score >= 0.7:
+            return SearchResult(
+                query=query,
+                matches=result.matches[:1],
+                rejection_reason=None,
+                rejection_category=None
+            )
+        
+        return SearchResult(
+            query=query,
+            matches=[],
+            rejection_reason="未找到高置信度推荐（< 70%）",
+            rejection_category="insufficient_info"
+        )

package/src/skill_finder/registry.py

@@ -0,0 +1,108 @@
+"""Registry 加载与索引查询"""
+
+import json
+from pathlib import Path
+from typing import Dict, List, Optional
+from .models import SkillPackage, SkillUnit
+
+
+class Registry:
+    """Registry 管理器 - 加载 packages/units 和索引"""
+    
+    def __init__(self, registry_root: Optional[Path] = None):
+        if registry_root is None:
+            registry_root = Path(__file__).parent.parent.parent / "data" / "third_party"
+        
+        self.registry_root = Path(registry_root)
+        self.packages_dir = self.registry_root / "packages"
+        self.units_dir = self.registry_root / "units"
+        self.indexes_dir = self.registry_root / "indexes"
+        
+        self._packages_cache: Dict[str, SkillPackage] = {}
+        self._units_cache: Dict[str, SkillUnit] = {}
+        self.indexes: Dict[str, dict] = {}
+        
+        self._load_indexes()
+    
+    def _load_indexes(self):
+        """加载所有索引文件"""
+        if not self.indexes_dir.exists():
+            raise FileNotFoundError(f"索引目录不存在: {self.indexes_dir}")
+        
+        index_files = {
+            "by_tag": "units.by_tag.json",
+            "by_keyword": "units.by_keyword.json",
+            "by_ide": "units.by_ide.json",
+            "packages_all": "packages.all.json",
+            "units_all": "units.all.json",
+        }
+        
+        for key, filename in index_files.items():
+            index_path = self.indexes_dir / filename
+            if index_path.exists():
+                with open(index_path, 'r', encoding='utf-8') as f:
+                    self.indexes[key] = json.load(f)
+            else:
+                self.indexes[key] = {} if key != "packages_all" and key != "units_all" else []
+    
+    def get_package(self, package_id: str) -> Optional[SkillPackage]:
+        """获取 package（带缓存）"""
+        if package_id in self._packages_cache:
+            return self._packages_cache[package_id]
+        
+        sanitized_id = package_id.replace(":", "_").replace("/", "_")
+        package_path = self.packages_dir / f"{sanitized_id}.json"
+        
+        if not package_path.exists():
+            return None
+        
+        try:
+            with open(package_path, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+                package = SkillPackage(**data)
+                self._packages_cache[package_id] = package
+                return package
+        except Exception as e:
+            print(f"加载 package {package_id} 失败: {e}")
+            return None
+    
+    def get_unit(self, unit_id: str) -> Optional[SkillUnit]:
+        """获取 unit（带缓存）"""
+        if unit_id in self._units_cache:
+            return self._units_cache[unit_id]
+        
+        sanitized_id = unit_id.replace(":", "_").replace("/", "_")
+        unit_path = self.units_dir / f"{sanitized_id}.json"
+        
+        if not unit_path.exists():
+            return None
+        
+        try:
+            with open(unit_path, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+                unit = SkillUnit(**data)
+                self._units_cache[unit_id] = unit
+                return unit
+        except Exception as e:
+            print(f"加载 unit {unit_id} 失败: {e}")
+            return None
+    
+    def search_by_tag(self, tag: str) -> List[str]:
+        """通过 tag 搜索 unit_id 列表"""
+        return self.indexes.get("by_tag", {}).get(tag.lower(), [])
+    
+    def search_by_keyword(self, keyword: str) -> List[str]:
+        """通过 keyword 搜索 unit_id 列表"""
+        return self.indexes.get("by_keyword", {}).get(keyword.lower(), [])
+    
+    def search_by_ide(self, ide: str) -> List[str]:
+        """通过 IDE 搜索 unit_id 列表"""
+        return self.indexes.get("by_ide", {}).get(ide.lower(), [])
+    
+    def get_all_packages(self) -> List[str]:
+        """获取所有 package_id"""
+        return self.indexes.get("packages_all", [])
+    
+    def get_all_units(self) -> List[str]:
+        """获取所有 unit_id"""
+        return self.indexes.get("units_all", [])