企业官网建设流程全解析

Hindsight 开源 AI 记忆系统贡献指南：从克隆仓库到提交第一份 PR

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

Hindsight 是一个开源的 AI 代理记忆系统（Agent Memory），负责让 AI 代理记住、回忆并整合信息。本文是它的贡献指南，覆盖本地开发环境搭建、提交第一份 PR、协作规则和发布流程。参与开发 Hindsight，你能接触生产级的 Python / TypeScript / Rust 混合工程，并在真实的 Agent Memory 场景中积累系统开发经验。

快速跑通 Hindsight 本地开发环境

这一节解决"clone 之后如何十分钟跑起来"的问题。做完三件事，本地就具备完整的开发环境。

Hindsight 是 monorepo：服务端 API 在 hindsight-api-slim/，前端控制面板在 hindsight-control-plane/，Python / TypeScript / Rust 三套 SDK 在 hindsight-clients/，文档在 hindsight-docs/。先拿到代码：

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

然后运行一键初始化脚本./scripts/dev/setup.sh（源码见 scripts/dev/setup.sh）。它会自动补齐缺失的工具链（uv/Python、Node/npm、Rust/cargo）、从.env.example生成.env、配置 git 钩子、安装全部 Python 与 Node 工作区依赖，并预下载本地 ML 模型和分词器，让 API 可以离线运行。脚本可重复执行，每个步骤都会检查是否已完成并自动跳过；--skip-build只装依赖、--skip-models跳过模型下载、--with-docs顺带构建文档站、--force强制重建产物。

脚本跑完后只留一步人工操作：编辑.env，把你的 LLM API 密钥和配置填进去。

接下来启动服务，三个脚本各管一块：

./scripts/dev/start-api.sh # 本地 API 服务 ./scripts/dev/start-control-plane.sh # Web 控制面板 ./scripts/dev/start-docs.sh # 文档站

Hindsight 贡献指南：本地开发环境中的控制面板 Knowledge 页面

Hindsight AI 记忆系统控制面板的本地运行效果，左侧为记忆图谱视图

想确认本地开发环境是否真正就绪，就跑到测试这一步：

cd hindsight-api uv run pytest tests/

Hindsight 记忆库开发环境中的知识页树与页面详情

控制面板树形视图：由记忆自动合成的知识页

提交你的第一个贡献

这一节解决"改完代码怎么交付"的问题：分支怎么开、提交前要跑什么、PR 里写什么。

• 分支规范：从main拉出功能分支，命名形如feature/your-feature-name，保持改动范围小、一个分支只做一件事。
• 测试要求：提 PR 前，在hindsight-api/目录下跑完完整测试套件并确认全部通过。
• PR 描述要素：改了什么、解决了哪个问题或新增了什么功能、测试结果如何、相关 issue 编号。涉及 API 行为的改动，同步更新hindsight-docs/下的相关页面。
• 风格底线：Python 代码带类型注解、跟随仓库既有模式、函数保持单一职责——这一点在下一节的规则清单里再展开。

协作红线与工具链

这一节用一张规则清单交代协作中的硬性约定：哪些检查是自动执行的、issue 报告需要包含什么。

自动化 git 钩子（git commit 前自动执行的检查脚本）：仓库内置的钩子位于 .githooks/，用./scripts/setup-hooks.sh挂载（setup.sh已完成这步）。钩子触发时并行执行 scripts/hooks/lint.sh：

检查项由钩子驱动，通常无需手动执行；需要单独跑时，用./scripts/hooks/lint.sh复现完整流程，或在对应包目录单独执行uv run ruff check --fix .、uv run ruff format .、uv run ty check hindsight_api。

代码风格：跟随现有代码模式，不引入新的风格变体。

issue 报告四要素：清晰的问题描述、可复现的步骤、预期行为与实际行为的对比、环境信息（操作系统、Python 版本）。四者齐全，维护者定位问题的速度会明显更快。

进阶方向：发布、架构与客户端生成

这一节面向有前几次提交经验、想往深处走的贡献者。

发布流程由 scripts/release.sh 自动化，例如./scripts/release.sh 0.5.0。脚本依次完成：更新全部组件的版本号、重新生成 OpenAPI 规范与 Python / TypeScript / Rust 三套客户端 SDK、更新文档版本号、创建发布提交与 git tag、推送到远端触发 CI/CD 发包。

两条容易踩的坑，先记下再动手：

• 开发期在__init__.py里改版本号，不需要重新生成客户端；客户端只在正式发布时重新生成。
• 不要手动运行./scripts/generate-clients.sh，除非你正在验证生成逻辑本身的变更。

架构级改动集中在 hindsight-api-slim/hindsight_api/engine/；涉及数据库结构变化时，需要按 alembic 迁移目录 的模式新增迁移并跑迁移相关测试。多语言 SDK 位于hindsight-clients/下的python/、typescript/、rust/，一般不建议手改——它们由 API 规范生成。

性能与基准：评测和回归在 hindsight-dev/benchmarks/ 下进行，改动检索或记忆整合链路时先跑一遍基准再提 PR。

BEAM 10M 基准：Hindsight 相对行业基线的得分对比

从 issue 列表挑一个带新手标签的任务，跑通本地环境后按上面的流程交付你的第一份 PR 即可。

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