mcpField
C
CodeClone

CodeClone

本地服务
orenlab.github.io其他1216 周前更新
代码仓库访问官网

关于 CodeClone

CodeClone 是面向 Python 开发的确定性结构审查工具，通过基线对比识别变更引入的结构回归，适用于开发者、评审者及 CI。其 2.1 alpha 还提供 MCP 控制流程，约束 AI Agent 的变更范围并验证补丁。

主要功能

  1. 01分析重复代码、复杂度和耦合
  2. 02用基线区分既有问题与新回归
  3. 03生成多格式统一结构报告
  4. 04CI 检查结构变更和 API 破坏
  5. 052.1 alpha 提供受控变更和补丁验证

适用场景

  1. 01在 CI 中阻止新结构回归
  2. 02审查 AI Agent 是否超出声明范围
  3. 03查看模块依赖和结构热点

MCP 相关

CodeClone 提供只读 MCP 控制界面，2.1 alpha 版本还提供变更意图、影响范围、编辑边界及补丁验证等工具。MCP 响应包含确定性的后续工具指引。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "orenlab-codeclone": {
      "command": "uvx",
      "args": [
        "codeclone"
      ]
    }
  }
}
启动命令uvx codeclone

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypicodeclone2.0.3

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

CodeClone — 面向 AI 辅助 Python 开发的确定性结构变更控制器

面向 AI 辅助 Python 开发的确定性结构变更控制器

让 Agent 快速行动。
让结构变更明确、可控且可验证。

README 配图 README 配图 README 配图 README 配图 README 配图

README 配图 README 配图

重要

标记为 2.1 alpha 的部分需要使用 CodeClone 2.1 预发布版。 其他所有功能均可使用当前稳定版 CodeClone 2.0.2。

什么是 CodeClone？

CodeClone 帮助开发者使用 AI 编码 Agent，同时不失去对结构变更的控制。

在 Agent 编辑代码之前，CodeClone 会记录预期变更、绘制结构影响范围，并明确编辑边界。编辑完成后，它会将实际补丁与声明的范围进行比较，验证是否出现结构回归，并生成可审计的审查记录。

CodeClone 不会生成或重写源文件，也不会要求大模型判断结构变更是否安全。所有发现和门禁均基于确定性的代码库事实，并由各个 Agent、人工审查者、IDE、报告和 CI 共享。

功能提供的能力
规范化结构分析一份确定性报告：克隆代码、复杂度、耦合度、内聚性、死代码、模块图、API 清单、覆盖率关联
基于基线的治理记录已接受的历史债务，并将其与当前变更引入的回归区分开来
一份报告，多种呈现方式通过一份规范载荷提供 CLI、HTML、JSON、Markdown、SARIF、MCP、IDE 集成和 GitHub Actions
结构变更控制器 — 2.1 alpha以意图为先的变更控制、影响范围、明确的编辑边界、补丁验证和审查记录
实时实现上下文 — 2.1 alpha从当前分析运行中提供实时结构和调用图上下文，无需维护过时索引
工程记忆 — 2.1 alpha本地、类型化且关联证据的项目知识，以及可复用的受控变更历史
Agent 协调 — 2.1 alpha支持冲突安全的多 Agent 意图、队列、恢复和工作区维护

CodeClone 无需托管服务或云账户。分析状态、控制器状态、工程记忆和轨迹均存储在本地。

为什么意图先于差异

大多数审查工具都是在补丁已经存在后才开始工作。CodeClone 更早介入：

task request
  → declared intent
  → structural blast radius
  → explicit boundary
  → actual patch
  → deterministic verification

Agent 扩大范围后，在最终差异中看起来可能合情合理。一项范围狭窄的任务可能悄然扩展到共享辅助工具、 测试、配置、公共 API 或无关模块。

等到这种范围扩展出现在最终差异中时，它看起来已经像是有意为之。CodeClone 则在声明的 边界处捕捉这种扩展——通过比较 Agent 声称要修改的内容与实际修改的内容。

快速开始

需要 Python 3.10 或更高版本。

1. 分析代码库

无需安装，直接运行稳定版：

uvx codeclone@latest .

更喜欢可浏览的报告？生成 HTML 视图并打开：

uvx codeclone@latest . --html --open-html-report
CodeClone HTML 报告——结构健康状况、克隆发现和审查优先级

经常使用后，可将其安装为本地工具：

uv tool install codeclone
codeclone .
2. 记录当前结构基线

在要求 Agent 修改代码库之前，先记录一次已接受的状态：

codeclone . --update-baseline
git add codeclone.baseline.json
git commit -m "chore: add CodeClone structural baseline"

基线会记录现有的结构性债务。之后的分析便可区分新增回归 与原本就存在的问题，让 Agent 和审查者专注于当前修改引入的内容。

更新基线是一项明确的治理操作。不要仅仅为了让检查通过而重新生成基线。

3. 连接 AI Agent — 2.1 alpha

继续阅读下文的 Agent 变更控制，了解如何安装 MCP 控制界面，并将 CodeClone 接入 Claude Code、Cursor、VS Code、Codex 或 Claude Desktop。

一份规范的结构报告

CodeClone 运行一次确定性分析，并通过所有受支持的界面呈现相同的规范报告。

报告涵盖：

  • 函数、代码块和代码段克隆；
  • 克隆漂移和重复分支族；
  • 复杂度、耦合度、内聚度、依赖循环和死代码；
  • 模块图——包/模块依赖关系图，提供循环、枢纽、过载模块和拆解候选项视图；
  • 引导式发现审查——按优先级排列的审查队列，包含共享发现卡片、筛选器和进度跟踪；
  • 公共 API 清单以及支持基线的 API 变更检测；
  • 与结构热点关联的外部覆盖率；
  • 确定性的结构健康状况和审查优先级。
codeclone . --json --html --md --sarif --text

CodeClone 的工作原理 · 规范报告约定

支持基线的治理与 CI

基线是一份经过版本控制和完整性检查的约定，用于记录代码库已接受的结构状态。

它让 CodeClone 和已连接的 Agent 能够区分：

  • 已经存在的问题；
  • 当前更改引入的回归；
  • 经用户批准的基线有意更新。

对照已提交的基线检查后续更改：

codeclone . --ci

在 GitHub Actions 中使用 CodeClone：

- uses: orenlab/codeclone/.github/actions/codeclone@v2
  with:
    fail-on-new: "true"
    sarif: "true"
    pr-comment: "true"

CI 可以拒绝新引入的克隆、指标回归、API 变更和覆盖率回归，而无需先清理现有代码库。

基线约定 · CI 集成与质量门禁

CodeClone 的不同之处

Lint 工具逐个文件检查风格和正确性。克隆检测器会报告重复代码，但到此为止。托管式审查机器人会询问模型对已完成差异的看法。

CodeClone 将基于 CFG 的克隆检测、多指标基线治理和只读 MCP 控制接口整合在一个本地优先、开源的软件包中，并且在编辑之前应用这些机制，而不仅仅是在编辑之后。结构事实以确定性方式计算，因此相同输入始终会得出相同结论，无论是在终端、CI 中，还是在你的 Agent 循环中。

Agent 变更控制 — 2.1 alpha

安装 MCP 控制接口
uv tool install --prerelease allow "codeclone[mcp]"
codeclone-mcp --transport stdio

该服务提供 38 个 MCP 工具，涵盖分析、变更控制、影响范围、记忆和诊断。响应专为 Agent 循环而设计：提供确定性的 next_tool 指引、感知令牌预算的载荷，并在回复中内嵌必需的控制事实，同时链接完整证据以供深入查看。

在对 Agent 或 CI 启用门控之前，请确认 [tool.codeclone] 和本地 gitignore 配置是否规范：

codeclone setup status
codeclone setup plan
codeclone setup apply   # or: codeclone setup wizard

请参阅仓库设置与就绪状态。

接入你的客户端
客户端设置
VS Code扩展设置
Cursor插件与技能
Claude Code插件设置
Codex插件设置
Claude Desktop捆绑包设置

所有客户端都使用相同的 MCP 接口和规范的结构事实。

受控变更工作流

对于 Agent，常规工作流如下：

analyze → start → edit → finish

分析。 CodeClone 为仓库生成一份规范的结构报告，并将其与已接受的基线进行比较。

开始。 start_controlled_change：

  • 记录 Agent 的意图；
  • 映射结构影响范围；
  • 将可编辑路径与审查上下文和禁止触碰的边界区分开；
  • 显示相对于已接受基线的回归预算；
  • 返回权威的 edit_allowed 结果。

编辑。 Agent 编写代码。CodeClone 不会生成或改写源文件。如果宿主支持钩子，集成可以在 edit_allowed=true 之前阻止编辑。编辑期间，Agent 可通过实时实现上下文保持方向，而不必通过广泛搜索重新探索仓库。

完成。 finish_controlled_change：

  • 确定实际变更的文件；
  • 将声明的范围与实际补丁进行比对；
  • 验证结构变更；
  • 验证可选的审查声明；
  • 记录 Patch Trail 证据；
  • 生成可审计的审查回执。

如果补丁超出声明的边界，或引入的回归超过预算，验证就会失败，而回执会准确记录失败的位置和原因。结果并非 AI 对补丁的看法，而是对声明的意图、仓库结构、已接受基线和实际变更进行的确定性比较。

阅读《结构变更控制器》指南

实时实现上下文

get_implementation_context 会直接从当前分析运行中，为 Agent 提供有界且限定任务范围的上下文：

  • 已声明编辑范围的结构上下文和调用关系；
  • 面向契约的事实映射和测试锚点；
  • 新鲜度信号和当前意图边界。

代码背后没有单独的向量数据库，也没有监视守护进程重新索引代码树。上下文来自生成分析结果和门控的同一轮分析，因此 Agent 读取的内容就是验证器检查的内容。上下文为只读：它会为编辑提供信息，但不会授权编辑。

2.1 系列中也包含
  • 平台可观测性 — 在开发期间跟踪 CLI、MCP、分析阶段、数据库活动和负载压力，让你了解 CodeClone 本身在做什么，以及这些操作的成本。
  • 语料库分析 — 对记录的受控更改进行离线意图聚类和可解释性分析，并提供带版本的配置文件以及可检查的 JSON/HTML 输出。

工程记忆 — 2.1 alpha

工程记忆为 Agent 提供持久且针对特定代码库的上下文，同时不会将模型输出视为项目事实。

本地 SQLite 存储可以包含：

  • 架构和契约说明；
  • 风险、测试锚点和公共接口；
  • Git 和变更控制来源信息；
  • 以往的轨迹和 Patch Trail 证据；
  • 名为 Experiences 的重复出现的建议模式。

由 Agent 创建的记录在获得人工批准前会一直保留为草稿。

codeclone memory init --root .
codeclone memory search "baseline schema" --match all

检索采用混合方式——FTS5/BM25 词法搜索、可选的 LanceDB 向量搜索，以及通过 Reciprocal Rank Fusion 合并两者——并可完全复现排序结果。

记忆可以为 Agent 提供指引，但不能授权编辑、覆盖影响范围、改变门控或取代规范报告中的事实。

工程记忆文档 · 轨迹和 Experiences

信任边界

  • 结构性发现和门控来自确定性分析，而非 LLM 判断。
  • edit_allowed 是控制器给出的明确结果；状态或建议的归属关系不会授予权限。
  • 只读分析命令不会修改源代码或项目治理状态。
  • 更新基线属于明确且经用户批准的治理操作。
  • 控制器和记忆操作只会写入各自明确指定的本地状态存储。
  • 记忆、轨迹和实现上下文证据仅供参考。
  • stdio 是本地客户端的推荐传输方式。
  • 通过 HTTP 远程公开服务需要明确指定 --allow-remote。

贡献

欢迎提交错误报告、功能讨论和拉取请求——请从 Issues 或 Discussions 开始，也可以加入 Discord。

从源代码运行仓库版本：

git clone https://github.com/orenlab/codeclone.git
cd codeclone
uv sync --all-extras
uv run codeclone .

文档

orenlab.github.io/codeclone

许可证

  • 代码： MPL-2.0
  • 文档： MIT

请参阅 LICENSES.md 中的许可证范围映射。

Links

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。