--- name: long-doc-authoring description: "Use this skill for long document generation, especially documents above 8000 Chinese characters or any task that may exceed model output limits. It guides the agent to generate a section tree, write leaf sections as Markdown, keep metadata and summaries, verify coverage and length, then render the final Word/PDF from one merged Markdown source." --- # Long Document Authoring Use this skill when the user asks to create a long report, plan, proposal, research material, government document, book-like manuscript, or any document that may exceed one normal model response. This skill is for controlled generation, checkpointing, recovery, and final assembly. The core rule is: ```text Markdown is the only authoritative source during generation. Word/PDF are final delivery artifacts, not the working source. ``` Do not generate one huge answer in the chat. Build the document through artifacts. ## Built-In Tool Workflow Use the dedicated long document tools whenever they are available: 1. `long_doc_create_project`: create `document_plan` and `task_ledger` artifacts from a generated outline. 2. `long_doc_update_node`: save or overwrite each leaf Markdown section, save metadata, and update the ledger. 3. `long_doc_merge`: merge saved leaf Markdown files in plan order into chapter or full Markdown. Use `write_file` directly only for supporting files that are outside this workflow, such as rendering scripts, source notes, or user-requested standalone artifacts. ## When To Use Use this skill when any of these are true: - The target length is above 8000 Chinese characters or about 5000 English words. - The user asks for a long report, long plan, full manuscript, full proposal, complete materials, research report, implementation plan, or multi-chapter document. - The document has chapters, sections, appendices, tables, references, or source materials. - A single model response may omit sections, fail the requested length, or lose consistency. If the document is public-sector or government-style writing, also use `sys_gov-writing` for tone, format, and official wording constraints. If final Word output is required, also use `sys_docx` before the final rendering step. ## Non-Negotiable Rules - Keep Markdown as the primary source. Do not use per-chapter `.docx` files as merge inputs. - Generate leaf nodes first. A leaf node is the smallest section that should be written in one model pass. - Save every leaf section as its own Markdown artifact. - Save metadata and summary for every leaf section. - Merge chapters and the full document by deterministic ordering from the document plan, not by asking the model to rewrite the whole document. - Final Word/PDF must be rendered from the merged Markdown source in one pass. - Chapter Word files are allowed only as previews for the user; never use them as the final merge source. - Do not invent facts, policy basis, names, dates, statistics, legal basis, responsible units, or source citations. Mark missing values as `待补充` or `待明确`. - If the user asks for a target length, track actual length and repair missing/short sections before final rendering. ## Artifact Layout Create artifacts with clear names and types. Prefer the dedicated long document tools for plan, ledger, leaf, metadata, and merged Markdown artifacts. Recommended files: ```text long-doc/ 00-document-plan.json 00-task-ledger.json sections/ 01-00.md 01-00.meta.json 01-01.md 01-01.meta.json 02-00.md 02-00.meta.json chapters/ 01.md 02.md full.md final.docx final.pdf ``` Use these artifact types: - `TASK_LEDGER`: `00-task-ledger.json`, progress, status, and validation results. - `GENERATED_DOCUMENT`: leaf Markdown, chapter Markdown, and full Markdown. - `SUMMARY_SNAPSHOT`: leaf summaries, chapter summaries, style notes, and continuity notes. - `CODE_SCRIPT`: rendering or validation scripts. - `MERGED_RESULT`: final merged Markdown or final delivery artifact when supported by the tool output. ## Document Plan Before writing body text, generate a section tree and call `long_doc_create_project`. The plan must include: ```json { "title": "待定标题", "audience": "读者或报送对象", "document_type": "research_report | implementation_plan | work_summary | proposal | manuscript | other", "target_length": { "unit": "chinese_chars", "total": 30000, "tolerance_percent": 10 }, "style": { "tone": "formal", "language": "zh-CN", "format_notes": [] }, "source_policy": { "may_infer": false, "missing_value_marker": "待明确", "citation_required": false }, "outline": [ { "id": "01", "title": "第一章 标题", "target_length": 5000, "children": [ { "id": "01-01", "title": "第一节 标题", "target_length": 1200, "key_points": [], "source_refs": [] } ] } ], "acceptance_criteria": [ "all leaf nodes generated", "actual length within tolerance", "no missing required sections", "heading hierarchy is consistent", "facts and source-sensitive claims are not invented" ] } ``` Keep leaf section targets around 800-2000 Chinese characters. Split larger sections into smaller leaves. ## Task Ledger `long_doc_create_project` creates the task ledger. `long_doc_update_node` keeps it updated during the work: ```json { "project_status": "planning | drafting | reviewing | merged | final", "current_node_id": null, "nodes": [ { "id": "01-01", "title": "第一节 标题", "status": "pending | drafted | reviewed | needs_rewrite | merged", "target_length": 1200, "actual_length": 0, "markdown_artifact_id": null, "meta_artifact_id": null, "issues": [] } ], "global_terms": [], "open_questions": [], "validation": { "missing_nodes": [], "short_nodes": [], "duplicated_points": [], "continuity_issues": [] } } ``` Update the ledger after each leaf section is saved. ## Leaf Generation Workflow For each leaf node: 1. Read the plan and task ledger. 2. Gather only the necessary context: - global requirements - current node path - current node target length - parent summary - previous sibling summary - required key points - source snippets or user-provided facts 3. Generate only the current leaf section body in Markdown. 4. Do not include unrelated chapters or repeat the full outline. 5. Call `long_doc_update_node` with the section Markdown, summary, status, and optional metadata. 6. Continue with the next leaf only after the tool returns the saved Markdown and meta resource IDs. The leaf prompt should follow this structure: ```text Write only this leaf section. Document title: Audience: Document type: Current node path: Target length: Required key points: Source constraints: Parent summary: Previous sibling summary: Terms that must remain consistent: Output format: - Markdown only - Start with the correct heading for this leaf - Do not write other sections - Mark missing facts as 待明确 ``` ## Leaf Metadata Each leaf metadata file should include: ```json { "node_id": "01-01", "title": "第一节 标题", "status": "drafted", "target_length": 1200, "actual_length": 1180, "summary": "本节摘要。", "key_claims": [], "source_refs_used": [], "terms": [], "continuity": { "depends_on_previous": false, "handoff_to_next": "下一节需要承接的内容" }, "quality": { "missing_facts": [], "risk_notes": [], "needs_user_confirmation": [] } } ``` Use the summary, not the full previous section, as context for later sections unless exact text is required. ## Chapter And Full Merge After all leaves in a chapter are drafted: 1. Call `long_doc_merge` with `scope=CHAPTER` and the chapter node id. 2. Create or update a chapter summary snapshot if useful. 3. Check that heading levels and transitions are coherent. After all chapters are complete: 1. Call `long_doc_merge` with `scope=FULL`. 2. Run full-document validation. 3. Repair missing, short, duplicated, or inconsistent sections at the leaf level. 4. Rebuild `full.md` by calling `long_doc_merge` again. Do not ask the model to "merge and rewrite everything" unless the user explicitly wants a shorter rewritten version. Merging should preserve generated section text. ## Validation Checklist Before final delivery, verify: - Every leaf node in `00-document-plan.json` has a saved Markdown artifact. - The final document has no placeholder section except allowed `待补充` or `待明确` markers. - Total length is within the requested tolerance or the user has accepted the deviation. - Each required key point appears in the intended node. - Heading levels are consistent. - Terms, organization names, dates, and numbers are consistent. - No section repeats a previous section without adding new value. - Cross-references such as `上文`, `下文`, `本章`, and `附件` are still correct after merge. - Tables are valid Markdown tables or separately represented as JSON for final rendering. - If citations are required, every citation maps to a provided source. ## Final Word Or PDF Rendering If the user wants Word/PDF: 1. Keep `full.md` as the authoritative source. 2. Use `sys_docx` when Word styling, templates, or conversion are required. 3. Use `write_file(artifactType=CODE_SCRIPT)` to save a rendering script if the script is more than a short inline snippet. 4. Use `code_exec(code_ref=..., activated_skill="sys_docx")` to render `full.md` into `/outputs/final.docx`. 5. Optionally convert `final.docx` to PDF. Prefer this pipeline: ```text leaf Markdown -> chapter Markdown -> full.md -> final.docx -> final.pdf ``` Avoid this pipeline: ```text leaf Word -> chapter Word -> merged Word ``` The avoided pipeline is fragile because Word subdocument merging can corrupt or conflict on styles, numbering, relationships, headers/footers, sections, fields, footnotes, captions, and table layout. ## Recovery And Rewrite Rules If a section is too short: - Rewrite or extend only that leaf section. - Update its metadata and summary. - Rebuild the affected chapter and `full.md`. If two sections overlap: - Keep the stronger section. - Rewrite the weaker leaf with a narrower scope. - Update the ledger with the duplication fix. If the document drifts from the user's requested tone: - Add a style note to the ledger. - Apply it to future leaves. - Revise completed leaves only when the drift is material. If the model loses context: - Re-read `00-document-plan.json`, `00-task-ledger.json`, the current node metadata, and the nearest summaries. - Do not reload the entire full document unless exact text is needed. ## User Communication For long document work, keep user updates short and concrete: - State which chapter or section is being drafted. - State when a checkpoint artifact is saved. - State validation results and remaining gaps. Ask the user only for blocking missing information. If a missing detail can be marked as `待明确`, continue and record it in the ledger.