gogcli 联系人生成指南使用gog contacts create在终端中创建 Google 联系人【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog contacts create是 Google Workspace 终端 CLI 工具 gogcli 中用于创建 Google 联系人的核心命令。本指南将带你掌握通过gog contacts create别名add、new在终端中快速录入联系人、批量附加邮箱/电话/地址/自定义字段等完整技能并深入源码剖析其底层实现原理与校验逻辑帮助你像管理代码一样管理你的通讯录。命令定位与用法gog contacts create归属于gog contacts命令族详见 gog contacts该命令族还包含list、get、search、update、delete、export、dedupe、directory、other、raw等子命令。从源码结构看命令族在 internal/cmd/contacts.go 中通过 Kong 声明create子命令带有add和new两个别名Create ContactsCreateCmd cmd: name:create aliases:add,new help:Create a contact因此以下三种写法完全等价gog contacts create --given Ada --family Lovelace gog contacts add --given Ada --family Lovelace gog contacts new --given Ada --family Lovelace完整的命令用法来自 gog-contacts-create.mdgog contacts (contact) create (add,new) [flags]其中(contact)表示父命令contacts也可写作其别名contact。命令的行为是“Create a contact”——创建一条新的 Google 联系人记录写入 Google People API而非本地缓存。联系人字段 Flags 详解以下参数专门用于描述要创建的联系人内容其定义可在源码 internal/cmd/contacts_crud.go 中的ContactsCreateCmd结构体中找到Flag类型说明--givenstring名Given name必填项--familystring姓Family name--emailstring邮箱地址创建时做格式校验--phonestring电话号码--orgstring组织/公司名称--titlestring职位头衔--url[]stringURL可重复传入多个--notestring备注/传记写入 People API 的 biography 字段--address[]string邮寄地址可重复传入多个源码中声明了sep:;分隔符--genderstring性别值--custom[]string自定义字段格式keyvalue可重复--relation[]string关系字段格式typeperson可重复必填与校验规则源码 internal/cmd/contacts_crud.go 中ContactsCreateCmd.Run首先执行校验if strings.TrimSpace(c.Given) { return usage(required: --given) }即--given是唯一必填参数缺省会直接报错退出测试 internal/cmd/contacts_crud_validation_more_test.go 验证了这一行为expected create missing given。邮箱则经过 internal/cmd/plain_email.go 中的validatePlainEmail校验——使用 Go 标准库net/mail解析要求是纯邮箱地址不允许带显示名非法邮箱如nope会在请求发出前被拦截addr, err : mail.ParseAddress(email) if err ! nil || addr nil || addr.Address ! email || addr.Name ! { return usagef(invalid %s %q, flag, email) }对应的测试 internal/cmd/contacts_crud_validation_more_test.go 断言expected create invalid email, got ...。可重复字段的解析规则--custom与--relation通过parseKeyValuePairsinternal/cmd/contacts_crud.go解析要求严格形如keyvalue缺或任一侧为空都会报错如expected keyvalue for --custom, got ...--custom被转换为 People API 的UserDefined结构--relation被转换为Relation{Type, Person}。--url与--address会逐条 trim 并过滤空串分别映射为people.Url与people.AddressStreetAddress字段。--gender会封装为带Primary: true元数据的people.Gender。可选字段在请求中的组装根据 internal/cmd/contacts_crud.go 的实现字段按“非空才附加”原则组装进people.Personp : people.Person{ Names: []*people.Name{{ GivenName: strings.TrimSpace(c.Given), FamilyName: strings.TrimSpace(c.Family), }}, }即名字names始终携带family 允许为空串邮箱、电话、组织、职位、URL、备注写入biographies、地址、性别、自定义字段、关系仅在提供非空值时才写入请求体。全局 Flags所有 gogcli 命令通用除联系人字段外gog contacts create还继承了 gogcli 的全局参数体系与 gog contacts 及命令索引 Command index 中一致。最常用的如下Flag类型默认说明-a/--account/--acctstring指定账号邮箱、别名或autoGoogle API 命令通用--access-tokenstring直接使用给定的访问令牌绕过存储的 refresh token令牌约 1 小时过期--clientstringOAuth 客户端名称选择存储的凭据与令牌桶-n/--dry-run/--dryrun/--noop/--previewbool不实际修改仅打印预期操作并成功退出-j/--json/--machineboolfalseJSON 输出到 stdout适合脚本-p/--plain/--tsvboolfalse输出稳定可解析的 TSV 文本无颜色--colorstringauto颜色输出auto\|always\|never--readonlyboolfalse运行时阻断所有变更 API 请求-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认提示--no-input/--non-interactive/--noninteractivebool永不提示直接失败适合 CI--quota-projectstring指定 Google Cloud 项目用于 API 计费以X-Goog-User-Project头发送--results-onlyboolJSON 模式下仅输出主结果丢弃 envelope 字段如nextPageToken--select/--pick/--projectstringJSON 模式下按逗号分隔选择字段支持点路径--enable-commands/--enable-commands-exact/--disable-commandsstring按前缀或精确路径启用/禁用命令dot paths 支持--gmail-no-sendboolfalse阻断 Gmail 发送操作Agent 安全开关--wrap-untrustedboolfalseJSON/raw 输出中对抓取的文本字段包裹外部不可信内容标记--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-v/--verbosebool启用详细日志-h/--helpkong.helpFlag显示上下文相关帮助--versionkong.VersionFlag打印版本并退出账号解析requireAccount在执行 API 调用前命令会通过 internal/cmd/account.go 中的requireAccount解析目标账号ADCApplication Default Credentials模式下无需用户邮箱、以服务账号身份认证常规模式下从--account、GOG_ACCOUNT环境变量或默认配置中确定账号并与--client选择的 OAuth 凭据配合使用。实战示例1. 创建最简联系人仅必填项gog contacts create --given Ada2. 创建完整联系人gog contacts create \ --given Ada \ --family Lovelace \ --email adaexample.com \ --phone 1 555-0100 \ --org Analytical Engine Ltd \ --title First Programmer \ --url https://example.com/ada \ --address 12 Curzon Street, London \ --gender female \ --note Analyst author \ --custom departmentcomputing \ --relation colleaguecharlesexample.com3. 可重复字段传多个值gog contacts create \ --given Ada \ --url https://example.com/ada \ --url https://example.com/ada-blog \ --address 12 Curzon Street, London \ --address Second home address4. 使用别名add / newgog contacts add --given Grace --family Hopper gog contacts new --given Grace --family Hopper5. 配合全局参数# 指定账号 JSON 输出适合脚本消费 gog -a meexample.com contacts create --given Ada --json # 在 CI 中无交互执行 gog contacts create --given Ada --no-input --account meexample.com # 指定 OAuth 客户端 gog --client work contacts create --given Ada源码原理从 Flag 到 People API 的完整调用链服务工厂命令通过 internal/cmd/runtime_services.go 中的peopleContactsService获取 Google People API 客户端该工厂从运行时注入的服务工厂Services.PeopleContacts中解析出people.Service再由requireAccount决定使用哪个账号的 OAuth 凭据func peopleContactsService(ctx context.Context, account string) (*people.Service, error) { runtime, err : runtimeWithService(ctx, people contacts) ... return runtime.Services.PeopleContacts(ctx, account) }创建请求的发出真正写库的调用在 internal/cmd/contacts_crud.gocreated, err : svc.People.CreateContact(p).Do()这对应 Google People API 的people.createContact端点。成功后created.ResourceName形如people/c123456789会被打印出来作为新联系人的唯一标识。输出格式默认表格模式打印一行resource\tpeople/...给出新联系人的资源名。JSON 模式--json输出完整创建结果{contact: {...}}包含 People API 返回的全部字段便于脚本解析或直接喂给 LLM/自动化流程。plain 模式--plain输出无颜色的稳定 TSV 文本。Dry-run不落库的预演--dry-run通过 internal/cmd/dryrun.go 的dryRunExit实现在contacts.create操作真正执行前打印预期请求体{dry_run: true, op: contacts.create, request: {...}}并以退出码 0 结束完全不会触碰认证/密钥环或发起 API 调用——这是批量录入前核对字段拼写、或在 CI 流水线中做变更预演的安全手段gog contacts create --given Ada --dry-run --json测试验证命令行为的可验证依据仓库为gog contacts create提供了较完整的测试保障internal/cmd/contacts_crud_validation_more_test.go 通过直接构造ContactsCreateCmd并调用Run验证了缺--given报错、非法邮箱报invalid --email等输入校验路径。internal/cmd/execute_contacts_test.go 使用httptest起本地 mock 服务端模拟 People API验证了contacts list的 JSON 输出结构含nextPageToken以及--max 0/-1等参数在创建服务前就失败的行为——这类端到端测试模式同样覆盖创建类命令的请求组装。从ContactsCreateCmd.Run的代码路径看校验必填、邮箱发生在服务实例化与任何网络请求之前因此错误反馈快速且无副作用。注意事项与限制只增不改create只会新建联系人不覆盖已存在条目。修改已有联系人是gog contacts update的职责参见 gog-contacts-update.md删除则是gog contacts delete。邮箱严格校验--email必须是纯地址不含显示名否则请求前即失败。别名可用contacts命令族本身支持contact别名create支持add、new别名方便按习惯书写。多值字段--url、--address、--custom、--relation均支持重复传入--custom/--relation必须遵循keyvalue/typeperson格式。安全与只读模式--readonly会阻断一切变更类请求包括创建--gmail-no-send等其他安全开关同样全局生效适合 Agent/自动化环境。--given为空字符串时报错命令对输入做 trim 后再判断全空白输入同样视为缺失。延伸阅读命令族总览gog contacts全命令索引Command index联系人其他操作gog contacts listgog-contacts-list.md、gog contacts getgog-contacts-get.md、gog contacts searchgog-contacts-search.md、gog contacts updategog-contacts-update.md、gog contacts deletegog-contacts-delete.md、gog contacts exportgog-contacts-export.md认证与账号管理gog auth、gog-login.md【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gogcli 联系人生成指南：使用 `gog contacts create` 在终端中创建 Google 联系人
gogcli 联系人生成指南使用gog contacts create在终端中创建 Google 联系人【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog contacts create是 Google Workspace 终端 CLI 工具 gogcli 中用于创建 Google 联系人的核心命令。本指南将带你掌握通过gog contacts create别名add、new在终端中快速录入联系人、批量附加邮箱/电话/地址/自定义字段等完整技能并深入源码剖析其底层实现原理与校验逻辑帮助你像管理代码一样管理你的通讯录。命令定位与用法gog contacts create归属于gog contacts命令族详见 gog contacts该命令族还包含list、get、search、update、delete、export、dedupe、directory、other、raw等子命令。从源码结构看命令族在 internal/cmd/contacts.go 中通过 Kong 声明create子命令带有add和new两个别名Create ContactsCreateCmd cmd: name:create aliases:add,new help:Create a contact因此以下三种写法完全等价gog contacts create --given Ada --family Lovelace gog contacts add --given Ada --family Lovelace gog contacts new --given Ada --family Lovelace完整的命令用法来自 gog-contacts-create.mdgog contacts (contact) create (add,new) [flags]其中(contact)表示父命令contacts也可写作其别名contact。命令的行为是“Create a contact”——创建一条新的 Google 联系人记录写入 Google People API而非本地缓存。联系人字段 Flags 详解以下参数专门用于描述要创建的联系人内容其定义可在源码 internal/cmd/contacts_crud.go 中的ContactsCreateCmd结构体中找到Flag类型说明--givenstring名Given name必填项--familystring姓Family name--emailstring邮箱地址创建时做格式校验--phonestring电话号码--orgstring组织/公司名称--titlestring职位头衔--url[]stringURL可重复传入多个--notestring备注/传记写入 People API 的 biography 字段--address[]string邮寄地址可重复传入多个源码中声明了sep:;分隔符--genderstring性别值--custom[]string自定义字段格式keyvalue可重复--relation[]string关系字段格式typeperson可重复必填与校验规则源码 internal/cmd/contacts_crud.go 中ContactsCreateCmd.Run首先执行校验if strings.TrimSpace(c.Given) { return usage(required: --given) }即--given是唯一必填参数缺省会直接报错退出测试 internal/cmd/contacts_crud_validation_more_test.go 验证了这一行为expected create missing given。邮箱则经过 internal/cmd/plain_email.go 中的validatePlainEmail校验——使用 Go 标准库net/mail解析要求是纯邮箱地址不允许带显示名非法邮箱如nope会在请求发出前被拦截addr, err : mail.ParseAddress(email) if err ! nil || addr nil || addr.Address ! email || addr.Name ! { return usagef(invalid %s %q, flag, email) }对应的测试 internal/cmd/contacts_crud_validation_more_test.go 断言expected create invalid email, got ...。可重复字段的解析规则--custom与--relation通过parseKeyValuePairsinternal/cmd/contacts_crud.go解析要求严格形如keyvalue缺或任一侧为空都会报错如expected keyvalue for --custom, got ...--custom被转换为 People API 的UserDefined结构--relation被转换为Relation{Type, Person}。--url与--address会逐条 trim 并过滤空串分别映射为people.Url与people.AddressStreetAddress字段。--gender会封装为带Primary: true元数据的people.Gender。可选字段在请求中的组装根据 internal/cmd/contacts_crud.go 的实现字段按“非空才附加”原则组装进people.Personp : people.Person{ Names: []*people.Name{{ GivenName: strings.TrimSpace(c.Given), FamilyName: strings.TrimSpace(c.Family), }}, }即名字names始终携带family 允许为空串邮箱、电话、组织、职位、URL、备注写入biographies、地址、性别、自定义字段、关系仅在提供非空值时才写入请求体。全局 Flags所有 gogcli 命令通用除联系人字段外gog contacts create还继承了 gogcli 的全局参数体系与 gog contacts 及命令索引 Command index 中一致。最常用的如下Flag类型默认说明-a/--account/--acctstring指定账号邮箱、别名或autoGoogle API 命令通用--access-tokenstring直接使用给定的访问令牌绕过存储的 refresh token令牌约 1 小时过期--clientstringOAuth 客户端名称选择存储的凭据与令牌桶-n/--dry-run/--dryrun/--noop/--previewbool不实际修改仅打印预期操作并成功退出-j/--json/--machineboolfalseJSON 输出到 stdout适合脚本-p/--plain/--tsvboolfalse输出稳定可解析的 TSV 文本无颜色--colorstringauto颜色输出auto\|always\|never--readonlyboolfalse运行时阻断所有变更 API 请求-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认提示--no-input/--non-interactive/--noninteractivebool永不提示直接失败适合 CI--quota-projectstring指定 Google Cloud 项目用于 API 计费以X-Goog-User-Project头发送--results-onlyboolJSON 模式下仅输出主结果丢弃 envelope 字段如nextPageToken--select/--pick/--projectstringJSON 模式下按逗号分隔选择字段支持点路径--enable-commands/--enable-commands-exact/--disable-commandsstring按前缀或精确路径启用/禁用命令dot paths 支持--gmail-no-sendboolfalse阻断 Gmail 发送操作Agent 安全开关--wrap-untrustedboolfalseJSON/raw 输出中对抓取的文本字段包裹外部不可信内容标记--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-v/--verbosebool启用详细日志-h/--helpkong.helpFlag显示上下文相关帮助--versionkong.VersionFlag打印版本并退出账号解析requireAccount在执行 API 调用前命令会通过 internal/cmd/account.go 中的requireAccount解析目标账号ADCApplication Default Credentials模式下无需用户邮箱、以服务账号身份认证常规模式下从--account、GOG_ACCOUNT环境变量或默认配置中确定账号并与--client选择的 OAuth 凭据配合使用。实战示例1. 创建最简联系人仅必填项gog contacts create --given Ada2. 创建完整联系人gog contacts create \ --given Ada \ --family Lovelace \ --email adaexample.com \ --phone 1 555-0100 \ --org Analytical Engine Ltd \ --title First Programmer \ --url https://example.com/ada \ --address 12 Curzon Street, London \ --gender female \ --note Analyst author \ --custom departmentcomputing \ --relation colleaguecharlesexample.com3. 可重复字段传多个值gog contacts create \ --given Ada \ --url https://example.com/ada \ --url https://example.com/ada-blog \ --address 12 Curzon Street, London \ --address Second home address4. 使用别名add / newgog contacts add --given Grace --family Hopper gog contacts new --given Grace --family Hopper5. 配合全局参数# 指定账号 JSON 输出适合脚本消费 gog -a meexample.com contacts create --given Ada --json # 在 CI 中无交互执行 gog contacts create --given Ada --no-input --account meexample.com # 指定 OAuth 客户端 gog --client work contacts create --given Ada源码原理从 Flag 到 People API 的完整调用链服务工厂命令通过 internal/cmd/runtime_services.go 中的peopleContactsService获取 Google People API 客户端该工厂从运行时注入的服务工厂Services.PeopleContacts中解析出people.Service再由requireAccount决定使用哪个账号的 OAuth 凭据func peopleContactsService(ctx context.Context, account string) (*people.Service, error) { runtime, err : runtimeWithService(ctx, people contacts) ... return runtime.Services.PeopleContacts(ctx, account) }创建请求的发出真正写库的调用在 internal/cmd/contacts_crud.gocreated, err : svc.People.CreateContact(p).Do()这对应 Google People API 的people.createContact端点。成功后created.ResourceName形如people/c123456789会被打印出来作为新联系人的唯一标识。输出格式默认表格模式打印一行resource\tpeople/...给出新联系人的资源名。JSON 模式--json输出完整创建结果{contact: {...}}包含 People API 返回的全部字段便于脚本解析或直接喂给 LLM/自动化流程。plain 模式--plain输出无颜色的稳定 TSV 文本。Dry-run不落库的预演--dry-run通过 internal/cmd/dryrun.go 的dryRunExit实现在contacts.create操作真正执行前打印预期请求体{dry_run: true, op: contacts.create, request: {...}}并以退出码 0 结束完全不会触碰认证/密钥环或发起 API 调用——这是批量录入前核对字段拼写、或在 CI 流水线中做变更预演的安全手段gog contacts create --given Ada --dry-run --json测试验证命令行为的可验证依据仓库为gog contacts create提供了较完整的测试保障internal/cmd/contacts_crud_validation_more_test.go 通过直接构造ContactsCreateCmd并调用Run验证了缺--given报错、非法邮箱报invalid --email等输入校验路径。internal/cmd/execute_contacts_test.go 使用httptest起本地 mock 服务端模拟 People API验证了contacts list的 JSON 输出结构含nextPageToken以及--max 0/-1等参数在创建服务前就失败的行为——这类端到端测试模式同样覆盖创建类命令的请求组装。从ContactsCreateCmd.Run的代码路径看校验必填、邮箱发生在服务实例化与任何网络请求之前因此错误反馈快速且无副作用。注意事项与限制只增不改create只会新建联系人不覆盖已存在条目。修改已有联系人是gog contacts update的职责参见 gog-contacts-update.md删除则是gog contacts delete。邮箱严格校验--email必须是纯地址不含显示名否则请求前即失败。别名可用contacts命令族本身支持contact别名create支持add、new别名方便按习惯书写。多值字段--url、--address、--custom、--relation均支持重复传入--custom/--relation必须遵循keyvalue/typeperson格式。安全与只读模式--readonly会阻断一切变更类请求包括创建--gmail-no-send等其他安全开关同样全局生效适合 Agent/自动化环境。--given为空字符串时报错命令对输入做 trim 后再判断全空白输入同样视为缺失。延伸阅读命令族总览gog contacts全命令索引Command index联系人其他操作gog contacts listgog-contacts-list.md、gog contacts getgog-contacts-get.md、gog contacts searchgog-contacts-search.md、gog contacts updategog-contacts-update.md、gog contacts deletegog-contacts-delete.md、gog contacts exportgog-contacts-export.md认证与账号管理gog auth、gog-login.md【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考