Autoflow 상세 설명서 — 무엇을, 왜, 어떻게

이 문서는 "버튼을 어떻게 누르나"가 아니라 Autoflow 가 무엇이고, 왜 만들었고, 어떤 역할을 하며, 안에서 무슨 일이 일어나는지를 설명합니다. 사용 절차는 화면 안의 안내로 충분하도록 만들었고, 이 문서는 판단·설명·영업에 쓰기 위한 것입니다.

정본 설계: docs/AUTOFLOW_BUILD_PLAN.md · 주소: https://flow.starplan.one · 2026-09-19 Phase 1 기준


1. 왜 만드는가

1-1. 우리가 반복해서 마주친 문제

지금까지 만든 서비스들을 운영하면서 "사람이 브라우저를 열고 같은 일을 매일 반복하는 구간" 이 계속 나왔습니다.

어디서반복되던 일우리가 임시로 한 것
셀러 콘솔테무·타오바오·1688 에서 상품 정보 긁어오기, 오픈마켓에 등록브라우저 브릿지·PC 에이전트를 셀러 전용으로 만듦
병원 포털닥터나우·나만의닥터 등 5개 예약 플랫폼 접수 확인·수락플랫폼별 유저스크립트·Electron 매크로를 따로 만듦
몰 운영어드민에서 주문·상품 목록을 내려받아 정산표 만들기사람이 매번 다운로드
마케팅광고 관리자·애널리틱스에서 지표를 모아 보고서 작성스크린샷을 찍어 카톡으로
세무·행정세금계산서 발행 포털, 은행·카드사 거래내역 다운로드월말마다 수작업

공통점은 셋입니다. ① 대상 사이트가 API 를 안 준다(또는 비싸다) ② 일은 단순하지만 매일·매주 정해진 시각에 해야 한다 ③ 로그인·2단계 인증·사내망 같은 사람 세션이 필요할 때가 있다.

그때마다 프로그램을 새로 짜는 대신, "한 번 가르치면 대신 반복하는 범용 도구" 를 만들어 두면 위의 모든 경우를 같은 방법으로 처리할 수 있습니다. 그것이 Autoflow 입니다.

1-2. 기존 도구로 안 되는 이유

Autoflow 는 이 세 가지의 빈틈을 겨냥합니다. 스크립트의 힘 + 노코드의 접근성 + 운영에 필요한 기록·보안·알림을 처음부터 한 몸으로.

1-3. 이 도구가 만들어 내는 가치

  1. 시간: 매일 20분짜리 반복 업무 하나가 연 80시간입니다. 플로우 하나가 그걸 없앱니다.
  2. 증거: 모든 실행이 스텝별 스크린샷·로그·산출물로 남습니다. "언제 뭘 받았는지" 를 사람이 기억할 필요가 없습니다.
  3. 재사용: 셀러·병원·몰 프로젝트에서 각각 만들던 자동화가 이제 플로우 파일 하나로 표현되고, 다른 고객에게 그대로 복사됩니다.
  4. 상품: "당신 회사의 반복 웹 업무를 자동화해 드립니다"는 크몽·기업 납품 어디서든 통하는 문장입니다. Autoflow 는 그 상품의 공장입니다.

2. 한 문장 정의

Autoflow 는 "사람이 브라우저에서 하는 반복 업무"를 플로우(절차서)로 적어 두면, 정해진 시각에 서버(또는 사무실 PC)가 대신 실행하고, 결과를 스크린샷·파일·알림으로 돌려주는 자동화 허브입니다.

비유하자면 "업무를 아는 신입 직원 + 그 직원의 업무 일지" 입니다. 절차서(플로우)를 한 번 써 주면, 매일 아침 그 절차대로 사이트에 들어가 일을 하고, 한 걸음마다 화면을 찍어 일지(실행 이력)에 붙이고, 끝나면 카톡(텔레그램)으로 보고합니다. 절차서에 없는 일은 하지 않고, 막히면 멈춰서 어디서 막혔는지 사진과 함께 알려줍니다.


3. 역할 — 누가 무엇을 얻는가

역할하는 일얻는 것
업무 담당자(직원)플로우를 실행하거나, 결과 산출물(CSV·파일)을 받는다반복 작업에서 해방. 매일 아침 결과만 확인
관리자(사장·팀장)어떤 업무가 자동화돼 있고 잘 도는지 대시보드로 본다실패 즉시 알림, 실행 증거, 사람 의존도 감소
플로우 작성자(우리 또는 파워유저)자연어 지시 → AI 초안 → 스텝 다듬기 → 금고에 자격증명 → 스케줄코딩 없이(또는 최소한으로) 자동화 제작
STARPLAN(운영 대행)고객사 플로우 제작·모니터링·사이트 변경 시 수리월 운영 수익, 다른 프로젝트에 재사용

4. 무엇을 할 수 있고, 무엇을 하지 않는가

할 수 있는 것

하지 않는 것 (의도적 경계)

잘 맞는 업무 / 안 맞는 업무


5. 구성 요소와 각자의 역할

 사용자(브라우저) ──▶ ┌────────── Hub (flow.starplan.one, Next.js) ──────────┐
                    │ 플로우 편집기 · AI 초안 · 실행 이력 · 산출물 · 금고 · 설정 │
                    │            runs 테이블에 "queued" 한 줄을 넣는다            │
                    └───────────────┬──────────────────────┬────────────────┘
                                    │ (DB)                  │ (HTTPS, 토큰)
                     ┌──────────────▼──────────┐   ┌────────▼───────────────┐
                     │ Worker/Runner (서버)     │   │ Desktop Agent (PC)     │
                     │ 3초마다 queued 확인       │   │ 4초마다 pull            │
                     │ 헤드리스 Chrome 로 실행   │   │ 로컬 Chrome(사람 세션)  │
                     │ 스텝마다 스샷·로그 기록   │   │ 스텝마다 report         │
                     │ 스케줄(cron) 큐잉        │   │ + 녹화기(Phase 2)       │
                     └──────────────┬──────────┘   └────────┬───────────────┘
                                    └──────────┬────────────┘
                                   ┌───────────▼─────────────┐
                                   │ 대상 웹사이트(ERP·몰·포털) │
                                   └─────────────────────────┘
        곁가지: 금고(AES-256-GCM) · AI Planner/Locator(Anthropic) · 알림(텔레그램/웹훅) · 파일 저장소(/var/lib/autoflow)
구성 요소역할왜 분리했나
Hub사람이 보는 전부. 플로우를 만들고, 실행을 "요청"하고, 결과를 본다웹 앱은 크롬을 띄우지 않는다 → 가볍고, 여러 실행이 웹 요청을 막지 않음
Worker/Runner큐에서 실행을 집어 실제로 브라우저를 조작한다. 스케줄도 여기서 큐잉실행이 오래 걸리거나 죽어도 Hub 는 멀쩡. 동시 실행 수를 따로 조절
Desktop Agent서버가 못 가는 곳(사내망·2FA·IP 제한)에서 같은 플로우를 실행. 브라우저 조작을 녹화해 플로우 초안을 만든다"사람 자리에서만 되는 일" 을 자동화 범위 안으로 끌어옴
AI Planner자연어 → 플로우 초안, 셀렉터가 깨졌을 때 후보 중 고르기, 화면 텍스트 → 구조화 값제작 시간을 시간 단위에서 분 단위로. 사이트 소폭 변경에 버팀
금고(Vault)자격증명 암호화 보관. 플로우에는 {{secret:키}} 만 남음플로우를 공유·복사해도 비밀은 따라가지 않음
알림성공/실패/추출값을 텔레그램·웹훅으로사람이 화면을 열지 않아도 결과가 옴

6. 핵심 개념

개념뜻데이터
플로우(Flow)하나의 반복 업무 절차서. 이름·스텝 목록·스케줄·실행 모드·허용 호스트·실패 정책flows 한 행, steps 는 JSON(DSL v1)
스텝(Step)플로우의 한 동작(이동·클릭·입력…). id(s1, s2…) 로 서로 가리킴flows.steps.steps[]
타깃(Target)스텝이 다룰 화면 요소를 찾는 방법: css / text(보이는 글자) / xpath / ai(설명)스텝 안
변수{{today:YYYY-MM}} 날짜, {{secret:erp.pass}} 금고, {{sales.rows}} 앞 스텝 결과실행 중 컨텍스트
실행(Run)플로우를 한 번 돌린 기록. queued → running → ok / failed / canceledruns
스텝 기록실행 안의 스텝별 결과: 상태·소요·스크린샷·로그·(AI 로 찾았다면) 제안 셀렉터run_steps + 파일
산출물(Artifact)실행이 남긴 파일: 표 CSV, 목록 JSON, 다운로드 파일, 스크린샷artifacts + 파일
모드server(헤드리스, 기본) / agent(PC 에이전트)flows.mode
스케줄cron 5필드(KST). 워커가 매 분 검사해 큐에 넣음flows.schedule_cron

7. 스텝 14종 — 목적·입력·실패 조건

타입목적주요 입력실패하는 경우남기는 것
goto페이지 이동url허용 호스트 밖, 45초 내 로드 실패스샷
click버튼·링크 클릭target요소를 못 찾음(AI 힐링 후에도)스샷
type입력칸에 글자target, text, enter, clear요소 없음스샷(로그엔 비밀값 ***)
select드롭다운 선택target, value요소·옵션 없음스샷
wait조건 대기`for: {cssurlIncludestextms}`제한시간 초과스샷
scroll스크롤to: top/bottom 또는 target—스샷
extract데이터 추출name + table{css} / list{css,fields} / text{css}표·요소 없음CSV/JSON 산출물 + 변수
download파일 내려받기target, saveAs클릭 후 파일이 안 생김파일 산출물
screenshot증빙 캡처name, full—이미지 산출물
ai_extract화면 텍스트 → 구조화 값name, schema{키:타입}, promptAI 응답 불가JSON 산출물 + 변수
if조건 분기exists: target, then[], else[](건너뛸 스텝 id)—스샷
notify알림channel: telegram/webhook, text, url채널 미설정·전송 실패스샷
loop반복over: "{{items.data}}"(앞 추출 배열) 또는 count(1~50), steps[](반복할 스텝 id), var(기본 item)안쪽 스텝 실패(실패 정책 따름), over 가 배열이 아님반복마다 안쪽 스텝 기록(s10@0, s10@1… 로그 앞 i/N)
sheet_appendGoogle Sheets 에 행 추가sheetId, range(Sheet1!A:Z), rows: "{{sales.data}}" 또는 values[[…]], serviceAccountSecret(금고 키, 기본 gsa)서비스 계정 JSON 없음, 권한 없음(403 — 시트를 서비스 계정 이메일과 공유해야 함), 시트 없음(404)로그에 추가된 범위

공통 옵션: label(설명) · retry(0~3, 기본 1) · timeoutMs · optional(실패해도 건너뜀). 플로우 공통: onError: stop | continue, allowHosts[], vars{}. loop 안 스텝은 최상위 순서에서는 건너뛰고 loop 가 돌 때만 실행되며, 안에서 {{item}}(또는 var 이름)·{{index}} 를 쓸 수 있습니다. 표 CSV 를 만드는 extract 는 직전 성공 실행의 같은 이름 CSV 와 자동 비교해 {{diff.added}}·{{diff.removed}}·{{diff.changed}}(행 수, 첫 열 기준) 를 알림 문장에 끼울 수 있습니다.

요소 찾기 순서(모든 target 공통)

  1. css 가 있으면 CSS 셀렉터로(보이는 요소만)
  2. text 가 있으면 그 글자를 포함하는 요소를 XPath 로 — 여러 개면 글자가 가장 짧은(가장 안쪽) 요소 를 고름
  3. xpath
  4. 위가 모두 실패하고 ai 설명이 있거나 힐링이 켜져 있으면(기본), 페이지의 클릭 가능한 요소 후보(최대 80개: 태그·글자·이름·id)를 AI 에게 보여 주고 번호를 고르게 함 → 성공하면 "제안 셀렉터" 를 실행 기록에 남김(플로우를 자동으로 고치진 않음 — 사람이 보고 반영)

실행을 시작하는 네 가지 방법

방법어떻게언제 쓰나
지금 실행플로우 화면의 [실행] 버튼만들고 바로 확인할 때
스케줄플로우의 cron(7 9 * * 1-5 = 평일 09:07). 워커가 1분마다 도래한 플로우를 큐에 넣음매일·매주 반복
웹훅 트리거편집기에서 [웹훅 키 발급] → POST https://flow.starplan.one/api/hooks/<플로우ID>?key=<키> (또는 Authorization: Bearer <키>). 본문 JSON(16KB 이하)은 실행의 입력이 되어 스텝 안에서 {{input.항목}} 또는 바로 {{항목}} 으로 쓴다. 키를 재발급하면 이전 URL 은 즉시 무효주문이 들어올 때, 다른 시스템(ERP·시트·Zapier 류)이 신호를 줄 때
PC 에이전트플로우 모드를 agent 로 두면 큐에 쌓인 실행을 페어링된 PC 의 앱이 가져가 그 PC 의 Chrome 으로 실행사내망·로그인 세션이 필요한 사이트

실행 생애주기

[지금 실행 / 스케줄 / 웹훅 / 재실행]  →  runs: queued
        워커가 집음(FOR UPDATE SKIP LOCKED — 동시 워커 안전)  →  running (started_at)
        스텝 순서대로 실행, 각 스텝: 재시도 → 성공(ok) / optional 이면 skipped / 아니면 failed
        onError=stop 이면 첫 failed 에서 중단, continue 면 끝까지
        스텝 사이마다 '취소 요청' 확인 → 있으면 canceled 로 종료(진행 중 스텝은 끝까지)
  →  ok / failed / canceled (ended_at, error, summary{steps, ok, failed, skipped, artifacts, ai 토큰, diff})

8. AI 가 하는 일 / 하지 않는 일

하는 일모델어떻게
초안 작성 — "이 사이트 로그인해서 KPI 뽑아 텔레그램" → 9스텝claude-sonnet-5DSL 규칙을 시스템 프롬프트로 주고 JSON 만 받음. 결과는 zod 로 검증, 저장은 사람이
요소 찾기 힐링 — 셀렉터·글자로 못 찾을 때 후보 중 선택claude-haiku-4.5후보 목록(글자·태그·name·id)만 전달. 입력값·비밀번호는 후보에 넣지 않음
구조화 추출 — 대시보드 텍스트에서 {daily, monthly, orders}claude-haiku-4.5페이지 본문 텍스트(최대 12,000자) + 스키마

하지 않는 일: 실행 순서를 즉흥적으로 바꾸지 않습니다. 스텝은 결정적이고, AI 는 "찾기·읽기·초안"에만 관여합니다. 그래서 같은 플로우는 같은 순서로 같은 행동을 하고, 문제가 생기면 어느 스텝인지 정확히 짚을 수 있습니다.

비용 감각: 초안 1회 ≈ 3~6원, 힐링 1회 ≈ 0.5원, ai_extract 1회 ≈ 3원(haiku). 실행 요약(summary.ai)에 토큰이 기록되어 플로우별 비용을 알 수 있습니다.


제안 셀렉터를 플로우에 반영하기

AI 힐링으로 요소를 찾은 스텝은 실행 상세에 "AI 로 찾음"과 함께 제안 셀렉터가 표시됩니다. [이 셀렉터로 플로우 고치기] 버튼을 누르면 그 스텝의 target 만 바뀌어 저장되므로(PATCH /api/flows/:id/steps/:stepId), 다음 실행부터는 AI 를 부르지 않고 바로 찾습니다. 힐링은 응급처치, 반영은 완치입니다.


9. 보안과 데이터


10. 서버 모드와 PC 에이전트 모드 — 왜 둘 다인가

서버(헤드리스)PC 에이전트
실행 위치우리 서버(고정 IP, 24시간)고객 사무실 PC(사람 세션)
잘 맞는 대상공개 웹·일반 로그인 사이트·우리 서비스들사내망/VPN 전용, IP 화이트리스트, OTP·인증서 로그인, "이미 로그인돼 있는" 브라우저
스케줄워커가 24시간PC 가 켜져 있을 때(트레이 상주)
만들기AI 초안 + 편집기녹화(사람이 한 번 시연) 또는 편집기
상태Phase 1 완료Phase 2 — 앱 코어·녹화기 완료, 실기기 페어링·실행 검증 1회, 허브 [에이전트] 화면 완성

두 모드가 같은 플로우 파일을 실행한다는 점이 핵심입니다. 서버에서 만들고 시험한 플로우를 모드만 바꿔 PC 로 보낼 수 있습니다.

PC 에이전트 쓰는 순서 (허브 [에이전트] 화면)

  1. 설치 파일 받기 — 화면 상단 Windows / macOS 카드에서 버전·크기·빌드 시각·sha256 을 확인하고 내려받습니다. 서명 없는 설치 파일이라 Windows SmartScreen 이 막으면 [추가 정보] → [실행]. 카드가 "준비 중" 이면 아직 빌드가 올라오지 않은 것입니다.
  2. 페어링 — 이름을 적고 [페어링 코드 발급] → 6자리 코드(10분 유효, 1회용)를 PC 앱에 입력합니다. 잠시 뒤 목록의 상태가 온라인 으로 바뀝니다.
  3. 상태 읽기 — 온라인(2분 안에 접속) · 유휴(1시간 안에 접속) · 오프라인. 앱이 켜져 있으면 3~5초마다 허브에 들르므로 늘 온라인입니다. 이름은 연필 아이콘으로 바꾸고, PC 를 바꾸거나 회수할 때는 [연결 해제](앱은 즉시 401, 진행 중 실행은 그대로).
  4. 플로우에 PC 배정 — 플로우 편집에서 실행 위치를 PC 에이전트 로 두면 "실행할 PC" 드롭다운이 나옵니다. 아무 PC(먼저 가져가는 앱) 또는 특정 PC. 배정한 PC 가 오프라인이면 [지금 실행] 옆에 경고가 뜨고, 실행은 큐에서 그 PC 가 켜질 때까지 기다립니다.
  5. 어느 PC 가 했나 — 실행 이력의 PC 열과 실행 상세 헤더의 "실행 PC: 이름(os)". 앱이 실행 도중 꺼져 10분 넘게 보고가 없으면 워커가 그 실행을 실패(에이전트 응답 없음) 로 정리하므로 영원히 "실행 중" 으로 남지 않습니다.

11. 실제 활용 시나리오

  1. 구매대행 정산 — 매일 08:37 오픈마켓 판매자센터 로그인 → 정산 예정 표 CSV → 텔레그램 "오늘 정산 N건 M원". (F2 데모가 이 골격)
  2. 경영 아침 보고 — 여러 시스템(ERP·광고·애널리틱스)의 KPI 를 순서대로 방문해 ai_extract 로 숫자만 뽑아 한 줄 요약. (F1 데모)
  3. 병원 접수 데스크 — 예약 플랫폼 5곳 새 접수 확인·수락 → 접수 표 추출 → 담당자 알림. 2FA 플랫폼은 PC 에이전트로.
  4. 경쟁사 가격 모니터 — 상품 URL 목록을 돌며 가격 텍스트 추출 → 어제 산출물과 비교(Phase 1.5 diff) → 변동만 알림.
  5. 세금계산서·거래명세 수집 — 월초 포털 로그인 → 기간 설정 → 엑셀 다운로드 → 산출물 보관(증빙 스샷 포함).
  6. 재고 동기화 — 공급사 B2B 사이트 재고 표 → CSV → (웹훅) 우리 몰 재고 API 로 반영.
  7. 사이트 헬스 체크 — 운영 중인 16개 서비스의 핵심 화면 방문 + 로그인 흐름 실행 → 실패만 알림(F3 데모의 확장).
  8. 광고 리포트 — 광고 관리자에서 기간 리포트 다운로드 → 스프레드시트 append(Phase 1.5).
  9. 데이터 이관 — 구 시스템 화면에서 목록 추출 → 새 시스템 입력 폼에 type 으로 채워 넣기(수백 건 반복은 loop, Phase 1.5).
  10. 채용·행정 포털 — 지원자 목록 다운로드, 공공 포털 공고 확인 등 "로그인 + 표 + 다운로드" 패턴 전부.

12. 상품화 관점 (우리가 파는 방식)


13. 로드맵과 현재 상태

Phase내용상태(2026-09-20)
1Hub 5화면, DSL v1 12스텝, 서버 러너, 금고, 스케줄러, AI 초안·힐링·추출, 텔레그램, 데모 F1~F3완료·운영 중
1.5loop 스텝, Google Sheets append(sheet_append), 웹훅 트리거, 실행 간 diff, 취소, 실패 지점부터 재실행, 제안 셀렉터 원클릭 반영, 에이전트용 locate API — 러너·DSL·편집기·실행 상세 확장 + npm test완료·운영 중(2026-09-19 배포)
2PC 에이전트(Electron): 페어링·로컬 실행·트레이·녹화기·설치 파일코어(A001)·녹화기(A002) 완료·병합. Windows 설치 파일은 https://flow.starplan.one/downloads/latest.json 이 가리키는 파일(A003 진행 중, 실기기 페어링·실행 검증 1회 성공). 허브 [에이전트] 화면(AF103, 2026-09-20): 설치 파일 카드·온라인 판정·이름 바꾸기·연결 해제·플로우↔PC 배정·실행 PC 표시·무응답 정리
2.5에이전트에서도 AI 힐링(허브 경유)이후
3멀티테넌트(조직·사용자·권한), 사용량 과금, 템플릿 마켓상품화 단계

14. 용어집