mirror of
https://github.com/Wx-2025/ST-Amily2-Chat-Optimisation.git
synced 2026-06-06 19:45:50 +00:00
112 lines
3.4 KiB
Markdown
112 lines
3.4 KiB
Markdown
# Amily2Bus (Amily2 总线系统)
|
|
|
|
Amily2Bus 是 Amily2-Chat-Optimisation 插件系统的核心基础设施。它为所有子模块和外部插件提供了一个规范化、安全且高兼容性的运行环境。
|
|
|
|
## 核心特性
|
|
|
|
- **安全控制台 (SafeConsole)**: 通过 Iframe 逃生通道获取纯净 Console 引用，绕过 SillyTavern 等环境的日志劫持。
|
|
- **能力令牌 (Capability Token)**: 插件注册后获取专属上下文，自动绑定身份，实现日志追踪与文件隔离。
|
|
- **防超时网络层 (FakeStream)**: `ModelCaller` 支持伪流式聚合，通过持续保持 TCP 连接活跃，彻底解决 CloudFlare 524 超时问题。
|
|
- **位运算日志系统**: 基于位掩码的日志级别控制，支持针对特定插件或模块动态调整输出粒度。
|
|
- **异步责任链**: 预置 `Chain` 模块，支持插件化的异步中间件处理流程。
|
|
|
|
---
|
|
|
|
## 快速开始
|
|
|
|
### 1. 初始化
|
|
|
|
总线通常在系统启动时自动挂载到 `window.Amily2Bus`。
|
|
|
|
```javascript
|
|
import { initializeAmilyBus } from './SL/bus/Amily2Bus.js';
|
|
initializeAmilyBus();
|
|
```
|
|
|
|
### 2. 插件注册
|
|
|
|
所有插件必须注册以获取专属上下文：
|
|
|
|
```javascript
|
|
const amily = window.Amily2Bus.register('MyAwesomePlugin');
|
|
```
|
|
|
|
---
|
|
|
|
## 模块说明
|
|
|
|
### 1. 标准日志 (Logger)
|
|
|
|
支持 `debug`, `info`, `warn`, `error` 四个级别。
|
|
|
|
```javascript
|
|
// 自动绑定插件名，输出格式: [时间] [MyAwesomePlugin::Main] [INFO]: 消息内容
|
|
amily.log('Main', 'info', '插件已就绪');
|
|
```
|
|
|
|
### 2. 网络请求 (ModelCaller & Options)
|
|
|
|
统一处理 API 调用，支持自动切换 ST 配置文件 (Profile) 及防超时处理。
|
|
|
|
```javascript
|
|
const { Options } = amily.model;
|
|
|
|
const opt = Options.builder()
|
|
.setMode('direct') // 'direct' (直连) 或 'preset' (ST预设)
|
|
.setFakeStream(true) // 开启伪流式聚合，防止 524 超时
|
|
.setApiUrl('...')
|
|
.setApiKey('...')
|
|
.setModel('gpt-4o')
|
|
.build();
|
|
|
|
const result = await amily.model.call(messages, opt);
|
|
```
|
|
|
|
### 3. 文件操作 (FilePipe)
|
|
|
|
提供基于插件命名的虚拟文件系统隔离，防止插件间非法访问。
|
|
|
|
```javascript
|
|
// 写入文件 (自动定位到 /virtual_fs/MyAwesomePlugin/config.json)
|
|
await amily.file.write('config.json', { theme: 'dark' });
|
|
|
|
// 读取文件
|
|
const data = await amily.file.read('config.json');
|
|
```
|
|
|
|
### 4. 责任链 (Chain)
|
|
|
|
用于处理复杂的、可扩展的异步逻辑流。
|
|
|
|
```javascript
|
|
import { Chain } from './SL/bus/chain/Chain.js';
|
|
|
|
const pipeline = new Chain();
|
|
pipeline.use(async (ctx, next) => {
|
|
ctx.data += " -> 步骤1处理";
|
|
await next();
|
|
});
|
|
|
|
const context = { data: "开始" };
|
|
await pipeline.execute(context);
|
|
```
|
|
|
|
---
|
|
|
|
## 目录结构
|
|
|
|
- `Amily2Bus.js`: 总线入口，协调各模块。
|
|
- `log/Logger.js`: 位运算日志管理器。
|
|
- `file/FilePipe.js`: 安全文件操作管道。
|
|
- `api/ModelCaller.js`: 核心 API 调用器。
|
|
- `api/Options.js`: API 请求配置构建器。
|
|
- `chain/Chain.js`: 异步责任链工具。
|
|
|
|
---
|
|
|
|
## 开发规范
|
|
|
|
1. **强制类型**: `model.call` 必须接收 `Options` 类的实例，建议始终使用 `Options.builder()` 构建参数。
|
|
2. **路径安全**: 使用 `file` 接口时，禁止在路径中使用 `..` 等跳转符，系统会自动进行安全校验。
|
|
3. **日志分级**: 生产环境默认屏蔽 `debug` 级别，调试时可通过 `window.Amily2Bus.Logger.setLevel('PluginName', 'all')` 动态开启。
|