TencentDB-Agent-Memory/CONTRIBUTING_CN.md

贡献指南

感谢你对 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 源码运行。

# 克隆仓库
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 行，表示你同意 开发者来源证书：

git commit -s -m "feat(store): add batch insert support"

没有有效 Signed-off-by 的提交将不会被合并。

安全问题

如果你发现安全漏洞，请通过 GitHub Issues 报告，我们会尽快处理。

许可证

提交贡献即表示你同意你的代码将在 MIT License 下许可。

---

再次感谢你的贡献！如有任何问题，欢迎在 Issues 中讨论。