用途:在开发、测试、文档生成、技能创建或修改、文件编辑、浏览器操作、截图、构建、校验、脚本运行以及 PowerShell/Python/Node 命令执行等过程中遇到工具链问题时使用本技能。核心是判断问题来自工具、环境还是执行通道,再选择保守恢复方案,并沉淀可复用经验。
主要原则:区分工具链问题与业务问题,不把脚本缺依赖、沙箱 helper 异常、编码误读、路径兼容或命令参数差异误判为需求、代码逻辑或文件内容问题;不伪造验证结果,官方校验无法运行时须说明真实失败原因并用替代验证补充证据,不声称原工具通过;不绕过权限与安全边界,按审批规则申请授权;替代方案须可解释、可验证,记录原始失败、替代动作、验证证据与残余风险;新问题解决后把通用规则写回 SKILL.md、USAGE.md 或 evals/evals.json,一次性项目细节不写入。全程使用中文,代码、路径、命令、API 名、错误原文、术语和库名可保留英文。
处理流程:一、捕获最小故障事实(失败命令或工具、关键错误、位置与目标文件、是否产生部分产物、权限/沙箱/网络/依赖限制),先判断类型不急着重试。二、分类匹配:编码与中文乱码(mojibake)走显式 UTF-8;补丁工具失败(apply_patch 报 sandbox/helper/read/update 错误)先缩小补丁,仍失败改用工作区原生命令写入并记录偏离;初始化脚本部分失败时保留有效产物、检查残留再补齐;校验工具缺依赖或解码失败时不宣称通过,补齐依赖或启用 UTF-8 后重跑,仍不可用则替代结构检查;命令参数不兼容时查本地帮助或改用更通用命令;权限或网络限制按审批规则处理;路径与 shell 差异用 -LiteralPath、显式工作目录和单一 shell。三、保守恢复,优先保留正确产物,先读现状再补齐,不擅自删除用户未确认内容。四、替代验证,用文件存在性、frontmatter、JSON/YAML 可解析、关键文本、模板残留、范围检查等可观察证据,只能说“替代验证通过”。五、判断是否值得写回。
编码方案:中文显示为椤圭洰鍚嶇О、闇€姹傛枃妗、浣滆€? 等通常不是文件损坏,而是 UTF-8 文件被按 ANSI/GBK 读取。读取用 Get-Content -Raw -Encoding UTF8 path\to\file.md;写入用 Set-Content -Path path\to\file.md -Value $content -Encoding UTF8;追加用 Add-Content -Path path\to\file.md -Value $content -Encoding UTF8;终端输出异常可设 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 与 $OutputEncoding = [System.Text.Encoding]::UTF8。Windows Python 默认 GBK 解码 UTF-8 文件时,先确认文件可正常 UTF-8 读取,再执行 $env:PYTHONUTF8='1' 后运行脚本;若提示 No YAML frontmatter found,检查是否有 UTF-8 BOM,重写时优先 UTF-8 no BOM 并记录原因。注意 Format-Hex 参数在不同 PowerShell 版本不一致。
适用场景与限制:适用于上述工具链故障的识别与恢复,尤其是沙箱 helper 异常、权限或路径问题、apply_patch 失败、依赖缺失、编码乱码等。限制:替代验证不等于原工具校验;权限、网络、安装或破坏性操作须遵循审批;目录删除、覆盖、批量移动须用户明确要求或审批通过;资料未提供具体评测数据、收费与平台支持信息。