[ AIWK 전체 로직설명 v1.0 ]

DOM부터 nodered flow ,서로 연동  인증 방식까지 체계까지 전체 한눈에 알수있게 프로토콜  전체 방향 큰그림 부터.  현재와  상세 향후까지 정의하고 그것을 보면 AI가 한번에 알고 HTML코드 분석후 FLOW작성가능하게
7s 동안 생각함

결론: AIWK 프로토콜은 “HTML/DOM 분석 → EXT 실행 → WSS 라우팅 → Node-RED Flow 처리 → 결과 반환”을 하나의 표준 규약으로 고정해야 합니다.
이 문서를 기준으로 잡으면, 앞으로 AI가 HTML 코드를 보고 자동으로 Node-RED Flow JSON까지 작성할 수 있습니다.

아래 내용은 앞으로 docs/aiwk_protocol_v001.md 기준 문서로 삼으면 됩니다.

AIWK Protocol v0.1 전체 큰그림
1. AIWK 최종 구조
[브라우저 DOM]
   ↑↓
[AIWK_EXT2]
   ↑↓ WSS
[AIWK_HUB 중앙 서버]
   ↑↓ WSS
[Local Node-RED]
   ↑↓
[node-red-contrib-aiwk]
   ↑↓
[MySQL / HTTP / 파일 / AI API / 다른 PC / 다른 탭]

역할은 이렇게 고정합니다.

AIWK_EXT2
- 현재 브라우저 탭의 DOM 읽기/쓰기/클릭
- 선택자 분석
- 현재 탭 상태 보고
- WSS 메시지 수신/실행/결과 반환

Node-RED
- Flow 작성/실행
- 순차 자동화
- 조건 분기
- DB/API/파일/스케줄 처리
- AIWK 명령 생성

node-red-contrib-aiwk
- Node-RED와 AIWK_EXT2/WSS를 연결하는 팔레트 노드

AIWK_HUB
- WSS 중계
- 인증
- client 라우팅
- room/project 관리
- 향후 shared flow 저장소

Native Host
- Chrome EXT와 로컬 node.exe/Node-RED 연결
- Node-RED 실행/상태 확인
- 로컬 파일/설치 자동화
2. 현재 완료 상태

현재 완료된 것:

v006
- EXT → Native Host 연결 성공
- Native Host → node.exe 확인 성공
- Native Host → Local Node-RED 상태 확인 성공
- Node-RED 자동 시작 구조 성공
- WSS 접속 성공

v007
- node-red-contrib-aiwk 설치 성공
- aiwk-config 노드 생성 성공
- aiwk-in 노드 생성 성공
- aiwk-out 노드 생성 성공
- aiwk-debug 노드 생성 성공
- Node-RED에서 WSS 송수신 1차 성공

현재 다음 단계:

v008
- AIWK_EXT2가 WSS 메시지를 직접 수신
- to 주소와 endpoint 판별
- dom.readText 실행
- dom.writeText 실행
- dom.click 실행
- 결과를 Node-RED aiwk-in으로 반환
3. 주소 체계

모든 AIWK 통신 주소는 이 형식으로 고정합니다.

group.project.room.client#endpoint

예:

home.IG_CRM.RE5ay2jRmY.A4#node-red
home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab
home.IG_CRM.RE5ay2jRmY.A2#chat.write
home.IG_CRM.RE5ay2jRmY.A2#read.result
구성 요소
group
- 큰 그룹
- 예: home

project
- 프로젝트명
- 예: IG_CRM

room
- 통신방
- 예: RE5ay2jRmY

client
- 접속자 ID
- 예: A1, A2, A4, B1

endpoint
- client 내부의 실제 실행 대상
- 예: node-red, ext.activeTab, chat.write, dom.read

중요 규칙:

WSS 서버는 group.project.room.client까지만 라우팅한다.
client 내부에서는 #endpoint를 보고 실행 대상을 결정한다.
4. 현재 프로젝트 기준 주소

현재 기준값:

group   = home
project = IG_CRM
room    = RE5ay2jRmY
Node-RED client = A4
EXT target client = A2

따라서 표준 주소:

Node-RED:
home.IG_CRM.RE5ay2jRmY.A4#node-red

A2 현재 탭:
home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab

잘못된 주소 예:

home.IG_CRM.A2#

이건 room도 빠졌고 endpoint도 비어 있으므로 앞으로 쓰지 않습니다.

5. endpoint 표준
현재 v008 우선 endpoint
#node-red
#ext.activeTab
의미
#node-red
- Node-RED 자체 수신 endpoint

#ext.activeTab
- 해당 client의 현재 활성 브라우저 탭
- DOM 읽기/쓰기/클릭 명령을 우선 여기로 보냄
향후 endpoint
#ext.tab.{tabId}
#dom.read
#dom.write
#chat.write
#chat.send
#read.result
#selector
#pocket.text
#pocket.result
#replay
#file

v008에서는 #ext.activeTab 하나로 시작하고, 기능이 늘어나면 endpoint를 세분화합니다.

6. 기본 메시지 패킷

모든 AIWK 메시지는 아래 형식을 따릅니다.

{
  "msg_id": "m_1001",
  "from": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "to": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "action": "dom.readText",
  "payload": {
    "selector": "body"
  },
  "need_ack": false,
  "need_result": true,
  "timeout_ms": 10000,
  "ts": 1770000000000
}

필드 정의:

msg_id
- 메시지 고유 ID
- 요청/응답 추적용

from
- 보낸 쪽 전체 주소

to
- 받을 쪽 전체 주소

action
- 실행할 동작명

payload
- action에 필요한 데이터

need_ack
- 수신 확인 필요 여부

need_result
- 실행 결과 필요 여부

timeout_ms
- 결과 대기 시간

ts
- 보낸 시각 timestamp
7. 표준 action
공통 action
aiwk.message
aiwk.ack
aiwk.result
aiwk.error
DOM action
dom.readText
dom.writeText
dom.click
dom.getValue
dom.setValue
dom.getHtml
dom.exists
dom.waitSelector

v008 1차는 아래 3개만 구현합니다.

dom.readText
dom.writeText
dom.click
상태 action
status.ping
status.pong
status.online
status.offline
Link action
link.call
link.return
link.error
8. DOM 요청/응답 규약
dom.readText 요청
{
  "msg_id": "m_1001",
  "from": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "to": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "action": "dom.readText",
  "payload": {
    "selector": "#prompt-textarea"
  },
  "need_result": true,
  "timeout_ms": 10000
}
dom.readText 결과
{
  "msg_id": "m_1001_result",
  "reply_to": "m_1001",
  "from": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "to": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "action": "aiwk.result",
  "payload": {
    "ok": true,
    "action": "dom.readText",
    "selector": "#prompt-textarea",
    "text": "읽은 텍스트"
  },
  "ts": 1770000000000
}
dom.writeText 요청
{
  "msg_id": "m_1002",
  "from": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "to": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "action": "dom.writeText",
  "payload": {
    "selector": "#prompt-textarea",
    "text": "AIWK 테스트 입력"
  },
  "need_result": true,
  "timeout_ms": 10000
}
dom.writeText 결과
{
  "msg_id": "m_1002_result",
  "reply_to": "m_1002",
  "from": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "to": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "action": "aiwk.result",
  "payload": {
    "ok": true,
    "action": "dom.writeText",
    "selector": "#prompt-textarea"
  },
  "ts": 1770000000000
}
dom.click 요청
{
  "msg_id": "m_1003",
  "from": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "to": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "action": "dom.click",
  "payload": {
    "selector": "button[type='submit']"
  },
  "need_result": true,
  "timeout_ms": 10000
}
dom.click 결과
{
  "msg_id": "m_1003_result",
  "reply_to": "m_1003",
  "from": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "to": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "action": "aiwk.result",
  "payload": {
    "ok": true,
    "action": "dom.click",
    "selector": "button[type='submit']"
  },
  "ts": 1770000000000
}
9. 오류 규약

실패 시에는 반드시 aiwk.error로 반환합니다.

{
  "msg_id": "m_1003_error",
  "reply_to": "m_1003",
  "from": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "to": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "action": "aiwk.error",
  "payload": {
    "ok": false,
    "error": "selector not found",
    "selector": "button[type='submit']"
  },
  "ts": 1770000000000
}

오류 원칙:

selector가 없으면 자동 보정하지 않는다.
대상 endpoint가 없으면 offline/error를 반환한다.
실행 실패는 조용히 무시하지 않는다.
모든 실패는 aiwk.error로 명시한다.
10. ACK / RESULT 규약
ACK

need_ack=true이면 수신 즉시 ACK를 보냅니다.

{
  "msg_id": "m_1001_ack",
  "reply_to": "m_1001",
  "from": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "to": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "action": "aiwk.ack",
  "payload": {
    "ok": true,
    "received": true
  },
  "ts": 1770000000000
}
RESULT

실행 완료 후 결과는 aiwk.result로 보냅니다.

ack    = 메시지를 받았다
result = 실행이 끝났다
error  = 실행 실패
11. 인증 체계
현재 v007 기준

현재 인증은 aiwk-config에 있는 token을 사용합니다.

WSS URL
group
project
room
clientId
token

Node-RED 설정 예:

WSS URL  = wss://n.yjm.kr/aiwk/ws
Group    = home
Project  = IG_CRM
Room     = RE5ay2jRmY
ClientID = A4
Token    = ********

EXT 설정도 같은 체계를 사용합니다.

register 패킷

각 client는 WSS 연결 후 register를 보냅니다.

{
  "type": "register",
  "role": "node-red",
  "group": "home",
  "project": "IG_CRM",
  "room_id": "RE5ay2jRmY",
  "client_id": "A4",
  "token": "TOKEN_VALUE",
  "endpoint": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "ts": 1770000000000
}

EXT는 role을 이렇게 둡니다.

{
  "type": "register",
  "role": "ext",
  "group": "home",
  "project": "IG_CRM",
  "room_id": "RE5ay2jRmY",
  "client_id": "A2",
  "token": "TOKEN_VALUE",
  "endpoint": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "ts": 1770000000000
}
인증 원칙
1. token 없으면 제한 모드 또는 거부
2. group/project/room/client 범위를 token payload와 비교
3. allow_targets 범위 밖으로 보내면 거부
4. client_id 중복은 같은 room 안에서 제한
5. endpoint는 client 내부 권한으로 처리
12. 향후 권한 체계

향후 token payload는 아래 구조를 표준으로 합니다.

{
  "iss": "yyAIWK",
  "aud": "aiwk_ws",
  "group": "home",
  "project": "IG_CRM",
  "room_id": "RE5ay2jRmY",
  "client_id": "A4",
  "perm": "USER",
  "mcp_enabled": 1,
  "connect_targets": [
    "home.IG_CRM.RE5ay2jRmY.A4"
  ],
  "allow_targets": [
    "home.IG_CRM.RE5ay2jRmY.*"
  ],
  "exp_days": "30"
}

권한 의미:

connect_targets
- 이 token으로 접속 가능한 client 주소

allow_targets
- 이 client가 메시지를 보낼 수 있는 대상 범위

perm
- USER / PROJECT_ADMIN / ROOT 등 권한 등급

mcp_enabled
- MCP/실행 기능 사용 여부
13. Node-RED msg 변환 규칙
aiwk-out 입력 msg

Node-RED Flow 안에서는 아래처럼 msg를 구성합니다.

{
  "payload": {
    "selector": "#prompt-textarea"
  },
  "aiwk_to": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "aiwk_action": "dom.readText",
  "need_result": true,
  "timeout_ms": 10000
}

aiwk-out은 이것을 표준 AIWK 패킷으로 변환합니다.

aiwk-out이 만드는 패킷
{
  "msg_id": "nr_1770000000000_12345",
  "from": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
  "to": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
  "action": "dom.readText",
  "payload": {
    "selector": "#prompt-textarea"
  },
  "need_ack": false,
  "need_result": true,
  "timeout_ms": 10000,
  "ts": 1770000000000
}
aiwk-in 출력 msg

aiwk-in은 수신 패킷을 이렇게 Node-RED msg로 바꿉니다.

{
  "topic": "aiwk.result",
  "payload": {
    "ok": true,
    "text": "읽은 텍스트"
  },
  "aiwk": {
    "msg_id": "m_1001_result",
    "reply_to": "m_1001",
    "from": "home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab",
    "to": "home.IG_CRM.RE5ay2jRmY.A4#node-red",
    "action": "aiwk.result"
  }
}
14. Node-RED Flow 생성 규칙

AI가 Node-RED Flow JSON을 만들 때 반드시 지켜야 할 규칙:

1. aiwk-config를 반드시 포함한다.
2. group/project/room/clientId를 정확히 채운다.
3. aiwk-out의 to는 group.project.room.client#endpoint 전체 형식으로 쓴다.
4. endpoint를 빈 값으로 두지 않는다.
5. DOM 조작은 우선 #ext.activeTab으로 보낸다.
6. 결과가 필요한 DOM action은 needResult=true로 둔다.
7. aiwk-in은 aiwk.result / aiwk.error를 받을 수 있게 둔다.
8. debug 노드는 payload와 aiwk 전체를 확인할 수 있게 둔다.
9. room을 생략하지 않는다.
10. action은 표준 action 이름만 쓴다.
15. HTML 분석 후 Flow 작성 규칙

AI가 HTML 코드를 분석할 때는 아래 순서로 해야 합니다.

1단계: 대상 요소 추출

HTML에서 다음을 찾습니다.

입력창
전송 버튼
결과 영역
상태 표시 영역
반복 목록
로그 영역
2단계: selector 후보 생성

selector 우선순위:

1. id
2. data-testid / data-* 계열
3. name
4. aria-label
5. role + text
6. class 조합
7. nth-child는 최후 수단

좋은 selector 예:

#prompt-textarea
button[data-testid="send-button"]
textarea[name="message"]
[aria-label="Send message"]

나쁜 selector 예:

div > div > div:nth-child(3) > button
3단계: action 매핑
입력창 → dom.writeText
전송 버튼 → dom.click
결과 영역 → dom.readText
특정 요소 대기 → dom.waitSelector
4단계: Node-RED Flow 생성

예:

inject
  ↓
function: payload 구성
  ↓
aiwk-out: dom.writeText
  ↓
aiwk-out: dom.click
  ↓
aiwk-in: aiwk.result 수신
  ↓
debug
16. HTML 분석 결과 표준 출력 형식

AI가 HTML을 분석하면 먼저 이 표를 만들어야 합니다.

{
  "page": {
    "title": "대상 페이지",
    "url_pattern": "https://example.com/*"
  },
  "elements": {
    "input": {
      "selector": "#prompt-textarea",
      "action": "dom.writeText",
      "confidence": 0.95
    },
    "send_button": {
      "selector": "button[data-testid='send-button']",
      "action": "dom.click",
      "confidence": 0.9
    },
    "result_area": {
      "selector": ".result-text",
      "action": "dom.readText",
      "confidence": 0.85
    }
  },
  "flow_plan": [
    "dom.writeText",
    "dom.click",
    "dom.readText"
  ]
}

이 결과를 기준으로 Flow JSON을 생성합니다.

17. 기본 Flow 패턴
패턴 1: 텍스트 읽기
inject
  ↓
function: selector 지정
  ↓
aiwk-out: dom.readText
  ↓
aiwk-in: aiwk.result
  ↓
debug
패턴 2: 텍스트 쓰기
inject
  ↓
function: selector/text 지정
  ↓
aiwk-out: dom.writeText
  ↓
aiwk-in: aiwk.result
  ↓
debug
패턴 3: 쓰기 후 클릭
inject
  ↓
function: 입력 payload
  ↓
aiwk-out: dom.writeText
  ↓
delay
  ↓
function: 클릭 payload
  ↓
aiwk-out: dom.click
  ↓
aiwk-in
  ↓
debug
패턴 4: AI 채팅 전송
inject
  ↓
function: 메시지 생성
  ↓
aiwk-out: dom.writeText
  ↓
delay
  ↓
aiwk-out: dom.click
  ↓
delay
  ↓
aiwk-out: dom.readText
  ↓
aiwk-in
  ↓
MySQL 저장 / debug / 다음 Flow
18. 현재 v008에서 구현할 최소 범위

v008은 욕심내지 말고 아래만 합니다.

EXT WSS register
EXT WSS message receive
to 주소 매칭
#ext.activeTab endpoint 처리
dom.readText
dom.writeText
dom.click
aiwk.result 반환
aiwk.error 반환

v008에서 아직 하지 않을 것:

selector 자동 분석
chat.write 전용 endpoint
read.result 전용 endpoint
pocket 저장
replay 기록
다중 tab 지정
flow 공유 서버 저장
19. 향후 확장 단계
v009
dom.exists
dom.waitSelector
dom.getValue
dom.setValue
v010
chat.write
chat.send
read.result
selector.analyze
v011
pocket.text
pocket.result
pocket.selector
v012
link.call
link.return
다른 PC endpoint 호출
v013
shared flow
domain profile
server flow repository
v014
설치 자동화
portable node.exe
AIWK_EXT2 자동 등록
Native Host 자동 등록
token 발급/갱신
20. 최종 핵심 규칙
1. Node-RED는 Flow 작성/실행 담당이다.
2. EXT는 현재 브라우저 DOM 실행 담당이다.
3. WSS는 client까지 배달한다.
4. endpoint는 client 내부 기능을 지정한다.
5. 모든 메시지는 group.project.room.client#endpoint 주소를 가진다.
6. 모든 실행 결과는 aiwk.result 또는 aiwk.error로 반환한다.
7. AI는 HTML 분석 후 selector/action/flow_plan을 먼저 만들고 Flow JSON을 생성한다.
8. room과 endpoint는 절대 생략하지 않는다.
9. 자동 보정하지 말고 실패는 명시적으로 반환한다.
10. 현재 표준 DOM endpoint는 #ext.activeTab이다.

이 문서 기준으로 가면, 앞으로 AI에게 이렇게 시킬 수 있습니다.

이 HTML을 분석해서
AIWK Protocol v0.1 기준으로
Node-RED Flow JSON을 만들어라.
대상은 home.IG_CRM.RE5ay2jRmY.A2#ext.activeTab이고,
Node-RED는 home.IG_CRM.RE5ay2jRmY.A4#node-red이다.

그러면 AI가 selector를 잡고, action을 정하고, aiwk-out / aiwk-in / function / debug까지 포함된 Flow JSON을 만들 수 있습니다.