企业官网建设流程全解析

Hindsight 贡献指南：参与 Agent 记忆系统开发，从本地启动到第一次 PR 合并的 5 道关卡

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

Hindsight 是一个开源的 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.sh

start-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 check，TypeScript 侧是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