# 智能体能力说明：生成、发布与灌数

一类专用智能体：先选定**模块**，再生成页面并发布到建站平台，最后导入业务数据。  
接口细节见：[智能体-生成发布-API.md](./智能体-生成发布-API.md)

> 业务用语称「**模块**」（API 路径仍为 `/apps`，字段仍为 `app_slugs`）。  
> **管理账号**可查看本租户全部模块（含在建）。  
> **智能体**：启用并赋予「生成发布」后即可**自由发布自建模块**；`app_slugs` 留空表示不限制，无需后台逐个授权。

---

## 1. 一句话定位

| 项目 | 说明 |
|------|------|
| 做什么 | 登记账号 → 选模块 → **生成页面** → **向建站平台发布** → 导入数据 |
| 得到什么 | 发布回执含模块名、加密访问路径、状态；控制台「打开模块」见多页业务后台 |
| 管理侧 | 管理账号在「模块管理」看到全部模块（在建 / 已发布 / 失败） |
| 不做什么 | 查业务库用户表；角色 / 邀请 / 组织管理；行级增删改（仅允许 import + 只读抽查） |

---

## 2. 核心规则（必读）

### 2.1 绑定宇恒 ID（首次必做）

智能体账号**不在**已发布模块的业务表里。禁止在业务库翻用户 / 权限。

| 宿主侧 | API 字段 | 说明 |
|--------|----------|------|
| **宇恒 ID** | `host_key` | 稳定唯一标识；**必传** |
| **名称** | `name` | 控制台显示名；**必传** |

`POST /api/v1/auth/agent/register` → `pending` → 管理员赋「生成发布」并**启用** → 换票。  
**不要求**再填写「可访问模块」才能发布。

### 2.2 管理账号与模块可见范围

| 账号类型 | `GET /api/v1/apps` 可见范围 |
|----------|------------------------------|
| **管理账号**（如 demo/`owner`，非 agent） | 本租户**全部**模块，含 **在建** 与已发布、失败 |
| **智能体（`app_slugs` 为空或含 `*`）** | 不限制（`scope=open`），可列本租户模块并自由发布自建 slug |
| **智能体（配置了白名单）** | 仅白名单内（`scope=granted`）——可选限制，非默认 |

状态展示：

| status | 中文 | 说明 |
|--------|------|------|
| `draft` / `validating` / `provisioning` | **在建** | 已生成蓝图或正在发布，尚未成功上线 |
| `published` | 已发布 | 可打开业务页、可灌数 |
| `failed` | 失败 | 发布失败，可继续编辑后重发 |

生成蓝图成功后可 `PUT /api/v1/apps/{slug}/draft` 登记为在建。

### 2.3 先选模块，再生成

发布前建议 `GET /api/v1/apps` 查看已有模块：

| 选择 | 含义 |
|------|------|
| **已有模块** | 为该模块 **生成新的页面**，再发布到该模块 |
| **没有合适模块** | **生成完整多页蓝图**，再 **新建模块**（自定 slug，无需后台预授权） |

### 2.4 页面必须多页

一次生成应产出多个 `pages`（至少列表 + 新建表单；建议再加编辑 / 看板）。  
页面数量**不设上限**。列表页建议带 `import`。

### 2.5 发布 = 向建站平台送建站数据

宿主侧点击「发布」时，应把蓝图与展示元数据 **POST 到本建站平台**（不是只在宿主本地落库）。

平台会：

1. 校验并落库模块蓝图（新建或向已有模块发布新页面）  
2. **按当前用户 / 智能体 ID 加密生成访问文件路径**（`access_path`）  
3. 回执模块名称、发布方式、访问地址、发布时间、状态，供宿主「AI 表格数据」展示  

### 2.6 发布后必须灌数

发布只建结构，**不会自动灌 Excel**。成功后必须 `import`，并建议抽查 `total > 0`。  
宿主提示「下一步：灌数 → 打开模块」与此一致。

---

## 3. 首次接入流程

```text
宇恒 ID + 名称
  → POST /api/v1/auth/agent/register
  → pending
  → 管理员：角色「生成发布」+ 启用（可访问模块可留空）
  → 换票后即可自定 slug 生成/发布
```

`app_slugs` **默认留空即可自由发布**；仅在需要收紧范围时再配白名单。

---

## 4. 能力边界

### 允许

1. 首次登记（宇恒 ID + 名称）  
2. 换票  
3. 列出本账号可访问模块、读取已发布蓝图  
4. 生成蓝图 / 生成新页面（可带 Excel / 截图 / HTML）  
5. 发布到建站平台（新建模块或向已有模块发布新页面；拿加密路径回执）  
6. 导入数据 + 只读抽查列表  

### 禁止

- 业务库查用户 / 权限表  
- `row.create` / `row.update` / `row.delete`（除 import）  
- admin / audit 等管理接口  
- 对已有模块默认 `mode=replace` 整站覆盖  
- 访问未授权模块（仅当管理员配置了 `app_slugs` 白名单时才受限）  

---

## 5. 角色与模块授权

推荐角色：**生成发布（`publisher`）**

| 权限 | 用途 |
|------|------|
| 「发布模块」 | 发布模块 |
| `app.read` | 列模块 / 读蓝图 |
| `row.import` | 灌数 |
| `row.read` | 抽查 |
| `storage.write` / `storage.read` | 素材（建议） |

`app_slugs`：**可选**。留空 = 不限制，智能体可随意发布自建模块；填写后才按白名单限制。

---

## 6. 宿主发布回执（需求）

宿主「AI 表格数据」应展示建站平台发布回执，而不是本地假数据：

| 表格项 | 含义 | 来自发布响应 |
|--------|------|----------------|
| 模块名称 | 业务显示名 | `module_name` |
| 发布方式 | 如立即发布上线 | `publish_style`（`immediate`） |
| 访问地址 | 可打开的地址 | `access_url`（或宿主域名 + `access_path`） |
| 发布时间 | 平台落库时间 | `published_at` |
| 状态 | 已发布 | `status` = `published` |

加密路径规则：

- 输入：租户 ID + 用户/智能体 ID + 模块 slug  
- 输出：`access_path`（如 `m/ajzm1_...`），路径中**无明文用户 id / slug**  
- 公开读蓝图：`GET /api/v1/public/m/{token}/blueprint`  

---

## 7. 标准工作流

```text
宇恒ID + 名称
  → register → 管理员启用（publisher；模块白名单可选）
  → 换票
  → GET /apps                         【先选模块】
       ├─ 已有 → GET blueprint → generate【生成新页面】→ publish(add_pages|auto)
       └─ 没有 → generate【完整蓝图】→ publish(create|auto)【新建模块】
  → 宿主用回执展示「AI 表格数据」（含加密访问路径）
  → import → 抽查 total > 0 → 打开模块
```

---

## 8. 验收清单

- [ ] 管理账号可在「模块管理」看到全部模块（含在建）  
- [ ] register 传了宇恒 ID + 名称  
- [ ] 角色为「生成发布」  
- [ ] 发布前 `GET /api/v1/apps` 选目标（仅见本账号模块）  
- [ ] 已有模块：generate **生成新页面**再发布；无模块才新建  
- [ ] 新页面 `id` / `route` 不与已有冲突  
- [ ] `pages` ≥ 2（含 list，建议带 import）  
- [ ] publish 回执含 `access_path` / `access_url` / `published_at` / `status`  
- [ ] 宿主表格用回执字段，不写死假地址  
- [ ] generate → publish → import 成功，列表 `total > 0`  
- [ ] 「打开模块」可见多页导航  
- [ ] 不会去业务库查用户表