koishi-plugin-chatluna-data

ChatLuna 专业运维控制台。它面向生产实例管理员，集中提供请求正文诊断、会话检索与批量变更、运行时资源检查、ChatLuna ACL/约束维护、数据完整性扫描和持久化审计。

当前版本：1.0.0

安装与依赖

npm install koishi-plugin-chatluna-data

必需 Koishi 服务：

• database
• console

可选运行时服务：

• chatluna >=1.4.0-alpha.42 <2

ChatLuna 是可选 peer，而不是精确锁定的运行版本。插件只使用 ChatLuna 公开服务；兼容的 ChatLuna 1.x 更新无需修改本插件。某项公开能力消失时，仅禁用对应操作并显示原因，不回退到私有字段。

启用后，从 Koishi Console 左侧栏打开 ChatLuna 运维。

产品边界

本插件负责：

• 查看规范化模型请求、响应和单次错误。
• 检索会话、消息链、binding、ACL 和归档引用。
• 批量修改会话 model、preset、chatMode。
• 批量归档、清理 binding 引用、指向单个会话、授予或撤销 ACL。
• 查看 provider、model、tool、chat mode、vector store 和 preset 目录。
• 维护 ChatLuna ACL 与 constraint。
• 有界扫描数据完整性，并执行问题类型允许的定向修复。
• 为所有写操作保留审计。

本插件不负责：

• Koishi 用户、频道、authority、permissions 或指令权限治理。
• ChatLuna Core、adapter 或模型凭据配置。
• preset 文件编辑。
• 任意消息创建、改写或删除。
• 全局 Koishi 日志捕获和手工错误文本分类。
• raw SQLite、数据库驱动私有接口或通用字段编辑。
• ChatLuna 生态导航、关系图或插件聚合。

控制台

总览

显示 ChatLuna 连接与兼容状态、会话状态、运行时资源、正在执行的操作、最近单次失败请求和失效运行时引用。

请求

请求记录来自 ChatLuna 公共 registerCallbacksProvider()：

• 常态只保存请求索引、模型、会话上下文、状态和脱敏错误。
• 管理员可开启 1 至 60 分钟的限时诊断捕获。
• 捕获可按 provider、model 或 conversation ID 过滤。
• 请求和响应正文默认保留 24 小时，之后只清空正文，保留索引。
• secret、authorization、cookie、token 和密码字段会被脱敏。
• 内联 base64 与二进制内容不会持久化。
• 同一 request ID 下的多个 model run 会关联展示。

这里的“请求体”是 ChatLuna 交给模型层的规范化 messages、tools 和参数，不是 adapter 最终发出的线级 HTTP 报文。

本插件明确不采集、不展示、也不聚合：

• 请求耗时
• 首 token 延迟
• token 用量
• 请求负载大小
• 失败率或失败趋势

会话

会话列表使用数据库侧筛选、排序、计数和分页。批量操作支持两种明确范围：

• 当前显式勾选的会话 ID。
• 当前服务端筛选条件匹配的全部会话。

“当前页全选”不会自动扩展为全部筛选结果。选择全部筛选结果必须单独打开开关。

所有批量写入都经过：

1. 后端锁定完整目标 ID 快照。
2. 返回准确总数、风险提示和有限差异样例。
3. 只使用 operationId 执行快照。
4. 按批次更新进度并记录逐项失败。
5. 写入持久化审计。

预览样例上限不会截断实际执行目标。修改 model、preset 或 chatMode 后会通过 ChatLuna 公共 API 清理受影响会话缓存。

运行时

只读展示 ChatLuna 公开目录和逐项能力报告。provider 刷新必须由管理员显式触发，页面加载不会自动刷新，也不会显示 API Key。

当前验证基线可以安全执行 sessionless 归档。恢复和删除仍需要真实用户 Session，因此控制台不会伪造 Session 绕过 ChatLuna ACL；在 ChatLuna 提供安全 operator API 前，这两项保持禁用。

ACL 与规则

这里只管理 ChatLuna 自身的 ACL 和 constraint：

• ACL 主体类型：user、guild
• ACL 权限：view、manage
• constraint 支持范围、路由、默认/固定 model、preset、chatMode 和行为策略

数据健康

扫描按配置上限读取 Core 数据，批量收集引用并消除逐行查询。可检查：

• latestMessageId 悬空
• message parent 悬空或循环
• tool_calls 类型错误
• binding 指向不存在或已删除会话
• ACL 枚举错误
• constraint 引用失效
• archive 引用不存在会话

每个自动修复动作只能用于匹配的问题类型。循环、驱动反序列化失败和无法确认的归档问题只报告，不猜测修复，也不回退 raw SQL。

审计

批量操作、ACL/规则写入、诊断捕获、请求清理和 provider 刷新都会先创建 running 审计，再记录成功或失败结果。进程意外中止后，遗留的 running 审计会在下次启动时标记为失败和中断。

只读与权限

建议生产环境首次启用时设置：

readonly = true

只读模式不仅禁用前端入口，后端也会拒绝所有写入、捕获、清理和修复 RPC。即使操作在关闭只读时完成预览，执行前重新开启只读也会阻止 apply。

Console authority：

• 普通读取：3
• 写入、正文查看、正文捕获与清理：4

配置

| 配置项 | 默认值 | 范围 | 说明 | | --- | ---: | ---: | --- | | readonly | false | boolean | 后端拒绝所有写操作 | | pageSize | 40 | 10-200 | 默认分页大小 | | maxOperationRows | 20000 | 100-100000 | 单个操作快照的最大对象数 | | operationBatchSize | 200 | 10-1000 | 批量执行的批次大小 | | maxPreviewRows | 100 | 10-500 | 预览样例数，不限制执行数 | | maxIntegrityRows | 5000 | 100-100000 | 单次完整性扫描上限 | | traceRetentionDays | 14 | 1-90 | 请求索引保留天数 | | traceBodyRetentionHours | 24 | 1-72 | 诊断正文保留小时数 | | traceBodyLimit | 262144 | 16384-1048576 | 单个规范化正文字符上限 | | captureDefaultMinutes | 15 | 1-60 | 默认捕获时长 | | captureMaxMinutes | 60 | 1-120 | 最大捕获时长 |

数据所有权

ChatLuna Core 完全拥有以下表；本插件不会重复 model.extend()：

• chatluna_conversation
• chatluna_message
• chatluna_binding
• chatluna_acl
• chatluna_constraint
• chatluna_archive
• chatluna_meta

本插件只定义：

• chatluna_data_trace
• chatluna_data_audit

从 0.8 升级

1.0 是破坏性重构。以下功能及旧 RPC 已删除：

• Koishi 权限页和 chatluna-data.permission.* 指令
• Koishi 身份刷新和自动权限分配
• ChatLuna/adapter 配置编辑
• preset CRUD
• 全局日志诊断台和手工报错研判
• raw SQLite 扫描与修复
• 任意消息 CRUD

旧表 chatluna_data_identity 和 chatluna_data_ops_error 不再注册或访问，但升级不会自动删除它们。确认不再需要历史数据后，请使用当前数据库后端的官方管理工具自行备份并清理。

前端与后端必须同时升级，不提供旧 RPC 的静默兼容别名。

开发与验证

yarn install
yarn typecheck:server
yarn typecheck:client
yarn test
yarn build
npm run check:package

从源码仓库构建并部署到 Koishi Desktop 默认实例：

npm run deploy:local

指定其他实例目录：

powershell -ExecutionPolicy Bypass -File scripts/deploy-local-koishi.ps1 -InstancePath 'D:\path\to\instance'

部署脚本会执行双端类型检查、测试、构建和包内容检查，将 tarball 写入实例的 .yarn/local，更新实例依赖并运行 Yarn 安装。脚本不会修改 koishi.yml，也不会自动启动或重启 Koishi。

自动发布

.github/workflows/ci.yml 会在分支推送和 Pull Request 上执行冻结安装、双端类型检查、测试、构建和 npm 包内容检查。

npm 信任发布器的 workflow 文件名必须配置为 publish.yml。发布支持两种入口：

• 推送与 package.json 版本一致的 v* 标签，例如 v1.0.0。
• 在默认分支手动运行 Publish to npm，输入与 package.json 一致的版本。

git tag v1.0.0
git push origin v1.0.0

稳定版本发布到 latest；1.1.0-alpha.1、1.1.0-beta.1、1.1.0-rc.1 等预发布版本分别使用对应的 npm dist-tag。工作流通过 GitHub OIDC 发布，不读取长期 npm token，并会拒绝已存在的 npm 版本。

详细实现约束和施工记录见 REFACTOR_PLAN.md。