Hindsight Devin Desktop 集成（原 Windsurf）演进与实战解析

Hindsight Devin Desktop 集成（原 Windsurf）演进与实战解析

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

本指南围绕 Hindsight 仓库中 Devin Desktop 集成的变更日志 展开，讲解hindsight-devin-desktop集成包的核心能力：如何把 Hindsight 的长期记忆（MCP 工具 + 记忆规则 + 会话钩子）注入 Devin Desktop 内置的两个智能体，以及该集成从 Windsurf 更名而来的版本演进背景。读完本文，你将掌握该集成的安装、双 Agent 接线原理、双层记忆库设计、确定性钩子机制以及全部 CLI 命令与配置项，并能结合源码定位到每一个关键实现文件。

变更日志：从 Windsurf 到 Devin Desktop

hindsight-devin-desktop是 Hindsight 官方维护的独立集成包（PyPI 包名hindsight-devin-desktop），其独立变更日志记录了面向用户的功能演进。目前文档记录的首个版本0.1.0包含一项关键改进：

• 将 Devin Desktop 集成（原 Windsurf）更名，并改进其并发使用时的稳定性。（贡献者 @DK09876，提交fcb2c958e）

这条记录隐含了两条重要信息：其一，该集成最初面向 Windsurf（Codeium）设计，在 Cognition 将 Windsurf 更名为 Devin Desktop 后跟随更名；其二，0.1.0 重点修复了多个会话/工具并发调用时的稳定性问题。从当前仓库的 pyproject.toml 可以看到，集成包现已演进到0.2.0版本，支持 Python ≥ 3.10，并通过hindsight-devin-desktop = "hindsight_devin_desktop.cli:main"暴露为命令行工具。更完整的用户向说明见该集成的 README。

集成的核心：一个 MCP 服务器，两个智能体

Devin Desktop 同时内置了两个配置彼此独立的智能体，init命令会为两者分别写入配置：

Cascade（Windsurf 遗留智能体）	Devin Local（继任智能体）
MCP 服务器配置	~/.codeium/windsurf/mcp_config.json（serverUrl字段）	~/.config/devin/config.json（url+transport+headers）
工具审批	自动	预置放行规则mcp__hindsight__*，工具调用不弹确认
项目级规则	.devin/rules/hindsight.md	仓库根目录AGENTS.md
全局规则	~/.codeium/windsurf/memories/global_rules.md	~/.config/devin/AGENTS.md
自动召回	—（规则驱动）	SessionStart钩子确定性注入记忆
留存提示	—	Stop钩子强制一次 retain 回合
可见性	post_mcp_tool_use横幅（hooks.json）	原生工具卡片 + 规则叙述

配置其中一个智能体并不会让另一个生效，因此集成会同时写入两套文件；所有文件编辑都是“外科手术式”的——专用文件直接写，共享文件（AGENTS.md、global_rules.md、hooks.json）只插入一个带围栏标记的管理块。上述路径为 macOS/Linux 布局，Windows 上 Devin Local 配置位于%APPDATA%\devin\，Cascade 仍使用~/.codeium/windsurf\。

从源码看，Cascade 侧的接线逻辑集中在 mcp_config.py：由于官方文档对mcp_config.json的实际位置说法不一（~/.codeium/windsurf/与~/.codeium/两种），default_mcp_paths()会同时写入两个位置，确保无论客户端读取哪一处都能发现hindsight服务器条目。Devin Local 侧则由 devin_local.py 负责，它写入的是与 Cascade 不同的远程 MCP schema（url+transport: "http"），并额外注入permissions.allow放行规则与两个钩子。

多银行模式：一个端点，两个记忆域

集成采用 Hindsight 的multi-bank 模式：单个 MCP 端点（URL 以/mcp/结尾，路径中不绑定任何 bank），所有工具接受可选的bank_id参数。init会生成形如下方的 Cascade 配置片段：

{ "mcpServers": { "hindsight": { "serverUrl": "https://api.hindsight.vectorize.io/mcp/", "headers": { "Authorization": "Bearer hsk_...", "X-Bank-Id": "devin-desktop" } } } }

其中X-Bank-Id头把全局银行指定为默认 bank——当模型在工具调用中省略bank_id时，请求会回落到该银行。这一行为的构造逻辑位于 mcp_config.py 的build_http_server()（Devin Local 侧对应 devin_local.py 的build_http_server()）。

双层记忆：全局银行 + 项目银行

记忆被拆分到两个相互隔离的 Hindsight bank，避免一个仓库的工作“串味”到另一个：

• 全局银行（默认devin-desktop）：跨项目的偏好、编码风格、身份信息，在所有项目中共享。
• 项目银行（默认devin-desktop-<slug>）：当前仓库的架构、决策、约定。<slug>由仓库的git remote派生，因此跨机器稳定，且对协作者完全一致——这意味着提交项目规则文件后，整个团队共享同一个项目银行。

项目银行的派生逻辑在 project.py 中实现：优先取git remote get-url origin的owner/repo部分（剥离 host 与.git，兼容git@host:owner/repo.git、https://host/owner/repo.git、ssh://三种形式），失败后依次回退到 git 仓库文件夹名、当前文件夹名，最终 slug 化为<global>-<slug>形式。

退出共享层：--no-global-bank

如果你不希望个人偏好跨仓库跟随，可传入--no-global-bank进入local-only 模式：项目事实与个人偏好全部写入当前仓库的项目银行，不共享任何内容，全局规则文件也不会写入。从 cli.py 的build_install()可以看到，该模式下rule_global被置为None（规则把所有记忆路由到项目银行），同时全局规则块被移除而非写入。

确定性记忆：Devin Local 的两个钩子

MCP 工具 + 规则是模型驱动的——智能体是因为规则要求它才去 recall/retain。而 Devin Local 额外支持两个钩子（均可用--no-hooks关闭），使记忆行为变为确定性触发：

• SessionStart自动召回：会话开始时召回项目 + 全局记忆并注入智能体上下文，即使模型忘记调用recall也能加载相关记忆。它总是汇报状态（已加载 N 条 / 空 / 不可用），记忆使用从不静默；同时永不阻塞会话（超时 8 秒、异常时也返回状态文本并退出码 0）。
• Stop留存提示：智能体停止前，钩子返回{"decision":"block","reason":...}强制进行一轮 retain——由模型判断哪些内容值得长期保存并调用retain工具。通过stop_hook_active做循环保护，每次会话仅多花费一个回合；可用--no-retain-hook单独关闭。

为什么不做成全自动 retain？因为 Devin 的钩子无法把会话转录文本交给脚本，钩子自身无法“总结并留存”——留存提示是最近似的确定性方案（保证触发，内容由模型创作）。Cascade 侧则两种钩子都不支持（其钩子无法注入上下文），因此 recall/retain 保持模型驱动，但init会添加一个post_mcp_tool_use横幅钩子，让 Cascade 在每次工具调用后可见地显示🧠 Hindsight: <tool> used。

钩子的实际执行逻辑集中在 hook.py：

• cmd_recall用标准库urllib走 MCPinitialize→notifications/initialized→tools/call（工具名recall，查询词固定为"Key architecture, decisions, conventions, and the user's preferences and coding style for this work."，max_tokens=1024），再把结果以additionalContext形式交给 Devin 注入上下文；
• cmd_retain_nudge根据是否 local-only 构造不同语气的留存提示（项目事实写入项目银行、用户事实写入全局银行）；
• cmd_banner则对所有 MCP 工具调用做过滤，只对hindsight服务器打印可见横幅。

每次钩子运行都会追加一行“存活证明”日志到~/.hindsight/devin-hook.log（可用环境变量HINDSIGHT_HOOK_LOG=off关闭），便于确认 recall/retain 钩子确实触发。

安装与使用

pip install hindsight-devin-desktop cd your-project hindsight-devin-desktop init --api-token YOUR_HINDSIGHT_API_KEY

init需要在仓库内运行（以便从 git remote 派生项目银行），它会同时接线两个智能体：MCP 服务器条目、项目规则（请提交./.devin/rules/hindsight.md与./AGENTS.md，这样协作者共享项目银行）以及全局规则。随后需要在所用智能体中激活服务器（配置不会热加载）：

• Cascade：打开 MCP 面板，点击Refresh。
• Devin Local：打开Devin MCP Marketplace，在Installed下找到hindsight，点击Connect。

不确定自己用的是哪个智能体？查看 Devin Desktop 右下角的智能体选择器即可。

验证是否生效

开启一个会话，你会直接“看到”记忆在工作：

• Devin Local：回复以状态行开头，如🧠 Hindsight preloaded 3 memories for this session（或no memory yet、⚠️ memory unavailable this session）。
• Cascade：每次recall/retain显示为工具卡片，展开post-tool hooks行即可看到🧠 Hindsight: <tool> used横幅。
• 运行hindsight-devin-desktop status可列出两个智能体的每个组件是否已安装，以及解析出的银行。

也可以先试运行hindsight-devin-desktop init --print-only，只打印将要写入的全部配置而不触碰任何文件。

连接 Hindsight

默认连接 Hindsight Cloud，也支持自托管服务器：

hindsight-devin-desktop init --api-url http://localhost:8888 # 本地开放服务器无需 token hindsight-devin-desktop init --bank-id <id> # 显式指定项目银行 hindsight-devin-desktop init --global-bank <id> # 更换跨项目银行

CLI 命令一览

命令	说明
hindsight-devin-desktop init	接线两个智能体的 MCP 服务器 + 记忆规则（自动派生项目银行）
hindsight-devin-desktop status	显示解析出的银行 + 各智能体是否已配置
hindsight-devin-desktop uninstall	从两个智能体移除 MCP 服务器 + 记忆规则

init还支持以下开关：--print-only（只打印不写入）、--no-hooks（跳过两个 Devin Local 钩子）、--no-retain-hook（保留自动召回、跳过留存提示）、--no-global-bank（local-only 模式）。所有选项与解析逻辑见 cli.py。

配置项

配置	环境变量	默认值
API URL	HINDSIGHT_API_URL	https://api.hindsight.vectorize.io
API Token	HINDSIGHT_API_TOKEN	（无；Cloud 必需）
全局银行	HINDSIGHT_DEVIN_DESKTOP_GLOBAL_BANK	devin-desktop
项目银行	HINDSIGHT_DEVIN_DESKTOP_BANK_ID	（由 git remote 派生）

init还会把连接信息与全局银行持久化到用户配置文件（~/.hindsight/下），后续运行优先读取该文件，再按“CLI 参数 > 环境变量 > 默认值”的优先级解析（见 cli.py 的_resolve()与 config.py）。

源码与测试指引

想深入验证本文所述行为的读者，可按以下路径继续阅读：

• CLI 装配：hindsight_devin_desktop/cli.py ——init/status/uninstall三个子命令与参数解析。
• Cascade 接线：hindsight_devin_desktop/mcp_config.py 与 hindsight_devin_desktop/rules.py、hindsight_devin_desktop/global_rules.py。
• Devin Local 接线：hindsight_devin_desktop/devin_local.py 与 hindsight_devin_desktop/hook.py、hindsight_devin_desktop/cascade_hooks.py。
• 银行派生：hindsight_devin_desktop/project.py。
• 测试：仓库提供了覆盖各模块的确定性测试套件（tests），本地可用uv sync && uv run pytest tests -v -m 'not requires_real_llm'运行（requires_real_llm标记的端到端用例需要真实 Hindsight 服务与 LLM 密钥，单独用-m requires_real_llm运行）。

小结

从变更日志记录的 0.1.0（Windsurf 更名 + 并发稳定性修复）到当前 0.2.0，hindsight-devin-desktop已形成一套完整方案：一个多银行 MCP 端点同时服务 Cascade 与 Devin Local 两个智能体，双层银行保证项目记忆隔离，SessionStart自动召回与Stop留存提示把记忆行为从“依赖模型自觉”升级为“确定性触发且全程可见”。对同时使用 Devin Desktop 多个工作区的开发者而言，一条init命令即可让长期记忆覆盖所有会话。

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