Wiki Style Guide zh CN

Wiki 编写规范

语言： English · 简体中文

本规范用于约束 LWC 公共 Wiki 的写作、本地化、审核与维护。整体风格遵循 GitHub Wiki 约定，并吸收成熟开源文档的共同实践：表达直接、页面围绕任务组织、导航稳定、命令可验证、不同语言同步维护。

规范语言与本地化

• 英文是规范技术正文，使用美式英语。
• 每一篇核心内容页都提供完整简体中文镜像，文件名为 <Page>-zh-CN.md。
• 中文页应当是一篇符合中文技术文档习惯的本地化内容，而不是逐句机器翻译。
• 两种语言必须表达相同的要求、边界、示例、警告和完成标准。
• 只要共同语义发生变化，就应在同一次提交中更新两个版本。

每篇页面开头都放置语言切换：

> **Language:** English · [简体中文](Page-zh-CN)

> **语言：** [English](Page) · 简体中文

文件命名与导航

• 使用稳定的英文 Title Case 页面名，并用连字符分隔，例如 Document-Knowledge-Graph.md。
• 中文镜像在 .md 前增加 -zh-CN。
• Home.md、Home-zh-CN.md、_Sidebar.md 和 _Footer.md 是 GitHub Wiki 特殊文件。
• 仓库中的文件保持扁平，概念层级由 _Sidebar.md 表达。
• 不发布死链接。只有中英文都通过审核后，才把页面加入侧栏。
• 内部链接优先使用不带 .md 的标准相对 Markdown 链接。

页面类型

概念页

适用于架构、术语或能力模型：

1. 用一句话给出定义；
2. 说明问题或动机；
3. 解释概念模型；
4. 明确边界与非目标；
5. 说明与其他能力的关系；
6. 给出下一篇相关页面。

任务页

适用于安装、配置、恢复或具体工作流：

1. 说明何时使用；
2. 写清前置条件和副作用；
3. 给出编号步骤；
4. 说明验证证据；
5. 提供失败与恢复指引；
6. 给出下一篇相关页面。

参考页

适用于命令、字段、限制或错误契约：

1. 写清准确作用域和版本边界；
2. 按用途组织紧凑表格；
3. 给出权威命令或结构；
4. 说明边界情况与限制；
5. 链接到以任务为中心的说明页。

不要把所有页面都写成穷举参考手册。读者应先理解用途，再接触命令细节。

英文写作要求

• 使用现在时、主动语态和直接表达。
• 说明任务步骤时直接使用“you”。
• 每段只承载一个主要观点。
• 优先使用明确动词，例如 “Run”“Inspect”“Require”“Preserve”“Verify”。
• 避免习语、营销套话、未解释的术语和容易过时的未来承诺。
• 标题使用 sentence-style capitalization。
• 命令、文件名、路径、字段和字面值使用代码格式。
• 先解释 LWC 专属概念，再使用缩写或实现细节。

中文写作要求

• 面向技术读者使用自然简体中文；英文语序生硬时，应主动调整句式。
• 优先使用“运行”“检查”“保留”“验证”等简洁动词；上下文清楚时省略不必要的主语。
• LWC、Agent、MCP、CodeGraph、Source、Page、Work、changeset、checkpoint 等产品或协议名在翻译会降低准确性时保留英文。
• 必要时在术语第一次出现时用中文解释，不要之后反复添加括号。
• 正文使用中文标点，代码内部使用 ASCII 标点。
• 避免“做一个决定”“执行一个检查”等直译表达，直接写“决定”“检查”。
• 不得擅自加入英文规范页没有的更强结论、额外警告或产品承诺。

命令与示例

• 使用 lwc <command> --help 或真实隔离运行核对命令。
• 命令代码块中不写 shell 提示符。
• 命令和对应输出分开呈现。
• 占位符使用尖括号，并解释不常见的占位符。
• 不得出现真实令牌、私人路径、Cookie、凭证或维护者本机特有环境假设。
• 直接调用全局安装的 lwc。不要教学日常导出 LWC_PROJECT_ROOT 或设置私人二进制变量。
• 安装软件、修改配置、初始化图、恢复 checkpoint 或写入当前项目之外的位置前，必须先说明副作用。

技术事实依据

按以下优先级确认事实：

1. 当前检出的实现与测试；
2. 当前 lwc --help 和隔离环境中的真实命令行为；
3. 仓库策略与持续维护的 README；
4. 集成第三方工具的当前官方文档；
5. 历史设计说明；行为可能变化时必须明确标注。

不要把一条过时 Wiki 声明复制到其他页面。文档与当前行为不一致时，应根据当前证据修正文档。

链接与内容去重

• 每个概念只设置一篇主页面，其他页面通过链接引用。
• 首页保持简洁，以导航为主。
• 操作流程放在任务页，精确字段列表放在参考页。
• Changelog、Release、安全策略和贡献文件直接链接仓库现有权威内容，不在 Wiki 中重复维护。
• 链接文字应说明目标，不使用含糊的“这里”。
• 发布前验证全部内部链接。

双语审核清单

每一对页面作为一个整体审核：

• 文件名和语言切换能够相互跳转；
• 标题层级与章节覆盖在语义上保持一致；
• 没有遗漏要求、警告、限制、示例或验证步骤；
• 中文表达自然，没有机械套用英文语序；
• 术语符合统一术语表；
• 必须一致的命令、标识符、JSON 字段和数值限制没有变化；
• 存在镜像页时，链接指向相同语言版本；
• 两种语言都没有加入无依据事实；
• 命令已经通过当前帮助或隔离真实运行核对；
• Markdown 与内部链接通过自动验证。

统一术语

英文	简体中文用法
proactive memory	主动记忆
persistent memory	持久记忆；强调跨会话时可写“长期记忆”
source-grounded	有来源依据；在 provenance 字段语境保留 source-grounded
Source	Source（来源）；命令实体名保留英文
Page	Page（页面）；命令实体名保留英文
provenance	来源证明；字段名保留 provenance
document knowledge graph	文档知识图；面向产品概念时可补充“记忆图网”
CodeGraph	CodeGraph 或代码图网
Word Graph	词图网
strong tag	强标签
Work	Work 任务
changeset	changeset；解释为原子变更草稿
checkpoint	checkpoint；解释为完整恢复点
read-only Viewer	只读 Viewer 或只读可视化界面

发布门禁

一对页面只有同时满足以下条件才算完成：

1. 两个文件都已完整编写；
2. 技术声明有当前证据支持；
3. 示例使用有效命令和安全占位符；
4. 双语审核清单中适用项全部通过；
5. 内部链接全部可解析；
6. 完成以上检查后才加入侧栏。

返回首页。