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），选中代码直接发问，答案写回编辑器。
省钱工程速览
核心原理：DeepSeek 上下文缓存按前缀字节匹配，命中价是未命中的 1/30——MingDao 保证系统提示前缀恒定，并围绕它构建了整套省钱体系。
| 能力 | 用法 | 省多少 |
|---|---|---|
| 自动路由 | mingdao init 开启（规划→pro，执行→flash） | 平均 30-50% |
| 避峰调度 | 调度任务勾选 🌙 避峰 / mingdao run --offpeak | 高峰价 50% |
| Batch 半价 | mingdao batch 任务清单.txt（每行一个任务） | 50% |
| 费用护栏 | config.json → costGuard { dailyLimitYuan, warnAtYuan, action } | 防爆金币 |
| 精确分账 | /cost 按模型分账（含缓存折扣与 Batch 半价真实口径） | 可观测 |
常用命令速查
| 命令 | 说明 |
|---|---|
mingdao init | 初始化向导（服务商 → Key 验证 → 模型） |
mingdao key set|list|remove | 凭证管理（独立凭证库） |
mingdao web [端口] [--auth-token 令牌] [--autostart|--no-autostart] | WebUI；可设开机/随 mingdao 自动启动 |
mingdao desktop | 任意目录启动桌面版（仓库形态） |
mingdao run "任务" / mingdao schedule add "任务" --every 10m | 后台任务 / 周期调度（单守护进程） |
mingdao skill search|install|update|trust | 技能库（三镜像自动回退） |
mingdao sync login|push|pull|share|conflicts | 云同步（session.mingdao.ai） |
mingdao update / mingdao rollback | 自更新 / 回滚（升级后冒烟失败自动回滚） |
mingdao batch / cost / audit | 批处理半价 / 月度费用报告 / 审计日志 |
常见问题
没有 API Key？到 DeepSeek 开放平台（platform.deepseek.com）注册并创建 Key，然后在
mingdao init 或 WebUI ⚙ 设置里填入。Windows SmartScreen / macOS 未公证提示？桌面版为未签名构建——SmartScreen 点「更多信息 → 仍要运行」；macOS 在「系统设置 → 隐私与安全性」点「仍要打开」。证书到位后会自动接入签名。
遇到问题去哪反馈？欢迎到「社区论坛」提交反馈，或直接在 GitHub/Gitee 仓库提 Issue。