# agentmd 自动日志与上下文注入

> 把每轮做了什么写进 markdown 日志，并在会话开始时把日志注入上下文。

## agentmd 自动日志

会话从 `running` 转 `idle` 时，插件会：

1. 从**该会话的事件流**里取本轮的用户消息与最终回复
   （只取 `source.kind === 'user'` 的真人输入，跳过 `agent.inject()` 注入的内容）；
2. 拼成 `用户消息 → 最终回复`，按 `agentmdSummaryChars` 截断；
3. 追加到 `<agentmdDir>/<agentmdMainFile>` 中「## 四、操作日志」表格的**最后一条数据行之后**；
4. 同步刷新文件头部「最后更新：」那一行的日期。

生成的行形如：

```
| 2026-09-30 02:04 | 真实链路验证 → 链路验证完成 | 完成 |
```

**容错**：`agentmdDir` 未配置 / 目录不存在 / 文件不存在 / 找不到日志表头 —— 一律只写
`[remote-qqbot]` 日志后跳过，绝不抛错、绝不影响 agent 主流程。

**并发安全**：同一进程内对同一文件的读改写走模块级 promise 队列串行化，
多个 agent 同时转 idle 也不会破坏表格。

## 会话上下文注入

`agentmdInject: true` 时，每个新会话在 `agent/created` 时注册一条
`systemPrompt.context`（名称 `remote-qqbot:agentmd`，`order: 150`）：

- 注册在 **`agent.ctx`** 作用域上，只影响该 agent，插件卸载时自动回收；
- `text` 是**函数**，每次组装 system prompt 都重新读盘 —— 外部编辑 `main.md`
  后，下一个模型步骤即生效，无需重启；
- 文件不存在时返回空串，该条上下文自动消失；
- `systemPrompt` 服务不可用（如 headless 装配）时只记日志并降级到 `agentmd_read` 工具。

### 🔴 注入是**有界**的（防爆上下文，1.0.2 起）

`text` 是每步重读盘的函数，所以「文件多大 = 每步 prompt 多大」。文档一旦被写到几十万字符，
上游会直接回 `413`，而且**每多贴一段就更糟**。所以注入前先过 `buildContextDoc()` 压缩：

- **硬上限** `agentmdInjectMaxChars`（默认 `8000`）：返回值**永不超过**这个字符数（有单测钉死）；
- 先保**最近的日志行**（`agentmdInjectTailRows`，默认 20 行）+ §四 小节，再拿剩余预算保开头正文；
- 压缩**绝不静默**：正文里明写 `…（此处省略约 N 个字符。需要完整内容请用 agentmd_read 工具读全文）…`
  —— 否则模型会把「没看到」当成「不存在」；
- 三个键都做了兜底：给 `0` / 负数 / `NaN` 一律回落出厂默认，**不会**被解释成「不限」。

追加方向也封了顶：单条日志行超过 `agentmdRowMaxChars`（默认 `600`）时只裁「操作」列，
时间列与三列结构保持完整 —— 免得一条超长日志把表格撑变形、越积越大。

> 实测（`tests/plugin.test.mjs`）：244,582 字符的文档经真实 provider 注入 **7,994 字符**；
> 把上限改成 1500 后注入 722 字符 —— 上限真的在起作用，不是写了不读。

---

[← 回到 README](../README.md)