Skip to content

context.md

Latest commit

 

History

History
230 lines (181 loc) · 7.76 KB

context.md

File metadata and controls

230 lines (181 loc) · 7.76 KB
Raw

上下文组装结果模型 (core/models/context.py) (v2.0)

本文档详细说明上下文组装结果模型中所有数据结构的字段含义、类型、读写角色、生命周期及设计考量。

v2.0 新增来源

来源 对应内容 zone 默认值
MEMORY_INDEX MEMORY.md 轻量索引（autoDream 产物） dynamic
SESSION_MEMORY 今日会话记忆（session/{date}.md） dynamic
TOOL_CACHE_PLACEHOLDER JSON 占位符工具结果 dynamic

设计理念

  • 压缩骨架：7 层渐进式压缩（FROZEN → TRIMMED → SUMMARIZED → CONSOLIDATED）
  • DYNAMIC_BOUNDARY：保护区（system_prompt + CHACHA.md + USER_MEMORY.md + CHACHA_MEMORY.md + skills）永不被截断
  • v2.1 双层永久记忆：USER_MEMORY.md（用户级跨项目）+ CHACHA_MEMORY.md（项目级），均在保护区，永不压缩、永不删除
  • v2.0 两阶段工具缓存：Stage 1 Dispatcher → Stage 2 Compressor

1. 来源分类：BlockSource

class BlockSource(str, Enum):
    SYSTEM_PROMPT = "system_prompt"            # 系统提示词
    STATIC_RULE = "static_rule"               # CHACHA.md 静态规范
    MEMORY = "memory"                         # MEMORY.md 记忆 / CHACHA_MEMORY.md 永久记忆
    HISTORY = "history"                       # 对话历史
    TOOL_RESULT = "tool_result"               # 工具执行结果
    SKILL = "skill"                           # 技能定义
    ADDITIONAL_CONTEXT = "additional_context"  # 钩子注入
来源 对应内容 zone 默认值 可缓存
SYSTEM_PROMPT 系统级指令 protected ✅ TTL 600s
STATIC_RULE 分层 CHACHA.md protected ✅ TTL 600s
MEMORY (global) USER_MEMORY.md 用户级永久记忆（跨项目） protected ✅ TTL 300s
MEMORY (permanent) CHACHA_MEMORY.md 项目永久记忆 protected ✅ TTL 300s
SKILL 技能定义、工具 schema protected ✅ TTL 1200s
MEMORY (index) MEMORY.md 轻量索引 dynamic ❌
MEMORY (session) 今日会话记忆 dynamic ❌
HISTORY 用户消息、助手回复 dynamic ❌
TOOL_RESULT 工具执行输出（可能为 JSON 占位符） dynamic ❌
RAG_RESULT Code-RAG 检索结果 dynamic ✅ TTL 120s
SUBAGENT_RESULT 子Agent 任务完成报告 dynamic ❌
ADDITIONAL_CONTEXT 钩子注入 dynamic ❌

2. 渐进式压缩层级：CompressionLevel

层级 触发 pressure LLM 成本 做法 典型压缩率
NONE < 0.5 — 原始内容 0%
FROZEN 0.5~0.7 零 Stage 2: JSON key 最小化 + 150字符摘要 90%+
TRIMMED 0.7~0.85 零 历史消息首尾裁剪 30-60%
SUMMARIZED 0.85~0.95 一次 LLM 摘要保留语义 70-90%
CONSOLIDATED > 0.95 一次 多条相关块合并为一条 85%+

3. v2.1 上下文字段顺序

protected zone:
  0. SYSTEM_PROMPT
  1. CHACHA.md (STATIC_RULE)
  2. USER_MEMORY.md（用户级永久记忆，跨项目）
  3. CHACHA_MEMORY.md (MEMORY, 项目永久记忆)
  4. SKILL

dynamic zone:
  10. MEMORY.md 索引
  11. 今日会话记忆
  20+. 对话历史
  30+. 工具结果（含 JSON 占位符）
  40+. RAG / SubAgent
  50+. 钩子注入

4. 典型压缩决策流程

ContextManager 产出 AssembledContext(blocks=25, total_tokens=120000)
        │
        ▼
读取 meta.utilization_ratio → 0.94（>0.8 触发线）
        │
        ├─ needs_compression = True
        ├─ recommended_level = TRIMMED
        │
        ▼
ContextCompressor 按策略执行：
        │
        ├─ 1. 保护区 BLOCK 跳过
        ├─ 2. Stage 2 FROZEN: JSON 占位符 → {"t","s","p"} 最小化
        ├─ 3. Stage 2 FROZEN: 完整结果 → 150字符摘要
        ├─ 4. TRIMMED: 旧历史消息裁剪
        └─ 5. total_tokens 回到安全区

5. ContextManager 使用示例

core/context_manager.py 是上下文组装的核心入口，负责将对话状态、记忆、规则、钩子注入组装为 AssembledContext。

基本初始化

from core.context_manager import ContextManager
from core.models.config import ContextConfig

# 使用默认配置（max_tokens=1048576, trigger_ratio=0.8）
mgr = ContextManager()

# 或自定义配置
mgr = ContextManager(ContextConfig(
    max_tokens=200_000,
    compression_trigger_ratio=0.75,
    enable_summarization=True,
))

注入各类内容

# —— protected zone（永不截断）——
mgr.set_system_prompt("你是 ChachaAgent...")
mgr.set_static_rules(chacha_md_content)           # CHACHA.md 宪法
mgr.set_global_permanent_memory(user_memory)       # ~/.chacha/USER_MEMORY.md
mgr.set_permanent_memory(project_permanent_memory) # CHACHA_MEMORY.md
mgr.set_skills(tool_schemas)                       # 工具/技能定义

# —— dynamic zone（可压缩）——
mgr.set_memory_index(memory_md_content)           # MEMORY.md 轻量索引
mgr.set_session_memory(today_session_text)         # 今日会话记忆

组装上下文

from core.models.session import ConversationState

state = ConversationState()  # 从对话历史构建

ctx = mgr.assemble(
    state=state,
    session_id="abc-123",
    static_rules=None,           # None → 使用已注入的
    skills=None,
    memory_content=None,
    additional_contexts=None,    # 钩子注入的额外 ContextBlock
)

# 检查压缩状态
print(f"Token: {ctx.meta.total_tokens}/{ctx.meta.budget_per_request}")
print(f"利用率: {ctx.meta.utilization_ratio:.1%}")
print(f"需压缩: {ctx.needs_compression}")
print(f"推荐级别: {ctx.recommended_level}")

# 转为 OpenAI 消息格式
messages = ContextManager.blocks_to_messages(ctx)

完整示例：从零构建一次 LLM 调用

from core.context_manager import ContextManager
from core.models.config import ContextConfig
from core.models.session import ConversationState, MessageEvent

# 1. 初始化
mgr = ContextManager(ContextConfig(max_tokens=500_000, compression_trigger_ratio=0.8))
mgr.set_system_prompt("你是 ChachaAgent，一个 AI 助手。")
mgr.set_static_rules("--- 项目宪法 ---\n- 代码风格: PEP 8")
mgr.set_permanent_memory("### 关键决策\n- 使用 SQLite 数据库")
mgr.set_memory_index("### 用户偏好\n- 偏好简洁回复")

# 2. 构建对话状态
state = ConversationState()
state.add_event(MessageEvent(source="user", role="user", content="帮我写一个 hello world"))

# 3. 组装
ctx = mgr.assemble(state, session_id="demo-1")
messages = ContextManager.blocks_to_messages(ctx)

# 4. 发送给 LLM Invoker
# response = await invoker.invoke(messages=messages, session_id="demo-1")

build_system_prompt() 静态方法

快速加载项目的所有静态上下文，不经过完整的 assemble 流程：

from core.context_manager import ContextManager
from core.context.memory_manager import MemoryManager

system_prompt = ContextManager.build_system_prompt(
    project_root="/path/to/project",
    base_prompt="你是 ChachaAgent...",
    memory_manager=MemoryManager(project_root="/path/to/project"),
)

# 返回的 system_prompt 包含：
# 1. base_prompt
# 2. ~/.chacha/CHACHA.md（用户级宪法）
# 3. {project_root}/CHACHA.md（项目级宪法）
# 4. CHACHA_MEMORY.md（项目永久记忆）
# 5. MEMORY.md（轻量索引）

消息格式互转

# AssembledContext → OpenAI 消息列表
messages = ContextManager.blocks_to_messages(ctx)

# OpenAI 消息列表 → ConversationState（用于恢复对话）
state = ContextManager.messages_to_state(
    messages,
    session_id="restored-session",
    project_id="my-project",
)