【2026 最新】CoworkOS 教學：自架三層 Agent，用 CSV 驗收產物、人工改稿與續跑

你請 AI 整理一份 CSV，它回覆「已完成」，但總額算錯；你手動改了價格，接著按續跑，它又拿舊數字交差。這篇 CoworkOS 教學，帶你把派工、檔案和對話狀態接起來，讓「完成」有一個能核對的答案。

寫給第一次接觸多代理、願意在終端機貼上指令的新手。你會先認識三層分工，再準備三筆假資料、獨立驗收器與兩輪改稿練習。已有模型服務的讀者可以接著執行 CoworkOS；還沒準備端點，也能先完成本機驗收器。

本文依 2026 年 11 月 4 日查閱的官方文件與原始碼整理，安裝範例固定 npm coworkos-app@0.1.3。AlphaLab 本次執行了下方驗收器的合成案例，未呼叫 CoworkOS 模型端點，也未執行代理改稿與中斷續跑；後兩者提供的是操作協議，沒有預填成功結果。

先說結論：可靠交付＝派工紀錄＋同版產物＋獨立驗收

可靠交付＝派工紀錄＋同版產物＋獨立驗收。把它想成一間小工作室：主責者決定要交什麼，調度員追工作進度，協作者交回草稿；最後還得拿著原始資料，對照真正交出的檔案。

• 先用三筆資料定義答案，再讓 Agent 工作；「我完成了」只是待檢查的回報。
• 人工改稿後留下新指紋，讓摘要清楚對應新版本。
• 續跑先盤點哪些動作已落地，再決定補做什麼；保留待辦與輸出檔兩份證據。

一、CoworkOS 教學：先把三層分工說清楚

本篇的 CoworkOS 是 RUC-NLPIR 公開的開源 cowork harness。Harness 可以理解成「讓模型能持續做事的執行層」；它把工具、工作狀態和回饋接起來。想先補上模型與執行層的差別，可讀 Agent Harness 白話教學。

① Main Agent：「專案主責者」。它決定策略、切分工作，並評估交付。以本篇為例，就是決定讀哪份 CSV、需要哪些欄位，以及錯誤時要退回重算。

② Coordinator Runtime：「調度與收件簿」。它安排委派、保存狀態與待送回饋，把任務、執行與回傳對到同一個身分。這是一層執行管理，不應把三層圖理解成每輪固定呼叫三個模型。

③ Subagents：「接小任務的協作者」。它們在提供的上下文與權限內工作，交回報告和檔案線索。子代理是選用；一個很小的摘要也可能由 Main 直接處理。官方架構說明把 runtime、應用服務和儲存的責任分開，適合對照原始碼。

二、先安裝與連線：從空白練習資料夾開始

第一個痛點是「程式裝好了，為什麼還不能做事？」安裝、模型設定、連線測試分三步。依 官方 CLI quickstart，這條路徑適用 macOS／Linux，需要 Node.js ≥22.19.0 與 npm。先執行版本查詢；版本不足時先完成 Node.js 安裝，再回到這裡。

node --version
npm --version
npm install -g coworkos-app@0.1.3
coworkos --version
mkdir -p "$HOME/coworkos-csv-lab"
cd "$HOME/coworkos-csv-lab"
pwd
coworkos init

記下 pwd 印出的專案絕對路徑，稍後把它交給 Main。若這個資料夾已有檔案，另取一個空資料夾名稱；這次只放練習資料。若安裝提示既有套件占用 coworkos 命令，照 quickstart 處理舊套件，不加 --force 強蓋。

設定依序填服務商給你的 API URL、模型 ID、API key。這不是登入一般聊天介面；你需要可用的模型服務與額度。URL 填根地址或 /v1，不要填到 /responses 或 /chat/completions。新連線預設 Responses，且所選格式必須支援串流與工具呼叫；詳見 模型設定文件。

# 只有服務僅支援 Chat Completions 時，才先設定這一行
export COWORK_MODEL_API=openai-completions
# 測試會送出模型請求並消耗服務額度
coworkos doctor --test-connection

看到所有檢查通過、模型那行為 OK 流式模型连接与工具调用 再往下；FAIL 就先修該項。這個環境變數只影響當前終端機及其啟動的程序；若原本使用 Responses，不執行那行。coworkos doctor 不加連線旗標時是本機檢查，適合找實際設定路徑。

先在供應端設定可接受的額度上限。Main、子代理、重試及連線測試都可能產生請求；開源授權與模型用量是兩本帳。空資料夾也不是權限沙箱：正式隔離要靠執行環境的可讀寫範圍，第一輪別放客戶資料或帳號祕密。

三、CoworkOS 教學的第一張考卷：三筆 CSV、四個答案欄位

第二個痛點是「怎樣才叫算對？」先固定交付格式。在剛才的專案資料夾新增 sales.csv，貼上以下文字並存檔；若用試算表編輯，選 UTF-8 CSV，保存後再核對內容。

id,qty,unit_price
A001,2,60
A002,1,80
A003,3,30

這份假資料共有三列、數量合計六，金額為 2×60＋1×80＋3×30＝290.00。我們把交付定為 summary.json：row_count 是整數 3、quantity_total 是整數 6、amount_total 是字串 "290.00"，另附 source_sha256。

SHA-256 是檔案的內容指紋：原始位元變了，摘要也應改用新指紋。它能把結果和某一版輸入對上，不能單靠指紋證明計算正確，也不能證明模型真的讀過檔案。Python 的 hashlib 文件說明了這個計算介面。

把核對器留給操作者，別和待驗產物混在一起

在專案外另存一份 verify_csv.py，例如放在你自己的 coworkos-review 資料夾；不要把改驗收器列進 Agent 的任務。下列程式只讀指定 CSV 與 JSON，以十進位數重新計算並逐欄比較。若要作正式系統評估，還須用權限隔離保護這份可信副本；不同資料夾名稱本身不會禁止 Agent 修改它。

import csv
import hashlib
import io
import json
import sys
from decimal import Decimal
from pathlib import Path

source, output = map(Path, sys.argv[1:3])
raw = source.read_bytes()
rows = list(csv.DictReader(io.StringIO(raw.decode('utf-8'))))
assert rows, 'empty CSV'
assert set(rows[0]) == {'id', 'qty', 'unit_price'}, 'CSV columns'
assert len({r['id'] for r in rows}) == len(rows), 'duplicate id'
assert all(r['id'] for r in rows), 'missing id'
quantity = 0
amount = Decimal('0')
for r in rows:
    q = int(r['qty'])
    price = Decimal(r['unit_price'])
    assert q >= 0 and price.is_finite() and price >= 0, 'invalid value'
    quantity += q
    amount += q * price
expected = {
    'source_sha256': hashlib.sha256(raw).hexdigest(),
    'row_count': len(rows),
    'quantity_total': quantity,
    'amount_total': format(amount, '.2f'),
}
actual = json.loads(output.read_text(encoding='utf-8'))
assert isinstance(actual, dict) and set(actual) == set(expected), 'JSON fields'
for key, value in expected.items():
    assert type(actual[key]) is type(value) and actual[key] == value, key
print('PASS', source.name, 'rows=', len(rows), 'amount=', expected['amount_total'])

先查 python3 --version，確認已有 Python 3。這段只用標準函式庫；csv.DictReader按欄名讀資料，Decimal以十進位運算。本練習限定上述三欄、非負數量與價格，金額輸出兩位小數；它是教學核對器，尚未包含任意大檔案、並行改寫與完整 CSV 業務規則。

四、交辦與驗收：讓錯誤有機會被擋下來

第三個痛點是「子代理報告很好看，怎麼知道輸出在哪？」交辦時要求路徑與證據。在專案資料夾執行 coworkos，把下列請求貼進互動輸入區；將尖括號內容換成剛才 pwd 的實際結果。

專案絕對路徑是 <貼上你的專案絕對路徑>。
讀取該路徑的 sales.csv，不修改輸入資料。
計算資料列數、qty 合計，以及 qty × unit_price 的總和。
將 summary.json 寫回同一專案資料夾，且只包含四欄：
source_sha256（輸入原始位元的 SHA-256 字串）、row_count（整數）、
quantity_total（整數）、amount_total（兩位小數字串）。
如果委派，請記錄子任務身分、候選檔路徑及檢查結果；
由 Main 讀取候選檔後決定採用，最後再讀回專案內的 summary.json。
完成回覆請列出實際輸出絕對路徑與仍未完成的項目。

官方 Coordinator 原始碼將子代理的 deliverables/ 視為候選產物，讓 Main 依路徑檢查後整合。「子任務結束」「檔案存在」「檔案正確」要各看一次。你的練習可能沒有委派；如有，記錄實際產生的身分，不自己編一個 call ID。

等回覆後先保存原文；輸入清空再按 Ctrl+D 離開。在同一個終端機執行以下命令；假設你已把核對器放在這個示例位置，否則改成實際路徑。

python3 "$HOME/coworkos-review/verify_csv.py" sales.csv summary.json

通過會印出 PASS、列數與金額；出現例外、非零結束或缺檔，都先保留失敗紀錄。把錯誤欄位交回 Main 修正，再用同一份核對器重跑。驗收器只核對此次讀到的兩個檔案，因此執行時先暫停人工與 Agent 寫入，避免讀取途中換版。

故意把總額改錯，觀察下一步是否改變

另存原始輸出，再人工把練習用 summary.json 的 amount_total 改成 "999.00"，其餘欄位保持原樣。重新執行核對器，應在 amount_total 拒絕。這是你安排的錯誤注入，並不是聲稱 CoworkOS 曾產生這個錯誤。

接著用 coworkos --continue 回到對話，明確要求重新讀取當前檔案，把核對器失敗回報交給 Main。觀察它是重算、退回候選、查錯檔，還是只重複先前的成功敘述；只記實際出現的行為。檔案檢查是否影響下一步決策，才是這一題真正要收的證據。

AlphaLab 已執行五個自製案例：正確基線通過、錯總額拒絕、改輸入但沿用舊摘要拒絕、更新摘要通過，以及用布林值冒充列數拒絕。這五項只驗證核對器；沒有把任何一項記成 CoworkOS 的成功率。

五、人工改稿與續跑：版本變了，完成條件也要更新

第四個痛點是「人改完資料，AI 還沿用舊摘要」。先停寫、再改稿、再通知。結束目前回覆與相關寫入後，把 sales.csv 的 A002,1,80 改成 A002,1,100 並保存。列數與數量不變，總額應改為 310.00；原摘要的來源指紋也已過期。

這時先跑一次核對器，讓舊摘要失敗，再請 Main 重新讀檔與產生新摘要。這裡用的是外部編輯器改 CSV 的協作練習。官方 內建文字編輯器文件列的是 TXT、Markdown 等文件；不要把這個 CSV 流程說成已測過內建試算表或應用資源的修訂協定。

CoworkOS 的 Runtime 參考另有 application candidate 接受與基底 revision 檢查：那是經應用服務操作受管資源的路徑。一般 CSV 檔案讀寫和受管資源的版本檢查，應分開記錄；本篇用原始位元指紋自行建立輸入與結果的對應。

第五個痛點是「中斷之後，到底哪些事已經做過？」把重接對話和重做工作分開。先要求 Main 分兩階段：只檢查現有輸出，列出待辦；下一則訊息才授權更新。需要中斷正在進行的回覆時按 Esc，記下當時畫面、檔案及待辦，再清空輸入、按 Ctrl+D 離開。

cd "$HOME/coworkos-csv-lab"
coworkos --continue
# 若要自行選取已存的對話，使用 coworkos --resume

接回後先問：「重新讀取目前 sales.csv 與 summary.json，列出已完成、待處理及需要我確認的事項；先不要重寫。」再核對它讀到的版本。--continue 延續該目錄最近的對話，--resume 選取已存對話；直接執行 coworkos 則開新對話。

官方 Runtime 文件明確區分停止 Main 和取消委派子代理：停止 Main 回合不會自動取消子代理，需明確使用取消子代理的控制。因此準備人工改稿前，要檢查仍在寫入的工作；不要把按 Esc 當成整個系統已靜止。對話重接也不是檔案回滾，已落地的修改要先盤點。

把自己的觀察寫成簡短紀錄：工具版本、專案路徑、會話識別、實際子任務身分、來源指紋、輸出路徑、核對器結束碼、Main 採取的下一步，以及仍待處理的工作。這份紀錄由你保存，並非宣稱 Runtime 已自動輸出這些 CSV 驗收欄位。

常見問題：八個先講答案的判斷

1. 三層架構會固定叫出三個 AI 嗎？

不會由層數決定。Coordinator 是執行管理；子代理為選用，記錄本次實際委派幾個。

2. 我一定要先安裝桌面 App 嗎？

這條練習走 CLI。安裝、模型連線、檔案讀寫與續接，都依官方 CLI 文件進行。

3. 連線測試會消耗用量嗎？

會。doctor --test-connection 會請求模型；只有 doctor 的本機檢查與它不同。

4. 子代理回覆完成，就可以省略核對器嗎？

仍要讀檔。回傳敘述、候選產物與最後交付分別留證據，再核對內容。

5. 指紋相同，代表答案算對嗎？

不代表。指紋對來源版本，重新計算對結果；兩者合起來才是本篇的交付檢查。

6. 把 CSV 放空資料夾，就有沙箱嗎？

還需要權限隔離。工作目錄只是操作起點，並非作業系統的存取邊界。

7. continue 會復原改錯的檔案嗎？

先盤點現況。它接回對話；若需要回復資料，使用你保存的副本並再次驗收。

8. 五個本機案例通過，代表 CoworkOS 已驗證可靠嗎？

只代表這五個核對器案例符合預期。代理執行、人工改稿的接收，以及中斷後待辦，需在你的模型與環境另外收紀錄。

給新手的三個重點

• 先寫完成條件，再交辦：列數、數量、金額與來源版本各自有答案。
• 把口頭報告連回真實路徑；候選檔通過檢查後，最後交付也要讀回。
• 人工改稿與中斷都可能留下已完成的變更；續接先盤點，再補做。