参与开发
本地开发环境、常用命令、CI 命令行、文档站的构建方式、发布流程和新增 npm 包的步骤。
环境要求
| 工具 | 版本 | 声明位置 |
|---|---|---|
| Node.js | 24 起 | package.json 的 engines 字段 |
| pnpm | 11 | package.json 的 packageManager 字段 |
| uv | 见配置 | scripts/ci/pyproject.toml 的 required-version |
常用命令
pnpm install
pnpm check # oxfmt --check、oxlint 类型检查与 vitest，CI 运行的就是它
pnpm bundle # 更新 dist/ 与 dsh/*/dist/：DSH、Cline 插件与 agent-stash 命令行都从这里加载
pnpm format工作区包放在 packages/ 下，各自的 bundle 脚本产出随仓库提交的 dist/；dsh/recall、dsh/autosuggest 与 dsh/kit 也是工作区包，由根目录的 pnpm bundle 构建。构建、上游同步、插件索引、文档站和 npm 相关的 CI 步骤由 scripts/ci 里的 Python 命令行执行（uv + Typer），pnpm check 与发布用的 pnpm tegami ci 由 workflow 直接调用。本地可以用同样的命令复现：
uv run --project scripts/ci ci --help
uv run --project scripts/ci ci bundle --check # 重建所有工作区包的 dist/，与检出内容不一致时失败
uv run --project scripts/ci ci npm status # 列出各包在 npm 上的版本与是否经 trusted publishing 发布仓库结构
文档站
文档站在 docs/ 下，是一个静态导出的 Fumadocs 站点。.github/workflows/pages.yml 用 ci docs 构建它、用 ci plugin-index 生成插件索引，两者放进同一个 GitHub Pages 产物：改动 docs/ 的 Pull Request 只构建预览产物，main 上的运行才部署。页面在 docs/content/docs/ 下，中文页面是 *.mdx，英文页面是同名的 *.en.mdx。
pnpm --filter agent-stash-docs dev # http://localhost:3883/agent-stash/
pnpm --filter agent-stash-docs build # 输出到 docs/out/截图与录屏放在 docs/public/media/，尺寸登记在 docs/lib/media.ts，页面用 <Showcase> 展示。英文页用同一段操作在英文界面下的录制，场景名带 -en 后缀。插件页与技能页末尾的贡献者和页面历史在构建时从 Git 读取，构建环境需要完整的提交历史；新页面提交之后才显示它们。
发布
版本号遵循语义化版本，由 Tegami 管理，配置在 scripts/tegami.ts。
写变更说明
在 .tegami/ 下新建 Markdown 文件，frontmatter 写明每个改动的包与升级类型（major、minor 或 patch），正文是用中文写的发布说明。正文至少要有一个 Markdown 标题，没有标题的文件 Tegami 不会读取：
---
packages:
"@agent-stash/init": minor
---
## 新增 xxx 预设
- xxx 预设从上游每天同步。合并 Version Packages PR
推送到 main 后，.github/workflows/release.yml 开 Version Packages PR，更新各包的版本号与 CHANGELOG.md。
发布到 npm
合并这个 PR 后，同一个 workflow 经 npm trusted publishing（OIDC）把升级过的包发布到 npm 并附带 provenance，然后打 tag、创建 GitHub release：@agent-stash/init 用 v<version>，其他包用 <name>@<version>。workflow 等到 npm 能安装新版本才结束，随后运行的 Pages 工作流重新生成插件索引和文档站。
只用 trusted publishing 发布
npm 上的包禁止用可以绕过 2FA 的令牌发布，CI 只通过 trusted publishing 发布。
README 里的版本 badge 自动读取最新的 GitHub release。
新增 npm 包
npm 只能给已经存在的包配置 Trusted Publisher，新包要先用一次性的令牌占个名字：
存入一次性令牌
在 npmjs.com 生成一个只用于这一步的发布令牌，复制到剪贴板后运行 uv run --project scripts/ci ci bootstrap store-token，它把剪贴板内容存成仓库的 NPM_TOKEN secret 并清空剪贴板。
发布占位版本
运行 uv run --project scripts/ci ci bootstrap publish --auth token：release workflow 用令牌给还没有正式版本的包发布一个空的 0.0.0-placeholder.<n>（dist-tag placeholder）。
添加 Trusted Publisher
在包的 npm 设置页添加 Trusted Publisher：仓库 Alice39s/agent-stash，workflow release.yml。
改用 OIDC 发布
运行 uv run --project scripts/ci ci bootstrap publish --auth oidc，确认 ci npm status 显示 trusted publishing 为 yes。
移除令牌
运行 uv run --project scripts/ci ci bootstrap remove-token，在 npmjs.com 吊销令牌，并把包的发布权限设为禁止绕过 2FA 的令牌。
最后更新于