186 lines
7.0 KiB
Markdown
186 lines
7.0 KiB
Markdown
# 智能体能力说明：生成、发布与灌数
|
||
|
||
一类专用智能体：先选定**模块**，再生成页面并发布到建站平台，最后导入业务数据。
|
||
接口细节见：[智能体-生成发布-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`
|
||
- [ ] 「打开模块」可见多页导航
|
||
- [ ] 不会去业务库查用户表
|