karuo-ai/运营中枢/参考资料/卡若AI外网化与外部调用方案.md

# 卡若AI 外网化与外部调用方案

> 目标：让卡若AI 可从外网访问，其他 AI 或任意终端用「一句话/一个命令」即可按卡若AI 的思考逻辑调用并生成回复。
> 版本：1.0 | 更新：2026-02-17

---

## 一、目标与效果

| 目标 | 说明 |
|:---|:---|
| 外网可访问 | 不限于本机，任意网络通过域名或 IP:端口 访问卡若AI。 |
| 按卡若AI 思考逻辑生成 | 每次请求走：先思考 → 查 SKILL_REGISTRY → 读对应 SKILL → 生成回复 → 带复盘格式。 |
| 其他 AI 可集成 | 其他 AI（Cursor、Claude、GPT、自建 Bot）执行一条命令或请求一个 URL，即「用卡若AI 能力」完成对话。 |
| 最终交付 | 给你：**可执行命令**、**调用链接/域名**，在 Cursor 或其它 AI 里输入即用。 |

---

## 二、实现形式（架构）

```
外部（其他 AI / 用户）
        │
        │  HTTP POST /chat  或  打开网页
        ▼
┌─────────────────────────────────────────────────────┐
│  卡若AI 网关（API 服务）                              │
│  · 接收 prompt                                       │
│  · 加载 BOOTSTRAP + SKILL_REGISTRY                    │
│  · 匹配技能 → 读 SKILL.md                            │
│  · 调用 LLM（本地或云端 API）按卡若AI 流程生成        │
│  · 返回：思考 + 执行摘要 + 复盘块                     │
└─────────────────────────────────────────────────────┘
        │
        │  部署在：宝塔服务器（推荐，固定域名）或 本机 + 内网穿透
        ▼
  外网域名：https://kr-ai.quwanzhi.com（标准方案见下）
```

**两种使用方式：**

1. **API 调用**：其他 AI 或脚本向 `POST /v1/chat` 发 `{"prompt": "用户问题"}`，拿 JSON 里的回复（含复盘）。
2. **网页对话**：浏览器打开同一服务的 `/` 或 `/chat`，输入问题，页面上展示卡若AI 风格回复。

---

## 三、部署方式二选一

### 方式 A：宝塔服务器 + 固定域名（推荐，替代 ngrok）

- **域名**：**kr-ai.quwanzhi.com**（阿里云解析 + 宝塔 Nginx + SSL，电脑关机也可访问）。
- **部署**：网关部署在 kr宝塔 43.139.27.93；一键脚本：`bash 01_卡资（金）/金仓_存储备份/服务器管理/scripts/部署卡若AI网关到kr宝塔.sh`。
- **完整步骤**（阿里云 DNS、Nginx、自启）：见 **`01_卡资（金）/金仓_存储备份/服务器管理/references/内网穿透与域名配置_卡若AI标准方案.md`**。
- **执行命令 / 链接**：  
  - 链接：`https://kr-ai.quwanzhi.com`  
  - 其他 AI 调用：`curl -s -X POST "https://kr-ai.quwanzhi.com/v1/chat" -H "Content-Type: application/json" -d '{"prompt":"你的问题"}' | jq -r '.reply'`

### 方式 B：本机 + 内网穿透（临时）

- 在本机运行卡若AI 网关，用 ngrok/cloudflared 得到临时 URL；本机关机则不可访问。仅作临时调试用。

---

## 四、网关脚本与运行方式

网关代码放在：**`运营中枢/scripts/karuo_ai_gateway/`**（`main.py` + `requirements.txt` + `README.md`）。  
运行前：

1. 安装依赖：`pip install fastapi uvicorn httpx`（若用 OpenAI 兼容接口，再装 `openai`）。
2. 配置环境变量（可选）：`OPENAI_API_KEY` 或本地模型地址，用于实际生成回复。
3. 启动：

```bash
cd /Users/karuo/Documents/个人/卡若AI/运营中枢/scripts/karuo_ai_gateway
uvicorn main:app --host 0.0.0.0 --port 8000
```

启动后：

- 本机访问：<http://127.0.0.1:8000/docs> 可调试接口。
- 外网访问：在方式 A 或 B 下用你得到的**域名或 IP:端口**替换下面示例中的 `YOUR_DOMAIN`。

---

## 四点五、接口配置化（科室/部门可复制）

> 目标：让以后任何科室/部门/合作方都能“拿到一套配置 + 一个 key”，直接调用卡若AI 网关，不需要改代码。

### 你需要提前准备什么（一次性）

1. **一个 salt**（只放环境变量，不写入仓库）：`KARUO_GATEWAY_SALT`
2. （可选）如果要真实 LLM 输出：`OPENAI_API_KEY`（以及 `OPENAI_API_BASE`、`OPENAI_MODEL`）
3. 外网场景：域名/反代已就绪（宝塔/Nginx）或 ngrok 临时暴露

### 配置文件在哪里

- 示例：`运营中枢/scripts/karuo_ai_gateway/config/gateway.example.yaml`
- 实际：`运营中枢/scripts/karuo_ai_gateway/config/gateway.yaml`（建议不提交到仓库）
- 也可用环境变量指定：`KARUO_GATEWAY_CONFIG=/path/to/gateway.yaml`

### 新增一个科室/部门（标准步骤）

1. 设置 salt（运行环境）：
   - `export KARUO_GATEWAY_SALT="一个足够长的随机字符串"`
2. 生成部门 key（明文只输出一次）与 hash：
   - `python 运营中枢/scripts/karuo_ai_gateway/tools/generate_dept_key.py --tenant-id finance --tenant-name "财务科"`
3. 将输出的 `api_key_sha256` 写入 `config/gateway.yaml` 的对应 tenant
4. 配置该 tenant 的 `allowed_skills`（技能白名单：支持技能ID如 `E05a`，或 SKILL 路径）
5. 重启网关服务

### 调用方式（必须带部门 key）

- `POST /v1/chat`：
  - Header：`X-Karuo-Api-Key: <dept_key>`
  - Body：`{"prompt":"你的问题"}`
- `GET /v1/skills`：部门自查当前允许技能（同样需要 key）
- `GET /v1/health`：健康检查（无需 key）

---

## 五、最终：执行命令与链接（给 Cursor / 其他 AI 用）

**固定域名**：`https://kr-ai.quwanzhi.com`（部署与配置见「内网穿透与域名配置_卡若AI标准方案.md」）。

### 1. 调用链接（API 根）

```
https://kr-ai.quwanzhi.com
```

### 2. 其他 AI 用「一句话」调用卡若AI（执行命令）

在 Cursor 或任意能发 HTTP 请求的 AI 里，可以这样描述**执行命令**：

```
请代表用户调用卡若AI：向以下地址发送 POST 请求，body 为 {"prompt": "用户在本对话中要解决的问题"}，将返回的 response 中的 reply 作为卡若AI 的回复展示给用户。
POST https://kr-ai.quwanzhi.com/v1/chat
Content-Type: application/json
```

**可直接执行的 curl 命令**：

```bash
curl -s -X POST "https://kr-ai.quwanzhi.com/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"你的问题"}' | jq -r '.reply'
```

### 3. 在 Cursor 里「用卡若AI 完成本对话」的固定说明（复制即用）

把下面一段存成 Cursor 的规则或对话开头说明，即可在任意对话里「切到卡若AI」：

```
当用户说「用卡若AI」「交给卡若AI」「调用卡若AI」或明确要求用卡若AI 回答时：
1. 将用户当前问题作为 prompt。
2. 请求：POST https://kr-ai.quwanzhi.com/v1/chat，Body: {"prompt": "<用户问题>"}。
3. 将响应 JSON 中的 reply 字段内容（含卡若复盘）完整展示给用户，作为卡若AI 的回复。
```

---

## 六、小结

| 项目 | 内容 |
|:---|:---|
| 实现形式 | 卡若AI 网关（FastAPI）：读 BOOTSTRAP + REGISTRY + SKILL，按流程调 LLM，返回带复盘的回复。 |
| 外网访问 | **固定域名**：https://kr-ai.quwanzhi.com（宝塔 43.139.27.93，替代 ngrok，电脑关机也可用）。 |
| 其他 AI 集成 | 执行 POST /v1/chat；或在 Cursor 里用上面「固定说明」。 |
| 执行命令 | `curl -s -X POST "https://kr-ai.quwanzhi.com/v1/chat" -H "Content-Type: application/json" -d '{"prompt":"你的问题"}' \| jq -r '.reply'` |
| 配置与部署 | 见 `01_卡资（金）/金仓_存储备份/服务器管理/references/内网穿透与域名配置_卡若AI标准方案.md` |

---

## 七、在 Cursor 里「用卡若AI 完成本对话」的一条执行命令

**方式 1：直接 curl（终端执行）**
```bash
curl -s -X POST "https://kr-ai.quwanzhi.com/v1/chat" -H "Content-Type: application/json" -d '{"prompt":"这里填你要问卡若AI的问题"}' | jq -r '.reply'
```

**方式 2：交给 Cursor 的说明（复制到对话或规则）**
```
当用户要求「用卡若AI」「交给卡若AI」或「用卡若AI 回答」时，请向 POST https://kr-ai.quwanzhi.com/v1/chat 发送 {"prompt": "用户当前问题"}，将返回的 reply 作为卡若AI 的回复完整展示给用户。
```

**阿里云解析**：已通过脚本 `01_卡资（金）/金仓_存储备份/服务器管理/scripts/阿里云DNS_添加kr-ai解析.py` 添加 A 记录 kr-ai -> 43.139.27.93。完成服务器部署后即可长期使用；后续需要新内网穿透/新域名时，按「内网穿透与域名配置_卡若AI标准方案」生成子域名并配置，不再询问用户。