Hindsight Reflect 使用规范与下一步规划

• HTML: https://decision.ht1072.top/2026-06-19-hindsight-reflect-usage-and-roadmap-2026-06-19.html
• Local HTML: [已移除本地路径]
• Generated: 2026-06-19T10:01:32+08:00

Hindsight Reflect 使用规范与下一步规划

入库时间：2026-06-19 适用范围：本机 Hindsight 0.8.1（端口 8889，bank=hermes，事实数 8157+） 配套 skill：integration/hindsight-reflect-ops CLI 入口：~/.local/bin/hindsight-reflect（symlink 到 ~/.hermes/scripts/hindsight_reflect.py）

页面摘要区

核心结论

Hindsight 的 reflect 不是"定时反思"，而是 query-driven 的 agentic RAG。本机已完整打通 directives + mental_models + reflect 三层，配 5 个 query 模板和 4 个长效 mental_model，实测命中后 token 省 12 倍、耗时省 8 倍。短期不上 cron，长期等周复盘稳定后可考虑。

推荐用法（按场景）

• 决策前 priming → 给新 agent 注入主题背景
• 矛盾诊断 → "我对 A vs B 的态度是否冲突"
• 周复盘 → 7 天反复模式 + 关键决策（带 response_schema 结构化输出）
• 风格简报 → 给外人/AI 解释涛哥工作方式
• 历史回顾 → 类似问题前看过去怎么决定的

关键边界

• reflect 只读，不写回 mental_model；mental_model 是独立创建的
• mental_model 自动生成靠 hindsight 内部跑 reflect，有跨主题污染风险——source_query 必须窄而清晰
• LLM 间歇性不遵守 forced tool_choice，短 query + 大量 directives 时容易直接 done()
• low budget + 注入 directives 后会触发 agent 偷懒返回 "I don't have information"，日常用 mid，复盘用 high

一、Reflect 是什么

Hindsight 0.8.x 的 POST /banks/{bank}/reflect 是 agentic RAG，而不是离线反思批处理。

调用时它会：

1. 强制按层级调工具检索：search_mental_models → search_observations → recall
2. 把检索结果合成中文 markdown 答案
3. 答案被 directives（强制规则）和 reflect_mission（角色定位）双重约束
4. 可选：传 response_schema 强制结构化 JSON 输出

它不会：

• 不会自动跑（没 cron / scheduler）
• 不会自动生成 mental_model 或 directives
• 不会接管 consolidation（那是单独的合并 pipeline）

二、当前资产清单

8 条全局 directives（tags=[]，全局生效）

4 个长效 mental_models

5 个 reflect 模板（CLI）

hindsight-reflect <template> [topic] [--budget low|mid|high] [--print]

输出落 ~/.hermes/cache/reflect-output/<template>-<ts>.{md,json}。

三、ROI 实证

同一个主题相关的 query，有无 mental_model 的差距：

实测数据来源：[已移除本地路径] 与 raw-20260619-095101.{md,json}。

四、几个关键陷阱

1. tag isolation（最坑的一个）

POST 完 directives 后，reflect 响应里 based_on.directives = []，输出风格也没变。

根因（memory_engine.py:10138）：reflect 默认 isolation_mode=True + 没传 tags → 所有带 tag 的 directive 都被过滤。

做法：全局通用 directive / mental_model 必须 tags=[]。

2. LLM 间歇性跳过 forced tool_choice

源码 agent.py:627 强制 tool_choice={"type":"function","function":{"name":"search_mental_models"}}，但实测部分短 query + mid budget 时 LLM 不遵守，4 秒内直接 done() 返回 "I don't have information"。

做法：

• query 写长一点、措辞明确（"先用 search_mental_models 搜索..."）
• mid 以上 budget 比 low 稳得多
• 重试 1-2 次

3. mental_model 跨主题污染

gateway-restart-protocol 的 source_query 里写了"验证 base_url、model、API mode"，结果生成的 mental_model 里塞了大量 routing 内容（属于 model-routing-canon 的领地）。

做法：source_query 用具体名词（hermes-gateway.service、decision_trace_publish.py），不要提其他主题的关键词。

4. budget 误用

5. Hindsight 0.8.1 已知 bug

reflect 输出末尾偶尔出现 memory_ids: [] mental_model_ids: [...]——这是 done() 工具的结构化输出泄漏，正则没清干净。可忽略，或在 wrapper 里后处理裁掉。

五、下一步规划

短期（已完成 + 不再扩张）

✅ 8 条 global directives 写入并验证生效 ✅ 4 个高 ROI 主题建成 mental_model ✅ hindsight-reflect CLI 部署到 ~/.local/bin/ ✅ 沉淀 skill integration/hindsight-reflect-ops

明确不做的：

• ❌ 不建 feishu-vs-weixin-channel mental_model — bank 里相关纯净 fact 太少，召回噪音太重
• ❌ 不建 external-project-absorption mental_model — 已有 skill external-project-absorption-eval 作为 canonical，重复建会冲突
• ❌ 不上 cron 定时跑 reflect — query-driven 工具盲跑等于烧 token

中期（条件触发，不强推）

条件 A：weekly 模板连续 2-3 周产出稳定 → 上 cron，周一早 6:30 跑 hindsight-reflect weekly → 飞书短卡 + 发到 decision.ht1072.top → 可参考 morning-brief-direct-feishu-send 模式

条件 B：consolidation 跑出新主题观察 → 给 mental_model 配 trigger.refresh_after_consolidation: true → consolidation 完成后 hindsight 自动 refresh 这些 mental_model → 等于"被动反思"，不需要手动触发

条件 C：新主题反复出现 → 任何主题在 1 个月内被 ≥3 次 raw query 覆盖，就考虑建 mental_model → 候选观察池：cron 治理、skill 治理、provider 升级路线、kanban 调度

长期（视价值密度决定）

directives 演进

• 现在 8 条都是从 USER.md 提炼的核心规则。如果未来发现某条 directive 在 reflect 输出里反复"生效却没什么帮助"，下调 priority 或软关停（is_active=false）
• 不主动加新 directive；只在反复指出同一类问题后才补

mental_model 库扩张原则

• 每个 mental_model 的 source_query 必须能用一句话概括，且不和现有库重叠
• 单个 mental_model 不超过 4k 字（超出说明主题不够聚焦，应拆分）
• 每季度复审一次：跑一次相关 reflect，看是否还命中、内容是否过时

何时考虑 reflect 自动化

• mental_model 库稳定到 ≥10 个，且 reflect 命中率（based_on.mental_models 非空的比例）≥80%
• weekly 模板的产出连续 3 周可读、可决策
• 出现明确的"我每周一定会问的问题"

满足前先观察、后决策；现在不动。

六、操作 Cheat Sheet

跑一次反思

# 主题简报
hindsight-reflect priming "<主题>"

# 矛盾诊断
hindsight-reflect conflicts "<A vs B>"

# 周复盘（带 schema）
hindsight-reflect weekly

# 自定义
hindsight-reflect raw "<query>" --budget mid

看 mental_models / directives 当前状态

# 当前所有 mental_models
curl -s http://localhost:8889/v1/default/banks/hermes/mental-models | python3 -m json.tool

# 当前所有 directives（按 priority 倒序）
curl -s http://localhost:8889/v1/default/banks/hermes/directives | \
  python3 -c "import sys,json; d=json.load(sys.stdin); \
  [print(f'[{x[\"priority\"]:3}] {x[\"name\"]}') for x in sorted(d['items'],key=lambda x:-x['priority'])]"

创建新 mental_model

import json, urllib.request
mm = {
    "id": "<lowercase-with-hyphens>",
    "name": "<人类可读名>",
    "source_query": "<让 hindsight reflect 生成内容的 query>",
    "max_tokens": 3000,
    "trigger": {"mode": "delta", "refresh_after_consolidation": False},
    "tags": []   # 关键：留空避免 isolation
}
urllib.request.urlopen(urllib.request.Request(
    "http://localhost:8889/v1/default/banks/hermes/mental-models",
    data=json.dumps(mm).encode(),
    headers={"Content-Type":"application/json"}, method="POST"
))

返回 operation_id，轮询 /operations/{op_id} 直到 status=completed（约 30-90s）。

修改 directive（软关停 / 改文案）

# 软关停
curl -X PATCH http://localhost:8889/v1/default/banks/hermes/directives/<id> \
  -H "Content-Type: application/json" -d '{"is_active": false}'

# 改文案
curl -X PATCH http://localhost:8889/v1/default/banks/hermes/directives/<id> \
  -H "Content-Type: application/json" -d '{"content": "新内容"}'

七、引用 / 关联

• skill：integration/hindsight-reflect-ops（含完整故障排查表和 cheat sheet）
• 兄弟 skill：integration/hindsight-memory-operations（umbrella）
• 源码参考：hindsight_api/engine/reflect/agent.py、prompts.py、memory_engine.py:list_directives
• API 文档：http://localhost:8889/openapi.json
• 缓存输出：~/.hermes/cache/reflect-output/
• 实测样本：raw-20260619-095101.{md,json}（4 个 mental_model 全命中、33k token、14 秒）

变更： 后续如果新建/废弃 mental_model、调整 directive priority、或改变 reflect 自动化策略，请同步更新本文。