附录 D：Feature Flags 一览

本附录以当前 ../octos main 分支的 Cargo workspace 为准。源码审查范围包括根 Cargo.toml 的 members 列表，以及 octos-cli、octos-bus、octos-agent 三个 crate 的 [features] 段。当前 workspace 采用 “默认最小、按需开启通道/工具” 的策略：default = []，生产部署通过显式 feature 组合选择 API、频道、admin bot 和可选工具能力。

Feature 传播图

flowchart LR
    CLI[octos-cli]
    Bus[octos-bus]
    Agent[octos-agent]

    CLI -->|api| BusApi[octos-bus/api]
    CLI -->|telegram / discord / slack / whatsapp / email / feishu / twilio / wecom / matrix / wecom-bot / qq-bot / wechat| Bus
    CLI -->|git| AgentGit[octos-agent/git]
    CLI -->|ast| AgentAst[octos-agent/ast]
    CLI -->|admin-bot includes api| AdminBot[dep:teloxide + dep:futures + api]

    BusApi --> Bus
    AgentGit --> Agent
    AgentAst --> Agent

这张图体现了三个层次：

  1. octos-cli 是最终二进制入口，负责把用户选择的 feature 转发到下游 crate。
  2. octos-bus 承载多频道接入能力，频道相关 feature 基本都从 CLI 转发到 bus。
  3. octos-agent 承载可选工具能力，git 与 ast 通过 CLI feature 暴露给最终构建。

octos-cli Feature Flags

Feature启用功能额外依赖 / 下游 feature默认开启
default最小 CLI 构建—是，且为空
apiWeb API、dashboard、SSE/WebSocket、监控、OTP 登录、Prometheus exporter、用户与 profile 管理dep:axum、dep:tower-http、dep:futures、dep:rust-embed、dep:metrics-exporter-prometheus、dep:lettre、dep:rand、dep:sysinfo、dep:subtle、octos-bus/api否
admin-bot管理 Bot；依赖 API 模式dep:teloxide、dep:futures、api否
telegramTelegram 频道集成octos-bus/telegram否
discordDiscord 频道集成octos-bus/discord否
slackSlack 频道集成octos-bus/slack否
whatsappWhatsApp 频道集成octos-bus/whatsapp否
emailEmail 频道集成octos-bus/email否
feishu飞书频道集成octos-bus/feishu否
twilioTwilio 频道集成octos-bus/twilio否
wecom企业微信回调频道octos-bus/wecom否
matrixMatrix 频道集成octos-bus/matrix否
wecom-bot企业微信 Bot WebSocket 通道octos-bus/wecom-bot否
qq-botQQ Bot WebSocket 通道octos-bus/qq-bot否
wechatWeChat WebSocket bridge 通道octos-bus/wechat否
gitAgent Git 工具能力octos-agent/git否
astAgent AST 代码结构分析能力octos-agent/ast否

octos-bus Feature Flags

Feature启用功能额外依赖默认开启
default最小 bus 构建—是，且为空
apiAPI/SSE/WebSocket 接入所需 bus 类型axum否
telegramTelegram channel 实现teloxide否
discordDiscord channel 实现serenity否
slackSlack WebSocket channel 实现tokio-tungstenite否
whatsappWhatsApp WebSocket channel 实现tokio-tungstenite否
feishu飞书 channel 与回调接入tokio-tungstenite、axum、rustls、rustls-native-certs否
twilioTwilio webhook/API channelaxum否
wecom企业微信 webhook/API channelaxum否
matrixMatrix webhook/API channelaxum否
wecom-bot企业微信 Bot WebSocket channeltokio-tungstenite、rustls、rustls-native-certs否
qq-botQQ Bot WebSocket channeltokio-tungstenite、rustls、rustls-native-certs否
wechatWeChat bridge WebSocket channeltokio-tungstenite否
emailEmail channel，含 IMAP/SMTP 与邮件解析async-imap、tokio-rustls、rustls、webpki-roots、lettre、mailparse否

octos-agent Feature Flags

Feature启用功能额外依赖默认开启
gitGit 操作与 diff 能力dep:gix、dep:similar否
astAST 代码结构分析，覆盖 Rust/Python/JavaScript/TypeScript parserdep:tree-sitter、dep:tree-sitter-rust、dep:tree-sitter-python、dep:tree-sitter-javascript、dep:tree-sitter-typescript否

octos-agent 当前没有显式 default = [] 行；这表示没有默认 feature 被声明，git 和 ast 仍然只会在上游显式开启时编译。

当前没有 [features] 的 crate

这些 crate 目前没有 Cargo feature flags；它们要么始终作为核心库编译，要么作为独立 app-skill / platform-skill 二进制维护自己的依赖边界：

类别Crate
核心库octos-core、octos-memory、octos-llm、octos-pipeline、octos-plugin、octos-swarm、octos-dora-mcp
平台/沙箱octos-sandbox、platform-skills/voice
App skillsnews、deep-search、deep-crawl、send-email、account-manager、time、weather、wechat-bridge、pipeline-guard、skill-evolve
Harness starter skillsharness-starter-generic、harness-starter-report、harness-starter-audio、harness-starter-coding

编译示例

# 最小 CLI：不启用 API、频道集成、Git/AST 工具
cargo build -p octos-cli --release

# CLI + Web API / Dashboard
cargo build -p octos-cli --release --features api

# API + 管理 Bot
cargo build -p octos-cli --release --features admin-bot

# Gateway 常见多频道组合
cargo build -p octos-cli --release --features "api,telegram,slack,email,feishu,wecom-bot,qq-bot,wechat"

# 开发者完整构建：包括 API、所有频道、Git/AST 工具
cargo build -p octos-cli --release --all-features

设计原则

Feature flags 的工程边界不是“功能分类标签”，而是“依赖树切割线”：

  1. 频道集成放在 octos-bus，CLI 只做 feature 转发，避免 CLI 直接知道每个频道的底层依赖。
  2. api 是服务端能力开关，不只启用 axum，还会连带 dashboard embedding、Prometheus exporter、OTP/email 相关依赖和 bus API 层。
  3. admin-bot 显式依赖 api，因为它不是独立聊天频道，而是服务端管理面的入口。
  4. git / ast 放在 octos-agent，通过 CLI 暴露，避免默认构建拉入较重的 Git 和 tree-sitter 依赖。
  5. app-skill 二进制没有使用 Cargo features；它们通过 workspace member 和 skill manifest 管理分发边界，而不是通过主 CLI 的 feature flag 混编。