在文档中使用通用占位数据

更新或编写工具文档时，切勿包含来自提示（prompt）、本地配置、脚本、任务文件或其他任何实现相关来源的真实数据。文档中必须仅使用通用、广为人知的占位数据，且该数据不得暴露任何敏感信息。

适用此规范的场景

• 编写或更新 README.md 文件
• 在 docs/ 目录下创建文档
• 向 Markdown 文件中添加代码示例
• 编写 CHANGELOG.md 条目
• 在已提交的源代码文件中添加代码注释

为何此规范至关重要

工具的源代码和本地配置中常包含真实姓名、真实邮箱地址、真实组织信息及真实域名等。这些值对工具正常运行是必需的，但它们绝不可出现在面向公众的文档中。将真实数据泄露至文档可能暴露：

• 内部业务名称与联系人
• 邮箱地址与域名
• 客户或终端用户标识符
• 账号名称与凭证
• 揭示私有运营细节的组织特有术语

核心规则

凡源自提示（prompt）、本地文件、脚本、配置或任务的数据——均不得进入文档。

文档中的示例仅可使用广为人知的虚构数据或明显为占位用途的数据。

何为“真实数据”

以下来源产生的任意值均视为真实数据：

• 本地配置文件（例如 config.json、.env、账号模块）
• 脚本与任务文件（例如批处理脚本、Shell 脚本、任务运行器）
• 提示上下文（例如用户在请求 agent 构建或更新工具时提供的数据）
• 映射或过滤文件（例如 JSON 映射、数据抽取规则）
• Git 忽略文件（例如被排除在版本控制之外、含环境特有值的文件）

文档中允许使用的占位数据

所有文档与示例中均应使用以下通用、惯用的占位数据：

占位数据需契合上下文

只有当占位数据在所处上下文中具备合理性时，才被视为正确。一个违反操作系统约定、工具惯例或所述工作流的通用名称，其误导性不亚于真实值。请选用符合目标平台、工具及其数据角色的替代项。

路径应匹配对应平台

当上下文文本或代码具有操作系统特异性（如 .bat 文件、在 Windows 上运行的 .jsx、bash 片段）时，路径占位符必须与之匹配。当文档本身平台中立时，则应同时展示两种形式，或使用明确抽象的标记（如 、）。

占位位置需匹配工作流语义

占位数据所在位置，须与其所代表的数据类型逻辑一致：

由用户触发的脚本若写入调试日志，不应将其存放在 C:\ProgramData…（机器级共享）；而维护共享状态的服务，也不应将其置于 ~/.config/…（用户级）。请选用真实实现中该角色所对应的实际位置。

标识符需匹配所属领域

当示例中使用标识符（账号名、项目名、数据集键等）时，应选择与上下文领域词汇一致的占位符。

• CRM 示例：acme-corp、northwind-traders
• 地理数据集示例：springfield、region-west
• 开发者工具示例：demo-app、sample-project

切勿混用领域（例如在地理数据示例中使用 acme-corp，即使该名称在通用列表中获批，仍属错误）。

自查清单

在提交占位符前，请自问：

• 路径语法是否与同一代码块中所示操作系统一致？
• 位置是否匹配该数据的角色（用户级 vs. 机器级、运行时 vs. 配置、本地 vs. 共享）？
• 标识符是否匹配周围示例的领域？

若任一问题答案为“否”，请更换为更贴合的占位符。

如何应用此规则

新增功能时

若新增功能依赖真实账号数据（例如以真实客户命名的脚本），则应在文档中使用虚构账号名进行说明。

真实实现文件：为特定企业配置的账号模块

文档示例：

// accounts/acme.mjs — 示例账号配置
export default {
  name: 'Acme Corp',
  email: 'reports@example.com',
  folder: 'INBOX',
};

更新配置文档时

若配置文件引用了真实域名、真实路径或真实凭证，则在纳入文档前，须将所有真实值替换为占位符。

文档示例：

{
  "host": "imap.example.com",
  "user": "admin@example.com",
  "folder": "INBOX/Reports",
  "outputDir": "./downloads"
}

编写脚本示例时

若脚本为特定组织自动化某项任务，则文档示例必须使用通用组织名与通用参数。

文档示例：

@echo off
REM 示例：为 Acme Corp 运行提取任务
node extractEmail.mjs --account acme --task download

代码与文档的边界

唯一例外

真实数据中的某个单词，仅当它作为普通英文词汇以常规语义使用，且未出现在示例上下文中时，方可保留在文档中。例如，“development”一词在句子 “This tool is under active development” 中是可接受的，即便它也出现在某个真实组织名称中。

总结

文档是公开的，实现数据是私有的——二者必须严格分离。每一份文档中的每一个示例都应通过一项简单检验：陌生人阅读该内容后，能否完全无法获知本工具背后的真实用户、客户或组织信息？ 若答案为“否”，请立即以通用占位符替换其中所有数据。