AGENT SKILL

context-lifecycle

上下文生命周期管理总览:四层记忆架构(L0-L3)、任务阶段感知、 渐进压缩策略、按需召回与四分区预算模型。

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
context-lifecycle
origin
harness-engineering
description
上下文生命周期管理总览:四层记忆架构(L0-L3)、任务阶段感知、 渐进压缩策略、按需召回与四分区预算模型。

03 SKILL.md 正文

Context Lifecycle Skill

管理 Claude Code 长时多轮任务中的上下文生命周期,避免压缩导致关键细节丢失。

架构概览

┌──────────────────────────────────────────────────────┐
│                 上下文窗口 (200K tokens)                │
│                                                        │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌────────┐ │
│  │  System   │ │  Ledger  │ │  Working   │ │ Buffer │ │
│  │  (10%)    │ │  (10%)   │ │  (65%)     │ │ (15%)  │ │
│  │ protected │ │ protected│ │ 主工作区    │ │ 溢出区  │ │
│  └──────────┘ └──────────┘ └────────────┘ └────────┘ │
└──────────────────────────────────────────────────────┘
         ↕ 渐进压缩                ↕ 按需召回
┌──────────────────────────────────────────────────────┐
│  L1: 摘要 + L2 引用   →   L2: 全文归档 (索引)         │
│  (替换 L0 原文)             (~/.claude/memory/)       │
│                                                        │
│  L3: 项目记忆 (跨会话)  →  docs/memory/ + Phase Ledger │
└──────────────────────────────────────────────────────┘

四层记忆模型

层级 名称 位置 内容 生命周期
L0 工作记忆 上下文窗口 当前对话、工具结果、代码 当前会话
L1 摘要记忆 上下文窗口 (替换 L0) 压缩摘要 + L2 归档引用 当前会话
L2 详情归档 ~/.claude/memory/sessions/{sid}/ 完整原文、关键词索引 本地持久
L3 项目记忆 docs/memory/ Phase Ledger、决策日志、经验 跨会话持久

渐进压缩策略

压缩基于 Working Zone 使用率,而非整体上下文使用率:

Working 使用率 压缩级别 操作
< 60% 无 保持 L0 原文
60% L0→L1 摘要工具结果、旧对话,原文归档到 L2
75% L1→L2 摘要 L1 内容,更老的摘要归档到 L2
90% L2→L3 紧急压缩,决策提升到项目记忆

阶段感知优先级

压缩时的保留/归档决策受当前任务阶段影响:

阶段 优先保留 优先归档
Planning 需求、边界、约束 探索性讨论
Design 架构决策、接口契约 备选方案分析
Implementation 当前文件、测试结果 设计讨论
Testing 测试结果、缺陷 实现细节
Review 评审结论、修改建议 测试细节

核心组件

库模块 (scripts/lib/)

模块 职责
phase_tracker.py 任务阶段状态机,多信号检测(命令 / handoff / 工具启发)
phase_ledger.py 阶段交接账页,在阶段切换时生成结构化 Markdown
context_budget.py 四分区预算模型,Zone-aware 压缩级别判定
context_archiver.py L2 归档写入、关键词索引、去重、批量归档
context_recall.py 按需召回:关键词 / 阶段 / 类型 / 决策多维检索
context_priority.py 上下文元素优先级评分(已有)

Hooks (scripts/hooks/)

Hook 触发点 作用
session_start.py 会话开始 加载 Phase Timeline、未解决项、决策摘要
pre_compact.py 压缩前 分类元素为 keep/summarize/archive/discard
suggest_compact.py 压缩建议 根据 Working Zone 使用率推荐渐进压缩策略

Skills (skills/)

Skill 用途
context-recall /recall 命令,按需从 L2 归档和 Phase Ledger 检索
context-lifecycle 本文档,整体架构说明
strategic-compact 已有的 trigger-based 上下文重组能力

数据流

写入路径

对话/工具结果 (L0)
    ↓ Working Zone > 60%
pre_compact → categorize as "archive"
    ↓
context_archiver.archive_and_index()
    ├── 写入 L2 文件: ~/.claude/memory/sessions/{sid}/archived/{hash}.md
    ├── 更新索引: ~/.claude/memory/sessions/{sid}/index.json
    └── 返回 L1 摘要 (替换上下文中的原文)
    
阶段切换时
    ↓
phase_ledger.generate_ledger() + save_ledger()
    ├── 写入 L3: docs/memory/sessions/{sid}/phase-{N}-{name}.md
    └── 更新索引: /tmp/harness-phase-ledger-{sid}.json

读取路径

会话启动
    ↓
session_start → get_recall_context_for_session_start()
    ├── 读取 Phase Ledger 索引 → phase_timeline
    ├── 统计未解决项 → pending_items
    └── 统计决策数 → recall_hint

用户请求 /recall
    ↓
context_recall → recall_by_keyword/phase/type/decisions()
    ├── 搜索 L2 索引 (index.json)
    ├── 加载 L2 完整内容
    └── 搜索 Phase Ledger

使用指南

自动行为(无需干预)

  1. 会话启动自动加载 Phase Timeline 和未解决项
  2. 压缩时自动按阶段优先级归档而非丢弃
  3. 阶段切换时自动生成 Phase Ledger

手动操作

  1. /recall keyword — 从归档中按关键词搜索
  2. /recall phase:design — 查看 design 阶段的完整交接记录
  3. /recall decisions — 查看所有决策链路
  4. /recall timeline — 查看阶段时间线

与现有能力的协同

  • strategic-compact: 本系统的 L0→L1 压缩替代了 strategic-compact 的全量压缩,两者可共存
  • error-experience-library: 错误经验在 L3 层跨会话持久保存
  • continuous-learning: instinct 产物不受压缩影响,已在 L3 层

配置

可通过环境变量或 hooks.json 参数调整:

参数 默认值 说明
Zone ratios 10/10/65/15 System/Ledger/Working/Buffer 分区比例
L0→L1 threshold 60% Working Zone 使用率触发 L0→L1
L1→L2 threshold 75% Working Zone 使用率触发 L1→L2
L2→L3 threshold 90% Working Zone 使用率触发 L2→L3

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k