CodeRef AI
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
CodeRef-AI — 编程 AI 的治理外脑,非编程人员的技术助理
Version 5.21.22 | Python 3.10+ | MCP Protocol | CodeRef 双轨授权协议
给编程 AI 一双确定性的眼睛,给非编程人员一张看得懂的工程体检单。
项目状态与路线图
当前阶段:5.X 已封板(2026-11-16)。
5.X 已完成最终验收修订并封板:版本 5.21.22 为 5.X 的最终版本,不再引入新功能、不再升版;后续仅保留已知问题说明,不再做功能性修订。
6.X 路线:转向 DeepSeek Hermes 改造,不再维护 MCP 工具集。
经过 5.X 对真实大型遗留工程(屎山)的实测,暴露出一个结构性限制:MCP 工具与编程 AI 的交互强度不足——工具是拉取式的,编程 AI 不主动调用就看不到任何结论;梦境 AI 的设想无法承载,记忆引擎与知识图谱无法常驻在对话里,导致大量设计在真实工程中落不了地,沦为无效产出。
因此 6.X 不再维护 MCP 工具集,改为对 DeepSeek Hermes 进行改造,形成专项代码治理软件工具。5.X 已验证的审计口径、图谱模型与治理语义作为 6.X 的设计输入保留,MCP 接口层不再作为交付形态。
完整版本索引见 docs/changelog/CHANGELOG.md。
5.X 已知问题(非编程缺陷,属 MCP 标注工具的结构性限制)
以下三条不是代码缺陷,而是「MCP 工具 + 外部编程 AI」这一交付形态本身的限制;5.X 不再投入改造,留待 6.X 架构变动解决:
无法有效与编程 AI 主动交互:MCP 工具是拉取式的,编程 AI 不主动调用就看不到任何结论,工具无法主动把风险推给 AI。
记忆系统与梦 AI 无法有效常驻后台:记忆引擎、知识图谱与梦境 AI 无法常驻在对话里,设想与上下文难以持续承载,大量设计在真实工程中落不了地。
项目评估台(index 工作台)内容未完全改为小白可读版:页面结构与入口已面向非技术读者,但文案与信息层级尚未全部改写完成;6.X 架构变动完成后将继续更新该功能。
Related MCP server: ws-mcp
它是什么
CodeRef-AI 通过 MCP 协议暴露 59 个工具,同时服务两类人:
编程 AI 的治理外脑:让 AI 不再逐文件读代码,而是像查数据库一样查询项目的结构、调用链与风险;编程 AI(或 CodeRabbit)给出论断时,还能用静态图谱做确定性核验,再决定采不采信。
非编程人员的技术助理:把代码变成通俗的健康仪表盘、Wiki 与流程确证。你只需定义「入口 A 应该依次经过步骤 B→C→D」,
coderef_flow_verify就会在调用链里给出确证 / 在管线 / 存疑 / 缺失四种状态——不用读代码,也能确认项目有没有按你的设想运转。
多数 AI 审查工具把结论建立在「大模型读代码」上,而模型会幻觉。CodeRef 反过来:审计、图谱、架构诊断、流程验证、变更守护、OWASP、论断核验等核心能力全部是纯静态分析,结果确定、可复现——同一个项目每次跑出同样结论。LLM 只用于 Wiki、业务报告、创新排查、产出物语义评估(coderef_eval)等「要人话」的场景,未配置 API Key 时会明确硬阻断(coderef_eval 返回 status=SKIP)并提示配置,绝不降级编造。
三条编排主线:59 个工具不是散件,而是一条主链
59 个工具虽多,但 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 软入口档「先架构诊断」**只摸底(架构梳理 + 治理价值决策门,不动生产码),价值成立再升级正式主链,价值不足则停在摸底不硬上全链。
Skill 怎么接入:先加载 skills/coderef-mcp/SKILL.md(工具速查 + 意图→工具路由 + 梦协议),再按阶段追加 probe / governance / governance-semi / asset。支持目录式 Skill 的客户端直接把 skills/ 复制到客户端 skills 目录;只支持系统提示的客户端把 coderef-mcp 正文粘进项目规则即可。完整说明见 MCP_SETUP.md → Skill 接入。
为什么可信:关键主张都有量化实证
CodeRef 不靠宣称,靠可复现的硬指标(完整方法见后文「可靠性如何验证」):
主张 | 实证 |
全量回归 | 11 个样本工程 × 9 类子探针 = 99/99 通过、0 失败,验证「测试污染 = 无」 |
治理闭环 | 五阶段端到端,指标单调收敛:模块归属度 0.03→0.04→0.11 ↑、未归属缺口 479→478→439 ↓、期望流程越界/缺失 =0;游离一键纳入后再降至 436、归属度 0.12 |
LLM 盲区 | 被测主链均为确定性静态链路(天然不触发 LLM);LLM 型链路一测即通,受控提炼零残留 |
工具收敛 | 冗余工具合并(操作记忆 6 合 1、记忆层 4 合 1)、旧接口移除、未知参数如实报、语义检索不可用时自动降级为关键词——收敛不缩水,降级不撒谎 |
降噪 | 一次审计从 873 条噪声收敛到 79 条(约 91% 降幅) |
给调用方 AI 的结论信封(v5.18.12 起)
真正读结论的往往是对方的 AI,而它的用户可能不懂代码。为避免把「输入过期」说成「工具坏了」,6 个高频工具的返回顶层新增 envelope:
"envelope": {
"verdict": "定标过期:本轮对齐度/覆盖率不可用,不是代码问题",
"usable_for_decisions": false,
"blocked_by": [{"id": "stale_target_arch", "owner": "consumer",
"human": "target_arch 已过期,请先重新定标", "limitation": "KL-01"}],
"owner_actions": {"coderef": [], "consumer": ["coderef_target_arch_set"]},
"cannot_conclude": ["对齐度", "覆盖率", "差距条数作为代码质量结论"],
"guardrails": ["定标过期时任何基于 target_arch 的指标都不可对外引用"],
"limitations": ["KL-01"]
}归属模型:
owner=coderef才是工具缺陷;consumer表示需要调用方先重跑/重定标;by_design是已知取舍。已知限制登记表 KL-01~KL-09:定标过期、IMPORTS 只建内部边、CALLS 按 import 作用域、模块数多口径、architecture 不产 findings、过期产物 unknown、备份需 whitelist、动态调用不覆盖、文档只认 Wiki 目录。
握手契约:
coderef_version(project_path)返回consumer_contract(3 条必读 + KL 全表 + 字段说明),调用方 AI 无需加载本仓 Skill 也能正确转述。覆盖工具:
coderef_audit/coderef_scan/coderef_report/coderef_arch_gap/coderef_arch_verify/coderef_interpret(action=health);旧字段全部保留,向后兼容。公开规程入口卡示例:没有本地
AGENTS.md时,coderef_operation_memory(action=recover)与首次重工具的memory_digest会从 docs/procedure-card.md 返回procedure_card(发布 SOP / 审计全流程 / CodeRabbit 位置)。该文件是一份示例模板,可直接复制到你自己的项目docs/procedure-card.md并替换成你的命令;它只是入口,完整细节仍以项目自己的规程为准。
结果级新鲜度硬戳(v5.19.1 起)
信封新增 freshness 块,滞后信息直接贴在结论上,调用方不查 coderef_version 也能看到:
"freshness": {
"artifacts_used": [{"key": "kg_db", "exists": true, "modified_at": "2026-11-09 10:00:00",
"code_newer": true, "stale_by_age": false, "refresh_hint": "coderef_memory(action=sync) 或重跑 coderef_audit"}],
"code_newer": true,
"stale_reason": "代码比产物新: 知识图谱",
"refresh_action": "coderef_memory(action=sync) 或重跑 coderef_audit"
}coderef_querystale 感知:查询前比对代码 mtime 与图谱built_at,代码更新超过阈值(默认 30 分钟或 3 个文件)时结果标stale=true,并自动排入后台增量sync,返回sync_task_id;<project>/.coderef/guard_config.json的query.mode=block可改为同步刷新后重查。图谱文件级增量:
coderef_memory(action=sync, mode=incr)只重建变更/删除文件及其 import 依赖方的节点与边,并与全量重建结果逐行一致;无变更时不重建。
统一范围层与前置闸门(v5.19.2 起)
.coderef/scope.json单一事实源:新增coderef_scope工具(add/remove/list/verify)。exclude_glob(路径模式)、ignore_lib(第三方库名)、include_override(误伤找回)一次写入、后续审计/图谱/SCA 自动生效;add立即返回生效验证回执(排除文件数、按工具计数、与保留文件同名的可疑误伤)。scope 边界:只作用于扫描与检索,不作用于 change_guard——忽略的是审计噪音,不是安全责任。
precondition 四闸门:G-A 未 recover、G-B 图谱过期、G-C 定标缺失、G-D 审计产物超龄。默认
warn(返回体附context.gate_warnings),<project>/.coderef/guard_config.json设preconditions.mode=block后返回status=blocked+envelope.blocked_by.owner=consumer+owner_actions;coderef_version/task_status/scan_list/scope等只读工具永远放行。
调度层 coderef-dispatcher(v5.19.3 起,形态 A)
编程 AI 从「编排 59 个工具」降级为「调用 4 个调度工具」,中间工具返回不再逐条进主 AI 上下文:
coderef_plan:意图(probe / single_audit / recover / governance / asset / remind)→ 计划卡(步骤、预计工具数与时长、用户决策点),纯规划不执行。remind纪律复盘:coderef_execute(intent=remind)由 dispatcher 进程内检查「操作记忆是否恢复、变更守卫是否覆盖当前工作区、图谱是否落后、审计产物是否过期」,返回forgotten / passed / unknown三类事实——主 AI 不必靠上下文回忆自己漏了什么。coderef_execute:按计划或意图执行,逐步过前置闸门;缺 recover 先 recover、图旧先 sync(违规自动补齐),G-C 定标缺失等需用户决策的步骤暂停浮出,不替用户做治理决策;默认后台执行返回task_id。coderef_dispatch_status/coderef_dispatch_report:前者看当前步骤与闸门记录,后者取最终摘要信封(结论 + freshness + KL +owner_actions+ 折叠的步骤索引 + 上下文节省比)。链定义:
core/dispatch_chains.yaml是唯一事实源(L1/L2/L3 步骤、失败策略、决策点)。轨迹落盘.coderef/dispatch/<task_id>.json;YAML 缺失/损坏时coderef_plan明确报错并给出裸工具回退建议,59 个工具照常可用。
LLM 意图层(v5.19.4 起,形态 B,可选)
coderef_plan(intent_text="用大白话说目标"):由 LLM 把自然语言归到 5 个链意图之一,计划卡标mode=llm与router{intent, confidence, reason}。LLM 只选链,审计/图谱/架构结论仍全部来自规则引擎与静态分析。无 Key 硬阻断:未配置有效 API Key 时返回
status=blocked+mode=rule,提示改用intent枚举(形态 A),不猜不编。置信度不足不执行:低于 0.6 或返回不可解析时
status=needs_confirmation+ 候选意图,交由用户/主 AI 确认。确认门:
coderef_execute不接受未确认的intent_text——必须先coderef_plan(intent_text=...)拿计划卡,再coderef_execute(plan_id=...)。
观测层(v5.19.5 起)
审计日志:每次工具调用的防护判定落盘
.coderef/audit_log/YYYYMMDD.jsonl(按日轮转),字段含tool/gate{result: hit|pass|miss, hits, mode}/memory_digest{injected, available, items}/freshness{code_newer, stale_reason, refresh_action}/scope{rules}/blocked{gate, reason},同一 MCP 进程共享session。coderef_dispatch_metrics:聚合最近 N 天(默认 7)日志,输出闸门命中率、阻断 Top 与原因 Top、记忆注入命中率、新鲜度事件与刷新动作 Top、scope 生效次数、dispatcher 任务结局。只统计实际落盘记录,empty 就是 empty,不做推断补齐。违规注入测试:block 模式下「未 recover 直接 audit」被 G-A 拦截且日志可追溯;scope add 后 audit 实际排除;stale 查询带
stale=true与sync_task_id。
梦(v5.20.0 起,v5.21.2 扩 job / 草稿 / P3):编程 AI 的离线巩固层
CodeRef 不只回答「现在是什么」,也在安静时替主 AI 补梦——复用 CodeRef 的主 LLM 配置(与其他 LLM 工具同一套 Key/预算),把被阻断、失败、变更守卫退化与主 AI 显式 seed 的经历巩固成更少、更准的联想,写入项目本地 .coderef/dream/:
coderef_dream(action=status|seed|read|run|drafts|evals):status看最近做梦时间、笔记数、草稿/评估数、主 LLM 状态、支持的 job 与上次错误;seed显式投喂一条显著事件(不读取主 AI 全量对话);read读DREAM.md或按 job/kind/关键词取笔记;run手动补一轮(默认后台);drafts读草稿摘要或按draft_id读全文;evals读评估摘要或按eval_id读全文。job 契约(v5.21.1):记忆/叙事类
pitfall(默认)/recap(续接目标与上次进度)/routing(当 X,先用 Y)/triage(先看什么)/change_narrative(上次改了什么)/failure_postmortem(失败根因假设)。recap的事实进「当前目标」,triage建议进「本次开工建议」;claim_type=advice永远只能是假设,不会进「已验证规则」。草稿链(v5.21.1):
review_draft/refactor_draft/asset_candidate/noise_proposal只写.coderef/dream/drafts/,返回requires_confirmation=true与服务端固定的next_tools;用coderef_dream(action=drafts)读取,用户确认后走review/arch_verify/asset/scope等确定性工具,永不自动应用。P3 维护/评估(v5.21.2):
false_memory_check纯确定性复核旧梦证据(失效 → rejected,审计日志窗口外不算失效);eval_replay从runs/notes/archive汇总token_cost / dream_hit / false_memory / decay_count,无 LLM 也出确定性指标,有 LLM 追加软摘要;报告写.coderef/dream/evals/,用coderef_dream(action=evals)读取。两者都手动触发,不自动跑。启动补梦(显式开启):
dream.run_on_startup=true后,首次带项目路径的工具调用会在后台触发一次,不阻塞首响应;默认关闭,避免在不知情时消耗主 LLM 额度。输出
DREAM.md(≤800 token):六节——当前目标 / 本次开工建议 / 已验证规则 / 坑 / 联想(当 X,先想到 Y)/ 未决问题;notes.json保留证据、job、claim_type 与状态,runs/留输入摘要与采纳/拒绝记录。LLM 提议 + 确定性核验:每条笔记必须有
evidence(file:/git:/audit:/seed:/dispatch:);核验失败直接rejected,无法核验标hypothesis,只有 verified 事实进入「已验证规则」。梦是假设,不改写任何审计结论。记忆摘要梦优先:重工具首次返回的
context.memory_digest先放 triage 的「开工建议」,再放 verified 笔记,最后补操作记忆;remind复盘新增dream段,列出「梦里提醒过什么」。诚实边界:主 LLM 无 Key →
status=SKIP,不产出占位内容;梦的视野仅限 CodeRef 被调用的范围,unknown/SKIP如实呈现。
工具面 profile(v5.21.0 起)
59 个工具不必每次全暴露给主 AI。CODEREF_TOOL_PROFILE 控制 tools/list 的暴露面:
full(默认):59 个工具全开,适合 CI / 高级用户。lite:只暴露 12 个入口——version/plan/execute/dispatch_status/dispatch_report/dream/task_status/scope/operation_memory/verify_findings/change_guard/audit,适合日常 AI 使用。隐藏不等于移除:handler 全部保留,隐藏工具仍可按名直接调用;
coderef_version返回tool_profile{profile, source, tools_exposed, tools_hidden},非法值回退full并如实报错。Skill 的「梦协议」与主链工具引用按
lite编写;需要 full-only 工具时显式标注。
快速开始
如果你是非编程人员:把这部分说明交给你的编程 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.txt2. 配置 LLM(可选)
审计、图谱、架构诊断、流程验证、变更守护、OWASP 不需要 LLM,纯静态即可运行。仅 LLM 型工具(Wiki、业务报告、代码审查、Prompt 资产、创新识别、
coderef_eval产出物语义评估)需要 LLM;未配置 API Key 时这类工具被硬阻断并提示配置(coderef_eval返回 status=SKIP),不产出降级/占位内容。梦(可选,复用主 LLM):梦不单独配置 Key,直接用上面的主 LLM 配置。要开启启动补梦,在
config/config.json增加"dream": {"enabled": true, "run_on_startup": true};不配置时仍可手动coderef_dream(action=run)。主 LLM 无 Key 时补梦返回SKIP,不影响其他工具。工具面(可选):在
config/config.json设"tool_profile": "lite",或设CODEREF_TOOL_PROFILE=lite,只向主 AI 暴露 12 个入口;默认full(59 个)。
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-flash" # 官方推荐: deepseek-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_server4. 配置 MCP 客户端
在 Trae / Claude Desktop 等 MCP 客户端中添加(详细指南见 MCP_SETUP.md):
{
"mcpServers": {
"coderef-ai": {
"command": "python",
"args": ["-m", "core.mcp_server"],
"cwd": "/path/to/coderef-ai"
}
}
}研发方式:项目由作者主导问题定义、架构取舍与验收;大量实现、审计与复审由编程 AI(Trae / Codex 等)在作者约束下完成。Git 历史中的 AI 提交身份如实保留,不伪装成人类提交——这既是项目的研发现实,也是它作为「AI 治理」实践样本的一部分。建议拿到代码后,用 CodeRef 自己审计一遍,让报告带你理解每处实现。
第一轮 · 完整体检(3 分钟看懂你的项目)
# 1. 全量审计(后台,自动构建知识图谱),用任务状态轮询取结果
coderef_audit(project_path="/path/to/project", background=True)
coderef_task_status(task_id="...")
# 2. 生成项目 Wiki(未配 Key 时被硬阻断并提示配置)
# 重型工具:大仓库单次可能 10 分钟以上,不要放在合入门禁/会话首响应同步调用
coderef_docs(project_path="/path/to/project", background=True)
# 3. 看健康读数(已归并到评估台;有评估台时直接返回其路径,不再产第二份仪表盘)
coderef_interpret(project_path="/path/to/project", action="dashboard")
# 4. 打开「项目评估台」(唯一用户入口):五 Tab(概览记分卡 / 架构 / 产品 / UX / 技术)
# 页面自带仅回环的轻后端:点「重新评估」刷新分数,
# 点产品/UX Tab 的按钮即跑 F 轨业务契合度 / U 轨人格走查,不依赖 AI 在旁
coderef_report(project_path="/path/to/project", open_server=True)后续 · 按需深入
# 提交前防止 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 个检测器
检测器 | 检测内容 |
治理审计 (gov) | 架构违规、安全漏洞、反模式、质量铁律,CWE/OWASP 映射 |
Agent 安全审计 (agent) | 提示注入、上下文操纵、工具滥用、数据泄露、自主行为 |
依赖扫描 (sca) | requirements.txt / pyproject.toml 的 CVE 漏洞 |
技术债务 (td) | 圈复杂度、认知复杂度、过长函数、魔法数字、注释代码 |
完整性检查 (integ) | TODO/FIXME 残留、孤立测试文件、文档覆盖率 |
盲区检测 (blind) | 文档盲区、缺失依赖、动态路径注入、空文件 |
创新传播 (inn) | 模块间设计模式不一致、"A 有 B 该有但没有"的缺口 |
垃圾文件 (junk) | 重复文件、应被 gitignore 的文件、孤立文件 |
资源遗漏 (resgap) | 缺失本地模块、动态导入风险、未使用依赖 |
代码精简 (simp) | 死代码、可标准库替代、过度工程 |
项目成熟度 (matu) | 项目健康度综合评分 |
三级自动降噪:AI 白名单精准抑制已知误报 → 规则匹配过滤 MD5 哈希、配置 URL 等常见噪声 → 邻行去重 + 爆发式合并同类项(>8 条同类别 → 1 条统计)。实测 873 → 79 条(约 91% 降幅)。
交叉验证反幻觉:多工具独立分析同一项目,相互验证,输出 HIGH / MEDIUM / LOW 置信度分级——单一工具可能误判,但多工具互验后置信度显著提升。
知识图谱
运行 audit / architecture / docs / memory_sync 后自动构建 SQLite 知识图谱,持久化到 <project>/cache/kg/,一次构建跨会话复用。
想知道什么 | query_type | 参数 |
项目有多大 |
| 无 |
搜索包含 "auth" 的代码 |
|
|
查找所有认证相关函数 |
|
|
谁调用了 |
|
|
|
|
|
修改 |
|
|
|
|
|
从 |
|
|
实体类型: module / function / class / method / config / constant
关系类型: CONTAINS / IMPORTS / INHERITS / CALLS / REFERENCES
关系层口径(v5.18.7 / v5.18.11 起):
私有函数 100% 收录:模块级
_foo不再被丢弃(只跳过类方法重复副本与 dunder)。CALLS 按 import 作用域解析:只有「本模块内定义」或「确实被本文件 import(含
as别名)」的调用才建边;同名但未 import 的check(...)、datetime.now等属性链一律不建边。精度优先、宁漏不假,因此fan_in偏保守,关键链路请用flow_verify核验。IMPORTS 只建项目内模块边:第三方/标准库 import 不建边,因此「零 IMPORTS 边模块」比例高属设计取舍,不代表依赖图缺失。
实测(外部 50 万行级项目):
check入边 7,788 → 12;跨模块且无 import 依据的 CALLS 66.1% → 17.1%;生产→测试调用 89 → 0。
59 个 MCP 工具速查
完整功能、参数与「意图 → 工具」路由见
skills/各 Skill 与MCP_SETUP.md。这里按引擎列出。
审计引擎
工具 | 功能 | 需 LLM |
| 11 审计一键产出 + 自动降噪 + 构建知识图谱; | 否 |
| 单维度审计(11 选 1),快一个量级;后台执行,用 | 否 |
| 列出 | 否 |
| 流程合规验证:「入口 A 调用管线是否覆盖 B→C→D」;状态分确证/在管线/存疑/缺失 | 否 |
| 确定性核验 LLM/CodeRabbit 论断:引用目标是否真实存在、是否在关键管线内 | 否 |
| Prompt 治理平台:资产生命周期 × 合规审计 × 跨模块一致性 | 否 |
| 架构腐化诊断(循环依赖/上帝模块/分层违例),聚合 0–10 健康度 | 否 |
| 设置/更新目标架构 JSON(治理参照系),纯确定性校验 | 否 |
| 获取当前目标架构 JSON | 否 |
| 游离一键纳入:游离/未建模模块按角色批量追加目标模块(dry_run 预览;幂等) | 否 |
| 架构差距分析(核心):9 类确定性差距,游离模块区分真游离/未建模并豁免 vendor/压缩产物噪声 | 否 |
| 业务架构画布:业务树 + 业务流程泳道( | 否 |
| 交互式流程画布:自动提取业务管线 + 数据流 | 否 |
| 差距清单 → 可执行重构任务卡 + 影响范围 + 验证标准 | 否 |
| 四维对齐度评分(职责 40%+依赖 30%+业务 20%+健康 10%)+ 差距复检 | 否 |
| 建档体检周期并导入差距为治理工作项 | 否 |
| 收尾周期,输出完成率/剩余/复发/豁免统计 | 否 |
| 查询治理工作项(预置视图 open/all/high/recurred/rejected/archived/overdue/assigned/recent) | 否 |
| 工作项状态流转 + 豁免 | 否 |
| 体检报告 / 治理看板 / 项目总览(report 单期+跨期趋势;board 交互 HTML;overview 健康+架构+Wiki+人话解读+工作项总览;已合并原 gov_board) | 否 |
| 治理自动流水线:在途项 → 任务卡 → 复验 → Verified/附缺口 | 否 |
| 动态探针:静态挖掘动态信号(动态导入/装饰器注册/间接索引),零执行被检项目 | 否 |
| 治理 Web 看板(兼容别名,转发到 gov_report action=board) | 否 |
| 多代码库聚合治理 | 否 |
| 定时体检:生成 run_cycle.py + 离期检查 | 否 |
| 符号级职责越界检测 | 可选 |
| 架构分析图谱 + 技术分区布局图( | 否 |
| 项目 Wiki 文档生成 + 子项目探测;重型,大仓单次可能 10 分钟以上,勿在合入门禁同步调用 | 是 |
| 按需读取已生成 Wiki 正文(返回内容而非路径) | 否 |
| 知识图谱结构化查询(9 种查询类型) | 否 |
| 代码审查:diff 变更审查 / 新项目全量语义首查 | 是 |
| 前端交互审查(按钮/菜单静态枚举 + 6 维度审查) | 是 |
| 聚合审计/图谱/Wiki 为自包含 HTML, | 否 |
| 审计策略判定(增量/全量)+ 重点维度 | 可选 |
| 白名单管理 + 核心模块规则配置 | 否 |
| 统一范围层: | 否 |
| dispatcher 计划卡:意图 → 链步骤 / 预计工具数与时长 / 用户决策点,纯规划不执行 | 否 |
| dispatcher 执行链:逐步入闸门、违规自动补齐、需用户决策处暂停;默认后台返回 task_id | 否 |
| dispatcher 任务状态:当前步骤、闸门命中与补齐记录、暂停决策点 | 否 |
| dispatcher 最终摘要信封:结论 + freshness + KL + owner_actions + 折叠的步骤索引 | 否 |
| 观测聚合:闸门命中率 / 阻断 Top / 记忆命中率 / 新鲜度与刷新事件 / scope 生效 / dispatcher 结局(读 | 否 |
| 后台任务状态查询 | 否 |
| 后台任务取消(协作式收尾) | 否 |
| 轻量版本探针(只读、零副作用):秒级返回当前加载的版本号,无需 project_path,用于断言「进程加载版本 == 目标版本」,杜绝进程未重启导致的结果误判 | 否 |
| 产出物语义评估(LLM-as-judge):给 CodeRef 自身的 LLM 产出物加语义质量门禁——4 个指标(answer_relevancy 相关性 / faithfulness 忠实度 / hallucination 幻觉检出 / coherence 连贯性)+ 软硬判定(硬指标一票否决,防致命错误被平均分稀释);action=assert 单条断言 / score 批量报告;只评自产,不评用户项目运行时产出 | 是 |
记忆引擎
工具 | 功能 | 需 LLM |
| 项目记忆层:sync 增量同步 / query 语义+结构查询 / status 覆盖度+盲区 / quality 质量评估+自动补全(4 工具合并) | 否 |
| 操作记忆层:sync / query / find 定位工具约定陷阱 / status / recover 恢复关键工具位置 / export 导出 Markdown(6 工具合并) | 否 |
记忆库落点:coderef_memory 写入 <项目根>/data/memory_state/;coderef_operation_memory 写入 <项目根>/data/operation_memory/。均按项目 hash 隔离,属运行时产物,data/ 已在 .gitignore。
创新识别引擎
工具 | 功能 | 需 LLM |
| 识别项目创新设计 + 传播缺口,理想清单 vs 实际实现对照 | 是 |
| 将验证过的设计固化 | 是 |
| 复刻铺排:检测目标项目对某资产的采用缺口 + 生成复刻指引;确定性,不自动改代码 | 否 |
| 复刻落地:把骨架 + 说明写入目标项目并生成 manifest;只落"确定性可给"内容,冲突默认不覆盖 | 否 |
| 把复刻铺排的确定性结论(entry_points / verified_findings)写回蓝图 | 否 |
| 管理已知设计库(别名归一,解决 LLM 命名漂移) | 否 |
| 创新复刻的 LLM 排查(是否真创新 + 复刻合理性);无 API Key 硬阻断 | 是 |
变更守护引擎
工具 | 功能 | 需 LLM |
| AI 代码退化检测(建立在 git 之上)。guard 对比基线拦截退化 / ensure_git 自动建库 / anchor 锚定健康基线 / list_baselines 列出基线 | 否 |
| 把 diff 归纳为「人话版」变更说明(新增/修改/影响/风险) | 可选 |
OWASP 合规
工具 | 功能 | 需 LLM |
| OWASP LLM Top 10 合规检测,LLM01-LLM10 逐类分级 | 否 |
人话解读平台
工具 | 功能 | 需 LLM |
| 把确定性结论翻译成人话:health 健康总览 / dashboard(已归并评估台,直接返回其路径)/ wiki / prompt / assets | 可选 |
设计特性
特性 | 说明 |
不修改代码 | 审计、图谱、诊断等分析只输出不执行;唯一例外: |
本地优先 | 分析完全在本地,审计和知识图谱无需网络,支持离线 |
隐私安全 | LLM 密钥存 |
结构化输出 | 报告 Markdown,仪表盘 HTML,知识图谱 SQLite |
检查点续跑 | 管线每 2 分钟保存进度,中断后可恢复 |
后台任务 | 长任务(audit / docs)异步执行,轮询获取结果 |
项目隔离 | 每个项目独立缓存,切换项目不互相干扰 |
开源友好 | 敏感数据集中 |
产物地图:哪些给人看,哪些给 AI 用
CodeRef 会落很多文件,但用户只需要看两个入口。其余产物要么是详情页,要么是给编程 AI 消费的数据。
用户面(需要打开看)
入口 | 从哪来 | 看什么 |
项目评估台 |
| 概览(结论)/ 架构(业务树 + 业务流程)/ 产品 F 轨 / UX U 轨 / 技术(原始分项 + 证据锚点 + 技术分区图); |
架构治理看板 |
| 治理工作项流转、周期体检(L2 治理专用,与评估台定位不同) |
架构画布:三种视图,前缀已分离
文件前缀 | 生成者 | 回答什么 |
|
| 业务树:入口 → 主功能 → 子功能 → 步骤 |
|
| 业务流程:泳道(角色)× 阶段(触发→校验→执行→落库→通知→交付) |
|
| 技术视图:角色分区布局图,面向架构师/AI 排查结构,非用户交付物 |
给编程 AI 的数据(不需要人工打开)
文件 | 用途 |
| 健康记分卡(CI 门禁、AI 读分) |
| F 轨 / U 轨结论 |
| 业务语义标注(actor / stage / handoff / value_node) |
| 审计发现结构化产物(重渲染的输入) |
| 调用链/数据流调试视图,供 AI 定位,非交付物 |
AI 直接取数据: | 不渲染 HTML,直接返回 |
| 默认不再自动生成(需 |
|
|
原则:用户面只有两个入口——项目评估台(代码健康 / 架构 / 产品 / UX)与架构治理看板(治理工作项)。其余 HTML 均为技术视图或历史产物,不作为交付物交付给非技术读者。
项目结构
coderef-ai/
├── core/ # 核心引擎
│ ├── mcp_server.py # MCP Server 入口(59 个工具)
│ ├── pipeline_runner.py # 管线引擎(audit/architecture/docs + 知识图谱)
│ ├── tool_registry.py # 工具注册中心
│ ├── review_strategy.py # 审计策略判定(增量/全量 + 影响闭包)
│ ├── functional_review.py # 功能审查(创新传播/结构复杂度等)
│ ├── report_renderer.py # 报告站点渲染(index.html = 项目评估台五 Tab)
│ ├── scorecard.py / scorecard_weights.json # 健康记分卡(确定性聚合 + 权重外置 + CLI)
│ ├── report_console.py # 评估台回环轻后端(/api/scorecard、/api/config、/api/evaluate)
│ ├── product_evidence.py # 产品证据包(能力/声称/首次价值路径自动枚举,全部带锚点)
│ ├── product_eval.py # F 轨业务契合度(五问矩阵 + 链路核验 + 三档结论)
│ ├── personas.json / ux_eval.py # U 轨人格走查(只判阻断 + Rage Map 业务后果列)
│ ├── business_semantics.py / arch_flow.py # 业务叙事标注(actor/stage/handoff)+ 流程泳道画布
│ ├── 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 # 健康仪表盘(默认不再自动产出,健康读数统一看评估台)
│ ├── wiki_generator.py / wiki_ir.py / wiki_compare.py / wiki_cross_verify.py # Wiki 生成与交叉验证
│ ├── flow_verify.py # 流程合规验证
│ ├── arch_audit.py / arch_gap_analyzer.py / arch_framework.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 # 变更守护
│ ├── version.py # 版本号唯一真源(__init__ / pyproject / mcp_server 均从此读取)
│ └── llm_integration.py / cache_manager.py / project_scope.py / shared_filter.py # 基础设施
├── skills/ # 5 个编排 Skill(mcp 入口 + probe/governance/governance-semi/asset)
├── tools/check_version.py # 发布前版本一致性校验(README/MCP_SETUP/CHANGELOG 与真源比对)
├── config/ # 配置(settings.py + 本地 config.json,含密钥,已 gitignore)
├── docs/ # 文档 + changelog 更新日志归档
├── cache/ # 运行时缓存(已 gitignore)
├── .coderef/ # 运行时产物:report/html 评估台、scorecard/findings(按项目隔离,已 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 调工具、非编程人员核对体检单,并覆盖「环境工具缺失时通过操作记忆恢复」的自愈路径。
当前量化基线(每轮回归刷新):
检测维度 | 缺陷命中率 |
技术债 / Prompt 治理 / 供应链 / 治理合规 / Agent 安全 / 流程验证 | 全 100% |
总体(9 个真实项目、35 个命中用例) | 100% |
早期基线为 41.9%——也就是说,工具盲区是通过可复现的硬指标暴露、并被逐轮补修填平的,而不是靠宣称。
三层防线 + 全量泛化回归(覆盖 v5.9–v5.12):
静态契约层:schema/工具注册扫描、Skill 引用断链扫描、旧接口移除核查。
运行时行为层:MCP 实调(合法/非法参数、全 action 覆盖、降级路径、落盘契约)。
端到端闭环层:真实项目五阶段治理闭环 + 定向构造的对抗场景(资产沉淀/复用/流程校验/真重复识别)。
全量泛化:11 样本 × 9 子探针 = 99/99 通过、0 失败。
边界与诚实声明:错题集需持续维护,我们通过「每缺陷附确定性证据 + 二次核验 + 逐轮刷新」控制其质量与覆盖面。我们不把工具定位为「替代人工审查」,而定位为确定性验证——能确证的就确证,不能确证的一律明确标注「待人工确证」,把不确定性如实交给使用者判断。
测试与验证:公开什么、不公开什么
5.X 封板后,本仓库已包含 tests/ 目录,当前基线 761 passed / 4 skipped / 74 subtests:
tests/:开发方自测用例,覆盖审计、知识图谱、Wiki、记忆、梦、调度、工具契约等;LLM 全部打桩,不依赖网络与私有样本。tests/external/:独立回归用例集,覆盖工具契约矩阵、提示词注入、极端输入、并发/多进程、多项目隔离、环境边界、版本回滚与各版本回归;全部在临时目录内运行,只读被测仓库。
运行方式:
pip install -r requirements-dev.txt
python -m pytest -q # 全量
python -m pytest tests/external -q # 只跑独立回归集不公开什么:
真实项目样本与私有测试资产(客户工程、真实案例 E2E、诊断脚本);
需 LLM Key 的语义评估用例与浏览器端到端用例(本地可选,不入库);
内部缺陷错题集与历史测试报告。
README 中的
99/99、降噪91%等数字来自开发方本地真实项目样本,样本未公开,属于内部回归记录,不是第三方可复现基准。公开 CI 只做 AST 编译/依赖一致性与 scorecard,不跑 pytest;这是已知边界,不伪装成完整质量门禁。外部可复现的证据是公开 CI 的compile-check/coderef-gate,以及在你自己的项目上运行coderef_audit、coderef_report、coderef_flow_verify得到的确定性产物。
杀毒误报处理
CodeRef-AI 是合法开源的安全审计工具,不含任何恶意代码。但依赖扫描(SCA)本地 CVE 库曾因含英文攻击型漏洞描述,被部分杀毒软件的启发式引擎(如 HEUR:HackTool/VulnScan)误判为漏洞扫描工具;v4.2.7 起已改为中文中性措辞,大幅降低误报概率。若仍误报:
加入排除项:将项目目录加入杀毒排除/白名单(Windows Defender:设置 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加文件夹)
厂商申诉:向杀毒厂商提交误报申诉,说明这是合法开源审计工具,请求将
sca_checker.py加入白名单(根治途经)如实告知审计 AI:若 SCA 结果缺失或被清理,先配好排除项再跑审计,避免误删导致结论失真
项目历史
名字与历史:本项目现名 CodeRef-AI(简称 CodeRef)。仓库初版曾以 PersuadeAI 名义开发;代码与历史提交中若仍出现
PersuadeAI Team,指的是本项目的早期署名,不是另一个产品/团队。自公开仓库起,对外名称统一为 CodeRef-AI;GitHub 仓库 slug 为Coderef-Ai(平台保留的大小写),文档一律写作 CodeRef-AI。阅读提示:
core/mcp_server.py模块 docstring 中的v4.6 — 四大引擎是该入口模块冻结时的历史标记;当前版本、引擎与工具数以 README 和coderef_version为准,不随该注释更新。
CodeRef-AI 从「一份看得懂的项目简报」出发,一步步长出静态审计、知识图谱、四大引擎与逻辑闭环。每个大版本都在回答同一个问题:让一个不懂编程的人,究竟能对自己的项目知道多少。
版本 | 目标 |
1.0 | 写一份完整的项目简报,让人类搞清楚项目是怎么回事 |
2.0 | 通过各类审计工具,查清项目有哪些常见问题 |
3.0 | 通过知识图谱和 Wiki,建立更详细的简报 |
4.0 | 通过四个引擎和四个支柱,增强覆盖、形成逻辑闭环 |
5.0 | 治理被反复修改搞乱的混乱管线,让项目回归正确 |
设计借鉴
CodeRef-AI v4.8 的操作记忆层(BRAIN.md 产物、判存标准、时间线机制)在设计上结合了以下开源项目方案:
mindmuxai/brain.md(Apache-2.0)——
BRAIN.md命名、「能否从代码重建」判存标准、「当前理解 + 时间线」结构。参考:https://github.com/mindmuxai/brain.mdTencentDB-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/openwikitt-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;需要商业授权的合作请与作者联系。
许可元数据说明:
pyproject.toml的 SPDXlicense字段为LicenseRef-CodeRef-Dual(自定义许可引用),与仓库根LICENSE的自定义双轨协议一致;实际授权以LICENSE文本为准。LICENSE-MIT-v4.md仅适用于 v4.9.12 及更早的 4.X 系列。
版本分界:v4.9.12 及更早的 4.X 系列 仍按 MIT License 授权(LICENSE-MIT-v4.md)。
贡献指引(Contributing)
欢迎通过 Issues 报告缺陷、提出建议或参与讨论;本仓库暂不接收外部代码合并(Pull Request),以保留未来商业化(商业授权)空间并规避外部贡献的版权归属问题。详见 贡献指引。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
A paid remote MCP for code graph MCP for AI coding, built to return verdicts, receipts, usage logs,
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Related MCP Servers
- AlicenseAqualityAmaintenanceA local-first codebase intelligence tool that enables AI assistants to research codebases using semantic search, multi-hop relationship discovery, and structural parsing. It allows users to extract architectural patterns and institutional knowledge across 30+ programming languages through an MCP-compatible interface.2741 PyPI1,463MIT
- AlicenseAqualityBmaintenanceA self-hosted MCP server that fetches live documentation and performs code audits using real-time authoritative references to prevent AI hallucinations. It provides tools for searching documentation across 330+ libraries and scanning local source code for security, performance, and accessibility issues.14163 npm7Elastic 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to perform hybrid code search, get explanations, analyze relations and impacts, retrieve context packs, and generate documentation across ~45 languages via 17 MCP tools, all powered by a local vector database and LLM.2Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAnalyzes codebases to produce a persistent code knowledge graph and an MCP server with 9 tools for AI coding agents.34 PyPI2Apache 2.0