feishu-docx-outline-digests

name	feishu-docx-outline-digests
description	Create polished Feishu/Lark docx reading versions for scheduled digests with real outline headings, wiki archive links, and verification. Use when a digest/newsletter/wiki cron must produce a Feishu doc, not just a message or markdown dump.
version	1.0.0

Feishu Docx Outline Digests

Use this when a scheduled digest must create a Chinese reading document in Feishu/Lark and the user requires a real document outline / left-side directory.

When to use

• User asks for a Feishu docx reading version of a daily digest, lens, newsletter, or wiki query.
• Requirements mention real Feishu headings, outline/navigation, H1/H2/H3, block types, or verification by listing document children.
• The digest must also update local wiki archives and log files with the final doc URL.

Workflow

1. Prepare the digest content first

   • Write the reading version as a platform-native document outline, not a markdown paste.
   • Keep it polished and concise; full source text should stay in the wiki/source index/raw archive.
   • For bilingual archive workflows, create separate EN/ZH markdown archives; the Feishu reading doc can be Chinese-only if requested.

2. Create real Feishu heading blocks

   • Use docx heading block types, not paragraph text that merely looks like a heading.
   • Required mapping:
     • H1 / outline level 1: block_type=3 with heading1
     • H2 / outline level 2: block_type=4 with heading2
     • H3 / outline level 3: block_type=5 with heading3
   • Body content should use text/list/quote blocks:
     • paragraph: block_type=2 with text
     • bullet: block_type=12 with bullet
     • ordered list: block_type=13 with ordered
     • quote/callout: block_type=15 with quote

3. Create documents and blocks via Feishu docx OpenAPI

   • Use the configured Feishu app credentials to obtain a tenant token; never print credential values.
   • Get tenant token: POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal.
   • Create docx: POST https://open.feishu.cn/open-apis/docx/v1/documents with {"title": "..."}; read data.document.document_id (or fallback data.document_id / token).
   • Append blocks under the document root block, whose block id is the document id: POST https://open.feishu.cn/open-apis/docx/v1/documents/:document_id/blocks/:document_id/children?document_revision_id=-1.
   • Use payload {"children": [blocks...], "index": <inserted_count>}; chunk large docs around 35–45 blocks/request and pause briefly between chunks.
   • Reliable raw block JSON shape for text-bearing blocks:
     • H1: {"block_type":3,"heading1":{"elements":[{"text_run":{"content":"...","text_element_style":{}}}],"style":{}}}
     • H2: same with block_type:4, key heading2
     • H3: same with block_type:5, key heading3
     • paragraph: block_type:2, key text; bullet: block_type:12, key bullet; ordered: block_type:13, key ordered; quote: block_type:15, key quote.
   • When generating archive markdown with Python f-strings, precompute strings such as "\n\n".join(source_notes) before interpolation; f-string expressions cannot contain backslashes and will raise SyntaxError.
   • Prefer running Feishu API scripts via terminal() when the script needs live environment variables such as FEISHU_APP_ID and FEISHU_APP_SECRET. execute_code() may run in a tool sandbox that does not inherit the same environment, even when terminal("env") shows the credentials are available. If execute_code() reports missing Feishu env vars, immediately write a temporary Python script and run it with terminal() rather than treating Feishu creation as unavailable.
   • If an initial archive/log entry was written with a Feishu failure placeholder, create the verified doc once credentials work, then patch the EN/ZH archive frontmatter and visible doc lines from FEISHU_DOC_CREATION_FAILED... to the final URL. Search the archives for the failure placeholder before final delivery.

   Typed SDK alternative:

   • Build a text object from Text, TextElement, and TextRun.
   • Construct blocks with the matching field for the block type: heading1, heading2, heading3, text, bullet, ordered, or quote.
   • Insert children under the document root block; for docx documents the root block id is the document id.

4. Mandatory verification

   • After writing, list document children with descendants enabled.
   • Read raw document content when available.
   • Treat verification as failed if:
     • total block count is under 25 for a normal digest,
     • block types do not include 3, 4, and 5,
     • required section names are missing,
     • headings were inserted as normal paragraphs.
   • When verifying required section names, match the exact visible phrases requested by the cron/user, not just semantically equivalent headings. For Follow Builders-style docs, include the literal phrase 归档与追溯 somewhere in the outline/body even if the outline template says 5.2 归档路径; using only 5. 跟进动作与归档 + 5.2 归档路径 can pass structure checks but fail phrase verification. A safe H2 is 5.2 归档与追溯.
   • Also verify qualitative requirements, not just structure. For polished digest docs, scan generated card/judgment text for repeated placeholders such as 保留为雷达信号 or generic 高影响事实需回到原 URL 验证; if several cards share the same judgment, revise the source-card synthesis and recreate the doc before finalizing.
   • If verification fails, recreate or rewrite the document before reporting success.

5. Archive and navigation updates

   • Put feishu_doc: <url> in the markdown archive frontmatter.
   • Add a visible line near the top such as 飞书文档中文阅读版：<url>.
   • Update the wiki index if the archive root or daily archive entry is missing.
   • Append a log entry with: Feishu doc URL, archive paths, source index, raw archive path, item count, feed timestamps/errors if relevant, and verification JSON.
   • Order verification correctly: if local verification checks index/navigation links, run it after updating index.md, not before. Otherwise you may log a false global index missing daily links failure even though update_index_and_log() subsequently inserted the links. If this happens, re-run local verification after navigation updates and patch the log entry to the final passed result.
   • If a rough/incorrect Feishu doc was created first, create a corrected doc and then patch all archive mentions to the final verified URL: frontmatter, visible doc link, source notes, verification JSON, and final response. Do not leave the superseded draft URL inside archive verification JSON (even as supersedes_draft) because later grep/readers may treat it as the canonical doc. It is okay to mention a superseded draft in log.md, but append a final clean log entry whose Feishu URL and verification JSON point only to the verified doc.
   • When patching a verification JSON line in markdown, avoid brittle non-greedy regexes like .*? that can stop at ? inside a Feishu API URL and leave truncated/malformed JSON. Prefer replacing the whole line by prefix match (for example, line starts with - Feishu verification：) or parse/re-render the whole archive file.
   • After patching URLs, run a targeted search on the EN/ZH archive files for both the final doc token and the superseded doc token. Require the archives to contain the final token and no superseded token before final delivery.
   • If writing raw source snapshots with sha256: frontmatter, compute and verify the hash over the exact body captured by a post-write regex such as ^---\n(.*?)\n---\n(.*)$. Beware the blank line after the closing frontmatter delimiter: writing ---\n\n means the regex body begins with \n, so a hash computed over the pre-rendered body string can be stale. Re-read each raw file after writing, recompute the body hash, patch the frontmatter if needed, and only then copy the verified hash values into archives/logs.

6. Final delivery

   • Keep the push/final response short.
   • Put the Feishu doc link first.
   • Include only the top 3 themes or takeaways plus archive/source-index paths.
   • Do not paste the full digest body into the push.

Verification checklist

Before finalizing, confirm:

• Feishu doc URL is the latest verified document, not an earlier rough draft.
• If any draft doc was superseded, EN/ZH archive files contain the final doc token and do not contain the superseded doc token.
• The document has block types 3, 4, and 5.
• Required outline sections appear in raw content.
• The local EN/ZH archives exist and contain the same Feishu doc URL.
• The source index/raw archive paths are present near the top of archives.
• Wiki index/log were updated.
• Card-level judgments are specific and varied; repeated generic fallback judgments have been replaced before delivery.

Pitfalls

• A markdown heading pasted into a paragraph does not create a Feishu outline. Use real heading blocks.
• Do not rely only on a successful document creation response; verify children and raw content after block insertion.
• If you create a rough/incorrect doc first, do not leave its URL in the archive or final response after creating a corrected version.
• Do not expose app secrets, tenant tokens, or environment file contents in logs or user-facing summaries.