Jidoka

代码库质量工程引擎
渐进式质询。领域适应度函数。交叉验证启发式。

给定一个从未见过的代码仓库，Jidoka 回答：**这个系统承诺了什么，它实际上能做什么，它证明了什么，以及哪些缺陷会在未来给你带来伤害？** 价值在于**各层之间的差距**——有意愿却无能力（空头产品）、有能力却无验证（未兑现的承诺）、以及有验证却无能力（无法证明任何有用内容的测试）。 Jidoka 是开放核心且 AI 增强的，但不是 AI 中心的。你控制决策引擎。每个结论都能追溯到前提。相同的输入，相同的结论。你的代码永远不会离开容器。 ## 目录 - [功能](#features) - [工作原理](#how-it-thinks) - [适应度函数](#fitness-functions) - [领域垂直方向](#domain-verticals) - [安装](#install) - [使用方法](#usage) - [语言和模块](#languages-and-cassettes) - [输出](#output) - [安全](#security) - [竞争格局](#competitive-landscape) - [社区模块](#community-cassettes) - [开发](#development) - [项目结构](#project-layout) - [许可证](#license) ## 功能 | 功能 | 描述 | |---|---| | **8层渐进式质询** | 从 T0 身份识别到 T7 处方——每层的发现为下一层的问题提供依据 | | **7维度评分** | 可观测性、可控性、可隔离性、可分解性、简单性、稳定性、自动化就绪度（A-F 等级）| | **46个适应度函数** | 7个垂直方向的确定性架构规则：基线、抵押贷款、保险、交易、资本市场、数据平台、对冲基金 | | **交叉验证富集度** | 独立适应度规则相互印证——组合置信度超过各部分之和 | | **31个领域本体** | 金融服务、抵押贷款、保险、交易、数据平台、Web API 的 YAML 驱动质量预期 | | **技术健康证书** | 业务可读的质量报告，包含风险分级、监管说明和修复处方 | | **可插拔模块** | 8种语言（C#、Python、TypeScript/JS、Java、Go、RPG、PHP、SQL）加上社区 YAML 扩展 | | **稳定的发现标识符** | 确定性 12 字符十六进制 ID，在 JSON、HTML、SARIF 和 CLI 输出中保持一致 | | **证据溯源** | 每个评分都可追溯到信号、发现和阈值 | | **分阶段 CI 门控** | 四种模式：建议、回归警告、阈值失败、阈值通过 | | **5个 GitHub Actions 模板** | 建议扫描、回归门控、阈值门控、PR 聚焦扫描、每日全量扫描 | | **MCP 服务器** | 7个 Claude Code 和 IDE 扩展工具——带模式快照的版本化契约 | | **气隙隔离执行** | Docker `network_mode: none`。无遥测。无源码持久化。| ## 工作原理 ``` graph LR T0[T0 Identity
What am I looking at?] --> T1[T1 Anatomy
How is it organized?] T1 --> T2[T2 Intent
What does it claim?] T2 --> T3[T3 Capability
What can it do?] T3 --> T4[T4 Verification
What does it prove?] T4 --> T5[T5 Gaps
What's missing?] T5 --> T6[T6 Risk
Where will it break?] T6 --> T7[T7 Prescription
What to do first?] style T0 fill:#1a1a2e,stroke:#4fc3f7,color:#e0f7fa style T1 fill:#1a1a2e,stroke:#4fc3f7,color:#e0f7fa style T2 fill:#1a1a2e,stroke:#4fc3f7,color:#e0f7fa style T3 fill:#1a1a2e,stroke:#4fc3f7,color:#e0f7fa style T4 fill:#1a1a2e,stroke:#4fc3f7,color:#e0f7fa style T5 fill:#1a1a2e,stroke:#81d4fa,color:#e0f7fa style T6 fill:#1a1a2e,stroke:#ffb74d,color:#e0f7fa style T7 fill:#1a1a2e,stroke:#81c784,color:#e0f7fa ``` 每层的发现为下一层的问题提供依据——这是一个有向无环质询图，而不是检查清单。 | 认知能力 | 实现方式 | 产出 | |---|---|---| | 感知 | tree-sitter AST 解析（8种语言）| 语言无关的结构 | | 结构推理 | NetworkX 图算法 | 依赖拓扑、循环、爆炸半径 | | 溯因推理 | 编码的启发式模式 | "这看起来像一个上帝类，因为..." | | 规范判断 | 预期本体（YAML，版本化）| "金融服务 API 应该具有..." | | 风险评估 | 差距 x 变更 x 爆炸半径 | 下一个生产事故发生的位置 | | 处方 | 确定性优先级排序 | 首先应该修复什么，以及为什么 | ## 可测试性的七个维度 每个维度都建立在制造质量传统的基础上： ``` graph TD subgraph "Six Sigma" OBS[Observability
MSA -- can you measure it?] SIM[Simplicity
Cpk -- process capability] end subgraph "Lean" ISO[Isolability
Single-Piece Flow] DEC[Decomposability
Small Batch Size] STA[Stability
SMED -- changeover time] end subgraph "TQM" CTR[Controllability
Process Control] AUT[Automation Readiness
Built-In Quality -- Jidoka] end style OBS fill:#1a1a2e,stroke:#4fc3f7,color:#e0f7fa style SIM fill:#1a1a2e,stroke:#4fc3f7,color:#e0f7fa style ISO fill:#1a1a2e,stroke:#29b6f6,color:#e0f7fa style DEC fill:#1a1a2e,stroke:#29b6f6,color:#e0f7fa style STA fill:#1a1a2e,stroke:#29b6f6,color:#e0f7fa style CTR fill:#1a1a2e,stroke:#26a69a,color:#e0f7fa style AUT fill:#1a1a2e,stroke:#26a69a,color:#e0f7fa ``` 可操作的评分，而非意见。每个维度都会产生一个等级（A-F）、使用的信号、理由和建议——所有这些都可追溯到特定的图实体和发现 ID。 ## 适应度函数 适应度函数是确定性的架构质量规则。每条规则扫描一个仓库并返回通过、失败或跳过，同时提供证据和修复指导。 **基线规则**（任何代码库）： | 规则 | 检查内容 | |---|---| | FF-01 | 源文件不超过 300 行 | | FF-02 | 每个测试都带有分类标记 | | FF-03 | 核心模块无循环导入 | | FF-04 | 测试与源文件比率 >= 0.5 | | FF-05 | 源文件中无硬编码密钥 | | FF-06 | 存在依赖注入模式 | | FF-07 | 无空的 catch/except 块 | | FF-08 | 服务类具有接口/协议 | | FF-10 | 业务逻辑中无直接使用 DateTime.Now | 领域特定规则强制执行垂直标准。请参阅[领域垂直方向](#domain-verticals)。 ### 交叉验证和富集度 适应度函数相互交叉验证。当两条独立规则印证同一质量维度时，组合置信度超过各部分之和。 **富集度**衡量交叉验证连接的密度。1.0 分意味着每条规则都参与至少一个交叉验证对。数据平台垂直方向在 8 条规则上实现了 1.0 富集度，包含 8 个域内对和 6 个跨域对。 ## 领域垂直方向 Jidoka 的本体系统用 YAML 编码领域特定的质量预期。每个垂直方向定义了在该领域中系统*应该*是什么样子——监管要求、架构模式和故障模式。 | 垂直方向 | 本体 | 适应度规则 | 关键标准 | |---|---|---|---| | **抵押贷款** | 发起、服务、资本市场、消费者网络 | FF-CV-01..09, FF-CM-01..03 | RESPA, TILA, MISMO 3.4, Reg AB II | | **家庭保险** | 财产险承保、理赔、评级 | FF-HI-01..08 | NAIC 模型法, SERFF, ISO HO-3/HO-5 | | **交易** | 零售经纪、做市 | FF-TR-01..05 | SEC Rule 606, FINRA 5310, FIX 协议 | | **数据平台** | 数据湖、云、可观测性、流式处理、搜索、分析、机器学习 | FF-DP-01..08 | OWASP A03, SR 11-7 模型风险 | | **对冲基金** | 量化、多策略、风险分析、监管报告、交易运营 | FF-HF-01..06 | SEC Form PF, 多德-弗兰克, 巴塞尔 III/IV | | **金融服务** | 基线安全、审计、加密 | （基线规则）| SOC 2, GLBA, PCI-DSS | ## 安装 ### Docker（推荐） ``` docker pull ghcr.io/heymumford/jidoka:latest docker run --rm --network=none \ -v /path/to/your/repo:/workspace:ro \ -v $(pwd)/output:/output \ ghcr.io/heymumford/jidoka:latest \ interrogate /workspace --output /output ``` 你的代码留在容器中。`network_mode: none`——永远没有出站连接。 ### 从源码构建 ``` git clone https://github.com/heymumford/jidoka.git cd jidoka && uv sync jidoka interrogate /path/to/repo ``` ### MCP 服务器 将 Jidoka 连接到 Claude Code 或任何 MCP 客户端： ``` { "mcpServers": { "jidoka": { "command": "uv", "args": ["run", "--project", "/path/to/jidoka", "jidoka-mcp"] } } } ``` | 工具 | 功能 | |---|---| | `interrogate` | 运行 T0-T7 渐进式质询 | | `score` | 7维度可测试性记分卡 | | `gate` | CI 质量门控（根据阈值通过/失败）| | `list_cassettes` | 可用的语言模块和规则数量 | | `explain_finding` | 追溯发现到源实体和图 | | `query_graph` | 对知识图谱进行结构化查询 | | `suggest_cassette` | 为检测到的语言推荐模块 | ## 使用方法 ``` # 完整询问 (T0-T7) jidoka interrogate /path/to/repo # 在特定层级停止 jidoka interrogate /path/to/repo --tier 5 # JSON、HTML 和 SARIF 输出 jidoka interrogate /path/to/repo --json --sarif # 七维评分 jidoka analyze /path/to/repo # CI 质量门禁 jidoka gate --scorecard ./output/scorecard.json --threshold 0.6 # 解释发现结果 jidoka explain t5.unverified --repo /path/to/repo # 比较记分卡 jidoka diff before.json after.json --fail-on-regression # Cassette 工具 jidoka cassette list jidoka cassette scaffold rust --output-dir ./my-cassettes jidoka cassette validate ./my-cassettes # 适应度函数 jidoka fitness evaluate /path/to/repo # Run core rules jidoka fitness evaluate /path/to/repo --domain hedge-fund # Add domain rules jidoka fitness list # Show all rules jidoka fitness fecundity /path/to/repo # Cross-validation ``` ### CI 集成 `.github/workflows/examples/` 中有可直接使用的工作流模板： | 模板 | 模式 | CI 失败？| |---|---|---| | `jidoka-advisory.yml` | 信息扫描 | 从不 | | `jidoka-regression-gate.yml` | 与基线比较 | 回归时 | | `jidoka-threshold-gate.yml` | 强制最低分数 | 低于阈值时 | | `jidoka-changed-files.yml` | PR 范围分析 | 从不（与每日扫描配合）| | `jidoka-nightly.yml` | 计划全量扫描 | 从不（生成基线）| ## 语言和模块 **内置支持：** C#、Python、TypeScript/JavaScript、Java、Go、RPG（ILE）、PHP、SQL——通过 tree-sitter AST 解析。 模块是可插拔的知识包：**模式**（编纂的反模式）、**预期**（领域标准）、**陷阱**（经验教训）。社区模块通过 YAML 扩展内置模块——它们是合并而非替换。 ``` # .jidoka/cassettes/kotlin.yml language: kotlin display_name: Kotlin file_extensions: [".kt", ".kts"] test_file_patterns: ["*Test.kt"] patterns: - id: kotlin-mutable-data name: Mutable data class observes: var in data class infers: Reduced immutability risk: medium recommendation: Use val gotchas: - id: kotlin-coroutine-leak name: Coroutine scope leak severity: critical ``` ## 输出 - **`interrogation.json`** —— 带稳定发现 ID 的逐层发现 - **`interrogation.sarif`** —— 用于 GitHub 代码扫描的 SARIF 2.1.0 - **`interrogation.html`** —— 带每层卡片和处方的报告 - **`scorecard.json`** —— 带证据溯源的 7 维度记分卡 - **`certificate.html`** —— 带风险分级和监管说明的技术健康证书 每个发现都可追溯到源实体。每个评分都可追溯到图查询和信号贡献。 ## 安全 | 边界 | 机制 | |---|---| | 网络隔离 | Docker `network_mode: none` | | 路径限制 | `safe_resolve()` —— 所有路径都在仓库根目录内 | | 文件大小限制 | 每个文件 5 MB，每次运行总计 200 MB | | AST 深度限制 | 递归上限 500 | | XSS 防护 | Jinja2 `autoescape=True` 无条件启用 | | 无源码持久化 | `persist_source=False` 结构不变量 | | 输出编辑 | 递归编辑受限配置文件 | 四种安全配置文件：`standard`、`api`、`metadata_only`、`strict_api`。请参阅 [SECURITY.md](

标签：DevOps工具, Homebrew安装, NIDS, 代码健康度检查, 代码审计工具, 代码度量, 代码覆盖率, 代码质量评估, 可测试性分析, 多语言支持, 威胁情报, 安全测试框架, 容器化, 开发者工具, 开源框架, 技术债务评估, 持续集成, 特权检测, 确定性分析, 编程工具, 自动化代码评估, 请求拦截, 软件质量工程, 远程代码执行, 逆向工具, 错误基检测, 静态代码分析