Birdview v0.4.0 — 架构评审、技能兼容性体检与更改路径

中文

这个版本让你更容易回答三个问题：架构该怎么改？多个技能会不会同时误触发？一次改动还会影响谁？ 在原有架构与约束视图之上，Birdview 新增架构评审、技能触发兼容性体检，并改进更改视图。

架构评审：先看懂建议，再决定怎么改

评审先读取源码，再把现状、问题与建议画出来：

• 现状图与红笔批注：展示已有模块、调用关系和具体问题，附源码原文。
• 建议稿：展示调整后的边界、调用方职责变化、收益、迁移成本和验证步骤。
• 可核对的依据：使用 --repo 渲染时，引用会与指定提交或工作区源码逐行核对；未提供仓库时标记为未核对。引用匹配不等于建议正确。
• 先审后改：展示页面后等待你确认具体方案，再实施已授权的范围。

安装独立入口后，在 Codex 中使用：

$birdview-review 评审这个项目的架构，画出现状、问题和优化建议，先不修改代码。

Claude Code 使用 /birdview-review。也可以明确要求 Birdview“优化架构”或“评审模块边界”；自然语言触发取决于宿主发现并选择技能，不是固定关键词拦截器。查看评审示例和评审流程。示例基于标注的源码版本，不代表对当前版本的最新评审。

技能兼容性体检：检查哪些请求会让技能撞车

体检先收集安装信息，再由 AI 阅读技能正文，比较触发范围、调用模式、写入权限和确认要求。结论围绕具体场景说明：可以一起用、需要先后顺序、可能冲突、仍无法判断，并附双方证据与建议。

$birdview-compatibility 检查本地技能的触发是否冲突，用中文说明冲突场景、依据和建议。

Claude Code 使用 /birdview-compatibility。结果是便于阅读的文字／Markdown 报告，同时保留 JSON；报告语言跟随对话，CLI 调用须显式传入 --language zh 或 en。单纯扫描到重复名称或宽泛描述不等于确认冲突，安装清单也不是最终结论。体检不会自动禁用、重排或改写其他技能。

更改视图：看清本次路径与范围外影响

• 在同一张架构图上查看 Agent 声明的改动模块、文件和执行步骤。
• 打开「范围外影响」，查看与计划直接相连、但未列入改动范围的模块，帮助发现需要进一步核对的边界。
• 改进连线路由、短折线和屏幕适配，在桌面与窄屏下更容易追踪路径。

这层影响来自图中已声明的直接关系，不表示这些模块必须修改，也不证明传递影响已被完整分析。查看架构与更改示例，其中活动为模拟数据。

其他改进与升级提醒

• birdview deliver 串联输入校验、按需约束编译与历史收集、页面渲染和交付回执，减少手工执行这些步骤；它不会替 AI 判断规则含义，也不代表视觉验收通过。
• 约束来源在约束页的「按目录」中阅读。独立 .sources.html 导出、--sources 参数和 sourceHref 接口已移除；依赖旧入口的脚本或链接需要更新。
• 旧的并排对照入口由更改路径与「范围外影响」取代。架构、约束和评审导航按实际渲染的数据提供。
• 默认仍为按需触发，自动模式可选。绘图后确认方案的流程继续保留。

安装与更新

按安装指南更新完整 birdview 技能包，保留本地定制。固定到本版时使用 v0.4.0 发布后的源码归档；npx skills add Qiuner/birdview --skill birdview 安装的是仓库当前版本。

独立命令需要对应入口：将包内 review-skill/ 安装为同一技能目录中的 birdview-review/，将 compatibility-audit/ 安装为 birdview-compatibility/，并保留完整的相邻 birdview/ 包。只安装主技能不会自动安装这两个入口。

在主技能目录运行 npm ci 和 node scripts/birdview.mjs doctor，对已配置项目重新运行 setup --project <project-root>，刷新基础规则并保留已有模式。新建 Agent 任务验证技能发现和触发。需要 Node.js 18 或更高版本；分发含生成后的 JavaScript，无需自行编译 TypeScript。通过 GitHub 分发，npm 包仍为私有。

验证与边界

发布候选需要通过 npm run check:pr：类型、生成产物、单元测试、浏览器交互、示例重新生成、输入校验和双语文档检查。提交后、打标签前，还需运行 npm run check:install 验证源码归档安装；具体发布状态以发布检查清单和候选提交的检查结果为准。

Birdview 展示 AI 整理的快照、证据和声明，不独立监控所有编辑，也不提供文件系统写入锁。技能兼容性结论需要结合宿主规则和实际任务，不是安全认证。约束页需要已审查的约束数据，仓库暂未提供可直接打开的约束示例。

English

This release helps answer three questions: How should the architecture change? Can installed skills trigger together unintentionally? What else could a change affect? Birdview adds architecture review and skill trigger compatibility audits, and improves the changes view alongside the existing architecture and constraints views.

Architecture review: understand the proposal before implementing

The review reads source first, then draws the current structure, problems and proposal:

• Current drawing and red-pencil notes show existing modules, calling relationships and specific problems, with quoted source.
• Proposed redraw shows revised boundaries, changes to caller responsibilities, benefits, migration costs and verification steps.
• Checkable evidence: rendering with --repo checks quotations line by line against the specified commit or working tree. Without a repository, quotations are marked unchecked. A matching quotation does not prove the proposal is correct.
• Review before implementation: the agent shows the page and waits for confirmation of a concrete proposal before implementing the authorized scope.

After installing the dedicated entry, use this in Codex:

$birdview-review Review this project's architecture. Draw the current structure, problems and proposals; do not edit code yet.

Use /birdview-review in Claude Code. You can also explicitly ask Birdview to optimize architecture or review module boundaries. Natural-language activation depends on the host discovering and selecting the skill; it is not a fixed keyword interceptor. See the review example and review workflow. The example reviews its recorded source revision, not necessarily the current version.

Skill compatibility: identify requests that activate competing skills

The audit inventories installations, then has the AI read skill bodies and compare trigger scope, invocation modes, write permissions and confirmation requirements. For concrete scenarios, it explains whether skills are compatible, need ordering, may conflict or remain unresolved, with evidence from both skills and recommendations.

$birdview-compatibility Check local skills for overlapping triggers. Explain scenarios, evidence and recommendations in English.

Use /birdview-compatibility in Claude Code. Results are readable text/Markdown with accompanying JSON. The report follows the conversation language; CLI calls must explicitly pass --language zh or en. Duplicate names or broad descriptions alone do not confirm a conflict, and an inventory is not the final assessment. The audit does not automatically disable, reorder or rewrite other skills.

Changes view: trace the plan and its outside-scope impact

• Inspect the modules, files and execution steps declared by the agent on the same architecture map.
• Enable Outside-scope impact to see modules directly connected to the plan but not declared as change targets, revealing boundaries worth checking.
• Improved routing, short bends and screen adaptation make paths easier to follow on desktop and narrow screens.

This impact layer uses declared direct relationships. It does not mean those modules must change or prove that all transitive effects have been analyzed. See the architecture and changes example, which uses simulated activity.

Other improvements and upgrade notes

• birdview deliver combines input validation, optional constraint compilation and history collection, page rendering and a delivery receipt, reducing manual execution of these steps. It does not interpret rule semantics for the AI or certify visual acceptance.
• Read constraint sources in By directory within the constraints page. Standalone .sources.html export, the --sources argument and the sourceHref interface have been removed; update scripts and links that depended on them.
• Change paths and Outside-scope impact replace the old side-by-side comparison entry. Architecture, Constraints and Review navigation appears according to the data rendered.
• On-demand remains the default, with optional auto mode. Confirmation of the displayed plan remains part of the workflow.

Install and update

Follow the installation guide to update the complete birdview bundle and preserve local customizations. For a fixed version, use the source archive after v0.4.0 is published; npx skills add Qiuner/birdview --skill birdview installs the current repository version.

Dedicated commands require their entries: install the bundle's review-skill/ as birdview-review/ and compatibility-audit/ as birdview-compatibility/ in the same skills directory, alongside the complete birdview/ bundle. Installing the main skill alone does not install these two entries.

In the main skill directory, run npm ci and node scripts/birdview.mjs doctor. Rerun setup --project <project-root> for configured projects to refresh foundation rules while preserving their modes. Start a fresh agent task to verify discovery and activation. Node.js 18 or newer is required; generated JavaScript is included, so users do not need to compile TypeScript. Distribution is through GitHub; the npm package remains private.

Verification and limitations

The release candidate must pass npm run check:pr: types, generated artifacts, unit tests, browser interactions, demo regeneration, input validation and paired documentation. After committing and before tagging, npm run check:install must verify source archive installation. Consult the release checklist and candidate checks for the actual release status.

Birdview shows AI-curated snapshots, evidence and declarations. It does not independently monitor all edits or enforce a filesystem write lock. Compatibility assessments depend on host rules and the actual task; they are not security certifications. The constraints view requires reviewed constraint data; the repository does not yet include a ready-to-open constraints example.