AI 骰娘4 (aiplugin4) 项目知识库¶
面向开发者的项目知识库,基于当前工作区代码整理。 面向普通使用者的安装、配置与命令手册请参阅项目根目录的 README。
这是什么¶
AI 骰娘4 是一个运行在 SealDice 上的 JS 插件,为骰娘接入 OpenAI 兼容的大模型 API,提供智能对话、TRPG 辅助工具、记忆/知识库、图片处理、定时任务等能力。
文档导航¶
| 文档 | 内容 |
|---|---|
| 01-项目概览 | 项目定位、核心能力、技术栈、版本信息、顶层目录结构 |
| 02-架构设计 | 分层架构、核心概念、消息处理流程、一次 AI 回复的完整链路 |
| 03-核心模块详解 | src/ 各模块职责、关键类与函数 |
| 04-工具系统 | 工具注册机制、内置工具清单、MCP、技能、工具权限 |
| 05-命令与配置 | .ai 命令体系、权限体系、配置分组总览、Prompt 模板 |
| 06-数据存储 | SealDice 存储键清单、序列化/反序列化机制、会话 ID 格式 |
| 07-开发指南 | 构建/测试命令、添加工具/配置/命令/智能体的操作步骤 |
| 08-相关后端项目 | 配套后端服务(独立仓库 aiplugin4-backends)的说明 |
| 09-注意事项与常见问题 | 与 README 的差异、已知问题、排障提示 |
| 10-TODO 与后续计划 | 待办事项、环境适配后需落地的改动清单 |
| 11-ob11-core-bridge-使用指南 | OB11 核心桥中间件：部署、SealDice/协议端/插件控制 WS 接入、工具参数与排障 |
| 12-配置JSON化方案 | 已实现：角色 / 技能 / MCP / 知识库从多框模板改为单框 JSON String，配套生成器四页签；新键名、schema v1、校验/回退；联网搜索「默认项」改为插件配置项；测试与实现说明 |
| 16-图片生命周期与图床方案 | 已实现（image-host 后端 1.0.14 + 插件 4.27.0 接入）：图片在建图/收图时上传入库（不落插件 base64 存储）、哈希去重 + 引用计数、来源/标签/重命名、WebUI 画廊（鉴权）、MCP 工具、交叉清理与对账；第一部分方案、第二部分实现细化（文件划分/路由/DDL/SQL/伪码/签名）、第三部分批量能力与性能实测，§35 为当前实现状态 |
| 17-图片引用标准与AI图库交互 | 已实现（插件 4.28.0 + image-host 1.0.15）：[img:<ref>] 通用引用标准（CIR v1）+ ImageRefAdapter 翻译层；工具返回图片来源（工具调用所在群，不写“未知”）与英文类型标签（按产出工具映射，不调识图；元数据与标签分离，不与元数据重复）；image_view / image_to_text 批量看图（≤4 / ≤3）；image_keep/tag/unkeep 批量处理（≤50）；模型可达性、urlBroken 自愈与回退链；含全量 img 标签覆盖矩阵、提示词定稿、测试与分期 |
阅读建议¶
- 首次接触项目:先读 01-项目概览 与 02-架构设计。
- 需要改代码:先读 07-开发指南,再按需查阅 03-核心模块详解 与 04-工具系统。
- 排查线上问题:优先看 02-架构设计 的消息流程和 09-注意事项与常见问题。
维护约定¶
- 本知识库描述的是当前工作区代码;若代码结构发生变化,请同步更新对应文档。
- 文档中的文件路径相对
docs/目录,代码路径相对仓库根目录。 - 与 README 描述不一致时,以代码为准;差异已在 09-注意事项与常见问题 中说明。
- 已实现的设计/方案文档（原 12 子代理、13 模型配置 v5、14/15/17 上下文成本治理、18 联网搜索）已在 4.26.0 发布后清理；其中仍属当前行为的注意事项 / 硬约束已并入 03/04/05/06/09（汇总见 09 的「已实现方案的关键不变量」），历史推导与调研内容见 Git 历史（v4.26.0 及更早提交）。16（图片生命周期与图床）已在 4.27.0 实现，保留为「方案 + 实现规格 + 当前状态」文档。