源于一个 59.8 MB 的 JavaScript 源映射文件(Source Map)
cli.js.map
npm install -g @sobird/claude-code进入到你的项目目录并运行 sobird
- Node.js 18+ 请自行安装
- Bun 全局安装
npm i -g bun
# 克隆仓库
git clone https://github.com/sobird/claude-code.git
# 进入仓库目录
cd claude-code
# 安装依赖
bun install# 在终端运行(基于当前项目) claude code
bun run dev# 生产环境构建
bun run build
# 在本项目目录运行构建后的版本
node dist/cli.js
# 或者 链接到本机全局命令 sobird,使用sobird命令运行任意项目 (可选)
npm link升级到新的上游版本时,按 carve → inventory → align → extract → probe → verify 的顺序运行 scripts/upgrade/cli.ts 的子命令,前一步的产物作为后一步的输入:
# 0. (仅 2.1.113+ 原生发布)从 Bun 单文件可执行中抽出内嵌 JS 模块图
bun scripts/upgrade/cli.ts carve --binary <native/claude> --out <carved.js>
# 1. 盘点 bundle:命令、环境变量、CLI 参数与字符串
bun scripts/upgrade/cli.ts inventory --bundle <upstream/cli.js> --out <inventory.json>
# 2. 对比参考版与目标版的函数节点,生成对齐结果
bun scripts/upgrade/cli.ts align --reference <2.1.88/cli.js> --target <2.1.89/cli.js> --out <align-dir>
# 3. 从变更节点中抽取待移植的字符串候选
bun scripts/upgrade/cli.ts extract --align <align-dir/align.json> --target <2.1.89/cli.js> --out <candidates-dir>
# 4. 用场景脚本探测运行时行为
bun scripts/upgrade/cli.ts probe --target <2.1.89/cli.js> --scenario <scenario.json> --out <trace.json>
# 5. 对拍源码与目标 bundle,校验台账并输出报告
bun scripts/upgrade/cli.ts verify --target <2.1.89/cli.js> --reference ./cli.js --src src --status docs/upgrade/2.1.89/status.json --out <report-dir>自 2.1.113 起 npm 包不再发布 cli.js:包是一个安装桩,真正的产物是平台原生二进制(Bun 单文件可执行)。carve 把所有带 // @bun @bytecode + release banner 的内嵌模块源码按图顺序拼成伪 bundle,后续步骤都接受它作为 target;但它的命令/字符串盘点会受属性顺序影响,只能当近似基线。
其余五个步骤里,inventory 与 align 建立差异基线(align 对 changed 候选按字符串字面量重叠 + 相对位置打分配对),extract 与 probe 收集待移植的静态字符串和运行时证据,verify 最终核对所有台账条目是否处于终态并生成 report.md / report.json。
交叉验证与收尾有五组辅助子命令,补齐 inventory/align 看不到的盲区:
# 官方 release 说明:下载并解析顶层条目(releaseItems 覆盖率用)
bun scripts/upgrade/cli.ts releasenotes --version v2.1.91 --out <work/release-notes-2.1.91.json>
# 结构化常量表:从 bundle 锚点抽字面量表,与参考版或 src 导出对拍
# --anchor 是属性名(如允许表里的 "get-date"),--whole 取包含该属性的整张表
bun scripts/upgrade/cli.ts table --bundle <target/cli.js> --anchor get-date --whole --out <work/table-target.json>
bun scripts/upgrade/cli.ts table --bundle <target/cli.js> --baseline <work/table-ref.json> --anchor get-date --whole --out <work/table-diff.json>
bun scripts/upgrade/cli.ts table --bundle <target/cli.js> --anchor get-date --whole \
--src src/tools/PowerShellTool/readOnlyValidation.ts#CMDLET_ALLOWLIST --out <work/table-src.json>
# 字符串分诊:输入是两份 inventory.json,把新增字符串切成 inSrc / releaseNotes / noise / unclassified
bun scripts/upgrade/cli.ts strings --target-inventory <target-inventory.json> --reference-inventory <ref-inventory.json> \
--src src --release-notes <work/release-notes-2.1.91.json> --out <work/strings-2.1.91>
# 证据刷新:校验 status.json 的 bundle 偏移,失效的按字符串重定位
bun scripts/upgrade/cli.ts refresh-evidence --target <target/cli.js> --status docs/upgrade/2.1.91/status.json --in-place
# 基线门禁:在 --ref 的临时 worktree 跑同一个门禁,与工作区做多集差分
bun scripts/upgrade/cli.ts gates --ref HEAD --repo-root . --out <work/gates> --fail-on-newgates 会归一化行/列、根路径、耗时、依赖顺序与 lint 代码框,只报告真正新增的发现;verify 只证明台账闭合,不证明行为等价。
想「改一个组件立刻看到效果」,用这个 harness:它把目标界面渲染进终端,bun --watch 监视到文件改动就重启进程重画。
bun run dev:ui编辑 scripts/ui-harness.tsx 里 Demo() 返回的组件即可切换预览对象,保存后自动重载,Ctrl+C 退出。真实界面一般需要 app 的 provider,harness 已按 tests/testing/ink.tsx 包好 AppStateProvider + KeybindingSetup(render 另加 ThemeProvider)。
说明:全屏 TUI 没法真正热替换(Ink 的 reconciler 持有终端状态,中途换树会错位),所以这里的「实时」是整进程重启;harness 在退出信号里先 unmount(),让 Ink 复原 raw mode / 光标,避免重启之间把终端弄乱。
打开vscode运行和调试面板,选择⚡️ Attach to claude code,点击开始调试(F5)。
按下 command + shift + p,输入 Debug: JavaScript Debug Terminal,回车。
在JavaScript Debug Terminal终端面板下输入:
node dist/cli.js上面的 attach 对应到现成脚本,分别断在源码和构建产物:
bun run debug # bun --inspect-brk,断在 src/**.ts(x)
bun run debug:dist # node --inspect-brk dist/cli.js,配合 cli.js.map运行后在 Chrome 的 chrome://inspect 或 VS Code 里 attach。
以调试模式启动(等价于 bun run dev 加 --debug):
bun run dev:log日志写入 ~/.claude/debug/<sessionId>.txt,并维护一个 latest 软链便于 tail:
tail -f ~/.claude/debug/latest常见开关:
--debug=<filter>:按模块包含/排除,例如--debug=ink,render、--debug=!1p,!file--debug-to-stderr(-d2e):日志同时打到 stderr--debug-file <path>:写到指定文件CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose:连带输出更啰嗦的诊断(默认debug)
会话中途也可以运行 /debug 开启日志并回读。
把整段 TUI 录成 asciicast v2,可用 asciinema 回放。录制器仅在 USER_TYPE=ant 且 CLAUDE_CODE_TERMINAL_RECORDING=1 时启用,脚本已替你设好这两个变量:
bun run dev:record录制文件落在 ~/.claude/projects/<sanitized-cwd>/<sessionId>-<timestamp>.cast:
asciinema play ~/.claude/projects/<...>/<sessionId>-*.castCLI 的界面由自定义的 Ink renderer 渲染,默认在 React DevTools 里是看不到的。用独立的 React DevTools 应用即可查看其组件树、props/hooks,并随交互实时刷新。
前置条件:
- 全局安装独立前端应用(自带 Electron,会打开一个窗口并监听
8097端口):npm i -g react-devtools
- 后端依赖
react-devtools-core已在仓库的devDependencies中,无需额外安装。
使用步骤:
- 终端 A 启动前端:
react-devtools - 终端 B 以开发模式启动 CLI:
bun run dev(Bun 默认NODE_ENV=development,会自动加载src/ink/devtools.ts) - 在 DevTools 窗口顶部把 renderer 切到
ink,即可看到组件树并实时刷新。
说明:
- 仅在开发模式生效:
src/ink/reconciler.ts在NODE_ENV === 'development'下动态引入src/ink/devtools.ts,生产构建不会加载。 react-devtools-core的后端是按浏览器环境写的,该模块会把self/window别名到globalThis(对整个进程生效),再依次调用initialize()、connectToDevTools()。- 若
react-devtools报Electron failed to install correctly,说明 Electron 二进制没下载成功;设置镜像ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/后重装,或删除node_modules/electron再重装。
本仓库仅供个人学习、研究、交流和参考使用,请勿将其用于任何商业活动