CONTRIBUTING.md

贡献指南

感谢你愿意为 workbuddy-config 出力。

这个仓库贡献什么

模板本身（SOUL.md / IDENTITY.md / USER.md / MEMORY.md）的改进。

⚠️ 最重要的一条

不要把你的真实配置提上来。

本仓是公开模板仓。以下内容一律不许出现在 PR 里：

• ❌ 真实的服务器 IP、域名、端口
• ❌ 真实的密钥路径、env 文件路径、凭据值
• ❌ 内部系统名（你的 Zabbix / InfluxDB / 内部 Git 地址）
• ❌ 真实姓名、岗位、城市
• ❌ 任何形如 {{...}} 但已填了真值的占位符

PR 里要举例说明，用 {{...}} 或明显的假值：

✅ 正确：- **服务器**: {{公网 IP}} / {{内网 IP}}
❌ 错误：- **服务器**: 203.0.113.10 / 10.0.0.5

提 PR 前自查：

python3 scripts/check_secrets.py      # 敏感信息扫描
python3 scripts/check_placeholders.py  # 占位符语法 / 命名 / 速查表登记
python3 scripts/check_links.py        # 内部链接与锚点

git diff --cached
grep -n '{{' *.md      # 确认占位符都还是占位符

三项检查脚本 CI 会跑同样的内容 —— 本地过了就不用等 CI 告诉你哪里错。

占位符命名规范

{{字段名}}              ← 无示例
{{字段名，如：示例值}}   ← 带示例

必须带字段名。 {{如：短狠直接}} 这种只有示例的写法有两个问题： 使用者看不出该填什么，也无法在 README 的「占位符速查」表里稳定引用 （示例值会变，登记就会失效）。

新增占位符时三件事一起做：

1. 在模板文件里使用它
2. 在 README 的「占位符速查」表里登记它（按字段名登记，不带示例）
3. 跑 python3 scripts/check_placeholders.py 确认通过

比对时一律按字段名（剥掉「，如：…」之后的示例部分）进行， 所以 {{数据源1}} 与 {{数据源1，如 Zabbix}} 视为同一个占位符。

快速判断表

你的改动	需要做什么
改进模板措辞	直接提，不用先开 Issue
新增一个占位符	在 README 的「占位符速查」表里也补一行
新增一节模板内容	说明它属于哪一层（SOUL / IDENTITY / USER / MEMORY）
修链接 / 排版	直接提
想加一个全新的配置文件	先开 Issue 讨论 —— 文件多了会破坏分层加载的清晰性

分层约定

改动必须放进正确的层：

SOUL.md       → 长期不变的人格与思考方式
IDENTITY.md   → 角色与行为准则
USER.md       → 关于「用户」的信息（谁、怎么工作、用什么工具）
MEMORY.md     → 操作层面的规则与决策（怎么做事、踩过什么坑）

放错层的典型后果：

• 放进 USER.md 的操作规则 → 换个人就失效
• 放进 SOUL.md 的项目细节 → 每换一个项目就要改「人格」

提交信息

用中文，格式：

<type>(<scope>): <一句话>

<为什么改>

<type>：feat / fix / docs / refactor / chore / ci <scope>：soul / identity / user / memory / readme / ci / docs

例：

docs(memory): 补充环境变量清单的填写指引

原清单只给了变量名，没说明「值放哪、怎么读」，第一次用的人容易
把真实值直接写进 MEMORY.md，违反 P0 规则第一条。

提交前自查

• git diff --cached 里没有任何真实凭据 / 内网地址 / 真实姓名
• 新增的占位符已登记进 README 的「占位符速查」表
• 改动放在了正确的层
• 没有把「我个人的偏好」写进通用模板 —— 模板应覆盖多数场景，个别场景的差异用 {{...}} 留给使用者填
• README 里的内部链接都有效