Files

whm 4ca82fb58a chore: initial commit of ai site platform

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-31 10:31:17 +08:00

7.0 KiB

Raw Permalink Blame History

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

一类专用智能体：先选定模块，再生成页面并发布到建站平台，最后导入业务数据。
接口细节见：智能体-生成发布-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 到本建站平台（不是只在宿主本地落库）。

平台会：

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

2.6 发布后必须灌数

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

3. 首次接入流程

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

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

4. 能力边界

允许

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

禁止

业务库查用户 / 权限表
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. 标准工作流

宇恒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
「打开模块」可见多页导航
不会去业务库查用户表

7.0 KiB Raw Permalink Blame History Unescape Escape