四十一条实测踩坑清单：每条都标了根因和正解

1

子串匹配误删（踩过两次）

现象：用「包含某关键词」去过滤要删的东西，把不相关的文件一起圈进来了——比如过滤某个缩写，命中了名字里含这几个字母的另一批文件。 正解：一律用前缀匹配或精确特征串，不用「包含」。执行前把命中清单打印出来核一遍。

2

规则只对「此后新增」生效（踩过三次）

现象：新加的忽略规则 / 命名规则看似生效了，但旧文件我行我素。 根因：已进入版本库的文件不受新规则约束。 正解：定规则时同时执行一次全库存量清理，并用「列出被跟踪文件」的命令核对，否则规则只对一半数据成立。

3

目录名像垃圾 ≠ 内容是垃圾

现象：一批纯时间戳目录看起来就是临时产物，差点整体删除；逐个读过内容后发现其中四个含有效成果（方案稿、课题记录、命名源头、离线依赖包）。 正解：判定价值的唯一可靠方法是读内容。目录名、创建时间、体积都不能作为删除依据。

4

同名文件直接覆盖

现象：把归档文件复制到目标目录，目标已存在同名文件，内容完全不同（一个是 30 KB 的项目日志，一个是 1.5 KB 的零散记录），直接复制会覆盖掉大的那份。 正解：先比对内容（哈希 / 大小），不同则追加而非覆盖。

5

回收站接口返回值与实际不符

现象：删除接口返回非零，看起来失败了，但文件其实已经删掉；随后再删就报「文件不存在」，造成二次确认的假失败。 正解：不要看返回值，操作后重新列目录核实实际状态。

6

删除对象 ≠ 删除关于它的陈述

现象：某个外部服务已全面停用、技能包与凭据都删了，但描述它的文字分散在四五个地方（用户级记忆整节、项目记忆整节、技能正文、云端档案），全局搜一遍名字能找出十几处残留。 正解：停用某个东西时，必须全局搜一遍它的名字，清理所有陈述。失效内容若确实要留作追溯，必须加生命周期标注（「已失效，仅作追溯」）。

7

删除前不备份

正解：批量操作前先复制一份到备份区；空目录删除本身有天然保护（非空会报错），文件走回收站。

8

参数名写错 → 静默返回空

现象：列举子节点的参数名写成了另一个近似的名字，不报错，直接返回 0 个子节点——很容易被误判成「这个目录是空的」。 正解：这个坑踩过两次。凡接口返回空，先核对参数名，再下结论。

9

列表型参数必须传 JSON 数组

现象：把单个 id 裸传进列表参数，报解析错误。 正解：传 ["id"] 形式的 JSON 数组字符串。

10

写入结构与读取结构不一致

现象：写入时每个值是「类型 → 值」的包装，读回来却是直接的值；记录 id 的字段名读写也不同。 正解：不要照着读到的结构去写。 这条是全文被推翻次数最多的一条（不同接口叫法不同），务必以当场实测为准，不要照抄任何记忆里记的名字。

11

字段值类型不匹配

现象：给选择类 / 日期类字段传了对象或数组，服务端报解析错误。 正解：按字段类型给对的形态（字符串 / 数字 / 布尔）。

12

选项 id 想当然

正解：选项 id 由服务端分配，成功响应的结构才是唯一可信来源；已有选项 id 永久不变，改字段时必须原样复用。

13

以为「创建」是可逆的

现象：测试建了几个节点和表，想清理时发现没有删除接口——表（节点）删不掉，只有字段和记录能删。 正解：壳不可删，内容可删。 凡通过接口创建节点，一律当作不可逆写操作，建之前确认标题、位置、内容。

14

覆写页面时不带节点 id

现象：每次运行都新建一个页面节点，永久堆积。 正解：必须带目标节点 id 执行覆盖导入；把节点 id 持久化到本地文件，丢了就会新建第二个节点。

15

传上去了 ≠ 放对了

现象：接口返回成功，但资产落在了错误的目录（复用了上下文里残留的旧父节点 id），手机上根本翻不到。 正解：判据是到「列节点」里看一眼它跟谁是兄弟，而不是看接口返回 success。

16

「节点时间戳」当作写入证据

现象：页面明明覆盖成功了，节点更新时间却停在几小时前，差点误判成「假成功」。 正解：节点元数据不反映内容变更。 查证写入一律看内容本体（表查记录、页面查内容里的时间戳标记）。

17

用「能不能写」试探权限

正解：用节点原样的标题去改名——成功也只是「改成它自己」，零副作用。

18

把「没搜到」当成「索引延迟」

现象：某类节点的正文明明在，检索却零命中，以为是索引还没建好。隔 24 小时复测仍为零。 正解：它压根不进索引。 反之另一类文件型节点（PPT/Word/PDF）上传后约 5 分钟就能被搜到——「快」与「能不能搜」是两回事。

19

只信封装脚本的「无命中」

现象：封装好的检索脚本报「没有命中」，但用底层接口在同样条件下返回了 3 条。 正解：两者过滤口径不同。怀疑检索不到时，用底层接口再验一次。

20

用节点级检索找文件和表格

现象：查某个数据表的名称，返回的是引用它的页面；查一个确实存在的文档标题，0 命中；查文件型节点，连标题都搜不到。 正解：找东西的主力是内容级检索，节点级只当辅助。

21

3-gram 重叠率高就当内容重复

现象：用中文 3-gram 相似度对比技能与记忆，发现重叠率普遍 10% 以上，差点得出「大面积重复」的结论。 正解：中文 3-gram 天然有 8%–10% 的基线，必须降级到「最长公共子串」层面才看得出真重复。逐段比对后结论正好相反——重复的只是标识符，没有整段规则被抄两遍。

22

静默失败（云端脚本头号坑）

现象一：某个子步骤失败后代码静默返回空列表，结果报「待处理 0 条」，而实际有 2 条。 现象二：导入接口三步全部返回成功，宿主也把预置的节点号当作成功报出来，但实际内容没变。 正解：① 每个降级分支必须打印诊断信息，不允许吞错；② 产出一律看内容本体，不信脚本自报的成功。

23

提示词里写死阈值 / 数量 / 路径

现象：改了源头配置，提示词里那份没跟着变——阈值过期、数量不符、指引指向一个已被移动的文件。 正解：一个事实两个存放点，迟早分家。 提示词只写流程与权限；能交给脚本判断的，一律让脚本给结论。

24

不想动手，直接等它到点跑

现象：自动化不能手动触发，提示词里的命令有错，要等下一整个周期才发现。 正解：写进提示词的每条命令，建之前先手工跑一遍。

25

验证等价物而不是交付物

现象：把入口文件里的核心命令抽出来在终端跑通了，就认为交付物没问题。实际文件换行符格式错误，运行时只执行到最后一行，前面全部被吞。 正解：落地形态是哪一种，就验证哪一种。

26

用一条命令的成败推断外部状态

现象：连通性预检报「找不到远程助手」，被归为「目标不可达」；实际是本机配置问题（命令不在 PATH / 用错了可执行文件版本）。 后果：自动化会安静地永远不工作，且不认为自己在失败。 正解：把环境处理、地址读取、超时、错误分类全部收进一个脚本，用不同退出码区分「可达 / 真网络不通 / 本机配置错误」。

27

给破坏性写入配周期重试

现象：一条「重建在线表」的周期任务，在接口持续报错时用重试去凑成功，最终依据过时清单误删了前一天手动建立的十几条真实数据。 正解：删除 / 覆盖 / 重建不进周期自动化；重试只对幂等操作安全。判定句式：这个动作失败时的代价是什么？重跑一遍会怎样？

28

只看规则成熟度就决定自动化

现象：三个候选（规则已写进技能、产出固定、周期明确）看起来都适合自动化，逐条核对后发现数据源在封闭内网、或者根本不是周期任务而是事件驱动。 正解：先看数据源够不够得着，再看规则成不成熟。

29

扩展名导致分流错误

现象：想把一个压缩包当「文件」存进网盘，结果被导入成了「页面」。 正解：资料库按扩展名分流。改个后缀（如把 .zip 改成 .dat）即可走网盘通道。

30

命令挂起，既不返回也不报错

现象：网络通、凭据有效，但同步命令无限期挂起，反复重试无效。 根因：系统级配置里启用了一个会等待图形界面助手的凭据管理器，在无交互终端的环境下永久阻塞。 正解：所有调用统一显式禁用凭据助手（地址里已内嵌有效凭据，助手纯属多余）。判定手段：加上该参数后若秒回，即可确诊。 注意：常见的「禁止终端提示」环境变量治不了这个问题——它只管终端提示，管不住图形界面分支。

31

用错可执行文件版本

现象：查询类命令能跑，一涉及网络传输就报「远程助手不是有效命令」。 根因：这类工具链通常有两个入口——一个是包装器，一个是本体。包装器自称的路径与实际存放远程助手的位置不一致。 正解：定位真正的本体并把它的目录加入 PATH。

32

命令不在 PATH，静默返回空

现象：某个命令直接调用时「静默返回 0 条结果」，会被误判成「一个文件都没同步」。 正解：脚本里自动定位完整路径，不依赖环境。

33

仓库元数据目录丢失

现象：报「不是有效仓库」，重建后又报「对象损坏」，看起来仓库已毁。 正解：通常只有部分子目录丢失，对象库与日志还在。若远端对象完好，走「备份损坏目录 → 重新初始化 → 取回远端 → 用远端树重置索引 → 以本地工作区为准重新提交 → 推送」这条路即可，不需要强制推送。

34

忽略规则的层级与拼写

现象一：规则里少了一个字母，导致它从未生效——这才是「本该被忽略的目录被纳入版本库」的根本原因。 现象二：不带前导斜杠的规则会匹配任意层级，把本应保留的镜像目录一起忽略。 正解：限定根目录必须带前导斜杠；写完规则立刻验证。

35

中文 / 带引号的路径走 shell

现象：路径经 shell 传递时被转义搞乱，批量操作出错。 正解：用「从标准输入读原始字节」的方式传路径列表，完全规避转义问题。

36

合并前不看远端改了什么

现象：远端有一批看起来杂乱的提交，差点整体丢弃；逐条核对后发现其中有一件有价值的东西（另一台设备修正过的部署路径）。 正解：合并前必须先看远端改了什么。 不能因为「提交多、看着乱」就整体丢弃。

37

加密拦截误判为代码 bug

现象：读写文件的进程被直接杀掉，且零输出 + 非零退出 + 无堆栈信息。 正解：这是外部拦截，不是代码 bug，也不是运行环境问题（两者都实际误判过）。立即停下报告，不自动重试、不自行换方案，由人决定后续。

38

判断「某层是否为空」时只搜了一处

现象：只看了最显然的那个配置文件，得出「这一层完全没有接入」的结论；实际另有第二、第三份配置，里面有数百条条目。 正解：结论前的路径搜索必须穷尽。 这是本机第三次因搜索不全导致误判。

39

只看一层目录就下「不在树里」的结论

现象：只展开了父目录一层，没看到某类节点，就断言它「不在目录树里，靠横向引用」。展开另一层后纠正。 正解：下结构性结论前，把引用链展开到最底层。

40

YAML 块标量被正则误判

现象：扫描技能元数据是否含某字段时，用「字段名 + 冒号 + 内容」的单行正则，把多行块写法误判为「字段缺失」。 正解：检测这类前置元数据必须兼容块标量语法，不能只匹配单行。

41

二进制资源一刀切忽略

现象：把某类文件整体排除出同步，结果把技能里的功能资源也排除了。 正解：判据是「删了技能还能不能用」，不是「是不是二进制」。技能里的截图 / 模板属于可用性的一部分。