giggsoinc/raven

# Raven v4.1.0 **AI 编码速度快。Raven 强制执行纪律 —— 战略思维、可扩展结构、源头安全。** 简单来说，它是如何工作的： - **战略思维** —— 在 Raven 让 AI 接触你的代码之前，它会制定一个计划，从三个角度（业务、技术、数据 —— 外加一个评论者）对该计划进行评估，并等待你的指令。Bug 不是靠猜的：通过 2 轮分诊首先找到根本原因。 - **可扩展结构** —— 每个 prompt 都会自动路由给正确的专家。由确定性规则挑选的 61 个专家，每个领域一个 —— 并且你总会看到一行说明，告知是谁在处理以及为什么。无论是在一个还是一百个 repo 中，工作方式都一样。 - **源头安全** —— 防护机制在你的机器上运行，在代码编写和提交的那一刻：拦截密钥，拦截有漏洞的库，并在真正完成思考之前拦截编辑。不是损坏后的报告 —— 而是之前的一道闸门。 全部本地化。零遥测。MIT 协议。 ## 安装 (Claude Code 插件市场) ``` /plugin marketplace add giggsoinc/raven /plugin install raven@raven ``` 然后重启你的会话。你应该会看到 Raven 的欢迎信息： ``` 🪶 Raven ✅ | {your-project} | {stack} Andie is your discipline layer. What are you working on? ``` ## 快速开始 | 你输入的内容 | 会发生什么 | |---|---| | `why is auth failing since yesterday?` | 路由至 **andie-jr** —— 2 轮分诊：根本原因 → 修复 → 审计记录 | | `should we use Postgres or Mongo here?` | 路由至 **andie** —— 一个模式卡片，3 角度审查，你批准每一个步骤 | | `/andie` 或 `/andie-jr` | 显式强制路由 | | 带有已暂存 API key 的 `git commit` | 在 pre-commit 闸门处**硬拦截**，并显示触发它的代码行 | | `rename this variable` | 不进行路由 —— 琐碎的编辑跳过这些繁琐流程 | ## 包含内容 - **2 个 orchestrator** —— Andie（计划优先，一个硬性闸门，评论者声音）和 Andie-Jr（brownfield 调试，最多 2 轮） - **确定性路由器** —— repo 状态 + 意图路由，带有可见的单行提示框；绝不静默路由 - **61 项领域技能** —— FastAPI、Postgres、K8s、Terraform、Salesforce、Odoo、Oracle、AWS/GCP/Azure 等，仅在你的工作匹配时加载 - **本地防护** —— 每次提交时进行密钥扫描 + CVE 检查（CVSS >7 则拦截）；可选的编辑闸门（`raven-skill-gate`，影子/软/硬模式）；风格和架构检查 - **成本感知模型路由** —— 将 prompt 分类至满足要求的最低成本层；将充满密钥的上下文强制路由至本地模型 - **审计 + 记忆** —— JSONL 审计日志、会话记录、token 仪表板 —— 全部位于本地磁盘上 ## 何时使用 Raven —— 用例表 | 场景 | Raven | 普通 Claude | 备注 | |----------|-------|-------------|-------| | **Brownfield bug** — *“为什么 auth 超时？”* | ✅ 更快 | ❌ | 2 轮分诊胜过开放式探索；在修复前强制找出根本原因。 | | **架构决策** — *“我们应该迁移到 Postgres 吗？”* | ✅ 更好 | ❌ | 三人小组（功能/技术/数据）能捕捉单一视角遗漏的角度。 | | **提交时的安全性** — 防止密钥/CVE 被推送 | ✅ 硬拦截 | ❌ | 基于模式的检测；降低风险，但非万无一失。 | | **常规功能开发** — *“为我构建一个登录表单”* | ❌ 较慢 | ✅ 更快 | Raven 增加了繁琐流程；普通 Claude 更直接。 | | **快速查询** — *“CloudRun 的定价是多少？”* | ❌ 过于多余 | ✅ 直接 | 无需决策；Raven 的路由开销被浪费了。 | ## Andie + Andie-Jr：决策二人组 ### Andie（架构、设计、战略） 当你的决策存在权衡时，运行一个 **Drama 小组辩论**： - **功能主管** —— 业务/领域所有者视角 - **技术主管** —— 系统/实现所有者视角 - **数据主管** —— 指标/集成所有者视角 每位小组成员从他们的角度进行辩论。你来引导辩论。最终输出：**决策 + 理由 + 被否决的替代方案 + 风险**。 ### Andie-Jr（Brownfield 分诊） 针对损坏的系统：**问题 → 诊断 → 修复 → 审计**。 - 第 1 轮：2 个澄清问题，以隔离根本原因。 - 第 2 轮：根本原因解释 + 修复 + 验证步骤 + 审计记录。 不适用于 greenfield 构建；仅适用于表现出症状（错误、超时、回归）的现有系统。 ### 路由表 | 场景 | 路由 | 方式 | |----------|-------|-----| | **Brownfield bug**（“为什么 X 坏了？”） | andie-jr | Repo >1 次提交 + 检测到症状语言 | | **Greenfield 或架构**（“我们应该……？”） | Andie | Repo ≤1 次提交 或检测到 Drama 模式意图 | | **数据问题**（“什么是……？”、“列出……”、“显示……”） | 直接 | 没有变更动词（构建、修复、创建）；没有路由开销 | | **强制路径**（`/andie`，`/andie-jr`） | 显式 | 用户输入了技能名称 —— 路由始终获胜 | ## Raven 的工作原理 —— 完整技术栈 ### 架构概览 ``` UserPromptSubmit (every message) ↓ triage-router.py [deterministic repo-state] ├─ Brownfield (>1 commit) → andie-jr ├─ Greenfield (≤1 commit) → Andie ├─ Data question (read/list/explain, no change verbs) → direct └─ Force path (/andie, /andie-jr) → always wins ↓ [Specialist runs, edit/commit allowed] ↓ PostToolUse: secret-scan.py (after Write/Edit) ├─ AWS keys, OpenAI keys, GitHub tokens, SSH, bearer tokens → WARN └─ Send intent to audit log (`.raven/audit/YYYY-MM-DD.log`) ↓ Pre-commit hook (.git/hooks/pre-commit) ├─ secret-scan.py → HARD BLOCK if secrets staged ├─ cve-check.py (new imports) → HARD BLOCK if CVSS >7 ├─ style-enforcer (line count, type hints, docstrings) → HARD BLOCK if violated ├─ architecture-guard (doc alignment) → WARN now, block in 24h ├─ db-guard (inline SQL, missing ERDs, migration order) → WARN └─ notify.py (SMTP + Slack) → send pass/fail summary + audit ↓ Commit lands (or blocked + approval flow starts) ``` ### 7 个 Guard Agent —— 检查内容 | Guard | 触发时机 | 检测内容 | 动作 | |-------|-------|---------|--------| | **manifest-checker** | SessionStart | 缺少 `.raven/manifest.json` | 硬停止并提供设置指南 | | **secret-guard** | PostToolUse + pre-commit | 已暂存文件中的 AWS key、token、SSH、PII | 编辑时警告 / 提交时硬拦截 | | **cve-check** | 新的 `import X` 语句 | 库漏洞 (CVSS >7) | 编码时警告 / 提交时硬拦截 | | **stack-validator** | 检测到导入 + 不在批准列表中 | 未批准的库（Polans 对比 Pandas 等） | 提交时警告 / 拦截 | | **style-enforcer** | 文件编辑 | 行数 >200、缺少类型提示、无文档字符串 | 提交时建议 / 拦截 | | **architecture-guard** | 创建新文件 | 缺少 `.raven/architecture.md` 文档 | 24 小时宽限期后警告 / 硬拦截 | | **db-guard** | 文件编辑（SQL、migration） | 非 SQL 文件中的内联 SQL、缺少 ERD、损坏的 migration 编号 | 在审计日志中警告 | ### 通知 (SMTP + Slack) 在 pre-commit hook 成功或被拦截时触发： - **提交通过**：确认邮件 + Slack（发送给 `.raven/manifest.secrets.json` 中的收件人） - **提交被拦截**：包含违规次数的警报 + Slack - **使用了覆盖**：记录至审计轨迹 + 邮件 - **Token 警告**：75% / 90% 阈值 ## Token 经济学 —— Raven 每条消息的成本 **规则：强制执行在 Python hook 中运行，在模型之外 —— 消耗零 token。** 闸门、防护机制、扫描器、审计日志和 pre-commit pipeline 永远不会进入 Claude 的上下文。只有薄薄的咨询层才会： | 层 | 频率 | Token | |---|---|---| | Hook：技能闸门、密钥扫描、CVE、pre-commit、token 守卫 | 每次工具调用 / 提交 | **0** | | 技能提醒 + 路由提示框（上下文注入） | 每条消息 | ~100 | | 会话启动（问候 + 透明横幅） | 每个会话一次 | ~500 | | 专家 SKILL.md 加载（当技能实际运行时） | 每个会话一次 | ~1–2k | | 违规消息（拦截/警告） | 仅在违规时 | ~50 | 稳态：典型会话的**约 2% 开销** —— 并且模型路由器 （0 token hook）通过将简单的 prompt 分层到更便宜的模型，并 将充满密钥的上下文路由到免费的本地模型来挽回这些开销。完整明细，包括 Raven 节省 token 的地方：[docs/TOKENOMICS.md](docs/TOKENOMICS.md) · 图表：[业务视图](docs/Agent_token_architecture_business.html) · [技术视图](docs/Agent_token_architecture_tech.html)。 ## 各版本功能 ### **Raven v4.1.0**（当前版本） —— 隐私 + 路由强化 **新增：** - 隐私强化：从 manifest 中清除了更新日志，所有注册表中的个人电子邮件被替换为组织电子邮件。 - **关键路由修复**：确定性的 repo 状态逻辑取代了正则表达式分类。Brownfield → andie-jr，greenfield → Andie，数据问题 → 直接。修复了将调试误分类为新工作的问题。 **从 v4.0 延续：** - Andie Drama 模式（关于权衡的 3 人小组辩论） - Andie-jr 快速分诊（2 轮根本原因流程） - 61 项领域技能（ML、Salesforce、Odoo、K8s、Terraform 等） - 提交时的密钥 + CVE 扫描 - 跨会话记忆（`.raven/memory/`） - SMTP + Slack 通知 ### **Raven v4.0.0** —— 诚实通关 + 首次发布 - 重写的 README：没有虚假声明，诚实的投资回报率（ROI）部分，按角色定制的消息传递。 - 验证了 61 项技能（纠正了之前的计数错误）。 - CLAUDE.md 顶部的每回合纪律契约；Raven/Lucky 闸门；真实的 hook 名称。 - Andie 中的首次入职引导：brownfield 自我检测与 greenfield 设置对比（≤2 个问题）。 - `/andie` + `/andie-jr` 强制路径命令；插件现在捆绑了 12 个命令。 - `notify.py`：连接到 pre-commit 的真实 SMTP + Slack。 - `install-claudemd.py`：仅追加的 CLAUDE.md 安装程序（从不删除用户内容）。 - 会话开始时的透明横幅。 ### **以前的版本** 有关 v3.x 及更早版本，请参阅 [CHANGELOG.md](CHANGELOG.md)。 ### 升级路径 - **v4.0 → v4.1**：直接替换。运行 `/raven-sync` 同步 manifest；无需更改配置。 - **v3.x → v4.0+**：不向后兼容。请参阅 CONTRIBUTING.md 中的迁移指南。 ## 其他安装路径 **Claude Desktop (ZIP)：** 下载 [`raven-plugin-v4.1.0.zip`](plugin/raven-plugin-v4.1.0.zip) → 设置 → 扩展 → 添加插件 → 拖入 ZIP → 重启。 **从源码构建：** ``` git clone https://github.com/giggsoinc/raven.git cd raven && bash plugin/make-plugin.sh # builds plugin/raven-plugin-v4.1.0.zip ``` ## Raven 企业版 此 repo 是**免费层 —— 一切都在本地运行**，采用 MIT 许可证，保持原样即完整。 **Raven 企业版**（付费，单独出售）在此基础上添加了团队和合规部门所需的内容：跨开发者和 repo 的 Hub 仪表板、按开发者的 token 归因和计费、合规/审计报告、集中式策略同步以及商业支持。 → [giggso.com](https://giggso.com) ## 支持与问题 - **Bug 报告**：[GitHub Issues](https://github.com/giggsoinc/raven/issues) - **问题**：在 [GitHub Discussions](https://github.com/giggsoinc/raven/discussions) 中发起讨论 - **安全漏洞**：发送电子邮件至 `rv@giggso.com`（请勿公开 issue）

由 Giggso 构建 · GitHub · MIT 许可证

*Raven v4.1.0 —— 为以思考速度进行的 AI 编码提供治理。*

标签：AI编程助手, Claude Code, DevSecOps, 上游代理, 安全扫描, 时序注入, 逆向工具