AgentKV-OS Development Plan

目标：把 planb.md 与 14_Viper_MemOS_Plan.md 合并成可执行的工程开发文档。
当前阶段：本地开发启动。
主线项目名：AgentKV-OS。
外部 workload：../viper。
主实验后端：vLLM OpenAI-compatible API。

1. 核心定位

AgentKV-OS 不做普通 Agent 记忆系统，而做 Agent Context Virtual Memory：

把长生命周期 Agent 的上下文、工具结果、分支状态抽象成可管理的虚拟内存对象，并通过 KV-aware 的物化、复用、淘汰与按需加载策略，控制哪些状态真正进入 vLLM KV Cache。

必须始终围绕一个问题开发：

哪些 Agent 状态应该进入 prompt/KV，哪些应该留在对象存储中，哪些应该被摘要，哪些应该被复用，哪些应该被淘汰？

2. 工程边界

2.1 本仓库负责

AgentKV-OS 核心内存管理模块。
Context DAG、Tool Result VM、Branch COW、KV-aware Prompt Materializer。
benchmark runner、metrics、trace logger、report generator。
AutoDL 部署脚本。
openEuler 适配文档和脚本。
最终技术报告、测试报告、答辩材料数据来源。

2.2 本仓库暂不负责

复制或重写 viper。
第一阶段大改 vLLM 内核。
AutoGPT 主线接入。
复杂 UI。
32B 大模型主实验。

2.3 `viper` 的定位

viper 是外部 Agent workload/benchmark substrate。第一阶段通过配置路径接入：

runtime:
  viper_path: ../viper
  llm_backend: mock

后续可升级为 Git submodule 或 adapter package，但本地开发阶段先保持简单。

3. 开发平台分工

平台	用途	必须产物
本地 Mac	核心代码、单测、mock LLM、文档	`pytest` 通过、mock benchmark 跑通
AutoDL 5090/80G 卡	vLLM、真实模型、性能实验	baseline 与 AgentKV-OS 对照结果
openEuler 容器/主机	国产 OS 适配	openEuler 复现日志与测试报告

本地第一阶段不依赖 GPU。所有核心模块必须能在 mock LLM 下测试。

4. 技术路线分层

L1: KV Pressure Control

必须完成。通过 AgentKV-OS 控制 prompt 物化内容，从源头减少 KV 压力。

目标：

大工具结果不全量进入 prompt。
失败分支不污染主上下文。
旧证据降级为 summary + handle。
prompt tokens、estimated KV bytes、TTFT、P95 latency 可观测。

L2: Prefix-aware KV Reuse

必须尽量完成。生成更适合 vLLM Automatic Prefix Caching 的 prompt layout。

固定布局：

[Stable System Prompt]
[Stable Tool Schema]
[Stable Agent Policy]
[Stable Report Schema]
[Current Task]
[Evolving Report]
[Latest Observation]
[Evidence Handles]
[Branch Delta]

要求：

stable segment 排序固定。
Context DAG node serialization 稳定。
segment hash 可复现。
prefix hash 可记录。
baseline 和 AgentKV-OS 的 cached tokens / hit tokens 可对比。

L3: Light vLLM Patch

冲奖增强项，不作为第一阶段阻塞。

目标：

每个请求携带 agent_task_id、branch_id、context_hash。
暴露 per-request prompt_tokens、cached_tokens、prefix_hash。
汇总 GPU KV usage、prefix cache hit、preemptions。
可选实现 system/tool/report prefix priority hint。

5. 代码模块规划

第一阶段采用 Python，实现路径统一放在 agentkv/。

agentkv/
  __init__.py
  types.py              # 核心数据结构
  ids.py                # 稳定 ID / hash 工具
  token_counter.py      # tokenizer 抽象与 mock counter
  context_dag.py        # Context DAG Manager
  object_store.py       # Tool Result Virtual Memory
  materializer.py       # KV-aware Prompt Materializer
  policy.py             # hot/warm/cold 与 eviction policy
  branch.py             # Branch COW Manager
  metrics.py            # metrics schema 与 JSONL trace
  manager.py            # AgentMemoryManager facade
  adapters/
    __init__.py
    viper.py            # viper 接入层
    dataframe.py        # DataFrame object adapter
    log.py              # Log object adapter
    document.py         # Document object adapter

benchmark 路径：

bench/
  tasks/
    tool_heavy_dataframe.jsonl
    long_agent_turns.jsonl
    branch_decision.jsonl
    concurrent_agents.jsonl
  runner.py
  baselines.py
  metrics.py
  report.py

脚本路径：

scripts/
  check_env.sh
  run_unit_tests.sh
  run_mock_benchmark.sh
  start_vllm.sh
  run_viper_baseline.sh
  run_agentkv_benchmark.sh

6. 核心数据结构

6.1 Context Node

@dataclass
class ContextNode:
    node_id: str
    node_type: str
    content: str | None
    content_hash: str
    parent_ids: list[str]
    token_count: int
    ref_count: int
    hotness: float
    storage_tier: str
    kv_status: str
    rebuild_cost: float
    semantic_importance: float
    created_at: float
    last_access_at: float
    metadata: dict[str, Any]

关键字段是 kv_status：

状态	含义
`not_materialized`	不进入当前 prompt/KV
`prompt_materialized`	以文本形式进入 prompt
`summary_materialized`	以摘要形式进入 prompt
`handle_materialized`	仅 handle/schema/sample 进入 prompt
`kv_reusable`	预期可通过稳定 prefix 被 vLLM 复用
`evicted`	从热上下文淘汰，只保留可恢复元数据

6.2 Object Handle

@dataclass
class ObjectHandle:
    object_id: str
    object_type: str
    raw_bytes: int
    raw_token_estimate: int
    prompt_token_estimate: int
    schema: dict[str, Any]
    sample: str
    summary: str
    storage_path: str
    content_hash: str
    created_at: float
    metadata: dict[str, Any]

6.3 Prompt Plan

@dataclass
class PromptPlan:
    task_id: str
    context_id: str
    branch_id: str | None
    messages: list[dict[str, str]]
    hot_nodes: list[str]
    warm_nodes: list[str]
    cold_handles: list[str]
    prompt_tokens: int
    estimated_kv_bytes: int
    prefix_hash: str
    compression_ratio: float
    metadata: dict[str, Any]

7. 核心接口

7.1 AgentMemoryManager

class AgentMemoryManager:
    def begin_task(self, task_id: str, user_query: str, metadata: dict) -> str: ...
    def append_agent_turn(self, task_id: str, role: str, content: str, metadata: dict) -> str: ...
    def register_tool_result(self, task_id: str, tool_name: str, raw_result: object, metadata: dict) -> ObjectHandle: ...
    def build_prompt(self, task_id: str, branch_id: str | None = None, budget_tokens: int = 8192) -> PromptPlan: ...
    def fork_branch(self, task_id: str, parent_context_id: str, metadata: dict) -> str: ...
    def merge_branch(self, task_id: str, branch_id: str, policy: str) -> str: ...
    def finalize_task(self, task_id: str, final_answer: str, metadata: dict) -> None: ...

7.2 Tool Result VM

class ToolResultVM:
    def register_object(self, raw_result: object, schema: dict, metadata: dict) -> ObjectHandle: ...
    def read_object(self, object_id: str, selector: dict) -> str: ...
    def summarize_object(self, object_id: str, budget_tokens: int) -> str: ...
    def materialize_object(self, object_id: str, mode: str) -> str: ...

7.3 Context DAG Manager

class ContextDAG:
    def add_node(self, node_type: str, content: str | None, parents: list[str], metadata: dict) -> str: ...
    def fork(self, parent_context_id: str, metadata: dict) -> str: ...
    def materialize(self, context_id: str, budget_tokens: int, policy: str) -> PromptPlan: ...
    def evict(self, policy: str) -> list[str]: ...

8. Benchmark 设计

8.1 任务类型

类型	目标	第一阶段规模
`tool_heavy_dataframe`	证明大工具结果不污染 KV	10-20 个任务
`long_agent_turns`	证明上下文增长受控	20/40/80 轮任务
`branch_decision`	证明分支 COW 和 prefix 复用	3/5 分支任务
`concurrent_agents`	证明固定显存预算下承载更多 Agent	2/4/8 并发

8.2 Baselines

至少实现以下对照：

编号	名称	说明
B0	linear-history	viper 原始线性 history
B1	vllm-apc-only	只开启 vLLM prefix cache
B2	summary-only	普通摘要压缩，无 DAG/Tool VM
B3	tool-vm-only	只开启工具结果对象化
B4	dag-no-prefix-layout	DAG 管理，但不做稳定 prefix layout
B5	agentkv-full	Tool VM + Context DAG + prefix-aware layout + Branch COW

这组 baseline 用来回答评委最可能问的问题：

是否只是摘要？
是否只是 RAG？
是否只是开启 vLLM prefix cache？
是否真的有 Agent 语义层内存管理？

8.3 指标

每个 Agent step 写 JSONL：

{
  "task_id": "task_001",
  "branch_id": "main",
  "context_id": "ctx_001",
  "strategy": "agentkv-full",
  "step": 12,
  "prompt_tokens": 7341,
  "completion_tokens": 312,
  "tool_raw_tokens": 18432,
  "tool_prompt_tokens": 612,
  "estimated_kv_bytes": 845152256,
  "ttft_ms": 842.7,
  "e2e_latency_ms": 3810.2,
  "p95_latency_ms": null,
  "gpu_memory_used_mb": 28640,
  "gpu_kv_usage_perc": 0.62,
  "prefix_queried_tokens": 6144,
  "prefix_hit_tokens": 4096,
  "object_reload_count": 1,
  "branch_shared_token_ratio": 0.78,
  "success": true
}

报告聚合指标：

task success rate
prompt token reduction
tool prompt token reduction
estimated KV byte reduction
TTFT / P50 / P95 / P99
peak GPU memory
max sustainable turns
max concurrent agents
prefix cache hit rate
branch shared token ratio

9. 开发里程碑

P0: 仓库与本地环境

周期：0.5-1 天。

任务：

初始化 Git 仓库。
固定目录结构。
本地 venv 可安装。
pytest 可运行。

交付：

README.md
pyproject.toml
docs/development_plan.md
scripts/run_unit_tests.sh

验收：

python -c "import agentkv; print(agentkv.__version__)"
python -m pytest

P1: Core Data Model + Context DAG

周期：2-3 天。

任务：

实现 types.py。
实现稳定 hash 与 node id。
实现 ContextDAG.add_node()、fork()、get_path()。
实现 token counter mock。

交付：

agentkv/types.py
agentkv/ids.py
agentkv/token_counter.py
agentkv/context_dag.py
tests/test_context_dag.py

验收：

DAG 节点可添加、查询、fork。
相同内容序列化 hash 稳定。
分支共享父节点，ref_count 正确变化。

P2: Tool Result Virtual Memory

周期：3-4 天。

任务：

实现本地 object store。
支持 text/log/dataframe 三类对象。
register 后返回 handle。
prompt 中只物化 schema/sample/summary/handle。
支持 selector 读取 evidence span。

交付：

agentkv/object_store.py
agentkv/adapters/dataframe.py
agentkv/adapters/log.py
agentkv/adapters/document.py
tests/test_object_store.py

验收：

大对象不直接进入 prompt。
raw_token_estimate 与 prompt_token_estimate 可计算。
read_object() 能返回局部证据。

P3: KV-aware Prompt Materializer

周期：3-5 天。

任务：

实现 stable prefix layout。
实现 hot/warm/cold policy。
实现 token budget。
输出 PromptPlan。
记录 prefix_hash、estimated_kv_bytes。

交付：

agentkv/policy.py
agentkv/materializer.py
agentkv/manager.py
tests/test_materializer.py

验收：

相同 system/tool/report segment 的序列化稳定。
不同分支共享相同 prefix hash。
超预算时按 policy 降级 cold/warm 节点。

P4: Mock Benchmark

周期：3-5 天。

任务：

构造本地 mock tasks。
实现 B0/B2/B3/B5 的无 GPU对照。
输出 JSONL trace 与 summary。
画出 token 曲线。

交付：

bench/runner.py
bench/baselines.py
bench/report.py
scripts/run_mock_benchmark.sh

验收：

本地一条命令跑完 mock benchmark。
能看到 tool prompt tokens 明显下降。
能看到 long turns 下 prompt tokens 增长受控。

P5: Viper Adapter

周期：1 周。

任务：

读取 ../viper 配置。
在 viper prompt 构建前接入 AgentKV-OS。
在工具执行后注册 tool result。
保留 baseline 与 AgentKV-OS 两种运行模式。

交付：

agentkv/adapters/viper.py
configs/viper.local.yaml
scripts/run_viper_baseline.sh
scripts/run_viper_agentkv.sh

验收：

viper -> AgentKV-OS -> mock LLM 跑通。
真实 vLLM 环境只需替换 base URL。

P6: AutoDL vLLM Benchmark

周期：1-2 周。

任务：

AutoDL 启动 vLLM。
Qwen2.5-7B / Coder-7B 跑通。
接入 vLLM /metrics。
跑 B0-B5。

交付：

docs/autodl_setup.md
scripts/start_vllm.sh
scripts/check_vllm_metrics.sh
results/*/summary.json

验收：

baseline vs AgentKV-OS 的 prompt tokens、TTFT、P95、显存/KV usage 有对照。
任务成功率基本不下降。

P7: Prefix-aware + Branch COW

周期：1 周。

任务：

开启 vLLM APC。
记录 prefix queried/hit tokens。
branch 任务支持 3/5 分支。
失败分支冷却，成功分支 merge。

交付：

agentkv/branch.py
bench/tasks/branch_decision.jsonl
results/branch/summary.json

验收：

branch shared token ratio 可计算。
AgentKV-OS 相比 full context branch 复制有明显 token reduction。
cached prefix tokens 有提升。

P8: openEuler 适配

周期：3-5 天。

任务：

准备 openEuler 容器。
运行 AgentKV-OS 单测。
可连接外部或容器内 vLLM。
跑一小组 benchmark。

交付：

deploy/openeuler/Containerfile
deploy/openeuler/README.md
docs/openeuler_deploy.md
docs/openeuler_test_report.md

验收：

cat /etc/os-release 显示 openEuler。
python -m pytest 通过。
benchmark smoke test 通过。

10. 第一周具体任务

当前已经完成：

新建 AgentKV-OS Git 仓库。
创建基础目录结构。
添加初始 README、pyproject、开发说明。

下一步按以下顺序执行：

新增 agentkv/types.py，定义 ContextNode、ObjectHandle、PromptPlan。
新增 agentkv/ids.py，实现稳定 JSON 序列化与 SHA256 hash。
新增 agentkv/token_counter.py，先用 mock token counter，后续替换 tokenizer。
新增 agentkv/context_dag.py，完成节点添加、父子关系、fork、ref_count。
新增 tests/test_context_dag.py。
新增 scripts/run_unit_tests.sh。
提交 P1 Context DAG foundation。

第一周最低验收：

python -m pip install -e .
python -m pytest

并能用一个 Python snippet 输出：

system -> tool_schema -> user_task -> branch_a_delta
                             └── branch_b_delta

11. Git 工作流

本地开发采用小步提交。

分支建议：

main
feature/context-dag
feature/tool-vm
feature/materializer
feature/viper-adapter
feature/benchmark
deploy/autodl
deploy/openeuler

提交粒度：

一个核心模块一个提交。
一个 benchmark baseline 一个提交。
一个可复现实验脚本一个提交。

提交信息格式：

Add Context DAG core
Add Tool Result VM local object store
Add prefix-aware prompt materializer
Add mock benchmark runner
Add AutoDL vLLM setup script

12. 编码约束

Python 作为主语言。
第一阶段不引入 C++/CUDA/Rust。
Python 版本支持 >=3.10。
数据结构优先 dataclasses，复杂校验后续再考虑 pydantic。
本地测试不依赖 GPU。
不把模型路径、AutoDL 路径、Ubuntu 路径写死。
生成数据、模型、日志、结果不入 Git。

12.1 Karpathy Guidelines

后续开发遵循 karpathy-guidelines：

Think before coding：实现前明确假设、边界和验收标准。
Simplicity first：优先最小可验证实现，不做 speculative abstraction。
Surgical changes：只改和当前任务直接相关的代码，不顺手重构无关模块。
Goal-driven execution：每个功能都必须有测试、脚本或指标验证。

实际执行方式：

1. State assumptions
2. Define success criteria
3. Implement the smallest useful change
4. Run verification
5. Commit the verified change

13. 风险控制

风险	应对
做成普通 prompt compression	所有文档和代码都围绕 `kv_status`、Context DAG、Tool VM、materialization
vLLM 环境拖慢开发	本地先 mock，AutoDL 后接真实 vLLM
任务成功率下降	Tool VM 保留 schema/sample/summary，并支持 read_object 按需读取
指标不可解释	每个 Agent step 写 JSONL trace，报告从 trace 自动生成
只像开了 prefix cache	设置 B1 vLLm-apc-only baseline，证明 AgentKV-OS layout 的额外收益
国产 OS 最后补不上	P8 只要求 openEuler smoke + benchmark small set，尽早建脚本

14. 冲奖判断标准

进入中后期后，每个功能都要回答四个问题：

它解决了赛题 14 的哪一个内存管理问题？
它改变了哪些可观测指标？
它和 baseline 的差异是否可复现？
它是否能在答辩中用一张图讲清楚？

如果不能回答，就延后，不进入主线。

FilesExpand file tree

development_plan.md

Latest commit

History

development_plan.md

File metadata and controls

AgentKV-OS Development Plan

1. 核心定位

2. 工程边界

2.1 本仓库负责

2.2 本仓库暂不负责

2.3 viper 的定位

3. 开发平台分工

4. 技术路线分层

L1: KV Pressure Control

L2: Prefix-aware KV Reuse

L3: Light vLLM Patch

5. 代码模块规划

6. 核心数据结构

6.1 Context Node

6.2 Object Handle

6.3 Prompt Plan

7. 核心接口

7.1 AgentMemoryManager

7.2 Tool Result VM

7.3 Context DAG Manager

8. Benchmark 设计

8.1 任务类型

8.2 Baselines

8.3 指标

9. 开发里程碑

P0: 仓库与本地环境

P1: Core Data Model + Context DAG

P2: Tool Result Virtual Memory

P3: KV-aware Prompt Materializer

P4: Mock Benchmark

P5: Viper Adapter

P6: AutoDL vLLM Benchmark

P7: Prefix-aware + Branch COW

P8: openEuler 适配

10. 第一周具体任务

11. Git 工作流

12. 编码约束

12.1 Karpathy Guidelines

13. 风险控制

14. 冲奖判断标准

2.3 `viper` 的定位