dsh-cyber-muyu

Readme

# dsh-cyber-muyu

**赛博木鱼 / Cyber Wooden Fish** —— 电子木鱼赛博修仙，agent 干活即修行。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D22.5-339933.svg)](package.json)
[![Runtime deps](https://img.shields.io/badge/runtime_deps-0-brightgreen.svg)](#本地开发--development)
[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-4B6BFB.svg)](https://github.com/topics/dsh-plugin)

`dsh-cyber-muyu` 是 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/DeepSeek-Harness) 的赛博木鱼插件：agent 每成功调用一次工具就敲一声木鱼、攒一分功德，报错算「渡劫」，一轮对话收工有连击；木鱼旁边还挂着一支**金钱卦**，摇六次铜钱当场起卦。功德簿同时是一份 agent 工作量与失败率统计。

A cyber wooden-fish (muyu) plugin for **DeepSeek Harness**. Every tool call the agent makes strikes the fish and earns merit, failed calls count as *tribulations*, and a finished turn rings a closing combo. Alongside it sits a real-time **I-Ching coin divination** (金钱卦) cast with three coins and six tosses. The merit ledger doubles as a lightweight workload and failure-rate report for your agent.

> 金钱卦是中国传统文化的趣味演绎，**结果仅供娱乐，工程决策请理性判断**。
> Coin divination here is a cultural toy, not a prediction service. Important decisions still deserve real analysis.

## 目录 / Contents

- [特性 / Features](#特性--features)
- [截图 / Screenshots](#截图--screenshots)
- [安装 / Installation](#安装--installation)
- [使用 / Usage](#使用--usage)
- [金钱卦怎么算 / How the divination works](#金钱卦怎么算--how-the-divination-works)
- [设置项 / Configuration](#设置项--configuration)
- [HTTP API](#http-api)
- [隐私 / Privacy](#隐私--privacy)
- [本地开发 / Development](#本地开发--development)
- [致谢与许可 / Credits and License](#致谢与许可--credits-and-license)

## 特性 / Features

| 特性 | 说明 |
| --- | --- |
| 悬浮木鱼 | 网页端常驻一枚可拖动的赛博木鱼，点「敲一下」即 +1 功德，配合成音效与飘字反馈。 |
| 自动敲击 | agent 每成功调用一次工具自动敲一下（成功 / 失败音色不同）；一轮对话结束有收尾连击，Todo 全部完成与起卦同样计入功德。 |
| 功德簿 | 设置页展示今日 / 累计功德、工具调用次数、渡劫（报错）次数、连击与修行成就，同时是一份 agent 工作量与失败率统计。 |
| 金钱占卦 | 点「籤」以三枚铜钱摇六次实时起卦，完整呈现本卦、动爻、变卦、互卦、体用生克、解卦与工程宜忌。不是预写签文库随机抽签，每一次都是现场演算。 |
| 模型工具 | `muyu_strike`（让 agent 自己敲木鱼）与 `muyu_oracle`（让 agent 按金钱卦为你起卦，结果同步在卷轴中展开）。 |
| 纯本地 | 功德与卦象历史只存于本机 dsh storageDomain；起卦是本地数学计算，不请求任何外部 API、不联网、不消耗模型额度。 |
| 零运行时依赖 | 宿主端与浏览器端均为纯 JavaScript，`npm install` 只服务于构建与测试。 |

## 截图 / Screenshots

| 界面预览 | Screenshots |
| :---: | :---: |
| **悬浮木鱼** | **摇卦过程** |
| ![悬浮木鱼](docs/01-floating-fish.png) | ![摇卦过程](docs/05-casting.png) |
| **卦象结果卷轴** | **设置页 · 功德簿** |
| ![卦象结果卷轴](docs/02-hexagram.png) | ![设置页 · 功德簿](docs/03-settings.png) |
| **卦象历史** | **木鱼特写** |
| ![卦象历史](docs/04-history.png) | ![木鱼特写](docs/06-muyu-closeup.png) |

## 安装 / Installation

**前置要求**：dsh（DeepSeek Harness）+ Node.js ≥ 22.5，使用 `web` profile。

```bash
dsh plugin --profile web add github:yang101and/dsh-cyber-muyu
```

安装后重启 dsh Web 使插件生效，页面角落会出现悬浮木鱼。

卸载：

```bash
dsh plugin --profile web remove dsh-cyber-muyu
```

## 使用 / Usage

### 网页端

| 操作 | 效果 |
| --- | --- |
| 点悬浮木鱼 | 手动敲击，功德 +1，播放动画与音效。 |
| 点「籤」 | 打开金钱卦卷轴，摇六次铜钱实时起卦，卦象落在卷轴中。 |
| 打开设置页 | 查看功德簿（今日 / 累计功德、工具调用、渡劫次数、连击、修行成就）与卦象历史，并调整各项设置。 |

### 模型工具

**`muyu_strike`** —— 敲一声木鱼，为当前工作积攒功德，并在网页端播放敲击动画与声音。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `reason` | string | 这一声为何而敲（心愿 / 庆祝 / 安慰），≤ 60 字，显示在木鱼飘字旁。可省略。 |
| `times` | integer | 连击次数 1–9，默认 1。 |

**`muyu_oracle`** —— 按金钱卦实时起卦，返回完整卦象。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `question` | string | 所问之事，≤ 200 字。可省略；问题字数会记入占验背景。 |

### 自动敲击的节流规则

毫秒级合批与冷却，避免 agent 高频调用把木鱼敲成机关枪：

| 事件 | 表现 | 合批 / 冷却 |
| --- | --- | --- |
| 工具调用成功 | 常规木鱼声 | 1.2 s 内合批，单次最多 8 声 |
| 工具调用失败 | 渡劫音色 | 1.6 s 内合批，单次最多 3 声 |
| 一轮对话结束 | 轻敲一声 | 1.5 s 冷却 |
| Todo 全部完成 | 收工三连击 | 每会话 5 分钟冷却 |
| 深夜（23:00–05:00）干活 | 深夜修行提醒 | 每晚一次 |

此外还有一层令牌桶限流（4 秒补满 12 声），兜住子 agent 风暴。

## 金钱卦怎么算 / How the divination works

插件实现的是民间通行的**文王六十四卦金钱课**（六爻金钱卦），全部计算在 `src/divination.js`，可单测复现：

1. **摇钱**：三枚铜钱，字面（阴）记 2、背面（阳）记 3，每掷三枚求和，共摇六次，自初爻（最下）向上爻（最上）排列。
   - 和为 **6**：老阴 ⚋×（阴爻，动）；**7**：少阳 ⚊（阳爻，静）；**8**：少阴 ⚋（阴爻，静）；**9**：老阳 ⚊○（阳爻，动）。
2. **成卦**：六爻组成**本卦**（查 8×8 卦宫表得周易卦序与卦名）；老阴变老阳、老阳变老阴后得**变卦**；二至四爻、三至五爻互得**互卦**。
3. **体用**：动爻所在的经卦为「用」，不动之经卦为「体」；上下俱动或六爻安静时，内卦（下卦）为体、外卦（上卦）为用。
4. **吉凶**：以体卦、用卦的五行生克定本卦基调（用生体 / 体用比和 / 体克用为吉，体生用为平，用克体为凶），再以变卦的体用关系定终应（生体、比和上调，克体下调），映射为上上 / 上吉 / 中吉 / 中平 / 小凶 / 下下六级。
5. **工程宜忌**：八卦各配一条「工程卦德」（如离主发布与文档、艮主冻结守成、坎主排障加固、坤主测试配合），结合体卦与变用卦实时组合出本次的「宜 / 忌」。
6. **起卦依据**：占问时刻会换算为农历年月日与时辰干支（`src/lunar.js`，1900–2100 历表），连同问题字数、六掷钱数记入卷轴底部的占验背景。

## 设置项 / Configuration

设置页可直接调整，也可通过 `GET` / `POST /dsh-cyber-muyu/api/config` 读写。

| 键 | 默认值 | 说明 |
| --- | --- | --- |
| `enabled` | `true` | 总开关。 |
| `volume` | `0.6` | 音量，取值 0–1。 |
| `autoStrike` | `true` | agent 事件自动敲击。 |
| `soundAuto` | `true` | 自动事件是否发声；关闭后只播放动画。 |
| `corner` | `"bottom-right"` | 悬浮木鱼位置：`bottom-right` / `bottom-left` / `top-right` / `top-left`。 |
| `showMeritPill` | `true` | 木鱼旁显示今日功德气泡。 |
| `nightGuard` | `true` | 深夜修行提醒。 |
| `categories` | 全部 `true` | 分类开关：`tool-ok` / `tool-fail` / `turn` / `finale`。 |

## HTTP API

所有路由挂在 `/dsh-cyber-muyu/api` 之下，并沿用 dsh 的信任栅栏：`connection.requestRejection` 的 Host / Origin 校验加浏览器认证。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/stream` | SSE 事件流，推送 `strike` / `achievement` / `oracle` / `night` 事件。 |
| `GET` | `/state` | 当前配置、功德簿摘要与最近 10 条卦象。 |
| `POST` | `/strike` | 手动敲击，body `{"times":1,"reason":"..."}`。 |
| `POST` | `/oracle` | 起卦，body `{"question":"...","coins":[[2,3,2], ...]}`；`coins` 为浏览器摇卦动画的六掷结果，省略则由服务端随机。 |
| `GET` / `POST` | `/config` | 读取 / 写入配置。 |
| `POST` | `/reset` | 重置功德簿与卦象历史，body `{"confirm":"reset"}`。 |

## 隐私 / Privacy

- 功德、成就、卦象历史通过 dsh storageDomain 保存在本机（storage 域 `dsh_cyber_muyu`），不上传。
- 起卦为纯本地计算，无网络请求、无外部 API、无遥测。
- 重置数据：`POST /dsh-cyber-muyu/api/reset`（body `{"confirm":"reset"}`），或停止 dsh 后删除对应 storage 文件。

## 本地开发 / Development

```bash
npm install            # 无运行时依赖，仅为构建与测试
npm run check          # 语法检查（host + client 全部源文件）
npm test               # 单元测试（禅修内核 / 农历 / 起卦引擎，41 用例）
npm run build:client   # 零依赖拼接构建 client/bundle.js
```

`client/bundle.js` 由 `scripts/build-client.mjs` 生成，**请勿手动修改**。

用 `--patch` 把工作树叠加进本地 dsh（不写入 profile，不影响已安装插件）：

```bash
cp cordis.dev.example.yml cordis.dev.yml
# 编辑 cordis.dev.yml，把 name 改成本仓库 src/index.js 的绝对路径
dsh --profile web --patch ./cordis.dev.yml --port 3180 --no-open
```

`cordis.dev.yml` 含本机绝对路径，已在 `.gitignore` 中，不会发布。

## 致谢与许可 / Credits and License

本项目以 [MIT 许可证](LICENSE) 发布。

黑白极简木鱼的造型语言受以下项目启发，木鱼图形为本项目自绘 SVG：

- [Ares-Chang/wooden-fish](https://github.com/Ares-Chang/wooden-fish)（MIT，© Chang）
- [zengsanxiang/mp-muyu](https://github.com/zengsanxiang/mp-muyu)（MIT，© caidukai）

农历换算表（`src/lunar.js`）数据源自 [jjonline/calendar.js](https://github.com/jjonline/calendar.js)，原始数据为香港天文台公开历表。

第三方声明详见 [NOTICE](NOTICE)。