cadence-skill

August 29, 2026 · View on GitHub

面向 Cadence Virtuoso 的 SKILL 脚本助手 —— DeepSeek Harness (DSH) 插件

让 AI 读懂 SKILL、写对 SKILL：官方文档锚定的 API 检索 · 不执行代码的深度静态检查 · 危险需求拦截

License: MIT DSH Bundle Node Dependencies Tests

为什么是它

让 AI 直接生成 SKILL（Virtuoso 的 Lisp 方言）脚本，几乎必然踩中三类致命伤：

痛点后果cadence-skill 的回答
API 幻觉：编造不存在的函数、臆造签名load 即报错，或更糟——静默出错知识库只收官方文档实测条目，每个签名带页码锚点；查不到就明说“未入库”，绝不编造
迭代器翻车：遍历 cv~>shapes 时就地 dbDelete*数据丢失、崩溃，且往往在真实版图上才暴露铁律组静态拦截 + 位置敏感的 copy() 保护判定
格式化错位：printf 家族占位符与实参不对齐CIW 报误导性错误逐行占位符-实参对账（数量 + 类型 + 端口实参形态）

三个特性构成了这个项目的底气：

  • 不执行一行 SKILL 代码，却具备接近 AST 的结构感知。 自研“词法深度坐标系”为每行代码 记录全生命周期括号栈深度（含超级右括号 ] 清栈、原生跨行字符串等真实词法语义）—— 不构建完整语法树，却能精确回答“这行在哪个括号层、属于哪个循环体”这类结构问题。 跨行循环头、同行闭合、长循环体，全部可判定，没有任何行数窗口。
  • 拒绝幻觉的纯净知识库。 26 本官方手册（IC6.1.8）全量入库，精读提炼 8488 条 API 条目 （语言/UI/版图数据库/原理图/PCell/版图套件/ROD/工艺/仿真验证/OCEAN 等；另含 4 条 明示非手册来源的社区惯用卡 xlo/xhi/ylo/yhi）， 签名带三级置信度标注——低置信签名会明确提示“请查 P 原文，不要照抄”。
  • 宿主半区零第三方依赖。 纯 Node 内置模块 + 预构建知识库 JSON，装上即用。

功能

工具作用
skill_api按函数名/关键词查官方文档：签名、说明、示例、章节页码、废弃状态与替代函数（置信度标注）
skill_check静态检查（不执行代码）：废弃 API / 性能 / 语法 / IO / UI / 命名 + iron 铁律组；支持 interactive/batch 双语境
skill_generate代码生成证据包：API 卡片 + 安全约定 + 标准骨架 + 铁律清单 + 危险需求（删除/清除/覆盖）拦截
skill_fix错误日志诊断：CIW *Error* 文本或结构化日志（JSON / YAML 审计格式）→ 精确锚点（ruleId+行号）+ 根因归类 + 规则库修复建议
skill_autofix静态自修复闭环（v1.9.0）：检查 → 确定性修复 → 复检一次完成。默认 dryRun 只出计划与 diff；dryRun:false 实际修复（自动幂等备份 .autofix.bak + 原子写 + 三重守恒校验）。可修：lex-3 多余闭括号、iron-1 Schema 注释（v1.10.0 起按上下文推断真实变量/字段/类型，插入声明锚行上方；推不出标"待补充"）；需推断意图的问题自动列入 residual 交人
配套面板Web 端“SKILL 助手”：API 浏览器、代码检查器（语境选择）、知识库状态，含 ErrorBoundary 降级

相对路径按工作区根解析（真实路径校验 + 1MB 熔断）。若调用进程没有会话工作区上下文（如 web 直连），请用 workspaceRoot 参数显式指定根目录——合法值会被记住，本会话后续调用无需再传。

iron 铁律组（Zero-Bug / Zero-Lock / Zero-Leak 的静态化子集）

iron-1 数据 Schema 注释（v1.10.0：nth/≥2 级 cadr 链/下标赋值触发，单层 car/cdr 不触发）· iron-2 循环内 nth（O(N²)）· iron-3 集合迭代删除 · iron-4 printf 占位符对齐 · iron-5 裸词 progn · iron-7 句柄判空 · iron-8 unwindProtect 事务保护 · iron-10 批处理禁 UI。 （铁律 6 布尔极性、铁律 9 作用域声明需语义分析，在 skill_generate 生成要求中强制执行。 ui-4 自 v1.10.0 起按文件级 ?unmapAfterCB t 配对判定：已配对降 info 提示，未配对仍 warning。）

快速开始

DSH（DeepSeek Harness）是一个本地运行的 AI Agent 运行时，插件通过 profile 挂载。 第一次接触 DSH？装好 Node.js ≥ 18 与 dsh，打开 Web GUI 后跟随下面任一路径即可。

① 插件市场一键安装（推荐） 打开 DSH Web GUI → 设置 → 插件市场 → 搜索 cadence-skill → 安装。

② dshpm 命令行安装

# 从 npm（若已发布）
dshpm install cadence-skill --profile web
# 或直接从 GitHub 仓库
dshpm install github:myd74108520/cadence-skill --profile web

③ 源码安装（开发者）

git clone https://github.com/myd74108520/cadence-skill.git
dshpm install ./cadence-skill --profile web

激活与验证：cadence-skill 是 bundle 插件——安装后重启 web UI 一次生效。 重启后应看到：会话中出现 skill_api / skill_check / skill_generate / skill_fix / skill_api_batch / skill_autofix 六个工具（v1.10.0 新增结构化日志诊断、 iron-1 真实 Schema 推断与 ui-4 文件级配对降噪； v1.9.0 新增静态自修复闭环；v1.5.0 新增批量核实与 lineMin/lineMax 局部报告、 skill_fix fixedCode 工具侧 diff 复检）；页面右上角出现 "SKILL" 助手面板入口。

开发期改宿主半区代码（lib/）后需再次重启生效；改客户端面板（lib/client.js）需 在 DSH checkout 中跑 pnpm run dev:web 或重建 web 产物。

30 秒看懂 skill_check

$ skill_check(target="遍历删除 shapes 的片段", context="interactive")

代码片段：发现 3 个问题（error=2 warning=1）

[E] 行17 [iron-3] 铁律3 迭代器安全：遍历 cv~>shapes/~>instances 等集合时不得直接
    dbDelete*——先 copy() 浅拷贝（或在循环前收集待删对象）
     建议: 先收集 dbId 列表再统一删除，或基于 copy(cv~>shapes) 遍历
[E] 行21 [iron-2] 铁律2 复杂度：循环内 nth() 遍历单向链表是 O(N^2) 慢操作
[W] 行 6 [perf-3] 浮点取整 fix(x*100) 会因浮点误差得到错误结果，改用 fix2
     文档: SKILL Language Reference P245/248

完整能力的“验收契约”见 tests/fixtures/abyss_v0.2.1.il—— 一份故意布满缺陷的极限测试桩，文件头逐行标注期望检出结果；v0.2.1 重构以它完成零误报通关， 发布说明见 RELEASE_NOTES_v0.2.1.md。

本地开发与验证

无 Virtuoso、不联网，克隆即可跑全量回归：

node tests/smoke.mjs            # 90+ 断言：KB 检索 / 词法扫描 / 规则检查 / 四工具 execute
node tests/mock-host.mjs        # 13 断言：apply() 接线 / 路由 / 403 门禁 / symlink 穿越 / 1MB 熔断
node tests/probe_v0.2.1_fix.mjs # 深渊桩扫描 + perf-3/iron-4 回归对照（与 live 工具同代码路径）
node tests/analyze-corpus.mjs <语料目录>  # 可选：GitHub 语料画像（语料不随仓库分发）

贡献规则请遵循“每修一项必补回归”：先在 tests/ 或 fixtures/ 固化用例，再改 lib/rules.js。规则库人工维护、每条带官方文档页码引用；知识库由构建管线从官方 PDF 生成 （PDF 版权所限不随仓库分发，kb-data/ 提供预构建数据）。

架构与安全模型

lib/index.js   宿主半区入口：注册四工具 + /plugin/cadence-skill/* 路由（loopback + Origin 门禁）
lib/tools.js   四工具实现：readTargetCode 安全读取（realpath 反穿透 / 1MB 熔断 / workspace 边界）
lib/rules.js   词法扫描器（深度坐标系）+ 规则引擎（预编译正则 + O(1) 规则 Map，2000 行 ≈ 25ms）
lib/kb.js      倒排索引检索：exact / prefix / keyword / fuzzy 四级 + 签名置信度
lib/client.js  浏览器面板（React 工厂风格，挂载于 DSH client slots）
kb-data/       预构建知识库（8616 条 / 26 本：design 1558 / layout 1682 / artist 710 /
               constraints 478 / ocean 330 / adexl 287 / schematic 285 / vivaxl 203 /
               language 494 / ui 920 / techfile 328 / pcell 138 / ocnxl 126 / …）

安全边界：只在用户显式指向文件时读取（realpath 解析 + workspace 限定 + 1MB 上限，仅读不写）； HTTP 路由仅接受 loopback Host 与同源 Origin；运行期零遥测、零外联。

编排侧改写纪律（P0-c，v1.7.0）

实测依据：trace X2/X3/X4——LLM 现写正则做结构化改写不可靠（闭括号数试错 3 次）、 pwsh -Command 引号转义失败 1 次、改写后文件状态与 edit 工具基线不同步 1 次。 本插件不提供写通道（运行时零写入红线不变），纪律落在编排侧：

  1. 同构批量改写（如"28 处 defun 加括号"）走确定性通道：先用括号配平扫描 （区分字符串/注释，skill_check 的 lex 扫描即同源逻辑）定位，再经 edit 工具 逐处落盘——禁止 pwsh -Command 正则直接写文件；
  2. 写操作单一化：文件写入只经 edit/write 工具通道；pwsh 仅做只读诊断；
  3. 写后重读：任何外部方式动过文件后，下一次 edit 前先 read 刷新基线 （消除 "file changed since read"）。

已知边界（诚实清单）

  • 版图/PCell 家族（le*/ge*/rod*/tech*/pc*）自 v1.0 起已入库（layout/rod/techfile/pcell/ design 五本手册按函数前缀指引检索）——历史上"尚未入库"的提示已移除；
  • UI 手册 392/916 条目无可靠签名（标注置信度并提示回查原文）；design 手册空签名率 1.9%， 新入库的 19 本函数参考空签名率 ≤13.2%（16 本 <5%、4 本为 0%；parasim 13.2% 为 小册尾部页码跨界）；
  • ide/ideqsg/guide 三本是用户指南/快速入门（话题索引而非函数目录）：ide 仅 6 个话题条目、 ideqsg 无函数目录 0 条目，均如实保留 doc 键、不混入 category=all；
  • 铁律 6（布尔极性）/ 铁律 9（作用域声明）需语义/作用域树分析，暂在生成要求中强制；
  • TOCTOU 理论窗口、同步检查阻塞事件循环、iron-8 ±30 行窗口——已记录，列入后续议题。

License

MIT