codeweb

查看 AI 编辑会影响哪些内容。

npx -y @ghostlygawd/codeweb .

针对 AI 代码变更的结构检查。 codeweb 的门禁会构建变更前后的调用图，并在出现以下三种回归时使拉取请求检查失败：新增依赖循环、新增经函数体确认的重复代码，或现有的非导出符号变成没有映射调用方的孤立符号。门禁条件与限制。

检查过程中不会使用 LLM。静态分析门禁消耗零模型令牌。 检查通过并不能证明程序能够正常运行。分析可能遗漏动态关系； 请检查未解析结果并运行相关测试。纯删除不会违反结构规则。

判定依据是映射图，而非模型，且不消耗 LLM 令牌。导出符号不受差异中的孤立符号检查约束。请检查 analysis.checks：跳过的检查不代表通过，刷新会丢弃评估重复代码所需的证据。

绿色结果不能证明依赖关系已完整覆盖，也不能证明行为正确。 纯删除不计为结构回归。 将门禁用于你的 PR →

门禁需要一张映射图进行比较，而这张图本身也值得一读。

codeweb 会读取你的代码，映射受支持的函数及可解析的函数调用。它能在约 3 秒内映射 3,000 个符号。相同的代码总会生成相同的静态分析结果。映射过程不使用 LLM。

静态提取可能会遗漏不受支持的布局、 有歧义的调用以及运行时分派；映射图不保证完整。

你的编码 Agent 可以查询映射图，而不必使用 grep。在实测中，使用 grep 的 Agent 漏掉了某个函数一半以上的实际调用方 （查看测量结果）。调用方列表不完整，可能导致 Agent 破坏未检查的代码。

• 为 Agent 提供结构化数据： Model Context Protocol（MCP）服务提供 28 个工具， 包括 codeweb_impact、codeweb_callers 和 codeweb_find_similar。
• 让答案保持精简： 每次查询都会返回有界的结构化答案。你的 Agent 可以将剩余上下文用于实现工作。
• 查看相同的数据： 交互式报告会展示提取出的代码库地图。

该地图还会展示单个文件中看不到的关系，包括 重复逻辑、死代码、热点和纠缠的领域。

---

在你的代码库上试用

cd your-project
npx -y @ghostlygawd/codeweb .

对于包含 3,000 个符号的代码库，首次生成地图大约需要 3 秒。打开 .codeweb/report.html 查看地图。

为每个拉取请求设置门禁

在 Codeweb 源码检出目录中本地运行判定；GitHub Action 可以在每个拉取请求上运行：

node scripts/ci-gate.mjs --base origin/main --target src   # exit 1 on a structural regression

门禁会分别基于拉取请求的基分支和头部分支构建图，然后进行差异比较。无论结果如何，它都会发布一条固定的结构审查评论，让审查者无需安装任何东西即可了解影响范围。

请将 Action 固定到发布标签，不要使用会变动的分支：浮动引用可能会在你不知情的情况下改变门禁的判定语义。将 codeweb-ref 也固定到相同标签，从而固定引擎版本。工作流 YAML、monorepo 矩阵形式以及所有输入都位于 docs/ci-gate.md。

想要托管式门禁——无需工作流 YAML、带缓存的基分支图，并保留组织内所有代码库的历史记录？这是付费服务 codeweb Teams 的规划范围，也是 免费边界的另一侧。自行运行将永远免费。

查看实际效果

下面的每张截图都展示了为 axios（280 个符号、7 个领域）生成的报告。 这些截图并非模型图。

codeweb 在 axios 中找到了 3 处真实重复，并排除了 12 处误报。请阅读 案例研究，或 查看实时地图。

在编写代码之前，了解修改会破坏什么

在实时地图中选择一个函数。地图会高亮显示该函数的影响范围，并展示修改可能影响的符号。

你的 Agent 可以在编辑代码前，通过 codeweb_impact MCP 工具获取相同的答案。

### 浏览整个系统

力导向图展示提取出的符号。你可以将符号折叠为领域。搜索、拖动、缩放或选择节点，即可追踪其调用方和依赖项。

发现 — 不再猜测该重构什么

Findings 选项卡会对重复代码、高度连接的热点以及可能的死代码进行排序。 选择一行，即可查看该符号的调用方和依赖项。

查看重复代码密度，以及领域之间的纠缠位置

Treemap — 每个区块的大小表示文件的代码行数。区块越亮， 其中重复的代码越多。利用亮色区块识别可能的整合目标。

Matrix — 矩阵展示领域之间的耦合关系。较大的非对角线单元格表示 强耦合。你可以合并这些领域，或在它们之间添加清晰的接口。

---

codeweb 在符号级别运行。它会映射函数、类、方法，以及它们之间的调用边和导入边。文件级扫描器可以显示两个模块相似。codeweb 则可以显示两个函数执行了相同的工作，识别它们的调用方，并计算合并的影响。

基准测试

• 编辑前查找调用方： 在 v0.9.0 效率试点中，在相同的上下文消耗下，Agent 使用 codeweb 找到了某个函数 74% 的实际调用方，而使用 grep 找到了 44%。漏掉调用方可能导致编辑破坏正常运行的代码。
• 计算更改的影响： 一次 codeweb 调用就返回了一个简短答案。在记录的对比中，模拟的图辅助 grep 循环使用的上下文大小是其 126 倍。这衡量的是上下文大小差异，而非 Agent 会话的总 token 节省量。
• 检测重复代码： codeweb 找到了所有人为植入的重复代码，且误报为零，包括重命名的副本。文本搜索找到的重命名副本为 0%。
• 检查确定性结果： 测试将 codeweb 与 TypeScript 编译器及其他独立实现进行了超过 490,000 次比较，结果完全一致。
• 快速映射和查询： 对包含 3,000 个符号的代码仓库，首次映射约需 3 秒。查询约需 0.1 秒。符号数量翻倍的代码仓库，映射耗时约为原来的 1.3 倍。
• 了解局限： 大幅编辑后重新映射可能需要更多时间。Agent 不使用 codeweb 也能成功完成简单任务。

方法、原始数据和各项声明的依据： 证据账本。从 Codeweb 源代码检出目录对自己的代码仓库运行基准测试：npm run bench -- <path>/.codeweb/graph.json。CI 会在每个 PR 上重新运行性能预算测试；如果已发布的数据被突破，构建就会失败。

codeweb 还会在本地记录活动统计。从 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

要评估某个依赖项，请让 codeweb 检查一个不属于你的代码仓库： /codeweb https://github.com/owner/repo。codeweb 会创建一个只读克隆、映射该克隆，并添加一份采用评估。codeweb 不会执行目标代码。

安装

免费，采用 MIT 许可证。完全在你的机器上运行——无需账户、服务器，也不会收集遥测数据。会读取你的代码，但绝不执行代码。

• codeweb 需要 Node.js ≥ 22。
• codeweb 没有任何必需依赖。CI 会在空的 node_modules 目录中验证其运行情况。
• 可选的 web-tree-sitter wasm 语法文件可改进提取效果。codeweb 不要求安装它。
• CI 发布时会附带 npm provenance。运行 npm audit signatures 可验证发布内容。

使用 Claude Code？ 安装插件，即可添加 /codeweb 命令、自动的编辑前影响卡片，以及全部 28 个工具：

/plugin marketplace add GhostlyGawd/codeweb
/plugin install codeweb

重启 Claude Code 以注册 /codeweb 命令、Agent 和技能。

使用 Codex？ 安装捆绑的编码技能和本地 MCP 服务：

codex plugin marketplace add GhostlyGawd/codeweb
codex plugin add codeweb@codeweb

重新加载 Codex，然后使用 $codeweb 在编辑前检查调用方、比较现有实现，或审查结构性变更。插件使用你现有的工具权限。

该插件/MCP 工作流已通过 Codex CLI 0.159.2 和 0.160.0 验证。如果客户端未公开捆绑的工具，请使用下方的独立 MCP 配置方式，并搭配编码技能。停用或移除 Codeweb 时，请管理每个已配置的条目。此工作流不保证自动交付钩子。

选择你的 MCP 客户端：设置页面 为 Claude Code、Cursor、Windsurf、Gemini CLI 或 Codex 提供统一的配置方式。在项目中打印配置并检查本地设置：

npx -y @ghostlygawd/codeweb setup --client cursor
npx -y @ghostlygawd/codeweb doctor

设置流程会打印配置，不会替换文件。Doctor 会检查本地服务和图谱；本地检查成功并不能证明编辑器连接正常。重启客户端，让你的 Agent 运行 codeweb_callers，并检查返回的源码位置。

**不使用 AI Agent 映射代码库：**在项目目录中运行一条命令：

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

docs/cli.md 列出了每个可执行文件、标志和退出代码。

VS Code：editor/vscode-codeweb 会在每个已映射符号上方显示 N callers · blast M 透镜。选择该透镜即可打开报告。

可以做什么

每个链接都会跳转到**参考文档**中的完整文档、标志和示例。

• **编辑前先了解情况：**查找调用方、计算变更影响，并检查是否已有现成实现。 → 查询图谱 · 上下文与预检
• **为每次编辑设置门禁：**为编辑、拉取请求或架构规则获取结构性回归结果。 → diff 判定 · PR 门禁 · 能力测试套件
• **按证据排序清理任务：**根据证据为整合和死代码清理工作排序。 → optimize · 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 <glob>、--mode internal|external 和 --open。详情请参阅 commands/codeweb.md。

codeweb 会将所有输出写入 <target>/.codeweb/。Agent 和其他工具可以读取 graph.json。 你可以打开 report.html。codeweb 也会创建 Markdown 版本。 查看每个输出文件的说明。

将其用作 MCP 工具

scripts/mcp-server.mjs 是一个零依赖的 Model Context Protocol (MCP) stdio 服务。它为 MCP 客户端提供 28 个工具。这些工具可帮助客户端了解整体情况、读取结构、在写入前检查、 把关编辑并规划清理工作。

9 月 14 日的打包评估使用 Codex CLI 0.154.0 测试了基线循环；该评估并未认证每个客户端中的每个 工具。该评估未测试 Claude 运行时兼容性及其他客户端。 请参阅记录的范围。

插件会自动注册该服务。 若要注册独立服务，请运行：

claude mcp add codeweb -- npx -y -p @ghostlygawd/codeweb codeweb-mcp

需要 Codeweb 0.15.0 或更高版本。 使用已安装的 MCP 服务，或按照参考文档所示，使用其绝对路径注册源代码检出版本。

Agent 执行的循环：

1. 使用 codeweb_brief 了解整体情况（若不知道符号名称，则使用 codeweb_find）。
2. 编辑之前，调用一次 codeweb_refresh {baseline:true}，以获取最新源代码。 更改符号之前，先对其调用 codeweb_explain，然后调用 codeweb_context、codeweb_impact 或 codeweb_dependents。
3. 编辑之后，调用 codeweb_diff {before:"baseline",refresh:true}。
4. 如果结果为红色，修复代码，并针对同一基线重复相同的 diff。 修复期间不要重新采集基线：baseline:true 会替换原有基线。 普通刷新和自动刷新会保留基线。开始下一项任务时，请创建新的基线。

已知的不支持的同一行 JS/TS 声明会产生 status: "inconclusive" 和 ok:false，而非通过检查。请在源代码中检查诊断位置和调用方。 检测器涵盖已知布局；没有诊断并不能证明已完整提取。

请查看 analysis.checks：跳过的检查不等于通过。刷新会丢弃重叠证据，因此 此循环不会评估重复情况；结构检查显示绿色并不能证明行为正确。也请运行项目测试。如果缺少基线，就无法通过已编辑的源代码重建它——请在重新开始前恢复编辑前的源代码。

对于 npm v0.14.0，请使用快照快速入门。 对于尚未发布的检出版本，请尝试简短的循环 → 修复 → 通过演练。 如果客户端隐藏了服务内置的说明，可以改为粘贴 规则片段。

该服务包含以下针对 Agent 的功能：

• 可选的 graph 参数： 省略 graph 时，服务会查找最近的映射。如果不存在映射， 错误会提示 Agent 使用 codeweb_map。
• 限制响应预算： 响应会包含排名最高的项目及准确总数。原本约为 300 KB 的上下文 响应现在约为 10 KB。
• 过时信息： 过时结果会指出其状态，并提示 Agent 调用 codeweb_refresh——适用于整体了解工具以及每个生成的顾问答复。

全部 28 个工具，分组说明 →

工作原理

对于 JavaScript、TypeScript、Python、Rust、Go、Java、C#、Ruby、PHP、Kotlin、Swift、C 和 C++， codeweb 默认使用确定性 Node 流水线。一条命令即可生成映射。流水线中不包含大模型，且相同的输入会生成相同的字节。

映射流水线包含下图所示的四个阶段。scripts/run.mjs 还会在重叠分析之后、报告渲染之前生成 optimize.md。

1. 提取（extract-symbols.mjs）会将每个源文件解析为函数、类和方法等原子节点。它还会记录调用边和导入边。如果一个未限定的调用可能指向多个定义，codeweb 会省略该边，而不是猜测。逐文件缓存使提取过程可增量执行，且结果与完整重建逐字节一致。导入的 .json 文件会作为文件级节点进入映射，但不会被解析。未被引用的 .json 文件不会进入映射，从而避免锁文件造成的噪声。
2. 聚类（cluster3.mjs）会移除真正的工具型枢纽，并将其余节点分组为以目录为锚点的语义领域。
3. 重叠分析（overlap.mjs）会检测重复逻辑和平行实现。它通过标记词片相似度，将每个候选项与实际函数体进行比较。这项检查可避免将名称巧合误判为发现。对标识符归一化后的骨架进行结构分析，还能发现改名后的 Type-2 克隆（find-similar --structural）。
4. 渲染（build-report.mjs）会将 graph.json 转换为自包含的 report.html 和 report.md 文件。

对于提取器无法解析的语言，codeweb 会采用 Agent 路径。 codeweb-dissector Agent 会为每个子系统提取节点和边。随后，codeweb-domain-mapper 会分配领域并分析重叠。

两条路径都会生成相同的 graph.json 架构。在外部模式下，两条路径还会添加采用评估结果。

**与语言服务器（LSP）的比较：**LSP 会在编辑器会话中按需回答一步范围内的问题，例如定义和直接引用。codeweb 则会构建一个确定性的全图产物，提供传递影响分析、带有函数体证据的重复项检测、死代码检测和领域耦合分析。

Agent 通过 MCP 查询该产物，CI 则会对其进行差异比较，以决定是否允许 PR 合并。二者可以配合使用——codeweb 替代的是反复 grep 的流程，而不是你的语言服务器。

请在文档索引中选择阅读路径，其中也介绍了仓库所有权。组件映射详细介绍了引擎。

路线图

• **支持更多一等语言：**codeweb 目前原生支持十三种语言： JavaScript、TypeScript、Python、Rust、Go、Java、C#、Ruby、PHP、Kotlin、 Swift、C 和 C++。其他语言使用 Agent 回退方案。动态分派 AST 层级涵盖 JS/TS、Java、C#、Python、Go、Rust、Ruby、PHP、C 和 C++。Kotlin 和 Swift 的分派需要使用固定 ABI 中受信任的 wasm 语法。请参阅 scripts/grammars/PROVENANCE.md。

近期版本新增了 Agent 智能套件（hotspots、campaign、 reading-order、Type-2 克隆检测和抑制记忆）、一个 实时交互式演示、快速路径中的 Go 和 Rust、重复趋势数据，以及一条配有 GitHub Action 的单命令 CI 回归检查门禁。 codeweb 目前提供 28 个工具。

版本管理与发布

以下维护命令需要检出 Codeweb 源代码。

codeweb 遵循语义化版本。它在 CHANGELOG.md 中记录变更，该文件采用 Keep a Changelog 格式。每项功能、基准测试和修复都会通过带标签的 GitHub 发布版本推出。

package.json 是版本号的唯一可信来源。 scripts/mcp-server.mjs 是 MCP 工具数量的唯一可信来源。发布工具会推导并验证其他值：

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 中运行。它会检查各处的版本号、工具数量和语言数量的已识别说明文本模式、当前版本对应的 CHANGELOG 条目，以及账本引用的所有证据文件。

关于

由 GhostlyGawd 构建。AI Agent 协助编写了大部分代码。提交中的共同作者标记注明了这些贡献。如有问题或疑问，请提交 issue。请通过 SECURITY.md 报告安全问题。

保持更新： codeweb 不会联系更新服务。要接收发布通知，请在 GitHub 上选择 Watch → Custom → Releases。

永久免费，以及付费边界

CHARTER.md 中批准的规则是：凡是在一台笔记本电脑上针对一个仓库运行的内容，永久免费；付费购买的是托管、多仓库聚合和人工支持。

此仓库中的所有内容都属于免费部分——地图、MCP 工具、钩子、报告、CLI、可自托管的门禁 Action，以及 codeweb 支持的每种语言。采用 MIT 许可，无需账户、无遥测、无许可证密钥。此处的任何内容以后都不会转为付费。

计划中的付费部分是独立的托管服务 codeweb Teams：由服务为你运行门禁，并在组织中的所有仓库间保留历史记录。计费仅在该服务中进行，因此付款问题只会影响托管层，绝不会影响你的本地工具或 CI。

此仓库的本地检查无法确认托管服务是否可用。定价页面保留了注册入口。

请阅读边界页面中的完整约定，以及定价页面中计划的 Teams 价格。

支持此项目

赞助可以支持此项目。赞助也会提供广告展示。顶级赞助者可以将其徽标放在此 README 顶部，每位赞助者都可以加入支持者名单。详情请参阅支持页面。

在组织中运行 codeweb 并需要帮助？请通过 GitHub 个人资料发送电子邮件。

后续衔接

如果你有 refactor-cleaner、codebase-onboarding 或 code-tour 这些工具，可以将 codeweb 的输出交给它们。codeweb 并不依赖这些工具。

接下来可以应用 optimize.md 中排名最高的就绪合并项。然后再次运行 codeweb，并比较发现数量。