update-packages

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Packages

包更新

First Step: Update Skills + Create Branch (MANDATORY)

第一步：更新Skills并创建分支（必填）

Before touching any packages, update the skills themselves and create a dedicated branch.

How to update skills:

Read
```
skills-lock.json
```
in the project root

Group skills by unique

source

field (e.g.

blogic-cz/blogic-marketplace

blogic-cz/agent-tools

, etc.)

Run
```
npx skills add <source> --all -g -y
```
in parallel — one command per unique source repo, all running simultaneously with
```
&
```
+
```
wait
```
Do NOT use
```
npx skills update
```
— it clones the repo separately for each skill and is extremely slow

Global lock health check (Bun, mandatory before package work):

bash

bun -e 'import { readFileSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; const p = join(homedir(), ".agents", ".skill-lock.json"); const d = JSON.parse(readFileSync(p, "utf8")); const m = Object.entries(d.skills ?? {}).filter(([, v]) => !(v && v.skillFolderHash)).map(([k]) => k); console.log(m.length, m); if (m.length > 0) process.exit(1);'

If the command returns non-zero, fix missing hashes first (otherwise

skills check/update

can incorrectly report "up to date" because entries with empty

skillFolderHash

are skipped):

bash

bun -e 'import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { tmpdir, homedir } from "node:os"; const lockPath = join(homedir(), ".agents", ".skill-lock.json"); const lock = JSON.parse(readFileSync(lockPath, "utf8")); const missing = Object.entries(lock.skills ?? {}).filter(([, v]) => !(v && v.skillFolderHash) && v?.sourceType === "github" && typeof v?.skillPath === "string"); if (missing.length === 0) { console.log("no missing hashes"); process.exit(0); } const repoTmp = mkdtempSync(join(tmpdir(), "skills-hash-")); const repoDir = join(repoTmp, "repo"); await Bun.$`git clone --depth 1 https://github.com/blogic-cz/blogic-marketplace.git ${repoDir}`.quiet(); for (const [name, meta] of missing) { const skillDir = String(meta.skillPath).replace(/\/SKILL\.md$/, ""); const out = (await Bun.$`git -C ${repoDir} ls-tree HEAD ${skillDir}`.quiet().text()).trim(); const hash = out.split(/\s+/)[2]; if (!hash) throw new Error(`Cannot resolve hash for ${name}`); lock.skills[name].skillFolderHash = hash; } writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8"); rmSync(repoTmp, { recursive: true, force: true }); console.log(`updated ${missing.length} entries`);'

For repeatable local updates with an agent allowlist, use the reusable Bun helper in

references/skills-update-local.ts

Typical usage from a project root with

skills-lock.json

bash

bun run scripts/skills-update-local.ts --dry-run
bun run scripts/skills-update-local.ts --source blogic-cz/blogic-marketplace --agent codex,opencode --concurrency 2

Then create a dedicated branch:

bash

but branch new chore/update-packages-$(date +%y%m%d-%H%M)

Rules:

Always update skills first — skills may contain updated instructions for this very workflow
Group by source and run in parallel — each clone installs all skills from that source at once
Never reuse an existing update-packages branch
Always create a fresh branch with the current timestamp
All package update commits go to this branch

在修改任何包之前，请先更新Skills本身并创建一个专用分支。

如何更新Skills：

读取项目根目录下的
```
skills-lock.json
```
按唯一的
```
source
```
字段对Skills进行分组（例如
```
blogic-cz/blogic-marketplace
```
、
```
blogic-cz/agent-tools
```
等）
并行运行
```
npx skills add <source> --all -g -y
```
—— 每个唯一的源仓库对应一条命令，使用
```
&
```
+
```
wait
```
让所有命令同时运行
不要使用
```
npx skills update
```
—— 它会为每个Skill单独克隆仓库，速度极慢

全局锁健康检查（Bun，包操作前必填）：

bash

bun -e 'import { readFileSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; const p = join(homedir(), ".agents", ".skill-lock.json"); const d = JSON.parse(readFileSync(p, "utf8")); const m = Object.entries(d.skills ?? {}).filter(([, v]) => !(v && v.skillFolderHash)).map(([k]) => k); console.log(m.length, m); if (m.length > 0) process.exit(1);'

如果命令返回非零值，请先修复缺失的哈希值（否则

skills check/update

会错误地报告“已更新至最新版本”，因为带有空

skillFolderHash

的条目会被跳过）：

bash

bun -e 'import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { tmpdir, homedir } from "node:os"; const lockPath = join(homedir(), ".agents", ".skill-lock.json"); const lock = JSON.parse(readFileSync(lockPath, "utf8")); const missing = Object.entries(lock.skills ?? {}).filter(([, v]) => !(v && v.skillFolderHash) && v?.sourceType === "github" && typeof v?.skillPath === "string"); if (missing.length === 0) { console.log("no missing hashes"); process.exit(0); } const repoTmp = mkdtempSync(join(tmpdir(), "skills-hash-")); const repoDir = join(repoTmp, "repo"); await Bun.$`git clone --depth 1 https://github.com/blogic-cz/blogic-marketplace.git ${repoDir}`.quiet(); for (const [name, meta] of missing) { const skillDir = String(meta.skillPath).replace(/\/SKILL\.md$/, ""); const out = (await Bun.$`git -C ${repoDir} ls-tree HEAD ${skillDir}`.quiet().text()).trim(); const hash = out.split(/\s+/)[2]; if (!hash) throw new Error(`Cannot resolve hash for ${name}`); lock.skills[name].skillFolderHash = hash; } writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8"); rmSync(repoTmp, { recursive: true, force: true }); console.log(`updated ${missing.length} entries`);'

如果需要通过Agent白名单进行可重复的本地更新，请使用

references/skills-update-local.ts

中的可复用Bun工具函数。

从带有

skills-lock.json

的项目根目录的典型用法：

bash

bun run scripts/skills-update-local.ts --dry-run
bun run scripts/skills-update-local.ts --source blogic-cz/blogic-marketplace --agent codex,opencode --concurrency 2

然后创建专用分支：

bash

but branch new chore/update-packages-$(date +%y%m%d-%H%M)

规则：

始终先更新Skills —— Skills可能包含针对此工作流的更新说明
按源分组并并行运行 —— 每个克隆会一次性安装该源下的所有Skills
不要重复使用现有的update-packages分支
始终创建带有当前时间戳的新分支
所有包更新提交都要推送到此分支

Definition of Done

完成标准

```
bun upgrade
```
shows all packages at latest versions
No packages remain to select or update
All checks pass (
```
bun run check
```
)
All relevant tests pass

```
bun upgrade
```
显示所有包均为最新版本
没有待选择或更新的包
所有检查通过（
```
bun run check
```
）
所有相关测试通过

If Bun Updates

当Bun更新时

When the Bun runtime itself has a new version:

Update

packageManager

field in root

package.json

json

"packageManager": "bun@X.Y.Z"

Update all Dockerfiles that reference
```
BUN_VERSION
```
:
dockerfile
```
ARG BUN_VERSION=X.Y.Z
```
Update CI pipeline
```
BUN_VERSION
```
environment variable in all relevant pipeline files.
Run checks to confirm nothing broke:
bash
```
bun run check
```
Commit message format:
```
chore: update bun to vX.Y.Z
```

当Bun运行时本身有新版本时：

更新根目录

package.json

中的

packageManager

字段：

json

"packageManager": "bun@X.Y.Z"

更新所有引用
```
BUN_VERSION
```
的Dockerfile：
dockerfile
```
ARG BUN_VERSION=X.Y.Z
```
更新所有相关流水线文件中CI流水线的
```
BUN_VERSION
```
环境变量。
运行检查以确认没有问题：
bash
```
bun run check
```
提交消息格式：
```
chore: update bun to vX.Y.Z
```

If Playwright Updates

当Playwright更新时

When

@playwright/test

playwright

npm version changes:

The Docker image version must match the npm package version exactly.
Find all references to the Playwright Docker image across:
- ```
Dockerfile
```
  files
- CI/CD pipeline YAML files
- Kubernetes Helm values files
- Any other infrastructure files
Update all references to use the matching image tag:
```
mcr.microsoft.com/playwright:vX.Y.Z-noble
```
Run E2E tests to confirm compatibility:
bash
```
bun run test:e2e
```
Commit message format:
```
chore: update playwright to vX.Y.Z
```

当

@playwright/test

或

playwright

的npm版本变更时：

Docker镜像版本必须与npm包版本完全匹配。
查找所有引用Playwright Docker镜像的位置：
- ```
Dockerfile
```
  文件
- CI/CD流水线YAML文件
- Kubernetes Helm值文件
- 任何其他基础设施文件
更新所有引用以使用匹配的镜像标签：
```
mcr.microsoft.com/playwright:vX.Y.Z-noble
```
运行端到端测试以确认兼容性：
bash
```
bun run test:e2e
```
提交消息格式：
```
chore: update playwright to vX.Y.Z
```

Catalog Packages

目录包

Some packages are managed via Bun's catalog and require manual version checking:

bash

undefined

部分包通过Bun的目录进行管理，需要手动检查版本：

bash

undefined

Check latest version of a catalog package

检查目录包的最新版本

npm view <package-name> version

Check all versions available

查看所有可用版本

npm view <package-name> versions --json


Update catalog entries in `package.json` or `bun.lockb` manually after confirming the latest version.

npm view <package-name> versions --json


确认最新版本后，手动更新`package.json`或`bun.lockb`中的目录条目。

Package Groups (Update Together)

包组（需一起更新）

These packages must always be updated as a group — mismatched versions cause type errors or runtime failures:

Group	Packages
tanstack-router	`@tanstack/react-router` , `@tanstack/router-devtools` , `@tanstack/router-plugin` , `@tanstack/start`
tanstack-query	`@tanstack/react-query` , `@tanstack/react-query-devtools` , `@tanstack/query-core`
trpc	`@trpc/server` , `@trpc/client` , `@trpc/react-query` , `@trpc/tanstack-react-query`
effect	`effect` , `@effect/schema` , `@effect/platform` , `@effect/language-service`
drizzle	`drizzle-orm` , `drizzle-kit` , `drizzle-zod`
pino	`pino` , `pino-pretty` , `@types/pino`
playwright	`@playwright/test` , `playwright` (+ Docker image sync — see above)

这些包必须始终作为一组更新 —— 版本不匹配会导致类型错误或运行时故障：

组	包
tanstack-router	`@tanstack/react-router` , `@tanstack/router-devtools` , `@tanstack/router-plugin` , `@tanstack/start`
tanstack-query	`@tanstack/react-query` , `@tanstack/react-query-devtools` , `@tanstack/query-core`
trpc	`@trpc/server` , `@trpc/client` , `@trpc/react-query` , `@trpc/tanstack-react-query`
effect	`effect` , `@effect/schema` , `@effect/platform` , `@effect/language-service`
drizzle	`drizzle-orm` , `drizzle-kit` , `drizzle-zod`
pino	`pino` , `pino-pretty` , `@types/pino`
playwright	`@playwright/test` , `playwright` （+ Docker镜像同步 —— 见上文）

Update Strategy

更新策略

Core Principle: Update + Analyze in Parallel

核心原则：并行更新与分析

Release notes analysis happens simultaneously with each package group update — not after. When

bun run check

fails, you already have migration guides and know exactly what changed.

发布说明分析与每个包组的更新同时进行 —— 而非之后。当

bun run check

失败时，你已经有了迁移指南，并且确切知道发生了哪些变更。

Per Package Group Flow

每个包组的流程

For each package group (see Package Groups table above), execute steps 1-4 before moving to the next group:

Step 1 — Identify versions (old → new)

Run
```
bun upgrade
```
interactively, note which packages have minor/major bumps
For catalog packages:
```
npm view <package> version
```
to find latest

Step 2 — Update + Analyze release notes IN PARALLEL

Do both at the same time:

Track A: Apply Update	Track B: Analyze Release Notes (background subagents)
Apply version bumps ( `bun upgrade` selection or catalog edit)	For each minor/major bump: `npm view <package> repository.url` → `gh release view <tag> --repo <owner/repo>` (fallback: `CHANGELOG.md` )
`bun install` if catalog	Major: breaking changes, migration guides, removed APIs
	Minor: new APIs, deprecations, opt-in improvements
	Search project codebase for usages of changed/deprecated/new APIs

Parallelization: packages from the same ecosystem (per Package Groups table) share one background subagent. Standalone packages get one subagent each. Each subagent reads release notes AND searches the codebase for affected usages.

Step 3 — Check + Fix with context

Run
```
bun run check
```
If check fails: consult the release notes analysis from Step 2 — you know what changed, have migration guides, and can fix with full context instead of blind trial-and-error
Fix any breaking changes using the migration info

Step 4 — Commit the group

Commit the update with appropriate message before moving to next group

对于每个包组（见上文的包组表格），在进入下一个组之前执行步骤1-4：

步骤1 —— 确定版本（旧→新）

交互式运行
```
bun upgrade
```
，记录哪些包有小版本/大版本更新
对于目录包：使用
```
npm view <package> version
```
查找最新版本

步骤2 —— 并行执行更新与发布说明分析

同时执行以下两项操作：

轨道A：应用更新	轨道B：分析发布说明（后台子Agent）
应用版本升级（ `bun upgrade` 选择或目录编辑）	对于每个小版本/大版本更新： `npm view <package> repository.url` → `gh release view <tag> --repo <owner/repo>` （备选：查看 `CHANGELOG.md` ）
若为目录包则运行 `bun install`	大版本变更：破坏性变更、迁移指南、移除的API
	小版本变更：新API、废弃通知、可选改进
	搜索项目代码库中已变更/废弃/新增API的使用情况

并行策略：同一生态系统的包（按包组表格）共享一个后台子Agent。独立包各自使用一个子Agent。每个子Agent会读取发布说明并搜索代码库中受影响的使用情况。

步骤3 —— 检查并结合上下文修复

运行
```
bun run check
```
如果检查失败：参考步骤2中的发布说明分析 —— 你知道发生了哪些变更，有迁移指南，可以结合完整上下文进行修复，而非盲目试错
使用迁移信息修复任何破坏性变更

步骤4 —— 提交组更新

在进入下一个组之前，使用适当的提交消息提交此次更新

Release Notes Report

发布说明报告

After all groups are updated, output a unified summary table:

| Package | Type | Old → New | Changes | Impact & Suggestions |
|---------|------|-----------|---------|----------------------|
| effect | MAJOR | 3.x → 4.0 | `Layer` API redesigned | ⚠️ 12 files use `Layer.succeed` → must change to `Layer.sync`. Files: src/services/Auth.ts:14, src/services/Db.ts:8, ... See migration: https://... |
| drizzle-orm | MINOR | 0.38 → 0.39 | `.having()` support | ❌ No aggregate queries in project |
| @tanstack/react-router | MINOR | 1.90 → 1.91 | `beforeLoad` abort signal | ✅ src/routes/dashboard.tsx:23 has slow loader — add `abortSignal` to cancel stale fetches. Suggested diff: `beforeLoad: ({ abortController }) => ...` |

Skip patch-only updates in this report.

所有包组更新完成后，输出统一的汇总表格：

| 包 | 类型 | 旧→新 | 变更内容 | 影响与建议 |
|---------|------|-----------|---------|----------------------|
| effect | 大版本 | 3.x → 4.0 | `Layer` API重新设计 | ⚠️ 12个文件使用了`Layer.succeed` → 必须改为`Layer.sync`。文件：src/services/Auth.ts:14, src/services/Db.ts:8, ... 查看迁移指南：https://... |
| drizzle-orm | 小版本 | 0.38 → 0.39 | 支持`.having()` | ❌ 项目中没有聚合查询 |
| @tanstack/react-router | 小版本 | 1.90 → 1.91 | `beforeLoad`中止信号 | ✅ src/routes/dashboard.tsx:23有慢加载器 —— 添加`abortSignal`以取消过时的请求。建议差异：`beforeLoad: ({ abortController }) => ...` |

此报告中跳过仅补丁版本的更新。

Release Notes Rules

发布说明规则

Each subagent MUST search the codebase for usages of changed/deprecated/new APIs
For breaking changes: list all affected files with line numbers and provide migration snippets
For new features: identify where in the project they could be adopted and show suggested code changes
Do NOT apply adoption suggestions — provide diffs/suggestions only, user decides
Packages with no releases/changelog → "no release notes available", move on

每个子Agent必须搜索代码库中已变更/废弃/新增API的使用情况
对于破坏性变更：列出所有受影响的文件及行号，并提供迁移代码片段
对于新功能：确定项目中可采用这些功能的位置，并展示建议的代码变更
不要直接应用采用建议 —— 仅提供差异/建议，由用户决定
无发布说明/变更日志的包 → 标注“无可用发布说明”，继续处理

Testing Requirements

测试要求

Update Type	Required Tests
UI/component packages ( `@base-ui/react` , etc.)	`bun run check` + visual review in browser
TRPC / TanStack Router	`bun run check` + `bun run test`
Drizzle ORM	`bun run check` + `bun run test`
Effect packages	`bun run check` + `bun run test`
Playwright	`bun run check` + `bun run test:e2e`
Bun runtime	`bun run check` + `bun run test` + `bun run test:e2e`
All others	`bun run check`

更新类型	必填测试
UI/组件包（ `@base-ui/react` 等）	`bun run check` + 浏览器可视化审查
TRPC / TanStack Router	`bun run check` + `bun run test`
Drizzle ORM	`bun run check` + `bun run test`
Effect包	`bun run check` + `bun run test`
Playwright	`bun run check` + `bun run test:e2e`
Bun运行时	`bun run check` + `bun run test` + `bun run test:e2e`
其他所有	`bun run check`

Cache Recovery (Bun)

缓存恢复（Bun）

If packages fail to install or you see stale cache errors after updating:

bash

bun clean:packages && bun install

This clears the local package cache and performs a fresh install.

如果包安装失败，或更新后看到缓存过期错误：

bash

bun clean:packages && bun install

这会清除本地包缓存并执行全新安装。

Common Breaking Changes

常见破坏性变更

Package	Common Issue	Fix
`@effect/language-service`	Version must match `effect` core exactly	Always update together with `effect`
`@types/react`	React 19 types changed significantly; some third-party types conflict	Check peer deps, may need `--legacy-peer-deps` workaround or type overrides
`@base-ui/react`	API surface changes frequently in pre-stable releases	Review changelog, update component usage accordingly

包	常见问题	修复方案
`@effect/language-service`	版本必须与 `effect` 核心包完全匹配	始终与 `effect` 一起更新
`@types/react`	React 19类型变更显著；部分第三方类型冲突	检查对等依赖，可能需要使用 `--legacy-peer-deps` workaround或类型覆盖
`@base-ui/react`	预稳定版本中API表面频繁变更	查看变更日志，相应更新组件用法

Guardrails

防护措施

DO NOT update packages with
```
workspace:*
```
version specifiers — these are internal monorepo packages managed separately
DO NOT skip
```
@typescript/native-preview
```
updates — this package affects TypeScript LSP performance and should stay current
DO NOT use
```
bun outdated
```
to check for updates — it misses packages that are in the catalog or have non-standard version specifiers; use
```
bun upgrade
```
interactively instead

不要更新版本指定符为
```
workspace:*
```
的包 —— 这些是内部单仓包，由单独流程管理
不要跳过
```
@typescript/native-preview
```
的更新 —— 此包会影响TypeScript LSP性能，应保持最新
不要使用
```
bun outdated
```
检查更新 —— 它会遗漏目录中的包或带有非标准版本指定符的包；请改用交互式的
```
bun upgrade
```