Kuro-Bridge/koishi-dev

Koishi 机器人项目

由 bun create koishi-ce 生成，运行于 @koishi-ce 社区再分发版 生态。

环境要求

- Bun ≥ 1.2（本项目唯一支持的运行时与包管理器：koishi CLI 与插件加载链均以 Bun 为准）

快速开始

bun install
bun run start        # 启动（生产模式）
bun run dev          # 启动（开发模式，启用 HMR 热更新）

启动后访问控制台：

公开克隆后首次接入 kurobridge 桥接前，请先完成下文「公开仓 clone 恢复 SOP」。

预装与预写

- 已预装：基础与控制台插件（@koishi-ce 全家桶）。koishi.yml 为配置页导出形态：插件键带 uid 实例后缀，分组带中文 $label 标签。其中依赖数据库但非必需的（admin / bind / broadcast / callme / auth）与暂无需启用的（inspect / server-temp / mock）以 ~ 前缀保持禁用——数据库已默认启用，去掉对应 ~ 即可。
- 数据库开箱即用：@koishi-ce/plugin-database-sqlite 已预装并默认启用，数据落在 data/koishi.db。
- 只预写、未预装：adapter（discord / telegram / qq …）官方插件以 ~ 禁用条目预写在 koishi.yml 的 group:adapter——loader 会跳过禁用条目，不安装也能正常启动；需要时在控制台「插件市场」搜索安装，回到配置页点击启用即可（mongo / mysql / postgres 等其他数据库插件未预写占位，市场安装后自动出现条目）。

仓库现状（2026-09-19）

远程信息

- origin：（public 公开仓，首推 2026-09-19）
- 默认分支：master

决策记录（2026-09-19）

1. 落点：Kuro-Bridge org 公开仓（用户拍板，替代默认私有提案）。
2. 公开前历史脱敏：git filter-branch 全历史重写，旧字典字面量（已全历史脱敏）统一替换为 REDACTED-BEFORE-PUBLIC-PUSH；重写后校验全历史零命中，并清理 filter-branch 备份 ref（提交哈希由 a6d417d/cf24d6c 重写为 8f4047b/e051999）。
3. 前向纪律：仓库内 koishi.yml 第 4 行 token 为占位值 SET-LOCAL-TOKEN-BEFORE-START，真值仅存本地工作树与 Pure 侧运行时配置（skip-worktree 隐藏本地差异，永不入库）。

token 轮换记录（2026-09-19）

- 沙盒 WS token 已完成轮换；新值格式为 32-hex 随机（openssl rand -hex 16，与 Pure 首启生成格式一致）。
- 真值位置仅两处、两侧同值：本仓 koishi.yml（本地工作树）与 KuroAdapter-Pure 仓 sandbox/server/plugins/KuroBridgePure/config.json。
- 验证：双侧握手日志——koishi 侧 data/logs/line1-rotation-stdout-20260919.log（「握手成功 { serverId: 'kurobridge-pure', version: '0.1.0', protocolVersion: '0.4.0' }」）、Pure 侧 sandbox/console-line1-rotation-20260919.log（「对端 koishi 握手成功」）——加一轮 chat 双向冒烟（标记 line1-rotation-smoke）。

1008 永久停机语义注记

服务端对鉴权失败回 1008 关闭码并断开连接；koishi 插件视其为永久停机、不自动重连——因此改 token 必须两侧同改并重启。

token 下次轮换 SOP

1. 停 koishi 宿主与 Pure 沙盒（顺序不限，两端都停）；
2. openssl rand -hex 16 生成新值；
3. 两侧同写上述两文件（本仓 koishi.yml 是 skip-worktree 本地文件，勿提交）；
4. 先起 Pure 沙盒（cwd KuroAdapter-Pure/sandbox/server，java -jar paper.jar nogui），再起 koishi（本目录 bun run start）；
5. 验证：双侧握手成功日志 + 一轮 chat 往返；
6. git 侧零动作。

公开仓 clone 恢复 SOP

clone 后 koishi.yml 的 token 为占位值 → 将其改为与 Pure 侧 config.json 一致的真值（或自行按上一节 SOP 轮换新值）→ git update-index --skip-worktree koishi.yml，保持真值永不入库。

挂载组件与运行时状态

- external/kurobridge：clone 自 （HEAD 0c8de7b，版本 0.2.0；上游已迁入 Kuro-Bridge org，本节刷新取代早前记载的旧上游地址与旧 HEAD），以 ./external/kurobridge 相对路径注册于 koishi.yml，连接 ws://127.0.0.1:25580（沙盒 token）。它是独立上游仓：对本仓只读、整体 gitignored（非 submodule，仅作本地联动调试用），版本由上游仓自管，更新走上游仓自己的 git；公开克隆不含 external/。
- plugins/kurobridge-mock-inject：M7 真机联调一次性辅助插件（63 行：包裹 Bot.broadcast 记录广播 + 8 秒后经 plugin-mock 注入一条平台消息）。2026-09-15 联调中因 koishi.db 已有同 pid 的 binding 行，出现过一次 UNIQUE constraint failed: binding.pid, binding.platform 注入失败（非致命，完整轨迹见 data/logs/.kurobridge-m7-koishi.log）。源码头注释原称「不入库不发布」；建仓时裁决入库留档（63 行、无发布面、属 M7 证据）。Pure 线联调窗口结束后建议整体删除（删 plugins/kurobridge-mock-inject/ + koishi.yml 第 7-8 行注册）。
- data/ 运行时状态：koishi.db 含 mock 平台测试行（binding pid 3054108135 / platform mock、channel 967493177）；logs/ 共 23 份运行日志（含上文引用的轮换握手日志）。均为运行时产物，已 ignore，不入库。

backup-line2-20260918 处置

data/backup-line2-20260918/koishi.db.bak（SMOKE-2 §2 留底）原样保留；data/ 整体 gitignored，不入库。

门禁下沉子仓

宿主不设 check 透传脚本（external/ 整体 gitignored，公开克隆无子仓，透传脚本必然断）；biome/tsc/vitest 门禁在 kurobridge 子仓执行。

安装插件

推荐在控制台「插件市场」页安装（已预配 registry.koishi.chat 镜像源）；也可以手动 bun add  后在 koishi.yml 中启用。

根依赖中的四行 npm alias——"koishi": "npm:@koishi-ce/koishi-shim@^4.18.11"、"@koishijs/plugin-console": "npm:@koishi-ce/console-shim@^5.30.11"、"@koishijs/core": "npm:@koishi-ce/koishi-shim@4.18.11"、"@koishijs/loader": "npm:@koishi-ce/koishi-shim@^4.18.11"——已把上游生态的 peer 依赖全部钉回 @koishi-ce 框架（前两行与后两行分别只涉及 koishi-shim / console-shim 两个包；请勿删除或改写这四行），不会形成第二份框架 / console / loader 副本。

更新依赖

bun run update        # 安全更新：只更新 @koishi-ce/* 生态位依赖

请勿裸跑 bun update：那是全树更新语义，会连带给市场安装的第三方插件与全部传递依赖重新求解，任一上游漂移都可能破坏运行时。bun run update 只显式更新 @koishi-ce/ 依赖（alias 冻结线不受影响）；第三方插件的版本请经控制台「插件市场」操作。

自定义插件

手动在 plugins/ 目录下创建插件包，或经脚手架进入 external/ 工作区：

- bun run new  —— 生成插件骨架到 external/（--console 附带控制台前端扩展）
- bun run clone  —— 克隆已有插件源码到 external/ 本地联动调试

两种来源的插件都在 koishi.yml 中以相对路径引用（如 ./plugins/my-plugin、./external/my-plugin）即可启用；Bun 直接加载 TypeScript 源码，无需预编译。克隆来的 monorepo 形态插件仓库（插件在 packages/ 等子目录）无需平铺——workspaces 声明的 external/* 通配任意深度，控制台「添加插件」列表同样按此声明收录，子包直接可见可启用（搬迁自其它包管理器的仓库若带着旧 node_modules，负向声明已将其排除，建议顺手删除节省空间）。

插件构建与发布

针对 external/ 工作区的插件项目：

- bun run build —— 串行构建 external/ 下全部可构建项目
- bun run release:version —— 消费 pending changeset 提升版本号
- bun run release:dryrun —— 完整发布链演练（version → build → publish --dry-run）
- bun run release —— 完整发布链（version → build → publish）