Hexis

用于管理 AI Agent 技能、工具、上下文、权限和身份的 Git 支持型控制平面。 可自托管，原生支持 MCP。

集中管理公司的 AI 插件、工具和知识，并进行审核和访问控制，供任何 AI Agent使用。Bevel 平台的开源核心。

为什么选择 Hexis？

已被以下团队采用

阅读我们总结的促成 Hexis 诞生的经验：我们的 Medium 文章

面向团队

工程师和非技术人员都能在同一处浏览和加载插件、提出建议并管理访问权限。

面向企业

每项技能、工具手册和权限都是你所拥有的 Git 仓库中的一个文件，因此审计记录就是存储层：谁在何时更改了什么、谁批准了更改，以及如何撤销。Agent 只能执行运行它的人员有权执行的操作，权限按文件解析，而且 Agent 永远不会持有它所使用的凭据。它运行在你的基础设施上，并受你自己的 SSO 保护。

与 MCP 网关有何不同：

MCP 网关是单向的；用户可以使用插件、技能或工具，但没有机制让用户提出更改，或分享新的技能和 MCP 服务。你可以在后台通过 GitHub 完成这些操作，但非技术用户无法使用，而且查看内容或参与审核流程都没有精细的访问控制。

Hexis 支持上述所有分发能力，并具备管理所需的双向协作能力。

在 Hexis 中，技能和工具手册都是可审核的文件。任何人都可以提出更改；在受保护的分支上，更改会送达受影响文件的所有者，并且只有在他们批准后才会发布。Agent 也可以提出更改：如果它在任务中遇到失效的技能，可以建议修复方案，由人来决定是否采纳。

目录

• 查看 Hexis 的实际效果
• 将 Hexis 连接到 Cline
• 试用在线演示
• 托管服务
• 使用 Docker 部署
• 知识页面中的链接和图片
• 本地开发
• 配置参考
• Cowork 和 claude.ai 中的技能
• 故障排除
• 仓库布局
• 常见问题

观看完整演示：连接 Agent、使用公司背景信息、审核提议的更改，并管理团队访问权限。

查看 Hexis 的实际效果

提议并批准技能更改

任何人都可以提议新技能或改进现有技能。在受保护的分支上，所有者会审核具体更改，并在其对团队的 Agent 开放使用前批准。

在 Claude 中使用团队技能

通过 MCP 将 Claude 连接到 Hexis，然后像平常一样提出请求。Claude 可以发现并加载你有权访问的已批准技能说明和公司背景信息，无需在工具之间复制提示词。

将 Hexis 连接到 Cline

Cline 可以直接连接到 Hexis，将其作为远程 Streamable HTTP MCP 服务。使用 Cline CLI 安装公开演示连接：

cline mcp install hexis --transport http https://demo.bevel.software/api/mcp --yes

出现提示时，在浏览器中完成 OAuth 登录。随后，Cline 会发现你在 Hexis 中有权访问的技能、工具和背景信息。若要连接自己的 Hexis 部署，请将 demo.bevel.software 替换为你的部署主机名。

与合适的人员共享技能

将团队成员添加到角色中，或在需要时直接授予访问权限。所有人都连接到同一个工作区，同时每个人及其 Agent 只能看到获准阅读的内容。

先试用：在线演示

demo.bevel.software 是一个公开实例，你可以使用 Google 账号登录，其中预置了一家虚构公司的知识、技能和工具。Start here 页面将带你走完整个流程：通过 MCP 连接自己的 Agent，让它根据一项技能制作销售演示文稿，并查看它提交的改进建议如何作为更改请求出现。此演示由多人共享，且以只读为主（访客可以提议，所有者负责批准）；下文将介绍如何部署功能相同、没有任何限制的实例。

想要托管实例？

我们会为你管理一切（托管、升级、备份、SSO），你的团队只需登录即可。请发送邮件至 [email protected]。

5 分钟内完成部署（Docker）

你需要：Docker 和 Compose，运行在一台 服务器上（也可以是你的笔记本电脑；下面会多一行操作），以及一个位于任意托管平台（GitHub、GitLab、Bitbucket、Azure DevOps、 可自托管）的空 Git 仓库，用于存放你的知识库。应用首次运行时会在仓库中初始化一个入门模板。

获取这两个部署文件——无需克隆仓库：

mkdir hexis && cd hexis
# v0.15.1 below = the release this page was written against; replace with the latest release tag
wget https://raw.githubusercontent.com/Bevel-Software/Hexis/v0.15.1/docker-compose.yml
wget -O .env https://raw.githubusercontent.com/Bevel-Software/Hexis/v0.15.1/.env.example

（在 Git 克隆仓库中操作也完全相同——两个文件都位于仓库根目录； 运行 cp .env.example .env。）

打开 .env 并填写四个必填值（其他值可以稍后再设置）：

[email protected]     # the deployment owner, always an admin
ADMIN_PASSWORD=pick-something   # sign-in password; only with password login (SSO-only deployments drop it)
JWT_SECRET=…                    # generate with the command below
SECRETS_ENC_KEY=…               # generate with the command below

生成两个密钥（运行两次，并将每次的结果分别粘贴到对应位置）：

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
# no Node installed? docker run --rm node:22-slim node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

如果要通过随附的代理以 HTTPS 公开部署，还需要设置域名——它会自动推导其他所有公开配置（源站、代理跳数）：

DOMAIN=bevel.your-domain.com

然后启动所有服务。部署时会拉取 CI 在每次发布时推送的镜像——服务器上无需编译，因此小型实例就足够了。 在 .env 中固定版本（HEXIS_VERSION=0.15.1），避免后续 pull 意外升级——UPGRADING.md介绍了升级和备份。 如果要改为从源代码构建（例如，让跟踪某个分支的暂存服务器运行，或使用一个分支），请使用 deployment/docker-compose.build.yml （说明见 deployment/）。

通过自己的反向代理提供公开 HTTPS（例如一台裸 EC2 实例或普通 VPS）： https 配置组会在应用前启动 Caddy，并为 DOMAIN 自动申请 Let's Encrypt 证书，同时将 HTTP 重定向到 HTTPS。首先：为域名设置一条指向服务器的 DNS A（或 AAAA）记录，并向互联网开放 80 和 443 端口（80 端口不可省略——证书验证和重定向都会用到它）。

docker compose -f docker-compose.yml --profile https up -d

位于你自己的反向代理后面（Coolify、Traefik、nginx）：不要启用配置组——同一个应用上有两个组件终止 TLS 就太多了。请不要设置 DOMAIN，而是在 .env 中设置源站值和代理跳数，这样 OAuth 重定向才能正确生成，速率限制也能获取真实客户端 IP，而不是代理的 IP：

PUBLIC_BACKEND_URL=https://bevel.your-domain.com   # public origin; OAuth redirects are built from it
PUBLIC_FRONTEND_URL=https://bevel.your-domain.com  # same origin: the backend serves the SPA
TRUST_PROXY=1                                      # your proxy hop count

docker compose -f docker-compose.yml up -d

这里显式使用 -f 很重要：在克隆仓库中操作时，它会跳过 docker-compose.override.yml， 因此应用不会发布主机端口——你的代理可以通过 Compose 网络在端口 3001 访问应用。这是有意为之：固定的已发布端口会导致每次重新部署都失败并报错 port is already allocated，因为替换容器启动时，旧容器仍占用该端口。

打开你的域名，并使用 ADMIN_EMAIL / ADMIN_PASSWORD 登录。

只想在笔记本电脑上试用？ 步骤相同，但无需设置 DOMAIN 和源站值——另外还需一个文件：单独使用 docker-compose.yml 不会发布主机端口（见上文），而 docker-compose.override.yml 会让应用监听 localhost。克隆仓库中已包含该文件；如果使用 wget 下载文件，也请一并获取：

wget https://raw.githubusercontent.com/Bevel-Software/Hexis/v0.15.1/docker-compose.override.yml
docker compose up -d

然后打开 **http://localhost:3001**（也可以使用其他端口： APP_PORT=8080 docker compose up -d）。此处不要设置 TRUST_PROXY——没有代理时，信任转发的标头会让客户端伪造自己的地址。

首次登录：设置页面

应用会询问它无法推断的信息，并在保存前使用真实主机进行测试：

1. 知识库仓库：该空仓库的 https 克隆 URL。
2. Git 凭据：具有该仓库读写权限的令牌（对于 GitHub：仅需一个对此仓库具有 Contents: read & write 权限的细粒度个人访问令牌）。
3. 分支模型：哪个分支是默认分支，哪些分支受保护（对受保护分支的更改只能通过已批准的变更请求提交）。系统会将仓库中的实际分支作为建议；对于空仓库，默认分支（main）即可。

由于仓库为空，应用会使用随附模板初始化仓库，并写入一个 roles.yaml，将你设为首位 Admin。就是这样：你已进入工作区。前往 技能与工具 创建你的第一个插件和技能，然后前往 连接（在应用菜单中）通过 MCP 连接 Agent。

准备投入生产？配置参考介绍了单点登录、需要备份的状态、健康检查，以及如何通过环境变量而非设置页面进行配置。

知识页面中的链接和图片

页面采用 Markdown 格式。指向其他页面的链接使用相对路径，Hexis 会在应用中打开该页面：

See the [approval process](../Processes/Approval.md#steps).

图片也使用相同方式处理。将图片放在使用它们的页面旁边的 assets/ 文件夹中，并使用相对路径链接：

![Approval screen](./assets/approval-screen.png)

访问权限遵循文件夹，因此，可以阅读页面的人也可以查看其中的截图；移动文件夹后，所有链接仍然有效；而共用一个 Uploads/ 文件夹则无法满足这两点。导出内容如果附带同级的 .assets/ 文件夹（例如 Microsoft Loop 导出的内容），可以直接放入知识库，链接无需更改即可正常解析。不支持粘贴 base64 图片：请保存文件并创建链接。

本地开发（从源码运行）

你需要：Node 22.13 或更新版本（.nvmrc；引擎版本范围为 >=22.13 <23）、pnpm 10、git ≥ 2.41 和一个 Postgres 17（使用随附版本即可）：

docker compose up -d db        # just the database
pnpm install
pnpm build                     # builds the packages the apps import
cp .env.example .env           # fill the same four required values;
                               # the default DATABASE_URL already points at the bundled db
pnpm dev                       # backend on :3001, Vite dev server on :5173

打开 **http://localhost:5173**（开发服务器会将请求代理到后端）。常用命令：`pnpm test、pnpm typecheck、pnpm lint`。

迁移会在启动时自动运行；无论在开发环境还是生产环境，都不需要单独执行迁移步骤。

参考

• 配置：所有环境变量、SSO 设置、密钥生成、备份和健康检查。
• 在一个进程中运行多个知识库：租户文件、隔离的内容，以及如何将租户迁移到独立部署。
• 故障排查：最可能遇到的问题及其原因。

仓库结构

路径	说明
packages/shared	@bevel-software/platform-shared：共享类型 + 纯领域工具
packages/core-backend	@bevel-software/platform-core-backend：核心后端（包含 migrations/ + kb-template/）
packages/core-frontend	@bevel-software/platform-core-frontend：核心 UI，以原始 TS/TSX 源码形式发布
apps/server	独立的核心后端外壳
apps/web	独立的核心 SPA 外壳（Vite）

常见问题

团队在评估 Hexis 是否适合作为 Agent 技能和工具的集中式版本化目录时，常会提出以下问题。

Agent 如何查找技能，而不让上下文窗口塞满？

它们会查找，而不是一次性加载所有技能：list_skills 和 search 可缩小范围，get_skill 则会在调用时返回单个技能。

Agent 如何知道知识库中有什么？

每个 MCP 会话都会以指令开始：固定的平台说明会介绍 Hexis，并要求先搜索知识库，再根据记忆作答；之后是存储库根目录中的 mcp-description.md，由管理员说明知识库包含哪些内容以及何时查阅。会读取握手信息的客户端（Claude Code、Claude Desktop、Cursor）会将其放入系统提示词；对于不会读取握手信息的客户端，首行说明也会显示在四个核心工具上。外部 Agent 访问页面会准确展示 Agent 能获取的内容。

哪些 Agent 可以连接？

任何支持 MCP 的客户端都可以连接，包括 Claude Code、Codex、Cursor、Cline 和 ChatGPT；每个客户端只能看到其用户角色允许查看的内容。

在你自己的机器上运行的 Agent，也可以将工作区作为本地 MCP 服务启动（npx -y @bevel-software/hexis-mcp），这样除了托管端点提供的工具，还能使用插件中的仅限本地工具。此命令需要 Node 22.13+ or 24——这些版本随附沙盒预构建的二进制文件——而从 Dock 或桌面图标启动的客户端可能根本无法在 PATH 中找到 npx：运行 which npx（Windows 上运行 where npx），并将输出的完整路径用作 "command"。请参阅 故障排除。

目录如何进行版本控制？

通过 git：每次保存都会生成一个提交，因此历史记录、责任追溯和还原的工作方式与代码相同；对受保护分支的更改则会以可供审查的变更请求形式发布。

我们能获得哪些治理能力？

按文件设置访问控制、通过审查的变更请求，以及记录谁更改了什么、谁批准了更改的 git 审计轨迹。

许可证：Apache-2.0