/长文档处理 · Long Doc Incremental Write

别名

When the user types any of these, load this skill:

• /长文档处理 (primary user-facing alias, with leading slash)
• 长文档处理
• 长文档 / /长文档 (short alias)
• 分段写入 / 分段写 / 骨架写入 / 追加写入
• 文件较长，请分段写入：先写骨架，再用多次追加补齐，每次追加不超过 100 行。写完后读回文件末尾，确认结尾完整闭合再继续。

> name must stay long-doc-incremental-write (platform validator enforces hyphen-case ASCII).
> The directory and internal identifier are unchanged; only the trigger language changes.

Purpose

A single oversized write call is the most common cause of malformed deliverables: the tail gets cut, closing tags go missing, or content silently drifts out of scope. This skill replaces one giant write with a controlled skeleton → append → verify flow that keeps every edit small and always leaves the file in a previewable state.

⚠ Model gate (mandatory before anything else)

Step zero: detect the current session model. If it is not a custom model, abort and use the platform default write path. Do not proceed to any of the model-specific rules below.

Custom model list (the only models this skill applies to):

Detection method — check the active model name from the session context. If the name contains any of the strings above (case-insensitive), route to that model's section. If none match, do NOT execute this skill. Say: "当前会话不是自定义模型，跳过长文档处理流程。"

> When in doubt (model name unrecognized), treat it as non-custom and skip.

When to enable (applies after passing the model gate)

Enable for any of:

• Estimated output exceeds 300 lines or 20 KB.
• User explicitly asks for segmented writing (any of the trigger phrases above).
• Task produces more than three files at once.
• The document mixes several independent concerns (CSS / markup / script / data table / copy prose), each large on its own.

Do not enable for a single file comfortably under 300 lines — the overhead is not worth it.

Hard limits (defaults, overridden per-model below)

Shared baseline rules (apply on every model)

These are non-negotiable across all tiers. Model-specific overrides are documented in each model's section below.

Plan once, on disk. Before step one, write a plan.md next to the deliverables: step list with status markers, key conventions (date ranges, output dirs), and nothing else. A second round of re-planning narration in chat is a defect — catch it and execute instead.

One step per turn. Execute exactly one plan step per turn: run the script or write the block, land the output in a file, then tick the step in plan.md with a one-line result note. Do not pre-announce the next step.

Data lives in files, not in chat. Exploration dumps, extracted tables, intermediate JSON go to disk. Chat carries at most a 5-line summary per step.

Read discipline — never read the same file twice. Keep a read ledger in plan.md:

## 已读账本
- extract/specs_full.txt → 14章结构，四大板块，金额门槛≥100万，表格≤5条（2026-09-01~09-15）
- extract/F1_国家级基金.xlsx → 第2层表头17列，成立日期在索引13，出资日期是协议截止日（分布至2074），不可用于报告期筛选
...

For data files, the ledger entry captures schema verbatim — sheet name, full header list, index of each key column, and what a date field actually means.

• Every read states its question first; the answer lands in the ledger or an output file immediately. No open-ended "先读来看看".
• Batch reads: all files the current step needs go out in one round of parallel calls.
• Never full-read a file over ~500 lines: Grep first, then read the narrow offset range.
• After a context compaction notice, the first move is the ledger, never the source files.

Full absolute path in every tool call. Never pass a path from memory — re-type the complete absolute path each time. This applies double inside loops.

No meta-narration. "这个任务很庞大", "考虑到高效性" — zero information, real tokens. Per-turn narration budget: two sentences, stating what was done and where it landed. Thinking stays internal: no </think> tags, no mid-sentence self-dialogue, no mixed-language monologue in the reply body.

Action first, claims need receipts. A turn opens with a tool call — not with a recap. Anything claimed done must have a file or tool call behind it.

Inline scripts must redirect. Exploration output goes to a file — python -c "..." > extract/step_A.txt — never printed into the conversation.

Resume from the file, not from memory. After any interruption, restart, or compacted context, the first action is: read plan.md if it exists, otherwise write one (≤10 lines) from what is known — then continue from the first unticked step.

Model-specific sections

DeepSeek-V4-Flash (1M 档)

Flash 特有纪律（在共享基础之上叠加）

Flash = 单步引擎，不是编排者。 同一个 13 文件任务 Flash 已经三次停住（re-planning 循环 → 复述循环 → 承诺收尾）。窗口大不是瓶颈，回合级兑现能力才是。对 8+ 文件或多章节交付物，把整体编排交给 GLM-5.3 或 256K 档；Flash 只做单步生成。

畸形阶梯（参数卫生）： Flash 的 file_path 尾部追加 < 是模型层 tokenization 缺陷，无法通过提示词治愈。只能绕行：

1. 一次畸形 → 原样重发一次（泄漏是偶发的）。
2. 连续两次 → 换 Bash heredoc：cat > extract/step_A.py <<'EOF' … EOF，路径在命令字符串内部，坏掉的 file_path 字段根本不会被生成。宣布和执行必须同回合（"说 Bash 做 Write"是缺陷）。
3. Bash 也畸形两次 → 内容以代码块交付给用户保存，报告缺陷。
4. 禁止路径变形循环：缩名（q.py）、改名、换语言、挪目录，全是同一病根的不同变体。

代码卫生（适用所有模型，Flash 额外严格）：

• 写完脚本先 python -m py_compile script.py —— 1 秒内拦截结构损坏（如 for r into in）。
• 再跑 --limit 3 小样本 dry-run —— 拦截乱码标识符（如 r[l3]、os.maket_dirs），避免大 Excel 跑几分钟才报 NameError。
• 禁止硬编码列索引：用 i = header.index('投资金额（万元）') 动态定位。
• 中文路径不跟 shell 转义硬拼，cd 进目录后相对路径，或用 Python os.path.join。
• 连续两次因乱码失败 → 停手，换 header-name 定位或报告，不要"冷静下来继续打字"。

Promises are not endpoints： 回合必须以完成时+路径收尾（"已落盘 extract/step_A.txt（8 行）"），以"现在写X…"收尾即为未完成回合，该承诺自动成为 plan.md 的下一步。

DeepSeek-V4-Pro (1M-cautious 档)

Pro 特有纪律

静默失败防御： 超过 ~930K 不会报错，输出直接降级。策略：

• 每批追加后都跑 verify_doc.py，不能只收尾验一次。
• 预算已预先打折，禁止上调。

代码卫生（和 Flash 同等严格，见上方"代码卫生"节）： Pro 的标识符乱码和 Flash 的参数畸形是同一家族（tokenization 缺陷），防法相同。

GLM-5.3-FP8 (400K 档)

GLM 特有纪律（四重防线）

核心定性：GLM 适合做编排者，但必须结构化约束。 Flash 坏在执行层，Pro 坏在参数层，GLM 坏在循环层——它会反复「恢复→重读→再恢复」。四重防线按优先级排列：

防线一：代码卫生（和 Pro/Flash 同等严格）

乱码标识符是 DeepSeek 系 tokenization 缺陷，不是 Pro 独占。GLM 写 Python 脚本时必须遵守：

• 编译闸门：写完脚本先 python -m py_compile script.py——拦截 os.maket_dirs、for r into in 等结构损坏（< 1 秒）。
• 小样本 dry-run：--limit 3 先跑——拦截 r[l3]、r[打0] 等名字类乱码（NameError 运行时才爆，dry-run 秒级暴露）。
• 禁止硬编码列索引：i = header.index('投资金额（万元）') 动态定位，绝不用 r[7]/r[12]——这是本次 GLM 会话里最贵的一类错误（r[ennes]、r[iat3]）。
• 连续两次因乱码失败 → 停手报告，不要"冷静下来继续打字"——那是循环本身。

防线二：阶段架构纪律（强制执行，不可协商）

GLM 擅长深度分析，不适合无结构的长任务。强制拆成 ≤5 个阶段，每个阶段有明确边界：

plan.md 结构模板（GLM 专用）：
## 执行计划（GLM 版）
任务：[一句话]
阶段：
  [ ] Phase 1: [名称] → 输入：[文件清单] → 输出：[落盘文件] → 状态快照：plan.md tick [ ]
  [ ] Phase 2: ...
  [ ] Phase 3: ...
  [ ] Phase 4: ...
  [ ] Phase 5: ...
账本：（每次读完文件立即追加一行）

每阶段结束必须落盘状态快照：

# 在 plan.md 中追加快照
echo "[2026-09-26 14:03] Phase 1 完成。extract/f1_full.txt 已落盘（823 行），
      关键结论：成立日期列在索引 13，出资日期是协议截止日（分布至 2074，不可用于报告期筛选）" >> plan.md

禁止「上下文已恢复」循环：每次任务开始的第一动作是读 plan.md，不是「恢复上下文」。如果 plan.md 不存在或已过期（最后修改时间 >30 分钟），重新建立而不是重读原始文件。

防线三：压缩防御（零信任策略）

一旦出现「上下文已压缩」提示，立即做三件事（按顺序）：

1. 停——暂停所有工具调用，不要继续推进任务。
2. 读账本——读 plan.md 的「已读账本」节，确认哪些文件已提取、哪些结论已落盘。
3. 从账本继续——用已落盘的文件继续，严禁重读源文件。

如果账本缺失（plan.md 被压缩丢失），重新建立 plan.md（从磁盘现有文件推断），而不是重读原始数据。

防线四：断言安全（禁止无意义重建）

QA 自检断言必须基于实际产物，不能假设：

• 断言前必须先 Read 实际产物内容（不能靠记忆算卡片数）。
• 断言失败 → 只修失败项，不重建整个文件。
• 如果一处失败导致连锁失败（某断言错导致多个后续断言全错），逐条修复、逐条重验，不要一次性重建。

工作目录纪律：plan.md 第一行必须写绝对路径（WORKDIR=D:/WorkBuddy/<date>/<task>/），后续所有文件操作必须基于该路径。禁止「工作目录看起来是…/」这种试探语句——如果不确定，先读 plan.md 第一行确认。

Qwen3-VL-30B-A3B-Instruct (256K 档，视觉主力)

视觉任务编排（通过视觉识别技能）

本档的视觉调用通过视觉识别技能路由（Qwen3-VL-30B-A3B-Instruct 远程接口）。本技能在此补充编排纪律：

• 视觉调用像文件读取一样进账本：image → method → result 落 plan.md。
• 单次视觉任务上限 6 次调用，超 6 次报区间不继续。
• 挂起重试只换提示词（简化 prompt），发散只换方法（分区域法 vs 边界框法 vs 裁剪法），同法重跑 = 重读文件，禁止。
• 每次调用后结果落盘，压缩上下文不丢已测数据。

> 视觉方法论本体（分辨率预检、结构先行、短提示词默认、速度启发式判伪、收敛即停、numpy 连通域交叉验证）写在视觉识别技能里。遇到图片理解任务，先加载视觉识别技能再按此技能编排。

chat-pro (通用档)

chat-pro 通用纪律

无已知 tokenization 类缺陷（与 DeepSeek 系/GLM 的乱码标识符、Flash 的参数畸形不同族），按共享基础规则执行即可：

• 骨架 → 追加 → 校验三阶段流程照常使用，append_block.py 与 verify_doc.py 均可用。
• 写脚本仍过编译闸门（python -m py_compile）+ 小样本 dry-run，防手误。
• 每批追加后建议跑一次 verify_doc.py，长任务（>600 行）时不得只收尾验一次。
• 中文路径一律用 os.path.join 或先 cd 进目录，不与 shell 转义硬拼。

其他模型（未在白名单中）

不执行本技能。 回复：

> 当前会话模型（{model_name}）不在自定义模型白名单内，跳过长文档处理流程，使用默认写入路径。

默认路径建议：单次 Write 控制在 500 行以内；超过则提示用户拆成多个文件或使用分段写入（不应用本技能的复杂规则）。

Phase 1 — Skeleton

Create the file with the Write tool. Budget follows the model-specific table above (default 200 lines for 256K). The skeleton must be a structurally valid, openable document, not a placeholder stub.

Include, in this order:

1. Document head: doctype, meta, title, external links.
2. An empty <style> block reserved for Phase 2 CSS.
3. Body markup with one marker line per planned section:
   <!-- @@SECTION:hero @@-->, <!-- @@SECTION:metrics @@-->, etc.
4. An empty <script> block reserved for Phase 2 logic.
5. Closing tags last: </body>, </html>.

Before writing, derive the marker list from the actual content plan — one marker per logical block. List them in the response so the remaining phases are mechanical.

Phase 2 — Incremental append

Work through the markers one at a time. Max lines per Edit follows the model-specific table (default 100).

Recommended edit shape — the marker is replaced by the content it reserves:

• old_string: the single marker line, e.g. <!-- @@SECTION:hero @@-->
• new_string: the new content only, no marker carried over

To land content above a marker, pass --before to append_block.py.

Order of preference:

1. If a large block is already staged on disk, use scripts/append_block.py. It locates the marker, inserts atomically, and supports --once for idempotency.
2. Otherwise use a plain Edit on the marker line.

python scripts/append_block.py --file out.html \
    --anchor SECTION:hero --text "<section class='hero'>...</section>" --once
python scripts/verify_doc.py out.html

CSS and <script> blocks fill in the same way, targeting their own markers @@STYLE@@ / @@SCRIPT@@.

Phase 3 — Verification

Run the checker on every file before declaring the task done:

python scripts/verify_doc.py out.html report.md --max-lines 900

It reports line count, byte size, the last six lines, remaining tag stack, any unclosed tag, unfilled markers, and a missing </html> / </body> / </script>.

Then read the tail of the file back to confirm visually that the closing tags are present and in the right order. The checker reports it; the read confirms it. If anything is off, append the missing piece rather than rewriting the file.

A file passes only when:

• The tail ends with the required closing tags.
• No unclosed or stray tags remain.
• Every marker has been consumed.
• Line count is within the agreed model-specific budget.

Batch of multiple files

For more than three files:

1. Publish a manifest first in the response — a short table of file name, purpose, estimated lines, and dependencies. The user can adjust the plan before any bytes are written.
2. Generate repetitive structure with code, not prose. Nav bars, card grids, table rows, and repeated sections are produced by a short script, not typed out.
3. One file at a time through the full three-phase flow. Do not interleave phases across files.
4. Verify all files together at the end with a single verify_doc.py call listing every path.

Standard request

When the user issues any trigger phrase (including /长文档处理), follow the model-gate → plan → three-phase flow above. Decompose the request into the three phases and report phase progress back to the user.

Reference

references/workflow-detail.md covers marker naming, a worked skeleton example, budget sizing, per-model failure signatures, and a pre-delivery checklist.