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 Core Simplification 设计文档中文版见 AGENT_CORE_SIMPLIFICATION.zh-CN.md完整梳理 Agent 核心循环精简改造的行为契约、产品取舍、前后对比指标与契约测试矩阵。你将掌握精简后的目标循环每个阶段的判定规则、reasonix run --metrics与e2ebench的指标采集方式、每项契约对应的测试文件位置以及每个阶段必须通过的 4 条质量门禁命令——这套方法可以直接复用于任何削减隐式调用、压缩延迟、稳定 prefix-cache的 Agent 循环改造项目。背景为什么要做 Agent 核心精简DeepSeek-Reasonix 是一个面向终端的 DeepSeek-native AI coding agent项目描述强调其工程核心是prefix-cache 稳定性leave it running常驻运行。prefix-cache 的命中率与请求的确定性直接相关请求越杂、隐式追加的调用越多cache 前缀越容易被破坏。因此本次 Agent 核心精简的总体目标是把普通请求收敛为一条尽可能短的 executor 请求链去掉隐式的 planner / reviewer / evaluator 调用、关闭默认的 synthetic continuation、让默认 compaction 保持单次摘要从而让每一次普通 turn 的行为可预测、可度量、可测试。该文档本身即是对这次改造的工程化约定行为契约Target loop、产品决策Product decisions、度量方案Metrics baseline、契约测试Contract tests与门禁Gates五部分本文依次展开并结合仓库源码逐项印证。目标循环精简后的五阶段行为契约改造后Agent 循环收敛为如下单一形态原文照录build request - provider stream - clean final: done - tool call: execute, next step - request error: unified retry - unhandled error: explicit failure每个阶段的语义可以拆解为构造请求build request根据当前会话与工具上下文构造单次 provider 请求。请求一旦发出即被冻结frozen后续重试原样回放该请求。provider stream流式接收模型输出包括文本块ChunkText、推理块ChunkReasoning与结束标记ChunkDone等。clean final结束收到干净的最终回答即结束本轮不追加任何 continuation。tool call执行并进入下一步模型请求调用工具执行工具后带着工具结果进入下一 step继续循环。request error统一 retry协议层错误如零内容响应EMPTY_RESPONSE走统一的、基于同一冻结请求的重试路径。未处理错误明确失败重试耗尽或其他无法归类的错误必须显式失败绝不静默降级。从源码结构看这套契约被完整固化在 internal/agent/agent_contract_test.go 中。例如TestContractCleanFinalMakesOneModelRequestL21-L36用scriptedProvider注入一段文本 Done的流断言整个Run只发出1 次provider 请求TestContractToolCallAdvancesToNextStepL40-L59注入一个 tool call turn 一个文本 turn断言调用次数为2工具轮 最终轮且工具结果写入了会话。这两个测试精确钉死了clean final 恰好一次请求、tool call 推进循环两条核心契约。产品取舍五个关键决策精简不是一刀切而是按流程语义做了显式区分。原文的五个产品决策如下普通请求默认 executor-onlyplanner 改为显式启用只有配置了planner_model才可能进入规划流程。普通 Agent 默认关闭 synthetic continuation模型说下一轮再处理不再触发宿主自动追加提示词而 Goal、review、guardian、typed report 等显式流程保留各自的约束。compaction 默认单次摘要chunked / tree-reduce 这类高级恢复仅限显式场景即手动/compact与明确标记的 recovery workflow。final readiness、工具安全、取消、预算和显式全文读取的有界暂停继续作为硬边界普通部分读取不冻结独立工作详见 读取证据生命周期英文版 READ_EVIDENCE_LIFECYCLE.md。旧配置与旧会话状态保留一版读取兼容但新运行时不再执行旧 fallback——即可读旧数据不跑旧逻辑。这几条决策在测试矩阵中都有对应钉子。例如TestContractCleanFinalAddsNoSyntheticContinuationL122-L139让模型输出 I will handle it next round.断言 provider 请求数仍为 1且会话中不存在StandardTodoContinuationPrefix、executorHandoffMarker等任何合成 continuation 提示词——模型口头承诺不会买来额外的请求。TestStandardTodoContinuationDisabledByDefault则从 todo 角度验证同一件事。指标基线如何量化精简前后改造前后的对比复用现有 usage 与 e2ebench 埋点不新增专用 fallback telemetry——这本身就是一条工程纪律可观测性靠既有管线不给精简路径开后门。两个采集命令reasonix run --metrics path单次运行输出机器可读的RunMetrics包含 token/成本总量、usage_by_sourceexecutor / planner / subagent / compaction 等各来源的请求调用数、retries、compactions、steps。go run ./cmd/e2ebench -task task -json按任务统计请求数、usage_by_source、trajectory 摘要stream retry、reasoning replay、empty-final retry、TTFT、按来源的请求数、墙钟时间、cache 命中/未命中。其中RunMetrics结构在 internal/cli/run_metrics.go 中有源码级定义L32-L80除 token/成本字段外还包含Steps每次流式请求计一步含工具轮、Compactions、ReadinessChecks/Allowed/Blocks/Recoveries等 readiness 计数器、SubagentRuns委托计数以及PrefixChangeReasonCounts——它逐项统计每次 cache 前缀变更的原因如compact_auto、snip、tools专门用来回答cache 命中率掉了到底是哪个操作干的。文档中的usage_by_source对应SourceUsage结构L19-L30每个来源记录Calls、PromptTokens、CompletionTokens、Cost与OriginalCosts混合币种时按 ISO 币种分别记账、绝不跨币种求和。结构体注释还指出Steps 统计所有计费模型调用因此总步数可以超过 executor 的 max_steps 预算——这个明细正是用来解释总步数为什么比主循环多的。指标对照表指标来源每个普通 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 结果必测场景与阶段目标至少对比三类场景普通问答normal QA、普通代码修改normal code edit、长上下文/工具密集context-pressure任务。每阶段的达成目标原文定义为普通请求一条 executor 请求链无隐式 planner/reviewer/evaluator 请求clean final 无额外 continuation默认 compaction 不进入多段 summary硬安全失败率不上升。这五条就是改造的完成定义与前面的产品决策一一对应且每条都可被表格中的指标量化。契约测试行为钉子的完整矩阵新增的汇总套件为 internal/agent/agent_contract_test.go其余契约项散落在各专项测试中。完整对照如下原文全表契约项测试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从源码看几个关键测试的断言方式冻结请求重试TestContractThinkingSurvivesUnifiedRetryL64-L86先让 provider 返回只有 Done、零内容触发重试第二次流返回reasoning 答案 Done。测试用reflect.DeepEqual断言两次请求逐字节一致重试必须回放冻结请求不得改 shape、不得关闭 thinking并且最终提交的 assistant turn 必须保留ReasoningContent——thinking 在统一 retry 中存活由此成立。重试耗尽不残留 fallbackTestContractNoLongLivedFallbackStateAfterRetryExhaustionL91-L117构造maxSamplingAttempts次全空响应令首次Run失败随后再发起一次普通Run断言其只发出 1 次请求——证明失败后没有安装任何长期降级模式下一次 turn 仍是正常的单请求循环。测试还顺带验证了失败轮不会把空 assistant 消息提交进会话。fail-closed 配置TestBuildFailsWhenPlannerModelIsUnresolvable等测试表明planner_model、guardian 模型、recovery 模型一旦配置为不可解析构建阶段就直接报配置错误——从配置侧看planner_model定义于 internal/config/config.go 等配置文件中相关解析与校验逻辑还涉及 model_runtime_settings.go这正是planner 显式启用的落点不配置即不启用配置错了直接拒绝构建。门禁每个阶段的强制质量关卡每个改造阶段都必须通过以下命令原文照录go test -count1 ./internal/agent/... ./internal/control/... ./internal/config/... ./internal/boot/... go test -race ./internal/agent/... ./internal/provider/... go vet ./... go run ./tools/repolint四条命令的分工可以解读为go test -count1绕过测试缓存全量跑 agent循环与契约、control协调器、config配置解析与 boot启动装配四个包的测试覆盖本文列出的全部契约项与配置 fail-closed 场景go test -race对 agent 与 provider 两个并发敏感包做竞态检测——统一重试、冻结请求回放、流式事件与取消路径正是竞态高发区go vet ./...静态检查全仓库go run ./tools/repolint仓库级 lint 工具源码位于 tools 目录对仓库整体约定做一致性校验。结语从契约到可复制的改造方法DeepSeek-Reasonix 的 Agent 核心精简给出一套完整的循环简化方法论先用文字钉死目标循环的五阶段行为再用产品决策明确哪些能力显式化、哪些能力保留为硬边界接着用既有埋点建立前后对比指标然后用一张契约-测试矩阵把每条行为承诺落实到具体测试文件最后用四条门禁命令守住每个阶段的提交质量。对于想在自己项目中做同类精简的团队这套文档测试门禁的组合比任何口头约定都更可靠——它把少调一次模型、少一次 continuation这类模糊目标变成了usage_by_source[executor].Calls 1这样可执行、可回归、可问责的工程契约。延伸阅读Agent 核心精简设计文档英文原版 与 中文版读取证据生命周期普通部分读取不冻结独立工作的硬边界说明契约测试主套件 与 循环端到端测试、重试端到端测试RunMetrics 结构定义reasonix run --metrics的完整输出字段e2ebench 基准工具-task/-json参数与context-pressure等任务场景【免费下载链接】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），仅供参考