# dsh-cifkit · 接口设计(v1,2026-11-21 冻结) > 本文件是 **dsh-cifkit 插件 host 半 / client 半之间的唯一真源**。 > 冻结后**允许新增字段**(向后兼容),**不允许改字段名 / 改语义**。 > 冻结依据:cifkit 仓库的实测口径(`python -m cifkit --help`、 > `cifkit/api.py::capabilities()`、`cifkit/cli.py::build_parser()`、 > `cifkit/schemas/ops.json`),不是文档转述。 > 本插件**不实现任何晶体学逻辑**:不算对称、不补氢、不切面——一律调 cifkit。 ## 0. 分层与角色 | 层 | 实体 | 说明 | |---|---|---| | 执行层(唯一写者) | cifkit CLI(`python -m cifkit …`) | 插件只 spawn 子进程,从不自己算结构 | | 宿主层 | `index.js` | 根目录/解释器解析、路径围栏、exec 白名单、作业与 SSE、只读工具 | | 渲染层(无状态) | `client.js` | 右侧栏面板、`/cifkit` 命令、工具卡、设置页 | - `index.js` 零依赖(只用 node 内置模块):desktop profile 里 `link:` 之后不需要 `npm install`。 - `client.js` 只 `require('react')`,不进构建链,不引 CDN,不引任何外网资源。 - 浏览器侧与宿主侧通过 `/cifkit/api/*` 通信;**唯一出网路径**是用户显式同意后的 cifkit 数据源动作。 ## 1. 交付物 ``` dsh-plugin/ package.json name=dsh-cifkit, type=module, dsh.bundle.patch + dsh.client.inject cordis.patch.yml insert: id=cifkit, name=dsh-cifkit index.js 宿主半(零依赖单文件) client.js 浏览器半(单文件,只 require react) locale/zh.json 与 client.js 内联字典**逐键逐值一致**(harness 断言) locale/en.json icon.svg DESIGN.md / README.md / CHANGELOG.md / docs/VERIFY.md dev/verify-host.mjs 宿主侧离线验收 dev/verify-client.mjs 浏览器侧离线验收(--write-locale 可重新生成 locale/*.json) ``` ## 2. 定位:cifkit 根目录与 Python 解释器 ### 2.1 根目录(七级,顺序固定) | 级别 | 来源 | 备注 | |---|---|---| | ① `request` | 请求参数 `root` / 工具参数 `root` / `?root=` | 最高优先级 | | ② `env` | 环境变量 `CIFKIT_ROOT` | | | ③ `config` | 插件配置 `projectRoot` | | | ④ `self` | **插件目录的上一级** | `link:` 安装时正好是 cifkit 仓根 → 无参开箱可用 | | ⑤ `session` | 会话工作目录 | 来自会话 cwd / `ctx.get('agents')` 软访问 | | ⑥ `workspace` | `ctx.get('workspaceRegistry').list()` | 逐项尝试 | | ⑦ `cwd` | `process.cwd()` | 兜底 | **合法性判据**:目录下同时存在 `cifkit/__init__.py` 与 `cifkit/cli.py`。 七级都不合法时**不抛异常、不 ENOENT 崩**:返回 `{root:null, source:'none', code:'root-not-found', error:'…'}`, HTTP 层映射为 **409 root-not-found**,工具层抛同码错误。 `GET /cifkit/api/diagnostics` 永远 200,把七行候选(含不合法项与判定 detail)原样列出。 ### 2.2 Python 解释器(四级) 1. `config.python`(字符串,可按 `"py -3"` 带前置参数,只做空格/引号切分) 2. `CIFKIT_PYTHON` 3. `/.venv/Scripts/python.exe`(win)/ `/.venv/bin/python`(*nix) 4. `py -3`(win)/ `python3`(*nix) 所有子进程固定带 `PYTHONUTF8=1`(输出按 UTF-8 解释)与 `PYTHONDONTWRITEBYTECODE=1`(浏览路径不因 import 往仓库里写 `.pyc`)。 ### 2.3 runs 目录 `/runs`;可用 `config.runsDir` / `CIFKIT_RUNS_DIR` / `options.runsDir` 覆盖 (本仓 `runs/` 有 ACL 时,指向一个可写目录即可正常跑写命令)。 ## 3. HTTP 端点总表 > 每一行到「实现分支(index.js 行号)+ harness 断言名」的逐条对应见 [docs/VERIFY.md §5](docs/VERIFY.md)。 前缀 `/cifkit`(`API_PREFIX = /cifkit/api`);只接受 `GET/HEAD/POST`,其余 405。 未知路径 404;请求体必须是 JSON 对象,否则 400 `bad-json`。 | 方法 | 路径 | 用途 | 返回要点 | |---|---|---|---| | GET | `/cifkit/api/health` | 宿主状态 | `{ok,root,rootSource,python,pythonSource,version,runsDir,runsWritable,cli,allowExec,commands}` | | GET | `/cifkit/api/diagnostics` | **只读诊断,永远 200** | `{ok,plugin,root,candidates[7],python,cli,cifkit,env,allowExec,exec{commands},degraded}` | | GET | `/cifkit/api/studies` | runs 列表(别名 `/runs`) | `{ok,root,runsDir,runs:[RunSummary]}` | | GET | `/cifkit/api/spec` | 子命令目录 + formats + bundles + sources | 全部来自 cifkit 自己;60s 进程内缓存,`?force=1` 绕过 | | GET | `/cifkit/api/run?run=` | 单 run 快照 | `{ok,run:RunSnapshot}` | | GET | `/cifkit/api/artifact?run=&name=[&download=1]` | 产物字节 | 文件字节 + `content-type` + `nosniff` | | GET | `/cifkit/api/preview?run=[&name=]` | 预览图 | PNG/JPEG/WebP/GIF 字节;没有图 → 404 | | GET | `/cifkit/api/jobs` / `/job?id=` | 作业列表 / 单个作业 | 内存,最近 50 条 | | GET | `/cifkit/api/exec/events?job=&[once=1]` | 作业日志流 | 默认 `text/event-stream`;`once=1` 给无 EventSource 的客户端一个 JSON 快照 | | POST | `/cifkit/api/exec` | 执行白名单命令 | `mode:'sync'` 直接返回结果;`mode:'job'` 返回 202 + `job` | | POST | `/cifkit/api/exec/cancel` | 取消作业 | `{ok,job:{status:'cancelled'}}` | ### 3.1 `RunSummary` ```json {"id":"spec_run","rel":"spec_run","abs":"","mtime":1762400000000,"kind":"pipeline", "ok":true,"failed_step":null,"n_steps":9,"n_artifacts":10,"atoms":1104, "formula":"Zn48 H480 C384 N192","topology":"sod","source":"local", "has_manifest":true,"has_report":true,"has_preview":true,"warnings":[]} ``` - `atoms`/`formula` 取 manifest.steps 里**最后一个带 natoms 的 step**;取不到给 `null`。 - 不含 manifest 的目录照样列出,`kind:"external"`、`ok:null`,并在 `warnings` 写明原因——**绝不臆造**。 - 按 mtime 倒序。 ### 3.2 `RunSnapshot` ```json {"id":"spec_run","rel":"spec_run","abs":"","mtime":1762400000000,"kind":"pipeline", "ok":true,"failed_step":null,"atoms":1104,"formula":"Zn48 H480 C384 N192", "manifest":{…manifest.json 原样,无则 null…}, "report_md":"# …(原文,无则 null)", "plan":[], "steps":[{name,status,detail,data}], "artifacts":[{name,rel,abs,bytes,kind,downloadable}], "validation":{ok,checks:[{name,ok,detail,severity}]}, "op":null,"warnings":[]} ``` - `plan` 取 `op.json` 的 plan(单步 run 才有);没有就是 `[]`。 - `validation` 取 `manifest.validation`;缺失给 `null`。 - 产物只列**扩展名在白名单内**、且真实存在的文件;超过 400 个截断并记 warning。 ### 3.3 `Job` ```json {"id":"job-20261121-000000-001-abcd","kind":"exec","command":"geom","mode":"job", "status":"running|done|failed|cancelled","started_at":"","ended_at":"", "elapsed_s":12.5,"argv":["geom","…"],"cwd":"","run_dir":"","returncode":0, "error":null,"steps":[],"log_tail":["…"],"result":{…}} ``` - `status` 只由退出码与是否被取消决定:0 → `done`,非 0 → `failed`,被 cancel → `cancelled`。 - `log_tail` 是子进程 stdout+stderr 原文(不加工),上限 2000 行。 - 作业在内存里保留最近 50 条;进程重启即丢(产物在磁盘上不丢)。 ### 3.4 SSE 帧(`GET /exec/events`) ``` event: meta data: {"job_id":"…","kind":"exec","command":"geom","argv":[…]} event: log data: {"line":"[geom] wrote geom.cif","stream":"stdout","replay":true} event: done data: {"job_id":"…","status":"done","returncode":0,"elapsed_s":12.5,"run_dir":"","error":null} ``` - 连上先发 `meta`,再把 `log_tail` 整段回放(刷新页面不丢日志)。 - 作业已结束 → 回放完直接 `done` 并关流。 - 还在跑 → 订阅实时日志,每 15s 发一次 `: keepalive` 注释帧;客户端断开即退订。 - `res` 不支持 `write`(极简假 res)→ 退化成一次性 JSON 快照。 ## 4. `POST /cifkit/api/exec` 请求体: ```json {"command":"geom","mode":"sync","run":"spec_run","consent":false, "params":{"file":"structure.vasp","standardize":true,"supercell":[2,2,1]}} ``` - `command` 必须在白名单内,否则 **403 command-not-allowed**(先判白名单,再解析 run)。 - **不接受调用方 argv**:只查表 + 校验参数后由 host 拼数组。 - `run` 只在命令需要时使用,且必须落在 runs-dir 内(见 §6)。 - `consent` 只对出网命令有意义(见 §4.2)。 - `params` 里出现的任何表外键名 → **400 bad-request**。 ### 4.1 白名单(14 条) | 命令 | 允许的 mode | 需要 run | 出网 | 参数(键名与 CLI 一一对应) | |---|---|---|---|---| | `route` | sync | 否 | 否 | `query`(必填,≤500 字,无换行) | | `pipeline` | sync, job | 否 | **是** | `query` / `spec`(二选一)、`source`、`topology`、`formats`、`surfaceFrame`、`bundles` | | `batch` | sync, job | 否 | **是** | `specs`(1–32 条,必填)、`jobs`、`timeout` | | `convert` | sync, job | 是 | 否 | `files`(1–64,必填)、`to`、`bundles`、`stem`、`title` | | `features` | sync, job | 是 | 否 | `files`(必填)、`jobs`、`noRdf`、`rdfBins`、`rdfMax`、`topology`、`rings` | | `dataset` | sync, job | 否 | 否 | `from`(runs|library)、`labelKey`、`noFeatures`、`noStructures`、`dedupe`、`jobs` | | `fetch` | sync, job | 否 | **是** | `source`、`topology`、`name`、`id`、`raw`、`noTypical`、`limit` | | `sources` | sync | 否 | `probe` 时是 | `probe` | | `repair` | sync, job | 是 | 否 | `file`(必填)、`addH`、`noDisorder`、`noContacts` | | `geom` | sync, job | 是 | 否 | `file`(必填)、`standardize`、`supercell`(3 整数)、`surface`(3 整数)、`surfaceFrame`、`vacuum`、`thickness`、`cluster` | | `export` | sync, job | 是 | 否 | `file`(必填)、`format`(必填,逗号列表) | | `validate` | sync | 是 | 否 | `file`(必填) | | `formats` | sync | 否 | 否 | — | | `selftest` | sync | 否 | 否 | `verbose` | 参数类型与约束:`query`(无控制字符,≤500)、`text`(≤200,通用字符集)、 `list`(逗号分隔短标识,≤200)、`number`(有限整数;计数类 ≥1;各自 max)、 `ints`(正好 N 个整数,含 per-item min/max)、`bool`(真布尔或 `'true'/'false'/'1'/'0'`)、 `enum`(查 choices)、`json`(JSON 对象,紧凑重排后单行)、 `artifact`(run 内单段文件名)、`files`(artifact 数组)。 ### 4.2 出网同意 `fetch` / `pipeline` / `batch`,以及 `sources` 带 `probe:true` 时, 必须显式 `consent:true`,否则 **400 consent-required**。 这是「唯一出网是用户显式点击的 cifkit 数据源动作」这条约束的落地点。 ### 4.3 输出改道(零写入) | mode | 输出目录 | 说明 | |---|---|---| | `sync` | `/dsh-cifkit-exec/-<时间戳>-<随机>` | 试算/快命令绝不碰仓库 | | `job` | `/-<时间戳>-<随机>` | 写命令的产物必须有落地处 | - 凡自带 `--out` / `--outdir` 的命令,argv 一律显式指向上面这个目录 (`repair -o …/repaired.cif`、`geom -o …/geom.cif`、`export -o `(目录)、 `features --out …/features.csv`、`convert --outdir …`、`fetch --outdir …`、 `dataset --outdir …`、`pipeline --outdir …`、`batch --outdir …`、`route --outdir …/route-preview`)。 - `runs-dir` 建不出作业目录 → **403 readonly-runs**(不静默失败、不改道)。 - `route` 的 `--outdir` 只进 TaskSpec 字段,不落盘。 - `dataset` 的 `--from-runs/--from-library` 固定指向 `/runs` / `/library`(只读扫描)。 - `pipeline` 不暴露 `--ingest`(它会写 `/library`,与零写入冲突), `batch` 不暴露 `--specs-file`(避免任意文件读取)。 ## 5. 错误模型 ```json {"error":"命令不在白名单:rm-rf(可用:route, pipeline, …)","code":"command-not-allowed"} ``` | code | HTTP | 触发 | |---|---|---| | `bad-request` | 400 | 缺字段 / 类型错 / 未知参数名 / 计数越界 | | `bad-json` | 400 | 请求体不是 JSON 对象 | | `path-outside` | 400 | run 或产物名逃出 runs-dir / run 目录 | | `consent-required` | 400 | 出网命令未带 `consent:true` | | `not-found` | 404 | run / 产物 / 作业不存在 | | `command-not-allowed` | 403 | 命令不在白名单 | | `exec-disabled` | 403 | `config.allowExec=false`(只读模式) | | `readonly-runs` | 403 | runs-dir 不可写 | | `root-not-found` | 409 | 七级候选都不是合法 cifkit 根 | | `bad-artifact` | 422 | 扩展名不在白名单 | | `timeout` | 504 | 同步命令超时 | | `spawn-failed` | 502 | 子进程起不来(EPERM 等,且文件重定向兜底也失败) | | `method-not-allowed` | 405 | 非 GET/HEAD/POST | | `internal` | 500 | 其它 | ## 6. 不变量(harness 必须覆盖,缺一即 bug) 1. **GET 无副作用**:只读浏览前后 runs 目录整棵树(含 mtime/size)逐字节不变。 2. **零写入浏览**:打开面板、切子页签、看 run/artifact/preview 全程不写 runs 目录; 连 import 也不写 `.pyc`(`PYTHONDONTWRITEBYTECODE=1`)。 3. **路径围栏**:`run=../../etc`、`name=a/b.cif`、`name=..`、绝对路径逃出 runs → 400 `path-outside`。 4. **artifact 白名单**:`name` 必须是该 run 目录内**真实存在**的单段文件名, 且扩展名在册(`.png .jpg .webp .gif .cif .vasp .poscar .xyz .extxyz .json .jsonl .csv .tsv .md .txt .log .lammps .data .qe .in .inp .cp2k .gjf .orca .xsf .gro .top .cfg .gen .sdf .mol .pdb .zip` 等)。 5. **不接受 argv**:任何请求都不能把 shell/argv 片段带进子进程;一切经白名单表生成。 6. **不经 shell**:一律 `spawn(prog, argvArray, {shell:false})`;路径含中文/空格也不会碎。 7. **不伪造**:拿不到的数据给 `null`/`[]`/`{}` + `warnings`,绝不编造原子数、真空值、拓扑。 8. **出网需同意**:见 §4.2;浏览路径永远不出网。 9. **失败留痕**:作业失败也保留 `log_tail` 与 `returncode`;`spec` 探针失败给空清单 + 原文 warning。 10. **feature detect**:任何 slot / 服务拿不到就跳过并记入注册日志,绝不把异常抛进外壳。 ## 7. 客户端接口 ### 7.1 信封与入口 ```js window.__ModuleLoader__.load({ id: 'dsh-cifkit', factory(require) { const React = require('react') // … return { inject: ['slots', 'locale'], apply(ctx) { /* 全部注册都在这里,且 feature detect */ } } }, }) ``` ### 7.2 注册面 | 入口 | 标识 | 内容 | |---|---|---| | 右侧栏页签 | slot `sidebar.right.pane.tab`,key `dsh-cifkit/panel` | `CifkitTab`(4 个子页签) | | 工具卡 | slot `tool.call.toolview`,key `cifkit_view` | `CifkitViewRow`(含「在工作台中打开」) | | 设置页 | slot `settings.section`,id `cifkit`,order 60 | `CifkitSettingsSection`(只读诊断) | | 页签类型 | `ctx.inject(['sidebarRightTabs'])` | `{id:'dsh-cifkit/panel', kind:'cifkit', title}` | | 命令 | `ctx.inject(['commandUi'])` | `/cifkit`(`ui.kind='action'`,打开右侧栏) | | 字典 | `ctx.locale.register('cifkit', {zh, en})` | zh/en 键集合完全一致 | **展示名**:页签与设置页分区都叫「**CIF 工作台**」(en: CIF Workbench,即 `tab.title` / `settings.title` 两个键); 技术标识仍是 `cifkit`(命令名 `/cifkit`、页签 `kind='cifkit'`、`id='dsh-cifkit/panel'`、工具名 `cifkit_view`)。 ### 7.3 面板子页签 | 页签 | 内容 | 网络行为 | |---|---|---| | 摘要(默认) | run 事实表、步骤、校验结论、report 开头 | 只读 GET | | 参数 | `route` 一句话解析、`geom` 表单、`export`(格式来自 `/spec`)、`pipeline`+出网同意 | 点击才 POST | | 运行 | 状态/argv/退出码/耗时/输出目录/日志(SSE 或 1.2s 轮询)/data/取消 | 只读 + cancel | | 产物 | 产物表 + PNG 预览 + 下载链接 | 只读 GET | ### 7.4 locale - namespace `cifkit`;`locale/zh.json` 与 `locale/en.json` 是内联字典的镜像, `node dev/verify-client.mjs` 断言「内联 zh == 内联 en 键集合」且「JSON == 内联」; `--write-locale` 可从内联字典重新生成镜像文件。 ## 8. 离线验收 ``` node --check index.js node --check client.js node dev/verify-host.mjs node dev/verify-client.mjs ``` 四条都必须 exit 0。逐条期望见 `docs/VERIFY.md`。 ## 9. 与 cifkit 的边界(已知限制) - 插件**不下载 POTCAR/UPF/力场**,也不把 bundle 说成「可直接运行」(沿用 cifkit 的措辞)。 - 插件**不解析 CLI 文本做决策**:能用 `--json` 就用 `--json`;解析失败给 `null` + warning。 - `/spec` 的子命令目录依赖 CPython 的 `argparse` 内部结构(`_actions`/`_choices_actions`); 拿不到时给空 `commands` + warning,**不手写替代清单**。 - 作业注册表在内存里:DSH 重启后历史作业不可查(产物仍在磁盘)。 - `subagent` 环境下无法装进 profile:安装与重启由 lead 统一处理(见 README)。