把代码仓库变成 AI 可用的智能工作区：Repowise 实战教程

# 建议在临时目录练习
mkdir -p ~/tmp/repo-intelligence-demo
cd ~/tmp/repo-intelligence-demo

# 克隆示例项目
git clone https://github.com/pallets/itsdangerous.git
cd itsdangerous

# 建议先建虚拟环境
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

pip install -U repowise
repowise --version
repowise init --help

# 二选一即可；不要把 key 写进代码或仓库
export ANTHROPIC_API_KEY="你的 key"
# 或
export OPENAI_API_KEY="你的 key"

mkdir -p .repowise
cat > .repowise/config.yaml <<'YAML'
provider: mock
model: mock
embedding_model: voyage-3
reasoning: auto

git:
  co_change_commit_limit: 200
  blame_enabled: true

dead_code:
  enabled: true
  safe_to_delete_threshold: 0.7

maintenance:
  cascade_budget: 10
YAML

provider: anthropic
model: claude-sonnet-4-5

provider: openai
model: gpt-4o-mini

# 无 LLM key 时，优先只建索引
repowise init . --index-only

# 有 LLM key 时，可以运行完整初始化
# repowise init .

find .repowise -maxdepth 3 -type f -print

pip install networkx matplotlib

from pathlib import Path
import json

import networkx as nx

ROOT = Path.cwd()
REPOWISE_DIR = ROOT / ".repowise"


def load_graph() -> nx.Graph | None:
    for path in REPOWISE_DIR.rglob("*"):
        if not path.is_file():
            continue
        if "graph" not in path.name.lower():
            continue

        try:
            if path.suffix == ".json":
                data = json.loads(path.read_text())
                if isinstance(data, dict) and "nodes" in data:
                    return nx.node_link_graph(data)
            if path.suffix == ".gml":
                return nx.read_gml(path)
            if path.suffix == ".graphml":
                return nx.read_graphml(path)
        except Exception as exc:
            print(f"skip {path}: {exc}")

    return None


def main() -> None:
    graph = load_graph()
    if graph is None:
        print("没有找到 graph artifact；请先检查 .repowise/ 文件树。")
        return

    print(f"nodes={graph.number_of_nodes()} edges={graph.number_of_edges()}")

    pagerank = nx.pagerank(graph)
    print("\nTop 10 files/modules by PageRank:")
    for node, score in sorted(pagerank.items(), key=lambda item: -item[1])[:10]:
        print(f"{score:.4f}\t{node}")

    try:
        from networkx.algorithms.community import greedy_modularity_communities

        communities = list(greedy_modularity_communities(graph.to_undirected()))
        print(f"\ncommunities={len(communities)}")
        print("top community sizes:", [len(c) for c in communities[:8]])
    except Exception as exc:
        print(f"community detection skipped: {exc}")


if __name__ == "__main__":
    main()

python analyze_repo_graph.py

如果一个目录里的文件被分进多个社区：
  可能说明目录命名过粗，或职责混杂。

如果多个目录的文件长期聚在同一社区：
  可能说明它们实际属于同一个功能模块。

如果某个文件连接多个社区：
  它可能是 glue code，也可能是过度耦合点。

请优先阅读 PageRank Top 5 文件，并注意 graph community 2 与 community 4 之间的交叉依赖。不要直接重构跨社区接口，先给出影响面分析。

repowise status

repowise dead-code
repowise dead-code --safe-only

死代码候选审查 checklist：
[ ] 是否有测试覆盖？
[ ] 是否可能被 CLI 入口调用？
[ ] 是否可能被插件系统调用？
[ ] 是否可能通过反射、字符串、配置动态调用？
[ ] 是否是外部用户依赖的 public API？
[ ] 删除后是否能跑完整测试？
[ ] 是否可以先 deprecate，而不是直接删除？

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

# DECISION: 为什么这里这样设计，不采用另一种方案？
# TECH_DEBT: 已知技术债是什么？什么时候必须处理？
# SAFETY: 这里的安全边界是什么？哪些行为禁止修改？

repowise update .
repowise decision list
repowise decision health

grep -R "DECISION:\|TECH_DEBT:\|SAFETY:" -n src tests > architecture-notes.txt

repowise generate-claude-md

AI 上下文文件审查 checklist：
[ ] 是否说明项目用途？
[ ] 是否列出入口文件和核心模块？
[ ] 是否包含构建、测试、格式化命令？
[ ] 是否标明高风险文件或禁止修改区域？
[ ] 是否保留关键架构决策？
[ ] 是否短到 agent 能真正使用？
[ ] 是否没有泄露密钥、内部地址、token？
[ ] 是否没有把死代码候选写成“可以删除”？

repowise search "URL-safe token signing"
repowise query "How does Signer detect tampered payloads?"
repowise query "What is risky about changing signer.py?"
repowise query "Produce a Mermaid diagram of the package"

请回答这个模块的作用，并列出你依据的文件路径。
如果缺少证据，请明确说不知道，不要猜。

repowise init . --index-only
find .repowise -maxdepth 3 -type f -print
python analyze_repo_graph.py

repowise status
repowise dead-code
repowise dead-code --safe-only

repowise generate-claude-md

你要先阅读仓库智能摘要，不要全仓盲搜。

已知信息：
- PageRank Top 10 文件：<粘贴列表>
- 主要社区/模块：<粘贴模块边界>
- Git 共变风险：<粘贴风险文件>
- 死代码候选：<粘贴候选，但不要删除>

任务：
1. 先解释你认为的项目结构。
2. 标出本次修改可能影响的文件。
3. 给出验证命令。
4. 未经确认，不要删除死代码候选。
5. 如果证据不足，明确说需要继续检查哪些文件。

# Project Context for AI Agents

## Project purpose
一句话说明项目做什么。

## Start here
- path/to/core_file.py — 为什么重要
- path/to/entrypoint.py — 为什么重要

## High-risk areas
- path/to/risky_module.py — 修改前必须跑哪些测试

## Architecture decisions
- DECISION: xxx
- SAFETY: xxx

## Commands
- test: `...`
- lint: `...`
- run: `...`

## Do not
- 不要自动删除 dead-code 候选
- 不要修改安全边界文件，除非任务明确要求