Hindsight 开发者指南从环境搭建到第一个 PR 的完整路径【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个让 AI 代理拥有记忆的开源系统核心是 retain写入、recall检索、reflect反思三条流水线。读完这篇贡献指南你能从零搭好本地开发环境跑通 API 服务并走通从一个小改动到提交第一个 PR 的全流程。贡献地图一览动手之前先选路径。下表把最常见的四类贡献映射到具体入口对照自己的基础选一条即可贡献类型入口难度适合人群文档修复与补充hindsight-docs/docs/低零基础的新手最快上手补充测试用例hindsight-api/tests/中想熟悉记忆流水线的开发者功能开发hindsight-api-slim/hindsight_api/高愿意深入核心逻辑的贡献者维护与优化scripts/dev/中关注工具链、脚本与 CI 的人选择你的切入点文档。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克隆仓库并进入目录git clone https://gitcode.com/GitHub_Trending/hindsight2/hindsight一键初始化环境./scripts/dev/setup.sh该脚本可重复执行会按需装好 uv、Node、cargo 工具链从 .env.example 生成 .env安装全部依赖并预下载本地模型。随后在 .env 里填入你的 LLM API 密钥。启动本地 API 验证环境./scripts/dev/start-api.sh需要界面时用同目录的 start-control-plane.sh 和 start-docs.sh 分别拉起控制面板与文档站。跑一遍测试确认没有破坏uv run pytest tests/ -x在 hindsight-api/ 目录下执行-x 让第一个失败即停方便定位。做一次最小改动改一处文档或补一个测试执行./scripts/hooks/lint.sh确认检查通过然后从 main 切出功能分支提交 PR。代码质量的三条底线格式与静态检查Python 用 ruff check --fix 和 ruff formatTypeScript 用 eslint --fix 和 prettier钩子在提交时把两套检查并行跑完。类型检查Python 侧额外跑 ty check所以新增代码必须带类型提示这是评审时会被重点看的。自动拦截执行一次./scripts/setup-hooks.shgit 会指向 .githooks/ 下的脚本之后每次 commit 前自动跑全部检查无需记命令。手动替代忘了装钩子也没关系./scripts/hooks/lint.sh就是 pre-commit 跑的那套完整检查提交前手动跑一遍即可。测试门槛新功能必须带测试用例涉及流水线的改动先在 hindsight-api/tests/ 对应文件里跑通再全量过一遍。提交之后会发生什么PR 从 main 切出的功能分支提交描述里写清改动内容、对应的问题编号和测试结果。维护者评审时主要看两点测试是否覆盖新逻辑代码是否遵循现有模式类型提示、既有代码结构、函数职责单一。对评审意见逐条回复处理方式改动以新 commit 推上去并同步 mainCI 的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考