┌──────────────────────────────────────────────────────────────────┐
│  AstrBot  (端口 6185)                                            │
│  LLM 编排平台，管理 14 个 persona，负责思考/推理/委派             │
│  接受 /run /next /summary /critic 等前缀命令                     │
└──────────────────┬───────────────────────────────────────────────┘
                   │  HTTP POST /api/v1/chat (kickoff)
                   │  HTTP streaming SSE (reply)
┌──────────────────▼───────────────────────────────────────────────┐
│  atk-sidecar  (端口 8090)                                        │
│  Go HTTP 服务，负责：                                            │
│  - 与 AstrBot 的所有通信（kickoff/recovery/swarm dispatch）      │
│  - Card/Event/Channel 持久化                                     │
│  - 自动化调度（recovery loop、swarm dispatch、challenge 管理）   │
│  - Flag 提交与比赛 API 对接                                      │
│  - Shell/Python 执行（通过 runner）                              │
│  - 知识库检索（指纹阶段可主动查询；恢复轮次注入 KNOWLEDGE_HINT） │
└──────────────────┬───────────────────────────────────────────────┘
                   │  run_shell / run_python (via MCP → HTTP)
┌──────────────────▼───────────────────────────────────────────────┐
│  Kali Linux 执行环境                                             │
│  本地模式 (mode=local) 直接执行 shell/python 命令               │
│  Docker 模式 (mode=docker) 在容器内执行                         │
└──────────────────────────────────────────────────────────────────┘

atk-sidecar 内部分层：

┌─────────────────────────────────┐
│        httpapi (HTTP 层)        │  ← 21 个端点，无业务逻辑
├─────────────────────────────────┤
│     service (核心业务逻辑层)    │  ←  所有自动化调度在此
│  ┌─────────────────────────────┐│
│  │ card_pipeline    swarm_disp ││  ← card 处理管道 / 蜂群分发
│  │ recovery         branch_ctl ││  ← 自动恢复 / 分支控制
│  │ pioneer_dispatch session_reg││  ← Pioneer 并发 / session 生命周期
│  │ challenge_manager           ││  ← 多题并发管理
│  │ astrbot_postprocess         ││  ← AstrBot 回复解析，提取 card
│  └─────────────────────────────┘│
├─────────────────────────────────┤
│         基础设施包              │
│  cards  channelbus  events      │
│  kickoff  officialapi  runner   │
│  knowledge  submissions  router │
└─────────────────────────────────┘

// internal/sidecar/types.go
type Card struct {
    CardID     string         // 唯一 ID，格式: "<type>-<nanoid>"
    CardType   string         // 见下方类型表
    Stage      string         // challenge code（多题并发隔离用）
    GroupKey   string         // 目标 channel key
    Role       string         // 产出此 card 的 agent 角色
    Title      string
    Summary    string
    Status     string         // proposed/observed/completed/halt/captured/...
    Priority   string         // low/medium/high/critical
    Confidence float64        // 0.0-1.0
    Tags       []string       // 用于 routing 规则匹配
    Payload    map[string]any // 结构化内容，各 card 类型有专属字段
    CreatedAt  time.Time
    UpdatedAt  time.Time
}

type Event struct {
    ID       string
    Type     string   // "card.upserted" / "system.kickoff.created" / "system.recovery.triggered" / ...
    Stage    string
    Source   string
    GroupKey string
    Role     string
    Tags     []string
    Status   string
    Impact   string
    Message  string
    CardType string
    CardID   string
    Payload  map[string]any
    CreatedAt time.Time
}

// internal/sidecar/kickoff/store.go
type Envelope struct {
    ID                string
    Source            string         // "competition_api" / "automation" / "swarm_dispatcher"
    Trigger           string         // 触发原因
    TargetRole        string         // 目标 AstrBot persona ID
    TargetChannel     string         // 期望输出的 channel
    Sender            string         // "system://official_api"
    CommandPrefix     string         // "/run"
    CommandText       string         // 完整 kickoff 消息文本
    Summary           string
    Stage             string         // challenge code
    SnapshotHash      string
    Snapshot          map[string]any // 官方 API 快照
    Meta              map[string]any
    SessionIDOverride string         // 非空时覆盖 AstrBot session ID（多题并发用）
    CreatedAt         time.Time
    Status            string
}

// internal/sidecar/channelbus/publisher.go
type PublishedMessage struct {
    ID          string
    ChannelKey  string
    Stage       string         // 从嵌入 card/event 自动提取（多题过滤用）
    Text        string
    Tags        []string
    Card        *sidecar.Card
    Event       *sidecar.Event
    PublishedAt time.Time
}

最终交付目录：
  persona/assembled/commander_main.md
  persona/assembled/recon_persona.md
  persona/assembled/summary_persona.md
  persona/assembled/planner_persona.md
  ... 共 14 个完整 prompt 文件

# 打开对应文件并复制完整 prompt
persona/assembled/<role>.md

官方 API 变更检测（scheduler, 每 10s）
  ↓
official.FetchStageSnapshot()
  ↓ 检测到 hash 变化
dispatchKickoff(ctx, snapshot)
  ├── kickoff.NewEnvelope(cfg.Automation.Kickoff, trigger, snapshot)
  │     CommandText: "/run [SYSTEM][competition_api] stage=X target_url=Y ..."
  │     → AstrBot POST /api/v1/chat { session_id: "atk-commander-main-v3" }
  │     → SSE streaming reply → astrbot_postprocess → extractReplyCards
  │
  └── go dispatchPioneerKickoff(snapshot)   ← 并发，独立 goroutine
        CommandText: "/run [SYSTEM][pioneer] stage=X target_url=Y ..."
        → AstrBot POST /api/v1/chat { session_id: "atk-pioneer-v1" }

challengeManager.tick()  ← 每 30s
  ↓
official.FetchChallengeList()
  ↓ 发现未解且未 active 的题目（按 difficulty 升序）
official.StartChallenge(code) → entrypoints
  ↓
dispatchChallenge(ch, entrypoints)
  ├── cmdEnv.SessionIDOverride = "atk-cmd-" + code
  │   dispatchKickoffEnvelope(cmdEnv)
  └── pioEnv.SessionIDOverride = "atk-pio-" + code
      go dispatchPioneerEnvelope(pioEnv)

planner_agent 输出 HypothesisCard { vuln_type: "sqli" }
  ↓
AstrBot reply → astrbot_postprocess → extractReplyCards
  ↓
upsertCard() → card_pipeline
  ↓
swarmDisp.MaybeDispatch(card)
  ├── 检查 card.CardType == "HypothesisCard"
  ├── 检查 vuln_type 在已知 6 种之内（"unknown" 不触发）
  ├── 检查同 stage+vuln_type 未有 active session
  ├── 检查 stageCount[stage] < MaxConcurrentPerStage (默认 3)
  └── go dispatch(agentRole="sqli_agent", vulnType="sqli", stage, card)
        ↓
        swarmCfg.TargetRole = "sqli_agent"
        swarmCfg.TargetChannel = "exec_feedback"
        snapshot.Normalized = { stage, vuln_type, target_url, hypothesis, validation_steps, ... }
        env.SessionIDOverride = "atk-swarm-sqli-" + sanitize(stage)
        loadDomainSkill("sqli") → env.CommandText += "[DOMAIN_SKILL]\n..."
        dispatchKickoffEnvelope(env)

另一触发路径（SecurityMatcher，专用于指纹到漏洞家族假设的自动匹配）：
AssetCard 到达 card_pipeline
  ↓
securityMatcher.MatchBySignals(signals)
  ↓ 命中高置信条目
自动生成 HypothesisCard { vuln_type: "rce", source: "security/*" }
  ↓ 同上 swarm dispatch 路径

agent 输出 GroupDigest（status=unsolved）或 RiskCard（status=halt）
  ↓
upsertCard() → recovery.ObserveCard(card)
  ├── recoveryTriggerFromCard(card) → recoveryTrigger{ Stage, CardType, CardID, Reason, FailureLevel }
  └── 更新 stageRecoveryState.queued（高优先级 trigger 覆盖低优先级）

dispatchKickoffEnvelope 完成回调 → maybeStartRecoveryRound
  ↓
recovery.CompleteKickoff(envelope) → returns queued trigger（若有）
  ↓
buildRecoveryEnvelope(trigger, previous)
  ├── CommandText 包含:
  │   - [SYSTEM][recovery_loop] stage=X round=N failure_level=L4 reason=...
  │   - 恢复策略指令（先 summary → critic → reflector → planner）
  │   - [RETRY_READY_CONTEXT] 块（最近 GroupDigest 内容）
  │   - [OFFICIAL_HINT] 块（来自比赛平台 /api/hint）
  │   └── [KNOWLEDGE_HINT] 块（知识库检索结果，按 trigger/runbook/reference 分层）
  └── 新 kickoff → AstrBot（同 session）

recovery 轮次限制：
  - commander: max_rounds = 5（yaml 配置）
  - pioneer: max_rounds = 2
  - swarm: 无 recovery（10 步结束即结束）
  - competition.auto_hint = true 时：round >= 2 且 hint_viewed=false 才请求 hint（pioneer 不请求）

任意 agent 输出 FlagCandidateCard { candidate: "flag{xxx}", stage: "BwAMWQ..." }
  ↓
upsertCard() → card_pipeline
  ├── markSessionSolved(sessionID, "flag candidate captured")
  │     └── stopAllForStage(stage, exceptSessionID)
  │           → 取消同 stage 其他 session 的 HTTP context（best-effort）
  │           → 标记为 stop_requested
  │
  └── maybeAutoSubmitFlagCandidate(card)
        ├── extractFlagValue(candidate)  ← 正则提取 flag{...}
        ├── 检查 confidence >= min_confidence (默认 0.85)
        ├── 检查未重复提交
        ├── [Competition 模式] official.SubmitCompetitionFlag(stage, flag)
        │     → POST /api/submit { code: stage, flag: flag }
        └── [Legacy 模式] official.SubmitFlag(stage, flag, sourceCardID)
              → POST {flag_submission.endpoint_path}

GET /v1/channels/messages?role=summary_agent&channel_key=main_control&stage=BwAMWQ
→ channelbus.Store.List(filter{Stage: "BwAMWQ"})
→ 只返回 PublishedMessage.Stage == "BwAMWQ" 的消息

server: # HTTP 监听地址
storage: # 持久化根目录（默认 runtime_data/）
scheduler: # 官方 API 轮询调度（interval 默认 10s）
official_api: # 比赛/题目平台 API（snapshot, hint, flag 提交）
automation: # kickoff + recovery + pioneer 配置
challenge_manager: # 多题并发管理（默认 disabled）
swarm_dispatcher: # 蜂群分发配置（默认 enabled, max 3/stage）
competition: # 比赛平台直连（独立于 official_api，默认 disabled）
knowledge: # 知识库检索（inject_on_recovery, top_k, paths）
runner: # Shell/Python 执行器（local/docker 模式）
channels: # Channel bus 配置（publisher, ingress）
routing: # Channel 路由规则（channels, publish_rules, mirror_rules）

challenge_manager:
  enabled: true # 启用后接管 challenge 生命周期
  poll_interval: "30s"
  max_concurrent: 3 # 比赛平台最大并发题目数

swarm_dispatcher:
  enabled: true
  max_concurrent_per_stage: 3 # 每道题同时运行的蜂群 agent 上限
  cooldown: "0s" # 同 vuln_type 重新 dispatch 的冷却时间
  skills_dir: "skills/domain" # domain skill 文件路径

competition:
  enabled: true
  auth_token: "Agent-Token 值"
  base_url: "https://competition-api.example.com"
  auto_submit: true # FlagCandidateCard → POST /api/submit
  auto_hint: true # recovery round >= 2 → POST /api/hint（pioneer 除外）

automation:
  kickoff:
    mode: "astrbot"
    astrbot:
      base_url: "http://127.0.0.1:6185"
      api_key: "abk_xxx"
      session_id: "atk-commander-main-v3"
      enable_streaming: true # SSE 流式回复，启用实时卡片解析

knowledge/
  indexes/                      # 索引文件（已构建，直接被 Retriever 加载）
    zone1_ctf_web/
      trigger.jsonl             # 触发规则：看到信号 X → 建立分支 Y
      runbook.jsonl             # 操作手册：按步骤执行 A/B/C
      reference.jsonl           # 参考资料：工具、CVE、服务特性
    zone2_src_component/
    zone3_multi_network_oa/
    zone4_ad_pentest/
  raw/                          # 原始知识文档（供重新构建索引用）
  security/                     # SecurityMatcher 数据（特征匹配型）
    apache/httpd-path-traversal.md
    redis/unauthorized-access.md
    tomcat/manager-default-creds.md

[KNOWLEDGE_HINT]
以下为可选战术参考，不是事实。当前目标的真实观测优先级高于任何知识提示。

[TRIGGER SIGNALS] — 匹配到以下信号时触发对应漏洞分支：
- ref=... score=0.82 title=... hint=...

[RUNBOOK] — 如果确认漏洞存在，按以下步骤执行：
- ref=... score=0.71 branch=sqli hint=...

[REFERENCE] — 工具/CVE/服务特定参考（仅 L5/hard stall 时包含）：
- ref=... score=0.65 hint=...

skills/domain/
  sqli/SKILL.md          # SQL 注入战术手册（~107 行）
  ssrf/SKILL.md
  auth-bypass/SKILL.md
  file-inclusion/SKILL.md
  rce/SKILL.md
  xss/SKILL.md
  web-recon/SKILL.md     # Web 侦察技术（recon_agent 使用）

runtime_data/                          # 运行时数据根目录（yaml: storage.root_dir）
  cards/
    <CardType>.jsonl                   # 每种 card 类型一个文件，按 card_id dedup
  events/
    events.jsonl                       # 事件流，追加写入
  channels/
    main_control.jsonl                 # channel 消息，追加写入
    recon_raw.jsonl
    exec_feedback.jsonl
    evidence_review.jsonl
    direct_solve.jsonl
    swarm_feedback.jsonl
  system_kickoff/
    commander_main.jsonl               # kickoff envelope 镜像（commander）
  pioneer_kickoff/
    pioneer.jsonl                      # kickoff envelope 镜像（pioneer）
  flag_submissions/
    submissions.jsonl                  # flag 提交记录
  runner_artifacts/
    <job_id>.txt                       # shell/python 执行输出

runtime_exec/                          # runner 工作目录（临时文件）

atk/
  cmd/atk-sidecar/
    main.go                  # 入口：初始化所有组件，启动 HTTP 服务 + 调度 goroutine

  internal/sidecar/
    types.go                 # 核心类型：Card, Event, PublishRequest, OfficialSnapshotKickoff
    id.go                    # NewID(prefix) — nanoid 生成

    cards/store.go           # JSONL card 存储（Upsert, List, Get）
    channelbus/
      publisher.go           # PublishedMessage 定义 + filePublisher（写 JSONL）
      store.go               # List(ListFilter) — 读 channel 消息，支持 Stage 过滤
    config/config.go         # 全部 Config struct + Load() + applyDefaults()
    events/
      bus.go                 # 事件总线（Publish, Subscribe）
      store.go               # 事件 JSONL 持久化
    httpapi/
      server.go              # HTTP 路由注册 + 所有 handler
      dashboard.go           # /v1/dashboard/progress 数据聚合
    kickoff/store.go         # Envelope 定义 + fileStore/httpStore/astrBotStore 实现
    knowledge/
      retriever.go           # TF-IDF 知识检索（New, Query, QueryScoped）
      security_matcher.go    # 特征指纹匹配（NewSecurityMatcher, MatchBySignals）
    officialapi/client.go    # 比赛/题目平台 API 客户端
    planning/ir.go           # PlanIR 解析（atk_plan XML-like 结构）
    router/router.go         # 路由规则引擎（ResolvePublish, ResolveIngress）
    runner/
      executor.go            # Shell/Python 执行（local/docker 模式）
      safety.go              # 命令安全检查
      types.go               # RunRequest, RunResult
    service/                 # 核心业务逻辑（见 2.1 节文件职责表）
    submissions/store.go     # Flag 提交记录 JSONL 存储

```atk_card
{
  "card_type": "HypothesisCard",   // 必填，使用上方表格中的类型名
  "card_id": "hypothesis-sqli-1",  // 必填，格式: <type>-<描述>[-<序号>]
  "group_key": "main_control",     // 目标 channel（可选，有默认值）
  "role": "planner_agent",         // 产出角色
  "summary": "...",
  "status": "proposed",
  "priority": "medium",
  "confidence": 0.75,              // 0.0-1.0
  "tags": ["PLAN"],
  "payload": { ... }               // 类型专属字段
}

`stage` 字段由 sidecar 从 envelope 自动填充，agent 通常不需要手动指定。

### 12.2 FlagCandidateCard 规范（关键）

```json
{
  "card_type": "FlagCandidateCard",
  "card_id": "pioneer-flag-abc123",
  "group_key": "exec_feedback",
  "role": "pioneer",
  "status": "captured",
  "confidence": 0.95,
  "tags": ["FLAG", "PIONEER"],
  "payload": {
    "candidate": "flag{exact_flag_string_here}",  // 只放精确 flag，不加任何额外文字
    "method": "SQL union-based injection",
    "session_id": "atk-pioneer-v1"               // 用于 markSessionSolved
  }
}

[RETRY_READY_CONTEXT]
<最近 GroupDigest 的 retry_ready_context 字段内容>

[OFFICIAL_HINT]
<比赛平台 hint>

[KNOWLEDGE_HINT]
<知识库检索结果>

/run [SYSTEM][<source>] stage=<code> target_url=<url> <key1>=<val1> ...
<newline>
<optional block 1>
<newline>
<optional block 2>

go build ./...                 # 编译检查
go test ./...                  # 全量测试
go test ./internal/sidecar/service/... -v -run TestServiceChannelMessages

1. 启动 Kali 执行环境（如 Docker 容器）
2. 启动 AstrBot（端口 6185）
   - 确认 14 个 persona 已从 `persona/assembled/*.md` 粘贴到 AstrBot Web
   - 确认 MCP server（atk-sidecar MCP）已配置
3. 启动 atk-sidecar（端口 8090）
   ATK_SIDECAR_CONFIG=configs/atk-sidecar.yaml ./atk-sidecar

# 直接复制 persona/assembled/<role>.md 到 AstrBot Web
# 例如：
sed -n '1,40p' persona/assembled/commander_main.md

go build -o atk-sidecar ./cmd/atk-sidecar/

# configs/atk-sidecar.yaml
competition:
  enabled: true
  auth_token: "<Agent-Token>"
  base_url: "https://hackathon-api.example.com"
  auto_submit: true
  auto_hint: true

challenge_manager:
  enabled: true
  poll_interval: "30s"
  max_concurrent: 3

# 单题模式的 scheduler 可以保留（用于快速测试），
# 但 challenge_manager 开启后会接管完整的题目生命周期
scheduler:
  enabled: false # 建议在 challenge_manager 模式下关闭

# 健康检查
curl http://localhost:8090/healthz

# 当前 session 状态
curl http://localhost:8090/v1/sessions/atk-commander-main-v3

# 最近 FlagCandidateCard
curl "http://localhost:8090/v1/cards?card_type=FlagCandidateCard&limit=10"

# Dashboard
open http://localhost:8090/dashboard

candidate          string   精确 flag 字符串（仅此，不加任何额外内容）
method             string   利用方式简述
session_id         string   当前 AstrBot session id（用于 markSessionSolved）
vuln_type          string   （蜂群输出时填写）

vuln_type          string   必填，触发 swarm dispatch 的关键字段
hypothesis         string   假设描述
preconditions      []string 前提条件
validation_steps   []string 验证步骤
success_signals    []string 成功信号
failure_signals    []string 失败信号
dominant_branch    string   当前最强主线
required_next_moves []string 必要的下一步动作
path_id            string   路径 ID（稳定、跨轮复用）
tool_requirements  []string 工具需求描述

facts              []string 已验证事实
unknowns           []string 待确认项
priorities         []string 优先级
dead_paths         []string 已证伪路径
repeat_failures    []string 重复失败模式
retry_ready_context []string 下一轮可直接消费的摘要
knowledge_candidates []string 候选知识提示（降噪后）
dominant_branch    string
required_next_moves []string
active_move_id     string
stall_state        string   "soft_stall" / "hard_stall" / ""

risk_type          string
reason             string
failure_level      string   L0-L5
decision           string   "proceed" / "require_revision_before_execute" / "halt"
need_branch_replan bool     L4/L5 时通常为 true
retry_advice       string
anti_pattern       []string

action_type        string
target             string
selected_tool      string
result             string
failure_level      string   L1-L4（成功时为空）
failure_reason     string
observed_deltas    []string 与预期的差异
path_id            string
move_id            string
evidence_gain      string