开发把秘密分成片段、可离线恢复的软件

## 把恢复软件做成多年后仍能为困境中的人工作的东西 应将恢复软件视为一种基础设施：它可能多年无人触碰，直到有人在艰难时刻依赖它。缺陷也许会在没有维护人员能够处理时暴露，因此应优化持久正确性，而不是追求快速完成。 - 更改现有系统前，先理解它，包括其边界和约定为何存在。 - 遵循既定模式和标准，不要引入只对局部方便的例外。 - 为可能不熟悉技术、手足无措或正在经历悲伤的人设计说明、消息和界面。 - 验证实际成果，而不只是确认分配的编辑任务已经完成。 谨慎、同理心、可移植性和长期可运行性都是工程要求，不是可有可无的修饰。 ## 修改或移除功能前，找出所有相关部分 添加任何常量、辅助函数、类型、列表或配置来源前，先进行搜索。找到规范定义并从中派生，防止并行副本逐渐偏离。 - 更改或移除功能前，追踪代码、样式、翻译、类型、测试、注释、文档和构建配置中的每个关联元素。 - 彻底移除过时行为。不要将其注释掉，不要用样式隐藏，也不要把它留在条件分支之后。 - 更改后再次搜索相关标识符和概念，有意识地找出残留引用，而不是等它们意外出现。 - 检查最终差异中是否存在无关编辑、重复逻辑、无用代码或未完成的清理。 在处理完整的依赖关系图和引用图之前，不能认为一项功能已经移除。 ## 让命令行和浏览器共用一套加密核心逻辑 将加密操作和其他核心行为放在命令行路径与浏览器路径共同使用的共享实现中。薄适配器可以不同，但安全敏感的逻辑、常量、格式和验证规则应只有一个规范来源。 - 编辑前，明确由哪个运行时负责创建、恢复、打包、用户界面行为和部署。 - 如果这种边界能提高复用性或可移植性，则在轻量离线恢复路径中使用浏览器原生代码，并在创建路径中使用已编译的浏览器模块。 - 通过构建时功能标志生成离线版本和网络辅助版本，使离线成果不包含无用的网络代码。 - 通过小型且明确的桥接层公开已编译函数，不要在宿主语言中重复实现其行为。 - 在各软件包之间保持运行时和模块选择一致。 如果嵌入资源会造成循环依赖，应在应用程序初始化时加载生成的模块，并通过明确接口注入其字节，而不是强行形成依赖环。 ## 恢复过程完全离线，只使用成熟的加密方式 独立恢复成果必须能在本地直接打开，无需安装，并能在没有服务器或网络连接的情况下完成恢复。每个分发的组合包都必须保持自包含，并且不依赖原始仓库。 - 只允许范围有限且有明确文档的变体访问网络，例如短暂检查外部信标的定时解锁成果，或从同一服务器获取归档的自托管页面。 - 即使存在可选服务器版本，也要让每个接收者的独立成果保持完全离线。 - 确保少于规定阈值的密钥片段不会泄露任何秘密信息，包括通过新增元数据泄露信息。 - 使用成熟的加密、阈值秘密共享和时间锁构造；绝不能发明自定义加密原语。 - 将任何时间锁层置于主要加密层之内，以形成纵深防御。 - 每项加密变更都必须有测试、审查和明确理由。 不要向恢复路径添加遥测、分析、远程字体、内容分发依赖或其他隐藏的网络要求。 ## 保持组合包格式稳定，并嵌入恢复所需的一切 将组合包布局、加密载荷格式、密钥片段编码和恢复步骤视为协议接口。更改这些内容需要迁移规划、更新后的测试数据、兼容性测试和文档化理由。 - 让恢复体验能够跨平台、浏览器和语言工作。 - 嵌入脚本、样式、模板及其他必需资源，不要依赖外部服务或短暂存在的格式。 - 在每个接收者的组合包中包含清晰的文本说明和可打印说明、加密归档的元数据，以及个性化恢复页面。 - 如果加密清单不大于10 MB，将其嵌入个性化页面，使恢复过程不需要单独文件；同时遵守明确禁用嵌入的选项。 - 如果浏览器创建路径没有单独的覆盖设置，让它自动嵌入符合条件的清单。 - 不要让创建或恢复组合包的人在运行时依赖开发工具链。 密钥片段分发后，不要承诺仍可撤销，也不要宣称系统保证永远有效。应追求耐久性，但不能夸大确定性。 ## 先写会失败的测试，页面改动要加浏览器测试 先编写一个会失败的测试，观察失败，再让它通过。从未亲眼确认失败的测试，可能并没有覆盖预期行为。 - 每项会影响浏览器恢复页面或创建页面的变更，都要添加浏览器层级测试。 - 对核心逻辑、归档处理、配置和命令行为使用聚焦的单元测试和集成测试。 - 更改HTML结构、浏览器代码、会影响布局或可见性的样式，或已编译的浏览器绑定时，运行浏览器端到端测试。 - 对仅涉及翻译、文档、文案调整，或不可能影响浏览器行为的纯后端变更，不要要求运行缓慢的浏览器测试。 - 报告完成前亲自运行相关测试，不要把验证留给他人。 每次更改后，都要搜索相关术语，重新构建受影响的成果，运行恰当的测试并检查结果。 ## 使用仓库规定的构建与测试命令，而不是临时工具 理解从前端编译、浏览器模块到最终命令行二进制文件的完整构建管线。生成的脚本和已编译模块可能会嵌入后续阶段，因此命令顺序也是正确性的一部分。 - 使用仓库规定的构建、测试、lint、静态站点和开发服务器命令。 - 如果编译或嵌入前必须存在生成资源，应使用项目的测试包装器，不要直接调用语言测试运行程序。 - 只有在前置成果已经生成时，才运行文档中用于单项测试的较窄命令。 - 只把依赖网络的测试套件用于需要这些集成的变更。 - 如果依赖项或构建工具不可用，应进入仓库声明的可复现开发环境，不要改用临时选择的软件包运行程序。 从嵌入的源文件构建静态成果；除非发布设计明确包含私有恢复成果，否则不要将其部署到公共站点。 ## 为面对压力任务的人写平静清楚的文字 撰写面向使用者的文案时，应像是在为一位正面对重大而紧张任务的人逐字斟酌。善意应来自清晰、节奏和预先考虑，而不是刻意表演出来的安慰。 - 优先使用直接、有人情味的语言，而不是技术化措辞；说明下一步行动，不要让读者先解读实现细节。 - 尽可能直接与人对话；能够使用清晰的主动句时，不要使用被动式指令。 - 根据受众一致地选用术语。面向公众的文案优先使用“你信任的人”和“片段”；写给接收者的说明可以使用“朋友”等体现关系的词。 - 避免感叹号、填充词、夸大主张、机械措辞和刻意营造的热情。 - 使用前后带空格的长破折号，不要使用双连字符或前后没有空格的破折号。 - 状态消息应简洁而有人情味；成功应安静地表达，而不是完全不作声。 采用对比度克制、柔和温暖且非企业化的视觉语言。集中管理配色值，避免纯黑、亮红和企业蓝，并将任何刻意设置的视觉例外隔离并记录在文档中。 ## 更新文档，变更记录以使用者能感知的变化为主 行为发生变化时，在同一项变更中更新相关文档、贡献者指南和操作说明。架构说明必须解释运行时边界、生成资源、网络例外，以及复现结果所需的命令。 - 让配置和构建说明与实现保持同步。 - 稳定格式发生变化时，更新测试数据和迁移指南。 - 围绕软件使用者实际感受到的变化编写变更记录。 - 先说明面向使用者的结果，只提供足以理解该结果的实现背景。 - 除非内部重构或代码重组会改变可观察行为，否则不要将其写入变更记录。 编写新条目前，先阅读附近条目，使语气和详细程度保持一致。 ## 向外部服务提交时，让贡献者本人审阅并提交 执行任何会写入外部问题跟踪器或代码托管服务的操作前，先阅读项目的贡献政策。如果该政策要求由人承担责任，应在提交前停止，并说明贡献者要对差异中的每一行代码和文字负责。 - 向人展示拟议差异、提交消息或提交说明，供其审查。 - 要求贡献者用自己的语言编辑材料，如实完成证明，并亲自执行commit、push和提交。 - 提交前移除生成的页脚、共同作者行、填充内容和自动归属标记。 - 在说明责任要求后，除非贡献者仍明确坚持，否则不要执行外部写入。 - 如果对方仍然坚持，应保持文案简洁直接，不要添加自动归属标记，并再提醒一次人工审查要求。 本地编辑协助和只读检查不触发这些外部写入限制。发布自动化仍应在公开前运行构建、测试、lint、浏览器检查、跨平台打包和校验和，并生成有代表性的成果。