GigleAI/cavil-loop

編碼代理工作循環

English · 中文

將 GitHub issue / PR 評論轉化為你本地 AI 的輸入與輸出。一個 systemd 計時器 + 數個 shell 腳本 + 兩個 GitHub 標籤，讓你直接透過 GitHub 網頁介面（或 iOS gh 應用程式）與 AI 對話。

此技能設計為與代理無關。工作 CLI 由 coding-agent.config 中的 WORKER_AGENT=<name> 選擇；守護行程/調度腳本透過一個薄薄的驅動層來插入不同的代理 CLI。內建驅動：claude（預設，Claude Code）、opencode（sst/opencode）、codex（OpenAI Codex CLI）、cursor（Cursor Agent CLI）。透過 scripts/drivers/<name>.sh 加入你自己的驅動 — 請參閱 docs/drivers.md。

何時呼叫

使用者透過 /coding-agent-work-loop <command> 或自然語言請求，從主機代理執行環境呼叫此技能。常見形式：

• "在專案 X 上安裝此守護行程" → 執行 setup 流程
• "編碼代理的狀態如何？" → 執行 status 流程
• "停用專案 X 上的編碼代理" → 執行 disable 流程

你（代理）在呼叫時應做的事

setup（部署到主機專案）

使用者提供一個主機專案路徑（例如 ~/github/myproject）。步驟：

1. 確認路徑存在且為 git 倉儲（有 .git）
2. 檢查依賴：git、gh（必須透過 gh auth login 登入）、tmux、jq、flock、systemctl，加上 WORKER_AGENT 選擇的工作 CLI（預設 claude；其他內建：opencode、codex、cursor）。每個都必須能透過 command -v 解析。
3. 執行：

   bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.agents/skills/coding-agent-work-loop}/setup.sh" <host-project-path>
   

   $CLAUDE_PLUGIN_ROOT 是 Claude Code 注入的技能根目錄環境變數；如果不存在，則退回到標準路徑 ~/.agents/skills/coding-agent-work-loop。
4. setup.sh 完成後會印出後續步驟指引 — 請逐字轉達給使用者。

status

使用者想要知道狀態。步驟：

1. systemctl --user list-timers 'coding-agent-poll@*' --no-pager — 計時器健康狀態
2. systemctl --user list-units 'coding-agent-poll@*.service' --no-pager — 最後一次執行
3. 對每個已註冊的 ~/.config/coding-agent-work-loop/*.conf：
   • tail -20 $STATE_DIR/poll.log（從設定檔讀取 STATE_DIR）
   • gh issue list --repo $REPO --label pending/agent + gh pr list --repo $REPO --label pending/agent
4. 為使用者總結

cleanup（在 PR 被接受/拒絕後）

使用者合併了一個 PR 或想要中止某個 issue 的工作。步驟：

1. 確認 issue 已完成（PR 已合併或關閉）
2. 執行：

   bash "$CLAUDE_PLUGIN_ROOT/scripts/cleanup-issue.sh" <issue-number>
   

   可選旗標：--force（即使工作忙碌也清理）、--keep-worktree（僅終止 session）、--delete-branch（也刪除本地分支）

cleanup-issue.sh 的作用：

• 忙碌檢查（除非使用 --force，否則預設拒絕）
• 執行專案層級的 CLEANUP_HOOK（在 coding-agent.config 中設定，例如拆除 tailscale 連接埠、停止開發伺服器）
• 終止工作者的 tmux session
• 移除工作樹（預設）
• 可選地移除本地分支

disable

使用者想要停止一個專案。步驟：

1. 確認實例名稱（systemctl --user list-timers 'coding-agent-poll@*'）
2. systemctl --user disable --now coding-agent-poll@<key>.timer
3. 可選：移除 ~/.config/systemd/user/coding-agent-poll@<key>.{service,timer} 實例符號連結（保留樣板本身）
4. 可選：移除 ~/.config/coding-agent-work-loop/<key>.conf
5. 回報結果

不會進入主機專案的內容

setup 完成後，主機專案的工作樹只會新增兩項東西：

1. 一行 .gitignore（排除 coding-agent.config）
2. 一個 coding-agent.config（已被 gitignore，設定檔）

腳本、systemd 單元、狀態、日誌都存放在主機專案之外（技能目錄 + ~/.config/ + ~/.local/state/）。

完整架構

請參閱同層目錄的 README.md。

檔案列表

• setup.sh — 引導主機專案
• scripts/ — 守護行程 + 調度腳本（從不複製到主機專案）
• prompts/ — 初始工作者 prompt 範本（可透過主機專案的 .agents/skills/coding-agent-work-loop/prompts/ 覆蓋）
• systemd/ — [email protected]/.timer 範本單元；setup 會將它們複製到 ~/.config/systemd/user/
• coding-agent.config.example — 設定檔範本