前言¶
在 DSH 或同类智能体宿主里，单个 skill 往往能做好一件事：验公式、抽 PDF、画图。任务一复杂，难点就变成选哪个 skill、按什么顺序跑、输出落在哪——零散、无状态的调用容易污染上下文、搞混文件版本，也让结果难以审计。
Chelate Shell 是面向研究与工程场景的工作流编排插件：仓库内自带 20 个已实现算法的 skill（不是提示词模板），由 core/router.py 按固定阶段顺序调度，并为每次调用写入类型化的门禁结果。下面介绍它是什么、核心机制，以及在 DSH 生态里如何安装与使用。
这是什么¶
- 定位：确定性编排器（deterministic orchestrator），把本地 agent skills 收成有阶段、有门禁、有工作区约定的流水线。
- 维护者：JiamingShi-JsPhys（GitHub 组织/账号同名）。
- 版本：README 标明 1.3.1，内含 20 个 skills。
- 分类：社区目录归类为工作流；GitHub 约 10 stars（以目录页/仓库页当时显示为准）。
插件解决的核心问题：在复杂任务里统一「谁先谁后、失败怎么处理、中间产物与最终结果如何区分」，并对科研相关输入做分发前安全筛查。
核心功能¶
20 个随仓 skills¶
安装后无需自行凑 skill 列表。README 列举的能力包括（均 wired 进 pipeline 并有测试覆盖）：
- formula-validator：SymPy 五层检查 + pint 单位交叉校验。
- quantitative-validator：RDKit 化学方程式配平。
- longitudinal-analysis：经 R 调用 lme4、lavaan。
- video-tracker：OpenCV CSRT 跟踪与轨迹 FFT。
- ml-auditor：scikit-learn 检查数据泄漏与标签错误。
- sci-visualizer：matplotlib/seaborn 出图。
- fulltext-extractor：PDF 页范围抽取。
- latex-exporter：仅用标准库把 Markdown 报告组装为可编译
.tex。
其余 skill 按 manifest 注册，由编排器统一发现与调用。
四层路由与阶段顺序¶
core/router.py 作为微内核：读取 20 份 manifest.json，按规范阶段顺序建计划；在真正分发前用 core/security_shield.py 对文本输入做 prompt injection 筛查；再经各 skill 的 adapter（run.py）执行，必要时经 core/sandbox.py（例如 120s 断路）。
自动流水线的主干是 ingest → gates → processors；workspace（如 task-organizer）在任务起点作为书挡，可在流水线前或通过 --selected 进入。--mode a 不会调度 workspace 段（详见 README 流程图说明）。
各阶段 skill 示例（与 README 流程图一致）：
| 阶段 | 部分 skill |
|---|---|
| workspace | task-organizer, multi-dim-manager, document-evolution-tracker |
| ingest | capstone-labmate, video-tracker, fulltext-extractor, literature-retriever, bibtex-normalizer |
| gates | formula-validator, conflict-detector, reference-auditor, data-profiler, quantitative-validator, ml-auditor, longitudinal-analysis |
| processors | ai-trace-remover, latex-exporter |
另有 category meta-skills（如 security-guard、sci-visualizer、3d-modeler）可被路由，但不在规范顺序的主干之内。
门禁（GateResult）与失败语义¶
每次 skill 调用在 process/gates/ 写入 GateResult，取值为：
- PASS：通过。
- UNVERIFIED：无法给出断言（例如可选依赖缺失、调用方尚未提供的输入）——不视为失败，流水线继续。
- FAIL：唯一会终止流水线的状态；一旦出现，管道当场停止，
process/锁定在中间状态，便于审计且不会误当作最终结果。
全部 gate 无 FAIL 时，process/ 提升为 results/promoted_TIMESTAMP/，并生成 results/pipeline_report_TIMESTAMP.json 与 _broadcast/pipeline_index_TIMESTAMP.json，便于后续会话先读摘要再打开原件。
同一输入在同一模式下应得到相同计划（deterministic stage order）；编排器还维护四维工作区约定与 _broadcast/ 索引。
与 DSH 的包形态¶
仓库 package.json 中声明了 DSH 捆绑配置：dsh.bundle.patch 指向 ./cordis.patch.yml，主入口含 cli.py、core/、skills/ 等。在支持插件市场的宿主上，以单一插件形式安装可保持微内核自动路由完整（README Installation 第一节强调）。
安装与启用¶
DSH 理念是「一切皆插件」；SkillHub 目录页 是社区索引，与 DeepSeek / 幻方无官方从属关系，安装前请自行查看源码与许可证。
官方 README 给出三种方式；与 DSH 相关要点如下。
方式一：在插件市场用仓库 Git URL 注册并安装
在宿主自带的插件市场中注册本仓库地址（重复注册无害，第二次会提示已存在）：
https://github.com/JiamingShi-JsPhys/chelate-shell
随后在市场中安装该仓库列出的插件条目。
方式二：命令行安装
README 写明：Claude Code、Codex、dsh 与 CodeBuddy 可使用一行插件命令；具体命令、参数与可选依赖集中在仓库文档 docs/INSTALL_COMMANDS.md。请以该页面对 DSH 的原文为准，勿凭仓库名自行拼接命令。
方式三：按 README「Method 3」让 AI 协助安装（需访问 GitHub 仓库并按仓库内 install.py 等说明操作；本文不展开 clone 步骤）。
安装后插件以当前 dsh 进程权限运行，执行前请审阅 core/、skills/ 及第三方依赖行为。
典型用法¶
一次运行的入口在 README 流程图中概括为：用户意图与输入文件 → cli.py pipeline（--mode a / b / c）→ core/registry.py 扫描 manifest → build_plan（规范顺序，--inputs 可收窄）→ 注入扫描 → 各阶段 run_skill() → 写 gate → 晋级或终止。
可操作步骤（概念层，细节以仓库 cli.py 与文档为准）：
- 在工作区准备好输入文件与用户意图描述。
- 调用 pipeline CLI，选择模式
a、b或c（不同模式对 workspace 书挡等的调度有差异）。 - 查看
process/gates/下各次调用的 GateResult；若有 FAIL，在锁定的process/中排查，勿将中间目录当最终结果。 - 成功结束后使用
results/下带时间戳的目录与pipeline_report_*.json，必要时先读_broadcast/pipeline_index_*.json。
缺失依赖时对应 skill 降为 UNVERIFIED，其余 skill 仍会继续执行，需在报告中区分「未验证」与「失败」。
适用场景与注意¶
适合谁
- 科研工作流需要固定阶段（ ingest → 校验 gate → 导出 processor）的智能体开发者。
- 希望同一套输入可复现相同编排计划、并对每次 skill 调用留痕（PASS/UNVERIFIED/FAIL）的团队。
- 需要随仓使用公式/化学/纵向统计/视频轨迹/PDF/LaTeX 等能力、又不想自行维护 20 个 manifest 的用户。
务必注意
- 作者免责声明：本仓库为辅助自动化工具，非同行评审学术项目；不会在实验室代做实验；生成物仅为数据分析草稿，学术责任在用户与机构。
- 部分工具脚本可能在 AI 辅助下生成并经作者审阅修改；第三方代码问题作者承诺对有效申诉及时响应。
- 插件能力依赖 Python 生态（SymPy、pint、RDKit、R、OpenCV 等）；缺依赖时对应环节为 UNVERIFIED，不等于整条流水线失败。
- 安全：分发前会做注入筛查；发现 marker 时在 dispatch 前 FAIL（injection-scan）。
结尾¶
Chelate Shell 把「会做什么」的 20 个 skills 与「按什么规则做」的 core/router.py 放在同一仓库：规范四区工作流、确定性阶段顺序、类型化门禁与首次 FAIL 即停，适合把 DSH 上的本地技能收成可审计的研究流水线。
