摘要我第一次接触 Birdview 时真正想验证的不是它能不能画出漂亮的架构图而是这套流程能否自然进入日常 AI Coding安装是否复杂Agent 能否在正确时机发现技能生成的图是否来自项目证据。实际梳理后我发现Birdview 的上手过程可以分成三个独立环节先把完整技能安装到宿主能够发现的位置再用只读自检确认 Node.js 依赖、数据校验器和 HTML 渲染器正常最后在新的 Agent 任务中明确调用 Birdview让它检查已有地图、分析项目源码并生成.birdview/architecture.json与独立 HTML。这里最容易混淆的是“安装成功”“自检通过”和“真实触发成功”并不是同一件事doctor能证明内置示例可以校验和渲染却不能证明宿主已经加载技能项目模式命令能写入 Agent 规则却不是文件拦截器。本文以 Windows PowerShell 和 Codex 为主线讲清安装、模式配置、首次建图、产物检查和常见问题帮助你生成第一张架构图也避免把成功打开的页面误解成对 Agent 行为的自动审计。我还会说明为什么要在新任务里验证宿主发现、为什么不能只复制一个说明文件、为什么默认按需模式更适合初次试用。即使从未配置过编码代理技能也可以沿着这些检查点逐步定位失败发生在文件安装、依赖、自检还是调用阶段。每一步都有不同的成功信号不能用其中一项替代整条链路。图 1Birdview 独立 HTML 查看器。截图使用项目内置的虚构演示数据不代表生产环境中的真实 Agent 活动。一、开始前先理解三个层次Birdview 不是一个需要常驻后端的 SaaS也不是安装后自动接管所有编辑动作的 IDE 插件。它由技能说明、数据契约、Node.js 校验与渲染脚本、浏览器查看器等部分组成。Agent 读取技能工作流分析目标项目然后把结果写成结构化数据和独立 HTML。上手时需要依次确认三个层次层次要确认的问题推荐验证方式技能文件Birdview 是否完整安装到宿主可发现的位置检查目录结构与SKILL.md工具链依赖、校验器和渲染器是否正常npm ci与birdview.mjs doctor宿主触发Codex 是否真的读取技能并执行工作流新建任务显式调用 Birdview这三个层次不能互相替代。比如校验器输出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--yesPowerShell 使用反引号进行续行。如果准备复制到其他终端建议先改成单行命令避免不同 Shell 的续行语法互相混用。参数的含义如下参数含义--skill birdview只选择仓库中的 Birdview 技能--agent codex选择 Codex 对应的安装位置--global安装到用户级目录而不是当前项目--copy复制技能内容而不是创建其他形式的引用--yes对安装器支持的确认项使用默认答案省略--global时安装器会进行项目级安装。用户级安装适合在多个项目里按需调用项目级安装适合希望把技能与某个仓库一起管理的情况。安装器负责把文件放到合适位置但不会替你安装 Birdview 的开发依赖也不会自动修改所有项目的模式。因此还要进入安装器输出的技能目录执行npm ci node scripts/birdview.mjs doctor也可以不切换目录使用npm --prefix。假设安装目录是$HOME/.agents/skills/birdview$birdviewRootJoin-Path$HOME.agents/skills/birdviewnpm--prefix$birdviewRootci node(Join-Path$birdviewRootscripts/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、模板、浏览器资源和依赖清单。完成复制后安装依赖并验证示例$birdviewRootJoin-Path$HOME.agents/skills/birdview# 安装锁文件中记录的完整依赖npm--prefix$birdviewRootci# 验证技能自带的架构示例node(Join-Path$birdviewRootscripts/validate.mjs)(Join-Path$birdviewRootexamples/architecture.json)校验器应输出包含以下字段的结果{ok:true,errors:[]}实际结果还会包含模块数、关系数和事件数。这里不应把示例中的模块理解为当前项目的架构因为它明确是一套虚构的契约示例。五、按需模式、自动模式和关闭模式安装完成后Birdview 默认按需调用。也就是说普通修复和功能开发不会自动生成地图只有用户显式选择技能、点名 Birdview或者明确要求架构图、约束图、变更图时才进入完整流程。如果希望给某个项目安装持续生效的基础规则可以运行$birdviewRootJoin-Path$HOME.agents/skills/birdview$projectRootD:\Code\your-projectnode(Join-Path$birdviewRootscripts/birdview.mjs) setup--project$projectRoot对新项目而言setup默认选择on-demand并在项目的AGENTS.md中写入一段由标记包围的管理规则。它会保留该文件中原有的其他内容。基础规则会指导 Agent 聚焦源码、依据证据和适度验证但按需模式下不会要求每次任务都加载完整技能或生成地图。三种模式的差异如下模式普通代码修改显式调用 Birdview项目基础规则on-demand不自动建图运行完整流程开启auto每次代码修改前介入运行完整流程开启off不介入当前任务明确调用时仍可运行关闭可以通过以下命令查询或切换$cliJoin-Path$birdviewRootscripts/birdview.mjsnode$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 文件并不代表任务已经完成。至少需要检查以下内容项目名称和地图范围是否对应当前仓库而不是技能自带示例。每个本地模块是否拥有文件或目录归属并附带源码证据。模块是否按职责划分而不是把每个文件都画成一个节点。不确定结论是否明确标记并列出具体待确认问题。关系方向、标签和证据是否与调用链一致。页面中是否可以切换架构、约束或来源视图。节点、连线、箭头和文字在实际浏览器视口中是否可读。还应检查 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 的核心目录和数据契约不因宿主而改变区别主要在技能发现位置、调用入口和项目指令文件。宿主常见调用方式模式管理目标Codex/skills或$birdviewAGENTS.mdClaude Code/birdviewCLAUDE.mdDeepSeek Harness宿主技能选择器或明确请求AGENTS.md使用 Claude Code 配置项目模式时需要添加node$clisetup--project$projectRoot--agent claude-codeDeepSeek 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 的约束可视化参考资料Birdview GitHub 仓库Birdview 中文安装指南Birdview 项目模式说明Birdview 建立项目地图流程Codex Skills 官方文档skills CLI GitHub 仓库