| name | coze-docs-sync |
| version | 1.0.0 |
| description | Mirror the official Coze docs (docs.coze.cn) to local Markdown, preserving the site's exact directory tree. Use whenever the user wants to sync / update / pull / archive Coze (扣子) docs, grab every page of a docs space (cozespace, guides, tutorial, …), or needs an offline copy of the Coze documentation. Works without a browser or login: it calls the same arcosite API the site uses — GetBusStructureById for the nav tree, then /api/open/docs/{business_id}/{_id} for each page's raw Markdown (the "open markdown" button) — and writes a numbered directory mirror. Idempotent: a manifest tracks output so each run reconciles local with live (stale files removed).
|
| license | MIT |
Coze Docs Sync
Mirror a Coze documentation space (docs.coze.cn/<space>/...) to local Markdown, following the
site's left-nav directory structure. Every run treats the live site as the source of truth.
When to use
- "同步 / 更新 / 拉取扣子文档" — sync, update or pull the Coze docs
- Grab every page of a space for an offline / version-controlled copy
- Refresh a previously synced tree after the docs change upstream
Run it
From the skill directory (paths below are relative to this skill dir):
node scripts/sync.mjs --out <target-dir>
If the user gives no specific output location, don't pass --out — the script defaults to a
coze-docs/ subdirectory under the current working dir, so the docs stay wrapped in one folder
instead of scattering into the project root. Only pass --out when the user asks for a particular
path.
Common flags:
| Flag | Default | Meaning |
|---|
--space <path> | cozespace | Doc space, the docs.coze.cn/<space>/... URL segment |
--out <dir> | ./coze-docs | Output root (a subdir under the current working dir) |
--business-id <id> | looked up from --space | Space id directly (for spaces not in the table) |
--concurrency <n> | 5 | Parallel body downloads |
Known spaces: cozespace (扣子使用文档), guides (扣子编程), tutorial, developer_guides,
dev_how_to_guides, cozeloop, customers, coze_pro.
Output layout
Mirrors the site tree. Directories are named by their Chinese title; pages are NN-标题.md; the NN
prefix preserves site ordering. Each body gets a > 来源：<url> line inserted after its H1.
01-了解扣子.md
02-快速开始/
01-开始使用扣子.md
03-Agent/
01-定制 Agent/
01-概述.md
02-扣子 Agent.md
02-使用 Agent/
09-技能/
...
Idempotency
The script writes .coze-sync-manifest.json in the output root listing every path it produced. The
next run deletes paths from the old manifest that no longer exist upstream, so local stays in sync
with live. The first time you point it at a directory that already holds hand-made folders, delete
those by hand first — the manifest takes over from then on.
How it works (reverse-engineered from the site bundle)
No browser, no auth required.
- Nav tree —
POST /api/open/playground/doc with headers
x-arcosite-action: GetBusStructureById, x-arcosite-content (= md5 of the body), and
authorization (an arcosite HMAC-SHA1 signature). Body: {app_id, business_id, req_source:"site"}.
The client AK/SK are the literal "*"; the server-side proxy fills in the real keys, so the call
works unauthenticated. Returns the nested tree (title / path / is_dir / subs / _id).
- Page body —
GET /api/open/docs/{business_id}/{_id} returns raw Markdown (the address behind
the "打开 markdown" button on each page).
app_id and the per-space business_id values are hard-coded at the top of
scripts/sync.mjs, lifted from docs.coze.cn's index.*.js. If Coze ships a
redesign that breaks the API, re-inspect that bundle around setOpenAPIConfig, cryptoSignature,
and /api/open/docs/ to repair it.
Requirements
- Node 18+ (uses global
fetch and node:crypto). No npm install, no dependencies.
