birdview

这是什么？适合谁？

Birdview（项目主页 qiuner.github.io/birdview，MIT，Node.js 18+）是一个**“先看架构再让 AI 改代码”的开发者工具**：它把两个此前分散的信息源合成一张图——

1. 架构图（architecture.json）：项目里有哪些模块、各自负责什么、谁拥有哪些文件、模块之间什么关系，每条都带证据链接；
2. Agent 活动记录（activity.jsonl）：编码 Agent 声明”我这次要动哪些模块、改哪些文件、检查结果如何”。

两者经校验后渲染成一个独立的、无服务器、无网络依赖的 HTML 文件，提供架构视图、变更视图和并排对比视图。README 的口号是”Stop letting AI code blind”——AI coding 日志解释”随时间发生了什么”，diff 解释”哪些行变了”，而 Birdview 补上缺失的那块：系统级上下文。

适合谁：重度使用 Claude Code / Codex 等 Agent 做日常改码、担心 AI”盲改”牵连无关模块的开发者与团队；需要向评审者直观展示”这次改动波及面”的工程师。

不适合谁：期望全自动拦截 Agent 写操作的用户（Birdview 是 agent guidance，不是 write interceptor）；需要实时看板/自动刷新的用户（v0.1 明确未实现 live transport）。

使用前提：Node.js ≥18；使用 Claude Code 等 Agent 时按 skill 方式接入，或直接用 CLI 渲染。

准备工作

1. 环境：Node.js 18 或更新版本（仓库徽章明确要求）
2. 获取：git clone https://github.com/Qiuner/birdview.git
3. 成本：MIT 开源，免费；无服务端、无网络依赖，零运行成本
4. 时间：10 分钟可跑通 demo；为真实项目建第一张架构图约 30-60 分钟（取决于模块梳理深度）
5. 前置知识：理解自己项目的模块划分；会用命令行
6. 替代方案：手动维护架构 Mermaid 图（免费但易过期）；商业代码地图工具（如 CodeSee 类，已停止服务）

快速上手（3 步）

第一步：跑通官方 demo 建立直觉

git clone https://github.com/Qiuner/birdview.git
cd birdview
npm ci
npm run validate:examples
npm test
npm run build:demo

然后用浏览器打开 examples/harness-activity.html——这是一个用仓库自带的示例数据（examples/system.architecture.json + examples/harness.activity.jsonl）生成的完整交互视图。

预期产出：一个可交互的 HTML 页面，含架构/变更/对比三个视图、关系过滤、模块检查和中英文界面切换。注意 README 标注：demo 使用仓库内置的虚构 agent harness 数据，不代表真实生产活动。

第二步：为你的项目写架构文件

参照 schemas/architecture.schema.json 创建 .birdview/architecture.json，定义模块、职责、文件所有权、证据、关系和布局。核心字段：模块 ID（stable module IDs）、每个模块的文件清单、关系边。

预期产出：一份描述你项目的架构 JSON，可被校验器接受。

第三步：校验并渲染

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

如需展示 Agent 声明的活动历史，把 activity.jsonl（有序任务事件、绑定到具体 map revision 和模块 ID）一起传入：

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

校验器还会检查跨记录规则：map 身份稳定、序列连续、scope/target 合法、文件所有权一致。双语言内容用 --bilingual；虚构活动记录用 --simulation。

预期产出：architecture.html 或 activity.html——独立可分享的交互视图（可发给评审者，对方无需安装任何东西）。

常见踩坑（症状 → 原因 → 解决）

1. 期望它自动监控 Agent 的每一次操作。症状：装好后发现”活动记录是空的”。原因：Birdview v0.1 是 file-based 的，activity 由 Agent 声明写入，工具本身不自动观察编码操作。解决：在 Agent 的工作流里要求其按 schema 写 activity.jsonl（配合 Claude Code skill 模式）；这是设计边界不是 bug。
2. 改了架构图页面没变。原因：当前版本需要重新渲染 HTML 并刷新浏览器，没有自动刷新。解决：重跑 render.mjs 后刷新页面；把校验+渲染写进一个小脚本减少操作成本。
3. 以为 completed 就等于检查通过。原因：schema 允许 Agent 报告任务完成，但 README 明确 “A completed event does not prove checks passed; only recorded check results make that claim”。解决：审计视图时看的是 check results 字段，不是完成状态。
4. 把 demo 当真实证据。原因：仓库自带 demo 是虚构 harness 数据，README 明确标注不代表真实生产活动。解决：用自己项目的数据重新渲染。
5. npm 上找不到这个包。原因：README 明确 “The package is currently marked private and is not published to npm”。解决：从 GitHub 源码安装使用，不要 npm install birdview。
6. 误以为校验器保证架构描述真实。原因：validate.mjs 只校验结构一致性与跨记录规则，“Validation does not prove that architecture claims are true or that referenced source files exist”。解决：架构图的证据链接（evidence）质量靠人/Agent 维护。
7. README 项目主页打开是英文。原因：英文版是默认入口。解决：页首有”简体中文”链接直达 README.zh.md；viewer 界面本身可切中英文。
8. skill 模式下 Agent 只声明不更新图。症状：Agent 声明受影响模块但架构图还是旧的。原因：auto 模式要求”复用或更新”两选一，Agent 偷懒只复用旧图。解决：在任务 prompt 里明确要求”若模块边界变化，先更新 architecture.json 再渲染”。

初级用法

• 每次 AI 改码前先渲染一次：把”渲染架构图 → 看受影响模块 → 再放行 Agent”固化为小 ritual，这正是 README 推荐的两阶段工作流（先建图，再按图声明 scope）。
• auto / on-demand 两种激活模式：node <skill-root>/scripts/birdview.mjs mode auto --project <project-root> 让每个改码任务先过架构图；mode on-demand 则显式请求才触发。配置只写进项目 AGENTS.md 里 Birdview 自己的块。
• 用对比视图做代码评审：渲染”改动前/改动后”两版视图，并排看模块受影响差异。

高级玩法

• 接入 Claude Code skill 目录：把 Birdview 作为 agent skill 安装（docs/installation.md 有完整步骤），Agent 在改码前自动复用/更新架构图并声明受影响模块——从”人看着办”升级为”Agent 被迫先交底”。
• stable module IDs 做长期治理：架构图里的模块 ID 是稳定的，可以把多轮 Agent 活动绑到同一套 ID 上，形成跨任务的”谁动过哪个模块”审计链。
• 证据链接约束文档漂移：每个模块的职责声明必须带 evidence，配合校验器跨记录规则，把”架构文档过期”变成可检测状态。

小技巧

1. 先用仓库自带 demo（examples/harness-activity.html）点开 toolbar 的 Guide——官方 spot­light 漫游会依次讲架构、当前变更、对比、模块证据与活动历史五个视图，比读文档快。
2. --bilingual 校验适合中英双语团队协作的架构图；--simulation 只能用于虚构活动记录，别用在真实数据上。
3. Viewer 支持明暗两套主题与关系过滤，模块多时先过滤关系边再看整体。
4. 架构图建好后把它纳入 Agent 每轮必读上下文，“evidence in view” 是这个工具的核心价值，不是装饰。
5. 中文用户直接读 README.zh.md，文档是中英双语完整的。

常见问题 FAQ

Q1: 它和直接看 git diff 有什么本质区别？

A: diff 回答”哪些行变了”，日志回答”随时间发生了什么”，Birdview 回答”架构上哪些职责被波及、有什么证据支撑这张图、哪些模块在范围内、实际验证了什么”——系统级上下文是前两者缺失的维度。

Q2: 会不会拖慢我的 AI 编码流程？

A: 默认 auto 模式要求每个改码任务先”检查→复用/更新架构图→渲染→声明受影响模块”再动手，多一步前置工作。可切 on-demand 模式按需触发。README 定位是”用强制上下文检查换取更少盲改”。

Q3: 能直接 npm install 吗？

A: 不能。包目前标记 private、未发布到 npm，从 GitHub 源码安装。

Q4: 输出的 HTML 能分享给没装环境的同事吗？

A: 可以。输出是 standalone HTML，无服务器、无网络依赖，对方用浏览器直接打开。

Q5: 和商业代码地图/架构可视化工具比，差距在哪？

A: Birdview v0.1 是纯本地、文件驱动的轻量方案：无实时监听、无自动刷新、无渲染端确认回执；换来的是零成本、零网络依赖和 schema 可校验的数据契约。适合个人/小团队，企业级实时治理需等后续版本。

免责声明

本文基于公开资料整理（GitHub 仓库 README 与项目主页，核验日期 2026-09-14），AI 辅助生成，未在真实项目中长期使用验证。仓库创建于 2026-09-12（2 天），处于早期版本（v0.1.1），功能边界以官方 release notes 为准。

参考链接

• GitHub 仓库 Qiuner/birdview
• 项目主页 qiuner.github.io/birdview
• 在线 Demo harness-activity.html
• 安装文档 docs/installation.md
• 中文文档 README.zh.md