@comate/zulu 1.4.0-beta.2 → 1.4.0-beta.3

package/comate-engine/assets/skills/create-automation-tasks-comate/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: create-automation-tasks
+description: |
+  帮助用户创建、配置和管理 Comate Automation 自动化任务。当用户表达以下意图时触发：
+  - 创建/设置/新建自动化任务、定时任务、cron 任务
+  - 修改/删除/查看已有的 Automation 配置
+  - "每天/每周/每月自动帮我做..."
+  - 配置 webhook 触发任务
+  不适用于普通的一次性任务请求，仅适用于需要周期性或事件驱动执行的自动化配置。
+---
+
+# create_automation_tasks Skill
+
+你正在帮助用户创建或管理 Comate Automation 自动化任务。本 Skill 的核心目标是**根据用户的具体需求，量身定制 AUTOMATION.md 的 query**，而不是套用固定流程模板。
+
+## 注入参数（运行时由 Comate 填充）
+
+```
+activeAutomations   = []          # 已有任务列表，格式见下方
+availableModelIds   = [ernie-x1-0401, ernie-4.5-8k]
+webhookBaseUrl      = null        # Phase 2 启用后注入，如 http://127.0.0.1:52384/webhook
+currentWorkspace    = ""          # 当前 IDE 打开的项目路径
+```
+
+`activeAutomations` 每项结构：`{name, enabled, triggerType, cron?, workspace, lastStatus, nextRunAt}`
+
+配置目录固定为 `~/.comate/automations`，每个任务对应目录下的一个 `AUTOMATION.md` 文件。
+
+---
+
+## AUTOMATION.md 格式
+
+每个任务存放在 `~/.comate/automations/{taskName}/AUTOMATION.md`。
+
+采用 **YAML frontmatter + Markdown body** 格式：frontmatter 为调度/执行配置，body 为发给 Agent 的 query 指令。
+
+### 基本格式（定时触发）
+
+````markdown
+---
+name: "task-name"                          # kebab-case，与目录名一致
+description: "任务描述"                     # 可选，非空字符串
+enabled: true
+
+triggers:
+  - type: schedule
+    schedule:
+      cron: "0 9 * * 1-5"                    # 5字段：分 时 日 月 周
+      timezone: "Asia/Shanghai"              # 可选，IANA 时区，默认系统时区
+
+execution:
+  workspace: "/absolute/path/to/project"  # 绝对路径，默认使用当前项目路径
+  timeoutSeconds: 3600                    # 可选，正整数，默认 3600，上限 7200
+---
+
+这里写任务指令（query）。必须自包含，包含所有必要上下文。
+
+完成后请将执行摘要写入 promise_done_summary.md。
+````
+
+同一任务可配置多个 trigger（schedule 至多一个）：
+
+```yaml
+triggers:
+  - type: schedule
+    schedule:
+      cron: "0 9 * * 1-5"
+  - type: webhook
+    webhook:
+      endpointId: "a3f9c2b1"
+      method: POST
+```
+
+### Webhook 触发（Phase 2，`webhookBaseUrl` 不为 null 时可配置）
+
+```yaml
+triggers:
+  - type: webhook
+    webhook:
+      endpointId: "a3f9c2b1"              # 8位hex，见下方生成方法
+      method: POST                          # 可选，GET | POST，默认 POST
+      filter:                               # 可选，二级过滤条件
+        bodyContains: "deploy succeeded"    # 可选，非空字符串
+        requiredHeaders:                    # 可选，字符串列表
+          - "X-My-Token"
+```
+
+> **生成 endpointId**（写入 AUTOMATION.md 前在终端执行一次，取输出填入）：
+> ```bash
+> node -e "console.log(require('crypto').randomBytes(4).toString('hex'))"
+> # 或: python3 -c "import uuid; print(uuid.uuid4().hex[:8])"
+> ```
+> webhook URL = `{webhookBaseUrl}/{endpointId}`，在 Dashboard 中展示给用户复制到外部系统。
+
+### GitHub / Slack 事件触发（Phase 3，暂不实现）
+
+```yaml
+triggers:
+  - type: github
+    github:
+      event: pull_request_opened  # push | pull_request_opened | ci_completed
+      repository: "org/repo"
+      branch: main
+  - type: slack
+    slack:
+      event: app_mention           # app_mention | message
+      channelId: "C12345678"
+```
+
+---
+
+## 执行 Agent 的能力与约束
+
+AUTOMATION.md 的 body（query）会被一个独立的 Comate Agent Session 执行。设计 query 时需了解该 Agent 的运行环境：
+
+**Agent 具备的能力**：
+- 与当前用户的 Comate 环境**完全一致**：拥有相同的 **Skills**、**Rules**、**Tools**
+- 这意味着：用户在当前项目中配置的所有 Rules（如 `.comate/rules/` 下的规则）和 Skills 在 Automation Session 中同样生效
+- 可以读写文件、执行终端命令、搜索代码、调用网络等
+- 运行在 **YOLO 模式**（权限全开）：所有工具调用和命令执行均自动批准，不弹确认
+
+**Agent 已知的上下文**：
+- 通过 Unattended Prompt 注入，Agent 知道自己是**无人值守自动化 Session**，不会等待用户确认
+- Agent 知道触发类型、时间、workspace、Git 状态等元信息
+- Agent 知道完成任务后必须写入 `promise_done_summary.md` 文件作为成功信号
+
+**Agent 不具备的能力**：
+- 没有本次对话的历史上下文（每次 run 是全新 Session）
+- 不会主动提问或等待用户输入（提问会导致 stall 直至超时）
+- 没有跨 run 的记忆（每次执行互相独立）
+因此，query 必须是**自包含的完整指令**：所有必要信息（路径、分支、环境、步骤、边界条件）都要写在 query 里，不能依赖"Agent 应该知道"的隐含假设。但可以通过引用 Skill 和 Rule 来复用已有配置（见下方引用语法），无需在 query 中重复这些内容。
+
+### 在 query 中引用 Skills 和 Rules
+
+执行 Agent 加载的 Skills/Rules 与当前用户环境一致。**如果 workspace 路径不变**，query 中直接写 Skill 名称或 Rule 文件名即可，Agent 会自动识别：
+- `使用 code-security skill 扫描项目安全漏洞`
+- `遵循 code-style.mdr 中的代码规范`
+
+**如果 workspace 指向了不同项目**，需要用绝对路径引用，因为执行 Agent 加载的是目标项目的配置：
+- Skill 路径在 `{currentWorkspace}/.comate/skills/` 或 `~/.comate/skills/` 下查找
+- Rule 路径在 `{currentWorkspace}/.comate/rules/` 下查找
+
+Agent 已自动加载 `.comate/rules/` 下的所有规则，大多数情况下无需显式引用。但如果需要强调某条规则，提及文件名即可。
+
+---
+
+## 策略模板库
+
+本 Skill 附带一组**策略模板**，存放在 `{skill_dir}/references/` 目录下。这些模板不是固定流程——而是按需引用的设计参考，用于为中等和复杂任务定制更高质量的 query。
+
+### 模板分类与使用规则
+
+**第一类：横切策略（按需叠加，任何类型任务都可能用到）**
+
+| 模板文件 | 覆盖内容 | 何时读取 |
+|---------|---------|---------|
+| `references/env_setup.md` | 运行时激活、环境变量、依赖安装、非交互式约束 | 任务依赖特定运行时或环境变量时 |
+| `references/git_operations.md` | 拉代码、分支管理、提交、push | 任务涉及 Git 操作时 |
+| `references/long_running_task.md` | 超时管理、分步执行、幂等性、错误处理、自主排障 | 任务步骤多或预期耗时长时 |
+
+**第二类：领域参考（通常只需读一个，选与项目类型匹配的）**
+
+| 模板文件 | 覆盖内容 | 何时读取 |
+|---------|---------|---------|
+| `references/testing_strategy.md` | 成功标准定义、测试类型选择、失败处理、证据收集 | 任务核心目标是验证代码正确性时（不是"跑 npm test"这种单命令，而是"修改代码后需要验证"） |
+| `references/frontend_dev.md` | 前端构建验证、lint/类型检查、无 GUI 限制 | 任务涉及前端代码修改或前端质量检查时 |
+| `references/backend_dev.md` | 服务依赖、数据库迁移、API 测试、进程管理 | 任务涉及后端代码修改或后端运维时 |
+
+**使用规则**：
+- 第一类模板可叠加（一个任务可同时参考 env_setup + git_operations）
+- 第二类模板通常只需读一个（项目是前端就读 frontend_dev，是后端就读 backend_dev）
+- **简单任务（单条命令即可完成）：不读任何模板**
+
+### 使用方式
+
+1. **分析用户 query**：理解任务本质——是简单的脚本执行？代码修改？还是多步骤的端到端流程？
+2. **按需读取相关模板**：只读取与用户任务相关的模板
+3. **提取策略融入 query 或直接引用**：
+   - 如果模板中的策略需要针对用户项目做具体适配（如替换具体命令、路径），则从模板中提取要点写进 query
+   - 如果模板整体适用且无需适配，可以在 query 中引用模板的**绝对路径**让执行 Agent 自行读取，例如：`关于 Git 操作细节，参考 /Users/xxx/.comate/skills/create-automation-tasks/references/git_operations.md`（注意：必须使用绝对路径，不能用 `{skill_dir}` 变量，因为执行 Agent 无法解析该变量）
+
+---
+
+## 你的职责
+
+### 创建任务
+
+**1. 收集必填信息**
+
+必问（用户未提及时主动询问）：
+- **做什么**：任务目标 → AUTOMATION.md body 核心内容
+- **项目路径**：默认使用 `{currentWorkspace}`（当前 IDE 打开的项目路径）。如果用户指定了不同的项目路径，主动提醒用户：执行 Agent 会加载**目标项目**的 Comate 配置（Skills/Rules），而非当前项目的。如果用户的 query 需要引用当前项目中的 Skill 或 Rule，应在 `{currentWorkspace}/.comate/skills/` 或 `~/.comate/skills/` 下查找其绝对路径，并在 query 中使用绝对路径引用
+- **触发方式**：定时（询问频率/时间点）或 webhook
+
+按需询问（根据任务复杂度决定要不要问，简单任务少问，复杂任务细问）：
+- Git 操作：拉代码？提交/push 到哪个分支？
+- 测试：改完是否跑测试？用什么命令？
+- **执行环境**（关键，环境不对则任务必然失败）：
+  - 项目依赖什么运行时？Python venv / conda 环境名？Node nvm 版本？Java/Go 版本？
+  - 需要 source 哪个文件？（如 `source ~/.bashrc`、`conda activate myenv`、`nvm use 18`）
+  - 是否依赖环境变量？（如 API Key、数据库连接串）→ 引导用户给出 `.env` 文件路径或具体值
+  - 是否依赖配置文件？（如 `.npmrc`、`settings.xml`、`kubeconfig`）→ 引导用户给出绝对路径
+  - 如果用户不确定，建议先手动在终端跑一次任务核心命令，确认环境可用后再配置自动化
+- 超时时长
+
+**2. 设计 query（AUTOMATION.md body）**
+
+将用户意图转化为可被无人值守 Agent 端到端执行的自包含指令（参见上方"执行 Agent 的能力与约束"）。
+
+**query 设计的第一原则：最小充分**
+
+在设计 query 之前，先判断任务复杂度，选择对应策略：
+
+- **一条命令能完成**（跑测试、lint、生成报告）→ 直接写命令 + 摘要要求，**不读取任何模板，不添加任何额外策略**。示例 query：`运行 npm test，将结果摘要写入 promise_done_summary.md。`
+- **2-3 个步骤，逻辑清晰**（依赖更新 + 测试验证）→ 按需读取 1-2 个模板，提取适用要点
+- **多步骤端到端流程**（拉代码 → 修改 → 测试 → push）→ 读取多个模板组合设计，参考 `long_running_task.md` 设计分步方案
+
+设计要点：
+- **环境配置写在 query 最前面**（如果需要的话）：Agent 在全新 Session 中启动，不会继承用户终端的环境。参考 `references/env_setup.md` 中的策略
+- **利用 Skills/Rules 引用减少 query 冗余**：不需要在 query 中重复写 Rules 中已有的规范，Agent 会自动加载。但可以提示 Agent 注意某个 Rule 或使用某个 Skill（见上方"引用 Skills 和 Rules"语法）
+- 所有必要信息写进 query（不能依赖对话历史或隐含假设）
+- 结尾加上：`完成后请将执行摘要写入 promise_done_summary.md。`
+
+**3. 展示 AUTOMATION.md 并确认**
+
+展示完整的 AUTOMATION.md 内容（frontmatter + body）及写入路径，等用户确认。
+
+**4. 写入文件并校验**
+
+```bash
+mkdir -p ~/.comate/automations/{taskName}
+# 写入 AUTOMATION.md
+python3 {skill_dir}/scripts/check_config.py ~/.comate/automations/{taskName}/AUTOMATION.md
+```
+
+校验脚本验证 frontmatter 的 YAML 格式、必填字段、cron 语法等。校验通过后告知用户。若报错，根据提示修正后重新校验。
+
+**5. 引导试跑**
+
+> "配置已就绪。建议先去 Automations Dashboard 找到该任务，点击**立即运行（Run Now）**跑一次，在 Session History 中查看结果是否符合预期。"
+
+### 管理已有任务
+
+- **查看**：读取 AUTOMATION.md 展示
+- **修改**：直接编辑 AUTOMATION.md，提醒 Scheduler 会自动 reload
+- **删除**：二次确认后删除 `~/.comate/automations/{taskName}/` 整个目录
+- **查看历史**：告知用户在 IDE Automations Dashboard → Session History 中查看
+
+---
+
+## 注意事项
+
+- Automation 仅在 Comate 运行时触发，关闭 IDE 则不执行任何 cron
+- `triggerAt` 建议设为创建后的下一个预期执行时间点，避免立即触发补跑
+- 创建前检查是否已有同名任务（查看 ~/.comate/automations/ 下的目录）
+- webhook 的 `endpointId` 必须通过命令行生成，不可由模型凭空编造
+- timeoutSeconds 默认 3600，上限 7200
+
+---
+
+## Cron 表达式速查
+
+### 理解语法
+
+cron 的每个字段描述"这个时间维度上哪些值会触发"，五个字段同时满足才触发：
+
+```
+分(0-59)  时(0-23)  日(1-31)  月(1-12)  周(0-7, 0和7均为周日)
+```
+
+| 语法 | 含义 | 集合视角 |
+|------|------|---------|
+| `*` | 该字段所有值 | 全集 |
+| `1-5` | 1 到 5 | 区间子集 |
+| `*/5` | 每隔 5 取一个（0,5,10,...）| 步长子集（x mod 5 = 0）|
+| `2-10/3` | 区间内步长，{2,5,8} | 区间内步长子集 |
+| `1,3,5` | 仅 1、3、5 | 显式枚举集合 |
+
+### 常用表达式对照
+
+| 用户说法 | cron 表达式 | 向用户展示时说 |
+|---------|------------|--------------|
+| 每天早上9点 | `0 9 * * *` | 每天 09:00 |
+| 工作日早上9点 | `0 9 * * 1-5` | 周一至周五 09:00 |
+| 每周一早上10点 | `0 10 * * 1` | 每周一 10:00 |
+| 每4小时 | `0 */4 * * *` | 每4小时（00:00/04:00/08:00...）|
+| 每30分钟 | `*/30 * * * *` | 每30分钟整点和半点 |
+| 每天午夜 | `0 0 * * *` | 每天 00:00 |
+| 每月1号9点 | `0 9 1 * *` | 每月1日 09:00 |
+| 每周一、三、五下午5点 | `0 17 * * 1,3,5` | 周一、三、五 17:00 |
+
+### 向用户展示配置时
+
+展示 cron 表达式时，**始终附带人类可读描述**，例如：
+
+> `cron: "0 9 * * 1-5"` → 执行时间：**周一至周五 09:00**
+
+用户说"大概几点"时，避免整点 :00 和 :30——大量用户的相同时间会并发触发：
+- "大概早上9点" → 用 `57 8 * * *` 或 `3 9 * * *`，不用 `0 9 * * *`
+- "每小时" → 用 `7 * * * *`，不用 `0 * * * *`

package/comate-engine/assets/skills/create-automation-tasks-comate/references/backend_dev.md

@@ -0,0 +1,109 @@
+# 后端开发任务策略模板
+
+当 Automation 任务涉及后端代码修改或后端质量检查时，将以下策略融入 query 设计。
+
+## 适用场景
+
+- 修改后端业务逻辑、API 端点、数据库模型等
+- 后端依赖更新或安全修复
+- 运行后端测试套件
+- API 健康检查、数据库迁移等运维任务
+
+## 策略要点
+
+### 服务依赖
+
+后端任务常依赖外部服务（数据库、缓存、消息队列等）。**默认先尝试启动服务**，不要看到"需要 Postgres/Redis/MongoDB"就放弃——大多数项目的 dev 命令或 docker-compose 已处理了依赖启动或 mock。只有在遇到**具体的运行时错误**表明确实缺少某个依赖时，才将其视为阻塞并记录在摘要中。
+
+```
+# 如果依赖 Docker Compose 管理的服务
+docker compose up -d postgres redis
+# 等待服务就绪
+sleep 5
+```
+
+### 测试策略
+
+后端测试通常分层：
+
+```
+运行测试：
+1. 单元测试：{unit_test_command}
+2. 集成测试：{integration_test_command}    # 可选，取决于是否有服务依赖
+3. API 测试：curl -s http://localhost:{port}/health  # 如果需要验证服务可用性
+```
+
+- 如果任务只改了业务逻辑，单元测试通常足够
+- 如果改了 API 接口或数据库模型，需要集成测试
+
+### 数据库迁移
+
+如果任务涉及数据库 schema 变更：
+
+```
+执行数据库迁移：
+{migrate_command}    # 如 python manage.py migrate, npx prisma migrate dev
+
+迁移后验证：
+{test_command}
+```
+
+- 迁移命令必须写在 query 中，Agent 不会自动猜测
+- 如果迁移失败，Agent 应记录错误而非自行回滚
+
+### 长时间运行任务
+
+后端任务（如全量测试、数据处理）可能耗时较长：
+
+- 在 frontmatter 中设置合理的 `timeoutSeconds`（默认 3600，上限 7200）
+- 在 query 中提示 Agent 注意超时：
+  ```
+  注意：本任务可能耗时较长。如果某个步骤超过 30 分钟未完成，跳过该步骤并记录原因。
+  ```
+
+### 进程管理
+
+**Automation Agent 如果为了测试而启动了后端服务，任务结束前必须停止服务。** 不停服务会导致端口被占用，影响下次 run 或用户的正常开发。
+
+```
+注意：
+- 不要使用 pkill -f 按名称杀进程，必须使用具体 PID
+- 启动服务时记录 PID，测试完成后用 kill {PID} 停止
+- 使用 kill {PID} 而不是 kill -9，给进程优雅退出的机会
+```
+
+## query 片段示例
+
+**场景：后端依赖安全修复（Python）**
+```
+检查 Python 依赖的安全漏洞：
+pip audit
+
+如果发现漏洞：
+1. 更新有漏洞的包到安全版本
+2. 运行测试：pytest
+3. 如果测试通过，更新 requirements.txt
+4. 提交修改
+```
+
+**场景：定期运行后端测试套件**
+```
+运行后端完整测试套件：
+pytest --tb=short -q
+
+在摘要中报告：
+- 通过/失败/跳过的测试数量
+- 失败测试的名称和错误摘要
+- 总耗时
+```
+
+**场景：API 健康检查 + 数据库连接验证**
+```
+验证后端服务健康状态：
+1. 启动服务：{start_command}（记录 PID）
+2. 等待服务就绪（最多 30 秒）
+3. 检查健康端点：curl -sf http://localhost:{port}/health
+4. 检查数据库连接：{db_check_command}
+5. 用 kill {PID} 停止服务
+6. 报告各项检查结果
+```

package/comate-engine/assets/skills/create-automation-tasks-comate/references/env_setup.md

@@ -0,0 +1,130 @@
+# 环境配置策略模板
+
+Automation Agent 在全新 Session 中启动，不会继承用户终端的环境。如果任务依赖特定运行时、环境变量或配置，必须在 query 中显式声明。
+
+## 适用场景
+
+- 项目使用 Python venv / conda / poetry
+- 项目使用 Node.js nvm / fnm / volta
+- 项目依赖环境变量（API Key、数据库连接串等）
+- 项目需要特定系统依赖或配置文件
+
+## 关键约束
+
+**所有命令必须是非交互式的。** Automation Agent 在无人值守环境中运行，交互式命令（需要用户输入 y/n、选择菜单等）会导致 Agent stall 直至超时。始终使用非交互 flag：
+- `apt-get install -y`（不是 `apt-get install`）
+- `pip install --yes`
+- `npm install`（本身非交互）
+- `pnpm approve-builds` → 不要使用（交互式），改用 `pnpm.onlyBuiltDependencies` 配置
+
+## 策略要点
+
+### 运行时激活
+
+不同技术栈的环境激活方式：
+
+**Python：**
+```
+# conda
+source /path/to/miniconda3/bin/activate {env_name}
+
+# venv
+source /path/to/project/.venv/bin/activate
+
+# poetry（注意：不要用 poetry shell，它会创建子 shell，在非交互终端行为不可预测）
+source $(poetry env info --path)/bin/activate
+# 或者直接用 poetry run 前缀执行命令：
+poetry run pytest
+```
+
+**Node.js：**
+```
+# nvm
+export NVM_DIR="$HOME/.nvm" && source "$NVM_DIR/nvm.sh" && nvm use {version}
+
+# fnm
+eval "$(fnm env)" && fnm use {version}
+```
+
+**Java / Go / Rust：**
+```
+# JAVA_HOME
+export JAVA_HOME=/path/to/jdk && export PATH=$JAVA_HOME/bin:$PATH
+
+# Go
+export GOROOT=/path/to/go && export PATH=$GOROOT/bin:$PATH
+
+# Rust
+source $HOME/.cargo/env
+```
+
+### 包管理器匹配锁文件
+
+在 query 中使用与项目锁文件匹配的包管理器，不要混用：
+
+| 锁文件 | 包管理器 |
+|-------|---------|
+| `package-lock.json` | npm |
+| `yarn.lock` | yarn |
+| `pnpm-lock.yaml` | pnpm |
+| `bun.lockb` | bun |
+| `poetry.lock` | poetry |
+| `Pipfile.lock` | pipenv |
+| `uv.lock` | uv |
+
+如果不确定，查看项目根目录下存在哪个锁文件。安装依赖前建议先删除 `node_modules`（Node.js 项目）以确保干净状态。
+
+### 环境变量
+
+```
+# 从文件加载
+source /path/to/project/.env
+
+# 或逐个设置
+export API_KEY="..."
+export DATABASE_URL="..."
+```
+
+- 引导用户将敏感信息存入 `.env` 文件，query 中只写 `source .env`
+- 不要在 AUTOMATION.md 中硬编码密钥
+
+### 依赖安装
+
+如果任务需要确保依赖是最新的：
+
+```
+# 进入项目后先安装/更新依赖
+npm install        # Node.js
+pip install -r requirements.txt  # Python
+go mod download    # Go
+```
+
+### 常见陷阱
+
+1. **PATH 不完整**：全新 Session 的 PATH 可能不包含用户安装的工具。必要时显式设置
+2. **代理/镜像源**：如果项目依赖特定的 npm/pip 镜像源，需要在 query 中配置
+3. **Docker 环境**：如果任务需要 Docker，确认 Docker daemon 已启动
+
+## query 片段示例
+
+**场景：Python + conda 项目**
+```
+执行前先配置环境：
+source /Users/xxx/miniconda3/bin/activate myproject
+cd /path/to/project
+pip install -r requirements.txt
+```
+
+**场景：Node.js 项目 + 环境变量**
+```
+执行前先配置环境：
+export NVM_DIR="$HOME/.nvm" && source "$NVM_DIR/nvm.sh" && nvm use 18
+cd /path/to/project
+npm install
+source .env
+```
+
+**场景：无特殊环境要求**
+```
+（无需额外环境配置，直接执行任务）
+```

package/comate-engine/assets/skills/create-automation-tasks-comate/references/frontend_dev.md

@@ -0,0 +1,74 @@
+# 前端开发任务策略模板
+
+当 Automation 任务涉及前端代码修改或前端质量检查时，将以下策略融入 query 设计。
+
+## 适用场景
+
+- 修改 `.tsx`、`.jsx`、`.vue`、`.html`、`.css`、`.scss` 等前端文件
+- 前端依赖更新或安全修复
+- 前端构建、lint、类型检查等质量门禁
+- UI 组件库维护
+
+## 策略要点
+
+### 构建验证
+
+前端修改后，构建是否成功是最基本的验证：
+
+```
+修改完成后验证：
+1. 运行 lint：{lint_command}          # 如 npm run lint
+2. 运行类型检查：{typecheck_command}   # 如 npx tsc --noEmit
+3. 运行构建：{build_command}           # 如 npm run build
+```
+
+- 构建失败必须修复，不能忽略
+- lint 警告可以记录但不阻塞，lint 错误必须修复
+
+### 前端测试
+
+```
+运行前端测试：
+{test_command}                        # 如 npm run test, vitest run, jest
+```
+
+- 优先运行与修改相关的测试文件
+- 如果有 snapshot 测试，修改后可能需要更新 snapshot
+
+### 无人值守限制
+
+Automation Agent 在无人值守模式下运行，没有用户在线监督。因此：
+
+- 优先依赖构建成功 + lint 通过 + 自动化测试通过作为验证手段
+- 如果需要更深入的视觉验证且 Agent 具备浏览器能力（如 automation-browser skill），可以在 query 中指示 Agent 使用
+- 对于无法自动化验证的 UI 效果，在摘要中标注"建议人工检查 UI 效果"
+
+### 包管理器
+
+使用与项目锁文件匹配的包管理器（详见 `env_setup.md` 中的包管理器匹配表）。
+
+## query 片段示例
+
+**场景：前端依赖安全修复**
+```
+检查前端依赖的安全漏洞：
+npm audit
+
+如果发现漏洞：
+1. 运行 npm audit fix 尝试自动修复
+2. 如果 audit fix 无法解决，手动更新有漏洞的包到安全版本
+3. 修复后运行：npm run lint && npx tsc --noEmit && npm run build
+4. 运行测试：npm test
+5. 如果全部通过，提交修改
+```
+
+**场景：前端质量门禁检查**
+```
+运行前端质量检查：
+1. npm run lint
+2. npx tsc --noEmit
+3. npm test
+4. npm run build
+
+在摘要中报告每项检查的结果（通过/失败），以及失败项的具体错误。
+```