Hindsight 贡献指南参与 Agent 记忆系统开发从本地启动到第一次 PR 合并的 5 道关卡【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个开源的 Agent 记忆系统它让 AI 智能体不仅能回看对话历史还能持续从经历中学习和归纳。如果你会写代码但没参与过开源协作想贡献 Hindsight这篇文章把整条路拆成 5 道关卡环境、运行、检查、PR、进阶。每道关卡都是几条命令加一个验证动作过完你就能提交自己的第一个 PR。关卡 1十分钟搭好本地开发环境 这一关解决仓库刚克隆下来接下来做什么的问题。不要手动逐个装依赖项目提供了一个可重复执行的一次性脚本。git clone https://gitcode.com/GitHub_Trending/hindsight2/hindsight cd hindsight ./scripts/dev/setup.sh为什么用它scripts/dev/setup.sh 会自动装齐 uv/Python、Node、Rust 三条工具链从.env.example生成.env配置 git 钩子安装 Python 和 Node 工作区依赖预下载本地 ML 模型并构建 TypeScript SDK 与 Rust CLI。脚本每一步都会先检查是否已完成中断后重跑不会出乱子。网络不好可以加--skip-models跳过模型下载只装依赖可以加--skip-build。.env 生成后补上你的 LLM 密钥setup.sh 已经帮你生成了.env你只需要打开它填上自己使用的 LLM 服务商密钥OpenAI、Anthropic、Gemini 等都支持也可用 Ollama 走本地模型。为什么必须填记忆写入链路retain/reflect每一步都要调 LLM没有密钥 API 能起来但功能跑不全。如果你不想用一键脚本手动路线只有两条命令uv sync --directory hindsight-api/装 Python 依赖npm install装 Node 依赖仓库用 npm workspaces 管理多个前端包。本关验收再跑一次./scripts/dev/setup.sh看到全部步骤显示已就绪环境就稳了。关卡 2让记忆系统真正跑起来 ️这一关解决代码到底怎么工作我在哪看效果的问题。仓库在scripts/dev/下准备了三个一键启动脚本分别对应服务的三个面。三个一键启动脚本./scripts/dev/start-api.sh ./scripts/dev/start-control-plane.sh ./scripts/dev/start-docs.shstart-api.sh会先加载根目录的.env再启动记忆 API所以密钥没填这里会直接报错——它替你把环境问题暴露在最前面。start-control-plane.sh启动 hindsight-control-plane/ 下的 Web 控制面板start-docs.sh则本地运行 hindsight-docs/ 里的文档站方便你边改边看文档效果。启动后去控制面板看一眼打开控制面板的 Knowledge 页面你会看到记忆库自动整理出的知识页和心智模型。第一次贡献前花五分钟浏览一遍这个界面比读十页代码更能帮你建立系统整体在做什么的直觉。Hindsight 控制面板 Knowledge 页面记忆库自动生成的知识页、心智模型与来源记忆统计本关验收你能在控制面板里看到至少一个记忆库的数据。之后写 PR 描述时这些界面截图就是最直接的验证材料。关卡 3提交前不让代码踩红线 ️这一关解决为什么 CI 总是因为格式问题挂掉的问题。Hindsight 对 Python 用 Ruff 加 ty 类型检查对 TypeScript 用 ESLint 加 Prettier标准写在 CONTRIBUTING.md 里。装上预提交钩子./scripts/setup-hooks.sh为什么装它会把 git 指向仓库自带的.githooks/每次git commit时并行跑完所有检查——Python 侧是ruff check --fix、ruff format、ty checkTypeScript 侧是eslint --fix和prettier。格式和类型问题在提交那一刻就被修掉不会流到评审阶段拖累合并。想手动跑一遍检查时./scripts/hooks/lint.sh这个脚本就是预提交钩子里那套检查的合集所有任务并行执行比逐个手动跑快得多。如果你只想针对 API 代码单独跑也可以在hindsight-api/下依次执行uv run ruff check --fix .、uv run ruff format .和uv run ty check hindsight_api。风格上记住三条Python 代码写类型提示遵循现有文件的写法函数保持单一职责。本关验收./scripts/hooks/lint.sh输出全部通过你的分支才具备提交评审的条件。关卡 4第一次 PR 的提交要领这一关解决代码写完了PR 该长什么样的问题。流程不复杂但有两个容易翻车的地方分支基点和 PR 描述。从 main 切干净的分支git checkout -b fix/your-issue-number分支名带上你要解决的 issue 编号。为什么强调从main切评审基线就是 main分支里混入无关改动会迫使评审人逐行判断哪些是你的修改合并周期会明显变长。PR 描述写清三件事第一它解决哪个 issue直接写编号第二你改了什么、为什么这么改第三你验证过什么——跑了哪些测试、在本地看到了什么行为。第三点最重要你在关卡 2 看到的面板和日志截图就是现成的验证证据。测试是最后一道门票cd hindsight-api uv run pytest tests/提交前跑完整套件。如果只改了一个模块可以先只跑对应模块的测试文件省时间但提交前必须过一次全量。hindsight-api/tests/ 里有几百个测试文件新写测试时照着相邻文件的写法来评审人一眼就能看懂。本关验收PR 提交后 CI 全绿、描述三要素齐全剩下的就交给评审回复。关卡 5第一次合并后选下一个目标 这一关解决第一个 PR 合并了然后往哪个方向走的问题。按投入深度分三档每档都有明确的落点目录。按档位挑任务新手档改文档、补测试用例。文档在hindsight-docs/测试在hindsight-api-slim/tests/两者门槛低、反馈快。进阶档修 bug、在hindsight-api-slim/hindsight_api/engine/里做小功能这里集中了记忆写入、检索、整合的核心管线。深入档优化检索与记忆整合算法或者在hindsight-integrations/下接新的 Agent 平台——这个目录里已有 50 多个现成集成可以照着抄结构。动手前先读一遍现状Hindsight 知识图谱视图记忆库中实体与概念节点及其关联关系图里这种从记忆中自动归纳出的实体网络就是核心管线在工作的样子。开始大改动之前先在hindsight-api-slim/hindsight_api/里找到对应模块读一遍再翻翻hindsight-integrations/里的同类实现。大功能动手前先开 issue 或讨论帖说清楚你的思路让维护者帮你看方向——返工的成本远高于提前问一句。本关验收你选定一个具体目录和一个具体任务并且能说清它依赖哪几个模块。卡住时找对人问问题 这一关解决报错看不懂、方向不确定时去哪求助的问题。问之前先把自己的材料备齐维护者才能快速定位。提交 issue 写全四要素问题描述、复现步骤、预期与实际行为、环境信息操作系统、Python 版本。四样缺一issue 大概率会停在请补充信息。纯疑问类问题走 Discussions 或直接联系维护者不要把讨论型问题伪装成 bug。官方文档是你第一求助对象动手提问前先翻 hindsight-docs/ 下的开发者和集成文档大部分为什么这样设计的问题里面都有答案。现在就去做一件具体的事打开 issue 列表挑一个你看得懂的小任务对照关卡 1 到关卡 4 过一遍你的第一个 PR 就上路了。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考