coze-docs-sync

A Claude Code / agent skill that mirrors the official Coze docs (docs.coze.cn, 扣子) to local Markdown — preserving the site's exact left-nav directory tree, one .md per page.

No browser, no login, no scraping of rendered HTML. It calls the same internal arcosite API the site itself uses, so you get the original Markdown source of every page, cleanly, in seconds.

GetBusStructureById  ──▶  the full nav tree (titles, paths, dirs, page ids)
        │
        ▼
/api/open/docs/{business_id}/{_id}  ──▶  raw Markdown for each page
        │                                 (the "打开 markdown" button)
        ▼
local mirror: 03-Agent/02-使用 Agent/09-技能/01-技能概述.md  +  > 来源：<url>

Highlights

• Exact directory mirror — folders by section title, pages as NN-标题.md; the NN prefix keeps the site's ordering.
• Original Markdown — the page source, not HTML converted back to text.
• Idempotent — a .coze-sync-manifest.json tracks output; each run reconciles local with live and removes pages that disappeared upstream.
• Zero dependencies — one Node file, global fetch + node:crypto. Nothing to npm install.

Install as a skill

Use the skills CLI — it detects your agent (Claude Code, Cursor, Codex, …) and links the skill into the right place:

# global (user-level), available in every project:
npx skills add -g LcpMarvel/coze-docs-sync

# …or project-level, into the current repo only:
npx skills add LcpMarvel/coze-docs-sync

Manual install (clone + symlink)

git clone https://github.com/LcpMarvel/coze-docs-sync.git

# Claude Code (user-level skills):
ln -s "$(pwd)/coze-docs-sync" ~/.claude/skills/coze-docs-sync

Once installed, the skill triggers automatically when you ask your agent in natural language:

• "同步一下扣子文档" · "更新本地的 Coze 文档"
• "把 docs.coze.cn 的编程文档拉到本地"
• "Sync the Coze docs to ./coze-docs"

The agent reads SKILL.md, picks the space and output dir, and runs the script for you.

Quick start (no install)

Run it directly, no skill registration needed:

git clone https://github.com/LcpMarvel/coze-docs-sync.git
node coze-docs-sync/scripts/sync.mjs        # → ./coze-docs/

With no --out, it writes to a coze-docs/ subdirectory under the current dir rather than scattering files into the project root. Sync a different space, or point somewhere else:

node coze-docs-sync/scripts/sync.mjs --space guides --out ./coze-编程文档

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 below
--concurrency <n>	5	Parallel body downloads

Known spaces

--space	Content
cozespace	扣子使用文档 (default)
guides	扣子编程
tutorial	教程
developer_guides	开发者指南
dev_how_to_guides	开发实践
cozeloop	扣子罗盘
customers	客户案例
coze_pro	扣子专业版

For any space not listed, grab its business_id from the site bundle and pass --business-id <id>.

Example output

Syncing cozespace produces ~46 docs across 8 nested directories:

01-了解扣子.md
02-快速开始/
  01-开始使用扣子.md
  02-打造你的 AI 团队.md
03-Agent/
  01-定制 Agent/
    01-概述.md ...
  02-使用 Agent/
    09-技能/
      01-技能概述.md ...
04-AI 编程/
06-探索/
...

How it works

The Coze docs site is a React SPA backed by ByteDance's arcosite doc platform. Two endpoints are all that's needed — both public and unauthenticated:

1. Nav tree — POST /api/open/playground/doc with x-arcosite-action: GetBusStructureById, x-arcosite-content (md5 of the JSON body) and an authorization HMAC-SHA1 signature. The client AK/SK are the literal "*" — a server-side proxy substitutes the real keys, so the call needs no auth. Returns the nested tree (title / path / is_dir / subs / _id).
2. Page body — GET /api/open/docs/{business_id}/{_id} returns the page's 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 the site's index.*.js bundle. If a redesign breaks them, re-inspect that bundle around setOpenAPIConfig, cryptoSignature, and /api/open/docs/.

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.

What's in the box

Path	What
SKILL.md	Skill definition: when to use, flags, output layout, API internals
scripts/sync.mjs	The sync script — tree fetch, signing, mirror, manifest reconcile

Requirements

• Node 18+ — uses global fetch and node:crypto. No npm install, no dependencies.

Contributing

Issues and PRs welcome. The most likely breakage is the upstream API: if a Coze redesign changes the signing or endpoints, the fix lives entirely in scripts/sync.mjs — see How it works for where to look in the site bundle. New --space mappings are a one-line addition to SPACE_MAP.

Disclaimer

Unofficial. It uses the same public, unauthenticated endpoints the docs site serves to anonymous visitors, purely to make a local/offline copy for reading. All documentation content remains the property of Coze / 字节跳动. Respect their terms; don't hammer the API (default concurrency is a polite 5).

License

MIT © LcpMarvel