ovecc

---

什么是 Ovecc

Ovecc 会读取一次你的代码仓库，并为其构建持久模型：涵盖每个文件、 导入、符号和调用。基于这个索引，它可以回答你对代码库提出的问题：

• 如果我更改这里，会造成什么影响？（impact）
• 依赖循环和紧密耦合在哪里？（query、summary）
• 有哪些重复代码、死代码或过度复杂的代码？（dupes、deadcode、health）
• 有哪些安全问题？哪些依赖存在已知 CVE？（security、audit）
• 哪些地方变动频繁？这段代码由谁负责？（hotspots）

它是一个架构数据库，可通过 CLI、CI 或编码 Agent 经由 MCP 调用确定性命令。

React 的依赖关系图由 ovecc export graph --html 渲染为单个文件，可直接打开，无需服务端或 CDN。

Agent 的成本

询问在 zod 中新增一个导入是否会闭合依赖循环，使用 Claude Sonnet 4.6：

	Token 数	成本
Agent 读取文件	528,865	$1.63
Agent + ovecc 经由 MCP	58,906	$0.22

单次运行、一个模型、一个问题；而 Agent 的运行结果并非确定。方法以及 ovecc 表现不佳的情况见 docs/benchmark/BENCHMARKS.md。

写下你的架构规则，并据此约束代码

大多数工具止步于读取代码。Ovecc 更进一步：你只需在一个小文件中写下 代码库的哪些部分可以依赖哪些部分，每次构建都会检查实际代码是否符合规则。

下面是一个小型应用的示例：

# .ovecc/architecture.toml
[[component]]
name = "api"
paths = ["src/api/**"]
depends_on = ["core"]              # the api may use core, nothing else

[[component]]
name = "features"
paths = ["src/features/**"]
depends_on = ["core"]
slices = true                      # and features may not import each other

[[component]]
name = "core"
paths = ["src/core/**"]
deny_capabilities = ["network"]    # pure domain: no fetch, no I/O
max_cyclomatic = 8                 # keep core functions simple

运行检查后，每项违规都会附上文件和行号：

$ ovecc architecture check

Divergences (1):
  [High] api -> features is not in the contract
    src/api/routes.ts:2 (../features/billing/service)

Slice isolation breaches (1):
  [High] features/billing -> features/users breaks slice isolation
    src/features/billing/service.ts:1 (../users/repo)

Denied capabilities used (1):
  [Medium] core uses denied capability 'network'
    src/core/pricing.ts:3 (fetch)

Complexity budgets exceeded (1):
  [Medium] core: 1 function over the cyclomatic budget
    src/core/pricing.ts:8 (cyclomatic 11 > 8)

一次运行即可捕捉四种架构退化：某一层越界依赖、某个功能与相邻功能纠缠、 你承诺为纯代码的部分却发起了网络调用，以及某个函数的规模逐渐超出你设定 的预算。将 ovecc architecture check 加入 CI，一旦架构偏离，拉取请求就会失败；不必等到几个月后由审查者 发现，也不必冒着无人发现的风险。

还没有架构规则？ ovecc architecture suggest 可以识别你已采用的架构 （Feature-Sliced、bulletproof-react、Clean/Hexagonal、Nx 工作区），并根据 实际文件夹生成规则文件。你也可以运行 ovecc architecture init，根据实际导入关系图生成初稿，让项目从第一天起就通过检查， 再逐步收紧规则。详情请见下方的契约参考。

安装

npx ovecc index .

npm 只会下载适用于你平台的二进制文件。npm i -g ovecc 会将它保留在你的 PATH 中。

预编译二进制文件也可在最新版本中获取：Linux x86_64 和 aarch64、Windows x86_64、macOS arm64。无需安装其他内容：DuckDB 已打包其中，没有运行时依赖，并且可完全离线运行。每次推送到 main 时都会发布一个滚动更新的 dev 构建。

macOS 二进制文件未经签名，因此浏览器下载后会被 Gatekeeper 隔离。清除一次标记即可运行：

xattr -d com.apple.quarantine ./ovecc-macos-aarch64

curl 和 npm 不会设置该标记，因此 npx ovecc 不会遇到这个问题。

从源代码构建

使用 stable Rust 构建（在 Windows 上使用 windows-gnu 工具链；DuckDB 会在首次构建时从源代码编译）。Windows 的分步设置说明见 docs/dev/SETUP.md。

cargo build --release
cargo test --workspace

二进制文件为 ovecc（crates/ovecc-cli）。

快速入门

ovecc index .                 # parse, resolve, and persist the model into .ovecc/
ovecc summary                 # coupling, density, cycles, risk score
ovecc advise src/server.ts    # the agent-facing surface: findings for one file, each with a fix
ovecc diagnose                # named architectural smells, evidence + curated remediation
ovecc history max_cyclomatic  # trend one metric across every index run — is it getting better?
ovecc violations              # architecture + security findings, with file:line
ovecc violations --write-baseline   # accept today's backlog; later runs surface only what is new
ovecc metrics                 # per-component fan-in/out, instability, abstractness, distance
ovecc components              # the components the graph recovers, and what they hold
ovecc coupling                # files that change together but do not import each other
ovecc security                # secrets, insecure patterns, weak crypto, tainted flows
ovecc audit                   # offline OSV dependency vulnerabilities
ovecc impact Billing          # blast radius of a change
ovecc hotspots                # churn x coupling x ownership debt ranking
ovecc dupes                   # duplicated code (clone families), with file:line
ovecc health                  # functions over the complexity thresholds (oxc)
ovecc deadcode                # unused exports + unreachable files (oxc + reachability)
ovecc fix                     # apply the mechanical fixes for those findings (dry-run by default)
ovecc query "cycles"          # real elementary dependency cycles (A -> B -> A)
ovecc report                  # one-shot architecture report (markdown or json)
ovecc gate                    # CI gate: fail a PR on new cycles / violations
ovecc review                  # the named new defects a change introduced (file:line + cycle witnesses)
ovecc architecture init       # draft .ovecc/architecture.toml from the graph, or a --template
ovecc architecture check      # gate the code against the contract, with file:line
ovecc architecture suggest    # recognize which architecture the repo already follows
ovecc export graph --html     # interactive dependency-graph viewer, one self-contained offline file
ovecc capabilities            # machine-readable contract: commands, metrics, rules, exit codes
ovecc mcp                     # MCP server over stdio: expose every command as an agent tool

如果你只会运行其中的三个命令，那么请在编辑文件前运行 advise，用 diagnose 代替 violations（发现结果相同，还会提供修复建议以及何时不该采取行动），并运行 history 查看代码库是否在改善。summary 会将这些内容作为页脚打印出来，因为只读一次的列表，不如每次运行时都能看到的输出有用。

每个命令都可通过 --format 输出为 text、json、ndjson 或 markdown（还支持 GitHub 代码扫描的 sarif 和 GitLab Code Quality 的 codeclimate），并返回稳定的 CI 退出码。包含实际输出的各命令完整参考见 docs/COMMANDS.md。对于拉取请求，仓库提供了一个可直接使用的 GitHub Action，用于索引 base 和 head，在 PR 上评论 review 发现结果，并根据严重程度设置门禁。

深入了解架构契约

.ovecc/architecture.toml 是以代码形式定义的预期架构。每个组件通过路径 glob 声明其包含的文件；depends_on 是该组件可导入内容的允许列表。ovecc architecture init 会根据现有依赖图生成初始草案， 因此每个条目都对应实际导入，第一天就能做到零违规。如果你倾向于采用已知架构形式，可以运行 init --template fsd（或 bulletproof-react、nx-workspace、 clean-architecture）来加入参考架构；与你的代码进行比对后，差异就会成为迁移计划。

之后，每次运行都会将代码与契约进行比对，并指出发现的问题：

• 偏离是指契约不允许的导入，
• 绕过是指跳过组件声明的公共接口的导入，
• 缺失是指已声明但从未实际使用的依赖。

另外三项检查会超越导入图进行分析（JS/TS）：

• slices = true 会隔离组件的子文件夹，使它们彼此不可见。这是 Feature-Sliced Design 和 bulletproof-react 背后的规则，并支持 FSD 的 @x 公共 API 例外机制。
• deny_capabilities 会禁止组件使用破坏纯性的环境能力：network、filesystem、storage、dom、process、time、random。纯领域中的 Date.now() 会显示对应的文件和行号。
• max_cyclomatic / max_cognitive 会在契约中为每个函数设定复杂度预算，从而让“保持核心简单”成为构建时可检查的规则。

接口是虚拟的：你只需列出组件的公共入口文件，ovecc 就会检查实际导入，因此无需 barrel 文件或额外的重新导出层，也能实现封装。

采用过程应循序渐进。check --freeze 会将当前违规记录到各组件的基线中（每行一条，便于分支合并），此后只对新增违规设置门禁，并在修复时删除相应条目，因此数量永远不会增加。Agent 可以在编辑前通过 ovecc architecture show <path> 或 ovecc_architecture MCP 工具读取契约。

规则

更简单、与语言无关的策略存放在 .ovecc/config.toml 中，在索引时强制执行，并显示在 violations（以及 gate CI 检查）中：

# Forbid a module-to-module dependency.
[[rules.boundaries]]
name = "billing must not depend on user"
source = "billing"
target = "user"
allowed = false
severity = "high"

# Ban imports by specifier pattern (exact, prefix*, *suffix, or *infix*).
[[rules.banned_imports]]
name = "no-deprecated-lodash"
pattern = "lodash"
message = "use es-toolkit instead"
severity = "medium"

在违规行内使用 // ovecc-ignore（或 // ovecc-ignore-next-line，Python 中使用 # ovecc-ignore）即可忽略单条发现；该发现会在索引时被丢弃。

用于 CI 和编码 Agent

每条命令都可以在流水线中运行：使用 --format 选择格式，依赖稳定的退出码（0 表示无问题，1 表示超过 --fail-on 阈值，2 及以上表示实际错误），并为 GitHub 和 GitLab 输出 sarif 或 codeclimate。开箱即用的 GitHub Action 会将 review 集成到拉取请求中。

编码 Agent 也可以通过模型上下文协议使用相同的分析功能。ovecc mcp 会通过 stdio 运行 MCP 服务，并将每条命令作为工具公开 （ovecc_summary、ovecc_impact、ovecc_architecture 等），因此 Agent 可以询问 “这个导出项有被使用吗？”、“BillingService 的影响范围有多大？”或“这个 PR 会破坏架构约定吗？”，并得到相同的确定性答案。 使用任意 MCP 客户端注册它：

{ "mcpServers": { "ovecc": { "command": "npx", "args": ["-y", "ovecc", "mcp"] } } }

如果二进制文件已在 PATH 中，使用 "command": "ovecc" 和 "args": ["mcp"] 即可启动服务，无需通过 npm 查找。

从 ovecc capabilities --format json 开始：它会返回每条命令、这些命令输出的指标和规则（每项都附有定义）、严重性词汇表以及退出码约定，足以在不阅读本文档的情况下进行审计。每条命令的 JSON 都采用稳定的自描述封装，路径统一为相对于仓库的 POSIX 路径，并且每次运行结果的字节内容完全相同。完整演练见 docs/dev/MCP.md。

语言

JavaScript 和 TypeScript 系列使用 tree-sitter 解析，并通过纯 Rust oxc 技术栈增强：可解析真实的 tsconfig 路径和 exports（oxc_resolver），还可计算每个函数的复杂度并获取导出项 （oxc_parser/oxc_semantic）。一个 tree-sitter 适配器支持 Python、Go、Rust 和 C++。这些语言都会输入同一套与语言无关的模型，因此解析、调用图、污点分析和规则都适用于每种受支持的语言。添加一种语言，只需在解析器边界后新增一个提取器，无需修改核心部分。

工作区布局

十个库 crate 和一个二进制程序，各自的 README.md 中都有文档（另有 xtask，即 cargo xtask 背后的仅使用标准库的任务运行器）：

Crate	职责
ovecc-core	数据模型、类型化 ID、配置、错误类型、trait 契约
ovecc-parser	Tree-sitter 适配器和安全模式检测
ovecc-indexer	索引流水线：发现、解析、解析引用、分析、持久化
ovecc-db	DuckDB 持久化、迁移、差异同步
ovecc-git	原生 Git 历史、变更量、归属信息（通过 gix）
ovecc-graph	影响范围、热点、循环、约定
ovecc-rules	规则评估和安全分类
ovecc-dataflow	从源到汇的污点可达性
ovecc-audit	离线 OSV 依赖审计
ovecc-ai	可选的确定性离线说明
ovecc-cli	命令行界面

设计保证

• 先确定性，后生成式。 每条发现都可追溯到明确事实；相同输入会产生相同输出。
• 本地且私密。 索引、分析和说明都在本机运行；没有任何内容会离开本机。
• 增量处理。 对未更改的仓库重新建立索引时，不会重新解析任何内容，并且只会写入新的快照。

许可证

MPL-2.0；详见 LICENSE。除非文件本身带有不同的 SPDX-License-Identifier 标头，否则本仓库中的每个文件均受该许可证约束。带有不同标头的文件改编自 fallow，仍采用 MIT 许可证；第三方归属信息见 THIRD-PARTY-NOTICES.md。

截至 v0.2.5（含该版本）的发行版均以 Apache-2.0 发布，且仍可根据该许可证使用。