CyberStrikeAI/docs/zh-CN/agent-and-role-guide.md

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 示例：

---
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 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