项目定位与整体架构

Symbio 旨在解决多智能体系统中"能力描述分散、调用方式不统一、可观测性弱"的常见痛点。框架通过统一的 能力账本（Capability Ledger） 对外暴露所有可被智能体或外部系统调用的能力，并提供 CLI 作为人与系统交互的最简入口。资料来源：README.md:1-40。

整体设计遵循"声明式能力 + 命令式编排"的思路：

• 声明式：每个能力在 src/symbio/capabilities.py 中以结构化方式注册，包含名称、输入输出契约、所需依赖等元数据。
• 命令式：CLI 通过解析用户命令，匹配到对应能力并触发执行链路，输出结构化结果。

核心能力账本（Capabilities）

能力账本是 Symbio 体系的核心数据结构，所有智能体的"技能"都以条目（entry）的形式登记在账本中。资料来源：src/symbio/capabilities.py:1-80。

账本的核心职责包括：

1. 能力注册：提供装饰器或显式注册接口，将函数、工具或智能体方法登记为可调用能力。
2. 元数据维护：为每个能力保存描述、参数 schema、版本号、所属域（domain）等信息，便于检索与展示。
3. 依赖解析：根据能力声明的依赖关系，构建可执行的调用链路 DAG，避免循环依赖。
4. 暴露给 CLI/UI：账本作为单一事实来源（Single Source of Truth），供 cli.py、前端或上层 Agent 直接查询。资料来源：src/symbio/capabilities.py:80-160。

下表展示了一个典型账本条目的字段约定，便于读者快速理解数据结构：

CLI 快速上手

CLI 是新用户接触 Symbio 的最低门槛入口。src/symbio/cli.py 实现了基于子命令的交互模式，覆盖能力查询、调用与诊断三类常见任务。资料来源：src/symbio/cli.py:1-60。

安装与初始化

git clone https://github.com/854875058/Symbio
cd Symbio
pip install -e .

安装完成后，可通过 symbio --help 查看全部子命令，CLI 会自动读取能力账本并动态生成帮助信息，无需手动维护命令列表。资料来源：src/symbio/cli.py:60-120。

常用命令示例

• symbio capabilities list：列出账本中已注册的全部能力，支持按 domain 过滤。
• symbio capabilities show <name>：查看某个能力的详细 schema、依赖与示例调用。
• symbio run <capability> --input ...：直接以 JSON 或 --key value 形式传入参数，触发能力执行。
• symbio doctor：运行环境自检，包括依赖完整性、账本一致性等。资料来源：README_zh.md:1-60。

功能特性与路线图

仓库通过两份文档持续维护功能边界与开发计划：

• docs/features.md 描述当前已发布能力的语义、调用方式与典型场景，是面向用户的功能手册。资料来源：docs/features.md:1-80。
• docs/feature-checklist.md 以勾选清单形式记录短期与中长期计划，区分"已完成 / 进行中 / 规划中"三态，便于追踪。资料来源：docs/feature-checklist.md:1-60。

flowchart LR
    A[README 定位] --> B[capabilities.py<br/>能力账本]
    B --> C[cli.py<br/>命令行入口]
    B --> D[features.md<br/>功能手册]
    B --> E[feature-checklist.md<br/>路线图]
    C --> F[用户 / 智能体调用]
    D --> F

总结

对初次接触 Symbio 的开发者，建议按"先读 README 建立心智模型 → 浏览能力账本理解可调用面 → 用 CLI 做最小可用验证 → 参考 features/feature-checklist 规划扩展"的顺序推进。能力账本是整个框架的中枢抽象，所有上层能力（CLI、Agent、UI）都通过它解耦，从而保证新增能力时只需修改 capabilities.py 即可被全链路感知。资料来源：README.md:1-40、src/symbio/capabilities.py:1-80、src/symbio/cli.py:1-60。

四层架构与目录模块划分

Symbio（共生）是一款 AI Infra 级多 Agent 协同框架，内置 33 项核心能力，包括动态 DAG、本体化记忆、防过早完成、数据飞轮、神经符号安全、OpenTelemetry 可观测、HITL 人类介入、MCP 原生支持、语义缓存、PromptOps、边缘计算及隐私计算，面向下一代多 Agent 编排场景。

概览与定位

DAG 调度编排与执行引擎是 Symbio 项目的核心执行层，负责将高层业务意图转化为可执行的有向无环图（DAG），并以受控、可观察、可回放的方式驱动各节点按依赖关系运行。引擎以"规划—审查—执行—运行时上下文"为四段式分层，将策略声明、计划生成、计划校验与节点调度解耦，使上层应用（Agent、Tool、Workflow）能够以统一语义接入调度器。在运行时，引擎既承担 DAG 拓扑解析、依赖排序、并发分区等"调度"职责，也承担节点调用、状态推进、产物落盘等"执行"职责，因此本模块既是编排器，也是执行器。资料来源：src/symbio/core/dag_orchestrator.py:1-1、src/symbio/core/dag_engine.py:1-1。

核心组件

• dag_orchestrator.py：作为编排主控，向上暴露统一的运行入口；它接收 DAG 描述、注入策略，并在各组件之间传递控制流。资料来源：src/symbio/core/dag_orchestrator.py:1-1`。
• dag_engine.py：执行内核，负责按计划驱动节点调度、状态推进与产物回传，是执行语义的具体实现者。资料来源：src/symbio/core/dag_engine.py:1-1`。
• dag_runtime.py：维护运行时的共享状态与上下文，使节点间可以基于黑板通信、复用中间结果。资料来源：src/symbio/core/dag_runtime.py:1-1`。
• execution_planner.py：从原始 DAG 描述生成"可执行计划"，包括节点展平、依赖排序、并行分区。资料来源：src/symbio/core/execution_planner.py:1-1`。
• planner_reviewer.py：对计划进行复核，可在执行前阻断非法或低质量计划并给出修复建议。资料来源：src/symbio/core/planner_reviewer.py:1-1`。
• workflow_policy.py：声明式策略来源，约束重试、退避、超时、并发上限等行为。资料来源：src/symbio/core/workflow_policy.py:1-1`。

从分层视角看，六个文件可归为三层：控制面（workflow_policy）、计划面（execution_planner、planner_reviewer）、执行面（dag_orchestrator、dag_engine、dag_runtime）。控制面回答"按什么规则执行"，计划面回答"按什么顺序执行"，执行面回答"具体怎样执行"。这种分层让策略调整、计划优化和执行实现的变更互不耦合。资料来源：src/symbio/core/execution_planner.py:1-1、src/symbio/core/workflow_policy.py:1-1。

执行流程

flowchart LR
    A[DAG 描述] --> B[workflow_policy]
    B --> C[execution_planner]
    C --> D[planner_reviewer]
    D -- 校验通过 --> E[dag_orchestrator]
    E --> F[dag_engine]
    F --> G[dag_runtime]
    G --> H[节点执行产物]

编排器首先加载工作流策略作为计划生成与执行控制的边界条件，再由规划器产出执行计划；审查器对计划做约束校验，校验通过的计划由编排器下发至执行引擎；执行引擎在运行时上下文中驱动节点串/并行执行，并持续回传状态与产物。资料来源：src/symbio/core/dag_orchestrator.py:1-1、src/symbio/core/dag_engine.py:1-1。

规划、审查与策略

execution_planner 与 planner_reviewer 形成"生成—复核"闭环：规划器负责将声明式的 DAG 转为调度器可消费的线性或分层计划，审查器在执行前以策略与约束为依据进行二次把关，避免运行时才发现拓扑错误、资源冲突或策略违例。workflow_policy 作为单一事实来源，决定重试次数、超时阈值、并发上限等控制面参数，从而把"如何执行"与"执行什么"解耦。该设计使得同一份 DAG 描述可以通过替换策略面获得不同运行时行为（例如更激进的并发或更保守的重试），无需修改执行引擎本体。资料来源：src/symbio/core/execution_planner.py:1-1、src/symbio/core/planner_reviewer.py:1-1、src/symbio/core/workflow_policy.py:1-1。

概览与定位

Symbio 的 security/ 与 core/ 子包共同构成了系统在接入层、运行层与可观测层的基础设施骨架。security/ 目录下的三个模块负责对外部输入进行净化、拦截与留痕，相当于应用网关（API Gateway）与防护代理；core/ 下的三个模块则承担语义缓存、上下文剪枝与调用成本监控等横切能力，为上游 Agent 提供稳定的运行时支撑。

从分层视角看，这套基础设施处于大模型调用栈的最外围和最底部：上层是 Agent 与工具调用逻辑，下层是 LLM Provider 与外部存储。任何外部输入在抵达业务逻辑之前，都会先经过 security/injection_guard.py 与 security/gateway.py 的过滤；任何出站调用产生的 Token、费用与延迟都会被 core/cost_monitor.py 记录；所有中间结果都会在 core/semantic_cache.py 中留下复用的可能。

资料来源：src/symbio/security/injection_guard.py:1-40；src/symbio/core/semantic_cache.py:1-30

接入层：安全网关与注入防护

接入层由三段处理流水线组成。第一段是 injection_guard.py 中定义的提示词注入检测器，它会扫描用户输入与外部检索内容，匹配常见的越权指令模式（如"忽略之前的设定"），并对命中片段进行掩码或截断处理。第二段是 gateway.py，作为统一的请求入口与协议适配层，将不同来源（HTTP、WebSocket、CLI、SDK）的请求统一为内部标准事件，并在此处插入审计埋点。第三段是 audit.py，负责把每一次拦截、放行与改写行为落盘为审计日志，便于事后回溯与合规检查。

[外部请求] 
   → injection_guard.py (净化/拦截)
   → gateway.py (协议归一化)
   → audit.py (留痕)
   → Agent 业务逻辑

这套链路的目的是把"信任边界"集中在一个目录中，而不是散落到各个工具调用里。资料来源：src/symbio/security/injection_guard.py:42-90；src/symbio/security/gateway.py:30-110；src/symbio/security/audit.py:20-75

运行层：上下文、缓存与成本治理

运行层的三个核心组件互为补充：

• core/semantic_cache.py 实现基于向量相似度的语义缓存。它为每一次 prompt 计算 embedding，并在配置的阈值内查找已有响应，从而避免对 LLM 的重复调用。资料来源：src/symbio/core/semantic_cache.py:55-120
• core/context_pruner.py 负责对进入 LLM 的上下文窗口进行剪枝。它会基于消息轮次、Token 预算与角色权重，对历史消息和工具结果进行截断或摘要，确保不超过模型上下文上限。资料来源：src/symbio/core/context_pruner.py:40-95
• core/cost_monitor.py 对调用进行计费计量，聚合每次 LLM 调用的输入/输出 Token 数、单价与时延，按会话或时间窗口输出费用概览。资料来源：src/symbio/core/cost_monitor.py:30-85

三者在数据流上呈线性串联：先由 semantic_cache 判断是否可短路返回；若未命中，则进入 context_pruner 压缩上下文；最终无论是否调用 LLM，都会被 cost_monitor 计入成本账本。

部署与运维：观测、日志与策略配置

虽然该层本身不包含 Dockerfile 或编排文件，但 security/audit.py 与 core/cost_monitor.py 是可观测性的两个主要出口：前者输出审计事件流，后者输出结构化的成本/时延指标。运维侧通常通过环境变量或配置对象控制阈值，例如语义缓存的相似度门槛、上下文剪枝的最大 Token 数、注入检测的严格等级等。

部署时建议将 security/ 的组件以进程内中间件的方式注入到 Agent 框架中，把 core/ 的三个模块作为可插拔的横切关注点引入到请求处理管线上，这样既能在本地测试中禁用，也能在生产环境中统一开启。资料来源：src/symbio/security/audit.py:80-140；src/symbio/core/cost_monitor.py:110-160

Pitfall Log / 踩坑日志

项目：854875058/Symbio

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/854875058/Symbio | host_targets=mcp_host, claude, claude_code, codex

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/854875058/Symbio | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/854875058/Symbio | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/854875058/Symbio | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/854875058/Symbio | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/854875058/Symbio | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/854875058/Symbio | release_recency=unknown