Decepticon 上下文工程实战指南:Red Team Agent 的有限上下文预算管理架构

原创2026-10-13 21:42:241,618 阅读

Decepticon 上下文工程实战指南:Red Team Agent 的有限上下文预算管理架构

Decepticon 是一个面向 Red Team 的自主黑客 Agent 框架(Autonomous Hacking Agent for Red Team)。本文以其 上下文工程架构设计文档 为骨架,结合仓库源码,系统讲解 recon Agent 在长会话中如何管理有限的上下文窗口:从「上下文是有限资源」这一核心设计原则出发,覆盖 Progressive Disclosure 知识分层、Observation Masking 观测遮蔽、Filesystem as Scratch Pad 文件暂存、KV-Cache 前缀缓存优化、/compact 手动压缩、工具描述设计与错误自愈、内存架构与 Skills 系统等完整链路。读完本文,你将掌握 Decepticon 中「tokens-per-task(每个任务完成的 token 总量)」视角的上下文工程方法论,以及每一层策略在 sandbox_kernel/tmux.py、tools/bash/bash.py、middleware/context_engineering.py 中的真实实现细节。

1. 设计原则:上下文工程的第一性原理

1.1 上下文是有限资源

Red Team recon(侦察)Agent 的典型工作负载是长时间、大输出:一次 nmap 扫描、DNS 记录批量查询、子域名枚举产生的 tool output 动辄数万字符。设计文档给出了一个关键判断:这类输出可能占据上下文窗口的 80% 以上,随着会话推进,Agent 的推理能力会因上下文被低信息密度内容占满而逐步退化。

因此 Decepticon 的核心优化指标不是「每次请求消耗的 token」,而是 tokens-per-task——完成一个完整任务(而非单次请求)所需的总 token 数。这个指标把所有「重复读取大输出」「把大输出留在上下文里反复参与注意力计算」「压缩后重新请求」的成本全部纳入考量,是整个上下文工程体系的设计目标函数。

1.2 Progressive Disclosure(渐进式披露)

「不要把所有知识一次性塞进系统提示词」是 Decepticon 的第一条组织原则。上下文被划分为两个层次:

  • 静态上下文(Static Context):系统提示词(persona、核心规则、工具指南),始终加载。
  • 动态上下文(Dynamic Context):SKILL.md 技能文件,仅当 Agent 执行对应任务时才按需加载。

设计文档给出的静态/动态负载示意:

静态加载(始终):
  ├── recon.md 系统提示词 (~2K tokens)
  └── bash tool description (~500 tokens)

动态加载(按需):
  ├── /skills/passive-recon/SKILL.md   → WHOIS/DNS/子域名任务时
  ├── /skills/active-recon/SKILL.md    → nmap/服务枚举任务时
  └── /skills/reporting/SKILL.md       → 编写报告时

这一模式在当前仓库中有完整落地。技能库位于 packages/decepticon/decepticon/skills/standard/,例如 active-recon/SKILL.md 的 frontmatter 中通过 description、metadata.when_to_use 声明其适用场景,Agent 只有在任务触发对应关键词(port scan、nmap、service detection……)时才通过 load_skill() 加载完整正文。从 middleware/skills.py 的实现看,系统提示词中只注入技能目录(description + trigger 关键词 + MITRE ATT&CK 技术编号),真正的技能正文全部按需加载——这正是 Progressive Disclosure 在中间件层面的直接体现。

1.3 Attention-Favored Positioning(注意力偏好定位)

现代 LLM 对上下文开头和结尾的注意力更强(primacy/recency 效应)。Decepticon 据此设计了系统提示词的结构顺序,把「最不可违反」的规则放在开头附近,把「需要 recency bias 兜底」的安全提醒放在结尾:

系统提示词结构:
  <IDENTITY>          ← 开头:核心 persona
  <CRITICAL_RULES>    ← 开头附近:绝不可违反的规则
  <ENVIRONMENT>       ← 中间:参考信息
  <TOOL_GUIDANCE>     ← 中间:工具用法
  <RESPONSE_RULES>    ← 中间-结尾:输出格式
  <WORKFLOW>          ← 结尾附近:工作顺序
  <OPSEC_REMINDERS>   ← 结尾:安全提醒(利用 recency bias)

仓库中的 recon.md 系统提示词 正是这一结构的真实样本:<IDENTITY> 定义 RECON 角色「只记录观测、不做分类决策」的职责边界;<CRITICAL_RULES> 紧随其后,承载 OPSEC First、Observation-Only Reporting、Scope Compliance 等最高优先级规则;<ENVIRONMENT> 描述沙箱工具与工件目录;<RESPONSE_RULES> 规定结构化输出与发现分级;<SCOPE> 放在末尾作为绝对收束。

2. 上下文优化策略

2.1 Observation Masking(观测遮蔽)——两级实现

Tool output 是上下文消耗的最大来源,Decepticon 在两级进行遮蔽(masking):

Level 1 — Sandbox 截断(_truncate):设计文档以 docker_sandbox.py 为例描述,当前仓库的对应实现位于 sandbox_kernel/tmux.py 的 _truncate():

  • 常量 MAX_OUTPUT_CHARS = 30_000:超过 30,000 字符的输出被非对称截断(head 60% / tail 40%)。
  • 截断提示语会主动引导 Agent 保存完整输出:「save full output to file with -oN or redirect to a workspace file to preserve complete results」——把「保存文件」变成 Agent 的下一步动作,而不是让它反复重跑命令。

从源码看,同一文件中还定义了 SIZE_WATCHDOG_CHARS = 5_000_000 的大小看门狗:当单次命令输出超过 5M 字符时,沙箱会直接杀掉命令并返回 [SIZE LIMIT] 标记,防止失控输出打爆上下文。这构成了输出管理的最外层硬边界。

Level 2 — 自动遮蔽(Auto-Masking):设计文档描述的 StreamingEngine 会在「3 轮之前且超过 5,000 字符」的 ToolMessage 自动替换为 compact summary,保留 Preview(200 字符)与元数据(command、session),原始数据则保存在沙箱 /workspace/ 下的文件中。遮蔽后的返回形态如下:

[Observation masked — 847 lines / 42,350 chars]
Command: nmap -sS -sV --top-ports 1000 10.0.1.50
Session: scan-1
Preview: Starting Nmap 7.94SVN ( https://nmap.org ) at 2025-...
[Use bash(session="scan-1") to re-read or check /workspace/ for saved files]

值得强调的是,遮蔽发生在保留可恢复路径的前提下:Agent 仍可通过 bash(session="scan-1") 或读取 /workspace/ 下的文件找回原始数据,遮蔽只压缩「上下文里的表示」,不销毁「磁盘上的事实」。

2.2 Filesystem as Scratch Pad(文件系统即草稿纸)

这是 filesystem-context 技能的核心模式:大输出写文件,上下文只留引用。设计文档给出 recon Agent 的典型工件结构:

/workspace/                          ← Docker sandbox 内部
├── recon_<target>_passive.txt       ← 被动侦察原始输出
├── recon_<target>_subdomains.txt    ← 子域名列表
├── nmap_<target>_<type>.txt         ← nmap 结果(human-readable)
├── nmap_<target>_<type>.xml         ← nmap 结果(工具联动)
└── report_<target>_final.md         ← 最终报告

当前仓库把这一模式实现为 bash 工具的三级输出管理(tools/bash/bash.py):

输出规模 处理方式
≤ 15K 字符(INLINE_LIMIT = 15_000) 内联返回工具结果
15K – 100K 字符 写入 <engagement>/.scratch/,返回摘要
> 5M 字符 沙箱大小看门狗直接杀掉命令

OFFLOAD(卸载)路径由 _offload_large_output() 实现:完整输出通过 docker cp 写入 {workspace}/.scratch/{session}_{ts}_{cmd_hash}.txt(注意用 upload_files 而非 shell 拼接,规避输出内容引发的注入风险),随后返回 head 2K + tail 1K 的预览、行数/字符数统计、以及文件路径引用,并明确提示「use read_file or grep to search specific content」。也就是说,Agent 后续可以通过 read_file/grep 按需访问大文件的任意片段,而无需把整份输出留在上下文中。

仓库还引入了 .scratch/ 目录的 TTL 清理机制(SCRATCH_TTL_MINUTES = 60,进程级 600 秒节流),保证长时间 engagement 中 scratch 目录不会无限增长;同时定义了完整的工具状态前缀集合([BACKGROUND]、[RUNNING、[DONE、[IDLE]、[KILLED]、[STALLED]、[TIMEOUT]、[SIZE LIMIT] 等),这些状态标记属于 Agent 解析的消息而非命令输出,绝不进入 OFFLOAD 路径,避免被二次包裹。

Agent 侧的三重学习引导是让这套模式真正起效的关键:bash 工具的错误恢复文案("save full output to file with -oN")、recon 系统提示词的规则("Long-running scans, save output to files")、以及每个 SKILL.md 中命令模板自带的 -oN /workspace/ 参数。三者合力把「先落盘、再引用」内化为 Agent 的习惯动作。

2.3 KV-Cache 优化(前缀缓存友好布局)

系统提示词与工具定义在每次请求中都是完全相同的字节序列,这天然适合 provider 侧的 prompt caching(如 Anthropic 的 prompt cache)。Decepticon 的布局策略是把稳定内容前移、动态内容后置:

缓存稳定区(不变化):
  [系统提示词] [工具定义] [技能元数据]

缓存不稳定区(每轮变化):
  [消息历史] [当前请求]

这一原则在 middleware/context_engineering.py 的 build_cache_optimized_prompt() 中有精确落地:提示词按「base system prompt(稳定,可命中缓存)→ Engagement Scope(每次 engagement 半稳定)→ Loaded Skills(每 Agent 加载一次)→ Current Context(每轮动态)」的顺序拼接。同文件还提供 ModelCapabilities 做能力适配(是否支持图片、严格 JSON schema、prompt caching),以及 handle_hallucinated_tool()——当模型幻觉出不存在工具名时,返回带最近匹配建议的错误消息让 Agent 自愈,而不是直接崩溃。

3. 上下文压缩策略

即使有前两节的前置优化,长会话仍会积累大量历史消息。Decepticon 提供主动压缩与自动告警两套手段。

3.1 /compact 手动压缩命令

在 CLI 中输入 /compact 可手动触发上下文压缩:

you> /compact
Compacted 12 tool outputs (~8,500 tokens freed).

设计文档给出的压缩动作分三步:

  1. 检查最近 2 轮以外的所有 ToolMessage;
  2. 将超过 5,000 字符的输出替换为 compact summary;
  3. 通过 agent.update_state() 更新 Agent 状态。

/compact 是「把 2.1 节的 Auto-Masking 变成显式、可控、随时可触发」的用户级操作——当 Agent 会话明显变慢或开始遗忘早期发现时,这是最直接的预算回收手段。

3.2 自动警告

当会话达到 15 轮时,CLI 会显示上下文劣化警告,提醒操作者主动干预:

[Context Warning] Long conversation detected.
Use /compact to free context budget or /clear to start fresh.

/clear 是另一种重置手段:生成新的 thread_id(见 5.3 节),彻底清空消息历史,代价是丢失会话内记忆——这也是「先 /compact、后 /clear」的告警文案排序逻辑。

3.3 Anchored Iterative Summarization(锚定迭代摘要,规划中)

设计文档将结构化摘要策略列为未来实现项。其核心思想是:摘要不能是自由文本流水账,而必须锚定在可追踪的结构上,尤其是 artifact trail(工件轨迹)——哪些文件写了、写在哪,必须在压缩后仍然明确,否则后续阶段会丢失证据链。规划中的摘要模板:

## Session Intent
[用户想要达成的目标]

## Targets Discovered
- example.com → 93.184.216.34 (Cloudflare CDN)
- api.example.com → 10.0.1.50 (直接暴露)

## Scans Completed
- Passive recon: WHOIS, DNS, subfinder, CT logs ✓
- Active recon: nmap top-1000 on api.example.com ✓
- UDP scan: pending

## High Priority Findings
1. [CRITICAL] MySQL 3306 exposed on api.example.com
2. [HIGH] Dangling CNAME: staging.example.com

## Files in /workspace/
- nmap_api_10.0.1.50_syn.txt (端口扫描结果)
- subdomains.txt (47 个子域名)
- report_example.com_final.md (进行中)

## Next Steps
1. 执行 UDP 扫描
2. 完成最终报告

注意该结构中的「Files in /workspace/」一节:它把 2.2 节的文件系统模式显式接入压缩流程,确保压缩时上下文里消失的是「输出正文」,而不是「输出存在哪里」这个关键索引。

4. 工具设计原则

工具 description 是 Agent 决定「何时用什么工具」的唯一依据,Decepticon 用一套结构化的回答模板约束它。

4.1 What/When/Returns 模式

每个工具 description 必须回答 4 个问题,以 bash 工具为例:

问题 bash 工具示例
WHAT(做什么) 在 Docker sandbox 中执行 bash 命令
WHEN(何时用) 运行 recon 工具、操作文件、安装包、检查运行状态
RETURNS(返回什么) stdout、[STALLED]、[TIMEOUT]、[IDLE]、[RUNNING]
ERROR RECOVERY(出错怎么办) [STALLED] → wait/kill;[TIMEOUT] → 稍后查询;not found → apt install

仓库中 tools/bash/prompt.py 的 <BASH_TOOLS> 提示词块正是该模式的生产实现:它不仅用参数表(command/description/session/background/timeout/is_input)逐一说明 WHAT 与 WHEN,还强制要求每次调用携带 description 参数(「一句话说明做什么、为什么」),该描述同时驱动操作者 UI 的 "Run " 展示行——工具设计同时服务于 LLM 与人类操作员两个读者。

4.2 Consolidation Principle(工具合并原则)

工具数量最小化。设计文档强调当前 recon Agent 仅使用 1 个自定义工具(bash),符合 architectural reduction 原则:

  • 单个 bash() 即可覆盖全部 recon 工具(nmap、dig、curl 等);
  • 文件操作交给 deepagents 内置工具(ls、read_file、write_file、grep、glob);
  • 不写薄包装器,把「用哪个外部工具、怎么组合」完全交给 Agent 的推理能力。

从当前仓库结构看,这一原则被继承并扩展:各角色 Agent 的工具集通过 build_tools(role=...) 按角色装配,而 bash 工具本身由 sandbox_kernel/tmux.py 的 execute_tmux() 提供持久 tmux 会话支撑(详见 7 节数据流),工具数量控制在角色所需的最小集合。

4.3 错误消息 → 自愈设计

错误消息必须让 Agent 能够自我恢复,而不是死路一条:

[STALLED] → "Options: 1. Wait 2. Interactive prompt 3. Kill: bash(command='C-c', is_input=True)"
[TIMEOUT] → "Check later: bash(session='scan-1')"
Command not found → (工具 description 中写明 apt-get install 模式)

仓库实现进一步细化了这套语义:tmux 层通过 PS1 标记检测命令完成、通过提示符尾部正则(msf6 >、meterpreter、sliver、(Pdb)、>>> 等,见 tmux.py)区分「交互提示符」与「静默挂起」;bash 工具层对连续 3 次内容完全相同的被动读取注入 [STALE] 提示,引导 Agent 放弃轮询、转向 kill-and-pivot 的恢复路径。错误不是终止信号,而是带选项的下一步指令。

5. 内存架构

Decepticon 用三种存储组件分别承担「文件系统路由」「跨会话记忆」「会话内历史」三个职责。

5.1 Backend Routing(CompositeBackend)

设计文档给出的路由拓扑:

CompositeBackend
├── /skills/* → FilesystemBackend (宿主机 FS, read-only)
│   └── passive-recon/, active-recon/, reporting/ SKILL.md
└── default → DockerSandbox (容器内部)
    └── /workspace/* (扫描结果, 报告)

当前仓库的对应实现是 backends/init.py 的 make_agent_backend():/skills/ 前缀路由到进程内 FilesystemBackend(读取 decepticon/skills 包内技能树,约 5ms 级延迟),其余路径(尤其是 /workspace/)默认走沙箱 HTTP 传输。CompositeBackend 让 SkillsMiddleware 与 FilesystemMiddleware 共享同一个 backend 对象,却从不同的物理存储读取。该函数还支持 extra_routes 按最长前缀优先合并租户/插件资产树,并对含 .. 的路径穿越键直接 ValueError 拒绝。

5.2 InMemoryStore(跨会话记忆)

store = InMemoryStore()
agent = create_deep_agent(
    ...
    store=store,   # 跨会话保持数据
)

用途:跨会话保留上一会话的 target 信息、Agent 习得的偏好与历史发现,让长周期 engagement 中的多轮会话共享「组织记忆」。

5.3 Checkpointer(对话历史)

checkpointer = MemorySaver()  # 线程内对话状态保持
  • 通过 thread_id 隔离不同会话;
  • /clear 时生成新的 thread_id,实现上下文重置。

两者的边界在源码中清晰可辨:store 属于「Agent 级」的长期知识载体,checkpointer 属于「会话级」的短期状态载体——这也解释了为什么 /compact 只动消息历史(checkpointer 域),而 filesystem 与 skills 数据不受影响。

6. Skills 系统

6.1 Progressive Disclosure 流程

1. Agent 启动 → 只加载 SKILL.md frontmatter (name + description)
2. 收到用户请求 → 基于 description 判断相关技能
3. 相关技能激活 → 加载完整 SKILL.md 正文
4. 用技能知识执行任务

6.2 Description 设计

description 是 Agent 选择技能的唯一标准,必须具体、可触发行为。设计文档的对照示例:

# 坏例子
description: "Passive recon techniques"

# 好例子
description: "Use when gathering intelligence WITHOUT touching the target:
  WHOIS lookups, DNS record queries (dig), subdomain enumeration (subfinder),
  Certificate Transparency (crt.sh), HTTP header fingerprinting, and Google dorking.
  Includes command templates and analysis patterns."

仓库中的真实技能文件印证了这一规范,例如 active-recon/SKILL.md 的 frontmatter:

---
name: active-recon
description: "Active target probing — port scanning, service detection, vulnerability scanning, banner grabbing, web directory fuzzing, SSL/TLS analysis."
allowed-tools: Bash Read Write
metadata:
  subdomain: reconnaissance
  when_to_use: "port scan, nmap, active scan, service detection, banner grab, vulnerability scan, nuclei, nikto, SSL analysis, network sweep, testssl"
  tags: nmap, port-scan, service-detection, banner-grab, nuclei, vulnerability-scan
  mitre_attack: T1595, T1595.001, T1595.002, T1595.003
---

when_to_use 中的 trigger 关键词正是中间件进行技能匹配的索引(见 middleware/skills.py 的「nmap port scan → 匹配 active-recon」规则),MITRE ATT&CK 编号则为技能目录提供战术语义维度。

6.3 Quick Reference 模式

每个 SKILL.md 顶部放置可直接复制粘贴的 Quick Reference 段,让 Agent 加载技能后立刻能用,无需通读全文:

# Quick Reference — Common Scan Patterns
nmap -sS -sV -p 22,80,443,8080,8443 <TARGET> -oN /workspace/nmap_<TARGET>.txt

仓库中的 active-recon/SKILL.md 提供了完整的 Quick Reference 家族:SYN 扫描、top-1000 扫描、脚本枚举、UDP 扫描(DNS/SNMP/NTP)、ffuf 目录爆破、nuclei 漏洞扫描——每一条都带 -oN/-o 落盘参数,与 2.2 节的「先落盘、再引用」原则严格对齐。

7. 数据流总结:一次请求的完整旅程

设计文档给出了从用户输入到渲染输出的完整数据流,结合当前仓库实现整理如下:

用户输入
  ↓
CLI
  ├── /compact → 压缩上下文(observation masking)
  ├── /clear → 新 thread_id → 上下文重置
  └── 一般输入 → 流式执行引擎
      ↓
StreamingEngine
  ├── 旧观测遮蔽 → 压缩过时的 verbose 输出
  └── agent.stream() → deepagents 执行
      ↓
Recon Agent
  ├── 系统提示词 (recon.md) → XML 标签结构(1.3 节)
  ├── 技能加载(progressive disclosure)
  └── bash() 工具调用
      ↓
Sandbox execute_tmux()        ← <a href="https://link.gitcode.com/i/5167ff68db9ae380d17ae795dd39e0c7" target="_blank">sandbox_kernel/tmux.py</a>
  ├── tmux 会话管理(并行执行)
  ├── PS1 标记完成检测
  ├── _truncate() → 非对称输出截断(head 60% / tail 40%)
  └── 结果返回 Agent 上下文
      ↓
CLI 渲染器
  └── Kali Linux 风格输出渲染

需要说明的是,设计文档写作时使用的模块命名(docker_sandbox.py、streaming.py、cli.py)与当前仓库的实际文件布局略有演进:沙箱执行的核心逻辑现在位于 sandbox_kernel/tmux.py 与 sandbox_kernel/base.py(与容器内 daemon 共享),流式执行与状态压缩相关逻辑可见于 core/subagent_streaming.py 与 mcp_server/conversation.py,CLI 客户端则位于 clients/cli/src/。整体架构(管理网与运营网分离、沙箱仅经 Docker socket 驱动等)可参考 docs/architecture.md。

总结:上下文工程是系统设计而非提示词技巧

纵观 Decepticon 的上下文工程体系,可以提炼出三条贯穿始终的工程判断:

  1. 预算前置:与其等上下文爆掉再处理,不如在设计层就把「大输出落盘、上下文只留引用」内化为工具语义、系统提示词规则与技能模板,让每一 token 都花在信息密度高的地方(2.1、2.2 节)。
  2. 可恢复性优先:所有压缩(遮蔽、OFFLOAD、/compact)都保留原始数据的恢复路径——文件在 /workspace/、/.scratch/,命令在 session 中可重读。压缩的是表示,不是事实(2.1、3.3 节)。
  3. 结构即缓存:稳定的系统提示词前置以命中 KV-cache,SKILL.md frontmatter 与正文分离以实现按需加载,结构化摘要锚定 artifact trail 以抗信息丢失——上下文工程的收益大量来自「布局」,而非单纯的「删减」(1.2、2.3、6 节)。

这套方法论不限于 Decepticon:任何面向长任务、多工具、大输出场景的 LLM Agent(尤其是渗透测试、漏洞研究、安全运营分析)都可以直接复用其分层思路——先在工具层解决输出爆炸,再在提示词层优化注意力分布,最后在会话层提供显式压缩手段。

登录后查看全文
Decepticon