DSH Ren'Py 开发工作台（dsh-renpy-dev）v1.2.0

支持 DSH 0.2.0-rc.2 及以上（0.1.x 的目录式 preset 已被引擎废除，本插件为 0.2.0 格式，无法在 0.1.x 上运行）。

一次对 DSH 核心思想的验证：agent preset + skills + web 插件三形态深度融合，自举构建的 Ren'Py 开发工作台。

在 DeepSeek Harness（DSH）内提供完整的 Ren'Py 游戏开发工作台：浏览器内编辑器（语法高亮含 Python 块、补全、查找替换、codicon 图标系统）、lint/运行/截图/自动化测试、保存历史与检查点回滚、工作区域锁定、写守卫、静态诊断与报错诊断面板、AI 学习注释、个性化设置（25 个颜色 token + 8 套预制配色）、15 个 Ren'Py 知识库（skill）+ 界面规范，以及可供 AI 直接调用的 13 个开发工具。

本仓库是开源仓库版（面向开发者/贡献者），含完整验证资产。普通使用者请用 Releases 里的发行版 zip（不含验证资产，更轻量）。

📦 文档导航：

• English version → README.en.md
• 部署流程（完整版，含三种模式/参数/故障排查/升级卸载）→ 见 DEPLOY.md
• 用户指南（功能/操作/预期/回归表 + 个人经验回传给开发者的方法）→ 见 GUIDE.md
• 测试用户功能手册（一站式：环境启动 + 逐功能详解 + 操作测试 + FAQ + 经验回传）→ 见 TESTER-GUIDE.md
• 知识流水线（15 个 skill 怎么生产出来的：提取→核验→引擎验证）→ 见 knowledge-pipeline.md
• 贡献指南（三层经验隔离 + 提交规范）→ 见 CONTRIBUTING.md
• 术语表（Ren'Py 中英术语对照）→ 见 glossary.md
• 快速上手 → 见下文。

许可

MIT License。

一、项目说明

1.1 这是什么

dsh-renpy-dev 是一套装在 DeepSeek Harness（DSH）里的 Ren'Py 游戏开发工作台：把一个普通的 AI 编程对话界面，扩展成带完整开发工具链的浏览器面板，让"看代码 → 改代码 → 验证 → 运行"的整个 Ren'Py 开发循环在浏览器内闭环完成，AI 全程参与但每一步都可审计、可回滚。

核心形态是 agent preset + skills + web 插件三形态深度融合：

这套工具本身也是用 DSH 自己的架构自举构建的——是对 DSH 核心思想（preset + skills + 插件三形态组合出专用开发环境）的一次完整验证。

1.2 设计理念

• 类 VSCode 工作台 + 类 Adobe 面板：活动栏/侧栏/编辑器/面板四区布局；面板可停靠、拖拽、浮动、最大化、布局持久化。
• 引擎事实优先：知识库全部经「源码核验 + lint 验证」生产（见 knowledge-pipeline.md），AI 的 Ren'Py 知识有据可依。
• 透明可审计：AI 每步改动实时可见（修改面板 diff + gutter 标记）、每次保存自动备份、每轮对话自动检查点——任何一步都可回滚。
• 安全双保险：工作范围（编辑与 AI 修改被锁定在区域内）+ 写守卫（保存前四层结构校验），防止人和 AI 破坏脚本。
• 零侵入部署：对 DSH 宿主的少量视觉调整（隐藏原生输入框、logo 品牌色）为运行时 CSS 注入，不改任何 DSH 安装文件。

1.3 架构（四层 + 共享核心）

┌─────────────────────────────────────────────────────────────┐
│ 界面层  renpy-client/lib/client.js  浏览器面板（编辑器/面板/设置）│
├─────────────────────────────────────────────────────────────┤
│ 宿主层  renpy-client/lib/host.js    39 个 /renpy-dev/* 端点  │
├─────────────────────────────────────────────────────────────┤
│ 共享核心 renpy-core.js              纯函数（诊断/守卫/解析/合并）│
├─────────────────────────────────────────────────────────────┤
│ 知识层  skills/renpy-*.md           15 个知识库 + 界面规范    │
├─────────────────────────────────────────────────────────────┤
│ 工具层  renpy-client/lib/           13 个 AI 工具 + 索引器    │
└─────────────────────────────────────────────────────────────┘

工作原理速览：

1.4 功能全景

1.5 知识库（skill）清单

AI 写 Ren'Py 代码时按需加载对应 skill；全部经「源码核验 + lint 验证」生产（见 knowledge-pipeline.md）。

1.6 Agent 工具清单

preset「RenPy Dev」注册给 AI 的 13 个开发工具（AI 在对话中可自主调用；工作台按钮与这些工具同源）。

二、文档目录

全部文档一览。测试用户只需 TESTER-GUIDE.md（一站式）；开发者/贡献者读其余。

各文档随版本持续更新；英文版见对应 .en.md。

三、快速部署（给使用者）

前置要求

完整部署流程、三种模式（已装 DSH / 连 DSH 一起装 / 官方桌面端）、参数与故障排查见 DEPLOY.md。

部署步骤

1. 解压本发布包到目标机器任意目录（如 D:\dsh-renpy-dev）。
2. 打开 PowerShell，进入该目录：

cd D:\dsh-renpy-dev
.\deploy.ps1

1. 脚本会依次：
   • 检测 DSH 并做版本闸门（0.1.x 直接拒绝并给出升级指引；未装则询问：手动安装后继续 / 用 -InstallDsh 自动装）
   • 检测 Ren'Py SDK（在常见位置找；找不到则提示你输入路径，不自动下载）
   • 复制 17 个 skill（16 个 renpy-* 知识库 + 界面规范）
   • 链接 dsh-renpy-dev-client 插件包，并建包内 node_modules junction（供 13 个工具解析 @deepseek-ai/dsh-tools）
   • 更新 web profile 并生成配置文件（preset 随插件包的 cordis.patch.yml 生效，不再单独部署）
2. 重启 dsh（完全退出后重新启动）。

想用官方桌面端（Electron）？ 上面的脚本只装 web profile；桌面端用独立的 desktop profile
（由 App 独占管理，命令行改不了），先跑完脚本，再按 DEPLOY.md §3 模式 C 加 bundle 并重启桌面端。
两者共用 ~/.dsh，skills / 运行配置 / 凭据不用重复装。

常用参数

.\deploy.ps1 -SdkPath D:\renpy-8.5.3-sdk   # 直接指定 SDK 目录
.\deploy.ps1 -InstallDsh                    # 目标机连 DSH 一起安装（npm 全局）
.\deploy.ps1 -DshHome D:\custom\.dsh        # 自定义 DSH 数据目录（一般不用）

Ren'Py SDK 下载（如果还没有）

• 官方下载页：https://www.renpy.org/latest.html
• 8.5.3 直链：https://www.renpy.org/dl/8.5.3/renpy-8.5.3-sdk.zip
• 解压后目录内应含 renpy.py 与 renpy.exe。

四、部署后验证

1. 重启 dsh，新建会话，preset 选择「RenPy Dev」。
2. 在会话页签中找到「Ren'Py」页签并打开。
3. 顶部输入项目路径（含 game/ 的 Ren'Py 项目根目录）→ 点 ⟳ 加载。
   • 没有项目？用对话框让 AI 执行 renpy_scaffold 生成一个，或让 AI 打开 SDK 自带示例（<SDK>\the_question）。
4. 快速冒烟：
   • 左侧出现文件树 → 点开一个 .rpy → 编辑器打开
   • 改一行 → Ctrl+S 保存 → 顶栏 ⚠ 检查 → lint 通过
   • 顶栏 ▶ 运行游戏 → 游戏窗口弹出 → 📷 截图 → 再点同一按钮（变 ■ 停止）停止

官方桌面端（Electron） 走同一套流程，但要先把 bundle 加进 desktop profile（DEPLOY.md §3 模式 C）。
若设置里「RenPy Dev」卡片显示红色「加载失败」且点不动，那是 preset 定义级挂载失败（不是插件没装），见 DEPLOY.md §7。

详细测试清单见 GUIDE.md。

五、目录结构

dsh-renpy-dev/
├── deploy.ps1                        # 一键部署脚本（入口）
├── README.md                         # 本文件（项目说明 + 文档目录 + 快速上手）
├── DEPLOY.md                         # 部署流程完整指南（三种模式/参数/排查/升级卸载）
├── GUIDE.md                        # 用户指南（功能/操作/预期/回归表）
├── TESTER-GUIDE.md                   # 测试用户功能手册（一站式：功能详解 + 测试 + FAQ）
├── knowledge-pipeline.md             # 知识生产方法论（提取→核验→引擎验证）
├── glossary.md                       # 中英术语对照表（翻译/本地化基准）
├── CONTRIBUTING.md                   # 贡献指南（三层经验隔离 + 提交规范）
├── LICENSE                           # MIT License
├── NOTICE                            # 第三方许可声明（Ren'Py / DSH）
├── skills/
│   ├── renpy-*.md                    # 16 个 Ren'Py 知识库 + workbench-ui 界面规范（按需加载）
│   └── workbench-ui.md               # 工作台界面样式设计规范（含图标系统）
├── verification/                     # 验证资产（仓库版独有）
│   ├── scripts/                      # 提取/验证脚本（extract-*.js、verify-text.py）
│   ├── extracts/                     # 结构化提取产物（*-extract.json）
│   ├── projects/                     # 17 个引擎验证项目 + eq-test
│   └── tests/                        # 22 个单测（node --check + 全量回归）
└── renpy-client/                     # 插件包（工作台 UI + /renpy-dev 服务 + agent preset + 13 个工具）
    ├── package.json                  # dsh.bundle.patch（bundle patch）+ 包导出 ./tools
    ├── cordis.patch.yml              # 两行：renpy-dev（宿主插件）+ preset-renpy（agent preset）
    └── lib/
        ├── host.js                   # 39 个 /renpy-dev/* 端点（需重启 dsh）
        ├── renpy-core.js             # 共享纯函数模块（lineDiff/hasOpenToolCall/诊断/守卫）
        ├── client.js                 # Ren'Py 面板 UI（刷新即生效；含 codicon 图标系统）
        ├── renpy-host.mjs            # 13 个 agent 工具（lint/index/scaffold/run/...）
        └── indexer.py                # 项目索引器（引擎 dump）

目录树中的 dsh-renpy-dev/ 即本仓库根（解压发布包后即为该目录名，部署时 cd 进入即可）。

部署产物（脚本写入目标机器）

插件统一挂到 ~/.dsh/profiles/node_modules/（dsh bundle 双锚点解析的第二锚点），
无论 DSH 是 npm 全局安装还是 npx 方式运行都能加载。
删除部署：移除以上位置的 renpy 相关项 + profiles/web/package.json 里的 dsh-renpy-dev-client 行即可。

六、运行时路径配置

部署脚本生成 ~/.dsh/renpy.config.json，插件运行时按以下优先级解析路径（无需改代码）：

1. 插件 config（0.2.0 起来自 renpy-client/cordis.patch.yml 里各行的 config；0.1.x 的 agent.cordis.yml 已废除）
2. ~/.dsh/renpy.config.json
3. 环境变量 RENPY_SDK_PATH / RENPY_USERDIR / RENPY_INDEXERPATH / RENPY_SKILLROOT
4. 默认推导（userDir = <sdk>/../.renpy-user 等）

重装/换机后只要重跑 deploy.ps1，配置自动更新。

七、部署与 DSH 原生元素（v1.1 起）

本插件会对 DSH 宿主界面做少量运行时视觉调整：

对部署流程的影响：无额外步骤。

• 以上均为运行时注入，不修改任何 DSH 安装文件（卸载面板/关闭页面即还原）；deploy.ps1 流程、插件 junction 链接、重启 dsh 生效的规则完全不变。
• ⚠️ 唯一注意：注入的 CSS 依赖 DSH 的 DOM 结构（类名后缀）。升级 DSH 后请回归验证两项注入是否仍生效（输入框不重复出现、侧栏 logo 为品牌色）；若失效，面板内对应代码位置（client.js 的注入 effect）需按新类名调整。
• skills 部署范围：deploy.ps1 复制 skills\*.md（16 个 renpy-* 知识库 + workbench-ui 界面规范，共 17 个）。
• 升级部署（v1.2 起）：先把 DSH 升到 0.2.0-rc.2 及以上（npm install -g @deepseek-ai/[email protected]）→ 重新解压发布包（或更新 renpy-client/ 与 skills/）→ 重跑 deploy.ps1（脚本含版本闸门，并会重建插件包 junction 与包内 node_modules junction）→ 完全退出并重启 dsh。
• ⚠️ 版本必须匹配：本发布包内的插件是 0.2.0 格式（宿主侧用 ctx.shell.execute、preset 走 bundle patch 行）。把插件包 junction 进 0.1.x 的 DSH，工作台会直接失效；务必先升级 DSH 再重启。

八、版本说明

• v1.2.0：迁移到 DSH 0.2.0-rc.2+。目录式 agent preset 已被引擎废除 → preset 改为插件包 renpy-client/cordis.patch.yml 里的一行 @deepseek-ai/dsh-agent-preset；工具插件改由包导出子路径 dsh-renpy-dev-client/tools 加载；新增包内 node_modules junction；deploy.ps1 增加版本闸门（拒绝 0.1.x）；修复 preset 定义级挂载失败（renpy-host.mjs 的 apply 缺 config 默认值 → 设置里「RenPy Dev」卡片显示「加载失败」且点不动）；新增**官方桌面端（Electron）**部署指引（DEPLOY.md §3 模式 C）。
• 面向 Ren'Py 8.5.x（本地 SDK 锁定 8.5.3）。
• 打包（distribute）暂不支持：SDK 打包在 launcher 内部，本插件只覆盖 build.rpy 配置知识（renpy-build skill）。
• 变更记录与实现细节见各版本 Releases 说明；贡献方式见 CONTRIBUTING.md。