gogcli 文档页脚管理：`gog docs footer list` 命令全解析——列出 Google Docs 页脚与 Segment ID

gogcli 文档页脚管理gog docs footer list命令全解析——列出 Google Docs 页脚与 Segment ID【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本篇文章聚焦 gogcli 的gog docs footer list命令它以 Google Docs API 为底层将文档中每个页脚Footer及其 segment ID 一次性枚举出来是页脚创建、删除、定位与脚本化审计的前提工具。读完本文你将掌握该命令的完整语法、全部 flags 的含义与默认值、TSV/JSON 两种输出格式的精确结构以及它在多标签Tabs文档中的行为细节并能直接用输出结果驱动footer delete完成页脚清理工作流。命令定位gogcli 如何管理文档页脚在 gogcli 的命令树中gog docs footer是一个负责列出、创建或删除文档页脚的子命令组其下属三个子命令分工明确gog docs footer list—— 列出页脚及其 segment ID本文主题gog docs footer create—— 创建并可选择性填充一个页脚gog docs footer delete—— 删除一个页脚。在 Google Docs 的 API 模型中页脚Footer和页眉Header一样是文档的独立段segment——每个页脚都拥有一个全局唯一的 segment ID形如kix.xxx正文中的文字索引、插入定位、删除操作都要以这个 ID 为句柄。因此list 命令是所有页脚操作的第一步只有先拿到 segment ID后续的删除footer delete docId footerId才能定位到具体目标。用法与别名gog docs footer list的完整语法如下gog docs (doc) footer (footers) list (ls) docId [flags]其中括号内的部分是该命令注册的别名alias在实际调用中可以任选其一docs可写为docfooter可写为footerslist可写为ls。例如下面四种写法完全等价gog docs footer list docId gog doc footers ls docId gog docs footers list docId gog doc footer ls docId命令的唯一位置参数是docId即目标 Google 文档的 ID可从文档 URL 中提取或先用gog drive search等命令获取。从源码实现看DocsFooterListCmd结构体仅定义了两个字段type DocsFooterListCmd struct { DocID string arg: name:docId help:Doc ID Tab string name:tab help:Limit results to a tab title or ID }即位置参数docId和可选的--tab过滤 flag。入口Run方法将参数转交给统一的runDocsSegmentList逻辑见 internal/cmd/docs_header_footer.go这意味着 footer 与 header 的枚举走的是同一套实现只是枚举的段类型不同。Flags 完整参考gog docs footer list继承了 gogcli 的全局命令体系可用 flags 如下表所示文档由gog schema --json自动生成可用make docs-commands重新生成见 docs/commands/README.mdFlagTypeDefaultHelp--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a--account--acctstringAccount email, alias, or auto for authenticated Google API commands--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--disable-commandsstringComma-separated list of disabled commands; dot paths allowed-n--dry-run--dryrun--noop--previewboolDo not make changes; print intended actions and exit successfully--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children-y--force--assume-yes--yesboolSkip confirmations for destructive commands--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)-h--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j--json--machineboolfalseOutput JSON to stdout (best for scripting)--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)-p--plain--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select--pick--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.--tabstringLimit results to a tab title or ID-v--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers其中--tab是 list 命令自身特有的过滤 flag其余多为 gogcli 全局 flags。按用途可把这 24 个 flags 归为几类便于记忆与查错认证与身份类--access-token直接使用传入的 access token绕过存储的 refresh tokentoken 约 1 小时后过期适合一次性脚本或 CI 注入。-a/--account/--acct指定账号邮箱、别名或auto用于切换多账号环境。--client指定 OAuth client 名称用于选择对应存储的凭据与 token 桶。--quota-project指定计费的 Google Cloud 项目以X-Goog-User-Project头发送部分 API 在使用--access-token或 ADC 时要求必须提供。输出与机器可读性类-j/--json/--machine以 JSON 输出到 stdout是脚本化处理的首选模式。-p/--plain/--tsv输出稳定可解析的 TSV 文本无颜色。--color控制颜色输出取值auto|always|never。--results-only在 JSON 模式下只输出主结果丢弃nextPageToken等信封字段。--select/--pick/--project在 JSON 模式下按逗号分隔选择字段尽力而为支持点路径。--wrap-untrusted在 JSON/raw 输出中将抓取到的文本字段用不可信外部内容标记包裹便于下游 Agent 区分来源。行为与安全类-n/--dry-run/--dryrun/--noop/--preview不实际变更打印预期动作后成功退出。虽然 list 本身是只读操作但这一全局 flag 保证了在统一的自动化框架下的一致性。--readonly运行时拦截所有 mutating API 请求auth add时也只会申请只读 OAuth scope。--no-input/--non-interactive/--noninteractive永不交互式提问遇到需要输入的场景直接失败适合 CI。--gmail-no-send阻断 Gmail 发送类操作Agent 安全措施。-y/--force/--assume-yes/--yes跳过破坏性命令的确认提示。--disable-commands/--enable-commands/--enable-commands-exact以逗号分隔的 dot path 列表启用或禁用命令可用于构建受限的 Agent 工具面。环境与调试类--home覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME环境变量。-h/--help显示上下文相关的帮助。-v/--verbose开启详细日志。--version打印版本并退出。输出格式详解默认TSV输出不带任何输出类 flag 时list 命令对每个页脚输出一行、四列、以制表符分隔的 TSV 文本源码见 internal/cmd/docs_header_footer.goID Type TabID Length四列含义如下列字段含义1ID页脚的 segment ID如kix.abc123删除时直接作为footerId传入2Type段类型footer 场景下恒为footer3TabID页脚所属标签页Tab的 ID文档未启用 Tabs 功能时为空4Length页脚内容长度即页脚内容中最后一个结构元素的EndIndexUTF-16 索引等价于页脚文本区域的结束位置Length的计算逻辑位于docsStructuralContentEndinternal/cmd/docs_header_footer.go它遍历该段的所有StructuralElement取EndIndex的最大值。通过对比两次 list 的Length值可以快速判断页脚内容是否被外部编辑过。JSON 输出使用-j/--json时输出为 JSON 对象internal/cmd/docs_header_footer.go{ documentId: 1AbCdEfGhIjKlMnOp, footers: [ { id: kix.abc123, type: footer, tabId: t.0, length: 42 } ] }其中footers数组内的每一项对应docsSegmentListItem结构type docsSegmentListItem struct { ID string json:id Type string json:type TabID string json:tabId,omitempty Length int64 json:length }注意tabId带omitempty标记当页脚不属于任何显式 Tab即来自未启用 Tabs 的旧文档时该字段会被省略。配合--results-only可以只输出footers数组本身配合--select id,length可以进一步裁剪字段方便管道处理gog docs footer list 1AbCdEfGhIjKlMnOp --json --results-only --select id,length源码实现原理list 命令的完整调用链gog docs footer list的实现集中在 internal/cmd/docs_header_footer.go页脚与页眉共用一套代码通过docsSegmentKindFooter/docsSegmentKindHeader常量区分。核心调用链如下func (c *DocsFooterListCmd) Run(ctx context.Context, flags *RootFlags) error { return runDocsSegmentList(ctx, flags, c.DocID, c.Tab, docsSegmentKindFooter) }runDocsSegmentListinternal/cmd/docs_header_footer.go按以下步骤执行规范化文档 ID通过normalizeGoogleID去除docId首尾空白若为空直接返回 usage 错误对应源码中的usage(empty docId)。获取 Docs 服务与文档调用requireDocsService完成认证初始化随后执行svc.Documents.Get(docID).IncludeTabsContent(true).Context(ctx).Do()。关键点是IncludeTabsContent(true)——该参数要求 API 返回文档全部标签页Tabs的完整内容包括每个 Tab 各自的 footers这是多标签文档页脚枚举能够成立的前提。收集页脚段collectDocsSegments根据是否指定--tab决定遍历范围internal/cmd/docs_header_footer.go指定--tab时调用findTab在扁平化后的 Tab 列表里按TabId 精确匹配或标题大小写不敏感匹配定位到目标 Tab仅收集该 Tab 的 footers找不到时返回tab not found错误并附带可用 Tab 标题列表见 internal/cmd/docs_tabs.go。未指定--tab时先遍历所有 Tab包括通过flattenTabs递归展开的子标签页见 internal/cmd/docs_tabs.go再补上文档根层级的 legacy 页脚段doc.Headers/doc.Footers对应docsLegacySegmentElements。排序收集到的条目按TabID升序、再按ID升序稳定排序保证多次运行输出顺序一致便于 diff 与脚本断言。按输出模式分派outfmt.IsJSON(ctx)为真时走 JSON 分支{documentId:..., footers:[...]}否则逐行打印 TSV。值得留意的是docsSegmentElementsinternal/cmd/docs_header_footer.go直接从tab.Footers映射中取出id - segment.Content再交给docsStructuralContentEnd计算长度——整个过程对 Docs API 返回结构保持无损读取没有本地二次解析因此输出的ID与Length与 Google 服务端视图严格一致。实战从列出到删除页脚的完整工作流footer list最常见的用途是为footer delete提供句柄。以下是一个端到端示例1. 列出文档中的全部页脚gog docs footer list 1AbCdEfGhIjKlMnOp输出示例TSVkix.a1b2c3 footer t.0 42 kix.d4e5f6 footer t.1 182. 按标签页过滤多标签文档只查某个 Tabgog docs footer list 1AbCdEfGhIjKlMnOp --tab 附录 # 或按 TabId gog docs footer list 1AbCdEfGhIjKlMnOp --tab t.13. 用拿到的 segment ID 删除页脚先用 dry-run 预览gog docs footer delete 1AbCdEfGhIjKlMnOp kix.a1b2c3 --dry-run gog docs footer delete 1AbCdEfGhIjKlMnOp kix.a1b2c3删除命令的第二个位置参数即footerId正是 list 输出第一列的值。若传入了错误类型的 ID例如把 header 的 segment ID 当成 footer删除实现中的loadDocsTargetSegment会校验段类型并报错源码见 internal/cmd/docs_header_footer.go避免误删。4. 脚本化审计页脚JSON 模式 jq 类工具gog docs footer list 1AbCdEfGhIjKlMnOp --json --results-only \ | jq -r .[] | select(.length 0) | .id这条命令可以列出所有非空页脚的 ID是批量化清理模板文档页脚的常用入口。由于 list 是只读操作它天然适合放在--readonly或受限命令集--enable-commands docs.footer.list的 Agent 沙箱中作为探查工具。与其他命令的关系gog docs footer list在命令树中位于 gog docs footer 之下其父命令 gog docs 还包含gog docs header兄弟命令组header 的 list/create/delete 与 footer 完全对称见 gog-docs-footer-create.md、gog-docs-footer-delete.md。创建页脚时可借助--text/--file填充初始内容并用--at、--at-end、--index控制页脚所在的 section 位置这些命令与 list 形成了查看 → 创建 → 删除的完整闭环。需要说明的是docs/commands/下所有命令页面均由gog schema --json自动生成页首注释明确标注 Do not edit this page by hand; runmake docs-commands本文所有 flags 与用法均以当前仓库生成的文档页 gog-docs-footer-list.md 为准完整的命令索引见 docs/commands/README.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考