ARTEX 设计思路全书
从零读懂一套 LLM 多 Agent 自主渗透系统

这份文档假设你没有读过一行源码，但会写 Go、知道什么是 HTTP 和数据库。所有概念都从「为什么需要它」讲起，再落到「代码在哪里、怎么实现的」。

1.1 一个 LLM 单 Agent 走不完全程

如果你让一个 LLM 直接做渗透测试，它会遇到四个结构性障碍，而且都不是「模型不够聪明」能解决的：

ARTEX 的答案不是「换个更强的模型」，而是把一个人的工作拆成一个组织的分工：有人看图、有人定方向、有人动手、有人记录、有人把关。

1.2 一句话说清架构

这个闭环里有两个关键角色和两个关键约束：

1.3 与传统扫描器的本质区别

1.4 用一张「作战指挥部」类比记住全系统

再补三个角色：Goals 分解器是开战前的参谋部，把「拿下这个站」拆成可验收的目标并划清行动边界；Main Agent 是司令部的热线，人通过它下指令；Guard / Intercept 是宪兵，每个动作出门前都要过它。

2.1 分层全景

2.2 为什么是「单二进制」

部署形态直接影响了架构：前端在构建期导出为纯静态文件，编译时嵌进 Go 二进制，运行时只暴露一个端口（默认 :8787）。这带来三个连锁决策：

2.3 进程内的真实拓扑

理解 ARTEX 的并发，关键是记住这张图：任务不是线程，而是一组 goroutine + 一个数据库里的 exploration。

如果把 ARTEX 的其他所有设计都删掉、只留一个，那就是双图。理解了它，引擎、工具集、覆盖度、报告全都是它的自然推论。

3.1 为什么不能只有一张图

直觉上「把资产和探索都塞进一张图」更简单。但这两类信息在四个维度上根本冲突：

混在一起会立刻出问题：任务 A 删掉自己的探索记录，不能把公司域名也删了；任务 B 也不能因为「没测过这个子域」就认为它不存在。把真值与过程分离，是这类长任务系统最基础的一条不变量。

3.2 两张图的形状

3.3 资产图：程序算结构，Agent 只交原料

资产图有六种节点，每种都有明确的唯一索引，这就是去重的真正实现——数据库唯一约束，不是应用层查重：

3.4 探索图：七种节点，各有一套状态机

探索图是「这次任务的思考轨迹」。节点类型不是随意设计的，每一种都对应一个明确的问题：

3.5 五种边与方向约定

3.6 锚点：把「过程」钉到「实体」上

两张图通过一张极简的连接表缝合：

-- 一个节点可以锚定多个资产；一个资产可以被多个节点锚定
CREATE TABLE IF NOT EXISTS exploration_anchors (
    node_id   BIGINT NOT NULL REFERENCES exploration_nodes(id) ON DELETE CASCADE,
    asset_id  BIGINT NOT NULL REFERENCES assets(id) ON DELETE CASCADE,
    PRIMARY KEY (node_id, asset_id)
);
CREATE INDEX IF NOT EXISTS idx_anchor_asset ON exploration_anchors(asset_id);

这三个字段的组合能回答两类完全不同的问题，而且是双向的：

3.7 一个完整例子：血缘链长什么样

假设目标是「证明 example.com 存在可利用漏洞」，实际跑出来的图可能是：

goal #1  「证明 example.com 存在可利用漏洞」           state=open
  │ spawns
  ├─▶ intent #2  「对 www.example.com 做指纹与目录探测」   state=done
  │     │ yields
  │     ├─▶ fact #5   「使用 ThinkPHP 5.0.24，/index.php 可访问」 confidence=observed
  │     └─▶ fact #6   「/backup/ 返回 403，但响应体泄露绝对路径」 confidence=observed
  │
  ├─▶ intent #9  「验证 ThinkPHP 5.0.24 已知 RCE」        state=exhausted
  │     │ derived_from: fact #5
  │     └─▶ fact #11  「payload 被 WAF 拦截，多种编码均 403」 confidence=observed
  │
  └─▶ intent #14 「利用 fact#6 的路径泄露读取配置文件」    state=done
        │ derived_from: fact #6
        ├─▶ fact #15  「/backup/../config.php 可读取，含 DB 密码」 confidence=observed
        └─▶ finding #16「任意文件读取导致敏感配置泄露」 severity=high
              │ proves
              └──▶ goal #1  state=met

这条链的价值在于：报告里说「存在任意文件读取」，能一路点回 哪条意图、基于哪条事实、用了什么 payload、拿到什么响应。而且 planner 在下一轮读到 fact #11（WAF 拦截）时，会知道「这条方向已被试过且失败」，不会让另一个 worker 重复撞墙。

引擎（server/engine.go）不到 1300 行，却是整个系统的心跳。它不实现任何业务逻辑，只做三件事：什么时候唤醒 planner、谁去领意图、什么时候该停。

4.1 闭环全图

4.2 七种唤醒来源

planner 不是定时任务，它是被动唤醒的。每次唤醒都会带上一组 TriggerEvent，告诉它「这次为什么醒」，避免它每轮都重新扫全图：

没有触发事件时（心跳、恢复），提示词会明确告诉它「本轮是定时巡检，图不一定有新变动」，并顺带要求它复查在跑意图——长时间没进展的用 steer_work 纠偏，方向整个错的用 kill_work 止损。

4.3 意图队列与原子领取

「队列」不是一个内存 channel，而是数据库里的一批行。领取用的是条件 UPDATE，靠数据库的行锁保证同一个意图不会被两个 worker 抢到：

// ClaimIntent atomically moves an open intent to running. Returns true if claimed.
func (s *ExplorationStore) ClaimIntent(id int64, owner string) (bool, error) {
    res, err := s.db.Exec(`UPDATE exploration_nodes SET state='running', owner=$1
WHERE id=$2 AND exploration_id=$3 AND kind='intent' AND state='open'`, owner, id, s.expID)
    if err != nil { return false, err }
    n, _ := res.RowsAffected()
    return n == 1, nil   // 只有真正把 open 改成 running 的那个 worker 才算领到
}

配套的队列查询本身也有讲究：ORDER BY priority DESC, id ASC——高优先级的先跑，同优先级按先进先出。而 priority 是 planner 派意图时可以设置的（比如人直投的意图优先级拉满）。

4.4 意图的状态机

这张图解释了一个常被误解的设计：worker 跑完不等于成功。系统把「结束」拆成四种，因为每种对应完全不同的后续动作：

4.5 任务终局的三条路径

任务不是「跑完所有意图就结束」——它可能永远跑不完。系统定义了三种收束方式：

4.6 控制面：暂停、杀意图、纠偏

引擎对运行中的任务提供三种控制，注意它们不是同一个东西：

steer 是个很妙的设计：它不是取消重来，而是在 agent 的工具循环里插入一条 user 消息。源码里用 drainSteer(intentID) 取队列，worker 每条工具结果后检查一次——所以人可以在它「正在扫目录」时插一句「别扫了，去看 /admin 的越权」，它下一步就会转向。

5.1 一张表看清分工

5.2 planner：一个每次醒来都失忆的参谋

planner 最反直觉的地方是：每一轮唤醒都是一个全新的会话。它不记得上一轮想过什么，只能看到图。这带来一个真问题：多步利用链怎么办？

如果每轮都从零开始，「先拿凭据、再横向、再提权」这种串行链会在第一轮被一次性并行派出去——下游拿不到还不存在的前置，只会空转或重复。

实现上只有一个 map 加一把锁，键是 exploration id：

// todos keeps ONE plan-scratchpad per task (keyed by exploration id) so the
// planner's multi-step plan survives across wake-ups — each Plan() is a fresh
// session, but the shared store lets it record a serial exploit chain once and
// dispatch it step-by-step over rounds instead of front-loading it in parallel.
todoMu sync.Mutex
todos  map[int64]*actool.TodoStore

func (p *Planner) todoFor(expID int64) *actool.TodoStore {
    p.todoMu.Lock()
    defer p.todoMu.Unlock()
    s := p.todos[expID]
    if s == nil {
        s = actool.NewTodoStore()
        p.todos[expID] = s
    }
    return s
}

每轮唤醒时，清单会被渲染进 user 输入，并附上一句行为约束：

planner 还有两个「非常规」工具

这两个工具的注释里有个细节：「读上下文、跨 work 复盘是规划职责」。planner 能看到所有 worker 的输出与 trace，所以它才有资格判断「这条跑偏了」。worker 看不到全局，自然也不该有这个权力。

5.3 planner 的决策流程（提示词骨架）

它的 system prompt 是一份决策手册，不是角色扮演。五步结构非常清晰：

1. 读完整态势

   本轮触发事件 + graph_overview 预取（目标、意图、事实、资产计数、覆盖度）。不需要再调工具拿概况，细节才按需查。

2. 判目标

   对已被证明的目标调 prove_goal(goal_id, evidence_id, reason)。含量化条件的目标（覆盖度 80%、拿 N 个 flag）必须先核对实测值，未达标禁止 prove_goal。

3. （可选）极轻量探测

   只在任务刚开局、图里几乎没有 fact 时允许 1–3 次只读探测，唯一合法产物是「一句更精准的意图描述」。一旦图里有 worker 产出的事实，就禁止自己再探。

4. 决定补哪些方向

   与 open + running + recent_done 逐一比对去重。done 的看 fact 结论；exhausted/blocked 的看 trace 实际进度；保持路线多样，但多样性服从操作约束。

5. 一次批量提交

   用一次 add_intent 提交最多 4 个最高价值方向，带 summary / asset_ids / parent_ids，不要逐条多次调。

5.4 worker：一个「只做一件事」的执行者

worker 的 system prompt 开头就是三条红线：

你领到【一条意图】(一句话探索方向)，唯一职责：**完成这一条意图、把发现写回知识图谱、然后停止返回。**

**边界（红线）**：
1. **只做你领到的这一条意图**。探本意图时若瞥见本意图之外值得深挖的线索，
   **在 fact 的 summary 里点一句交给规划者**。
2. 初次受阻（payload 被过滤 / 404 / 注入无回显）不代表已探透——把本意图的
   所有绕过手段走完再输出结论；
3. 只在授权范围内操作。系统提示顶部若附【操作约束】，那是最高优先级红线。

第 1 条特别值得学：它没有简单禁止 worker「注意到别的线索」，而是给这种注意力一个合法出口——写进 fact 交给规划者。这比「不许分心」有效得多，因为分心是 LLM 的本能，堵不如疏。

三种写回，绝不串图

写 fact 有三条硬规矩，全都写进了 prompt：

为什么 worker 没有 Glob / Grep / MultiEdit

这是刻意的工具面收敛：

// worker 刻意不给 MultiEdit/Glob/Grep：文件精改用 Edit、检索走 Bash(grep/find)，
// 收敛工具面、减少低价值调用。其余 SDK 默认工具(Read/Write/Edit/LS/Bash/Sleep)照常。
base = append(base, defaultToolsExcept("MultiEdit", "Glob", "Grep")...)

给 LLM 的工具越多，它越倾向于「先搜一搜再说」。把重复能力的工具砍掉，等于强制它用 Bash 一步到位，减少无价值的往返。

5.5 worker 之间的「过程级信息交换」

一个很实际的问题：worker A 在跑的时候，某条命令的报错里泄露了一个内网地址——但它没把这条写成 fact（也许觉得不够格）。后面的 worker C 本来可以顺着这条线索走，却永远不知道。

ARTEX 的解法不是让 worker 共享上下文（那会破坏隔离），而是让它们能检索彼此的 activity 流水：

这三件套的设计意图是「信息可发现，但边界不越」：worker C 能复用 A 的观察，但它依然只做 #56 这一条意图，不会去接管 A 的活。

5.6 goals 分解器：只跑一次，但决定了后面所有事

任务创建时，这个 Agent 从「任务目标 + 描述」里抽三样东西，顺序很重要：

1. 先抽操作约束 → set_constraints

   把「不扫端口」「不做写操作」「只测某子域」这类边界登记下来，并按 allow / deny 分类。约束会被单独注入执行阶段的提示，所以必须自包含：把「当前目标」这类指代词替换成具体域名/IP。

2. 再登记测试范围 → add_task_scope

   遵循最小范围原则：目标是 https://a1b2c3.lab.example.net/path 就登记 a1b2c3.lab.example.net，绝不能缩成 example.net——那会把范围扩到授权之外。只有裸根域名或明确说「所有子域」才用 root_domain。

3. 最后拆目标 → set_goals

   只拆「最终可交付/可核验的结果」，禁止把「信息收集」「漏洞验证过程」「攻击步骤」列为子目标。多个独立交付物才拆多条。

5.7 mainagent：人的手柄，不是第二个大脑

它跑在聊天页，每次人发消息才启动。它有三类别名工具：

它有三个专用回调，是别的角色没有的：

6.1 三个工具集，三种世界观

注意几个「缺失」都是刻意的：

6.2 读工具：三级信息粒度

读工具的设计围绕一个矛盾：planner 需要全局态势，但不能把整张图塞进上下文。解法是三级粒度：

6.3 资产查询：给 LLM 一门小语言

让 LLM 写 SQL 是危险的，让它填一堆结构化参数又太笨重。ARTEX 选了中间路线：一门极简 DSL。

domain = "example.com" and port >= 8000
technology = "nginx" or technology = "php"
status_code = 200 and page_title ~ "后台"
type=service and root_domain = "example.com"

支持的字段被白名单限定在几个 map 里（字符串 / 数组 / 数值三类），解析成 AST 后再拼参数化 SQL。未知字段直接报错，绝不透传：

// knownStringFields maps DSL field name → SQL column name.
// NOTE: "type" is intentionally excluded — it is a separate parameter, not a DSL field.
var knownStringFields = map[string]string{
    "domain": "domain", "root_domain": "root_domain",
    "ip": "ip", "url": "url", "page_title": "page_title",
    "technology": "technologies", // … 白名单
}

另一个细节：list_assets 在没传 id/ids 时 dsl 不能为空，否则直接报错「不允许无条件查询全部资产」。这是一个防呆设计——LLM 很容易图省事查全表，然后在上下文里塞进 5000 条资产。

6.4 写工具：每个都有「不写什么」的定义

三个写入口的 schema 都很朴素，真正的约束在描述文本里。这些描述长达几百字，读起来像产品需求文档——因为它们确实是给模型的 API 契约：

把探索【事实/结论】写入探索图，连到产生它的意图（intent_id）。
用于记录探索结果——包括指纹/枚举等【正向结论】，和'端口关闭'/'参数不可注入'/
'未发现登录入口'等【否定结论】。
…
**多个观察汇总成【一条】事实**（summary 一句总结 + detail 写对总结的拓展）…
**只写增量**：只记这次【新得到】的，别把已有事实换措辞重记…
**只写真实看到的**：给 evidence（一行：命令+最能证明的一两行输出），
标 confidence（observed=直接看到 / inferred=据现象推断）。

6.5 工具不是固定的：三层动态装配

一个 Agent 最终能看到的工具，是三次过滤的结果：

延迟工具（deferred tools）：为什么要把 schema 藏起来

MCP 服务器可能有几十个工具，每个的 schema 都塞进 system prompt，光工具定义就吃掉几千 token，而且模型会忍不住乱调。ARTEX 的做法是：

• 全局可用的 MCP 工具：只在 system 末尾列名字，schema 不注入；
• 技能门控的 MCP 工具：连名字都不出现，直到对应 Skill 被加载才解锁；
• 系统提示末尾的 <available-deferred-tools> 块作为最后一个 segment，配合 DynamicBoundary 让整段 system 可缓存。

这套机制还处理了一个隐蔽的 bug：主 agent 每轮新建会话，内存里的「已解锁集合」会重置。所以 seedUnlockFromHistory 会重放历史里的 Skill() 调用，把解锁状态恢复出来——否则模型能看到工具名，却调不动。

panic 防护：一个工具崩了不该带走整个进程

// guardPanic turns a panicking tool handler into an ordinary tool error. The
// harness runs each tool on its own goroutine, so a panic inside a handler can't
// be recovered by the caller that started the run — it takes the whole process
// down, and on restart the agent replays the same call and crashes again.
// Applied last, so it covers every tool the agent can reach: domain, SDK, MCP and skill.
func guardPanic(t actool.CoreTool) actool.CoreTool { return &guardedTool{CoreTool: t} }

最后这句「在重启后重放同一个调用又会崩」是关键：工具 panic 不是一次故障，而是无限重启循环。所以必须在工具边界兜住。

7.1 三段式：可编辑的身体 + 不可编辑的尾巴

每个 Agent 的 system prompt 都由三部分拼成，分界线是「谁拥有它」：

func workerSystem(proxyAddr, caCert, dataDir, runDir string) string {
    body := renderSystem("worker", workerDefaultTmpl, WorkerVars{ProxyAddr: proxyAddr, DataDir: dataDir, Now: nowStr()})
    // caCert 只在录制 MITM 开启时存在，正好是 traffic_* 工具注册的时候 → 用它门控说明块
    return body + workerTrafficBlock(caCert != "") + workerArtifactSpec(runDir)
}   //        ↑ 段 B：代码固定            ↑ 段 C：代码固定

注意段 B 的门控条件：它看的是 caCert != ""（录制开启），而不是「有没有配代理」。因为如果只是走了全局代理、没开录制，traffic_* 工具根本不存在，讲它们的用法只会让模型去调一个不存在的工具。

7.2 模板变量与「永不半渲染」

内置默认 prompt 本身就是 Go template，和用户存进数据库的版本走同一套渲染：

func renderSystem(agentKey, def string, vars any) string {
    tmpl := def
    if PromptOverride != nil {
        if t, ok := PromptOverride(agentKey); ok && t != "" { tmpl = t }
    }
    if out, err := renderTmpl(tmpl, vars); err == nil { return out }
    // DB 模板坏了（比如引用了目录外的变量）→ 回退代码默认
    if out, err := renderTmpl(def, vars); err == nil { return out }
    return def
}

三层兜底：用户模板 → 内置模板 → 原始字符串。加上 Option("missingkey=error")，用户只要写了一个不存在的变量，整段模板就渲染失败并回退——而不是渲染出一堆 <no value> 让模型困惑。

7.3 最精彩的一处取舍：态势放 user，意图放 system

planner 和 worker 在这件事上做了相反的决定，而且源码里明确解释了为什么：

7.4 收尾词：预算耗尽也要把话说完

Agent 跑到步数上限或超时被掐断，最容易烂尾——发现了五个事实，一个都没写回。ARTEX 的处理是不让它直接死，而是进入一个「结算回合」：

你即将因预算耗尽被终止。不要再运行任何命令/探测。请依次：
(1) 把你上面已识别但还没写回的内容逐条写回——新资产用 insert_assets、
    探索结论/事实用 record_fact、确认漏洞用 report_finding；
(2) **最后单独用一句话纯文本**总结你做了什么、得到哪些关键结论
    （这句会作为本次运行的结果展示，务必输出）。

配套的机制还有：

• 结算回合隐藏 Bash（Settlement.DisabledTools），从物理上阻止它继续探测；
• 墙钟到点会打断在跑的工具并在活 ctx 上就地进结算，不是粗暴 kill；
• 任务级 deadline 夹逼单个 run 的预算时，收尾词会切换成「任务到点」的版本，而不是「你自己步数用完了」——这两句话对模型的含义完全不同。

7.5 操作约束：最高优先级的红线

goals 分解器抽出的约束，会以一段独立文本注入 planner / worker 的 system prompt 末尾：

【操作约束】（最高优先级，覆盖上面所有常规流程）
- 禁止：不扫端口；不得对生产环境做写/删操作；禁止爆破
- 允许：只测试 abc.example.net；仅针对目标端口 443

三个细节值得注意：

这是所有长任务 Agent 系统都会撞上的墙：工具输出越攒越多，20 轮之后上下文就满了。ARTEX 用了四层互不干扰的机制，每层解决不同尺度的问题。

8.1 cold-digest：把「冷掉的推理链」压成摘要

这一层是 ARTEX 最有原创性的设计。它解决的问题不是「对话太长」，而是「图太大，planner 每轮读不动」。

什么是冷节点

一个节点如果连续 R 个规划轮次都没有任何下游分支（没有新事实从它派生、没有新意图引用它），它就被判定为「冷」。系统用 cold_since_round 记录它变冷的那一轮，用 round_no 记录当前轮次。

怎么折

不是随机打包，而是按连通性分组：把通过上游/下游边相连的冷节点聚成一块，再让 LLM 为这一块写一段摘要，生成 kind=digest 的新节点，并用 covers 边指向所有成员。

并发与正确性

后台折叠最怕的是「折叠期间节点复活了」——摘要刚生成，那个节点又被新意图引用了，于是 digest 覆盖了一个活跃节点。解法是提交时再检查一次存活：

// Concurrency: one compaction per task at a time (mutex), ≥cooldown between runs,
// and a commit-time liveness recheck drops any member that revived while the body
// was being generated so a digest never covers a hot node.

再加三道闸：每任务同时只跑一个折叠（mutex）、两次折叠间隔 ≥60s（cooldown）、单次折叠硬上限 5 分钟。全部在后台 goroutine，绝不阻塞规划主路径。

折叠后还能展开吗

能。planner 有 expand_digest 工具，可以按「摘要正文 → 成员列表 → 具体节点 detail」三级展开。这意味着折叠是无损的索引压缩，不是删除。

8.2 旁路提问：别在主线程里问闲话

人在任务跑到一半时想问「这个 CVE 是什么来着？」——如果走主对话，会把这条问答永久写进 transcript，挤占上下文，还可能干扰 agent 的判断。

ARTEX 的做法是 /btw 旁路：

1. 抓快照

   主 Agent 每次模型请求前后，把结构化消息、system prompt、工具定义、生成参数深拷贝成一份不可变快照。

2. 独立回答

   旁路服务用「快照 + 最近成功问答 + 新问题」发一次独立请求，不创建 agent session、不接工具执行器、不写主 transcript。

3. 独立历史

   问答存在 side_question_requests 表，可追问、可停止、可清空。清空只影响旁路，主上下文快照保留。

8.3 token 账本

所有这些机制要能调优，前提是知道 token 花在哪。系统在每个 activity 上记四个数：input_tokens / output_tokens / cache_read_tokens / cache_write_tokens，并按任务、会话、日维度聚合。

-- Task-list polls aggregate result usage and find the latest event repeatedly.
-- Cover the token columns for index-only aggregation and the timestamp order for
-- per-exploration latest-activity lookups.
CREATE INDEX IF NOT EXISTS idx_act_result_usage ON activity(exploration_id)
  INCLUDE (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
  WHERE kind='result';

这个 partial index 是个典型的 PG 优化：仪表盘要频繁按任务聚合 token，用覆盖索引（INCLUDE）就能走 index-only scan，不回表。设计文档里连「为什么是这个索引」都写在注释里。

这套系统让 LLM 直接跑 Bash、发 HTTP、调 Kali 工具。安全设计不能靠「模型应该不会乱来」，必须在工具调用边界做强制拦截。ARTEX 用了三道闸，粒度从粗到细。

9.1 三道闸的分工

9.2 拦截规则：三种动作，一套优先级

规则的结构比想象中完整——它不只是「匹配什么」，还包括超时后怎么办：

type InterceptRule struct {
    Name           string // 人类可读的名字
    Enabled        bool
    Priority       int    // 数值越大越先匹配
    MatchTarget    string // tool / input / both
    MatchType      string // string / regex
    Pattern        string
    Action         string // allow / deny / ask
    Message        string // 返回给模型的解释
    TimeoutEnabled bool   // ask 等多久
    TimeoutSeconds int
    TimeoutAction  string // 超时是放行还是拒绝
}

9.3 LLM 裁判：规则匹配不到时的兜底

正则规则永远写不全。ARTEX 提供可选的「LLM 裁判」：规则未命中时，把工具名 + 完整参数交给一个判定模型，让它输出 allow / deny / ask。

dec, matched := g.interceptor.Match(ev.ToolName, ev.Input)
if !matched {
    // No rule matched. Ask the LLM fallback judge (if enabled); when it is off
    // or unwired, keep current behavior and allow.
    d, judged := g.interceptor.Judge(ctx, ev.ToolName, ev.Input)
    if !judged { return hook.Result{} }
    dec = d
}
switch dec.Action {
case "deny":  /* 记 denied，返回 block */
case "allow": /* 记 allowed，放行 */
case "ask":   /* 创建 pending，阻塞等待人工 */
}

注意 judged=false 时是放行，不是拒绝。这是刻意的：裁判服务挂了不应该让整个系统停摆，硬边界仍然由规则层保证。这是一个「可用性优先于这一层」的取舍，前提是规则层已经覆盖了真正危险的类别。

9.4 那句写给模型的拦截文案

这是整个安全设计里最容易被忽略、但最精妙的一处。guard 返回给模型的不是「禁止执行此工具」，而是：

【ARTEX 平台管控·非目标防御】此调用被平台拦截。原因：…。此操作被禁止。

源码注释解释了为什么要加这个前缀：

9.5 审批的等待与审计

一次 ask 的完整生命周期：

1. 创建 pending 记录

   写入 intercept_pending，同时往当前会话的 activity 流写一条 intercept_request，于是它会内联出现在对话记录里，人不用去另一个页面找。

2. 阻塞等待

   为这条请求建一个 channel，worker 的 goroutine 阻塞在上面。人在 UI 点「批准 / 拒绝」→ HTTP handler 调 Decide(pendingID, allowed) → 唤醒 channel。

3. 超时处理

   按规则配置的 timeout_seconds 与 timeout_action 决定放行还是拒绝；ctx 取消则立即拦截。

4. 落审计

   无论 allow / deny / ask 的结果，都写一条 intercept_log，带工具名、参数、规则、判定、耗时。审批记录页可展开看完整调用详情。

审计侧还有一个「失败归因」机制（源码里叫 Observer / G5）：PostToolUse 钩子把 Bash 结果分成三类：

这三类的区分让 planner 能做出不同判断：blocked 说明目标有防护，要换绕过思路；error 说明自己命令写错了，要修命令。如果都归为「失败」，模型只会盲目重试。

9.6 为什么「内置规则」也放在数据库里

系统预置的破坏性/外泄拦截规则，不是硬编码在 Go 里，而是以普通 [内置] 规则的形式 seed 进数据库，用户可以禁用甚至删除。

10.1 为什么必须留痕

渗透测试的结论如果没有原始请求响应，就等于「我说有洞」。留痕解决三个问题：

10.2 架构：代理 + 文件树 + 旁路索引

10.3 三个让工具「零配置」的细节

细节一：把代理和 CA 塞进子进程环境

worker 跑的 curl 不该需要人教它加 -x 和 -k。所以系统在启动 Bash 子进程时注入一整套环境变量：

HTTP_PROXY / HTTPS_PROXY / http_proxy / https_proxy / ALL_PROXY …
NODE_USE_ENV_PROXY=1          // Node 24+ 的内置 fetch 才会读代理变量
SSL_CERT_FILE=…               // curl / urllib / Go / openssl
CURL_CA_BUNDLE=…              // curl 专用
REQUESTS_CA_BUNDLE=…          // python requests 不读 SSL_CERT_FILE
GIT_SSL_CAINFO=…              // git
NODE_EXTRA_CA_CERTS=…         // node

注释里有一句经验之谈：「Each ecosystem reads a different CA var (verified empirically)」——每个生态读的变量不一样，是实测出来的。还有个容易漏的点：curl 读 socks5 代理只认 ALL_PROXY，不读 HTTP(S)_PROXY，所以两个都设。

细节二：大正文溢出到 blob，索引只留指针

一个 200MB 的下载响应不能塞进 SQLite。系统对超过阈值的正文做 spill：正文按 sha256 存成文件，索引里只留 @blob sha256:… 标记。agent 要看时用 traffic_blob(hash) 分段读。

细节三：搜索必须先指定 host

traffic_search 强制要求 host 参数，且默认只返回 3 条极轻量索引（id / method / url / status / resp_len，不含响应内容）。要看正文得再调 traffic_get(id)。

这和 list_assets 的防呆是同一个思路：不让模型一次拿到海量数据。但它留了一个强大的例外——body_contains 可以在请求/响应正文里做全文搜索（至少 3 字符，支持中文），用来找密码、密钥、报错、内网地址。

10.4 证据：与流量解耦的不可变副本

流量是「可丢弃的」——用户可能清理磁盘、归档任务、只保留证据。所以报告用的证据不能直接引用流量 ID，必须独立存一份。

// Package evidence preserves finding evidence independently of disposable traffic.
func hashPath(dir, hash string) (string, error) {
    if len(hash) != 64 { return "", errors.New("invalid evidence hash") }
    if _, err := hex.DecodeString(hash); err != nil || strings.ToLower(hash) != hash {
        return "", errors.New("invalid evidence hash")
    }
    return filepath.Join(dir, "blobs", hash[:2], hash+".bin"), nil
}

三个设计点：

• 严格的 hash 校验：必须 64 位、小写十六进制、能 hex 解码。这防的是路径穿越——如果 hash 可以是 ../../etc/passwd，读证据就变成了任意文件读取。
• 两级目录：hash[:2] 分桶，避免单目录几十万文件。
• 写入后校验：verifyFile 重新算 sha256 比对，确认落盘内容没坏。

10.5 流量与漏洞的绑定

一条漏洞可以绑定多条流量，且顺序有意义（复现步骤的先后）。绑定不是随便挑几个 ID，而是有明确的判定纪律：

11.1 归属：显式 vs 范围推导

一个资产属于哪家公司？系统允许两种来源，且永远不会互相覆盖：

company_scope：五种范围规则

表上有一个 CHECK 约束做「三选一」：domain 规则必须有 domain、ip/cidr 必须有 net、icp/keyword 必须有 value，其余字段为 NULL。这样不可能出现「kind=domain 但 net 有值」的脏数据。

11.2 task_scope：授权边界 = 覆盖度的分母

任务级范围比公司级更严格，因为它是这次任务的授权边界：

11.3 覆盖度的公式（以及它为什么是「约」）

target AS (          -- 分母：task_scope 命中的资产去重
  SELECT DISTINCT a.id, a.type, …
  FROM assets a JOIN task_scope ts ON ts.task_id = $1 AND (
       (ts.kind='company'     AND a.company_id = ts.company_id)
    OR (ts.kind='root_domain' AND a.root_domain = ts.domain)
    OR (ts.kind='subdomain'   AND a.domain = ts.domain)
    OR (ts.kind IN ('ip','cidr') AND ts.net >>= try_inet(a.ip))
    OR (ts.kind='icp' AND …)
  )
),
tested AS (          -- 分子：本探索中被 fact 锚定过的资产
  SELECT DISTINCT ea.asset_id
  FROM exploration_anchors ea
  JOIN exploration_nodes en ON en.id = ea.node_id
  WHERE en.exploration_id = $2 AND en.kind = 'fact'
)

所以：

源码注释里明确写着「Reference figure only（仅供参考）」。为什么不敢说精确？

11.4 覆盖图：把「测到哪了」画出来

资产覆盖图是一个力导向布局的包含关系图：company → root_domain → subdomain / ip → service → endpoint，外加 app 挂到 company。

11.5 enrich：不靠 LLM 的自动补全

有些事不需要模型判断，纯工程就能做：解析域名、探 HTTP。这些交给 enrich 引擎，异步、带冷却、可去重。

const (
    cooldown    = 5 * time.Minute   // 同一资产 5 分钟内不重复解析/探测
    httpTimeout = 12 * time.Second
    queueSize   = 1024              // 有界队列：满了就丢，不阻塞写入
)

它做两件事：

• DNS 解析：用 dnsx 解析域名，把结果写成 IP 节点 + 解析关系，回填 record_type / record_value。
• HTTP 探测：对站点发一次请求，抓 title、status_code、technologies、favicon hash，并且走记录代理——所以补全产生的流量也会进录制库。

11.6 资产同步：从 ScopeSentry 直接导入

实际工作中，资产往往已经在别的系统里收集过了。ARTEX 支持按项目/任务维度从 ScopeSentry 同步域名、子域、IP、端口、站点、端点，一键导入并按公司范围归并，直接进入资产图供 agent 使用。

这一步的产品意义大于技术意义：它把「资产收集」和「自主测试」解耦了。你不需要让 ARTEX 从零开始扫全网，它可以只做「拿到一批资产后，自主决定怎么打」。

12.1 LLM 池：一条链 + 一个全进程熔断器

自主系统最怕的不是漏洞打不出来，而是跑到一半模型没额度了。ARTEX 的做法是把多个 LLM 配置串成一条降级链：

三个值得学的点：

llmrec：记录「线上的原始字节」

常规的 LLM 调用日志记的是规范化后的请求对象——但排查问题时，你需要的往往是「实际发出去的 JSON 长什么样」。所以系统在 HTTP transport 层挂了捕获器：

// This exists because everything the Recorder itself sees is already normalized:
// llm.CompletionRequest is re-serialized rather than the body buildBody() sent, and
// the response arrives as decoded StreamEvents, not the SSE frames. For debugging a
// live provider, the bytes on the wire are the only ground truth.
//
// norma's doStream retries the request-establishment phase, so one Stream can issue
// several HTTP attempts. Each attempt is kept: the discarded ones … are exactly what
// makes rate-limit and gateway failures diagnosable.

注意「每次重试都保留」这个细节：被丢弃的失败尝试，才是诊断限流和网关问题的关键证据。只记最后一次成功请求，等于把故障现场擦干净了。

12.2 任务级并发：上限与排队

同时跑 20 个任务，每个 3 个 worker，就是 60 个 LLM 并发——大多数账号扛不住。所以系统有一个任务级并发上限：

最后一条是个典型的并发陷阱：两个 goroutine 都读到「还有 1 个空位」，于是各启动一个任务，超限了。解法不是加锁保护计数，而是把「检查 + 占用」串行化。

12.3 任务级超时：到点不是杀死，是收尾

建单时可以设 timeout_seconds。到点后的处理顺序很讲究：

1. 停止发新活

   worker 循环看到 isSettling 就不再领新意图；planner 的普通唤醒被丢弃（收尾轮由协调器直接驱动）。

2. 给在跑的 run 注入收尾词

   通过 ctx 携带的 deadline 夹逼 MaxDuration，让每个 run 自然进入结算回合，把已识别的写回。

3. 等 drain

   协调器等待在跑的 worker 结束（有上限），不是无限等。

4. 落终态

   用 SetTerminalStatusGuarded 做 CAS，避免和用户手动暂停 / 删除打架。

12.4 归档：把任务打包成可搬运的证据

任务跑完不能一直占着数据库。归档会把任务、探索图、资产关联、活动记录、LLM 记录、旁路问答打包成一个压缩包（当前格式版本 3，兼容 v1/v2）。

12.5 自更新：三次启动的原子换装

这是整个项目里最「运维」的一段代码，也是最值得学的工程范式：把易错逻辑放进强类型语言，把守护循环留给脚本。

12.6 通知：叶子包 + 拨号守卫

漏洞发现后要推送到钉钉/飞书/企微/Webhook/Telegram/邮件。这个子系统被刻意做成不依赖数据库、不依赖 server 的叶子包：

// 分层：本包是**叶子包**，只依赖标准库。它不认识数据库、不认识 server。渠道配置
// 以 map[string]any 传入（对应 notification_channels.config 这一 JSONB 列），
// 待推送内容以 Message 传入。这样拆开的好处是：签名计算、UTF-8 截断、过滤匹配这些
// 真正容易出错的地方可以脱离 PostgreSQL 单测，宿主只需在 server 侧做编排。
//
// 并发约定：Channel 的实现必须**无状态**。同一个 Channel 实例会被多个渠道配置
// （甚至同一渠道的多个机器人实例）并发复用，所有凭据一律从 cfg 参数传入。

「无状态」这条约束很关键：钉钉的加签、飞书的 timestamp+sign，如果实现里缓存了某个 webhook 的 secret，多个机器人实例并发复用就会串号。所有凭据从参数传入，实例就天然可复用。

SSRF 防护：在拨号那一刻检查

通知目标 URL 是用户填的，天然是一个 SSRF 入口。系统没有只在保存配置时校验，而是在 http.Transport 的 DialContext.Control 钩子里检查——因为那才是最终生效点，能同时挡住 DNS 重绑定和同主机重定向。

// isBlockedDialIP 报告目标 IP 是否属于「默认不允许投递」的地址段。
//
// 只拒绝环回、链路本地（含云元数据 169.254.169.254）、未指定与组播。
// **不拒绝** RFC1918 私网：内网自建 Mattermost / SMTP 中继是很常见的合法用法，
// 把它们一并挡掉会让功能在真实环境里直接不可用。这条取舍是刻意的——
// 防护要挡住真正敏感的目标，同时不能把正常部署一起废掉。

12.7 可观测性

三个入口，覆盖三种排障场景：

即使你完全不关心渗透测试，这个项目的 Go 代码本身就是一份很好的「长任务系统」参考实现。下面这些手法在任何一个后台服务里都用得上。

13.1 并发：任务是一组有名字的 goroutine

每个任务启动 1 + N 个 goroutine，全部登记在一个 taskRuntime 里，统一用 runTaskRoutine 包裹。这样做的目的不是「优雅」，而是可观测与可停止：

rt := e.registerTaskRoutines(ctx, t.ID, 1+workers)
e.touch(t.ID)
runTaskRoutine(rt, func(loopCtx context.Context) { e.plannerLoop(loopCtx, t) })
for i := 0; i < workers; i++ {
    name := fmt.Sprintf("work#%d", i+1)
    runTaskRoutine(rt, func(loopCtx context.Context) { e.workerLoop(loopCtx, t, name) })
}
e.startDeadlineCoordinator(ctx, t)

为什么 worker 用 work#1..N 这样的固定槽位名，而 transcript 用 exp{id}-worker-i{intentID}？因为槽位是可复用的，意图不是。用槽位名做会话 ID，第二条意图会读到第一条的对话历史——这是一个非常隐蔽的 bug，源码注释专门点出来了。

13.2 context：四种取消原因必须分开

整个系统里，一个 run 可能因为四种完全不同的原因被取消。如果都当成「取消」，后续处理会全错：

实现上用 context.WithCancelCause 而不是普通 cancel——context.Cause(ctx) 能取回具体原因，引擎据此决定「重排队、标 stopped、还是标 blocked」。这就是 agent/cancelcause.go 存在的意义。

13.3 状态机的 CAS：谁先写谁赢

任务终态是竞争最激烈的地方：planner 判完成、用户点暂停、超时协调器落 timeout，可能同时发生。系统用「带条件的 UPDATE」做仲裁：

// SetTerminalStatusGuarded sets a terminal status only when the task is NOT already
// in a terminal state. Returns won=false when another terminal status already stuck —
// the caller then leaves it alone.
UPDATE tasks SET status=$1, completed_at=…
WHERE id=$2 AND status NOT IN ('done','failed','timeout')

这个模式在整个项目里反复出现：意图状态转换有 ErrIntentStateConflict、归档有 Archive...Failed 状态、审批有 pending 的原子解析。不要用「先读再判断再写」，那是竞态的温床。

13.4 生命周期锁：不要直接读写共享字段

Task 结构体有很多会被并发修改的字段（status、paused、deadline…）。代码里有一条明确约定：

// taskLifecycleState is an internally consistent view of the mutable task
// lifecycle and inherited-scope context. Callers must use lifecycleSnapshot and
// updateLifecycle instead of reading or writing the corresponding Task fields
// directly after the task has been published by Manager.

做法是把可变字段打包成一个快照结构，读的时候一次性拷贝出来（lifecycleSnapshot()），写的时候在锁里改（updateLifecycle(func(*state))）。好处是：

• 不会读到「status 已改成 done 但 completed_at 还是 0」这种撕裂状态；
• 调用方拿到的是一份不会变的副本，不用一直持锁；
• 所有写路径集中在一处，容易审计。

13.5 幂等迁移：「重启即迁移」

没有 migration 工具、没有版本号表，只有一个每次启动都全量跑的 schema.sql。它必须满足一个强条件：跑 1 次和跑 100 次结果一样。

DO $$
BEGIN
    IF EXISTS (
        SELECT 1 FROM pg_constraint
        WHERE conrelid='exploration_nodes'::regclass
          AND conname='ck_node_kind'
          AND pg_get_constraintdef(oid) NOT LIKE '%digest%'
    ) THEN
        ALTER TABLE exploration_nodes DROP CONSTRAINT ck_node_kind;
        ALTER TABLE exploration_nodes ADD CONSTRAINT ck_node_kind
            CHECK (kind IN ('begin','goal','intent','fact','finding','hint','digest'));
    END IF;
END $$;

这段 SQL 解决的是 CHECK 约束的「只能新建、不能修改」问题：先查现有约束定义里有没有新值，没有才重建。比「无脑 DROP 再 ADD」安全（后者在并发启动时可能互相踩），也比「要求用户手动执行迁移」友好。

13.6 脏数据防御：两行代码挡住两类线上事故

渗透工具的输出是「野生字节」：nmap 的乱码、二进制响应、截断的 UTF-8。直接写 PG 会失败，而且是静默失败（activity 记录悄悄丢了）。所以每个字符串入库前都过一遍：

// utf8Clean: 替换非法 UTF-8 为 U+FFFD，并去掉 NUL (0x00) 字节。
// PG 的 UTF8 编码拒绝非法字节序列（"invalid byte sequence"），
// 而 NUL 是合法 UTF-8（U+0000）却被 text 列拒绝（SQLSTATE 22021）——所以要单独删。
// jsonbClean: json.Marshal 会把 NUL 编码成 \u0000，json 类型能存，jsonb 会拒绝（22P05）。

这段注释的信息量很大：两类列、两种失败码、两个不同的清洗函数。而且 jsonbClean 还要判断反斜杠的奇偶——\\u0000 是字面文本，不能删。这种「看起来只是 trim 一下」的代码，背后是对 PG 编码规则的精确理解。

13.7 nil 安全与 typed-nil

Agent 可能在「没有资产库」「没有流量」「没有 LLM」的情况下被构造（测试、编排、降级）。所以大量可选依赖用 nil 表示「该能力不可用」，且每个工具内部自己 guard：

if t.cs == nil { return actool.Errorf("list_companies 未启用: CompanyStore 未初始化"), nil }

// typed-nil guard: only set when concrete (avoids harness panic)
if hooks != nil { opts.Hooks = hooks }

第二行是个 Go 的经典坑：把一个 (*Guard)(nil) 赋给 interface 类型的 Hooks，interface 本身不为 nil，调用方法时就会 panic。所以必须先判具体类型再赋。

13.8 有界与冷却：所有旁路都要有闸

旁路任务（enrich、通知、归档）如果无限制地堆积，会把主流程拖死。项目里所有旁路都有三道闸：

13.9 降级而不是崩溃

系统里到处是「做不到就退一步」的代码，而不是「做不到就报错」：

// bumpDrop increments and returns the running count of dropped (unpersistable)
// activity records for a task. Concurrent planner + worker emits race here, so the
// counter is an atomic behind sync.Map. The count in the log shows loss scale at a
// glance instead of forcing a grep-and-count.

注意这里的设计意图：允许丢，但必须知道丢了多少。比起让一条脏 activity 把整个任务写崩，丢掉它并计数是更好的选择。

13.10 叶子包与依赖方向

依赖图是单向的，叶子包不反向依赖：

cmd/artex
   └── server ──┬── agent ──┬── db
                │           └── intercept
                ├── guard ────── intercept
                ├── traffic ──── db
                ├── llmpool ──── (norma/llm)
                ├── llmrec ───── (标准库)
                ├── notify ───── (只用标准库)
                ├── evidence ─── db + traffic
                ├── report ───── db
                └── selfupdate ─ (标准库)

notify 和 selfupdate 都是纯标准库实现。这不是洁癖，而是让最容易出错的部分（签名、哈希、换装）可以脱离数据库跑单测。

13.11 测试策略：表驱动 + 真实 PG

153 个测试文件，覆盖密度很高。几个特点：

• db 包用真实 PostgreSQL（testmain_test.go 起库、跑 schema），因为要测的是 SQL 语义，mock 没意义；
• 纯算法抽成无依赖文件（coldgraph.go 不 import db / llm），可以纯单测冷热判定与分组；
• 竞态与生命周期专项测试：company_lock_test.go、task_delete_concurrency_test.go、task_context_lock_test.go——这些都是实际出过 bug 的地方；
• 端到端捕获测试：provider_capture_e2e_test.go 验证真实 HTTP 报文捕获链路。

13.12 注释：记录「为什么」，不记录「是什么」

这个项目的注释密度极高，但几乎不解释代码在做什么，而是解释为什么这样、不这样会怎样：

这些注释的价值在于：它们把设计决策的上下文固化了。半年后有人想简化代码，会先看到「这里为什么不能简化」。

把前面所有章节串起来，看一个任务从创建到归档会经过什么。每一步都标注了「谁做的」和「写进了哪张表」。

1. ① 建单（POST /api/tasks）

   写入 tasks 行 + 新建 explorations 行（这次任务的探索空间）+ 写入 begin 根节点。如果设了并发上限且已满，任务标记 queued 排队。
   代码：Manager.CreateTaskWithOptions / db.CreateTask

2. ② 目标分解（goals agent，只跑一次）

   LLM 读「目标 + 描述」，产出：操作约束（task_constraints）、测试范围（task_scope）、目标节点（exploration_nodes, kind=goal）。
   如果 LLM 不可用，回退到规则拆分，保证 goal 节点一定存在。

3. ③ 启动引擎（Engine.Run）

   起 1 个 plannerLoop + N 个 workerLoop，启动 deadline 协调器。如果已有 open/running 意图（种子意图），跳过首轮规划；否则踢第一轮。
   关键判断：HasActiveIntent()（open + running），不是只数 open。

4. ④ 第一轮规划

   planner 读到「图几乎是空的」，于是根据 goal 派 2–4 条初始意图（侦察、指纹、目录、端口…），带 asset_ids 锚定到范围内资产。
   产物：intent 节点（state=open）+ spawns 边。

5. ⑤ worker 领取

   空闲 worker 轮询 frontier，用条件 UPDATE 抢到一条意图，状态变 running，owner 记成 work#2。构造 system prompt（含意图 + 目标资产原始数据），Resume 该意图的历史 transcript（如有）。

6. ⑥ 执行与留痕

   每一轮工具调用：PreToolUse 过审批门 → 执行 → PostToolUse 归因 → 写 activity。HTTP 流量进 MITM 代理，落文件树 + SQLite 索引。
   每个工具结果都可能触发一手写回：insert_assets / record_fact / report_finding。

7. ⑦ 图变更 → 唤醒 planner

   worker 的写回触发 t.Notify()；引擎 800ms debounce 后跑下一轮规划。planner 看到本轮触发事件（done / finding），判断要不要补方向。
   这是闭环的核心：写回本身就是下一轮的输入。

8. ⑧ 串行链推进（可能多轮）

   如果存在依赖链，planner 用共享 todo 记录整条链，每轮只派「前置已满足」的一步。新事实出现 → 下一轮派下一步。
   期间可能有人插话：steer_work 纠偏、add_hint 加提示、add_intent 直投。

9. ⑨ 目标证明

   某条 finding/fact 足以证明 goal 时，planner 调 prove_goal(goal_id, evidence_id, reason)，写入 proves 边，goal 状态变 met。
   当最后一个 open goal 被标 met → 系统判定任务完成 → 取消在跑 worker。

10. ⑩ 收尾与终态

    任务状态落 done / failed / timeout（CAS 保证只有一个赢家）。在跑的 worker 进入结算回合，把已识别的写回，最后输出一句总结。

11. ⑪ 报告与复测

    report 包从探索图渲染 Markdown：漏洞列表（含严重级、证据、PoC）+ 资产统计。漏洞可发起复测——独立的 retester agent 会话，结论三选一（仍可复现 / 已修复 / 无法确认）。
    复测成功且判「已修复」时，自动把漏洞处置状态改为已修复。

12. ⑫ 归档

    任务暂停或终态后，可归档成压缩包（格式 v3）：任务、探索图、活动、LLM 记录、旁路问答。归档后从主库移除，需要时再恢复。

14.1 一张时序图看关键交互

14.2 如果中途出问题，会发生什么

学一个系统最好的方式不是记它做了什么，而是理解它在哪些岔路口选了哪条、放弃了什么。下面是这个项目里最重要的 14 个取舍。

15.1 如果让我重做，哪些地方可以更好

客观地说，这套设计也有明显的成本和风险，读代码时应该带着批判：

不要从 main.go 开始逐行读——这个项目的入口很薄，真正的结构在数据模型和引擎里。按下面的顺序，每一天都能独立跑通一小块。

16.1 读码时的三个技巧

17.1 术语表

17.2 文件地图：想改什么，去哪里

17.3 常用命令

# 本地开发：后端 :8787 + 流量代理 :8788 + 前端 :5173
./dev.sh

# 只跑后端（不内嵌前端）
go run ./cmd/artex

# 全量测试
go test ./...

# 构建单二进制（需要先把前端导出到 server/webui/dist）
cd web && npm ci && npm run build:static && cd ..
cp -r web/out server/webui/dist
CGO_ENABLED=0 go build -tags embedui -o artex ./cmd/artex

# 跨平台发布包
./build.sh --release

18.1 最后一页：这套系统的三句话