从安装到第一张架构图：Windows 上手 Birdview 完整指南

摘要

我第一次接触 Birdview 时，真正想验证的不是它能不能画出漂亮的架构图，而是这套流程能否自然进入日常 AI Coding：安装是否复杂，Agent 能否在正确时机发现技能，生成的图是否来自项目证据。实际梳理后我发现，Birdview 的上手过程可以分成三个独立环节：先把完整技能安装到宿主能够发现的位置；再用只读自检确认 Node.js 依赖、数据校验器和 HTML 渲染器正常；最后在新的 Agent 任务中明确调用 Birdview，让它检查已有地图、分析项目源码并生成.birdview/architecture.json与独立 HTML。这里最容易混淆的是“安装成功”“自检通过”和“真实触发成功”并不是同一件事：doctor能证明内置示例可以校验和渲染，却不能证明宿主已经加载技能；项目模式命令能写入 Agent 规则，却不是文件拦截器。本文以 Windows PowerShell 和 Codex 为主线，讲清安装、模式配置、首次建图、产物检查和常见问题，帮助你生成第一张架构图，也避免把成功打开的页面误解成对 Agent 行为的自动审计。我还会说明为什么要在新任务里验证宿主发现、为什么不能只复制一个说明文件、为什么默认按需模式更适合初次试用。即使从未配置过编码代理技能，也可以沿着这些检查点逐步定位失败发生在文件安装、依赖、自检还是调用阶段。每一步都有不同的成功信号，不能用其中一项替代整条链路。

图 1：Birdview 独立 HTML 查看器。截图使用项目内置的虚构演示数据，不代表生产环境中的真实 Agent 活动。

一、开始前先理解三个层次

Birdview 不是一个需要常驻后端的 SaaS，也不是安装后自动接管所有编辑动作的 IDE 插件。它由技能说明、数据契约、Node.js 校验与渲染脚本、浏览器查看器等部分组成。Agent 读取技能工作流，分析目标项目，然后把结果写成结构化数据和独立 HTML。

上手时需要依次确认三个层次：

这三个层次不能互相替代。比如，校验器输出ok: true，只能说明输入符合当前数据契约；doctor输出OK，只能说明内置示例和渲染依赖可用；只有在新的 Codex 任务中看到技能被读取、已有地图被检查，并最终得到项目自己的架构产物，才能认为真实触发链路已经走通。

图 2：从技能安装到首次生成架构图的完整链路。

二、环境准备

Birdview 本身要求 Node.js 18 或更高版本。需要注意，第三方安装器或 Agent 宿主可能有更高的 Node.js 版本要求，因此最终应同时满足 Birdview 和宿主两边的要求。

在 PowerShell 中先检查本机环境：

node--version npm--version git--version

如果node --version低于 18，应先升级 Node.js。本文还会使用npx调用第三方skillsCLI，并从 GitHub 获取项目，因此需要能够访问 npm registry 与 GitHub。

Birdview 当前的package.json标记为private。这意味着下面这条命令不是项目支持的安装方式：

# 错误示例：Birdview 当前不是公开 npm 包npm install-g birdview

正确方式是通过第三方 skills CLI、GitHub 源码包或 Git 仓库安装完整技能目录。

三、方式一：使用 skills CLI 安装

项目文档推荐使用第三方 skills CLI 选择目标 Agent 和安装范围。最简命令如下：

npx skills add Qiuner/birdview--skill birdview

这条命令会进入交互式选择。若希望明确安装到 Codex 的全局技能目录，并减少交互，可以使用：

npx skills add Qiuner/birdview `--skill birdview `--agent codex `--global `--copy`--yes

PowerShell 使用反引号进行续行。如果准备复制到其他终端，建议先改成单行命令，避免不同 Shell 的续行语法互相混用。

参数的含义如下：

省略--global时，安装器会进行项目级安装。用户级安装适合在多个项目里按需调用；项目级安装适合希望把技能与某个仓库一起管理的情况。

安装器负责把文件放到合适位置，但不会替你安装 Birdview 的开发依赖，也不会自动修改所有项目的模式。因此还要进入安装器输出的技能目录执行：

npm ci node scripts/birdview.mjs doctor

也可以不切换目录，使用npm --prefix。假设安装目录是$HOME/.agents/skills/birdview：

$birdviewRoot=Join-Path$HOME'.agents/skills/birdview'npm--prefix$birdviewRootci node(Join-Path$birdviewRoot'scripts/birdview.mjs')doctor

成功时，doctor会报告内置示例校验、渲染依赖和模板资源正常。它不会写入项目，也不会验证 Codex 是否已经发现技能。

四、方式二：手动安装到 Codex

如果不希望依赖第三方安装器，可以从 Birdview 的 GitHub Releases 下载指定版本源码并解压，然后将完整目录放到：

~/.agents/skills/birdview

在 Windows PowerShell 中，~和$HOME都指向当前用户主目录。安装后的关键结构应类似下面这样：

birdview/ ├─ SKILL.md ├─ package.json ├─ scripts/ ├─ schemas/ ├─ assets/ ├─ references/ ├─ examples/ └─ docs/

SKILL.md必须直接位于birdview目录下，不能因为解压源码包而多嵌套一层，例如birdview/birdview-0.3.0/SKILL.md。只复制SKILL.md也不够，因为渲染器还需要脚本、Schema、模板、浏览器资源和依赖清单。

完成复制后安装依赖并验证示例：

$birdviewRoot=Join-Path$HOME'.agents/skills/birdview'# 安装锁文件中记录的完整依赖npm--prefix$birdviewRootci# 验证技能自带的架构示例node(Join-Path$birdviewRoot'scripts/validate.mjs')`(Join-Path$birdviewRoot'examples/architecture.json')

校验器应输出包含以下字段的结果：

{"ok":true,"errors":[]}

实际结果还会包含模块数、关系数和事件数。这里不应把示例中的模块理解为当前项目的架构，因为它明确是一套虚构的契约示例。

五、按需模式、自动模式和关闭模式

安装完成后，Birdview 默认按需调用。也就是说，普通修复和功能开发不会自动生成地图，只有用户显式选择技能、点名 Birdview，或者明确要求架构图、约束图、变更图时才进入完整流程。

如果希望给某个项目安装持续生效的基础规则，可以运行：

$birdviewRoot=Join-Path$HOME'.agents/skills/birdview'$projectRoot='D:\Code\your-project'node(Join-Path$birdviewRoot'scripts/birdview.mjs')` setup--project$projectRoot

对新项目而言，setup默认选择on-demand，并在项目的AGENTS.md中写入一段由标记包围的管理规则。它会保留该文件中原有的其他内容。基础规则会指导 Agent 聚焦源码、依据证据和适度验证，但按需模式下不会要求每次任务都加载完整技能或生成地图。

三种模式的差异如下：

可以通过以下命令查询或切换：

$cli=Join-Path$birdviewRoot'scripts/birdview.mjs'node$climode--project$projectRootnode$climode auto--project$projectRootnode$climode on-demand--project$projectRootnode$climode off--project$projectRoot

这些设置本质上是写入项目指令文件的 Agent 规则，不是文件系统拦截器。已有会话可能仍保留旧上下文，所以切换模式后最好新建任务进行验证。

六、生成第一张项目架构图

为了把安装验证和真实项目隔离开，我建议先选一个无敏感数据、规模适中的测试仓库。不要一开始就在重要生产项目中使用自动模式。

在目标项目中新建 Codex 任务，通过/skills选择 Birdview，或直接输入：

$birdview 展示这个项目的架构和约束，不修改代码。

“不修改代码”非常重要。这个请求只授权调查、建图、校验和渲染，不授权实现业务改动。正常情况下，Agent 会先报告它在什么位置检查了已有地图，以及为什么复用、更新或新建；随后读取项目入口、构建清单、相关源码与项目规则，建立模块和关系。

图 3：首次建图完成后应看到的完整架构视图。截图取自本地仓库的.birdview静态产物，内容由 Agent 声明并经渲染，不是对生产系统或全部编辑操作的实时监控。

图 4：仅建图任务中，Birdview 对已有地图的复用、更新与交付流程。

默认产物通常位于目标项目的.birdview/：

.birdview/ ├─ architecture.json ├─ architecture.html ├─ constraints.catalog.json ├─ constraints.selection.json ├─ constraints.reviewed.json └─ architecture.sources.html

具体约束文件取决于项目规则发现和审查是否完成。没有已审查规则时，Agent 应说明已检查路径、剩余缺口和无法生成完整规则图的原因，而不是用演示规则填充。

七、如何判断第一张图是否合格

看到 HTML 文件并不代表任务已经完成。至少需要检查以下内容：

1. 项目名称和地图范围是否对应当前仓库，而不是技能自带示例。

2. 每个本地模块是否拥有文件或目录归属，并附带源码证据。

3. 模块是否按职责划分，而不是把每个文件都画成一个节点。

4. 不确定结论是否明确标记，并列出具体待确认问题。

5. 关系方向、标签和证据是否与调用链一致。

6. 页面中是否可以切换架构、约束或来源视图。

7. 节点、连线、箭头和文字在实际浏览器视口中是否可读。

还应检查 JSON 是否通过新地图的严格作者校验。以下命令中的路径需要替换为实际技能目录和项目目录：

node"$birdviewRoot/scripts/validate.mjs"`"$projectRoot/.birdview/architecture.json"`--authoring `--bilingual

--authoring要求新地图显式分类模块角色，并解释为什么某个模块只能使用通用分类；--bilingual要求中英文交付的文本覆盖完整。Schema 和语义校验通过仍然不能证明架构判断真实，因此还要抽查证据路径与符号。

八、从架构图进入真实编码任务

当用户提出具体编码需求时，Birdview 会在同一张地图上增加活动记录，展示完整范围、当前目标、文件和验证计划。按照当前技能规则，Agent 必须先展示可审阅的修改计划，再等待用户明确确认。

这个确认不是重复询问“是否允许写文件”，而是让用户确认已经看见的具体方案：

• 涉及哪些模块和文件；

• 预期改变什么可观察行为；

• 哪些项目约束适用；

• 准备运行哪些验证；

• 还存在哪些不确定项。

确认后，Agent 才进入editing阶段。如果实现中发现必须新增模块、行为或适用约束，就要更新计划并再次确认实质变化。范围内的普通编辑不需要每一行都重复确认。

图 5：活动详情把完整范围、当前目标、声明文件和验证状态放在同一面板中，便于用户在实施前后核对 Agent 的任务声明。

活动页可以手动生成：

node"$birdviewRoot/scripts/render.mjs"`"$projectRoot/.birdview/architecture.json"`"$projectRoot/.birdview/activity.html"`"$projectRoot/.birdview/activity.jsonl"

更新活动后需要重新生成 HTML 并刷新页面。Birdview 当前没有实时传输、自动刷新或对编辑动作的强制拦截。

九、Claude Code 与 DeepSeek Harness 的差异

Birdview 的核心目录和数据契约不因宿主而改变，区别主要在技能发现位置、调用入口和项目指令文件。

使用 Claude Code 配置项目模式时，需要添加：

node$clisetup--project$projectRoot--agent claude-code

DeepSeek Harness 使用：

node$clisetup--project$projectRoot--agent deepseek

同一个项目如果同时由多个宿主使用，不要假设AGENTS.md与CLAUDE.md会自动同步。查询和写入时应始终使用与目标宿主一致的--agent参数。

十、常见问题排查

1. Codex 中看不到 Birdview

先确认SKILL.md是否直接位于~/.agents/skills/birdview/，目录有没有多嵌套一层，并检查是否存在多个同名旧副本。Codex 官方技能文档说明用户级技能目录为~/.agents/skills，仓库级目录为.agents/skills。如果目录刚刚变化但技能仍未出现，可以重启宿主后再检查。

2.doctor通过，但任务没有自动建图

这是正常现象。Birdview 默认是on-demand，普通编码请求不会自动触发。应在当前任务中通过技能选择器或$birdview显式调用，或者为特定项目主动配置auto。

3. 页面生成了，但打开后不是当前项目

检查 Agent 是否错误使用了examples/下的虚构地图。真实项目产物通常位于目标项目的.birdview/，project.name、模块归属和证据路径都应对应当前仓库。

4. 校验通过，架构却看起来不对

校验器只能检查结构和已定义的一致性规则，不能证明源码证据支持结论。应点击模块检查证据，回到源码核对职责和调用方向，并把缺乏证据的判断改成uncertain。

5. 切换模式后当前任务没有变化

模式依赖 Agent 加载项目指令文件，已有任务可能继续使用旧上下文。新建任务后重新查询模式和验证触发，不要把 CLI 写入成功直接当作当前会话已经刷新。

总结

我认为 Birdview 最合理的上手方式不是安装后立刻给所有仓库开启自动模式，而是先把“文件安装”“工具自检”和“宿主触发”三个层次逐一验证。先通过 skills CLI 或手动方式保留完整技能目录，再执行npm ci和只读doctor，确认数据契约、渲染依赖与模板资源正常；随后选择无敏感数据的测试仓库，新建 Codex 任务并明确要求 Birdview 只展示架构和约束。拿到第一张图后，我会检查模块职责、文件归属、源码证据、不确定项和关系方向，而不会因为页面能打开就默认架构正确。确认链路可靠后，再为常用项目执行setup并保留按需模式；只有团队愿意为每次修改承担建图和方案确认成本时，才适合切换到auto。进入编码任务后，Birdview 仍需要和 Git diff、测试、代码审查配合：它负责提前暴露 Agent 对系统边界和修改范围的理解，其他工具负责核对真实改动与行为结果。只要保持这条边界，Birdview 就不是给 AI Coding 增加形式负担，而是在复杂任务开始前增加一个具体检查点：先确认我们和 Agent 看到的是不是同一张系统地图，再决定是否让修改继续发生。若第一次页面缺少约束，我会检查指令来源和审查覆盖，而不会直接补上想象中的规则；若模块关系含糊，我会回到对应源码抽查。只有这些基础检查能稳定完成，我才会考虑把它纳入更关键的仓库，并让团队共同约定何时需要方案确认。安装教程的终点不是命令返回成功，而是用户确实能理解和审查当前项目的地图。

系列延伸阅读

• Codex Skill 与 Claude Code Skill 的 Birdview 接入差异

• AGENTS.md 和 CLAUDE.md 的约束可视化

参考资料

1. Birdview GitHub 仓库

2. Birdview 中文安装指南

3. Birdview 项目模式说明

4. Birdview 建立项目地图流程

5. Codex Skills 官方文档

6. skills CLI GitHub 仓库