특수 제품군: CanonWorks, Manus, 노드

핵심 오케스트레이션 기능을 넘어, Operator MCP에는 Revka를 도메인 플랫폼으로 전환하는 전문 목적 도구 제품군이 포함되어 있습니다. 연재 소설 세계관 관리자, 실시간 웹 리서치 브리지, 이미지 생성, 실시간 대시보드 캔버스, 원격 하드웨어 레지스트리가 제공됩니다. 각 기능은 에이전트가 채팅에서 직접 호출하거나 워크플로 단계에 연결할 수 있는 Operator MCP 도구로 노출됩니다. 이 페이지는 다섯 가지 기능 모두에 대한 레퍼런스입니다.

아래의 모든 도구는 Operator MCP 서버에 존재하므로 오퍼레이터가 설치되어 실행 중이어야 합니다. 설정 방법은 Operator MCP를, 사전 요구 사항은 Python MCP 사이드카 설치를 참조하십시오.

CanonWorks: 연재 소설 세계관 관리

CanonWorks는 연재 소설의 캐릭터, 타임라인, 관계, 스토리라인, 복선 등을 Kumiho 그래프 프로젝트로 관리합니다. 시리즈를 초기화한 후에는 에피소드 팩토리 워크플로를 실행하여 새 에피소드를 작성하고, 스테이트 싱크 워크플로를 통해 스토리가 성장함에 따라 세계관의 일관성을 유지합니다. 주로 한국 웹소설 제작을 위해 설계되었으므로 기본 언어는 ko-KR이고 기본 연재 주기는 web_serial입니다.

시리즈 설정

두 가지 방법이 있습니다. 한 번에 초기화하는 프로그래밍 방식과, 그래프를 미리 확인한 후 커밋하는 대화형 인터뷰 방식입니다.

한 번에 초기화

canonworks_init은 단일 호출로 전체 프로젝트를 빌드합니다. Kumiho 스페이스, 세계관 번들, 초기 시리즈/캐릭터/관계/타임라인 항목, 아티팩트, 그래프 엣지를 생성한 다음 워크플로가 사용하는 project_config_yaml을 반환합니다.

{
  "title": "Quantum Soul",
  "project": "quantum-soul",
  "story_slug": "quantum-soul",
  "premise": "A courier discovers her implant hosts a dead AI.",
  "language": "ko-KR",
  "cadence": "web_serial",
  "target_length": "6000",
  "characters": [
    { "id": "rin", "name": "Rin", "role": "protagonist", "summary": "..." }
  ],
  "relationships": [
    { "from": "rin", "to": "the-ai", "type": "hosts", "label": "..." }
  ]
}

title만 필수입니다. 그 외 항목(project, story_slug)은 제목의 슬러그를 기본값으로 사용합니다.

대화형 인터뷰

가이드 방식의 설정을 원한다면 인터뷰 도구를 순서대로 사용하십시오.

1. canonworks_start(seed?, answers?, project_name?) — 설정 인터뷰를 시작하거나 재개합니다. Kumiho 프로젝트와 스페이스를 스캐폴딩하고(defer_kumiho_scaffold: true를 전달하면 드라이 런), 스토리 시드 답변을 수집한 후 다음 질문을 합니다.

2. canonworks_preview(session_id?, seed?, answers?) — Kumiho를 변경하지 않고 스페이스, 번들, 항목, 아티팩트, 관계 엣지를 미리 확인합니다.

3. canonworks_commit(session_id?, allow_incomplete?) — 내부적으로 canonworks_init을 호출하여 초안을 커밋하고, 나중에 실행 도구가 내부 설정 경로를 필요로 하지 않도록 project_config_artifact_path를 저장합니다.

제작 워크플로 실행

프로젝트가 커밋된 후에는 두 가지 도구로 지속적인 제작을 진행합니다. 두 도구 모두 project_config_yaml 처리를 내부에서 수행합니다. session_id(또는 project + story_slug)를 전달하면 나머지는 자동으로 해결됩니다.

도구	실행 워크플로	주요 입력
canonworks_run_episode	canonworks-serial-episode-factory	episode_goal, target_length, must_include, avoid, continuity_context, pacing_mode, initial_episode_number
canonworks_sync_state	canonworks-serial-canon-state-sync	apply_mode, review_focus, target_episode_number, target_episode_kref, bootstrap_mode

이 도구들은 동일한 이름의 내장 워크플로에 매핑됩니다. 전체 목록과 내장 워크플로의 구조에 대해서는 내장 워크플로 및 오케스트레이션 패턴을 참조하십시오.

팁

CanonWorks 도구는 세계관을 플랫 파일이 아닌 그래프에 유지함으로써, 몇 달 간격으로 생성된 에피소드도 일관성을 유지합니다. 새로 작성된 에피소드를 세계관 상태와 동기화하는 것이 바로 싱크 워크플로의 역할입니다.

Manus 웹 리서치 연동

manus_create_task는 Manus 호스팅 웹 에이전트에서 임시 리서치 작업을 실행합니다. Manus는 실시간 브라우징과 구조화된 데이터 추출을 위한 실제 브라우저 접근 권한을 갖추고 있습니다. 모델의 학습 데이터보다 실시간 웹 검색이 유리한 질문이 있을 때 대화 중간에 활용하십시오. 이 도구는 manus: 워크플로 단계 타입과 동일하게 동작하며 동일한 인증 우선순위를 공유합니다.

{
  "prompt": "Find the three most-cited papers on graph memory published in 2025, with links.",
  "structured_output_schema": {
    "type": "object",
    "properties": { "papers": { "type": "array" } }
  },
  "agent_profile": "manus-1.6",
  "timeout_seconds": 600,
  "credentials_ref": "manus:work"
}

필드	타입	기본값	설명
prompt	string	(필수)	Manus에 전달할 리서치 프롬프트.
structured_output_schema	object	—	Manus가 채울 JSON 스키마. 설정 시 결과에 structured_output이 포함됩니다.
connectors	string[]	—	연결할 Manus 커넥터 ID (예: google_drive).
agent_profile	string	manus-1.6	Manus 에이전트 프로필 ID.
timeout_seconds	integer	600	작업 폴링의 최대 시간(초).
poll_interval_seconds	integer	5	폴링 호출 간격(초).
credentials_ref	string	—	인증 프로필 ID (예: manus:work). 설정하지 않으면 MANUS_API_KEY 환경 변수로 폴백됩니다.

인증 우선순위는 다음과 같습니다. credentials_ref 인증 프로필을 먼저 사용하고, 없으면 MANUS_API_KEY 환경 변수로 폴백합니다. 작업은 task_id, task_url, final_state, 어시스턴트 메시지, attachments, 선택적 structured_output을 반환합니다.

주의

manus_create_task는 결과를 자동으로 저장하지 않습니다. 결과를 그래프에 저장하려면 kumiho_create_item을 별도로 호출하십시오. Kumiho 메모리 도구를 참조하십시오.

이미지 생성 (Codex CLI 사용)

generate_image_codex는 OpenAI Codex CLI의 내장 image_generation 도구를 사용하여 PNG 이미지를 생성합니다. 한 번의 호출로 최대 5장의 이미지를 병렬로 생성할 수 있으며(asyncio.gather를 통한 독립적인 Codex 세션), 더 많은 이미지가 필요할 경우 배치 단위로 반복 호출하십시오. 선택적으로 Live Canvas에 갤러리 프레임을 푸시하고 각 PNG를 Kumiho 아티팩트로 등록할 수 있습니다.

{
  "prompt": "A fox in a forest, cinematic lighting",
  "output_path": "fox.png",
  "count": 3,
  "canvas": true,
  "space": "Marketing/Logos"
}

필드	타입	기본값	설명
prompt	string	(필수)	생성할 이미지에 대한 설명.
output_path	string	(필수)	절대 경로가 아닌 경우 cwd 기준의 대상 PNG 경로. count > 1이고 output_pattern이 없으면 <stem>-N.<ext> 형식으로 확장됩니다.
cwd	string	~/.revka/workspace	Codex 작업 디렉터리.
count	integer (1–5)	1	병렬로 생성할 이미지 수.
output_pattern	string	—	{n} 플레이스홀더가 포함된 파일명 템플릿 (예: logo-{n}.png).
input_images	string | string[]	—	codex exec --image에 참조로 전달할 로컬 이미지 경로. 프롬프트 내의 [IMAGE:/path] 마커도 자동으로 추출됩니다.
canvas	bool | string	false	true이면 기본 캔버스에 갤러리 프레임을 푸시하며, 문자열을 전달하면 해당 canvas_id를 사용합니다.
register_artifact	bool	true	<harness>/<space> 아래에 Kumiho 항목 + 리비전을 생성하고 각 PNG를 첨부합니다.
space	string	Images	Kumiho 스페이스 (하네스 프로젝트 기준). Marketing/Logos와 같은 다중 세그먼트 경로를 지원합니다.
item_name	string	(파일명 스템)	Kumiho 항목의 이름.
sandbox	enum	(자동)	Codex --sandbox 모드: read-only, workspace-write, danger-full-access.

결과 확인

응답에는 대시보드에서 로드할 수 있는 서명된 /workspace/... URL 배열(urls[])과 절대 파일시스템 경로 배열(files[])이 포함됩니다. 직접 HTML이나 캔버스 출력을 구성할 때는 urls[]를 참조하십시오. 브라우저 샌드박스는 원시 파일시스템 경로를 읽을 수 없습니다. 서명된 URL은 게이트웨이의 워크스페이스 에셋 서빙을 통해 생성되므로 터널을 통해서도 동작합니다.

참고

사전 요구 사항 및 주의 사항. 이 도구를 사용하려면 codex CLI가 설치되어 있고 ChatGPT OAuth로 인증되어 있어야 합니다(최신 image_generation 기능을 사용하려면 v0.128 이상 권장). sandbox는 플랫폼에 따라 자동 선택됩니다. macOS/Linux 및 관리자 권한으로 설치된 Windows에서는 workspace-write가 사용되지만, Windows 사용자 설치 npm(%APPDATA%\npm\codex.CMD)에서는 샌드박스 헬퍼가 자식 프로세스를 생성할 수 없어 danger-full-access가 사용됩니다. 이 경우 Codex의 이미지 스킬이 로드되지 않아 PNG가 생성되지 않습니다. canvas: true를 전달하면 이 도구가 이미 작동하는 프레임을 푸시하므로, 동일한 이미지에 대해 render_canvas를 추가로 호출하면 중복이 발생합니다.

Codex CLI 연동에 대한 자세한 내용은 코드 에이전트, 위임 및 파이프라인을 참조하십시오.

Live Canvas 렌더링

Live Canvas는 에이전트가 렌더링한 콘텐츠(HTML, SVG, Markdown, 일반 텍스트)를 실시간으로 대시보드의 Canvas 페이지에 푸시합니다. 여러 개의 명명된 캔버스를 지원하며, 대시보드는 최신 프레임을 표시하고 모든 WebSocket 구독자는 새 프레임을 즉시 수신합니다.

Operator 도구

도구	파라미터	용도
render_canvas	content (필수), content_type (html | svg | markdown | text, 기본값 html), canvas_id (기본값 default)	캔버스에 프레임을 푸시합니다.
clear_canvas	canvas_id (기본값 default)	캔버스와 프레임 히스토리를 지웁니다.

{
  "content": "<svg viewBox='0 0 100 100'><circle cx='50' cy='50' r='40'/></svg>",
  "content_type": "svg",
  "canvas_id": "default"
}

게이트웨이 엔드포인트 및 실시간 업데이트

동일한 캔버스 시스템이 구독 브라우저 및 외부 호출자를 위해 게이트웨이를 통해 노출됩니다. 대시보드는 WebSocket으로 구독하며, REST로도 캔버스를 제어할 수 있습니다.

ws://host:port/ws/canvas/<canvas_id>?token=<bearer>

연결 시 게이트웨이는 현재 스냅샷(있는 경우)을 전송한 다음 {"type":"connected","canvas_id":"..."}를 보냅니다. 새 콘텐츠는 {"type":"frame","canvas_id":"...","frame":{}}로 도착합니다. 브로드캐스트 링 버퍼에서 뒤처진 느린 구독자는 {"type":"lagged","missed_frames":N}을 수신합니다.

메서드	경로	인증	용도
GET	/api/canvas	Bearer	활성 캔버스 ID 목록 조회
GET	/api/canvas/:id	Bearer	현재 스냅샷 조회
GET	/api/canvas/:id/history	Bearer	프레임 히스토리 조회
POST	/api/canvas/:id	루프백: 없음 / 외부: Bearer	프레임 푸시
DELETE	/api/canvas/:id	루프백: 없음 / 외부: Bearer	캔버스 지우기

POST 바디는 도구와 동일한 형식을 사용합니다.

{ "content_type": "html", "content": "<h1>Live status</h1>" }

주의

콘텐츠 타입은 허용 목록에 대해 유효성이 검사되며(eval 제외), 크기 제한을 초과하는 콘텐츠는 HTTP 413을 반환합니다. 캔버스 레지스트리에는 용량 제한이 있습니다. {"type":"error","error":"Maximum canvas count reached"}가 발생하면 새 캔버스를 생성하기 전에 DELETE /api/canvas/:id로 기존 캔버스를 삭제하십시오.

전체 실시간 인터페이스는 실시간: WebSocket, SSE 및 Live Canvas를 참조하십시오. 대시보드 측면은 에이전트, 팀 및 캔버스를 참조하십시오.

원격 노드 (하드웨어 / IoT)

원격 노드는 WebSocket을 통해 게이트웨이에 연결하고 기능을 광고하는 외부 프로세스입니다(예: 스마트폰, 센서, IoT 기기, 원격 머신). 광고된 각 기능은 동적으로 사용 가능한 에이전트 도구가 되며, 게이트웨이는 호출을 해당 노드로 디스패치합니다.

Operator 도구

도구	파라미터	용도
list_nodes	(없음)	연결된 노드와 해당 기능 목록을 조회합니다.
invoke_node	node_id (필수), capability (필수), args (기본값 {})	노드의 기능을 호출합니다.

노드가 노출하는 기능을 먼저 파악하기 위해 항상 list_nodes를 먼저 호출한 다음 기능을 호출하십시오.

{ "node_id": "phone-1", "capability": "camera.snap", "args": {} }

노드 연결

노드는 WebSocket을 통해 게이트웨이의 동적 노드 레지스트리에 연결하고 기능을 등록합니다.

ws://host:port/ws/nodes?token=<bearer>

서브 프로토콜: revka.nodes.v1. 노드는 register 프레임을 전송하고, 게이트웨이는 registered로 응답합니다.

{
  "type": "register",
  "node_id": "phone-1",
  "capabilities": [
    {
      "name": "camera.snap",
      "description": "Capture a photo from the rear camera",
      "parameters": { "type": "object", "properties": {} }
    }
  ]
}

에이전트가 기능을 호출하면 게이트웨이는 call_id, capability, args가 포함된 invoke 프레임을 노드에 전송합니다. 노드는 result 프레임(call_id, success, output, 선택적 error)으로 응답합니다. 기능 parameters는 JSON Schema 객체이며, 기본값은 {"type":"object","properties":{}}입니다.

인증 및 수명 주기:

• 설정에서 노드별 auth_token이 우선 적용되며, 노드 토큰이 설정되지 않은 경우 게이트웨이는 표준 페어링 가드로 폴백합니다.
• node_id는 1~128자이어야 합니다. 동일한 node_id로 재등록하면 기존 항목이 업데이트됩니다.
• 레지스트리에는 설정 가능한 max_nodes 용량이 있습니다. WebSocket 연결이 닫히면 노드는 자동으로 등록 해제됩니다.

전체 노드 프로토콜과 기능 이름이 에이전트 도구가 되는 방식에 대해서는 실시간: WebSocket, SSE 및 Live Canvas 및 하드웨어 퀵스타트를 참조하십시오.

관련 문서

Operator MCP 이 모든 도구를 호스팅하는 서버를 설치하고 실행합니다.

워크플로 단계 타입 선언적 워크플로에서 manus, image, canvas 단계를 사용합니다.

실시간 게이트웨이 API 캔버스와 노드를 위한 WebSocket 및 REST 인터페이스.

Kumiho 그래프 메모리 CanonWorks 및 이미지 아티팩트가 저장되는 그래프.