# dsh-cifkit · 验收(逐条命令与期望) > 路径已做发布化替换,命令可按占位符复跑;结论与数字一个都不许改。 > 全部命令在该目录执行:`` > 本次实测时间:2026-11-21;cifkit 检出:``(插件目录的上一级) > Python:`/.venv/Scripts/python.exe`(3.14.8,editable 装了 cifkit 0.1.0) ## 0. 四条必过命令(本节即验收口径) | # | 命令 | 期望 | 本次实测 | |---|---|---|---| | 1 | `node --check index.js` | exit 0,无输出 | exit **0** | | 2 | `node --check client.js` | exit 0,无输出 | exit **0** | | 3 | `node dev/verify-host.mjs` | exit 0,`RESULT: PASS` | exit **0**,235 通过 / 0 失败 / **0 跳过** | | 4 | `node dev/verify-client.mjs` | exit 0,`RESULT: PASS` | exit **0**,113 通过 / 0 失败 | 一次跑完: ```powershell cd node --check index.js; "exit=$LASTEXITCODE" node --check client.js; "exit=$LASTEXITCODE" node dev/verify-host.mjs; "exit=$LASTEXITCODE" node dev/verify-client.mjs; "exit=$LASTEXITCODE" ``` 实测尾部输出: ```text dsh-cifkit host harness 汇总 通过 : 235 失败 : 0 跳过 : 0 合计 : 235 RESULT: PASS(235 项通过,0 项跳过) host_exit=0 dsh-cifkit client harness 汇总 通过 : 113 失败 : 0 合计 : 113 RESULT: PASS(113 项通过) client_exit=0 ``` 辅助计数(与上面一致,便于机器核对): ```powershell ($h | Select-String "^ ok ").Count # 235 ($h | Select-String "^ FAIL ").Count # 0 ($c | Select-String "^ ok ").Count # 113 ($c | Select-String "^ FAIL ").Count # 0 ``` ## 1. `verify-host.mjs` 覆盖了什么(235 条) | 分组 | 条数 | 关键断言 | |---|---|---| | 导出面 | 27 | 24 个导出 + `inject=['webServer','tools']` + `CifkitError` 带 `.code/.status` | | resolveRoot / rootCandidates | 16 | 七级顺序逐级命中;七级皆不合法 → `root-not-found`;候选表恰好 7 行 | | pythonSpec / resolveRunsDir | 8 | config > env > `.venv` > 平台兜底;runs-dir 三种覆盖 | | 路径围栏 | 9 | `../../etc`、空 run、绝对路径逃出、`a/b.cif`、`..`、`evil.exe` | | listRuns / readRunSnapshot | 22 | atoms 取最后一个带 natoms 的 step;无 manifest 的目录「不臆造」;validation 原样照抄 | | EXEC_COMMANDS / buildExecArgv | 44 | 14 条命令 + 18 条 argv 精确形状 + 14 条拒绝路径(403/400/422) | | cifkit_view 工具 | 13 | 只读、默认不含 report、缺检出 409、run 不存在 404、注册面 2 条 | | HTTP 路由分派 | 60 | GET 只读 + **零写入前后快照一致**;artifact/preview 字节与 400/422/404;POST 白名单/同意/禁用;sync 输出改道 tmp;job 202 + SSE 回放 + cancel | | 真检出项 | 12 | 真 spawn `python -c` 探针:**31 formats / 12 bundles / 6 sources / 19 子命令**;真 `formats --json`;真 run 上跑 `cifkit_view` | | 离线兜底 | 7 | 缺检出时 6 个端点全 409 `root-not-found`(不是 ENOENT 崩) | 真检出实测数字(本次): ```text ok probeSpec(真检出):formats=31 bundles=12 sources=6 commands=19 ok 真检出 commands 含 geom/validate/formats/pipeline ok listRuns(真检出) 返回 run 列表 ok cifkit_view(真检出) 产出紧凑 Markdown NOTE 真检出样本 run: demo_sod_zif8(steps=10,产物=12) ok runCli(formats --json) exitCode=0 NOTE 真 CLI 输出 2641 字节;解析到 31 个格式 ``` ## 2. `verify-client.mjs` 覆盖了什么(113 条) | 分组 | 条数 | 关键断言 | |---|---|---| | 模块信封 | 6 | `__ModuleLoader__.load` 的 id=`dsh-cifkit`;factory 只 `require('react')`;导出 `apply` 与 `inject` | | 注册项 | 29 | locale.register/bind;3 个 slot(tab / 工具卡 / 设置页);tab 类型 `{id,kind:'cifkit'}`;tab 标题=设置页分区名=`CIF 工作台`;`/cifkit` 命令;style 标签无外链 | | locale 对齐(防漂移) | 4 | 内联 zh/en 键集合一致(164 键);`locale/{zh,en}.json` 与内联**逐键逐值一致** | | 面板:摘要 | 14 | 4 个子页签;run 事实/步骤/校验失败项/report 开头;首屏 4 个 GET 全是 GET | | 面板:参数 + 执行与日志 | 20 | route/geom/export/pipeline 表单;格式来自 `/spec`;缺文件不发请求;route POST `{command,mode:'sync',params.query}`;geom job POST;无 EventSource 时 1.2s 轮询拿日志与 result | | 面板:产物 | 5 | 文件名/大小/类型;每个产物都有 `/cifkit/api/artifact…download=1` 链接;预览图指向 `/cifkit/api/preview` | | 工具卡 | 6 | 工具名/run/返回片段;「在工作台中打开」点击后切到 `cifkit` 页签并展开右侧栏 | | 设置页 | 10 | 调 `/diagnostics`;七级候选级别名;Python 探测串;CLI 入口;exec 白名单条数;注册结果 | | 端点常量 | 11 | `/cifkit/api`、`/artifact`、`/preview`、`/exec`、`/exec/cancel`、`/exec/events`、`once=1`、`NETWORK_COMMANDS` | | feature detect | 8 | `apply({})` / `locale:null` / 无 `slots` 都不抛;重复 apply 会 teardown 上一份并移除 style 标签 | ## 3. 手动/浏览器侧自查(可选) 面板与「零出网」的运行时自查(需要 DSH 已加载插件): ```text 1) 设置页搜 cifkit → 诊断小节应显示:root 命中、Python 3.14.8、CLI 入口 ok、注册结果全「就绪」 2) 打开右侧栏 cifkit 页签 → 摘要页应列出 runs/ 下的 run;DevTools Network 里**只有 /cifkit/api/* 的同源 GET** 3) 「参数」页点「同步执行」(route)→ 「运行」页出现 argv 与退出码 0;runs 目录 mtime 不变 4) 「产物」页点某个 png 的预览 → 走 /cifkit/api/preview(同源) ``` 零写入的机器判据(不依赖浏览器):见 `verify-host.mjs` 里的 「零写入不变量:只读浏览前后 runs 树完全一致」——它把 fixture 的 runs 目录整棵树 (名字 + 类型 + size + mtimeMs)前后各拍一次快照并逐条比较。 ## 4. 失败时怎么定位 - `verify-host.mjs` / `verify-client.mjs` 都会在末尾打印「失败明细:期望 / 实际」; - 真 CLI 断言在找不到检出的环境里会 **SKIP 并打印原因**(进程仍 exit 0)—— 这不是通过,看汇总里的「跳过 : N」; - 想看被跳过的原因:汇总尾部会列「跳过项(明确原因,不算失败)」; - `DSH_CIFKIT_VERIFY_ROOT` / `CIFKIT_ROOT` 可指到任意 cifkit 检出后再跑 host harness。 ## 3.1 真检出端到端只读扫描(本次实测,一次性探针,已删除) 在真检出上直接调**真 handler + 真 spawn**(不是假 spawn),只发 GET: ```text GET /cifkit/api/health?root= 200 root= python=\.venv\Scripts\python.exe version=0.1.0 runsWritable=true commands=14 GET /cifkit/api/studies?root= 200 79 个 run 目录 GET /cifkit/api/spec?root= 200 formats=31 bundles=12 sources=6 commands=19 warnings=[] GET /cifkit/api/run?run=demo_sod_zif8 200 steps=10 artifacts=12 validation.ok=true atoms=2208 GET /cifkit/api/artifact?...structure.vasp 200 152719 字节 application/octet-stream GET /cifkit/api/preview?run=demo_sod_zif8 200 300594 字节 image/png GET /cifkit/api/artifact?...name=../../../pyproject.toml 400 code=path-outside(路径围栏生效) GET /cifkit/api/diagnostics?root= 200 candidates=7 cli.ok=true python.ok=true degraded=0 cifkit_view({root,run:'demo_sod_zif8'}) → 1803 字符紧凑 Markdown(steps + 校验结论),warnings=0 零写入:runs 目录整棵树 10019 条(名字|类型|size|mtimeMs)前后完全一致 → identical=true ``` 对照:同一个 run 的 manifest.json 有 2327 行;`cifkit_view` 只产出 1803 字符, 这正是「不把整份报告塞进上下文」的量化证据。 ## 5. 冻结接口 v1 ↔ 实现 ↔ 断言 逐条对应(供审计) 端点表在 [DESIGN.md §3](../DESIGN.md);下表把每一行落到 `index.js` 的**实现分支行号**与**harness 断言名**。 (行号以本次提交为准;`index.js` 共 3159 行。) | 端点(DESIGN §3) | 实现位置(index.js) | host harness 断言 | |---|---|---| | 前缀/方法/404/405/405 | `createHandler` L2287、L2350 起(方法白名单、前缀校验、route 切片) | `DELETE → 405`、`GET /unknown → 404`、`前缀外路径 → 404` | | `POST /api/exec/cancel` | L2394 | `cancel → 200`、`cancel 后 status=cancelled`、`子进程事后结算也不覆盖 cancelled`、`cancel 未知作业 → 404`、`cancel 缺 id → 400` | | `POST /api/exec` | L2431–L2597(root 解析 → 白名单 → consent → mode → run 围栏 → 输出改道 → argv → sync/job) | `无命令 → 403`、`非白名单命令 → 403`、`缺检出 POST /exec → 409`、`出网命令缺同意 → 400`、`allowExec=false → 403`、`sync formats → 200`、`run 内文件越界 → 400`、`需要 run 的命令缺 run → 400`、`run 不存在 → 404`、`formats 不支持 job → 400`、`job geom → 202` | | `GET /api/health` | L2599 | `GET /health 200`、`health.version 来自 cifkit/__init__.py`、`health.commands 与白名单同长`、`health.runsWritable=true`、`缺检出 GET /health → 409` | | `GET /api/diagnostics` | L2643(实现体 `diagnosticsPayload` L2159) | `GET /diagnostics 200`、`候选表恰好 7 行`、`python 探测 ok`、`cli.ok=true`、`degraded 为空` | | `GET /api/studies`(别名 `/runs`) | L2663(实现体 `listRuns` L829) | `GET /studies 200`、`studies 返回 2 条 run`、`无 manifest 的目录被如实标注` | | `GET /api/spec` | L2679(实现体 `probeSpec` L1698) | `GET /spec 200`、`spec.formats 来自 cifkit`、`spec.commands 来自 argparse 目录`、`spec.sources 来自 cifkit.api`、`spec.exec 下发白名单` | | `GET /api/jobs` / `/api/job?id=` | L2714 / L2718 | `GET /jobs 200`、`GET /job 未知 → 404`、`GET /jobs 含刚创建的作业` | | `GET /api/exec/events`(SSE / `once=1`) | L2727(流実现 `streamJobEvents`) | `SSE 结束态回放 200`、`SSE 回放含 meta 帧`、`SSE 回放含 done 帧并关流`、`SSE 未知作业 → 404`、`作业最终结算为 done` | | `GET /api/run` | L2741(实现体 `readRunSnapshot` L911) | `GET /run 200`、`run.steps 长度 3`、`GET /run 越界 → 400`、`GET /run 不存在 → 404` | | `GET /api/artifact` | L2758(围栏 `resolveArtifactPath` L704) | `GET /artifact 200`、`artifact 返回字节`、`GET /artifact 越界 → 400`、`扩展名不合格 → 422`、`不存在 → 404` | | `GET /api/preview` | L2777 | `GET /preview 200`、`preview content-type=image/png`、`没有图 → 404` | | exec 白名单(DESIGN §4.1,14 条) | `EXEC_COMMANDS` L1017(`buildExecArgv` L1466) | 14×「白名单含 …」+ 18×「… argv」+ 14×拒绝路径 | | 出网同意(DESIGN §4.2) | `commandNeedsConsent` L1494 | `出网同意判定:fetch/pipeline/sources --probe/sources/route` | | 路径围栏(DESIGN §6.3) | `resolveRunDir` L685、`resolveArtifactPath` L704 | 9 条围栏断言 + `文件参数越界 → 400 path-outside` | | 只读工具 `cifkit_view`(DESIGN §7) | `cifkitViewTool` L3066(`buildRunText` L2951 / `buildRunsText` L2921) | 13 条工具断言 + `真检出「cifkit_view 产出紧凑 Markdown»` | | 注册面(DESIGN §7.2) | `apply` L3263 | client harness 21 条(locale/3 slot/tab 类型/命令/style) | client 侧端点行为(真渲染 + 假 fetch): | 面板动作 | 打的端点 | client harness 断言 | |---|---|---| | 首屏 | `/health`、`/studies`、`/run`、`/spec`(全 GET) | `首屏 GET /health|/studies|/run|/spec`、`首屏全部是 GET(浏览零写入)` | | route 同步执行 | `POST /exec` | `route 按钮 POST /exec(command=route,mode=sync)`、`route 的 params.query 来自输入框` | | geom 作为作业 | `POST /exec` → `/exec/events?once=1` 轮询 | `geom 作业路径 POST /exec(mode=job)`、`作业开启了日志流(无 EventSource 时轮询 once=1)`、`运行页显示作业日志行` | | 取消 | `POST /exec/cancel` | (host harness 5 条;client 侧按钮渲染由「运行页显示作业 id」+ 取消按钮存在覆盖) | | 产物下载 / 预览 | `/artifact?…download=1` / `/preview` | `每个产物都有下载链接`、`预览图指向 /cifkit/api/preview` | | 设置页 | `/diagnostics` | `设置页 GET /diagnostics` + 9 条内容断言 |