Gridctl 是一个 MCP 网关，内置技能库，目标是让开发者把自己的智能体配置放进版本控制。MCP 服务器、技能、智能体定义和规则都以可提交的文件形式声明。Gridctl 在一个网关后面运行 MCP 服务器；另有一个独立的投影机制，把技能、智能体定义和规则写入受支持的客户端。
用途与定位
Gridctl 面向维护自有智能体环境或团队共享环境的开发者。它让 MCP 服务器、技能、智能体定义和规则归属于文件，而运行中的进程、密钥值以及每台机器上的客户端安装不属于文件。提交的栈文件就是 gridctl apply 在该主机上启动的内容，但结果取决于文件中的固定版本以及能够运行它们的主机，并不承诺智能体行为完全一致。Gridctl 不运行智能体的规划或模型循环，需要搭配自选的智能体运行时；gridctl plan 是另一个命令，用于预览部署变更，而不是规划智能体工作。
主要能力
- 声明式、可版本控制的 MCP 环境：用 YAML 定义 MCP 服务器栈，启动并通过一个网关暴露；提交前可验证，应用前可预览，并能检测环境漂移。漂移检测在后台运行，标记已运行但不在规格中的服务器，以及已声明但尚未部署的内容。
- 技能库与注册表：注册表中的每个 SKILL.md 会作为提示向上游 MCP 客户端暴露，可经 git 仓库、本地目录、客户端导入或 pack 进入注册表。技能遵循 agentskills.io 规范，为带 frontmatter 的普通 Markdown。
- 客户端连接：gridctl link 自动检测已安装的 LLM 客户端并注入网关配置，不安装技能、智能体或规则；在 stack.yaml 中声明 link 块可在每次 apply 时幂等连接所列客户端。支持客户端包括 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Gemini、Antigravity、OpenCode、Grok Build、Continue、Cline、AnythingLLM、LM Studio、Roo、Zed、Goose。
- 导入：gridctl import 反向扫描客户端配置，去重服务器并追加到 stack.yaml，可将明文密钥写入加密变量存储；gridctl import <client> --kind all 在一次运行中导入该客户端的技能、智能体与全局上下文。
- 运行时控制：提供 MCP 执行控制（hardened 与 local 模式）、工具调用频率限制、按客户端/服务器/工具限制调用速率。
- 工具面控制：通过每服务器 tools: 白名单、groups: 跨服务器分组端点（/groups/{name}/mcp）、clients: 限制各客户端可访问的内容。
- 输出格式转换：工具调用结果默认 JSON，可在网关或每服务器级别设置 output_format 转为 TOON 或 CSV，针对表格与键值数据减少 token 消耗 25–61%；非 JSON 响应和超过 1 MB 的负载原样传递，格式转换只重写文本块。
- 使用观测与优化：统计每次成功工具分派的参数与结果；Metrics 工作区展示吞吐、调用次数与格式转换节省；gridctl optimize 扫描运行中的网关，给出可操作发现及预计每周 token 影响，并附可粘贴的 YAML 修复。
- 供应链信任：首次见到工具定义时固定，后续 apply 标记漂移；固定定义会扫描注入信号，如隐藏指令、敏感文件引用、隐藏 Unicode、跨服务器工具遮蔽；技能文档同样采用首次使用信任，逐文件摘要、漂移需人工批准。
- 下游授权：对受 OAuth 保护的远程服务器，gridctl 作为 OAuth 客户端，一次浏览器登录服务所有已连接客户端，令牌加密存储并自动刷新。
- 作用域变量交付：密钥与环境配置存放在变量存储中（锁定后静态加密），stack.yaml 中声明无值前置条件，可检查每个键的消费位置而不暴露值；GRIDCTL_ 开头及 OP_CONNECT_TOKEN、OP_SERVICE_ACCOUNT_TOKEN 为控制平面保留，不能交付给工作负载。
- 实时工具调用：无需启动守护进程即可在选定的运行网关上搜索和调用工具。
- 出站 A2A（实验性）：在 a2a: 下声明远程 Agent Card 并启用 experimental.a2a，向 MCP 客户端暴露 A2A 1.0/0.3 JSON-RPC 的 send、task-get、task-cancel 及咨询技能工具；默认关闭。
- 生成式 Python 容器：无需维护 Dockerfile 即可构建精确的公共 PyPI 发布版或来自 git、本地目录的打包 Python 项目；生成镜像使用固定的 Python 与 uv 基础，以非 root 用户运行。
使用方式
安装器把最新发布版安装到 ~/.local/bin/gridctl；Homebrew、预构建二进制、源码构建、容器运行时设置等详见安装指南。安装器校验 SHA256 而非发布来源，建议先按 Release Verification 验证再解压或安装。需要 Docker 或 Podman，首次构建需要访问 PyPI 的网络。gridctl init 生成起始 stack.yaml，但该脚手架不是经过验证的工具服务器。gridctl link 检测客户端并让用户选择；显式命令如 gridctl link claude-code 在客户端未安装时以 1 退出。默认 apply 监听 8180 端口，Web UI 位于 http://localhost:8180，仅用于查看，不是调用路径。网关认证与监听安全设置为仅重启生效，reload 会拒绝安全变更。
限制
Gridctl 不负责智能体的规划或模型循环；容器观测需要受支持的 Linux 守护进程环境；A2A 适配器默认关闭且为实验性，任务与上下文句柄为 bearer 密钥，24 小时后过期，适配器替换或重启即失效；工具面控制中 groups 与自声明客户端选择器不是已认证身份；导出的 stack 文件可能仍含凭据，分享前需自行审查。
