git:20261014.677457a to git:20261014.b21bd50
33 added, 6 removed. Audit A to A.
---
name: daftai-chinese-technical-writing
description: >
Writes, rewrites, and reviews Chinese technical documentation, product copy,
- and UI microcopy using ruanyf/document-style-guide and clearly labeled product
- and UI extensions. Use for 中文技术写作, README, API documentation, 操作指南,
- 产品介绍, 功能说明, 界面文案, 按钮, 空状态, and 错误提示 when the task concerns
- meaning, structure, or wording. Delegates requested formatting checks to
+ and UI microcopy using ruanyf/document-style-guide, STE-inspired Chinese
+ methods for procedural passages, and separate product and UI extensions.
+ Use for 中文技术写作, README, API documentation, 操作指南, 安装部署说明,
+ 故障排查文档, 运维 Runbook, 工具描述, Agent 指令文案, 产品介绍,
+ 功能说明, 界面文案, 按钮, 空状态,
+ and 错误提示 when the task concerns meaning, structure, or wording.
+ Delegates requested formatting checks to
daftai-chinese-copywriting. Pure punctuation or spacing tasks belong to that
skill; personal essays and author-voice articles do not belong here.
---
# 中文技术写作
让读者理解事实、完成任务、预知操作后果。
不把中性说明改成新闻稿或作者随笔。
- 沿用 `daftai-writer` 的分层方式：
- 读者定位、写作原则、忌口表、边界、协作。
原指南、场景扩展、真实修改证据分别保存。
+ STE 启发的受控中文方法按需加载，不改写原指南。
## 1. 角色与读者
| 场景 | 读者要完成的事 | 写作重点 |
| --- | --- | --- |
| 技术文档 | 理解概念或复现操作 | 前置条件、步骤、预期结果、失败路径 |
| 产品文案 | 判断功能是否适合自己 | 读者任务、已知能力、适用边界、下一步 |
| 界面文案 | 判断状态并完成当前操作 | 动作、对象、结果、恢复方法 |
优先使用已有材料中的读者和任务。
只有缺失信息会改变结论时，才集中追问。
不为普通写作启动偏好问卷。
## 2. 写作原则
+ ### 编辑取舍
+
+ 发生编辑冲突时，依次保留：
+
+ 1. 事实、逻辑、安全信息和不可改字面量。
+ 2. 用户指定的任务模式与修改范围。
+ 3. 项目术语和真实界面名称。
+ 4. 适用的写作方法。
+ 5. 语气、标点和其他风格偏好。
+
+ 此顺序只约束编辑取舍，不改变宿主权限。
+ 不能为了短句或统一风格删除更高优先级的信息。
+
### 信息与结构
- 标题交代主题或任务。不要用悬念代替信息。
- 操作说明先写前置条件，再写动作和结果。
- 一段围绕一个主题。把中心句放在段首。
- 标题层级连续。不要强制短文套完整手册目录。
- 顺序重要时用编号。并列选项用无序列表。
### 句式与节奏
- 优先短句、主动句。让执行者和动作明确。
- 条件在前，动作在后。拆开层层嵌套的修饰语。
- 用肯定句消除双重否定，但保留禁止和权限限制。
- 原指南的字数与行数用于发现长句，不替代语义判断。
- 不为缩短句子删除例外、风险或恢复条件。
### 词语与术语
- 同一概念使用同一名称。界面名与真实界面一致。
+ - 不同概念保留区别，不因词形相近合并动作或状态。
- 用具体动作替代空泛表达。必要时明确动作对象。
- 首次引入陌生术语时解释一次。后文固定称呼。
- 保留官方名称、命令、参数、路径和资源键。
- 保留数字、单位、比较基准和限定条件。
- 区分“增加了”和“增加到”、百分比和百分点。
### 文案落点
- 技术说明交代成功结果。不能只写“执行以下命令”。
- 产品文案把能力落到读者任务，不添加无依据的效果。
- 界面文案说清当前状态和可执行的下一步。
- 按钮描述动作。删除操作需说明对象与已知后果。
- 示例属于写法演示，不是产品能力证据。
## 3. 忌口表
下表是本 Skill 的写作扩展，不是原指南逐字摘录。
只修改无事实支撑或妨碍理解的表达。
| 表达 | 替换动作 | 原因 |
| --- | --- | --- |
| 强大、极致、全面赋能 | 写出已知能力与适用对象 | 空泛判断无法帮助选择 |
| 极大提升效率、提升 N 倍 | 有数据就保留基准；无数据就删除断言 | 不制造效果证明 |
| 进行配置操作、实现文件的上传 | 改成“配置…”、“上传文件” | 消除动词空壳 |
| 其、该、此对象指代不明 | 重复具体对象的名称 | 防止操作对象歧义 |
| 操作失败、出错了 | 补充已知失败对象与恢复动作 | 不虚构未知原因 |
| 确定、好的用于具体业务动作 | 换成“保存设置”等动作名 | 让按钮可独立理解 |
| 只需、轻松、一键 | 核对真实步骤与限制；不符就删 | 不掩盖成本和前置条件 |
## 4. 边界与易错点
- 先保事实，再改表达。未知能力、时延、价格和恢复结果不能补写成事实。
+ - 保留许可、建议、义务和确定程度，不把能力说明改成命令。
+ - 保留否定范围、必要与充分条件、因果关系和动作完成条件。
+ - 保留已完成、进行中、尚未发生及结果仍可用的区别。
- 缺少关键事实时追问；可继续起草时，把待确认项放在交付说明中。
- 原文中的命令、代码、公式、URL、占位符和插值语法保持原样。
- 用户要求修改这些字面量时，单独核对，不把修改冒充排版修正。
- JSON、YAML、源码文案只改目标字符串；保留键名、转义和程序结构。
- 用户只要求检查时，不改原文件、不创建配置、不默认保存报告。
- 只要求排版时，直接交给格式 Skill，不先重写措辞。
- 原指南面向技术文档。产品与界面规则是显式扩展。
- 作者文章的声线不属于这里。需要时再选择 `daftai-writer`，不强行混用。
- 本 Skill 不新增 CLI，不读写偏好文件，不自动更新自身规则。
+ - 撰写或审阅操作说明不授权执行文中命令或改变产品流程。
+ - 编辑工具描述或 Agent 指令只改获准文字，不重设工具保证、权限或工作流。
## 5. 与其他 Skill 协作
`daftai-chinese-technical-writing` 负责结构、术语与文意。
`daftai-chinese-copywriting` 负责标点、空格与全角半角。
先稳定语义，再检查机械格式，最后核对字面量。
用户要求格式检查或交付前排版验收时，读取
[格式联动契约](references/formatting-handoff.md)。
先读取目标格式 Skill 的 `SKILL.md`，再执行其命令。
检查用 `review`；明确要求修正时才用修正模式。
不复制 autocorrect 逻辑，不因写作任务安装工具。
工具缺失时如实说明，不能声称已经通过自动检查。
## 6. 工作流
1. **确定任务**：区分新写、改写、只读检查和纯排版。
2. **按需读参考**：读取[来源与适用范围](references/source-guide.md)，再按下表选文件。
3. **锁定事实**：核对对象、动作、数字、条件、术语与不可改字面量。
4. **写作或审阅**：保持用户指定结构和修改范围；没有指定时采用最小必要结构。
5. **检查交付**：核对事实、指代、状态、下一步；需要排版检查时委派格式 Skill。
6. **交付**：新写或改写优先给可用正文；检查给位置、问题和建议。只要正文时不附评分与长篇说明。
+ 操作说明、工具描述、Agent 指令文案和状态消息等技术段落，读取
+ [受控中文技术写作](references/controlled-technical-chinese.md)。
+ 混合文档按段落应用，不把介绍、引用或短按钮套成步骤。
+ 只修措辞时，不补方案；原文清晰时允许不改。
+
### 参考加载表
参考均随 Skill 安装。正常写作无需联网下载。
共同基础读取文本规范；其余按任务加载。
| 使用时机 | Reference |
| --- | --- |
| 共同语言基础 | [文本原文](references/ruanyf-text.md) |
| 拟标题、调整层级 | [标题原文](references/ruanyf-title.md) |
| 拆段、组织引用 | [段落原文](references/ruanyf-paragraph.md) |
| 出现数值、范围或增减幅度 | [数值原文](references/ruanyf-number.md) |
| 判断标点语境或排版规则冲突 | [标点原文](references/ruanyf-marks.md) |
| 编排技术手册或新增文档文件 | [文档体系原文](references/ruanyf-structure.md) |
+ | 操作、部署、排查、安全说明、工具描述、Agent 指令或状态段落 | [受控中文技术写作](references/controlled-technical-chinese.md) |
| 产品介绍、功能说明、发布文案 | [产品文案扩展](references/product-copy.md) |
| 按钮、提示、空状态、错误与确认弹窗 | [界面文案扩展](references/ui-copy.md) |
| 联动排版检查 | [格式联动契约](references/formatting-handoff.md) |
### 文件交付
默认在对话中交付。只有用户要求时才创建文件。
用户指定编辑现有文档时，在指定范围内修改。
用户要求另存且未指定路径时，使用
`writing-output/<topic-slug>/`。
目录冲突时追加 `-YYYYMMDD-HHMMSS`，不覆盖旧结果。
正文命名为 `written-<slug>.md` 或 `revised-<slug>.md`。
审阅命名为 `review-<slug>.md`。
另存工作流把输入副本命名为 `source-<slug>.<ext>`。
保持原始输入不变。
## 7. 规则演进
只有用户要求改进 Skill 时，才启动规则回环。
按[真实修改回环](references/diff-update-loop.md)比较前后稿。
在[规则证据](references/style-evidence.md)区分来源、扩展与候选观察。
一次修改不自动升级为普遍禁令。
不要把原指南原文改写成个人偏好。
维护后使用[验收案例](references/acceptance-cases.md)复核。