来源总览

什么是来源#

来源是工作台与外部世界之间的数据连接。它把一个外部服务、一个 HTTP 接口或一个本机目录接进对话，让 Agent 能读到模型本身并不知道的真实数据，而不是凭印象作答。

每种来源最终都会变成 Agent 在对话中可调用的工具。你说「看看我这边有哪些待处理的工单」或「查一下这份接口文档」，背后走的都是来源；来源没接好，Agent 只能给出无法核实的回答。

来源与模型彼此独立。同一个来源既能配合平台提供的模型使用，也能配合你自己配置的服务商使用，换模型时不需要重新接线。

• MCP 服务：按统一协议发布工具的服务端，GitHub、Linear 这类服务大多有官方实现。
• REST 接口：任何提供 HTTP 接口的服务，填好地址与凭据即可发起请求。
• 本地目录：指向本机文件夹的具名书签，可附说明文件告诉 Agent 目录里有什么。

来源类型#

三类来源覆盖了绝大多数接入需求：标准协议的服务走 MCP，只有 HTTP 接口的服务走 REST 接口，本机已有的资料走本地目录。

判断顺序很简单：这个服务有没有现成的 MCP 服务？有就用 MCP，工具更细、语义更清楚；只有 HTTP 接口就用接口来源，请求路径由你控制；资料就在自己机器上则用本地目录，不额外引入网络调用。

• MCP 服务：Linear、GitHub 这类服务通常自带官方 MCP 服务，连上后直接获得查询与写入工具。
• REST 接口：内部后端、自建检索服务、报表类接口，只要能发起 HTTP 请求就能接。
• 本地目录：笔记、下载目录、参考资料库，也可以直接指向一个代码仓库的工作副本。

来源如何工作#

每个来源对应工作区目录下的一个来源文件夹，路径形态为 ~/.zero-works/workspaces/<工作区 ID>/sources/<来源标识>/。文件夹里的文件共同决定这个来源怎么连、怎么用、能做哪些操作。

config.json 是必需文件，声明来源类型、启用状态、服务标识与认证状态；guide.md 是可选的说明文件，用来告诉 Agent 这个来源覆盖哪些范围、该怎么用；permissions.json 可选，用于补充只读模式下的允许范围；icon.svg 或 icon.png 可选，用于在来源列表里显示图标。

来源接入后，工作台按 config.json 建立连接并发现它实际提供的工具。只有发现到工具，来源才在对话中真正可用；连接成功却没有工具的来源，会一直停在未就绪状态。

• type：来源类型，取 mcp、api 或 local。
• enabled：来源是否启用，停用后配置保留。
• provider：服务标识，用来区分同名来源。
• isAuthenticated：是否已经保存凭据。
• connectionStatus：连接状态，取 connected、needs_auth、failed、untested 或 local_disabled。

作用域#

来源与它保存的凭据都按工作区隔离。每个工作区有独立的来源目录和凭据记录，一个工作区里配置的来源不会自动出现在另一个工作区。

凭据本身不写进 config.json，而是单独加密保存，并按「认证方式 + 工作区 + 来源标识」区分归属。删除来源时，对应的凭据记录一并失效。

这条边界让「按项目或按场景分工作区」成为安全的隔离手段：试验性质的接入、临时令牌与正式连接的凭据不会互相污染。

使用原则#

给来源起能说明用途的名字，例如「仓库工单」「设计参考库」，而不是 source1、source2。名字会出现在工具前缀和对话记录里，越具体越不容易被误用。

来源可以附带一份说明文件，写清这个来源覆盖哪些范围、有哪些约定、哪些操作要谨慎。边界说明到位，Agent 才不会把一个项目的规则套到另一个项目上。

不要一次接入过多来源。每多一个来源就多一组工具，工具过密会拖慢每轮响应，也会让模型更难判断该用哪一个。

• 先接当前任务真正需要的那一个，跑通之后再加下一个。
• 凭据只填在专用配置字段里，不要写进说明文件、对话正文或技能文件。
• 接口地址、模型标识、令牌这类会变化的信息集中在一处保存，便于整体替换。

启用与停用#

来源可以随时停用而不必删除。停用后配置与凭据都保留，只是不再向对话提供工具，适合临时收起暂时不用的接入。

停用与删除是两件不同的事。停用只影响这一次配置在对话中的可见性，凭据仍然保存在本地；删除则会同时清掉配置与对应的凭据记录。

1. 在来源设置里把目标来源切换为停用，状态会立即同步到当前会话。
2. 需要恢复时重新启用，工具会重新出现在可调用列表里。
3. 确认不再需要时再删除来源，并一并清理对应的凭据。

• 在界面上切换开关，或把 config.json 里的 enabled 改为 false。
• 停用的来源不会出现在对话里，也不会消耗它的接口额度。
• 停用不影响已产生的历史记录，历史对话里的工具调用结果照常保留。

来源生命周期#

一个来源通常经历建立、认证、测试、启用使用到停用几个阶段。每一阶段都有明确的完成标志，缺一环就会在后续步骤暴露出来。

各阶段可以反复发生。凭据过期后回到认证阶段，权限调整后回到测试阶段，都不需要重建来源目录；只有接入目标本身变了，才需要新建来源。

• 建立：创建来源文件夹并写好 config.json，类型、名称与启用状态都要填对。
• 认证：按服务要求准备凭据，填入专用字段；需要交互式授权的服务按其官方流程完成。
• 测试：执行连接校验，确认地址可达、凭据有效、工具或接口确实可用。
• 启用使用：来源在对话中可用，工具按来源名称加前缀出现，便于分辨调用来源。
• 停用：暂时不用时关掉开关，保留配置以便随时恢复。

只读模式下的来源权限#

默认情况下，来源在只读模式下就可用，但只能执行读取类操作。需要放行更多只读动作时，可以在来源目录里加一份 permissions.json，逐条写明允许的模式。

模式会自动限定在当前来源内部：写 list 这样的简单模式，系统会展开成该来源下的工具调用，因此不会把一个来源的放行范围带到另一个来源。

• MCP 来源用 allowedMcpPatterns 写工具名模式。
• 接口来源用 allowedApiEndpoints 按请求方法与路径放行。
• 本地目录来源用 allowedBashPatterns 放行只读命令。

下一步#

接下来按你要接的东西选一条路径：标准协议的 MCP 服务看「连接器与 MCP」，只有 HTTP 接口的服务看「REST 接口来源」，本机资料看「本地文件夹」。

拿不定主意时，先看「来源接入清单」，那里按服务类型列出了常见来源的接入方式、验证方法和需要注意的限制。

模型侧的配合另见「模型与服务商」：来源决定能拿到什么数据，模型与服务商决定用哪个模型来加工这些数据。