三层模型
| 层 | 内容 | 形式 |
|---|---|---|
| Mechanism | `klink` Python client、算法、MCP bridge、KLayout 插件。 | 安装包和 salt package，普通用户不修改。 |
| Development repo | 测试、录制、开发示例、内部设计记录。 | 开发仓，不等于公开发布内容。 |
| User project | `pdk.py`、`custom_devices/`、specs、输出结果。 | 用户自己的目录，agent 在这里写代码。 |
控制路径
Agent (Claude Code / Codex)
-> MCP server (python -m klink.mcp)
-> klink client (NDJSON over TCP)
-> KLayout plugin (in-process RPC server)
RPC: 127.0.0.1:8765+
klive-compatible: 127.0.0.1:8082KLayout 插件保持薄，复杂逻辑在外部 Python 中运行。这样 agent、脚本、测试和可选第三方库不需要塞进 KLayout macro 环境。
Process purity
`klink` 核心不带工艺默认值。文档和 demo 中出现的层号、尺寸、器件参数，属于示例或用户 `pdk.py`，不是 klink 的默认工艺。
- 换工艺：写你的 `pdk.py`，不要改 `klink/`。
- 调用 API：把 layer、width、spacing、device library 等显式传入。
- 缺参数：工具应该返回带 `next_action` 的 instructive error，而不是静默套默认值。
Agent 工具设计原则
klink 的可靠性不靠“提示词写得好”，而靠工具本身的设计。同一套原则在路由、搬运、器件流里反复出现：
- 一个用户意图 = 一次调用。 编排本身就是产品，不指望弱 agent 正确拼装原语顺序（如
structdevice.build_from_netlist、nanodevice.hallbar、photonics.connect）。 - 错误即指令，不是诊断。 失败结果携带
next_action（可直接复述给用户的下一步）和problems（须逐字转述、不得杜撰）；歧义返回候选而非瞎猜；成功结果也带next_action，让工作流成为“靠结果串联的链表”。 - 先验证后变更（validate-before-mutate）。 纯计算/校验先做完、确认无误才写盘或改版图；编辑包在事务里，失败可幂等重试、不留疤（如
connect_nets任何 LVS 不匹配就整体撤销）。 - 状态落盘，不留在 agent 记忆里。 跨调用/跨会话的上下文由工具自己持久化到文档化路径（
.klink/下的 spec、net 表、interaction context），任何 agent、任何新会话都能续接。 - 长驻进程纯净。 工具要在同一 MCP server 进程里反复调用而不互相污染，例如
exec.python用每连接独立命名空间 + 显式exec.reset。
这些保证分三层实现：最强的是工具本身的强制（跨 harness 通用）→ 中立的 lane/recipe 定义 → 各 harness 的薄适配（CLAUDE.md / AGENTS.md）。所以即使换一个较弱的 agent，工具也会用“带修复建议的报错”把它拉回正确做法。
批量 RPC
生成式版图不能一个 shape 一次 RPC。klink 提供批量方法降低 TCP、JSON、transaction 和 GUI bookkeeping 成本。
| 工作量 | 优先 RPC |
|---|---|
| 同一个 cell/layer 上很多 box | `shape.insert_boxes` |
| 混合 shape | `shape.insert_many`，支持 box、polygon、path、text。 |
| 很多 child-cell instances | `instance.insert_many` |
| 很多 library/basic PCell instances | `instance.insert_pcell_many` |
单个 insert 适合调试，不适合作为生成器主循环。
公开领域
routing
Port/Anchor marker 上的 tapered、steiner、damped、channel 后端，以及自定义器件电路 detailed-router 到 LVS。
nanodevice
EBL wraparound、Hall bar、neural electrode harness 和 flake 相关工具。
photonics
gdsfactory bridge、blackbox port harvesting、import_gf_component、photonic net intent、reroute。
structdevice
device extraction、netlist、logic map、layout engine、P&R、LVS-lite 和 live LVS 对接。
MCP core
tool discovery、session registry、interaction context、recorder、transfer、diagnostics。
release 边界
这个网站只写公开 release 可验证的内容。站点内容核对过以下公开入口：
- `README.md` / `README.zh-CN.md`
- `docs/public/` 的 getting-started、architecture、demos、recipes、project-model、control-plane、interactive-workflows
- `examples_klink/public/` 的 demos、features、smoke
- `klink/`、`klink_plugin/`、`pyproject.toml` 里的包名、入口和公开源码结构