CircuiTikZ 迁移评估
结论先行：全库 CircuiTikZ 存量极小（582 页中 1 页 / 3 个图），自动转换成功率 0%；失败的根因是转换器不支持命名节点锚点（(SUM1.west) 等），而非拓扑不可表达。建议长期共存：存量保留 LaTeX 管线，不做批量迁移；新图一律走 circuit-project（Agent 路径 A/D）。
2026-10-20 续：其中 2 个框图（Fig 10.48/10.51）已通过 路径 D（agent 事务 + 草稿图元） 重绘为工程并替换为
circuit-project；OTA 原理图（Fig 3）保留 LaTeX 管线，详见 §3。
前后关系
前置知识：Analog Canvas 集成可行性分析（双管线架构与三轨通道） 后续延伸：按需手工重绘存量图（在 /editor/ 中） 外部关联：基准源知识地图（新电路图示例）
1. 评估方法（可复现）
在 VPS 部署工作区用桥模块逐块执行：
- 扫描
wiki/**/*.md（排除 schema/assets/templates/raw），正则提取```circuit围栏块； - 每块调用
circuitikz-to-project.convertCircuitikz(code)（与/edit/api/circuitikz/import同一转换器）； - 聚合
report.errors / warnings / unmapped / stats，按错误类型归一。
2. 实测结果（2026-10-20，582 页）
| 指标 | 数值 |
|---|---|
| 扫描页面 | 582 |
含 circuit 块的页面 | 1（concepts/16-bit音频CT-ΔΣ调制器设计实例.md） |
| 块总数 | 3 |
| 转换成功 | 0 |
| 仅警告 | 0 |
| 转换失败 | 3（62 errors / 50 warnings） |
| unmapped 器件 | 0 |
错误类型 Top（归一后）：
| 错误 | 次数 | 说明 |
|---|---|---|
坐标无法解析：(INT1.west) | 6 | node.anchor 形式坐标 |
坐标无法解析：(INT1.east) | 6 | 同上 |
坐标无法解析：(SUM1.west / .east / .south / .north) | 4+4+4+3 | 同上 |
坐标无法解析：(M1.D) 等引脚锚点 | 4 | 同上 |
坐标无法解析：(vo1) | 3 | 非数字、非已注册节点名 |
转换器支持：数字坐标
(x,y)、相对坐标++dx,dy、普通节点名(name)；不支持(node.anchor)引脚锚点——这是 3 个图的唯一阻断原因。
3. 已执行迁移（图 1/2，2026-10-20 续）
| 项 | 事实 |
|---|---|
| 手段 | Agent 路径 D：POST /api/projects/blank 建空工程 → upsert_drafting_object 事务批量写入草稿图元（矩形/圆/文本/箭头/构造线）→ 桥渲染 SVG → 入库 |
| Fig 10.48（单环原型框图） | slug c-fig1048-ctdsm，43 个草稿对象，SVG 56,082 B（21 path / 2 circle，字形已转路径） |
| Fig 10.51（复合系统框图） | slug c-fig1051-ctdsm，55 个草稿对象，SVG 73,970 B（26 path / 2 circle） |
| 文章替换 | 前两个 ```circuit 块 → ```circuit-project（slug 指向上述工程）；OTA 原理图（图 3）保留 LaTeX（器件锚点无法被转换器表达，硬转会失真） |
| 迁移后存量 | circuit 块 3 → 1；circuit-project 块 0 → 2（同页） |
经验：框图的正确工具是草稿图元（drafting），不是电路器件符号；原理图（器件+引脚）才属于 circuit-project 的强项——两者不要混用。
4. 成本/收益
| 方案 | 工作量 | 收益 | 风险 |
|---|---|---|---|
| A 长期共存（推荐） | 0 | 现有 LaTeX 管线稳定，站点渲染正常 | 无 |
| B 手工重绘 3 图（/editor/） | 约 0.5–1 人时 | 视觉统一、可交互维护、进入电路画廊 | 需目视验收 |
| C 扩展转换器支持锚点 | 1–2 人日 + 回归 | 提升 Agent 写 CircuiTikZ 的兼容面 | 锚点依赖器件几何（.C/.B/.E 与 .east/.west 语义不同），需按 symbol 引脚映射，回归成本高 |
决策依据：存量仅 3 图，C 的投入产出比不成立（当前仅 1 页受影响）；但若未来 Agent 大量手写 CircuiTikZ，C 的价值会上升——建议以「出现 ≥10 个含锚点块」为重新评估阈值。
5. 迁移手册（如未来需要）
- 单页评估：转换器
dry_run报告 → 若仅锚点错误，评估手工重绘（B）而非硬转； - 重绘后在
/editor/保存 → 文章改用circuit-project块 → 删除旧circuit块； - 发布链门禁会校验工程渲染（失败阻断、SVG 漂移记录）；
- 禁止批量脚本替换：LaTeX 管线与 SVG 管线产物不同（字体、主题适配），需逐页目视验收。
6. Agent 指引（已同步技能）
- 新图优先
POST /edit/api/circuitikz/import（白名单 + 数字坐标）； - 需要
(node.anchor)坐标或非白名单器件 → 路径 D（agent 事务）或路径 C（人工/editor/）； - 不要为了迁移而迁移：
circuit块可长期保留。
参考
- 转换器：
knowledge-wiki-admin/scripts/circuitikz-to-project.mjs - 管线：
quartz/plugins/transformers/circuit.ts（circuit / circuit-project 双分支） - 技能：
knowledge-wiki-admin/skills/analog-canvas/SKILL.md