x7-code-line 0.3.0 → 0.4.0

package/README.md

@@ -1,407 +1,421 @@
-# x7-code-line
-
-`x7-code-line` 是一个用于安装 Cursor、Codex 和 Git hooks 的 npm 模块。它用于在 agent 工作流中区分普通用户已有改动和 AI 生成改动，并在提交信息中自动追加 AI 行数 trailer。
-
-## 功能概览
-
-- 安装 Cursor 项目 hooks：写入当前安装目录的 `.cursor/hooks.json`。
-- 安装 Codex 项目 hooks：写入当前安装目录的 `.codex/hooks.json`。
-- 安装 Git hooks：为目标项目写入 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg`。
-- 初始化中心缓存目录：写入当前安装目录的 `.x7-code-line/`。
-- 支持多项目：多项目配置只用于替换目标项目的 Git hooks，以及在 `prompt-submit` / `stop` 时遍历读取这些项目的 `git diff`。
-- 记录普通 diff 行：prompt 提交时读取 `git diff`，把尚未进入 AI 缓存的 diff 行写入普通缓存。
-- 记录 AI diff 行：agent 结束时再次读取 `git diff`，把不属于普通缓存的 diff 行写入 AI 缓存。
-- 计算提交 AI 行数：`pre-commit` 对比当前仓库 staged diff 和中心 AI 缓存，计算本次提交真实包含的 AI diff 行数。
-- 写入 commit trailer：`commit-msg` 追加或替换 `x7-ai-lines: <数量>`。
-
-## 安装行为
-
-作为 npm 依赖安装时，`postinstall` 脚本使用 `INIT_CWD` 作为当前安装目录，也就是执行 `npm install` 时所在的项目目录。
-
-如果只是全局安装：
-
-```sh
-npm install -g x7-code-line
-```
-
-此时只安装 CLI，不会自动为任何项目写入 hooks。全局安装完成后，需要手动执行：
-
-```sh
-x7-code-line install --dir <absolute-path>
-```
-
-只有在 `X7_CODE_LINE_DIRS` 或 `X7_CODE_LINE_CONFIG` 明确提供目标目录时，`postinstall` 才会继续执行项目安装逻辑。
-
-当前安装目录会创建或覆盖：
-
-```text
-.x7-code-line/install.json
-.x7-code-line/projects.json
-.x7-code-line/ai-diff-line-ids.json
-.x7-code-line/normal-diff-line-ids.json
-.cursor/hooks.json
-.codex/hooks.json
-```
-
-如果目标项目存在 `.git`，会创建或覆盖：
-
-```text
-.git/hooks/pre-commit
-.git/hooks/commit-msg
-```
-
-多项目配置只影响两类行为：
-
-- 为配置中的项目目录替换 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg`。
-- 执行 `prompt-submit` / `stop` 时遍历配置中的项目目录读取 `git diff`。
-
-`.cursor/hooks.json`、`.codex/hooks.json` 和 `.x7-code-line/` 只会写入当前安装目录，不会写入每个多项目目标目录。
-
-## Cursor Hooks
-
-Cursor 模板写入 `.cursor/hooks.json`：
-
-```json
-{
-  "hooks": {
-    "beforeSubmitPrompt": [
-      {
-        "command": "npx --no-install x7-code-line prompt-submit"
-      }
-    ],
-    "stop": [
-      {
-        "command": "npx --no-install x7-code-line stop"
-      }
-    ]
-  }
-}
-```
-
-## Codex Hooks
-
-Codex 模板写入 `.codex/hooks.json`：
-
-```json
-{
-  "hooks": {
-    "UserPromptSubmit": [
-      {
-        "command": "npx --no-install x7-code-line prompt-submit"
-      }
-    ],
-    "Stop": [
-      {
-        "command": "npx --no-install x7-code-line stop"
-      }
-    ]
-  }
-}
-```
-
-## Diff 行缓存
-
-`prompt-submit` 会进入每个已缓存的项目目录，执行：
-
-```sh
-git diff --no-ext-diff --unified=0 --no-color
-```
-
-然后对每个变更行计算 ID。ID 由以下信息生成：
-
-- 项目绝对路径
-- 文件路径
-- 变更类型：`add` 或 `delete`
-- 行号
-- 行内容
-- 该文件当前的修改时间
-
-如果该 ID 不在 AI diff 缓存中，就写入普通 diff 缓存：
-
-```text
-.x7-code-line/normal-diff-line-ids.json
-```
-
-`stop` 会再次读取每个项目的 `git diff` 并计算行 ID。如果某个 ID 不在普通 diff 缓存中，就写入 AI diff 缓存：
-
-```text
-.x7-code-line/ai-diff-line-ids.json
-```
-
-缓存按项目绝对路径分组，结构类似：
-
-```json
-{
-  "projects": {
-    "/path/to/repo-a": ["line-id-1"],
-    "/path/to/repo-b": ["line-id-2"]
-  }
-}
-```
-
-## Git Hooks
-
-安装器会生成 shell hook，并写入中心缓存目录：
-
-```sh
-X7_CODE_LINE_BASE='<当前安装目录>'
-export X7_CODE_LINE_BASE
-npx --no-install x7-code-line git-pre-commit
-```
-
-`pre-commit` 会读取当前仓库的 staged diff：
-
-```sh
-git diff --cached --no-ext-diff --unified=0 --no-color
-```
-
-然后使用当前仓库绝对路径从中心缓存中取出对应项目的 AI diff 行 ID，计算本次提交真正包含的 AI diff 行数，并写入：
-
-```text
-.x7-code-line/pending-commit.json
-```
-
-计算完成后，会清除当前仓库在以下两份中心缓存中的条目：
-
-```text
-.x7-code-line/ai-diff-line-ids.json
-.x7-code-line/normal-diff-line-ids.json
-```
-
-其他项目的缓存不会被修改。
-
-`commit-msg` 会读取该结果，并追加或替换 trailer：
-
-```text
-x7-ai-lines: 3
-```
-
-如果没有命中 AI diff 行，则写入：
-
-```text
-x7-ai-lines: 0
-```
-
-## 多项目安装
-
-`install` 至少需要传入一个目录；0 目录场景会直接失败。
-
-默认要求传入绝对路径：
-
-```sh
-npm  install -g  x7-code-line --dir /abs/path/repo-a --dir /abs/path/repo-b
-```
-
-例如，将 `x7-code-line` 安装在 C 盘目录，但指定 D 盘的 Git 项目：
-
-```powershell
-cd C:\x7-tools\x7-code-line-host
-npm  install -g  x7-code-line  --dir D:\work\repo-a --dir D:\work\repo-b
-```
-
-如果确实需要解析相对路径，必须显式传 `--relative`：
-
-```sh
-npm  install -g  x7-code-line  --relative --dir ../repo-a --dir ../repo-b
-```
-
-此时相对路径基于当前执行 `install` 命令的目录解析。
-
-也可以在安装时通过环境变量指定多个目标目录。
-
-如果通过环境变量或配置文件传相对路径，需要同时设置 `X7_CODE_LINE_RELATIVE_PATHS=1`。
-
-macOS / Linux 示例：
-
-```sh
-X7_CODE_LINE_RELATIVE_PATHS=1 X7_CODE_LINE_DIRS="../repo-a:../repo-b" npm install -g x7-code-line 
-```
-
-Windows 使用 `;` 作为目录分隔符：
-
-```powershell
-$env:X7_CODE_LINE_RELATIVE_PATHS = "1"
-$env:X7_CODE_LINE_DIRS = "../repo-a;../repo-b"
-npm install -g x7-code-line
-```
-
-## 配置文件
-
-可以通过 `--config` 或 `X7_CODE_LINE_CONFIG` 指定 JSON 配置文件：
-
-```json
-{
-  "dirs": ["../repo-a", "../repo-b"],
-  "gitDirs": [".git"]
-}
-```
-
-字段说明：
-
-- `dirs`：目标项目目录列表。
-- `gitDirs`：相对于每个目标项目目录的 Git 目录列表。
-
-## macOS 适配说明
-
-macOS 下整体可以直接使用，但需要注意以下几点：
-
-- Git hooks 使用 `#!/bin/sh`，macOS 自带 `/bin/sh`，无需额外安装 shell。
-- 安装器会对生成的 hook 文件执行 `chmod 755`。如果你手动复制 hook 文件，也需要执行：
-
-```sh
-chmod +x .git/hooks/pre-commit .git/hooks/commit-msg
-```
-
-- macOS / Linux 的多项目环境变量使用 `:` 分隔目录；不要使用 Windows 的 `;`。
-- 如果 Cursor 或 Codex 不是从终端启动，GUI 进程可能拿不到你的 shell `PATH`，导致 hook 中的 `npx` 找不到。遇到这种情况，优先从终端启动 Cursor/Codex，或确保 Node.js / npm 的安装路径已经进入 GUI 应用可见的 `PATH`。
-- 如果项目路径包含空格，安装器生成的 Git hook 会对 `X7_CODE_LINE_BASE` 做 shell quote，通常可以正常工作。
-- 使用 nvm、fnm、asdf 等 Node 版本管理器时，macOS GUI 应用经常不会加载对应初始化脚本。建议在运行 hooks 前确认：
-
-```sh
-which node
-which npm
-which npx
-```
-
-如果这些命令在 Cursor/Codex hook 环境中不可用，需要调整启动方式或 PATH。
-
-## Windows 适配说明
-
-- Git for Windows 会用 Git Bash 执行 `.git/hooks/*`，因此 `#!/bin/sh` hook 可以运行。
-- PowerShell 下设置多项目环境变量时使用 `$env:X7_CODE_LINE_DIRS`。
-- Windows 目录分隔符使用 `;`，例如：
-
-```powershell
-$env:X7_CODE_LINE_DIRS = "D:\repo-a;D:\repo-b"
-```
-
-## 增量添加目录
-
-在已经完成安装的当前安装目录下，可以使用 `addDir` 增量添加新的项目目录：
-
-```sh
-x7-code-line addDir --dir /abs/path/repo-c
-```
-
-这个命令只做两件事：
-
-- 把新目录追加到当前安装目录 `.x7-code-line/projects.json`
-- 为新目录安装 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg`
-
-它不会重写当前安装目录的 `.cursor/hooks.json`、`.codex/hooks.json`，也不会重写已有项目集合。
-
+# x7-code-line
+
+`x7-code-line` 是一个用于安装 Cursor、Codex 和 Git hooks 的 npm 模块。它用于在 agent 工作流中区分普通用户已有改动和 AI 生成改动，并在提交信息中自动追加 AI 行数 trailer。
+
+## 功能概览
+
+- 安装 Cursor 项目 hooks：写入当前安装目录的 `.cursor/hooks.json`。
+- 安装 Codex 项目 hooks：写入当前安装目录的 `.codex/hooks.json`。
+- 安装 Git hooks：为目标项目写入 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg`。
+- 初始化中心缓存目录：写入当前安装目录的 `.x7-code-line/`。
+- 支持多项目：多项目配置只用于替换目标项目的 Git hooks，以及在 `prompt-submit` / `stop` 时遍历读取这些项目的 `git diff`。
+- 记录普通 diff 行：prompt 提交时读取 `git diff`，把尚未进入 AI 缓存的 diff 行写入普通缓存。
+- 记录 AI diff 行：agent 结束时再次读取 `git diff`，把不属于普通缓存的 diff 行写入 AI 缓存。
+- 计算提交 AI 行数：`pre-commit` 对比当前仓库 staged diff 和中心 AI 缓存，计算本次提交真实包含的 AI diff 行数。
+- 写入 commit trailer：`commit-msg` 追加或替换 `x7-ai-lines: <数量>`。
+
+## 安装行为
+
+作为 npm 依赖安装时，`postinstall` 脚本使用 `INIT_CWD` 作为当前安装目录，也就是执行 `npm install` 时所在的项目目录。
+
+如果只是全局安装：
+
+```sh
+npm install -g x7-code-line
+```
+
+此时只安装 CLI，不会自动为任何项目写入 hooks。全局安装完成后，需要手动执行：
+
+```sh
+x7-code-line install --dir <absolute-path>
+```
+
+只有在 `X7_CODE_LINE_DIRS` 或 `X7_CODE_LINE_CONFIG` 明确提供目标目录时，`postinstall` 才会继续执行项目安装逻辑。
+
+当前安装目录会创建或覆盖：
+
+```text
+.x7-code-line/install.json
+.x7-code-line/projects.json
+.x7-code-line/ai-diff-line-ids.json
+.x7-code-line/normal-diff-line-ids.json
+.cursor/hooks.json
+.codex/hooks.json
+```
+
+如果目标项目存在 `.git`，会创建或覆盖：
+
+```text
+.git/hooks/pre-commit
+.git/hooks/commit-msg
+```
+
+多项目配置只影响两类行为：
+
+- 为配置中的项目目录替换 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg`。
+- 执行 `prompt-submit` / `stop` 时遍历配置中的项目目录读取 `git diff`。
+
+`.cursor/hooks.json`、`.codex/hooks.json` 和 `.x7-code-line/` 只会写入当前安装目录，不会写入每个多项目目标目录。
+
+## Cursor Hooks
+
+Cursor 模板写入 `.cursor/hooks.json`：
+
+```json
+{
+  "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": "npx --no-install x7-code-line prompt-submit"
+      }
+    ],
+    "stop": [
+      {
+        "command": "npx --no-install x7-code-line stop"
+      }
+    ]
+  }
+}
+```
+
+## Codex Hooks
+
+Codex 模板写入 `.codex/hooks.json`：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "command": "npx --no-install x7-code-line prompt-submit"
+      }
+    ],
+    "Stop": [
+      {
+        "command": "npx --no-install x7-code-line stop"
+      }
+    ]
+  }
+}
+```
+
+## Diff 行缓存
+
+`prompt-submit` 会进入每个已缓存的项目目录，执行：
+
+```sh
+git diff --no-ext-diff --unified=0 --no-color
+```
+
+然后对每个变更行计算 ID。ID 由以下信息生成：
+
+- 项目绝对路径
+- 文件路径
+- 变更类型：`add` 或 `delete`
+- 行号
+- 行内容
+- 该文件当前的修改时间
+
+如果该 ID 不在 AI diff 缓存中，就写入普通 diff 缓存：
+
+```text
+.x7-code-line/normal-diff-line-ids.json
+```
+
+`stop` 会再次读取每个项目的 `git diff` 并计算行 ID。如果某个 ID 不在普通 diff 缓存中，就写入 AI diff 缓存：
+
+```text
+.x7-code-line/ai-diff-line-ids.json
+```
+
+缓存按项目绝对路径分组，结构类似：
+
+```json
+{
+  "projects": {
+    "/path/to/repo-a": ["line-id-1"],
+    "/path/to/repo-b": ["line-id-2"]
+  }
+}
+```
+
+## Git Hooks
+
+安装器会生成 shell hook，并写入中心缓存目录：
+
+```sh
+X7_CODE_LINE_BASE='<当前安装目录>'
+export X7_CODE_LINE_BASE
+npx --no-install x7-code-line git-pre-commit
+```
+
+`pre-commit` 会读取当前仓库的 staged diff：
+
+```sh
+git diff --cached --no-ext-diff --unified=0 --no-color
+```
+
+然后使用当前仓库绝对路径从中心缓存中取出对应项目的 AI diff 行 ID，计算本次提交真正包含的 AI diff 行数，并写入：
+
+```text
+.x7-code-line/pending-commit.json
+```
+
+计算完成后，会清除当前仓库在以下两份中心缓存中的条目：
+
+```text
+.x7-code-line/ai-diff-line-ids.json
+.x7-code-line/normal-diff-line-ids.json
+```
+
+其他项目的缓存不会被修改。
+
+`commit-msg` 会读取该结果，并追加或替换 trailer：
+
+```text
+x7-ai-lines: 3
+```
+
+如果没有命中 AI diff 行，则写入：
+
+```text
+x7-ai-lines: 0
+```
+
+## 多项目安装
+
+`install` 至少需要传入一个目录；0 目录场景会直接失败。
+
+默认要求传入绝对路径：
+
+```sh
+npm  install -g  x7-code-line --dir /abs/path/repo-a --dir /abs/path/repo-b
+```
+
+例如，将 `x7-code-line` 安装在 C 盘目录，但指定 D 盘的 Git 项目：
+
+```powershell
+cd C:\x7-tools\x7-code-line-host
+npm  install -g  x7-code-line  --dir D:\work\repo-a --dir D:\work\repo-b
+```
+
+如果确实需要解析相对路径，必须显式传 `--relative`：
+
+```sh
+npm  install -g  x7-code-line  --relative --dir ../repo-a --dir ../repo-b
+```
+
+此时相对路径基于当前执行 `install` 命令的目录解析。
+
+也可以在安装时通过环境变量指定多个目标目录。
+
+如果通过环境变量或配置文件传相对路径，需要同时设置 `X7_CODE_LINE_RELATIVE_PATHS=1`。
+
+macOS / Linux 示例：
+
+```sh
+X7_CODE_LINE_RELATIVE_PATHS=1 X7_CODE_LINE_DIRS="../repo-a:../repo-b" npm install -g x7-code-line 
+```
+
+Windows 使用 `;` 作为目录分隔符：
+
+```powershell
+$env:X7_CODE_LINE_RELATIVE_PATHS = "1"
+$env:X7_CODE_LINE_DIRS = "../repo-a;../repo-b"
+npm install -g x7-code-line
+```
+
+## 配置文件
+
+可以通过 `--config` 或 `X7_CODE_LINE_CONFIG` 指定 JSON 配置文件：
+
+```json
+{
+  "dirs": ["../repo-a", "../repo-b"],
+  "gitDirs": [".git"]
+}
+```
+
+字段说明：
+
+- `dirs`：目标项目目录列表。
+- `gitDirs`：相对于每个目标项目目录的 Git 目录列表。
+
+## macOS 适配说明
+
+macOS 下整体可以直接使用，但需要注意以下几点：
+
+- Git hooks 使用 `#!/bin/sh`，macOS 自带 `/bin/sh`，无需额外安装 shell。
+- 安装器会对生成的 hook 文件执行 `chmod 755`。如果你手动复制 hook 文件，也需要执行：
+
+```sh
+chmod +x .git/hooks/pre-commit .git/hooks/commit-msg
+```
+
+- macOS / Linux 的多项目环境变量使用 `:` 分隔目录；不要使用 Windows 的 `;`。
+- 如果 Cursor 或 Codex 不是从终端启动，GUI 进程可能拿不到你的 shell `PATH`，导致 hook 中的 `npx` 找不到。遇到这种情况，优先从终端启动 Cursor/Codex，或确保 Node.js / npm 的安装路径已经进入 GUI 应用可见的 `PATH`。
+- 如果项目路径包含空格，安装器生成的 Git hook 会对 `X7_CODE_LINE_BASE` 做 shell quote，通常可以正常工作。
+- 使用 nvm、fnm、asdf 等 Node 版本管理器时，macOS GUI 应用经常不会加载对应初始化脚本。建议在运行 hooks 前确认：
+
+```sh
+which node
+which npm
+which npx
+```
+
+如果这些命令在 Cursor/Codex hook 环境中不可用，需要调整启动方式或 PATH。
+
+## Windows 适配说明
+
+- Git for Windows 会用 Git Bash 执行 `.git/hooks/*`，因此 `#!/bin/sh` hook 可以运行。
+- PowerShell 下设置多项目环境变量时使用 `$env:X7_CODE_LINE_DIRS`。
+- Windows 目录分隔符使用 `;`，例如：
+
+```powershell
+$env:X7_CODE_LINE_DIRS = "D:\repo-a;D:\repo-b"
+```
+
+## 增量添加目录
+
+在已经完成安装的当前安装目录下，可以使用 `addDir` 增量添加新的项目目录：
+
+```sh
+x7-code-line addDir --dir /abs/path/repo-c
+```
+
+这个命令只做两件事：
+
+- 把新目录追加到当前安装目录 `.x7-code-line/projects.json`
+- 为新目录安装 `.git/hooks/pre-commit` 和 `.git/hooks/commit-msg`
+
+它不会重写当前安装目录的 `.cursor/hooks.json`、`.codex/hooks.json`，也不会重写已有项目集合。
+
 `addDir` 会沿用与 `install` 相同的严格校验：
-
-- 目录必须真实存在
-- 目录必须可访问
-- 目录必须包含可用的 `.git` 目录
-
-任一新增目录不满足条件时，命令直接失败，不会继续追加。
-
+
+- 目录必须真实存在
+- 目录必须可访问
+- 目录必须包含可用的 `.git` 目录
+
+任一新增目录不满足条件时，命令直接失败，不会继续追加。
+
 默认只接受绝对路径；如果需要解析相对路径，需要显式传入：
-
-```sh
+
+```sh
 x7-code-line addDir --relative --dir ../repo-c
 ```
 
-## CLI 命令
-
-```sh
-x7-code-line install --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]
-x7-code-line addDir --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]
-x7-code-line prompt-submit
-x7-code-line stop
-x7-code-line git-pre-commit
-x7-code-line git-commit-msg <commit-msg-file>
-```
-
-## 本地验证
-
-```sh
-npm test
-npm pack --dry-run
-```
-
-## 发布到 npm
-
-首次发布和后续更新都建议先在本地完成校验：
-
-```sh
-npm test
-npm pack --dry-run
-```
-
-确认当前登录的 npm 账号：
-
-```sh
-npm whoami
-```
-
-如果还没有登录：
-
-```sh
-npm login
-```
-
-### 首次发布
-
-确认 `package.json` 中的包名和版本号正确后，执行：
-
-```sh
-npm publish --access public
-```
-
-如果 npm 账号开启了 2FA，通常需要附带 OTP：
-
-```sh
-npm publish --otp <6位验证码>
-```
-
-如果将来改为 scope 包并需要公开发布，则使用：
-
-```sh
-npm publish --access public --otp <6位验证码>
-```
-
-### 更新已发布版本
-
-每次发布新版本前，手动修改package.json版本号或命令提升版本号：
-
-```sh
-npm version patch
-```
-
-也可以按需要使用：
-
-```sh
-npm version minor
-npm version major
-```
-
-然后重新发布：
+`install` 和 `addDir` 成功后，会输出：
 
-```sh
-npm publish --otp <6位验证码>
+```text
+[x7-code-line] D:\your-repo configured successfully.
 ```
-
-### 常见发布流程
-
-```sh
-npm test
-npm pack --dry-run
-npm version patch
-npm publish --otp <6位验证码>
+
+## CLI 命令
+
+```sh
+x7-code-line install --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]
+x7-code-line addDir --dir <absolute-path> [--dir <absolute-path> ...] [--config path] [--relative]
+x7-code-line prompt-submit
+x7-code-line stop
+x7-code-line git-pre-commit
+x7-code-line git-commit-msg <commit-msg-file>
 ```
 
-### 2FA 与 token
-
-如果 npm 账号开启了两步验证，发布时需要满足以下任一条件：
-
-- 直接在 `npm publish` 时传入 `--otp`。
-- 使用具备 publish 权限并允许 bypass 2FA 的 npm access token。
-
-手动在本机发布时，最直接的方式通常是：
-
-```sh
-npm publish --otp <当前验证码>
-```
+`prompt-submit` 和 `stop` 执行时，会优先按以下顺序定位主目录中的 `.x7-code-line` 缓存：
+
+- `X7_CODE_LINE_BASE`
+- 当前目录向上查找 `.x7-code-line/install.json`
+- 安装时写入的全局 base 指针
+
+因此即使在其他目录手动执行命令，也会优先读取主目录缓存，而不是把执行目录当作缓存目录。
+
+## 本地验证
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+## 发布到 npm
+
+首次发布和后续更新都建议先在本地完成校验：
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+确认当前登录的 npm 账号：
+
+```sh
+npm whoami
+```
+
+如果还没有登录：
+
+```sh
+npm login
+```
+
+### 首次发布
+
+确认 `package.json` 中的包名和版本号正确后，执行：
+
+```sh
+npm publish --access public
+```
+
+如果 npm 账号开启了 2FA，通常需要附带 OTP：
+
+```sh
+npm publish --otp <6位验证码>
+```
+
+如果将来改为 scope 包并需要公开发布，则使用：
+
+```sh
+npm publish --access public --otp <6位验证码>
+```
+
+### 更新已发布版本
+
+每次发布新版本前，手动修改package.json版本号或命令提升版本号：
+
+```sh
+npm version patch
+```
+
+也可以按需要使用：
+
+```sh
+npm version minor
+npm version major
+```
+
+然后重新发布：
+
+```sh
+npm publish --otp <6位验证码>
+```
+
+### 常见发布流程
+
+```sh
+npm test
+npm pack --dry-run
+npm version patch
+npm publish --otp <6位验证码>
+```
+
+### 2FA 与 token
+
+如果 npm 账号开启了两步验证，发布时需要满足以下任一条件：
+
+- 直接在 `npm publish` 时传入 `--otp`。
+- 使用具备 publish 权限并允许 bypass 2FA 的 npm access token。
+
+手动在本机发布时，最直接的方式通常是：
+
+```sh
+npm publish --otp <当前验证码>
+```