xiantong 文档
来源

概览

通过 MCP 服务器、REST API 以及本地文件系统连接你的 Agent 与外部数据

来源是驱动 Agent 的数据连接。它们让你的 Agent 访问外部服务、API 和文件，以完成需要真实世界数据的任务。

正在使用本地文件？ 若需在单个目录中直接访问文件系统，请使用工作目录。它提供内置工具如 Read、Write 和 Bash，无需配置 MCP。来源最适合连接外部服务或访问多个文件位置。

只需告诉你的 Agent。 添加来源最简单的方式就是告诉它：

  • “连接我的 GitHub 账号”
  • “在此工作区中添加 Slack”
  • “为我的 Obsidian 库设置访问”

Agent 会自动处理配置、认证与验证。

什么是来源？#

来源是你的 Agent 可以使用的任何外部数据连接：

  • MCP 服务器 - 标准化的 AI 工具集成
  • REST API - 任意具有 HTTP 端点的服务
  • 本地文件夹 - 你机器上的文件夹书签

每个来源都会为 Agent 提供可在对话中调用的工具。当你让 Agent“查看我的 GitHub 问题”或“搜索网络”时，背后就是在使用来源。所有类型的来源 —— MCP 服务器、API 和本地文件夹 —— 都适用于所有配置的 LLM 提供商，包括 Anthropic、OpenAI/Codex、Google Gemini、GitHub Copilot 以及自定义端点。

来源类型#

MCP 服务器#

Model Context Protocol 服务器提供丰富的、预构建的工具集成。许多服务提供官方 MCP 支持。示例： Linear、GitHub、Brave Search

REST API#

连接任意具有 API 的服务。提供文档后你的 Agent 即可进行经身份验证的请求。示例： Exa Search、自定义后端

本地文件夹#

为你机器上的文件夹创建书签，便于快速访问与文档查看。示例： 会议记录、下载、参考目录

来源如何工作#

每个来源都存放在以下文件夹中：

~/.xiantong/workspaces/{workspace-id}/sources/{source-slug}/

来源文件夹包含：

  • config.json - 连接设置、认证类型、状态（必需）
  • guide.md - 指导 Agent 如何使用此来源（可选）
  • permissions.json - 探索模式的自定义规则（可选）
  • icon.* - 来源图标（可选）

config.json#

配置文件定义如何连接该来源：

{
"type": "mcp",
"name": "Linear",
"slug": "linear",
"enabled": true,
"provider": "linear",
"mcp": {
"url": "https://mcp.linear.app",
"authType": "oauth"
},
"isAuthenticated": true,
"connectionStatus": "connected"
}

关键字段：

  • type - 来源类型：mcp、api 或 local
  • enabled - 该来源是否处于激活状态
  • provider - 服务标识符（例如 "linear"、"github"、"custom"）
  • isAuthenticated - 是否已存储凭证
  • connectionStatus - 当前状态：connected、needs_auth、failed、untested 或 local_disabled

icon.*#

在来源文件夹中放置图标文件（icon.svg、icon.png）以实现自定义品牌。图标会自动被发现 —— 无需额外配置。图标工作原理：

config.icon 值行为
Emoji（"🔧"）以 Emoji 呈现
本地路径（"./icon.svg"）从来源文件夹加载
URL（"https://..."）验证时自动下载
未设置自动发现 icon.svg/icon.png，并回退到网站 favicon

最佳实践： 创建来源时将 icon 设为 URL，然后运行验证。图标会下载并本地缓存，以实现快速的离线显示。

guide.md#

guide 文件帮助 Agent 了解如何有效使用该来源：

# Linear

Issue and project tracking for the iOS team.

## Scope

Access to the "xiantong iOS" project and related issues.

## Guidelines

- Search issues before creating duplicates
- Use labels consistently with team conventions
- Check sprint assignments before moving issues

编写良好的 guide.md 会显著提升 Agent 的效率。请包含具体的项目名称、团队约定与常见工作流程。

激活与停用#

可以在不删除来源的情况下启用或禁用它：

  1. 在 UI 中： 在工作区设置中切换来源的开关
  2. 在 config.json 中： 将 "enabled": false

禁用的来源仍然保留配置，但在对话中不会对 Agent 可用。

来源生命周期#

  1. 设置 - 创建来源文件夹和 config.json
  2. 认证 - 存储凭证（OAuth、API 密钥等）
  3. 测试 - 验证连接是否可用
  4. 主动使用 - 来源在对话中可用
  5. 停用 - 不需要时禁用

探索模式权限#

默认情况下，来源在探索模式下使用只读访问权限。创建 permissions.json 可定义哪些操作是安全的：

{
"allowedMcpPatterns": [
{ "pattern": "list", "comment": "All list operations" },
{ "pattern": "get", "comment": "All read operations" },
{ "pattern": "search", "comment": "All search operations" }
]
}

模式会自动作用于该来源，因此 list 会在内部变为 mcp__linear__.*list。

下一步#

MCP 服务器#

连接支持 MCP 的服务

REST API#

连接任意具有 API 的服务

本地文件夹#

为你机器上的文件夹创建书签

认证#

设置安全凭证

上一页交互