CAS Studio

一个用于设计和模拟复杂自适应系统（CAS）作为基于智能体模型的工作室。您可以定义智能体类型（状态 + 局部规则），将智能体连接成有向、带符号的交互图，为系统提供带有源和汇的开放环境，并针对其运行确定性、带种子、同步的模拟引擎。七个经典的 CAS 属性是一等公民、可观测的特性——每个属性都有显式的模型构造和分析端点，而不仅仅是文档。

纯 Python + numpy 核心。FastAPI + SQLAlchemy + Alembic 用于 REST API 和持久化。Vanilla-JS canvas UI。无重型依赖，无网络调用，无外部数据。

快速开始

./run.sh                      # venv + deps (via uv), alembic upgrade, uvicorn
# HOST=127.0.0.1 PORT=8002 ./run.sh   to override

然后打开 http://localhost:8000/ —— 首次启动时，如果数据库为空，会加载种子演示（并记录审计日志）：市场中的创新扩散 —— 40 个智能体位于小世界环形格上，包括创新者、早期多数和落后者采纳者、两个怀疑者（平衡回路）、两个自适应价格供应商，以及环境中的一个 information 源。两个相邻的种子采纳者会触发 S 曲线采纳级联（平均采纳率 0.12 → 0.95，约 11 步），并在起飞时标记涌现事件；如果只保留一个种子，则会失败。

运行测试：

.venv/bin/python -m pytest tests/ -q

Related MCP server: COMSOL MCP Server

七个 CAS 属性

1. 涌现

宏观模式源于微观交互。每一步引擎都会记录宏观指标：每个状态变量的平均场、总体方差、活跃簇计数（在无向交互图上，主变量 ≥ 0.5 的“活跃”智能体的连通分量）、一个序参量 |2·active_fraction − 1|，以及类似 Moran's I 的邻居相关性。GET /api/runs/{id}/emergence 返回序列以及标记的涌现事件：当宏观指标的逐步骤变化的 z 分数超过 3 且外生输入保持不变（无注入）时的步骤。诚实的警告： 短序列上的 z 分数是一个粗略的检测器——请将事件视为检查的标记，而非证据。

2. 非线性

POST /api/systems/{id}/sensitivity 使用 {"param", "deltas": [...], "steps", "seed"} 重新运行模拟，对 param 施加每个 delta 扰动，并报告响应比率 |Δoutcome/Δparam|（outcome = 主变量的最终平均场）。它标记 nonlinear（比率在不同量级间变化超过 10 倍——超线性区域）、threshold（某些扰动产生响应，其他则无）和 sign_flip。参数寻址：

种子演示在 seed_count:innovator:adopted 处有一个真正的阈值：一个种子失败（采纳率 0.075），两个相邻种子级联（0.95）。

3. 去中心化

智能体仅基于局部信息行动：自身状态、直接入邻居状态的加权平均值，以及通过通量获取的环境变量。规则 DSL 的条件词汇是封闭的——全局状态在构造上不可表示（没有“所有智能体”的聚合，没有全局查找）。自组织通过每次运行序列中类似 Moran's I 的邻居状态相关性来跟踪。

4. 反馈回路

GET /api/systems/{id}/loops 枚举有向交互图的初等环（Johnson 风格 DFS，每个环从其最小节点报告一次；max_len 和 1000 环上限限制枚举并报告 truncated）。每个回路被分类为增强（负耦合数量为偶数）或平衡（奇数），回路增益 = 边权重的乘积。运行摘要包括每个回路的活动度：运行期间流经该回路各边的边通量，其中每步边通量 = |源智能体主变量变化| × |权重|（这是“沿此边传播了多少变化”的启发式，而非物理量）。

5. 适应

智能体类型可以声明 "adaptation": {"target_var", "target_value", "rate"}。每一步智能体向 target_var 添加一个有界偏置；步骤结束后，偏置通过无梯度强化更新：如果步骤使变量更接近 target_value，则保留并放大偏置（×1.25，上限 |1.0|），否则反转并衰减（×−0.5）。给定种子时是确定性的。种子演示中的供应商以这种方式将 price 爬山至 0.7。

6. 开放边界

每个系统都有一个环境：命名的浮点变量加上源/汇——{"var": "information", "inflow": 1.0, "outflow_rate": 0.05} 每步应用 v += inflow − outflow_rate·v。智能体通过守恒通量效应与环境交换：{"flux": "information", "by": 0.02} 将 0.02 单位从环境移动到智能体（同名的状态变量）；环境恰好损失智能体获得的量（由测试验证）。POST /api/runs/{id}/inject 使用 {"step", "var", "amount"} 调度一个外生脉冲：它使用基础运行的系统/种子/步骤重新运行，并在该步骤将脉冲添加到环境，返回新运行以及结果差异。

7. 嵌套层次

一个 System 可以有 parent_id；子系统是完整的系统，拥有自己的智能体、规则和运行。GET /api/systems/{id}/rollup 将每个子系统的最新运行的宏观指标聚合到父系统的报告中（子系统主平均场的智能体数量加权平均值）。

规则 DSL

一个智能体类型有 state（浮点变量字典）和 rules——一个 {"if": <condition>, "then": [<effect>, ...]} 列表。第一个匹配的规则触发；后续规则在该步骤被忽略（"then": [] 的规则是吸收状态守卫）。

条件：

"always"
{"var": "adopted", "op": ">=", "value": 0.5}                 // own state
{"neighbor_mean": {"var": "adopted"}, "op": ">=", "value": 0.35}  // in-neighbors

op ∈ > < >= <= ==。neighbor_mean 是入邻居中携带该变量的加权平均值 Σ wᵢxᵢ / Σ|wᵢ|——因此负权重（怀疑者）邻居会稀释平均值。

效果：

{"set": "adopted", "value": 1.0}        // set own var
{"adjust": "energy", "by": -0.1}        // add to own var
{"flux": "information", "by": 0.02}     // conserve quantity with the environment

单个智能体可以携带 state_override：浮点数，或 {"uniform": [lo, hi]}，后者在每次运行中从运行种子 RNG（np.random.default_rng(seed)）采样一次——这就是使运行种子有意义的原因。相同模型 + 相同种子 → 相同的指标序列（已测试）。

引擎同步步进：每个智能体从同一快照计算其下一个状态——无更新顺序伪影（已用振荡双智能体模型测试）。

REST API

所有变更都记录审计日志（GET /api/audit）。

MCP 集成

CAS Studio 附带一个 MCP（模型上下文协议）stdio 服务器，使 AI 主机（Cursor、Claude Desktop 等）可以直接设计和模拟系统。它通过 HTTP 代理 REST API——使用 CAS_API_URL（默认 http://127.0.0.1:8000）指向任何运行中的实例。

在您主机的 MCP 配置中注册它（参见 mcp-config.example.json）：

{
  "mcpServers": {
    "cas-studio": {
      "command": "/path/to/cas-studio/.venv/bin/python",
      "args": ["-m", "app.mcp_server"],
      "cwd": "/path/to/cas-studio",
      "env": {"CAS_API_URL": "http://127.0.0.1:8000"}
    }
  }
}

暴露的工具（每个代理上述对应的 REST 端点）：list_systems、get_system、list_agent_types、create_agent_type、create_agents（批量）、add_interaction、set_environment_flow、run_simulation、get_run_series、get_emergence_events、list_feedback_loops、run_sensitivity、inject_pulse、get_rollup 和 describe_cas_properties（七属性指南 + 规则 DSL）。

AI 智能体

UI 的 AI Agent 选项卡是一个内置聊天智能体，通过本地 Ollama LLM 驱动工作室——无需 API 密钥，数据不会离开机器。

要求：Ollama 正在运行（ollama serve）且至少有一个模型，例如：

ollama pull qwen3:8b   # the default; supports tool calling and thinking

模型下拉列表列出 Ollama 报告已安装的模型，默认选择 qwen3:8b，然后是任何 gemma3*，然后是 llama3.1:8b，最后是第一个模型（GET /api/agent/models）。使用 OLLAMA_URL（默认 http://127.0.0.1:11434）将智能体指向另一个 Ollama 主机。

POST /api/agent/chat 和 POST /api/agent/generate 作为后台任务运行（HTTP 202 {job_id}），因此慢速的本地 LLM 永远不会挂起请求：轮询 GET /api/agent/jobs/{id} 以获取 {status: pending|running|done|error, progress: [...], result|error} — 进度条目会在循环运行时出现（“round 2: calling run_simulation…”、“attempt 2: validation failed: …”），并且每次失败都会以特定的人类可读错误结束。LLM 调用使用 Ollama 的原生 /api/chat，并设置 think: false（qwen3 的思考模式在 CPU 密集型的 Ollama 上慢 ~10×，并且对工具调用毫无帮助），默认轮次上限为 5。

POST /api/agent/chat {messages, model?, system_id?, temperature?, max_rounds?} 针对 Ollama 的 /api/chat 运行一个工具调用循环：模型选择一个工具，服务器执行它（通过 MCP 服务器使用的同一工具注册表，app/tools.py），追加结果，然后重复 — 直到 max_rounds — 直到模型写出最终答案。作业结果是 {reply, model, tool_trace, rounds}；tool_trace 列出每次调用及其参数和修剪后的结果，UI 将其渲染为每个回复下的可折叠块。思维链（来自 qwen3 的 thinking 块）会从回复中剥离。如果所选模型不支持工具调用，代理会回退到单次无工具答案并附注说明；如果 Ollama 宕机，模型端点会优雅降级，作业以明确的错误结束。

POST /api/agent/generate {description, name?, model?, system_id?, temperature?, max_rounds?} 将纯英语转换为一个可运行的 CAS 模型。LLM（Ollama JSON 模式）起草一个系统规范 — 具有规则 DSL 行为的代理类型、代理数量、交互拓扑（ring_lattice / random / small_world）、按源类型的有符号边权重、具有源/汇的环境变量，以及可选的嵌套子系统 — 在紧凑的 DSL 参考、少样本示例和系统工程设计规则（类型学分解、至少一个增强回路和一个平衡回路、守恒量的开放边界流、系统之系统的嵌套）的指导下。服务器对规范进行严格验证（模式、完整的规则 DSL 验证器、拓扑物化）；失败时，验证错误会反馈给模型，最多 max_rounds 次尝试（默认 3），之后作业以错误结束并附带收集到的消息。成功时，所有内容都通过仓库创建（由 ai-agent 审计记录为 generate_system），结果携带新的系统 ID、摘要和原始规范。同样的能力以 generate_system_from_description 工具的形式暴露给 MCP 主机（它提交作业并等待），并在 UI 中作为 AI Agent 选项卡的 Generate system 模式（带有实时进度）提供。

LLM 设置

AI Agent 选项卡中的齿轮按钮打开设置：temperature（默认 0.2）和 max tool rounds（默认 8）— 作为 temperature / max_rounds 随每个请求发送到 /api/agent/chat 和 /api/agent/generate — 以及活动的 Ollama URL 和 ollama pull 提示。模型、温度和轮次选择会持久化在 localStorage 中。

编辑、示例和引导式用户体验

画布有一个编辑工具栏（选择 / 添加代理 / 连接 / 删除）用于手动构建模型 — 单击节点或边会在详情面板中打开编辑器（名称、状态覆盖、边权重）。Structure 选项卡编辑代理类型（状态模式 + 规则 DSL，带有内联验证错误）和环境（变量 + 源/汇流）。新端点：PUT /api/agents/{id}、PUT /api/interactions/{id}、PUT /api/agent-types/{id}（全部经过验证并审计记录）。Examples 选项卡一键加载精选系统（GET /api/examples、POST /api/examples/{name}）：创新市场级联、捕食者–猎物草地，以及两层供应网络（嵌套层次）— 每个都附有“值得关注”的说明。首次运行的帮助覆盖层、每个选项卡的解释栏和空状态提示引导新用户；涌现面板在没有任何事件触发时显示最强的亚阈值偏移（near_misses 在 GET /api/runs/{id}/emergence 上）。

图形画布

系统图完全可交互：拖动空白区域进行平移，鼠标滚轮进行缩放（以光标为锚点，带有缩放指示器和 Fit 按钮），拖动节点重新排列 — 位置在服务器端持久化（pos_x/pos_y，在拖拽结束时保存），自动布局仅填充没有保存位置的节点。边显示方向箭头，绿色实线 / 红色虚线表示正 / 负耦合，并在承载符号之外的信息时显示权重标签。节点以名称标记

• 运行后的主要状态值；悬停显示包含完整代理状态的工具提示；类型图例位于角落。纯几何/布局辅助函数位于 app/static/graph.js 中，并使用 node --test 进行单元测试（参见 tests/js/）。

布局

app/
  main.py        FastAPI app, REST API, static UI
  tools.py       shared tool registry (names/schemas/execution) for MCP + agent
  mcp_server.py  MCP stdio server fronting the REST API (CAS_API_URL)
  agent.py       in-app AI agent: Ollama tool-calling loop (OLLAMA_URL)
  jobs.py        in-process background jobs for slow LLM work (submit/poll)
  generate.py    natural-language -> validated CAS system spec -> repository
  examples.py    curated one-click example systems
  db.py          engine + session factory (DATABASE_URL, default sqlite:///./cas_studio.db)
  repository.py  SQLAlchemy models + Repository (single DB access point)
  rules.py       rule DSL validation + evaluation (pure functions)
  engine.py      deterministic seeded synchronous simulation engine
  analysis.py    emergence events, loops, sensitivity, Moran's I
  seed.py        the innovation-diffusion demo model
  static/index.html  canvas UI (graph, run controls, chart, loops/sensitivity/inject panels, AI agent)
  static/graph.js    pure canvas helpers (view transform, force layout, edge geometry)
alembic/         schema migrations
tests/           pytest, one file per concern

许可证

MIT — © 2026 Vector Stream Systems LLC.