修改代码后：推 GitHub、发 npm、本机更新插件/Agent
May 8, 2026 · View on GitHub
本文档供维护者在改完仓库内文件后，按固定顺序发布并更新本机环境。包名以 paperfit-cli、远程以 OpenRaiser/PaperFit 为例，请按你的 fork/组织替换。
一、推送到 GitHub
在包仓库根目录（含 package.json 的目录）执行：
git status
git diff
git add -A
git commit -m "feat: 简述本次改动"
git pull origin main --rebase # 若团队用 main；有冲突先解决
git push origin main
若本次发 npm 且使用 npm version 打的 tag（见下文），还需：
git push origin v1.0.6 # 换成实际版本 tag
可选：在 GitHub 网页 Releases 里基于该 tag 写 Release notes，便于用户查看变更。
二、发布到 npm（paperfit-cli）
2.1 前置条件
- 已安装 Node.js（建议 ≥18，与
package.json的engines一致）。 - 已登录 npm：
npm whoami能显示用户名。 - 当前账号对
paperfit-cli有 publish 权限（npm owner ls paperfit-cli）。 - 工作区干净：
npm version会要求无未提交改动；否则先git commit或使用npm version patch --no-git-tag-version（仅改版本号，不自动 commit）。
2.2 版本号
在项目根目录任选其一：
# 推荐：自动改 package.json + package-lock.json，并生成 git commit 与 tag
npm version patch -m "chore: release %s" # 1.0.5 → 1.0.6
# npm version minor
# npm version major
若工作区不干净：
npm version patch --no-git-tag-version
# 再手动 git add package.json package-lock.json && git commit && git tag v… && push
2.3 发布
npm publish --access public
- 若账号开启 2FA（auth-and-writes）：需使用验证器里的 6 位 TOTP，例如
npm publish --access public --otp=123456（123456 仅为格式示例，请换成实时码）。 - 或使用 npm 网站生成的 Granular Access Token 写入
~/.npmrc的//registry.npmjs.org/:_authToken=...，可减少交互式 OTP 场景（以 npm 当前策略为准）。
2.4 发版后自检
npm view paperfit-cli version
npm install -g paperfit-cli@latest
paperfit --version
paperfit doctor --target claude
2.4.1 发布前校验说明
发布前至少完成以下基础校验：
| 命令 | 覆盖范围 | 适用时机 |
|---|---|---|
npm run verify | 配置校验、Node 语法检查、Python warning gate | 日常提交前、发版前 |
paperfit doctor --target <host> | 宿主环境与安装状态体检 | 本机发版验证、安装器改动后 |
对应 CI：
.github/workflows/ci.yml：基础校验链，运行npm run verify
2.5 常见问题
| 现象 | 处理 |
|---|---|
Git working directory not clean | 先提交或 stash，或 --no-git-tag-version。 |
E404 / 无权限 | 确认 npm whoami，联系包 owner 执行 npm owner add <你> paperfit-cli。 |
EOTP | 使用认证器当前 6 位码；不要用占位数字。 |
| 同一版本不能二次发布 | 再执行一次 npm version patch 升版本后 publish。 |
注意：发布前确认 package.json 的 files 字段不会把 __pycache__、*.pyc 等打进包；若本地有 scripts/__pycache__/，应加入 .gitignore / .npmignore 或在发版前删除。
三、本机更新「新版 CLI + 插件/Agent/命令」
全局安装的 paperfit 与复制到宿主目录的 commands/skills/agents/rules 不是同一步：升级 npm 包后，需要再跑一次安装脚本，把包内 canonical 资产同步到目标宿主目录（如 ~/.claude、~/.codex、~/.cursor）与共享目录 ~/.paperfit。
3.0 一键更新部署（一条命令做完 npm + 宿主目录同步）
仅更新 Claude 插件不会出现 paperfit 命令；必须装/更新 npm 全局包 paperfit-cli。
| 情况 | 命令 |
|---|---|
任意目录（不必 cd 克隆） | npx -y paperfit-cli@latest upgrade --target claude |
本机已有 paperfit | paperfit upgrade --target claude 或 cd <克隆根> && paperfit upgrade --local --target claude |
仅在克隆根目录（必须有 package.json） | bash install.sh --update --local --target claude |
还没有 paperfit、也不 npx | bash install.sh --update --target claude 或 curl …/install.sh | bash -s -- --update --target claude |
也可以改成 --target codex、--target cursor 或 --target all。
常见错误：在 ~ 家目录执行 npm run upgrade → npm 会找 ~/package.json，不存在即 ENOENT。请先 cd 到克隆根，或改用 npx -y paperfit-cli@latest upgrade --target ... / paperfit upgrade --target ...。
完成后仍建议在 Claude 里执行 §3.3 的 /plugin marketplace update 与 /plugin update，插件版本与 npm 独立。
3.1 更新全局 CLI（npm 包本体）
npm install -g paperfit-cli@latest
# 或指定版本
npm install -g paperfit-cli@1.0.6
paperfit --version
3.2 把包内命令/技能/Agent 合并到本机 Claude Code
在任意目录均可执行（脚本会读已安装包路径）：
paperfit install-global --target claude
首次想预览将写入的文件：
paperfit install-global --target claude --dry-run
该步骤会把 paperfit-cli 包内的 commands / skills / agents / rules / config 按 install-host-global.js 的逻辑同步到目标宿主目录与 ~/.paperfit（具体以 config/install_targets.json 为准）。
3.3 用 Claude Code 插件更新（只贴斜杠命令，在聊天框逐条执行）
前提：市场名 paperfit-vto、插件标识 paperfit@paperfit-vto 与仓库内 PaperFit-release/.claude-plugin/marketplace.json 一致；若你 fork 了仓库，把下面 GitHub 路径换成你的。
首次：添加市场 + 安装插件
/plugin marketplace add OpenRaiser/PaperFit
/plugin install paperfit@paperfit-vto
或用 HTTPS 添加市场（与上一行二选一即可）：
/plugin marketplace add https://github.com/OpenRaiser/PaperFit
/plugin install paperfit@paperfit-vto
日常：拉到 GitHub 上最新插件内容
先看已装列表（确认名字，一般是 paperfit）：
/plugin list
优先尝试更新（若 CLI 提示不支持该子命令，改用下面「卸载再装」）：
/plugin update paperfit@paperfit-vto
强制与远端一致（等价于重装最新 commit）：
/plugin uninstall paperfit@paperfit-vto
/plugin install paperfit@paperfit-vto
和 npm 的关系（两条线）
| 做什么 | 用哪里 |
|---|---|
更新 paperfit / paperfit run / Python 脚本 | 终端：npm install -g paperfit-cli@latest（见 3.1） |
| 更新 斜杠命令 / Agent / Skill 文本（来自 Git 的插件） | Claude：上表 /plugin update 或 uninstall + install |
发完 npm 且已 git push 后，建议 终端 3.1 + 3.2 与 Claude 本节 都做一遍，避免只升一半。
3.4 只跟 Git 开发、不发 npm 时
终端（克隆目录内）：
git pull
npm install
paperfit install-global --target claude
Claude：仍须执行 3.3 里的 /plugin update paperfit@paperfit-vto；若无该命令，则用 /plugin uninstall + /plugin install，否则编辑器里仍是旧版插件资源。
四、推荐一条龙（发 npm 的 release 日）
终端：
git pull origin main
# … 改代码 …
git add -A && git commit -m "feat: …"
npm version patch -m "chore: release %s"
git push origin main
git push origin --tags
npm publish --access public --otp=<实时6位> # 或已配置 token
paperfit upgrade --target claude
# 或在克隆目录: npm run upgrade
Claude（同一台机器、要更新插件时，在会话里再执行）：
/plugin update paperfit@paperfit-vto
若无 update 或失败：
/plugin uninstall paperfit@paperfit-vto
/plugin install paperfit@paperfit-vto
五、版本与文档同步
- 发 npm 前确认
package.json的version与 CHANGELOG / README 中对外版本描述一致（若有）。 - GitHub 默认分支上的
README.md与 npm 包内files包含的 README 应同源，避免用户看到两套说明。
维护者可按团队规范增删「CI 发版」「GitHub Actions」等段落；本文仅覆盖本地手工流程。若某条 /plugin 子命令在你当前 Claude Code 版本中不存在，以官方命令补全或插件面板按钮为准。