# Knowledge Session State And Context

> 覆盖会话状态所有权、持久事件、读侧投影、历史分叉/回退、活动轮次恢复及模型上下文压缩。 适用于修改 Session 生命周期、JSONL/CQRS、resume/fork/rewind、steering、Token 预算或项目记忆。 不含 Agent 决策循环（见 ../agent-execution-and-orchestration/）和工具执行机制（见 ../tool-and-automation-platform/）。 关键词：SessionRuntime, SessionService, PersistentStore, SessionEventLog, JSONL, CQRS, compaction, rewind, steering。

- Skill: `echovic/knowledge-session-state-and-context` (Agent Skill)
- Install (CLI): `npx skillmds@latest add echovic/knowledge-session-state-and-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/echovic/knowledge-session-state-and-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: echovic (https://skillmd.com/u/echovic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/echovic/knowledge-session-state-and-context

---


## Module Structure

该域负责把一次会话的权威事实、活动运行时与各端读模型分开：持久事实进入 JSONL，运行时持有互斥与恢复状态，TUI/Web/ACP 从相同事实投影，模型上下文则可在不破坏完整历史的前提下压缩。

### Directory Layout
- `packages/cli/src/context/`：事件模型、持久存储、上下文组装、压缩与 Token 预算
- `packages/cli/src/agent/runtime/`：Session 所有权、活动轮次 mailbox、恢复和私有 artifact
- `packages/cli/src/services/SessionService.ts`：会话目录、加载、分叉、回退、归档与导出编排
- `packages/cli/src/services/SessionInteractionService.ts`：持久交互请求、响应和崩溃恢复
- `packages/cli/src/memory/`：跨会话项目记忆与压缩后巩固

### Key Entry Points
- `SessionRuntime.initialize()` in `packages/cli/src/agent/runtime/SessionRuntime.ts`：获取会话所有权并执行恢复
- `PersistentStore` in `packages/cli/src/context/storage/PersistentStore.ts`：将领域动作转换为有序事件
- `SessionService` in `packages/cli/src/services/SessionService.ts`：面向 CLI、Web 与 ACP 的持久会话服务
- `CompactionService.compact()` in `packages/cli/src/context/CompactionService.ts`：生成并约束模型可见替换上下文

## Gotchas
- `sessionId` 不是全局身份；省略 `projectPath` 的查找可能因多个工作区同名而拒绝，跨端路由必须保持 `sessionId + canonical projectPath` 复合身份 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/server/sessionRef.ts`)
- Runtime、TUI store、Web store 和 SQLite 都不是持久真相，修复恢复问题时必须从 materialized JSONL 重新推导，不能把某个内存快照写回当作权威 (`packages/cli/src/context/storage/PersistentStore.ts`, `packages/cli/src/context/storage/sqlite/projection.ts`)
- rewind 与 compaction 都保留原始 transcript：前者通过 `session_rewound` 改变有效事件，后者通过 replacement checkpoint 改变模型可见上下文；直接截断 JSONL 会同时破坏审计、导出和断点续传 (`packages/cli/src/services/sessionRewind.ts`, `packages/cli/src/services/SessionService.ts`)
- durable inbox、prompt artifact 等 sidecar 不是独立会话真相；它们必须通过 transcript 中的 acknowledgement、message metadata 或生命周期事件对账后才能删除或重放 (`packages/cli/src/agent/runtime/DurableSteeringInbox.ts`, `packages/cli/src/agent/runtime/UserPromptArtifactStore.ts`)
- 会话恢复必须先取得 `SessionLease` 再修复 orphan 进程、工具调用和 turn；颠倒顺序会让两个进程同时“恢复”同一条父链 (`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/agent/runtime/SessionLease.ts`, `git:46145c53`)

## Architecture
- 写路径为 `SessionRuntime/SessionService -> ContextManager/PersistentStore -> SessionEventLog -> JSONLStore`，事件落盘并取得 seq 后才允许发布给各 surface (`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/context/ContextManager.ts`, `packages/cli/src/context/events/SessionEventLog.ts`)
- 读路径有三种不同投影：完整可见历史供 UI/导出，replacement checkpoint 之后的上下文供模型，SQLite materialization 供目录与搜索；三者不能互相替代 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/context/storage/sqlite/projection.ts`)
- 活动轮次采用“双账本”恢复：inbox 保存尚未确认的输入，JSONL 保存 turn/tool/interaction 事实；启动时通过 message ID 和终态 receipt 对账形成 exactly-once continuation (`packages/cli/src/agent/runtime/DurableSteeringInbox.ts`, `packages/cli/src/context/storage/PersistentStore.ts`)
- 跨端一致性依赖同一事件语义而非同一 UI reducer：TUI 使用共享 conversation reducer，Web 消费 SSE 投影，ACP 消费顺序化 update，但都以已提交 JSONL 生命周期为恢复边界 (`packages/cli/src/store/slices/sessionSlice.ts`, `packages/cli/web/src/store/session/handlers/eventHandlers.ts`, `packages/cli/src/acp/Session.ts`)

## Decisions
- 项目从多套 surface 事件系统收敛为 append-only committed events 加 ephemeral deltas，以换取可重放、可断点续传和持久化先于可见性的统一契约 (`packages/cli/src/context/events/SessionEventLog.ts`, `git:c776d496`)
- SQLite 被刻意定义为可删除、可重建、失败开放的读缓存，而不是第二写模型，因此绕过 event log 的历史写入仍能被拉取式同步捕获 (`packages/cli/src/context/storage/sqlite/projection.ts`, `git:1f856671`)
- ContextManager 已从状态容器收缩为 PersistentStore 的薄门面，压缩、过滤和记忆均由独立服务拥有，新增上下文行为不应重新塞回 ContextManager (`packages/cli/src/context/ContextManager.ts`, `git:a074815b`)

## Conventions
- 需要“只允许一个胜者”的生命周期转换使用 `commitValidated` 或 `commitValidatedBatch`，在同一 per-file 队列内读取最新事实、校验并追加 (`packages/cli/src/context/events/SessionEventLog.ts`, `packages/cli/src/context/storage/JSONLStore.ts`)
- 所有恢复与目录聚合先调用 `materializeSessionEvents()`，确保历史中的多次 rewind 按顺序生效后再计算 turn、interaction、搜索或 metadata (`packages/cli/src/services/sessionRewind.ts`, `packages/cli/src/services/SessionService.ts`)
- UI 可见性、模型可见性和持久性是三个独立维度；例如 token handoff 可持久但不对客户端广播，delta 可广播但不持久 (`packages/cli/src/context/TokenBudgetHandoff.ts`, `packages/cli/src/context/events/SessionEventLog.ts`)

## Child Knowledge Nodes
- `./durable-transcript-and-event-projection/SKILL.md`：修改 JSONL 提交、seq、replay、SQLite 或 TUI/Web 事件投影时进入
- `./session-catalog-fork-rewind-and-export/SKILL.md`：修改目录分页、归档、恢复、分叉、回退、搜索或 Markdown 导出时进入
- `./active-turn-interactions-and-recovery/SKILL.md`：修改 turn 互斥、steering、持久交互、崩溃恢复、旁路问答或用户 Shell 时进入
- `./context-compaction-token-budget-and-memory/SKILL.md`：修改上下文组装、压缩策略、Token handoff、工具结果预算或 Auto Memory 时进入