Ripple Agent System
Ripple Agent Runtime
一次请求进入 Server 后，会被拆成可恢复的会话、可验证的工具动作、可压缩的上下文和可持久化的用户工作区。
入口协议
运行态
执行边界
暂停恢复
领域流程
上下文管理
后台任务
事件协议
Module 01
请求入口：从 Chat API 进入运行时
入口层接收 OpenAI-compatible 请求，解析 user、model、stream 和 system prompt。
它的产物不是最终答案，而是一个已经绑定上下文和工具边界的 session。
- OpenAI-compatible messages
- model / stream / max_turns
- X-Ripple-User-Id
- 提取最后一条 user message
- 收集 caller system prompt
- 解析模型别名
- get_or_create_session()
- 新建或磁盘恢复
- 进入 stream / collect
Module 02
Session 与 Sandbox：运行态和工作区分层
session 保存一次对话如何继续推进。
user sandbox 保存同一用户长期共享的 workspace、凭证和任务状态。
.ripple/sandboxes/<user_id>chat state
same workspace
own runtime
Module 03
Message 模型：统一对话、工具和事件
模型 provider、前端 SSE 和内部 loop 都有自己的表达方式。
Message 层把它们收敛成稳定的 System、User、Assistant、Tool block 和 StreamEvent。
- SystemMessage
- UserMessage
- caller system prompt
- AssistantMessage
- text block
- tool_use block
- UserMessage
- tool_result block
- tool_use_id 关联
- session.messages：展示与追溯
- session.model_messages：模型上下文
- 压缩通常只影响模型历史
- messages/types.py
- messages/utils.py
- messages/cleanup.py
Module 04
Agent Loop：模型推理与工具事实闭环
模型负责提出下一步，系统负责执行边界内的动作。
工具结果不会直接变成最终答案，而是回到模型上下文再判断下一轮。
- lightweight cleanup
- should_compact()
- 同步 current_messages
- client.stream()
- StreamEvent 文本增量
- AssistantMessage 完整落地
- extract_tool_use_blocks()
- 并发安全工具可抢跑
- 没有工具则进入 stop hooks
- completed
- ask_user / permission
- max_turns / unrecoverable
- tool_result block
- 写回 model context
- 需要模型再理解一轮
- run_tools()
- 权限 / 沙箱 / 截断
- ToolResult 标准化
Module 05
流式 API：增量输出、工具参数和 usage 收口
文本、reasoning、tool arguments 和 usage 会分片到达。
API 层负责拼装缓冲区，最后产出 StreamEvent 和完整 AssistantMessage。
- text delta
- reasoning_content
- tool_calls[].function.arguments
- current_text
- tool_calls_map
- last_usage
- StreamEvent
- AssistantMessage
- usage calibration
- 包装为 <think> 文本块
- 复用 MarkdownRenderer 折叠
- 保留 _args_parse_error
- 工具层返回结构化错误
Module 06
工具系统：把模型意图变成受控副作用
Tool 抽象定义模型能调用什么，也定义系统如何安全执行。
编排层处理查找、去重、分批、权限、截断和 tool_result 标准化。
- name / description
- input schema
- risk_level
- max_result_size_chars
- requires_confirmation()
- is_concurrency_safe()
- log_input_summary()
- log_result_summary()
- tool_use id
- name
- input
- find tool
- dedup
- partition batches
- tool_result
- is_error
- source assistant uuid
Module 07
权限暂停：危险动作停在可恢复位置
危险工具在执行前被拦截，并写入等待确认的占位结果。
用户确认后，server 重放同一个 tool_use，并替换成真实结果。
- 执行工具
- 生成真实 tool_result
- loop 继续
- 保存 pending request
- 写等待占位 tool_result
- AgentStopEvent
Module 08
上下文压缩：长任务的模型窗口管理
展示历史可以完整保留，模型上下文必须控制在窗口内。
系统先做轻量清理，再尝试摘要，失败时进入定向裁剪和硬截断。
- lightweight_cleanup()
- 清理旧 tool_result / tool_input
- 每轮开始执行
- should_compact()
- 阈值约 75% context window
- 优先 LLM summary
- reactive_compact()
- targeted trim
- hard truncate 兜底
- API usage.input_tokens
- 扣除 system/tool overhead
- 反向修正估算缓存
- compact/auto_compact.py
- compact/summary.py
- compact/truncate.py
- compact/context_manager.py
Module 09
Skill 系统：把领域 SOP 注入工具使用方式
Skill 不新增底层副作用，而是组织已有工具的使用方式。
它声明适用场景、参数、允许工具、执行步骤和失败降级。
- SKILL.md
- YAML frontmatter
- name / description
- shared skills
- workspace/skills
- workspace 覆盖 shared
- SkillTool schema
- args 参数替换
- allowed tools 约束
- 把 skill 正文作为 tool_result
- 当前模型继续执行流程
- 通过 AgentTool 启动子 agent
- 适合复杂多步骤任务
Module 10
定时任务：后台执行仍然属于用户沙箱
Scheduler 由 Server 后台 tick 驱动，不依赖模型阻塞等待。
每次运行都写入状态和历史，command 与 agent job 都落在当前 user 边界内。
- execution_type: command / agent
- schedule_type: once / interval
- enabled / timeout / max_runs
- SchedulerManager tick
- 检查 next_run_at
- running marker 防重复
- command: user lock + nsjail
- agent: sched-* runtime
- 写 duration / summary / tail
- jobs.json：定义
- jobs-state.json：运行态
- runs/<job>/<run>.json：历史
- Schedule tool
- /v1/sandbox/schedules
- ScheduledTasksPanel
Module 11
Subagent / Fork：继承上下文的后台分工
AgentTool 会 fork 父上下文，并把子任务追加到稳定的消息前缀之后。
子 agent 继承工具、cwd、workspace 和权限边界，但写入自己的后台输出。
- current_messages
- tool set / cwd
- permission_manager
- 保留父 assistant tool_use
- 填统一占位 tool_result
- 追加子任务指令
- task-outputs/
- AgentToolOutput
- 父 agent 可读取摘要
- 扫描 <fork-boilerplate>
- 子 agent 再调 AgentTool 会返回错误
- tools/builtin/agent_tool.py
- core/fork.py
- core/background.py
Module 12
Hooks / Recovery：完成前校验与错误分流
模型停止调用工具不等于系统一定可以结束。
Stop hooks 做最后校验；恢复器把输出超限、连接错误等问题分到不同处理路径。
- 仅在无 tool_use 时运行
- 发现问题可阻塞完成
- 也可写回消息继续一轮
- 第一阶段放大 max_tokens
- 第二阶段注入 recovery message
- 次数上限防循环
- 未产出 assistant 时可重试
- 已产出则避免重复污染历史
- 走终止错误路径
- 尽量维持同一 session
- 避免重复 assistant message
- 让模型能继续收口
- core/stop_hooks.py
- core/recovery.py
- core/errors.py
Module 13
前端事件协议：文本流之外的运行状态
Web UI 不只显示 assistant 文本，还要显示工具执行、任务进度和暂停状态。
SSE adapter 把内部事件翻译成 OpenAI chunk 与 Ripple 扩展事件。
- StreamEvent
- AssistantMessage
- UserMessage tool_result
- AgentStopEvent
- OpenAI chunk
- tool_call / tool_result
- task_progress / heartbeat
- ChatMessage
- TaskExecutionPanel
- ScheduledTasksPanel
- SettingsModal
- awaiting_user_input
- awaiting_permission
- idle / running
- 追加 session.messages
- 回写 session.model_messages
- 同步 usage 与状态
Module 14
扩展路径：Tool 改能力，Skill 改流程
新外部 API、CLI、文件写入或资源操作，应该落成 Tool。
已有工具的稳定组合、业务 SOP、服务使用规范，应该落成 Skill。
- 实现 Tool 类
- 定义 Pydantic 输入
- 声明 risk / concurrency
- 注册到 server tools
- 创建 SKILL.md
- 写使用时机和步骤
- 限制 allowed tools
- 描述失败降级方式
Runtime Map
一条主线，多个支撑系统
主线负责推进一次请求：入口、会话、消息、循环、工具和权限。
支撑系统负责维持工程可用性：压缩、调度、子代理、恢复、前端事件和扩展边界。
Ripple 的关键设计是让模型只提出动作，让运行时掌握状态、权限和副作用。
Entry → Session → Loop
Tools → Permission
Messages → Streaming → Compact
Scheduler → Fork
Hooks → Recovery
Skills → Extend
SSE → Web UI
User Sandbox