agentsw 0.7.1 → 0.8.0

package/README.md

@@ -23,7 +23,7 @@ switching to vfing (openai) · default model glm-5.3-flash
 
 skip claude    Claude Code does not support openai-protocol providers
 ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
-               backup: ~/.config/agentsw/backups/config.toml.2026-08-31T15-58-24-678Z
+               backup: ~/.config/agentsw/backups/transaction-<unique>
 ok   omp       ~/.omp/agent/models.yml
                select in omp with: omp --model vfing/glm-5.3-flash
 skip pi        pi not detected (pass --apps pi to force)
@@ -39,18 +39,18 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 - **It runs where a desktop app cannot.** Headless servers, containers, devcontainers, CI.
   `npx agentsw use myproxy -a codex,omp` is one line in a provisioning script; nine GUI
   clicks are not.
-- **`--dry-run` prints diffs.** Review what a switch will write before it writes it, or pipe
-  it into a code review. Every file is backed up first regardless.
+- **`--dry-run` prints redacted diffs.** Preview changes without writing files or creating
+  backups. Existing configuration files are backed up when actual changes are committed.
 - **Non-destructive by design.** Only the fields agentsw owns are rewritten. Provider-level
   keys it does not model — `authHeader`, `headers`, `compat`, `discovery` — per-model extras
   like `thinkingLevelMap`, and YAML comments all survive a re-sync.
 - **Model metadata, not just an id list.** Reseller `/v1/models` endpoints return bare ids.
-  agentsw enriches them from [models.dev](https://models.dev) and writes what each app
+  agentsw enriches them from [models.dev](https://models.dev), automatically fills meaningful gaps from AI Gateway when needed, and writes what each app
   actually reads: `thinkingLevelMap` for pi/prime, `limit`/`attachment` for opencode,
   `contextWindow`/`maxTokens` for omp, `reasoningEfforts`/`input` for dsh.
 - **Adopts what you already have** — including [cc-switch](https://github.com/farion1231/cc-switch).
   `import` scans every installed agent *and* cc-switch's own store, merges duplicates
-  (same protocol + base URL), and never writes back to either.
+  (same protocol + normalized endpoint + credentials), and never writes back to either.
 - **Wire-aware.** `/v1/chat/completions` and `/v1/responses` are different endpoints;
   agentsw tracks which one a provider speaks and never downgrades a working one.
 
@@ -62,7 +62,7 @@ imports from it rather than competing with it.
 
 ```bash
 npx agentsw               # zero install: opens the interactive menu
-npm install -g agentsw    # requires Node >= 22.12
+npm install -g agentsw    # requires Node >= 22.13 (built-in SQLite without an extra flag)
 ```
 
 The provider sync and config management work on Linux, macOS, and Windows. On Windows,
@@ -139,13 +139,15 @@ imported sub · openai · https://new.vfing.de/v1 · 18 models [from omp]
 imported zhipu-glm · anthropic · https://open.bigmodel.cn/api/anthropic · 1 models [from cc-switch]
 ```
 
-Without `--all` the list is a multi-select preview; nothing is written until you pick.
+In an interactive terminal, omitting `--all` opens a multi-select preview before provider
+records are saved. `--all`, or non-interactive stdin, imports all eligible new entries;
+use `--all` explicitly in scripts. Model discovery may update the local metadata cache.
 
 ## Model discovery filters
 
 `--discover` lists model ids from the provider's `/v1/models`, then enriches each id from
-models.dev. Reseller lists are noisy, so filters are persisted per provider and re-applied on
-every `discover`:
+models.dev first, with automatic AI Gateway supplementation when needed. Reseller lists are noisy,
+so filters are persisted per provider and re-applied on every `discover`:
 
 ```bash
 # snapshot duplicates (gpt-5.2-latest, glm-4.7-250414, ...) are DROPPED by default
@@ -158,6 +160,77 @@ asw discover myproxy --no-filter                # clear it
 
 Explicit `--models` entries and the default model are never filtered out.
 
+## Automatic model metadata
+
+**No extra flags are needed.** New providers and providers without a saved mode use `auto`:
+models.dev is checked first, then the public
+[AI Gateway model catalog](https://vercel.com/docs/ai-gateway/models-and-providers#dynamic-model-discovery)
+is consulted only for missing core parameters (context window, maximum output, reasoning or image input),
+to refresh unchanged Gateway-supplied fields that models.dev has not replaced, or to verify an identity
+conflict in previously tracked automatic values. Missing names, prices, optional input limits or
+reasoning-effort lists alone do not trigger a Gateway lookup.
+agentsw directly fetches `https://ai-gateway.vercel.sh/v1/models` without provider credentials or an AI SDK dependency.
+
+```bash
+# Refresh only saved models using the saved mode (auto if unset)
+# No model discovery or agent config writes
+asw refresh --provider myproxy
+
+# Inspect effective mode, sources, conflicts and reference pricing (no API key)
+asw models --provider myproxy --metadata
+
+# Custom or ambiguous names need explicit aliases; wire model IDs stay unchanged
+asw refresh --provider myproxy --metadata-mode auto \
+  --gateway-models '{"my-model":"openai/gpt-5.4"}'
+
+# Always consult Gateway, even when core parameters are complete
+asw refresh --provider myproxy --metadata-mode on
+
+# Stop future Gateway fetches; retain saved model parameters
+asw refresh --provider myproxy --metadata-mode off
+
+# Return an explicitly disabled provider to automatic mode
+asw refresh --provider myproxy --metadata-mode auto
+
+# Preview and apply separately; sync does not query catalogs
+asw sync --provider myproxy --dry-run
+asw sync --provider myproxy
+```
+
+The menu's **Configure and refresh model metadata** action offers **Automatic (recommended)**,
+**Always supplement**, and **Disabled**, with the provider's current mode selected. Onboarding has no extra prompts.
+`add`, `quick`, `discover`, `import`, and `refresh` accept `--metadata-mode <auto|on|off>`.
+The existing `--gateway-metadata` and `--no-gateway-metadata` flags remain explicit `on` and `off` choices.
+Omitted options preserve saved settings: an existing `false` remains off until you select `auto` or `on`.
+Invalid modes and conflicting mode/boolean flags are rejected before fetching or saving.
+Without `--provider`, `refresh` applies to all providers, including any supplied mode.
+`--gateway-models` replaces the whole alias map (`{}` clears it); aliases do not change the saved mode or override `off`.
+Import still skips already configured accounts.
+
+- **Field-level priority:** manual values > models.dev > Gateway gap filling. Tracked automatic values may
+  refresh; subsequent manual edits are retained. Legacy values without provenance are conservatively treated
+  as manual overrides. Unmodeled extension fields survive enrichment too.
+- **Exact identities:** automatic lookup can map a bare, case-sensitive ID (no `/`) to a unique Gateway
+  `creator/model` identity when models.dev evidence is absent or agrees. Ambiguous creator evidence in either
+  catalog is rejected; custom or ambiguous names need explicit aliases. Qualified IDs never have their prefixes
+  stripped, and matching never guesses from substrings, case folding or versions. Auto/on mode also uses conservative
+  exact models.dev matching; off retains the legacy models.dev lookup. Unmatched models remain usable.
+  Alias changes clear unchanged automatic values tied to confirmed superseded identities, never manual edits.
+- **No routing changes:** metadata never adds available models or changes IDs, protocols, URLs, defaults or
+  accounts. Gateway capabilities are reference specs, not proof of reseller support. `supported_specifications`
+  is not a URL version.
+- **Reference-only prices:** Gateway prices are converted to USD per million tokens and stored separately in
+  `metadata.gateway.referenceCost`, not effective provider `cost` or runtime agent pricing. Variable/tiered
+  pricing is flagged separately.
+  Auto does not fetch solely to refresh this reference snapshot: check `metadata.gateway.fetchedAt`, or use
+  `refresh --provider <id> --metadata-mode on` to request fresh reference prices.
+- **Auditable and optional:** `metadata.fields` records origins, value snapshots and timestamps;
+  `metadata.conflicts` records disagreements with retained values. This audit stays in agentsw, never runtime agent configs.
+  Gateway has a separate 24-hour cache; failures use stale cached data or skip supplementation.
+- **Automatic lookup is not automatic sync:** enrichment updates saved metadata during add/quick/discover/import/refresh.
+  It does not add an automatic push to agents. Sync behavior is unchanged: ordinary `sync` only writes saved settings
+  and fetches neither model lists nor metadata catalogs.
+
 ## Commands
 
 | Command | What it does |
@@ -173,7 +246,8 @@ Explicit `--models` entries and the default model are never filtered out.
 | `sync` | re-apply the active provider (after an agent update, say) |
 | `discover <id> [--sync]` | refresh the model list + metadata from `/v1/models` |
 | `models [query]` | search the models.dev catalog |
-| `refresh` | re-fetch metadata for every configured provider |
+| `refresh [--provider <id>]` | refresh saved metadata and optionally configure Gateway; keep the model list |
+| `models --provider <id> --metadata` | inspect field sources, conflicts and reference pricing as JSON |
 | `prune <id>` / `remove <id> [--prune]` | remove from app configs / from the store |
 | `remove <id> --apps omp` | delete only the selected app's entry; supports `--dry-run` |
 | `apps` / `install <app>` / `upgrade` | agent version manager |
@@ -204,8 +278,18 @@ sync of a managed provider can add it back to that app.
 
 ## How your configs are treated
 
-- Every modified file is backed up first to `~/.config/agentsw/backups/`.
-- The provider store lives at `~/.config/agentsw/config.json` (mode 0600).
+- Existing provider-store and agent configuration files are backed up before committed
+  changes to `~/.config/agentsw/backups/transaction-*`. New files have no prior copy;
+  cache refreshes are not configuration backups. Dry runs create neither files nor backups.
+- Each adapter stages all its files before committing; failed writes trigger best-effort
+  rollback. A multi-agent sync is not one filesystem-wide transaction: successful agents
+  remain updated if another fails, and failures are reported with a nonzero exit status.
+- The provider store lives at `~/.config/agentsw/config.json` (mode 0600). Concurrent stale
+  saves are rejected instead of overwriting newer records; retry after the other writer finishes.
+- Existing file permissions are preserved and new configuration files default to 0600.
+- A busy write lock reports its owner PID/time. If a writer crashed, stop all agentsw
+  writers and confirm the lock is abandoned before manually removing the reported
+  `.write.lock` file; active or unknown locks are never automatically stolen.
 - A sync overwrites only the fields agentsw owns. Unmodeled provider-level keys and per-model
   extras survive; an owned field that stops applying is cleared rather than left stale, and a
   per-model `api`/`baseUrl` override that contradicts the route is dropped (it would silently
@@ -219,8 +303,10 @@ sync of a managed provider can add it back to that app.
 - Codex only speaks the Responses API; a chat-completions-only endpoint cannot be used with
   it, and the sync output says so.
 - DeepSeek Harness keeps secrets out of `settings.yaml`: the route carries
-  `apiKeyEnv: AGENTSW_<ID>_API_KEY`, the key goes into `$DSH_HOME/.credentials.yaml`
+  `apiKeyEnv: AGENTSW_<ID>_<DIGEST>_API_KEY`, the key goes into `$DSH_HOME/.credentials.yaml`
   (`refs:`, mode 0600). `$DSH_HOME` defaults to `~/.dsh`.
+  The digest distinguishes IDs such as `foo-bar` and `foo_bar`; legacy generated references
+  remain recognizable. External/custom references are not renamed or removed indiscriminately.
 - cc-switch's database is opened read-only and never written to.
 - The apps manager supports native Windows commands for Claude Code, Codex CLI, pi,
   opencode, Hermes, and DeepSeek Harness. Oh My Pi and prime-agent still need their own
@@ -250,8 +336,13 @@ npm run dev -- ...  # run from source via tsx
 
 Each agent is one adapter in [`src/targets/`](./src/targets) implementing
 `apply` / `prune` / `current` / `candidates`; read-only import sources live in
-[`src/sources/`](./src/sources). Adding an app is one file plus a line in
-[`src/targets/index.ts`](./src/targets/index.ts).
+[`src/sources/`](./src/sources). To add an app, register it in
+[`src/targets/index.ts`](./src/targets/index.ts), wrap its implementation with
+`transactionalTarget()`, and add its schemas/references to `rename.ts` and `remove.ts`.
+Use shared credential, YAML/JSONC, URL and model helpers; add apply/prune/import,
+rename/removal, malformed-input, dry-run and account-isolation tests. If installable,
+also add its platform commands to `apps.ts`. WorkBuddy local deletion uses the stable
+account selector shown by `list --apps workbuddy`, not an ambiguous hostname alone.
 
 ## License
 

package/README.zh-CN.md

@@ -23,7 +23,7 @@ switching to vfing (openai) · default model glm-5.3-flash
 
 skip claude    Claude Code does not support openai-protocol providers
 ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
-               backup: ~/.config/agentsw/backups/config.toml.2026-08-31T15-58-24-678Z
+               backup: ~/.config/agentsw/backups/transaction-<unique>
 ok   omp       ~/.omp/agent/models.yml
                select in omp with: omp --model vfing/glm-5.3-flash
 skip pi        pi not detected (pass --apps pi to force)
@@ -38,18 +38,18 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 
 - **它能去桌面应用去不了的地方。** 无头服务器、容器、devcontainer、CI。
   `npx agentsw use myproxy -a codex,omp` 在开机脚本里是一行；GUI 点九次不是。
-- **`--dry-run` 直接打 diff。** 写盘前先看清楚要改什么，或者把 diff 丢进 code review。
-  无论如何每个文件都会先备份。
+- **`--dry-run` 输出脱敏 diff。** 写盘前先预览；预览不写文件、不创建备份。
+  正式提交变更时，已有配置文件才会先备份。
 - **默认不破坏现有配置。** 只覆盖 agentsw 自己管理的字段：它不建模的供应商级键
   （`authHeader`、`headers`、`compat`、`discovery`）、`thinkingLevelMap` 之类的模型级字段、
   以及 YAML 注释，都会在重新同步后原样保留。
 - **写的是元数据，不只是模型 id。** 转售商 `/v1/models` 只返回裸 id；agentsw 从
-  [models.dev](https://models.dev) 补全，并按各应用真正读取的字段下发：pi/prime 的
+  [models.dev](https://models.dev) 优先补全，并在有实际缺口时自动查询 AI Gateway，按各应用真正读取的字段下发：pi/prime 的
   `thinkingLevelMap`、opencode 的 `limit`/`attachment`、omp 的 `contextWindow`/`maxTokens`、
   dsh 的 `reasoningEfforts`/`input`。
 - **接管你已有的配置——包括 [cc-switch](https://github.com/farion1231/cc-switch)。**
   `import` 会扫描所有已安装的智能体**以及 cc-switch 自己的存储**，合并重复项
-  （相同协议 + base URL），并且对两者都只读不写。
+  （相同协议 + 归一化端点 + 凭据），并且对两者都只读不写。
 - **区分接口形态。** `/v1/chat/completions` 与 `/v1/responses` 是两个不同端点；
   agentsw 记录供应商说的是哪一种，并且绝不把可用的 responses 降级。
 
@@ -61,7 +61,7 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 
 ```bash
 npx agentsw               # 免安装，直接打开交互菜单
-npm install -g agentsw    # 需要 Node >= 22.12
+npm install -g agentsw    # 需要 Node >= 22.13，内置 SQLite 无需额外启动参数
 ```
 
 供应商同步与配置管理支持 Linux、macOS 和 Windows。Windows 下 agentsw 自身状态默认存放在
@@ -137,11 +137,13 @@ imported sub · openai · https://new.vfing.de/v1 · 18 models [from omp]
 imported zhipu-glm · anthropic · https://open.bigmodel.cn/api/anthropic · 1 models [from cc-switch]
 ```
 
-不加 `--all` 时先展示多选预览，选定之前不写任何文件。
+在交互终端中，不加 `--all` 会先展示多选预览，选定后才保存供应商记录。
+使用 `--all` 或非交互输入时会导入全部符合条件的新条目；脚本中建议明确写 `--all`。
+模型发现过程中可能更新本地元数据缓存。
 
 ## 模型发现过滤
 
-`--discover` 从供应商 `/v1/models` 拉取模型 id，再从 models.dev 补全元数据。
+`--discover` 从供应商 `/v1/models` 拉取模型 id，优先从 models.dev 补全元数据，必要时自动查询 AI Gateway。
 转售商列表噪音大，过滤规则持久化在供应商上，每次 `discover` 自动复用：
 
 ```bash
@@ -155,6 +157,69 @@ asw discover myproxy --no-filter                # 清除规则
 
 手动 `--models` 指定的 id 和默认模型永不被过滤。
 
+## 自动补全模型元数据
+
+**默认无需额外参数。** 新供应商和未保存模式的供应商使用 `auto`：先查询 models.dev，
+仅在核心参数（上下文窗口、最大输出、推理或图片输入能力）仍缺失、已有 Gateway 自动字段
+未被手动修改或 models.dev 替代而需刷新，或需核实旧自动值的身份冲突时，才查询公开的
+[AI Gateway 模型目录](https://vercel.com/docs/ai-gateway/models-and-providers#dynamic-model-discovery)。
+仅缺名称、价格、可选输入上限或推理等级列表，不会触发 Gateway 查询。
+直接请求 `https://ai-gateway.vercel.sh/v1/models`，不携带供应商密钥，也不安装 AI SDK。
+
+```bash
+# 按保存的模式刷新已有模型参数（未设置时为 auto）
+# 不发现新模型、不写智能体配置
+asw refresh --provider myproxy
+
+# 查看生效模式、字段来源、冲突和参考价格；JSON 不含 API key
+asw models --provider myproxy --metadata
+
+# 自定义或有歧义的名称需显式映射；实际调用的模型 ID 不变
+asw refresh --provider myproxy --metadata-mode auto \
+  --gateway-models '{"my-model":"openai/gpt-5.4"}'
+
+# 即使核心参数完整，也始终查询 Gateway
+asw refresh --provider myproxy --metadata-mode on
+
+# 停止后续 Gateway 获取；保留已保存的参数
+asw refresh --provider myproxy --metadata-mode off
+
+# 将显式关闭的供应商恢复为自动模式
+asw refresh --provider myproxy --metadata-mode auto
+
+# 单独预览、同步；sync 不查询目录
+asw sync --provider myproxy --dry-run
+asw sync --provider myproxy
+```
+
+交互菜单的“设置并刷新模型参数补充源”提供“自动按需（推荐）”“始终补充”“关闭”，
+默认选中该供应商当前模式；添加供应商时不增加提问。
+`add`、`quick`、`discover`、`import`、`refresh` 均支持 `--metadata-mode <auto|on|off>`。
+原有 `--gateway-metadata` / `--no-gateway-metadata` 仍分别表示显式 `on` / `off`。
+省略参数会保留已保存的设置：已有 `false` 仍保持关闭，直到主动选择 `auto` 或 `on`。
+无效模式或相互冲突的模式/布尔开关，会在查询或保存之前报错。
+`refresh` 不传 `--provider` 会作用于全部供应商，包括更新传入的模式。
+`--gateway-models` 替换整个映射，传 `{}` 清空；映射不会更改保存的模式，也不会覆盖 `off`。
+导入仍跳过已经配置的账号。
+
+- **按字段合并：** 用户手动值优先，其次 models.dev，最后 Gateway 补缺。已记录来源的自动值可以刷新，
+  手动修改后会保留；旧版本中没有来源记录的已有值保守视为手动值，不强制覆盖。未知扩展字段也保留。
+- **精确匹配：** 不含 `/` 的裸 ID 可按大小写精确匹配唯一的 Gateway `creator/model` 身份，
+  前提是 models.dev 没有身份线索或线索一致。任一目录中的创建者身份有歧义时拒绝自动匹配；
+  自定义或有歧义的名称仍需显式映射。带命名空间的 ID 不会剥离前缀，不按子串、大小写折叠或版本相似度猜测。
+  `auto` / `on` 模式下 models.dev 也采用保守的精确匹配；`off` 保留原有 models.dev 查询行为。
+  匹配失败不妨碍模型继续使用。修改/删除映射时，只清理确认已失效身份的自动值，保留手动修改。
+- **不改变调用语义：** 目录不会给供应商增加模型，不改模型 ID、协议、URL、默认模型或账户；
+  Gateway 能力是参考规格，不保证转售商实际实现。`supported_specifications` 不是 URL 版本。
+- **价格仅供参考：** Gateway 价格转换为美元/百万 token，单独保存在 `metadata.gateway.referenceCost`，
+  不写入供应商的有效 `cost`，也不下发为智能体计费价格；分档/供应商差异另有标记。
+  自动模式不会仅为刷新参考价格而查询：可查看 `metadata.gateway.fetchedAt` 判断快照时间，
+  需要重新查询参考价格时使用 `refresh --provider <id> --metadata-mode on`。
+- **可追溯、可降级：** `metadata.fields` 记录来源、原值快照和时间，`metadata.conflicts` 记录保留值与冲突。
+  审计信息仅保存在 agentsw，不写入智能体运行配置。Gateway 目录独立缓存 24 小时；请求失败可使用旧缓存，无缓存时只跳过补充。
+- **自动查询不等于自动同步：** 添加、快速添加、发现、导入、刷新时补全保存的元数据，并不新增自动推送。
+  同步行为不变：普通 `sync` 仅写入已保存的设置，既不获取模型列表，也不请求元数据目录。
+
 ## 命令
 
 | 命令 | 作用 |
@@ -170,7 +235,8 @@ asw discover myproxy --no-filter                # 清除规则
 | `sync` | 重新应用当前供应商（比如某个智能体升级之后） |
 | `discover <id> [--sync]` | 从 `/v1/models` 刷新模型列表与元数据 |
 | `models [query]` | 搜索 models.dev 目录 |
-| `refresh` | 重新拉取所有供应商的元数据 |
+| `refresh [--provider <id>]` | 刷新已有模型参数，可设置 Gateway 补充源，不改变模型列表 |
+| `models --provider <id> --metadata` | 以 JSON 查看字段来源、冲突和参考价格 |
 | `prune <id>` / `remove <id> [--prune]` | 从各应用配置中清除 / 从存储中删除 |
 | `remove <id> --apps omp` | 仅删除指定智能体内的条目，支持 `--dry-run` |
 | `apps` / `install <app>` / `upgrade` | 智能体版本管理 |
@@ -200,8 +266,16 @@ asw remove unused-provider --apps omp
 
 ## 它如何对待你的配置
 
-- 每个被修改的文件先备份到 `~/.config/agentsw/backups/`。
-- 供应商存储位于 `~/.config/agentsw/config.json`（权限 0600）。
+- 正式提交变更前，已有中央存储和智能体配置先备份到
+  `~/.config/agentsw/backups/transaction-*`。新文件没有旧副本；缓存刷新不属于配置备份。
+  预览不写文件，也不创建备份。
+- 每个适配器先准备全部文件再提交，写入失败时尝试回滚。多智能体同步不是全局文件系统事务：
+  某个智能体失败时，其他成功项仍保留，并通过非零退出码报告失败。
+- 供应商存储位于 `~/.config/agentsw/config.json`（权限 0600）。并发写入导致快照过期时，
+  拒绝覆盖新记录；等待其他写入完成后重试。
+- 保留已有文件权限，新建配置文件默认使用 0600。
+- 写锁占用时会显示持有者 PID 和时间。若进程曾异常退出，先停止所有 agentsw 写入并确认
+  锁已遗留，再手动删除报错中指定的 `.write.lock` 后重试；不会自动抢占活动或状态不明的锁。
 - 同步只覆盖 agentsw 自己管理的字段：未建模的供应商级键与模型级扩展字段保留；
   自己管理但本次不再写出的字段会被清除而非留成陈旧值；与新路由矛盾的模型级
   `api`/`baseUrl` 覆盖会被删除（否则它会静默盖过供应商条目）并在输出中点名。
@@ -212,8 +286,9 @@ asw remove unused-provider --apps omp
   手动指定；同步绝不把已有的 responses 端点降级。
 - Codex 只支持 Responses API；仅提供 chat-completions 的端点无法用于 Codex，同步输出会提示。
 - DeepSeek Harness 不把密钥写进 `settings.yaml`：路由里只保存
-  `apiKeyEnv: AGENTSW_<ID>_API_KEY` 引用，密钥写入 `$DSH_HOME/.credentials.yaml`
+  `apiKeyEnv: AGENTSW_<ID>_<DIGEST>_API_KEY` 引用，密钥写入 `$DSH_HOME/.credentials.yaml`
   的 `refs:`（权限 0600）。`$DSH_HOME` 默认为 `~/.dsh`。
+  摘要用于区分 `foo-bar` 和 `foo_bar` 等 ID；旧版生成引用仍可识别，不随意修改外部或自定义引用。
 - cc-switch 的数据库以只读方式打开，永不写入。
 - 安装管理器在 Windows 下为 Claude Code、Codex CLI、pi、opencode、Hermes 和 DeepSeek Harness
   使用原生安装命令。Oh My Pi 与 prime-agent 仍需使用各自的 Windows 安装方式；WorkBuddy
@@ -242,8 +317,12 @@ npm run dev -- ...  # 通过 tsx 从源码运行
 
 每个智能体是 [`src/targets/`](./src/targets) 下的一个适配器，实现
 `apply` / `prune` / `current` / `candidates`；只读的导入来源放在
-[`src/sources/`](./src/sources)。新增一个应用 = 一个文件 +
-[`src/targets/index.ts`](./src/targets/index.ts) 里的一行。
+[`src/sources/`](./src/sources)。新增应用时，在
+[`src/targets/index.ts`](./src/targets/index.ts) 注册，用 `transactionalTarget()` 包装适配器，
+并为 `rename.ts`、`remove.ts` 补充对应配置结构与引用处理。
+复用共享凭据、YAML/JSONC、URL 和模型工具，补齐同步、清理、导入、重命名、删除、
+异常输入、预览及账户隔离测试；支持安装的应用还需在 `apps.ts` 中注册平台命令。
+删除 WorkBuddy 本地账户时，使用 `list --apps workbuddy` 显示的稳定账户标识，避免同域名歧义。
 
 ## 许可证
 

package/dist/apps.js

@@ -1,6 +1,7 @@
 import { execFileSync, execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import semver from "semver";
 import { appDataDir, home, readJsonIfExists } from "./fsutil.js";
 export const appPackages = [
     {
@@ -137,12 +138,20 @@ export function installedVersion(app) {
     if (app.binary) {
         try {
             const binary = executableName(app.binary);
-            const out = execFileSync(binary, app.versionArgs ?? ["--version"], {
+            const args = app.versionArgs ?? ["--version"];
+            const isBatch = process.platform === "win32" && /\.(cmd|bat)$/i.test(binary);
+            const quote = (value) => {
+                if (/["%\r\n]/.test(value))
+                    throw new Error("unsupported Windows version-probe argument");
+                return `"${value}"`;
+            };
+            const out = execFileSync(isBatch ? process.env.ComSpec || "cmd.exe" : binary, isBatch ? ["/d", "/s", "/c", `"${[binary, ...args].map(quote).join(" ")}"`] : args, {
                 encoding: "utf8",
                 timeout: 15000,
                 stdio: ["ignore", "pipe", "pipe"],
+                ...(isBatch ? { windowsVerbatimArguments: true } : {}),
             });
-            return SEMVERISH.exec(out)?.[0];
+            return normalizeAppVersion(SEMVERISH.exec(out)?.[0]) ?? "?";
         }
         catch {
             // binary present but probe failed (e.g. runtime version gate) -> installed, version unknown
@@ -200,25 +209,27 @@ export async function latestVersion(app) {
         return undefined;
     }
 }
-/** numeric-aware semver-ish comparison; true when b is newer than a */
+/** Accept SemVer (including prereleases), with the legacy two-component display form. */
+export function normalizeAppVersion(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const version = value.trim();
+    return semver.valid(version) ?? (/^v?\d+\.\d+$/.test(version) ? semver.valid(`${version}.0`) ?? undefined : undefined);
+}
+/** Build metadata has no precedence; prereleases sort before the corresponding release. */
 export function isNewer(installed, latest) {
-    const pa = installed.split(/[.+-]/).map(Number);
-    const pb = latest.split(/[.+-]/).map(Number);
-    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-        const a = pa[i] ?? 0;
-        const b = pb[i] ?? 0;
-        if (Number.isNaN(a) || Number.isNaN(b))
-            break;
-        if (b > a)
-            return true;
-        if (b < a)
-            return false;
-    }
-    return false;
+    const before = normalizeAppVersion(installed);
+    const after = normalizeAppVersion(latest);
+    return before !== undefined && after !== undefined && semver.gt(after, before);
 }
 /** Run an install/upgrade command with live output. Throws on nonzero exit. */
 export function runShell(command) {
-    execSync(command, { stdio: "inherit", env: process.env });
+    if (process.platform === "win32") {
+        execSync(command, { stdio: "inherit", env: process.env });
+    }
+    else {
+        execFileSync("bash", ["-o", "pipefail", "-c", command], { stdio: "inherit", env: process.env });
+    }
 }
 /** Resolve the platform-specific command while keeping the package table readable. */
 export function appCommand(app, action, platform = process.platform) {
@@ -227,34 +238,27 @@ export function appCommand(app, action, platform = process.platform) {
     return action === "install" ? app.installCmd : app.upgradeCmd ?? app.installCmd;
 }
 function executableName(binary) {
-    if (process.platform !== "win32")
-        return binary;
-    for (const suffix of ["", ".cmd", ".exe", ".bat"]) {
-        const candidate = `${binary}${suffix}`;
-        if (binaryOnPath(candidate))
-            return candidate;
+    return findBinary(binary) ?? binary;
+}
+function findBinary(binary) {
+    const names = process.platform === "win32" && !path.extname(binary)
+        ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((suffix) => `${binary}${suffix.toLowerCase()}`)
+        : [binary];
+    const dirs = path.isAbsolute(binary) ? [""] : (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        for (const name of names) {
+            const file = path.resolve(dir.replace(/^"|"$/g, ""), name);
+            try {
+                if (!fs.statSync(file).isFile())
+                    continue;
+                fs.accessSync(file, process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
+                return file;
+            }
+            catch { /* Try the next executable; directories and inaccessible files are not commands. */ }
+        }
     }
-    return binary;
+    return undefined;
 }
 export function binaryOnPath(binary) {
-    const dirs = (process.env.PATH ?? "").split(path.delimiter);
-    return dirs.some((d) => {
-        try {
-            const names = process.platform === "win32" && !path.extname(binary)
-                ? [binary, ...((process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((s) => `${binary}${s.toLowerCase()}`))]
-                : [binary];
-            return names.some((name) => {
-                try {
-                    fs.accessSync(path.join(d, name), process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
-                    return true;
-                }
-                catch {
-                    return false;
-                }
-            });
-        }
-        catch {
-            return false;
-        }
-    });
+    return findBinary(binary) !== undefined;
 }