LamplitIsles/kepos-hindsight

kepos-hindsight

一个用于陪伴式 DSH 代理的小型 Hindsight 适配器。它仅替换 DSH 官方的编码代理适配器。Codex 可以继续使用官方编码代理钩子和相同的 ~/.hindsight/coding-agent.json 文件。

该包针对确切的 DSH 0.1.2-rc.1 Host 和 Web 客户端契约；将其作为 bundle 安装时，请使用匹配的 rc.1 DSH 运行时。

它的功能

- 在每次直接用户回合上运行原始 Hindsight 召回，使用当前消息和少量先前的用户上下文。
- 在每次直接回合上注入一个 Hindsight 上下文：宿主的当前本地时间是权威的，而召回的事实仍明确为不可信的历史上下文。检索失败会超时，且绝不会阻塞回复。
- 每个会话保留到一个稳定的 Hindsight 文档中：dsh:。DSH 启动后第一个完成的回合会用可用的完整会话记录替换它；之后的回合仅追加其 JSONL 增量。
- 暴露一个刻意设计的只读工具：hindsight_reflect，用于在自动提供的原始事实和当前对话无法回答问题时，进行由 bank 定义的多记忆综合。

它不会为代码库播种、创建知识页面、自动反思、导入 bank 模板或启用子代理。

为什么不使用官方编码代理集成？

官方集成将仓库或工作树视为持久实体：它调查代码、保留编码会话、维护知识页面、召回过去的决策，并暴露面向项目的工具。这非常适合工程代理，但对于一个在无关对话和工作区之间持续存在的陪伴者来说，这是错误的身份和生命周期。

此适配器改变的是产品契约，而不仅仅是改变提示词：

| 关注点 | 官方编码代理集成 | 此陪伴适配器 |
| --- | --- | --- |
| 持久身份 | 仓库/工作区 | 一个用户选择的关系 bank |
| 自动检索 | 编码知识、初始综合和页面指导 | 在每次直接用户回合前进行原始、非 LLM 召回 |
| 重复 | 编码生命周期决定综合/指导何时有用 | 每个结果在每个相关回合上仍然有资格；无跨回合抑制 |
| 保留 | 编码会话、仓库事实、Git/文档策略 | 每个聊天会话中一个可修复文档中的干净用户/助手对话 |
| 反思 | 编码知识工作流的一部分 | 用于需要综合的问题的刻意显式工具 |
| 工具 | 知识页面、项目搜索/捕获/摄取、Reflect | 一个只读的 hindsight_reflect 工具 |
| 路由 | 从工作区派生的 bank | 工作区、CWD 和预设绝不会重新路由所选 bank |
| 策略所有权 | 附带编码任务和策略 | 不发送任何策略或任务；bank 所有者定义陪伴记忆策略 |
| Agent 拓扑结构 | 支持编码代理和子代理工作流 | 仅限直接伴随会话；子代理被排除在外 |

实际结果是：在无需编码代理开销的情况下实现连续性——每轮运行低成本的检索，完整的源对话作为稳定的会话文档提交，而昂贵的 Reflect 综合仅在请求时发生。

有关生命周期、失败语义、提示边界以及这些选择背后的设计原则，请参阅伴随记忆设计。

Bank 策略与提示

适配器对 bank 的 retain_mission、observations_mission 或 reflect_mission 没有任何意见。

它从不调用 /import，不发送 Hindsight strategy，也不发送 retain context。请通过 Hindsight 的正常 UI 或 bank 配置 API，为目标 bank 配置这些任务。这样可让每个伴随的记忆策略完全由用户掌控，并防止 DSH 插件更新将其覆盖。

围绕召回事实的简短包装是一个提示注入边界，而非 Hindsight 策略：召回的历史是证据，绝不是指令。时钟在本地为当前轮次生成，随同一上下文传递，并被排除在保留的转录之外。

作为本地 DSH 包安装

pnpm install
pnpm build
dsh plugin --profile web add file:/absolute/path/to/kepos-hindsight

该包挂载 kepos-hindsight。它不会改动官方 Codex 集成。在启动 DSH 之前确认组合：

dsh --profile web --dump-config

输出中应包含一行已启用的 kepos-hindsight。正在运行的 DSH 主机在更改其包列表后必须重启。

对于已发布的版本，直接安装公共包：

dsh plugin --profile web add @lamplitisles/kepos-hindsight

配置

端点、凭据、各 bank 的任务以及全局 disabled 标志保留在常规的共享 Hindsight 配置 ~/.hindsight/coding-agent.json 中。

在 Settings → Plugins → Hindsight memory 中选择 DSH 伴随 bank。它默认为 yuki-memory。这是唯一的路由选择：DSH 代理、其预设、其工作区以及当前工作目录都不会选择或重新映射 bank。所选的 bank 会被自动召回、异步保留和 hindsight_reflect 共同使用。

保存是一项实时 DSH 设置，会在下一轮生效。DSH 有意仅允许从其回环 Web UI 进行 Settings RPC 写入，因此请在主机上更改，而不是通过 Kepos 代理的移动连接。

可选的 harnesses.dsh.companion.recall 扩展仅用于调整检索；它不会选择 bank，也不会添加召回/保留开关。官方编码代理适配器会忽略此扩展。

{
"harnesses": {
"dsh": {
"companion": {
"recall": {
"budget": "low",
"maxTokens": 900,
"types": ["observation", "world", "experience"],
"preferObservations": true,
"topK": 3,
"contextTurns": 2,
"maxQueryChars": 800,
"timeoutMs": 4000
}
}
}
}
}

此示例是可选的：所示的值即为默认值。low 召回是检索，而不是 Reflect LLM 请求。只有在确认真实对话需要更广泛的检索之后，才提高其预算。自动召回和保留有意不设 UI 控件；全局 Hindsight 的 disabled 和 retainSessions 设置仍然是它们共享的服务级保障措施。

Yuki 存在于 DSH 实时配置中

本仓库有意不附带任何 Yuki 人设或预设。请在本地 $DSH_HOME/.agent-presets/yuki/ 下创建并保存该预设，最好通过 DSH 的预设 UI 复制 DSH 当前的 standard 预设，然后编辑该副本。对于单会话伴侣，请禁用或移除其 delegation 组。工作区自身的 AGENTS.md、SOUL.md、IDENTITY.md 和 USER.md 仍然是人格与关系行为的唯一事实来源。

开发
bash
pnpm check
pnpm test
pnpm build

测试使用伪造的 Hindsight HTTP 响应以及测试自有的临时配置目录；它们绝不会读取或修改真实的 bank。

维护者发布

发布工作流仅针对与 v 匹配的语义化版本标签发布 @lamplitisles/kepos-hindsight。在发布任务可以运行之前，它会验证冻结的 pnpm 安装、类型检查、测试、构建、发布预检以及打包后的 DSH 产物。

首次 npm 和 GitHub 设置

在首次可信发布之前，维护者必须：

1. 创建或认领 @lamplitisles npm 作用域。临时将包版本设置为独特的引导预发布版本 0.1.0-beta.0（不要创建 Git 发布标签），然后运行匹配的预检和检查：

bash
pnpm check
pnpm test
pnpm build
GITHUB_REF_NAME=v0.1.0-beta.0 pnpm release:check
pnpm pack-smoke

在维护者机器上以交互方式完成身份验证后，将该引导版本发布到 npm 的 beta 通道：

bash
npm publish --access public --tag beta

这样可以为首次稳定 OIDC 发布保留 0.1.0。
2. 在 npm 包设置中，为 LamplitIsles GitHub 所有者、仓库 kepos-hindsight、工作流 .github/workflows/release.yml 和环境 npm 添加 Trusted Publisher。
3. 创建受保护的 GitHub npm 环境，并应用该仓库的发布审批策略（例如，必需审阅者和允许的发布标签）。
4. 通过授权的 forge 命令创建首个稳定版本。CI 会在预检和发布之前，从标签同步其一次性包清单：

bash
og tag v0.1.0

该标签会启动由 OIDC 支持的工作流，将 0.1.0 发布到 npm 的 latest 通道。不要使用直接的 Git 标签或推送命令。
受信任发布使用 GitHub 的 OIDC 身份和 npm 来源证明。请勿向此仓库或其 GitHub secrets 添加 npm 身份验证令牌或任何其他 npm 凭据。

常规发布

在变更准备就绪后，使用仓库授权的 forge 命令创建并发布标签：
bash
og tag v0.1.0

使用预发布版本（如 v0.1.1-beta.1）进行 beta 测试。稳定标签发布到 npm 的 latest dist-tag；包含预发布标识符的标签发布到 beta。CI 会在其一次性验证工作区中将包版本同步到标签，然后仅发布经过验证的产物。

要在本地复现发布预检而不实际发布，请使用一次性工作树，从标签同步其包清单，然后运行检查：
bash
GITHUB_REF_NAME=v0.1.0 pnpm release:sync-version
GITHUB_REF_NAME=v0.1.0 pnpm release:check

预检会拒绝格式错误或不匹配的标签、非公开的 npm 元数据，以及省略 DSH 入口点或包含不安全构建输出的打包产物。完整的本地验证仍为：
bash
pnpm install --frozen-lockfile
pnpm check
pnpm test
pnpm build
pnpm pack-smoke

设计与操作说明

companion-memory 笔记涵盖了编码/伴侣边界、提示与提取策略、会话回填、冷启动成本、重排序、提供商迁移及相关集成。