Unified IMA OpenAPI for Notes and Knowledge Base

Solving the Complexity of Notes and Knowledge Base Management

When developers integrate Tencent IMA's notes and knowledge base features, they often encounter issues like fragmented API calls, encoding problems, and cross-module coordination. For instance, improper UTF-8 handling during notes writing can cause irreversible garbled text; file uploads require strict title-filename matching; and interactions between notes and knowledge base modules need accurate routing to avoid confusion. The ima-skills skill simplifies these tasks through a unified OpenAPI layer, reducing redundant configurations and debugging efforts.

Core Capabilities and Key Steps

ima-skills supports two core modules: notes and knowledge-base. Core capabilities include:
- Notes Module Operations: APIs like import_doc and append_doc enable creating and appending content to notes, with support for searching, browsing, and content retrieval.
- Knowledge Base Module Operations: APIs like create_media and add_knowledge facilitate file uploads, webpage link additions, knowledge base searching, and information queries.
- Cross-module Coordination: For tasks involving both notes and knowledge base, such as noting content from the knowledge base, the skill reads knowledge-base/SKILL.md first, then notes/SKILL.md, and executes sequentially.

Key steps are as follows:
1. Credential Check: First, verify the existence of ~/.config/ima/client_id and api_key; if missing, guide users to set them up to prevent API call failures.
2. Intent Routing: Based on user input, decide whether to use the notes or knowledge-base module using a decision table. For example, "upload file to knowledge base" routes to knowledge-base, while "create new note" routes to notes.
3. API Calls: All requests are sent via the ima_api.cjs script using HTTP POST with JSON Body, targeting https://ima.qq.com.
4. Error Handling: Check two error layers—script execution errors (e.g., exit code -100 for program errors, -200 for updates needed) and backend business errors (e.g., code≠0)—providing direct feedback with the msg content.
5. Update Check: Automatically check for skill updates on the first API call each day to ensure the latest version is used, retrying the original request after updates.

Caveats and Applicable Boundaries

When using ima-skills, adhere to these mandatory rules to avoid operation failures:
- UTF-8 Encoding Validation: Before calling import_doc or append_doc, all string fields (e.g., content, title) must be validated for legal UTF-8, especially in scenarios like file reading, WebFetch scraping, or user input.
- File Upload Rules: During upload, the title must equal the file name (with extension) without renaming; unsupported file types like videos or URLs from Bilibili/YouTube must be immediately rejected, suggesting the IMA desktop client instead.
- PowerShell Compatibility: In PowerShell 5.1, the request Body is silently converted to GBK encoding; detect the version and use UTF-8 byte arrays for sending.
- Clear Module Decision: Correctly distinguish user intent—for example, "add note to knowledge base" actually associates a note with the knowledge base, routing to the knowledge-base module's add_knowledge.
- Cross-module Task Execution: When user intent involves both notes and knowledge base, read both sub-modules' SKILL.md files before execution to avoid missing steps.

These rules, though adding implementation details, ensure data reliability and operational stability, making ima-skills suitable for development scenarios requiring fine-grained control over IMA API integration.