01 - 项目概览¶

项目定位¶

AI 骰娘4(aiplugin4)是运行在 SealDice 上的 JavaScript 插件,为骰娘接入 OpenAI 兼容格式的大模型 API,让骰娘具备智能对话能力,并深度整合海豹骰子生态的 TRPG 功能(属性检定、牌堆抽取、COC 模组等)。

核心特性:

智能对话:基于 OpenAI 兼容 API,支持上下文感知、角色设定、示例对话。
记忆体系:长期记忆(向量检索 + 标签/用户/群组过滤)、观察记忆、配置驱动的知识库(JSON 配置 + Markdown 正文自动分块)。
工具系统:内置 60+ 工具函数(TRPG 检定、牌堆、图片、语音、禁言、消息、定时器等),支持函数调用与提示词工程两种模式;支持外部 MCP 服务器与可配置技能。
图片与媒体:图片识别、表情包制作、Markdown/HTML 渲染为图片、本地图片/语音资源;语音合成与文生图内置(4.24.0 起,在「模型配置」里用 kind: "tts" / "gen" 声明,异步任务队列 + 完成唤醒,不再依赖 tts/tti 依赖插件)。
权限体系:命令权限(会话权限/用户权限/强触权限三维)与工具权限(禁止/默认关闭/按会话开关)。
可观测性:结构化日志(级别控制、密钥脱敏)、token 用量统计与图表、工具调用审计。

技术栈¶

类别	选型
语言	TypeScript(源码),打包后为单个 JS 文件
打包	esbuild(`tools/build.js`),产物 `dist/aiplugin4.js`,头部拼接 `header.txt` 的 UserScript 注释
运行时	SealDice 的 JS 插件沙箱(通过全局 `seal.*` API 交互,`puerts` 环境),浏览器平台目标
模型接入	OpenAI 兼容 HTTP API(`fetch`),支持对话/图片理解/嵌入三类模型,以及语音合成/文生图媒体用途
配置解析	模型配置为一个 JSON(v5,取代旧的两个 TOML 框,`src/config/v5/`);角色/技能/MCP/知识库也各自为一个 JSON(`src/config/domain/`);知识库正文按 Markdown 自动分块;媒体用途默认用内置供应商预设(`src/config/static_config/media_presets.ts`,按 vendor + 模型名给出原生请求结构),需要时用该模型 `request.body` 里的 `{占位符}` + 嵌套表逐键合并覆盖
模板渲染	Handlebars(system prompt、记忆、工具提示词等模板)
流式输出	通过配套后端服务中转(见 08-相关后端项目)
冒烟测试	Node 内置 `seal` 桩(Proxy 兜底)加载打包产物
CI	GitHub Actions(构建检查 + 手动发布 Release)

版本信息¶

src/config/static_config/meta.ts 中 VERSION = "4.27.0",作者 baiyu&错误,插件名 aiplugin4。
开发遵循「分支 + squash PR」流程(见 07-开发指南);近期工作围绕:记忆 v2 引擎与心智模型、配置分组重组(角色设定/上下文拆分)、工具结果原文保留与只读检索、全局分用途模型覆盖、MCP 会话工作区、token 估算校准、模型配置 v4(api连接/模型规则)、公开会话目录、子代理委派(DSH 对齐)、MCP/技能/知识库平台白名单、上下文编辑工具组、语音合成与文生图内置(tts / image-generation 用途 + 异步任务队列)、媒体送达三段式与同步等待窗口(4.25.0)、待机群上下文成本治理(冷热态 / 归档分片 / 记忆结算 / .ai ctx，4.26.0)、联网搜索接入层(10 家 provider + web_fetch，4.26.0)、配置 JSON 化(角色/技能/MCP/知识库 + 联网默认项拆分配置，4.26.1)、后端配置整合为单 JSON + 论坛独立页签 + 图片 URL HTML 实体解码(4.27.0)等。
README 顶部徽章与 VERSION 保持一致（当前 4.27.0）(详见 09-注意事项与常见问题)。

环境要求¶

SealDice v1.4.6+;图片相关功能在分离部署(napcat/llonebot 协议)下建议 v1.5.0+。
大模型 API:OpenAI 兼容格式。
本地开发:Node.js + npm(构建使用 esbuild,建议使用较新 Node 版本;package.json 中 engines.node >= 10 是模板遗留)。

顶层目录结构¶

aiplugin4/
├── src/                  # TypeScript 源码(插件全部逻辑)
│   ├── index.ts          # 插件入口:装配与事件注册
│   ├── pipeline.ts       # 消息管线(非指令/指令/机器人消息)
│   ├── agent/            # 智能体编排(含流式与 DSH 对齐子代理框架 subagent/)
│   ├── cmd/              # .ai 命令系统与权限(含 tts/tti/media 媒体生成命令)
│   ├── media/            # 媒体生成任务队列(异步提交/结算/唤醒,4.24.0 起)
│   ├── pub/              # 公开会话目录(.ai pub + pub_read/pub_send 工具)
│   ├── config/           # 配置注册/读取与静态常量
│   ├── context/          # 会话上下文与消息结构
│   ├── memory/           # 记忆/知识库服务
│   ├── model/            # 模型注册表/连接列表拉取与分类/per-model 请求规则/媒体模板与响应解析
│   ├── prompt/           # system prompt 分节组装
│   ├── resource/         # 图片资源(Image)
│   ├── session/          # 会话/群档案/用户档案
│   ├── tool/             # 工具系统(MCP/技能/内置工具)
│   ├── utils/            # 通用工具函数
│   ├── logger.ts         # 日志模块
│   ├── timer.ts          # 定时器管理
│   ├── changelog.ts      # 版本更新日志
│   ├── usage.ts          # token 用量统计与图表
│   └── trigger.ts        # 触发模块(预留)
├── tools/                # 构建脚本(build.js / build-config.js)
├── scripts/              # smoke.js 冒烟、prepare-sealpack.js / build-release.js 打包、deps.cjs 依赖清单、release-notes.js 发布正文
├── types/                # seal.d.ts(SealDice API 类型定义)
├── dist/                 # 构建产物 aiplugin4.js
├── dev/                  # build-dev 产物(带 sourcemap)
├── build/                # 陈旧的 tsc 输出(与构建流程无关,见注意事项)
├── sealpack/             # SealRepo 打包源(info.toml / assets/icon.png,scripts/main.js 自动同步)
├── skills/               # 开发用 skills(aiplugin4-test-suite)
├── .github/workflows/    # build-check.yml / release.yml
├── header.txt            # 打包时拼接到产物头部的 UserScript 注释
└── package.json

各模块的详细说明见 03-核心模块详解。