AI 技术写作辅助：结构化大纲与内容润色的工程实践
AI 技术写作辅助：结构化大纲与内容润色的工程实践
一、技术写作的效率瓶颈与 AI 辅助的切入点
技术写作的效率瓶颈不在"写"本身，而在"想清楚写什么"和"确保写得对"。一篇深度技术文章的典型时间分配是：选题与大纲构建占 40%，初稿撰写占 30%，代码示例与图表制作占 20%，校对润色占 10%。AI 辅助的最大价值在于加速前 40% 的大纲构建和后 10% 的润色校对——这两个环节恰好是最容易标准化的。
然而，直接让 AI "写一篇文章"的效果通常很差。原因是 AI 缺乏对文章深度、目标读者和论证逻辑的理解，生成的文本往往是正确的废话。有效的 AI 辅助写作需要将创作过程拆解为可标准化的步骤，在每个步骤中给 AI 提供足够的上下文和约束。
二、AI 辅助写作的流程设计
AI 辅助写作的核心流程分为五个步骤，每一步都有明确的输入、输出和 AI 的角色定位。
graph LR A[1. 选题与定位] --> B[2. 大纲生成] B --> C[3. 段落扩写] C --> D[4. 代码与图表] D --> E[5. 润色与校对] A -->|AI 角色: 热点分析| A1[输出: 选题 + 读者画像] B -->|AI 角色: 结构建议| B1[输出: 四级大纲] C -->|AI 角色: 初稿生成| C1[输出: 段落初稿] D -->|AI 角色: 代码审查| D1[输出: 代码片段 + Mermaid] E -->|AI 角色: 风格检查| E1[输出: 修正建议]选题与定位阶段，AI 的角色是信息聚合——分析技术社区的热点话题、评估选题的差异化空间。但选题的最终决策权在人类，AI 只提供数据支撑。
大纲生成阶段，AI 的角色是结构化建议——基于选题生成多种可能的大纲结构，由人类选择和调整。AI 生成的大纲通常过于泛化，需要人类注入具体的论证角度和实战经验。
段落扩写阶段，AI 的角色是初稿生成——基于大纲的每个章节，生成包含技术细节的初稿。这一步的效果高度依赖 Prompt 的精确度。
代码与图表阶段，AI 的角色是代码生成和 Mermaid 图设计——根据文章内容生成配套的代码示例和架构图。
润色与校对阶段，AI 的角色是风格检查和逻辑审查——检测禁用词、长句、繁体字和逻辑矛盾。
三、AI 辅助写作的工程实现
3.1 大纲生成与结构化审查
from dataclasses import dataclass, field from typing import Optional from enum import Enum class SectionType(Enum): INTRODUCTION = "introduction" # 引言痛点 PRINCIPLE = "principle" # 原理剖析 IMPLEMENTATION = "implementation" # 代码实现 TRADEOFF = "tradeoff" # 边界权衡 SUMMARY = "summary" # 总结 @dataclass class OutlineSection: level: int # 层级：1=章, 2=节, 3=小节 title: str section_type: SectionType key_points: list[str] needs_code: bool = False needs_mermaid: bool = False estimated_words: int = 0 @dataclass class ArticleOutline: title: str target_reader: str sections: list[OutlineSection] total_estimated_words: int = 0 class OutlineValidator: """大纲结构合规性校验器""" REQUIRED_TYPES = { SectionType.INTRODUCTION, SectionType.PRINCIPLE, SectionType.IMPLEMENTATION, SectionType.TRADEOFF, SectionType.SUMMARY, } def validate(self, outline: ArticleOutline) -> list[dict]: """校验大纲是否符合五模块结构""" issues = [] # 规则 1: 必须包含五个核心模块 present_types = {s.section_type for s in outline.sections} missing = self.REQUIRED_TYPES - present_types if missing: issues.append({ "type": "missing_section", "severity": "high", "detail": f"缺少必要模块: {', '.join(t.value for t in missing)}", }) # 规则 2: 至少一个章节需要 Mermaid 图 has_mermaid = any(s.needs_mermaid for s in outline.sections) if not has_mermaid: issues.append({ "type": "missing_mermaid", "severity": "high", "detail": "大纲中没有任何章节标记需要 Mermaid 图", "suggestion": "在原理剖析章节添加架构图或流程图", }) # 规则 3: 至少一个章节需要代码示例 has_code = any(s.needs_code for s in outline.sections) if not has_code: issues.append({ "type": "missing_code", "severity": "high", "detail": "大纲中没有任何章节标记需要代码示例", "suggestion": "在代码实现章节添加生产级代码片段", }) # 规则 4: 总字数预估应 >= 1000 total_words = sum(s.estimated_words for s in outline.sections) outline.total_estimated_words = total_words if total_words < 1000: issues.append({ "type": "insufficient_words", "severity": "medium", "detail": f"预估总字数 {total_words} 低于 1000 字要求", "suggestion": "扩展原理剖析或代码实现章节的深度", }) # 规则 5: 总结章节标题必须是固定格式 for s in outline.sections: if s.section_type == SectionType.SUMMARY: if s.title not in ("总结", "结语"): issues.append({ "type": "invalid_summary_title", "severity": "medium", "detail": f"总结章节标题 '{s.title}' 不符合规范", "suggestion": "修改为 '总结' 或 '结语'", }) return issues3.2 段落扩写与上下文管理
class SectionExpander: """基于大纲的段落扩写器""" EXPAND_PROMPT = """请根据以下信息撰写技术文章的一个章节。 ## 文章标题 {article_title} ## 目标读者 {target_reader} ## 当前章节 标题: {section_title} 类型: {section_type} 核心要点: {key_points} ## 写作约束 1. 语气客观严谨，基于事实和数据 2. 两个标点之间的字数不超过 35 字 3. 禁止使用"震惊""必看""精通"等浮夸词汇 4. 代码注释使用中文，解释"为什么"而非"做什么" 5. 正文字数约 {target_words} 字（不含代码块） ## 输出要求 直接输出章节正文，使用 Markdown 格式。 如果该章节需要代码示例，在正文中嵌入代码块。 如果该章节需要 Mermaid 图，使用 ```mermaid 代码块。""" def __init__(self, llm_client): self._llm = llm_client def expand(self, outline: ArticleOutline, section: OutlineSection) -> str: """扩写单个章节""" prompt = self.EXPAND_PROMPT.format( article_title=outline.title, target_reader=outline.target_reader, section_title=section.title, section_type=section.section_type.value, key_points="\n".join(f"- {p}" for p in section.key_points), target_words=section.estimated_words, ) return self._llm.generate(prompt, max_tokens=section.estimated_words * 2)3.3 内容润色与一致性检查
import re class ContentPolisher: """内容润色与一致性检查工具""" # 风格规则 FORBIDDEN_WORDS = ["震惊", "必看", "精通", "小白也能懂", "极其简单", "完美无瑕"] MAX_SENTENCE_LENGTH = 35 # 繁简对照表（常见易混淆字） TRADITIONAL_MAP = { "說": "说", "學": "学", "電": "电", "腦": "脑", "時": "时", "個": "个", "這": "这", "那": "那", "為": "为", "與": "与", "從": "从", "來": "来", "過": "过", "還": "还", "開": "开", "關": "关", "體": "体", "點": "点", "問": "问", "題": "题", "實": "实", "驗": "验", "證": "证", "據": "据", } def polish(self, text: str) -> tuple[str, list[dict]]: """润色文章并返回修改记录""" changes = [] # 1. 繁体字转简体 text, trad_changes = self._fix_traditional(text) changes.extend(trad_changes) # 2. 禁用词检测 for word in self.FORBIDDEN_WORDS: if word in text: changes.append({ "type": "forbidden_word", "original": word, "suggestion": "替换为客观表述", }) # 3. 长句拆分建议 long_sentences = self._find_long_sentences(text) for sent in long_sentences: changes.append({ "type": "long_sentence", "original": sent[:50] + "...", "suggestion": f"建议拆分（{len(sent)} 字）", }) # 4. 标题格式检查 title_issues = self._check_titles(text) changes.extend(title_issues) return text, changes def _fix_traditional(self, text: str) -> tuple[str, list[dict]]: """繁体字转简体""" changes = [] for trad, simp in self.TRADITIONAL_MAP.items(): if trad in text: count = text.count(trad) text = text.replace(trad, simp) changes.append({ "type": "traditional_to_simplified", "original": trad, "replacement": simp, "count": count, }) return text, changes def _find_long_sentences(self, text: str) -> list[str]: """查找过长的句子""" sentences = re.split(r'[。！？；\n]', text) return [s.strip() for s in sentences if len(s.strip()) > self.MAX_SENTENCE_LENGTH] def _check_titles(self, text: str) -> list[dict]: """检查标题格式""" issues = [] lines = text.split('\n') for line in lines: if line.startswith('# ') and not line.startswith('## '): title = line[2:].strip() if len(title) < 10: issues.append({ "type": "short_title", "original": title, "suggestion": "标题应 ≥ 10 字且含标点断句", }) if not re.search(r'[：，——、；]', title): issues.append({ "type": "no_punctuation_in_title", "original": title, "suggestion": "标题应包含标点断句（冒号、破折号等）", }) return issues四、AI 辅助写作的边界与权衡
AI 生成内容的深度不足：AI 擅长生成结构清晰、表述正确的文本，但在深度技术分析上往往浅尝辄止。例如，AI 可以描述一个算法的工作流程，但很难给出"为什么这个方案在特定边界条件下会失败"的洞察。解决方案是将 AI 定位为"初稿生成器"，深度分析由人类补充。
风格一致性的挑战：多轮 AI 生成的内容可能存在风格不一致——前半段严谨客观，后半段突然变得口语化。这需要在大纲阶段就明确每个章节的语气要求，并在润色阶段做统一检查。
代码示例的可靠性：AI 生成的代码示例可能包含微妙的 Bug 或过时的 API 用法。必须经过人工审查和实际运行验证，不能直接复制粘贴。建议在代码生成后，用独立的测试用例验证其正确性。
创作依赖的风险：长期依赖 AI 辅助可能导致独立写作能力退化。建议定期进行"无 AI 写作"练习，保持核心的思考和表达能力。AI 是工具而非拐杖。
五、总结
AI 辅助技术写作的核心价值在于加速大纲构建和润色校对两个环节，而非替代整个写作过程。结构化 Prompt 将创作意图转化为 AI 可理解的指令，大纲校验器确保文章符合五模块结构，段落扩写器生成初稿供人类修改，润色工具检查风格一致性。在工程落地时，关键原则是：AI 负责可标准化的工作（结构建议、格式检查、初稿生成），人类负责不可替代的工作（选题决策、深度分析、代码验证）。写作的本质是思考，AI 辅助的是表达而非思考本身。