核心思路 - klink

geometry-first 核心思路

传统参数化版图工具（如基于 stretch handle 的 PCell）默认形状是矩形——拉一条边就等于一个参数 W。CMOS 全是方块，这招管用。但光子学、柔性电子、MEMS、超导电路的形状不是方块：渐变 taper、弧形弯曲、自由拓扑，没有“拉那条边 = 参数”这种一一对应。

klink 走另一条路：轻量语义标注（lightweight semantic annotation），而不是完备约束系统。你在自己确定的几何位置上标记意图，routing 算法补全被标记之间的部分；不满意就补标、再跑。这是一个可迭代收敛的过程，不是一次性黑箱生成。两类标记：

Port

连接意图（net endpoint）

klink_Port PCell，携带 net + 朝向 + 宽度。它回答“这里要连出一条属于某网络的线，朝哪个方向、多宽”。

Anchor

路由约束（routing constraint）

klink_Anchor PCell，kind 为 waypoint_region / bend_region / corridor。它回答“线应该经过这里 / 在这里弯 / 走这条通道”。

这两者就是路由后端的输入：先 mark Port + Anchor，再调一个 routing.* 工具，几何布线由算法生成。这条边界让 klink 的机制层保持工艺无关——所有工艺事实（层、尺寸、间距）都由你在调用时显式传入。

Port：连接意图

Port 标记一个网络端点。它是一个 klink_Port PCell，参数就是唯一权威数据源（center / orientation / width / target_layer / port_type / net）——三角朝向标记和文字标签由 PCell 自动生成，永远不会和参数漂移。routing 后端默认从 999/99 层读取 Port 标记。

port.mark cell="NET1" name="A" center_um=[0,0]   orientation="E" width_um=2 net="sig"
port.mark cell="NET1" name="B" center_um=[80,20] orientation="W" width_um=2 net="sig"
port.list cell="NET1"

命名对齐 gdsfactory 习惯（方向名 E0/N0/W0/S0、类型名 o1/e1）。你在 GUI 里画的三角/矩形也能被吸附固化成标准 Port——通过方向推断 + 就近真实边吸附（贴边容差、45° 栅格回退）。Port 由不可变 name 标识，可以 update / transform（含按 GUI 选择批量改）/ unmark；重复或空名可以用 port.repair_names 修复。完整工具见 MCP 参考 · Port 与 Anchor。

Anchor：路由约束

Anchor 表达“线要怎么走”。默认从 999/1 层读取。三种 kind：

kind	几何与语义
`waypoint_region`	矩形必经区域——线必须穿过它。
`bend_region`	三角形，取其内切圆作为弯曲搜索区——线在这里做圆弧/折角过渡。
`corridor`	折线定义的方向性通道：线要“进入 → 沿方向走 → 离开”，不是简单穿过。普通 corridor 必经；标 `choice_group=BUS` 后变成 `routing.global_channel_cell` 的可选负载均衡候选通道。

anchor.mark cell="NET1" kind="waypoint_region" center_um=[40,40] radius_um=6 net="sig"

Anchor 与 Port 共享同一套身份模型：id/name 定位、label 显示、net 连接语义三者分离，重复/空 id 可以用 anchor.repair_ids 修复。这套“薄插件只做增删改、厚客户端负责理解手绘标记”的分工是有意为之——如何解读一个标记属于会持续演化的 workflow 逻辑，不该固化进 KLayout 插件。

Keepout 不是 anchor 类型。 避障是你传给 routing 工具的 obstacle_layers——你自己设计里的 keepout 层。klink 不带默认 keepout 层（900/0 是保留 keepout 层，structdevice 内部把它当 scratch 用）。

标记 → 路由 → 验证

geometry-first 的最简完整流程：

1 · 几何手绘或生成器件/焊盘几何。

2 · 标意图port.mark + anchor.mark。

3 · 路由routing.* 生成布线几何。

4 · 验证结构化报告 + live LVS。

port.mark cell="NET1" name="A" center_um=[0,0]   orientation="E" width_um=2 net="sig"
port.mark cell="NET1" name="B" center_um=[80,20] orientation="W" width_um=2 net="sig"
anchor.mark cell="NET1" kind="waypoint_region" center_um=[40,40] radius_um=6 net="sig"
routing.tapered_hybrid_cell cell="NET1" angle_mode="manhattan" obstacle_layers=["900/0"]
# 检查结果：ok=true、obstacle_hit_count=0、无 sibling overlap

路由后端按拓扑/质量分工（tapered hybrid 为主、tapered polygon 连续 taper、steiner 多端、damped 更强避让、global channel 全局决策、multilayer escape 跨层逃逸、gdsfactory 策略）。逐个见 MCP 参考 · 路由后端。多后端拒绝“一个万能路由器”：它们共享同一套 Port/Anchor 规划器，输出差异是“表达形式不同”而非“质量分级”。

几条贯穿路由层的设计原则：

零栅格化几何路由。 用可见性图 + Dijkstra，产生完美直线段而不是锯齿，天然支持 0/45/90° 角度模式；不依赖 klayout.db。
Port 出线契约。 路由器不能把 Port 当任意点——必须沿 orientation 从 center 发射再进入全局寻路；会造成回折时加一个垂直小 dogleg，而不是静默改写 Port 方向。
结果必须自证。 ok / obstacle_hit_count / sibling overlap / route_count 是结构化质量门；零匹配不等于成功。参数无法被所选后端满足时会报错并点名哪些后端支持它，绝不静默忽略。
诚实汇报边界。 global channel 明确“不是完整的拆线重布拥塞路由器”；multilayer escape 不建模过孔包围盒；gdsfactory 的 astar 不可靠，klink 会二次校验、穿墙则主动报错。

用户项目模型

klink 和 klink_plugin 是机制层（安装的包，永远不改）。你的工艺、器件、尺寸、层号、DRC/LVS 规则都留在用户项目里，显式传给机制层。

your-project/
  pdk.py          你的工艺——工艺事实唯一的家
  custom_devices/ agent 或你写的 device generator / flow 脚本
  specs/          .klink 规格、net table、交互意图
  out/            生成的 GDS / 结果（切勿提交 GDS）
  AGENTS.md       agent 规则（CLAUDE.md 指向它）
  mcp.example.json

用户项目绝不包含 GDS/PDK 内容——无论专有 foundry PDK 还是器件版图。模板 .gitignore 默认拦 *.gds/*.oas。让 recipe 代码在运行时指向这些文件（开放 PDK 可依赖，同样不提交）。

创建项目

用打包进 wheel 的 CLI 脚手架一个项目，再用 agent 打开它。

klink init my-chip
cd my-chip

描述你在做什么，agent 识别领域后从匹配的 recipe 脚手架 pdk.py + 第一条 custom_devices/ 脚本，并把你的工艺显式传进 klink。没有硬编码默认项目——新项目要先明确 domain 和 geometry tier 才开始生成。

升级 klink 之后，用 klink update mychip（或在项目目录内直接 klink update）刷新 example_template/ 里的 starter demo；你自己的 pdk.py、custom_devices/、.klink/、out/、specs/ 绝不会被覆盖：

python -m pip install -U klayout-klink
klink update mychip

选择 recipe

recipe 是某个领域的参考实现。geometry tier 说明它需不需要你的机密几何。

领域	几何层级	公开 release 状态
EBL nanodevice	Self-contained	离线可跑，示例内自带参数。
Neural electrode harness	Self-contained	需 live KLayout，公开示例用 Port/Anchor PCell + tapered-hybrid router。
Silicon photonics	Open or your own	公开 feature 用开放 `gf.gpdk`（需装 gdsfactory）；换成你的 PDK 即路由你的。
Digital P&R → LVS	Self-contained or your own	fit-device demo 用合成 exemplar；换成你真实器件几何来拟合并布线。Verilog→gates 需外部 yosys，缺失时流程返回确切修复命令。

新领域=一个为它塑形的 pdk.py + 一个 custom_devices/ 脚本（import 你的工艺、显式调 klink API）。复制最近的目录条目改写即可，你从不编辑 klink 来加领域。

验证习惯

klink 教程不把截图当完成依据。判定用：

layout.info、cell.tree、layer.list 查结构。
shape.query、instance.query、selection.get 查几何。
routing report 的 ok、overlap、obstacle hit、route count。
live LVS 的 match=True。

一个路由/版图只有在 live KLayout LVS 返回 match=True 时才算“完成”；marker 计数和“看起来连上了”都不算。截图可以向人展示结果，但不能替代结构化验证。

核心思路：geometry-first