yida-page-config git:20260803.a74d0e1A

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

---
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`，否则切到目标页时会重新出现宜搭原导航。

## 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 次，仍失败则停止并提示用户检查网络 |
| 未知错误 | 停止执行，完整展示错误信息，建议用户反馈问题 |