The Kingsoft Docs CLI Skill provides a complete set of online document operation tools, interacting with the Kingsoft Docs API through the kdocs-cli command-line tool. It supports creating, querying, reading, editing, sharing, and moving various types of online documents.
Strict Rules
NEVER
- NEVER allow the Token to appear in plaintext in conversations, logs, command output, code comments, or any files; the Token may only be saved to the system keychain via
kdocs-cli auth set-tokenorkdocs-cli auth loginto save it to the system keychain - The
content_base64that must be passed to interfaces such as upload and write may be very large (over 1 MB after encoding); never generate a Base64 string token by token in the conversation—use a script to read the file, encode it, and pass the parameter - When permissions are insufficient, never retry or bypass; immediately inform the user that they lack permission
MUST
- Before performing irreversible operations (delete/close types), confirmation from the user must be obtained
- After creating a cloud document file and verifying it passes, an accessible link must be shown to the user. If the response contains
data.link_url, display it directly; if the response has no link, callget_file_linkto obtain and display it. - Except for the main-path tools for which SKILL.md already provides minimal usable examples, before calling other tools you must first read the corresponding
references/detailed reference documentation; parameter details (types, allowed values, constraints) are subject to the tool reference documentation - When the trigger conditions of the "Problem Feedback" section are met, you must run the feedback command and display the complete feedback link, and comply with the anti-duplication rules of that section; it is forbidden to merely verbally tell the user to contact customer service or to end the conversation with only "not currently supported"
Keep the latest version
When to trigger:First use Skill / More than 24h since the last self-check / Received unknown action or unknown service error。
- CLI version：
kdocs-cli version— if the command does not exist, install it according to "Tool Installation and Authentication" below; if it is lower than the frontmatterversionin this file, runkdocs-cli upgrade -y(automatically backs up the old version; on failure you cankdocs-cli upgrade --rollback） - Skill version: if the
versionin this file is lower thankdocs-cli version, runkdocs-cli call check_skill_update version=2.6.17 skill_name=kdocs; if it returnsupdate_available: true, extract the zip download link frominstruction, download and unzip it to replace the current Skill directory
If both upgrade and rollback fail, re-run the installation script in this Skill directory (bash setup.sh / powershell setup.ps1 / node setup.cjs; the script is located at scripts/) to reinstall from the CDN. If it still cannot be updated, rely on the toolset actually supported by kdocs-cli --help .
Tool Installation and Authentication
| Operation | Command |
|---|---|
| Install | bash scripts/setup.sh / powershell scripts/setup.ps1 / node scripts/setup.cjs |
| Authenticate | User has provided a Token: kdocs-cli auth set-token "<token>" · No Token: kdocs-cli auth login |
For the manual acquisition process when login fails,auth status diagnostics,auth logout logout, etc., see references/auth.md。
Invocation format
kdocs-cli [parameters]
Parameter passing
| Parameter characteristics | Recommended method | Example |
|---|---|---|
| Simple value (no Chinese) | key=value | kdocs-cli drive search-files keyword=test type=all |
| Array/object, short JSON | JSON string | kdocs-cli sheet query-records '{"file_id":"xxx","filter":{}}' |
| Array/object, or contains Chinese/newlines/>200 characters | --file | kdocs-cli otl insert-content --file payload.json |
| Script pipeline integration | stdin | node gen.js | kdocs-cli otl insert-content - |
--file/ stdin input must be that tool'scomplete JSON parameter object- Chinese/multiline parametersForbidden key=value (Windows/PowerShell corrupts UTF-8 encoding)
- Generate JSON files with Node.js/Python;Forbidden ConvertTo-Json (output includes BOM)
- PowerShell must backslash-escape JSON strings:
'{\"key\":[\"val\"]}'
--file example: When writing large blocks of content, use a script to generate a JSON file and then
--filepass it in, and delete the temporary file after the operation is complete:const fs = require('fs'); fs.writeFileSync('payload.json', JSON.stringify({ file_id: "<file_id>", content: fs.readFileSync('article.md', 'utf8'), format: "markdown", mode: "append" }), 'utf8');kdocs-cli otl insert-content --file payload.json --silent// 操作完成后清理临时文件 fs.unlinkSync('payload.json');
Global options：
| Option | Description |
|---|---|
--token <token> |
One-time Token (highest priority, not persisted) |
--endpoint <url> |
Override the default endpoint |
--compact |
Output compact JSON |
--silent |
Output only the data field |
--verbose |
Output request details to stderr |
--timeout <ms> |
HTTP request timeout (milliseconds, default 30000) |
Help：kdocs-cli --help、kdocs-cli <service> --help、kdocs-cli <service> <action> --help
Command not found? Browse
--helpIf you find that an expected service or action does not exist, first runkdocs-cli upgrade -yto upgrade to the latest version and try again. CLI capabilities continuously expand with versions, and not upgrading is the primary cause of missing commands. See the "Stay on the latest version" section above for details.
Read/write main paths
Use read_filefor reading and create_file_with_contentfor writing. Other tools⚠️ Do not skip the reference and call directly(violating this will inevitably cause parameter errors); the tool overview is only for routing selection, and before calling you must read the corresponding references/ documentation.
Read:read_file
read_file is the main entry point for reading content; for the location parameter url / link_id / file_id , choose one of three:
kdocs-cli drive read-file url="https://www.kdocs.cn/l/xxx"
Choose one parameter based on the existing location information: if the user provides a full link, pass url; if a share link has been parsed, pass link_id; if the file ID is already available, pass file_id. Do not pass multiple location parameters at the same time.
When the first request returns status=pending , carry the task_id from that response and the original read parameters to request again, and the full document content will be returned:
kdocs-cli drive read-file file_id=file_xxx task_id=task_xxx
task_id must come from this response; guessing or reusing across requests is forbidden.
You must check the data.warningsin the return: the table may only read the default worksheet or the first-screen area, and warnings will indicate the actual read range.
Embedded images in smart documents (.otl): By default, read_file returns only the ![image]() empty placeholder. For complete steps, see references/otl.md"Common workflows → Reading embedded images in smart documents".
kdocs-cli drive read-file link_id=xxx enable_upload_medias=true
If content still contains an empty placeholder ![image](), do not stop; instead read references/otl.md"Common workflows → Reading embedded images in smart documents".
Write:create_file_with_content
create_file_with_content is the main path for "create and write content". When the target directory is clear, pass only parent_id(folder id); when no directory is specified, both the drive and the directory may be omitted (defaults to the personal cloud drive root).
kdocs-cli drive create-file-with-content --file payload.json
payload.json：
{
"name": "周报",
"file_extension": "otl",
"content": "# 周报\n\n这里是正文"
}
| Suffix | Key Parameters |
|---|---|
.otl .docx .md .pdf |
name + file_extension + content |
.xlsx .ksheet |
name + file_extension + sheet_name + rangeData |
.dbt |
name + file_extension + sheet_name + fields + records |
The table's rangeData root node must be an array, each item is an object,formula must be a two-dimensional array; do not mix sheet.update_range_data of {range, values}：
payload.json：
{
"name": "台账",
"file_extension": "xlsx",
"sheet_name": "Sheet1",
"rangeData": [{
"row_from": 0,
"row_to": 0,
"col_from": 0,
"col_to": 1,
"formula": [["姓名", "部门"]]
}]
}
Reference Documentation (read as needed)
When you need to supplement parameter descriptions or troubleshoot call errors, you can read:
read_file：references/drive/read_and_download.mdcreate_file_with_content：references/drive/create_and_upload.md
Read the reference documentation using the complete paths above; do not guess file names.
The following tools are irreversible and must be confirmed with the user before calling (for detailed constraints, see the "Operation Constraints" section of each tool's reference documentation):
otl.block_delete、dbsheet.delete_sheet、kwiki.close_knowledge_view、sheet.delete_sheets、sheet.delete_range_data、dbsheet.delete_view、dbsheet.delete_fields、cancel_share、kwiki.delete_item、sheet.delete_protection_ranges、dbsheet.delete_records、sheet.delete_data_validations、cancel_collaborator_permissions、sheet.delete_conditional_format_rules、sheet.delete_float_images、sheet.delete_filters、dbsheet.sheet_batch_delete、sheet.delete_pivot_table、dbsheet.permission_delete_roles_async、dbsheet.innerdoc_block_delete、dbsheet.innerdoc_block_batch_delete
Capability Scope
Operation Domain Routing
The Agent first determines the operation domain of the user request:
When entering "Partial Update" or "Type-Specific Capabilities" and the suffix/type is unknown: first use
references/file-locating-guide.mdto confirm the type, then open the reference for the corresponding type; do not guess the call. Reading/creating/file management does not require this first.
| Operation Domain | Trigger Scenario | Routing |
|---|---|---|
| Create/Write | Create and write, upload local files, create blank documents | For the main path, see "Read/Write Main Path" above; for uploading local files and creating blank documents, see references/drive.md |
| Partial Update | Modify blocks/paragraphs/cells, modifications on an existing target document | According to "Supported Document Types" → the write/update tools in the corresponding reference |
| Type-Specific Capabilities | Conditional formatting, export conversion, translation, PDF splitting, slide themes, data validation | According to "Supported Document Types" → the dedicated feature chapters in the corresponding reference |
| Read | Read/extract/export document content | Body:read_file（url/link_id/file_id, see references/drive/read_and_download.md）；.otl embedded images → references/otl.md"Common Workflows → Read Embedded Images in Smart Documents"; otherwise follow "Locate File" |
| Locate File | Search/look up file identifiers or attributes by link/browse directories | See references/file-locating-guide.md; view my cloud drive → references/drive/read_and_download.md（drive.list_my_files） |
| File Management | Move/rename/share/tag/favorite/recycle bin/comments/document library/historical versions/save as | → references/drive.md |
| AI Generation | AI makes PPT/generates presentations | → references/aippt.md |
| Knowledge Base | Knowledge base space/import/organize | → references/kwiki.md |
Supported Document Types
| Type | Alias | File Suffix | Description | Detailed Reference |
|---|---|---|---|---|
| Smart Document Preferred | ap | .otl | Beautiful layout, supports rich components | references/otl.md — operations on elements such as pages, text, headings, to-dos, etc. |
| Table | et / Excel | .xlsx | Dedicated to data tables | references/sheet.md — worksheet management, range data retrieval, batch updates |
| PDF Document | Dedicated to PDF documents | references/pdf.md — PDF creation and content reading |
||
| Text Document | wps / Word | .docx | Traditional format | references/wps.md — Word document creation and content operations |
| Presentation | wpp | .pptx | Dedicated to PPT documents | references/wpp.md — Slide theme font and color settings, download and export |
| Smart Sheet | as | .ksheet | Structured spreadsheet, supports multiple views and field management | references/sheet.md — Worksheet management, range data retrieval, batch updates |
| Base | db / dbsheet | .dbt | Multiple data tables, rich field types and views (grid/kanban/gantt, etc.) | references/dbsheet.md — Supports full CRUD for data tables/views/fields/records, including form views, parent-child records, sharing and collaboration, advanced permissions, and Webhook |
| Smart Form | form | .form | Lightweight form draft creation, question configuration, publishing, and querying | references/form.md — Draft creation/update/publishing and form information querying |
High-frequency workflow guide
Create/Write
| User intent | Tool | Applicable suffix / Description |
|---|---|---|
| Only need a blank document | create_empty_file |
.doc .docx .otl .dbt (default columns) .xlsx .xls .ksheet .pptx .ppt |
| Existing body text or table data to be written | create_file_with_content |
.otl .docx .pdf .xlsx .ksheet .dbt |
| Create a new Base and must customize columns | create_file_with_content |
.dbt (fields+records required even without business data) |
| Create a local Markdown as an office document | create_file_with_content |
.otl .docx .pdf; only use for .md as-is upload_new_file |
| Create a cloud document by uploading a local file | upload_new_file |
.doc .docx .xls .xlsx .ppt .pptx .pdf .md .txt .html .zip .png .jpg .jpeg .csv .json .dps .et .wps .gif |
| AI-generated PPT | aippt.execute |
.pptx |
When the suffix is uncertain, default to .otl. When specifying a folder, first use references/file-locating-guide.md to get drive_id、parent_id。
After selecting a tool, read references/drive/create_and_upload.md the corresponding section for parameter constraints (aippt.execute see references/aippt.md）。
Search and locate documents
Tool description:search_files(keyword="关键词", page_size=10) to search (type can be omitted, default all); get file_id、drive_id for use in subsequent chains.
type is the search dimension (file_name/content/all); to filter folders/files, use file_type.
For detailed parameters and return structure, see references/drive/search.md。
More operation workflows
| Workflow | Description | Detailed reference |
|---|---|---|
| Read Base cloud document metadata | Extract the file_id of the cloud document field from Base records, then call get_file_info to get metadata (file name, size, type, modification time, etc.) | references/workflows/read-cloud-doc-meta.md |
| AI-generated presentation (full text) | aippt.execute single-interface full-text generation workflow: supports two modes, html (two calls + follow_up) and basic (one call, classic minimalist mode), covering theme/document scenarios | references/workflows/aippt-full-text.md |
| AI single-page slide generation | aippt.execute single-interface single-page slide generation: HTML layout mode, completed in one call, can be inserted into an existing presentation via wpp.import_slides | references/workflows/aippt-single-page.md |
| Web clipping | Capture web page content and automatically save it as a smart document | references/workflows/web-scrape.md |
| Search-Read-Report writing | Search multiple documents, extract information, and summarize to write a new report | references/workflows/search-read-report.md |
| Scheduled reading and broadcasting | Regularly read specified documents, extract key information, and generate summaries | references/workflows/periodic-read-summary.md |
| Smart classification and organization | List directories, create folders by content or specified dimensions, and archive | references/workflows/smart-classify.md |
| Precise search and risk investigation | Batch search documents in a specified directory, read and analyze them one by one, and summarize into a new document | references/workflows/precise-search-analysis.md |
| Import slides from cloud documents | Import specified slides from an external PPTX file into an existing presentation | references/workflows/import-slides.md |
| Convert sign-up chain to table | Recognize sign-up chain text content, automatically extract and convert it into an online table | references/workflows/jielong-to-table.md |
| Cross-table field backfill (matched by primary key) | Match two tables by primary key column (such as order number, enterprise ID, SKU), and write the specified columns of the source table into the corresponding columns of the target table; you must first read the headers to locate by column name, and after writing, read back by column name to verify | references/workflows/sheet-cross-fill.md |
| Form collection | Design and create a smart form according to user requirements, and generate a filling link after publishing | references/workflows/form-collection.md |
| Intelligent knowledge organization | Intelligently organize and structurally reorganize scattered content in the knowledge base | references/workflows/knowledge-format.md |
| One-click knowledge save | Save various types of content (web pages, files, text) to the knowledge base with one click | references/workflows/knowledge-save.md |
| Table beautification and data standardization | Read table data, perform format beautification, data standardization, and style adjustment, and solidify rules through conditional formatting, data validation, and range permissions | references/workflows/table-beautify.md |
Quick error reference
| Error feature | Cause | Handling method |
|---|---|---|
400006 / Authentication failed |
Token expired or not configured | Run kdocs-cli auth login to log in again, or kdocs-cli auth set-token <token> to reset |
429001 / Rate limited |
Requests are too frequent, response containsrate limit recovery time | Immediately stop command calls until the recovery time is reached; do not immediately retry, change parameters, or continuously request with different subcommands |
429002 / Circuit broken |
Multiple consecutive triggers within a short time due to 429001 , response containscircuit breaker duration |
Make zero requests during the circuit breaker period, and try again after it expires; replan the task to avoid overly frequent requests |
403 / Insufficient permissions / 无权访问 / forbidden |
The current credentials have no operation permission for the target document, directory, or resource | Stop the operation; do not retry or attempt to bypass with other interfaces; inform the user that the current account has no permission, and suggest contacting the document owner to grant permission, confirming the sharing link permissions, or switching to an account with permission |
unknown action / unknown service |
CLI version is too old or the name is misspelled | First run kdocs-cli upgrade to upgrade to the latest version; if it still reports an error, then run kdocs-cli <service> --help to confirm available commands |
| No search results | Keywords too precise / index delay | Shorten keywords / wait 3-5 seconds and retry |
| Read content is empty | The file has no content or the format is not supported | Confirm that the file is not empty and the extension is correct |
| Third-party service error: task does not exist | Used an invalid, cross-request, or completed task_id |
If the previous attempt already returned complete content, use the existing result directly; otherwise discard the old task_id, and reread according to the original file positioning parameters |
| Failed to create file | Incorrect file name extension | Check the extension:.otl / .docx / .xlsx / .ksheet / .dbt / .pdf / .pptx |
| Failed to move file | The target folder does not exist | Search first to confirm or create the folder |
Client.Timeout exceeded while awaiting headers |
Server-side processing or queueing time exceeds the CLI HTTP timeout, commonly seen in slow operations such as uploads, exports, AI generation, format conversion, and large file reads | After confirming the tool's idempotency, retry once, and explicitly set the --timeout value (e.g., --timeout=120000); for write/create-type tools, query the result before retrying to avoid duplicate creation |
conflict / lock / concurrent write conflict |
Multiple write operations modifying the same resource (knowledge base nodes, multi-dimensional table records, etc.) at the same time cause lock contention | Retry with exponential backoff (2s → 4s → 8s, up to 3 times); for batch write scenarios, switch to serial execution one by one; see the "Error Quick Reference Table" in each kwiki / dbsheet reference for details |
| HTTP 5xx | Server-side failure | Wait 3 seconds and retry once |
| Validation failed (read-back value does not match expectation) | Write did not take effect or was delayed | Wait 2 seconds and re-validate; if it still fails, report to the user |
setup.sh execution failed / installation error |
The current version may no longer be compatible | Execute the "Keep the latest version" process above |
| The CLI interface returns an unknown error code (not 5xx, not 400006, not 429001/429002, not tool does not exist) | The Skill version is too old, causing interface incompatibility | Execute the "Keep the latest version" process above; if it still fails, go to kdocs-cli feedback |
The error message contains version、incompatible、not_supported、deprecated and other version keywords |
Skill or API version incompatibility | Execute the "Keep the latest version" process above; if it still fails, go to kdocs-cli feedback |
| Tool call failed and the reason is unknown | The Skill version may be too old | Execute the "Keep the latest version" process above; if it still fails, go to kdocs-cli feedback |
| All the above handling methods have been tried and the issue still cannot be resolved | Unknown issue | If it still fails, then kdocs-cli feedback |
| When a tool call fails, it is necessary to determine whether it can be retried | Different tools have different idempotency | Check the idempotency description in the "Operation Constraints" section of the tool's reference documentation; idempotent tools can be safely retried, while non-idempotent tools must have their status confirmed first |
Issue feedback
When any of the followinganyconditions is met, a feedback link MUST be provided.Definable exceptionThere is no need to first exhaust the error quick reference table.
Definable exceptions (link required): Missing functionality, tool does not exist, format/type not supported, interface/parameter not supported, results not up to standard (read-back validation failed and cannot be corrected), permission/account restrictions (after informing the reason), search/query returns no results (retrieval conditions have been adjusted at least once and the task still cannot continue).
Errors and fallback: The current error handling steps (including limited retries) have been completed and it still fails.
User-initiated: Requests feedback, complaints, problem reports, or submits feature requests.
Guidance: For bugs/exceptions, use "Welcome to provide specific issue feedback";Feature requestUse "Welcome to tell us what you want to achieve through the feedback link." When a feature is missing or unsupported, do not end with only "not currently supported"; a feedback link must be included.
Run kdocs-cli feedback(optional --reason <trigger_reason> for statistics), display the full stdout URL to the user, and tell them "click to open the feedback page."
When a complex task is partially successful and the user may have suggestions for improvement, a feedback link may be included at the end of the reply; it does not need to be shown every time for simple everyday successes.
Anti-duplication (MUST comply):
- Each reply may display at most 1 feedback link; once displayed, do not obtain the link again within the same reply.
- Within the same session, for the same root cause (the same type of blockage, such as the same unsupported format or the same missing capability), the link only needs to be provided once; for subsequent similar situations, explain in text and you may remind the user to reuse the link already provided.
- After the user has indicated that they do not need feedback or has acknowledged it, do not proactively post the link again in this session; unless the user requests it again or a new blockage with a different root cause occurs.
- "Search/query returned no results" counts as MUST only after the search conditions have been adjusted at least once and it is still impossible to continue.
Security constraints
- Credentials are managed by the
kdocs-clisystem keychain; the Skill itself does not store or record them - Stateless agent, does not cache any document content or business data
- Only calls the corresponding API when the user actively initiates an operation