DeepSeek-Reasonix Agent 核心精简改造目标循环行为契约、指标基线测试与门禁全解析【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix本文档记录 DeepSeek-Reasonix 的 Agent 核心精简agent-core simplification改造精简后循环的行为契约、用于前后对比的指标以及每个契约项的测试位置。原文见 AGENT_CORE_SIMPLIFICATION.zh-CN.md英文版见 AGENT_CORE_SIMPLIFICATION.md。导读DeepSeek-Reasonix 是一款面向终端、围绕前缀缓存稳定性设计的 DeepSeek 原生 AI 编码 Agent。为了让长驻运行的 Agent 更可预测、更省 token、更利于缓存命中项目对核心循环实施了精简改造普通请求走单一 executor 请求链planner/reviewer/evaluator 等重流程改为显式启用compaction 默认保持单次摘要。本文将完整展开这次改造的目标循环、产品取舍、指标基线与契约测试套件并深入仓库源码internal/agent、internal/cli、cmd/e2ebench验证每个契约项的真实落点。读完本文你将掌握如何用reasonix run --metrics与 e2ebench 量化一次运行的成本结构如何读懂usage_by_source分解以及如何通过契约测试与门禁命令守住普通请求不隐式调用规划器、clean final 不追加续写的行为边界。目标循环精简后的行为契约改造后的核心循环是一个显式、无隐含分支的状态机文档以如下伪代码定义构造请求 → provider stream → clean final:结束 → tool call:执行并进入下一 step → request error:统一 retry → 未处理错误:明确失败这条循环的契约含义是构造请求每次 step 只构造一次请求请求一旦发出即冻结provider stream流式读取 provider 输出clean final收到干净、完整的最终文本即结束回合不再追加任何后续请求tool call检测到工具调用则执行工具然后进入下一 step新一轮请求request error请求层错误走统一的 retry 路径重试时原样重放冻结的请求含 thinking未处理错误无法恢复的错误必须明确失败而不是悄悄降级。在源码层面该循环由 internal/agent/run_loop.go 与 internal/agent/coordinator.go 等实现而行为边界由 internal/agent/agent_contract_test.go 的汇总契约套件逐条钉死详见下文契约测试一节。这套套件正是精简后循环的行为契约的权威可执行定义。产品取舍每个决策的取舍逻辑与配置落点精简改造共包含六项明确的产品取舍每一项都对应可验证的配置项或测试。1. 普通请求默认 executor-onlyplanner 显式启用普通请求默认只走 executor 一条模型请求链planner规划器不再隐式介入只有配置了planner_model才启用双模型协作。从 internal/config/config.go 的AgentConfig可以看到// AgentConfig configures the harness loop. PlannerModel is optional: when set // to another providers name it enables two-model collaboration, where the // planner handles low-frequency planning in its own session (kept separate so // each models prompt prefix stays cache-stable). type AgentConfig struct { // ... PlannerModel string toml:planner_model // ... }关键细节planner 运行在独立 session中目的正是让每个模型的 prompt 前缀保持缓存稳定cache-stable——这与项目围绕 prefix-cache 稳定性设计的定位一脉相承。对应契约测试包括TestCoordinatorOrdinaryRequestDoesNotCallPlanner、TestDecidePlannerRouteExplicitOnlyplanner_model指向不可用模型时被视为配置错误TestBuildFailsWhenPlannerModelIsUnresolvableplanner 失败则 fail-closed 不执行 executorTestCoordinatorFailsClosedWhenPlannerFailsplanner 未提交submit_plan的散文结果直接判失败TestCoordinatorPlanAndExecuteRequiresSubmittedPlan。2. 普通 Agent 默认关闭 synthetic continuation普通 Agent 不再自动追加继续类续写Goal、review、guardian、typed report 等显式流程保留各自的约束。测试TestContractCleanFinalAddsNoSyntheticContinuation验证即使模型文本承诺下一轮再处理一个直接 Run 也必须在首个 clean final 处结束session 中不得出现任何宿主生成的续写 user 消息TestStandardTodoContinuationDisabledByDefault则钉死普通 Agent 不追加 todo continuation相关实现见 internal/agent/standard_todo_continuation.go。3. compaction 默认单次摘要默认压缩只做单次摘要chunked/tree-reduce 等高级恢复仅限显式场景手动/compact与明确标记的 recovery workflow。契约测试TestPressureCompactionDoesNotCallChunkedFold验证压力场景下 compaction 不会进入多段chunked折叠。相关实现可参考 internal/agent/compact.go、internal/agent/compact_chunked_policy_test.go。4. 硬边界全部保留以下边界继续作为硬边界保留不因精简而放宽final readiness最终就绪检查工具安全工具权限/畸形参数门禁取消cancel预算task/token/cost 预算显式全文读取的有界暂停而普通的部分读取不冻结独立工作其证据生命周期详见 读取证据生命周期英文版 READ_EVIDENCE_LIFECYCLE.md。也就是说精简只砍隐式的模型调用开销不砍任何安全与可靠性保障。对应测试包括 final_readiness_test.go、cancel_test.go、run_budget_test.go、argument_validation_test.go 以及 gate 相关测试如 capability_gate_test.go、recovery_gate_test.go。5. 旧配置/旧状态保持一版读取兼容旧配置与旧 session 状态保留一版可读性读取兼容但新运行时不再执行旧的 fallback。从 internal/config/config.go 可以看到max_steps、planner_max_steps、temperature等字段被明确标注为 Deprecated compatibility fields旧 TOML 可读但加载时被归一化为零、渲染时被省略。换句话说读得懂旧的行为上只认新的。6. 缺失的 guardian/recovery 模型 fail-closedguardian_model与recovery_model缺失或不可解析时构建失败TestBuildFailsWhenGuardianModelIsUnresolvable、TestBuildFailsWhenRecoveryModelIsUnresolvable绝不静默降级。相关配置字段同样定义于 internal/config/config.goGuardianModel string toml:guardian_model GuardianTemperature float64 toml:guardian_temperature // RecoveryModel names the optional recovery reviewer. Empty leaves // rule-only recovery; it is not implied by guardian or the main model. RecoveryModel string toml:recovery_model指标基线如何量化精简前 vs 精简后精简改造复用现有 usage 与 e2ebench 埋点不新增专用 fallback telemetry保证前后对比口径一致。每个阶段前后对比使用两类工具。工具一reasonix run --metrics path单次运行输出机器可读的RunMetrics。CLI 入口见 cmd/reasonix/main.go指标结构体定义在 internal/cli/run_metrics.go。核心字段JSON 键名包括字段含义prompt_tokens/completion_tokens总输入/输出 tokencache_hit_tokens/cache_miss_tokens缓存命中/未命中 tokenprefix_change_reason_counts缓存前缀变化原因计数如compact_auto、snip、tools用于定位缓存重置归因于哪个操作steps模型调用数每次 stream 计一次含工具轮cost/currency总成本与币种混合币种运行时original_costs按 ISO 币种分别记账、绝不跨币种求和usage_by_source按来源executor/planner/subagent/compaction/...拆分的请求调用数、token 与成本retries重试次数由Retrying事件累加compactions压缩次数由CompactionStarted事件累加readiness_*final readiness 检查/放行/阻断/恢复等细分计数subagent_*子代理运行、嵌套、变更等委托计数tool_calls/tool_failures/tool_calls_by_name工具执行统计complete区分最终记录与运行中途快照进程被杀时只留下completefalse的 partial 快照其数值是下界duration_ms/outcome/arm运行时长、结局与实验分组实现上metricsSinkinternal/cli/run_metrics.go实现event.Sink接口每个Usage事件累加 token 与steps按e.UsageSource归桶空 source 记为 executorRetrying事件累加retries。值得注意的实现细节快照机制运行期间会以snapshotEvery节流写入path.partial侧车文件运行被杀也能留下可审计的中间账目最终记录写入path并删除 partial二者不会同时被误读、也不会被重复计数见writeMetricsinternal/cli/run_metrics.go来源归桶未知来源保留在独立 key 下而不丢弃保证用于对账的总数不会因未来新增来源而悄然缺失见recordSourceinternal/cli/run_metrics.goSteps 的语义Steps 统计所有计费模型调用不分来源因此运行总量可能超过 executor 的 max_steps 预算——usage_by_source分解正是让这个总数可解释而非吓人见 internal/cli/run_metrics.go 注释。工具二go run ./cmd/e2ebench -task task -json按任务输出请求数与 trajectory 摘要。e2ebench 位于 cmd/e2ebenchtrajectory 结构定义在 cmd/e2ebench/trajectory.go相关字段JSON 键名包括字段含义stream_retries流式重试次数reasoning_replaysreasoning 重放次数empty_final_retries空最终响应重试次数ttft_ms首个文本事件延迟span 开始 → 首个输出增量见 cmd/e2ebench/trajectory.goexecutor_requests/planner_requests按来源统计的请求数wall_ms墙钟时间cache hit/miss缓存命中情况指标对照表每个契约维度的度量来源指标来源每个普通 turn 的模型请求数usage_by_source[executor].Calls/ trajectoryExecutorRequestsplanner 请求数usage_by_source[planner].Calls/ trajectoryPlannerRequestsreviewer/evaluator/guardian 请求数usage_by_source[recovery_reviewer\|goal_evaluator]、guardian assessment usagesynthetic continuation 次数clean turn 的 executor 请求数超出 1 的部分trajectoryEmptyFinalRetriesstream retry 次数trajectoryStreamRetries/RunMetrics.Retriescompaction 请求数与 summary spansRunMetrics.Compactions、compaction telemetry 通知spans、reqs首个文本事件延迟trajectoryTTFTMs总 turn 延迟RunMetrics.DurationMs/ benchWallMstool 执行成功率bench 任务 solved 率 /SolvedThenBroken因协议错误终止次数trajectory retry-exhausted 结果对比场景与每阶段目标至少对比三类场景普通问答、普通代码修改、长上下文/工具密集context-pressure任务。每阶段目标普通请求是一条 executor 请求链无隐式 planner/reviewer/evaluator 请求clean final 后无额外 continuation默认 compaction 不进入多段 summary硬安全失败率不上升。契约测试汇总套件逐项解读新增的汇总套件位于 internal/agent/agent_contract_test.go。其文件头注释明确每个测试钉住精简循环承诺的一个行为其余契约项对应的套件在docs/AGENT_CORE_SIMPLIFICATION.md中列出。契约项与测试对照表契约项测试clean final 恰好一次模型请求TestContractCleanFinalMakesOneModelRequesttool call 执行后进入下一 stepTestContractToolCallAdvancesToNextStepthinking 在统一 retry 中保留冻结请求TestContractThinkingSurvivesUnifiedRetryretry 耗尽后不残留长期 fallback 状态TestContractNoLongLivedFallbackStateAfterRetryExhaustionclean final 不追加 synthetic continuationTestContractCleanFinalAddsNoSyntheticContinuationreasoning-only clean stop 直接完成TestRunAcceptsReasoningOnlyFinalAnswer完全零内容走统一EMPTY_RESPONSEretryTestRunRetriesZeroContentWithTheSameFrozenRequestretry 耗尽返回明确协议错误TestRunStopsAfterExhaustedZeroContentRetriesWithoutCommittingEmptyMessagesstrict provider 缺失 reasoning 只做一次冻结请求重试TestRunSilentlyRecoversMissingToolCallReasoning及loop_e2e_test.go/retry_e2e_test.go的 replay 套件#9776 修复incomplete-read 门incomplete_read_test.gofinal readinessfinal_readiness_test.go取消cancel_test.gotask/token/cost 预算run_budget_test.go工具权限/畸形参数argument_validation_test.go、gate 相关测试普通请求不调用 plannerTestCoordinatorOrdinaryRequestDoesNotCallPlanner、TestDecidePlannerRouteExplicitOnlyplanner 无submit_plan的散文失败TestCoordinatorPlanAndExecuteRequiresSubmittedPlanplanner 失败不跑 executorTestCoordinatorFailsClosedWhenPlannerFails不可用的planner_model是配置错误TestBuildFailsWhenPlannerModelIsUnresolvable普通 Agent 不追加 todo continuationTestStandardTodoContinuationDisabledByDefault普通 compaction 保持单次摘要TestPressureCompactionDoesNotCallChunkedFold缺失的 guardian/recovery 模型 fail-closedTestBuildFailsWhenGuardianModelIsUnresolvable、TestBuildFailsWhenRecoveryModelIsUnresolvable关键契约测试的源码级解读clean final 恰好一次模型请求agent_contract_test.go用 scripted provider 预置一个文本 chunk Done 的回合Run结束后断言 provider 收到的请求数必须等于 1且会话中最后一条 assistant 内容就是最终答案。它钉死了 executor-only 的快乐路径一个用户 turn 一个 provider 请求 零宿主后续动作。tool call 推进循环agent_contract_test.go第一回合返回工具调用echo第二回合返回最终文本断言 provider 调用数为 2工具轮 最终轮、session 中保留了工具结果、最终内容正确。它定义了执行工具并进入下一 step的循环形态。thinking 在统一 retry 中存活agent_contract_test.go第一次流式返回空触发EMPTY_RESPONSE统一重试第二次返回 reasoning 文本 Done。断言两次请求reflect.DeepEqual逐字相同冻结请求原样重放thinking 绝不被禁用或改写且恢复出的 reasoning 保留在已提交的 assistant turn 上。retry 耗尽无长期 fallback 状态agent_contract_test.go连续maxSamplingAttempts次空响应后Run必须报错且不得提交任何非空 assistant 内容紧接着的第二次Run必须恢复到正常的单请求循环请求数 1证明失败回合没有在 Agent 上安装任何持久的降级模式。clean final 不追加 synthetic continuationagent_contract_test.go模型文本为我下一轮再处理时Run 仍只发一个请求随后扫描会话确认StandardTodoContinuationPrefix、visible answer、executorHandoffMarker等续写标记一个都不存在。门禁每个阶段的强制检查每个改造阶段必须通过以下命令组合门禁覆盖 agent、control、config、boot、provider 各包的单元测试、竞态检测、静态检查与仓库规范性检查go test -count1 ./internal/agent/... ./internal/control/... ./internal/config/... ./internal/boot/... go test -race ./internal/agent/... ./internal/provider/... go vet ./... go run ./tools/repolint第一条关闭测试缓存-count1跑核心循环、控制、配置与启动链路的全量测试其中就包含 internal/agent/agent_contract_test.go 的契约套件第二条对 agent 与 provider 包做-race竞态检测确保精简循环冻结请求重放、retry 状态机、source 归桶等共享状态无数据竞争第三条go vet静态检查第四条go run ./tools/repolint执行仓库级规范性检查见 tools 目录下的 repolint 工具。结语精简的验收标准Agent 核心精简的最终验收标准可以浓缩为一句话普通请求是一条 executor 请求链——无隐式 planner/reviewer/evaluator 请求、clean final 后无额外 continuation、默认 compaction 不进入多段 summary、硬安全失败率不上升。这套标准既有可执行的契约测试internal/agent/agent_contract_test.go又有可量化的指标口径internal/cli/run_metrics.go 的RunMetrics与 cmd/e2ebench/trajectory.go 的 trajectory还有每个阶段强制执行的 门禁命令。对于希望把 Agent 循环做得更省、更稳、更可审计的读者这套契约 指标 门禁的组合本身就是一份可直接复用的工程范本。【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考