尧图网站建设 
GE Demo Generator 外部样例文件生成与 Google Drive 存储机制解析跨源对账演示的数据载体设计与部署上传链路【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai本文基于search/gemini-enterprise/ge-demo-generator/skills/ge-demo-generator/references/external_files_and_drive.md展开并结合该 Skill 的生成脚本、部署脚本与测试门禁进行源码级印证。文章聚焦 GE Demo Generator 如何为 Gemini Enterprise Agent 演示合成数据库之外的外部样例文件PDF 审计报告、Excel 供应商台账、模拟扫描单据以及这些文件如何以部署账户的gcloud令牌为唯一通道进入其个人 Google Drive。读完本文你将掌握三类外部文件的规格与生成实现、跨源异常播种策略、Workspace MCP 的检索前提以及账户所有权、权限与多账户访问的完整处理模型。GE Demo Generatorv2.14.4是一个端到端生成完整、领域定制化 Gemini Enterprise 演示环境的 Skill它合成真实感的外部样例数据文件PDF 报告、Excel 台账、模拟运营扫描件这些文件故意放在演示数据库之外让 Agent 有可以对账的对象从而支撑跨源推理演示、文档 OCR/扫描工作流以及 Google Workspace MCP 的直接探索。这类文件最终落在哪里是整个流程中最容易误解的部分因此文档在最前面就给出了结论它们总是在本地生成并暂存到gs://$GCS_BUCKET_NAME/部署时由执行部署的账户通过 Drive v3 REST API使用该机器自己的gcloud访问令牌上传到该账户的 Google Drive。上传是进入 Drive 的唯一路径当它没有运行时——令牌缺少 Drive scope或设置了SKIP_DRIVE_UPLOAD1——这些文档就完全没有 Drive 副本部署完成横幅会说明原因并给出修复命令。已部署的 Agent 无法自行创建 Drive 副本一次部署不能写入别人的 DriveSKILL.md 的 Phase 3 与 §5 对此有完整说明。1. 为什么需要外部文件跨源对账演示的设计动机演示数据库BigQuery 表 Firestore 集合承载的是企业系统内数据但真实的业务对账场景里决策者手里还有大量来自外部对等方的文档对方寄来的审计报告、供应商台账、纸质运单扫描件。GE Demo Generator 生成这些文件的目的就是让 Agent 面对一个和现实一致的问题——系统里的数字和外部文档里的数字对得上吗这也对应三条演示能力线跨源推理Cross-Source ReasoningAgent 必须同时查询内部表与阅读外部文档才能回答高层级战略问题对应演示剧本中的Prompt 3 (Cross-Source WOW Moment)文档 OCR / 扫描工作流Document OCR/Scanning Workflows模拟扫描件触发多模态视觉理解与单据处理Google Workspace MCP 探索Direct Workspace MCP Exploration当enableWorkspaceMcp: true时Agent 可以直接在已登录用户的 Drive 中搜索这些文件。文件与数据库的绑定关系在 Phase 2 的演示架构简报Brief §3 External Sample Files Cross-Source Lineage中就要逐行写清每个外部文件对应哪张表、以哪个外键列 JOIN、带有多大比例的刻意偏差。文档强调一条只说与订单相关的血缘行不是设计——外部文件的价值恰恰在于只有同时读文档 查表才能回答的问题而这要求键必须对齐70% 外键匹配、5-15% 审计偏差。2. 三类外部样例文件的规格与生成实现原文档 §1 用一张规格表定义了三种文件类型这是演示真实感的基础文件类型格式/扩展名规格与真实感要求演示中的角色审计 / 对账报告PDF.pdf多章节业务报告至少 1,500 字符含 Executive Summary、Background、Table Data、图表占位/图形以及特定交易 ID相对 BigQuery 表播种 5-20% 的刻意偏差触发Prompt 3跨源 WOW Moment运营供应商台账Excel.xlsx复合工作簿报告标题、KPI 摘要卡片、40-80 行详细交易记录含单位、货币格式与 FK 引用70% ID 匹配支持高量级交叉引用与基于 JOIN 的对账模拟运营文档JPEG.jpg用gemini-3.1-flash-image生成的采购订单/交货单扫描件含真实感手写墨迹注释、公司印章、页眉和行项目触发 OCR / 多模态提取与(J) Dynamic Multi-Entity Batch Editor工作流生成脚本 generate_and_upload_external_files.py 中三类文件各有独立的生成函数且都带有保底设计PDFgenerate_pdfL60-138基于 reportlab注册日文 CID 字体HeiseiKakuGo-W5/HeiseiMin-W3以保证 CJK 字符不出现豆腐块tofu按sections渲染多章节正文discrepancy章节渲染带网格样式的对账差异表格。若 reportlab 抛异常会降级写出同名 Markdown 文件而不是让整个流程失败。Excelgenerate_excelL289-351基于 openpyxl工作簿名为External_Ledger含标题行、KPI 摘要行[Executive Summary KPIs]、表头填充与细边框并对数值列右对齐、按内容自适应列宽。模拟扫描件generate_document_imageL162-287第一优先调用 Vertex AI Agent Platform 的图像生成模型依次尝试gemini-3.1-flash-image、gemini-3-pro-imageresponse_modalities[IMAGE]提示词区分常规单据routine与异常单据exception/discrepancy两种模板包含红色公司印章APPROVED、手写批注、NEEDS REVIEW / PENDING APPROVAL审核章、加急说明文字等真实感要素当图像生成失败或PROJECT_ID缺失时降级为 Pillow 渲染一张 1000x1350 的纸面俯拍示意图含 Noto CJK 字体探测与红色椭圆印章轮廓。脚本输出的实际文件名main()L688-691为domain_audit_report.pdf、domain_external_ledger.xlsx、domain_simulated_order_task1.jpg、domain_simulated_order_task2_discrepancy.jpg域名中的.替换为_原文档 §3 中以handwritten_order_1.jpg/handwritten_order_2.jpg指代后两张扫描件两者对应同一批产物。3. 跨源绑定与异常播种让演示产生WOW Moment外部文件如果只是一堆格式正确的文档演示就没有悬念。原文档 §2 给出了三层设计确保演示产生令人印象深刻的瞬间逻辑键对称Logical Key Symmetry外部 PDF 与 Excel 中引用的主键如order_id、lot_id、invoice_id必须真实存在于 BigQuery 表中。这是跨源可对账的前提——没有共享键Agent 就无从交叉引用。刻意偏差Intentional Variance / Audit Discrepancy外部文件中有 2-4 条特定记录的值与系统略有不同例如实收数量 1,050 vs 系统期望 1,200或状态存在偏差。默认示例中PDF 差异表内置了REF-0001 → 1,200 vs 1,050 (mismatch)、REF-0002 → 850 vs 850 (match)这类对照行脚本 L728-737Excel 默认 50 行数据中则有 6 行被标记为FLAGGED_DISCREPANCYL754-763。自主交叉引用Autonomous Cross-Referencing面对高层级战略问题Prompt 3时Agent 会自主查询内部表并与外部 Drive 文件比对从而发现异常——演示脚本不需要告诉它去打开外部报告。数值粒度的约定贯穿整个 Skill外部文件与表之间 70% 外键匹配、5-15% 审计偏差SKILL.md Brief §3。差异不能太多否则对账变成数字全对不上也不能太少否则没有戏剧性这正是external_files_spec.json中discrepancy字段要精确定制的内容。4. 生成与上传的命令行流程uv 临时依赖 spec 文件原文档 §3 给出了 Phase 3 中的实际执行命令。它用uv run --no-project临时装载openpyxl、reportlab、pillow三个依赖不污染当前环境# 1. 本地生成 PDF 与 Excel 文件 uv run --no-project \ --with openpyxl3.1.0,4.0.0 \ --with reportlab4.0.0,6.0.0 \ --with pillow10.0.0,13.0.0 \ python3 scripts/generate_and_upload_external_files.py \ --domain $DOMAIN \ --company $COMPANY_NAME \ --suffix $SUFFIX \ --outdir ./external_files \ --spec-file ./data/external_files_spec.json参数含义脚本main()L669-683 的 argparse 定义参数默认值说明--domaindemo.example.com客户域名用于生成文件名前缀--companyDemo Company公司名进入 PDF/Excel/扫描件内容与 Drive 文件夹名--suffix1234唯一演示后缀Phase 3 用date %s \| tail -c 5生成--outdir./external_files本地输出目录--spec-file空本次演示外部文件的 JSON 内容描述--spec-file承载本次演示自己的内容是真实感演示的必需品。原文档强调其 JSON 结构如下所有内容都用演示的语言与行业领域书写{ style: {handwriting_language: ..., routine_doc_kind: ..., exception_doc_kind: ..., location: ..., approval_seal: ..., review_stamp: ..., urgent_note: ...}, pdf: {title: ..., sections: [{heading: ..., content: ...}], discrepancy: {heading: ..., table_data: [[...], ...]}}, excel: {title: ..., kpis: [{label: ..., value: ...}], headers: [...], rows: [[...], ...]}, scans: [{title: ..., doc_no: ..., date: ..., headers: [...], rows: [[...], ...], is_discrepancy: false}, {...}] }其中style直接喂给扫描件生成提示词DEFAULT_DOC_STYLE提供语言与行业中立的默认措辞pdf.sections与pdf.discrepancy驱动 PDF 正文与差异表excel.kpis/headers/rows驱动工作簿scans数组按顺序对应两张扫描件is_discrepancy决定走常规还是异常提示词模板。脚本本身只内置通用占位内容Counterparty A、REF-0101绝不把单一客户的内容硬编码进去——SKILL.md 的 Phase 3 也明确要求setup_and_deploy.sh的 Job 1.5L803-840在部署时会用当前data/external_files_spec.json重新执行一遍该脚本若无 spec 文件则会用占位内容覆盖 Phase 3 写好的文档导致跨源提示词没有可交叉引用的东西。上传完成后生成 4 个文件文件夹GE Demo - Company Name (Suffix)文件domain_audit_report.pdf→https://drive.google.com/file/d/PDF_ID/viewdomain_external_ledger.xlsx→https://drive.google.com/file/d/XLSX_ID/viewhandwritten_order_1.jpg→https://drive.google.com/file/d/IMG1_ID/viewhandwritten_order_2.jpg→https://drive.google.com/file/d/IMG2_ID/view上传走 Drive v3 REST API认证用的是gcloud auth print-access-token——无需安装任何额外 CLI文件夹归执行部署的账户所有重复部署会复用同名文件夹而非再建一个。上传结果写入external_files/drive_upload_summary.json脚本 L813-816供部署横幅与测试读取。5. Google Workspace MCPAgent 如何看到这些文件当enableWorkspaceMcp: true时enableWorkspaceAuth单独开启也适用第 1 点Agent 以--authorization-id注册进 Gemini EnterpriseAgent 直接获得Google Drive MCP与Google Sheets MCP工具集Agent 可以直接搜索用户 Drive 文件夹中的这些文件例如Search Google Drive for the latest supplier audit reportRead the reconciliation ledger from Google Sheets and compare with operational tables但原文档 §4 明确了一个关键的前置依赖这两个提示词只能找到已登录用户Drive 里可见的内容因此它们依赖两件事同时成立——部署时上传确实运行过、演示由执行部署的那个账户驱动。只要其中一条不成立这两个提示词就会返回空结果且之后没有任何机制能补救所以要在承诺 Drive 步骤之前先检查完成横幅并给观众提供 Cloud Storage 链接。Agent 的系统指令也被告知同样的事实因此它会回答文档在云存储中而不是给出一个它无法执行的导入。需要留意的是enableWorkspaceMcp在 SKILL.md 的选项表中被标注为Advanced, rarely usedWorkspace MCP 服务器处于 Developer Preview项目必须先行 allowlist否则每次 Workspace 调用都会 403。这与enableWorkspaceAuth用户 OAuth 直通是分开的两个开关。6. 账户所有权模型一个身份贯穿始终原文档 §5 的核心论断是只有一个身份在起作用——gcloud当前登录的那个账户。它拥有项目、执行部署并且自 v2.13.0 起拥有 Drive 文件夹因为上传是携带该账户自己访问令牌的 Drive v3 REST 调用。没有第二个 CLI、没有第二个 Drive、也不需要与部署目标共享任何东西——因为部署目标本身就是所有者。这解决了历史版本的一大类故障直到 v2.11.x上传用的是以操作员身份认证的内部gdriveCLI文件夹归操作员所有部署目标需要靠分享链接访问。两个原因导致其被移除一是该二进制是 Google 内部工具无法随 Skill 的公开副本分发二是google.com→ 客户域名的跨域分享经常被策略拒绝导致目标拿到一个 404 的链接。文件夹归部署账户所有同时消除了这两个问题脚本 L531-542 的注释有同样说明。6.1 Drive scope 是唯一的前置条件也是唯一常见的失败点普通的gcloud auth login只授予cloud-platform不包含 Drive scope因此 Drive 会返回403 ACCESS_TOKEN_SCOPE_INSUFFICIENT。脚本的get_drive_identity()L399-424以一次GET drive/v3/about?fieldsuser完成预检一次调用同时解析出令牌身份与 scope并把 403 翻译成可执行的修复命令。由于 Agent IDE 终端和远程开发机通常没有本地浏览器可交接必须使用gcloud auth login --enable-gdrive-access --no-launch-browser情形行为令牌带 Drive scope创建/复用GE Demo - Company (Suffix)上传四个文档文件夹归部署账户所有令牌无 Drive scope或根本没有令牌跳过上传横幅打印上面的重新登录命令SKIP_DRIVE_UPLOAD1主动跳过上传同样的预检也出现在 SKILL.md 的 Phase 2写演示简报之前用curl探测同一端点得到DRIVE_OK200或非 200并据此决定 Brief §3/§5 中写哪一行——是上传到${GCP_ACCOUNT}的 Google Drive还是没有 Google Drive 副本。这是要在简报阶段就讲清的事实而不是部署时才发现的意外。6.2 上传按名称幂等重复部署不产生重复文件文件夹与文件都按名称查找复用。脚本drive_find_folder()L436-449在files.create之前先执行files.list查询条件为name folder and mimeType folder and trashed false and me in ownersme in owners不是装饰没有它别人分享给你的同名文件夹会赢得查找文档就会落进陌生人的 Drive。每个文档随后在文件夹内做同样的查找name file and folder id in parents and trashed falsedrive_find_child()L452-469若已存在则改为PATCH .../files/id?uploadTypemultipart而非再次POST。文档注明该行为已对照线上 API 验证连续两次运行只会留下 4 个文件而不是 8 个文件 id 不变、version 递增。保留 id 很重要——已经粘贴进演示脚本的链接在重新部署后依然有效。parents只在创建时可写所以更新请求只发送名称见drive_upload_file()L472-514 的注释。7. 链接共享尽力而为绝不阻塞文件夹创建后脚本会请求{type: anyone, role: reader}让观众无需逐个被添加就能打开链接。但很多组织禁止这种开放共享此时拒绝被记录为share_error写入external_files/drive_upload_summary.json横幅打印ℹ️ LINK SHARING OFF提示。这是一个没落地的便利功能而不是旧的故障状态——所有者永远可以打开文件夹演示照常进行。8. 跳过上传SKIP_DRIVE_UPLOAD1与没有 Drive 副本的恢复横幅SKIP_DRIVE_UPLOAD1完全跳过 Drive适用于机器上不该存放这些资产的场景。文档明确这是一笔交易而不是一个后备方案接受演示没有 Drive 副本的事实。该变量取代了旧的SKIP_HOST_DRIVE_UPLOAD——后者针对的是一个已不复存在的第二个身份。当上传被跳过时文档完好无损只是没有 Drive 文件夹它们位于./external_files/和gs://$GCS_BUCKET_NAME/。setup_and_deploy.sh在每一种模式下都会执行 GCS 暂存Job 侧 L1422-1423gcloud storage cp -r external_files/* gs://${GCS_BUCKET_NAME}/v2.9.0 之前这份拷贝只存在于 rag 分支里导致 MCP 模式演示完全没有 bucket。脚本读取external_files/drive_upload_summary.json中的upload_skipped_reason在 External Sample Files - NOT in Google Drive标题下打印代价是什么演示脚本中的 Drive/Sheets 步骤什么都找不到、如何修复gcloud auth login --enable-gdrive-access --no-launch-browser后重跑或手动上传./external_files/并分享。这个横幅就是全部恢复故事这是有意设计。原文档 §5.5 记录了 v2.10.0 曾试图从另一端堵上缺口Agent 在每轮对话的第一轮、未经请求地、用用户的 OAuth 令牌把文档复制进已登录用户的 Drive背后有 Firestore 声明、工作线程与等待预算。v2.11.0 全部删除——工具、自动运行、声明、AUTO_IMPORT_DEMO_FILES、DRIVE_FOLDER_URL理由有三按权重排序为什么删除细节它上传了错误的东西上传器取走gs://$GCS_BUCKET_NAME/根目录下的所有对象。在 rag 模式下根目录同时是 datastore 的语料库真实演示中是 13 个对象 / 103 MB 客户自己的手册而不是 4 个生成样本——被塞进终端用户的个人 Drive且未经任何人同意机制压过了功能本身跨实例、跨会话的幂等需要以令牌邮箱为键的 Firestore 声明、接管超时、垃圾桶文件夹复检和停放式通知渠道——约 390 行代码只为完成部署用几次 REST 调用就能做的事每一轮对话都在为它买单before-agent 回调在所有轮次运行第一轮会阻塞至多AUTO_IMPORT_WAIT_S8 秒等待复制完成——而这个预算只适合 4 个小文件现在 Agent 的系统指令与横幅表述一致文档存在于云存储中部署会把副本放进部署账户的 Drive若 Drive 搜索返回空Agent 必须如实说明而不是提供它无法完成的复制。仓库测试 test_external_files_wiring.py 的第四组检查专门锁死了这条回归防线RETIRED列表import_demo_files_to_my_drive、AUTO_IMPORT_DEMO_FILES、DRIVE_FOLDER_URL等 7 个名字不得以任何形式重新出现在tools.py、agent.py与setup_and_deploy.sh中DRIVE_FOLDER_URL也不得再传入 Cloud Run。9. 报告与访问指引每个目的地都是一个可点击的链接原文档 §5.6 强调文件的每一条路径最终都应落在读者能点击的链接上——裸的gs://URI 或文件夹名都不是链接。Drive仅当上传确实运行时Drive 所有者执行部署的账户链接共享组织允许时为Anyone with link (Reader)否则出现ℹ️ LINK SHARING OFF提示观众需要显式分享打开文件夹https://drive.google.com/drive/folders/FOLDER_ID单文件链接https://drive.google.com/file/d/FILE_ID/view⚠️多账户浏览器警告打开 Google Drive 链接前请务必将浏览器切换到所有者 Google 账户。若同时登录了多个 Google 账户用非所有者账户访问会以 Permission Denied (403/404) 失败。Cloud Storage始终存在因为暂存拷贝无条件执行️浏览 buckethttps://console.cloud.google.com/storage/browser/BUCKET?projectPROJECT_ID直接打开文件https://storage.cloud.google.com/BUCKET/OBJECT——该地址用storage.objects.get把对象提供给已登录浏览器因此是每个已上传文件最值得打印的链接控制台 URL 是对象名在报告时未知时的后备。在 setup_and_deploy.sh 中这些渲染由 Stage 4 横幅完成脚本用jq从drive_upload_summary.json解析folder_url、owner_account、upload_skipped_reason、uploaded_files、share_error、shared_permissionsL1740-1747据此分支渲染 Google Drive External Sample Files、 External Sample Files - NOT in Google Drive或 External Sample Files in Cloud Storage三个区块L1785-1833GCS_FILE_LINKS会为external_files/下每个非记账文件跳过drive_upload_summary.json与*.url.json生成一条https://storage.cloud.google.com/${GCS_BUCKET_NAME}/filename链接。10. 测试门禁四个事实被锁定在仓库里search/gemini-enterprise/ge-demo-generator/test_external_files_wiring.pyv2.13.0 引入把本文描述的四项事实变成了可执行的门禁防止未来版本悄悄破坏这些设计契约文档在每种模式下都暂存到 GCS——将 Job 1.5 的代码块从脚本中切片出来在桩gcloud/python3下分别以RAG_MODE0与RAG_MODE1运行断言出现buckets create gs://demo-docs与storage cp -r external_files/同时断言GCS_BUCKET_NAME通过CR_ENV_VARS传入容器。上传是 Drive v3 gcloud 令牌、无外部 CLI——断言源码含https://www.googleapis.com/drive/v3与gcloud auth print-access-token不含gdrive内部二进制的任何踪迹其路径曾泄露进公开副本且REAUTH_HINTgcloud auth login --enable-gdrive-access --no-launch-browser出现在脚本中share_error、SKIP_DRIVE_UPLOAD、upload_skipped_reason均被断言存在。每个目的地都被报告缺失的 Drive 副本被明确宣告——断言每个暂存文件有可打开的 https 链接、bucket 有控制台地址、横幅含${DRIVE_OWNER_ACCOUNT}与LINK SHARING OFF且 no Drive copy 分支会打印${DRIVE_SKIP_REASON}与修复命令。对话内导入保持已删除——RETIRED名字列表全部不得出现Drive 上传辅助函数必须留在 Workspace 门控之下其剩余消费者是save_deliverables_to_drivebefore-agent 回调不做任何 Drive 工作Agent 指令中必须存在文档在 cloud storage不要提议把它们复制进用户的Drive 这样的表述。结语GE Demo Generator 的外部样例文件链路是一套让演示既真实又可控的完整工程三类文件在本地合成PDF/Excel/扫描件含刻意播种的审计偏差以gcloud令牌为唯一凭据上传到部署账户自己的 Drive幂等、按名复用、链接共享尽力而为并在不可行时通过SKIP_DRIVE_UPLOAD与部署完成横幅给出诚实、可恢复的降级路径。贯穿始终的设计原则是进入 Drive 只有部署时一条通道Agent 永不代写横幅永远如实报告。相关的兄弟文档可继续深入datastore_connectors.md§2.3 给出了Discovery Engine 创建的 Drive 数据存储无法被 Agent 服务账号读取、也无法限定到文件夹的实证、deployment_and_iam.md完整.env键参考与 SKILL.mdPhase 2-7 的完整生命周期。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GE Demo Generator 外部样例文件生成与 Google Drive 存储机制解析：跨源对账演示的数据载体设计与部署上传链路
GE Demo Generator 外部样例文件生成与 Google Drive 存储机制解析跨源对账演示的数据载体设计与部署上传链路【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai本文基于search/gemini-enterprise/ge-demo-generator/skills/ge-demo-generator/references/external_files_and_drive.md展开并结合该 Skill 的生成脚本、部署脚本与测试门禁进行源码级印证。文章聚焦 GE Demo Generator 如何为 Gemini Enterprise Agent 演示合成数据库之外的外部样例文件PDF 审计报告、Excel 供应商台账、模拟扫描单据以及这些文件如何以部署账户的gcloud令牌为唯一通道进入其个人 Google Drive。读完本文你将掌握三类外部文件的规格与生成实现、跨源异常播种策略、Workspace MCP 的检索前提以及账户所有权、权限与多账户访问的完整处理模型。GE Demo Generatorv2.14.4是一个端到端生成完整、领域定制化 Gemini Enterprise 演示环境的 Skill它合成真实感的外部样例数据文件PDF 报告、Excel 台账、模拟运营扫描件这些文件故意放在演示数据库之外让 Agent 有可以对账的对象从而支撑跨源推理演示、文档 OCR/扫描工作流以及 Google Workspace MCP 的直接探索。这类文件最终落在哪里是整个流程中最容易误解的部分因此文档在最前面就给出了结论它们总是在本地生成并暂存到gs://$GCS_BUCKET_NAME/部署时由执行部署的账户通过 Drive v3 REST API使用该机器自己的gcloud访问令牌上传到该账户的 Google Drive。上传是进入 Drive 的唯一路径当它没有运行时——令牌缺少 Drive scope或设置了SKIP_DRIVE_UPLOAD1——这些文档就完全没有 Drive 副本部署完成横幅会说明原因并给出修复命令。已部署的 Agent 无法自行创建 Drive 副本一次部署不能写入别人的 DriveSKILL.md 的 Phase 3 与 §5 对此有完整说明。1. 为什么需要外部文件跨源对账演示的设计动机演示数据库BigQuery 表 Firestore 集合承载的是企业系统内数据但真实的业务对账场景里决策者手里还有大量来自外部对等方的文档对方寄来的审计报告、供应商台账、纸质运单扫描件。GE Demo Generator 生成这些文件的目的就是让 Agent 面对一个和现实一致的问题——系统里的数字和外部文档里的数字对得上吗这也对应三条演示能力线跨源推理Cross-Source ReasoningAgent 必须同时查询内部表与阅读外部文档才能回答高层级战略问题对应演示剧本中的Prompt 3 (Cross-Source WOW Moment)文档 OCR / 扫描工作流Document OCR/Scanning Workflows模拟扫描件触发多模态视觉理解与单据处理Google Workspace MCP 探索Direct Workspace MCP Exploration当enableWorkspaceMcp: true时Agent 可以直接在已登录用户的 Drive 中搜索这些文件。文件与数据库的绑定关系在 Phase 2 的演示架构简报Brief §3 External Sample Files Cross-Source Lineage中就要逐行写清每个外部文件对应哪张表、以哪个外键列 JOIN、带有多大比例的刻意偏差。文档强调一条只说与订单相关的血缘行不是设计——外部文件的价值恰恰在于只有同时读文档 查表才能回答的问题而这要求键必须对齐70% 外键匹配、5-15% 审计偏差。2. 三类外部样例文件的规格与生成实现原文档 §1 用一张规格表定义了三种文件类型这是演示真实感的基础文件类型格式/扩展名规格与真实感要求演示中的角色审计 / 对账报告PDF.pdf多章节业务报告至少 1,500 字符含 Executive Summary、Background、Table Data、图表占位/图形以及特定交易 ID相对 BigQuery 表播种 5-20% 的刻意偏差触发Prompt 3跨源 WOW Moment运营供应商台账Excel.xlsx复合工作簿报告标题、KPI 摘要卡片、40-80 行详细交易记录含单位、货币格式与 FK 引用70% ID 匹配支持高量级交叉引用与基于 JOIN 的对账模拟运营文档JPEG.jpg用gemini-3.1-flash-image生成的采购订单/交货单扫描件含真实感手写墨迹注释、公司印章、页眉和行项目触发 OCR / 多模态提取与(J) Dynamic Multi-Entity Batch Editor工作流生成脚本 generate_and_upload_external_files.py 中三类文件各有独立的生成函数且都带有保底设计PDFgenerate_pdfL60-138基于 reportlab注册日文 CID 字体HeiseiKakuGo-W5/HeiseiMin-W3以保证 CJK 字符不出现豆腐块tofu按sections渲染多章节正文discrepancy章节渲染带网格样式的对账差异表格。若 reportlab 抛异常会降级写出同名 Markdown 文件而不是让整个流程失败。Excelgenerate_excelL289-351基于 openpyxl工作簿名为External_Ledger含标题行、KPI 摘要行[Executive Summary KPIs]、表头填充与细边框并对数值列右对齐、按内容自适应列宽。模拟扫描件generate_document_imageL162-287第一优先调用 Vertex AI Agent Platform 的图像生成模型依次尝试gemini-3.1-flash-image、gemini-3-pro-imageresponse_modalities[IMAGE]提示词区分常规单据routine与异常单据exception/discrepancy两种模板包含红色公司印章APPROVED、手写批注、NEEDS REVIEW / PENDING APPROVAL审核章、加急说明文字等真实感要素当图像生成失败或PROJECT_ID缺失时降级为 Pillow 渲染一张 1000x1350 的纸面俯拍示意图含 Noto CJK 字体探测与红色椭圆印章轮廓。脚本输出的实际文件名main()L688-691为domain_audit_report.pdf、domain_external_ledger.xlsx、domain_simulated_order_task1.jpg、domain_simulated_order_task2_discrepancy.jpg域名中的.替换为_原文档 §3 中以handwritten_order_1.jpg/handwritten_order_2.jpg指代后两张扫描件两者对应同一批产物。3. 跨源绑定与异常播种让演示产生WOW Moment外部文件如果只是一堆格式正确的文档演示就没有悬念。原文档 §2 给出了三层设计确保演示产生令人印象深刻的瞬间逻辑键对称Logical Key Symmetry外部 PDF 与 Excel 中引用的主键如order_id、lot_id、invoice_id必须真实存在于 BigQuery 表中。这是跨源可对账的前提——没有共享键Agent 就无从交叉引用。刻意偏差Intentional Variance / Audit Discrepancy外部文件中有 2-4 条特定记录的值与系统略有不同例如实收数量 1,050 vs 系统期望 1,200或状态存在偏差。默认示例中PDF 差异表内置了REF-0001 → 1,200 vs 1,050 (mismatch)、REF-0002 → 850 vs 850 (match)这类对照行脚本 L728-737Excel 默认 50 行数据中则有 6 行被标记为FLAGGED_DISCREPANCYL754-763。自主交叉引用Autonomous Cross-Referencing面对高层级战略问题Prompt 3时Agent 会自主查询内部表并与外部 Drive 文件比对从而发现异常——演示脚本不需要告诉它去打开外部报告。数值粒度的约定贯穿整个 Skill外部文件与表之间 70% 外键匹配、5-15% 审计偏差SKILL.md Brief §3。差异不能太多否则对账变成数字全对不上也不能太少否则没有戏剧性这正是external_files_spec.json中discrepancy字段要精确定制的内容。4. 生成与上传的命令行流程uv 临时依赖 spec 文件原文档 §3 给出了 Phase 3 中的实际执行命令。它用uv run --no-project临时装载openpyxl、reportlab、pillow三个依赖不污染当前环境# 1. 本地生成 PDF 与 Excel 文件 uv run --no-project \ --with openpyxl3.1.0,4.0.0 \ --with reportlab4.0.0,6.0.0 \ --with pillow10.0.0,13.0.0 \ python3 scripts/generate_and_upload_external_files.py \ --domain $DOMAIN \ --company $COMPANY_NAME \ --suffix $SUFFIX \ --outdir ./external_files \ --spec-file ./data/external_files_spec.json参数含义脚本main()L669-683 的 argparse 定义参数默认值说明--domaindemo.example.com客户域名用于生成文件名前缀--companyDemo Company公司名进入 PDF/Excel/扫描件内容与 Drive 文件夹名--suffix1234唯一演示后缀Phase 3 用date %s \| tail -c 5生成--outdir./external_files本地输出目录--spec-file空本次演示外部文件的 JSON 内容描述--spec-file承载本次演示自己的内容是真实感演示的必需品。原文档强调其 JSON 结构如下所有内容都用演示的语言与行业领域书写{ style: {handwriting_language: ..., routine_doc_kind: ..., exception_doc_kind: ..., location: ..., approval_seal: ..., review_stamp: ..., urgent_note: ...}, pdf: {title: ..., sections: [{heading: ..., content: ...}], discrepancy: {heading: ..., table_data: [[...], ...]}}, excel: {title: ..., kpis: [{label: ..., value: ...}], headers: [...], rows: [[...], ...]}, scans: [{title: ..., doc_no: ..., date: ..., headers: [...], rows: [[...], ...], is_discrepancy: false}, {...}] }其中style直接喂给扫描件生成提示词DEFAULT_DOC_STYLE提供语言与行业中立的默认措辞pdf.sections与pdf.discrepancy驱动 PDF 正文与差异表excel.kpis/headers/rows驱动工作簿scans数组按顺序对应两张扫描件is_discrepancy决定走常规还是异常提示词模板。脚本本身只内置通用占位内容Counterparty A、REF-0101绝不把单一客户的内容硬编码进去——SKILL.md 的 Phase 3 也明确要求setup_and_deploy.sh的 Job 1.5L803-840在部署时会用当前data/external_files_spec.json重新执行一遍该脚本若无 spec 文件则会用占位内容覆盖 Phase 3 写好的文档导致跨源提示词没有可交叉引用的东西。上传完成后生成 4 个文件文件夹GE Demo - Company Name (Suffix)文件domain_audit_report.pdf→https://drive.google.com/file/d/PDF_ID/viewdomain_external_ledger.xlsx→https://drive.google.com/file/d/XLSX_ID/viewhandwritten_order_1.jpg→https://drive.google.com/file/d/IMG1_ID/viewhandwritten_order_2.jpg→https://drive.google.com/file/d/IMG2_ID/view上传走 Drive v3 REST API认证用的是gcloud auth print-access-token——无需安装任何额外 CLI文件夹归执行部署的账户所有重复部署会复用同名文件夹而非再建一个。上传结果写入external_files/drive_upload_summary.json脚本 L813-816供部署横幅与测试读取。5. Google Workspace MCPAgent 如何看到这些文件当enableWorkspaceMcp: true时enableWorkspaceAuth单独开启也适用第 1 点Agent 以--authorization-id注册进 Gemini EnterpriseAgent 直接获得Google Drive MCP与Google Sheets MCP工具集Agent 可以直接搜索用户 Drive 文件夹中的这些文件例如Search Google Drive for the latest supplier audit reportRead the reconciliation ledger from Google Sheets and compare with operational tables但原文档 §4 明确了一个关键的前置依赖这两个提示词只能找到已登录用户Drive 里可见的内容因此它们依赖两件事同时成立——部署时上传确实运行过、演示由执行部署的那个账户驱动。只要其中一条不成立这两个提示词就会返回空结果且之后没有任何机制能补救所以要在承诺 Drive 步骤之前先检查完成横幅并给观众提供 Cloud Storage 链接。Agent 的系统指令也被告知同样的事实因此它会回答文档在云存储中而不是给出一个它无法执行的导入。需要留意的是enableWorkspaceMcp在 SKILL.md 的选项表中被标注为Advanced, rarely usedWorkspace MCP 服务器处于 Developer Preview项目必须先行 allowlist否则每次 Workspace 调用都会 403。这与enableWorkspaceAuth用户 OAuth 直通是分开的两个开关。6. 账户所有权模型一个身份贯穿始终原文档 §5 的核心论断是只有一个身份在起作用——gcloud当前登录的那个账户。它拥有项目、执行部署并且自 v2.13.0 起拥有 Drive 文件夹因为上传是携带该账户自己访问令牌的 Drive v3 REST 调用。没有第二个 CLI、没有第二个 Drive、也不需要与部署目标共享任何东西——因为部署目标本身就是所有者。这解决了历史版本的一大类故障直到 v2.11.x上传用的是以操作员身份认证的内部gdriveCLI文件夹归操作员所有部署目标需要靠分享链接访问。两个原因导致其被移除一是该二进制是 Google 内部工具无法随 Skill 的公开副本分发二是google.com→ 客户域名的跨域分享经常被策略拒绝导致目标拿到一个 404 的链接。文件夹归部署账户所有同时消除了这两个问题脚本 L531-542 的注释有同样说明。6.1 Drive scope 是唯一的前置条件也是唯一常见的失败点普通的gcloud auth login只授予cloud-platform不包含 Drive scope因此 Drive 会返回403 ACCESS_TOKEN_SCOPE_INSUFFICIENT。脚本的get_drive_identity()L399-424以一次GET drive/v3/about?fieldsuser完成预检一次调用同时解析出令牌身份与 scope并把 403 翻译成可执行的修复命令。由于 Agent IDE 终端和远程开发机通常没有本地浏览器可交接必须使用gcloud auth login --enable-gdrive-access --no-launch-browser情形行为令牌带 Drive scope创建/复用GE Demo - Company (Suffix)上传四个文档文件夹归部署账户所有令牌无 Drive scope或根本没有令牌跳过上传横幅打印上面的重新登录命令SKIP_DRIVE_UPLOAD1主动跳过上传同样的预检也出现在 SKILL.md 的 Phase 2写演示简报之前用curl探测同一端点得到DRIVE_OK200或非 200并据此决定 Brief §3/§5 中写哪一行——是上传到${GCP_ACCOUNT}的 Google Drive还是没有 Google Drive 副本。这是要在简报阶段就讲清的事实而不是部署时才发现的意外。6.2 上传按名称幂等重复部署不产生重复文件文件夹与文件都按名称查找复用。脚本drive_find_folder()L436-449在files.create之前先执行files.list查询条件为name folder and mimeType folder and trashed false and me in ownersme in owners不是装饰没有它别人分享给你的同名文件夹会赢得查找文档就会落进陌生人的 Drive。每个文档随后在文件夹内做同样的查找name file and folder id in parents and trashed falsedrive_find_child()L452-469若已存在则改为PATCH .../files/id?uploadTypemultipart而非再次POST。文档注明该行为已对照线上 API 验证连续两次运行只会留下 4 个文件而不是 8 个文件 id 不变、version 递增。保留 id 很重要——已经粘贴进演示脚本的链接在重新部署后依然有效。parents只在创建时可写所以更新请求只发送名称见drive_upload_file()L472-514 的注释。7. 链接共享尽力而为绝不阻塞文件夹创建后脚本会请求{type: anyone, role: reader}让观众无需逐个被添加就能打开链接。但很多组织禁止这种开放共享此时拒绝被记录为share_error写入external_files/drive_upload_summary.json横幅打印ℹ️ LINK SHARING OFF提示。这是一个没落地的便利功能而不是旧的故障状态——所有者永远可以打开文件夹演示照常进行。8. 跳过上传SKIP_DRIVE_UPLOAD1与没有 Drive 副本的恢复横幅SKIP_DRIVE_UPLOAD1完全跳过 Drive适用于机器上不该存放这些资产的场景。文档明确这是一笔交易而不是一个后备方案接受演示没有 Drive 副本的事实。该变量取代了旧的SKIP_HOST_DRIVE_UPLOAD——后者针对的是一个已不复存在的第二个身份。当上传被跳过时文档完好无损只是没有 Drive 文件夹它们位于./external_files/和gs://$GCS_BUCKET_NAME/。setup_and_deploy.sh在每一种模式下都会执行 GCS 暂存Job 侧 L1422-1423gcloud storage cp -r external_files/* gs://${GCS_BUCKET_NAME}/v2.9.0 之前这份拷贝只存在于 rag 分支里导致 MCP 模式演示完全没有 bucket。脚本读取external_files/drive_upload_summary.json中的upload_skipped_reason在 External Sample Files - NOT in Google Drive标题下打印代价是什么演示脚本中的 Drive/Sheets 步骤什么都找不到、如何修复gcloud auth login --enable-gdrive-access --no-launch-browser后重跑或手动上传./external_files/并分享。这个横幅就是全部恢复故事这是有意设计。原文档 §5.5 记录了 v2.10.0 曾试图从另一端堵上缺口Agent 在每轮对话的第一轮、未经请求地、用用户的 OAuth 令牌把文档复制进已登录用户的 Drive背后有 Firestore 声明、工作线程与等待预算。v2.11.0 全部删除——工具、自动运行、声明、AUTO_IMPORT_DEMO_FILES、DRIVE_FOLDER_URL理由有三按权重排序为什么删除细节它上传了错误的东西上传器取走gs://$GCS_BUCKET_NAME/根目录下的所有对象。在 rag 模式下根目录同时是 datastore 的语料库真实演示中是 13 个对象 / 103 MB 客户自己的手册而不是 4 个生成样本——被塞进终端用户的个人 Drive且未经任何人同意机制压过了功能本身跨实例、跨会话的幂等需要以令牌邮箱为键的 Firestore 声明、接管超时、垃圾桶文件夹复检和停放式通知渠道——约 390 行代码只为完成部署用几次 REST 调用就能做的事每一轮对话都在为它买单before-agent 回调在所有轮次运行第一轮会阻塞至多AUTO_IMPORT_WAIT_S8 秒等待复制完成——而这个预算只适合 4 个小文件现在 Agent 的系统指令与横幅表述一致文档存在于云存储中部署会把副本放进部署账户的 Drive若 Drive 搜索返回空Agent 必须如实说明而不是提供它无法完成的复制。仓库测试 test_external_files_wiring.py 的第四组检查专门锁死了这条回归防线RETIRED列表import_demo_files_to_my_drive、AUTO_IMPORT_DEMO_FILES、DRIVE_FOLDER_URL等 7 个名字不得以任何形式重新出现在tools.py、agent.py与setup_and_deploy.sh中DRIVE_FOLDER_URL也不得再传入 Cloud Run。9. 报告与访问指引每个目的地都是一个可点击的链接原文档 §5.6 强调文件的每一条路径最终都应落在读者能点击的链接上——裸的gs://URI 或文件夹名都不是链接。Drive仅当上传确实运行时Drive 所有者执行部署的账户链接共享组织允许时为Anyone with link (Reader)否则出现ℹ️ LINK SHARING OFF提示观众需要显式分享打开文件夹https://drive.google.com/drive/folders/FOLDER_ID单文件链接https://drive.google.com/file/d/FILE_ID/view⚠️多账户浏览器警告打开 Google Drive 链接前请务必将浏览器切换到所有者 Google 账户。若同时登录了多个 Google 账户用非所有者账户访问会以 Permission Denied (403/404) 失败。Cloud Storage始终存在因为暂存拷贝无条件执行️浏览 buckethttps://console.cloud.google.com/storage/browser/BUCKET?projectPROJECT_ID直接打开文件https://storage.cloud.google.com/BUCKET/OBJECT——该地址用storage.objects.get把对象提供给已登录浏览器因此是每个已上传文件最值得打印的链接控制台 URL 是对象名在报告时未知时的后备。在 setup_and_deploy.sh 中这些渲染由 Stage 4 横幅完成脚本用jq从drive_upload_summary.json解析folder_url、owner_account、upload_skipped_reason、uploaded_files、share_error、shared_permissionsL1740-1747据此分支渲染 Google Drive External Sample Files、 External Sample Files - NOT in Google Drive或 External Sample Files in Cloud Storage三个区块L1785-1833GCS_FILE_LINKS会为external_files/下每个非记账文件跳过drive_upload_summary.json与*.url.json生成一条https://storage.cloud.google.com/${GCS_BUCKET_NAME}/filename链接。10. 测试门禁四个事实被锁定在仓库里search/gemini-enterprise/ge-demo-generator/test_external_files_wiring.pyv2.13.0 引入把本文描述的四项事实变成了可执行的门禁防止未来版本悄悄破坏这些设计契约文档在每种模式下都暂存到 GCS——将 Job 1.5 的代码块从脚本中切片出来在桩gcloud/python3下分别以RAG_MODE0与RAG_MODE1运行断言出现buckets create gs://demo-docs与storage cp -r external_files/同时断言GCS_BUCKET_NAME通过CR_ENV_VARS传入容器。上传是 Drive v3 gcloud 令牌、无外部 CLI——断言源码含https://www.googleapis.com/drive/v3与gcloud auth print-access-token不含gdrive内部二进制的任何踪迹其路径曾泄露进公开副本且REAUTH_HINTgcloud auth login --enable-gdrive-access --no-launch-browser出现在脚本中share_error、SKIP_DRIVE_UPLOAD、upload_skipped_reason均被断言存在。每个目的地都被报告缺失的 Drive 副本被明确宣告——断言每个暂存文件有可打开的 https 链接、bucket 有控制台地址、横幅含${DRIVE_OWNER_ACCOUNT}与LINK SHARING OFF且 no Drive copy 分支会打印${DRIVE_SKIP_REASON}与修复命令。对话内导入保持已删除——RETIRED名字列表全部不得出现Drive 上传辅助函数必须留在 Workspace 门控之下其剩余消费者是save_deliverables_to_drivebefore-agent 回调不做任何 Drive 工作Agent 指令中必须存在文档在 cloud storage不要提议把它们复制进用户的Drive 这样的表述。结语GE Demo Generator 的外部样例文件链路是一套让演示既真实又可控的完整工程三类文件在本地合成PDF/Excel/扫描件含刻意播种的审计偏差以gcloud令牌为唯一凭据上传到部署账户自己的 Drive幂等、按名复用、链接共享尽力而为并在不可行时通过SKIP_DRIVE_UPLOAD与部署完成横幅给出诚实、可恢复的降级路径。贯穿始终的设计原则是进入 Drive 只有部署时一条通道Agent 永不代写横幅永远如实报告。相关的兄弟文档可继续深入datastore_connectors.md§2.3 给出了Discovery Engine 创建的 Drive 数据存储无法被 Agent 服务账号读取、也无法限定到文件夹的实证、deployment_and_iam.md完整.env键参考与 SKILL.mdPhase 2-7 的完整生命周期。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考