yida-page-config git:20260818.7ea39f2A

Immutable. This exact content is served forever at /api/v1/blob/2b054a1b63a003d8.

---
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 "<页面标题>"
```

这条命令只做页面级导航隐藏：

| 场景 | 用这个命令吗 | 说明 |
| --- | --- | --- |
| 页面隐藏导航 / 无导航 / 全屏无框 | 是 | 对应 `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 次，仍失败则停止并提示用户检查网络 |
| 未知错误 | 停止执行，完整展示错误信息，建议用户反馈问题 |