在終端中使用程式設計代理
終端編碼代理（例如 Claude Code 或 Codex）可以將 Kanera 卡從提取到完成：讀取卡、宣佈卡正在工作、報告進度、在需要人員時進行標記以及將卡標記為完成。本指南將迴圈設定為 Kanera CLI，適用於任何可以執行 shell 命令的代理。
安裝並登入
在執行代理的計算機上安裝 CLI 一次,需要 Node 22 或更高版本。
npm install --global @kanera/cli
kanera auth login --agent "Claude Code" # use your agent's own product name
kanera auth login 列印一個連結和程式碼,並在瀏覽器中開啟該連結。 在檢查程式碼匹配後,在那裡批准請求,CLI 將儲存一個自我更新的登入。 對於無人值守執行的代理,如 CI,請使用 kanera auth login --with-api-key 用一個鍵從 配置檔案設定 -> API 金鑰 然後選擇 只讀 然後確認代理將能夠做什麼: 確認代理將能夠做什麼:
kanera whoami # the user and the credential's scope
kanera doctor # credentials, connectivity, and the API address in use
對於沙盒或 CI 作業,跳過儲存的配置檔案並設定 KANERA_API_KEY 請參見 Kanera CLI 對於命名配置檔案和自託管地址。
只讀或寫入
選擇金鑰的工作範圍，而不是為了方便。
- 只讀 適合只需要找到並讀取工作的代理:分類、在開始之前總結卡片,或回答"我的盤子上有什麼? " Kanera 拒絕 API 中的每個更改,無論代理嘗試什麼。
- 寫 此頁面上的所有其他操作都需要註冊:開啟賽局、評論和完成卡片。 Kanera仍然會在每個看板上檢查你的角色,所以代理人不能更改你是觀察員的看板。
拒絕寫入並退出並帶有程式碼 4，與普通失敗不同，因此代理可以停止並告訴您而不是重試。 代理安全 介紹如何設定代理的訪問範圍。
安裝代理說明
kanera setup 編寫指令,教導代理如何安全使用 CLI:首先檢查金鑰的作用域,然後使用 kanera commands --json 用來代替猜測, --quiet 或 --json 解析輸出時,並將破壞性工具視為需要明確請求。
kanera setup claude # writes .claude/skills/kanera/SKILL.md in the current directory
kanera setup claude --global # writes ~/.claude/skills/kanera/SKILL.md for every project
kanera setup codex # adds a Kanera section to AGENTS.md in the current directory
kanera skill # prints the skill document, for any other agent
setup claude安裝了Kanera的代理技能,當Claude Code在Kanera出現時載入了它。 它不會覆蓋現有的SKILL.md;重新執行--force升級 CLI 後替換它。setup codex創造AGENTS.md如果它不存在,則將其刪除,或者新增一個短的 Kanera 部分。 重新執行是安全的:如果檔案已經記錄了 Kanera,則不會改變任何內容。kanera setup agents對於任何讀取代理的代理,AGENTS.md.
兩個設定目標都包括工作迴圈：當被要求執行卡片時，代理開始執行，保持進度可見，評論其結果，並在最終答覆之前將卡片移動到適當的列表。只讀問題、探索性計劃、僅草稿請求和明確限制不授權這些寫入。現有安裝保留舊指令：升級後，重新整理 Claude 技能 --force，或更新現有的 Kanera 部分 AGENTS.md 使用當前 kanera skill 調整輸出。 專案說明如下 為您的工作流程。
工作迴圈
下面的每個步驟都是代理執行的命令。 Card 引數接受一個鍵,例如 MKT-42、卡 ID 或卡 URL。
1.接工作
kanera work --json # your assigned work across every board
kanera work --filters.q "checkout" --json # narrowed by card text
kanera priorities --json # your ranked Up next queue
kanera card MKT-42 --json # the card itself: description, checklists, fields
kanera card history MKT-42 --json # its activity and comments
kanera priorities 當你保持一個 接下來 佇列:代理可以拿頂部的卡,而不是為自己選擇。
2.開啟執行
在進行實質性工作之前，閱讀相關注釋和看板配置，檢查卡上沒有其他人，然後開啟執行。恢復您自己的實時執行以執行同一任務；在進行重疊工作之前報告另一個代理的實時執行：
kanera comments MKT-42 --json
kanera board <boardId> --json # lists and their actual IDs
kanera runs MKT-42 --json
RUN_ID=$(kanera run start MKT-42 "Fixing the checkout rounding bug" \
--externalUrl "https://github.com/acme/shop/pull/318" \
--quiet | jq -r .id)
卡片圖塊現在顯示一個實時晶片,說明代理正在工作,卡片詳細資訊顯示執行及其標題和進度說明。 --externalUrl 是可選的;給它一個可以開啟的 pull 請求、分支或 session 日誌。 參見 代理執行與操作歸屬 為了別人看到的東西。
在移動卡片之前,記錄卡片的原始列表 ID、名稱和工作流程含義。 使用 kanera card move 將它放在表明該板的工作流程中活動工作的可用列表中。 執行不會移動卡片。 從板的配置中解析列表,如果已經在那裡,則跳過移動; kanera help cards.move 請勿假設每個看板都使用代理工作流程模板。
3. 報告進度
每次更新也是心跳,而一個執行了15分鐘而沒有心跳的執行會被標記為 停滯，因此對於長時間任務，代理應至少每十分鐘更新一次。
kanera run update "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"
執行摘要是每次更新所替換的狀態行。 對於團隊應該保留的任何內容,請在卡片上註釋:
kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."
給予每個意圖的評論或執行建立一個新的 --idempotencyKey 如果沒有金鑰而丟失了響應,請在重試之前檢查卡片,以避免重複。
4. 標記攔截者
當代理需要決定、批准或它沒有的訪問許可權時,標記執行 blocked 說出它需要的東西:
kanera run update "$RUN_ID" --status blocked \
--summary "Need a decision: round half up or half even?"
kanera comment MKT-42 "Blocked: should order totals round half up or half even? Both are drafted in PR 318."
晶片變成琥珀色,卡片詳細資訊顯示 等待著你。將執行標記為阻止本身不會通知任何人，這就是評論很重要的原因：它到達了卡的觀察者和受讓人。選擇一個反映該委員會工作流程中阻礙因素的列表。當代理恢復時，它將執行設定回 --status running 並將卡片移回到活動列表。
如果另一張卡是必備條件,也要建立一個 卡依賴性: kanera card block API-42 WEB-18 表示 API-42 阻止 WEB-18。 被阻止的執行描述了代理的狀態;它不會建立此關係。 kanera work --filters.blockedOnly true 找到等待的牌,以及 kanera deps WEB-18 讀取其直接前提條件和傳遞上游/下游鏈。
5. 完成
在最終回覆之前，釋出持久結果評論，其中包含更改或發現的內容、驗證及其結果（包括失敗或跳過的檢查）、相關 PR/提交/工件連結以及剩餘工作或決策。僅標記實際完成的清單專案。然後結束執行並路由卡：
kanera comment MKT-42 "Rounding is now per order. Focused regression checks pass; full suite not run. PR 318 is ready for review; merge and deployment remain."
kanera run done "$RUN_ID" "Implementation ready for review in PR 318"
kanera card move MKT-42 <destinationListId> --anchor '{"side":"after","id":null}'
kanera card MKT-42 --json
執行的結束摘要變成 已完成 只能在 Activity 中完成一個行;它不會替換結果註釋、移動卡片或完成卡片。 成功執行可能只覆蓋卡片的一部分,只有在商定的工作流允許並滿足其條件時才能完成卡片。
在移動卡片之前，請重新讀取它及其板。考慮原始列表、當前可用的列表及其含義、已完成的內容以及剩餘的內容。選擇最能代表該卡在此板工作流程中的實際狀態的列表。返回原始列表可能是適當的，但不是自動的。不要單獨假設列表名稱或從列表順序或正在進行的設定中進行選擇。在結果評論中解釋選擇。
如果分配的工作無法完成,解釋剩下的內容並結束執行 --status failed 或 --status cancelled。保留 blocked 只在真正等待恢復時才執行;不要讓停止的工作繼續執行。 已結束的執行不能更改;如果工作稍後恢復,則開始新的執行。
從寫入結果和新讀取中驗證結果卡片列表、結果註釋和執行狀態。 考慮自動化和隊友的介入行動。 如果沒有明確的目標,則保持當前列表不變,儲存您可以儲存的執行/註釋更新,並僅詢問缺失的路由選擇。 如果寫入被拒絕,則報告限制和哪些跟蹤步驟仍未儲存;不要暗示成功。
作品歸屬於誰
登入的 CLI 如何決定代理的工作如何標記:
| 全權證書 | 評論和卡片更改 | 執行晶片標籤 |
|---|---|---|
瀏覽器登入 --agent (kanera auth login --agent "Claude Code") | 作為你， 透過 Claude 程式碼(計算機名稱上的 Kanera CLI) | Claude 程式碼(計算機名稱上的 Kanera CLI) |
瀏覽器登入無需 --agent | 作為你， 透過 Kanera CLI(計算機名稱) | Kanera CLI(計算機名稱) |
| 個人 API 金鑰 | 作為你，沒有 透過 徽章 | API客戶端 |
| 工作區或板 API 金鑰 | 正如鑰匙的名字 | 金鑰的名稱 |
瀏覽器登入是一次 OAuth 裝置連線，因此代理的工作承載著 透過 您的代理在您的通知中分別分組,並且與您在 Work Done 中的工作分開,與 MCP 相同。 Kanera 只能看到 CLI, 因此在您登入時,請指定代理的名稱。 --agent （或 KANERA_AGENT_NAME）。該名稱對於該登入是固定的；給每個代理自己的 概況 若多臺計算機共享一個計算機。 透過 MCP 代理自我命名;見 設定 Claude 或 設定 Codex. kanera mcp，CLI 的本地 MCP 伺服器，使用與 CLI 相同的儲存憑證和相同的屬性。
將其新增到您的專案說明中
現狀 kanera setup claude 以及 kanera setup codex 要使專案的接受策略明確,請在下面的指南中修改本節內容: CLAUDE.md 或 AGENTS.md:
## Kanera card work
Use connected Kanera MCP tools when available, otherwise the Kanera CLI.
When asked to carry out a card, keep it updated as part of the assignment:
- Read the card, relevant comments and board lists; record the original list ID/name/meaning and check for another live agent run.
- Start a run before substantive work and move to the board's active list.
- Keep progress current at milestones and at least every ten minutes.
- When blocked, update the run, comment what you need and move to the waiting list.
- Before the final reply, comment changes, checks/results, relevant links and remaining work.
- End the run appropriately. Re-read the card and board; consider the original list, available lists
and their meanings, completed work and remaining work. Choose the list that reflects the card's
actual state in this board's workflow, without assuming names or automatically restoring its
original list. Explain the choice in the comment. If unclear, leave the list unchanged and ask.
Complete the card only when the agreed workflow permits it and its criteria are met.
- Verify the saved comment, run status and card list; report any tracking writes that failed.
- Read-only or exploratory requests cause no tracking writes; explicit user limits win.
將其與寫入金鑰配對。 使用只讀金鑰,只保留讀取步驟。