[Bug] Windows 文件系统不兼容 - 标识符中包含非法字符冒号(:)

[2217173240]

问题描述

在 Windows 环境下运行单元测试时，遇到 ENOENT: no such file or directory, mkdir 错误，无法创建
目录。

复现步骤

1. 在 Windows 环境下克隆项目
2. 安装依赖: npm install
3. 运行单元测试: npm run test:unit
4. 观察到多个测试失败，报告无法创建目录

根本原因

Windows 文件系统不允许文件/目录名包含冒号 :，但代码中多处使用冒号作为标识符分隔符：

• Agent ID: agt:01KCGMTE419G1ED239ZJ2AKNW9
• Fork ID: fork:1765790723759
• Snapshot ID: sfp:0
• Checkpoint ID: agentId:timestamp

这些标识符被用作目录/文件名，导致在 Windows 上通过 Node.js 创建目录时失败。

影响范围

• ❌ Windows 用户无法运行测试
• ❌ Windows 用户使用 SDK 时可能遇到运行时错误
• ✅ Linux/macOS 用户不受影响（这些系统允许文件名包含冒号）

解决方案

已在分支 fix/windows-compatibility 中修复，将所有标识符中的冒号 : 替换为连字符 -：

• agt: → agt-
• fork: → fork-
• sfp: → sfp-
• :${Date.now()} → -${Date.now()}

同时修复了相关的 TypeScript 编译错误和测试适配问题。

测试结果

✅ 所有 58 个单元测试在 Windows 环境下通过 (100%)

Breaking Change

⚠️ 这是一个破坏性变更，因为 ID 格式发生改变：

• 旧的持久化数据（使用冒号格式的 Agent ID）无法直接与新版本兼容
• 建议作为主版本更新发布 (v3.0.0)

相关 PR

#[PR 编号] - 等待创建

---

环境信息:

• 操作系统: Windows 10/11
• Node.js 版本: v22.14.0
• SDK 版本: 2.7.0

📊 修复详情

修改的文件 (14个):

1. src/utils/agent-id.ts - Agent ID 格式
2. src/core/agent.ts - Agent ID 和 Fork ID
3. src/utils/session-id.ts - Fork ID 和 Snapshot ID
4. src/core/checkpointer.ts - Checkpoint ID
5. src/core/checkpointers/file.ts - Checkpoint ID
6. src/core/checkpointers/redis.ts - Checkpoint ID
7. src/tools/mcp.ts - TypeScript 类型错误
8. src/tools/tool.ts - TypeScript 类型错误
9. src/tools/type-inference.ts - TypeScript 类型错误
10. tests/unit/tools/todo.test.ts - 测试框架适配
11. tests/helpers/fixtures.ts - 测试路径修复
12. examples/03-room-collab.ts - 示例代码更新
13. examples/nextjs-api-route.ts - 示例代码更新
14. tests/integration/collaboration/room-collab.test.ts - 集成测试更新

[luojiyin1987]

@2217173240 麻烦提pr