朝堂 · dsh-chaotang

把 DSH 里的智能体团队，画成一张上朝图。 谁是总管、谁在干活、干到哪一步、烧了多少 token，一眼看见。

---

一、三个版本，别搞混

这套东西一共三个版本，长得像，但不是同一个东西。

#	版本	是什么	怎么打开	改代码后
1	DSH 本体插件 （lib/client.js）	嵌在 DSH 里，点侧边栏「朝堂」就在主区域出现	DSH 左侧栏 → 点 🏯「朝堂」	升版本 + 重启 DSH
2	网页版 · 单团队 （lib/page.html）	独立网页，浏览器打开，用真实数据	桌面「开朝堂」快捷方式 或 http://127.0.0.1:<端口>/chaotang	刷新浏览器即可
3	多团队预览版 🔧 （预览-多团队.html）	半成品 · 假数据演示页，只看布局，不接真数据	双击 html 文件	—

各自擅长什么

① DSH 本体插件 —— 日常用这个

• 在 DSH 里随手点开，不用另开浏览器
• 卡片、连线、音效、典章设置全都有（文案 / 背景 / 音色 / 调色）
• 点卡片 → 右侧抽屉看聊天记录，还能直接给队员发消息派活

② 网页版（单团队） —— 想单独看时用

• 独立窗口，可以摆到第二块屏
• 功能和插件版基本一致（少了「调色」）
• 设置独立存一份，跟插件版互不影响

③ 多团队预览版 🔧 半成品，别指望它干活

• ❌ 不接真数据——里面的人名、任务、数字全是编的
• ❌ 改不了任何东西——按钮是假的，点了只改标题，不存任何设置
• ❌ 不能当正式版用——它只是一张"布局草图"
• ✅ 唯一用途：看看「多个团队各占一块、各自滚动」大概长什么样

为什么还没做完：正式版目前只支持一个团队（一个总管 + 队员）。 要做成多团队，后端得改成返回 teams[] 数组，前端得渲染好几个块—— 这块还没动，别拿去跟人说"支持多团队"。

⚠️ 两个正式版本是分开的：各有各的设置文件、各有各的背景图目录。 改一边，另一边不会跟着变——这是故意的。

---

二、安装（给 AI 看的）

这一节写给 AI 助手。人不用看，直接把本文件发给 DSH 里的 AI，让它装。

这个插件叫 dsh-chaotang（中文名「朝堂」），是一个 DSH 插件。
它把 DSH 的智能体团队可视化成一棵"朝堂树"。

【前置】
- DSH 版本 >= 0.1.5-rc.1
- 有 pnpm（DSH 一般自带）

【安装步骤】
1. 找到 DSH 的 profile 目录（通常是 ~/.dsh/profiles/desktop）
2. 编辑该目录下的 package.json，在 dependencies 里加一行：
   "dsh-chaotang": "github:tiankongshenchu/dsh-chaotang"
3. 在同一个文件的 dsh.profile.bundles 数组里，加上字符串 "dsh-chaotang"
4. 在该目录执行：pnpm install
5. 让用户手动重启 DSH（不要自己结束 DSH 进程）
6. 重启后验证：DSH 左侧栏应出现「朝堂」入口，
   点开能在主区域看到卡片和连线。

【如果 github 装不上（国内网络）】
改用本地 tgz：
1. 下载 dsh-chaotang-<版本>.tgz
2. package.json 里写 "dsh-chaotang": "file:<tgz 的绝对路径>"
3. 其余步骤同上

【出问题怎么看】
- 侧边栏没有「朝堂」→ 检查 bundles 数组加了没、pnpm install 成功没
- 有入口但点开空白 → 检查 DSH 版本是否 >= 0.1.5-rc.1
- 提示 main panel 未注册 → 插件没加载成功，看 DSH 日志

---

三、装了之后能看见什么

                    ┌──────────────┐
                    │  ● lead      │  ← 总管（当前会话）
                    │  督阵中…      │
                    └──────┬───────┘
                  ╱        │        ╲
        ┌────────┐   ┌────────┐   ┌────────┐
        │ ● a    │   │ ● b    │   │ ● c    │  ← 队员
        │ 在忙    │   │ 空闲    │   │ 臣有本奏│
        └────────┘   └────────┘   └────────┘

每张卡片上有：

• 名字、分工说明
• 中间那句话（闲着说闲话 / 干活显示任务名 / 干完亮金色「臣有本奏！」）
• 右下角状态：空闲 / 在忙 / 暂候 / 干完了
• 底部：上下文用量 433k / 1.0M + 进度条 + 步数 + 时长

连线： 总管 → 每个队员，干活的那条发光、会流动。

---

四、能改什么（典章）

点顶栏「典章」，四个页签：

页签	改什么
文案	顶部标题、卡片上那句话（改着先存草稿，点「入册」才落定）
背景	整页背景图（原图直存，不压缩）、卡片背景、字色
音色	每个动作配什么声音（开朝=鼓、退朝=钟、养神=木鱼、赏花=花瓣…），也能传自己的音频
调色	连线的颜色（插件版有，网页版没有）

还能：

• 双击总管的名字改称呼
• 顶栏「另册 ▾」放你自己续录的状态
• 五个状态各有各的音效

---

五、文件结构

dsh-chaotang/
├── package.json          插件声明（dsh.bundle / dsh.client 都在这儿）
├── cordis.patch.yml      往 DSH 里挂载的补丁
├── README.md             本文件
├── LICENSE               MIT
└── lib/
    ├── index.js          Host 半：HTTP 接口（团队状态 / 会话消息 / 设置）
    ├── client.js         Client 半：DSH 里的那个界面（React）
    └── page.html         网页版（独立页面，原生 JS）

运行时生成（不打包）：

lib/chaotang-settings.json   设置（两个版本各一份）
lib/bg/                      网页版背景图
lib/bg-plugin/               插件版背景图

---

六、接口一览

方法	路径	干什么
GET	/chaotang	网页版页面
GET	/chaotang/state	团队快照（成员 / 任务 / 用量）
GET	/chaotang/session?id=	某会话最近的消息
GET	/chaotang/search?id=&q=	搜历史（按日期分组）
POST	/chaotang/send	给队员发消息（发给 lead 不行）
GET/POST	/chaotang/settings	读 / 写设置
POST	/chaotang/upload	上传背景图（原图不压缩）
POST	/chaotang/clean-bg	清理旧背景图
prefix	/chaotang/bg	取背景图（别加尾斜杠）

---

七、踩过的坑（想改代码的先看）

开发过程中摔了 30 多个坑，全记在：

开发日志-踩过的坑.md（33 条，每条都有「现象 / 原因 / 怎么解」）

几条最要紧的：

1. 改 client.js 必须升 version + 重启 DSH（按版本号缓存）
2. page.html 不用升版本，Host 每次现读，刷新浏览器就生效
3. prefix 路由别带尾斜杠：/chaotang/bg ✅，/chaotang/bg/ ❌
4. localStorage 按端口隔离，DSH 换端口设置就丢 → 所以存磁盘
5. surfaceTokens 不能做进度条（重启后重置成小值），要用 totalTokens
6. 别用宽正则批量改 JS（-replace 不分大小写，会把 target.name 这类也吃掉）

---

八、手动安装 / 卸载

装：

dsh plugin --profile desktop add "link:D:\dsh-plugins\downloads\插件\朝堂插件"

装完重启 DSH。

卸：

dsh plugin --profile desktop remove dsh-chaotang

---

许可

MIT