GhostlyGawd/codeweb
GitHub: GhostlyGawd/codeweb
codeweb 通过确定性的调用/导入图为 AI 编程代理和开发者提供代码影响分析、重复检测和死代码发现能力，让代码变更在编写前即可预知破坏范围。
Stars: 0 | Forks: 0
[](https://github.com/GhostlyGawd/codeweb/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@ghostlygawd/codeweb)
[](LICENSE)
[](#how-it-works)
[](#use-it-as-an-mcp-tool)
[](https://github.com/sponsors/GhostlyGawd)
**你的编码 agent 在 grep。codeweb 深知其中奥秘。**
**免费且基于 MIT 许可证。完全在你的本地机器上运行——无需账号，无需服务器，无遥测。读取你的代码；绝不执行它。**
DETERMINISTIC · READ-ONLY · ZERO-DEPENDENCY
每一个重大的变更都始于同样的问题：*谁在使用它？如果我修改它会破坏什么？
这个已经存在了吗？它已经是死代码了吗？* 如今，agent 通过 grep 和阅读整个文件来回答这些问题——每个问题消耗数千个 token，而且依然靠猜。codeweb 一次性映射代码库的调用/导入图（针对 3000 个符号约需 3 秒），随后在**几毫秒内精确回答这些问题，每个问题仅需约 1 KB 开销**——通过 **27 个确定性的 MCP 工具**（MCP 是像 Claude Code、Cursor 和 Windsurf 这样的编码 agent 用来调用工具的开放协议；codeweb 的闭环中不涉及任何 LLM）以及一个**为你准备的独立交互式地图**。
在 [vite](https://github.com/vitejs/vite)（3000+ 个符号）上进行测量，并由 TypeScript 编译器作为独立裁判进行评级（[`bench/results/oracle-ab.json`](bench/results/oracle-ab.json))：
| 问题 | codeweb | grep |
|---|---|---|
| *"谁依赖于 X？"*（30 个符号） | **100% 编译器验证的文件，比 grep 具有更好的精确度，仅需 0.7 KB，一次调用** | 命中 100% 的文件，但消耗 3 倍的 token，输出为 agent 仍需阅读的原始文本行 |
| *"如果我修改 X 会破坏什么？"* | **一次约 1 KB 的回答** | 缺乏传递操作符：约 5 轮递归，**消耗 126 倍的 token** |
| *"这个已经存在了吗？这是死代码吗？我的编辑破坏了结构吗？"* | 每次调用即可回答（`find_similar` / `deadcode` / `diff` gate） | 无法通过搜索回答 |
不要只听 vite 的一面之词——**在你自己的代码库上运行同样的裁判**：
`npm run bench --
/.codeweb/graph.json`（衡量上下文成本；由 TypeScript 编译器在解析 `typescript` 的地方评估召回率/精确度——与已发布结果使用相同的引擎）。
在针对 v0.9.0 预算响应（即 agent 实际收到的回复）的前沿 agent A/B 测试中，codeweb 在同等 token 成本下将调用者发现召回率提升了 **+0.31**（所有 5 次引擎冻结重复测试均为正面结果）。而副产品正是你能看到的那个部分：地图还能浮现**代码重复、死代码、热点以及混乱的领域**——即你的代码库在哪里重复造轮子，这是你或 agent 从单个文件内部都无法察觉的。
**[官方网站](https://ghostlygawd.github.io/codeweb/)** · [查看实际效果](#see-it-in-action) · [安装](#install) · [使用](#use) · [面向 agent (MCP)](#use-it-as-an-mcp-tool) · [工作原理](#how-it-works) · [更新日志](CHANGELOG.md)
## 查看实际效果
一条命令即可运行整个确定性流水线，并在 `
/.codeweb/report.html` 生成交互式地图。**下方的每一张截图均来自实际生成的报告**，codeweb 以只读方式指向 **[axios](https://github.com/axios/axios)**——横跨 8 个领域的 274 个产品符号（默认隐藏测试和工具）。非模型图；可随时使用 `node scripts/screenshot.mjs` 重新生成。
### 在编写代码前，预知修改会破坏什么
这正是其核心所在。提问*如果我修改了这个函数，还有什么会受影响？*——codeweb 会基于代码结构回答你，而不是靠猜。点击 [动态地图](https://ghostlygawd.github.io/codeweb/) 中的任意节点，其**影响范围**便会高亮显示：每一个受传递影响的函数，以及它所跨越的领域。这就是 `codeweb_impact` 工具——与 agent 在编写一行代码之前通过 MCP 获取的答案完全相同。
Selecting AxiosError in axios lights up its 58 users across the areas that depend on it — try it yourself in the living map.
### 浏览整个系统
一张包含每个符号的力导向图，可折叠至各个领域。支持搜索、拖拽、缩放，点击任意节点即可追踪依赖于它的内容以及它能触达的内容。
### 分析结果——停止盲目猜测重构目标
按排名显示的**代码重复**（在多个文件中定义的相同函数）、需要谨慎修改的最受依赖的**热点**，以及可能的**死代码**——每一行均可点击，以检查调用它的内容和它调用的内容。
### 查看重复代码密度，以及领域相互纠缠的位置
Treemap — every file sized by lines of code; the brighter red a block, the more of it
is duplicated. The bright blocks are your consolidation targets, at a glance.
|
Matrix — area-to-area coupling. A big off-diagonal cell means two areas are tangled:
merge them, or put a clean interface between them.
|
The deterministic pipeline, looping: extract → cluster → overlap → render.
codeweb 是缺失的**原子级分析 + 重叠检测侦探**层。当 `repo-scan` 对*文件*进行分类并标记重复*模块*，且 `codebase-onboarding` 编写高层架构文档时，codeweb 在**符号粒度**上工作：函数、类和方法，它们之间的调用/导入边，每个符号所属的语义领域，以及跨领域的重叠图。
## 经验证有效——基于测量，而非空谈
我们不仅仅是断言 codeweb 有效；我们**预先注册了假设并对其进行了测量**，应用了与 codeweb 用于代码的相同严谨度：独立基准、锁定的跨语言语料库、置信区间和对抗性审查。**33 项预注册检查中有 32 项通过**
（[逐项检查的完整记录](bench/preregistration.md)，冻结的注册信息保存在 `v0.8.0` 标签中以提供时间戳证明）——并且测试足够严谨，能够**发现并修复了两个真实的 bug**，这是引擎自身的 286 个测试套件所遗漏的。
- **面对独立基准依然保持正确性**——**在 >490,000 次对比中未观察到任何分歧**（循环、影响范围、调用者/被调用者、context-pack）；在 20,000 次编辑安全试验中违规次数为 0。
- **检测结果准确**——完全相同的克隆 **F1 1.0**（对比名称匹配的 0.67），重命名克隆的召回率**结构化为 1.0 对比词法化为 0.0**，复用排序 **MRR 0.99**。
- **扩展性良好**——运行时间呈**低于二次方**增长（在此语料库中呈次线性增长，b=0.33）；在包含 3,201 个符号的图上，结构化查询约需 **~95–120 ms** 即可返回结果；零必须依赖。
- **诚实透明**——唯一一项未通过的及格/不及格指标（高变动频率下的增量加速）已作为测量的曲线如实报告；agent A/B 的压轴测试返回了无效结果（在清洁任务上没有提升空间），并已如实说明。
- **并且它在前沿 agent 上有可量化的提升**——在针对 agent 实际接收的预算响应上运行的 v0.9.0 发现试点发现，codeweb 在同等 token 成本下将调用者发现**召回率提升了 +0.31 ± 0.04**（所有 5 次引擎冻结重复测试均为正面结果；精确度 +0.23 ± 0.08——
[`bench/experiments/efficiency-pilot.reps5-v090.json`](bench/experiments/efficiency-pilot.reps5-v090.json))。
早期在另一个基础模型上进行的 8 次重复运行也显示工具调用减少了约 34%，token 减少了约 44%；这些节省**在当前的节俭型基础 agent 上未能复现**，我们如实报告了这一点，而不是引用更好看的数据。难度更高的编辑质量压轴测试依然是一个诚实的无效结果。
并且 codeweb 在实际工作中产生的价值是在其积累之处计算的——严格限定的局部结果账本（`npm run stats`，在每次会话简报中展示）会输出形如以下的记录：
```
codeweb this month: 41 pre-edit card(s) · 5 card-named caller(s) followed · 2 regression(s) flagged · 120 queries served
```
## 两种模式
- **Internal（内部）**——映射你自己的代码库并寻找重构整合的机会。
- **External（外部）**——*只读*克隆第三方代码库（例如你在 GitHub 上发现的 Claude Code 插件），对其进行全面映射，并在决定使用之前进行采纳评估。codeweb 绝不执行目标代码。
## 安装
**免费且基于 MIT 许可证。完全在你的本地机器上运行——无需账号，无需服务器，无遥测。读取你的代码；绝不执行它。** 零必须依赖项——它可以在空的 `node_modules` 上运行（已通过 CI 验证）；你需要 **Node.js ≥ 22**。一个*可选的* wasm 语法（`web-tree-sitter`）在存在时可增强提取效果，且从不强制要求。发布版本由 CI 发布并附带 **npm 出处**——使用 `npm audit signatures` 验证任何安装。
**在使用 Claude Code？** 该插件会添加 `/codeweb` 命令、环境感知的编辑前影响卡片，以及全部 27 个工具：
```
/plugin marketplace add GhostlyGawd/codeweb
/plugin install codeweb
```
然后重启 Claude Code，以便 `/codeweb` 命令、agent 和技能完成注册。
**在使用 Cursor、Windsurf 或其他 MCP agent？** 注册同一个零依赖的 stdio 服务器（此处展示的是 Claude Code 的语法——替换为你所用客户端的添加服务器命令即可）：
```
claude mcp add codeweb -- npx -y -p @ghostlygawd/codeweb codeweb-mcp
```
**只想要地图——不想涉及 AI？** 在你的项目目录下运行一条命令：
```
cd your-project
npx -y @ghostlygawd/codeweb . # ~3 s for 3,000 symbols — then open .codeweb/report.html
```
*不确定？运行 npx 这一行命令即可——这就是完整的地图，无需安装，也不用撤销任何操作。*
**或者通过克隆仓库运行引擎：**
```
git clone https://github.com/GhostlyGawd/codeweb.git
node codeweb/scripts/run.mjs /path/to/your/project # map lands in /path/to/your/project/.codeweb
# 首先试运行捆绑的示例代码（无风险，约2s）：
node codeweb/scripts/run.mjs codeweb/bench/corpus/flask --out-dir /tmp/flask-map
```
需要 **Node.js ≥ 22**——整个确定性流水线（提取 → 聚类 → 重叠分析 → 渲染）均在 Node 上运行，无任何外部依赖。静态分析工具（universal-ctags、ripgrep、madge 等）是*可选的*——它们仅用于增强 agent 的回退路径；默认引擎会直接读取代码。
**在你的编辑器中：** [`editor/vscode-codeweb`](editor/vscode-codeweb/) 是一个零依赖的 VS Code 扩展，它会在每个映射符号上方显示 **`N callers · blast M`** CodeLens（由最近的 `.codeweb/graph.json` 提供数据，数值与 `codeweb_callers`/`codeweb_impact` 相同），并支持点击跳转到交互式报告中。
## 你可以做什么——三大任务
以下所有功能都服务于这三大任务之一。根据你的需求快速浏览；每一节都包含了完整的参数说明。
- **编辑前心知肚明**——谁调用了它、会破坏什么、这个是否已存在：`impact`、`context-pack`、`find`、`find-similar` 以及环境感知的编辑前卡片。
- **为每次编辑把关**——对编辑、PR 和架构规则进行结构化回归判定：`diff`、`ci-gate`、`review`、`fitness` 以及编辑后 hook。
- **基于排名进行清理**——以证据为导向排序的整合和死代码清理工作：`optimize`、`deadcode`、`hotspots`、`campaign`、`trend`。
## 使用
```
/codeweb # map the current project
/codeweb src/payments --depth symbol # deep-dive one subsystem
/codeweb https://github.com/owner/repo # external review before adopting
/codeweb owner/repo --open # clone, map, and open the report
```
参数：`--depth module|symbol|auto`、`--engine hybrid|read|tools`、`--focus `、`--mode internal|external`、`--open`。详见 `commands/codeweb.md`。
## 输出（位于 `/.codeweb/` 下）
| 文件 | 说明 |
|---|---|
| `graph.json` | 机器可读的网络结构：包含 `nodes`、`edges`、`domains`、`overlaps`，以及 `meta`（目标根路径、引擎、语言、统计数据）。 |
| `report.html` | 独立的交互式地图——力导向图、领域树、可点击的节点详情、按排名显示的重叠选项。无需网络/CDN。 |
| `report.md` | 以纯 Markdown 呈现的相同地图——包含领域、顶级节点、按排名显示的重叠。 |
| `overlap.md` | 以纯 Markdown 呈现的按排名显示的整合优化机会。 |
| `optimize.md` | 整合建议——将重复逻辑发现划分为 **ready / blocked / review** 三个等级，每项都预先通过了门禁的循环检查（即 `optimize.mjs` 报告）。 |
| `fragment.json` | 聚类之前的原始提取器输出（原子节点 + 边）——流水线的第一阶段。 |
## 查询图（供 agent 和人类使用）
一旦生成了 `graph.json`，`scripts/query.mjs` 就能回答 agent 在编辑前所需的结构化问题——只读、确定性强、闭环中无 LLM：
```
node scripts/query.mjs --impact # blast radius: transitive callers + domains touched
node scripts/query.mjs --callers # direct callers
node scripts/query.mjs --callees # direct callees
node scripts/query.mjs --cycles # file-level dependency cycles (SCCs)
node scripts/query.mjs --orphans # uncalled & unexported (dead-code candidates)
```
`` 是一个节点 ID（`file:label`）或单纯的标签（匹配多个节点的标签会作用于这些节点的并集，并在 `matched` 中报告）。添加 `--json` 以获得稳定、机器可读的输出。退出代码：`0` 表示成功（即使结果为空），`1` 表示未找到符号，`2` 表示用法/IO 错误。例如——*“如果我修改了状态存储，可能会破坏什么？”*：
```
$ node scripts/query.mjs .codeweb/graph.json --impact lib/state-store/index.js:get
impact of lib/state-store/index.js:get: 120 functions across 12 domains
```
## 保护 agent 的编辑（`diff`）
`scripts/diff.mjs` 会对比两份 `graph.json` 快照（编辑前 vs 编辑后）并标记出结构上的**回归**，因此它可以作为 PostToolUse 钩子或 CI 门禁来运行：
```
node scripts/diff.mjs [--json]
```
它会报告新增和移除的节点/边/重叠/循环/孤儿节点以及跨领域耦合度的变化，并在编辑引入了新的依赖循环、新的重复项发现，或者导致现有符号失去所有调用者时，**以退出码 1 退出**（并列出 `regressions`）。对于纯粹的删除操作，它会**以退出码 0 退出**——删除代码/循环/重复项是一种改进，而不是回归——而全新且未被调用的节点会被报告，但不会触发门禁（agent 通常会先添加函数，然后再进行连线）。
## 为每个 PR 把关（GitHub Action）
`scripts/ci-gate.mjs` 将 `diff` 门禁转化为 CI：它会分别构建 PR 基准分支和目标分支的图，并在**发生结构回归**（出现新循环、新重复项，或某个符号失去了所有调用者）时**使构建失败**。将其放入任何代码库中即可（完整规格说明见：[`docs/ci-gate.md`](docs/ci-gate.md))：
```
# .github/workflows/codeweb-gate.yml
on: pull_request
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 } # required — the gate diffs against the PR base
- uses: GhostlyGawd/codeweb/.github/actions/codeweb-gate@main
with: { target: src, comment: true } # comment posts the structural review on the PR
```
本地运行：`node scripts/ci-gate.mjs --base [ [--target ]`。纯粹的删除操作永远不会触发门禁；全新且未被调用的函数会被报告，但不会导致构建失败。
## 建议代码整合（`optimize.mjs`）
`diff.mjs` 负责对编辑进行*把关*（通过/失败），而 `optimize.mjs` 则负责*提供建议*：它会读取图中经过函数体确认的 `overlaps[]`，并将 `duplicate-logic` 发现按优先级排序为整合机会，**在提出每次合并建议前，都会预先对照门禁自身的循环检查进行校验**——全程无需修改一行源码。
```
node scripts/optimize.mjs [--json] # or set CODEWEB_WS
```
每个机会都被划分了等级：**ready**（函数体确认重合度 ≥60%，未发生偏移，且模拟合并保持无环 → 门禁会通过，重复项 −1），**blocked**（简单合并会引入新的文件间循环 → 门禁会拒绝它；需要一个中立的位置存放），或者 **review**（发生偏移的副本、仅具备结构相似性置信度，或非 `duplicate-logic` 的发现——需要人工/agent 进行判断）。置信度低或被证伪的发现会被直接排除。它会选出一个标准的存活项（被调用最多的，并以 LOC 然后是 ID 作为平局决胜规则），并报告移除了哪些副本、重新连线的调用者、影响范围以及回收的 LOC 代码行数。它**仅供参考**——从不编写代码，也绝不会在正常读取时返回非零退出码；是否合并始终由人类和门禁共同决定。
## 追踪代码重复的演变趋势（`trend.mjs`）
一次性的地图快照会告诉你当前的现状；而 `trend.mjs` 告诉你未来的走向——代码库正在整合还是变得分散？它会在多个快照间绘制**经函数体确认的重复代码**和**跨领域耦合**的变化趋势，并配有走势图和上升/下降的判定结论：
```
node scripts/trend.mjs --git --last 10 [--focus ] [--json] # snapshot the last N commits
node scripts/trend.mjs a.json b.json c.json [--labels …] [--json] # or chart pre-built snapshots
```
`--git` 模式会将最近 N 次提交逐一检出到一个**临时工作树**（对当前工作区是只读的）中，运行确定性流水线，并记录指标——这样你就可以一边观察重复率如何随着整合而下降，一边在代码审查中发现其悄然上升的趋势。
## 查找热点——应该从哪里开始重构（`hotspots.mjs`）
在庞大的代码库中，首要问题是*我到底该从哪里开始？* `hotspots.mjs` 通过 **复杂度 × 扇入 × 变更频率** 模型回答了这个问题——将风险最高、最受依赖、变更最频繁的符号排在首位。圈复杂度和最大嵌套深度是在函数体扫描期间计算得出的（每个 `function`/`method` 节点都带有 `complexity` 和 `maxDepth`），因此不需要额外的工具支持；变更频率是可选指标（`--git`，或者 `--churn `）。
```
$ node scripts/hotspots.mjs
codeweb hotspots: axios/lib — 253 symbol(s) ranked by complexity x fan-in x churn
weights: complexity 0.5, fanIn 0.3, churn 0.2
0.533 adapters/fetch.js:factory [cx 147 in 1 churn 0]
0.347 adapters/http.js:httpAdapter [cx 102 in 0 churn 0]
0.312 core/mergeConfig.js:mergeConfig [cx 33 in 6 churn 0]
0.270 helpers/toFormData.js:toFormData [cx 50 in 3 churn 0]
```
每一行都会显示其原始组成指标，因此排名是可审计的，而不是一个黑盒。添加 `--json` 以获取机器可读的输出；该功能也作为 `codeweb_hotspots` MCP 工具开放。
## 规划整体优化战役（`campaign.mjs`）
`optimize`（准备就绪的合并）、`deadcode`（安全的删除）和 `break-cycles`（已验证的切断操作）是三个独立的顾问。`campaign.mjs` 将它们组合成一个**按顺序执行、单独把关、并按 ROI 排序的工作列表**，并附带累积的预测增量——相当于“在任何规模下自动优化此代码库”。至关重要的是，每一步都经过了预检，以确保按**既定顺序**应用这些步骤绝不会引入原本不存在的循环：一场安全的战役其安全性体现在*作为一个序列*整体安全，而不仅仅是指单一步骤的安全。它是一个只读的计划——codeweb 绝不编写源码；由 agent（配合门禁）来执行每一步。
```
$ node scripts/campaign.mjs
codeweb campaign: axios/lib — 80 step(s): 2 cut, 77 delete, 1 merge
projected: -12 LOC, 2 cycle(s) broken (all steps stay gate-green in order)
[DELETE] adapters/fetch.js:duplex (roi 0; +0 LOC, +0 cycle; cumulative -0 LOC)
…each of 80 steps tagged [CUT|DELETE|MERGE] with its own gate verdict + cumulative delta
```
`--budget N` 仅保留 ROI 排名前 N 的前缀；`--json` 会输出每一步的 `{op, gate:{ok}, delta, cumulative, roi}`。同时也作为 `codeweb_campaign` 开放。
## 按依赖顺序进行上手阅读（`reading-order.mjs`）
为了快速了解一个代码库或某个领域，`reading-order.mjs` 会输出一条**基础优先**的阅读路径：先阅读被依赖的叶子节点，再阅读调用它们的编排逻辑，并在设定的预算范围内进行展示。这是一场精心策划的导览，而不是盲目地 grep。
```
$ node scripts/reading-order.mjs --budget 6
codeweb reading-order: 6 symbol(s) — read top-down (foundations first):
1. core/AxiosError.js:AxiosError
foundation — 18 in-scope caller(s)
2. cancel/CanceledError.js:CanceledError
foundation — 5 in-scope caller(s)
…
```
使用 `--scope domain|file|symbol ` 来限定范围；遇到循环时会优雅降级（根据扇入对成员排序，绝不会崩溃）。确定性强且只读；同时也是 `codeweb_reading_order` MCP 工具。
## 经过测量的覆盖率——“这个符号真的被测试到了吗？”（`coverage.mjs`）
`codeweb_tests` 会基于测试类型的调用边来回答（一种启发式方法）。如果向 codeweb 提供真实的覆盖率报告，答案就会变成**基于实际测量**的：
```
node --test --experimental-test-coverage --test-reporter=lcov > lcov.info # Node's own runner
node scripts/coverage.mjs .codeweb/graph.json lcov.info # or a c8/istanbul JSON
```
每个被插桩的符号都会获得 `covered`/`hits` 的状态事实，并且 `explain`、`--tests` 和 `context-pack` 的回答会在 agent 编辑未被保护的符号之前，明确说明 `已被记录的运行覆盖（最高 N 次命中）` 或者——最响亮的警示——`⚠ 未被记录的测试运行覆盖`。该功能可选且需明确开启（如果不提供输入，图文件保持逐字节不变）；`codeweb_refresh` 会丢弃过期的注释，并说明如何恢复它们。
## Agent 工具——上下文与预检（`context-pack`、`simulate-edit`）
两款只读工具，旨在将工作从 LLM 转移到图中（完整规格说明见：
[`docs/agent-tools.md`](docs/agent-tools.md))：
```
node scripts/context-pack.mjs [--json] # minimal context to edit
node scripts/simulate-edit.mjs --delete | --merge [--into ] | --move --to
```
`context-pack` 返回某个符号**基于影响范围作用域**的上下文——包括它的函数体、直接调用者（包含函数体的调用位置）、直接被调用者（仅包含位置信息），以及传递性影响集合（仅包含 ID）——从而让 agent 可以通过一个轻量级的视窗进行编辑，而无需阅读整个文件。`simulate-edit` 能够在不实际执行假设的删除/合并/移动操作的情况下，预测回归测试门禁的**结构性判定**（`{newCycles, lostCallers, ok}`），从而让注定会失败的编辑被低成本地放弃。这两者都共享 `graph-ops.mjs` 中纯粹的 `applyEdit` 原语，与 `optimize.mjs` 同源（保持单一事实来源），并且都有属性测试来保障工具输出与独立基准相一致。
## Agent 能力套件（编写 · 审查 · 优化）
一系列只读、确定性的工具，旨在让 agent 在这三大任务上表现更出色——每一项都有属性测试保障，与独立的基准相对齐（完整规格说明见：[`docs/agent-tools-v2.md`](docs/agent-tools-v2.md))：
| 工具 | 任务 | 回答的问题 |
|---|---|---|
| `find-similar.mjs --body/--stdin/--signature [--structural]` | **write** | “像这样的代码是否已经存在？”——根据 token-shingle 相似度对现有的函数体进行排序（或者，使用 `--structural` 参数，通过标识符归一化的*骨架*相似度进行排序，以捕获重命名/Type-2 类型的克隆），从而让 agent 复用而不是重新实现。 |
| `placement.mjs --calls ` | **write** | 一个新符号应该放在哪里（根据被调用者的引力推导领域 + 文件），以及它是否与现有代码重复。 |
| `query.mjs --tests ` | **write** | 哪些测试执行了某个符号——以便在编辑后运行正确的测试子集。 |
| `review.mjs --changed [--before g] [--gate]` | **review** | 将变更映射到对应的修改符号、影响范围、所属领域，以及按扇入排序的审查顺序；包含结构回归测试门禁。 |
| `fitness.mjs --rules codeweb.rules.json` | **review** | 检查架构的不变性（禁止的依赖、分层、禁止循环、扇入/LOC 上限）；违规即失败。 |
| `risk.mjs [--changed] [--churn/--git]` | **review** | 根据变更风险（扇入 × 扇出 × loc × 影响范围 × 变更频率）对符号进行排序，以供分类处理。 |
| `codemod.mjs --merge --into [--write]` | **optimize** | 规划一次整合合并（删除操作 + 重写调用者 + 预期的门禁校验）；`--write` 会在门禁校验下应用该操作，且过程可逆。 |
| `break-cycles.mjs ` | **optimize** | 针对每个依赖循环，找出成本最低且*经过验证*能切断它的那一条边。 |
| `deadcode.mjs ` | **optimize** | 将孤儿节点划分为可安全删除和需优先审查（受测试保护 / 类似入口点）两类。 |
| `annotate.mjs --suppress [--note …]` | **review** | 在 `.codeweb/annotations.json` 中记录误报抑制信息（绝不触碰源码）；随后 `overlap`/`deadcode` 会隐藏该发现，并报告一个 `suppressedCount`。指纹基于身份标识，因此一个真正的*新*问题绝无法隐藏在旧的抑制记录背后。 |
此外还包含**图新鲜度更新**：`extract-symbols.mjs --cache ` 仅重新扫描已更改的文件**并复用按文件缓存的边**（增量式的边推导，受全局符号集签名保护；`--full` 会强制进行从头开始的重建，其结果与增量构建逐字节一致），并且 `refresh.mjs ` 会从磁盘重新提取图中节点的边，确保编辑过程中的查询保持准确。节点现在包含一个 `signature`（参数/返回值），并且对于函数/方法，还包含 `complexity` 和 `maxDepth`；来自测试文件的属于一种独特的 `test` 类型（因此生产环境中的 `--callers` 不会包含测试代码）。以上所有功能也都通过 MCP 开放（见下文）。
## 将其作为 MCP 工具使用
`scripts/mcp-server.mjs` 是一个零依赖的 MCP (Model Context Protocol) stdio 服务器，它将 codeweb 的全部 **27** 种查询功能及能力套件暴露为工具，可供任何 MCP 客户端在任务执行期间随时调用：
`codeweb_map`（通过 MCP 构建/重建图）、`codeweb_brief`（首日代码库概览页——请最先调用它）、`codeweb_find`（概念搜索——支持将像 *“retry backoff”* 这样的自由文本排序列出相关的初始符号，无需知道确切名称）、`codeweb_callers/callees/impact/
cycles/orphans/diff`、编辑闭环工具 `codeweb_context/refresh`、智能分析工具
`codeweb_hotspots/campaign/reading_order`、预检与代码卫生闭环工具
`codeweb_simulate`（针对假设的删除/合并/移动操作返回门禁的判定结果——在任何编辑之前）、`codeweb_annotate`（误报抑制记忆，仅存放在旁路文件中）以及 `codeweb_stats`（本地价值收据），外加 `codeweb_tests/find_similar/placement/review/
fitness/risk/break_cycles/deadcode/codemod`（最后一个仅用于规划——不开放 `--write` 功能）。
**安装该插件会自动注册服务器**（`.claude-plugin/plugin.json` 包含 `mcpServers` 条目）。独立使用时——无需插件——可以从 npm（或克隆的仓库）注册它：
```
claude mcp add codeweb -- npx -y -p @ghostlygawd/codeweb codeweb-mcp
claude mcp add codeweb -- node /abs/path/to/codeweb/scripts/mcp-server.mjs # clone variant
```
或者在一个 `.mcp.json` 文件中：
```
{ "mcpServers": { "codeweb": { "command": "node", "args": ["/abs/path/to/codeweb/scripts/mcp-server.mjs"] } } }
```
专为 agent 打造，而不仅仅是让它们能够触达：
- **`graph` 在任何地方都是可选的**——服务器会自动解析其当前工作目录（或 `CODEWEB_WS`）上方最近的 `.codeweb/graph.json`。还没有图？错误提示会指明 `codeweb_map`，它会构建一个（针对包含 3k 个符号的代码库约需 3 秒），且整个过程无需离开 MCP。
- **默认提供预算控制后的响应**——返回大量列表的工具会回复一行简短的 `summary`、最相关的前 N 个项目、TRUE 总数，以及一个明确的 `more.remaining`；可通过 `full: true`（或 `limit`/`offset`）进行覆盖。以前在活跃符号上重达 ~300KB 的 `codeweb_context`，现在只需约 ~10KB 的调用位置视窗即可完成作答。
- **过期感知**——当图与磁盘文件不再匹配时，查询结果会明确指出这一点，并引导使用 `codeweb_refresh`。
- 握手过程中会携带 `instructions`，指导整个闭环的流程：*上下文获取 → 编辑 → 刷新 → diff 门禁校验*。
## 工作原理
对于 JavaScript、TypeScript、Python、Rust、Go、Java、C#、Ruby、PHP、Kotlin 和 Swift，默认采用**确定性的 Node 流水线**——一条命令，闭环中无 LLM，逐字节可复现。`scripts/run.mjs` 会将五个阶段串联起来，针对每个目标生成专属工作区：
1. **提取**（`extract-symbols.mjs`）——将每个源文件解析为原子节点（函数、类、方法）以及调用/导入边。未解析的单纯调用只有在名称毫无歧义时才会连接到全局定义；对于具有多个定义的名称，会丢弃该连接边，而不是凭空捏造一个错误的中心节点。每个函数/方法节点还会获得一个 `signature`（签名）、圈 `complexity`（复杂度）和 `maxDepth`（最大深度）；边按文件进行缓存（支持增量更新，与完整重建结果逐字节一致），从而加快刷新速度。
2. **聚类**（`cluster3.mjs`）——剔除真正的通用工具型中心节点，然后将节点归类到以目录为锚点的语义领域中。
3. **重叠检测**（`overlap.mjs`）——检测重复逻辑和平行实现，然后通过真实的函数体（token-shingle 相似度）对每个候选项进行确认，确保发现的结果是基于函数体内容的，而非仅仅因为名称巧合。基于标识符归一化的*骨架*进行的一次结构性扫描，还能捕获重命名过的（Type-2）克隆（`find-similar --structural`）。
4. **渲染**（`build-report.mjs`）——将 `graph.json` 转换为完全独立的 `report.html`（以及 `report.md`）。
对于提取器无法解析的语言（或者完全跳过确定性引擎时），codeweb 会**回退**到 agent 路径：并行的 `codeweb-dissector` agent 会针对每个子系统提取节点和边，这些片段通过节点 ID 合并为一张完整的图，随后 `codeweb-domain-mapper` 会标记领域并检测重叠。这两种路径输出的是完全相同的 `graph.json` 模式，因此聚类、重叠检测和渲染环节是共享的。在 **external** 模式下，无论选择哪条路径，最后都会附加一份采纳判定结论（风险、依赖关系、架构）。
## 组件构成
```
codeweb/
├── .claude-plugin/plugin.json
├── commands/codeweb.md # /codeweb trigger
├── scripts/ # the deterministic engine (default fast path)
│ ├── run.mjs # orchestrator — one command, runs all stages per target
│ ├── extract-symbols.mjs # stage 1: source -> atomic nodes + edges (JS/TS/Python/Rust/Go)
│ ├── cluster3.mjs # stage 2: hub-strip + directory-anchored domains
│ ├── overlap.mjs # stage 3: body-confirmed duplication/overlap detection
│ ├── build-report.mjs # stage 4: graph.json -> interactive report.html + report.md
│ ├── report-template.html # the renderer's self-contained HTML shell
│ ├── query.mjs # structural queries (callers/callees/tests/impact/cycles/orphans)
│ ├── diff.mjs # graph-delta / post-edit regression gate (before vs after)
│ ├── trend.mjs # duplication + coupling over snapshots / git history (dashboard)
│ ├── ci-gate.mjs # CI gate: before(base)-vs-after(working tree) diff, exits 1 on regression
│ ├── optimize.mjs # advise: rank body-confirmed dups into gated consolidation opportunities
│ ├── context-pack.mjs # agent context: blast-radius-scoped window to edit a symbol
│ ├── simulate-edit.mjs # agent pre-flight: predict the gate's verdict for delete/merge/move
│ ├── refresh.mjs # F0: re-extract a graph's nodes+edges from disk (cached, fast)
│ ├── find-similar.mjs # F1: rank existing bodies vs a candidate (reuse-at-write-time)
│ ├── placement.mjs # F2: suggest a new symbol's domain/file + reuse warnings
│ ├── review.mjs # F5: structural review of a change (blast radius, regressions)
│ ├── fitness.mjs # F6: architectural fitness-rule checker
│ ├── risk.mjs # F7: change-risk ranking for review triage
│ ├── codemod.mjs # F8: consolidation edit plan (+ gated/reversible --write)
│ ├── deadcode.mjs # F10: confidence-tiered dead-code workflow
│ ├── break-cycles.mjs # F9: cheapest verified cut per dependency cycle
│ ├── hotspots.mjs # rank symbols by complexity x fan-in x churn (where to refactor first)
│ ├── campaign.mjs # compose optimize+deadcode+break-cycles into one gated ROI worklist
│ ├── reading-order.mjs # foundations-first reading path for onboarding (bounded by budget)
│ ├── annotate.mjs # record false-positive suppressions in .codeweb/annotations.json
│ ├── mcp-server.mjs # MCP stdio server exposing all queries + the capability suite
│ └── lib/
│ ├── graph-ops.mjs # shared pure graph primitives (index, cycles, orphans, impact, reviewImpact, …)
│ ├── shingles.mjs # F1: shared token-shingle/jaccard (also used by overlap.mjs)
│ ├── skeleton.mjs # identifier-normalized skeleton for Type-2 (renamed) clone detection
│ ├── complexity.mjs # cyclomatic complexity + nesting depth (the hotspot inputs)
│ ├── dup-check.mjs # incremental duplication check over changed symbols (edit gate)
│ ├── annotations.mjs # finding fingerprints + false-positive suppression memory
│ ├── hotspots.mjs # the complexity x fan-in x churn blend (shared with tests)
│ ├── campaign.mjs # the ordered/gated/ROI campaign planner (pure)
│ ├── reading-order.mjs # foundations-first DAG linearization
│ └── risk.mjs # F7: the change-risk formula + weights (one truth)
├── agents/ # fallback path (unparseable langs / no deterministic engine)
│ ├── codeweb-dissector.md # atomic dissection (parallel, read-only)
│ └── codeweb-domain-mapper.md # domain tagging + overlap detection
├── skills/codebase-anatomy/
│ ├── SKILL.md # orchestration brain (fast path default, agents fallback)
│ └── references/
│ ├── graph-schema.md
│ ├── overlap-heuristics.md
│ └── engine-detection.md
├── assets/ # brand art (logo, hero, animated demo) + report screenshots
└── README.md
```
## 路线图
- **更多一等公民语言**——目前原生支持十一种语言（JavaScript、TypeScript、Python、**Rust**、
**Go**、**Java**、**C#**、**Ruby**、**PHP**、**Kotlin**、**Swift**）；其他所有语言均通过 agent 回退路径处理。动态分发的 AST 分层覆盖了 JS/TS、Java、C#、Python、Go、Rust、**Ruby** 和 **PHP**；Kotlin/Swift 的分发分析则需等待在我们锁定的 ABI 版本上受信任的 wasm 语法支持
（记录在 `scripts/grammars/PROVENANCE.md` 中）。
_最近已发布：**agent 智能套件**——重构**热点**（复杂度 × 扇入 × 变更频率）、受门禁控制并按 ROI 排序的优化**战役**规划器、基础优先的**阅读顺序**、**Type-2（重命名）克隆**检测、误报**抑制记忆**，以及不断扩展的 MCP 工具面（**目前已提供 27 种工具**） · 一个部署在 GitHub
Pages 上的 **[实时交互式演示](https://ghostlygawd.github.io/codeweb/demo/)** · Go 和 Rust 进入快速通道 · 代码重复演变趋势分析（`trend.mjs`） · 一键式 CI 回归门禁及 GitHub Action。_
## 版本控制与发布
codeweb 遵循 [语义化版本控制](https://semver.org/)，并维护着一份遵循
[Keep a Changelog](https://keepachangelog.com/) 格式的 [`CHANGELOG.md`](CHANGELOG.md)。每一项新功能、基准测试或修复都会记录在其中，并作为**带有标签的 GitHub release** 发布——产品、营销和研发齐头并进，永远不会迷失在提交历史中。
坚持单一事实来源以保持诚实可信。版本号存在于 `package.json` 中；MCP 工具数量的统计则存在于 `scripts/mcp-server.mjs` 中。其他所有内容都是派生并经过验证的：
```
npm run version-sync # propagate version + tool count -> plugin.json, SKILL.md, README badge
npm run check-consistency # fail if any public-facing surface has drifted
npm run build:site # regenerate the docs/ website (zero-dependency, deterministic)
npm run release -- --minor # roll the changelog, bump, sync, rebuild; prints the git/tag steps
```
`check-consistency` 会在 CI 中运行，将 codeweb 自身“回归即失败”的哲学应用于其对外沟通中。它实际把关的内容包括：各个界面上的版本字符串、派生得出的 MCP 工具数量（包括在 README、网站、技能说明和 npm 描述中以文字形式提及的工具和语言数量）、当前版本对应的 CHANGELOG 条目，以及账本中引用的每一个证据文件都必须在磁盘上真实存在。对于它无法覆盖的文字内容（如已经发布到 npm 上的说明页面），将在下一次版本发布时予以修正，届时会重新运行相同的检查门禁。
## 关于
由 [GhostlyGawd](https://github.com/GhostlyGawd) 开发。大部分代码是由 AI agent 协助编写的；提交记录中的 co-author 尾缀标明了具体的参与方。欢迎提出 Issue 和疑问。安全漏洞报告途径请见：[`SECURITY.md`](SECURITY.md)。
**保持关注：** codeweb 绝不会主动连接外部服务器。若希望了解新版本的动态，请在 GitHub 上关注 Releases（**Watch → Custom → Releases**）。
## 支持本项目
所有在你机器上本地运行的功能都将**永久免费**。没有账号、没有遥测、没有许可证密钥。
[赞助](https://github.com/sponsors/GhostlyGawd) 为开发提供了资金支持——主要用于覆盖基准测试带来的 AI 账单开销以及新语言的支持。详情请参见
[支持页面](https://ghostlygawd.github.io/codeweb/support.html)。
**企业级支持**：提供附带 SLA 的邮件支持、上手帮助以及对功能请求的优先处理。每年 **$3–6k**，仅限于少数客户。可通过 GitHub 个人主页上的联系方式进行沟通。
## 任务交接
如果你安装了这些工具，codeweb 的领域地图和重叠列表可以自然地融入到 `refactor-cleaner`（用于执行整合列表）、`codebase-onboarding`（使用领域地图作为指南）和 `code-tour`（将导览锚定到符号索引上）的工作流中。这些都不是必需的——如果没有它们，理想的第二步其实很简单：应用 `optimize.md` 中排名第一的 **ready** 合并项，重新运行 codeweb，然后看着发现的问题数量不断下降。]标签：AI编程助手, MCP, MITM代理, SOC Prime, 云安全监控, 代码地图, 开发工具, 自定义脚本, 调用图, 静态分析
