Coding 套件
pi-roundtable-coding 提供管理 repository 的 shelf,以及獨立執行的 Pi coding worker。
worker 能修改 clone、建立 commit,再回報分支和變更。
送出變更是另一個步驟:repo_push 只會在 host 的 hold gate 放行後,把先前回報過的完整 SHA 推到 default branch,不會 force push。
bun add pi-roundtable-coding pi-roundtable需要 Linux 或 macOS 上的 Bun 1.4.4 以上、>=0.50.0 <0.51.0 的 pi-roundtable,以及 >=1.0.0 <2 的 Pi。
若 host 仍使用 Pi 0.99.x,加入這個套件前要先升級 Pi 相依套件。
預設 clone 方式需要 Git 和 GitHub CLI(gh)。
host 也要有能讀取 repository 的 Git credential;只有確實需要推送的 repository 才給寫入權限,並準備 Pi model credential。
預設 clone 會執行 gh repo clone;之後 fetch 和 push 需要設定 Git credential helper。
import { coding } from "pi-roundtable-coding";
export default { // ...其他 roundtable 設定... plugins: [coding({ shelfDir: "/srv/roundtable/repos", model: "provider/model-id", })],};| 選項 | 預設值 | 用途 |
|---|---|---|
shelfDir |
必填 | 管理 clone 的目錄。 |
model |
必填 | worker 使用的 Pi model,格式為 provider/model-id。 |
thinking |
medium |
worker 的 thinking level。 |
ownerRepos |
[] |
完整的 owner/repo 名稱;這些 repository 不會觸發套件本身的 push hold。 |
isOwnerRepo |
無 | host 明確提供的 push 免核准政策,可涵蓋未來的 clone;只有回傳 true 才免核准。 |
pushHoldText |
repo、sha、目標與分支 | host 明確提供的 repo_push 核准卡片文字;只改文字,不改變誰需要核准。 |
adoptClones |
[] |
啟動時移入既有獨立 clone,保留內容,不覆蓋 shelf 上的目錄。 |
resolveRun |
設定的 worker、呼叫者 channel | 依呼叫者選擇 model、thinking、回報 channel 和 thread origin。 |
postChangeReport |
目前 surface | 用呼叫者身分,在指定 channel 張貼修改紀錄。 |
presentation |
套件英文文字 | 修改報告的張貼/工具結果,以及啟動通知與略過 skill 的說明。 |
toolText |
套件文字 | 各 repository 工具的說明與參數描述,例如 { repo_task: { description, parameters: { task: "…" } } };不改變工具的引數或核准規則。 |
threads / threadText |
無/英文 | 進度與核准 thread 介面,以及 host 自訂文字。 |
workerWorkspace / workerPrompt |
clone/通用指示 | 可信任的 shell 寫入政策邊界與常駐 prompt。 |
workerBlockText |
預設拒絕訊息 | worker 被拒絕或未核准時讀到的文字;不改變誰需要核准。 |
limits |
20,000 報告字數、10 個 hold 項目各 1,000 字 | { reportChars?, heldEntries?, heldChars? }:報告保留的內容上限;各欄位都是整數(至少 1)或 Infinity。 |
diagnosticChars |
600 |
failure 中保留的 git、gh 和 worker 錯誤文字長度;整數(至少 1)或 Infinity。 |
skipUnavailableCarriedSkills |
false |
明確開啟後,略過並告知載入失敗的 implicit skill;指定 skill 仍會拒絕。 |
workerPackages |
[] |
worker 載入的已安裝 Pi extension 絕對路徑。 |
agentDir |
Pi host 目錄 | Pi 登入與 model 設定所在目錄。 |
workerEnv |
{} |
{ pass? }:worker process 為了 model 額外取得的 host 環境變數;models.json 的 $VAR、CLAUDE_*、ANTHROPIC_* 已自動帶上。它的 shell 永遠拿不到。 |
githubToken |
setup 時讀取的 host GH_TOKEN |
字串或函式,只以 GH_TOKEN 交給 shelf 的 git 與 gh 呼叫。 |
timeoutMs |
3600000 |
工作時間上限;等待 owner 核准的時間不計入。 |
holds |
無 | 額外的 worker hold check。 |
clone |
ghClone |
替代的 Git host clone 實作。 |
worker |
PiCodingWorker |
可信任的 worker runner 替代實作。 |
onResult |
回覆目前 surface | 自訂結果傳送方式。 |
resolveRun(turn) 回傳 { model, thinking, channel, origin? };carried skills 仍依呼叫者決定。
onResult 的 job 包含載入成功的 skillNames 和可選的 thread,host 可以將結果排入新對話 turn,並保留自己的語言與格式。
設定 thread 後,核准卡只出現在該 thread,封存後才傳送結果;無法開 thread 時,高風險動作會保留,不會改向其他 channel 索取核准。
clone 路徑仍是 shelfDir/owner/repo,不需要資料庫遷移。
這是 host 上的 coding desk,不是 sandbox。
worker process 只拿到 shell 的環境變數白名單、PI_CODING_AGENT_DIR、model 可能讀的變數(models.json 的 $VAR、CLAUDE_*、ANTHROPIC_*)與 workerEnv.pass 列出的名稱;它的 shell 只拿到白名單與 host 的 shellEnv,永遠拿不到 model 的憑證。
它仍能讀取 host 使用者可存取的檔案、執行 shell command、使用網路並建立 commit。
hold rule 只會用 heuristic 偵測特定高風險 shell 操作,不是作業系統隔離。
只對可信任的 repository 和程式碼使用,最好讓它在權限較低的專用 host 帳號下執行。
如果不能接受它存取 host,請改用 container 或 VM。
token 不要放進 URL,並使用最低必要權限;套件不會記錄 credential 或 subprocess 診斷內容。
使用 repo_change_report 和 repo_push 前,先檢查 worker 的變更與驗證結果。
ownerRepos 和 host 明確提供的 isOwnerRepo 政策,只略過這個套件的 push hold,不會略過 shell hold 或其他 host 規則。
免核准政策不可來自 model 輸入或 repository 檔案。
自訂 prompt 與文字不會略過完整 SHA 的報告紀錄、non-force push、取消或 process group 清理。
完整流程、工具介面和限制見pi-roundtable-coding README(英文)。