Birdview

Birdview 是一款专为 AI 编码代理（Agent）设计的技能工具，改变传统的“直接修改代码”流程。它强制 AI 在动手编辑之前，先理清系统架构、明确影响范围，并生成可视化的证据链。

通过 Birdview，开发者不再是被动接受 AI 的代码变更，而是能够“先看清架构，再允许动手”。它将抽象的系统上下文转化为独立、可交互的 HTML 视图，让团队在改动发生前就能预判风险，确保 AI 的实现始终与周围系统保持一致。

核心痛点与解决方案

核心功能亮点 (v0.1)

1. 带证据的架构地图
   • 定义稳定的模块 ID、明确的文件归属和源码证据。
   • 支持中英文界面，内容可由用户自定义语言编写。
2. 多维度可视化视图
   • 完整架构视图：展示项目全貌。
   • 更改视图：高亮本次任务涉及的模块。
   • 并排对照视图：对比修改前后的状态。
   • 活动历史视图：追踪 Agent 的操作轨迹。
3. 严格的语义校验
   • 针对 architecture.json 和 activity.jsonl 进行 JSON Schema 校验。
   • 检查稳定地图标识、连续序号、合法范围、文件归属及一致性。
4. 零依赖独立输出
   • 渲染结果为自包含的 HTML 文件，无需服务器或网络资源即可在浏览器中打开。
   • 支持响应式明暗主题、关系筛选和模块详情查看。

工作原理

Birdview 的工作流分为两个阶段，通过标准化的数据契约连接：

1. 阶段一：建立/更新项目地图
   • 分析项目源码，生成或更新 .birdview/architecture.json。
   • 该文件定义了模块、职责、归属、证据、关系与布局。
2. 阶段二：表达变更与活动
   • Agent 在执行具体任务前，声明计划范围、目标、涉及文件及验证结果，记录为 .birdview/activity.jsonl。
   • 渲染器校验这两个文件，生成包含地图与活动历史的交互式 HTML 查看器。

快速开始

1. 环境准备

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

npm ci
npm run build:demo

2. 运行演示

在浏览器中打开 examples/harness-activity.html，体验由模拟数据生成的可视化效果。

3. 集成到 Agent

• 自动模式：每次改代码前自动检查并复用/更新架构图。

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

• 按需模式：仅在明确要求时介入。

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

4. 渲染你的项目

# 校验架构文件
node scripts/validate.mjs .birdview/architecture.json

# 渲染为 HTML
node scripts/render.mjs .birdview/architecture.json .birdview/architecture.html

为什么选择 Birdview？

• 提升编码质量：强制的上下文检查让 AI 在“看清”系统后再行动，显著减少低级错误。
• 增强团队信任：可视化的架构和影响范围让非技术人员也能理解 AI 的改动逻辑。
• 标准化协作：通过 JSON Schema 约束，使得架构描述和活动记录成为可机器读取、可版本控制的资产。
• 隐私安全：所有处理均在本地完成，生成的 HTML 不依赖外部服务，适合对数据安全有高要求的企业环境。