mirror of
https://github.com/TencentCloud/TencentDB-Agent-Memory
synced 2026-07-10 12:34:27 +00:00
chrishuan
134 lines
4.3 KiB
Markdown
134 lines
4.3 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 **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 中讨论。
|