Skip to main content
Glama

MCP Badge

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 架构变动解决:

  1. 无法有效与编程 AI 主动交互:MCP 工具是拉取式的,编程 AI 不主动调用就看不到任何结论,工具无法主动把风险推给 AI。

  2. 记忆系统与梦 AI 无法有效常驻后台:记忆引擎、知识图谱与梦境 AI 无法常驻在对话里,设想与上下文难以持续承载,大量设计在真实工程中落不了地。

  3. 项目评估台(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_query stale 感知:查询前比对代码 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.txt

2. 配置 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_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(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

参数

项目有多大

stats

无

搜索包含 "auth" 的代码

search

keyword="auth"

查找所有认证相关函数

entity

name="auth", type="function"

谁调用了 process_order

callers

func_name="process_order"

main 调用了哪些函数

callees

func_name="main"

修改 utils.py 影响哪些模块

impact

file_path="utils.py"

server.py 有哪些函数和类

file_entities

file_path="server.py"

从 handle_request 展开调用链

call_graph

func_name="handle_request", depth=3

实体类型: 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

coderef_audit

11 审计一键产出 + 自动降噪 + 构建知识图谱;strategy=auto/full/incr

否

coderef_scan

单维度审计(11 选 1),快一个量级;后台执行,用 coderef_task_status 轮询

否

coderef_scan_list

列出 coderef_scan 可选维度

否

coderef_flow_verify

流程合规验证:「入口 A 调用管线是否覆盖 B→C→D」;状态分确证/在管线/存疑/缺失

否

coderef_verify_findings

确定性核验 LLM/CodeRabbit 论断:引用目标是否真实存在、是否在关键管线内

否

coderef_prompt_governance

Prompt 治理平台:资产生命周期 × 合规审计 × 跨模块一致性

否

coderef_arch_audit

架构腐化诊断(循环依赖/上帝模块/分层违例),聚合 0–10 健康度

否

coderef_target_arch_set

设置/更新目标架构 JSON(治理参照系),纯确定性校验

否

coderef_target_arch_get

获取当前目标架构 JSON

否

coderef_target_adopt

游离一键纳入:游离/未建模模块按角色批量追加目标模块(dry_run 预览;幂等)

否

coderef_arch_gap

架构差距分析(核心):9 类确定性差距,游离模块区分真游离/未建模并豁免 vendor/压缩产物噪声

否

coderef_arch_canvas

业务架构画布:业务树 + 业务流程泳道(with_flow,默认开);format=data 不渲染 HTML、直接返回结构化数据(lanes/edges/clusters)给 AI

否

coderef_flow_canvas

交互式流程画布:自动提取业务管线 + 数据流

否

coderef_refactor_plan

差距清单 → 可执行重构任务卡 + 影响范围 + 验证标准

否

coderef_arch_verify

四维对齐度评分(职责 40%+依赖 30%+业务 20%+健康 10%)+ 差距复检

否

coderef_gov_start

建档体检周期并导入差距为治理工作项

否

coderef_gov_close

收尾周期,输出完成率/剩余/复发/豁免统计

否

coderef_gov_issues

查询治理工作项(预置视图 open/all/high/recurred/rejected/archived/overdue/assigned/recent)

否

coderef_gov_transition

工作项状态流转 + 豁免

否

coderef_gov_report

体检报告 / 治理看板 / 项目总览(report 单期+跨期趋势;board 交互 HTML;overview 健康+架构+Wiki+人话解读+工作项总览;已合并原 gov_board)

否

coderef_gov_pipeline

治理自动流水线:在途项 → 任务卡 → 复验 → Verified/附缺口

否

coderef_dynamic_probe

动态探针:静态挖掘动态信号(动态导入/装饰器注册/间接索引),零执行被检项目

否

coderef_gov_board

治理 Web 看板(兼容别名,转发到 gov_report action=board)

否

coderef_gov_workspace

多代码库聚合治理

否

coderef_gov_schedule

定时体检:生成 run_cycle.py + 离期检查

否

coderef_role_boundary

符号级职责越界检测

可选

coderef_architecture

架构分析图谱 + 技术分区布局图(arch_layout_*,面向架构师/AI,非用户交付物)

否

coderef_docs

项目 Wiki 文档生成 + 子项目探测;重型,大仓单次可能 10 分钟以上,勿在合入门禁同步调用

是

coderef_docs_read

按需读取已生成 Wiki 正文(返回内容而非路径)

否

coderef_query

知识图谱结构化查询(9 种查询类型)

否

coderef_review

代码审查:diff 变更审查 / 新项目全量语义首查

是

coderef_frontend

前端交互审查(按钮/菜单静态枚举 + 6 维度审查)

是

coderef_report

聚合审计/图谱/Wiki 为自包含 HTML,index.html 即「项目评估台」(五 Tab:概览 / 架构 / 产品 / UX / 技术 + 健康记分卡;open_server 起回环服务)

否

coderef_audit_advisor

审计策略判定(增量/全量)+ 重点维度

可选

coderef_whitelist

白名单管理 + 核心模块规则配置

否

coderef_scope

统一范围层:.coderef/scope.json 持久化忽略规则(exclude_glob / ignore_lib / include_override),add 即返回生效验证回执;只作用于扫描检索,不影响 change_guard

否

coderef_plan

dispatcher 计划卡:意图 → 链步骤 / 预计工具数与时长 / 用户决策点,纯规划不执行

否

coderef_execute

dispatcher 执行链:逐步入闸门、违规自动补齐、需用户决策处暂停;默认后台返回 task_id

否

coderef_dispatch_status

dispatcher 任务状态:当前步骤、闸门命中与补齐记录、暂停决策点

否

coderef_dispatch_report

dispatcher 最终摘要信封:结论 + freshness + KL + owner_actions + 折叠的步骤索引

否

coderef_dispatch_metrics

观测聚合:闸门命中率 / 阻断 Top / 记忆命中率 / 新鲜度与刷新事件 / scope 生效 / dispatcher 结局(读 .coderef/audit_log)

否

coderef_task_status

后台任务状态查询

否

coderef_task_cancel

后台任务取消(协作式收尾)

否

coderef_version

轻量版本探针(只读、零副作用):秒级返回当前加载的版本号,无需 project_path,用于断言「进程加载版本 == 目标版本」,杜绝进程未重启导致的结果误判

否

coderef_eval

产出物语义评估(LLM-as-judge):给 CodeRef 自身的 LLM 产出物加语义质量门禁——4 个指标(answer_relevancy 相关性 / faithfulness 忠实度 / hallucination 幻觉检出 / coherence 连贯性)+ 软硬判定(硬指标一票否决,防致命错误被平均分稀释);action=assert 单条断言 / score 批量报告;只评自产,不评用户项目运行时产出

是

记忆引擎

工具

功能

需 LLM

coderef_memory

项目记忆层:sync 增量同步 / query 语义+结构查询 / status 覆盖度+盲区 / quality 质量评估+自动补全(4 工具合并)

否

coderef_operation_memory

操作记忆层:sync / query / find 定位工具约定陷阱 / status / recover 恢复关键工具位置 / export 导出 Markdown(6 工具合并)

否

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

创新识别引擎

工具

功能

需 LLM

coderef_innovation

识别项目创新设计 + 传播缺口,理想清单 vs 实际实现对照

是

coderef_asset

将验证过的设计固化 WorkflowAsset 资产(需 ≥2 处采用 + evidence 防污染)

是

coderef_replicate

复刻铺排:检测目标项目对某资产的采用缺口 + 生成复刻指引;确定性,不自动改代码

否

coderef_replicate_apply

复刻落地:把骨架 + 说明写入目标项目并生成 manifest;只落"确定性可给"内容,冲突默认不覆盖

否

coderef_asset_blueprint

把复刻铺排的确定性结论(entry_points / verified_findings)写回蓝图

否

coderef_registry

管理已知设计库(别名归一,解决 LLM 命名漂移)

否

coderef_innovation_review

创新复刻的 LLM 排查(是否真创新 + 复刻合理性);无 API Key 硬阻断

是

变更守护引擎

工具

功能

需 LLM

coderef_change_guard

AI 代码退化检测(建立在 git 之上)。guard 对比基线拦截退化 / ensure_git 自动建库 / anchor 锚定健康基线 / list_baselines 列出基线

否

coderef_change_report

把 diff 归纳为「人话版」变更说明(新增/修改/影响/风险)

可选

OWASP 合规

工具

功能

需 LLM

coderef_owasp

OWASP LLM Top 10 合规检测,LLM01-LLM10 逐类分级

否

人话解读平台

工具

功能

需 LLM

coderef_interpret

把确定性结论翻译成人话:health 健康总览 / dashboard(已归并评估台,直接返回其路径)/ wiki / prompt / assets

可选


设计特性

特性

说明

不修改代码

审计、图谱、诊断等分析只输出不执行;唯一例外:coderef_change_guard ensure_git 会在被测项目无 git 时 git init 并写本地身份配置(守护引擎运转前提,仅该项目本地配置,不写全局)

本地优先

分析完全在本地,审计和知识图谱无需网络,支持离线

隐私安全

LLM 密钥存 config/config.json(已 gitignore),不提交 Git

结构化输出

报告 Markdown,仪表盘 HTML,知识图谱 SQLite

检查点续跑

管线每 2 分钟保存进度,中断后可恢复

后台任务

长任务(audit / docs)异步执行,轮询获取结果

项目隔离

每个项目独立缓存,切换项目不互相干扰

开源友好

敏感数据集中 cache/ 与 config/config.json,删除即清理


产物地图:哪些给人看,哪些给 AI 用

CodeRef 会落很多文件,但用户只需要看两个入口。其余产物要么是详情页,要么是给编程 AI 消费的数据。

用户面(需要打开看)

入口

从哪来

看什么

项目评估台 <project>/.coderef/report/html/index.html

coderef_report

概览(结论)/ 架构(业务树 + 业务流程)/ 产品 F 轨 / UX U 轨 / 技术(原始分项 + 证据锚点 + 技术分区图);audit.html / kg.html / wiki.html 是它的详情页。按项目隔离,多项目交替跑不会互相覆盖入口

架构治理看板 gov_board.html / project_overview.html

coderef_gov_start(open_server=true) / coderef_gov_report

治理工作项流转、周期体检(L2 治理专用,与评估台定位不同)

架构画布:三种视图,前缀已分离

文件前缀

生成者

回答什么

arch_canvas_*.html

coderef_arch_canvas(arch_view)

业务树:入口 → 主功能 → 子功能 → 步骤

arch_flow_*.html

coderef_arch_canvas(arch_flow)

业务流程:泳道(角色)× 阶段(触发→校验→执行→落库→通知→交付)

arch_layout_*.html

coderef_architecture(canvas_generator)

技术视图:角色分区布局图,面向架构师/AI 排查结构,非用户交付物

给编程 AI 的数据(不需要人工打开)

文件

用途

.coderef/scorecard.json

健康记分卡(CI 门禁、AI 读分)

.coderef/product_fit.json / ux_fit.json

F 轨 / U 轨结论

.coderef/business_semantics.json

业务语义标注(actor / stage / handoff / value_node)

.coderef/audit_findings_<hash>.json

审计发现结构化产物(重渲染的输入)

workflow_graph_*.html / flow_canvas_*.html

调用链/数据流调试视图,供 AI 定位,非交付物

AI 直接取数据:coderef_arch_canvas(format="data")

不渲染 HTML,直接返回 tree + semantics(lanes 泳道分组 / edges 邻接 / clusters 连通分量聚类)——AI 读不了交互页面,需要的是可复现的结构数据

health_dashboard_*.html

默认不再自动生成(需 coderef_audit(with_dashboard=true));健康读数统一看评估台

interpret_dashboard_*.html

coderef_interpret(action=dashboard) 已改为直接返回评估台路径;仅评估台不存在时才兜底渲染

原则:用户面只有两个入口——项目评估台(代码健康 / 架构 / 产品 / 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 起已改为中文中性措辞,大幅降低误报概率。若仍误报:

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

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

  3. 如实告知审计 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 产物、判存标准、时间线机制)在设计上结合了以下开源项目方案:

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;需要商业授权的合作请与作者联系。

许可元数据说明:pyproject.toml 的 SPDX license 字段为 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      A 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.
      2
      741 PyPI
      1,463
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      14
      163 npm
      7
      Elastic 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      2
      Apache 2.0