架构 - klink

三层模型

层	内容	形式
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:8082

KLayout 插件保持薄，复杂逻辑在外部 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 对接。

imaging

由同一份版图/工艺声明驱动的成像出口：.pyxs 工艺剖面、3D 渲染 + 离线交互查看器、SEM 风格俯视图、Blender 论文级渲染。

L-Edit bridge

与运行中的 Tanner L-Edit 双向文件交换：拉取选区/cell、推送几何回去；更深的 T-Cell 读写走 Python API。

MCP core

tool discovery、session registry、interaction context、recorder、transfer、diagnostics。

这些领域都是内置的，但第三方也能扩展：写一个 pip 包，通过 klink.plugins entry point 贡献自己的 MCP 工具、find_tools 域和命名资源（profile/devices/recipe/stack），故障按包隔离——这是给 PDK 供应商和扩展作者的入口，不是终端用户功能。见编写扩展包指南。

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 里的包名、入口和公开源码结构

内部开发记录只用于判断哪些内容不该公开。网站不发布未进入 release 的开发流程、私有 PDK、私有 GDS 或 NDA 验证细节。

机制层稳定，工艺层留给用户