mingdao-harness 0.3.2 → 0.4.0

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.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.2",
+  "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

@@ -67,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;
@@ -467,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 工具的只读标注自动放行

package/src/cli.js

@@ -79,6 +79,7 @@ const HELP_LINES = [
   ['  mingdao --journal          新会话带上最近会话日志（默认不注入，新会话全新开始）', null],
   ['  mingdao --resume           从会话列表选择恢复', null],
   ['  mingdao --model <模型名>   指定模型，例如 deepseek-v4-pro', null],
+  ['  mingdao --preset <名>      应用智能体预设（工具白名单/权限/参数，v0.4.0 契约化）', null],
   ['  mingdao init               初始化配置向导', null],
   ['  mingdao update [--check]   一键自更新（git 安装形态；--check 只对比版本）', null],
   ['  mingdao rollback           回滚到上次 update 之前的提交', null],
@@ -125,6 +126,8 @@ function parseArgs(/** @type {any} */ argv) {
     else if (a === '-v' || a === '--version') opts.version = true;
     else if (a === '-c' || a === '--continue') opts.continueSession = true;
     else if (a === '--journal') opts.journal = true;
+    else if (a === '-p' || a === '--preset') opts.preset = argv[++i];
+    else if (a.startsWith('--preset=')) opts.preset = a.slice(9);
     else if (a === '-r' || a === '--resume') opts.resume = true;
     else if (a === '--init' || a === 'init') opts.init = true;
     else if (a === '-m' || a === '--model') opts.model = argv[++i];
@@ -350,6 +353,29 @@ async function main() {
   // 模型回退链（向导允许跳过模型选择 → cfg.model 可缺省）：参数 > config > 该服务商首个预设模型 > flash
   let modelName = opts.model || cfg.model || /** @type {any} */ (PROVIDERS)[cfg.provider]?.models?.[0] || 'deepseek-v4-flash';
   const io = createIO();
+  const workingDir = process.cwd();
+
+  // v0.4.0 Agent Preset：--preset <名> 应用声明式预设（工具白名单/权限/模型/参数 + 系统提示定制段）。
+  // 预设覆盖优先级：CLI 显式参数 > 预设 > config.json。
+  // 会话级 overlay：不改写 cfg（否则 REPL /model、/think 的 saveConfig 会把预设字段持久化进 config.json）。
+  let activePreset = /** @type {any} */ (null);
+  let presetBlock = '';
+  let presetOverlay = /** @type {Record<string, any>} */ ({});
+  if (opts.preset) {
+    const { loadPreset, presetConfigOverrides, presetSystemBlock, listPresets } = await import('./presets.js');
+    activePreset = loadPreset(workingDir, opts.preset);
+    if (!activePreset) {
+      const names = listPresets(workingDir).map((/** @type {any} */ p) => p.name).join(', ') || '（无可用预设）';
+      io.print(style(`⚠ 预设 "${opts.preset}" 不存在。可用：${names}`, C.yellow));
+    } else {
+      presetOverlay = { ...presetConfigOverrides(activePreset), presetName: activePreset.name };
+      if (!opts.model && presetOverlay.model) modelName = presetOverlay.model;
+      presetBlock = presetSystemBlock(activePreset);
+      io.print(style(`▣ 已应用智能体预设：${activePreset.name}${activePreset.label ? '（' + activePreset.label + '）' : ''}`, C.cyan));
+    }
+  }
+  // agent 使用的配置 = cfg + 预设 overlay（presetTools/permission/参数按预设生效，cfg 本体保持干净）
+  const agentCfg = Object.keys(presetOverlay).length ? { ...cfg, ...presetOverlay } : cfg;
 
   const pc0 = resolveProviderConfig(cfg, modelName);
   if (!pc0.apiKey) {
@@ -367,8 +393,13 @@ async function main() {
   }
 
   let provider = await createProvider(cfg, modelName);
-  const permission = createPermission(cfg.permission ?? 'ask', io);
-  const workingDir = process.cwd();
+  const permission = createPermission(agentCfg.permission ?? 'ask', io);
+  // v0.4.0 契约化：挂载 config.tools 声明式第三方工具（幂等，重启生效）
+  {
+    const { mountConfigTools } = await import('./tools/index.js');
+    const mounted = mountConfigTools(cfg);
+    if (mounted.length) io.print(style(`🔧 已挂载声明式工具（config.tools）：${mounted.join(', ')}`, C.dim));
+  }
   // 会话级 undo 备份仓：模型切换、子代理均共享，撤销记录不丢失
   const sessionUndoStore = { backups: new Map() };
   // MCP 服务器：后台启动（不阻塞交互），就绪后工具自动出现在后续轮次
@@ -410,7 +441,7 @@ async function main() {
     io,
     modelName,
     workingDir,
-    cfg,
+    cfg: agentCfg,
     undoStore: sessionUndoStore,
     mcp: mcpFacade,
     sessionRef,
@@ -440,7 +471,7 @@ async function main() {
     const turnIo = jsonMode ? createIO({ quiet: true }) : io;
     const session = createSession(home);
     const messages = [
-      { role: 'system', content: buildSystemPrompt({ modelName, workingDir, withJournal }) },
+      { role: 'system', content: buildSystemPrompt({ modelName, workingDir, withJournal, presetBlock }) },
       { role: 'user', content: question },
     ];
     let oneShotPersisted = messages.length;
@@ -451,7 +482,7 @@ async function main() {
       io: turnIo,
       modelName,
       workingDir,
-      cfg,
+      cfg: agentCfg,
       undoStore: sessionUndoStore,
       mcp: mcpFacade,
       sessionRef: oneShotRef,
@@ -528,7 +559,7 @@ async function main() {
 
   // —— 交互式 TUI（Phase C C2：已抽取至 commands/repl.js） ——
   const { runRepl } = await import('./commands/repl.js');
-  await runRepl({ io, cfg, home, pc0, opts, modelName, provider, permission, workingDir, sessionUndoStore, mcpFacade, mcpManager, sessionRef, agent, preset, withJournal, tuiState });
+  await runRepl({ io, cfg, agentCfg, home, pc0, opts, modelName, provider, permission, workingDir, sessionUndoStore, mcpFacade, mcpManager, sessionRef, agent, preset, withJournal, presetBlock, tuiState });
   return;
 
 }

package/src/commands/repl.js

@@ -98,6 +98,7 @@ const HELP_LINES = [
   ['会话内命令', C.bold + C.yellow],
   ['  /help        显示帮助          /clear   清空上下文', null],
   ['  /model <名>  切换模型          /mode    pro/flash 快捷切换', null],
+  ['  /preset      列出/切换智能体预设（v0.4.0 契约化）', null],
   ['  /compact     压缩上下文        /plan    计划模式（先计划后执行）', null],
   ['  /init        生成 AGENTS.md    /memory add <内容> 追加用户记忆', null],
   ['  /skills      列出技能          /status  会话状态 · /cost 累计费用', null],
@@ -140,6 +141,10 @@ async function generatePlan(provider, modelName, task) {
  */
 export async function runRepl(ctx) {
   const { io, cfg, home, pc0, opts, permission, workingDir, sessionUndoStore, mcpFacade, sessionRef, preset, withJournal, tuiState } = ctx;
+  let presetBlock = ctx.presetBlock || ''; // v0.4.0 Agent Preset 系统提示定制段（/preset 可切换）
+  let permissionNow = permission; // /preset 可换权限模式
+  // v0.4.0 Agent Preset：agent 用 agentCfg（预设 overlay 会话级生效）；cfg 保持干净供 saveConfig 持久化
+  let agentCfg = ctx.agentCfg || cfg;
   let mcpManager = ctx.mcpManager;
   let modelName = ctx.modelName;
   let provider = ctx.provider;
@@ -216,7 +221,7 @@ export async function runRepl(ctx) {
   sessionRef.name = path.basename(session.file);
   io.print(style(`会话  ${path.basename(session.file)}`, C.dim));
 
-  const systemPrompt = buildSystemPrompt({ modelName, workingDir, withJournal });
+  const systemPrompt = buildSystemPrompt({ modelName, workingDir, withJournal, presetBlock });
   // 恢复会话时刷新 system prompt（用户记忆 / AGENTS.md / 技能清单 / 时间戳以当前为准），
   // 旧 system 消息保留在会话文件中，不影响追加历史。
   const loadedMsgs = session.messages || [];
@@ -258,11 +263,11 @@ export async function runRepl(ctx) {
       }
       agent = createAgent({
         provider,
-        permission,
+        permission: permissionNow,
         io,
         modelName,
         workingDir,
-        cfg,
+        cfg: agentCfg, // v0.4.0：预设 overlay 恒生效（/model 后白名单不丢）
         undoStore: sessionUndoStore,
         mcp: mcpFacade,
         sessionRef,
@@ -271,7 +276,7 @@ export async function runRepl(ctx) {
           tuiState.persisted = msgs.length;
         },
       });
-      messages[0] = { role: 'system', content: buildSystemPrompt({ workingDir, withJournal }) };
+      messages[0] = { role: 'system', content: buildSystemPrompt({ workingDir, withJournal, presetBlock }) };
       if (!silent) {
         const p2 = modelPreset(modelName);
         io.print(style(`✓ 已切换到 ${C.bold}${modelName}${C.reset}${p2 ? `（${p2.label}）` : ''}`, C.green));
@@ -309,6 +314,38 @@ export async function runRepl(ctx) {
         } catch {}
         tuiState.persisted = messages.length;
         io.print('已清空上下文（会话文件已同步重置）。');
+      } else if (cmd === '/preset') {
+        // v0.4.0 Agent Preset：列出/切换声明式智能体预设（工具白名单/权限/参数 + 系统提示定制段）
+        const { listPresets, loadPreset, presetConfigOverrides, presetSystemBlock } = await import('../presets.js');
+        if (!arg) {
+          const ps = listPresets(workingDir);
+          if (!ps.length) io.print(style('（无可用预设。目录：<项目>/.mingdao/presets/、~/.mingdao/presets/、内置 presets/）', C.dim));
+          else for (const p of ps) io.print(`  - ${p.name}（${p.label || '无标签'}，${p.source === 'project' ? '项目' : p.source === 'user' ? '用户' : '内置'}）${p.description ? '：' + p.description : ''}`);
+          continue;
+        }
+        const pname = arg.split(/\s+/)[0];
+        const p = loadPreset(workingDir, pname);
+        if (!p) {
+          io.print(style(`预设 "${pname}" 不存在（/preset 列出全部）。`, C.yellow));
+          continue;
+        }
+        const over = presetConfigOverrides(p);
+        // 应用覆盖：权限/参数/工具白名单/模型建议——只进 agentCfg（会话级 overlay），
+        // 绝不改写 cfg：否则后续 /model、/think 的 saveConfig 会把预设字段持久化进 config.json。
+        agentCfg = { ...cfg, ...over, presetName: p.name };
+        if (over.model) await switchToModel(over.model, { silent: true, persist: false });
+        presetBlock = presetSystemBlock(p);
+        permissionNow = createPermission(agentCfg.permission ?? 'ask', io);
+        agent = createAgent({
+          provider, permission: permissionNow, io, modelName, workingDir, cfg: agentCfg,
+          undoStore: sessionUndoStore, mcp: mcpFacade, sessionRef,
+          onCompact: (/** @type {any} */ msgs) => {
+            rewriteSession(session.file, msgs);
+            tuiState.persisted = msgs.length;
+          },
+        });
+        messages[0] = { role: 'system', content: buildSystemPrompt({ workingDir, withJournal, presetBlock }) };
+        io.print(style(`▣ 已应用智能体预设：${p.name}${p.label ? '（' + p.label + '）' : ''}${over.presetTools ? `，工具白名单 ${over.presetTools.length} 个` : ''}`, C.green));
       } else if (cmd === '/model') {
         if (!arg) {
           io.print(`当前模型：${modelName}`);
@@ -336,7 +373,7 @@ export async function runRepl(ctx) {
           saveConfig(cfg);
         } else { io.print(style('无效取值：low|high|max|off', C.red)); continue; }
         agent = createAgent({
-          provider, permission, io, modelName, workingDir, cfg,
+          provider, permission: permissionNow, io, modelName, workingDir, cfg: agentCfg,
           undoStore: sessionUndoStore, mcp: mcpFacade, sessionRef,
           onCompact: (/** @type {any} */ msgs) => {
             rewriteSession(session.file, msgs);

package/src/index.js

@@ -1,13 +1,35 @@
 // MingDao-Harness 公共 API：供第三方程序/插件以库形式复用核心能力。
+// 稳定性契约（v0.4.0 起）：@stable 在 minor 版本内保持向后兼容；@experimental 可能变更。
+// 详细契约与示例见 docs/DEVELOPER.md。
 
+// —— @stable：Agent 内核 ——
 export { createAgent } from './agent.js';
+export { createPermission } from './permissions.js';
+export { createIO, style, C } from './ui.js';
+
+// —— @stable：Provider 与模型 ——
 export { createProvider, resolveProviderConfig } from './providers/index.js';
-export { toolSchemas, dispatch } from './tools/index.js';
+export { MODELS, PROVIDERS, modelPreset, providerPreset } from './models.js';
+export { resolveModelCaps, safeBudget, isLocalBaseUrl } from './model-caps.js';
+
+// —— @stable：工具（含 v0.4.0 第三方注册）——
+export { toolSchemas, dispatch, registerTool, listRegisteredTools, mountConfigTools, buildToolSchemas } from './tools/index.js';
+
+// —— @stable：Agent Preset（v0.4.0）——
+export {
+  listPresets,
+  loadPreset,
+  validatePreset,
+  presetConfigOverrides,
+  presetSystemBlock,
+  presetDirs,
+} from './presets.js';
+
+// —— @stable：上下文与压缩 ——
 export { trimMessages, approxTokens, clampText, TOOL_RESULT_LIMIT } from './context.js';
 export { compactConversation, summarizeConversation } from './compact.js';
-export { createPermission } from './permissions.js';
-export { MODELS, PROVIDERS, modelPreset, providerPreset } from './models.js';
-export { createIO, style, C } from './ui.js';
+
+// —— @stable：配置与凭证 ——
 export {
   mingdaoHome,
   ensureHome,
@@ -26,8 +48,12 @@ export {
   maskKey,
   resolveApiKey,
 } from './credentials.js';
+
+// —— @stable：计价与计量 ——
 export { estimateCost, estimateCostLabel, isPeakHour, PRICE_DATA_AS_OF } from './pricing.js';
 export { countTokens, heuristicTokens, makeTokenCounter, isTokenizable } from './tokenizer.js';
+
+// —— @experimental：更新/审计/技能/会话（接口可能调整）——
 export { updateCheck, mingdaoUpdate, mingdaoRollback, findRepoRoot } from './update.js';
 export { writeAudit, listAudit, redactSecrets, auditFile } from './audit.js';
 export { trustSkill, skillDirHash, readSourceMeta } from './skill-lib.js';

package/src/presets.js

@@ -0,0 +1,154 @@
+// Agent Preset（v0.4.0 契约化）：声明式智能体预设——把「系统提示 + 工具集 + 权限 + 模型 + 参数」
+// 打包成一个可安装、可复用、可分享的 JSON 单元，让开发者/用户不改源码就能定制自己的智能体。
+//
+// 发现顺序（同名后者遮蔽前者）：
+//   1. 项目级  <工作目录>/.mingdao/presets/*.json
+//   2. 用户级  <mingdao-home>/presets/*.json
+//   3. 内置    随 npm 包分发的 presets/ 目录（只读参考实现）
+//
+// 预设字段（全部可选，缺省时保持当前配置不变）：
+//   name          唯一名（必填，字母/数字/-/_，1-64）
+//   label         展示名（可选，默认 name）
+//   description   一句话用途
+//   systemPrompt  追加到系统提示的定制段（角色/规则/上下文约定）
+//   tools         工具白名单（数组，省略=不限制）
+//   permission    权限模式 ask/auto/readonly（省略=当前配置）
+//   model         建议模型（省略=当前模型）
+//   temperature / maxOutputTokens / maxRounds / contextBudget  参数覆盖
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mingdaoHome, ensureHome } from './config.js';
+
+const PRESET_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+// 合法字段白名单：未知字段报错（防拼写错误静默失效——契约化核心）
+const KNOWN_FIELDS = new Set([
+  'name', 'label', 'description', 'systemPrompt', 'tools',
+  'permission', 'model', 'temperature', 'maxOutputTokens', 'maxRounds', 'contextBudget',
+]);
+const PERMISSION_MODES = ['ask', 'auto', 'readonly'];
+
+/** 内置预设目录（随 npm 包分发，只读参考）。 */
+export function builtinPresetDir() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'presets');
+}
+
+/** 发现目录与 source 标签对齐（遮蔽顺序：项目 → 用户 → 内置）。 */
+function presetLocations(/** @type {any} */ workingDir) {
+  const locs = [];
+  if (workingDir) locs.push({ dir: path.join(String(workingDir), '.mingdao', 'presets'), source: 'project' });
+  locs.push({ dir: path.join(mingdaoHome(), 'presets'), source: 'user' });
+  locs.push({ dir: builtinPresetDir(), source: 'builtin' });
+  return locs;
+}
+
+/** @param {any} workingDir 预设发现目录（按遮蔽顺序：项目 → 用户 → 内置）。 */
+export function presetDirs(/** @type {any} */ workingDir) {
+  return presetLocations(workingDir).map((/** @type {any} */ l) => l.dir);
+}
+
+/** @param {any} obj 校验预设对象，返回 { ok, errors: string[] }。 */
+export function validatePreset(/** @type {any} */ obj) {
+  const errors = [];
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return { ok: false, errors: ['预设必须是 JSON 对象'] };
+  const name = String(obj.name ?? '').trim();
+  if (!name) errors.push('缺少 name 字段');
+  else if (!PRESET_NAME_RE.test(name)) errors.push(`name 非法（${PRESET_NAME_RE}）：${name}`);
+  for (const k of Object.keys(obj)) {
+    if (!KNOWN_FIELDS.has(k)) errors.push(`未知字段：${k}（合法：${[...KNOWN_FIELDS].join('/')}）`);
+  }
+  if (obj.systemPrompt !== undefined && typeof obj.systemPrompt !== 'string') errors.push('systemPrompt 必须是字符串');
+  if (obj.tools !== undefined && (!Array.isArray(obj.tools) || obj.tools.some((/** @type {any} */ t) => typeof t !== 'string'))) {
+    errors.push('tools 必须是字符串数组');
+  }
+  if (obj.permission !== undefined && !PERMISSION_MODES.includes(String(obj.permission))) {
+    errors.push(`permission 必须是 ${PERMISSION_MODES.join('/')}`);
+  }
+  for (const k of ['temperature', 'maxOutputTokens', 'maxRounds', 'contextBudget']) {
+    if (obj[k] !== undefined && !(Number.isFinite(Number(obj[k])) && Number(obj[k]) > 0)) {
+      errors.push(`${k} 必须是正数`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * 列出全部可用预设（发现顺序：项目遮蔽用户遮蔽内置，同名只留前者）。
+ * 返回 [{ name, label, description, source: 'project'|'user'|'builtin', file }]
+ */
+export function listPresets(/** @type {any} */ workingDir) {
+  ensureHome();
+  const seen = new Map();
+  const order = /** @type {string[]} */ ([]);
+  for (const { dir, source } of presetLocations(workingDir)) {
+    let files = [];
+    try {
+      files = fs.readdirSync(dir).filter((/** @type {any} */ f) => f.endsWith('.json'));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (seen.has(f)) continue;
+      seen.set(f, { dir, source });
+      order.push(f);
+    }
+  }
+  const out = [];
+  for (const f of order) {
+    const { dir, source } = seen.get(f);
+    try {
+      const obj = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      const v = validatePreset(obj);
+      if (!v.ok) continue; // 非法预设跳过并静默（不阻塞会话）；diagnose 可查
+      out.push({
+        name: String(obj.name),
+        label: String(obj.label || obj.name),
+        description: String(obj.description || ''),
+        source,
+        file: path.join(dir, f),
+        ...(obj.systemPrompt ? { systemPrompt: obj.systemPrompt } : {}),
+        ...(Array.isArray(obj.tools) ? { tools: obj.tools } : {}),
+        ...(obj.permission ? { permission: String(obj.permission) } : {}),
+        ...(obj.model ? { model: String(obj.model) } : {}),
+      });
+    } catch {
+      // JSON 解析失败：跳过
+    }
+  }
+  return out;
+}
+
+/**
+ * 按名解析单个预设（含全部字段），找不到返回 null。
+ * @param {any} workingDir @param {any} name
+ */
+export function loadPreset(/** @type {any} */ workingDir, /** @type {any} */ name) {
+  const all = listPresets(workingDir);
+  const hit = all.find((/** @type {any} */ p) => p.name === name || path.basename(String(p.file), '.json') === name);
+  if (!hit) return null;
+  try {
+    return JSON.parse(fs.readFileSync(hit.file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 预设 → cfg 覆盖：只返回预设声明的参数键（其余键保持调用方当前配置）。
+ * tools 单独走 cfg.presetTools（白名单在 agent 的 toolsFor 处生效）。
+ */
+export function presetConfigOverrides(/** @type {any} */ preset) {
+  const out = /** @type {Record<string, any>} */ ({});
+  for (const k of ['permission', 'model', 'temperature', 'maxOutputTokens', 'maxRounds', 'contextBudget']) {
+    if (preset && preset[k] !== undefined) out[k] = preset[k];
+  }
+  if (preset && Array.isArray(preset.tools)) out.presetTools = [...preset.tools];
+  return out;
+}
+
+/** 预设系统提示定制段（无则空串），插入系统提示 BASE 之后。 */
+export function presetSystemBlock(/** @type {any} */ preset) {
+  const s = preset && typeof preset.systemPrompt === 'string' ? preset.systemPrompt.trim() : '';
+  if (!s) return '';
+  return `\n\n<preset_rules>\n${s}\n</preset_rules>`;
+}

package/src/prompts.js

@@ -30,8 +30,8 @@ function loadFile(/** @type {any} */ p, /** @type {any} */ cap) {
   }
 }
 
-/** @param {{ workingDir: any, withJournal?: boolean, projectMemory?: string, [key: string]: any }} opts */
-export function buildSystemPrompt({ workingDir, withJournal = false, projectMemory }) {
+/** @param {{ workingDir: any, withJournal?: boolean, projectMemory?: string, presetBlock?: string, [key: string]: any }} opts */
+export function buildSystemPrompt({ workingDir, withJournal = false, projectMemory, presetBlock }) {
   // 前缀字节稳定性（评估 P1-1/P1-2，四份评估一致的最高价值项）：
   // 系统提示不含「当前模型」「当前日期」等易变字段——DeepSeek 上下文缓存按前缀字节匹配，
   // 路由 pro⇄flash 翻转或跨天会改变前缀 → 整段历史按未命中价重计（命中价的 30 倍）。
@@ -40,6 +40,9 @@ export function buildSystemPrompt({ workingDir, withJournal = false, projectMemo
 
 当前工作目录：${workingDir}`;
 
+  // v0.4.0 Agent Preset：预设定制的角色/规则段（会话内恒定，前缀稳定）
+  if (presetBlock) prompt += presetBlock;
+
   // 用户级记忆（~/.mingdao/AGENTS.md，/memory add 手动追加 + 会话结束自动提炼）
   const memory = loadFile(path.join(mingdaoHome(), 'AGENTS.md'), 8000);
   if (memory) prompt += `\n\n<user_memory>\n${memory}\n</user_memory>`;

package/src/tasks/worker.js

@@ -53,6 +53,9 @@ export async function runWorkerTask(id, question, { permission, model, offpeak }
     }
     const provider = await createProvider(cfg, modelName);
     const io = createIO({ quiet: true });
+    // v0.4.0 契约化：后台任务同样挂载 config.tools 声明式工具（幂等）
+    const { mountConfigTools } = await import('../tools/index.js');
+    mountConfigTools(cfg);
     const permissionObj = createPermission(perm, io);
     /** @type {any} */
     let mcpManager = null;

package/src/tools/index.js

@@ -6,6 +6,7 @@ import { runBash } from './bash.js';
 import { runGit } from './git.js';
 import { runFetch } from './fetch.js';
 import { listSkills, loadSkill } from '../skills.js';
+import { spawnSync } from 'node:child_process';
 
 // 只读工具集合的单一来源：permissions.js 引用此导出，新增只读工具时只需改这里
 export const READONLY_TOOLS = new Set(['read', 'glob', 'grep', 'ls', 'skill', 'git', 'fetch']);
@@ -245,6 +246,108 @@ export function toolSchemas() {
   return TOOLS;
 }
 
+// —— 第三方工具注册表（v0.4.0 契约化）：程序化 registerTool 注册的自定义工具 ——
+// 与内置工具同一链路：schema 进 buildToolSchemas（省钱剥描述/只读档/预设白名单全适用）、
+// dispatch 执行、审计/权限由 agent 外层统一处理。注册名不得与内置工具同名。
+const customTools = new Map(); // name -> { schema, run }
+const CUSTOM_TOOL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+/**
+ * 注册第三方工具（进程级，重复注册同名会报错——避免静默覆盖）。
+ * @param {{ name: string, description?: string, parameters?: any, run: (args: any, ctx: any) => any | Promise<any> }} tool
+ */
+export function registerTool(/** @type {any} */ tool) {
+  const name = String(tool?.name ?? '').trim();
+  if (!CUSTOM_TOOL_NAME_RE.test(name)) {
+    throw new Error(`自定义工具名非法（${CUSTOM_TOOL_NAME_RE}）：${name}`);
+  }
+  // mcp__ 前缀保留给 MCP 工具（agent 按前缀路由到 mcp.call），自定义工具占用会静默错路由
+  if (name.startsWith('mcp__')) {
+    throw new Error(`自定义工具名不能以 mcp__ 开头（该前缀保留给 MCP 工具）：${name}`);
+  }
+  if (TOOLS.some((/** @type {any} */ t) => t.function.name === name) || customTools.has(name)) {
+    throw new Error(`工具 ${name} 已存在（内置或已注册），不能重复注册`);
+  }
+  if (typeof tool?.run !== 'function') {
+    throw new Error(`自定义工具 ${name} 必须提供 run(args, ctx) 函数`);
+  }
+  const parameters =
+    tool.parameters && typeof tool.parameters === 'object' ? tool.parameters : { type: 'object', properties: {} };
+  const entry = {
+    schema: {
+      type: 'function',
+      function: { name, description: String(tool.description || ''), parameters },
+    },
+    run: tool.run,
+  };
+  customTools.set(name, entry);
+  return entry.schema;
+}
+
+/** 已注册的第三方工具名列表。 */
+export function listRegisteredTools() {
+  return [...customTools.keys()];
+}
+
+/** 第三方工具 schema 列表（与内置 TOOLS 合并进 buildToolSchemas）。 */
+function customToolSchemas() {
+  return [...customTools.values()].map((/** @type {any} */ t) => t.schema);
+}
+
+// —— config.tools 声明式工具挂载（v0.4.0 契约化）——
+// config.json: { "tools": [ { "name": "ping", "description": "...", "parameters": {...}, "command": "..." } ] }
+// command 经 /bin/bash -lc 执行；参数以 MINGDAO_TOOL_ARGS（JSON）环境变量传入——参数不经字符串拼接进
+// shell（防注入），由命令自行解析；执行受 agent 权限引擎门控（与 bash 同权重，权限提示含参数）。
+// 进程级挂载（幂等：同名已挂载则跳过），改 config.tools 需重启生效（与 MCP 预设一致）。
+const mountedConfigTools = new Set();
+
+/**
+ * 把 config.tools 声明式工具挂载进注册表（幂等，可在启动路径重复调用）。
+ * 返回本次新挂载的工具名数组。非法条目（坏名/与内置冲突）跳过不挂载——
+ * 用户配置错误绝不能让 CLI/WebUI 启动崩溃，用 console.error 提示即可。
+ */
+export function mountConfigTools(/** @type {any} */ cfg) {
+  const entries = Array.isArray(cfg?.tools) ? cfg.tools : [];
+  const mounted = [];
+  for (const e of entries) {
+    const name = String(e?.name ?? '').trim();
+    if (!name || mountedConfigTools.has(name)) continue;
+    if (typeof e?.command !== 'string' || !e.command.trim()) continue; // 缺 command 的条目跳过
+    try {
+      registerTool({
+        name,
+        description: String(e.description || ''),
+        parameters: e.parameters,
+        run: (/** @type {any} */ args, /** @type {any} */ ctx) => {
+          const shell = process.platform === 'win32' ? 'cmd.exe' : '/bin/bash';
+          const shellArgs = process.platform === 'win32' ? ['/d', '/s', '/c', e.command] : ['-lc', e.command];
+          const r = spawnSync(shell, shellArgs, {
+            cwd: ctx.cwd,
+            env: { ...process.env, MINGDAO_TOOL_ARGS: JSON.stringify(args ?? {}) },
+            timeout: Math.min(Number(e.timeout) > 0 ? Number(e.timeout) : 120, 600) * 1000,
+            maxBuffer: 2 * 1024 * 1024,
+          });
+          const out = String(r.stdout || '');
+          const err = String(r.stderr || '');
+          const capped = out.length > 20000 ? out.slice(0, 20000) + `\n…[输出过长已截断，共 ${out.length} 字]` : out;
+          return {
+            ok: r.error ? false : (r.status ?? 0) === 0,
+            exitCode: r.error ? null : (r.status ?? null),
+            output: (capped || '（无输出）').trim(),
+            ...(err.trim() ? { stderr: err.trim().slice(0, 4000) } : {}),
+            ...(r.error ? { error: `命令执行失败：${String(r.error?.message || r.error)}` } : {}),
+          };
+        },
+      });
+      mountedConfigTools.add(name);
+      mounted.push(name);
+    } catch (/** @type {any} */ err) {
+      console.error(`[MingDao] ⚠ config.tools 条目 "${name}" 挂载失败（已跳过）：${String(err?.message || err)}`);
+    }
+  }
+  return mounted;
+}
+
 /**
  * 递归去除对象中的全部 description 键（保留类型/required/enum 等结构性字段）。
  * @param {any} obj
@@ -283,7 +386,7 @@ export function buildToolSchemas(usedNames, extra = []) {
       }
       return t;
     });
-  return [...strip(TOOLS), ...strip(extra)];
+  return [...strip(TOOLS), ...strip(customToolSchemas()), ...strip(extra)];
 }
 
 function runSkill(/** @type {any} */ args, /** @type {any} */ ctx) {
@@ -333,6 +436,15 @@ function runTodo(/** @type {any} */ args, /** @type {any} */ ctx) {
 }
 
 export async function dispatch(/** @type {any} */ name, /** @type {any} */ args, /** @type {any} */ ctx) {
+  const custom = customTools.get(name);
+  if (custom) {
+    try {
+      const r = await custom.run(args, ctx);
+      return r && typeof r === 'object' ? r : { ok: true, output: String(r ?? '') };
+    } catch (/** @type {any} */ err) {
+      return { ok: false, error: `自定义工具 ${name} 执行失败：${String(err?.message || err)}` };
+    }
+  }
   switch (name) {
     case 'read':
       return read(args, ctx);

package/src/web/app.js

@@ -345,6 +345,9 @@ async function send(){
   arm();
   input.value=''; input.style.height='44px';
   const payload={message:text,file:currentSession};
+  // v0.4.0 Agent Preset：选择器选中的预设随本轮发送（服务端按会话应用一次）
+  const presetVal=$('#presetSel')?.value;
+  if(presetVal) payload.preset=presetVal;
   // 带上文开关：勾选后系统提示注入最近会话日志（默认不注入——新会话全新开始，避免串到历史会话上下文）
   if($('#journalChk')?.checked) payload.withJournal=true;
   if(attachments.length) payload.attachments=attachments;
@@ -647,6 +650,11 @@ async function init(){
   }
   refreshSessions();
   refreshWsSel();
+  try{
+    // v0.4.0 Agent Preset：加载预设列表进下拉（项目 → 用户 → 内置）
+    const pr=await fetch('/api/presets',{cache:'no-store'}).catch(()=>null); const pj=pr?await pr.json():{presets:[]};
+    const psel=$('#presetSel'); if(psel&&pj.presets){ for(const p of pj.presets){ const o=document.createElement('option'); o.value=p.name; o.textContent=p.label+'（'+(p.source==='project'?'项目':p.source==='user'?'用户':'内置')+'）'; o.title=p.description||p.name; psel.appendChild(o); } }
+  }catch(e){}
   try{
     const dr=await fetch('/api/draft?file='+encodeURIComponent(currentSession||''),{cache:'no-store'}); const dj=await dr.json();
     if(dj.text){ input.value=dj.text; input.style.height=Math.min(input.scrollHeight,200)+'px'; input.focus(); }

package/src/web/index.html

@@ -57,6 +57,7 @@ header button{white-space:nowrap;flex:none}
 header select{flex:none}
 #sessionSearch{flex:1 1 auto;min-width:70px;max-width:220px;background:var(--bg3);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:6px 12px;font-size:13px}
 #modelSel{max-width:170px;min-width:0}
+#presetSel{max-width:140px;min-width:0}
 #permSel{max-width:150px;min-width:0}
 #sessions{max-width:150px;min-width:0}
 #wsSel{max-width:130px;min-width:64px}
@@ -197,11 +198,12 @@ footer{flex:none;border-top:1px solid var(--border);background:var(--bg2);paddin
 #composer #permSel{max-width:96px;min-width:64px;flex:none;padding:8px 8px}
 #composer #reasoningSel{max-width:64px;min-width:48px;flex:none;padding:8px 6px;font-size:12px}
 #composer #modelSel{max-width:150px;min-width:88px;flex:none;padding:8px 8px;font-size:12px}
+#composer #presetSel{max-width:130px;min-width:76px;flex:none;padding:8px 8px;font-size:12px}
 #input{flex:1;background:var(--bg3);border:1px solid var(--border);border-radius:12px;color:var(--text);padding:10px 14px;font:14px/1.6 inherit;resize:none;min-height:44px;max-height:200px;min-width:0}
 #input:focus{outline:none;border-color:var(--accent2)}
 #hint{font-size:11.5px;color:var(--faint);margin-top:6px;max-width:860px;margin-left:auto;margin-right:auto}
 #statusBar{font-size:11.5px;color:var(--faint);margin-top:2px;max-width:860px;margin-left:auto;margin-right:auto;font-variant-numeric:tabular-nums;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
-@media (max-width:560px){footer{padding:10px 8px}#composer{gap:6px}#composer #permSel{min-width:52px;padding:8px 4px}#composer #reasoningSel{min-width:44px;padding:8px 4px}#composer #modelSel{min-width:72px;padding:8px 4px}#attachBtn{padding:10px 9px}}
+@media (max-width:560px){footer{padding:10px 8px}#composer{gap:6px}#composer #permSel{min-width:52px;padding:8px 4px}#composer #reasoningSel{min-width:44px;padding:8px 4px}#composer #modelSel{min-width:72px;padding:8px 4px}#composer #presetSel{min-width:64px;max-width:88px;padding:8px 4px}#attachBtn{padding:10px 9px}}
 .modal-mask{position:fixed;inset:0;background:rgba(0,0,0,.55);display:flex;align-items:center;justify-content:center;z-index:50}
 .modal{background:var(--panel);border:1px solid var(--border);border-radius:14px;width:min(520px,92vw);padding:18px;max-height:88vh;overflow-y:auto}
 /* 设置多级菜单（审计：一拉到底改为左侧分组导航 + 右侧面板） */
@@ -330,6 +332,7 @@ footer{flex:none;border-top:1px solid var(--border);background:var(--bg2);paddin
       <option value="readonly">只读</option>
     </select>
     <select id="modelSel" title="切换模型"></select>
+    <select id="presetSel" title="智能体预设：一键切换工具白名单/权限/参数组合（v0.4.0 契约化）"><option value="">预设…</option></select>
     <select id="reasoningSel" title="思考模式（推理等级）：关＝不推理省 token · 低 · 高（默认）· 最高＝最强推理" style="display:none">
       <option value="off">关</option>
       <option value="low">低</option>

package/src/web/routes/domains/misc.js

@@ -3,6 +3,7 @@
 import { loadMemory, writeMemory, dedupeMemory } from '../../../memory.js';
 import { recordUsage, listCacheStats, summarizeCacheStats, costBreakdown } from '../../../cachestats.js';
 import { costGuardStatus } from '../../../cost-guard.js';
+import { listPresets } from '../../../presets.js';
 
 /**
  * 杂项域路由。命中返回 true，未命中返回 false。
@@ -100,6 +101,13 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
     return true;
   }
 
+  // v0.4.0 Agent Preset：列出可用预设（项目 → 用户 → 内置，同名遮蔽）
+  if (method === 'GET' && p === '/api/presets') {
+    const workingDir = deps.state?.workingDir || process.cwd();
+    json(res, 200, { ok: true, presets: listPresets(workingDir) });
+    return true;
+  }
+
   if (method === 'POST' && p === '/api/memory') {
     const body = await readBody(req, MAX_API_BODY);
     if (body.action === 'dedupe') {

package/src/web/server.js

@@ -194,6 +194,13 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   const provider = await getProviderFor(modelName);
   const undoStore = { backups: new Map() };
 
+  // v0.4.0 契约化：挂载 config.tools 声明式第三方工具（幂等，重启生效）
+  {
+    const { mountConfigTools } = await import('../tools/index.js');
+    const mounted = mountConfigTools(cfg);
+    if (mounted.length) console.error(`[MingDao] 🔧 已挂载声明式工具（config.tools）：${mounted.join(', ')}`);
+  }
+
   // MCP：A2 预热——await 连接（6s 超时）；超时本会话冻结工具集（不再中途注入，保护前缀缓存）
   /** @type {any} */
   let mcpManager = null;
@@ -408,7 +415,24 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         sessionMemoryCache.delete(oldest);
       }
     }
-    const systemPrompt = buildSystemPrompt({ workingDir: taskDir, withJournal: body.withJournal === true, projectMemory: projectMemorySnapshot });
+    // v0.4.0 Agent Preset：body.preset 按会话一次选定（新会话或显式传值）；应用工具白名单/参数覆盖，
+    // 系统提示注入预设定制段。预设覆盖优先级：CLI/WebUI 显式 > 预设 > config.json。
+    let chatPreset = /** @type {any} */ (null);
+    let presetBlock = '';
+    let chatCfg = cfg;
+    if (typeof body.preset === 'string' && body.preset) {
+      const { loadPreset, presetConfigOverrides, presetSystemBlock } = await import('../presets.js');
+      chatPreset = loadPreset(taskDir, body.preset);
+      if (chatPreset) {
+        const over = presetConfigOverrides(chatPreset);
+        chatCfg = { ...cfg, ...over, presetName: chatPreset.name };
+        presetBlock = presetSystemBlock(chatPreset);
+      } else {
+        // 预设不存在：不静默——banner 告知（前端下拉与磁盘不同步/项目级预设未带入时可见）
+        send({ type: 'banner', text: `⚠ 预设 "${String(body.preset)}" 不存在，已按当前配置继续。` });
+      }
+    }
+    const systemPrompt = buildSystemPrompt({ workingDir: taskDir, withJournal: body.withJournal === true, projectMemory: projectMemorySnapshot, presetBlock });
     let messages =
       session.messages?.length && session.messages[0]?.role === 'system'
         ? session.messages
@@ -448,7 +472,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         entry.abortHandler = fn;
       },
     }));
-    const permission = createPermission(cfg.permission ?? 'ask', io);
+    const permission = createPermission(chatCfg.permission ?? 'ask', io);
     let providerNow;
     try {
       // 首次使用引导：未配置密钥时给明确指引，而不是晦涩的 401 原始报错
@@ -471,7 +495,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
       io,
       modelName: runModel,
       workingDir: taskDir,
-      cfg,
+      cfg: chatCfg, // v0.4.0：预设覆盖后的配置（工具白名单 presetTools/参数/权限）
       undoStore,
       mcp: mcpFacade,
       // 自动压缩后重写会话文件（否则每次加载历史都会重新触发压缩），并同步落盘游标