English ｜ 简体中文
**月汐（kimi-tide）是一个小插件，装在 DSH 上。DSH 就是你平时跟 AI 一起写代码、干活的工具（DeepSeek 官方开源）。**
**它只做一件事：自动替你换一个更合适的 AI。** 你手里通常接了好几个 AI——有的便宜、有的聪明、有的看得懂图。以前全靠自己手动切，切完还常忘了切回来；装上月汐，它每一轮自己挑：**日常活先给便宜的，要紧的活交给更聪明的，图交给看得懂图的。**
**它给你三样东西：**
- **省钱**——不该花的地方不花。闲聊、翻译、改文案、整理资料这类活，继续用最便宜的那个，**好钢只用在刀刃上**。
- **不掉链子**——关键处有强模型兜着。写代码、审代码、做数学各自走更强的那个；要紧的产出还能先让强模型审一遍（问题按严重度列出 + 改进建议 + 通过／不通过），再交到你手上。
- **不用记着切回来**——贴完一张图，只有那一轮换到看得懂图的 AI，下一轮自动回到你原来用的。**贵 AI 是按「段」用的，不是按「整场会话」用的。**
（下文里「AI」和「模型」是一回事——DSH 管它们叫模型。）
**适合谁**：在用 DSH、且接了不止一个模型的人。
**不适合**：只用一个模型，或还没跑起 DSH 的人（先把 DSH 用起来，再回来装这个）。
---
## 它解决什么问题
**场景一：贴了张截图，模型说看不了**
- 以前：手动切到能看图的模型 → 贴图 → 问完 → 记得切回来。
- 装后：直接贴。带图的消息自动交给能看图的模型，下一条纯文字消息自动回到默认模型。
**场景二：切完模型，忘了切回来**
- 以前：为一张图切到贵的模型，之后整场会话都在烧贵的额度。
- 装后：月汐按「每一步」决策，一会话不绑死——图处理完，下一条消息就回到你的默认模型。
**场景三：额度总比预期烧得快**
- 以前：所有消息——包括「你好」和「帮我看下这句翻译」——都走最贵的模型。
- 装后：选「省钱」预设（一套配好的「默认模型 + 规则」方案），闲聊、翻译、日常杂活自动走便宜模型，代码和图才动用贵的模型；面板实时显示套餐余额（Kimi/GLM 等带套餐的模型，无套餐的置灰不显示）。
---
## 30 秒看懂路由逻辑
一条消息进来，月汐按这个顺序决定用哪个模型：
1. **显式点名**：消息里写 `@kimi`（provider 级：模型取你预设里配过的那个）或 `@kimi/k3`（精确钉到某个模型）→ 最高优先。
2. **规则命中**：按预设规则判定——带图？命中哪组关键词？→ 规则按**特异度**排序（命中词多者优先、带图恒第一、平手按列表序），排序后**首条目标可用的规则**说了算（目标不可用自动降级下一条）。
3. **默认打底**：都没命中 → 用预设的默认模型。
4. **带图保险**：就算选了纯文本模型，消息带图也会被强制改道给能看图的模型——不会崩。
```mermaid
flowchart LR
A["💬 你的消息
（本轮新消息）"] --> B{"显式 @模型？"}
B -- "@kimi 等" --> H["🎯 显式指令
最高优先"]
B -- 否 --> C["📏 预设规则链
带图 / 关键词组
特异度降序 · 首条可用生效"]
C -- 命中 --> D["🌙 规则目标：模型｜协作流
（不可用则降级跳过）"]
C -- 未命中 --> E["💰 预设默认模型
（打底）"]
H --> J
D -- "目标=协作流" --> T["🌊 转述流
vision-exp 读图转文字"]
D -- "目标=模型" --> F
E --> F{"带图且目标
文本-only？"}
T --> K["✍️ 转述文字
文本模型接力"]
F -- 是 --> G["🖼️ 图像护栏
改道多模态候选"]
F -- 否 --> J["📋 dock 面板留痕
选谁 + 为什么"]
G --> J
K --> J
```
> 图中「协作流」= 一条「先 A 后 B」的自动流程（比如：图先转成文字，再交给便宜模型作答）；「多模态」= 能看懂图片的模型；「转述」= 让能看图的模型（图中 vision-exp 是 Kimi 家一款能看图的模型名）把图里的内容写成文字；「dock 面板」= 输入框下方的「🌙 月汐」面板。
## 它长什么样
[](docs/assets/readme/kimi-tide-architecture.html)
*点图看大图。`docs/assets/readme/kimi-tide-architecture.html` 下载后用浏览器打开，是可平移缩放/搜索的交互式架构图（明暗双主题，节点可溯源到源码）。*
---
## 快速开始
### 1. 前置条件
- Node.js ≥ 22
- DSH `@deepseek-ai/dsh@0.1.2-rc.1` 及以上（本版实机验证于 `0.1.5-rc.1`）
- 你想互相调度的模型已接入 DSH——**不限哪一家**。想用 Kimi，就准备一把 **Kimi Code Console API Key**（在 Kimi 控制台生成的密钥；配额面板也用这把 key）
### 2. 接入候选模型（DSH「设置 → Models」页）
「设置 → Models」里添加模型来源（示例：**`kimi-coding`**，`apiKeyEnv` 填 `KIMI_API_KEY`，然后在凭据区粘贴你的 Key——k3 等 4 个 Kimi 模型会自动出现在目录里）。**接几家都行**：月汐的候选池就是这页的全部模型。密钥由 DSH 托管保存，**不会写进任何插件配置文件**。
### 3. 安装插件
```bash
cd packages/dsh-kimi-tide
npm install && npm run build && npm pack
dsh plugin --profile web add ./dsh-kimi-tide-.tgz
```
### 4. 用起来
重启 `dsh web`：
- **设置 → 月汐**：预设行选「省钱」或「能力」，路由器即刻上岗；
- 消息里 **`@kimi`** 可以显式点名，或者靠内置关键词组自动改道（比如消息里出现「代码」就走编码模型）；
- 输入框下方的「🌙 月汐」面板实时显示每一步选了谁、为什么；
- ✅ **30 秒验收**：发一句「帮我写个函数」——面板应显示命中 code 规则并改道到编码模型。看不到理由条 = 路由器没上岗，回「设置 → 月汐」确认已选预设。
---
## 预设与规则
预设 = 一套「默认模型 + 规则」方案，一键全局切换；月汐自带两套：
| 预设 | 默认模型（没规则命中时用它） | 规则 | 适合谁 |
|---|---|---|---|
| 关闭 | — | — | 想完全手动选模型的人 |
| 省钱 | `deepseek-v4-flash` | 带图 → `k3`；代码关键词 → `kimi-for-coding`；翻译关键词 → `deepseek-v4-flash` | 额度敏感、日常杂活多 |
| 能力 | `k3` | 带图 → `k3`；审查 → `k3`；代码 → `kimi-for-coding`；数学 → `deepseek-v4-pro`；长文 → `k3`；写作 → `deepseek-v4-pro`；翻译 → `deepseek-v4-flash`；闲聊 → `deepseek-v4-flash` | 追求最佳产出质量 |
内置 7 组关键词（词表可改，也可自建新组）：
| 组 | 方向 | 内置词表（可改） |
|---|---|---|
| `code` | 编码 | 代码, code, bug, 重构, refactor, 实现, 函数, 测试, 接口, 联调, 部署, 性能, 报错, 日志, 编译, 命令, 脚本 |
| `review` | 审查 | 审查, review, 评审, 挑毛病, 复检, 检查, audit, 意见, 打分 |
| `writing` | 写作 | 写作, 文案, 润色, 改写, 扩写, 标题, 推文, 周报, 演讲稿, 总结 |
| `translate` | 翻译 | 翻译, 译成, 中译英, 英译中, translate, 本地化 |
| `longdoc` | 长文 | 长文档, 通读, 逐段, 全文, 上万字, 大文档 |
| `math` | 数学 | 数学, 证明, 推导, 求解, 公式, 数论, 概率, 逻辑题 |
| `chitchat` | 寒暄 | 你好, 谢谢, 怎么样, 随便, 聊聊, 天气 |
> `review` 组默认服务于**评审协作流**（请强模型评审本轮产出）——机制、三个开关与今天的边界见下文「多模型协作评审」一节。
两个常用微调（都在「设置 → 月汐」里点几下就能配）：
- **最少命中词数**：给规则配一个下限（比如 2），一句话里至少命中这个词组的 2 个词才触发——避免「做个方案」这种顺带提到关键词的普通句子误触发。
- **推理力度（effort）**：给规则目标或默认模型指定「思考深度」档位（想得越深越慢越贵）；模型不支持你配的档位时自动忽略，不会报错。
### 用量与余额（跟着命中的目标自动切）
面板第二行的额度槽会**跟随当前命中的目标**自动换形态：订阅类（code plan）显示用量窗（周 / 5h，条画的是**剩余**比例），API 计费类显示**余额**（余额不足以调用 API 时会明确标注）。旁边还有一个**总览**按钮——一屏列出全部已注册的源，以及某个源为什么没数据：「该套餐无公开 API」/「key 未配置」/「取数失败」三态分别说清，不用你猜。
> 取数用的凭据按 **`settings.yaml` 里该 provider 配置的 `apiKeyEnv` 名字**解析（并自动兼容内置别名）——**你给 provider 起的 key 名与插件内置默认名不一致时，面板照样取得到数**。
### 说明页与语义确认闸
- **「设置 → 月汐 → 说明」**：面板每个元素是什么、设置里每个字段什么意思，八个分区讲清，关键条目带**当前值**（如「触发方式：当前＝手动 ⇒ 关键词命中不会触发评审」），另有一张**症状 → 原因**表。
- **语义确认闸**（默认关闭，需在配置里开）：开启后关键词命中不会立刻改道——先让**本预设的打底模型**确认「这是本轮真意图吗」，判否就跳过该条规则、继续匹配后续规则。超时/模型不可用/输出解析失败一律**按原关键词结果走**；显式 `@` 轮与「带图规则已排首位」的轮不发判官调用。配置项 `preset.hitConfirm`。
- **判词写在决策原因里**：判否 / 确认 / 无结论会前置到面板的决策原因串（如「语义闸无结论 1200ms（code-kfc）」）。因为判否会让规则出链、最终落打底，带判词注记的**打底决策也会照常上报**——否则「判否」这个最该被看见的结果反而看不见。
- **判官按目标能力关掉思考**：判官是推理模型，而这道闸只给它 64 token 的预算——如果放任它先思考，预算会被思考吃光、正文一个字都不剩，判词必然不可解析（**闸门静默失效，什么都不改**）。所以判官目标声明支持「off」档位时，插件会显式关掉思考；目标不支持（例如 k3）就不下发，绝不硬塞一个它不认的档位。
### 显式 @ 的两种写法
- `@kimi`（provider 级）：模型取**你预设里配过的那个** kimi 目标（不是目录里碰巧排第一的），决策原因里会写明依据；
- `@kimi/k3`（精确到模型）：直接钉到该模型——想用哪个模型就用哪个，不受候选池顺序影响；模型不可用时会**明确告诉你回落到了谁**，不会静默换人。
- **只有真的 provider 才算指令**：`@` 后面若不是本插件认识的 provider——例如工作区路径引用 `@README.md`、scoped 包名 `node_modules/@deepseek-ai/…`、路径里的 `@xxx`——**不会被当成显式指令**，该轮照常走关键词规则，决策原因里写明「`@x` 非本路由器已知 provider（已忽略）」。
匹配细节（词边界、特异度排序、降级语义）、带图行为、配置全字段：见[路由器架构详解](packages/dsh-kimi-tide/docs/router.md)。候选池 = Models 页全量目录，任何模型都能当默认或规则目标。
## 多模型协作评审（强模型把关）
路由决定「这一步用谁」，评审决定「这一步干得够不够好」。两者可以分开用，也可以一起用。
**它做什么**：一轮结束后，月汐把「本轮你的需求 + 主模型产出」发给**你指定的评审模型**（通常是更强、更贵的那个），拿回一份结构化评审——问题（按严重度分级：阻塞／建议／可选）→ 改进建议 → 结论（通过／有条件通过／不通过），并以**评审卡**贴在那一轮下面。
**三个开关**（设置 → 月汐 → 协作流）：
| 开关 | 今天的实际行为 |
|---|---|
| 触发方式 | `关键词`：消息命中指定关键词组才评审；`手动`：随时敲 `/kimi-tide review` 评审上一轮 |
| 轮数 | 1–3，约束评审往返次数 |
| 自动修订 | **尚未实现的配置项**——勾选不会产生任何行为（字段保留，实现排在规划中） |
**它今天不做的事**：不会自动把产出退回重做，也不会替你改代码。评审判「不通过」时，下一步由你决定——这是有意的取舍：默认不烧强模型额度，也不自动改掉你满意的产出。
**成本**：评审只发生在**命中的轮**，且只把该轮产出切片发给评审模型（单段上限 12000 字符、60 秒超时、失败不打断本轮）。研究仓库引用的业界数据里，对抗式评审回路的 token 消耗常在单模型的 2–3 倍量级——**本插件自身尚未测量**。
**证据分级**：机制设计与三轮实证见 [kimi-tide-research](https://github.com/tafcear/kimi-tide-research)。其中「评审能否提升弱模型产出质量」**尚未度量**（意见接受率、与「强模型独立完成」的对照基线、修复引入新问题的比率均无数据），因此本节不写效果数字；「转移效率对照实验」已立为 v1.4.0 的发布前证据。
---
## 常见问题
**Q：以前的 OAuth 接入方式去哪了？**
A：退役了。DSH 官方生态已原生支持 Kimi 接入，自研的那层属于重复造轮，已整体删除。现在一把 Console API Key + 官方 Models 页配置即可。历史存档见 [`docs/legacy-setup.md`](docs/legacy-setup.md)。
**Q：还需要装 Kimi CLI 并 `kimi login` 吗？**
A：不需要。一把 Console API Key + 官方 Models 页配置即可。
**Q：带图会话有什么限制？**
A：默认「锁存」姿态下，会话一旦带过图就锁定在能看图的模型上——如果它的额度/Key 失效，这个会话切不回文本模型，只能新开。想避免：把预设的带图兜底改成「懒转述」（图片先转成文字，文本模型接力）或「盲答」（当没图处理）。转述结果有缓存，失败不会反复重试。重要的带图任务，保持模型额度健康即可。
**Q：之前听说有个「能力评分引擎」？**
A：退役了。以前靠机器打分选模型，黑箱难懂；现在改成你写得出的规则——命中即路由，未命中走默认，每个决策你都能读懂、改得动。旧评分配置升级时自动转成预设。
**Q：路由配置存在哪里？升级会丢吗？**
A：存在 DSH 设置里（「设置 → 月汐」编辑，重启保持）。跨版本升级自动迁移，旧配置自动留档；细节见[路由器架构详解](packages/dsh-kimi-tide/docs/router.md)的「迁移链」节。
---
## 版本与路线
> 当前版本：**v1.3.0（2026-09-15）**
- 每个版本你得到了什么：[CHANGELOG.md](CHANGELOG.md)
- 维护者证据链（commit 锚点 / 验收记录）：[docs/release-evidence.md](docs/release-evidence.md)
- 规划中：子代理转述、0.8.5「强化与包装」小版本——详见[证据链文档](docs/release-evidence.md)「规划中」条。
---
## 文档索引
> 这个项目的三条原则：**官方优先 · 规则透明 · 决策可观测**——路由依据是你写得出的规则，每次自动选路都有理由、有留痕。
**我想用**
- 快速开始（本页）
- 常见问题（本页）
- [更新日志](CHANGELOG.md)
**我想深挖**
- [路由器架构详解](packages/dsh-kimi-tide/docs/router.md)：预设/规则/降级/迁移链/配置全字段
- [交互式架构图](docs/assets/readme/kimi-tide-architecture.html)（下载后浏览器打开；静态版见上文「它长什么样」）
- [DSH 宿主平台契约调研](docs/host-platform-map.md)
- [项目定位与维护策略](docs/positioning.md)
- [双模型协作闭环方法论](docs/agent-collaboration-loop.md)（本项目自己的开发方式；独立研究见 [kimi-tide-research](https://github.com/tafcear/kimi-tide-research)）
**我想参与**
- 来 [Discussions](https://github.com/tafcear/kimi-tide/discussions) 聊使用体验
- 报告问题、提交修复（欢迎任何形式的贡献，见下方贡献者）
---
## 开发与测试
```bash
cd packages/dsh-kimi-tide
npm install
npm run typecheck # tsc --noEmit
npm test # vitest
npm run build # tsc 宿主 + esbuild 浏览器
```
质量基线：全量测试绿 + typecheck 0 错误 + build 通过方可提交。本仓库实践「实施 → 独立审查 → 修复 → 复检验收」双模型协作闭环（见 [`docs/agent-collaboration-loop.md`](docs/agent-collaboration-loop.md)）。
**文档门禁**：`npm run check` 跑三条机器门禁——CHANGELOG / README / package 版本三方一致、全库文档链接不断、两个 README 双语对一致（版本行 / 章节骨架 / 徽章 / 本地文档链接集合四项，规则见 [`docs/agents/readme-pair.md`](docs/agents/readme-pair.md)）——任何用户可见改动，中英两份 README 必须同一次提交里一起改。
**Release 双语四段式**：每个新版本的 Release 正文（= 附注 tag 消息）必须是**双语**——中文整块在上、English 整块在下，每种语言内部四段：① 一句话定位 ② `本次更新` / `What's new` ③ `安装与升级` / `Install & upgrade` ④ `验证与验收` / `Verification & acceptance`。打 tag 前用 `node scripts/check-release-notes.mjs --file <正文草稿>` 自检，Actions 在 `gh release create` 前再拦一次（模板与细则见 [`docs/agents/release-notes.md`](docs/agents/release-notes.md)）。
**发布门禁**：任何版本发版（打 tag / 触发 Actions Release）前，必须在真实宿主上跑通该版本的实机验收清单并全绿，且由维护者裁定 tag——「单元测试绿」不等于「宿主里能跑」。各版本验收记录见 [docs/release-evidence.md](docs/release-evidence.md)。
> **发布规范（维护者）**：DSH 插件必须声明 `dsh.bundle.patch`（指向 `cordis.patch.yml`）才能作为 profile 层加载。本插件已按官方规范声明，升级版本时请勿移除该字段。
---
## 贡献者
- 感谢 [@dracpet](https://github.com/dracpet) 的实机诊断与社区贡献：[PR #1](https://github.com/tafcear/kimi-tide/pull/1)（OAuth 过期刷新）、[PR #2](https://github.com/tafcear/kimi-tide/pull/2)（`commands/execute` 跨宿主契约容错）、[PR #3](https://github.com/tafcear/kimi-tide/pull/3)（YAML null 配置归一化）与 [Issue #4](https://github.com/tafcear/kimi-tide/issues/4)（rc.2 投影 wire 契约诊断）——你的反馈直接加固了 0.5.x–0.6.0 的发布质量。
- 感谢 [@pandashere](https://github.com/pandashere) 的 [dsh-kimi-bridge](https://github.com/pandashere/dsh-kimi-bridge)（MIT）：项目初期的 Kimi CLI 桥接由此起步，早期审查轮与双面插件/投影机制为月汐的面板链路提供了先行验证；该组件已随官方接入路径成熟而退役归档（git 历史保留），特此致谢。
- 也欢迎任何形式的贡献：报告问题、提交修复，或来 [Discussions](https://github.com/tafcear/kimi-tide/discussions) 聊聊使用体验。
---
## 许可证与合规提示
- **kimi-tide 本体**：[MIT](LICENSE)（Copyright 2026 kimi-tide contributors）
- **第三方组件**：`@earendil-works/pi-ai`（MIT）、`@deepseek-ai/dsh-llm-pi-ai`（MIT, DeepSeek）、`schemastery`（MIT）、`zod`（MIT）、`yaml`（MIT）、`dsh-kimi-bridge`（MIT，历史致谢，已归档）
- **合规**：默认走 **Console API Key 官方路径**，个人使用安心；Kimi Code 订阅条款仍以官方表述为准，请勿高频批量调用或共享密钥。
- 本仓库**不含任何凭据**；请勿将 `~/.dsh/.credentials.yaml`、环境变量中的密钥提交到仓库。