SRA — Skill Runtime Advisor

📋 项目概览

名称

SRA Agent

sra-agent

版本

1.4.0-dev

MIT License

Python

≥ 3.8

依赖: pyyaml

SRA — Skill Runtime Advisor 是一个运行在 AI Agent 旁的守护进程，在 Agent 收到用户消息时自动分析语义、推荐最匹配的 Hermes Skill，并通过 pre_tool_call 钩子系统在校验工具调用前检查技能遵循度。

⚠️ 版本由 setuptools-scm 从 git tag 自动推导（__init__.py 含多级 fallback，静态 regex 不可靠）。当前 dev 版，正式版见 git tag。

属性	值
作者	Emma (SRA Team), Kei
仓库	`github.com/JackSmith111977/Hermes-Skill-View`
入口 CLI	`sra` / `srad`
守护端口	HTTP `:8536` + Unix Socket `~/.sra/srad.sock`
技能来源	`~/.hermes/skills/**/SKILL.md` (YAML frontmatter)
数据持久化	`~/.sra/data/`

🏗️ 三层架构

Layer 3 — 接口层 Interface

CLI (sra)HTTP API (:8536)Unix Socket (~/.sra/srad.sock)

⬇ 委托 ⬇

Layer 2 — 业务逻辑层 Service

SRaDDaemon (daemon.py)SkillAdvisor (advisor.py)SkillMatcher (matcher.py)SkillIndexer (indexer.py)ForceLevelManager (force.py)SceneMemory (memory.py)Synonyms (synonyms.py)

⬇ 读写 ⬇

Layer 1 — 数据层 Data

~/.hermes/skills/~/.sra/data/~/.sra/config.json

核心模块职责

模块	文件	职责	关键方法
SkillAdvisor	`advisor.py`	推荐引擎主入口，Facade 封装	`recommend()`, `recheck()`, `record_view/use/skip()`, `analyze_coverage()`, `build_contract()`
SRaDDaemon	`runtime/daemon.py`	守护进程，HTTP + Socket 双协议	`start()`, `stop()`, `_handle_request()`, `get_stats()`
SkillMatcher	`matcher.py`	四维匹配引擎（词法/语义/场景/类别）	`score()`
SkillIndexer	`indexer.py`	技能扫描、索引构建、关键词提取	`build()`, `load_or_build()`, `get_skills()`, `extract_keywords()`
SceneMemory	`memory.py`	场景记忆 + 技能轨迹追踪 + 遵循率统计	`record_view/use/skip()`, `get_compliance_stats()`
ForceLevelManager	`runtime/force.py`	力度等级引擎 🆕 v1.3.0	`get_level()`, `set_level()`, `is_injection_point_active()`
Validate	`runtime/endpoints/validate.py`	工具调用前技能校验	`handle_validate()`
SkillMap	`skill_map.py`	文件扩展名→技能映射注册表	`get_required_skills()`
CLI	`cli.py`	命令行接口 + 降级策略	`cmd_*() + _socket_request()`
Lock	`runtime/lock.py`	OS 级文件锁（fcntl.flock 单例保障）	`acquire_lock()`

🔌 全部 API 端点

HTTP API (port 8536)

方法	路径	说明	Sprint
GET	`/health`	健康检查 + 基本统计	v1.x
GET	`/status`	引擎状态 + 配置 + 力度等级	v1.x
GET	`/stats`	运行统计详情	v1.x
GET	`/stats/compliance`	技能遵循率统计	Sprint 2 🆕
GET	`/recommend?q=...`	技能推荐（GET 方式）	v1.x
POST	`/recommend`	技能推荐（POST + rag_context + contract）	v1.x
POST	`/record`	记录使用/查看/跳过	Sprint 2 🆕
POST	`/refresh`	刷新技能索引	v1.x
POST	`/validate`	工具调用前技能校验	Sprint 1 🆕
POST	`/force`	运行时力度管理（查看/切换等级）	v1.3.0 🆕
POST	`/recheck`	长任务上下文漂移重检	Sprint 2 🆕

Unix Socket API (~/.sra/srad.sock)

Action	Params	说明	Sprint
`recommend`	`{query, top_k?}`	技能推荐	v1.x
`record`	`{skill, action?, input?}`	记录使用/查看/跳过	Sprint 2 🆕
`refresh`	`{}`	刷新索引	v1.x
`stats`	`{}`	获取统计	v1.x
`stats/compliance`	`{}`	遵循率统计	Sprint 2 🆕
`coverage`	`{}`	覆盖率分析	v1.x
`validate`	`{tool, args, loaded_skills?}`	工具调用校验	Sprint 1 🆕
`force`	`{level?}`	查看/设置力度等级	v1.3.0 🆕
`recheck`	`{conversation_summary, loaded_skills?}`	漂移重检	Sprint 2 🆕
`ping`	`{}`	心跳检测	v1.x
`stop`	`{}`	远程停止守护进程	v1.x

💻 CLI 命令全集

守护进程管理

命令	说明
`sra start`	启动守护进程（后台）
`sra stop`	停止守护进程
`sra restart`	重启守护进程
`sra status`	查看运行状态
`sra attach`	前台运行（调试用）

查询命令

命令	说明
`sra recommend`	技能推荐
`sra query`	同 recommend
`sra stats`	查看统计
`sra coverage`	覆盖率分析
`sra compliance`	技能遵循率统计
`sra refresh`	刷新索引

管理命令

命令	说明
`sra record`	记录使用
`sra force [set \|list]`	运行时力度管理
`sra config [show\|set\|reset]`	配置管理
`sra install`	安装到 Agent
`sra upgrade [-V ]`	升级 SRA
`sra uninstall [--all]`	卸载 SRA
`sra dep-check`	检查 Gateway 依赖链健康度
`sra version`	版本信息
`sra adapters`	列出 Agent 适配器
`sra help`	帮助信息

📊 EPIC & Story 状态

EPIC-003: v2.0 Enforcement Layer (19/19)

ID	Story	优先级	Sprint
`SRA-003-01`	✅ Tool 层 SRA 校验	P0	Sprint 1
`SRA-003-02`	✅ 文件类型技能映射	P0	Sprint 1
`SRA-003-10`	✅ systemd 自启动部署	P2	Sprint 1
`SRA-003-11`	✅ 安装脚本自动配置	P2	Sprint 1
`SRA-003-12`	✅ Daemon 单例守护	P0	Sprint 1
`SRA-003-13`	✅ HTTP 架构 + 异常处理	P0	Sprint 1
`SRA-003-03`	✅ 技能使用轨迹记录	P1	Sprint 2
`SRA-003-04`	✅ 长任务上下文漂移保护	P1	Sprint 2
`SRA-003-14`	✅ 测试覆盖增强	P1	Sprint 2
`SRA-003-05`	✅ SRA 契约机制	P1	v1.3.0
`SRA-003-06`	✅ 运行时力度体系	P1	v1.3.0
`SRA-003-17`	✅ Drop-in 生命周期管理	P1	Sprint 2
`SRA-003-18`	✅ 质量修复 Sprint 1	P0	Sprint 2
`SRA-003-19`	✅ 质量修复 Sprint 2	P1	Sprint 2
`SRA-003-20`	✅ 质量修复 Sprint 3	P1	Sprint 2
`SRA-003-15`	✅ 质量增强（Schema/日志/魔法数字）	P1	Sprint 3
`SRA-003-16`	✅ 架构优化（并发安全/路由统一）	P1	Sprint 3
`SRA-003-21`	✅ 分支同步与 v1.3.0 发布	P0	Sprint 3
`SRA-003-22`	✅ os.fork()→subprocess.Popen (A-8)	P0	Sprint 3

🧪 测试覆盖

314

通过测试

314

总测试

32s

运行时间

测试文件: test_matcher.py, test_indexer.py, test_coverage.py, test_benchmark.py, test_daemon.py, test_cli.py, test_daemon_http.py, test_dropin.py, test_adapters.py, test_singleton.py, test_skill_map.py, test_contract.py, test_force.py, test_validate.py, test_memory.py, test_config.py, test_concurrency.py

🏃 Sprint 历史

Sprint	版本	日期	完成的 Story	测试增长
Sprint 1	v2.0-alpha	2026-05-09	7	38→103
Sprint 2	v1.3.0	2026-05-11	11	174→290
Sprint 3	v2.0.0	2026-05-12	19	290→312
Hotfix (v2.0.1-v2.0.2)	v2.0.2	2026-05-12	0	312→314
Sprint 4 — 文档对齐+工作流改进	v2.0.4	2026-05-12	4	314→314

🔮 SRA — Skill Runtime Advisor v2.0.4

由 generate-project-report.py 于 2026-05-12 10:06 生成

🔮 SRA — Skill Runtime Advisor