openyida 0.1.2 → 1.0.0-beta.0

package/yida-skills/skills/yida-get-schema/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: yida-get-schema
+description: 宜搭表单 Schema 获取技能，通过调用 getFormSchema 接口获取指定表单的完整 Schema 结构，用于分析字段定义、组件配置、确认字段 ID（fieldId）等。
+license: MIT
+compatibility:
+  - opencode
+  - claude-code
+metadata:
+  audience: developers
+  workflow: yida-development
+  version: 1.0.0
+  tags:
+    - yida
+    - low-code
+    - schema
+    - api
+---
+
+# 宜搭表单 Schema 获取技能
+
+## 概述
+
+本技能描述如何通过 `getFormSchema` 接口获取宜搭表单的完整 Schema 结构。获取到的 Schema 可用于分析字段定义、组件配置、学习表单结构等场景，也可用于在编码时确认字段 ID（fieldId）。
+
+## 何时使用
+
+当以下场景发生时使用此技能：
+- 用户需要查看已有表单的字段结构
+- 需要确认表单中各字段的 fieldId
+- 在编码前需要了解表单的组件配置
+- 需要分析现有表单作为参考
+
+## 使用示例
+
+### 示例 1：获取表单 Schema
+**场景**：获取表单的完整 Schema 结构
+**命令**：
+```bash
+openyida get-schema APP_XXX FORM-XXX
+```
+**输出**：完整的 Schema JSON，包含 pages、componentsMap 等
+
+## 使用方式
+
+```bash
+openyida get-schema <appType> <formUuid>
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `appType` | 是 | 应用 ID，如 `APP_XXX` |
+| `formUuid` | 是 | 表单 UUID，如 `FORM-XXX` |
+
+**示例**：
+
+```bash
+openyida get-schema "APP_XXX" "FORM-XXX"
+```
+
+**输出**：日志输出到 stderr，Schema JSON 输出到 stdout。
+
+## 前置依赖
+
+- Node.js
+- 项目根目录存在 `.cache/cookies.json`（首次运行会自动触发扫码登录）
+
+## 调用流程
+
+1. 读取项目根目录的 `.cache/cookies.json` 获取登录态；若不存在则自动触发扫码登录
+2. 调用 `getFormSchema` 接口获取表单 Schema；根据响应体 `errorCode` 自动处理异常（详见 `yida-login` 技能文档「错误处理机制」章节）
+3. 将 Schema 输出到 stdout
+
+## 文件结构
+
+```
+yida-get-schema/
+└── SKILL.md                      # 本文档
+```
+
+## 接口说明
+
+`getFormSchema` 接口的完整参数、返回值和错误处理机制，请参考 `../../reference/yida-api.md` 文档中的「表单设计类 API」章节。
+
+## 与其他技能配合
+
+- **获取已有表单 Schema** → 本技能，用于确认字段 ID 或学习字段结构
+- **创建表单页面** → 使用 `yida-create-form-page` 技能
+- **部署页面代码** → 使用 `yida-publish` 技能

package/yida-skills/skills/yida-login/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: yida-login
+description: 宜搭平台登录态管理技能，支持标准环境（Playwright 扫码登录）和悟空环境（CDP 从内置浏览器提取 Cookie），Cookie 持久化 + 自动获取 CSRF Token。
+license: MIT
+compatibility:
+  - opencode
+  - claude-code
+metadata:
+  audience: developers
+  workflow: yida-auth
+  version: 1.1.0
+  tags:
+    - yida
+    - auth
+    - login
+    - cookie
+    - wukong
+---
+
+# 宜搭登录态管理技能
+
+## 概述
+
+本技能提供宜搭平台的登录态管理能力，支持 Cookie 持久化和自动验证，首次使用需扫码登录，后续自动复用 Cookie。
+
+## 何时使用
+
+当以下场景发生时使用此技能：
+- 首次使用宜搭技能，需要扫码登录
+- Cookie 过期或失效，需要重新登录
+- 其他技能调用时提示登录态异常
+- 用户要求手动执行登录
+
+## 使用示例
+
+### 示例 1：标准环境触发登录
+**场景**：手动触发扫码登录（标准环境）
+**命令**：
+```bash
+openyida login
+```
+**输出**：
+```json
+{"csrf_token":"b2a5d192-xxx","corp_id":"dingxxx","user_id":"1955225xxx","base_url":"https://abcd.aliwork.com"}
+```
+
+### 示例 2：悟空环境登录
+**场景**：在悟空（Real）环境中，从内置浏览器提取登录态
+
+> ⚠️ **AI 必读**：在悟空环境中触发登录时，必须按以下步骤操作，**不能**直接运行脚本。
+
+**步骤 1**：读取登录地址
+```bash
+cat config.json  # 获取 loginUrl 字段
+```
+
+**步骤 2**：使用悟空内置浏览器打开登录页面，等待用户完成扫码登录
+- 悟空环境内置浏览器控制能力，可直接打开 URL（使用悟空的 `open_url` 或浏览器工具）
+- 登录地址即 `config.json` 中的 `loginUrl`（如 `https://www.aliwork.com/workPlatform`）
+- 等待用户在内置浏览器中完成钉钉扫码登录后，再进行步骤 3
+
+**步骤 3**：登录完成后，运行命令从内置浏览器提取 Cookie
+```bash
+openyida login --wukong
+```
+**输出**（与标准登录格式完全一致）：
+```json
+{"csrf_token":"b2a5d192-xxx","corp_id":"dingxxx","user_id":"1955225xxx","base_url":"https://abcd.aliwork.com","cookies":[...]}
+```
+
+## 使用方式
+
+### 标准环境
+
+```bash
+openyida login
+```
+
+无需任何参数，登录地址从项目根目录的 `config.json` 中读取（`loginUrl` 字段），登录后可能跳转到 `abcd.aliwork.com` 等域名。
+
+### 悟空环境
+
+```bash
+openyida login --wukong
+```
+
+**工作原理**：通过 CDP 协议连接悟空内置浏览器（端口 4249），调用 `Network.getAllCookies` 提取完整 Cookie（包括 `document.cookie` 无法获取的 HttpOnly Cookie），从中提取 `tianshu_csrf_token` 等关键字段。
+
+**输出**：登录成功后，将 `csrf_token`、`base_url`（跳转后的实际域名）和 Cookie 信息以 JSON 格式输出到 stdout，同时 Cookie 持久化到项目根目录的 `.cache/cookies.json`。
+
+> ⚠️ **重要**：`base_url` 取自登录成功后浏览器**实际跳转到的域名**，而非 `config.json` 中配置的 `loginUrl` 或 `defaultBaseUrl`。例如，即使 `loginUrl` 配置为 `https://www.aliwork.com`，如果你的账号所属组织对应的是 `abcd.aliwork.com`，平台会自动跳转，最终 `base_url` 将是 `https://abcd.aliwork.com`。后续所有 API 请求（包括 `yida-publish` 发布）都会使用这个 `base_url`。如需发布到特定域名，请确保 `config.json` 中的 `loginUrl` 指向该域名对应的组织，并且你的账号属于该组织。
+
+> 项目根目录通过向上查找 `config.json` 或 `.git` 目录来定位。
+
+## 工作流程
+
+1. 检查本地是否存在 `.cache/cookies.json` 缓存（包含 Cookie 和 `base_url`）
+2. 若存在，**直接从 Cookie 中提取** `csrf_token`（`tianshu_csrf_token`）、`corp_id` 和 `user_id`（`tianshu_corp_user`），无需访问任何页面
+3. 若 Cookie 中无 `tianshu_csrf_token`，视为失效，打开有头浏览器让用户扫码登录
+4. 登录成功后直接从 Cookie 中提取所需信息，保存 Cookie 和 `base_url`（从登录后实际跳转的 URL 获取）
+
+## 前置依赖
+
+- Node.js 16+
+- `openyida` NPM 包已安装（`npm install -g openyida`）
+
+## 文件结构
+
+```
+yida-login/
+└── SKILL.md           # 本文档
+
+项目根目录/
+├── config.json        # 全局配置（loginUrl、defaultBaseUrl）
+└── .cache/
+    └── cookies.json   # 登录态缓存（运行时自动生成，含 Cookie + base_url）
+```
+
+## 输出格式
+
+脚本成功执行后，最后一行输出 JSON：
+
+```json
+{
+  "csrf_token": "b2a5d192-db90-484c-880f-9b48edd396d5",
+  "corp_id": "ding9a0954b4f9d9d40ef5bf40eda33b7ba0",
+  "user_id": "19552253733782",
+  "base_url": "https://abcd.aliwork.com",
+  "cookies": [...]
+}
+```
+
+> `csrf_token` 从 Cookie `tianshu_csrf_token` 的 value 中提取；`corp_id` 和 `user_id` 从 Cookie `tianshu_corp_user` 的 value 中提取，格式为 `{corpId}_{userId}`，按最后一个 `_` 分隔。
+
+> `base_url` 是登录后浏览器实际跳转到的域名（如 `https://abcd.aliwork.com`），**可能与 `config.json` 中的 `loginUrl` 不同**。其他脚本应使用此值作为 API 请求的基础地址，而非硬编码域名。
+
+其他脚本可通过管道接收并解析 stdout 最后一行获取登录态信息。
+
+## 缓存格式
+
+`.cache/cookies.json` 文件格式（兼容旧版纯 Cookie 数组）：
+
+```json
+{
+  "cookies": [...],
+  "base_url": "https://abcd.aliwork.com"
+}
+```
+
+`csrf_token`、`corp_id`、`user_id` 不存储在缓存中，每次启动时直接从 Cookie 列表中提取（`tianshu_csrf_token` 和 `tianshu_corp_user` 字段）。
+
+## 全局配置
+
+`openyida` 从项目根目录的 `config.json` 读取配置，不再硬编码 URL：
+
+```json
+{
+  "loginUrl": "https://www.aliwork.com/workPlatform",
+  "defaultBaseUrl": "https://www.aliwork.com"
+}
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `loginUrl` | 扫码登录页面地址（登录成功后平台可能自动跳转到其他域名） |
+| `defaultBaseUrl` | API 请求的默认基础地址（仅当 `base_url` 未从登录态中获取时作为兜底使用，正常流程不会用到） |
+
+## 错误处理机制
+
+各 skill 脚本通过解析接口响应体的 `errorCode` 字段来判断登录态异常，并自动调用本技能处理：
+
+| errorCode | 含义 | 标准环境处理方式 | 悟空环境处理方式 |
+| --- | --- | --- | --- |
+| "TIANSHU_000030" | csrf 校验失败（csrf_token 过期） | `openyida login` 自动无头刷新 csrf_token，无需重新扫码 | `openyida login --wukong` 重新从内置浏览器提取完整 Cookie |
+| "307" | 登录状态已过期（Cookie 失效） | `openyida login` 触发完整重新登录（可能需要扫码） | `openyida login --wukong` 重新从内置浏览器提取完整 Cookie |
+
+> **注意**：错误判断基于响应体 JSON 的 `errorCode` 字段，而非 HTTP 状态码。
+
+> **悟空环境说明**：悟空环境下不支持 `--refresh-csrf` 模式，csrf_token 过期和 Cookie 失效均通过重新调用 `openyida login --wukong` 处理。由于 CDP 提取 Cookie 速度极快（无需扫码），这不会带来明显的延迟。
+
+## 退出登录
+
+清空本地 Cookie 缓存文件内容即可完成退出，下次调用任意技能时将自动触发重新扫码登录：
+
+```bash
+openyida logout
+```
+
+**适用场景**：
+- 需要切换账号或切换组织
+- Cookie 失效且无法自动刷新
+- 用户主动要求退出登录
+
+> **注意**：Cookie 缓存文件位于**项目根目录**（含 `README.md` 或 `.git` 的目录）的 `.cache/` 目录下。退出登录不影响已部署的页面和已保存的数据。
+
+## 与其他技能配合
+
+- **退出登录**：需要切换账号或 Cookie 失效时，执行 `openyida logout` 后重新运行任意技能即可触发扫码登录
+- **`yida-publish`**：发布时自动调用本技能获取登录态
+- **`yida-create-app`**、**`yida-create-page`**、**`yida-create-form-page`**：自动调用本技能获取登录态

package/yida-skills/skills/yida-logout/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: yida-logout
+description: 宜搭平台退出登录技能，清空本地 Cookie 缓存内容。
+license: MIT
+compatibility:
+  - opencode
+  - claude-code
+metadata:
+  audience: developers
+  workflow: yida-auth
+  version: 1.0.0
+  tags:
+    - yida
+    - auth
+    - logout
+    - cookie
+---
+
+# 宜搭退出登录技能
+
+## 概述
+
+本技能提供宜搭平台的退出登录能力，通过清空本地 Cookie 缓存文件内容使登录态失效。下次使用 `yida-login` 时将重新打开浏览器进行扫码登录。
+
+## 何时使用
+
+当以下场景发生时使用此技能：
+- 用户需要切换账号
+- Cookie 失效且无法自动刷新
+- 用户要求退出登录
+- 需要切换到另一个组织
+
+## 使用示例
+
+### 示例 1：退出登录
+**场景**：清空登录态缓存
+**命令**：
+```bash
+openyida logout
+```
+
+## 使用方式
+
+```bash
+openyida logout
+```
+
+## 工作流程
+
+1. 清空项目根目录下的 `.cache/cookies.json` 文件内容（写入空字符串）
+2. 下次调用 `yida-login` 时，因缓存内容为空，将自动打开浏览器要求重新扫码登录
+
+> **注意**：Cookie 缓存文件位于**项目根目录**（含 `README.md` 或 `.git` 的目录）的 `.cache/` 目录下。
+
+## 与其他技能配合
+
+- **`yida-login`**：退出后需重新登录时使用，会自动检测 Cookie 缓存为空并打开浏览器
+- 退出登录不影响已部署的页面和已保存的数据

package/yida-skills/skills/yida-page-config/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: yida-page-config
+description: 宜搭页面配置技能，提供页面公开访问和组织内分享的 URL 验证与配置保存功能。包括公开访问（/o/xxx）和组织内分享（/s/xxx）两种模式。
+license: MIT
+compatibility:
+  - opencode
+  - claude-code
+metadata:
+  audience: developers
+  workflow: yida-development
+  version: 1.0.0
+  tags:
+    - yida
+    - low-code
+    - page-config
+    - public-url
+    - share-url
+---
+
+# 宜搭页面配置技能
+
+## 概述
+
+本技能提供宜搭页面的公开访问和组织内分享配置功能：
+
+| 功能 | 说明 |
+|------|------|
+| **URL 验证** | 验证公开访问/分享 URL 是否可用（是否被占用） |
+| **配置保存** | 保存页面的公开访问/分享配置 |
+
+支持的 URL 类型：
+
+| 类型 | 前缀 | 示例 | 访问范围 |
+|------|------|------|----------|
+| 公开访问 | `/o/` | `/o/myapp` | 任何人可访问 |
+| 组织内分享 | `/s/` | `/s/myapp` | 仅组织内成员 |
+
+## 何时使用
+
+当以下场景发生时使用此技能：
+- 用户需要设置页面的公开访问功能
+- 用户需要设置页面的组织内分享功能
+- 在配置公开访问/分享之前需要检查 URL 是否被占用
+- 需要修改或关闭已有页面的分享配置
+
+## ⚠️ 重要限制：自定义页面使用表单数据时不支持公开发布
+
+**如果自定义页面中有读取或写入宜搭表单数据的操作（如查询表单记录、提交表单等），则该页面不支持配置公开访问（`/o/xxx`）。**
+
+原因：公开访问页面对任何人开放，无需登录，但宜搭表单数据接口需要登录态（Cookie）才能访问，匿名用户无法读取表单数据，页面会出现数据加载失败的问题。
+
+**判断标准**：
+
+| 页面类型 | 是否支持公开访问 |
+|---------|---------------|
+| 纯展示页面（静态内容、外部 API） | ✅ 支持 |
+| 使用宜搭表单数据（查询/提交/更新） | ❌ 不支持 |
+| 使用宜搭成员/部门数据 | ❌ 不支持 |
+
+**遇到此情况时，AI 应该**：
+1. 不生成公开访问链接（`/o/xxx`）
+2. 告知用户该页面因使用了表单数据，不支持公开访问
+3. 如有需要，可配置**组织内分享**（`/s/xxx`），仅限组织内登录成员访问
+
+## URL 格式要求
+
+- 公开访问：`/o/xxx`，如 `/o/myapp`
+- 组织内分享：`/s/xxx`，如 `/s/myapp`
+- 只支持 a-z A-Z 0-9 _ -
+- 路径部分是唯一的，不能与已有页面冲突
+
+## 使用示例
+
+### 示例 1：验证公开访问 URL
+```bash
+openyida verify-short-url APP_XXX FORM-XXX /o/myapp
+```
+
+### 示例 2：开启公开访问
+```bash
+openyida save-share-config APP_XXX FORM-XXX /o/myapp y n
+```
+
+### 示例 3：关闭公开访问
+```bash
+openyida save-share-config APP_XXX FORM-XXX "" n
+```
+
+### 示例 4：查询页面配置
+```bash
+openyida get-page-config APP_XXX FORM-XXX
+```
+
+### 示例 5：隐藏顶部导航
+```bash
+openyida update-form-config APP_XXX FORM-XXX false "页面标题"
+```
+
+## 工具说明
+
+### 1. verify-short-url - URL 验证
+
+验证短链接 URL 是否已被占用。
+
+```bash
+openyida verify-short-url <appType> <formUuid> <url>
+```
+
+**参数**：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `appType` | 是 | 应用 ID，如 `APP_XXX` |
+| `formUuid` | 是 | 表单 UUID，如 `FORM-XXX` |
+| `url` | 是 | 短链接路径，`/o/xxx` 或 `/s/xxx` |
+
+**输出**：
+
+```json
+{
+  "available": true,
+  "url": "/o/myapp",
+  "urlType": "open",
+  "message": "该公开访问路径可用"
+}
+```
+
+### 2. save-share-config - 配置保存
+
+保存页面的公开访问或组织内分享配置。
+
+```bash
+openyida save-share-config <appType> <formUuid> <url> <isOpen> [openAuth]
+```
+
+**参数**：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `appType` | 是 | 应用 ID |
+| `formUuid` | 是 | 表单 UUID |
+| `url` | 是 | 短链接路径，关闭时传空字符串 `""` |
+| `isOpen` | 是 | 是否开放，`y` 开启，`n` 关闭 |
+| `openAuth` | 否 | 是否需要授权，`y` 需要，`n` 不需要，默认 `n` |
+
+**输出**：
+
+```json
+{
+  "success": true,
+  "url": "/o/myapp",
+  "isOpen": true,
+  "message": "公开访问配置已保存"
+}
+```
+
+### 3. get-page-config - 查询页面配置
+
+查询页面的公开访问/分享配置。
+
+```bash
+openyida get-page-config <appType> <formUuid>
+```
+
+**输出**：
+
+```json
+{
+  "isOpen": true,
+  "openUrl": "/o/myapp",
+  "shareUrl": "/s/myapp"
+}
+```
+
+### 4. update-form-config - 表单配置更新
+
+更新表单的基本配置，如显示/隐藏顶部导航。
+
+```bash
+openyida update-form-config <appType> <formUuid> <isRenderNav> <title>
+```
+
+**参数**：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `appType` | 是 | 应用 ID |
+| `formUuid` | 是 | 表单 UUID |
+| `isRenderNav` | 是 | `true` 显示顶部导航，`false` 隐藏顶部导航 |
+| `title` | 是 | 页面标题 |
+
+**输出**：
+
+```json
+{
+  "success": true,
+  "isRenderNav": false,
+  "message": "已隐藏顶部导航"
+}
+```
+
+## 前置依赖
+
+- Node.js
+- `yida-cli` 工具已安装（`npm install -g yida-cli`）
+- 项目根目录存在 `.cache/cookies.json`（首次运行会自动触发扫码登录）
+
+## 调用流程
+
+1. 读取项目根目录的 `.cache/cookies.json` 获取登录态；若不存在则自动触发扫码登录
+2. 验证 URL 格式
+3. 调用对应接口进行验证或保存
+4. 返回操作结果
+
+## 文件结构
+
+```
+yida-page-config/
+└── SKILL.md                      # 本文档
+```
+
+> 脚本已集成到 `openyida-cli` 工具中，通过 `openyida` 命令调用。
+
+## 接口说明
+
+### verifyShortUrl（验证短链接 URL）
+
+- **地址**：`GET /dingtalk/web/{appType}/query/formdesign/verifyShortUrl.json`
+- **参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `_api` | String | 是 | `App.verifyShortUrlForm` |
+| `openUrl` | String | 否 | 公开访问路径 `/o/xxx` |
+| `shareUrl` | String | 否 | 组织内分享路径 `/s/xxx` |
+| `formUuid` | String | 是 | 表单 UUID |
+| `_csrf_token` | String | 是 | CSRF Token |
+
+- **返回值**：`content: true` 可用，`content: false` 被占用
+
+### saveShareConfig（保存分享配置）
+
+- **地址**：`POST /dingtalk/web/{appType}/query/formdesign/saveShareConfig.json`
+- **参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `_api` | String | 是 | `Share.saveShareConfig` |
+| `formUuid` | String | 是 | 表单 UUID |
+| `openUrl` | String | 是 | 短链接路径 |
+| `isOpen` | String | 是 | `y` 开启，`n` 关闭 |
+| `openPageAuthConfig` | String | 否 | 权限配置 JSON |
+| `_csrf_token` | String | 是 | CSRF Token |
+
+- **返回值**：`success: true` 表示成功
+
+## 与其他技能配合
+
+- **页面开发** → 使用 `yida-custom-page` 技能
+- **页面发布** → 使用 `yida-publish-page` 技能
+- **获取表单 Schema** → 使用 `yida-get-schema` 技能