dsh-cc-studio · CCv3 角色卡工坊
从一句话点子到可导入 SillyTavern / Risu 的 chara_card_v3。专治「只有点子，世界观薄弱」。
DSH（DeepSeek Harness）插件：输入框上方的胶囊 → 全屏融合工坊，配合 CC 模式 预设让 LLM 通过 14 个 Tool 先问再填、与你共创角色卡，最后一键导出 JSON / PNG / CHARX。
| 项目 | 值 |
|---|
| 插件包名 | @dsh-plugins/dsh-cc-studio |
| 当前版本 | 0.3.1 |
| 宿主 RPC | /dsh-cc-studio-rpc（自带路由，适配 dsh ≥ 0.1.5-rc.1；已在 0.1.6-alpha.1 实测） |
| 客户端挂载点 | conversation.input.dock（胶囊）+ shell.overlay（工坊）+ settings.section |
| 落盘位置 | ~/.dsh/cc-library/（角色卡）、~/.dsh/cc-drafts/（会话草稿） |
安装
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，把上面命令里的 ~/.dsh / %USERPROFILE%\.dsh 换成该路径；插件本体位于 <DSH_HOME>/profiles/web/node_modules/@dsh-plugins/dsh-cc-studio/。
agent.cordis.yml 在一份 standard 拷贝上追加 id: cc-studio-agent, name: '@dsh-plugins/dsh-cc-studio/agent'，并把 persona 改为「共创搭档」——先问再填、每步 1-2 问。切换会话模式后胶囊自动出现。
手工拷贝的目录没有安装记录，因此会被自动安装流程视为「你的自有文件」而跳过；想交回插件管理，删掉该目录后重启即可。
卸载/删除插件不会删除 <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. 常见问题
| 现象 | 处理 |
|---|
| 输入框上方没有胶囊 | 确认当前会话模式是 CC 模式；确认 ~/.dsh/.agent-presets/cc/ 下 preset.yml 与 agent.cordis.yml 都在且目录名是 cc（正常应由插件自动安装；缺失则看启动日志里 [dsh-cc-studio] 的告警）；重启 dsh web 后刷新页面 |
| 工坊出现橙色条「草稿已新建」 | 该会话没有历史草稿（首次创建或草稿目录被清）；已存档会话恢复时会改为蓝色条并显示 creation_date，下次写入后提示消失 |
切 CC 模式报 invalid config: S.prefix missing required value | presets/cc/agent.cordis.yml 是 0.2.22 之前的旧版（persona 用了 text:），重新拷贝新模板 |
dsh 启动报 cannot get property "webServer" without inject | 插件版本低于 0.2.22，更新插件 |
| 校验报错 | 必填 spec: chara_card_v3 / spec_version: 3.0 / group_only_greetings；主图标需唯一；正则需合法 |
快速上手
- 新建会话，会话模式选 CC 模式（胶囊随即出现在输入框上方）。
- 直接说需求：「我想做雨城记忆典当行老板娘，世界观很薄」。
- 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。
- 随时点胶囊进工坊手改。校验通过后：侧栏
★ 保存当前（已载入 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 保证对比度。切换路径：设置 → 外观 → 浅色/深色/跟随系统，刷新后工坊立即生效。
规范依据
更新日志
完整历史见 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.
收录
