Secretive 开源项目贡献指南：安全审计、零依赖与本地化协作的完整规范-平芜编程栈

桌面应用
应用安全
密码学

【免费下载链接】secretive

Protect your SSH keys with your Mac's Secure Enclave

项目地址：https://gitcode.com/gh_mirrors/se/secretive

Secretive 是一款将 SSH 密钥保护在 Mac 芯片 Secure Enclave（安全隔区）中的 macOS 应用。本文围绕仓库根目录下的 CONTRIBUTING.md 展开，系统梳理该项目面向贡献者的完整规范：从安全审计底线的「零第三方依赖」「拒绝 AI 生成代码」两条硬性红线，到贡献流程、代码行为准则、本地化翻译路径，以及项目高度自主（Opinionated）的维护策略。读完本文，你将掌握向此类安全敏感型开源项目提交高质量、可被接受贡献的完整方法论，并理解其安全设计如何在 SECURITY.md 与源码结构中得到呼应。

一、贡献前的总原则：把安全与可审计性放在第一位

CONTRIBUTING.md 开篇就明确了 Secretive 的核心立场：安全（Security）对该项目来说是一切贡献的准入门槛。任何损害项目安全性或可审计性的贡献都会被拒绝（rejected）。这不是一句空话，而是由项目的根本定位决定的——Secretive 的设计初衷就是让用户在放心使用它管理 SSH 私钥的同时，有能力对源码进行完整审计。

这一点与 SECURITY.md 中阐述的安全原则一脉相承：

"Secretive Can't Read The Key Material"（难以泄露连 Secretive 自己都读不到的密钥）：应用只操作硬件背书（hardware-backed）的密钥，私钥数据即便应用自身也无法访问，这从根上降低了因代码缺陷导致密钥泄露的风险；
简洁与可审计（Simplicity and Auditability）：项目拒绝扩张到"可能有的每一个功能"，凡是会显著膨胀代码库、损害可审计性的功能，即使很酷也不会实现；
零依赖（Dependencies）：为了排除供应链攻击（supply chain attacks），应用本体不依赖任何第三方代码，仅构建过程存在有限例外。

从仓库结构可以印证这一点：根目录的 Package.swift 中dependencies: []为空数组，Sources/Packages/Package.swift 同样没有任何第三方依赖声明，所有功能均由SecretKit、SecureEnclaveSecretKit、SmartCardSecretKit、SSHProtocolKit、CertificateKit、SecretAgentKit、XPCWrappers等自研 Swift 包实现。贡献者提交任何引入新依赖的代码，都将直接触犯这条红线。

二、两条硬性红线：零第三方依赖与拒绝 AI/LLM 生成代码

2.1 零第三方依赖（Dependencies）

CONTRIBUTING.md 明确指出：Secretive 被设计为"易于被考虑使用它的人审计"（easily auditable），因此项目没有任何第三方依赖（no third party dependencies），任何引入新依赖的贡献都会被拒绝。

这条约束对贡献者的实际影响是：

提交新功能时，不能用现成的第三方库快速实现，必须自行实现所需逻辑；
审视代码时要额外关注是否"顺手"引入了框架或包管理依赖；
从源码结构看，所有能力都以独立 Swift Package 形式组织在 Sources/Packages/Sources 下，各包之间通过内部依赖（如SecretKit）互相引用，而非外部库。

这种"宁可自研也不引依赖"的取舍，与 SECURITY.md 中"排除供应链攻击、保证代码库可审计"的目标完全一致。

2.2 AI/LLM 生成代码政策

与依赖政策出于同样的安全与审计原因，CONTRIBUTING.md 规定：任何使用 AI 或 LLM 工具生成的代码都不会被接受（any code generated with AI or LLM tools will not be accepted）。

这意味着在向 Secretive 提交 Pull Request 之前，务必确认：

提交的代码确实由你本人编写，而非由 AI 工具生成；
如果借助过 AI 辅助工具（包括代码补全、自动生成器等），需要重写或人工审查到"非生成"状态（该文档原文表述为任何 AI/LLM 工具生成的代码均不接受）；
这一点与零依赖政策共同构成了该项目在"可审计性"上的双保险：人工编写的零依赖代码，使得安全审计者可以在有限代码量内完整追踪每一个逻辑分支。

三、行为准则与社区协作基础

CONTRIBUTING.md 要求所有贡献者必须遵守仓库中的 CODE_OF_CONDUCT.md。

该文件采用业界通用的Contributor Covenant 1.4 版，核心内容包括：

承诺（Our Pledge）：为所有参与者营造无骚扰、开放友好的社区环境，不论年龄、体型、族裔、性别认同、经验水平、教育背景、国籍、种族、宗教或性取向；
正向行为示例：使用包容性语言、尊重不同观点与经验、优雅接受建设性批评、以社区利益为重、对成员展现同理心；
不可接受行为：性化语言/图像与不受欢迎的性关注、挑衅侮辱与人身/政治攻击、公开或私下骚扰、未经许可发布他人隐私信息，以及其他在专业场合下不恰当的行为；
维护者职责：澄清可接受行为的标准，并对违规行为采取适当且公正的纠正措施（包括删除、编辑、拒绝不合规的评论/提交/wiki 编辑/Issue，甚至临时或永久封禁贡献者）；
适用范围：既适用于项目空间内，也适用于个人代表项目或社区时（如使用官方邮箱、官方社交媒体账号发帖等）的公共空间；
执行机制：违规行为可向项目团队邮箱举报，所有投诉都会被审查并调查，团队有义务对举报人身份保密。

四、本地化（Localization）：翻译贡献的入口与流程

如果你希望贡献翻译，CONTRIBUTING.md 指引你前往 LOCALIZING.md 查看入门指南。

LOCALIZING.md 详细说明了翻译协作的两种方式：

Crowdin 在线翻译（推荐）：Secretive 使用 Crowdin 平台进行本地化，打开 Crowdin 项目页面选择你的语言即可直接翻译，这是最便捷的方式；
手动提交 Pull Request：Crowdin 之外，维护者也接受直接以 PR 形式提交的翻译。

仓库中对应本地化基础设施的体现：

所有本地化字符串集中维护在 Sources/Packages/Resources/Localizable.xcstrings，这是一个 Swift String Catalog 文件，以en为源语言（"sourceLanguage" : "en"），包含大量语言的本地化条目；
根目录 Package.swift 与 Sources/Packages/Package.swift 均声明defaultLocalization: "en"，并通过localization资源项将Localizable.xcstrings打包进各个 target；
LOCALIZING.md 还列出了已有的多语言贡献者致谢名单，涵盖法语、中文、葡萄牙语（巴西）、德语、意大利语、芬兰语、韩语、日语、加泰罗尼亚语、波兰语、俄语等，并特别致谢 Crowdin 对开源项目的支持。

翻译贡献者在动手前如果对某些术语有歧义或困惑，可在仓库中开 Issue 提问，维护者乐于澄清。

五、署名（Credits）：让实质性贡献被记录

CONTRIBUTING.md 要求：如果你对应用做出了实质性贡献（material contribution），请把自己添加到 credits 文件末尾。

这一署名机制体现了项目对贡献的重视——不过需要注意，该文件（Sources/Secretive/Credits.rtf）位于主仓库（maxgoedjen/secretive）中，当前镜像仓库（gh_mirrors/se/secretive）的 Sources 目录下未包含该文件，因此以主仓库的实际路径为准。提交 PR 时遵循文档要求，在 credits 文件末尾追加自己的署名即可。

六、Collaborator 状态：为什么贡献者拿不到协作者权限

CONTRIBUTING.md 明确声明：维护者不会向任何贡献者授予仓库的 collaborator 访问权限。原因是 GitHub 的 collaborator 可以访问仓库内 Actions 使用的加密签名凭据（encrypted secrets），出于安全考虑一律不授予。

这对贡献者的实际影响是：

所有贡献都通过Fork + Pull Request流程提交；
不要期待"先拿到 collaborator 权限再直接推分支"的路径；
这再次印证了该项目在"安全优先"上的极致态度——连协作者权限这种常见的协作便利都被安全考量所否决。

七、Secretive 是一个高度自主（Opinionated）的项目

CONTRIBUTING.md 直言："Secretive is Opinionated"（Secretive 是有主见的）。维护者开源该项目的目的是让其他人能够使用和审计它——人们可以放心，因为源码是公开的，他们能亲眼看到它在做什么。维护者对项目应有的样貌有非常明确的想法，可能会婉拒与其愿景不符的贡献（respectfully decline）。

对贡献者的实战建议：

先提案后实现：如果你希望在实现之前先提议一个变更，可以在 GitHub 上打开一个带有proposed标签的 Issue（Open an Issue with the proposed tag），与维护者对齐方向后再动手；
接受被婉拒：即使贡献技术正确，若与项目愿景不符，也可能被礼貌拒绝——这是该项目的既定策略，并非针对个人；
小步验证：在实现大功能前，先通过 Issue 确认方向是否符合项目"简洁、可审计"的核心愿景。

八、从贡献规范到源码实践：在镜像仓库中验证与学习

虽然本文以 CONTRIBUTING.md 为主体，但贡献者在提交代码前，可以从当前仓库源码中提前熟悉项目结构与构建约定，确保贡献与项目风格一致：

构建配置：仓库使用 configure_team_id.sh 脚本生成Sources/Config/OpenSource.xcconfig，写入SECRETIVE_BASE_BUNDLE_ID_OSS与SECRETIVE_DEVELOPMENT_TEAM_OSS两个构建变量；Sources/Config/Config.xcconfig 则通过#include? "OpenSource.xcconfig"引入该文件，并为默认值（com.maxgoedjen.Secretive、Z72PRUAWF6）提供了 fallback。注意 README.md 的提醒：Keychain 只允许密钥的创建者（具体到 bundle ID）读取密钥，自行从源码构建时必须保持一致使用的 bundle ID，否则 Keychain 无法定位你的密钥；
包结构：功能全部以内置 Swift Package 形式组织，根目录 Package.swift（面向 Xcode 依赖场景的瘦身版）与 Sources/Packages/Package.swift（完整版）并存；贡献代码应遵循各包内部既有的命名与分层模式（如SecretKit定义核心Secret/SecretStore协议，SecureEnclaveSecretKit、SmartCardSecretKit提供具体实现，SSHProtocolKit负责协议编解码）；
测试约定：各包均配有同名测试 target（如SecretKitTests、SSHProtocolKitTests、SecretAgentKitTests、BriefTests），完整版包配置还启用了swiftLanguageMode(.v6)、treatAllWarnings(as: .error)与strictMemorySafety()——提交的代码需要能通过这套严格编译设置。

九、总结：面向安全敏感型开源项目的贡献清单

综合 CONTRIBUTING.md 全文，向 Secretive 提交贡献的完整检查清单如下：

检查项	要求	依据
安全性	不损害项目的安全性与可审计性，否则直接拒绝	CONTRIBUTING.md「Security」
依赖	零第三方依赖，禁止引入新依赖	CONTRIBUTING.md、Package.swift
代码来源	不接受 AI/LLM 生成的代码	CONTRIBUTING.md「AI/LLM Policy」
行为准则	遵守 CODE_OF_CONDUCT.md	CONTRIBUTING.md「Code of Conduct」
本地化	按 LOCALIZING.md 指引走 Crowdin 或 PR	CONTRIBUTING.md「Localization」
署名	实质性贡献者追加到 credits 文件末尾	CONTRIBUTING.md「Credits」
协作方式	无 collaborator 权限，走 Fork + PR	CONTRIBUTING.md「Collaborator Status」
愿景对齐	大改动先以`proposed`标签开 Issue 对齐方向	CONTRIBUTING.md「Secretive is Opinionated」