Birdview

用 Birdview 改变你的开发工作流！将注意力从代码转向架构——打破 AI 编程的黑箱！

在 AI 改动发生之前看清它。

别再让 AI 盲目写代码。 使用 Birdview Skill 颠覆默认的编码流程：先绘制架构图，暴露 Agent 计划触及的模块，然后让它在证据可见的情况下进行编辑。Birdview 将架构描述和 Agent 声明的活动转化为独立的交互式 HTML 视图，让团队在变更发生之前看清将要改变什么。

项目主页： qiuner.github.io/birdview · 主题标签： agent-tools architecture-as-code code-visualization coding-agents developer-tools software-architecture

Birdview 通过让模型在编辑之前检查架构来提升编码质量。这种强制的上下文检查能尽早暴露受影响的模块，减少盲目改动，并使实现与周围系统保持一致。

Birdview activity view

截图使用的是本仓库内置的虚构 Agent harness，并不代表实际观察到的生产活动。

为什么选择 Birdview

AI 编码日志解释的是随时间发生了什么，而 diff 解释的是哪些行发生了变化。Birdview 补上了缺失的系统上下文：涉及哪些架构职责、哪些证据支撑着架构图、哪些模块在范围内，以及哪些内容经过了实际验证。

Birdview v0.1 提供：

带证据链接的架构图，具有稳定的模块 ID 和明确的文件归属。
同一布局下的架构视图、变更视图和并排对比视图。
针对架构图和活动历史的 JSON Schema 与语义验证。
自包含的 HTML 输出，无需服务器或网络依赖。
响应式的明暗主题、关系过滤和模块检查。
中英文界面控制，并支持以其他语言编写内容。

快速开始

要在你的 Agent 中使用 Birdview，请参阅安装指南。有关首个版本的功能与限制，请查看 0.1.1 发布说明。

要从源码检出运行演示：

Birdview 需要 Node.js 18 或更高版本。

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

在浏览器中打开 examples/harness-activity.html。该演示是由 examples/system.architecture.json 和 examples/harness.activity.jsonl 构建的模拟。

查看器指南

在查看器工具栏中打开指南，可获得聚焦式引导讲解：架构、当前变更、对比、模块证据和活动历史。没有活动记录的架构图只显示架构和证据步骤。首次访问的引导是可选的；可以随时关闭、跳过或按 Escape 键。退出后会恢复原始视图、记录、选择和缩放。文本跟随所选的中文/英文界面语言。在浏览器存储可用时，关闭状态会被记住；工具栏始终允许重新播放。

激活模式

Birdview 默认为 auto（自动）：每个涉及代码变更的任务都会先检查并复用/更新架构图，渲染它并在编辑前声明受影响的模块。它也覆盖显式的受影响模块规划。被显式设置为 on-demand（按需）的项目将保留该设置，需要 Birdview 或"编辑前先画图"的请求。你可以说"为本项目启用 Birdview 自动模式"或"切换到按需模式"，或者运行：

node <skill-root>/scripts/birdview.mjs mode auto --project <project-root>
node <skill-root>/scripts/birdview.mjs mode on-demand --project <project-root>
node <skill-root>/scripts/birdview.mjs mode --project <project-root>

该命令只管理项目 AGENTS.md 中属于它自己的代码块。“这次使用 Birdview"不会持久化任何设置。这是 Agent 指引，而非写入拦截器。参见模式与 CLI 设置。

渲染你的项目

创建一个符合 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

当需要中英双语编写时，可为验证器使用 --bilingual 参数。--simulation 参数仅用于渲染虚构的活动记录。

工作原理

project source ──> architecture.json ─┐
                                     ├──> validate ──> render ──> standalone HTML
agent declarations ─> activity.jsonl ┘

架构文件定义模块、职责、归属、证据、关系和布局。可选的 JSONL 流将有序的任务事件绑定到特定项目、架构图版本和一组模块 ID。渲染器在生成视图之前会验证这两份输入。

推荐的工作流包含两个有序阶段：

检查项目，建立或更新其有证据支撑的架构图，验证并审查渲染出的 HTML。
针对具体的编码任务，基于同一架构图版本声明计划范围、当前目标、文件、生命周期阶段和真实的检查结果。

完整工作流请参见阶段 1：为项目绘制架构图和阶段 2：展示变更。

数据契约

输入	用途
`architecture.json`	项目标识、模块、归属、证据、关系、分组和稳定布局
`activity.jsonl`	有序的、由 Agent 声明的任务范围、目标、文件、阶段和验证记录
`architecture.html`	生成的独立查看器，包含已验证的架构图和可选的活动历史

Schema 强制结构规范。scripts/validate.mjs 还会检查跨记录规则，例如稳定的架构图标识、连续的序列、有效的范围和目标、文件归属以及一致的检查结果。验证并不能证明架构声明是真实的，也不能证明引用的源文件存在。

项目结构

路径	内容
`schemas/`	架构和活动的 JSON Schema
`scripts/`	验证器、独立渲染器和文档检查
`assets/`	共享的查看器模板、样式、路由、活动和本地化代码
`examples/`	虚构的架构图、活动记录和生成的交互式演示
`references/`	编写工作流、契约、活动和双语指南
`test/`	契约、渲染和可选的浏览器级检查

当前边界

Birdview v0.1 刻意采用基于文件的方式：

活动由 Agent 声明；Birdview 不会自动观察编码操作。
更新需要重新生成 HTML 并刷新浏览器。
实时传输、自动刷新和渲染确认尚未实现。
completed 事件并不能证明检查通过；只有记录在案的检查结果才能支撑这一说法。
该包目前标记为 private，尚未发布到 npm。

开发

npm test                 # 契约与渲染器测试
npm run validate:examples
npm run build:demo       # 重建虚构活动演示
node scripts/check-docs.mjs

浏览器级检查位于 test/viewer.browser.mjs，需要本地 Playwright 安装，或通过 BIRDVIEW_PLAYWRIGHT_PATH 指向其路径。

有关字段语义和不变量，请阅读 Birdview 契约。文档变更必须遵循 CONTRIBUTING.md 中的双语规则。

Birdview 开源发布：别再让 AI 盲目写代码，每次改动前先绘制架构图