Yunshang Knowledge Base

Use this skill when the user wants to:

把内容写入云商知识库
把聊天内容/文档沉淀到知识库
查询当前账号可访问的知识空间
查询目录/分类列表
查询空间里的知识文档
生成知识库完整结构目录
更新已有知识
删除知识文档

Guardrails

Always read config.json before doing anything.
Space visibility and space-level permissions are expected to be enforced by the server-side API key.
If allowedParentIds is configured, only write into those categories and only update/delete docs that belong to those categories.
If defaultSpaceId is configured, prefer it when the user does not name a target space.

First-use check

Open config.json and make sure these fields are filled:

baseUrl
appKey
appSecret
defaultSpaceId if the user usually works in one space
allowedParentIds only if you want to limit writes to specific directories
Leave uploadCommand blank to use the bundled NOS uploader by default
Only fill uploadCommand and uploadWorkingDir if you want to override the bundled uploader with another internal uploader

If config is blank, use config.example.json as the reference shape.

After the user fills appKey and appSecret for the first time:

Immediately run python3 scripts/yunshang_kb.py export-structure
This generates 知识库结构目录.md
Tell the user: 这是你的目录结构文档，您可以生成一个定时任务每天更新拉取结构，或者选择指定空间和目录导入文档，修改文档内容，或者删除文档。

Recommended: bundled NOS uploader

This skill bundles scripts/nos-upload.js and will use it automatically for local files and chat attachments.

The helper uploads the local file to NOS
The uploader returns a public CDN URL
Then it immediately calls Yunshang importDoc

This means end users only send a file; they do not need to prepare a URL.

Important:

The returned CDN URL is public
Do not use this uploader for sensitive documents

Alternate: custom uploadCommand

This OpenAPI imports by download URL, not by raw file bytes. If you want to replace the bundled NOS uploader, configure uploadCommand once.

uploadCommand should upload a local file to your internal NOS/OSS/CDN and print a downloadable URL to stdout.
The helper accepts placeholders:
- {file} absolute local file path
- {filename} file name with extension
- {basename} file name without extension
The uploader can print:
- a plain https://... URL on stdout, or
- a JSON object containing url, downloadUrl, data.url, or data.downloadUrl
The uploader can optionally include TTL metadata:
- expiresIn
- ttlSeconds
- expiresAt
- expireAt

If TTL metadata is present, the helper will reject links that are already expired or too close to expiration.

Core commands

Run the helper from this skill directory:

python3 scripts/yunshang_kb.py export-structure
python3 scripts/yunshang_kb.py list-spaces
python3 scripts/yunshang_kb.py list-docs --space-id 70055
python3 scripts/yunshang_kb.py list-categories --space-id 70055
python3 scripts/yunshang_kb.py import-doc --space-id 70055 --parent-id 52190 --file ~/.nanobot/media/abc123.md
python3 scripts/yunshang_kb.py import-doc --space-id 70055 --parent-id 52190 --title "团队 FAQ.md" --url "https://example.com/team-faq.md"
python3 scripts/yunshang_kb.py update-doc --space-id 70055 --doc-id 70919 --title "团队 FAQ.md" --url "https://example.com/team-faq-v2.md"
python3 scripts/yunshang_kb.py delete-doc --space-id 70055 --doc-id 70919

Depositing knowledge workflow

When the user says “把这个知识写入到云商知识库” or “把这个文档沉淀下来”:

Turn the finalized knowledge into a clean Markdown file when needed.
If 知识库结构目录.md is missing, or the user just finished first-time config, run export-structure first.
Resolve the target space from defaultSpaceId, the user request, or list-spaces.
If the category is unclear, query categories first.
Prefer importing from a local file path with import-doc --file ....
Let the helper upload the file and call Yunshang importDoc.

Attachment-first workflow

When a user sends a file to OpenClaw/nanobot:

Telegram messages are recorded like [file: /Users/.../.nanobot/media/xxxx.ext]
Discord messages are recorded like [attachment: /Users/.../.nanobot/media/xxxx.ext]
Prefer the downloaded local file path from the message and run import-doc --file /that/path
Do not ask the user to manually produce a URL if the bundled NOS uploader or a custom uploadCommand is available
If space/category is still unknown, ask only for those choices

If the user gives a local file path instead of a public URL:

Prefer --file /path/to/file.md.
The helper will use the bundled NOS uploader by default.
If uploadCommand is configured, it overrides the bundled uploader.
If neither the bundled uploader nor uploadCommand is available, stop and explain that the OpenAPI imports by download URL.

Choosing the right action

First-time onboarding / refresh full tree: export-structure
New knowledge/doc: import-doc
Replace an existing doc: update-doc
Remove obsolete knowledge: delete-doc
Confirm target space/category/doc first: list-spaces, list-categories, list-docs
For attached files, default the title to the file name unless the user gives a better title

References

For the exact endpoints and signing rule used by the helper, read references/openapi-summary.md. For the bundled uploader behavior, read references/nos-upload.md.

yunshang-kb