资源管理

CLI 提供对 North Coder 核心资源的完整 CRUD 操作。这些命令通过 HTTP API 与后端通信，需要服务可达（参见服务发现）。

环境变量默认参数

需要 id 的资源命令在省略参数时，会按命令回退到对应环境变量（self-context）；显式参数永远优先：

命令	省略参数时回退到
`workspace list`	`$NORTH_CODER_PROJECT_ID`
`conversation list`	`$NORTH_CODER_WORKSPACE_ID`
`conversation get` / `history` / `status` / `siblings` / `tail`、`context`	`$NORTH_CODER_CONVERSATION_ID`

这些变量由 North Coder 注入到 Agent 运行的 shell（RFC-0078），所以 Agent 内调用 ncoder 通常无需自己反查 id。回退也缺位时，CLI 打印可执行的提示（--json 模式给出 code + hints 字段，便于脚本分支），而不是裸的 “missing argument”。

写类命令刻意不做回退：conversation create 的 workspace id 仍必须显式传入，避免把 mutation 落到环境变量隐含的 workspace 上。

project — 项目管理

project create

创建新项目。

ncoder project create NAME PATH

参数	说明
`NAME`	项目名称。
`PATH`	项目本地路径。

示例：

ncoder project create "My App" /Users/me/projects/my-app

workspace — 工作区管理

workspace list

列出项目下的所有工作区。

ncoder workspace list [PROJECT_ID]

PROJECT_ID 可省略：缺省时回退到 $NORTH_CODER_PROJECT_ID（参见环境变量默认参数）。输出表格包含 ID、分支、状态、创建时间。

workspace create

创建新工作区。

ncoder workspace create PROJECT_ID [OPTIONS]

选项	默认值	说明
`--branch`, `-b`	—	指定 Git 分支。
`--source-ref`	—	创建新分支时使用的 source ref，可以是 branch、tag 或 commit SHA。
`--commit`	—	`--source-ref` 的别名，便于从指定 commit 创建工作区。

示例：

ncoder workspace create proj_abc123 --branch feature/new-ui

# 从指定 commit 创建工作区分支
ncoder workspace create proj_abc123 --branch repro/old-state --commit 0123456789abcdef

CLI 只把 --source-ref / --commit 传给后端；commit 是否存在、source ref 如何解析，由后端 Git 逻辑处理。

workspace status

查看工作区状态。

ncoder workspace status WORKSPACE_ID

conversation — 会话管理

conversation list

列出工作区下的所有会话。

ncoder conversation list [WORKSPACE_ID]

WORKSPACE_ID 可省略：缺省时回退到 $NORTH_CODER_WORKSPACE_ID（参见环境变量默认参数）。输出表格包含 ID、标题、创建时间。

只想看“同一个 workspace 里的其它会话”时，用 conversation siblings 更直接——它排除当前会话本身，且不需要先反查 workspace。

conversation create

创建新会话。

ncoder conversation create WORKSPACE_ID [OPTIONS]

选项	默认值	说明
`--title`, `-t`	—	会话标题。

示例：

ncoder conversation create ws_abc --title "修复登录问题"

conversation get

查看会话元数据和持久化的 Agent 配置。

ncoder conversation get [CONVERSATION_ID]

CONVERSATION_ID 可省略：缺省时回退到 $NORTH_CODER_CONVERSATION_ID（参见环境变量默认参数）；以下 history / status / siblings / tail 同理。

人类可读模式下会显示 agent_config 中已经持久化的 Agent profile、model、reasoning effort、禁用工具、禁用 skill 和上下文 token 设置。这个命令保持 thin CLI：它只调用 GET /api/conversations/{id} 并渲染返回值，不会读取本地 settings，也不会推导全局默认或 builtin fallback 后的 effective profile/model。

如果需要脚本读取原始字段，使用 JSON 输出：

ncoder --json conversation get conv_abc | jq .agent_config

conversation history

查看会话历史消息。

ncoder conversation history [CONVERSATION_ID]

人类可读模式下显示每条消息的角色和内容（超过 200 字符截断）。JSON 模式下返回完整消息列表。只想快速了解“上一会话最近做了什么”时，用 conversation tail 拿“首条 user 消息 + 最近 N 条”，比拉全量历史更省。

conversation status

查看会话的轻量运行状态、正在执行的 invocation，以及最后一条 assistant 文本消息。

ncoder conversation status [CONVERSATION_ID]

这个命令适合脚本和 agent 轮询当前会话状态。需要完整消息列表时再使用 conversation history。

JSON 输出示例：

{
  "conversation_id": "conv_abc",
  "workspace_id": "ws_abc",
  "status": "running",
  "queue_depth": 1,
  "active_invocations": [
    {
      "invocation_id": "inv_123",
      "status": "running"
    }
  ],
  "latest_invocation": {
    "invocation_id": "inv_123",
    "status": "running"
  },
  "last_assistant_message": {
    "message_id": "msg_456",
    "content": "已经定位到失败用例..."
  }
}

conversation search

按标题和消息内容全文检索会话。

ncoder conversation search QUERY [OPTIONS]

选项	默认值	说明
`--limit`、`-n`	`25`	返回的最大匹配数。
`--conversation`	—	限定在某个会话内搜索。
`--workspace`	—	限定在某个 workspace 内搜索。
`--project`	—	限定在某个 project 内搜索。

示例：

ncoder conversation search "登录失败" --workspace ws_abc -n 10

conversation siblings

列出当前会话所在 workspace 下的其它会话（排除自身），按最近更新时间倒序。它是 context 的 siblings 投影，等价于 conversation list <本会话的 workspace> 但省去自己反查 workspace、并自动排除当前会话。

ncoder conversation siblings [CONVERSATION_ID]

CONVERSATION_ID 可省略，缺省回退到 $NORTH_CODER_CONVERSATION_ID。--json 输出的是 siblings 数组（[{id, title, agent_status, updated_at}]），等价于 ncoder --json context | jq .siblings：

ncoder --json conversation siblings | jq '.[].id'

conversation tail

只看会话的「首条 user 消息 + 最近 N 条」，覆盖“上一个会话最后做了什么”这一最常见的接力场景，无需拉取并解析全量历史。裁剪在客户端完成（服务端仍只提供完整 history）。

ncoder conversation tail [CONVERSATION_ID] [-n N]

选项	默认值	说明
`--limit`、`-n`	`20`	显示的最近消息条数；首条 user 消息始终置顶（与最近窗口重叠时不重复）。

# 上一个兄弟会话最近 30 条
ncoder --json conversation tail conv_sibling -n 30

context — 自身上下文（relay 场景）

一次调用拿到当前会话在 project / workspace 图中的位置，外加同 workspace 的兄弟会话——专为 Agent “接力另一个会话”的场景设计，把原先 project list → workspace list → conversation list 的多步反查压成一步。服务端在单次请求内 join conversation → workspace → project 并枚举 siblings，CLI 保持 thin。

ncoder context [CONVERSATION_ID]

CONVERSATION_ID 可省略，缺省回退到 $NORTH_CODER_CONVERSATION_ID（注入到 Agent shell，见环境变量默认参数）。

JSON 输出：

{
  "conversation_id": "conv_self",
  "title": "当前任务",
  "agent_status": "running",
  "workspace_id": "ws_abc",
  "workspace_name": "feat/x",
  "project_id": "proj_abc",
  "project_name": "Alpha",
  "branch": "feat/x",
  "worktree_path": "/path/to/worktree",
  "siblings": [
    { "id": "conv_sib", "title": "更早的工作", "agent_status": "awaiting_input", "updated_at": "2026-06-04T00:00:00Z" }
  ]
}

无 workspace 的会话（如 Home）返回 200，workspace_* / project_* / branch / worktree_path 为 null，siblings 为空数组；只有 id 真不存在才返回 404。

典型接力路径 ≤ 3 步：

# 1. 我是谁 + 有哪些兄弟会话
ncoder context
# 2. 看某个兄弟会话最近做了什么
ncoder conversation tail <sibling_id> -n 30
# 3. 需要时再拉全量
ncoder conversation history <sibling_id>

message — 消息与任务

message send

向会话发送消息，触发 Agent 执行。

ncoder message send CONVERSATION_ID CONTENT [OPTIONS]

选项	默认值	说明
`--profile`	—	Agent profile ID。
`--model`, `-m`	—	模型 ID。
`--permission-mode`	`default`	工具权限模式：`default` / `acceptEdits` / `bypassPermissions` / `plan`。详见下文 `permission` 一节。
`--wait`	`false`	等待任务完成。
`--poll-interval`	`1.0`	轮询间隔（秒）。
`--timeout`, `-t`	`0`（无限）	等待超时（秒）。

--wait 的行为与 run --wait 相同，参见等待机制。

示例：

# 发送消息但不等待
ncoder message send conv_abc "请帮我重构这个函数"

# 发送消息并等待完成
ncoder message send conv_abc "运行测试" --wait --timeout 60

不等待时，JSON 输出会返回 invocation_id，可以传给 message status、message result、message cancel、message promote。如果任务进入 requires_action：ask_user 提问用 message answer 回答；工具权限请求（permission_request）用下文的 permission 子命令审批。也可以用 conversation status 查询会话最新状态。

message status

查看任务（invocation）状态。

ncoder message status INVOCATION_ID

输出包含：ID、状态、创建时间、开始时间、完成时间。

任务状态值：

状态	含义
`queued`	排队中。
`running`	执行中。
`requires_action`	等待用户或外部动作：`ask_user` 提问用 `message answer` 回答；工具权限请求用 `permission` 子命令审批。
`completed`	已完成。
`failed`	执行失败。
`cancelled`	已取消。

message cancel

取消任务。message cancel 使用 invocation_id 调用服务端 control plane：

queued：从队列中移除并标记为 cancelled。
running：请求停止当前 Agent run。
requires_action：取消正在等待用户输入的那一轮。
终态任务：幂等返回当前状态，不重复取消。

ncoder message cancel INVOCATION_ID

如果任务已终止，命令会提示当前状态但不报错。

示例：

# 提交任务
RESULT=$(ncoder --json message send conv_abc "大规模重构")
INV_ID=$(echo "$RESULT" | jq -r .invocation_id)

# 稍后取消
ncoder message cancel "$INV_ID"

message result

获取某个 invocation 的结果内容。

ncoder message result INVOCATION_ID

服务端会根据当前状态返回对应结果：

状态	行为
`queued`	返回 `202`，表示还没有结果。
`running` / `requires_action`	返回 partial result。
`completed`	返回完整结果。
`failed` / `cancelled`	返回已有 partial result 和错误/取消信息。

JSON 模式下会直接输出 /api/invocations/{id}/result 的原始响应：

ncoder --json message result inv_123 | jq .status

message answer

回答 requires_action 状态任务中的 ask_user 提问。

ncoder message answer INVOCATION_ID [OPTIONS]

选项	默认值	说明
`--answer`, `-a`	—	直接传入答案；有多个问题时按顺序重复使用。
`--interactive`, `-i`	`false`	逐题交互回答；没有传 `--answer` 且 stdin 是 TTY 时会默认进入交互模式。
`--wait`	`false`	发送答案后继续等待新任务完成。
`--poll-interval`	`1.0`	轮询间隔（秒），配合 `--wait` 使用。
`--timeout`, `-t`	`0`（无限）	等待超时（秒），配合 `--wait` 使用。

message answer 会读取任务状态和结果内容，提取 Agent 发起的 ask_user 问题，然后把答案发送回同一个会话。只有处于 requires_action 状态的任务可以回答；如果提取到了问题列表，答案数量需要与问题数量一致。

示例：

# 交互式回答
ncoder message answer inv_123 -i

# 直接按问题顺序传入答案
ncoder message answer inv_123 -a "React" -a "Alice"

# 回答后继续等待 Agent 完成后续任务
ncoder message answer inv_123 -a "继续" --wait --timeout 300

message promote

将仍在队列中的 message 提升为下一轮优先执行。

ncoder message promote INVOCATION_ID

只有 queued 状态的 invocation 可以提升。已经 running、requires_action 或处于终态的 invocation 不会被提升，命令会返回服务端给出的原因。

permission — 工具权限审批

当 Agent 调用受权限控制的工具（如 run_shell_command、文件编辑）时，run 会暂停为 requires_action，且 required_action.type = "permission_request"。此时可以用 permission 子命令进行 headless 审批；所有决策完成后，run 会自动恢复执行。

ncoder permission list      INVOCATION_ID
ncoder permission approve   INVOCATION_ID TOOL_CALL_ID
ncoder permission allow-once INVOCATION_ID TOOL_CALL_ID
ncoder permission deny      INVOCATION_ID TOOL_CALL_ID

子命令	决策	说明
`list`	—	列出该 invocation 待审批的工具权限请求（读取 `GET /api/invocations/{id}` 的 `required_action.pending_requests`）。
`approve`	`allow`	允许，并把该 `permission_key` 记为长期 allow 规则。
`allow-once`	`allow_once`	仅本次允许，不写入长期规则。
`deny`	`deny`	拒绝；模型会收到 denied 的 tool result，可以解释或改用其他方案。

每个工具权限请求由 tool_call_id 唯一标识，可从 permission list 或 run --wait 的 pending_requests 中获取。

示例：

# 1. run 暂停在权限审批，拿到 invocation_id
ncoder --json run "安装依赖并构建" -p proj_abc --wait
# 2. 查看待审批项
ncoder permission list inv_123
# 3. 批准其中一个 tool_call，run 随后自动恢复
ncoder permission approve inv_123 tc_xyz

行为说明：

endpoint 只接受属于该 invocation requires_action 的 tool_call_id；不匹配返回 404。
幂等：对同一请求重复提交相同决策返回当前状态；提交不同决策时 V1 fail-closed 返回 409，避免多客户端覆盖已做出的安全决策。
当一个 invocation 的所有 pending 请求都已 resolve，服务端调用 runtime resume，invocation 从 requires_action 回到 running。

如果只是想跑一个不被权限打断的会话，用 run --permission-mode bypassPermissions（或 message send --permission-mode ...）从一开始就放行，而不必逐个审批。

schedule — 定时任务

管理会话级定时任务。任务绑定到某个会话，到点时把指定 prompt 作为普通用户消息入队执行。任务是进程内存对象，后端重启后清空。

schedule list

列出定时任务。

ncoder schedule list [OPTIONS]

参数	说明
`--conversation`、`-c`	只列出该会话的任务（别名 `--conversation-id`）。
`--all`、`-a`	包含已禁用的任务（默认只列出启用中的）。

输出表格包含 ID、会话、Cron、时区、是否启用、下次运行时间（UTC）。

schedule create

为会话创建定时任务。

ncoder schedule create CONVERSATION_ID --cron "<expr>" --prompt "<text>" [OPTIONS]

参数	说明
`CONVERSATION_ID`	目标会话 ID。
`--cron`	标准 5 字段 cron 表达式（别名 `--cron-expr`）；不接受 6 字段秒级 cron。
`--prompt`	到点时入队的 prompt 文本。
`--timezone`	IANA 时区，默认 `UTC`。
`--enabled` / `--disabled`	是否创建即启用，默认启用。

示例：

ncoder schedule create conv_abc \
  --cron "*/30 * * * *" \
  --prompt "拉取最新代码并总结改动" \
  --timezone "Asia/Shanghai"

非法 cron 或时区返回 422。

schedule toggle

启用或禁用一个任务。

ncoder schedule toggle TASK_ID --enabled
ncoder schedule toggle TASK_ID --disabled

必须且只能指定 --enabled 或 --disabled 之一。重新启用时，下次运行时间会从当前时间重新计算。

schedule delete

删除一个任务。

ncoder schedule delete TASK_ID

通用行为

错误处理

所有资源命令在以下情况退出码为 1：

服务发现失败（没有可用的 North Coder 后端）。
HTTP 连接失败。
服务端返回 4xx 或 5xx 错误。

JSON 输出

所有命令支持 --json 全局选项。JSON 模式下返回服务端原始响应，适合脚本处理：

# 获取所有项目 ID
ncoder --json project list | jq '.[].id'

# 获取工作区分支
ncoder --json workspace status ws_abc | jq .branch

本页内容