在终端中使用编程代理

终端编码代理（例如 Claude Code 或 Codex）可以将 Kanera 卡从提取到完成：读取卡、宣布卡正在工作、报告进度、在需要人员时进行标记以及将卡标记为完成。本指南将循环设置为 Kanera CLI，适用于任何可以运行 shell 命令的代理。

首先连接的 MCP 工具 如果您的代理可以连接到 Kanera 的托管 MCP 服务器，请改用它。粘贴设置提示 将 Kanera 连接到您的 AI 代理 代理通过OAuth获得相同的工具,并且其工作被标记为 通过 <代理人>。 CLI 是具有 shell 但没有 MCP 连接的代理的路由。无论哪种方式，下面的循环都是相同的；只是交通发生了变化。 :::

安装并登录

在运行代理的计算机上安装 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.

将其与写入密钥配对。 使用只读密钥,只保留读取步骤。

相关页面

• Kanera CLI
• 代理运行与操作归属
• 代理安全
• 将 Kanera 连接到您的 AI 代理