idea-intake-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Idea Intake Workflow - Unified Interface

想法收集工作流 - 统一界面

Purpose

用途

Single command interface for Matt Maher's "do-work" autonomous idea intake pattern. Provides unified access to capture, validation, and processing operations without needing to remember multiple commands across different skills.
This skill orchestrates three sub-skills into a cohesive workflow:
  • idea-queue-capture - Fast idea capture
  • Senior PM Enhanced (validation) - Feasibility assessment and routing
  • work-queue-processor - Autonomous execution
Matt Maher的"do-work"自主想法收集模式的单一命令界面。无需记住不同技能的多个命令,即可统一访问想法捕获、验证和处理操作。
该技能将三个子技能编排为连贯的工作流:
  • idea-queue-capture - 快速想法捕获
  • Senior PM Enhanced(验证) - 可行性评估与路由
  • work-queue-processor - 自主执行

Philosophy

设计理念

One command to rule them all:
/workflow
with intelligent subcommands that handle the entire lifecycle from idea capture to execution and archival.
Context Isolation: Each phase runs in isolated contexts to prevent pollution and maintain predictable behaviour:
  • Capture Claude: Instant idea collection (no planning overhead)
  • Work Claude: Autonomous execution with fresh sub-agents per item
  • Validation: Runs in either instance with proper state tracking

一令通管:使用
/workflow
命令搭配智能子命令,处理从想法捕获到执行和归档的全生命周期。
上下文隔离:每个阶段在独立上下文中运行,防止污染并保持可预测的行为:
  • Capture Claude:即时想法收集(无规划开销)
  • Work Claude:为每个任务生成全新子Agent进行自主执行
  • 验证:在任一实例中运行并保持状态跟踪

Quick Start Guide

快速入门指南

For First-Time Users

首次使用用户

  1. Capture an idea: Simply type your idea naturally, then use
    /workflow capture
  2. Validate ideas: Use
    /workflow validate
    to have Senior PM assess feasibility and assign agents
  3. Process validated work: Use
    /workflow process
    to autonomously execute validated items
  4. Monitor progress: Use
    /workflow status
    to see what's happening in real-time
  1. 捕获想法:自然输入你的想法,然后使用
    /workflow capture
  2. 验证想法:使用
    /workflow validate
    让资深PM评估可行性并分配Agent
  3. 处理已验证任务:使用
    /workflow process
    自主执行已验证的任务项
  4. 监控进度:使用
    /workflow status
    实时查看当前状态

Common Workflows

常见工作流

Rapid capture mode (Capture Claude):
User: Fix the navigation padding on mobile
/workflow capture

User: Also analyze R&D transactions for FY2023-24
/workflow capture

User: And add dark mode toggle to settings
/workflow capture
Autonomous execution mode (Work Claude):
/workflow process --continuous

(Runs until queue empty or tokens exhausted)
Quick status check:
/workflow status

快速捕获模式(Capture Claude):
用户:修复移动端导航栏内边距问题
/workflow capture

用户:同时分析2023-24财年的研发交易
/workflow capture

用户:另外在设置中添加深色模式切换按钮
/workflow capture
自主执行模式(Work Claude):
/workflow process --continuous

(运行至队列空或令牌耗尽)
快速状态检查
/workflow status

Commands

命令说明

/workflow
(no args)

/workflow
(无参数)

Shows interactive menu with current queue status and available commands.
Output:
🔄 Idea Intake Workflow v2.0.0

Current Queue Status:
├─ Pending:    3 items (awaiting validation)
├─ Validated:  2 items (ready to process)
├─ Processing: 1 item  (currently executing)
└─ Completed:  15 items (archived)

Available Commands:
├─ /workflow capture   - Capture the current message as an idea
├─ /workflow validate  - Validate all pending items (PM review)
├─ /workflow process   - Process validated items (execute work)
├─ /workflow status    - Show detailed queue status
└─ /workflow stats     - Show performance statistics

💡 Quick Actions:
- To capture current message: /workflow capture
- To validate all pending: /workflow validate
- To process everything: /workflow process --continuous
- To see what's happening: /workflow status

📚 Documentation: .agent/skills/idea-intake-workflow/SKILL.md
When to use:
  • First time using the system
  • Forgot available subcommands
  • Need quick overview of queue state
Aliases: None (canonical form only)

显示交互式菜单,包含当前队列状态和可用命令。
输出
🔄 想法收集工作流 v2.0.0

当前队列状态:
├─ 待处理:    3项(等待验证)
├─ 已验证:  2项(可处理)
├─ 处理中: 1项 (正在执行)
└─ 已完成:  15项(已归档)

可用命令:
├─ /workflow capture   - 将当前消息捕获为想法
├─ /workflow validate  - 验证所有待处理项(PM审核)
├─ /workflow process   - 处理已验证项(执行任务)
├─ /workflow status    - 显示详细队列状态
└─ /workflow stats     - 显示性能统计数据

💡 快速操作:
- 捕获当前消息:/workflow capture
- 验证所有待处理项:/workflow validate
- 处理所有任务:/workflow process --continuous
- 查看当前状态:/workflow status

📚 文档:.agent/skills/idea-intake-workflow/SKILL.md
适用场景
  • 首次使用系统
  • 忘记可用子命令
  • 需要快速查看队列状态概览
别名:无(仅使用标准形式)

/workflow capture

/workflow capture

Captures the current user message (or previous message if empty) as an idea to the work queue.
Aliases:
capture
,
add
,
queue
,
idea
Process:
  1. Extract user's most recent message (or use provided text)
  2. Auto-detect type (feature/bug/improvement/task/client_request)
  3. Generate concise title (max 80 chars)
  4. Apply intelligent grouping if multiple related ideas detected
  5. Write to Supabase work_queue with status='pending'
  6. Return confirmation with queue ID and position
Implementation:
typescript
import { addToQueue } from '@/lib/queue/work-queue-manager';

// Capture idea
const queueItem = await addToQueue({
  title: generatedTitle,
  description: userInputVerbatim,
  queue_item_type: detectedType,
  payload: {
    original_message: userInput,
    context: currentContext,
    timestamp: new Date().toISOString(),
    source: 'workflow-capture',
  },
});

console.log(`✅ Captured: ${queueItem.title} (ID: ${queueItem.id})`);
Example 1 - Simple Bug:
User: The navigation header has too much padding on mobile devices
User: /workflow capture

Claude: ✅ Idea captured successfully!

**Title**: Fix navigation header padding on mobile
**Type**: Bug
**Queue position**: #3
**Status**: Pending validation

Next: The Senior PM agent will validate this idea and assign it to an agent.
Example 2 - Multiple Related Ideas (Grouped):
User: The description panel has two issues:
1. The copy icon overlaps with text
2. There's not enough spacing between sections
User: /workflow capture

Claude: ✅ Idea captured successfully!

**Title**: Fix description panel UI issues
**Type**: Bug
**Queue position**: #4
**Status**: Pending validation

Note: Grouped 2 related issues affecting the same component.
Next: Senior PM will validate and route to the appropriate agent.
Example 3 - Multiple Unrelated Ideas (Separated):
User: Fix the copy icon overlap. Also, analyze R&D transactions for FY2023-24.
User: /workflow capture

Claude: ✅ 2 ideas captured successfully!

1. **Fix copy icon overlap** (Bug) - Position #5
2. **Analyze R&D transactions for FY2023-24** (Feature) - Position #6

Note: Created separate items since these are different domains (UI vs tax analysis).
Next: Senior PM will validate both ideas.
Example 4 - Explicit Text Capture:
User: /workflow capture Add dark mode toggle to settings page

Claude: ✅ Idea captured successfully!

**Title**: Add dark mode toggle to settings page
**Type**: Feature
**Queue position**: #7
**Status**: Pending validation

Next: Senior PM will validate and assess feasibility.
Options:
  • --text "..."
    - Capture specific text instead of previous message
  • --type <type>
    - Override auto-detection (feature|bug|improvement|client_request|task)
  • --separate
    - Force multiple ideas to be separate items (disable grouping)
Error Handling:
❌ Failed to capture idea

Error: Database connection failed

Suggestions:
- Check SUPABASE_SERVICE_ROLE_KEY is configured
- Verify Supabase project is running
- Run migration: supabase migration up

Your idea has not been lost. Please try again or contact support.

将当前用户消息(若为空则使用上一条消息)捕获为想法并加入工作队列。
别名
capture
,
add
,
queue
,
idea
流程
  1. 提取用户最新消息(或使用提供的文本)
  2. 自动检测类型(功能需求/BUG/改进/任务/客户请求)
  3. 生成简洁标题(最多80字符)
  4. 若检测到多个相关想法则自动智能分组
  5. 写入Supabase的
    work_queue
    表,状态标记为'pending'
  6. 返回包含队列ID和位置的确认信息
实现代码
typescript
import { addToQueue } from '@/lib/queue/work-queue-manager';

// 捕获想法
const queueItem = await addToQueue({
  title: generatedTitle,
  description: userInputVerbatim,
  queue_item_type: detectedType,
  payload: {
    original_message: userInput,
    context: currentContext,
    timestamp: new Date().toISOString(),
    source: 'workflow-capture',
  },
});

console.log(`✅ 已捕获:${queueItem.title} (ID: ${queueItem.id})`);
示例1 - 简单BUG
用户:移动端导航栏内边距太大了
用户:/workflow capture

Claude:✅ 想法捕获成功!

**标题**:修复移动端导航栏内边距问题
**类型**:BUG
**队列位置**:#3
**状态**:待验证

下一步:资深PM Agent将验证此想法并分配给对应执行Agent。
示例2 - 多个相关想法(已分组)
用户:描述面板有两个问题:
1. 复制图标与文本重叠
2. 各区块之间间距不足
用户:/workflow capture

Claude:✅ 想法捕获成功!

**标题**:修复描述面板UI问题
**类型**:BUG
**队列位置**:#4
**状态**:待验证

说明:已将影响同一组件的2个相关问题分组。
下一步:资深PM将验证并路由至对应Agent。
示例3 - 多个不相关想法(已拆分)
用户:修复复制图标重叠问题。另外,分析2023-24财年的研发交易。
用户:/workflow capture

Claude:✅ 已成功捕获2个想法!

1. **修复复制图标重叠问题**(BUG)- 位置#5
2. **分析2023-24财年研发交易**(功能需求)- 位置#6

说明:因属于不同领域(UI vs 税务分析),已创建独立任务项。
下一步:资深PM将验证这两个想法。
示例4 - 显式文本捕获
用户:/workflow capture 在设置页面添加深色模式切换按钮

Claude:✅ 想法捕获成功!

**标题**:在设置页面添加深色模式切换按钮
**类型**:功能需求
**队列位置**:#7
**状态**:待验证

下一步:资深PM将验证并评估可行性。
选项
  • --text "..."
    - 捕获指定文本而非上一条消息
  • --type <type>
    - 覆盖自动检测的类型(feature|bug|improvement|client_request|task)
  • --separate
    - 强制将多个想法拆分为独立任务项(禁用分组)
错误处理
❌ 想法捕获失败

错误:数据库连接失败

建议:
- 检查SUPABASE_SERVICE_ROLE_KEY是否配置正确
- 验证Supabase项目是否正常运行
- 执行迁移:supabase migration up

你的想法未丢失,请重试或联系支持人员。

/workflow validate

/workflow validate

Validates all pending queue items using Senior PM Enhanced agent. Performs feasibility assessment, complexity analysis, duplicate detection, priority assignment, and agent routing.
Aliases:
validate
,
review
,
pm-review
Process:
  1. Fetch all pending items from work_queue (status='pending')
  2. For each item: a. Assess feasibility (0-100 score) b. Determine complexity (simple/medium/complex) c. Check for duplicates in Linear d. Assign priority (P0/P1/P2/P3) e. Route to domain agent f. Determine execution strategy (direct/requires_planning/specialist_review) g. Calculate confidence score
  3. Mark items as 'validated' with validation_result
  4. Optionally create Linear issues if not duplicates
  5. Return summary of validated items
Implementation:
typescript
import { getQueueItemsByStatus, markAsValidating, markAsValidated } from '@/lib/queue/work-queue-manager';
import { validateQueueItem } from '@/lib/queue/pm-validator';

// Fetch pending items
const pendingItems = await getQueueItemsByStatus('pending');

for (const item of pendingItems) {
  // Mark as validating
  await markAsValidating(item.id);

  // Run validation
  const validationResult = await validateQueueItem(item);

  // Mark as validated
  await markAsValidated(item.id, validationResult);

  console.log(`✅ Validated: ${item.title}`);
  console.log(`   Complexity: ${validationResult.complexity}`);
  console.log(`   Priority: ${validationResult.priority}`);
  console.log(`   Agent: ${validationResult.assigned_agent}`);
}
Example 1 - Single Item Validation:
User: /workflow validate

Claude: 🔍 Starting validation of pending items...

Validating: Fix navigation header padding on mobile

**Feasibility Score**: 85/100
- Frontend changes are straightforward with existing patterns
- UI component change with minimal risk

**Complexity**: Simple
- Single file change, straightforward implementation

**Priority**: P2 (Medium)
- Bug fix, affects user experience

**Assigned Agent**: general
- No specialist required

**Execution Strategy**: Direct
- Can execute immediately without planning phase

**Confidence**: 80%

**Duplicate Check**: No duplicates found

✅ Validation complete! Item ready for processing.

Status changed: pending → validated
Example 2 - Multiple Items with Duplicate Detection:
User: /workflow validate

Claude: 🔍 Starting validation of pending items...

[1/3] Validating: Fix description panel spacing

**Feasibility Score**: 90/100
**Complexity**: Simple
**Priority**: P2
**Agent**: general
**Strategy**: Direct
**Confidence**: 85%
**Duplicate**: ⚠️ Similar to UNI-42 (87% match)

Action: Merging context into existing Linear issue UNI-42
Status: Marked as duplicate, will not create new issue

---

[2/3] Validating: Analyze R&D transactions for FY2023-24

**Feasibility Score**: 95/100
- Xero integration available for data extraction
- R&D Tax Incentive specialist available

**Complexity**: Complex
- Significant analysis required, multiple files affected

**Priority**: P1 (High)
- R&D registration deadline approaching

**Assigned Agent**: rnd-tax-specialist
- Routed to R&D specialist for Division 355 analysis

**Execution Strategy**: Specialist Review
- Requires user approval before execution due to complexity

**Confidence**: 90%
**Duplicate**: No duplicates found

Action: Creating Linear issue...
✅ Created: UNI-45 - Analyze R&D transactions for FY2023-24

---

[3/3] Validating: Add dark mode toggle to settings

**Feasibility Score**: 85/100
**Complexity**: Medium
**Priority**: P3 (Low)
**Agent**: general
**Strategy**: Requires Planning
- Requires planning sub-agent before execution

**Confidence**: 80%
**Duplicate**: No duplicates found

Action: Creating Linear issue...
✅ Created: UNI-46 - Add dark mode toggle to settings

---

📊 Validation Summary
- Total pending: 3 items
- Validated: 3 items
- Duplicates: 1 item
- Linear issues created: 2 items
- Ready for execution: 3 items (2 new, 1 merged)

Next: Use `/workflow process` to start autonomous execution
Options:
  • --batch <N>
    - Validate max N items (default: all pending)
  • --create-issues
    - Create Linear issues immediately (default: true)
  • --skip-duplicates
    - Skip duplicate checking (faster, not recommended)
Validation Criteria:
CriterionThresholdsAction
Feasibility Score< 50Mark as not feasible, require user review
Feasibility Score50-79Mark as feasible with notes
Feasibility Score80-100Mark as highly feasible
Duplicate Similarity> 70%Flag as duplicate, merge context
Duplicate Similarity50-70%Flag as potential duplicate, notify user
Duplicate Similarity< 50%Not a duplicate
Error Handling:
❌ Validation failed for: Analyze R&D transactions

Error: Linear API connection failed

Action: Marked as 'validating' (will retry)
Suggestion: Check LINEAR_API_KEY and retry

Continuing with other items...

使用Senior PM Enhanced Agent验证所有待处理队列项。执行可行性评估、复杂度分析、重复项检测、优先级分配和Agent路由。
别名
validate
,
review
,
pm-review
流程
  1. work_queue
    表获取所有待处理项(状态为'pending')
  2. 对每个任务项: a. 评估可行性(0-100分) b. 确定复杂度(简单/中等/复杂) c. 在Linear中检查重复项 d. 分配优先级(P0/P1/P2/P3) e. 路由至领域Agent f. 确定执行策略(直接执行/需要规划/专家审核) g. 计算置信度得分
  3. 将任务项标记为'validated'并保存验证结果
  4. 若不是重复项则可选创建Linear问题
  5. 返回已验证任务项的摘要
实现代码
typescript
import { getQueueItemsByStatus, markAsValidating, markAsValidated } from '@/lib/queue/work-queue-manager';
import { validateQueueItem } from '@/lib/queue/pm-validator';

// 获取待处理项
const pendingItems = await getQueueItemsByStatus('pending');

for (const item of pendingItems) {
  // 标记为验证中
  await markAsValidating(item.id);

  // 执行验证
  const validationResult = await validateQueueItem(item);

  // 标记为已验证
  await markAsValidated(item.id, validationResult);

  console.log(`✅ 已验证:${item.title}`);
  console.log(`   复杂度:${validationResult.complexity}`);
  console.log(`   优先级:${validationResult.priority}`);
  console.log(`   分配Agent:${validationResult.assigned_agent}`);
}
示例1 - 单个任务项验证
用户:/workflow validate

Claude:🔍 开始验证待处理项...

验证中:修复移动端导航栏内边距问题

**可行性得分**:85/100
- 前端修改可基于现有模式直接完成
- UI组件修改风险极低

**复杂度**:简单
- 仅需修改单个文件,实现直接明了

**优先级**:P2(中等)
- BUG修复,影响用户体验

**分配Agent**:general
- 无需专业Agent

**执行策略**:直接执行
- 无需规划阶段可立即执行

**置信度**:80%

**重复项检查**:未发现重复项

✅ 验证完成!任务项已准备好执行。

状态已变更:pending → validated
示例2 - 多个任务项验证(含重复项检测)
用户:/workflow validate

Claude:🔍 开始验证待处理项...

[1/3] 验证中:修复描述面板间距问题

**可行性得分**:90/100
**复杂度**:简单
**优先级**:P2
**分配Agent**:general
**策略**:直接执行
**置信度**:85%
**重复项**:⚠️ 与UNI-42高度相似(匹配度87%)

操作:将上下文合并至现有Linear问题UNI-42
状态:标记为重复项,不会创建新问题

---

[2/3] 验证中:分析2023-24财年研发交易

**可行性得分**:95/100
- 已集成Xero可用于数据提取
- 有R&D税收激励专业Agent可用

**复杂度**:复杂
- 需要大量分析,涉及多个文件

**优先级**:P1(高)
- 研发注册截止日期临近

**分配Agent**:rnd-tax-specialist
- 路由至R&D专业Agent进行Division 355分析

**执行策略**:专家审核
- 因复杂度高,执行前需用户批准

**置信度**:90%
**重复项**:未发现重复项

操作:正在创建Linear问题...
✅ 已创建:UNI-45 - 分析2023-24财年研发交易

---

[3/3] 验证中:在设置中添加深色模式切换按钮

**可行性得分**:85/100
**复杂度**:中等
**优先级**:P3(低)
**分配Agent**:general
**策略**:需要规划
- 执行前需规划子Agent参与

**置信度**:80%
**重复项**:未发现重复项

操作:正在创建Linear问题...
✅ 已创建:UNI-46 - 在设置中添加深色模式切换按钮

---

📊 验证摘要
- 待处理项总数:3项
- 已验证:3项
- 重复项:1项
- 创建Linear问题:2项
- 可执行:3项(2项新任务,1项合并)

下一步:使用`/workflow process`启动自主执行
选项
  • --batch <N>
    - 最多验证N个任务项(默认:所有待处理项)
  • --create-issues
    - 立即创建Linear问题(默认:true)
  • --skip-duplicates
    - 跳过重复项检查(速度更快,不推荐)
验证标准
标准阈值操作
可行性得分< 50标记为不可行,需用户审核
可行性得分50-79标记为可行并添加备注
可行性得分80-100标记为高度可行
重复项相似度> 70%标记为重复项,合并上下文
重复项相似度50-70%标记为潜在重复项,通知用户
重复项相似度< 50%非重复项
错误处理
❌ 验证失败:分析研发交易

错误:Linear API连接失败

操作:标记为'validating'(将重试)
建议:检查LINEAR_API_KEY并重试

继续处理其他任务项...

/workflow process

/workflow process

Processes all validated queue items autonomously using the work-queue-processor pattern. Spawns fresh sub-agent contexts for each item to avoid context pollution.
Aliases:
process
,
execute
,
work
,
do-work
Process:
  1. Fetch next validated item (status='validated', ordered by priority then creation time)
  2. Mark item as 'processing'
  3. Create Linear issue if not exists
  4. Route based on complexity:
    • Simple: Execute directly
    • Medium: PLANNER sub-agent → EXECUTOR sub-agent
    • Complex: PLANNER sub-agent → USER APPROVAL → EXECUTOR sub-agent
  5. Update Linear status as work progresses
  6. Capture before/after screenshots
  7. Mark as 'complete' or 'failed'
  8. Archive if complete
  9. Repeat until queue empty or stopped
Implementation:
typescript
import { getNextValidatedItem, markAsProcessing, markAsComplete, markAsFailed } from '@/lib/queue/work-queue-manager';
import { createIssue, updateIssue } from '@/lib/linear/api-client';

// Orchestrator loop
while (true) {
  // Fetch next item
  const item = await getNextValidatedItem();
  if (!item) {
    console.log('Queue is empty');
    break;
  }

  // Mark as processing
  await markAsProcessing(item.id);

  // Create Linear issue if needed
  if (!item.linear_issue_id) {
    const issue = await createIssue(buildIssueFromQueue(item));
    await updateLinearMetadata(item.id, {
      issue_id: issue.id,
      issue_identifier: issue.identifier,
      issue_url: issue.url,
    });
  }

  // Execute based on complexity
  try {
    let result;
    if (item.complexity === 'simple') {
      result = await executeSimpleTask(item);
    } else if (item.complexity === 'medium') {
      const plan = await spawnPlannerSubAgent(item);
      result = await spawnExecutorSubAgent(item, plan);
    } else {
      const plan = await spawnPlannerSubAgent(item);
      const approved = await askUserForApproval(plan);
      if (!approved) {
        await markAsFailed(item.id, 'User rejected plan');
        continue;
      }
      result = await spawnExecutorSubAgent(item, plan);
    }

    // Mark as complete
    await markAsComplete(item.id, result);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('completed'),
    });

  } catch (error) {
    // Mark as failed
    await markAsFailed(item.id, error.message);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('canceled'),
    });
  }

  // Rate limit (4-second delay)
  await sleep(4000);
}
Example 1 - Simple Item (Direct Execution):
User: /workflow process

Claude: ⚙️ Work Queue Processor Started

[1/3] Processing: Fix navigation header padding on mobile (UNI-43)
- Complexity: simple
- Strategy: Direct execution (no planning needed)

Executing...
- Reading: app/components/Navigation.tsx
- Analyzing: Current padding values
- Updating: Mobile breakpoint padding from 20px to 12px
- Testing: Visual verification

✅ Complete! (3 minutes)

Changes:
- Updated: app/components/Navigation.tsx (1 file, 3 lines changed)
- Before screenshot: .queue/screenshots/uuid-123/before.png
- After screenshot: .queue/screenshots/uuid-123/after.png

Linear: https://linear.app/unite-hub/issue/UNI-43
Status: Complete → Archived

---

[2/3] Processing: Add dark mode toggle to settings (UNI-46)
- Complexity: medium
- Strategy: Requires planning
- Agent: general

Spawning PLANNER sub-agent...

📋 Plan Created:
1. Create ThemeContext provider with light/dark state
2. Create ThemeToggle component with switch UI
3. Update existing components to read from ThemeContext
4. Add CSS variables for theme colors
5. Persist theme preference to localStorage

✓ Plan approved automatically (medium complexity)

Spawning EXECUTOR sub-agent...

Executing plan...
- Created: lib/theme/ThemeContext.tsx
- Created: components/ThemeToggle.tsx
- Updated: app/layout.tsx (wrap with ThemeProvider)
- Updated: 8 components to use theme colors
- Added: CSS variables in globals.css
- Added: localStorage persistence

Testing dark mode...
✅ Light mode works
✅ Dark mode works
✅ Theme persists on reload

✅ Complete! (12 minutes)

Changes:
- Created: 2 files
- Updated: 10 files
- Total lines: 247 lines changed

Linear: https://linear.app/unite-hub/issue/UNI-46
Status: Complete → Archived

---

[3/3] Processing: Analyze R&D transactions for FY2023-24 (UNI-45)
- Complexity: complex
- Strategy: Specialist review required
- Agent: rnd-tax-specialist

Spawning PLANNER sub-agent (rnd-tax-specialist)...

📋 Plan Created:
1. Fetch all Xero transactions for FY2023-24 (July 1, 2023 - June 30, 2024)
2. Filter for potential R&D expenditure (development, research, consulting)
3. Apply Division 355 four-element test to each transaction
4. Calculate eligible expenditure
5. Calculate R&D tax offset (43.5% for turnover < $20M)
6. Generate compliance report with legislative references
7. Flag transactions requiring further review

Estimated value: $200K-$500K potential refund

⚠️ This is a complex analysis involving significant financial value.

Proceed with execution? [Yes/No]

User: Yes

✓ Approved by user

Spawning EXECUTOR sub-agent (rnd-tax-specialist)...

Executing R&D analysis...
- Fetching Xero transactions (July 1, 2023 - June 30, 2024)...
- Retrieved: 1,247 transactions
- Filtering for potential R&D expenditure...
- Found: 387 potential R&D transactions

Applying Division 355 four-element test...
- Test 1 (New Knowledge): 256 transactions pass
- Test 2 (Outcome Unknown): 198 transactions pass
- Test 3 (Systematic Approach): 167 transactions pass
- Test 4 (Scientific Method): 127 transactions pass

✅ Eligible: 127 transactions

Calculating tax benefit...
- Total eligible expenditure: $293,000
- R&D tax offset (43.5%): $127,455
- Potential refund: $127,455

Generating compliance report...
- Transaction breakdown by category
- Four-element test results per transaction
- Legislative references (Division 355 ITAA 1997)
- Registration deadline: April 30, 2025
- Professional review recommendations

✅ Complete! (18 minutes)

Analysis Summary:
- Transactions analyzed: 1,247
- Eligible R&D transactions: 127
- Eligible expenditure: $293,000
- Tax offset: $127,455
- Confidence: High (90%)

Report saved: .queue/reports/rnd-analysis-fy2023-24.pdf

⚠️ Recommendations:
- Professional review required before submission
- Register with AusIndustry before April 30, 2025
- 15 transactions flagged for further documentation

Linear: https://linear.app/unite-hub/issue/UNI-45
Status: Complete → Archived

---

📊 Session Complete

Processed: 3 items
Succeeded: 3 items (100%)
Failed: 0 items
Total time: 33 minutes
Tokens used: ~18,500 PTS

Queue status:
- Pending: 0 items
- Validated: 0 items
- Processing: 0 items

All items complete! 🎉
Example 2 - Continuous Mode:
User: /workflow process --continuous

Claude: ⚙️ Work Queue Processor Started (Continuous Mode)

Will process items continuously until queue empty or tokens exhausted.

Press Ctrl+C or use /workflow pause to stop gracefully.

---

[1/10] Processing: Fix copy icon overlap (UNI-42)
...
✅ Complete! (2 minutes)

[2/10] Processing: Update form validation (UNI-47)
...
✅ Complete! (8 minutes)

[3/10] Processing: Refactor tax calculation logic (UNI-48)
...
⚙️ Processing... (45% complete)

(Continues until queue empty)

---

📊 Session Complete

Processed: 10 items
Succeeded: 9 items (90%)
Failed: 1 item (10%)
Total time: 87 minutes
Tokens used: ~42,300 PTS
Tokens remaining: ~47,700 PTS

Queue status: Empty

Next: Use /workflow capture to add more ideas
Options:
  • --continuous
    - Run until queue empty or tokens exhausted
  • --limit <N>
    - Process maximum N items then stop
  • --priority <P>
    - Only process items with specific priority (P0/P1/P2/P3)
  • --agent <name>
    - Only process items assigned to specific agent
Error Handling:
When an item fails:
❌ Execution failed: Add dark mode toggle (UNI-46)

Error: Component ThemeContext.tsx already exists
Retry count: 1/3

Action:
- Marked as 'failed' with error message
- Updated Linear issue to 'Canceled'
- Added comment to Linear with error details

The work loop will continue with the next item.
To retry failed items, use /workflow retry
When token budget is low:
⚠️ Token budget low (8,500 PTS remaining)

Action: Pausing work loop gracefully
Status: Saved processor state

Items processed this session: 8
Items remaining in queue: 2

To resume: /workflow process
Performance Targets:
MetricTarget
Simple item execution< 5 minutes
Medium item execution< 15 minutes
Complex item execution< 30 minutes
Queue throughput10-25 items per 90 minutes
Success rate> 95%
Token usage per item50-500 PTS

使用work-queue-processor模式自主处理所有已验证队列项。为每个任务项生成全新子Agent上下文,避免上下文污染。
别名
process
,
execute
,
work
,
do-work
流程
  1. 获取下一个已验证任务项(状态为'validated',按优先级和创建时间排序)
  2. 将任务项标记为'processing'
  3. 若不存在则创建Linear问题
  4. 根据复杂度路由:
    • 简单:直接执行
    • 中等:PLANNER子Agent → EXECUTOR子Agent
    • 复杂:PLANNER子Agent → 用户批准 → EXECUTOR子Agent
  5. 随着任务推进更新Linear状态
  6. 捕获前后截图
  7. 标记为'complete'或'failed'
  8. 若完成则归档
  9. 重复至队列为空或停止
实现代码
typescript
import { getNextValidatedItem, markAsProcessing, markAsComplete, markAsFailed } from '@/lib/queue/work-queue-manager';
import { createIssue, updateIssue } from '@/lib/linear/api-client';

// 编排器循环
while (true) {
  // 获取下一个任务项
  const item = await getNextValidatedItem();
  if (!item) {
    console.log('队列为空');
    break;
  }

  // 标记为处理中
  await markAsProcessing(item.id);

  // 若需要则创建Linear问题
  if (!item.linear_issue_id) {
    const issue = await createIssue(buildIssueFromQueue(item));
    await updateLinearMetadata(item.id, {
      issue_id: issue.id,
      issue_identifier: issue.identifier,
      issue_url: issue.url,
    });
  }

  // 根据复杂度执行
  try {
    let result;
    if (item.complexity === 'simple') {
      result = await executeSimpleTask(item);
    } else if (item.complexity === 'medium') {
      const plan = await spawnPlannerSubAgent(item);
      result = await spawnExecutorSubAgent(item, plan);
    } else {
      const plan = await spawnPlannerSubAgent(item);
      const approved = await askUserForApproval(plan);
      if (!approved) {
        await markAsFailed(item.id, '用户拒绝了计划');
        continue;
      }
      result = await spawnExecutorSubAgent(item, plan);
    }

    // 标记为完成
    await markAsComplete(item.id, result);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('completed'),
    });

  } catch (error) {
    // 标记为失败
    await markAsFailed(item.id, error.message);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('canceled'),
    });
  }

  // 速率限制(4秒延迟)
  await sleep(4000);
}
示例1 - 简单任务项(直接执行)
用户:/workflow process

Claude:⚙️ 工作队列处理器已启动

[1/3] 处理中:修复移动端导航栏内边距问题(UNI-43)
- 复杂度:简单
- 策略:直接执行(无需规划)

执行中...
- 读取:app/components/Navigation.tsx
- 分析:当前内边距值
- 更新:移动端断点内边距从20px改为12px
- 测试:视觉验证

✅ 完成!(3分钟)

变更:
- 更新:app/components/Navigation.tsx(1个文件,修改3行)
- 截图(处理前):.queue/screenshots/uuid-123/before.png
- 截图(处理后):.queue/screenshots/uuid-123/after.png

Linear链接:https://linear.app/unite-hub/issue/UNI-43
状态:已完成 → 已归档

---

[2/3] 处理中:在设置中添加深色模式切换按钮(UNI-46)
- 复杂度:中等
- 策略:需要规划
- Agent:general

正在生成PLANNER子Agent...

📋 已创建计划:
1. 创建支持亮色/暗色状态的ThemeContext提供者
2. 创建带开关UI的ThemeToggle组件
3. 更新现有组件以读取ThemeContext
4. 添加主题颜色的CSS变量
5. 将主题偏好持久化到localStorage

✓ 计划已自动批准(中等复杂度)

正在生成EXECUTOR子Agent...

执行计划中...
- 创建:lib/theme/ThemeContext.tsx
- 创建:components/ThemeToggle.tsx
- 更新:app/layout.tsx(用ThemeProvider包裹)
- 更新:8个组件以使用主题颜色
- 添加:globals.css中的CSS变量
- 添加:localStorage持久化

测试深色模式...
✅ 亮色模式正常
✅ 暗色模式正常
✅ 刷新后主题保持不变

✅ 完成!(12分钟)

变更:
- 创建:2个文件
- 更新:10个文件
- 总修改行数:247行

Linear链接:https://linear.app/unite-hub/issue/UNI-46
状态:已完成 → 已归档

---

[3/3] 处理中:分析2023-24财年研发交易(UNI-45)
- 复杂度:复杂
- 策略:需要专家审核
- Agent:rnd-tax-specialist

正在生成PLANNER子Agent(rnd-tax-specialist)...

📋 已创建计划:
1. 获取2023-24财年(2023年7月1日-2024年6月30日)的所有Xero交易
2. 筛选潜在的R&D支出(开发、研究、咨询)
3. 对每个交易应用Division 355四要素测试
4. 计算符合条件的支出
5. 计算R&D税收抵免(营业额<2000万澳元为43.5%)
6. 生成包含法规引用的合规报告
7. 标记需要进一步审核的交易

预估价值:潜在退款20万-50万澳元

⚠️ 这是涉及重大财务价值的复杂分析。

是否继续执行?[是/否]

用户:是

✓ 用户已批准

正在生成EXECUTOR子Agent(rnd-tax-specialist)...

执行R&D分析中...
- 获取Xero交易(2023年7月1日-2024年6月30日)...
- 已获取:1247笔交易
- 筛选潜在R&D支出...
- 发现:387笔潜在R&D交易

应用Division 355四要素测试...
- 测试1(新知识):256笔交易通过
- 测试2(结果未知):198笔交易通过
- 测试3(系统方法):167笔交易通过
- 测试4(科学方法):127笔交易通过

✅ 符合条件:127笔交易

计算税收优惠...
- 总符合条件支出:293,000澳元
- R&D税收抵免(43.5%):127,455澳元
- 潜在退款:127,455澳元

生成合规报告...
- 按类别划分的交易明细
- 每笔交易的四要素测试结果
- 法规引用(Division 355 ITAA 1997)
- 注册截止日期:2025年4月30日
- 专业审核建议

✅ 完成!(18分钟)

分析摘要:
- 分析交易数:1247笔
- 符合条件的R&D交易:127笔
- 符合条件支出:293,000澳元
- 税收抵免:127,455澳元
- 置信度:高(90%)

报告已保存:.queue/reports/rnd-analysis-fy2023-24.pdf

⚠️ 建议:
- 提交前需专业审核
- 2025年4月30日前向AusIndustry注册
- 15笔交易需补充文档

Linear链接:https://linear.app/unite-hub/issue/UNI-45
状态:已完成 → 已归档

---

📊 会话完成

已处理:3项
成功:3项(100%)
失败:0项
总耗时:33分钟
使用令牌:约18,500 PTS

队列状态:
- 待处理:0项
- 已验证:0项
- 处理中:0项

所有任务项已完成!🎉
示例2 - 连续模式
用户:/workflow process --continuous

Claude:⚙️ 工作队列处理器已启动(连续模式)

将持续处理任务项直到队列为空或令牌耗尽。

按Ctrl+C或使用/workflow pause优雅停止。

---

[1/10] 处理中:修复复制图标重叠问题(UNI-42)
...
✅ 完成!(2分钟)

[2/10] 处理中:更新表单验证(UNI-47)
...
✅ 完成!(8分钟)

[3/10] 处理中:重构税收计算逻辑(UNI-48)
...
⚙️ 处理中...(完成45%)

(持续处理直到队列为空)

---

📊 会话完成

已处理:10项
成功:9项(90%)
失败:1项(10%)
总耗时:87分钟
使用令牌:约42,300 PTS
剩余令牌:约47,700 PTS

队列状态:空

下一步:使用/workflow capture添加更多想法
选项
  • --continuous
    - 运行至队列为空或令牌耗尽
  • --limit <N>
    - 最多处理N个任务项后停止
  • --priority <P>
    - 仅处理指定优先级的任务项(P0/P1/P2/P3)
  • --agent <name>
    - 仅处理分配给指定Agent的任务项
错误处理
当任务项失败时:
❌ 执行失败:添加深色模式切换按钮(UNI-46)

错误:组件ThemeContext.tsx已存在
重试次数:1/3

操作:
- 标记为'failed'并添加错误信息
- 将Linear问题更新为'Canceled'
- 在Linear中添加包含错误详情的评论

工作循环将继续处理下一个任务项。
如需重试失败任务项,使用/workflow retry
当令牌预算不足时:
⚠️ 令牌预算不足(剩余8,500 PTS)

操作:优雅暂停工作循环
状态:已保存处理器状态

本次会话已处理任务项:8项
队列剩余任务项:2项

如需恢复:/workflow process
性能目标
指标目标
简单任务项执行时间< 5分钟
中等任务项执行时间< 15分钟
复杂任务项执行时间< 30分钟
队列吞吐量90分钟处理10-25项
成功率> 95%
每个任务项令牌使用量50-500 PTS

/workflow status

/workflow status

Shows detailed breakdown of current queue status, including what's currently processing, items in each state, and recent completions.
Aliases:
status
,
queue
,
progress
Process:
  1. Fetch queue statistics from work_queue table
  2. Get currently processing item (if any)
  3. Get recent completions (last 5)
  4. Calculate estimated time remaining
  5. Show breakdown by status
Implementation:
typescript
import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';

// Get statistics
const stats = await getQueueStatistics();

// Get currently processing
const processingItems = await getQueueItemsByStatus('processing', 1);
const currentItem = processingItems[0] || null;

// Get recent completions
const recentCompletions = await getQueueItemsByStatus('complete', 5);

// Display status
console.log('📊 Queue Status\n');
if (currentItem) {
  console.log('Currently processing:');
  console.log(`- ${currentItem.title} (${currentItem.linear_issue_identifier})`);
  console.log(`- Progress: Executing...`);
  console.log(`- Time elapsed: ${calculateElapsed(currentItem.updated_at)}\n`);
}

console.log('Queue breakdown:');
console.log(`├─ Pending:    ${stats.pending_count} items`);
console.log(`├─ Validating: ${stats.validating_count} items`);
console.log(`├─ Validated:  ${stats.validated_count} items (ready to process)`);
console.log(`├─ Processing: ${stats.processing_count} items`);
console.log(`├─ Complete:   ${stats.complete_count} items`);
console.log(`├─ Failed:     ${stats.failed_count} items`);
console.log(`└─ Archived:   ${stats.archived_count} items\n`);
Example Output:
User: /workflow status

Claude: 📊 Queue Status

Currently processing:
- Analyze R&D transactions for FY2023-24 (UNI-45)
- Progress: Applying Division 355 test (67% complete)
- Time elapsed: 12 minutes
- Agent: rnd-tax-specialist

Queue breakdown:
├─ Pending:    2 items (awaiting validation)
├─ Validating: 0 items
├─ Validated:  3 items (ready to process)
├─ Processing: 1 item  (currently executing)
├─ Complete:   25 items
├─ Failed:     1 item
└─ Archived:   22 items

Recently completed:
1. Fix navigation header padding (UNI-43) - 15 mins ago ✅
2. Update form validation (UNI-47) - 23 mins ago ✅
3. Refactor tax calculation (UNI-48) - 45 mins ago ✅
4. Add user authentication (UNI-49) - 1 hour ago ✅
5. Fix database migration (UNI-50) - 2 hours ago ✅

Session statistics:
- Items processed today: 8
- Success rate: 87.5%
- Average execution time: 9.3 minutes
- Total token usage: 24,500 PTS

Estimated time for validated items: ~45 minutes

Next in queue:
1. Add dark mode toggle (UNI-46) - P3 - Medium complexity
2. Fix copy icon overlap (UNI-51) - P2 - Simple
3. Create export functionality (UNI-52) - P1 - Complex

To process validated items: /workflow process
To see detailed statistics: /workflow stats
When to use:
  • Check what's currently happening
  • See queue backlog
  • Monitor progress during long processing sessions
  • Verify items were captured/validated
  • Check estimated completion time

显示当前队列状态的详细 breakdown,包括当前处理的任务项、各状态的任务项数和最近完成的任务。
别名
status
,
queue
,
progress
流程
  1. work_queue
    表获取队列统计数据
  2. 获取当前处理的任务项(若有)
  3. 获取最近完成的任务(最近5项)
  4. 计算预计剩余时间
  5. 按状态显示breakdown
实现代码
typescript
import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';

// 获取统计数据
const stats = await getQueueStatistics();

// 获取当前处理的任务项
const processingItems = await getQueueItemsByStatus('processing', 1);
const currentItem = processingItems[0] || null;

// 获取最近完成的任务
const recentCompletions = await getQueueItemsByStatus('complete', 5);

// 显示状态
console.log('📊 队列状态\
');
if (currentItem) {
  console.log('当前处理中:');
  console.log(`- ${currentItem.title} (${currentItem.linear_issue_identifier})`);
  console.log(`- 进度:执行中...`);
  console.log(`- 已耗时:${calculateElapsed(currentItem.updated_at)}\
`);
}

console.log('队列breakdown:');
console.log(`├─ 待处理:    ${stats.pending_count}`);
console.log(`├─ 验证中: ${stats.validating_count}`);
console.log(`├─ 已验证:  ${stats.validated_count}项(可处理)`);
console.log(`├─ 处理中: ${stats.processing_count}`);
console.log(`├─ 已完成:   ${stats.complete_count}`);
console.log(`├─ 失败:     ${stats.failed_count}`);
console.log(`└─ 已归档:   ${stats.archived_count}项\
`);
示例输出
用户:/workflow status

Claude:📊 队列状态

当前处理中:
- 分析2023-24财年研发交易(UNI-45)
- 进度:应用Division 355测试(完成67%)
- 已耗时:12分钟
- Agent:rnd-tax-specialist

队列breakdown:
├─ 待处理:    2项(等待验证)
├─ 验证中: 0项
├─ 已验证:  3项(可处理)
├─ 处理中: 1项 (正在执行)
├─ 已完成:   25项
├─ 失败:     1项
└─ 已归档:   22项

最近完成:
1. 修复导航栏内边距(UNI-43)- 15分钟前 ✅
2. 更新表单验证(UNI-47)- 23分钟前 ✅
3. 重构税收计算(UNI-48)- 45分钟前 ✅
4. 添加用户认证(UNI-49)- 1小时前 ✅
5. 修复数据库迁移(UNI-50)- 2小时前 ✅

会话统计:
- 今日已处理任务项:8项
- 成功率:87.5%
- 平均执行时间:9.3分钟
- 总令牌使用量:24,500 PTS

已验证任务项预计耗时:约45分钟

队列下一个任务:
1. 添加深色模式切换按钮(UNI-46)- P3 - 中等复杂度
2. 修复复制图标重叠(UNI-51)- P2 - 简单
3. 创建导出功能(UNI-52)- P1 - 复杂

如需处理已验证任务项:/workflow process
如需查看详细统计:/workflow stats
适用场景
  • 查看当前正在处理的任务
  • 查看队列积压情况
  • 在长处理会话中监控进度
  • 验证任务项是否已捕获/验证
  • 查看预计完成时间

/workflow stats

/workflow stats

Shows detailed performance statistics and metrics for the idea intake workflow system.
Aliases:
stats
,
metrics
,
performance
,
analytics
Process:
  1. Fetch queue statistics from database
  2. Calculate performance metrics (success rate, execution time, token usage)
  3. Break down by complexity, priority, agent
  4. Show validation statistics
  5. Display trends over time
Implementation:
typescript
import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';
import { calculateValidationStats } from '@/lib/queue/pm-validator';

// Get statistics
const stats = await getQueueStatistics();

// Get all validated items for PM stats
const validatedItems = await getQueueItemsByStatus('validated');
const pmStats = calculateValidationStats(validatedItems);

// Calculate success rate
const totalProcessed = stats.complete_count + stats.failed_count;
const successRate = totalProcessed > 0
  ? (stats.complete_count / totalProcessed * 100).toFixed(1)
  : 0;

// Display stats
console.log('📊 Workflow Statistics\n');
console.log('Overall Performance:');
console.log(`- Total items processed: ${totalProcessed}`);
console.log(`- Success rate: ${successRate}%`);
console.log(`- Average execution time: ${stats.avg_execution_time_seconds}s`);
console.log(`- Total token usage: ${stats.total_token_usage} PTS\n`);

console.log('By Complexity:');
console.log(`- Simple: ${pmStats.by_complexity.simple} items`);
console.log(`- Medium: ${pmStats.by_complexity.medium} items`);
console.log(`- Complex: ${pmStats.by_complexity.complex} items\n`);
Example Output:
User: /workflow stats

Claude: 📊 Workflow Statistics

Overall Performance:
- Total items processed: 127
- Success rate: 96.8% (123 succeeded, 4 failed)
- Average execution time: 8.3 minutes
- Total token usage: 45,230 PTS
- Average tokens per item: 356 PTS

Status Breakdown:
├─ Pending:    3 items (2.3%)
├─ Validating: 0 items (0%)
├─ Validated:  2 items (1.6%)
├─ Processing: 1 item  (0.8%)
├─ Complete:   119 items (93.7%)
├─ Failed:     2 items (1.6%)
└─ Archived:   115 items (90.6%)

By Complexity:
├─ Simple:   47 items (37.0%) - Avg time: 3.2 mins
├─ Medium:   58 items (45.7%) - Avg time: 9.1 mins
└─ Complex:  22 items (17.3%) - Avg time: 21.4 mins

By Priority:
├─ P0 (Critical): 2 items (1.6%)
├─ P1 (High):     28 items (22.0%)
├─ P2 (Medium):   74 items (58.3%)
└─ P3 (Low):      23 items (18.1%)

By Assigned Agent:
├─ general:                    67 items (52.8%)
├─ rnd-tax-specialist:         18 items (14.2%)
├─ deduction-optimizer:        12 items (9.4%)
├─ xero-auditor:               11 items (8.7%)
├─ loss-recovery-agent:        8 items (6.3%)
├─ trust-distribution-analyzer: 5 items (3.9%)
└─ Other specialists:          6 items (4.7%)

Validation Statistics:
- Average feasibility score: 82/100
- Average confidence: 78/100
- Duplicate detection rate: 12% (15 duplicates found)

Execution Strategy:
- Direct execution: 47 items (37.0%)
- Requires planning: 58 items (45.7%)
- Specialist review: 22 items (17.3%)

Recent Trends (Last 24 Hours):
- Items captured: 15
- Items validated: 12
- Items processed: 10
- Success rate: 100%
- Average time per item: 7.2 minutes

Time Distribution:
- 0-5 minutes:   47 items (37.0%)
- 5-10 minutes:  38 items (29.9%)
- 10-15 minutes: 20 items (15.7%)
- 15-30 minutes: 18 items (14.2%)
- 30+ minutes:   4 items (3.1%)

Token Distribution:
- 0-100 PTS:    52 items (40.9%)
- 100-500 PTS:  61 items (48.0%)
- 500-1000 PTS: 12 items (9.4%)
- 1000+ PTS:    2 items (1.6%)

Failed Items Analysis:
- Database connection: 1 item
- User canceled: 1 item
- Total failed: 2 items (1.6%)

Top Performing Categories:
1. UI/Frontend changes: 98% success rate (3.8 min avg)
2. Tax analysis: 95% success rate (18.2 min avg)
3. Database changes: 87% success rate (12.4 min avg)

Recommendations:
✅ High capture rate - system is being used effectively
✅ Excellent success rate (96.8%) - execution quality is strong
⚠️ 12% duplicate rate - consider improving capture descriptions
✅ Token usage is efficient (356 PTS avg per item)
When to use:
  • Periodic performance review
  • Understanding system usage patterns
  • Identifying bottlenecks or issues
  • Reporting metrics to stakeholders
  • Optimizing workflow processes

显示想法收集工作流系统的详细性能统计和指标。
别名
stats
,
metrics
,
performance
,
analytics
流程
  1. 从数据库获取队列统计数据
  2. 计算性能指标(成功率、执行时间、令牌使用量)
  3. 按复杂度、优先级、Agent细分
  4. 显示验证统计数据
  5. 显示时间趋势
实现代码
typescript
import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';
import { calculateValidationStats } from '@/lib/queue/pm-validator';

// 获取统计数据
const stats = await getQueueStatistics();

// 获取所有已验证任务项用于PM统计
const validatedItems = await getQueueItemsByStatus('validated');
const pmStats = calculateValidationStats(validatedItems);

// 计算成功率
const totalProcessed = stats.complete_count + stats.failed_count;
const successRate = totalProcessed > 0
  ? (stats.complete_count / totalProcessed * 100).toFixed(1)
  : 0;

// 显示统计数据
console.log('📊 工作流统计\
');
console.log('整体性能:');
console.log(`- 已处理任务项总数:${totalProcessed}`);
console.log(`- 成功率:${successRate}%`);
console.log(`- 平均执行时间:${stats.avg_execution_time_seconds}`);
console.log(`- 总令牌使用量:${stats.total_token_usage} PTS\
`);

console.log('按复杂度划分:');
console.log(`- 简单:${pmStats.by_complexity.simple}`);
console.log(`- 中等:${pmStats.by_complexity.medium}`);
console.log(`- 复杂:${pmStats.by_complexity.complex}项\
`);
示例输出
用户:/workflow stats

Claude:📊 工作流统计

整体性能:
- 已处理任务项总数:127
- 成功率:96.8%(123项成功,4项失败)
- 平均执行时间:8.3分钟
- 总令牌使用量:45,230 PTS
- 每个任务项平均令牌使用量:356 PTS

状态Breakdown:
├─ 待处理:    3项(2.3%)
├─ 验证中: 0项(0%)
├─ 已验证:  2项(1.6%)
├─ 处理中: 1项 (0.8%)
├─ 已完成:   119项(93.7%)
├─ 失败:     2项(1.6%)
└─ 已归档:   115项(90.6%)

按复杂度划分:
├─ 简单:   47项(37.0%)- 平均耗时:3.2分钟
├─ 中等:   58项(45.7%)- 平均耗时:9.1分钟
└─ 复杂:  22项(17.3%)- 平均耗时:21.4分钟

按优先级划分:
├─ P0(关键):2项(1.6%)
├─ P1(高):     28项(22.0%)
├─ P2(中等):   74项(58.3%)
└─ P3(低):      23项(18.1%)

按分配Agent划分:
├─ general:                    67项(52.8%)
├─ rnd-tax-specialist:         18项(14.2%)
├─ deduction-optimizer:        12项(9.4%)
├─ xero-auditor:               11项(8.7%)
├─ loss-recovery-agent:        8项(6.3%)
├─ trust-distribution-analyzer: 5项(3.9%)
└─ 其他专家:          6项(4.7%)

验证统计:
- 平均可行性得分:82/100
- 平均置信度:78/100
- 重复项检测率:12%(已发现15个重复项)

执行策略:
- 直接执行:47项(37.0%)
- 需要规划:58项(45.7%)
- 专家审核:22项(17.3%)

近期趋势(过去24小时):
- 捕获想法数:15
- 验证任务项数:12
- 处理任务项数:10
- 成功率:100%
- 每个任务项平均耗时:7.2分钟

时间分布:
- 0-5分钟:   47项(37.0%)
- 5-10分钟:  38项(29.9%)
- 10-15分钟: 20项(15.7%)
- 15-30分钟: 18项(14.2%)
- 30+分钟:   4项(3.1%)

令牌分布:
- 0-100 PTS:    52项(40.9%)
- 100-500 PTS:  61项(48.0%)
- 500-1000 PTS: 12项(9.4%)
- 1000+ PTS:    2项(1.6%)

失败任务项分析:
- 数据库连接:1项
- 用户取消:1项
- 总失败数:2项(1.6%)

表现最佳类别:
1. UI/前端变更:98%成功率(平均3.8分钟)
2. 税务分析:95%成功率(平均18.2分钟)
3. 数据库变更:87%成功率(平均12.4分钟)

建议:
✅ 捕获率高 - 系统使用效率良好
✅ 优秀的成功率(96.8%)- 执行质量高
⚠️ 12%的重复率 - 考虑改进捕获描述
✅ 令牌使用高效(每个任务项平均356 PTS)
适用场景
  • 定期性能审核
  • 了解系统使用模式
  • 识别瓶颈或问题
  • 向利益相关者报告指标
  • 优化工作流流程

Implementation Notes

实现说明

Architecture Overview

架构概览

┌─────────────────────────────────────────────────────────────┐
│                    /workflow Command                         │
│                    (Orchestrator Skill)                      │
└───────────────┬─────────────────────────────────────────────┘
                ├─ /workflow capture
                │  └─ Uses: lib/queue/work-queue-manager.ts
                │     └─ Function: addToQueue()
                ├─ /workflow validate
                │  └─ Uses: lib/queue/pm-validator.ts
                │     └─ Function: validateQueueItem()
                │     └─ Function: checkForDuplicates()
                │     └─ Uses: lib/linear/api-client.ts
                ├─ /workflow process
                │  └─ Uses: lib/queue/work-queue-manager.ts
                │     └─ Function: getNextValidatedItem()
                │     └─ Function: markAsProcessing()
                │     └─ Function: markAsComplete()
                │     └─ Function: markAsFailed()
                │     └─ Uses: lib/linear/api-client.ts
                ├─ /workflow status
                │  └─ Uses: lib/queue/work-queue-manager.ts
                │     └─ Function: getQueueStatistics()
                │     └─ Function: getQueueItemsByStatus()
                └─ /workflow stats
                   └─ Uses: lib/queue/work-queue-manager.ts
                      └─ Function: getQueueStatistics()
                      └─ Uses: lib/queue/pm-validator.ts
                         └─ Function: calculateValidationStats()
┌─────────────────────────────────────────────────────────────┐
│                    /workflow 命令                         │
│                   (编排器技能)                      │
└───────────────┬─────────────────────────────────────────────┘
                ├─ /workflow capture
                │  └─ 使用:lib/queue/work-queue-manager.ts
                │     └─ 函数:addToQueue()
                ├─ /workflow validate
                │  └─ 使用:lib/queue/pm-validator.ts
                │     └─ 函数:validateQueueItem()
                │     └─ 函数:checkForDuplicates()
                │     └─ 使用:lib/linear/api-client.ts
                ├─ /workflow process
                │  └─ 使用:lib/queue/work-queue-manager.ts
                │     └─ 函数:getNextValidatedItem()
                │     └─ 函数:markAsProcessing()
                │     └─ 函数:markAsComplete()
                │     └─ 函数:markAsFailed()
                │     └─ 使用:lib/linear/api-client.ts
                ├─ /workflow status
                │  └─ 使用:lib/queue/work-queue-manager.ts
                │     └─ 函数:getQueueStatistics()
                │     └─ 函数:getQueueItemsByStatus()
                └─ /workflow stats
                   └─ 使用:lib/queue/work-queue-manager.ts
                      └─ 函数:getQueueStatistics()
                      └─ 使用:lib/queue/pm-validator.ts
                         └─ 函数:calculateValidationStats()

Key Dependencies

关键依赖

Database (Supabase):
  • Table:
    work_queue
    (created by migration
    20260129_create_work_queue.sql
    )
  • Service Client:
    lib/supabase/server.ts
  • Functions:
    • get_next_pending_queue_item()
      - Row-level locking with SKIP LOCKED
    • get_next_validated_queue_item()
      - Priority-sorted with locking
    • get_queue_statistics()
      - Aggregated statistics
Queue Manager (
lib/queue/work-queue-manager.ts
):
  • addToQueue()
    - Add new items
  • getNextPendingItem()
    - Fetch for validation
  • getNextValidatedItem()
    - Fetch for execution
  • markAsValidating()
    ,
    markAsValidated()
    ,
    markAsProcessing()
    ,
    markAsComplete()
    ,
    markAsFailed()
    - Status transitions
  • archiveQueueItem()
    - Archive completed items
  • updateLinearMetadata()
    - Store Linear issue references
  • getQueueStatistics()
    - Performance metrics
  • getQueueItemsByStatus()
    - Filter by status
  • timeoutStuckItems()
    - Safety mechanism for stuck items
PM Validator (
lib/queue/pm-validator.ts
):
  • validateQueueItem()
    - Main validation pipeline
  • assessFeasibility()
    - Feasibility scoring (0-100)
  • assessComplexity()
    - Complexity detection (simple/medium/complex)
  • assignPriority()
    - Priority assignment (P0/P1/P2/P3)
  • determineAssignedAgent()
    - Agent routing logic
  • determineExecutionStrategy()
    - Execution strategy (direct/planning/review)
  • checkForDuplicates()
    - Linear duplicate detection
  • calculateValidationStats()
    - Validation metrics
Linear Integration (
lib/linear/api-client.ts
):
  • createIssue()
    - Create Linear issue from queue item
  • updateIssue()
    - Update issue status
  • searchIssues()
    - Search for duplicates
  • addComment()
    - Add comments to issues
  • getStateIdByType()
    - Get workflow state IDs
Linear Utilities (
lib/linear/graphql-queries.ts
):
  • buildIssueFromQueue()
    - Convert queue item to Linear issue format
  • extractSearchKeywords()
    - Extract keywords for duplicate search
  • findPotentialDuplicates()
    - Similarity matching
  • mapQueueStatusToLinearState()
    - Status mapping
数据库(Supabase)
  • 表:
    work_queue
    (由迁移
    20260129_create_work_queue.sql
    创建)
  • 服务客户端:
    lib/supabase/server.ts
  • 函数:
    • get_next_pending_queue_item()
      - 行级锁并跳过已锁定行
    • get_next_validated_queue_item()
      - 按优先级排序并加锁
    • get_queue_statistics()
      - 聚合统计数据
队列管理器
lib/queue/work-queue-manager.ts
):
  • addToQueue()
    - 添加新任务项
  • getNextPendingItem()
    - 获取待验证任务项
  • getNextValidatedItem()
    - 获取待执行任务项
  • markAsValidating()
    ,
    markAsValidated()
    ,
    markAsProcessing()
    ,
    markAsComplete()
    ,
    markAsFailed()
    - 状态转换
  • archiveQueueItem()
    - 归档已完成任务项
  • updateLinearMetadata()
    - 存储Linear问题引用
  • getQueueStatistics()
    - 性能指标
  • getQueueItemsByStatus()
    - 按状态筛选
  • timeoutStuckItems()
    - 处理卡住任务项的安全机制
PM验证器
lib/queue/pm-validator.ts
):
  • validateQueueItem()
    - 主验证流水线
  • assessFeasibility()
    - 可行性评分(0-100)
  • assessComplexity()
    - 复杂度检测(简单/中等/复杂)
  • assignPriority()
    - 优先级分配(P0/P1/P2/P3)
  • determineAssignedAgent()
    - Agent路由逻辑
  • determineExecutionStrategy()
    - 执行策略(直接/规划/审核)
  • checkForDuplicates()
    - Linear重复项检测
  • calculateValidationStats()
    - 验证指标
Linear集成
lib/linear/api-client.ts
):
  • createIssue()
    - 从队列任务项创建Linear问题
  • updateIssue()
    - 更新问题状态
  • searchIssues()
    - 搜索重复项
  • addComment()
    - 向问题添加评论
  • getStateIdByType()
    - 获取工作流状态ID
Linear工具
lib/linear/graphql-queries.ts
):
  • buildIssueFromQueue()
    - 将队列任务项转换为Linear问题格式
  • extractSearchKeywords()
    - 提取重复项搜索关键词
  • findPotentialDuplicates()
    - 相似度匹配
  • mapQueueStatusToLinearState()
    - 状态映射

Data Flow

数据流

Capture Flow:
User message
  → Parse and extract ideas
  → Auto-detect type
  → Generate title
  → addToQueue() → Supabase work_queue
  → Return confirmation
Validation Flow:
Pending items
  → getQueueItemsByStatus('pending')
  → For each item:
     → markAsValidating()
     → validateQueueItem()
       → assessFeasibility()
       → assessComplexity()
       → checkForDuplicates() → Linear API
       → assignPriority()
       → determineAssignedAgent()
       → determineExecutionStrategy()
     → markAsValidated()
     → Create Linear issue if not duplicate
  → Return summary
Processing Flow:
Validated items
  → getNextValidatedItem() (with row locking)
  → markAsProcessing()
  → Create Linear issue if needed
  → Route based on complexity:
     → Simple: executeSimpleTask()
     → Medium: spawnPlannerSubAgent() → spawnExecutorSubAgent()
     → Complex: spawnPlannerSubAgent() → askUserForApproval() → spawnExecutorSubAgent()
  → markAsComplete() or markAsFailed()
  → updateIssue() → Linear API
  → archiveQueueItem() (if complete)
  → Repeat
捕获流程
用户消息
  → 解析并提取想法
  → 自动检测类型
  → 生成标题
  → addToQueue() → Supabase work_queue
  → 返回确认信息
验证流程
待处理任务项
  → getQueueItemsByStatus('pending')
  → 对每个任务项:
     → markAsValidating()
     → validateQueueItem()
       → assessFeasibility()
       → assessComplexity()
       → checkForDuplicates() → Linear API
       → assignPriority()
       → determineAssignedAgent()
       → determineExecutionStrategy()
     → markAsValidated()
     → 若不是重复项则创建Linear问题
  → 返回摘要
处理流程
已验证任务项
  → getNextValidatedItem()(带行锁)
  → markAsProcessing()
  → 若需要则创建Linear问题
  → 根据复杂度路由:
     → 简单:executeSimpleTask()
     → 中等:spawnPlannerSubAgent() → spawnExecutorSubAgent()
     → 复杂:spawnPlannerSubAgent() → askUserForApproval() → spawnExecutorSubAgent()
  → markAsComplete() 或 markAsFailed()
  → updateIssue() → Linear API
  → archiveQueueItem()(若完成)
  → 重复

Error Handling Patterns

错误处理模式

Database Errors:
typescript
try {
  const item = await addToQueue({ ... });
  return { status: 'success', item };
} catch (error) {
  console.error('Failed to add item to queue:', error);
  return {
    status: 'error',
    error: error.message,
    suggestions: [
      'Check SUPABASE_SERVICE_ROLE_KEY is configured',
      'Verify Supabase project is running',
      'Run migration: supabase migration up'
    ]
  };
}
Linear API Errors:
typescript
try {
  const duplicateCheck = await checkForDuplicates(item);
} catch (error) {
  console.warn('Duplicate check failed, continuing without:', error);
  // Graceful degradation - assume not duplicate
  duplicateCheck = { isDuplicate: false };
}
Execution Failures:
typescript
try {
  const result = await executeQueueItem(item);
  await markAsComplete(item.id, result);
} catch (error) {
  console.error(`Execution failed for ${item.id}:`, error);
  await markAsFailed(item.id, error.message);

  // Update Linear
  await updateIssue(item.linear_issue_id, {
    stateId: await getStateIdByType('canceled'),
  });
  await addComment(item.linear_issue_id,
    `Execution failed: ${error.message}\n\nMarked as failed in queue.`
  );

  // Continue to next item (don't stop loop)
  continue;
}
Token Exhaustion:
typescript
const estimatedRemainingTokens = calculateRemainingTokens();

if (estimatedRemainingTokens < MIN_TOKEN_THRESHOLD) {
  console.warn('Token budget low, stopping gracefully');

  await saveProcessorState({
    lastProcessedId: item.id,
    itemsProcessed: count,
    timestamp: new Date().toISOString(),
  });

  return {
    status: 'paused',
    reason: 'token_budget_low',
    itemsProcessed: count,
    message: 'Work loop paused due to low token budget. Restart to continue.',
  };
}
数据库错误
typescript
try {
  const item = await addToQueue({ ... });
  return { status: 'success', item };
} catch (error) {
  console.error('添加任务项到队列失败:', error);
  return {
    status: 'error',
    error: error.message,
    suggestions: [
      '检查SUPABASE_SERVICE_ROLE_KEY是否配置正确',
      '验证Supabase项目是否正常运行',
      '执行迁移:supabase migration up'
    ]
  };
}
Linear API错误
typescript
try {
  const duplicateCheck = await checkForDuplicates(item);
} catch (error) {
  console.warn('重复项检查失败,将继续执行:', error);
  // 优雅降级 - 假设不是重复项
  duplicateCheck = { isDuplicate: false };
}
执行失败
typescript
try {
  const result = await executeQueueItem(item);
  await markAsComplete(item.id, result);
} catch (error) {
  console.error(`任务项${item.id}执行失败:`, error);
  await markAsFailed(item.id, error.message);

  // 更新Linear
  await updateIssue(item.linear_issue_id, {
    stateId: await getStateIdByType('canceled'),
  });
  await addComment(item.linear_issue_id,
    `执行失败:${error.message}\
\
已在队列中标记为失败。`
  );

  // 继续处理下一个任务项(不停止循环)
  continue;
}
令牌耗尽
typescript
const estimatedRemainingTokens = calculateRemainingTokens();

if (estimatedRemainingTokens < MIN_TOKEN_THRESHOLD) {
  console.warn('令牌预算不足,将优雅停止');

  await saveProcessorState({
    lastProcessedId: item.id,
    itemsProcessed: count,
    timestamp: new Date().toISOString(),
  });

  return {
    status: 'paused',
    reason: 'token_budget_low',
    itemsProcessed: count,
    message: '因令牌预算不足,工作循环已暂停。重启可继续。',
  };
}

Configuration

配置

Environment Variables:
bash
undefined
环境变量
bash
undefined

Database (Required)

数据库(必填)

SUPABASE_URL=https://your-project.supabase.co SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_URL=https://your-project.supabase.co SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Linear Integration (Required for validation/processing)

Linear集成(验证/处理必填)

LINEAR_API_KEY=lin_api_... LINEAR_TEAM_ID=UNI LINEAR_PROJECT_ID=project-id-optional
LINEAR_API_KEY=lin_api_... LINEAR_TEAM_ID=UNI LINEAR_PROJECT_ID=project-id-optional

Queue Configuration (Optional)

队列配置(可选)

QUEUE_BATCH_SIZE=10 # Max items per validation/processing session QUEUE_POLL_INTERVAL_MS=5000 # How often to check for new items QUEUE_MAX_RETRIES=3 # Max retries on failure QUEUE_TIMEOUT_HOURS=2 # Mark as failed after N hours in 'processing' MIN_TOKEN_THRESHOLD=10000 # Stop processing if tokens < this

**Rate Limiting**:
- **Linear API**: 4-second delay between calls (follows Gemini pattern)
- **Supabase**: No rate limiting (self-hosted or generous limits)
- **Token Budget**: Stop if < 10,000 PTS remaining
QUEUE_BATCH_SIZE=10 # 每次验证/处理会话的最大任务项数 QUEUE_POLL_INTERVAL_MS=5000 # 检查新任务项的间隔时间 QUEUE_MAX_RETRIES=3 # 失败后的最大重试次数 QUEUE_TIMEOUT_HOURS=2 # 处理中状态超过N小时则标记为失败 MIN_TOKEN_THRESHOLD=10000 # 令牌少于此值则停止处理

**速率限制**:
- **Linear API**:调用间隔4秒延迟(遵循Gemini模式)
- **Supabase**:无速率限制(自托管或限额宽松)
- **令牌预算**:剩余令牌<10,000 PTS时停止处理

Security Considerations

安全考虑

Database Access:
  • Uses
    SUPABASE_SERVICE_ROLE_KEY
    (bypasses RLS)
  • No user authentication required (internal tool)
  • Queue items are not user-specific (shared queue)
Sensitive Data Handling:
  • Capture preserves user input verbatim (including sensitive data)
  • Warn user if sensitive information detected
  • Linear issues created in private team workspace
  • Execution logs may contain sensitive context
Prohibited Actions (never executed, even if in queue):
  • Deleting production data
  • Modifying Xero data (read-only)
  • Submitting ATO filings
  • Committing secrets to git
  • Force-pushing to main branch
数据库访问
  • 使用
    SUPABASE_SERVICE_ROLE_KEY
    (绕过RLS)
  • 无需用户认证(内部工具)
  • 队列任务项不区分用户(共享队列)
敏感数据处理
  • 捕获时保留用户输入原文(包括敏感数据)
  • 若检测到敏感信息则警告用户
  • Linear问题创建在私有团队工作区
  • 执行日志可能包含敏感上下文
禁止操作(即使在队列中也绝不会执行):
  • 删除生产数据
  • 修改Xero数据(仅只读)
  • 提交ATO申报
  • 向git提交机密信息
  • 强制推送到主分支

Performance Optimization

性能优化

Database Queries:
  • Use row-level locking (
    FOR UPDATE SKIP LOCKED
    ) to prevent race conditions
  • Index on
    status
    column for fast filtering
  • Index on
    created_at
    for queue ordering
  • Index on
    priority
    for priority-based processing
Caching:
  • Cache queue statistics for 60 seconds
  • Cache Linear team/project IDs for session
  • No caching of queue items (always fetch fresh)
Batching:
  • Validate items in batches (default: all pending)
  • Process items one at a time (sequential for isolation)
  • Rate limit Linear API calls (4-second delay)
Token Management:
  • Estimate tokens per item (50-500 PTS)
  • Stop if < 10,000 PTS remaining
  • Save processor state for resumption

数据库查询
  • 使用行级锁(
    FOR UPDATE SKIP LOCKED
    )防止竞态条件
  • status
    列创建索引以加快筛选
  • created_at
    列创建索引以优化队列排序
  • priority
    列创建索引以支持基于优先级的处理
缓存
  • 缓存队列统计数据60秒
  • 缓存Linear团队/项目ID会话
  • 不缓存队列任务项(始终实时获取)
批处理
  • 批量验证任务项(默认:所有待处理项)
  • 逐个处理任务项(顺序执行以隔离上下文)
  • Linear API调用速率限制(4秒延迟)
令牌管理
  • 预估每个任务项的令牌使用量(50-500 PTS)
  • 剩余令牌<10,000 PTS时停止
  • 保存处理器状态以便恢复

Testing Checklist

测试清单

Capture Tests

捕获测试

  • Can capture single idea from user message
  • Can capture explicit text with
    --text
    option
  • Auto-detects correct type (feature/bug/improvement/task/client_request)
  • Generates concise title (< 80 chars)
  • Groups related ideas correctly
  • Separates unrelated ideas correctly
  • Handles database connection errors gracefully
  • Warns user about sensitive information
  • Returns correct queue position
  • Stores full context in payload
  • 可从用户消息捕获单个想法
  • 可使用
    --text
    选项捕获显式文本
  • 自动检测正确类型(feature/bug/improvement/task/client_request)
  • 生成简洁标题(<80字符)
  • 正确分组相关想法
  • 正确拆分不相关想法
  • 优雅处理数据库连接错误
  • 警告用户敏感信息
  • 返回正确队列位置
  • 在payload中存储完整上下文

Validation Tests

验证测试

  • Fetches all pending items
  • Assesses feasibility correctly (0-100 score)
  • Detects complexity (simple/medium/complex)
  • Assigns priority (P0/P1/P2/P3)
  • Routes to correct agent
  • Determines execution strategy correctly
  • Checks for duplicates in Linear
  • Creates Linear issues if not duplicate
  • Merges context into existing issues if duplicate
  • Handles Linear API errors gracefully
  • Marks items as validated with validation_result
  • Returns summary with all validated items
  • 获取所有待处理任务项
  • 正确评估可行性(0-100分)
  • 检测复杂度(简单/中等/复杂)
  • 分配正确优先级(P0/P1/P2/P3)
  • 路由至正确Agent
  • 正确确定执行策略
  • 在Linear中检查重复项
  • 若不是重复项则创建Linear问题
  • 若为重复项则将上下文合并至现有问题
  • 优雅处理Linear API错误
  • 将任务项标记为已验证并保存验证结果
  • 返回包含所有已验证任务项的摘要

Processing Tests

处理测试

  • Fetches validated items with row locking
  • Processes items in priority order
  • Executes simple items directly
  • Plans and executes medium items
  • Asks user approval for complex items
  • Spawns fresh sub-agents per item
  • Updates Linear status as work progresses
  • Captures before/after screenshots
  • Marks items as complete with metadata
  • Marks items as failed on error
  • Archives completed items
  • Continues on individual item failure
  • Stops when queue empty
  • Stops when token budget low
  • Respects rate limits (4-second delay)
  • 获取带行锁的已验证任务项
  • 按优先级顺序处理任务项
  • 直接执行简单任务项
  • 规划并执行中等任务项
  • 复杂任务项需用户批准
  • 为每个任务项生成全新子Agent
  • 随着任务推进更新Linear状态
  • 捕获前后截图
  • 标记任务项为完成并保存元数据
  • 错误时标记任务项为失败
  • 归档已完成任务项
  • 单个任务项失败时继续处理
  • 队列为空时停止
  • 令牌预算不足时停止
  • 遵守速率限制(4秒延迟)

Status Tests

状态测试

  • Shows currently processing item
  • Shows queue breakdown by status
  • Shows recent completions
  • Calculates estimated time remaining
  • Displays next items in queue
  • Handles empty queue correctly
  • 显示当前处理中的任务项
  • 按状态显示队列breakdown
  • 显示最近完成的任务
  • 计算预计剩余时间
  • 显示队列中的下一个任务项
  • 正确处理空队列

Stats Tests

统计测试

  • Calculates overall performance metrics
  • Breaks down by complexity
  • Breaks down by priority
  • Breaks down by agent
  • Shows validation statistics
  • Shows execution strategy distribution
  • Shows time distribution
  • Shows token distribution
  • Shows failed items analysis
  • Provides recommendations

  • 计算整体性能指标
  • 按复杂度拆分
  • 按优先级拆分
  • 按Agent拆分
  • 显示验证统计
  • 显示执行策略分布
  • 显示时间分布
  • 显示令牌分布
  • 显示失败任务项分析
  • 提供建议

Troubleshooting

故障排除

Common Issues

常见问题

Issue: "Failed to add item to queue: Database connection failed"
Solution:
  1. Check
    SUPABASE_URL
    and
    SUPABASE_SERVICE_ROLE_KEY
    are configured
  2. Verify Supabase project is running
  3. Run migration:
    supabase migration up
  4. Check network connectivity

Issue: "Duplicate check failed, continuing without"
Solution:
  1. Check
    LINEAR_API_KEY
    is configured
  2. Verify Linear team/project IDs are correct
  3. Check Linear API rate limits
  4. This is a warning, not an error - validation continues

Issue: "Execution failed: Component already exists"
Solution:
  1. Item marked as failed, work loop continues
  2. Review error message in Linear issue comment
  3. Fix issue manually or adjust queue item
  4. Use
    /workflow retry
    to retry failed items

Issue: "Token budget low, stopping gracefully"
Solution:
  1. This is expected behaviour, not an error
  2. Processor state saved automatically
  3. Use
    /workflow process
    to resume
  4. Consider processing fewer items per session with
    --limit

Issue: "No items in queue" when expecting items
Solution:
  1. Check status with
    /workflow status
  2. Items may be in different status (pending, validating, processing)
  3. Use
    /workflow validate
    to validate pending items first
  4. Check if items were archived

Issue: Items stuck in 'processing' status
Solution:
  1. Safety mechanism will timeout after 2 hours
  2. Run
    timeoutStuckItems()
    function manually
  3. Check for crashed/interrupted processor
  4. Manually mark items as 'validated' to retry

问题:"添加任务项到队列失败:数据库连接失败"
解决方案
  1. 检查
    SUPABASE_URL
    SUPABASE_SERVICE_ROLE_KEY
    是否配置正确
  2. 验证Supabase项目是否正常运行
  3. 执行迁移:
    supabase migration up
  4. 检查网络连接

问题:"重复项检查失败,将继续执行"
解决方案
  1. 检查
    LINEAR_API_KEY
    是否配置正确
  2. 验证Linear团队/项目ID是否正确
  3. 检查Linear API速率限制
  4. 这是警告而非错误 - 验证将继续

问题:"执行失败:组件已存在"
解决方案
  1. 任务项已标记为失败,工作循环将继续
  2. 查看Linear问题评论中的错误信息
  3. 手动修复问题或调整队列任务项
  4. 使用
    /workflow retry
    重试失败任务项

问题:"令牌预算不足,将优雅停止"
解决方案
  1. 这是预期行为而非错误
  2. 处理器状态已自动保存
  3. 使用
    /workflow process
    恢复
  4. 考虑使用
    --limit
    减少每次会话处理的任务项数

问题:预期有任务项但显示"队列为空"
解决方案
  1. 使用
    /workflow status
    查看状态
  2. 任务项可能处于其他状态(待处理、验证中、处理中)
  3. 先使用
    /workflow validate
    验证待处理任务项
  4. 检查任务项是否已归档

问题:任务项卡在'processing'状态
解决方案
  1. 安全机制将在2小时后超时
  2. 手动运行
    timeoutStuckItems()
    函数
  3. 检查处理器是否崩溃/中断
  4. 手动将任务项标记为'validated'以重试

Advanced Usage

高级用法

Custom Agent Routing

自定义Agent路由

Override automatic agent assignment:
typescript
import { updateQueueItem } from '@/lib/queue/work-queue-manager';

// Force specific agent
await updateQueueItem(itemId, {
  assigned_agent: 'rnd-tax-specialist',
  priority: 'P0',
});
覆盖自动Agent分配:
typescript
import { updateQueueItem } from '@/lib/queue/work-queue-manager';

// 强制分配给特定Agent
await updateQueueItem(itemId, {
  assigned_agent: 'rnd-tax-specialist',
  priority: 'P0',
});

Retry Failed Items

重试失败任务项

typescript
import { getQueueItemsByStatus, updateQueueItem } from '@/lib/queue/work-queue-manager';

// Get all failed items
const failedItems = await getQueueItemsByStatus('failed');

// Reset to validated for retry
for (const item of failedItems) {
  await updateQueueItem(item.id, {
    status: 'validated',
    error_message: null,
    error_count: 0,
  });
}
typescript
import { getQueueItemsByStatus, updateQueueItem } from '@/lib/queue/work-queue-manager';

// 获取所有失败任务项
const failedItems = await getQueueItemsByStatus('failed');

// 重置为已验证状态以重试
for (const item of failedItems) {
  await updateQueueItem(item.id, {
    status: 'validated',
    error_message: null,
    error_count: 0,
  });
}

Bulk Archive Old Items

批量归档旧任务项

typescript
import { archiveOldFailedItems } from '@/lib/queue/work-queue-manager';

// Archive failed items older than 30 days
const archivedCount = await archiveOldFailedItems(30);
console.log(`Archived ${archivedCount} old failed items`);
typescript
import { archiveOldFailedItems } from '@/lib/queue/work-queue-manager';

// 归档30天以上的失败任务项
const archivedCount = await archiveOldFailedItems(30);
console.log(`已归档${archivedCount}个旧失败任务项`);

Manual Timeout Cleanup

手动超时清理

typescript
import { timeoutStuckItems } from '@/lib/queue/work-queue-manager';

// Timeout items stuck in 'processing' for > 2 hours
const timedOutCount = await timeoutStuckItems(2);
console.log(`Timed out ${timedOutCount} stuck items`);

typescript
import { timeoutStuckItems } from '@/lib/queue/work-queue-manager';

// 将处理中状态超过2小时的任务项超时
const timedOutCount = await timeoutStuckItems(2);
console.log(`已超时${timedOutCount}个卡住的任务项`);

Integration with Other Skills

与其他技能的集成

Xero Integration

Xero集成

Queue items can trigger Xero data fetching:
typescript
// Example: R&D analysis queue item
const item = await addToQueue({
  title: 'Analyze R&D transactions for FY2023-24',
  description: 'Review all Xero transactions for R&D eligibility',
  queue_item_type: 'feature',
  payload: {
    financial_year: 'FY2023-24',
    start_date: '2023-07-01',
    end_date: '2024-06-30',
    analysis_type: 'rnd',
  },
});

// Processing will route to rnd-tax-specialist
// Agent will fetch Xero data automatically
队列任务项可触发Xero数据获取:
typescript
// 示例:R&D分析队列任务项
const item = await addToQueue({
  title: '分析2023-24财年研发交易',
  description: '审核所有Xero交易的R&D资格',
  queue_item_type: 'feature',
  payload: {
    financial_year: 'FY2023-24',
    start_date: '2023-07-01',
    end_date: '2024-06-30',
    analysis_type: 'rnd',
  },
});

// 处理将路由至rnd-tax-specialist
// Agent将自动获取Xero数据

Tax Law Research

税务法规研究

Complex tax questions can be queued:
typescript
const item = await addToQueue({
  title: 'Research Division 7A loan repayment requirements',
  description: 'Client has $150K shareholder loan, need repayment schedule',
  queue_item_type: 'client_request',
  payload: {
    loan_amount: 150000,
    client_id: 'client-123',
    legislation: 'Division 7A ITAA 1936',
  },
});

// Processing will route to loss-recovery-agent
// Agent will research legislation and calculate repayments
复杂税务问题可加入队列:
typescript
const item = await addToQueue({
  title: '研究Division 7A贷款还款要求',
  description: '客户有15万澳元股东贷款,需要还款计划',
  queue_item_type: 'client_request',
  payload: {
    loan_amount: 150000,
    client_id: 'client-123',
    legislation: 'Division 7A ITAA 1936',
  },
});

// 处理将</think_never_used_51bce0c785ca2f68081bfa7d91973934>{</think_never_used_51bce0c785ca2f68081bfa7d91973934>
  "description": "自主想法收集工作流系统的统一命令界面",
  "content": "# 想法收集工作流 - 统一界面

Linear Workflow Integration

用途

Queue items automatically sync with Linear:
  • Capture: Creates placeholder for future Linear issue
  • Validation: Creates Linear issue if not duplicate
  • Processing: Updates Linear issue status as work progresses
  • Completion: Marks Linear issue as complete, adds final comment
Matt Maher的"do-work"自主想法收集模式的单一命令界面。无需记住不同技能的多个命令,即可统一访问想法捕获、验证和处理操作。
该技能将三个子技能编排为连贯的工作流:
  • idea-queue-capture - 快速想法捕获
  • Senior PM Enhanced(验证) - 可行性评估与路由
  • work-queue-processor - 自主执行

Reporting Integration

设计理念

Queue data can feed into reports:
typescript
import { getQueueStatistics } from '@/lib/queue/work-queue-manager';
import { calculateValidationStats } from '@/lib/queue/pm-validator';

// Generate weekly report
const stats = await getQueueStatistics();
const validationStats = calculateValidationStats(validatedItems);

const report = {
  week: getCurrentWeek(),
  items_processed: stats.complete_count,
  success_rate: (stats.complete_count / (stats.complete_count + stats.failed_count) * 100),
  avg_execution_time: stats.avg_execution_time_seconds,
  by_complexity: validationStats.by_complexity,
  by_priority: validationStats.by_priority,
};

// Save to reports table or send to stakeholders

一令通管:使用
/workflow
命令搭配智能子命令,处理从想法捕获到执行和归档的全生命周期。
上下文隔离:每个阶段在独立上下文中运行,防止污染并保持可预测的行为:
  • Capture Claude:即时想法收集(无规划开销)
  • Work Claude:为每个任务生成全新子Agent进行自主执行
  • 验证:在任一实例中运行并保持状态跟踪

Future Enhancements

快速入门指南

Planned Features

首次使用用户

  1. Priority Bumping: Auto-bump priority based on age or Linear updates
  2. Scheduled Processing: Run processor at specific times (cron-like)
  3. Batch Linear Updates: Reduce API calls by batching updates
  4. Smart Retry Logic: Auto-retry failed items with exponential backoff
  5. User Notifications: Notify when high-priority items complete
  6. Analytics Dashboard: Web UI for queue statistics and trends
  7. Agent Performance Metrics: Track success rate per agent
  8. Complexity Prediction: ML model to predict execution time
  9. Parallel Processing: Process multiple simple items in parallel
  10. Queue Templates: Pre-defined templates for common workflows
  1. 捕获想法:自然输入你的想法,然后使用
    /workflow capture
  2. 验证想法:使用
    /workflow validate
    让资深PM评估可行性并分配Agent
  3. 处理已验证任务:使用
    /workflow process
    自主执行已验证的任务项
  4. 监控进度:使用
    /workflow status
    实时查看当前状态

Experimental Ideas

常见工作流

  • Voice Capture: Capture ideas via voice commands
  • Email Integration: Capture ideas from email
  • Slack Integration: Capture ideas from Slack messages
  • GitHub Integration: Capture ideas from GitHub issues/PRs
  • Auto-Prioritization: ML-based priority assignment
  • Cost Estimation: Estimate financial value of queue items

快速捕获模式(Capture Claude):
用户:修复移动端导航栏内边距问题
/workflow capture

用户:同时分析2023-24财年的研发交易
/workflow capture

用户:另外在设置中添加深色模式切换按钮
/workflow capture
自主执行模式(Work Claude):
/workflow process --continuous

(运行至队列空或令牌耗尽)
快速状态检查
/workflow status

Changelog

命令说明

v2.0.0 (2026-01-29)

/workflow
(无参数)

  • Initial comprehensive skill documentation
  • Unified
    /workflow
    command interface
  • Integration with work-queue-manager.ts
  • Integration with pm-validator.ts
  • Integration with Linear API
  • Detailed examples for all commands
  • Error handling patterns
  • Performance targets and metrics
  • Testing checklist
  • Troubleshooting guide

显示交互式菜单,包含当前队列状态和可用命令。
输出
🔄 想法收集工作流 v2.0.0

当前队列状态:
├─ 待处理:    3项(等待验证)
├─ 已验证:  2项(可处理)
├─ 处理中: 1项 (正在执行)
└─ 已完成:  15项(已归档)

可用命令:
├─ /workflow capture   - 将当前消息捕获为想法
├─ /workflow validate  - 验证所有待处理项(PM审核)
├─ /workflow process   - 处理已验证项(执行任务)
├─ /workflow status    - 显示详细队列状态
└─ /workflow stats     - 显示性能统计数据

💡 快速操作:
- 捕获当前消息:/workflow capture
- 验证所有待处理项:/workflow validate
- 处理所有任务:/workflow process --continuous
- 查看当前状态:/workflow status

📚 文档:.agent/skills/idea-intake-workflow/SKILL.md
适用场景
  • 首次使用系统
  • 忘记可用子命令
  • 需要快速查看队列状态概览
别名:无(仅使用标准形式)

References

/workflow capture

Related Skills

  • idea-queue-capture - Fast idea capture (sub-skill)
  • work-queue-processor - Autonomous execution (sub-skill)
  • australian-tax-law-research - Tax legislation research
  • xero-api-integration - Xero data fetching
  • rnd-eligibility-assessment - R&D tax analysis
将当前用户消息(若为空则使用上一条消息)捕获为想法并加入工作队列。
别名
capture
,
add
,
queue
,
idea
流程
  1. 提取用户最新消息(或使用提供的文本)
  2. 自动检测类型(功能需求/BUG/改进/任务/客户请求)
  3. 生成简洁标题(最多80字符)
  4. 若检测到多个相关想法则自动智能分组
  5. 写入Supabase的
    work_queue
    表,状态标记为'pending'
  6. 返回包含队列ID和位置的确认信息
实现代码
typescript
import { addToQueue } from '@/lib/queue/work-queue-manager';

// 捕获想法
const queueItem = await addToQueue({
  title: generatedTitle,
  description: userInputVerbatim,
  queue_item_type: detectedType,
  payload: {
    original_message: userInput,
    context: currentContext,
    timestamp: new Date().toISOString(),
    source: 'workflow-capture',
  },
});

console.log(`✅ 已捕获:${queueItem.title} (ID: ${queueItem.id})`);
示例1 - 简单BUG
用户:移动端导航栏内边距太大了
用户:/workflow capture

Claude:✅ 想法捕获成功!

**标题**:修复移动端导航栏内边距问题
**类型**:BUG
**队列位置**:#3
**状态**:待验证

下一步:资深PM Agent将验证此想法并分配给对应执行Agent。
示例2 - 多个相关想法(已分组)
用户:描述面板有两个问题:
1. 复制图标与文本重叠
2. 各区块之间间距不足
用户:/workflow capture

Claude:✅ 想法捕获成功!

**标题**:修复描述面板UI问题
**类型**:BUG
**队列位置**:#4
**状态**:待验证

说明:已将影响同一组件的2个相关问题分组。
下一步:资深PM将验证并路由至对应Agent。
示例3 - 多个不相关想法(已拆分)
用户:修复复制图标重叠问题。另外,分析2023-24财年的研发交易。
用户:/workflow capture

Claude:✅ 已成功捕获2个想法!

1. **修复复制图标重叠问题**(BUG)- 位置#5
2. **分析2023-24财年研发交易**(功能需求)- 位置#6

说明:因属于不同领域(UI vs 税务分析),已创建独立任务项。
下一步:资深PM将验证这两个想法。
示例4 - 显式文本捕获
用户:/workflow capture 在设置页面添加深色模式切换按钮

Claude:✅ 想法捕获成功!

**标题**:在设置页面添加深色模式切换按钮
**类型**:功能需求
**队列位置**:#7
**状态**:待验证

下一步:资深PM将验证并评估可行性。
选项
  • --text "..."
    - 捕获指定文本而非上一条消息
  • --type <type>
    - 覆盖自动检测的类型(feature|bug|improvement|client_request|task)
  • --separate
    - 强制将多个想法拆分为独立任务项(禁用分组)
错误处理
❌ 想法捕获失败

错误:数据库连接失败

建议:
- 检查SUPABASE_SERVICE_ROLE_KEY是否配置正确
- 验证Supabase项目是否正常运行
- 执行迁移:supabase migration up

你的想法未丢失,请重试或联系支持人员。

Related Files

/workflow validate

  • lib/queue/work-queue-manager.ts
    - Queue operations
  • lib/queue/pm-validator.ts
    - Validation logic
  • lib/linear/api-client.ts
    - Linear integration
  • lib/linear/graphql-queries.ts
    - Linear utilities
  • lib/supabase/server.ts
    - Database client
  • supabase/migrations/20260129_create_work_queue.sql
    - Database schema
使用Senior PM Enhanced Agent验证所有待处理队列项。执行可行性评估、复杂度分析、重复项检测、优先级分配和Agent路由。
别名
validate
,
review
,
pm-review
流程
  1. work_queue
    表获取所有待处理项(状态为'pending')
  2. 对每个任务项: a. 评估可行性(0-100分) b. 确定复杂度(简单/中等/复杂) c. 在Linear中检查重复项 d. 分配优先级(P0/P1/P2/P3) e. 路由至领域Agent f. 确定执行策略(直接执行/需要规划/专家审核) g. 计算置信度得分
  3. 将任务项标记为'validated'并保存验证结果
  4. 若不是重复项则可选创建Linear问题
  5. 返回已验证任务项的摘要
实现代码
typescript
import { getQueueItemsByStatus, markAsValidating, markAsValidated } from '@/lib/queue/work-queue-manager';
import { validateQueueItem } from '@/lib/queue/pm-validator';

// 获取待处理项
const pendingItems = await getQueueItemsByStatus('pending');

for (const item of pendingItems) {
  // 标记为验证中
  await markAsValidating(item.id);

  // 执行验证
  const validationResult = await validateQueueItem(item);

  // 标记为已验证
  await markAsValidated(item.id, validationResult);

  console.log(`✅ 已验证:${item.title}`);
  console.log(`   复杂度:${validationResult.complexity}`);
  console.log(`   优先级:${validationResult.priority}`);
  console.log(`   分配Agent:${validationResult.assigned_agent}`);
}
示例1 - 单个任务项验证
用户:/workflow validate

Claude:🔍 开始验证待处理项...

验证中:修复移动端导航栏内边距问题

**可行性得分**:85/100
- 前端修改可基于现有模式直接完成
- UI组件修改风险极低

**复杂度**:简单
- 仅需修改单个文件,实现直接明了

**优先级**:P2(中等)
- BUG修复,影响用户体验

**分配Agent**:general
- 无需专业Agent

**执行策略**:直接执行
- 无需规划阶段可立即执行

**置信度**:80%

**重复项检查**:未发现重复项

✅ 验证完成!任务项已准备好执行。

状态已变更:pending → validated
示例2 - 多个任务项验证(含重复项检测)
用户:/workflow validate

Claude:🔍 开始验证待处理项...

[1/3] 验证中:修复描述面板间距问题

**可行性得分**:90/100
**复杂度**:简单
**优先级**:P2
**分配Agent**:general
**策略**:直接执行
**置信度**:85%
**重复项**:⚠️ 与UNI-42高度相似(匹配度87%)

操作:将上下文合并至现有Linear问题UNI-42
状态:标记为重复项,不会创建新问题

---

[2/3] 验证中:分析2023-24财年研发交易

**可行性得分**:95/100
- 已集成Xero可用于数据提取
- 有R&D税收激励专业Agent可用

**复杂度**:复杂
- 需要大量分析,涉及多个文件

**优先级**:P1(高)
- 研发注册截止日期临近

**分配Agent**:rnd-tax-specialist
- 路由至R&D专业Agent进行Division 355分析

**执行策略**:专家审核
- 因复杂度高,执行前需用户批准

**置信度**:90%
**重复项**:未发现重复项

操作:正在创建Linear问题...
✅ 已创建:UNI-45 - 分析2023-24财年研发交易

---

[3/3] 验证中:在设置中添加深色模式切换按钮

**可行性得分**:85/100
**复杂度**:中等
**优先级**:P3(低)
**分配Agent**:general
**策略**:需要规划
- 执行前需规划子Agent参与

**置信度**:80%
**重复项**:未发现重复项

操作:正在创建Linear问题...
✅ 已创建:UNI-46 - 在设置中添加深色模式切换按钮

---

📊 验证摘要
- 待处理项总数:3项
- 已验证:3项
- 重复项:1项
- 创建Linear问题:2项
- 可执行:3项(2项新任务,1项合并)

下一步:使用`/workflow process`启动自主执行
选项
  • --batch <N>
    - 最多验证N个任务项(默认:所有待处理项)
  • --create-issues
    - 立即创建Linear问题(默认:true)
  • --skip-duplicates
    - 跳过重复项检查(速度更快,不推荐)
验证标准
标准阈值操作
可行性得分< 50标记为不可行,需用户审核
可行性得分50-79标记为可行并添加备注
可行性得分80-100标记为高度可行
重复项相似度> 70%标记为重复项,合并上下文
重复项相似度50-70%标记为潜在重复项,通知用户
重复项相似度< 50%非重复项
错误处理
❌ 验证失败:分析研发交易

错误:Linear API连接失败

操作:标记为'validating'(将重试)
建议:检查LINEAR_API_KEY并重试

继续处理其他任务项...

External Documentation

/workflow process

使用work-queue-processor模式自主处理所有已验证队列项。为每个任务项生成全新子Agent上下文,避免上下文污染。
别名
process
,
execute
,
work
,
do-work
流程
  1. 获取下一个已验证任务项(状态为'validated',按优先级和创建时间排序)
  2. 将任务项标记为'processing'
  3. 若不存在则创建Linear问题
  4. 根据复杂度路由:
    • 简单:直接执行
    • 中等:PLANNER子Agent → EXECUTOR子Agent
    • 复杂:PLANNER子Agent → 用户批准 → EXECUTOR子Agent
  5. 随着任务推进更新Linear状态
  6. 捕获前后截图
  7. 标记为'complete'或'failed'
  8. 若完成则归档
  9. 重复至队列为空或停止
实现代码
typescript
import { getNextValidatedItem, markAsProcessing, markAsComplete, markAsFailed } from '@/lib/queue/work-queue-manager';
import { createIssue, updateIssue } from '@/lib/linear/api-client';

// 编排器循环
while (true) {
  // 获取下一个任务项
  const item = await getNextValidatedItem();
  if (!item) {
    console.log('队列为空');
    break;
  }

  // 标记为处理中
  await markAsProcessing(item.id);

  // 若需要则创建Linear问题
  if (!item.linear_issue_id) {
    const issue = await createIssue(buildIssueFromQueue(item));
    await updateLinearMetadata(item.id, {
      issue_id: issue.id,
      issue_identifier: issue.identifier,
      issue_url: issue.url,
    });
  }

  // 根据复杂度执行
  try {
    let result;
    if (item.complexity === 'simple') {
      result = await executeSimpleTask(item);
    } else if (item.complexity === 'medium') {
      const plan = await spawnPlannerSubAgent(item);
      result = await spawnExecutorSubAgent(item, plan);
    } else {
      const plan = await spawnPlannerSubAgent(item);
      const approved = await askUserForApproval(plan);
      if (!approved) {
        await markAsFailed(item.id, '用户拒绝了计划');
        continue;
      }
      result = await spawnExecutorSubAgent(item, plan);
    }

    // 标记为完成
    await markAsComplete(item.id, result);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('completed'),
    });

  } catch (error) {
    // 标记为失败
    await markAsFailed(item.id, error.message);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('canceled'),
    });
  }

  // 速率限制(4秒延迟)
  await sleep(4000);
}
示例1 - 简单任务项(直接执行)
用户:/workflow process

Claude:⚙️ 工作队列处理器已启动

[1/3] 处理中:修复移动端导航栏内边距问题(UNI-43)
- 复杂度:简单
- 策略:直接执行(无需规划)

执行中...
- 读取:app/components/Navigation.tsx
- 分析:当前内边距值
- 更新:移动端断点内边距从20px改为12px
- 测试:视觉验证

✅ 完成!(3分钟)

变更:
- 更新:app/components/Navigation.tsx(1个文件,修改3行)
- 截图(处理前):.queue/screenshots/uuid-123/before.png
- 截图(处理后):.queue/screenshots/uuid-123/after.png

Linear链接:https://linear.app/unite-hub/issue/UNI-43
状态:已完成 → 已归档

---

[2/3] 处理中:在设置中添加深色模式切换按钮(UNI-46)
- 复杂度:中等
- 策略:需要规划
- Agent:general

正在生成PLANNER子Agent...

📋 已创建计划:
1. 创建支持亮色/暗色状态的ThemeContext提供者
2. 创建带开关UI的ThemeToggle组件
3. 更新现有组件以读取ThemeContext
4. 添加主题颜色的CSS变量
5. 将主题偏好持久化到localStorage

✓ 计划已自动批准(中等复杂度)

正在生成EXECUTOR子Agent...

执行计划中...
- 创建:lib/theme/ThemeContext.tsx
- 创建:components/ThemeToggle.tsx
- 更新:app/layout.tsx(用ThemeProvider包裹)
- 更新:8个组件以使用主题颜色
- 添加:globals.css中的CSS变量
- 添加:localStorage持久化

测试深色模式...
✅ 亮色模式正常
✅ 暗色模式正常
✅ 刷新后主题保持不变

✅ 完成!(12分钟)

变更:
- 创建:2个文件
- 更新:10个文件
- 总修改行数:247行

Linear链接:https://linear.app/unite-hub/issue/UNI-46
状态:已完成 → 已归档

---

[3/3] 处理中:分析2023-24财年研发交易(UNI-45)
- 复杂度:复杂
- 策略:需要专家审核
- Agent:rnd-tax-specialist

正在生成PLANNER子Agent(rnd-tax-specialist)...

📋 已创建计划:
1. 获取2023-24财年(2023年7月1日-2024年6月30日)的所有Xero交易
2. 筛选潜在的R&D支出(开发、研究、咨询)
3. 对每个交易应用Division 355四要素测试
4. 计算符合条件的支出
5. 计算R&D税收抵免(营业额<2000万澳元为43.5%)
6. 生成包含法规引用的合规报告
7. 标记需要进一步审核的交易

预估价值:潜在退款20万-50万澳元

⚠️ 这是涉及重大财务价值的复杂分析。

是否继续执行?[是/否]

用户:是

✓ 用户已批准

正在生成EXECUTOR子Agent(rnd-tax-specialist)...

执行R&D分析中...
- 获取Xero交易(2023年7月1日-2024年6月30日)...
- 已获取:1247笔交易
- 筛选潜在R&D支出...
- 发现:387笔潜在R&D交易

应用Division 355四要素测试...
- 测试1(新知识):256笔交易通过
- 测试2(结果未知):198笔交易通过
- 测试3(系统方法):167笔交易通过
- 测试4(科学方法):127笔交易通过

✅ 符合条件:127笔交易

计算税收优惠...
- 总符合条件支出:293,000澳元
- R&D税收抵免(43.5%):127,455澳元
- 潜在退款:127,455澳元

生成合规报告...
- 按类别划分的交易明细
- 每笔交易的四要素测试结果
- 法规引用(Division 355 ITAA 1997)
- 注册截止日期:2025年4月30日
- 专业审核建议

✅ 完成!(18分钟)

分析摘要:
- 分析交易数:1247笔
- 符合条件的R&D交易:127笔
- 符合条件支出:293,000澳元
- 税收抵免:127,455澳元
- 置信度:高(90%)

报告已保存:.queue/reports/rnd-analysis-fy2023-24.pdf

⚠️ 建议:
- 提交前需专业审核
- 2025年4月30日前向AusIndustry注册
- 15笔交易需补充文档

Linear链接:https://linear.app/unite-hub/issue/UNI-45
状态:已完成 → 已归档

---

📊 会话完成

已处理:3项
成功:3项(100%)
失败:0项
总耗时:33分钟
使用令牌:约18,500 PTS

队列状态:
- 待处理:0项
- 已验证:0项
- 处理中:0项

所有任务项已完成!🎉
示例2 - 连续模式
用户:/workflow process --continuous

Claude:⚙️ 工作队列处理器已启动(连续模式)

将持续处理任务项直到队列为空或令牌耗尽。

按Ctrl+C或使用/workflow pause优雅停止。

---

[1/10] 处理中:修复复制图标重叠问题(UNI-42)
...
✅ 完成!(2分钟)

[2/10] 处理中:更新表单验证(UNI-47)
...
✅ 完成!(8分钟)

[3/10] 处理中:重构税收计算逻辑(UNI-48)
...
⚙️ 处理中...(完成45%)

(持续处理直到队列为空)

---

📊 会话完成

已处理:10项
成功:9项(90%)
失败:1项(10%)
总耗时:87分钟
使用令牌:约42,300 PTS
剩余令牌:约47,700 PTS

队列状态:空

下一步:使用/workflow capture添加更多想法
选项
  • --continuous
    - 运行至队列为空或令牌耗尽
  • --limit <N>
    - 最多处理N个任务项后停止
  • --priority <P>
    - 仅处理指定优先级的任务项(P0/P1/P2/P3)
  • --agent <name>
    - 仅处理分配给指定Agent的任务项
错误处理
当任务项失败时:
❌ 执行失败:添加深色模式切换按钮(UNI-46)

错误:组件ThemeContext.tsx已存在
重试次数:1/3

操作:
- 标记为'failed'并添加错误信息
- 将Linear问题更新为'Canceled'
- 在Linear中添加包含错误详情的评论

工作循环将继续处理下一个任务项。
如需重试失败任务项,使用/workflow retry
当令牌预算不足时:
⚠️ 令牌预算不足(剩余8,500 PTS)

操作:优雅暂停工作循环
状态:已保存处理器状态

本次会话已处理任务项:8项
队列剩余任务项:2项

如需恢复:/workflow process
性能目标
指标目标
简单任务项执行时间< 5分钟
中等任务项执行时间< 15分钟
复杂任务项执行时间< 30分钟
队列吞吐量90分钟处理10-25项
成功率> 95%
每个任务项令牌使用量50-500 PTS

Notes

/workflow status

  • Designed for Australian Tax Optimizer (ATO) platform
  • Follows Matt Maher's "do-work" autonomous pattern
  • Complements "Capture Claude" and "Work Claude" two-instance pattern
  • Each item gets fresh sub-agent context (no pollution)
  • Observable via Linear for team visibility
  • Fault-tolerant: Continues on individual item failures
  • Archives maintain full audit trail
  • Uses Australian English throughout (optimisation, labour, etc.)

Last Updated: 2026-01-29 Version: 2.0.0 Author: Matt Maher Maintainer: Claude Code Agent Fleet
显示当前队列状态的详细 breakdown,包括当前处理的任务项、各状态的任务项数和最近完成的任务。
别名
status
,
queue
,
progress
流程
  1. work_queue
    表获取队列统计数据
  2. 获取当前处理的任务项(若有)
  3. 获取最近完成的任务(最近5项)
  4. 计算预计剩余时间
  5. 按状态显示breakdown
实现代码
typescript
import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';

// 获取统计数据
const stats = await getQueueStatistics();

// 获取当前处理的任务项
const processingItems = await getQueueItemsByStatus('processing', 1);
const currentItem = processingItems[0] || null;

// 获取最近完成的任务
const recentCompletions = await getQueueItemsByStatus('complete', 5);

// 显示状态
console.log('📊 队列状态\
');
if (currentItem) {
  console.log('当前处理中:');
  console.log(`- ${currentItem.title} (${currentItem.linear_issue_identifier})`);
  console.log(`- 进度:执行中...`);
  console.log(`- 已耗时:${calculateElapsed(currentItem.updated_at)}\
`);
}

console.log('队列breakdown:');
console.log(`├─ 待处理:    ${stats.pending_count}`);
console.log(`├─ 验证中: ${stats.validating_count}`);
console.log(`├─ 已验证:  ${stats.validated_count}项(可处理)`);
console.log(`├─ 处理中: ${stats.processing_count}`);
console.log(`├─ 已完成:   ${stats.complete_count}`);
console.log(`├─ 失败:     ${stats.failed_count}`);
console.log(`└─ 已归档:   ${stats.archived_count}项\
`);
示例输出
用户:/workflow status

Claude:📊 队列状态

当前处理中:
- 分析2023-24财年研发交易(UNI-45)
- 进度:应用Division 355测试(完成67%)
- 已耗时:12分钟
- Agent:rnd-tax-specialist

队列breakdown:
├─ 待处理:    2项(等待验证)
├─ 验证中: 0项
├─ 已验证:  3项(可处理)
├─ 处理中: 1项 (正在执行)
├─ 已完成:   25项
├─ 失败:     1项
└─ 已归档:   22项

最近完成:
1. 修复导航栏内边距(UNI-43)- 15分钟前 ✅
2. 更新表单验证(UNI-47)- 23分钟前 ✅
3. 重构税收计算(UNI-48)- 45分钟前 ✅
4. 添加用户认证(UNI-49)- 1小时前 ✅
5. 修复数据库迁移(UNI-50)- 2小时前 ✅

会话统计:
- 今日已处理任务项:8项
- 成功率:87.5%
- 平均执行时间:9.3分钟
- 总令牌使用量:24,500 PTS

已验证任务项预计耗时:约45分钟

队列下一个任务:
1. 添加深色模式切换按钮(UNI-46)- P3 - 中等复杂度
2. 修复复制图标重叠(UNI-51)- P2 - 简单
3. 创建导出功能(UNI-52)- P1 - 复杂

如需处理已验证任务项:/workflow process
如需查看详细统计:/workflow stats
适用场景
  • 查看当前正在处理的任务
  • 查看队列积压情况
  • 在长处理会话中监控进度
  • 验证任务项是否已捕获/验证
  • 查看预计完成时间

/workflow stats

显示想法收集工作流系统的详细性能统计和指标。
别名
stats
,
metrics
,
performance
,
analytics
流程
  1. 从数据库获取队列统计数据
  2. 计算性能指标(成功率、执行时间、令牌使用量)
  3. 按复杂度、优先级、Agent细分
  4. 显示验证统计数据
  5. 显示时间趋势
实现代码
typescript
import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';
import { calculateValidationStats } from '@/lib/queue/pm-validator';

// 获取统计数据
const stats = await getQueueStatistics();

// 获取所有已验证任务项用于PM统计
const validatedItems = await getQueueItemsByStatus('validated');
const pmStats = calculateValidationStats(validatedItems);

// 计算成功率
const totalProcessed = stats.complete_count + stats.failed_count;
const successRate = totalProcessed > 0
  ? (stats.complete_count / totalProcessed * 100).toFixed(1)
  : 0;

// 显示统计数据
console.log('📊 工作流统计\
');
console.log('整体性能:');
console.log(`- 已处理任务项总数:${totalProcessed}`);
console.log(`- 成功率:${successRate}%`);
console.log(`- 平均执行时间:${stats.avg_execution_time_seconds}`);
console.log(`- 总令牌使用量:${stats.total_token_usage} PTS\
`);

console.log('按复杂度划分:');
console.log(`- 简单:${pmStats.by_complexity.simple}`);
console.log(`- 中等:${pmStats.by_complexity.medium}`);
console.log(`- 复杂:${pmStats.by_complexity.complex}项\
`);
示例输出
用户:/workflow stats

Claude:📊 工作流统计

整体性能:
- 已处理任务项总数:127
- 成功率:96.8%(123项成功,4项失败)
- 平均执行时间:8.3分钟
- 总令牌使用量:45,230 PTS
- 每个任务项平均令牌使用量:356 PTS

状态Breakdown:
├─ 待处理:    3项(2.3%)
├─ 验证中: 0项(0%)
├─ 已验证:  2项(1.6%)
├─ 处理中: 1项 (0.8%)
├─ 已完成:   119项(93.7%)
├─ 失败:     2项(1.6%)
└─ 已归档:   115项(90.6%)

按复杂度划分:
├─ 简单:   47项(37.0%)- 平均耗时:3.2分钟
├─ 中等:   58项(45.7%)- 平均耗时:9.1分钟
└─ 复杂:  22项(17.3%)- 平均耗时:21.4分钟

按优先级划分:
├─ P0(关键):2项(1.6%)
├─ P1(高):     28项(22.0%)
├─ P2(中等):   74项(58.3%)
└─ P3(低):      23项(18.1%)

按分配Agent划分:
├─ general:                    67项(52.8%)
├─ rnd-tax-specialist:         18项(14.2%)
├─ deduction-optimizer:        12项(9.4%)
├─ xero-auditor:               11项(8.7%)
├─ loss-recovery-agent:        8项(6.3%)
├─ trust-distribution-analyzer: 5项(3.9%)
└─ 其他专家:          6项(4.7%)

验证统计:
- 平均可行性得分:82/100
- 平均置信度:78/100
- 重复项检测率:12%(已发现15个重复项)

执行策略:
- 直接执行:47项(37.0%)
- 需要规划:58项(45.7%)
- 专家审核:22项(17.3%)

近期趋势(过去24小时):
- 捕获想法数:15
- 验证任务项数:12
- 处理任务项数:10
- 成功率:100%
- 每个任务项平均耗时:7.2分钟

时间分布:
- 0-5分钟:   47项(37.0%)
- 5-10分钟:  38项(29.9%)
- 10-15分钟: 20项(15.7%)
- 15-30分钟: 18项(14.2%)
- 30+分钟:   4项(3.1%)

令牌分布:
- 0-100 PTS:    52项(40.9%)
- 100-500 PTS:  61项(48.0%)
- 500-1000 PTS: 12项(9.4%)
- 1000+ PTS:    2项(1.6%)

失败任务项分析:
- 数据库连接:1项
- 用户取消:1项
- 总失败数:2项(1.6%)

表现最佳类别:
1. UI/前端变更:98%成功率(平均3.8分钟)
2. 税务分析:95%成功率(平均18.2分钟)
3. 数据库变更:87%成功率(平均12.4分钟)

建议:
✅ 捕获率高 - 系统使用效率良好
✅ 优秀的成功率(96.8%)- 执行质量高
⚠️ 12%的重复率 - 考虑改进捕获描述
✅ 令牌使用高效(每个任务项平均356 PTS)
适用场景
  • 定期性能审核
  • 了解系统使用模式
  • 识别瓶颈或问题
  • 向利益相关者报告指标
  • 优化工作流流程

实现说明

架构概览

┌─────────────────────────────────────────────────────────────┐
│                    /workflow 命令                         │
│                   (编排器技能)                      │
└───────────────┬─────────────────────────────────────────────┘
                ├─ /workflow capture
                │  └─ 使用:lib/queue/work-queue-manager.ts
                │     └─ 函数:addToQueue()
                ├─ /workflow validate
                │  └─ 使用:lib/queue/pm-validator.ts
                │     └─ 函数:validateQueueItem()
                │     └─ 函数:checkForDuplicates()
                │     └─ 使用:lib/linear/api-client.ts
                ├─ /workflow process
                │  └─ 使用:lib/queue/work-queue-manager.ts
                │     └─ 函数:getNextValidatedItem()
                │     └─ 函数:markAsProcessing()
                │     └─ 函数:markAsComplete()
                │     └─ 函数:markAsFailed()
                │     └─ 使用:lib/linear/api-client.ts
                ├─ /workflow status
                │  └─ 使用:lib/queue/work-queue-manager.ts
                │     └─ 函数:getQueueStatistics()
                │     └─ 函数:getQueueItemsByStatus()
                └─ /workflow stats
                   └─ 使用:lib/queue/work-queue-manager.ts
                      └─ 函数:getQueueStatistics()
                      └─ 使用:lib/queue/pm-validator.ts
                         └─ 函数:calculateValidationStats()

关键依赖

数据库(Supabase)
  • 表:
    work_queue
    (由迁移
    20260129_create_work_queue.sql
    创建)
  • 服务客户端:
    lib/supabase/server.ts
  • 函数:
    • get_next_pending_queue_item()
      - 行级锁并跳过已锁定行
    • get_next_validated_queue_item()
      - 按优先级排序并加锁
    • get_queue_statistics()
      - 聚合统计数据
队列管理器
lib/queue/work-queue-manager.ts
):
  • addToQueue()
    - 添加新任务项
  • getNextPendingItem()
    - 获取待验证任务项
  • getNextValidatedItem()
    - 获取待执行任务项
  • markAsValidating()
    ,
    markAsValidated()
    ,
    markAsProcessing()
    ,
    markAsComplete()
    ,
    markAsFailed()
    - 状态转换
  • archiveQueueItem()
    - 归档已完成任务项
  • updateLinearMetadata()
    - 存储Linear问题引用
  • getQueueStatistics()
    - 性能指标
  • getQueueItemsByStatus()
    - 按状态筛选
  • timeoutStuckItems()
    - 处理卡住任务项的安全机制
PM验证器
lib/queue/pm-validator.ts
):
  • validateQueueItem()
    - 主验证流水线
  • assessFeasibility()
    - 可行性评分(0-100)
  • assessComplexity()
    - 复杂度检测(简单/中等/复杂)
  • assignPriority()
    - 优先级分配(P0/P1/P2/P3)
  • determineAssignedAgent()
    - Agent路由逻辑
  • determineExecutionStrategy()
    - 执行策略(直接/规划/审核)
  • checkForDuplicates()
    - Linear重复项检测
  • calculateValidationStats()
    - 验证指标
Linear集成
lib/linear/api-client.ts
):
  • createIssue()
    - 从队列任务项创建Linear问题
  • updateIssue()
    - 更新问题状态
  • searchIssues()
    - 搜索重复项
  • addComment()
    - 向问题添加评论
  • getStateIdByType()
    - 获取工作流状态ID
Linear工具
lib/linear/graphql-queries.ts
):
  • buildIssueFromQueue()
    - 将队列任务项转换为Linear问题格式
  • extractSearchKeywords()
    - 提取重复项搜索关键词
  • findPotentialDuplicates()
    - 相似度匹配
  • mapQueueStatusToLinearState()
    - 状态映射

数据流

捕获流程
用户消息
  → 解析并提取想法
  → 自动检测类型
  → 生成标题
  → addToQueue() → Supabase work_queue
  → 返回确认信息
验证流程
待处理任务项
  → getQueueItemsByStatus('pending')
  → 对每个任务项:
     → markAsValidating()
     → validateQueueItem()
       → assessFeasibility()
       → assessComplexity()
       → checkForDuplicates() → Linear API
       → assignPriority()
       → determineAssignedAgent()
       → determineExecutionStrategy()
     → markAsValidated()
     → 若不是重复项则创建Linear问题
  → 返回摘要
处理流程
已验证任务项
  → getNextValidatedItem()(带行锁)
  → markAsProcessing()
  → 若需要则创建Linear问题
  → 根据复杂度路由:
     → 简单:executeSimpleTask()
     → 中等:spawnPlannerSubAgent() → spawnExecutorSubAgent()
     → 复杂:spawnPlannerSubAgent() → askUserForApproval() → spawnExecutorSubAgent()
  → markAsComplete() 或 markAsFailed()
  → updateIssue() → Linear API
  → archiveQueueItem()(若完成)
  → 重复

错误处理模式

数据库错误
typescript
try {
  const item = await addToQueue({ ... });
  return { status: 'success', item };
} catch (error) {
  console.error('添加任务项到队列失败:', error);
  return {
    status: 'error',
    error: error.message,
    suggestions: [
      '检查SUPABASE_SERVICE_ROLE_KEY是否配置正确',
      '验证Supabase项目是否正常运行',
      '执行迁移:supabase migration up'
    ]
  };
}
Linear API错误
typescript
try {
  const duplicateCheck = await checkForDuplicates(item);
} catch (error) {
  console.warn('重复项检查失败,将继续执行:', error);
  // 优雅降级 - 假设不是重复项
  duplicateCheck = { isDuplicate: false };
}
执行失败
typescript
try {
  const result = await executeQueueItem(item);
  await markAsComplete(item.id, result);
} catch (error) {
  console.error(`任务项${item.id}执行失败:`, error);
  await markAsFailed(item.id, error.message);

  // 更新Linear
  await updateIssue(item.linear_issue_id, {
    stateId: await getStateIdByType('canceled'),
  });
  await addComment(item.linear_issue_id,
    `执行失败:${error.message}\
\
已在队列中标记为失败。`
  );

  // 继续处理下一个任务项(不停止循环)
  continue;
}
令牌耗尽
typescript
const estimatedRemainingTokens = calculateRemainingTokens();

if (estimatedRemainingTokens < MIN_TOKEN_THRESHOLD) {
  console.warn('令牌预算不足,将优雅停止');

  await saveProcessorState({
    lastProcessedId: item.id,
    itemsProcessed: count,
    timestamp: new Date().toISOString(),
  });

  return {
    status: 'paused',
    reason: 'token_budget_low',
    itemsProcessed: count,
    message: '因令牌预算不足,工作循环已暂停。重启可继续。',
  };
}

配置

环境变量
bash
undefined

数据库(必填)

SUPABASE_URL=https://your-project.supabase.co SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Linear集成(验证/处理必填)

LINEAR_API_KEY=lin_api_... LINEAR_TEAM_ID=UNI LINEAR_PROJECT_ID=project-id-optional

队列配置(可选)

QUEUE_BATCH_SIZE=10 # 每次验证/处理会话的最大任务项数 QUEUE_POLL_INTERVAL_MS=5000 # 检查新任务项的间隔时间 QUEUE_MAX_RETRIES=3 # 失败后的最大重试次数 QUEUE_TIMEOUT_HOURS=2 # 处理中状态超过N小时则标记为失败 MIN_TOKEN_THRESHOLD=10000 # 令牌少于此值则停止处理

**速率限制**:
- **Linear API**:调用间隔4秒延迟(遵循Gemini模式)
- **Supabase**:无速率限制(自托管或限额宽松)
- **令牌预算**:剩余令牌<10,000 PTS时停止处理

安全考虑

数据库访问
  • 使用
    SUPABASE_SERVICE_ROLE_KEY
    (绕过RLS)
  • 无需用户认证(内部工具)
  • 队列任务项不区分用户(共享队列)
敏感数据处理
  • 捕获时保留用户输入原文(包括敏感数据)
  • 若检测到敏感信息则警告用户
  • Linear问题创建在私有团队工作区
  • 执行日志可能包含敏感上下文
禁止操作(即使在队列中也绝不会执行):
  • 删除生产数据
  • 修改Xero数据(仅只读)
  • 提交ATO申报
  • 向git提交机密信息
  • 强制推送到主分支

性能优化

数据库查询
  • 使用行级锁(
    FOR UPDATE SKIP LOCKED
    )防止竞态条件
  • status
    列创建索引以加快筛选
  • created_at
    列创建索引以优化队列排序
  • priority
    列创建索引以支持基于优先级的处理
缓存
  • 缓存队列统计数据60秒
  • 缓存Linear团队/项目ID会话
  • 不缓存队列任务项(始终实时获取)
批处理
  • 批量验证任务项(默认:所有待处理项)
  • 逐个处理任务项(顺序执行以隔离上下文)
  • Linear API调用速率限制(4秒延迟)
令牌管理
  • 预估每个任务项的令牌使用量(50-500 PTS)
  • 剩余令牌<10,000 PTS时停止
  • 保存处理器状态以便恢复

测试清单

捕获测试

  • 可从用户消息捕获单个想法
  • 可使用
    --text
    选项捕获显式文本
  • 自动检测正确类型(feature/bug/improvement/task/client_request)
  • 生成简洁标题(<80字符)
  • 正确分组相关想法
  • 正确拆分不相关想法
  • 优雅处理数据库连接错误
  • 警告用户敏感信息
  • 返回正确队列位置
  • 在payload中存储完整上下文

验证测试

  • 获取所有待处理任务项
  • 正确评估可行性(0-100分)
  • 检测复杂度(简单/中等/复杂)
  • 分配正确优先级(P0/P1/P2/P3)
  • 路由至正确Agent
  • 正确确定执行策略
  • 在Linear中检查重复项
  • 若不是重复项则创建Linear问题
  • 若为重复项则将上下文合并至现有问题
  • 优雅处理Linear API错误
  • 将任务项标记为已验证并保存验证结果
  • 返回包含所有已验证任务项的摘要

处理测试

  • 获取带行锁的已验证任务项
  • 按优先级顺序处理任务项
  • 直接执行简单任务项
  • 规划并执行中等任务项
  • 复杂任务项需用户批准
  • 为每个任务项生成全新子Agent
  • 随着任务推进更新Linear状态
  • 捕获前后截图
  • 标记任务项为完成并保存元数据
  • 错误时标记任务项为失败
  • 归档已完成任务项
  • 单个任务项失败时继续处理
  • 队列为空时停止
  • 令牌预算不足时停止
  • 遵守速率限制(4秒延迟)

状态测试

  • 显示当前处理中的任务项
  • 按状态显示队列breakdown
  • 显示最近完成的任务
  • 计算预计剩余时间
  • 显示队列中的下一个任务项
  • 正确处理空队列

统计测试

  • 计算整体性能指标
  • 按复杂度拆分
  • 按优先级拆分
  • 按Agent拆分
  • 显示验证统计
  • 显示执行策略分布
  • 显示时间分布
  • 显示令牌分布
  • 显示失败任务项分析
  • 提供建议

故障排除

常见问题

问题:"添加任务项到队列失败:数据库连接失败"
解决方案
  1. 检查
    SUPABASE_SERVICE_ROLE_KEY
    是否配置正确
  2. 验证Supabase项目是否正常运行
  3. 执行迁移:
    supabase migration up
  4. 检查网络连接

问题:"重复项检查失败,将继续执行"
解决方案
  1. 检查
    LINEAR_API_KEY
    是否配置正确
  2. 验证Linear团队/项目ID是否正确
  3. 检查Linear API速率限制
  4. 这是警告而非错误 - 验证将继续

问题:"执行失败:组件已存在"
解决方案
  1. 任务项已标记为失败,工作循环将继续
  2. 查看Linear问题评论中的错误信息
  3. 手动修复问题或调整队列任务项
  4. 使用
    /workflow retry
    重试失败任务项

问题:"令牌预算不足,将优雅停止"
解决方案
  1. 这是预期行为而非错误
  2. 处理器状态已自动保存
  3. 使用
    /workflow process
    恢复
  4. 考虑使用
    --limit
    减少每次会话处理的任务项数

问题:预期有任务项但显示"队列为空"
解决方案
  1. 使用
    /workflow status
    查看状态
  2. 任务项可能处于其他状态(待处理、验证中、处理中)
  3. 先使用
    /workflow validate
    验证待处理任务项
  4. 检查任务项是否已归档

问题:任务项卡在'processing'状态
解决方案
  1. 安全机制将在2小时后超时
  2. 手动运行
    timeoutStuckItems()
    函数
  3. 检查处理器是否崩溃/中断
  4. 手动将任务项标记为'validated'以重试

高级用法

自定义Agent路由

覆盖自动Agent分配:
typescript
import { updateQueueItem } from '@/lib/queue/work-queue-manager';

// 强制分配给特定Agent
await updateQueueItem(itemId, {
  assigned_agent: 'rnd-tax-specialist',
  priority: 'P0',
});

重试失败任务项

typescript
import { getQueueItemsByStatus, updateQueueItem } from '@/lib/queue/work-queue-manager';

// 获取所有失败任务项
const failedItems = await getQueueItemsByStatus('failed');

// 重置为已验证状态以重试
for (const item of failedItems) {
  await updateQueueItem(item.id, {
    status: 'validated',
    error_message: null,
    error_count: 0,
  });
}

批量归档旧任务项

typescript
import { archiveOldFailedItems } from '@/lib/queue/work-queue-manager';

// 归档30天以上的失败任务项
const archivedCount = await archiveOldFailedItems(30);
console.log(`已归档${archivedCount}个旧失败任务项`);

手动超时清理

typescript
import { timeoutStuckItems } from '@/lib/queue/work-queue-manager';

// 将处理中状态超过2小时的任务项超时
const timedOutCount = await timeoutStuckItems(2);
console.log(`已超时${timedOutCount}个卡住的任务项`);

与其他技能的集成

Xero集成

队列任务项可触发Xero数据获取:
typescript
// 示例:R&D分析队列任务项
const item = await addToQueue({
  title: '分析2023-24财年研发交易',
  description: '审核所有Xero交易的R&D资格',
  queue_item_type: 'feature',
  payload: {
    financial_year: 'FY2023-24',
    start_date: '2023-07-01',
    end_date: '2024-06-30',
    analysis_type: 'rnd',
  },
});

// 处理将路由至rnd-tax-specialist
// Agent将自动获取Xero数据

税务法规研究

复杂税务问题可加入队列:
typescript
const item = await addToQueue({
  title: '研究Division 7A贷款还款要求',
  description: '客户有15万澳元股东贷款,需要还款计划',
  queue_item_type: 'client_request',
  payload: {
    loan_amount: 150000,
    client_id: 'client-123',
    legislation: 'Division 7A ITAA 1936',
  },
});

// 处理将路由至loss-recovery-agent
// Agent将研究法规并计算还款计划

Linear工作流集成

队列任务项自动与Linear同步:
  • 捕获:为未来的Linear问题创建占位符
  • 验证:若不是重复项则创建Linear问题
  • 处理:随着任务推进更新Linear问题状态
  • 完成:将Linear问题标记为完成并添加最终评论

报告集成

队列数据可用于生成报告:
typescript
import { getQueueStatistics } from '@/lib/queue/work-queue-manager';
import { calculateValidationStats } from '@/lib/queue/pm-validator';

// 生成周报
const stats = await getQueueStatistics();
const validationStats = calculateValidationStats(validatedItems);

const report = {
  week: getCurrentWeek(),
  items_processed: stats.complete_count,
  success_rate: (stats.complete_count / (stats.complete_count + stats.failed_count) * 100),
  avg_execution_time: stats.avg_execution_time_seconds,
  by_complexity: validationStats.by_complexity,
  by_priority: validationStats.by_priority,
};

// 保存到报告表或发送给利益相关者

未来增强

计划功能

  1. 优先级提升:根据任务项时长或Linear更新自动提升优先级
  2. 定时处理:在特定时间运行处理器(类似cron)
  3. 批量Linear更新:通过批量更新减少API调用
  4. 智能重试逻辑:使用指数退避自动重试失败任务项
  5. 用户通知:高优先级任务项完成时通知用户
  6. 分析仪表板:用于查看队列统计和趋势的Web UI
  7. Agent性能指标:跟踪每个Agent的成功率
  8. 复杂度预测:ML模型预测执行时间
  9. 并行处理:并行处理多个简单任务项
  10. 队列模板:常见工作流的预定义模板

实验性想法

  • 语音捕获:通过语音命令捕获想法
  • 邮件集成:从邮件捕获想法
  • Slack集成:从Slack消息捕获想法
  • GitHub集成:从GitHub问题/PR捕获想法
  • 自动优先级分配:基于ML的优先级分配
  • 成本估算:估算队列任务项的财务价值

更新日志

v2.0.0(2026-01-29)

  • 初始完整技能文档
  • 统一
    /workflow
    命令界面
  • 与work-queue-manager.ts集成
  • 与pm-validator.ts集成
  • 与Linear API集成
  • 所有命令的详细示例
  • 错误处理模式
  • 性能目标和指标
  • 测试清单
  • 故障排除指南

参考

相关技能

  • idea-queue-capture - 快速想法捕获(子技能)
  • work-queue-processor - 自主执行(子技能)
  • australian-tax-law-research - 税务法规研究
  • xero-api-integration - Xero数据获取
  • rnd-eligibility-assessment - R&D税务分析

相关文件

  • lib/queue/work-queue-manager.ts
    - 队列操作
  • lib/queue/pm-validator.ts
    - 验证逻辑
  • lib/linear/api-client.ts
    - Linear集成
  • lib/linear/graphql-queries.ts
    - Linear工具
  • lib/supabase/server.ts
    - 数据库客户端
  • supabase/migrations/20260129_create_work_queue.sql
    - 数据库模式

外部文档

说明

  • 为澳大利亚税务优化器(ATO)平台设计
  • 遵循Matt Maher的"do-work"自主模式
  • 补充"Capture Claude"和"Work Claude"双实例模式
  • 每个任务项使用全新子Agent上下文(无上下文污染)
  • 可通过Linear供团队查看
  • 容错性:单个任务项失败时继续处理
  • 归档保留完整审计轨迹
  • 全程使用澳大利亚英语(如optimisation, labour等)

最后更新:2026-01-29 版本:2.0.0 作者:Matt Maher 维护者:Claude Code Agent Fleet ",