Agent：匯入、更新、刪除

Agent 生命週期

階段	IndustrialClaw 提供的能力
Build 建置	把 Agent 打包成一個 ZIP（TOOLS.md ＋ skills/），匯入時逐項掃描
Deploy 部署	把套件匯入核准的設備，並指派給可以使用它的帳號
Manage 管理	版本、權限、運行狀態、Log、Session、Outputs 與 Audit
Scale 擴展	把驗證過的套件複製到更多設備、產線與場域

Agent 部署之後，設備上的日常運作是圍繞著平台的一個循環：編排、派工與執行、監控、治理，再持續改善。圖中的 Agent 類型只是示意，不是平台定義的名稱。

每個階段由誰負責，取決於各場域自己的組織分工，不是平台規定的。IndustrialClaw 自己定義的角色只有 Administrator、User 與初始 admin，詳見角色與限制。

建立 Agent 套件

一個 Agent 就是一個 ZIP，結構如下：

<agent-name>.zip
├── TOOLS.md
└── skills/
    ├── <skill-name>/
    │   ├── scripts/        （選填）
    │   ├── references/     （選填）
    │   └── SKILL.md
    └── <每個 Skill 一個資料夾>/

建立步驟

1. 建一個資料夾，在 skills/<skill-name>/ 底下寫一份 SKILL.md。Skill 需要執行腳本時，把腳本放在同一個 Skill 的 scripts/。

2. 在資料夾根目錄寫 TOOLS.md，在 ## Skills 底下列出每個 Skill。

3. 先在設備上直接執行 SKILL.md 寫的指令，確認腳本可以正常跑完並產生預期結果。

4. 進入資料夾，把 TOOLS.md 與 skills/ 打包成 ZIP。檔名就是 Agent 名稱，只能用小寫英文、數字與 -，不能叫 main 或 main-agent：

   zip -r ../<agent-name>.zip TOOLS.md skills

   也可以用壓縮工具選取 TOOLS.md 與 skills/ 壓縮，但兩者必須在 ZIP 最外層，不能再多包一層資料夾。Task 檔不要放進 ZIP。

5. 依照匯入 Agent 匯入，再建立 Task 執行驗證。

TOOLS.md

匯入時，平台會讀取 ## Skills 的清單。新增或改名 Skill 時，請確認：

• 每個 Skill 各列一行，格式為 - [名稱](skills/名稱/SKILL.md)。
• 名稱與 skills/ 底下的資料夾名完全相同。
• 每個資料夾都列到，沒有漏列、多列或重複。

其他區塊（例如 ## Purpose）是寫給人看的說明。

複製空白的 TOOLS.md

# <Agent 標題>

## Skills

- [<skill-name>](skills/<skill-name>/SKILL.md)

## Purpose

<這個 Agent 的用途>

SKILL.md

一份 SKILL.md 的骨架由四個區塊組成：

區塊	告訴模型什麼
Description	這個 Skill 做什麼、什麼時候該用它
Behavior	要執行的完整指令，以及它會、不會做哪些事
Expected Result	成功時的輸出長什麼樣子
Completion Criteria	怎樣才算成功

複製空白的 SKILL.md

# <Skill 標題>

## Description

<這個 Skill 做什麼、什麼時候該用>

## Behavior

Run the bundled script:

```bash
<完整指令>
```

<會做與不會做的事>

## Expected Result

<成功時的輸出>

## Completion Criteria

<怎樣才算成功>

為小模型而寫

Skill 要在 4B 等級小模型上驗證。小模型容易漏掉隱含步驟，寫法要明確：

• 一步一件事，指令整行寫完。
• 已知參數直接寫出；計算與複雜條件交給腳本。
• 明講讀哪個檔、寫到哪個路徑、輸出包含什麼。
• 用 qwen3.5:4b 或同級模型實際跑一次：通過匯入與掃描不代表結果正確。

需要額外執行環境時

需要額外套件、GPU 或服務時才需要這一節。

未宣告 runtime 的 Skill 在共用容器 skill-runner-<agent>（Python 3.12 ＋ Node 24）執行。容器用完即刪，安裝步驟要寫進 SKILL.md，每次執行重裝：

## 環境需求

    pip install "requests>=2.31"

需要專屬容器時，在 SKILL.md 開頭用 YAML frontmatter 宣告（寫在正文無效）：

---
runtime:
  type: compose
  file: docker-compose.yml
  service: worker
---

type	必填欄位	說明
compose	file、service	Compose 檔與要跑的 service
dockerfile	file（可選 context）	由 Dockerfile 建置
image	image	直接使用現成 image

路徑相對於 Skill 目錄，不可為絕對路徑或含 ..。權限確認見匯入 Agent。

環境超過幾行 pip install（系統套件、GPU 函式庫、資料庫、安裝耗時）時，建議用 Compose：共用容器每次重裝，專屬容器只建置一次。

套件規則

項目	規則
<agent-name>.zip	ZIP 檔名就是 Agent 名稱；名稱已被使用時會自動加上尾碼。根目錄除了 TOOLS.md 與 skills/ 不放別的
TOOLS.md	在 ## Skills 底下每個 Skill 一行，開頭是該 Skill 的目錄名，必須與 skills/ 底下完全一致
SKILL.md	每個 Skill 目錄都要有一份，而且不能是空的
大小	20 MB 以內
模型	Skill 需小模型驗證過，可以正常運行

完整範例見建立第一個 Agent。

匯入 Agent

以 Administrator 開啟 Dashboard → Agent Management，按 Create Agent。

步驟	會發生什麼
Import Package	選擇 Agent ZIP 後繼續。這時還沒有建立任何東西。
Security Scanner	套件會被掃描。逐一檢視每個 Skill 的風險、檔案位置、權限、掛載與連接埠。
Create Agent	檢視摘要後確認。自備容器的 Skill 會在你核准之前，先列出它想要的目錄、連接埠與權限。

查看：Import Package

查看：Security Scanner

查看Agent 已建立畫面

前兩步中途退出不會留下任何東西；匯入失敗也會完整回退——不會有裝到一半的 Agent。

掃描結果

結果	平台會怎麼做	你要做的事
LOW	繼續	確認基本權限與相依套件。
MEDIUM	顯示警告，並要求 Administrator 確認「這一次的掃描結果」	讀懂該筆發現與它指向的檔案，確認這個行為確實必要。
HIGH	擋下匯入	退回去修好，重新掃描。
CRITICAL	擋下匯入	停下來，請人工檢視程式碼。

完整的規則與門檻在安全掃描參考。

常見的匯入問題

訊息	原因
TOOLS.md 與 Skill 對不起來	名稱和資料夾名不一樣，或漏列／多列
沒有權限	設備還沒配對，跑一次 setup_pairing.sh
檔名不合規	ZIP 檔名有大寫、空格、底線，或使用了保留名稱 main、main-agent

Agent 的 workspace

建立 Agent 的同時會給它一個自己的 workspace：

目錄	放什麼
skills/	套件裡帶進來的 Skill
tasks/	之後才建立的 Task 定義
materials/	Task 需要的輸入檔案
outputs/	Task 宣告的產出預設放這裡

新的 Agent 還沒有任何 Task，這是正常的。

容器裡會有什麼

execute、check 與 Final Verification 都可使用以下環境變數：

變數	內容
TASK_ID	這次 Task 的 id
TASK_ARTIFACT_DIR	可寫的目錄，放中間檔與工作檔
TASK_MANAGER	平台 CLI 的位置，用來寫 Task 自己的紀錄

沒有輪次、Step 編號或重試次數的變數；跨輪次比對用 TASK_ID。

可寫入的路徑只有 Agent workspace（產出）與 $TASK_ARTIFACT_DIR（中間檔）。Expected Output 不要寫進 $TASK_ARTIFACT_DIR，平台不會檢查那裡。

stdout 會收進 Task 的 Log；要獨立、可下載的紀錄檔，用平台 CLI：

python3 "$TASK_MANAGER" output-log "$TASK_ID" --append "cpu=12.4"
python3 "$TASK_MANAGER" output-log "$TASK_ID" --append "12:00,4.9" --file rows.csv

更新 Agent

1. 停掉這個 Agent 上正在執行的 Task。
2. 在 Agent Management 該 Agent 的列按 Update。
3. 完成 Import Package → Security Scanner → Update Agent。
4. 確認更新後的 Skill 與模型。

查看：更新 Agent

查看更新檢視畫面

更新包只帶有變動的 Skill，但掃描器評估的是合併後的完整內容，不是差異包本身。更新成功會保留這個 Agent 既有的 Task、Material、Outputs 與其他 workspace 檔案；任何一步失敗，安裝中的版本原封不動——更新失敗不等於停機。

更新既有 Agent 不佔 10 個 Sub-Agent 的上限。

刪除 Agent

1. 停掉它上面所有執行中的 Task。
2. 把需要保留的 Outputs 下載下來。
3. 在 Agent Management → Sub-Agents 按 Delete，再確認一次。

查看：刪除 Agent

查看確認刪除畫面

刪除是永久的：停掉該 Agent、移除註冊，並刪掉整個 workspace——Task 定義、Material 與 Outputs 一起消失。原始 ZIP 不受影響，可以再匯入。Main Agent 不能被刪除。

相關文件

• Agent 角色與協作 —— Main Agent、Sub-Agent 與檔案交接
• 建立第一個 Agent —— 套件格式，以及更新包可以放什麼
• 安全掃描參考 —— 掃描結果背後的每一條規則
• Task —— 給新的 Agent 一點事做