depwire

Depwire

你的 AI 不了解你的架构。Depwire 了解。

Depwire 有何不同

支持 16 种编程语言，另加 Angular 模板。Depwire 会解析符号，并在其支持的结构之间构建依赖关系。对于无法解析的关系，它会如实记录，而不是凭空创建依赖边。

Depwire 通过解析源代码构建确定性依赖图，不使用嵌入或相似度搜索。对于拟议的更改，它会遍历图中已有的关系，展示已知依赖项、导入链和健康度变化。结果取决于解析器可分析的语言结构和文件。

它也不是构建图。 Depwire 会跟踪符号级关系，用于 What If 模拟、图感知安全扫描和影响范围分析。

目录

• Depwire 的独特之处
• 性能证据
• 问题
• 从这里开始
• 基础设施层
• 在真实项目中的测试
• What If 模拟
• 安全扫描器
• 操作前验证
• 提交之间的结构差异
• 可视化
• 时间图
• 所有命令
• MCP 服务 — AI 集成
• 跨语言边检测
• 架构健康评分
• 语言支持
• SDK
• 云端仪表板
• VSCode 扩展
• GitHub Action — PR 影响分析
• pre-commit / prek 钩子
• Depwire 操作令牌 (DAT)
• 路线图
• 安全态势
• 路径和文件计数

---

Depwire 为 AI 编码助手提供图上下文。解析项目以检查已记录的关系、评估健康状况，并模拟拟议的更改。

⭐ 如果 Depwire 帮你避免了构建失败，请为仓库点星——这有助于项目发展。

---

性能证据

此前发布的 Agent 基准测试已撤回，因为审计发现，任务提示词暴露了答案，评分文件集的范围小于单体仓库所需更改的范围，并且其中一个测试组使用了不同的工作目录。此后已运行 3 次修正后的探索性会话；这些会话并不能证明在性能或正确性方面具有优势。不得引用已撤回测试得出的任何结论。

审计和修正后的测试框架 →

---

问题

AI 编码工具越来越智能，但它们仍有一个根本盲点：在动手之前，它们不了解你的架构。

例如，你让 AI 助手删除一个实用工具文件。它没有任何警告就把文件删了。

随后，构建过程才揭示仍在导入该文件的下游使用方。

助手只看到了一个文件，没有检查这些使用方。

这不是模型的问题，而是上下文的问题。AI 对此一无所知。

---

基础设施层

Depwire 是 AI 生成代码的上下文与安全层。

Depwire 使用 tree-sitter 根据受支持的源代码结构构建依赖关系图，并通过 24 个 MCP 工具将其提供给 AI 助手。

工作原理：

• 本地 — CLI 在你的机器上分析源代码，不收集任何使用遥测数据。它不会上传源代码、文件名、图数据或分析结果。适用的 security 扫描默认会运行依赖漏洞和供应链检查；这些检查可能会联系软件包注册表和公共安全公告数据库。提供 GitHub URL 时，connect_repo 会访问 GitHub。What If 浏览器页面会从 CDN 加载 D3。Cloud 是一项独立服务。
• 安全扫描器 — 默认运行本地代码检查和适用的依赖项审计；无需 Depwire API 密钥。
• 节省令牌 — Depwire 提供预先计算的图数据，让 Agent 能够请求重点依赖上下文，而不必获取大量文件内容。
• 确定性 — tree-sitter 提供一致的结构解析，不依赖模型推理。

---

从这里开始

npm install -g depwire-cli

为受支持的代码库提供的三个命令：

depwire whatif     # simulate a proposed change
depwire security   # scan for supported finding patterns
depwire viz        # view the recorded dependency graph

---

在真实项目上测试

项目	语言	文件数	符号数	边数	健康度
google/guice	Java（多模块，13 个模块）	647	30,592	10,081	31/100
honojs/hono	TypeScript	352	6,462	2,194	41/100
apache/commons-lang	Java（单模块）	624	29,723	9,037	—
pallets/flask	Python	79	2,005	851	—
dart-lang/shelf	Dart	108	1,639	219	—
rstudio/plumber	R	197	1,194	219	—
payloadcms/payload	TypeScript	645	9,292	3,511	—

在公开代码仓库上运行的历史 depwire parse 数据，最后一次验证使用的是 v1.8.2（2026 年 6 月）。

1.9.0 之前的测量结果。 v1.9.0 修复了解析器错误（TypeScript/Python/C#/C++/Java 解析器重复输出符号、丢弃仅类型导入的边、错误识别孤立节点），这些问题会直接影响符号数、边数和健康度评分。后续版本再次改变了图的内容和健康度计算方法。这些数据尚未重新测量，并非当前结果。

---

What If 模拟

在动手修改之前，了解影响范围。

depwire whatif . --simulate delete --target src/utils/encode.ts

在 honojs/hono 上的实际输出——352 个文件，6,245 个符号：

健康度评分：    41 → 41  （+0 → 不变）
受影响节点：    29
损坏的导入：    30
• src/utils/jwt/jwt.ts 导入 decodeBase64Url
• src/adapter/aws-lambda/handler.ts 导入 encodeBase64
• src/utils/basic-auth.ts 导入 decodeBase64
[另有 27 项……]
删除的边：      32

1.9.0 之前的测量结果——采集于 v1.9.0 修复解析器之前；尚未重新测量。

模拟会在已加载的图上运行，不会更改源文件；加载或解析图需要进行文件 I/O。

五种操作：

depwire whatif . --simulate delete --target src/utils/encode.ts
depwire whatif . --simulate move --target src/utils/encode.ts --destination src/core/encode.ts
depwire whatif . --simulate rename --target src/utils/encode.ts --destination src/utils/encoder.ts
depwire whatif . --simulate split --target src/services/auth.ts --symbols "validateToken,refreshToken"
depwire whatif . --simulate merge --target src/utils/helpers.ts --merge-target src/utils/formatters.ts

不使用 --simulate 运行，即可打开浏览器 UI，查看并排的弧线图，比较当前状态与模拟状态。

---

跨模块依赖智能分析

对于多模块 Maven 和 Gradle 项目，Depwire 会解析跨模块边界的导入，而不仅限于单个模块内部。

示例：模拟删除 google/guice 中的 Injector.java（一个由 13 个模块组成的 Java DI 框架）：

$ depwire whatif . --simulate delete --target core/src/com/google/inject/Injector.java

Action:          DELETE core/src/com/google/inject/Injector.java
Affected Nodes:  128
Broken Imports:  124  (cross-module: 106 across 10 extension modules)

1.9.0 之前的测量结果——google/guice 是一个 Java 项目；Java 解析器的重复输出错误（已在 v1.9.0 修复）会影响此数据。尚未重新测量。

跨模块解析让影响分析能够报告跨模块边界的受支持关系。

支持的构建系统：

• Maven（pom.xml 中包含 <modules> 声明，支持递归嵌套模块）
• Gradle（settings.gradle / settings.gradle.kts 中包含 include() 声明）

同时支持标准的（src/main/java）和非标准的（src/）源代码布局。

---

安全扫描器

Depwire 的安全扫描器会在本地报告发现项，并可使配置的 CI 门禁失败。

depwire security .                        # full repo scan
depwire security . --target src/auth.ts   # single file
depwire security . --format sarif         # GitHub Security tab integration
depwire security . --fail-on high         # CI gate — exit 1 if HIGH or above
depwire security . --class secrets         # specific check only
depwire security . --no-dependency-audit   # skip dependency checks and their network requests

10 类检查——依赖项 CVE、进程安全、凭据管理、路径安全、身份验证安全、输入验证、信息泄露、加密弱点、输出编码安全和架构级风险。

适用的安全扫描默认会运行依赖项漏洞和供应链检查；这些检查可能会联系软件包注册表和公共安全公告数据库。如需跳过这些检查及其网络请求，请使用 --no-dependency-audit；其他检查仍会运行。security_scan MCP 工具和 SDK 支持设置 dependencyAudit: false，以实现相同效果。选择不包含依赖项检查的类别（例如 --class secrets）也会跳过审计请求。

图感知严重性会使用记录的 MCP 工具和 HTTP 路由可达性来对发现项进行分类。

可通过 MCP 工具 security_scan 和 depwire-cli/sdk 使用。

---

操作前验证

在应用更改前分析拟议的更改。报告损坏的导入、在存在已解析的更改后图时的循环组变化、健康度变化和安全发现项。仅导出已编辑内容或统一差异的比较无法确定循环组安全性：此类比较会返回 cyclicGroupChanges.status: not_comparable，且不会认证更改是安全的。

depwire verify-change --file src/auth.ts --content-from new-auth.ts
depwire verify-change --diff changes.patch
depwire verify-change --file src/auth.ts --content-from new-auth.ts --json
cat new-auth.ts | depwire verify-change --file src/auth.ts

CI 集成：

depwire verify-change --diff pr.patch --fail-on-warnings --quiet
# exits 1 for medium risk, 2 for high risk

可通过 MCP 工具 verify_change 和 CLI 命令 depwire verify-change 使用。

---

提交间结构差异

比较任意两个 git 引用（分支、标签、提交哈希、HEAD~N）之间的依赖图。

depwire diff main feature/auth-refactor
depwire diff HEAD~5 HEAD --verbose
depwire diff v1.5.0 v1.6.0 --json | jq

差异使用图比较，不涉及大模型。它会临时暂存未提交的更改，并在分析后尝试恢复；如果恢复失败，会报告该情况，以便手动恢复。

选项：--json（机器可读）、--verbose（按名称列出每个符号/边）、--no-security / --no-health（更快地运行）。

---

可视化

depwire viz

图中展示了图内文件及其关系的交互式弧形图。悬停可查看详情，点击可筛选，并可导出为 PNG 或 SVG。

---

时间图

depwire temporal

查看 git 历史记录中架构的变化。时间线滑块可在提交间移动，并更新弧形图。

---

所有命令

命令	描述
depwire viz	在浏览器中查看交互式弧形图
depwire whatif	在修改代码前模拟更改
depwire verify-change	分析拟议的更改——损坏的导入、健康度变化、安全性和比较限制
depwire security	扫描漏洞——图感知严重性
depwire health	6 个维度的架构健康度评分，范围为 0-100
depwire dead-code	查找带置信度的死代码候选项；JSON 输出包含 reasonCode
depwire docs	生成 13 份架构文档
depwire temporal	可视化 git 历史记录中的架构演变
depwire parse	解析依赖图并将其导出为 JSON
depwire prompt	获取面向图优先工作流的 AI Agent 提示词
depwire diff	比较两个 git 提交间的结构差异——符号、边、健康度、安全性
depwire mcp	启动面向 AI 编码助手的 MCP 服务

命令接受项目路径；如果未指定，depwire parse 会使用提供的目录或当前目录。

depwire prompt — 面向 AI Agent 的图优先工作流

# Get the graph-first workflow prompt for your agent
depwire prompt                    # generic
depwire prompt --tool claude      # Claude Code optimized
depwire prompt --tool cline       # Cline optimized
depwire prompt --tool codex       # Codex optimized

开始复杂任务前，将输出粘贴为 Agent 的系统上下文。

---

MCP 服务 — AI 集成

将 Depwire 连接到任何兼容 MCP 的 AI 工具。你的 AI 可以自主调用 24 种工具。

Claude Desktop — 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

使用已保存的图谱启动 MCP：

# Parse once (writes depwire-output.json)
depwire parse .

# Output defaults to the parsed project directory; --output takes precedence
depwire parse ./services/api --output ./artifacts

# MCP starts from the saved graph
depwire mcp .

# Flags:
depwire mcp . --from-cache   # error if no cache found
depwire mcp . --no-cache     # force full re-parse

depwire parse [directory] 会读取指定目录；若省略，则读取 cwd （不会向上遍历到祖先项目）。如果提供 --output <dir>，则将 depwire-output.json 写入该目录；否则写入 [directory]，再否则写入 cwd。 相对路径根据 cwd 解析；--output 是一个目录。

解析结果	退出代码	结果
成功解析一个或多个文件	0	已导出图谱
部分文件解析成功，部分失败	0	已导出部分图谱；stderr 上有非致命警告
未解析任何文件（目录为空、文件不受支持、文件被排除、文件过大或全部解析失败）	2	stderr 上显示清晰的消息；未导出图谱
目录遍历、图谱构建或输出写入失败	1	stderr 上显示错误

SDK 调用方可通过 parseProject(...).errorFiles 获取各文件的解析失败信息，并且必须同时检查 length 和 errorFiles。导出的图谱格式不变；部分解析诊断信息不会嵌入 JSON 图谱中。解析失败时，不会替换或删除之前的输出文件：CI 必须先检查退出代码，再使用该文件。

Cursor — Settings → Features → Experimental → Enable MCP → Add Server：

• Command：npx
• Args：-y depwire-cli mcp

自动生成的项目上下文

运行 depwire parse . 后，Depwire 会生成 .depwire/AGENTS.md — 一份针对项目的上下文文件，其中包含模块结构、关键文件、健康状况摘要和 MCP 快速入门命令。

要让 Claude Code 使用生成的上下文，请在 CLAUDE.md 中引用它：

# In your project root CLAUDE.md:
echo "## Depwire Context" >> CLAUDE.md
echo "Read .depwire/AGENTS.md for codebase architecture." >> CLAUDE.md

此引用可让 Claude Code 使用生成的项目上下文，而无需调用 MCP 工具。

24 个 MCP 工具

工具	描述
connect_repo	连接任意本地项目或 GitHub 仓库
get_architecture_summary	项目概览
get_file_context	完整上下文——导入、导出和依赖项。包括跨语言连接。
get_dependencies	某个符号依赖什么？
get_dependents	什么依赖这个符号？
get_symbol_info	查询任意符号的详细信息
search_symbols	在整个代码库中按名称查找符号
list_files	列出所有文件及其统计信息
impact_analysis	修改某个符号会导致什么问题？包括跨语言边。
visualize_graph	生成交互式弧线图
get_health_score	0-100 的健康评分及建议
find_dead_code	疑似无用代码，附带可信度和 reasonCode 证据
get_project_docs	获取自动生成的代码库文档
update_project_docs	按需重新生成文档
get_temporal_graph	查看架构随 Git 历史的演变
simulate_change	在修改代码前模拟移动、删除、重命名、拆分或合并。返回健康度变化、受影响的导入项和节点。包括跨语言边。
security_scan	扫描漏洞，并根据图结构提升严重性。无需 API 密钥。
verify_change	应用代码更改前生成安全报告。返回受影响的导入项、循环组变化（或明确的不可用原因）、健康度变化和受影响文件。也可通过 depwire verify-change CLI 使用。
claim_files	多 Agent 协调：声明要修改的文件，以便其他客户端避免冲突。
release_files	释放先前声明的文件。
get_active_claims	查询当前各方正在处理的内容。
record_decision	保存结构化决策，供未来会话参考。
get_decisions	按查询、会话、文件或标签检索过往决策。
affected_files	查找修改文件或符号后会受影响的文件和测试。

.depwire/ 运行时状态

协调工具（claim_files、release_files、get_active_claims、record_decision、get_decisions）会将运行时状态写入 .depwire/claims.jsonl 和 .depwire/decisions.jsonl。请将这些文件添加到项目的 .gitignore 中：

.depwire/claims.jsonl
.depwire/decisions.jsonl

---

跨语言边检测

Depwire 可检测不同语言编写的文件之间的连接。

例如，受支持的 TypeScript fetch('/api/users') 调用可以按路径匹配 Python @app.get('/api/users') 路由定义。该记录的边可用于分析路由变更的影响。

支持的模式：

• REST API 边——将 fetch/axios 调用与 Express、FastAPI、Flask、Gin 路由定义匹配
• 子进程边——将 execSync/subprocess.run 调用与图中的目标文件匹配

记录的跨语言边可用于“What If”模拟、影响分析、安全扫描和可视化。

---

架构健康度评分

cyclicGroups 维度衡量处于相互依赖组中的图相关文件占比，以及最大组的大小。它分别报告组数、循环依赖文件数、覆盖率和最大组大小；组数不会影响评分。组采用现有的健康度边策略：排除普通类型引用，同时保留旧版的纯类型导入规范化处理。见证路径用于展示每个组，而不会枚举所有循环。

之前的循环数不完整，且取决于遍历顺序。该指标已被移除，而非重新定义。健康度结果带有 dimensions_v 方法标记；跨越方法论边界的趋势会抑制改进／退化差值，并说明 变更。图格式仍为 2。此次修正并不意味着所有旧数值都不正确：无环图的数值确实为 0，且部分计数恰好一致。

模拟报告分别列出新出现循环的文件、解除循环的文件、新增／删除的循环文件、 组的合并／拆分以及内部边的变化。合并两个已有组不算解决问题；删除循环文件不等于解除仍存在文件的循环。

depwire health .

报告对六个维度进行评分：耦合度、内聚度、循环依赖组、巨型文件、孤立项和死代码，以及依赖深度。报告包含字母等级、建议和可比运行结果之间的趋势。

关于 v1.6.1 评分变更的说明： v1.6.1 修正了死代码评分方法，现在仅将没有任何依赖者的导出符号 计为死代码候选项。此前，局部变量和类内部成员被错误地纳入统计，导致 内部结构复杂的代码库的死代码比率被夸大。v1.6.1 及更高版本的健康度评分 与早期版本的评分无法直接比较。

---

SDK

Depwire 提供稳定的公共 API，可用于编程调用和 CI 流水线：

npm install depwire-cli

import {
  parseProject,
  buildGraph,
  calculateHealthScore,
  analyzeDeadCode,
  generateDocs,
  scanSecurity,
  SimulationEngine,
  detectCrossLanguageEdges,
  searchSymbols,
  getImpact,
  getArchitectureSummary,
  DepwireSDKVersion
} from 'depwire-cli/sdk';

SDK 是稳定的公共 API 接口。所有集成都应从 depwire-cli/sdk 导入，绝不要从内部路径导入。

---

为什么选择 Depwire

	Depwire	基于 RAG 的工具	LLM 扫描
方法	基于 AST 的依赖图	向量相似度	直接检查文件
重构上下文	调用和导入关系	语义检索的代码块	模型选择的文件
上下文形式	聚焦的图查询	检索到的文本块	可变
跨语言	REST + 子进程边	取决于实现	取决于模型
安全扫描器	感知图结构的严重性	取决于实现	取决于模型
What If 模拟	可用	取决于实现	取决于模型
多模块 JVM 支持	跨模块解析	取决于实现	取决于模型
本地运行	支持	取决于实现	取决于实现

---

语言支持

TypeScript、JavaScript、Python、Go、Rust、C、C#、Java、C++、Kotlin、PHP、Swift、Mojo、Ruby、Dart、R——共 16 种编程语言，另加 Angular 模板。跨语言检测涵盖受支持的 REST API 和子进程模式。下文的解析器说明列出了受支持的语法结构；这并不保证能够捕获任意代码库中的所有关系。覆盖边界记录了 TypeScript、JavaScript 和 Python 中已检查与未检查的导入形式。一份独立的 源代码 AST CI 台账会检查这三种语言中固定版本的导入与重新导出语法结构；它不保证能够捕获任意代码库或其他语言中的关系。

Java / JVM——类、接口、枚举、记录、注解、内部类、匿名类、Lambda 表达式、Maven pom.xml 和 Gradle 构建文件依赖边、Spring Boot 跨语言边（@GetMapping、@PostMapping、@RequestMapping）、JAX-RS / Jakarta EE 路由检测、Spring WebFlux RouterFunction 支持。 C# / .NET — 类、接口、记录、结构体、枚举、委托、文件范围命名空间、主构造函数、全局 using、.csproj ProjectReference 和 PackageReference 依赖边，以及 ASP.NET Core 跨语言边（属性路由 + Minimal API）。

C++ / 系统 — 类、结构体、联合体、枚举、命名空间、概念、协程、C++20 模块，以及支持移除参数的模板。解析 CMakeLists.txt、Conan 和 vcpkg 依赖边。检测 Crow、Drogon、Pistache 和 cpp-httplib 的跨语言路由。检测死代码，并排除虚函数表和模板。健康度评分检查：循环包含、缺少头文件保护、上帝类、原始指针字段、缺少虚析构函数。安全扫描器：内存安全模式、格式字符串问题、内存管理模式、进程执行安全模式。

Kotlin / JVM — 类、数据类、密封类、对象、伴生对象、值类、类型别名、扩展函数、枚举类、注解类。协程感知：挂起函数、GlobalScope 检测、结构化并发检查。解析 build.gradle.kts、build.gradle 和 settings.gradle.kts 依赖。检测 Spring Boot、Ktor、Http4k 和 Ktor Resources 的跨语言路由。检测 Android Retrofit 出站边。检测死代码，并排除 Android 生命周期和 Spring 注解。安全扫描器：查询安全模式、凭据管理模式、随机数生成安全性、滥用非空断言、Ktor 缺少身份验证代码块。

PHP / Web — 函数、类、方法、接口、特征、枚举、命名空间、use 语句、require/include 依赖边。支持过程式和面向对象两种风格。检测 Laravel（Route::get/post/put/delete/patch、中间件）、Symfony（#[Route(...)]）、Slim Framework 和 WordPress REST API（register_rest_route）的跨语言路由。检测 Guzzle 和 file_get_contents HTTP 客户端边。检测死代码，并排除 WordPress 钩子、Laravel 服务提供者、Symfony 控制器和魔术方法（__construct、__get、__set、__call）。安全扫描器：查询安全模式、运行时求值安全模式、进程执行安全模式、正则表达式修饰符漏洞、序列化安全模式、变量处理安全模式、密码哈希安全模式、已弃用的加密库、安全场景中较弱的伪随机数生成器、凭据管理模式。

Swift / Apple — 函数、方法、初始化器（init）、反初始化器（deinit）、类、结构体、枚举、协议、扩展、Actor（Swift 并发）、属性（var、let）、计算属性、类型别名、关联类型。解析 Package.swift（SPM）依赖。检测 Vapor、Hummingbird 和 Perfect 的跨语言路由。检测 URLSession 和 Alamofire HTTP 客户端边。检测死代码，并排除 AppDelegate/SceneDelegate 生命周期、SwiftUI View body、@IBAction/@IBOutlet、@objc、协议遵循、Codable 合成、XCTestCase 和 @main 入口点。安全扫描器：通过字符串插值检查查询字符串安全性、Process() 执行安全性、内存指针安全模式、UserDefaults 存储敏感数据、CC_MD5/CC_SHA1 弱哈希、CryptoKit 中的 Insecure.MD5/SHA1、加密场景中的 arc4random、App Transport Security 模式、凭据管理模式、硬编码的 HTTP URL。 Mojo / AI 原生 （战略性支持） — fn（带类型的函数）、def（兼容 Python 的函数）、struct（值类型）、类、trait（接口）、alias（类型别名和编译时常量）、var/let 声明、import 和 from...import 语句。基于模式的解析器（无可用的 tree-sitter-mojo）。支持 @value、@register_passable、@staticmethod 装饰器，inout/owned/borrowed 参数修饰符，以及 SIMD/Tensor/DType 类型引用。解析 mojoproject.toml 依赖项。检测 Python 互操作（from python import）。通过 Python 框架互操作检测跨语言路由（FastAPI/Starlette）。检测死代码，支持 init/copyinit/moveinit 生命周期、trait 实现、MLIR 方言操作，以及排除 @export。安全扫描器：Pointer[T] 和 DTypePointer 内存安全、Python 互操作求值安全、未初始化内存模式、SIMD 边界安全、通过 Python random 模块生成弱随机数、alias 声明中的硬编码密钥，以及加密场景中通过 Python 互操作使用 hashlib。

Ruby / Web — 方法定义（def、def self.）、类、模块、实例变量（@var）、类变量（@@var）、常量、attr_accessor/attr_reader/attr_writer、require/require_relative 依赖关系边、include/extend/prepend 混入关系边、块、proc、lambda、Struct 和 OpenStruct 定义，以及对 ActiveSupport::Concern 的支持。解析 Gemfile 依赖项。检测 Rails（routes.rb 中的 get/post/put/patch/delete/resources/namespace）、Sinatra（路由 + do 块）、Rack（config.ru 中的 map/run/use）和 Grape API 跨语言路由。检测 Faraday、Net::HTTP 和 HTTParty HTTP 客户端关系边。检测死代码，支持 Rails 控制器回调、ActiveRecord 生命周期回调、rake 任务、RSpec/Minitest 方法、concern（included/class_methods 块）、initialize、method_missing/respond_to_missing?、Pundit 策略方法，以及排除 Devise 策略。安全扫描器：数据库查询方法中的字符串插值、命令执行安全模式、运行时求值安全模式、动态分派安全模式、文件操作安全模式、YAML 反序列化安全、Marshal 反序列化安全、模板渲染安全模式、弱哈希算法（Digest::MD5/SHA1）、弱随机数（rand 与 SecureRandom）、凭据管理模式、SSL 验证模式，以及弱加密算法。

Dart / Flutter — 类、抽象类、密封类（Dart 3.0+）、混入、扩展、增强型枚举、typedef、记录、顶层函数和变量、构造函数（命名构造函数和工厂构造函数）、方法、getter/setter、字段。支持 import/export/part/part of/library 指令及相对路径解析。解析 pubspec.yaml 依赖项。具备 Flutter widget 树感知能力：检测 StatelessWidget、StatefulWidget、State 子类，并跟踪 build() 方法组合。检测 Shelf router、Aqueduct/Conduit、Angel 框架和 Serverpod endpoint 跨语言路由。检测 Dio、http 包、Chopper（@Get/@Post）和 Retrofit Dart（@GET/@POST）HTTP 客户端关系边。检测死代码，支持 Flutter widget 生命周期（initState、dispose、build、didChangeDependencies、didUpdateWidget）、框架重写方法、序列化方法（fromJson/toJson/copyWith）、Riverpod providers、Bloc/Cubit 事件处理器、GetX 控制器生命周期、测试方法，以及排除 mock 类。安全扫描器：数据库查询中的字符串插值、进程执行安全、运行时反射模式、文件路径安全、JSON 解码验证、WebView JavaScript 通道安全、平台通道验证、未加密本地存储模式、凭据弱哈希、不安全的随机数生成、凭据管理模式、SSL 证书验证、不安全的 HTTP 连接，以及 SharedPreferences 与 FlutterSecureStorage 使用模式。基于模式的解析器（无可用的 tree-sitter-dart WASM）。 R / 统计与数据科学 — 函数（包括匿名函数和闭包）、S3/S4/R5/R6 类定义、方法、变量赋值（包括 <- 和 = 形式）、library/require/source 依赖边、NAMESPACE 导入/导出指令、DESCRIPTION 文件依赖解析。基于模式的解析器（npm 上没有 tree-sitter-r）。跨语言边检测：plumber HTTP API 路由定义（@get、@post、@put、@delete、@patch 装饰器）与客户端调用方匹配；Shiny 响应式图边（server/UI 函数连线、observe、reactive、eventReactive、renderXxx 输出绑定）；通过 httr（GET、POST、PUT、DELETE）和 httr2（request + req_perform）发出的 HTTP 客户端边；DBI 数据库连接边（dbConnect、dbGetQuery、dbExecute）；reticulate Python 互操作边（import_from_path、source_python、py_run_file）。死代码检测会排除 S3/S4 泛型注册、Shiny 模块 server/UI 函数，以及 testthat/RUnit 测试块。安全扫描器：数据库查询调用中的字符串插值、system/system2/shell 执行安全模式、eval/parse 运行时求值安全、文件路径处理安全、凭据管理模式、统计安全场景中的弱 PRNG（密钥材料使用 sample/runif 而非 openssl），以及 plumber 路由处理程序中未经验证的输入。

HTML / Angular 模板 — Angular 组件模板解析（*.component.html）。自动将每个模板与其同级的 *.component.ts 组件配对。从 Angular 模板语法中提取组件选择器（自定义元素标签）、结构型指令、属性型指令、事件绑定和管道引用。生成从模板指向其引用的组件和管道的 uses 边。外部/库组件（Angular 内置组件、PrimeNG、ngx-translate 等）会解析为 external:: 标记，并从图中排除，以避免产生虚假节点。基于模式的解析器（使用正则表达式提取 Angular 模板语法）。

---

GitHub Action — PR 影响分析

Depwire 可通过 depwire-action GitHub Action 集成到 CI/CD 工作流中。

配置为用于拉取请求时，Action 会发布依赖影响报告，其中包含记录的变更和健康评分。它使用配置的 CLI 版本，该版本可能与最新版本不同。

添加到 .github/workflows/depwire.yml：

name: Depwire PR Impact
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  depwire:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - uses: depwire/depwire-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

阻止损害架构的 PR：

- uses: depwire/depwire-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    fail-on-score-drop: 5

GitHub Marketplace — depwire-action 仓库

---

pre-commit / prek 钩子

此仓库自带 .pre-commit-hooks.yaml，因此 Depwire 可作为远程钩子与 pre-commit 及 prek 等兼容运行器配合使用——无需使用 repo: local 封装 depwire-cli。添加到 .pre-commit-config.yaml：

repos:
  - repo: https://github.com/depwire/depwire
    rev: v1.21.2
    hooks:
      - id: depwire
        args: ["parse", ".", "--stats"]

rev 是包含 .pre-commit-hooks.yaml 的发布标签。该钩子会运行仓库级分析（pass_filenames: false）；默认命令为 parse . --stats，因此只有在需要传入其他 CLI 选项或运行其他命令时才需要使用 args，例如 args: ["health", "."]。运行器首次使用时会从标签安装 CLI；之后的解析可以复用 .depwire/cache.db。

只有当已暂存文件属于 Depwire 可解析的语言或构建清单时，钩子才会运行；如果提交中没有任何可解析的文件，则会报告为 Skipped，而不是因 No parseable files found 而失败。将 depwire-output.json 和 .depwire/ 添加到 .gitignore。

---

云端仪表板

app.depwire.dev — 在浏览器中查看完整依赖图、健康评分、死代码报告和 AI 代码库聊天。无需本地设置。

• 公共仓库免费
• Pro（$9.99/月）— 仓库数量不限，支持私有仓库，提供 AI 代码库聊天

VSCode 扩展

在 VSCode 扩展面板中搜索 Depwire，或运行：

ext install depwire.depwire-vscode

在 Marketplace 中查看

支持 Mac 和 Windows。可免费安装。

免费功能：

• 交互式依赖弧图
• 文件和符号计数
• 架构健康度评分

Pro 功能（$9.99/月）：

• 健康度维度细分（6 项指标）
• 具备图感知严重性评估的安全扫描器
• 死代码检测
• What If 模拟
• Verify Change — 提交前安全检查
• Git 提交之间的结构差异
• 文件上下文和依赖映射
• 时间图
• 多 Agent 协调
• 决策日志

在 app.depwire.dev/subscribe 订阅。

---

路线图

已发布

• 弧图可视化
• 24 个 MCP 工具
• 多语言支持（TypeScript、JavaScript、Python、Go、Rust、C、C#、Java、C++、Kotlin、PHP、Swift、Mojo、Ruby、Dart、R、HTML/Angular）
• 架构健康度评分
• 死代码检测
• 时间图
• What If 模拟 — CLI + 浏览器 UI
• 安全扫描器 — 图感知严重性提升
• 跨语言边检测 — REST API + 子进程
• 提交之间的结构差异 — depwire diff
• 公共 SDK — depwire-cli/sdk
• 云端仪表板 — app.depwire.dev
• PR Impact GitHub Action
• VSCode 扩展 — Mac + Windows，Marketplace
• HTML/Angular 模板解析
• 构造函数/字段依赖注入解析（Angular 服务、injects 边类型）
• 所有 MCP 工具的 Windows 路径规范化
• verify_change 对已编辑内容和差异设置明确的比较上限
• SQLite 图缓存，加快热解析速度
• 从持久化的 depwire-output.json 快速启动 MCP
• depwire prompt — 面向 AI Agent 的工作流提示词
• depwire parse 后自动生成 .depwire/AGENTS.md 项目上下文

接下来计划

• AI 建议的重构
• 自然语言架构查询

---

安全状况

解析器读取源文件，不会修改或执行这些文件。CLI 命令可以写入派生工件，例如图输出、解析缓存和 .depwire/AGENTS.md；协调工具会写入各自的运行时状态。

• 使用 tree-sitter 解析支持的语法；部分语言和 Angular 模板使用基于模式的解析器
• 可视化服务仅绑定到 localhost
• CLI 不会上传源代码、文件名、图数据或分析结果，也不会收集使用遥测数据。适用的安全扫描默认会执行依赖检查，并可能联系外部漏洞服务。提供 URL 时，connect_repo 会访问 GitHub；What If 浏览器页面会从 CDN 加载 D3。云端服务独立运行
• 阻止访问敏感系统目录

完整详情请参阅 SECURITY.md。

---

贡献

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 提交拉取请求
5. 签署 CLA（在你首次提交 PR 时自动处理）

---

作者

Atef Ataya — AI 架构师、作者和 Depwire 创作者。

• YouTube — 涵盖 AI Agent、MCP 和 LLM 的视频
• The Architect's Playbook: 5 Pillars
• LinkedIn

---

Depwire Action Token (DAT)

Depwire Action Token (DAT) 是一项用于签署 AI Agent 操作的草案规范。CLI 参考实现正在开发中；当前 Depwire 版本不会为每次工具调用、文件更改或委派操作生成 DAT 审计轨迹。

---

许可证

Business Source License 1.1 — 可免费用于个人和公司内部用途。将于 2029 年 2 月 25 日转为 Apache 2.0。

商业许可：[email protected]

---

使用 tree-sitter、graphology、D3.js 和 Model Context Protocol 构建。

路径和文件数量

图文件路径、符号 ID 路径前缀，以及 impact、affected、verify-change、whatif、死代码、安全和 MCP 工具输出的文件路径，在所有平台上都使用 POSIX / 分隔符，并且相对于被分析的项目根目录。 原生绝对路径仍适用于文件系统 IO、projectRoot 元数据字段和输出目录参数。文件查询接受反斜杠和开头的 ./。绝对路径查询必须与对应的图项目根目录匹配。文件名大小写会保留；不同的 POSIX 文件名不会进行大小写折叠。

共享的图导入边界会在跨文件解析、图构建和 JSON 恢复之前，对解析后的记录（包括缓存记录和解析器提示）进行规范化。监视器更新也使用该边界。直接构造 graphology 图的 SDK 使用者必须使用规范键，或通过 deserializeGraph 加载；加载现有 JSON 图时会进行规范化。

如果无法在图中找到文件（包括被排除的文件或没有图节点的文件），affected_files 会返回错误。成功解析到的文件如果没有依赖项，则会返回空结果。将空结果视为分析无异常之前，请先检查错误。verify-change 会将唯一的规范路径（包括变更文件本身）计入其影响范围。

• 图文件 / fileCount / totalFiles：由图节点表示的唯一文件，包括结构性文件节点。架构摘要、文档、图 JSON 和 MCP 均采用此定义。筛选后的文件列表只统计返回的子集。
• 已解析文件 / parsedFileCount（JSON 元数据）/ parsedFiles（MCP 架构概览）：成功解析的文件，包括没有图节点的文件。解析失败的文件会保留在 SDK errorFiles 中，不计入已解析文件。较旧的 JSON 可能没有此计数；此时会省略，不会推断。增量监视器变更会使此计数失效，直到下一次完整解析。

例如，成功解析 58 个文件，其中有 3 个文件仅包含注释，则结果为 Parsed files: 58 和 Graph files: 55。架构和 MCP 会报告 55 个图文件。本仓库的架构 CLI 入口为 depwire docs <path> --include architecture --stats；没有独立的 architecture 命令。depwire parse <path> --stats 会打印图统计信息。

图格式版本为 2。解析缓存采用独立的版本控制；解析变更会使较旧的缓存解析记录失效，但不会更改图格式。