跳到內容

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(英文)。