dsh-cc-studio · CCv3 角色卡工坊

从一句话点子到可导入 SillyTavern / Risu 的 chara_card_v3。专治「只有点子，世界观薄弱」。

DSH（DeepSeek Harness）插件：输入框上方的胶囊 → 全屏融合工坊，配合 CC 模式 预设让 LLM 通过 14 个 Tool 先问再填、与你共创角色卡，最后一键导出 JSON / PNG / CHARX。

安装

1. 从 GitHub 安装（推荐）

dsh plugin --profile web add github:xia-sc/dsh-cc-studio

dsh plugin 只是把参数转发给 profile 目录（~/.dsh/profiles/web）里的 pnpm；装完 dsh 会把 @dsh-plugins/dsh-cc-studio 自动追加到该 profile 的 dsh.profile.bundles，不需要手改 package.json。

• 锁定版本 / 指定分支：github:xia-sc/dsh-cc-studio#v0.3.0、...#master（tag 见仓库 Tags）。
• allowBuilds 提示：本插件没有 prepare 构建脚本，正常安装不会触发 pnpm 的构建拦截；若 pnpm 仍打印该提示，把提示里给出的键加进 ~/.dsh/profiles/web/pnpm-workspace.yaml 的 allowBuilds 后重跑。
• 在 DSH 会话里由 Agent 执行时：写入位置在会话工作区之外，需先把文件权限切到 danger-full-access；自己在终端执行则无此限制。

2. 从本地仓库安装（开发 / 调试）

git clone https://github.com/xia-sc/dsh-cc-studio.git
cd dsh-cc-studio
dsh plugin --profile web add .

相对路径按你执行命令时所在的目录解析（dsh 会先把 .、./xxx 重写成绝对路径再交给 pnpm，避免误链到 profile 目录）。装出来的是 link: 到源码目录：改 lib/*.js 后重启 dsh web 生效；只改 lib/client.js 时刷新页面即可（若同时跑着 dsh 仓库的 pnpm run dev:web，客户端 bundle 会重建，连刷新都省了）。

3. CC 预设（已自动安装，无需手工拷贝）

插件挂载时会自动把 presets/cc 装到 <DSH_HOME>/.agent-presets/cc（DSH_HOME 默认 ~/.dsh），目录名固定为 cc——宿主与客户端都按 preset id cc 判定 CC 模式。装完插件、启动 dsh web 后即可在会话模式里选到 CC 模式。

之所以需要这一步：dsh 的预设发现只扫三个根——shipped 根（dsh-agent-presets 包内自带）+ 部署 config.roots + 用户根 <DSH_HOME>/.agent-presets；插件包内的 presets/ 不在其中，「随包分发」≠「已注册」。所以由插件在启动时把它装进用户根。

更新策略是幂等的，且绝不静默覆盖你的改动：

安装记录是预设目录里的 .dsh-cc-studio-preset.json（记版本与各文件写入时的 sha256）。若出现「已保留未覆盖」的告警而你想改用插件模板，二选一：

# A. 删掉旧目录，重启 dsh web 即重新自动安装
Remove-Item "$env:USERPROFILE\.dsh\.agent-presets\cc" -Recurse -Force

# B. 用环境变量强制覆盖后重启 dsh web（macOS / Linux）
DSH_CC_STUDIO_PRESET_INSTALL=force dsh web   # auto（默认）| force | off

# B. 同上（Windows PowerShell）
$env:DSH_CC_STUDIO_PRESET_INSTALL = 'force'; dsh web

也可在插件行声明 config.presetInstall（需自己写 overlay patch），它的优先级高于环境变量。off 时请按下面的手工方式自行管理预设。

# Windows PowerShell（GitHub 安装）
$src = "$env:USERPROFILE\.dsh\profiles\web\node_modules\@dsh-plugins\dsh-cc-studio\presets\cc"
Copy-Item $src "$env:USERPROFILE\.dsh\.agent-presets\cc" -Recurse -Force

# 本地仓库开发时改用：$src = ".\presets\cc"

# macOS / Linux（GitHub 安装）
mkdir -p ~/.dsh/.agent-presets/cc
cp -R ~/.dsh/profiles/web/node_modules/@dsh-plugins/dsh-cc-studio/presets/cc/. ~/.dsh/.agent-presets/cc/

卸载/删除插件不会删除 <DSH_HOME>/.agent-presets/cc/（自动安装也不注册删除动作）。

4. 重启与验证

# 宿主行在启动时组合，装完必须重启 dsh web
dsh web

# 配置里应出现插件行
dsh --profile web --dump-config | findstr dsh-cc-studio   # Windows
dsh --profile web --dump-config | grep dsh-cc-studio      # macOS / Linux

# —— 以下两项自检需要会话 cookie：用 dsh web 启动时打印的 token 换取 ——
TOKEN='<dsh web 打印的 token>'
COOKIE=$(curl -s -D - -o /dev/null "http://127.0.0.1:3080/?token=$TOKEN" \
  | sed -n 's/^[Ss]et-[Cc]ookie:[[:space:]]*\(dsh-auth-[^;]*\).*/\1/p' | head -1)

# 客户端资源应返回 200。地址形如 /plugins/??<包名>/client.js&rev=<内容哈希>：
# 缺 ?? 或缺 rev 都会 404，而 rev 每次改 lib/client.js 都会变，所以从首页里取。
ASSET=$(curl -s http://127.0.0.1:3080/ -H "cookie: $COOKIE" \
  | grep -o '/plugins/??@dsh-plugins/dsh-cc-studio/client\.js&rev=[0-9a-f]*' | head -1)
curl -s -o /dev/null -w "%{http_code}  $ASSET\n" "http://127.0.0.1:3080$ASSET" -H "cookie: $COOKIE"
# -> 200  /plugins/??@dsh-plugins/dsh-cc-studio/client.js&rev=…

# RPC 自检（与其它 /api 同源：需要宿主/Origin 围栏 + 会话 cookie）
curl -s http://127.0.0.1:3080/dsh-cc-studio-rpc/ping \
  -H 'content-type: application/json' \
  -H "cookie: $COOKIE" \
  --data '{"type":"client-request","rpcId":"smoke","method":"ping","payload":{}}'
# -> {"type":"server-response","rpcId":"smoke","result":{"ok":true,"value":{"ok":true,"time":...}}}

Windows PowerShell 等价写法（rev 同样从首页取）：

$TOKEN='<dsh web 打印的 token>'
$s=New-Object Microsoft.PowerShell.Commands.WebRequestSession
$null=Invoke-WebRequest "http://127.0.0.1:3080/?token=$TOKEN" -WebSession $s -UseBasicParsing
$idx=(Invoke-WebRequest 'http://127.0.0.1:3080/' -WebSession $s -UseBasicParsing).Content
$asset=[regex]::Match($idx,'/plugins/\?\?@dsh-plugins/dsh-cc-studio/client\.js&rev=[0-9a-f]+').Value
Invoke-WebRequest "http://127.0.0.1:3080$asset" -WebSession $s -UseBasicParsing | Select-Object StatusCode

首页（/）与 RPC 端点都受会话 cookie 保护，不带 cookie 会得到 401 dsh web authentication required，这是正常行为，不代表插件没装上。会话 cookie 的名字不是 dsh-auth-127.0.0.1:3080，而是 dsh-auth- + base64url(sha256(权威段))，本机即 dsh-auth-VPhEEcLKeqRDBoBalzN2Nm7CnfxKhLE00pKIDWxt1sw——从浏览器 devtools 抄，或用上面的 token 换取。另外，资源地址 /plugins/??…&rev=… 本身不走鉴权，缺 ?? / rev 只会 404，别把 404 误判成鉴权问题。浏览器刷新页面后切到 CC 模式 会话，输入框上方出现胶囊即安装成功。

5. 更新与卸载

# 更新到默认分支（master）最新提交：重新执行 add，pnpm 会重新解析
dsh plugin --profile web add github:xia-sc/dsh-cc-studio

# 若解析未前移，先移除再装
dsh plugin --profile web remove @dsh-plugins/dsh-cc-studio
dsh plugin --profile web add github:xia-sc/dsh-cc-studio

# 卸载（dsh 会同步把它从 dsh.profile.bundles 移除）
dsh plugin --profile web remove @dsh-plugins/dsh-cc-studio

记录在 ~/.dsh/cc-library/ 的角色卡与 ~/.dsh/cc-drafts/ 的会话草稿不会被卸载流程删除。

6. 常见问题

快速上手

1. 新建会话，会话模式选 CC 模式（胶囊随即出现在输入框上方）。
2. 直接说需求：「我想做雨城记忆典当行老板娘，世界观很薄」。
3. LLM 按 6 步推进，每一步都会先问你 1-2 个问题再落笔；每次调用 Tool，胶囊与工坊实时刷新： cc_get_card（总结进度并提问）→ cc_patch_character（讨论气质/关系后填四件套）→ cc_patch_world（讨论世界侧重后补 ≥3 维，autoLorebook）→ cc_add_lorebook_entries（讨论触发词后补 ≥5，至少 1 条 constant）→ cc_patch_greetings（讨论场景后补问候语）→ cc_validate。
4. 随时点胶囊进工坊手改。校验通过后：侧栏 ★ 保存当前（已载入 ID 时原地覆盖，未载入则新建 ID）或 ＋ 另存为新，或导出 JSON / PNG / CHARX。后续可按 ID 载入/重命名/导出/删除（顶部 已载入 ID:xxxx 高亮当前卡），也可以直接对模型说「帮我载入 ID xxxx」。

特性

融合工坊（客户端）

• 布局：输入框上方胶囊（CC 模式自动出现）→ shell.overlay 全屏工坊，左侧导航 4 页（5维世界观 / 角色细化 / 世界书 / 校验导出）/ 自适应主区 / 280px 已存角色侧栏 / 360px 实时 card.json 预览。深浅色自适应（DSW Token + 品牌紫 #7c5cff 固定）。
• 风格标签：在「角色细化」中以逗号分隔编辑 tags，实时写回 data.tags。
• 5 维世界观：年表 / 势力 / 地理 / 力量体系 / 日常 → cc_patch_world(autoLorebook=true) 自动生成带 @@position / @@depth / @@activate 的 Lorebook 条目（至少 1 条 constant 常驻；再次调用自动覆盖旧自动条目、保留手动条目）。每维为预览卡片 + 展开大框编辑（小卡显示 140 字预览/字数，点击卡片或「⛶ 编辑」弹出 720px 大框）。
• 全量长文本大框编辑：description / personality / scenario / system_prompt / post_history_instructions / first_mes / alternate_greetings / group_only_greetings / mes_example / creator_notes 全部是「标签 + 右上 ⛶」的小框 + 720px 大框，实时同步，解决多行长文在小框里难预览/编辑。
• 已存角色侧栏（ID 化 CRUD）：280px 可折叠，高亮当前载入卡（紫框 + 顶部 已载入 ID:xxxx，显示 ID 前 8 位），★ 保存当前 在已载入 ID 时原地覆盖、＋ 另存为新 强制新建、✎ 重命名 / ＋ 新建；搜索/载入/导出/删除落盘 ~/.dsh/cc-library/<id>.json。
• 导入导出：⬆ 导入 JSON/PNG/CHARX 自动识别容器；⬇ JSON / ⬇ PNG（1×1 占位图）/ ⬆ 写入 PNG（写入你上传的任意 PNG，自动剥离旧 ccv3/chara 块并 CRC32 重算）/ ⬇ CHARX（打包 card.json）。
• 中英双语：完整 zh / en 词表（locale: dshCcStudio），跟随全局 设置 → 通用 → 语言 自动切换（胶囊/工坊/设置即时刷新，插件内无手动开关）。
• 深浅色自适应：全量使用 var(--dsw-alias-bg-* / border-l1/l2 / label-primary/secondary)，主按钮/选中态固定品牌紫，刷新即生效。

CC 模式（模型侧 14 个 Tool）

• 6 步工作流 + 共创约束：每步前 LLM 必须用 1-2 个开放问题征求偏好（气质/关系/世界侧重/触发词/开场场景等），严禁未讨论就一次性推断填满；角色四件套 → 五维 ≥3 → 世界书 ≥5 → 问候语 → cc_validate 才可收口。 cc_get_card / cc_patch_character / cc_patch_world / cc_add_lorebook_entries / cc_patch_greetings / cc_validate
• Lorebook 精细管理：cc_delete_lorebook_entries / cc_update_lorebook_entry。
• 已存库 CRUD（与侧栏共享 ID）：cc_list_library / cc_save_to_library / cc_load_from_library / cc_delete_from_library / cc_rename_in_library / cc_get_library_entry——用户说「帮我更新/载入 ID xxxx」时模型可直接操作，无需手动点 UI。

校验与规范

• 宿主实时校验：spec / group_only_greetings 必填、主图标唯一性、正则合法性，spec: chara_card_v3 / spec_version: 3.0。
• CCv3 全覆盖：name / nickname / tags / description / personality / scenario / system_prompt / post_history_instructions / first_mes / alternate_greetings / group_only_greetings / mes_example / creator_notes / assets / character_book，支持 CBS {{char}} / {{random}} / {{roll}}。

结构

dsh-cc-studio/
├── package.json          # @dsh-plugins/dsh-cc-studio, dsh.bundle.patch + dsh.client, exports ./client ./agent
├── cordis.patch.yml      # 宿主行插入：id dsh-cc-studio
├── lib/
│   ├── index.js          # host: /dsh-cc-studio-rpc（validate, cc_getDraft/cc_setDraft/cc_patchDraft, cc_isCcMode,
│   │                     #   cc_validateDraft, 已存库 cc_*Library, 容器 cc_importFromPng/cc_exportPng(+imageB64)/
│   │                     #   cc_importFromCharx/cc_exportCharx, CRC32/ZIP/STORE&DEFLATE）
│   ├── agent.js          # CC 模式 Tools：6 步共创 + 2 Lorebook 管理 + 6 已存库 CRUD = 14 个，含「先与用户讨论」提示
│   └── client.js         # client: dock 胶囊 + overlay 工坊 + settings.section（DSW Token 深浅色、品牌紫、
│                         #   五维回显、长文本大框、JSON/PNG/CHARX 导入导出/写入）
├── presets/cc/           # CC 模式预设模板（共创 persona + cc-studio-agent）
│   ├── preset.yml
│   └── agent.cordis.yml
├── prototypes/           # A/B 融合前的对比原型（H5，浏览器直接打开）
│   ├── index.html
│   ├── prototype-a.html  # 轻量浮层
│   └── prototype-b.html  # 侧边常驻
├── tests/
│   └── rpc-channel.test.mjs  # host 半 RPC 通道回归（假 ctx + 真实 http，23 项断言）
├── CHANGELOG.md          # 完整版本历史
├── README.md             # 中文（默认）
└── README_EN.md          # English

dsh-cc-agent 已于 5f95110 合并为 lib/agent.js（@dsh-plugins/dsh-cc-studio/agent），无需单独安装；CC 模式 预设仅挂该单一来源，不污染 standard。

开发与测试

pnpm test                                  # = node tests/rpc-channel.test.mjs
node tests/rpc-channel.test.mjs            # host 半 RPC 通道回归（23 项断言）

• 原型预览（本地直接打开，无需安装）：prototypes/index.html 总览 → prototype-a.html（轻量浮层）/ prototype-b.html（侧边常驻）对比。
• 改客户端：lib/client.js 改动刷新页面即可；跑着 dsh 仓库的 pnpm run dev:web 时可热更新。
• 改宿主：lib/index.js 改动需重启 dsh web（宿主行在启动时组合）。

外观

深浅色通过 var(--dsw-alias-*) 自动适配（body[data-ds-dark-theme]），主操作固定 #7c5cff 保证对比度。切换路径：设置 → 外观 → 浅色/深色/跟随系统，刷新后工坊立即生效。

规范依据

• CCv3 SPEC_V3.md（权威）
• concepts.md 已过时，仅参考

更新日志

完整历史见 CHANGELOG.md。最近三版：

• 0.3.0 移除「点子」页：工坊导航改为 4 页（5维世界观 / 角色细化 / 世界书 / 校验导出），⛶ 大框 能力改用统一 fieldHead() 落到全部长文本 string 字段，侧栏搜索保留。同步修掉该改动引入的数组往返回退（[] 会被写成 [""]，即凭空多一条空白问候语）；并把问候语字段改为逐条独立编辑（一条 = 一个编辑框），根除「多段问候语一编辑就被拆成多条」的静默损坏，顺带补上问候语增删与 10 条上限对齐。另修大框「取消」真正回滚、清掉自 67172fd 起就调不通的 expandIdea / expandWorld 死代码、完成全量 i18n 接线（此前词表已建好但大量调用点硬编码中文，切到 English 仍显示中文；现全部 122 条中文字面量接入词表，中文界面逐字未变）、CC 预设改为自动安装（此前需手工拷贝），并修掉首次切到 CC 模式时胶囊不出现（探测读错了 projectionValues.agentPreset 字段，导致必须刷新页面或切换会话才出现）。
• 0.2.22 适配 dsh 0.1.5-rc.1 启动崩溃：connection.rpc.handle() 对外部插件不可用，host 半改为在 webServer 上自注册 /dsh-cc-studio-rpc 前缀路由并实现同一套 RPC 线上协议；请求体改事件式读取；修 presets/cc persona 的 prefix；新增 23 项回归测试。
• 0.2.21 修复 #2 草稿静默丢失：草稿变更即落盘 ~/.dsh/cc-drafts/<会话>.json，重启/换会话自动恢复；建空会警告、恢复会提示。

License

MIT © 2026 xia-sc — see LICENSE.

收录