Skip to content

Copilot 生命周期、预算与项目指令 ​

每次工具调用都有稳定的 CallId、轮次、尝试次数/上限、运行时、工具名、读写级别、风险、审批模式、幂等性、并发模式、资源指纹、排队耗时、失败分类、是否允许重试、参数摘要、开始/结束时间、总耗时、超时、结果摘要和最终状态。状态包括 Running、AwaitingApproval、Completed、Failed、TimedOut、Denied、Cancelled 和 Interrupted。

多工具并发 ​

Harness 创建后会显式启用 FunctionInvokingChatClient.AllowConcurrentInvocation,因此模型在同一响应内发出的多个函数调用可以由 Agent Framework 并行调度。业务工具不会直接无约束并发,而是统一进入 CopilotToolExecutionGate:

  • 独立的 SharedRead 最多同时运行 4 个。
  • 相同资源指纹的读取互斥,避免重复访问同一状态或缓存。
  • Exclusive 调用会阻止新的读取,等待现有读取结束后全局独占;任何写工具都会被强制提升为 Exclusive,即使工具声明错误。
  • 等待闸门时取消会产生 Cancelled trace 和审计记录,但不会调用工具。
  • Agent 事件出口串行化,保证并行工具不会并发修改聊天状态。

框架的并行开关及其默认串行语义见 FunctionInvokingChatClient.AllowConcurrentInvocation。

上下文压缩与请求预算 ​

ColorVision 使用独立于模型 Profile 的 Agent 上下文窗口,默认 1,048,576 Token;当最大输出为默认 8,192 Token 时,单次输入预算为 1,040,384 Token。ContextWindowCompactionStrategy 在每次模型调用前执行框架原生两阶段策略:

  1. 达到输入预算的 50% 后,先把旧工具调用组折叠成简短结果,保留工具名称和结论。
  2. 达到输入预算的 80% 后,再删除最旧的非系统消息组,同时保留最近对话。

1M 是 ColorVision 新 Agent 配置的统一默认值,不从模型 Profile 推导;用户可以在独立 Agent 设置页收紧它,单次请求也可以覆盖。框架会从 MaxContextWindowTokens - MaxOutputTokens 计算输入预算;具体策略见 ContextWindowCompactionStrategy。

CopilotAgentRunBudget 统一管理一次 Agent 运行的上下文窗口、累计请求 Token、业务工具调用、Agent pass 和总时长。这些参数保存在独立的 CopilotConfig.AgentDefaults;Profile 只保留厂商、协议、端点、模型和生成参数。有效值按“单次请求覆盖 > 全局 Agent 默认值 > 框架安全默认值”解析。默认值是 1,048,576 Token 上下文窗口、1,048,576 累计请求 Token、128 次业务工具调用、32 个 pass 和 7,200 秒;可配置硬上限分别是 1,048,576、1,048,576、512、128 和 86,400 秒,避免误循环变成真正无界运行。业务工具硬上限由 Bridge 独立执行,Harness 的 todo、mode、approval 等框架函数和最后一次自然语言总结使用单独的有界迭代余量,因此用完最后一次业务工具后仍可返回结论;只有继续越界调用工具时才记录 ToolBudgetExhausted。设置窗口把这些值放在独立 Agent 页,集成调用方仍可通过 CopilotAgentRunBudgetOverride 只收紧或覆盖当前请求。

Harness 正常结束但没有产生任何 TextContent 时,Runtime 不再把空 Todo 账本直接判为完成。它会通过同一 Token 与传输重试中间件发起一次非流式最终总结,ChatOptions.Tools 固定为空,并把有界工具观察与当前任务账本作为数据交给模型;因此这个阶段不能重放业务或 Framework 工具。总结仍为空或失败时会发出固定用户提示、记录 IncompleteOutput 与 provider_empty_output blocker,保存 checkpoint,并且绝不标记 Completed。

本轮自动收尾请求还会在原请求之后,按交付顺序加入已确认进入 Provider 的有界 steering 补充指令,保留用户对语言、格式或任务约束的最新修正;这些指令不恢复任何工具权限。尚未交付的排队输入继续走 SteeringRecovery,不能因进入收尾阶段就标为已消费或加入最终回答请求。

CopilotAgentRecoveryMode.Finalize 为这种状态以及“Provider 在任务已完成后断流”的状态提供独立恢复协议。Runtime 在验证 profile、checkpoint 和最后一次 RunStopped 后直接进入 no-tools Provider 调用,不发现外部 MCP、不创建 Harness、不恢复 Todo、不打开审批;不匹配的 Finalize 请求会在工具发现之前拒绝,不能降级成普通 Agent 执行。再次空输出或超时时会刷新原 session 的 journal 与对话记忆并继续保留 checkpoint;成功后旧 session checkpoint 会退役,因为旁路生成的最终回答并不存在于旧 Framework session 中,后续轮次应从包含新答案的可见历史创建新 session。

只更新 journal 不会使旧执行会话重新变得可恢复。CopilotAgentSessionCheckpoint.SessionResumeRestriction 将未知工具结果或未闭合的 Provider 工具调用绑定到保留的 SerializedSessionJson;CopyWithOutcome 及其 journal 复制入口在替换 journal 前固化该限制,JSON 存储、快照、等价判断和 journal 裁剪继续保留它。非法限制值拒绝恢复。连续失败的 Finalize 不能靠新增无工具 run 清除限制;真正重新规划并创建新 Session 时不继承旧标记,也不会因历史 journal 中仍有未知结果而永久禁止恢复。旧版本缺少会话关联限制时,需要重新规划并核对外部结果。

CopilotTokenBudgetChatClient 基于官方 DelegatingChatClient 中间件包装真实模型客户端,累计同一 Agent 请求内所有供应商调用的 usage。每轮工具循环都会重读全部历史,缓存读取的费用约为新输入的十分之一,全额计入会让长任务因几乎没有计费的 Token 提前结束,因此判断预算耗尽时把供应商报告的缓存读取按 10% 计入(BudgetChargeTokens),调用前的估算也沿用上一次的缓存读取量;ConsumedTokens 和 Reported* 仍是原始账单值,可能超过预算值而未耗尽。子 Agent 共享池仍按原始值扣减。当已观测用量达到有效请求预算时,中间件在下一次供应商调用前抛出受控的 CopilotAgentTokenBudgetExceededException,由 Runtime 转成确定性的结束提示,不会再次调用模型或重放工具。供应商不返回 usage 时使用字符数近似,并在诊断中标记 includes estimates。这个预算是跨调用循环闸门;单个供应商响应可能使最终统计略微超过阈值。

同一次流式响应的 usage 更新通过 CopilotTokenUsage.MergeProgress 合并,各字段保留已观测最大值,总量还须覆盖合并后的输入与输出之和;后续片段省略或降低 total 不会让用量倒退、重新开放已耗尽的预算。不同供应商调用之间仍使用 Add 累加。

非流式响应通过 ExtractResponseUsage 读取 ChatResponse.Usage,并兼容消息内的 UsageContent;同一响应的两种表示单调合并,不能重复计数。预算中间件、最终总结和 Finalize 使用同一读取逻辑,不把已经返回的正式用量降为字符估算;输入、输出和缓存用量仍按不同调用累加。

总时长由与调用方取消令牌链接的运行级计时器约束。超时或业务工具越界都会返回结构化 BudgetExhausted 结果,并在可能时先完成任务账本和 Session 检查点;用户主动暂停或取消的语义优先于同时发生的超时。最终 Token、供应商调用、工具调用、pass 上限、已用时长、是否使用估算以及具体预算耗尽类型都会作为 RuntimeDiagnostic 和 CopilotAgentBudgetSnapshot 写入执行记录。

无工具最终总结仍属于同一次运行,也使用同一取消和总时长结算路径。总结被 RunControl 暂停/取消或总时长超时打断时,不把已有工具记录、用量和预算重置为空;继续完成账本与检查点收尾,并将最终回答标为未完成。否则预算已发布后的空结果会违反 Turn 生命周期的单调性校验,把可解释的停止错误转成执行故障。未提供 RunControl 的集成调用仅取消 caller token 时,仍按原契约向调用方抛出 OperationCanceledException,不伪装为总时长耗尽。

最终账本和 Session 检查点收尾期间仍可接收暂停、取消或总时长耗尽;收尾前后重新识别来源,受控中断保留本轮已发生的工具、用量和预算,并在有限收尾期限内使用可用检查点。最后一个异步等待结束后才统一确定停止原因与 blocker、封存 journal 并发布完成事件;取消丢弃可执行 Session,暂停保留检查点及其原有恢复限制。只取消 caller token 的集成调用在封存前仍向上传播取消。封存后到达的取消不回写已完成终态。

最终 Session 序列化的异步等待被受控中断时,Runtime 回退到已发布的最近增量检查点,不重新调用 Provider、工具或最终序列化。回退副本保留原始 Session、兼容性指纹和 SessionResumeRestriction,仅封存本轮终态 journal;未知工具结果不能因 journal 更新而变成可恢复会话。

原生任务账本与 plan/execute ​

Harness 的 TodoProvider 和 AgentModeProvider 作为标准运行时能力启用:

  • 模型通过框架原生 todos_add、todos_complete、todos_remove 和查询工具维护任务;任务保存在 AgentSessionStateBag,随会话检查点一起持久化。
  • 新会话默认进入 execute;模型在确实需要用户做关键选择时可切换到 plan。模式同样属于 Session 状态。
  • TodoCompletionLoopEvaluator 只在 execute 模式驱动后续 Agent pass。只要还有未完成任务,Harness 会把剩余清单作为反馈再次调用 Agent;pass 数、工具调用、请求 Token 和总时长都使用当前请求解析后的统一运行预算。
  • 每轮结束都会生成结构化 CopilotAgentTaskLedgerSnapshot,并把完成数、模式和最多三个未完成标题写入 RuntimeDiagnostic。聊天会话因此保留可检查的任务恢复记录,同时真实状态仍以 Framework Session 为唯一数据源。
  • 从检查点恢复时,会在执行记录中明确标注恢复了多少任务。未完成只读任务可继续;持久任务只代表上下文和计划,不代表执行授权。
  • Todo 状态更新本身由 Framework 对同一 Session 串行化,避免并发函数调用产生重复 ID 或丢失更新。

这里直接使用 Framework 的任务提供器与完成循环,而不是实现自定义 planner。官方 Harness 说明将持久 Todo、plan/execute 模式、逐次模型调用历史和可选完成循环列为完整 Agent 脚手架的组成部分,参见 Agent Harnesses 与 TodoCompletionLoopEvaluator。

项目指令链 ​

非 Chat 模式发现 Codex home 中首个非空的 AGENTS.override.md 或 AGENTS.md,以及受信项目根到目标文件目录的项目指令。文件先按严格 UTF-8(或 BOM)解码,失败再按 GB18030。受信项目根优先取当前解决方案目录,未打开解决方案时才回退到活动文档目录。每个项目目录选择一个共享入口,依次尝试 AGENTS.override.md、AGENTS.md、已配置的 fallback 文件、CLAUDE.md 和 .claude/CLAUDE.md。项目根的 .claude/rules/**/*.md 按规则相对路径排序,接在根共享指令之后。各目录的非空 CLAUDE.local.md 作为私有叠加层,适合本机测试数据或工作流偏好,仓库应把它加入 .gitignore。

数量或字节预算不足时,个人指令优先保留,项目指令优先保留活动文档链中更具体的作用域。同一作用域先保留 local,再保留共享指令及匹配路径的规则,最后保留无条件规则。注入顺序仍是个人在前,项目从外到内,每个作用域按共享入口、适用规则、local 排列。

/init 创建项目指令 ​

CopilotProjectInitialization 将 /init 解释为有界的真实 Agent 请求,不是直接写模板文件。它先规范化现有工作区根,并调用共享指令发现逻辑检查 AGENTS.override.md、AGENTS.md、配置的 fallback 文件及 CLAUDE.md / .claude/CLAUDE.md;已有同名文件系统项(包括空文件)阻止初始化,避免覆盖或遮蔽旧指令。

请求要求先读项目结构和必要文档,只以一次 PreviewWorkspacePatchEnvelope 提议根级 AGENTS.md 的单一 add,再将原 change set 交给 ApplyWorkspacePatchEnvelope。应用仍服从当前原生审批策略;请求来源声明或指令正文不提供授权。应用前还需复查共享指令候选和目标不存在,不能将竞态降格为覆盖。内容只保留证据支持的长期项目事实、架构边界、PowerShell 构建/测试入口与完成标准,不写凭据、个人绝对路径、生成清单或临时分支状态。本初始化任务不执行构建/测试;完成后仍需用户审阅生成的规则。

搜索根不等于受信项目根 ​

显式本地文件和文件附件仍可增加只读搜索根,让 Agent 在用户要求时读取对应文件;它们不会自动成为受信项目根,因此相邻的 AGENTS.md、CLAUDE.md、.claude/rules 和 .agents/skills 不会进入模型上下文。这个分离与 Codex 只从受信项目层加载项目配置的边界,以及 Claude Code“附加目录授予文件访问、默认不加载 CLAUDE.md/rules”的行为一致。/permissions 会分别显示搜索根和受信项目根,便于确认来源。

路径规则与指令预算 ​

rules 不含 paths frontmatter 时无条件适用于该受信项目根;存在 paths 时,只有活动文档、用户文本中的显式本地文件或文件附件在请求开始前已知、位于受信项目根内,且其根内相对路径匹配至少一个 glob 时才加载。支持 *、?、** 和 {ts,tsx} 一类花括号展开;单个规则最多 16 个模式,每个模式最多 256 个字符。绝对路径、父目录段、否定模式、控制字符、空段、重复或畸形 paths 会让该规则失败关闭,而不是意外变成全局规则。匹配使用 Windows 不区分大小写语义,frontmatter 只供宿主筛选,进入模型前会移除。ColorVision 当前在构造固定请求上下文时完成匹配,不会因为本轮工具稍后发现了一个此前未知文件而热注入新规则;后续新请求会按当时目标重新发现。

单份原始文件和处理后的单份正文各以 32,768 个字符为上限。发现阶段最多选 16 份文档,合计按 UTF-8 计量,默认预算为 32 KiB,可配置为 0 至 64 KiB。rules 遍历最多检查 64 个目录、每目录前 256 个条目和 64 份 Markdown,frontmatter 最多读取 8,192 个字符,规则目录及文件路径上的重解析点会被跳过。注入阶段再按正文合计 65,536 字符和作用域 JSONL 整块 81,920 字符限制输出。被截短的文档标记 IsTruncated,序列化保留完整 JSON 行。

为减少只面向维护者的上下文噪声,文件中代码围栏之外的 <!-- HTML comments --> 会在脱敏和截断前剥离;围栏内的示例原样保留。共享入口、rules 和 local 叠加层都不会展开 Claude Code 的 @path 导入,因此不会因为仓库指令静默扩大文件读取范围。CLAUDE.local.md 与 rules 使用相同的正文预算、脱敏和权限边界;“个人”或“路径匹配”都不提升可信等级。项目指令始终作为 workspace-scoped user-role 数据注入,只影响其目录范围内的行为,不能授权写入、审批、外部副作用或越界访问。这结合了 Codex AGENTS.md 的根到当前目录、override 与回退语义、Codex 项目层信任 的配置边界,以及 Claude Code memory 和 Claude Code additional directories 中项目指令与额外文件访问分离的语义。

Agent Skills ​

技能通过独立的发现、选择与按需加载链进入运行时。项目/用户/内置路径、同名优先级、/skills、开关、元数据预算、使用统计与 MCP 依赖统一见 Copilot 技能。技能内容不授予文件、Shell、SQL 或流程操作权限。

基于 MIT License 发布。