samartomar/ai-harness

# aih — 企业级 AI 引导工具 [](https://github.com/samartomar/ai-harness/actions/workflows/ci.yml) [](https://github.com/samartomar/ai-harness/actions/workflows/codeql.yml) [](https://scorecard.dev/viewer/?uri=github.com/samartomar/ai-harness) [](LICENSE) [](package.json)

一个跨平台的 CLI，用于为开发者工作站和代码仓库做准备，以实现 **在企业代理后进行安全、受控的 AI 辅助编码**。它能够提取 企业级信任机制、调优本地推理、利用护栏加固代码仓库、连接 MCP / 可观测性 / 沙盒机制，并建立一套与工具无关的上下文 架构 —— 所有这些都通过一个统一的命令界面完成。 ## 设计理念 - **默认 Dry-run。** `aih ` 计算并打印执行计划；在你添加 `--apply` 之前不会 写入任何内容。添加 `--verify` 可运行只读检查。 - **绝不修改远程系统。** 每个工作单元都是一个本地 `write`（写入）、 本地 `exec`（执行，如 icacls/chmod/junction…）、只读的 `probe`（探测），或 `doc`（文档， 即用于云端设置的精确命令 —— SSO、网关、Langfuse、MDM —— 仅为人类生成，绝不自动执行）。 没有任何配置云端基础设施的代码路径，因此自动化运行无法“伪造”它。 - **幂等且非破坏性。** Shell 配置文件的修改位于带有标记的托管 块中；JSON 配置会进行深度合并（你的密钥会保留）；每次覆盖都会 备份到 `*.aih.bak`，并在失败时作为事务进行回滚。 - **跨平台。** Windows 和 Linux 均已在真实的物理机上验证（Windows： PowerShell/icacls/junctions；Linux：真实的 `/proc`、`/etc/ssl/certs`、`chmod`、 `ln -sfn`，并在 Hyper-V Ubuntu 虚拟机中进行了冒烟测试）。macOS 已实现并进行了 固定装置测试。所有操作系统的调用都通过一个可注入的运行器进行。 ## 安装说明 ``` npm install # deps npm run build # → dist/cli.js (bin: aih) node dist/cli.js --help ``` ## 命令概览 | 命令 | 功能说明 | | --- | --- | | `aih certs` | 从操作系统信任库中提取企业根 CA，对其进行锁定，并将信任传播到 npm/pip/cargo/conda。 | | `aih heal` | 诊断**并修复** `certs` 假定可以正常工作的受损运行时 —— 企业 TLS 信任、npm、PATH 和 MCP 预检 —— 适用于任何 TLS 拦截代理（`--ca-pattern`/`AIH_CA_PATTERN`，绝不硬编码）。默认进行诊断（损坏时以非零状态退出），并在 `--apply` 下进行修复；npm 自愈脚本作为操作员运行的脚本（绝不自动执行），唯一的更改是本地 Windows 注册表写入，以持久化保存由 GUI 启动的应用（Kiro/Claude）的 CA，因此该工具绝不会联系远程。`--scope certs,npm,path,mcp,all`。 | | `aih hardware` | 分析 CPU/RAM/GPU；计算内存/线程/并行限制及量化；生成调优后的 Ollama/llama.cpp 配置。 | | `aih vdi` | 检测 VDI（Citrix/WorkSpaces/RES/RDP），并将缓存和 SQLite 重定向到本地暂存区（在 Windows 上使用 junction）。 | | `aih profile` | 递归检测代码仓库的技术栈，并生成 Cursor 技术栈规则（`.cursor/rules/*.mdc`）。根引导程序由 `bootstrap-ai` 负责。 | | `aih ecc` | 为选定的 CLI 安装 [affaan-m/ECC](https://github.com/affaan-m/ECC)（技能、直觉、记忆、安全性、研究优先），范围限制在检测到的技术栈：Claude 插件路径，为 codex/cursor/zed/opencode 执行 `ecc-install`，其他情况下使用 `consult` 顾问。 | | `aih superpowers` | 为选定的 CLI 安装 [obra/Superpowers](https://github.com/obra/Superpowers)（头脑风暴 → 计划 → TDD → 子代理审查技能）。 | | `aih scaffold` | 创建标准上下文目录（`--context-dir`，默认为 `ai-coding`） —— INDEX/SKILL 骨架、一个代理 **`SETUP-TASKS.md`** 操作手册（从代码中填充上下文 + 护栏）、一次性的 `project-guardrails.md`、机密拒绝列表，以及一个 pre-commit hook。（引导程序由 `bootstrap-ai` 负责。） | | `aih guardrails` | 生成 `.gitleaks.toml`、`.pre-commit-config.yaml`，以及一个用于拦截 AGPL/强传染性开源协议的 CI 许可证检查关卡。 | | `aih secrets` | 扫描明文 `.env*`/`secrets/` 并编写代理拒绝规则及保险库注入指南。`--verify` 是**机密扫描 CI 关卡**（存在明文机密时以状态码 1 退出）；`--sarif ` 会为 GitHub 代码扫描功能针对每个路径生成一个错误级别的结果。 | | `aih mcp` | **针对目标 CLI**（`--cli`/`--all-tools`，默认为 claude）生成 MCP server 配置：Claude/Cursor/Kiro/Kimi 会写入其正确的项目文件（`.mcp.json`, `.cursor/mcp.json`, …）；Codex (TOML)、Copilot、OpenCode、Zed 以及全局配置工具会得到精确的逐工具指南，而不是 aih 可能会写错的文件。作用域：本地/项目/远程。对于严格受限的组织，提供 `--mode offline`（本地供应商命令服务器）或 `--mode none`（无 MCP + CLI 工具回退），以及一个 `managed-mcp.json` 管理员模板。 | | `aih sandbox` | 生成 devcontainer + 受管理的沙盒设置（出站请求白名单，`failIfUnavailable`）。 | | `aih telemetry` | 注入 OpenTelemetry 环境变量、一个脱敏的 Bindplane 收集器，以及一个分析抓取器（使用情况 + 技能端点 → `{ usage_report, skills }`）。 | | `aih report` | 只读的分析摘要。本地：一个开发者控制台 —— 代理的**上下文占用**（token 冗余）以及一个**每轮负载组**面板（总是被加载的最重的单个工具的引导程序 —— 即单个工具每轮实际付出的代价，而不是总和；`--gate --token-budget ` 在超出限制时于 CI 中以非零状态退出）。该占用计算**遵循 gitignore**（仅统计已追踪/未追踪且未被忽略的源文件，绝不包括每个 CLI 生成的副本 —— 使用 `--all-files` 可覆盖此行为；`--since ` 可缩小范围至 PR 中更改的文件）、**仓库与分支状态**（当前分支，与 main 分支相比的超前/落后情况，脏状态；`--team` 通过 `gh` → `git ls-remote` → 最后抓取的层级结构，添加正在进行的团队分支信息，并在 gh/网络受阻时优雅降级）、仓库配置存在情况、本地 AI-CLI 工具饱和度，以及**趋势**（记录历史中提交/代码行数/采用率/分支的 unicode 微线图 —— 参见 `aih track`）。组织（`--org `）：热门技能、按类型划分的 token、**缓存节省**（扣除写入的净值估算），以及来自已保存 Admin-API 导出的接受/拒绝率。正文原样打印；`--json` 包含结构化数据；`--format md\|html` 在 `--apply` 下写入静态产物。**`--open`** 构建自包含的 HTML 仪表板（采用率环、KPI 指示条、趋势图表）并在浏览器中启动（隐含 html + apply）；**`--refresh `** 保持其动态更新 —— 打开一次，然后每隔 `` 秒重新生成，同时页面自动重新加载（按 Ctrl+C 停止）。默认为暗色主题并带有亮色切换；内嵌了 Inter + JetBrains Mono 字体，因此可完全离线工作。默认无网络操作；`--team` 是唯一一个可选的联网调用。 | | `aih track` | 将一个指标样本（7天提交数、代码行数差异、采用率得分、分支数、追踪的文件数）记录到 `.aih/history.jsonl` —— 即 `aih report` 趋势背后的时间序列。只读 git/文件系统；dry-run 预览，`--apply` 追加（按提交幂等）。将其接入提交 / 代理停止 hook，以便不断累积历史 —— Kiro 的 `metrics-on-stop` hook（`aih bootstrap-ai --cli kiro`）会自动运行 `aih track --apply`。 | | `aih usage` | 安装**多工具使用情况捕获**层 → `.aih/usage.jsonl`（由 `aih report` 的 Usage 面板渲染）。**通用基础层**是一个 git 的 `post-commit` hook，它记录**任何**工具的提交活动（它以提交而非代理作为判断依据）。针对特定工具的 **skill/MCP** 层通过每个 CLI 已验证的本地 hook 接入（Claude/Codex/Cursor/Gemini/Kiro/… —— `aih usage` 记录了确切的机制）；技能按来源聚合（ECC/canon/用户）。行为捕获几乎是通用的（11 个 CLI 中有 9 个具备本地 hook）；只有**资金成本**是不均衡的（Claude 提供真实的 USD，Codex/Gemini/Kimi/OpenCode 提供 token 计数，Cursor/Windsurf 仅限云端）。 | | `aih crispy` | 运行 CRISPY 上下文工程阶段机（确定性，按关卡排序）。 | | `aih bootstrap` | 统筹工作站 4 阶段部署（证书 → 硬件/vdi → 遥测）。 | | `aih bootstrap-ai` | 生成并验证代码仓库的 Layer-2 `ai-coding/` 规范：`RULE_ROUTER.md`、每个 CLI 的适配器以及根引导程序（工具前言 + 重新生成的共享块）。`--verify` 是漂移关卡**，同时也是对生成的规范进行弱模型安全检查** —— 每个 `#[[file:…]]`/反引号引用都必须能被解析，且不得遗留任何 ``/`TODO` 脚手架（悬空引用会导致关卡失败；软命令/品味词相关的散文仅作为参考建议）。 | | `aih init` | 初始化代码仓库：一次性完成 profile + superpowers + bootstrap-ai + scaffold + secrets + guardrails + mcp + sandbox（每个文件仅执行一次写入）。ECC 是一个单独的受控网络步骤 —— 准备好后运行 `aih ecc`（它指向 ECC 自己的安装程序）。 | | `aih workspace` | 搭建一个**多仓库**工作区（仅限父级）：跨仓库架构映射（一次性写入）+ 每个仓库的纪律规范、一个 VS Code 的 `.code-workspace`、跨越每个子仓库的组合 graph/filesystem MCP，以及一个 `.aih-workspace.json` 标记文件。 | | `aih doctor` | 对工作站/代码仓库配置进行故障安全（fail-closed）验证（+ 工作区模式：验证每个子仓库）。包含对脚手架生成的 `ai-coding/` 树的（只读）**规范 Markdown 检查**。 | | `aih status` | 该套件已配置内容的只读清单。 | 全局标志：`--apply`、`--verify`、`--json`、`--context-dir `、`--root `、`--cli `、`--all-tools`。 设置也可以从 `AIH_*` 环境变量中读取（`AIH_APPLY`、`AIH_CONTEXT_DIR`，…）。 ### 仪表板 `aih report --open` 构建一个**自包含、离线**的 HTML 仪表板（默认为暗色，带亮色切换；内嵌字体） —— 上下文占用 + KPI 指示条、采用率环、输出速度和代码质量面板，以及来自记录历史（`aih track`）的趋势微线图。添加 `--demo` 可使用展示数据，或使用 `--refresh ` 保持其实时更新。  ### 目标 CLI `aih ecc`、`aih superpowers` 和 `aih bootstrap-ai` 仅会触及你实际使用的代理 CLI。 传入带有逗号分隔列表的 `--cli`，传入 `--all-tools` 包含每一个支持的 CLI，或者传入 `--detect` 以自动定位此机器上找到的 CLI；默认是 `claude`。支持范围： `claude, codex, cursor, antigravity, gemini, copilot, windsurf, opencode, zed, kimi, kiro`。 ``` aih ecc --cli claude,codex # ECC for Claude (plugin) + Codex (ecc-install) aih superpowers --cli antigravity # agy plugin install … (runs under --apply) aih bootstrap-ai --cli kiro # writes .kiro/steering/00-canon.md (inclusion: always) aih bootstrap-ai --detect # target only the CLIs installed here aih init . --all-tools # bootstrap a repo for every CLI at once ``` 每个 CLI 都会获得其原生的入口文件：Claude → `CLAUDE.md`，Codex/OpenCode/Zed/Kimi/Antigravity → `AGENTS.md`，Gemini → `GEMINI.md`，Cursor → `.cursor/rules/*.mdc`，Windsurf → `.windsurfrules`， Copilot → `.github/copilot-instructions.md`，**Kiro → `.kiro/steering/00-canon.md`**（`inclusion: always`，带有 `#[[file:…/RULE_ROUTER.md]]` 实时引用）。对于 aih 尚未适配的工具， `/adapters/other-tools.md` 文档说明了如何将其指向 `RULE_ROUTER.md`。 **Kiro 深度支持。** 由于 Kiro 无法读取 `~/.claude`，选择 `kiro` 还会生成 Kiro 原生 内容（schema 已根据 [Kiro 的文档](https://kiro.dev/docs/steering/) 和 ECC 的真实 `.kiro/` 树进行了验证）： - `aih bootstrap-ai --cli kiro` → `.kiro/steering/agent-tools.md`（感知技术栈的 CLI 用法）+ 感知技术栈的 `.kiro/hooks/*.kiro.hook` 文件（`aih-secret-scan-on-create`、`aih-tests-on-edit`、 `aih-quality-gate` 运行仓库真实的 lint/test），符合 Kiro 真实的 hook schema。 - `aih ecc --cli kiro` → 当找到本地 ECC 检出（`--ecc-path `，或 `~/.claude/ecc`、`~/ECC`）时，运行 ECC **原生**的 `.kiro/install.sh`（将 ECC 的 agents/skills/ steering/hooks 复制到 `.kiro/`）；否则记录相应的 `git clone` + 安装操作。 - `aih superpowers --cli kiro` → `.kiro/steering/superpowers-methodology.md` （头脑风暴 → 计划 → TDD → 审查路由，因为 Kiro 无法加载 `~/.claude/superpowers`）。 **检测**（`--detect`）会寻找每个工具的配置目录（`~/.claude`、`~/.codex`、`~/.gemini`、 `~/.cursor`、`~/.kiro`，…）或其在 PATH 上的二进制文件（通过 Runner 接缝实现 —— 测试中没有真实进程）。 优先级：`--all-tools` > `--cli` > `--detect` > 默认 `claude`。当 `--detect` 未发现任何内容时， 它会默认使用 `claude` 并说明情况。**在交互式终端中，`--detect` 会显示检测到的列表，并 要求你确认或编辑它**（按 Enter 接受，或输入逗号分隔的列表来添加/移除 工具），然后才会进行任何安装 —— 传入 `--yes`（或在非交互式/管道/`--json` 模式下运行）以跳过 提示并直接使用检测到的列表。`aih doctor` 会报告它检测到的 CLI，并且 `aih bootstrap-ai --verify` 会在漂移关卡旁添加一个针对每个 CLI 的 **“installed”** 确认步骤（通过 = 已找到，跳过 = 尚不存在， 但仍会写入引导程序）。 **规范目录名称。** 每个生成的文件和引用都会采用 `--context-dir ` —— 使用你喜欢的任何 名称；默认是可见的 `ai-coding/`： ``` aih init # → ai-coding/ (default, visible) aih init --context-dir my-canon # → my-canon/ (any name; everything adapts) aih init --context-dir .ai-context # → hidden, the old default ``` Shell 可执行的安装（`ecc-install`、`agy`/`copilot plugin install`）在 `--apply` 下运行； 工具内的斜杠命令安装（Claude/Codex/Kimi 插件）会作为要在 工具内运行的准确命令输出。ECC 和 Superpowers 是互补的 —— ECC 提供感知技术栈的规则、代理 和记忆；Superpowers 提供使用它们的有纪律的代理循环。 ### 分层 AI 规范 (`bootstrap-ai`) 该套件采用了与参考代码仓库（eicp / ai-os / syntegris）中相同的双层设置模型： - **Layer 1 — 用户基线：** ECC + Superpowers，由 `aih ecc` / `aih superpowers` 按每个 CLI 进行安装。 - **Layer 2 — 代码仓库规范：** 提交的 `ai-coding/`（或 `--context-dir`）树 —— `RULE_ROUTER.md` （感知技术栈的路由入口点）、`adapters/.md`（逐工具接线说明）、`REGENERATION.md`， 以及根 **引导程序**（`CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、Cursor/Windsurf/Copilot）。 `aih bootstrap-ai` 生成并验证 Layer 2。每个引导程序都是可手动编辑的特定工具 内容，**外加一个由 `bootstrap-ai` 幂等重新生成的带标记的共享块** —— 你在标记之外所做的修改将被保留（会被合并进来，并生成一个 `.aih.bak` 备份）。`aih bootstrap-ai --verify` 是**漂移关卡**：如果路由器丢失或引导程序的块被手动编辑偏离了 规范的源代码，它就会失败 —— 将其接入 CI 可以让每个工具的入口点保持同步。 ``` aih bootstrap-ai --all-tools --apply # lay down RULE_ROUTER + adapters + bootloaders for every CLI aih bootstrap-ai --verify # CI drift gate (no writes; exit 1 on drift) ``` 优先级：**Layer 2 优先级最高** —— 代码仓库规范覆盖通用基线。运行 `aih scaffold` 以获取路由器指向的上下文目录（`INDEX/architecture/conventions`）。 ### 多仓库工作区 大多数组织将产品拆分到**独立的代码仓库**中（一个 git 组织中的一个 UI 代码仓库和一个后端代码仓库）。此时， 编辑 UI 的代理就无法看到后端的情况 —— 没有跨仓库的影响范围意识。`aih workspace` 从容纳这些代码仓库的**父文件夹**中弥补了这一差距： ``` aih workspace ./my-org --apply # auto-detects child repos (*/.git); or --repos ui,backend ``` 它在父级写入（它**不会**触及子代码仓库 —— 请在每个子仓库中运行 `aih init`）： - `/cross-repo-architecture.md` —— 每个代码仓库的职责 + 一个**跨仓库功能映射** （UI 列 · 后端列 · 契约）。**一次性写入** —— aih 根据你的代码仓库列表为其播种，然后 由你负责；重新运行绝不会覆盖它。 - `/repo-discipline.md` —— 在编辑代码仓库之前先加载其自身的规范。 - `CLAUDE.md` + `AGENTS.md` —— 指向跨仓库规范的轻量级工作区引导程序。 - `.code-workspace` —— 在一个 VS Code 窗口中打开所有代码仓库。 - `.mcp.json` —— 组合的**代码审查 graph + filesystem MCP**，跨越每个子代码仓库路径，因此位于 工作区根目录的代理可以在编辑子代码仓库之前分析跨仓库的影响范围。 - `.aih-workspace.json` —— 一个标记文件，使 `aih doctor` 进入**工作区模式**（验证每个子 代码仓库是否已构建好脚手架）。 ### 示例 ``` aih doctor --json # what's configured? (read-only) aih init . --apply # bootstrap the current repo aih certs --ca-pattern Zscaler --apply --verify aih hardware # preview the tuned inference env block AIH_CONTEXT_DIR=ai-coding aih scaffold --apply ``` ## 开发说明 ``` npm test # vitest npm run typecheck # tsc --noEmit npm run lint # biome npm run build # tsup → dist/ ``` 技术栈：TypeScript (ESM) · commander · zod · vitest · biome · tsup。有关架构、 贡献者/代理工作流以及可委派的任务，请参阅 [`.github/AGENT_TASKS.md`](.github/AGENT_TASKS.md)。 ## 许可证 [Apache-2.0](LICENSE)。

标签：AI代码辅助, GNU通用公共许可证, MITM代理, Node.js, 企业级AI治理, 开发辅助工具, 暗色界面, 用户代理, 自动化攻击, 自动化配置