常见集成场景

集成方式主要由三个问题决定：任务开始后是否需要继续输入、工具操作是否需要外部决策、会话是否需要跨进程或机器恢复。本页按常见产品形态列出 TypeScript 和 Python 的推荐入口、能力组合与运行边界。

快速选择

任务
 |
 +-- 一次输入即可完成 --------> query() 单次任务
 +-- 需要追问或动态补充 ------> TypeScript 异步消息流
 |                              Python QoderSDKClient
 +-- 操作需要外部审批 --------> canUseTool / can_use_tool + Hooks
 +-- 会话需要跨实例恢复 ------> sessionStore / session_store + resume
 `-- 需要访问业务系统 --------> MCP 工具、Skills 或自定义 Agent

产品形态	推荐入口	重点能力
批处理脚本、CI 任务	`query()` + 字符串任务	`cwd`、工具范围、非交互权限、Result
交互式开发工具	TypeScript 异步消息流；Python `QoderSDKClient`	流式输出、追加输入、中断、会话 ID
后端 API 或任务服务	每个任务创建或恢复会话	服务认证、并发控制、外置会话存储
带人工审批的自动化	`canUseTool` / `can_use_tool`	allow/deny 规则、审批 UI、Hooks
领域工作流	MCP、Skills、Agents、Plugins	业务工具、领域指令、可复用能力包

批处理脚本和 CI

代码检查、测试补全、迁移报告、文档生成等任务通常只需要一个明确输入和一个最终结果。使用字符串调用 query()，任务完成后结束会话。

CI Job 或定时任务
        |
        v
  query("完成指定任务")
        |
        +-- 结构化消息和工具活动
        `-- Result：成功、失败或中断

推荐配置：

使用 PAT 或 Service Account 等适合自动化环境的认证方式，不依赖开发机登录态。
显式设置 cwd，让文件和命令操作落在本次任务的工作区。
报告类任务只开放 Read、Glob、Grep 等只读工具；需要修改时再加入 Edit、Write 或 Bash。
后台任务无法弹出确认界面。可用明确的 allow/deny 规则配合 dontAsk，让未预授权操作直接拒绝；acceptEdits 适合允许修改受控工作区的任务。
消费消息流直到 Result，并根据 subtype、errors 和可用的 error_code 判断任务结果。

跳过全部权限检查只适合已经由容器、临时工作区或同等级机制完成隔离的环境。权限配置见权限控制，结果处理见错误处理与错误码。

交互式开发工具

聊天式代码助手、IDE 功能和内部研发门户需要在任务开始后继续接收输入，并把 Agent 文本、工具活动和状态实时显示出来。

TypeScript：向 query() 传入 AsyncIterable<SDKUserMessage>。
Python：使用 QoderSDKClient 建立会话，通过 query() 发送消息，通过 receive_response() 接收每一轮输出。
使用流式事件驱动界面更新，使用 interrupt() 停止当前轮次。
每个产品会话保存对应的 session_id；需要延续历史时使用 resume，需要保留原分支时使用 fork。
运行中新增的输入应明确处理时机：立即改变方向、下一时机处理或当前轮次结束后处理。

聊天或 IDE
   |  输入、追问、中断
   v
长会话 -------------> 流式消息 -------------> 界面
   |
   `----------------> session_id

输入方式见输入模式，界面消息处理见流式输出，恢复和分叉见会话控制。

后端 API 和任务服务

后端服务可以把一次 HTTP 请求、队列消息或定时任务转换为 Agent 会话。每个活动会话由本地 qodercli 进程承载，因此并发上限需要同时考虑进程数、模型请求、文件系统和命令执行资源。

HTTP API / Queue
       |
       v
应用服务 -----> Agent SDK -----> qodercli
   |                                |
   +-- 会话索引或外置存储           +-- 工作区与命令
   `-- 日志、超时和取消             `-- Qoder 模型服务

服务化集成通常需要以下约束：

运行环境必须允许启动 qodercli 子进程，并提供任务所需的工作目录、命令和依赖。
自动化服务使用显式凭据；本机登录态只适合开发工作站。
请求与 session_id 建立稳定映射。单实例可使用本地会话；多实例、容器或临时磁盘环境使用 sessionStore / session_store 镜像会话。
跨实例恢复时，各实例应使用一致的项目目录语义和可访问的项目内容。
流式接口可以把 Agent 事件直接转发给调用方；异步任务可以只保存进度和最终 Result。
超时应触发 interrupt() 或关闭会话，并保留足够的错误与进程诊断信息。

认证方式见SDK 认证，多实例恢复见外置会话存储。

带人工审批的工作流

代码修改、命令执行、发布操作或业务系统写入可能需要产品 UI、审批系统或策略服务作出决定。权限控制可以分为静态边界和运行时决策：

tools 决定本次会话可见的工具。
allowedTools / allowed_tools 和 disallowedTools / disallowed_tools 定义预授权与禁止项。
canUseTool / can_use_tool 接收未预授权的工具请求，并返回 allow 或 deny。
Hooks 在工具执行前后进行校验、审计或告警。

Agent 提出工具调用
        |
        v
静态规则 ----拒绝----> 返回拒绝结果
        |
       待审批
        v
产品 UI / 策略服务
   | allow         | deny
   v               v
执行工具        返回拒绝结果

审批请求应展示工具名、关键参数、影响范围和会话上下文。无人值守任务应设置明确的拒绝策略和超时，避免会话无限等待。审批与 Hook 不替代工作区隔离和凭据最小权限。详细配置见权限控制和 Hooks。

接入业务工具和领域能力

Agent 可以通过扩展能力访问业务数据、调用内部系统，或复用领域工作方法。能力类型应按目标选择：

目标	推荐能力	适合内容
调用宿主进程中的函数	进程内 MCP 工具	数据查询、工单操作、内部 API 封装
连接已有工具服务	外部 MCP Server	已独立部署的标准化工具集合
提供可复用操作说明	Skills	团队规范、排障流程、交付模板
定义专门角色	Agents	代码审查、测试分析、迁移规划等职责
分发一组扩展	Plugins	Skills、Agents、MCP 和命令的组合

工具输入应使用明确的结构化字段，返回值只包含完成任务所需的数据。业务凭据应保留在工具实现或宿主服务中，不应拼接进任务文本。写操作继续经过权限规则或审批回调。扩展方式见工具、MCP、Agents、Skills和Plugins。

上线检查

运行环境：qodercli 可启动，cwd 指向正确且隔离的工作区，所需命令和依赖可用。
认证：凭据由环境变量或密钥服务注入，日志和任务文本不包含密钥。
权限：工具集合遵循最小权限；后台任务不会依赖无法完成的交互确认。
生命周期：消息流消费到 Result；超时、中断、进程退出和应用关闭都有处理路径。
会话：需要恢复时保存 session_id；多实例环境配置共享的会话存储。
并发：按活动 qodercli 进程、工作区、模型请求和工具资源共同规划容量。
可观测性：记录 Result、工具活动和必要诊断，同时过滤凭据和敏感业务数据。
版本：使用 SDK 随包运行时；指定外部 qodercli 路径时保持版本兼容。

​快速选择

​批处理脚本和 CI

​交互式开发工具

​后端 API 和任务服务

​带人工审批的工作流

​接入业务工具和领域能力

​上线检查

​相关文档