# https://github.com/frumu-ai/tandem 项目说明书
生成时间：2026-05-26 08:33:38 UTC
## 目录
- [Tandem 概述](#home)
- [系统架构](#architecture)
- [核心概念](#core-concepts)
- [快速开始](#quickstart)
- [桌面应用](#desktop-app)
- [引擎 CLI 与无头服务](#engine-cli)
- [SDK 参考文档](#sdk-reference)
- [MCP 集成](#mcp-integration)
- [智能体 Pack 系统](#agent-packs)
- [企业级功能](#enterprise-features)
## Tandem 概述
### 相关页面
相关主题：[系统架构](#architecture), [快速开始](#quickstart), [核心概念](#core-concepts)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
- [engine/src/main.rs](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
- [src-tauri/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
- [src-tauri/src/sidecar.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
- [src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
- [packages/tandem-client-ts/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
- [packages/tandem-client-ts/src/wire/index.ts](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/src/wire/index.ts)
- [engine/README.md](https://github.com/frumu-ai/tandem/blob/main/engine/README.md)
# Tandem 概述
Tandem 是一个本地优先、零信任的 AI 工作空间运行时基础设施。它不仅仅是聊天界面或代理框架，而是 AI 代理在从回答问题到在企业系统中执行操作的过程中，所依赖的执行运行时。Tandem 将意图转化为受治理的工具执行，确保每一次操作都有审计追踪。
资料来源：[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]()
## 架构概览
```mermaid
graph TB
subgraph "客户端层"
TUI["TUI 终端界面
tandem-tui"]
Desktop["桌面应用
Tauri App"]
Panel["Web 控制面板
Control Panel"]
SDK["SDK 客户端
TypeScript/Python"]
end
subgraph "引擎运行时"
Engine["tandem-engine
Headless HTTP/SSE 运行时"]
Sidecar["tandem-browser
浏览器自动化 Sidecar"]
end
subgraph "核心子系统"
Memory["Memory System
记忆系统"]
Tools["Tool Registry
工具注册表"]
MCP["MCP Connectors
MCP 连接器"]
Governance["Governance Engine
治理引擎"]
end
subgraph "提供商层"
Providers["Provider Registry
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
```
### 组件职责
| 组件 | 类型 | 职责 | 源码位置 |
|------|------|------|----------|
| `tandem-engine` | Rust 二进制 | Headless HTTP/SSE 运行时，执行 AI 任务 | [engine/src/main.rs]() |
| `tandem-browser` | Sidecar 二进制 | 浏览器自动化能力 | [src-tauri/src/sidecar.rs]() |
| Tauri Desktop | 桌面应用 | 本地桌面入口，带 Vault 加密存储 | [src-tauri/src/lib.rs]() |
| @frumu/tandem-client | TypeScript SDK | HTTP API 客户端封装 | [packages/tandem-client-ts/README.md]() |
资料来源：[engine/src/main.rs:1-50]()
## 支持的 AI 提供商
Tandem 采用提供商无关（Provider agnostic）的设计，支持 12 种以上的 AI 提供商：
```mermaid
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"]
```
| 提供商 ID | 说明 | 配置方式 |
|-----------|------|----------|
| `openai` | OpenAI GPT 系列 | API Key |
| `openrouter` | OpenRouter 聚合 | API Key |
| `anthropic` | Anthropic Claude 系列 | API Key |
| `ollama` | 本地 Ollama | 端点配置 |
| `groq` | Groq 加速推理 | API Key |
| `mistral` | Mistral AI | API Key |
| `together` | Together AI | API Key |
| `azure` | Azure OpenAI | Azure 凭据 |
| `bedrock` | AWS Bedrock | AWS 凭据 |
| `vertex` | Google Vertex AI | GCP 凭据 |
| `copilot` | GitHub Copilot | OAuth 认证 |
| `cohere` | Cohere | API Key |
资料来源：[engine/src/main.rs:16-28]()
## 引擎 CLI 与命令
`tandem-engine` 是 Tandem 的核心命令行工具，提供多种运行模式：
```bash
# 启动 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
```
### 服务命令示例
| 命令 | 用途 | 环境变量 |
|------|------|----------|
| `serve` | 启动 HTTP/SSE 服务 | `TANDEM_ENGINE_HOST`, `TANDEM_ENGINE_PORT` |
| `status` | 健康检查 | `TANDEM_ENGINE_HOST`, `TANDEM_ENGINE_PORT` |
| `run` | 单次任务执行 | `--provider`, `--model` |
| `tool` | 工具直接调用 | `--json` |
| `memory` | 记忆导入导出 | `--path`, `--format`, `--tier` |
资料来源：[engine/src/main.rs:30-60]()
## Sidecar 架构
Tandem 采用 Sidecar 模式管理浏览器自动化能力。桌面应用通过进程间通信与 `tandem-browser` sidecar 交互。
```mermaid
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 的版本追踪、下载和更新：
| 功能 | 说明 | 源码 |
|------|------|------|
| 版本检测 | 探测已安装 sidecar 版本 | [src-tauri/src/sidecar.rs:45-60]() |
| 版本更新 | 从 GitHub releases 检查更新 | [src-tauri/src/sidecar_manager.rs:20-40]() |
| 进程管理 | Windows Job Objects / Unix fork | [src-tauri/src/sidecar.rs:25-40]() |
| 健康检查 | 版本探针和状态报告 | [crates/tandem-server/src/browser_parts/part02.rs]() |
资料来源：[src-tauri/src/sidecar.rs:1-60]()
## 安全与隐私
Tandem 采用零信任安全模型，在多个层面保护用户数据和系统安全：
| 安全特性 | 实现方式 | 说明 |
|----------|----------|------|
| 遥测零追踪 | 无分析/追踪代码 | Tandem 不包含任何分析或回拨遥测 |
| 提供商流量隔离 | 仅发送至配置端点 | AI 请求内容只发送到用户配置的提供商 |
| 网络范围控制 | 桌面运行时仅通信本地 sidecar | 与 `127.0.0.1` 和配置的端点通信 |
| 凭据加密存储 | AES-256-GCM | 提供商密钥使用 AES-256-GCM 加密 |
| 文件系统安全 | 作用域访问 | 访问仅限于授权文件夹，敏感路径默认拒绝 |
### Vault 状态管理
桌面应用中的 Vault 模块管理加密密钥的生命周期：
```rust
pub struct VaultState {
pub unlocked: RwLock, // Vault 是否解锁
pub master_key: RwLock>>, // 解密的主密钥
pub app_data_dir: PathBuf, // 应用数据目录
}
```
资料来源：[src-tauri/src/lib.rs:45-60]()
## 客户端 SDK
### TypeScript / Node.js 客户端
`@frumu/tandem-client` 是 Tandem 的官方 TypeScript SDK，支持 Node 18+：
```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"
);
// 3. 流式接收响应
for await (const event of client.stream(sessionId, runId)) {
if (event.type === "session.response") {
process.stdout.write(String(event.properties.delta ?? ""));
}
}
```
### 客户端配置选项
| 选项 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `baseUrl` | `string` | 是 | - | Tandem 引擎地址 |
| `token` | `string` | 是 | - | 引擎 API Token |
| `timeoutMs` | `number` | 否 | 20000 | 请求超时（毫秒） |
### 浏览器状态响应
SDK 提供了完整的类型定义来描述引擎状态：
```typescript
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 支持多种部署模式，可根据需求选择：
```mermaid
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"]
```
### 快速入门指南
| 场景 | 推荐方式 | 命令 |
|------|----------|------|
| 桌面用户 | Tauri 应用 | 下载 [tandem.ac](https://tandem.ac/) |
| Web 控制面板 | npm 全局安装 | `npm i -g @frumu/tandem && tandem install panel && tandem panel init` |
| 纯引擎 | npm 全局安装 | `npm i -g @frumu/tandem && tandem-engine serve` |
| 终端界面 | TUI | `npm i -g @frumu/tandem-tui && tandem-tui` |
| 自定义集成 | SDK | `npm install @frumu/tandem-client` |
资料来源：[packages/tandem-control-panel/README.md:1-30]()
## 许可证说明
Tandem 采用开放核心（Open Core）许可模式：
| 组件 | 许可证 | 说明 |
|------|--------|------|
| 运行时、协议、SDK、本地工具 | MIT / Apache-2.0 | permissive 开源许可 |
| tandem-plan-compiler | BUSL-1.1 | 任务/计划编译器，商业源码可用许可 |
| tandem-governance-engine | BUSL-1.1 | 递归治理引擎，商业源码可用许可 |
详细许可信息请参阅 [docs/LICENSING.md](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。
| 版本 | 发布日期 | 关键特性 |
|------|----------|----------|
| v0.5.11 | 2026-05-25 | 企业引擎分发路径、Linux x64 二进制、npm wrapper |
| v0.5.9 | 2026-04-xx | SDK 稳定版 |
资料来源：[README.md:社区上下文]()
## 相关文档
- [架构设计](ARCHITECTURE.md) - Tandem 完整架构文档
- [引擎 CLI 参考](docs/ENGINE_CLI.md) - 命令行工具完整参考
- [引擎通信协议](docs/ENGINE_COMMUNICATION.md) - 桌面/运行时通信契约
- [MCP 集成](https://tandem.ac/docs-mcp) - Model Context Protocol 连接指南
- [AI 运行时基础设施](docs/AI_RUNTIME_INFRASTRUCTURE.md) - 深度技术文档
- [企业就绪](docs/ENTERPRISE_READINESS.md) - 企业部署指南
- [安全模型](SECURITY.md) - 威胁模型和安全报告流程
---
## 系统架构
### 相关页面
相关主题：[Tandem 概述](#home), [核心概念](#core-concepts), [桌面应用](#desktop-app), [引擎 CLI 与无头服务](#engine-cli)
相关源码文件
以下源码文件用于生成本页说明：
- [ARCHITECTURE.md](https://github.com/frumu-ai/tandem/blob/main/ARCHITECTURE.md)
- [contracts/http.md](https://github.com/frumu-ai/tandem/blob/main/contracts/http.md)
- [contracts/events.json](https://github.com/frumu-ai/tandem/blob/main/contracts/events.json)
- [manifests/components/tandem-engine.yaml](https://github.com/frumu-ai/tandem/blob/main/manifests/components/tandem-engine.yaml)
- [manifests/components/tandem-desktop.yaml](https://github.com/frumu-ai/tandem/blob/main/manifests/components/tandem-desktop.yaml)
- [crates/tandem-core/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-core/src/lib.rs)
- [src-tauri/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
- [src-tauri/src/sidecar.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
- [src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
- [engine/src/main.rs](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
- [packages/tandem-client-ts/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
# 系统架构
Tandem 是一个本地优先、零信任的 AI 工作空间应用程序，采用分布式进程架构设计。本页面详细介绍 Tandem 的系统架构、核心组件、进程间通信机制以及各组件的职责划分。
## 架构概览
Tandem 采用多进程架构，将桌面应用、引擎运行时和浏览器自动化能力解耦为独立进程，通过本地 HTTP/SSE API 进行通信。这种设计实现了关注点分离，使得各个组件可以独立开发、部署和扩展。
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
## 核心组件
### 桌面端主进程
桌面端采用 Tauri 框架构建，负责整个应用的生命周期管理、状态协调和用户界面呈现。
| 组件 | 源码位置 | 职责 |
|------|----------|------|
| VaultState | [lib.rs:60-75](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs) | 保管库状态管理，存储主密钥和锁定状态 |
| SidecarManager | [sidecar.rs:1-80](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs) | Sidecar 进程启动、生命周期管理 |
| SidecarBinaryManager | [sidecar_manager.rs:1-60](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs) | 二进制版本跟踪、下载和更新 |
| SkillTemplates | [skill_templates.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/skill_templates.rs) | 技能模板管理 |
| ToolPolicy | [tool_policy.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/tool_policy.rs) | 工具调用策略控制 |
主进程通过 `Manager` trait 与 Tauri 运行时交互，并使用 `StoreExt` 扩展进行持久化状态存储：
```rust
use tauri::{Manager};
use tauri_plugin_store::StoreExt;
```
资料来源：[src-tauri/src/lib.rs:35-45](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
### Engine 引擎运行时
`tandem-engine` 是 Tandem 的核心推理引擎，以独立进程运行，提供 HTTP/SSE API 接口。
#### CLI 子命令
| 命令 | 功能 | 示例 |
|------|------|------|
| `serve` | 启动 HTTP/SSE 运行时 | `tandem-engine serve --hostname 0.0.0.0 --port 39731` |
| `status` | 检查引擎健康状态 | `tandem-engine status --hostname 127.0.0.1 --port 39731` |
| `run` | 单次提示执行 | `tandem-engine run "Summarize this" --provider openrouter --model openai/gpt-4o-mini` |
| `tool` | 直接工具执行 | `tandem-engine tool --json @payload.json` |
| `providers` | 列出支持的提供商 | `tandem-engine providers` |
| `memory` | 内存导入导出 | `tandem-engine memory import --path ~/.openclaw --format openclaw` |
资料来源：[engine/src/main.rs:30-80](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
#### 支持的 AI 提供商
引擎支持 12 个主流 AI 提供商，通过 `ProviderRegistry` 进行统一管理：
| 提供商 ID | 说明 |
|-----------|------|
| `openai` | OpenAI GPT 系列 |
| `openrouter` | OpenRouter 聚合服务 |
| `anthropic` | Anthropic Claude 系列 |
| `ollama` | 本地 Ollama 部署 |
| `groq` | Groq 推理加速 |
| `mistral` | Mistral AI |
| `together` | Together AI |
| `azure` | Azure OpenAI |
| `bedrock` | AWS Bedrock |
| `vertex` | Google Cloud Vertex AI |
| `copilot` | GitHub Copilot |
| `cohere` | Cohere |
```rust
const SUPPORTED_PROVIDER_IDS: [&str; 12] = [
"openai", "openrouter", "anthropic", "ollama", "groq",
"mistral", "together", "azure", "bedrock", "vertex",
"copilot", "cohere",
];
```
资料来源：[engine/src/main.rs:18-27](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
### 浏览器自动化组件
`tandem-browser` 是独立的浏览器自动化 Sidecar，通过 Playwright 提供浏览器控制能力。
#### 状态检测逻辑
```mermaid
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. 本地浏览器是否可用
```rust
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](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/browser_parts/part02.rs)
## 进程间通信
### HTTP/SSE 协议
引擎通过 HTTP REST API 和 Server-Sent Events (SSE) 提供双向通信能力。
```mermaid
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 使用示例
```typescript
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](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
### API 参数配置
| 选项 | 类型 | 说明 |
|------|------|------|
| `baseUrl` | `string` | 引擎服务地址，默认 `http://localhost:39731` |
| `token` | `string` | 引擎 API 令牌 |
| `timeout` | `number` | 请求超时时间（毫秒） |
| `retries` | `number` | 重试次数 |
### Sidecar 进程管理
桌面端通过进程管理机制启动和控制 Engine Sidecar：
#### Windows 进程隔离
在 Windows 平台上，使用 Job Objects 实现进程隔离和资源控制：
```rust
#[cfg(windows)]
use windows_sys::Win32::System::JobObjects::{
AssignProcessToJobObject, CreateJobObjectW, JobObjectExtendedLimitInformation,
SetInformationJobObject, JOBOBJECT_EXTENDED_LIMIT_INFORMATION,
JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
};
```
#### 进程启动参数
```rust
std::process::Command::new(path)
.arg("--version")
.output()
```
Sidecar 使用子进程方式启动，支持通过环境变量配置连接参数：
| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `TANDEM_ENGINE_HOST` | `127.0.0.1` | 引擎主机地址 |
| `TANDEM_ENGINE_PORT` | `39731` | 引擎服务端口 |
| `TANDEM_BROWSER_SIDECAR` | 自动检测 | 浏览器 Sidecar 路径 |
资料来源：[src-tauri/src/sidecar.rs:20-40](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
## 版本管理与更新
### Sidecar 二进制管理器
SidecarBinaryManager 负责从 GitHub releases 自动下载和更新二进制文件。
```mermaid
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
```
#### 版本检查配置
| 常量 | 值 | 说明 |
|------|-----|------|
| `ENGINE_REPO` | `frumu-ai/tandem` | GitHub 仓库 |
| `MIN_BINARY_SIZE` | `100 * 1024` | 最小二进制大小（100KB） |
| `RELEASES_PER_PAGE` | `20` | 每次请求的发布数 |
| `MAX_RELEASE_PAGES` | `5` | 最大请求页数 |
| `RELEASE_CHECK_INTERVAL_SECS` | `6 * 60 * 60` | 检查间隔（6小时） |
```rust
const RELEASE_REQUEST_TIMEOUT_SECS: u64 = 8;
const MIN_BINARY_SIZE: u64 = 100 * 1024; // 100KB minimum
```
资料来源：[src-tauri/src/sidecar_manager.rs:10-30](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
## 核心模块架构
### Tandem Core 库
`tandem-core` 是共享的基础库，提供核心类型定义和工具函数：
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-core/src/lib.rs)
### 技能系统
技能（Skills）系统允许扩展 Tandem 的能力边界：
| 组件 | 说明 |
|------|------|
| `SkillInfo` | 技能元数据 |
| `SkillContent` | 技能内容定义 |
| `SkillLocation` | 技能存储位置 |
| `SkillTemplateInfo` | 技能模板信息 |
```rust
use tandem_skills::{SkillContent, SkillInfo, SkillLocation, SkillTemplateInfo};
```
资料来源：[src-tauri/src/sidecar.rs:15-18](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
### 模式系统
模式（Modes）定义了不同的运行策略，包括 Plan Mode 和 Immediate Mode：
| 模式 | 行为 |
|------|------|
| Plan Mode | 先规划后执行，生成可审查的工作流 |
| Immediate | 直接执行，快速响应 |
## 部署架构
### 桌面端部署
```mermaid
graph LR
A[Tandem 桌面应用] --> B[启动 Sidecar]
B --> C[tandem-engine]
B --> D[tandem-browser]
C --> E[Web 控制面板]
E --> F[浏览器访问 :39734]
```
### 企业版部署
v0.5.11 版本引入了企业版引擎分发路径：
| 组件 | 说明 |
|------|------|
| `tandem-engine` (企业版) | 包含浏览器自动化和企业级路由的 Linux x64 二进制 |
| `@frumu/tandem` (npm) | 企业版 Sidecar 的专用 npm 包装器 |
```bash
# 企业版安装
npm install -g @frumu/tandem
```
### Docker 部署
提供了 Docker Compose 配置，支持容器化部署：
```yaml
# 关键配置
engine:
port: 39731
token_file: ./secrets/tandem_api_token
panel:
port: 39734
depends_on: engine
```
资料来源：[packages/tandem-control-panel/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/README.md)
## 安全架构
### 零信任安全模型
Tandem 实现零信任安全架构，所有组件间通信都需要显式认证：
| 安全措施 | 实现 |
|----------|------|
| API 令牌认证 | 通过 `engine_api_token_file_path()` 管理 |
| 进程隔离 | Windows Job Objects，Linux cgroups |
| 加密存储 | AES-256-GCM 加密提供商密钥 |
| 文件系统隔离 | 访问仅限于授权文件夹 |
```rust
pub struct VaultState {
pub unlocked: RwLock,
pub master_key: RwLock>>,
pub app_data_dir: std::path::PathBuf,
}
```
资料来源：[src-tauri/src/lib.rs:55-65](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
### 网络范围
| 组件 | 通信范围 | 说明 |
|------|----------|------|
| 桌面运行时 → Sidecar | `127.0.0.1` | 仅本地通信 |
| Sidecar → AI 提供商 | 互联网 | 取决于配置的提供商 |
| Sidecar → 本地 Ollama | 本地网络 | 支持私有部署 |
### 遥测与隐私
- **无遥测**：不包含分析或回传遥测
- **提供商流量**：AI 请求仅发送到用户配置的端点
- **更新检查**：仅 GitHub 端点
资料来源：[README.md 安全和隐私部分](https://github.com/frumu-ai/tandem/blob/main/README.md)
## 技术栈概览
| 层级 | 技术 | 源码位置 |
|------|------|----------|
| 桌面框架 | Tauri | `src-tauri/` |
| 核心引擎 | Rust + Tokio | `engine/src/` |
| Web 控制面板 | React + TypeScript | `packages/tandem-control-panel/` |
| SDK | TypeScript / Python | `packages/tandem-client-ts/` |
| 浏览器自动化 | Playwright | `tandem-browser/` |
### 引擎包结构
```mermaid
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]
```
构建命令：
```bash
# 本地开发
cargo build -p tandem-engine
# 发布打包
cargo build --release -p tandem-engine
```
资料来源：[engine/README.md](https://github.com/frumu-ai/tandem/blob/main/engine/README.md)
## 相关文档
- [ENGINE_CLI.md](https://github.com/frumu-ai/tandem/blob/main/docs/ENGINE_CLI.md) - 引擎 CLI 参考手册
- [ENGINE_COMMUNICATION.md](https://github.com/frumu-ai/tandem/blob/main/docs/ENGINE_COMMUNICATION.md) - 桌面/运行时通信契约
- [ENGINE_TESTING.md](https://github.com/frumu-ai/tandem/blob/main/docs/ENGINE_TESTING.md) - 引擎测试与冒烟检查
- [SECURITY.md](https://github.com/frumu-ai/tandem/blob/main/SECURITY.md) - 安全威胁模型与报告流程
- [LICENSING.md](https://github.com/frumu-ai/tandem/blob/main/docs/LICENSING.md) - 混合许可证说明
---
## 核心概念
### 相关页面
相关主题：[系统架构](#architecture), [MCP 集成](#mcp-integration), [企业级功能](#enterprise-features)
相关源码文件
以下源码文件用于生成本页说明：
- [engine/src/main.rs](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
- [src-tauri/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
- [src-tauri/src/sidecar.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
- [src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
- [packages/tandem-client-ts/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
- [README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
# 核心概念
Tandem 是一个本地优先、零信任的 AI 工作空间应用，其核心架构围绕自主代理引擎（tandem-engine）构建，支持多模型提供商路由、工具调用策略管理、内存系统和浏览器自动化能力。资料来源：[README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
本页面介绍 Tandem 的核心概念、架构组件、运行模式以及各子系统之间的协作关系，帮助开发者理解系统的设计哲学和使用方式。
---
## 系统架构概览
Tandem 采用**桌面运行时 + 引擎后端**的双层架构设计。桌面应用（基于 Tauri）作为控制前端，而核心 AI 推理和工具执行由独立的 `tandem-engine` 进程处理。资料来源：[src-tauri/src/lib.rs:1-50](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
```mermaid
graph TD
subgraph Desktop["桌面运行时 (Tauri)"]
UI["用户界面"]
Vault["保险库状态"]
SidecarManager["Sidecar 管理器"]
ToolProxy["工具代理"]
Orchestrator["编排器"]
end
subgraph Engine["引擎后端 (tandem-engine)"]
HTTP["HTTP/SSE 服务"]
ProviderRegistry["提供商注册表"]
ToolRegistry["工具注册表"]
MemorySystem["内存系统"]
PlanCompiler["计划编译器"]
end
subgraph External["外部组件"]
AI["AI 提供商 API"]
MCP["MCP 服务器"]
Browser["浏览器自动化"]
FileSystem["文件系统"]
end
UI <--> SidecarManager
SidecarManager <--> Engine
Orchestrator <--> ToolProxy
Engine --> ProviderRegistry
Engine --> ToolRegistry
Engine --> MemorySystem
Engine --> External.AI
Engine --> External.MCP
Engine --> External.Browser
Engine --> External.FileSystem
style Desktop fill:#e1f5fe
style Engine fill:#fff3e0
style External fill:#f3e5f5
```
### 架构设计原则
| 原则 | 说明 | 实现方式 |
|------|------|----------|
| **本地优先** | 数据不离开本地环境 | sidecar 运行在 `127.0.0.1`，敏感文件访问需要用户授权 |
| **零信任安全** | 所有操作需要显式授权 | 权限系统基于 Capabilities，密钥使用 AES-256-GCM 加密 |
| **提供商无关** | 支持多种 AI 模型提供商 | 通过 ProviderRegistry 抽象层统一接口 |
| **可扩展工具** | 支持 MCP、自定义工具和插件 | ToolRegistry 动态加载和策略控制 |
资料来源：[README.md - Security and privacy](https://github.com/frumu-ai/tandem/blob/main/README.md)
---
## 核心组件详解
### 2.1 tandem-engine 引擎
`tandem-engine` 是 Tandem 的核心运行时，是一个无头（headless）的 AI 代理后端。它通过 HTTP/SSE 协议提供服务，支持即时执行和异步运行两种模式。资料来源：[engine/src/main.rs:1-80](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
#### 引擎 CLI 命令
引擎提供以下主要命令：
```bash
# 启动 HTTP/SSE 服务
tandem-engine serve --hostname 127.0.0.1 --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 tool --json @payload.json
cat payload.json | tandem-engine tool --json -
# 查看支持的提供商列表
tandem-engine providers
# 导入记忆数据
tandem-engine memory import --path ~/.openclaw --format openclaw
```
#### 支持的 AI 提供商
引擎内置支持 **12 种** AI 提供商，通过 `ProviderRegistry` 进行统一管理：资料来源：[engine/src/main.rs:12-26](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
| 提供商 ID | 说明 | 配置方式 |
|-----------|------|----------|
| `openai` | OpenAI GPT 系列 | API Key |
| `openrouter` | OpenRouter 聚合平台 | API Key |
| `anthropic` | Anthropic Claude 系列 | API Key |
| `ollama` | 本地 Ollama 模型 | 本地端点 |
| `groq` | Groq 快速推理 | API Key |
| `mistral` | Mistral AI | API Key |
| `together` | Together AI | API Key |
| `azure` | Azure OpenAI Service | Azure 凭证 |
| `bedrock` | AWS Bedrock | AWS 凭证 |
| `vertex` | Google Vertex AI | GCP 凭证 |
| `copilot` | GitHub Copilot | OAuth |
| `cohere` | Cohere | API Key |
---
### 2.2 Sidecar 管理器
Sidecar 是 Tandem 桌面应用与引擎后端之间的通信桥梁，负责管理 `tandem-engine` 进程的生命周期。资料来源：[src-tauri/src/sidecar.rs:1-60](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
#### Sidecar 生命周期管理
```mermaid
stateDiagram-v2
[*] --> Stopped: 应用启动
Stopped --> Starting: 启动引擎
Starting --> Running: 进程成功
Starting --> Failed: 启动失败
Running --> Updating: 检测到更新
Updating --> Restarting: 下载完成
Restarting --> Running: 重启成功
Running --> Stopping: 用户关闭
Stopping --> Stopped: 进程终止
Failed --> Starting: 重试
```
#### Sidecar 配置与环境变量
Sidecar 进程通过以下环境变量和配置进行初始化：资料来源：[src-tauri/src/sidecar.rs:80-150](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
| 配置项 | 环境变量 | 说明 | 默认值 |
|--------|----------|------|--------|
| API Token | `TANDEM_API_TOKEN` | 引擎认证令牌 | 自动生成 |
| 主机地址 | `TANDEM_ENGINE_HOST` | 引擎监听地址 | `127.0.0.1` |
| 端口 | `TANDEM_ENGINE_PORT` | 引擎监听端口 | `39731` |
| 内存限制 | `BUN_JSC_forceRAMSize` | JSC 内存上限 | `268435456` (256MB) |
| GC 级别 | `BUN_GARBAGE_COLLECTOR_LEVEL` | 垃圾回收激进程度 | `1` |
#### 版本管理与自动更新
Sidecar Manager 负责检测和下载引擎更新，从 GitHub Releases 获取最新版本：资料来源：[src-tauri/src/sidecar_manager.rs:1-50](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
- **检查间隔**: 每 6 小时自动检查一次更新
- **最小二进制大小**: 100KB（用于验证下载完整性）
- **请求超时**: 8 秒
- **发布版本缓存**: 本地缓存 `sidecar_release_cache.json`
---
### 2.3 工具注册表与策略
Tandem 通过 **ToolRegistry** 管理所有可用工具，并通过 **ToolPolicy** 控制工具的访问策略。这种设计确保了工具调用的安全性和可审计性。
#### 工具注册流程
```mermaid
graph LR
A[工具定义] --> B[ToolRegistry 注册]
B --> C[权限检查]
C --> D{是否允许?}
D -->|是| E[执行工具]
D -->|否| F[拒绝调用]
E --> G[记录审计日志]
```
#### 工具来源
工具可以来自多种来源：
1. **内置工具**: 引擎内置的核心工具（文件系统、搜索等）
2. **MCP 工具**: 通过 MCP (Model Context Protocol) 协议连接外部服务器
3. **自定义技能**: 用户开发的技能包（Skills）
4. **插件**: 第三方插件扩展
---
### 2.4 内存系统
Tandem 的内存系统（tandem-memory）提供了多层次的知识存储和检索能力，支持工作空间级别的记忆管理和全局记忆导入。资料来源：[README.md - Memory](https://github.com/frumu-ai/tandem/blob/main/README.md)
#### 记忆分层架构
| 层级 | 作用域 | 说明 |
|------|--------|------|
| **全局 (Global)** | 所有项目和会话 | 跨项目共享的知识库 |
| **项目 (Project)** | 当前项目 | 与特定工作空间关联的记忆 |
| **会话 (Session)** | 当前对话 | 临时的对话上下文 |
#### 记忆导入格式
Tandem 支持从多种格式导入记忆数据：
```bash
# 导入 OpenClaw 格式
tandem-engine memory import --path ~/.openclaw --format openclaw
# 导入到全局层级
tandem-engine memory import --path ./notes --tier global
# 导入到项目层级（指定项目ID）
tandem-engine memory import --path ./docs --tier project --project-id repo-123 --sync-deletes
```
---
### 2.5 编排器 (Orchestrator)
Orchestrator 负责协调整个任务执行流程，包括计划生成、步骤执行、依赖管理和结果聚合。它是 Tandem "Plan Mode" 功能的核心组件。资料来源：[src-tauri/src/orchestrator](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/orchestrator)
#### 编排器工作流程
```mermaid
graph TD
A[用户任务] --> B[计划生成]
B --> C{执行模式}
C -->|即时模式| D[直接执行]
C -->|计划模式| E[用户确认]
E -->|批准| D
E -->|拒绝| F[取消]
D --> G[步骤执行]
G --> H{下一步}
H -->|有依赖| I[等待依赖完成]
H -->|就绪| J[执行当前步骤]
I --> J
J --> K[收集输出]
K --> H
H -->|全部完成| L[结果聚合]
L --> M[返回最终结果]
```
#### 步骤类型
| 步骤类型 | 说明 | 典型用途 |
|----------|------|----------|
| `research` | 研究和信息收集 | 网络搜索、文档读取 |
| `synthesize` | 综合和分析 | 生成报告、提取摘要 |
| `deliver` | 交付和输出 | 写入文件、创建 Notion 页面 |
---
## 安全模型
Tandem 的安全设计遵循**零信任**原则，所有敏感操作都需要显式授权。资料来源：[README.md - Security and privacy](https://github.com/frumu-ai/tandem/blob/main/README.md)
### 安全特性
| 特性 | 实现方式 | 保护范围 |
|------|----------|----------|
| **无遥测** | 不包含分析或追踪代码 | 隐私 |
| **凭证加密** | AES-256-GCM | API Keys |
| **文件系统隔离** | 访问权限限制 | 敏感文件 |
| **网络隔离** | 仅与本地 sidecar 和配置的 API 通信 | 网络安全 |
| **保险库** | 加密存储主密钥 | Vault 状态 |
### 权限系统
权限通过 **Capabilities** 机制进行管理：
- 桌面运行时定义 capabilities 配置文件（`src-tauri/capabilities/`）
- 每个 capability 包含权限名称和描述
- 用户可以在运行时授予或撤销权限
- 敏感路径（系统目录等）默认拒绝访问
---
## SDK 与 API
Tandem 提供多语言 SDK 用于与引擎进行程序化交互。所有 SDK 都是 API 客户端，**不包含引擎二进制**。资料来源：[packages/tandem-client-ts/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
### TypeScript SDK
```typescript
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;
}
```
### SDK 概览
| SDK | 包名 | 语言 | 最低版本 |
|-----|------|------|----------|
| TypeScript | `@frumu/tandem-client` | TypeScript/JavaScript | Node 18+ |
| Python | `tandem-client` | Python | Python 3.9+ |
| 引擎包 | `@frumu/tandem` | npm | - |
---
## 常见故障与排查
### 引擎启动失败
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 端口被占用 | 39731 端口已被其他进程使用 | 使用 `--port` 指定其他端口 |
| 权限不足 | 无法创建进程 | 检查用户权限 |
| API Token 无效 | Token 格式错误或过期 | 重新生成 Token |
### Sidecar 检测问题
| 问题 | 说明 | 解决方案 |
|------|------|----------|
| `browser_sidecar_not_found` | 未找到 tandem-browser 二进制 | 设置 `TANDEM_BROWSER_SIDECAR` 环境变量或安装浏览器 sidecar |
| 版本探测失败 | 无法获取 sidecar 版本 | 手动检查二进制路径是否正确 |
### 内存使用问题
为解决空闲状态下内存占用过高的问题（>500MB），Sidecar 会自动设置 JSC 内存限制：资料来源：[src-tauri/src/sidecar.rs:100-110](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
```bash
# 手动设置内存限制
export BUN_JSC_forceRAMSize=268435456
export BUN_GARBAGE_COLLECTOR_LEVEL=1
```
---
## 相关文档
- [架构概述](ARCHITECTURE.md) - Tandem 系统架构详解
- [引擎 CLI 参考](docs/ENGINE_CLI.md) - tandem-engine 命令行工具完整文档
- [引擎通信协议](docs/ENGINE_COMMUNICATION.md) - 桌面运行时与引擎的通信契约
- [引擎测试指南](docs/ENGINE_TESTING.md) - 引擎测试和冒烟检查
- [SDK 文档](https://docs.tandem.ac/) - 多语言 SDK 使用指南
- [MCP 文档](https://tandem.ac/docs-mcp) - MCP 协议集成说明
---
## 快速开始
### 相关页面
相关主题：[桌面应用](#desktop-app), [引擎 CLI 与无头服务](#engine-cli), [SDK 参考文档](#sdk-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
- [packages/tandem-client-ts/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
- [packages/tandem-control-panel/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/README.md)
- [engine/README.md](https://github.com/frumu-ai/tandem/blob/main/engine/README.md)
- [docs/ENGINE_CLI.md](https://github.com/frumu-ai/tandem/blob/main/docs/ENGINE_CLI.md)
- [engine/src/main.rs](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
# 快速开始
本文档帮助你在本地快速部署并运行 Tandem AI 引擎。无论是桌面应用、Web 控制面板、命令行界面还是 SDK 集成，Tandem 都提供了灵活的入口方式。
## 概述
Tandem 是一个**本地优先、零信任**的 AI 工作空间应用，核心是头部的 `tandem-engine` 运行时引擎。该引擎支持多种 AI 提供商，包括 OpenAI、Anthropic、Ollama、Groq、Mistral、Azure 等 12 个主流服务提供商。
Tandem 的核心特性包括：
- **本地优先**：数据优先存储在本地，不强制云端同步
- **零信任安全**：不包含遥测追踪，提供加密凭证存储（AES-256-GCM）
- **提供商无关**：可自由路由到用户配置的 AI 服务端点
- **可扩展架构**：支持技能（Skills）、插件（Plugins）、MCP 协议
资料来源：[README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
## 安装方式
Tandem 提供多种安装路径，开发者可根据使用场景选择最适合的方案。
### 桌面应用（推荐新手）
桌面应用集成了完整的控制面板和引擎运行时，适合日常使用。
1. 下载并安装 Tandem：[tandem.ac](https://tandem.ac/)
2. 打开 **Settings** 添加提供商 API 密钥
3. 选择工作区文件夹
4. 开始使用任务提示，选择 **Immediate** 或 **Plan Mode** 模式
资料来源：[README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
### Web 控制面板
Web 控制面板提供完整的图形化配置界面，适合服务器部署和远程访问。
```bash
npm i -g @frumu/tandem
tandem install panel
tandem panel init
```
资料来源：[packages/tandem-control-panel/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/README.md)
### Docker 部署
对于容器化部署场景，Tandem 提供了开箱即用的 Docker Compose 配置：
```bash
# 从 tandem-control-panel 包中获取 docker-compose.yml
# 或使用 tandamd install panel 后在本地查找
docker-compose up -d
```
Docker 部署会将引擎和面板运行在同一 Docker 网络中，默认面板监听端口 `39734`。
资料来源：[packages/tandem-control-panel/DOCKER.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/DOCKER.md)
### 纯引擎运行时
如果只需要头部的引擎运行时（无图形界面），可通过 npm 全局安装：
```bash
npm install -g @frumu/tandem
tandem-engine serve --hostname 127.0.0.1 --port 39731
```
资料来源：[README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
### 终端界面（TUI）
对于命令行爱好者，Tandem 提供全屏终端用户界面：
```bash
npm i -g @frumu/tandem-tui && tandem-tui
```
### 可编辑面板脚手架
生成完全可定制的控制面板应用：
```bash
npm create tandem-panel@latest my-panel
cd my-panel
npm install
npm run dev
```
此方式允许开发者自定义路由、页面、主题、样式或运行时行为。
资料来源：[README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
## 引擎配置
### 环境变量配置
`tandem-engine` 支持通过环境变量进行配置：
| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `TANDEM_ENGINE_HOST` | 引擎监听主机地址 | `127.0.0.1` |
| `TANDEM_ENGINE_PORT` | 引擎监听端口 | `39731` |
| `TANDEM_ENGINE_TOKEN` | API 认证令牌 | 自动生成 |
| `TANDEM_STATE_DIR` | 状态存储目录 | `.tandem` |
资料来源：[engine/src/main.rs:40-60](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
### 命令行参数
`tandem-engine` 支持多种子命令：
```bash
# 启动 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](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
### AI 提供商配置
引擎支持的提供商列表：
| 提供商 ID | 说明 |
|---------|------|
| `openai` | OpenAI GPT 系列 |
| `openrouter` | OpenRouter 聚合 |
| `anthropic` | Anthropic Claude |
| `ollama` | 本地 Ollama |
| `groq` | Groq 推理 |
| `mistral` | Mistral AI |
| `together` | Together AI |
| `azure` | Azure OpenAI |
| `bedrock` | AWS Bedrock |
| `vertex` | Google Vertex AI |
| `copilot` | GitHub Copilot |
| `cohere` | Cohere |
资料来源：[engine/src/main.rs:15-30](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
## SDK 集成
### TypeScript SDK
```typescript
// 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](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
### Python SDK
```bash
pip install tandem-client
```
```python
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](https://github.com/frumu-ai/tandem/blob/main/README.md)
## 认证与令牌管理
### 生成 API 令牌
首次启动引擎后，需要生成认证令牌：
```bash
tandem-engine token generate
```
### Web 登录流程
托管部署场景下，控制面板支持浏览器 OAuth 登录：
1. 打开控制面板登录页
2. 选择 "Sign in with Tandem"
3. 完成浏览器中的身份验证
4. 返回控制面板继续使用
本地独立安装场景下，需要在控制台输入引擎令牌进行认证。
资料来源：[packages/tandem-control-panel/src/app/LoginPage.tsx](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/src/app/LoginPage.tsx)
## 工作流程图
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/browser_parts/part02.rs)
### 凭证存储加密
Tandem 使用 **AES-256-GCM** 加密存储提供商 API 密钥，存储位置由 `tandem_core::resolve_shared_paths()` 决定。
## 下一步
- [引擎 CLI 参考](./engine-cli.md) - 完整的命令行文档
- [引擎通信协议](./engine-communication.md) - 桌面/运行时通信契约
- [架构概述](./architecture.md) - 深入理解系统设计
- [安全模型](./security.md) - 零信任安全实现细节
## 另请参阅
- [Tandem 官方文档](https://docs.tandem.ac/)
- [@frumu/tandem-client npm 包](https://www.npmjs.com/package/@frumu/tandem-client)
- [Python SDK (PyPI)](https://pypi.org/project/tandem-client/)
- [GitHub Releases](https://github.com/frumu-ai/tandem/releases)
---
## 桌面应用
### 相关页面
相关主题：[快速开始](#quickstart), [引擎 CLI 与无头服务](#engine-cli)
相关源码文件
以下源码文件用于生成本页说明：
- [src-tauri/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
- [src-tauri/src/sidecar.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
- [src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
- [README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
- [src/i18n/locales/en/common.json](https://github.com/frumu-ai/tandem/blob/main/src/i18n/locales/en/common.json)
- [packages/tandem-control-panel/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/README.md)
# 桌面应用
Tandem 桌面应用是基于 [Tauri](https://tauri.app/) 框架构建的安全、本地优先的 AI 工作空间客户端。它作为用户与 Tandem Engine 运行时之间的桥梁，提供图形界面、凭证管理、扩展管理和浏览器自动化等核心功能。
## 核心架构
Tandem 桌面应用采用**双进程架构**：主进程（Rust/Tauri）与引擎 Sidecar 子进程通过本地回环地址（`127.0.0.1`）进行安全通信。
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
### 进程生命周期
桌面应用启动时执行以下初始化流程：
1. 解析共享路径和配置目录
2. 初始化日志系统（tracing + 非阻塞写入）
3. 加载或创建引擎 API Token
4. 启动/检测 Sidecar 进程状态
5. 注册 Tauri 命令和事件处理器
**资料来源**：[src-tauri/src/lib.rs:20-40](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
## 安全模型
Tandem 桌面应用实现了**零信任（Zero-Trust）安全架构**，默认拒绝敏感路径访问，并对所有外部通信进行严格控制。
### 安全特性
| 安全措施 | 说明 | 实现位置 |
|---------|------|---------|
| 凭证加密 | Provider API 密钥使用 AES-256-GCM 加密存储 | `vault.rs` |
| 文件系统隔离 | 访问权限限制在用户授权的文件夹内 | `capabilities/` |
| 网络范围控制 | 仅与本地 Sidecar（`127.0.0.1`）和配置的 Provider 通信 | `sidecar.rs` |
| 敏感路径拒绝 | 关键系统路径默认禁止访问 | Tauri capabilities |
| 无遥测 | 不包含分析/追踪或回传机制 | 架构设计 |
**资料来源**：[README.md 安全和隐私部分](https://github.com/frumu-ai/tandem/blob/main/README.md)
### Vault 状态管理
Vault 模块管理加密凭证的生命周期：
```mermaid
stateDiagram-v2
[*] --> Locked: 应用启动
Locked --> Unlocked: 用户解锁
Unlocked --> Locked: 锁定/退出
Unlocked --> [*]: 应用关闭
state Unlocked {
[*] --> HasMasterKey: 解密成功
HasMasterKey --> [*]: Token 可用
}
```
**资料来源**：[src-tauri/src/lib.rs:44-55](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
## 核心组件
### Sidecar 管理器
Sidecar 管理器负责 Engine 进程的完整生命周期，包括检测、下载、更新和版本追踪。
**资料来源**：[src-tauri/src/sidecar_manager.rs:1-40](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
| 功能 | 说明 |
|-----|------|
| 版本检测 | 探测已安装 Engine 版本 |
| 发布检查 | 每 6 小时检查 GitHub Releases |
| 自动下载 | 下载并验证 Sidecar 二进制文件 |
| 缓存管理 | 维护发布版本缓存 |
### Sidecar 进程通信
Sidecar 模块处理与 Engine 进程的进程间通信：
**资料来源**：[src-tauri/src/sidecar.rs:1-50](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/src/i18n/locales/en/common.json)
| 扩展类型 | 说明 | 配置方式 |
|---------|------|---------|
| Skills | 可复用的任务模板和工作流 | 本地文件夹 |
| Plugins | 功能插件扩展 | 动态加载 |
| MCP | Model Context Protocol 连接器 | JSON 配置 |
| Modes | 高级运行模式 | 系统预设 |
## 用户界面
### 登录与认证
桌面应用支持两种认证模式：
**资料来源**：[packages/tandem-control-panel/README.md:1-30](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/README.md)
| 模式 | 适用场景 | 认证方式 |
|-----|---------|---------|
| 本地安装 | 独立桌面部署 | Engine Token |
| 托管面板 | 企业托管服务 | 组织成员验证 |
### 工作区管理
用户首次使用时需要：
1. 下载并启动 Tandem
2. 在 **Settings → Providers** 中配置 API 密钥
3. 或使用本地控制面板连接 Codex 账户
4. 选择工作区文件夹
5. 使用任务提示启动 **Immediate** 或 **Plan Mode**
**资料来源**：[README.md 使用入门部分](https://github.com/frumu-ai/tandem/blob/main/README.md)
## 配置与自定义
### 可编辑面板脚手架
开发者可以生成本地完全可编辑的控制面板应用：
```bash
npm create tandem-panel@latest my-panel
cd my-panel
npm install
npm run dev
```
此方式适用于需要自定义路由、页面、主题、样式或运行时行为的场景，无需修改 `node_modules`。
**资料来源**：[README.md 可编辑 App 脚手架部分](https://github.com/frumu-ai/tandem/blob/main/README.md)
### 引擎配置
引擎支持通过命令行参数和环境变量配置：
```bash
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](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
## 常见问题排查
### 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](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/browser_parts/part02.rs)
### 浏览器自动化状态检查
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/browser_parts/part02.rs)
### 引擎 Token 问题
如果面板无法连接 Engine，检查：
1. Engine Token 是否生成：`tandem-engine token generate`
2. Token 文件路径是否正确：`~/.tandem/tandem_api_token`
3. Token 是否在浏览器和 Engine 间一致
## 许可证说明
Tandem 采用**开放核心**模式，许可证分布如下：
| 组件 | 许可证 |
|-----|-------|
| 核心引擎 (`tandem-core`, `tandem-server` 等) | `MIT OR Apache-2.0` |
| 任务编译器 (`tandem-plan-compiler`) | `BUSL-1.1` |
| 治理引擎 (`tandem-governance-engine`) | `BUSL-1.1` |
**资料来源**：[README.md 许可证部分](https://github.com/frumu-ai/tandem/blob/main/README.md)
## 相关文档
- [架构概览](ARCHITECTURE.md) — 完整系统架构说明
- [引擎运行时与 CLI 参考](docs/ENGINE_CLI.md) — 命令行工具完整文档
- [引擎通信协议](docs/ENGINE_COMMUNICATION.md) — 桌面与引擎间的通信契约
- [引擎测试](docs/ENGINE_TESTING.md) — 测试与冒烟检查指南
- [Tandem MCP 文档](https://tandem.ac/docs-mcp) — MCP 集成配置
- [文档门户](https://docs.tandem.ac/) — 官方文档中心
---
## 引擎 CLI 与无头服务
### 相关页面
相关主题：[快速开始](#quickstart), [桌面应用](#desktop-app), [SDK 参考文档](#sdk-reference), [MCP 集成](#mcp-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [engine/src/main.rs](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
- [packages/tandem-client-ts/README.md](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
- [packages/tandem-ai/package.json](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-ai/package.json)
- [engine/README.md](https://github.com/frumu-ai/tandem/blob/main/engine/README.md)
- [crates/tandem-server/src/browser_parts/part02.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/browser_parts/part02.rs)
- [src-tauri/src/sidecar.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar.rs)
- [src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
- [src-tauri/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
# 引擎 CLI 与无头服务
## 概述
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 服务，辅助进程处理浏览器自动化等特定功能。该设计将计算密集型或系统级任务隔离到独立进程中，通过进程间通信协调工作。
```mermaid
graph TD
A[Desktop Client
Tauri App] -->|IPC + SSE| B[Engine Main Process
tandem-engine serve]
B --> C[Browser Sidecar
tandem-browser]
B --> D[AI Provider API
OpenAI/Anthropic/Ollama...]
E[External Agent
MCP Client] -->|HTTP/SSE| B
```
### 支持的 AI Provider
引擎支持 **12 种主流 AI Provider**，通过统一接口路由请求：
| Provider ID | 说明 | 认证方式 |
|-------------|------|----------|
| `openai` | OpenAI GPT 系列 | API Key |
| `openrouter` | OpenRouter 聚合平台 | API Key |
| `anthropic` | Anthropic Claude 系列 | API Key |
| `ollama` | 本地 Ollama 部署 | 本地/自定义端点 |
| `groq` | Groq 加速推理 | API Key |
| `mistral` | Mistral AI | API Key |
| `together` | Together AI | API Key |
| `azure` | Azure OpenAI Service | Azure 凭证 |
| `bedrock` | AWS Bedrock | AWS 凭证 |
| `vertex` | Google Vertex AI | GCP 凭证 |
| `copilot` | GitHub Copilot | OAuth |
| `cohere` | Cohere Command | API Key |
资料来源：[engine/src/main.rs:17-30]()
## 命令行接口
### 全局命令结构
`tandem-engine` CLI 采用子命令架构，主要包含以下操作：
```bash
tandem-engine [GLOBAL_OPTIONS] [ARGS]
```
| 命令 | 功能 | 典型用途 |
|------|------|----------|
| `serve` | 启动 HTTP/SSE 服务 | 作为后台常驻进程 |
| `status` | 健康检查 | 验证引擎运行状态 |
| `run` | 单次提示执行 | 快速测试和脚本集成 |
| `tool` | 直接工具调用 | 调试和自动化任务 |
| `providers` | 列出可用 Provider | 配置验证 |
| `memory` | 内存导入导出 | 数据迁移和备份 |
| `token` | 令牌管理 | API 认证配置 |
### 常用命令示例
#### 启动服务
```bash
# 默认配置启动（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
```
#### 健康检查
```bash
# 默认检查
tandem-engine status
# 指定目标
tandem-engine status --hostname 127.0.0.1 --port 39731
```
#### 单次任务执行
```bash
tandem-engine run "Summarize this repository" --provider openrouter --model openai/gpt-4o-mini
```
#### 工具直接调用
```bash
# 从文件加载 JSON payload
tandem-engine tool --json @payload.json
# 从标准输入读取
cat payload.json | tandem-engine tool --json -
```
#### 内存导入
```bash
# 导入 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]()
## 服务配置
### 环境变量
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `TANDEM_ENGINE_HOST` | `127.0.0.1` | 服务监听地址 |
| `TANDEM_ENGINE_PORT` | `39731` | 服务监听端口 |
| `TANDEM_API_TOKEN` | 自动生成 | API 认证令牌 |
| `TANDEM_STATE_DIR` | `.tandem` | 状态持久化目录 |
| `TANDEM_BROWSER_SIDECAR` | 自动检测 | 浏览器 Sidecar 路径 |
| `BUN_JSC_forceRAMSize` | `268435456` | Bun 内存限制（字节） |
| `BUN_GARBAGE_COLLECTOR_LEVEL` | `1` | GC 激进程度 |
### Sidecar 管理
引擎的浏览器自动化功能依赖独立的 `tandem-browser` Sidecar 进程。引擎会自动检测二进制文件位置：
1. **显式配置**：`browser.sidecar_path` 或 `TANDEM_BROWSER_SIDECAR` 环境变量
2. **托管安装**：`/binaries/tandem-browser`
3. **共享路径解析**：`tandem-core::resolve_shared_paths()` 返回的规范根目录
Sidecar 版本探测通过执行 `--version` 参数验证，失败时记录警告但不影响核心功能。
```mermaid
graph LR
A[Engine Start] --> B{Has explicit
sidecar_path?}
B -->|Yes| C[Use explicit path]
B -->|No| D{Managed path
exists?}
D -->|Yes| C
D -->|No| E[Search PATH]
E --> F{Found
tandem-browser?}
F -->|Yes| C
F -->|No| G[Mark unavailable
Continue without browser]
C --> H[Probe version
with --version]
```
资料来源：[crates/tandem-server/src/browser_parts/part02.rs:45-85]()
### 浏览器功能状态检测
引擎启动时执行完整的浏览器子系统检测：
| 状态字段 | 类型 | 说明 |
|----------|------|------|
| `runnable` | `bool` | 是否可执行浏览器任务 |
| `blocking_issues` | `Issue[]` | 阻止性问题列表 |
| `recommendations` | `string[]` | 修复建议 |
**阻塞问题代码**：
- `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()` 确定。
```bash
# 生成新令牌
tandem-engine token generate
# 查看当前令牌
tandem-engine token show
```
### TypeScript SDK 认证
```typescript
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 客户端使用
### 完整工作流程
```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 事件类型
| 事件类型 | 说明 | 典型 Payload |
|----------|------|-------------|
| `session.response` | 响应片段 | `{ delta: string }` |
| `run.complete` | 运行成功完成 | `{ output: any }` |
| `run.completed` | 运行完成（别名） | `{ output: any }` |
| `run.failed` | 运行失败 | `{ error: string }` |
| `session.run.finished` | 会话运行结束 | `{ runId: string }` |
资料来源：[packages/tandem-client-ts/README.md:45-75]()
## 打包与分发
### npm 包结构
#### `@frumu/tandem-ai` - CLI 安装器
核心 npm 包，提供 `tandem` CLI 命令：
```json
{
"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
类型安全的引擎客户端库：
```json
{
"name": "@frumu/tandem-client",
"version": "0.5.9",
"engines": {
"node": ">=18"
},
"dependencies": {
"zod": "^4.3.6"
}
}
```
### 引擎构建
Rust 引擎可通过 Cargo 构建：
```bash
# 构建 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]()
## 内存与存储
### 存储层级
| 层级 | 作用域 | 典型用途 |
|------|--------|----------|
| `global` | 全局共享 | 跨项目通用知识 |
| `project` | 单个项目 | 项目特定上下文 |
| `session` | 单次会话 | 临时工作状态 |
### 导入格式
引擎支持多种导入格式，核心是 **OpenClaw 兼容格式**：
```bash
# 导入 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. 验证托管路径 `/binaries/tandem-browser` 存在
3. 确认文件系统权限
#### 2. 版本探测失败
**症状**：`version probe failed` 错误
**排查步骤**：
1. 手动执行 ` --version` 验证可执行性
2. 检查 stderr 输出
3. 确认二进制架构匹配（x64/arm64）
#### 3. 内存占用过高
**症状**：Bun/JSC 进程空闲时内存超过 500MB
**解决方案**：引擎自动设置以下环境变量限制内存：
- `BUN_JSC_forceRAMSize=268435456`（256MB）
- `BUN_GARBAGE_COLLECTOR_LEVEL=1`
这些设置仅在变量未显式配置时生效。
#### 4. Provider 连接失败
**排查矩阵**：
| Provider | 检查项 | 配置位置 |
|----------|--------|----------|
| `ollama` | 本地服务是否运行 | `OLLAMA_HOST` 环境变量 |
| `openai` | API Key 有效性 | Provider 配置 |
| `azure` | Azure 端点和密钥 | `AZURE_OPENAI_*` 环境变量 |
| `bedrock` | AWS 凭证 | 标准 AWS 凭证链 |
### 日志调试
引擎日志输出到：
- 标准输出/标准错误（前台模式）
- Tauri 日志系统（桌面集成）
日志级别通过 `RUST_LOG` 环境变量控制：
```bash
RUST_LOG=debug tandem-engine serve
```
## 进程生命周期
### 启动序列
```mermaid
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 进程启动时接收环境变量形式的凭证：
```rust
for (key, value) in env_vars.iter() {
cmd.env(key, value);
}
cmd.env("TANDEM_API_TOKEN", &self.api_token);
```
每次 Provider 配置变更后，新凭证通过 Sidecar 重启生效。
## 相关文档
- [架构概述](ARCHITECTURE.md) — 完整的系统架构图
- [引擎通信协议](docs/ENGINE_COMMUNICATION.md) — Desktop/Engine 通信契约
- [引擎测试指南](docs/ENGINE_TESTING.md) — 单元测试和冒烟测试
- [Tandem MCP 文档](https://tandem.ac/docs-mcp) — MCP 接口集成
- [SDK 参考](packages/tandem-client-ts/README.md) — TypeScript 客户端完整 API
## 参见
- [许可证说明](docs/LICENSING.md) — 混合许可模型说明
- [安全策略](SECURITY.md) — 威胁模型和漏洞报告流程
- [Tandem 官方文档](https://docs.tandem.ac/) — 用户文档门户
---
## SDK 参考文档
### 相关页面
相关主题：[引擎 CLI 与无头服务](#engine-cli), [MCP 集成](#mcp-integration), [企业级功能](#enterprise-features)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/tandem-client-ts/src/client.ts](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/src/client.ts)
- [packages/tandem-client-ts/src/stream.ts](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/src/stream.ts)
- [packages/tandem-client-py/tandem_client/client.py](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-py/tandem_client/client.py)
- [packages/tandem-client-py/tandem_client/stream.py](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-py/tandem_client/stream.py)
- [packages/tandem-client-ts/package.json](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/package.json)
- [packages/tandem-client-py/setup.py](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-py/setup.py)
- [guide/src/content/docs/sdk/index.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/sdk/index.md)
- [guide/src/content/docs/sdk/typescript.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/sdk/typescript.md)
- [guide/src/content/docs/sdk/python.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/sdk/python.md)
- [README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
# SDK 参考文档
## 概述
Tandem SDK 是一套跨语言的 API 客户端库，用于与 Tandem Engine 运行时进行交互。SDK 不包含 `tandem-engine` 二进制文件，而是作为轻量级客户端，通过 HTTP/SSE 协议与运行中的引擎实例通信。
**核心能力：**
- 创建和管理会话（Sessions）
- 触发任务执行（Runs）
- 流式接收事件和响应（Streaming Events）
- 管理工具注册表和 MCP 连接
- 访问权限控制的记忆存储
**SDK 与引擎的关系：**
```mermaid
graph LR
subgraph "SDK 层（客户端）"
TS_SDK[TypeScript SDK
@frumu/tandem-client]
PY_SDK[Python SDK
tandem-client]
end
subgraph "运行时层（服务端）"
DESKTOP[桌面端内置 Sidecar]
HEADLESS[tandem-engine serve
headless 模式]
end
subgraph "模型层"
MODELS[OpenAI / Anthropic /
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](https://github.com/frumu-ai/tandem/blob/main/README.md)
---
## 前提条件
### 运行环境要求
| SDK | 运行时要求 | 最低版本 |
|-----|-----------|---------|
| TypeScript SDK | Node.js | ≥ 18 |
| Python SDK | Python | ≥ 3.10 |
**资料来源：**[packages/tandem-client-ts/package.json](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/package.json)
### 引擎运行时
SDK 需要一个运行中的 Tandem 引擎实例作为后端。两种启动方式：
**方式一：桌面端启动（推荐开发使用）**
1. 启动 Tandem 桌面应用程序
2. 引擎 sidecar 自动在 `127.0.0.1:39731` 启动
**方式二：独立 Headless 引擎**
```bash
# 安装 npm 包
npm install -g @frumu/tandem
# 启动 headless 引擎
tandem-engine serve --hostname 127.0.0.1 --port 39731
```
**资料来源：**[README.md](https://github.com/frumu-ai/tandem/blob/main/README.md)
---
## TypeScript SDK
### 安装
```bash
npm install @frumu/tandem-client
```
**依赖项：**
| 依赖 | 版本 | 用途 |
|------|------|------|
| zod | ^4.3.6 | 类型验证 |
**资料来源：**[packages/tandem-client-ts/package.json](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/package.json)
### 初始化客户端
```typescript
import { TandemClient } from "@frumu/tandem-client";
// 基础初始化
const client = new TandemClient({
baseUrl: "http://localhost:39731",
token: "your-api-token"
});
```
**配置参数：**
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `baseUrl` | `string` | 是 | `http://localhost:39731` | 引擎服务地址 |
| `token` | `string` | 是 | - | API 认证令牌 |
**资料来源：**[packages/tandem-client-ts/src/client.ts](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/src/client.ts)
### 创建会话
```typescript
// 创建新会话
const session = await client.sessions.create({
workspaceId: "workspace-123",
metadata: {
name: "My Task Session"
}
});
console.log("Session ID:", session.id);
```
### 触发任务执行
```typescript
// 触发同步运行
const run = await client.runs.create({
sessionId: session.id,
prompt: "Summarize this repository",
provider: "openrouter",
model: "openai/gpt-4o-mini"
});
```
### 流式响应
```typescript
import { TandemStreamClient } from "@frumu/tandem-client";
// 创建流式客户端
const streamClient = new TandemStreamClient({
baseUrl: "http://localhost:39731",
token: "your-api-token"
});
// 监听流事件
await streamClient.streamRun({
sessionId: session.id,
prompt: "Write a report on AI trends"
}, {
onToken: (token) => process.stdout.write(token),
onComplete: () => console.log("\nDone!"),
onError: (error) => console.error("Error:", error)
});
```
**资料来源：**[packages/tandem-client-ts/src/stream.ts](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/src/stream.ts)
### 完整示例
```typescript
import { TandemClient, TandemStreamClient } from "@frumu/tandem-client";
async function main() {
const client = new TandemClient({
baseUrl: "http://localhost:39731",
token: process.env.TANDEM_TOKEN
});
// 1. 创建会话
const session = await client.sessions.create({
workspaceId: "default"
});
// 2. 创建流式客户端
const streamClient = new TandemStreamClient({
baseUrl: "http://localhost:39731",
token: process.env.TANDEM_TOKEN
});
// 3. 流式执行任务
await streamClient.streamRun(
{
sessionId: session.id,
prompt: "Explain what Tandem SDK does"
},
{
onToken: (token) => process.stdout.write(token),
onComplete: () => console.log("\n\nTask completed!")
}
);
// 4. 关闭连接
await streamClient.close();
}
main().catch(console.error);
```
---
## Python SDK
### 安装
```bash
pip install tandem-client
```
**资料来源：**[packages/tandem-client-py/setup.py](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-py/setup.py)
### 初始化客户端
```python
from tandem_client import TandemClient
# 基础初始化
client = TandemClient(
base_url="http://localhost:39731",
token="your-api-token"
)
```
### 创建会话
```python
# 创建新会话
session = client.sessions.create(
workspace_id="workspace-123",
metadata={"name": "My Task Session"}
)
print(f"Session ID: {session.id}")
```
### 触发任务执行
```python
# 触发同步运行
run = client.runs.create(
session_id=session.id,
prompt="Summarize this repository",
provider="openrouter",
model="openai/gpt-4o-mini"
)
```
### 流式响应
```python
from tandem_client import TandemStreamClient
# 创建流式客户端
stream_client = TandemStreamClient(
base_url="http://localhost:39731",
token="your-api-token"
)
# 流式执行任务
stream_client.stream_run(
{
"session_id": session.id,
"prompt": "Write a report on AI trends"
},
on_token=lambda token: print(token, end="", flush=True),
on_complete=lambda: print("\nDone!"),
on_error=lambda e: print(f"Error: {e}")
)
```
**资料来源：**[packages/tandem-client-py/tandem_client/stream.py](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-py/tandem_client/stream.py)
### 完整示例
```python
import os
from tandem_client import TandemClient, TandemStreamClient
def main():
client = TandemClient(
base_url="http://localhost:39731",
token=os.environ.get("TANDEM_TOKEN")
)
# 1. 创建会话
session = client.sessions.create(
workspace_id="default"
)
# 2. 创建流式客户端
stream_client = TandemStreamClient(
base_url="http://localhost:39731",
token=os.environ.get("TANDEM_TOKEN")
)
# 3. 流式执行任务
stream_client.stream_run(
{
"session_id": session.id,
"prompt": "Explain what Tandem SDK does"
},
on_token=lambda token: print(token, end="", flush=True),
on_complete=lambda: print("\n\nTask completed!")
)
# 4. 关闭连接
stream_client.close()
if __name__ == "__main__":
main()
```
---
## API 参考
### 客户端配置
#### TandemClient 配置参数
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `baseUrl` | `string` | 是 | `http://localhost:39731` | 引擎 HTTP 端点 |
| `token` | `string` | 是 | - | Bearer 认证令牌 |
| `timeout` | `number` | 否 | `30000` | 请求超时（毫秒） |
| `retryAttempts` | `number` | 否 | `3` | 失败重试次数 |
**资料来源：**[packages/tandem-client-ts/src/client.ts](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/src/client.ts)
#### TandemStreamClient 配置参数
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `baseUrl` | `string` | 是 | `http://localhost:39731` | 引擎 SSE 端点 |
| `token` | `string` | 是 | - | Bearer 认证令牌 |
| `reconnectDelay` | `number` | 否 | `1000` | 重连延迟（毫秒） |
**资料来源：**[packages/tandem-client-ts/src/stream.ts](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/src/stream.ts)
### 核心方法
#### 会话管理
| 方法 | 说明 | 返回类型 |
|------|------|----------|
| `sessions.create(params)` | 创建新会话 | `Session` |
| `sessions.get(id)` | 获取会话详情 | `Session` |
| `sessions.list()` | 列出所有会话 | `Session[]` |
| `sessions.delete(id)` | 删除会话 | `void` |
#### 任务执行
| 方法 | 说明 | 返回类型 |
|------|------|----------|
| `runs.create(params)` | 创建同步运行 | `Run` |
| `runs.get(id)` | 获取运行状态 | `Run` |
| `runs.cancel(id)` | 取消运行 | `void` |
| `streamRun(params, handlers)` | 创建流式运行 | `void` |
#### 流事件处理器
| 回调 | 参数 | 说明 |
|------|------|------|
| `onToken` | `token: string` | 接收到文本片段 |
| `onComplete` | `() => void` | 流结束 |
| `onError` | `error: Error` | 发生错误 |
| `onToolCall` | `toolCall: ToolCall` | 工具调用事件 |
| `onApprovalRequired` | `approval: Approval` | 需要人工批准 |
---
## 认证与令牌
### 获取 API 令牌
SDK 需要使用 Bearer Token 进行认证。令牌通过以下方式获取：
**方式一：桌面端自动管理**
桌面应用程序自动生成并管理令牌，SDK 连接到本地 sidecar 时使用自动生成的令牌。
**方式二：Headless 引擎令牌**
```bash
# 启动引擎时指定令牌
tandem-engine serve \
--hostname 127.0.0.1 \
--port 39731 \
--api-token your-secret-token
```
### 令牌管理
```typescript
// 从环境变量读取令牌
const client = new TandemClient({
baseUrl: "http://localhost:39731",
token: process.env.TANDEM_API_TOKEN
});
```
**最佳实践：**
- 不要将令牌硬编码在源代码中
- 使用环境变量或安全的密钥管理服务
- 令牌应具有最小必要权限
---
## 常见使用模式
### 模式一：对话式交互
```mermaid
sequenceDiagram
participant App as 应用层
participant SDK as Tandem SDK
participant Engine as Tandem Engine
participant Model as AI Model
App->>SDK: 创建会话
SDK->>Engine: POST /sessions
Engine-->>SDK: Session ID
loop 多轮对话
App->>SDK: 发送消息
SDK->>Engine: 创建运行
Engine->>Model: 转发请求
Model-->>Engine: 流式响应
Engine-->>SDK: SSE 事件流
SDK-->>App: onToken 回调
end
```
### 模式二：后台自动化任务
```typescript
// 创建长时间运行的自动化任务
const run = await client.runs.create({
sessionId: session.id,
prompt: "Analyze 100 files and generate report",
provider: "openrouter",
model: "openai/gpt-4o"
});
// 轮询运行状态
while (run.status === "running") {
await sleep(5000);
run = await client.runs.get(run.id);
if (run.status === "requires_approval") {
// 等待人工批准
await waitForApproval(run.id);
}
}
```
### 模式三：工具调用处理
```typescript
await streamClient.streamRun(
{ sessionId: session.id, prompt: "Search the web for..." },
{
onToolCall: async (toolCall) => {
console.log(`Tool called: ${toolCall.name}`);
console.log(`Arguments: ${JSON.stringify(toolCall.arguments)}`);
// 返回工具执行结果
return { result: "search results..." };
}
}
);
```
---
## 错误处理
### 错误类型
| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| `AUTH_001` | 无效或过期令牌 | 重新获取令牌 |
| `AUTH_002` | 缺少认证信息 | 检查请求头 |
| `SESSION_001` | 会话不存在 | 重新创建会话 |
| `SESSION_002` | 会话已过期 | 创建新会话 |
| `RUN_001` | 运行不存在 | 检查运行 ID |
| `RUN_002` | 运行已取消 | 重新发起运行 |
| `TOOL_001` | 工具执行失败 | 检查工具配置 |
| `NETWORK_001` | 连接超时 | 增加超时时间 |
### 错误处理示例
```typescript
import { TandemClient, TandemError } from "@frumu/tandem-client";
const client = new TandemClient({
baseUrl: "http://localhost:39731",
token: process.env.TANDEM_TOKEN
});
try {
const run = await client.runs.create({
sessionId: session.id,
prompt: "Execute task"
});
} catch (error) {
if (error instanceof TandemError) {
switch (error.code) {
case "AUTH_001":
// 刷新令牌
await refreshToken();
break;
case "SESSION_001":
// 重新创建会话
const newSession = await client.sessions.create({...});
break;
default:
console.error(`Error ${error.code}: ${error.message}`);
}
}
}
```
---
## SDK 架构设计
### 模块结构
```mermaid
graph TD
subgraph "SDK 客户端"
Client[TandemClient
同步请求]
StreamClient[TandemStreamClient
SSE 流式]
end
subgraph "核心模块"
HTTP[HTTP 传输层]
SSE[SSE 事件解析]
Auth[认证模块]
Retry[重试机制]
end
subgraph "API 层"
Sessions[会话管理]
Runs[任务执行]
Memory[记忆存储]
Tools[工具注册]
end
Client --> HTTP
StreamClient --> SSE
HTTP --> Auth
SSE --> Auth
HTTP --> Retry
HTTP --> Sessions
HTTP --> Runs
HTTP --> Memory
HTTP --> Tools
```
### 依赖关系
```
TandemClient
├── HTTP 传输层
│ └── 重试机制
├── 认证模块
└── API 端点
├── Sessions API
├── Runs API
├── Memory API
└── Tools API
TandemStreamClient
├── SSE 事件解析器
├── 认证模块
└── 流事件处理器
├── onToken
├── onToolCall
├── onApprovalRequired
└── onComplete
```
---
## 故障排除
### 连接问题
**问题：无法连接到 `localhost:39731`**
排查步骤：
1. 确认引擎已启动
```bash
# 检查引擎进程
ps aux | grep tandem-engine
```
2. 验证端口可用
```bash
# 测试连接
curl http://localhost:39731/health
```
3. 检查防火墙设置
```bash
# Windows
netsh advfirewall firewall add rule name="Tandem" action=allow localport=39731 protocol=tcp
# macOS/Linux
sudo ufw allow 39731/tcp
```
### 认证问题
**问题：返回 `AUTH_001` 错误**
解决方案：
1. 检查令牌是否正确设置
2. 确认令牌未过期
3. 验证令牌权限
```typescript
// 调试：打印请求头
const client = new TandemClient({
baseUrl: "http://localhost:39731",
token: "debug-token"
});
// 启用调试日志
client.debug = true;
```
### 流式问题
**问题：流式响应中断**
解决方案：
1. 检查网络稳定性
2. 增加重连延迟
3. 实现断点续传
```typescript
const streamClient = new TandemStreamClient({
baseUrl: "http://localhost:39731",
token: "your-token",
reconnectDelay: 5000 // 增加重连延迟
});
```
---
## 版本兼容性
| SDK 版本 | 引擎版本要求 | 新增功能 |
|----------|-------------|----------|
| 0.5.x | 0.5.x | 流式 MCP 事件、改进的错误处理 |
| 0.4.x | 0.4.x | 会话管理 API |
| 0.3.x | 0.3.x | 基础客户端功能 |
**资料来源：**[guide/src/content/docs/sdk/index.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/sdk/index.md)
---
## 相关资源
| 资源 | 链接 |
|------|------|
| TypeScript SDK 文档 | [guide/src/content/docs/sdk/typescript.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/sdk/typescript.md) |
| Python SDK 文档 | [guide/src/content/docs/sdk/python.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/sdk/python.md) |
| npm 包 | [@frumu/tandem-client](https://www.npmjs.com/package/@frumu/tandem-client) |
| PyPI 包 | [tandem-client](https://pypi.org/project/tandem-client/) |
| 官方文档 | [docs.tandem.ac](https://docs.tandem.ac/) |
---
## 另请参阅
- [Engine CLI 参考文档](https://github.com/frumu-ai/tandem/blob/main/docs/ENGINE_CLI.md) - 命令行工具完整参考
- [引擎通信协议](https://github.com/frumu-ai/tandem/blob/main/docs/ENGINE_COMMUNICATION.md) - HTTP/SSE 协议详解
- [架构概述](https://github.com/frumu-ai/tandem/blob/main/ARCHITECTURE.md) - 系统整体架构
- [MCP 集成指南](https://tandem.ac/docs-mcp) - MCP 工具连接配置
---
## MCP 集成
### 相关页面
相关主题：[引擎 CLI 与无头服务](#engine-cli), [核心概念](#core-concepts), [智能体 Pack 系统](#agent-packs)
相关源码文件
以下源码文件用于生成本页说明：
- [crates/tandem-runtime/src/mcp.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-runtime/src/mcp.rs)
- [crates/tandem-runtime/src/mcp_ready.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-runtime/src/mcp_ready.rs)
- [crates/tandem-server/src/mcp_catalog.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/mcp_catalog.rs)
- [crates/tandem-server/resources/mcp-catalog/index.json](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/resources/mcp-catalog/index.json)
- [docs/MCP_IMPROVEMENTS.md](https://github.com/frumu-ai/tandem/blob/main/docs/MCP_IMPROVEMENTS.md)
- [guide/src/content/docs/mcp-automated-agents.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/mcp-automated-agents.md)
- [guide/src/content/docs/mcp-capability-discovery-and-request-flow.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/mcp-capability-discovery-and-request-flow.md)
- [crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs)
- [src/i18n/locales/en/common.json](https://github.com/frumu-ai/tandem/blob/main/src/i18n/locales/en/common.json)
# MCP 集成
## 概述
MCP（Model Context Protocol）集成是 Tandem 实现 AI 代理能力扩展的核心机制。通过 MCP 协议，Tandem 可以连接外部工具、数据源和服务，使 AI 代理能够执行多样化的任务，如网络研究、社区数据收集、文档检索等。
Tandem 的 MCP 集成采用**零信任安全模型**，所有 MCP 工具调用都经过权限验证和策略控制，确保敏感操作得到适当的授权审批。资料来源：[docs/MCP_IMPROVEMENTS.md](https://github.com/frumu-ai/tandem/blob/main/docs/MCP_IMPROVEMENTS.md)
## 核心架构
```mermaid
flowchart TD
subgraph 核心层["Tandem 核心引擎"]
MCP["MCP 运行时
(tandem-runtime)"]
Catalog["MCP 目录服务
(mcp_catalog)"]
Policy["工具策略引擎
(tool_policy)"]
Discovery["能力发现模块
(mcp_ready)"]
end
subgraph MCP服务层["MCP 服务器连接"]
TandemMCP["tandem_mcp
文档检索工具"]
Composio["composio
第三方集成"]
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 服务器及其配置。
### 目录结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | MCP 服务器唯一标识符 |
| `name` | string | 显示名称 |
| `capabilities` | array | 支持的工具能力列表 |
| `auth` | object | 认证配置（OAuth/API Key） |
| `scopes` | array | 权限范围 |
资料来源：[crates/tandem-server/resources/mcp-catalog/index.json](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/resources/mcp-catalog/index.json)
### 内置 MCP 服务器
Tandem 预置了以下 MCP 服务器连接：
| MCP 服务器 | 功能描述 | 权限范围 |
|-----------|---------|---------|
| `tandem_mcp` | Tandem 内部文档检索与搜索 | `search_docs`, `get_doc` |
| `composio.reddit` | Reddit 社区数据收集 | `reddit_get_subreddits_search`, `reddit_search_across_subreddits`, `reddit_retrieve_reddit_post` |
| `composio.notion` | Notion 页面创建与更新 | 写入选定的 collection |
资料来源：[crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs:1-50](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs)
## 能力发现与请求流程
### 发现机制
Tandem 实现了完整的能力发现机制，确保 AI 代理在执行任务前了解可用的 MCP 工具。发现流程遵循以下原则：
1. **启动时扫描**：引擎启动时扫描所有已配置的 MCP 服务器
2. **动态更新**：当 MCP 服务器配置变更时，实时更新能力清单
3. **按需暴露**：根据当前任务上下文，仅暴露相关工具能力
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/mcp-capability-discovery-and-request-flow.md)
### 请求授权流程
每个 MCP 工具调用都需要经过授权检查：
1. 代理发起工具调用请求
2. 策略引擎评估请求的风险级别
3. 根据配置决定自动批准或触发人工审批
4. 返回执行结果或审批请求
## 工作流集成
### 规划代理中的 MCP 使用
Tandem 的任务规划代理（`agent_planner`）在执行复杂研究任务时，会协调多个 MCP 工具的调用。以下是一个典型的研究-综合工作流：
| 阶段 | 代理角色 | MCP 工具调用 | 说明 |
|------|---------|-------------|------|
| 范围确认 | `agent_research_planner` | - | 确认任务范围和目标 |
| 文档研究 | `agent_docs_researcher` | `mcp.tandem_mcp.search_docs`, `mcp.tandem_mcp.get_doc` | 检索 Tandem 内部文档 |
| 市场研究 | `agent_market_researcher` | `web_research`, `web_fetch` | 收集外部市场信息 |
| 社区信号 | `agent_community_researcher` | `mcp.composio.reddit_*` | 收集 Reddit 讨论 |
| 综合报告 | `agent_synthesizer` | `mcp.composio.notion` | 输出到 Notion |
资料来源：[crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs:20-80](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-plan-compiler/src/workflow_plan_parts/part02.rs)
### 工作流步骤定义
每个工作流步骤包含以下元数据：
```json
{
"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 配置：
| 标签页 | 功能 |
|-------|------|
| Skills | 技能管理 |
| Plugins | 插件管理 |
| **MCP** | MCP 服务器连接配置 |
| Modes | 运行模式设置 |
资料来源：[src/i18n/locales/en/common.json](https://github.com/frumu-ai/tandem/blob/main/src/i18n/locales/en/common.json)
### MCP 服务器配置
配置 MCP 服务器时，需要提供以下信息：
| 配置项 | 必填 | 说明 |
|-------|-----|------|
| 服务器 ID | 是 | MCP 服务器的唯一标识 |
| 连接地址 | 是 | MCP 服务器的 URL 或本地路径 |
| 认证方式 | 否 | OAuth 2.0 或 API Key |
| 权限范围 | 是 | 允许使用的工具列表 |
## 安全与策略
### 零信任安全模型
Tandem 对所有 MCP 交互实施零信任安全原则：
- **最小权限**：代理仅获得完成任务所需的最小权限集
- **显式授权**：每个敏感操作都需要显式授权
- **审计追踪**：所有 MCP 调用都被记录用于审计
### 策略执行点
| 策略检查点 | 检查内容 |
|-----------|---------|
| 连接建立 | MCP 服务器身份验证 |
| 工具发现 | 能力清单访问权限 |
| 工具调用 | 操作类型和参数验证 |
| 数据访问 | 资源范围和敏感度评估 |
资料来源：[docs/MCP_IMPROVEMENTS.md](https://github.com/frumu-ai/tandem/blob/main/docs/MCP_IMPROVEMENTS.md)
## 浏览器自动化集成
Tandem 支持通过专用的 `tandem-browser` sidecar 实现浏览器自动化能力。这项功能依赖于 MCP 协议与浏览器的通信。
### 状态检查
浏览器自动化组件会执行以下状态检查：
| 检查项 | 状态字段 | 说明 |
|-------|---------|------|
| Sidecar 发现 | `sidecar.found` | tandem-browser 二进制文件是否存在 |
| Sidecar 版本 | `sidecar.version` | 已安装的版本号 |
| 浏览器引擎 | `browser.found` | 浏览器引擎可用性 |
资料来源：[crates/tandem-server/src/browser_parts/part02.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/browser_parts/part02.rs)
### Sidecar 自动下载
对于托管部署场景，Tandem 支持自动下载和管理浏览器 sidecar：
```bash
# 配置浏览器 sidecar 路径
TANDEM_BROWSER_SIDECAR=/custom/path/tandem-browser
# 或在配置文件中设置
browser:
sidecar_path: /custom/path/tandem-browser
```
## 常见配置问题
### MCP 连接失败排查
| 问题症状 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 连接超时 | 网络隔离或防火墙 | 检查网络配置，确保 127.0.0.1 访问 |
| 认证失败 | API Key 过期或权限不足 | 更新凭证或扩展权限范围 |
| 工具未发现 | MCP 服务器未启动 | 确认 MCP 服务器进程运行中 |
### Sidecar 下载失败
当浏览器自动化 sidecar 下载失败时：
1. 检查 GitHub API 访问权限（可能存在速率限制）
2. 手动下载对应平台的 release asset
3. 通过 `--browser-sidecar` 参数指定本地路径
## 参考文档
- [MCP 自动化代理指南](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/mcp-automated-agents.md)
- [MCP 能力发现与请求流程](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/mcp-capability-discovery-and-request-flow.md)
- [MCP 改进文档](https://github.com/frumu-ai/tandem/blob/main/docs/MCP_IMPROVEMENTS.md)
## 另请参阅
- [Tandem 架构概览](ARCHITECTURE.md)
- [引擎运行时与 CLI 参考](docs/ENGINE_CLI.md)
- [工具策略配置](docs/TOOL_POLICY.md)
- [自动化工作流](docs/AUTOMATIONS.md)
---
## 智能体 Pack 系统
### 相关页面
相关主题：[MCP 集成](#mcp-integration), [核心概念](#core-concepts), [企业级功能](#enterprise-features)
相关源码文件
以下源码文件用于生成本页说明：
- [agent-templates/PACKS.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/PACKS.md)
- [agent-templates/notes.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/notes.md)
- [agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md)
- [agent-templates/pack-docs/finance-analysis-pack/PACK_INFO.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/finance-analysis-pack/PACK_INFO.md)
- [agent-templates/pack-docs/research-synthesis-pack/PACK_INFO.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/research-synthesis-pack/PACK_INFO.md)
- [crates/tandem-server/src/pack_manager.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/pack_manager.rs)
- [guide/src/content/docs/automation-composer-workflows.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/automation-composer-workflows.md)
# 智能体 Pack 系统
Tandem 的 **智能体 Pack 系统**（Agent Pack System）是一个结构化的任务封装框架，旨在为用户提供可复制、即开即用的智能体工作流解决方案。Pack 将提示词模板、参考文档、示例输入和工作流程配置打包为独立的文件夹，使用户能够快速启动特定领域的自动化任务。
## 概述
### 什么是 Pack
Pack 是一种**引导式、可复制的工作流文件夹**，专门设计用于实际生产任务。每个 Pack 包含启动指南、提示词模板和示例输入，使智能体能够快速适应特定领域的工作需求。
资料来源：[agent-templates/PACKS.md:1-10](https://github.com/frumu-ai/tandem/blob/main/agent-templates/PACKS.md)
### Pack 的核心价值
| 价值主张 | 说明 |
|---------|------|
| **开箱即用** | 包含 `START_HERE.md` 启动指南，无需从零配置 |
| **领域适配** | 针对特定场景（研究、金融、生物信息学等）优化 |
| **可复制性** | 文件夹结构标准化，便于分发和版本管理 |
| **渐进引导** | 提供示例输入和预期输出，帮助用户理解工作流 |
资料来源：[src/i18n/locales/en/common.json](https://github.com/frumu-ai/tandem/blob/main/src/i18n/locales/en/common.json)
### Pack 与其他扩展的关系
Tandem 提供了多种扩展机制来增强智能体能力：
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md)
### PACK_INFO.md 元数据规范
```markdown
---
name: bio-informatics-pack
version: 1.0.0
description: 生物信息学数据分析工作流
author: Tandem Team
tags: [research, biology, data-analysis]
---
```
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | 是 | Pack 唯一标识符 |
| `version` | string | 是 | 语义化版本号 |
| `description` | string | 是 | Pack 功能描述 |
| `author` | string | 否 | 创建者信息 |
| `tags` | string[] | 否 | 分类标签数组 |
资料来源：[agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md)
## 内置 Pack 示例
Tandem 仓库中预置了多个领域的 Pack，展示了系统的实际应用场景。
### 研究综合 Pack（Research Synthesis Pack）
用于自动化研究文献的综述和综合分析。
资料来源：[agent-templates/pack-docs/research-synthesis-pack/PACK_INFO.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/research-synthesis-pack/PACK_INFO.md)
```mermaid
graph LR
A[输入研究论文] --> B[文献检索与筛选]
B --> C[关键信息提取]
C --> D[主题聚类分析]
D --> E[综合报告生成]
E --> F[结构化输出]
```
### 金融分析 Pack（Finance Analysis Pack）
专注于金融数据的处理、分析和报告生成。
资料来源：[agent-templates/pack-docs/finance-analysis-pack/PACK_INFO.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/finance-analysis-pack/PACK_INFO.md)
### 生物信息学 Pack（Bio-informatics Pack）
提供生物序列分析、基因表达数据处理等专用工作流。
资料来源：[agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md](https://github.com/frumu-ai/tandem/blob/main/agent-templates/pack-docs/bio-informatics-pack/PACK_INFO.md)
## Pack 管理器
### PackManager 架构
Pack 管理器（`PackManager`）是服务端核心组件，负责 Pack 的发现、加载、验证和运行。
资料来源：[crates/tandem-server/src/pack_manager.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/pack_manager.rs)
```mermaid
classDiagram
class PackManager {
+discover_packs() Vec~PackMetadata~
+load_pack(name: &str) Pack
+validate_pack(pack: &Pack) ValidationResult
+execute_pack(pack: &Pack, context: &Context) Result
}
class Pack {
+metadata: PackMetadata
+prompts: Vec~PromptTemplate~
+inputs: Vec~SampleInput~
+configs: Option~WorkflowConfig~
}
class PackMetadata {
+name: String
+version: String
+description: String
+tags: Vec~String~
}
PackManager --> Pack
Pack --> PackMetadata
```
### Pack 发现机制
Pack 管理器通过文件系统扫描发现可用的 Pack：
1. **目录扫描**：遍历预设的 Pack 搜索路径
2. **元数据解析**：解析每个目录中的 `PACK_INFO.md`
3. **有效性验证**：检查必需文件和目录结构
4. **索引构建**：建立 Pack 名称到路径的映射
资料来源：[crates/tandem-server/src/pack_manager.rs:1-50](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/pack_manager.rs)
### Pack 验证规则
| 验证项 | 规则 | 错误代码 |
|--------|------|----------|
| 目录存在 | Pack 根目录必须存在 | `PACK_NOT_FOUND` |
| 元数据文件 | `PACK_INFO.md` 必须存在且有效 | `MISSING_PACK_INFO` |
| 启动指南 | `START_HERE.md` 必须存在 | `MISSING_START_HERE` |
| 版本格式 | 版本号必须符合语义化版本规范 | `INVALID_VERSION` |
| 提示词模板 | `prompts/` 目录必须非空 | `EMPTY_PROMPTS` |
## Pack 与工作流集成
### Pack 在自动化编排中的角色
Pack 系统与 Tandem 的自动化编排引擎深度集成，支持复杂工作流的构建和执行。
资料来源：[guide/src/content/docs/automation-composer-workflows.md](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/automation-composer-workflows.md)
```mermaid
graph TD
subgraph Pack 生命周期
A[Pack 发现] --> B[Pack 加载]
B --> C[Pack 验证]
C --> D{验证结果}
D -->|通过| E[Pack 执行]
D -->|失败| F[错误报告]
end
subgraph 工作流集成
E --> G[工作流编排器]
G --> H[任务分解]
H --> I[提示词注入]
I --> J[执行引擎]
J --> K[结果聚合]
end
G --> L[输出格式化]
```
### Pack 执行上下文
当 Pack 被加载执行时，系统会创建一个执行上下文，包含以下信息：
| 上下文字段 | 说明 | 来源 |
|-----------|------|------|
| `pack_name` | 当前执行的 Pack 名称 | PACK_INFO.md |
| `pack_version` | Pack 版本号 | PACK_INFO.md |
| `workspace_dir` | 用户工作区目录 | 用户配置 |
| `input_path` | 选定输入文件路径 | 用户选择 |
| `output_dir` | 结果输出目录 | 用户配置 |
| `variables` | 自定义变量映射 | 用户配置 |
## 前端界面集成
### 界面文案
Tandem 桌面应用和 Web 控制面板中集成了 Pack 系统的用户界面元素。
资料来源：[src/i18n/locales/en/common.json](https://github.com/frumu-ai/tandem/blob/main/src/i18n/locales/en/common.json)
| 界面元素 | 英文 Key | 中文说明 |
|---------|----------|----------|
| 标题 | `packs.title` | Starter Packs |
| 副标题 | `packs.subtitle` | 引导式、可复制的工作流文件夹 |
| 搜索框 | `packs.searchPlaceholder` | 搜索 packs（研究、写作、安全...）|
| 安装说明 | `packs.installsInclude` | 安装包含 START_HERE.md、提示词和示例输入 |
### 界面交互流程
```mermaid
sequenceDiagram
participant User as 用户
participant UI as 界面
participant PM as Pack 管理器
participant FS as 文件系统
User->>UI: 打开 Pack 标签页
UI->>PM: 请求 Pack 列表
PM->>FS: 扫描 Pack 目录
FS-->>PM: 返回 Pack 元数据
PM-->>UI: 显示 Pack 列表
User->>UI: 搜索/过滤 Pack
UI->>PM: 搜索请求
PM-->>UI: 过滤结果
User->>UI: 选择 Pack
UI->>PM: 加载 Pack 内容
PM-->>UI: 显示 Pack 详情
User->>UI: 执行 Pack
UI->>PM: 执行请求
PM->>FS: 读取 Pack 文件
PM-->>UI: 执行结果
```
## 使用指南
### 创建自定义 Pack
1. **创建目录结构**
```bash
mkdir my-custom-pack
cd my-custom-pack
touch PACK_INFO.md START_HERE.md
mkdir -p prompts inputs configs
```
2. **编写 PACK_INFO.md**
```markdown
---
name: my-custom-pack
version: 1.0.0
description: 我的自定义工作流
tags: [custom, example]
---
```
3. **编写 START_HERE.md**
包含清晰的使用步骤、输入要求和预期输出。
4. **添加提示词模板**
在 `prompts/` 目录中添加 Markdown 格式的提示词文件。
5. **添加示例输入**
在 `inputs/` 目录中添加示例数据文件。
### Pack 搜索与发现
用户可以通过以下方式发现可用的 Pack：
| 方式 | 说明 |
|------|------|
| Web 控制面板 | 在「Extensions → Packs」标签页浏览和搜索 |
| 命令行 | 使用 `tandem pack list` 查看已安装 Pack |
| 文件系统 | 直接浏览 `~/.tandem/packs/` 目录 |
## 技术注意事项
### 路径解析
Pack 管理器使用共享路径解析机制定位 Pack 目录：
```rust
fn resolve_pack_root() -> PathBuf {
resolve_shared_paths()
.map(|p| p.canonical_root)
.unwrap_or_else(|_| {
dirs::home_dir()
.map(|h| h.join(".tandem"))
.unwrap_or_else(|| PathBuf::from(".tandem"))
})
.join("packs")
}
```
资料来源：[crates/tandem-server/src/pack_manager.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/pack_manager.rs)
### 文件访问权限
| 路径类型 | 访问权限 | 说明 |
|---------|---------|------|
| Pack 根目录 | 只读 | 系统内置 Pack |
| 用户 Pack 目录 | 读写 | 用户创建的 Pack |
| 输出目录 | 读写 | 执行结果写入位置 |
| 临时文件 | 读写 | 执行过程中的临时文件 |
## 相关资源
- [自动化编排工作流文档](https://github.com/frumu-ai/tandem/blob/main/guide/src/content/docs/automation-composer-workflows.md)
- [Tandem 引擎 CLI 参考](https://github.com/frumu-ai/tandem/blob/main/docs/ENGINE_CLI.md)
- [Pack 示例仓库](https://github.com/frumu-ai/tandem/tree/main/agent-templates/pack-docs)
## 参见
- [扩展系统概览](./extensions-overview.md) - Skills、Plugins、MCP 和 Modes 的完整说明
- [自动化编排引擎](./automation-composer-workflows.md) - 工作流编排的详细文档
- [引擎 CLI 参考](../guides/engine-cli.md) - 命令行工具完整参考
---
## 企业级功能
### 相关页面
相关主题：[核心概念](#core-concepts), [系统架构](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/ENTERPRISE_READINESS.md](https://github.com/frumu-ai/tandem/blob/main/docs/ENTERPRISE_READINESS.md)
- [docs/EU_AI_ACT_COMPLIANCE.md](https://github.com/frumu-ai/tandem/blob/main/docs/EU_AI_ACT_COMPLIANCE.md)
- [docs/compliance/README.md](https://github.com/frumu-ai/tandem/blob/main/docs/compliance/README.md)
- [crates/tandem-enterprise-contract/src/governance.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-enterprise-contract/src/governance.rs)
- [crates/tandem-enterprise-server/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-enterprise-server/src/lib.rs)
- [crates/tandem-governance-engine/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-governance-engine/src/lib.rs)
- [contracts/http.md](https://github.com/frumu-ai/tandem/blob/main/contracts/http.md)
- [manifests/components/tandem-sdk-clients.yaml](https://github.com/frumu-ai/tandem/blob/main/manifests/components/tandem-sdk-clients.yaml)
- [src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
- [engine/src/main.rs](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
# 企业级功能
Tandem v0.5.11 引入了完善的企业级功能集，为组织提供了在托管环境中部署和运行自主 AI 工作空间的能力。本页面详细介绍 Tandem 的企业级架构、部署模式、安全特性、合规支持以及 SDK 集成方案。
## 功能概览
Tandem 企业级功能旨在满足以下核心需求：
| 功能类别 | 描述 | 适用场景 |
|---------|------|---------|
| **托管引擎分发** | 独立的 Linux x64 二进制分发包 | VPS、服务器部署 |
| **企业级路由** | 完整的路由能力与浏览器自动化集成 | 复杂工作流自动化 |
| **托管 Sidecar 包装器** | 专用 npm 包用于托管环境 | 云原生部署 |
| **治理引擎** | 递归策略执行与合规检查 | 企业政策合规 |
| **多提供商支持** | 支持 12+ AI 提供商 | 灵活的模型选择 |
| **零信任安全** | 端到端加密与凭证保护 | 数据敏感环境 |
> 资料来源：[docs/ENTERPRISE_READINESS.md](https://github.com/frumu-ai/tandem/blob/main/docs/ENTERPRISE_READINESS.md)
## 企业架构
### 系统组件架构
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-enterprise-server/src/lib.rs)
### 引擎服务架构
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs) 和 [crates/tandem-governance-engine/src/lib.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-governance-engine/src/lib.rs)
## 部署模式
Tandem 企业版支持多种部署模式，以适应不同的基础设施需求。
### 托管模式
托管模式适用于需要集中管理的组织：
```bash
# 安装托管引擎
npm i -g @frumu/tandem-engine
# 启动托管引擎服务
tandem-engine serve --hostname 0.0.0.0 --port 39731
```
> 资料来源：[packages/tandem-engine](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-engine/package.json)
### 托管 Sidecar 模式
v0.5.11 新增了专用的托管 Sidecar npm 包装器，提供更好的云原生集成：
| 配置项 | 说明 | 默认值 |
|-------|------|--------|
| `sidecar_path` | Sidecar 二进制路径 | `~/.tandem/binaries/` |
| `TANDEM_BROWSER_SIDECAR` | 浏览器 Sidecar 环境变量 | - |
| `browser.sidecar_path` | 配置文件中的路径 | - |
> 资料来源：[src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
### 容器化部署
Tandem 提供 Docker Compose 配置用于容器化部署：
```yaml
# 标准配置
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](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/DOCKER.md)
## 企业安全特性
### 零信任安全模型
Tandem 企业版实现了完整的零信任安全架构：
| 安全层级 | 保护机制 | 实现方式 |
|---------|---------|---------|
| **传输加密** | API Token 认证 | `tandem-engine token generate` 生成令牌 |
| **凭证存储** | AES-256-GCM 加密 | `src-tauri/src/keystore.rs` |
| **文件系统隔离** | 作用域化访问 | 仅允许授权文件夹访问 |
| **敏感路径保护** | 默认拒绝策略 | `src-tauri/src/tool_policy.rs` |
| **遥测控制** | 无追踪/无遥测 | README.md 安全声明 |
> 资料来源：[README.md - 安全和隐私](https://github.com/frumu-ai/tandem/blob/main/README.md)
### 凭证管理
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/lib.rs)
## 合规支持
### EU AI Act 合规
Tandem 企业版针对 EU AI Act 提供了专门的合规支持模块：
| 合规要求 | 实现状态 | 相关模块 |
|---------|---------|---------|
| 透明度报告 | ✅ 支持 | 遥测日志 |
| 数据处理记录 | ✅ 支持 | 工具历史 |
| 人工监督接口 | ✅ 支持 | Plan Mode |
| 风险评估 | ✅ 支持 | 治理引擎 |
| 合规审计日志 | ✅ 支持 | 观测性模块 |
> 资料来源：[docs/EU_AI_ACT_COMPLIANCE.md](https://github.com/frumu-ai/tandem/blob/main/docs/EU_AI_ACT_COMPLIANCE.md) 和 [docs/compliance/README.md](https://github.com/frumu-ai/tandem/blob/main/docs/compliance/README.md)
### 治理策略执行
企业治理引擎负责递归策略检查：
```rust
// 治理引擎核心接口
pub struct GovernancePolicy {
pub allowed_providers: Vec,
pub denied_tools: Vec,
pub audit_enabled: bool,
pub compliance_mode: ComplianceLevel,
}
```
> 资料来源：[crates/tandem-enterprise-contract/src/governance.rs](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-enterprise-contract/src/governance.rs)
## SDK 与 API 集成
### TypeScript SDK
企业应用可以通过官方 SDK 集成 Tandem 引擎：
```typescript
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](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-client-ts/README.md)
### 支持的 AI 提供商
Tandem 企业版支持以下 AI 提供商的无缝集成：
| 提供商 | ID | 配置要求 |
|-------|-----|---------|
| OpenAI | `openai` | API Key |
| OpenRouter | `openrouter` | API Key |
| Anthropic | `anthropic` | API Key |
| Ollama | `ollama` | 本地端点 |
| Groq | `groq` | API Key |
| Mistral | `mistral` | API Key |
| Together AI | `together` | API Key |
| Azure OpenAI | `azure` | Azure 凭证 |
| AWS Bedrock | `bedrock` | AWS 凭证 |
| Google Vertex | `vertex` | GCP 凭证 |
| GitHub Copilot | `copilot` | OAuth/Token |
| Cohere | `cohere` | API Key |
> 资料来源：[engine/src/main.rs - SUPPORTED_PROVIDER_IDS](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
### HTTP API 合约
企业服务通过标准 HTTP API 与引擎通信：
| 端点 | 方法 | 描述 |
|-----|------|------|
| `/api/v1/sessions` | POST | 创建会话 |
| `/api/v1/sessions/:id/prompt` | POST | 发送提示 |
| `/api/v1/stream` | GET | SSE 事件流 |
| `/api/v1/status` | GET | 引擎状态 |
| `/api/v1/providers` | GET | 提供商列表 |
> 资料来源：[contracts/http.md](https://github.com/frumu-ai/tandem/blob/main/contracts/http.md)
## 版本与分发
### 企业版发布流程
v0.5.11 引入的企业版发布机制：
```mermaid
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](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
### Sidecar 版本管理
企业版自动管理 Sidecar 二进制版本：
| 配置参数 | 说明 | 默认值 |
|---------|------|--------|
| `RELEASES_PER_PAGE` | 每页发布版本数 | `20` |
| `MAX_RELEASE_PAGES` | 最大页数 | `5` |
| `RELEASE_CHECK_INTERVAL_SECS` | 检查间隔 | `6 * 60 * 60` (6小时) |
| `RELEASE_REQUEST_TIMEOUT_SECS` | 请求超时 | `8` 秒 |
| `MIN_BINARY_SIZE` | 最小二进制大小 | `100KB` |
> 资料来源：[src-tauri/src/sidecar_manager.rs](https://github.com/frumu-ai/tandem/blob/main/src-tauri/src/sidecar_manager.rs)
## 许可与开放核心
Tandem 采用开放核心许可证模式：
| 组件 | 许可证 | 可用性 |
|-----|--------|--------|
| 运行时、协议、SDK | MIT / Apache-2.0 | 开源 |
| 任务编译器 (`tandem-plan-compiler`) | BUSL-1.1 | 源可用 |
| 治理引擎 (`tandem-governance-engine`) | BUSL-1.1 | 源可用 |
| Tandem 桌面应用 | MIT / Apache-2.0 | 开源 |
> 资料来源：[README.md - 许可](https://github.com/frumu-ai/tandem/blob/main/README.md) 和 [docs/LICENSING.md](https://github.com/frumu-ai/tandem/blob/main/docs/LICENSING.md)
## 快速开始
### 企业托管部署
```bash
# 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](https://github.com/frumu-ai/tandem/blob/main/packages/tandem-control-panel/README.md)
### 本地控制面板
```bash
# 生成可编辑的控制面板
npm create tandem-panel@latest my-enterprise-panel
cd my-enterprise-panel
npm install
npm run dev
```
> 资料来源：[README.md - 可编辑应用脚手架](https://github.com/frumu-ai/tandem/blob/main/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](https://github.com/frumu-ai/tandem/blob/main/crates/tandem-server/src/browser_parts/part02.rs)
### 引擎连接失败
| 检查项 | 命令 | 解决方案 |
|-------|------|---------|
| 服务状态 | `tandem-engine status` | 启动引擎服务 |
| 端口占用 | `netstat -an \| grep 39731` | 更换端口或释放端口 |
| Token 验证 | 检查 `$TANDEM_API_TOKEN` | 重新生成 Token |
| 防火墙 | 测试本地连接 | 开放必要端口 |
> 资料来源：[engine/src/main.rs - STATUS_EXAMPLES](https://github.com/frumu-ai/tandem/blob/main/engine/src/main.rs)
## 延伸阅读
| 文档 | 描述 |
|-----|------|
| [架构概览](ARCHITECTURE.md) | Tandem 系统架构详解 |
| [引擎 CLI 参考](docs/ENGINE_CLI.md) | tandem-engine 命令行完整参考 |
| [引擎通信契约](docs/ENGINE_COMMUNICATION.md) | 桌面/运行时通信协议 |
| [MCP 集成](https://tandem.ac/docs-mcp) | MCP 工具连接配置 |
| [安全威胁模型](SECURITY.md) | 完整安全模型与报告流程 |
| [文档门户](https://docs.tandem.ac/) | 官方文档中心 |
---
---
## Doramagic 踩坑日志
项目：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