31 — 通用 Agent 架构设计¶
状态:设计提案(评审意见与修订路线见 §17)
适用项目:Remilia
设计目标:将现有 AI 插件演进为可通过自然语言驱动多种工具、软件和执行环境的通用 Agent 平台。
前置文档:
26-ai-layering.md— AI 插件分层27-ai-freeze-checklist.md— AI 架构冻结清单29-ai-package-boundaries.md— AI 分包边界30-ai-mcp-architecture.md— MCP 接入架构评审
1. 背景与目标¶
1.1 当前问题¶
现有 AI 插件已经具备一定的 Agent 基础,包括:
- LLM 请求与工具调用循环。
- Tool、Skill 等动作的注册与执行。
- 工具目录、能力端口与执行器分层。
- 任务计划的创建和步骤更新。
- 工具调用权限、人工审批、超时、中断等机制。
- MCP 工具来源接入所需的部分架构基础。
这些能力解决了 AI 如何选择和调用工具的问题,但距离完整的通用 Agent 仍有差距。
主要差距不在于 LLM 能否生成代码,而在于系统能否可靠地完成一项跨越多个工具、执行环境和软件的任务。
例如,用户提出:
帮我检查项目里的性能问题,修改代码,运行测试,然后整理修改报告。
系统需要完成的不只是生成工具调用,还需要:
- 理解用户目标与约束。
- 确定任务需要访问的工作区。
- 拆解任务并安排执行顺序。
- 读取文件、分析代码、修改代码。
- 运行测试并收集真实结果。
- 根据结果决定是否需要继续修复。
- 处理中途失败、超时、取消和人工审批。
- 保存任务进度与产物。
- 验证目标是否达成,并向用户交付结果。
这一流程同样适用于浏览器操作、软件配置、文件处理、数据分析和其他自动化场景。
因此,架构目标应从“提供 AI 工具调用能力”提升为“提供通用任务执行能力”。
1.2 核心目标¶
建设一个以任务为中心、以能力为执行手段、以执行环境为资源边界、以策略系统为安全边界的通用 Agent 平台。
平台需要满足以下要求:
- 任务通用性:任务模型不绑定编码、浏览器或某一种软件。
- 能力可扩展性:内置工具、插件、MCP 服务和其他能力来源可以统一接入。
- 执行环境可替换性:同一类任务可以在本机、远程机器或隔离环境执行。
- 执行可控性:支持权限检查、人工审批、超时、取消和资源预算。
- 过程可恢复性:能够持久化任务状态,在进程重启后恢复可恢复的任务。
- 结果可验证性:任务完成不能仅依赖模型自行宣称成功。
- 结果可追溯性:记录执行步骤、调用结果、审批记录和最终产物。
1.3 非目标¶
本阶段不追求一次性实现所有 Agent 能力。
明确暂不作为第一阶段目标的内容:
- 多 Agent 自主协作与动态组队。
- 完全自主的桌面视觉操作。
- 无边界的本机 Shell 或系统管理权限。
- 任意环境中的透明迁移与执行恢复。
- 通用分布式工作流编排平台。
- 复杂的长期记忆、人格和自主目标系统。
- 通过 MCP 协议直接替代执行环境管理。
第一阶段优先建立稳定的任务模型与执行基础设施,再通过具体应用场景验证设计。
2. 设计原则¶
2.1 从工具中心转向任务中心¶
工具调用是任务执行过程中的一种行为,不应成为整个系统的核心抽象。
平台需要区分:
- Task:用户希望达成的目标及其约束。
- Plan:为了完成目标而制定的执行方案。
- Step:计划中的一个可追踪执行步骤。
- Capability:系统可以调用的原子能力。
- ExecutionNode:实际承载任务执行的环境或节点。
- Artifact:任务过程中产生或最终交付的文件、报告、日志、截图等产物。
Task 负责表达目标,Plan 负责表达执行意图,Capability 负责表达可执行动作,ExecutionNode 负责提供执行环境。
它们不能相互替代。
2.2 通用核心与场景专用逻辑分离¶
Agent Runtime 不应知道如何编译 Go 项目、填写网页表单或操作某一种桌面软件。
这些差异应通过能力和执行适配器表达。
例如:
- 编码 Agent 是通用 Agent 使用文件、Git、命令执行和测试能力的场景组合。
- 浏览器 Agent 是通用 Agent 使用网页导航、页面读取和表单交互能力的场景组合。
- 数据分析 Agent 是通用 Agent 使用文件读取、数据处理、计算和报告生成能力的场景组合。
通用核心负责调度与治理,场景专用模块负责提供更高层的领域能力。
2.3 模型负责决策,程序负责约束¶
LLM 可以提出执行计划、选择工具、分析结果和调整策略。
但以下行为必须由确定性的程序逻辑保障:
- 权限检查。
- 审批流程。
- 任务状态迁移。
- 超时与资源预算。
- 工具调用参数校验。
- 执行环境隔离。
- 取消与生命周期管理。
- 结果记录与审计。
不能把安全性或任务正确性寄托在 Prompt 上。
2.4 不将外部协议等同于执行环境¶
MCP 是外部工具和上下文能力的接入协议,不是完整的任务运行时,也不是远程桌面协议。
通过 MCP 暴露的工具可以参与任务执行,但本地文件系统、进程生命周期、远程工作区、容器管理和产物收集仍需要独立的执行抽象。
2.5 优先建立最小稳定接口¶
第一阶段只实现能够形成完整闭环的能力,不提前建设庞大的抽象体系。
抽象是否进入核心层,应由多个实际执行场景的共同需求决定,而不是仅因未来可能需要而预先引入。
3. 总体架构¶
3.1 逻辑分层¶
┌───────────────────────────────────────────────────────┐
│ Interaction Layer │
│ QQ / Discord / Telegram / Web / API / Commands │
└──────────────────────────┬────────────────────────────┘
│ 用户请求 / 任务事件
┌──────────────────────────▼────────────────────────────┐
│ Agent Runtime │
│ Goal Understanding / Reasoning / Tool Calling Loop │
│ Plan Proposal / Result Interpretation / Replanning │
└──────────────────────────┬────────────────────────────┘
│ 执行意图
┌──────────────────────────▼────────────────────────────┐
│ Task Runtime │
│ Task Lifecycle / Step Scheduler / Budget / Recovery │
│ Cancellation / Checkpoint / Verification / Events │
└────────────┬────────────────────┬─────────────────────┘
│ │
┌────────────▼─────────┐ ┌───────▼─────────────────────┐
│ Capability Runtime │ │ Policy Runtime │
│ Catalog / Resolver │ │ Permission / Approval │
│ Invocation / Result │ │ Risk / Audit / Constraints │
└────────────┬─────────┘ └─────────────────────────────┘
│
┌────────────▼──────────────────────────────────────────┐
│ Execution Runtime │
│ Local Node / Remote Node / Container / Adapters │
│ Workspace / Process / Browser / Application │
└────────────┬──────────────────────────────────────────┘
│
┌────────────▼──────────────────────────────────────────┐
│ Artifact Runtime │
│ Files / Diffs / Logs / Reports / Screenshots │
│ References / Checksums / Provenance │
└───────────────────────────────────────────────────────┘
横切基础设施:
Persistence / Observability / Configuration / Lifecycle
这是逻辑架构,不要求每一层在第一版都成为独立 Go 包或独立进程。
3.2 六个核心子系统¶
| 子系统 | 核心职责 | 不负责的内容 |
|---|---|---|
| Agent Runtime | 推理、计划提议、能力选择、结果分析、重规划 | 自行绕过权限执行动作 |
| Task Runtime | 任务生命周期、步骤调度、预算、恢复、取消、验证流程 | 直接实现具体软件操作 |
| Capability Runtime | 能力目录、解析、调用、统一结果 | 管理任意执行环境的生命周期 |
| Execution Runtime | 工作区、进程、远程节点、运行时适配 | 决定用户任务的最终目标 |
| Policy Runtime | 权限、风险、审批、审计 | 依赖模型自行遵守安全规则 |
| Artifact Runtime | 产物登记、引用、收集、交付 | 代替任务状态机判断完成 |
Persistence、Observability 和 Lifecycle 属于横切基础设施,可以复用项目已有的实现。
4. Agent Runtime¶
4.1 职责¶
Agent Runtime 负责将自然语言目标转化为可执行的任务意图,并在执行反馈的基础上持续决策。
核心职责包括:
- 理解用户目标、约束和预期结果。
- 识别尚未明确且影响执行的重要信息。
- 选择直接执行、先规划或向用户询问。
- 生成和更新计划提案。
- 从 Capability Catalog 中选择可用能力。
- 生成结构化工具调用参数。
- 分析工具返回的真实结果。
- 决定继续执行、调整计划、请求审批或结束任务。
- 生成面向用户的进度说明与最终摘要。
4.2 执行循环¶
接收任务上下文
│
▼
判断当前信息是否足够
│
├── 否 ──> 向用户澄清
│
▼
制定或更新计划提案
│
▼
选择下一项动作
│
▼
交由 Task Runtime 调度
│
▼
接收执行结果
│
├── 需要继续 ──> 分析与重规划
│
├── 需要审批 ──> 等待授权
│
├── 需要澄清 ──> 等待用户
│
▼
验证目标是否达成
│
├── 未达成 ──> 继续执行或报告失败
│
▼
形成最终交付
Agent Runtime 可以继续使用现有 LLM 客户端和 Tool Calling Loop,但应逐步把任务级生命周期从单次对话循环中剥离出来。
4.3 决策与执行分离¶
模型可以提议:
- 调用哪个能力。
- 传入什么参数。
- 下一步执行什么。
- 是否需要调整计划。
实际执行前,系统必须再次确认:
- 能力当前仍然存在且可用。
- 参数通过 Schema 校验。
- 当前调用者拥有必要权限。
- 当前任务具备对应的工作区与执行环境。
- 所需审批已完成。
- 当前任务预算和执行限制允许该操作。
模型生成的工具调用不应直接等同于已授权的执行请求。
5. Task Runtime¶
Task Runtime 是本次架构升级的核心。
它负责将一次自然语言请求变成有明确状态、可观察、可控制和可恢复的任务实例。
5.1 Task 数据模型¶
建议第一版采用以下逻辑模型:
type Task struct {
ID string
OwnerID string
SessionID string
Goal string
Constraints TaskConstraints
Status TaskStatus
PlanVersion uint64
Steps []TaskStep
WorkspaceID string
NodeID string
Budget TaskBudget
Artifacts []ArtifactRef
CreatedAt time.Time
UpdatedAt time.Time
}
上述结构用于说明职责边界,不是要求直接照搬的最终 Go 接口。实际实现应根据仓库现有 ID、时间、存储和领域模型统一规范。
TaskConstraints 至少应支持:
- 用户明确提出的限制。
- 允许访问的工作区。
- 允许使用的能力范围。
- 执行时间和资源预算。
- 是否允许产生外部副作用。
- 结果验证要求。
- 审批策略引用。
5.2 Plan 与 Task 分离¶
Task 描述目标和约束;Plan 描述为达成目标而提出的步骤集合。
建议单独定义版本化计划:
type Plan struct {
TaskID string
Version uint64
Steps []TaskStep
}
type TaskStep struct {
ID string
Description string
Status StepStatus
Dependencies []string
Action *ActionRequest
Result *StepResult
}
需要明确:
- Plan 是可被修改的执行提案,不是不可变的用户目标。
- 计划更新必须产生新版本或可追溯的变更记录。
- 已完成步骤的历史结果不能因为重新规划而被静默覆盖。
- 计划中的依赖关系必须经过程序校验。
- 只有具备明确输入、输出和执行语义的步骤,才能交由调度器执行。
- 模型不能通过修改 Plan 来覆盖权限、预算或任务约束。
5.3 任务状态机¶
建议 Task 状态至少包括:
pending:已创建,尚未开始。planning:正在分析目标或生成计划。ready:具备执行条件。running:正在执行。waiting_approval:等待人工审批。waiting_input:等待用户补充信息。paused:已暂停。succeeded:目标已通过要求的验证。failed:任务失败。cancelled:任务已取消。interrupted:执行中断,等待恢复策略处理。
状态机必须明确合法迁移。例如,waiting_approval 不能在审批未通过时直接迁移到 running;cancelled 不能因为迟到的工具结果而被覆盖为 succeeded。
interrupted 是运行时恢复状态,不应简单等同于任务失败。恢复时必须重新验证环境、任务版本和未完成步骤的执行情况。
5.4 Step 状态机¶
Step 与 Task 使用不同的状态机。
建议包括:
pendingreadyrunningwaiting_approvalsucceededfailedskippedcancelled
Task 可以继续运行,而某个 Step 已失败。例如,非关键步骤失败后,Agent 可能调整计划或选择替代方案。
5.5 调度器职责¶
Task Scheduler 负责:
- 选择满足依赖条件的就绪步骤。
- 控制并发度。
- 施加任务级和步骤级预算。
- 在执行前进行策略检查。
- 启动能力调用并关联执行上下文。
- 收集结果并更新状态。
- 处理超时、取消与失败。
- 触发后续验证或重规划。
第一版不必实现通用 DAG 工作流引擎。先支持顺序执行、显式依赖和受控并发即可。
5.6 持久化与恢复¶
不能把进程内 Session 当作唯一任务记录。
至少需要持久化:
- Task 当前状态和版本。
- Plan 及其变更记录。
- Step 状态与执行结果。
- 正在等待的审批和用户输入。
- 已产生的 Artifact 引用。
- 执行节点与工作区引用。
- 重要事件和审计信息。
恢复任务时,不应直接重放所有未完成工具调用。
应先判断调用是否已经产生副作用、执行环境是否仍然存在,以及调用是否具有幂等性。对于无法安全判断的操作,应进入人工确认或明确失败状态。
6. Capability Runtime¶
6.1 职责¶
Capability Runtime 是 Agent 与实际工具之间的统一入口。
它需要处理:
- 能力注册与注销。
- 能力来源识别。
- 目录快照与版本管理。
- 能力发现与解析。
- 输入 Schema 校验。
- 调用分发。
- 结果规范化。
- 调用超时与取消传播。
- 调用追踪和错误分类。
现有 ToolProvider、Capability、Catalog、Invoker 和 MCP 相关抽象应优先在这一层复用。
6.2 Capability 的定位¶
Capability 表示系统可以执行的一个有明确输入、输出和副作用语义的动作。
建议至少区分以下信息:
type CapabilityDescriptor struct {
ID ActionID
Description string
InputSchema Schema
OutputSchema Schema
Effects []Effect
Requirements []Requirement
Source CapabilitySource
}
这是逻辑示意,不要求立即新增完全相同的公共结构。
能力描述应区分:
- 稳定身份。
- 面向模型的名称与描述。
- 输入和输出约束。
- 可能产生的副作用。
- 执行所需的资源或环境。
- 权限与审批要求。
- 能力来源及其版本。
能力的模型可见名称不应成为唯一身份键。应继续遵循现有 MCP 架构评审中对 ActionID、不可变工具定义与版本化 Catalog Snapshot 的设计方向。
6.3 能力分类¶
建议按照职责,而不是按照技术来源分类。
| 类别 | 示例 |
|---|---|
| Information | 读取文件、查询状态、获取网页内容 |
| Workspace | 创建文件、编辑文件、检查差异 |
| Process | 运行测试、执行构建、启动受控进程 |
| Application | 调用应用专用接口、执行软件操作 |
| Browser | 打开页面、读取页面、填写表单 |
| Communication | 发送消息、创建通知 |
| Artifact | 保存报告、登记截图、生成交付清单 |
这些分类可以作为发现与策略的元数据,但不要求每种分类都建立一个独立运行时。
6.4 能力来源¶
Capability Runtime 应支持多个来源:
- Remilia 内置工具。
- 插件提供的能力。
- 用户或管理员配置的 Skill。
- MCP Server 暴露的工具。
- 本机或远程执行节点暴露的能力。
- 后续引入的浏览器、桌面或其他软件适配器。
来源之间必须统一身份、目录、调用、错误和策略语义。
但统一接口不意味着所有来源具有相同的信任级别。MCP Server 和第三方插件仍应接受独立的权限、信任和资源约束。
7. Execution Runtime¶
7.1 为什么需要独立的执行运行时¶
Capability 说明“可以做什么”,Execution Runtime 说明“在哪里做,以及如何控制执行过程”。
例如,process.run 是一种能力,但实际运行时还必须决定:
- 使用哪个节点。
- 运行在哪个工作目录。
- 继承哪些环境变量。
- 能访问哪些文件。
- 使用什么身份运行。
- 允许消耗多少资源。
- 如何取消和回收进程。
- 如何收集标准输出、错误输出和退出码。
这些问题不应散落在每个工具实现里。
7.2 ExecutionNode¶
ExecutionNode 表示一个可承载任务执行的环境。
第一版可以定义以下逻辑接口:
type ExecutionNode interface {
ID() string
Capabilities() []NodeCapability
PrepareWorkspace(
ctx context.Context,
req WorkspaceRequest,
) (Workspace, error)
Execute(
ctx context.Context,
req ExecutionRequest,
) (ExecutionResult, error)
Cancel(
ctx context.Context,
executionID string,
) error
}
这是职责示意,具体接口应根据现有 Go 项目的错误处理、生命周期和资源管理约定调整。
7.3 第一阶段节点类型¶
优先实现两类节点。
LocalNode
负责本机受控执行,包括:
- 工作区访问。
- 文件操作。
- 受控进程启动。
- 进程超时与取消。
- 输出收集。
- 产物回收。
RemoteNode
负责将执行请求转发到远程执行服务,包括:
- 节点身份认证。
- 执行请求传输。
- 远程工作区管理。
- 状态与结果回传。
- 取消与超时传播。
- 节点健康状态管理。
RemoteNode 可以后续实现,但其接口边界应在架构阶段确定。
7.4 Workspace¶
Workspace 是任务访问文件和执行进程的明确边界。
建议至少包含:
- Workspace ID。
- 所属任务或授权范围。
- 执行节点 ID。
- 工作目录。
- 文件访问策略。
- 创建与清理策略。
- 当前版本或快照引用。
不能仅依靠一个任意路径字符串来表达任务对整个文件系统的访问权。
默认应将任务限制在指定工作区内;访问工作区之外的路径必须经过独立策略检查。
7.5 Process Execution¶
进程执行接口应明确支持:
- 命令及参数。
- 工作目录。
- 环境变量白名单或显式配置。
- 标准输入、标准输出和标准错误。
- 超时时间。
- 取消信号。
- 退出码。
- 输出大小限制。
- 资源限制。
- 进程启动与结束时间。
默认不应将模型生成的任意 Shell 字符串直接交给具有完整用户权限的 Shell 执行。
优先使用明确的可执行程序、参数数组和受控环境。对于确实需要 Shell 语义的场景,应作为风险更高的执行模式单独授权。
7.6 远程执行边界¶
远程节点应有独立的认证和授权机制。
至少要求:
- 节点身份验证。
- 任务与节点之间的授权绑定。
- 传输加密。
- 执行请求 ID 和幂等处理。
- 超时与取消协议。
- 结果完整性校验。
- 远程产物引用与生命周期管理。
- 节点断连后的状态判定。
MCP 可以用于接入远程工具,但不应替代上述执行节点协议。
8. Policy Runtime¶
8.1 职责¶
Policy Runtime 为所有实际副作用建立统一的策略入口。
现有 RBAC、工具审批和调用上下文能力应优先复用,逐步从单次工具调用层面扩展到任务与执行环境层面。
策略至少应回答:
- 谁发起了任务?
- 任务允许访问什么资源?
- 当前能力是否允许被调用?
- 当前调用会产生什么副作用?
- 是否需要人工审批?
- 审批覆盖哪些具体参数与资源?
- 执行期间授权是否仍然有效?
- 如何记录和审计最终结果?
8.2 风险分级¶
建议采用可配置的风险策略,而不是为每一个工具硬编码独立审批逻辑。
| 风险级别 | 典型操作 | 建议策略 |
|---|---|---|
| 低 | 读取授权范围内的文件、查询状态 | 自动执行 |
| 中 | 修改工作区文件、执行普通测试 | 根据工作区策略自动放行或审批 |
| 高 | 安装软件、执行外部脚本、访问敏感路径 | 默认要求审批或更严格的隔离 |
| 严重 | 删除重要数据、修改生产系统、执行不可逆操作 | 明确授权、强约束或直接禁止 |
风险级别是策略输入,不是唯一授权依据。即使某个操作被标记为低风险,也必须通过资源权限和任务约束检查。
8.3 审批模型¶
审批请求应绑定具体操作,而不是只批准一个模糊的自然语言目标。
建议至少包含:
- Task ID。
- Step ID。
- Capability ID 与版本。
- 关键调用参数或其摘要。
- 目标资源。
- 风险说明。
- 申请时间与失效时间。
- 审批人和审批结果。
如果执行参数、目标路径、执行节点或重要副作用发生变化,应重新评估审批是否有效。
审批通过不应成为永久授权,也不能让嵌套 Skill、MCP 工具或后续重规划绕过策略入口。
8.4 最小权限¶
执行环境应默认遵循最小权限:
- 仅访问授权工作区。
- 仅使用必要的环境变量。
- 默认不继承敏感凭证。
- 默认限制网络访问范围。
- 为进程设置资源和时间预算。
- 对危险操作进行明确授权。
- 将第三方能力视为独立信任域。
9. Artifact Runtime¶
9.1 为什么产物需要独立建模¶
任务的结果不只是模型回复中的一段文本。
一个任务可能产生:
- 代码修改。
- Git Diff。
- 测试报告。
- 编译日志。
- 文件或压缩包。
- 截图。
- 浏览器操作结果。
- 数据分析报告。
- 操作审计记录。
这些结果需要能够被发现、引用、校验和交付。
9.2 Artifact 模型¶
建议将产物作为具有稳定身份和来源信息的对象管理。
type Artifact struct {
ID string
TaskID string
StepID string
Kind string
Name string
URI string
MediaType string
Size int64
Digest string
CreatedAt time.Time
}
上述模型仅为设计示意。实际结构需要根据存储方式、文件系统和远程节点的能力进一步收敛。
产物元数据至少应回答:
- 产物属于哪个任务和步骤?
- 由哪个执行节点产生?
- 内容存放在哪里?
- 内容是否发生变化?
- 用户是否有权读取?
- 产物是否仍然有效?
- 是否可以在最终回复中直接交付?
9.3 Artifact 与 Workspace 的关系¶
Workspace 是任务执行时的工作空间,Artifact 是需要被登记、追踪或交付的结果。
工作区内的每个文件都不必自动成为 Artifact。
只有被任务流程明确登记的结果,才进入产物管理流程。代码修改场景可以将 Diff、测试报告和最终修改文件作为重点产物。
10. MCP 与现有插件体系的关系¶
10.1 MCP 的定位¶
MCP 是 Capability Runtime 的一种外部能力接入方式。
它负责将远端或外部服务的工具描述映射为内部能力,并管理协议连接、工具发现和调用。
MCP 不负责:
- 定义用户任务状态机。
- 管理通用任务计划。
- 决定任务是否完成。
- 代替执行节点管理本地进程。
- 统一管理所有工作区。
- 代替全局审批与审计系统。
10.2 统一调用路径¶
所有能力来源都应经过统一的调用与策略路径:
Agent Runtime
│
▼
Task Runtime
│
▼
Policy Runtime ──> 权限与审批判定
│
▼
Capability Resolver
│
├── 内置工具
├── 插件工具
├── Skill
├── MCP 工具
└── ExecutionNode 能力
│
▼
统一结果与错误处理
│
▼
Task Runtime 更新状态
具体实现中,纯只读动作可以采用较轻的策略路径;但所有会产生副作用的动作都必须经过足够的权限和执行约束检查。
10.3 现有模块的复用原则¶
| 现有模块或能力 | 在新架构中的定位 | 处理建议 |
|---|---|---|
protocol |
LLM 协议与消息模型 | 保持协议边界,不承载任务领域状态 |
toolkit |
工具定义、动作描述及相关端口 | 逐步统一为 Capability 领域表达 |
catalog |
能力目录、解析与相关注册逻辑 | 保留并明确版本化目录语义 |
runtime |
工具调用运行机制与执行器 | 复用调用机制,避免直接承担完整 Task Runtime |
execution |
执行辅助、输出捕获等机制 | 保留可复用机制,逐步明确环境执行职责 |
decision |
权限、审批或调用判定相关逻辑 | 与新的 Policy Runtime 对齐 |
mcp |
外部能力接入 | 作为 Capability Source 继续演进 |
| AI 主循环 | 模型推理和工具调用 | 保留为 Agent Runtime 的基础执行循环 |
上述映射是目标边界,不意味着现有包已经完整实现对应的全部新职责。
重构应通过明确接口逐步迁移,避免一次性将现有代码大规模搬迁到新目录。
11. 错误处理、重试与重规划¶
11.1 区分错误类型¶
任务执行至少需要区分:
- 参数错误:请求无法通过输入校验。
- 权限错误:当前调用者无权执行。
- 审批等待或拒绝:策略不允许直接继续。
- 环境错误:工作区、进程或执行节点不可用。
- 能力错误:工具不存在、来源断连或调用失败。
- 业务失败:操作执行完成,但目标条件未达成。
- 验证失败:执行返回成功,但结果未通过验证。
- 基础设施错误:存储、网络或运行时发生故障。
- 取消或超时:任务或步骤未在预算内完成。
不能将所有错误都转成一段普通字符串后交给模型自行判断。
11.2 重试策略¶
重试必须由程序根据错误语义和动作特征决定是否允许。
适合重试的情况可能包括:
- 可恢复的网络错误。
- 明确可重试的服务限流。
- 只读请求的暂时性失败。
不应盲目重试的情况包括:
- 未知是否已产生副作用的写操作。
- 重复执行可能造成重复扣款、重复发送或重复删除的操作。
- 权限拒绝。
- 人工审批未通过。
- 参数不合法。
11.3 重规划策略¶
当当前计划无法继续时,Agent 可以提出新的计划,但必须保留原有执行记录。
重规划前应向模型提供:
- 已完成步骤及其真实结果。
- 失败步骤及其错误类别。
- 当前工作区状态。
- 已产生的产物。
- 剩余预算。
- 当前策略限制。
重规划结果仍需经过 Task Runtime 的结构校验和 Policy Runtime 的权限检查。
11.4 完成判定¶
任务完成必须满足预定义的完成条件。
例如:
- 文件修改任务:目标文件已发生预期变化。
- 编码任务:要求的测试和构建检查通过。
- 浏览器任务:页面状态或业务结果符合要求。
- 数据分析任务:目标报告已生成且结构符合要求。
如果没有明确的验证器,可以采用模型辅助评估,但应标记为低置信度验证,而不是把它等同于确定性的成功。
12. 持久化与可观测性¶
12.1 任务事件¶
建议为关键状态变化建立统一事件模型,例如:
TaskCreatedPlanUpdatedStepStartedCapabilityInvokedApprovalRequestedApprovalResolvedStepCompletedStepFailedArtifactRegisteredTaskPausedTaskResumedTaskCompletedTaskFailedTaskCancelled
事件模型不要求第一版立即使用完整事件溯源架构。
第一阶段可以采用普通关系型或嵌入式存储持久化当前状态,并额外记录关键事件,满足审计、恢复和问题排查需求。
12.2 追踪关联¶
建议所有调用都能够关联:
- Task ID。
- Step ID。
- Tool Call ID。
- Capability ID。
- Execution ID。
- Workspace ID。
- Execution Node ID。
这样可以将用户请求、模型决策、工具执行、远程调用和最终产物串联起来。
12.3 预算与成本¶
任务级预算至少应包括:
- 最大执行时长。
- 最大步骤数。
- 最大工具调用次数。
- 最大并发数。
- 单步骤超时。
- 输出大小限制。
- 可选的模型 Token 或费用预算。
所有预算都必须由运行时强制执行。模型只能在剩余预算内提出动作,不能自行提高预算上限。
13. 第一阶段最小实现¶
第一阶段的目标不是拥有最多工具,而是建立一个完整、可靠的任务闭环。
13.1 必须实现¶
- Task、Plan、Step 的最小领域模型。
- Task 与 Step 状态机。
- Task Runtime 与现有工具调用循环之间的清晰接口。
- 持久化任务状态。
- 受控的本机 Workspace。
- 文件读取、文件修改和差异查看能力。
- 受控进程执行。
- 统一的权限与审批入口。
- 超时、取消和错误分类。
- Artifact 登记与最终结果交付。
- 基础的任务进度查询。
- 至少一类真实结果验证器。
13.2 第一阶段暂缓¶
- 完整远程节点集群。
- 浏览器视觉操作。
- 任意桌面应用自动化。
- 多 Agent 协作。
- 通用事件触发和定时执行平台。
- 复杂的长期记忆与自主任务生成。
- 大规模分布式任务调度。
这些能力应在核心任务模型通过真实场景验证后再增加。
14. 分阶段实施路线¶
Phase 0:架构冻结¶
目标:确定最小领域模型与模块边界。
交付:
- Task、Plan、Step、Artifact 的定义。
- 状态机与状态迁移规则。
- Capability、ExecutionNode、Workspace 的职责边界。
- Policy Runtime 的调用契约。
- 与现有 AI 插件的模块映射。
- 第一阶段验收标准。
Phase 1:Task Runtime¶
目标:让现有 Agent 能以可追踪的任务方式执行工作。
交付:
- 任务创建和查询。
- 计划版本管理。
- 步骤调度。
- 任务持久化。
- 取消与超时。
- 基础恢复策略。
- 进度事件。
验收:重启前后可以查询已持久化的任务状态;任务取消后不能被迟到的工具结果错误覆盖。
Phase 2:Local Execution Runtime¶
目标:提供受控的本机执行能力。
交付:
- Workspace 管理。
- 文件读写。
- Diff 获取。
- 进程启动与回收。
- 输出收集。
- 执行预算与路径限制。
- Artifact 登记。
验收:任务能够在授权工作区内修改文件、运行测试并交付真实结果;超时与取消能够终止受控进程。
Phase 3:编码场景闭环¶
目标:用编码任务验证通用架构,而不是将架构永久限定为编码 Agent。
交付:
- 项目分析。
- 代码修改。
- 测试运行。
- 基于测试结果的有限重规划。
- 修改报告与 Diff 交付。
验收:能够执行一个多步骤编码任务,并基于实际测试结果判断成功或失败;模型不能通过声称成功绕过验证。
Phase 4:Remote Execution Runtime¶
目标:将任务执行从机器人所在进程中解耦。
交付:
- 远程节点注册与认证。
- 远程工作区。
- 执行请求和结果协议。
- 取消、超时与断连处理。
- 远程产物引用。
验收:相同的 Task 与 Capability 调用契约可以通过不同执行节点运行,不需要把任务业务逻辑重写一遍。
Phase 5:通用软件操作¶
目标:扩展到编码之外的实际工作场景。
按独立适配器逐步加入:
- 浏览器操作。
- 文档与表格处理。
- 应用专用 API。
- 桌面软件操作。
- 数据分析与报告生成。
每一种适配器都应提供明确的能力描述、权限要求、结果语义和验证方式。
Phase 6:长期任务与自动触发¶
目标:在前述运行时稳定后,支持更长生命周期的自动化。
候选能力:
- 定时任务。
- 事件触发。
- 人工接管与恢复。
- 长期任务检查点。
- 多 Agent 协作。
这一阶段应独立评估,不能作为第一阶段的前置条件。
15. 验收标准¶
整个架构是否成功,应由以下指标判断,而不是工具数量。
15.1 通用性¶
- 新增一种软件能力,不需要修改 Task Runtime 的核心状态机。
- 新增一种执行节点,不需要重写 Agent 决策循环。
- MCP 工具与内置工具使用一致的任务调度和策略入口。
- 编码场景专用逻辑不侵入通用任务模型。
15.2 可靠性¶
- 任务状态迁移合法且可追踪。
- 超时和取消能够传播到受控执行过程。
- 任务恢复不会默认重复执行具有非幂等副作用的操作。
- 失败、审批等待和用户等待有明确状态。
- 最终成功必须满足任务定义的验证条件。
15.3 安全性¶
- 每次实际副作用执行前都有策略检查。
- 审批绑定具体操作和关键参数。
- 工作区访问范围明确。
- 进程执行具有资源限制。
- 第三方能力不会因统一接入而自动获得信任。
- 关键操作可以追溯到发起者、任务和执行节点。
15.4 可维护性¶
- Task、Capability、ExecutionNode 和 Artifact 的职责清晰。
- 现有 AI 插件能力可以逐步迁移,不需要整体推倒重写。
- 核心接口可通过单元测试和契约测试验证。
- 各执行节点能够独立测试与替换。
16. 最终结论¶
Remilia 的 AI 插件应演进为通用 Agent 平台,但这一演进不应表现为不断给现有工具调用循环添加新功能。
核心变化是建立一个独立于具体应用场景的任务执行层:
- Agent Runtime 负责决策。
- Task Runtime 负责任务生命周期。
- Capability Runtime 负责能力发现与调用。
- Execution Runtime 负责执行环境。
- Policy Runtime 负责安全与授权。
- Artifact Runtime 负责结果与交付。
现有的工具目录、能力端口、执行器、审批机制和 MCP 接入能力仍然具有价值,应尽量复用。
第一阶段以本机受控执行为基础,通过一个能够修改文件、运行测试、验证结果并交付产物的完整编码任务验证架构。编码只是验证场景,不是平台的边界。
当 Task Runtime、Execution Runtime 和 Policy Runtime 的职责稳定后,浏览器、桌面软件、远程节点和其他自动化能力就可以作为可替换的扩展加入,而不必再次重构整个 Agent 核心。
最终目标:让用户只需描述想要达成的目标,由 Agent 在明确的权限、环境和预算约束下,可靠地完成任务并交付可验证的结果。
17. 评审补充与修订路线¶
本节是在 §1–§16 定稿后追加的评审意见:先核对设计与代码现状的差距,再给出一组收敛化的实施顺序、兼容性约束、风险与验收补充。实施阶段以本节为准,§14 的分期作为终局参考保留。
17.1 现状核对(评审时实测)¶
| 设计中的假设 | 代码现状 | 判定 |
|---|---|---|
| LLM 请求与工具调用循环 | builtin/ai/process.go 的 processWithTools:流式、并行工具、重试预算、反思与重规划指令 |
✅ 比本文描述更成熟 |
| Tool/Skill 注册与执行 | toolkit(Tool/Registry/Provider)、catalog(快照/发现)、runtime(三种 Invoker) |
✅ |
| 目录、能力端口、执行器分层 | catalog/snapshot.go、catalog/capabilities.go、runtime/invoke.go |
✅ 能力端口当前只有记忆/待办/提醒三类 |
| 任务计划与步骤更新 | session/plan.go + catalog/plantool.go:软计划,无依赖、无版本、无验证、无独立任务实体 |
⚠️ 种子,不是 Task Runtime |
| 权限、审批、超时、中断 | decision.go 单一策略闸门 + execution/approval.go(epoch ID、按钮/文本双通道)+ 回合中断 |
✅ 均为"回合内、进程内"语义 |
| MCP 接入基础 | 已是独立插件:stdio/HTTP、握手与无状态协议、安全(命令/环境白名单、SSRF、TLS)、软不可用、端到端可执行 | ✅ 本文低估了 |
| Task/Plan(版本化)/Step/Artifact/Workspace/ExecutionNode | 全仓库无对应实现 | ❌ 从零开始 |
| 执行环境与进程执行 | 仅 MCP stdio 与 updater 插件有 os/exec;无通用进程执行助手、无沙箱 |
❌ 最大缺口 |
| 持久化 | infra/storage(GORM+SQLite)、infra/kv(LevelDB);会话落库;builtin/job、builtin/scheduler 均为内存态 |
⚠️ 无任务表、无恢复协议 |
| 管理面 | api/server.go 路由硬编码,插件不能注册路由;已有 scheduler/auditlog 路由与 dashboard SPA |
⚠️ 任务 UI 需新增 API + Dashboard |
身份模型 ActionID |
toolkit/identity.go 已定义测试,但生产路由仍按名称;即文档 30 的 M0 尚未落地 |
⚠️ 本文的前置依赖 |
17.2 评估结论¶
- 可行性:高。 没有根本性阻碍,且目录/审批/MCP/会话持久化已可复用。
- 合理性:方向合理,但"通用平台"作为当前目标偏早。 仓库的既有原则是"第二个真实场景出现再做抽象"(
docs/notes/README.md);当前只有一个场景(对话机器人),缺少宿主执行的安全基础设施与管理面。 - 两个硬约束: 宿主执行 + 不可信用户群(群聊)是最高的安全风险;
builtin/ai现有行为已按 27 号冻结清单锁定,任何任务化改造不得造成对话行为回归。
17.3 设计收敛建议¶
- 第一阶段把六个运行时收敛为四个概念面:Task 领域模型(Task/Plan/Step/状态机/存储)、Capability 描述扩展(效应/风险/幂等/schema 校验)、执行适配器(先本地 Workspace + 受控进程)、策略扩展(参数指纹、变更重审)。Artifact 先做"引用 + 交付"最小实现。
- Agent Runtime 与 Task Runtime 之间先定义最小契约:
ProposeSteps(observation) → []Step与Interpret(outcome) → Verdict;现有processWithTools先扮演 Agent 角色,不整体重写。 - 明确 Task 与 Session/回合模型的关系:任务如何从消息产生、进度如何播报、取消从"回合中断"升级为"任务取消"、二者互不覆盖;后台推进复用
runner.go的既有模式。 - ExecutionNode 接口延后固化:先实现 LocalExecutor 内部接口;容器/远程节点出现第二个实现时再定协议(本文 §2.5 原则)。
- 补齐与既有子系统的复用映射:任务表复用
infra/storage;产物复用附件存储思路(builtin/messagelog/attachments);触发复用builtin/scheduler;编排参考builtin/job;审计复用builtin/auditlog;观测复用infra/metrics、infra/health、EventBus。 - 声明对文档 30 的依赖顺序:
ActionID落地与目录代数(30 的 M0)先于能力/策略扩展。 - 命名与包归属:
builtin/ai/runtime已被 LLM 调用运行时占用;任务领域建议builtin/ai/task,执行环境作为独立子系统(沿用 MCP 的"独立插件 + 自持配置节"先例,如plugins.exec)。 - 配置边界:任务/执行配置不塞进
plugins.ai,避免配置膨胀(30 号 §8 的结论)。
17.4 修订后的实施路线¶
| 阶段 | 目标与交付 | 关键验收 | 风险 |
|---|---|---|---|
| 0 设计冻结与信任模型 | 任务/计划/产物 schema;Task↔Session 映射;Agent↔Task 契约;默认关闭的信任模型;危险动作清单 | 评审通过;危险动作与拒绝策略成文 | 低 |
| 1 任务化(不新增执行能力) | 把软 Plan 升级为持久 Task:所有权、状态机、计划版本、查询/取消;对话路径不变 | 重启后任务可查;取消后迟到的工具结果不覆盖状态;冻结用例全绿 | 低 |
| 2 能力抽象与策略扩展 | 30 的 M0:ActionID 成为路由/去重键、目录代数、ActionPolicy 增加效应/风险/幂等、调用前 schema 校验 |
新增能力不改状态机;审批绑定参数指纹 | 中 |
| 3 本地执行(强管控) | Workspace 根目录与路径策略、文件读写 + diff、受限进程执行(可执行 + 参数数组 + allowlist + 环境清洗 + 超时/输出上限/进程树回收);仅管理员白名单 | 工作区外访问 100% 拒绝;超时/取消能终止进程树;无 shell 字符串直通 | 高(安全) |
| 4 编码场景闭环 | 分析→修改→真实测试→基于结果判定→diff/报告交付;确定性验证器;产物登记与聊天交付 | 多步任务端到端成功;模型自证成功不被接受 | 中高 |
| 5 任务 UX 与管理面 | /ai task 命令族、任务 API 路由、Dashboard 任务页(可选)、进度播报 |
多平台可用;取消 ≤ 约定时延生效 | 中 |
| 6 第二真实场景 | 运维巡检(只读优先)或报表生成,用第二个场景检验通用性 | "新增能力不改 Task Runtime 状态机"成立 | 中 |
| 7 隔离执行 | 容器/远程 executor 独立插件;此时才固化 ExecutionNode 协议 | 同一 Task 契约在本地与远程节点均可运行 | 中高 |
| 8 扩展 | 浏览器/桌面/多 Agent/定时触发;独立评估,不作为前置 | 按需 | 高 |
与 §14 的差异:新增阶段 1 的"任务化"使第一份交付就有用户价值且不碰执行面;把 30 的 M0 前置为阶段 2;编码场景从第三阶段提前,用真实场景驱动执行层;远程节点后移并明确以容器/远程隔离兜底安全问题;补齐任务管理面。
17.5 兼容性要点¶
- 可用的接入缝(均已存在):插件描述符依赖声明、
TryService/ExportIface、ctx.Spawn/SpawnNamed/TaskGroup/After/RegisterCron、EventBus、health.CheckProvider、storage服务、permission服务、插件级 Prometheus 注册表。 - 代码归属建议:任务领域与 Agent 装配放在
builtin/ai子包(纯逻辑、不持有*Plugin,遵守 29 号分包约束);执行环境独立成插件,避免 AI 插件热重载连带杀死在途任务,也避免plugins.ai配置膨胀。 - 行为冻结:任何改动以 27 号冻结用例与全量测试回归;用户可见变更记入
CHANGELOG.md。 - 平台差异:QQ/TG/Discord 的按钮、Markdown、消息长度限制影响进度播报与审批 UX,复用现有按钮通道。
- 热重载:任务状态必须在插件重载/进程重启后仍可查询;审批 ID 的 epoch 方案(
execution/approval.go)是可参考的先例。
17.6 实施难点与风险¶
排序后的难点:任务生命周期从回合循环中剥离且不回归(最难);宿主执行的跨平台控制与沙箱缺失;恢复时的副作用/幂等判定;参数 schema 校验与审批绑定(当前调用器不做校验,审批只带摘要);长任务的上下文与成本控制;确定性验证器;预算与配额强制执行;宿主执行的测试与 CI。
主要风险及缓解:
| 风险 | 等级 | 缓解 |
|---|---|---|
| 提示注入导致宿主 RCE | 最高 | 默认关闭;能力白名单;工作区根限制;参数校验;读取内容与执行动作策略分离;复刻 MCP 的外部内容边界标记到文件/进程输出 |
| 不可信群成员触发高权限/高成本任务 | 高 | 任务所有权=发起者;群内默认只读;管理员白名单;配额与限流 |
| 凭据泄露 | 高 | 环境变量白名单;工作区外路径拒绝;输出脱敏 |
| 现有对话行为回归 | 中高 | 27 号冻结用例 + 分阶段开关 + 任务化阶段不改对话路径 |
| 过度设计/无真实用户 | 中高 | 每阶段设停止条件;先做编码场景;第二个场景出现前不固化远程/浏览器抽象 |
| 任务在重载/重启中丢失 | 中 | 任务落库、独立于 AI 插件生命周期;参考审批 epoch 与 StatefulPlugin 状态迁移 |
| 资源滥用(挖矿、扫网、外传) | 中 | 资源预算 + 网络策略 + 审计 + 审批 |
17.7 验收标准补充¶
在 §15 基础上补充可量化项:
- 重启(进程与插件重载)后任务状态、计划版本与步骤结果可查询;恢复不自动重放非幂等步骤。
- 取消在约定时延内传播到受控进程;迟到的工具结果不能把
cancelled覆盖为成功状态。 - 每次产生副作用的调用前都有策略检查;审批绑定参数指纹,参数变化触发重审。
- 新增一种能力来源不需要修改任务状态机;MCP 与内置工具走同一调度与策略入口。
- 宿主执行:工作区外访问拒绝率 100%;环境变量白名单生效;无 shell 字符串直通。
- 27 号冻结用例与全量测试(含
-race)保持通过。
17.8 文档待办¶
实施过程中需要回填到本文件的内容:Task/Plan/Step 的最终 Go 类型与存储 schema;Agent↔Task 最小接口;Task↔Session 映射与进度播报策略;能力效应/风险/幂等字段定义;ActionID 路由的落地记录;执行子系统配置边界与信任模型;任务 API 与 Dashboard 的形态;各阶段验收的实测数据。
其中已完成回填:任务类型与存储 schema、Task↔Session 映射、执行子系统信任模型、任务 API 形态(见 §17.9);待回填:Agent↔Task 最小接口的最终形态、能力效应/风险字段、ActionID 路由、Dashboard 形态、各阶段验收实测数据。
17.9 实施状态(滚动更新)¶
| 路线阶段 | 状态 | 落点 | 说明 |
|---|---|---|---|
| 0 设计冻结 | ✅ 初版 | 本文件 §17、builtin/ai/task |
任务/计划/步骤类型与状态机(含终态保护)已定稿并落地 |
| 1 任务化 | ✅ | builtin/ai/task、builtin/ai/tasks.go、builtin/ai/taskapi.go、api/aitasks.go |
持久任务(ai_tasks 表)、计划镜像、/ai task 命令、取消联动、重启恢复、任务指标、REST 查询与取消 |
| 2 能力抽象与策略扩展 | 🚧 部分 | builtin/ai/protocol/argvalidate.go |
已落地调用前 Schema 校验;ActionID 路由与效应/风险/幂等字段待做 |
| 3 本地执行 | 🚧 部分 | builtin/ai/workspace、builtin/ai/procexec、builtin/ai/catalog/filetool.go、catalog/exectool.go |
工作区只读/写入、精确替换与 diff、白名单进程执行(强制审批、RBAC、环境清洗、整树回收、输出上限);容器与系统级沙箱未做 |
| 4 编码场景闭环 | ✅ 实测通过 | builtin/ai/evidence.go、catalog/plantool.go、builtin/ai/artifacts.go、tests/agent |
完成闸门 + 产物登记 + 端到端实测:真实 LLM(deepseek-flash)在远程节点上完成 5 步任务(列目录 → 写 fib.py → python3 运行 → uname -a → 汇报),3 次工具审批全部经人工批准,任务 succeeded、产物 fib.py 417 字节,节点侧文件与输出经 SSH 复核。实测数据:总耗时约 11s,预算消耗 3 次工具调用 |
| 5 任务 UX 与管理面 | ✅ | /ai task 命令、/api/v1/ai/tasks*、Dashboard「AI 任务」页 |
查询/取消/进度下钻(步骤与产物)齐备;进度播报复用既有计划消息与后台推进 |
| 6 第二真实场景 | ✅ 实测通过 | tests/agent |
运维只读巡检:同一套任务/能力/策略契约完成 4 条只读命令(df/uname/uptime/free)采集与中文报告,3 步计划全部成功、0 产物、4 次审批;证明通用架构不绑定编码场景 |
| 7 隔离执行 | ✅ 单节点 | builtin/ai/execnode、cmd/executor、ai.exec_node=remote |
远程节点(HTTP + Bearer、节点侧工作区/白名单、取消传播终止进程树)已落地并在 10.0.0.19 实测:认证、文件读写/替换/列举、越界拒绝、远程执行与取消传播全部通过。多节点选择、mTLS 与节点注册中心待需要时再做 |
| 8 扩展 | ⏳ 待评估 | — | 浏览器/桌面/多 Agent,按需独立评估 |
已落地的关键约定(供后续维护者对照):
- 任务类型与存储:
task.Task(ID / SessionID / OwnerID / ChatID / Platform / Goal / Status / PlanVersion / Steps / CreatedAt / UpdatedAt);存储表ai_tasks(显式表名,避免与同库records冲突)。 - 状态机:任务 11 态、步骤 8 态;终态(succeeded/failed/cancelled)无出边,
SyncPlan对终态任务返回ErrTaskTerminal(迟到的工具结果不能覆盖取消)。 - Task ↔ Session:任务按
platform:chatID:userID归属;计划动作(create_plan / update_plan_step)在调用点镜像到任务;取消有三个入口(/ai stop、/ai plan cancel、/ai task cancel)且都会同时取消计划与任务。 - 重启恢复:启动时把 running/planning 任务置为 interrupted,下一次计划推进回到 running,不重放步骤。
- 运行时预算:任务级预算(
task_max_tool_calls/task_max_duration)在工具调用前检查并累加,超限时任务失败并取消计划;预算计数在会话内按计划重置。 - 执行信任模型:能力默认关闭;
workspace_roots开启只读,workspace_allow_write开启写入(强制审批 +ai.file.write),exec_allowlist开启进程执行(强制审批 +ai.exec.run、命令白名单、环境变量白名单、工作区工作目录、整树回收)。
编码场景的最小可用配置(自托管、管理员使用):
plugins:
ai:
workspace_roots: ["./data/workspace"] # 只读文件能力
workspace_allow_write: true # 写入与精确替换(每次强制审批)
exec_allowlist: ["go", "git"] # 允许的验证/构建命令
exec_require_approval: true # 默认强制审批,保持开启
task_max_tool_calls: 200
task_max_duration: "2h"
尚未实施且刻意留待有真实消费者时再做的项(避免无消费者的抽象):ActionID 成为路由/去重键与目录可用性状态机(文档 30 的 M0,等第二个来源出现同名冲突时做)、能力效应/风险/幂等元数据(等远程节点或高风险能力接入时做)、任务事件总线接入(等第二个订阅方出现时做)。
17.10 浏览器与桌面能力评估¶
现状盘点(实测)
- 已有能力:
web_search(SearXNG 自建 / Serper,标题+链接+摘要)与fetch_url(仅 https 公网:URL 准入 + 拨号层 IP 二次校验 + 重定向逐跳校验,2MB / 4000 字上限,结果带外部数据边界标记,带并发出网上限与抓取缓存),来源cmd/bot/plugins/websearch,经ToolProvider进入目录,类别general(基线保留)。二者覆盖"搜索 + 静态网页正文"。两者安全边界不同:搜索端点是运维配置的固定地址(自建 SearXNG 常在回环/内网),拨号受信名单与同源重定向只对它生效,抓取路径始终要求公网地址。 - 能力缺口:JS 渲染页面(现代 SPA 正文抓不到)、登录态与 Cookie 会话、交互(点击/输入/滚动/上传/下载)、等待条件、截图与 PDF、页面内结构化提取。
- 执行节点环境(10.0.0.19,实测):无 node/npm/浏览器;
chromium-browser仅有 snap 包装;有xdotool、ImageMagickimport、xvfb-run;graphical.target活跃(存在图形会话,桌面自动化有打扰真人的风险);30GB 内存 / 16 核 / 27GB 空闲磁盘;sudo免密;Chrome 官方 deb 可下载。 - 关键前置缺口:多模态工具结果回灌。当前工具结果回填给模型的只有文本;MCP 的图片/音频附件只进入最终回复通道,模型看不到截图。任何"截图 → 视觉判断 → 下一步动作"的闭环都依赖它(属文档 30 的延后项)。
浏览器路径对比
| 路径 | 做法 | 优点 | 缺点 | 量级 |
|---|---|---|---|---|
| A. MCP 浏览器服务器 | 节点装 Node + Playwright MCP,经现有 MCP HTTP 接入 | 零框架开发;复用审批/权限/白名单;工具成熟 | 引入 Node 与外部工具链;工具粒度不受控;截图回灌仍缺;逐动作审批噪音大 | 1–2 天(含环境) |
| B. 节点原生浏览器能力(CDP) | execnode 增 browser_*:headless Chrome + 每任务独立 profile + 域名白名单 + 截图存产物 |
策略/身份/审批全在框架内;可做 DOM 断言验证;截图可登记为产物 | 需要 CDP 客户端与浏览器生命周期管理(进程、超时、回收) | 1–2 周 |
| C. 机器人宿主机浏览器 | 在 bot 进程所在机器跑 | 无网络跳转 | 与"执行隔离"方向相反,宿主污染与凭据风险最高 | 不推荐 |
桌面路径对比
| 路径 | 做法 | 风险 |
|---|---|---|
| D1. 隔离虚拟显示只读截图 | 节点起独立 Xvfb :99 + import/scrot 截图存产物 |
低(不接触真人会话),价值也有限 |
| D2. 桌面输入 | xdotool(X11)/ SendInput(Windows)点击、输入 |
高:节点存在活跃图形会话,误操作会打扰真人;必须有独立显示、应用白名单与强制审批 |
建议
- 浏览器优先于桌面:聊天助手场景里"读懂 JS 页面、能检索/填表"的价值远高于桌面自动化;桌面只做 D1(隔离显示只读),D2 暂缓。
- 先 A 后 B:先用 MCP 浏览器服务器做一周验证(与 30 号文档"外部能力优先走 MCP"的决策一致),若工具粒度、截图回灌或策略控制不满足,再实现节点原生 CDP 能力。
- 先补多模态回灌:否则浏览器退化成"文本抽取器",视觉闭环无从谈起。
- 现有的
fetch_url保持为首选轻量路径:浏览器动作只在"需要渲染或交互"时使用,工具描述里明确二者分工,避免每次都拉起浏览器。
共同安全约束(无论哪条路径)
- 域名策略:默认拒绝内网、回环与云元数据地址。出站统一走
infra/outbound(设计见 32 号笔记),按目标来源分三层:Untrusted(用户/模型给出的 URL,仅 https 公网)、TrustedOrigin(框架/平台自己产生的地址,命中所声明来源可走内网/明文)、OperatorEndpoint(运维配置的端点,同受信语义但不允许空来源)。fetch_url用Untrusted:URL 准入 + 拨号前对全部解析结果二次校验并直连已校验 IP(关掉 DNS 重绑定窗口)+ 重定向逐跳校验;后续浏览器与桌面能力必须复用同一策略,不得绕过。例外只有运维显式配置的端点:搜索端点(自建 SearXNG 常在回环/内网)为OperatorEndpoint,附件/图片的受信来源 = 平台适配器自声明(platform.MediaOriginProvider,如 OneBot 的media_base_url)+plugins.ai.allow_private_media_hosts/plugins.sauce.allow_private_media_hosts补充名单。名单只来自运维配置与适配器实现,用户/模型可控 URL 的路径不得进入受信来源,且拦截会计入outbound_blocked_total并输出限频 Warn,不再"静默失效"。 - 会话隔离:每任务独立浏览器 profile,不复用个人资料与 Cookie,不持久化登录凭证。
- 内容不可信:页面文本按外部数据标记(
fetch_url的搜索/抓取结果已包数据边界标记;MCP 外部工具与文件能力同款);点击、表单提交、上传等副作用动作强制人工审批。 - 资源:浏览器进程有内存上限与空闲回收,随任务取消终止。
- 下载/上传:下载落节点工作区并登记为产物(大小上限);上传仅允许来自工作区的文件。
- 验证:优先 DOM/文本断言,不把"截图看起来对"当作成功判据。
阶段与验收
| 阶段 | 内容 | 验收 |
|---|---|---|
| B0 | 节点安装 Chrome(deb)并做 headless 渲染冒烟:--dump-dom 抓取 JS 重页面 |
能拿到渲染后正文;记录安装体积与耗时 |
| B1 | 浏览器只读能力:browser_open / browser_read / browser_screenshot(截图登记为产物) |
SPA 正文可读;截图可在任务详情与 Dashboard 查看 |
| B2 | 交互能力:browser_click / browser_type / browser_wait,域名白名单 + 每次审批 |
完成一次真实检索型任务(不做敏感提交) |
| B3 | 视觉闭环:截图回灌 + 页面内验证断言 | 页面异常可被模型识别并重试 |
| D1 | 隔离显示只读截图 | 不接触真人会话的截图产物 |
| D2 | 桌面输入(评估后决定,默认不做) | — |
结论:search/fetch 已覆盖静态网页读取;浏览器能力补的是"渲染 + 交互 + 可视证据",是当前剩余缺口中最有实用价值的一块,且可以完全复用现有的任务、能力、审批与远程节点体系。桌面自动化在目标节点上"技术上可行、风险偏高"(存在活跃图形会话),只建议做隔离显示的只读部分。
远程执行节点(可选):
# 构建(Linux amd64 静态二进制)并部署
make executor-build
scp bin/remilia-executor-linux-amd64 <node>:/home/ubuntu/remilia-executor
ssh <node> 'chmod +x ~/remilia-executor && mkdir -p ~/remilia-ws'
# 在节点上启动(token 必填;-allow 为空时只提供文件能力)
ssh <node> 'setsid nohup ~/remilia-executor -addr 0.0.0.0:9020 \
-token <token> -roots ~/remilia-ws -allow go,git,uname,ls \
< /dev/null > ~/remilia-executor.log 2>&1 &'
机器人侧配置(本地 workspace_roots / exec_allowlist 在 remote 模式下不再使用):
plugins:
ai:
exec_node: "remote"
exec_remote_url: "http://10.0.0.19:9020"
exec_remote_token: "<token>"
workspace_allow_write: true
exec_require_approval: true
文件与执行动作要求 RBAC 权限:使用前需要为使用者授予 ai.file.read、ai.file.write(写入)与 ai.exec.run(进程执行);未授权时动作会被过滤出模型视野(模型会如实回答"没有这些工具"),而不是执行后报错。
端到端场景用例(真实 LLM + 远程节点,自动批准工具调用):
REMILIA_AI_API_KEY=<key> REMILIA_EXEC_NODE_URL=http://10.0.0.19:9020 \
REMILIA_EXEC_NODE_TOKEN=<token> go test -tags network ./tests/agent -run TestRemoteCodingScenario -v
联调(需要 network 构建标签,覆盖认证、文件、替换、越界拒绝、远程执行与取消传播):
REMILIA_EXEC_NODE_URL=http://10.0.0.19:9020 REMILIA_EXEC_NODE_TOKEN=<token> \
go test -tags network ./builtin/ai/execnode -run TestLiveRemoteNode -v
修订记录¶
| 版本 | 修订 |
|---|---|
| v1 | 初稿:六运行时逻辑架构、状态机、分阶段路线与验收标准 |
| v1.1 | 追加 §17 评审补充:现状核对、设计收敛、修订路线、兼容性、风险与验收细化 |
| v1.2 | 追加 §17.9 实施状态:任务化、工作区、受控进程执行、任务 API 的落地记录与剩余阶段状态 |
| v1.3 | §17.9 更新:阶段 4/6/7 完成端到端实测(编码场景与运维巡检场景,真实 LLM + 远程节点) |
| v1.4 | 追加 §17.10 浏览器与桌面能力评估:现状盘点、路径对比、安全约束、阶段与验收 |