Skip to content
Python

feat(memhub): add product memory pipeline diagnostics (#25)

feitianxiang2a4dc2ffa2d3
diff --git a/memhub/README.md b/memhub/README.md
index 16d3556..ac21140 100644
--- a/memhub/README.md
+++ b/memhub/README.md
@@ -42,6 +42,8 @@ Linux 制品由 GitHub Actions 在原生架构 runner 上构建并完成生命
架构详情见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 和
[`docs/contracts/runtime-unification.md`](docs/contracts/runtime-unification.md)。
+产品、测试和一线支持排查导入与记忆沉淀时,使用
+[`docs/PRODUCT_LOG_TROUBLESHOOTING.md`](docs/PRODUCT_LOG_TROUBLESHOOTING.md)。
## 开发环境
diff --git a/memhub/apps/core/src/one_memory/imports/supervisor.py b/memhub/apps/core/src/one_memory/imports/supervisor.py
index 0322b88..c3cda03 100644
--- a/memhub/apps/core/src/one_memory/imports/supervisor.py
+++ b/memhub/apps/core/src/one_memory/imports/supervisor.py
@@ -316,6 +316,10 @@ class ImportSupervisor:
"source_id": current.source_id,
"mode": current.operation,
"count": current.stored,
+ "stored_count": current.stored,
+ "revised_count": current.revised,
+ "skipped_count": current.skipped,
+ "error_count": current.errors,
},
)
diff --git a/memhub/apps/core/src/one_memory/memory_processing.py b/memhub/apps/core/src/one_memory/memory_processing.py
index 98c3320..65303e3 100644
--- a/memhub/apps/core/src/one_memory/memory_processing.py
+++ b/memhub/apps/core/src/one_memory/memory_processing.py
@@ -334,6 +334,19 @@ class MemoryTaskRunner:
**diagnostic_exception(error),
)
raise
+ outputs, counts = await asyncio.gather(
+ in_the_background(self.tasks.outputs, task_id),
+ in_the_background(self.tasks.counts),
+ )
+ outstanding = sum(
+ counts.get(status, 0)
+ for status in (
+ MemoryTaskStatus.PENDING,
+ MemoryTaskStatus.WAITING_FOR_PERMISSION,
+ MemoryTaskStatus.WAITING_FOR_MODEL,
+ MemoryTaskStatus.FAILED,
+ )
+ )
diagnostic_event(
level="error" if result.status is MemoryTaskStatus.FAILED else "info",
component="memory.task",
@@ -343,6 +356,11 @@ class MemoryTaskRunner:
duration_ms=elapsed_ms(started),
state_after=str(result.status),
error_code=result.last_error_code,
+ details={
+ "result_count": len(outputs),
+ "pending_count": outstanding,
+ "attempt": result.attempts,
+ },
)
return result
diff --git a/memhub/apps/core/tests/test_diagnostic_trace.py b/memhub/apps/core/tests/test_diagnostic_trace.py
index 793179f..7882862 100644
--- a/memhub/apps/core/tests/test_diagnostic_trace.py
+++ b/memhub/apps/core/tests/test_diagnostic_trace.py
@@ -165,6 +165,13 @@ def test_import_request_trace_reaches_the_background_job_without_original_text(t
assert "import.queued" in names
assert "import.started" in names
assert "import.finished" in names
+ finished = next(event for event in events if event["event"] == "import.finished")
+ assert {
+ "stored_count",
+ "revised_count",
+ "skipped_count",
+ "error_count",
+ } <= finished["details"].keys()
assert secret not in written
diff --git a/memhub/apps/core/tests/test_memory_processing.py b/memhub/apps/core/tests/test_memory_processing.py
index d124b4a..678da5f 100644
--- a/memhub/apps/core/tests/test_memory_processing.py
+++ b/memhub/apps/core/tests/test_memory_processing.py
@@ -315,6 +315,12 @@ def test_memory_task_logs_six_step_durations_without_content(tmp_path) -> None:
events = [json.loads(line) for line in written.splitlines()]
steps = [event for event in events if event["event"] == "memory_task.step_completed"]
assert [event["details"]["phase"] for event in steps] == ["1", "2", "3", "4", "5", "6"]
+ finished = next(event for event in events if event["event"] == "memory_task.finished")
+ assert finished["details"] == {
+ "attempt": 1,
+ "pending_count": 0,
+ "result_count": 1,
+ }
assert tasks.processing_metrics()["hy_calls"] == 1
assert all(event["duration_ms"] >= 0 for event in steps)
assert marker not in written
diff --git a/memhub/docs/PRODUCT_LOG_TROUBLESHOOTING.md b/memhub/docs/PRODUCT_LOG_TROUBLESHOOTING.md
new file mode 100644
index 0000000..5960ff7
--- /dev/null
+++ b/memhub/docs/PRODUCT_LOG_TROUBLESHOOTING.md
@@ -0,0 +1,253 @@
+# MemHub 产品日志排查手册
+
+本文给产品、测试和一线支持同学使用。目标不是解释底层实现,而是回答三个问题:
+
+1. 数据有没有成功导入;
+2. 记忆沉淀有没有持续运行、产出了多少条;
+3. 如果停住,停在导入、模型调用还是最终写入。
+
+默认 `info` 下的结构化诊断日志不包含会话正文、模型输入输出或 API Key。`debug`
+会额外启用 HY pipeline trace,其中可能包含完整 prompt/response 和获授权的对话正文。
+排查时优先通过 App 的“导出日志”提供文件,不要直接发送整个 `~/.one-memory` 数据目录;
+debug 期间产生的 pipeline 日志在分享前必须由开发人员确认并脱敏。
+
+## 1. Log level 设什么
+
+### 日常观察:`info`
+
+`info` 是默认级别,已经包含导入数量、任务排队、模型沉淀结果、待处理数量和失败终态。
+持续观察产品是否正常工作时,不需要打开 debug。
+
+### 复现具体问题:`debug`
+
+只有开发人员明确要求跟踪一次点击、一次召回或一个具体模型任务时,才打开:
+
+> 设置 → 运行诊断 → 详细日志(排查用)
+
+开关打开后等同于 `debug`。复现完成后:
+
+1. 点击“记录问题时间点”;
+2. 点击“导出日志(发给开发排查)”;
+3. 关闭“详细日志(排查用)”。
+
+debug 可能把完整模型 prompt/response 写入本机调试日志,不得长期开启。切回 `info`
+只会停止后续正文记录,不会自动删除此前已经产生的 debug 文件。
+
+不要把日志级别设置成仅 `warning` 或 `error` 来判断系统是否健康,因为正常进度事件是
+`info`。
+
+## 2. 日志在哪里
+
+App 内推荐直接使用“运行诊断 → 导出日志”。开发人员远程指导时,优先使用
+`memhub logs`,它会再次过滤不安全字段。需要现场查看原始结构化日志时,Core 日志默认位于:
+
+```text
+~/.one-memory/logs/diagnostic-core.jsonl
+```
+
+每行都是一条 JSON。macOS 终端中可先设置:
+
+```bash
+LOG="$HOME/.one-memory/logs/diagnostic-core.jsonl"
+```
+
+## 3. 用什么 key 过滤
+
+产品排查只需要认识以下字段:
+
+- `timestamp`:发生时间;
+- `level`:`info`、`warn`、`error`;
+- `event`:事件名称,是最重要的过滤 key;
+- `outcome`:`started`、`succeeded`、`completed`、`failed` 等结果;
+- `error_code`:稳定错误码,可直接发给开发;
+- `job_id`:一次导入任务;
+- `task_id`:一次记忆沉淀任务;
+- `request_id` / `trace_id`:串联一次模型或界面请求;
+- `details.result_count`:本次沉淀最终关联了多少条记忆;
+- `details.pending_count`:完成本次任务后还有多少条待处理;
+- `details.stored_count`:本次导入新增了多少条原始消息;
+- `duration_ms`:耗时。
+
+不要按用户原话、会话内容或 API Key 搜索;这些内容按设计不会进入诊断日志。
+
+## 4. 系统正常工作时应该看到什么
+
+### A. Core 已启动
+
+```text
+event = core.ready
+outcome = succeeded
+```
+
+没有 `core.ready` 时,后面的导入和沉淀都不会运行。
+
+### B. 原始消息正在导入
+
+```text
+event = import.finished
+outcome = completed
+details.stored_count >= 0
+details.error_count = 0
+```
+
+`stored_count=0` 可能只是没有新消息;只要状态不是 failed,就不能单凭 0 判故障。
+
+### C. 记忆任务进入队列
+
+```text
+event = memory_scheduler.tasks_queued
+outcome = succeeded
+details.prepared_count > 0
+```
+
+这表示导入的数据已经进入记忆沉淀队列。
+
+### D. SDK 正在沉淀
+
+```text
+event = hy.ingest_started
+outcome = started
+```
+
+随后应出现:
+
+```text
+event = hy.ingest_completed
+outcome = succeeded
+details.result_count = 本次 SDK 返回的记忆数
+```
+
+如果有 reconcile,还会出现:
+
+```text
+event = hy.reconcile.completed
+details.created_count
+details.updated_count
+details.superseded_count
+details.deleted_count
+```
+
+### E. MemHub 已完成本次沉淀
+
+最适合产品观察的是:
+
+```text
+event = memory_task.finished
+outcome = completed
+details.result_count = 本任务最终写入或关联的记忆数
+details.pending_count = 剩余待处理任务数
+details.attempt = 第几次尝试
+```
+
+健康表现是:
+
+- `memory_task.finished` 持续出现;
+- `pending_count` 总体下降,或在持续导入时保持动态变化;
+- `result_count` 间歇性大于 0;
+- 没有持续重复的同一 `error_code`。
+
+`result_count=0` 并不一定是故障。某段对话没有值得长期保存的信息时,0 是正常结果。只有大量
+任务连续为 0,同时存在 `hy.ingest_failed`、`memory_task.failed` 或积压只增不减,才需要升级
+排查。
+
+## 5. 可复制的过滤命令
+
+优先使用以下安全读取命令:
+
+```bash
+memhub logs --since 2h --event memory_task.finished --json
+memhub logs --since 2h --event hy.reconcile.completed --json
+memhub logs --since 24h --errors-only --tail 500 --json
+memhub status --json
+```
+
+以下 `jq` 命令仅用于 `diagnostic-core.jsonl`,不要对 `core.log`、`service.log` 或 debug
+pipeline 日志直接运行后把完整输出发给他人。
+
+### 查看最近的失败
+
+```bash
+jq -r '
+ select(.level == "error" or .outcome == "failed") |
+ [.timestamp, .service, .event, (.error_code // "-"), (.task_id // .job_id // "-")] |
+ @tsv
+' "$LOG"
+```
+
+### 查看每次沉淀数量和剩余积压
+
+```bash
+jq -r '
+ select(.event == "memory_task.finished") |
+ [.timestamp, .outcome, (.details.result_count // 0),
+ (.details.pending_count // 0), (.details.attempt // 0), (.error_code // "-")] |
+ @tsv
+' "$LOG"
+```
+
+输出列依次是:
+
+```text
+时间 结果 本次记忆数 剩余待处理数 尝试次数 错误码
+```
+
+### 统计当前日志里累计完成和累计记忆数
+
+```bash
+jq -s '
+ [.[] | select(.event == "memory_task.finished" and .outcome == "completed")] |
+ {
+ completed_tasks: length,
+ memory_results: (map(.details.result_count // 0) | add // 0),
+ latest_pending: (last.details.pending_count // 0)
+ }
+' "$LOG"
+```
+
+这里的 `memory_results` 是任务结果数量之和,用于判断流水线是否持续产出;它不是当前记忆库
+去重后的总行数。
+
+### 查看导入数量
+
+```bash
+jq -r '
+ select(.event == "import.finished") |
+ [.timestamp, .details.source_id, .outcome,
+ (.details.stored_count // 0), (.details.revised_count // 0),
+ (.details.skipped_count // 0), (.details.error_count // 0)] |
+ @tsv
+' "$LOG"
+```
+
+### 跟踪一个具体任务
+
+先从失败或完成日志复制 `task_id`:
+
+```bash
+TASK_ID="粘贴-task_id"
+jq --arg id "$TASK_ID" 'select(.task_id == $id)' "$LOG"
+```
+
+## 6. 常见停点怎么判断
+
+- 有 `core.ready`,没有 `import.finished`:来源未授权、未开启同步,或来源读取失败。
+- `import.finished` 正常,没有 `memory_scheduler.tasks_queued`:导入内容尚未形成完整会话,或未进入处理窗口。
+- 有 `memory_task.started`,没有 `hy.ingest_completed`:重点查模型配置、余额、网络、超时和 `hy.ingest_failed`。
+- 有 `hy.ingest_completed`,但 `memory_task.finished` 失败:重点查最终治理写入和对应 `error_code`。
+- `pending_count` 长时间完全不下降:查看是否反复出现同一个错误码,或任务都在
+ `waiting_for_model`。
+- 导入数量持续增加、沉淀任务完全没有出现:这是异常,不应解释为“对话没有记忆价值”。
+
+## 7. 产品反馈给开发时提供什么
+
+请提供:
+
+1. 问题发生的大致时间;
+2. App 版本和平台;
+3. 是否开启了详细日志;
+4. 点击“记录问题时间点”后显示的结果;
+5. 通过“导出日志”得到的诊断文件;
+6. 最近重复出现的 `error_code`;
+7. `memory_task.finished` 最近几行中的 `result_count` 和 `pending_count`。
+
+不要提供 API Key,也不要打包发送整个记忆数据库。
diff --git a/memhub/docs/contracts/diagnostic-logging.md b/memhub/docs/contracts/diagnostic-logging.md
index 3b7bd01..cbc023d 100644
--- a/memhub/docs/contracts/diagnostic-logging.md
+++ b/memhub/docs/contracts/diagnostic-logging.md
@@ -44,6 +44,16 @@ host-bridge、desktop 和 cli。单文件 4 MiB,保留 3 份轮转;额外清
权限与安装操作、关键 IPC、失败分类、重试、耗时和终态。不记录无变化的高频轮询或逐条原文,
导入使用阶段和计数汇总,避免日志反过来造成性能问题。
+产品进度判断使用以下稳定事件:
+
+- `import.finished`:`stored_count`、`revised_count`、`skipped_count`、`error_count`;
+- `hy.ingest.completed`:SDK 本次返回的 `result_count`;
+- `hy.reconcile.completed`:新增、更新、取代和删除数量;
+- `memory_task.finished`:最终 `result_count`、剩余 `pending_count` 和 `attempt`。
+
+其中 `memory_task.finished` 是产品侧判断沉淀是否持续推进的最终事件;不能只用
+`hy.ingest.completed` 代替,因为后者早于 Governance 写入。
+
## 验收
隐私测试必须先植入一条可检测的秘密作为正向对照,再证明真实链路日志和导出均不含该秘密。