Birdview 是一款面向 AI 编码代理（AI agent）的架构可视化工具，在代理改动代码前先画出项目架构与约束地图，把 AI 编码的黑盒变成可审查的视图。本文拆解它的代码架构：一次完整的 TypeScript 迁移，如何把双轨 JS 代码库升级为严格类型的单一来源，让这款 AI 代理工具真正可靠。

🗺️ 为什么需要 Birdview：别让 AI 代理"盲写"代码

AI 代理直接搜索并修改代码时，你只能在事后逐行审查 diff——此时范围错误已经发生。Birdview 换了个顺序：

• 先展示地图：项目有哪些模块、各自负责什么、如何连接；
• 再确认变更：代理声明要改哪些文件、适用哪些约束规则，等你确认后才动手；
• 最后记录验证：实际跑过哪些检查、结果如何。

输出是一个独立 HTML 页面，用file://直接打开即可，无需服务器、无需联网。更多细节可看 README.zh.md 和查看器设计文档 docs/viewer-design.zh.md。

图中展示的是仓库内置的模拟代理 harness 演示，用于说明架构、更改与对照三种视图。

⚙️ 代码架构：TypeScript 成为唯一手写来源

迁移前的痛点很典型：.mjs手写实现与.mts实验代码并存，浏览器脚本靠文本拼接和隐式全局变量协作——一旦 AI 代理参与修改，双轨结构极易产生漂移。

迁移后的规则只有一条：手写源码只存在于src/，分发的 JavaScript 全部是生成产物。

build-artifacts.json 是一份显式的分发清单，列出了scripts/、assets/、docs/下每一个生成文件；打开 scripts/render.mjs 会看到第一行注释就写着"由src/render.mts生成，用npm run build重新生成"。手写实现和生成产物从此不再纠缠。

📜 核心决策：TypeBox + Ajv 构建数据契约

AI 代理工具最大的可靠性来源，是对"不可信输入"的防御。Birdview 选择用TypeBox 0.34.41 定义结构契约、Ajv 8.20.0 做运行时校验，类型从契约定义推导，而不是反过来手写两遍：

// src/contracts/parse.mts —— 契约编译为校验器，类型一并导出 export const checkArchitecture = ajv.compile<Architecture>(architectureSchema);

三条关键纪律：

1. 外部输入先按unknown接收，通过 Schema 校验后才收窄为类型；
2. 跨记录语义保持显式校验——版本绑定、事件顺序、约束引用不会因为对象"有类型"就自动成立；
3. JSON/JSONL 仍是面向 AI 的交换格式，契约单一来源，不维护平行的手写 Schema。

完整定义见 src/contracts/models.mts，AI 代理吐出的任何非法数据都会在校验层被拒绝，而不是让浏览器页面白屏。

🔒 严格编译配置：错误在编译期就出局

tsconfig.json 打开了 TypeScript 最严格的一档：strict、exactOptionalPropertyTypes、noUncheckedIndexedAccess、noEmitOnError。配套的质量门槛同样"不留后门"：

• 禁止用大范围any、@ts-nocheck或双重断言"伪装"迁移完成；
• 每批改动必须通过类型检查、构建产物对照和相关行为测试；
• 失败批次连同生成产物一起回滚，验收前保留旧发布版。

对 AI 辅助编码来说，这套配置等于给代理装上了护栏：写错类型直接编译失败，而不是带着隐患进入运行时。

✅ 六阶段迁移：每一步都有可验证证据

完整施工文档见 docs/typescript-migration.zh.md，各阶段验收不靠承诺，靠证据：

最终验证：80 项测试、五组 Chromium 浏览器套件、可复现构建、源码归档全新安装，npm audit零漏洞。

🚀 快速上手体验

只需 Node.js 18+，本地跑一遍即可感受"契约先行"的工程体验：

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

生成后在浏览器打开 examples/harness-activity.html，切换架构/更改/对照视图试试。Birdview 同样支持英文界面，同一份数据呈现为：

结语

Birdview 的 TypeScript 迁移不是框架重写，也没有性能承诺——它做的事情很朴素：让每个类型、每条契约、每个生成物都可追溯、可复现、可验证。这正是 AI 代理工具走向可靠的正确姿势：先约束，再编码。