@loom-framework/core 0.1.0-alpha.191 → 0.1.0-alpha.195

package/builtin-skills/app-skill/references/models.md

@@ -29,8 +29,10 @@
 | 语法 | 示例 | 说明 |
 |------|------|------|
 | 等值匹配 | `{"subject":"数学"}` | 字段等于指定值 |
+| IN 数组匹配 | `{"subject":["数学","英语"]}` | 字段匹配数组中任一值 |
 | 多条件 AND | `{"subject":"数学","difficulty":"困难"}` | 多字段同时匹配 |
 | 范围查询 | `{"createdAt":{"__range":["2026-03-01","2026-03-31"]}}` | 闭区间，包含两端点 |
+| 开放上界 | `{"createdAt":{"__range":["2026-05-21","9999-12-31"]}}` | 实现大于等于（≥），上界设为远未来日期 |
 
 **注意**：不支持 `$gte`、`$gt`、`$lte`、`$lt`、`>=`、`<` 等比较操作符，使用不支持的语法不会报错但返回空结果。范围查询必须使用 `__range`。
 

package/builtin-skills/app-skill/references/process-recovery.md

@@ -0,0 +1,222 @@
+# Process 恢复指南
+
+## 目的
+
+当 Loom 实例因停机（电脑关机、服务重启等）错过 Feeder 消息或 cron 执行时，AI 助手使用本指南帮用户恢复遗漏的数据和补跑错过的定时任务。
+
+## 触发场景
+
+用户可能这样说：
+- "补一下过去4小时的消息"
+- "我昨天下班后到今早的消息没收到，恢复一下"
+- "从昨晚10点到今天早上9点的消息补回来"
+- "看看有没有定时任务漏跑了"
+
+## 前提条件
+
+恢复操作依赖以下数据模型字段（如果模型没有这些字段，告知用户先添加）：
+
+| 字段 | 类型 | 用途 |
+|------|------|------|
+| `messageId` | string | 消息唯一 ID（去重键），从 `rawData.mid` 或 `rawData.msgId` 提取 |
+| `conversation` | string | 会话（会话名+会话ID），格式如 `"AntDingCli测试群1(73408370409)"`，从 `rawData.group` 或 `rawData.groupName+groupId` 拼接，单聊用 `rawData._conversationTitle` |
+
+如果当前模型缺少这些字段，需要在 `loom.config.ts` 的对应模型 fields 中添加：
+
+```typescript
+{ name: 'messageId', type: 'string', description: { 'zh-CN': '消息ID（去重键）', 'en-US': 'Message ID (dedup key)' } },
+{ name: 'conversation', type: 'string', description: { 'zh-CN': '会话（会话名+会话ID）', 'en-US': 'Conversation (name + ID)' } },
+```
+
+## 恢复流程
+
+### 第一步：确定时间窗口
+
+用户指定时间范围，格式灵活：
+- 相对时间："过去4小时" → `--from 4h`
+- 绝对时间："昨晚10点到今早9点" → `--from "2026-05-20 22:00" --to "2026-05-21 09:00"`
+- 日期："昨天一整天" → `--from 1d --to 0d`
+
+将用户意图转换为 `antding history` 的 `--from` / `--to` 参数。`--from` 和 `--to` 支持：
+- `YYYY-MM-DD`（天级）
+- `YYYY-MM-DD HH:MM`（分钟级）
+- `Nd` / `Nh` / `Nm`（相对时间）
+- Unix 时间戳（秒级）
+
+### 第二步：确定会话列表
+
+从当前实例的 Process 配置中提取监控的会话。查看各 Process 的 source 脚本中的 `--cid` 参数：
+
+```bash
+loom process list
+```
+
+从输出中找到所有 Feeder 的 `--cid` 参数，收集去重后的 CID 列表。
+
+用户也可以**额外指定**不在 Feeder 监控范围内的会话：
+- "也把岳立那个聊天的补一下" → 用 `antding list` 查找 CID
+
+### 第三步：查已有消息确定 gap
+
+查询 inbox 在目标时间窗口内已有哪些消息，用于后续去重：
+
+```bash
+# 日级范围查询（推荐，避免时间格式不一致问题）
+loom data read <inbox_model> --filter '{"createdAt":{"__range":["2026-05-20","2026-05-21"]}}' --limit 200
+
+# 按 conversation 分组查看（等值匹配会话名+ID）
+loom data read <inbox_model> --filter '{"conversation":"AntDingCli测试群1(73408370409)"}' --limit 100
+```
+
+**filter 语法注意**：Loom 只支持三种 filter 操作符：
+- 等值匹配：`{"status":"pending"}`
+- IN 数组：`{"status":["pending","dispatched"]}`
+- 范围查询（闭区间）：`{"createdAt":{"__range":["2026-05-20","2026-05-21"]}}`
+- 不支持 `_gte`、`_lte` 等操作符；实现"大于等于"用 `{"createdAt":{"__range":["2026-05-21","9999-12-31"]}}`
+
+### 第四步：逐会话拉取遗漏消息
+
+对每个 CID 执行 `antding history`：
+
+```bash
+# 优先 --hybrid（本地优先，远程补充）
+antding history -c <CID> --from "<开始时间>" --to "<结束时间>" --limit 50 --format json --hybrid
+
+# 如果 hybrid 失败或超时，回退到 --local
+antding history -c <CID> --from "<开始时间>" --to "<结束时间>" --limit 50 --format json --local
+```
+
+**关键参数**：
+- `--limit`：默认只有 10 条，恢复场景必须显式设大（建议 50-100）
+- `--format json`：返回结构化数据，每条消息含 `messageId`、`conversationId`、`senderId`、`createdAtMsec` 等（注意：`conversationId` 是 antding 返回的原始 CID，写入 inbox 时需拼接为 `会话名(CID)` 格式存入 `conversation` 字段）
+- `--hybrid`：本地数据库优先，覆盖不到的时间段自动从服务端拉取
+- `--local`：纯离线，不依赖 daemon，但只包含本地缓存的消息
+- `--timeout`：默认 20 秒，大量消息时可能需要加大
+
+**注意**：`antding history` 一次只支持一个 CID，需要逐个会话查询。
+
+消息量过大时（>100条/会话）分批处理：
+1. 首次 `--limit 50`
+2. 如果返回满 50 条，用最早一条的 `createdAtMsec` 作为新的 `--to`，继续拉取
+3. 重复直到返回不足 50 条
+4. 批间适当等待，避免 daemon 压力
+
+### 第五步：去重并写入
+
+对每条拉取到的消息：
+
+**5a. 提取 messageId 和 conversation**
+
+从 `antding history --format json` 返回的消息结构中：
+- `messageId` → 消息唯一标识（字符串，如 `"26084289099968"`）
+- `conversationId` → 会话 CID（如 `"73408370409"` 或 `"997642:1388075"`），需拼接为 `会话名(CID)` 存入 `conversation` 字段
+- `_conversationTitle` → 会话名（如 `"AntDingCli测试群1"`、`"岳立"`），与 CID 拼接后写入 `conversation`
+- `senderId` → 发送者 UID
+- `createdAt` / `createdAtMsec` → 消息时间
+- `messageContent` → 消息内容（结构体，含 `text`、`contentType` 等）
+
+**5b. 去重检查**
+
+```bash
+loom data read <inbox_model> --filter '{"messageId":"<messageId>"}'
+```
+
+如果返回非空（total > 0），说明该消息已存在，跳过。计数 `skipped++`。
+
+**5c. 写入 inbox**
+
+```bash
+loom data write <inbox_model> --data '{
+  "source": "dingtalk",
+  "sender": "<senderName>(<senderId>)",
+  "content": "<提取的文本内容>",
+  "rawData": <原始消息JSON>,
+  "messageId": "<messageId>",
+  "conversation": "<会话名(CID)>",
+  "status": "pending",
+  "traceId": "trace_recovery_<messageId>"
+}'
+```
+
+**5d. 触发路由（如果需要）**
+
+写入 inbox 后，如需让下游 Process 处理，向 EventBus 注入事件：
+
+```bash
+curl -sf -X POST http://localhost:<port>/api/v1/events/emit \
+  -H 'Content-Type: application/json' \
+  -H "Authorization: Bearer $LOOM_TOKEN" \
+  -d '{
+    "pattern": "<对应的event pattern>",
+    "payload": {
+      "msgContent": "<消息内容>",
+      "messageId": "<messageId>",
+      "recovered": true,
+      "recoveryWindow": "<开始时间> ~ <结束时间>"
+    },
+    "source": "cli"
+  }'
+```
+
+`source` 只允许 `server`、`cli`、`feeder` 三个值。
+
+事件 pattern 根据消息来源确定——参考各 Process 的事件订阅配置（`loom event list`）。恢复消息统一使用基础 pattern（如 `dingtalk:message`），urgent/mention 的判断交给 ingest Process 重新执行。
+
+### 第六步：汇报结果
+
+恢复完成后，向用户汇报：
+
+```
+消息恢复完成：
+- <会话名>(<CID>)：<N> 条新消息，<M> 条重复跳过
+- <会话名>(<CID>)：该时段无消息
+
+合计：恢复 <X> 条，跳过 <Y> 条重复
+所有恢复的消息已写入 inbox，<是否触发EventBus路由>。
+```
+
+## Cron 断档检测
+
+用户还可能问"哪些定时任务漏跑了"。检测流程：
+
+### 1. 列出有 cron 的 Process
+
+```bash
+loom process list
+```
+
+从输出中找到所有有 `cron` 配置的 Process。
+
+### 2. 读取执行日志
+
+```bash
+loom process logs <name> --limit 20
+```
+
+查看每个 cron Process 的最近执行时间，对比断档窗口内应有的执行次数。
+
+### 3. 建议补跑
+
+```
+过去 <N> 小时断档，以下定时任务错过了执行：
+
+| Process | Cron | 应执行 | 实际执行 | 建议 |
+|---------|------|--------|---------|------|
+| morning-brief | 0 8 * * 1-5 | 1次 | 0次 | 建议补跑 |
+| vuln-remind | 0 9 * * 1-5 | 1次 | 0次 | 建议补跑 |
+
+是否要我补跑？执行命令：loom process run <name>
+```
+
+**注意**：不要自动补跑，等用户确认后再执行 `loom process run <name>`。有些定时任务（如已经过期的告警巡检）补跑意义不大，让用户判断。
+
+## 边界情况
+
+| 场景 | 处理方式 |
+|------|---------|
+| antding daemon 未运行 | `--hybrid` 会失败，自动回退 `--local`；都失败则告知用户启动钉钉后重试 |
+| 消息量过大 | 分批拉取，每次 50 条，向用户说明进度 |
+| short gap（<5分钟断档） | 直接告知"断档时间很短，可能没有遗漏消息"，如用户坚持则照常执行 |
+| 去重查询失败 | 保守跳过——宁可少恢复不可重复写入 |
+| 历史消息无法拉取 | `--local` 模式受本地缓存限制，更早的消息可能不可用，告知用户时间范围限制 |
+| conversation 格式 | 统一为 `会话名(CID)` 格式，如 `AntDingCli测试群1(73408370409)` 或 `岳立(997642:1388075)`，与 sender 的 `姓名(UID)` 格式保持一致 |

package/builtin-skills/playwright-cli/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: playwright-cli
+description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages. This is a low-level tool - for authenticated web fetching, use web-fetch skill instead.
+allowed-tools: Bash(playwright-cli:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+playwright-cli fill e5 "user@example.com"
+playwright-cli drag e2 e8
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+playwright-cli snapshot --filename=after-click.yaml
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli network
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start
+playwright-cli video-stop video.webm
+```
+
+## Open parameters
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+# Connect to browser via extension
+playwright-cli open --extension
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command.
+
+If `--filename` is not provided, a new snapshot file is created with a timestamp. Default to automatic file naming, use `--filename=` when artifact is a part of the workflow result.
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Local installation
+
+In some cases user might want to install playwright-cli locally. Use `npm install -g @playwright/cli@latest` `playwright-cli --help` to launch. If running globally available `playwright-cli` binary fails, use `npx playwright-cli` to run the commands. For example:
+
+```bash
+npx playwright-cli open https://example.com
+npx playwright-cli click e1
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli network
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Specific tasks
+
+* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+* **Running Playwright code** [references/running-code.md](references/running-code.md)
+* **Browser session management** [references/session-management.md](references/session-management.md)
+* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+* **Test generation** [references/test-generation.md](references/test-generation.md)
+* **Tracing** [references/tracing.md](references/tracing.md)
+* **Video recording** [references/video-recording.md](references/video-recording.md)
+
+## Related Skills
+
+* **playwright-cli-auth** - 认证会话管理，用于保存和复用登录态

package/builtin-skills/playwright-cli/references/request-mocking.md

@@ -0,0 +1,87 @@
+# Request Mocking
+
+Intercept, mock, modify, and block network requests.
+
+## CLI Route Commands
+
+```bash
+# Mock with custom status
+playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+playwright-cli route-list
+
+# Remove a route or all routes
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+## URL Patterns
+
+```
+**/api/users           - Exact path match
+**/api/*/details       - Wildcard in path
+**/*.{png,jpg,jpeg}    - Match file extensions
+**/search?q=*          - Match query parameters
+```
+
+## Advanced Mocking with run-code
+
+For conditional responses, request body inspection, response modification, or delays:
+
+### Conditional Response Based on Request
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/login', route => {
+    const body = route.request().postDataJSON();
+    if (body.username === 'admin') {
+      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
+    } else {
+      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
+    }
+  });
+}"
+```
+
+### Modify Real Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/user', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    json.isPremium = true;
+    await route.fulfill({ response, json });
+  });
+}"
+```
+
+### Simulate Network Failures
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/slow', async route => {
+    await new Promise(r => setTimeout(r, 3000));
+    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
+  });
+}"
+```