foliko 1.0.65 → 1.0.67

package/skills/ambient-agent/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: ambient-agent
+description: Ambient Agent - 持续后台运行的智能代理，用于主动监控事件和执行操作
+allowed-tools: ambient_goals,ambient_status,ambient_think,ambient_remember,ambient_control
+---
+
+# Ambient Agent
+
+Ambient Agent 是一个持续后台运行的智能代理，监控事件并主动执行操作。
+
+## 核心概念
+
+### Goal（目标）
+目标是对话式 LLM 派发的任务，包含：
+- `title` - 目标标题
+- `description` - 目标描述
+- `priority` - 优先级 1-10
+- `actions` - 要执行的操作列表
+- `conditions` - 激活条件（如监听特定事件）
+- `state` - 状态：`pending` | `active` | `completed` | `failed`
+
+### Action（操作）
+操作是目标的最小执行单元，有三种类型：
+
+| 类型 | 说明 | 参数 |
+|------|------|------|
+| `tool` | 调用工具 | `name` 工具名, `args` 参数 |
+| `message` | 发送消息 | `content` 消息内容 |
+| `think` | 触发思考 | `topic` 主题, `mode` 模式, `depth` 深度 |
+
+### Event（事件）
+目标可以监听框架事件：
+- `tool:result` - 工具执行结果
+- `scheduler:reminder` - 定时提醒
+- `agent:message` - 代理消息
+- `email:received` - 收到邮件
+- `webhook:received` - Webhook 接收
+
+## 工具
+
+### ambient_goals - 目标管理
+
+```javascript
+// 列出所有目标
+await ambient_goals({ action: 'list' })
+
+// 创建目标
+await ambient_goals({
+  action: 'create',
+  title: '监控邮件',
+  description: '定期检查新邮件',
+  priority: 8,
+  actions: [
+    { id: 'check-email', type: 'tool', name: 'email_list', args: { box: 'INBOX' } }
+  ],
+  conditions: {
+    events: ['email:received']
+  }
+})
+
+// 更新目标
+await ambient_goals({
+  action: 'update',
+  goalId: 'xxx-xxx',
+  title: '新标题',
+  actions: [...]  // 新操作列表
+})
+
+// 删除目标
+await ambient_goals({ action: 'delete', goalId: 'xxx-xxx' })
+
+// 激活目标
+await ambient_goals({ action: 'activate', goalId: 'xxx-xxx' })
+```
+
+### ambient_status - 获取状态
+
+```javascript
+await ambient_status({})
+// 返回: { running, tickCount, activeGoals, pendingGoals, recentActivities }
+```
+
+### ambient_think - 触发思考
+
+```javascript
+await ambient_think({
+  goalId: 'xxx-xxx',  // 可选，关联目标
+  mode: 'reflect',     // reflect | brainstorm | plan | analyze
+  topic: '反思主题',    // 可选
+  depth: 2              // 可选，1-5
+})
+```
+
+### ambient_remember - 记忆管理
+
+```javascript
+// 存储记忆
+await ambient_remember({
+  action: 'store',
+  key: 'user-preference',
+  content: '用户喜欢在早上收到摘要'
+})
+
+// 检索最近记忆
+await ambient_remember({
+  action: 'retrieve',
+  limit: 10
+})
+
+// 搜索记忆
+await ambient_remember({
+  action: 'search',
+  query: '邮件'
+})
+```
+
+### ambient_control - 控制循环
+
+```javascript
+// 暂停
+await ambient_control({ action: 'pause' })
+
+// 恢复
+await ambient_control({ action: 'resume' })
+
+// 调整参数
+await ambient_control({
+  action: 'adjust',
+  tickInterval: 10000,    // 新 tick 间隔（毫秒）
+  cooldownPeriod: 5000    // 新冷却时间（毫秒）
+})
+```
+
+## action 与 step 的关系
+
+Ambient Agent 的 action 与 Workflow Engine 的 step 共用 `StepExecutor` 执行：
+
+```
+action.type → step.type
+───────────────────────
+tool      → tool
+message   → message
+think     → think
+```
+
+这意味着：
+- 变量引用语法一致：`{{variableName}}`
+- sessionId 传递机制一致
+- 错误处理方式一致
+
+## action 执行上下文
+
+当 action 执行时，可用的上下文：
+
+```javascript
+// context.variables 中可用
+context.variables._event      // 触发的事件数据（如果有）
+context.variables._action     // 当前执行的 action 对象
+context.variables.loopIndex   // 循环索引（如果被 loop 执行）
+
+// context.input 中可用
+context.input                 // 工作流/目标输入参数
+```
+
+## 创建目标的最佳实践
+
+1. **明确目标标题** - 让用户清楚知道目标意图
+2. **设置合适优先级** - 高优先级目标会被优先处理
+3. **操作要原子化** - 每个 action 只做一件事
+4. **设置冷却时间** - 避免同一目标过度频繁执行
+5. **检查循环** - 同一 action 连续失败 3 次会判定为循环
+
+## 示例：创建邮件自动回复目标
+
+**重要**：`email:received` 事件的 `email` 对象包含：
+- `email.from` - 发件人地址
+- `email.to` - 收件人地址
+- `email.subject` - 邮件主题
+- `email.body` - 邮件正文
+
+使用 `{{}}` 语法从事件中提取参数：
+
+```javascript
+await ambient_goals({
+  action: 'create',
+  title: '邮件自动回复',
+  description: '收到邮件后自动回复发件人',
+  priority: 8,
+  actions: [
+    {
+      id: 'auto-reply',
+      type: 'tool',
+      name: 'email_auto_reply',
+      args: {
+        to: '{{_event.email.from}}',
+        subject: '{{_event.email.subject}}',
+        body: '{{_event.email.body}}'
+      }
+    }
+  ],
+  conditions: {
+    events: ['email:received']
+  }
+})
+```
+
+**错误示例**（缺少参数）：
+```javascript
+// ❌ 错误 - 没有传递必需参数
+{ type: 'tool', name: 'email_auto_reply', args: {} }
+
+// ✅ 正确 - 从事件中提取参数
+{ type: 'tool', name: 'email_auto_reply', args: {
+    to: '{{_event.email.from}}',
+    subject: '{{_event.email.subject}}',
+    body: '{{_event.email.body}}'
+  }
+}
+```
+
+**注意**：`email_auto_reply` 需要 `to`、`subject`、`body` 三个必需参数，必须从 `{{_event.email.xxx}}` 提取。
+
+## 生命周期
+
+```
+Goal 创建 → [条件满足] → ACTIVE → 执行 actions → COMPLETED/FAILED
+                ↑                              ↓
+                └────── 重新激活 ← ─────────────┘
+```
+
+- **pending** - 待激活，满足条件后自动变为 active
+- **active** - 执行中，循环处理 actions
+- **completed** - 所有 actions 执行完毕
+- **failed** - 达到最大尝试次数或检测到循环

package/skills/workflow-guide/SKILL.md

@@ -138,6 +138,45 @@ allowed-tools: execute_workflow,reloadWorkflows
 }
 ```
 
+**重要：使用 `{{result}}` 引用上一步结果（推荐）**
+
+上一步骤的结果自动保存在 `{{result}}` 中，可以直接提取字段：
+
+```json
+{
+  "type": "tool",
+  "name": "获取IP",
+  "tool": "fetch",
+  "args": {
+    "url": "https://api.ipify.org?format=json"
+  }
+},
+{
+  "type": "tool",
+  "name": "发送通知",
+  "tool": "notification_send",
+  "args": {
+    "title": "IP 信息",
+    "message": "当前公网IP: {{result.body.ip}}"
+  }
+}
+```
+
+支持的引用格式：
+
+| 格式 | 说明 |
+|------|------|
+| `{{result}}` | 上一步完整结果 |
+| `{{result.body}}` | 提取 body 字段 |
+| `{{result.body.ip}}` | 从 body 提取嵌套字段 |
+| `{{result.body.data[0].name}}` | 支持数组索引 |
+| `{{lastResult}}` | result 的别名 |
+| `{{lastResult.error}}` | 从错误对象提取信息 |
+| `{{variables.xxx}}` | 显式引用 context.variables |
+| `{{input.xxx}}` | 引用工作流输入参数 |
+
+**自动 JSON 解析**：如果字段值是 JSON 字符串，会自动解析为对象后再提取嵌套字段。
+
 ### 3. loop - 循环步骤
 
 重复执行一组步骤：
@@ -215,6 +254,7 @@ allowed-tools: execute_workflow,reloadWorkflows
 
 ### 示例：获取IP并发送通知
 
+**推荐写法**（使用 `{{result}}` 直接引用上一步结果）：
 ```json
 {
   "name": "get-ip-notify",
@@ -227,23 +267,41 @@ allowed-tools: execute_workflow,reloadWorkflows
       "args": {
         "url": "https://api.ipify.org?format=json",
         "proxy": true
-      },
+      }
+    },
+    {
+      "type": "tool",
+      "name": "发送通知",
+      "tool": "notification_send",
+      "args": {
+        "title": "IP 信息",
+        "message": "当前公网IP: {{result.body.ip}}"
+      }
+    }
+  ]
+}
+```
+
+**旧写法**（仍支持，但不推荐）：
+```json
+{
+  "name": "get-ip-notify-old",
+  "steps": [
+    {
+      "type": "tool",
+      "tool": "fetch",
+      "args": { "url": "https://api.ipify.org?format=json" },
       "outputVariable": "ipResult"
     },
     {
       "type": "script",
-      "name": "提取IP",
       "outputVariable": "currentIp",
       "script": "var r=context.variables.ipResult; return (r&&r.success&&r.body)?(typeof r.body==='object'?r.body.ip:r.body.trim()):'获取失败';"
     },
     {
       "type": "tool",
-      "name": "发送通知",
       "tool": "notification_send",
-      "args": {
-        "title": "IP 信息",
-        "message": "当前公网IP: {{currentIp}}"
-      }
+      "args": { "message": "当前公网IP: {{currentIp}}" }
     }
   ]
 }
@@ -282,13 +340,15 @@ allowed-tools: execute_workflow,reloadWorkflows
 
 ## 注意事项
 
-1. **script 必须 return**：`script` 是函数体，必须用 return 返回值
-2. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
-3. **JSON 中不能有注释**：注释会导致 JSON 解析失败
-4. **context.variables** 在所有步骤间共享，可存储中间结果
-5. **context.input** 是工作流的输入参数
-6. 循环变量 `i` 从 0 开始计数
-7. 条件分支的 `condition` 是 JavaScript 表达式字符串
+1. **优先使用 `{{result}}` 引用**：上一步结果直接用 `{{result.field}}` 提取，比 script 更简洁
+2. **script 必须 return**：`script` 是函数体，必须用 return 返回值
+3. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
+4. **JSON 中不能有注释**：注释会导致 JSON 解析失败
+5. **context.variables** 在所有步骤间共享，可存储中间结果
+6. **context.input** 是工作流的输入参数
+7. 循环变量 `i` 从 0 开始计数
+8. 条件分支的 `condition` 是 JavaScript 表达式字符串
+9. **自动 JSON 解析**：`{{result.body}}` 如果是 JSON 字符串会自动解析
 
 ## 最佳实践