coze-docs-sync

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.

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.