# Koishi 插件设计系统

适用范围：araea 维护的 16 个 external 插件。Koishi 主框架、控制台与聊天客户端不在修改范围内。

## 规范与实现

- 视觉、组件、形状、排版与语义颜色以 [Material 3 / Expressive](https://m3.material.io/) 为准。
- [Apple HIG](https://developer.apple.com/design/human-interface-guidelines/accessibility) 用于操作反馈、平台惯例、可恢复性与可访问性，不引入 Apple 视觉组件。
- [WCAG 2.2 AA](https://www.w3.org/TR/WCAG22/) 用于非文本内容、颜色与对比度、时间限制、输入错误和破坏性操作审查。
- 色彩使用 Google Material Color Utilities 0.4.0 的 HCT 与 Tonal Spot 动态角色，明确使用 2025 色彩规范。历史 `lch` API 名仅用于源码兼容，计算已经统一为 HCT。彩色角色（primary / secondary / tertiary / error 及其容器）走官方 Tonal Spot；中性面（surface 系列、on-surface 系列、outline 系列）由 HCT 按本设计系统的色调重算——表面留住一点源色味道、文字取深色档，避免成片近白、文字偏浅的发晃感。
- `m3.ts` 是角色颜色、字阶、间距、圆角、层级和基础组件的唯一源文件。`material-color*.ts` 是固定版本的官方算法生成物，授权见 `THIRD_PARTY_NOTICES.md`。
- 不额外添加静态截图无法表达的动画；基础 CSS 禁用减少动态效果偏好下的动画和过渡。

## 输出、交互与内容

1. 有渲染图时只发图片，不附同内容的文字，避免在群里重复刷屏；图片生成失败时才退回文字。插件不提供个人显示模式开关。
2. 每个插件的主指令都带描述，`help` 列表右侧不留空；主指令先于任何子指令注册（Koishi 会忽略已存在指令的描述）。文本回复不能把后续条目无提示地压掉；较长管理列表分页。
3. 裸输入必须符合词法、对局状态及参与条件。多个插件匹配时不执行，要求明确完整指令；完整指令继续可用。
4. 回复说明当前结果、未完成原因和可执行的下一步，不用管理员日志替代用户可用的反馈。退款、赔付与渲染失败不能伪装成功。
5. 破坏性清空需展示范围、不可撤销性和限时确认码。确认码限制到同一机器人、平台、用户与频道，使用后立即失效。
6. 多轮输入等待 5 分钟，提问里写明可回复的内容与「取消」，不再追加计时说明。对局内的短窗口（如 21 点保险、投降）提供显式跳过，全员表态后立即进入下一阶段，而不是提供「延长」。
7. 货币发放先写入核对记录，入账结果不明确时保留待核对状态，不自动重发。管理员核对实际流水并按需人工补发后标记确认；确认操作自身不转账。

## 内容边界

- message-counter 的昵称测量与省略号策略保留。图片中合理截断昵称，文字榜单提供完整名称与完整请求范围。
- P5 / PJSK 输出是用户请求的作品素材，其作品风格保留；选择、参数、提示和文字替代遵循统一交互规则。
- 象棋棋盘与棋子是游戏内容，配套容器遵循 M3，并附带棋子位置与轮次的文字说明。
- see-color 是以颜色辨认为目的的感官测试；说明标明题目目的和坐标规则，不在文字替代中泄露答案。词影的笔画图形线索属于字形辨认内容，文字说明给出字与位置状态及相似笔画数量。不能宣称这些感官测试变成了完全等价的无视觉玩法。
- 聊天客户端的焦点、缩放、读屏与消息合并行为必须在相应客户端验收，不能由服务端截图测试替代。当前测试不是整个平台的 WCAG 合规认证。

## 维护与验证

源仓库：`koishi-plugin-markdown-to-image-service`。每个消费者随包携带本地副本，不通过相邻目录做运行时导入。

在包含这 16 个仓库的 external 目录中：

```sh
node markdown-to-image-service/scripts/sync-design-system.mjs
node markdown-to-image-service/scripts/sync-design-system.mjs --check
```

单个消费者仓库也带有 `scripts/check-design-system.mjs`，校验共享文件哈希；升级时重新运行同步器，不要单独修改生成副本。该检查会拒绝未同步的本地修改。

官方色彩算法可在源仓库安装开发依赖后通过 `node scripts/build-material-colors.mjs` 重建，再同步消费者。

回归检查覆盖：24 个源色相的明暗角色对比度、奖牌前景、图表填充/轨道差异、浏览器/服务端 HCT 一致性、主指令描述、输入冲突、入账异常、清空确认和 Wordle 并发/渲染失败。工作区截图脚本为 `scripts/verify-rendering.ts`，需 Puppeteer Core 和可用 Chromium。

## 本轮改动对应关系

| 范围 | 实现 |
| --- | --- |
| 共享设计规范 | 官方 HCT、2025 动态颜色角色、共享字阶与间距、同步与哈希校验 |
| Markdown | M3 明暗主题；旧主题名按明暗迁移；代码高亮与 Mermaid 使用 M3 角色；长代码可换行 |
| message-counter / monetary-rank | M3 角色与共享图表字阶、HCT 头像配色、完整文字榜单；保留昵称截断 |
| Wordle | 替换复制的 NYT 外观；状态符号与图例；明暗角色；异常释放并发锁；安全解析模式编号；裸词只在确定是猜测时回应 |
| MCDLE | 猜测按行排成一张表，方便逐项对照；单句页脚居中 |
| 2048 / ciyi | 数字与奖牌前景按实际对比度选色 |
| 斗牛 / 21 点 | 付款核对记录、如实反馈退款失败、明确下注金额、可显式跳过的短窗口 |
| sentinel | 完整封印列表按每页 10 位展示 |
| 其余插件 | 渲染失败退回文字、可取消输入与上下文反馈 |