Repowise全流程助力代码库智能化，实现图分析、死代码检测与AI上下文

背景与目标

在大型开源项目中，代码关系错综复杂，传统的代码审查往往只能靠人工经验。Repowise 通过 LLM 驱动的索引与图谱分析，把整个仓库转化为可查询的知识图谱，帮助开发者快速定位关键文件、发现死代码并记录架构决策。本文以 itsdangerous 为例，完整展示从环境搭建到可视化的全链路流程。

环境准备与工具初始化

克隆目标仓库
```
git clone https://github.com/pallets/itsdangerous.git /content/itsdangerous
cd /content/itsdangerous
```
配置 LLM 提供商
- 优先使用 ANTHROPIC_API_KEY，若不存在则回退到 OPENAI_API_KEY。
- 未检测到密钥时，Repowise 以 mock 模式运行，仅完成索引，不调用 LLM。
生成 .repowise/config.yaml
```
provider: ${provider}
model: ${model}
embedding_model: voyage-3
reasoning: auto
git:
  co_change_commit_limit: 200
dead_code:
  enabled: true
  safe_to_delete_threshold: 0.7
```
启动索引
```
repowise init .          # 有密钥时完整初始化
repowise init . --index-only   # 无密钥时仅建立索引
```

代码图谱分析

Repowise 会在 .repowise/ 生成多种图文件（.json, .gml, .graphml），其中包含节点（文件或类）与边（引用、共变更等）。
使用 networkx 读取后可计算 PageRank，排序后得到最核心的 10 个文件，例如 signer.py、serializer.py 等。
通过 模块社区检测（greedy modularity），可以看到代码自然分层，如签名模块、序列化模块、工具函数等。

import networkx as nx, json
G = nx.node_link_graph(json.load(open('graph.json')) )
pr = nx.pagerank(G)
top10 = sorted(pr.items(), key=lambda x: -x[1])[:10]
print('核心文件:', [n for n,_ in top10])

死代码检测与架构决策记录

repowise dead-code 列出所有未被引用或测试覆盖率低的函数/类。
repowise dead-code --safe-only 只返回安全删除阈值以上的代码，降低误删风险。
在关键文件中加入 DECISION 注释，如在 signer.py 写下：

# DECISION: Signers are stateless by design — secrets are passed at construction so signing can be parallelised safely.

提交后执行 repowise update .，工具会自动把决策抽取到内部知识库，可通过 repowise decision list 查看。

AI 上下文生成（CLAUDE.md）

当 LLM 密钥可用时，运行：

repowise generate-claude-md

该命令会基于仓库的代码、文档、图谱以及已记录的决策，生成一份结构化的 CLAUDE.md，供后续的 AI 辅助开发（如 Copilot、ChatGPT）直接读取上下文，提升代码补全与问题回答的准确性。

CLI 工具一览（MCP 风格）

功能	示例命令	说明
查询代码片段	`repowise search "timestamp expiry validation"`	基于向量检索返回相关实现
结构化问答	`repowise query "Architecture overview please"`	LLM 生成项目整体结构概览
风险评估	`repowise query "What is risky about changing signer.py?"`	自动标记潜在破坏性改动
生成 Mermaid 图	`repowise query "Produce a Mermaid diagram of the package"`	可直接嵌入文档的可视化模型

可视化展示

通过 matplotlib 绘制子图，仅保留 PageRank 前 40 的节点，节点大小随重要性指数线性放大，配色采用项目品牌橙色 #F59520，直观呈现关键文件之间的依赖网络。此图可用于技术分享或 onboarding 文档。

import matplotlib.pyplot as plt
top = [n for n,_ in sorted(pr.items(), key=lambda x: -x[1])[:40]]
H = G.subgraph(top)
size = [4000*pr[n]/max(pr.values())+80 for n in H.nodes]
pos = nx.spring_layout(H, seed=7, k=0.9)
nx.draw(H, pos, node_size=size, node_color='#F59520', with_labels=True, font_size=8)
plt.show()

实践意义

快速定位核心代码：PageRank 排名让新成员第一眼就能看到业务关键点。
降低技术债务：死代码检测配合阈值过滤，帮助团队有序清理冗余。
决策可追溯：DECISION 注释与决策列表形成闭环，防止“知识失传”。
AI 开发即插即用：生成的 CLAUDE.md 为后续的大模型提供完整上下文，显著提升自动化 refactor 与 bug 诊断的效率。

小结

Repowise 将传统的代码审计与现代 LLM 能力结合，实现了 仓库级智能化：从图谱结构到死代码检测，再到决策记录与 AI 上下文生成，全流程可在本地完成，既保证了安全，又提升了团队生产力。对任何希望在开源或内部项目中引入 AI 辅助开发的团队而言，这是一套值得复制的最佳实践。