赛博木鱼 yang101and/dsh-cyber-muyu

dsh-cyber-muyu

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

License: MIT
Node
Runtime deps
dsh-plugin

dsh-cyber-muyu 是 DeepSeek Harness (dsh) 的赛博木鱼插件：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
- 截图 / Screenshots
- 安装 / Installation
- 使用 / Usage
- 金钱卦怎么算 / How the divination works
- 设置项 / Configuration
- HTTP API
- 隐私 / Privacy
- 本地开发 / Development
- 致谢与许可 / Credits and License

特性 / Features

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

截图 / Screenshots

| 界面预览 | Screenshots |
| 悬浮木鱼 | 摇卦过程 |
| 悬浮木鱼 | 摇卦过程 |
| 卦象结果卷轴 | 设置页 · 功德簿 |
| 卦象结果卷轴 | 设置页 · 功德簿 |
| 卦象历史 | 木鱼特写 |
| 卦象历史 | 木鱼特写 |

安装 / Installation

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

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

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

卸载：

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

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，不影响已安装插件）：

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 许可证 发布。

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

- Ares-Chang/wooden-fish（MIT，© Chang）
- zengsanxiang/mp-muyu（MIT，© caidukai）

农历换算表（src/lunar.js）数据源自 jjonline/calendar.js，原始数据为香港天文台公开历表。

第三方声明详见 NOTICE。