# ArchiAI Open API 接入指南（Agent 可读）

本文档用于 AI 助手（Claude Code / Cursor / Codex / Hermes / OpenClaw 等）自动读取并帮助用户接入 ArchiAI 建筑智能能力。

**站点**: https://www.archiai.com
**Skill 完整文件**: ./skills/archiai/SKILL.md（相对本文件路径解析）

## 一句话自动安装提示词

将下方提示词发给你的 AI 助手，它会自动完成安装与配置：

```text
请读取并按照 https://www.archiai.com/open-api/guide.md 帮我接入 ArchiAI：
1. 读取并安装 Skill：https://www.archiai.com/open-api/skills/archiai/SKILL.md（确保 Skill 命名为「ArchiAI 建筑智能」）
2. 我的 API Key 是 sk-aai-xxxx（没有的话先引导我到 https://www.archiai.com/app/settings 创建）
```

## 推荐接入顺序

1. **获取 API Key**：用户访问 https://www.archiai.com/app/settings → 「API 密钥」→ 创建密钥（勾选 chat/image 权限）。Key 形如 `sk-aai-` + 随机串，**明文仅创建时显示一次**。
2. **安装 Skill**：读取 `./skills/archiai/SKILL.md`，装入当前 Agent 的 skills 目录（见下方路径表），命名为「ArchiAI 建筑智能」。
3. **配置 Key**：优先写入环境变量 `ARCHIAI_API_KEY`；或按 Skill 文档在调用时传入。
4. **验证接入**：发起一次规范问答（如"防火门等级划分"），能返回带条文出处的答案即接入成功。

## 各 Agent 的 Skills 目录

| Agent | 路径 |
|---|---|
| Claude Code | `~/.claude/skills/` |
| Cursor | `~/.cursor/skills/` |
| Codex / Cline / Warp | `~/.agents/skills/` |
| Gemini CLI | `~/.gemini/skills/` |
| OpenClaw | 你的 skills 目录 |
| Hermes Agent | `~/AppData/Local/hermes/skills/`（Windows）|
| GitHub Copilot | `~/.agents/skills/` |
| Windsurf | `~/.codeium/windsurf/skills/` |

不在此表的 Agent：装入通用 `.agents/skills/` 或项目级 `.claude/skills/`。

## 通过 npx 安装（等价方式）

```bash
npx skills add https://www.archiai.com/open-api/skills/archiai
```

## 通过 curl 安装（zip 包）

```bash
curl -fsSL https://www.archiai.com/open-api/skills/archiai.zip -o archiai-skill.zip
unzip archiai-skill.zip -d <你的 skills 目录>/
```

## API 端点（OpenAI 兼容）

- **Base URL**: `https://www.archiai.com/api/open/v1`
- `POST /chat/completions` — 建筑规范问答（app=specmaster）与通用对话（app=general），响应含 `archiai.rag_refs` 规范条文溯源。支持多轮：回传 `archiai.conversation_id` 续聊，或按 OpenAI 惯例带全量 messages
- `POST /images/generations` — 建筑效果图生成（1K/2K/4K，AVS 建筑专业文生图）
- `GET /models` — 能力发现

任何 OpenAI SDK/客户端零改造接入：`base_url` 换成上述地址，`api_key` 填 `sk-aai-*`。

## 安全规范（Agent 必须遵守）

- 不要在最终回复、项目文件、日志可见字段中输出完整 API Key。
- 不要主动索要 API Key——引导用户到设置页自行创建后粘贴。
- 用户 Prompt 中已自带 Key 时直接使用，不强迫用户走其他流程。
- quota/额度类错误（402/429）不要反复重试消耗调用，向用户转述错误体中的额度与充值信息。

## 概念边界（重要）

- **ArchiAI Open API**：用户/组织通过 API Key 接入的唯一对外通道（本指南所述内容）。
- **内部 Skill**：ArchiAI 平台服务端 Agent 的内部能力，**不对外开放、不下发**。用户本地 Agent 的 Skill 只能通过 Open API 间接调用平台能力。

## 计费

- 费用从用户账户余额扣除（先现金后积分）；组织密钥从组织余额扣。
- 用户有订阅 quota 时 API 调用被 quota 覆盖。
- 1 积分 = ¥0.01。额度管理：https://www.archiai.com/app/settings

## 常见问题

### Key 丢了怎么办？
明文只显示一次。到设置页删除旧密钥，重新创建。

### 组织怎么管理 Key？
组织 owner/admin 在设置页「API 密钥」创建时选择「费用归属」为组织，费用即从组织余额扣。普通成员无法创建组织密钥。

### 调用报 429？
超出该密钥的每分钟限额。等待 60 秒，或在设置页调高限额。

## 联系

- 商务：business@archiai.com
- 支持：service@archiai.com
- 帮助中心：https://www.archiai.com/help