文案与措辞：根据读者与目的选择表达
把要表达的意思变成读者容易理解、符合场景且不改变原意的文字。根据目的选择描述角度与风格，把抽象主张写具体，再整理段落、句子与要求强度。
读者、场景、目的与内容依据按文档写作原则确定。本文承接这些判断，处理“同一个意思怎样说更有效”；改写时发现主张不清或事实不足，应先补足内容。
根据目的选择风格
风格包括语气、节奏、详略、术语密度和修辞方式。下面是选择依据，不是每类内容必须采用的固定写法。
| 当前目的与场景 | 可以采用的表达 | 重点检查 |
|---|---|---|
| 帮助陌生读者查找和选择，如专题介绍、目录 | 具体、直接，从读者能识别的问题、用途或结果切入 | 能否判断与自己是否相关、下一步去哪里 |
| 解释原理、指导操作，如技术说明、教程 | 准确、有层次，按读者基础补背景、推导和步骤 | 能否理解原因、正确操作；术语和条件是否充分 |
| 吸引关注、建立印象，如推广页、活动文案 | 鲜明、有节奏，可用比喻、故事、口号或情绪表达 | 是否吸引目标读者、突出真实特点，事实承诺是否可靠 |
| 说服读者、支持决定，如提案、观点文章 | 立场明确，组织理由、证据与取舍，也可用叙事增强感受 | 是否回应读者关切，理由能否支撑结论 |
| 记录经历、表达感受，如个人随笔、创作 | 保留个人口吻、细节、节奏和留白 | 是否传达想表达的经验与感受，润色是否抹掉作者声音 |
| 提示状态、帮助恢复，如错误信息、操作反馈 | 明确、体谅处境，必要时安抚并给出下一步 | 读者能否知道发生了什么、影响什么、接下来怎么办 |
同一页面也可以有不同风格：开场吸引注意，介绍说明用途，操作提示保持准确。它们服务不同的局部目的，同时维持一致的身份与事实含义。
按表达需要选择描述角度
描述角度决定从对象的哪一面切入，风格决定用怎样的语气和节奏表达。同一对象可以从不同角度描述，也可以用不同语气表达同一个角度。选能服务当前目的的角度，必要时组合；一段介绍不需要把所有角度写全。
| 描述角度 | 回答读者什么问题 | 什么时候有用、怎么写 | 写法示例 |
|---|---|---|---|
| 对象与范围 | 这是什么，涉及哪些内容？ | 读者尚不能辨认对象时，用熟悉的类别定位，并说明影响选择的范围。名称或列表已足够清楚时省略重复介绍。 | 面向命令行 Agent 的交互式终端工具。 |
| 问题与场景 | 我遇到的困难，这里能处理吗？ | 导航、排障入口和专题介绍优先写读者能认出的现象，不要求他先知道内部机制或根因。 | Skill 不触发、Agent 不遵守约束，怎么办？ |
| 任务与用途 | 我可以用它做什么？ | 用具体动作和对象表达用途，适合教程、工具和操作入口。 | 查看一次 Pi 会话的执行过程。 |
| 结果与变化 | 做完之后能得到什么，有什么不同？ | 说明具体成果或行为变化，让读者判断是否值得投入。教程要达到的目标与已经取得的结果分别表达。 | 让 Agent 写出的文档便于人阅读、使用和审阅。 |
| 机制与差异 | 它怎么做到，为什么适合我？ | 机制影响使用选择、理解或排障时再讲，并说明它对任务的实际影响。 | 人可以随时接手 Agent 正在使用的终端，完成需要本人操作的步骤。 |
| 事实与证据 | 我凭什么作出这个判断？ | 展示作品、输入输出、行为实例、测试条件和结果，让读者看到主张的依据。 | 展示同一任务的修改前后输出，说明改了什么、哪些问题仍然存在。 |
| 经历与感受 | 作者经历了什么，为什么在意？ | 用具体场景、变化和个人声音表达体验，适合随笔、故事和介绍创作动机。 | 我开始做这个工具，是因为每次执行到登录那一步，都得来回切换终端。 |
| 观点与态度 | 作者怎么看，希望我注意什么？ | 明确表达立场、偏好或愿景；需要说服时展开理由，帮助读者认识作者时保留个人判断。 | 我更希望工具把控制权交还给使用者。 |
在帮助读者选择内容的场景中，“客观”不保证有信息量。“这里提供一组 Skill”可以准确，但读者仍不知道为什么要用；“如何借助 Agent，从产品设计推进到可交付、可维护的应用”说明了专题的用途。需要解释各项 Skill 的分工时，再进入具体内容。
陌生读者带着需求查找内容时，问题式和结果式表达便于识别。“如何提升效率”仍然宽泛，“如何查看 Agent 卡在哪一步”才给出了具体问题。读者来这里欣赏作品、了解作者或阅读故事时，则按相应目的选择角度。
遇到空泛表达，决定改写、补事实还是删除
需要说明能力，却只剩自夸：补具体依据
工具介绍要帮助读者判断是否适用时，“强大、专业、全面、高效、全能”等评价没有充分说明能力。找出评价背后具体的行为或结果，直接写出来；需要证明效果时提供相应材料。宣传中的鲜明语气可以保留，但有关能力和效果的承诺仍要有依据。
例如，“全能的 Bash 工具”没有说明差异，“人可随时接手 Agent 正在使用的终端”给出了可理解的行为。若要进一步声称“更高效”，就需要说明哪项任务减少了哪些步骤，或在什么条件下取得了怎样的结果。
没有支撑时删去评价，不用“相关能力”“多种功能”等中性词替换它。
中性但无增量的介绍：做删除比较
按内容取舍的删除比较判断介绍是否有作用。
“这里展示我的 AI 与 Agent 项目”下方若已经是这些项目，可以直接展示作品。若分类不明显，一个明确的分组标题可能就足够；若用途不明显，应补具体用途，而不是再介绍一遍“这里有什么”。
用于帮助选择的摘要，应让读者少做一项归纳或判断。仅重述标题、列表或页面结构，又没有其他表达作用的句子，可以删除。用于强调或形成节奏的重复，则看它是否产生预期效果。
读者不熟悉内部分类：翻译成能识别的用途
当入口需要帮助陌生读者选路时，从内部名称出发，追问：读者什么时候会需要它？会遇到什么现象？用它能完成什么？将答案放在入口，机制说明留在读者需要理解原因或取舍的位置。
专业术语用于精确指认，不用于替代用途说明。项目名不清楚时，可配一句具体用途；模板名、命令名已经便于检索时，保留原名。
笼统的好处与原则：补上会改变判断的信息
“提高质量”“保持清晰”“遵循最佳实践”很难指导当前动作。说明具体阻碍、选择依据或可检查的变化。
例如，把“文档要清晰易懂”展开成“目录用读者能识别的问题引导选读，不要求读者先知道根因”，读者才知道应怎样修改。仍说不出具体差异时，先补充事实或重新想清主张，不靠增加形容词和句子凑信息量。
防御性解释：把必要条件写进主张
正面表达完整的主张，把必要的范围、条件与确定程度交代清楚，再用依据、做法和示例帮助读者理解与执行。为防备假想误读而追加的限定、例外或提醒，应直接删去或将其中的必要信息融入主张。
例如，将“清理全部缓存，但不包括正在使用的缓存”写成“清理未被使用的缓存”。条件影响读者决定时，在相关主张处说明；无需用连续的“不是……”“不代表……”围绕一句话补充辩解。
选好内容之后，再整理段落与句子
说明、指导和论证段落围绕一个中心展开，一条要求只讲一个主张。写完用一句话说出这段让读者得到的判断或做法：说不出，先想清主张；说出的是多件并列的事，用列表或拆段分开。叙事与抒情段落则按事件、感受和节奏组织。
技术说明、要求与操作文案的句子表达参照 ASD-STE100（Simplified Technical English）的下列结构原则；其英文词汇与时态规则不直接用于中文：
- 一句只做一个动作或一个主张，多个动作或条件拆开写。
- 用主动语态并写明施动者，施动者确实未知时除外。
- 省略与指代只在不存在第二种解读时使用。
- 同一概念全篇使用同一个词，不做同义词轮换。
明确区分必须、建议与可选，说明适用条件，不把可能包含的内容写成必填项。供机器解析或执行的文本，如工具描述、错误信息、Agent 间指令和操作步骤，按歧义零容忍检查。
语气符合用途与说话者。个人记录可以表达经历、观点和感受；操作提示说明动作与结果。润色后核对原意、确定程度和承诺范围，例如“不在网站公开”不能仅为口语化而改成“只有我能看到”。
应用：让专题与目录帮助读者找到所需内容
以下以知识库的公开专题为例：目标是让不熟悉内部体系的读者判断内容是否适合自己，并找到下一篇。
专题描述：说明为什么值得进入
先用一句话交代整个专题帮助解决的问题或完成的任务，再补影响选择的范围、方法或阅读前提。读者应能判断这是不是自己需要的内容，而不只是知道作者收集了哪些材料。
下面示范如何把分类介绍改为用途说明：
| 专题 | 只介绍内容的写法 | 面向读者的写法 |
|---|---|---|
| Agent 设计与改进 | Agent 的原理、Skill、工具与测试方法。 | 如何设计和改进 Agent、优化 Skill，并通过实际任务判断改动是否有效。 |
| AI 软件工厂 | 用于软件设计、实现与验收的一组 Skill，以及使用记录。 | 如何借助 Agent，从产品设计、体验与架构设计推进到工程实现，交付可维护的应用。 |
| 文档写作 | 文档的组织、表达与修改方法。 | 如何指导 Agent 写出人能读、能用、能审阅的文档，减少空泛修辞、重复介绍和防御性解释。 |
说明用途时，保留内容实际支持的范围。“如何判断改动是否有效”提供一种判断方法；“确保每次优化都有效”则承诺了每次结果。不能靠扩大承诺让描述显得有吸引力。
目录与标题：帮助选择下一步
读者带着问题找内容时，用问题、现象或任务命名；读者寻找已知对象时，保留准确名称。分组可以使用简短领域名，具体条目说明要解决什么，两者共同完成导航。
- “能力发现与纠偏”面向了解机制的人；对遇到问题的人，可以写“Skill 不触发、Agent 不遵守约束怎么办”。
- “终端接续”隐去了用途；“人可随时接手的 Agent 终端”直接说明行为差异。
- “执行观察”范围不明；“查看 Pi 会话的执行过程”说明对象和动作。
- “测试记录模板”已经能让读者识别目标，无需硬改成问句。
仅给名词加上“如何”通常不够。写完后检查：读者能否在几项相近内容中选中所需的一项？标题带来的预期是否与到达后的内容一致？
改写后的表达核对
将改写结果放回实际页面或段落，检查三件事：
- 是否更容易理解：描述角度、术语、指代和句子关系是否清楚？标题与介绍带来的预期是否与正文一致？
- 是否保留原意：事实、适用条件、确定程度、要求强度和承诺范围有没有变化？方法、目标与已取得的结果是否分清？
- 是否符合场景：语气、节奏和详略是否服务当前目的？是否为追求统一风格抹掉了个人声音或必要衔接？
整篇文档能否支持理解、判断和行动，按修改与检查走读。
#写作 #知识管理