# 场景一：DSH 插件作者管理社区

[← 返回 README](../README.md) ｜ 相关文档：[团队协作](./scenario-team.md) ｜ [会话分享广场](./scenario-share-square.md)

你是某个 DSH 插件的作者，想把用户聚在一起：发版公告有人看、问题反馈有地方贴、重复提问不用一遍遍回答。这份文档给出一套可以直接照抄的社区配置与日常运营动作，外加每一步的权限怎么勾。

---

## 一、目标与最终形态

搭完之后你的社区大致长这样：

| 频道 | 类型 | 用途 |
| --- | --- | --- |
| `公告` | 公告 | 只读发版信息，进社区即订阅 |
| `综合讨论` | 文字 | 闲聊、自由提问 |
| `反馈与报障` | 文字 | 用户贴图传文件报 bug（附件直接拖进输入框） |
| `话题讨论` | 话题 | 每个功能 / bug 一条话题，独立成串，24h 无人回复自动归档 |

角色：`@everyone`（普通用户）+ `维护者`（你和协作者）+ 可选 `内测`。

---

## 二、建社区

1. 打开 DSH-Guild 面板 → **＋** → 创建社区，可见性按需要选：
   - **公开**：用户能在发现页搜到并直接加入，适合大多数插件；
   - **私有**：只能凭邀请码加入，适合还在早期、只想给一小撮人用的插件。
2. 创建完成后社区里会自带一个 **公告** 频道，以及一条置顶的开箱指南 —— 先把它改成你的插件简介。
3. 社区设置里补上名称 / 简介 / 图标：简介会在**发现页**展示，写上「这个插件是干什么的 + 去哪里看文档」，能显著减少无效提问。

> 邀请码在创建时生成且**固定不变**，可以直接贴进 README 或插件仓库，不用担心过期。

---

## 三、频道怎么配

在频道列表里用 **新建频道** 逐个添加，类型选好后不可随意与其它类型混用（三种类型互斥）：

- **公告频道**：默认对 `@everyone` **只读**，不需要改权限 —— 只有你（所有者）和经频道权限放行「发送消息」的角色能发帖。用户进社区即订阅，这就是你的发布渠道。
- **文字频道**：`综合讨论` 设为全员可发言（默认即可）；`反馈与报障` 如果需要限制刷屏，可以后续用频道权限收紧。
- **话题频道**：`话题讨论` 用来分流长问题。点进频道看到的是**话题列表**，点开某条话题才进入聊天；24 小时无人回复会自动归档，有人回复即自动恢复。

频道右上角菜单里可以**改名 / 改主题 / 改类型 / 删除**，列表支持**上移 / 下移**排序 —— 把 `公告` 排在最上面。

---

## 四、角色与权限

角色模型是 Discord 式的：每个社区自带 `@everyone`（隐式作用于全体成员）与一个预设「管理员」角色（本质是普通角色，建社区时按全部权限位初始化，需要手动分配）。

### 建「维护者」角色

1. 进入 **管理 → 角色 → 新建角色**，命名 `维护者`，选个颜色便于在成员列表里区分。
2. 勾选需要的权限位：`查看频道` `发送消息` `管理消息` `发起讨论组` `管理讨论组` `邀请成员`。
   - 想让协作者也能发公告 / 改频道结构，再加 `管理频道`；想让他们能处理捣乱用户，再加 `踢出成员`。
3. **不要**把 `管理社区` `管理角色` 随手给出去 —— 前者能改社区设置甚至删除社区，后者能改所有角色的权限。
4. 在成员面板里给协作者分配这个角色。

### 两条硬规则（撞上了别以为是 bug）

- **层级防提权**：只能操作层级**严格低于**自己的角色与成员。也就是说你没法给一个比自己高的角色改权限，也没法动层级不低于你的人。
- **不能授予自己没有的权限**：你自己没有的权限位，配置时不给勾。

### 公告频道只让维护者发言

如果 `维护者` 的角色权限里没勾 `发送消息`，就到 **频道权限** 里单独覆盖：针对 `维护者` 设 `发送消息 = allow`（针对 `@everyone` 保持默认 deny）。频道级覆盖只支持频道级权限位，角色级权限仍需在角色里配。

权限改动**实时下发**：在线连接会被重新校验，失去频道可见性的连接会被主动断开，不用让用户重启 DSH。

---

## 五、日常运营动作

- **发版公告**：在 `公告` 频道发一条消息；重要的用 **置顶**（需要「管理消息」权限）固定到频道头部，置顶面板可查看并跳转到原消息。
- **回收反馈**：让用户在 `反馈与报障` 里 **拖拽 / 粘贴截图**，一条消息最多 4 个附件，图片内联预览、其它文件直接下载。
- **减少重复提问**：用 **消息搜索**（关键词 + 频道 / 作者 / 时间范围 / 仅 `@我`）先搜一遍历史，把结论补充到置顶帖里。
- **用户贴代码 / 日志**：用消息里的 Markdown 渲染（代码块）而不是截图；必要时要对方用「分享 DSH 会话」把复现现场打包发上来。
- **全员通知**：确实需要打扰所有人时用 `@everyone`，会计入提及未读；日常优先在公告频道发帖。
- **私密内测**：见下面的「内测群」一节。
- **处理捣乱**：先在成员面板 **移除成员**；反复回来就 **封禁**，被封禁者无法重新加入，随时可在成员面板解封。
- **转让所有权**：你不再维护这个插件时，在成员面板把所有权转给新的维护者。

### 内测群

两种做法，按封闭程度挑：

- **私密社区 + 邀请码**：最彻底，非邀请码无法进入；
- **私密讨论组 + 密码**：留在同一个社区里，讨论组可见性设为 `私密` 并设**进入密码**；不设密码则只能由组内成员主动拉人。组内成员可从社区成员里拉人、移出成员，成员也可自行退出。

---

## 六、进阶：把社区开在发现页顶部

如果你是**自己托管 Server** 的部署者，可以用官方社区种子一次性给你的 Server 铺好底：创建 3 个公开社区（DSH 官方 / 会话分享广场 / 插件与技能开发），自带公告、文字频道与各频道置顶说明帖，owner 是你自己。这几个社区恒排在发现页顶部并带「官方」标记。

配置 `ADMIN_TOKEN` 后执行：

```bash
curl -X POST https://<你的自定义域>/api/admin/seed-official \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Admin-Token: <ADMIN_TOKEN>"
```

可重复执行，已存在的官方社区会跳过。详见 [自部署 Server](./deploy.md#六可选写入官方社区与种子内容)。

> 如果你用的是现成的公共 Server（默认 `https://dsh-guild-api.huiwang.fun`），这一步不用做 —— 发现页里已经有官方社区，你只管建自己的插件社区。

---

## 七、常见坑

| 现象 | 原因 / 处理 |
| --- | --- |
| 用户说进不来 | 私有社区必须给邀请码；封禁过的用户需要你先解封 |
| 公告频道自己发不了 | 你不在允许发送的名单里 —— 检查频道权限覆盖里 `发送消息` 是否为 allow |
| 话题突然"不见了" | 讨论组 24h 无人回复自动归档，回复任意消息即恢复 |
| 创建社区失败 | 自建社区有上限（20 个）与**每 24 小时最多 5 个**的滚动限制 |
| 改了权限对方没反应 | 权限会实时重校验并断开会失效的连接，让用户刷新页面重连 |