Dart Query Batch Ops

dart-query Batch Operations

任務批量操作：執行DartQL語句、批量更新/刪除、CSV導入。

Access Pattern (all examples below use this)

tool: mcp__plugin_slop-mcp_slop-mcp__execute_tool
params:
  mcp_name: "dart-query"
  tool_name: "<tool-name>"
  parameters: { ... }

Safety Protocol — MANDATORY

NEVER_SKIP:
  1: "ALWAYS dry_run: true first"
  2: "Review matched tasks before executing"
  3: "batch_delete requires confirm: true"
  4: "CSV import requires validate_only: true first"

DartQL Selector Syntax

DartQL採標準SQL-92 WHERE子句語法。知SQL即知DartQL。

Operators: =, !=, <>, >, >=, <, <=, AND, OR, NOT, LIKE (with % and _ wildcards), IN, NOT IN, BETWEEN, IS NULL, IS NOT NULL, CONTAINS (aliases: INCLUDES, HAS), parentheses for grouping. Strings use single quotes.

Available fields:

text:     title, description, status, dartboard, assignee  # singular in WHERE, maps to assignees array
string:   priority, size  # string values from get_config (e.g. "Critical", "High")
date:     due_at, start_at, created_at, updated_at, completed_at  # ISO8601
id:       parent_task, dart_id  # use IS NULL / IS NOT NULL
array:    tags, subtask_ids, blocker_ids, blocking_ids, duplicate_ids, related_ids

注意： 狀態與優先級名稱因工作區而異。用get_config發現工作區實際值。下列示例使用常見默認值——你的可能不同（如「To-do」vs「Todo」，「Doing」vs「In Progress」）。

Examples:

status = 'To-do' AND priority >= 4
status IN ('To-do', 'Doing') AND dartboard = 'Sprint 5'
title LIKE '%authentication%'
due_at BETWEEN '2026-02-15' AND '2026-02-28'
tags CONTAINS 'urgent' AND assignee IS NOT NULL

execute_dartql — Recommended

批量操作首選工具。支持帶SQL-92 WHERE子句之UPDATE與DELETE。

Features:

• Template variables: SET title = 'DONE: {title}' — 按任務字段值插值
• Inline COMMENT: UPDATE WHERE ... SET ... COMMENT 'reason' — 對每個匹配任務添加注釋
• Multi-statement: chain operations with ; separator
• Array literals: SET blocker_ids = ['id1', 'id2']

Parameters:

• query (string, required) — DartQL statement(s)
• dry_run (boolean, default true) — 預覽匹配而不修改
• concurrency (integer, default 5, range 1-20)

Example — simple status update (always dry_run first):

tool_name: execute_dartql
parameters:
  query: "UPDATE WHERE status = 'Todo' AND priority >= 4 SET status = 'In Progress'"
  dry_run: true

Example — template variable (prefix title per task):

tool_name: execute_dartql
parameters:
  query: "UPDATE WHERE dartboard = 'Sprint 5' AND status = 'Done' SET title = 'DONE: {title}' COMMENT 'Sprint completed'"
  dry_run: false
  concurrency: 10

Example — multi-statement (update then delete):

tool_name: execute_dartql
parameters:
  query: "UPDATE WHERE status = 'In Progress' SET priority = 3; DELETE WHERE status = 'Done' AND updated_at < '2026-01-01' CONFIRM;"
  dry_run: true

Example — use as query tool (dry_run returns matches without modifying):

tool_name: execute_dartql
parameters:
  query: "UPDATE WHERE tags CONTAINS 'urgent' AND assignee IS NULL SET status = 'Todo'"
  dry_run: true

batch_update_tasks — Deprecated (use execute_dartql)

仍可用，但新工作流首選execute_dartql。

Parameters:

• selector (string) — DartQL WHERE clause
• updates (object) — fields to update (same fields as update_task)
• dry_run (boolean, default true)
• concurrency (integer)

關係數組（blocker_ids、subtask_ids等）採完全替換語義——設[]以清空。

Example:

tool_name: batch_update_tasks
parameters:
  selector: "status = 'Todo' AND dartboard = 'Backlog'"
  updates:
    priority: 3
    tags: ["needs-triage"]
  dry_run: true

batch_delete_tasks — Deprecated (use execute_dartql)

額外安全：dry_run: false時需confirm: true。

Parameters:

• selector (string) — DartQL WHERE clause
• dry_run (boolean, default true)
• confirm (boolean) — REQUIRED when dry_run: false
• concurrency (integer)

Example:

tool_name: batch_delete_tasks
parameters:
  selector: "status = 'Done' AND completed_at < '2025-12-01'"
  dry_run: false
  confirm: true
  concurrency: 5

get_batch_status

查詢運行中或已完成批量操作之狀態。

Parameters:

• batch_operation_id (string) — returned in the response from any batch operation

操作完成後在內存中保留1小時。

Example:

tool_name: get_batch_status
parameters:
  batch_operation_id: "batch_abc123"

import_tasks_csv

從CSV批量創建任務。導入前必須驗證。

Parameters:

• dartboard (string, required) — target dartboard dart_id or name
• csv_data (string) — inline CSV content
• csv_file_path (string) — path to CSV file (one of csv_data or csv_file_path required)
• column_mapping (object) — map CSV headers to task fields
• validate_only (boolean, default true) — 解析驗證但不創建任務
• continue_on_error (boolean, default true) — 跳過無效行繼續
• concurrency (integer)

Workflow: validate_only: true → 審閱報告 → 設validate_only: false執行。

Standard CSV format (headers match task field names directly):

title,status,priority,assignee,due_at
"Fix login bug",Todo,2,user@example.com,2026-05-01
"Update docs",Todo,4,,

Custom column mapping (when CSV headers differ from field names):

column_mapping:
  "Task Name": title
  "Owner": assignee
  "Due Date": due_at
  "Urgency": priority

Example — inline CSV with validation:

tool_name: import_tasks_csv
parameters:
  dartboard: "Sprint 6"
  csv_data: |
    title,status,priority,due_at
    "Implement OAuth",Todo,2,2026-05-15
    "Write unit tests",Todo,3,2026-05-20
  validate_only: true

Example — file import with custom mapping:

tool_name: import_tasks_csv
parameters:
  dartboard: "Backlog"
  csv_file_path: "/tmp/tasks-export.csv"
  column_mapping:
    "Task Name": title
    "Priority Level": priority
    "Assigned To": assignee
  validate_only: false
  continue_on_error: true
  concurrency: 8

Concurrency Tuning

默認5對大多數操作安全。

• 1-2 — 關係字段（blocker_ids、subtask_ids）、有副作用之狀態轉換
• 5 (default) — 混合字段更新
• 10-20 — 大批量（100+任務）之簡單字段更新（priority、title）