dingtalk-aisearch

DingTalk AI Search & Ask Skill

Minimal Execution Contract

• Use only dws to operate DingTalk, include --format jsonwith every command, and draw conclusions only from structured returns.
• person/enterprise/behavior Call directly, do not pre-read shared, Reference, Schema, Help, or downstream Skills.
• Do not guess commands, fields, IDs, profiles, or facts; with multiple candidates do not take the first item, and do not mix IDs from different domain .
• An empty result ends this search; failures, incomplete results, or candidate results must not be stated as "the object does not exist", as complete, or as unique.
• When the source is uncertain or the user lists multiple sources, the first business command must be a single merged --types of aisearch enterprise, and must not search product by product first.

Routing

Intent	Entry
Finding people by name, employee ID, department, position, responsibility, superior/subordinate, or mobile number clue	dws aisearch person
Finding content by topic across documents, messages, emails, to-dos, schedules, notes, etc.	dws aisearch enterprise
Sending/receiving with me as the endpoint, or what I created, edited, or shared	dws aisearch behavior
IM only and requires per-message predicate filtering	dws chat +search-msg
Listing recently accessed/edited documents without a topic	dws drive +recent
Enumerating all members of a department	dingtalk-contact
Full mobile number exact reverse lookup	dws contact user search-mobile --mobile "<手机号>" --format json
Reading/modifying after a stable ID is known	Corresponding product Skill

Order: resource scope → answer form → native predicate.

1. Personnel search

Dimensions: name=name, department=department, position=position, responsibility/owner=duty, superior=supervisor, subordinate=subordinate, employee ID=jobNumber, mobile number clue=phone; use only when it truly cannot be determined all。

dws aisearch person --query "<用户原始目标>" --dimension <维度> --format json

• Keep the complete target; query independent conditions separately. If the correct dimension is empty, end; do not switch all, shorten words, or expand homophones.
• Use searchEvidence.returnedCandidateCount to report the number of candidates in this search; without pagination completion evidence, only say "returned this time".
• Name/nickname contains queries only deliver _searchEvidence.exactAliasContainsQuery=true；exactAliasContainsCount=0 i.e., no exact contains item; semantic approximation cannot substitute.
• resolvedRelation.status=resolved When target/supervisor/relation to answer the direct superior, do not search again, and do not treat the superior's superior as the direct superior.
• Use one dimension=dutyfor product ownership and owner, keep the product name and "responsible"; only those with clear responsibility evidence may be called owner, for multiple candidates list candidates and departments, a common superior does not equal owner.
• Name and nickname can be associated by the same candidate's aliases ; IDs from different domains cannot be directly compared. Use the real userId to switch Contact only when more personnel details are needed.

2. Cross-source content search

Time words go only into --time-range, type words go only into --types, the rest of the topic goes into --queries。

dws aisearch enterprise --queries "<主题>" --types <类型CSV> [--time-range "<原时间词>"] --format json

Types: document/regular file=document, message=im, email=mail, schedule=calendar, to-do=todo, notes=minute, log=report, AI table=notable, knowledge content=baike; the sources listed by the user are merged into a single call.

• requestConstraints Echo the actual conditions,sources give the count for each source;no_returned_items indicates only that this attempt had no hit,coverage.status=unknown it cannot prove completeness.
• _searchEvidence.queryMatch=text_evidence_present only then is there textual subject evidence;no_text_evidence it is merely a semantic candidate, marked as unverified.
• Deliver only result the retained items and explain delivery.omitted；doNotRetryOrExpand=true stop when, without changing terms, supplementing searches per product, or reading Help.
• A unique exact title may come with resolvedDetail. Its status is resolved or resolved_from_search_payload and when the fields are sufficient, answer directly;failed only then report a supplementary read failure.
• When the schedule has no hit, the interface may call the calendar with the original time,meta.nativeFallback=true this still counts as evidence from this AISearch, and the Agent need not check the calendar again.
• When an exact title has no hit, do not substitute an approximate title, the nearest item, or the first item. "Read only if unique" requires designated source coverage, pagination completion, and a unique exact match; body text complete=true does not mean the search is complete.
• When the user only wants candidate summaries or links, do not read the original text; only when the body text is genuinely needed and fields are missing from the same result, read the corresponding product by its true stable ID.

3. Behavior traceback

dws aisearch behavior --queries "<主题>" --types <类型CSV> --behavior-type <all|send|receive|create|edit|share> [--time-range "<原时间词>"] [--direction "我->某人|某人->我|我<->某人"] [--chat-scope "<完整群名>"] --format json

• Call once per group of action, direction, and time, and merge the types. Direction is from the current user's perspective: "I sent to someone" =send; "someone sent to me" =receive。chat-scope is used only for IM, and the direction retains the original name.
• On a successful empty array, deliver "queried, 0 items this time", listing 0 by source; no longer use enterprise to piece together behavior evidence, do not delete subjects, expand the time, shrink group names, or use recent as a substitute.
• timeEvidence.withinRequestedRange=false exclude; for null mark the time as unverified.messageEvidence.perMessageVerified=false you cannot attribute all mixed-conversation snippets to the target person.
• "Someone sent a Word file" or "messages someone sent me today" calls behavior only once:types=im、receive, person direction, and the original time words; do not switch to Chat, guess the sender, or expand the year.
• resolvedMessageEvidence.status=resolved use directly messages, and even if empty, do not call Chat again;identity.match=returned_alias only proves that the display-name match returned an alias.
• For "who sent me a file on a certain subject" with an unknown sender, use direction="某人->我", by identity.match=any_returned_sender of messages.sender aggregate, without first guessing the person or splitting into two searches.

4. Verification and delivery

• Time: retain the original time words; "this week" does not equal the last seven days. Confirm the unit of numeric times. For creation behavior use the creation time, and do not substitute the modification time or the meeting start time.
• Identity: verify the sender, the recipient relationship, and the creator; visibility within a group does not equal being sent to me. Prefer stableRefs/identityRefs, only IDs with the same domain can be compared directly.
• Subject/type: there must be textual, attachment, or object-type evidence; group names, ordinary links, and the search hit itself cannot prove the subject or file attributes.
• Unique/full set: check the source and the pagination end state, deduplicate by stable ID; when only asking "is there any", a valid positive hit is sufficient.
• Summary: do not fill in fields that were not returned, do not write suggestions as facts, and do not call a snippet the body text; report hits, empty results, failures, and unverified items separately.

5. Same-condition native verification and multi-hop

Path:AISearch locate → confirm target → prioritize using the same resolvedDetail → only when required fields are missing, call one corresponding product by real ID.

• Switch to the corresponding product only when details, complete members, or evidence verification are needed, and a stable ID or a natively executable identical exact title/department/scope already exists; keep the topic, identity, direction, time, and permissions unchanged, and do not expand the scan scope.
• The fixed first step for cross-source is enterprise. When there is no stable ID, native re-search cannot be used as a substitute; if the target is unclear, identities conflict, it fails, or there is no permission, explain the limitation and stop.
• For people use userId, for documents use nodeId, for meeting notes use taskUuid, for to-dos use the real taskId; a Ding uid cannot be used as a Contact userId, and a snippet cannot be used as the body text.
• The user's preconditions such as "only read if unique" must still be met. Read only when the ID domain or the next hop is unclear multi-hop short process。

6. Local fallback is prohibited

For DingTalk objects, only DWS-returned results may be used as business evidence; when there is no hit, do not use find、rg、mdfind or evaluation fixtures to answer. For a meeting agenda item owner, use one person --dimension duty to preserve the original meeting and responsibility wording; only when the content can provide the original responsibility text, switch to using one enterprise --types calendar,im,document, and do not run both.

Errors and cost

1. retryable=true , the original call may be retried at most once; otherwise stop, and do not switch identity or bypass permissions.
2. Success but empty or no exact target: do not repeat, change wording, or expand the time range.
3. unknown flag only then check that command's Help once; API, permission, and empty-result issues are not resolved via Help.
4. Independent sources may continue; subsequent steps that depend on a failed result stop. Preserve the source, link, ID, scope, count, completeness, and error.

Reference on demand

Do not read the Reference for common paths. Read only when low-frequency enumeration or compatibility parameters are unclear complete command reference; when product boundaries are unclear, read local intent disambiguation; when the stable ID domain or next hop is unclear, read multi-hop short process。