武侠RPG sujubaima/wuxia-rpg-dsh

武侠 RPG

一个由 Coding Agent / LLM 担任游戏主持人（GM）的文字武侠 RPG 套件。项目将规则、世界设定、结构化数据、数值引擎、存档系统与交互界面拆分为独立模块，可按需要选择以下运行方式：

| 方式 | 适用场景 | 需要的目录 |
| Coding Agent Skill | 在支持 Skill 与工具调用的 Coding Agent 中直接游玩 | wuxia-rpg/ |
| DSH 插件 | 在 DeepSeek Harness（DSH）会话中使用武侠卡片、面板与战斗 UI | wuxia-rpg/、dsh-plugin/、install.sh |
| 自带 Web 套件 | 使用独立 Web UI，通过 agent-lite 连接模型 API 驱动 GM | wuxia-rpg/、web/、agent/、config.json |

当前 Skill 版本：0.9.13。

[!WARNING]
当前项目仍处于初期阶段，代码实现、游戏机制与数值设计均有待持续打磨。后续版本不排除引入不兼容修改，当前版本仅供体验。

运行预览

自带WebUI套件 WebUI Explore WebUI Combat

DSH插件（可交互卡片） DSH Explore DSH Combat

项目组成

.
├── wuxia-rpg/ # 核心 Skill：规则、设定、数据、数值引擎与存档逻辑 │ ├── SKILL.md │ ├── references/ # GM 规则、数据结构、战斗规则与 Markdown UI │ ├── assets/data/ # 角色、武学、物品、状态、阵营与地图基线数据 │ └── scripts/ # go / judge / check / scene-prepare / quest-prepare / query 等引擎入口 ├── web/ # 标准库 HTTP/SSE 服务与原生、React Web UI ├── agent/ # 纯 Python 标准库的 agent-lite 底座 ├── dsh-plugin/ # DSH Host 工具、隐藏命令、Client UI 与武侠GM Preset 声明 ├── config.json # Web 套件配置 ├── install.sh # DSH 插件一键安装脚本 └── release.sh # 完整套件打包脚本

wuxia-rpg/assets/data/ 是发布和内容编辑的唯一权威数据源；backup/history/ 中的数据目录仅作历史归档，不参与运行或发布。

存档默认写入 ~/.wuxia/save/slot_/，可通过环境变量修改。

环境要求

- Python 3.9 或更高版本。
- Skill 与引擎本身只使用 Python 标准库，无需安装 pip 依赖。
- 使用 DSH 插件时需已安装 DSH、pnpm；从源码构建还需 Node.js 18+ 与 npm。
- 所选模型需要具备稳定的工具调用、文件读取与长上下文能力。

一、作为 Coding Agent Skill 使用

1. 安装 Skill

必须完整保留 wuxia-rpg/ 目录，不能只复制 SKILL.md；规则引用、数据文件和引擎脚本均通过相对路径加载。

Claude Code 用户级安装（复制到 ~/.claude/skills/，若目标已存在请先自行确认覆盖或保留）：

mkdir -p ~/.claude/skills
cp -R /绝对路径/cc-game-dsh/wuxia-rpg ~/.claude/skills/

或使用符号链接，项目更新后立即生效：

mkdir -p ~/.claude/skills
ln -s /绝对路径/cc-game-dsh/wuxia-rpg ~/.claude/skills/wuxia-rpg

其他 Coding Agent：将 wuxia-rpg/ 注册为该 Agent 的 Skill 目录，并确保 Agent 至少具有读取 Skill 文档与 references/ 文件、执行 Python/Bash 命令并传入 stdin、对存档目录读写的能力。

2. 开始与使用

启动 Agent 后直接输入：

开始游戏

也可以使用以下自然语言指令：

开始大世界模拟查看地图查看背包前往杭州城挑战眼前的刀客保存游戏退出游戏

正常游玩无需手动调用引擎；该命令主要用于安装验证和调试。

3. 存档目录

默认存档位置：

~/.wuxia/save/

自定义位置：

export WUXIA_RPG_SAVE_DIR=/绝对路径/wuxia-save

建议为不同部署实例设置不同存档目录，避免多个实例同时操作同一档位。

二、作为 DSH 插件使用

需先安装 Python 3 和 pnpm。安装器按顺序选择 DSH CLI：PATH 中的 dsh → $DSH_HOME/profiles/node_modules/@deepseek-ai/dsh 内置 CLI → npx --yes @deepseek-ai/dsh（需 Node.js 18+ 与 npm）。进入项目根目录执行：

chmod +x install.sh
./install.sh

脚本会自动：

1. 从源码构建插件，或校验发布包中的预构建产物；
2. 将带完整 Skill 的“武侠GM”Preset 安装到当前 $DSH_HOME；
3. 优先通过 dsh 接入插件；命令不在 PATH 时自动改用 npx --yes @deepseek-ai/dsh。

自定义 profile 或 DSH Home：

./install.sh --profile web --dsh-home /你的/dsh-home 安装后执行 dsh web；若没有全局命令，则执行 npx --yes @deepseek-ai/dsh web。选择“武侠GM”新建会话并输入“开始游戏”。若以后移动项目目录，请在新位置重新运行安装脚本以刷新插件链接。

三、部署自带 Web 套件与 agent-lite 底座

Web 套件提供完整浏览器界面、SSE 对话流和 /api/engine 兼容接口。Web 会启动独立的共享 Engine Service，并从 wuxia-rpg/tools.json 注册受限的 wuxia_ 工具。服务端及 agent-lite 均为 Python 标准库实现。

1. 准备目录

确保以下内容位于同一项目根目录：

cc-game-dsh/
├── wuxia-rpg/
├── web/
├── agent/
└── config.json

2. 配置 config.json

环境变量优先级高于 config.json。推荐从以下配置开始：

{
"backend_mode": "llm",
"server": {
"host": "127.0.0.1",
"port": 8000,
"frontend": "old"
},
"paths": {
"save_dir": "",
"skill_dir": ""
},
"engine": {
"service_url": "",
"timeout_ms": 120000
},
"llm": {
"base_url": "https://your-openai-compatible-endpoint.example/v1",
"api_token": "",
"model": "your-model"
}
}

通用配置

| 配置字段 | 环境变量 | 默认值 | 说明 |
| backend_mode | LLM_BACKEND | llm | GM 后端模式，默认 llm（agent-lite + 模型 API） |
| server.host | HOST | 127.0.0.1 | HTTP 监听地址 |
| server.port | PORT | 8000 | HTTP 监听端口 |
| server.frontend | WUXIA_FRONTEND | old | 使用原生 JavaScript 游戏界面 |
| paths.save_dir | WUXIA_RPG_SAVE_DIR | ~/.wuxia/save | 存档根目录 |
| paths.skill_dir | WUXIA_RPG_SKILL_DIR | 项目根/wuxia-rpg | Skill 目录 |
| engine.service_url | WUXIA_RPG_ENGINE_URL | 空 | 外部 Engine Service；为空时自动启动独立实例 |
| engine.timeout_ms | WUXIA_RPG_ENGINE_TIMEOUT_MS | 120000 | 引擎请求超时 |

llm 后端

llm 模式使用 agent/ 中的 agent-lite，直接连接 OpenAI 兼容接口。

| 配置字段 | 环境变量 | 说明 |
| llm.base_url | AGENT_API_BASE | OpenAI 兼容接口地址，通常包含 /v1 |
| llm.api_token | AGENT_API_TOKEN | Bearer Token；服务不要求鉴权时可留空 |
| llm.model | AGENT_MODEL | 模型名称 |

Web 的 agent-lite 只注册 use_skill、九个 wuxia_ 工具和受限的 wuxia_read_reference，不提供通用 read/write/bash/list。claude 后端仍受 Claude Code 自身权限模式约束。

3. 启动

从项目根目录执行：

python3 web/server.py

临时使用环境变量覆盖配置的示例：

HOST=127.0.0.1 PORT=9000 LLM_BACKEND=llm \
AGENT_API_BASE=http://127.0.0.1:8646/v1 \
AGENT_MODEL=your-model \
python3 web/server.py

4. 访问与使用

| 地址 | 界面 |
| http://127.0.0.1:8000/ | 原生 JavaScript 游戏界面 |
| http://127.0.0.1:8000/game | 原生 JavaScript 游戏界面 |
| http://127.0.0.1:8000/ui/vanilla/classic | 经典聊天界面 |
| http://127.0.0.1:8000/api/health | 服务健康检查 |

打开页面后输入“开始游戏”，即可新建角色、读取存档并进入游历。浏览器会保存会话 ID；游戏进度独立保存在 WUXIA_RPG_SAVE_DIR 中。

llm 后端的对话上下文保存在服务进程内存中，服务重启后会话上下文丢失，但游戏存档不受影响。

5. 生产部署建议

- 仅本机使用时，将 server.host 设为 127.0.0.1。
- 对外提供服务时，建议在前方部署带鉴权、HTTPS、请求大小限制和超时控制的反向代理。
- 不要把模型 API Token 提交到版本库；生产环境优先通过环境变量或密钥管理服务注入。
- 不建议多个 Web/DSH 实例同时写同一个存档目录。

常见问题

Skill 未触发或提示找不到 wuxia-rpg

检查目录层级是否为：

/wuxia-rpg/SKILL.md

并确认复制的是完整目录。DSH 一键安装后还可检查 dsh-plugin/skills/wuxia-rpg/SKILL.md（安装器同步）；随后重启或新建会话，让 Skill 重新扫描。

Web 的 llm 后端无响应

核对启动日志中的 AGENT_API_BASE、AGENT_MODEL 和 Token 状态，并确认模型服务支持 OpenAI 兼容的聊天与工具调用协议。

修改配置后没有生效环境变量优先于 config.json。先检查当前 shell、systemd、容器或反向代理配置中是否已经设置同名环境变量。

进一步文档

- 核心 GM 规则：wuxia-rpg/SKILL.md
- Web 套件说明：web/README.md
- agent-lite 说明：agent/README.md
- 玩家手册：docs/玩家手册.md
- 详细规则：docs/详细规则.md