Craft Agents 桌面端 0.2.30 发布详解Diff 查看器、Windows Git Bash 配置与跨平台工程化加固【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss本文基于 Craft Agents 开源仓库中的版本发布说明 0.2.30.md 撰写并结合仓库源码逐项剖析该版本引入的 Diff 查看器交互、Windows Git Bash 检测向导、应用菜单体系、跨平台路径处理、构建系统现代化与会话持久化可靠性改造。读者读完可以完整掌握这些能力的操作方式、配置持久化机制以及背后可复用的工程实践与对应源码位置。Craft Agents 0.2.30 是桌面客户端在「代码审查体验」「Windows 平台支持」「跨平台健壮性」三个维度上的一次集中升级。它一方面把 diff 查看从简单展示升级为带视图切换、统计信息与偏好持久化的完整工具另一方面针对 Windows 用户补齐了 Git Bash 的自动探测与手动配置流程同时借助 ESLint 规则与构建脚本 TypeScript 化把工程底座打磨得更稳。Diff 查看器可控、可统计、可持久化的审阅体验0.2.30 为 diff 查看新增了一套完整的控制栏覆盖三种能力Split / Unified 视图切换在左右分栏split与上下堆叠unified两种布局之间一键切换背景高亮开关可按需关闭变更行的背景高亮减轻长时间审阅的视觉负担内联统计在控制栏直接显示-删除数 新增数无需数行即可感知本次改动规模设置持久化上述偏好写入preferences.json取代旧的 localStorage 方案重启后保持。控制栏的组件化实现控制栏由 DiffViewerControls.tsx 实现组件接收additions、deletions、diffStyle、disableBackground及对应的变更回调DiffViewerControls additions{additions} deletions{deletions} diffStyle{diffStyle} // unified | split onDiffStyleChange{(style) {...}} disableBackground{disableBackground} onBackgroundChange{(disabled) {...}} /交互细节值得注意视图切换按钮展示的是「将要切换到的模式」图标当前为 unified 时显示 split 图标反之亦然并通过aria-label与title提供无障碍与悬浮提示统计区以-Xtext-destructive红色系与Ytext-success绿色系的等宽字体呈现风格对齐 diffs.com 的opacity-60 hover:opacity-100控制栏。按钮还显式设置了WebkitAppRegion: no-drag确保在 Electron 的可拖拽标题栏区域依然可点击。底层 Diff 引擎与主题接入核心渲染组件 ShikiDiffViewer.tsx 基于pierre/diffs构建通过parseDiffFromFile(oldFile, newFile)解析出FileDiffMetadata并支持 Shiki 语法高亮与 light/dark 双主题。其中统计数字正是由getDiffStats()逐 hunk 累加additionCount/deletionCount得到的。在 Electron 渲染进程侧ShikiDiffViewer.tsx 是对该基础组件的封装它通过useTheme()读取应用的明暗模式与 Shiki 主题如 dracula、nord透传给底层组件未配置 Shiki 主题时则回退到带透明背景的craft-dark/craft-light主题以配合 CSS 变量换肤体系。preferences.json 持久化链路版本说明中「Persisted settings via preferences.json (replaces localStorage)」的落地位置有三处类型定义preferences.ts 中定义了DiffViewerPreferencesexport interface DiffViewerPreferences { /** Diff layout: unified (stacked) or split (side-by-side) */ diffStyle?: unified | split; /** Whether to disable background highlighting on changed lines */ disableBackground?: boolean; }它作为UserPreferences.diffViewer字段由updatePreferences()采用浅合并策略写入默认文件位于~/.craft-agent/preferences.jsonCONFIG_DIR由 paths.ts 定义。读写逻辑ChatDisplay.tsx 挂载时通过window.electronAPI.readPreferences()读取diffViewer字段注入组件状态用户切换视图或背景高亮后经handleDiffViewerSettingsChange合并回写若文件损坏无法解析则重建仅含diffViewer与updatedAt的新配置。这正是「替换 localStorage」的含义——本地偏好不再散落于渲染进程存储而是统一收敛到主进程管理的配置文件天然支持跨窗口同步与后续的配置查看/备份。Windows 专项Git Bash 检测与配置向导0.2.30 为 Windows 用户引入了完整的 Git Bash 引导流程自动探测常见安装路径、支持手动浏览自定义安装位置、并在引导阶段给出清晰指引。检测优先级与兜底策略主进程 IPC 处理器 system.ts 实现了gitbash.CHECK通道检测顺序如下平台判断非win32平台直接返回found: true不打扰其他系统用户已持久化路径若配置中已有gitBashPath且校验通过直接复用并写入CLAUDE_CODE_GIT_BASH_PATH环境变量若校验失败则清除该记录常见安装路径依次探测C:\Program Files\Git\bin\bash.exeC:\Program Files (x86)\Git\bin\bash.exe%LOCALAPPDATA%\Programs\Git\bin\bash.exe%PROGRAMFILES%\Git\bin\bash.exe系统 PATH 兜底执行where bash5 秒超时取第一条命中路径并要求路径中包含git且通过校验才采纳全部失败则删除环境变量并返回found: false触发引导 UI。检测结果通过CLAUDE_CODE_GIT_BASH_PATH注入 SDK 子进程——这一点在 storage.ts 的注释中明确说明是 Git Bash 与底层 Claude Code SDK 协同的关键桥梁。手动浏览与路径校验对应gitbash.BROWSE打开文件选择对话框默认定位C:\Program Files\Git\bin过滤器限定*.exe与gitbash.SET_PATH持久化用户指定路径两个通道实现位于 system.ts。路径合法性校验集中在 git-bash.ts三个核心函数isGitBashExecutablePath()正则/(?:^|[\\/])bash\.exe$/i同时接受 Windows 反斜杠与 POSIX 正斜杠写法validateGitBashPath()强制要求文件名是bash.exe且磁盘上真实存在、指向文件返回结构化的{ valid, error }错误信息如Path must point to bash.exe/File does not exist at the specified pathisUsableGitBashPath()无 UI 副作用的布尔包装供自动检测链路静默调用。配套测试 git-bash.test.ts 覆盖了不同分隔符的路径识别、非 bash 可执行文件拒绝、文件不存在拒绝与合法路径通过四类场景可直接作为该模块行为契约的参考。状态持久化setGitBashPath()/getGitBashPath()/clearGitBashPath()storage.ts将路径写入用户级配置文件使检测结果跨重启保留当持久化路径失效时自动清除并回退到自动探测流程。应用菜单体系macOS 原生菜单与统一 schema0.2.30 完善了应用菜单完整的 macOS 风格下拉菜单及子菜单覆盖标准编辑操作Undo/Redo/Cut/Copy/Paste/Select All、窗口控制Minimize/Maximize/New Window、视图控制Zoom In/Zoom Out/Reset Zoom并在开发构建中提供 Debug 子菜单。菜单的真正来源单一 schema菜单结构与快捷键并非散落在主进程代码中而是定义在共享 schema menu-schema.tsEDIT_MENU、VIEW_MENU、WINDOW_MENU、DEBUG_MENU分别声明各菜单项并同时携带role如undo、zoomIn交给 Electron 原生行为actionId关联渲染进程的动作注册表如view.toggleSidebar平台化的快捷键展示macOS 显示⌘ZWindows/Linux 显示CtrlZ对应 IPC 通道如RPC_CHANNELS.menu.ZOOM_IN所有 label 均为 i18n key如menu.edit由消费方在渲染/构建时调用t()解析避免模块级静态翻译导致的过期文案。平台差异处理主进程 menu.ts 的rebuildMenu()展示了明确的平台策略Windows / LinuxMenu.setApplicationMenu(null)完全隐藏原生菜单功能入口收拢到应用内的 Craft logo 下拉菜单macOS按 Apple 规范保留原生菜单栏并动态注入「检查更新 / 安装更新」项根据auto-update.ts的下载状态切换Debug 子菜单仅当!app.isPackaged || isDebugMode开发模式或--debug启动时追加 DevTools 切换等条目生产包默认不暴露。菜单项还显式设置registerAccelerator: false将快捷键交还给渲染进程的 Action Registry 统一处理避免主/渲染进程重复响应。跨平台健壮性ESLint 规则与路径处理重构规则层约束本次新增的 ESLint 规则集中体现了「把平台差异挡在编码阶段」的思路定义于 eslint-rules 并在 eslint.config.mjs 中接入 flat configno-hardcoded-path-separator.cjs拦截path.startsWith(dir /)这类硬编码分隔符的写法在 Windows 上会静默失效引导改用pathStartsWith()来自craft-agent/core/utils或 Node 的path.sepno-direct-platform-check.cjs约束平台判断的集中入口避免散落的process.platform win32no-hardcoded-z-index.cjs / no-nonstandard-shadows.cjs约束样式层级体系与阴影规范保证 UI 一致性另有no-localstorage.cjs从规则层面推动「偏好走配置文件而非 localStorage」——与本文第一部分的持久化改造形成呼应。路径与临时目录临时目录采用 OS 适配的临时路径如 Nodeos.tmpdir()派生替代硬编码/tmp等写法Monorepo 路径解析资源与构建产物路径改为相对仓库根的可移植解析配合 copy-assets.ts 将resources/整体复制到dist/resources/并设置可移植的setBundledAssetsDir根确保 docs、themes、permissions 等资源在 Windows 与 macOS 上解析一致。构建系统现代化从 Shell 脚本到 TypeScript0.2.30 将构建脚本从 shell 命令迁移到 TypeScript并拆分出 main、preload、renderer、resources 的独立构建步骤。当前 package.json 中的 scripts 即是该改造的延续形态bun run build:main # esbuild 打包主进程 → dist/main.cjs bun run build:preload # preload 脚本 → dist/bootstrap-preload.cjs bun run build:preload-toolbar bun run build:interceptor # 网络拦截器 bun run build:renderer # vite build bun run build:copy # bun scripts/copy-assets.ts bun run build # lint 以上全部 validate开发侧则使用vite devHMR 热更新提升迭代效率Windows 构建路径单独提供build:win/start:win跳过依赖.env的 OAuth 注入分支避免 shell 语法差异导致的失败。脚本拆分使主进程、preload、渲染层可独立增量构建也便于 CI 按需缓存。会话持久化异步队列与防过期写入版本说明强调会话持久化的三处改进——异步队列、处理代数计数器generation counter、并发操作健壮性——对应 persistence-queue.ts 的实现按会话串行化的防抖队列enqueue()以 500ms 防抖合并短时间内的连续持久化请求同一 session 的待写数据会被最新数据替换并重置计时器避免主线程被高频写入阻塞原子写入先写.tmp再rename覆盖进程中途崩溃只损坏临时文件、原session.jsonl保持完整Windows 上先unlink再rename以规避「目标存在时 rename 失败」的平台差异并发保护flush()会等待该 session 进行中的写入完成再启动新写入writeInProgress跟踪杜绝共享.tmp文件上的竞态外部元数据保护通过比对 header 签名getHeaderMetadataSignature识别「磁盘被外部修改」的场景队列写入只合并不覆盖外部变更如 watcher 编辑、其他实例改动可移植路径写入前将workspaceRootPath、workingDirectory等转换为可移植路径保证会话文件跨机器可读。UI 打磨本次对预览层做了统一收口所有预览浮层diff、代码、终端集中管理背景样式与进行中状态改善覆盖层组件架构使三种预览的视觉与交互保持一致。相关消费者组件可参见 ChatDisplay.tsx 中统一的 overlay 状态机overlayState统一管理 Input/Output/Activity 等覆盖层。Bug 修复Task 结果清理导致工具嵌套错误修复了任务结果清理阶段产生的工具调用嵌套错乱会话持久化竞态修复了并发持久化可能引发的写入竞态与上文队列串行化、原子写配套Monorepo 开发路径解析修复了开发环境下跨包路径解析错误保证 workspace 依赖craft-agent/*在开发与打包两种模式下都能正确加载。小结0.2.30 的价值在于「体验」与「地基」并重diff 查看器从被动展示进化为可配置、可记忆的生产力工具Windows 上的 Git Bash 引导把最容易卡住的「环境就绪」环节做成了自动探测 手动兜底 持久化的闭环而 ESLint 规则、TypeScript 构建脚本、异步持久化队列这些「看不见」的改造则为后续版本的多平台发布与并发稳定性提供了底座。对开发者而言这些模块DiffViewerControls.tsx、git-bash.ts、persistence-queue.ts、menu-schema.ts也是可直接借鉴的工程样例配置统一走preferences.json、平台差异用规则与工具函数收敛、写入用原子替换 队列防抖。【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考