knowledge-work-plugins 中的 Gmail 合同附件检索:contract-review 技能的取件实战指南

原创2026-09-14 11:01:331,696 阅读
文章标签:人工智能AI 技能插件系统提示工程企业应用协同办公

knowledge-work-plugins 中的 Gmail 合同附件检索:contract-review 技能的取件实战指南

本文聚焦 knowledge-work-plugins 仓库中 small-business 插件 contract-review 技能的核心取件环节——通过 Gmail MCP 连接器在近期邮件中定位并获取合同附件。读完本文,你将掌握 search_threads 检索查询的构造方法、候选确认与下载流程、连接失败时的回退话术,以及该流程在整个合同评审工作流中的准确定位与边界约束。

一、gmail-fetch 在 contract-review 工作流中的位置

在 small-business 插件中,contract-review 技能 面向没有专职法务的中小企业主(SMB),提供 NDA、MSA、供应商合同等协议的轻量评审。其工作流的第一步是"获取合同(Get the contract)",共三个来源,按优先级排列:

  1. Gmail:在近期邮件中检索带附件的合同邮件(即本指南主题,参见 reference/gmail-fetch.md);
  2. DocuSign:按信封 ID 获取,或检索等待签署的草稿(参见 reference/docusign-fetch.md);
  3. 本地文件或粘贴文本:通过 Read 工具读取 PDF(10 页以上文件使用 pages 参数分块读取)或 DOCX。

也就是说,Gmail 取件是 contract-review 的首选数据来源。它在插件体系中的定位也可从 small-business/README.md 的说明中得到印证:Gmail 被列为合同评审的挂接连接器(contract-review 技能页注明"Required: -- (works with file upload),Optional: Gmail, DocuSign"),说明即使 Gmail 不可用,技能仍可通过文件上传退化为可用状态,但连接 Gmail 能显著减少人工转发附件的工作量。

二、用 search_threads 构造合同检索查询

gmail-fetch.md 的核心操作是使用 Gmail MCP 连接器的 search_threads 工具,配以一个针对近期带附件邮件的查询。原文档给出的查询原文为:

Query: "has:attachment (contract OR agreement OR NDA OR MSA OR SOW) newer_than:14d"

查询语法拆解

  • has:attachment:Gmail 搜索运算符,仅返回带附件的邮件线程。这是整个查询的过滤基石,把范围直接收敛到可能包含合同文件的邮件;
  • (contract OR agreement OR NDA OR MSA OR SOW):括号分组 + OR 逻辑,匹配主题或正文中含任一合同类型关键词的邮件。五个关键词覆盖了中小企业最常见的协议类型:
    • contract(合同)——泛指;
    • agreement(协议)——正式协议标题常用词;
    • NDA(保密协议);
    • MSA(主服务协议);
    • SOW(工作说明书)。
  • newer_than:14d:Gmail 相对时间运算符,限定最近 14 天的邮件,避免检索到过时、已失效的合同版本。

三个条件同时成立(AND 语义),即"最近 14 天内、带附件、命中合同关键词"的邮件线程。

调参建议

  • 若 14 天窗口内没有结果,可放宽为 newer_than:30d 或 newer_than:90d,但需注意越旧的合同越可能是已签署或已过期的版本,评审价值降低;
  • 若命中过多(如咨询公司客户多、附件邮件量大),可追加发件人限定,例如 from:vendor@example.com,或收紧时间窗口为 newer_than:7d;
  • 若已知合同类型,可直接用单一关键词(如仅 MSA)代替五个词的 OR 组,提高精确度。

search_threads 并非 contract-review 独有。在 business-pulse/reference/data_sources.md 中,search_threads 同样被用于检索"紧急线程(is:important OR is:starred)"、"客户升级(escalation/complaint/cancel 等关键词)"、"时间敏感请求(is:unread + deadline/ASAP/today)",可见它是本插件各技能共用的 Gmail 检索入口,其返回结果天然是**线程(thread)**维度而非单封邮件维度。

三、拿到检索结果后的三步处理流程

原文档明确要求按以下顺序处理结果,不能直接下载附件:

  1. 先列出候选:若多个候选匹配,输出一个简短列表,包含**主题(subject)、发件人(sender)、日期(date)**三项即可,避免信息过载;
  2. 请用户确认:在下载前先询问用户确认是哪一封。这是本插件"每个工作流在采取行动前都会暂停,未经你同意不执行任何操作"设计原则在取件环节的具体体现(见 small-business/README.md 中的设计说明);
  3. 获取完整线程并读取附件:用户确认后,用 get_thread 拉取完整线程(而非单封邮件),因为合同正文、条款修改、谈判往来通常分散在同一线程的多封邮件中;随后定位附件并读取。

第 3 步与 contract-review/SKILL.md 中的硬性要求相衔接:"阅读完整文档后再分析,危险条款经常藏在文末的附件(exhibits)和附表(schedules)中"。这一点在 reference/gotchas.md 中有专门的反面案例:40 页的 MSA 中,IP 归属与责任上限条款位于第 28 页起的 Schedule A–D,若只读取前 10 页,会产出一份"看似干净"实则漏掉关键条款的评审结论。因此 get_thread 之后务必确认附件被完整读取,而不是只读邮件正文。

四、回退方案:连接失败或无匹配附件时

Gmail 可能因未连接、授权过期或确实没有匹配邮件而不可用。gmail-fetch.md 给出的标准回退话术为:

"I didn't find a recent contract attachment in Gmail — can you forward it or attach the file directly?"

这句话同时做了两件事:透明说明检索结果(没有找到),给出替代路径(转发邮件或直接上传文件)。这与 contract-review 的三来源设计一致——退回到"本地文件或粘贴文本"路径后,技能依然完整可用,符合 small-business/README.md 中"Required: -- (works with file upload)"的降级能力说明。

值得注意的是,Gmail 授权不稳定在本插件中属于已知问题:business-pulse 技能的 reference/gotchas.md 记录了"Gmail auth is intermittently flaky(授权间歇性失效)"的故障模式,并建议在授权失败时静默降级、在附录中注明"Gmail unavailable",而不是中断整个工作流。contract-review 的 Gmail 取件同样适用这一降级思路。

五、禁止事项:评审工作流的边界红线

gmail-fetch.md 用"What NOT to do"明确了取件环节的行为边界:

  • 不得读取与合同无关的邮件——不做笼统的收件箱通读(no general inbox trawl)。这与合同评审"只取所需"的隐私与效率原则一致;同理,search_threads 的查询必须始终以 has:attachment + 合同关键词锚定,防止范围漂移;
  • 评审过程中不得发送任何回复或草拟邮件(Do not send any reply or draft email during the review workflow)——contract-review 是纯评审型技能,产出物是评审摘要与 redline DOCX,不是邮件交互。即便用户希望向对方发送修改意见,也必须等到评审完成后、导出 redline 文档并经用户明确确认,才可能进入发送环节(参见 contract-review/SKILL.md 的 Approval gates:"未经用户明确确认,绝不将 redline DOCX 发送给对方")。

这两个禁令与 DocuSign 来源的约束(reference/docusign-fetch.md 中"绝不调用 triggerWorkflow、updateEnvelope、createEnvelope,本技能只读")共同构成 contract-review 的"只读评审"设计哲学:获取、阅读、分析、导出,但不对外产生任何动作。

六、取件到评审的完整链路

将本指南放入 contract-review 全流程看,Gmail 取件是第一步"Get the contract"的一部分,后续链路为:

  1. 取件:Gmail 检索 → 确认 → get_thread 读取附件(本文主题);或 DocuSign 拉取信封;或本地文件/粘贴;
  2. 通读:完整读取文档(含 exhibits/schedules),判断合同类型(NDA/MSA/SOW/SaaS 订阅/咨询/分包/供应商)与缔约双方身份,识别是否为大公司模板(模板通常单方有利,对方预期被讨价还价);
  3. 八类风险分析:付款条款与现金流、责任与赔偿、终止与退出、知识产权、范围与变更管理、竞业与排他、保密与数据、运营问题——按典型风险严重度排序;
  4. 分级呈现:🔴 红色(签署前必须反击)、🟡 黄色(可谈判)、🟢 关键条款提示、📋 合同摘要、💡 谈判行动手册——每条均引用条款原文而非转述;
  5. 导出 redline DOCX:用 docx 技能生成保留原结构、删除线标记删除、下划线标记新增、带封面摘要的 Word 文档(完整输出示例见 reference/examples/flagged-summary-saas.md)。

在上述全链路中,本指南对应的取件阶段虽短,却决定了后续分析能否开始、分析对象是否准确——检索查询写得准,才不至于漏掉或拿错合同版本。

七、小结与自查清单

Gmail 取件的完整操作要点可浓缩为一张清单:

步骤 动作 关键参数/话术
1. 检索 search_threads has:attachment (contract OR agreement OR NDA OR MSA OR SOW) newer_than:14d
2. 列出 主题 + 发件人 + 日期 多候选时先出短列表
3. 确认 请用户确认目标 不跳过、不擅自下载
4. 拉取 get_thread + 读附件 读取完整线程与完整文档(含附表)
5. 回退 未连接/无匹配 "I didn't find a recent contract attachment in Gmail — can you forward it or attach the file directly?"
6. 边界 不读无关邮件、不发送/草拟任何邮件 只读评审,见 SKILL.md Approval gates

最后再次强调评审纪律(SKILL.md 中 Approval gates 的原文要点):输出不得被描述为法律意见;红色旗帜事项务必建议用户咨询律师;引用条款必须使用原文;既要标记"存在的不利条款",也要标记"缺失的标准条款"(没有责任上限、没有变更单流程的合同往往比条款不利更危险);不标记市场标准 boilerplate;并根据双方实力对比(Fortune 500 采购模板 vs 初创协议)调整建议语气。Gmail 取件只是把合同送进这个评审漏斗的第一步,而这一步的严谨程度,决定了后续所有风险判断是否建立在正确的文档之上。

登录后查看全文
knowledge-work-plugins