Skip to main content
Glama
README.md
<!-- AI Summary: CodeRef-AI exposes 59 MCP tools that give coding AI a deterministic "audit brain" and give non-programmers a readable view of their project. It covers audit, knowledge graph, architecture diagnosis, flow verification, change guard, OWASP, deterministic verification, and prompt compliance — all pure static analysis that is reproducible with no LLM. LLM is only used for synthesis tasks (wiki, report, code review) and semantic evaluation (coderef_eval) and hard-blocks honestly without an API key. It ships three orchestration Skills (L1 probe / L2 governance / L3 asset) that turn the 59 tools into a compact chain. It builds a closed loop: deterministically verify LLM/CodeRabbit claims, govern legacy structure along a map→target→refactor→verify→health mainline, and solidify/replicate reusable design assets. Best for: non-programmers who use a coding AI and want to confirm their project runs as intended, and teams that want AI that augments rather than hallucinates. -->
[![MCP Badge](https://lobehub.com/badge/mcp/keaizuizui-coderef-ai?style=flat)](https://lobehub.com/mcp/keaizuizui-coderef-ai)

# 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](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 架构变动完成后将继续更新该功能。

---

## 它是什么

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 接入](MCP_SETUP.md#skill-接入让编程-ai-知道先做什么再做什么)。

---

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

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`:

```json
"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](docs/procedure-card.md) 返回 `procedure_card`(发布 SOP / 审计全流程 / CodeRabbit 位置)。该文件是一份**示例模板**,可直接复制到你自己的项目 `docs/procedure-card.md` 并替换成你的命令;它只是入口,完整细节仍以项目自己的规程为准。

### 结果级新鲜度硬戳(v5.19.1 起)

信封新增 `freshness` 块,滞后信息直接贴在结论上,调用方不查 `coderef_version` 也能看到:

```json
"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 免编译直接装好。

```bash
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:**

```bash
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):**

```bash
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

```bash
python -m core.mcp_server
```

### 4. 配置 MCP 客户端

在 Trae / Claude Desktop 等 MCP 客户端中添加(详细指南见 [MCP_SETUP.md](MCP_SETUP.md)):

```json
{
  "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/`:独立回归用例集,覆盖工具契约矩阵、提示词注入、极端输入、并发/多进程、多项目隔离、环境边界、版本回滚与各版本回归;全部在临时目录内运行,只读被测仓库。

运行方式:

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

- **mindmuxai/brain.md**(Apache-2.0)—— `BRAIN.md` 命名、「能否从代码重建」判存标准、「当前理解 + 时间线」结构。参考:[https://github.com/mindmuxai/brain.md](https://github.com/mindmuxai/brain.md)
- **TencentDB-Agent-Memory**(MIT)—— 分层记忆与渐进式披露,控制上下文 token 占用。参考:[https://github.com/Tencent/TencentDB-Agent-Memory](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](https://github.com/langchain-ai/openwiki)
- **tt-a1i/archify**(Apache-2.0)——「生成/校验分离」(LLM 产出 JSON-IR → schema 校验 → 确定性渲染)与 Last-good 门控(校验通过的产物备份,失败时保留上次可用版本)。参考:[https://github.com/tt-a1i/archify](https://github.com/tt-a1i/archify)

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

---

## 许可证

CodeRef-AI 从 **5.0** 起采用**双轨授权协议**([LICENSE](LICENSE)):兼容 PolyForm Noncommercial 1.0.0 的使用边界,并清晰界定「企业内部自用免费、禁止转卖」:

- **企业内部自用,免费**:企业团队用本工具协助自己的软件开发、排解编程困境(无论是否以盈利为目的的自研业务),**不属于「商业再分发」**,欢迎直接使用,无需付费或额外授权。
- **禁止转卖 / 对外提供 / 嵌入竞品**:**不得**将本软件(或衍生版本)直接出售、**作为服务/工具对外提供并收费**,或**作为竞争产品的部分**嵌入其他以售卖为目标的商业软件——即防止「拿本工具去卖钱」。若确实需要对外提供商业服务,请与作者联系另行授权。
- **非商业场景免费**:个人学习、研究、开源项目、非营利/教育/政府机构等非商业目的可自由下载、使用、修改、分发,无需付费。
- 完整许可文本见 [LICENSE](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](LICENSE-MIT-v4.md))。

---

## 贡献指引(Contributing)

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