Birdview：让 AI 改代码前先画架构图，把「黑盒改动」变成看得见的模块清单

一句话概括：这不是又一个 AI 编程助手，而是给所有 AI 编程助手加的一道前置动作——动手改代码之前，先把系统架构画出来、把要碰的模块圈出来。

一个被忽略的问题：AI 改代码是”盲改”

过去两年，AI 编程工具的能力一路飞涨：能读整个仓库、能跨文件重构、能自己跑测试。但有一个环节几乎没变——AI 在动手之前，并不真的”看见”这个系统。

它看到的是一堆文件片段和检索结果。它不知道某个文件的改动会牵动哪些上游、哪些模块只是邻居而不是目标、哪些职责边界不能越过。于是就有了那些熟悉的事故现场：

• 改了一个看似孤立的工具函数，结果三个调用方全崩了
• 修复 A 模块的 bug，顺手把 B 模块的隐式契约破坏了
• 提交信息写着”小改动”，实际 diff 涉及 20 个文件

日志能告诉你发生了什么，diff 能告诉你哪几行变了，但没有任何东西告诉你：这次改动在系统里的位置在哪、影响了哪些职责。

这就是 Birdview 想补上的那一块。

Birdview 是什么

Birdview 是一个给 AI 编程智能体用的技能（Skill），作者 Qiuner，MIT 协议，当前版本 0.2.0。它的口号很直接：

Stop letting AI code blind.

See AI changes before they happen.

它做的事情可以拆成两阶段：

1. 先建图：检查项目、建立或更新一张带证据链的架构地图，校验后渲染成 HTML，然后人眼看一遍确认

2. 再声明：真正要改代码时，先声明计划范围、当前目标文件、所处生命周期阶段以及真实的检查结果——全部绑定到同一份地图版本上

关键点在于：声明发生在编辑之前。等 AI 已经改完了再画图，那只是事后报告；在编辑前圈出模块，才是给这次改动设了一道可见的闸门。

核心机制：架构是代码，地图有证据

Birdview 的数据模型非常克制，全部是纯文件：

architecture.json 描述”这个系统由什么组成、谁负责什么、依据是什么”，activity.jsonl 描述”这次任务要动哪里、做到哪一步了”。

渲染器的输出是一个自包含的 HTML 文件——没有服务器、没有网络依赖，双击就能在浏览器里打开。对于需要走内网、或者要把架构视图发给同事的场景，这一点相当实用。

地图里到底有什么

打开官方的演示视图（examples/harness-activity.html），你会看到一个典型的三段式布局：

• Interaction & review（交互与评审）：Workbench 提交目标、检查计划；Change review 检查 diff、批准操作
• Harness runtime（运行时）：Session control、Context builder、Model gateway、Task scheduler、Agent loop、Policy & approval、Events & checkpoints、Context cache、Tool executor
• External execution & services（外部执行与服务）：Model provider、Sandbox workspace、MCP services

每个模块都带类型标注——前端、后端、安全、任务/队列、数据存储、缓存，或”通用”。演示图里的统计是 14/20 个模块、15/20 条关系，处于”模拟运行、无真实执行”状态。

而一次具体的任务声明长这样：

Simulated plan: add tool timeouts and cancellation, propagate cancellation through the scheduler, and handle termination in the execution loop.

对应的地图上，Task scheduler 被标为”计划范围”，Agent loop 和 Tool executor 被标为”下一步目标”——哪个模块这次要动、哪个是稍后要动，一眼分得清。

而且要看三种视角随时切换：Architecture / Changes / Compare，同一个布局上分别看架构全貌、本次变更、以及左右对照。

工程上值得称道的地方

看了一圈它的实现，有几个细节比宣传语更有说服力：

模块 ID 稳定，归属与证据分离。 地图里模块有稳定的 ID，文件归属（ownership）和证据（evidence）是两个独立字段。README 里反复强调邻居不等于编辑目标——这个区分在真实重构里非常重要，因为 AI 最容易犯的错就是”顺手把旁边的也改了”。

校验器真的在校验。 scripts/validate.mjs 不仅校验 JSON Schema，还检查跨记录的规则：地图身份是否稳定、序列是否连续、scope 和 targets 是否合法、文件归属是否冲突、检查结果是否自洽。用 --bilingual 可以要求中英双语内容齐备。

它非常诚实地说明自己做不到什么。 这是我最欣赏的一点。README 专门有「Current Boundaries」一节：

• 活动是智能体声明的，Birdview 不会自动观测编码操作
• 更新需要重新生成 HTML 并刷新浏览器，没有实时传输
• 一个 completed 事件不能证明检查通过，只有被记录的检查结果才能这么说
• 校验通过不代表架构声明为真，也不代表引用的源文件真实存在
• 包目前标记为 private，没有发布到 npm
• 它是智能体指导，不是写入拦截器

市面上太多工具在模糊声明和事实的边界，这种把”我知道什么、我不知道什么”写清楚的做法，反而更容易让人信任。

怎么用起来

环境要求很低：Node.js 18 或以上，没有其他后端依赖。

从源码检出跑通演示：

npm ci
npm run validate:examples
npm test
npm run build:demo

渲染你自己的项目，先写一份符合 schemas/architecture.schema.json 的架构文件，然后：

node scripts/validate.mjs .birdview/architecture.json
node scripts/render.mjs .birdview/architecture.json .birdview/architecture.html

带上声明的活动历史：

node scripts/validate.mjs .birdview/architecture.json .birdview/activity.jsonl
node scripts/render.mjs .birdview/architecture.json .birdview/activity.html .birdview/activity.jsonl

它还会在项目的 AGENTS.md（或 Claude Code 的 CLAUDE.md）里维护一小段自己的配置块，用来控制激活模式：

node /scripts/birdview.mjs mode auto --project 
node /scripts/birdview.mjs mode on-demand --project 

• auto（默认）：每一个会改代码的任务，都先检查并复用/更新地图、渲染出来、声明受影响模块，然后才动手
• on-demand：只有明确要求”画架构图”或”编辑前先看变更地图”时才激活

导入安装的完整步骤见仓库的 docs/installation.md。

谁适合用

我觉得三类团队会立刻感受到价值：

一、代码库已经大到”没人全懂”的项目。 架构图的价值从来不在于画得漂亮，而在于逼着 AI（和人）在动手前把上下文对齐一次。这个”强制检查”本身就是质量保障。

二、用多个 AI 编程助手协作的团队。 Birdview 是技能形态，不绑定具体厂商——Claude Code、Codex、DeepSeek Harness 都能接。同一份架构地图可以成为不同智能体之间的共同语言。

三、需要把 AI 改动留档、可审计的场景。 每次任务的范围、目标文件、验证结果都落在 activity.jsonl 里，是纯文本、可 diff、可入库。相比”AI 说它改好了”，这是更硬的证据。

值得注意的取舍

Birdview 目前是文件驱动的，这意味着它没有实时的面板、没有自动刷新、也没有和 IDE 的深度集成。你改完架构要重新渲染、重新刷新浏览器。对习惯了实时工具的人来说，这个体感是”隔一层”的。

另外，它的地图质量取决于写地图的那一次分析质量。工具本身不能保证架构声明的真实性——它只保证结构合法、前后自洽。所以第一次建图仍然值得人来审一遍。

但换个角度看，纯文件、无服务、可 diff、可入库，恰恰是它最容易嵌进现有 CI 和代码评审流程的原因。这是一个很清醒的设计取舍，而不是能力不足。

项目信息

• 仓库：github.com/Qiuner/birdview
• 项目站点：qiuner.github.io/birdview
• 在线演示：examples/harness-activity.html（也可在项目站点打开）
• 协议：MIT License · Copyright (c) 2026 Qiuner
• 版本：0.2.0 · 需要 Node.js 18+
• 热度：发布几天即获得 300+ Star，且仍在持续更新

如果你也在被”AI 改代码改出新 bug”困扰，Birdview 值得花二十分钟试一下——哪怕最后不用它，它提出的那个问题也很有价值：在让 AI 动手之前，你有没有先让它把系统看明白？