核心概念
Monstrum 概念与术语
本文档定义 Monstrum 平台中的所有抽象概念和技术名词。阅读架构文档或源码前，建议先通读本文。
目录
- 设计范式
- 核心概念辨析
- 资源模型
- 权限模型
- 工具体系
- 执行架构
- 会话与消息
- 记忆系统
- 提示词管理
- 事件系统
- 工作流
- 任务与调度
- 插件系统
- SDK
- 网关与适配器
- 用户与多租户
- 审计与成本
- LLM Provider
- 设计原则速查
设计范式
从工具到行为主体
管理 AI Agent 和管理组织中的员工，在结构上是同一件事。在 Monstrum 中，AI Bot 不是 LLM 的包装器，而是一个受管的行为主体——拥有身份、权限、凭据、记忆和预算的独立实体。
| 员工得到什么 | Bot 得到什么 |
|---|---|
| 身份与角色 — 姓名、职位、部门 | Bot 档案 — 名称、描述、模型、性格提示词 |
| 能力边界 — “你可以使用这些工具” | 工具可见性 — 只有被授权的工具存在于 Bot 的世界中 |
| 凭据 — 门禁卡、钥匙（看不到保险柜密码） | 加密凭据 — 在执行层使用，AI 永远看不到 |
| 策略约束 — “生产环境只读” | 声明式 scope 规则 — 参数级检查，由代码强制执行 |
| 记忆 — 经验、上下文、团队知识 | 分区记忆 — 全局、频道、任务、资源四种 scope |
| 标准流程 — SOP、检查清单 | 工作流 — 可视化 DAG 编辑器，支持分支、并行、审批节点 |
| 团队协作 — 委派任务、共享上下文 | Bot 间委派 — 权限只能收窄，永远不能扩大 |
| 预算 — 支出限额、费用追踪 | Token 预算 — 实时消耗追踪，超额自动终止 |
| 行为记录 — 考勤、审计 | 审计日志 — 每次工具调用、每次 LLM 请求、每个 Token 都有记录 |
| 沟通渠道 — 邮件、Slack、电话 | 多渠道网关 — Slack、飞书、Telegram、Discord、Webhook |
这不是类比——这是 Monstrum 的核心设计范式。Bot 是受管的行为主体，不是 LLM 的包装器。
平台强制，而非 AI 自律
AI Agent 有能力但不可信——它会幻觉、会被注入、会越权。不能靠 AI 自律来保证安全。
Monstrum 的核心主张：安全由平台架构保证，而非依赖 AI 的自我约束。
- LLM 说”我不会访问那个仓库”？→ 不够。平台让它根本看不到那个仓库的工具
- LLM 说”我不会泄露 API Key”？→ 不够。平台从不把明文凭据交给 LLM
- LLM 说”我只操作授权范围”？→ 不够。平台在每次工具调用后校验参数是否越界
治理三原则
1. 最小权限 — 看不到 = 不存在
Bot 只能看到被显式授权的工具。未绑定的 Resource 对 Bot 完全不可见——不是”可见但禁止调用”，而是 LLM 根本不知道它们的存在。
2. 凭据隔离 — LLM 永远碰不到密钥
凭据 AES-256 加密存储。执行时由平台解密注入到 Executor 层，LLM 在整个生命周期中接触不到任何明文。
3. Fail-Closed — 出错就停
任何环节出错，结果是”Bot 什么也做不了”，而不是”不受限制”：
- ToolResolver 出错 → 返回空工具列表
- Guardian 出错 → 拒绝请求
- EventDispatcher 投递前 re-check 失败 → 阻止投递
核心概念辨析
Bot vs Agent vs LLM
| 概念 | 是什么 | 在 Monstrum 中的实体 |
|---|---|---|
| LLM | 大语言模型，纯推理引擎。接收 prompt 和工具定义，返回文本或工具调用。 | LLMProvider（API 配置）、ModelInfo（模型元数据） |
| Bot | Monstrum 平台上的受管 AI 实体。拥有身份、权限、配置、记忆、预算。 | Bot 模型。一个 Bot = 一个 LLM 配置 + 一组资源绑定 + 权限策略 + 运行时状态。 |
| Agent | 具有自主决策能力的 AI 程序。在 Monstrum 中有两个含义（见下文）。 | 取决于上下文。 |
Session vs Task
| Session | Task | |
|---|---|---|
| 触发 | 用户发 IM 消息 | API 调用 / 定时调度 / Bot-to-Bot 委托 / 事件触发 |
| 交互 | 多轮对话，有上下文 | 单次执行，独立上下文 |
| 生命周期 | 空闲 30 分钟回收 | 执行完毕即结束 |
| 记忆 | MemoryContext（三层缓存，scope 分区） | AgentRuntime 加载全局+任务记忆 |
Executor vs Integration
| Executor | Integration | |
|---|---|---|
| 本质 | 工具执行的内部引擎 | 一个完整的集成包（声明 + 执行逻辑） |
| 用户交互 | 平台内部，用户不直接接触 | 通过控制台或 SDK 上传声明式 YAML 清单 |
| 内置 vs 自定义 | 8 个内置执行器 | 内置集成 + 用户自定义集成 |
资源模型
Monstrum 的资源管理是三层抽象：声明能力 → 实例化连接 → 授权绑定。
ResourceType（资源类型）
能力声明。定义一个集成”能做什么”。
| 字段 | 说明 |
|---|---|
id | 唯一标识（如 ssh、mcp、github） |
tools: ToolDef[] | LLM 可调用的工具定义 |
scope_dimensions | 参数级权限检查规则 |
auth_methods | 支持的凭据获取方式 |
credential_schema | 凭据字段定义 |
config_schema | 连接配置字段定义 |
内置类型（8 个）： SSH、MCP、Bot、Local、Web、Browser、RMCP、Docker
Resource（资源实例）
具体的外部系统连接。一个 ResourceType 可以有多个 Resource 实例。
BotResource（资源绑定）
Bot 与 Resource 之间的授权关系。这是权限的核心载体。
权限模型
两层独立的安全过滤，任意一层都足以阻止越权。
RolePermissions（运行时权限）
| 字段 | 说明 |
|---|---|
allowed_operations | 操作 glob 列表（如 ["issue.*", "pr.read"]） |
allowed_tools | 工具 glob 列表（动态类型专用） |
scope_constraints | 参数级约束（如 {"repos": ["org/repo-*"]}) |
delegate | 委派约束 DelegateConstraints |
ScopeDimension（权限维度声明）
声明式规则，插件开发者只需声明”检查什么”，平台自动执行。
工具体系
ToolDef（工具定义）
LLM 可调用的工具声明，定义在 ResourceType 中。
ToolCatalog（工具目录）
数据驱动的全局工具索引。启动时从 DB 加载所有 ResourceType 的工具定义。
两类工具
| 外部资源工具 | Bot 自有能力工具 | |
|---|---|---|
| 本质 | Bot 访问外部系统 | Bot 操作自己的数据 |
| 例子 | SSH / MCP / GitHub | 记忆、调度、工作流、进度 |
| Pre-LLM | BotResource 绑定过滤 | BotRuntimeConfig 开关 / 始终注入 |
| Post-LLM | Guardian scope 校验 | 不走 Guardian（所有权天然保证） |
执行架构
AgentRuntime（Agent 执行引擎）
核心 LLM 调用循环。接收任务，构建 system prompt，循环调用 LLM 和工具直到完成。
Agent Mode（推理模式）：
| 模式 | 行为 |
|---|---|
reactive | 直接执行，不输出计划（默认） |
planning | 先输出编号计划，再逐步执行 |
adaptive | 计划 → 执行 → 反思 → 调整计划 |
会话与消息
Session（会话）
用户与 Bot 之间的活跃对话。会话 Key：(config_id|source, channel_id, bot_id)
生命周期： 首条消息 → 创建 Session → 每条消息 FIFO 处理 → 空闲 30 分钟 → 记忆提取 → 回收
会话持久化
频道级对话持久化。压缩阈值 80 条消息，LLM 总结旧消息，保留最近 50 条 + 摘要。
记忆系统
记忆 Scope
| origin 值 | 含义 | 可见范围 |
|---|---|---|
NULL | 全局记忆 | 所有场景 |
channel:{config_id}:{channel_id} | 频道记忆 | 该 IM 频道的会话 |
task:{task_id} | 任务记忆 | 该任务执行期间 |
resource:{resource_id} | 资源记忆 | 绑定了该 Resource 的场景 |
MemoryContext（记忆上下文）
Session 模式下的三层记忆缓存：base（全局+频道）、resource（资源相关）、injected（动态装入）。
提示词管理
9 个 prompt key 集中定义，支持三层覆盖：Bot 级 > Workspace 级 > 代码默认。
事件系统
覆盖全生命周期的事件（task.、workflow.、schedule.、session.、runner.、custom.）。支持 Bot 订阅和 Workflow 触发。
工作流
可视化 DAG 工作流，支持步骤类型：START、END、RESOURCE_CALL、CONDITION、PARALLEL、WAIT、APPROVAL、LLM_CALL、FOR_EACH、SUB_WORKFLOW。
三种触发方式：API 直接触发、定时调度、事件触发。
插件系统
自定义集成通过声明式 YAML 清单定义，指定工具、凭据、权限维度和认证方式。你可以通过控制台或 Python SDK 上传集成清单，平台自动处理凭据注入、权限执行和审计日志。
SDK
Monstrum 提供 Python SDK（pip install monstrum），用于以编程方式管理 Bot、触发任务、查询审计日志以及上传自定义集成。所有 SDK 调用都经过完整的权限检查链路。详见 SDK 指南。
用户与多租户
所有实体（Bot、Resource、审计日志）按 Workspace 隔离。支持 OWNER、ADMIN、MEMBER、VIEWER 四种角色。
审计与成本
全链路审计条目（ActionLog），Token 统计（TokenStatistics），预算执行（monthly_token_budget → 超预算自动终止）。
设计原则速查
| 原则 | 一句话 |
|---|---|
| Bot 是行为主体 | 不是 LLM 包装器，是平台给 LLM 套的管控壳 |
| 平台强制，非 AI 自律 | 安全由架构保证，不依赖 LLM 的自我约束 |
| 最小权限 | 看不到 = 不存在 |
| 凭据隔离 | LLM 永远碰不到明文凭据 |
| Fail-Closed | 出错 → Bot 什么也做不了 |
| 声明式权限 | 插件声明 ScopeDimension，平台通用引擎自动检查 |
| 两层独立过滤 | Pre-LLM + Post-LLM，任一层都足以阻止越权 |
| 委派不放大 | 子 Bot 有效权限 = 委派约束 ∩ 自身权限 |
| Workspace 隔离 | 所有实体按工作区隔离 |