快速上手 - klink

环境要求

KLayout 桌面版。klink 是围绕 KLayout GUI 和 `pya`/`db` API 工作的工具。
Python 3.10 或更新版本。release 元数据声明 `requires-python = ">=3.10"`。
可选：Claude Code、Codex 或其他 MCP client。
按工作流可选安装 `gdsfactory`、`klayout` Python 包、NumPy/OpenCV、SciPy/scikit 系列库。

klink 核心包不打包第三方科学库。某个功能缺依赖时，工具会返回具体 `pip install` 指令。这样可以保持基础安装轻量。

支持版本

组件	版本下限	说明
`klayout`（pip）	>= 0.28	0.27 不支持：klink 的 device extractor 用到一个 `GenericDeviceExtractor` 重载，pya 自己的文档说明它是 0.28 才引入的。
`gdsfactory`（`[photonics]`）	>= 9.0, < 10	9.x 全线版本都覆盖到。gdsfactory 8.x 测试能跑，但还没纳入 pin，当作实验性对待。

这些版本由公开仓库 CI 的 gf-compat / klayout-compat 矩阵持续验证。

安装 Python 包

普通用户从 PyPI 安装公开包：

python -m pip install klayout-klink

这会安装 `klink` 和它自带的两个 Rust 加速内核 `klink-boxmaze-rs` 与 `klink-trackmaze-rs`。如果某个平台没有预编译 wheel，pip 可能回退到源码编译，需要 Rust toolchain；只想安装纯 Python 核心时可用：

python -m pip install klayout-klink --no-deps

按需安装可选能力：

python -m pip install klayout
python -m pip install gdsfactory
python -m pip install numpy opencv-python-headless
python -m pip install scipy scikit-learn scikit-image

安装 KLayout 插件

`klink_plugin` 是 KLayout salt package。它不是普通 Python import 包，安装方式是复制公开仓库里的 `klink_plugin/` 文件夹到 KLayout 的 salt 目录。

Windows PowerShell

cd path\to\klink
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\KLayout\salt" | Out-Null
Copy-Item -Path ".\klink_plugin" -Destination "$env:USERPROFILE\KLayout\salt\" -Recurse -Force

Linux / macOS

cd /path/to/klink
mkdir -p ~/.klayout/salt
cp -R klink_plugin ~/.klayout/salt/

复制后重启 KLayout。插件启动成功时，KLayout console 会出现类似：

[klink.server] listening on 127.0.0.1:8765

如果 `8765` 被占用，插件会尝试后续端口直到 `8799`。每个 KLayout 窗口都是独立 session。

连接测试

启动带插件的 KLayout 后，用 Python client 连接：

from klink import KLinkClient

with KLinkClient() as c:
    print(c.ping(nonce=42))
    print(c.layout_info(verbosity="summary"))

如果 KLayout 监听的是其他端口：

from klink import KLinkClient

with KLinkClient(port=8766) as c:
    print(c.ping())

也可以直接跑 preflight：

python -m klink.doctor --port 8765

第一个结果

完全离线：EBL wraparound

PyPI-only 用户先创建项目，然后运行模板里的 starter demo。这个 demo 不需要 KLayout、不需要外部 GDS：

klink init my-chip
cd my-chip
python example_template/nanodevice/ebl_wraparound.py

如果你是在公开源码/release checkout 里，也可以运行公开 gallery 的模块路径：

python -m examples_klink.public.demos.nanodevice.ebl_wraparound

release 文档记录的实测摘要：`"ok": true`，40 electrodes，12 patches，writefield 16 fields / 11 windows / 20 crossings，0 violations，0 overlaps。

live KLayout：neural electrode harness

这个 demo 需要 KLayout + 插件，但不需要你的 GDS：

python example_template/nanodevice/neural_electrode.py --port <session-port> --elec-rows 4

源码/release checkout 中对应路径：

python -m examples_klink.public.demos.nanodevice.neural_electrode --port <session-port> --elec-rows 4

release 文档记录的实测摘要：48 ports，24 nets routed，sibling-overlap 0，obstacle-hit 0。

KLayout 的 port 只是 session 端口，没有特殊角色。跑 demo 时请用空白或测试窗口，不要指向正在手工编辑的重要 layout。

升级 klink 后刷新 starter

装了新版本 klink 之后，用 `klink update` 刷新 `example_template/` 里的 starter demo；你自己的文件（`pdk.py`、`custom_devices/`、`.klink/`、`out/`、`specs/`）绝不会被碰：

python -m pip install -U klayout-klink
klink update my-chip   # 或者在项目目录内直接运行: klink update

接入 MCP

安装 Python 包后会有 `klink-mcp` 命令入口。先给项目安装 agent skill 和项目记忆文件：

cd path\to\klink
klink-mcp --setup .

claude mcp add klayout -- python -m klink.mcp --profile read,write,verify,escape --session-id project-klink

常用 profile：

Profile	用途
`read`	layout、cell、layer、shape、view、selection 查询。
`write`	创建 cell、layer、shape、instance、PCell 和 undo transaction。
`verify`	DRC、LVS 和结构化验证工具。
`escape`	`exec.python` 等受控 escape hatch。
`all`	暴露全部工具。

排错

Python 连接失败：确认 KLayout 已启动、插件已复制到 salt、重启过 KLayout、端口正确。
MCP 工具存在但调用报连接错误：MCP server 在跑，但 KLayout 不可达。启动 KLayout 后调用 `klink.reconnect` 或重启 MCP client。
gdsfactory 工具缺依赖：在运行 MCP server 的同一个 Python 环境里安装 `gdsfactory`。
PowerShell 不允许激活 venv：只对当前进程放开脚本执行策略。

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1