AIRP — AI 互动角色扮演模式（DeepSeek Harness）

Name: IcyOct/dsh-airp
Author: IcyOct

English: README.en.md

AIRP（AI RolePlay） 是运行在 DeepSeek Harness（dsh）之上的 AI 互动角色扮演 Agent 模式，对标 SillyTavern 的玩法与数据生态：角色卡 / 世界书 / 预设 / 多 API / 提示词管线 / 聊天运行时，并附带一个 SillyTavern 风格的 Web 前端（/airp 路由插件）。

社区项目，非 DeepSeek 官方产品。 DeepSeek Harness 尚在 developer preview，兼容性可能随版本变化；请按发布版本安装使用。

✨ 功能特性

能力	说明
🎭 角色卡	导入/导出 PNG `tEXt/iTXt chara` 与 JSON，兼容 V1 / V2 / V3；支持 Chub / JanitorAI UUID 在线导入
📖 世界书（Lorebook）	ST 标准 / NovelAI / RisuAI / AngAI 自动转换；六步激活算法：扫描 → 匹配 → 排序 → 抽样与驻留（sticky/cooldown/delay）→ 递归扫描 → token 预算
⚙️ 预设（Preset）	Chat Completion / Text Completion；`prompt_order`、Instruct/Context 模板、采样参数、旧字段自动迁移；Web 端可视化编辑
🔌 多 API	OpenAI 兼容端点（自定义 Base URL）/ Anthropic / OpenRouter / Ollama / LM Studio / KoboldAI / text-generation-webui / NovelAI；SSE 流式、指数退避重试、超时、模型目录、连接测试
💬 聊天运行时	每角色多聊天、重roll（swipe 保留候选）、继续、匿名扮演、分支、编辑/删除/插入消息、群聊、作者注、token 计数、上下文用量进度条、User Persona
🌐 Web 前端	SillyTavern 风格 SPA（`/airp`）：角色/世界书/预设/API/设置五页签、亮/暗主题、桌面与移动端响应式、本地文件上传导入、零外部 CDN
🧩 对话式管理	dsh 会话中经 `airp_*` 工具完成全部管理（导入/选择/挂载/配置/导出），角色内回复必须经 `airp_chat` 生成，保证提示词管线真正生效
🔒 安全	API Key AES-256-GCM 加密落盘；路径沙箱防穿越；导入大小/PNG 块级上限（防 zip bomb）；错误信息脱敏；仅监听 loopback

📸 截图

聊天视图（亮）	聊天视图（暗）

角色管理	世界书	预设

API 连接	设置	移动端

🗂 仓库结构

dsh-airp/
├── agent-preset/           # dsh agent preset：AIRP 模式本体
│   ├── agent.cordis.yml    #   组合：persona + 6 个引擎插件 + skill
│   ├── preset.yml          #   模式名/描述（GUI preset 选择器显示）
│   ├── plugins/            #   本地插件：core / import / prompt / providers / chat / commands
│   ├── lib/                #   纯函数库（零依赖）：char-card / lorebook / preset / prompt /
│   │                       #   providers / store / seal / token / template / regex / sse / retry …
│   ├── fixtures/           #   文档样例 + 测试数据（含 V3 PNG 角色卡）
│   ├── test/               #   80 项测试（解析器 + golden + 存储 + SSE + 模板）
│   └── skills/airp/        #   操作手册（随 preset 挂载）
├── web-ui/                 # Web 前端插件（profiles/web 本地插件）
│   ├── airp-ui.mjs         #   插件入口：注册 /airp 路由 + tapIndex 注入
│   └── airp-ui/            #   engine（生成编排）/ api（REST+SSE）/ app（SPA）/ test / e2e
├── prompts/                # 模式与前端方案的设计/执行提示词（v1.0 规格文档）
├── docs/                   # 安装 / 使用 / 架构文档
├── scripts/                # 一键安装脚本（PowerShell / Shell）
├── screenshots/            # 产品截图
├── LICENSE                 # MIT
└── SECURITY.md             # 安全披露政策

🚀 快速安装

环境要求：DeepSeek Harness（rc.6 及以上）、Node.js ≥ 20.11（纯 ESM，零外部依赖）。

# 1) 克隆仓库
git clone https://github.com/IcyOct/dsh-airp.git
cd dsh-airp

# 2) 安装 agent preset（AIRP 模式本体）
#    Windows：
powershell -ExecutionPolicy Bypass -File scripts/install.ps1
#    macOS / Linux：
bash scripts/install.sh

安装脚本会完成：

复制 agent-preset/ → $DSH_HOME/.agent-presets/airp；
复制 web-ui/airp-ui.mjs 与 web-ui/airp-ui/ → $DSH_HOME/profiles/web/；
在 $DSH_HOME/profiles/web/cordis.patch.yml 幂等追加 - insert: airp-ui 行；
打印验证命令与访问地址。

然后 重启 dsh：

打开 http://127.0.0.1:<端口>/airp 进入 Web 前端；
或在 dsh 新会话选择 AIRP模式 preset，进入对话式角色扮演。

手工安装 / 回滚 / 故障排查见 docs/install.md。

🎮 使用方式

AIRP 提供两种使用形态：

1. Web 前端（推荐，SillyTavern 风格）

打开 http://127.0.0.1:<端口>/airp（或 dsh 原生界面右下角 🎭 AIRP 面板 入口）；
角色页：输入角色卡路径 / URL / UUID，或 📁 浏览本地 .png / .json 文件导入；
点击角色 → ＋新聊天（自动呈现开场白）→ 输入剧情消息，SSE 流式回复；
消息悬停可编辑/删除/复制；底部 继续 / 扮演 / 重roll；
世界书、预设、API、设置页签管理其余能力。

2. dsh 会话模式（对话式）

新会话选择 AIRP模式 preset；
告诉它"导入角色卡"并提供路径/URL/UUID（可用样例 agent-preset/fixtures/linwan-v3.png）；
选中角色并开场，之后的剧情输入自动经 airp_chat 生成角色回复；
管理请求（导入/查看/设置/导出）用对话完成，/help 随时查看能力清单。

详细指南见 docs/usage.md，架构与设计决策见 docs/architecture.md。

🧪 测试

# agent preset：80 项测试
cd agent-preset
node test/char-card.test.mjs      # 角色卡解析（V1/V2/V3、PNG chara）
node test/lorebook.test.mjs       # 世界书激活算法
node test/preset.test.mjs         # 预设解析与字段迁移
node test/prompt.golden.test.mjs  # 提示词构建 golden test
node test/providers.test.mjs      # 多 API 请求体 / SSE / 重试
node test/store.test.mjs          # 存储 / 分支 / 路径沙箱 / 密钥加密
node test/regex.test.mjs          # 正则替换
node test/template.test.mjs       # {{var}} / {{#each}} / {{#if}}
node test/token.test.mjs          # token 计数与截断
node test/smoke.test.mjs          # 导入→开场→对话→swipe→分支 端到端

# web-ui：33 项测试
cd ../web-ui/airp-ui
node test/engine.test.mjs
node test/api.test.mjs
node test/sse.test.mjs

# 端到端（需 dsh 实例运行中）
node e2e-live.mjs <port>          # 主流程 26 项
node e2e-features.mjs <port>      # 上传导入 / models / 回归 9 项
node e2e-st.mjs <port>            # 用户设定 / 预设编辑 / OpenRouter 真实生成

🔗 兼容性矩阵

数据	格式	状态
角色卡	V3（`chara_card_v3`）JSON / PNG	✅ 测试覆盖
角色卡	V2（`chara_card_v2`）JSON / PNG	✅
角色卡	V1（平铺）JSON	✅
角色卡	Chub / JanitorAI 公开 API（UUID）	✅ 实现（需网络）
世界书	ST 标准 JSON	✅
世界书	NovelAI JSON / PNG（`ccv3`）	✅
世界书	RisuAI / AngAI	✅ 自动转换
预设	ST Chat Completion（含 `message_after_an` 别名）	✅
预设	ST Text Completion（Context + Instruct 模板）	✅
预设	旧字段（`generation_*` → sampler）	✅ 自动迁移
API	OpenAI 兼容 / OpenRouter / Ollama / LM Studio	✅（流式 + 重试 + 超时）
API	Anthropic Messages	✅（system 抽取、SSE）
API	KoboldAI / text-generation-webui	✅
API	NovelAI	✅ 实现（需 accessToken，未实测）

🔒 安全

密钥：API Key 经 lib/seal.mjs（AES-256-GCM + 安装级 .secret）加密落盘到 $DSH_HOME/airp/settings/keys.json，任何 API 响应、日志、前端响应均不含密钥明文（允许 ***后4位）；
边界：数据只发送到用户配置的端点；Web 插件仅监听 loopback；
导入：本地/远程文件 10MB 上限、PNG 块级 4MB/16MB/4096 块上限、压缩 iTXt 拦截（防 zip bomb）；导入内容只读、白名单转换，不执行任何代码；
路径：所有路径参数经 store 沙箱 + assertIdParam 校验，防路径穿越；
正则：ReDoS 复杂度预检与超时；
错误：统一脱敏（密钥 / URL / 超长截断），不在前端展示未处理的原始报错。

详见 SECURITY.md 与 docs/architecture.md 的威胁模型章节。

📄 许可证

AIRP — AI 互动角色扮演模式（DeepSeek Harness）

English: README.en.md

社区项目，非 DeepSeek 官方产品。 DeepSeek Harness 尚在 developer preview，兼容性可能随版本变化；请按发布版本安装使用。

✨ 功能特性

能力	说明
🎭 角色卡	导入/导出 PNG `tEXt/iTXt chara` 与 JSON，兼容 V1 / V2 / V3；支持 Chub / JanitorAI UUID 在线导入
📖 世界书（Lorebook）	ST 标准 / NovelAI / RisuAI / AngAI 自动转换；六步激活算法：扫描 → 匹配 → 排序 → 抽样与驻留（sticky/cooldown/delay）→ 递归扫描 → token 预算
⚙️ 预设（Preset）	Chat Completion / Text Completion；`prompt_order`、Instruct/Context 模板、采样参数、旧字段自动迁移；Web 端可视化编辑
🔌 多 API	OpenAI 兼容端点（自定义 Base URL）/ Anthropic / OpenRouter / Ollama / LM Studio / KoboldAI / text-generation-webui / NovelAI；SSE 流式、指数退避重试、超时、模型目录、连接测试
💬 聊天运行时	每角色多聊天、重roll（swipe 保留候选）、继续、匿名扮演、分支、编辑/删除/插入消息、群聊、作者注、token 计数、上下文用量进度条、User Persona
🌐 Web 前端	SillyTavern 风格 SPA（`/airp`）：角色/世界书/预设/API/设置五页签、亮/暗主题、桌面与移动端响应式、本地文件上传导入、零外部 CDN
🧩 对话式管理	dsh 会话中经 `airp_*` 工具完成全部管理（导入/选择/挂载/配置/导出），角色内回复必须经 `airp_chat` 生成，保证提示词管线真正生效
🔒 安全	API Key AES-256-GCM 加密落盘；路径沙箱防穿越；导入大小/PNG 块级上限（防 zip bomb）；错误信息脱敏；仅监听 loopback

📸 截图

聊天视图（亮）	聊天视图（暗）

角色管理	世界书	预设

API 连接	设置	移动端

🗂 仓库结构

dsh-airp/
├── agent-preset/           # dsh agent preset：AIRP 模式本体
│   ├── agent.cordis.yml    #   组合：persona + 6 个引擎插件 + skill
│   ├── preset.yml          #   模式名/描述（GUI preset 选择器显示）
│   ├── plugins/            #   本地插件：core / import / prompt / providers / chat / commands
│   ├── lib/                #   纯函数库（零依赖）：char-card / lorebook / preset / prompt /
│   │                       #   providers / store / seal / token / template / regex / sse / retry …
│   ├── fixtures/           #   文档样例 + 测试数据（含 V3 PNG 角色卡）
│   ├── test/               #   80 项测试（解析器 + golden + 存储 + SSE + 模板）
│   └── skills/airp/        #   操作手册（随 preset 挂载）
├── web-ui/                 # Web 前端插件（profiles/web 本地插件）
│   ├── airp-ui.mjs         #   插件入口：注册 /airp 路由 + tapIndex 注入
│   └── airp-ui/            #   engine（生成编排）/ api（REST+SSE）/ app（SPA）/ test / e2e
├── prompts/                # 模式与前端方案的设计/执行提示词（v1.0 规格文档）
├── docs/                   # 安装 / 使用 / 架构文档
├── scripts/                # 一键安装脚本（PowerShell / Shell）
├── screenshots/            # 产品截图
├── LICENSE                 # MIT
└── SECURITY.md             # 安全披露政策

🚀 快速安装

环境要求：DeepSeek Harness（rc.6 及以上）、Node.js ≥ 20.11（纯 ESM，零外部依赖）。

# 1) 克隆仓库
git clone https://github.com/IcyOct/dsh-airp.git
cd dsh-airp

# 2) 安装 agent preset（AIRP 模式本体）
#    Windows：
powershell -ExecutionPolicy Bypass -File scripts/install.ps1
#    macOS / Linux：
bash scripts/install.sh

安装脚本会完成：

复制 agent-preset/ → $DSH_HOME/.agent-presets/airp；
复制 web-ui/airp-ui.mjs 与 web-ui/airp-ui/ → $DSH_HOME/profiles/web/；
在 $DSH_HOME/profiles/web/cordis.patch.yml 幂等追加 - insert: airp-ui 行；
打印验证命令与访问地址。

然后 重启 dsh：

打开 http://127.0.0.1:<端口>/airp 进入 Web 前端；
或在 dsh 新会话选择 AIRP模式 preset，进入对话式角色扮演。

手工安装 / 回滚 / 故障排查见 docs/install.md。

🎮 使用方式

AIRP 提供两种使用形态：

1. Web 前端（推荐，SillyTavern 风格）

打开 http://127.0.0.1:<端口>/airp（或 dsh 原生界面右下角 🎭 AIRP 面板 入口）；
角色页：输入角色卡路径 / URL / UUID，或 📁 浏览本地 .png / .json 文件导入；
点击角色 → ＋新聊天（自动呈现开场白）→ 输入剧情消息，SSE 流式回复；
消息悬停可编辑/删除/复制；底部 继续 / 扮演 / 重roll；
世界书、预设、API、设置页签管理其余能力。

2. dsh 会话模式（对话式）

新会话选择 AIRP模式 preset；
告诉它"导入角色卡"并提供路径/URL/UUID（可用样例 agent-preset/fixtures/linwan-v3.png）；
选中角色并开场，之后的剧情输入自动经 airp_chat 生成角色回复；
管理请求（导入/查看/设置/导出）用对话完成，/help 随时查看能力清单。

详细指南见 docs/usage.md，架构与设计决策见 docs/architecture.md。

🧪 测试

# agent preset：80 项测试
cd agent-preset
node test/char-card.test.mjs      # 角色卡解析（V1/V2/V3、PNG chara）
node test/lorebook.test.mjs       # 世界书激活算法
node test/preset.test.mjs         # 预设解析与字段迁移
node test/prompt.golden.test.mjs  # 提示词构建 golden test
node test/providers.test.mjs      # 多 API 请求体 / SSE / 重试
node test/store.test.mjs          # 存储 / 分支 / 路径沙箱 / 密钥加密
node test/regex.test.mjs          # 正则替换
node test/template.test.mjs       # {{var}} / {{#each}} / {{#if}}
node test/token.test.mjs          # token 计数与截断
node test/smoke.test.mjs          # 导入→开场→对话→swipe→分支 端到端

# web-ui：33 项测试
cd ../web-ui/airp-ui
node test/engine.test.mjs
node test/api.test.mjs
node test/sse.test.mjs

# 端到端（需 dsh 实例运行中）
node e2e-live.mjs <port>          # 主流程 26 项
node e2e-features.mjs <port>      # 上传导入 / models / 回归 9 项
node e2e-st.mjs <port>            # 用户设定 / 预设编辑 / OpenRouter 真实生成

🔗 兼容性矩阵

数据	格式	状态
角色卡	V3（`chara_card_v3`）JSON / PNG	✅ 测试覆盖
角色卡	V2（`chara_card_v2`）JSON / PNG	✅
角色卡	V1（平铺）JSON	✅
角色卡	Chub / JanitorAI 公开 API（UUID）	✅ 实现（需网络）
世界书	ST 标准 JSON	✅
世界书	NovelAI JSON / PNG（`ccv3`）	✅
世界书	RisuAI / AngAI	✅ 自动转换
预设	ST Chat Completion（含 `message_after_an` 别名）	✅
预设	ST Text Completion（Context + Instruct 模板）	✅
预设	旧字段（`generation_*` → sampler）	✅ 自动迁移
API	OpenAI 兼容 / OpenRouter / Ollama / LM Studio	✅（流式 + 重试 + 超时）
API	Anthropic Messages	✅（system 抽取、SSE）
API	KoboldAI / text-generation-webui	✅
API	NovelAI	✅ 实现（需 accessToken，未实测）

🔒 安全

密钥：API Key 经 lib/seal.mjs（AES-256-GCM + 安装级 .secret）加密落盘到 $DSH_HOME/airp/settings/keys.json，任何 API 响应、日志、前端响应均不含密钥明文（允许 ***后4位）；
边界：数据只发送到用户配置的端点；Web 插件仅监听 loopback；
导入：本地/远程文件 10MB 上限、PNG 块级 4MB/16MB/4096 块上限、压缩 iTXt 拦截（防 zip bomb）；导入内容只读、白名单转换，不执行任何代码；
路径：所有路径参数经 store 沙箱 + assertIdParam 校验，防路径穿越；
正则：ReDoS 复杂度预检与超时；
错误：统一脱敏（密钥 / URL / 超长截断），不在前端展示未处理的原始报错。

详见 SECURITY.md 与 docs/architecture.md 的威胁模型章节。

IcyOct/dsh-airp

AIRP — AI 互动角色扮演模式（DeepSeek Harness）

✨ 功能特性

📸 截图

🗂 仓库结构

🚀 快速安装

🎮 使用方式

1. Web 前端（推荐，SillyTavern 风格）

2. dsh 会话模式（对话式）

🧪 测试

🔗 兼容性矩阵

🔒 安全

📄 许可证

Community comments

IcyOct/dsh-airp

AIRP — AI 互动角色扮演模式（DeepSeek Harness）

✨ 功能特性

📸 截图

🗂 仓库结构

🚀 快速安装

🎮 使用方式

1. Web 前端（推荐，SillyTavern 风格）

2. dsh 会话模式（对话式）

🧪 测试

🔗 兼容性矩阵

🔒 安全

📄 许可证

Community comments