Symbiont REPL 指南¶

分支执行状态： 异步内置函数保留发起调用方的身份。桥接层会冻结其项目根目录，默认的 reason()/tool_call() 调用需要受保护的运行日志，并返回公开的审计引用。直接推理调用同样需要日志；:audit 会列出它们的公开引用。函数和 behavior 声明会在多次输入之间保留，运行中的 behavior 会保留其辅助函数的快照。旧版 REPL 语法并未实现按代理进行的规范沙箱选择。显式声明的不受支持的层级、沙箱、资源和执行策略要求现在会导致注册失败。当前覆盖范围参见 DSL 调用上下文和分支指南。

其他语言¶

在寻找交互式 TUI 吗？ symbi shell（Beta）包装了本指南所涵盖的同一个 repl_core 引擎，并在其上叠加了 LLM 编排器、完整的命令目录（/spawn、/run、/chain 等）以及远程附加功能。当您需要可脚本化的 JSON-RPC 接口用于 IDE 集成时，使用 REPL；当您希望在同一个运行时上进行对话式创作时，使用 shell。

功能特性¶

交互式 DSL 求值：实时执行 Symbiont DSL 代码
智能体生命周期管理：创建、启动、停止、暂停、恢复和销毁智能体
执行监控：通过统计信息和追踪进行实时执行监控
策略执行：内置策略检查和能力门控
会话管理：快照和恢复 REPL 会话
JSON-RPC 协议：通过 stdio 上的 JSON-RPC 进行程序化访问
LSP 支持：用于 IDE 集成的语言服务器协议

入门指南¶

启动 REPL¶

# Interactive REPL mode
symbi repl

# JSON-RPC server mode over stdio (for IDE integration)
symbi repl --stdio

注意： --config 标志尚不支持。配置从默认的 symbiont.toml 位置读取。自定义配置支持计划在未来版本中提供。

基本使用¶

每条声明在一行内输入：

agent Greeter {}
function greet(value: string) { return upper(value) }
behavior Welcome { steps { return greet(args) } }
:agents
:agent start <id>
:agent execute <id> Welcome hello

请把 <id> 替换为 Greeter 输出的 UUID。最后一条命令返回 HELLO。声明和启动并不会执行 behavior。可选的命令参数会作为一个名为 args 的字符串传入。定义会被保留；局部变量和参数不会带入下一次调用。模块注册失败不会替换已有的定义。运行时错误仍然可见，客户端可以继续接受下一条命令。print() 的诊断信息输出到 stderr，与结构化响应相互独立。

symbi run 使用的规范 agent name(...) { with ... } 语言走的是另一条解析路径。旧版 REPL 的安全层级和沙箱模式并不是它的执行设置。注册会在发布任何定义之前，拒绝显式的旧版 tier/sandbox 模式、非空的资源声明和执行策略。重复的约束块和能力列表同样会导致解析失败。仅声明能力的声明保留原有检查。工具作用使用项目边界和受治理的派发器；若未配置允许的门控，工具请求会被拒绝。直接 LLM 调用、组合调用和模式调用都要求每次提供者调用都有签名日志。它们已有的结果类型保持不变；公开引用请使用 :audit 查看。通信需要已配置的门控和已注册的接收方。send_to 确认的是持久化的启动，其终态日志记录后续的完成情况。race 返回第一个成功结果并取消其余调用。这些控制并不构成规范的源码选择，也不构成汇总的推理预算。

在完成工作区构建后，可用以下命令复现 RPC 与终端冒烟测试：

python3 scripts/test-repl-session.py --binary target/debug/repl-cli --report /tmp/repl-session.json

REPL 命令¶

智能体管理¶

命令	描述
`:agents`	列出所有智能体
`:audit`	列出最近的直接推理审计引用以及被省略的引用数量
`:agent list`	列出所有智能体
`:agent start <id>`	启动智能体
`:agent stop <id>`	停止智能体
`:agent pause <id>`	暂停智能体
`:agent resume <id>`	恢复已暂停的智能体
`:agent destroy <id>`	销毁智能体
`:agent execute <id> <behavior> [args]`	执行智能体行为
`:agent debug <id>`	显示智能体的调试信息

监控命令¶

命令	描述
`:monitor stats`	显示执行统计信息
`:monitor traces [limit]`	显示执行追踪
`:monitor report`	显示详细执行报告
`:monitor clear`	清除监控数据

内存命令¶

命令	描述
`:memory inspect <agent-id>`	查看智能体的内存状态
`:memory compact <agent-id>`	压缩智能体的内存存储
`:memory purge <agent-id>`	清除智能体的所有内存

Webhook 命令¶

命令	描述
`:webhook list`	列出已配置的 webhook
`:webhook add`	添加新的 webhook
`:webhook remove`	移除 webhook
`:webhook test`	测试 webhook
`:webhook logs`	显示 webhook 日志

录制命令¶

命令	描述
`:record on <file>`	开始将会话录制到文件
`:record off`	停止录制会话

会话命令¶

命令	描述
`:snapshot`	创建会话快照
`:clear`	清除会话
`:help` 或 `:h`	显示帮助信息
`:version`	显示版本信息

DSL 功能¶

智能体定义¶

metadata {
  version = "2.1.0"
  description = "Analyzes datasets with privacy protection"
}

agent data_analyzer(data: DataSet, options: AnalysisOptions) -> AnalysisResults {
  capabilities = ["data_read", "analysis"]

  policy privacy {
    allow: read(data) if true
    deny: write(any)
  }

  with memory = "ephemeral", sandbox = "tier1" {
    return analyze(data, options);
  }
}

智能体的行为存在于该智能体的 with 块中（以及 function 定义中）—— 没有单独的 behavior 构造。策略规则（allow / deny / require / audit）用于限制智能体可执行的操作。完整语法请参见 DSL 指南和 DSL 规范。

内置函数¶

函数	描述	示例
`print(...)`	将值输出到控制台	`print("Hello", name)`
`len(value)`	获取字符串、列表或映射的长度	`len("hello")` -> `5`
`upper(string)`	将字符串转换为大写	`upper("hello")` -> `"HELLO"`
`lower(string)`	将字符串转换为小写	`lower("HELLO")` -> `"hello"`
`format(template, ...)`	使用参数格式化字符串	`format("Hello, {}!", name)`

计划的内置函数： 高级 I/O 函数如 read_file()、read_csv()、write_results()、analyze() 和 transform_data() 尚未实现。这些计划在未来版本中提供。

数据类型¶

# Basic types
let name = "Alice"          # String
let age = 30               # Integer
let height = 5.8           # Number
let active = true          # Boolean
let empty = null           # Null

# Collections
let items = [1, 2, 3]      # List
let config = {             # Map
  "host": "localhost",
  "port": 8080
}

# Time and size units
let timeout = 30s          # Duration
let max_size = 100MB       # Size

架构¶

组件¶

symbi repl
├── repl-cli/          # CLI interface and JSON-RPC server
├── repl-core/         # Core REPL engine and evaluator
├── repl-proto/        # JSON-RPC protocol definitions
└── repl-lsp/          # Language Server Protocol implementation

核心组件¶

DslEvaluator：通过运行时集成执行 DSL 程序
ReplEngine：协调求值和命令处理
ExecutionMonitor：跟踪执行统计信息和追踪
RuntimeBridge：与 Symbiont 运行时集成进行策略执行
SessionManager：处理快照和会话状态

JSON-RPC 协议¶

REPL 支持 JSON-RPC 2.0 进行程序化访问：

// Evaluate DSL code
{
  "jsonrpc": "2.0",
  "method": "evaluate",
  "params": {"input": "let x = 42"},
  "id": 1
}

// Response
{
  "jsonrpc": "2.0",
  "result": {"value": "42", "type": "integer"},
  "id": 1
}

安全与策略执行¶

能力检查¶

REPL 执行智能体安全块中定义的能力要求：

agent SecureAgent {
  name: "Secure Agent"
  security {
    capabilities: ["filesystem", "network"]
  }
}

behavior ReadFile {
  input { path: string }
  output { content: string }
  steps {
    # This will check if agent has "filesystem" capability
    require capability("filesystem")
    # NOTE: read_file() is a planned built-in function (not yet implemented).
    # This example illustrates how capability checking works.
    let content = read_file(path)
    return content
  }
}

策略集成¶

REPL 与 Symbiont 策略引擎集成，以执行访问控制和审计要求。

调试与监控¶

执行追踪¶

:monitor traces 10

Recent Execution Traces:
  14:32:15.123 - AgentCreated [Agent: abc-123] (2ms)
  14:32:15.125 - AgentStarted [Agent: abc-123] (1ms)
  14:32:15.130 - BehaviorExecuted [Agent: abc-123] (5ms)
  14:32:15.135 - AgentPaused [Agent: abc-123]

统计信息¶

:monitor stats

Execution Monitor Statistics:
  Total Executions: 42
  Successful: 38
  Failed: 4
  Success Rate: 90.5%
  Average Duration: 12.3ms
  Total Duration: 516ms
  Active Executions: 2

智能体调试¶

:agent debug abc-123

Agent Debug Information:
  ID: abc-123-def-456
  Name: Data Analyzer
  Version: 2.1.0
  State: Running
  Created: 2024-01-15 14:30:00 UTC
  Description: Analyzes datasets with privacy protection
  Author: data-team@company.com
  Available Functions/Behaviors: 5
  Required Capabilities: 2
    - data_read
    - analysis
  Resource Configuration:
    Memory: 512MB
    CPU: 2
    Storage: 1GB

IDE 集成¶

语言服务器协议¶

REPL 通过 repl-lsp crate 为 IDE 集成提供 LSP 支持。LSP 服务器与 REPL 本身是分开启动的：

# The LSP server is provided by the repl-lsp crate and launched
# by your editor's LSP client configuration (not via symbi repl flags).

注意： symbi repl 不支持 --lsp 标志。LSP 在 repl-lsp crate 中实现，应通过编辑器的 LSP 设置进行配置。

支持的功能¶

语法高亮
错误诊断
文本同步

计划功能（尚未实现）： - 代码补全 - 悬停信息 - 转到定义 - 符号搜索

最佳实践¶

开发工作流¶

从简单表达式开始：测试基本的 DSL 构造
增量定义智能体：从最小的智能体定义开始
单独测试行为：在集成之前定义和测试行为
使用监控：利用执行监控进行调试
创建快照：保存重要的会话状态

性能建议¶

定期使用 :monitor clear 重置监控数据
使用 :monitor traces <limit> 限制追踪历史
销毁未使用的智能体以释放资源
对复杂会话状态使用快照

安全注意事项¶

始终为智能体定义适当的能力
在开发中测试策略执行
对不受信任的代码使用沙箱模式
监控执行追踪以发现安全事件

故障排除¶

常见问题¶

智能体创建失败

Error: Missing capability: filesystem

解决方案：在智能体安全块中添加所需的能力

执行超时

Error: Maximum execution depth exceeded

解决方案：检查行为逻辑中的无限递归

策略违规

Error: Policy violation: data access denied

解决方案：验证智能体是否具有适当的权限

调试命令¶

# Check agent state
:agent debug <agent-id>

# View execution traces
:monitor traces 50

# Check system statistics
:monitor stats

# Create debug snapshot
:snapshot

示例¶

简单智能体¶

agent Calculator {
  name: "Basic Calculator"
  version: "1.0.0"
}

behavior Add {
  input { a: number, b: number }
  output { result: number }
  steps {
    return a + b
  }
}

# Test the behavior
let result = Add(5, 3)
print("5 + 3 =", result)

数据处理智能体¶

agent DataProcessor {
  name: "Data Processing Agent"
  version: "1.0.0"

  security {
    capabilities: ["data_read", "data_write"]
  }

}

behavior ProcessCsv {
  input { file_path: string }
  output { summary: ProcessingSummary }

  steps {
    require capability("data_read")

    # NOTE: read_csv(), transform_data(), and write_results() are planned
    # built-in functions (not yet implemented). This example illustrates
    # the intended pattern for data processing behaviors.
    let data = read_csv(file_path)
    let processed = transform_data(data)

    require capability("data_write")
    write_results(processed)

    return {
      "rows_processed": len(data),
      "status": "completed"
    }
  }
}

另请参阅¶

DSL 指南 - 完整的 DSL 语言参考
运行时架构 - 系统架构概览
安全模型 - 安全实现细节
API 参考 - 完整的 API 文档