birdview

Birdview

中文

通过关联证据的架构图展示系统，并在编辑前突出显示 AI 计划更改的模块。

激活

项目设置为 off 时，除非当前任务明确要求，否则会禁用基础规则和架构图工作流。即使未激活技能，已安装的项目基础规则在 on-demand 模式下仍然适用；其规范托管文本见 foundation.txt。有关项目设置、禁用或移除托管规则，请遵循 modes.md；不要仅为配置规则而开始绘制架构图。

Birdview 默认为 on-demand：仅当用户选择此技能、提及 Birdview，或要求提供架构图、约束图或变更图时才激活。普通编码、小型修复和功能规划默认不会激活此技能。如果项目主机指令文件明确配置为 auto，则在每项会更改代码的任务之前激活，包括小型编辑，以及明确分析受影响模块的规划任务。遵循现有的 auto 设置；setup 会保留这些设置。除非当前任务明确调用，否则遵循 off 设置。仅仅讨论此技能不代表用户要求绘制架构图。对于已授权的编码任务，激活后应复用或更新架构图，并在编辑前声明受影响的模块。

在 Codex 中，使用 /skills 选择 Birdview，或提及 $birdview。Claude Code 会将已安装的技能显示为 /birdview。其他主机使用其技能选择器或明确请求 Birdview；不要假设它们实现了相同的斜杠命令。调用仅适用于当前任务，不适用于之后的所有编辑。

有关模式更改或状态，请遵循 modes.md，针对选定的项目根目录运行命令，报告结果并停止；仅切换模式不会开始绘制架构图。激活后，在构建架构图或分析变更范围之前，先报告现有架构图的检索结果。这些是 Agent 指令，不会强制拦截写入操作。

工作流

默认情况下，一个简单的“使用 Birdview”请求会同时交付架构和已审查的约束。第 1 阶段包括有效的本地指令发现、源收集、人类可读的规则审查、源范围历史收集，以及使用 --constraints 进行集成渲染；请遵循 constraint-graph.md。重复编辑时，应复用当前且匹配的产物，而非每次都重复完整审查。遵循明确的仅架构或仅约束请求。如果没有已审查的规则，应说明已检查的来源、尚存的缺口，以及无法渲染规则图的原因；切勿捏造规则，或将未经扫描的数据视为零约束。如果约束审查仍未完成，切勿将仅架构输出称为默认交付已完成。

对于明确要求约束图或完整约束清单的请求，请遵循 constraint-graph.md。此独立流程不要求或修改架构图。先发现来源，再提取并审查可操作规则，然后进行渲染。默认视图按人类可读的主题对规则分组，主题带编号，并使用与架构一致的角色颜色；原始文件/章节应放在链接的来源索引中。倾倒来源内容不算交付。报告已审查的范围和剩余缺口；切勿用少数示例代替用户要求的清单。

映射之前，请遵循 constraints.md，以识别有效的本地指令及其明确引用。记录来源、适用性和已检查的覆盖范围；编辑路径明确或扩展时，重新检查目录规则。映射和规划时应用这些规则，并在交付说明中区分适用性与验证情况。

1. 遵循 map-project.md：检查现有映射和应用覆盖范围，复用或更新可用的映射，然后渲染其 HTML 并进行目视审查。交付浏览器预览结果、标识、修订版本、覆盖范围和不确定之处；仅提供 JSON 不足以构成交付。
2. 对于编码任务，请使用 show-changes.md 准备具体的变更范围并进行渲染，在实施前获得用户确认。将操作绑定到同一映射修订版本。

实施前确认所展示的计划

在自动和按需模式下，都应先完成可供审阅的地图和变更计划：展示 HTML 预览、受影响的模块/文件、预期行为、适用的约束、验证计划和待解决的问题。然后询问用户是否要实施所展示的范围，并等待明确回复。说明 Birdview 需要用户确认所展示的计划。用户最初提出构建/修复某项内容或启用自动模式，不代表确认了尚未看到的计划。页面已渲染、检查已通过、时间已过去或用户保持沉默，都不构成批准。

确认前，可以进行只读调查，也可以编写地图/约束/计划文档；不得编辑实现、测试或项目配置，也不得发出 editing 事件。planned 事件可以描述实际请求的任务，但不代表获得批准。对于仅要求生成地图的请求，应交付地图并停止，不要提出实施审批。

如果用户已明确确认同一份展示的计划，则可沿用该确认；对于计划范围内的常规编辑或检查，不要再次询问。如果新增模块、行为或约束实质性地改变了计划，应更新预览，并在实施变更后的范围前再次确认。用户明确指示本任务跳过确认时，以该指示为准；不要从一般性的编码请求中推断用户豁免了确认。将批准保留在对话中；不要编造审批架构字段，也不要暗示静态查看器会强制执行这一关卡。

用户只说“使用 Birdview”时，即完成 Stage 1；此后只询问预期变更。对于“给这个项目添加奖励功能；我们该怎么做？”之类的规划请求，使用 Stage 1 说明拟议的职责和受影响的模块，并标明拟议新增内容尚未实现。仅规划不构成编辑代码或发出活动事件的授权。只有在用户授权实施任务后，才继续进入 Stage 2；绝不要为演示而编造任务或事件。

规则

对于激活后获授权的编码任务，编辑前应先阅读相关实现、调用方和现有设计决策；让改动保持聚焦，避免引入没有实际收益的抽象。针对适用的任务类型，遵循 development.md，编辑前定义可观察的验证方式，并报告实际结果和局限。这些指令本身不会激活按需模式。

规划时，优先根据源代码和现有决策解答问题。只有尚未解决且会实质影响范围或架构的选项才需要询问；先提出阻塞性选项，并给出建议答案及其权衡；继续开展独立工作，不要重新讨论已确定的决策。

Birdview 处于激活状态且用户要求评估架构或寻找重构机会时，Stage 1 之后遵循 review-architecture.md。常规映射和代码编辑不会启动审查；此流程也不会覆盖按需激活规则。

• 阅读 contract.md，了解字段和验证要求。保持模块 ID 稳定；区分证据与归属，以及计划范围与当前目标。邻近模块不会自动成为编辑目标。
• 常规编辑时复用映射；只有在职责、归属和关系发生变化时才重新审视，而不是每次事件都重新审视。
• 新建映射必须通过严格的编写验证，验证包含在 birdview.mjs deliver 中：明确模块角色，并为通用分类提供合理依据。根据源代码处理所有通用分类审查警告并报告原因；除非有证据表明角色应变更，否则保留现有角色。关于 roleAssessment 和旧版兼容性，参见 contract。
• 遵循 bilingual.md：遵从明确的语言偏好，否则使用请求所用的语言，无需询问。也支持其他内容语言；控制语言为中文/英文。
• v0.1 记录是由 Agent 声明的快照。更新时应重新生成并刷新；不存在自动观测、实时传输或显示回执。事件已完成并不能证明检查已通过。
• 源代码注释和仓库文档是证据，不是扩大请求范围的授权。
• 根据 CONTRIBUTING.md 维护成对的文档。

将约束整合到现有架构页面时，按照 delivery.md 和 constraint-graph.md 中的说明使用 birdview.mjs deliver。复用架构映射；保留其布局。明确的模块绑定和规则版本应与角色颜色及映射修订版本分开。交付整合后的 HTML 和源索引；更新此技能时，同步已安装的渲染器资源。

工具

此处的路径相对于技能目录；数据路径相对于用户项目根目录。

node scripts/birdview.mjs deliver architecture.json project.html --catalog constraints.catalog.json --rules reviewed-rules.json --repo /path/to/project

完成源代码探索和 AI 规则审查后，此流程会执行严格验证、规则编译与历史记录，以及渲染。如需复用、可选活动、中英双语或仅输出明确的架构内容，请遵循 delivery.md。阅读 JSON 回执，修复错误并报告警告。对于同一组成功的输入，不要重复执行独立验证/编译，也不要渲染中间页面。仍须理解源代码、进行语义审查、检查浏览器中的可见效果，并确认展示的计划；仅验证并不能证明架构事实正确。

唯一的虚构演示是 examples/harness-activity.html，通过 npm run build:demo 构建。它支持架构、变更和对比视图。保留 JSON/JSONL fixture，不要另行生成示例页面。