尧图网站建设 
gogcli 文档结构化gog docs paragraphs命令的用法、过滤与源码解析【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文以 docs/commands/gog-docs-paragraphs.md 与 docs/commands/gog-docs-paragraphs-list.md 为骨架结合 gogcli 仓库内 internal/cmd/docs_enumerators.go、internal/cmd/docs_paragraphs.go 及对应测试系统讲解gog docs paragraphs命令树如何按段落列出 Google Docs 的结构化内容、如何用--style与--tab过滤、输出格式是什么以及其底层遍历算法与相关命令的协作方式。gog docs paragraphs是 gogcli 在终端中操作 Google Docs 的“段落枚举器”系列命令之一用于把一篇文档的正文拆解为带编号、带样式信息、带起止索引的段落列表。它服务于脚本化处理、结构审计、以及 LLM/Agent 对文档结构的快速理解——例如你想知道“这篇文档里所有HEADING_2段落出现在哪几个 UTF-16 索引区间”或想在写回文档之前确认第 N 段的确切位置都可以用这一条命令完成。读完本文你将掌握该命令的完整用法、输出契约、过滤语义与底层实现原理。命令定位gog docs家族中的段落枚举器gog docs paragraphs是gog docs命令树的子命令。在 internal/cmd/docs.go 中可以看到它与其他枚举器structure、headings、tables、images并列注册gog docs structure—— 以编号段落的形式展示文档结构gog docs paragraphs—— 列出文档段落本文主题gog docs headings—— 仅列出标题段落gog docs tables/gog docs images—— 分别枚举表格与图片。paragraphs与headings共享同一套“文档枚举器”基础设施enumerateDocsParagraphs区别仅在于是否过滤标题类型。因此把paragraphs理解为“不加过滤的完整段落清单”把headings理解为“只保留标题段落的子集”是准确的。命令语法与子命令根据 gog-docs-paragraphs.md命令树结构如下gog docs paragraphs └── gog docs paragraphs list (别名 ls) docId [flags]父命令gog docs paragraphs本身没有可执行动作只负责组织子命令唯一的子命令list别名ls接收一个必填位置参数docId功能为“List paragraphs”。典型调用形式# 列出默认标签页的全部段落 gog docs paragraphs list docId # 使用别名 ls gog docs paragraphs ls docId # 只列出 HEADING_2 段落 gog docs paragraphs list docId --style HEADING_2 # 只列出指定标签页的段落多标签文档 gog docs paragraphs list docId --tab Roadmap其中docId可以是 Google Docs 的文档 ID也可以是文档 URL——从源码 docs_enumerators.go 可见命令会先经过normalizeGoogleID处理因此粘贴完整 URL 也能正常工作。命令专用参数除全局旗标外list子命令只有两个命令专属参数定义见 docs_enumerators.go参数类型说明--stylestring只返回指定命名样式Named Style的段落例如NORMAL_TEXT、HEADING_2、TITLE不传则返回全部段落--tabstring按标签页标题或 ID 过滤不传则使用默认标签页多标签文档必须显式指定--style的过滤语义源码在 docs_enumerators.go 中对用户输入执行strings.ToUpper(strings.TrimSpace(c.Style))后与段落样式比较比较时同样使用大写形式因此大小写不敏感--style heading_2、--style Heading_2、--style HEADING_2等价首尾空白会被自动去除样式名必须与 Docs API 的NamedStyleType枚举一致如TITLE、SUBTITLE、HEADING_1HEADING_6、NORMAL_TEXT。--tab的底层行为当传入--tab时命令通过IncludeTabsContent(true)拉取多标签内容再调用findTab按标题或 ID 定位标签页docs_enumerators.go。若指定的标签页不存在命令会返回错误不会静默回退到默认标签页。输出格式终端表格默认默认以制表符分隔的表格输出表头为#、START、END、STYLE、TEXTdocs_enumerators.go# START END STYLE TEXT 1 0 27 TITLE Meeting Notes 2026-02-23 2 27 38 HEADING_1 Attendees 3 38 57 NORMAL_TEXT Alice, Bob, Carol 4 57 68 HEADING_1 Discussion 5 68 94 NORMAL_TEXT Very fun! Delightful to use各列含义列含义#段落序号从 1 开始递增与gog docs structure的编号口径一致START/END段落文本在文档中的UTF-16 代码单元起止索引与 Docs API 的startIndex/endIndex一致可用于后续gog docs update、gog docs delete等按索引操作的命令STYLE段落命名样式NamedStyleType如TITLE、HEADING_1、NORMAL_TEXTTEXT段落纯文本制表符等特殊字符会经docsTSVField转义以保证 TSV 可解析在--plain-p/--tsv模式下输出内容完全一致只是不绘制彩色表格适合直接管道给awk、cut等工具处理。JSON 模式使用-j/--json时输出结构化为{ documentId: 1abc..., tabId: t.0, paragraphs: [ { index: 1, startIndex: 0, endIndex: 27, style: TITLE, headingId: h.abc123, text: Meeting Notes 2026-02-23, isEmpty: false, runs: [ { text: Meeting Notes 2026-02-23, bold: true, link: null } ] } ] }JSON 条目比表格多出三类增强字段源码见 docs_enumerators.goheadingId—— 标题段的锚点 IDGoogle Docs 标题会自动生成可用于构建目录锚点isEmpty—— 该段落是否为空段落无文本、也无非文本内容runs—— 段内文本运行run的明细包含每个 run 的bold、italic等格式信息与link超链接对象适合做格式审计或富文本重建。配合全局旗标--results-only可去掉外层信封字段如nextPageToken配合--select可按点路径挑选字段。例如只取段落文本gog docs paragraphs list docId -j --results-only --select paragraphs.text源码级解析段落枚举算法递归遍历段落、表格单元格与目录enumerateDocsParagraphsdocs_enumerators.go是整个命令的核心算法其要点是递归而不是平面遍历遍历文档Body.Content中的每个StructuralElement遇到Paragraph直接登记为一条记录提取NamedStyleType为空时回退为NORMAL_TEXT与HeadingId遇到Table时递归进入每个单元格的Content因此表格单元格内的段落也会被枚举出来且会按全局顺序编号遇到TableOfContents时同样递归进入其内容SectionBreak等不可编辑元素被忽略。这一设计与 internal/cmd/docs_paragraphs.go 中的buildParagraphMap供gog docs structure使用不同structure的段落地图把“表格”整体视为一个编号项带TABLE类型与行列数而paragraphs枚举器则把表格内部段落也逐条展开。两者的编号口径因此存在差异——如果你需要“表格也算一项”的文档结构视图请使用gog docs structure如果需要“每个可编辑段落一行”的扁平清单则使用本文的gog docs paragraphs。文本提取规则paragraphTextdocs_paragraphs.go负责从段落元素中拼接纯文本依次拼接每个TextRun的Content使用strings.TrimRight(s, \n)去掉 Google Docs 自动附加在每段末尾的换行符保证输出干净这一行为被测试 docs_paragraphs_test.go 明确验证内容为Meeting Notes 2026-02-23\n的段落输出文本为Meeting Notes 2026-02-23。错误处理与边界docId为空时返回usage(empty docId)用法错误文档不存在或不是 Google Doc 时返回doc not found or not a Google Doc (id...)指定标签页无内容或找不到时分别返回明确错误测试用例覆盖了TabNotFound场景docs_paragraphs_test.go。全局旗标速查gog docs paragraphs及其子命令继承 gogcli 全命令树的全局旗标完整定义见 gog-docs-paragraphs.mdFlag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a/--account/--acctstring指定账户邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth 客户端名称选择对应存储的凭据与令牌桶--colorstringauto彩色输出auto/always/never--disable-commandsstring逗号分隔的禁用命令列表支持点路径-n/--dry-run/--dryrun/--noop/--previewbool不实际执行变更打印预期动作后成功退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 可用范围--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不会连带启用子命令-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全开关-h/--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本化--no-input/--non-interactive/--noninteractivebool绝不提示交互直接失败适合 CI-p/--plain/--tsvboolfalse输出稳定可解析的纯文本到 stdoutTSV无颜色--quota-projectstring用于 API 计费的 Google Cloud 项目作为X-Goog-User-Project发送某些 API 在--access-token或 ADC 模式下需要--readonlyboolfalse运行时阻止变更类 API 请求auth add也会只申请只读 OAuth 范围--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select/--pick/--projectstringJSON 模式下按逗号分隔字段挑选输出尽力而为支持点路径多数命令推荐使用--fields-v/--verbosebool开启详细日志--versionkong.VersionFlag打印版本后退出--wrap-untrustedboolfalseJSON/raw 输出时将拉取的文本字段包裹在外部不可信内容标记中对于只读的段落枚举操作推荐组合--readonly从运行时与 OAuth 范围两个层面确保无副作用与--no-input在 CI 中避免挂起等待交互。实战场景场景一审计文档的标题结构LLM / Agent 可用gog docs paragraphs list docId -j --results-only \ --select paragraphs.index,paragraphs.style,paragraphs.text | head -50通过--select只取编号、样式和文本得到一份压缩的目录式视图方便在写入变更前快速核对文档大纲。场景二按样式定位段落索引配合索引类命令精确修改gog docs update、gog docs delete等命令按 UTF-16 索引定位。可以先枚举出目标段落的START/ENDgog docs paragraphs list docId --style HEADING_2 -p输出的START/END列直接可作为后续索引操作的输入实现“先查结构、再定点修改”的流水线。场景三多标签页文档的段落清单gog docs paragraphs list docId --tab 2026 Roadmap -jtabId字段会返回该标签页的规范 ID如t.0供其他命令引用。场景四富文本运行明细gog docs paragraphs list docId -j --results-only --select paragraphs.runs输出每个段落的文本运行、加粗/斜体状态与链接对象可用于样式审计或文档迁移前的格式摸底。验证依据测试用例仓库内 docs_paragraphs_test.go 与 docs_enumerators_test.go 覆盖了本命令的关键行为TestBuildParagraphMap_Basic验证段落编号从 1 开始、TITLE/HEADING_1样式识别、bullet 标记与嵌套层级、索引范围提取TestBuildParagraphMap_DefaultStyleType无显式样式时回退为NORMAL_TEXTTestBuildParagraphMap_WithNestedBullets嵌套列表的NestLevel正确记录TestBuildParagraphMap_WithTab/TabNotFound标签页定位与错误路径TestParagraphMap_Get越界访问返回明确错误paragraph N out of range。这些测试同时印证了段落枚举与结构映射paragraphMap两套实现之间“编号口径不同”的差异可作为阅读与使用命令时的行为参照。相关文档命令参考gog docs paragraphs、gog docs paragraphs list父命令gog docs姊妹命令gog docs structure编号结构视图表格作为整体编号、gog docs headings标题子集源码internal/cmd/docs_enumerators.go、internal/cmd/docs_paragraphs.go、internal/cmd/docs.go测试internal/cmd/docs_paragraphs_test.go、internal/cmd/docs_enumerators_test.go命令总索引docs/commands/README.md【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gogcli 文档结构化：`gog docs paragraphs` 命令的用法、过滤与源码解析
gogcli 文档结构化gog docs paragraphs命令的用法、过滤与源码解析【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文以 docs/commands/gog-docs-paragraphs.md 与 docs/commands/gog-docs-paragraphs-list.md 为骨架结合 gogcli 仓库内 internal/cmd/docs_enumerators.go、internal/cmd/docs_paragraphs.go 及对应测试系统讲解gog docs paragraphs命令树如何按段落列出 Google Docs 的结构化内容、如何用--style与--tab过滤、输出格式是什么以及其底层遍历算法与相关命令的协作方式。gog docs paragraphs是 gogcli 在终端中操作 Google Docs 的“段落枚举器”系列命令之一用于把一篇文档的正文拆解为带编号、带样式信息、带起止索引的段落列表。它服务于脚本化处理、结构审计、以及 LLM/Agent 对文档结构的快速理解——例如你想知道“这篇文档里所有HEADING_2段落出现在哪几个 UTF-16 索引区间”或想在写回文档之前确认第 N 段的确切位置都可以用这一条命令完成。读完本文你将掌握该命令的完整用法、输出契约、过滤语义与底层实现原理。命令定位gog docs家族中的段落枚举器gog docs paragraphs是gog docs命令树的子命令。在 internal/cmd/docs.go 中可以看到它与其他枚举器structure、headings、tables、images并列注册gog docs structure—— 以编号段落的形式展示文档结构gog docs paragraphs—— 列出文档段落本文主题gog docs headings—— 仅列出标题段落gog docs tables/gog docs images—— 分别枚举表格与图片。paragraphs与headings共享同一套“文档枚举器”基础设施enumerateDocsParagraphs区别仅在于是否过滤标题类型。因此把paragraphs理解为“不加过滤的完整段落清单”把headings理解为“只保留标题段落的子集”是准确的。命令语法与子命令根据 gog-docs-paragraphs.md命令树结构如下gog docs paragraphs └── gog docs paragraphs list (别名 ls) docId [flags]父命令gog docs paragraphs本身没有可执行动作只负责组织子命令唯一的子命令list别名ls接收一个必填位置参数docId功能为“List paragraphs”。典型调用形式# 列出默认标签页的全部段落 gog docs paragraphs list docId # 使用别名 ls gog docs paragraphs ls docId # 只列出 HEADING_2 段落 gog docs paragraphs list docId --style HEADING_2 # 只列出指定标签页的段落多标签文档 gog docs paragraphs list docId --tab Roadmap其中docId可以是 Google Docs 的文档 ID也可以是文档 URL——从源码 docs_enumerators.go 可见命令会先经过normalizeGoogleID处理因此粘贴完整 URL 也能正常工作。命令专用参数除全局旗标外list子命令只有两个命令专属参数定义见 docs_enumerators.go参数类型说明--stylestring只返回指定命名样式Named Style的段落例如NORMAL_TEXT、HEADING_2、TITLE不传则返回全部段落--tabstring按标签页标题或 ID 过滤不传则使用默认标签页多标签文档必须显式指定--style的过滤语义源码在 docs_enumerators.go 中对用户输入执行strings.ToUpper(strings.TrimSpace(c.Style))后与段落样式比较比较时同样使用大写形式因此大小写不敏感--style heading_2、--style Heading_2、--style HEADING_2等价首尾空白会被自动去除样式名必须与 Docs API 的NamedStyleType枚举一致如TITLE、SUBTITLE、HEADING_1HEADING_6、NORMAL_TEXT。--tab的底层行为当传入--tab时命令通过IncludeTabsContent(true)拉取多标签内容再调用findTab按标题或 ID 定位标签页docs_enumerators.go。若指定的标签页不存在命令会返回错误不会静默回退到默认标签页。输出格式终端表格默认默认以制表符分隔的表格输出表头为#、START、END、STYLE、TEXTdocs_enumerators.go# START END STYLE TEXT 1 0 27 TITLE Meeting Notes 2026-02-23 2 27 38 HEADING_1 Attendees 3 38 57 NORMAL_TEXT Alice, Bob, Carol 4 57 68 HEADING_1 Discussion 5 68 94 NORMAL_TEXT Very fun! Delightful to use各列含义列含义#段落序号从 1 开始递增与gog docs structure的编号口径一致START/END段落文本在文档中的UTF-16 代码单元起止索引与 Docs API 的startIndex/endIndex一致可用于后续gog docs update、gog docs delete等按索引操作的命令STYLE段落命名样式NamedStyleType如TITLE、HEADING_1、NORMAL_TEXTTEXT段落纯文本制表符等特殊字符会经docsTSVField转义以保证 TSV 可解析在--plain-p/--tsv模式下输出内容完全一致只是不绘制彩色表格适合直接管道给awk、cut等工具处理。JSON 模式使用-j/--json时输出结构化为{ documentId: 1abc..., tabId: t.0, paragraphs: [ { index: 1, startIndex: 0, endIndex: 27, style: TITLE, headingId: h.abc123, text: Meeting Notes 2026-02-23, isEmpty: false, runs: [ { text: Meeting Notes 2026-02-23, bold: true, link: null } ] } ] }JSON 条目比表格多出三类增强字段源码见 docs_enumerators.goheadingId—— 标题段的锚点 IDGoogle Docs 标题会自动生成可用于构建目录锚点isEmpty—— 该段落是否为空段落无文本、也无非文本内容runs—— 段内文本运行run的明细包含每个 run 的bold、italic等格式信息与link超链接对象适合做格式审计或富文本重建。配合全局旗标--results-only可去掉外层信封字段如nextPageToken配合--select可按点路径挑选字段。例如只取段落文本gog docs paragraphs list docId -j --results-only --select paragraphs.text源码级解析段落枚举算法递归遍历段落、表格单元格与目录enumerateDocsParagraphsdocs_enumerators.go是整个命令的核心算法其要点是递归而不是平面遍历遍历文档Body.Content中的每个StructuralElement遇到Paragraph直接登记为一条记录提取NamedStyleType为空时回退为NORMAL_TEXT与HeadingId遇到Table时递归进入每个单元格的Content因此表格单元格内的段落也会被枚举出来且会按全局顺序编号遇到TableOfContents时同样递归进入其内容SectionBreak等不可编辑元素被忽略。这一设计与 internal/cmd/docs_paragraphs.go 中的buildParagraphMap供gog docs structure使用不同structure的段落地图把“表格”整体视为一个编号项带TABLE类型与行列数而paragraphs枚举器则把表格内部段落也逐条展开。两者的编号口径因此存在差异——如果你需要“表格也算一项”的文档结构视图请使用gog docs structure如果需要“每个可编辑段落一行”的扁平清单则使用本文的gog docs paragraphs。文本提取规则paragraphTextdocs_paragraphs.go负责从段落元素中拼接纯文本依次拼接每个TextRun的Content使用strings.TrimRight(s, \n)去掉 Google Docs 自动附加在每段末尾的换行符保证输出干净这一行为被测试 docs_paragraphs_test.go 明确验证内容为Meeting Notes 2026-02-23\n的段落输出文本为Meeting Notes 2026-02-23。错误处理与边界docId为空时返回usage(empty docId)用法错误文档不存在或不是 Google Doc 时返回doc not found or not a Google Doc (id...)指定标签页无内容或找不到时分别返回明确错误测试用例覆盖了TabNotFound场景docs_paragraphs_test.go。全局旗标速查gog docs paragraphs及其子命令继承 gogcli 全命令树的全局旗标完整定义见 gog-docs-paragraphs.mdFlag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a/--account/--acctstring指定账户邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth 客户端名称选择对应存储的凭据与令牌桶--colorstringauto彩色输出auto/always/never--disable-commandsstring逗号分隔的禁用命令列表支持点路径-n/--dry-run/--dryrun/--noop/--previewbool不实际执行变更打印预期动作后成功退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 可用范围--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不会连带启用子命令-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全开关-h/--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本化--no-input/--non-interactive/--noninteractivebool绝不提示交互直接失败适合 CI-p/--plain/--tsvboolfalse输出稳定可解析的纯文本到 stdoutTSV无颜色--quota-projectstring用于 API 计费的 Google Cloud 项目作为X-Goog-User-Project发送某些 API 在--access-token或 ADC 模式下需要--readonlyboolfalse运行时阻止变更类 API 请求auth add也会只申请只读 OAuth 范围--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select/--pick/--projectstringJSON 模式下按逗号分隔字段挑选输出尽力而为支持点路径多数命令推荐使用--fields-v/--verbosebool开启详细日志--versionkong.VersionFlag打印版本后退出--wrap-untrustedboolfalseJSON/raw 输出时将拉取的文本字段包裹在外部不可信内容标记中对于只读的段落枚举操作推荐组合--readonly从运行时与 OAuth 范围两个层面确保无副作用与--no-input在 CI 中避免挂起等待交互。实战场景场景一审计文档的标题结构LLM / Agent 可用gog docs paragraphs list docId -j --results-only \ --select paragraphs.index,paragraphs.style,paragraphs.text | head -50通过--select只取编号、样式和文本得到一份压缩的目录式视图方便在写入变更前快速核对文档大纲。场景二按样式定位段落索引配合索引类命令精确修改gog docs update、gog docs delete等命令按 UTF-16 索引定位。可以先枚举出目标段落的START/ENDgog docs paragraphs list docId --style HEADING_2 -p输出的START/END列直接可作为后续索引操作的输入实现“先查结构、再定点修改”的流水线。场景三多标签页文档的段落清单gog docs paragraphs list docId --tab 2026 Roadmap -jtabId字段会返回该标签页的规范 ID如t.0供其他命令引用。场景四富文本运行明细gog docs paragraphs list docId -j --results-only --select paragraphs.runs输出每个段落的文本运行、加粗/斜体状态与链接对象可用于样式审计或文档迁移前的格式摸底。验证依据测试用例仓库内 docs_paragraphs_test.go 与 docs_enumerators_test.go 覆盖了本命令的关键行为TestBuildParagraphMap_Basic验证段落编号从 1 开始、TITLE/HEADING_1样式识别、bullet 标记与嵌套层级、索引范围提取TestBuildParagraphMap_DefaultStyleType无显式样式时回退为NORMAL_TEXTTestBuildParagraphMap_WithNestedBullets嵌套列表的NestLevel正确记录TestBuildParagraphMap_WithTab/TabNotFound标签页定位与错误路径TestParagraphMap_Get越界访问返回明确错误paragraph N out of range。这些测试同时印证了段落枚举与结构映射paragraphMap两套实现之间“编号口径不同”的差异可作为阅读与使用命令时的行为参照。相关文档命令参考gog docs paragraphs、gog docs paragraphs list父命令gog docs姊妹命令gog docs structure编号结构视图表格作为整体编号、gog docs headings标题子集源码internal/cmd/docs_enumerators.go、internal/cmd/docs_paragraphs.go、internal/cmd/docs.go测试internal/cmd/docs_paragraphs_test.go、internal/cmd/docs_enumerators_test.go命令总索引docs/commands/README.md【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考