getadvantage-cli

优势 开源的AI控系统只需一条命令是否安全 检测泄露提交的`文件、是否干净、构建 —0`（通过）或`1`（不通过）。，无依赖，不会离开您的机器。 [](https://www.npmjs.com/package/getadvantage) 量](https://img.shields.io/npmantage)](www.npmjs.com/packageantage) [ [](nodejs.org) AI编写代码。**谁在代码部署它？** ```bash npx getadvantage # 一安全检查（通过通过）-安装，无需注册 您的 AI 代理一个外部检查者，它必须通过aude Code · Cursor · Codex · Grok Build）： ```bash claude add getadvantage getadvantage m``` 在每次推送前门控： ```bash npx getadv # 自动 CI 工作流 ``` 在部署前捕获了问题，**请为加星** —者可以通过星级判断依赖它。遇到问题新增检查？**** — 每个问题都会被阅读和回答 您将获得 一个本地、无依赖的**预控 + 便携式项目大脑**，适用于 AI的应用 — Claude Code、Cursor、Lovable、Bolt、v0、Replit 等。 在您的仓库中运行。它读取您的项目并为您提供： - **部署前的一句语言判断** — 代码中没有秘密， 没有提交的 `.env`， 一个干净的工作树， 构建 + 类型检查， 模式版本检查。 - **便携式项目大脑** (`PROJECT-BRIEF.md`) — 一个单页的、与模型无关的项目记忆，任何模型、会话或工具都可以读取它，这样您就不需要重复解释。 - **会话交接** (`HANDOFF.md`) — 保存您的位置，然后开始一个新的、快速的会话（或切换模型），无需损失任何内容。 - **MCP 服务器** (`getadvantage mcp`) — 让 AI 代理（Claude Code，Cursor）可以在会话中调用大脑 + 检查，而无需离开聊天。 - **扇出 + 安全扇入导演** (`getadvantage fan-out <n>` · `fan-in`) — **安全地部署多个 AI 代理**。任何人都可以并行运行代理（每个代理都在自己的 git 工作树中，共享同一个大脑）；难点在于协调它们生成的内容。该导演将它们协调成一个**校验的主线**：一个**冲突地图**（哪些文件被多个分支触及），一个**合并列车**（文本冲突提前暴露），**组合树门，它在后重新运行检查，以便捕获“都通过后失败”的隔离该分支 —不会将未经验证的冲突提交到主线。尝试使用一条命令：`getadvantage demo`可选的运行报告** (`--report`)getadvantage login` 一次，然后 `check --report` / `fan-in --report` 将每次**判决 + 元数据**（`--json` 永远不会源代码）发布到Advantage 帐户。`getadvantage github-action相同的门控写入 CI。无需 `--report`内容都不会离开您的机器。 您的上下文存储在您的**中，而不是您的工具中。您可以从 Claude到 Cursor 再切换到 Qwen 并继续进行不是拖着一个缓慢、臃肿的会话，而是开始一个干净、快速的会话。 ## 使用方法 无需安装： ```bash npx getadvantage # 运行预部署检查（通过/不通过） npx getadvantage brief # 生成/刷新项目大脑 npx getadvantage init # 在每次会话开始时自动加载大脑 npx handoff # 为下一次会话保存您的位置 npx getadvantage switch # 在不丢失上下文的情况下切换工具/模型 npx getadvantage mcp # 运行 MCP 服务器（代理在会话中） npxantage fan-out 3 # 3 个并行分支共享一个大脑（然后 `fan-in`）） ``` 或添加到您的项目中： ```bash npm install --save-dev getadv``` ```jsonc // package.json始终调用 getadvantage 二进制使用 bare ship-safe 名称） scripts": { "gate": "getadvantage check", "ship": "get" } } ``` ## 命令 仅需教导和使用 **`getadvantage`**。-safe` 二进制文件仍然作为的兼容别名安装，但 **`npx ship-safe` 是一个不同的 npm 包**（的、积极维护的项目）。使用 `npx ship-safe` —无法运行 getAdvantage。 | 功能 | |---|---| | `getadvantage ship` | 完整的门控，包括：是否可以部署？退出 ** 为 `0`，**NO-GO** 为 `1`。与 `check --build` 相同 — 您记住的名称。 | |advantage check` | 只读预部署检查 → 退出 **GO** 为 `0`，**NO-GO** 为 `1`。添加 `--build` 以进行完整构建。运行 `getadvantage` 时不带子命令时的默认行为。 | | `getadvantage map` | 应用程序的只读地图：API 接口（哪些接口已门控，哪些接口发生突变 — 带有 **⚠**发生突变的路由，该路由没有明显的门控），代理和集成，计划和路由映射涵盖 **Next.js** 应用路由器，**Express/Fastify** **Flask/FastAPI** （而为的正则表达式解析 — 不运行代码）；其他堆栈获取属性视图和诚实的范围注释。方向，而不是判决 — 始终退出 `0`。 | | `get | 生成/刷新 `PROJECT-BRIEF.md`冷** 层（项目**是什么**）。在 `getadvantage:brief:notes` 标记之间的手写笔记在再生。`--check` 警告已过时；它永远不会阻止| `getadvantage handoff`刷新简介 **和** 编写 `` — **热** 层离开的地方**）。您的笔记在；它永远不会覆盖它创建OFF.md`。 | | `antage init`大脑连接到代理文件 (`CLAUDE.md` / `` / `.cursorrules` / `.frules` / `.clinerules`)在会话开始时自动加载 `PROJECT-BR` + `HANDOFF.md`。 | | `getadvantage switch [tool]` | 在不丢失上下文的情况下切换工具/模型 — 保存您的位置，连接每个 AI 工具文件，并打印开始新会话的提示。 | | `getadvantage models` | 选择和切换 AI 模型的纯（原则 | |antage gauge` | 快速判断“变得很（自上次以来的仓库活动），在事情变重置 — 一种启发式方法，而不是令。 | | `getadvantage ledger` | 显示会话账本 — 每个 ` 记录的运行日志（保存在 `.getadvantage/ledger.md` 中；旧的-safe/` 目录仍然被读取并在时迁移）。 | | `getadvcp` | 在 stdio 上运行的 **MCP，以便 AI 代理（Claude Code，Cursor）可以在调用大脑、门控和地图。工具_brief`，`refresh_brief`get_handoff`，`save_handoffcheck`，`map`，``gauge`。与 CLI 使用相同的引擎 — 无需 API 密钥，无需网络。 | | `getadvantage fan-out <n>` | 打开 **N 个并行分支**（1-8）作为 `HEAD` 的 git 工作树都复制并连接了大脑。添加 `--task "..."` 以打印一个共享任务到每个分支的指导中。打开不同的模型/工具，每个分支一个，平行工作。 | | `getadvantage fan-in **安全的扇**。将分支协调成一个已验证的主线：冲突地图**，合并列车**（文本冲突提前暴露），以及一个在每次合并后重新运行检查的**组合树门控**，以便捕获“单独通过但合并后失败”的情况，并隔离该分支（回滚），永远不会将未经验证的冲突提交到主线。默认是只读预览；使用 `--apply` 进行落地。 | | `getadvantage demo` | 快速创建一个示例仓库，包含 3 个预制的不同分支（一个干净的，一个破坏构建冲突的），并在其中运行整个**导演** — 整个过程仅需，无需设置。 | | `getadvantage architecture` | **增生扫描器** — 代码在哪里通过构建**覆盖**而不是折叠而腐烂？按 **size × churn ×排名最佳折叠候选者：（> 600 1000 / > 1800 行），git 变更 100 次提交），重复 ≥15（精确/近似，出现 ≥），以及 JS/TS 复杂性。**它显示** AI 编码代理缺少的信号 — 它永远不会重构意味着启发式方法没有发现任何问题，*不是* 清洁架构。**仅建议 — 始终退出 0**；`--json` 获取机器报告，`--top <n>` 调整排名大小。 | | `antage login` / `logout` | 存储（或删除）您的 `adv_live_` API 密钥在 `~/.getadvantage` 中 — 按用户、仅限文件，永远不会在仓库内。由` 使用；`GETADVANTAGE_API_KEY` 环境变量始终优先于存储的密钥。密钥永远不会被打印回来。 | | `getadvantage github-action` | 编写 `.github/workflows/getadvantage.yml`：在每次推送 + 拉取请求上运行 `getadvantage check --ci --report`（报告使用 `GETADVANTAGE_API_KEY` 仓库秘密）。 — 它永远不会在不使用 `--force` 的情况下文件。别名：`github-action`。 | |antage deploy _(高级干净的、分离的工作树 URL 的项目前缀。运行真正的 `vercel --prod`；项目前缀源自链接的 `.vercel`（或传递 `--expect-prefix`）。 | ## 门控（`check`执行的操作） | 检查 | 判决 | 详细信息 | |---|---|---| | _dirty-tree 守护进程 | **阻止** | 跟踪文件修改/将与 `vercel --prod` 一起部署。仅未跟踪文件警告。 | | 机密扫描 |** | 每个跟踪 + 暂存 **文本** 文件（包括和 `.map` 源映射，其中经常隐藏复制的中检测密钥模式 — OpenAI、Anthropic、Stripe（实时/受网络钩子）、AWS、经典 + 精细粒度）、、Slack、SendGrid、牌、裸 JWT、数据库嵌入密码）、Vercel 令牌、KV/REST 凭证、私钥块、Bearer 字面量Advantage 自己的平台密钥（`adv_live_`）。命中报告为 **屏蔽显示指纹 + sha256 身份验证 ID**（从不打印完整值）。超过 2 MB 的文件部分扫描（前 + 后 256 KB），披露并命名 — 从不沉默。**允许列表（0.8.3：内置的公共 AWS 文档密钥`AKIA…EXAMPLE`）；存储库策略在 **跟踪/提交** 的 `.getadvantage/config.json` 中（`secrets.ignore`：`values`、`hashes`、`paths`、`patternIds`）。授权读取 **git 索引** blob 仅 — 未跟踪、gitignored 或未暂存的工作树授权忽略。允许列表命中，从不沉默。 | | 跟踪的 `.env` 文件 | **阻止** | 提交的 `.env` 本身就是泄漏，无论其内容如何，因为 git保留每个值。警告本地 `.env` 文件 *不* 被 gitignore。Gitignored `. 文件从不读取。模板（`.env.example` 等）可以。 | | 类型检查 | **阻止** | `tsc --noEmit`，仅当项目实际tsconfig.json` 和本地 TypeScript 依赖（项目感知，通过 `fan-in` 的组合树门控检测）。纯 JS 项目获得诚实的跳过，而不是假失败。 | | 构建 | **阻止** | 仅在 `--build` 时运行项目的` 脚本，并且仅当存在时。 | 模式检查 |** | DDL 更改而未增加 `SCHEMA_VERSION`（不遵循该约定，则诚实地跳过）。 | | 概 | ** | API、集成和计划的只读信息性阻塞。 数据库 URL 模式故意忽略占位符密码（`mypassword`、`changeme` 等）和指向本地开发主机的 URLlocalhost`.0.0.、`0.0.0.0`、`::1`、`host.docker.internal`）— 因此，实际生产凭证使用其中一种格式不会被标记。 - 模式扫描可能会错过与已知形状不匹配不会扫描超过 的部分前 ）。 - 二进制图像、字体、视频、存档、PDF）被跳过 — 它们源贴。内容具有**无字节顺序标记**（例如 UTF- BOM）的非寻常编码文件可能会被视为二进制过- BOM的文件扫描。 ### 机列表（策略配置） 文档装置和基准样本令牌的假阳性口需静。AWS 公共文档访问密钥 ID（`AKIAIOSFODNN7EXAMPLE` 和AKIA`其他所有文件，请在**advantage/config.json` 中并 **提交** 它。 授权读取 **git引** blob 仅跟踪、 或未暂存的工作树编辑警告并 **无法** 授权忽略。脏跟踪/暂存的 `config.json` 是部署风险（CLI 永远生成它），因此整体 GO 需要具有预期策略的干净树```{ "version": 1, "se { ignore": { " ["sk_live_…确切的固定值…"], "hash ["6789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"], "paths": ["docs/**", "fixtures/*"], "patternIds": [" } } ``` 复制 `getadvantage check` 报告中的 **身份验证** ID（64 个 sha256进制），装置路径/模式 ID。显示（`sk_live_…abcd (32 个字符)`）仅供人类阅读，**不是** 授权标识符。完整的私钥块与 BEGIN…END 匹配（哈希/值块完整的 PEM（BEGIN 没有匹配的 END **NO**，并且无法通过值/哈希（不唯一必须通过固定装置，请使用显式 `: ["-in`。列表在密扫描中命名（`built-in:…` 或 `policy:）。之外的仍然-G。 ## 作为 MCP 服务器在调用大脑`antage mcp` 在 上依赖的 **模型上下文协议** 服务器。指向您的代理您工作的大脑、门控和地图 — `brief`、`refresh_、`andoffsave_handoff`、`check`、`map`、`architecture`、`gauge` — 而不是您手动运行 CLI。它与 CLI 使用相同的引擎：无需 API 密钥，无需网络，机器上没有任何内容离开。 ** Code** — 使用一条： ```bash claude mcp add getadvantage -- nadvcp ``` 或在您的 MCP 配置 JSON 中： ```json "mcpServers": { "getadvantage " "npx", "args": ["get", "mcp"] } } } ``` ** —块添加到 `.cursor/mcp.json`（项目）或 `cursor/m`）： ```json { "m": "get": { "command": "npx", "args": ["getadvantage", "mcp"] } } } ``` **OpenAI Codex** （CLI / VS Code 扩展 / 桌面版 — ）： ```bash codex mcp add getadvantage -- npx -y getadvantage mcp ``` 如果第一次启动超时（冷 `npx` 下载可能超过 Codex 的 10 秒握手超时），请在 `~/.codex/config.toml` 中的 `[mcpadvantage]` 块中添加 `startup_timeout_sec = 60`xAI Grok BuildCLI，测试版）： ```grok mcp add getadvantage -- npx -advantage mcp ``` Grok Build 还会读取现有的 Claude/Cursor MCP 配置文件，因此如果您在那里添加了 get，它可能已经可用。（ 的代理 — Codex 云，grok.com — 无法启动本地 stdio 服务器；请使用 CLI 界面。） 每个工具都带有可选的 `cwd`（默认为服务器运行的位置），因此您可以将其指向机器上的任何项目仓库。 ## 安全着陆舰队（扇出/扇入） 因为你的大脑居住在仓库中，所以你可以在同一个项目上**同时运行多个模型**，而且更重要的是，可以**安全地着陆它们的工作**： ```bash npx getadvantage fan-out 3 --task "添加设置页面" ``` 这会刷新大脑，然后创建三个git工作树（`../<repo>-lane-1 … -lane-3`），每个工作树都是从`HEAD`分支出的全新分支，并复制了`PROJECT-BRIEF.md`和`HANDOFF.md`文件。打开一个**不同的**模型/工具在每个通道中（ChatGPT、Claude、Gemini、Cursor、Qwen…），让它们工作，然后： ```bash npx getadvantage fan-in # 预览：冲突地图 + 合并列车干预运行 npx getadvantage fan-in --apply # 安全着陆干净的通道，带有门控 ``` `fan-in`是**安全的扇入指挥家**。它首先绘制一个**冲突地图**（哪个文件被多个通道触及），然后运行一个**合并列车**干预运行，以在合并任何内容之前找到文本冲突。使用`--apply`，它将干净的通道一个一个地合并到当前分支上，并且**在每次合并后重新运行检查门控**。两个分支可以都是绿色，但合并后变为红色；当这种情况发生时，**隔离**（回滚合并）受影响的通道，而不是污染主分支。它在一个判决屏幕上结束，告诉你哪些通道着陆，哪些需要你。 `--apply`仅从**干净的工作树**开始（因此永远不会出现半合并），并且**对自动化是安全的**：只有当所有可着陆的通道都着陆绿色时，它才会退出`0`，如果通道需要你或运行被拒绝（例如，脏树），则退出非零。因此，`fan-in --apply && deploy`永远不会在无操作上继续。`fan-out`为你提交自己的大脑刷新，因此默认是干净树启动。清理设计为保守：回滚仅撤销飞行中的合并，**已着陆的通道永远不会被恢复**，如果在列车后出现意外的工作树更改，它会停止并准确告诉你当前状态，而不是重置任何内容。如果合并带来**新的依赖项**（`package.json` / 锁定文件更改），指挥家会在门控前运行安装（带有锁定文件的`npm ci`，否则`npm install`），并将安装失败报告为确切的失败。 对于CI和工具，`check`和`fan-in`都接受 **`--json`**：标准输出携带一个JSON文档—— `{ command, verdict, exitCode, checks?/lanes?, generatedAt }` ——人类渲染被路由到标准错误： ```bash npx getadvantage check --json npx getadvantage fan-in --apply --json ``` 设计诚实：我们**检测**重叠并**门控**组合结果——我们不声称使不兼容的工作兼容。**没有冲突未经验证就到达主分支。** 一切都是git原生的：没有API密钥，没有网络，除非你使用`--report`显式选择加入（如下所示）。你带来模型；CLI持有大脑和编排基础。 在一次命令中，在一个临时仓库中查看整个过程： ```bash npx getadvantage demo ``` ## 将运行报告给getAdvantage账户（可选） **默认本地运行。** 任何命令都不会触及网络，除非你使用`--report`（或`GETADVANTAGE_REPORT=1`）显式选择加入。当你这样做时，`check`和`fan-in`会将运行结果发布到你的getAdvantage账户，这样你的仪表盘会显示运行的每个门控——在CI和你的机器上。 **发送的内容——确切地说：** 运行 **报告**，即命令打印的相同 `--json` 文档（判决、退出代码、检查结果/通道结果），加上仓库名称（`owner/name`）、分支和提交ID。**绝不发送你的源代码、差异或文件。** 没有`--report`，永远不会发送任何内容。 ```bash npx getadvantage login # 存储你的 adv_live_ 密钥（仅所有者文件在 ~/.getadvantage/） npx getadvantage check --report # 门控正常 + 发布判决 npx getadvantage fan-in --apply --report # 着陆通道 + 发布扇入结果 npx getadvantage logout # 删除存储的密钥 ``` 成功时，CLI会打印运行的报告URL：`→ 判决发布：https://…`。 - **密钥：** `GETADVANTAGE_API_KEY`（环境变量——始终优先）或由`login`存储的密钥。它仅作为`Authorization`头部发送——绝不打印、记录或写入仓库。 - **端点：** `https://getadvantage.app`；使用`GETADVANTAGE_API_URL`（暂存/自托管）覆盖。 - **尽力而为的设计：** 发布失败是一个响亮的警告，绝不是改变判决——退出代码保持门控的GO / NO-GO，因此网络中断不会使你的CI失败。传递`--report-required`如果你**希望**发布失败退出非零。 ### 在CI（GitHub Actions）中 ```bash npx getadvantage github-action # 写入.github/workflows/getadvantage.yml ``` 工作流在每次推送和拉取请求时运行`npx getadvantage check --ci --report`。`--ci`是非交互模式：它绝不会提示，容忍CI使用的分离HEAD检出，并默认基准比较为`origin/main`（或PR的`GITHUB_BASE_REF`）——`--base-ref <ref>`覆盖。添加你的密钥作为`GETADVANTAGE_API_KEY`仓库秘密；如果没有它，门控仍然运行，但报告会降级为警告。退出代码保持CI诚实：`0` = GO，非零 = NO-GO / 拒绝。 ## 它是什么——不是什么 - 它 **读取并报告** —— “这是我发现的内容，在你发布之前。” 它不声称你的应用是“安全”或“认证”的。 - 它是**无依赖**（仅限Node内置模块）和**只读**的，除了明确的`brief` / `handoff`写入（你的两个仓库驻留文件）和明确的`deploy`命令。 - 它**默认本地运行** —— 除非你明确传递`--report`（或设置`GETADVANTAGE_REPORT=1`），否则没有任何内容离开你的机器。报告仅发送运行报告—— `--json`文档（判决、退出代码、检查结果/通道结果）加上仓库名称、分支和提交ID——到你的getAdvantage账户。**绝不**发送你的源代码、差异或文件。 它还附带自己的证明：`npm test`运行一个集成套件（包括一个自我测试，它在临时fixture仓库中植入漏洞——一个提交的`.env`，一个带有尾部密钥的超大文件，文档/CSS假阳性诱饵——并断言门控捕获每个真实漏洞，同时对其他漏洞保持沉默）。 ### 0.6.0：秘密扫描强化 - **已提交的`.env`文件不再被秘密扫描跳过。** 早期版本跳过`.env*`基名，认为它们被gitignore了。但是，gitignore文件永远不会到达扫描器，因此跳过只会抑制危险情况。已修复，并新增了**跟踪的`.env`检查**，直接阻止提交的`.env`（如果本地`.env`尚未被gitignore，则发出警告）。 - **超大文件（> 2 MB）不再被静默跳过。** 扫描前256 KB和后256 KB，并披露应用于哪些文件的部分扫描结果。 - **新增模式：**Anthropic密钥（在更广泛的OpenAI形状之前检查，以便`sk-ant-…`不会被误标为），npm访问令牌，裸JWT（头部验证以避免假阳性），以及带有嵌入式密码的数据库URL（占位符密码和本地开发主机将被忽略）。 - **每个文件都会统计所有出现次数**，而不仅仅是第一次匹配。 需要 **Node ≥ 18**。由 [getAdvantage](https://getadvantage.app) 构建。