gaoding-cli 1.0.0-alpha.21 → 1.0.0-alpha.22

package/skills/gd-cli/references/dam.md

@@ -1,20 +1,52 @@
 # DAM 素材管理
 
-## 查询
+## 先发现，再操作
 
-- `gd-cli dam list --repository-id <id>` 查看资源库中的最近素材。
-- `gd-cli dam search <query> --repository-id <id>` 按关键词搜索。
-- `gd-cli dam get <asset>` 获取某个素材的完整信息与可用 URL。
-- 跨资源库查询仅在用户明确要求时使用 `--all-repositories`。
+任何资源库范围内的查询或写入都先运行：
 
-列表与搜索支持文件夹、类型、格式、标签、数量和游标筛选。先使用命令 `--help` 核对当前选项，不猜资源库 ID、文件夹 ID 或素材 ID。
+```bash
+gd-cli org current
+gd-cli dam repository list --json
+```
 
-## 写入
+只使用返回的 `repositories[].repository_id`。团队资源库的 `type` 为 `team`，企业资源库的 `type` 为 `enterprise`；不要使用名称、前端 URL、团队实体 ID 或历史值猜 ID。资源库不做 switch，`org switch` 只切换组织。
 
-- 用 `gd-cli dam upload <file> --repository-id <id>` 上传本地文件；按需补充标题、文件夹或标签。
-- 只有用户明确允许受保护路径时才加 `--allow-sensitive-path`。
-- 需要等素材分析完成时加 `--wait-analysis`。
-- 用 `gd-cli dam delete <asset> --repository-id <id>` 移入回收站。
-- 只有用户明确要求永久删除时才加 `--permanent`。
+需要文件夹或标签 ID 时继续发现：
 
-上传和删除前确认目标资源库；不得从本地登录状态或历史输出中替用户猜测目标。
+```bash
+gd-cli dam folder list --repository-id <id> --json
+gd-cli dam tag list --repository-id <id> --json
+```
+
+文件夹可用 `--parent-id`、`--query`、`--page` 和 `--page-size`；标签可用 `--query`。根文件夹 ID 为 `0`，涉及目标位置时必须显式传 `--target-folder-id 0`，不要把缺省值理解为根目录。
+
+## 查询与下载
+
+```bash
+gd-cli dam list --repository-id <id> --json
+gd-cli dam search <query> --repository-id <id> --json
+gd-cli dam get <asset-id> --json
+gd-cli dam download <asset-id> --repository-id <id> --output-dir ./downloads --json
+```
+
+跨资源库查询只在用户明确要求时使用 `--all-repositories`。列表或搜索按需增加文件夹、类型、格式、标签、数量和游标筛选。下载只支持一个素材，不支持文件夹下载，也不会覆盖已存在的同名文件。
+
+## 单条目写入
+
+```bash
+gd-cli dam upload ./asset.png --repository-id <id> --folder-id <folder-id> --tag-ids <tag-id> --json
+gd-cli dam rename <entry-id> --kind asset --title <new-title> --repository-id <id> --json
+gd-cli dam copy <entry-id> --kind asset --repository-id <source-id> --target-repository-id <target-id> --target-folder-id <folder-id> --json
+gd-cli dam move <entry-id> --kind asset --repository-id <source-id> --target-repository-id <target-id> --target-folder-id <folder-id> --json
+gd-cli dam delete <asset-id> --repository-id <id>
+```
+
+- `rename`、`move`、`copy` 的 `--kind` 只能是 `asset` 或 `folder`。
+- 一次只处理一个素材或文件夹；不拆分或模拟批量操作。
+- 上传受保护路径时，只有用户明确允许才加 `--allow-sensitive-path`；需要等待分析完成时加 `--wait-analysis`。
+- 复制结果可能没有 `copied_entry_id`，这不表示失败；查询目标文件夹或目标资源库发现新副本，不要猜测新 ID，也不要再次提交 copy。
+- 移动、复制或重命名若返回“已提交但未确认”，先查询目标位置并报告诊断 ID，不要立即重复提交。
+- 删除默认移入回收站；只有用户明确要求永久删除时才加 `--permanent`。
+- 回收站列表和恢复暂不可用，不要尝试不存在的 `dam recycle` 命令。
+
+写操作前确认资源库、条目 ID、类型和目标位置。优先从本轮 JSON 输出取得 ID，不从本地登录状态或旧输出替用户猜测。

package/skills/gd-cli/references/editor.md

@@ -70,6 +70,8 @@ Connector 必须从一个 Shape 绑定到另一个 Shape，`lineType` 只支持
 
    只有该命令成功才可以声明作品已保存。新 Board 在第一次显式保存时创建作品 ID；把返回的公开 `url` 交给用户，并保留其中的环境参数。
 
+   保存会等待 AI+ Editor 的真实持久化完成，可能明显慢于其他 Editor 命令；Bridge 为 Save 保留最长 5 分 30 秒。保持命令运行直到返回，不因短暂无输出而中断或并发发起其他 Editor 命令。
+
 6. 保存成功后断开 Session：
 
    ```bash
@@ -246,7 +248,7 @@ type FocusedEditorAction =
 - `EDITOR_ROLLBACK_FAILED`：无法确认恢复到 Apply 前状态。停止所有 `apply` 和 `save`，只读取 Snapshot 或截图并报告。
 - `SAVE_FAILED`：保留当前 Session，处理明确失败原因后可再次执行 `save --json`；成功前不报告已保存。
 - `EDITOR_BUSY`：等待当前命令结束后再发下一条，保持串行。
-- `EDITOR_RPC_TIMEOUT`：页面是否执行完成未知，Bridge 会关闭。读取类操作可重新连接同一作品后重试；`apply` 或 `save` 属于不确定写入，先重新连接同一作品并检查真实状态，再决定后续动作。无法检查原作品时停止并报告，不自动重试该写入。
+- `EDITOR_RPC_TIMEOUT`：页面是否执行完成未知，Bridge 会关闭。普通 Editor RPC 默认等待 1 分钟，Save 最长等待 5 分 30 秒。读取类操作可重新连接同一作品后重试；`apply` 或 `save` 属于不确定写入，先重新连接同一作品并检查真实状态，再决定后续动作。无法检查原作品时停止并报告，不自动重试该写入。
 - `PROTOCOL_VERSION_MISMATCH`：停止并升级 GD CLI，或使用协议匹配的 AI+ Editor。
 
 任何写操作在超时、取消或连接中断后都可能已经提交。恢复时先观察真实状态，避免重复创建、重复 Apply 或重复 Save。