Symbiont/README.zh-cn.md at main · ThirdKeyAI/Symbiont

面向生产环境的策略治理智能体运行时。 同一个智能体。安全的运行时。

你看到的是： 一个真实模型（claude-haiku-4.5）请求列出智能体集群。一条 Cedar forbid 规则在每次重试时都拒绝该调用 —— 无需更改代码，只需策略。用一条命令复现 ↓ · ▶ 完整演示

Symbiont 是一个 Rust 原生运行时，用于在显式策略、身份和审计控制下执行 AI 智能体和工具。

大多数智能体框架侧重于编排。Symbiont 侧重于智能体在真实环境中运行时面临的真实风险：不可信工具、敏感数据、审批边界、审计要求和可重复的执行控制。

为什么选择 Symbiont

AI 智能体易于演示，却难以信任。

一旦智能体可以调用工具、访问文件、发送消息或调用外部服务，你需要的不仅仅是提示词和胶水代码。你需要：

策略执行 控制智能体可以做什么 — 内置 DSL 和 Cedar 授权
工具验证 使执行不再是盲目信任 — SchemaPin 对 MCP 工具的密码学验证
工具契约 规范工具的执行方式 — ToolClad 声明式参数校验、作用域强制和注入防护
智能体身份 使你了解谁在执行操作 — AgentPin 域锚定 ES256 身份
沙箱隔离 用于高风险工作负载 — 可按智能体选择 Docker、gVisor (runsc) 或 Firecracker microVM
审计追踪 记录发生了什么以及原因 — 密码学防篡改日志
审批门控 用于敏感操作 — 策略要求时需经人工审批后方可执行

Symbiont 正是为这一层而构建的。

Open Agent Trust Stack (OATS) — 参考实现

Symbiont 是 Open Agent Trust Stack (OATS) 的参考实现 —— 一份开放规范（CC BY 4.0），通过结构性强制而非事后拦截来保障 AI 智能体执行的安全（"定义允许的行为，使其余一切在结构上无法表达"）。OATS 规范根植于 Symbiont 的生产运维经验，Symbiont 的设计也直接对应 OATS 的各层：

OATS 层级	Symbiont 映射
Layer 1 — ORGA Loop（类型状态强制的 Observe-Reason-Gate-Act）	`crates/runtime/src/reasoning/` —— 类型状态强制的阶段；策略门在编译期不可跳过。参见 Wanger 2026 / DOI 10.5281/zenodo.19896446。
Layer 2 — Tool Contracts	ToolClad 声明式 `.clad.toml` 清单 + `crates/runtime/src/toolclad/` 中的 `agent_summary` 类型状态屏障。参见 Wanger 2026 / DOI 10.5281/zenodo.19957596。
Layer 3 — Identity	面向 MCP 工具的 SchemaPin + AgentPin ES256 域锚定智能体身份。
Layer 4 — Policy Engine	Cedar 策略门（`crates/runtime/src/reasoning/cedar_gate.rs`）+ 用于智能体间调用的 `CommunicationPolicyGate`；两者自 v1.14.0 起默认失败即关闭。
Layer 5 — Audit Journal	推理循环中的哈希链接、Ed25519 签名的 `BufferedJournal`；`crates/runtime/src/logging.rs` 中加密的模型 I/O 日志。

Symbiont 符合 OATS Extended（C1–C7 + E1–E8）。为该规范提供依据的结构性强制运行时实证比较见 Wanger 2026 / DOI 10.5281/zenodo.20043247。

快速开始

观看策略门拒绝工具调用 —— 一条命令，无需配置

一条 Cedar forbid 阻止特权工具，而安全工具则放行。直接对已发布镜像复制粘贴运行（无需克隆、无需构建）：

docker run --rm --entrypoint sh ghcr.io/thirdkeyai/symbi:latest -c '
mkdir -p /tmp/p && cat > /tmp/p/policy.cedar <<EOF
forbid(principal, action == Symbi::Action::"tool_call::list_agents",   resource);
permit(principal, action == Symbi::Action::"tool_call::system_health", resource);
EOF
echo "{\"tool_name\":\"list_agents\"}"   | symbi policy evaluate --stdin --policies /tmp/p --json
echo "{\"tool_name\":\"system_health\"}" | symbi policy evaluate --stdin --policies /tmp/p --json'

{"decision":"deny","reason":"deny policies matched: policy_0","tool":"list_agents", ...}
{"decision":"allow","reason":"allow policies matched: policy_1","tool":"system_health", ...}

这正是运行时接入实时推理循环的同一个 Cedar 策略门 —— 与上方演示中展示的拒绝完全一致。

安装 CLI

# Linux / macOS — installs the `symbi` binary to /usr/local/bin
curl -fsSL https://symbiont.dev/install.sh | bash
symbi --help

安装程序会为你的平台获取预构建的发布二进制文件。可用 bash -s -- --version v1.15.2 固定版本，或用 --dir 更改目标路径。更喜欢 Docker 或从源代码构建？两者都在下方。

前提条件

Docker（推荐）或 Rust 1.82+

搭建并运行项目（Docker，约 60 秒）

# 1. Create the project in the current directory.
#    Generates symbiont.toml, agents/, policies/, docker-compose.yml, and
#    a .env with a freshly generated SYMBIONT_MASTER_KEY.
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile assistant --no-interact --dir /workspace

# 2. Start the runtime. Reads .env automatically.
docker compose up

就这样 —— 运行时 API 位于 http://localhost:8080，HTTP 输入位于 http://localhost:8081。使用 symbi init --catalog list（或对应的 Docker 命令）浏览预构建的智能体。

其他 Docker 用法

# Ad-hoc runtime without a project (ephemeral, no master key)
docker run --rm -p 8080:8080 -p 8081:8081 ghcr.io/thirdkeyai/symbi:latest up

# MCP server only
docker run --rm -p 8080:8080 ghcr.io/thirdkeyai/symbi:latest mcp

# Parse an agent definition (`.symbi`; legacy `.dsl` also accepted)
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  dsl -f /workspace/agent.symbi

从源代码构建

cargo build --release
./target/release/symbi --help

# Scaffold a project locally, then start the runtime
./target/release/symbi init --profile assistant --no-interact
./target/release/symbi up

对于生产部署，请在启用不可信工具执行之前查阅 SECURITY.md 和部署指南。

工作原理

Symbiont 将智能体意图与执行权限分离：

智能体提出操作请求，通过推理循环（Observe-Reason-Gate-Act）
运行时评估每个操作的策略、身份和信任检查
策略决定 — 允许的操作被执行；拒绝的操作被阻止或路由到审批流程
一切皆被记录 — 每个决策都有防篡改审计追踪

模型输出永远不会被视为执行权限。运行时控制实际发生的操作。

示例：不可信工具被策略阻止

智能体尝试调用一个未验证的 MCP 工具。运行时：

检查 SchemaPin 验证状态 — 工具签名缺失或无效
评估 Cedar 策略 — forbid(action == Action::"tool_call") when { !resource.verified }
阻止执行并记录拒绝详情的完整上下文
可选地路由给操作员进行人工审批

无需更改代码。策略治理执行。

DSL 示例

agent secure_analyst(input: DataSet) -> Result {
    policy access_control {
        allow: read(input) if input.verified == true
        deny: send_email without approval
        audit: all_operations
    }

    with memory = "persistent", requires = "approval" {
        result = analyze(input);
        return result;
    }
}

参见 DSL 指南了解完整语法，包括 metadata、schedule、webhook 和 channel 块。

文件扩展名： Symbiont 智能体定义使用 .symbi 作为其规范扩展名（例如 agents/assistant.symbi）。出于向后兼容考虑，旧的 .dsl 扩展名将无限期继续被解析，但通过 symbi init 搭建的新项目以及本仓库中的所有示例均使用 .symbi。

核心能力

能力	说明
策略引擎	对智能体操作、工具调用和资源访问的细粒度 Cedar 授权
工具验证	执行前使用 SchemaPin 对 MCP 工具 schema 进行密码学验证
工具契约	ToolClad 声明式契约，提供参数校验、作用域强制和 Cedar 策略生成
智能体身份	AgentPin 面向智能体和计划任务的域锚定 ES256 身份
推理循环	类型状态强制的 Observe-Reason-Gate-Act 循环，带策略门和熔断器
沙箱隔离	Docker、gVisor (`runsc`) 或 Firecracker microVM —— 通过 DSL `with { sandbox = ... }` 块按智能体选择
审计日志	防篡改日志，为每个策略决策提供结构化记录
密钥管理	Vault/OpenBao 集成，AES-256-GCM 加密存储，按智能体命名空间隔离
MCP 集成	原生 Model Context Protocol 支持，带治理工具访问

其他能力：工具/skill 内容威胁扫描（40 条规则，10 个攻击类别）、cron 调度、持久化智能体记忆、混合 RAG 搜索（LanceDB/Qdrant）、webhook 验证、交付路由、OTLP 遥测、HTTP 安全加固，以及面向 Claude Code 和 Gemini CLI 的治理插件。详见完整文档。

代表性基准测试可在 benchmark harness 和阈值测试中查看。

安全模型

Symbiont 围绕一个简单原则设计：模型输出永远不应被信任为执行权限。

操作通过运行时控制流转：

零信任 — 所有智能体输入默认不可信
策略检查 — 每次工具调用和资源访问前进行 Cedar 授权
工具验证 — SchemaPin 对工具 schema 的密码学验证
沙箱边界 — 按智能体选择隔离级别：Docker（默认）、gVisor（runsc 系统调用过滤器）或 Firecracker（microVM）
操作员审批 — 敏感操作的人工审批门
密钥控制 — Vault/OpenBao 后端、加密本地存储、智能体命名空间
审计日志 — 每个决策的密码学防篡改记录

如果你正在执行不可信代码或高风险工具，请不要仅依赖弱本地执行模型作为唯一屏障。参见 SECURITY.md 和安全模型文档。

工作区

Crate	说明
`symbi`	统一 CLI 二进制文件
`symbi-runtime`	核心智能体运行时与执行引擎
`symbi-dsl`	DSL 解析器与求值器
`symbi-channel-adapter`	Slack/Teams/Mattermost 适配器
`repl-core` / `repl-proto` / `repl-cli`	交互式 REPL 和 JSON-RPC 服务器
`repl-lsp`	Language Server Protocol 支持
`symbi-shell`	用于编写、编排和远程附加的交互式 TUI（Beta）
`symbi-a2ui`	管理仪表板（Lit/TypeScript，alpha 阶段）

治理插件：symbi-claude-code | symbi-gemini-cli

文档

如果你正在评估 Symbiont 用于生产环境，请从安全模型和入门指南文档开始。

SDK

用于从应用程序集成 Symbiont 运行时的官方客户端 SDK：

语言	包	代码仓库
JavaScript/TypeScript	symbiont-sdk-js	GitHub
Python	symbiont-sdk	GitHub

生产建议： JS 和 Python SDK 是面向应用集成与原型开发的 HTTP 客户端。对于生产环境的智能体工作负载，我们建议直接基于 Rust 实现 构建，以充分利用 Symbiont 完整的类型状态驱动安全保证 —— 能力授权、策略执行和生命周期不变量都在编译期而非运行期得到强制。动态语言客户端只能在请求越过运行时边界之后才能验证这些属性。

许可证

社区版（Apache 2.0）：核心运行时、DSL、策略引擎、工具验证、沙箱隔离、智能体记忆、调度、MCP 集成、RAG、审计日志，以及所有 CLI/REPL 工具。
企业版（商业许可证）：合规审计导出、AI 驱动的工具审查、加密多智能体协作、监控仪表板和专属支持。（三种沙箱后端 —— Docker、gVisor 和 Firecracker —— 均为 OSS。）

联系 ThirdKey 获取企业许可。

Navigation Menu

Uh oh!

为什么选择 Symbiont

Open Agent Trust Stack (OATS) — 参考实现

快速开始

观看策略门拒绝工具调用 —— 一条命令，无需配置

安装 CLI

前提条件

搭建并运行项目（Docker，约 60 秒）

其他 Docker 用法

从源代码构建

工作原理

示例：不可信工具被策略阻止

DSL 示例

核心能力

安全模型

工作区

文档

SDK

许可证

Uh oh!

FilesExpand file tree

README.zh-cn.md

Latest commit

History

README.zh-cn.md

File metadata and controls

为什么选择 Symbiont

Open Agent Trust Stack (OATS) — 参考实现

快速开始

观看策略门拒绝工具调用 —— 一条命令，无需配置

安装 CLI

前提条件

搭建并运行项目（Docker，约 60 秒）

其他 Docker 用法

从源代码构建

工作原理

示例：不可信工具被策略阻止

DSL 示例

核心能力

安全模型

工作区

文档

SDK

许可证