Create records by convention in Action

docs/6-automation/1-quick-start-workflow.md

@@ -18,11 +18,12 @@ sidebar_position: 1
 
 ### 系统目录
 
-自动化支持的目录结构如下：
-| 目录 | 说明 |
-| --- | --- |
-| /cos/files | 输入目录，即记录中的文件 |
-| /cos/outputs | 输出目录，即每个调用的输出|
+自动化的容器在运行过程中，会挂载多个系统目录，方便与平台的数据进行交互，以下是常见的目录。完整的目录请参考[动作运行时信息](./6-action-runtime.md)。
+
+| 目录         | 说明                       |
+| ------------ | -------------------------- |
+| /cos/files   | 输入目录，即记录中的文件   |
+| /cos/outputs | 输出目录，即每个调用的输出 |
 
 ## 快速开始
 

docs/6-automation/6-action-runtime.md

@@ -1,6 +1,6 @@
 # 动作运行时信息
 
-在动作执行期间，平台会自动注入一系列环境变量，并准备上／下游辅助步骤，方便动作与平台之间进行数据交换。
+在动作执行期间，刻行平台会自动注入一些环境变量，并提供相应的辅助步骤，方便动作与平台进行数据交互。
 
 ## 环境变量 {#environment-variables}
 
@@ -31,4 +31,66 @@
 
 `COS_TOKEN` 会在动作启动时自动注入到环境变量中，其权限与触发者账号 **完全一致**。
 
-在例如 **跨项目** 等操作场景下，请确保触发者对目标项目拥有所需权限，否则相关 API 调用将会失败。
+进行**跨项目**操作时，请确保动作触发者拥有目标项目的相应权限，否则相关 API 调用将失败。
+
+## 使用输出目录创建和更新现有记录
+
+在 Action 的运行时，可以使用 COS_TOKEN 来调用 OpenAPI 或 coCLI 来完成几乎所有的平台操作。
+
+对于创建和更新记录的常见操作，也可以按指定的文件结构输出，动作运行环境自动完成记录创建和更新。
+
+当动作运行结束后，平台会自动扫描 COS_OUTPUT_VOLUME 下的特定目录结构，并根据配置文件自动创建或更新记录，同时上传相关文件。
+
+### 目录结构规范 {#directory-convention}
+
+请在挂载的 COS_OUTPUT_VOLUME 目录内，按照以下结构存放文件：
+
+```
+$COS_OUTPUT_VOLUME
+└── records
+    ├── 记录目录1/                # 任意命名
+    │   ├── front-001.jpg        # 待上传的文件
+    │   ├── front-002.jpg
+    │   └── .cos/
+    │       └── record.patch.json
+    └── 记录目录2/
+        ├── rear-001.jpg
+        ├── rear-002.jpg
+        └── .cos/
+            └── record.patch.json
+```
+
+关键要求：
+
+- /records 下每个一级子目录表示一个记录操作。
+- 每个记录目录内必须包含一个 .cos/ 子目录。
+- .cos/ 目录必须包含一个 record.patch.json 文件。
+- 记录目录中的其他文件会自动上传至对应记录。
+
+### 声明文件格式 {#declaration-file-schema}
+
+`record.patch.json` 定义记录的创建或更新操作，格式如下：
+
+```json
+{
+  "projectSlug": "项目slug", // 可选，默认使用当前项目
+  "id": "记录的 UUID", // 更新或删除操作时必填
+  "labels": [],
+  "title": "记录标题", // 创建记录时必填
+  "description": "记录描述", // 可选
+  // 其他 record 属性，可选
+  "patch": [
+    // RFC 6902 JSON Patch 标准
+    { "op": "replace", "path": "/title", "value": "Cam-front (night)" },
+    { "op": "add", "path": "/labels/-", "value": "night-run" },
+    { "op": "remove", "path": "/labels/0" },
+    { "op": "add", "path": "/files/path/to/file", "value": "../1.jpg" }
+  ]
+}
+```
+
+该 JSON 文件主要包含三个部分：
+
+- 特殊属性：如需要进行跨项目操作，请指定 `projectSlug`。
+- 常规属性：描述记录的基本信息，未指定 id 时表示创建新记录。
+- patch 数组：提供细粒度的属性修改控制，格式遵循 RFC 6902 标准。

i18n/en/docusaurus-plugin-content-docs/current/6-automation/1-quick-start-workflow.md

@@ -18,7 +18,7 @@ Automation is a task-based workflow system. With its flexible and powerful featu
 
 ### System Directories
 
-The directory structure supported by automation is as follows:
+During runtime, action containers mount multiple system directories to facilitate interaction with platform data. The following are common directories. For the complete directory list, please refer to [Action Runtime Information](./6-action-runtime.md)."
 
 | Directory    | Explanation                                            |
 | ------------ | ------------------------------------------------------ |

i18n/en/docusaurus-plugin-content-docs/current/6-automation/6-action-runtime.md

@@ -32,3 +32,65 @@ Some of the above environment variables have empty values, which are optional. I
 `COS_TOKEN` is automatically injected at startup.
 
 Its permissions **mirror those of the user who triggered the action**. When performing **cross-project** operations, ensure the triggering user holds the required permissions on the target project; otherwise, related API calls will fail.
+
+## Using Output Directory to Create and Update Records
+
+During action runtime, you can use `COS_TOKEN` to call OpenAPI or coCLI to perform almost all platform operations.
+
+For common operations like creating and updating records, you can also output files according to a specified file structure, and the action runtime environment will automatically complete record creation and updates.
+
+After the action finishes running, the platform will automatically scan the specific directory structure under `COS_OUTPUT_VOLUME` and automatically create or update records based on configuration files, while uploading related files.
+
+### Directory Structure Convention {#directory-convention}
+
+Please organize files according to the following structure within the mounted `COS_OUTPUT_VOLUME` directory:
+
+```
+$COS_OUTPUT_VOLUME
+└── records
+    ├── record-directory-1/      # Any name
+    │   ├── front-001.jpg        # Files to be uploaded
+    │   ├── front-002.jpg
+    │   └── .cos/
+    │       └── record.patch.json
+    └── record-directory-2/
+        ├── rear-001.jpg
+        ├── rear-002.jpg
+        └── .cos/
+            └── record.patch.json
+```
+
+Key requirements:
+
+- Each first-level subdirectory under `/records` represents a record operation.
+- Each record directory must contain a `.cos/` subdirectory.
+- The `.cos/` directory must contain a `record.patch.json` file.
+- Other files in the record directory will be automatically uploaded to the corresponding record.
+
+### Declaration File Format {#declaration-file-schema}
+
+`record.patch.json` defines record creation or update operations in the following format:
+
+```json
+{
+  "projectSlug": "project-slug", // Optional, defaults to current project
+  "id": "record UUID", // Required for update or delete operations
+  "labels": [],
+  "title": "Record Title", // Required when creating records
+  "description": "Record Description", // Optional
+  // Other record properties, optional
+  "patch": [
+    // RFC 6902 JSON Patch standard
+    { "op": "replace", "path": "/title", "value": "Cam-front (night)" },
+    { "op": "add", "path": "/labels/-", "value": "night-run" },
+    { "op": "remove", "path": "/labels/0" },
+    { "op": "add", "path": "/files/path/to/file", "value": "../1.jpg" }
+  ]
+}
+```
+
+This JSON file mainly contains three parts:
+
+- Special properties: If you need to perform cross-project operations, specify `projectSlug`.
+- Regular properties: Describe basic record information. When no `id` is specified, it indicates creating a new record.
+- patch array: Provides fine-grained property modification control, following the RFC 6902 standard.