mingdao-harness 0.1.54

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MingDao-Harness Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# MingDao-Harness（明道）
+
+> 开源智能体框架（Agent Harness）：**零运行时依赖、开箱即用**，针对 DeepSeek-V4 首发深度优化，开放主流模型接入。一条命令安装，终端与浏览器双界面，命令：`mingdao`（简写 `mdh`）。
+
+轻量的「模型循环 + 工具 + 权限」内核，能力以 ESM 库导出、接口全部开放。架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
+
+## 为什么选 MingDao
+
+- ⚡ **真正的零依赖**：纯 Node.js ≥ 18，无任何 npm 运行时依赖、无构建步骤——装完即用，不拖 node_modules
+- 💰 **DeepSeek-V4 深度省钱**：384K 上下文预设、**缓存命中计价**（命中价仅为未命中的 1/30）+ 命中率仪表盘、峰谷计价（周末全天低价自动识别）、自动路由（pro 规划 / flash 执行 + 分类缓存 + 会话粘滞）、精确 tokenizer（官方词表 BPE）、滞回自动压缩、**Batch API 半价批处理**（`mingdao batch`）、**避峰调度**（`--offpeak` 高峰顺延 14:00 后）、**费用护栏**（每日上限防超支）
+- 🖥 **双界面 + IDE 全家桶**：产品级 TUI（流式 Markdown、代码高亮、编辑 diff、Ctrl+C 中断、Tab 补全）与 `mingdao web` 一键 WebUI（PWA 可装桌面、多任务并行、全项设置面板）；VS Code 侧边栏与 JetBrains 工具窗深度集成
+- 🧠 **36 个技能开箱即用**：14 个内置常驻 + 22 个可安装技能库（线上 registry 逐文件 sha256 校验防供应链篡改，`mingdao skill install sql` 一键装，可自建企业内 registry）
+- 🔌 **生态即插即用**：MCP 客户端（零依赖实现，`mcpServers` 配置即接入任意 MCP 服务器）+ Hooks 钩子 + 9 个 MCP 生态预设
+- ☁️ **云同步与多用户协作**：跨设备会话同步、分享码协作、跨设备冲突图形化三选一；服务端零依赖单文件，一台 Linux 服务器即可自建
+- 🛡 **安全默认**：权限三档（ask/auto/readonly）+ 工具级规则、bash 沙箱三档（bubblewrap）、API Key 与配置分离（绝不进仓库）、附件/正则/路径全部有界、**工具调用审计日志**（`mingdao audit` 追溯每次执行与拒绝）
+- 🖼 **多模态**：DeepSeek-V4-Flash-Vision-Exp 视觉模型内置，WebUI 直接上传图片；模型列表以官方 `/models` 线上名单为准，新模型发布自动出现
+- ♻ **长会话不丢上下文**：超预算自动压缩——早期段落由 executor 模型压成摘要注入（`/compact` 可手动），绝不静默失忆
+- 🔎 **历史会话秒搜**：增量索引全文检索（中文 bigram 分词，`mingdao sessions search` / WebUI 搜索框共用）；WebUI **会话级工作空间**——每个会话记住自己的项目目录，多任务并行互不串目录
+- 🌍 **真·跨平台**：Linux / macOS / Windows 全程实测，三平台 CI 矩阵（Ubuntu 18/20/22 + Windows + macOS）常驻守护，Windows 下 journal/测试全绿
+
+## 快速开始（3 步）
+
+```bash
+mingdao init                          # ① 向导：选服务商/模型 → 填 API Key → 选权限与沙箱
+mingdao                               # ② 开始对话
+mingdao web                           # ③ 或浏览器界面 http://127.0.0.1:3820
+```
+
+常用一行式：
+
+```bash
+mingdao "用 Python 写一个快速排序"      # 单次提问（脚本/管道友好）
+mingdao --format json "问题"           # JSON 结构化输出（机器集成）
+mingdao --continue                    # 继续最近会话 · --resume 从列表恢复
+mingdao --model deepseek-v4-pro       # 指定模型
+```
+
+API Key 从 [DeepSeek 开放平台](https://platform.deepseek.com) 获取。密钥只存本机凭证库（权限 600），不写入仓库与配置文件。
+
+## 安装指南
+
+### 任意平台（npm）
+
+```bash
+npm install -g mingdao-harness   # 之后 mingdao / mdh 即可用（升级：npm update -g mingdao-harness）
+```
+
+### Linux / macOS
+
+一行安装（自动装 Node 并安装 `mingdao` 命令）。**三平台内容完全一致——你在哪个平台浏览，就用哪一行**（Gitee / GitCode 国内速度快，GitHub 面向海外）：
+
+```bash
+# Gitee（国内推荐）
+curl -fsSL https://gitee.com/MingDaoTCM/MingDao-harness/raw/main/install.sh | bash -s -- gitee
+
+# GitCode（国内推荐；其 raw 接口对 curl 有反爬拦截，改用克隆式）
+git clone https://gitcode.com/MingDaoTCM/MingDao-Harness.git MingDao-Harness && cd MingDao-Harness && bash install.sh
+
+# GitHub（海外）
+curl -fsSL https://raw.githubusercontent.com/MingDaoTCM/MingDao-Harness/main/install.sh | bash -s -- github
+```
+
+> 若某平台的 raw 脚本下载被反爬拦截，把 `| bash` 换成克隆式安装即可（见下方「手动克隆」）。
+
+或手动克隆（建议在本平台克隆，速度最快；目录名统一为 `MingDao-Harness`）：
+
+```bash
+git clone https://gitee.com/MingDaoTCM/MingDao-harness.git MingDao-Harness     # Gitee
+git clone https://gitcode.com/MingDaoTCM/MingDao-Harness.git MingDao-Harness  # GitCode
+git clone https://github.com/MingDaoTCM/MingDao-Harness.git MingDao-Harness   # GitHub
+cd MingDao-Harness && bash install.sh
+```
+
+- 无管理员权限时自动安装到 `~/.local/bin`；装完 `mingdao init` 开始使用
+- 卸载：删除 `mingdao` / `mdh` 命令即可，数据目录 `~/.mingdao/` 按需保留
+
+### Windows 10 / 11
+
+1. 在本平台克隆或下载本项目并解压（上方三条克隆地址任选其一，国内建议 Gitee / GitCode）；
+2. 双击 `install.bat`（自动经 winget 安装 Node.js，无需管理员权限）；
+3. 运行 `mingdao init` → `mingdao`。
+
+说明：`bash` 工具自动使用 `cmd.exe`；配置目录 `C:\Users\<用户名>\.mingdao\`；推荐 Windows Terminal / PowerShell 7 获得最佳彩色显示。
+
+### 桌面版（Electron）
+
+```bash
+npm run desktop          # 源码直跑（自动启动内置 WebUI 并打开窗口）
+npm run desktop:dist     # 打包为未压缩可运行目录（desktop/dist/linux-unpacked/）
+```
+
+三平台安装包（Windows NSIS / macOS dmg / Linux AppImage+deb）由 GitHub Actions `desktop.yml`
+在打 tag 时自动构建；本地用 `cd desktop && npm run dist:win|dist:mac|dist:linux` 手动构建。
+
+### 从源码运行（开发）
+
+```bash
+git clone https://gitee.com/MingDaoTCM/MingDao-harness.git MingDao-Harness && cd MingDao-Harness   # 其余平台见上方「手动克隆」
+node src/cli.js        # 直接运行，无需安装
+```
+
+### 验证安装
+
+```bash
+mingdao --version      # 显示版本号即成功
+node -v                # 需 ≥ 18.17
+```
+
+## 使用指南
+
+### 终端会话
+
+会话内命令（输入 `/help` 查看全部）：`/model <名>` 切模型 · `/mode pro|flash` 快捷切换 · `/compact` 手动压缩上下文（超预算时另有**自动压缩**：早期段落被 executor 模型压成摘要注入，替代静默丢弃） · `/plan` 先计划后执行 · `/memory add <内容>` 长期记忆 · `/skills` 技能列表 · `/sessions` 历史检索 · `/status` `/cost` `/cache` 状态与费用 · `/mcp` MCP 状态 · `/route` 自动路由开关 · `/exit` 退出。支持 Tab 补全、↑↓ 历史、Ctrl+C 中断、行尾 `\` 多行输入。
+
+### 后台任务与调度
+
+```bash
+mingdao run "重构 src 下的工具层" --permission auto   # 后台任务（独立进程）
+mingdao tasks / tasks watch / tasks kill <id>        # 任务面板
+mingdao schedule add "生成周报" --at "2026-08-21 09:00"   # 定时一次
+mingdao schedule add "同步数据" --every 2h                # 周期（可 --anchor 09:00 每日锚点）
+mingdao schedule chain "构建" "测试" "部署"               # 链式依赖
+mingdao schedule list/remove/pause/resume               # 管理；重启自愈
+```
+
+### 自更新（`mingdao update`）
+
+```bash
+mingdao update          # 一键升级：从 Gitee/GitCode/GitHub 三镜像取最新（哪个可达用哪个）→ 自动跑冒烟测试 → 失败自动回滚
+mingdao update --check  # 只对比版本，不改动工作区
+mingdao rollback        # 回滚到上次 update 之前的提交（升级验证失败也可一键退回）
+```
+
+git 安装形态（仓库 + 全局链接）开箱即用；npm 形态按提示用 `npm update -g` 升级。
+
+### WebUI（`mingdao web`）
+
+- 流式对话：Markdown 渲染、代码高亮、编辑 diff、工具卡片、思考实况、实时滚动
+- **上传入口**：输入框 📎 上传图片（视觉模型，如 `deepseek-v4-flash-vision-exp`）与文本文件
+- 多任务并行（上限 8）、权限确认弹窗、会话管理、PWA 安装到桌面
+- ⚙ 设置面板全项管理：模型与 API Key（动态模型列表）、权限/沙箱、调度、工作空间、记忆、缓存仪表盘、技能库、云同步
+- 远程/手机访问：配置 `"web": {"host": "0.0.0.0"}` 后自动启用访问令牌（打印 `?token=` 链接；`mingdao web --auth-token <令牌>` 可固定）；默认 `127.0.0.1` 本机免令牌
+
+### IDE 集成
+
+- **VS Code**：`ide/vscode/` 复制到扩展目录 → 侧边栏内嵌完整 WebUI、选中代码右键「发送选中代码」、服务器随面板自动启停
+- **JetBrains**：`ide/jetbrains/` 工具窗（JCEF）集成，`./gradlew buildPlugin` 构建后安装
+- **桌面快捷方式**：`bash scripts/desktop/install-desktop.sh`
+
+### 工作空间
+
+WebUI 顶部（⚙ 右侧）下拉切换/新建（目录缺失自动创建，服务端工作目录随切换）；CLI：
+
+```bash
+mingdao workspace add 项目A ~/projects/a   # 登记（list/use/path/remove 管理）
+cd "$(mingdao workspace path 项目A)"        # 一键进入
+```
+
+### 技能系统（36 个开箱即用）
+
+内置 14 个常驻技能（`git-commit` `code-review` `debugging` `testing` `pdf` `docx` `xlsx` `pptx` `docker` 等）+ 22 个可安装技能库：
+
+```bash
+mingdao skill search 文件      # 搜索（内置库 + 线上 registry）
+mingdao skill install sql      # 一键安装到 ~/.mingdao/skills/（可改可删）
+mingdao skill list/uninstall/update
+```
+
+安装来源自动识别：库名 / 本地目录 / SKILL.md 的 URL / git 仓库；安装前 dry-run 校验格式。三级优先级：用户级 > 项目级（`.mingdao/skills/`）> 内置。企业内网可设 `MINGDAO_REGISTRY_URL` 指向自建 registry。
+
+### 云同步与多用户协作
+
+**服务端**（一台 Linux 服务器，零依赖单文件）：
+
+```bash
+sudo mkdir -p /var/lib/mingdao-sync
+sudo mingdao sync-server 443
+# 公网务必 HTTPS：SYNC_CERT=/证书/fullchain.pem SYNC_KEY=/证书/privkey.pem
+```
+
+**客户端**：
+
+```bash
+mingdao sync login <用户名> <密码> https://你的服务器   # 首次自动注册 + 设备配对
+mingdao sync push / pull / status                      # 推送 / 拉取 / 状态
+mingdao sync passwd <新密码>                           # 改密码（吊销全部设备，需重新登录）
+mingdao sync share <会话名>                            # 分享会话 → 16 位分享码
+mingdao sync accept <分享码>                           # 接受分享（再次接受即刷新）
+mingdao sync conflicts                                 # 跨设备冲突三选一（保留本地/采用远端/都保留）
+```
+
+多设备自动同步（会话结束静默推送）；冲突绝不丢数据（自动 `.server-*` / `.remote-*` 备份 + 图形化选择）；WebUI 设置面板含完整同步/分享/冲突区块。
+
+### 模型与 Key
+
+- 内置：DeepSeek（v4-pro / v4-flash / v4-flash-vision-exp）、OpenAI（GPT-5 系列）、Qwen（qwen3.7-max）、GLM（GLM-5）、Kimi（kimi-latest）
+- **动态模型列表**：下拉框只显示已设置 Key 的服务商，名单以官方 `/models` 接口线上拉取为准（缓存 1 小时，设置面板可手动「刷新模型」），新模型发布自动出现
+- 自定义 OpenAI 兼容端点：WebUI 设置面板直接添加/修改/删除（名称/标签/API 地址/Key，可标 `vision` 支持图片）
+- 其他协议：`~/.mingdao/providers/<name>.mjs` 写 `createProvider(cfg)`，见 [docs/PROVIDERS.md](docs/PROVIDERS.md)
+
+### 安全
+
+- **权限三档**：`ask`（默认，写文件/命令逐次确认）/ `auto` / `readonly`；工具级规则 `{"mode":"ask","allow":["bash:git *"],"deny":["write"]}`
+- **沙箱三档**（Linux + bubblewrap）：`off` / `readonly` 全盘只读 / `safe` 只读+断网；非 Linux 自动降级并明示
+- **密钥分离**：Key 存 `~/.mingdao/credentials.json`（600 权限，`mingdao key` 管理），`config.json` 无密钥可分享可提交
+
+## 配置与扩展
+
+配置字段、权限规则、Hooks、MCP、云同步、自定义 Provider 的完整说明见 [docs/CONFIG.md](docs/CONFIG.md)；架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)；Provider 扩展见 [docs/PROVIDERS.md](docs/PROVIDERS.md)。
+
+## 常见问题
+
+| 问题 | 解决 |
+| --- | --- |
+| 提示「没有可用 API Key」 | `mingdao key set <服务商>`（或 WebUI 设置面板设 Key）；Key 从对应平台获取 |
+| 模型下拉框是空的 | 说明没有任何服务商设置了 Key——设 Key 后自动拉取线上模型列表（可点「刷新模型」） |
+| 沙箱提示降级 | 需要 Linux 且安装 bubblewrap（`apt install bubblewrap` / `dnf install bubblewrap`） |
+| Windows 颜色异常 | 使用 Windows Terminal 或 PowerShell 7 |
+| 同步服务器自签证书报错 | 登录时加 `--insecure` 过渡；正式环境请配置 Let's Encrypt 证书 |
+| 上传图片报「模型不支持」 | 切换到 `deepseek-v4-flash-vision-exp` 或给自定义模型加 `vision` 标记 |
+| 局域网/公网访问 WebUI | `mingdao web --auth-token <令牌>`（或 `MINGDAO_WEB_TOKEN` / `web.token`）；未配置且非回环绑定时自动生成随机令牌并打印 `?token=` 链接，所有数据接口强制校验令牌与 Host 头 |
+
+## 目录结构
+
+```
+src/               CLI / Agent 循环 / 工具 / 权限 / 技能库 / MCP / 云同步 / WebUI（全部零依赖）
+skills/            14 个内置常驻技能
+skills-lib/        22 个可安装技能库预设
+registry/          线上技能 registry 索引
+test/              smoke（离线）+ e2e（真实进程/HTTP）测试
+docs/              架构与扩展文档
+install.sh / install.bat / install.ps1   一键安装
+```
+
+## 测试
+
+```bash
+node test/smoke.js         # 离线冒烟：工具 / SSE / Agent 循环 / 权限 / 技能 / 同步
+node test/e2e-local.js     # 端到端：mock 服务器 + 完整 CLI 进程
+node test/e2e-web.js       # 端到端：WebUI HTTP/SSE/权限/调度/同步
+node test/e2e-schedule.js  # 端到端：定时/周期/链式调度
+```
+
+## License
+
+[MIT](LICENSE)

package/docs/ARCHITECTURE.md

@@ -0,0 +1,108 @@
+# MingDao-Harness 架构设计
+
+本文档说明 MingDao 的设计决策、架构分层，以及对四个参考实现的学习结论。
+
+## 1. 对参考实现的学习
+
+| 参考实现 | 值得借鉴的设计 | MingDao 的采纳 |
+| --- | --- | --- |
+| **Claude Code** | TUI 会话循环；工具循环（模型 ↔ 工具调用）；权限系统（ask / acceptEdits / bypassPermissions + allow/deny 规则）；`--continue`/`--resume` 会话续聊；headless `-p` 模式；AGENTS.md 目录约定 | 全部采纳（TUI + 三档权限 + JSONL 会话 + 单次提问 + AGENTS.md） |
+| **OpenAI Codex CLI** | TypeScript 单体；skills；沙箱化 bash；config.toml 分层配置 | 采纳「配置分层 + 预设目录」；skills/沙箱进入路线图 |
+| **DeepSeek-Harness** | Cordis「一切皆插件」组合架构；`llm-retry` 自动重试；`token-meter` 计量；context 预算与 compaction 分层；host/client 解耦 | 采纳「重试 + 计量 + 预算裁剪 + UI 与核心解耦」；以轻量注册表（Provider/Tool）替代重依赖的插件内核，保持零依赖 |
+| **CodeWhale** | 单一耐用运行时（TUI / `exec` / Fleet 同内核）；审批策略引擎独立（execpolicy）；SQLite 持久化；OpenAI + Anthropic 双适配层；MCP/hooks 分层 | 采纳「权限引擎独立 + Provider 适配层」；`mingdao "…"` 单次提问即 headless 入口；SQLite/MCP/hooks 进入路线图 |
+
+**结论**：一个 Harness 的最小可行内核 = `模型 Provider 层 + 工具注册表 + 权限引擎 + 上下文管理 + 会话持久化`，UI 只是内核的一个适配器。MingDao 按此分层实现。
+
+## 2. 总体架构
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                     UI 适配层（可替换）                      │
+│   TUI（流式 Markdown/代码高亮/diff 预览/spinner/中断/补全）  │
+│   · 单次提问 headless · WebUI（HTTP+SSE，复用同一 io 抽象）                          │
+└───────────────────────────┬────────────────────────────────┘
+                            │ io 接口（print/ask/confirm/流式写入）
+┌───────────────────────────▼────────────────────────────────┐
+│                      Agent 核心循环（agent.js）              │
+│   消息 → Provider（流式）→ 工具调用？→ 权限引擎 → 执行工具    │
+│        → 结果回填 → 循环（上限 24 步）→ 输出最终文本          │
+└──────┬──────────────────────┬──────────────────────┬────────┘
+       │                      │                      │
+┌──────▼──────┐   ┌───────────▼───────────┐  ┌───────▼────────┐
+│ Provider 层 │   │ 权限引擎 permissions.js │  │ 上下文管理      │
+│ 注册表+工厂  │   │ ask/auto/readonly      │  │ token 估算+裁剪 │
+│ 重试/超时   │   │ + allow/deny 规则      │  │ 工具输出截断    │
+└──────┬──────┘   └───────────────────────┘  └────────────────┘
+       │
+┌──────▼───────────────────────────────────────────────┐
+│ OpenAI 兼容协议（HTTP + SSE 流，DeepSeek/OpenAI/...）  │
+│ 自定义 Provider 模块（~/.mingdao/providers/*.mjs）    │
+└──────────────────────────────────────────────────────┘
+
+横切：config.js（~/.mingdao/config.json + 向导，不含密钥） · credentials.js（~/.mingdao/credentials.json，密钥独立凭证库，权限 600） · session.js（JSONL）
+```
+
+## 3. 技术选型与关键决策
+
+| 决策 | 选择 | 理由 |
+| --- | --- | --- |
+| 运行时 | Node.js ≥ 18（纯 ESM，**零 npm 依赖**） | 内置 `fetch`/`readline`/`fs` 覆盖全部需求；免构建、免依赖下载，一键安装最可靠 |
+| UI 起步形态 | **TUI**（终端会话式） | 实现成本最低（Claude Code 同形态）；核心与 UI 解耦，WebUI/IDE 后置 |
+| 模型接入协议 | OpenAI 兼容 chat/completions 作为通用层 | DeepSeek/OpenAI/Qwen/GLM/Kimi/大量网关同协议；非兼容协议走自定义 Provider 模块 |
+| 工具协议 | OpenAI function-calling Schema | 与协议层一致，模型无需适配 |
+| 会话存储 | JSONL 追加写 | 零依赖、可流式恢复、人类可读；SQLite 留作索引化路线图 |
+| 密钥存储 | 独立凭证库 `credentials.json`（600 权限）+ 环境变量 | Key 与 config.json/仓库完全隔离：config 可分享可提交，密钥只在本机；`mingdao key` 命令族管理 |
+| 权限 | 独立权限引擎，默认 ask | 借鉴 CodeWhale execpolicy 分层；写/命令类工具默认逐次确认 |
+| 上下文 | CJK 感知启发式估算 + 尾部保留裁剪 | 无分词器依赖；保留 system + 最近消息；裁剪插入说明消息 |
+| 扩展点 | Provider 模块 / Tool 注册表 / io 接口 / 库 API | 对应 DSH「插件点」思想，但用零依赖注册表实现 |
+
+## 4. 关键组件
+
+### Agent 循环（src/agent.js）
+每轮：裁剪消息至预算 → 请求模型（流式输出 text/reasoning）→ 若有 `tool_calls`，逐项走 PreToolUse 钩子 → 权限引擎 → 执行 → PostToolUse 钩子 → `tool` 角色消息回填 → 循环（≤24 步）。返回 text/usage/steps/finish/duration。内置子代理（task）、todo 清单状态、undo 备份仓、Ctrl+C 中断。
+
+### Provider 层（src/providers/）
+- `openai-compatible.js`：SSE 增量解析（容错跨 chunk 断行、分片 tool_calls 拼接、`reasoning_content` 渲染）；
+- `index.js`：`resolveProviderConfig`（模型预设 → 服务商预设 → config → 凭证库/环境变量）、超时 + 429/5xx 指数退避重试、自定义模块加载。
+
+### 工具层（src/tools/）
+文件/命令工具（read/write/edit/ls/glob/grep/bash）+ 智能体工具（skill 技能加载 / task 子代理 / todo 清单 / undo 撤销）；write/edit 自动备份支持 undo（每文件 10 份，会话级）。
+
+### Skills 技能系统（src/skills.js）
+渐进式披露：技能清单（名称+描述）注入系统提示，模型按需用 `skill` 工具加载 SKILL.md 全文。三级来源与同名覆盖优先级：**用户级 `~/.mingdao/skills/` > 项目级 `<项目>/.mingdao/skills/` > 内置 `<安装包>/skills/`**（借鉴 DeepSeek-Harness 的 SKILL.md 格式，内置 14 个常用技能）。
+
+### Hooks（src/hooks.js）
+PreToolUse（stdin 收 JSON，stdout 输出 `{decision:"block", reason}` 可阻止执行）与 PostToolUse（审计/通知）；matcher 支持 `*`、逗号分隔多工具、前缀通配。协议借鉴 Claude Code hooks。
+
+### 上下文管理（src/context.js）
+估算：英文 ≈ 4 字符/token，CJK ≈ 1 字符/token。裁剪：恒保留首条 system，从尾部向前取到预算；被裁剪时插入说明消息。工具输出上限 2 万字符。`/compact` 用模型压缩旧上下文（完整历史保留在会话文件）。
+
+### 权限引擎（src/permissions.js）
+只读工具（read/ls/glob/grep/skill）默认放行；写/命令按模式处理。`deny` 优先于 `allow`；规则支持「工具名」与「工具名:参数前缀」模式匹配（如 `bash:git *`）。
+
+### 配置与凭证（src/config.js / src/credentials.js）
+- `config.js`：`~/.mingdao/config.json` 与初始化向导。**不含任何密钥字段**，可安全分享、提交仓库。
+- `credentials.js`：独立凭证模块。Key 存 `~/.mingdao/credentials.json`（权限 600）；解析优先级为「环境变量 → 本地凭证库 → config.json 显式字段（兼容旧版本）」；提供 `maskKey` 脱敏（前 6 位…后 4 位）与 `mingdao key status/set/remove/import` 命令族。安装包与仓库零密钥，每个用户安装后配置自己的 Key。
+
+### 会话（src/session.js）
+`~/.mingdao/sessions/<时间戳>-<随机>.jsonl`，每轮自动追加；`--continue` 载入最近会话，`--resume` 打开选择器（首条消息预览 + 相对时间）；`/init` 生成项目 AGENTS.md，`/memory` 维护用户级记忆（`~/.mingdao/AGENTS.md`），两者自动注入系统提示。
+
+## 5. 面向 DeepSeek-V4 的优化设计
+
+1. **预设调优**：v4-pro（推理/规划：温度 0.4、输出上限 32k、预算 200k）；v4-flash（日常：温度 0.6、输出 8k、预算 128k）；两者 `contextWindow` 均为 384K（正式版规格：2026-08-17 起 V4-Pro 转正商用），预算可随时调高。
+2. **推理内容流式展示**：`reasoning_content` 以暗色增量渲染，与正文同流。
+3. **峰谷定价适配**：每轮后展示 prompt/completion tokens，便于用户把批处理放在谷时段（v4 系列 2026-08-17 起峰谷定价，高峰 9:00–14:00 为闲时 2 倍）。官方同时提供 Responses API 与 Anthropic 兼容接口；MingDao 默认走 OpenAI 兼容 chat/completions，如需原生协议可写自定义 Provider 模块。
+4. **模型路由（路线图）**：规划用 v4-pro、执行用 v4-flash 的自动分工；Provider 抽象已支持任意切换。
+5. **可靠性**：超时 + 指数退避重试，长上下文下避免瞬时错误中断任务。
+
+## 6. 扩展指南速览
+
+- **加一个模型网关**：`mingdao init` → custom → 填 baseUrl（OpenAI 兼容即可）。
+- **加一个非兼容协议**：见 [PROVIDERS.md](PROVIDERS.md) 的模块示例。
+- **加一个工具**：在 `src/tools/index.js` 的 `TOOLS` 里加 Schema + `dispatch` 分支（返回 `{ok, output|error}`）。
+- **换 UI**：实现 `io` 接口（print/writeText/writeReasoning/ask/confirm/choose），`createAgent` 不感知终端。
+- **库方式复用**：`import { createAgent, createProvider, dispatch } from 'mingdao-harness'`。
+
+## 7. 路线图
+
+WebUI（HTTP/SSE 适配器）→ MCP 客户端 → 子代理与 plan 模式 → 精确 tokenizer + 自动压缩 → Hooks/Skills → SQLite 会话检索 → bash 沙箱 → IDE 插件。

package/docs/CONFIG.md

@@ -0,0 +1,257 @@
+# 配置详解（~/.mingdao/config.json）
+
+配置文件**不含任何密钥**，团队内可安全共享、可提交仓库。API Key 一律存独立凭证库
+`~/.mingdao/credentials.json`（权限 600），解析优先级：**环境变量 > 凭证库 > 配置字段**。
+
+## 基本字段
+
+```json
+{
+  "provider": "deepseek",
+  "model": "deepseek-v4-flash",
+  "baseUrl": "https://api.deepseek.com/v1",
+  "permission": "ask",
+  "sandbox": "off",
+  "contextBudget": 128000
+}
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `provider` | `deepseek` / `openai` / `qwen` / `glm` / `moonshot` / `custom` / 自定义 Provider 模块名 |
+| `model` | 模型名（预设见 `src/models.js`；自定义端点可任意命名） |
+| `baseUrl` | OpenAI 兼容 API 地址（可覆盖内置服务商默认值） |
+| `permission` | `ask`（默认）/ `auto` / `readonly`，或规则对象（见下） |
+| `sandbox` | `off` / `readonly` / `safe`（Linux + bubblewrap；其余平台自动降级） |
+| `contextBudget` | 上下文预算 tokens（模型预设默认值：flash 128k / pro 200k） |
+
+可选字段：`temperature`、`maxOutputTokens`、`includeUsage`（流式请求 usage 统计，个别网关不支持
+`stream_options` 时设 `false`）、`autoTitle`（自动生成会话标题，默认开）、`notify`（任务桌面通知，默认开）、
+`autoCompact`（上下文自动压缩，默认开，见下）、`audit`（工具调用审计，默认开，见下）。
+
+## 工具调用审计（P3-5）
+
+每个工具调用（含被拒/被钩子阻止/参数解析失败）自动落 `~/.mingdao/audit.jsonl`（600 权限）：
+时间、会话、模型、工具名、参数（`sk-` 系 Key 自动脱敏）、执行结果/退出码/超时/耗时/输出大小、
+拒绝原因。查看：`mingdao audit [数量]`（默认 20 条）或会话内 `/audit`；`"audit": false` 关闭。
+超过 20000 行自动保留最近 10000 行。
+
+## 技能完整性（P3-3）
+
+registry 技能安装时逐文件校验索引声明的 `sha256`（不符即拒绝安装）；安装后在
+`.mingdao-source.json` 记录目录指纹，加载时校验——被本地篡改的技能**拒绝加载**并在
+`mingdao skill` 列表 / WebUI 技能面板中警示。确认是自己改的：`mingdao skill trust <名称>`
+重新记录指纹；否则卸载重装。
+
+## 上下文自动压缩（auto-compaction）
+
+长会话超出 `contextBudget`、静默裁剪即将丢弃早期段落时（被裁段落 ≥3 条且 ≥2000 tokens），
+MingDao 先用 executor 模型（路由关闭时为当前模型）把被裁段落压成 ≤500 字摘要，以单条 user
+消息注入，替代「失忆」；压缩后会话文件同步重写为压缩形态，不会每轮重复压缩。摘要失败自动
+回退普通裁剪，绝不阻塞会话。设置 `"autoCompact": false` 可关闭（回到纯静默裁剪）。
+
+触发线（滞回缓冲）：默认达到预算 **80%** 即提前压缩、压到约 60%——避免在预算线附近反复
+裁剪/压缩导致缓存前缀频繁失效（每次失效 = 该轮 prompt 全额按未命中计费）。可用
+`"compactTrigger": 0.9` 调整触发线（0–1 之间的小数）。
+
+## 会话检索索引（P3-2）
+
+`mingdao sessions search <关键词>` 与 WebUI 历史会话搜索走增量词表索引
+（`~/.mingdao/sessions-index.json`）：中文按 bigram+单字、英文按词，多词 AND 匹配；
+只有内容变化（mtime/size）的会话才重新分词，删除的会话自动清出索引。索引文件可随时
+删除（下次搜索自动重建）。
+
+## 会话级工作空间（P3-4）
+
+WebUI 中每个会话记住自己的工作目录：新会话记录创建时的全局工作空间；继续该会话时任务
+固定写回它的目录，**全局切换工作空间只影响新会话**，多任务并行互不串目录（服务端不再
+`process.chdir`）。载入历史会话时全局工作空间自动聚焦到该会话的目录；头部下拉显式切换
+时当前会话跟随。映射存于 `~/.mingdao/session-workspaces.json`，会话改名/删除自动维护。
+
+## 权限规则（工具级 allow/deny）
+
+```json
+{
+  "permission": {
+    "mode": "ask",
+    "allow": ["bash", "bash:git *"],
+    "deny": ["write"]
+  }
+}
+```
+
+- `allow` / `deny` 为工具名列表，支持「工具名:参数前缀」匹配（如 `bash:git *` 只放行 git 命令）；
+- `deny` 优先于 `allow`；匹配不到时回落到 `mode`（`ask` 逐次确认）；
+- **需要特殊授权时弹窗交互**：被 `deny` 规则拦截、或 `readonly` 模式下执行写操作时，WebUI/TUI 会弹出询问（「是否本次强制放行？」），同意即放行、拒绝/无响应即拒绝——不再静默拦截。
+
+## Hooks（工具调用生命周期）
+
+```json
+{
+  "hooks": {
+    "PreToolUse":  [{ "matcher": "write|edit|bash", "cmd": "node ~/hooks/pre.js" }],
+    "PostToolUse": [{ "matcher": "*", "cmd": "curl -X POST http://localhost:9000/audit" }]
+  }
+}
+```
+
+- `PreToolUse`：工具执行前调用，命令输出非空即阻止执行（返回的文本交给模型）；
+- `PostToolUse`：执行后调用（审计/日志）；
+- 协议：stdin 收 JSON（工具名/参数），stdout 回 JSON；`matcher` 支持 `|` 分隔与 `*` 通配；
+- ⚠ **hooks 命令以 `shell: true` 执行——配置即代码执行**：命令会在每次工具调用时运行，请只填自己完全信任的命令（例如不直接填 `curl <不可信地址>`）。
+
+## MCP 服务器
+
+```json
+{
+  "mcpServers": {
+    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/你的/目录"] },
+    "everything": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"] }
+  }
+}
+```
+
+格式与 Claude Code 相同；工具以 `mcp__<服务器>__<工具>` 并入 Agent 循环，带 `readOnlyHint`
+标注的工具自动放行。会话内 `/mcp` 查看状态；`mingdao mcp preset list/add` 一键接入常用服务器。
+
+## WebUI 服务器
+
+```json
+{
+  "web": { "host": "127.0.0.1", "port": 3820, "token": "可选访问令牌" }
+}
+```
+
+- 仅本机使用保持默认 `127.0.0.1`（无需令牌）；
+- 绑定 `0.0.0.0`/局域网地址时**强制令牌认证**：未配置则每次启动随机生成并打印
+  `http://<地址>:<端口>/?token=…` 访问链接；固定令牌三种方式（优先级从高到低）：
+  `mingdao web --auth-token <令牌>`、环境变量 `MINGDAO_WEB_TOKEN`、`web.token`；
+- 令牌同时接受 URL `?token=`、请求头 `X-MingDao-Token` 或 `Authorization: Bearer`；
+- 服务端校验 `Host` 头必须等于回环名或绑定地址（防 DNS rebinding），代理场景会 403 属预期。
+
+## 沙箱环境变量过滤
+
+bash 工具**默认**从子进程环境中剥离敏感变量（`*_API_KEY`、`*_TOKEN`、`*_SECRET`、
+`*_PASSWORD`、`*_CREDENTIAL` 等），防止模型驱动的命令一条 `env` 读走密钥——与沙箱档位
+无关（`sandbox: "off"` 同样过滤）。按名放行 / 整体关闭：
+
+```json
+{ "bashEnvKeep": ["NPM_TOKEN"], "bashEnvFilter": false }
+```
+
+## 定价覆盖
+
+内置价格表数据时点为 2026-08（`/api/state` 的 `pricingAsOf` 字段），官方调价后无需等
+发版即可覆盖（单位：元/百万 tokens）：
+
+```json
+{
+  "pricing": {
+    "overrides": {
+      "deepseek-v4-flash": { "input": 1.5, "output": 4.5, "cacheHit": 0.05, "peak": { "input": 3 } }
+    }
+  }
+}
+```
+
+`peak` 缺省的字段沿用闲时价；未覆盖的模型继续用内置价格表。峰谷判断默认锚定**北京时间**
+（`Asia/Shanghai`，与 DeepSeek 计费口径一致，海外用户本机时区不再错位），可覆盖：
+`"pricing": { "timezone": "Asia/Shanghai" }`。
+
+其他护栏字段：`maxEmptyRounds`（连续空输出续写轮数上限，默认 3——每轮空输出都是全额
+completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger`（自动压缩触发线，默认 0.8）。
+
+## 费用护栏（costGuard）
+
+按北京时间自然日累计实际费用（含缓存折扣与 Batch 半价后的真实口径），Agent 每轮开始前检查：
+
+```json
+{ "costGuard": { "dailyLimitYuan": 10, "warnAtYuan": 8, "action": "block" } }
+```
+
+- `action: "warn"`（默认）超限仅提醒；`"block"` 到达上限暂停执行（明天自动恢复）；
+- `/cost` 与 WebUI 头部费用徽标实时显示「今日费用 / 上限百分比」。
+
+## 战略省钱：Batch 半价 + 避峰调度
+
+- **Batch API（50% off）**：`mingdao batch <问题文件|->` 每行一个问题，单轮批量任务走
+  批处理通道（无工具无流式），结果落 `mingdao-batch-result-<时间戳>.jsonl` 并计入 `/cost`
+  分账（`batch` 标记）。端点不支持的网关会明确报错；可用 `config.batchBaseUrl` 指定支持
+  批处理的网关、`batchEndpoint`/`batchWindow` 覆盖协议字段。
+- **避峰执行（高峰输入价 2 倍）**：`mingdao run --offpeak` / `mingdao schedule add --offpeak`
+  ——高峰时段（北京时间工作日 9:00–14:00）自动顺延到 14:00 后执行；**周末全天按闲时计价**
+  （DeepSeek 官方邮件确认），不触发避峰等待。WebUI 调度面板勾选「🌙 避峰执行」。
+
+## 云同步
+
+```json
+{
+  "sync": {
+    "url": "https://session.mingdao.ai",
+    "username": "you",
+    "deviceName": "我的笔记本",
+    "auto": true
+  }
+}
+```
+
+设备 token 存凭证库（`credentials.json` 的 `sync` 字段），配置里只留非秘密项。自建自签证书
+过渡阶段可加 `"insecure": true`（正式证书就绪后删除）。详见 README「云同步与多用户协作」。
+
+同步**服务端**（`mingdao sync-server`）支持注册开关环境变量：
+`MINGDAO_SYNC_REGISTRATION=open|invite|closed`（默认 open）+ `MINGDAO_SYNC_INVITE_CODES=码1,码2`
+（invite 模式生效），公网自建建议至少 `invite`。
+
+## 会话日志与「带上文」（跨会话连续性）每个会话结束时写入 `~/.mingdao/journal.jsonl`（首条用户消息 + 结果摘要）。**默认不注入**新会话的
+系统提示——新会话应当全新开始，避免「新会话却接着上一次会话的工作」的上下文混淆；需要延续上次
+工作时显式开启：
+
+- WebUI：输入框下方「📌 带上文」勾选（仅本次发送生效）；
+- CLI：`mingdao --journal`（新会话或 `--continue` 均可叠加）。
+
+长期偏好仍走用户记忆（`AGENTS.md`，见上），不受此开关影响。
+
+## 自定义模型（WebUI 添加后落盘的结构）
+
+```json
+{
+  "customModels": {
+    "my-gpt4": { "label": "我的 GPT-4 网关", "baseUrl": "https://gateway.example.com/v1" },
+    "my-ds": { "label": "自建 DeepSeek 网关", "baseUrl": "https://gw.example.com/v1", "tokenizer": "deepseek" }
+  }
+}
+```
+
+自定义模型的 Key 存凭证库 `custom:<模型名>` 键下；增删改建议直接用 WebUI 设置面板完成。
+
+自定义端点若跑的是 DeepSeek 系模型（模型名不以 `deepseek` 开头时默认走启发式估算、预算误差
+可达 ±2 倍），加 `"tokenizer": "deepseek"` 即按官方词表精确计数：
+
+## 自定义 Provider 模块（非 OpenAI 兼容协议）
+
+在 `~/.mingdao/providers/<name>.mjs` 导出：
+
+```js
+export async function createProvider(cfg) {
+  // cfg: { name, baseUrl, apiKey, envHint, ... }
+  return { name: 'my-provider', async chat(opts) { /* 返回流式响应对象 */ } };
+}
+```
+
+`provider` 填模块名即生效。完整协议见 [PROVIDERS.md](PROVIDERS.md)。
+
+## 辅助调用结构化输出与并行子代理
+
+- 标题生成/记忆提取/路由分类器三类辅助调用走 `response_format: json_object`（maxTokens
+  120→50、300→200、80→20），解析失败自动回退纯文本路径——不支持的网关静默兼容。
+- `task` 子代理工具支持 `readOnly: true`：只读调研任务（read/ls/glob/grep/skill）自动并行
+  执行（auto 权限模式下），写类任务仍串行。
+- 调度器为**单守护进程**：`mingdao schedule daemon [status|stop]` 查看/停止；有任务时任意
+  schedule 命令自动拉起，无任务自动退出（每任务一个 sleeper 进程的旧方案仅作兜底）。
+
+## 月度费用报告
+
+`mingdao cost` 控制台速览；`mingdao cost report [YYYY-MM|all]` 导出 Markdown 报告
+（按模型分账、每日费用柱状图、缓存命中率、Batch 子项），文件落当前目录
+`mingdao-cost-report-<月>.md`。数据源为 cache-stats.jsonl（含缓存折扣与 Batch 半价的真实口径）。
+