AACWorkflow Docs

架构图

AACWorkflow 系统架构、任务生命周期、安全边界和智能体协作流的可视化指南。

AACWorkflow 架构、任务分发、安全模型和智能体协作模式的参考图。

系统架构

AACWorkflow Cloud 连接 web UI、通过守护进程在用户机器上运行的智能体，以及中央后端。

graph TB
    subgraph cloud ["AACWorkflow Cloud"]
        api["API Server<br/>(Go + PostgreSQL)"]
        ws["WebSocket<br/>Real-time Updates"]
        auth["Auth Service<br/>(OAuth, PAT)"]
    end

    subgraph local ["User Machine (Local Runtime)"]
        daemon["Daemon<br/>(Long-running)"]
        ai["AI Coding Tool<br/>(Claude Code, Cursor, etc.)"]
        cwd["Code Directory<br/>(Git repo)"]
    end

    subgraph ui ["Web UI"]
        board["Issue Board"]
        settings["Settings &<br/>Member List"]
        comments["Comments"]
    end

    board -->|assign issue| api
    api -->|dispatch task| ws
    ws -->|task event| daemon
    daemon -->|poll every 30s| api
    daemon -->|invoke| ai
    ai -->|read/write| cwd
    ai -->|report result| daemon
    daemon -->|upload result| api
    api -->|update| ws
    ws -->|refresh| board
    settings -->|create agent| api
    comments -->|post comment| api
    auth -.->|verify PAT| daemon
    auth -.->|verify session| ui

关键流：

  • 任务分发： 任务分配 → API → WebSocket → 守护进程（30 秒内）
  • 执行： 守护进程在本地调用 AI 工具；工具读取代码、运行命令、编辑文件
  • 结果上传： 智能体向 API 报告完成；WebSocket 实时通知 web UI
  • 认证边界： PAT（个人访问令牌）用于守护进程；session cookies 用于 web UI

任务生命周期

任务从创建到完成，经历不同状态，期间有重试和网络钩子。

graph LR
    queued["📋 Queued<br/>(Issue created)"]
    dispatched["🚀 Dispatched<br/>(Daemon picked it up)"]
    running["⚙️ Running<br/>(AI tool executing)"]
    completed["✅ Completed<br/>(Result uploaded)"]
    failed["❌ Failed<br/>(Error or timeout)"]
    retry["🔄 Retrying<br/>(Automatic retry)"]

    queued -->|daemon polls| dispatched
    dispatched -->|daemon invokes AI| running
    running -->|success| completed
    running -->|error| failed
    failed -->|retry policy| retry
    retry -->|running| running
    retry -->|final failure| failed

    completed -->|webhook| slack["Slack Notification"]
    failed -->|webhook| slack

状态时间：

  • Queued → Dispatched： ≤ 30 秒（守护进程轮询间隔）
  • Dispatched → Running： ≤ 5 秒（AI 工具启动）
  • Running 持续时间： 秒到小时（取决于任务复杂性）
  • Failed → Retry： 可配置的退避（默认指数）

安全与信任边界

AACWorkflow 在云、守护进程和本地执行之间强制明确边界。

graph TB
    subgraph cloud ["AACWorkflow Cloud<br/>(Fully Trusted)"]
        api["API<br/>(Manages auth, dispatch,<br/>webhooks)"]
        db["PostgreSQL<br/>(Stores issues, agents,<br/>audit logs)"]
    end

    subgraph untrusted ["User Machine<br/>(Partially Trusted)"]
        daemon["Daemon<br/>(Runs with user<br/>permissions)"]
        ai["AI Tool<br/>(Untrusted execution<br/>context)"]
        code["Code Directory<br/>(All code readable<br/>by AI tool)"]
    end

    subgraph external ["External Services<br/>(OAuth, Git, Webhooks)"]
        github["GitHub"]
        slack["Slack"]
    end

    api -->|PAT validation| daemon
    api -->|task dispatch| daemon
    daemon -->|result telemetry| api
    api -->|webhook| slack
    api -->|API| github
    ai -->|fork + exec| code
    daemon -->|invoke + stream| ai

    style cloud fill:#90EE90
    style untrusted fill:#FFB6C1
    style external fill:#ADD8E6

信任假设：

  • Cloud API： 未经验证的用户输入不受信任；所有代码默认安全
  • Daemon： 在用户 OS 权限下本地运行；仅对云 API 有网络访问
  • AI 工具： 在守护进程的 OS 用户下执行；对代码目录有读写访问；可执行任意命令
  • 外部服务： GitHub/Slack 网络钩子有速率限制和验证

智能体技能与能力模型

智能体可增强 技能 — 预打包的指令、工具和上下文 — 以处理专业任务。

graph TB
    subgraph agent ["Agent"]
        name["Name & Provider<br/>(Claude Code, Cursor, etc.)"]
        model["Model Selection<br/>(gpt-4, claude-opus, etc.)"]
        instructions["Custom Instructions<br/>(System prompt)"]
    end

    subgraph skills ["Skills (Optional)"]
        skill1["Skill: Frontend<br/>React + Next.js<br/>guidelines"]
        skill2["Skill: Backend<br/>Go + sqlc<br/>patterns"]
        skill3["Skill: DevOps<br/>Terraform +<br/>Kubernetes"]
    end

    subgraph context ["Runtime Context"]
        files["Code Directory<br/>(Git repo)"]
        tools["Local Tools<br/>(git, npm, go,<br/>make, etc.)"]
        secrets["Env Vars & Secrets<br/>(API keys,<br/>credentials)"]
    end

    agent -->|attached to| skills
    agent -->|runs with| context
    skills -->|loaded before| instructions
    name -->|determines| model

    style skills fill:#FFE4B5

技能加载：

  1. 守护进程将技能内容加载到智能体系统提示
  2. 技能上下文（文档、指南、示例）先于用户任务
  3. 智能体使用上下文做出更好的决策（无需显式工具调用）
  4. 技能叠加 — 一个智能体上的多项技能结合其上下文

小队委派

小队是由小队主管领导的智能体团队。传入任务可根据标签、组件或关键字自动路由到正确的智能体。

graph TB
    subgraph squad ["Squad: Backend"]
        lead["🏆 Squad Lead<br/>(Routes issues)"]
        agent1["Agent: Go Expert<br/>(sqlc, handlers)"]
        agent2["Agent: Testing<br/>(unit tests, mocks)"]
        agent3["Agent: DevOps<br/>(migrations, DB)"]
    end

    issue["Incoming Issue<br/>(label: 'backend')"]
    routing["Routing Rule<br/>(Squad + label)"]

    issue -->|matches| routing
    routing -->|dispatches to| squad
    lead -->|decides| agent1
    lead -->|or| agent2
    lead -->|or| agent3

    style squad fill:#E6E6FA
    style lead fill:#FFD700

何时使用小队：

  • 多个智能体具有不同专业知识（前端、后端、QA、DevOps）
  • 自动路由规则（e.g., "all backend/* labels → Backend squad"）
  • 明确的所有权和问责制
  • 通过让智能体专注来减少上下文切换

自动驾驶触发流

自动驾驶观察事件（任务创建、PR 评论等）并自动分发匹配的任务 — 无需手动分配。

graph TB
    subgraph event ["Events"]
        new_issue["New Issue Created"]
        pr_comment["PR Comment Posted"]
        schedule["Scheduled Time"]
    end

    subgraph rules ["Autopilot Rules"]
        rule1["Rule: New Issues<br/>with label 'bug'<br/>→ QA Agent"]
        rule2["Rule: PR Comment<br/>mentioning @bot<br/>→ Code Reviewer"]
        rule3["Rule: Daily 9am<br/>→ Digest Agent"]
    end

    subgraph dispatch ["Dispatch"]
        queue["Task Queue"]
        daemon["Daemon picks up<br/>(within 30s)"]
    end

    new_issue -->|event| rule1
    pr_comment -->|event| rule2
    schedule -->|event| rule3
    rule1 -->|matches| queue
    rule2 -->|matches| queue
    rule3 -->|matches| queue
    queue -->|poll| daemon

    style event fill:#E0FFFF
    style rules fill:#FFFACD
    style dispatch fill:#F0F8FF

自动驾驶用途：

  • 自动分配 bug 到 QA 小队进行回归测试
  • 从合并的 PR 自动草稿 release notes
  • 周期性任务（日常健康检查、周期总结）
  • 将所有 Terraform 差异路由到 DevOps 智能体

数据流：Issue → Agent → PR → Resolution

端到端流，展示任务如何通过分配、执行和 PR 关联移动。

sequenceDiagram
    participant user as User
    participant web as Web UI
    participant api as API Server
    participant daemon as Daemon
    participant ai as AI Tool
    participant code as Code Dir
    participant github as GitHub

    user->>web: Create Issue
    web->>api: POST /issues
    api->>api: Store issue (status: queued)

    user->>web: Assign to Agent
    web->>api: PATCH /issues/:id (assignee)
    api->>api: Dispatch task (status: dispatched)
    api-->>daemon: WebSocket: New task

    daemon->>daemon: Wake up from poll
    daemon->>ai: Invoke AI tool
    ai->>code: Read codebase, run commands

    ai->>ai: Generate solution
    ai->>code: Edit files, commit to branch
    ai->>github: Push branch, create PR

    daemon->>api: POST /tasks/:id/complete (with PR URL)
    api->>api: Update issue status (completed)
    api-->>web: WebSocket: Task complete

    user->>web: Link PR in issue
    web->>api: PATCH /issues/:id (link_pr_url)
    api->>api: Store PR link, sync PR comments

    github->>api: PR merged webhook
    api->>api: Update issue status (resolved)
    api-->>web: WebSocket: Issue resolved

    web-->>user: Show resolved badge

工作区多租户

每个工作区都是一个隔离的租户，拥有自己的成员、智能体、任务和审计日志。

graph TB
    subgraph ws1 ["Workspace: Acme Corp"]
        team1["Members: alice, bob,<br/>agent-backend"]
        issues1["Issues: AAC-1 to AAC-100"]
        agents1["Agents: 3"]
        board1["Board & Views"]
    end

    subgraph ws2 ["Workspace: StartupXYZ"]
        team2["Members: charlie, diana,<br/>agent-full-stack"]
        issues2["Issues: SXY-1 to SXY-50"]
        agents2["Agents: 2"]
        board2["Board & Views"]
    end

    subgraph ws3 ["Workspace: Open Source"]
        team3["Members: eve, frank,<br/>bot-ci, bot-release"]
        issues3["Issues: OS-1 to OS-200"]
        agents3["Agents: 5"]
        board3["Board & Views"]
    end

    db["PostgreSQL<br/>(Shared database<br/>with workspace_id<br/>partition key)"]

    ws1 -.->|workspace_id=1| db
    ws2 -.->|workspace_id=2| db
    ws3 -.->|workspace_id=3| db

多租户保证：

  • 每个查询在数据库层按 workspace_id 过滤
  • 工作区间数据泄露在设计上不可能
  • 审计日志跟踪哪个成员在哪个工作区做了哪个变化
  • 工作区可独立存档、重命名或删除

提供商景观

AACWorkflow 与 16 款 AI 编程工具集成，每个运行自己的模型并提供不同的 API。

graph TB
    aacw["AACWorkflow<br/>Platform"]

    subgraph claude_ecosystem ["Anthropic Ecosystem"]
        cc["Claude Code<br/>(macOS/Linux)"]
        opus["Model: Claude 3.5 Sonnet<br/>(via API)"]
    end

    subgraph cursor_eco ["Cursor Ecosystem"]
        cursor["Cursor IDE<br/>(macOS/Windows/Linux)"]
        gpt4["Model: GPT-4, Claude<br/>(configurable)"]
    end

    subgraph copilot_eco ["Microsoft Ecosystem"]
        copilot["GitHub Copilot<br/>(VS Code + Visual Studio)"]
        copilot_model["Model: GPT-4 Turbo<br/>(via GitHub)"]
    end

    subgraph others ["Other Providers"]
        hermes["Hermes"]
        antigravity["Antigravity"]
        kimi["Kimi"]
    end

    aacw -->|daemon invokes| cc
    aacw -->|daemon invokes| cursor
    aacw -->|daemon invokes| copilot
    aacw -->|daemon invokes| others
    cc -.->|uses| opus
    cursor -.->|uses| gpt4
    copilot -.->|uses| copilot_model

    style claude_ecosystem fill:#FFE4E1
    style cursor_eco fill:#E0F4FF
    style copilot_eco fill:#F0FFF0

所有提供商通过 AACWorkflow 共享相同的分配、执行和结果报告流。

这些图简化以求清晰。详细实现见：

本页目录

系统架构任务生命周期安全与信任边界智能体技能与能力模型小队委派自动驾驶触发流数据流：Issue → Agent → PR → Resolution工作区多租户提供商景观