# Ref Material Writing

> 基于写作需求、提纲和多份参考资料驱动的文档写作。当用户提供写作需求、提纲和多份参考资料并要求撰写文档/报告/方案/综述/建议书时触发；当用户强调"基于参考资料""不要编造""严格按提纲写"时优先使用；默认采用正式严谨的公文风格。适用于政府/企业正式文书、产业报告、商务建议书等有据可查的文档撰写场景。不适用于无参考资料的内容创作、创意写作或仅润色改写。

- Skill: `zhangweildlh/ref-material-writing` (Agent Skill, multi-file: 55 files)
- Install (CLI): `npx skillmds@latest add zhangweildlh/ref-material-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhangweildlh/ref-material-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Proprietary
- Author: zhangweildlh (https://skillmd.com/u/zhangweildlh)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhangweildlh/ref-material-writing

---


# 基于多份参考资料的文档撰写

> **本 Skill 采用渐进式披露设计**。主文件仅含核心路由与决策规则；每一步骤的详细规范位于 `_router/step-NN.md`，按执行顺序加载。
> 文件读写（Markdown / TXT / 状态文件等）由 AI 使用其**原生文件读写能力**自主完成，工具名通过 `_router/bootstrap.md` 的「工具能力映射表」解析，**禁止在步骤中硬编码平台特定工具名**。
> 详细环境约束见 `references/02-environment-setup.md`；Office 文件读写指南见 `references/04-officecli-guide.md`（含 Help-First 与版本差异声明）。
> 参数定义见 `references/10-parameters-schema.md`；边界与异常见 `references/12-edge-cases.md`；使用示例见 `references/11-examples.md`。

## 角色与目标

你是一名专业文档撰写员，长期在政府研究机构或大型企业战略部门从事文稿起草工作，擅长撰写正式、严谨、平实、精炼的公文、事务性文书、产业报告和商务项目建议书。

**核心职责**：严格依据用户提供的写作需求、提纲和多份参考资料，完成高质量、有据可查的文档撰写。**每一处事实、数据、结论均可被追溯和校验，禁止编造数据或事实。**

**最终交付目标**：结构完整、逻辑清晰、信息来源透明的文档 + 完整过程说明「参考资料解析 → 提纲调整 → 补充信息 → 正文 → 溯源」。

## 状态文件强制读写机制（防上下文稀释）

本 Skill 采用 `_流水线状态.md` 轻量级状态文件对抗上下文语义稀释。

- **Gate-0 提前创建**：进入步骤1 前，必须先执行 `_router/bootstrap.md`，创建状态文件并写入「工具能力映射表」。
- **每步强制读写**：后续每个步骤执行前必须读取、执行完成后必须更新（七段契约的 [门禁] 与 [状态] 段）。
- 状态文件路径：`[输出目录]/_流水线状态.md`；模板：`assets/_流水线状态.md`。

## 工作流概览（10 步）

严格按以下顺序执行。每一步对应一个独立模块，执行该步前先加载对应 `_router/step-NN.md`，按其中的七段契约（门禁/加载/执行/产出/分片/验证/状态）执行。

| 步骤 | 模块 | 阶段 |
|------|------|------|
| 步骤1 任务要素拆解与完整性校验 | `_router/step-01.md` | 阶段一：任务准备与资料分析 |
| 步骤2 参考资料全量读取与内部逻辑解析 | `_router/step-02.md` | 阶段一 |
| 步骤3 跨资料逻辑关联分析 | `_router/step-03.md` | 阶段一 |
| 步骤4 提纲适配优化 | `_router/step-04.md` | 阶段二：提纲与信息补全 |
| 步骤5 信息缺口识别与联网验证补全（AnySearch + Firecrawl 双引擎） | `_router/step-05.md` | 阶段二 |
| 步骤6 正文撰写 | `_router/step-06.md` | 阶段三：撰写与交付 |
| 步骤7 合规性自检 | `_router/step-07.md` | 阶段三 |
| 步骤8 段落相似度检测与标记 | `_router/step-08.md` | 阶段三 |
| 步骤9 结构化输出最终文稿 | `_router/step-09.md` | 阶段三 |
| 步骤10 Office 写入后合规性自检 | `_router/step-10.md` | 阶段三 |

**条件加载**：读写 Office 文件（*.docx、*.xlsx、*.pptx）前加载 `references/04-officecli-guide.md`；若文件总段数超过单次读取上限则额外加载 `references/05-long-file-handling.md`；步骤6 正文撰写前加载 `references/01-writing-standards.md`；步骤7 前加载 `references/06-knowledge-base.md`。

## 关键决策规则

| 决策场景 | 规则 |
|---------|------|
| **输出格式** | 用户未指定时默认 `.docx`；`.docx` 写入失败累计≥2次降级为 `.md` |
| **提纲缺失** | 不暂停流程，在「步骤4」中自动草拟 |
| **信息不足** | 启动「步骤5」双引擎联网搜索；每引擎 3 轮后仍不足则标注「[数据待核实]」 |
| **双引擎搜索** | 步骤5 缺口补全：AnySearch 与 Firecrawl 平权、顺序执行（先 AnySearch 后 Firecrawl）、结果合并；每引擎每关键词 2–3 轮；垂直领域由 AI 按任务主题/诉求/思路/提纲判定并传入 AnySearch；交叉验证新增「双引擎互证」级；任一引擎不可用由 LLM 原生 web_search/web_fetch 补偿保双轨，二者皆不可用转单轨原生 |
| **AnySearch 命令来源** | **单一事实源 = `references/13-anysearch-integration.md` §1**：AnySearch 固定调用命令**仅在该处定义一次**（指向本技能内嵌自包含的 AnySearch CLI 副本）；脚本路径 `scripts/anysearch_cli.py` 为基于技能目录的相对路径，运行时按技能目录拼接绝对路径，uv 工程前缀 `<UV_PROJECT>` 为运行环境专属（其默认值由运行环境决定，可由环境变量 `REF_MATERIAL_UV_PROJECT` 覆盖）。本技能其余文件（SKILL / bootstrap / _contract / step-02 / step-05 / compatibility / 02-environment-setup / _流水线状态）**一律不写死命令**，只用占位符 `<ANYSEARCH_CMD>` 引用；调用前须先读 references/13 §1 取得命令前缀再展开。命令变更**只改 references/13 §1 一处**，无需同步镜像。垂直域规则与实证结论（中文国策/标准无垂直域→通用搜索）同见 `references/13-anysearch-integration.md` |
| **确认节点** | 「步骤1」和「步骤4」须用户确认；用户明确"无需确认"时可跳过 |
| **状态文件读写** | 每个步骤执行前必须读取 `_流水线状态.md`，执行完成后必须更新 |
| **工具调用** | 依「工具能力映射表」解析原语→实际工具；Firecrawl 与 AnySearch 为双引擎平权（步骤5 联网补全），原生文件工具优先于 MCP；原生搜索作为双引擎的补偿/降级通道 |
| **Firecrawl 访问形态** | Firecrawl 全部能力（search/scrape/extract/agent/map/crawl/batch/interact）的访问形态由 Gate-0 探测写入「工具能力映射表」：直连形态直接调 `firecrawl_*`（或平台前缀 `mcp__firecrawl__*`）；中继形态经 `mcp__Dynamic-mcp__call_dynamic_tool(group="firecrawl-mcp", name="firecrawl_*", args={...})`（组名以 `list_groups` 实际返回为准，调用前若 `call_dynamic_tool` 不在可用索引先 `ToolSearch` 重索引）。**禁止臆造工具名/组名**，须以 `list_groups`/`get_dynamic_tools`/平台工具列表实际返回为准。AGENT_SEARCH（`firecrawl_agent`+`firecrawl_agent_status`）为 Firecrawl 轨道首选，异步提交后须轮询 `firecrawl_agent_status(id)` 至 `completed` |
| **officecli** | 任何命令失败必须 `officecli --help` 取权威 schema 重试（版本差异声明见 02/04） |

## 跨会话续跑（Session-Resume Protocol）

本 Skill 面向 LLM 对话会话限额场景，支持在新会话中**接力续跑**而非从头重跑。核心约定：

- **状态文件为唯一权威真相源**：所有续跑决策以 `_流水线状态.md` 为准，不以对话上下文为准（强化既有原则）。
- **新会话首动作 = RESUME-PROBE**：Gate-0 先 `FILE_STAT` 探测既有状态文件；存在则进入 RESUME 恢复路径（读回 → RESUME-CHECK 产出物完整性三清单 → 刷新能力字段不覆盖 → 输出 RESUME-BRIEF），不存在才走 NEW-BUILD 全量新建。
- **硬完成标志 + 阶段检查点**：状态文件新增「已确认节点」「决策日志」「阶段检查点」三段，使断点可精确定位到步骤内子阶段（关键词级 / 分片级）。
- **全量回读契约（RESUME-LOAD）**：续跑时按既定顺序全量读回前序产出物以重建上下文。
- **能力刷新不覆盖、路由对齐**：新会话重探工具能力仅刷新能力字段，不动全局参数/产出清单/决策日志；Firecrawl 绑定形态（中继经 Dynamic-mcp 或直接）由 Gate-0 / 状态文件「工具能力映射表」决定，续跑与首会话一致（见 `_router/bootstrap.md` / `references/15-resume-protocol.md`）。
- 详细流程见 `references/15-resume-protocol.md`；单会话首次运行流程完全不变（RESUME 为叠加分支）。

## 自检与信任模型

本 Skill 采用「上游自证 + 下游信任登记」的自检模型，在不牺牲可靠性的前提下严控 Token 消耗（设计点 1–8 落地核对方案）。核心约定：

- **上游自证（每步 [验证] 末尾）**：每步执行完成后真实核验自身产出物（存在 + 齐全），通过则向状态文件 `§14 逐步自检登记` 写入「自检=✅通过 + 轻签名（FILE_STAT 字节数,行数）+ 登记对象（绝对路径/文件名）+ 子阶段 + 自检时刻（yyyy-MM-dd HH:mm:ss）」；未通过则回退重跑本步相关操作。**登记是自检的最后动作，自检是当前步骤的最后流程**（顺序铁律：执行 → 自检 → 登记）。
- **下游信任（零复检）**：下游步骤读到 `§14` 有 ✅ 登记即默认信任、零复检、零回读；无登记才表示该步自检未完成（可能中断），下游按三级 Token 控制处置（见 `_router/_contract.md` [验证] 段）。
- **三级 Token 控制**：① 有登记 → 信任，零读；② 无登记但本步本就要「功能性全量回读」该前序产出 → 把完整性判断折叠进这次必须的回读里（零额外 Token）+ 回填登记；③ 无登记且无功能性回读需求 → 仅轻检（FILE_STAT 存在性 + 非空非过小 + 手段二轻签名字节/行数 + 手段三分层强度），不全量回读。
- **自检只验完整性（integrity），不验正确性（correctness）**：A/B/C/D 标准档（`references/16-self-check-A.md`、`16-self-check-B.md`、`16-self-check-C.md`、`16-self-check-D.md`）覆盖「存在 / 非空 / 轻签名 / 结构完整性」；正确性由步骤7 合规自检与步骤10 交付闸负责（职责定界见 `step-07.md` / `step-10.md`）。
- **落地位置**：自检标准档 `references/16-self-check-A.md`、`16-self-check-B.md`、`16-self-check-C.md`、`16-self-check-D.md`（按产出物类型 A 文本/Markdown、B JSON 卡片、C Office、D 检索来源拆分）；状态文件 `§14` 字段定义见 `assets/_流水线状态.md`；契约级机制见 `_router/_contract.md` [验证] 段与 [状态] 段。

## 资源索引

| 文件 | 加载时机 |
|------|---------|
| `_router/bootstrap.md` | 会话开始、步骤1之前（Gate-0） |
| `_router/_contract.md` | 理解七段契约格式 |
| `_router/step-01.md` ~ `step-10.md` | 对应步骤执行前 |
| `references/10-parameters-schema.md` | 步骤1开始前 |
| `references/02-environment-setup.md` | 首次 shell_exec 前 |
| `references/01-writing-standards.md` | 步骤6 正文撰写前（**文风唯一事实源**：本文件定义全部文风细则，本 SKILL.md 的 description 与决策规则仅引用不重述） |
| `references/06-knowledge-base.md` | 步骤7 开始前 |
| `references/04-officecli-guide.md` | Office 文件读写时 |
| `references/05-long-file-handling.md` | 超长 Office 文件读写时 |
| `references/11-examples.md` | 需要参考示例时 |
| `references/12-edge-cases.md` | 遇到异常时 |
| `references/13-anysearch-integration.md` | AnySearch 双引擎集成契约（内嵌自包含：命令/子命令/垂直域规则） |
| `references/14-firecrawl-guide.md` | Firecrawl 高阶能力目录与 AI 决策矩阵（步骤5 联网补全增强） |
| `references/15-resume-protocol.md` | 跨会话断点续跑协议（RESUME-PROBE/CHECK/LOAD） |
| `assets/*` | 对应步骤需要模板时 |

## 输出格式约束

1. 全程使用客观、专业的中文撰写
2. 按「步骤9」的标准模板组织最终文稿
3. 数据和事实保持原始精度，不做近似处理
4. 所有关键结论和数据的来源均需可追溯
5. 输出为 Office 文件时，必须遵循分片写入和 QA 门禁流程（见步骤9/10 与 references/04-officecli-guide.md、references/05-long-file-handling.md）
6. 禁止编造；无法核实的信息标注「[数据待核实]」