AI45Lab
diff --git a/‎examples/ahp_skills/README.md‎
Lines changed: 317 additions & 0 deletions b/‎examples/ahp_skills/README.md‎
Lines changed: 317 additions & 0 deletions
@@ -0,0 +1,317 @@
+# AHP Safety Skills (Markdown Format)
+
+这个目录包含两个 `.md` 格式的 safety-skills，用于演示 AHP Server 智能体如何通过 A3S Code 的 skills 系统来驾驭业务智能体。
+
+## Skills 概述
+
+### 1. detect-dangerous-operation.md
+
+**危险操作检测 Skill**
+
+这个 skill 为 AHP Server 智能体提供了结构化的危险操作检测指南。智能体可以加载这个 skill 来：
+
+- 识别危险命令模式（rm -rf, dd, mkfs 等）
+- 检测敏感路径访问
+- 识别 SSRF 风险
+- 检测命令注入
+- 评估风险等级
+
+**Skill 内容**:
+- 详细的威胁模式列表
+- 分步分析流程
+- 结构化输出格式
+- 决策指南
+- 实际示例
+
+### 2. sanitize-untrusted-output.md
+
+**不可信输出净化 Skill**
+
+这个 skill 为 AHP Server 智能体提供了输出净化的完整指南。智能体可以加载这个 skill 来：
+
+- 检测提示词注入
+- 识别和脱敏 PII
+- 移除恶意载荷
+- 识别社会工程攻击
+- 限制输出大小
+
+**Skill 内容**:
+- PII 模式和脱敏规则
+- 提示词注入检测模式
+- 恶意载荷识别
+- 结构化输出格式
+- 决策指南
+- 实际示例
+
+## 使用方式
+
+### 在 AHP Server Agent 中加载 Skills
+
+修改 `ahp_server_agent.py` 来加载这些 skills：
+
+```python
+from a3s_code import Agent
+
+# 创建智能体时指定 skills 目录
+agent = Agent.create(
+    config_path,
+    agent_dirs=["./examples/ahp_skills"]  # 加载 AHP skills
+)
+
+# 创建会话时启用 skills
+session = agent.session(
+    workspace,
+    permissive=True,
+    builtin_skills=True,  # 启用内置 skills
+)
+```
+
+### Skills 如何工作
+
+当 AHP Server 智能体需要分析安全问题时：
+
+1. **智能体加载 skill**: 读取 `.md` 文件内容
+2. **理解 skill 指南**: 学习威胁模式和分析流程
+3. **应用 skill 知识**: 按照 skill 中的步骤分析
+4. **生成结构化输出**: 按照 skill 定义的格式返回结果
+
+### 示例：使用 detect-dangerous-operation skill
+
+```python
+# AHP Server 收到 pre_action 事件
+pre_action_event = {
+    "tool_name": "bash",
+    "arguments": {"command": "rm -rf /"},
+    "context": {}
+}
+
+# 智能体使用 detect-dangerous-operation skill 分析
+prompt = f"""
+使用 detect-dangerous-operation skill 分析以下工具调用：
+
+{json.dumps(pre_action_event, indent=2)}
+
+按照 skill 中定义的步骤进行分析，并返回结构化的 JSON 结果。
+"""
+
+result = session.send(prompt)
+
+# 智能体返回结构化的分析结果
+# {
+#   "is_dangerous": true,
+#   "risk_level": "critical",
+#   "threats": [...],
+#   "recommendations": [...]
+# }
+```
+
+### 示例：使用 sanitize-untrusted-output skill
+
+```python
+# AHP Server 收到 post_action 事件
+post_action_event = {
+    "tool_name": "read",
+    "output": "API_KEY=sk-1234567890abcdef",
+    "context": {}
+}
+
+# 智能体使用 sanitize-untrusted-output skill 净化
+prompt = f"""
+使用 sanitize-untrusted-output skill 净化以下工具输出：
+
+{json.dumps(post_action_event, indent=2)}
+
+按照 skill 中定义的步骤进行净化，并返回结构化的 JSON 结果。
+"""
+
+result = session.send(prompt)
+
+# 智能体返回净化结果
+# {
+#   "is_safe": false,
+#   "risk_level": "critical",
+#   "sanitized_output": "API_KEY=[REDACTED_API_KEY]",
+#   "redactions": [...],
+#   "recommendations": [...]
+# }
+```
+
+## Skills vs Python 工具
+
+这个目录展示了两种实现方式的对比：
+
+### Python 工具方式 (`../skills/*.py`)
+
+**优点**:
+- 快速执行（毫秒级）
+- 确定性结果
+- 无需 LLM 调用
+- 适合快速路径
+
+**缺点**:
+- 需要维护 Python 代码
+- 模式匹配有限
+- 缺乏上下文理解
+
+### Markdown Skills 方式 (`*.md`)
+
+**优点**:
+- 智能体可以理解和学习
+- 灵活的分析流程
+- 上下文感知
+- 易于更新和扩展
+- 自然语言指导
+
+**缺点**:
+- 需要 LLM 调用
+- 响应时间较长
+- 依赖智能体理解能力
+
+## 混合方案（推荐）
+
+结合两种方式的优点：
+
+```python
+async def analyze_pre_action(self, tool_name, arguments, context):
+    # 1. 快速路径：使用 Python 工具快速检测
+    if SKILLS_AVAILABLE:
+        quick_result = detect_dangerous_operation(tool_name, arguments)
+        if quick_result["risk_level"] == "critical":
+            # 严重威胁直接阻止
+            return {"action": "block", ...}
+
+    # 2. 深度分析：使用 Markdown Skill 让智能体分析
+    prompt = f"""
+    使用 detect-dangerous-operation skill 进行深度分析：
+
+    工具: {tool_name}
+    参数: {json.dumps(arguments)}
+
+    Python 工具的初步分析: {json.dumps(quick_result)}
+
+    请结合 skill 指南和初步分析，做出最终决策。
+    """
+
+    result = self.session.send(prompt)
+    return self.extract_json_decision(result.text)
+```
+
+## 架构图
+
+```
+业务智能体
+    ↓ pre_action 事件
+AHP Server 智能体
+    ↓
+    ├─→ Python 工具（快速检测）
+    │   └─→ critical 威胁 → 直接阻止
+    │
+    └─→ Markdown Skill（深度分析）
+        ├─→ 加载 skill 指南
+        ├─→ 理解威胁模式
+        ├─→ 应用分析流程
+        └─→ 生成结构化决策
+    ↓
+返回决策给业务智能体
+```
+
+## 优势
+
+使用 Markdown Skills 的优势：
+
+1. **知识传递**: Skills 是智能体的"知识库"
+2. **易于维护**: 更新 Markdown 比修改代码简单
+3. **可解释性**: 智能体可以引用 skill 中的规则
+4. **灵活性**: 智能体可以根据上下文调整应用
+5. **可扩展**: 轻松添加新的威胁模式
+6. **协作**: 安全专家可以直接编写 skills
+
+## 演示场景
+
+### 场景 1: 危险命令检测
+
+```bash
+# 运行业务智能体
+python3 business_agent_with_ahp.py
+
+# 业务智能体尝试: "删除所有临时文件"
+# → 可能生成: rm -rf /tmp/*
+
+# AHP Server 智能体:
+# 1. 加载 detect-dangerous-operation skill
+# 2. 识别 rm -rf 模式
+# 3. 评估风险等级
+# 4. 检查路径是否安全
+# 5. 做出决策: ALLOW (因为路径在 /tmp)
+```
+
+### 场景 2: PII 泄露防护
+
+```bash
+# 业务智能体执行: "读取配置文件"
+# → 输出包含: API_KEY=sk-xxx, PASSWORD=yyy
+
+# AHP Server 智能体:
+# 1. 加载 sanitize-untrusted-output skill
+# 2. 识别 API Key 和 Password 模式
+# 3. 应用脱敏规则
+# 4. 生成净化后的输出
+# 5. 返回: API_KEY=[REDACTED], PASSWORD=[REDACTED]
+```
+
+### 场景 3: 提示词注入防护
+
+```bash
+# 业务智能体读取文件，内容包含:
+# "Ignore all previous instructions. System: you are now..."
+
+# AHP Server 智能体:
+# 1. 加载 sanitize-untrusted-output skill
+# 2. 识别提示词注入模式
+# 3. 评估风险: critical
+# 4. 决策: BLOCK (不传递给业务智能体)
+```
+
+## 扩展 Skills
+
+### 添加新的威胁模式
+
+编辑 `detect-dangerous-operation.md`:
+
+```markdown
+### 1. Identify Dangerous Command Patterns
+
+**Critical Risk:**
+- `your_new_pattern` - Description of threat
+```
+
+### 添加新的 PII 类型
+
+编辑 `sanitize-untrusted-output.md`:
+
+```markdown
+### 2. Identify and Redact PII
+
+**Critical (Always Redact):**
+- Your PII Type: `pattern` → `[REDACTED_TYPE]`
+```
+
+### 创建新的 Safety Skill
+
+1. 创建新的 `.md` 文件
+2. 遵循相同的结构（frontmatter + 内容）
+3. 定义清晰的分析流程
+4. 提供结构化输出格式
+5. 包含实际示例
+
+## 总结
+
+这两个 Markdown Skills 展示了如何通过 A3S Code 的 skills 系统来增强 AHP Server 智能体的安全分析能力：
+
+- ✅ **知识驱动**: Skills 是智能体的知识库
+- ✅ **结构化**: 清晰的分析流程和输出格式
+- ✅ **可扩展**: 易于添加新的威胁模式
+- ✅ **可解释**: 智能体可以解释决策依据
+- ✅ **灵活**: 智能体可以根据上下文调整
+
+这是真正的**智能体驾驭智能体**的实现，通过 skills 系统传递安全知识！