LocalGate

# LocalGate

> **在线 Agent + LocalGate = 一个真正能在本地开发、执行任务并完成交付的工作型 Agent。**
>
> 很多在线 Agent 会思考、会对话，但缺少真实的开发和工作能力。接入 LocalGate 后，它可以安全地操作本地文件、修改代码、运行命令、启动长期进程、执行审批流程并完成部署。

**多种接入模式：MCP + Skills；有网络访问或者有 MCP 都可接入。**

**自描述 + Skills 支持 + 静态应用部署 + 动态应用部署 + 后台管理与审计**

LocalGate 不只是给 Agent 增加几个工具，而是提供从能力发现、使用指引、执行控制，到应用发布和事后追踪的一整套工作闭环。

**把 AI Agent 的本地执行能力，从“直接给 Shell”升级为一套可隔离、可审批、可观察、可部署的控制平面。**

LocalGate 位于 AI Agent 与操作系统之间，把文件操作、命令执行、交互式进程和应用部署封装成具名工具。客户端可以通过 stdio MCP、HTTP MCP 或普通 HTTP API 使用同一套能力，而目录范围、命令策略、审批规则、日志和审计都由服务端统一控制。

```text
AI Agent / MCP Client / HTTP Client
                 │
       stdio MCP │ HTTP MCP │ REST
                 ▼
┌─────────────────────────────────────┐
│              LocalGate              │
│ Tool Registry · Task · Session      │
│ Approval · Audit · Root Policy      │
│ Static/Dynamic Deployment           │
└─────────────────────────────────────┘
                 │
         Filesystem · Shell · Runtime
```

<p align="center">
  <img src="./images/gpt_application.png" alt="ChatGPT 通过 LocalGate 获得本地开发与执行能力" width="720">
</p>

<p align="center"><sub>ChatGPT / 在线 Agent 通过 MCP 或 Skills 接入 LocalGate</sub></p>

## 为什么是 LocalGate

### 1. 给 Agent 工具，而不是把整台机器交给它

LocalGate 通过具名工具提供能力，但不会把完整 Registry 平铺成 MCP 顶层工具。普通 MCP 模式只保留稳定的核心工具面；部署、Session、Task、Subagent 等领域能力由 Builtin Skill 渐进披露，再通过 `get_tool_schema` + `invoke_tool` 调用。无论从哪个入口执行，目标工具仍要经过 root、路径、命令、环境变量、审批和 Shell 语法策略检查。

这意味着你可以让 Agent 真正完成开发和运维工作，同时把访问范围限制在指定项目目录，而不是开放一个无边界的远程终端。

普通 MCP 模式的稳定顶层工具为：

- `get_startup_instructions`
- `get_skill`
- `get_tool_schema`
- `invoke_tool`
- `read_file`
- `apply_patch`
- `run_command`
- `upload_file`
- `export_file`

其中 `upload_file` / `export_file` 保持直接 MCP 暴露，用来保留宿主文件参数和 MCP `resource_link` 等原生协议语义。其余低频工具仍是完整的 LocalGate Registry 能力，只是不再长期占用 `tools/list`；匹配任务时先加载 startup 推荐的 Builtin Skill，再读取目标 schema 并通过 `invoke_tool` 执行。

### 2. 审批不是弹窗，而是执行状态机的一部分

高风险操作可以在真正执行前进入 `pending_approval`。审批记录会绑定原始 Task、工具、参数摘要和请求者。

批准后继续执行的是**同一个 Task**，客户端不需要重新发起命令，也不会因为“批准后重试”自然产生第二份任务。这使审批可以嵌入 Agent 的自动化流程，而不是成为流程之外的人工补丁。

### 3. Task 与 Session 分离，短任务和长进程都能正确管理

- **Task** 负责一次性工作：读写文件、执行测试、构建产物、发布站点。
- **Session** 负责持续工作：REPL、开发服务器、watch 进程、交互式终端。

Task 有状态、增量日志、事件流、取消和最终结果；Session 有独立终端缓冲、stdin 和生命周期。客户端不需要拿一个“万能 Shell 接口”勉强处理所有执行模式。

### 4. MCP + Skills，多种环境都能接入

LocalGate 不要求在线 Agent 必须原生支持某一种固定协议：

- **有 MCP 能力**：直接通过 stdio MCP 或 Streamable HTTP MCP 发现并调用工具。
- **只有网络访问能力**：通过 Skills 获取调用规则，再使用普通 HTTP API 执行任务。
- **本地客户端**：可以使用 stdio MCP，避免额外开放网络服务。
- **远程在线 Agent**：可以通过 HTTP MCP，或通过 Skills + HTTP API 接入。

因此，只要 Agent 能访问网络，或者本身支持 MCP，就可以接入 LocalGate。Skills 负责告诉 Agent 如何发现工具、构造参数、处理 Task/Session、审批和结果；MCP 与 HTTP API 则负责真正执行。

同一套能力支持三种传输方式：

- **stdio MCP**：适合桌面 Agent 和本地 MCP Host。
- **Streamable HTTP MCP**：适合远程或常驻 MCP 服务。
- **REST API**：适合脚本、后台服务、CI 和管理系统集成。

工具定义、策略和审计不会因为传输方式不同而分裂成多套实现。

### 5. 原生支持标准 Skills，按需扩展模型能力

除了仓库内置的 LocalGate 使用 Skills，LocalGate 还原生支持标准 `SKILL.md` 目录结构。你可以安装任意面向 Agent 的通用 Skill，用它补充领域知识、操作流程、工具选择规则和任务执行规范，而不需要修改 LocalGate 本身。

LocalGate 会扫描两个标准位置：

```text
~/.agents/skills/<skill-name>/SKILL.md
<root>/.agents/skills/<skill-name>/SKILL.md
```

这套机制具备：

- **动态安装**：把 Skill 目录复制、解压、克隆或软链接到上述目录后，下一次调用 `get_startup_instructions` 时即可被发现，通常无需重新编译或重启 LocalGate。
- **全局与项目级作用域**：全局 Skills 可以被多个 LocalGate 实例共用，项目级 Skills 只服务于当前 root。
- **标准 Frontmatter**：读取 `name`、`description` 和 `disable-model-invocation` 等字段。
- **渐进式披露**：启动阶段只向模型披露 Skill 的名称、简介和文件位置；只有任务与描述匹配时，模型才使用 `read_file` 读取完整 `SKILL.md` 及其引用内容。
- **上下文节省**：不会在每次请求中把所有 Skill 正文全部塞进提示词，减少无关上下文和 Token 消耗。
- **可控可见性**：设置 `disable-model-invocation: true` 的 Skill 不会出现在模型可见列表中。
- **目录与软链接兼容**：支持标准 Skill 目录，也支持通过软链接管理共享 Skill 集合。

渐进式披露流程：

```text
扫描 Skills 目录
      │
      ▼
仅披露 name / description / location
      │
      │ 任务与 Skill 描述匹配
      ▼
read_file 读取对应 SKILL.md
      │
      ▼
按 Skill 指引完成当前任务
```

因此，LocalGate 不只是提供一组固定工具，还可以作为标准 Skills 的运行入口，让模型能力随着 Skill 的安装和更新持续扩展。

### 6. Agent 可以从改代码一路走到部署

LocalGate 不只提供文件和命令工具，还内置静态与动态应用部署：

- 静态目录发布
- 动态进程监督
- 健康检查
- stdout/stderr 日志轮转
- 崩溃重启
- Release 保留
- 原版本回滚
- 控制面与 deployment 应用面使用独立监听端口，并继续执行 Host 校验

Agent 可以在同一个受控执行面中完成“修改代码 → 运行测试 → 构建 → 部署 → 检查日志 → 回滚”。

### 7. 默认面向真实机器的安全边界

LocalGate 的限制不是客户端约定，而是在服务端执行：

- 单 root 目录隔离
- 路径拒绝列表
- 命令 allowlist / denylist
- Shell 管道、重定向、后台执行和命令替换开关
- 环境变量 allowlist
- HTTP Bearer 鉴权
- 高风险工具审批
- 输出大小与执行超时限制
- 敏感字段脱敏与审计记录

### 8. 用 MCP 文件对象打通在线 Agent 与本地文件系统

在线 Agent 通常运行在隔离环境中，不能直接访问用户电脑上的路径，也很难主动连接本地上传接口。LocalGate 的 `upload_file` 不要求 Agent 先申请临时上传 Token，而是直接使用 MCP 宿主提供的文件对象。

当用户在 ChatGPT 中上传文件时，ChatGPT 会为该文件签发短期可访问 URL，并把文件对象作为 MCP 工具参数传给 LocalGate。LocalGate 再将文件下载到经过 root policy 校验的本地绝对路径。

```text
用户在 ChatGPT 上传文件
          │
          │ ChatGPT 文件对象
          │ file_id / file_name / mime_type / temporary download_url
          ▼
   MCP tools/call: upload_file
          │
          ▼
LocalGate 下载并校验目标路径
          │
          ▼
本地 root 文件系统
```

这样，在线 Agent 即使存在网络与文件系统隔离，也能通过标准 MCP 文件参数把附件可靠地送入本地开发环境。

## 适合哪些场景

- 给 Claude、ChatGPT、Co

... (truncated)