--- name: wecomcli-doc-manage description: 何时用:仅当用户明确指向企业微信文档的公共管理(搜索/改名/成员权限/加入规则)时使用;本地文件管理默认走本地工具。适用所有企微文档类型;新建 doc 走 wecomcli-doc、新建在线表格走 wecomcli-sheet、智能表格 CRUD 走 wecomcli-smartsheet、生成智能文档走 wecomcli-smartpage;「看过哪些文档/浏览历史」走本技能。 metadata: requires: bins: ["wecom-cli"] --- > 执行任何 `wecom-cli` 命令前，必须先读取并完成 `wecomcli-shared` 技能的公共前置检查。 ## 核心概念 - **四种文档类型**：在线文档 `doc`、在线表格 `sheet`、智能表格 `smartsheet`、智能文档 `smartpage`。`doc_type` 枚举在多接口中复用。 - **搜索接口额外支持的类型**：收集表 `collect`、PPT `ppt`、脑图 `mind`、流程图 `flow`、汇报 `journal`、PDF `pdf`。这些类型仅在「搜索文档」接口的 `doc_types` 过滤中可用，其他接口（改名、权限、加入规则等）不适用。 ## 适用范围 **适用**： - 仅支持搜索 doc文档 / 在线表格 / 智能表格 / 智能文档 / PPT / 收集表 / 脑图 / 流程图 / 汇报 / PDF 文档类型 - 仅支持修改 doc文档 / 在线表格 / 智能表格 / 智能文档 的名称 - 仅支持添加 doc文档 / 在线表格 / 智能表格 / 智能文档 的成员权限 - 仅支持设置 doc文档 / 在线表格 / 智能表格 / 智能文档 的加入规则 ## 接口路由表 路由表第二列若是 `references/xxx.md` 链接 → 必须先用 `read` 读完该文件，再构造命令。 | 用户意图 | 参考位置 | |---------------------------------------------------------|---| | 搜索文档（包含最近浏览/创建） | 见下方「搜索文档」 | | 修改文档名 | [+names-update](references/doc-names-update.md) | | 添加文档成员 / 改权限 | [+members-update](references/doc-members-update.md) | | 设置链接加入规则 | [+rules-update](references/doc-rules-update.md) | ## 接口详述 ### 搜索文档 按关键词与过滤条件（类型 / 创建者 / 浏览者-成员 / 时间窗 / 排序）搜索文档 > 关于"浏览者"与"成员"：在本接口的搜索语义下二者等价——`visitor_userids` 命中的是"该 userid 作为浏览者/成员/相关者"的文档，用来表达"包含 X"、"X 参与的"、"与 X 相关的"、"X 作为成员的"均可。**注意权限约束**：无论传谁的 userid，最终结果只会返回**当前调用者本人有权限访问**的文档；他人有权限但你没权限的文档不会出现在结果中，因此本接口不能用于"窥探他人独占的文档列表"。 #### 命令 ```bash wecom-cli doc search --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` 必填。 - **`userid`（前缀 `wo`）**：用户提供的是姓名时通过 `读取 wecomcli-contact 技能` 解析为 `userid`；禁止把姓名当 `userid` 拼接，禁止凭记忆或猜测编造。 - **`keywords` 必须先分词再组装**：当用户给出自然语言 query（如 `"帮我找下产品的待办tool文档"`）时，禁止把整段 query 直接当成单个 keyword 传入。处理流程： 1. 对 query 做中英文分词，得到 token 列表（中文按词切分，英文按空格 / 大小写边界切分），并剔除"帮我"、"找下"、"文档"、"的"等口语化 / 通用 / 停用词。 2. 判定"必传 token"：从剩余 token 中挑出真正承载用户检索意图的核心词（通常是专有名词、产品名、功能名等强区分度词），其余作为辅助 token。 3. 组装 `keywords` 数组：第 1 个元素是所有"必传 token"用空格拼接的串（只拼必传的，不要把全部 token 都塞进去），后续元素依次是各单独 token（必传 + 辅助）。例如 query `"帮我找下产品的待办tool文档"`，分词后必传 token 为 `["待办", "tool"]`，则 `keywords = ["待办 tool", "待办", "tool"]`。 4. 若必传 token 只有 1 个，第 1 个元素就是该 token 本身，不必重复追加。例如 query `"周报"` → `keywords = ["周报"]`。 - **多候选必须让用户确认**：结果 >1 条时，按下方「结果展示规范」展示候选列表，等用户选定后再继续后续动作。 - **无候选必须追问用户**：结果 =0 条时，告知用户当前没有搜到文档，追问用户是否可以提供更多的关键词线索。 示例：用户 query `"帮我找下产品的待办tool文档"` 剔除"帮我 / 找下 / 的 / 文档"等通用词，剩余 `["产品", "待办", "tool"]`；判定核心检索意图为 `"待办"` 与 `"tool"`，故必传 token 为 `["待办", "tool"]`，`"产品"` 作为辅助 token。 ```bash 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`、权限角色等）缺失时，用简洁自然语言仅追问缺失或有歧义的信息；有候选项时在文字中列出供用户选择，不得自行猜测。