内容
# APIPASS 无界面版适用于 Claude 代码
**APIPASS 无界面版** 是指在没有图形界面的情况下操作 APIPASS 平台 — 通过自然语言，使用 AI 助手。本仓库提供了第一个集成：适用于 [Claude 代码](https://claude.com/claude-code) 的官方插件 `apipass-integrations`。
通过与 Claude 对话，您可以构建、发布、测试和调查 APIPASS 集成 — 您只需描述所需的内容，Claude 就会规划、构建、验证和执行，并通过托管的 MCP 服务器（MCP Server）与平台通信。
本仓库是一个 **Claude 代码插件市场**。`apipass-integrations` 插件由以下部分组成：
- **技能**（命令 `/apipass-integrations:*`）— 构建流程、搜索操作、创建自定义操作、审查、记录和消耗分析。
- **子代理** — 专门用于搜索目录操作和在隔离会话中创作自定义操作。
- **钩子** — 在进行任何具有实际影响的操作之前（发布、测试、重新执行）需要确认。
- **托管的 MCP 服务器** — 与 APIPASS 平台通信的工具；无需本地运行。
## 要求
- 已安装 [Claude 代码](https://claude.com/claude-code)。
- 一个 APIPASS 账户（您的 **accountName**，用于解析 Keycloak 的 realm）。
- 可以访问生产环境的 MCP 服务器（`https://elb.apipass.com.br/mcp`）。
## 安装
在 Claude 代码中：
```
/plugin marketplace add https://github.com/APIPASS-Integrations/apipass-plugins.git
/plugin install apipass-integrations@apipass-plugins
/reload-plugins
```
> 无需本地运行：插件已指向 APIPASS 的托管 MCP 服务器。
## 首次使用（登录）
每个人都使用 **自己的账户** 进行身份验证。在请求第一个操作时（例如，“列出我在 APIPASS 中的项目”），Claude 将回复您需要登录。运行：
```
apipass_login account_name="您的账户"
```
在浏览器中打开返回的 URL，在您的账户的 Keycloak 中授权，然后返回 Claude。令牌保留在您的会话中并自动续期。实用工具：`apipass_auth_status`（查看状态）和 `apipass_logout`（退出）。
## 可以完成的操作
- **构建流程**：“构建一个将 X 与 Y 同步的流程”。Claude 发现操作（目录 + 固定操作），组装步骤，并在保存之前验证。
- **版本控制和发布**：保存开发版本 -> 创建版本 -> 在环境中发布（需确认）。
- **测试**：使用有效载荷（需确认）运行流程测试。
- **调查执行**：列出日志，打开执行，读取步骤的有效载荷，查看摘要。
- **重新执行/停止** 执行（需明确确认）。
具有实际影响的操作（创建/保存/发布/测试/重试/停止）始终需要确认。
## 更新
当有新版本的插件时：
```
/plugin marketplace update apipass-plugins
/reload-plugins
```
## 可用命令（技能）
流程构建：
- `/apipass-integrations:build-flow` — 构建/修改集成流程（入口点）
- `/apipass-integrations:build-agent-flow` — 构建/修改 AI 代理流程（RAG，知识库）
- `/apipass-integrations:research-action` — 搜索目录中的操作
- `/apipass-integrations:create-action` — 从 API 文档创建自定义操作
参考：
- `/apipass-integrations:apipass-actions` — 目录 + FlowStep 剖析
- `/apipass-integrations:apipass-agent-actions` — AI 操作目录（Agent Builder）
- `/apipass-integrations:apipass-patterns` — 结构、版本控制、发布、测试
- `/apipass-integrations:apipass-gotchas` — 常见错误和执行调试
分析和维护：
- `/apipass-integrations:review-flow` — 审核流程是否符合最佳实践
- `/apipass-integrations:diff-versions` — 比较流程版本
- `/apipass-integrations:document-flows` — 生成项目流程文档（Word/PDF）
- `/apipass-integrations:apipass-usage` — 账户消耗/使用分析
账户：
- `/apipass-integrations:set-account` — 在登录时设置账户（realm）
## 如何贡献
欢迎贡献 — 从报告问题到提出新的技能。
### 报告错误和建议改进
打开一个 [issue](https://github.com/APIPASS-Integrations/apipass-plugins/issues)，描述发生了什么（或您希望如何）。对于错误，请包括您使用的命令/请求、期望结果和实际结果。
### 发送更改
1. 复刻仓库并从 `main` 分支创建分支（例如 `feat/我的技能`，`fix/简短描述`）。
2. 按照以下结构和约定进行更改。
3. 在本地测试（参见下文）。
4. 打开一个拉取请求到 `main` 分支，描述更改和原因。
### 仓库结构
```
.claude-plugin/marketplace.json # 市场目录（名称，版本，描述）
plugins/apipass-integrations/
.claude-plugin/plugin.json # 插件清单（版本，元数据）
.mcp.json # 插件使用的托管 MCP 服务器
skills/<名称>/SKILL.md # 命令 /apipass-integrations:<名称>
agents/<名称>.md # 专用子代理
hooks/hooks.json + *.js # 确认门控（PreToolUse）
```
### 约定
- **语言：** 技能、代理和文档使用葡萄牙语（pt-BR），与插件其余部分一致。
- **技能：** 每个技能位于 `skills/<名称>/SKILL.md`，具有前置信息（`name`，`description`）。`description` 是 Claude 决定何时加载技能的内容 — 应具体。
- **版本：** 修改插件行为时，在 **`plugin.json` 和 `marketplace.json`** 中增加 `version`（两者应保持相同），并在 [CHANGELOG.md](CHANGELOG.md) 中添加条目。
- **绝不** 在代码或文档中嵌入凭证、令牌或内部 URL。
### 在本地测试
将 Claude 代码指向您的本地副本，而不是远程仓库：
```
/plugin marketplace add /路径/到/apipass-plugins
/plugin install apipass-integrations@apipass-plugins
/reload-plugins
```
编辑技能、代理或钩子后，运行 `/reload-plugins` 以重新加载而无需重新安装。
## 支持
登录问题（`invalid redirect_uri`，`client not found`）由 Keycloak 中的客户端注册引起；401/403 来自网关。请与平台团队联系。
