Release 25.31

docs/3-collaboration/record/4-upload-files.md

@@ -5,75 +5,82 @@ sidebar_position: 4
 # 上传文件
 
 ## 简介
+
 > 仅项目成员及以上权限角色可上传文件
 
 在[创建记录](2-create-record.md)后，可通过以下方式上传文件：
+
 1. 本地直接上传
 2. 从其它记录复制
 3. 链接导入
 4. 命令行工具 coCLI 上传
 
 ## 本地上传
+
 通过拖拽文件，或点击【上传】按钮，将本地的文件/文件夹上传到记录中。
 
 - 通过【上传】按钮上传
 
   在记录详情页面，点击【上传】按钮，选择文件/文件夹，即可上传。
 
-    ![upload-file_1](./img/upload-file_1.png)
+  ![upload-file_1](./img/upload-file_1.png)
 
 - 通过拖拽文件上传
 
   在记录详情页面，将文件/文件夹拖拽至文件列表区域，即可上传。
 
-    ![upload-file_2](./img/upload-file_2.png)
+  ![upload-file_2](./img/upload-file_2.png)
 
 ## 从其它记录复制
+
 将其它记录中的文件复制到当前记录，实现文件的快速复用。
 
 1. 在记录详情页，点击【上传】中的【复制文件自】按钮。
 
-    ![upload-file_3](./img/upload-file_3.png)
+   ![upload-file_3](./img/upload-file_3.png)
 
 2. 在弹窗中，选择要从哪条记录中复制文件，勾选文件/文件夹，点击【确定】按钮。
 
-    ![upload-file_4](./img/upload-file_4.png)
+   ![upload-file_4](./img/upload-file_4.png)
 
 ## 链接导入
+
 通过粘贴文件 URL 的方式，将远程文件导入到记录中。
 
 1. 在记录详情页，点击【上传】中的【链接导入】按钮。
 
-    ![upload-file_5](./img/upload-file_5.png)
+   ![upload-file_5](./img/upload-file_5.png)
 
 2. 在弹窗中，粘贴文件 URL，点击【确定】按钮。
 
-    ![upload-file_6](./img/upload-file_6.png)
+   ![upload-file_6](./img/upload-file_6.png)
 
 3. 当「通过链接上传文件」动作执行完成后，即可在文件列表中查看导入的文件。
 
-    ![upload-file_7](./img/upload-file_7.png)
+   ![upload-file_7](./img/upload-file_7.png)
 
 ## 命令行工具 coCLI 上传
 
-若要将本地文件批量上传到记录中，可使用[命令行工具 coCLI](../../developers/coSceneCli/1-cli-install.md)。
+若要将本地文件批量上传到记录中，可使用[命令行工具 coCLI](../../developers/cocli/1-cli-install.md)。
 
 ## 了解更多
+
 - [管理文件](5-manage-file.md)
 
 ## 常见问题
+
 1. **问：上传同名文件是什么逻辑**
 
-    答：本地上传同名文件时，会自动覆盖；通过系统动作生成的文件，如：解压缩、链接导入等，会自动重命名，即在文件名后加上后缀。
+   答：本地上传同名文件时，会自动覆盖；通过系统动作生成的文件，如：解压缩、链接导入等，会自动重命名，即在文件名后加上后缀。
 
 2. **问：上传文件到一半时，网络中断，文件上传失败，如何处理？**
 
-    答：上传文件失败时，会在上传进度弹框中显示「上传失败」的状态，需要重新上传该文件。
+   答：上传文件失败时，会在上传进度弹框中显示「上传失败」的状态，需要重新上传该文件。
 
 3. **拖拽上传文件夹时，文件上传了两份，为什么？**
 
-    答：若拖拽时展开了文件夹，并选中了文件夹与文件夹下的文件，则会将其分别进行上传。仅拖拽文件夹上传即可解决该问题。
-    
+   答：若拖拽时展开了文件夹，并选中了文件夹与文件夹下的文件，则会将其分别进行上传。仅拖拽文件夹上传即可解决该问题。
+
 4. **链接导入失败，如何处理？**
 
-    答：请检查链接是否正确，是否为公开链接。
+   答：请检查链接是否正确，是否为公开链接。

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/4-trigger.md

@@ -16,10 +16,12 @@ sidebar_position: 3
 
 ## 触发条件
 
-平台支持以下两种触发时机：
+平台支持以下触发时机：
 
 - 上传文件到记录时
-- 任务状态变更时
+- 设备采集状态变更时
+- 记录变更时
+- 通用任务变更时
 
 ### 上传文件到记录时
 
@@ -33,16 +35,32 @@ sidebar_position: 3
 
 ![trigger_6](./img/trigger_6.png)
 
-### 任务状态变更时
+### 设备采集状态变更时{#collect-status-change}
 
-当「手动采集任务」或者「规则采集任务」的状态发生变更时，触发器会检查任务的状态是否满足触发条件。
+当「手动采集」或者「规则采集」的状态发生变更时，触发器会检查设备采集的状态是否满足触发条件。
 
-例如：当手动采集任务完成时，触发器会触发动作运行。
+例如：当手动采集完成时，触发器会触发动作运行。
 
 ![trigger_7](./img/trigger_7.png)
 
-## 关联动作
+### 记录变更时
+
+当记录的标签或自定义字段发生变更时，触发器会检查变更的内容是否满足触发条件。
 
-用户在动作页面创建的所有动作均属于项目动作，可按需选用。平台基于客户常见业务场景，预先开发并内置了一系列通用系统动作，如数据诊断功能。
+例如：当记录添加 `uploaded` 标签时，触发器会触发动作运行。
 
 ![trigger_8](./img/trigger_8.png)
+
+### 通用任务变更时
+
+当「通用任务」的字段发生变更时，触发器会检查变更的内容是否满足触发条件。
+
+例如：当通用任务状态为「已处理」时，触发器会触发动作运行。
+
+![trigger_9](./img/trigger_9.png)
+
+## 关联动作
+
+用户在动作页面创建的所有动作均属于项目动作，可按需选用。平台基于客户常见业务场景，预先开发并内置了一系列通用系统动作，如「解压文件」功能。
+
+![trigger_8](./img/trigger_10.png)

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 标准。

docs/client/2-apt-source-install.md

@@ -13,7 +13,7 @@ curl -fsSL https://apt.coscene.cn/coscene.gpg | sudo gpg --dearmor -o /etc/apt/t
 ## 添加仓库到源列表
 
 ``` bash
-echo "deb [signed-by=/etc/apt/trusted.gpg.d/coscene.gpg] https://apt.coscene.cn $(. /etc/os-release && echo $UBUNTU_CODENAME) main stable" | sudo tee /etc/apt/sources.list.d/coscene.list
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/trusted.gpg.d/coscene.gpg] https://apt.coscene.cn $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/coscene.list
 ```
 
 ## 更新 APT 仓库