Search real notes via the official getnote CLI. Do not assemble OpenAPI requests, note IDs, or access links yourself. For machine calls use -o json; only a JSON success=true with exit code 0 counts as business success.
When to use
- "About a topic, vague memory": use
getnote search; when the book/source is clear or full coverage is needed, choose a path below. - "What notes are recent, list them by save time": hand off to the notes Skill's
getnote notes, do not mistake a list for semantic search. - After the user selects one, hand off to the notes Skill to read details with
getnote note <note_id>; during the search stage do not automatically modify, move, share, or create notes.
First choose a lookup path
- Clear book (book title or book author), especially when "all highlights" are wanted: first read the knowledge base reference. For book title use
kbs --scope BOOKSPACE --query; when only the author name is available usekbs --scope BOOKSPACE --authorand omit--query, do not stuff the author into a query that only matches names. Pass both only when both book title and author are known; the two are AND conditions. When necessary use the real--book-idto disambiguate, then choose whether to add--note-type refbased on whether the user wants "all notes" or "highlights"; when full text is needed, call by IDnote。 - Clear article/course (including "a certain teacher's course"): follow "Course, manuscript, and comment location" below. When a real source ID/article link already exists, filter precisely directly; even without candidates, location information can be listed by source.
topics=[]does not block this route. - Only a topic or vague memory: semantic search → deduplicate by string note ID → read details/original text for selected candidates. Top-K (maximum 10) is not a complete list; zero hits also cannot prove there are no related notes in the whole library.
Easily confused combined phrasings
| User wording | Path and conditions that must not be lost |
|---|---|
| "Find Borges's book notes" / "Find notes mentioning Borges" | The former locates by book author; the latter is a content topic search, and does not restrict all notes mentioning a person to that person's works. |
| "The manuscript for a certain course's group reading of a certain book" | When the course/manuscript is clear, prioritize the course citation path; the book title here is a manuscript clue, do not jump to BOOKSPACE. |
| "Course notes" | First distinguish Dedao course citations from self-recorded class notes; set dedao/course_article only when the user specifies the source, and do not exclude class recordings. |
| "About a topic in a certain library/certain book" | First locate the real topic_id, then search --kb; if there is no hit, supplement the lookup in that library's list according to the knowledge base reference, do not treat an empty search as absence in the library, and do not omit the library scope. |
| "A certain course note saved last week/modified yesterday" | For lists use the corresponding time filter; search has no time/source filter parameters, and semantic candidates need to be checked against timestamps/reference. Do not claim time filtering is complete just by putting time words into the query. |
| "Notes under a certain course link" / "Highlights of this manuscript link" | After the course homepage URL matches reference.url, take each article of that course; only a manuscript URL is passed as --article-url. The encoded ID in the URL is not --reference-id; do not convert it yourself. |
| "All notes" / "All highlights" | The former does not add a note-type ref by default; the book library may contain non-quote notes such as reflections. Obtaining the course reference path only proves the highlight set under that source; it cannot cover course reflections or recordings that the user wrote separately. |
Multi-condition queries must preserve all of the user's constraints; when moving from candidates to an exact manuscript list, also preserve the already specified topic/time/source. When conditions conflict or the author or version does not match, explain the actual candidates; do not silently drop conditions. When there is a body topic restriction, a source match only proves "it comes from here"; the body still needs to be checked. A word not appearing in a truncated preview cannot be taken as the full text not containing it. When merging results from multiple libraries/books, deduplicate by the string note_id; do not merge different highlights with different IDs.
Enhanced results' resource_type uses lowercase resource types such as note/file; the old top-level note_type retains the uppercase NOTE/FILE compatibility values; the actual note type is in note.note_type. Use note.display_title for display, use snippet(the old interface is content) to explain the hit; do not replace the search snippet with the detail preview.snippet_source=unknown is preserved as is;score=null is unknown, not 0;returned_count is the number of snippets,distinct_note_count is the number of deduplicated notes. When non-note results such as FILE have no note ID, present only the real resource information; do not construct a note link.
Course, manuscript, and comment locating
search is Top-K semantic recall; the presence of source metadata in the return value does not guarantee that it participated in recall. Do not judge a task for a specified course as successful just because other notes were found.
- Extract constraints: distinguish course name, manuscript name, instructor, content topic, comments, and the user-given time. For example, "Help me find the highlights in the article about probability in Teacher Lin's Science Course" should preserve the course/instructor constraints, and not just search the whole sentence once and stop. When an exact article URL is provided, directly read the source filter of the note reference.
- Discover candidates: you may first use course/manuscript keywords
getnote search '<课程名或文稿标题关键词>' --limit 10 -o json. Check the results'note.reference; when old results do not have it, readnotefor relevant candidates. When there is no source match, only irrelevant results, or the user wants "all notes of the entire course," go to the source list below; do not repeatedly search with the whole sentence. - Supplementary source list check: when the user explicitly says it is a Dedao course, execute the following command; in the same conversation, pages already read may be reused, but when the user says new notes were added, they must be read again.
getnote notes --source dedao --note-type ref --reference-type course_article --page-size 20 -o json
# 有下一页时，保持筛选和 page-size，用真实返回的 pagination.next_cursor 继续
getnote notes --source dedao --note-type ref --reference-type course_article --page-size 20 --cursor '<pagination.next_cursor>' -o json
When the user gives a time/knowledge base, also preserve the corresponding filter; do not arbitrarily add restrictions such as "the last month." When the source is not clear, first verify based on candidates; do not treat all courses as Dedao sources. Read only locating information; do not first download the full text of the entire library. This command has no course-name query parameter; the name is matched by the Agent in the returned metadata, and it cannot be described as the server directly filtering by course name.
| User clues | Check fields and boundaries |
|---|---|
| Course name, abbreviation | reference.title; candidates may be found by ignoring surrounding book-title marks, spaces, and full-width/half-width differences, while preserving season/version, and not treating "Daily Lesson 6" as another season. |
| Manuscript title | reference.article.title; snippets may be used for candidate matching, and are only confirmed after detail verification. |
| Teacher/author | Prioritize reference.author; when missing, a name appearing in the course title can serve as a candidate clue, but the author field must not be fabricated nor identity asserted. |
| Same course, multiple documents | Use the real reference.url to distinguish courses; when missing or conflicting with the same name, list candidates; each document's resource_id cannot substitute for the course ID. |
| Personal comments | Read the candidate details' content, and do not guess comments from preview or ref_content . |
- Control traversal and disambiguation: paginate by the returned
pagination.has_more/next_cursor, deduplicate by the string note_id, and verify capabilities/applied_filters; if a cursor loop, repeated lack of progress, or mid-way failure occurs, state that it is incomplete. For a single source candidate discovery, read at most 5 pages first (20 items per page); if exceeded, keep the candidates found and the progress, state that it is still not fully checked, narrow the scope with the user's clues, or ask whether to continue. This execution budget must not be treated as "the entire library has none". When the user explicitly requests all, continue according to the knowledge base reference's complete pagination rules; only when traversal is truly complete can a full conclusion be given. When same-name courses/same-name documents cannot be distinguished, list candidates for the user to choose. When the relevantmetadata_state.referenceis partial/unavailable or the required fields are missing, keep it as a candidate pending verification, and read details if necessary; one must not assert that it does not belong to the target source merely because fields are missing. - Fulfill the user's goal: when finding one, read the matching candidate's details; when finding all highlights of the same document, use the note reference's
--reference-idor--article-urlto retrieve all precisely; when finding all of an entire course, complete the traversal of the course reference scope, group by course source, then read details item by item as needed. Preserve the distinction between original text, personal comments, and source; do not merge multiple highlights into one by document ID.
When only the personal comment is remembered: first use the comment's substantive text for semantic search and read details to verify. If the user has already narrowed it to a course but the search has no match, narrow candidates according to the above source list; comments are omitted in the list, so candidates cannot be excluded on that basis. For a small candidate set (no more than 20 items), read details item by item as needed to match; when more than 20, first narrow further using the given course/document/time, and if still insufficient, ask the user for clues; do not batch-download the entire account's full text. Generalized comments such as "inspiring" may correspond to multiple items; return all verified candidates rather than arbitrarily choosing the first. When the user has not limited the source, do not on your own check only courses and then claim to have checked all comments.
Semantic search execution steps
Execute only when the above path selection requires semantic search; not specifying a knowledge base does not mean semantic search must be performed first.
- When the user has not specified a knowledge base, execute
getnote search <query> --limit <1-10> -o json. The default limit is 10 and must not be increased on your own. - When the user specifies a knowledge base name, first execute according to its type
getnote kbs --scope <scope> -o json; by default queryDEFAULT, and books, customer files, and team knowledge bases respectively useBOOKSPACE、CUSTOMER、TEAMSPACE. Match using the returned realtopic_idandscope; when names are the same or the intent is unclear, the user must be asked to choose. - After the knowledge base is confirmed, execute
getnote search <query> --kb <topic_id> --limit <1-10> -o json。 - Only read the title, summary, string
note_id, and realnote_urlfrom the return value. Non-note results withoutnote_id/note_urlmay display content, but a "open note" link must not be fabricated. - The same note may appear multiple times due to matching multiple snippets. When listing "how many notes" to the user, it must be by the string
note_idDeduplicate; if the count after deduplication is less than the number requested by the user, you may increase it within the upper limit of 10--limitand search again; if it is still insufficient, truthfully return the actual count.
Command results and user presentation
Search
getnote search "支付流程" --limit 10 -o json
getnote search "客户反馈" --kb <topic_id> --limit 5 -o json
Stable fields of a successful JSON response:
| Field | Meaning | How the Agent uses it |
|---|---|---|
success |
Whether the operation succeeded | Only if true should you continue to present results. |
data.results[] |
Search results | An empty array is a successful "not found", not a failure. |
data.results[].title |
Note title | Prefer note.display_title; for older responses use title instead, and only if both are missing display unnamed. |
data.results[].note_id |
Note snowflake ID | Always pass it through as a string, unchanged, to subsequent note commands. |
data.results[].note_url |
Real note link | Only provide the user with "open note" when it is non-empty. |
data.results[].content |
Matched summary or body excerpt | Extract only a short excerpt relevant to the question; do not pass it off as the full text. |
data.results[].score |
Relevance score, may be null | null means unknown; use it only for internal ranking, and do not fabricate an "accuracy rate" to the user. |
On success, provide a numbered list ordered by relevance, for example:
这次搜索找到 3 条不同的相关笔记：
1. 《支付流程优化想法》——“用户等待时增加进度提示…”
打开：<真实 note_url>
2. 《客户支付反馈》——“…”
打开：<真实 note_url>
你想看哪一条的详情或原文？
If data.partial=true or if data.warningsexists, first explain that the retrieval had some results that could not complete permission verification or reading, and explain the cause according to warnings; an empty result also must not be described as no matches after a complete search. If data.results=[] or none of the results match the source specified by the user, first complete a supplementary source search within the same request scope according to the selected path; a supplementary search is not expanding the scope across knowledge bases or accounts. Only when it is a topic search and there are no available source clues, explain "this semantic search found nothing"; do not say the interface failed or that the entire database has nothing; do not create notes or fabricate results.
Failure, privacy, and follow-up actions
success=falseor exit code non-zero: reply with the failed step,error.message/error.reason, whetherretryableand optionalrequest_id; do not describe HTTP success or empty output as a successful search.- If the CLI prompts "search service response timed out", this means the retrieval was not completed, not that there are "no results". Suggest retrying later, or narrowing the keywords, specifying a knowledge base, and trying again; do not fabricate an empty list.
- Retrieval results may contain private body text. In group chats or shared sessions, by default show only the title, necessary excerpt, and real link; expand the full text only after the user explicitly requests it.
- After the user selects a result, reuse the returned string
note_id, then readgetnote note <note_id> -o json; do not truncate from the URL or convert it to a number.