用途
deid 用于解决一个具体问题:在一个共享制品(公开仓库、模板、测试夹具集、交付物)中,找出属于某一个人或某一个组织的数据,并使其不再留在其中,同时保证制品仍然可用。所谓“共享”,意味着这个制品本不该包含某个特定主体的私人或专有信息。
工具的运行边界由人工明确指定:一个是制品(文件夹或仓库),一个是数据主体(一个人或一个组织)。若人工未指明这两者,工具会询问;若涉及多个主体,则对每个主体各运行一次。工具不会自行挑选目标,也不会扩大范围。
主要能力
- 构建针(needles):读取人工指向的数据主体记录(身份与登录文件、个人资料、业务与收款设置、客户名单、账本、消息导出等),只读不写,生成一个 JSON 针文件。每行形如
{ "label": "...", "value": "...", "ci": true, "regex": true },其中ci(大小写不敏感)与regex(正则)为可选字段。标签必须唯一且描述值的种类(如 client-phone、owner-name-ko),绝不使用值本身,因为标签会被打印。每个值要覆盖其所有书写形式(姓名在各文字与顺序下的写法、电话含与不含分隔符及国家区号、邮箱任意大小写、ID 含与不含前缀);过短或常见的词转为带词边界的正则,因为脚本拒绝三字符以下的纯文本针。针文件须放在制品之外或置于被 git 忽略的本地名称下,后续步骤一律以标签指代针,绝不打印值。 - 扫描命中(scan):在技能目录运行
node scripts/deid.mjs scan <root> --needles <file> [--decisions <file>] [--no-git] [--json]。在 git 工作树内读取 git 未忽略的每个文件;--no-git则读取根目录下所有文件。每处命中输出文件、行、列和标签,绝不输出值。退出码 0 表示无命中,3 表示有命中,2 表示用法错误或针文件损坏。非 UTF-8 文本文件会被报告但不带行号,且永不被改写。 - 判定并记录决策:逐条在上下文中阅读命中(不回显携带值的整行),作出三选一决定:该值已由数据主体选择公开(如仓库自身地址、已发布的作者署名、制品引用的公开资料)则保留并写明理由;散文中的值替换为其扮演的角色(操作者、客户、公司);代码、测试或夹具中的值替换为同形状占位符,且仍能执行同一分支(如邮箱用保留示例域名、同长度明显合成号码、虚构姓名),并检查所有读取该值的断言。决策文件为 JSON 数组,行形如
{ "needle": "<label>", "replace": "..." }或{ "needle": "<label>", "keep": "<reason>" },可带可选"paths": [globs]按仓库相对路径匹配;首个针与路径同时匹配的行决定该命中,故范围窄的行应置于通用行之前。脚本拒绝本身携带针的替换值。决策文件与针文件放在一起。 - 先说明严重程度再应用(apply):变更前先告知人工发现的数据种类(身份、联系方式、凭据、客户记录、业务数字、平台 ID)与数量,仅以标签和计数呈现,因为补救方式取决于此。然后运行
node scripts/deid.mjs apply <root> --needles <file> --decisions <file> [--json]。它只改写文本实际变化的文件,重叠针取最长者,无决策匹配的命中保持原样;退出码 3 表示仍有未决命中。重复判定与应用步骤,直到带--decisions的 scan 退出码为 0,再运行制品自身的测试与检查;失败应作为更合适的占位符写回决策文件,而非手工修改。 - 只读扫描历史(history):在 git 仓库运行
node scripts/deid.mjs history <root> --needles <file> [--decisions <file>] [--rev <rev>]... [--json],除非用--rev指定,否则读取所有引用。它按针标签列出每个在补丁中把针加入文件的提交,以及每个提交消息携带针的提交,仅以提交 ID 呈现,不作任何更改。加入针的提交即其进入点;其后每个后代都携带它,直到后续提交移除,因此内容重写从该提交开始。退出码 0 表示历史干净,3 表示不干净。 - 报告并移交历史:报告工作区结果(改写的文件、保留的值及理由、未决命中)与历史结果。对提交消息携带针的情况,告知人工对所列提交运行
/re0-git。对过往文件内容,仅指出只有数据主体能作出的决定,工具本身不执行:用内容重写工具重写所列提交及其后代、强制推送每个引用,并接受克隆、分叉与托管方在清除前可能继续提供旧提交;重新创建仓库是替代方案。
使用方式
整体流程为:固定制品与主体 → 构建针文件 → 扫描命中 → 逐条判定写入决策文件 → 说明严重程度并应用 → 历史只读扫描 → 报告并移交。全部操作通过命令行脚本完成,命令与参数如上所述。
适用场景
- 公开仓库或模板中混入了某个人或组织的姓名、联系方式、ID 等,需要在保持项目可用的前提下清除。
- 测试夹具、示例数据或交付物中带有真实客户或企业信息,需替换为同形状合成值。
- 需要评估某主体数据在 git 历史中的进入点与传播范围,并据此决定是否重写历史。
限制
- 每轮只处理一个人工指定主体与一个指定制品,范围不扩大。
- 针值、标签、保留理由及拼出该值的路径都不得进入输出、报告、提交或制品;针与决策文件必须置于制品外或被 git 忽略的本地名称下,脚本不会把它们当作树的一部分读取。
- 数据主体的记录只读,绝不写入。
- 工作区只通过 apply 与决策文件变更;手工修改须写回决策文件以便下次重放。
- 替换值不得借用其他真实个人或公司的数据,只能是角色名词或表面即合成的值。
- 保留必须附理由;“已公开”指由数据主体选择公开,而非仅仅可被搜到。
- 历史只读;重写过往内容、强制推送、请求托管方清除均由数据主体决定,工具只报告不执行;提交消息交由
/re0-git处理(它只重写消息、不改内容)。 - 非 UTF-8 文本文件只报告、不重写,交由人工处理。
- 无命中的一轮不改变任何内容并如实说明。
验证要求
完成前需确认:带决策文件的 scan 在工作区退出码为 0,且 apply 后制品自身测试与检查通过;运行打印、写入制品或报告的内容中不出现任何针值;决策文件中每个保留都写明理由;历史结果连同两项移交(消息交 /re0-git、内容重写决定交数据主体且不执行)一并报告;脚本变更时,其测试需通过指向技能文件夹的联结或符号链接调用 CLI 并通过。