JCode Onboarding 沙箱完全指南用 JCODE_HOME 与 JCODE_RUNTIME_DIR 隔离首次引导状态安全反复迭代【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode本文围绕 JCode 仓库中的 onboarding 沙箱方案 展开讲解如何在不触碰真实认证状态的前提下反复演练、测试与回归「首次使用引导onboarding」流程。读完本文你将掌握scripts/onboarding_sandbox.sh的全部命令用法、JCODE_HOME/JCODE_RUNTIME_DIR两个环境变量的重定向原理、用真实登录数据做导入演练的技巧以及可复用本地认证 fixture 与无头截图生成的完整工作流。为什么需要 onboarding 沙箱JCode 的 onboarding 流程是一套「有状态」的首次引导它要完成 provider 登录、检测并导入已有的外部登录Codex / Claude / Gemini / Copilot / Cursor / OpenCode / pi 等、续接历史会话、展示新会话建议卡片等步骤。这些状态默认落在真实用户目录~/.jcode、真实运行时 socket 目录和真实的应用配置中。如果直接在本机反复跑 onboarding会产生两个问题污染真实状态每次试跑都会读写真实的登录凭据、信任决策与配置文件一旦引导逻辑有 bug可能破坏开发者的正常使用环境无法复现「全新机器」场景真实环境里早已存在的登录状态和已信任的外部认证源会让「首次运行」分支如外部登录导入提示根本无法被触达也就无法测试与验证。为此仓库提供了scripts/onboarding_sandbox.sh用独立沙箱目录承载 jcode 的全部状态使每次迭代都从「干净的首次运行」开始随时可一键重建。核心原理两个环境变量的状态重定向沙箱的隔离能力完全建立在两个环境变量之上onboarding_sandbox.sh 中对它们进行了明确布局环境变量默认指向作用JCODE_HOME~/.jcode重定向 jcode 自有状态如~/.jcode、应用配置JCODE_HOME/config/jcode以及外部认证/会话查找根目录JCODE_RUNTIME_DIR系统临时目录重定向 socket 等一次性运行时文件沙箱脚本会为每个沙箱构建如下目录结构scratch_root/onboarding/sandbox_name/ ├── home/ # 作为 JCODE_HOME 使用 └── runtime/ # 作为 JCODE_RUNTIME_DIR 使用其中scratch_root默认是$HOME/.jcode/scratch可用JCODE_SCRATCH_DIR覆盖见 onboarding_sandbox.sh。外部认证与转录的查找重定向当设置了JCODE_HOME时jcode 会把每一个外部凭据与转录的查找路径解析到$JCODE_HOME/external/与 $HOME 相同的相对路径。这一点在 crates/jcode-base/src/storage/tests.rs 中有直接的单测证据user_home_path(.codex/auth.json)在设置了JCODE_HOME后解析为$JCODE_HOME/external/.codex/auth.json同一个测试文件还验证了应用配置目录在设置了JCODE_HOME时解析为$JCODE_HOME/config/jcodecrates/jcode-base/src/storage/tests.rs。这样设计的好处是onboarding 的「导入外部登录」逻辑本身无需任何改动——它只是按照既有的user_home_path规则去external/目录下找文件。沙箱只需要往这个目录里种入文件副本检测与导入行为就和一台装有这些工具的全新机器完全一致。外部认证信任决策存进沙箱配置外部认证的信任决策例如是否信任某个路径上的 Claude / Codex / Copilot 凭据同样被写入沙箱配置JCODE_HOME/config/jcode之下而非真实配置。因此一个全新沙箱默认没有任何已信任的外部认证导入正好对应真实用户的首次运行状态。相关信任判定逻辑可参见 crates/jcode-base/src/auth/claude.rs 与 crates/jcode-base/src/auth/codex.rs 中的has_unconsented_external_auth/trust_external_auth_source实现。快速开始一行命令进入干净沙箱scripts/onboarding_sandbox.sh freshfresh等价于先reset删除整个沙箱再在沙箱内启动 jcode见 onboarding_sandbox.sh。它给你的是一次干净、完全隔离的 jcode 启动适合立刻走一遍 onboarding 主流程。脚本内部在启动 jcode 时还会做两件关键的事清除从父进程继承的JCODE_CLIENT_SELFDEV_MODE、JCODE_SELFDEV、JCODE_CANARY让沙箱行为与真实独立安装一致onboarding_sandbox.sh默认追加--no-selfdev避免因为在仓库内启动而自动加入共享 self-dev 服务器、跳过本地首次运行行为如需共享服务器可设JCODE_SANDBOX_SELFDEV1onboarding_sandbox.sh。用你的真实登录做导入演练干净的沙箱是完全隔离的所以 onboarding 的「导入既有登录」步骤一开始没有东西可导入。为了演练「导入」与「续接历史会话」这两个步骤可以把真实凭据和转录文件的副本种进沙箱# 复制真实外部登录Codex/Claude/Gemini/Copilot/Cursor/OpenCode/pi scripts/onboarding_sandbox.sh seed-real-logins # 同时复制真实的 Codex/Claude 转录让续接会话步骤有真实历史可恢复 scripts/onboarding_sandbox.sh seed-real-logins --with-transcripts # 或者一步到位重置沙箱 → 种入真实登录 → 启动 jcode scripts/onboarding_sandbox.sh fresh-real --with-transcriptsseed 了哪些文件从 onboarding_sandbox.sh 的实现可以看到脚本会按$HOME相对路径逐项复制以下认证/凭据文件到$JCODE_HOME/external/下.codex/auth.jsonCodex.claude/.credentials.json、.claude.jsonClaude.local/share/opencode/auth.jsonOpenCode.pi/agent/auth.jsonpi.gemini/oauth_creds.jsonGemini.config/github-copilot/hosts.json、.config/github-copilot/apps.jsonCopilot.cursor/auth.json、.config/cursor/auth.json、.config/Cursor/User/globalStorage/state.vscdbCursor多个候选路径以及两个转录目录--with-transcripts时.codex/sessionsCodex 会话.claude/projectsClaude 项目/会话安全模型复制而非移动seed-real-logins使用的是副本cp -a不是符号链接——这是有意的设计jcode 会拒绝符号链接形式的外部认证文件对应的单测见 crates/jcode-base/src/storage/tests.rs 的validate_external_auth_file_rejects_symlink。复制完成后脚本会立即chmod -R go-rwx收紧external/目录权限。你的原始$HOME文件永远不会被移动、重写或删除沙箱保持纯本地。种入完成后启动沙箱走 onboardingscripts/onboarding_sandbox.sh jcode它会像一台装有这些工具的全新机器一样检测并逐一提供真实登录的导入选项。注意这些副本包含真实的 token会一直存留到reset或purge-external。status命令会在检测到external/存在时给出醒目警告。fresh-real在退出时会自动清除这些副本除非设置JCODE_ONBOARDING_KEEP_EXTERNAL1onboarding_sandbox.sh。常用命令总览命令作用env打印沙箱的环境变量导出JCODE_HOME/JCODE_RUNTIME_DIRstatus显示沙箱路径与当前内容并在含真实凭据副本时告警reset彻底删除沙箱fresh重置后启动干净的 jcodeshell打开带沙箱环境变量的干净 shelljcode [args...]在沙箱内运行任意 jcode 命令auth-status在沙箱内运行jcode auth statuslogin provider在沙箱内运行jcode --provider provider login ...不影响正常 jcode 配置seed-real-logins [--with-transcripts\|--transcripts-only]种入真实外部登录及转录副本fresh-real [--with-transcripts]重置 → 种入真实登录 → 启动 jcodepurge-external仅删除已复制的真实凭据/转录fixture-list / fixture-save / fixture-load / fixture-run本地认证 fixture 的列表、保存、加载、加载后执行典型用法示例# 查看确切的环境变量与沙箱路径 scripts/onboarding_sandbox.sh env scripts/onboarding_sandbox.sh status # 从空白 onboarding 状态重新开始 scripts/onboarding_sandbox.sh reset scripts/onboarding_sandbox.sh fresh # 在不触碰正常 jcode 配置的情况下登录某个 provider scripts/onboarding_sandbox.sh login openai scripts/onboarding_sandbox.sh login claude scripts/onboarding_sandbox.sh auth-status # 在沙箱内运行任意 jcode 命令 scripts/onboarding_sandbox.sh jcode auth status scripts/onboarding_sandbox.sh jcode pair脚本还支持用JCODE_ONBOARDING_SANDBOX命名多套互不干扰的沙箱默认名为default名称必须匹配^[A-Za-z0-9][A-Za-z0-9._-]*$且不能是./..onboarding_sandbox.sh。可复用的本地认证 fixture对于反复进行的登录测试不要每次重新走一遍浏览器登录——把沙箱在某个「有趣状态」典型的已登录 OpenAI 用户、token 过期状态、外部认证导入待批准状态等下的JCODE_HOME存成本地 fixture。fixture 存储默认位于.tmp/auth-fixtures这是刻意的本地开发状态目录。fixture 可能包含真实的 OAuth token 或 API key 引用切勿提交或分享。推荐工作流一次性建立真实登录态之后快速复用# 一次性设置一个真实的已登录状态 scripts/onboarding_sandbox.sh reset scripts/onboarding_sandbox.sh login openai scripts/onboarding_sandbox.sh auth-status scripts/onboarding_sandbox.sh fixture-save normal-openai # 之后的快速循环 scripts/onboarding_sandbox.sh fixture-load normal-openai scripts/onboarding_sandbox.sh auth-status scripts/onboarding_sandbox.sh jcode auth-test --provider openai也可以加载 fixture 后直接执行一条命令scripts/onboarding_sandbox.sh fixture-run normal-openai -- auth-test --provider openai --no-smoke底层 fixture 助手fixture 机制由 scripts/auth_fixture.sh 独立实现onboarding_sandbox.sh通过run_auth_fixture转发onboarding_sandbox.sh。其命令包括scripts/auth_fixture.sh list # 列出已保存的 fixture scripts/auth_fixture.sh save normal-openai # 把当前沙箱 JCODE_HOME 存为 fixture scripts/auth_fixture.sh load normal-openai # 用 fixture 替换沙箱 JCODE_HOME scripts/auth_fixture.sh run normal-openai -- auth status # 加载后执行命令 scripts/auth_fixture.sh path [name] # 打印 fixture 根目录或某个 fixture 路径 scripts/auth_fixture.sh delete name # 删除一个 fixture scripts/auth_fixture.sh reset-sandbox # 仅清空当前沙箱 JCODE_HOME保存时会在 fixture 下写入metadata.txt记录name、saved_at、sandbox_name、source_jcode_home并明确标注「May contain real local auth tokens. Do not commit or share.」scripts/auth_fixture.sh。有用的环境覆盖环境变量作用JCODE_ONBOARDING_SANDBOX选择接收 fixture 的沙箱名默认defaultJCODE_ONBOARDING_DIR指定显式的沙箱目录JCODE_AUTH_FIXTURE_DIR把 fixture 存储放到仓库之外例如~/.local/share/jcode-auth-fixturesJCODE_SCRATCH_DIR覆盖沙箱父目录默认$HOME/.jcode/scratch建议的 fixture 命名约定normal-openai、normal-claude、expired-openai、api-key-openrouter、external-opencode-approved。移动端 onboarding 模拟器仓库还提供了一个可重置的无头移动端模拟器内置预定义 onboarding 场景用于迭代移动端引导 UX由 iOS 侧的JCodeMobile相关实现支撑# 后台启动模拟器默认场景 onboarding scripts/onboarding_sandbox.sh mobile-start onboarding # 检查状态 scripts/onboarding_sandbox.sh mobile-status scripts/onboarding_sandbox.sh mobile-state scripts/onboarding_sandbox.sh mobile-log # 重置回场景起点 scripts/onboarding_sandbox.sh mobile-reset当前支持的场景onboarding首次引导pairing_ready配对就绪connected_chat已连接会话无头截图生成导入登录的成功引导序列scripts/capture_onboarding.sh可以不启动终端、不读取真实凭据地生成「成功导入登录」的 onboarding 截图序列scripts/capture_onboarding.sh # 或指定输出目录 scripts/capture_onboarding.sh ~/onboarding-screenshots其工作原理见 capture_onboarding.sh设置JCODE_ONBOARDING_SCREENSHOT_DIR后运行cargo test -p jcode-tui --lib onboarding_import_happy_path_images -- --ignored --nocapture。该测试把线上应用使用的同一套OnboardingFlow阶段与 ratatui widget 树渲染到离屏的TestBackend对应测试位于 crates/jcode-tui/src/tui/app/tests/onboarding_golden.rs。输出为 SVG若安装了rsvg-convert会同时生成 PNG。onboarding_graph.rs中的每个静止状态resting state都会得到渲染OpenAI 登录提示、已检测登录汇总含选择模式与遥测子页、导入进度卡片、恢复与失败界面、legacy 续接提示以及完整应用帧起始选择器、新会话建议、已接受的建议评审轮次。状态机本身定义在 crates/jcode-tui/src/tui/app/onboarding_graph.rs其中 12 个NodeId节点、显式声明的EdgeId转移以及结构不变量检查如every_failure_node_reaches_a_settled_state_quickly、the_happy_path_stays_short保证了引导图的可验证性。为什么这样更安全一个全新的沙箱意味着不复用任何真实 jcode 配置文件不复用任何真实运行时 socket不复用任何此前已信任的外部认证来源一次reset即可整体销毁使用 fixture 时沙箱与正常 jcode 状态依然是隔离的只是加载的 fixture 可能刻意包含来自更早沙箱登录复制的认证状态。此外脚本的reset自带双重保护拒绝删除/、$HOME、仓库根目录等危险路径对自定义沙箱目录要求存在.jcode-onboarding-sandbox标记文件否则拒绝删除onboarding_sandbox.sh。所有沙箱目录、JCODE_HOME、运行时目录均以700权限创建外部凭据副本以go-rwx收紧marker 文件为600onboarding_sandbox.sh。推荐的迭代工作流紧耦合的 onboarding 迭代循环scripts/onboarding_sandbox.sh resetscripts/onboarding_sandbox.sh fresh走一遍 onboarding 流程调整代码重复如果专门在迭代移动端 onboarding UX保持模拟器运行在每轮之间使用mobile-reset。注意事项沙箱的设计目标是隔离jcode 自有状态与受信任的外部导入状态。如果你后续想要显式测试来自外部工具的「导入/复用」流程请有意为之并将其视为与首次运行 onboarding 相互独立的测试用例——不要混在同一轮迭代里。延伸阅读沙箱主脚本scripts/onboarding_sandbox.shfixture 底层助手scripts/auth_fixture.sh无头截图脚本scripts/capture_onboarding.sh状态重定向与外部文件校验的单测crates/jcode-base/src/storage/tests.rsonboarding 状态机定义crates/jcode-tui/src/tui/app/onboarding_graph.rs外部认证信任判定crates/jcode-base/src/auth/claude.rs、crates/jcode-base/src/auth/codex.rs【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考