release v26.13.0

docs/developers/cocli/1-cli-install.md

@@ -13,7 +13,7 @@ sidebar_position: 1
 curl -fL https://download.coscene.cn/cocli/install.sh | sh
 ```
 
-在命令行中可以使用 `cocli -h` 来确认命令行工具已经成功安装，并查看工具的基基本用法。
+在命令行中可以使用 `cocli -h` 来确认命令行工具已经成功安装，并查看工具的基本用法。
 
 ```bash
 Usage:
@@ -27,7 +27,9 @@ Available Commands:
   project     Work with coScene project.
   record      Work with coScene record.
   registry    Manage coScene container registry access
+  role        Work with coScene roles.
   update      Update cocli version
+  user        Work with coScene users.
 
 Flags:
       --config string      config file path (default "/Users/yujing/.cocli.yaml")

docs/developers/cocli/2-cli-record-operations.md

@@ -8,7 +8,7 @@ sidebar_position: 2
 记录是刻行平台中的核心概念，本文列举了记录和其中文件的常见操作，并附简单的例子。
 
 :::warning
-关于具体命令的的详细参数，都以使用 `cocli [command] [subcommand] -h` 来查看。本文中只列举了常用的命令和参数及用法。
+关于具体命令的详细参数，都以使用 `cocli [command] [subcommand] -h` 来查看。本文中只列举了常用的命令和参数及用法。
 :::
 
 ```bash
@@ -68,6 +68,12 @@ URL:                     https://coscene.cn/coscene-lark/docs/records/c5f7a2fa-a
 -------------------------------------------------------------
 ```
 
+创建记录时可通过 `--custom` 设置自定义字段（`key=value` 形式，可重复指定多项）：
+
+```bash
+cocli record create -t my-record --custom "priority=high" --custom "batch=2025-03"
+```
+
 ### 列举项目中的记录 {#list-records}
 
 ```bash
@@ -121,16 +127,41 @@ cocli record list --keywords "keyword1,keyword2"
 cocli record list --include-archive
 ```
 
+`list` 的输出格式可通过 `-o` 指定，除默认表格外还支持 `wide`、`csv`、`json`、`yaml`。其中 `wide` 与 `csv` 会尽量将创建人、用户型自定义字段等解析为可读名称（需能访问对应用户信息）。
+
+**分页与导出：**`wide`、`csv`、`json`、`yaml` 与表格一样，**默认只包含当前页**（由服务端分页决定，未指定 `--page-size` 时常见为每页最多 100 条）。若要**一次性导出当前筛选条件下的全部记录**，请加上 `--all`（记录量很大时请求会更久，也可改用上面的 `--page-token` 分页拉取后在脚本里拼接）。`--labels`、`--keywords` 等过滤与 `--all` 可同时使用，表示「符合条件的全部」。
+
+```bash
+# 宽表输出（便于一眼看到更多列）
+cocli record list -o wide
+
+# 导出当前页为 CSV（仅本页数据）
+cocli record list -o csv > records-page.csv
+
+# 导出符合条件的全部记录为 CSV（常用作完整导出）
+cocli record list --all -o csv > records-all.csv
+```
+
+使用 `-s` / `--search` 可传入与网页端高级搜索一致的 **JSON Logic** 查询字符串，做更复杂的筛选。注意：**`--search` 与 `--include-archive`、`--labels`、`--keywords` 不能同时使用**，请择一组合。
+
+```bash
+# 使用单引号将网页端复制的 json 过滤条件括起来
+cocli record list --search '<search_json>'
+
+# e.g. 示例
+cocli record list --search '{"and":[{"==":[{"var":"isArchived"},"false"]},{"and":[{"in":[{"var":"relatedLabels.id"},["29fd2ca8-edc6-433a-8cb7-94b1b340102d"]]},{">=":[{"var":"byteSize"},104857600]},{">=":[{"var":"summary.filesDuration"},0]}]}]}'
+```
+
 ### 上传文件到记录 {#upload-files-to-record}
 
-您可以将任意指定的文件或者目录内的文件上传到特定记录
+您可以将**一个或多个**本地路径（文件或目录）上传到指定记录。上传目录时**默认递归**包含子目录中的文件，无需额外参数。多个路径写在记录 ID 或资源名之后即可，例如：`cocli record upload <record> ./a.mcap ./more-data/`。
 
 ```bash
 # 创建一个临时文件
 touch episode-1.mcap
 
 # 将该文件上传到前面创建的 Record
-cocli record upload 9c9177f6-8194-4d69-8536-3cfebce6fc2 ./episode-1.mcap
+cocli record upload 9c9177f6-8194-4d69-8536-3cfebce6fc23 ./episode-1.mcap
 ```
 
 ```bash
@@ -140,13 +171,17 @@ Upload Status:
 /Users/yujing/Workspace/co/docs/episode-1.mcap:                                                              Upload completed
 
 Total: 1, Skipped: 0, Success: 1
-View record at: https://coscene.cn/coscene-lark/docs/records/9c9177f6-8194-4d69-8536-3cfebce6fc2
+View record at: https://coscene.cn/coscene-lark/docs/records/9c9177f6-8194-4d69-8536-3cfebce6fc23
 ```
 
+:::tip
+在交互式终端中上传时，进行中的文件会显示进度条（以 `=` 表示已传比例），并可能显示**上传速率**与**已用时间**；无 TUI 环境可使用 `cocli record upload -h` 中说明的 `--no-tty` 等选项。
+:::
+
 ### 下载记录中的文件 {#download-files-from-record}
 
 ```bash
-cocli record download 9c9177f6-8194-4d69-8536-3cfebce6fc2 .
+cocli record download 9c9177f6-8194-4d69-8536-3cfebce6fc23 .
 ```
 
 ```
@@ -198,7 +233,7 @@ URL:          https://coscene.cn/coscene-lark/docs/records/52c5afac-22ca-4ab5-b9
 ```
 
 :::tip
-如果记录关联了设备或包含自定义字段值，这些信息也会在 `describe` 命令的输出中显示。
+如果记录关联了设备或包含自定义字段值，这些信息也会在 `describe` 命令的输出中显示。`describe` 的 `-o` 支持 `table`、`json`、`yaml`。
 :::
 
 ```bash
@@ -222,7 +257,7 @@ URL:                     https://coscene.cn/coscene-lark/docs/records/52c5afac-2
 
 ### 更新记录信息 {#update-record}
 
-命令行也支持更改记录的名字、描述等信息，完整的更新列表请查看帮助。
+命令行也支持更改记录的名字、描述、标签与自定义字段等信息，完整的更新列表请查看帮助。更新自定义字段同样使用 `--custom key=value`，可重复指定。
 
 ```bash
 cocli record update 52c5afac-22ca-4ab5-b9cf-fc069053b1af -d "物体运行过程中，机械臂扭矩未达到预期，失败" # 更新记录描述
@@ -305,6 +340,10 @@ cocli record moment download bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6 . --flat
 
 标签是管理和查询记录的重要手段，通过对记录添加和删除标签，我们可以在批处理和自动化的过程中，对不同的数据进行简单的区分。
 
+:::tip
+同一次 `record update` 中，`--append-labels`、`--update-labels` 与 `--delete-labels` 仅能使用其中一类（互斥）。下文各小节为分步示例。
+:::
+
 ### 添加标签
 
 ```bash

docs/developers/cocli/3-cli-action-operations.md

@@ -59,6 +59,8 @@ fb1bb37a-7b27-11ee-b962-0242ac120002     system      ros2-mcap-converter
 6cdf7cf9-d635-4cad-9333-cb58fc6a8e24     system      yw-cyber-converter                                          1970-01-01T08:00:00+08:00
 ```
 
+`cocli action list` 会列出当前项目中的动作，并在有权访问时合并系统级动作；该子命令**没有** `--all` 选项（勿与 `cocli record list` 混淆）。
+
 ## 触发动作 {#trigger-an-action}
 
 找到我们想要的执行的动作之后，我们可以在命令行中，直接触发这个动作，实现全流程的自动化。
@@ -74,7 +76,7 @@ fb1bb37a-7b27-11ee-b962-0242ac120002     system      ros2-mcap-converter
 ```bash
 # 使用 JSON 输出获取记录和动作, 比如要在第一个记录中执行 coScene-test 动作
 RECORD_NAME=$(cocli record list --page-size 10 -o json | jq -r '.records[0].name')
-ACTION_NAME=$(cocli action list --all -o json | jq -r '.actions[] | select(.spec.name | contains("coScene-test")) | .name')
+ACTION_NAME=$(cocli action list -o json | jq -r '.actions[] | select(.spec.name | contains("coScene-test")) | .name')
 cocli action run $ACTION_NAME $RECORD_NAME
 ```
 
@@ -96,10 +98,10 @@ The final parameters in the action run to be created:
 Action run created successfully.
 ```
 
-较为复杂的动作可能会需要额外的参数对动作进行定制，您可以使用 `-p` 的标志位提供这些参数
+较为复杂的动作可能会需要额外的参数对动作进行定制，请使用 **`-P`（大写）** 或 **`--param`** 传入键值对（可重复）。注意：此处的 **`-p` 已用于 `--project`（默认项目）**，不要用小写 `-p` 传动作参数。
 
 ```bash
-cocli action run $ACTION_NAME $RECORD_NAME -f -p 参数1=123 -p 参数2=456
+cocli action run $ACTION_NAME $RECORD_NAME -f -P 参数1=123 -P 参数2=456
 ```
 
 请注意在这种调用模式下，如果有 `参数1` 和 `参数2` 之外的参数，那么剩余的这些未提供明确数值的参数会使用动作中定义的默认值

docs/developers/cocli/4-cli-user-role-registry.md

@@ -0,0 +1,93 @@
+---
+slug: user-role-registry
+sidebar_position: 4
+---
+
+# 用户、角色与容器镜像仓库
+
+本节介绍与组织成员、权限角色以及刻行容器镜像仓库相关的命令。这些能力通常用于管理员或需要在本地使用 Docker 拉取/推送镜像的场景。
+
+:::warning
+具体标志位与输出格式请以本机 `cocli user -h`、`cocli role -h`、`cocli registry -h` 及各子命令的 `-h` 为准。
+:::
+
+```bash
+cocli user -h
+cocli role -h
+cocli registry -h
+```
+
+## 用户 {#user}
+
+`cocli user` 用于查询当前登录身份所在组织（或指定项目）下的用户信息。
+
+### 列举用户 {#user-list}
+
+- **不传 `-p`**：按**组织**范围列举用户。
+- **传入 `-p <项目 slug>`**：仅列举该项目下的用户。
+- **`--role-code`**：按角色代码过滤（例如 `PROJECT_WRITER`、`ORGANIZATION_ADMIN`）。可与 `cocli role list` 中看到的角色编码对照使用。
+- **分页**：与 `record list` 类似，使用 `--page-size`（10–100）与 `--page-token` 翻页；默认每页条数由服务端上限决定，终端会在有下一页时提示 `--page-token`。
+- **输出**：`-o` 支持 `table`、`wide`、`json`、`yaml`；`-v` 为更详细的表格列。
+
+```bash
+# 组织内用户
+cocli user list
+
+# 某项目内用户
+cocli user list -p my-project-slug
+
+# 按角色过滤（示例）
+cocli user list --role-code PROJECT_WRITER -o json
+```
+
+### 查看用户详情 {#user-get}
+
+- **无参数**：尝试获取**当前登录用户**（若接口不可用，请显式传入用户 ID 或资源名）。
+- **有参数**：支持用户 **ID**（将解析为 `users/<id>`）或完整资源名（如 `users/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）。
+
+```bash
+cocli user get
+cocli user get <user-id>
+cocli user get users/<uuid> -o json
+```
+
+## 角色 {#role}
+
+`cocli role list` 列出平台中可用的角色定义，便于与 `cocli user list --role-code` 配合使用。
+
+- **`--level`**：可选 `organization` 或 `project`，只看待定层级的角色。
+- **分页**：`--page-size`、`--page-token`，行为与 `user list` 一致。
+- **输出**：`-o table|wide|json|yaml`，`-v` 更详细。
+
+```bash
+cocli role list
+cocli role list --level project -o wide
+```
+
+## 容器镜像仓库 {#registry}
+
+`cocli registry` 用于获取刻行容器镜像仓库的临时凭证，并可选地调用本机 **Docker** 执行 `docker login`。子命令**不走与普通资源命令相同的全局登录校验**，但仍需本地配置文件中存在可用的登录配置，以便调用 OpenAPI 签发凭证。
+
+### 登录 Docker（推荐） {#registry-login}
+
+根据当前 profile 的 **OpenAPI endpoint** 推断镜像仓库域名（例如 SaaS `openapi.coscene.cn` 对应 `cr.coscene.cn`）；若无法推断，需使用 **`--registry`** 手动指定主机名。
+
+**要求**：本机已安装 Docker，且 `docker` 在 `PATH` 中。
+
+```bash
+cocli registry login
+cocli registry login --registry cr.example.com
+```
+
+### 仅生成临时凭证 {#registry-create-credential}
+
+不调用 Docker，仅向标准输出打印用户名与密码（临时凭证）。默认纯文本两行；也可使用 `-o json` / `yaml` / `table` 便于脚本解析。
+
+```bash
+cocli registry create-credential
+cocli registry create-credential -o json
+```
+
+:::tip
+临时密码请视为敏感信息，勿写入版本库或日志；在 CI 中优先使用密钥管理或短期令牌策略。
+:::

docs/developers/cocli/97-cli-common-batch-tasks.md

@@ -35,8 +35,8 @@ for dir in */; do
   # 去除目录名称末尾的斜杠，并创建一个新的记录，获取记录的完整资源名称
   record_name=$(cocli record create -t "${dir%/}" -o json | jq -r '.name')
 
-  # 上传当前子目录的内容到创建的记录中
-  cocli record upload -R "$record_name" "$dir"
+  # 上传当前子目录的内容到创建的记录中（目录默认递归上传，无需额外参数）
+  cocli record upload "$record_name" "$dir"
 done
 ```
 

docs/developers/cocli/99-advanced-features.md

@@ -13,6 +13,7 @@ sidebar_position: 99
 
 ```bash
 cocli login add -n <凭证名字> -p <项目Slug> -t <访问令牌>
+# 需指定 OpenAPI 端点时，可加上 -e <openapi 地址>（与 login set 一致）
 ```
 
 我们可以使用如下命令来获取当前所有可用的凭证

i18n/en/docusaurus-plugin-content-docs/current/developers/cocli/1-cli-install.md

@@ -27,7 +27,9 @@ Available Commands:
   project     Work with coScene project.
   record      Work with coScene record.
   registry    Manage coScene container registry access
+  role        Work with coScene roles.
   update      Update cocli version
+  user        Work with coScene users.
 
 Flags:
       --config string      config file path (default "/Users/yujing/.cocli.yaml")

i18n/en/docusaurus-plugin-content-docs/current/developers/cocli/2-cli-record-operations.md

@@ -68,6 +68,12 @@ URL:                     https://coscene.cn/coscene-lark/docs/records/c5f7a2fa-a
 -------------------------------------------------------------
 ```
 
+When creating a record, you can set custom fields with `--custom` in `key=value` form (repeat as needed):
+
+```bash
+cocli record create -t my-record --custom "priority=high" --custom "batch=2025-03"
+```
+
 ### List Records in a Project {#list-records}
 
 ```bash
@@ -121,16 +127,41 @@ cocli record list --keywords "keyword1,keyword2"
 cocli record list --include-archive
 ```
 
+Use `-o` to choose the output format: besides the default table, `wide`, `csv`, `json`, and `yaml` are supported. For `wide` and `csv`, creator and user-type custom fields are resolved to readable names when the corresponding user information is accessible.
+
+**Pagination and export:** `wide`, `csv`, `json`, and `yaml` behave like the table view and **only include the current page** by default (server-side pagination; when `--page-size` is omitted, up to 100 rows per page is typical). To **export all records matching the current filters in one go**, add `--all` (for very large result sets this may take longer; you can also use `--page-token` pagination as above and merge in a script). `--labels`, `--keywords`, and other filters can be used together with `--all` to mean **all rows that match the filters**.
+
+```bash
+# Wide table (more columns at a glance)
+cocli record list -o wide
+
+# Export current page to CSV (this page only)
+cocli record list -o csv > records-page.csv
+
+# Export all matching records to CSV (typical full export)
+cocli record list --all -o csv > records-all.csv
+```
+
+Use `-s` / `--search` to pass a **JSON Logic** query string consistent with the web UI’s advanced search for more complex filtering. **Note: `--search` cannot be used together with `--include-archive`, `--labels`, or `--keywords`.** Choose one combination.
+
+```bash
+# Use single quotes around the JSON filter copied from the web UI
+cocli record list --search '<search_json>'
+
+# Example
+cocli record list --search '{"and":[{"==":[{"var":"isArchived"},"false"]},{"and":[{"in":[{"var":"relatedLabels.id"},["29fd2ca8-edc6-433a-8cb7-94b1b340102d"]]},{">=":[{"var":"byteSize"},104857600]},{">=":[{"var":"summary.filesDuration"},0]}]}]}'
+```
+
 ### Upload Files to a Record {#upload-files-to-record}
 
-You can upload any specified files or files within a directory to a specific record.
+You can upload **one or more** local paths (files or directories) to a record. Directory uploads **recurse into subdirectories by default**; no extra flag is required. List multiple paths after the record ID or resource name, e.g. `cocli record upload <record> ./a.mcap ./more-data/`.
 
 ```bash
 # Create a temporary file
 touch episode-1.mcap
 
 # Upload the file to the previously created Record
-cocli record upload 9c9177f6-8194-4d69-8536-3cfebce6fc2 ./episode-1.mcap
+cocli record upload 9c9177f6-8194-4d69-8536-3cfebce6fc23 ./episode-1.mcap
 ```
 
 ```bash
@@ -140,13 +171,17 @@ Upload Status:
 /Users/yujing/Workspace/co/docs/episode-1.mcap:                                                              Upload completed
 
 Total: 1, Skipped: 0, Success: 1
-View record at: https://coscene.cn/coscene-lark/docs/records/9c9177f6-8194-4d69-8536-3cfebce6fc2
+View record at: https://coscene.cn/coscene-lark/docs/records/9c9177f6-8194-4d69-8536-3cfebce6fc23
 ```
 
+:::tip
+In an interactive terminal, in-progress uploads show a progress bar (filled with `=`) and may show **transfer rate** and **elapsed time**; for environments without a TUI, see `--no-tty` and related flags in `cocli record upload -h`.
+:::
+
 ### Download Files from a Record {#download-files-from-record}
 
 ```bash
-cocli record download 9c9177f6-8194-4d69-8536-3cfebce6fc2 .
+cocli record download 9c9177f6-8194-4d69-8536-3cfebce6fc23 .
 ```
 
 ```
@@ -197,7 +232,7 @@ URL:          https://coscene.cn/coscene-lark/docs/records/52c5afac-22ca-4ab5-b9
 ```
 
 :::tip
-If the record is associated with a device or contains custom field values, this information will also be displayed in the `describe` command output.
+If the record is associated with a device or contains custom field values, this information will also be displayed in the `describe` command output. For `describe`, `-o` supports `table`, `json`, and `yaml`.
 :::
 
 ```bash
@@ -221,7 +256,7 @@ URL:                     https://coscene.cn/coscene-lark/docs/records/52c5afac-2
 
 ### Update Record Information {#update-record}
 
-The CLI also supports changing the record's name, description, and other information. For a complete list of updates, please check the help documentation.
+The CLI also supports changing the record's name, description, labels, and custom fields. See the command help for the full flag list. Custom fields use `--custom key=value` and may be repeated.
 
 ```bash
 cocli record update 52c5afac-22ca-4ab5-b9cf-fc069053b1af -d "Object movement process, mechanical arm torque did not reach expected level, failed" # Update record description
@@ -304,6 +339,10 @@ cocli record moment download bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6 . --flat
 
 Labels are an important means of managing and querying records. By adding and removing labels from records, we can easily distinguish different data during batch processing and automation.
 
+:::tip
+In a single `record update`, only one of `--append-labels`, `--update-labels`, or `--delete-labels` may be used (mutually exclusive). The sections below are separate examples.
+:::
+
 ### Add Labels
 
 ```bash