@itenl/sec 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,704 @@
-# Temporary Holding Version
+# sec
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一次配置、跨 Git 仓库使用的安全扫描 CLI。基于官方 `@openai/codex-security` 的独立封装，负责扫描范围、项目规范、风险门禁、私有或共享漏洞台账及修复复核。
+
+npm 包名为 `@itenl/sec`，当前源码版本 `0.1.1`，采用 MIT 许可证。支持 macOS / Linux，未声明 Windows 支持。扫描引擎固定为 `0.8.3`；本工具和模板的 MIT 许可不替代扫描引擎及所选模型服务各自的许可或使用条款。
+
+## 安装与快速开始
+
+需要 Node 22.13+（22.x）、24 或 26，Git，以及 Python 3.10+。Python 3.10 还需要 tomli；优先使用 Python 3.11+。uv 可选。
+
+安装并完成首次接入：
+
+```sh
+npm install -g @itenl/sec
+sec setup
+sec auth
+sec doctor
+
+cd /path/to/repository
+sec init project --dry-run
+sec init project
+sec config --project
+sec branch --dry-run
+```
+
+维护者检查生成的通用规范、模型和比较目标后，再执行 `sec branch` 正式扫描。setup 不会自动安装 Git 或 Python，缺少时需先安装。通用模板需要按项目实际情况补充；已有团队规范不覆盖。正式扫描会向所选模型服务发送代码和扫描上下文，并消耗该服务的额度。
+
+## 从源码检查与安装
+
+在本仓库先检查帮助，无需安装、配置或 API key：
+
+```sh
+node bin/sec.mjs --help
+pnpm test
+pnpm check
+pnpm check:package
+```
+
+本地全局安装：
+
+```sh
+pnpm pack
+npm install -g ./itenl-sec-0.1.1.tgz
+sec setup
+```
+
+通过本地 tarball 安装不需要包已经发布，也不需要登录 npm。npm 的发布账号与 `sec setup` 中的模型服务认证是两套独立登录。
+
+## 从 0.1.0 升级
+
+`0.1.0` 在传入项目规范或共享知识文档时，会提前把文档副本放进引擎输出目录，导致扫描在准备阶段报 `Scan output directory is not empty` 并以 `2` 退出。`0.1.1` 将这些输入副本移到私有状态目录的 `contexts/<执行标识>/`，扫描报告仍使用原来的 `runs/<执行标识>/`。
+
+安装已发布的修复版本后，直接重试原命令即可：
+
+```sh
+npm install -g @itenl/sec@0.1.1
+sec --version
+sec branch
+```
+
+升级保留已有认证、用户配置、项目规范和漏洞台账，无需重新 setup 或 init。不要为解决这个错误删除状态目录或旧报告；该错误表示扫描未完成，不能视为零漏洞。`sec branch` 不支持直接传入引擎提示的 `--archive-existing` 参数。
+
+## 一次 setup
+
+`sec setup` 可以在任意目录运行，不需要先进入项目。它会：
+
+1. 检查 Python 和扫描引擎，复用可用的官方 CLI 0.8.3；缺少兼容版本时安装到本工具的用户目录，不替换其他全局工具。
+2. 询问 API 服务地址、模型和推理强度。首次留空使用官方服务、`gpt-6.1-sol` 和 `high`；自定义兼容 Responses 的服务需要支持所选模型。每位使用者需要自己的有效凭据。
+3. 隐藏输入 API key，通过 stdin 交给官方 CLI 保存；使用独立登录目录，避免覆盖日常 Codex 登录。
+4. 保存不含 key 的用户级配置，并提供 zsh/bash 的 `sec:xxx` 快捷命令安装选项。
+
+```sh
+sec setup --api-key
+sec setup --base-url https://api.example.test/v1 --model your-model
+sec setup --model gpt-6.1-sol --effort high
+sec setup --no-aliases
+```
+
+`--api-key` 是开关，后面不能填写 key。setup 需要交互式终端，不接受命令行明文 key。初始化不请求模型，不证明凭据、额度和模型权限有效。已有配置会备份；已有登录默认保留。
+
+终端的 `OPENAI_API_KEY` / `CODEX_API_KEY` 可覆盖已保存登录；setup 会提醒，但不会擅自改变父终端环境。工具不会自动继承日常 Codex 的 provider 或其他仓库的模型配置。
+
+## 查询登录方式
+
+```sh
+sec auth          # 显示 sec 的已保存登录方式、环境 key 和非交互默认认证来源
+sec auth --json   # 输出相同信息的 JSON，便于脚本读取
+```
+
+此命令可在任意目录运行，不需要进入 Git 仓库，不请求模型或消耗扫描 token。会区分 **API key**、**ChatGPT 账号登录**、**未登录**和**无法确认**，并单独列出环境变量名称，不输出 key、token、邮箱、账号 ID 或官方原始状态输出。ChatGPT 账号登录可能使用账号的 Codex 权益，但状态查询不验证订阅等级、权益、剩余额度或最终计费。
+
+非交互扫描默认优先级为 **`OPENAI_API_KEY` → `CODEX_API_KEY` → sec 保存的登录**。例如已保存 ChatGPT 登录，但当前终端设置了 API key，非交互扫描默认使用 API key；交互式扫描如果引擎要求选择，以当次选择为准。环境 key 不会替换已保存的登录。自定义 provider 是否接受账号登录取决于该服务，不能据此认定使用订阅即可扫描。
+
+查询使用与 sec 扫描相同的引擎和独立认证目录，支持官方文件或系统凭据存储；直接运行未带 sec 环境的 `codex-security login status` 或 `codex login status` 可能查询到另一套登录。官方状态查询可能初始化或同步 sec 的本机认证缓存，不修改业务仓库或日常 Codex 登录；不自动发起登录、替换凭据或读取模型额度。登录状态子进程最多等待 10 秒，引擎版本检查另有 10 秒上限；失败或未识别的输出会显示“无法确认”，不会猜测登录类型。
+
+API key 状态兼容官方新旧两种输出：`API key configured…` 和 `Logged in using an API key…`。两者只表示本机配置了凭据，不代表已经通过真实请求验证。若旧版 sec 在 setup 后仍显示“无法确认”，先更新 CLI 后重试 `sec auth`，无需因此重新输入或替换 key。
+
+没有环境 key 且未登录时返回 `2`；引擎缺失、不兼容、状态查询失败或无法识别保存状态时也返回 `2`。已识别登录方式，或确认未保存登录但存在环境 key 时返回 `0`。`0` 仅表示来源查询完成，不证明认证有效。当前 `sec setup` 的登录入口是隐藏输入 API key；`sec auth` 只查询，不切换登录方式。
+
+## 模型与推理强度
+
+本工具默认使用 **`gpt-6.1-sol` + `high`（高）**，会显式传给扫描引擎，不依赖引擎自身的模型默认值。scan、diff、branch 和真正调用模型的 verify 使用相同规则，模型与推理强度分别按以下优先级选择：**单次命令参数 → 项目共享设置 → setup 保存的个人设置 → 工具默认值**。
+
+```sh
+sec setup --model gpt-6.1-sol --effort high  # 保存个人默认值，仍需交互式 setup
+sec branch                                 # 使用个人设置；没有时使用工具默认值
+sec branch --effort xhigh                   # 仅本次改成超高，模型保持原设置
+sec scan --model your-model --effort medium # 仅本次同时覆盖模型与推理强度
+sec diff --model your-model                 # 仅本次覆盖模型，强度保持原设置
+sec verify --effort xhigh                   # 仅本次修复复核使用超高
+sec doctor                                 # 查看不带单次参数时的模型与强度
+```
+
+单次参数不会写回用户配置，也不改变服务地址或登录。已有配置指定了其他模型或强度时继续保留；旧配置缺少某项时使用对应的工具默认值，无需改写配置。setup 中留空保留已有值，首次留空会保存工具默认值；要恢复工具默认值，显式运行 `sec setup --model gpt-6.1-sol --effort high`。
+
+`--model` 填写服务实际接受的完整模型 ID，例如 `gpt-6.1-sol`。`--effort` 填写该模型及服务支持的推理强度，例如 `medium`、`high` 或 `xhigh`；更换模型不会自动替换强度。不支持的组合会报错，不自动降级或换模型。实际支持、额度和费用以所选服务为准；初始化、doctor 和 dry-run 不会通过真实请求验证这些条件。正式执行会显示请求的模型与强度，并记录到该次私有 `wrapper-result.json` 的 `modelSettings` 中；这是请求设置，不证明第三方服务内部实际路由。
+
+## sec:xxx 快捷命令
+
+npm 的可执行文件名规范化不保留冒号，所以包实际注册 `sec`；`sec:xxx` 通过 zsh/bash alias 实现：
+
+```sh
+sec aliases --install              # 也可在 setup 中安装
+sec aliases --install --shell bash
+sec aliases                        # 只打印内容，供手动配置
+```
+
+安装会保留现有 shell 内容，先备份后维护带标记的 alias 段。zsh 使用 `${ZDOTDIR:-$HOME}/.zshrc`，bash 使用 `~/.bashrc`。打开新终端或手动 source 对应文件后生效。若 bash 登录 shell 未加载 `.bashrc`，需要自行在登录配置中加载它。其他 shell、脚本或 CI 中直接使用 `sec branch` 等标准命令。
+
+## 默认比较分支配置
+
+初始化之后可以直接修改默认比较目标，**不用重新 setup，也不用每次输入 `--base`**。这修改的是 sec 的扫描设置，不会改变 Git 的 `origin/HEAD`、当前分支或远端默认分支。
+
+```sh
+# 用户级默认值：影响该同学电脑上所有没有仓库覆盖的项目，选一个设置即可
+sec config set baseRef origin/master
+sec config set baseRef origin/main
+
+# 仅当前仓库：在该仓库根目录或子目录执行，适合多个项目的目标分支不同
+sec config set baseRef origin/master --local
+
+# 以后直接使用保存的目标
+sec branch --dry-run
+sec branch
+```
+
+**团队统一基线可用 `sec config set baseRef origin/main --project`；个人仓库覆盖使用 `--local`。** 优先级为：**单次 `sec branch --base` → 本机仓库配置 → 项目共享配置 → 用户级配置 → `origin/HEAD`**。不猜测分支创建来源或 upstream；保存了不存在的引用时，扫描会报错，不自动改用其他目标或 fetch。
+
+```sh
+sec config                            # 查看用户级配置位置和默认目标
+sec config get baseRef                # 输出用户级默认目标，未设置时输出 origin/HEAD
+sec config --local                    # 查看当前仓库配置位置和继承后的默认目标
+sec config get baseRef --local        # 输出当前仓库实际默认目标，不含单次 --base
+sec config unset baseRef --local      # 清除仓库覆盖，重新继承用户级设置
+sec config unset baseRef              # 清除用户级设置，未被仓库覆盖时回退 origin/HEAD
+```
+
+也可以手动编辑无密钥的 JSON 配置：用户级默认为 `~/.config/sec/config.json`（支持 `XDG_CONFIG_HOME`），在原有对象中增加或修改 `baseRef` 字段，例如 `"baseRef": "origin/master"`，保留原有地址、模型等其他字段。仅当前仓库的配置位于 `sec paths` 显示的 `repositoryConfig`，默认是 `~/.local/state/sec/repositories/<本机仓库路径哈希>/config.json`，不要放到业务仓库中；建议用命令创建和修改。
+
+配置查询和修改都不请求模型、检查 key 或重新登录；不需要 Python 或扫描引擎。用户级配置可在任意目录管理，`--local` 需要在目标 Git 仓库内。仓库配置按本机 checkout 路径隔离，移动仓库或换电脑后需要重新设置。修改后先运行 `sec branch --dry-run`，确认本地引用、目标与差异范围，再正式扫描。
+
+## 在任意项目运行
+
+> **_正式扫描或修复复核期间，请保持目标仓库和扫描配置不变，直到命令退出并显示最终结果。即使进度已到 98%，也不要保存改动、提交或切换分支；最后校验失败仍可能导致本次结果无法入账，已经消耗的模型额度不会因此恢复。具体范围见[扫描期间注意事项](#扫描期间注意事项)。_**
+
+```sh
+cd /path/to/repository
+sec:branch --dry-run # 先预览范围，不调用模型
+sec:branch # 正式扫描，会消耗额度
+
+# 标准命令完全等价
+sec branch --base origin/main
+sec diff
+sec scan
+```
+
+branch 扫描所选目标与 HEAD 的唯一 merge-base 到 HEAD 的已提交净差异。比较目标按单次 `--base`、本机仓库配置、项目共享配置、用户级配置、本地 `origin/HEAD` 的顺序选择；持久设置见[默认比较分支配置](#默认比较分支配置)。引用缺失、历史不足或正在合并/变基时会报错；不自动 fetch，不猜 upstream。已有 origin/HEAD 不保证指向当前 PR 的合入目标，应按实际任务选择。
+
+`--dry-run` 检查项目配置输入并展示本地范围，不调用引擎、不检查认证、不创建报告或台账。空分支差异、空暂存差异直接跳过。
+
+diff 只扫描 HEAD 到真实 index 的差异，支持部分暂存、首次提交及 `GIT_INDEX_FILE`；未暂存内容不进入快照。branch / diff 使用仓库外隔离快照，不更改源工作区、分支和 index。
+
+scan 扫描当前工作区。scan（内部模式 full）与 verify 会比较工作区指纹，diff 会检查 index 和 HEAD，branch 会检查 HEAD；对应状态变化会阻止结果导入，详见下节。
+
+中危/高危/严重发现返回 1，低危警告放行返回 0。执行失败、证据不足、未知等级或产物不完整返回 2；取消保留非零状态。完整扫描即使风险阻断，也会导入发现；错误结果不入账。退出码 0 不代表逐文件完整审计或不存在漏洞。
+
+正式扫描需要网络并消耗模型额度。认证与依赖要求也可查阅[官方 CLI 文档](https://developers.openai.com/codex/security/cli/)。工具只请求报告，不自动修复、fetch、提交或推送。
+
+## 扫描期间注意事项
+
+> **_先完成改动和范围确认，再开始扫描；从命令启动到退出并显示最终结果之前，暂停对同一仓库的编辑、格式化和 Git 写操作。进度接近 100% 不代表报告已经完整保存或通过校验。_**
+
+需要保持不变的范围按命令区分：
+
+- **`sec scan` 和真正调用模型的 `sec verify`**：保持整个仓库的已跟踪文件、未被忽略的未跟踪文件、HEAD 和暂存区不变。包括源码、配置、依赖清单、锁文件、文档，以及新增、删除、重命名、文件权限和符号链接变化；verify 也检查整个范围，并非只检查漏洞所在文件。已跟踪文件即使符合 ignore 规则，仍在校验范围内。未跟踪且被忽略的文件不纳入该指纹，但如果扫描需要读取它们，也应保持稳定。该校验范围不等于扫描器保证逐文件审计的范围。
+- **`sec diff`**：保持真实暂存区（index）和 HEAD 不变；设置了 `GIT_INDEX_FILE` 时，对应的是该 index。不要暂存、取消暂存或提交。单独修改未暂存内容通常不会触发这里的范围校验，但这些修改不在本次隔离快照中，报告仍对应启动时的暂存版本；建议同样暂停编辑，避免误认扫描范围。
+- **`sec branch`**：保持启动时的 HEAD 不变。不要新增提交、amend、切换分支或改写历史。暂存、未暂存和未跟踪内容不在本次已提交快照中，单独改变它们通常不会触发 HEAD 校验，也不会让它们被扫描。目标引用在启动时解析；需要 fetch 或调整比较目标时，请在扫描前完成。
+
+常见需要暂停的操作：
+
+- 编辑器保存、自动保存、保存时格式化，其他 AI 编程工具写文件，`lint --fix`、代码生成，以及会改写文件的开发监听脚本。安装或升级依赖也可能改动依赖清单、锁文件或生成文件，请提前完成。
+- `git add`、取消暂存、`git reset`、`git restore`、`git commit` / `--amend`、`git switch` / `checkout`、merge、rebase、cherry-pick，以及 stash 的保存、应用或弹出。它们可能改变源码、index 或 HEAD，具体影响按上述模式判断。
+- 修改本次 `--knowledge-base` 指定的文件或目录，包括仓库外的背景文档。额外文档不保证全部受工作区指纹保护，应自行保持不变。
+- 对同一仓库并发运行其他正式扫描、复核或 `sec update`，以及手动修改 `ledger.json`。这些写入可能使最终台账一致性检查失败；排队请在复核前完成。
+- 移动仓库，改动本次使用的配置、认证或引擎版本，重新运行 setup 或升级 CLI，以及移动、删除或修改状态目录、原始报告、证据和临时快照。历史原始证据也是定向复核的输入，不能只保留台账。
+
+可以只读查看源码、`git status`、`git diff`，或运行 `sec list`、`sec paths` 查看已有信息；注意关闭编辑器自动保存。需要继续开发时，优先使用另一份独立 clone，并保留扫描目录不动。
+
+**_如果扫描过程中改了上述受校验的内容，即使模型已经处理了大部分工作，最终校验仍会拒绝导入结果或更新复核状态，通常返回退出码 2。工具无法退回已消耗的额度，重新扫描可能再次计费。_**
+
+失败或中断后的报告保留情况：
+
+- 正常走到收尾时，工具通常会保留已写出的私有原始产物、`summary.md` 和 `wrapper-result.json`，并在终端显示位置。可在仓库内用 `sec paths` 找到 runs 目录，再定位本次执行目录；不要立即删除它。
+- 保留了文件不代表得到完整、有效的安全结论。检查摘要和最终状态；未通过校验的结果不会自动入账，也不能当作当前代码已经扫描或漏洞已经修复的证明。
+- 引擎尚未写完报告时取消、强制终止进程（如 `kill -9`）、关闭终端或断电，可能只留下部分产物，甚至来不及生成摘要；启动早期失败也可能尚未创建执行目录。**_本工具不保证中断后存在完整报告，也不提供自动断点续扫。_** 需要重试时先保留现有执行目录，再确认范围并重新运行。
+
+## 项目初始化与团队共享规范
+
+每台电脑执行一次 `sec setup`，每个项目由维护者执行一次 `sec init project`。同事拉取已接入的业务仓库后可直接运行 `sec branch`，不需要逐人配置规范路径或安装额外 skill。CLI 包只携带通用模板，不携带使用项目的架构、技术栈、业务规则或历史发现。
+
+通用模板作为独立 Markdown 文件随 npm 包分发，初始化时从已安装 CLI 的 `templates/` 目录读取，并写入目标业务仓库：
+
+- `templates/security-policy.md`：通用安全审查规范，默认写到 `.agents/skills/project-security/SKILL.md`。
+- `templates/review-report.md`：人工中文复核报告模板，默认写到 `.agents/skills/project-security/references/report-template.md`。
+
+这两份模板由本工具维护，初始化不从 Codex 官方或其他远程地址下载，也不调用模型生成。维护 CLI 的默认内容时直接编辑这两个文件；实际目标路径由项目配置决定。已生成的项目文件保留，更新 CLI 模板只影响后续创建的缺失文件，项目规范的调整由维护者审核。
+
+```sh
+cd /path/to/repository
+sec init project --dry-run   # 列出计划，不写文件、不安装引擎、不调用模型
+sec init project             # 创建缺失文件、输出目录，并补充 .gitignore
+sec config --project         # 查看业务仓库中的共享配置
+sec branch --dry-run         # 检查项目输入及本地差异范围，不调用模型
+sec branch                   # 正式扫描，会消耗额度
+```
+
+`sec init` 不带 `project` 会显示用法错误；没有 `--force` 或覆盖开关。支持在 Git 子目录执行；不是 Git 仓库时会报错。重复初始化会保留已有规范、模板、台账及配置值，只补齐缺失的默认项和文件。初始化不会读取或复制其他业务仓库，不改个人登录、Git 引用、hook 或暂存区，不自动提交。原有本机私有台账不会自动合并到共享台账。
+
+默认生成的根目录 `sec.config.json` 如下。`baseRef` 初始取本机仓库覆盖、用户默认值或 `origin/HEAD`；下例是没有覆盖时的值。已有台账会推断并沿用其单一编号前缀，不硬编码团队编号。
+
+```json
+{
+  "schemaVersion": 1,
+  "policyFile": ".agents/skills/project-security/SKILL.md",
+  "reportTemplate": ".agents/skills/project-security/references/report-template.md",
+  "trackerFile": "docs/security/findings.json",
+  "summaryDir": "docs/security/reviews/generated",
+  "reviewDir": "docs/security/reviews",
+  "knowledgeBase": [],
+  "idPrefix": "SEC",
+  "baseRef": "origin/HEAD",
+  "model": "gpt-6.1-sol",
+  "effort": "high",
+  "failOnSeverity": "medium"
+}
+```
+
+各字段的作用：
+
+- `schemaVersion`：配置结构版本，当前为 `1`，不能通过 config 命令修改。
+- `policyFile`：项目安全背景和审查规范。初始化生成合法 skill 格式的通用起点；维护者需要补充真实安全边界、攻击前提与已确认的部署条件。扫描自动通过知识文档传入；修复复核将规范与原始证据一起放进私有输入文件。不执行规范中的脚本或安装其他 skill。存放在 skill 目录不代表扫描依赖 AI 助手先加载 skill；也可以配置成仓库根 `SECURITY.md`。
+- `reportTemplate`：人工中文复核报告的结构和证据要求。CLI 检查并记录其摘要，但不会用一次扫描自动代替人工复核，也不会将模板任意插入自动摘要。人工报告按模板整理后保存到 `reviewDir`。
+- `trackerFile`：团队共享的稳定编号台账。scan/diff/branch 完整结果写其工作副本，list/update/verify 使用同一个文件；没有该字段时沿用仓库外本机私有台账。配置路径不会自动搬迁、覆盖或合并原台账。
+- `summaryDir`：自动生成的脱敏中文摘要目录，按 UTC 日期和执行标识分文件。必须由 Git 忽略，且不能包含已跟踪文件；初始化会补充 ignore 规则。每次执行仍保留仓库外私有摘要原件。没有此字段时只保存私有摘要。
+- `reviewDir`：维护者整理、审核后的人工报告目录。初始化创建目录；扫描不会自动写入完整人工报告。可以自行审核后提交其中的报告。
+- `knowledgeBase`：额外项目背景文件或目录的 JSON 数组，可包含多个相对路径。扫描会在 `policyFile` 之外传入这些材料；verify 不把这些额外材料作为知识库加载，仅使用项目规范及漏洞证据。目录中的符号链接会被拒绝。
+- `idPrefix`：稳定漏洞编号前缀，默认 `SEC`；支持 `TEAM-SEC` 等大写分段形式。已有台账须与配置一致，不自动重编号；更换前缀前应单独规划迁移。
+- `baseRef`：项目默认的分支比较目标；初始化仅保存引用名，不 fetch，也不验证该引用是否存在。
+- `model` / `effort`：团队默认模型与推理强度，初始化为 `gpt-6.1-sol` / `high`。单次命令参数可覆盖，不改变每个人的服务地址或登录。
+- `failOnSeverity`：最低阻断等级，取 `critical`、`high`、`medium` 或 `low`；默认 `medium`，即中危及以上阻断、低危警告。扫描与复核使用同一阈值，错误和证据不足始终阻断。
+
+**项目配置中的所有路径，包括 `knowledgeBase`，都相对于 Git 仓库根目录，不相对于终端当前子目录。** 不接受绝对路径、`..` 越界、`.git` 路径或符号链接；规范、模板、台账、配置和报告输出不得使用相互冲突的位置。配置是 JSON 数据，不执行项目提供的 JavaScript。服务地址、API key 和认证配置不能写入此文件。
+
+配置支持以下全部操作：
+
+```sh
+sec config --project
+sec config get policyFile --project
+sec config set policyFile .agents/skills/project-security/SKILL.md --project
+sec config set reportTemplate .agents/skills/project-security/references/report-template.md --project
+sec config set trackerFile docs/security/findings.json --project
+sec config set summaryDir docs/security/reviews/generated --project
+sec config set reviewDir docs/security/reviews --project
+sec config set knowledgeBase '["docs/architecture.md","docs/security/context"]' --project
+sec config set idPrefix TEAM-SEC --project   # 空台账或同前缀台账才可修改
+sec config set baseRef origin/main --project
+sec config set model gpt-6.1-sol --project
+sec config set effort high --project
+sec config set failOnSeverity medium --project
+sec config unset knowledgeBase --project
+sec config unset baseRef --project
+```
+
+`get <key>` 输出所选项目字段，数组输出 JSON；baseRef/model/effort 未设置时显示个人值或工具默认值，其他缺省字段显示“未设置”。`set <key> <value>` 只改该字段并校验配置，`knowledgeBase` 要用引号包住 JSON 数组。`unset <key>` 删除所选字段；删掉路径字段就停止对应的项目集成，不删除原文件。再次 `init project` 会补回默认字段。可以直接编辑 JSON；修改路径不会搬迁文件，需先准备对应文件；改变摘要目录后可运行初始化补充 ignore 规则。配置和初始化命令均不调用模型。
+
+`--project` 写业务仓库根的共享配置；`--local` 仍是仓库外、仅当前电脑 checkout 的 baseRef 覆盖，两者不能同时使用。个人与 `--local` 作用域仍只支持 baseRef，模型个人设置通过 setup 管理。
+
+- 比较目标：单次 `--base` → 本机 `--local` → 项目 `--project` → 用户默认值 → `origin/HEAD`。
+- 模型和推理强度分别选择：单次 `--model` / `--effort` → 项目共享值 → 个人设置 → 工具默认值。
+
+正式扫描和 dry-run 会先检查项目规范、模板、额外材料和摘要目录配置；必需文件缺失或不合规时在调用模型前报错。项目规范和额外材料读取当前工作区版本，即使 branch/diff 的业务代码来自已提交/暂存快照；其路径与 SHA-256 记录在私有 `wrapper-result.json.projectInputs`。扫描传入规范和额外材料的私有副本。期间规范、模板、项目配置或额外材料变化会拒绝入账；不要一边扫描一边修改这些文件。
+
+**_项目模式允许 CLI 更新配置指定的共享台账工作副本及被忽略的脱敏摘要，不自动暂存、提交或改写业务源码。初始化和 config --project 则按命令目的修改项目接入文件。完整原始证据、源码片段、模型输入、认证和 key 仍保存在仓库外。_**
+
+维护者应审核后将 `sec.config.json`、规范、模板、共享台账及 ignore 规则提交到业务仓库；自动摘要不提交，人工报告检查脱敏后再提交。同事需使用相同 CLI/引擎版本、代码快照和有效设置，结果才具有可比性；模型发现不保证逐次完全相同。多人在不同分支分配编号可能产生 Git 冲突，需要按证据协调；相同编号不能单独证明是同一漏洞，本机文件锁不能解决跨电脑冲突。
+
+共享台账只包含脱敏信息和私有证据索引。换电脑后，自动导入项可能缺少完整证据，verify 会拒绝关闭问题；应恢复对应执行目录到 `sec paths` 显示的 runs 下、重新扫描刷新关联，或由维护者整理足够的脱敏证据。不自动搜索或导入其他工具的状态目录。人工已整理证据的历史台账可继续使用，历史编号与基线保持不变。
+
+## 项目自己的安全背景
+
+本包不携带任何使用项目的规范、架构或文件清单。需要让扫描器了解本地规范时，可以初始化项目共享规范，或显式追加你控制的文件：
+
+```sh
+sec branch --knowledge-base /path/to/local-context.md
+sec scan --knowledge-base /path/to/local-context.md --knowledge-base /path/to/other-context.md
+```
+
+它们会作为扫描上下文发送给所选模型，并可能随原始产物保存在私有目录，不会被复制进 CLI 源码或 npm 包。没有安装 skill 的要求。
+
+## 台账与修复复核
+
+```sh
+sec:list
+sec:list --severity high
+sec:list --all
+sec:update SEC-001 SEC-002
+sec:verify
+```
+
+list、update 不联网、不调用模型。update 只将指定编号追加到待验证队列，未知/重复编号整批拒绝，不清空其他项。
+
+verify 调用官方 `verify-fix` 的 static 模式，仅处理待验证项与必要关联代码。无队列直接跳过；不会运行应用、安装项目依赖或执行线上验证。fixed 记为 verified_static，仍有问题回到 open，证据不足保留 pending_verification。仅验证指定快照，不代表线上通过。
+
+扫描按规则、锚点和主要路径指纹关联稳定的 SEC 编号；缺少锚点或关联歧义会标记人工复核。再次报告已复核项会重新打开，新扫描未报告旧项不会自动关闭。并发写入用锁和内容比较保护；未启用共享台账时，同一仓库不同本机路径的数据不会自动合并；启用后通过业务仓库的 Git 协作共享，冲突需人工协调。
+
+自动导入项必须有原始私有证据才能定向复核。移动/删除状态目录、换电脑或移动 checkout 后，只有台账 JSON 不足以恢复复核；需恢复完整、匹配的证据或重新扫描。锁文件遗留时先确认无运行进程，再处理，不要强行覆盖并发台账。
+
+## 数据与配置位置
+
+```sh
+sec paths
+sec doctor
+```
+
+默认位置：
+
+- 无 key 的配置：`~/.config/sec/config.json`，可由 `XDG_CONFIG_HOME` 改变。
+- 引擎隔离的 `CODEX_HOME`：上述配置目录下的 `engine-home/`，作为 sec 专用的配置及凭据导入来源，不使用日常 Codex 目录。
+- 官方引擎实际的独立认证目录：`~/.local/state/sec/engine/codex-home/`，由官方 CLI 管理，可能使用文件或系统凭据存储；以 `sec auth` 显示的位置为准。
+- 缺失引擎时的安装位置：上述配置目录下的 `runtime/`。
+- 每仓库比较目标配置：`~/.local/state/sec/repositories/<本机仓库路径哈希>/config.json`，可用 `sec config --local` 管理。
+- 未启用项目共享台账时的每仓库私有台账：`~/.local/state/sec/repositories/<本机仓库路径哈希>/ledger.json`。
+- 每次执行：同目录 `runs/<UTC 时间>-<模式>-<UUID>/`，包括 summary.md、原始报告、校验与复核资料。
+- 项目规范与知识文档副本：同目录 `contexts/<执行标识>/`，与对应 `runs/<执行标识>/` 配对保留；引擎启动前的报告输出目录必须为空。
+- 状态根目录支持 `SEC_STATE_DIR`；否则使用 `XDG_STATE_HOME` 或默认值。
+- 仓库外临时快照结束时删除，目录回退使用用户缓存下的 `sec/tmp`。
+
+基础私有模式不需要修改业务仓库；`init project` 按上述约定创建接入文件并补充 ignore，`config --project` 修改共享配置。两种模式都不修改项目 package.json、Git 配置或提交 hook。私有状态与认证目录必须在被扫描仓库外。原始证据、输入和诊断可能包含源码与漏洞详情，应保留在私有位置；自动摘要仅复制允许的元数据、等级和相对位置。
+
+doctor 只检查本地依赖及配置，不检验 key 或实际模型权限。运行环境升级、换用户、换配置目录时可能需要重新 setup。
+
+## 完整命令参考
+
+以下列出当前版本的全部命令及支持的参数。示例采用标准入口 `sec <命令>`；安装 shell 快捷命令后，均可等价写为 `sec:<命令>`，例如 `sec branch --base origin/main` 等价于 `sec:branch --base origin/main`。
+
+`<ref>`、`<path>`、`<url>`、`<model>`、`<effort>` 表示需要替换的参数值，不要连同尖括号输入。路径含空格时用引号包住；需要值的长参数也可写为 `--base=origin/main` 这种形式。不同参数可以组合，具体示例见各命令。
+
+扫描、台账、排队、复核和 paths 命令需在 Git 仓库内运行，可从根目录或子目录调用；它们会定位到仓库根目录。setup、doctor、auth、用户级 config、aliases、help 和版本查询不要求位于 Git 仓库内；`sec config --local`、`sec config --project` 和 `sec init project` 需要定位当前 Git 仓库。
+
+### 1. 帮助与版本
+
+```sh
+sec                         # 不带任何参数，显示总帮助
+sec help                    # 显示总帮助
+sec --help                  # 显示总帮助
+sec -h                      # 总帮助的简写
+sec branch --help           # 显示总帮助，不执行 branch
+sec setup --help            # 显示总帮助，不执行 setup
+sec --version               # 显示本工具版本
+sec -v                      # 版本查询的简写
+```
+
+所有子命令都支持 `--help`，当前统一显示总帮助，不执行该命令的实际动作。不读取凭据、不调用模型、不写配置或扫描数据。快捷命令可用 `sec:help`、`sec:branch --help` 等形式。
+
+`-h` 仅作为顶层帮助简写，`-v` / `--version` 仅作为顶层版本查询。当前没有 `sec version` 或 `sec:version` 命令。
+
+### 2. sec setup：用户级初始化
+
+```sh
+sec setup
+sec setup --api-key
+sec setup --base-url https://api.example.test/v1 --model your-model
+sec setup --model your-model
+sec setup --effort high
+sec setup --model gpt-6.1-sol --effort xhigh
+sec setup --base origin/main
+sec setup --no-aliases
+sec setup --base-url ''
+sec setup --api-key --base-url https://api.example.test/v1 --model your-model --effort high --base origin/main --no-aliases
+```
+
+不带参时，交互式询问服务地址、模型和推理强度，检查依赖，按需安装兼容引擎，保存个人登录及用户配置，并询问是否安装快捷命令。已有地址/模型/强度时留空保留；首次使用时留空采用官方服务、`gpt-6.1-sol` 和 `high`。已有登录会询问是否更换 key，默认保留。
+
+- `--api-key`：跳过已有登录状态检查，直接隐藏输入自己的 key。它是布尔开关，不接收 key 值；其他初始化步骤仍照常执行。
+- `--base-url <url>`：本次直接指定服务地址，跳过地址提问；地址不得含用户名、密码、查询参数或片段。自定义地址使用兼容 Responses 的接口，且需要支持所选模型。
+- `--model <model>`：本次直接指定并保存模型，跳过模型提问。不改变当前服务地址或推理强度。
+- `--effort <effort>`：本次直接指定并保存推理强度，跳过强度提问。不改变模型或服务地址；首次默认 `high`。
+- `--base <ref>`：保存用户级默认分支比较目标，供以后所有项目的 branch 使用；当前仓库配置和单次 `sec branch --base` 可以覆盖它。以后可用 `sec config set baseRef <ref>` 单独修改，无需重新 setup。它不是对当前仓库分支的修改，也不会 fetch 该引用。
+- `--no-aliases`：本次不询问、不安装 shell 快捷命令；不删除之前已经安装的快捷命令。
+- `--base-url ''`：清除已保存的自定义服务地址，恢复使用扫描器的官方默认服务；保留已配置模型。空的 `--model ''` / `--effort ''` 会保留原值；尚无原值时使用工具默认值，清除默认 base 使用 `sec config unset baseRef`；当前没有专门清除模型的开关。
+
+这些参数可以组合。即使提供了地址、模型等参数，setup 仍需交互式终端，用于登录相关输入及必要确认。会写用户配置、个人登录目录，按需联网安装引擎；选择安装快捷命令时会备份并修改 shell 配置。不发起安全扫描或模型请求，不修改业务仓库。
+
+### 3. sec scan：扫描全仓当前工作区
+
+```sh
+sec scan
+sec scan --model gpt-6.1-sol --effort high
+sec scan --effort xhigh
+sec scan --knowledge-base /path/to/local-context.md
+sec scan --knowledge-base ./local-context.md --knowledge-base '/path/with spaces/policies.md'
+```
+
+不带参时，对当前 Git 仓库的工作区发起全仓扫描，范围不限于当前分支新增的内容，也不限于暂存内容。实际纳入/排除文件及覆盖限制以官方产物为准，全仓范围不保证逐文件完整审计。
+
+- `--model <model>` / `--effort <effort>`：仅覆盖本次扫描，按[模型与推理强度](#模型与推理强度)的优先级解析，不保存。可以单独使用，也可与本命令其他参数组合。
+- `--knowledge-base <path>`：额外提供本地安全背景文件或目录；可重复传入多次。相对路径从执行命令时的当前目录解析。相关内容会发送给所选模型，并可能保存在私有原始产物中。
+
+完成后保存私有报告和自动摘要，关联或新增本仓库的台账项。会调用模型并消耗额度。扫描期间修改工作区、HEAD 或 index 会导致结果无法导入。
+
+**_扫描结束前保持文件和 Git 状态稳定，具体文件范围及中断影响见[扫描期间注意事项](#扫描期间注意事项)。_**
+
+### 4. sec diff：扫描暂存差异
+
+```sh
+sec diff
+sec diff --model gpt-6.1-sol --effort high
+sec diff --effort medium
+sec diff --knowledge-base /path/to/local-context.md
+sec diff --knowledge-base ./local-context.md --knowledge-base ./other-context.md
+```
+
+不带参时，扫描 HEAD 到真实 Git index 的差异，也就是已暂存的新增、修改、删除和重命名。支持首次提交、部分暂存与独立 index；同一文件尚未暂存的修改不进入快照。为判断改动影响，扫描器可能读取快照中的必要关联代码。
+
+- `--model <model>` / `--effort <effort>`：仅覆盖本次扫描，按[模型与推理强度](#模型与推理强度)的优先级解析，不保存。可以单独使用，也可与本命令其他参数组合。
+- `--knowledge-base <path>`：含义、相对路径规则及多次传入方式与 scan 相同。
+
+没有暂存差异时直接跳过，不调用模型，也不生成执行报告或更新台账。有差异时使用仓库外隔离快照扫描，完成后保存产物并关联台账；会消耗模型额度。不自动替你执行 `git add`，也不重设暂存区。
+
+**_扫描结束前不要改变暂存区或 HEAD；未暂存修改不会被本次扫描覆盖，详见[扫描期间注意事项](#扫描期间注意事项)。_**
+
+### 5. sec branch：扫描当前分支的已提交差异
+
+```sh
+sec branch
+sec branch --model gpt-6.1-sol --effort high
+sec branch --effort xhigh
+sec branch --dry-run
+sec branch --base origin/main
+sec branch --base origin/develop --dry-run
+sec branch --base v1.0.0
+sec branch --base <commit-sha>
+sec branch --knowledge-base ./local-context.md
+sec branch --base origin/main --knowledge-base ./local-context.md --knowledge-base ./other-context.md
+sec branch --base origin/main --dry-run --knowledge-base ./local-context.md
+```
+
+不带参时，先选择比较目标，再扫描目标与当前 HEAD 的唯一共同祖先到 HEAD 的已提交净差异。默认目标的优先级为：本次 `--base` → 本机仓库 baseRef → 项目共享 baseRef → 用户级 baseRef（setup 或 config 保存）→ 本地 `origin/HEAD`。它不是从首次创建分支的时间开始扫描，也不是按提交作者筛选。
+
+- `--base <ref>`：本次指定目标分支、标签或提交。引用必须能在本地解析；不会保存成默认值，也不会自动 fetch。`<commit-sha>` 是占位写法，应替换成实际提交 SHA。
+- `--dry-run`：只预览扫描范围，不执行漏洞分析。展示目标引用及解析出的提交、共同祖先、当前 HEAD，以及差异文件的增删行统计；空差异只显示跳过提示。
+- `--model <model>` / `--effort <effort>`：仅覆盖本次扫描，按[模型与推理强度](#模型与推理强度)的优先级解析，不保存。可以单独使用，也可与本命令其他参数组合。
+- `--knowledge-base <path>`：额外提供本地安全背景，规则与 scan 相同，可多次传入。
+
+`--dry-run` 可以与其他参数组合，但不会启动引擎、检查 key 或生成报告/台账；会检查项目配置中的规范、模板和额外材料，但不验证单次显式 --knowledge-base 的内容；它确认的是本地 Git 差异范围。正式扫描会调用模型、保存私有产物并关联台账；无已提交差异时直接跳过。
+
+暂存、未暂存及未跟踪内容都不在 branch 的目标快照内。目标分支独立新增的内容不会被当作本分支改动。目标引用缺失、历史不足、共同祖先不唯一、冲突或正在进行的合并/摘取/变基会阻止执行，需要先处理后重试。
+
+**_正式扫描结束前不要提交、切换分支或改写 HEAD；接近完成时改变 HEAD 仍可能导致无法入账，详见[扫描期间注意事项](#扫描期间注意事项)。_**
+
+### 6. sec list：按等级查看有效台账
+
+```sh
+sec list
+sec list --severity critical
+sec list --severity high
+sec list --severity medium
+sec list --severity low
+sec list --all
+sec list --all --severity high
+```
+
+不带参时，按 critical、high、medium、low 顺序列出当前仓库的 open 和 pending_verification 项，默认隐藏 verified_static 项。
+
+- `--severity <level>`：只显示指定等级，取值仅限 `critical`、`high`、`medium`、`low`。
+- `--all`：包含已通过源码复核的历史项；可与 `--severity` 组合。
+
+此命令只读有效台账，不调用模型、不更新状态。没有台账时显示零项；这只表示本机没有相应记录，不代表项目已经扫描或没有漏洞。
+
+### 7. sec update：将指定编号加入待验证队列
+
+```sh
+sec update
+sec update SEC-001
+sec update SEC-001 SEC-002
+sec update 'SEC-001    SEC-002'
+```
+
+不带参时只显示操作提示，不修改台账。带一个或多个完整 SEC 编号时，将指定项标为 pending_verification，记录排队时间与当前 HEAD，保留其他已排队项。支持多个参数，也支持一个参数内用空白分隔多个编号。
+
+只更新有效台账，不调用模型，不代表问题已经修复。未知编号、重复编号或格式错误会整批拒绝，不进行部分更新。再次排入已通过源码复核的项，可用于检查后续改动是否重新引入问题。
+
+完成后运行 `sec verify` 才会真正复核。update 不接受 `--all` 或等级过滤，需明确指定编号。
+
+### 8. sec verify：定向复核已排队项
+
+```sh
+sec verify
+sec verify --model gpt-6.1-sol --effort high
+sec verify --effort xhigh
+sec verify --list
+sec verify --pending SEC-001
+sec verify --pending SEC-001 SEC-002
+```
+
+不带参时，使用默认模型设置复核本仓库台账中全部 pending_verification 项；没有待验证项时直接跳过。使用当前工作区源码和原始漏洞证据，范围包含必要关联代码，不仅是几行 diff。
+
+- `--model <model>` / `--effort <effort>`：仅覆盖本次实际复核，按[模型与推理强度](#模型与推理强度)的优先级解析，不保存。不能与 `--list` 或 `--pending` 组合。
+- `--list`：兼容的只读入口，显示全部状态的台账，相当于 `sec list --all`；不调用模型，也不修改状态。不与 `--pending` 等其他参数组合。
+- `--pending <ID> [<ID> ...]`：兼容的排队入口，行为对应 `sec update`，只排队、不调用模型；每个编号作为独立参数传入。之后还需再次运行不带参的 `sec verify` 才会复核。
+
+真正复核会调用模型，保存私有输入、验证结果和摘要，并更新台账：fixed → verified_static；still_vulnerable → open；inconclusive → pending_verification。缺失或损坏的原始证据、无效结果、取消或期间状态变化不能用于关闭问题。
+
+**_复核结束前保持整个仓库文件、HEAD、暂存区、台账及原始证据稳定；不限于本次漏洞所在文件，详见[扫描期间注意事项](#扫描期间注意事项)。_**
+
+verified_static 只表示指定快照通过源码复核，不代表运行时/线上验证通过，也不代表整个项目安全。此命令不执行新的全仓发现，不运行应用、项目测试或线上请求。
+
+`sec verify SEC-001` 不是有效用法；要只复核某些项，先明确排队。其他已经排队的项仍会一起复核，工具没有“只处理本次新增队列”的参数。
+
+### 9. sec paths：查看本项目的数据位置
+
+```sh
+sec paths
+```
+
+不带参时，以 JSON 显示用户配置文件、本仓库比较目标配置（`repositoryConfig`）、共享项目配置（`projectConfig` 与 `project`）、状态目录、有效 ledger 文件和 runs 目录的位置，便于查找报告或保留私有证据。不调用模型，不创建这些目录，也不修改台账。除通用 `--help` 外，不接受其他参数。
+
+### 10. sec doctor：检查本地环境
+
+```sh
+sec doctor
+```
+
+不带参时，读取并校验用户配置，检查 Git、Python 和兼容扫描引擎，显示版本、路径，以及当前仓库的有效模型和推理强度（仓库外显示个人默认值）。依赖缺失、配置无效或引擎版本不符时返回非零，并提示处理方向。不会自动安装依赖、提示输入 key 或发起真实请求。
+
+此命令只能确认本地环境条件，不检验 API key、网络可达性、额度和模型权限。除通用 `--help` 外，不接受其他参数。
+
+### 11. sec aliases：打印或安装 sec:xxx 快捷命令
+
+```sh
+sec aliases
+sec aliases --install
+sec aliases --install --shell zsh
+sec aliases --install --shell bash
+```
+
+不带参时只打印 alias 定义，便于检查或手动安装，不修改 shell 配置。
+
+- `--install`：将 alias 段安装到当前 shell 的配置文件，默认根据 `$SHELL` 判断 zsh 或 bash。已有文件变更前会备份，保留其他内容；重复安装相同内容不重复追加。
+- `--shell zsh` / `--shell bash`：与 `--install` 一起使用，指定安装目标。仅传 `--shell` 而没有 `--install` 时，仍然只打印通用定义，不写文件。
+
+安装包含 `sec:init`（用法 `sec:init project`）、`sec:setup`、`sec:doctor`、`sec:auth`、`sec:config`、`sec:scan`、`sec:diff`、`sec:branch`、`sec:list`、`sec:update`、`sec:verify`、`sec:paths`、`sec:aliases`、`sec:help`。这些 alias 分别调用对应的 `sec <命令>`，参数含义不变。升级前已安装的 alias 需要重新运行 `sec aliases --install` 并加载 shell 配置，才能使用新加的 `sec:init` / `sec:auth` / `sec:config`；标准入口 `sec auth` / `sec config` 不依赖 alias。
+
+安装不会让父终端立即加载新定义；打开新终端，或在当前 shell 中手动 source 对应配置文件后使用。不支持的 shell 请使用标准命令，或手动配置适合该 shell 的快捷方式。此命令不配置认证、不运行扫描。
+
+### 12. sec auth：查询 sec 的登录方式
+
+```sh
+sec auth
+sec auth --json
+sec:auth             # 安装并加载新版 alias 后等价使用
+```
+
+不带参时，显示已保存的登录类型、当前环境中设置的 API key 变量名、非交互扫描默认认证方式及其来源、独立认证目录，以及是否使用自定义 provider。详情及状态查询的本机缓存影响见[查询登录方式](#查询登录方式)。
+
+- `--json`：以 JSON 输出相同信息，不混入文字说明；此参数仅供 auth 使用，不是通用参数。`savedLogin` 取值为 `api_key`、`chatgpt`、`none` 或 `unknown`；`environmentApiKeys` 仅含已设置且非空的变量名；`noninteractiveDefault` 包含默认的 `method` 和 `source`，无法确认来源时 `source` 为 `null`。
+
+这是认证来源查询，不验证登录有效性、模型权限或订阅额度，也不运行安全扫描。未登录且无环境 key，或查询无法完成时返回 `2`，其余已确认情况返回 `0`。除 `--json` 和通用 `--help` 外，不接受其他参数或位置参数；没有 `sec auth login` / `logout` 子命令。
+
+### 13. sec config：管理默认比较分支与项目配置
+
+```sh
+sec config
+sec config get baseRef
+sec config set baseRef origin/master
+sec config set baseRef origin/main
+sec config unset baseRef
+sec config --local
+sec config get baseRef --local
+sec config set baseRef origin/master --local
+sec config unset baseRef --local
+```
+
+不带参时显示用户级配置文件位置、已保存的 baseRef 和回退后的默认值，不显示 provider、凭据或其他配置内容。增加 `--local` 时切换到当前仓库作用域，同时显示继承后的默认目标。
+
+- `get baseRef`：只输出所选作用域的默认目标。用户级未设置时为 `origin/HEAD`；本机仓库级未设置时依次继承项目共享值、用户级值和 `origin/HEAD`。在仓库内查询用户级值仍需与 `--local` 区分；该命令不解析 Git 提交或应用单次 `--base`。
+- `set baseRef <ref>`：只保存这一字段，保留其他设置，不运行完整 setup。`<ref>` 可填 `origin/master`、`origin/main` 或其他本地可解析的分支、标签、提交；保存时仅校验参数格式，不确认引用存在。真正检查范围用 `sec branch --dry-run`。
+- `unset baseRef`：仅清除所选作用域的 baseRef，恢复继承/回退；不清除另一作用域的设置，也不删除模型、服务地址或登录。未设置时不创建配置文件。
+- `--local`：与查询、get、set、unset 均可组合，配置只对当前本机 checkout 生效。文件保存在仓库外私有状态目录，不修改 `.git/config`、`origin/HEAD` 或任何业务仓库文件。
+
+用户级和 `--local` 仅支持 `baseRef`；增加 `--project` 后支持全部项目字段，详见[项目初始化与团队共享规范](#项目初始化与团队共享规范)。命令不请求模型、不重新登录、不 fetch；不依赖 Python 或扫描引擎。有效查询/修改返回 `0`，参数、配置、目录或写入错误返回 `2`。除 `--local`、`--project` 和通用 `--help` 外，不接受其他选项；`--local` 和 `--project` 互斥。配置位置、优先级及手动编辑方法见[默认比较分支配置](#默认比较分支配置)。
+
+### 14. sec init project：初始化项目规范
+
+完整用法为 `sec init project`、`sec init project --dry-run` 和 `sec init project --help`。不带参数的 `sec init` 报用法错误；没有覆盖参数。生成文件、重复执行、配置字段、已有台账兼容及路径解析见[项目初始化与团队共享规范](#项目初始化与团队共享规范)。
+
+### 15. 参数边界、输出与退出码
+
+- 扫描的 `--dry-run` 和 `--base` 仅由 branch 支持；init project 也支持仅预览初始化计划的 `--dry-run`；setup 的 `--base` 用于保存默认值。scan / diff 不支持这两个扫描选项。
+- `--model` / `--effort` 可在 setup 中保存个人设置，也可在 scan / diff / branch / verify 中单次覆盖；单次覆盖不写配置。
+- `--knowledge-base` 仅由 scan / diff / branch 支持，可重复传入；verify 通过台账及原始证据执行复核，不接受该参数。
+- 本工具只接受上面列出的参数，不会把任意官方引擎参数自动透传。`--json` 仅由 auth 支持，当前没有通用 `--json`、`--output-dir`、自动修复或发布命令。
+- 返回 `0`：命令完成且未被门禁阻断，也可能只是帮助、预览、空范围跳过或只剩低危问题。不能仅据此认定已扫描或全项目安全。
+- 返回 `1`：完整扫描发现达到有效门禁等级的问题，或定向复核确认达到该等级的问题仍存在；完整发现仍会记录到台账。
+- 返回 `2`：参数、环境、认证、执行或产物错误；定向复核证据不足也返回 2。复核证据不足可保留待验证状态和结果记录，执行错误不会被当作修复通过。
+- 被取消或终止时可能返回 `130`、`143` 等非零状态。完整原始报告和复核证据保存在本机私有目录；启用项目配置时可更新共享台账和忽略的脱敏摘要。这些业务仓库内容不进入 npm 包。
+
+## 开发与发布检查
+
+本仓库只有工具代码和合成测试数据；测试不会读取真实 key、调用模型或修改用户 shell 配置。封装测试不能替代一次真实扫描验证。实际 npm 安装包通过 files 白名单仅包含 bin、lib、两份 templates Markdown、README、LICENSE 和 package.json；测试、脚本、Git 历史及扫描数据不发布。
+
+```sh
+pnpm install --frozen-lockfile --ignore-scripts
+pnpm test
+pnpm check
+pnpm check:package
+pnpm pack
+```
+
+发布检查应核对真实 tarball 的文件名与内容。`check:package` 会限制包内文件范围、检查个人路径和常见凭据特征，并确认两份模板实际随包分发。它不能代替维护者对源码及新增内容的检查。
+
+`pnpm release:check` 汇总包元数据、语法、全部合成测试与实际 tarball 检查，不发布、不登录、不请求模型。直接从本目录运行 `npm publish` 前，`prepublishOnly` 会自动执行这一检查；不要用 `--ignore-scripts` 绕过正式发布门禁。
+
+```sh
+pnpm release:check
+npm publish --dry-run --ignore-scripts --access public --registry=https://registry.npmjs.org/
+```
+
+第二条命令只预演 npm 打包，不上传；这里跳过生命周期脚本是因为前一条已完整检查，避免再次执行同一组测试。预演成功不能证明 npm 账号、scope、双因素认证或发布权限可用。
+
+## 首次发布
+
+包名为 `@itenl/sec`，本次版本为 `0.1.1`。发布者的 npm 账号必须拥有 `@itenl` scope 或相应组织的发布权限；GitHub 账号和仓库所有权不会自动授予 npm 权限。维护者应先检查 GitHub 仓库公开内容、完成自己的提交和推送，再将仓库公开。GitHub 仓库可见性与 npm 包可见性互相独立。
+
+在完成上面的发布检查及本地 tarball 安装验证后，由发布者在终端执行：
+
+```sh
+npm login --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+`npm publish` 会真正上传公开包，发布者按 npm 的提示完成账号或双因素认证，不把 token、密码或验证码写入仓库。包内的 `publishConfig` 固定公开访问和官方 npm registry；`private:true` 已移除。公开包会分发 npm tarball 中的 CLI 源码、通用模板、README 和许可证，不包含业务仓库、测试数据或 Git 历史。
+
+发布完成后检查版本，并在新的终端或干净账户按快速开始验证：
+
+```sh
+npm view @itenl/sec@0.1.1 version --registry=https://registry.npmjs.org/
+npm install -g @itenl/sec@0.1.1
+sec --version
+sec setup
+```
+
+更新版本时同步 `package.json`、本 README 的版本示例与 `CHANGELOG.md`；已经发布的名称和版本组合不能通过再次上传来覆盖。PR 自动扫描、远程扫描服务和独立 skill 分发不属于当前版本。
+
+## 卸载与重新初始化
+
+卸载当前 Node/npm 环境中的 CLI：
+
+```sh
+npm uninstall -g @itenl/sec
+```
+
+如果安装过快捷命令，从 zsh 的 `${ZDOTDIR:-$HOME}/.zshrc` 或 bash 的 `~/.bashrc` 中移除下面两个标记之间的整段内容（包含标记），保留其余 shell 配置；打开新终端后生效：
+
+```text
+# >>> sec CLI aliases >>>
+# <<< sec CLI aliases <<<
+```
+
+卸载包会保留 sec 的个人登录、配置、报告及台账。需要重新走首次 setup 时，可先把自己的配置和状态目录移到备份位置。先结束所有扫描或复核，再执行；状态目录包含完整扫描证据，不应为了重测直接丢弃。
+
+```sh
+sec_reset_stamp=$(date +%Y%m%d-%H%M%S)
+sec_config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/sec"
+sec_state_dir="${SEC_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/sec}"
+
+[ ! -d "$sec_config_dir" ] || mv "$sec_config_dir" "${sec_config_dir}.backup-$sec_reset_stamp"
+[ ! -d "$sec_state_dir" ] || mv "$sec_state_dir" "${sec_state_dir}.backup-$sec_reset_stamp"
+```
+
+这会移开 sec 专用文件配置和认证缓存，保留备份；不需要删除日常 Codex 目录。官方引擎如使用系统凭据存储，保存的登录仍可能被识别，应以重新安装后的 `sec auth` 为准。环境 API key 也可能继续生效，请检查它报告的认证来源。项目里的共享配置、规范和台账保持原样；验证全新项目初始化时使用另一个干净测试仓库。
+
+重新安装并运行 `sec setup` 即可继续。多套 Node 版本各自可能有全局安装，可用 `type -a sec` 检查来源。已有 Git、Python 或全局扫描引擎仍可能被复用；完整模拟一台没有任何依赖的新电脑，使用独立的系统账户或干净环境。