GuardianAgent

安全优先的 AI 智能体平台，适用于本地 LLM、受控工具使用、编码工作流、自动化以及个人助手工作。

GuardianAgent 是一个自托管的 AI 助手和智能体编排运行时，专为本地 AI、托管云和前沿 LLM 设计。它将日常使用的“第二大脑”与受控的高级用户界面相结合，适用于编码、工作站操作、工作流自动化、安全、网络和云操作。该助手可通过 Web、CLI 和 Telegram 访问，由运行时强制执行工具审批、沙箱、提示注入防御、审计追踪和策略边界。

## 目录 - [产品概述](#product-overview) - [核心能力](#core-capabilities) - [仓库状态](#repository-status) - [项目布局](#project-layout) - [文档](#documentation) - [安全一览](#security-at-a-glance) - [入门指南](#getting-started) - [LLM 提供商](#llm-providers) - [配置](#configuration) - [开发与验证](#development-and-verification) - [贡献](#contributing) - [故障排除](#troubleshooting) - [许可证](#license) ## 产品概述 GuardianAgent 专为需要本地 AI 智能体来完成实际工作，但又不想将未经检查的工具访问权交给 LLM 的用户而构建。它通过 Ollama 支持本地 LLM 助手，通过 OpenAI、Anthropic、OpenRouter、NVIDIA Cloud 和 Google Gemini 等提供商支持托管模型，并为搜索、编码、自动化、集成、与 Shell 相关的工作流以及运维任务提供了一个受控的工具层。 与简单的 Chatbot 包装器不同，GuardianAgent 将工具使用视为受控的安全边界。运行时通过共享网关路由意图，通过审批机制控制非只读操作，应用沙箱和允许路径策略，扫描提示注入和敏感信息泄露，并将 MCP 工具、包安装、浏览器操作、工作区访问和自动化限制在明确的护栏之后。 ### 第二大脑 Second Brain (`#/`) 是默认的 Web 主页。 - `Today` 以日程、快速记录、优先任务、简报、笔记和日常习惯为中心 - `Calendar` 将同步和本地事件与支持助手的计划和跟进相结合 - `Tasks` 提供了一个轻量级面板，用于管理优先级、截止日期和状态跟踪 - `Notes` 将可搜索、可固定和可归档的笔记集中在一处 - `Contacts`、`Library`、`Briefs` 和 `Routines` 完善了日常使用的记忆和维护工作流 - 将日常上下文与运维和工作站控制台分开 - 延伸阅读：[第二大脑构建设计](docs/design/SECOND-BRAIN-AS-BUILT.md)

Today 是默认的 Second Brain 落地视图，用于日程、记录、任务、简报、笔记和日常习惯。

Calendar	Tasks
Notes	Routines

### 高级用户能力 - `Performance` (`#/performance`) 用于工作站健康检查、可编辑配置文件、实时进程和已审查的清理操作。参见[性能管理规范](docs/design/PERFORMANCE-MANAGEMENT-DESIGN.md)。 - `Code` (`#/code`) 用于范围限定的代码仓库编码会话，包含聊天、Monaco 编辑器、差异比较、审批、信任审查、会话绑定的终端和工作区范围的执行。参见[编码工作区规范](docs/design/CODING-WORKSPACE-DESIGN.md)。 - `Automations` (`#/automations`) 用于已保存和计划执行的 Guardian 工作流和助手任务。参见[自动化框架规范](docs/design/AUTOMATION-FRAMEWORK-DESIGN.md)。 - `Security`、`Network` 和 `Cloud` 用于警报、安全态势、诊断和基础设施监控。从 [WebUI 设计](docs/design/WEBUI-DESIGN.md) 和 [SECURITY.md](SECURITY.md) 开始。 - `Configuration` 和 `Reference Guide` 用于设置、集成、策略和操作员指导。 ### 共享助手 - Web、CLI 和 Telegram 均使用相同的受控助手模型 - 支持本地、托管云和前沿 LLM 提供商，包括 Ollama、Ollama Cloud、OpenRouter、NVIDIA Cloud、Anthropic、OpenAI 和其他兼容 OpenAI 的提供商 - 内置工具、集成、记忆和自动化均在审批和策略控制之下 - 更多细节：[WebUI 设计](docs/design/WEBUI-DESIGN.md)，[工具控制平面设计](docs/design/TOOLS-CONTROL-PLANE-DESIGN.md) ## 截图 Second Brain 的截图已在上文的产品概述中展示。下方的图库涵盖了其余主要的 Guardian 界面。

打开完整的应用程序图库

安全、网络、云、自动化、配置、编码工作区和参考指南。

Security	Network
Cloud	Automations
Configuration / Providers	Coding Workspace
Reference Guide

## 核心能力 - 安全优先的 AI 智能体平台，适用于本地、自托管和混合 LLM 工作流 - 本地 AI 和 Ollama 支持，以及 OpenAI、Anthropic、OpenRouter、NVIDIA Cloud、Gemini 和其他托管提供商 - 受控的工具使用，包含审批、沙箱、允许路径、命令策略和审计追踪 - 提示注入防御、输出扫描、敏感信息脱敏、信任感知记忆和隔离的工具结果重注入 - AI 编码助手和范围限定的 Coding Workspace，带有编辑器、差异比较、会话绑定的终端、信任审查和验证界面 - 日常使用的 Second Brain，用于规划、记录、检索、日历感知上下文、任务、笔记、联系人、日常习惯和简报 - 工作流自动化和计划执行的 Agent 运行，具有有界权限、运行历史和感知审批的执行 - MCP 工具安全、原生集成、搜索、浏览器/工作区工具以及提供商连接器，均在相同的运行时护栏之后 - 跨 Web、CLI 和 Telegram 的共享助手 - 规范和架构文档，在您需要时提供更深入的实现细节 ## 仓库状态 GuardianAgent 是一个专注于安全的、本地优先的助手运行时，拥有几个成熟的产品界面和几个正在积极演进的控制平面区域。 | 区域 | 状态 | |------|--------| | Second Brain、Coding Workspace、Security 仪表板、Configuration Center | 正在积极实现的产品界面 | | Web、CLI 和 Telegram 渠道 | 受支持的第一方渠道 | | 本地、托管云和前沿 LLM 提供商 | 通过可配置的提供商配置文件支持 | | 代理工作器隔离、审批、输出扫描、审计追踪 | 核心运行时安全模型 | | 部分云、托管、联盟和企业提案 | 位于 `docs/proposals/` 和 `docs/plans/` 下的设计阶段或路线图材料 | 已发布的旧提案位于 `docs/implemented/`。已完成的一次性计划位于 `docs/archive/`。现行规范主要位于 `docs/design/` 和 `docs/architecture/`。 ## 项目布局 ``` GuardianAgent/ ├─ src/ TypeScript runtime, channels, tools, prompts, memory, and orchestration │ ├─ channels/ Web, CLI, Telegram, and runtime route adapters │ ├─ runtime/ Intent gateway, orchestration, code sessions, memory, security, automations │ ├─ tools/ Built-in tools, executor, registry, MCP client, and tool policy surfaces │ ├─ llm/ Provider clients, routing, failover, and guarded LLM access │ ├─ guardian/ Admission, policy, output, and audit security controls │ └─ search/ Local and provider-backed search integration ├─ web/public/ Browser UI, page modules, chat panel, styles, assets, and vendored UI code ├─ scripts/ Setup scripts, smoke tests, integration harnesses, and packaging helpers ├─ docs/ │ ├─ architecture/ Current architecture and module-boundary guidance │ ├─ design/ Current product and runtime specifications │ ├─ guides/ Operator and contributor guides │ ├─ plans/ Active implementation plans │ ├─ proposals/ Unshipped or partially scoped future proposals │ ├─ implemented/ Historical proposals whose core scope has shipped │ └─ archive/ Retired designs and completed plans ├─ policies/ Security and runtime policy files ├─ skills/ Bundled skill instructions and workflows ├─ native/windows-helper/ Rust helper for Windows-native host integration and isolation support └─ build/ Generated packaging artifacts ``` ## 文档 请从这些文档开始阅读，而不是浏览 `docs/` 下的每个文件： | 主题 | 文档 | |-------|----------| | 架构概览 | [docs/architecture/OVERVIEW.md](docs/architecture/OVERVIEW.md) | | 前向模块边界 | [docs/architecture/FORWARD-ARCHITECTURE.md](docs/architecture/FORWARD-ARCHITECTURE.md) | | 安全模型 | [SECURITY.md](SECURITY.md) | | Web UI 信息架构 | [docs/design/WEBUI-DESIGN.md](docs/design/WEBUI-DESIGN.md) | | Second Brain 产品界面 | [docs/design/SECOND-BRAIN-AS-BUILT.md](docs/design/SECOND-BRAIN-AS-BUILT.md) | | Coding Workspace | [docs/design/CODING-WORKSPACE-DESIGN.md](docs/design/CODING-WORKSPACE-DESIGN.md) | | 工具控制平面 | [docs/design/TOOLS-CONTROL-PLANE-DESIGN.md](docs/design/TOOLS-CONTROL-PLANE-DESIGN.md) | | 能力编写 | [docs/guides/CAPABILITY-AUTHORING-GUIDE.md](docs/guides/CAPABILITY-AUTHORING-GUIDE.md) | | 集成测试 | [docs/guides/INTEGRATION-TEST-HARNESS.md](docs/guides/INTEGRATION-TEST-HARNESS.md) | | 安装和打包 | [INSTALLATION.md](INSTALLATION.md) | ## 安全一览 GuardianAgent 在运行时级别强制执行安全——Agent 无法绕过它。每条消息、LLM 调用、工具操作和响应都会经过强制性的检查点。 | 层级 | 时机 | 功能 | |-------|------|--------------| | **1 — Admission** | Agent 看到输入之前 | 提示注入检测、速率限制、能力检查、敏感信息/PII 扫描、路径阻断、SSRF 防护 | | **1.5 — Process Sandbox** | 工具执行期间 | 通过 bwrap 命名空间 进行操作系统级隔离、原生辅助程序 或 ulimit/env 硬化回退 | | **2 — Guardian Agent** | 工具执行之前 | 内联 LLM 评估每个非只读工具操作；阻止高/严重风险。默认失败关闭 | | **3 — Output Guardian** | 执行之后，交付或重新注入之前 | 扫描 LLM 响应和工具结果，对信任度进行分类（`trusted` / `low_trust` / `quarantined`），脱敏敏感信息/PII，并可以抑制原始重新注入 | | **4 — Sentinel Audit** | 回顾性（计划或按需） | 分析审计日志以查找异常模式：能力探测、体量激增、重复的敏感信息检测、错误风暴 | 内置的聊天/规划器循环运行在一个**代理工作器进程**中，且没有网络访问权限。工具、审批、信任元数据和 LLM API 调用均通过代理 RPC 进行调解。 类似于安装的公共包管理器操作也会通过专用的托管路径进行路由。Guardian 使用 `package_install` 来暂存请求的顶级包构件，在执行前对其进行审查，通过活动工作区或配置的允许路径解析安装工作目录，并在统一的安全工作流中显示警告或阻止的发现，而不是将包安装视为普通的 shell 命令。 有关完整的安全架构、威胁模型和配置细节，请参阅 [SECURITY.md](SECURITY.md)。 ## 入门指南 ### 前置条件 - **Node.js 20** 或更新版本 - 本地、托管云或前沿的 **LLM 提供商**（Ollama、Ollama Cloud、OpenRouter、NVIDIA Cloud、Anthropic、OpenAI 等） 当 Node 构建包含 `node:sqlite` 时，将启用 SQLite 支持的持久化和监控。否则，助手记忆和分析将在内存中自动运行。 ### 快速开始 克隆仓库并使用平台启动脚本： **Windows:** ``` .\scripts\start-dev-windows.ps1 ``` **Linux / macOS:** ``` bash scripts/start-dev-unix.sh ``` 这些脚本处理依赖项安装、构建、启动和初始配置引导。 对于手动开发循环： ``` npm install npm run check npm test npm run dev ``` ### 首次运行 启动后： 1. **打开 Web UI** 并进入 **Configuration Center** (`#/config`，通常是 `http://localhost:3000`) 2. **添加您的 LLM 提供商** — 选择 Ollama 用于本地模型，或者为 Ollama Cloud、OpenRouter、NVIDIA Cloud、Anthropic、OpenAI 或其他受支持的外部提供商添加 API key。 3. 在 `#/` **打开 Second Brain** 以确认默认的日常主界面已上线，并且助手已准备好执行任务、笔记、日历和联系人工作流。 4. **如果需要，连接 Google Workspace 或 Microsoft 365** — 当您希望将提供商支持的日历和联系人同步到 Second Brain 时，请使用 `Cloud > Connections`。 5. **审查工具策略** — 默认对主助手设置为 `on-request` / `approve_each`，并带有只读 shell 白名单。变更工具仍需审批，公共包管理器安装应通过托管的 `package_install` 路径而不是 `shell_safe` 进行。 6. **启用可选渠道** — Telegram 机器人设置位于 `Configuration > Integration System > Telegram Channel` 7. **设置 Web 身份验证** — Web 访问默认为 Bearer 保护模式；在 `Configuration > Integration System > Web Authentication` 或使用 CLI `/auth ...` 进行配置 8. **如果需要，打开 Coding Workspace** — 前往 `#/code` 获取具有独立会话历史、信任审查、终端、审批和验证界面的项目级编码工作区 大多数配置是通过 **Web UI** 或 **CLI 命令**（`/config`、`/providers`、`/auth`、`/tools`）完成的。手动编辑 `config.yaml` 是可选的，仅供高级使用。 ### 使用 GuardianAgent GuardianAgent 可通过三个渠道访问： | 渠道 | 访问方式 | 最适合 | |---------|--------|----------| | **Web** | 配置端口的浏览器 | Second Brain、仪表板/运维界面、配置、、聊天和 Coding Workspace | | **CLI** | 运行 GuardianAgent 的终端 | 快速命令、脚本编写和本地开发 | | **Telegram** | Telegram 机器人（需要设置） | 移动访问和通知 | **您可以执行的操作：** - 与内置的 AI 助手聊天 - 将 Second Brain 用作任务、笔记、联系人、日常习惯和日历感知规划的默认日常主页 - 将 Performance、Security、Network、Cloud 和 Automations 用作专用的运维界面，而不是将所有内容都埋没在聊天中 - 使用 Coding Workspace 进行范围限定的代码仓库工作，带有编辑器、差异比较、审批、检查、信任审查和会话绑定的终端 - 在同一个助手中运行受控的工具、集成、搜索和自动化工作流 **审批与安全：** 根据策略、信任级别和工具风险，操作可能会自动运行、等待审批或被拒绝。有关详细行为，请参阅 [SECURITY.md](SECURITY.md) 和 [工具控制平面设计](docs/design/TOOLS-CONTROL-PLANE-DESIGN.md)。 ### 编程 Workspace Web 的 `Code` 页面是一个专用的范围限定代码仓库工作区，由服务器拥有的代码会话提供支持。它具有独立的会话上下文、编辑器、差异比较、审批、检查、信任审查和会话绑定的终端。 实现细节和当前限制记录在 [docs/design/CODING-WORKSPACE-DESIGN.md](docs/design/CODING-WORKSPACE-DESIGN.md) 中。 ### Telegram 设置 1. 打开 Telegram，搜索 `@BotFather`，按 **Start**，运行 `/newbot` 2. 按照提示输入机器人名称和用户名（必须以 `bot` 结尾），复制机器人 token 3. 在 `Configuration > Integration System > Telegram Channel` 中添加 token，或通过 CLI 配置流程添加 4. 使用允许的聊天 ID 限制访问 5. 保存频道设置；当 token 或凭证引用和白名单有效时，Telegram 的更改会热重载 ### Windows 便携版构建（可选） 为了在 Windows 上获得额外的原生子进程隔离： ``` npm run portable:windows # Portable zip with sandbox helper npm run installer:windows # Traditional installer ``` 有关 Windows 打包选项的完整列表，请参阅 [INSTALLATION.md](INSTALLATION.md)。 ## LLM 提供商 GuardianAgent 跨本地、托管云和前沿层级支持 12 个内置提供商家族： | 提供商 | 类型 | 备注 | |----------|------|-------| | **Ollama** | Local | 通过原生 Ollama 路径在本地运行模型 | | **Ollama Cloud** | Managed cloud | 介于本地和前沿提供商之间的 Ollama 原生远程层 | | **OpenRouter** | Managed cloud | 兼容 OpenAI 的模型网关，适用于许多托管模型 | | **NVIDIA Cloud** | Managed cloud | 兼容 OpenAI 的 NVIDIA 托管推理端点 | | **Anthropic** | Frontier hosted | 带有提示缓存的 Claude 模型 | | **OpenAI** | Frontier hosted | GPT 模型 | | **Groq** | Frontier hosted | 快速的兼容 OpenAI 的推理 | | **Mistral AI** | Frontier hosted | Mistral 托管模型 | | **DeepSeek** | Frontier hosted | DeepSeek 托管模型 | | **Together AI** | Frontier hosted | 开源模型托管 | | **xAI (Grok)** | Frontier hosted | Grok 模型 | | **Google Gemini** | Frontier hosted | 通过兼容 OpenAI 的端点提供 Gemini 模型 | ### 智能路由 当同时配置了本地和外部提供商时，工具会按类别自动路由： | 路由到 **Local** 模型 | 路由到 **External** 模型 | |---|---| | Filesystem、Shell、Network、System、Memory | Web、Browser、Workspace、Email、Contacts、Search、Automation | 单一提供商设置无需配置即可工作。智能路由可以在 Configuration > Tools 中关闭。可以通过 LLM 列下拉菜单进行每个工具和每个类别的覆盖。 在外部层级中，`Configuration > AI Providers` 控制 Guardian 是倾向于托管云配置文件（例如 Ollama Cloud、OpenRouter 或 NVIDIA Cloud）还是前沿托管配置文件。Model Auto Selection Policy 可以将命名的托管云配置文件绑定到 general、direct、tool-loop 和 coding 角色。 **基于质量的回退：** 当本地模型产生退化的响应（空、拒绝或样板回复）时，系统会自动通过回退链进行重试。 ## 配置 大多数用户通过 **Web Configuration Center** (`#/config`) 或 **CLI 命令** 配置 GuardianAgent。位于 `~/.guardianagent/config.yaml` 的 `config.yaml` 文件由这些流程自动创建和更新。 三个简化的顶级配置别名涵盖了最常见的设置： ``` sandbox_mode: workspace-write # off | workspace-write | strict approval_policy: on-request # on-request | auto-approve | autonomous writable_roots: # merged into allowedPaths + sandbox writePaths - /home/user/projects ``` 默认运行时保持代理模式，具有 `workspace-write` 沙箱配置文件和宽松的强制执行。当您希望有风险的子进程支持工具在没有强大的沙箱后端可用时默认失败关闭，请设置 `sandbox_mode: strict`。 有关详细的配置文档： - [配置中心规范](docs/design/CONFIG-CENTER-DESIGN.md) - [WebUI 设计规范](docs/design/WEBUI-DESIGN.md) ## 开发与验证 ``` npm test # Run all tests (vitest) npm run test:verbose # Verbose test output npm run test:coverage # Run with v8 coverage npx vitest run src/path/to.test.ts # Run a single test file npm run check # Type-check only (tsc --noEmit) npm run build # TypeScript compilation → dist/ npm run dev # Run with tsx (starts CLI channel) ``` 针对常见回归表面的专注测试套件： ``` node scripts/test-coding-assistant.mjs node scripts/test-code-ui-smoke.mjs node scripts/test-contextual-security-uplifts.mjs node scripts/test-security-verification.mjs ``` 在迭代期间使用专注的 Vitest 运行，然后在交接涉及路由、审批、编码、安全、Web UI、提供商或启动行为的更改之前，运行更广泛的相关测试套件。集成测试指南包含完整的矩阵：[docs/guides/INTEGRATION-TEST-HARNESS.md](docs/guides/INTEGRATION-TEST-HARNESS.md)。 ## 贡献 此仓库专为架构敏感的更改而构建。在更改子系统之前，请阅读所属的设计文档，并保持实现、测试和文档同步。 - 保持现有 TypeScript 风格的代码：严格的 ESM、2 空格缩进、分号、单引号以及相对导入中的显式 `.js` 扩展名。 - 为行为更改添加或更新并置的 `*.test.ts` 覆盖。 - 在提交 PR 之前运行 `npm run check` 和相关的 Vitest 或测试套件命令。 - 为面向用户/操作员的工作流更改更新 `src/reference-guide.ts`。 - 在更改架构、路由、工具行为、安全边界或 Web 界面时，更新相关的 `docs/design/`、`docs/architecture/` 或指南文档。 - 不要提交敏感信息、本地凭证、来自 `~/.guardianagent/` 的生成运行时状态或来自 `tmp/` 的草稿输出。 ## 故障排除 | 症状 | 首先检查 | |---------|--------------| | Web UI 未加载 | 确认开发脚本仍在运行，检查配置的端口，并查看终端中是否有启动错误。 | | 提供商调用失败 | 复查 `Configuration > AI Providers` 中的提供商配置文件、API key 或凭证引用、模型名称和网络访问。 | | 本地 Ollama 模型不可用 | 确认 `ollama serve` 正在运行，并且配置的模型已在本地拉取。 | | Web API 返回 unauthorized | 在 `Configuration > Integration System > Web Authentication` 或通过 CLI `/auth ...` 配置或轮换 Web 身份验证。 | | 工具执行被阻止 | 在 Configuration 中审查待处理的审批、沙箱模式、允许路径、允许命令和工具策略。 | | Coding Workspace 无法访问文件 | 确认活动的代码会话指向预期的工作区，并且请求绑定到该会话。 | ### 报告意图路由问题 如果 GuardianAgent 选择了错误的路由、使用了错误的工具、要求了错误的澄清，或者给出了与请求界面不匹配的结果，请提交 GitHub issue 并附带： - 确切的用户请求和您看到的响应 - 使用的渠道或界面，例如 Web、CLI、Telegram 或 Code - 响应头中显示的模型/提供商配置文件（如果有） - 来自 `~/.guardianagent/routing/intent-routing.jsonl` 的相关意图路由跟踪 在 Windows 上，跟踪通常位于 `C:\Users\\.guardianagent\routing\intent-routing.jsonl`。如果可能，请仅附上失败请求附近的行。跟踪可能包含提示、本地文件路径、提供商名称和工具参数，因此在共享之前请检查并编辑敏感数据。 GitHub issue 评论支持拖放文件附件以用于日志和 JSON 数据。如果 GitHub 拒绝 `.jsonl` 文件扩展名，请将摘录重命名为 `.log` 或将其放入 `.zip` 中后再附上。参见 GitHub 的附件指南：https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/attaching-files。 ## 免责声明 本软件按“原样”提供，不提供任何形式的保证。GuardianAgent 实施了旨在降低 AI 智能体系统风险的安全控制，但**没有任何软件可以保证绝对安全**。开发者和贡献者对因使用本软件而产生的任何损害、数据丢失、凭证泄露、财务损失或其他伤害不承担任何责任。 使用 GuardianAgent，即表示您承认： - AI 系统本质上是不可预测的，可能会产生意想不到的输出 - 安全模式（敏感信息扫描、提示注入检测）依赖于已知的签名和启发式方法，可能无法捕获新颖或混淆的攻击向量 - 您需对您环境中的本软件的配置、部署和操作自行承担全部责任 - 您应独立评估安全控制是否足以满足您的用例 - 本软件不应用作处理敏感数据的系统的唯一安全控制，除非有额外的保障措施 本项目未隶属于任何安全认证机构，也不作任何合规性声明。 ## 许可证 Apache 2.0

标签：AI安全运营, AI开发框架, AI智能体编排, AI风险缓解, ATT&CK防御, CISA项目, CSV导出, DevSecOps, DNS 反向解析, GNU通用公共许可证, IP 地址批量处理, JSON 请求, MITM代理, Node.js, Telegram机器人, 上游代理, 个人助手, 云安全运营, 云端大模型, 代码工作区, 前沿大模型, 可视化界面, 多平台支持, 多渠道集成, 安全第一, 安全防护, 审计追踪, 工作流自动化, 工具审批, 开源AI, 提示工程安全, 提示注入防御, 本地LLM, 本地大模型, 沙盒环境, 沙箱隔离, 源代码安全, 私有化部署, 第二大脑, 策略边界, 系统运维自动化, 网络安全, 自动化攻击, 自托管, 防御规避, 隐私保护