MingDao Harness 使用指南

从安装到精通：三步上手 → 三端使用 → 能力全景 → 省钱工程落地 → 智能体预设 → 扩展能力。

第一步：安装

方式 A · 桌面版（推荐）：官网「下载桌面版」选择对应平台安装包，双击安装即可——首次运行自动初始化，进入界面后在 ⚙ 设置里填入 API Key 即可对话。

方式 B · 全局 CLI（Node ≥ 18.17）：

npm install -g mingdao-harness   # 之后 mingdao / mdh 即可用；升级：npm update -g mingdao-harness

方式 C · 源码：

git clone https://gitee.com/MingDaoTCM/MingDao-harness.git MingDao-Harness && cd MingDao-Harness
node src/cli.js        # 直接运行，无需构建

第二步：初始化配置（`mingdao init`）

交互式向导按「① 选服务商 → ② 填 API Key（自动验证有效性）→ ③ 选模型（可跳过）」进行：选定服务商后立即输入该服务商的 API Key，系统会调用 /models 接口验证密钥并把线上可用模型列出来供你选择；模型也可以暂时跳过，进入后随时用 /model 切换。

mingdao init
mingdao key set deepseek   # 单独补录/更换密钥
mingdao key list           # 查看已配置的服务商

密钥保存在独立凭证库（~/.mingdao/credentials.json，600 权限），绝不写入 config.json，可放心分享配置。解析优先级：环境变量 > 凭证库 > 配置字段。

第三步：开始对话

mingdao                              # 交互式 TUI（Tab 补全、/help 查看命令）
mingdao "帮我写一个贪吃蛇游戏"        # 单次提问
mingdao web                          # WebUI（浏览器打开 http://127.0.0.1:3820）
mingdao --resume                     # 恢复历史会话

三端使用

🖥 TUI（终端）

/plan 先计划后执行 · /compact 压缩上下文 · /memory add <内容> 长期记忆
/model 切换模型 · /mode 权限模式 · /cost 费用分账 · /cache 缓存命中率仪表盘
/skill 技能系统 · /sessions 会话管理 · /audit 工具调用审计

🌐 WebUI / PWA

流式思考实况、工具卡片、权限确认弹窗、会话搜索、任务面板（多会话并行）
可安装为 PWA（浏览器地址栏「安装」），图标与桌面版统一
设置面板：模型与 API Key、权限/沙箱、自动路由、云同步（默认 https://session.mingdao.ai/，注册即用）、调度任务、技能库

🪟 桌面版（Electron）

托盘常驻、窗口状态记忆、随机端口 + 一次性令牌、权限全拒、自动更新（官网 feed，国内直连）
首次运行自动初始化并引导在界面内配置 Key；关闭窗口最小化到托盘

🧩 IDE（VS Code / JetBrains）

插件开箱即用（ide/vscode），选中代码直接发问，答案写回编辑器。

能力全景（各模块怎么用）

能力	作用	怎么用
内置工具 ×13	读写文件、跑命令、查代码、联网抓取	`read/write/edit/ls/glob/grep/bash/git/fetch/todo/task/undo/skill` 由模型自动调用；`git` 只读子命令、`fetch` 公网只读（SSRF 防护）
Agent Preset 预设	声明式定制智能体（系统提示+白名单+权限+模型）	`mingdao --preset 名` / REPL `/preset` / WebUI 下拉；JSON 见下方
第三方工具	注册自己的工具（程序化 / 声明式）	`registerTool()` 或 `config.tools`；见下方
MCP 生态	接入 Model Context Protocol 服务器	`config.mcpServers` + `mingdao mcp preset list/add`；会话内 `/mcp`
技能库	可安装、可分享的领域技能（含完整性校验）	`mingdao skill search\|install\|update\|trust`；REPL `/skills`
项目记忆	每个项目沉淀「决定/事实/教训」，换会话不重来	自动写 `.mingdao/memory.md`；`/memory add` 手动追加；`/init` 生成 AGENTS.md
会话 / 续跑	长任务跑满步数自动续跑、断点恢复	`--continue` / `--resume` / WebUI「带上文」；已完成文件不重做
工作空间	多项目目录登记与快速切换	`mingdao workspace add\|list\|use\|path\|remove`；每个会话记住自己的目录
云同步	会话跨设备同步、多人协作	`mingdao sync login\|push\|pull\|share`；自建 `mingdao sync-server`
调度任务	后台任务 + 定时/依赖编排	`mingdao run "任务"` / `schedule add\|chain\|pause`
一键诊断	生成脱敏诊断包，贴给反馈即查	`mingdao diagnose`（含「当前模型能力」报告）
审计 / 权限 / 沙箱	每次工具调用落审计、权限门控、可选沙箱	`mingdao audit` / `permission: ask\|auto\|readonly` / `sandbox: off\|readonly\|safe`

省钱工程：怎么用才真正省钱

核心原理：DeepSeek 上下文缓存按前缀字节匹配，命中价是未命中的 1/30。MingDao 保证系统提示前缀恒定，并围绕它构建了整套省钱体系——省钱的杠杆大多无需手动操作（Schema 瘦身、只读阶段、前缀稳定是内核自动做的），你只需掌握下面几个「开关」。

① 缓存命中计价（省 84.5%，内核自动）

只要会话前缀稳定，后续每轮的 prompt 前缀就能命中缓存、按 1/30 计价。MingDao 已自动保证系统提示字节恒定、Schema 两态冻结、压缩按滞回缓冲。你只需：

同一任务尽量在同一个会话里做完——频繁新开会话 = 前缀重新积累 = 每轮都按未命中全额计费。
长任务用 --continue / --resume 续跑，而不是重开一个会话从头再来。
会话内 /cache 看命中率；命中率越高，这一轮越省。

② 自动路由 pro⇄flash（日常省 30–50%）

pro 贵但强，flash 便宜但够用——MingDao 用 pro 做规划、flash 做执行。怎么开：

mingdao init          # 向导里开启自动路由
/route on             # 会话内开关
# 配置：routing.enabled=true（WebUI 设置「自动路由」开关）

粘滞 flash 会话复杂度上升时，会自动升级回 planner（routing.upgradeSteps/upgradeTruncated 可调阈值）。没有复杂规划需求的任务，强制关掉 pro 最省：/mode flash 或 /route off。

③ 避峰调度（高峰输入价 2 倍 → 闲时半价）

高峰时段（北京时间工作日 9:00–12:00、14:00–18:00）输入价是闲时的 2 倍。让非紧急任务顺延到闲时：

mingdao run "跑测试并修红" --offpeak      # 后台任务：高峰自动顺延到最近闲时
mingdao schedule add "每日总结" --every 24h --offpeak   # 定时任务同样避峰

WebUI 调度面板勾选「🌙 避峰执行」。周末与午间 12:00–14:00 按闲时计价。

④ Batch 半价（省 50%）

成批的单轮、无工具、无流式任务（如批量总结、批量翻译、批量打标签）走批处理通道，半价且不计时：

mingdao batch 任务清单.txt    # 每行一个任务
cat 问题.txt | mingdao batch -   # 从管道读

结果落 mingdao-batch-result-<时间戳>.jsonl 并计入 /cost 分账（batch 标记）。注意：批处理不支持工具调用，只适合问答/生成类任务。

⑤ 思考强度分级（关掉思考最省推理 token）

推理 token 也是钱。DeepSeek-V4 pro 支持 off/low/high/max 四档：

/think                # REPL 切换思考强度
# 配置（按模型独立）：
{ "reasoningByModel": { "deepseek-v4-pro": "low", "deepseek-v4-flash": "off" } }

简单任务用 off 显式关思考（flash 默认不发 reasoning_effort）；复杂推理才上 high/max。

⑥ 费用护栏（绝不超支）

按北京时间自然日累计真实费用（含缓存折扣与 Batch 半价），每轮开始前检查：

{
  "costGuard": { "dailyLimitYuan": 10, "warnAtYuan": 8, "action": "block" }
}

action: "warn"（默认）超限仅提醒；"block" 到顶暂停（明天自动恢复）；"downgrade" 触顶自动切更便宜的 flash 继续。
WebUI 头部费用徽标实时显示「今日费用 / 上限百分比」。

⑦ 观测与分账（省了要知道省了多少）

/cost                          # 会话内：按模型分账 + 缓存命中 + Batch 半价真实口径
mingdao cost report 2026-09     # 月度 Markdown 报告（按模型分账/每日柱状图/命中率）

⑧ 本地模型自适应（私有化部署专属省钱）

本机/内网推理框架自动按「资源有限」对待：上下文预算收紧到 窗口×75% 舒适区、工具结果按 窗口/16 截断、分层超时（本地慢 prefill 不被误杀）。本地模型请显式声明能力：

{
  "customModels": {
    "local-qwen": { "label": "本机 Qwen", "baseUrl": "http://127.0.0.1:8081/v1",
                    "contextWindow": 131072, "maxOutputTokens": 8192 }
  }
}

WebUI 设置 → 自定义模型「修改」可直接改 API 地址 / 标签 / 上下文窗口 / 最大输出（留空不变）。未声明 contextWindow 时本地兜底 32k（输出/预算会被压缩），mingdao diagnose 的「当前模型能力」会提示后果。

智能体预设（Agent Preset）

一个 JSON 文件 = 系统提示定制段 + 工具白名单 + 权限 + 模型 + 参数，不改一行代码定制智能体。放在三个位置（同名后者覆盖前者）：项目 .mingdao/presets/<名>.json → 用户 ~/.mingdao/presets/<名>.json → 内置。

{
  "name": "code-reviewer",
  "label": "代码审查员",
  "description": "只读审查并输出分级报告",
  "systemPrompt": "你是代码审查员。只读审查，按严重度分级输出，每条带文件:行号证据。",
  "tools": ["read", "ls", "glob", "grep", "skill", "git", "fetch", "todo"],
  "permission": "auto",
  "model": "deepseek-v4-flash",
  "maxRounds": 4
}

CLI：mingdao --preset code-reviewer "审查 src/ 目录"；交互 mingdao --preset code-reviewer
REPL：/preset 列出全部；/preset code-reviewer 会话内切换（即时生效）
WebUI：输入框旁「预设…」下拉选择（随本次发送生效）

安全：预设 tools 白名单外工具对模型不可见、调用被硬拦；预设声明的 permission 若比当前更宽松（ask→auto）会被忽略并提示——克隆恶意仓库不能静默跳过你的确认。

扩展能力：第三方工具 · MCP · 技能 · 云同步

第三方工具（registerTool / config.tools）

// 程序化注册（嵌入自己程序时）——详见「API 文档」
import { registerTool } from 'mingdao-harness';
registerTool({ name: 'weather', description: '查天气', parameters: {...}, run: async (args) => {...} });

// 声明式挂载（config.json，不改代码）：shell 命令包装成工具
{ "tools": [ { "name": "date-now", "description": "当前时间", "command": "date" } ] }

声明式工具的参数以 MINGDAO_TOOL_ARGS（JSON）环境变量传入（防注入）；执行走统一权限门控。

MCP 服务器

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/你的/目录"],
                    "trusted": true }
  }
}

格式与 Claude Code 相同，工具以 mcp__<服务器>__<工具> 并入。v0.4.1 起：只读自动放行仅信任带 trusted:true 的服务器，未授信服务器谎报只读也走确认。

技能库与云同步

mingdao skill search|install|update|trust <名称>   # 技能（sha256 完整性校验）
mingdao sync login|push|pull|share|conflicts        # 跨设备会话（session.mingdao.ai）
mingdao sync-server [端口]                          # 自建同步服务端

常用命令速查

命令	说明
`mingdao init`	初始化向导（服务商 → Key 验证 → 模型 → 自动路由）
`mingdao key set\|list\|remove`	凭证管理（独立凭证库）
`mingdao web [端口] [--auth-token 令牌]`	WebUI；绑定局域网时强制令牌认证
`mingdao --preset 名` / `--model 名`	应用预设 / 指定模型
`mingdao run "任务" [--offpeak]`	后台任务（可避峰）
`mingdao schedule add\|list\|remove\|pause\|resume\|chain`	定时任务与依赖编排
`mingdao batch 文件.txt`	批处理半价（每行一任务）
`mingdao cost report [月\|all]` / `audit [n]`	月度费用报告 / 审计日志
`mingdao diagnose`	一键诊断（脱敏打包，含模型能力报告）
`mingdao sync login\|push\|pull\|share`	云同步
`mingdao skill search\|install\|trust`	技能库
`mingdao update` / `rollback`	自更新 / 回滚

常见问题

没有 API Key？到 DeepSeek 开放平台（platform.deepseek.com）注册并创建 Key，然后在 mingdao init 或 WebUI ⚙ 设置里填入。

安装提示？macOS：v0.2.5 起已由 Apple Developer ID 签名并公证，下载后双击直接打开。Windows：桌面版尚未代码签名，首次运行若出现 SmartScreen 提示，点「更多信息 → 仍要运行」即可。

本地模型输出截断 / 子代理没反应？多为模型未声明 contextWindow 或 routing 派发问题（v0.4.1 已修复）。先跑 mingdao diagnose 看「当前模型能力」，再在 WebUI 自定义模型里补上上下文窗口。

遇到问题去哪反馈？欢迎到「社区论坛」提交反馈，或直接在 GitHub/Gitee 仓库提 Issue。

MingDao Harness 使用指南

第一步：安装

第二步：初始化配置（mingdao init）

第三步：开始对话

三端使用

🖥 TUI（终端）

🌐 WebUI / PWA

🪟 桌面版（Electron）

🧩 IDE（VS Code / JetBrains）

能力全景（各模块怎么用）

省钱工程：怎么用才真正省钱

① 缓存命中计价（省 84.5%，内核自动）

② 自动路由 pro⇄flash（日常省 30–50%）

③ 避峰调度（高峰输入价 2 倍 → 闲时半价）

④ Batch 半价（省 50%）

⑤ 思考强度分级（关掉思考最省推理 token）

⑥ 费用护栏（绝不超支）

⑦ 观测与分账（省了要知道省了多少）

⑧ 本地模型自适应（私有化部署专属省钱）

智能体预设（Agent Preset）

扩展能力：第三方工具 · MCP · 技能 · 云同步

第三方工具（registerTool / config.tools）

MCP 服务器

技能库与云同步

常用命令速查

常见问题

第二步：初始化配置（`mingdao init`）