openclaude/docs/free-code-main-diff-analysis.md

/Users/yovinchen/project/claude 与 /Users/yovinchen/Downloads/free-code-main 差异分析

1. 分析目标

本文档用于比较当前工作区：

• /Users/yovinchen/project/claude

与参考项目：

• /Users/yovinchen/Downloads/free-code-main

重点回答三个问题：

1. 当前项目相对参考项目改了什么。
2. 哪些改动属于“恢复后为保证可运行而做的必要修复”。
3. 哪些差异仍然值得继续收敛或补做验证。

2. 总体结论

当前项目不是简单复制参考项目，而是一个“基于参考快照恢复后可运行化”的工作副本。

核心判断如下：

1. 工程配置层与参考项目总体高度接近。
2. 当前项目为了恢复 bun run dev、build、compile 能力，加入了一层运行时补丁和仓库管理文件。
3. 源码层存在较多文件差异，主要集中在 CLI 启动链路、遥测、认证、模型配置、LogoV2、Claude in Chrome、MCP/SDK 辅助代码等区域。
4. 当前项目额外引入了一批 .js 文件，明显属于“补齐运行时依赖/类型生成产物/兼容层”的恢复性文件。
5. 参考项目仍然保留一些当前仓库没有带入的资源文件、说明文件和脚本文件，这些不一定影响运行，但会影响“与参考仓库完全一致”的完整度。

3. 差异概览

3.1 顶层目录差异

当前项目独有的顶层内容：

• .gitattributes
• docs/
• vendor/
• cli.js.map
• .DS_Store

参考项目独有的顶层内容：

• .env
• CLAUDE.md
• FEATURES.md
• assets/
• changes.md
• install.sh
• run.sh

说明：

1. 当前项目更像“已接入 Git 管理、可持续维护”的开发仓库。
2. 参考项目更像“恢复快照 + 使用说明 + 辅助资源”的完整分发目录。
3. assets/、CLAUDE.md、FEATURES.md、changes.md 当前未带入，功能上未必是阻塞，但文档与资源完整度低于参考项目。

3.2 源码文件差异规模

通过目录级比较可见：

1. src/ 下有约 55 个同名文件内容不同。
2. 参考项目在 src/ 下没有发现当前缺失而参考独有的源码文件。
3. 当前项目反而额外多出一批源码/运行时补丁文件。

这说明当前项目的主体源码骨架已经基本补齐，但很多文件内容已经偏离参考项目，不再是“原样恢复”。

4. 工程配置差异

4.1 package.json

文件：

• /Users/yovinchen/project/claude/package.json
• /Users/yovinchen/Downloads/free-code-main/package.json

关键差异：

1. 包身份不同

   • 当前：name = "claude-code-recover"
   • 参考：name = "claude-code-source-snapshot"

2. 版本号不同

   • 当前：2.1.88
   • 参考：2.1.87

3. 当前项目增加了 main: "./cli"

4. bin 被精简

   • 当前只保留 claude
   • 参考同时暴露 claude 和 claude-source

5. scripts 被精简

   • 当前保留：build、compile、dev
   • 参考还包含：build:dev、build:dev:full

6. 当前 dev 脚本加入了 MACRO 注入

   • 当前：通过 bun run -d 'MACRO:...' ./src/entrypoints/cli.tsx
   • 参考：直接 bun run ./src/entrypoints/cli.tsx

7. 当前额外声明了依赖：

   • scheduler

分析：

1. 这些差异不是随机漂移，而是为了让恢复后的工作区更适合直接运行。
2. MACRO 注入是本项目最关键的运行性修复之一，因为当前源码曾出现 MACRO is not defined 的实际故障。
3. 删除 claude-source 和精简 scripts 会降低与参考项目的“接口一致性”，但能让当前项目更聚焦于单一运行入口。
4. 新增 scheduler 很像一个恢复期补依赖动作，说明当前项目在实际运行时遇到过依赖缺失。

4.2 tsconfig.json

文件：

• /Users/yovinchen/project/claude/tsconfig.json
• /Users/yovinchen/Downloads/free-code-main/tsconfig.json

关键差异：

1. 当前项目增加了：
   • "ignoreDeprecations": "6.0"

分析：

1. 这属于 TypeScript 版本兼容调优。
2. 它不会直接改变运行时行为，但说明当前项目更偏向“先保证开发过程稳定”。

4.3 构建脚本

文件：

• /Users/yovinchen/project/claude/scripts/build.ts
• /Users/yovinchen/Downloads/free-code-main/scripts/build.ts

结论：

1. 构建脚本主体保持一致。
2. 当前工程与参考项目的差异主要不在构建逻辑本身，而在于 package.json 对入口和开发脚本的包装方式。

5. 运行时恢复性差异

这一类差异是当前项目最值得单独识别的部分，因为它们明显是“为了跑起来”而不是“为了贴近参考”。

5.1 MACRO 兜底与注入

关键文件：

• /Users/yovinchen/project/claude/src/entrypoints/cli.tsx
• /Users/yovinchen/project/claude/src/main.tsx

观察到的现象：

1. 当前项目与参考项目在这两个入口文件上都存在差异。
2. 当前项目为了开发态运行，已经通过 package.json 的 dev 脚本显式注入 MACRO。
3. 当前项目的 src/main.tsx 中还保留了一层 MAIN_MACRO 兜底逻辑，而参考项目直接使用 MACRO.VERSION。

分析：

1. 这是非常明确的“开发态/恢复态兼容修复”。
2. 它解决的是参考项目默认依赖构建期注入、但恢复项目直接 bun run 时缺少注入的问题。
3. 这类修复提高了当前项目的可运行性，但也让入口行为不再完全等同于参考项目。

5.2 SDK 运行时补齐文件

当前项目独有文件：

• /Users/yovinchen/project/claude/src/entrypoints/sdk/controlTypes.js
• /Users/yovinchen/project/claude/src/entrypoints/sdk/coreTypes.generated.js
• /Users/yovinchen/project/claude/src/entrypoints/sdk/runtimeTypes.js
• /Users/yovinchen/project/claude/src/entrypoints/sdk/settingsTypes.generated.js
• /Users/yovinchen/project/claude/src/entrypoints/sdk/toolTypes.js

分析：

1. 参考项目只有对应的 .ts 类型/生成源码，而当前项目额外保留了 .js 文件。
2. 这些文件高概率是为了解决 Bun 运行时直接加载、模块解析或类型生成产物缺失的问题。
3. 它们属于典型“恢复补丁文件”。

风险：

1. 如果这些 .js 文件并非由统一生成流程产出，而是手工补入，那么后续源码变更后容易和 .ts 文件脱节。
2. 如果要长期维护，最好明确这些文件是“源码的一部分”还是“应由生成流程产出”。

5.3 其他当前项目独有源码

当前项目独有文件：

• /Users/yovinchen/project/claude/src/skills/bundled/verify/SKILL.md
• /Users/yovinchen/project/claude/src/skills/bundled/verify/examples/cli.md
• /Users/yovinchen/project/claude/src/skills/bundled/verify/examples/server.md
• /Users/yovinchen/project/claude/src/tools/TungstenTool/TungstenLiveMonitor.js
• /Users/yovinchen/project/claude/src/tools/TungstenTool/TungstenTool.js
• /Users/yovinchen/project/claude/src/tools/WorkflowTool/constants.js
• /Users/yovinchen/project/claude/src/types/connectorText.js

分析：

1. 这批文件同样更像运行时补齐或恢复期追加文件，而不是参考项目原始快照的一部分。
2. 其中 .js 文件的存在说明当前项目对“直接运行”做过较强适配。
3. verify 技能目录属于额外内置资源，偏离参考项目，但不一定是负面差异。

6. 同名源码文件差异分布

当前与参考项目存在内容差异的主要文件区域包括：

• src/main.tsx
• src/entrypoints/cli.tsx
• src/entrypoints/init.ts
• src/commands.ts
• src/commands/release-notes/release-notes.ts
• src/commands/ultraplan.tsx
• src/components/ConsoleOAuthFlow.tsx
• src/components/LogoV2/*
• src/components/StructuredDiff/colorDiff.ts
• src/constants/*
• src/hooks/useApiKeyVerification.ts
• src/screens/REPL.tsx
• src/services/analytics/*
• src/services/api/client.ts
• src/services/mcp/client.ts
• src/services/oauth/*
• src/services/voice.ts
• src/skills/bundled/claudeInChrome.ts
• src/skills/bundled/verifyContent.ts
• src/utils/auth.ts
• src/utils/claudeInChrome/*
• src/utils/config.ts
• src/utils/logoV2Utils.ts
• src/utils/model/*
• src/utils/modifiers.ts
• src/utils/releaseNotes.ts
• src/utils/ripgrep.ts
• src/utils/telemetry/*
• src/utils/theme.ts

分析：

1. 差异覆盖面很广，不像单点修复，更像恢复过程中发生过多轮替换、补抄和本地修订。
2. 受影响的区域里，很多都属于“用户可感知行为”或“外部集成逻辑”，比如认证、OAuth、模型选择、遥测、CLI 启动参数、UI 展示。
3. 这意味着当前项目虽然已经可运行，但和参考项目在行为层面未必完全一致。

7. 文档、资源和仓库管理层差异

7.1 当前项目新增的仓库管理能力

当前项目比参考项目多出：

• .gitattributes
• 更严格的 .gitignore
• docs/

其中当前 .gitignore 比参考项目更偏向真实开发仓库，额外忽略了：

• .DS_Store
• .idea/
• .claude/
• cli.js.map
• *.log

分析：

1. 当前项目已经从“快照目录”转向“可持续维护仓库”。
2. 这是正向改动，但它说明当前项目的目标已经不只是还原参考仓库。

7.2 当前缺失的参考项目文档与资源

参考项目存在、当前项目没有纳入的内容：

• /Users/yovinchen/Downloads/free-code-main/CLAUDE.md
• /Users/yovinchen/Downloads/free-code-main/FEATURES.md
• /Users/yovinchen/Downloads/free-code-main/changes.md
• /Users/yovinchen/Downloads/free-code-main/assets/
• /Users/yovinchen/Downloads/free-code-main/install.sh
• /Users/yovinchen/Downloads/free-code-main/run.sh

分析：

1. 当前项目缺的更多是“说明性与辅助性内容”，而不是主干源码。
2. 如果目标是“恢复可运行 CLI”，这些缺失不是第一优先级。
3. 如果目标是“尽量贴近参考项目完整交付物”，这些内容应该补回或至少评估是否要保留。

8. 差异定性判断

8.1 明显合理的差异

这部分差异大概率是正确且有价值的：

1. package.json 中 dev 脚本注入 MACRO
2. tsconfig.json 增加 ignoreDeprecations
3. 增加 .gitignore、.gitattributes、docs/
4. 将当前仓库定位为可维护的 Git 项目

8.2 明显属于恢复补丁的差异

这部分差异很可能是为了跑起来而做的临时或兼容性补丁：

1. src/main.tsx 的 MAIN_MACRO 兜底
2. src/entrypoints/sdk/*.js
3. src/tools/TungstenTool/*.js
4. src/tools/WorkflowTool/constants.js
5. src/types/connectorText.js
6. scheduler 依赖补入

8.3 需要继续验证的差异

这部分差异可能带来行为偏移，建议后续重点回归：

1. src/main.tsx
2. src/entrypoints/cli.tsx
3. src/services/oauth/*
4. src/services/api/client.ts
5. src/services/mcp/client.ts
6. src/utils/model/*
7. src/services/analytics/*
8. src/components/LogoV2/*
9. src/commands.ts 与 src/commands/ultraplan.tsx

原因：

1. 这些区域要么直接影响 CLI 主流程，要么影响鉴权/模型/遥测/展示逻辑。
2. 即使项目现在能跑，也不代表与参考项目完全同构。

9. 建议的后续动作

9.1 如果目标是“继续可用优先”

建议：

1. 保留当前 MACRO 注入方案。
2. 继续把 .js 补丁文件当作运行时兼容层管理。
3. 用当前仓库作为主维护仓库，不强求逐字对齐参考项目。

9.2 如果目标是“尽量收敛到参考项目”

建议：

1. 逐步审计 src/main.tsx、src/entrypoints/cli.tsx 与 package.json。
2. 确认 src/entrypoints/sdk/*.js 等补丁文件是否可以通过生成流程替代。
3. 评估是否恢复 claude-source、build:dev、build:dev:full。
4. 视需求补回 assets/、CLAUDE.md、FEATURES.md、changes.md、install.sh、run.sh。

9.3 如果目标是“做正式恢复基线”

建议：

1. 把当前差异分成：
   • 必要修复
   • 兼容补丁
   • 尚未验证的行为偏移
2. 为主链路建立最少一轮验证：
   • bun run dev -- --help
   • bun run dev -- --version
   • bun run build
   • bun run compile
3. 针对鉴权、模型选择、OAuth、MCP 连接、遥测开关做专项回归。

10. 最终结论

当前项目已经不是参考项目的简单副本，而是一个“参考快照基础上恢复成功、可直接运行、带本地修补层”的工程化版本。

可以用一句话概括：

/Users/yovinchen/project/claude 的主要价值在于“已经能跑并且适合继续维护”，而 /Users/yovinchen/Downloads/free-code-main 的主要价值在于“作为参考基线和资源来源”。

如果下一步要继续治理代码，最合理的策略不是盲目回滚当前差异，而是先把差异分类，再决定哪些保留、哪些收敛、哪些补测试。