Morit Plugin6. 검증과 배포

오류 해결

오류를 catch로 숨기기 전에 어느 경계에서 발생했는지 구분합니다.

빠른 진단 순서

text

source를 읽을 수 있는가
  → validate가 성공하는가
  → preview artifact가 생기는가
  → signed build와 reopen이 성공하는가
  → API 인증과 목록 조회가 성공하는가
  → 설치 상태가 active인가
  → Connection과 권한이 ready인가
  → capability가 실행되는가
  → UI가 결과를 렌더링하는가

앞 단계가 실패한 상태에서 다음 단계 오류를 우회하지 않습니다.

Validate 오류

증상	확인 항목
unknown field	문서에 없는 key 제거, v1/v2 필드 혼합 여부
duplicate ID	manifest 배열과 모든 fragment를 함께 검색
unknown permission	지원 목록과 Manifest 전역 권한 확인
capability reference	UI, Slash Command, child dependency 대상 ID 확인
state/data binding	`initial_state`, `data_sources`, `item` scope 확인
source entrypoint	각 `src/*.py`와 `sandbox_python` 1:1 확인
image asset	`assets/` 경로·확장자·실제 파일 확인

진단에 표시된 첫 오류부터 고치고 다시 validate합니다. 허용 필드를 늘리거나 unknown key를 무시하게 바꾸지 않습니다.

Preview 오류

preview 전에 validate가 실행됩니다. artifact가 없으면 출력 디렉터리 권한과 source size를 확인합니다. preview가 열려도 실제 앱의 typography, navigation, scroll, async state는 별도 검증 대상입니다.

Build·signature 오류

output 확장자가 .mplg인지 확인합니다.
package가 2 MiB, 64 entry 한도 안인지 확인합니다.
private key 파일 권한과 publisher identity를 확인합니다.
source ZIP을 .mplg로 이름만 바꾸지 않았는지 확인합니다.
verify가 반환한 plugin ID, publisher, version, SHA-256을 기록합니다.
trusted publisher에 등록된 key와 embedded public key가 다른 경우 올바른 조직 key로 다시 build합니다.

목록 조회와 설치 오류

Not Found는 URL 이동으로 해결하지 않습니다. API base URL, 배포 route, 인증 header, 사용자 RLS를 확인합니다. 401은 endpoint가 없다는 뜻이 아니라 인증이 필요하다는 뜻입니다.

설치 뒤 목록 조회가 실패했다가 재시도에서 duplicate가 나오면 package file, Installation row, default Instance, cache가 하나의 atomic transaction으로 정리되는지 확인합니다. 앱 데이터 삭제만으로 서버 DB와 외부 저장소는 삭제되지 않습니다. 사용자별 API 목록과 서버 package store를 함께 확인합니다.

정상 duplicate는 같은 plugin ID·publisher·version 정책으로 판단하고 파일명만 사용하지 않습니다.

Connection 오류

상태	의미	사용자 동작
`not_configured`	필수 Connection/Secret 없음	계정 연결 또는 Developer Secret 설정
`unavailable`	provider·암호화·runtime 사용 불가	운영 설정 확인
credential rejected	token 만료·철회	한 번 refresh 후 다시 연결
rate limited	Connector 한도 초과	제한된 시간 뒤 재시도

token을 로그에 출력해 진단하지 않습니다. 연결 metadata와 공개 오류 코드만 사용합니다.

Capability 오류

permission required: Manifest와 capability 권한, 사용자 grant 확인
disabled/incompatible: Instance state와 Morit version 확인
timeout: capability timeout과 Connector timeout을 비교하고 작업을 작게 나눔
retryable network: Connector의 bounded retry만 사용
invalid response: summary, data, evidence 형태와 외부 response mapping 확인
code worker unavailable: broker/worker health와 lease 확인; Archive process에서 직접 실행하지 않음

Tool 하나의 실패가 AI 요청 전체 실패를 뜻하지 않는 경우 대체 Tool·부분 결과·재연결을 시도하고 최종 답변에 남은 제한을 설명합니다.

UI 오류

해당 extension만 fallback되고 대화·앱 전체가 계속 동작하는지 확인합니다.
없는 state/data/route를 참조하지 않는지 확인합니다.
list/timeline child가 정확히 하나인지 확인합니다.
surface가 children을 가지는지 확인합니다.
positioned는 stack, expanded는 row/column 안인지 확인합니다.
literal image URL 대신 capability result binding을 사용했는지 확인합니다.
원격 이미지가 안 보이면 Manifest와 활성 Instance의 network 권한, public HTTPS 여부를 먼저 확인합니다. redirect, MIME/magic 불일치, 손상된 파일, 512 KiB 또는 가로·세로 4096 px 초과는 Host가 의도적으로 차단합니다. 애니메이션은 최대 128 frame이고 width × height × frame 수로 계산한 frame 합산 pixel이 16,000,000 이하여야 합니다.
원격 이미지 실패를 앱 직접 fetch나 임의 외부 URL widget으로 우회하지 않습니다.
Response UI가 원래 AI 메시지 안의 한 container에 붙는지 확인합니다.
Response UI가 안 보이면 config.a2ui.version이 v0.9인지, schema가 실제 완료 데이터와 맞는지, response의 data source가 실행 capability를 가리키는지, Instance 권한이 승인됐는지 확인합니다.
빈 데이터·무관한 답변·중복 결과·Tool 실패에서 Response UI가 생기지 않는 것은 정상입니다. AI가 catalog 항목을 선택하지 않은 경우에도 서버가 임의 fallback UI를 만들지 않고 텍스트만 남깁니다.

MCP 오류

Local MCP:

bash

node --version
npx -y @morit/plugin-mcp
codex mcp list

Remote MCP:

bash

curl -i https://morit-api.moring.co/mcp

인증 전 401과 WWW-Authenticate는 정상 OAuth 시작 신호입니다. 404는 ingress route, 5xx는 MCP service health와 server log를 확인합니다. Codex에서는 codex mcp login <name>, Tool 목록에서는 morit_sdk_contract와 morit_docs_search를 먼저 확인합니다.