dsh-decision-tools

向本地模型要概率，而不是要文字。 两个 DSH 工具，把有界判定变成便宜、可重复的调用：

| 工具 | 回答什么 | 典型用法 | |---|---|---| | decision | 一份判据判 1–64 项，或一次问最多 64 个不同问题 | 筛列表、分类工单、路由请求、排序候选、「这段日志是不是失败？」 | | monitor | 反复采样同一个源，直到判据成立 | 等构建结束、等某行出现、等作业失败 |

判定跑在你自己的 Ollama（/v1/systemone）上：不经过云服务，材料也不必进入对话上下文。

为什么值得用

• 天然省钱：判据只发一次，一次调用判最多 64 项；逐项循环才是昂贵的反模式。
• 材料不进上下文：传工作区文件、glob 或另一个工具的原始输出，你只读回答案。
• 输出诚实：每个答案是概率 + confidence；部分完成写进 coverage，插件做了什么写在 notes。

环境要求

• 已启用本插件的 DSH 桌面版（见「安装」）。
• 本地 Ollama 提供 decision 模型 —— 默认 tev1:0.8b，可用 model 单次覆盖。
• 无需 API Key；判定本身不出网。
• 图片 material 需要视觉模型（clef / clef-flash）；tev1 / nimble 会回 does not support vision。

安装

npm 发布后：

dsh plugin --profile web add dsh-decision-tools

开发期从工作区链接：

dsh plugin --profile web add link:/absolute/path/to/dsh-decision-tools

然后确认工具可见：

cordis_inspect_query(platform="host", provider="Tool", method="listTools")

随包技能 decision-usage 与工具一起注册，写全了每个参数，按需加载。

换用本机其它模型

默认值（baseUrl = http://localhost:11434、defaultModel = tev1:0.8b、四条 ladder）都只是快照。任何能应答 System One 端点的 Ollama 模型都能用：

• 单次指定 —— model: "<名称>"（同时关闭容量选择与升档）；
• 改会话默认 —— defaultModel；
• 换主机/端口 —— baseUrl；
• 调升档阶梯 —— ladder: [{ model, numCtx }]（见 Configuration）。

想知道本机实际装了哪些、并拿到可直接粘贴的 ladder：

node scripts/list-models.mjs          # 名称 · 上下文 · 参数量 · 大小
node scripts/list-models.mjs --json   # { models, ladder }

numCtx 取自 /api/show 的声明上下文长度（上限），运行时 num_ctx 可能更小。

快速开始

// 1) 筛列表：一份判据判 N 项
{ "material": "<列表或其上下文>", "rubric": "This is a bug report?",
  "items": ["app crashes on save", "please add dark mode"], "type": "noul" }

// 2) 对同一个文件问不同的问题
{ "material": { "file": { "path": "build.log", "startLine": 1, "endLine": 200 } },
  "questions": [
    { "name": "ok", "type": "noul", "instructions": "Did the build succeed?" },
    { "name": "why", "type": "choice", "instructions": "What failed?",
      "criteria": { "compile": "compile error", "test": "a test failed", "env": "missing dependency" } }
  ] }

// 3) 判另一个工具的输出，而不把它读进上下文
{ "material": { "tool": { "name": "git_bash", "arguments": { "command": "npm test" } } },
  "rubric": "Did the test suite pass?", "items": ["the test suite output"], "type": "noul" }

// 4) 判图片（需要视觉模型）
{ "material": { "images": ["screenshots/checkout-error.png"] },
  "model": "clef-flash:latest",
  "questions": [ { "name": "has_error", "type": "noul", "instructions": "Does this screenshot show an error state?" } ] }

// 5) 等后台作业结束，并让插件通知你
{ "source": { "kind": "job", "id": "<jobId>" },
  "rubric": "Did the job finish successfully?", "background": true, "notify": "inbox" }

decision：一次调用，一种模式

给 material，再加恰好一种模式：

| 模式 | 形状 | 含义 | |---|---|---| | 批量 | rubric + items + type（+ criteria） | 一份共享判据，逐项独立判定 | | 混合 | questions | 对同一份材料问最多 64 个不同问题 |

| 参数 | 必填 | 说明 | |---|---|---| | material | 是 | 内联字符串 / {file} / {glob} / {tool} / {images} / {text, images} | | rubric | 批量 | 唯一共享判据；线格式会替模型重复它 | | items | 批量 | 1–64 个自包含项；直接传字符串也合法 | | questions | 混合 | 1–64 个 {name, type, instructions, criteria?} | | type | 批量 | choice / noul / score（混合模式逐题给） | | criteria | choice/score | 标签集只写一次：批量走顶层，混合走每题 | | depth | 否 | quick（不升档不分批）、normal（默认）、deep（可切块）；图片请求忽略 | | model | 否 | 固定模型；关闭容量选择与升档 |

材料形态：内联文本 · { file: { path, startLine?, endLine? } } · { glob: { pattern, limit? } } · { images: ["a.png"] }（或 { text, images }）· { tool: { name, arguments? } }。工具输出不进上下文，全文落盘、路径回传为 material.spillPath；text/file/glob 可与 images 组合，tool 不能与其它形态组合，插件自身工具会被拒。

图片：工作区内 PNG/JPEG/WebP 路径（1–8 张；单张 ≤16 MiB、总量 ≤24 MiB base64 前、请求体 ≤32 MiB）。插件读盘、按 magic 校验并 base64 编码，图片字节不进你的上下文。图片请求需要视觉模型，且只发一次——depth 被忽略（不升档/不分批/不扫描）。输出里会带 material.images（count/bytes/encodedBytes/formats）。

读结果：results[]（id/type/value/probabilities?/confidence?）· coverage（requested/answered/batches/truncated/truncatedBy/failed/aborted）· cost（model/inputTokens/bodyBytes/wallMs/escalated/attempts）· notes（首行是选档结论）。

noul 返回布尔 value；P(true) 在 probabilities.true 里（0.475 = 47.5% 是）。score 落在 0..N-1 尺度；choice 返回所选标签。confidence 是分布集中度，不是正确率 —— 当 notes 点名低置信项时，改读 probabilities 而不是标签。

monitor：等一个事件

按间隔采样同一个源、每次问同一个判据、累计命中。once 达到 countThreshold（或 deadline）返回；continuous 跑到 deadline/cancel，返回累积 count。它绝不 kill、重试或取消任何东西。

| 采样源 | 允许的键 | 读什么 | |---|---|---| | job | id?、select?（newest/oldest）、jobKind? | 后台作业输出（缺省看本会话最新） | | file | path、startLine?、endLine? | 工作区相对文件 | | glob | pattern、limit? | 命中文件拼接 | | command | argv | 复用插件上游管道重跑宿主命令 | | events | types、limit? | 作业事件环形缓冲（无缓冲时退到当前作业列表） |

参数：description（必填；作业 label = source.kind + description）· source（必填）· rubric（必填）· type（仅 noul）· criteria · hitThreshold（0.5）· tailBytes（4096，上限 65536）· mode（once|continuous）· countMode（cumulative|consecutive，默认 cumulative）· notifyEvery（continuous，默认 1）· intervalMs（5000）· timeoutMs（120000）· countThreshold（1；仅 once）· background · notify · coalesce · maxNotificationsPerMinute（6）。

• 空样本：file/glob 为空时立即返回（samples: 1、emptySource: true，不调模型）；job/events/command 的空样本按 P=0 记一次未命中并继续等待事件。
• 后台：background: true 返回 jobId；job_output 流式读过程行（config/hit/trigger/summary，读一次即消耗）。notify: "inbox" 只在 trigger 发一行通知（once 达标 / continuous 每 notifyEvery 次命中），且必须是后台调用。作业状态：abort ⇒ killed；全部探测 errors（无有效 verdict）⇒ failed；timeout/有有效 verdict ⇒ completed。
• detail：finished [...] 对 once 为 hit/P|EP/dur，continuous 为 trigger_num/EP/dur；EP：once = Σ(hit P)/N（N=countThreshold，不足补 0；0 hit ⇒ 0）；continuous = 各 trigger P 均值（trigger P = 窗口 hit P / notifyEvery；0 trigger ⇒ 0）。once hit=false 取 1-EP；单位 ms。布尔型 verdict 无 P 时按 0.00（detail/通知/流都不出现 -）；description 折叠为单行；永久源错误（描述符/越界/显式作业 id 不存在/文件超限）当场失败，瞬态读取错误继续重试；abort 会打断 in-flight decide/sleep。作业 label = source.kind + description。
• command 的 argv：argv[0] 选解释器（pwsh、git_bash/bash/sh/zsh）；解释器标志会被剥掉；带空格的参数要自己加引号。
• events.types 按固定词表校验（job.registered、job.stopping、job.output、job.progress、job.settled、job.completed、job.failed、job.killed、job.removed、job.running、job.unknown），拼错报 source_invalid。

Configuration

插件由四行组成：核心行、decision 行、monitor 行与 skill 行。每行在 Plugins 页都有自己的开关；核心/decision/monitor 三行还各有自己的 Configure 页。GUI 可改字段声明为 .volatile()，保存后下一次调用生效，无需重载行。toolName / monitorToolName / ladder / spillDirCap 是注册期或高级 YAML 项：在 cordis.patch.yml 里改，然后重载对应行。

核心行 — decision-tools-plugin（共享模型与运行时）

| Key | Default | Meaning | |---|---|---| | baseUrl | http://localhost:11434 | Ollama 地址；路径前缀会被保留；GUI 可改。 | | defaultModel | tev1:0.8b | 工具行没有 modelOverride 时使用的模型；GUI 可改。 | | timeoutMs | 120000 | 单次请求预算，含冷加载；GUI 可改。 | | keepAlive | unset | 透传为 keep_alive；未设用服务端默认；GUI 可改。 | | apiKey | 未设 | 可选；作为 Bearer token 发给远程 / System One 兼容接口；GUI 可改。 | | modelsPath | /api/tags | 模型发现路径；OpenAI 兼容接口可用 /v1/models；GUI 可改。 | | systemOnePath | v1/systemone | 判定接口路径（相对 baseUrl）；GUI 可改。 | | modelOrder | 未设 | 逗号分隔的模型优先级；model@numCtx 可指定上下文；未知模型按 8192；GUI 可改。 | | escalationEnabled | true | 上下文溢出时允许自动升档；GUI 可改。 | | ladder | unset (DEFAULT_LADDER) | 有序的 {model,numCtx}[]；仅 YAML；改后重载核心行。 | | toolName | decision | decision 工具的模型可见名；改后重载 decision 行。 | | monitorToolName | monitor | monitor 工具的模型可见名；改后重载 monitor 行与 decision 行（两行都快照该名）。 | | spillDirCap | unset (16 MiB) | 插件转储目录的字节上限；仅 YAML。 |

decision 行 — decision-tools-decision

| Key | Default | Meaning | |---|---|---| | modelOverride | unset (core default) | 留空使用核心行的 defaultModel；GUI 可改。 | | defaultDepth | normal | quick / normal / deep；调用省略 depth 时使用；GUI 可改。 | | bodyWarning | true | false 时不再返回体积/文本形状提示；GUI 可改。 | | softBodyBytes | unset (4096) | 超过该字节数会在 notes[] 带体积提示；0 表示每次都告警；GUI 可改。 | | minConfidence | unset (0.25) | confidence 低于该值（或缺失）的 choice/score 项会被点名；0 关闭；GUI 可改。 | | maxChoiceOptions | unset (255) | choice 选项数上限；GUI 可改。 | | escalationMaxAttempts | 3 | 额外升档次数（不含首次；deep +2；留空 = 3）；GUI 可改。 | | scanFirstChunkBytes | unset (4096) | 首块字节预算；GUI 可改。 | | scanMaxChunks | unset (32) | 单次扫描的块数上限；GUI 可改。 | | scanMaxTotalBytes | unset (4 MiB) | 单次扫描的累计字节上限；GUI 可改。 | | scanDeadlineMs | unset (180000) | 单次扫描的墙钟预算；GUI 可改。 | | scanAggregate | none | none / any；any 会给跨块答案加一个暂定的最大概率；GUI 可改。 |

monitor 行 — decision-tools-monitor

| Key | Default | Meaning | |---|---|---| | modelOverride | unset (core default) | 留空使用核心行的 defaultModel；GUI 可改。 | | minProbeIntervalMs | unset (1000) | monitor 探测间隔下限；GUI 可改。 | | notifyCoalesceWindowMs | unset (5000) | 同类通知合并窗口；0 表示不合并；GUI 可改。 | | maxNotificationsPerMinute | unset (6) | 每分钟通知上限；GUI 可改。 |

覆盖既有行要用裸 id、不带 insert，字段写在 config 键下。config 是整块替换、不做深合并，所以覆盖时必须重述该行用到的全部字段。

- id: decision-tools-plugin
  config:
    baseUrl: 'http://localhost:11434'
    defaultModel: 'tev1:0.8b'
    timeoutMs: 180000
    keepAlive: '30m'
- id: decision-tools-decision
  config:
    modelOverride: 'tev1:0.8b'
    defaultDepth: normal
- id: decision-tools-monitor
  config:
    modelOverride: 'nimble:latest'

三条 Config schema 在 lib/configs.js。

常见问题

| 现象 | 可能原因 | 处理 | |---|---|---| | context_overflow | 材料 + 问题超出模型窗口 | 用 depth: "deep" 切块、减小材料或减少问题数 | | 工具列表里没有 | 插件未在 profile 启用 | 链接进 profile 后重载 | | DSH 升级后 ERR_MODULE_NOT_FOUND | 工作区 node_modules 仍指向旧安装 | 在 DSH 内跑 scripts/rebuild-node-modules.mjs，再复跑测试 | | monitor 返回 hit:false 且 errors:0 | 源为空，或 types 没匹配到 | 看 emptySource；notes 会写原因 | | monitor 返回 errors: N > 0 | 读取或判定失败 | 看错误正文，渲染结果里也有 failed probes | | source.kind=events 报错 | 该组合下事件源不可用 | 能回落时会退到本会话当前作业列表 | | invalid_request / mode_invalid | 参数不合法 | 报错列出合法值；mode_invalid = 模式/数量/形态，invalid_request = 字段 |

边界与安全

• 这些是概率，不是证据：不得当作正确性证据，也不得单独作为放行/拒绝的依据（那需要产物级证据）。
• 工具不得决定路由，也不得作为任何 fail-open / fail-closed 策略的依据 —— 那属于确定性规则。
• tev1 只返回概率、不返回文本；需要可读理由时换生成类模型。
• 工具原始输出落到插件自建的临时目录（总上限 16 MiB，spillDirCap），路径随结果回传。
• 判定全程本地，插件自身不发起云调用。

开发

node --test test/*.test.mjs     # 全量套件
node --check lib/*.js          # 语法门

改过 lib/ 后，先在 DSH 里重载插件再下结论：宿主跑的是最后一次加载的快照。

Licence

MIT —— 见 LICENSE。

无兼容层

这是一次性结构升级，不是版本过渡。旧行 id（decision-tools-tool）与旧配置键（decisionEnabled / monitorEnabled）不再被接受；使用上面的四行与三张 Config 表。契约见 docs/architecture.md，用例见 docs/use-cases.md。