四层代理工作流插件集Chillizu/mop-plugins

mop-plugins

CI
npm

MiOpIIk 的 DeepSeek Harness（DSH）插件集。

English：MiOpIIk 是面向 DeepSeek Harness 的一套单一职责插件套件——检查点/回退恢复、事件驱动的自动检查点（每个根会话轮次都会落下一行恢复记录）、历史会话召回、带零默认模型契约的受控执行器子代理、工作区作用域的模型授权门、接缝能力探测、token 遥测，以及一个四层（审查者/规划者/监督者/执行者）代理工作流预设。用一条命令即可全部安装：dsh plugin --profile web add dsh-miopiik。

架构总览

graph TD
U[用户] -->|任务 / 独立验收| R[审查层 Reviewer主会话 · miopiik preset]
R -->|2.1 任务下达| P[规划层 Plannercontinuable 子代理 · 强模型]
R -.->|接收 [EXEC] 报告| S[监督层 Supervisor沉默即通过 · 弱模型]
P -->|契约文件 + 并行派发| E1[执行层 Executor ×None-shot · mop_spawn_executor]
E1 -->|交付 + 验收对照| P
P -->|[EXEC] 周期汇报| R
S -.->|[CONCERN] 仅路径偏离时| R

四角色职责、通信协议与设计决策见 docs/PLAN.md。

快速安装：给 Agent 的一键提示词

把下面这段原样复制给另一个 Agent（或你自己的新会话），它会按本 README 的「安装」章节执行。提示词要求它先逐项取得你的确认再动手、装完做只读验证、失败原样上报，不含自创命令。手动安装见安装。

你是安装助手。目标：把公开仓库 Chillizu/mop-plugins（DeepSeek Harness 插件集）
安装到用户的 DeepSeek Harness。

0. 事实源：先读
https://raw.githubusercontent.com/Chillizu/mop-plugins/main/README.md ，
以其「安装」章节为准。不要自创命令、不要臆造路径；README 没写的操作不要做。

1. 动手前逐项询问并取得用户明确确认；未获确认前不安装、不写文件、不改 profile、
不重启服务：
- 是否授权安装本插件集（是/否）？
- 目标 Harness 是哪个（web / headless / 其它）？对应 profile 名是什么？
- 安装来源：npm 套件包（推荐，无需 clone）还是源码？源码安装时 clone/checkout
到哪个目录？该目录是否已存在？
- 是否允许修改 profile 配置（dsh plugin add 会写 profile）？
- 是否同时安装 miopiik preset（复制 examples/miopiik 为
${DSH_HOME}/.agent-presets/miopiik）？完整四层工作流需要它；只装插件层可跳过。
- 是否允许重启 Harness 服务以加载插件与 preset？

2. 确认完成后，按 README「安装」章节执行，优先方式一（套件包）：
dsh plugin --profile  add dsh-miopiik 装插件层 +
npx dsh-miopiik 装 preset（用户未同意 preset 则跳过此步）。
仅当用户明确选择源码安装时，才 clone 仓库并改用
dsh plugin --profile  add link:./packages/... 逐个装 9 个包、
再 cp -r examples/miopiik "${DSH_HOME}/.agent-presets/miopiik"。
不跳过、不自造参数、不改动包内文件。

3. 安装后验证（只读，不额外改动）：
- 核对 9 个包已进入 profile（dsh plugin list 或 dsh.profile.bundles）；
- 重启后确认实际加载：Web UI 设置→插件清单出现 dsh-miopiik-；装了 preset 则用
standingKeyFor('miopiik') 验证挂载；
- 可选 smoke：按 examples/miopiik/README.md 的「最小 smoke task」跑一遍
（probe capabilities → checkpoint → list）；
- 可选：在仓库根跑 npm test 验证本仓库测试；若缺 Node 依赖，先说明，
不要擅自 npm install；
- 任一环节失败：原样报告错误与已执行步骤，不要擅自多方案重试或改动其它插件。

4. 全程不修改模型选择/路由，不碰 preset 之外的配置、设计文档、契约、实验产物；
不 commit、不 push。

English Quickstart
MiOpIIk 是 DeepSeek Harness 的一套单一职责插件套件：检查点/回退恢复 + 事件驱动的自动检查点（dsh-miopiik-tool-recovery、dsh-miopiik-checkpoint）、历史会话召回（dsh-miopiik-recall）、受控的一次性执行器子代理（带零默认模型契约，mop_spawn_executor）、工作区级模型授权门、两级证据级别的接缝探测、token 遥测、魔法关键词，以及四层 reviewer/planner/supervisor/executor 工作流预设。

1) plugins — all seven with one command
dsh plugin --profile web add dsh-miopiik

2) preset — the four-layer workflow (copies to ${DSH_HOME}/.agent-presets/miopiik)
npx dsh-miopiik

3) restart DSH, then validate the mount
standingKeyFor('miopiik')

冒烟任务（无需凭据）：在 miopiik 预设上启动一个会话，请求
mop_probe_capabilities → 读取 .dsh/memory/capabilities.md，然后使用标签调用 mop_checkpoint，
再调用 mop_checkpoint_list。

范围

本仓库包含重建 MiOpIIk 插件层与 preset 的全部材料：

- 插件层：9 个 dsh-miopiik- 插件包（packages/）+ 测试 + 设计文档。
- MiOpIIk agent preset：persona 与 Cordis 组合行（planner / executor / supervisor 工具编排）。脱敏可重建模板在 examples/miopiik/（复制为 ${DSH_HOME}/.agent-presets/miopiik/ 即可）；定稿 persona 的 draft 源在 docs/design/presets/drafts/（executor.prompt.md 逐字同步进 dsh-miopiik-executor 的 EXECUTOR_PERSONA，其余 persona 由 persona-sync 测试与 examples/miopiik 副本保持一致）。

不在库的只有作者私有运行态：API 凭据、模型 allowlist 内容（工作区级 /.dsh/memory/model-allowlist.md，0.1.8 起不再使用全局文件，详见 docs/design/model-auth.md）、用户偏好与调研笔记（docs/profile/、docs/research/）。这是有意的脱敏边界——新部署需自行配置凭据，并用 mop_model_authorize 在自己的工作区建立 allowlist。

DSH 兼容矩阵见 docs/design/dsh-compat.md。

插件清单（9 插件 + 1 套件包）

| 包                                                                   | 类型     | 工具 / 行为                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dsh-miopiik                               | 套件 | 一条命令装齐 9 插件（聚合 bundle patch）+ npx dsh-miopiik 初始化 miopiik preset                                                                                                                                                                                               |
| dsh-miopiik-tool-recovery   | 恢复     | mop_checkpoint（记录目标会话 turn 边界 + git note）、mop_rewind（fork 到 checkpoint，含冷会话）、mop_checkpoint_list、mop_checkpoint_prune（按 keep 裁剪，dry-run 默认，keep=0 高风险）、mop_rule_inject / mop_rule_show / mop_rule_clear（会话级硬规则注入） |
| dsh-miopiik-executor             | 执行     | mop_spawn_executor（一次性执行层子代理，零默认零兜底：model+provider 必须显式成对给出，省略/只给一边即抛错，无 Config 默认、不继承调用者；逐次指定 timeoutMs 硬超时）                                                                                                   |
| dsh-miopiik-magic-keywords | hook     | 正文检测 ultrathink / workflowz（排除 code fence / inline code）→ form: notice 上下文消息注入（Config: notices dict）                                                                                                                                                   |
| dsh-miopiik-model-auth         | 授权闸   | mop_model_authorize / mop_model_revoke / mop_model_list + agent/request 硬闸；allowlist 工作区级（/.dsh/memory/model-allowlist.md，0.1.8+，跨工作区隔离；Config: allowlistPath 可显式覆盖）                                                          |
| dsh-miopiik-capabilities     | 探测     | mop_probe_capabilities（探测 DSH seam 可用性，清单含「在场 / 实调」双证据与环境行 → .dsh/memory/capabilities.md）                                                                                                                                                           |
| dsh-miopiik-learn                   | 学习     | mop_learn（把可复用流程铸成 .dsh/skills//SKILL.md，被 skill-filesystem 发现）、mop_learn_list（只读枚举已铸 skill 名称）                                                                                                                                            |
| dsh-miopiik-run-stats           | 遥测     | mop_run_stats（D18 可编程 token 出口：读 session 累计四桶 uncached/cacheRead/cacheWrite/output，不计算价格/成本）                                                                                                                                                             |
| dsh-miopiik-recall                 | 记忆     | mop_recall（会话/工作目录级历史消息检索：流式 zstd 解压扫描 ~/.dsh/sessions 下本工作目录全部历史会话日志，命中行带时间/会话/角色；scope=workspace 默认 / session 只扫当前会话；大日志无上限）                                                                           |
| dsh-miopiik-checkpoint         | 记忆     | 里程碑自动检查点（0.1.13）：根会话每轮关闭由 agent/turn-stopping 事件自动追加 auto-turn 行到 .dsh/memory/checkpoints.md，agent/error 记 auto-error；同 turn 去重，子代理轮次不写；mop_checkpoint 手动显式命名里程碑仍可用且互补                                 |

工具安全行为与限制
- mop_spawn_executor Config.strict（默认 false，行为不变）：true 时执行层工具面收为 [read, glob, grep, edit, todo_write]——去掉 bash 与 write，面向不可信任务/来宾场景；edit 保留以符合 persona「只 append 不覆盖」硬规则。作用域：只收紧 executor 子代理自身的工具面，不改变主会话与全局工具权限。
- mop_spawn_executor timeoutMs：可选（毫秒），缺省无超时、行为不变。超时经 AbortController 中止子代理并返回 [aborted] executor timed out after {N}ms（末尾仍带 [executor-session: {id}]）。限制：仅 per-call 参数，无 Config 级默认；不调用 run.dispose()，进程内资源清理仍归 provider/tool 层。
- mop_model_revoke：从工作区 allowlist（/.dsh/memory/model-allowlist.md）移除 provider/model，与 mop_model_authorize 对称；拒绝撤销当前默认模型（隐式授权、不在 allowlist），对不存在项幂等返回。限制：全量重写经进程内 withAuthLock 串行化，跨进程并发 revoke+authorize 存在丢行窗口（文档化接受，属低频运维操作）。
- mop_learn_list：只读枚举 .dsh/skills/ 下实际含 SKILL.md 的 skill 名称（排序），空/目录不存在返回 (no skills)。限制：不读内容、不读 frontmatter description、不写任何文件。
- mop_checkpoint_prune：keep 必填（非负整数）；confirm 必须为布尔，仅严格 true 才写，缺省/false 一律 dry-run（返回将删数量与 label 清单）。只删 parseCheckpointLine 能识别的现行行，注释/空行/旧格式行/普通文本原位保留。keep=0 清空全部现行行，高风险、仍需 confirm:true。限制：旧格式行永不裁剪；不生成备份文件。
- mop_recall：只读检索（zstd 子进程管道流式解压，命中即收、达上限即 kill），不写任何文件、不修改会话。限制：扫描的是 ~/.dsh/sessions 下已落盘的日志快照（内存态实时内容不在其中）；大日志无大小上限，但极端大量命中受 maxLines 截断。
- 自动检查点（dsh-miopiik-checkpoint）：只写 /.dsh/memory/checkpoints.md 一个文件（轮关闭时 append 一行），不读会话内容、不触碰子代理；仅根会话（delegationDepth=0）生效，子代理轮次不写。落盘失败仅 warn、绝不阻断轮关闭。

安装

三级路径，按需选择其一；同一 profile 内勿混用（尤其勿把套件包与逐包安装叠加，重复插入同名行属于未定义组合）。

方式一（推荐）：套件包一条命令

插件层：一条命令装入全部 9 个插件（自动并入 profile bundles）
dsh plugin --profile web add dsh-miopiik

preset 层（完整四层工作流需要）：初始化 miopiik preset 到 ${DSH_HOME}/.agent-presets/miopiik
npx dsh-miopiik               # 目标已存在则拒绝覆盖；--force 覆盖（别名 dsh-miopiik-init 同义）

dsh plugin add 会把声明了 dsh.bundle.patch 的包并入 profile 的 bundles 列表并自动解析依赖；重启后 standingKeyFor 挂载验证。

方式二：逐包安装（按需取用）

每包已声明 dsh.bundle.patch，npm 名即包名：

dsh plugin --profile web add \
dsh-miopiik-tool-recovery \
dsh-miopiik-executor \
dsh-miopiik-magic-keywords \
dsh-miopiik-model-auth \
dsh-miopiik-capabilities \
dsh-miopiik-learn \
dsh-miopiik-run-stats \
dsh-miopiik-recall \
dsh-miopiik-checkpoint

需要完整四层工作流时再装 preset（脱敏模板在本仓库 examples/miopiik/）：

cp -r examples/miopiik "${DSH_HOME}/.agent-presets/miopiik"

重启后 standingKeyFor('miopiik') 验证挂载；smoke 步骤见 examples/miopiik/README.md。

方式三：源码 clone/link（开发者）

git clone https://github.com/Chillizu/mop-plugins && cd mop-plugins
dsh plugin --profile web add \
link:./packages/dsh-miopiik-tool-recovery \
link:./packages/dsh-miopiik-executor \
link:./packages/dsh-miopiik-magic-keywords \
link:./packages/dsh-miopiik-model-auth \
link:./packages/dsh-miopiik-capabilities \
link:./packages/dsh-miopiik-learn \
link:./packages/dsh-miopiik-run-stats \
link:./packages/dsh-miopiik-recall \
link:./packages/dsh-miopiik-checkpoint
免发布/pnpm 的等价做法：把包目录放到任意位置（如 ~/.dsh/profiles/dsh-miopiik-），在 ~/.dsh/profiles/node_modules/ 下建同名 symlink（ln -sfn ~/.dsh/profiles/dsh-miopiik-executor ~/.dsh/profiles/node_modules/dsh-miopiik-executor），preset 行写裸包名 dsh-miopiik-——这样 Web UI 插件列表显示的是包名而非文件路径（@deepseek-ai/dsh- 依赖同样靠 ~/.dsh/profiles/node_modules 的 fallback 解析）。bundle 方式可被 dsh plugin list/remove 管理。

从旧名迁移（2026-08 前安装的本地环境）

1. 用新包名重装（方式一/二/三任一），再 dsh plugin remove 掉旧 @chillizu/mop- 行；
2. 删除旧 symlink 与空 scope 目录：rm ~/.dsh/profiles/node_modules/@chillizu/mop- && rmdir ~/.dsh/profiles/node_modules/@chillizu 2>/dev/null；
3. preset 行名同步为新包名（重新执行 cp -r examples/miopiik ... 最省事）；
4. 重启后 standingKeyFor('miopiik') 复验。工具名 mop_ 未变，会话记忆/checkpoints 文件无需迁移。

版本演进与验收（0.1.6 → 0.1.13）

完整逐版记录见 CHANGELOG.md；缺陷闭环摘要：

| 版本   | 内容                                                                                                                                |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| 0.1.6  | 六缺陷初版验收（子代理模型不可预测 / memory 空转 / 弱模型不守规则），确立回归基线                                                   |
| 0.1.7  | 零默认零兜底模型契约：mop_spawn_executor 必须显式 model+provider，无 Config 默认、无继承、无决策文件兜底                  |
| 0.1.8  | 授权收紧为工作区级：allowlist 迁至 /.dsh/memory/model-allowlist.md，撤回全部全局授权；recall 首发（D 缺陷发现）    |
| 0.1.9  | B3（授权对闸门即时生效，共享缓存+mtime 失效）、C2（mop_dispatch 迁至 preset 装配）、D（preset 补 recall 行）                        |
| 0.1.10 | B1 二轮修复（start 阶段错误回传）+ recall scope=session 前缀归一化（R4c）                                                           |
| 0.1.11 | B1 三轮真因：失败是 stopReason='error' 的成功 resolve 而非 reject → 正常返回路径显式判定                                      |
| 0.1.12 | recall 流式解压，根治 20M+ 大会话 maxBuffer 超限 skip；四缺陷全数验收 PASS                                                      |
| 0.1.13 | 里程碑自动检查点（dsh-miopiik-checkpoint）：记忆落盘由 agent/turn-stopping 事件驱动，不再依赖 persona 自觉；memory 缺口闭环 |

每版验收证据归档于工作区 acceptance-.md（0.1.8 / 0.1.9 / 0.1.12-FINAL / 0.1.13）。

设计（计划树）

完整设计/决策见 docs/PLAN.md：三层 + 监督层工作流、固定通信协议、分级记忆、恢复工具包、魔法关键词、模型授权闸，逐条带验收证据。

命名约定

- 包 / 插件 name / 组合行 id：dsh-miopiik-（npm 无 scope，与 DSH 官方包的 dsh- 风格对齐；2026-08 起由旧名 @chillizu/mop- 全量改名，一一对应）
- 工具：mop_，下划线小写动词（如 mop_spawn_executor、mop_run_stats），保持不变——与 DSH 内置工具（session_search、send_message 等）的 snake_case 风格一致；persona、实验 golden 装置不受改名影响
- preset id：小写 miopiik

模型路由切换（miopiik preset）

examples/miopiik 的 provider/model 用 YAML 锚点收敛为唯一定义点（真实 Loader 组合测试覆盖）：

| 层                         | 模型                                                                                                                                          | 定义位置                                                            |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 审查层（主会话）           | 用户自己的模型路由                                                                                                                            | preset 不干预                                                       |
| 常规子代理 / fork / 监督层 | &flash-model（示例 opencode-go/mimo-v2.5）                                                                                                  | tool-subagent 行 agentOptions（锚点定义处，改一处全跟随）         |
| 规划层                     | &planner-model（示例 hy3，与 dispatch 同源）                                                                                                | tool-subagent-planner / tool-subagent-dispatch 行（唯一手写处） |
| 执行层                     | 零默认零兜底：mop_spawn_executor 每次调用必须显式 model+provider 成对给出，省略或只给一边即抛错（无 Config 默认、不继承调用者） | per-call 参数；未授权模型由模型闸（dsh-miopiik-model-auth）拒发   |

换 provider 时改锚点定义处的 &dsh-provider 与上述 model 即可；不引入环境变量插值等未证实特性。规划层强模型须先在工作区 mop_model_authorize 授权（0.1.8 起授权为工作区级）。