内容
# 🧰 Agentic 工具包
[](https://github.com/pacphi/agentic-kit/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@pacphi/agentic-kit)
[](https://nodejs.org)
[](LICENSE)
**一个 npm 包，让 [ruflo](https://github.com/ruvnet/ruflo) 和 [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe) 真正起作用 — 已安装、修复并在 macOS、Linux 和 Windows 上经过验证。**
```bash
npm install -g @pacphi/agentic-kit@next # alpha 通道，直到 4.0.0 GA
ak setup # 每个机器一次；在一个 git 仓库中运行以设置该项目
```
您只需手动安装此包 — **您不需要自己安装 ruflo 或 agentic-qe。** `ak setup` 为您全局安装它们（构建 natives 以通过 npm ≥11.17 的 `allow-scripts` 门槛），然后修复和验证它们。
## 为什么存在这个包
ruflo 承诺提供持久内存、自我学习、安全扫描和 Claude Code 的后台工作线程。在实践中，股票安装会悄悄地陷入损坏状态：本地 SQLite 绑定被 npm 升级删除（内存写入消失，同时打印“OK”），CLI 仍导入的包停止发货（[#2670](https://github.com/ruvnet/ruflo/issues/2670) 留下了提示注入防御，静默失效），模式存储在写入中断时损坏，状态行在未通知您实际内容的情况下重新生成，而后台守护进程曾用于无监督地燃烧令牌。上游修复不断落地 — 这个工具包的工作是 *差距*：检测漂移，收敛到健康状态，并 **验证** 而不是假设。
每个守卫背后的完整调查历史（附带已提交的上游问题）存放在 [docs/archive/](docs/archive/) 中。
## 四个命令
```text
ak 状态 + 一个建议的下一步行动
ak setup 首次设置 — 机器和/或您所在的项目 [--project] [--minimal] [--yes] [--no-aqe] [--no-security] [--reconfigure]
ak status 只读仪表盘：什么正确，什么漂移 [--json] [--deep]
ak sync 收敛到良好状态：升级 + 修复 + 验证 [--dry-run] [--no-upgrade]
ak uninstall 清洁退出 [--dry-run] [--purge]
```
（`ak` 是日常驱动程序的别名；完整的 `agentic-kit` 命令是相同的。如果您还使用 AutoKitteh：其 CLI 也命名为 `ak` — 完整的命令始终有效。）
**当有疑问时：`ak sync`.** 每个变异命令都采用 `--dry-run` 并打印其计划和原因 — 您在任何更改发生之前都会看到影响。
动词的作用：
| 动词 | 它做了什么 |
| ------ | -------------- |
| **setup** | 全局安装/更新 ruflo + agentic-qe（处理 npm ≥11.17 的 `allow-scripts` 以构建原生），部署令牌审计技能，将托管的指导块合并到 `~/.claude/CLAUDE.md`，提供一次 MCP 注册（用户范围，具有工具系列选择器），并在仓库内初始化项目：清理的 `ruflo init`，绝对内存路径固定，一个 **验证** 的存储→磁盘写入，状态行页脚和具有 **本地唯一（$0）工作线程** 的后台守护进程（令牌消费 AI 工作线程在上游的机器范围预算后保持可选）。项目范围在当前文件夹中的 `.git` 目录上触发；如果没有，则跳过并附上注释。 `--project` 强制执行（例如，一个尚未 `git init` 的文件夹）， `--minimal` 跳过， `--yes` 接受所有提示（非交互式）， `--no-aqe` / `--no-security` 禁用这些子系统， `--reconfigure` 重新提供 MCP 注册。 |
| **status** | 按子系统 ✓/⚠/✗（版本，工具包自己的版本，原生，安全，学习，aqe/RVF，MCP，**主机**（claude/codex — 版本 + 安装方法，或“已启用但未安装”），**提供者**（主机布线 + aqe 备用链，或“漂移”/claude-only 默认），守护进程，CLAUDE.md 块，状态行），每个漂移行命名 `sync` 将对其执行的操作。 |
| **sync** | 收敛动词：首先在存在新版本时升级，然后修复升级删除的所有内容，然后重新检查和报告。包含在此修复中：它 **安装任何启用的前沿主机**（claude/codex），该主机完全不存在 — 绝不触及外部（mise/brew/native）安装 — 并 **重新应用提供者布线**（`ENABLE_*` 主机环境，aqe 备用链和 ruflo API 提供者），每当它漂移时。它还 **自我更新工具包**：当存在较新的 `@pacphi/agentic-kit` 时，它将其作为 *最后* 一步安装（新代码从下一个 `ak` 运行开始应用，绝不在同步期间）。预发布安装（`4.0.0-alpha.*`）跟踪 `next` npm 分发标签以及 `latest`，因此 alpha 版本会看到其后续版本；稳定安装仅限于 `latest`。 `--no-upgrade` 跳过自我更新和包升级。 |
| **uninstall** | 删除工具包的占用（和任何遗留 shell-kit 安装）；绝不触及项目数据； `--purge` 还提供删除全局包。 |
高级用户机制位于 `ak x …`（`daemon-gc`，`mcp pick|off`，`provider status|pick|off`，`reference diff|sync`，`verify learning|security|aqe`，`improvement-eval`）下 — 请参阅 `ak --help --all`。
## 状态行
由工具包设置的项目在 ruflo 自己的状态行下获得一个追加的页脚，每个段 **仅在真正活动时显示**： 🧠 SONA 模式/轨迹（+ 实时微 LoRA Δ‖W‖）， 📈 路由-RL 指标， 🛡 aidefence， ⚙ 机器范围守护进程计数，和 🎓 Agentic-QE 统计。
## 要求
节点 ≥ 22，npm 和 `claude` CLI（Claude Code）。这就是整个列表 — **ruflo 和 agentic-qe 不是先决条件；`ak setup` 为您安装它们**（预先安装它们也没关系 — 设置只是检测并重用它们）。所有其他内容 — 包括 SQLite — 都嵌入其中；没有运行时依赖项。即使此仓库使用 pnpm 开发，npm 在运行时仍需：工具包修复了 *npm 管理的* 全局 ruflo/agentic-qe 树（`npm root -g`，`npm i -g`），这是这些包在目标机器上安装的方式。（pnpm 管理的全局：跟踪后续。）
### 前沿主机和 LLM 提供者
`ak` 检测您机器上的前沿代理 CLI，并可以将 ruflo + agentic-qe 连接到一个或两个 — **claude-default，codex 可选**，因此现有仓库在您选择加入之前会看到零变化。两个独立的轴：
- **主机** — 哪个代理 CLI 运行 ruflo 循环：`claude`（Claude Code）和/或 `codex`（OpenAI Codex），两者同时通过双模式。完全不存在的主机为您安装（`npm i -g @anthropic-ai/claude-code` / `@openai/codex`）；外部管理的安装（mise/brew/native）被检测、重用和绝不遮蔽。
- **提供者** — 路由器使用的 LLM，独立于主机：agentic-qe 的 `AQE_LLM_PROVIDER`（`claude-code`/`claude`/`openai`/`gemini`/`openrouter`/`azure-openai`/`bedrock`/`cognitum`/`ollama`/`onnx`）以及有序的备用链，和 ruflo 的 API 提供者。API 密钥保留在环境中 — 绝不写入 `kit.json`。
`ak x provider status` 显示检测到的内容和连接的内容；`ak x provider pick` 选择并应用（可逆）；`ak x provider off` 恢复 claude-only 默认。完整指南： [docs/PROVIDERS.md](docs/PROVIDERS.md)。
## 故障排除
[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — 症状 → `agentic-kit` 命令。
## 鸣谢
ruflo/claude-flow 由 ruvnet · agentic-qe 由 proffesor-for-testing · 先前艺术：Ciprian Melian 的修复 gist · 从该工具包的验证工作中提交的上游问题：[#2219](https://github.com/ruvnet/ruflo/issues/2219)，[#2222](https://github.com/ruvnet/ruflo/issues/2222)，[#2239](https://github.com/ruvnet/ruflo/issues/2239)，[#2360](https://github.com/ruvnet/ruflo/issues/2360)，[#2549](https://github.com/ruvnet/ruflo/issues/2549)，[#2670](https://github.com/ruvnet/ruflo/issues/2670)。
> v4（npm，跨平台）。基于 shell 的 v3 工具包存档在 [docs/archive/](docs/archive/) 中 — `ak setup` 自动迁移现有的 shell-kit 安装。一个薄的、可逆的层 — 不是一个分支。欢迎 PR。
