@optima-chat/optima-agent 0.8.46 → 0.8.48

package/.claude/settings.local.json

@@ -0,0 +1,154 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh api:*)",
+      "WebFetch(domain:platform.claude.com)",
+      "Bash(git init:*)",
+      "Bash(mkdir:*)",
+      "Bash(npm run typecheck:*)",
+      "Bash(npm view:*)",
+      "WebSearch",
+      "Bash(commerce --help)",
+      "Bash(done)",
+      "Bash(commerce product:*)",
+      "Bash(commerce order:*)",
+      "Bash(commerce i18n:*)",
+      "Bash(google-ads:*)",
+      "Bash(scout --help:*)",
+      "Bash(tree:*)",
+      "Bash(cloc:*)",
+      "Bash(npm run build:*)",
+      "Bash(git restore:*)",
+      "Bash(gh repo view:*)",
+      "Bash(mv:*)",
+      "Bash(rmdir:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push)",
+      "Bash(timeout 5 npm run optima:*)",
+      "Bash(npm install:*)",
+      "Bash(cat:*)",
+      "Bash(gh issue create:*)",
+      "Bash(npx tsx:*)",
+      "Bash(timeout 30 npx tsx:*)",
+      "Bash(git push origin feature/ask-user-question)",
+      "Bash(node:*)",
+      "Bash(npm version:*)",
+      "Bash(git push:*)",
+      "Bash(npm publish:*)",
+      "Bash(pkill:*)",
+      "Bash(git -C /Users/verypro/optima-agent log --oneline --all -- \".claude/\")",
+      "Bash(wc:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(commerce collection --help:*)",
+      "Bash(commerce collection update --help:*)",
+      "Bash(commerce collection set-cover:*)",
+      "Bash(commerce collection get --help:*)",
+      "Bash(commerce collection list --help:*)",
+      "Bash(commerce collection create --help:*)",
+      "Bash(commerce collection remove-products:*)",
+      "Bash(commerce collection list-products:*)",
+      "Bash(commerce --version:*)",
+      "Bash(bi-cli --version:*)",
+      "Bash(commerce homepage create --help:*)",
+      "Bash(commerce homepage reorder --help:*)",
+      "Bash(commerce homepage delete --help:*)",
+      "Bash(commerce homepage update-images:*)",
+      "Bash(commerce homepage update-collections:*)",
+      "Bash(commerce homepage update-target:*)",
+      "Bash(commerce homepage switch-template:*)",
+      "Bash(commerce inventory:*)",
+      "Bash(commerce merchant:*)",
+      "Bash(commerce review:*)",
+      "Bash(commerce product-page:*)",
+      "Bash(bi-cli:*)",
+      "Bash(comfy:*)",
+      "Bash(scout search:*)",
+      "Bash(scout product:*)",
+      "Bash(commerce homepage create-collections:*)",
+      "Bash(commerce homepage create-featured:*)",
+      "Bash(commerce homepage create-collection-products:*)",
+      "Bash(commerce homepage create-banner:*)",
+      "Bash(xargs -I {} sh -c 'echo \"\"\"\"=== {} ===\"\"\"\"; head -3 /Users/verypro/optima-agent/.claude/skills/{}/SKILL.md | grep \"\"\"\"name:\"\"\"\"')",
+      "Bash(ls:*)",
+      "Bash(gh issue view:*)",
+      "Bash(npx markdownlint-cli:*)",
+      "Bash(chmod:*)",
+      "Bash(npm whoami:*)",
+      "Bash(tsx test-scripts/test-headless-progress.ts:*)",
+      "Bash(DEBUG_STREAM=1 node dist/bin/optima.js:*)",
+      "Bash(git describe:*)",
+      "WebFetch(domain:github.com)",
+      "Bash(./scripts/test-headless.sh:*)",
+      "Bash(./scripts/test-headless-simple.sh:*)",
+      "Bash(env)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(optima --version:*)",
+      "Bash(optima agent headless:*)",
+      "Bash(optima headless:*)",
+      "Bash(/Users/verypro/optima-agent/scripts/test-headless.sh:*)",
+      "Bash(/Users/verypro/optima-agent/scripts/test-headless-simple.sh:*)",
+      "Bash(tee:*)",
+      "Bash(CONV_ID=\"conv-1\":*)",
+      "Bash(echo:*)",
+      "Bash(scout tiktok trending --help:*)",
+      "Bash(scout tiktok trending:*)",
+      "Bash(git checkout:*)",
+      "Bash(npm test:*)",
+      "Bash(git tag:*)",
+      "Bash(/private/tmp/claude/-Users-verypro-optima-agent/68a9ac2c-def2-44e1-b42b-e53bd9022ab6/scratchpad/test-canUseTool.sh)",
+      "Bash(optima --help:*)",
+      "Bash(npx @optima-chat/ads-cli:*)",
+      "Bash(head:*)",
+      "Bash(git pull:*)",
+      "Bash(pnpm build:*)",
+      "Skill(read-code)",
+      "Bash(npm run cli:*)",
+      "Bash(scout:*)",
+      "WebFetch(domain:docs.scrapecreators.com)",
+      "WebFetch(domain:scrapecreators.com)",
+      "Bash(gh auth status:*)",
+      "Bash(optima-agent:*)",
+      "Bash(python3:*)",
+      "Bash(python3 -c \" import sys content = sys.stdin.read\\(\\) # Find flushMessageQueueSync idx = content.find\\(''flushMessageQueueSync''\\) # Get context around it lines = content.split\\(''\\\\n''\\) for i, line in enumerate\\(lines\\): if ''flushMessageQueueSync'' in line and ''private'' in line: for j in range\\(i, min\\(i+20, len\\(lines\\)\\)\\): print\\(f''{j+1}: {lines[j]}''\\) break \")",
+      "Bash(optima:*)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:registry.npmjs.org)",
+      "WebFetch(domain:zod.dev)",
+      "Bash(npm ls:*)",
+      "Bash(NODE_DEBUG=child_process npx tsx:*)",
+      "Bash(DEBUG_CLAUDE_AGENT_SDK=1 npx tsx:*)",
+      "Bash(CLAUDECODE= npx tsx:*)",
+      "Bash(env:*)",
+      "Bash(gh release:*)",
+      "Bash(npm info:*)",
+      "Bash(gh run:*)",
+      "Bash(gtimeout 90:*)",
+      "Bash(sentinel:*)",
+      "Bash(gh pr:*)",
+      "Bash(git fetch:*)",
+      "Bash(git log:*)",
+      "Bash(npm bin:*)",
+      "Bash(git status:*)",
+      "Bash(browser-cli --version && browser-cli --help)",
+      "Bash(browser-cli status:*)",
+      "Bash(browser-cli launch:*)",
+      "Bash(browser-cli screenshot:*)",
+      "Bash(browser-cli --version)",
+      "Bash(browser-cli close:*)",
+      "Bash(npm update:*)",
+      "Bash(node -e \"console.log\\(require\\('./node_modules/@optima-chat/browser-cli/package.json'\\).version\\)\")",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(aws ecs:*)",
+      "Bash(aws ecr:*)",
+      "Bash(gh search:*)",
+      "Bash(npx tsc:*)",
+      "Bash(find /Users/verypro/optima-agent -path */node_modules -prune -o -type f \\\\\\(-name *comfy* -o -name *gen* \\\\\\) -print)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.claude/skills/browser/SKILL.md

@@ -17,8 +17,20 @@ description: "Browser automation for web interactions. Use when user needs to op
 - 简单网页抓取 → 使用 WebFetch
 - 已有专用 skill 的任务（如 scout、tiktok、instagram、shein 等）
 
+## 脚本优先原则
+
+每次执行浏览器任务前，**先检查是否有现成脚本**：
+
+1. `browser-cli scripts` — 查看已有脚本（显示名称、描述、步骤）
+2. 如果有匹配的脚本 → 直接用 `browser-cli runscript <name> --param ...`
+3. 如果没有 → 手动探索完成任务，然后生成脚本并提交
+
+脚本执行零 token 消耗，比手动操作快 10 倍以上。
+
 ## 命令
 
+### 基础命令
+
 ```bash
 # 会话管理
 browser-cli launch [--url <url>] [--force]  # 启动浏览器（--force 先关闭已有会话）
@@ -36,6 +48,7 @@ browser-cli input <index> <text> [--no-clear]  # 输入文本（--no-clear 追
 browser-cli select <index> <option>   # 选择下拉选项
 browser-cli scroll <up|down> [--pages <n>]     # 滚动页面（默认 1 页）
 browser-cli keys <key>                # 键盘操作（Enter、Tab 等）
+browser-cli upload <index> <file...> # 上传文件到 file input（路径自动转换）
 
 # 页面检查
 browser-cli dom                       # 获取当前 DOM 状态
@@ -49,6 +62,23 @@ browser-cli switch <tab_id>           # 切换标签页
 browser-cli close-tab <tab_id>        # 关闭标签页
 ```
 
+### 脚本命令
+
+```bash
+# 查看与管理
+browser-cli scripts                                        # 列出所有脚本（含描述和步骤）
+browser-cli script-code <name>                             # 查看脚本源码
+browser-cli delete-script <name>                           # 删除脚本
+
+# 提交
+browser-cli submit-script --name <name> --code-file <path> # 提交脚本（新建或覆盖）
+
+# 执行
+browser-cli runscript <name> --param key=value [...]       # 执行脚本（自动轮询到完成）
+browser-cli runscript <name> --param key=value --no-poll   # 执行但不等待
+browser-cli script-task <task-id>                          # 查询执行状态
+```
+
 ## DOM 索引格式
 
 每个操作都会返回当前 DOM 状态，格式如下：
@@ -62,105 +92,326 @@ browser-cli close-tab <tab_id>        # 关闭标签页
 - 每次操作后索引会**重新分配** — 务必使用最新的索引
 - 使用这些索引来执行 `click`、`input` 和 `select` 命令
 
-## 注意事项
+## 登录与 Profile
 
-- **DOM 自动返回**：每个操作会自动返回 DOM 状态 — 无需单独调用 `browser-cli dom`
-- **避免不必要的截图**：截图消耗 token，日常导航用 DOM 输出即可
-- **5 分钟超时**：无操作 5 分钟后会话自动关闭
-- **登录提示**：遇到登录页面时，向用户询问账号密码或验证码
-- **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
+浏览器自动为每个用户保持一个持久化的 Chrome Profile。所有平台的登录态（cookies、session）保存在同一个 Profile 中。
+
+- **首次登录**：需要用户提供账号和验证码，登录后自动保存
+- **后续使用**：自动恢复登录态，无需重新登录
+- **多平台**：小红书、抖音、微博等登录态共存于同一个 Profile
+
+无需任何参数或命令来管理 Profile，完全自动。
+
+## 文件路径
+
+浏览器后端可以直接读取用户工作空间的文件（通过共享 EFS）。传文件路径时直接使用你看到的路径即可，后端会自动转换：
+
+```
+~/images/photo.jpg              → 自动转换 ✓
+/home/aiuser/images/photo.jpg   → 自动转换 ✓
+/mnt/efs/{userId}/images/...    → 自动转换 ✓
+```
+
+不需要上传文件，不需要手动转换路径。
+
+## 操作流程
+
+### 流程一：有脚本（常见）
 
-## 基本操作示例
+```bash
+# 1. 检查脚本
+browser-cli scripts
+# 输出:
+# xiaohongshu-image-note — 在小红书创作者平台发布图文笔记
+#   [1] navigate — 打开小红书发布页
+#   [2] switch_tab — 切换到上传图文模式
+#   [3] upload — 上传图片 {images}
+#   ...
+
+# 2. 直接执行
+browser-cli runscript xiaohongshu-image-note \
+  --param title="今日分享" \
+  --param body="内容..." \
+  --param 'images=["~/images/photo1.jpg", "~/images/photo2.jpg"]'
+# 输出: ✓ Script completed
+```
+
+### 流程二：无脚本（首次）
 
 ```bash
-# 1. 启动浏览器并导航
-browser-cli launch --url "https://example.com"
+# 1. 检查脚本 — 没有匹配的
+browser-cli scripts
+# 输出: No scripts registered.
+
+# 2. 手动探索
+browser-cli launch --url https://creator.xiaohongshu.com
+# → 如果需要登录，向用户询问手机号和验证码
+browser-cli input 11 "18500400810"
+browser-cli click 33   # 发送验证码
+# (用户提供验证码)
+browser-cli input 12 "123456"
+browser-cli click 38   # 登录
+# → 登录成功，继续操作...
+browser-cli dom                           # 分析页面
+browser-cli click 1880                    # 点击"上传图文"
+browser-cli dom                           # 找到 file input
+browser-cli upload 1092 ~/images/photo.jpg  # 上传图片
+browser-cli input 2905 "标题"              # 填写标题
+browser-cli input 3432 "正文内容"          # 填写正文
+browser-cli click 2814                    # 点击发布
+# → 任务完成
+
+# 3. 生成 Python 脚本
+# 根据上面的探索轨迹，生成脚本文件，必须包含：
+# - DESCRIPTION: 脚本描述
+# - STEPS: 语义步骤列表（StepDef）
+# - run(ctx): 异步执行函数
+# 写到本地文件
+
+# 4. 提交脚本
+browser-cli submit-script \
+  --name xiaohongshu-image-note \
+  --code-file /tmp/xiaohongshu_image_note.py
+
+# 5. 关闭浏览器
+browser-cli close
+```
 
-# 2. 根据 DOM 索引进行交互
-browser-cli click 15          # 点击按钮
-browser-cli input 22 "hello"  # 输入文本
-browser-cli keys Enter         # 按回车
+### 流程三：脚本失败（Fallback）
 
-# 3. 完成后关闭
+```bash
+# 1. 执行脚本
+browser-cli runscript xiaohongshu-image-note --param ...
+# 输出:
+# ⚠ Script needs fallback
+#
+# ✓ Completed:
+#   [1] navigate — 打开小红书发布页
+#   [2] switch_tab — 切换到上传图文模式
+#
+# ✗ Failed at step [3] upload: file input not found
+#
+# → Remaining steps:
+#   [3] upload — 上传图片 ["~/photo.jpg"]
+#   [4] fill_title — 填写标题'测试'
+#   [5] fill_body — 填写正文'内容'
+#   [6] publish — 点击发布按钮
+#   [7] verify — 确认发布成功
+#
+# Session is still open — use browser-cli dom/click/input to continue
+
+# 2. 接管完成剩余步骤（Session 仍然打开，不需要重新 launch）
+browser-cli dom                    # 查看当前页面
+browser-cli click 15               # 继续操作
+browser-cli input 22 "测试"
+browser-cli click 30
+# → 任务完成
+
+# 3. (可选) 更新脚本以修复问题
+# 重新生成脚本，覆盖旧版本
+browser-cli submit-script \
+  --name xiaohongshu-image-note \
+  --code-file /tmp/xiaohongshu_image_note_v2.py
+
+# 4. 关闭浏览器
 browser-cli close
 ```
 
-## Workflow（操作录制与回放）
+## 脚本代码规范
+
+### 基本结构
+
+每个脚本必须包含 `DESCRIPTION`、`STEPS` 和 `async def run(ctx)`:
+
+```python
+"""脚本描述。"""
+from __future__ import annotations
+import asyncio
+import json
+from app.scripts.base import ScriptContext, ScriptResult, StepDef, render_steps
+
+DESCRIPTION = "一句话描述脚本功能"
+
+STEPS = [
+    StepDef(id="step_id", description="步骤描述，支持 {param} 占位符"),
+]
+
+PAGE_SETTLE = 2  # 页面操作后等待秒数
+
+async def run(ctx: ScriptContext) -> ScriptResult:
+    bs = ctx.browser_session
+    steps = render_steps(STEPS, ctx.params)
+    completed: list[StepDef] = []
+
+    try:
+        # 逐步执行，每完成一步 append
+        # ...
+        return ScriptResult(status="completed", output={...}, completed_steps=completed)
+    except Exception as e:
+        remaining = [s for s in steps if s not in completed]
+        snapshot = await _capture_snapshot(bs)
+        return ScriptResult(
+            status="needs_fallback",
+            completed_steps=completed,
+            remaining_steps=remaining,
+            error=str(e),
+            snapshot=snapshot,
+        )
+
+async def _capture_snapshot(bs) -> dict:
+    try:
+        state = await bs.get_browser_state_summary(include_screenshot=False)
+        dom = state.dom_state.llm_representation() if state and state.dom_state else ""
+    except Exception:
+        dom = ""
+    return {"dom": dom}
+```
 
-将浏览器操作录制为可复用的 workflow，后续执行时零 token 消耗。
+### 浏览器操作 API
 
-### Workflow 命令
+```python
+# 导航
+action = ctx.action_model(navigate={"url": "https://example.com"})
+await ctx.controller.act(action, bs)
+await asyncio.sleep(PAGE_SETTLE)
 
-```bash
-# 保存与管理
-browser-cli save-workflow <name> [--description <desc>]   # 保存当前 session 操作为 workflow
-browser-cli list-workflows                                 # 列出所有 workflow
-browser-cli workflow-info <name>                           # 查看 workflow 详情（步骤列表）
-browser-cli delete-workflow <name>                         # 删除 workflow
-
-# 编辑（保存后参数化）
-browser-cli edit-workflow <name> --set-var --step <N> --name <varName>    # 将步骤 N 的值设为变量
-browser-cli edit-workflow <name> --add-input <varName> --type string [--required]  # 声明输入变量（type: string/number/bool）
-browser-cli edit-workflow <name> --add-step extract --selectors '<json>' [--screenshot]  # 添加 extract 步骤
-browser-cli edit-workflow <name> --add-step wait_for_element --selector '<css>' [--timeout 30]  # 添加等待步骤
-browser-cli edit-workflow <name> --remove-step <N>                       # 删除步骤
-browser-cli edit-workflow <name> --update-step <N> --requires-confirmation  # 标记敏感操作
-browser-cli edit-workflow <name> --update-step <N> --target-text '<text>'   # 修改定位文本
-browser-cli edit-workflow <name> --auto-clean                            # 自动清理冗余步骤
-
-# 执行与监控
-browser-cli run-workflow <name> [--param key=value ...] [--force]   # 执行（--force 自动关闭已有 session）
-browser-cli workflow-status <task_id>                               # 查询执行状态
-browser-cli workflow-input <task_id> --var key=value                # 提供变量值
-browser-cli workflow-input <task_id> --value <val>                  # 提供值（仅单变量时）
-browser-cli workflow-input <task_id> --confirm                      # 确认敏感操作
-browser-cli workflow-cancel <task_id>                               # 取消执行
-
-# 降级接管（workflow 失败后用 --session 继续操作）
-browser-cli --session <session_id> dom          # 查看降级 session 的页面
-browser-cli --session <session_id> click 5      # 在降级 session 上操作
-browser-cli --session <session_id> close        # 完成后关闭
+# 点击（通过 DOM index）
+action = ctx.action_model(click={"index": idx})
+await ctx.controller.act(action, bs)
+
+# 输入文本
+action = ctx.action_model(input={"index": idx, "text": "内容"})
+await ctx.controller.act(action, bs)
+
+# 获取当前 DOM（每步操作前刷新）
+state = await bs.get_browser_state_summary(include_screenshot=False, cached=False)
+sm = state.dom_state.selector_map or {}
+
+# 获取当前 URL
+page = await bs.get_current_page()
+url = await page.get_url()
 ```
 
-**注意**：
-- `--force` 会自动关闭已有 session 并取消运行中的 task
-- 不带 `--force` 时，如果有活跃 session 或运行中 task 会返回 409 错误
+### 元素查找（语义匹配，不要硬编码 index）
+
+DOM index 每次页面变化后会重新分配，脚本中**不能硬编码 index**。
+必须通过语义属性动态查找：
+
+```python
+# 按文字内容查找（如按钮、标签页）
+def _find_by_text(sm, text, tag=None):
+    for idx, node in sm.items():
+        node_tag = (getattr(node, "tag_name", "") or "").lower()
+        if tag and node_tag != tag:
+            continue
+        try:
+            node_text = node.get_all_children_text().strip() if hasattr(node, "get_all_children_text") else ""
+        except Exception:
+            node_text = ""
+        if text in node_text:
+            return idx
+    return None
+
+# 按 placeholder 查找（如输入框，支持 shadow DOM）
+def _find_by_placeholder(sm, placeholder_contains):
+    for idx, node in sm.items():
+        attrs = getattr(node, "attributes", {}) or {}
+        if placeholder_contains in attrs.get("placeholder", ""):
+            return idx
+        # Shadow DOM fallback
+        if not attrs:
+            try:
+                llm = node.llm_representation() if hasattr(node, "llm_representation") else ""
+                if placeholder_contains in llm:
+                    return idx
+            except Exception:
+                pass
+    return None
+
+# 按 role 查找（如 contenteditable 编辑器）
+def _find_by_role(sm, role, tag=None):
+    for idx, node in sm.items():
+        node_tag = (getattr(node, "tag_name", "") or "").lower()
+        if tag and node_tag != tag:
+            continue
+        attrs = getattr(node, "attributes", {}) or {}
+        if attrs.get("role") == role:
+            return idx
+        if attrs.get("contenteditable") and role == "textbox":
+            return idx
+    return None
+
+# 按文件类型查找 file input（如图片上传）
+def _find_image_file_input(bs, sm):
+    for idx, node in sm.items():
+        if not bs.is_file_input(node):
+            continue
+        attrs = getattr(node, "attributes", {}) or {}
+        accept = attrs.get("accept", "")
+        if any(ext in accept for ext in [".jpg", ".jpeg", ".png", ".webp"]):
+            return idx
+    for idx, node in sm.items():
+        if bs.is_file_input(node):
+            return idx
+    return None
+```
 
-### 保存 workflow
+### 文件上传
 
-当用户完成浏览器操作后说"把这个操作保存下来"或类似意图时：
+上传文件需要 `FileSystem` 和 `available_file_paths`：
 
-1. **保存前先查看最终页面 DOM**：`browser-cli dom` — 记住页面结构，为 extract 步骤准备 CSS selector（注意：session 必须还在，未 close）
-2. `browser-cli save-workflow '操作名称'` — 保存操作记录（自动附带 DOM snapshot）。同名 workflow 不会覆盖，需先 `delete-workflow` 再重新保存
-3. 用 `edit-workflow` 进行参数化：
-   - 识别可变值（搜索词、用户名、密码等），用 `--set-var` 替换为变量占位符
-   - 用 `--add-input` 声明 input_schema
-   - 如果 workflow 需要返回数据（如查价格、查状态），根据保存时看到的 DOM 结构添加 extract 步骤（用 CSS selector 指定要提取的字段）；纯执行型 workflow（如发帖）可不加 extract
-   - 对支付、删除等敏感操作，用 `--update-step N --requires-confirmation` 标记
-4. 确认 workflow 可用：`browser-cli workflow-info '操作名称'`
+```python
+from browser_use.filesystem.file_system import FileSystem
+from app.services.file_upload import UPLOAD_TEMP_BASE
+import secrets as _secrets
 
-### 执行 workflow
+# 创建临时目录
+fs_dir = UPLOAD_TEMP_BASE / f"script_{_secrets.token_hex(4)}"
+fs_dir.mkdir(parents=True, exist_ok=True)
+file_system = FileSystem(base_dir=str(fs_dir), create_default_files=False)
 
-当用户说"用之前录的 XX workflow"或类似意图时：
+# 上传每个文件
+images = json.loads(ctx.params.get("images", "[]"))
+file_idx = _find_image_file_input(bs, sm)
+for img_path in images:
+    action = ctx.action_model(upload_file={"index": file_idx, "path": img_path})
+    await ctx.controller.act(action, bs, available_file_paths=images, file_system=file_system)
+```
 
-1. `browser-cli list-workflows` — 确认 workflow 存在
-2. `browser-cli run-workflow '名称' --param key=value` — 启动执行
-3. `browser-cli workflow-status <task_id>` — 每 3-5 秒轮询一次状态
-4. 根据状态处理：
-   - `needs_input` → 检查输出中的字段：
-     - 有 `Missing: xxx` → 缺少变量值，向用户询问后用 `workflow-input --var xxx=值` 提供
-     - 有 `Confirmation: xxx` → 敏感操作待确认，告知用户后用 `workflow-input --confirm` 确认
-   - `failed` → 用 `--session` flag 接管当前 session 完成任务（见降级接管）
-   - `completed` → 返回 Output 给用户
+文件路径由引擎自动转换（~/xxx → /mnt/workspaces/{userId}/xxx），脚本直接用 `ctx.params` 中的路径即可。
 
-### 降级接管
+### 等待页面变化
 
-workflow 执行失败后，session 仍然活跃。用 `workflow-status` 返回的 session ID 接管：
+页面操作后（导航、上传、点击）需要等待，用轮询模式：
 
-```bash
-browser-cli --session <session_id> dom    # 查看当前页面
-browser-cli --session <session_id> click 5  # 用普通命令完成剩余操作
-browser-cli --session <session_id> close    # 完成后关闭
+```python
+# 简单等待
+await asyncio.sleep(PAGE_SETTLE)
+
+# 轮询等待某个元素出现（如上传后等编辑模式）
+target_idx = None
+for attempt in range(10):
+    await asyncio.sleep(PAGE_SETTLE)
+    state = await bs.get_browser_state_summary(include_screenshot=False, cached=False)
+    sm = state.dom_state.selector_map or {}
+    target_idx = _find_by_placeholder(sm, "填写标题")
+    if target_idx is not None:
+        break
+if target_idx is None:
+    raise RuntimeError("等待超时：目标元素未出现")
 ```
 
-不需要重新 `launch`。
+### 完整示例
+
+参考系统内置脚本 `xiaohongshu-image-note`（通过 `browser-cli script-code xiaohongshu-image-note` 查看完整源码）。
+
+## 注意事项
+
+- **脚本优先**：每次操作前先 `browser-cli scripts`，有脚本就用脚本
+- **DOM 自动返回**：每个操作会自动返回 DOM 状态 — 无需单独调用 `browser-cli dom`
+- **避免不必要的截图**：截图消耗 token，日常导航用 DOM 输出即可
+- **5 分钟超时**：无操作 5 分钟后会话自动关闭
+- **登录自动保持**：登录一次后自动持久化，无需重复登录
+- **文件路径自动转换**：直接传你看到的路径（~/xxx），后端自动处理
+- **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
+- **Fallback 后更新脚本**：如果脚本频繁失败，重新生成并 submit-script 覆盖

package/dist/bin/comfy.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "@optima-chat/comfy-cli";
+//# sourceMappingURL=comfy.d.ts.map

package/dist/bin/comfy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comfy.d.ts","sourceRoot":"","sources":["../../bin/comfy.ts"],"names":[],"mappings":";AACA,OAAO,wBAAwB,CAAC"}

package/dist/bin/comfy.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "@optima-chat/comfy-cli";
+//# sourceMappingURL=comfy.js.map

package/dist/bin/comfy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comfy.js","sourceRoot":"","sources":["../../bin/comfy.ts"],"names":[],"mappings":";AACA,OAAO,wBAAwB,CAAC"}

package/dist/src/agent.d.ts

@@ -11,7 +11,7 @@ export declare class OptimaAgent {
      * @param prompt 用户输入
      * @param chatOptions 选项，包括 streamFormat: 'delta' | 'content'
      */
-    chat(prompt: string, chatOptions?: ChatOptions): AsyncGenerator<import("@anthropic-ai/claude-agent-sdk").SDKUserMessage | import("@anthropic-ai/claude-agent-sdk").SDKAssistantMessage | import("@anthropic-ai/claude-agent-sdk").SDKResultSuccess | import("@anthropic-ai/claude-agent-sdk").SDKResultError | import("@anthropic-ai/claude-agent-sdk").SDKSystemMessage | import("@anthropic-ai/claude-agent-sdk").SDKPartialAssistantMessage | import("@anthropic-ai/claude-agent-sdk").SDKCompactBoundaryMessage | import("@anthropic-ai/claude-agent-sdk").SDKStatusMessage | import("@anthropic-ai/claude-agent-sdk").SDKLocalCommandOutputMessage | import("@anthropic-ai/claude-agent-sdk").SDKHookStartedMessage | import("@anthropic-ai/claude-agent-sdk").SDKHookProgressMessage | import("@anthropic-ai/claude-agent-sdk").SDKHookResponseMessage | import("@anthropic-ai/claude-agent-sdk").SDKToolProgressMessage | import("@anthropic-ai/claude-agent-sdk").SDKAuthStatusMessage | import("@anthropic-ai/claude-agent-sdk").SDKTaskNotificationMessage | import("@anthropic-ai/claude-agent-sdk").SDKTaskStartedMessage | import("@anthropic-ai/claude-agent-sdk").SDKTaskProgressMessage | import("@anthropic-ai/claude-agent-sdk").SDKFilesPersistedEvent | import("@anthropic-ai/claude-agent-sdk").SDKToolUseSummaryMessage | import("@anthropic-ai/claude-agent-sdk").SDKRateLimitEvent | import("@anthropic-ai/claude-agent-sdk").SDKElicitationCompleteMessage | import("@anthropic-ai/claude-agent-sdk").SDKPromptSuggestionMessage | {
+    chat(prompt: string, chatOptions?: ChatOptions): AsyncGenerator<import("@anthropic-ai/claude-agent-sdk").SDKUserMessage | import("@anthropic-ai/claude-agent-sdk").SDKAssistantMessage | import("@anthropic-ai/claude-agent-sdk").SDKResultSuccess | import("@anthropic-ai/claude-agent-sdk").SDKResultError | import("@anthropic-ai/claude-agent-sdk").SDKSystemMessage | import("@anthropic-ai/claude-agent-sdk").SDKPartialAssistantMessage | import("@anthropic-ai/claude-agent-sdk").SDKCompactBoundaryMessage | import("@anthropic-ai/claude-agent-sdk").SDKStatusMessage | import("@anthropic-ai/claude-agent-sdk").SDKAPIRetryMessage | import("@anthropic-ai/claude-agent-sdk").SDKLocalCommandOutputMessage | import("@anthropic-ai/claude-agent-sdk").SDKHookStartedMessage | import("@anthropic-ai/claude-agent-sdk").SDKHookProgressMessage | import("@anthropic-ai/claude-agent-sdk").SDKHookResponseMessage | import("@anthropic-ai/claude-agent-sdk").SDKToolProgressMessage | import("@anthropic-ai/claude-agent-sdk").SDKAuthStatusMessage | import("@anthropic-ai/claude-agent-sdk").SDKTaskNotificationMessage | import("@anthropic-ai/claude-agent-sdk").SDKTaskStartedMessage | import("@anthropic-ai/claude-agent-sdk").SDKTaskProgressMessage | import("@anthropic-ai/claude-agent-sdk").SDKFilesPersistedEvent | import("@anthropic-ai/claude-agent-sdk").SDKToolUseSummaryMessage | import("@anthropic-ai/claude-agent-sdk").SDKRateLimitEvent | import("@anthropic-ai/claude-agent-sdk").SDKElicitationCompleteMessage | import("@anthropic-ai/claude-agent-sdk").SDKPromptSuggestionMessage | {
         type: "text_delta";
         delta: {
             text: string;

package/dist/src/hooks-loader.d.ts

@@ -0,0 +1,6 @@
+import type { HooksConfig } from "./types.js";
+/**
+ * 从 skills 目录加载所有 skill 的 hooks
+ */
+export declare function loadSkillHooks(skillsDir: string, cwd: string, getSessionId: () => string | undefined): HooksConfig;
+//# sourceMappingURL=hooks-loader.d.ts.map

package/dist/src/hooks-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-loader.d.ts","sourceRoot":"","sources":["../../src/hooks-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AAwL5D;;GAEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,MAAM,GAAG,SAAS,GACrC,WAAW,CAiFb"}