Pake 的 AGENTS.md：为 Codex、Claude Code 等 AI 代理打造的单一事实来源知识库

Pake 是一个「一条命令把网页打包成轻量桌面应用」的 Tauri v2 + TypeScript CLI 项目。它的 AGENTS.md 不只是给人看的文档，而是 Codex、Claude Code 等 AI 编码代理在仓库中工作时的项目知识库（Project Knowledge Base）：项目事实、开发命令、风险热点、发布规则、排障方案全部收敛在这一个文件里，并以符号链接的方式被所有代理工具共享。读完本文，你能掌握这套「Agent 协作知识库」的完整设计：如何组织单一事实来源、如何把回归风险写成可执行的排查地图、如何把发布多真值面的校验规则固化进文档，从而让不同 LLM 代理在同一个项目里保持一致的行为。

一、AGENTS.md 的定位：跨代理的单一事实来源

仓库在 AGENTS.md 开头就声明了自己的定位：

Keep shared project facts in this file so Codex, Claude Code, and other agents use the same source of truth. CLAUDE.md is a symlink to this file, so edit AGENTS.md only.

这句话是整份文档的骨架：所有代理工具读到的必须是一份内容，因此 CLAUDE.md 是指向 AGENTS.md 的符号链接（仓库中确实如此，CLAUDE.md -> AGENTS.md），日常修改只允许发生在 AGENTS.md 上。同时，仅对本地环境生效的覆盖文件（CLAUDE.local.md、AGENTS.override.md、.claude/settings.local.json）被刻意留在 git 忽略范围内，保证提交进仓库的"项目事实"对所有协作者和代理一致。

围绕这份知识库，Pake 还搭了一整套配套结构，全部在仓库内可以直接查看：

• .claude/rules/rust.md：项目专用的 Rust 规则（Rust + Tauri 专项约定）；
• .agents/skills/：代理技能目录，包含 /release、/bugs、/github-ops、/code-review 四个技能，.claude/skills/* 全部是指向 .agents/skills/ 对应目录的符号链接——只编辑 .agents 一侧的副本；
• 一个例外：pake 技能的真实源码位于 plugins/pake/skills/pake/SKILL.md（它通过 Claude Code 插件市场发布给用户，由 .claude-plugin/marketplace.json 声明），.agents/skills/pake 只是指向它的符号链接。

这套「一处定义、多处软链」的做法消除了多代理工具各自维护规则副本导致事实漂移的问题，是本文最重要的工程决策之一。

项目身份速览

知识库首先固化了项目的基本事实（防止代理临场猜测）：

• Pake：一条命令把任意网页打包成约 5MB 的桌面应用（约为 Electron 方案的 1/20 体积）；
• 技术栈：Tauri v2（Rust）+ TypeScript CLI；
• 平台：macOS、Windows、Linux；
• 机制：使用系统 WebView（macOS/Linux 上是 WebKit，Windows 上是 WebView2）。

二、仓库结构地图：给 Agent 的导航图

AGENTS.md 用一段目录树给代理（和新加入的开发者）提供了标准导航。以当前仓库实际状态为准：

路径	职责
bin/（bin/cli.ts 为主入口，Commander.js 驱动）	CLI 源码（TypeScript）
bin/builders/	平台构建器：BaseBuilder.ts、MacBuilder.ts、WinBuilder.ts、LinuxBuilder.ts、BuilderProvider.ts
bin/helpers/	配置合并、CLI 程序组装等辅助逻辑
src-tauri/	Tauri Rust 应用
src-tauri/src/app/	窗口创建、setup、菜单、配置与 invoke（window.rs、setup.rs、menu.rs、auth.rs、invoke.rs 等）
src-tauri/src/inject/	注入到页面里的 JS/CSS 行为（event.js、auth.js、find.js 等）
dist/	编译后的 CLI 产物（dist/cli.js 是随 npm 包发布的构建产物）
docs/	文档：CLI 参数、定制指南、FAQ（均有中英文变体）
schema/	pake.schema.json：--config 的 JSON Schema，对外公开契约
plugins/	Claude Code 插件源码（面向用户的 pake skill）
llms.txt	面向 Agent 的契约摘要（--json、--config、退出码）
tests/	单元、集成与发布流程测试
default_app_list.json	发布构建时的流行应用配置
package.json、rollup.config.js	Node.js 依赖/版本、CLI 构建配置

这份地图的价值在于：代理不需要自己摸索仓库布局，直接按表索骥即可定位到「窗口行为问题去 src-tauri/src/app/，注入脚本问题去 src-tauri/src/inject/」。

三、开发命令表：可直接执行的统一口径

AGENTS.md 用一张表把日常开发命令固定下来，这是代理执行构建、测试、格式化任务时的唯一依据：

命令	用途
pnpm install	安装依赖
pnpm run dev	Tauri 开发模式
pnpm run cli:dev	Rollup watch 构建 bin/dev.ts 到 dist/dev.js（debug 级 CLI）
node dist/dev.js <url> --iterative-build	快速构建模式：只出 app，不产 dmg/deb/msi；并非跳过检查
pnpm run cli:build	Rollup + TypeScript 类型检查（能抓住 Prettier 漏掉的类型错误）
pnpm run release:check	/release 技能要求的全部发布前门禁
pnpm run build	构建当前平台
pnpm run build:mac	macOS 通用二进制（Intel + Apple Silicon）
pnpm run format	格式化代码（prettier + cargo fmt）
npx vitest run	仅跑单元与集成测试（亚秒级）
pnpm test -- --no-build	全量测试，但不含多架构真实构建
pnpm test	全量测试，包含 release workflow

对照 package.json 可以验证这些命令都是真实脚本：例如 release:check 实际执行 node scripts/check-release-version.mjs && pnpm run format:check && npx vitest run && pnpm run cli:build && npm pack --dry-run --ignore-scripts——版本一致性、格式检查、vitest、CLI 构建、npm 打包干跑，构成发布前的完整门禁链。文档把「命令」和「它作为门禁的角色」绑在一起，代理就不会用 npx vitest run（快但只测纯逻辑）去冒充 pnpm test（含真实构建）的验证力度。

代码规范部分只有一条硬规则：任何源码（Rust / TypeScript / 任意文件）中禁止中文注释，注释与标识符一律英文，并跟随周边行文的语言风格。

四、工作原则：把「验证义务」写进文档

Working Principles 一节的设计哲学是「只写目标与项目事实，路径交给代理自己找」，但其中三条原则信息密度极高，值得逐条拆解。

最小正确 diff，最窄真实验证

Deliver the smallest correct diff and prove it with the narrowest real verification; expand only when evidence demands it. If key context is missing, make one reasonable assumption and proceed.

即：交付最小正确改动，用范围最窄的真实验证证明它；确缺关键上下文时允许做一次合理假设然后继续推进，而不是停下来反复询问。这条原则直接决定了代理的工作节奏：先跑 npx vitest run 这类亚秒级测试，只有证据要求时才扩大到 pnpm test 的真实构建。

dist/cli.js 重建规则：两个触发器，不是一个

这是全文档最容易「翻车」的一条规则，其背后的机制在 rollup.config.js 中可以得到解释——Rollup 会把整个 package.json manifest 内联进 dist/cli.js。因此触发重建的不是「改了 CLI 源码」这一件事，而是两件事：

1. bin/ 下任何变更；
2. 任何对 package.json 的变更——依赖升版、pnpm.overrides 编辑、engines 改动，甚至 description 措辞修改，都会让 dist/cli.js 陈旧，而 bin/ 没有任何 diff 能提示你。

依赖升级类 PR 正是最容易漏掉这一点的场景。修复方式：pnpm run cli:build 重新构建，并把再生成的 dist/cli.js 与源码变更一起提交。npm 侧的 package.json files 字段只包含 dist/cli.js（而不是整个 dist/），印证了它是「随包发布的构建产物」这一身份。

发布多真值面：一个面的绿色不能暗示另一个面

Release status, issue closeout, npm delivery, and GitHub assets are separate truth surfaces. Verify each one live; never let one passing surface imply another.

npm 可信发布（Trusted Publishing）可能在流行应用发布 workflow 完成前就成功；GitHub Release 资产可能已经生成而 workflow run 仍处于排队中。这条原则与后文「发布工作流」章节的逐面校验命令一一对应，是全文档「反自欺」思维的集中体现。

五、热点地图：给 /bugs 技能的回归风险索引

Hotspot Map 是一张专门服务于 .agents/skills/bugs/SKILL.md 中「主动潜在缺陷扫描」的索引表。文档明确警告：第三列是历史失败模式 / 回归风险，不是对当前代码树状态的断言；扫描时应「选一行深挖，不要虚构全仓扫描范围」。

热点	路径	若复发的回归风险
链接/下载启发式	src-tauri/src/inject/event.js	SPA 路由或 Cmd/Ctrl+点击被当作下载；路径根过宽
下载成功语义	invoke.rs、window.rs 的 on_download	非 2xx 被当成功弹 toast；toast/IPC 硬编码 "pake"；请求丢失会话 cookie
菜单/聚焦窗口	menu.rs	命令打到了主窗口而非聚焦窗口；错误页上 eval 失效
启动可见性	lib.rs、setup.rs	空白外壳、about:blank 误报就绪、用户隐藏动作与兜底显示互相竞态
认证/弹窗	auth.js、event.js	macOS 认证崩溃、SSO 被甩到系统浏览器、Apple 弹窗例外
剪贴板	event.js	keydown 抢走原生粘贴；双重粘贴兜底
多窗口/图标	window.rs、setup.rs	显示时漏掉 reapply_window_icon；副窗口 toast/目标错乱；Cmd+N 空白闪烁
平台能力	auth.rs、代理、WebKit 标志	标志名存在但平台上是空操作
CLI/配置契约	bin/、schema/	配置塞入 CLI 会拒绝的越界值

这张表本质上是把团队踩坑史编译成可检索的知识：代理拿到一行，就知道该看哪个文件、该防哪种回归、该用哪条「当前风险区域」不变量来评判改动。

六、当前风险区域（Current Risk Areas）：可验证的深层机制

这是 AGENTS.md 中最长、信息量最大的章节。每一条都是「现状 + 机制 + 归属文件/测试」的三段式，下面按主题选取重点条目并结合源码佐证。

CLI 选项同步链：七处必须一致

CLI 选项是用户可见面，必须保持同步的位置有：bin/helpers/cli-program.ts、bin/types.ts、bin/defaults.ts、bin/helpers/merge.ts、生成的 dist/cli.js、schema/pake.schema.json 以及 docs/cli-usage*.md。其中「Schema 与 CLI 的同步」由 tests/unit/config-file.test.ts 强制执行，其余靠人为纪律。这解释了一个关键设计：文档漂移是可以被测试抓住的，而不是纯靠自觉。

--json 机器契约：面向 Agent 的公开 API

--json 输出是代理（如 CI 脚本、Claude Code）消费的公开契约，稳定性要求极高：

• 机器模式下 stdout 只能承载恰好一个 JSON 结果对象，任何日志都走 stderr；
• 退出码固定为 0/2/3/4/1（llms.txt 给出完整语义：0 成功、2 输入非法、3 构建失败、4 环境缺失、1 意外）；
• 错误码为 INVALID_INPUT、ENV_MISSING、BUILD_FAILED、UNEXPECTED，外加一个保留且当前未使用的 NETWORK（网络失败目前按阶段码上报）；
• logger.warn 会进入 JSON 的 warnings 数组，所以 warn 只能用于真正的告警，不能当状态行打印；
• 归属实现：bin/utils/output.ts、bin/cli.ts、bin/utils/shell.ts。

这与 llms.txt 中「Agent contract」一节的描述完全一致（{ok, name, platform, arch, outputs, warnings, error} 结构），两处文档互为印证，构成了对外 Agent 契约的双保险。

本地目录打包：dist_bak 的暂存与自愈

把本地 HTML 文件/静态目录打包时，Pake 会把用户内容暂存（stage）进 CLI 自己的 dist/ 目录（先把原目录移为 dist_bak，结束时只还原 cli.js）。一次崩溃的本地输入运行可能把 dev.js 和测试夹具留在 dist_bak 里，因此每次 CLI action 的开头都会调用 restoreLocalTree() 自愈，无需人工清理。源码层面可验证：bin/helpers/merge.ts 中定义了 restoreLocalTree，注释说明「dist_bak 存在时必然保存着原始 dist，因此任何运行都安全地调用它」；bin/cli.ts 的注释则点明了调用时机——「在任何动作之前，先修复上一次崩溃的本地输入运行遗留的 dist_bak」。

macOS 认证弹窗的脆弱面

macOS 上触发 WebKit 原生认证弹窗路径的认证/登录 URL，在该路径可能中止应用时必须留在当前窗口内。文档把这一面的职责切分得非常清楚：

• URL 匹配逻辑在 src-tauri/src/inject/auth.js（matchesAuthUrl，从 src-tauri/src/app/window.rs 注入），由 tests/unit/auth-sso-patterns.test.js 覆盖；
• 只有 window.open 拦截在 src-tauri/src/inject/event.js；
• Apple Sign-In（appleid.apple.com / AppleAuthentication 命名窗口）是例外，必须保留原生 window.open 弹窗。

改到任何一侧都必须补定向测试。这种「一个行为拆成两个文件、各配一个测试」的写法，让代理修改时不可能漏测另一侧。

剪贴板快捷键桥接：为什么 Ctrl+V 必须放行

Linux/Windows 上的安全剪贴板快捷键（Ctrl+C/X/V/A）在 src-tauri/src/inject/event.js 中桥接。规则是：复制/剪切/全选留在可信的 handleClipboardShortcut keydown 路径里；而 Ctrl+V 必须不处理 keydown，让原生 WebView 粘贴事件得以保留图片、文件、富文本格式；只有在可信 keyup 上确认原生粘贴事件没有触发时，才允许回退到纯文本的 navigator.clipboard.readText()。桥接被 isNonMacDesktop() 与 event.isTrusted 双重门控，只作用于可编辑/已选中的目标，且绝不能在 macOS 上触发（那里原生快捷键本来就好使）。该行为由 event-clipboard-shortcuts.test.js 中两条具名测试锁死：lets native paste preserve non-text clipboard data 与 falls back to clipboard text only when native paste does not fire。

Windows 任务栏图标与多窗口可见性

Windows 上自启动应用若在 Explorer 图标缓存就绪前显示，任务栏图标可能注册为空白（issue #1323）。修复纪律是：所有从隐藏到显示的 window.show() 路径（托盘显示/点击、激活快捷键、单实例激活、启动/页面加载显示、多窗口 Cmd+N 显示）都必须调用 src-tauri/src/app/window.rs 中的 reapply_window_icon（或走已经调用的 reveal_built_window / reveal_startup_window）——该 helper 同时重设小窗口图标和大任务栏图标。

多窗口侧同样有两条 Windows 专属约束（#1343）：托盘点击处理器必须匹配 button_state == MouseButtonState::Up，因为 Windows 每次物理点击会发出两次 TrayIconEvent::Click，对两次都响应会把切换执行两遍；any_app_window_visible 必须排除最小化窗口，因为 hide_on_close 先最小化再隐藏，而最小化（iconic）状态下 Windows 仍报告 IsWindowVisible 为真。整组行为由 tests/unit/tray-toggle-visibility.test.ts 锁定。

「不是每个绿色 CI 步骤都是证据」

这是风险区域里最具方法论价值的一条：.github/workflows/quality-and-test.yml 中的 Test CLI Integration (smoke) 步骤以 || true 结尾，无论 CLI 行为如何都报成功——它是日志生产者，不是门禁。真正能因回归而失败的步骤是 Run Fast Test Suite（三平台）和 Full Tauri Build（真实的 pnpm test，仅在 push 和 dispatch 时运行）。结论：声称某改动「已验证」时只引用这些步骤；并且把任何步骤当证据之前，先检查它有没有 || true 或 continue-on-error。

其他值得注意的条目（摘要）

• --incognito 以牺牲持久化为代价换取干净隐私会话，改动时警惕登录、cookie、localStorage 与微信类 WebView 检测；
• --new-window / --multi-window 不能绕过所有服务商策略，Google OAuth 等内嵌 WebView 限制仍可能要求正常浏览器或原生客户端；
• macOS Basic Auth 在 CLI/配置中只保留启用布尔值，用户名密码是仅运行时输入，绝不进 CLI 参数、配置、生成物、日志或持久层；
• 本地构建/测试运行会把 src-tauri/pake.json、tauri.conf.json、tauri.macos.conf.json 及再生成图标当作构建状态去修改被跟踪文件：运行前记录 git status --short 基线，之后只还原基线中干净且新增 diff 可证明由本次运行产生的路径；
• default_app_list.json 中「默认 false/数值型」的每应用可选字段目前借 GitHub 表达式（matrix.config.x || false）取默认值；第一个「默认 true」的字段不能走这条路，因为 GitHub 表达式把 null 和 false 都转成 0，必须把默认值挪进 jq 读取步骤；
• .github/workflows/pake-cli.yaml 与 single-app.yaml 是外部用户从自己 fork 触发的公共构建面，推送 main 即对外发布，应像公共 API 而非内部 CI 来对待。

七、平台特定开发

平台	关键点
macOS	--multi-arch 产出通用二进制（Intel + Apple Silicon）；图标为 .icns；标题栏可通过 Tauri 窗口选项定制
Windows	编译需要 Visual Studio Build Tools；图标为 .ico；MSI 安装器由 Tauri bundler 支持
Linux	多种打包格式：.deb、.AppImage、.rpm；运行时依赖 libwebkit2gtk 及其配套库；图标为 .png；Wayland 上 WebKit 合成行为对平台敏感，改默认值前先看 Current Risk Areas

八、分支策略与版本管理

单分支策略

只有 main 一个分支，所有开发与发布都直接在此进行。这简化了「发布状态分裂」问题的排查面，但把发布纪律的压力全部压在了 tag 与工作流上。

四处版本必须同步

每次发布，以下四个文件的版本字段必须一致：

文件	字段
package.json	"version"
src-tauri/Cargo.toml	[package] 下的 version
src-tauri/Cargo.lock	包 pake 的 version
src-tauri/tauri.conf.json	"version"

而且版本升级必须同时重建并提交 dist/cli.js（它内嵌包版本）。这套规则不是纯文字约束：scripts/check-release-version.mjs 会解析并比对 tag（或 GITHUB_REF_NAME）、package.json、Cargo.toml、Cargo.lock、tauri.conf.json 以及从 dist/cli.js 正文中正则提取出来的内嵌版本，还顺带校验 repository.url 与 files 字段必须包含 LICENSE-EXCEPTION、llms.txt、dist/cli.js 且不得包含整个 dist。pnpm run release:check 的第一步就是跑它。

Tag 格式与陷阱

• 格式：V<major.minor.patch>，大写 V（如 V3.13.1）；当前版本以 package.json 为准（当前为 3.15.7）。
• 找上一个发布 tag 必须写 git tag --list 'V*' --sort=-version:refname | head -1。裸的 git tag --sort 会被游离的非版本 tag（list、continuous、0.1.0）污染而静默选错日志范围。
• 不要擅自删除这些 tag：continuous 挂着 2023 年一个真实的预发布（40 个资产、约 700 次下载），删掉会打断全部历史下载链接；list 和 0.1.0 指向没有关联发布的旧提交。任何删 tag 都是公开的、不可逆的动作，需要维护者在当前轮次明确授权。

九、发布工作流（CI）

V* tag 触发的双工作流

推送 V* tag 会触发 .github/workflows/release.yml，五个阶段依次为：

1. release-apps —— 读取 default_app_list.json 得到应用清单；
2. create-release —— 创建 GitHub Release 占位；
3. build-cli —— 构建并上传 dist/ CLI 产物；
4. build-popular-apps —— 在 macOS/Windows/Linux 上并行构建所有应用；
5. publish-docker —— 构建并推送 Docker 镜像到 GHCR。

该 workflow 也支持 workflow_dispatch 手动触发，可独立选择构建流行应用或发布 Docker。

同一 V* tag 还会触发 .github/workflows/npm-publish.yml，通过 Trusted Publishing 把 pake-cli 发布到 npm（可信发布者配置为 GitHub Actions、tw93/Pake、workflow 文件 npm-publish.yml、无 environment）。本地 npm publish 只是 CI 或 npm 注册表状态受阻时的兜底。

npm-only CLI 热修：不依赖 tag 的发布路径

npm-publish.yml 支持从 main 用 workflow_dispatch 走 npm-only 热修：在 main 上抬升版本文件，等待该精确提交通过 quality-and-test.yml，然后把该提交作为 expected_sha、成功运行作为 quality_run_id 传入。发布工作流会先校验两者，再无需 V* tag 或应用发布直接发布。由此确立了一条铁律：npm publish 与 git tag 是两个独立动作，绝不互相推断。每次发布任务开始时，要先复述本轮触及哪些面（npm 包、GitHub Release + 应用资产、Docker、git tag），请维护者确认；每个 publish/tag/关 issue 动作都需要当前轮次的授权。

验证命令与边界纪律

• 认定 npm 已发布前，两个命令都要跑：gh workflow list --all | grep "Publish npm Package" 与 npm view pake-cli@X.Y.Z version；更推荐 npm view pake-cli@X.Y.Z version gitHead dist.tarball --json，把发布包绑定回目标提交；
• npm 注册表没返回目标版本之前，不要回复或关闭任何 GitHub issue 说「已发布」；
• 应用资产声明要直接 gh release view <tag> --json assets 检查资产数量/状态，不能只信源码状态或 workflow 名称；
• 贡献者机器人可能在任意时刻（包括本地提交与 bump 推送之间）推入 chore: update contributors [skip ci]。推送被拒时，git pull --rebase 过它再推；发布后把本地 main 快进，但不要移动已推送的发布 tag 去包含它；永远不要给 bot 提交本身打 tag——GitHub 对 tag 推送也按 head 提交判定 [skip ci]，落在它上面的 V* tag 会静默地不产生 workflow run、不产生发布、不产生资产，而且没有任何报错。推发布 tag 前确认目标提交主题没有 [skip ci] 且其自身有绿色 Quality 运行。

此外：Claude Code 插件（.claude-plugin/marketplace.json + plugins/pake）从 main 经 git 独立发布，不受 V* 发布约束——技能与清单的编辑一旦落到 main，新安装立即生效；npm 包与应用资产仍在各自的发布工作流里等待。

网络镜像行为

Pake 默认使用官方 npm 与 Rust 源；国内镜像是显式 opt-in：

• 仅当用户或 CI 环境有意要 npmmirror/rsProxy 时才设置 PAKE_USE_CN_MIRROR=1；
• 不要重新引入自动按中国域名切换镜像的逻辑；
• 若安装对着国内镜像失败，重试同一条安装命令，以区分网络可用性与产品回归；
• 该行为的归属是 bin/utils/mirror.ts 与 bin/builders/BaseBuilder.ts（两者均真实存在于仓库），改动时保持文档与测试对齐。

十、修复后的 Issue 关闭循环

针对用户报告的 CLI 缺陷，默认循环是：先以 npm patch 版本交付修复，然后回复报告者具体的升级命令（npm install -g pake-cli@latest，若 latest 可能指向别处则写 pake-cli@X.Y.Z），最后关闭 issue 并注明可复开。禁止指着未发布的提交回复「已修复」——npm 注册表必须先返回修复版本。

配套纪律：用户报告缺陷的提交信息里不要写 closes #N / fixes #N。GitHub 在提交到达 main 的瞬间就关闭 issue，那时 npm 上还没有修复，报告者看到的是静默关闭却依旧无法升级。正确做法是裸 #N 引用，待注册表返回修复版本后手动关闭。

十一、社区 PR 分诊

所有社区 PR 归入三种结局，且绝不把别人的贡献改写成自己的新 PR：

• 原样合并：实现合理。本地验证（构建 + 相关测试）后合并、致谢作者；
• 方向正确、实现需打磨：直接把修复推进贡献者的分支以保留其署名，然后合并并回复说明改了什么、为什么；
• 超出范围：以「不计划实现」关闭，附一行致歉和边界理由（Pake 刻意不做什么），保持友好、留有余地。

十二、故障排查

通用问题见 docs/faq.md。文档专门收录了三个高频场景：

macOS SDK / 编译错误

若编译出错（例如 macOS beta），创建 src-tauri/.cargo/config.toml：

[env]
MACOSX_DEPLOYMENT_TARGET = "15.0"
SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"

该文件已被 .gitignore 忽略（与仓库结构表中标注的 src-tauri/.cargo/ 一致）。

dist/cli.js 与源码不同步

症状：bin/ 或 package.json 编辑后，测试或发布构建仍用陈旧 CLI 行为。修复：pnpm run cli:build 并重新提交 dist/cli.js。注意 dist/ 被 gitignore 而 dist/cli.js 是被跟踪的，所以要 git add -f dist/cli.js。quality-and-test.yml 在 Linux 上会重建后检查 git diff -- dist/，非空即失败——未重建的产物会在 CI 上失败，而不是静默发布。

首次 Tauri 构建很慢

全新克隆的首次 cargo build 需要 10 分钟以上，因为 Cargo 从源码编译全部 Tauri 依赖；后续构建复用 src-tauri/target/ 缓存。这是预期行为，不是 bug。

十三、文档维护指南

AGENTS.md 末尾给出了文档体系自身的分工规则：

• 主 README（README.md / README_CN.md）：只保留常用高频参数，避免杂乱；
• CLI 文档（docs/cli-usage.md 及语言变体）：收录全部 CLI 参数与详细用法示例；
• 冷门/高级参数（如 --title、--incognito、--system-tray-icon、--multi-window、--min-width、--min-height）：在 docs/cli-usage*.md 完整文档化，但主 README 中极少提及或不提及；
• README 流行应用橱窗：以 <td> 两两成对渲染应用截图，截图先上传外部静态仓库再推送 README 行；应用下载链接要等下一个 V* 发布构建出资产前一直是 404；
• 应用清单精选：橱窗与 default_app_list.json 的增删用 gh release view <tag> --json assets 的真实下载量判断，而不是凭直觉；README 双语版保持相同顺序；
• 关键配置文件：src-tauri/pake.json（默认应用配置，构建期与 CLI 选项合并）、src-tauri/tauri.conf.json（共享 Tauri 设置）、src-tauri/tauri.{macos,windows,linux}.conf.json（分平台覆盖）。

小结：这份 AGENTS.md 为什么值得 LLM 代理实践者学习

从源码结构与文档组织看，Pake 的 AGENTS.md 给出了「AI 代理协作知识库」的一份完整范本：

1. 单一事实来源：CLAUDE.md -> AGENTS.md 软链 + 仅本地覆盖文件被忽略，Codex 与 Claude Code 读到同一份事实；
2. 规则可执行化：版本同步有四文件表 + scripts/check-release-version.mjs 脚本兜底，CLI 选项同步有 tests/unit/config-file.test.ts 强制 schema-CLI 一致，文档中的每条纪律几乎都找到了「谁在测试里守着它」；
3. 风险知识结构化：热点地图（文件 → 历史失败模式）+ 当前风险区域（机制 + 归属 + 锁定测试）两级索引，让代理的排障与回归判断有据可依；
4. 反自欺的验证文化：|| true 步骤不算证据、绿色 CI 步骤逐一点名、npm 注册表是唯一决定面、「一个面的绿色不暗示另一个面」——把最容易骗过自动化（也最容易骗过代理）的环节写死成纪律；
5. 对外契约双文档：AGENTS.md 面向仓库内协作者与代理，llms.txt 面向消费 pake-cli 的外部 Agent，--json 结构、退出码、错误码在两边保持一致。

对同样使用多个 AI 编码代理维护 Tauri/Rust + TypeScript 项目的团队，可以直接借鉴的正是这套结构：一个被软链共享的知识库文件、一张可执行的命令表、一张回归风险热点图、一节把「多真值面验证」写成命令的发布纪律。