dsh-local-ollama-models

---

doc: usage-declaration plugin: "@local/dsh-local-ollama-models" version: 1.6.1 audience: AI agent（人类也可直接阅读） purpose: 让任何一台刚装上本插件的机器上的 AI，无需历史对话即可正确启用、使用并验收本插件 host-tools: [ollama_local_models, subagent_local] settings-section: 设置 → 本地模型 config-namespace: local-ollama-models hard-requirements:

• 本机 Ollama 可访问（默认 http://127.0.0.1:11434）
• llm-pi-ai 中存在一条 provider 路由（默认名 ollama-local）—— 见 §2.2
• 要委派的模型 id 必须写在该路由的 models: 列表里 —— 见 §2.3 integrity: 本文件与 package.json 的 version 应当一致；不一致说明插件被改过，优先信任代码

---

本地模型子代理 · 使用声明

DSH (DeepSeek Harness) plugin — delegate read-only collection tasks (scan logs, extract fields, count, dedupe, read a large file and return only the conclusion) to a local Ollama model: zero cloud token cost, zero API keys. Ships a Settings panel, a model-selection ruler (bench.mjs), and this AI-readable usage declaration. Requires DSH + Ollama ≥ 0.3 + one declared llm-pi-ai provider route. Full details below (Chinese; the plugin's UI text is Chinese as well).

这份文件是插件的自带说明书。它假设读者（AI 或人）此前对这台机器、这个插件一无所知， 因此把"怎么开、怎么用、怎么验收、怎么排错"全部写死在这里，不依赖任何历史对话。

装它（第一次来的人看这里）

这是一个 DSH profile bundle（不是独立程序）。两种装法，任选其一：

A. 从 GitHub 直接装（推荐，跟着仓库更新）

在 DSH 里让 AI 执行：plugin_manager → action: install_bundle → target: "github:Movingelated/dsh-local-ollama-models"。

B. 克隆后按路径装

git clone https://github.com/Movingelated/dsh-local-ollama-models.git

然后 install_bundle 的 target 填克隆到的绝对路径。

装完重启 DSH —— 宿主插件是模块代码，DSH 不做热替换（这条是实测结论）。重启后打开「设置 → 本地模型」。

⚠ 光装插件不够：委派还需要一条 provider 路由。没有 §2.2 那条路由，任何委派都会失败。 建议顺序：装插件 → 重启 → 按 §2.1 量本机模型 → 按 §2.2 声明路由与凭据占位 → 再重启 → 用面板开关。

0. 给 AI 的 60 秒速览

• 我拿到什么：两个工具 —— ollama_local_models（只读查状态）、subagent_local（把只读采集任务派给本机 Ollama 模型，零云端 token）。
• 第一步永远先调 ollama_local_models：它同时告诉你 Ollama 是否活着、有哪些模型可用、以及本 README 的绝对路径。
• 模型名与参数一律以本机实测为准：本文档里出现的任何模型名、吞吐、上下文、显存数字都只是样本，不是推荐值。 换一台机器，就照 §2.1 用 bench.mjs 重新量一遍，再决定往路由里写什么。
• 派活公式：subagent_local({ prompt })，prompt 必须自包含（绝对路径 + 要提取什么 + 输出格式），因为子代理看不到对话。
• 三条铁律：
  1. 只派读多写少的活（采日志、计数去重、字段抽取、模式匹配、图转文）；代码、架构、措辞交付别派。
  2. 它的数字不可信：分类与定位基本可信，计数必须自己机械复核（一条 grep 的事）。
  3. 大语料先切块：路由上下文默认 32K token，超了直接报错。
• 省钱的原理：不是本地模型算得快，而是主上下文不必吞下原文。原文只进本地，回来的是结论。
• 改配置不用重启：enabled / model / baseURL 是 volatile 字段，在「设置 → 本地模型」点一下即生效。
• 改代码要重启：宿主插件是 ESM 模块，DSH 不会热替换模块代码。

1. 它是什么，不是什么

是：一台"零成本的只读采集工人"。它把一段自包含的采集任务交给本机 Ollama 模型，在独立上下文里执行， 只把结论拿回主对话。子代理自己会调 read / grep 等只读工具去读文件、翻日志。

不是：

• 不是省钱魔法 —— 本地模型烧的 token 比云端更多（Ollama 没有提示缓存），它省的是主上下文，也就是钱。
• 不是万能工人 —— 它判断力弱：归类可以，计数不准，架构与质量类结论不可用。
• 不是写手 —— 不要让它产出最终交付文本或改代码。

2. 前置条件（换新机器只需照做这四步）

2.1 Ollama、模型与选型（本文件不指定推荐模型）

ollama --version                      # 需要 0.3 以上（/v1 兼容层 + tools 能力）
curl -s http://127.0.0.1:11434/api/version
ollama pull <模型>                    # 装哪个由下面的判据决定，别照抄本文档

本机一个模型都没有时，先随便拉一个支持工具调用的当起点（例如 qwen3:30b-a3b，约 17 GB）， 再用下面的尺子实测决定要不要换 —— 起点不等于推荐。

选型判据（六条，逐条量，别抄参数）

node bench.mjs                   # 第一步：列出本机可用模型 + 各自的事实（秒回，不测速）
node bench.mjs <模型id>           # 第二步：实测它（工具调用/吞吐/显存），并打印可直接粘贴的路由 YAML
node bench.mjs <模型id> --json    # 给程序或 AI 解析用

三条命令只读：只调 Ollama 的 /api/*，不拉取、不删除、不改配置。 它输出的 YAML 已经把本机实测值填好了 —— 抄它，别抄本文档。

2.2 在 profile 里声明 provider 路由

本插件不自带路由：它委派时必须有一个已注册的 provider 路由。没有这一步，任何委派都会失败。 把下面这段加到 profile 的 cordis.patch.yml（顶层数组里），路由名保持 ollama-local：

- id: llm-pi-ai
  name: "@deepseek-ai/dsh-llm-pi-ai"
  config:
    providers:
      ollama-local:
        displayName: Ollama 本地（文字）
        api: openai-completions
        baseURL: http://127.0.0.1:11434/v1
        apiKeyEnv: OLLAMA_API_KEY
        reasoning: off              # 开思考会吃光 token 预算且 content 恒空
        timeoutMs: 300000
        defaultContextWindow: 32768
        defaultMaxTokens: 8192
        defaultInput: [text]        # 显式声明，防止把图片误发给纯文本模型
        models:
          - id: "<本机实测选定的模型 id>"      # ← 用 bench.mjs 生成这一段，别照抄本文档
            name: <显示名，随便取>
            contextWindow: 32768               # 建议值；bench.mjs 会按该模型的原生上下文给出
            maxTokens: 4096
            input: [text]

凭据占位符：Ollama 的 /v1 不校验 key，但 pi-ai 必须有非空凭据。在 <DSH_HOME>/.credentials.yaml 的 refs 下加一条占位值即可（按请求解析，免重启）：

OLLAMA_API_KEY: ollama-local-no-key-required

2.3 模型必须写进路由（最容易踩的坑）

• 设置面板列出的是 Ollama 里的全部模型；能被委派的只有路由 models: 列表里声明过的那些。
• 选到未声明的模型 → 调用以 UNKNOWN_MODEL 失败（pi-ai provider "X" has no configured model "Y"）。
• 本插件会在委派前自查并给出可执行的报错（列出该路由已声明的模型 id），但补声明要人工做： 在 §2.2 的 models: 下加一条，然后重启 DSH。

2.4 自检清单

ollama ps                                   # 看模型是否 100% GPU 驻留

cordis_inspect_query host / Config / listConfigs  {name: "@local/dsh-local-ollama-models"}
  → status 应为 "schema"（为 "absent" 说明 Config 没加载，设置页将不可写）
cordis_inspect_query host / Tool / listTools
  → 应能看到 ollama_local_models 与 subagent_local
cordis_inspect_query client / Slots / listSubTree {root: "settings.section"}
  → occupants 里应有 id "local-ollama"

3. 开启与配置

方式一（推荐，人人可用）：设置 → 本地模型 →

• 「启用本地模型子代理」按钮：开 / 关
• 模型列表：点任意条目切换默认模型
• 端点框：改完失焦即保存（留空 = 先读 OLLAMA_HOST，再退回 127.0.0.1:11434）

方式二（无界面时）：直接改 profile 的 cordis.patch.yml：

- id: local-ollama-models
  config:
    enabled: true            # 开关
    model: <本机实测选定的模型 id>   # 默认模型（必须已写进路由 models:，见 §2.3）
    baseURL: ""              # 端点覆盖
    toolName: subagent_local # 工具名（非 volatile，界面改不到）
    provider: ollama-local   # 路由名（非 volatile，需与 §2.2 一致）
  disabled: false

生效语义：enabled / model / baseURL 是 volatile 字段 —— 写进 profile patch， 即时生效、无需重启、不重挂插件。其余字段改了要重启。

关闭：把开关关掉，或在「插件」页停用本 bundle（停用会让两个工具一起从工具表消失）。

历史包袱：1.2.0 之前用过 <DSH_HOME>/local-ollama-models.json 存状态，现已废弃、不再读取，可以删。

4. 工具契约

ollama_local_models()

• 入参：无。只读，无副作用，不启动也不下载任何模型。
• 返回：端点 / 连通性 / 版本 / 模型总数 / 可作子代理数 / 可用模型清单（带体积、量化、上下文、人设警告）+ 本 README 路径。
• 用于：委派前的环境确认；以及"这台机器上到底有什么模型"。

subagent_local({ prompt, model?, label?, collect? })

• prompt（必填）：自包含任务描述。必须含要提取什么、期望输出格式。
• model（可选）：覆盖默认模型，须在 §2.3 的已声明列表内。
• label（可选）：会话里显示的短标签。
• collect（可选，v1.5.0 起强烈建议；v1.6.0 起支持自动分批）：让宿主侧代取素材，直接把命中行拼进子代理的 prompt。 { path, include?, pattern?, maxChars?, chunkLines? } —— path 是文件或目录，include 是目录下的文件名 glob（如 launcher*.log）， pattern 是 JS 正则会只保留匹配行（建议最简形式 WARN|ERROR），maxChars 默认 60000 超则截断， chunkLines（默认 0 = 不分批）超过该行数就自动切片 → 逐片归类 → 合并（每片 ≤N 行且 ≤8000 字符，最多 8 片）。 用了它：素材 100% 正确、不占主上下文、子代理的 grep/glob 会被自动禁用（它就是靠这两个工具静默改坏过素材）。 结果末尾会回 [宿主预取素材] N 个文件 / M 行 / K 字符 与 [分批委派] X 片 × ≤N 行 → … 共 T 秒，供调用方核对。 ⚠ 为什么值得分批：实测同一模型 33 行 → 100% 覆盖，115 行 → 59%（详见 §9.1）。
• 返回：本地模型产出的文本结论（不是原始文件内容）。
• 错误语义（都会抛错，不会静默失败）：

  报错关键字	含义	处置
  关闭状态	开关是关的	打开「设置 → 本地模型」的开关
  尚未指定本地模型	没配 model	面板选一个，或传 model
  provider 路由 ... 未注册	缺 §2.2 的路由	补路由后重启
  没有写进 provider ... 的 models 列表	缺 §2.3 的声明	补声明后重启
  subagents 服务不可用	宿主组合异常	检查 dsh-base 是否完整

• 子代理视角：看不到本对话，独立上下文，跑在配置的 provider 路由上，零云端 token。
• 只读是机制保证的：委派时用 toolFilter.deny 摘掉 write / edit / pwsh / job_kill / plugin_manager 以及再派活类（subagent / subagent_fork / subagent_local / workflow）。 ⚠ 但 tools.restrict() 只认"继承来的可 restrict 全局工具名"（dsh-tools: view(scope).restrictableNames）， 名单里只要有一个不在该集合里，整条调用就抛错。所以插件是"尽力而为"：把报错点名的名字逐个剔除后重试， 保住其余防护；整份名单都被拒时才退化为不过滤。 并且它一定会告诉你结果 —— 过滤没能完全生效时，委派结果末尾会附一句 ⚠ 只读过滤未完全生效：<被剔除的名字> 或 ⚠ 只读过滤未生效：…。 想自行核对权威证据：跑一次委派，再看那个子代理会话的 request/header.tools 里有没有 write。
• 本机实测（一次真实委派，权威证据取自子代理会话的 request/header.tools）： 工具数 32 → 24；被摘掉的是 write / edit / pwsh / job_kill / plugin_manager / subagent_fork / subagent_local / workflow；唯一摘不掉的是 subagent —— 它落在子代理 scope 自己的那一层，而 view() 里"自己层"的工具只算 known、不算 restrictable，属于 tools.restrict() 的固有限制。 想彻底封死"子代理再派活"，可考虑给 agentOptions 配 maxDepth（本插件未启用，未验证；注意 maxDepth: 0 会让子代理卡在启动前）。在这一天到来之前，这句 ⚠ 就是它诚实的自我声明。

5. 最优使用法

5.1 该派 / 不该派

判据一句话：输出能被机械验收（grep / 数字 / schema）→ 派；需要"信它的判断"→ 别派。

5.2 prompt 模板（v1.5.0 起：素材交给宿主取）

首选做法：用 collect 参数，不要让本地模型自己去 grep。

// subagent_local({ prompt, collect })
{
  "prompt": "把素材里的「告警与报错」按根本原因归类去重。\n输出格式：分类 | 次数 | 代表原文(≤80字) | 出处\n最后单独一行输出 TOTAL=<覆盖条数>。不要开场白、解释、建议。",
  "collect": { "path": "D:\\logs", "include": "app*.log", "pattern": "WARN|ERROR", "maxChars": 60000 }
}

prompt 里不用再写路径（素材已附在 prompt 末尾），只写"要什么 / 怎么归类 / 输出格式"。

万不得已要它自己取素材时，两条死规矩：

1. 检索式必须是最简形式（如 WARN|ERROR）——给它带括号或转义的正则，它一定会"优化"它。
2. 强制自报口径：要求它先输出 HITS=<工具返回的条数>，最后输出 TOTAL=<覆盖条数>，两个数必须相等。
3. 一口别超过约 40 行：同一批素材行数越多，它越容易只抓大类别、丢掉只有 1~3 条的小类别。 实测同一模型同一任务：33 行 → 100% 覆盖（6/6 根因）；115 行 → 59%（4/6 根因，丢的全是 ≤3 条的小类）。 对策（v1.6.0 起首选自动）：给 collect 加 chunkLines: 40 —— 宿主自动切片、逐片归类、再合并， 每一口都是"小而完整"的料；先去重再喂同样有效（本例 6 份日志是同一份的累积快照，只取最新那份即从 115 行降到 33 行）。 对照数据见 §9.1。

经验：

• 一次只派一个任务；任务边界越窄，本地模型越不容易跑偏。
• 让它只输出表格/清单，别要散文 —— 散文既贵又难验收。

5.3 模型常驻

切换模型要重新加载（5～30 秒，显存大的要更久）。锁定一个主力模型长期用，别一次任务换一个。 ollama ps 可以看到驻留情况（默认闲置 5 分钟后卸载）。

5.4 让它"在该用的时候被用上"（主动性机制）

问题：工具描述只会说"我能做什么"，不会在具体情境里主动冒出来。上线首日实测：某会话 250 次工具调用中， 本插件仅 6 次，全部是用户点名要求演示的，自发调用 0 次。工具没问题 —— 是触发条件没写进模型看得见的地方。

两个机制（v1.4.0 起）：

怎么验证生效：重启 DSH 后给一个"读大文件 / 扫一批日志"的任务，看是否先调 subagent_local； 或让它读一份 > 30 KB 的文件，结果末尾应出现 ⚠ 采集提示。

怎么调：阈值与文案都在 index.js —— BIG_READ_CHARS（默认 30000 字符）、DELEGATION_POLICY。 ⚠ 政策文本必须保持静态（见 §10 第 7 条）。

6. 验收纪律（本节最重要）

本地模型的"分类"和"定位"基本可信，"计数"和"统计值"不可信。 样本数据（某 30B 级模型的一次真实委派；换模型后偏差幅度会变，但"数字必须复核"这条纪律不变）：

因此验收动作固定为三条：

1. 先对账再信数：让它回报 HITS（取到多少行）/ TOTAL（覆盖多少行），两者不等就有缺口； 再用你自己的 grep 核一遍总量。
2. 数字自己数一遍：Select-String -Path <files> -Pattern <关键词> | Measure-Object（或 grep -c）。成本几秒。
3. 抽查 2～3 条引用：打开它给的行号，确认内容对得上；行号对不上就整份打回。

⚠ 口径也要对齐：大小写、编码、是否把续行算作命中，都会改变计数。实测我自己的 PowerShell 计数 （Select-String 默认大小写不敏感）把一条 JSON 续行 [Error: ... 也算成命中，比真实标记多 1 条 —— 差点把一次"33/33 全召回"判成 97%。数错的不只是本地模型，验收工具链也会。

7. 已知限制

8. 故障排查

9. 实测样本（一台具体机器的数字，只示范方法，切勿照抄）

下表来自一台 24 GB 显存的机器，不是推荐清单。换机器后"装不装得下、快不快"都会变。 量你自己的：node bench.mjs（清单）→ node bench.mjs <id>（实测 + 打印路由 YAML）。判据见 §2.1。

9.1 对照实验：素材"怎么喂"决定召回率（同一模型、同一任务）

任务：把 6 份启动器日志里的告警按根因归类。裁判：宿主侧机械分组（大小写敏感、按消息去重，见 §6 口径提醒）。

四条结论：

1. 取材错 = 灾难：A/B/C 三组全都漏掉最大的一类（node.exe，26 条），因为它的 grep 把 [WARN ] （WARN 后带空格）整类滤掉了 —— 而输出行号真、原文真、格式规整，看起来毫无破绽。
2. 取材对了，还有规模门槛：E 组素材 100% 正确、node.exe 找回来了（25/26），但 115 行一口吃下只剩 59%， 丢的全是 ≤3 条的小类。同一模型：33 行 100% vs 115 行 59% —— 小模型的"胃口"是真有上限的。
3. 分批把"丢小类"基本治好了：E2（E + chunkLines: 40）把 浏览器 2 / 进程崩溃 2 / 环境标志 3 这些小类全找回来了，根因覆盖 4/7 → 6/7（只差 20 秒无响应 那 3 行）。 代价：本地时间 56.9s → 137.6s（3 片 + 1 次合并；本地 token 35,967，零成本）； 4 次推理全部零工具调用、工具表 22 个（grep/glob 被摘）。分批买的是召回率，付的是本地等待时间。
4. ⚠ 合并这一步会让计数膨胀：E2 报 node.exe 54 次，逐行数只有 26；报 TOTAL=75，素材实际 115 行。 所以"数字自己数一遍"这条纪律，分批之后更不能省。

一次真实委派的账本（一批 82.1 KB 的日志，997 行 / 118 条告警）：

10. 维护铁律（要改这个插件之前必读）

1. 工具集合恒定：只在 apply() 里注册一次，不因配置变化增删。工具表一变，整条 prompt 前缀缓存作废， 几十万 token 的会话要重新 prefill，用户会看到"发一句话卡住几分钟"（实测 166 秒零 token）。

2. 配置走 volatile：只有 Schema.volatile() 字段才会出现在设置表单并被写入接口接受； 改完即时生效、不重挂插件。非 volatile 字段只在 patch 里改。

3. 零裸 import：插件以 link: 安装，模块真实路径在工作区，Node 从真实路径向上找不到 profile 的依赖树 （实测 ERR_MODULE_NOT_FOUND）。需要 schemastery 时用 createRequire 以 dsh 安装目录 / profile 目录为基准解析。

4. 前端护栏：React Hook 只能在组件函数体内（在 factory 里调用组件会让整棵前端树崩掉）； 面板要包 ErrorBoundary；remote 的命名空间必须逐个显式 inject。

5. 异步流程不许在模块加载期跑：加载期零副作用，全部进 apply()。

6. toolFilter 名单要跟着部署走：tools.restrict() 只认"可 restrict 的继承全局工具名"，名单里有一个不在就整条抛错 （allow 与 deny 一样）。startChild() 已把这一步包成"按报错点名逐个剔除 → 重试 → 结果里如实告知"， 改名单时务必保留这条自适应路径，否则换台机器就可能静默失去防护（真机踩过一次静默降级）。

7. 政策段落文本保持静态：DELEGATION_POLICY 里不要塞 enabled/model 这类会变的状态 —— 它位于系统提示词最前端， 文本一变整条 prompt 前缀缓存作废，长会话要重新 prefill（实测踩过 166 秒零 token）。要降级就用文案里的"报已关闭就自己读"。

8. 主动性靠"看得见的触发条件"，不靠工具描述：光有工具不给触发规则，实测自发调用率是 0（见 §5.4）。 想让它被用上，就把"什么时候用"写进系统提示词或工具结果，而不是写进 README 等模型来读。

9. 取材不交给弱模型：凡是"它自己选参数"的环节（正则式、路径、扫描范围）都是静默失败的来源 —— 错误不会写在输出里，只会让某一整类凭空消失，而报告看起来毫无破绽。要么给死参数，要么由宿主代劳（collect）。

10. 验证自己的工具链：判分用的 grep/PowerShell 也要声明口径（大小写、编码、续行），否则你会拿被污染的 分母去评判别人（实测差点把 100% 判成 97%）。

11. 弱模型的"胃口"有上限，而且只能靠分批解决：同一模型同一任务 33 行 100% / 115 行 59%（§9.1）—— 提高 prompt 质量、强制先清点，都没能改善（B/C 组实测无效）。collect.chunkLines 就是为这条存在的： 切片 → 逐片归类 → 合并，全程在宿主侧，主上下文不受影响（E 组：零工具调用、只回结论）。

11. 文件清单