workspaceguard

WorkspaceGuard

安装 • 快速开始 • CLI 参考 • 比较 • 常见问题

针对一个由多个工作区共享的可自托管 AI 助手部署（Odysseus 或兼容的后端），按工作区统计用量，并在达到配额上限时安全拒绝请求。

在家庭或小型团队中运行 Odysseus（或兼容的可自托管助手）时，你无法查看本月每个人发送了多少条消息，也无法阻止某个人的用量耗尽其他人的 API 预算。WorkspaceGuard 是一个侧车组件，为你补上这一层能力：按工作区统计消息数、可选的月度配额上限（达到上限时安全拒绝请求），以及管理员或其他 Agent 可读取的 CLI（或 JSON）报告。

npx workspaceguard-cli usage
-> alex   [[email protected]]: 812 messages this period, cap 1000 (81%)
-> jordan [[email protected]]: 203 messages this period, cap unlimited

安装

npm install -g workspaceguard-cli

也可以不安装，直接运行：

npx workspaceguard-cli usage

此软件包名为 workspaceguard-cli；安装的命令为 workspaceguard。一个真正独立、具有相同 CLI 接口和 --json 输出结构的 Python 移植版本也单独以 workspaceguard-cli 的名称发布在 PyPI 上（pip install workspaceguard-cli，参见 python/）。

快速开始

# Register the workspaces sharing one deployment (identity = the header value
# your reverse proxy sets after authenticating, e.g. Cloudflare Access).
workspaceguard add-workspace alex --identity [email protected]
workspaceguard add-workspace jordan --identity [email protected]

# Optional: cap alex at 1000 messages/month. Omit for unlimited (the default).
workspaceguard set-cap alex 1000

# See usage for every workspace.
workspaceguard usage

全新安装后的实际输出：

-> alex [[email protected]]: 0 messages this period, cap 1000 (0%)
-> jordan [[email protected]]: 0 messages this period, cap unlimited

功能

• 按工作区统计消息数。 每个经过侧车组件 chat() 入口的请求，都会递增该工作区按月统计的计数器（src/core/usage.ts）；各工作区相互隔离，一个工作区的用量不会泄露到另一个工作区。
• 安全拒绝超出配额的请求。 工作区达到配额上限时，会在调用后端之前抛出 QuotaExceededError。如果用量存储损坏或无法读取，WorkspaceGuard 会阻止请求，而不是悄悄将所有人的计数重置为零（参见 CHANGELOG.md）。
• 所有命令均支持适用于 Agent 的 --json。 workspaceguard usage --json 会返回编排器可直接解析的结构化输出，无需抓取屏幕内容。
• 采用 AES-256-GCM 的保险库，支持真正的密钥轮换。 workspaceguard rotate-key <id> 会使用新密钥重新加密工作区的密钥，并使旧密文失效。
• 可自我修复的熔断器。 后端连续失败 3 次后，后端调用会触发熔断；随后通过半开探测重试，并在成功后恢复闭合，而不会一直处于熔断状态。
• 单一关键入口，而非分散检查。 src/core/isolation-guard.ts 中的 chat() 是每个请求都会经过的唯一入口：解析工作区、检查配额、调用后端、记录用量。
• 两个独立且经过测试的发行版本。 TypeScript 软件包（npm）和 Python 移植版本（PyPI）针对各自独立的测试套件实现了相同设计：截至本文撰写时，TypeScript 测试通过 41/41，Python 测试通过 50/50。

CLI 参考

每条命令都支持 --json，以结构化、原生适用于 Agent 的格式输出，而非下方所示的便于人类阅读的文本。

命令	功能
workspaceguard init	为此部署初始化数据目录和保险库。
workspaceguard add-workspace <id> --identity <value>	注册工作区；对同一 id 重复调用不会产生副作用。--identity 按位置解析，必须紧跟在 <id> 后面；它不是独立的标志。
workspaceguard status [--json]	列出已配置的工作区。
workspaceguard usage [--json]	列出当前月份各工作区的消息数、上限和已使用百分比。
workspaceguard set-cap <id> <count|none>	设置或清除工作区的月度消息上限。
workspaceguard rotate-key <id>	轮换工作区的保险库加密密钥（使旧密文失效）。
workspaceguard scan [--json]	隔离配置扫描（沿用原始构建的脚手架占位实现；目前始终返回空的发现列表）。
workspaceguard -h、--help	打印上述命令列表并以状态码 0 退出。
workspaceguard -V、--version	打印已安装的软件包版本并以状态码 0 退出。

全局选项

选项	功能
--data-dir <path>	配置、保险库和用量数据的数据目录。优先级高于 WORKSPACEGUARD_DATA_DIR。
--force	仅适用于 init：即使解析后的数据目录中已有的密钥文件看起来已损坏或被截断，也会重新生成主密钥。
--json	输出结构化、原生适用于 Agent 的格式，而非便于人类阅读的文本。

警告

--force 会永久使所有已使用旧主密钥加密的内容失效。仅当确认现有密钥文件无法恢复时才使用。

数据目录的解析顺序： --data-dir 标志，然后是 WORKSPACEGUARD_DATA_DIR 环境变量，最后是 ~/.workspaceguard。以前，默认目录是当前工作目录，且无法覆盖——如果从错误的 shell 运行 init，可能会在无关目录中悄悄写入正在使用的加密密钥。对已有有效密钥运行 init 不会产生副作用（会加载并复用该密钥）；如果密钥文件存在但无法解码为有效密钥，init 会拒绝覆盖，除非指定 --force。

$ workspaceguard usage --json
{"ok":true,"usage":[{"workspaceId":"alex","identity":"[email protected]","monthlyMessageCap":1000,"percentUsed":81,"period":"2026-07","messageCount":812,"estimatedBytes":48213}]}

--json 模式让它真正原生适用于 Agent，而不只是方便人类使用：编排器或监控 Agent 可以调用 workspaceguard usage --json 并直接解析结果，无需抓取终端输出。

库 API

import { createWorkspaceGuard, MockAdapter, QuotaExceededError } from "workspaceguard-cli";

const guard = await createWorkspaceGuard({ dataDir: "./data", backend: new MockAdapter() });
await guard.addWorkspace("alex", "[email protected]");
await guard.setCap("alex", 1000);

try {
  await guard.chat("[email protected]", "hello");
} catch (err) {
  if (err instanceof QuotaExceededError) {
    // alex is over their monthly cap
  }
}

const report = await guard.usageReport();

Python 移植版提供相同的接口：from workspaceguard import create_workspace_guard, MockAdapter, QuotaExceededError。

MCP 服务

WorkspaceGuard 的 Python 发行版附带一个 模型上下文协议 服务，因此兼容 MCP 的 Agent（Claude Desktop、Claude Code、编排器）可以直接将 WorkspaceGuard 作为工具调用，而不必通过 shell 调用 CLI 并解析文本。

pip install "workspaceguard-cli[mcp]"

它提供一个工具 run，这是一个通用的子进程包装器：传入与命令行相同的参数列表，它会调用已安装的 workspaceguard 二进制文件，解析生成的 JSON 并返回结果。所有失败情况（缺少二进制文件、启动错误、超时、非零退出、无法解析输出）都会以普通的 {"error": ...} 字典返回，而不会抛出异常，因此错误调用不会导致服务崩溃。

run(args=["usage", "--json"])
# -> {"ok": true, "usage": [{"workspaceId": "alex", "identity": "[email protected]", "monthlyMessageCap": 1000, "percentUsed": 0, "period": "2026-08", "messageCount": 0, "estimatedBytes": 0}]}

要将其注册到 Claude Desktop 等兼容 MCP 的客户端，请将它添加到客户端的服务配置中：

{
  "mcpServers": {
    "workspaceguard": {
      "command": "workspaceguard-mcp"
    }
  }
}

此处假设 workspaceguard-mcp 已位于 PATH 中（通过上文的 mcp extra 安装）。如果安装在其他位置，请将 "command" 替换为控制台脚本的完整路径。

对比

WorkspaceGuard 是一个 sidecar，并非竞争产品。它位于 Odysseus 部署（或兼容后端）之前，补上该后端未提供的一层能力。

能力	WorkspaceGuard	Odysseus（原生）
按用户隔离（聊天记录、记忆、API 密钥）	不重复实现；视为已解决	是，默认内置
按工作区统计消息数	是	否
每月配额上限，失败时默认拒绝	是	否
CLI / --json 用量报告	是	否
许可证	MIT	AGPL-3.0

WorkspaceGuard 是什么？它为何存在

这个项目最初旨在为可自托管的 AI 聊天平台添加按用户进行的工作区隔离（独立的聊天记录、记忆、API 密钥）。可行性验证发现，Odysseus 默认已强制执行对聊天记录、记忆和 API 令牌的按用户所有权控制，因此构建一个竞争性的隔离层，只会重复 Odysseus 已正确完成的工作。

WorkspaceGuard 则保留其经过测试的隔离引擎（命名空间分离、支持真实密钥轮换的 AES-256-GCM 保险库、失败时默认拒绝的身份解析、自愈式断路器）作为身份解析基础，并构建 Odysseus 未提供的能力层：按工作区进行用量计量和配额强制执行。

免费层（本仓库，MIT）： 按工作区统计消息数、强制执行每月上限，以及 CLI/JSON 用量报告。不在本仓库中： 托管式多租户计费控制面板是一个单独的闭源产品，此处仅将其列为路线图项目，绝不会合并到这个 MIT 代码库中。

架构

• src/core/isolation-guard.ts -- 唯一的关口（chat()），每个请求都会经过这里：解析工作区、检查配额、调用后端、记录用量。
• src/core/usage.ts -- 本项目新增的用量计量引擎：按工作区和月份统计计数器，自动切换周期，并强制执行 QuotaExceededError。
• src/core/vault.ts、src/core/namespace.ts、src/core/circuit-breaker.ts -- 原有的隔离引擎代码，作为用量计量层读取的身份和工作区边界基础。
• src/adapters/ -- BackendAdapter 接口。目前唯一的实现是 MockAdapter；尚未构建真正的 Odysseus HTTP 适配器。

特定于后端的行为绝不会直接进入 src/core/。所有操作都通过 BackendAdapter 进行。

信任边界

WorkspaceGuard 信任上游身份标头（默认：Cf-Access-Authenticated-User-Email）来解析工作区。

警告

此服务绝不能直接从网络访问。只能在会设置该标头的可信代理（Cloudflare Access、Tailscale 等）之后运行。此边界仅有文档说明，未通过代码强制执行。

已实现与尚未构建的内容

• 已实现且经过测试： 用量计量、配额强制执行、原有的隔离引擎（保险库、命名空间分离、断路器），以及支持 --json 模式的 CLI；TypeScript 测试 41/41 通过，Python 测试 50/50 通过。
• 尚未构建： 真正的 Odysseus HTTP 适配器（目前只有 MockAdapter），以及托管式多租户计费控制面板（按计划不属于这个 MIT 仓库的范围）。

文档

• 入门指南
• 概念
• CI 集成
• 后端集成

常见问题

Q：WorkspaceGuard 实际上有什么作用？ 答：它在一个共享的可自托管 AI 助手部署前添加按工作区计量用量和强制执行配额的功能。它会按工作区和月份统计消息数，让你设置可选的上限（达到上限后会拒绝请求），并向你或 Agent 提供 workspaceguard usage 报告。它本身不会添加聊天历史记录、记忆或 API 密钥隔离；目标平台默认已提供这些功能（参见上文“什么是 WorkspaceGuard”），而 WorkspaceGuard 自身的隔离代码（src/core/vault.ts、src/core/namespace.ts）仅作为身份解析的基础层保留，供计量层读取。

问：WorkspaceGuard 真正的差异化优势是什么？ 答：专注做好一件事：它不是完整的计费平台，也不会重新实现后端已有的隔离功能。每个请求都会经过同一个入口（src/core/isolation-guard.ts 中的 chat()）；如果用量存储损坏，配额执行会拒绝请求，而不是悄悄将所有人的用量重置为零（参见 CHANGELOG.md）；并且每条命令都支持 --json，以便 Agent 原生使用输出。

问：WorkspaceGuard 与 Odysseus 有何不同？ 答：它不是竞争产品。WorkspaceGuard 是一个侧车，部署在 Odysseus 部署（或兼容后端）前面；它不会取代 Odysseus 已有的任何功能。具体的功能划分请参见上文的对比表。

问：WorkspaceGuard 可以在哪些平台上运行？ 答：npm 包（workspaceguard-cli）需要 Node.js 20 或更高版本（package.json 中的 engines.node）。Python 移植版 python/ 需要 Python 3.9 至 3.13（参见 python/pyproject.toml 中的分类器）。这两个发行版都不包含特定平台的二进制文件，因此只要对应的运行时能够运行，它们就能在相应平台上运行（Linux、macOS、Windows）。

问：WorkspaceGuard 是命令行工具、库，还是两者兼具？ 答：两个发行版都兼具两者。命令行工具（workspaceguard <command>）支持 init、add-workspace、status、usage、set-cap、rotate-key 和 scan。同样的功能也可直接导入（TypeScript 包中的 createWorkspaceGuard，Python 包中的 create_workspace_guard），供希望直接从代码调用而非通过命令行运行的程序使用。

问：在依赖 WorkspaceGuard 之前，有什么当前的实际限制需要了解？ 答：目前唯一实现的后端适配器是 MockAdapter，它是用于测试和本地试验的内存适配器。真实的 Odysseus HTTP 适配器尚未构建（参见 docs/integrations/backends.md），因此 WorkspaceGuard 目前还不能将实时聊天流量转发到实际的 Odysseus 部署。计量和配额逻辑本身是真实且经过测试的；尚未完成的部分是连接实时后端的网络桥接。

问：WorkspaceGuard 需要自己的 API 密钥，或需要持有我的 AI 提供商凭证吗？ 答：不需要。目前唯一存在的后端适配器（MockAdapter）是内存适配器，不会调用任何外部 API。所有特定于后端的行为都通过 BackendAdapter 接口（src/adapters/）隔离，因此 WorkspaceGuard 自身的代码永远不需要直接接触提供商凭证。

问：WorkspaceGuard 可免费用于商业用途吗？ 答：可以。整个代码库均采用 MIT 许可，没有双重许可，也没有功能限制。上文提到的托管式多租户计费仪表板是单独的闭源产品，仅作为路线图项目介绍；这个 MIT 代码库中没有计费仪表板代码，也没有隐去这部分代码。

贡献与安全

请参阅 CONTRIBUTING.md 和 SECURITY.md。重要变更会记录在 CHANGELOG.md 中。

许可证

MIT。