前言¶
DeepSeek Harness（DSH）把对话、工具调用和界面扩展收进同一套插件机制里。若你只想在本地 Harness 里和当前会话的模型下一盘棋，而不另开网页或独立客户端，就需要一个在对话侧注册工具、在界面侧挂棋盘的插件。dsh-xiangqi 由社区维护者 Galaxy-2001 发布，归类为「趣味换装」，在 DSH 里提供中国象棋对弈：你执红方点棋盘走子，模型执黑方通过 xiangqi 工具应招，并支持走棋动画、悔棋及按会话保存棋局。
这是什么¶
dsh-xiangqi 是 DSH 的中国象棋插件。维护者为 Galaxy-2001，源码与说明见 GitHub 仓库，社区目录页为 skillhub.cn/plugins/Galaxy-2001/dsh-xiangqi。项目采用 MIT 许可证；当前包版本为 0.1.1（以 package.json 为准）。
它解决的是：在 Harness 对话流里完成对弈——每一步用户落子会作为用户消息进入当前会话并唤醒模型，模型调用 Host 侧注册的 xiangqi 工具查看局面、走黑棋；前端轮询到新状态后刷新棋盘。棋局保存在本机 DSH 数据目录，插件重载或重启 DSH 后可恢复。
核心功能¶
下面介绍 README 中已写明、且与实现文件对应的能力。
界面与入口¶
- 左侧栏在「插件 / 插件市场 / 自动化任务」下方增加棋子图标「中国象棋」。
- 点击左侧栏图标后，主区域会短暂进入象棋页，随后自动回到对话，并把棋盘放进右侧栏常驻；右栏 tab 关闭后，可在象棋页点「右侧栏常驻」重新打开。
- 主区域的大棋盘页也可直接使用，底部有「右侧栏常驻」「返回对话」按钮。
对弈流程¶
- 安装并启用插件后刷新 Harness 页面，加载 Client 代码。
- 点左侧栏棋子图标，右栏出现「中国象棋」棋盘。
- 点 开始对局（会在对话里告知模型新开了一盘）。
- 点选红棋，再点目标交叉点落子。
- 每走一步，该步作为用户消息送入当前对话并唤醒模型；模型用
xiangqi工具应招，棋盘轮询到新状态后自动刷新。
对局控制¶
支持 悔棋、重新开局、认输、提醒对手（模型长时间无反应时）。悔棋会回到「轮到你走」的局面：若刚走完一步就悔，撤 2 手（对方 + 你）；若对手正在思考时悔，撤 1 手。
模型侧工具 xiangqi¶
| 参数 | 说明 |
|---|---|
action |
status（默认，看局面 + 合法走法）、move、new、resign |
from / to |
move 时的起终点坐标，如 h0、h2 |
reason |
认输 / 重开的简短原因（可选） |
坐标约定：列 a-i 从左到右（红方视角），行 0-9 从下到上，0 是红方底线。status 会给出当前全部合法走法（形如 h0h2）。
规则与持久化¶
规则引擎（engine.js）覆盖基本走法、自将过滤、将帅照面、将军、将死和困毙；尚未实现重复局面、长将长捉等竞赛裁判规则，也没有棋钟或内置专业象棋引擎。棋局按会话保存在 ~/.dsh/xiangqi/games.json，每手落子写入存档，悔棋栈一并保存。
安装与启用¶
需要先安装 DeepSeek Harness，并配置可正常对话、调用工具的模型。本插件没有额外的运行时 npm 依赖。
README 写明：当前验证环境为 Windows 桌面端 DSH 0.2.1-rc.3；0.1.0 已实测开局、双方走棋、对话应招与悔棋；0.1.1 的状态修复已通过自动化回归测试，完整桌面回归仍待进行。其他 DSH 版本、macOS 和 Linux 尚未实际验证。
从 v0.1.1 发布页 下载 dsh-xiangqi-0.1.1.tgz，在包所在目录执行：
dsh plugin --profile desktop add ./dsh-xiangqi-0.1.1.tgz
Web 版将 desktop 替换为 web。回到 DSH 的「插件」页面启用中国象棋；若界面提示重启或刷新，按提示操作。
从源码开发和打包时，可先检查与测试，再打包：
npm run check
npm test
npm pack
npm pack 会先运行语法检查和测试。
典型用法与 HTTP 接口¶
Host 侧除 xiangqi 工具外，还提供 HTTP RPC（仅回环地址，并校验 Host / Origin），供前端落子、开新局等。常用路径包括：
| 路径 | 说明 |
|---|---|
GET /plugins/dsh-xiangqi/state?sessionId= |
读当前会话棋局与合法走法 |
POST /plugins/dsh-xiangqi/move |
用户落子（body: sessionId/from/to），成功后唤醒模型 |
POST /plugins/dsh-xiangqi/new |
开新局（announce:false 可不打扰模型） |
POST /plugins/dsh-xiangqi/undo |
悔棋 |
POST /plugins/dsh-xiangqi/resign |
用户认输 |
POST /plugins/dsh-xiangqi/nudge |
提醒模型走棋 |
右侧栏是会话作用域的：点左侧栏入口时需先切回对话再打开右栏，否则右栏拿不到当前会话。
适用场景与注意¶
适合谁：在本机 DSH 单用户对话里，想用当前会话模型下中国象棋、并希望在侧边栏常驻棋盘的开发者或使用者。
运行与权限：插件以当前 dsh 进程权限运行；安装前应阅读源码与 MIT 许可证，确认可接受其数据写入（如 ~/.dsh/xiangqi/games.json）及与模型的调用成本。
范围说明：与 AI 的对弈使用当前会话的模型调用，费用和响应时间取决于模型配置。HTTP 接口面向本机单用户场景；规则引擎为纯函数、无 npm 依赖，Host/Client 不依赖 Harness 内部包。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-xiangqi 把「对话 + 工具 + 侧边栏 UI」串成一条可复现的对弈链路：红方在界面走子，黑方由模型通过 xiangqi 应招，棋局按会话持久化。进一步了解可访问 目录页 与 GitHub 仓库。
