Repository navigation
中文
架构评审现在开篇就给出明确结论:健康、需要改进或有风险,随后是一句话结论和一至三条理由。理由可跳转到支撑它的建议,「建议先做」也放在同一张总评卡片中。
评审改进
- 源码依据默认折叠为文件、行号和批注,展开后查看原文。代码续行悬挂在缩进之下,悬停时高亮整行源码。
- 桌面端滚动时建议稿保持可见。论证区先突出方案,再展示收益、迁移代价、边界和删除测试;与已有决策冲突时高亮提示。
- 红笔批注避让节点、连线、连线标签和其他批注。缺接缝虚线和重复项括号使用外侧路径,减少遮挡。
不兼容变更:评审 schema 版本 3
不再接受版本 "2" 的评审 JSON。迁移已有报告时:
- 重新评估已检查的范围,添加
verdict: { grade, headline, reasons }。等级为healthy、needs-work或at-risk;一句话结论不超过 40 字符;提供一至三条理由,每条不超过 120 字符,可附candidatesID。 - 将
schemaVersion设为"3"。存在带 observed 批注的 strong 候选时不能判为healthy;at-risk至少需要一条理由引用候选。 - 运行
node scripts/render-review.mjs review.json review.html --repo <repository-root>渲染并校验。
不要只修改版本号,也不要为通过校验编造总评。参见评审契约和更新后的示例。此前生成的独立 HTML 仍是原有快照,需重新生成才能使用新版布局。
约束改进
discover-constraints.mjs 支持重复传入 --entry,收集常规 AGENTS/CLAUDE 入口之外的 Markdown 规则文件,例如 CONTEXT.md。缺失或非 Markdown 的入口记录在 coverage.unresolved 中。
规则视图的生成文字跟随架构语言,并在查看器切换语言时更新。中文地图使用中文,其他语言使用英文;未提供语言时,旧入口仍默认中文。来源正文不会被翻译。参见约束图参考。
安装与更新
使用 v0.5.0 源码归档固定到本版,或按安装指南更新完整技能包并保留本地定制。npx skills add Qiuner/birdview --skill birdview 安装仓库当前版本。如使用独立入口,保留与主技能包相邻的 birdview-review 和 birdview-compatibility。
在技能目录运行 npm ci 和 node scripts/birdview.mjs doctor。对已配置项目重新运行 setup --project <project-root>,然后新建 Agent 任务。需要 Node.js 18 或更高版本。分发包含生成后的 JavaScript;通过 GitHub 发布,npm 包仍为私有。
验证与限制
发布检查为 npm run check:pr(类型、生成产物、单元与浏览器测试、示例重新生成、示例校验和双语文档),以及对已提交候选运行的 npm run check:install。参见发布检查清单。
总评是 AI 对声明范围及依据的判断,不是独立认证。Birdview 展示快照和 Agent 声明的活动,不会独立观测所有编辑,也不强制执行修改前流程。图中布局采用启发式算法。约束发现不会解释规则含义,语言切换只翻译界面文字。
English
Architecture reviews now open with a direct conclusion: Healthy, Needs work or At risk, followed by a one-sentence headline and one to three reasons. Reasons can link to the supporting proposals, and the recommended first step appears in the same card.
Review improvements
- Source evidence starts folded into a file, line range and note; expand it to read the quotation. Wrapped code hangs under its indentation, and hovering highlights the whole source line.
- Proposed drawings stay visible while scrolling on desktop. The argument leads with the solution, followed by benefits, migration costs, boundaries and the deletion test; conflicts with existing decisions are highlighted.
- Red-pencil notes avoid nodes, connectors, edge labels and other notes. Missing-seam lines and duplicate brackets use outside routes to reduce overlap.
Breaking change: review schema version 3
Version "2" review JSON is no longer accepted. To migrate an existing report:
- Reassess the inspected scope and add
verdict: { grade, headline, reasons }. The grade ishealthy,needs-workorat-risk; the headline is at most 40 characters; provide one to three reasons, each at most 120 characters, with optionalcandidatesIDs. - Set
schemaVersionto"3". A strong candidate with an observed finding rules outhealthy;at-riskrequires at least one reason that cites a candidate. - Render and validate with
node scripts/render-review.mjs review.json review.html --repo <repository-root>.
Do not change only the version number or invent a verdict to pass validation. See the review contract and updated example. Previously generated standalone HTML remains a snapshot; regenerate it to get the new layout.
Constraint improvements
discover-constraints.mjs accepts repeatable --entry options for Markdown rule files outside the usual AGENTS/CLAUDE entries, such as CONTEXT.md. Missing or non-Markdown entries are recorded in coverage.unresolved.
Generated rule-view text follows the architecture language and updates when the viewer language changes. Chinese maps use Chinese; other languages use English. The legacy default without a language remains Chinese. Source content is not translated. See the constraint graph reference.
Install and update
Use the v0.5.0 source archive for this fixed version, or follow the installation guide to update the complete bundle while preserving local customizations. npx skills add Qiuner/birdview --skill birdview installs the current repository version. Keep the dedicated birdview-review and birdview-compatibility entries alongside the main bundle if you use them.
Run npm ci and node scripts/birdview.mjs doctor in the skill directory. Rerun setup --project <project-root> for configured projects, then start a fresh agent task. Node.js 18 or newer is required. Generated JavaScript is included; distribution is through GitHub and the npm package remains private.
Verification and limitations
Release checks are npm run check:pr (types, generated artifacts, unit and browser tests, demo regeneration, examples and bilingual documentation) and, against the committed candidate, npm run check:install. See the release checklist.
The verdict is an AI assessment of the declared scope and evidence, not an independent certification. Birdview displays snapshots and agent-declared activity; it does not independently observe every edit or enforce the pre-edit workflow. Diagram placement is heuristic. Constraint discovery does not interpret rule semantics, and language switching translates interface text only.