使用说明
威斯基特
“在知道围栏建起来的原因之前，不要把它拆掉。” --G.K.切斯特顿
威斯基特 是一个本地MCP服务器，它从git历史中提取决策意图，并保护有意代码免受AI修改。
当Claude Code（或任何兼容MCP的代理）即将编辑文件时，wisegit会注入一个 决策清单 显示哪些函数是冻结的、稳定的或开放的——因此人工智能尊重的是有意的，而不仅仅是编译的。
零配置。零外部服务。一切都是当地的。
安装
# 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： @桑迪普124/怀斯吉特
- MCP注册表： io.github。桑迪124/怀斯吉特
- github： 桑迪124/怀斯吉特
问题
LLMs没有概念 有意代码手动测试的修复程序和损坏的存根看起来完全相同——两者都只是文本。真实场景：
- 您可以通过以下方式修复Stripe比赛条件
sleep(350)--手动测试，提交。 - 下一节课：“查找bug。”Claude删除
sleep(350)--看起来像死代码。 - 生产事故。
根本原因： git历史包含意图证明。没有人提取它。
运作原理
Git History → Tree-sitter AST → Intent Extraction → SQLite Event Store → MCP Tools
- 索引您的git历史记录 --遍历每个提交，在AST级别解析差异（函数边界，而不是行数）
- 对提交进行分类 --结构化(
fix:,feat:)、描述性（简单的句子）或噪音(wip,x) - 提取意图 --基于规则的结构化/描述性提交，LLM用于噪声（第2阶段）
- 计算冻结分数 --每个功能0-1，来自保护信号（git、issue、代码结构、测试、结构、Naur、Aranda）减去自适应淘汰惩罚（8个信号，熵校准）。年龄使用威布尔生存[18]；专业知识使用DOE模型[19]
- 通过MCP提供决策清单 --克劳德代码调用
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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- 冰冻 （得分>=0.80）：未经用户明确批准，不得修改
- 稳定 （0.50-0.79分）：谨慎行事，先审查意图
- 打开 （分数<0.50）：可以自由修改
快速开始
先决条件
- Node.js>=20
就是这样。没有Docker，没有PostgreSQL，没有外部服务。
1.设置存储库（一个命令）
cd /path/to/your/repo
npx @sandip124/wisegit setup
这个命令：
- 在以下位置创建本地SQLite数据库
~/.wisegit/wisegit.db - 对整个git历史进行索引（约13秒内462次提交）
- 创建
.mcp.json用于克劳德代码自动发现 - 创建
CLAUDE.md指示AI在编辑前进行检查的规则 - 增加
.mcp.json到.gitignore
2.丰富问题背景（可选）
# Fetch issue/PR details from GitHub/GitLab
GITHUB_TOKEN=ghp_... npx @sandip124/wisegit enrich
这获取了引用的问题（例如。， #134 在提交消息中），检测“无法修复/按设计”决策，并提高与这些问题相关的函数的冻结分数。
3.完成
在Claude Code中打开仓库。它将自动：
- 启动wisegit MCP服务器（通过
.mcp.json) - 阅读保护规则（通过
CLAUDE.md) - 呼叫
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 |
使用主机LLM提取NOISE提交的意图——不需要Olama |
find_similar_functions |
在编写新代码之前，搜索解决类似问题的现有函数 |
predict_impact |
预测如果修改给定函数，哪些函数会中断 |
get_codebase_conventions |
提取文件邻域的编码约定 |
MCP资源： wisegit://manifest/{filePath} --决策清单作为可自动发现的资源
MCP提示： check_before_edit --在编辑任何文件之前返回决策清单的强制工作流提示
LLM意图提取策略
wisegit使用智能回退链从NOISE提交中提取意图：
| 背景 | LLM使用方法 | 如何使用 |
|---|---|---|
| 克劳德代码内部 | 主机LLM（Claude） | MCP采样——要求Claude分析diff.Zero设置。 |
| CLI与Ollama | Ollama（通话3） | wisegit init --ollama --使用本地Ollama实例 |
| 没有Ollama的CLI | 无 | 仅基于规则的提取，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代码
选项A：每次回购（推荐）
跑 npx @sandip124/wisegit setup 在任何回购中。它创造了 .mcp.json 自动。
选项B：全球注册
claude mcp add wisegit -- npx @sandip124/wisegit serve
选项C：手动 .mcp.json
创建 .mcp.json 在您的repo根目录中：
{
"wisegit": {
"command": "npx",
"args": ["@sandip124/wisegit", "serve"]
}
}
支持的语言
| 语言 | 扩展 |
|---|---|
C .cs |
|
| TypeScript | .ts, .tsx |
| JavaScript | .js, .jsx, .mjs, .cjs |
python .py |
|
| 去吧 | .go |
| 生锈 | .rs |
可以通过Tree sitter语法配置添加更多语言 src/ast/languages/.
问题丰富
承诺说 fix: handle null token #134 指向一个包含复制步骤、根本原因和明确决策理由的问题——提交消息从未说过的一切。
# 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_TOKEN / GH_TOKEN 对于GitHub， GITLAB_TOKEN GitLab。从不使用wisegit存储。
发出冻结信号
| 信号 | 冻结增强 | 何时 |
|---|---|---|
| 无法修复/按设计 | +0.35 | 问题已结束 not_planned，或已 wontfix/by-design 标签或评论说“有意” |
| 复制步骤 | +0.15 | 问题正文包含“复制步骤” |
| 平台特定标签 | +0.10 | 已标记问题 ios, safari, windows等等。 |
| 无法访问问题 | +0.10 | 问题引用存在，但API返回404-缺少上下文=保护更多 |
| PR审核意见 | +0.15 | 链接PR有审核人讨论 |
冻结分数信号
冻结分数为 从不直接存储 --它是通过重放每个函数的事件流得出的。信号类别：
| 类别 | 重量 | 来源 |
|---|---|---|
| Git历史 | 0.20 | 还原、验证关键字、事件引用、贡献者计数、威布尔年龄[18] |
| 问题丰富 | 0.20 | 无法修复/按设计、复制步骤、平台标签 |
| 代码结构 | 0.15 | 内联注释、幻数、防御模式 |
| 测试信号 | 0.15 | 专用测试、边缘情况标签、共同提交测试 |
| 结构重要性 | 0.15 | 呼叫次数（PageRank），公共API，DOE专业模型[19] |
| 诺尔理论 | 0.10 | 全球模式、有意矛盾、消除成本 |
| Aranda Signals | 0.05 | 被遗忘的模式、时间线差距、问题链接中断 |
| 过时（8个信号） | 自适应 | 死码、过时子图、迁移剩余、过时deps、被取代、SAAD、变化突发缺失、共变发散 |
冻结分数公式：
freeze_score = base_score x (1 - obsolescence_penalty)
保护信号产生基本分数（当前信号类别的加权平均值，而不是加和）；过时信号会产生惩罚。 过时重量为 自适应的 --使用香农熵对每个存储库进行校准 以及贝叶斯反馈。当<20个函数有信号时，返回硬编码默认值。 年龄信号使用 Weibull生存模型 [18] （k=0.7，λ=2.4y）；贡献者专业知识使用 DOE模型 [19] （4个变量：贡献份额、近期、持续时间、频率）。
学术基础：发表论文24篇。看 参考.md 完整引用。
交叉回购验证
在3个真实世界的开源代码库上进行了测试：
| 回购 | 承诺 | 功能 | 冻结 | 稳定 | 最高得分 |
|---|---|---|---|---|---|
| 托盘/烧瓶 | 5565 | 4355 | 72 | 2272 | 0.927 |
| expressjs/express | 6382 | 409 | 1 | 247 | 0.811 |
| zeeguu/api | 4,515 | 3,216 | 1 | 12 | 0.583 |
Flask的核心API(__init__, run, wsgi_app, url_for)正确得分为冷冻（0.87+）。快速路由原语(paramCallback, Route, Router)正确得分为冻结/稳定。分数适应每个代码库的历史，而不是产生统一的分布。
看 参考.md 了解详细的验证结果和实施更改。
遗留代码库演变
wisegit是为积累了多年有意决策的代码库而设计的。冻结分数并不意味着“永远不要改变这一点”，而是意味着“在改变之前理解这些决定”
渐进式迁移，而不是闪亮的重写。 Per Távora[12]：混乱代码中的业务规则是 正确且有价值技术债务在于结构，而非决策。在修复结构时，wisegit会保护决策。
| 阶段 | wisegit如何提供帮助 |
|---|---|
| 了解AS-IS | wisegit audit 显示了什么是故意的。 wisegit team-health 显示了机构知识丢失的地方。 |
| 重构过程中的保护 | 清单告诉开发人员+AI哪些行为是故意选择的 |
| 记录理由 | 覆盖原因持续存在 .wisegit/overrides.jsonl --没有埋在Slack中 |
| 保留迁移上下文 | 分支快照记录了被替换的内容和不应返回的内容 |
| 轨道跨境deps | 共变信号检测传统代码和替换代码之间的耦合 |
看 参考.md 完整的遗产进化部分有学术基础（24篇已发表论文）。
团队支持
wisegit使用三层架构，不需要单独的“团队模式”：
| 层 | 什么 | 共享？ |
|---|---|---|
| 确定性基础 | 提交分类、基于规则的意图、git信号 | 通过git（自动） |
| 团队知识 | 丰富、覆盖、意图、分支上下文 | 通过 .wisegit/ （跟踪git） |
| 本地缓存 | SQLite位于 ~/.wisegit/wisegit.db |
从未（衍生） |
.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客户端之前，对错误消息进行了清理
- 文件写入前检查符号链接
- 仅使用分配的键解析配置文件（无原型污染）
路线图
- [x] 第一阶段 --事件存储、AST分块、提交分类、意图提取、MCP服务器、CLI
- [x] 第1.5阶段 --使用Won't Fix/By-Design检测问题丰富（GitHub、GitLab），冻结增强信号
- [x] 第2阶段 --完全冻结分数：调用图+PageRank、理论差距检测（Naur死亡、遗忘模式）、共同变化信号、Aranda信号、Ollama客户端、Go+Rust支持
- [x] 阶段4 --覆盖系统（强制原因、时间框到期、审计跟踪）、分支上下文保存（合并后挂钩、快照存储、恢复）
- [x] A阶段 --共享团队知识层：
.wisegit/包含JSONL文件的目录，用于丰富、覆盖、分支上下文和团队配置 - [x] B阶段 --团队意识体现：理论持有者跟踪、风险水平（健康/脆弱/危急）、团队状态+健康命令
- [x] 阶段C --AI时代的适应：提交来源检测（HUMAN/AI_REVIEWED/AI_UNREVIEWED）、来源加权冻结分数
- [x] D阶段 --覆盖审批工作流、团队健康指标
- [x] E阶段 --自适应淘汰校准：8个淘汰信号、熵校准权重、贝叶斯反馈、，
wisegit calibrate命令行界面
许可证
麻省理工学院
