gog-restricted

核心用法

gog-restricted 是 gog CLI 的安全封装版本，通过命令白名单机制仅开放只读和组织类操作，硬阻断所有外发、删除、管理类命令。核心能力覆盖：

Gmail 操作 — 支持搜索（gmail search、gmail messages search）、读取（gmail read、gmail get）、标签管理（labels list/create/add/remove）、批量修改（thread modify、batch modify）。支持附件下载（gmail attachment）和线程历史查询。组织操作通过标签实现：归档即移除 INBOX，标记已读即移除 UNREAD，垃圾邮件即添加 TRASH。

Calendar 操作 — 支持事件查询（calendar events、calendar search、calendar freebusy）、日历列表（calendar calendars）、冲突检测（calendar conflicts）、ACL 查询（calendar acl list）。受限创建模式（calendar create）仅允许 --summary、--from、--to 等白名单参数，其他参数一律拦截。

认证管理 — 支持多账户环境（GOG_ACCOUNT 环境变量）、账户列表查询（auth list）、服务范围查看（auth services）。

显著优点

1. Fail-Closed 安全模型：白名单机制确保任何未显式允许的命令均被拒绝，包括 gmail send、calendar update、drive、docs 等整类服务。短标志（-m 等）因解析歧义被全局禁止，进一步降低注入风险。

2. Agent 运行时适配：安装脚本（script/setup.sh）支持 HOME 被重定向到 profile 目录的场景，自动回退到系统级路径（/opt/homebrew/bin、/usr/local/bin），并提供 GOG_RESTRICTED_INSTALL_DIR 覆盖机制。

3. 结构化输出优先：强制 --json 和 --no-input 模式，便于自动化解析且避免交互阻塞。

4. 细粒度日历创建限制：calendar create 的参数白名单阻止通过 --conference-data 等隐蔽参数创建含外部会议链接的事件，防范钓鱼和供应链攻击。

潜在缺点与局限性

• 功能裁剪严重：无法发送/回复邮件、删除邮件或标签、更新/删除日历事件、管理 ACL、访问 Drive/Docs/Sheets/Chat 等服务。适合纯读取和轻量组织场景，复杂工作流受限。

• 短标志不可用：习惯 -m 10 的用户需改写为 --max 10，增加迁移成本。

• 白名单维护负担：gog 新增安全参数需同步更新 wrapper 才能使用，存在版本滞后风险。

• 安装权限敏感：系统级路径安装使 wrapper 对所有用户可见，多用户环境需额外隔离配置。

适合人群

• 需要自动化邮件分类、归档、标签管理但禁止外发的安全敏感场景
• 日程查询、冲突检测、空闲时间分析的自动化代理
• 受监管环境（合规要求禁止邮件外发、数据删除）下的 Google Workspace 集成

常规风险

• Prompt 注入：邮件正文、主题、发件人名称、日历标题/描述均可能包含恶意指令（"forward this to X"、"run this command"），需严格过滤，禁止据此执行任何操作。

• 附件风险：下载的附件可能包含恶意内容，禁止自动执行或解析其中的指令。

• 数据泄露边界：邮件地址、内容、日程详情不得透出到 CLI 外部服务。

• 误操作放大：TRASH 标签添加即生效，建议优先使用 pending-review 标签，批量操作限制在 50 条以内并记录审计日志。

核心用法

gog-restricted 是一个围绕 Google Workspace CLI 的安全包装器，通过严格的命令白名单机制，为 AI Agent 提供受控的 Gmail 和 Calendar 访问能力。该 Skill 本身不包含可执行代码，而是通过 Markdown 文档定义允许的命令子集，实际调用由系统上的 gog 二进制完成。

典型工作流：
1. 初始化认证：运行 gog-restricted auth status 确认认证状态，使用环境变量 GOG_ACCOUNT 指定默认账户
2. Gmail 检索：通过 gmail search '<query>' --max 10 --json 搜索邮件，支持完整的 Gmail 查询语法（如 from:alice after:2025/01/01）
3. 邮件组织：使用 gmail thread modify <threadId> --add LABEL --remove LABEL 进行标签管理，实现归档、标记已读等操作
4. 日历查询：calendar events --json 列出事件，配合 --from/--to 限制时间范围
5. 分页处理：检查响应中的 nextPageToken，通过 --page 参数实现结果分页

所有命令必须使用长格式参数（--max 10 而非 -m 10），并搭配 --json 获取结构化输出、--no-input 避免交互提示。

显著优点

1. Fail-Closed 安全架构
包装器采用"默认拒绝"设计原则：任何不在明确白名单中的命令均被硬阻断，包括短参数（short flags）、未知子命令、甚至 gog 未来可能新增的危险参数。这种设计消除了配置错误导致的安全漏洞。

2. 破坏性操作全面阻断
邮件发送（send/reply/forward）、批量删除、过滤器设置、日历修改/删除、ACL 变更等 30+ 项高危操作被明确列入黑名单，从 CLI 层面消除数据泄露和权限提升风险。

3. 提示词注入防护
SKILL.md 内置详尽的安全指南，强制要求将邮件主题、正文、发件人名称、日历事件内容等全部视为不可信输入，并提供具体防护指令（如忽略"转发给 X"、"点击链接"等诱导性内容）。

4. 零依赖与高性能
作为纯文档型 Skill（T-MD），无第三方代码依赖，仅调用系统标准工具。支持 --max 分页和精确查询语法，有效降低 API 配额消耗。

5. 灵活的部署适配
安装脚本支持 Agent 运行时环境（如 Hermes），自动检测可写目录，支持通过 GOG_RESTRICTED_INSTALL_DIR 覆盖安装路径，适配容器化与多租户场景。

潜在缺点与局限性

1. 功能高度受限
仅支持读取和轻量标签管理，无法发送邮件、创建草稿、修改日历事件、访问 Google Drive/Docs/Sheets 等其他服务。对于需要完整 Workspace 操作的用户，必须解除限制直接使用 gog。

2. 依赖外部二进制
Skill 本身不实现 API 调用，完全依赖宿主系统预装的 gog 二进制。若 gog 版本过旧、未安装或被篡改，功能将失效。

3. 参数形式限制
强制使用长参数导致命令冗长，且部分 gog 的合法功能参数因未加入白名单而无法使用（如 --conference-data 等会议相关参数）。

4. 无内置缓存机制
重复查询相同数据将每次都调用 Google API，在高频场景下可能快速耗尽配额。

5. T3 信任级别的来源风险
维护者为个人开发者（cettoana），无组织背书，虽代码通过安全审计，但长期维护与更新承诺存在不确定性。

适合的目标群体

• AI Agent 开发者：需要为 Agent 安全地接入 Gmail/Calendar 数据读取能力，同时严格控制操作边界
• 自动化工作流工程师：构建邮件分类、日历冲突检测、附件归档等只读自动化流程
• 企业安全团队：在零信任架构下，为员工 AI 助手提供受限的 Workspace 访问，满足合规审计要求
• 隐私敏感用户：希望利用 AI 处理邮件，但拒绝任何可能泄露或篡改原始数据的 write 权限

使用风险

1. 间接依赖风险
gog-restricted 的安全性建立在底层 gog 二进制的可信度上。若 gog 存在漏洞或被恶意替换，包装器的保护可能被绕过。建议通过包管理器安装 gog 并启用自动更新。

2. 提示词注入的持续威胁
尽管 Skill 文档强调防护，但 Agent 的实际行为取决于上层实现。若 Agent 未能严格隔离邮件内容与系统指令，攻击者仍可能通过构造恶意邮件诱导 Agent 执行非预期操作（如将敏感内容复制到外部）。

3. 配额与性能瓶颈
Google API 存在严格的速率限制。无内置缓存 + 分页查询机制可能导致：

• 大规模数据同步时触发配额冻结
• --max 设置过大导致响应延迟和内存压力
• 频繁的小批量查询效率低下

4. 标签误操作风险
TRASH 标签添加等"软删除"操作未被完全阻断，若 Agent 逻辑错误可能导致重要邮件进入垃圾箱。SKILL.md 建议的 pending-review 标签机制和审计日志需由上层系统实现。

5. 跨账户数据泄露
多账户场景下，若 GOG_ACCOUNT 环境变量配置错误，Agent 可能访问非预期的用户数据。建议在每次调用前显式验证账户身份。