资料来源：README.md:1-10

核心设计理念

Tandem 的核心理念是 Intent → Authority Projection → Scoped Execution → Approval Gates → Artifacts → Audit Trail。这个流程确保了 AI 操作的可控性和可追溯性。

Tandem 不是另一个聊天封装器，也不是简单的代理框架。它是代理在企业系统中移动时赖以运行的执行运行时。所有入口点（桌面应用、TUI、Web 控制面板、SDK）都连接到同一个引擎运行时，而运行时拥有运行、会话、内存、上下文、提供商密钥、MCP 工具、审批、工件和审计记录的权威性。

资料来源：README.md:47-60

架构概览

graph TB
    subgraph "客户端层"
        TUI["TUI 终端界面<br>tandem-tui"]
        Desktop["桌面应用<br>Tauri App"]
        Panel["Web 控制面板<br>Control Panel"]
        SDK["SDK 客户端<br>TypeScript/Python"]
    end
    
    subgraph "引擎运行时"
        Engine["tandem-engine<br>Headless HTTP/SSE 运行时"]
        Sidecar["tandem-browser<br>浏览器自动化 Sidecar"]
    end
    
    subgraph "核心子系统"
        Memory["Memory System<br>记忆系统"]
        Tools["Tool Registry<br>工具注册表"]
        MCP["MCP Connectors<br>MCP 连接器"]
        Governance["Governance Engine<br>治理引擎"]
    end
    
    subgraph "提供商层"
        Providers["Provider Registry<br>12+ 提供商支持"]
        OpenAI["OpenAI"]
        Anthropic["Anthropic"]
        Ollama["Ollama"]
        Others["Others..."]
    end
    
    TUI -->|HTTP/SSE| Engine
    Desktop -->|Sidecar IPC| Engine
    Panel -->|HTTP/SSE| Engine
    SDK -->|HTTP API| Engine
    
    Engine <--> Sidecar
    Engine <--> Memory
    Engine <--> Tools
    Engine <--> MCP
    Engine <--> Governance
    
    Providers --> OpenAI
    Providers --> Anthropic
    Providers --> Ollama
    Providers --> Others
    
    Engine --> Providers

组件职责

资料来源：engine/src/main.rs:1-50

支持的 AI 提供商

Tandem 采用提供商无关（Provider agnostic）的设计，支持 12 种以上的 AI 提供商：

graph LR
    P["Provider Registry"] --> O["openai"]
    P --> OR["openrouter"]
    P --> A["anthropic"]
    P --> OL["ollama"]
    P --> G["groq"]
    P --> M["mistral"]
    P --> T["together"]
    P --> AZ["azure"]
    P --> B["bedrock"]
    P --> V["vertex"]
    P --> C["copilot"]
    P --> CO["cohere"]

资料来源：engine/src/main.rs:16-28

引擎 CLI 与命令

tandem-engine 是 Tandem 的核心命令行工具，提供多种运行模式：

# 启动 HTTP/SSE 运行时服务
tandem-engine serve --hostname 127.0.0.1 --port 39731

# 检查引擎健康状态
tandem-engine status --hostname 127.0.0.1 --port 39731

# 单次 prompt 执行
tandem-engine run "Summarize this repository" --provider openrouter --model openai/gpt-4o-mini

# 直接工具执行
tandem-engine tool --json @payload.json

# 从标准输入读取
cat payload.json | tandem-engine tool --json -

# 列出可用提供商
tandem-engine providers

# 生成 API Token
tandem-engine token generate

服务命令示例

资料来源：engine/src/main.rs:30-60

Sidecar 架构

Tandem 采用 Sidecar 模式管理浏览器自动化能力。桌面应用通过进程间通信与 tandem-browser sidecar 交互。

sequenceDiagram
    participant Desktop as Tauri Desktop App
    participant Engine as tandem-engine
    participant Sidecar as tandem-browser
    
    Desktop->>Engine: 启动服务
    Engine->>Sidecar: 进程启动 (Child Process)
    Desktop->>Engine: 请求浏览器操作
    Engine->>Sidecar: 转发操作指令
    Sidecar->>Sidecar: 执行浏览器自动化
    Sidecar-->>Engine: 返回结果
    Engine-->>Desktop: SSE 事件推送

Sidecar 生命周期管理

Sidecar 管理器负责 sidecar 的版本追踪、下载和更新：

资料来源：src-tauri/src/sidecar.rs:1-60

安全与隐私

Tandem 采用零信任安全模型，在多个层面保护用户数据和系统安全：

Vault 状态管理

桌面应用中的 Vault 模块管理加密密钥的生命周期：

pub struct VaultState {
    pub unlocked: RwLock<bool>,           // Vault 是否解锁
    pub master_key: RwLock<Option<Vec<u8>>>,  // 解密的主密钥
    pub app_data_dir: PathBuf,           // 应用数据目录
}

资料来源：src-tauri/src/lib.rs:45-60

客户端 SDK

TypeScript / Node.js 客户端

@frumu/tandem-client 是 Tandem 的官方 TypeScript SDK，支持 Node 18+：

import { TandemClient } from "@frumu/tandem-client";

const client = new TandemClient({
  baseUrl: "http://localhost:39731",
  token: "your-engine-token",
});

// 1. 创建会话
const sessionId = await client.sessions.create({
  title: "My agent session",
  directory: "/path/to/my/project",
});

// 2. 异步启动运行
const { runId } = await client.sessions.promptAsync(
  sessionId,
  "Summarize the README"
);

// 3. 流式接收响应
for await (const event of client.stream(sessionId, runId)) {
  if (event.type === "session.response") {
    process.stdout.write(String(event.properties.delta ?? ""));
  }
}

客户端配置选项

浏览器状态响应

SDK 提供了完整的类型定义来描述引擎状态：

interface BrowserStatusResponse {
  enabled?: boolean;
  runnable?: boolean;
  headless_default?: boolean;
  sidecar?: BrowserBinaryStatus;
  browser?: BrowserBinaryStatus;
  blocking_issues?: BrowserBlockingIssue[];
  recommendations?: string[];
}

资料来源：packages/tandem-client-ts/src/wire/index.ts:1-80

部署模式

Tandem 支持多种部署模式，可根据需求选择：

graph TB
    A["部署模式选择"] --> B["桌面应用"]
    A --> C["Headless 引擎"]
    A --> D["Web 控制面板"]
    A --> E["自定义 SDK"]
    
    B --> B1["Tauri 桌面客户端"]
    B --> B2["内置 sidecar 管理"]
    
    C --> C1["tandem-engine serve"]
    C --> C2["无图形界面"]
    C --> C3["远程/VPS 部署"]
    
    D --> D1["@frumu/tandem-panel"]
    D --> D2["完整 Web UI"]
    
    E --> E1["TypeScript SDK"]
    E --> E2["Python SDK"]
    E --> E3["直接 HTTP API"]

快速入门指南

资料来源：packages/tandem-control-panel/README.md:1-30

许可证说明

Tandem 采用开放核心（Open Core）许可模式：

详细许可信息请参阅 docs/LICENSING.md。

资料来源：README.md:80-100

版本与发布

当前稳定版本为 Tandem v0.5.11 (2026-05-25)：

Tandem 0.5.11 准备了托管企业引擎分发路径。此版本构建了包含浏览器自动化和企业完整路由的 Linux x64 tandem-engine 二进制文件，作为单独的企业发布资产发布，并添加了专用的 npm wrapper 用于托管 sidecar。

资料来源：README.md:社区上下文

相关文档

• 架构设计 - Tandem 完整架构文档
• 引擎 CLI 参考 - 命令行工具完整参考
• 引擎通信协议 - 桌面/运行时通信契约
• MCP 集成 - Model Context Protocol 连接指南
• AI 运行时基础设施 - 深度技术文档
• 企业就绪 - 企业部署指南
• 安全模型 - 威胁模型和安全报告流程

架构概览

Tandem 采用多进程架构，将桌面应用、引擎运行时和浏览器自动化能力解耦为独立进程，通过本地 HTTP/SSE API 进行通信。这种设计实现了关注点分离，使得各个组件可以独立开发、部署和扩展。

graph TD
    subgraph Desktop["桌面端 (Tauri)"]
        A[Tauri 应用主进程]
        B[Web 控制面板]
        C[技能系统]
        D[模式系统]
        E[内存系统]
    end
    
    subgraph Sidecar["Sidecar 进程"]
        F[tandem-engine]
        G[工具注册表]
        H[提供商注册表]
    end
    
    subgraph Browser["浏览器自动化"]
        I[tandem-browser]
        J[Playwright 引擎]
    end
    
    subgraph External["外部服务"]
        K[AI 提供商]
        L[本地 Ollama]
        M[MCP 连接器]
    end
    
    A -->|spawn| F
    A -->|spawn| I
    F -->|HTTP/SSE| B
    F -->|API 调用| K
    F -->|API 调用| L
    F -->|MCP 协议| M
    I -->|自动化| J

资料来源：src-tauri/src/lib.rs:1-50

核心组件

桌面端主进程

桌面端采用 Tauri 框架构建，负责整个应用的生命周期管理、状态协调和用户界面呈现。

主进程通过 Manager trait 与 Tauri 运行时交互，并使用 StoreExt 扩展进行持久化状态存储：

use tauri::{Manager};
use tauri_plugin_store::StoreExt;

资料来源：src-tauri/src/lib.rs:35-45

Engine 引擎运行时

tandem-engine 是 Tandem 的核心推理引擎，以独立进程运行，提供 HTTP/SSE API 接口。

#### CLI 子命令

资料来源：engine/src/main.rs:30-80

#### 支持的 AI 提供商

引擎支持 12 个主流 AI 提供商，通过 ProviderRegistry 进行统一管理：

const SUPPORTED_PROVIDER_IDS: [&str; 12] = [
    "openai", "openrouter", "anthropic", "ollama", "groq",
    "mistral", "together", "azure", "bedrock", "vertex",
    "copilot", "cohere",
];

资料来源：engine/src/main.rs:18-27

浏览器自动化组件

tandem-browser 是独立的浏览器自动化 Sidecar，通过 Playwright 提供浏览器控制能力。

#### 状态检测逻辑

flowchart LR
    A[配置检查] --> B{browser.enabled?}
    B -->|是| C{sidecar.found?}
    B -->|否| D[runnable = false]
    C -->|是| E{browser.found?}
    C -->|否| F[添加阻塞问题]
    E -->|是| G[runnable = true]
    E -->|否| H[添加阻塞问题]

状态检测会评估三个条件：

1. 浏览器自动化是否启用
2. Sidecar 二进制文件是否存在
3. 本地浏览器是否可用

status.runnable = config.enabled
    && status.sidecar.found
    && status.browser.found
    && status.blocking_issues.is_empty();

资料来源：crates/tandem-server/src/browser_parts/part02.rs:30-60

进程间通信

HTTP/SSE 协议

引擎通过 HTTP REST API 和 Server-Sent Events (SSE) 提供双向通信能力。

sequenceDiagram
    participant Client as TypeScript SDK
    participant Engine as tandem-engine
    participant Browser as tandem-browser
    
    Client->>Engine: POST /sessions (创建会话)
    Engine-->>Client: session_id
    
    Client->>Engine: POST /sessions/{id}/prompt (发送提示)
    Engine-->>Client: SSE stream (run.started)
    
    Engine->>Browser: 浏览器自动化请求
    Browser-->>Engine: 自动化结果
    
    Engine-->>Client: SSE stream (session.response)
    Engine-->>Client: SSE stream (run.complete)

#### SDK 使用示例

import { TandemClient } from "@frumu/tandem-client";

const client = new TandemClient({
  baseUrl: "http://localhost:39731",
  token: "your-engine-token", // 从 tandem-engine token generate 获取
});

// 1. 创建会话
const sessionId = await client.sessions.create({
  title: "My agent session",
  directory: "/path/to/my/project",
});

// 2. 启动异步运行
const { runId } = await client.sessions.promptAsync(
  sessionId,
  "Summarize the README and list the top 3 TODOs"
);

// 3. 流式接收响应
for await (const event of client.stream(sessionId, runId)) {
  if (event.type === "session.response") {
    process.stdout.write(String(event.properties.delta ?? ""));
  }
  if (event.type === "run.complete" || event.type === "run.failed") {
    break;
  }
}

资料来源：packages/tandem-client-ts/README.md:20-50

API 参数配置

Sidecar 进程管理

桌面端通过进程管理机制启动和控制 Engine Sidecar：

#### Windows 进程隔离

在 Windows 平台上，使用 Job Objects 实现进程隔离和资源控制：

#[cfg(windows)]
use windows_sys::Win32::System::JobObjects::{
    AssignProcessToJobObject, CreateJobObjectW, JobObjectExtendedLimitInformation,
    SetInformationJobObject, JOBOBJECT_EXTENDED_LIMIT_INFORMATION,
    JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
};

#### 进程启动参数

std::process::Command::new(path)
    .arg("--version")
    .output()

Sidecar 使用子进程方式启动，支持通过环境变量配置连接参数：

资料来源：src-tauri/src/sidecar.rs:20-40

版本管理与更新

Sidecar 二进制管理器

SidecarBinaryManager 负责从 GitHub releases 自动下载和更新二进制文件。

flowchart TD
    A[启动检查] --> B{本地已安装?}
    B -->|是| C{版本匹配?}
    B -->|否| D[查询 GitHub API]
    C -->|否| D
    C -->|是| E[使用缓存]
    D --> F[下载最新版本]
    F --> G[验证二进制大小]
    G --> H[缓存版本信息]
    H --> I[启动进程]
    
    style D fill:#f96
    style F fill:#f96

#### 版本检查配置

const RELEASE_REQUEST_TIMEOUT_SECS: u64 = 8;
const MIN_BINARY_SIZE: u64 = 100 * 1024; // 100KB minimum

资料来源：src-tauri/src/sidecar_manager.rs:10-30

核心模块架构

Tandem Core 库

tandem-core 是共享的基础库，提供核心类型定义和工具函数：

classDiagram
    class ToolRegistry {
        +register(tool: Tool)
        +execute(name: String, args: JSON)
        +list() Vec~Tool~
    }
    class ProviderRegistry {
        +register(provider: Provider)
        +get(id: String) Option~Provider~
        +list_providers() Vec~String~
    }
    class RuntimeState {
        +sessions: HashMap
        +active_runs: HashMap
        +memory_tiers: Vec
    }
    
    ToolRegistry --> ProviderRegistry
    RuntimeState --> ToolRegistry

关键导出项：

• ToolRegistry - 工具注册与管理
• ProviderRegistry - AI 提供商注册与管理
• resolve_shared_paths() - 解析共享数据路径
• DEFAULT_ENGINE_PORT - 默认引擎端口 39731
• engine_api_token_file_path() - API 令牌文件路径

资料来源：crates/tandem-core/src/lib.rs

技能系统

技能（Skills）系统允许扩展 Tandem 的能力边界：

use tandem_skills::{SkillContent, SkillInfo, SkillLocation, SkillTemplateInfo};

资料来源：src-tauri/src/sidecar.rs:15-18

模式系统

模式（Modes）定义了不同的运行策略，包括 Plan Mode 和 Immediate Mode：

部署架构

桌面端部署

graph LR
    A[Tandem 桌面应用] --> B[启动 Sidecar]
    B --> C[tandem-engine]
    B --> D[tandem-browser]
    C --> E[Web 控制面板]
    E --> F[浏览器访问 :39734]

企业版部署

v0.5.11 版本引入了企业版引擎分发路径：

# 企业版安装
npm install -g @frumu/tandem

Docker 部署

提供了 Docker Compose 配置，支持容器化部署：

# 关键配置
engine:
  port: 39731
  token_file: ./secrets/tandem_api_token

panel:
  port: 39734
  depends_on: engine

资料来源：packages/tandem-control-panel/README.md

安全架构

零信任安全模型

Tandem 实现零信任安全架构，所有组件间通信都需要显式认证：

pub struct VaultState {
    pub unlocked: RwLock<bool>,
    pub master_key: RwLock<Option<Vec<u8>>>,
    pub app_data_dir: std::path::PathBuf,
}

资料来源：src-tauri/src/lib.rs:55-65

网络范围

遥测与隐私

• 无遥测：不包含分析或回传遥测
• 提供商流量：AI 请求仅发送到用户配置的端点
• 更新检查：仅 GitHub 端点

资料来源：README.md 安全和隐私部分

技术栈概览

引擎包结构

graph TD
    A[tandem-engine] --> B[tandem-core]
    A --> C[tandem-server]
    A --> D[tandem-providers]
    A --> E[tandem-tools]
    A --> F[tandem-skills]
    C --> G[tandem-plan-compiler]
    G --> H[tandem-governance-engine]

构建命令：

# 本地开发
cargo build -p tandem-engine

# 发布打包
cargo build --release -p tandem-engine

资料来源：engine/README.md

相关文档

• ENGINE_CLI.md - 引擎 CLI 参考手册
• ENGINE_COMMUNICATION.md - 桌面/运行时通信契约
• ENGINE_TESTING.md - 引擎测试与冒烟检查
• SECURITY.md - 安全威胁模型与报告流程
• LICENSING.md - 混合许可证说明

本页面介绍 Tandem 的核心概念、架构组件、运行模式以及各子系统之间的协作关系，帮助开发者理解系统的设计哲学和使用方式。

概述

Tandem 是一个本地优先、零信任的 AI 工作空间应用，核心是头部的 tandem-engine 运行时引擎。该引擎支持多种 AI 提供商，包括 OpenAI、Anthropic、Ollama、Groq、Mistral、Azure 等 12 个主流服务提供商。

Tandem 的核心特性包括：

• 本地优先：数据优先存储在本地，不强制云端同步
• 零信任安全：不包含遥测追踪，提供加密凭证存储（AES-256-GCM）
• 提供商无关：可自由路由到用户配置的 AI 服务端点
• 可扩展架构：支持技能（Skills）、插件（Plugins）、MCP 协议

资料来源：README.md

安装方式

Tandem 提供多种安装路径，开发者可根据使用场景选择最适合的方案。

桌面应用（推荐新手）

桌面应用集成了完整的控制面板和引擎运行时，适合日常使用。

1. 下载并安装 Tandem：tandem.ac
2. 打开 Settings 添加提供商 API 密钥
3. 选择工作区文件夹
4. 开始使用任务提示，选择 Immediate 或 Plan Mode 模式

资料来源：README.md

Web 控制面板

Web 控制面板提供完整的图形化配置界面，适合服务器部署和远程访问。

npm i -g @frumu/tandem
tandem install panel
tandem panel init

资料来源：packages/tandem-control-panel/README.md

Docker 部署

对于容器化部署场景，Tandem 提供了开箱即用的 Docker Compose 配置：

# 从 tandem-control-panel 包中获取 docker-compose.yml
# 或使用 tandamd install panel 后在本地查找
docker-compose up -d

Docker 部署会将引擎和面板运行在同一 Docker 网络中，默认面板监听端口 39734。

资料来源：packages/tandem-control-panel/DOCKER.md

纯引擎运行时

如果只需要头部的引擎运行时（无图形界面），可通过 npm 全局安装：

npm install -g @frumu/tandem
tandem-engine serve --hostname 127.0.0.1 --port 39731

资料来源：README.md

终端界面（TUI）

对于命令行爱好者，Tandem 提供全屏终端用户界面：

npm i -g @frumu/tandem-tui && tandem-tui

可编辑面板脚手架

生成完全可定制的控制面板应用：

npm create tandem-panel@latest my-panel
cd my-panel
npm install
npm run dev

此方式允许开发者自定义路由、页面、主题、样式或运行时行为。

资料来源：README.md

引擎配置

环境变量配置

tandem-engine 支持通过环境变量进行配置：

资料来源：engine/src/main.rs:40-60

命令行参数

tandem-engine 支持多种子命令：

# 启动 HTTP/SSE 服务
tandem-engine serve --hostname 0.0.0.0 --port 39731

# 检查引擎健康状态
tandem-engine status --hostname 127.0.0.1 --port 39731

# 一次性执行提示
tandem-engine run "Summarize this repository" --provider openrouter --model openai/gpt-4o-mini

# 列出可用提供商
tandem-engine providers

# 导入记忆数据
tandem-engine memory import --path ./docs --tier project --project-id repo-123

资料来源：engine/src/main.rs:30-50

AI 提供商配置

引擎支持的提供商列表：

资料来源：engine/src/main.rs:15-30

SDK 集成

TypeScript SDK

// npm install @frumu/tandem-client
import { TandemClient } from "@frumu/tandem-client";

const client = new TandemClient({
  baseUrl: "http://localhost:39731",
  token: "your-engine-token", // 从 `tandem-engine token generate` 获取
});

// 1. 创建会话
const sessionId = await client.sessions.create({
  title: "My agent session",
  directory: "/path/to/my/project",
});

// 2. 启动异步运行
const { runId } = await client.sessions.promptAsync(
  sessionId,
  "Summarize the README and list the top 3 TODOs"
);

// 3. 流式获取响应
for await (const event of client.stream(sessionId, runId)) {
  if (event.type === "session.response") {
    process.stdout.write(String(event.properties.delta ?? ""));
  }
  if (
    event.type === "run.complete" ||
    event.type === "run.completed" ||
    event.type === "run.failed" ||
    event.type === "session.run.finished"
  )
    break;
}

前置条件：需要 Node.js 18+（使用内置 fetch 和 ReadableStream）

资料来源：packages/tandem-client-ts/README.md

Python SDK

pip install tandem-client

from tandem_client import TandemClient

client = TandemClient(
    base_url="http://localhost:39731",
    token="your-engine-token"
)

session_id = client.sessions.create(
    title="My agent session",
    directory="/path/to/my/project"
)

result = client.sessions.prompt(session_id, "Summarize this repository")
print(result)

SDK 重要说明

注意：SDK 是 API 客户端，它们不包含 tandem-engine。

必须先运行 Tandem 运行时（桌面侧载或头部引擎），然后再使用 SDK 创建会话、触发运行和流式传输事件。

资料来源：README.md

认证与令牌管理

生成 API 令牌

首次启动引擎后，需要生成认证令牌：

tandem-engine token generate

Web 登录流程

托管部署场景下，控制面板支持浏览器 OAuth 登录：

1. 打开控制面板登录页
2. 选择 "Sign in with Tandem"
3. 完成浏览器中的身份验证
4. 返回控制面板继续使用

本地独立安装场景下，需要在控制台输入引擎令牌进行认证。

资料来源：packages/tandem-control-panel/src/app/LoginPage.tsx

工作流程图

graph TD
    A[安装 Tandem] --> B{选择使用方式}
    B -->|桌面应用| C[下载安装包]
    B -->|Web 控制面板| D[npm 全局安装]
    B -->|纯引擎| E[tandem-engine serve]
    B -->|SDK 集成| F[安装 SDK 包]
    
    C --> G[配置 AI 提供商]
    D --> H[tandem panel init]
    E --> G
    F --> I[启动引擎]
    
    G --> I
    H --> I
    I --> J[生成认证令牌]
    J --> K[创建会话]
    K --> L[提交任务提示]
    L --> M[流式响应结果]

常见问题

引擎启动失败

症状：tandem-engine serve 命令报错

排查步骤：

1. 检查端口占用：lsof -i :39731
2. 确认 Node.js/npm 已正确安装
3. 查看日志输出：tandem-engine serve --verbose

找不到 tandem-browser 侧载

症状：浏览器自动化功能不可用

解决方案：

1. 确保 tandem-browser 二进制文件已安装
2. 或设置环境变量：TANDEM_BROWSER_SIDECAR=/path/to/tandem-browser
3. 或在配置文件中指定：browser.sidecar_path

资料来源：crates/tandem-server/src/browser_parts/part02.rs

凭证存储加密

Tandem 使用 AES-256-GCM 加密存储提供商 API 密钥，存储位置由 tandem_core::resolve_shared_paths() 决定。

下一步

• 引擎 CLI 参考 - 完整的命令行文档
• 引擎通信协议 - 桌面/运行时通信契约
• 架构概述 - 深入理解系统设计
• 安全模型 - 零信任安全实现细节

另请参阅

• Tandem 官方文档
• @frumu/tandem-client npm 包
• Python SDK (PyPI)
• GitHub Releases

核心架构

Tandem 桌面应用采用双进程架构：主进程（Rust/Tauri）与引擎 Sidecar 子进程通过本地回环地址（127.0.0.1）进行安全通信。

graph TD
    subgraph Desktop["桌面应用 (Tauri Rust)"]
        A[用户界面] --> B[命令层]
        B --> C[状态管理]
        C --> D[凭证存储 Vault]
        C --> E[扩展管理]
        C --> F[浏览器自动化]
    end
    
    subgraph Sidecar["引擎 Sidecar"]
        G[tandem-engine 进程]
        H[HTTP/SSE API]
        I[工具执行器]
        J[记忆系统]
    end
    
    K[Provider API] --> G
    L[文件系统] --> G
    
    Desktop <-->|127.0.0.1:39731| Sidecar
    
    style Desktop fill:#e1f5fe
    style Sidecar fill:#fff3e0

资料来源：src-tauri/src/lib.rs:1-50

进程生命周期

桌面应用启动时执行以下初始化流程：

1. 解析共享路径和配置目录
2. 初始化日志系统（tracing + 非阻塞写入）
3. 加载或创建引擎 API Token
4. 启动/检测 Sidecar 进程状态
5. 注册 Tauri 命令和事件处理器

资料来源：src-tauri/src/lib.rs:20-40

安全模型

Tandem 桌面应用实现了零信任（Zero-Trust）安全架构，默认拒绝敏感路径访问，并对所有外部通信进行严格控制。

安全特性

资料来源：README.md 安全和隐私部分

Vault 状态管理

Vault 模块管理加密凭证的生命周期：

stateDiagram-v2
    [*] --> Locked: 应用启动
    Locked --> Unlocked: 用户解锁
    Unlocked --> Locked: 锁定/退出
    Unlocked --> [*]: 应用关闭
    
    state Unlocked {
        [*] --> HasMasterKey: 解密成功
        HasMasterKey --> [*]: Token 可用
    }

资料来源：src-tauri/src/lib.rs:44-55

核心组件

Sidecar 管理器

Sidecar 管理器负责 Engine 进程的完整生命周期，包括检测、下载、更新和版本追踪。

资料来源：src-tauri/src/sidecar_manager.rs:1-40

Sidecar 进程通信

Sidecar 模块处理与 Engine 进程的进程间通信：

资料来源：src-tauri/src/sidecar.rs:1-50

sequenceDiagram
    participant Desktop as 桌面应用
    participant Sidecar as tandem-engine
    participant Provider as AI Provider
    
    Desktop->>Sidecar: 启动进程
    Sidecar->>Desktop: 进程就绪
    Desktop->>Sidecar: HTTP/SSE 请求
    Sidecar->>Provider: API 调用
    Provider-->>Sidecar: 响应数据
    Sidecar-->>Desktop: SSE 流式事件

扩展系统

桌面应用支持四类扩展，统一在扩展管理界面中管理：

资料来源：src/i18n/locales/en/common.json:20-35

用户界面

登录与认证

桌面应用支持两种认证模式：

资料来源：packages/tandem-control-panel/README.md:1-30

工作区管理

用户首次使用时需要：

1. 下载并启动 Tandem
2. 在 Settings → Providers 中配置 API 密钥
3. 或使用本地控制面板连接 Codex 账户
4. 选择工作区文件夹
5. 使用任务提示启动 Immediate 或 Plan Mode

资料来源：README.md 使用入门部分

配置与自定义

可编辑面板脚手架

开发者可以生成本地完全可编辑的控制面板应用：

npm create tandem-panel@latest my-panel
cd my-panel
npm install
npm run dev

此方式适用于需要自定义路由、页面、主题、样式或运行时行为的场景，无需修改 node_modules。

资料来源：README.md 可编辑 App 脚手架部分

引擎配置

引擎支持通过命令行参数和环境变量配置：

tandem-engine serve --hostname 127.0.0.1 --port 39731
tandem-engine status --hostname 127.0.0.1 --port 39731

资料来源：engine/src/main.rs:30-55

常见问题排查

Sidecar 相关问题

问题：tandem-browser sidecar binary was not found

解决方案：

• 安装或打包 tandem-browser
• 设置环境变量 TANDEM_BROWSER_SIDECAR
• 或在配置中设置 browser.sidecar_path

资料来源：crates/tandem-server/src/browser_parts/part02.rs:15-25

浏览器自动化状态检查

flowchart LR
    A[检查配置] --> B{enabled?}
    B -->|否| C[状态: 不运行]
    B -->|是| D{browser found?}
    D -->|否| E[阻塞问题: 浏览器未找到]
    D -->|是| F{sidecar found?}
    F -->|否| G[阻塞问题: Sidecar 未找到]
    F -->|是| H[状态: 可运行]
    E --> I[推荐解决方案]
    G --> I

资料来源：crates/tandem-server/src/browser_parts/part02.rs:10-35

引擎 Token 问题

如果面板无法连接 Engine，检查：

1. Engine Token 是否生成：tandem-engine token generate
2. Token 文件路径是否正确：~/.tandem/tandem_api_token
3. Token 是否在浏览器和 Engine 间一致

许可证说明

Tandem 采用开放核心模式，许可证分布如下：

资料来源：README.md 许可证部分

相关文档

• 架构概览 — 完整系统架构说明
• 引擎运行时与 CLI 参考 — 命令行工具完整文档
• 引擎通信协议 — 桌面与引擎间的通信契约
• 引擎测试 — 测试与冒烟检查指南
• Tandem MCP 文档 — MCP 集成配置
• 文档门户 — 官方文档中心

概述

Tandem Engine 是 Tandem 项目的核心无头（Headless）AI 后端运行时，提供 HTTP/SSE API 接口，支持模型无关的 AI 任务编排。引擎通过命令行接口（CLI）驱动，具备健康检查、会话管理、工具执行和内存导入等核心功能。开发者可通过 TypeScript SDK 或直接调用 REST API 与引擎交互，实现本地部署或远程托管的自定义 AI 工作流。

引擎的定位是 本地优先（Local-first） 的隐私保护型 AI 运行时，默认与桌面客户端的 Sidecar 进程通过 127.0.0.1 通信，确保数据不离开本地环境，除非用户显式配置外部 Provider 端点。资料来源：engine/src/main.rs:32-55

核心架构

进程模型

Tandem Engine 采用 Sidecar 模式 运行，主进程负责任务编排和 API 服务，辅助进程处理浏览器自动化等特定功能。该设计将计算密集型或系统级任务隔离到独立进程中，通过进程间通信协调工作。

graph TD
    A[Desktop Client<br/>Tauri App] -->|IPC + SSE| B[Engine Main Process<br/>tandem-engine serve]
    B --> C[Browser Sidecar<br/>tandem-browser]
    B --> D[AI Provider API<br/>OpenAI/Anthropic/Ollama...]
    E[External Agent<br/>MCP Client] -->|HTTP/SSE| B

支持的 AI Provider

引擎支持 12 种主流 AI Provider，通过统一接口路由请求：

资料来源：engine/src/main.rs:17-30

命令行接口

全局命令结构

tandem-engine CLI 采用子命令架构，主要包含以下操作：

tandem-engine [GLOBAL_OPTIONS] <COMMAND> [ARGS]

常用命令示例

#### 启动服务

# 默认配置启动（localhost:39731）
tandem-engine serve

# 指定端口和网络接口
tandem-engine serve --hostname 0.0.0.0 --port 39731

# 带状态目录的持久化启动
tandem-engine serve --state-dir .tandem-state --provider openrouter --model openai/gpt-4o-mini

#### 健康检查

# 默认检查
tandem-engine status

# 指定目标
tandem-engine status --hostname 127.0.0.1 --port 39731

#### 单次任务执行

tandem-engine run "Summarize this repository" --provider openrouter --model openai/gpt-4o-mini

#### 工具直接调用

# 从文件加载 JSON payload
tandem-engine tool --json @payload.json

# 从标准输入读取
cat payload.json | tandem-engine tool --json -

#### 内存导入

# 导入 OpenClaw 格式数据
tandem-engine memory import --path ~/.openclaw --format openclaw

# 导入到项目级别存储
tandem-engine memory import --path ./docs --tier project --project-id repo-123 --sync-deletes

资料来源：engine/src/main.rs:38-75

服务配置

环境变量

Sidecar 管理

引擎的浏览器自动化功能依赖独立的 tandem-browser Sidecar 进程。引擎会自动检测二进制文件位置：

1. 显式配置：browser.sidecar_path 或 TANDEM_BROWSER_SIDECAR 环境变量
2. 托管安装：<shared_root>/binaries/tandem-browser
3. 共享路径解析：tandem-core::resolve_shared_paths() 返回的规范根目录

Sidecar 版本探测通过执行 --version 参数验证，失败时记录警告但不影响核心功能。

graph LR
    A[Engine Start] --> B{Has explicit<br/>sidecar_path?}
    B -->|Yes| C[Use explicit path]
    B -->|No| D{Managed path<br/>exists?}
    D -->|Yes| C
    D -->|No| E[Search PATH]
    E --> F{Found<br/>tandem-browser?}
    F -->|Yes| C
    F -->|No| G[Mark unavailable<br/>Continue without browser]
    C --> H[Probe version<br/>with --version]

资料来源：crates/tandem-server/src/browser_parts/part02.rs:45-85

浏览器功能状态检测

引擎启动时执行完整的浏览器子系统检测：

阻塞问题代码：

• browser_sidecar_not_found：Sidecar 二进制文件缺失
• browser_not_found：本地浏览器未安装
• version_mismatch：版本不兼容

资料来源：crates/tandem-server/src/browser_parts/part02.rs:28-50

API 认证

令牌管理

引擎使用文件存储的 API 令牌进行认证，令牌文件路径由 tandem_core::engine_api_token_file_path() 确定。

# 生成新令牌
tandem-engine token generate

# 查看当前令牌
tandem-engine token show

TypeScript SDK 认证

import { TandemClient } from "@frumu/tandem-client";

const client = new TandemClient({
  baseUrl: "http://localhost:39731",
  token: "your-engine-token", // 从 tandem-engine token generate 获取
});

SDK 需要 Node 18+ 环境，利用内置的 fetch 和 ReadableStream API。

资料来源：packages/tandem-client-ts/README.md:25-40

TypeScript 客户端使用

完整工作流程

import { TandemClient } from "@frumu/tandem-client";

const client = new TandemClient({
  baseUrl: "http://localhost:39731",
  token: "your-engine-token",
});

// 1. 创建会话
const sessionId = await client.sessions.create({
  title: "My agent session",
  directory: "/path/to/my/project",
});

// 2. 启动异步运行
const { runId } = await client.sessions.promptAsync(
  sessionId,
  "Summarize the README and list the top 3 TODOs"
);

// 3. 流式获取响应
for await (const event of client.stream(sessionId, runId)) {
  if (event.type === "session.response") {
    process.stdout.write(String(event.properties.delta ?? ""));
  }
  if (
    event.type === "run.complete" ||
    event.type === "run.completed" ||
    event.type === "run.failed" ||
    event.type === "session.run.finished"
  ) {
    break;
  }
}

SSE 事件类型

资料来源：packages/tandem-client-ts/README.md:45-75

打包与分发

npm 包结构

#### @frumu/tandem-ai - CLI 安装器

核心 npm 包，提供 tandem CLI 命令：

{
  "name": "tandem-ai",
  "version": "0.5.9",
  "description": "Tandem authority-layer runtime CLI installer/launcher",
  "bin": {
    "tandem": "bin/tandem.js"
  },
  "publishConfig": {
    "access": "public"
  }
}

#### @frumu/tandem-client - TypeScript SDK

类型安全的引擎客户端库：

{
  "name": "@frumu/tandem-client",
  "version": "0.5.9",
  "engines": {
    "node": ">=18"
  },
  "dependencies": {
    "zod": "^4.3.6"
  }
}

引擎构建

Rust 引擎可通过 Cargo 构建：

# 构建 tandem-engine
cargo build -p tandem-engine

# 运行测试
cargo test -p tandem-engine --no-run

# 构建发布版本
cargo build -p tandem-engine --release

# 打包发布
cargo package -p tandem-engine

资料来源：engine/README.md:1-30

企业版发布 (v0.5.11+)

v0.5.11 版本开始提供独立的企业版发行资产：

• Linux x64 二进制：包含浏览器自动化和企业级完整路由
• 专用 npm wrapper：用于托管 Sidecar 部署

资料来源：engine/README.md:10-18

内存与存储

存储层级

导入格式

引擎支持多种导入格式，核心是 OpenClaw 兼容格式：

# 导入 OpenClaw 格式
tandem-engine memory import --path ~/.openclaw --format openclaw

# 指定导入层级
tandem-engine memory import --path ./notes --tier global
tandem-engine memory import --path ./docs --tier project --project-id repo-123

# 同步删除操作
tandem-engine memory import --path ./docs --tier project --sync-deletes

数据文件位置

数据默认存储在以下位置之一：

1. tandem_core::resolve_shared_paths().canonical_root
2. ~/.tandem（回退位置）
3. 当前目录 ./.tandem（最后回退）

资料来源：crates/tandem-server/src/browser_parts/part02.rs:88-98

故障排查

常见问题

#### 1. Sidecar 二进制未找到

症状：browser_sidecar_not_found 错误

排查步骤：

1. 检查环境变量 TANDEM_BROWSER_SIDECAR
2. 验证托管路径 <root>/binaries/tandem-browser 存在
3. 确认文件系统权限

#### 2. 版本探测失败

症状：version probe failed 错误

排查步骤：

1. 手动执行 <sidecar_path> --version 验证可执行性
2. 检查 stderr 输出
3. 确认二进制架构匹配（x64/arm64）

#### 3. 内存占用过高

症状：Bun/JSC 进程空闲时内存超过 500MB

解决方案：引擎自动设置以下环境变量限制内存：

• BUN_JSC_forceRAMSize=268435456（256MB）
• BUN_GARBAGE_COLLECTOR_LEVEL=1

这些设置仅在变量未显式配置时生效。

#### 4. Provider 连接失败

排查矩阵：

日志调试

引擎日志输出到：

• 标准输出/标准错误（前台模式）
• Tauri 日志系统（桌面集成）

日志级别通过 RUST_LOG 环境变量控制：

RUST_LOG=debug tandem-engine serve

进程生命周期

启动序列

sequenceDiagram
    participant CLI as CLI / Main
    participant Core as tandem-core
    participant Server as tandem-server
    participant Sidecar as Browser Sidecar

    CLI->>Core: resolve_shared_paths()
    CLI->>Core: load_or_create_engine_api_token()
    Core-->>CLI: paths, token
    CLI->>Server: start_http_server()
    Server->>Server: load_capabilities()
    Server->>Sidecar: detect_sidecar_binary_path()
    Sidecar-->>Server: path_option
    Server->>Sidecar: probe_binary_version()
    alt sidecar found
        Server->>Sidecar: spawn_sidecar_process()
        Sidecar-->>Server: running
    else sidecar not found
        Server-->>Server: continue_without_browser
    end
    Server-->>CLI: HTTP server ready

优雅关闭

引擎支持以下关闭信号：

• SIGTERM / SIGINT：标准终止信号
• Windows Job Objects：进程树统一终止（通过 SetInformationJobObject）

资料来源：src-tauri/src/sidecar.rs:55-80

安全考量

零信任架构

• 网络范围：桌面运行时仅与 127.0.0.1 通信
• 凭证存储：Provider API Key 使用 AES-256-GCM 加密
• 文件系统：访问限于授权文件夹，敏感路径默认拒绝

凭证更新

Sidecar 进程启动时接收环境变量形式的凭证：

for (key, value) in env_vars.iter() {
    cmd.env(key, value);
}
cmd.env("TANDEM_API_TOKEN", &self.api_token);

每次 Provider 配置变更后，新凭证通过 Sidecar 重启生效。

相关文档

• 架构概述 — 完整的系统架构图
• 引擎通信协议 — Desktop/Engine 通信契约
• 引擎测试指南 — 单元测试和冒烟测试
• Tandem MCP 文档 — MCP 接口集成
• SDK 参考 — TypeScript 客户端完整 API

参见

• 许可证说明 — 混合许可模型说明
• 安全策略 — 威胁模型和漏洞报告流程
• Tandem 官方文档 — 用户文档门户

概述

Tandem SDK 是一套跨语言的 API 客户端库，用于与 Tandem Engine 运行时进行交互。SDK 不包含 tandem-engine 二进制文件，而是作为轻量级客户端，通过 HTTP/SSE 协议与运行中的引擎实例通信。

核心能力：

• 创建和管理会话（Sessions）
• 触发任务执行（Runs）
• 流式接收事件和响应（Streaming Events）
• 管理工具注册表和 MCP 连接
• 访问权限控制的记忆存储

SDK 与引擎的关系：

graph LR
    subgraph "SDK 层（客户端）"
        TS_SDK[TypeScript SDK<br/>@frumu/tandem-client]
        PY_SDK[Python SDK<br/>tandem-client]
    end
    
    subgraph "运行时层（服务端）"
        DESKTOP[桌面端内置 Sidecar]
        HEADLESS[tandem-engine serve<br/>headless 模式]
    end
    
    subgraph "模型层"
        MODELS[OpenAI / Anthropic /<br/>Ollama / OpenRouter]
    end
    
    TS_SDK -->|HTTP/SSE| DESKTOP
    PY_SDK -->|HTTP/SSE| DESKTOP
    TS_SDK -->|HTTP/SSE| HEADLESS
    PY_SDK -->|HTTP/SSE| HEADLESS
    DESKTOP --> MODELS
    HEADLESS --> MODELS

资料来源：README.md

概述

MCP（Model Context Protocol）集成是 Tandem 实现 AI 代理能力扩展的核心机制。通过 MCP 协议，Tandem 可以连接外部工具、数据源和服务，使 AI 代理能够执行多样化的任务，如网络研究、社区数据收集、文档检索等。

Tandem 的 MCP 集成采用零信任安全模型，所有 MCP 工具调用都经过权限验证和策略控制，确保敏感操作得到适当的授权审批。资料来源：docs/MCP_IMPROVEMENTS.md

核心架构

flowchart TD
    subgraph 核心层["Tandem 核心引擎"]
        MCP["MCP 运行时<br/>(tandem-runtime)"]
        Catalog["MCP 目录服务<br/>(mcp_catalog)"]
        Policy["工具策略引擎<br/>(tool_policy)"]
        Discovery["能力发现模块<br/>(mcp_ready)"]
    end

    subgraph MCP服务层["MCP 服务器连接"]
        TandemMCP["tandem_mcp<br/>文档检索工具"]
        Composio["composio<br/>第三方集成"]
        CustomMCP["自定义 MCP 服务器"]
    end

    subgraph 代理层["AI 代理"]
        Planner["任务规划代理"]
        Researcher["研究代理"]
        Synthesizer["综合代理"]
    end

    subgraph 外部服务["外部服务"]
        Reddit["Reddit API"]
        Notion["Notion API"]
        Web["Web 研究服务"]
    end

    Planner --> MCP
    Researcher --> MCP
    Synthesizer --> MCP
    MCP --> Catalog
    MCP --> Policy
    MCP --> Discovery
    Discovery -.->|能力列表| Planner
    
    MCP --> TandemMCP
    MCP --> Composio
    Composio --> Reddit
    TandemMCP --> Web
    
    Policy -.->|审批结果| MCP

MCP 目录与注册

Tandem 维护一个集中的 MCP 服务器目录，位于 crates/tandem-server/resources/mcp-catalog/index.json。该目录定义了所有可用的 MCP 服务器及其配置。

目录结构

资料来源：crates/tandem-server/resources/mcp-catalog/index.json

内置 MCP 服务器

Tandem 预置了以下 MCP 服务器连接：

资料来源：crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs:1-50

能力发现与请求流程

发现机制

Tandem 实现了完整的能力发现机制，确保 AI 代理在执行任务前了解可用的 MCP 工具。发现流程遵循以下原则：

1. 启动时扫描：引擎启动时扫描所有已配置的 MCP 服务器
2. 动态更新：当 MCP 服务器配置变更时，实时更新能力清单
3. 按需暴露：根据当前任务上下文，仅暴露相关工具能力

sequenceDiagram
    participant Agent as AI 代理
    participant Discovery as 能力发现模块
    participant Catalog as MCP 目录
    participant Runtime as MCP 运行时
    participant Policy as 策略引擎

    Agent->>Discovery: 请求任务所需能力
    Discovery->>Catalog: 查询可用工具列表
    Catalog-->>Discovery: 返回能力清单
    Discovery->>Policy: 验证能力访问权限
    Policy-->>Discovery: 返回授权结果
    Discovery-->>Agent: 返回已授权能力列表
    Agent->>Runtime: 调用工具
    Runtime->>Policy: 请求执行授权
    Policy-->>Runtime: 审批/拒绝

资料来源：guide/src/content/docs/mcp-capability-discovery-and-request-flow.md

请求授权流程

每个 MCP 工具调用都需要经过授权检查：

1. 代理发起工具调用请求
2. 策略引擎评估请求的风险级别
3. 根据配置决定自动批准或触发人工审批
4. 返回执行结果或审批请求

工作流集成

规划代理中的 MCP 使用

Tandem 的任务规划代理（agent_planner）在执行复杂研究任务时，会协调多个 MCP 工具的调用。以下是一个典型的研究-综合工作流：

资料来源：crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs:20-80

工作流步骤定义

每个工作流步骤包含以下元数据：

{
  "step_id": "generated_step_02",
  "kind": "research",
  "objective": "使用 mcp.tandem_mcp.search_docs 获取可靠的工作流设计文档。",
  "agent_role": "agent_docs_researcher",
  "input_refs": [],
  "depends_on": ["generated_step_01"],
  "output_contract": {
    "kind": "structured_json"
  }
}

桌面客户端配置

MCP 设置界面

在 Tandem 桌面应用的扩展设置中，可以管理 MCP 配置：

资料来源：src/i18n/locales/en/common.json

MCP 服务器配置

配置 MCP 服务器时，需要提供以下信息：

安全与策略

零信任安全模型

Tandem 对所有 MCP 交互实施零信任安全原则：

• 最小权限：代理仅获得完成任务所需的最小权限集
• 显式授权：每个敏感操作都需要显式授权
• 审计追踪：所有 MCP 调用都被记录用于审计

策略执行点

资料来源：docs/MCP_IMPROVEMENTS.md

浏览器自动化集成

Tandem 支持通过专用的 tandem-browser sidecar 实现浏览器自动化能力。这项功能依赖于 MCP 协议与浏览器的通信。

状态检查

浏览器自动化组件会执行以下状态检查：

资料来源：crates/tandem-server/src/browser_parts/part02.rs

Sidecar 自动下载

对于托管部署场景，Tandem 支持自动下载和管理浏览器 sidecar：

# 配置浏览器 sidecar 路径
TANDEM_BROWSER_SIDECAR=/custom/path/tandem-browser

# 或在配置文件中设置
browser:
  sidecar_path: /custom/path/tandem-browser

常见配置问题

MCP 连接失败排查

Sidecar 下载失败

当浏览器自动化 sidecar 下载失败时：

1. 检查 GitHub API 访问权限（可能存在速率限制）
2. 手动下载对应平台的 release asset
3. 通过 --browser-sidecar 参数指定本地路径

参考文档

• MCP 自动化代理指南
• MCP 能力发现与请求流程
• MCP 改进文档

另请参阅

• Tandem 架构概览
• 引擎运行时与 CLI 参考
• 工具策略配置
• 自动化工作流

概述

什么是 Pack

Pack 是一种引导式、可复制的工作流文件夹，专门设计用于实际生产任务。每个 Pack 包含启动指南、提示词模板和示例输入，使智能体能够快速适应特定领域的工作需求。

资料来源：agent-templates/PACKS.md:1-10

Pack 的核心价值

资料来源：src/i18n/locales/en/common.json

Pack 与其他扩展的关系

Tandem 提供了多种扩展机制来增强智能体能力：

graph TD
    A[Tandem 扩展系统] --> B[Pack 系统]
    A --> C[Skills 技能]
    A --> D[Plugins 插件]
    A --> E[MCP 模型上下文协议]
    A --> F[Modes 运行模式]
    
    B --> B1[引导式工作流]
    B --> B2[领域提示词]
    B --> B3[示例数据]
    
    C --> C1[特定任务能力]
    D --> D1[功能增强]
    E --> E1[外部工具集成]

Pack 作为用户可直接使用的高层次封装，专注于完整工作流的提供，而 Skills、Plugins 和 MCP 则提供了更细粒度的功能扩展能力。

Pack 目录结构

标准 Pack 结构

每个 Pack 文件夹遵循统一的标准结构：

{pack-name}/
├── PACK_INFO.md      # Pack 元数据配置
├── START_HERE.md     # 启动指南
├── prompts/          # 提示词模板目录
│   ├── main.md       # 主提示词
│   └── variants/     # 变体提示词
├── inputs/           # 示例输入目录
│   ├── sample1.md   # 示例输入 1
│   └── sample2.md   # 示例输入 2
└── configs/          # 可选配置文件
    └── workflow.json # 工作流配置

资料来源：agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md

PACK_INFO.md 元数据规范

功能概览

Tandem 企业级功能旨在满足以下核心需求：

资料来源：docs/ENTERPRISE_READINESS.md

企业架构

系统组件架构

graph TD
    subgraph "企业托管层"
        A[企业控制面板] --> B[tandem-engine]
        B --> C[治理引擎]
        B --> D[计划编译器]
    end
    
    subgraph "运行时层"
        B --> E[Sidecar 进程]
        E --> F[浏览器自动化]
        E --> G[工具执行]
    end
    
    subgraph "提供商层"
        H[OpenAI] 
        I[Anthropic]
        J[Ollama]
        K[Azure]
        L[其他提供商]
    end
    
    G --> H
    G --> I
    G --> J
    G --> K
    G --> L
    
    C --> M[合规策略检查]
    M --> N[EU AI Act]
    M --> O[企业数据策略]

资料来源：crates/tandem-enterprise-server/src/lib.rs

引擎服务架构

graph LR
    A[Engine CLI] -->|serve 命令| B[HTTP Server]
    B --> C[Provider Router]
    C --> D[Tool Registry]
    C --> E[Skill Manager]
    
    F[Enterprise Contract] -->|策略定义| G[Governance Engine]
    G -->|合规检查| H[Policy Gate]
    
    I[Sidecar Manager] -->|生命周期| J[Browser Automation]
    I -->|版本管理| K[Release Cache]

资料来源：engine/src/main.rs 和 crates/tandem-governance-engine/src/lib.rs

部署模式

Tandem 企业版支持多种部署模式，以适应不同的基础设施需求。

托管模式

托管模式适用于需要集中管理的组织：

# 安装托管引擎
npm i -g @frumu/tandem-engine

# 启动托管引擎服务
tandem-engine serve --hostname 0.0.0.0 --port 39731

资料来源：packages/tandem-engine

托管 Sidecar 模式

v0.5.11 新增了专用的托管 Sidecar npm 包装器，提供更好的云原生集成：

资料来源：src-tauri/src/sidecar_manager.rs

容器化部署

Tandem 提供 Docker Compose 配置用于容器化部署：

# 标准配置
services:
  engine:
    image: tandem-engine:latest
    ports:
      - "39731:39731"
    volumes:
      - ./secrets:/secrets
  
  panel:
    image: tandem-panel:latest
    ports:
      - "39734:39734"
    depends_on:
      - engine

资料来源：packages/tandem-control-panel/DOCKER.md

企业安全特性

零信任安全模型

Tandem 企业版实现了完整的零信任安全架构：

资料来源：README.md - 安全和隐私

凭证管理

sequenceDiagram
    participant User as 用户
    participant App as Tandem App
    participant Vault as 加密保险库
    participant Engine as tandem-engine
    
    User->>App: 输入 API Key
    App->>Vault: 加密存储
    App->>Engine: 请求 Token
    Engine->>Vault: 验证并解密
    Vault->>Engine: 返回凭证
    Engine->>Provider: AI 请求

资料来源：src-tauri/src/lib.rs - VaultState

合规支持

EU AI Act 合规

Tandem 企业版针对 EU AI Act 提供了专门的合规支持模块：

资料来源：docs/EU_AI_ACT_COMPLIANCE.md 和 docs/compliance/README.md

治理策略执行

企业治理引擎负责递归策略检查：

// 治理引擎核心接口
pub struct GovernancePolicy {
    pub allowed_providers: Vec<ProviderId>,
    pub denied_tools: Vec<ToolId>,
    pub audit_enabled: bool,
    pub compliance_mode: ComplianceLevel,
}

资料来源：crates/tandem-enterprise-contract/src/governance.rs

SDK 与 API 集成

TypeScript SDK

企业应用可以通过官方 SDK 集成 Tandem 引擎：

import { TandemClient } from "@frumu/tandem-client";

const client = new TandemClient({
  baseUrl: "http://localhost:39731",
  token: process.env.TANDEM_API_TOKEN,
});

// 创建会话
const sessionId = await client.sessions.create({
  title: "企业分析任务",
  directory: "/path/to/project",
});

// 异步执行任务
const { runId } = await client.sessions.promptAsync(
  sessionId,
  "分析代码库并生成报告"
);

// 事件流
for await (const event of client.stream(sessionId, runId)) {
  console.log(event);
}

资料来源：packages/tandem-client-ts/README.md

支持的 AI 提供商

Tandem 企业版支持以下 AI 提供商的无缝集成：

资料来源：engine/src/main.rs - SUPPORTED_PROVIDER_IDS

HTTP API 合约

企业服务通过标准 HTTP API 与引擎通信：

资料来源：contracts/http.md

版本与分发

企业版发布流程

v0.5.11 引入的企业版发布机制：

graph LR
    A[源码构建] --> B[标准构建]
    A --> C[企业版构建]
    
    C --> D[Linux x64 引擎]
    C --> E[浏览器自动化]
    C --> F[完整路由]
    
    D --> G[Enterprise Release Asset]
    E --> G
    F --> G
    
    G --> H[GitHub Releases]
    H --> I[@frumu/tandem-engine npm]

资料来源：src-tauri/src/sidecar_manager.rs - ENGINE_REPO

Sidecar 版本管理

企业版自动管理 Sidecar 二进制版本：

资料来源：src-tauri/src/sidecar_manager.rs

许可与开放核心

Tandem 采用开放核心许可证模式：

资料来源：README.md - 许可 和 docs/LICENSING.md

快速开始

企业托管部署

# 1. 安装 Tandem 企业工具链
npm i -g @frumu/tandem

# 2. 初始化控制面板
tandem install panel
tandem panel init

# 3. 生成 API Token
tandem-engine token generate

# 4. 配置环境变量
export TANDEM_API_TOKEN="your-token-here"

# 5. 启动引擎
tandem-engine serve --hostname 0.0.0.0 --port 39731

资料来源：packages/tandem-control-panel/README.md

本地控制面板

# 生成可编辑的控制面板
npm create tandem-panel@latest my-enterprise-panel
cd my-enterprise-panel
npm install
npm run dev

资料来源：README.md - 可编辑应用脚手架

常见问题与故障排除

Sidecar 未找到

错误: browser_sidecar_not_found
建议: 
  - 安装 tandem-browser: npm i -g @frumu/tandem-browser
  - 或设置环境变量: TANDEM_BROWSER_SIDECAR
  - 或配置: browser.sidecar_path

资料来源：crates/tandem-server/src/browser_parts/part02.rs

引擎连接失败

资料来源：engine/src/main.rs - STATUS_EXAMPLES

延伸阅读

Pitfall Log / 踩坑日志

项目：frumu-ai/tandem

摘要：发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Workflow automation-v2-e42950f5-9d9e-483c-a8da-3d568f98dd46 failed at research_sources: automation run blocked by upstr…。

1. 安装坑 · 来源证据：Workflow automation-v2-e42950f5-9d9e-483c-a8da-3d568f98dd46 failed at research_sources: automation run blocked by upstr…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Workflow automation-v2-e42950f5-9d9e-483c-a8da-3d568f98dd46 failed at research_sources: automation run blocked by upstream node outcome
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d7998fa92e2f4cae91e7040b71c38bf9 | https://github.com/frumu-ai/tandem/issues/38 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 配置坑 · 来源证据：Workflow automation-v2-1f391975-681a-4041-94b5-8845dfe3307b failed at execute_goal: automation run blocked by upstream…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-1f391975-681a-4041-94b5-8845dfe3307b failed at execute_goal: automation run blocked by upstream node outcome
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b3856a6aadb944f0977020d9841025a5 | https://github.com/frumu-ai/tandem/issues/28 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Workflow automation-v2-65662b51-ab4e-4348-8349-ea10e7b634c6 failed at synthesize_report: automation run failed from nod…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-65662b51-ab4e-4348-8349-ea10e7b634c6 failed at synthesize_report: automation run failed from node outcomes: synthesize_report
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8c10aeb4b1874bf39ce9347480864a20 | https://github.com/frumu-ai/tandem/issues/1396 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：Workflow automation-v2-7a7374b2-16bc-416d-bc38-81edb5be7050 failed at assess: automation run failed from node outcomes:…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-7a7374b2-16bc-416d-bc38-81edb5be7050 failed at assess: automation run failed from node outcomes: assess
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8fda7ba929c344aa863117d5164cb1e5 | https://github.com/frumu-ai/tandem/issues/32 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at assess_reddit_activity: automation run blocked by…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at assess_reddit_activity: automation run blocked by upstream node outcome
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_55cc9e60475944d78cd5af4305d0f1ef | https://github.com/frumu-ai/tandem/issues/35 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 配置坑 · 来源证据：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at search_agents_keep: automation node `search_agent…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at search_agents_keep: automation node search_agents_keep timed out after 180000 ms
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fd1ae3d40b5d4c97b8e86767f85466b4 | https://github.com/frumu-ai/tandem/issues/40 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 配置坑 · 来源证据：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at search_multi_agent: automation node `search_multi…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at search_multi_agent: automation node search_multi_agent timed out after 180000 ms
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9f60d02de0544ffcbacc2c984db5ccaf | https://github.com/frumu-ai/tandem/issues/36 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据：Workflow automation-v2-a776164f-06ef-440d-af54-748186205aef failed at analyze_findings: provider stream chunk error: er…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-a776164f-06ef-440d-af54-748186205aef failed at analyze_findings: provider stream chunk error: error decoding response body
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7f64d78b216242bd8b6108520a197aff | https://github.com/frumu-ai/tandem/issues/49 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 配置坑 · 来源证据：Workflow automation-v2-a776164f-06ef-440d-af54-748186205aef failed at research_sources: automation run blocked by upstr…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-a776164f-06ef-440d-af54-748186205aef failed at research_sources: automation run blocked by upstream node outcome
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_bb5c682d661c42d7b568ae17b9e8e0f9 | https://github.com/frumu-ai/tandem/issues/41 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

10. 配置坑 · 来源证据：Workflow automation-v2-b2d6ef35-c222-4027-9251-40adca379cf3 failed at collect_recent_files: required output `.tandem/ru…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-b2d6ef35-c222-4027-9251-40adca379cf3 failed at collect_recent_files: required output `.tandem/runs/automation-v2-run-593051dc-78bf-4927-…
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fed96ae76b684a42b4e5a90f3f421837 | https://github.com/frumu-ai/tandem/issues/34 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

11. 配置坑 · 来源证据：Workflow automation-v2-bba896a6-0036-4d7a-981f-be803affaa78 failed at assess_tmp_git_repositories: automation run block…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-bba896a6-0036-4d7a-981f-be803affaa78 failed at assess_tmp_git_repositories: automation run blocked by upstream node outcome
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ae2338d77fe04260af3a7dbdae5c45df | https://github.com/frumu-ai/tandem/issues/31 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

12. 配置坑 · 来源证据：Workflow automation-v2-e42950f5-9d9e-483c-a8da-3d568f98dd46 failed at analyze_findings: required output `.tandem/runs/a…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Workflow automation-v2-e42950f5-9d9e-483c-a8da-3d568f98dd46 failed at analyze_findings: required output `.tandem/runs/automation-v2-run-6f7ba9ed-df91-4261-9271…
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9e491d1989bf4812be296a05d006b876 | https://github.com/frumu-ai/tandem/issues/1336 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:ac.tandem/docs-mcp:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/ac.tandem%2Fdocs-mcp/versions/0.3.2 | README/documentation is current enough for a first validation pass.

14. 运行坑 · 来源证据：Workflow automation-v2-0af90431-6b5e-40fd-8b9d-7b982770a851 failed at automation_v2: automation run paused after no pro…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Workflow automation-v2-0af90431-6b5e-40fd-8b9d-7b982770a851 failed at automation_v2: automation run paused after no provider activity for at least 300s
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_add4a18d3c9845a387fb3dc35428ae3a | https://github.com/frumu-ai/tandem/issues/30 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

15. 运行坑 · 来源证据：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at automation_v2: automation run paused after no pro…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Workflow automation-v2-9ee33834-bf6d-4f86-acb3-3cd41d9cef19 failed at automation_v2: automation run paused after no provider activity for at least 300s
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a823ae57304c43e1b6a6ff27911e34dc | https://github.com/frumu-ai/tandem/issues/29 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

16. 运行坑 · 来源证据：Workflow automation-v2-ac727d53-7f94-4c8d-935e-5d615fe5db38 failed at automation_v2: automation run paused after no pro…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Workflow automation-v2-ac727d53-7f94-4c8d-935e-5d615fe5db38 failed at automation_v2: automation run paused after no provider activity for at least 300s
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e0012b3de456436babf130e167def424 | https://github.com/frumu-ai/tandem/issues/33 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:ac.tandem/docs-mcp:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/ac.tandem%2Fdocs-mcp/versions/0.3.2 | last_activity_observed missing

18. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:ac.tandem/docs-mcp:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/ac.tandem%2Fdocs-mcp/versions/0.3.2 | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:ac.tandem/docs-mcp:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/ac.tandem%2Fdocs-mcp/versions/0.3.2 | no_demo; severity=medium

20. 安全/权限坑 · 来源证据：[ACA Slice Parent] Phase 2 - Isolate runtime execution, secrets, artifacts, and streams

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[ACA Slice Parent] Phase 2 - Isolate runtime execution, secrets, artifacts, and streams
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3ad20ab8b4cf40c7af6095e044e19fcb | https://github.com/frumu-ai/tandem/issues/1442 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:ac.tandem/docs-mcp:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/ac.tandem%2Fdocs-mcp/versions/0.3.2 | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:ac.tandem/docs-mcp:0.3.2 | https://registry.modelcontextprotocol.io/v0.1/servers/ac.tandem%2Fdocs-mcp/versions/0.3.2 | release_recency=unknown