yovinchen/openclaude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
openclaude/docs/free-code-main-diff-analysis.md
YoVinchen 5af8acb2bb Checkpoint the full local bridge and audit work before telemetry removal 
You asked for all local code to be committed before the broader telemetry-removal pass. This commit snapshots the current bridge/session ingress changes together with the local audit documents so the next cleanup can proceed from a stable rollback point.

Constraint: Preserve the exact local worktree state before the telemetry-removal refactor begins
Constraint: Avoid mixing this baseline snapshot with the upcoming telemetry deletions
Rejected: Fold these staged changes into the telemetry-removal commit | Would blur the before/after boundary and make rollback harder
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Treat this commit as the pre-removal checkpoint when reviewing later telemetry cleanup diffs
Tested: Not run (baseline snapshot commit requested before the next cleanup pass)
Not-tested: Runtime, build, and typecheck for the staged bridge/session changes
2026-04-09 14:09:44 +08:00

367 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# `/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` 的主要价值在于“作为参考基线和资源来源”。
如果下一步要继续治理代码，最合理的策略不是盲目回滚当前差异，而是先把差异分类，再决定哪些保留、哪些收敛、哪些补测试。
Reference in New Issue View Git Blame Copy Permalink