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.

1. 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).
2. 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.