claude-desktop-debian 工程治理指南AGENTS.md 中的补丁零改动契约、代码规范与构建分发架构【免费下载链接】claude-desktop-debianClaude Desktop for Linux项目地址: https://gitcode.com/GitHub_Trending/cl/claude-desktop-debian本文以 claude-desktop-debian 仓库根目录的 AGENTS.md 为主体系统讲解这个将 Anthropic 官方 Claude Desktop for Linux.deb重打包为 RPM、AppImage、Nix、AUR 等多种格式的项目其工程治理如何运转patch-zero补丁零改动契约如何约束对官方app.asar的每次改动active_patches编排数组与构建期 tripwire 如何守住契约代码风格与文档规范、CI/CD、APT/DNF 分发、版本管理与调试工作流又如何在源码层面落地。读完你将掌握该项目的协作规则与核心机制并能在修改scripts/patches/*.sh、scripts/launcher-common.sh或新增分发格式时快速对齐其约束与验证方法。项目定位重打包官方.deb而不是维护一个 forkAGENTS.md 的Project Overview一节开宗明义这个项目将Anthropic 官方 Claude Desktop for Linux.deb重打包成 Anthropic 不提供的格式RPM、AppImage、Nix、AUR并额外提供自己的.deb每一种格式外面都包一层带 Linux 环境修复的 launcherWayland 选择、GPU 崩溃恢复、--doctor诊断。自 v3.0.0 基于官方 Linux 包 rebase决策 D-002之后项目的核心契约是patch-zero官方app.asar默认以字节级原样发布任何补丁必须能针对官方字节证明自己是在弥补真实的 Linux 缺口否则默认裁决就是删除。这一方向的背景记录在 docs/decisions.md 的 D-002 中Anthropic 于 2026-06-30 通过 APT 仓库发布了第一方 Linux beta1.17377.1Electron 42.5.1官方构建原生解决了此前补丁套件存在的大部分问题tray SNI 竞态、无边框窗口、autoUpdater、native-binding stub、node-pty还提供了 Windows 重打包无法复现的能力KVM Cowork VM、Rust X11 输入注入、浏览器 native-messaging host。因此项目从重打包 Windows 安装包硬切换为重打包官方 Linux.deb并删除了所有冗余补丁回退路径是 git 历史与pre-cutover-windows-pipeline标签。从源码看这个契约直接落到了 scripts/patches/app-asar.sh 的active_patches数组上数组为空时构建直接跳过 extract/repack官方app.asar字节级原样发布见 patch_app_asar 的空数组分支。文档体系谁是事实来源AGENTS.md 是一份给 AI 工具遵循 agents.md 厂商中立标准快速参考的高杠杆规则文件。它明确声明不是所有规则的源头而是快速索引CONTRIBUTING.md —— 接受什么、什么该提交上游、子系统 owner、AI 署名政策docs/styleguides/bash_styleguide.md —— shell 脚本规范源自 YSAPTab 缩进、80 列、[[ ]]、不用set -e、不用evaldocs/styleguides/docs_styleguide.md ——docs/目录树的页面结构与反模式docs/index.md —— 全仓文档的唯一切入点SECURITY.md —— 漏洞报告以及什么在范围内、什么属于上游。文件头注释还规定了一个有趣的同步策略AGENTS.md 与 CLAUDE.md 在 H1 标题以下必须逐字节一致两者唯一有意的差异就是顶部那段 sync-policy 注释这样用 Claude Code 或任何其他 AI 工具的贡献者拿到的是同一套指令无需交叉对照。改其中一个就必须改另一个。docs/learnings沉淀踩坑考古AGENTS.md 花了大量篇幅介绍 docs/learnings/ 目录——这些是从调试和修复问题中获得的、光读代码看不出来的硬核知识是项目的考古层official-deb-rebase-verification.md —— 针对官方.deb逐字节验证的补丁必要性矩阵以及 rebase 依赖的安装布局事实process.resourcesPath辅助程序解析、硬编码的 OVMF/AAVMF 固件探测列表、按架构区分的依赖契约、SUID 记录等patching-minified-js.md —— 长期维护对上游反复重新压缩的 JS 的补丁套件的通用经验锚点选择、\wvs$标识符捕获陷阱、美化代码假阴性、幂等守卫、SHA-256 固定的假设验证配方packaging-permissions.md —— 严格 umask 下的 deb/rpm/AppImage 权限陷阱nix.md —— 官方 deb 的 Nix 派生式设计契约与 SRI 自动升级apt-worker-architecture.md —— Cloudflare Worker GitHub Releases 的 APT/DNF 二进制分发wayland-global-shortcuts-portal.md —— Quick Entry 快捷键在 GNOME Wayland 上为何只能聚焦式绑定、GlobalShortcutsPortal方案与三态CLAUDE_USE_WAYLANDconfig-wipe-guard.md —— 中毒缓存导致的配置清空问题以及 launcher 侧备份轮换backup_user_config这一 patch-zero-clean 的主修复以及 mcp-double-spawn.md、plugin-install.md、tray-rebuild-race.md、test-methodology-and-coverage.md、quit-cleanup-scope-fence.md、test-harness-electron-hooks.md、test-harness-ax-tree-walker.md、cowork-vm-daemon.md 等。主题已不再随当前版本发布的知识会移入 docs/archive/如 linux-topbar-shim.md、cowork-linux-handover.md带过时声明头但仍可作为诊断记录被检索到。代码风格安全、可预测的 bash项目所有 shell 脚本必须遵循 Bash Style Guide。关键点Tab 缩进行宽不超过 80 字符URL 与正则表达式例外条件判断用[[ ]]命令替换用$(...)字面量用单引号需要展开时用双引号变量名小写仅常量/导出用大写函数内必须用local避免set -e和eval。反模式每一条背后都是事故AGENTS.md 的 Anti-patterns 不是审美偏好每条都对应历史上真实踩过的坑反模式原因set -e与$(...)捕获和函数返回值交互恶劣项目历史上调试过足够多的静默退出才定下此结论。正确做法是显式检查状态cmd \|\| handle_erreval用数组组合 argvcmd ${args[]}。eval击败所有解析器是永久性的 SC2046 磁铁POSIX[ ... ]对未加引号的展开解析错误[[ ]]不会反引号不能干净嵌套且把补丁贴进 PR 评论时与 markdown 冲突硬编码工作目录构建期运行的脚本必须用$work_dir由build.sh设置。硬编码路径会静默破坏 AppImage 构建因为其运行目录布局与 deb/rpm 不同if cmd; then true; else false; fi式包装直接cmd即可退出码已经在那里往 baseline 文件里追加内容以压制shellcheck修复根本问题真误报才用带解释注释的# shellcheck disableSCXXXXLint 纪律推送前用shellcheck检查 shell 脚本、用actionlint检查 GitHub Actions 工作流。顺序是先修代码禁用指令是最后手段且必须附上解释为什么需要禁用也可以用/lint技能手动检查。从源码看这些风格已经在 scripts/_common.sh 等文件中严格执行——例如_resolve_asar里判断工具可用性时完全不用set -e而是显式if (( asar_probe_status ! 0 )) \|\| ...; then ... return 1; fi见 _resolve_asar。文档规范declarative 开头 症状式标题docs/styleguides/docs_styleguide.md 规定了docs/树的组织方式顶层平铺 小写 kebab-case文件名顺序信息放在 docs/index.md不放进文件名或数字前缀子目录只在主题超过约 5 页时出现learnings / testing / issue-triage / upstream-reports / styleguides 均由此产生每页开头先一句陈述句然后立刻是代码块或列表——不要 In this guide we will explore… 式开场白troubleshooting 的标题就是字面症状## Black screen on Fedora KDE under Wayland而不是## Troubles with Wayland因为搜索命中的是标题决策记录走 ADR 格式统一放在 docs/decisions.md不要在 how-to 页面里重新争论已定方向链接过去即可子系统深挖放 docs/learnings/比埋在 commit message 或补丁脚本注释里更好大量交叉链接每页链接 24 个其他页面。GitHub 工作流gh CLI、按 issue 编号建分支、AI 署名AGENTS.md 规定的协作流程所有 GitHub 交互使用ghCLI分支按 issue 编号命名fix/123-description或feature/123-descriptioncommit 与 PR 中用#123或Fixes #123引用 issue建 PR 后在对应 issue 下评论摘要与链接。调查旧 issue先看提出时的代码状态对较老的 issue先检查 issue 提出时的代码状态——可能已经修好了# 获取 issue 创建时间 gh issue view 123 --json createdAt # 找到 issue 创建之前最近的 commit git log --oneline --until2025-08-23T08:48:35Z -1 # 查看该时间点的文件内容 git show commit:path/to/file.sh # 搜索 issue 创建以来的相关改动 git log --oneline --after2025-08-23 -- path/to/file.sh # 查看可能修复了该 issue 的某个 commit git show commit这样能判断 issue 是否已被解决并能在回复中引用具体 commit。AI 署名政策PR 描述必须包含完整署名块用真实模型名如Claude Opus 4.5百分比诚实反映该次工作的贡献比例形成可审计的 AI 辅助开发记录--- Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude model-name noreplyanthropic.com XX% AI / YY% Human Claude: what AI did Human: what human didissue 和评论用简化署名Written by Claude model-name via Claude Codecommit 加Co-Authored-By: Claude claudeanthropic.comtrailer。贡献者致谢按时间顺序维护在 ACKNOWLEDGMENTS.md灵感项目 k3d3、emsi、leobuskin 排最前其后按合并/修复时间排序合并外部 PR、或直接采用了 issue 作者提供的具体修复/代码片段时都要更新该文件。操作压缩混淆的 JavaScript锚点、陷阱与正则纪律项目持续对上游反复重新压缩的主进程 JS 打补丁AGENTS.md 用一节专门约束这件事一律用正则修改源码 JS。补丁位于scripts/patches/*.shapp-asar.sh 是编排器显式的active_patches数组当前为quick-window.sh、org-plugins.sh、virtiofsd-probe.sh、cowork-bwrap.shconfig.sh被 source 但 parked/未接线。minified 与 beautified 间距不同模式必须两者兼容Minifiedoe.nativeTheme.on(updated,(){Beautifiedoe.nativeTheme.on(updated, () {需要分组或交替时sed 用-E扩展正则。动态提取变量名而不是硬编码。示例来自quick-window.sh# The minified Quick Entry window var, anchored on a stable literal quick_var$(grep -oP [$\w](?\.setAlwaysOnTop\(\s*!0\s*,\s*pop-up-menu\)) \ $index_js)处理可选空白例如(oe\.nativeTheme\.on\(\s*updated\s*,\s*\(\)\s*\s*\{)。为什么变量名会漂移补丁面对的是压缩后的变量/函数名它们随版本变化。自上游 1.19367.0 起主进程做了代码分割code-split.vite/build/index.js变成一个require()内容哈希的index.chunk-hash.js主 chunk 的桩因此补丁操作的是$main_js由app-asar.sh中的_resolve_main_js解析而不是直接操作index.js单个补丁甚至可以跨 chunk见cowork-bwrap.sh的 warm chunk。完整的锚点技艺与代码分割教训在 patching-minified-js.md。从源码看quick-window.sh 的实践比 AGENTS.md 的示例更进一步1.26832.0 换了压缩器后几乎所有字符串字面量都变成了反引号模板所以锚点必须写 quote class[]而不是裸双引号见该文件顶部的_QW_Q变量。同时锚点解析也从一个主文件演进为_resolve_anchor_file[app-asar.sh](https://link.gitcode.com/i/93b9626fbff04b06f2c5c96210f55cad#L174-L209)它拿完整锚点形状的 PCRE 去.vite/build目录里grep -rlPz 匹配并要求恰好命中一个文件——0 个或多个都算硬错误替代了旧的多 chunk 守卫避免静默错补。补丁编排patch-zero 契约的落地点scripts/patches/app-asar.sh 拥有 asar 补丁阶段AGENTS.md 明确了它的四件事active_patches数组是补丁接线的唯一入口。空数组 ⇒ 不 extract、不 repack官方app.asar字节级原样发布。当前数组见 app-asar.sh 第 48-54 行包含patch_quick_window、patch_org_plugins_path、patch_virtiofsd_probe、patch_cowork_bwrap、patch_tray_icon_env_overrideproductName 守卫如果上游productName不再是Claude构建直接失败——它不再影响WM_CLASS但 Electron 的 userData 路径~/.config/Claude以它为键launcher、doctor、文档都依赖这个位置上游 tripwireAU-1/MB-1构建直接 grep 原始 asarasar 内文件未压缩patch-zero 模式下也能检查若官方 bundle 不再包含managed_by_package_manager上游从apt_channel_pending改名而来表示 Linux 上应用内更新关闭、更新归包管理器管或menuBarEnabled:!0菜单栏默认开启构建失败。这取代了 v3.0.0 删除补丁后遗留的 per-patch WARNING——补丁没了上游翻转就得靠构建期硬失败来拦截Repack 不变量unpacked 文件集合从随包的app.asar.unpacked目录树推导repack 后必须完全一致折叠成单个--unpack花括号 glob否则上游原生辅助程序可能被静默内联或丢失。此外bwrap 备用 daemoncowork-vm-service.js故意放在resources/process.resourcesPathasar 之外child_process无法 exec asar 内部的脚本且放在app.asar.unpacked之外才能把上面的 repack 不变量钉在上游集合上。该文件仅在用户以COWORK_VM_BACKENDbwrap启动时生效。配置清空主修复在 launcher 侧而非补丁#768 的配置清空config wipe问题有一个重要裁决恢复逻辑放在 launcher而不是 asar 补丁。launcher-common.sh中的backup_user_config见 launcher-common.sh 第 766-810 行在每次启动前轮换claude_desktop_config.json与 Cowork 各 store 的离带备份保留 5 份仅在真实变化时轮换永不阻塞启动这是 patch-zero-clean 的主修复——它覆盖了 in-band 守卫覆盖不到的 corrupt-JSON / ENOENT / single-bad-entry Zod 三种清空模式。与之相对的config.sh虽然被硬化R1/R2/R3 恢复规则、lazy-clone 非粘性、CF-1 不复活约束但在相反意见审查后保持 parked 状态作为备用local-stores.sh则被整体删除其不能 JSON 解析规则漏掉了抛出异常的真实 loader。详见 config-wipe-guard.md。2.x frame-fix 为什么回不来了2.x 时代的 frame-fix wrapperframe-fix-wrapper.js拦截require(electron)已经删除——官方构建拥有自己的窗口行为。任何再次拦截 Electron API 的提案都必须过 D-002 的 patch-zero 关卡。搭建 build-reference从官方 .deb 提取并美化源码若build-reference/缺失或需要检查新版本的源码按以下流程从官方 Linux.deb提取并美化v3.0.0 rebase 后 Windows 安装包那条路已废弃。前置条件# 安装必要工具ar 来自 binutils sudo apt install binutils wget xz-utils zstd nodejs npm # 全局安装 asar 和 prettier或用 npx npm install -g electron/asar prettier第 1 步下载官方 .deb固定的版本、pool 路径和 SHA-256 都在 scripts/setup/official-deb.sh 的OFFICIAL_DEB_*变量里当前版本1.52386.6amd64/arm64 各带一个 SHA-256 pin。取固定的 amd64 构建mkdir -p build-reference cd build-reference # 读取当前 pin source ../scripts/setup/official-deb.sh 2/dev/null || true wget -O claude-desktop.deb \ https://downloads.claude.ai/claude-desktop/apt/stable/$OFFICIAL_DEB_POOL_AMD64 echo $OFFICIAL_DEB_SHA256_AMD64 claude-desktop.deb | sha256sum -c如果想查看 pool 里最新的条目可从 Packages 索引解析official-deb.sh的resolve_official_deb干的就是这件事curl -fsS https://downloads.claude.ai/claude-desktop/apt/stable/dists/stable/main/binary-amd64/Packages \ | awk -v RS /claude-desktop/ | grep -E ^(Version|Filename|SHA256):第 2 步提取 .deb不需要 dpkg——artar处理所有成员data 成员历史上既发过.tar.zst也发过.tar.xz用ar t确认ar t claude-desktop.deb # 列出成员 ar p claude-desktop.deb data.tar.xz | tar -J -x # 或 --zstd 处理 .tar.zst # 应用树落在 usr/lib/claude-desktop/ cp usr/lib/claude-desktop/resources/app.asar . cp -a usr/lib/claude-desktop/resources/app.asar.unpacked . # 可选hicolor 图标留作参考 cp -a usr/share/icons/hicolor tray-icons第 3 步解包 app.asarasar extract app.asar app-extracted第 4 步美化 JS 文件提取出的 JS 是压缩的用 prettier 使其可读。注意 1.19367.0 之后主进程代码分割index.js是极小的桩真正的代码在index.chunk-hash.js——glob 覆盖所有 chunk# 美化构建目录下所有 JS 文件 npx prettier --write app-extracted/.vite/build/*.js # 主进程 chunk 是最大的 .vite/build/*.jsindex.js 只是 require 它。 # 想只美化它就从桩里解析出来 main_chunk$(grep -oP require\(\./\Kindex\.chunk-[^]\.js(?\)) \ app-extracted/.vite/build/index.js) npx prettier --write app-extracted/.vite/build/$main_chunk第 5 步可选清理与最终结构rm -rf usr claude-desktop.deb rm -rf app.asar app.asar.unpacked # 只保留 app-extractedbuild-reference/ ├── app-extracted/ │ ├── .vite/ │ │ ├── build/ │ │ │ ├── index.js # 主进程入口桩 │ │ │ ├── index.chunk-hash.js # 主进程1.19367.0 代码分割 │ │ │ ├── mainWindow.js # 主窗口 preload │ │ │ ├── mainView.js # 主视图 preload │ │ │ └── ... │ │ └── renderer/ │ │ └── ... │ ├── node_modules/ │ │ └── ant/claude-native/ # Rust 原生绑定Linux 上真实存在 │ └── package.json └── tray-icons/ # 官方 hicolor 图标可选最后记住对美化输出验证过的模式作用到实际压缩字节上时要用空白容忍的形式。新增包格式或仓库的 CI 指南AGENTS.md 对给 RPM、Flatpak、Snap 之类新增分发格式或仓库给出了明确流程核心是避免在 CI 里反复迭代调试动手前先研究理解目标系统的约束——每种包格式有特定规则版本字符串格式如 RPM 的 Version 字段不能有连字符、必需元数据字段、签名要求与工具搜索现有 CI 实现——已有工作流会暴露必需 flags、环境设置与常见坑检查工具在非交互环境的行为——CI 没有 TTYGPG 需要--batch、--yes才能不提示运行。考虑并发多个 job 写同一分支会竞争——若 APT 与 DNF 仓库都推gh-pages加 job 依赖needs: [other-job]或 push 前git pull --rebase 重试循环外部进程也可能改分支——GitHub Pages 自动部署就会造成 push 冲突。测试完整流水线先在本地跑签名/打包命令合并前抓错新基建用test tag非发布 tag先验证完整 CI 流水线CI 成功后在干净系统上实际测试 README 里的安装命令验证最终用户体验。常见 CI 坑速查表问题解法GPG cannot open /dev/tty加--batchGPG File exists 错误加--yes覆盖push 被拒ref 已变push 前git pull --rebase带重试循环版本格式非法先研究目标格式的版本约束找不到签名 key确保签名步骤前已导入 key核对 key ID 输出CI/CD触发构建与产物清单触发构建、查看运行、下载产物全部走gh# 在分支上触发 CI gh workflow run CI --ref branch-name # 观察运行 gh run watch RUN_ID # 下载产物 gh run download RUN_ID -n artifact-name一个跨平台构建build.yml在ubuntu-latest上通过--arch输入同时产出全部产物host-vs-target 陷阱见下claude-desktop-unofficial_VERSION_amd64.deb/_arm64.deb—— Debian 包claude-desktop_1.16000.0-1_all.deb—— 过渡 apt 包amd64 腿产出把旧claude-desktop安装迁移到claude-desktop-unofficialclaude-desktop-unofficial-VERSION-1.x86_64.rpm/.aarch64.rpm—— RPM 包claude-desktop-unofficial-VERSION-amd64.AppImage/-arm64.AppImage—— AppImageCI 里附带.zsyncresult/—— Nix 构建输出symlink已 gitignore。其中有一个被 AGENTS.md 单独点名的教训类别host-vs-target 混淆。构建期运行的工具按uname -m取键产物则按--arch取键症状是跨架构腿上的Exec format error例如 Node.js 下载按 HOST 架构键控见 AGENTS.md 的 Common Gotchas。分发架构APT/DNF 走 Cloudflare Worker 直通APT 与 DNF 二进制由pkg.claude-desktop-debian.dev的 Cloudflare Worker 前置元数据InRelease、Packages、KEY.gpg、repodata/*直通到gh-pages分支二进制请求/pool/.../*.deb、/rpm/*/*.rpm302 到对应的 GitHub Release 资产。这样.deb/.rpm完全不进gh-pages永远碰不到 GitHub 每个文件 100 MB 的 push 上限。关键文件与职责worker/src/worker.js —— Worker 源码worker/wrangler.toml —— Worker 配置路由、custom_domain true仓库 secretsCLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_IDtoken 限定 Edit Cloudflare Workers 模板。ci.yml里的update-apt-repo和update-dnf-repojob 还以 Worker 存活为前提来 gate 一个 strip 步骤——本地 pool 树里的二进制在 push 前被移除。完整细节重定向链、http-scheme-downgrade 陷阱、凭据归属、heartbeat 失败 runbook在 apt-worker-architecture.md。测试本地构建、Nix 与 AppImage 日志# 本地构建 AppImage ./build.sh --build appimage --clean no # Nix 构建 nix build .#claude-desktop nix build .#claude-desktop-fhs # 带日志运行 AppImage ./test-build/claude-desktop-*.AppImage 21 | tee ~/.cache/claude-desktop-debian/launcher.logNix 派生式通过fetchurlautoPatchelfHook重打包官方.deb不用 nixpkgs 的 Electron目前仅 x86_64 构建验证过真实 NixOS 上的运行时与 aarch64 腿仍是开放验证项设计契约与测试配方在 nix.md。调试工作流检查运行中应用的代码# 找到挂载的 AppImage 路径 mount | grep claude # 例如/tmp/.mount_claudeXXXXXX # 提取运行中应用的 asar 供检查官方裸并置布局 # ELF chrome-sandbox resources/ 平铺 npx asar extract /tmp/.mount_claudeXXXXXX/usr/lib/claude-desktop/resources/app.asar /tmp/claude-inspect # 在提取出的代码里搜索模式。1.19367.0 后主进程代码分割 # 跨所有 chunk grepindex.js 是桩主进程锚点在 index.chunk-hash.js grep -rn pattern /tmp/claude-inspect/.vite/build/检查 DBus/Tray 状态# 列出已注册的 tray 图标 gdbus call --session --destorg.kde.StatusNotifierWatcher \ --object-path/StatusNotifierWatcher \ --methodorg.freedesktop.DBus.Properties.Get \ org.kde.StatusNotifierWatcher RegisteredStatusNotifierItems # 找到哪个进程持有某 DBus 连接 gdbus call --session --destorg.freedesktop.DBus \ --object-path/org/freedesktop/DBus \ --methodorg.freedesktop.DBus.GetConnectionUnixProcessID :1.XXXX日志位置Launcher 日志~/.cache/claude-desktop-debian/launcher.log应用日志~/.config/Claude/logs/带日志运行./app.AppImage 21 | tee ~/.cache/claude-desktop-debian/launcher.log常用路径内容路径应用数据~/.config/Claude/日志~/.config/Claude/logs/SingletonLock~/.config/Claude/SingletonLockLauncher 日志~/.cache/claude-desktop-debian/launcher.log版本管理与发布发布版本由两个 GitHub Actions仓库变量不是文件管理REPO_VERSION—— 项目自身版本如1.3.23。发项目改动时手动gh variable set REPO_VERSION --body X.Y.ZCLAUDE_DESKTOP_VERSION—— 上游 Claude Desktop 版本如1.1.8629。由check-claude-version工作流检测到新上游发布时自动更新。Tag 格式Tag 遵循v{REPO_VERSION}claude{CLAUDE_DESKTOP_VERSION}例如v1.3.23claude1.1.7714。推送 tag 触发 CI 发布构建# 查看当前值 gh variable get REPO_VERSION gh variable get CLAUDE_DESKTOP_VERSION # 升版本并打 tag gh variable set REPO_VERSION --body 1.3.24 git tag v1.3.24claude$(gh variable get CLAUDE_DESKTOP_VERSION) git push origin v1.3.24claude$(gh variable get CLAUDE_DESKTOP_VERSION)上游更新时check-claude-version工作流从官方 APTPackages索引解析最新条目两架构都要带跨架构一致门sed 更新 scripts/setup/official-deb.sh 里的OFFICIAL_DEB_*pins更新CLAUDE_DESKTOP_VERSION然后自动建 tag——无需人工干预。不要手动在分支上跑它auto-tag 会用当时暂存的REPO_VERSION直接切一个发布。版本 pin 的三方核对提交 scripts/setup/official-deb.sh 前确保分支带着最新 pins# 仓库变量是事实来源 gh variable get CLAUDE_DESKTOP_VERSION # 分支上 pin 的版本 grep -oP ^OFFICIAL_DEB_VERSION\K[^] scripts/setup/official-deb.sh # 官方 pool 当前提供的版本 curl -fsS https://downloads.claude.ai/claude-desktop/apt/stable/dists/stable/main/binary-amd64/Packages \ | grep -E ^Version: | sort -V | tail -1从源码看official-deb.sh 的official_deb_pin只认amd64/arm64两架构下载后立即用 pin 的 SHA-256 校验fetch_official_deb且_extract_deb_member处理 zst/xz/gz/纯 tar 四种 data 成员压缩——这也是为什么 AGENTS.md 强调永远不要硬编码一种压缩。常见陷阱速查.zsync文件—— 用于增量更新可忽略/删除AppImage 挂载点—— 运行中的 AppImage 挂载到/tmp/.mount_claude*用mount | grep claude查看杀掉应用—— 必须杀所有 electron 子进程不能只杀主进程pkill -9 -f mount_claudeSingletonLock—— 应用起不来时检查过期锁~/.config/Claude/SingletonLockNode 版本—— 构建需要 Node.js脚本按需自行下载按 HOST 架构取键——见 cross-build 教训版本 pin—— 官方.deb版本、pool 路径与 SHA-256 都 pin 在 scripts/setup/official-deb.sh 的OFFICIAL_DEB_*由 main 上的check-claude-version自动更新data.tar 压缩多变—— 上游两种格式都发过official-deb.sh的_extract_deb_member处理 zst/xz/gz/纯 tar。总结AGENTS.md 是一份可执行的工程契约纵观全篇AGENTS.md 并不是普通的贡献者礼貌指南而是一份把patch-zero 重打包工程哲学落成可执行规则的操作手册文档体系划定了事实来源与知识沉淀的位置learnings 目录代码风格章节用历史事故解释了每一条反模式补丁编排章节给出了active_patches、tripwire、repack 不变量这些可验证的守卫CI/CD 与分发章节完整交代了产物与发布机制而版本管理与调试章节则让任何贡献者无论人类还是 AI都能在同一个信息水平上接手。若要深入某一子系统docs/index.md 是继续导航的入口docs/learnings/ 则保存着每个非显而易见结论的完整推导过程。【免费下载链接】claude-desktop-debianClaude Desktop for Linux项目地址: https://gitcode.com/GitHub_Trending/cl/claude-desktop-debian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考