Hindsight 开发者指南：从环境搭建到第一个 PR 的完整路径

Hindsight 开发者指南：从环境搭建到第一个 PR 的完整路径

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

Hindsight 是一个让 AI 代理拥有记忆的开源系统，核心是 retain（写入）、recall（检索）、reflect（反思）三条流水线。读完这篇贡献指南，你能从零搭好本地开发环境，跑通 API 服务，并走通从一个小改动到提交第一个 PR 的全流程。

贡献地图一览

动手之前先选路径。下表把最常见的四类贡献映射到具体入口，对照自己的基础选一条即可：

选择你的切入点

文档。hindsight-docs/docs/ 下有 developer、sdks 等目录，developer/development.md 是最常被修订的一页。修错别字、补命令示例、翻译缺失章节都算数，改完可用 scripts/dev/start-docs.sh 在本地预览效果。

测试。hindsight-api/tests/ 里两百多个测试文件按模块命名，比如 test_retain.py、test_recall_config.py。共享 fixture 集中在 conftest.py，先跑通一个现有文件，再照着模式补新用例，不需要先读懂整条流水线。

功能开发。核心逻辑在 hindsight-api-slim/hindsight_api/：engine/ 是记忆处理引擎，api/ 是路由层。下图是记忆库的星图视图，可以看到节点与因果、时间链接构成的图结构，这也是引擎主要操作的数据形态。

注意 hindsight-clients/ 下的 Python、TypeScript、Rust 客户端是从 OpenAPI 规范生成的，不要手改生成代码。

维护与优化。从 scripts/ 目录切入：dev/ 放各类启动脚本，benchmarks/ 放性能基准脚本，hooks/ 放质量检查脚本。下图展示了记忆从原始写入到整合成事实的观察结果的流程，理解它有助于优化整合相关的性能问题。

五步完成第一个 PR

1. 克隆仓库并进入目录：

git clone https://gitcode.com/GitHub_Trending/hindsight2/hindsight

2. 一键初始化环境：

./scripts/dev/setup.sh

该脚本可重复执行，会按需装好 uv、Node、cargo 工具链，从 .env.example 生成 .env，安装全部依赖并预下载本地模型。随后在 .env 里填入你的 LLM API 密钥。

3. 启动本地 API 验证环境：

./scripts/dev/start-api.sh

需要界面时用同目录的 start-control-plane.sh 和 start-docs.sh 分别拉起控制面板与文档站。

4. 跑一遍测试确认没有破坏：

uv run pytest tests/ -x

在 hindsight-api/ 目录下执行，-x 让第一个失败即停，方便定位。

5. 做一次最小改动（改一处文档或补一个测试），执行./scripts/hooks/lint.sh确认检查通过，然后从 main 切出功能分支，提交 PR。

代码质量的三条底线

• 格式与静态检查：Python 用 ruff check --fix 和 ruff format，TypeScript 用 eslint --fix 和 prettier，钩子在提交时把两套检查并行跑完。
• 类型检查：Python 侧额外跑 ty check，所以新增代码必须带类型提示，这是评审时会被重点看的。
• 自动拦截：执行一次./scripts/setup-hooks.sh，git 会指向 .githooks/ 下的脚本，之后每次 commit 前自动跑全部检查，无需记命令。
• 手动替代：忘了装钩子也没关系，./scripts/hooks/lint.sh就是 pre-commit 跑的那套完整检查，提交前手动跑一遍即可。
• 测试门槛：新功能必须带测试用例；涉及流水线的改动，先在 hindsight-api/tests/ 对应文件里跑通，再全量过一遍。

提交之后会发生什么

PR 从 main 切出的功能分支提交，描述里写清改动内容、对应的问题编号和测试结果。维护者评审时主要看两点：测试是否覆盖新逻辑，代码是否遵循现有模式（类型提示、既有代码结构、函数职责单一）。对评审意见逐条回复处理方式，改动以新 commit 推上去并同步 main；CI 的 lint 与测试全绿后通常即可合并。

新手常踩的坑

改了功能，要重新生成客户端 SDK 吗？不用。hindsight-clients/ 下的多语言客户端由 OpenAPI 规范生成，生成动作只在发布时触发。开发期间init.py 里的版本号变动不需要重新生成，也不要手动执行 scripts/generate-clients.sh，除非你在测试生成逻辑本身。

版本是怎么发布的？

./scripts/release.sh 0.5.0

这是发布唯一入口：脚本统一提升 API、客户端、CLI、控制面板、Helm 的版本号，重新生成 OpenAPI 规范与 Python、TypeScript、Rust 三套 SDK，更新文档版本，创建发布提交和 git tag，推送后由 CI 完成发包。

setup.sh 报错或 API 起不来怎么办？脚本是幂等的，重跑安全；只装依赖用 --skip-build，跳过模型下载用 --skip-models，顺带构建文档站用 --with-docs。API 启动报错时优先检查 .env 里的 LLM 密钥与模型配置是否正确。

改动影响了性能怎么自证？用 scripts/benchmarks/ 下的脚本做前后对照。下图是 BEAM 长期记忆基准的结果，Hindsight 以 64.1% 领先行业基线，性能类贡献可参照同样的口径验证收益。

去 Issue 列表挑一个文档类任务，克隆仓库，照上面五步走一遍。第一个被合并的 PR，就是最好的入门证明。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight