前言¶
用 DSH 跑任务时有一段不好安排的时间：模型在思考、在推理，Web GUI 上暂时没有别的事可做，只能干等。dsh-xiangqi 把这段空档利用起来——一只抱着「象」字棋子的卡通宠物悬浮在 DSH Web GUI 上，邀请你在 AI 思考的间隙下几步中国象棋。
对局是纯消遣的人机对弈，与对话 agent 完全独立，不阻塞主循环。下面介绍这个插件的功能、安装方式与使用注意。
这是什么¶
dsh-xiangqi 由 ovdoesw 开发，MIT 许可证开源，当前版本 0.1.0。一句话定位：DSH Web 客户端插件，AI 思考时可以下中国象棋的消遣宠物，内置自写引擎与离线台词，LLM 局势点评可选。
先说明两个基本属性：
1、完全离线可玩。本地规则引擎负责走法与台词，不依赖任何在线服务；LLM 点评只是锦上添花，不用也不影响对局。
2、它是 Cordis 客户端插件包，dsh.client.platform 为 web，peer 依赖 @deepseek-ai/cordis >=0.1.0 与 react >=17。
核心功能¶
功能围绕「一只宠物 + 一副棋盘」展开：
- 悬浮宠物：拖拽可移动，位置持久化；悬停时棋子升起，弹出随机邀请气泡。
- 小面板棋盘：点击宠物展开，支持点选走子、难度切换、新局、悔棋、点评，以及放大全屏。
- 全屏棋盘：放大到全屏对弈，按
Esc收起；背板保持点击穿透，不影响底层应用的操作。 - 本地台词：开局定式名（当头炮 / 仙人指路 / 屏风马 / 顺手炮 / 列手炮等）与三国杀风格的击杀、将军、绝杀台词，全部离线即时触发。
- 状态持久化：对局进度、难度、宠物位置、设置都保存在浏览器，刷新不丢。
内置引擎与难度分档¶
引擎是作者自写的纯 TypeScript 实现：negamax + α-β 剪枝 + 迭代加深，以异步分片方式执行，不阻塞主线程。难度分三档：
| 难度 | 策略 |
|---|---|
初级 easy |
深度 1 + 随机扰动，从分数接近的候选中随机挑一个 |
中级 medium |
深度 2 固定搜索 |
高级 hard |
迭代加深到深度 4，或限时 5 秒 |
需要坦白的一点：作者自述初学象棋，内置引擎「比较菜」，只是简化搜索加上简单的子力/位置估值。对应解法见后面的典型用法一节。
LLM 局势点评（可选）¶
- 默认复用 DSH 已配置的 LLM 服务（
ctx.llm）； - 需要指定模型时，在插件设置里填入
base / key / model，走 OpenAI 兼容的/chat/completions直连端点； - 支持每步自动点评与手动点评按钮，风格可在「专业棋评 / 娱乐主播」间切换。
所有 LLM 失败都会静默降级为 null，不会中断或遮挡对局；断网时本地台词仍让体验完整。
安装与启用¶
插件从源码构建安装。先克隆仓库、装依赖，再构建产物：
git clone https://github.com/ovdoesw/dsh-xiangqi.git
cd dsh-xiangqi
npm install
npm run build
npm run build 产出 lib/client.js 与 lib/index.js。装载方式见仓库内的 INTEGRATION.md，其中有 cordis.patch.yml 配置与 dsh plugin 命令的说明；本地开发可用 link: 指向本目录。
经过上面的步骤装载后，建议先在纯 Node 环境跑一遍核心层与 AI 层单测，确认构建正常——这一步不需要 DSH 前端环境：
npm test # node --import tsx --test test/*.test.ts
npm run typecheck # tsc --noEmit
npm run typecheck 如需 DSH runtime 类型，要先装载进 DSH 或安装 peer 依赖。
典型用法¶
日常对弈：点击宠物展开小面板，点选棋子走子，随时切换难度、开新局或悔棋；想看得更清楚就放大到全屏，按 Esc 收起。全屏背板保持点击穿透，不占用底层应用。
配置点评：默认什么都不用填，插件直接复用 DSH 的 LLM 服务；想换模型再去插件设置填 base / key / model。风格二选一：「专业棋评」或「娱乐主播」。
让 Agent 调棋力：觉得对手太弱时，可以直接让 DSH 里当前的 AI Agent 改引擎——想更强，就加深 hard 的搜索（改 src/ai/search.ts 的 maxDepth 或 src/ai/engine.ts 的时限），或加强 src/ai/evaluate.ts 的估值函数；想更休闲，就加大 easy 的随机扰动或降低搜索深度。README 给的示例指令是「帮我让高级难度下得更强，别 5 秒就随便应招」。Agent 改完跑 npm run build 重新打包即时生效。
适用场景与注意¶
适合两类人：一是经常在 DSH Web GUI 里等长任务、想找点事做的用户；二是想给 AI Agent 安排一个「看得见、改得着」的小项目——这套纯 TypeScript 引擎零依赖、可单测，适合让 Agent 就地修改。
安装前有几点需要知道：
1、插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。本项目为 MIT 许可，源码公开在 GitHub。
2、长将 / 长捉是简化版仲裁：同一局面出现第三次判将方负，完整亚洲规则仲裁不在 v1 范围。
3、击杀台词为文字呈现，暂无音频播报。
4、LLM 点评依赖网络与 token，失败会静默降级，不影响对局本身。
5、项目明确不做：联网对战、外部 UCI 引擎（如 Stockfish）、开局库深度学习。
小结¶
dsh-xiangqi 不解决生产力问题，解决的是等待时间怎么打发：本地方案、离线可玩、棋力不满意还能让 Agent 当场改。core / ai / client 分层加上 node –test 单测的结构，对想写 DSH 插件的开发者也有参考价值。
项目源码：https://github.com/ovdoesw/dsh-xiangqi
社区目录收录页：https://www.skillhub.cn/plugins/ovdoesw/dsh-xiangqi （该目录为独立社区站点，与 DeepSeek / 幻方无官方从属关系）
