contribute

贡献

用户是一名临床医生，可能从未提交过拉取请求。替他们处理 git 工作：绝不要让他们输入 git 命令，也绝不要在他们看到的任何内容中使用“rebase”“upstream”或“HEAD”这些词。他们本地的编辑与真实患者和真实手稿有关，因此下面的安全步骤才是这项技能的意义所在，而不是 git 操作本身。

不容妥协的一条规则

**在作者看过所有即将发送的内容并表示同意之前，任何内容都不得离开这台机器。**在任何内容发送出去之前，每次都要明确说明：没有发送任何内容。

安全扫描只是辅助工具，不是保证：没有任何模式列表能识别出所有患者姓名或所有医院。要明确说出来，因为一旦用户以为扫描器无所不包，就会停止查看差异，而泄露恰恰会在这种时候发生。

如果扫描报告中出现阻断项（患者级数据、凭据），不要提供变通办法。删除这一行。贡献绝不需要患者数据来阐明观点。

阶段 0：他们改了什么？

python3 "${CLAUDE_SKILL_DIR}/scripts/find_local_changes.py" --target claude --json \
  --out qc/local_changes.json

此步骤会将已安装技能与已发布内容的哈希值进行比较。它只读取内容。

• 没有更改 → 直截了当地说明并停止；这是正常情况，不是失败。改为提供反馈渠道（阶段 4）。
• 有更改 → 按技能分组展示：
  • 新增文件（期刊配置文件、引文样式、报告示例）——通常是最有价值的贡献类型，因为这是项目中无人掌握的领域知识。要说明这一点。
  • 编辑过的文件——询问他们的专业领域有哪些问题；答案就是拉取请求的描述。绝不要猜测编辑原因。
  • 已删除的文件——通常不算贡献。纳入之前先询问。

如果某项更改只适用于一家医院（内部规则、带有科室抬头的模板），那就是本地调整，不是贡献：要说明这一点，不要纳入，并告诉他们保留它也没问题。

阶段 1：安全扫描（阻断）

python3 "${CLAUDE_SKILL_DIR}/scripts/check_contribution_safety.py" \
  --changes qc/local_changes.json --out qc/safety.json

此关卡采用失败即拒绝机制：只要发现任何内容，都会以非零状态退出；这与仓库中的其他检测器都不同——这是刻意的，因为一个打印出医院名称却仍返回成功的工具，迟早会让人相信它什么也没说。

判定结果：PHI_SUSPECTED、SECRET（阻断项——删除该行，不要争辩）、IDENTITY、INSTITUTION、APPROVAL_ID、MANUSCRIPT_ID、LOCAL_PATH。与他们一起逐项修复发现的问题，按照扫描输出中对应的 do 行处理（姓名 → 身份；医院 → 通用描述；IRB 或手稿 ID → 删除；主目录路径 → ~）。手稿 ID 也很重要，因为正在审稿的论文属于机密，其 ID 可以标识该论文。

非 UTF-8 文本的文件（图像、二进制文件）无法扫描或读取，因此会被列为 NOT SCANNED；在将其从贡献中移除之前，扫描都会失败。qc/safety.json 会记录每个已扫描文件的 sha256；除非即将发送的文件与记录的文件完全一致且未经更改，否则提交步骤会拒绝执行。每次编辑后都要重新运行扫描——旧报告，或使用 --text 对其他文件生成的报告，都不能清除任何问题。

然后打印每个即将发送文件的完整文本，并请他们逐一阅读。不是摘要——要显示全文。这一步才是真正保护他们的措施。

第 2 阶段：它是否符合项目自身的标准？

如果仓库在本地可用，请针对更改运行仓库的验证器；否则请人工检查：

• 期刊配置文件引用了期刊的公开作者指南：字数限制、摘要结构和 AI 政策必须引用自指南，否则就不写。不要凭记忆填写影响因子或数字。
• 引用样式必须是 Zotero 仓库中的官方 CSL。
• 技能编辑仍然要说明它的用途，而且更改应具有通用性——能够帮助其他医院的人。如果不符合，那就是本地定制；请仅在本地保留。

如果不符合要求，请用对方自己的话说明需要更改什么。不要提交注定会被拒绝的贡献——那比完全不贡献更糟。

第 3 阶段：提交

python3 "${CLAUDE_SKILL_DIR}/scripts/submit_contribution.py" \
  --changes qc/local_changes.json --safety qc/safety.json \
  --title "Add a journal profile for <journal>" --dry-run

务必先使用 --dry-run，并向对方展示计划。只有对方明确同意后，才再次运行并去掉 --dry-run。该脚本会采用可用的最高级别方式：

1. 已安装 GitHub 工具且已登录 → 脚本会创建分支、复制文件并发起拉取请求。对方无需输入任何内容。
2. 已安装但未登录 → 脚本会打印唯一需要运行的命令（gh auth login），然后停止。引导对方完成登录：GitHub.com → HTTPS → 通过浏览器登录。
3. 未安装 → 脚本会将更改写入文件，并在对方的浏览器中打开预先填写好的议题。不要把安装开发工具作为提供帮助的前提。

告诉对方接下来会发生什么：维护者会阅读内容，如果需要修改，他们可以直接在该页面用日常语言回复。他们不需要进行任何 git 操作。

第 4 阶段：非代码更改反馈

误报或失败步骤往往是临床工作者能提供的最有用信息：这是检测器在真实稿件而非合成测试样本上的表现证据。请收集：

• 检测器误触发：哪个检测器（其 qc/*.json 中的 detector 字段）、判定结果，以及能够复现问题的最短片段——如果不能展示真实内容，请改写其中的数字和姓名；重要的是句子的结构。
• 某个步骤失败：命令、错误信息、主机（Claude Code / Codex / Cursor / Copilot）、操作系统。
• 某些内容不适用于你的专科：工具包作了什么假设，以及实际情况是什么。

完成同样的安全检查后，将其作为议题发送——真实稿件中的复现示例正是 PHI 容易藏匿的地方：

python3 "${CLAUDE_SKILL_DIR}/scripts/check_contribution_safety.py" --text qc/feedback.md
gh issue create --repo Aperivue/medsci-skills --title "<one sentence>" --body-file qc/feedback.md --web

--web 会在浏览器中打开预先填写好的议题：对方阅读后点击 Submit。我们不会发送任何内容。

第 5 阶段：更新时保留他们的更改

告诉对方，安装程序在覆盖任何经过修改的技能前，已经会创建永久备份（位于 ~/.medsci-skills/backups/ 下），因此更新绝不会毁掉他们的工作——很多人以为更新会覆盖自己的更改，所以不愿更新。如果更改值得保留，将其贡献出来，就能让后续更新包含这些更改。

设置——不会有人收到催促

python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --status
python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --on    # remind me
python3 "${CLAUDE_SKILL_DIR}/scripts/contribution_prefs.py" --off   # never mention it (default)

• 提醒功能需要主动选择加入，默认关闭。安装程序只会在首次安装结束时提及一次该选项，之后不再提及。选择加入后，只有在对方确实更改了内容时才会显示提醒，且最多每月一次。
• 此设置仅控制提醒。无论何时运行，/contribute 都会正常工作。
• 此设置无法削弱安全措施：没有相关配置项，且 check_contribution_safety.py 不读取任何配置。选择加入绝不意味着“无需询问就发送”。

表示感谢

许多觉得这很有用的临床医生从未给仓库点过星标，因为没人告诉他们星标有什么用。工具包确实帮他们做成一件事后，告诉他们——该脚本会说明星标的作用，并让他们只需运行一条命令即可点星标：

python3 "${CLAUDE_SKILL_DIR}/scripts/star_repo.py" --how   # explain + show both ways
python3 "${CLAUDE_SKILL_DIR}/scripts/star_repo.py" --now   # do it from here (GitHub CLI)

• 绝不询问两次——展示过一次就会记录下来；不采取行动也是一种回答。
• 切勿粉饰此事：不要暗示没有他们的星标，工具包就会受到影响；也不要在工具包还没帮他们做成任何事之前就提出请求。提前索要感谢就是乞讨。

范围

只涉及已安装的技能——绝不触碰用户的手稿、数据或任何其他文件。贡献通过 fork 的拉取请求或议题提交；绝不推送到主仓库。

已知限制

• 患者标识符模式涵盖一组固定的标签和格式。它们无法识别的内容包括：韩语的注册号码或患者编号标签、不带连字符的居民登记号码、字母数字混合的患者 ID、“hospital number”，以及使用月份名称或以“born”引出的出生日期。扩大这些模式就意味着要在文本中进行关键词匹配，而这此前曾导致误报，因此没有这样做。逐行读取（阶段 1）可以覆盖这些情况。