sra-agent 0.0.0.dev0__py3-none-any.whl

skill_advisor/__init__.py

@@ -0,0 +1,41 @@
+# SRA Agent — Skill Runtime Advisor
+# 让 AI Agent 知道自己有什么能力，以及什么时候该用什么能力。
+# License: MIT
+
+# ⚠️ 版本号由 setuptools-scm 从 git tag 自动生成
+# 不要手动修改！版本来源见 pyproject.toml [tool.setuptools_scm]
+# 层级 1: setuptools-scm 生成的 _version.py（built 包）
+try:
+    from ._version import version as __version__
+except ImportError:
+    try:
+        # 层级 2: importlib.metadata（editable install + pip install）
+        from importlib.metadata import version as _v
+        __version__ = _v("sra-agent")
+    except (ImportError, ModuleNotFoundError):
+        # 层级 3: git describe（开发环境 fallback）
+        try:
+            import os
+            import subprocess
+            tag = subprocess.check_output(
+                ["git", "describe", "--tags", "--dirty=.dirty", "--always"],
+                cwd=os.path.dirname(os.path.abspath(__file__)),
+                stderr=subprocess.DEVNULL,
+                timeout=5,
+            ).decode().strip().lstrip("v")
+            __version__ = tag
+        except Exception:
+            __version__ = "0.0.0-dev"
+
+__author__ = "Emma (SRA Team), Kei"
+
+from .adapters import get_adapter, list_adapters
+from .advisor import SkillAdvisor
+from .runtime.daemon import SRaDDaemon
+
+__all__ = [
+    "SkillAdvisor",
+    "SRaDDaemon",
+    "get_adapter",
+    "list_adapters",
+]

skill_advisor/adapters/__init__.py

@@ -0,0 +1,313 @@
+"""
+SRA Agent 适配器 — 让 SRA 能接入任何 AI Agent 系统
+
+适配器将 SRA 的推荐结果转换成特定 Agent 能理解的格式。
+每种 Agent 一个适配器类，统一接口。
+
+支持的 Agent:
+  - Hermes Agent (原生)
+  - Claude Code (Anthropic CLI)
+  - OpenAI Codex CLI
+  - OpenCode CLI
+  - 通用 OpenAI API 格式
+"""
+
+import json
+import os
+import socket
+import sys
+from typing import Dict, List
+
+# ── Socket 客户端 ───────────────────────────
+
+SOCKET_FILE = os.path.expanduser("~/.sra/srad.sock")
+
+
+def _sra_socket_request(request: dict, timeout: float = 5.0) -> dict:
+    """通过 Unix Socket 向 SRA Daemon 发送请求"""
+    if not os.path.exists(SOCKET_FILE):
+        return {"error": "SRA Daemon 未运行", "suggestion": "请先运行 'sra start'"}
+
+    try:
+        client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        client.settimeout(timeout)
+        client.connect(SOCKET_FILE)
+        client.sendall(json.dumps(request).encode("utf-8"))
+        response = client.recv(65536).decode("utf-8")
+        client.close()
+        return json.loads(response)
+    except socket.timeout:
+        return {"error": "SRA Daemon 超时"}
+    except ConnectionRefusedError:
+        return {"error": "SRA Daemon 连接被拒", "suggestion": "请检查 'sra status'"}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# ── 基础适配器接口 ─────────────────────────
+
+class BaseAdapter:
+    """所有 Agent 适配器的基类"""
+
+    def __init__(self, socket_path: str = SOCKET_FILE):
+        self.socket_path = socket_path
+
+    def recommend(self, query: str, top_k: int = 3) -> List[Dict]:
+        """推荐技能 — 所有适配器共享的核心逻辑"""
+        result = _sra_socket_request({
+            "action": "recommend",
+            "params": {"query": query, "top_k": top_k},
+        })
+        if "error" in result:
+            return []
+        return result.get("result", {}).get("recommendations", [])
+
+    def format_suggestion(self, recommendations: List[Dict]) -> str:
+        """将推荐结果格式化为该 Agent 的提示文本"""
+        raise NotImplementedError
+
+    def ping(self) -> bool:
+        """检查 SRA Daemon 是否运行"""
+        result = _sra_socket_request({"action": "ping"})
+        return result.get("pong", False) and result.get("status") == "ok"
+
+
+# ── Hermes Agent 适配器 ─────────────────────
+
+class HermesAdapter(BaseAdapter):
+    """Hermes Agent 适配器 — 生成 <available_skills> 增强块"""
+
+    def format_suggestion(self, recommendations: List[Dict]) -> str:
+        if not recommendations:
+            return ""
+
+        lines = ["💡 SRA 技能推荐:"]
+        for r in recommendations:
+            icon = "✅" if r.get("confidence") == "high" else "💡"
+            lines.append(
+                f"  {icon} `{r['skill']}` (得分: {r['score']})"
+            )
+            if r.get("reasons"):
+                lines.append(f"     理由: {'; '.join(r['reasons'][:2])}")
+
+        top = recommendations[0]
+        if top.get("confidence") == "high":
+            lines.append(f"\n⚡ 建议自动加载: skill_view('{top['skill']}')")
+
+        return "\n".join(lines)
+
+    def to_system_prompt_block(self, skills_count: int = None) -> str:
+        """生成增强版 system prompt 块"""
+        stats = _sra_socket_request({"action": "stats"})
+        if "error" in stats:
+            return ""
+
+        s = stats.get("stats", stats)
+        count = skills_count or s.get("skills_count", 0)
+
+        return (
+            f"\n## SRA Runtime ({s.get('version', '1.2.1')})\n"
+            f"SRA 是一个独立运行的技能推荐引擎。\n"
+            f"当前管理 {count} 个技能。\n"
+            f"API: Unix Socket ({SOCKET_FILE}) / HTTP (:{s.get('config', {}).get('http_port', 8536)})\n"
+            f"使用 'sra --query <输入>' 或 HTTP POST 查询推荐。\n"
+        )
+
+    def to_proxy_format(self, message: str) -> dict:
+        """以 Proxy 格式获取推荐（消息前置推理用）
+        
+        POST /recommend 请求 {'message': msg} 的响应格式。
+        返回 rag_context + should_auto_load + recommendations。
+        """
+        result = _sra_socket_request({
+            "action": "recommend",
+            "params": {"query": message, "top_k": 5},
+        })
+        if "error" in result:
+            return {
+                "rag_context": "",
+                "recommendations": [],
+                "top_skill": None,
+                "should_auto_load": False,
+                "sra_available": False,
+            }
+
+        recs = result.get("result", {}).get("recommendations", [])
+        top_skill = None
+        should_auto_load = False
+        rag_lines = []
+
+        if recs:
+            top = recs[0]
+            top_skill = top["skill"]
+            score = top["score"]
+            should_auto_load = score >= 80
+
+            rag_lines.append("── [SRA Skill 推荐] ──────────────────────────────")
+            for i, r in enumerate(recs[:5]):
+                flag = "⭐" if i == 0 else "  "
+                conf = r["confidence"]
+                s_name = r["skill"]
+                s_score = r["score"]
+                s_reasons = " | ".join(r.get("reasons", [])[:2])
+                rag_lines.append(f"  {flag} [{conf:>6}] {s_name} ({s_score:.1f}分) — {s_reasons}")
+
+            if should_auto_load:
+                rag_lines.append(f"\n  ⚡ 强推荐自动加载: {top_skill}")
+            else:
+                rag_lines.append("\n  💡 建议: 可参考上述 skill")
+
+            rag_lines.append("── ──────────────────────────────────────────────")
+
+        return {
+            "rag_context": "\n".join(rag_lines),
+            "recommendations": [
+                {
+                    "skill": r["skill"],
+                    "score": r["score"],
+                    "confidence": r["confidence"],
+                    "reasons": r.get("reasons", []),
+                    "description": r.get("description", ""),
+                }
+                for r in recs[:5]
+            ],
+            "top_skill": top_skill,
+            "should_auto_load": should_auto_load,
+            "sra_available": True,
+        }
+
+
+# ── Claude Code 适配器 ──────────────────────
+
+class ClaudeCodeAdapter(BaseAdapter):
+    """Anthropic Claude Code CLI 适配器"""
+
+    def format_suggestion(self, recommendations: List[Dict]) -> str:
+        if not recommendations:
+            return ""
+
+        lines = ["[SRA Skill Recommendation]"]
+        for r in recommendations[:2]:
+            lines.append(f"- {r['skill']} (confidence: {r.get('confidence', 'medium')})")
+            if r.get("description"):
+                lines.append(f"  {r['description'][:80]}")
+
+        return "\n".join(lines)
+
+    def to_claude_tool_format(self, recommendations: List[Dict]) -> List[Dict]:
+        """转换为 Claude Tool Use 格式"""
+        tools = []
+        for r in recommendations[:3]:
+            tools.append({
+                "name": r["skill"],
+                "description": r.get("description", "")[:200],
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "task": {
+                            "type": "string",
+                            "description": f"Use {r['skill']} to handle the user request"
+                        }
+                    },
+                    "required": ["task"]
+                }
+            })
+        return tools
+
+
+# ── OpenAI Codex CLI 适配器 ─────────────────
+
+class CodexAdapter(BaseAdapter):
+    """OpenAI Codex CLI 适配器"""
+
+    def format_suggestion(self, recommendations: List[Dict]) -> str:
+        if not recommendations:
+            return ""
+
+        lines = ["# SRA recommended skills"]
+        for r in recommendations:
+            lines.append(f"# - {r['skill']}: {r.get('description', '')[:80]}")
+
+        return "\n".join(lines)
+
+    def to_openai_tool_format(self, recommendations: List[Dict]) -> List[Dict]:
+        """转换为 OpenAI Function Calling 格式"""
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": r["skill"],
+                    "description": r.get("description", "")[:200],
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string",
+                                "description": f"The task for {r['skill']}"
+                            }
+                        },
+                        "required": ["query"]
+                    }
+                }
+            }
+            for r in recommendations[:3]
+        ]
+
+
+# ── 通用 CLI 适配器 ─────────────────────────
+
+class GenericCLIAdapter(BaseAdapter):
+    """通用 CLI Agent 适配器 — 输出纯文本格式"""
+
+    def format_suggestion(self, recommendations: List[Dict]) -> str:
+        if not recommendations:
+            return ""
+
+        lines = ["=== SRA Skill Recommendation ==="]
+        for i, r in enumerate(recommendations[:3], 1):
+            lines.append(f"{i}. {r['skill']}")
+            lines.append(f"   Score: {r['score']} | Confidence: {r.get('confidence', 'medium')}")
+            if r.get("description"):
+                lines.append(f"   {r['description'][:100]}")
+        lines.append("=" * 35)
+
+        return "\n".join(lines)
+
+
+# ── 适配器工厂 ──────────────────────────────
+
+ADAPTER_REGISTRY = {
+    "hermes": HermesAdapter,
+    "claude": ClaudeCodeAdapter,
+    "codex": CodexAdapter,
+    "opencode": GenericCLIAdapter,
+    "generic": GenericCLIAdapter,
+}
+
+
+def get_adapter(agent_type: str = "hermes") -> BaseAdapter:
+    """获取对应 Agent 的适配器"""
+    adapter_class = ADAPTER_REGISTRY.get(agent_type.lower(), GenericCLIAdapter)
+    return adapter_class()
+
+
+def list_adapters() -> List[str]:
+    """列出所有支持的 Agent 类型"""
+    return list(ADAPTER_REGISTRY.keys())
+
+
+# ── 独立测试 ────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+
+    agent = sys.argv[1] if len(sys.argv) > 1 else "hermes"
+    query = sys.argv[2] if len(sys.argv) > 2 else "帮我画个架构图"
+
+    adapter = get_adapter(agent)
+    recs = adapter.recommend(query)
+
+    print(f"Agent: {agent}")
+    print(f"Query: {query}")
+    print()
+    print(adapter.format_suggestion(recs))

skill_advisor/advisor.py

@@ -0,0 +1,325 @@
+"""
+SRA - Skill Runtime Advisor
+让 AI Agent 知道自己有什么能力，以及什么时候该用什么能力。
+
+主入口：SkillAdvisor 类
+"""
+
+import os
+import time
+from typing import Dict, List
+
+from .indexer import SkillIndexer
+from .matcher import SkillMatcher
+from .memory import SceneMemory
+from .synonyms import SYNONYMS
+
+
+class SkillAdvisor:
+    """技能推荐引擎主类"""
+
+    # 推荐阈值
+    THRESHOLD_STRONG = 80  # 强推荐：自动加载
+    THRESHOLD_WEAK = 40    # 弱推荐：附加提示
+
+    def __init__(self, skills_dir: str = None, data_dir: str = None):
+        """
+        初始化 SRA 引擎
+
+        Args:
+            skills_dir: 技能目录路径。默认为 ~/.hermes/skills
+            data_dir: 数据持久化目录。默认为 ~/.sra/data
+        """
+        self.skills_dir = skills_dir or os.path.expanduser("~/.hermes/skills")
+        self.data_dir = data_dir or os.path.expanduser(
+            os.environ.get("SRA_DATA_DIR", "~/.sra/data")
+        )
+
+        # 确保数据目录存在
+        os.makedirs(self.data_dir, exist_ok=True)
+
+        # 初始化子模块
+        self.indexer = SkillIndexer(self.skills_dir, self.data_dir)
+        self.matcher = SkillMatcher(SYNONYMS)
+        self.memory = SceneMemory(self.data_dir)
+
+        # 懒加载索引
+        self._index_loaded = False
+
+    def _ensure_index(self):
+        """确保索引已加载"""
+        if not self._index_loaded:
+            self.indexer.load_or_build()
+            self._index_loaded = True
+
+    def refresh_index(self) -> int:
+        """强制刷新技能索引"""
+        count = self.indexer.build()
+        self._index_loaded = True
+        return count
+
+    def build_contract(self, query: str, scored: List[Dict]) -> Dict:
+        """为推荐结果构建技能契约
+
+        Args:
+            query: 用户原始输入
+            scored: 已评分排序的技能列表（带 .score 字段）
+
+        Returns:
+            {
+                "task_type": str,              # 推测的任务类型
+                "required_skills": [str],       # 强推荐（score >= 80）
+                "optional_skills": [str],       # 可选推荐（40 <= score < 80）
+                "confidence": str,              # high / medium / low
+                "summary": str,                 # 自然语言描述
+            }
+        """
+        required = [s["skill"] for s in scored if s.get("score", 0) >= self.THRESHOLD_STRONG]
+        optional = [s["skill"] for s in scored if self.THRESHOLD_WEAK <= s.get("score", 0) < self.THRESHOLD_STRONG]
+
+        # 推测任务类型：取最高分技能的 category
+        categories = {s.get("category", "") for s in scored if s.get("category")}
+        task_type = next(iter(categories)) if len(categories) == 1 else (", ".join(categories) if categories else "general")
+
+        # 置信度
+        max_score = max((s.get("score", 0) for s in scored), default=0)
+        if max_score >= 80:
+            confidence = "high"
+        elif max_score >= 60:
+            confidence = "medium"
+        else:
+            confidence = "low"
+
+        # 自然语言总结
+        parts = []
+        if required:
+            parts.append(f"必须加载: {', '.join(required)}")
+        if optional:
+            parts.append(f"建议参考: {', '.join(optional)}")
+        summary = f"任务类型「{task_type}」— " + ("; ".join(parts) if parts else "无特定技能推荐")
+
+        return {
+            "task_type": task_type,
+            "required_skills": required,
+            "optional_skills": optional,
+            "confidence": confidence,
+            "summary": summary,
+        }
+
+    def recommend(self, query: str, top_k: int = 3) -> Dict:
+        """
+        推荐匹配技能
+
+        Args:
+            query: 用户输入
+            top_k: 返回 top-k 结果
+
+        Returns:
+            {
+                "recommendations": [...],
+                "processing_ms": float,
+                "skills_scanned": int,
+                "query": str,
+                "contract": {            # 🆕 契约机制
+                    "task_type": str,
+                    "required_skills": [str],
+                    "optional_skills": [str],
+                    "confidence": str,
+                    "summary": str,
+                }
+            }
+        """
+        self._ensure_index()
+        start = time.time()
+
+        skills = self.indexer.get_skills()
+        stats = self.memory.load()
+
+        # 提取输入关键词
+        input_words = self.indexer.extract_keywords(query)
+        input_expanded = self.indexer.expand_with_synonyms(input_words)
+
+        if not input_expanded:
+            return {"recommendations": [], "processing_ms": 0, "skills_scanned": 0, "query": query}
+
+        # 对所有 skill 评分
+        scored = []
+        for skill in skills:
+            total, details, reasons = self.matcher.score(
+                input_expanded, skill, stats
+            )
+
+            if total >= self.THRESHOLD_WEAK:
+                scored.append({
+                    "skill": skill["name"],
+                    "description": skill.get("description", "")[:120],
+                    "category": skill.get("category", ""),
+                    "score": round(total, 1),
+                    "confidence": "high" if total >= self.THRESHOLD_STRONG else "medium",
+                    "reasons": reasons[:3],
+                    "details": details,
+                })
+
+        # 排序取 top-k
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        top = scored[:top_k]
+
+        # 更新推荐计数
+        self.memory.increment_recommendations()
+
+        # 🆕 构建契约
+        contract = self.build_contract(query, scored)
+
+        elapsed = round((time.time() - start) * 1000, 1)
+
+        return {
+            "recommendations": top,
+            "processing_ms": elapsed,
+            "skills_scanned": len(skills),
+            "query": query,
+            "contract": contract,       # 🆕
+        }
+
+    def recheck(self, conversation_summary: str, loaded_skills: List[str] = None,
+                 top_k: int = 5) -> Dict:
+        """
+        长任务上下文漂移重检
+
+        在长任务执行过程中定期调用，检测上下文是否漂移，
+        以及是否有新的技能应该被加载。
+
+        Args:
+            conversation_summary: 当前对话摘要
+            loaded_skills: 已经加载的技能名称列表
+            top_k: 推荐 top-k 技能
+
+        Returns:
+            {
+                "has_drift": bool,           # 是否检测到漂移
+                "missing_skills": [...],      # 推荐但未加载的技能
+                "drift_score": float,         # 漂移程度 (0-1)
+                "recommendations": [...],      # 完整推荐结果
+                "loaded_skills_count": int,
+                "processing_ms": float,
+            }
+        """
+        # 1. 运行推荐算法
+        result = self.recommend(conversation_summary, top_k=top_k)
+        recs = result.get("recommendations", [])
+        elapsed = result.get("processing_ms", 0)
+
+        # 2. 对比已加载技能
+        loaded = loaded_skills or []
+        loaded_lower = [s.lower() for s in loaded]
+        [r["skill"].lower() for r in recs]
+
+        missing = [r for r in recs if r["skill"].lower() not in loaded_lower]
+
+        # 3. 计算漂移分数
+        if recs:
+            drift_score = round(len(missing) / len(recs), 2)
+        else:
+            drift_score = 0.0
+        has_drift = len(missing) > 0 and drift_score >= 0.2
+
+        # 4. 记录推荐
+        if has_drift:
+            self.memory.increment_recommendations()
+
+        return {
+            "has_drift": has_drift,
+            "drift_score": drift_score,
+            "missing_skills": missing,
+            "recommendations": recs,
+            "loaded_skills_count": len(loaded),
+            "processing_ms": elapsed,
+            "query": conversation_summary[:100],
+        }
+
+    def record_usage(self, skill_name: str, user_input: str, accepted: bool = True):
+        """记录技能使用场景"""
+        self.memory.record_usage(skill_name, user_input, accepted)
+
+    def record_view(self, skill_name: str):
+        """记录技能被查看"""
+        self.memory.record_view(skill_name)
+
+    def record_use(self, skill_name: str):
+        """记录技能被使用"""
+        self.memory.record_use(skill_name)
+
+    def record_skip(self, skill_name: str, reason: str = ""):
+        """记录技能被跳过"""
+        self.memory.record_skip(skill_name, reason)
+
+    def get_compliance_stats(self) -> Dict:
+        """获取遵循率统计"""
+        return self.memory.get_compliance_stats()
+
+    def show_stats(self) -> Dict:
+        """获取统计信息"""
+        self._ensure_index()
+        stats = self.memory.load()
+        skills = self.indexer.get_skills()
+
+        return {
+            "total_skills": len(skills),
+            "total_recommendations": stats.get("total_recommendations", 0),
+            "scene_patterns": len(stats.get("scene_patterns", [])),
+            "skills_with_stats": len(stats.get("skills", {})),
+            "memory": stats,
+        }
+
+    def analyze_coverage(self) -> Dict:
+        """
+        分析 SRA 对技能目录的覆盖率
+        返回：每个 skill 是否能被 SRA 的 trigger 机制识别
+        """
+        self._ensure_index()
+        skills = self.indexer.get_skills()
+        stats = self.memory.load()
+
+        results = []
+        covered = 0
+        for skill in skills:
+            # 用 skill 自己的 triggers 作为测试查询
+            triggers = skill.get("triggers", [])
+            name = skill.get("name", "")
+
+            # 构造测试查询
+            test_queries = []
+            if triggers:
+                test_queries.extend(triggers[:3])
+            # 用 name 作为后备查询
+            test_queries.append(name.replace("-", " "))
+
+            # 测试所有查询
+            max_score = 0
+            for q in test_queries:
+                if not q:
+                    continue
+                input_words = self.indexer.extract_keywords(q)
+                input_expanded = self.indexer.expand_with_synonyms(input_words)
+                if input_expanded:
+                    total, _, _ = self.matcher.score(input_expanded, skill, stats)
+                    max_score = max(max_score, total)
+
+            is_covered = max_score >= self.THRESHOLD_WEAK
+            if is_covered:
+                covered += 1
+
+            results.append({
+                "name": skill["name"],
+                "category": skill.get("category", ""),
+                "has_triggers": len(triggers) > 0,
+                "max_score": round(max_score, 1),
+                "covered": is_covered,
+            })
+
+        return {
+            "total": len(skills),
+            "covered": covered,
+            "coverage_rate": round(covered / len(skills) * 100, 1) if skills else 0,
+            "not_covered": [r for r in results if not r["covered"]],
+            "details": results,
+        }