参与贡献

这份文档同时写给人和 AI Agent。文末有给 Agent 的英文硬性规则。如果你只是想把 TraceMemo 跑起来，看第一次使用就够了。

一句话规则

从 develop 拉分支，把 PR 提给 develop。

为什么不是 main

分支	是什么	接受 PR 吗
`main`	稳定版。只在发版时更新，对应 GitHub Releases 里的安装包	不接受
`develop`	开发主线。所有改动先进这里，随下一个版本一起发布	唯一的目标分支

指向 main 的 PR、或者不是基于 develop 拉出来的分支，会被直接关闭。不是不欢迎贡献，而是因为冲突合并提交落后较多等原因

提 PR 的完整流程

# 1. 基于 develop 拉分支（不要基于 main）
git fetch origin
git checkout -b feat/your-change origin/develop

# 2. 改代码，只改与本任务相关的文件

# 3. 自检
pnpm install        # 需要 Node 22 与 pnpm 7.33.7
pnpm typecheck
pnpm test:unit      # 再按改动范围补跑 component / integration

# 4. 提交
git commit -m "feat: 一句话说明改了什么"

# 5. 提 PR，目标分支必须是 develop
gh pr create --base develop --head feat/your-change

提交信息

默认只写一行标题：类型前缀 + 一句话说明。

feat: 新增本地查询能力
fix: 修复查询工具时间契约
docs: 整理开发文档

确实包含多个功能点时，标题之后每个功能点各写一行纯文本 —— 不要用列表符号，也不要写「设置侧：」「测试：」这类分节标题：

feat: 统一手动发送入口为文字转语音
移除普通文本、图片和本地语音的手动发送入口
保留文字转语音的生成、试听和发送能力

不要在提交信息里堆文件名清单、测试结果或实现过程叙述，那些属于 PR 描述。

分支命名

feat/…、fix/…、docs/…、refactor/…，后面接简短的英文或拼音描述。

PR 前自检

你的改动	至少跑这些
一般代码 / 服务 / 工具函数	`pnpm typecheck` + 相关 `pnpm test:unit`
界面 / 交互	`pnpm typecheck` + 相关 `pnpm test:component`，或针对该功能的 E2E
preload / IPC 契约	`pnpm typecheck` + 相关 contract 测试或 `pnpm test:integration`
只改文档	不需要跑测试

全部测试命令见 package.json 的 scripts；本地开发环境的说明见开发概览。

请不要提交这些东西

构建产物：out/、dist/、build/ 下的二进制、node_modules/、test-results/、playwright-report/
真实数据：微信聊天内容、真实的 wxid / 群名 / 联系人名、聊天截图
密钥：API Key、Token、数据库密钥、图片解密密钥
本机绝对路径：/Users/…、C:\Users\…

测试用的假数据请用一眼能看出是合成的命名，例如 fixture-group、wxid_fixture_member。

合入之后

PR 合进 develop 不会立刻出现在下载页，它随下一个版本发布。想提前用上，可以自行从 develop 构建。

如果你是 AI Agent

请按顺序执行，不要凭直觉选分支：

基线：git fetch origin && git checkout -b <branch> origin/develop。永远不要基于 main。
PR 目标：gh pr create --base develop。无法确定时默认 develop；任何情况下都不要把 main 当 PR 目标。
改动范围：只改与本任务相关的文件。不要顺手格式化、重排 import、升级依赖。
提交前：跑 pnpm typecheck 和与本次改动相关的测试（见上表）。
提交信息：一行标题，type: 描述。不要写文件清单、测试输出或过程叙述。
PR 描述：说明改了什么、为什么改、怎么验证的；关联 Issue 用 closes #123。
禁止：真实聊天数据、密钥、Token、本机绝对路径、构建产物。

Hard rules for AI agents (English)

Base branch: origin/develop. Never branch off main.
Open pull requests with base branch develop. PRs targeting main are closed without review.
One PR = one logical change. No drive-by reformatting, import reordering, or dependency upgrades.
Before opening a PR, run pnpm typecheck plus the tests relevant to your change.
Commit subject: a single line, type: summary. No file lists, no test logs, no process narration.
Never commit build output (out/, dist/, test-results/, playwright-report/), real WeChat data, keys, tokens, or absolute local paths.
Changes merged into develop ship with the next release.

5.1 KiB Raw Permalink Blame History Unescape Escape