Glean CLI
glean 是一个本地 CLI，用于认证到公司的 Glean 实例并暴露其 REST API。它可以搜索企业索引、与 Glean Assistant 对话、查询人员、获取并总结文档，以及管理 Glean 侧资源（集合、置顶、go-links、公告、精选答案、智能体、验证工作流）。
输出以 JSON 写入 stdout，错误写入 stderr，退出码反映成功与否。这使该 CLI 非常适合通过管道传给 jq。
前置检查
在使用本技能中的任何内容之前，请确保二进制文件位于 $PATH 中：
command -v glean
glean CLI 命令由 brew install gleanwork/tap/glean-cli 提供。
如果未找到该命令，你应询问用户是否希望你为其安装。
如果未认证（在认证错误时运行 glean auth status），且用户位于终端：glean auth login（浏览器 OAuth）。对于 CI 或脚本，改为设置 GLEAN_API_TOKEN 和 GLEAN_HOST 环境变量——凭据解析顺序为：环境变量 -> 系统密钥环 -> ~/.glean/config.json。
始终先自省
glean schema 是命令和标志的权威来源——Glean 会发布更新，schema 反映本地安装的版本。在调用本会话中尚未使用过的命令之前，运行：
glean schema <command> # 单个命令的完整机器可读 schema glean schema | jq '.commands' # 列出所有可用命令
本技能中的参考文件（references/commands.md）是快速查找，但如果 glean schema 与之不一致，以 schema 为准。
调用模式
glean <command> [subcommand] [flags]
有三个全局标志值得提前了解：
标志 用途
--output <json|ndjson|text> 默认 json。在将结果流式传输到管道时使用 ndjson。
--json '<payload>' 发送完整的 JSON 请求体。覆盖所有其他标志——对任何非平凡请求都使用它，schema 记录了请求体结构。
--dry-run 打印将要发送的请求，不发送任何内容。在任何创建/更新/删除操作之前始终使用。
存在简短的位置标志用于便捷查询（glean search "vacation policy"、glean chat "what are the holidays?"），但超出单个字符串的任何内容都应通过 --json 传递。
命令一览
只读：
命令 用途
glean search 在所有企业来源中查找文档。
glean chat 向 Glean Assistant 提问；流式返回 AI 答案。
glean documents 获取文档的元数据、内容、权限或 AI 摘要。
glean entities 查询人员、团队或自定义实体。
glean messages 按 ID 读取特定的 Slack/Teams 消息。
glean insights 拉取搜索/使用分析。
glean agents 列出、检查并运行 Glean AI 智能体。
glean tools 列出并运行 Glean 平台工具。
glean answers 列出/获取精选问答对。
写入/管理：
命令 用途
glean collections 创建/更新/删除文档集合；添加/移除条目。
glean pins 将文档提升到给定查询结果的顶部。
glean shortcuts 管理 go-links（例如 go/wiki）。
glean announcements 创建/更新/删除有时间限制的公司公告。
glean answers 创建/更新精选答案。
glean verification 将文档标记为已验证；发送验证提醒。
glean activity 记录用户活动事件；提交相关性反馈。
glean api 对任何 Glean REST 端点进行原始认证 HTTP 调用（逃生舱）。
关于上述任何命令的标志级细节和示例，请阅读 references/commands.md——它按命令组织，顺序与上述表格相同。
常见工作流
搜索并通过管道传给 jq。搜索返回的 JSON 包含 results 数组；每个结果有一个 document，包含 title、url、id、snippets 等。
glean search "incident response runbook" | jq '.results[] | {title: .document.title, url: .document.url}'
先查找再总结。将 search 与 summarise 子命令结合：
DOC_ID=$(glean search "Q1 OKRs" | jq -r '.results[0].document.id') glean documents summarize --json "{"documentId":"$DOC_ID"}" | jq -r .summary
提问。对于任何“我们公司对 X 怎么说”的问题，优先使用 glean chat 而非 glean search——Glean Assistant 会在其回答中引用底层文档。
glean chat "How do I expense international travel?"
查询人员。
glean entities read-people --json '{"query":"Jane Smith"}' | jq '.[0] | {name, email, title, department}'
注意事项
不要回显令牌。GLEAN_API_TOKEN 是敏感的；切勿回显它、记录它、将其包含在错误消息中或将其提交到文件。仅通过环境变量使用它。
写入操作始终先 --dry-run。任何 create、update、delete、verify、remind、add-items、delete-item 或 report 操作都会将数据发送到客户的 Glean 租户。先打印请求体，如果不是用户的明确要求，先获得用户确认，然后再发送。
--json 覆盖一切。如果同时提供 --json 和单独标志，JSON 请求体会静默胜出。不要混用两者。
以 schema 为准，而非记忆。标志名称和 JSON 请求体结构在 Glean 版本之间会演变。如果你传递请求体而 API 拒绝它，运行 glean schema <command> 并检查当前结构，而不是猜测。
glean api 是逃生舱，不是默认选项。如果存在用于你所做事情的专用子命令（例如 glean search 而非 glean api search），优先使用它——专用命令具有更好的易用性和稳定的契约。
错误落在 stderr。当通过管道传给 jq 或其他消费者时，单独捕获 stderr，以便你能呈现真正的错误消息，而不是下游的“parse error: unexpected end of JSON”。
搜索结果不总是文档对象。results[] 可能包含提升的答案、人员或置顶项——在编程处理时，根据 .type 分支或用 .document? 进行防护。