docs: add contributing guidelines and update README_CN

2026-07-10 12:34:27 +00:00 · 2026-05-11 14:28:14 +08:00
parent 30be052e14
commit d9f6291bec
3 changed files with 545 additions and 159 deletions
@@ -0,0 +1,133 @@
+# 贡献指南
+
+感谢你对 **TencentDB Agent Memory** 项目的关注！我们欢迎来自社区的各种贡献——无论是报告问题、改进文档还是提交代码。
+
+## 贡献方式
+
+- **报告 Bug**：在 GitHub Issues 中描述问题并提供复现步骤。
+- **请求功能**：在 Issues 中描述使用场景和你期望的解决方案。
+- **改进文档**：修复错别字、完善说明或补充示例。
+- **提交代码**：修复 Bug、实现新功能或优化性能。
+
+## 开发入门
+
+### 前置条件
+
+- Node.js >= 22.16.0
+- npm 或 pnpm
+- OpenClaw >= 2026.3.13
+
+### 从源码开发
+
+本项目无需编译。Node.js 22.16+ 原生支持 TypeScript 类型剥离，OpenClaw 直接加载 `.ts` 源码运行。
+
+```bash
+# 克隆仓库
+git clone https://github.com/Tencent/TencentDB-Agent-Memory.git
+cd TencentDB-Agent-Memory
+
+# 安装依赖
+npm install
+
+# 将当前目录作为本地插件注册到 OpenClaw
+openclaw plugins install --link .
+```
+
+`install --link` 会将当前目录作为本地插件注册到 OpenClaw，修改源码后重启 Gateway 即可生效。
+
+### 项目结构
+
+```
+├── index.ts                 # 插件入口
+├── openclaw.plugin.json     # OpenClaw 插件清单
+├── src/
+│   ├── config.ts            # 配置管理
+│   ├── conversation/        # L0 对话层 — 原始对话捕获
+│   ├── record/              # L1 记录层 — 结构化信息提取
+│   ├── scene/               # L2 场景层 — 场景归纳与聚合
+│   ├── persona/             # L3 画像层 — 用户画像构建
+│   ├── store/               # 存储层 — SQLite/向量数据库
+│   ├── hooks/               # OpenClaw 钩子集成
+│   ├── prompts/             # LLM 提示词模板
+│   ├── tools/               # 工具函数
+│   ├── utils/               # 通用工具
+│   └── report/              # 健康检测与报告
+├── hermes-plugin/           # Hermes 智能体插件适配
+├── scripts/                 # 辅助脚本（Gateway 控制等）
+├── CHANGELOG.md             # 变更日志
+└── README.md                # 项目说明
+```
+
+## 提交 Pull Request
+
+1. **Fork** 本仓库并基于 `main` 分支创建你的特性分支。
+2. **进行修改** — 保持每个提交专注且原子化。
+3. **测试** — 确保现有功能不受影响。
+4. **更新文档** — 如果更改涉及用户可见行为，请同步更新 README 或相关文档。
+5. **提交 PR** — 描述修改动机、变更内容，并关联相关 Issue。
+
+### 分支说明
+
+| 分支 | 用途 |
+|------|------|
+| `main` | 默认分支，PR 提交目标 |
+
+## 提交信息规范
+
+使用以下格式编写 commit message：
+
+```
+<类型>(<范围>): <简要描述>
+
+<详细说明（可选）>
+
+Closes #123
+Signed-off-by: Your Name <your-email@example.com>
+```
+
+### 类型
+
+与 PR 模板中的 Change Type 对应：
+
+| 类型 | 说明 | 对应 PR Change Type |
+|------|------|---------------------|
+| `fix` | Bug 修复 | Bug fix |
+| `feat` | 新功能 | New feature |
+| `docs` | 文档更新 | Documentation update |
+| `perf` | 代码优化 | Code optimization |
+| `refactor` | 代码重构（不影响功能） | Code optimization |
+| `test` | 测试相关 | — |
+| `chore` | 构建/工具/依赖变更 | — |
+
+### 范围示例
+
+`store`、`hooks`、`persona`、`scene`、`record`、`conversation`、`gateway`、`hermes`
+
+## 代码风格
+
+- **TypeScript**：使用项目已有的代码风格，保持一致性。
+- **命名**：使用有意义的变量名和函数名，优先使用英文。
+- **注释**：关键逻辑处添加注释，说明"为什么"而非"做了什么"。
+- **导入顺序**：Node.js 内置模块 → 第三方依赖 → 项目内部模块。
+
+## 开发者来源证书 (DCO)
+
+所有提交必须包含 `Signed-off-by` 行，表示你同意 [开发者来源证书](https://developercertificate.org/)：
+
+```bash
+git commit -s -m "feat(store): add batch insert support"
+```
+
+没有有效 `Signed-off-by` 的提交将不会被合并。
+
+## 安全问题
+
+如果你发现安全漏洞，请通过 [GitHub Issues](https://github.com/Tencent/TencentDB-Agent-Memory/issues) 报告，我们会尽快处理。
+
+## 许可证
+
+提交贡献即表示你同意你的代码将在 [MIT License](./LICENSE) 下许可。
+
+---
+
+再次感谢你的贡献！如有任何问题，欢迎在 Issues 中讨论。