WieHeistDu119/ctf-agent-deepseek-harness-

ctf-agent-cluster — CTF 多层级 Agent 作战集群（DSH web 插件）

移植自 WieHeistDu119/ctf-agent（ctf-orchestrator，asyncio + Textual TUI）。
本插件用 DeepSeek Harness（DSH）的原生架构重做：前端（web UI：对话记录与对话框之间的 CTF 面板）替代 TUI，
agent 编排直接用 DSH 的 subagent / persona / toolFilter / 并行工具调用，不再自建 asyncio 运行时。

三级架构

用户（甲方）
└─ 第一层 用户层：用户 agent（当前对话会话）
│  ctf_start（唯一启动权）/ 汇报 / 转达任务 / 确认人工提交
▼  ctf_spawn(role=boss) —— 每次任务 = 一次「决策会议」
└─ 第二层 管理 agent 层：主 agent（核心决策）+ 席位 agent（获取/难度审核/分派/提交/综合）
│  决策 → 席位 agent 执行 → 席位 agent 用 ctf_spawn 给做题层写提示词并分派
▼  ctf_spawn(role=solver, challengeId, model)
└─ 第三层 做题 agent 层：每道题一个 solver（只做指派题，上报候选 flag / 受阻）

- agent 给 agent 写提示词：ctf_spawn 的 task 参数就是调用方（主 agent / 席位 agent / 用户 agent）写给子 agent 的完整任务提示词；插件负责附加角色简报（persona）、工具白名单（toolFilter）、模型分配与角色登记。
- 模型由管理 agent 自主调配：ctf_model_pool 查看可用模型（自动发现 deepseek / mimo 等 provider + 定制条目），ctf_spawn(model="provider/model") 按题分配；mimo 是多模态模型，图片取证类题目优先。ctf_model_upsert 可登记 gpt-5.5 等新模型。
- 状态驱动：boss/manager/solver 都按“一次性状态处理器”运行。每轮读取 state.json，完成一个明确状态转换，写回 ctf_progress_report / 题目字段 / 留言板后退出；等待新状态时由新 agent 接续，避免长上下文拖垮 DSH。
- 并发：一条消息里多个 ctf_spawn 并行派发（DSH 并行工具调用）；ctf_system_load 给出本机负载和建议 solver 并发，管理层再结合靶机容量、题型和队列长度动态调整。

可配置比赛 Skill

插件把比赛关键信息集中在 lib/competition.js，所有角色通过 ctf_competition_info 或角色简报读取同一份配置。公开仓库不包含任何比赛 AccessKey；运行时通过环境变量注入：

- CTF_COMPETITION_NAME：比赛名称，默认 CTF Competition
- CTF_SERVER_HOST：比赛平台地址，默认 https://pro.dasctf.com
- DASCTF_ACCESS_KEY：DASCTF Agent API AccessKey，不要写入源码或日志
- CTF_API_BASE_PATH：DASCTF Agent API base path，默认 /slab-match/api/v1/agent
- CTF_WORKSPACE_ROOT / CTF_ROOT：做题根目录，默认 ~/ctf-workspace
- CTF_TOOLS_ROOT：额外工具目录，默认 ~/tools
- CTF_API_DOC / CTF_GATEWAY_DOC：比赛 API 文档路径，默认位于做题根目录下

solver 每题开独立目录，产物写入本题 scripts/、output/、artifacts/ 和 progress.md。多人分片默认由用户层赛前指定，题目字段里的 owner 用来标记责任范围。

管理层和做题层在 CTF_WORKSPACE_ROOT 工作区内不要反复询问常规读写权限；如果路径越界导致权限失败，先回到当前题目目录或 CTF_WORKSPACE_ROOT/.ctf-agent/scripts，不要申请 danger-full-access。

统一获取路径（固定脚本，可热修改）

所有比赛接入走 .ctf-agent/scripts/ 下的固定脚本，禁止每次 curl 网页找题：

1. ctf_event_add 注册比赛（名字 + 网址）；
2. ctf_fetch_challenges 调用 fetch-challenge.mjs 拉题与附件到 challenges///（DASCTF Agent API / CTFd API / JSON 清单 / 本地目录自动识别）；
3. 平台不兼容 → 直接编辑脚本（改完即生效），并在留言板发建议。

Flag 提交统一走 submit-flag.mjs：DASCTF 自动提交（/slab-match/api/v1/agent/answer-panel/answer）或 CTFd 自动提交（/api/v1/challenges/attempt）；
不支持自动提交的平台 → 进入「待人工提交」队列，在 UI 显著位置展示（复制 flag → 平台提交 → 点「已提交，标记解决」）。
solver 找到候选 flag 后调用 ctf_flag_report，默认立即自动提交；提交 accepted 后写 writeup.md、保存 evidence/截图并结束。提交 agent 只处理自动提交失败、人工提交、rejected/rate_limited 和复核。

调度与巡查

- 用户说“启动系统/开始做题”时，用户层直接调用 ctf_start(autoBoss=true)。该工具会重新认领当前根会话为用户层、使用配置的 CTF 工作区，并默认后台召集主 agent。
- 前期拉题后先启动快车队列：官网/API 已标为 VERY_EASY/EASY 或低分的题直接分派 solver；review 只补未知难度、medium+、异常附件或靶机不明的题，每批限时 3-5 分钟。
- 主 agent 先用 ctf_system_load、ctf_manager_policy、ctf_target_status 判断本轮 solver 并发，不固定 3 个。CPU/内存余量足时提高简单题并发；负载高时减并发并优先无需靶机题。
- ctf_target_status 显示 web/pwn 靶机容量和活跃靶机；容量满时先做 rev/crypto/misc 等无需靶机题，或回收空闲靶机。
- ctf_progress_report 写入可巡查报告，并追加到题目 progress.md。solver 约 15 分钟或关键转折后报告；巡查 agent 约 10 分钟一轮。
- 为减少总调度上下文不一致，把稳定事实写回 state.json、题目字段、progress.md、留言板，不依赖长篇口头上下文。任何 agent 需要等待新状态、方向大幅切换或上下文变长时写 handoff 后退出。
- 模型默认：百炼 deepseek-v4-flash + router standard 用于粗审和普通题；图片强相关优先 mimo，高级识图用百炼 qwen-vl；DeepSeek Pro 走极简模式。

留言板（agent → 用户）

agent 通过 ctf_board_post 发建议（suggestion）/ 需用户处理（need-user）/ 信息 / 报告；
UI 留言板区域可查看与「标为解决」。这是热修改系统的入口：必要/建议的新增功能都在这，
用户另开对话对插件本体进行修改（脚本级修改则直接在 .ctf-agent/scripts/ 编辑）。

工具清单

| 工具 | 谁能用 | 作用 |
|---|---|---|
| ctf_status | 全部 | 集群状态快照 |
| ctf_competition_info | 全部 | 固定比赛 skill（host、文档、tools、模型策略、靶机容量，AccessKey 脱敏） |
| ctf_system_load | 全部 | 本机轻量负载快照和建议 solver 并发 |
| ctf_start / ctf_pause / ctf_resume | 仅用户层 | 启动/暂停/恢复（idle→running→paused） |
| ctf_event_add / ctf_event_list | 用户层/管理 agent | 注册/列出比赛事件（统一获取路径入口） |
| ctf_fetch_challenges | 管理 agent | 固定脚本拉题 + 附件 |
| ctf_challenge_list | 全部 | 题目清单（过滤） |
| ctf_challenge_update | 管理 agent | 难度评估 / 状态流转 / 备注 |
| ctf_target_status / ctf_target_start / ctf_target_recover | 状态全部可读；启停仅管理 agent | DASCTF 靶机容量、启动、回收 |
| ctf_progress_report | 全部 | 做题/巡查进度报告，追加到 progress.md |
| ctf_model_pool / ctf_model_upsert | 池：全部；登记：管理 agent | 模型目录 / 登记新模型 |
| ctf_spawn | 用户层/管理 agent | 委派（boss/manager/solver），可指定模型，可后台 |
| ctf_flag_report | 全部 | solver 上报候选 flag / 受阻；默认自动提交候选 flag |
| ctf_flag_submit | 管理 agent | 自动/人工提交，处理失败、复核和人工队列 |
| ctf_flag_confirm | 仅用户层 | 用户确认人工提交结果 |
| ctf_maintenance | 用户层/管理 agent | 赛中/赛后本地状态维护；默认 dry-run，不调用外部平台 |
| ctf_board_post / ctf_board_list | 全部 | 留言板 |
| ctf_scripts | 全部 | 固定脚本位置与用法 |

数据与目录

集群根目录 = 选定的工作区，运行时数据在其 .ctf-agent/ 下：

.ctf-agent/
├── state.json          # 集群状态投影（原子写）
├── events.jsonl        # 活动日志（追加）
├── board.jsonl         # 留言板日志（追加）
├── scripts/            # 固定脚本副本（热修改入口，改完即生效）
challenges/// # 做题工作区（description.md + files/ 附件）
└── progress.md         # 每题进度报告（由 ctf_progress_report 追加）

安装

方式 A：运行时注入（免重启，开发态）

已有 dsh-super-injector 常驻时，对任一 agent 会话说：

dev_inject_plugin

注入即完整生效（host 工具 + client UI），改代码后约 1.5s 自动热重载；重启后由注入清单自动恢复。

方式 B：官方 bundle（生产态，重启后生效）

dsh plugin --profile web add

或手工：把插件 junction 到 ~/.dsh/profiles/node_modules/@dsh-external/ctf-agent-cluster，
并在 ~/.dsh/profiles/web/cordis.patch.yml 追加：

- insert:
- id: ctf-agent-cluster
name: '@dsh-external/ctf-agent-cluster'
config: {}

使用流程（比赛时）

1. 打开 web（重启后插件加载）→ 对话记录与对话框之间出现 CTF 集群面板；
2. 首次使用在面板点「绑定此对话为用户层」（或直接让用户 agent ctf_start 时自动绑定）→ 在对话里对用户 agent 说「启动集群」；
3. 用户 agent 召开决策会议（ctf_spawn role=boss）→ 主 agent 读取状态和负载 → 获取 agent 拉题 → 简单题快车队列先开 solver，同时 review 限时补审剩余题；
4. 做题层找到 flag 后 ctf_flag_report 默认自动提交；accepted 后写题解和证据并退出，失败才进入提交/复核链路；
5. 留言板看 agent 的新功能建议，脚本级改动直接编辑 .ctf-agent/scripts/。

环境变量

- CTF_COMPETITION_NAME：比赛名称。
- CTF_SERVER_HOST：比赛平台地址，默认 https://pro.dasctf.com。
- CTF_WORKSPACE_ROOT / CTF_ROOT：集群根目录显式指定。
- CTF_TOOLS_ROOT：solver 可读取/执行的外部工具目录。
- CTF_API_DOC / CTF_GATEWAY_DOC：比赛文档路径。
- DASCTF_ACCESS_KEY：插件配置读取的 DASCTF AccessKey。
- CTF_DASCTF_ACCESS_KEY：固定脚本内部接收 DASCTF AccessKey；通常由插件工具从 DASCTF_ACCESS_KEY 注入。
- CTF_AGENT_TOKEN（或 --token-env 指定名字）：CTFd 平台 API Token，只从进程环境读取。