Wisegit

wisegit

“在弄清楚篱笆为何立起之前，别把它拆掉。” — G.K. Chesterton

wisegit 是一个本地 MCP 服务，可从 Git 历史中提取决策意图，并保护有意保留的代码不被 AI 修改。

当 Claude Code（或任何兼容 MCP 的 Agent）即将编辑文件时，wisegit 会注入一份决策清单，说明哪些函数已冻结、稳定或开放，让 AI 尊重代码背后的意图，而不只是确保代码能编译。

零配置。零外部服务。一切均在本地运行。

安装

# Set up any repo (one command)
npx @sandip124/wisegit setup

# Or add as MCP server globally
claude mcp add wisegit -- npx @sandip124/wisegit serve

发布平台

• npm： @sandip124/wisegit
• MCP Registry： io.github.Sandip124/wisegit
• GitHub： Sandip124/wisegit

问题

大模型无法理解有意保留的代码。手动测试过的修复和损坏的存根看起来毫无区别——它们都只是文本。实际场景：

1. 你用 sleep(350) 修复了一个 Stripe 竞态条件——经过手动测试并提交。
2. 下次会话中，你要求“查找错误”。Claude 删除了 sleep(350)——它看起来像是死代码。
3. 线上事故。

根本原因： Git 历史记录中包含意图的证据，但没人提取这些证据。

工作原理

Git History → Tree-sitter AST → Intent Extraction → SQLite Event Store → MCP Tools

1. 为 Git 历史建立索引——遍历每个提交，在 AST 层解析差异（基于函数边界，而非行数）
2. 对提交分类——STRUCTURED（fix:、feat:）、DESCRIPTIVE（普通句子）或 NOISE（wip、x）
3. 提取意图——对结构化/描述性提交采用基于规则的方法，对噪声提交使用大模型（第二阶段）
4. 计算冻结分数——每个函数的分数为 0–1，根据保护信号（Git、问题、代码结构、测试、结构、Naur、Aranda）减去自适应过时惩罚（8 种信号，经熵校准）得出。代码年龄采用 Weibull 生存模型 [18]；专业知识采用 DOE 模型 [19]
5. 通过 MCP 提供决策清单——Claude Code 在编辑任何文件前调用 get_file_decisions

AI 会看到什么

[DECISION MANIFEST: payment.service.cs]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FROZEN:  ProcessPayment()  [score: 0.89] [Recovery: L1]
  - sleep(350) → Stripe race condition. Won't Fix.
    HIGH — commit a3f19b2

STABLE:  ValidateOrder()  [score: 0.55] [Recovery: L2]
  - Fixed null reference on Safari iOS WebKit.
    MEDIUM — commit 7c14694

OPEN:    FormatReceipt()  [score: 0.12] [Recovery: L3]
  ← safe to modify
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• FROZEN（冻结）（分数 >= 0.80）：未经用户明确批准，不得修改
• STABLE（稳定）（分数 0.50-0.79）：谨慎处理，先检查意图
• OPEN（开放）（分数 < 0.50）：可以自由修改

快速开始

前提条件

• Node.js >= 20

就这些。无需 Docker、PostgreSQL 或外部服务。

1. 设置仓库（一条命令）

cd /path/to/your/repo
npx @sandip124/wisegit setup

这条命令会：

• 在 ~/.wisegit/wisegit.db 创建本地 SQLite 数据库
• 为整个 Git 历史建立索引（462 次提交约需 13 秒）
• 创建 .mcp.json，以供 Claude Code 自动发现
• 创建 CLAUDE.md 规则，指示 AI 在编辑前进行检查
• 将 .mcp.json 添加到 .gitignore

2. 补充问题上下文（可选）

# Fetch issue/PR details from GitHub/GitLab
GITHUB_TOKEN=ghp_... npx @sandip124/wisegit enrich

此步骤会获取引用的问题（例如提交消息中的 #134），检测 Won't Fix / By Design 决策，并提高关联到这些问题的函数的冻结分数。

3. 完成

在 Claude Code 中打开仓库。它会自动：

1. 启动 wisegit MCP 服务（通过 .mcp.json）
2. 读取保护规则（通过 CLAUDE.md）
3. 在编辑任何文件前调用 get_file_decisions

MCP 工具

工具	描述
get_file_decisions	文件决策清单 — 冻结评分、意图历史、恢复级别、覆盖状态
get_freeze_score	特定函数的评分和信号明细
get_function_history	函数完整的时间顺序决策时间线
get_theory_gaps	理由无法恢复的函数（作者不活跃、时间线缺失）
get_branch_context	分支合并历史 — 迁移了什么以及原因
search_decisions	按关键字搜索整个仓库中的过往决策
create_override	覆盖已冻结的函数（用户在 Claude Code UI 中批准）
extract_intent	使用宿主大模型为 NOISE 提交提取意图 — 无需 Ollama
find_similar_functions	编写新代码前，搜索已有的类似问题解决函数
predict_impact	预测修改指定函数会导致哪些函数出问题
get_codebase_conventions	提取文件所在代码区域的编码约定

MCP 资源： wisegit://manifest/{filePath} — 可自动发现的决策清单资源

MCP 提示词： check_before_edit — 强制工作流提示词，在编辑任何文件前返回决策清单

大模型意图提取策略

wisegit 使用智能回退链，为 NOISE 提交提取意图：

场景	使用的大模型	方式
在 Claude Code 中	宿主大模型（Claude）	MCP 采样 — 请求 Claude 分析差异。无需任何设置。
在装有 Ollama 的命令行中	Ollama（llama3）	wisegit init --ollama — 使用本地 Ollama 实例
在未装 Ollama 的命令行中	无	仅进行基于规则的提取，NOISE 提交不会获得意图

在 Claude Code 中，调用 extract_intent 可追溯恢复 NOISE 提交的意图 — 使用 Claude 本身，无需安装 Ollama。

CLI 命令

wisegit setup [--path <dir>] [--global]         # One-command repo setup
wisegit init [--full-history] [--path <dir>]     # Index git history
wisegit enrich [--path <dir>]                    # Fetch issue/PR context from GitHub/GitLab
wisegit audit <file>                             # Show decision manifest
wisegit history <target> [--file <path>]         # Show decision timeline
wisegit recompute [--path <dir>]                  # Recompute scores with PageRank + theory gaps
wisegit override <fn> --file <f> --reason "..."  # Override a frozen function
wisegit overrides                                # List active overrides
wisegit sync                                     # Rebuild local cache from git + .wisegit/
wisegit config list                              # View team configuration
wisegit config set <key> <value>                 # Modify team policy
wisegit team-status                              # Team overview: enrichments, overrides, contributors
wisegit team-health                              # Theory health: healthy/fragile/critical functions
wisegit branch-capture                           # Capture branch context from last merge
wisegit branch-list                              # List all captured branch snapshots
wisegit branch-recover <sha>                     # Recover context from old merge commit
wisegit calibrate                                # Show adaptive obsolescence weights vs defaults
wisegit report [--output <file>]                 # Generate HTML report with scores + insights
wisegit serve                                    # Start MCP server (stdio)
wisegit hook install|uninstall                   # Manage git hooks (post-commit + post-merge)

配置 Claude Code

选项 A：针对每个仓库（推荐）

在任意仓库中运行 npx @sandip124/wisegit setup。它会自动创建 .mcp.json。

选项 B：全局注册

claude mcp add wisegit -- npx @sandip124/wisegit serve

选项 C：手动配置 .mcp.json

在仓库根目录中创建 .mcp.json：

{
  "wisegit": {
    "command": "npx",
    "args": ["@sandip124/wisegit", "serve"]
  }
}

支持的语言

语言	扩展名
C#	.cs
TypeScript	.ts、.tsx
JavaScript	.js、.jsx、.mjs、.cjs
Python	.py
Go	.go
Rust	.rs

可通过 src/ast/languages/ 中的 Tree-sitter 语法配置添加更多语言。

Issue 信息补充

一条写着 fix: handle null token #134 的提交，指向一个包含复现步骤、根本原因和明确决策理由的 Issue — 这些信息在提交消息中从未提及。

# Fetch issue context from GitHub/GitLab
wisegit enrich --path /path/to/repo

# With auth (5000 req/hr instead of 60)
GITHUB_TOKEN=ghp_... wisegit enrich

支持的平台： GitHub、GitLab（计划支持 Azure DevOps、Jira、Bitbucket）

身份验证令牌： GitHub 使用 GITHUB_TOKEN / GH_TOKEN，GitLab 使用 GITLAB_TOKEN。wisegit 从不存储这些令牌。

基于 Issue 的冻结信号

信号	冻结加成	条件
不会修复 / 按设计如此	+0.35	Issue 以 not_planned 状态关闭，或带有 wontfix / by-design 标签，或评论中写明“有意为之”
复现步骤	+0.15	Issue 正文包含“复现步骤”
特定平台标签	+0.10	Issue 带有 ios、safari、windows 等标签
无法访问 Issue	+0.10	存在 Issue 引用，但 API 返回 404 — 缺少上下文时应加强保护
PR 审查评论	+0.15	关联的 PR 中有审查者讨论

冻结分数信号

冻结分数从不直接存储——它是通过重放每个函数的事件流推导出来的。信号类别如下：

类别	权重	来源
Git 历史	0.20	回滚、已验证的关键词、事件引用、贡献者数量、Weibull 年龄 [18]
问题增强	0.20	Won't Fix/By Design、复现步骤、平台标签
代码结构	0.15	行内注释、魔法数字、防御性模式
测试信号	0.15	专用测试、边界情况标签、共同提交的测试
结构重要性	0.15	调用次数（PageRank）、公共 API、DOE 专业知识模型 [19]
Naur 理论	0.10	全局模式、有意的矛盾、移除成本
Aranda 信号	0.05	被遗忘的模式、时间线空档、失效的问题链接
过时性（8 种信号）	自适应	死代码、陈旧子图、迁移遗留、过时依赖、已被取代、SAAD、变更爆发缺失、共同变更偏离

冻结分数公式：

freeze_score = base_score x (1 - obsolescence_penalty)

保护信号产生基础分数（对存在的信号类别进行加权平均，而非求和）；过时性信号则产生惩罚。 过时性权重是自适应的——根据 Shannon 熵和贝叶斯反馈，按仓库进行校准。当带有信号的函数少于 20 个时，会回退到硬编码默认值。 年龄信号使用 Weibull 生存模型 [18]（k=0.7，lambda=2.4y）；贡献者专业知识使用 DOE 模型 [19]（4 个变量：贡献占比、近期性、持续时间、频率）。

学术依据：24 篇已发表论文。完整引文请参阅 REFERENCE.md。

跨仓库验证

在 3 个真实世界的开源代码库上进行了测试：

仓库	提交数	函数数	FROZEN	STABLE	最高分数
pallets/flask	5,565	4,355	72	2,272	0.927
expressjs/express	6,382	409	1	247	0.811
zeeguu/api	4,515	3,216	1	12	0.583

Flask 的核心 API（__init__、run、wsgi_app、url_for）均正确获得 FROZEN 评分（0.87+）。Express 路由基元（paramCallback、Route、Router）均正确获得 FROZEN/STABLE 评分。分数会根据各代码库的历史进行调整，而非生成统一的分布。

详细的验证结果和实现变更请参阅 REFERENCE.md。

遗留代码库演进

wisegit 专为积累了多年有意决策的代码库而设计。冻结分数并不意味着“永远不要改动它”——而是意味着“改动前先理解这些决策”。

渐进式迁移，而非光鲜的重写。 根据 Távora [12] 的观点：杂乱代码中的业务规则是正确且有价值的。技术债务在于结构，而非决策。wisegit 会保护这些决策，同时让你修复结构。

阶段	wisegit 如何提供帮助
理解现状	wisegit audit 展示哪些内容是有意为之的。wisegit team-health 展示哪些地方正在流失机构知识。
重构期间予以保护	清单会告知开发者和 AI 哪些行为是经过有意选择的
记录理由	覆盖理由会保存在 .wisegit/overrides.jsonl 中——不会埋没在 Slack 里
保留迁移背景	分支快照会记录哪些内容被替换，以及哪些内容不应再回归
跟踪跨边界依赖	共同变更信号会检测遗留代码与替代代码之间的耦合

完整的遗留代码库演进章节及其学术依据（24 篇已发表论文），请参阅 REFERENCE.md。

团队协作

wisegit 采用三层架构——无需单独的“团队模式”：

层级	内容	是否共享？
确定性基础层	提交分类、基于规则的意图、git 信号	通过 git（自动）
团队知识层	补充信息、覆盖项、意图、分支上下文	通过 .wisegit/（由 git 跟踪）
本地缓存	位于 ~/.wisegit/wisegit.db 的 SQLite	从不（派生数据）

.wisegit/                      # Tracked by git — shared with team
├── config.json                # Team policy (thresholds, AI authors)
├── enrichments.jsonl          # Issue enrichment cache
├── overrides.jsonl            # Override audit trail
└── branch-contexts.jsonl      # Branch merge snapshots

JSONL 格式——每行一个 JSON 对象。并发追加不会产生 git 合并冲突。

队友推送 .wisegit/ 更改后，运行 wisegit sync 将其导入本地缓存。

完整的团队架构设计请参阅 TEAM-ROADMAP.md。

架构

┌─────────────────────────────────────────────────┐
│  Claude Code / MCP Client                       │
│  ┌───────────────────────────────────────────┐  │
│  │ 1. Reads CLAUDE.md protection rules       │  │
│  │ 2. Calls get_file_decisions before edits  │  │
│  │ 3. Respects FROZEN / STABLE / OPEN        │  │
│  └───────────────────────────────────────────┘  │
└─────────────────┬───────────────────────────────┘
                  │ MCP (stdio)
┌─────────────────▼───────────────────────────────┐
│  wisegit MCP Server                             │
│  ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │
│  │get_file_ │ │get_freeze│ │search_decisions │ │
│  │decisions │ │_score    │ │                 │ │
│  └────┬─────┘ └────┬─────┘ └───────┬─────────┘ │
└───────┼─────────────┼───────────────┼───────────┘
        │             │               │
┌───────▼─────────────▼───────────────▼───────────┐
│  SQLite (~/.wisegit/wisegit.db)                 │
│  ┌──────────────┐ ┌────────────┐ ┌───────────┐ │
│  │decision_events│ │freeze_scores│ │issue_     │ │
│  │(append-only) │ │(derived)   │ │enrichments│ │
│  └──────────────┘ └────────────┘ └─────┬─────┘ │
└────────────────────────────────────────┼────────┘
                                         │
┌────────────────────────────────────────▼────────┐
│  Issue Enrichment (wisegit enrich)              │
│  ┌─────────┐ ┌─────────┐ ┌──────────────────┐  │
│  │ GitHub  │ │ GitLab  │ │ Jira (planned)   │  │
│  │ REST API│ │ REST API│ │                  │  │
│  └─────────┘ └─────────┘ └──────────────────┘  │
└─────────────────────────────────────────────────┘

环境变量

变量	默认值	描述
WISEGIT_DB_PATH	~/.wisegit/wisegit.db	SQLite 数据库路径
GITHUB_TOKEN / GH_TOKEN	—	GitHub API 令牌（每小时 5000 次请求，而未认证时为 60 次）
GITLAB_TOKEN	—	用于问题补充信息的 GitLab API 令牌
OLLAMA_URL	http://localhost:11434	Ollama 服务 URL（第 2 阶段）
OLLAMA_CHAT_MODEL	llama3	用于意图提取的模型（第 2 阶段）
OLLAMA_EMBED_MODEL	nomic-embed-text	用于生成嵌入的模型（第 2 阶段）

安全性

• 所有操作均在本地运行——只有问题补充信息会发起出站 API 调用（通过 wisegit enrich 自行选择启用）
• 仅追加的事件存储——决策永不删除，只会添加
• SQLite 数据库存储于 ~/.wisegit/wisegit.db——不暴露于网络
• MCP 工具输入使用严格的 Zod 架构进行验证（防止路径遍历，限制长度）
• 返回给 MCP 客户端前会清理错误消息
• 写入文件前会检查是否存在符号链接
• 配置文件仅使用允许列表中的键进行解析（防止原型污染）

路线图

• 第 1 阶段——事件存储、AST 分块、提交分类、意图提取、MCP 服务、CLI
• 第 1.5 阶段——问题补充信息（GitHub、GitLab），包含“拒绝修复”/“按设计如此”检测和冻结增强信号
• 第 2 阶段——完整冻结分数：调用图 + PageRank、理论缺口检测（Naur 式消亡、遗忘模式）、共同变更信号、Aranda 信号、Ollama 客户端、Go + Rust 支持
• 第 4 阶段——覆盖系统（必须提供原因、限时过期、审计跟踪）、分支上下文保留（合并后钩子、快照存储、恢复）
• 阶段 A——共享团队知识层：.wisegit/ 目录，其中包含用于补充信息、覆盖项、分支上下文和团队配置的 JSONL 文件
• 阶段 B——团队感知清单：理论持有者跟踪、风险级别（健康/脆弱/危急）、团队状态 + 健康状况命令
• 阶段 C——AI 时代适配：提交来源检测（HUMAN/AI_REVIEWED/AI_UNREVIEWED）、按来源加权的冻结分数
• 阶段 D——覆盖审批工作流、团队健康指标
• 阶段 E——自适应过时校准：8 种过时信号、经熵校准的权重、贝叶斯反馈、wisegit calibrate CLI

许可证

MIT