From 3d44acfb15c6f46b1e7078546a275113a6480eee Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 4 Jun 2026 03:24:03 +0000 Subject: [PATCH] fix: guide mxcx apply-patch stale context recovery --- docs/reference/cli.md | 4 +-- scripts/src/apply-patch-v2.ts | 15 +++++++- scripts/ssh-argv-guidance-contract-test.ts | 40 ++++++++++++++++++++++ 3 files changed, 56 insertions(+), 3 deletions(-) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 0a6c433a..89b509d6 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -33,7 +33,7 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 DEV/PROD 滚动、P - `server rebuild ` 创建异步 job，先构建目标服务镜像，随后在 `.state/locks/server-compose.lock` 串行保护下用 `--no-deps --force-recreate` 替换目标 service 并等待容器 `healthy/running`；该命令用于替代手工删除容器的兜底流程，其中 `dev-frontend-proxy` 只更新主 server dev 入口薄代理，`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 和 `oa-event-flow` 只重建主 server 承载的对应后端，不会重建或删除 database 命名卷。D601 Code Queue 执行面不由 `server rebuild` 管理，Rust backend-core 迭代不得用 `server rebuild backend-core` 在 master server 编译，规则见 `docs/reference/dev-environment.md`。 - `provider attach [--master-server URL] [--up] [--force]` 在新计算节点生成两项配置的 provider-gateway 挂载包：`.state/provider-.env` 默认只包含 `UNIDESK_MASTER_SERVER` 与 `PROVIDER_ID`，`provider-.yml` 固定 Docker socket、`pid: "host"`、`restart: always`、只读 `/workspace` 和 SSH 维护私钥挂载；`--up` 会立即执行生成的 `docker compose up -d --build`。`provider triage [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]` 是只读多信号健康裁决入口，会把单路径 `provider is not online`、SSH 超时、registry 失败和 service proxy 失败归类成 `runner-local-observation-gap`、`service-degraded`、`provider-degraded` 或 `global-blocker`。默认输出只返回裁决、scope、失败/降级/未知信号和有界 evidence 摘要，完整 evidence 必须显式加 `--full` 或 `--raw`；推荐交叉验证命令仍包含 `debug health`、`debug dispatch host.ssh --wait-ms 15000`、`trans argv true`、`artifact-registry health --provider-id `、`microservice health k3sctl-adapter`、`microservice health code-queue` 和 `codex tasks --view supervisor --limit 20`。 - `trans [operation args...]` / `tran [operation args...]` 通过 backend-core 内网 WebSocket broker 和 provider-gateway 的 Host SSH / WSL SSH 维护桥连接目标节点；`route` 基础形态是 provider id，例如 `D601` 或 `G14`，也可以扩展为纯定位路径 `provider:plane[:namespace:resource[:container]]`，例如 `D601:win`、`D601:win/c/test`、`G14:k3s`、`D601:k3s` 或 `G14:k3s::`。WSL provider 的 Windows cmd 入口固定写 `trans D601:win cmd `，需要 Windows cwd 时用 `trans D601:win/c/test cmd cd`，由 CLI 自动设置 `chcp 65001`、`PYTHONUTF8=1` 和 `PYTHONIOENCODING=utf-8`；命名只允许 `win`，不得使用 `win32`。非交互远端命令优先使用 `trans argv ...`；需要 shell 脚本、管道、变量或循环时优先使用 quoted heredoc 单步传输，例如 `trans G14 script <<'SCRIPT'`、`trans G14:k3s script <<'SCRIPT'` 或 `trans G14:k3s:: script <<'SCRIPT'`，把脚本走 stdin。`script -- '<单个字符串>'` 是无需 stdin 的远端 shell one-liner，例如 `trans G14:/root/hwlab script -- 'cd /root/hwlab && git status --short --branch'`；`script -- <多个 argv>` 才是 direct argv，适合 `trans D601:/path script -- sed -n '1,20p' file` 这类带短横线的单进程命令。顶层 remote option parser 必须保留命令已经开始后的 `--`，不得把它吞成全局选项结束符。需要远端改文本文件时默认优先使用 ` apply-patch < patch.diff`；需要可靠传输非文本或整文件时使用 ` upload ` 和 ` download `，CLI 会按字节数与 SHA-256 自动校验并在 provider-gateway stdin/argv 限制下切换客户端分块策略；需要旧 helper 时显式使用 `:k3s:: apply-patch-v1` 或 ` apply-patch-v1`。ssh-like 命令遇到 timeout/kex/255 类失败时，CLI 会在 stderr 追加一行 `UNIDESK_SSH_HINT` JSON，提示 stdin script/argv 重试和 provider triage 交叉验证。 -- `trans apply-patch < patch.diff` 是默认推荐的远端 patch 入口：本地 TypeScript line-based engine 解析和计算新文件内容，远端 route 只负责读写文件；支持 host workspace、k3s pod workspace、Windows workspace route（例如 `D601:win/c/test`）和 frontend transport，并优先处理长中文/Unicode、低上下文插入、重复块 `@@` 定位等旧 helper 容易失败的场景。`apply-patch` 输出按 Codex 标准文本口径，不套 UniDesk JSON 限制：成功 stdout 为 `Success. Updated the following files:`，失败 stdout 为空、stderr 写失败原因；多文件补丁中途失败时，stderr 只列出第一个失败前已成功执行的 hunk 和失败 hunk，随后按 Codex 语义停止，不继续尝试后续 hunk。v2 兼容常见 MiniMax/MXCX 非标准补丁输入，例如重复 nested `*** Begin Patch` / `*** End Patch` envelope、unified-diff hunk header、Add/Delete 误加 `@@`、Update context 漏掉前导空格，并在 stderr 给出 canonical 写法 hint；parser 或上下文失败时仍坚持唯一 v2 引擎，只提示修正 patch 文本或 hunk context，不自动重试或切换到 `apply-patch-v1`。Windows route 复用同一套 v2 核心算法，只把底层读写替换成 PowerShell 文件系统接口；`trans apply-patch-v1 [tool args...] < patch.diff` 保留为显式 legacy 入口，直接调用远端注入的 `apply_patch` sh/perl helper；默认 `apply-patch` 不把 v1 当 fallback。 +- `trans apply-patch < patch.diff` 是默认推荐的远端 patch 入口：本地 TypeScript line-based engine 解析和计算新文件内容，远端 route 只负责读写文件；支持 host workspace、k3s pod workspace、Windows workspace route（例如 `D601:win/c/test`）和 frontend transport，并优先处理长中文/Unicode、低上下文插入、重复块 `@@` 定位等旧 helper 容易失败的场景。`apply-patch` 输出按 Codex 标准文本口径，不套 UniDesk JSON 限制：成功 stdout 为 `Success. Updated the following files:`，失败 stdout 为空、stderr 写失败原因；多文件补丁中途失败时，stderr 只列出第一个失败前已成功执行的 hunk 和失败 hunk，随后按 Codex 语义停止，不继续尝试后续 hunk。v2 兼容常见 MiniMax/MXCX 非标准补丁输入，例如重复 nested `*** Begin Patch` / `*** End Patch` envelope、unified-diff hunk header、Add/Delete 误加 `@@`、Update context 漏掉前导空格，并在 stderr 给出 canonical 写法 hint；parser 或上下文失败时仍坚持唯一 v2 引擎，只提示修正 patch 文本或 hunk context，不自动重试或切换到 `apply-patch-v1`；大块/函数替换因上下文过期失败时，正确动作是重新读取当前目标块、缩小或拆分 Update File hunk 后继续用 `apply-patch`，不得改走 `download`/`upload`、远端 Python/Perl/sed heredoc 或整文件重写。Windows route 复用同一套 v2 核心算法，只把底层读写替换成 PowerShell 文件系统接口；`trans apply-patch-v1 [tool args...] < patch.diff` 保留为显式 legacy 入口，直接调用远端注入的 `apply_patch` sh/perl helper；默认 `apply-patch` 不把 v1 当 fallback。 - `trans py [script-args...] < script.py` 把本地 stdin 落到远端临时 `.py` 文件后再以 `python3 -u` 执行并自动清理，避免再手写 `'python3 -'`、heredoc 或多层引号；`script-args` 会按 argv 安全透传给远端脚本。 - `trans skills [--scope all|wsl|windows] [--limit N]` 发现目标节点上的 WSL/Linux skill 根目录；当 provider 是 WSL 时同一次调用还会扫描 Windows 用户目录下的 `.agents/skills` 与 `.codex/skills`。 - `trans :k3s[:namespace:workload[:container]] ...` 是原生 k3s 结构化 route 入口，route 只定位控制面或 workload，`kubectl`、`logs`、`exec`、`script`、`apply-patch`、旧 `apply-patch-v1` fallback 和普通容器命令作为 operation 放在 route 之后；CLI 固定注入 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 并把 kubectl、workload exec、logs 和 pod workspace 读写参数组装成 argv，避免在 Host SSH、bash、kubectl exec 和容器 shell 之间反复手写多层引号；D601 与 G14 都有 provider-specific guard，分别校验 `d601` 和 G14 k3s 节点身份。 @@ -272,7 +272,7 @@ ssh-like 远端命令如果出现 `kex_exchange_identification`、`Connection cl `trans ` 透传只在当前 operation 需要 helper 时才注入 `/tmp/unidesk-ssh-tools`，普通 `argv`、`script`、`kubectl`、`logs` 和默认 `apply-patch` 等路径不得传输无关工具源码。`apply-patch-v1` 只注入 `apply_patch`；`glob` 只注入 `glob`；`skills`/`skill discover` 只注入 `skill-discover`。`apply_patch` 接受标准 `*** Begin Patch` / `*** End Patch` patch 格式，便于通过 SSH 透传编辑远端仓库文件；远端存在 `perl` 时必须走快速精确匹配路径，避免大文件 hunk 被 sh 模式匹配拖成几十秒，缺少 `perl` 时才退回 sh-only 实现。`glob` 和 `skill-discover` 需要远端 `python3`。注入工具只写 `/tmp/unidesk-ssh-tools`，不修改目标仓库。 -远端文本 patch 默认使用 `apply-patch` 的 v2 引擎：它不把 hunk 解析交给远端 shell/perl helper，而是在本地按行序列匹配，支持长中文/Unicode 行、纯新增 hunk、低上下文插入和 `@@` 上下文定位，再把完整新内容写回远端。v2 的文件操作提交顺序按 Codex 标准 `apply_patch` 语义执行：空 patch 会失败；删除不存在的文件会失败；`Add File` 可覆盖已有文件；`Move to` 可覆盖目标文件；当大 patch 后续 hunk 不匹配时，已成功提交的前序文件操作会保留，并在错误详情中记录 `partialChanges`，调用方应基于当前文件内容继续补一个更小的 patch，而不是期待全量事务回滚。`apply_patch` 旧 helper 默认拒绝低上下文 update hunk：空搜索/纯插入无锚点、只在插入点前有上下文而没有插入点后上下文、或同一 hunk search 在目标文件中匹配多个位置时，都会结构化失败并提示补充上下文。成功应用时每个 hunk 会在 stderr 输出 `apply_patch: hunk N matched path:line`，用于复核实际落点；只有人工确认确实需要旧 helper 行为或 `--allow-loose` 时，才显式调用 `apply-patch-v1 --allow-loose`。 +远端文本 patch 默认使用 `apply-patch` 的 v2 引擎：它不把 hunk 解析交给远端 shell/perl helper，而是在本地按行序列匹配，支持长中文/Unicode 行、纯新增 hunk、低上下文插入和 `@@` 上下文定位，再把完整新内容写回远端。v2 的文件操作提交顺序按 Codex 标准 `apply_patch` 语义执行：空 patch 会失败；删除不存在的文件会失败；`Add File` 可覆盖已有文件；`Move to` 可覆盖目标文件；当大 patch 后续 hunk 不匹配时，已成功提交的前序文件操作会保留，并在错误详情中记录 `partialChanges`，调用方应基于当前文件内容继续补一个更小的 patch，而不是期待全量事务回滚。若 stderr 报 `failed to find expected lines` 且显示 partial context match，尤其是大块/函数替换，调用方必须先重读目标文件当前块，再用更少稳定上下文、`@@ ` 或多个小 hunk 重试；该失败不构成改用 `download`/`upload`、远端脚本整文件替换或 `apply-patch-v1` 的理由。`apply_patch` 旧 helper 默认拒绝低上下文 update hunk：空搜索/纯插入无锚点、只在插入点前有上下文而没有插入点后上下文、或同一 hunk search 在目标文件中匹配多个位置时，都会结构化失败并提示补充上下文。成功应用时每个 hunk 会在 stderr 输出 `apply_patch: hunk N matched path:line`，用于复核实际落点；只有人工确认确实需要旧 helper 行为或 `--allow-loose` 时，才显式调用 `apply-patch-v1 --allow-loose`。 如果只是远端打文本补丁，不需要再手写 `ssh D601 'apply_patch' < patch.diff` 这种命令拼接；正式默认入口是 `trans D601:/absolute/workspace apply-patch < patch.diff`、`trans D601:k3s::/ apply-patch < patch.diff` 或 `trans D601:win/c/test apply-patch < patch.diff`。旧 helper 只有 `apply-patch-v1` 一个入口，附加参数会原样透传给远端 `apply_patch`，例如 `trans D601 apply-patch-v1 --help` 或 `trans D601 apply-patch-v1 --allow-loose < reviewed.patch`。标准单命令用法如下，不需要先创建本地 patch 临时文件： diff --git a/scripts/src/apply-patch-v2.ts b/scripts/src/apply-patch-v2.ts index 03e555c0..4ac1e3d0 100644 --- a/scripts/src/apply-patch-v2.ts +++ b/scripts/src/apply-patch-v2.ts @@ -126,6 +126,7 @@ export function applyPatchV2HelpPayload() { "A blank line in Add File is a line containing only +.", "Update File uses @@ or @@ context markers, followed by context lines starting with one extra space prefix and changed lines starting with - or +; for a column-0 source line `const x`, write ` const x`, and for a two-space-indented source line write three spaces total. Unified-diff line-range headers are accepted with hints for MiniMax compatibility.", "Prefer `trans apply-patch < /tmp/patch.diff` for long patches, Windows paths, or quoting-sensitive content.", + "If `failed to find expected lines` reports stale or oversized context for a block/function replacement, re-read the exact current block and retry with a smaller Update File hunk or split hunks around unique anchors.", "MiniMax compatibility: stray @@ or unprefixed content inside Add File, unprefixed Update File context lines, and extra hunk/body lines after Delete File, are accepted with stderr hints.", "MiniMax/MXCX concatenated patch compatibility: repeated nested Begin Patch / End Patch markers are accepted with stderr hints, but the CLI still uses only the v2 engine and never auto-falls back to apply-patch-v1." ], @@ -153,6 +154,7 @@ export function applyPatchV2HelpPayload() { "Do not put @@ after `*** Add File:`; @@ is only for Update File.", "Prefer canonical @@ or @@ context over unified diff headers such as `@@ -1,3 +1,4 @@`; v2 accepts those headers with a hint.", "If multiple printf/heredoc fragments were concatenated, keep one outer Begin/End envelope or include complete nested envelopes; v2 will hint on nested markers instead of trying the legacy helper.", + "Do not recover from apply-patch context mismatch by switching to download/upload, remote Python/Perl/sed, or whole-file rewrites; retry with corrected v2 hunks.", "Do not use remote Python/Perl/sed heredocs for text patches when `trans apply-patch` is available." ], note: "apply-patch reads patch text from stdin and uses the v2 engine by default. Use `apply-patch-v1` only for the legacy helper." @@ -475,6 +477,9 @@ function appendExpectedLineDiagnostics(lines: string[], cause: Record | null { @@ -1044,13 +1049,15 @@ function expectedLineDiagnostics(originalLines: string[], chunk: UpdateChunk, pr const firstExpectedLine = chunk.oldLines.find((line) => line.trim().length > 0) ?? ""; const firstExpectedLineCandidates = firstExpectedLine.length === 0 ? [] : candidateLineNumbers(originalLines, firstExpectedLine, 8); const prefix = bestPrefixMatch(originalLines, chunk.oldLines, firstExpectedLine, preferredStart); + const missingAddedPrefixes = likelyMissingAddedPrefixes(chunk, prefix.matchedLines); return { firstExpectedLine, firstExpectedLineCandidates, firstExpectedLineCandidatesTruncated: firstExpectedLine.length > 0 && candidateLineNumbers(originalLines, firstExpectedLine, 9).length > firstExpectedLineCandidates.length, bestPrefixMatchedLines: prefix.matchedLines, bestPrefixStartLine: prefix.startLine, - likelyMissingAddedPrefixes: likelyMissingAddedPrefixes(chunk, prefix.matchedLines), + likelyMissingAddedPrefixes: missingAddedPrefixes, + likelyStaleOrOversizedContext: !missingAddedPrefixes && likelyStaleOrOversizedContext(chunk, prefix.matchedLines), }; } @@ -1093,6 +1100,12 @@ function likelyMissingAddedPrefixes(chunk: UpdateChunk, bestPrefixMatchedLines: return bestPrefixMatchedLines > 0 && bestPrefixMatchedLines < chunk.oldLines.length; } +function likelyStaleOrOversizedContext(chunk: UpdateChunk, bestPrefixMatchedLines: number): boolean { + if (chunk.oldLines.length < 4) return false; + if (bestPrefixMatchedLines < 2 || bestPrefixMatchedLines >= chunk.oldLines.length) return false; + return chunk.addedLineCount > 0 || chunk.deletedLineCount > 0 || chunk.contextLineCount >= 4; +} + function lineEquivalent(left: string, right: string): boolean { return left === right || left.trimEnd() === right.trimEnd() || left.trim() === right.trim() || normalizeLine(left) === normalizeLine(right); } diff --git a/scripts/ssh-argv-guidance-contract-test.ts b/scripts/ssh-argv-guidance-contract-test.ts index 6c817b9f..ca5ed11c 100644 --- a/scripts/ssh-argv-guidance-contract-test.ts +++ b/scripts/ssh-argv-guidance-contract-test.ts @@ -1078,6 +1078,46 @@ export async function runSshArgvGuidanceContract(): Promise { missingPlusLargeInsertVisibleV2.stderr, ); + const staleBlockReplacementVisibleV2 = await applyPatchV2FixtureAttempt([ + "*** Begin Patch", + "*** Update File: runner-trace.ts", + "@@", + " export async function waitForAgentResult(", + " initial: AgentChatResponse,", + " activityRef?: ActivityRefSource", + " ): Promise {", + " if (isTerminalStatus(initial.status)) {", + " return isTerminalStatus(initial.status) ? initial : null;", + " }", + "- return initial;", + "+ return pollAgentResult(initial, activityRef);", + " }", + "*** End Patch", + "", + ].join("\n"), { + "runner-trace.ts": [ + "export async function waitForAgentResult(", + " initial: AgentChatResponse,", + " activityRef?: ActivityRefSource", + "): Promise {", + " if (isTerminalStatus(initial.status)) return initial;", + " return pollAgentResult(initial);", + "}", + "", + ].join("\n"), + }, { stderrOutput: true }); + assertCondition(staleBlockReplacementVisibleV2.exitCode === 1 && staleBlockReplacementVisibleV2.error === null, "v2 should reject stale block-replacement hunks without falling back", staleBlockReplacementVisibleV2); + assertCondition( + staleBlockReplacementVisibleV2.stderr.includes("Best partial context match: 4 expected line(s) matched") + && staleBlockReplacementVisibleV2.stderr.includes("stale or oversized context for a block/function replacement") + && staleBlockReplacementVisibleV2.stderr.includes("Do not switch to download/upload") + && staleBlockReplacementVisibleV2.stderr.includes("remote Python/Perl/sed") + && staleBlockReplacementVisibleV2.stderr.includes("retry apply-patch with a smaller hunk") + && staleBlockReplacementVisibleV2.stderr.includes("split the edit into hunks around unique anchors"), + "v2 stale block replacement failure should steer MiniMax back to smaller apply-patch hunks instead of file transfer or script rewrites", + staleBlockReplacementVisibleV2.stderr, + ); + const fragmentedEnvelopeFailureV2 = await applyPatchV2FixtureAttempt([ "*** Begin Patch", "*** Update File: fragment.txt",