sra-agent 0.0.0.dev0__tar.gz

sra_agent-0.0.0.dev0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug Report
+about: 报告一个问题来帮助 SRA 变得更好
+title: "[Bug]: "
+labels: bug
+assignees: ''
+---
+
+## 问题描述
+清晰简洁地描述这个 Bug。
+
+## 复现步骤
+1. 运行命令 `...`
+2. 看到错误
+
+## 期望行为
+你期望发生的事情。
+
+## 环境信息
+- OS: [e.g. Ubuntu 22.04]
+- Python 版本: [e.g. 3.11]
+- SRA 版本: [e.g. v1.1.0]
+
+## 日志/截图

sra_agent-0.0.0.dev0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: 为 SRA 提出一个新想法
+title: "[Feature]: "
+labels: enhancement
+assignees: ''
+---
+
+## 你的功能请求和某个问题相关吗？
+清晰描述问题。例如：'当 [...] 时，我总是感到很麻烦'
+
+## 描述你想要的解决方案
+清晰简洁地描述你希望发生的事情。
+
+## 替代方案
+你考虑过的替代方案。
+
+## 附加上下文
+任何其他上下文、截图或示例。

sra_agent-0.0.0.dev0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## 描述
+
+请清晰描述这个 PR 做了什么。
+
+## 类型
+
+- [ ] Bug Fix
+- [ ] New Feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] Test
+
+## 检查清单
+
+- [ ] 测试已通过：`pytest tests/ -v`
+- [ ] 代码风格符合项目规范
+- [ ] 文档已更新（如需）
+- [ ] 相关 Issue 已引用
+
+## 相关 Issue
+
+Closes #
+
+## 附加上下文
+
+任何 Reviewer 需要知道的信息。

sra_agent-0.0.0.dev0/.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+# SRA CI — 自动化测试 + Lint + 类型检查
+# 每个 push/PR 自动运行
+name: CI
+
+on:
+  push:
+    branches: [master, main, feat/v2.0-enforcement-layer]
+  pull_request:
+    branches: [master, main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: 🧪 pytest (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 需要完整历史用于 setuptools-scm 版本推导
+
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: 📦 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: ✅ Verify test fixture integrity
+        run: python3 tests/check_fixtures.py 2>&1 || { echo "❌ Fixture 检查失败"; exit 1; }
+
+      - name: 🔍 Verify version (setuptools-scm)
+        run: |
+          python -c "from skill_advisor import __version__; print(f'Version: {__version__}')"
+
+      - name: 🧪 Run tests
+        run: |
+          python -m pytest tests/ -q --tb=short -o "addopts="
+
+  lint:
+    name: 🧹 Ruff lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Run ruff
+        run: ruff check skill_advisor/ tests/
+
+  typecheck:
+    name: 🔤 Mypy type check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true  # ⚠️ 逐步引入，当前不 block
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install deps
+        run: |
+          pip install -e ".[dev]" mypy
+      - name: Run mypy
+        run: |
+          mypy skill_advisor/ || echo "⚠️ mypy 发现类型问题（非阻塞，逐步修复中）"

sra_agent-0.0.0.dev0/.github/workflows/release.yml

@@ -0,0 +1,95 @@
+# SRA Release — 自动构建 + PyPI 发布 + GitHub Release
+# 触发: git tag v*.*.* 推送时
+name: Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+
+permissions:
+  contents: write
+  id-token: write
+  attestations: write
+
+jobs:
+  build:
+    name: 📦 Build distribution
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: 🧪 Run tests before build
+        run: |
+          pip install -e ".[dev]"
+          python -m pytest tests/ -q --tb=short -o "addopts="
+
+      - name: 🔨 Build wheel + sdist
+        run: |
+          pip install build
+          python -m build
+
+      - name: ⬆️ Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: 🚀 Publish to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sra-agent
+
+    steps:
+      - name: 📥 Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: 🚀 Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: 📝 Create GitHub Release
+    needs: [build]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: 📥 Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: 📝 Generate release notes
+        id: notes
+        run: |
+          # Extract version from tag
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: 🏷️ Create Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "v${{ steps.notes.outputs.version }}" \
+            --notes "SRA Agent v${{ steps.notes.outputs.version }}" \
+            dist/*.tar.gz dist/*.whl

sra_agent-0.0.0.dev0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+*.whl
+
+# SRA 数据
+*.sra_agent/
+data/
+skill_usage_stats.json
+skill_full_index.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+venv/
+.venv/
+
+# Test artifacts
+.pytest_cache/
+htmlcov/
+.coverage

sra_agent-0.0.0.dev0/.hermes/AGENTS.md

@@ -0,0 +1,146 @@
+# HERMES AGENT RULES
+
+## 🔴 P0: REALITY CHECK FIRST (PREREADING GATE)
+
+**BEFORE** reading any project documentation to analyze "current state", you **MUST**:
+
+1. **🔍 Scan code reality first**:
+   - `git log --oneline -30` — See what actually happened recently
+   - `git diff --stat` — See uncommitted changes
+   - `pytest --collect-only -q` (if applicable) — Get actual test count
+
+2. **🧪 Cross-verify doc claims vs code**:
+   - If a doc says "test_dropin.py doesn't exist", check if it actually does
+   - If a doc says "version is v1.2.1", check __init__.py + pyproject.toml
+   - If a doc lists issues as "unfixed", check `git log` for fix commits
+
+3. **⏱️ Check doc timestamps**:
+   - Is the doc dated? Is it from before or after the latest code changes?
+   - If a doc has no timestamp, assume it's stale until verified.
+
+> **Core principle**: Trust the code, verify the docs. Docs describe the past;
+> code describes the present. Always let code reality override document claims.
+
+## 🛑 MANDATORY WORKFLOW (CRITICAL)
+
+**BEFORE** starting ANY task or calling ANY tool (except `skill_finder` or `pre_flight`), you **MUST** follow this sequence:
+
+1. **🔍 Run Reality Check** (see P0 above)
+
+2. **🛑 Run Pre-Flight Check**:
+    - Execute: `python3 ~/.hermes/scripts/pre_flight.py "<Task Name>"`
+    - **IF** the output contains `BLOCKED`, you **MUST STOP** immediately.
+    - **IF** the output is `PASS`, proceed to step 3.
+
+3. **📡 Run Skill Discovery**:
+    - Execute: `python3 ~/.hermes/skills/learning-workflow/scripts/skill_finder.py "<Task Keywords>"`
+    - **IF** a skill is found (Match >= 30), you **MUST** load it with `skill_view`.
+    - **NEVER** skip this step to "save time".
+
+4. **📋 SDD Spec 门禁 — 没有批准的 Spec 就不写代码**:
+    - **执行门禁检查**:
+      ```bash
+      # 自动检查当前任务是否需要 Spec
+      python3 ~/.hermes/skills/sdd-workflow/scripts/spec-gate.py enforce "<任务描述>"
+      if [ $? -ne 0 ]; then
+          echo "🛑 SDD 门禁拦截！"
+          echo "   1. 创建 Spec: cp docs/STORY-TEMPLATE.md docs/stories/STORY-XXX-NN.md"
+          echo "   2. 初始化: python3 ~/.hermes/skills/sdd-workflow/scripts/spec-state.py create \"STORY-XXX-NN\" \"标题\""
+          echo "   3. 填充内容后提交审阅"
+          exit 1
+      fi
+      ```
+
+## 🧹 POST-TASK: MANDATORY DOCUMENTATION ALIGNMENT + PRE-COMMIT VERIFICATION
+
+**AFTER** completing any development task (story/sprint/bugfix/feature), **BEFORE** committing code, you **MUST**:
+
+### Phase 0: 测试基础设施检查（写新测试前的强制前序）
+
+**写新测试前，必须执行：**
+
+```bash
+# 0.1 扫描已有 fixture 模式
+grep -rn "FIXTURES_DIR\|fixtures/" tests/ 2>/dev/null | head -10
+
+# 0.2 检查 fixture 目录是否存在
+ls tests/fixtures/ 2>/dev/null || echo "⚠️  无 fixture 目录"
+
+# 0.3 如果 fixture 存在，新测试必须优先使用它
+# 禁止直接引用 ~/.hermes/skills —— CI 中没有此目录！
+```
+
+**🔴 铁律**: 如果有 `tests/fixtures/` 目录，新测试中**禁止**出现 `~/.hermes/skills`。
+违反此规则的测试将被视为「有缺陷的测试 —— CI 不可运行」。
+
+参考 `tests/TEST-DATA-MANIFESTO.md` 了解所有可用 fixture。
+
+### Phase 1: 本地 CI 预演（验证通过后才能提交）
+
+```bash
+# 1. 测试基础设施健康检查
+python3 -c "
+import os
+d = 'tests/fixtures/skills'
+count = sum(1 for _,_,files in os.walk(d) for f in files if f == 'SKILL.md')
+assert count >= 300, f'Fixture 不完整: {count}'
+print(f'✅ {count} valid fixture skills')
+"
+
+# 2. 扫描新测试是否引用了运行时依赖（这是 P0 违规）
+grep -rn "hermes/skills\|~/.hermes" tests/ 2>/dev/null && {
+    echo "❌ 测试中禁止引用 ~/.hermes/skills！请用 tests/fixtures/ 替代"
+    exit 1
+} || echo "✅ 无测试依赖运行时环境"
+
+# 3. Ruff lint — 代码风格
+ruff check skill_advisor/ tests/ || exit 1
+
+# 4. 全量测试
+python -m pytest tests/ -q --tb=short -o "addopts=" || exit 1
+
+# 5. 版本检查
+python -c "from skill_advisor import __version__; print(f'Version: {__version__}')"
+```
+
+> ⚠️ **不要等 CI 告诉你失败了**。本地预演能提前发现 95% 的问题。
+> CI 实战教训：测试依赖本地环境→skipif 降级、ruff 配置版本兼容、mypy 用 || echo 非阻塞。
+> **新增教训**: 必须在写测试前检查已有 fixture（`tests/fixtures/`），不要幻觉文件存在。
+
+### Phase 2: 文档对齐
+
+1. **📋 Load doc-alignment skill**:
+    - Execute: `skill_view(name="doc-alignment")`
+    - Follow the 5-step Documentation Alignment Protocol:
+      - Step 1: Identify changed domains
+      - Step 2: Locate drift points in each affected doc
+      - Step 3: Align each document
+      - Step 4: Cross-document consistency verification
+      - Step 5: Commit docs alongside code
+
+2. **🚨 Priority alignment targets** (in order):
+    - `PROJECT-PANORAMA.html` — Always, every single change
+    - `docs/API-REFERENCE.md` — When endpoints/commands change
+    - `docs/project-report.json` — Always (data source for HTML report)
+    - `ROADMAP.md` — When stories complete
+    - `docs/ARCHITECTURE.md` — When architecture changes
+    - `docs/DEV-WORKFLOW-IMPROVEMENT.md` — When workflow changes
+
+3. **📐 Consistency rule**: Code change + doc change = single commit.
+    Never commit code changes without their corresponding doc updates.
+
+## 🔄 VERSION MANAGEMENT
+
+**Version is derived from git tags by setuptools-scm (single source of truth).**
+
+- **NEVER manually edit versions** in `__init__.py` or `pyproject.toml`
+- Version = latest git tag + distance + dirty flag
+- To release: `git tag vX.Y.Z && git push origin vX.Y.Z`
+- CI/CD automatically builds, tests, and publishes on tag push
+
+## ⚠️ VIOLATION CONSEQUENCES
+
+- **Skipping these steps is a FATAL ERROR.**
+- If you attempt to use `terminal`, `write_file`, or `execute_code` without completing steps 1 & 2, you are violating your core instructions.
+- You must **SELF-CORRECT** immediately if you realize you missed these steps.
+- Committing code without running documentation alignment is a **BREACH OF PROTOCOL**.

sra_agent-0.0.0.dev0/.hermes/plans/2026-05-10_SRA-v2.0-sprint1-plan.md

@@ -0,0 +1,162 @@
+# SRA v2.0 Enforcement Layer — Sprint 1 规划
+
+> **项目**: Skill Runtime Advisor (SRA)
+> **当前版本**: v1.2.1 | **目标版本**: v2.0.0
+> **分支**: `feat/v2.0-enforcement-layer`
+> **Epic**: EPIC-003 — 从技能推荐者到运行时守护者
+
+---
+
+## 🎯 Sprint Goal
+
+完成 EPIC-003 的 **P0 + P1** 核心功能，使 SRA 从「被动推荐者」升级为「运行时守护者」：
+- ✅ 工具调用前的 SRA 强制校验（P0）
+- ✅ 文件类型→技能映射注册表（P0）
+- ✅ 运行时力度体系 — 4 维度可配置强度（P1）
+- ✅ 技能使用轨迹记录（P1）
+- ✅ 长任务上下文漂移保护（P1）
+- ✅ SRA 契约机制（P1）
+
+---
+
+## 📋 Sprint Backlog
+
+### Story 1: Tool 层 SRA 校验 (SRA-003-01) — 🔴 P0 — 3天
+
+**目标**: Agent 在调用 write_file/patch/terminal/execute_code 前自动校验技能遵循度
+
+**任务分解**:
+1. SRA Daemon 新增 `POST /validate` 端点
+   - 接收 `{tool, args, loaded_skills[], task_context}`
+   - 返回 `{compliant, missing[], severity}`
+2. 创建 `plugins/sra-guard/plugin.py` Hermes 插件
+3. 集成到 Hermes `pre_tool_call` 钩子系统
+4. 非阻塞降级：SRA 不可用时不影响工具执行
+5. 编写测试用例
+
+**文件变更**:
+- 新增: `skill_advisor/runtime/endpoints/validate.py`
+- 新增: `plugins/sra-guard/plugin.py`
+- 修改: `skill_advisor/runtime/daemon.py`
+- 修改: `tests/`
+
+### Story 2: 文件类型技能映射 (SRA-003-02) — 🔴 P0 — 2天
+
+**目标**: 通过文件扩展名自动推导所需技能
+
+**任务分解**:
+1. 创建 `FILE_SKILL_MAP` 映射表 (`config/skill_map.json`)
+2. 集成到 `POST /validate` 校验中
+3. 支持用户自定义扩展映射
+4. 编写测试用例
+
+**文件变更**:
+- 新增: `skill_advisor/skill_map.py`
+- 新增: `skill_advisor/config/skill_map.json`
+
+### Story 3: 技能使用轨迹记录 (SRA-003-03) — 🟡 P1 — 2天
+
+**目标**: 追踪技能加载和实际使用情况，检测模式偏差
+
+**任务分解**:
+1. 增强 `POST /record` 端点支持 `action: "viewed"|"used"|"skipped"`
+2. Hermes `skill_view()` 拦截自动上报
+3. Hermes 工具调用后自动上报
+4. 场景记忆记录使用序列
+
+**文件变更**:
+- 修改: `skill_advisor/runtime/daemon.py`
+- 修改: `skill_advisor/memory.py`
+- 修改: Hermes `run_agent.py`
+
+### Story 4: 长任务上下文保护 (SRA-003-04) — 🟡 P1 — 2天
+
+**目标**: 长任务执行中定期重注入技能建议，防止上下文漂移
+
+**任务分解**:
+1. Hermes `run_conversation()` 每 5 轮自动重查询 SRA
+2. SRA 新增 `recheck()` 基于对话摘要
+3. `[SRA 提醒]` 轻量级注入
+4. 可配置提醒间隔
+
+**文件变更**:
+- 修改: Hermes `run_agent.py`
+- 修改: `skill_advisor/advisor.py`
+
+### Story 5: SRA 契约机制 (SRA-003-05) — 🟡 P1 — 2天
+
+**目标**: 任务开始时生成技能契约，明确推荐技能优先级
+
+**任务分解**:
+1. `POST /recommend` 返回新增 `contract` 字段
+2. `build_contract()` 方法生成契约
+3. 契约信息格式化到 `rag_context`
+4. 契约在 `/validate` 校验时参考
+
+**文件变更**:
+- 修改: `skill_advisor/runtime/daemon.py`
+- 修改: `skill_advisor/advisor.py`
+
+### Story 6: 运行时力度体系 (SRA-003-06) — 🟡 P1 — 3天
+
+**目标**: 4 级注入覆盖度体系，从 basic(仅消息) → omni(全钩子+频率注入)
+
+**核心原则**: 永不阻断（no blocking），只注入推荐上下文
+
+**任务分解**:
+1. 设计 4 级注入覆盖度配置（`runtime/force.py`）
+   - **basic**: 仅用户消息时 POST /recommend
+   - **medium**: 消息 + pre_tool_call(关键工具)
+   - **advanced**: 消息 + pre_tool_call(全部工具) + post_tool_call
+   - **omni**: 全部 + 每 N 轮周期性重注入
+2. 注入点路由引擎 — 根据力度级别条件启用/禁用注入点
+3. 非阻塞设计：所有注入点只有 info/warning 级别
+4. 集成到 daemon.py 端点（按力度级别条件服务）
+5. L4 周期性重注入 `recheck()` 方法（基于对话摘要）
+6. `sra config set runtime_force.level` CLI 命令
+7. 编写测试用例验证各层级注入点启停
+
+**文件变更**:
+- 新增: `skill_advisor/runtime/force.py`
+- 修改: `skill_advisor/runtime/daemon.py`
+- 修改: `skill_advisor/cli.py`
+- 修改: `skill_advisor/advisor.py`
+- 新增: `tests/test_force.py`
+
+---
+
+## 📊 估时汇总
+
+| Story | 优先级 | 预估天数 | 依赖 |
+|:-----|:------:|:--------:|:----:|
+| SRA-003-01 Tool 层校验 | 🔴 P0 | 3 | — |
+| SRA-003-02 文件类型映射 | 🔴 P0 | 2 | — |
+| SRA-003-03 轨迹记录 | 🟡 P1 | 2 | SRA-003-01 |
+| SRA-003-04 上下文保护 | 🟡 P1 | 2 | — |
+| SRA-003-05 契约机制 | 🟡 P1 | 2 | SRA-003-01 |
+| SRA-003-06 运行时力度体系 | 🟡 P1 | 3 | SRA-003-01 |
+| **合计** | | **~14天** | |
+
+**Burndown 节奏**: 每个 Story 完成后进行 Code Review + 测试验证
+
+---
+
+## ✅ 验收标准（Sprint DoD）
+
+- [ ] 所有 P0 Story 完成：POST /validate + FILE_SKILL_MAP
+- [ ] 至少两个 P1 Story 完成（含 SRA-003-06 运行时力度体系）
+- [ ] 所有新增 API 有集成测试覆盖
+- [ ] 力度体系 4 级注入覆盖度全部可切换生效（无阻断）
+- [ ] 测试覆盖率 ≥ 90%
+- [ ] CHANGELOG.md 更新
+- [ ] ROADMAP.md 进度更新
+
+---
+
+## 🔄 风险管理
+
+| 风险 | 概率 | 影响 | 应对 |
+|:----|:----:|:----:|:-----|
+| pre_tool_call 钩子系统不兼容 | 中 | 高 | 调研 model_tools.py 722-737 行代码 |
+| SRA 不可用时 Agent 阻塞 | 低 | 高 | 超时降级 + try/except 兜底 |
+| 追踪数据膨胀 | 低 | 中 | 设定内存上限，定期归档 |