Claude Code Windows Symlink 权限问题调查

问题发现

在使用 Claude Code 进行代码审查时，我启动了多个后台子代理（sub-agent）并行工作。完成后发现一个奇怪现象：

├─ superpowers:code-reviewer (Review code quality) · 58 tool uses · 0 tokens ⎿ Done
├─ Agent (Review UI/UX design) · 34 tool uses · 0 tokens ⎿ Done
├─ Explore (Explore project structure) · 12 tool uses · 0 tokens ⎿ Done

子代理明明执行了 58 次工具调用，怎么可能是 0 tokens？

第一阶段：怀疑竞态条件

最初通过分析临时文件，我发现了：

指标	数值
总输出文件	89 个
空文件（0 字节）	82 个（92%）
非空文件	7 个（8%）

结合 transcript 文件显示实际产生了 41397 tokens，我初步认为这是竞态条件导致的：

T0: 子代理完成
T1: completeAgentTask() 被调用
T2: void evictTaskOutput(taskId)  ← 不等待
T3: enqueueAgentNotification() 发送通知
T4: 主会话读取输出文件 → 文件为空
T5: 磁盘 flush 完成（太晚）

我在 Issue 中详细分析了这个假设。

第二阶段：验证发现异常

为了验证，我再次启动多个后台子代理进行测试。结果：

所有子代理输出文件都是 0 字节！

这太统一了，不像是竞态条件。竞态条件应该有时成功有时失败，而这里是 100% 失败。

第三阶段：发现真正原因

我检查了文件类型：

ls -la *.output
# -rw-r--r-- 1 user 0 ... xxx.output
# 普通空文件

查看源码发现 initTaskOutputAsSymlink() 函数：

尝试创建 symlink 从输出文件指向 transcript
失败时回退为创建空文件

关键发现：Windows 上创建 symlink 需要特殊权限！

测试 PowerShell：

New-Item -ItemType SymbolicLink -Path "link" -Target "target"
# 错误：此项操作需要管理员权限。

确认了：Windows 默认不允许普通用户创建 symlink，需要开启开发者模式。

第四阶段：开启开发者模式

开启 Windows 开发者模式：

设置 → 更新和安全 → 开发者选项 → 开发人员模式

重新测试后：

ls -la *.output
# lrwxrwxrwx 1 user 120 ... xxx.output -> agent-xxx.jsonl
# 现在是 symlink，指向 transcript 文件
 
wc -c *.output
# 1498 xxx.output  ← 有内容了！

问题解决！

最终结论

原始假设	实际原因
竞态条件	❌ 错误
Windows symlink 权限问题	✅ 正确

根本原因：

Windows 默认不允许普通用户创建 symlink
CLI 在 symlink 创建失败时静默回退到空文件
没有向用户提示权限问题或解决方案

提交内容

Issue #55263

在 Issue 中补充了真正的原因分析，并提供了 workaround：

Windows users can try enabling Developer Mode:

Settings → Update & Security → For developers → Developer mode

PR #56334

提交了文档改进，在 README 中添加 Windows Developer Mode 说明：

Note for Windows users: Some features require symlink support. Enable Developer Mode if you encounter issues with background agents.

这个 PR 获得了社区用户的 APPROVED。

经验总结

调试方法论

排除法 - 从多个假设中逐一验证
统计数据分析 - 92% 的空文件率太统一，不像竞态条件
检查文件类型 - ls -la 显示文件类型是关键线索
验证假设 - 开启开发者模式后问题解决
逐步深入 - 从代码分析 → 行为观察 → 权限验证

真理比面子重要

最初认为问题原因是竞态条件。但当证据指向其他方向时，需要承认错误并补充真正的原因。

真理和诚信比虚名更重要。