【免费下载链接】DecepticonAutonomous Hacking Agent for Red Team项目地址https://gitcode.com/gh_mirrors/de/Decepticon点击查看免费下载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 ContextSKILL.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 ATTCK 技术编号真正的技能正文全部按需加载——这正是 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 在两级进行遮蔽maskingLevel 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保留 Preview200 字符与元数据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(sessionscan-1) to re-read or check /workspace/ for saved files]值得强调的是遮蔽发生在保留可恢复路径的前提下Agent 仍可通过bash(sessionscan-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).设计文档给出的压缩动作分三步检查最近 2 轮以外的所有 ToolMessage将超过 5,000 字符的输出替换为 compact summary通过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(commandC-c, is_inputTrue) [TIMEOUT] → Check later: bash(sessionscan-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 RoutingCompositeBackend设计文档给出的路由拓扑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( ... storestore, # 跨会话保持数据 )用途跨会话保留上一会话的 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 ATTCK 编号则为技能目录提供战术语义维度。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() ← [sandbox_kernel/tmux.py](https://link.gitcode.com/i/d850dac2f37bb8257f599d4bb03adfbf) ├── 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.pyCLI 客户端则位于 clients/cli/src/。整体架构管理网与运营网分离、沙箱仅经 Docker socket 驱动等可参考 docs/architecture.md。总结上下文工程是系统设计而非提示词技巧纵观 Decepticon 的上下文工程体系可以提炼出三条贯穿始终的工程判断预算前置与其等上下文爆掉再处理不如在设计层就把「大输出落盘、上下文只留引用」内化为工具语义、系统提示词规则与技能模板让每一 token 都花在信息密度高的地方2.1、2.2 节。可恢复性优先所有压缩遮蔽、OFFLOAD、/compact都保留原始数据的恢复路径——文件在/workspace/、/.scratch/命令在 session 中可重读。压缩的是表示不是事实2.1、3.3 节。结构即缓存稳定的系统提示词前置以命中 KV-cacheSKILL.mdfrontmatter 与正文分离以实现按需加载结构化摘要锚定 artifact trail 以抗信息丢失——上下文工程的收益大量来自「布局」而非单纯的「删减」1.2、2.3、6 节。这套方法论不限于 Decepticon任何面向长任务、多工具、大输出场景的 LLM Agent尤其是渗透测试、漏洞研究、安全运营分析都可以直接复用其分层思路——先在工具层解决输出爆炸再在提示词层优化注意力分布最后在会话层提供显式压缩手段。赞分享【免费下载链接】DecepticonAutonomous Hacking Agent for Red Team项目地址https://gitcode.com/gh_mirrors/de/Decepticon点击查看免费下载相关推荐pstack 上下文窗口守护指南有限上下文的 token 预算与子代理路由策略pstack 上下文窗口守护指南有限上下文的 token 预算与子代理路由策略 导读 principle guard the context window 是人工智能AI 技能AI 插件开发工具Vibe Coding 上下文管理技巧ai-guide 教程之上下文工程实战指南Vibe Coding 上下文管理技巧ai guide 教程之上下文工程实战指南 让 AI 真正理解你的项目从上下文窗口到记忆体系为 AI 装上可靠的记文档教程知识库人工智能Waza /health 上下文检查器inspector-context实战指南Agent 指令面、上下文预算与技能安全审计Waza /health 上下文检查器inspector context实战指南Agent 指令面、上下文预算与技能安全审计 导读 本文聚焦 Waza 插创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考