参与贡献
本项目采用 AI Native 的开发流程：先规格、再实现、再验证、再文档。以下规则对人和 Agent 同样适用。
开发流程
① Plan → 明确问题、边界、验收标准
② Execute → 实现与自测
③ Review → lint + format + build + test
④ Commit → scripts/committer
⑤ Docs → 更新文档与 API 契约
⑥ Iterate → 复盘与下一步分支与提交
- 主分支：
main - 不要擅自切换分支、创建 worktree 或使用
git stash（可能有其他 Agent 在工作） - 提交必须使用安全脚本：
bash
scripts/committer "feat(task): add retry on node failure" \
libs/modules/src/task/services/task-execution.service.ts禁止：
git add .git commit -a- 提交
.env、证书、node_modules/、dist/
提交信息格式：
<type>(<scope>): <subject>| type | 用途 |
|---|---|
feat | 新功能 |
fix | 修复 |
refactor | 重构 |
docs | 文档 |
test | 测试 |
chore | 构建/工具 |
模块边界
| 路径 | 谁可以依赖 |
|---|---|
libs/common | 所有模块；不得反向依赖 libs/modules 或 apps |
libs/modules | 通过模块或 barrel 互相导入 |
libs/shared | 所有模块 |
apps/hushwork | 可依赖上述库；不得被库反向依赖 |
规则：
- 使用
@app/modules/<module>路径别名 - 不直接引用其他模块的
services/或entities/ - 禁止循环依赖；共享逻辑提到
libs/common - 输入边界使用
class-validator
测试要求
| 变更 | 必须 |
|---|---|
| 新增业务逻辑 | 单测 |
| 修改状态机 | 单测 + 真库 e2e |
| 修改事务边界 | e2e 反证（回滚） |
| 修改 API | Swagger 装饰器 + e2e |
| 修改前端 | 构建通过 |
常用命令：
bash
npm test
npm run test:e2e:hushwork
npm run build
npm run frontend:build
npx jest libs/modules/src/state单测基线存在部分历史失败，新增代码不应增加失败数。
文档要求
| 变更 | 动作 |
|---|---|
| 新增/修改 API | npm run docs:api |
| 新增模块 | 模块 README.md + 本站在模块参考中新增页面 |
| 新功能 | /getting-started 或对应指南补充 |
| 破坏性变更 | 迁移说明 + 更新日志 |
| 任意功能变更 | site/changelog/index.md 追加 |
文档站发布：
bash
npm run docs:build
npm run docs:deploy只 build 不会更新线上。
代码风格
bash
npm run lint
npm run format约定：
- TypeScript strict 倾向
- 避免
any，边界类型必须显式 - 金额使用整数最小单位
- 时间使用 UTC 存储
- 日志不打印密钥与个人敏感信息
安全
- 不把密钥写入代码或文档
- 新增对外端点必须校验身份与归属
- 外部输入必须经过 DTO / Schema 校验
- 涉及资金的变更需要 review
提交前检查清单
- [ ] 只提交自己修改的文件
- [ ]
npm run build通过 - [ ] 相关测试通过
- [ ]
git diff无调试代码与临时文件 - [ ] 文档已同步
- [ ] 提交信息符合规范