sra-agent 1.2.0__tar.gz

sra_agent-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SRA Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sra_agent-1.2.0/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: sra-agent
+Version: 1.2.0
+Summary: Skill Runtime Advisor — 让 AI Agent 知道自己有什么能力，以及什么时候该用什么能力。带守护进程、多 Agent 适配器、完整 CLI、消息前置推理中间件。
+Author: Emma (SRA Team), Kei
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JackSmith111977/Hermes-Skill-View
+Project-URL: Repository, https://github.com/JackSmith111977/Hermes-Skill-View.git
+Project-URL: Documentation, https://github.com/JackSmith111977/Hermes-Skill-View#readme
+Keywords: ai-agent,skill-management,runtime-advisor,hermes,llm,daemon
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=5.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Dynamic: license-file
+
+# SRA — Skill Runtime Advisor 🎯
+
+[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)
+[![CI](https://github.com/JackSmith111977/Hermes-Skill-View/actions/workflows/ci.yml/badge.svg)](https://github.com/JackSmith111977/Hermes-Skill-View/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
+[![CLI](https://img.shields.io/badge/CLI-sra-orange)](https://github.com/JackSmith111977/Hermes-Skill-View)
+[![PyPI](https://img.shields.io/badge/PyPI-sra--agent-0073e0)](https://pypi.org/project/sra-agent/)
+
+> **为 Hermes Agent 解决技能发现痛点的运行时消息前置推理中间件。**  
+> 每次用户消息到达 Agent 之前，先经过 SRA Proxy 语义分析，自动注入最匹配技能（SKILL.md）的 RAG 上下文——让 Agent 永远知道当前任务该用什么能力。
+
+🌐 [English README](README_en.md) · 📖 [Runtime Design](./RUNTIME.md) · ⚡ [Quick Install](#安装) · 🩺 [Integration Guide](./docs/INTEGRATION.md)
+
+---
+
+## 📐 架构总览
+
+### 消息流时序图
+
+```mermaid
+sequenceDiagram
+    participant U as 👤 User
+    participant SRA as 🎯 SRA Proxy :8536
+    participant IDX as 📚 Skill Index
+    participant H as 🤖 Hermes Agent
+    participant SK as 📁 ~/.hermes/skills/
+
+    U->>+H: "画个架构图"
+    H->>+SRA: POST /recommend {"message":"..."}
+    SRA->>+IDX: 语义匹配 (TF-IDF + 同义词)
+    IDX-->>-SRA: architecture-diagram (score: 92)
+    SRA->>+SK: 读取 SKILL.md 元数据
+    SK-->>-SRA: triggers, description, usage
+    SRA-->>-H: rag_context + top_skill + should_auto_load
+    Note over H: 注入 RAG 上下文到系统提示
+    H-->>-U: "好的，为你生成架构图..." + 正确工具调用
+```
+### 组件架构图
+
+```mermaid
+flowchart LR
+    subgraph Input["📥 输入层"]
+        U[User Message<br/>自然语言查询]
+    end
+
+    subgraph SRA_MW["🎯 SRA 中间件层"]
+        direction TB
+        P[SRA Proxy :8536<br/>Unix Socket + HTTP]
+        M[匹配引擎<br/>TF-IDF + 同义词 + 共现矩阵]
+        I[(Skill Index Store<br/>275+ skills indexed)]
+    end
+
+    subgraph Agent["🤖 Agent 消费层"]
+        direction TB
+        H[Hermes Agent<br/>注入 rag_context]
+        T[工具执行<br/>terminal / file / web]
+    end
+
+    subgraph Output["📤 输出层"]
+        R[Agent Response<br/>正确的技能 + 工具调用]
+    end
+
+    SK[~/.hermes/skills/<br/>SKILL.md files]
+
+    U -->|POST /recommend| P
+    P -->|lookup| M
+    M -->|query| I
+    I -->|scan| SK
+    P -->|rag_context + top_skill| H
+    H -->|enhanced context| T
+    T --> R
+
+    classDef input fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
+    classDef sra fill:#f0fdf4,stroke:#16a34a,color:#14532d
+    classDef agent fill:#fefce8,stroke:#ca8a04,color:#713f12
+    classDef output fill:#fce7f3,stroke:#db2777,color:#831843
+    classDef storage fill:#f3e8ff,stroke:#9333ea,color:#581c87
+
+    class U input
+    class P,M sra
+    class I,SK storage
+    class H,T agent
+    class R output
+```
+
+**一句话解释**：用户说"画个架构图" → SRA 在 < 5ms 内找到 `architecture-diagram` 技能 → 把技能的触发词和使用方法注入到 Agent 的上下文 → Agent 立刻知道该用哪个工具。
+
+---
+
+## 🎯 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| **消息前置推理** | 每次用户消息到达 Agent，自动查询最匹配的技能并注入 RAG 上下文 |
+| **语义匹配引擎** | 同义词扩展 + TF-IDF + 共现矩阵混合匹配，不是简单的关键词搜索 |
+| **守护进程** | 7x24 后台运行，Unix Socket + HTTP 双协议，自动定时刷新技能索引 |
+| **覆盖率分析** | 统计哪些技能能被识别、哪些是盲区，驱动技能库质量改进 |
+| **Agent 适配器** | 为 Hermes / Claude / Codex 等 Agent 提供原生格式的输出 |
+| **零侵入集成** | SRA 不修改 Agent 代码，只在消息路径上增加一个 HTTP 调用 |
+
+---
+
+## 🤔 为什么要用 SRA？
+
+Hermes Agent 的技能库（`~/.hermes/skills/`）越来越大（60+），但 Agent 面临这些问题：
+
+1. **静态列表失效** — `<available_skills>` 列表太长，Agent 经常忽略最合适的技能
+2. **新技能不可见** — 添加一个新的 SKILL.md 后，Agent 不会自动知道它的存在
+3. **没有反馈闭环** — Agent 用了哪个技能、效果如何，完全不可追踪
+4. **发现成本高** — Agent 需要遍历所有技能的 triggers 和 description 才能做出选择
+
+**SRA 的解决方案**：在消息路径上插入一个**语义感知层**，用 TF-IDF + 同义词 + 共现矩阵做实时匹配，把最相关的技能上下文在消息处理前就注入给 Agent。
+
+---
+
+## ⚡ 安装
+
+### 方式一：pip 安装（推荐）
+
+```bash
+pip install sra-agent
+sra version    # 验证安装
+```
+
+### 方式二：一键脚本（自动配置）
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/JackSmith111977/Hermes-Skill-View/main/scripts/install.sh | bash
+```
+
+### 方式三：源码安装
+
+```bash
+git clone https://github.com/JackSmith111977/Hermes-Skill-View.git
+cd Hermes-Skill-View
+pip install -e .
+```
+
+### 方式四：Proxy 模式（消息前置推理）
+
+```bash
+bash scripts/install.sh --proxy
+```
+
+---
+
+## 🚀 快速开始
+
+### 1. 启动守护进程
+
+```bash
+sra start
+# 预期输出: SRA Daemon 运行中...
+```
+
+### 2. 查询技能推荐
+
+```bash
+sra recommend "画个架构图"
+# 预期输出: -> 推荐技能: architecture-diagram, 得分: 92, 置信度: high
+```
+
+### 3. 检查状态
+
+```bash
+sra status
+# 预期输出: 运行状态、技能数量、版本
+```
+
+### 4. Proxy 模式（消息前置推理）
+
+```bash
+curl -s -X POST http://127.0.0.1:8536/recommend \
+  -H "Content-Type: application/json" \
+  -d '{"message": "画个架构图"}'
+```
+
+返回示例：
+```json
+{
+  "top_skill": "architecture-diagram",
+  "should_auto_load": true,
+  "rag_context": "[SRA] 推荐加载 architecture-diagram 技能：用于生成暗色主题的系统架构图...",
+  "recommendations": [
+    {"name": "architecture-diagram", "score": 92, "confidence": "high"},
+    {"name": "excalidraw", "score": 67, "confidence": "medium"}
+  ],
+  "timing_ms": 4.2
+}
+```
+
+### 5. 集成到 Hermes Agent
+
+在 SOUL.md 或 AGENTS.md 中添加消息前置推理规则：
+
+```yaml
+# 每条用户消息到达 Agent 前，先调 SRA
+pre_process:
+  - curl -s -X POST http://127.0.0.1:8536/recommend
+    -H "Content-Type: application/json"
+    -d '{"message": "<用户消息原文>"}'
+  - 将返回的 rag_context 注入到 Agent 的系统提示中
+```
+
+---
+
+## 🔧 命令大全
+
+| 命令 | 说明 |
+|------|------|
+| `sra start` | 启动守护进程 |
+| `sra stop` | 停止守护进程 |
+| `sra status` | 查看运行状态 |
+| `sra restart` | 重启守护进程 |
+| `sra attach` | 前台运行（调试用） |
+| `sra recommend <输入>` | 查询技能推荐 |
+| `sra query <输入>` | 同 recommend |
+| `sra coverage` | 分析技能识别覆盖率 |
+| `sra stats` | 查看运行统计 |
+| `sra refresh` | 刷新技能索引 |
+| `sra record <技能> <输入>` | 记录技能使用 |
+| `sra config [show\|set\|reset]` | 配置管理 |
+| `sra adapters` | 列出支持的 Agent 类型 |
+| `sra install <agent>` | 安装到指定 Agent |
+| `sra version` | 显示版本 |
+| `sra help` | 显示帮助 |
+
+---
+
+## 🔌 Proxy API
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/health` | GET | 健康检查 |
+| `/status` | GET | 详细运行状态 |
+| `/stats` | GET | 统计信息 |
+| `/recommend?q=<查询>` | GET | 技能推荐（GET 方式） |
+| `/recommend` | POST | 技能推荐（POST 方式，JSON body） |
+| `/record` | POST | 记录技能使用 |
+| `/refresh` | POST | 刷新技能索引 |
+
+---
+
+## 💡 设计哲学
+
+SRA 以三个原则指导其作为运行时的设计：
+
+1. **消息优先于工具** — SRA 不是 Agent 主动加载的"技能"，而是 Agent 收到每条消息时**被动触发**的中间件。它不改变 Agent 的行为，只增强 Agent 的上下文。
+2. **AI 可观测性优先** — 每个组件必须有状态反馈（ok / warn / error），AI 永远知道"当前状态是什么"和"下一步该怎么做"
+3. **渐进式披露** — README（入口）→ RUNTIME.md（运行时设计）→ docs/（详细文档），按需深入
+
+> 📖 完整的运行时设计文档请看 [RUNTIME.md](./RUNTIME.md)
+
+---
+
+## 📊 环境检查
+
+安装后运行以下命令确认全部就绪：
+
+```bash
+python3 scripts/check-sra.py
+```
+
+预期输出：
+```
+python: ok (3.11.5)
+sra cli: ok (sra v1.1.0)
+sra daemon: ok (port 8536, 275 skills indexed)
+skills dir: ok (~/.hermes/skills, 62 skills)
+sra config: ok (~/.sra/config.json)
+```
+
+---
+
+## 🗺️ 路线图
+
+| 优先级 | 改进项 | 目标 |
+|--------|--------|------|
+| 🔴 P0 | 修复 watch_skills_dir 文件监听 | 新技能秒级感知 |
+| 🔴 P0 | 改进中文匹配精度 | 覆盖率提升至 95%+ |
+| 🟡 P1 | 自动 Agent 集成脚本 | 一条命令完成所有配置 |
+| 🟡 P1 | 推荐反馈闭环自动化 | Agent 使用技能后自动记录 |
+| 🟢 P2 | 推荐质量仪表盘 | 可视化展示推荐命中率 |
+
+### 远期愿景
+
+- **主动学习**：根据场景记忆自动调整推荐权重，高频场景更快匹配
+- **多级推荐**：不仅是 skill 级别，还能推荐 skill 内的具体章节
+- **Agent 反馈回路**：Agent 用了推荐技能后自动反馈结果给 SRA
+
+---
+
+## ❓ FAQ
+
+**Q: sra 命令找不到？**  
+检查 PATH 是否包含 `~/.local/bin`，或运行 `pip install sra-agent` 重试。
+
+**Q: 守护进程启动失败？**  
+先运行 `python3 scripts/check-sra.py` 诊断环境，针对未通过项修复。
+
+**Q: Proxy 模式不工作？**  
+确认守护进程运行中，端口 8536 可用。运行 `sra status` 检查。
+
+**Q: 支持哪些 Agent？**  
+目前支持 Hermes Agent（原生适配），也兼容任何能通过 HTTP 调用的 Agent（Claude Code、Codex CLI 等）。
+
+---
+
+## 📝 许可证
+
+MIT — 详见 [LICENSE](./LICENSE)

sra_agent-1.2.0/README.md

@@ -0,0 +1,311 @@
+# SRA — Skill Runtime Advisor 🎯
+
+[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)
+[![CI](https://github.com/JackSmith111977/Hermes-Skill-View/actions/workflows/ci.yml/badge.svg)](https://github.com/JackSmith111977/Hermes-Skill-View/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
+[![CLI](https://img.shields.io/badge/CLI-sra-orange)](https://github.com/JackSmith111977/Hermes-Skill-View)
+[![PyPI](https://img.shields.io/badge/PyPI-sra--agent-0073e0)](https://pypi.org/project/sra-agent/)
+
+> **为 Hermes Agent 解决技能发现痛点的运行时消息前置推理中间件。**  
+> 每次用户消息到达 Agent 之前，先经过 SRA Proxy 语义分析，自动注入最匹配技能（SKILL.md）的 RAG 上下文——让 Agent 永远知道当前任务该用什么能力。
+
+🌐 [English README](README_en.md) · 📖 [Runtime Design](./RUNTIME.md) · ⚡ [Quick Install](#安装) · 🩺 [Integration Guide](./docs/INTEGRATION.md)
+
+---
+
+## 📐 架构总览
+
+### 消息流时序图
+
+```mermaid
+sequenceDiagram
+    participant U as 👤 User
+    participant SRA as 🎯 SRA Proxy :8536
+    participant IDX as 📚 Skill Index
+    participant H as 🤖 Hermes Agent
+    participant SK as 📁 ~/.hermes/skills/
+
+    U->>+H: "画个架构图"
+    H->>+SRA: POST /recommend {"message":"..."}
+    SRA->>+IDX: 语义匹配 (TF-IDF + 同义词)
+    IDX-->>-SRA: architecture-diagram (score: 92)
+    SRA->>+SK: 读取 SKILL.md 元数据
+    SK-->>-SRA: triggers, description, usage
+    SRA-->>-H: rag_context + top_skill + should_auto_load
+    Note over H: 注入 RAG 上下文到系统提示
+    H-->>-U: "好的，为你生成架构图..." + 正确工具调用
+```
+### 组件架构图
+
+```mermaid
+flowchart LR
+    subgraph Input["📥 输入层"]
+        U[User Message<br/>自然语言查询]
+    end
+
+    subgraph SRA_MW["🎯 SRA 中间件层"]
+        direction TB
+        P[SRA Proxy :8536<br/>Unix Socket + HTTP]
+        M[匹配引擎<br/>TF-IDF + 同义词 + 共现矩阵]
+        I[(Skill Index Store<br/>275+ skills indexed)]
+    end
+
+    subgraph Agent["🤖 Agent 消费层"]
+        direction TB
+        H[Hermes Agent<br/>注入 rag_context]
+        T[工具执行<br/>terminal / file / web]
+    end
+
+    subgraph Output["📤 输出层"]
+        R[Agent Response<br/>正确的技能 + 工具调用]
+    end
+
+    SK[~/.hermes/skills/<br/>SKILL.md files]
+
+    U -->|POST /recommend| P
+    P -->|lookup| M
+    M -->|query| I
+    I -->|scan| SK
+    P -->|rag_context + top_skill| H
+    H -->|enhanced context| T
+    T --> R
+
+    classDef input fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
+    classDef sra fill:#f0fdf4,stroke:#16a34a,color:#14532d
+    classDef agent fill:#fefce8,stroke:#ca8a04,color:#713f12
+    classDef output fill:#fce7f3,stroke:#db2777,color:#831843
+    classDef storage fill:#f3e8ff,stroke:#9333ea,color:#581c87
+
+    class U input
+    class P,M sra
+    class I,SK storage
+    class H,T agent
+    class R output
+```
+
+**一句话解释**：用户说"画个架构图" → SRA 在 < 5ms 内找到 `architecture-diagram` 技能 → 把技能的触发词和使用方法注入到 Agent 的上下文 → Agent 立刻知道该用哪个工具。
+
+---
+
+## 🎯 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| **消息前置推理** | 每次用户消息到达 Agent，自动查询最匹配的技能并注入 RAG 上下文 |
+| **语义匹配引擎** | 同义词扩展 + TF-IDF + 共现矩阵混合匹配，不是简单的关键词搜索 |
+| **守护进程** | 7x24 后台运行，Unix Socket + HTTP 双协议，自动定时刷新技能索引 |
+| **覆盖率分析** | 统计哪些技能能被识别、哪些是盲区，驱动技能库质量改进 |
+| **Agent 适配器** | 为 Hermes / Claude / Codex 等 Agent 提供原生格式的输出 |
+| **零侵入集成** | SRA 不修改 Agent 代码，只在消息路径上增加一个 HTTP 调用 |
+
+---
+
+## 🤔 为什么要用 SRA？
+
+Hermes Agent 的技能库（`~/.hermes/skills/`）越来越大（60+），但 Agent 面临这些问题：
+
+1. **静态列表失效** — `<available_skills>` 列表太长，Agent 经常忽略最合适的技能
+2. **新技能不可见** — 添加一个新的 SKILL.md 后，Agent 不会自动知道它的存在
+3. **没有反馈闭环** — Agent 用了哪个技能、效果如何，完全不可追踪
+4. **发现成本高** — Agent 需要遍历所有技能的 triggers 和 description 才能做出选择
+
+**SRA 的解决方案**：在消息路径上插入一个**语义感知层**，用 TF-IDF + 同义词 + 共现矩阵做实时匹配，把最相关的技能上下文在消息处理前就注入给 Agent。
+
+---
+
+## ⚡ 安装
+
+### 方式一：pip 安装（推荐）
+
+```bash
+pip install sra-agent
+sra version    # 验证安装
+```
+
+### 方式二：一键脚本（自动配置）
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/JackSmith111977/Hermes-Skill-View/main/scripts/install.sh | bash
+```
+
+### 方式三：源码安装
+
+```bash
+git clone https://github.com/JackSmith111977/Hermes-Skill-View.git
+cd Hermes-Skill-View
+pip install -e .
+```
+
+### 方式四：Proxy 模式（消息前置推理）
+
+```bash
+bash scripts/install.sh --proxy
+```
+
+---
+
+## 🚀 快速开始
+
+### 1. 启动守护进程
+
+```bash
+sra start
+# 预期输出: SRA Daemon 运行中...
+```
+
+### 2. 查询技能推荐
+
+```bash
+sra recommend "画个架构图"
+# 预期输出: -> 推荐技能: architecture-diagram, 得分: 92, 置信度: high
+```
+
+### 3. 检查状态
+
+```bash
+sra status
+# 预期输出: 运行状态、技能数量、版本
+```
+
+### 4. Proxy 模式（消息前置推理）
+
+```bash
+curl -s -X POST http://127.0.0.1:8536/recommend \
+  -H "Content-Type: application/json" \
+  -d '{"message": "画个架构图"}'
+```
+
+返回示例：
+```json
+{
+  "top_skill": "architecture-diagram",
+  "should_auto_load": true,
+  "rag_context": "[SRA] 推荐加载 architecture-diagram 技能：用于生成暗色主题的系统架构图...",
+  "recommendations": [
+    {"name": "architecture-diagram", "score": 92, "confidence": "high"},
+    {"name": "excalidraw", "score": 67, "confidence": "medium"}
+  ],
+  "timing_ms": 4.2
+}
+```
+
+### 5. 集成到 Hermes Agent
+
+在 SOUL.md 或 AGENTS.md 中添加消息前置推理规则：
+
+```yaml
+# 每条用户消息到达 Agent 前，先调 SRA
+pre_process:
+  - curl -s -X POST http://127.0.0.1:8536/recommend
+    -H "Content-Type: application/json"
+    -d '{"message": "<用户消息原文>"}'
+  - 将返回的 rag_context 注入到 Agent 的系统提示中
+```
+
+---
+
+## 🔧 命令大全
+
+| 命令 | 说明 |
+|------|------|
+| `sra start` | 启动守护进程 |
+| `sra stop` | 停止守护进程 |
+| `sra status` | 查看运行状态 |
+| `sra restart` | 重启守护进程 |
+| `sra attach` | 前台运行（调试用） |
+| `sra recommend <输入>` | 查询技能推荐 |
+| `sra query <输入>` | 同 recommend |
+| `sra coverage` | 分析技能识别覆盖率 |
+| `sra stats` | 查看运行统计 |
+| `sra refresh` | 刷新技能索引 |
+| `sra record <技能> <输入>` | 记录技能使用 |
+| `sra config [show\|set\|reset]` | 配置管理 |
+| `sra adapters` | 列出支持的 Agent 类型 |
+| `sra install <agent>` | 安装到指定 Agent |
+| `sra version` | 显示版本 |
+| `sra help` | 显示帮助 |
+
+---
+
+## 🔌 Proxy API
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/health` | GET | 健康检查 |
+| `/status` | GET | 详细运行状态 |
+| `/stats` | GET | 统计信息 |
+| `/recommend?q=<查询>` | GET | 技能推荐（GET 方式） |
+| `/recommend` | POST | 技能推荐（POST 方式，JSON body） |
+| `/record` | POST | 记录技能使用 |
+| `/refresh` | POST | 刷新技能索引 |
+
+---
+
+## 💡 设计哲学
+
+SRA 以三个原则指导其作为运行时的设计：
+
+1. **消息优先于工具** — SRA 不是 Agent 主动加载的"技能"，而是 Agent 收到每条消息时**被动触发**的中间件。它不改变 Agent 的行为，只增强 Agent 的上下文。
+2. **AI 可观测性优先** — 每个组件必须有状态反馈（ok / warn / error），AI 永远知道"当前状态是什么"和"下一步该怎么做"
+3. **渐进式披露** — README（入口）→ RUNTIME.md（运行时设计）→ docs/（详细文档），按需深入
+
+> 📖 完整的运行时设计文档请看 [RUNTIME.md](./RUNTIME.md)
+
+---
+
+## 📊 环境检查
+
+安装后运行以下命令确认全部就绪：
+
+```bash
+python3 scripts/check-sra.py
+```
+
+预期输出：
+```
+python: ok (3.11.5)
+sra cli: ok (sra v1.1.0)
+sra daemon: ok (port 8536, 275 skills indexed)
+skills dir: ok (~/.hermes/skills, 62 skills)
+sra config: ok (~/.sra/config.json)
+```
+
+---
+
+## 🗺️ 路线图
+
+| 优先级 | 改进项 | 目标 |
+|--------|--------|------|
+| 🔴 P0 | 修复 watch_skills_dir 文件监听 | 新技能秒级感知 |
+| 🔴 P0 | 改进中文匹配精度 | 覆盖率提升至 95%+ |
+| 🟡 P1 | 自动 Agent 集成脚本 | 一条命令完成所有配置 |
+| 🟡 P1 | 推荐反馈闭环自动化 | Agent 使用技能后自动记录 |
+| 🟢 P2 | 推荐质量仪表盘 | 可视化展示推荐命中率 |
+
+### 远期愿景
+
+- **主动学习**：根据场景记忆自动调整推荐权重，高频场景更快匹配
+- **多级推荐**：不仅是 skill 级别，还能推荐 skill 内的具体章节
+- **Agent 反馈回路**：Agent 用了推荐技能后自动反馈结果给 SRA
+
+---
+
+## ❓ FAQ
+
+**Q: sra 命令找不到？**  
+检查 PATH 是否包含 `~/.local/bin`，或运行 `pip install sra-agent` 重试。
+
+**Q: 守护进程启动失败？**  
+先运行 `python3 scripts/check-sra.py` 诊断环境，针对未通过项修复。
+
+**Q: Proxy 模式不工作？**  
+确认守护进程运行中，端口 8536 可用。运行 `sra status` 检查。
+
+**Q: 支持哪些 Agent？**  
+目前支持 Hermes Agent（原生适配），也兼容任何能通过 HTTP 调用的 Agent（Claude Code、Codex CLI 等）。
+
+---
+
+## 📝 许可证
+
+MIT — 详见 [LICENSE](./LICENSE)