Operate only after reading the real knowledge bases, permissions, and directories through the official CLI; do not guess IDs from names. Machine calls uniformly use -o json; only when the exit code is 0 and success=true is it a business success. All knowledge base, directory, blogger, and note IDs in the return are passed through as strings exactly as they are.
For the JSON of all API commands, first check success。success=false or when the exit code is non-zero, read error.code/message/reason/retryable and the optional request_id; do not say that creation, archiving, subscription, or deletion has been completed just because the API returned HTTP 200.
Intent routing
| Intent | Command entry |
|---|---|
| Owned/manageable knowledge bases | getnote kbs --scope <scope> |
| Knowledge bases I subscribe to | getnote kbs-sub --scope <scope> |
| Knowledge base notes | getnote kb <topic_id> |
| Create personal knowledge base | getnote kb create |
| Add note | getnote kb add |
| Remove note | getnote kb remove |
| Browse folders | gnote kb dir |
| Create folder | gnote kb mkdir |
| Rename/move folder | gnote kb mvdir |
| Delete empty folder | gnote kb rmdir |
| Blogger list | getnote kb bloggers |
| Blogger content list | getnote kb blogger-contents |
| Blogger content details | getnote kb blogger-content |
| Subscribe to Douyin blogger | getnote kb blogger-follow |
| Livestream list | getnote kb lives |
| Livestream details | getnote kb live |
| Subscribe to livestream | getnote kb live-follow |
| Use MCP temporary credentials to upload local files directly to OSS | getnote upload <file> |
| Query file constraints | getnote file-capabilities |
| Get upload token when CLI is logged in | getnote file-token <extension> |
| Submit OSS result into the library when CLI is logged in | getnote file-add <topic_id> <directory_id> |
gnote and short commands are stable aliases; when the old environment has no alias, fall back to getnote kb directories/directory-create/directory-update/directory-delete. Parameters are always based on the target command --help .
Select knowledge base and permissions
getnote kbsandgetnote kbs-subby default only queryDEFAULT. When the user explicitly wants books, customer profiles, or team knowledge bases, pass--scope BOOKSPACE、--scope CUSTOMER、--scope TEAMSPACErespectively; multiple Scopes cannot be mixed in the same paginated result.- When the user asks "the knowledge bases I manage/my knowledge bases", execute
getnote kbs --scope <scope> -o json; when asking "the knowledge bases I subscribe to", executegetnote kbs-sub --scope <scope> -o json. The subscription list only includes knowledge bases created by others and genuinely subscribed to by the current account, paginating through all pages byhas_morerespectively. - Match by name and
scope; when names are the same or the user's intent is unclear, let the user choose, do not guesstopic_id. When the target name could be either a knowledge base or a folder, ask clearly first. - Subscribed knowledge bases are usually read-only. If the list result explicitly returns a role or writable flag, judge by the real fields; when the current CLI contract does not guarantee permission fields, do not claim that it has been pre-checked as owner/admin, you may attempt to write after the user explicitly authorizes it, and faithfully handle permission failures.
- When an ordinary member's write fails, clearly state that permissions are insufficient, and do not attempt to bypass. Currently do not create team knowledge bases on behalf of the user.
Locate by book title and author, then select the content scope
When the user wants the highlights of a certain book or a certain author, first locate the book knowledge base, and do not treat the Top-K of semantic search as the full set.--query only matches knowledge base names or book titles,--author matches book authors; when both parameters are passed at the same time it is AND, not either one.
- "Find notes for 《a certain book》": pass
--query, put only the book title in the query term, and do not include "my notes", "all highlights", or the author's name. - "Find book notes by a certain author": pass only
--author, omit--query, then read according to the returned book libraries. When the user wants all books by that author, iterate through each library; only disambiguate when they want just one of them but the candidates are not unique. - "Find 《a certain book》 written by a certain author": pass both the book title
--queryand the author--author. Mistakenly passing the author keyword as query and getting an empty list cannot be interpreted as the user having no notes by that author.
# 只有作者线索,无需先猜书名
getnote kbs --scope BOOKSPACE --author '用户提供的作者' --all -o json
# 同时知道书名与作者
getnote kbs --scope BOOKSPACE --query '书名' --author '用户提供的作者' --all -o json
# 用户明确查订阅库时保持原有条件;只知作者仍只传 author
getnote kbs-sub --scope BOOKSPACE --author '用户提供的作者' --all -o json
# 只要划线 / 摘录
getnote kb '<返回的 topic_id>' --note-type ref --page-size 20 --all -o json
# 要这本书里的全部笔记:不加 note-type,避免漏掉读书心得等其它类型
getnote kb '<返回的 topic_id>' --page-size 20 --all -o json
getnote note original '<返回的 note_id>' -o json
- "All notes" and "all highlights" are not the same scope: add
--note-type refonly when the user explicitly asks for highlights/excerpts. When the user wants highlights for a certain chapter, verify against the candidatereference.location.chapter_name/chapter_id, and do not treat the chapter name as the book title; a missing field cannot prove that the chapter has no notes. - "Content in a book about a certain topic": after locating the book library, use
getnote search '主题' --kb '<topic_id>' --limit 10 -o json, and do not fall back to a global search and then attribute content from elsewhere to this book. When the search is empty or the results do not match the topic, usegetnote kb '<topic_id>' --page-size 20 -o jsonto search again within the same library; page through according to the real pagination, match the locating information first, and when truncated or insufficient, read the real body text/original text of the candidate details as needed. The discovery and deep-reading budget follows the search reference; exceeding the budget means the scope was not fully searched rather than determining that nothing exists. When the user asks for everything, verify item by item according to the complete pagination; Top-K cannot promise completeness. - When there is no match in one's own book library and the user has not restricted it to "only search mine", the real subscription book library may be queried, preserving the original scope/query/author/book-id; if the user explicitly says to search only the subscription library, use kbs-sub directly. A command error, insufficient permission, or parsing failure cannot be treated as an empty library, and the conditions cannot be removed and then claimed as a successful filter.
- When the author is unknown, omit
--author. First usename、scope=BOOKSPACE、book_info.title/author/book_idto verify the candidate; when multiple authors with the same name or multiple versions still make it non-unique, ask the user to choose, and do not substitute the first item. If a real book ID already exists,--book-idmay be added; it is not a knowledge base ID. - query/author will undergo NFKC, outer book-title-mark/quote, and case normalization, but this is not automatic word segmentation or fuzzy error correction. When the full name does not match, stable fragments from the user's original wording may be used to find candidates (such as the author's surname or a consecutive book-title fragment), then verify the complete book title/author; do not arbitrarily change the author, season number, or version, and do not silently ignore conflicting conditions.
BOOKSPACErepresents a book library and is not equal to everything coming from Dedao. When the user explicitly says "Dedao ebooks", verifybook_info.sourceand the referencedreference.source; do not treat books with the same title from other sources such as Douban as Dedao sources. When only a certain book is mentioned, do not arbitrarily add a platform restriction.- For ordinary knowledge bases, in the note's
topics[]there is still onlyid/name; only book associations additionally carryscope/book_info. Neither tags nor knowledge base names can replacereferenceas source evidence. - For a new query, verify
meta.capabilities(knowledge.lookup.v1、pagination.v1; note filtering also requiresnote.filters.v1, and citation filtering also requiresnote.reference.v1) andapplied_filters. The CLI will reject unsupported or unapplied conditions; the conditions must not be removed and then unfiltered results handed in as the answer. The list returns only locating information; when complete content is needed, callnote_idaccording togetnote note。 - The
stats.note_countof a candidate knowledge base may lag and does not represent the number of highlights after filtering; the answer is based on the paginated results verified this time and the deduplicated IDs. --allonly when the exit code is 0,success=true、data.traversal.completed=trueandpagination_verified=trueOnly then can it be confirmed that the traversal of the current authorized scope is complete. Deduplicate by string note ID;traversal.returned_countis the number actually retrieved this time,traversal.total_count=nullstill indicates that the server-side exact total is unknown. The oldtotalretains compatibility semantics and cannot be used as the new filtered total.- Manual pagination or MCP: keep scope, all filters, and page_size unchanged; continue as-is by
pagination.next_page/next_cursoruntilhas_more=false. Record the page numbers/cursors and note IDs already visited; loops, empty pages that still claim to have a next page, repeated results with no progress, or failures midway cannot be claimed as "all found." - The library not existing, no matches, or no highlights in the library does not mean the account has no references from that book's source. When the user has explicitly obtained the ebook, you can use
getnote notes --source dedao --note-type ref --reference-type ebook --page-size 20 -o jsonto supplement the search by source, matching inreference.title/author/book_id; continue according to the budget and pagination rules in the search reference, and if necessary use the realreference.resource_idfor exact filtering. Draw conclusions only for the current authorized scope; do not create new libraries or modify ownership.
Folder and archive workflow
- When the user requests placement into a folder, use
gnote kb dir <topic_id> -o jsonto read the root directory or the specified directory. - For an existing folder, use
data.directories[].idto return the real directory ID; when browsing a specified directory, pass that value to--directory-id. If missing, first ask whether to create it, then usemkdir。 getnote kb addwhile passing the realtopic_id, the stringnote_id, and the directory parameters specified in the CLI help.- At most 20 items per batch. Removing notes and deleting directories must be confirmed first; deleting a directory must also be verified as empty by the CLI/service.
- When moving or renaming, change only the items specified by the user; unspecified names or parent directories remain unchanged.
Direct local file upload (MCP authorized)
- Use the authorized MCP to obtain file capabilities and a temporary upload token; accept only the formats and sizes currently allowed by the capability interface. Do not hardcode the format list; Markdown is currently disabled. If MCP does not yet provide this tool, state that clearly; do not guess the tool name or claim it is already supported.
getnote upload <file> --token-file <受控临时文件> --max-size-bytes <该格式上限>Only uploads directly to OSS, and does not read or require a CLI identity token. The token can also be passed via stdin; credentials must not be placed in command parameters, chat content, or logs. When installing the CLI only for uploading files, do not executeauth loginorsetup。- returns
stage=oss_uploadedonly indicates that the file bytes have been uploaded; pass thefile_name/file_type/md5/urlfrom the machine result to the knowledge base ingestion tool under the same authorization, together with the realtopic_id、directory_id. The cloud MCP must not receive file bytes, and arbitrary commands in the token content must not be executed. - Query the resource list and confirm the same resource
status=SUCCESSbefore saying it has been ingested;CONVERT/ANALYZINGmeans processing; failures should report the reason. On timeout, recheck the existing ID and do not upload again. When file upload is not requested, continue using the cloud MCP and do not require installing the CLI.
When CLI authorization already exists, you can use getnote file-capabilities -o json、getnote file-token <extension> -o json to obtain the same capability and token, then ingest with getnote file-add <topic_id> <directory_id> --metadata-file <upload-result.json> -o json . When only MCP is authorized, do not ask the user to log in again for these two authentication commands; just use the corresponding MCP tools. Temporary token file permissions are limited to the current user.
Bloggers and livestreams
- When the user provides a Douyin homepage and requests ongoing following, first confirm the target knowledge base and write permission, then use
blogger-follow; when only looking for a certain piece of content, query first and do not create a subscription. - The list first returns the blogger/livestream name, the real string ID, and the necessary status; after selection, read the full content.
- In the blogger content details, the
post_media_textis the complete original text; do not pass off a summary as the original.
Result and reply format for each command
| Command | Successful results must include | Reply rules |
|---|---|---|
getnote kbs --scope <scope> -o json |
success=true、data.topics[].topic_id/name/scope/stats、has_more/total |
The default scope is DEFAULT; for special types, scope must be passed explicitly. |
getnote kbs-sub --scope <scope> -o json |
success=true、data.topics[].topic_id/name/scope、has_more/total |
Only return other people's knowledge bases that are actually subscribed under that scope, usually read-only. |
getnote kb <topic_id> -o json |
success=true、data.notes[].note_id/title/note_type、has_more/total |
Return the actual notes in the knowledge base; when links are needed, use note to read the details. |
getnote kb create <name> -o json |
success=true、data? |
when no ID is returned. topic_id。 |
getnote kb add <topic_id> <note_id…> -o json |
success=true、data? |
At most 20 items; when the final directory ownership needs to be confirmed, read the directory again. |
getnote kb remove <topic_id> <note_id…> --yes -o json |
success=true、data? |
At most 20 items; confirm first, then state that they have been removed from that knowledge base. |
gnote kb dir <topic_id> -o json |
success=true、data.current_directory?、directories[].id/name、resources[].id/directory_id/note_id?/name/type/status、total |
Read the directory primary key with directories[].id; read resource ownership with resources[].directory_id, verify note resources with resources[].note_id ; fall back in old environments to getnote kb directories。 |
gnote kb mkdir <topic_id> --name <name> -o json |
success=true、data? |
It is also compatible with positional parameters <name>; the two must not be used at the same time. If a new directory ID or hierarchy needs to be given, read the directory again afterward. |
gnote kb mvdir <topic_id> <directory_id> … -o json |
success=true、data? |
Only confirm the rename/move specified by the user; when the final name or parent is needed, read the directory again. |
gnote kb rmdir <topic_id> <directory_id> --yes -o json |
success=true、data? |
Only delete empty directories; before stating that something has been deleted, business success must be obtained. |
getnote kb bloggers <topic_id> -o json |
success=true、data.bloggers[].follow_id_str/account_name/platform、has_more/total |
Use follow_id_str in the list as the ID for subsequent queries. |
getnote kb blogger-follow <topic_id> <link> -o json |
success=true、data.follow_id_str/url/platform/type/created_at |
State the platform and object actually subscribed to; first confirm that the target knowledge base has write permission. |
getnote kb blogger-contents <topic_id> <follow_id> -o json |
success=true、data.contents[].post_id_alias/post_title/post_publish_time、has_more/total |
Return the title and summary; before reading the full text, let the user choose the specific content. |
getnote kb blogger-content <topic_id> <post_id> -o json |
success=true、data.post_title/post_summary?/post_media_text?/post_url?/post_publish_time |
post_media_text is the complete original text; a summary cannot replace it. |
getnote kb lives <topic_id> -o json |
success=true、data.lives[].live_id/name/status、has_more/total |
First list the actual livestreams, then read the details according to the user's choice. |
getnote kb live <topic_id> <live_id> -o json |
success=true、data.post_title/post_summary?/post_media_text?/post_publish_time |
post_media_text is the livestream original text/transcript; when it is unavailable, do not fill it in from the summary. |
getnote kb live-follow <topic_id> <link> -o json |
success=true、data.follow_id_str/url/platform/type/created_at |
State the actual subscription object and platform. |
Failures such as insufficient permissions, non-empty directories, and batch limits being exceeded must be explained as they are, without fabricating a downgraded success; preserve request_id and retryable。
Actions after completion, processing, and failure
kbs、kbs-sub、kb、dir, an empty list of bloggers and livestreams means there are no results for this query; check the filters, pagination, and the stated supplementary query path according to the user's goal, then state that “nothing was found within this scope”; do not directly say that the account does not have any, and do not automatically create a knowledge base, directory, or subscription.kb create、kb add、mkdir、mvdirFor write operations such asdatamay not provide the complete object due to different service versions. Only confirm that the action has been submitted whensuccess=true; if a new directory ID, final hierarchy, or note ownership is to be returned to the user,gnote kb dirorgetnote kb <topic_id>must be read again immediately afterward; do not guess fields.kb addEven if the request succeeds, do not describe “join initiated” as “has entered a certain directory”; only after reading again can the final ownership be shown if, in the same item ofresources[], the corresponding stringsnote_idanddirectory_idappear.kb remove、rmdir, there must be explicit user confirmation and it must include--yes; ifreason=knowledge_directory_not_empty, clearly prompt “the directory is not empty; please move out the contents or delete the subdirectories first”, and do not retry the original request. Other failures should also explain the real reason and the next step, and never claim that deletion has been completed.- The absence of a knowledge base from the list on a certain page or under a certain scope does not directly imply insufficient permissions; first check the scope, the complete pagination, and the owned/subscribed ranges. Only an actual returned permission error indicates no access; do not substitute a personal knowledge base item with the same name for a team knowledge base.
- "This note" can only reuse the string
note_idthat has already been returned by the CLI and verified in the current session. When there is no reliable context, first ask the user to provide the note ID; do not guess from unsupported private links, titles, or numeric conversions of snowflake IDs.