sealdice / sealdice-manual-next

海豹骰全新官方文档。

sealdice-manual-next

VitePress 驱动的海豹骰官方使用手册。

当前手册预览可见 海豹手册。

编写文档

文档写在 docs 下的 .md 文件中，按文件夹分组。

如需调整导航栏和侧边栏，则涉及到修改 docs/.vitepress/theme.ts 和 docs/.vitepress/catalogue.ts 中的配置。

Lint

提交前请务必使用 markdownlint 进行检查，不满足格式要求的修改无法合并入主仓库。

pnpm install
pnpm run lint:md
pnpm run lint:md:fix // 检查并进行部分自动修复

对于 VS Code 用户，请使用 markdownlint 插件获取编辑器警告。这一插件已经被添加到本项目的推荐插件中，只需在打开本项目时按 VS Code 的提示安装即可。

排版

文档排版应当遵循 中文文案排版指北 的规范。

使用 AutoCorrect 插件可以提供相关帮助。

• VS Code
• JetBrains

标注功能版本

对于新加入的功能，需要在标题和正文开头都注明加入的版本。

段落标题的标签应当加在尽可能高等级的标题上，使用以下标签附在标题末尾：

## 新加入的功能 <Badge type="tip" text="vA.B.C"/>

在紧随以上标题的第一段正文开头，也应该做出文字叙述，例如：

从 <Badge type="tip" text="vA.B.C"/> 起，海豹支持某新加入的功能……

最终的效果应当类似下图：

开发版中的新功能

如果是为当前开发版中的新功能编写文档，而不能确定下一个正式版的版本号，使用以下标签：

<Badge type="tip" text="NextVersion"/>

这样做的好处是：在确定版本号后，方便通过文本替换批量修改。

归档警告

对于弃用的功能，需要在正文开头注明弃用的版本和归档的时间。

在第一段正文开头，做出以下文字叙述：

::: warning 注意：海豹已于 <Badge type="warning" text="vA.B.C"/> 版本弃用此方案，以下内容归档于 xxxx 年 xx 月 xx 日。

:::

最终的效果应当类似下图：

开发版中弃用的功能

对于在当前开发版中弃用，即将于下一个正式版中去除的功能，不要在正式版发布前移动原始文本。

如果不能确定新版本的版本号，使用以下标签和类似文案：

::: warning 注意：海豹将于 <Badge type="warning" text="NextVersion"/> 版本弃用此功能。
:::

如果能确定版本号但尚未发布，将以上标签中的 NextVersion 替换为确定的版本号。

在正式版发布后应尽快将原始文本移动到归档路径。

本地调试

pnpm install
pnpm run docs:dev

运行以上命令启动本地文档服务便于调试。

将自己的分支发布为 GitHub Pages

主仓库 的 Pages 自动追踪主仓库的 main 分支。

如果你希望请其他人预览修改的效果，或者有其他需求，需要将自己的分支也发布为 GitHub Pages。

我们已经为 fork 仓库配置了 GitHub Actions 自动部署，在你启用后，会将最新推送的 commit 进行部署。如果你是首次使用，请参考以下步骤：

1. 在你的 fork 仓库，进入 Actions 选项卡，你需要点击一个绿色的「I understand my workflows, go ahead and enable them」按钮；
   • 如果你没有看到这个按钮，而是列出了一些 workflow，这说明你已启用过 Actions，可以跳过下面的步骤；
2. 在左侧边栏选择 docs；
3. 在 runs 列表的上方应有一个 banner，内容为「This workflow has a workflow_dispatch event trigger」，选择它右边的「Run workflow」；
4. 在弹出的下拉菜单中选择你的分支，运行 workflow；
5. 等待 workflow 完成，这时你的仓库应多出一个 gh-pages 分支；
6. 进入 Settings 选项卡，左边栏选择 Code and automation 下的 Pages；
7. Source 选择「Deploy from a branch」，Branch 选择「gh-pages」，点击保存；
   • 如果需要，你可在下方的 Custom domain 填写一个自定义的域名，否则，你的 GitHub 用户名将出现在域名中；
8. 回到 Actions，应有一个新的名为 pages-build-deployment 的 workflow 正在运行；
9. 等待 workflow 完成，左边栏选择 Deployments，应能看到一个对应你分支的 Pages 链接；
10. 完成以上步骤后，你每次推送新的 commit 到自己的 fork 仓库，都会自动执行构建和部署，无需再次手动操作。

VitePress

手册使用 VitePress 驱动，文档见 VitePress。

sealdice-manual-next's Issues

缺 ban 指令的介绍

使用章不含扩展命令各节

Ref #13

归档旧内容

调整主页内容，增强对称性

WebUI 综合设置部分大部分缺少说明

JS配置项 应补充取得配置内容的部分

https://docs.sealdice.com/advanced/js_example.html#%E7%A4%BA%E4%BE%8B%E4%BB%A3%E7%A0%81-%E6%B3%A8%E5%86%8C%E9%85%8D%E7%BD%AE%E9%A1%B9

目前只提供了这样一种不太常用的用法：

let config = seal.ext.getConfig(ext, val);
if (config) {
    seal.replyToSender(ctx, msg, config.value);
}

应该把带变量类型的也列出

使用的 `1.4.6` 新版本占位符需在 `1.5.0` 发布前替换

或许我们需要一种更固定, 对全文替换更友好的方式表示在正式版中还未引入的功能

手册应该单独列出一个界面讲解 JS 插件？

理由：

1. 相比于 JS 插件，牌堆和帮助文档的复杂度与 JS 插件不是一个等级的
2. “编写新的 TRPG 规则”这一节的内容在实际上也是编写一个 JS 插件，但是放在“编写 JS 插件”同级的界面中，不太合理

希望有一篇“手机豹保活”介绍文档

@vuepress/plugin-register-components 依赖冲突

@vuepress/plugin-register-components 依赖 @vuepress/core 2.0.0-rc.0 版本，手册依赖 2.0.0-beta.67 版本，TS 类型不兼容

OpenShamrock部分是否重新写回手册

rt。OpenShamrock近期仓库恢复public，同时发版1.1.1。里面包含OneBot分支的发布。core仓库已提issue(#497)。考虑到这样的情况，或许明确一下开发者的态度（继续支持/不继续支持）会好些

follow up。1.1.1版的OpenShamrock仍然存在支持OB的版本。（不同branch发了两个包）是否考虑写回手册？@JustAnotherID @Xiangze-Li @MX-fox

使用-扩展命令 除 DnD 外各个扩展

find 指令内容需补充

缺少介绍 页大小和分页flag 的内容

[开发组内部需求] manual 推送到 fork 仓库的任意分支都触发构建

一个常见场景是：在 manual 仓库作出修改后，在提 PR 的同时要自行部署一个预览版。

目前这种部署在 fork 仓库的 开发分支 必须手动触发。

希望能修改 action 配置，使得：如果 push 是发生在 fork 仓库，不论是否 main 分支，都触发构建。

说明：如果 fork 仓库没有手动启用过 action，无论怎样 push 都不会触发构建，因此这样配置应当也是安全的。

内置脚本语言相关更改为DS

相关内容

• 进阶/内置脚本语言
  • #248
  • 编写新内容
  • 加迁移提示
• 进阶/编写复杂文案
  • 更新例子
• 进阶/编写自定义回复
  • 嵌入内置脚本 段
  • 其他与脚本相关的内容或应独立成另一节
• 进阶/编写牌堆
  • 插入海豹内置脚本语言 段

[JS API] 代码示例中所有给 `ext` 赋值的地方应加入 `let` 前缀

在 sealdice/sealdice-core#927 中，有用户因为缺少 let 前缀而被误导，写了错误的代码

手册上的扩展注册相关

在提问之前...

• 我填写了简短且清晰明确的标题，以便开发者在翻阅 issue 列表时能快速确定大致问题。而不是“一个建议”、“卡住了”等
• 我基本确定这是一个新功能/建议，而不是遇到了 bug（不确定的话请附上日志）

说说你遇到的问题？

手册中注册扩展案例
if (!seal.ext.find('test')) {
const ext = seal.ext.new('test', '木落', '1.0.0');
seal.ext.register(ext);
}
后面的文件使用了外部声明ext
let ext = seal.ext.find('test');
if (!ext) {
ext = seal.ext.new('test', '木落', '1.0.0');
seal.ext.register(ext);
}
手册这里是否需要标注一下前者在两个文件注册同一扩展名时ReferenceError: ext is not defined at data报错在预期内。不太确定，在这里提一下建议。

有什么好的想法？

手册这里是否需要标注一下前者在两个文件注册同一扩展名时ReferenceError: ext is not defined at data报错在预期内。不太确定，在这里提一下建议。

其他内容

No response

豹语介绍缺少逻辑运算符

手册核心指令更新关于迁移到 fun 模块的指令的说明

Ref sealdice/sealdice-core#784

有自定义文案的指令，应当在文档中说明自定义文案组合的方式

如 coc 的 判定-常规 系列和 判定-简短 系列的关系, 技能成长_结果_成功 与 技能成长_结果_成功_无后缀 的关系等, UI 上的说明是比较缺少的, 只能通过查代码逻辑来详细确定.

应当由开发组清楚写到手册和/或 WebUI, 应当包括: 在何种情况下使用哪个文案, 某一个中间变量是由哪些文案 (和可能的固定文本) 以哪些方式组合而成的, 等等.

部署、使用-CoC、使用-Story、使用-Log

缺少对备份/自动备份/自动清理备份的介绍

onebot客户端部分界面与当前版本UI表述不符合

Largange、Go-cqhttp / Mirai两节 登录的图片以及表述都与1.4.5的UI不符合，
应为
[QQ[onebot11正向WS]]/[QQ[onebot11反向WS]]

Openshamrock一节 shamrock仓库已经public archive，是否要同上面所说，对手册相关章节的指引进行更新，还是向用户宣布相关信息并且仅做资料的保留待查？

编写新文档进度跟踪

此 ToDo List 尽可能忠实地跟踪新文档的编写进度.

• 首页
• 部署
  • 快速开始
  • 迁移
  • 特色功能
• 配置
  • 自定义文案
  • 自定义回复
  • 牌堆
  • JavaScript 插件
  • 帮助文档
  • 拦截
  • 黑白名单
• 使用 (可能将要进行结构调整)
  • 基础概念
  • 快速上手
  • 特色功能 (移动到 部署 章)
  • 常见问题
  • 核心指令
  • 辅助机制
  • 扩展命令
    • CoC 7th
    • D&D 5E
    • 支持的其他规则
    • 属性同义词
    • Story
    • Log
    • Fun
    • Deck / Reply
    • 暗影狂奔 改为「支持的其他规则」索引
• 进阶
  • 进阶介绍
  • 内置脚本语言
  • 编写复杂文案
  • 编写自定义回复
  • 编写牌堆
  • 编写 JavaScript 插件
  • 编写帮助文档
  • 编写敏感词库
• 关于
  • 关于
  • 许可协议
  • 参与开发

归档整个基础知识一节，同时逐渐将部分部署指南直接指向上游的文档

提议归档整个「基础知识」一章，并逐渐剥离部分部署指南内容。考虑如下：

1. 本手册是海豹的使用手册，介绍计算机使用内容超出了手册应当承担的内容，加重了手册维护的工作量。我们应当将更多精力放在完善手册中海豹本身使用内容的工作上。
2. 部署相关也应该逐渐引导向上游手册，由于QQ的特殊性，上游的部署方式可能频繁改变，我们可能很难做到实时更新，只有上游自己更清楚如何部署。如果有补充的部分可以直接向上游提交pr，而不是保留在我们的文档中。

cc @sealdice/manual-team

补充：基础知识一块目前看起来并没有起到我们之前所期望的作用，不看的依然不会看。同时这一块除非维护成计算机百科全书，否则不可能完全覆盖，我们没有精力也不应该做这种事情。故提议归档降低压力。

缺少手机豹本地数据目录相关内容