jerryshell 中文技术文档与产品文案排版规范
在以下任务中使用这份 Skill：
- 文档首页、落地页、首屏文案
- 接口文档、参数说明、常见问题、更新日志
- 产品能力介绍、解决方案页、能力说明页
- 界面文案、按钮文案、导航标签、提示信息
不要用这份 Skill 去改写代码字面量、JSON 键名、URL、API 路径、数据库字段名或其他机器可读标识符。
目标
- 准确先于修辞
- 清晰先于热闹
- 导航感先于宣传感
- 可扫读先于堆砌解释
- 以信息架构和内容组织引导阅读，而不是依赖修辞或口号式表达
语气
- 使用克制、直接、可执行的中文
- 以说明、界定、引导为主，不用夸张宣传语
- 避免「领先」「强大」「重磅」「颠覆」「震惊」「炸裂」「恭喜」等空泛形容
- 优先陈述「是什么、适用于什么、下一步看哪里」
- 不用第二人称
- 避免问候式开场、平台营销话术和口号式抽象表达
- 避免使用
Hello、Hi这类问候式开场
黑话短名单
默认避免以下高危黑话词，除非用户明确要求保留，或该词在当前语境中有严格业务定义：
赋能抓手闭环沉淀对齐对标拉通打通协同联动洞察赛道心智调性战役链路势能兜底落盘收口透传串起来
以下中危词只有在语义明确时才使用：
场景生态体系路径触点卡点布局矩阵颗粒度复盘梳理输出提炼
优先替换为更具体的表达：
赋能->提供抓手->关键措施闭环->完整流程沉淀->形成/积累对齐->统一拉通/打通->连接/贯通洞察->分析结论兜底->保障机制落盘->写入文件/保存到本地收口->完成最后处理/整理完透传->原样传给下游串起来->按流程查一遍
仅在以下情况允许保留黑话原词：
- 用户明确要求保留原词
- 正在引用原始材料、访谈、方案原文或外部文档
- 该词在特定行业语境里有固定含义，替换后会损失准确性
- 该词是产品名称、功能名称、方法论名称或组织内部正式术语
如果保留黑话原词，优先采用以下处理方式：
- 首次出现时给出更具体解释
- 在同一句或下一句说明它实际指什么
- 避免连续堆叠多个黑话词
强制规则
1. 标点
- 中文引号统一使用直角引号：
「」 - 不使用中文双引号：
“” - 正文中避免连续使用多个感叹号、省略号、宣传口号式断句
- 避免使用感叹号
2. 称呼与受众
- 不使用：
你、您、同学 - 根据语境替换为：
开发者、技术负责人、实施人员、业务负责人、产品经理 - 如无必要，不直接点名读者，用无主句或说明句即可
3. 中文与英文、数字之间的留白
在可见正文中，中文与可读的半角英文单词、英文缩写、独立数字和版本号之间保留空格，以提高可读性。
推荐写法：
获取批量 IDHTTP 请求版本 2.0AI 服务与 PM 协作读取系统日志
以下内容不要机械加空格：
- 行内代码和代码块
- JSON 键名
- URL
- API 路径
- 数据库字段名
- 表头中直接镜像接口字段定义的标签
- 用户明确指定的拼写或大小写
示例：
user_id保持原样/api/example保持原样statusCode保持原样- 请求头字段名如
Content-Type在代码里保持原样
说明：
- 将中西文留白视为最终校对规则，而不是机械替换规则
- 不直接使用
pangu.js批量处理 Markdown 文档 - 如遇字段名、协议名、路径或术语边界不清的情况，优先保持原样并人工判断
4. 可见术语的大小写归一
仅对可见正文中的自然语言短语做归一：
Id/id/ID->IDhttp/Http/HTTP->HTTPurl/URL/Url->URLjson/JSON/Json->JSONapi/Api/API->APIai/Ai/AI->AI
术语大小写归一扩展清单（高频）
以下清单用于补充高频技术术语，写法统一为 错写 -> 推荐。仅作用于可见正文，不作用于代码、路径、字段和配置项字面量。
java->Javajavascript->JavaScripttypescript->TypeScriptJS/Js->JavaScriptllm/Llm->LLMaigc/Aigc->AIGCrag/Rag->RAGchatgpt/Chatgpt->ChatGPTopenai api/OpenAI api->OpenAI APIembeding->embeddingfinetune/fine tune->fine-tuning（如语义是训练过程，也可直接写微调）python->Pythongolang/go（指语言名） ->Gorust->Rustkotlin->Kotlinswift->Swiftphp->PHPruby->Rubyscala->Scaladart->Dartsql->SQLbash->Bashpowershell->PowerShellnodejs/node（指运行时或平台名） ->Node.jsdotnet->.NETreactjs->Reactvuejs->Vuenextjs->Next.jsnuxtjs->Nuxtvitejs->Vitetailwind->Tailwind CSSnginx->Nginxredis->Redispostgres/postgresql->PostgreSQLmysql->MySQLmongodb->MongoDBelasticsearch->Elasticsearchkafka->Kafkarabbitmq->RabbitMQgithub->GitHubgitlab->GitLabdocker->Dockerk8s（正式文案） ->Kuberneteshttps->HTTPSgrpc->gRPCgraphql->GraphQLwebsocket->WebSocketyaml->YAMLxml->XMLjwt->JWToauth->OAuth 2.0H5->HTML5（如语义是移动 Web 页面，优先直接写移动 Web 页面）
适用示例：
批量 id->批量 ID接口 url->接口 URL响应 json->响应 JSON启用 rag->启用 RAG接入 chatgpt->接入 ChatGPT调用 openai api->调用 OpenAI API
以下内容不要改写：
- 机器可读标识符
- 字段化标签，如
user_id - 直接镜像接口定义的表头
- 用户明确指定的大小写
5. 行动按钮文案
- 按钮文案应体现下一步动作，避免与标题重复
- 优先使用「动作 + 结果」或「动作 + 目标」
示例：
从这里开始核对调用规则初步了解
避免：
阅读平台介绍查看认证规则
当标题已经表达同一信息时，不要在行动按钮文案里重复。
常见内容类型模板
以下模板是通用写法参考，不是强制结构。项目如有专属信息架构，应由项目覆盖规则单独约定。
入口页或总览页
首段通常回答三件事：
- 覆盖什么
- 适合谁使用
- 从哪里开始读
段落保持紧凑，不要叠加口号式表达。
介绍页
第一段通常说明：
- 这页给谁看
- 这页解决什么问题
- 建议接着读哪里
解决方案页
按业务用途组织，而不是按接口清单平铺。
可参考的顺序：
- 适用场景
- 典型问题
- 推荐方案
- 推荐调用顺序
- 实施建议
- 能力边界
接口说明页
- 请求方法行放进代码块，不要裸露在正文里
- 参数说明尽量一列一义，不写含混描述
- 错误码文案要统一口径
- 不要机械直译常见英文状态词和错误词
常见误译词表：
Success- 不默认写成
成功 - 按语义选择：
已完成、已处理、请求已受理
- 不默认写成
Invalid- 不翻译成
非法 - 按语义选择：
无效、格式无效、有误、校验未通过
- 不翻译成
Available- 不机械翻译成
可用 - 按语义选择：
已开通、可获取、可访问、可使用
- 不机械翻译成
Unsupported- 优先翻译为：
暂不支持、不支持该类型、当前不支持
- 优先翻译为：
Pending- 优先翻译为：
待处理、处理中、待确认
- 优先翻译为：
Expired- 优先翻译为：
已过期
- 优先翻译为：
Missing- 优先翻译为：
缺少、未提供
- 优先翻译为：
Denied- 优先翻译为：
被拒绝、不予通过
- 优先翻译为：
Forbidden- 不直接翻译成
禁止 - 按语义选择：
无权限访问、当前不允许访问
- 不直接翻译成
Not Found- 优先翻译为：
未找到对应内容、未找到对应数据
- 优先翻译为：
Accepted- 不机械翻译成
已接受 - 按语义选择：
已受理、已接收，等待处理
- 不机械翻译成
Completed- 优先翻译为：
已完成
- 优先翻译为：
Failed- 优先翻译为：
失败 - 如上下文更偏流程处理，可用：
处理失败
- 优先翻译为：
Conflict- 不机械翻译成
冲突 - 按语义选择：
状态冲突、资源状态不一致、请求与当前状态冲突
- 不机械翻译成
Unauthorized- 不翻译成
未授权 - 优先翻译为：
未登录、认证未通过、缺少认证信息
- 不翻译成
Bad Request- 不机械翻译成
错误请求 - 优先翻译为：
请求参数有误、请求格式有误
- 不机械翻译成
Timeout- 优先翻译为：
超时 - 如需更完整，可写为：
请求超时、处理超时
- 优先翻译为：
常见问题与排查页
- 先给判断路径，再给例外
- 优先说明「先查什么」，而不是只罗列概念
- 错误排查文本要偏操作性，不要写成泛泛说明
排版与结构规则
- 一个段落只承载一个主要信息点
- 长句可以保留，但避免连续堆叠两个以上长句
- 列表项要平行，不要有的写定义、有的写宣传、有的写结论
- 标题要能反映用途，不要只写抽象名词
当同一标题下出现 4 个及以上并列项时：
- 统一命名结构
- 统一句式
- 统一信息密度
界面文案规则
- 按钮文案短，不解释背景
- 卡片描述补信息，不重复标题
- 导航标题偏名词
- 行动文案偏动作
移动端可读性规则
- 三列表参数表在移动端不应靠缩字硬挤
- 常见
参数 / 是否必填 / 说明表优先改卡片式行布局 - 真正宽表再使用横向滚动
编辑流程
- 先判断内容类型。 例如：入口页、介绍页、解决方案页、接口说明页、常见问题、界面文案。
- 先去重复。 如果标题、正文和行动按钮文案在表达同一件事，优先重写行动按钮文案。
- 应用强制规则。 统一标点、称呼、留白和常见误译词。
- 再收句子。 只保留准确阅读和下一步导航所必需的信息。
- 最后通读。 检查语气、术语、留白、标题和扫读节奏。
中文易错表达清单
用于排查词义错位、数量逻辑错误和表达歧义。优先写成「具体、可验证、不歧义」的表达。
出生于技术团队->出身于技术团队（出生仅用于生理出生）阀值->阈值请先登陆系统->请先登录系统（登陆多用于登岸）截止 4 月 12 日->截至 2026 年 4 月 12 日（时间范围优先用截至，并给完整日期）布署到生产环境->部署到生产环境配制服务器参数->配置服务器参数起用该功能->启用该功能反回结果->返回结果回朔历史版本->回溯历史版本标示字段->标识字段（指 ID、标签、标记物时）帐户余额->账户余额（金融语境）帐号登录->账号登录（平台用户语境，建议统一）搜寻日志->搜索日志即时通信->实时通信（系统能力描述语境）做为默认配置->作为默认配置系统发布到生产环境->部署到生产环境/发布新版本（区分部署与发布）完成授权（语义为身份校验） ->完成认证（认证 = 确认身份，授权 = 授予权限）缩小了 3 倍->缩小到原来的 1/3/减少了 2/3增长到 30%（原来 20%） ->从 20% 提高到 30%/相对增长 50%转化率提升了 5%（20% -> 25%） ->提升了 5 个百分点/相对提升 25%翻了 1 倍->变为原来的 2 倍不超过 100 以上->不超过 100预计大约在 3 点左右->预计 3 点/预计 3 点左右是否可以 A 或者 B->可以 A 或者 B/是否可以 A尽快处理->30 分钟内处理（将模糊词改为明确时限）使用提示工程学优化输出->使用提示工程优化输出模型出现幻听->模型出现幻觉
最终检查清单
交付前检查：
- 是否出现
你、您、同学 - 是否出现中文双引号
“” - 中文与英文、数字之间是否需要留白
- 文案是否重复标题
- 行动按钮文案是否与标题重复
- 是否存在过强的宣传口吻
- 文案是否便于扫读
改写示例
示例 1
改写前：
阅读平台介绍
改写后：
从这里开始
示例 2
改写前：
本页适合第一次进入文档中心的业务负责人、产品经理、技术负责人和实施同学。
改写后：
本页适合首次访问文档中心的业务负责人、产品经理、技术负责人和实施人员。
示例 3
改写前：
获取数据批量ID
改写后：
获取数据批量 ID
示例 4
改写前：
集中说明请求头、签名算法、时间戳与错误码，适合发起请求前逐项核对。
改写后：
集中说明通用技术约定，适合发起请求前快速逐项核对。