# Helix AI 接入体系手册

> 面向全公司的完整指南:MCP / CLI / 插件 / 连接器是什么、怎么用、怎么选,
> 以及——如果你的团队想给自己的系统做同样的能力——照 Helix 这套生产级
> 标准怎么建。
>
> 本文是知识库版本的源文档,维护在 Helix 仓库 `docs/kb/`;产品内随时可用
> 的精简版见 Helix「帮助中心 → AI 助手集成」。

---

# 上篇 · 概念与使用(零基础可读)

## 1. 一句话看懂这些名词

想象公司里有一位什么都知道的 IT 同事。过去你要自己登系统、点菜单、填表单;
现在你可以直接对 AI 说「我的电脑是哪台?」「帮我申请个 Zoom 坐席」,AI 替你
去和系统打交道。要让 AI 有这个本事,需要几样东西配合:

| 名词 | 一句话解释 | 生活化类比 |
|------|-----------|-----------|
| **MCP** | 让 AI 能调用某个系统的「标准接口协议」 | 电器上的 USB-C 口:任何牌子的线都能插 |
| **MCP Server** | 某个系统按 MCP 标准暴露出来的能力集合 | Helix 这台「电器」上的那个 USB-C 口 |
| **工具 (Tool)** | MCP Server 里的一个具体能力 | 「查我的资产」「提交申请」都是一个工具 |
| **连接器 (Connector)** | 在 claude.ai / Claude Desktop 里添加一个 MCP Server | 把线插上并登录授权 |
| **插件 (Plugin)** | Claude Code(终端版 Claude)的一键安装包 | 手机装 App:连接+玩法+快捷键一次到位 |
| **CLI** | 不经过 AI、在终端直接调用系统的命令行工具 | 遥控器:自己按按钮,不用跟 AI 说话 |
| **PAT(个人令牌)** | 一串代表「你本人」的密钥,给脚本/客户端用 | 一把只开你自己抽屉的钥匙 |
| **OAuth** | 浏览器里登录授权、不用复制密钥的方式 | 刷脸进门,不用配钥匙 |

**为什么 MCP 重要**:它是厂商中立的行业标准(Anthropic 发起,OpenAI、
Cursor 等均已支持)。Helix 只建了一个 MCP Server,所有支持 MCP 的 AI
客户端就都能用——不需要为每个客户端单独开发。

## 2. 安全模型:先吃三颗定心丸

无论从哪条路接入,下面三条铁律完全一致:

1. **AI 拿到的永远是「你本人」的权限**——你在网页上看不到的,AI 也看不到。
   管理员的 AI 能做管理员的事,普通员工的 AI 不能。
2. **写操作照走审批**——AI 说「已提交申请」,意思是它替你点了「提交」,
   审批链(飞书审批到 IT/资产管理员)一步没少。AI 不是绕过治理的后门。
3. **每一步都有审计**——AI 的每次调用都记录在审计日志里(动作、时间、
   令牌、IP),离职后所有接入自动失效。

## 3. 我该用哪条路?(六路径决策)

按「覆盖人群从广到窄」排列,从上往下找到第一条适合你的:

| 你是谁 | 走哪条路 | 要做什么 |
|--------|----------|---------|
| 所有人,不想配置任何东西 | **Helix 站内 AI 助手** | 打开 Helix 网页,右下角直接问 |
| 用 claude.ai 网页版 / Claude Desktop | **Claude 连接器(OAuth)** | 贴一个 URL,浏览器登录一次 |
| 用 Claude Code 终端的工程师 | **Claude Code 插件** | `helix plugin install` 一条命令 |
| 写脚本、跑自动化 | **helix CLI** | 帮助中心下载,配一次 PAT |
| 用 Cursor 等其他 MCP 客户端 | **MCP 直连** | 贴同一个端点 URL |
| 做系统对系统集成的团队 | **对外 API(helix_api_)** | 申请机器凭证,按 scope 授权 |

> 记住:选哪条只是「入口」的区别,不是「权限」的区别。

## 4. 手把手:四条主路的接入步骤

### 4.1 Claude 连接器(零安装,推荐给最多人)

1. 打开 claude.ai(或 Claude Desktop)→ 设置 → Connectors → **Add custom connector**
2. URL 填:`https://helix.pingcap.net/api/v1/mcp`,连接方式选 **Individual sign-in**
3. 浏览器跳转到 Helix 登录(Google/飞书)→ 出现授权同意页 → 点「授权」
4. 完成。试一句:「用 helix 看看我名下有哪些设备」

不需要创建任何令牌;想撤销时到 Helix「设置 → 已连接应用」一键断开。

### 4.2 Claude Code 插件(工程师)

已装 helix CLI 的(推荐):

```bash
helix plugin install     # 下载 + 校验 + 自动注册到 Claude Code
```

没装 CLI 的:帮助中心 → AI 助手集成 → Claude Code 插件 → 下载 zip,解压后:

```bash
unzip ~/Downloads/helix-claude-plugin.zip -d ~/.helix/
claude plugin marketplace add ~/.helix/helix-claude-plugin
claude plugin install helix@helix
```

> 路径必须以 `~/`、`./` 或 `/` 开头。如果报
> `SSH authentication failed / Permission denied (publickey)`,
> 说明路径丢了开头的 `~/.`——claude 把 `helix/helix-claude-plugin`
> 当成 GitHub 仓库去 clone 了,不是本地文件权限问题;补全路径重跑即可。

装完你会得到:Helix MCP 连接(首次使用时浏览器弹 SSO 授权,零令牌)、
一组玩法剧本(AI 自动知道怎么组合 400+ 工具)、五个斜杠命令:
`/helix:whoami`、`/helix:my-it`、`/helix:approvals`、`/helix:costs`、`/helix:support`。
更新:`helix plugin update`。

### 4.3 helix CLI(脚本与自动化)

1. 帮助中心 → AI 助手集成 → helix CLI:按你的系统下载单文件二进制(免 Python)
2. 「一键创建 PAT」拿到令牌,然后:

```bash
helix config set-url https://helix.pingcap.net
pbpaste | helix auth token set --token-stdin   # 从剪贴板读,不进 shell 历史
helix whoami                                    # 验证
helix mcp call list_my_assets --arg page=1      # 调任意工具
```

退出码契约(可编排):0 成功 / 1 用法错 / 2 未授权 / 3 越权 / 4 远程拒绝 / 5 网络错。
危险操作(如 `server_destroy`)CLI 会强制二次确认,`--yes` 才能跳过。

### 4.4 其他 MCP 客户端(Cursor 等)

贴同一个端点 `https://helix.pingcap.net/api/v1/mcp`:支持 OAuth 的客户端
(含 Cursor)会自动引导浏览器登录;不支持的配请求头
`Authorization: Bearer helix_pat_…`。

## 5. AI 能帮你做什么(示例)

- **查**:「我手里有哪些硬件?」「我在 ap-northeast-1 有哪些云服务器?」
  「哪些审批还在等?」「我名下的域名哪些快到期?」「这个月我的 IT 成本?」
- **办(走审批)**:「申请一个 Zoom 坐席,理由是客户演示」「给我邮箱加个
  sales-china@ 别名」「借用资产 HX-LP-0042,6 月 1 日还」
- **官方剧本(Prompts)**:支持的客户端里直接选用——我的 IT 全景 / 审批
  一览 / 成本体检 / 离职交接清单 / 入职进度。

---

# 下篇 · 建设指南(给想照做的团队)

> 目标读者:想给自己的系统(报销、CRM、工单、数据平台……)加上同样 AI
> 能力的工程团队。Helix 的实现全部开源在公司仓库,可直接抄。

## 6. 总架构:一个中心,多个入口

```
                         ┌────────────────────────────┐
 claude.ai / Desktop ───▶│                            │
 Claude Code 插件 ──────▶│   你的系统的 MCP Server     │──▶ 业务逻辑
 Cursor 等客户端 ───────▶│  (鉴权/审计/审批在这一层)   │      │
 CLI(mcp call)─────────▶│                            │   数据库
                         └────────────────────────────┘
```

**核心原则:能力只建一次。** MCP Server 是唯一的能力中心;插件、CLI、
连接器都只是它的「入口薄壳」。Helix 的 CLI 没有重复实现任何业务——
`helix assets list` 内部就是 `mcp call list_my_assets`。

## 7. 建一个生产级 MCP Server 的十条军规

以下每条都有 Helix 真实代码可参照(路径均在 Helix 仓库):

1. **身份随请求走,权限随人走** —— 每个工具调用解析出「哪个员工」,复用
   系统既有 RBAC,绝不给 AI 单独开一套权限。参照
   `server/app/mcp/middleware.py`(PAT/OAuth 双通道)+ `runtime.py`
   (每请求从 DB 现查角色)。
2. **双鉴权:PAT 给配置文件,OAuth 给 GUI** —— GUI 连接器(claude.ai)
   只认 OAuth 发现(RFC 9728/8414/7591/7636):access token 短时效 +
   audience 绑定,refresh 单次轮换。参照 `server/app/auth/oauth/`。
3. **写操作过既有审批链** —— mutating 工具只是「替用户提交」,别让 AI
   直连改库。Helix 每个写工具都进 Feishu 审批或幂等任务队列。
4. **全量审计** —— 每次调用记 `action="mcp.<tool>"` + trace_id + 令牌 ID。
5. **工具注解自动化** —— `readOnlyHint`/`destructiveHint` 别手写 400 行
   表,从代码里的读写事实源推导(Helix 用启动时 AST 解析,见
   `server/app/mcp/annotations.py`);危险清单与 CLI 确认清单用测试锁等。
6. **描述写给 AI 看** —— 工具 description 讲清「什么时候用我、参数怎么
   填、返回什么、和相邻工具怎么区分」,并与 HTTP 端点 1:1 对应。
7. **Resources + Prompts 别漏** —— 平台自述与实时工具目录做成 Resources;
   高频流程做成官方 Prompts,所有客户端共享(见 `resources.py`/`prompts.py`)。
8. **幂等 + 限流 + 版本闸** —— 写操作幂等;按用户限流;客户端 UA 带版本,
   服务端可设最低版本 kill-switch(参照 `CLI_MIN_SUPPORTED_VERSION`)。
9. **离职即失效** —— 令牌/授权全部挂在人身上,离职流程统一吊销;写操作
   另有 Leaver 闸兜底。
10. **测试锁契约** —— 工具数量 hint、注解全覆盖、危险清单一致性、鉴权
    401/403,全部有回归测试(参照 `server/tests/test_mcp*`)。

## 8. CLI:MCP 的薄壳,不是第二套后端

- 只依赖 HTTP 客户端 + 标准库,能打成单文件二进制分发(PyInstaller)
- 一切业务命令 = `mcp call <tool>`;便捷命令只是别名
- 安全细节照抄:令牌只从 stdin/env/配置文件读(绝不接受 `--token` 参数)、
  输出全量密钥脱敏、`https://` 强制、危险工具 TTY 二次确认
- 分发:CI 构建 → S3 固定命名空间 + `latest/manifest.json` → 产品内
  下载卡(presigned URL + sha256 展示)。参照 `.github/workflows/cli-release.yml`
  + `server/app/domains/cli_dist/`

## 9. Claude Code 插件:打包与分发

- 结构:marketplace 目录(`.claude-plugin/marketplace.json`)包插件目录
  (`.claude-plugin/plugin.json` + `.mcp.json` + `skills/` + `commands/`)
- **`.mcp.json` 零凭证**:不带 Authorization 头,让客户端走 OAuth 发现;
  用 `${VAR:-default}` 支持本地 dev 覆盖
- Skills 写「怎么组合工具办成事」,不是复述工具列表;工具名必须与注册面
  实名对齐(上线前跑校验)
- **分发坑(实测)**:HTTPS URL 直挂 marketplace.json 时相对路径插件源
  不解析,外源必须 git/npm——内网场景打整目录 zip 放对象存储,员工本地
  目录注册;配套 `<cli> plugin install/update` 做安装器(sha256 校验 +
  zip-slip 防护 + 原子换入固定路径)。参照 Helix `plugin/` + DECISIONS
  2026-07-09
- **MCPB(Claude Desktop 扩展包)不要做**:只支持本地 stdio,远程 HTTP
  系统硬塞要捆本地桥 + 长效令牌,劣于 OAuth 连接器

## 10. 工程侧配套(团队内提效,不是平台对外能力)

- **CLAUDE.md / AGENTS.md**:仓库根放一份「AI 上岗说明书」——架构地图、
  不可协商规则、验证命令、文档更新纪律。Helix 的 `CLAUDE.md` 是范本;
  关键经验:让 AI「先查已有能力再动手」(Helix 曾差点重复建已上线的
  OAuth 服务)。
- **Hooks / Subagents / 斜杠命令**:Claude Code 的项目级扩展点,放
  `.claude/` 目录;适合编码规范强制、专用审查代理、常用操作快捷键。
- **GitHub Action**:@claude 进 PR 做审查/修复的接法,适合 CI 侧。
- **Agent SDK**:当你要把 AI 助手嵌进自己的产品界面(像 Helix 站内
  copilot),用 Agent SDK 自建,底下同样接 MCP。

## 11. 安全与治理清单(企业必答题)

- [ ] AI 通道权限 == 网页权限(无独立提权面)
- [ ] 写操作 100% 过审批链;danger 工具有客户端确认注解 + CLI 二次确认
- [ ] 全量审计带 trace_id,可从令牌反查人/IP/动作
- [ ] OAuth: PKCE + 短时效 + audience 绑定 + refresh 轮换;PAT: 前缀可识别、
  有效期、每设备一枚、最近使用可见、可单独吊销
- [ ] 离职自动失效(令牌 + OAuth 授权 + 写闸三层)
- [ ] Prompt injection 意识:工具描述/资源内容是「给 AI 的指令面」,
  上线前审一遍;不在描述里放可被外部数据污染的动态内容
- [ ] Confused deputy:服务端校验的是「令牌属主」的权限,绝不信客户端
  自称的身份
- [ ] 分发完整性:制品带 sha256,安装器校验;marketplace/zip 内容有
  结构校验挡投毒
- [ ] 版本 kill-switch:发现漏洞可全员强制升级
- [ ] 新能力登记:新建 MCP Server 后在 IT 知识库登记(名称/端点/负责人/
  scope),并给 Helix IT 报备纳入连接器准入清单

## 12. 一页速查

| 你要做的事 | 抄哪里 |
|------------|--------|
| MCP Server 鉴权/审计/运行时 | `server/app/mcp/{middleware,runtime}.py` |
| OAuth 授权服务 | `server/app/auth/oauth/` |
| 工具注解自动推导 | `server/app/mcp/annotations.py` |
| Resources / Prompts | `server/app/mcp/{resources,prompts}.py` |
| CLI 骨架与安全细节 | `cli/helix_cli/` |
| CLI/插件 S3 分发管线 | `.github/workflows/{cli,plugin}-release.yml` |
| 产品内下载卡/帮助页 | `web/src/pages/help/` |
| 插件本体 | `plugin/marketplace/` |
| 决策依据(为什么这么做) | `docs/architecture/DECISIONS.md` 2026-06-18/23、2026-07-09 |

---

*维护:IT — Helix 平台。产品内精简版:Helix → 帮助中心 → AI 助手集成。*
*本文随平台演进更新;发现内容过期请提工单或直接改仓库源文件。*