Ripple
Ripple（涟漪） 是一个基于 复杂自适应系统（Complex Adaptive System, CAS）理论 构建的 Agent-Native 通用人类社会行为预测引擎。 / Ripple is an Agent-Native universal human social behavior prediction engine built on Complex Adaptive System (CAS) theory.
Install / Use
/learn @xyskywalker/RippleREADME
<details> <summary><strong>📑 目录</strong></summary>为什么值得关注
- CAS 原生预测：将传播、反馈、相变等复杂系统机制直接编码进引擎
- 更低成本：以群体模拟替代逐人模拟，相比 OASIS 将 LLM 调用量压缩约 3 个数量级
- 更现实的结论：通过 Tribunal 多专家结构化辩论，主动校准 LLM 常见的乐观偏误
- 项目简介
- 🌊🦞 一键装入 OpenClaw
- 设计理念
- 核心概念：CAS 如何驱动预测
- 星海合议架构
- 运行时引擎
- 系统架构
- 快速开始
- 成本对比
- 社交媒体：第一个领域实现
- PMF 验证：第二个领域实现
- 无限可能
- 工程结构
- 项目状态
- 技术栈
- 文档索引
- 灵感来源：OASIS
- 致谢
- 许可证
🌊 项目简介
Ripple（涟漪） 是一个以 复杂自适应系统（Complex Adaptive System, CAS）理论 为底座构建的 Agent-Native 通用人类社会行为预测引擎。
它不依赖手写传播规则，而是让智能体在上下文中自主判断、相互作用，再由系统观测信号如何扩散、叠加、衰减，并最终触发宏观层面的结构变化。
在 Ripple 中，社会信息传播被视作水面的涟漪——一颗石子投入水中，波纹向外扩散，并在相遇时产生叠加、干涉、共振或抵消。Ripple 将这种物理直觉转化为可计算过程：信号在智能体之间传递能量，进而涌现出非线性放大、反馈环和相变——这也正是本项目名称的由来。
Ripple 目前已实现两个应用场景：
- 📱 社交媒体内容传播预测：输入一条计划发布的内容，系统通过多智能体模拟，输出含置信度的传播预测、系统动力学诊断和可操作的优化建议
- 🎯 PMF（产品市场契合度）验证：输入产品方案与目标市场，系统模拟消费者群体的真实反应，输出多维度 PMF 评分、风险诊断和改进策略
两个场景均引入了合议庭（Tribunal）机制——通过多专家结构化辩论，系统性对抗 LLM 的乐观偏误，确保预测结果的现实性。
项目定位
- 🔬 独立项目，灵感来自 OASIS 的多智能体社交模拟思路
- 🎯 面向实际应用场景（内容创作、产品市场分析、舆论研判），而非学术研究
- 🌐 CAS 内核完全领域无关，社交媒体和 PMF 验证是前两个应用场景
- ⚡ 追求极致的实用性和成本效率——相比 OASIS，LLM 调用量压缩约 3 个数量级
🌊🦞 一键装入 OpenClaw
想把 Ripple 直接接进 OpenClaw，可直接执行：
curl -fsSL https://raw.githubusercontent.com/xyskywalker/Ripple/main/install.sh | bash
如果本机已安装并运行 OpenClaw，脚本会自动安装 ripple skill；否则只完成 Ripple 本体安装。
💡 设计理念
1. 🌊 动力学基础——涟漪
信号犹如涟漪一般在智能体网络中传播能量。每个智能体接收涟漪后，根据自身特征决定响应方式——放大、吸收、变异或忽略——产生的新涟漪继续向外传播。涟漪携带能量并自然衰减，多条涟漪在节点处叠加时可能触发非线性效应，这是系统产生涌现行为的根本机制。
2. 👥 群体模拟范式
一改 OASIS "一人一 Agent" 的个体模拟架构，Ripple 采用群体模拟思路。真实社交网络中，大多数普通用户的行为呈现群体统计特征——Ripple 将具有相似属性的用户聚合为一个群体智能体，用统计分布替代逐人模拟，将 LLM 调用数量降低约 3 个数量级，同时通过 CAS 理论框架保留了涌现行为的捕捉能力。
3. ⭐🌊 独创"星海合议架构"
Ripple 提出独创的 星海合议（Star-Sea-Tribunal）四体智能体架构：
- 🌟 星（Star）智能体：高声量个体（KOL/意见领袖）延续个体模拟，保留个性化决策能力
- 🌊 海（Sea）智能体：普通用户群体采用群体模拟，以统计分布刻画集体行为
- 👁️ 全视者（Omniscient）智能体：上帝视角的全局编排者，统筹传播裁决、环境观测与系统调控
- ⚖️ 合议庭（Tribunal）智能体：多专家评审团，通过结构化辩论校准预测结果
四者协同形成 "个体精准 + 群体高效 + 全局统筹 + 多元校准" 的最优资源分配格局。
4. 🤖 Agent-Native
将决策权完全交给大模型，充分发挥 LLM 的涌现能力。没有硬编码的 CAS 参数、没有预设的传播路径——所有动力学行为由全视者智能体基于全局上下文进行实时推断。系统的智能不来自预定义的规则，而来自 LLM 对复杂系统动态的深度理解。
5. ✨ 极简设计
尽可能简化系统架构：未使用任何三方 Agent 框架，纯 Python + httpx 直连多家 LLM API。35 个核心模块——追求用最少的代码实现最完整的 CAS 模拟能力。
6. 🧩 领域分离与 Skill 架构
核心 CAS 引擎完全领域无关——不知道什么是"点赞"、"流量池"或"PMF 分数"。所有领域知识通过 Skill 包 注入：纯自然语言的领域画像 + 平台/渠道/行业画像 + 角色 Prompt，实现零代码扩展新领域。
7. ⚖️ 合议庭校准机制
引入合议庭（Tribunal）多专家评审架构，通过结构化辩论流程——独立评审 → 交叉质疑 → 修正立场 → 合成裁定——系统性对抗 LLM 的乐观偏误。不同领域的合议庭配置不同的专家角色、评分维度和审查标准，但共享同一套辩论机制。配合反乐观偏误五层防线（行业现实锚点 → 保守性指令 → 现实行为锚定 → 乐观审计 → 行为锚点校准），确保预测结果贴近现实。
8. 🔍 直观可追溯
模拟过程全链路可观测：每一轮 Wave 的全视者裁决、每个智能体的响应决策、涟漪的传播路径和能量变化、合议庭的评审过程和辩论记录——全部增量记录为结构化 JSON。预测结果附带置信度评估，让用户清楚知道模型"多确定"或"多不确定"。
🔬 核心概念：CAS 如何驱动预测
人类社会行为天然具有**复杂自适应系统（CAS）**的核心特征。Ripple 将这些特征编码为引擎的核心原语：
| CAS 特征 | 含义 | Ripple 中的实现 | 现实世界的例子 | |----------|------|----------------|---------------| | 涌现（Emergence） | 宏观行为从微观交互中自发产生 | 全视者观测 + 涌现检测 | 病毒式传播、市场泡沫、社会运动 | | 非线性（Non-linearity） | 微小扰动可能引发巨大效应 | 涟漪能量传播 + 叠加效应 | 一次转发触发级联、技术采纳 S 曲线 | | 正反馈环（Positive Feedback） | 自我强化的增长循环 | 全视者动态调控传播裁决 | 高互动→算法推荐→更多曝光 | | 负反馈环（Negative Feedback） | 自我抑制的制动机制 | 能量衰减 + 注意力竞争 | 内容疲劳、审美饱和、市场饱和 | | 相变（Phase Transition） | 系统在不同宏观状态间突变 | PhaseVector 多维相态跟踪 | 内容传播"引爆点"、舆论翻转 | | 初始条件敏感性 | 初始的微小差异导致截然不同的结果 | 种子用户差异化响应 | 首批用户决定产品扩散路径 | | 适应性（Adaptation） | 智能体根据环境变化调整行为 | Star/Sea 基于上下文的 LLM 决策 | 用户跟随热点、规避负面话题 |
Ripple 核心原语
| 原语 | 定义 | 在引擎中的角色 | |------|------|---------------| | Ripple（涟漪） | 信息传播的基本单元 | 携带内容、能量、情感、传播路径，支持语义变异 | | Event（事件） | 智能体的行为记录 | 记录动作类型、能量转化、响应方式 | | Field（场） | CAS 全局环境状态 | 维护拓扑结构、注意力池、模因池、动态参数 | | PhaseVector（相态向量） | 系统宏观状态的多维表示 | 跟踪热度、情感极化、话题聚散度等维度 | | Meme（模因） | 文化信息传播单元 | 在模因池中演化，影响传播动力学 |
⭐ 星海合议架构
Ripple 的四体智能体架构是理解整个系统的关键：
<p align="center"> <img src="misc/tribunal_architecture_cn.png" alt="星海合议架构" width="600" /> </p>| 智能体 | 映射对象 | 模拟粒度 | LLM 模型 | 职责 | |--------|---------|---------|---------|------| | 👁️ 全视者 | 系统本身 | 全局 | 高智能（Qwen3.5-Plus / Doubao-Seed-2.0-Pro） | 初始化、传播裁决、观测、合议庭主持、最终合成 | | 🌟 星 | KOL / 意见领袖 | 个体 | 高质量（Doubao-Seed-2.0-Lite / DeepSeek-V3.2） | 个性化内容决策、影响力传播 | | 🌊 海 | 普通用户群体 | 群体 | 轻量（Doubao-Seed-2.0-Mini / Qwen3-Flash） | 统计化群体响应、互动行为 | | ⚖️ 合议庭 | 领域专家评审团 | 全局 | 高智能（与全视者同级） | 多维度评审、交叉质疑、反乐观校准 |
合议庭在不同领域的角色配置
合议庭的核心机制（evaluate → challenge → revise → synthesize）跨领域通用，但专家角色和评分维度因领域而异：
| 维度 | 社交媒体合议庭 | PMF 验证合议庭 | |------|--------------|---------------| | 使命 | 传播预测现实性校准 | 多维度产品市场匹配度评分 | | 成员 | 传播动力学专家 · 平台生态专家 · 魔鬼代言人 | 市场分析专家 · 用户代言人 · 魔鬼代言人 | | 评分语义 | 高分 = 预测合理且有强证据 | 高分 = 强 PMF 信号 | | 3 分含义 | 模拟预测符合基准现实 | 产品在该维度表现一般 | | 核心关注 | 传播预测是否过度乐观 | 产品需求是否真实 |
🔄 运行时引擎
全视者驱动的 5-Phase Wave 执行循环，配合可选的 DELIBERATE 合议庭审议阶段：
<p align="center"> <img src="misc/architecture_cn.png" alt="5-Phase 运行时引擎" width="700" /> </p>各 Phase 详解
| Phase | 名称 | 驱动者 | 核心动作 | |-------|------|--------|---------| | Phase 0 | INIT | 全视者 | 解析输入、构建智能体拓扑、初始化 Field、估计模拟总 Wave 数 | | Phase 1 | SEED | 全视者 | 创建种子 Ripple（涟漪）、确定初始能量和传播目标 | | Phase 2 | RIPPLE | Star & Sea | 被激活的智能体接收涟漪并决策响应（放大/吸收/变异/忽略） | | Phase 3 | OBSERVE | 全视者 | 聚合宏观指标、观测系统状态、判定相态变化 | | Phase 4 | FEEDBACK & RECORD | 引擎 | 记录 Wave 数据、更新 Field 状态、判定终止条件或进入下一轮 | | Extra | DELIBERATE | 全视者 + 合议庭 | 多专家评审模拟结果、结构化辩论、反乐观校准、合成最终裁定 |
🏗️ 系统架构
<p align="center"> <img src="misc/layered_architecture_cn.png" alt="系统架构" width="700" /> </p>🚀 快速开始
推荐：Docker 启动方式（仅需 Docker）
无需本地 Python/pip 依赖。服务以 HTTP+SSE 方式对外提供接口。
RIPPLE_API_TOKEN 为可选参数：
- 未设置、设为空字符串、或仅包含空白字符时：所有服务接口均不做身份验证
- 设为非空值时：所有服务接口均要求
Authorization: Bearer <token>
deploy/docker/docker-compose.yml 的默认行为也已改为不启用鉴权；只有显式设置 RIPPLE_API_TOKEN 时才开启鉴权。
推荐始终使用单一宿主机目录挂载：先执行 mkdir -p data/ripple-service/ripple_outputs，再将本地 data/ripple-service/ 挂载到容器 /data。服务会把 JSON / Markdown 产物写到容器 /data/ripple_outputs/，宿主机对应目录即 data/ripple-service/ripple_outputs/。
POST /v1/simulations/{job_id}/report 会优先复用创建任务时请求体中的 llm_config，只有当请求里未提供时才回退到容器启动时的默认 llm_config.yaml，因此客户端不需要进入 Docker 读取配置文件。
方式1：启动时传入默认 LLM 参数（显式开启鉴权）
启动后，POST /v1/simulations 可不再传 llm_config。
A) API Key 明文写死
docker run -d --name ripple-service \
-p 127.0.0.1:8080:8080 \
-e RIPPLE_API_TOKEN=your-service-token \
-e RIPPLE_LLM_MODEL_PLATFORM=openai \
-e RIPPLE_LLM_MODEL_NAME=gpt-5.2 \
-e RIPPLE_LLM_API_KEY=sk-xxx \
-e RIPPLE_LLM_URL=https://api.openai.com/v1 \
-e RIPPLE_LLM_API_MODE=chat_completions \
-v "$PWD/data/ripple-service:/data" \
xyplusxy/ripple:v0.2.1
B) 引用环境变量
export OPENAI_API_KEY=sk-xxx
docker run -d --name ripple-service \
-p 127.0.0.1:8080:8080 \
-e RIPPLE_API_TOKEN=your-service-token \
-e RIPPLE_LLM_MODEL_PLATFORM=openai \
-e RIPPLE_LLM_MODEL_NAME=gpt-5.2 \
-e RIPPLE_LLM_API_KEY="$OPENAI_API_KEY" \
-e RIPPLE_LLM_URL=https://api.openai.com/v1 \
-e RIPPLE_LLM_API_MODE=chat_completions \
-v "$PWD/data/ripple-service:/data" \
xyplusxy/ripple:v0.2.1
方式1：HTTP+SSE 调用示例（开启鉴权）
BASE_URL=http://127.0.0.1:8080
RIPPLE_API_TOKEN=your-service-token
# 1) 创建任务
curl -sS -X POST "$BASE_URL/v1/simulations" \
-H "Authorization: Bearer $RIPPLE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"skill":"pmf-validation",
"event":{"name":"demo","description":"startup default llm"}
}'
# 2) 订阅事件（SSE）
curl -N "$BASE_URL/v1/simulations/<JOB_ID>/events" \
-H "Authorization: Bearer $RIPPLE_API_TOKEN"
# 3) 查询状态
curl -sS "$BASE_URL/v1/simulations/<JOB_ID>" \
-H "Authorization: Bearer $RIPPLE_API_TOKEN"
# 4) 生成模拟后解读报告
curl -sS -X POST "$BASE_URL/v1/simulations/<JOB_ID>/report" \
-H "Authorization: Bearer $RIPPLE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"rounds":[
{"label":"summary","system_prompt":"请用简体中文总结本次模拟结果。","extra_user_context":""}
]
}'
# 5) 宿主机直接查看产物
ls data/ripple-service/ripple_outputs
方式2：启动时不传 LLM 参数（每次调用时传 llm_config，默认不鉴权）
docker run -d --name ripple-service \
-p 127.0.0.1:8080:8080 \
-v "$PWD/data/ripple-service:/data" \
xyplusxy/ripple:v0.2.1
如果你希望这一模式也启用鉴权，只需额外传入
-e RIPPLE_API_TOKEN=your-service-token。
方式2：HTTP+SSE 调用示例（不鉴权）
BASE_URL=http://127.0.0.1:8080
# 1) 创建任务（请求内传 llm_config）
curl -sS -X POST "$BASE_URL/v1/simulations" \
-H "Content-Type: application/json" \
-d '{
"skill
