mingdao-harness 0.3.1 → 0.4.0

package/docs/CONFIG.md

@@ -23,7 +23,7 @@
 | `baseUrl` | OpenAI 兼容 API 地址（可覆盖内置服务商默认值） |
 | `permission` | `ask`（默认）/ `auto` / `readonly`，或规则对象（见下） |
 | `sandbox` | `off` / `readonly` / `safe`（Linux + bubblewrap；其余平台自动降级） |
-| `contextBudget` | 上下文预算 tokens（模型预设默认值：flash 128k / pro 200k） |
+| `contextBudget` | 期望的上下文预算 tokens；实际预算按模型窗口自动收紧（见「本地模型自适应」） |
 
 可选字段：`temperature`、`maxOutputTokens`、`includeUsage`（流式请求 usage 统计，个别网关不支持
 `stream_options` 时设 `false`）、`autoTitle`（自动生成会话标题，默认开）、`notify`（任务桌面通知，默认开）、
@@ -221,7 +221,8 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 {
   "customModels": {
     "my-gpt4": { "label": "我的 GPT-4 网关", "baseUrl": "https://gateway.example.com/v1" },
-    "my-ds": { "label": "自建 DeepSeek 网关", "baseUrl": "https://gw.example.com/v1", "tokenizer": "deepseek" }
+    "my-ds": { "label": "自建 DeepSeek 网关", "baseUrl": "https://gw.example.com/v1", "tokenizer": "deepseek" },
+    "local-qwen": { "label": "本机 Qwen", "baseUrl": "http://127.0.0.1:8081/v1", "contextWindow": 131072, "maxOutputTokens": 8192 }
   }
 }
 ```
@@ -231,6 +232,27 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 自定义端点若跑的是 DeepSeek 系模型（模型名不以 `deepseek` 开头时默认走启发式估算、预算误差
 可达 ±2 倍），加 `"tokenizer": "deepseek"` 即按官方词表精确计数：
 
+### 本地模型自适应（v0.3.2）
+
+本机/内网部署的推理框架（baseUrl 为 `127.0.0.1`/`localhost`/私网 IP）自动按「资源有限」对待，
+避免长任务把上下文撑到窗口边缘后 prefill 指数恶化、被客户端超时掐断（典型：127k 上下文首 token
+需 200s+，客户端 3 分钟无响应断开 → network error）。机制：
+
+- **上下文窗口感知**：`customModels.<name>.contextWindow` 显式声明模型真实窗口；未声明时本地
+  模型兜底 **32k**、远程兜底 **128k**。
+- **安全预算**：`contextBudget` 会被自动收紧到 `min(contextBudget, 窗口×75%, 窗口−maxOutput−余量)`，
+  prompt 永不逼近窗口边缘（75% 舒适区以上 prefill 时间陡增）。
+- **边缘检测**：模型每轮上报真实 `prompt_tokens`，≥ 窗口 85% 时下一轮强制压缩历史（即使启发式
+  计数低估也强制触发）。
+- **工具输出截断**：单条工具结果按 `窗口/16` 封顶（最少 2000 字），小窗口不再整条回灌大段代码。
+- **分层超时**：`timeout.firstTokenMs`（首 token 等待，本地默认 600s / 远程 300s）、
+  `timeout.streamIdleMs`（流式空闲，默认 120s）、`timeout.totalMs`（总量，本地 30min / 远程 10min），
+  留空则自适应；本地慢 prefill 不再被一刀切超时误杀。
+
+```json
+{ "timeout": { "firstTokenMs": 600000, "streamIdleMs": 120000, "totalMs": 1800000 } }
+```
+
 ## 自定义 Provider 模块（非 OpenAI 兼容协议）
 
 在 `~/.mingdao/providers/<name>.mjs` 导出：

package/docs/DEVELOPER.md

@@ -0,0 +1,126 @@
+# MingDao Harness 开发者指南（v0.4.0 契约化）
+
+> 战略依据：[STRATEGY-NEXT.md](STRATEGY-NEXT.md)（垂直产品 × 开放内核）。
+> 本指南面向**用 MingDao 做二次开发 / 定制自己智能体**的开发者。
+> 稳定契约：`@stable` 导出在 minor 版本内保持向后兼容；`@experimental` 可能调整。
+
+## 零、三种使用方式
+
+| 方式 | 适合 | 命令 |
+| --- | --- | --- |
+| 产品终端 | 开箱即用的 DeepSeek 省钱 Coding Agent | `npm i -g mingdao-harness && mingdao` |
+| **Agent Preset** | 不改代码，声明式定制智能体（本指南重点） | `mingdao --preset <名>` |
+| **库嵌入** | 把 Agent 嵌进自己的 Node 程序 | `npm i mingdao-harness` + `import { createAgent } from 'mingdao-harness'` |
+
+零依赖承诺：安装无 node_modules 树；公共 API 只用 Node ≥18.17 内置能力。
+
+## 一、Agent Preset：声明式定制智能体
+
+### 1.1 什么是预设
+
+一个 JSON 文件 = { 系统提示定制段, 工具白名单, 权限模式, 模型建议, 参数 }。
+放在三个位置（同名后者遮蔽前者）：
+
+1. `<项目>/.mingdao/presets/<名>.json` — 项目级（随项目走）
+2. `~/.mingdao/presets/<名>.json` — 用户级（本机全局）
+3. `presets/`（随 npm 包分发）— 内置参考（已内置 `local-audit` 示例）
+
+### 1.2 格式
+
+```json
+{
+  "name": "code-reviewer",
+  "label": "代码审查员",
+  "description": "只读审查并输出分级报告",
+  "systemPrompt": "你是代码审查员。只读审查，按严重度分级输出，每条带文件:行号证据。",
+  "tools": ["read", "ls", "glob", "grep", "skill", "git", "fetch", "todo"],
+  "permission": "auto",
+  "model": "deepseek-v4-flash",
+  "temperature": 0.3,
+  "maxOutputTokens": 4096,
+  "maxRounds": 4,
+  "contextBudget": 96000
+}
+```
+
+字段全部可选（缺省保持当前配置）。`tools` 白名单外的工具对模型不可见、调用会被硬拦。
+未知字段会**校验报错**（防拼写错误静默失效）。
+`model` 是**建议**：CLI 在未显式 `-m` 时采纳；WebUI 以用户当前选择的模型为准（预设不覆盖）。
+
+### 1.3 使用
+
+- CLI：`mingdao --preset code-reviewer "审查 src/ 目录"`；交互模式 `mingdao --preset code-reviewer`。
+- REPL：`/preset` 列出全部；`/preset code-reviewer` 会话内切换（工具白名单/权限/参数即时生效）。
+- WebUI：输入框旁「预设…」下拉选择（随本次发送生效，服务端按会话应用）。
+- 程序化：`import { loadPreset, presetConfigOverrides, presetSystemBlock } from 'mingdao-harness'`。
+
+## 二、第三方工具：registerTool / config.tools
+
+### 2.1 程序化注册（嵌入自己程序时）
+
+```js
+import { registerTool, createAgent } from 'mingdao-harness';
+
+registerTool({
+  name: 'weather',
+  description: '查询城市天气',
+  parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+  run: async (args, ctx) => ({ ok: true, output: `${args.city}：晴 24°C` }),
+});
+// 之后 createAgent 的模型就能调用 weather；执行走统一权限/审计/省钱链路。
+```
+
+约束：名字 `[A-Za-z0-9][A-Za-z0-9_-]{0,63}`、不得与内置 13 工具同名、不得重复注册；
+`run` 抛异常会转成结构化错误回填（不中断会话）。
+
+### 2.2 声明式挂载（config.json，不改代码）
+
+```json
+{ "tools": [ { "name": "date-now", "description": "当前时间", "command": "date" } ] }
+```
+
+`command` 经 `/bin/bash -lc` 执行；**参数以 `MINGDAO_TOOL_ARGS`（JSON）环境变量传入**——
+不做字符串拼接（防注入），由命令自行解析；执行受权限引擎门控（与 bash 同权重）。
+改 config.tools 需重启生效（与 MCP 预设一致）。
+
+## 三、库嵌入：最小示例
+
+```js
+import { createProvider, createAgent, createPermission, createIO } from 'mingdao-harness';
+
+const provider = await createProvider(cfg, 'deepseek-v4-flash'); // cfg: 同 config.json 结构
+const io = createIO(); // 或自实现 print/ask 接口
+const agent = createAgent({
+  provider,
+  permission: createPermission('ask', io),
+  io,
+  modelName: 'deepseek-v4-flash',
+  workingDir: process.cwd(),
+  cfg,
+});
+const res = await agent.runTurn([
+  { role: 'system', content: '你是代码助手。' },
+  { role: 'user', content: '帮我看看 package.json 的依赖' },
+]);
+console.log(res.text, res.usage, res.perf);
+```
+
+## 四、公共 API 速查（@stable 面）
+
+| 分组 | 导出 |
+| --- | --- |
+| Agent 内核 | `createAgent` · `createPermission` · `createIO` |
+| Provider/模型 | `createProvider` · `resolveProviderConfig` · `modelPreset` · `resolveModelCaps` · `safeBudget` · `isLocalBaseUrl` |
+| 工具 | `registerTool` · `listRegisteredTools` · `mountConfigTools` · `buildToolSchemas` · `dispatch` |
+| Agent Preset | `listPresets` · `loadPreset` · `validatePreset` · `presetConfigOverrides` · `presetSystemBlock` |
+| 上下文 | `trimMessages` · `approxTokens` · `clampText` · `compactConversation` |
+| 配置/凭证 | `loadConfig` · `saveConfig` · `mingdaoHome` · `setStoredKey` · `maskKey` |
+| 计价/计量 | `estimateCost` · `isPeakHour` · `countTokens` · `makeTokenCounter` |
+
+@experimental（接口可能调整）：update/audit/skill-lib/skills/mcp/session 组。
+
+## 五、约定
+
+- 预设/工具的扩展点沿用既有安全链路（权限引擎、审计、脱敏、沙箱），**不提供绕过入口**。
+- 公共 API 变更必须过测试门禁（smoke 含「公共 API 导出面」断言）+ 发布前自检。
+- 自定义 Provider 模块（非 OpenAI 兼容协议）见 [PROVIDERS.md](PROVIDERS.md)。

package/docs/PLAN-v0.3.2.md

@@ -0,0 +1,65 @@
+# v0.3.2 规划：本地模型自适应（资源受限部署不中断）
+
+## 背景（用户 MacBook M5 Pro 实测定位结论）
+
+本地部署 `mtplx-qwen38-27b`（131072 窗口 + q8 KV 量化）跑 71 步长任务时 network error。
+其他 agent 定位结论：**不是内存拒绝，是「长上下文 prefill 过慢 → 客户端等待超时主动断连」**。
+
+- 服务端无任何 507/内存拒绝，q8 生效，峰值 47.38GB < 48G 预算。
+- 失败请求：prompt=127,912 / 131,072（窗口边缘），`request_cancelled=client_disconnected`，
+  188.9s 内 0 token 输出。
+- prefill 指数恶化：ttft 46.4s → 67.8s → 96.0s → 196.5s → 中断（189s 无输出）。
+  根因：每轮全量历史 + 上一轮大段代码输出回灌，新增 prefill 从 7.9k 涨到 32k，
+  prefill 速度仅 ~165–185 tok/s，ttft 超过客户端等待阈值。
+
+调用 DeepSeek 官方 API 无此问题（窗口 1M + prefill 极快），说明瓶颈在「资源受限的本地模型」，
+必须做成**共性能力**：其他客户本地部署更小模型（窗口小/内存少）也会踩，不能只修 MacBook。
+
+## 目标
+
+让 MingDao 针对不同「参数 / 上下文窗口 / KV cache / 机器资源」的模型**灵活自适应**，
+小模型、低内存自动收紧参数适应，不撑爆、不误杀；本地慢 prefill 不被一刀切超时掐断。
+
+## 方案（本次实现）
+
+### 1. 模型能力解析（`src/model-caps.js` 新增）
+单一来源解析 `contextWindow / maxOutputTokens / isLocal`：
+- 优先级：`customModels.<name>.contextWindow/maxOutputTokens` > 内置 preset > 兜底。
+- 兜底：本地模型 32k、远程 128k（本地小模型宁可保守不撑爆）。
+- `isLocalBaseUrl`：127.0.0.1 / localhost / 私网 IP 判定本地推理框架。
+
+### 2. 安全预算推导（`safeBudget`）
+`budget = min(期望 contextBudget, 窗口×75% 舒适区, 窗口 − maxOutput − 2048 余量)`。
+prompt 永不逼近窗口边缘（75% 以上 prefill 时间陡增），从根上避免 prefill 爆炸。
+对内置模型零影响（pro 200k / flash 128k 均远小于各自窗口 75%）。
+
+### 3. 分层超时（providers）
+- 首 token 等待：本地 600s / 远程 300s（覆盖慢 prefill）。
+- 流式空闲：有帧后 120s 无新帧即断（真挂死才断）。
+- 总量：本地 30min / 远程 10min。
+- `config.timeout.{firstTokenMs,streamIdleMs,totalMs}` 可覆盖；`parseStream` 按「帧到达」刷新
+  空闲计时（prefill 阶段服务端可能先发 usage-only 帧，不误杀）。
+
+### 4. 边缘检测 + 强制压缩
+模型每轮上报真实 `prompt_tokens`，≥ 窗口 85% 时下一轮 `force` 压缩——即便非 DeepSeek 模型
+启发式计数低估（误差 ±2 倍）也强制触发（`compact.js` force 绕过触发线门槛）。
+
+### 5. 工具输出截断自适应
+单条工具结果按 `窗口/16` 封顶（最少 2000 字），小窗口不再整条回灌大段代码。
+
+### 6. 配置/UI 打通
+- `customModels.<name>.contextWindow/maxOutputTokens`（WebUI 添加自定义模型表单新增两项）。
+- `config.timeout.*`（设置 → 通用面板新增三项，秒为单位，留空自适应）。
+- `/api/config`、`/api/models-config` 契约扩展。
+
+## 验收
+
+- smoke 新增 model-caps（本地/远程判定、窗口兜底/显式声明、舒适区+输出余量预算）与
+  provider 分层超时（首 token vs 流式空闲）两组断言。
+- 全绿：smoke 69 组 / e2e-local / e2e-web / e2e-schedule / api-contracts / bench；strict 0/0。
+- 用户在 3820 用本地模型跑长任务验收，确认无 network error 中断后发布。
+
+## 非目标（顺延）
+
+- 增量上下文（基线+变化）——自动续跑 + 语义检索已覆盖省钱与长程主场景。
+- 本地窗口自动探测（从服务端 /models 读 max_model_len）——依赖各家推理框架能力，暂用显式声明。

package/docs/PLAN-v0.4.0.md

@@ -0,0 +1,38 @@
+# v0.4.0 规划：阶段 A「契约化」——把 MingDao 变成可二次开发的开放内核
+
+> 依据：docs/STRATEGY-NEXT.md（已确认：垂直产品 × 开放内核；本地/私有化第一公民与 DeepSeek 省钱并列双主攻；v0.4.0 先做契约化）。
+> 原则：不新增重架构、不动零依赖根基；把**已存在**的扩展点从「能用」升级为「有契约、有文档、有示例、有测试」的一等公民。
+> 节奏：小版本分批，每批全绿 + 发布前自检；实现后不发布，等用户在 3820 验收确认。
+
+## 一、现状盘点（扩展点已存在，缺契约）
+
+- 公共 API 面：`src/index.js` 已导出 `createAgent` / `createProvider` / 工具 / 上下文 / 权限 / 模型 / 会话 / 计价 / tokenizer 等（42 行导出，无 semver 承诺、无开发者文档）。
+- 扩展点：自定义 Provider 模块（`<home>/providers/*.mjs`）、hooks（PreToolUse/PostToolUse）、用户级/项目级技能、MCP 客户端、`customModels`——全部可用，但契约散落、无统一示例。
+
+## 二、本版目标
+
+1. **公共 API 冻结与文档**：`docs/DEVELOPER.md`（API 参考 + 最小示例集），`src/index.js` 导出面逐项标注稳定性（stable / experimental）。
+2. **Agent Preset（智能体预设）**：声明式文件 = { 系统提示, 工具集白名单, 权限策略, 记忆策略, 模型建议 }，放 `<home>/presets/` 或 `<项目>/.mingdao/presets/`；CLI（`mingdao --preset <名>`）与 WebUI 一键选用。
+3. **第三方工具注册**：`registerTool({ name, schema, run })` 程序化注册 + `config.tools` 声明式挂载，工具进审计/权限/省钱 schema 链路。
+4. **契约测试**：预设加载、工具注册、公共 API 面的自动化断言入 smoke。
+
+## 三、任务分解（实现顺序）
+
+1. `src/presets.js`（新）：预设目录发现/加载/校验（JSON，schema 校验 + 错误可读）；内置一个示例预设（如「本地模型审计」：system 提示 + 只读工具集 + auto 权限 + 语义记忆）。
+2. `src/index.js`：导出 `loadPresets`/`resolvePreset`/`buildPresetConfig`；导出稳定性注释分 stable/experimental 两组。
+3. `src/tools/index.js`：`registerTool` + `listRegisteredTools`；`config.tools` 声明式工具挂载（name/schema/command 三态：内置函数引用 / bash 命令包装 / 自定义 Provider 函数）；注入 dispatch + 权限引擎 + 审计。
+4. CLI：`mingdao --preset <名>` 参数 + REPL `/preset`；WebUI 模型选择器旁加预设下拉（复用 /api/models-config 模式新增 /api/presets）。
+5. `docs/DEVELOPER.md`：API 参考表（stable/experimental 标注）+ 5 个最小示例（自定义工具 / 自定义 Provider / 自定义权限 / 自定义记忆 / embed 进自己的程序）。
+6. 测试：smoke 新增「presets：发现/校验/应用」「第三方工具：注册/调度/审计归属/权限拦截」「公共 API：导出面断言」；api-contracts 新增 /api/presets 契约。
+7. 全绿（smoke/e2e/bench/strict/typecheck）+ 自检 → 3820 验收 → 等确认后发布。
+
+## 四、验收标准
+
+- `npm i mingdao-harness` 后按 DEVELOPER.md 三步跑通一个自定义智能体（预设 + 自定义工具）。
+- 预设文件语义与 DSH profile 对齐但零依赖、JSON 声明式。
+- 全绿测试门禁 + strict 0/0 + 发布前自检；用户在 3820 验收后再发布。
+
+## 五、非目标（顺延后续版本）
+
+- 预设市场/registry 分发（阶段 B）、本地模型一键接入预设（阶段 B）、企业私有化包（阶段 C）。
+- 不引入 Cordis/插件内核；不做云平台/账号体系。

package/docs/STRATEGY-NEXT.md

@@ -0,0 +1,175 @@
+# MingDao Harness 战略复盘与长期路线（2026-09）
+
+> 成文：2026-09-05（v0.3.2 发布后）
+> 性质：战略策划文件，非迭代任务。路线图各阶段**经确认后**才逐步落地；
+> 每期迭代前先对照本文件确认方向不漂移，每期保持「可独立发布 + 全绿测试门禁 + 发布前自检」纪律。
+> 数据口径：本地仓库 git 历史 + 官网线上状态（2026-09-05 实查）。
+
+---
+
+## 一、回望：这 18 天我们走了什么路
+
+**时间轴**：v0.1.0（2026-08-18）→ v0.3.2（2026-09-05），18 天 83 个版本，平均 4.6 版/天。
+
+**沉淀下来的资产（按可验证程度排序）：**
+
+| 资产 | 事实 | 性质 |
+| --- | --- | --- |
+| 零依赖内核 | `src/` 73 文件 ~15K 行纯 Node 内置 API，无运行时 npm 依赖；`npm i -g` 秒装 | 分发/审计成本极低，同赛道稀缺 |
+| DeepSeek 省钱纵深 | 官方词表 BPE tokenizer（黄金值精确命中）· 前缀缓存两态冻结 · 峰谷双窗口计价 · Batch 半价 · 滞回压缩 · bench-savings 省 63% 基线 | 对 DeepSeek 计费细节的闭环掌握，通用框架不会做 |
+| 长程任务能力 | 任务续跑 + 检查点（v0.3.0）· 自动续跑（v0.3.1）· 项目级记忆 · 子代理 | 从「24 步必断」到「长任务连续执行」 |
+| 本地模型自适应 | 上下文窗口感知预算 + 分层超时 + 边缘强制压缩 + 工具输出自适应截断（v0.3.2） | 大厂押注云端模型，这是空档 |
+| 工程可信度 | strict 棘轮 0/0 · 覆盖率 60% · bench 208 断言 · 三平台 CI · 每次发布自检 | 信任是独立开发者最稀缺的护城河 |
+| 中国分发链路 | 官网直连下载（国内极速）+ gitee/gitcode 镜像 + 论坛 + 桌面自动更新 | 大厂不覆盖的「国内可用性」细节 |
+| 双界面 | TUI + WebUI + Electron 桌面（四平台签名包） | 使用面完整 |
+
+**结论**：我们走的其实是「**垂直产品路线**」——围绕 DeepSeek 省钱 + Coding 场景做深，每一版都在强化这个垂直切面。这条路是对的，但它有天花板：产品只能覆盖我们自己能想得到的场景，生态的想象空间被我们自己框死。
+
+---
+
+## 二、抬头看路：2026-09 的格局（外部实查）
+
+| 玩家 | 模式 | 事实（来源） |
+| --- | --- | --- |
+| **DSH（DeepSeek Harness）** | 官方智能体框架 | 2026-08-13 开源公测，MIT 协议，基于 Cordis「一切皆插件」，对标 Claude Cowork/Codex；插件生态同步开放；`npx @deepseek-ai/dsh web`；四种模式（标准/PTC/极简/创造）。**Model+Harness=Agent** 是官方公式。([IT之家](https://www.ithome.com/0/989/446.htm)) |
+| **WorkBuddy（腾讯）** | 通用 Agent 平台 | 2026-03 上线，2026-09-02 开放平台：首批 100+ 伙伴，打通硬件/行业应用/开发者三层生态（Skill/Expert/Connector，MCP+CLI 双方案）；目标「Agent 时代的操作系统」。([IT168](https://cloud.it168.com/a2026/0902/6948/000006948500.shtml)) |
+| **Claude Cowork** | 企业级 Agent+插件 | Anthropic 官方，企业定制插件，团队级工作流。([claude.com](https://claude.com/ko-kr/blog/cowork-plugins-across-enterprise)) |
+| **Claude Code / OpenHands** | 通用 Coding Agent | Claude Code $17/月托管；OpenHands BYOK 开源。([theaiagentindex](https://theaiagentindex.com/compare/openhands-vs-claude-code)) |
+| **元脑 Z3 等** | 本地智能体工作站 | 浪潮等硬件厂商做「中小企业本地智能体」一体机。([InfoQ](https://www.infoq.cn/article/yi0mr2CkzQZgljL00kgA)) |
+
+**格局读法**：
+
+1. **框架生态位已被官方拿走**。DSH 背靠 DeepSeek 官方 + MIT 开源 + Cordis 插件生态，任何第三方去拼「谁的框架更框架」都是正面撞车。
+2. **平台生态位被巨头拿走**。WorkBuddy 的开放平台是腾讯体量的资源战（硬件联名 + 行业伙伴 + 开发者三层），不可复制。
+3. **本地/私有化开始有玩家**。元脑 Z3 证明「中小企业本地智能体」是真需求，但它卖的是硬件一体机，软件层依然是空档。
+4. **独立开发者仍有机会的缝隙**：模型中立、零依赖、私有化、资源受限设备、中国本地分发——这些都是巨头和官方框架不优先的地方。
+
+---
+
+## 三、路线抉择：DSH 框架模式 or WorkBuddy 通用 Agent 模式？
+
+### 3.1 两条路的本质与代价
+
+**纯 DSH 框架模式**（开放插件内核，开发者二次开发）：
+- 代价：需要 Cordis 级插件内核（与零依赖冲突）、插件生态冷启动（框架没人用就死）、与官方 DSH 正面撞车。
+- 我们没有 DeepSeek 官方的品牌和流量，无法复制。
+
+**纯 WorkBuddy 模式**（通用 Agent + 开放平台）：
+- 代价：需要腾讯级的硬件/行业资源、平台治理、商业化能力；通用办公场景与 WorkBuddy/讯飞等正面交锋。
+- 我们既没有资源，也不应该丢下已经做深的 Coding + DeepSeek 垂直面。
+
+### 3.2 结论：不做「二选一」，做「垂直产品 × 开放内核」一体两面
+
+**MingDao 的路 = 保持垂直产品的深度（DeepSeek 省钱 Coding Agent），同时把内核开放出来（让第三方开发者定制自己的智能体）。**
+
+理由（各自独立成立）：
+
+1. **产品侧**：我们已经用 83 个版本证明了「DeepSeek 重度用户 + 省钱 + 省心」这条垂直产品线成立（官网已上线、桌面分发、真实用户验收）。丢垂直面去追平台 = 自废武功。
+2. **内核侧**：`src/index.js` 已经导出了完整公共 API 面（`createAgent` / `createProvider` / 工具 / 上下文 / 权限 / 会话 / 计价 / tokenizer，42 行导出），扩展点（自定义 Provider 模块、hooks、用户级技能、MCP）也已存在——**我们其实已经是「半个框架」了，缺的是把扩展点从「能用」变成「有契约、有文档、有示例、有分发」的一等公民**。
+3. **差异化恰好落在巨头缝隙**：DSH 要 pnpm install + build + Cordis 概念负担；WorkBuddy 是云端平台。我们给开发者的是「**零依赖、一条 npm 命令、本地/私有化第一公民、模型中立**」的定制基座——这是官方框架和巨头平台都不给的位置。
+
+### 3.3 是否开放接口？——开放，但要按我们的方式开放
+
+- **开放什么**：智能体预设（Agent Preset：系统提示 + 工具集 + 权限策略 + 记忆策略打包成一个可安装单元）、程序化工具注册（第三方工具进注册表）、hooks、Provider、技能——这些点已存在，v0.4.x 起把它们正式化为**有契约的公共 API**（semver 保证，example 仓库，文档站）。
+- **不开放什么（至少现在）**：不引入 Cordis/重插件内核（保住零依赖）、不做云平台账号体系、不做插件商店抽成商业化。
+- **开放的方式**：`npm i mingdao-harness` 当库用 + `<preset>.json/mjs` 声明式组合，学习成本以「分钟」计，而不是 DSH 的「先懂 Cordis」。
+
+---
+
+## 四、优势与护城河：诚实盘点
+
+**真护城河（别人短期抄不走）：**
+
+| # | 护城河 | 为什么难抄 | 现状 |
+| --- | --- | --- | --- |
+| 1 | **DeepSeek 省钱纵深链** | 官方词表黄金值、峰谷双窗口、缓存 1/30、Batch 半价的组合闭环 + bench 棘轮锁定，需要长期浸在 DeepSeek 计费细节里 | 已建成，持续加深 |
+| 2 | **零依赖内核** | 主流框架全是依赖树；推到「一条命令装完」需要从头设计约束 | 已建成 |
+| 3 | **本地模型自适应** | 大厂产品绑定自家云端模型；「资源受限本地模型不中断」是空档，我们已有 v0.3.2 的完整机制 | 刚建成，是未来主攻方向 |
+| 4 | **工程可信度** | strict 0/0 + 覆盖率 + bench + 发布自检的纪律是组织习惯，不是功能 | 已建成 |
+
+**伪护城河（会褪色，要警惕）：**
+- 功能广度（工具数/技能数）——DSH 插件生态几个月内就会超过我们。
+- 「先发」本身——DSH 公测才一个月，窗口极短。
+- 省钱幅度数字——会被大厂「抄作业」，只有持续领先才有意义。
+
+**护城河的正确用法**：不靠单一护城河，靠「#1+#2+#3+#4 的组合 + 持续领先节奏」——单点都可被追平，组合与速度难被复制。
+
+---
+
+## 五、错位竞争：怎么避开与头部大厂正面交锋
+
+**三条避战原则：**
+
+1. **不拼框架拼契约**。DSH 的框架深度我们拼不过，但「零依赖 + 分钟级上手」的定制体验是 Cordis 给不了的。开发者要的不是更多抽象，是更快落地。
+2. **不拼平台拼私有**。WorkBuddy 拼云上生态，我们拼「你的模型、你的机器、你的数据不出门」——政企私有化、科研本地算力、个人 MacBook 本地模型。
+3. **不拼通用拼垂直**。通用办公场景让 WorkBuddy 和讯飞去卷；我们把「DeepSeek 省钱」和「本地模型自适应」两个垂直面做到他们不想做、做了不划算的深度。
+
+**对标表（MingDao 与谁不打、与谁打）：**
+
+| 维度 | 巨头在做什么 | MingDao 的打法 |
+| --- | --- | --- |
+| 模型绑定 | 各自绑自家云端模型 | **模型中立**：DeepSeek 深度优化 + 任意 OpenAI 兼容 + 本地模型一等公民 |
+| 部署 | 云平台 / 托管订阅 | **私有化/本机第一**：npm 即装、桌面即装、数据不出门 |
+| 生态 | 插件市场、开放平台 | **轻量契约**：预设/工具/技能契约 + 官方示例库，不追商店规模 |
+| 分发 | 官方渠道 | **中国本地分发**：官网直连、gitee/gitcode、论坛（已建成，继续维护） |
+
+---
+
+## 六、独特的 MingDao：一句话定位
+
+> **「模型中立、零依赖、会省钱、私有化第一公民的 Agent 内核与终端」——
+> 给 DeepSeek 重度用户一个最省钱的 Coding Agent，给开发者一个分钟级上手的定制基座，给本地/私有化场景一个不被云端绑架的选择。**
+
+对照 STRATEGY-0.3 的旧定位（「DeepSeek 生态里最好用、最能省、最省心的 Coding Agent 终端」）：**旧定位是产品定位，新定位是产品+内核双定位**。产品线继续按旧定位做深，新增的内核线把天花板打开。
+
+---
+
+## 七、路线图（确认后逐步落地，每期可独立发布）
+
+### 阶段 A「契约化」（v0.4.x，约 2-3 版）
+把已有扩展点正式化为公共 API，**不新增重架构**：
+1. 公共 API 冻结与文档：`src/index.js` 导出面逐项 semver 化 + JSDoc 契约 + `docs/DEVELOPER.md`（API 参考 + 5 个最小示例：自定义工具、自定义 Provider、自定义权限、自定义记忆、embed 进自己的程序）。
+2. **Agent Preset 格式**：一个声明式文件 = { 系统提示, 工具集白名单, 权限策略, 记忆策略, 模型建议 }，放 `<home>/presets/` 或 `<项目>/.mingdao/presets/`，CLI/WebUI 一键选用（对齐 DSH 的 profile 概念，但零依赖、JSON 声明式）。
+3. 第三方工具注册 API：`registerTool({ name, schema, run })` 程序化注册 + `config.tools` 声明式挂载，进审计/权限/省钱链路。
+- 验收：全绿 + 新增 API 契约测试 + example 仓库跑通。
+
+### 阶段 B「生态萌芽」（v0.5.x）
+1. 官网开发者区：文档站 + 示例库 + 预设目录（官网分发，与桌面安装包同一基建）。
+2. 预设市场雏形：预设/skill 的 registry 已有 sha256 防篡改基建（技能库已用），复用到预设分发。
+3. 本地模型生态打通：ollama / llama.cpp / vLLM 一键接入预设（复用 v0.3.2 的窗口自适应），把「本地模型」从「用户自己配」变成「选一个预设即可」。
+- 验收：开发者按文档 10 分钟跑通自定义智能体；本地预设端到端可用。
+
+### 阶段 C「纵深与护城河加固」（v0.6.x）
+1. 省钱纵深继续领先：Batch 自动化、路由升级、更精细分账（保持 bench 棘轮只升不降）。
+2. 企业私有化包：内网部署包（零外网依赖）+ 国产 GPU/本地推理适配。
+3. 生态反哺产品：社区预设/工具里验证过的能力回并进内置产品。
+
+### 明确的「不做」清单
+- 不自研模型、不做云端 Agent 平台、不做账号/订阅体系。
+- 不引入 Cordis/任何重依赖插件内核（零依赖是根基）。
+- 不做硬件生态、不做应用商店抽成。
+- 不与 DSH/WorkBuddy 在「框架完备度/平台规模」上对标竞争。
+
+---
+
+## 八、节奏与纪律（防止战略漂移）
+
+1. **每期对照本文件**：迭代前先回答「这一期强化的是 #1-#4 里哪条护城河？有没有撞进『不做』清单？」
+2. **产品/内核双线比例**：产品线（省钱/省心）与内核线（契约/生态）按 2:1 分配精力，产品线永远优先（产品是内核的活广告）。
+3. **发布纪律不变**：全绿测试门禁 + 发布前自检 + 用户验收后再发布。
+4. **战略复盘节奏**：每 10 个版本重读一次本文件，用事实（下载/issue/生态反馈）校准路线。
+
+---
+
+## 九、待用户决策的关键点
+
+> **✅ 已确认（2026-09-05）**：
+> 1. 方向：**认同「垂直产品 × 开放内核」路线**——不做纯 DSH 框架、不做纯 WorkBuddy 平台。
+> 2. 主攻：**「本地/私有化第一公民」与「DeepSeek 省钱」并列双主攻**。
+> 3. 节奏：**v0.4.0 先做阶段 A「契约化」**（公共 API 冻结 + Agent Preset + 第三方工具注册 + DEVELOPER 文档示例）。
+>
+> 落地计划见 [PLAN-v0.4.0.md](PLAN-v0.4.0.md)。
+
+1. **方向确认**：是否认同「垂直产品 × 开放内核」路线（不纯框架、不纯平台）？——✅ 认同
+2. **开放节奏**：阶段 A 的「契约化」是否作为 v0.4.0 的第一优先级？——✅ 是
+3. **本地模型战略地位**：是否把「本地/私有化第一公民」提升为与「DeepSeek 省钱」并列的主攻方向？——✅ 是，双主攻

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   "files": [
     "src/",
     "skills/",
+    "presets/",
     "assets/",
     "docs/",
     "install.sh",

package/presets/local-audit.json

@@ -0,0 +1,10 @@
+{
+  "name": "local-audit",
+  "label": "本地模型审计",
+  "description": "面向本地/资源受限模型（如 131k 窗口 q8 量化）的只读审计预设：只读工具集 + auto 权限 + 保守参数，配合 v0.3.2 本地自适应长任务不中断",
+  "systemPrompt": "你是一名代码审计员。任务是对给定代码库做只读审计：先 ls/glob 摸清结构，再 read/grep 逐文件审查，可用 git 查看历史与 diff、fetch 抓取相关文档。输出审计报告：发现的缺陷按严重度分级，每条给出文件:行号证据；不做任何修改。若上下文紧张，先审查最关键的部分并明示未覆盖区域。",
+  "tools": ["read", "ls", "glob", "grep", "skill", "git", "fetch", "todo"],
+  "permission": "auto",
+  "maxRounds": 4,
+  "maxOutputTokens": 4096
+}

package/src/agent.js

@@ -6,6 +6,7 @@ import { trimMessages, clampText, messageTokens, approxTokens } from './context.
 import { compactConversation } from './compact.js';
 import { buildToolSchemas, dispatch } from './tools/index.js';
 import { modelPreset } from './models.js';
+import { resolveModelCaps, safeBudget, EDGE_RATIO } from './model-caps.js';
 import { makeTokenCounter } from './tokenizer.js';
 import { createHooks } from './hooks.js';
 import { createIO, style, C } from './ui.js';
@@ -29,8 +30,19 @@ const SUBAGENT_MAX_STEPS = 24;
  */
 export function createAgent({ provider, permission, io, modelName, workingDir, cfg = {}, undoStore, maxSteps, mcp, onCompact, sessionRef }) {
   const preset = modelPreset(modelName) || {};
-  const budget = cfg.contextBudget || preset.budgetTokens || 128000;
-  const maxOutput = cfg.maxOutputTokens || preset.maxOutputTokens || 8192;
+  // v0.3.2 模型自适应：预算按模型上下文窗口推导（留输出余量 + 75% 舒适区），
+  // 自定义/本地小模型不再套 128000 默认撑爆窗口；prompt 永不逼近窗口边缘（prefill 不爆炸）。
+  const caps = resolveModelCaps(cfg, modelName);
+  // safeBudget 恒用：即使用户显式 contextBudget 也套「窗口−输出−余量」上限与 75% 舒适区，
+  // 防显式值撑爆窗口（本地模型窗口可能只有 32k/131k，用户却留了默认 128000）。
+  const budget = safeBudget(cfg, caps);
+  // maxOutput 也按窗口封顶：显式配超大 maxOutputTokens 时，prompt(预算)+output 仍不得越过窗口
+  // （预算已按 caps.maxOutputTokens 留余量，但显式值可能更大——此处兜底，防服务端截断/拒绝）
+  const maxOutput = Math.min(cfg.maxOutputTokens || caps.maxOutputTokens, Math.max(1024, caps.contextWindow - budget));
+  // v0.3.2 工具输出截断自适应：窗口越小截得越狠（单条工具结果按窗口 1/16 封顶，最少 2000 字），
+  // 但绝不超过旧默认 20000（大窗口模型如 1M 不因公式放大回灌、不推高成本）。
+  // 本地小模型（32k 窗口 → 2k 字）不再把大段代码/日志整条回灌，省 prompt 且不撑爆窗口。
+  const toolResultCap = Math.min(20000, Math.max(2000, Math.floor(caps.contextWindow / 16)));
   const temperature = cfg.temperature ?? preset.temperature ?? 0.6;
   const reasoningEffort = cfg.reasoningByModel?.[modelName] ?? cfg.reasoningEffort ?? preset.reasoningEffort?.default ?? undefined;
   const hooks = createHooks(cfg.hooks, workingDir);
@@ -55,8 +67,18 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   const hasWriteIntent = (/** @type {any} */ text) => WRITE_INTENT_RE.test(String(text || ''));
   // A1（前缀稳定）：剥描述集合按「回合冻结快照」——回合内恒定（至多两态：只读档/全量档），
   // 新使用的工具只在下一回合才进入剥描述集合；回合边界本身就有新 user 消息，schema 变化免费。
+  // v0.4.0 Agent Preset：cfg.presetTools 白名单恒生效（在只读档过滤之后收紧——预设只减不增）。
+  const presetToolSet = Array.isArray(cfg.presetTools) ? new Set(cfg.presetTools.map(String)) : null;
+  const activePresetName = String(cfg.presetName || ''); // 白名单拦截提示用
   const toolsFor = (/** @type {boolean} */ readOnlyPhase, /** @type {Set<string>} */ strippedSet) => {
-    const schemas = buildToolSchemas(strippedSet, mcpSchemas());
+    let schemas = buildToolSchemas(strippedSet, mcpSchemas());
+    if (presetToolSet) {
+      schemas = schemas.filter((/** @type {any} */ t) => {
+        const n = t?.function?.name;
+        if (!n) return true;
+        return presetToolSet.has(n) || (n.startsWith('mcp__') && presetToolSet.has(n.slice(5)));
+      });
+    }
     if (!readOnlyPhase) return schemas;
     return schemas.filter((/** @type {any} */ t) => {
       const n = t?.function?.name;
@@ -152,6 +174,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     let aborted = false;
     let emptyRounds = 0; // 连续空/截断输出计数（防止无限续写）
     let currentAc = /** @type {any} */ (null);
+    // v0.3.2 边缘检测状态：模型上报 prompt_tokens 逼近窗口 → 下一轮强制压缩（见下方 compactConversation force）
+    let windowPressure = false;
+    let pressureWarned = false;
     // 省钱 B4（护栏降级）：action='downgrade' 超限后本回合切换到便宜模型继续执行；
     // activeModel 是本回合实际使用的模型（分账/记录归属它），downgraded 保证只提示一次。
     let activeModel = modelName;
@@ -201,6 +226,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             provider,
             executorModel: subagentModel(cfg, modelName),
             triggerRatio: cfg.compactTrigger, // 可配置触发线（默认 80%）
+            force: windowPressure, // v0.3.2：逼近窗口时强制压缩（忽略最小阈值门槛）
           });
           if (compacted) {
             messages.splice(0, messages.length, ...compacted.messages);
@@ -368,6 +394,16 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         if (Number.isFinite(res.usage.prompt_cache_miss_tokens)) {
           usage.prompt_cache_miss_tokens = (usage.prompt_cache_miss_tokens || 0) + res.usage.prompt_cache_miss_tokens;
         }
+        // v0.3.2 边缘检测：模型上报的真实 prompt_tokens（含缓存命中）逼近窗口 85% 即标记——
+        // 下一轮强制激进压缩（force），不让 prompt 逼近窗口边缘导致 prefill 指数恶化。
+        const realPrompt = Number(res.usage.prompt_tokens);
+        if (Number.isFinite(realPrompt) && realPrompt > 0 && realPrompt >= caps.contextWindow * EDGE_RATIO) {
+          windowPressure = true;
+          if (!pressureWarned) {
+            pressureWarned = true;
+            io.print(style(`⚠ 上下文已逼近模型窗口（${realPrompt}/${caps.contextWindow}，≥${Math.round(EDGE_RATIO * 100)}%），下轮将强制压缩历史防 prefill 恶化`, C.yellow));
+          }
+        }
       }
 
       if (res.toolCalls?.length) {
@@ -441,6 +477,13 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           }
 
           const isMcp = name.startsWith('mcp__');
+          // v0.4.0 Agent Preset：白名单强制（模型可能调用白名单外工具——schema 已不发，此处兜底硬拦）
+          if (presetToolSet && !presetToolSet.has(isMcp ? name.slice(5) : name)) {
+            io.renderToolDenied(name, args, `不在预设工具白名单内（${activePresetName || 'preset'}）`);
+            if (auditOn) auditEntry({ denied: true, reason: '预设工具白名单拦截' });
+            messages.push({ role: 'tool', tool_call_id: tc.id, content: `工具 ${name} 不在当前预设的工具白名单内，已拒绝执行。` });
+            return null;
+          }
           let allowed = false;
           if (isMcp && mcp?.isReadonly(name)) {
             allowed = true; // MCP 工具的只读标注自动放行
@@ -529,7 +572,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           }
           const text = typeof result === 'string' ? result : JSON.stringify(result); // 紧凑 JSON（评估 B3）：嵌套结果省 10-20% 回填 token，且下轮按 prompt 重复计费
           const prefix = prep.cached ? '（与同回合相同调用结果一致，已复用）\n' : '';
-          messages.push({ role: 'tool', tool_call_id: prep.tc.id, content: prefix + clampText(text) });
+          messages.push({ role: 'tool', tool_call_id: prep.tc.id, content: prefix + clampText(text, toolResultCap) });
         }
 
         let i = 0;