wecomteam wecom-cli 是插件提供的 tool，不是终端命令：所有操作都通过调用该 tool 完成，参数应使用 args 传入，禁止通过 exec / shell / 终端等命令行方式使用。
⚠️ 前置条件：首次调用 wecom-cli 前，必须按 wecomcli-preflight 技能执行前置条件检查，确保工具已加入白名单。
核心概念
- 四种文档类型：在线文档
doc、在线表格sheet、智能表格smartsheet、智能文档smartpage。doc_type枚举在多接口中复用。 - 搜索接口额外支持的类型：收集表
collect、PPTppt、脑图mind、流程图flow、汇报journal、PDFpdf。这些类型仅在「搜索文档」接口的doc_types过滤中可用，其他接口（改名、权限、加入规则等）不适用。
适用范围
适用：
- 仅支持搜索 doc文档 / 在线表格 / 智能表格 / 智能文档 / PPT / 收集表 / 脑图 / 流程图 / 汇报 / PDF 文档类型
- 仅支持修改 doc文档 / 在线表格 / 智能表格 / 智能文档 的名称
- 仅支持添加 doc文档 / 在线表格 / 智能表格 / 智能文档 的成员权限
- 仅支持设置 doc文档 / 在线表格 / 智能表格 / 智能文档 的加入规则
接口路由表
路由表第二列若是 references/xxx.md 链接 → 必须先用 read 工具读完该文件，再构造命令。
| 用户意图 | 参考位置 |
|---|---|
| 搜索文档（包含最近浏览/创建） | 见下方「搜索文档」 |
| 修改文档名 | +names-update |
| 添加文档成员 / 改权限 | +members-update |
| 设置链接加入规则 | +rules-update |
接口详述
搜索文档
按关键词与过滤条件（类型 / 创建者 / 浏览者-成员 / 时间窗 / 排序）搜索文档
关于"浏览者"与"成员"：在本接口的搜索语义下二者等价——
visitor_userids命中的是"该 userid 作为浏览者/成员/相关者"的文档，用来表达"包含 X"、"X 参与的"、"与 X 相关的"、"X 作为成员的"均可。注意权限约束：无论传谁的 userid，最终结果只会返回当前调用者本人有权限访问的文档；他人有权限但你没权限的文档不会出现在结果中，因此本接口不能用于"窥探他人独占的文档列表"。
调用方式
使用 wecom-cli 工具按照下面格式调用
wecom-cli doc search --json '<JSON 参数>'
参数
| 字段 | 类型 | 必填 | 默认值 | 语义 |
|---|---|---|---|---|
keywords |
string[] | 是 | — | 关键词数组，OR 关系。仅按其他条件过滤时传空数组 [] |
search_scope |
string | 否 | title_content |
搜索范围枚举：title（仅标题） / title_content（标题和内容，默认） / content（仅内容） |
doc_types |
string[] | 否 | — | 限定类型，取值为 doc / sheet / smartsheet / smartpage / collect / ppt / mind / flow / journal / pdf 的子集 |
creator_userids |
string[] | 否 | — | 限定创建者 userid 列表（典型：传当前用户 userid 查"我最近创建"） |
visitor_userids |
string[] | 否 | — | 限定"浏览者 / 成员" userid 列表 |
created_after / created_before |
string | 否 | — | 创建时间窗，YYYY-MM-DD HH:mm:ss |
opened_after / opened_before |
string | 否 | — | 最近打开时间窗，YYYY-MM-DD HH:mm:ss |
sort_by |
string | 否 | best_match |
排序枚举：best_match（默认） / create_time（创建时间） / modify_time（修改时间） |
limit |
int | 否 | 10 |
返回上限，不超过 100 |
cursor |
string | 否 | — | 分页游标；首次传空，后续取上页 next_cursor |
返回
| 字段 | 类型 | 说明 |
|---|---|---|
has_more |
boolean | 是否还有下一页；true 时用 next_cursor 续取 |
next_cursor |
string | 下一页游标 |
docs |
array | 结果文档列表，每项字段见下表 |
docs[] 单条文档字段：
| 字段 | 类型 | 说明 |
|---|---|---|
docid |
string | 文档唯一 ID |
doc_name |
string | 文档名 |
doc_type |
string | 文档类型 |
url |
string | 可访问的文档链接 |
creator_userid |
string | 文档创建者 userid |
create_time / modify_time |
string | 创建 / 最近修改时间 |
title_highlight / text_highlight |
string[] | 命中高亮片段 |
使用规则
ppt/journal/collect/mind/flow目前没有任何下游 skill 或 CLI 能读取正文，命中这些类型且用户要看内容时，直接告知暂不支持读取，引导用户用doc_url在企业微信客户端内打开查看。- 参数组合按意图分派（含必填约束）：先判定用户意图，再按对应分支组装参数。禁止所有参数均不传或仅传空值（如
{}）。- (a) 按内容找 →
keywords（必填，不得为空数组） +search_scope=title_content+sort_by=best_match - (b) "我最近浏览 / 与我相关 / 我作为成员 / 包含我的文档" →
visitor_userids=[<当前 userid>]（必填，不得为空） +sort_by=best_match+opened_after（默认近 7 天） - (c) "包含某人为成员 / 某人参与 "（他人）→
visitor_userids=[<他人 userid>]（必填，先经wecomcli-contact由姓名解析）+sort_by=best_match；必须提醒用户：只会返回当前调用者有权限访问的那部分文档，对方独占且你无权访问的文档不会出现。 - (d) "我最近创建" →
creator_userids=[<当前 userid>]（必填，不得为空） +created_*时间窗 +sort_by=create_time+created_after（默认近 7 天） - 若意图不属于 (b)(c)(d)，一律按 (a) 处理，
keywords必填。
- (a) 按内容找 →
userid（前缀wo）：用户提供的是姓名时通过读取 wecomcli-contact 技能解析为userid；禁止把姓名当userid拼接，禁止凭记忆或猜测编造。keywords必须先分词再组装：当用户给出自然语言 query（如"帮我找下产品的待办tool文档"）时，禁止把整段 query 直接当成单个 keyword 传入。处理流程：- 对 query 做中英文分词，得到 token 列表（中文按词切分，英文按空格 / 大小写边界切分），并剔除"帮我"、"找下"、"文档"、"的"等口语化 / 通用 / 停用词。
- 判定"必传 token"：从剩余 token 中挑出真正承载用户检索意图的核心词（通常是专有名词、产品名、功能名等强区分度词），其余作为辅助 token。
- 组装
keywords数组：第 1 个元素是所有"必传 token"用空格拼接的串（只拼必传的，不要把全部 token 都塞进去），后续元素依次是各单独 token（必传 + 辅助）。例如 query"帮我找下产品的待办tool文档"，分词后必传 token 为["待办", "tool"]，则keywords = ["待办 tool", "待办", "tool"]。 - 若必传 token 只有 1 个，第 1 个元素就是该 token 本身，不必重复追加。例如 query
"周报"→keywords = ["周报"]。
- 多候选必须让用户确认：结果 >1 条时，按下方「结果展示规范」展示候选列表，等用户选定后再继续后续动作。
- 无候选必须追问用户：结果 =0 条时，告知用户当前没有搜到文档，追问用户是否可以提供更多的关键词线索。
示例：用户 query "帮我找下产品的待办tool文档"
剔除"帮我 / 找下 / 的 / 文档"等通用词，剩余 ["产品", "待办", "tool"]；判定核心检索意图为 "待办" 与 "tool"，故必传 token 为 ["待办", "tool"]，"产品" 作为辅助 token。
使用 wecom-cli 工具按照下面格式调用
wecom-cli doc search --json '{"keywords":["待办 tool","待办","tool","产品"],"search_scope":"title_content","limit":10}'
结果展示规范
向用户展示搜索结果（含单条与多候选）时严格遵守：
- 用 markdown 无序列表逐条展示，禁止使用表格——最多展示10条结果，即使只有 2~3 条结果也用列表；表格会强制四列对齐，反而把 ID / 时间等噪声字段一起暴露。
- 文档名必须是可点击链接：每条首行写成
- [doc_name](url)，url取接口返回的url字段原样使用。 - 默认不展示创建者：
creator_userid是内部 ID，禁止以任何形式输出给用户。
跨技能依赖
| 依赖技能 | 典型协作场景 | 数据流向 |
|---|---|---|
wecomcli-contact |
添加文档成员时用户只给姓名，需先解析为 userid |
wecomcli-contact 的 contact users search → 返回 userid → 本 skill 的 doc members update 接口 |
需要读取、打开搜索到的docid
拿到 docid 只是第一步。读取/打开文档正文是另一类技能，必须按doc_types，先 read 对应"内容技能"的 SKILL.md，再按其文档发命令：
doc（在线文档）→wecomcli-doc技能smartpage（智能文档）→wecomcli-smartpage技能sheet（在线表格）→wecomcli-sheet技能smartsheet（智能表格）→wecomcli-smartsheet技能 严禁直接拼"读正文"的命令；首次读取正文前必须 read 上述对应内容技能的 SKILL.md，命令一律以该 SKILL.md 为准。
搜索多候选需确认 / 搜索意图类确认 / 必填参数（
docid、权限角色等）缺失时，用简洁自然语言仅追问缺失或有歧义的信息；有候选项时在文字中列出供用户选择，不得自行猜测。