mirror of
https://github.com/Ed1s0nZ/CyberStrikeAI.git
synced 2026-07-11 06:43:49 +02:00
公明
198 lines
5.4 KiB
Markdown
198 lines
5.4 KiB
Markdown
# Agent 与角色指南
|
|
|
|
CyberStrikeAI 的 Agent 行为由三类资源共同决定：角色、子代理和 Skills。角色决定当前任务身份和可用工具；子代理决定多代理分工；Skills 提供可按需加载的专题知识与流程。
|
|
|
|
## 角色
|
|
|
|
角色文件位于 `roles/`，格式为 YAML。角色通常包含：
|
|
|
|
- 名称。
|
|
- 描述。
|
|
- 系统提示词。
|
|
- 可用工具列表。
|
|
|
|
设计原则：
|
|
|
|
- 专用角色只绑定必要工具。
|
|
- 提示词明确授权边界。
|
|
- 对高风险操作要求先说明影响并等待审批。
|
|
- 输出格式尽量稳定，便于报告和复盘。
|
|
|
|
示例方向：
|
|
|
|
- 信息收集。
|
|
- Web 应用扫描。
|
|
- API 安全测试。
|
|
- 云安全审计。
|
|
- 数字取证。
|
|
- 二进制分析。
|
|
- CTF。
|
|
|
|
## 单代理
|
|
|
|
单代理接口：
|
|
|
|
- `POST /api/eino-agent`
|
|
- `POST /api/eino-agent/stream`
|
|
|
|
适合：
|
|
|
|
- 快速问答。
|
|
- 单目标测试。
|
|
- 工具链较短的任务。
|
|
- 需要稳定上下文的交互式分析。
|
|
|
|
## 多代理模式
|
|
|
|
多代理接口：
|
|
|
|
- `POST /api/multi-agent`
|
|
- `POST /api/multi-agent/stream`
|
|
|
|
编排模式：
|
|
|
|
- `deep`：主代理拆解任务，按需调用子代理。
|
|
- `plan_execute`：先规划，再执行，必要时重规划。
|
|
- `supervisor`：主管代理根据进展转交不同子代理。
|
|
|
|
适合：
|
|
|
|
- 多阶段渗透测试。
|
|
- 大范围信息收集。
|
|
- 需要并行角色分工的分析。
|
|
- 长任务和批量任务。
|
|
|
|
## 子代理 Markdown
|
|
|
|
子代理位于 `agents/*.md`。Front matter 示例：
|
|
|
|
```yaml
|
|
---
|
|
name: Attack Surface Enumeration
|
|
id: attack-surface-enumeration
|
|
description: 枚举目标暴露面并整理可验证线索
|
|
tools:
|
|
- subfinder
|
|
- nmap
|
|
- http-framework-test
|
|
bind_role: 信息收集
|
|
max_iterations: 300
|
|
---
|
|
```
|
|
|
|
正文写系统提示词。建议包含：
|
|
|
|
- 职责边界。
|
|
- 输入期望。
|
|
- 使用工具顺序。
|
|
- 输出格式。
|
|
- 禁止事项。
|
|
|
|
## 主代理
|
|
|
|
主代理可用：
|
|
|
|
- `agents/orchestrator.md`
|
|
- `agents/orchestrator-plan-execute.md`
|
|
- `agents/orchestrator-supervisor.md`
|
|
|
|
或在 front matter 中设置 `kind: orchestrator`。每种编排只应有一个主代理定义。
|
|
|
|
## 工具选择
|
|
|
|
工具选择顺序建议：
|
|
|
|
1. 角色绑定最小工具集。
|
|
2. 子代理按任务补充专用工具。
|
|
3. `tool_search` 动态解锁大量工具。
|
|
4. 高风险工具由 HITL 审批。
|
|
|
|
不要给所有角色默认绑定全部工具，否则上下文成本和误调用风险都会上升。
|
|
|
|
## 提示词建议
|
|
|
|
好的角色提示词应说明：
|
|
|
|
- 只在授权范围内行动。
|
|
- 先确认目标和约束。
|
|
- 对写入、删除、爆破、持久化、C2、WebShell 等操作请求审批。
|
|
- 输出可复核证据。
|
|
- 不确定时标注假设，不编造结果。
|
|
|
|
## 调试
|
|
|
|
如果 Agent 选错工具：
|
|
|
|
- 缩小角色工具列表。
|
|
- 增强工具 `short_description`。
|
|
- 开启或调整 `tool_search_always_visible_tools`。
|
|
- 在角色提示词中明确工具使用顺序。
|
|
|
|
如果多代理跑偏：
|
|
|
|
- 检查子代理描述是否过宽。
|
|
- 降低 `sub_agent_user_context_max_runes` 或明确任务输入。
|
|
- 优化 orchestrator 提示词。
|
|
- 查看过程详情和工具执行监控。
|
|
|
|
## 角色、子代理、Skill 的职责边界
|
|
|
|
三者经常混用，建议这样分工：
|
|
|
|
| 资源 | 解决的问题 | 不适合承载 |
|
|
| --- | --- | --- |
|
|
| Role | 当前对话的身份、语气、工具边界和授权规则 | 大量参考资料 |
|
|
| Agent Markdown | 多代理中的专业分工、交接格式和局部策略 | 一次性任务事实 |
|
|
| Skill | 可复用方法论、检查清单、模板和长参考资料 | 权限控制 |
|
|
|
|
如果把授权边界写进 Skill，而角色没有限制工具，Agent 仍可能在未加载 Skill 前选错工具。权限边界应优先放在 Role 和 HITL 中。
|
|
|
|
## 编排模式选择
|
|
|
|
| 模式 | 适合 | 不适合 |
|
|
| --- | --- | --- |
|
|
| `eino_single` | 短任务、交互式分析、需要稳定上下文 | 多阶段大任务 |
|
|
| `deep` | 主代理动态拆分任务，子代理按需深入 | 需要严格步骤顺序的流程 |
|
|
| `plan_execute` | 有明确阶段、需要执行后复盘和重规划 | 用户频繁打断的即兴对话 |
|
|
| `supervisor` | 专家分工明确，需要主管路由 | 子代理定义含糊或过多 |
|
|
|
|
经验上，普通安全测试先用 `eino_single`；复杂项目用 `plan_execute`；需要多个专业角色时用 `deep` 或 `supervisor`。
|
|
|
|
## 工具可见性如何影响行为
|
|
|
|
多代理里 `tool_search` 会让模型一开始只看见部分常驻工具。结果是：
|
|
|
|
- 工具页面显示可用，不代表模型当前上下文可见。
|
|
- `tool_search_always_visible_tools` 里的工具更容易被模型调用。
|
|
- 工具描述越清晰，越容易被搜索命中。
|
|
- 子代理自己的 `tools` 限制仍然很重要。
|
|
|
|
调试“Agent 为什么不用某工具”时，要同时检查角色工具、子代理工具、tool_search 配置和工具描述。
|
|
|
|
## 好的子代理输出格式
|
|
|
|
子代理不要只返回“已完成”。建议固定格式：
|
|
|
|
```markdown
|
|
## 结论
|
|
|
|
## 证据
|
|
- 命令/工具：
|
|
- 关键输出：
|
|
- 置信度：
|
|
|
|
## 风险
|
|
|
|
## 建议下一步
|
|
```
|
|
|
|
这样主代理才能继续编排，也方便攻击链和项目事实沉淀。
|
|
|
|
## 源码锚点
|
|
|
|
- Markdown Agent 解析：`internal/agents/markdown.go`
|
|
- 多代理准备：`internal/handler/multi_agent_prepare.go`
|
|
- 编排实现：`internal/multiagent/eino_orchestration.go`
|
|
- 工具搜索中间件：`internal/multiagent/eino_middleware.go`
|
|
- 子代理上下文：`internal/multiagent/sub_agent_context_test.go`
|