# cmb-sq **Repository Path**: pff_study/cmb-sq ## Basic Information - **Project Name**: cmb-sq - **Description**: cbm-sq - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-08 - **Last Updated**: 2026-09-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # cbm-sq — 基于知识图谱的代码质量规则引擎 + 中心化治理平台 > 在 **codebase-memory-mcp**（C 二进制，零源码修改）之上，用 Go 构建的四层 DSL 规则引擎 + pre-commit 门禁 + MCP server + 主控同步平台。v0.5.0（版本以 `internal/version` 常量单轨为准；v0.2.0 = C4 WebUI，v0.3.0 = C6 MCP 透传 22 工具单入口，v0.4.0 = C5 规则禁用三件套（--exclude-rules/enabled:false/--severity-min）+ C8 质量修复（范围失控/门禁面/文件级豁免）——契约 B v1.4；v0.5.0 = C9 规则优化（测试类豁免/魔法数字方法体内限定）+ suppression CLI——契约 B v1.4 内新增能力；v0.10.2 = V17 审核修复闭环（F-1~F-7+W-1 全量——门禁四源/stale 透传/DSL naming 数组与 target_exclude/夹具排除）+ 在线三端/WebUI 验收加固；v0.11.0 = V14 提交规范专项（八阶段生命周期/hook --push/统一输出分页标准/baseline 全链）；v0.12.0 = V15 规则生成质量面（误报率真实统计/dry_run 样例项目参数）；v0.13.0 = baseline 图谱指纹补全 + 规则级误报率输出（F-4 闭环）；v0.14.0 = graph 规则 Go 标签适配（Method∪Function——顶层函数入射程）；v0.15.0 = func_count_limit 文件函数数规则 + 规则级误报率输出）。）。**完整使用说明见 [`docs/USAGE.md`](docs/USAGE.md)**。 **差异化定位**（PLAN §1.5.3）：基于本地知识图谱的、规则引擎 + pre-commit 门禁 + 中心化 metrics/审计一体化服务——理解侧（search_graph/query_graph）由 cbm 原生解决，cbm-sq 专注**判断侧**（主动发现 + 门禁 + 治理）。 --- ## 架构 ![cbm-sq 架构图](docs/diagrams/cbm-sq-architecture.png) ``` ┌─ 节点 cbm-sq（单二进制——纯本地：扫描/门禁/规则）──────────────┐ │ CLI: scan / check / validate-commit / validate-push / hook / │ │ sq-import / setup（一键接入）/ sync-daemon（run/proc——常驻同步代理）│ │ MCP server: 24 工具 = 10 自有 + 14 cbm 透传（stdio，契约 B v1.8——单入口）│ │ ┌─ 四层规则引擎 ──────────────────────────────────────────────┐ │ │ │ graph（图谱 Cypher）│ ast（tree-sitter）│ semantic（符号表）│ │ │ │ dataflow（semgrep taint） │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ 扫描缓存（SQLite ~/.cache/cbm-sq/）+ 同步面 sync.db（outbox/ │ │ 豁免/sync_meta——~/.cbm-sq/） │ │ cbm_client（CLI 子进程 + JSON——零源码修改硬约束）→ codebase-memory-mcp │ │ cbm_mcp_client（MCP 会话透传——C6 单入口）→ codebase-memory-mcp │ └───────────────────────────────────────────────────────────────────┘ ┌─ sync-daemon（cbm-sq 子命令——常驻）──────────────────────────────┐ │ 自动：上报（outbox 监测——409 跳过/分批/429 退避）心跳/规则包/豁免│ │ 进程自管理（start/stop/status/restart/logs——无 systemd） │ └───────────────────────────────────────────────────────────────────┘ ┌─ 主控 cbm-sq-central（单二进制）──────────────────────────────────┐ │ HTTP REST（契约 A v1.2）：注册 / 心跳 / 规则包（ED25519 签名）/ │ │ 上报（验签+幂等）/ 豁免下发 / sync-failures / offline 判定 │ │ SQLite（~/.cbm-sq-central/：nodes/tokens/规则包/审计/上报） │ └───────────────────────────────────────────────────────────────────┘ ``` **三端全链路**（编码智能体 → cbm-sq → sync-daemon → cbm-sq-central）：扫描（CLI/MCP）→ 无条件本地入队（sync.db——身份无关）→ **sync-daemon 自动补报**（outbox 监测——实时）→ 主控验签/幂等入库/审计沉淀；心跳自动拉规则包/豁免（版本不一致即触发）。 --- ## 核心流程 ### 扫描流程 ![扫描流程](docs/diagrams/flow-scan.png) 索引（graph 层前置）→ 四层规则引擎执行 → 结果缓存（18x 加速）→ **无条件本地入队**（sync.db——身份无关）→ 报告输出。semgrep 缺失时 dataflow 规则自动 skipped（fail-closed——不误报）。 ### 在线接入与上报闭环 ![在线接入与上报闭环](docs/diagrams/flow-online.png) `cbm-sq setup` 一条命令完成接入（注册 + daemon 启动 + 通用 MCP 配置输出）→ 扫描自动入队 → **sync-daemon 自动补报**（outbox 监测）→ 主控验签/幂等/审计/metrics 沉淀 → 心跳自动拉取规则包/豁免。409 跳过丢弃、429 Retry-After 退避、>5000 issues 分批（part）全部自动。 ### 门禁流程 ![门禁流程](docs/diagrams/flow-gate.png) `validate-commit`：git 变更闭包 → 草稿区事务式扫描 → 规则面门禁判定 → 通过（exit 0）/ 阻断（exit 3 + fix_hints）；输出恒带 `summary` 摘要档（total + by_severity 5 键 + by_rule 分布——与 scan 同聚合形态，agent 先看聚合再决定深挖）；hook 安装后自动拦截。 **规则面（V13-M2 + V13-M6 + V13.1 扩展）**：`--rule-sets/--rules/--exclude-rules` 三参数（互斥；显式空串用法错误）——缺省 = **安全基线（security 集）+ default 规则集（`~/.cbm-sq/rulesets/default.json`——首次 check/扫描自动创建用户 16 条门禁需求集（hardcoded 四连 + 注释五条 + 行数/参数/复杂度三条 + magic 系列三条——V13.1 用户裁决——`manage_ruleset` 可改）+ 项目 rulesets 自动同源**（非全量——非安全类规则不再缺省参与）；显式指定 = 展开结果 ∪ 安全基线**强制合并**（用户配集不能漏掉安全；exclude 不可剔除基线；**default 仅缺省含——显式指定不并入**）。**判定 = 集内全拦**（规则面内任意 severity 命中即阻断——magic 系列入 default 后变更闭包魔法字面量即拦——配合 `report_issue` 豁免管理缓解）；`severity_min` 语义从判定阈值降为**输出过滤**（报告只列 ≥ min——blocked 判定独立）。 ### 豁免闭环 ![豁免闭环](docs/diagrams/flow-suppression.png) 本地 `report_issue` 立即生效；在线模式：申请（User API Key）→ QA 审批 → daemon 自动 pull-suppressions → 全局过滤。 ### 离线韧性 ![离线韧性](docs/diagrams/flow-offline.png) 断网/无主控 → 扫描照常 → outbox 落盘累积（不丢）→ 恢复后 daemon 自动补报（scan_id 幂等——duplicate 不重复入库）。 --- ## 安装 ```bash # 方式一：离线发布包 bundle（推荐——cbm-sq 双二进制 + cbm 基座 + semgrep 全离线一键装） ./scripts/build-bundle.sh [--cbm-src <静态版目录或官方tar.gz>] # 构建 bundle（make setup） # → dist/bundle/cbm-sq--bundle/（bin/ + cbm/ + wheels/ + SHA256SUMS） # 目标机（无网）：tar 解压 → ./install.sh（SHA256 校验 → 双二进制 → cbm 基座 → semgrep venv → 验证） # 详细离线/在线使用：docs/USAGE-OFFLINE.md / docs/USAGE-ONLINE.md # bundle 缓存（.bundle-cache/——一次下载永久复用，重建 bundle 零下载）： # cbm-linux-amd64.tar.gz（linux 基座——官方 portable 静态版，GLIBCXX 无关）/ cbm-windows-amd64.zip（win 基座）/ # wheels-linux/ + wheels-win/（semgrep 双平台 wheels） # 缓存缺失才下载并自动入库；禁止删除（git-ignored 不入库——AGENTS §3.5 纪律） # 方式二：发布产物（双二进制——AGENTS §3.5） make dist # dist/ 双二进制（linux-amd64 基线）+ SHA256SUMS make verify # 校验 + 版本自检 make install # install.sh 安装到 /usr/local/bin # 平台矩阵：linux-amd64 基线；windows-amd64（make cross——musl.cc mingw 交叉工具链）； # Windows 离线包：make bundle-windows（zip 便携——exe + cbm.exe + semgrep win wheels——README-WINDOWS.md）； # arm64 需 aarch64 工具链（make cross 诚实 SKIP）；darwin 需 CI # 方式三：源码构建（开发） go build -o cbm-sq ./cmd/cbm-sq go build -o cbm-sq-central ./cmd/cbm-sq-central # dataflow 层依赖 semgrep（Python——bundle 已含离线 wheels；手动：清华镜像） UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv tool install semgrep ``` --- ## 快速开始（local 模式——离线完整可用） ```bash # 1. 索引项目（graph 层；ast 层可跳过） CBM_ALLOWED_ROOT=/path/to/codebase cli index_repository --repo-path # 2. 扫描（四层规则全跑；--quick 仅 graph <1s；默认增量——未改文件 mtime 快路径 # 命中零重扫（meta.cached_hits/cache_misses 文件级命中统计）；--force 全量重扫； # --cache-strict 纯内容寻址（rsync/tar 归档）；CBM_SQ_CACHE_STRICT=1 等价） # 注意：扫描面 = 当前目录——请 cd 到项目根运行（父目录运行会扫描整个工作区）； # --project 仅绑定 cbm 图谱/缓存（不决定扫描面） CBM_BIN= cbm-sq scan --project <项目名> # 3. MCP server（编码智能体接入——24 工具单入口：10 自有 + 14 cbm 透传；opencode 配置见 USAGE §3） cbm-sq mcp serve # 4. 提交门禁（草稿区事务式扫描 + pre-commit hook；默认增量——变更文件必扫 + # closure 未变文件缓存合并；--force 全量重扫；--rule-sets/--rules/--exclude-rules # 规则面三参数——缺省 = 安全基线 + 项目 rulesets；判定 = 集内全拦） cbm-sq validate-commit --project /path/to/repo # 退出码 0=通过 / 3=阻止 cbm-sq validate-commit --project /path/to/repo --rule-sets security,my-team # 显式集（安全基线强制合并） cbm-sq hook install # 4.1 推送门禁（V13-M2b：pre-push——graph 能力层兜底——分层门禁补位： # pre-commit 拦 ast/semantic/dataflow + graph 带 metric；pre-push 拦 graph 无 # metric（复杂度/传递类——Cypher 查图面）。变更集 = git log / # ..HEAD 未推送 commit 涉及文件（无远端 → 全部未推送 commit——退化注记）→ # IndexRepository 增量索引（commit 后合法）→ graph 规则执行 + 变更闭包过滤 + # 集内全拦；索引/扫描失败 → fail-closed（blocked——无法判定即不放行，R19）。 # MCP 不新增工具（CLI/hook 场景——YAGNI）） cbm-sq validate-push --project /path/to/repo # 退出码 0=通过 / 3=阻止（hook 判定） cbm-sq validate-push --project /path/to/repo --remote origin --base-ref v1.0 # 显式远端/基线 # hook 接线（pre-push 示例：.git/hooks/pre-push——失败阻断 push） cbm-sq validate-push --project "$(git rev-parse --show-toplevel)" || exit 1 # 5. SonarQube 规则导入流水线 cbm-sq sq-import convert --input S2077.json # SQ 元数据 → DSL 草案 cbm-sq sq-import validate --input draft.jsonc --project # dry_run 真实命中 cbm-sq sq-import commit --input draft.jsonc # 入库（~/.cbm-sq/rules/） ``` --- ## 在线主控（节点 + 管理员）快速上手 ```bash # 主控（管理员） cbm-sq-central serve --addr 127.0.0.1:8787 # 生产经 TLS 终止代理 cbm-sq-central register-code # 注册码（一次性限时，stdout 仅显示一次） cbm-sq-central rulepack publish --rules-dir rules --version 1.0.0 # 规则包（ED25519 签名） # 节点（一条命令一键接入——注册 + daemon 常驻 + 通用 MCP 配置输出） cbm-sq setup --code REG-XXXX-YYYY --central http://:8787 --user user_42 \ --code-root /path/to/codebase [--cbm-bin ] cbm-sq sync-daemon proc status # daemon 运维（start/stop/status/restart/logs——无 systemd） ``` - **自动同步**：daemon 常驻——上报（outbox 监测实时补报）/心跳/规则包拉取（版本不一致自动）/豁免增量——全部自动，无需手动命令 - **离线韧性**：断网照常扫描/门禁（结果落 sync.db outbox）→ 恢复后 daemon 自动补报（scan_id 幂等——补报不丢） - **版本语义**：主控新包发布后旧版本上报 → 409（daemon 跳过该报告 + 提示重扫）；上报限流 60 次/分/node（429 + Retry-After 退避） - **安全**：Node Token 哈希存储；规则包 ED25519 签名（公钥经注册响应分发）；上报签名验签 + 白名单 + 全链路审计 - **完整手册**：场景 A 离线单机 / 场景 B 在线节点 / 场景 C 主控运营 —— 见 `docs/USAGE.md` §4-§6 ## Web UI（主控运营控制台，v0.2.0 起） 主控自带 Web 控制台（纯 HTML/JS/CSS 无构建、零外部依赖、离线可用）： ```bash cbm-sq-central serve --addr 0.0.0.0:8787 # 浏览器打开 http://:8787/ui/ → 输入 User API Key 登录（user-key generate 签发） ``` - **10 个视图**：概览（节点状态卡/最近报告/severity 环图）/ 节点（列表/详情/吊销）/ 报告（过滤+分页+详情抽屉含 issues 与 blame）/ Issue 浏览 / 指标（五维度聚合 + SVG 柱状图）/ 豁免（申请/审批流/已批准）/ 规则包（历史/详情/JSONC 发布）/ 审计（qa+）/ 管理（注册码/用户 key/团队，admin）/ 设置（API 地址切换） - **角色菜单**：user 本人数据域（服务端强制）无管理入口；qa 增审批/审计；admin 全量（发布/注册码/用户 key/团队） - **跨域双通道**：同源访问 `/ui/` 无需配置；独立静态托管或本地打开 HTML 跨域访问 API 时，主控以 `--cors-origins` 放行（逗号分隔；`*` 允许任意含 file:// 场景） - **机密一次性**：User API Key / 注册码明文仅生成时显示一次；列表页绝不含密钥明文 - **完整操作说明（视图指南/角色矩阵/典型流程/故障排查）**：见 [`docs/WEBUI.md`](docs/WEBUI.md) --- ## CLI 命令 | 命令 | 说明 | |---|---| | `scan` | 规则扫描（--project 必填（**仅预检**——target not found 兜底）；**扫描面 = 当前工作目录（src=cwd）——须 cd 到目标仓库再扫**（MCP scan_rules 为项目名反查——C5-T5，两者语义不同）；--rules 白名单子集；--exclude-rules 黑名单（与 --rules 互斥）；--quick 仅 graph；--severity-min 输出过滤，默认 info；--exclude-tests 测试面排除（src/test/**、*Test.java/*Tests.java、Go *_test.go 与夹具目录 tests/fixtures/**、testdata/**、tests/e2e/**——V17 批次 3 扩面）；--detail 输出粒度（summary_only/issues/issues_full，默认 issues）；--top-n 输出截断（默认 20，0=不限——V17 批次 3 F-6）；规则文件 `"enabled": false` 四源禁用） | | `check` | cbm 后端连通 + 已索引项目探测 | | `mcp serve` | MCP server（stdio；24 工具 = 10 自有 + 14 cbm 透传单入口；--no-proxy-cbm 关闭透传） | | `validate-commit` | 提交门禁（git 变更闭包 + 规则面三参数（--rule-sets/--rules/--exclude-rules——缺省安全基线 + 项目 rulesets）+ 集内全拦判定（severity_min 输出过滤）；退出码 0=通过/3=阻止） | | `validate-push` | 推送门禁（V13-M2b——pre-push graph 能力层兜底：变更集 origin..HEAD 未推送 commit + 增量索引 + graph 无 metric 规则执行 + 集内全拦；索引/扫描失败 fail-closed blocked；退出码 0=通过/3=阻止） | | `hook install` | 安装 pre-commit hook（门禁失败阻止提交） | | `sq-import` | SonarQube 导入（convert/validate/commit 三子命令） | | `setup` | 一键接入向导（注册 → daemon 配置落盘/启动 → 通用 MCP 配置输出；--offline 免注册码） | | `sync-daemon run` | 常驻同步代理主循环（自动上报/心跳/拉包/豁免——被 proc start 后台调用） | | `sync-daemon proc` | daemon 进程自管理（start/stop/status/restart/logs——无 systemd 依赖） | | `suppression list` | 列出本地豁免（JSON 数组；`--rule ` 过滤） | | `suppression rm` | 删除本地豁免（`--dedupe-key ` / `--rule ` / `--file ` 三选一互斥；规则优化后清理冗余豁免） | **MCP 24 工具**（契约 B v1.8——单入口）：自有 10 工具 `scan_rules`（异步 job + await）/ `get_scan_report`（wait_ms 阻塞）/ `validate_commit`（永不 isError）/ `add_rule` / `list_rules` / `add_rules_batch`（dry_run 验证）/ `ensure_indexed` / `report_issue`（豁免闭环）/ `manage_ruleset` / `list_rulesets`（V13-M1 规则集管理——create/update/delete/list + 全量查询）**+ 透传 cbm 14 图谱工具**（search_graph/query_graph/get_code_snippet/get_architecture/trace_path/list_projects/index_repository/index_status/delete_project/manage_adr/detect_changes/get_graph_schema/ingest_traces/search_code——name/desc/inputSchema/content 零改写，与直连 cbm 零差异）。返回一律严格 JSON minified。接入配置见 `docs/USAGE.md` §3（只配 cbm-sq 一个 MCP 即可）。 --- ## 规则体系 - **114 条内置规则**（装载口径——文件 115 含 1 条禁用 missing_type_annotation；Java + Go 5 条 go_*），四层分布：graph 11 / ast 66（结构 57 + comments 9）/ semantic 4（另 1 条禁用）/ dataflow 33——**V16-A +6 ast + V16-B2a/B2b +14（dataflow 12 taint + ast 2——注入/路径/上传/模板 SSTI/响应头拆分/文件披露/LDAP 认证/JWT 签名面）**——**V18 +1 ast（jdk8_api_limit——JDK 9+ API 禁用——best_practice 首条）**——**完整清单/分类/适用说明/示例见 [`docs/RULES.md`](docs/RULES.md)** - 规则文件 JSONC（`rules//.jsonc`——rationale 必填）；**四源装载**（内置 < 中央 `~/.cbm-sq/rules-central/` < 项目 `.cbm-sq/rules/` < 个人 `~/.cbm-sq/rules/`） - **SQ 转换器**：SonarQube 官方 API 元数据（fetch-sq-rules.sh）→ DSL 草案（severity 五对五/layer 判定/sqKey 溯源）→ 智能体补全 pattern → dry_run 验证（样例项目真实命中）→ 入库 - **豁免闭环**：本地 `report_issue` suppress/false_positive 立即生效；在线模式 sync-daemon 自动 `pull-suppressions` 合并全局 approved（过期条目本地失效） --- ## API 面 - **契约 A（主控 HTTP REST v1.5）**：节点面 6 活跃端点（register/heartbeat/rule-packs/reports/suppressions/sync-failures——v1.2 起）+ 审批流（申请/列表/审批——v1.5 落地）+ 管理/查询面（v1.5 落地：节点列表/报告/issue/豁免全量/规则包/注册码/用户 key/团队/metrics 全局/me——WebUI 数据源） - **契约 B（节点 MCP）**：24 工具 = 10 自有 + 14 cbm 透传（stdio，v1.8） - **管理面**：WebUI（10 视图）+ CLI 并存（注册码/用户 key/团队/规则包发布 CLI 保留） - 速查表与错误码语义：`docs/USAGE.md` §7；权威源：`docs/contracts/` --- ## 开发与贡献 - **强制纪律**：`AGENTS.md`（依赖白名单/分层单向/TDD 红绿重构/五环节流程/21 项评审必查/里程碑沉淀四件套） - **契约**：`docs/contracts/`（契约 A v1.2 主控↔节点 / 契约 B v1.8 MCP↔LLM（24 工具）——semver 演进冻结机制） - **验收与复盘**：`docs/testing/`（m1-m6/m55/c1/c2/three-tier-flow-acceptance.md——命令原文可复现）+ `docs/superpowers/retrospective-*.md` - **知识库**：`docs/cbm-knowledge.md`（tree-sitter 形态/semgrep 行为/cbm 图谱——上游实证结论） - **里程碑计划**：`docs/superpowers/plans/`（M1-M6 + M5.5 + C1-C2 + 三端流程） - **跨项目教训**：`llm-tools/docs/llm-tools-dev-GROWTH.md`（33 条 G 条目） - **验证**：`gofmt -l . && go vet ./... && go test ./... && go build ./...` 全绿；验收锚点式 e2e --- ## 文档导航 ``` docs/ ├─ USAGE.md 使用说明（安装/智能体接入/三场景手册/API 参考/配置/FAQ）← 从这里开始 ├─ WEBUI.md WebUI 运营控制台使用说明（10 视图/角色矩阵/典型流程/故障排查） ├─ USAGE-OFFLINE.md 离线模式详细使用（bundle 安装/智能体配置/扫描门禁/规则/豁免） ├─ USAGE-ONLINE.md 在线模式详细使用（主控部署/节点接入/智能体/审批/审计/metrics/韧性） ├─ RULES.md 规则清单（114 条——分类/适用说明/示例/SQ 溯源） ├─ contracts/ 契约 A（central-node.md v1.5）+ 契约 B（mcp-llm.md v1.8）+ 总览与演进策略 ├─ testing/ 验收记录（m1-m6/m55/c1/c2/c3m/c3g/c4/three-tier-flow/rules-expand/m7）+ test-plan.md ├─ superpowers/ 复盘（retrospective-*.md）+ 里程碑计划（plans/ + c*-tasks/ + rules-expand/） └─ cbm-knowledge.md 上游实证结论（tree-sitter/semgrep/cbm 图谱形态） ```