huawei-cloud-clouddocs-aipage

huawei-cloud-clouddocs-aipage — Create an online page document based on content (most basic version)

The minimal page skill trimmed from the slide skill:User provides content → model generates markdown → page +create create in one go → deliver link → file +export export local docx. Retains only the brand-new creation pipeline, export wrap-up, and idempotent breakpoints; does not include single-block editing, templates, batch, or other capabilities.

Core design: generate markdown → create in one go → export docx ★

A single main pipeline throughout, with no staged rendering:

1. Generate: the model constructs markdown according to the user's original requirements, writes it to <项目工作目录>/drafts/page.md(for content specifications see references/page-content.md）。
2. Create：create_page.py reads markdown, via clouddocs-cli page +create --title <t> --content <c> [--format 1] creates an online page document in one go, writes the created_doc.json anchor, and returns doc_id + doc_url。
3. Deliver: hand doc_url（{base}/wapp/doc/<docId>) to the user.
4. Export：clouddocs-cli file +export --document_id <doc_id> --export_type word exports the online document as docx and saves it to the local delivery directory (after creation, wait 10 seconds first; on failure retry once after 10 seconds; if it still fails, give up on export and deliver only the link).

organization_id / wiki_id is automatically resolved by the CLI (personal space + default document library); the script requires no prior space +fetch / docbase +fetch; optional --parent-document-id to create under a specified parent document (such as AI creation documents).Idempotencyis the key guardrail:created_doc.json if it already exists, rerunning only returns it and never creates the document again.

Draft directory convention (drafts are always created in the project working directory) ★

• The drafts directory (page.md / created_doc.json / page.kpge and other intermediate artifacts) is always created under thecurrent user project working directory(session cwd / caller working directory):<项目工作目录>/drafts/。
• Forbiddento write to the skill installation directory (~/.cac/skills/<技能名>/) or the skill source directory (<skills 源码仓库>/.../skills/<技能名>/) — the skill directory is read-only specifications and scripts and does not belong to any specific run.
• Step 1: the model uses Write to create <项目工作目录>/drafts/page.md(Write automatically creates the directory); the script defaults to --drafts-dir drafts, and when run in the project working directory it resolves to <项目工作目录>/drafts/。
• created_doc.json(idempotency anchor) and page.kpge fall into the project working directory together with drafts, are retained with the session deliverables, and can be resumed across sessions from breakpoints.

Iron rules for user interaction

To the user,output only："正在生成文档内容..."(optional) / "文档已创建：<链接>" / "本地Word：<本地路径>"(wrap-up) / a concise error explanation (when export fails: "Document created: <link>, local Word export failed"). Everything else is silent — skill names / script names / file paths / doc_id / raw API responses and all other internal state must not appear.At wrap-up, report only the local file path, without appending an article content overview/chapter summary。

Pre-checks

• CLI installed：command -v clouddocs-cli(on Windows cmd/PowerShell use where clouddocs-cli / Get-Command clouddocs-cli) can locate the executable;if not found, first follow <技能基目录>/bin/cli-installation-guide.md install sub-skill to complete installation(Windows only, execute bin/windows/install-windows.ps1, see that sub-skill for details), and continue only after installation is complete.
• Authentication：clouddocs-cli auth status shown ready; otherwise use the two-step device authorization (Do not directly run the blocking clouddocs-cli auth login—it prints the URL and then hangs polling for authorization, the command does not exit, and the URL is not output when captured by a pipe, so it will hang):
  1. clouddocs-cli auth login --no-wait --json → returns JSON immediately, take verification_url and device_code；
  2. automatically open the authorization page（Windows）：powershell.exe -NoProfile -Command "Start-Process '<verification_url>'"(in practice it reliably pops up the browser; if the environment still cannot open it, read the URL to the user to open manually);
  3. background continuation automatically detects authorization: immediately after initiating authorization, run in the background clouddocs-cli auth login --device-code <device_code>(this command has built-in polling, 240s max by default)—the moment the user authorizes successfully, the background task automatically completes login and saves credentials, no need to wait for the user to notify; while the background task is not finished, give the URL to the user to click authorize.
• Service address：clouddocs-cli config init --host <url>, or ~/.clouddocs/config.json already configured base_url。
• For troubleshooting: run in the project working directory python3 <技能基目录>/scripts/create_page.py --probe-auth(only checks base/auth, no network requests).

Step 1. Generate markdown

Based on the user's original requirements (topic, key points, purpose, audience, etc.), the model constructs markdown according to the references/page-content.md specification, and writes it in one go with Write to <项目工作目录>/drafts/page.md(for the drafts directory convention see "Drafts directory convention" above). The modelmust not directly call the CLI。

• The document title is taken from the content topic;# <标题> the first line is consistent with --title .
• Cover all the user's key points; no consecutive duplicate blank lines; no fabricated data.
• When the content is long, keep the structure complete; if it exceeds the CLI parameter limit (about 30KB), prompt the user to split it or condense it.

Step 2. Create an online page document (one-shot script)

cd <项目工作目录>
python3 <技能基目录>/scripts/create_page.py --title '<按主题命名的文档标题>'

cwd = Project working directory, the script defaults to --drafts-dir drafts(i.e. <项目工作目录>/drafts/). The script reads <项目工作目录>/drafts/page.md, creates the document via page +create and writes created_doc.json. Act according to the exit code:

Exit code	Meaning / next action
0	Created successfully, stdout contains doc_id / doc_url → proceed to step 3 for delivery.
1	Parameter or prerequisite missing (document not created) → fix according to stderr (mostly missing --title / missing page.md) then rerun this script.
2	Authentication / network failure (document not created) → stop and report to the user; never retry repeatedly; you may first --probe-auth troubleshoot.

Optional parameters:

python3 <技能基目录>/scripts/create_page.py --title '<标题>' --content '<markdown 文本>'        # 不走文件
python3 <技能基目录>/scripts/create_page.py --title '<标题>' --parent-document-id '<父文档ID>'   # 建到指定父文档
python3 <技能基目录>/scripts/create_page.py --title '<标题>' --dry-run                          # 预览请求，不发网络
python3 <技能基目录>/scripts/create_page.py --title '<标题>' --drafts-dir '<自定义目录>'         # 指定草稿目录（默认 ./drafts）

🚨 After exit code 0,do not verify, and do not go back to the generation stage. The script stdout is already the complete source of truth.

Step 3. Delivery

Just read doc_url to the user.After successful creation, do not proactively open the document link(do not call cloud_doc_operate open, do not launch a browser); whether to open it is up to the user.

Step 4. Export docx locally (wrap-up)

After the online page document is created successfully,wait 10 seconds before exporting(to give the backend time to finish persisting/indexing the content, ensuring the exported docx contains the full content), use clouddocs-cli file +export Export the document as docx and save it locally as an offline deliverable:

sleep 10   # 创建后等 10 秒，等后端落库完成
clouddocs-cli file +export \
  --document_id '<doc_id>' \
  --export_type word \
  --file_name '<按主题命名>' \
  --output '<本地保存目录或全路径>'

• doc_id Take created_doc.json from doc_id(or truncate from the end of doc_url).
• --output The target directory must already exist(otherwise the CLI treats --output as a full-path file write, and the artifact becomes a file with no extension); when the directory exists, the exported filename is <document_id>.docx。
• The returned JSON contains file_path / file_name / file_size; according to the returned file_path , rename the exported fileto "<topic>.docx" and place it in the delivery directory(tested: --file_name has no effect on the exported filename).
• The exported content is based onthe full content in the backend document objectand is consistent with online rendering.

Failure retry policy (at most 2 attempts; give up on failure)：

1. First export failure → sleep 10 retry the exact same file +export。
2. Retry still fails → give up exporting, no further retries. Stop and explain to the user: "Document created: <link>, local Word export failed", and deliver the link (the document itself succeeded; the docx can be completed later by manually rerunning step 4).

Resume from checkpoint

• Idempotency anchor：<项目工作目录>/drafts/created_doc.json(written to disk once document creation succeeds). After an interruption, directly rerun in the project working directory python3 <技能基目录>/scripts/create_page.py --title ...(default drafts directory ./drafts); if the anchor already exists → only return doc_id/doc_url, never recreate the document.
• <项目工作目录>/drafts/page.md: after the markdown content is written to disk, it is not deleted with the workflow and can be edited and rerun at any time (you must first delete created_doc.json for it to be recreated).
• docx not exported → rerun step 4's file +export(idempotent; export can be repeated to overwrite the local file; export failure retries at most once, then stop and deliver the link).

File contract (drafts intermediate artifacts, always under the project working directory)

File	Description
<项目工作目录>/drafts/page.md	Model-generated markdown (written in step 1, read by create_page.py)
<项目工作目录>/drafts/created_doc.json	Document creation anchor (doc_id / doc_url, basis for idempotency)
<项目工作目录>/drafts/page.kpge	doc_url as plain text (runtime state)
<项目工作目录>/outputs/<主题>.docx	Offline deliverable exported in step 4 (file +export artifact, renamed to the topic name, delivery directory = <项目工作目录>/outputs/）

Constraints

• Document creationonly goes through clouddocs-cli（create_page.py via the shared adapter layer scripts/_hws_cli.py to call the CLI; authentication is managed by the CLI itself),forbiddenfor scripts to connect directly to the backend HTTP.
• Strictly forbidden to bypass create_page.py and directly call clouddocs-cli page +create; strictly forbidden to hand-write scripts that call the backend API to create documents.
• created_doc.json can only be written to disk by create_page.py ; the model and coordinator must not overwrite it by hand.
• drafts intermediate artifacts (page.md / created_doc.json / page.kpge) must all be placed underthe current project working directory; writing to the skill installation directory (~/.cac/skills/<技能名>/) or the skill source directory is forbidden.
• Content is preferably sent directly as markdown; only when the backend explicitly rejects markdown, switch to block JSON as a fallback per references/page-content.md Section 2.
• Exporting docx goes through clouddocs-cli file +export（--export_type word），forbiddento hand-write scripts that assemble docx or bypass the CLI.
• JSON output must never contain markdown code block markers; text in Chinese, JSON keys in English.

Runtime dependencies

• clouddocs-cli executable（requires: bins: ["clouddocs-cli"]): all backend operations are performed through it. Prerequisites: installed (if not installed, install it first according to the <技能基目录>/bin/cli-installation-guide.md installation sub-skill; only Windows is supported), logged in (clouddocs-cli auth status shows ready; otherwise auth login gives the verification URL to the user), service address configured (clouddocs-cli config init --host <url> or ~/.clouddocs/config.json in base_url）。
• Python 3.8+ standard library: Both scripts use only the standard library, with no third-party dependencies.