为什么我创建 Agent Canvas

从现有 Repo 到完整交互画布

交给能读写 Repo 并执行命令的 coding agent。无需事先准备 Storybook 或手写画面清单；仅安装包不会自动填满画布。

粘贴给你的 Coding Agent

Read https://github.com/tombelieber/app-canvas/blob/v0.16.0/AGENT_GUIDE.md and add a completely populated Agent Canvas to this repository. Discover all screens, components, variants, states and navigation from the whole application source. Use original UI code. Create the missing synthetic fixtures and render harnesses. Reconcile an independent source inventory with rendered cases and source-linked runtime checks. Add checked happy, failure and recovery journeys. Group by actual page and feature, connect checked flows, deduplicate repeated captures and resume checkpoints. Run --ui-complete against the original source root; keep the stricter --complete source audit separate and unchanged. Continue until the full landscape is populated and verified; report genuine blockers as incomplete. Keep production sessions, credentials and real user data out of previews.

1. 安装共享工具

   使用 Node.js 22+，沿用项目的包管理器与 lockfile。安装固定版本的 GitHub release，再安装浏览器。npm 12 若阻止此直接 Git 依赖，才添加 --allow-git=root；无需更改全局设置。

   npm install --save-dev github:tombelieber/app-canvas#v0.16.0
   npx agent-canvas browsers

2. 先盘点，再选择 Case

   对整个原有 App repository 运行 plan。检查所有文件和 UI anchors，追查影响 UI 的依赖，并核对实际导航。独立列齐页面和状态，不能由 catalog 反推范围；未解决 UI 必须保留。

   npx agent-canvas plan --source-root . --out ui-review/ui-inventory.json
   npx agent-canvas status --inventory ui-review/ui-inventory.json

3. 用 Fixtures 渲染原有 UI

   Agent 创建 ui-review/canvas.config.mjs、catalog、合成 fixtures、preview entry 和可检查 journeys。Web adapter 导入原有页面、providers 与样式；fixtures 只替代数据和依赖，不能重写 UI。拒绝未知网络请求。

   ui-review/
     canvas.config.mjs
     catalog.json
     frame.jsx
     fixtures.js
     README.md
   .artifacts/app-canvas/inventory.json

   // package.json → scripts
   "ui:review": "agent-canvas --config ui-review/canvas.config.mjs"

   React/Vite · Agent 指南

4. 验证状态和交互

   覆盖已实现的正常、空白、加载、错误、拒绝访问、对话框和恢复状态。检查每个 case，流程要操作真实控件。核对 inventory、关联源码的 assertions 和 routes，再对同一 App 根目录通过 --ui-complete。 --complete 保留为独立、严格的完整源码审查；其待办数并非漏页数。

   npx agent-canvas populate --config ui-review/canvas.config.mjs --source-root . --verify

5. 从源代码维护和检查

   运行 ui:review，查看总览和状态图，再播放流程。让 Agent 修改真正的 App 源码；既有 preview 会重新构建。新 route 或状态需要更新 inventory、fixture 和 journey，交付前必须通过完整检查。

   npm run ui:review

哪些文件留在你的 App Repo

共享包维护 viewer、CLI 和 skill；各 Repo 维护自己的 adapter、fixtures、独立 inventory、catalog 和交互检查。从可运行的 React/Vite 示例开始；其他技术栈使用专属 adapter。

可选的 Agent Skill

Codex 和 Claude Code 可以安装附带的 skill，其他 coding agent 可直接阅读 AGENT_GUIDE.md。Canvas runtime 不调用模型，也无需模型 API key；你选择的 Agent 有自己的费用和权限。

npx agent-canvas install --target both