13시간의 한계를 넘어서는 개발: Android 휴대폰에 'Watchdog'과 'Shadow Sandbox'를 갖춘 AI 에이전트 구축기

AI 에이전트를 모바일 휴대폰에서 실행할 때 가장 큰 두려움은 단 하나의 잘못된 코드 라인이 시스템 전체를 완전히 다운시켜 복구할 방법조차 없게 만드는 것입니다.

이것이 바로 이 프로젝트의 원래 동기였습니다.

I. 프로젝트 소개: Z-Agent-Termux

이것은 Android 휴대폰의 Termux 환경에서 실행되는 자가 진화형 AI 에이전트입니다. 핵심 임무는 단 하나입니다. 코드가 아무리 수정되어도 시스템이 절대 다운되어서는 안 됩니다.

이러한 '불패성'을 달성하기 위해, 저는 이 에이전트에 이중 보험 아키텍처를 설계했습니다:

1. Watchdog (boot_guard): 프로그램 시작 전에 AST(추상 구문 트리), 심볼, 스모크 자가 테스트를 자동으로 수행합니다. 시작에 성공하면 'last_good' 스냅샷을 자동 생성하고; 시작에 실패하면 가장 최근의 스냅샷을 자동으로 로드하여 원자적 롤백(atomic rollback)을 수행합니다.
2. Shadow Sandbox (shadow_test): 코드가 실제로 교체되기 전에, 'mock LLM'이 구동하는 전체 논리 세트를 격리된 샌드박스 환경에서 실행합니다. 모든 단언(assertion)이 통과하고 런타임 불변 오류(runtime invariant errors)가 없을 때만 'gene write-to-disk'가 허용됩니다.

게다가, 저는 아키텍처에 물리적 격리(zcore 도구 라이브러리를 zguard 방어 시스템으로부터 분리)를 구현하여, Watchdog이 메인 프로그램에 의해 손상되는 것을 막았습니다.

II. 13시간의 극한 '창조' 여정

이 프로젝트는 일상적인 방식으로 단계별로 구축된 것이 아닙니다. 오늘 오전 9시부터 오후 10시까지 이어진 13시간 동안의 작업 결과물입니다.

• 9:00 – 12:00 AM: 문제점 및 충돌 (Pitfalls and Crashes) 처음에는 API 인터페이스를 만지작거리다가 401(잘못된 키), 503(서버 과부하)에 부딪혔고, 심지어 nano 에디터에서 중요한 소스 코드를 실수로 삭제하기도 했다. 반복적인 충돌과 복구 시도를 통해 깨달았다: 모바일 환경은 너무나도 취약하며, '자가 치유(self-healing)' 메커니즘이 필수적이라는 것을.
• 12:00 – 4:00 PM: 리팩토링 및 통합 (Refactoring and Integration) 외부 대규모 모델(GLM-5.3)의 지적 지원을 받아 소스 코드를 리팩토링하기 시작했다. 원래 2,000줄이 넘는 단일 파일 구조였던 모놀리스(monolith)를 zcore와 zguard로 분할했다. 이 과정에서 워치독(watchdog, boot_guard)과 섀도우 샌드박스(shadow sandbox, shadow_test)가 도입되었다.
• 4:00 – 6:00 PM: 보안 정리 및 문서화 (Security Cleanup and Documentation) API 키 유출을 방지하기 위해 모든 로그 및 설정 파일을 감사하고 정제했다. 그런 다음 중국어 배포 매뉴얼과 사용자 매뉴얼을 처음부터 매우 상세하게 작성했다.
• 6:00 – 8:00 PM: 홍보 및 아웃리치 (Promotion and Outreach) 토론을 위한 QQ 그룹을 설정하고, 홍보 문구를 작성했으며, Bilibili에 업데이트를 게시하는 동시에 Juejin과 Zhihu에 오픈 소스 기사를 게재했다.
• 8:00 – 10:00 PM: Git 동기화 및 출시 (Git Sync and Release) 이 부분이 가장 어려웠다. 로컬 코드와 원격 GitHub 저장소 사이에 충돌이 발생했다( ! [rejected] ). git pull --allow-unrelated-histories와 git push를 여러 차례 주고받은 끝에, 마침내 모든 코드, README, 배지, 빠른 시작 튜토리얼 및 llms.txt 파일을 GitHub에 성공적으로 푸시할 수 있었다.

III. 프로젝트 하이라이트 및 알려진 한계점 (Project Highlights and Known Limitations)

• 하이라이트: 이 시스템은 내장된 자가 치유 루프를 가지고 있다. 소스 코드를 망가뜨리더라도 재시작 시 부팅 가능한 버전으로 자동 롤백된다. 이는 사용자가 휴대폰에서 에이전트를 자유롭게 실험할 수 있다는 것을 의미한다.
• 알려진 한계점: '잘못된 완성(false completion)'은 방지하지만, '저품질 완성(low-quality completion)'은 방지하지 못한다. 섀도우 샌드박스는 현재 첫 번째 출력만 가짜로 만들 뿐이며, 실제 네트워크 환경을 시뮬레이션할 수는 없다.

IV. 사용 방법

이 프로젝트는 GitHub에서 완전한 오픈 소스로 공개되었으며, 중국어 문서가 완벽하게 갖춰져 있습니다. 관심 있는 누구든지 자유롭게 시도해 볼 수 있으며, 토론을 위해 Issues를 열어도 좋습니다.

👉 GitHub 저장소: [https://github.com/zxxzxx1314/Z-agent-termux]
💬 QQ 토론 그룹: 1072611451

만약 여러분도 온디바이스 AI 에이전트에 관심이 있거나, 보안 샌드박스가 있는 경량 실험 프레임워크를 찾고 있다면, 별점을 주어 응원해 주세요. 오픈 소스는 쉽지 않습니다. 지원에 감사드립니다!