foliko 1.1.6 → 1.1.7

package/skills/ambient-agent/SKILL.md

@@ -1,314 +1,342 @@
----
-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}`（Ambient Agent 使用 `${}`)
-- sessionId 传递机制一致
-- 错误处理方式一致
-
-## action 执行上下文
-
-当 action 执行时，可用的上下文：
-
-```javascript
-// context.variables 中可用
-context.variables._event; // 触发的事件数据（如果有）
-context.variables._action; // 当前执行的 action 对象
-context.variables.loopIndex; // 循环索引（如果被 loop 执行）
-
-// context.input 中可用
-context.input; // 工作流/目标输入参数
-```
-
-## 变量引用语法
-
-Ambient Agent 使用 `${}` 语法在 action 参数中引用变量：
-
-### 1. 事件数据引用 `${event.xxx}`
-
-当 goal 监听事件时，事件数据可通过 `${event.xxx}` 直接引用：
-
-```javascript
-{
-  id: 'auto-reply',
-  type: 'tool',
-  name: 'email_auto_reply',
-  args: {
-    to: '${event.from}',
-    subject: '${event.subject}',
-    body: '${event.text}',
-    from: ''
-  }
-}
-```
-
-**注意**：`email:received` 事件的数据结构：
-
-- `event.from` - 发件人地址
-- `event.subject` - 邮件主题
-- `event.text` - 邮件正文（纯文本）
-- `event.body` - 邮件正文（可能含 HTML）
-- `event.messageId` - 邮件消息 ID
-
-### 2. 多步骤引用 `${actionId.output.field}`
-
-当有多个顺序执行的 action 时，后续 action 可以引用前一个 action 的输出：
-
-```javascript
-actions: [
-  {
-    id: 'read-email',
-    type: 'tool',
-    name: 'email_read',
-    args: { limit: 1, unreadOnly: true },
-  },
-  {
-    id: 'process',
-    type: 'tool',
-    name: 'some_processor',
-    args: {
-      // 引用 read-email 输出的 emails 数组的第一个元素的 from 字段
-      sender: '${read-email.output.emails[0].from}',
-    },
-  },
-];
-```
-
-### 3. 变量解析规则
-
-`${}` 语法支持嵌套属性访问：
-
-- `${event.from}` - 直接字段
-- `${actionId.output.field}` - 嵌套字段
-- `${event.data.xxx}` - data 对象内的字段（兼容性别名）
-
-## 创建目标的最佳实践
-
-1. **明确目标标题** - 让用户清楚知道目标意图
-2. **设置合适优先级** - 高优先级目标会被优先处理
-3. **操作要原子化** - 每个 action 只做一件事
-4. **设置冷却时间** - 避免同一目标过度频繁执行
-5. **检查循环** - 同一 action 连续失败 3 次会判定为循环
-
-## 示例：创建邮件自动回复目标
-
-**重要**：`email:received` 事件的数据结构：
-
-- `event.from` - 发件人地址
-- `event.subject` - 邮件主题
-- `event.text` - 邮件正文（纯文本）
-- `event.messageId` - 邮件消息 ID
-
-使用 `${}` 语法从事件中提取参数：
-
-```javascript
-await ambient_goals({
-  action: 'create',
-  title: '邮件自动回复',
-  description: '收到邮件后自动回复发件人',
-  priority: 8,
-  actions: [
-    {
-      id: 'auto-reply',
-      type: 'tool',
-      name: 'email_auto_reply',
-      args: {
-        to: '${event.from}',
-        subject: '${event.subject}',
-        body: '${event.text}',
-        from: '',
-      },
-    },
-    {
-      id: 'mark-read',
-      type: 'tool',
-      name: 'email_mark_read',
-      args: {
-        messageId: '${event.messageId}',
-      },
-    },
-  ],
-  conditions: {
-    events: ['email:received'],
-  },
-});
-```
-
-**错误示例**（缺少参数）：
-
-```javascript
-// ❌ 错误 - 没有传递必需参数
-{ type: 'tool', name: 'email_auto_reply', args: {} }
-
-// ✅ 正确 - 从事件中提取参数
-{ type: 'tool', name: 'email_auto_reply', args: {
-    to: '${event.from}',
-    subject: '${event.subject}',
-    body: '${event.text}',
-    from: ''
-  }
-}
-```
-
-**注意**：`email_auto_reply` 需要 `to`、`subject`、`body` 三个必需参数，必须从 `${event.xxx}` 提取。由于 `email:received` 事件已携带邮件数据，不需要额外的 `email_read` 步骤来读取邮件。
-
-## 生命周期
-
-```
-Goal 创建 → [条件满足] → ACTIVE → 执行 actions → COMPLETED/FAILED
-                ↑                              ↓
-                └────── 重新激活 ← ─────────────┘
-```
-
-- **pending** - 待激活，满足条件后自动变为 active
-- **active** - 执行中，循环处理 actions
-- **completed** - 所有 actions 执行完毕
-- **failed** - 达到最大尝试次数或检测到循环
+---
+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` - 激活条件（如监听特定事件）
+- `persistent` - 是否持久化（默认 true，false 为一次性任务）
+- `state` - 状态：`pending` | `active` | `completed` | `failed`
+
+### Action（操作）
+
+操作是目标的最小执行单元，有三种类型：
+
+| 类型      | 说明     | 参数                                    |
+| --------- | -------- | --------------------------------------- |
+| `tool`    | 调用工具 | `name` 工具名, `args` 参数              |
+| `message` | 发送消息 | `content` 消息内容                      |
+| `think`   | 触发思考 | `topic` 主题, `mode` 模式, `depth` 深度 |
+
+每个 action 有 `completed` 标记，执行完成后标记为 true。
+
+### Event（事件）
+
+目标可以监听以下框架事件：
+
+| 事件                       | 触发时机          | 数据结构                                                                        |
+| -------------------------- | ----------------- | ------------------------------------------------------------------------------- | ---- |
+| `email:received`           | 收到新邮件        | `{uid, messageId, from, to, subject, text, body, html, attachments, timestamp}` |
+| `webhook:received`         | 收到 Webhook 请求 | `{path, method, query, body, timestamp}`                                        |
+| `webhook:processed`        | Webhook 处理完成  | `{path, method, query, body, response, timestamp}`                              |
+| `scheduler:task_created`   | 定时任务创建      | `{taskId, taskName, type, scheduleTime, cronExpression}`                        |
+| `scheduler:reminder`       | 定时提醒触发      | `{taskId, message, time}`                                                       |
+| `scheduler:task_completed` | 定时任务完成      | `{taskId, result}`                                                              |
+| `scheduler:task_failed`    | 定时任务失败      | `{taskId, error}`                                                               |
+| `think:thought_completed`  | 思考完成          | `{mode, topic, thought, depth}`                                                 |
+| `tool:result`              | 工具执行成功      | `{name, args, result, source}` (source: tool                                    | mcp) |
+| `tool:error`               | 工具执行错误      | `{name, args, error, source}` (source: tool                                     | mcp) |
+| `tool:call`                | 工具被调用        | `{name, args, source}` (source: tool                                            | mcp) |
+| `agent:message`            | Agent 发送消息    | `{content, sessionId, userMessage}`                                             |
+| `worker:completed`         | Worker 完成       | `{workerId, name, result, notification}`                                        |
+| `worker:error`             | Worker 错误       | `{workerId, name, error, notification}`                                         |
+| `subagent:chat:end`        | 子 Agent 聊天结束 | `{parentAgent, subAgent, subAgentName, result}`                                 |
+
+## 工具
+
+### ambient_goals - 目标管理
+
+```javascript
+// 列出所有目标
+await ambient_goals({ action: 'list' })
+
+// 创建持久化目标（默认）- 事件驱动，执行完等待下一事件
+await ambient_goals({
+  action: 'create',
+  title: '监控邮件',
+  description: '收到邮件后自动回复',
+  priority: 8,
+  persistent: true,  // 默认 true，持久化目标
+  actions: [
+    { id: 'auto-reply', type: 'tool', name: 'email_auto_reply', args: {...} }
+  ],
+  conditions: {
+    events: ['email:received']
+  }
+})
+
+// 创建一次性目标 - 执行完自动完成，不等待新事件
+await ambient_goals({
+  action: 'create',
+  title: '处理定时提醒',
+  description: '提醒到达后执行一次操作',
+  priority: 8,
+  persistent: false,  // 一次性任务
+  actions: [
+    { id: 'process', type: 'tool', name: 'some_tool', args: {...} }
+  ],
+  conditions: {
+    events: ['scheduler:reminder']
+  }
+})
+
+// 更新目标
+await ambient_goals({
+  action: 'update',
+  goalId: 'xxx-xxx',
+  title: '新标题',
+  persistent: false,  // 改为一次性
+  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}`（Ambient Agent 使用 `${}`)
+- sessionId 传递机制一致
+- 错误处理方式一致
+
+## action 执行上下文
+
+当 action 执行时，可用的上下文：
+
+```javascript
+// context.variables 中可用
+context.variables._event; // 触发的事件数据（如果有）
+context.variables._action; // 当前执行的 action 对象
+context.variables.loopIndex; // 循环索引（如果被 loop 执行）
+
+// context.input 中可用
+context.input; // 工作流/目标输入参数
+```
+
+## 变量引用语法
+
+Ambient Agent 使用 `${}` 语法在 action 参数中引用变量：
+
+### 1. 事件数据引用 `${event.xxx}`
+
+当 goal 监听事件时，事件数据可通过 `${event.xxx}` 直接引用：
+
+```javascript
+{
+  id: 'auto-reply',
+  type: 'tool',
+  name: 'email_auto_reply',
+  args: {
+    to: '${event.from}',
+    subject: '${event.subject}',
+    body: '${event.text}',
+    from: ''
+  }
+}
+```
+
+**注意**：`email:received` 事件的数据结构：
+
+- `event.from` - 发件人地址
+- `event.subject` - 邮件主题
+- `event.text` - 邮件正文（纯文本）
+- `event.body` - 邮件正文（可能含 HTML）
+- `event.messageId` - 邮件消息 ID
+
+### 2. 多步骤引用 `${actionId.output.field}`
+
+当有多个顺序执行的 action 时，后续 action 可以引用前一个 action 的输出：
+
+```javascript
+actions: [
+  {
+    id: 'read-email',
+    type: 'tool',
+    name: 'email_read',
+    args: { limit: 1, unreadOnly: true },
+  },
+  {
+    id: 'process',
+    type: 'tool',
+    name: 'some_processor',
+    args: {
+      // 引用 read-email 输出的 emails 数组的第一个元素的 from 字段
+      sender: '${read-email.output.emails[0].from}',
+    },
+  },
+];
+```
+
+### 3. 变量解析规则
+
+`${}` 语法支持嵌套属性访问：
+
+- `${event.from}` - 直接字段
+- `${actionId.output.field}` - 嵌套字段
+- `${event.data.xxx}` - data 对象内的字段（兼容性别名）
+
+## 创建目标的最佳实践
+
+1. **明确目标标题** - 让用户清楚知道目标意图
+2. **设置合适优先级** - 高优先级目标会被优先处理
+3. **操作要原子化** - 每个 action 只做一件事
+4. **选择合适的持久化模式** - 需要持续监控用 `persistent: true`，一次性任务用 `persistent: false`
+5. **检查循环** - 同一 action 连续失败 3 次会判定为循环
+
+## 示例：创建邮件自动回复目标
+
+`email:received` 事件的数据结构：
+
+- `event.from` - 发件人地址
+- `event.subject` - 邮件主题
+- `event.text` - 邮件正文（纯文本）
+- `event.body` - 邮件正文（与 text 相同）
+- `event.messageId` - 邮件消息 ID
+- `event.uid` - 邮件 UID（数字）
+
+```javascript
+await ambient_goals({
+  action: 'create',
+  title: '邮件自动回复',
+  description: '收到邮件后自动回复发件人',
+  priority: 8,
+  persistent: false, // 一次性任务，回复完成后不再等待新邮件
+  actions: [
+    {
+      id: 'auto-reply',
+      type: 'tool',
+      name: 'email_auto_reply',
+      args: {
+        to: '${event.from}',
+        subject: '${event.subject}',
+        body: '${event.text}',
+      },
+    },
+  ],
+  conditions: {
+    events: ['email:received'],
+  },
+});
+```
+
+**错误示例**（缺少参数）：
+
+```javascript
+// ❌ 错误 - 没有传递必需参数
+{ type: 'tool', name: 'email_auto_reply', args: {} }
+
+// ✅ 正确 - 从事件中提取参数
+{ type: 'tool', name: 'email_auto_reply', args: {
+    to: '${event.from}',
+    subject: '${event.subject}',
+    body: '${event.text}',
+  }
+}
+```
+
+**注意**：`email_auto_reply` 需要 `to`、`subject`、`body` 三个必需参数，必须从 `${event.xxx}` 提取。由于 `email:received` 事件已携带邮件数据，不需要额外的 `email_read` 步骤来读取邮件。
+
+## 生命周期
+
+```
+Goal 创建 → [条件满足] → ACTIVE → 执行 actions → COMPLETED/FAILED
+                ↑                              ↓
+                └────── 重新激活 ← ─────────────┘（仅 persistent=true）
+```
+
+- **pending** - 待激活，满足条件后自动变为 active
+- **active** - 执行中，循环处理 actions
+- **completed** - 所有 actions 执行完毕（一次性任务执行完后直接完成）
+- **failed** - 达到最大尝试次数或检测到循环
+
+**persistent 行为**：
+
+- `persistent: true`（默认）- 事件驱动目标，actions 执行完后等待下一事件再次执行
+- `persistent: false` - 一次性目标，所有 actions 执行完后直接完成，不等待新事件