NeXgen-Engine

# NeXgen 引擎（Alpha） 一个基于 Git 的 AgentOps 控制层，用于 AI 编程 CLI。注意：该项目目前处于 Alpha 阶段。 共享指令、生成的 MCP 配置、漂移检查、机密管理以及跨机器的代理内存，均以 Git 仓库中的普通文件形式存在，而非托管服务。 您可以使用 Claude Code、Codex、OpenCode 或 Antigravity，可能不止一个，也可能在两台机器上。 每个 CLI 从不同的文件读取其启动指令，维护自己的 MCP 配置，并且不知道其他 CLI 的操作。 更改一个 CLI 的配置，其他 CLI 可能会偏离同步，通常在问题出现之前不会被注意到。 NeXgen 引擎为它们提供了一个统一的源，并允许检查是否偏离了该源。 ## 适用人群 您在自己的机器上运行至少一个代理 CLI，并希望使用实际的保险库，而不是演示版。 如果您运行多个 CLI 或在多台机器上运行相同的设置，那么框架将发挥最大作用：下面的 provisioner 和 doctor 脚本就是为这种情况设计的。 如果您只有一个 CLI 在一台机器上，您仍然可以获得知识保险库和启动纪律，而无需运行任何同步工具。 ## 演示路径 1. 克隆仓库并运行预检：`bash install.sh --check`。它检查先决条件，验证保险库脚手架，并列出在您的机器上找到的代理 CLI。 它不会写入任何内容。 2. 打开 `INIT.md` 并将其粘贴到一个具有文件系统能力的代理 CLI（Claude Code、Codex、OpenCode、Antigravity）中，而不是一个无法写入文件的网络聊天中。代理会询问您（多少个 CLI，多少台机器，Local-Only 或 Cloud-Server）并写入 `99-INDEX/USER-PROFILE.md`。 3. 代理根据 `03-INFRA/` 中的清单，安装 MCP 服务器和适用于您选择的 CLI 的技能。 4. 如果您处于 MULTI 配置文件（2 个以上的 CLI 或机器），请运行 `agent-sync apply` 以传播规范配置，然后运行 `agent-doctor` 以查看实际的合规性检查：对正在运行的 CLI、VPS 服务和机密处理进行 30 多个实时检查，并对每行给出 pass、warn 或 fail 的结果。 5. 在此之后手动更改某些内容（一个错误的 MCP 条目，一个在保险库之外编辑的配置文件），然后再次运行 `agent-doctor`。这就是漂移检查的工作原理。 ## 不具备的功能 没有 UI，没有托管仪表板，没有专有内存存储。 它不与 RAG 构建器或工作流协调器竞争。 它假设您已经对要使用的代理和工具有了自己的看法，并为它们提供了一个共享的、可审计的基础来运行。 **NeXgen 不具备的功能：** NeXgen 管理配置 - 一个规范源，生成的派生，漂移检测，单点写入。 它 **不** 位于代理与其工具之间的运行时：`agent-doctor` 不能阻止使用捏造的但看起来有效的参数进行的调用。 该边界由您的 CLI 托管（权限模式，用户确认提示）和 MCP 服务器本身的服务器端验证（例如 `vault-library` 中的 `expected_hash` 锁定）强制执行。 ## 核心概念 - **AI 基础设施即代码。** 清单文件定义工具，权限和代理行为。 一个统一的 Python 脚本 (`agent_sync.py`) 为不同的 CLI 生成正确的配置。 - **Git 支持的内存。** 代理读取和写入 Markdown 文件。 每个更改都经过版本控制，可差异化和轻松恢复。 - **确定性 AI 委员会（Alpha）。** 一个本地协调器 (`council.py`) ，用于协调多个模型进行头脑风暴和中继任务。 它使用显式 Python 代码传递控制，而不是依赖 LLM 来管理规则。 - **漂移检测。** 在 MULTI 配置文件中，`agent-doctor` 脚本对 CLI 的实时配置，保险库连接，技能和机密处理执行 30 多个只读检查，并报告每行的 pass，warn 或 fail（失败时退出代码为非零）。 它检测漂移和错误配置；它不位于执行路径中。 在 MINIMAL 中，没有医生：单个 CLI 在单个机器上通过视觉检查。 - **跨平台一致性（可选）。** 在 MULTI 配置文件中，系统通过 provisioner 强制代理在不同机器上表现相同（例如，Windows 工作站和 Linux 笔记本电脑）。 在 MINIMAL 中，只有一台机器，因此 provisioner 是 no-op 并且不安装。 ## 架构：三个层面 NeXgen 引擎将操作分为三个不同的层面： 1. **行为：** 一个链接到每个运行时环境的单一操作策略（`AGENTS.md`）。 2. **配置：** 一个抽象的 MCP 清单，编译成每个 CLI 的特定方言的生成器脚本。 3. **内存：** 一个纯 Markdown 保险库，通过序列化路径写入。 写入通过每种事物的一个门户进行。 知识笔记仅通过内存工具服务器写入，该服务器使用锁和预期哈希检查序列化，从而防止代理覆盖彼此的工作。 **技能保持延迟状态。** 工具感知和策略保留在启动和 MCP 清单中。 可选的任务工作簿存在于急切的发现根目录之外，并且仅在需要时打开。 请参阅 [`docs/lazy-skills.md`](docs/lazy-skills.md)。 ## 通过 MCP（模块化且免费）共享工具 代理共享基础设施而不是重新发明它。 一些服务运行一次，每个代理通过模型上下文协议（MCP）访问它们： > **注意：** 这些特定工具是完全可互换的。 它们之所以被选中，是因为它们可以在 **Oracle Cloud Always Free VPS** （4 ARM Ampere 内核，24GB RAM，200GB SSD）上舒适地运行且无成本。 您可以轻松地将它们替换为企业级同等产品。 - **语义搜索：** 一个自我托管的检索层（通过 model2vec + BM25 的静态嵌入）仅在私有 VPS 上运行 CPU。 代理通过含义查询知识库，而不会将内部数据发送到云模型。 - **网页抓取：** 一个自我托管的 Firecrawl 实例作为默认只读通道。 - **本地 OCR：** 一个自我托管的 OCR 服务，从截图，日志和扫描文档中本地提取文本。 - **可见浏览器：** 对于交互式任务（表单，登录，页面检查），代理通过 DevTools 协议附加到一个真正的，可见的 Chrome 窗口。 **代理严禁在用户背后运行无头浏览器。** ## 我们故意不构建的内容 我们没有编写专有内存引擎。 Markdown，Git 和一个简单的工具服务器已经提供了持久，可审计的内存，适用于人类和代理。 没有复杂的“代理到代理协商”，没有自治 Swarm A \* 计划器，没有 CRDT 和没有辅助数据库。 工作完全放在存储层之上：操作治理和安全防护。 ## 内容 | 目录 | 用途 | |---|---| | `03-INFRA/` | 引擎。包含代理启动规则（`AGENTS.md`），MCP 服务器定义和验证脚本（`agent-sync`，`agent-doctor`）。 | | `99-INDEX/` | 身份层。告诉代理当前硬件，操作系统和部署上下文（`USER-PROFILE.md`）。 | | `01-NOTES/` | 文档标准工作区。 | | `02-PROJECTS/` | 项目跟踪和执行日志。 | | `04-NOW/` | 活动优先级。 这限制了代理进入无关任务。 | ## 部署模式 1. **仅限本地。** 完全在您的机器上运行。依赖原生 CLI 工具和本地模型。适合测试和单用户设置。 2. **云服务器。** 连接到一个自我托管的堆栈（例如 n8n 用于编排，Firecrawl 用于抓取和专用 OCR），在 **您自己的私有环境** （VPS 或本地服务器）上通过 SSH 隧道部署。您维护您的数据的所有权； NeXgen 不为您提供或托管这些服务。 AI 引导的设置 (`INIT.md`) 为您的环境配置正确的模式。 ## 安装配置文件 框架适合两种使用方式。安装程序 (`INIT.md`) 会询问并选择合适的配置文件。 - **最小化。** 一个 CLI 在一台机器上（例如，只有 Claude Code 在您的笔记本电脑上，或 [OpenCode](https://opencode.ai) 用于基于 DeepSeek 的单 CLI 设置）。您获得知识保险库，启动规则，延迟技能和通过一个门户写入内存的纪律。无需运行 provisioner，无需安排医生，无需跨机器同步。直接在 CLI 中手动安装 MCP 服务器和技能。最适合只想要 AgentOps 治理的单个用户。 - **多重。** 两个或多个 CLI 和/或两台或以上机器。统一的 Python provisioner (`agent_sync.py`)，医生和健康检查上线，并将每个 CLI 和机器与保险库中的规范源保持一致。最适合工作站+笔记本电脑设置，或同时运行多个 CLI。 MULTI 传播是一个锁定，关闭事务。 拉取操作必须与来自一个权威远程的最新数据配合使用，然后再生运行时文件； 发布始终是一个单独的命令。 请参阅 [`docs/sync-contract.md`](docs/sync-contract.md)。 您可以从 MINIMAL 开始，稍后切换到 MULTI。 保存在保险库中的规范文件在配置文件之间不会更改。 ## 安装 您不需要手动填写配置文件。 1. 克隆仓库： ```bash git clone https://github.com/matteopasseri407/NeXgen-Engine.git ~/KnowledgeVault cd ~/KnowledgeVault ``` > 可选预检：`bash install.sh` 检查先决条件，验证脚手架，检测您的 CLI 并打印下一步骤。 它不会写入任何内容，可以安全地重新运行。 2. 打开 `INIT.md`。 3. 将其内容粘贴到一个 **具有文件系统能力的代理 CLI** （Claude Code，Codex，OpenCode，Antigravity）中，打开此文件夹，而不是一个普通的网络聊天（claude.ai / gemini），它无法写入文件。 4. 代理将询问您有多少个 CLI 和机器，您的硬件和部署模式，然后自动配置保险库。 ## 先决条件 - Git - Python 3.11+ 附带 PyYAML (`pip install pyyaml`)，或 Python 3.10 附带 `tomli`（`pip install pyyaml tomli`） - Node.js（用于 `npx`，如果您安装 MCP 服务器或外部技能，则需要） - 可选：[OpenCode](https://opencode.ai) 作为支持的 CLI 之一 - Linux/Mac 上的 `jq` 和 `curl`（仅在 MULTI 配置文件的同步和健康脚本中需要） ## 平台状态 **为什么是 Alpha？** Linux 是每日驱动的平台，并且测试最多，但框架仍处于 Alpha 阶段，因为跨平台支持和核心协调器正在积极稳定。具体来说： - **Windows 支持：** 虽然核心 provisioner 已统一到一个 Python 脚本 (`agent_sync.py`) 中，但 MCP 配置生成器 (`render.py`) 仍然缺乏 Windows 方言，并且一些运行时路径是推断的而不是实时确认的。 - **AI 委员会：** 确定性协调器 (`council.py`) 支持 `opencode`，`agy` 和 `codex` 席位。 自动测试涵盖所有四种模式的控制流，但供应商适配器和 Windows 启动器仍需要物理跨平台验证。 目前，MINIMAL 配置文件是 Windows 上更安全的起点。 macOS 遵循 Linux 代码路径，但实际使用较少。 ## 许可证 PolyForm 非商业许可证 1.0.0。免费用于任何非商业用途，包括阅读，运行，分支和修改。完整的许可证文本请参见 `LICENSE`。原始软件或衍生作品的任何商业用途都需要作者的单独许可证：请参见 `COMMERCIAL.md`。 ## 支持 本项目免费使用。一些可选链接（例如上面的 OpenCode）是推荐链接，可以在不增加您额外成本的情况下资助维护：请参见 `SUPPORT.md` 以获取声明的单个位置。 ## 通过MCP共享的工具（模块化并针对Free-Tier优化） 代理共享基础设施，而不是重新发明它。一些服务在单个实例中运行，所有代理通过模型上下文协议（MCP）访问： > **重要注意：** 这些特定工具是完全可互换的。它们被选中是因为它们可以在**Oracle Cloud Always Free VPS**（4核ARM Ampere，24GB RAM，200GB SSD）上轻松免费运行。根据需要，它们可以被企业替代品取代。 - **语义搜索：** 自托管的检索层（通过model2vec + BM25的静态嵌入）在私有VPS上仅使用CPU运行。代理在不向云模型发送内部数据的情况下，根据含义查询知识库。 - **网页抓取：** 自托管的Firecrawl实例作为预定义的只读通道。 - **本地OCR：** 自托管的OCR服务从本地扫描的截图、日志和文档中提取文本。 - **可见浏览器：** 对于交互式任务（表单、登录、页面控件），代理通过DevTools协议连接到真实且可见的Chrome窗口。**严禁代理在用户不知情的情况下执行无头浏览器。** ## 我们故意不构建的内容 我们没有编写专有的内存引擎。Markdown、Git和简单的服务器工具已经提供了人类和代理可以读取的持久且可审计的内存。 没有复杂的“代理间协商”，也没有自治的Swarm A\*规划器、CRDT或二级数据库。所有的精力都放在了存储**之上**的层面：运营治理和安全轨道。 ## 目录 | 目录 | 目的 | |---|---| | `03-INFRA/` | 引擎。包含基本规则（`AGENTS.md`）、MCP服务器定义和验证脚本（`agent-sync`、`agent-doctor`）。 | | `99-INDEX/` | 身份层。向代理报告硬件、操作系统和当前上下文（`USER-PROFILE.md`）。 | | `01-NOTES/` | 标准文档工作空间。 | | `02-PROJECTS/` | 项目跟踪和操作日志。 | | `04-NOW/` | 活动优先级。防止代理分散在不相关的任务上。 | ## 部署模式 1. **本地。** 完全在您的机器上运行。使用原生CLI工具和本地模型。适合单用户测试和设置。 2. **云服务器。** 连接到远程堆栈（例如，用于编排的n8n，用于抓取和专用OCR的Firecrawl），并通过SSH隧道安装和在您的**私有环境**（VPS或本地服务器）中管理。保持对您的数据的完全控制；NeXgen不提供或托管这些服务。 AI引导的设置（`INIT.md`）将为您配置适合您环境的模式。 ## 安装配置文件 框架适应两种使用形式。安装程序（`INIT.md`）会询问并选择正确的配置文件。 - **最小化。** 机器上的CLI（例如，仅Claude Code笔记本，或基于DeepSeek的[OpenCode](https://opencode.ai)单CLI设置）。通过单个端口获取知识库、引导规则、惰性技能和内存写入纪律。无需启动提供者，无需调度医生，无需机器间同步。在CLI中手动安装MCP服务器和技能。适合单人工作并希望在单个代理上使用AgentOps治理。 - **多。** 两台或多台CLI和/或两台或多台机器。统一的Python提供者（`agent_sync.py`）、医生和健康检查启动并保持每个CLI和机器与规范知识库同步。适合桌面+笔记本设置，或并行运行多个CLI。 在MULTI配置文件中，传播是带有锁定和安全阻塞的交易，以防发生错误。 拉取操作必须证明数据已更新，相对于单一远程授权，然后再重新生成运行时文件。 发布始终是一个单独的命令。 完整合同见[`docs/sync-contract.md`](docs/sync-contract.md)。 您可以从MINIMAL开始，然后在以后切换到MULTI。知识库的规范文件在配置文件之间不会更改。 ## 安装 您不必手动编译配置文件。 1. 克隆仓库： ```bash git clone https://github.com/matteopasseri407/NeXgen-Engine.git ~/KnowledgeVault cd ~/KnowledgeVault ``` > 可选的预检：`bash install.sh`检查先决条件，验证脚手架，检测您的CLI并打印下一步骤。它不会写入任何内容，可以安全地重新运行。 2. 打开`INIT.md`。 3. 将内容粘贴到**能够写入文件的代理CLI**（Claude Code、Codex、OpenCode、Antigravity）中，打开此文件夹，而不是网页聊天（claude.ai / gemini），因为它无法写入文件。 4. 代理将询问您有多少个CLI和机器、您的硬件和部署模式，然后自动配置知识库。 ## 先决条件 - Git - Python 3.11+，带有PyYAML（`pip install pyyaml`），或Python 3.10，带有`tomli`（`pip install pyyaml tomli`） - Node.js（用于`npx`，如果您安装MCP服务器或外部技能，则需要） - 可选：[OpenCode](https://opencode.ai)作为支持的CLI之一 - Linux/Mac上的`jq`和`curl`（仅MULTI配置文件需要，用于同步和健康检查） ## 平台状态 **为什么我们处于Alpha阶段？** Linux是每天使用的平台，测试最多，但框架处于Alpha阶段，因为跨平台支持和主要编排器仍在稳定。具体来说： - **Windows支持：** 虽然主要的提供者已统一为Python脚本（`agent_sync.py`），但MCP配置生成器（`render.py`）尚无Windows方言，一些运行时路径通过与Linux的类比推断，而不是通过实际确认。 - **AI建议：** 确定性编排器（`council.py`）支持`opencode`、`agy`和`codex`座位。 自动测试涵盖了四种模式的流程。 供应商适配器和Windows启动器仍需在两个平台上进行物理验证。 在Windows上，MINIMAL配置文件是目前最安全的起点。macOS遵循与Linux相同的代码路径，但实际使用较少。 ## 许可证 PolyForm非商业许可证1.0.0。免费用于任何非商业用途，包括阅读、执行、fork和修改。完整文本见`LICENSE`。原始软件或衍生作品的任何商业使用都需要作者的单独许可证：见`COMMERCIAL.md`。 ## 支持 该项目免费使用。一些可选链接（例如上面的OpenCode链接）是推荐链接，支持维护，不会增加您的额外成本：见`SUPPORT.md`以了解它们声明的唯一内容。