sage-kernel

<div align="center"> # Sage Kernel ### 一个优先考虑证明的、适用于本地机器的MCP原生工程操作系统 **一个可控的界面，您和AI编码代理都可以在此检查任何仓库，运行完整的SDLC，并凭借证据而非感觉交付。** [](LICENSE) [](package.json) [](docs/MCP_SERVER.md) [](docs/mcp-tools.md) [](docs/RELEASE_PROCESS.md) [](package.json) [快速开始](#-60%E5%88%AB%E5%BF%AB%E9%80%9F%E5%90%AF%E5%8A%A8) · [工作原理](#-%E5%B7%A5%E4%BD%9C%E5%8E%9F%E7%84%A1) · [功能](#-%E5%90%8E%E6%9C%AA%E5%90%8E%E5%90%8C%E5%AD%97%E5%90%8C%E6%AD%A5%E5%99%A8) · [架构](#-%E6%9E%B6%E6%9E%B6) · [语言支持](#-%E8%AF%AD%E8%A8%80%E6%94%AF%E6%89%81%E6%9C%AA%E5%90%8E%E5%90%8C%E5%AD%97%E5%90%8C%E6%AD%A5%E5%99%A8) · [文档](#-%E6%96%87%E6%A1%A3%E6%A1%8C%E5%9B%BE) </div> --- > [!NOTE] > **诚实的范围，一开始就说清楚。** *深入*的分析引擎（AST代码审查，SAST + taint，执行覆盖率）是**JavaScript / TypeScript / Node原生**的。其他语言通过正确的工具链命令推断获得配置文件检测 + 仓库元检查。Sage Kernel是一个**MCP stdio服务器** — 它在任何MCP功能的客户端（Claude Code，Claude Desktop，Cursor，Windsurf，Cline，Codex）中工作。 它不能从非MCP聊天机器人使用。参见[功能矩阵](#-语言支持-诚实)。 --- ## ✦ 为什么选择Sage Kernel 现代软件工作分散在十几个界面上 — 终端命令、代理提示、QA脚本、模板、安全扫描、发布检查、批准决策、运行历史和文档。Sage Kernel将它们合并成**一个可审计的本地控制平面**，人类和AI代理可以通过相同的协议驱动。 它的定义原则是**优先考虑证明**：没有任何事情是“完成”的，因为模型说可以。每个结果都有一个真实的工件作为证据，或者诚实地报告为阻止。没有假的绿色。 ``` 向内核提问 ─► 它运行真正的网关 ─► 它记录证明 ─► 你（或你的代理）信任结果 ``` --- ## ⚡ 60秒快速开始 ```bash git clone https://github.com/JasonTeixeira/sage-kernel.git cd sage-kernel npm install # Node >= 22, 零依赖 npm run mcp:smoke # 真实的客户端握手 — 打印“passed, 140 tools” # 指向任意仓库并获得真实的SDLC评估（只读）： npm run onboard -- /path/to/your/project ``` 您将获得一个单屏报告：检测到的配置文件、循环得分、审查得分、安全状态、所需检查和顶部间隙 — 根据**您的**仓库实际内容计算。您的代码永远不会被修改。 <details> <summary><strong>将其连接到您的AI客户端（永久）</strong></summary> ```jsonc { "mcpServers": { "sage-kernel": { "command": "node", "args": ["apps/mcp-server/src/server.mjs"], "cwd": "/绝对路径/to/sage-kernel", "env": { "SAGE_PROFILE_ALLOWED_ROOTS": "/Users/you/code:/Users/you/work" } } } } ``` - `cwd` **必须**是内核检查（它相对于`cwd`解析自己的DB）。 - `SAGE_PROFILE_ALLOWED_ROOTS`列出内核可以分析的父目录。 - 完整教程： **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)**。 </details> --- ## ✦ 工作原理 Sage Kernel在每个任务上运行相同的有纪律的循环 — 高级工程师遵循的操作顺序，使其机械化和可证明。 ```mermaid flowchart LR A["① ORIENT<br/>profile.gaps"] --> B["② DEFINE DONE<br/>done.generate"] B --> C["③ LOOP<br/>operate / gates"] C --> D{"④ PROVE<br/>enforce.proof_gate"} D -- "no fresh proof" --> C D -- "diff-matched passing proof" --> E["⑤ SCORE<br/>loop.score"] E --> F(("Result<br/>backed by ledger")) style A fill:#0ea5e9,color:#fff,stroke:#0369a1 style C fill:#6366f1,color:#fff,stroke:#4338ca style D fill:#f59e0b,color:#111,stroke:#b45309 style E fill:#16a34a,color:#fff,stroke:#15803d style F fill:#111827,color:#fff,stroke:#000 ``` 保证是**完整性，而不是数字**：声称“完成/验证/通过”仅在存在新鲜的、差异匹配的、通过的证明时有效。否则，内核会以`blocked_*`和下一步骤的形式报告。 --- ## ✦ 功能 ```mermaid flowchart TB subgraph CLIENT["您的MCP客户端"] H["👤 人类"] AI["🤖 AI编码代理"] end CLIENT -->|"stdio · JSON-RPC"| SRV subgraph SRV["Sage Kernel — MCP服务器（140种工具）"] direction TB P["配置文件和SDLC<br/>profile · done · loop · score"] R["审查和安全<br/>AST审查 · SAST · taint · 供应链"] T["测试<br/>影响映射 · 覆盖率 · 突变 · 应力"] O["操作和自主<br/>操作循环 · 自我修复 · 驱动目标"] G["生成<br/>模板 · 脚手架 · 蓝图"] J["运维<br/>作业 · 批准 · 仪表盘 · 审计日志"] end SRV --> ENG[["引擎<br/>acorn AST · 数据流 · 配置文件"]] SRV --> LEDGER[["证明账本<br/>哈希链 · HMAC签名"]] SRV --> DB[("SQLite 默认<br/>Postgres 可选")] style CLIENT fill:#1e293b,color:#fff,stroke:#0f172a style SRV fill:#312e81,color:#fff,stroke:#1e1b4b style LEDGER fill:#7c2d12,color:#fff,stroke:#431407 style ENG fill:#155e75,color:#fff,stroke:#083344 style DB fill:#374151,color:#fff,stroke:#111827 ``` | 功能 | 您获得的内容 | | --- | --- | | **检查任意仓库** | 检测项目配置文件，计算完成定义，评分健康状况，并显示真实的间隙 — 只读。 | | **审查和加固** | 基于AST的代码审查，涵盖5个维度；SAST + 过程内污点分析（命令注入、eval、路径遍历、弱加密、原型污染、SSRF…）。 | | **深入测试** | 影响映射的测试选择、执行基础的覆盖率测试、突变测试和压力/混沌矩阵。 | | **自主操作** | 自我修复的循环驱动一个真实的模型来修复故障、**证明或丢弃**，并重新验证 — 带有类型停止条件。 | | **生成** | 从机器可读的目录生成生产应用程序模板和脚手架。 | | **治理** | 签名批准、权限边界、篡改证据的审计日志和本地运维仪表盘。 | --- ## ✦ 架构 ```mermaid flowchart TD subgraph APPS["apps/"] MCP["mcp-server<br/>stdio · 140种工具 · 合同"] DASH["dashboard<br/>本地运维控制台"] WRK["worker<br/>作业 · 队列 · 运行"] end subgraph PKGS["packages/"] CORE["core<br/>运行时 · 策略 · 错误信封"] AST["ast<br/>acorn 解析 + 遍历"] REV["审查 · 安全<br/>SAST · 污点 · 供应链"] TEST["测试<br/>影响 · 覆盖率 · 突变"] PROF["配置文件<br/>检测 · 工具链"] COMP["伴侣<br/>操作循环 · 分解 · 驱动目标"] PROOF["证明<br/>账本 · 图 · 声明防火墙"] DBP["数据库<br/>sqlite · postgres适配器"] end CAT["目录/<br/>仓库 · 模板 · 阶段"] MCP --> CORE --> AST CORE --> REV & TEST & PROF & COMP REV & TEST & PROF & COMP --> PROOF CORE --> DBP MCP --> CAT DASH --> CORE WRK --> CORE style APPS fill:#1e3a8a,color:#fff,stroke:#1e1b4b style PKGS fill:#0f766e,color:#fff,stroke:#134e4a style PROOF fill:#7c2d12,color:#fff,stroke:#431407 ``` | 层 | 路径 | 责任 | | --- | --- | --- | | MCP服务器 | `apps/mcp-server/` | stdio服务器，140种工具清单，资源，提示，合约，烟雾测试 | | 运行时 | `packages/core/` | 工具调度，策略/批准检查，统一`{ok,data}`/`{ok,error}`信封 | | 分析引擎 | `packages/{ast,review,security,testing,profiles}/` | acorn AST，SAST + 污点，覆盖率，配置文件检测 | | 伴侣循环 | `packages/companion/` | 操作循环，目标分解，自主驱动，能力注册 | | 证明主干 | `packages/proof/` | 哈希链 + HMAC签名账本，证明图，声明防火墙 | | 持久性 | `packages/db/` | SQLite（默认）和Postgres适配器，迁移/备份/恢复 | 完整详情： **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** · **[docs/RUNTIME_ENGINE.md](docs/RUNTIME_ENGINE.md)** --- ## ✦ 真实的交互 ```mermaid sequenceDiagram participant U as 您 / AI代理 participant K as Sage Kernel participant L as 证明账本 U->>K: kernel.profile.gaps { projectPath } K-->>U: { ok, profile, confidence, gaps[] } U->>K: kernel.operate.run { goal, acceptanceCriteria, files } K->>K: 并发运行网关 · 诊断 · 修复 · 重新验证 K->>L: 记录每个网关的证明（差异哈希） K-->>U: { ok, status, score, evidenceIds[] } U->>K: kernel.enforce.proof_gate K->>L: 当前差异是否得到通过证明的支持？ K-->>U: { allowed: true, proofId } ← 只有这样才算“完成” ``` 每个工具都返回一个统一的信封 — 成功是 `{ ok: true, data }`，失败是 `{ ok: false, error: { code, kind, message } }`。服务器在错误的调用时永远不会崩溃；它会返回一个类型化的错误。 --- ## ✦ 语言支持（诚实） Sage Kernel检测和评估**任何**项目，但分析深度是JS/TS原生。 此矩阵精确地设置了期望： | 功能 | JS / TS / Node | Python | Go · Rust · Java · Ruby · PHP · Swift | | --- | :---: | :---: | :---: | | 配置文件检测 + 完成定义 | ✅ 深入 | ✅ | ✅ | | 循环得分 · 间隙 · 所需检查 | ✅ | ✅ 元数据 | ✅ 元数据 | | AST代码审查（`review.quality_score`） | ✅ 结构 | ⚠️ 启发式 | ⚠️ 元数据 | | SAST + 污点（`security.proof`） | ✅ AST数据流 | ⚠️ 正则表达式规则 | ❌ 仅元数据 | | 执行覆盖率 / 测试运行 | ✅ `node --test` | ➖ 推断 | ➖ 推断 | | 工具链命令 | `npm` | `pytest` | `go test` · `cargo` · `mvn` … | **信任Node/TS仓库的完整SDLC深度。 将非Node输出视为配置文件 + 元数据指导** （内核通过`toolchainNote`诚实地标记它）。 --- ## ✦ 质量，有保证 Sage Kernel坚持它对其他人强制执行的标准。证明是可复制的： ```bash npm test # 完整的单元测试套件 npm run release:check # 78个硬性网关，必须退出0 npm run mcp:smoke # 真实的MCP客户端握手 npm run security:scan # 机密扫描 npm run publish:ready # 开源发布准备网关 ``` - **140种MCP工具**，每种都有源提取的一致性测试。 - **78个发布网关**在每次更改时运行（lint，类型，合约，安全，覆盖率，应力，漂移，文档）。 - **执行基础的覆盖率** — “测试”意味着*执行*，而非导入可达。 - **篡改证据的证明账本** — 哈希链，HMAC签名，关闭验证。 - **对抗性测量的安全性** — 保留 + 新生成的语料库，而不是调优的1.0。 详情： **[docs/QUALITY_RATCHET.md](docs/QUALITY_RATCHET.md)** · **[docs/RELEASE_PROCESS.md](docs/RELEASE_PROCESS.md)** --- ## ✦ 每日命令 `sage`CLI是可选的 — 使用`npm link`启用它一次（或直接调用`node bin/sage.mjs <cmd>`）。`npm run`命令不需要链接。 ```bash npm link # 一次性：使`sage`命令可用 sage daily # 健康状况、工具、作业、批准、下一个动作 sage audit . # 仓库审计工作流 sage mcp config cursor --json # 生成客户端配置 npm run onboard -- <repo> # 任意项目的单屏SDLC报告（不需要链接） npm run engineer:measure # 具有证明支持的能力记分卡 npm run stress:verify -- --passes 5 # 稳定性 / 故障检测 ``` 完整参考： **[docs/USAGE.md](docs/USAGE.md)** --- ## ✦ 从您的AI客户端驱动它（斜杠命令链） 一旦MCP服务器连接到您的客户端（参见[开始使用](docs/GETTING_STARTED.md)），您描述一个结果，代理调用正确的`kernel.*`工具。 为了使常见的多步骤流程只需一个按键，请将现成的链复制到客户端的命令目录： ```bash cp examples/slash-commands/*.md ~/.claude/commands/ # Claude Code（用户范围） ``` 每个链都命名确切的sage-kernel工具（因此路由是确定性的）并与您的其他MCP服务器（文档，浏览器，GitHub）组合： | 命令 | 链 | 用途 | | --- | --- | --- | | `/sk-audit [path]` | 配置文件 → 完成 → 循环得分 → 审查 → 安全 → 顶部5个修复 | 评估任意仓库 | | `/sk-onboard <path>` | 单屏SDLC报告 | 项目的第一印象 | | `/sk-feature <what>` | 当前文档 → 实现 → 测试 → 审查/安全 → 差异 | 正确构建更改 | | `/sk-ship [title]` | 审查 → 验证 → 证明网关 → 打开一个带有证据的PR | 带有证据而非感觉的合并 | | `/sk-secure [path]` | SAST + 污点 + 供应链，按严重性排名 | 重点的安全检查 | | `/sk-proof` | 强制执行当前差异的证明网关 | 确认工作真正有证明 | 模板： **[examples/slash-commands/](examples/slash-commands/)**。 --- ## ✦ 文档地图 | 这里开始 | 参考 | 操作 | | --- | --- | --- | | [开始使用](docs/GETTING_STARTED.md) | [架构](docs/ARCHITECTURE.md) | [使用指南](docs/USAGE.md) | | [使用内核](docs/USING_SAGE_KERNEL.md) | [MCP工具](docs/mcp-tools.md) · [资源](docs/mcp-resources.md) · [提示](docs/mcp-prompts.md) | [持久性](docs/PERSISTENCE.md) | | [工程循环](docs/ENGINEERING_LOOP.md) | [运行时引擎](docs/RUNTIME_ENGINE.md) | [发布流程](docs/RELEASE_PROCESS.md) · [发布证明](docs/RELEASE_PROOF.md) | | [视觉指南](docs/VISUAL_GUIDE.md) | [源仓库策略](docs/source-repo-policy.md) | [质量梯度](docs/QUALITY_RATCHET.md) | 同时： [路线图](docs/ROADMAP.md) · [贡献](CONTRIBUTING.md) · [安全策略](SECURITY.md) · [行为准则](CODE_OF_CONDUCT.md) · [变更日志](CHANGELOG.md) --- ## ✦ 开发 ```bash npm install npm run catalog:validate npm run mcp:contracts # 从清单中重新生成工具合约 npm run release:check # 完整的网关套件 ``` 可选的Postgres路径： ```bash docker compose -f docker-compose.postgres.yml up -d postgres SAGE_RUN_POSTGRES_TESTS=1 DATABASE_URL=postgresql://sage:sage@127.0.0.1:55432/sage_kernel npm run postgres:integration ``` --- ## ✦ 状态与哲学 Sage Kernel **生产级别的本地MCP工程工作流**适用于JS/TS/Node项目，并且对其他项目提供有用的配置文件/元数据层。它默认是本地优先的；将公共网络暴露视为一个单独的强化项目。 它建立在一个不可妥协的原则上： **声明的内容，一切都经过验证**。没有假的绿色，没有脚手架，没有未获得分数的分数。 <div align="center"> **[开始使用 →](docs/GETTING_STARTED.md)** · 遵循 [MIT](LICENSE) 许可 </div>