wecomcli-doc-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

执行任何
wecom-cli
命令前，必须先读取并完成
wecomcli-shared
技能的公共前置检查。

Before executing any
wecom-cli
command, you must read and complete the public pre-checks of the
wecomcli-shared
skill.

核心概念

Core Concepts

四种文档类型：在线文档
```
doc
```
、在线表格
```
sheet
```
、智能表格
```
smartsheet
```
、智能文档
```
smartpage
```
。
```
doc_type
```
枚举在多接口中复用。
搜索接口额外支持的类型：收集表
```
collect
```
、PPT
```
ppt
```
、脑图
```
mind
```
、流程图
```
flow
```
、汇报
```
journal
```
、PDF
```
pdf
```
。这些类型仅在「搜索文档」接口的
```
doc_types
```
过滤中可用，其他接口（改名、权限、加入规则等）不适用。

Four Document Types: Online document
```
doc
```
, online spreadsheet
```
sheet
```
, smart spreadsheet
```
smartsheet
```
, smart document
```
smartpage
```
. The
```
doc_type
```
enumeration is reused across multiple interfaces.
Additional Types Supported by Search Interface: Collection form
```
collect
```
, PPT
```
ppt
```
, mind map
```
mind
```
, flow chart
```
flow
```
, report
```
journal
```
, PDF
```
pdf
```
. These types are only available in the
```
doc_types
```
filter of the "Search Documents" interface and are not applicable to other interfaces (rename, permission, joining rules, etc.).

适用范围

Scope of Application

适用：

仅支持搜索 doc文档 / 在线表格 / 智能表格 / 智能文档 / PPT / 收集表 / 脑图 / 流程图 / 汇报 / PDF 文档类型
仅支持修改 doc文档 / 在线表格 / 智能表格 / 智能文档的名称
仅支持添加 doc文档 / 在线表格 / 智能表格 / 智能文档的成员权限
仅支持设置 doc文档 / 在线表格 / 智能表格 / 智能文档的加入规则

Applicable:

Only supports searching doc documents / online spreadsheets / smart spreadsheets / smart documents / PPT / collection forms / mind maps / flow charts / reports / PDF document types
Only supports modifying the names of doc documents / online spreadsheets / smart spreadsheets / smart documents
Only supports adding member permissions for doc documents / online spreadsheets / smart spreadsheets / smart documents
Only supports setting joining rules for doc documents / online spreadsheets / smart spreadsheets / smart documents

接口路由表

Interface Routing Table

路由表第二列若是

references/xxx.md

链接 → 必须先用

read

工具读完该文件，再构造命令。

用户意图	参考位置
搜索文档（包含最近浏览/创建）	见下方「搜索文档」
修改文档名	+names-update
添加文档成员 / 改权限	+members-update
设置链接加入规则	+rules-update

If the second column of the routing table is a

references/xxx.md

link → you must first read the file using the

read

tool before constructing the command.

User Intent	Reference Location
Search documents (including recently viewed/created)	See "Search Documents" below
Rename document	+names-update
Add document members / modify permissions	+members-update
Set link joining rules	+rules-update

接口详述

Interface Details

搜索文档

Search Documents

按关键词与过滤条件（类型 / 创建者 / 浏览者-成员 / 时间窗 / 排序）搜索文档

关于"浏览者"与"成员"：在本接口的搜索语义下二者等价——
visitor_userids
命中的是"该 userid 作为浏览者/成员/相关者"的文档，用来表达"包含 X"、"X 参与的"、"与 X 相关的"、"X 作为成员的"均可。注意权限约束：无论传谁的 userid，最终结果只会返回当前调用者本人有权限访问的文档；他人有权限但你没权限的文档不会出现在结果中，因此本接口不能用于"窥探他人独占的文档列表"。

Search documents by keywords and filter conditions (type / creator / viewer-member / time window / sorting)

Regarding "viewers" and "members": In the search semantics of this interface, they are equivalent —
visitor_userids
hits documents where "the userid is a viewer/member/stakeholder". It can be used to express "includes X", "participated by X", "related to X", "X as a member", etc. Note on Permission Constraints: No matter whose userid is passed, the final results will only return documents that the current caller has permission to access; documents that others have permission to access but you don't will not appear in the results, so this interface cannot be used to "snoop on others' exclusive document lists".

命令

Command

bash

wecom-cli doc search --json '<JSON 参数>'

bash

wecom-cli doc search --json '<JSON parameters>'

参数

Parameters

字段	类型	必填	默认值	语义
`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`

Field	Type	Required	Default Value	Semantics
`keywords`	string[]	Yes	—	Array of keywords, in OR relationship. Pass an empty array `[]` when filtering only by other conditions
`search_scope`	string	No	`title_content`	Search scope enumeration: `title` (title only) / `title_content` (title and content, default) / `content` (content only)
`doc_types`	string[]	No	—	Restrict types, subset of `doc` / `sheet` / `smartsheet` / `smartpage` / `collect` / `ppt` / `mind` / `flow` / `journal` / `pdf`
`creator_userids`	string[]	No	—	Restrict list of creator userids (typical: pass current user's userid to check "my recently created")
`visitor_userids`	string[]	No	—	Restrict list of "viewer / member" userids
`created_after` / `created_before`	string	No	—	Creation time window, `YYYY-MM-DD HH:mm:ss`
`opened_after` / `opened_before`	string	No	—	Recent opening time window, `YYYY-MM-DD HH:mm:ss`
`sort_by`	string	No	`best_match`	Sorting enumeration: `best_match` (default) / `create_time` (creation time) / `modify_time` (modification time)
`limit`	int	No	`10`	Return upper limit, no more than 100
`cursor`	string	No	—	Pagination cursor; pass empty for the first time, take `next_cursor` from the previous page for subsequent requests

Return

字段	类型	说明
`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[]	命中高亮片段

Field	Type	Description
`has_more`	boolean	Whether there is a next page; use `next_cursor` to continue fetching when `true`
`next_cursor`	string	Next page cursor
`docs`	array	Result document list, see the table below for fields of each item

Fields of a single document in

docs[]

Field	Type	Description
`docid`	string	Unique document ID
`doc_name`	string	Document name
`doc_type`	string	Document type
`url`	string	Accessible document link
`creator_userid`	string	Document creator userid
`create_time` / `modify_time`	string	Creation / recent modification time
`title_highlight` / `text_highlight`	string[]	Hit highlighted fragments

使用规则

Usage Rules

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}'

Currently, no downstream skill or CLI can read the content of
ppt
/
journal
/
collect
/
mind
/
flow
. When these types are hit and the user wants to view the content, directly inform them that reading is not supported yet, and guide them to open the document in the WeCom client using
```
doc_url
```
.
Parameter combinations are assigned by intent (including mandatory constraints): First determine the user's intent, then assemble parameters according to the corresponding branch. It is forbidden to pass no parameters or only empty values (such as
```
{}
```
).
- (a) Search by content →
```
keywords
```
  (required, cannot be empty array) +
```
search_scope=title_content
```
  +
```
sort_by=best_match
```
- (b) "My recently viewed / related to me / I am a member / documents that include me" →
```
visitor_userids=[<current userid>]
```
  (required, cannot be empty) +
```
sort_by=best_match
```
  +
```
opened_after
```
  (default: last 7 days)
- (c) "Include someone as a member / someone participated" (others) →
```
visitor_userids=[<other userid>]
```
  (required, first resolve from name via
```
wecomcli-contact
```
  ) +
```
sort_by=best_match
```
  ; must remind the user: only documents that the current caller has permission to access will be returned, documents that the other party has exclusive access to and you don't will not appear.
- (d) "My recently created" →
```
creator_userids=[<current userid>]
```
  (required, cannot be empty) +
```
created_*
```
  time window +
```
sort_by=create_time
```
  +
```
created_after
```
  (default: last 7 days)
- If the intent does not belong to (b)(c)(d), handle it according to (a),
```
keywords
```
  is required.
userid
(prefix
wo
): When the user provides a name, resolve it to
```
userid
```
by
```
reading the wecomcli-contact skill
```
; it is forbidden to use the name as
```
userid
```
for splicing, and forbidden to make up based on memory or guesses.
keywords
must be segmented before assembly: When the user gives a natural language query (such as "Help me find the product's to-do tool document"), it is forbidden to directly pass the entire query as a single keyword. Processing flow:
1. Perform Chinese-English word segmentation on the query to get a token list (Chinese segmented by words, English segmented by spaces / case boundaries), and remove colloquial / general / stop words such as "help me", "find", "document", "de".
2. Determine "mandatory tokens": Select core words that truly carry the user's retrieval intent from the remaining tokens (usually proper nouns, product names, function names, etc. with strong distinguishability), and the rest as auxiliary tokens.
3. Assemble the
```
keywords
```
  array: The first element is a string formed by concatenating all "mandatory tokens" with spaces (only mandatory ones, do not include all tokens), followed by individual tokens (mandatory + auxiliary). For example, query "Help me find the product's to-do tool document", after segmentation, mandatory tokens are ["待办", "tool"], then
```
keywords = ["待办 tool", "待办", "tool"]
```
  .
4. If there is only 1 mandatory token, the first element is the token itself, no need to append it repeatedly. For example, query "Weekly report" →
```
keywords = ["周报"]
```
  .
Multiple candidates must be confirmed by the user: When there are >1 results, display the candidate list according to the "Result Display Specification" below, and wait for the user to select before proceeding with subsequent actions.
No candidates must prompt the user: When there are 0 results, inform the user that no documents were found, and ask if they can provide more keyword clues.

Example: User query "Help me find the product's to-do tool document"

Remove general words like "help me / find / de / document", remaining ["产品", "待办", "tool"]; determine the core retrieval intent as "待办" and "tool", so mandatory tokens are ["待办", "tool"], "产品" as auxiliary token.

bash

wecom-cli doc search --json '{"keywords":["待办 tool","待办","tool","产品"],"search_scope":"title_content","limit":10}'

结果展示规范

Result Display Specification

向用户展示搜索结果（含单条与多候选）时严格遵守：

用 markdown 无序列表逐条展示，禁止使用表格——最多展示10条结果，即使只有 2~3 条结果也用列表；表格会强制四列对齐，反而把 ID / 时间等噪声字段一起暴露。
文档名必须是可点击链接：每条首行写成
```
- [doc_name](url)
```
，
```
url
```
取接口返回的
```
url
```
字段原样使用。
默认不展示创建者：
```
creator_userid
```
是内部 ID，禁止以任何形式输出给用户。

Strictly follow these rules when displaying search results to users (including single and multiple candidates):

Display item by item using markdown unordered list, do NOT use tables——Display up to 10 results, use a list even if there are only 2~3 results; tables force four-column alignment, which exposes noise fields like ID / time instead.
Document name must be a clickable link: Write the first line of each item as
```
- [doc_name](url)
```
, use the
```
url
```
field returned by the interface as-is for
```
url
```
.
Do not display creator by default:
```
creator_userid
```
is an internal ID, it is forbidden to output it to the user in any form.

跨技能依赖

Cross-skill Dependencies

依赖技能	典型协作场景	数据流向
`wecomcli-contact`	添加文档成员时用户只给姓名，需先解析为 `userid`	`wecomcli-contact` 的 `contact users search` → 返回 `userid` → 本 skill 的 `doc members update` 接口

Dependent Skill	Typical Collaboration Scenario	Data Flow
`wecomcli-contact`	When adding document members, the user only provides a name, which needs to be resolved to `userid` first	`contact users search` of `wecomcli-contact` → returns `userid` → `doc members update` interface of this skill

需要读取、打开搜索到的docid

Need to read and open the searched 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
、权限角色等）缺失时，用简洁自然语言仅追问缺失或有歧义的信息；有候选项时在文字中列出供用户选择，不得自行猜测。

Getting the

docid

is only the first step. Reading/opening the document content is another type of skill. You must first read the SKILL.md of the corresponding "content skill" according to doc_types, then send commands according to its documentation:

```
doc
```
(online document) →
```
wecomcli-doc
```
skill
```
smartpage
```
(smart document) →
```
wecomcli-smartpage
```
skill
```
sheet
```
(online spreadsheet) →
```
wecomcli-sheet
```
skill
```
smartsheet
```
(smart spreadsheet) →
```
wecomcli-smartsheet
```
skill It is strictly forbidden to directly assemble commands for "reading content"; before reading content for the first time, you must read the SKILL.md of the above corresponding content skills, and commands must be based on that SKILL.md.

When multiple search candidates need confirmation / search intent needs confirmation / mandatory parameters (such as
docid
, permission role, etc.) are missing, use concise natural language to only ask for the missing or ambiguous information; when there are candidates, list them in the text for the user to choose, do not guess on your own.