아키텍처 분석 · gosuda/flats v0.4.0

Flats ↔ 에이전트 연동 구조

에이전트는 Flats에 무엇으로 붙고, 어디까지 할 수 있으며, 어디서 사람이 반드시 개입하는가.

1. 전체 그림

에이전트 쪽에는 연결 정보만 있고, 기능과 규칙은 전부 Flats 호스트에 있어요. 아래 그림에서 왼쪽 파란 영역이 에이전트 머신, 오른쪽 초록 영역이 Flats 호스트, 보라색이 운영자(사람)예요.

핵심은 “입구는 여러 개, 서비스는 하나”예요. MCP, CLI, 콘솔이 모두 core.Service의 같은 메서드를 부르고, 호출 출처(via)만 다르게 넘겨요. 권한 검사는 각 입구가 아니라 서비스 안에서 via를 보고 해요. 그래서 MCP에 도구를 하나 더 붙여도 권한 규칙을 우회할 수 없어요.

2. 플러그인: 무엇이 설치되나

레포의 plugins/flats 하나가 세 클라이언트용 매니페스트를 모두 갖고 있어요. 내용물은 놀랄 만큼 작아요.

plugins/flats/
├── .claude-plugin/plugin.json   # Claude Code
├── .codex-plugin/plugin.json    # Codex (skills, mcpServers, UI 문구)
├── .cursor-plugin/plugin.json   # Cursor
├── .mcp.json                    # {"flats": {"command": "flats", "args": ["mcp"]}}
└── skills/flats-deploy/SKILL.md # 연결 안내 + 승인 규칙 요약

플러그인 없이도 연결할 수 있어요. MCP 클라이언트에 http://127.0.0.1:7878/mcp(또는 콘솔의 tailnet 주소 + /mcp)를 HTTP 서버로 등록하면 되고, flats mcp-config가 클라이언트별 설정을 출력해요. MCP 자체가 없으면 <console>/llms.txt가 같은 안내를 텍스트로 줘요.

3. flats mcp 브리지

Claude Code, Codex, Cursor 플러그인이 공통으로 실행할 수 있는 MCP 형태는 stdio예요. 그래서 Flats는 호스트에 HTTP MCP를 두고, 클라이언트 쪽에는 그 앞에 붙는 stdio↔HTTP 중계기를 둬요. 중계기는 메시지를 해석하지 않고 그대로 넘겨요.

호스트 선택 순서

플러그인은 주소를 모르기 때문에, 브리지가 매번 아래 순서로 정해요. 실행 시 stderr에 flats mcp: relaying to … (출처)를 찍어요.

구현에서 눈여겨볼 점

• 타임아웃 없음. 도구 호출이 길 수 있어서 HTTP 클라이언트 타임아웃을 0으로 두고, stdin EOF나 시그널로만 끝나요.
• 큰 메시지 허용. 인라인 업로드가 base64라서 한 줄 최대 256 MiB까지 받아요. 실제 제한은 호스트가 걸어요.
• 순서 보장. 메시지마다 고루틴이 뜨지만 앞 메시지가 호스트에 쓰인 뒤에 다음 것을 보내요. initialize만은 응답까지 기다려 세션 ID를 받은 뒤 진행해요.
• 잘못된 입력. JSON이 아닌 줄은 호스트로 보내지 않고 JSON-RPC 오류 -32700을 바로 돌려줘요.

4. 호스트의 MCP 서버

호스트는 공식 Go SDK(modelcontextprotocol/go-sdk)로 /mcp에 Streamable HTTP 서버를 둬요. 설정이 꽤 보수적이에요.

5. 지식 전달: 지침 → guide → refusal

Flats는 에이전트 컨텍스트를 아끼려고 지식을 세 층으로 나눠요. 항상 필요한 것만 처음에 주고, 나머지는 에이전트가 필요할 때 꺼내 읽게 해요.

이 구조 덕분에 스킬 파일이 아무리 오래돼도 에이전트가 읽는 규칙은 지금 돌아가는 호스트 버전의 것이에요. 스킬에 배포 절차를 써 두면 호스트가 바뀔 때 어긋나는데, Flats는 그걸 구조적으로 막았어요.

6. 도구 27개와 권한

v0.4.0 호스트가 노출하는 도구는 27개예요(핵심 24 + guide, get_runtime_reference, get_content_types). MCP 어노테이션으로 읽기 전용/쓰기/파괴적 동작을 표시해요. 중요한 건 “쓰기”라도 대부분 Draft만 바꾼다는 점이에요.

7. 배포 흐름과 승인 게이트

guide의 topic.index가 제시하는 표준 흐름은 다섯 단계예요. 에이전트가 할 수 있는 구간과 사람이 해야 하는 구간이 명확히 나뉘어요.

• 승인은 무엇을 승인하는지 고정해요. Draft revision·hash, 버전, 스냅샷, 공개 범위, 공급자를 얼려두고, 그 사이 바뀌면 stale_approval로 실패해요. 같은 요청이 이미 대기 중이면 새로 만들지 않고 재사용해요.
• 결과는 숫자로 와요. get_approval의 result_data에 failure_code, data_impact(none/runtime_start/restore_data/unknown) 등이 담기고, 에이전트는 그대로 보고하게 돼 있어요.
• Draft는 덮어쓰기예요. 매번 전체 빌드를 보내고, expected_revision으로 동시 수정 충돌(conflict)을 잡아요.

8. 신뢰 경계와 보안

9. 배치 형태: 호스트에서 vs 원격에서

같은 플러그인이 두 가지 배치에서 모두 동작해요. 차이는 flats mcp가 어디로 중계하느냐와, 호스트 디스크를 직접 쓸 수 있느냐뿐이에요.

플러그인 형식을 지원하지 않는 MCP 클라이언트도 같은 구성으로 붙을 수 있어요. 스킬 파일을 그 클라이언트의 스킬 위치에 두고, MCP 서버로 stdio flats mcp(또는 HTTP /mcp)를 등록하면 플러그인과 똑같이 동작해요.

10. 설계에서 배울 점과 주의점