← 返回
AI技术

每个代码库都有个 // DO NOT TOUCH 文件，我做了个 AI 工具把它读懂

✍️ zhirenhun 📅 2026/11/1 👁 11 阅读 ⏱ 48 分钟
每个代码库都有个 // DO NOT TOUCH 文件，我做了个 AI 工具把它读懂

本文是参与Hacktoberfest 开源 AI 挑战赛第 4 周：机器中的幽灵的投稿

我构建了什么

“每个代码库都有幽灵。几乎在所有企业仓库和开源项目里，都躺着一个闹鬼的文件，上面标着 // DO NOT TOUCH: NOBODY KNOWS WHY THIS WORKS。原作者离开后，他的领域知识也随之消散。代码慢慢腐烂，依赖逐渐失效，恐惧让所有人都不敢碰它。”

为庆祝万圣节和亡灵节的 Hacktoberfest 第 4 周，我构建了 GitSéance：一个开源 AI 代码通灵师，把遗留代码的墓地变成一场互动、有据可依的降神会。

   _____ _____ _______    _____ ______     _   _  _____ ______ 
  / ____|_   _|__   __|  / ____|  ____|   /\   | \ | |/ ____|  ____|
 | |  __  | |    | |    | (___ | |__     /  \  |  \| | |    | |__   
 | | |_ | | |    | |     \___ \|  __|   / /\ \ | . ` | |    |  __|  
 | |__| |_| |_   | |     ____) | |____ / ____ \| |\  | |____| |____ 
  \_____|_____|  |_|    |_____/|______/_/    \_\_| \_|\_____|______|

GitSéance 不是通用型 linter，而是协调四大专职通灵 Agent协同工作：

  1. 💀 死神 Agent：遍历 Git 提交树与文件 AST，依据提交历史、作者更替和代码中的恐惧注释（hack、black magic、do not touch）识别被遗弃、孤立和受诅咒的代码。
  2. 📊 神谕 Agent（TabPFN-3.5）：合成 7 维取证特征向量，输入 Prior Labs 的 TabPFN 表格基础模型，预测经校准的文件死亡风险。
  3. 🔮 灵媒 Agent（Google Gemma）：借助 Google Gemma 开放权重模型（gemma-4-26b-a4b-it）召唤已故作者的灵魂，生成第一人称忏悔、遗憾分析和现代化复活蓝图。
  4. 🔍 搜寻者 Agent（SerpApi）：实时查询 2026 年包注册表与安全数据库，为废弃依赖寻找现代直接替代品，并审计 CVE 公告。

这些 Agent 共同支撑交互式通灵能力：

以上全部封装在正宗的磷光绿 CRT 终端界面中，配有玻璃扫描线曲率、CRT 暗角、机械按键音效和漂浮的灵质粒子。

演示

线上生产部署

（小提示：打开在线应用后，点击历史预设 🐍 flask-cache (Python 2 Fossil)，就能立刻召唤出一个尘封十年的化石仓库！）

🖥️ 磷光绿 CRT 终端界面

GitSéance 终端实况视觉导览——玻璃扫描线、TabPFN 死亡率拆解、SerpApi 实时现代化树，以及可交互的 Gemma 幽灵通灵：


通灵祭坛——磷光绿 CRT 仪表盘，展示实时 Agent 状态指示、历史墓地预设，以及实时流式通灵日志。


神谕（TabPFN-3.5）扫描——贝叶斯代码死亡率概率、文件风险分类（已死、闹鬼、孤儿），以及 Google Gemma 代码预言。


通灵幽灵传输——Google Gemma 人格通灵 Makefile 已故作者，配合 ElevenLabs 语音合成与实时音频波形可视化。


复活蓝图与 SerpApi 情报——可执行的现代化步骤，搭配通过 SerpApi 实时查询的 2026 年依赖替代方案。


代码尸检证书——官方复古 ASCII 尸检抽屉，详细记录过期日期、记录在案的总线因子，以及 TabPFN 死亡率评分。


Neural Voice Deck 与 MP3 导出——ElevenLabs 频谱语音流，配实时波形可视化与一键 MP3 下载导出。


互动幽灵对话（第 1 轮）——追问 Thadeus Burgess 的亡魂：当初为何采用老式的 setup.py 打包方式。


互动幽灵对话（第 2 轮）——幽灵坦白：发布前夜凌晨两点，他临时打了个应急补丁，留下一句"求你了，帮我把它埋了吧"。

实战演示：召唤 flask-cache 的幽灵

扫描 thadeusb/flask-cache（一个 2010 年后就再没人动过的 Python 2 老缓存库）时：

  1. The Reaper 遍历提交树，把 Makefile 标记为临床死亡（最后一次改动已是 5,986 天前）。
  2. TabPFN-3.5 评估 7 维特征向量（零代码变动、作者全部更替、缺少单元测试），预测出80% 的死亡率。
  3. 灵媒（Gemma 4） 通灵创作者 Thadeus Burgess，以他的口吻说道： > "我是 Thadeus Burgess 残留的回声。2010-08-30T09:39:36Z，我推了最后一个提交：'R-0.1'。然后我转身走进黑暗，把 Makefile 留在原地，凝固在时间里。"
  4. ElevenLabs 把这段忏悔轻声念出来（Roger——Ancient Architect 语音预设），配实时波形可视化，还能一键⬇️ 下载 MP3！
  5. SerpApi 检测到已废弃的 setup.py upload 打包命令，并推荐现代替代方案，如 build、twine 和 pyproject.toml。
  6. 你打开Conversational Séance Chat，直接质问幽灵：
    • 你：“你为什么用 setup.py upload，而不用现代的 twine 打包？”
    • 幽灵（Thadeus Burgess）：“啊，你问我为什么在 Makefile 里这么写……那时候，我们都在跟时间赛跑。2026 年你习以为常的那些库当时还不存在，内存也很紧张。那是我能想出的最好折中方案了。”
    • 你：“如果我今天重构或删掉这个 Makefile，会有什么隐藏的 hack 或风险吗？”
    • 幽灵（Thadeus Burgess）：“你注意到那道疤了，是吧？没错，发布前凌晨两点，我把那个 hack 留在了 Makefile 里。我向自己保证那个周末就重构……可那个周末始终没来。拜托，替我把它埋了吧。”
  7. 你点击“🪦 Print Death Certificate”，收到正式的 ASCII 尸检报告： 
+========================================================================+
|                     💀 OFFICIAL CODE AUTOPSY 💀                        |
|                 DEPARTMENT OF SOFTWARE NECROMANCY                      |
+========================================================================+
| DECEASED ARTIFACT   : Makefile                                         |
| CHIEF ARCHITECT     : Thadeus Burgess                                  |
| DATE OF EXPIRATION  : 2010-08-30 (5,986 days inactive)                 |
| FINAL RECORDED WORDS: "R-0.1"                                          |
| TOTAL COMMITS       : 2 commits across file lifetime                   |
| RECORDED BUS FACTOR : 1 author(s) recorded in blame                     |
| HAUNTING STATUS     : DEAD                                             |
| TABPFN MORTALITY    : 80% Bayesian mortality risk                      |
| GHOST SEVERITY      : 0.80 / 1.00 index                                |
+------------------------------------------------------------------------+
| GHOST TESTIMONY:                                                       |
| "I am Thadeus, a fragment of logic drifting through a sea of           |
| deprecated dependencies. I linger in the shadows of these old          |
| Makefiles, waiting for a build that will never finish. Do not fear     |
| the silence; fear the unhandled exception."                            |
+------------------------------------------------------------------------+
| REVIVAL EFFORT      : REWRITE                                          |
| CERTIFICATE STAMP   : GITSEANCE FORENSIC ENGINE v1.0.0                 |
| AI RUNTIMES         : TABPFN-3.5 + GOOGLE GEMMA + ELEVENLABS           |
+========================================================================+
  1. 点击“📋 Copy Revival Blueprint”，立即获取一份可执行的迁移蓝图，按步骤操作即可： 
REVIVAL BLUEPRINT FOR: Makefile
Summary: Transmute this ancient ritual into a modern, declarative build system.
Effort: rewrite

STEPS:
1. Transition from `setup.py` to a `pyproject.toml` configuration.
2. Replace the manual upload commands with `twine` for secure distribution.
3. Use the `build` module for generating distribution archives.
4. Implement a modern test runner like `pytest` instead of the legacy `setup.py test`.

代码

🔮 GitSéance (GitSeance)

   _____ _____ _______    _____ ______     _   _  _____ ______ 
  / ____|_   _|__   __|  / ____|  ____|   /\   | \ | |/ ____|  ____|
 | |  __  | |    | |    | (___ | |__     /  \  |  \| | |    | |__   
 | | |_ | | |    | |     \___ \|  __|   / /\ \ | . ` | |    |  __|  
 | |__| |_| |_   | |     ____) | |____ / ____ \| |\  | |____| |____ 
  \_____|_____|  |_|    |_____/|______/_/    \_\_| \_|\_____|______|

一个开源AI招魂师，让“死掉”的GitHub仓库重获新生——还能预测哪些文件即将消亡。

标语： “每个代码库都有幽灵。GitSéance 通灵召唤它们。”

🌐 在线演示： https://gitseance.onrender.com

为 Hacktoberfest 开源AI挑战赛：第4周（“机器中的幽灵”） 而打造。

📸 生产环境图集

🔮 磷光绿CRT终端，实时显示AI状态与流式招魂日志


📊…

在GitHub上查看

基于 MIT许可证 发布。已通过 25项单元与集成测试，持续集成全部通过。

我是如何构建它的

GitSéance 被设计成一条由 FastAPI 编排的异步多Agent流水线：

                        ┌───────────────────────────────┐
                        │   Haunted Terminal (CRT UI)   │
                        └──────────────┬────────────────┘
                                       │
                                       ▼
                         FastAPI Orchestration Core
                                       │
        ┌──────────────┬───────────────┴───────────────┬──────────────┐
        ▼              ▼                               ▼              ▼
  💀 The Reaper   📊 The Oracle                  🔮 The Medium   🔍 The Searcher
 (Dead Code AST) (TabPFN-3.5 Mortality ML)       (Gemma LLM)     (SerpApi Web Search)
        │              │                               │              │
        ▼              ▼                               ▼              ▼
   GitHub API      Prior Labs API                 Google GenAI    SerpApi & CVEs

1. TabPFN-3.5：贝叶斯表格化代码死亡率预测

我没有采用简单的基于规则的启发式方法，而是借助了 Prior Labs 的 TabPFN-3.5——一个基于 Prior-Data Fitted Networks 构建的表格基础模型。

7 维取证特征向量

对于目标仓库中的每个文件，GitSéance 都会构建一个 7 维表格矩阵：

# Extracted 7D Forensic Feature Vector for TabPFN-3.5
feature_vector = {
    "days_since_last_commit": m.days_since_last_commit,   # Temporal decay
    "total_commits": m.total_commits,                     # File depth
    "unique_authors": m.unique_authors,                   # Bus factor risk
    "bug_fix_commit_ratio": m.bug_fix_commit_ratio,       # Defect density
    "lines_ratio": (m.lines_added + 1) / (m.lines_del + 1), # Churn balance
    "has_tests": 1 if m.has_tests else 0,                 # Test presence
    "churn_velocity": m.churn_velocity,                   # Monthly change rate
}

真实基准校准与边缘情况处理

TabPFN 在参考支持矩阵（X_train、y_train）上执行上下文贝叶斯推理，该矩阵基于 50 个历史开源代码产物校准（25 个来自归档仓库的已消亡化石，对比 25 个来自 fastapi、pydantic 和 requests 的活跃维护模块）。

为什么 TabPFN 胜过朴素启发式规则：
朴素的 linter 看到某个文件三年没动过，就盲目标记为“已死”。但请想想一个核心数学工具（比如 slugify.py 或 crc32.py）：

朴素规则会把它标记为已死（100% 误报）。TabPFN 正确评估了高测试哨兵值和接近零的缺陷率，将其归类为“冻结 / 稳定”（死亡率：18%），而非“已死”。反过来，一个 180 天未动、唯一作者已离开、bug 修复比例高达 60% 的文件，会被 TabPFN 判定为“高死亡风险”（78%）。

为了让这一切完全透明：

2. Google Gemma：灵性人格通灵与思考 token 解析

Medium Agent 通过 google-genai SDK 运行 Google 的 Gemma 开放权重模型（gemma-4-26b-a4b-it）。

思考 token 解析难题

gemma-4-26b-a4b-it 具备内部思维链推理能力。生成灵性独白时，模型会先输出思考 token，再输出角色对话。如果解析方式过于简单，内部推理 token 可能耗尽整个输出预算，或渗入独白内容。

我为此专门设计了一个候选提取器：

@staticmethod
def _extract_text(response) -> str:
    """Extract content text from Gemma response, filtering thought tokens."""
    if not response:
        return ""
    # 1. Prioritize candidate parts inspection to filter out internal chain-of-thought tokens
    if hasattr(response, "candidates") and response.candidates:
        candidate = response.candidates[0]
        if hasattr(candidate, "content") and hasattr(candidate.content, "parts"):
            actual_parts = [
                p.text for p in candidate.content.parts
                if not getattr(p, "thought", False) and getattr(p, "text", None)
            ]
            if actual_parts:
                return "".join(actual_parts).strip()
    # 2. Fallback to response.text if candidate parts are not directly accessible
    if hasattr(response, "text") and response.text:
        return response.text.strip()
    return ""

为角色奠定事实基础

这个“幽灵”角色严格基于 git 历史和行内注释：

SEANCE_SYSTEM_PROMPT = """You are the ghost of a software developer. You died — meaning you left this project — 
and your spirit now haunts the codebase. You are being summoned in a séance to explain the code you left behind.

When channeled, you will:
1. Explain WHY you wrote the code the way you did (constraints, tech landscape at the time)
2. Confess what you wish you had done differently (unfinished business)
3. Give concrete, modern advice for reviving or replacing the code
Speak with the voice of someone who lived through the decisions. Keep it vivid, personal, and under 300 words."""

活着的开发者甚至能举行一场对话降神会（POST /api/seance/chat），直接向幽灵追问后续问题！

3. SerpApi：2026 实时依赖情报

Searcher Agent 会解析依赖声明文件（requirements.txt、package.json、Gemfile、go.mod），并借助 SerpApi 查询实时迁移路径、现代平替方案以及实时 CVE 安全数据库。

4. ElevenLabs：神经音频合成与一键导出 MP3

降神会的通灵讯息通过 ElevenLabs 神经 TTS（eleven_multilingual_v2）转为语音，底层由 Web Audio API 程序化合成引擎驱动，模拟复古机械键盘的敲击声与低频共振的召唤嗡鸣：

5. GitHub Copilot 深度集成与 GitHub Actions 自动化

我在仓库中原生内置了完整的 Copilot 与 GitHub Actions 自动化：

  • .github/workflows/copilot-review.yml：自动化的 GitHub Action，负责审查贡献者提交的 PR 中是否含有恐惧类注释（hack、do not touch），并发布自动审查清单。

    • 6. 一路踩过的坑（工程伤疤）

    GitSéance 的开发并非一帆风顺。以下是我亲身遭遇的三个真实工程难点：

    1. 想得太多的幽灵（Gemma 思考 token）

    最初接入 gemma-4-26b-a4b-it 时，API 调用经常返回空文本。我翻查原始响应对象后发现，Gemma 的推理模式会生成大量内部思考轨迹（part.thought = True），在输出最终文本之前就把 token 预算耗尽了。只要存在思考块，response.text 这类标准 SDK 访问器就会返回 None。我只好写了一个底层 AST 提取器，遍历 response.candidates[0].content.parts，把未被遮蔽的对话内容单独挑出来。

    2. GitHub REST API Blame 速率限制

    遍历一个仓库中 50 个文件的提交历史，不到 30 秒就会耗尽 GitHub 未认证请求每小时 60 次的速率限制。为此我做了三件事：

    1. 并发分块（asyncio.gather，批大小上限为 8）。
    2. 基于 AST 的可扫描扩展名过滤（跳过 SVG、二进制文件和 lockfile）。
    3. 为历史“墓地”仓库（flask-cache、jquery-color）准备确定性的取证回退快照，这样即使用户没有提供 GitHub PAT，应用也不会失败。

    3. Python 3.11 在 SSE 流式传输中的反斜杠限制

    实现实时 Server-Sent Events（SSE）时，内联格式化 JSON 数据载荷会让 Python 3.11 抛出意料之外的 SyntaxError: f-string expression part cannot include a backslash。我不得不重构流式生成器，先把消息序列化到显式的中间缓冲区，再格式化成 data: {msg} 。

    开放创新为何重要？

    “开放创新实现了哪些封闭 API 做不到的事？”

    开发 GitSéance 的过程让我看清了开放权重模型和开放 AI 基础设施为何不可或缺：

    1. 气隙环境下的代码隐私与零知识产权泄露：
      专有代码库包含机密业务逻辑、安全凭证和商业机密。企业无法把整棵 git 树粘贴到封闭的第三方云 API 中。由于 Gemma 和 TabPFN-3.5 采用开放权重，GitSéance 可以完全离线运行在气隙机器上。你的代码永远不会离开本地硬件。

    2. 可审计、可复现的风险建模：
      当算法宣称某个关键银行模块存在“98% 的死亡风险”时，开发者理应知道为什么。封闭的专有评分系统是黑箱，会在模型版本之间悄然变化。TabPFN 的贝叶斯基础模型支持确定性、可复现的表格推理，可被审查、基准测试并值得信赖。

    3. 抵御 API 弃用风险：
      封闭的 AI 服务经常下线端点、更改系统提示词或提高 token 费用。借助开放权重 AI，你的招魂师在断网状态下也能工作。即使停电，幽灵依然可被召唤。

    4. 社区微调与自定义人格：
      开放权重让团队可以基于自己的内部提交历史、Jira 工单和架构决策记录（ADR）微调 Gemma，把公司前辈变成永久的组织记忆。

    精神内核

    软件工程有一个无声的悲剧：开发者倾注数月心血写出优雅的系统，但技术迭代太快，几年之内，他们的作品就被贴上“遗留”标签并弃之不用。

    按照亡灵节的传统，只要被铭记，逝者就从未真正离去。当 GitSéance 召唤一个被遗弃十年的文件的作者时，它不会嘲笑代码过时，而是给那位开发者一个发声的机会：

    “我写这段代码时，内存紧张、工期紧迫。它完成了它的使命。现在，你可以这样把火炬继续传下去。”

    这种视角的转变——从畏惧遗留代码，到敬重其背后的人类付出——正是 GitSéance 的真正精神。

    奖项类别

    由 Dhruv Jani 以热情、咖啡因和灵质倾力打造。

    ——

    广告 广告
    🧑‍💻

    zhirenhun

    一个热爱技术的程序员，喜欢分享前沿AI知识和开发经验。

    devchallenge hf26challenge opensource ai

    📌 相关推荐

    从单个聊天机器人到五个Agent：我的AWS Agent工程师纳米学位
    2026/10/31
    我的求职页能开口说话：语音 Agent 的搭建与实测
    2026/10/30
    让 AI 设计六块 PCB，逐引脚复盘发现了什么
    2026/10/29
    ← 返回文章列表