cambium (remote)

cambium-remote

xylem 技术栈的一部分。

一个 Cloudflare Worker MCP 服务，可让 **claude.ai（包括移动端）**检索 cambium 已推广的知识，且仅提供只读访问。

本地 cambium 是一个桌面 stdio 服务；其团队知识存放在每个项目仓库的 cambium 分支上，组织知识存放在专用知识仓库中——两者都是 git 中普通的 knowledge.json 文件。此 Worker 通过 GitHub Contents API 读取这些文件，并基于它们提供 recall()，采用与 agentsync-remote 为协调看板所用的相同模式。

此服务按设计为只读。它提供 recall 和 status。它不会执行 distill、endorse 或 promote（这些操作涉及 CAS 写入／通用化关卡，只能在桌面端使用），而且此处的 recall 不会增加 recall 计数（因此绝不会参与推广）。本地（个人、未推广）范围仅限桌面端，无法远程访问——只有已推广的团队和组织层级可用。

工具

• recall(query, scope?, limit?) — 搜索团队和组织知识。scope： auto（默认，团队＋组织）| team | org。如果相关性低于最低阈值，则返回 no_confident_match，与本地 cambium 完全相同。
• status() — 查看 Worker 配置读取的内容，以及每个范围中有多少条有效条目。如果 recall 结果为空，请先调用此工具。

⚠️ 信任模型——将其用于组织前请先阅读

团队“范围”是读取选择器，不是授权控制。它回答的是“我们要在哪里查找”，而不是**“谁有权告诉我们信息”**。此 Worker 不会检查其提供的知识的来源、签名或作者身份。

在默认的 TEAM_SCOPE_MODE = "discover" 模式下，团队范围的完整成员资格检查仅为：

由 TEAM_OWNER 所有的这个仓库，是否有一个名为 TEAM_BRANCH 的分支？

**没有允许列表，也没有拒绝列表。**因此：

• 任何能向 TEAM_OWNER 旗下任意仓库推送 cambium 分支的人，都能向你的组织级 recall 注入内容——例如，对某个小型仓库有写入权限的外部贡献者、遭到入侵的 CI 令牌，或你忘记移除的协作者。他们的 knowledge.json 会被当作权威的团队知识读取。
• 内容会在5 分钟的发现缓存 TTL 内生效。无需重新部署、审核或通知。
• Agent 会将 recall() 的输出视为既定事实并据此行动。这是向 Agent 行为注入内容的途径，不只是数据质量问题。

发现模式仍为默认模式，因为对于本服务面向的单人运维场景，它确实安全，而且若悄然更改现有部署的设置，团队范围将变为空。只有当你是唯一能向 TEAM_OWNER 旗下仓库推送的人时，发现模式才安全。

如果还有其他人能向 TEAM_OWNER 旗下仓库推送，请使用严格模式

TEAM_SCOPE_MODE = "allowlist"
TEAM_REPOS = "owner/repo-a,owner/repo-b"

此时团队范围将仅限这些仓库。不会执行发现扫描，而且会完全忽略 TEAM_OWNER——因此，即使在 wrangler.toml 中保留该设置，范围也不会在之后悄然扩大。添加仓库需要明确修改配置。

status() 会在其输出中以通俗语言说明当前采用哪种模式。如果不确定某个部署的运行方式，请调用它。

status() 有意不提供的信息

默认情况下，status() 返回的是团队仓库的数量，而非仓库名称。在发现模式下，这些名称来自对 TEAM_OWNER 所有仓库的扫描，因此会向任何持有路径令牌的人列出私有仓库的存在及其名称；这些人没有 GitHub 身份，也没有自己的仓库权限。这个数量足以回答实际的诊断问题（“团队范围是否找到了内容？”）。设置 STATUS_DISCLOSE_REPOS = "true" 可选择重新显示仓库名称。在 allowlist 模式下，始终会显示名称：它们来自你自己提交的配置，而不是发现扫描的结果。

GH_PAT 是 xylem 技术栈中权限最广的凭据

发现功能需要对 TEAM_OWNER 下的每个仓库拥有 Metadata: Read + Contents: Read 权限，包括私有仓库。这使该 Worker 的 PAT 权限远大于 agentsync-remote 的 PAT（仅限一个协调仓库）。有两点值得采取行动：

• 优先使用 allowlist 模式，这样可以将 PAT 的范围限定为仅列出的仓库，而非整个账户。
• 如果这里的 AUTH_TOKEN 泄露，其严重性高于同类 Worker：该 Worker 会代表调用者读取范围内的任何仓库。

配置（wrangler.toml 中的 vars）

var	含义
ORG_REPO	专用组织知识仓库的 owner/name（其默认分支中的 knowledge.json）。留空 = 不提供组织记忆。
TEAM_SCOPE_MODE	discover（默认）或 allowlist。这是一个信任决策——请参阅信任模型。
TEAM_OWNER	仅限 discover 模式。 用于自动发现团队仓库的所有者（用户/组织）；其所有包含 TEAM_BRANCH 的仓库都会被读取。留空 = 不进行发现。在 allowlist 模式下会被忽略。
TEAM_REPOS	discover 模式： 在发现结果之外可选添加的 owner/name 仓库。allowlist 模式： 团队范围的完整仓库集合，以逗号分隔。
TEAM_BRANCH	团队范围分支（默认为 cambium）。
KNOWLEDGE_PATH	文件名（默认为 knowledge.json）。
STATUS_DISCLOSE_REPOS	"true" 允许 status() 列出团队仓库名称。默认关闭——发现的名称可能包含私有仓库。

在 discover 模式下，团队范围是一个不断扩大的集合：新晋升为团队仓库的内容无需重新部署，几分钟内就会出现在移动端。每隔几分钟进行一次 GraphQL 扫描（在隔离环境中缓存）以列出仓库；没有该分支的仓库会被跳过。

部署

npm install
npm run typecheck && npm test
npx wrangler deploy
# then set the two secrets in the Cloudflare dashboard (never in the repo):
npx wrangler secret put AUTH_TOKEN   # the path-token credential; URL is /mcp/<AUTH_TOKEN>
npx wrangler secret put GH_PAT       # fine-grained GitHub token: Metadata: Read + Contents: Read across your repos
#                                    # (team scope is auto-discovered, so it needs to see all of TEAM_OWNER's repos)

然后在 claude.ai → Settings → Connectors 中，将 https://cambium-remote.<subdomain>.workers.dev/mcp/<AUTH_TOKEN> 添加为自定义连接器。整个 URL 都是凭据——请像密码一样对待。

🔒 身份验证 — 连接器 URL 是凭据

路径令牌：POST /mcp/<token>，与 AUTH_TOKEN 密钥进行比对，耗时不受内容和长度影响；其他任何请求都会返回空白的 404。与同类 Worker 使用相同的方案，现在也使用完全相同的代码（src/shared/mcp-core.ts）。

为什么令牌位于 URL 路径中，以及这会带来什么代价

这是经过深思熟虑的设计选择，并非疏忽。claude.ai 自定义连接器无法可靠地发送自定义标头，因此不能依赖 Authorization: 标头这一显而易见的替代方案。将凭据放在路径中，才能让连接器正常工作。

请明确了解其中的代价，因为它与使用标头不同：

• URL 会被记录在请求正文不会出现的地方。浏览器历史记录、Shell 历史记录、代理和 CDN 访问日志、崩溃报告、错误报告、屏幕截图、“复制链接”按钮，以及Agent 会话记录。在编写本节的审计过程中，发现这些 Worker 的连接器 URL 在单台机器上的 13 份本地会话记录中出现了约 54 次——没有一次是有人刻意粘贴的；它们只是出现在 Agent 回显的工具配置中。
• **Worker 本身不会记录它。**每条日志都会将路由记录为 /mcp/***。泄露面是 Worker 周围的一切，而这些恰恰是你无法审计的。
• 这里的泄露在三种情况中后果最严重，因为此 Worker 的 GH_PAT 涵盖 TEAM_OWNER 下的所有仓库（参见信任模型）。

实用建议：

1. 按计划轮换，不要等到起疑时才轮换——假设 URL 已记录在某个你无法控制的地方。轮换成本很低：更改 AUTH_TOKEN，更新连接器。
2. 如果你分享了配置了此连接器的机器上的终端录屏、会话记录、屏幕截图或错误报告，请立即轮换。
3. 使用足够长的随机令牌（32 字节以上，例如 openssl rand -hex 32）。
4. 按 TEAM_SCOPE_MODE 所允许的范围，尽可能缩小 GH_PAT 的权限范围。
5. 如果有机会改用标头或 OAuth，就改用它们。这是客户端迫使我们做出的权衡，并非首选方案。

开发

npm install
npm run typecheck
npm test

CI（.github/workflows/ci.yml）会在每次推送和 PR（包括分叉仓库中的 PR）时运行类型检查和测试。.github/workflows/deploy.yml 只会在 main 分支通过检查时部署规范仓库，并通过 if: github.repository == … 进行保护，因此分叉仓库不会尝试执行缺少所需机密的部署。

许可证

MIT——参见 LICENSE，与同系列的 agentsync-remote 和 context-keeper-remote Worker 保持一致。

致维护者：此 README 之前声明采用 PolyForm Noncommercial 1.0.0，但仓库中并没有 LICENSE 文件。此处已添加 MIT LICENSE，以与另外两个同系列项目保持一致。如果此 Worker 原本打算采用 PolyForm 许可，请在合并前替换 LICENSE 和本节——这一不一致问题早已存在，此处将其标出，并未擅自推定。