Analog Canvas 集成可行性分析
结论先行：Analog Canvas 与本项目的集成已在生产运行（/editor/ 自托管 + /api/projects + .icproj.json v60 + circuit-project 块渲染），不存在”从零接入”问题。真正待补的是 Agent 能力产品化（专用 Skill、契约文档、验收链）与编辑入口体验（内嵌/直达）。本报告给出证据、方案对比与路线图。
前后关系
前置知识：运算放大器设计基础（示例电路风格参考）
后续延伸：knowledge-wiki-admin/skills/analog-canvas/SKILL.md（操作契约）
外部关联：基准源知识地图（受益于高质量电路图的典型内容）
1. 现状链路（已实现）
/editor/ (Analog Canvas 构建产物, admin 静态托管, nginx 反代)
│ 保存项目
▼
POST /api/projects ──► vault: assets/circuits/<id>.icproj.json (schemaVersion 60)
│ assets/circuits/<id>.svg (bridge 渲染)
▼
文章内 ```circuit-project 块 ──► quartz/plugins/transformers/circuit.ts
构建期内联 SVG（去白底 + currentColor 适配主题）
关键实现事实：
| 组件 | 事实 |
|---|---|
| 编辑器托管 | admin app.use("/editor") + EDITOR_STATIC_DIR；上游构建由 scripts/build-editor.sh 完成 |
| 工程存储 | <vault>/assets/circuits/<id>.icproj.json + 同名 .svg，随 git 版本化 |
| 渲染桥 | scripts/knowledge-wiki-bridge.mjs：parseProject → renderDocumentSvg → 文本转路径（字体无关，CJK 回退 <text>） |
| 插入块 | 图库弹窗（showGalleryModal）列出工程并插入 circuit-project 块 |
| CircuiTikZ 通道 | POST /edit/api/circuitikz/import（dry_run 报告 + 自动建工程） |
| 存量工程 | vault 内 2 个工程（schemaVersion 58/60，加载时由 protocol 迁移） |
2. Analog Canvas 能力矩阵（源码实证）
| 包/模块 | 能力 | 对集成的意义 |
|---|---|---|
@icm/model | 原理图文档模型（instances/routes/nets/symbols/rich text/坐标域） | 结构化 model = 可程序化编辑、可 diff |
@icm/edit-engine | 放置/连线/布线的 planner、history、authoring schema | 为 Agent 提供受控编辑动作 |
@icm/render-svg | renderDocumentSvg（margin/background/objectIds） | 服务端 SVG 渲染（bridge 已用） |
@icm/exporters | 正式 SVG（含 bounds）、PNG 栅格、PDF（browser） | 导出能力完整；服务端用 SVG |
@icm/project-protocol | CURRENT_PROJECT_FILE_VERSION = 60、parse/serialize/迁移（58→60 等） | .icproj.json 是稳定契约，可安全版本迁移 |
@icm/agent-adapter + apps/mcp-server | Agent Kit、OpenAPI、MCP（18 个工具：inspect/search/apply_actions/render/export_file/import_file…） | 上游原生 Agent 通道存在，但需编辑器 claim code（人工在场） |
docs/agent/circuit-style-knowledge.md | Razavi/教材风格构图规范（左→右信号流、正电源在上、地/负电源在下、局部对称、标签走廊） | 与本站审美一致；属”清晰教材风”，非 rough.js 抖动线条 |
美学结论：可以生成符合本站”教材/Razavi”规范的电路图（风格指南 + ICM 样式档案含手绘细节如圆点句号字体）；若要求”抖动手绘线条”视觉，需要自研 symbol skin，不建议在现阶段投入。
3. 集成方案对比
| 方案 | 形态 | 优点 | 风险/代价 | 建议 |
|---|---|---|---|---|
| A 独立路由（现状） | /editor/?project=<id> 新标签；/edit/ 图库保留”新建/插入” | 零构建耦合；AGPL 上游零改动隔离；发布链不变 | 编辑体验需切页 | 保留为基座 |
| B iframe 内嵌（增强） | /edit/ 弹窗内 iframe 打开 /editor/?project=<id>&embed=1 | 编辑器不离开后台，上下文连贯 | 上游无 embed 参数（需注入 compact chrome 或 CSS）；跨源/回退成本低 | P2 推荐试点 |
| C 复用前端产物并入 /edit/ | 把 editor bundle 打进 admin 前端 | 深度整合 | 构建耦合、升级同步、AGPL 边界变复杂、发布链需改 | 不推荐 |
接口契约（方案 A/B 共用）：会话 Cookie 或 x-agent-token；GET/POST /api/projects、PUT /api/projects/:id（if-match: revision-N）、GET /api/projects/:id/preview.svg、POST /edit/api/circuitikz/import。工程与 SVG 进 git，quartz build 无需新增步骤。
4. 风险与约束
- AGPL-3.0：上游必须保持零改动（桥在外部、经
createRequire解析依赖）——任何编辑器行为改动应走上游 PR 或部署侧注入。 - 版本迁移：project schema v60 会继续演进；直写工程 JSON 的风险随时间上升 → Agent 默认走 CircuiTikZ 导入。
- MCP 全自动上限与自建通道：上游 Agent 会话需要人工 claim code；本项目已通过自建 agent 事务通道（
POST /api/projects/:id/agent，edit-engine 同一写路径）实现无人值守自由画布——支持edits / wireIntent / structureEdits，不支持需浏览器宿主规划的 authoringcommand。 - 编辑器升级：
build-editor.sh重新构建 + 部署才生效；升级前后需跑渲染回归（preview 快照对比）。
5. 路线图
| 阶段 | 交付物 | 验收标准 |
|---|---|---|
| P0 勘察（本报告） | 现状链路 + 能力矩阵 + 方案对比 | 事实可追溯到源码/生产接口 |
| P1 Skill 固化（本次） | skills/analog-canvas/SKILL.md + AGENT_API 指针 | Agent 按技能完成一次 import → 插入 → review 闭环 |
| P1.5 无人值守通道（已落地 2026-10-20） | POST /api/projects/blank + /api/projects/:id/agent（bridge 直连 edit-engine 事务） | VPS 实测：空工程创建+渲染、move+restore、空事务/过期 revision 正确拒绝 |
| P2 内嵌入口 | /editor/?project=<id>&embed=1（compact chrome）+ /edit/ 弹窗 iframe | 后台内完成”打开→编辑→保存→插入”无跳页；保存后 preview 与构建期 SVG 一致 |
| P3 Agent 验收链（已落地 2026-10-20） | 发布链渲染门禁：逐工程 parse+render 失败阻断；入库 SVG 同参比对（漂移记录）；CircuiTikZ 金样冒烟（转换+渲染） | VPS 实测：2 工程 0 错误、SVG 漂移 0、金样 ok；任何渲染失败即中止发布 |
| P4 迁移评估（已落地 2026-10-20） | 全库扫描 + 逐块转换实测：582 页仅 1 页 3 图，锚点坐标不支持导致 0% 转换；报告见 CircuiTikZ 迁移评估 | 结论：长期共存，不批量迁移；重评估阈值 = ≥10 个含锚点块 |
参考
- 技能契约：
knowledge-wiki-admin/skills/analog-canvas/SKILL.md - 权威接口：
knowledge-wiki-admin/AGENT_API.md§3.2；上游docs/agent/（API 3.0、MCP、风格指南）