Contributing zh

🌐 English · 中文 · 🏠 首页

参与贡献

你在考虑给 humanities-writing-companion 出一份力——真心欢迎。这一页是贡献指南里"带你走一遍"的友好版本。最权威、最简洁的原文，请看仓库根目录的 CONTRIBUTING.md。两者若有出入，以根目录那份为准。

---

先读这一段：贡献首先是"合不合得来"，其次才是代码

大多数"如何贡献"的文档上来就讲 fork、提 PR。我们换个起点，因为这个项目有点不一样。

这份 skill 是有思想立场的——而且是堂堂正正地有。它押下了三个赌注，里面每一个模块都被这三件事塑形：

• 思想对话，而非格式润色。 比起逗号摆得齐不齐，它更在乎你的论证站不站得住。它有意先处理最高一层尚未解决的问题（论证 → 概念 → 结构 → 表达 → 格式），这意味着它早期给的反馈往往不会让你的文字"看起来"更漂亮——而是逼你看见那个你宁愿不看的问题。
• 工程化严谨，而非经验启发。 版本管理、修订日志、验证清单、可续接的会话——这套 skill 从软件工程里借来了真实的认知架构，好让一个长达数月、不断被打断的写作项目能活下来。
• 作者的声音，而非标准学术语体。 "我手写我心"。这套 skill 的活儿从来不是把你的文字洗成顺滑、匿名的学术腔，而是让你留在文本里——包括那些让文字之所以是你的不对称判断、犹豫，和奇怪的跳跃。

如果你想看清这三个立场背后的完整论证，docs/design-philosophy.md 把话都说透了——那正是你的贡献需要"合得来"的设计立场。

所以说句实在话：给这个项目做贡献，"合不合得来"和"代码好不好"一样重要。 一个技术上干净、却悄悄把 skill 变成通用润色器的 PR，在这里不是好贡献——它是一个 fork。这完全没问题！但事先认清这个区别，能帮所有人省下时间，也省下失望。

还有一条值得先知道的边界：这份 skill 不做实证研究流水线——文献检索、数据收集、方法论合规这些，都不归它管。那是 academic-research-skills 的领地。本 skill 专注人文学科的写作声音、论证肌理、文风发展。在提议之前，不妨先掂量一下：你想做的事，落在这个范围里吗？

---

为什么值得贡献

这套 skill 是从一个人真实的人文学科论文项目里长出来的。这是它的长处——它对"人文作者到底在做什么"有相当准确的把握，而不是凭空猜测。但这也是它的局限：它最初的形态带着那一个项目的学科偏向，在你的领域里到底表现如何，不等你这个领域的人真正用一遍，它自己也不知道。

这正是你登场的地方。在这个项目看来，普遍性应当从众多特殊性的交汇处生长出来——而不是从一个被抽空的、架空的"通用框架"里掉下来。每一个来测试它的学科、每一句被人揪出来的未审视套话、每一个被补上缺失语言的文件，都让这套 skill 离"真正服务整个人文学科"更近一步。在这里贡献，不是在别人的工具上做杂活；是把你的那一份特殊性，添进这个交汇处。

---

怎么贡献最有价值（按优先级排）

下面这些，大致按"最需要"往下排，是真正能推动 skill 前进的地方。

🥇 学科测试——你能做的最有价值的一件事

这一条不需要你写任何代码。最有用的贡献，其实就是：

1. 在你自己的学科或论文项目里，真刀真枪地用一遍。
2. 反馈回来：哪些模块好用，哪些在你的领域里水土不服。
3. 在你撞墙的地方，提议学科特定的扩展——比如中世纪研究的拉丁文核查、艺术保护的物质文化分析、民族音乐学的田野记录处理。

一句诚实的"这个在我学科里不合用"是金子。正是这些反馈，让设计能在更多特殊性里长大，而不是围着它的起源项目僵化。docs/cross-domain-testing.zh.md 里有按学科分组的测试场景，目前已经梳理到哪一步，可以在 Discipline Guides 这一页看到。

🥈 扩充 AI 痕迹排查清单

references/ai-trace-checklist.zh.md 是这套 skill 对付未审视文字的"防御纵深"。如果你在自己的写作里发现了新的未审视表达模式——不只是 AI 套话，还有学科特定的八股、读多了理论沉淀下来的惯性——欢迎提 PR 补充。这类改动小、价值高，特别适合作为第一次贡献。

🥉 双语补全剩下的文件

SKILL.md 和 README 已经有了两种语言（SKILL.md / SKILL.zh.md、README.md / README.zh.md）。但 references/ 下的支持文件（ai-trace-checklist、project-management、target-reader-profile-template）和 scripts/ 里的注释，目前还基本只有中文。把它们翻成英文，是高价值的贡献。

几条翻译原则，因为这件事比看上去更微妙：

• ai-trace-checklist.md 里的中文套话清单（如"值得注意的是"）需要补上对等的英文套话（如 "It is worth noting"、"It should be noted"）——不是直译，而是英文学术写作里真正会用的那种填充语。
• 引用速查里凡是涉及 GB/T 7714 之外的规范，按英文学术惯例来处理，而不是把中文指引硬搬过去。

🏅 新增工作模式

skill 目前有 11 个工作模式（A–K）。如果你发现了一个它们全都没覆盖的高频写作场景，可以提议新模式。但门槛是实打实的——一个新模式必须同时满足下面三条：

• 它机械区分于每一个现有模式（不是某个模式的换名或再说明）。
• 它有独立的输入要求和输出格式。
• 它附带至少一个具体使用场景 + 预期效果。

如果这三条你说不全，那它八成是某个现有模式的扩展，而不是一个新模式。（而且因为各模式彼此联动，新模式一律先从开 issue 起步——见下面的提交流程。）

更深的引用格式支持

skill 的引用配置假设作者会在 onboarding 时选定一种格式（APA / Chicago / MLA / GB/T 7714 / 期刊自定义）。如果你想让某个标准有更深的内置支持——比如自动生成符合 GB/T 7714 顺序编码制的参考文献列表——这是受欢迎的提议。

脚本工具

scripts/ 目录里放着几个小工具，也还有添新的空间。合得来的点子，比如：

• 段落连贯性检测（基于句首 / 句尾词汇的重复）。
• 概念漂移检测（同一术语在不同章节里的语境频率如何变化）。
• 引用密度分析（按章节统计引用密度，标出异常段落）。

唯一一条硬规矩：新脚本必须零依赖或少依赖——zsh、Python 3 标准库，最多一两个常用包——并遵守 scripts/README.md 里的设计原则。这套 skill 是要能在任何地方跑起来的，沉重的依赖树直接出局。

好奇这一切往哪儿走？Roadmap 页面记录着已规划的和仍开放的方向。

---

哪些贡献不太需要（以及为什么）

这不是一份"这些点子很烂"的清单。它们都是相当合理的诉求——只是和 skill 的设计立场对着拉，所以提了不一定会被合并。与其等你写完 PR 才知道，不如现在就讲清楚。

• ❌ 把 skill 变得"通用"。 加一个"通用润色模式"，或者把它扩展到实证社科或 STEM。skill 故意把范围圈在人文学科、思想优先、文风保持——它不试图取悦所有写作场景。要做实证研究流水线，academic-research-skills 才是对的去处。
• ❌ 把现有模块替换成运行时 LLM 调用。 工作模式是有意用纯文本 prompt 描述的。正是这一点，让 skill 能在任何 Claude 接入点跑起来——Agent SDK、Claude Code、Claude.ai——不需要额外的管道。把运行时模型调用焊进去，就会毁掉这种可移植性。
• ❌ "AI 智能润色"功能。 整套 skill 就是在反对"AI 自动帮你润稿"这套叙事。这里的润色，是作者驱动的对话过程，不是一键清理。
• ❌ 付费 / 订阅集成。 skill 是开源的公共物品，而且会一直是。

如果你的点子落进了这一节，但你真心觉得它应该被接纳，别闷头提交——去开个讨论，在设计哲学这个层面上把道理讲出来。这样的争论是受欢迎的；一个默默假设立场不存在的 PR 则不然。

---

提交流程

小改动 → 直接提 PR

typo、文档修订、ai-trace-checklist 的小补充——直接开个 pull request，附一句改动理由就行。不需要什么仪式。

大改动 → 先开 issue

新模式，或者大幅修订 SKILL.md？请在动手写 PR 之前，先开一个 issue 讨论。

为什么这件事要紧、而不只是走流程：SKILL.md 和 SKILL.zh.md 各约 900 行，各节之间是真的彼此咬合。一个大 PR 冷不丁砸进来，很容易在无意之间破坏现有设计。（举个具体例子：模式 G「盲读核对」故意不去读 _writing-config/ 文件。这是设计——正是这一点让盲读之所以"盲"——不是什么有待"修复"的疏忽。）先开 issue，能让我们在你为一个补丁砸下几个小时之前，就把这类联动问题看出来。

开 issue 时，把下面这些讲清楚会帮上大忙：

1. 你想解决的具体写作场景问题是什么。
2. 现有哪个模块或规则不够用（能引用 SKILL.md 的行号就更好）。
3. 你的改动会牵动 SKILL.md 的哪些其他部分——联动检查。
4. 你打算怎么验证这个改动。你怎么知道它改对了？

双语联动规则

这一条最容易绊倒人，所以单列一个小标题。对 SKILL.md 的任何实质性改动，都必须同时改 SKILL.zh.md，保持两种语言一致。README.md / README.zh.md 同理。只动了一种语言版本的 PR，会被要求先补全另一种才能合并。两种语言是一对配套的孪生，不是"原文加译文"——请让它们同步前进。

（纯翻译工作当然是例外——那正是上面 🥉 双语补全那一档的意义所在。）

Commit message 建议

不强制，但你这么做能让评审顺畅得多：

• 写明改了哪一节 / 哪个模块。
• 用一句话说明为什么。
• 如果你在 SKILL.md 里动了几处需要联动的地方，把它们列出来。

一个好例子：

ai-trace-checklist: 新增"过度概念化"作为第七类未审视模式

在多次实测中发现，AI 倾向于把日常表达升格为术语
（"这表明" → "这一现象在认识论层面表明"）。这一模式
不属于现有六类中任何一类，但出现频率很高。

---

行为准则（简版）

三条简单的原则：

• 学术性的批判欢迎，人格性的攻击不欢迎。 跟观点较劲，别跟人较劲。
• 每一种学科传统都值得尊重。 "我学科才是真学问"的姿态，这里不欢迎。
• skill 服务于作者的思考。 任何会削弱作者认知主体性的提议——比如把作者变成 AI 输出的盲签字员——都不会被接受。这是底线。

---

许可协议

提交贡献，即表示你同意按 CC BY-NC 4.0 协议发布你的贡献。

注意： 本项目自 2026-05-19 起，从 MIT 改为 CC BY-NC 4.0。新贡献归入 CC BY-NC 4.0——这意味着你的贡献也只能用于非商业用途。如果这让你有所顾虑，请在提交 PR 之前先开个 issue 聊一聊。

---

接下来去哪儿

• 📜 权威原文：根目录 CONTRIBUTING.md
• 🧭 你的贡献需要合得来的设计立场：docs/design-philosophy.md
• 🗂️ Discipline Guides——看看各个学科走到了哪一步
• 🛣️ Roadmap——已规划的和仍开放的方向