CodeRef-AI — 编程 AI 的治理外脑，非编程人员的技术助理

Version 5.13.11 | Python 3.10+ | MCP Protocol | PolyForm Noncommercial 1.0.0

给编程 AI 一双确定性的眼睛，给非编程人员一张看得懂的工程体检单。

它是什么

CodeRef-AI 通过 MCP 协议暴露 50 个工具，同时服务两类人：

• 编程 AI 的治理外脑：让 AI 不再逐文件读代码，而是像查数据库一样查询项目的结构、调用链与风险；编程 AI（或 CodeRabbit）给出论断时，还能用静态图谱做确定性核验，再决定采不采信。

• 非编程人员的技术助理：把代码变成通俗的健康仪表盘、Wiki 与流程确证。你只需定义「入口 A 应该依次经过步骤 B→C→D」，coderef_flow_verify 就会在调用链里给出确证 / 在管线 / 存疑 / 缺失四种状态——不用读代码，也能确认项目有没有按你的设想运转。

多数 AI 审查工具把结论建立在「大模型读代码」上，而模型会幻觉。CodeRef 反过来：审计、图谱、架构诊断、流程验证、变更守护、OWASP、论断核验等核心能力全部是纯静态分析，结果确定、可复现——同一个项目每次跑出同样结论。LLM 只用于 Wiki、业务报告、创新排查等「要人话」的场景，未配置 API Key 时会明确硬阻断并提示配置，绝不降级编造。

Related MCP server: ws-mcp

三条编排主线：50 个工具不是散件，而是一条主链

50 个工具虽多，但 CodeRef 把它们整理成三条互补的编排主线（Skill），编程 AI 只需知道自己该在哪条链上；L1/L2/L3 之间用编排 gate 强制转场（命中条件才转，简单任务不被反复切链拖累），并由 coderef-mcp 的「顶层入口判定」在动身前先选对链：

L1  coderef-probe      · 小阶段 · 变更驱动的轻量探查与防护（类 CodeRabbit）
L2  coderef-governance · 大阶段 · 周期驱动的存量工程系统性规整
L3  coderef-asset      · 资产层 · 把治理/开发成果沉淀成可复用设计

• L1 探查链：提交/CI 前，增量、分钟级地快速探查——change_guard 拦截「把旧代码改坏」、verify_findings 确定性核验 LLM/CodeRabbit 论断防自查幻觉、误报进白名单收敛、小问题即时闭环；存量结构问题升级 L2。

• L2 治理主链：把被反复修改搞乱的存量工程捋回正轨——先辨清真身/孪生/孤本，再沿 map → target → refactor → verify → health 五阶段规整，用 9 类确定性差距生成任务卡，靠四维对齐度确认真正回正轨，最后用定期体检维持。

• L3 资产链：把值得复用的设计提炼成资产，防止高价值设计随项目迁移流失——沉淀有门槛（≥2 处采用 + 证据防污染）、命名先归一、复刻不自动改源码。

跨链转场由编排 gate 强制兜底，不靠调用方自觉：L2 ③ 改码前 → gate G1 转 L1 做变更探查/防护；L2 ③ 收尾/⑤ 体检/L2 软入口档摸底发现可复用设计 → gate G2 转 L3 评估沉淀；L1 发现存量结构问题 → gate G3 回 L2 立项，L3 复刻落地 → gate G3 回 L1 验证。真·屎山项目可先进 **L2 软入口档「先架构诊断」**只摸底（架构梳理 + 治理价值决策门，不动生产码），价值成立再升级正式主链，价值不足则停在摸底不硬上全链。详见仓库 skills/ 目录下的 4 个 Skill（含 coderef-mcp 的「意图 → 工具」速查表与顶层入口判定）。

为什么可信：关键主张都有量化实证

CodeRef 不靠宣称，靠可复现的硬指标（完整方法见后文「可靠性如何验证」）：

快速开始

如果你是非编程人员：把这部分说明交给你的编程 AI，它会帮你完成安装、配置和第一轮分析。你真正要做的，是最后打开它生成的健康仪表盘和 Wiki，看懂自己的项目。如果你是自己动手：照下面四步走。

1. 安装

只依赖纯 Python 包，不触发 C 源码编译，Python 3.10-3.14 免编译直接装好。

git clone https://github.com/keaizuizui/CodeRef-AI.git
cd CodeRef-AI
pip install -r requirements.txt

2. 配置 LLM（可选）

审计、图谱、架构诊断、流程验证、变更守护、OWASP 不需要 LLM，纯静态即可运行。仅 Wiki、业务报告、代码审查、Prompt 资产、创新识别需要 LLM；未配置 API Key 时这类「人话报告」被硬阻断并提示配置，不产出降级/占位内容。

Windows： 运行 setup.bat。

Linux / macOS：

export CODEREF_API_KEY="your-api-key"
export CODEREF_PROVIDER="deepseek"        # deepseek / openai / ollama
export CODEREF_BASE_URL="https://api.deepseek.com"
export CODEREF_MODEL="deepseek-v4-flash"  # 官方推荐: deepseek-v4-flash / deepseek-v4-pro

本地 Ollama（免费，无需 API Key）：

export CODEREF_PROVIDER="ollama"
export CODEREF_BASE_URL="http://localhost:11434/v1"
export CODEREF_MODEL="qwen2.5:7b"
export CODEREF_API_KEY="ollama"

3. 启动 MCP Server

python -m core.mcp_server

4. 配置 MCP 客户端

在 Trae / Claude Desktop 等 MCP 客户端中添加（详细指南见 MCP_SETUP.md）：

{
  "mcpServers": {
    "coderef-ai": {
      "command": "python",
      "args": ["-m", "core.mcp_server"],
      "cwd": "/path/to/coderef-ai"
    }
  }
}

本项目由编程 AI 辅助研发，作为 AI 治理方向的实践样本。建议拿到代码后，用 CodeRef 自己审计一遍，让报告带你理解每处实现。

第一轮 · 完整体检（3 分钟看懂你的项目）

# 1. 全量审计（后台，自动构建知识图谱），用任务状态轮询取结果
coderef_audit(project_path="/path/to/project", background=True)
coderef_task_status(task_id="...")

# 2. 生成项目 Wiki（未配 Key 时被硬阻断并提示配置）
coderef_docs(project_path="/path/to/project", background=True)

# 3. 看人话健康仪表盘（无需读代码）
coderef_interpret(project_path="/path/to/project", action="dashboard")

后续 · 按需深入

# 提交前防止 AI 把代码改坏（L1）
coderef_change_guard(project_path=..., action="guard", diff="<git diff 文本>")
coderef_change_report(project_path=..., diff="<git diff 文本>")

# 验证流程是否按预期走（L1 核验）
coderef_flow_verify(project_path=..., entry="pipeline_runner.audit", steps=["A","B","C"])

# 沿治理主链治理存量（L2）：捋管线 → 定目标 → 差距 → 任务卡 → 对齐验证
coderef_architecture(project_path=...)
coderef_target_arch_set(project_path=..., target_arch={...})
coderef_arch_gap(project_path=...)
coderef_refactor_plan(project_path=...)
coderef_arch_verify(project_path=...)

# 定期体检维持（L2 health）
coderef_gov_start(project_path=...) → coderef_gov_transition(project_path=..., issue_id=..., to="Fixing") → coderef_gov_close(project_path=...)
coderef_gov_report(project_path=...)   # 单期 + 跨期趋势 / Web 看板

# 沉淀 & 复刻好设计（L3）
coderef_innovation(project_path=...)    # 识别创新设计 + 传播缺口
coderef_replicate(project_path=..., canonical="...")   # 检测目标项目采用缺口（只报告）

# 查询知识图谱，替代 grep（省 10-100 倍 token）
coderef_query(project_path=..., query_type="callers", func_name="login")
coderef_query(project_path=..., query_type="impact", file_path="utils.py")

审计管线

11 个检测器

三级自动降噪：AI 白名单精准抑制已知误报 → 规则匹配过滤 MD5 哈希、配置 URL 等常见噪声 → 邻行去重 + 爆发式合并同类项（>8 条同类别 → 1 条统计）。实测 873 → 79 条（约 91% 降幅）。

交叉验证反幻觉：多工具独立分析同一项目，相互验证，输出 HIGH / MEDIUM / LOW 置信度分级——单一工具可能误判，但多工具互验后置信度显著提升。

知识图谱

运行 audit / architecture / docs / memory_sync 后自动构建 SQLite 知识图谱，持久化到 cache/kg/，一次构建跨会话复用。

实体类型： module / function / class / method / config / constant 关系类型： CONTAINS / IMPORTS / INHERITS / CALLS / REFERENCES

50 个 MCP 工具速查

完整功能、参数与「意图 → 工具」路由见 skills/ 各 Skill 与 MCP_SETUP.md。这里按引擎列出。

审计引擎

记忆引擎

记忆库落点：coderef_memory 写入 <项目根>/data/memory_state/；coderef_operation_memory 写入 <项目根>/data/operation_memory/。均按项目 hash 隔离，属运行时产物，data/ 已在 .gitignore。

创新识别引擎

变更守护引擎

OWASP 合规

人话解读平台

设计特性

项目结构

coderef-ai/
├── core/                             # 核心引擎
│   ├── mcp_server.py                 # MCP Server 入口（50 个工具）
│   ├── pipeline_runner.py            # 管线引擎（audit/architecture/docs + 知识图谱）
│   ├── tool_registry.py              # 工具注册中心
│   ├── review_strategy.py            # 审计策略判定（增量/全量 + 影响闭包）
│   ├── functional_review.py          # 功能审查（创新传播/结构复杂度等）
│   ├── report_renderer.py            # 报告/图谱/Wiki → HTML 渲染
│   ├── code_review.py                # 代码审查（diff / 全量语义首查，evidence 标记）
│   ├── frontend_inspector.py         # 前端交互审查
│   ├── code_analyzer.py / ast_parser.py / code_models.py   # AST 分析
│   ├── code_knowledge_graph.py       # 知识图谱引擎（SQLite 持久化）
│   ├── health_dashboard.py           # 健康仪表盘（零外部依赖 HTML）
│   ├── wiki_generator.py / wiki_ir.py / wiki_compare.py / wiki_cross_verify.py  # Wiki 生成与交叉验证
│   ├── flow_verify.py                # 流程合规验证
│   ├── arch_audit.py / arch_gap_analyzer.py / target_arch_schema.py / refactor_task_generator.py / arch_alignment_verifier.py  # 架构治理
│   ├── canvas_generator.py / workflow_graph.py / diagram_generator.py  # 可视化
│   ├── governance_audit.py / agent_security_auditor.py / sca_checker.py / tech_debt_detector.py / integrity_checker.py / blind_spot_detector.py / innovation_propagation_detector.py / junk_detector.py / resource_gap_detector.py / code_simplifier.py / project_maturity_checker.py  # 11 检测器
│   ├── memory_layer.py / memory_quality.py / prompt_governance.py / prompt_compliance.py  # 记忆与 Prompt 治理
│   ├── innovation_engine.py / design_registry.py / replicate_engine.py  # 创新与资产
│   ├── verify_findings.py / interpretation_platform.py / owasp_compliance.py  # 核验/人话/合规
│   ├── change_guard.py / change_report.py              # 变更守护
│   └── llm_integration.py / cache_manager.py / project_scope.py / shared_filter.py  # 基础设施
├── skills/                          # 三层编排 Skill（probe/governance/asset/mcp）
├── config/                           # 配置（settings.py + 本地 config.json，含密钥，已 gitignore）
├── docs/                             # 文档 + changelog 更新日志归档
├── cache/                            # 运行时缓存（已 gitignore）
├── coderef-report/                   # 输出报告（已 gitignore）
├── setup.bat                         # Windows 配置向导
├── requirements.txt
├── MCP_SETUP.md / LICENSE / LICENSE-MIT-v4.md

可靠性如何验证

我们不把「能跑通」当验收标准，而是用多重方式 + 量化指标持续证明工具测得准、不误报、不撒谎，按五层由浅入深逼近真实使用：

• 单工具可调用（tool）：每个 MCP 工具能被正确调用、输入校验符合预期。

• 多工具编排（workflow）：审计→图谱→报告等既定工作流不短路、不丢结果。

• 跨工具思路（idea）：跨引擎配合，如审计发现驱动知识图谱与创新复刻。

• 已知缺陷命中（defect-hit）：维护真实缺陷清单（错题集），每个缺陷都定位到源码文件/行号/标识符证据、经二次核验、禁止臆造；逐批跑审计后按「缺陷 × 维度」算检出率，作为可复现硬指标——检出率低的维度即暴露盲区，驱动下一轮补修。

• 修复验证负向断言（defect_clean）：对已登记缺陷预置「修复后应不再命中」的负向断言，验证缺陷修复后工具不再误报，补上「错题重做做对没」的双向闭环。

• 维度独立命中率：对绑定维度逐个判定命中，暴露单维度漏报，避免「任一维度命中即 PASS」掩盖盲区。

• 注册表 ↔ 源码一致性（validate_registry）：校验错题集登记与源码真实签名不漂移，防止错题集长期失真。

• LLM 自主审查（llm-review）：让 LLM 扮演审查者自主编排工具做端到端审查，验证「AI 自己会用这些工具」这一最贴近真实使用的场景。

• 正向模拟：分别模拟编程 AI 调工具、非编程人员核对体检单，并覆盖「环境工具缺失时通过操作记忆恢复」的自愈路径。

当前量化基线（每轮回归刷新）：

早期基线为 41.9%——也就是说，工具盲区是通过可复现的硬指标暴露、并被逐轮补修填平的，而不是靠宣称。

三层防线 + 全量泛化回归（覆盖 v5.9–v5.12）：

• 静态契约层：schema/工具注册扫描、Skill 引用断链扫描、旧接口移除核查。

• 运行时行为层：MCP 实调（合法/非法参数、全 action 覆盖、降级路径、落盘契约）。

• 端到端闭环层：真实项目五阶段治理闭环 + 定向构造的对抗场景（资产沉淀/复用/流程校验/真重复识别）。

• 全量泛化：11 样本 × 9 子探针 = 99/99 通过、0 失败。

边界与诚实声明：错题集需持续维护，我们通过「每缺陷附确定性证据 + 二次核验 + 逐轮刷新」控制其质量与覆盖面。我们不把工具定位为「替代人工审查」，而定位为确定性验证——能确证的就确证，不能确证的一律明确标注「待人工确证」，把不确定性如实交给使用者判断。

杀毒误报处理

CodeRef-AI 是合法开源的安全审计工具，不含任何恶意代码。但依赖扫描（SCA）本地 CVE 库曾因含英文攻击型漏洞描述，被部分杀毒软件的启发式引擎（如 HEUR:HackTool/VulnScan）误判为漏洞扫描工具；v4.2.7 起已改为中文中性措辞，大幅降低误报概率。若仍误报：

1. 加入排除项：将项目目录加入杀毒排除/白名单（Windows Defender：设置 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加文件夹）

2. 厂商申诉：向杀毒厂商提交误报申诉，说明这是合法开源审计工具，请求将 sca_checker.py 加入白名单（根治途经）

3. 如实告知审计 AI：若 SCA 结果缺失或被清理，先配好排除项再跑审计，避免误删导致结论失真

项目历史

CodeRef-AI 从「一份看得懂的项目简报」出发，一步步长出静态审计、知识图谱、四大引擎与逻辑闭环。每个大版本都在回答同一个问题：让一个不懂编程的人，究竟能对自己的项目知道多少。

更新日志

3.X 与 5.X 系列的完整逐版本更新日志（v3.0 – v5.13.2）统一归档至 docs/changelog/CHANGELOG.md；线上 README 只保留当前版本状态。

当前版本 v5.13.2 — U-37 外部反馈三工具问题修复（arch_gap 白名单豁免 + flow_verify 实例化调用建边）

承接测试方交接清单（U-37）：arch_gap 不消费白名单 rule=duplicate 豁免（已豁免符号仍报 true_duplicate）/ flow_verify 对「import（模块级/方法体内）+ 实例化对象方法调用」建边缺口（svc.run() 漏建边致真连通步骤判 outside/missing），2 项真实缺陷修复。

• fix（U-37①）：arch_gap_analyzer._detect_duplicates 新增 _whitelist_duplicate_exemptions 读取 whitelist rule=duplicate 条目（file+rule+category），簇的任一副本文件命中豁免即不再产出 duplicate gap；未豁免真重复 / designed_parallel 语义保留。

• fix（U-37②）：ast_parser 新增 local_imports/local_assignments 递归提取方法体内局部 import 与赋值；_build_from_ast 从两档 import + 实例化赋值推导「变量名 → 宿主类」映射，tool=ResearchTool(cfg) → tool.run 建 CALLS 边到 ResearchTool.run（精确主键匹配防跨类同名误绑），置于短名 LIKE 回退之前杜绝伪边；caller 定位新增 AST 结构兜底。

• 回归测试：tests/test_feedback_fixes.py 新增 11 用例（豁免消费 / 局部+模块级实例化建边 / self 兄弟保护 / 不误绑 / verify 闭环），宿主 suite 58 用例 7 RED 全转绿，全量 154 用例通过。

• 版本号：5.13.1 → 5.13.2（patch，缺陷修复；不改工具暴露面）。

设计借鉴

CodeRef-AI v4.8 的操作记忆层（BRAIN.md 产物、判存标准、时间线机制）在设计上结合了以下开源项目方案：

• mindmuxai/brain.md（Apache-2.0）—— BRAIN.md 命名、「能否从代码重建」判存标准、「当前理解 + 时间线」结构。参考：https://github.com/mindmuxai/brain.md

• TencentDB-Agent-Memory（MIT）—— 分层记忆与渐进式披露，控制上下文 token 占用。参考：https://github.com/Tencent/TencentDB-Agent-Memory

CodeRef-AI v4.9 的 Wiki 工具增强层（wiki_generator 增量同步 / wiki_ir / wiki_cross_verify）参考了：

• langchain-ai/openwiki（MIT）—— 增量同步（.last-update.json + 快照比对）+ 结构化元数据；同时以其成本失控、限流重试不健壮、输出截断静默失败等真实缺陷警示我们补上开销封顶与诚实失败。参考：https://github.com/langchain-ai/openwiki

• tt-a1i/archify（Apache-2.0）——「生成/校验分离」（LLM 产出 JSON-IR → schema 校验 → 确定性渲染）与 Last-good 门控（校验通过的产物备份，失败时保留上次可用版本）。参考：https://github.com/tt-a1i/archify

与上述项目不同，CodeRef 保留自己的差异化主轴：以静态知识图谱交叉验证徽章为文档可信来源，而不是依赖宿主 LLM 的自我断言。

许可证

CodeRef-AI 从 5.0 起采用双轨授权协议（LICENSE）：兼容 PolyForm Noncommercial 1.0.0 的使用边界，并清晰界定「企业内部自用免费、禁止转卖」：

• 企业内部自用，免费：企业团队用本工具协助自己的软件开发、排解编程困境（无论是否以盈利为目的的自研业务），不属于「商业再分发」，欢迎直接使用，无需付费或额外授权。

• 禁止转卖 / 对外提供 / 嵌入竞品：不得将本软件（或衍生版本）直接出售、作为服务/工具对外提供并收费，或作为竞争产品的部分嵌入其他以售卖为目标的商业软件——即防止「拿本工具去卖钱」。若确实需要对外提供商业服务，请与作者联系另行授权。

• 非商业场景免费：个人学习、研究、开源项目、非营利/教育/政府机构等非商业目的可自由下载、使用、修改、分发，无需付费。

• 完整许可文本见 LICENSE；需要商业授权的合作请与作者联系。

版本分界：v4.9.12 及更早的 4.X 系列 仍按 MIT License 授权（LICENSE-MIT-v4.md）。

贡献指引（Contributing）

欢迎通过 Issues 报告缺陷、提出建议或参与讨论；本仓库暂不接收外部代码合并（Pull Request），以保留未来商业化（商业授权）空间并规避外部贡献的版权归属问题。详见 贡献指引。