yida-page-config · diff
git:20260803.a74d0e1 to git:20260818.7ea39f2
10 added, 3 removed. Audit A to A.
---
name: yida-page-config
description: 配置已有页面的公开访问和组织内分享。
---
# 页面配置
## 适用范围
- 不得把不支持、冲突、stale、reconciliation required 或状态不确定的任务自动改走 `save-share-config`/`update-form-config`，不得按标题或 URL adopt、猜 formUuid。
- 只有页面目标明确属于当前普通 OpenYida 资源时，以下命令、stdout/stderr 和返回行为才按本技能契约使用；所有权不明确时零远端写。
## 严格禁止 (NEVER DO)
- 不要为使用宜搭表单数据的自定义页面配置公开访问（`/o/xxx`），匿名用户无法调用需要登录态的表单接口
- 不要跳过 `verify-short-url` 验证直接保存配置，URL 格式错误会导致配置失败
- 不要编造 `appType` 或 `formUuid`，必须从命令返回或 `config.json` 中提取
## 严格要求 (MUST DO)
- 配置公开访问前必须确认页面类型：纯展示页面才可配置 `/o/` 公开访问
- 必须先运行 `verify-short-url` 验证 URL 有效性，再执行 `save-share-config`
- 配置完成后必须访问生成的 URL 验证页面可正常访问
- **本技能不读写 memory**：页面配置通过 CLI 命令写入宜搭平台，不依赖跨会话的 memory 状态
## 适用场景
| 用户意图 | 触发条件 |
|---------|---------|
| 页面公开访问 | "公开访问"、"分享链接"、"外部访问" |
| 组织内分享 | "组织内分享"、"内部分享" |
| 导航栏显示控制 | "隐藏导航"、"全屏展示" |
## 触发条件
**正向触发**：
- "公开访问"、"分享链接"、"外部访问"、"生成分享地址"
- "组织内分享"、"内部分享"
- "隐藏导航"、"全屏展示"、"隐藏顶部导航栏"
- 页面发布后需要配置访问权限时
---
## ⚠️ 关键限制
**使用宜搭表单数据的自定义页面不支持公开访问（`/o/xxx`）**，因为匿名用户无法调用需要登录态的表单接口。
| 页面类型 | 公开访问 `/o/` | 组织内分享 `/s/` |
|---------|:-:|:-:|
| 纯展示页面（静态/外部 API） | ✅ | ✅ |
| 使用宜搭表单数据 | ❌ | ✅ |
## 命令
### 验证 URL
```bash
openyida verify-short-url <appType> <formUuid> <url>
```
### 保存配置
```bash
openyida save-share-config <appType> <formUuid> <url> <isOpen> [openAuth]
```
| 参数 | 必填 | 说明 |
|------|------|------|
| `url` | 是 | `/o/xxx` 或 `/s/xxx`，关闭时传 `""` |
| `isOpen` | 是 | `y` 开启 / `n` 关闭 |
| `openAuth` | 否 | `y` 需授权 / `n` 不需要（默认） |
### 查询配置
```bash
openyida get-page-config <appType> <formUuid>
```
- ### 隐藏顶部导航
+ ### 隐藏页面导航
```bash
openyida update-form-config <appType> <formUuid> false "<页面标题>"
```
- > 看板/驾驶舱新建页面默认导航可见；只有用户显式要求隐藏导航 / 无导航 / 全屏无框时，才使用 `openyida create-page <appType> "<页面名>" --mode dashboard --hide-nav` 一步完成导航隐藏并输出无左侧工作台栏的沉浸式 URL。
- > 若页面内使用 `yida-nav-shell` 自绘导航壳，本命令是发布后的必做配置；同时导航壳里的自定义页目标 URL 必须追加 `?isRenderNav=false`，否则切到目标页时会重新出现宜搭原导航。
+ 这条命令只做页面级导航隐藏：
+
+ | 场景 | 用这个命令吗 | 说明 |
+ | --- | --- | --- |
+ | 页面隐藏导航 / 无导航 / 全屏无框 | 是 | 对应 `isRenderNav=false` |
+ | 自定义页自绘应用侧边/顶部导航 | 不是主命令 | 先执行 `openyida update-app <appType> --hide-app-nav` |
+ | 自绘应用导航后还要求页面本身也隐藏导航 | 是 | 在 `update-app --hide-app-nav` 之后再执行本命令 |
+
+ 看板/驾驶舱新建页面默认导航可见；只有用户显式要求页面隐藏导航 / 无导航 / 全屏无框时，才使用 `openyida create-page <appType> "<页面名>" --mode dashboard --hide-nav` 一步完成页面导航隐藏。自定义页之间跳转不靠 `?isRenderNav=false` 隐藏应用导航。
## URL 格式
- 公开访问：`/o/xxx`，组织内分享：`/s/xxx`
- 路径段仅支持 `a-z A-Z 0-9 _ -`，可用 `/` 分隔多级路径，例如 `/o/team/report-2026`
- 不允许空路径段、连续 `/` 或尾部 `/`，路径全局唯一
## 异常处理
| 异常场景 | 处理方式 |
|---------|----------|
| verify-short-url 验证失败 | 检查 URL 格式（路径段只含 `a-z A-Z 0-9 _ -`，`/` 仅作分隔符），确认路径全局唯一 |
| save-share-config 失败 | 必须先执行 verify-short-url 验证通过后再保存 |
| 公开访问页面无法加载数据 | 使用宜搭表单数据的页面不支持公开访问（/o/），改用组织内分享（/s/） |
| 配置后访问 URL 404 | 确认 URL 路径唯一，等待 CDN 缓存刷新（通常 1-2 分钟） |
## Agent 错误处理策略
当 Agent 执行本技能遇到错误时，必须遵循以下默认行为：
| 错误类型 | 默认处理策略 |
|---------|-------------|
| 命令执行失败 | 停止执行，向用户展示错误信息，询问是否重试或调整参数 |
| 参数缺失（appType/formUuid 等） | 主动询问用户补充，不得猜测或编造 |
| 权限不足 / 登录态失效 | 停止执行，提示用户执行 `openyida auth status` 检查登录态 |
| URL 验证失败 | 停止执行，提示用户检查 URL 格式或更换路径 |
| 网络超时 | 重试 1 次，仍失败则停止并提示用户检查网络 |
| 未知错误 | 停止执行，完整展示错误信息，建议用户反馈问题 |