内容
# 企业 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)
跨平台命令行工具，准备开发者工作站和仓库，以实现**在企业代理后面安全、可控的 AI 辅助编码**。它提取企业信任，调整本地推理，强化仓库防护，连接 MCP / 可观察性 / 沙盒，并建立工具无关的上下文架构 — 所有这些都通过一个命令界面。
> 将架构蓝图 *"企业 DevSecOps AI 启动：加密信任、本地性能优化和统一可观察性"* 变为现实的、经过测试的产品。
## 设计立场
- **默认干预运行.** `aih <cmd>` 计算并打印计划；除非添加 `--apply`，否则不会写入任何内容。添加 `--verify` 运行只读检查。
- **从不修改远程系统.** 每个工作单元都是本地写入、本地执行（icacls/chmod/junction…）、只读探测或文档（云设置的 exact 命令 — SSO、网关、Langfuse、MDM — 为人类发出，从不执行）。没有提供云基础设施的代码路径，因此自动化运行不能“伪造”。
- **幂等且非破坏性.** Shell 配置文件编辑生活在标记的托管块中；JSON 配置文件深度合并（您的密钥生存）；每个覆盖都备份到 `*.aih.bak` 并在失败时回滚为事务。
- **跨平台.** Windows 和 Linux 在真实硬件上经过验证（Windows：PowerShell/icacls/junctions；Linux：真实 `/proc`、`/etc/ssl/certs`、`chmod`、`ln -sfn`，在 Hyper-V Ubuntu VM 中经过烟雾测试）。macOS 已实施并经过固定测试。所有 OS 调用都通过可注入的运行器。
## 安装
```bash
npm install # 依赖项
npm run build # → dist/cli.js (bin: aih)
node dist/cli.js --help
```
## 命令界面
| 命令 | 功能 |
| --- | --- |
| `aih certs` | 从 OS 信任存储中提取企业根 CA，锁定并传播信任到 npm/pip/cargo/conda。 |
| `aih hardware` | 配置 CPU/RAM/GPU；计算内存/线程/并行限制 + 量化；发出调整后的 Ollama/llama.cpp 设置。 |
| `aih vdi` | 检测 VDI（Citrix/WorkSpaces/RES/RDP）并将缓存 + SQLite 重定向到本地临时目录（Windows 上为连接）。 |
| `aih profile` | 递归检测仓库的堆栈并综合 Cursor 堆栈规则（`.cursor/rules/*.mdc`）。根加载程序由 `bootstrap-ai` 所有。 |
| `aih ecc` | 为选定的 CLI 安装 [affaan-m/ECC](https://github.com/affaan-m/ECC)（技能、直觉、内存、安全、研究优先）作用于检测到的堆栈：Claude 插件路径、`ecc-install` 用于 codex/cursor/zed/opencode，`consult` 顾问否则。 |
| `aih superpowers` | 为选定的 CLI 安装 [obra/Superpowers](https://github.com/obra/Superpowers)（头脑风暴 → 计划 → TDD → 子代理审查技能）用于选定的 CLI。 |
| `aih scaffold` | 创建规范的上下文目录（ `--context-dir`，默认为 `ai-coding`）— INDEX/SKILL 骨架，一个代理 **`SETUP-TASKS.md`** 攻略（填充上下文 + 防护栏从代码），一个一次性 `project-guardrails.md`，一个秘密拒绝列表，以及一个预提交钩子。（加载程序是 `bootstrap-ai` 的工作。） |
| `aih guardrails` | 生成 `.gitleaks.toml`、`.pre-commit-config.yaml` 和一个阻止 AGPL/强 copyleft 的 CI 许可证门。 |
| `aih secrets` | 扫描纯文本 `.env*`/`secrets/` 并编写代理拒绝规则 + 保密注射指南。 |
| `aih mcp` | 生成 `.mcp.json`（本地/项目/远程范围）；对于锁定组织， `--mode offline`（本地命令服务器的预置）或 `--mode none`（无 MCP + CLI 工具回退）以及一个 `managed-mcp.json` 管理模板。 |
| `aih sandbox` | 生成一个 devcontainer + 管理的沙盒设置（出口允许列表，`failIfUnavailable`）。 |
| `aih telemetry` | 注入 OpenTelemetry 环境，一个遮蔽 Bindplane 收集器和一个分析器提取器（用法 + 技能端点 → `{ usage_report, skills }`）。 |
| `aih report` | 只读分析摘要。本地：一个开发控制台 — 代理 **上下文足迹**（令牌膨胀），**仓库和分支状态**（当前分支，领先/落后 vs main，脏； `--team` 添加进行中的团队分支通过 `gh` → `git ls-remote` → 最后获取的梯度，当 gh/network 被阻塞时优雅降级），仓库配置存在，本地 AI-CLI 工具饱和度和 **趋势**（提交/LOC/采用/分支的历史记录 — 参见 `aih track`）。组织（ `--org <export.json>`）：顶级技能，按类型划分的令牌，**缓存节省**（净写入估计）和从保存的 Admin-API 导出接受/拒绝。 正文按原样打印； `--json` 携带结构化数据； `--format md\|html` 在 `--apply` 下写入静态工件。 **`--open`** 构建自包含的 HTML 仪表盘（采用环，KPI 条，趋势图）并在浏览器中启动（意味着 html + apply）； **`--refresh <sec>`** 使其保持活动 — 打开一次，然后每 `<sec>` 秒重新生成，同时页面自动重新加载（Ctrl+C 停止）。默认黑暗主题，具有浅色切换；Inter + JetBrains Mono 嵌入式，因此它完全离线工作。默认网络免费； `--team` 是唯一的网络调用。 |
| `aih track` | 记录一个指标样本（提交 7d，LOC 增量，采用率，分支计数，跟踪文件）到 `.aih/history.jsonl` — `aih report` 趋势背后的时间序列。只读 git/文件系统；干预运行预览， `--apply` 追加（每个提交幂等）。将历史记录累积到提交/代理停止钩子中 — Kiro `metrics-on-stop` 钩子（ `aih bootstrap-ai --cli kiro` ）自动运行 `aih track --apply`。 |
| `aih usage` | 安装 **多工具用法捕获** 层 → `.aih/usage.jsonl`（由 `aih report` 用途面板渲染）。 **通用底线** 是一个 git `post-commit` 钩子，记录 **任何** 工具的提交活动（它从提交中获取，而不是代理）。每个工具的 **技能/MCP** 层通过每个 CLI 的验证本地钩子连接（Claude/Codex/Cursor/Gemini/Kiro/… — `aih usage` 记录确切的机制）；技能按来源聚合（ECC/规范/用户）。行为捕获几乎是普遍的（9/11 CLI 有本地钩子）；只有 **美元成本** 是不均匀的（Claude 的实时美元，令牌计数来自 Codex/Gemini/Kimi/OpenCode，Cursor/Windsurf 仅限云）。 |
| `aih crispy` | 运行 CRISPY 上下文工程阶段机器（确定，门控顺序）。 |
| `aih bootstrap` | 协调工作站 4 阶段推出（证书 → 硬件/VDI → 可观察性）。 |
| `aih bootstrap-ai` | 发出并验证仓库的第 2 层 `ai-coding/` 规范： `RULE_ROUTER.md`，每个 CLI 的适配器和根加载程序（工具前奏 + 再生共享块）。 `--verify` 是漂移门。 |
| `aih init` | 初始化仓库：配置文件 + superpowers + bootstrap-ai + scaffold + secrets + guardrails + mcp + sandbox 一次通过（每个文件一个写入器）。ECC 是一个单独的 gated 网络步骤 — 运行 `aih ecc` 时准备就绪（它指向 ECC 自己的安装程序）。 |
| `aih workspace` | 脚手架一个 **多仓库** 工作空间（仅限父目录）：跨仓库架构图（写入一次）+ 每个仓库的纪律，一个 VS Code `.code-workspace`，一个跨越每个子仓库路径的文件系统 MCP，以及一个 `.aih-workspace.json` 标记。 |
| `aih doctor` | 工作站/仓库配置的故障封闭验证（ + 工作空间模式：验证每个子仓库）。 |
| `aih status` | 已配置的组件的只读清单。 |
全局标志： `--apply`， `--verify`， `--json`， `--context-dir <dir>`， `--root <dir>`， `--cli <list>`， `--all-tools`。
设置也会从 `AIH_*` 环境变量中读取（ `AIH_APPLY`， `AIH_CONTEXT_DIR`， …）。
### 目标 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`.
```bash
aih ecc --cli claude,codex # ECC 用于 Claude（插件）+ Codex（ecc-install）
aih superpowers --cli antigravity # agy 插件安装 … （在 --apply 下运行）
aih bootstrap-ai --cli kiro # 编写 .kiro/steering/00-canon.md（包含：始终）
aih bootstrap-ai --detect # 仅针对此处安装的 CLI
aih init . --all-tools # 为每个 CLI 启动一个仓库
```
每个 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 尚未定位的工具，
`<context-dir>/adapters/other-tools.md` 记录了如何将其指向 `RULE_ROUTER.md`.
**Kiro 深度.** 由于 Kiro 无法读取 `~/.claude`，选择 `kiro` 还会生成 Kiro 原生内容（架构经 [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 的真实钩子架构中。
- `aih ecc --cli kiro` → 在找到本地 ECC 检出时运行 ECC 的 **原生** `.kiro/install.sh` （复制 ECC 的代理/技能/
导航/钩子到 `.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` 并显示检测到的列表并询问您确认或编辑它
（按 Enter 接受，或输入逗号分隔的列表以添加/删除
工具）然后再安装 — 传递 `--yes` （或非交互式运行/管道/ `--json` ）以跳过
提示并直接使用检测到的列表。 `aih doctor` 报告它检测到的 CLI， 而
`aih bootstrap-ai --verify` 添加每个 CLI 的 **"installed"** 确认步骤（通过 = 找到，跳过 = 还没有
在这里，但是仍然写入启动器）与漂移门一起。
**规范目录名称.** 每个生成的文件和引用都采用 `--context-dir <name>` — 使用您喜欢的任何
名称；默认为可见的 `ai-coding/`:
```bash
aih init # → ai-coding/ （默认，可见）
aih init --context-dir my-canon # → my-canon/ （任意名称；所有内容都适应）
aih init --context-dir .ai-context # → 隐藏，旧默认
```
可运行的安装程序（ `ecc-install` ， `agy` / `copilot 插件安装程序` ）在 `--apply` 下执行；
工具内的斜杠命令安装（Claude/Codex/Kimi 插件）作为确切的命令在
工具内运行。 ECC 和 Superpowers 是互补的 — ECC 提供堆栈感知的规则、代理和内存；
Superpowers 提供使用它们的学科代理循环。
### 分层 AI 规范（ `bootstrap-ai` ）
该工具包使用参考仓库中使用的相同两层设置（eicp / ai-os / syntegris）：
- **第 1 层 — 用户基线：** ECC + Superpowers，由 `aih ecc` / `aih superpowers` 按 CLI 安装。
- **第 2 层 — 仓库规范：** 提交的 `ai-coding/` （或 `--context-dir` ）树 — `RULE_ROUTER.md`
（堆栈感知的路由入口）， `adapters/<cli>.md` （每个工具的线路说明）， `REGENERATION.md`，
和根 **加载程序** （ `CLAUDE.md` ， `AGENTS.md` ， `GEMINI.md` ，Cursor/Windsurf/Copilot）。
`aih bootstrap-ai` 生成并验证第 2 层。每个加载程序都是可编辑的工具特定内容
**加上一个标记分隔的共享块** ， `bootstrap-ai` 幂等再生 —
您的编辑在标记之外存活（合并，带有 `.aih.bak` 备份）。 `aih bootstrap-ai --verify`
是 **漂移门** ：如果路由器丢失或加载程序的块已被手动编辑
移出规范源，则失败 — 将其连接到 CI 以保持每个工具的入口点同步。
```bash
aih bootstrap-ai --all-tools --apply # 铺设 RULE_ROUTER + 适配器 + 加载程序，用于所有 CLI
aih bootstrap-ai --verify # CI 漂移门（无写入；退出 1 漂移）
```
优先级： **第 2 层获胜** 冲突时 — 仓库规范覆盖通用基线。 运行
`aih scaffold` 获取路由器指向的上下文目录（ `INDEX/architecture/conventions` ）。
### 多仓库工作空间
大多数组织将产品分散到 **单独的仓库** （一个 git 组织中的 UI 仓库和后端仓库）。一个
编辑 UI 的代理无法查看后端 — 没有跨仓库的辐射范围。 `aih workspace`
从 **父文件夹** 桥接该间隙：
```bash
aih workspace ./my-org --apply # 自动检测子仓库（*/.git）；或 --repos ui,backend
```
它在父目录下编写（它 **不** 触摸子仓库 — 在每个仓库中运行 `aih init` ）：
- `<context-dir>/cross-repo-architecture.md` — 每个仓库的职责 + **跨仓库功能映射**
（UI 列 · 后端列 · 合同）。 **写入一次** — aih 从您的仓库列表中提供种子，然后
您拥有它；重新运行时永远不会覆盖它。
- `<context-dir>/repo-discipline.md` — 加载仓库的规范后再编辑它。
- `CLAUDE.md` + `AGENTS.md` — 薄的工作空间加载程序指向跨仓库规范。
- `<name>.code-workspace` — 打开所有仓库到一个 VS Code 窗口。
- `.mcp.json` — 一个 **跨越每个子仓库路径的 filesystem MCP** ，所以代理在工作空间根目录
可以跨仓库读取。
- `.aih-workspace.json` — 标记，将 `aih doctor` 置于 **工作空间模式** （验证每个
仓库已搭建）。
### 示例
```bash
aih doctor --json # 配置了什么？（只读）
aih init . --apply # 引导当前仓库
aih certs --ca-pattern Zscaler --apply --verify
aih hardware # 预览调优的推理环境块
AIH_CONTEXT_DIR=ai-coding aih scaffold --apply
```bash
## 开发
```bash
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).
