robbin/grokbot-local-agent

Bot 컴퓨터의 Pi Agent 호출

Pi는 Bot 컴퓨터에 설치된 명령줄 코딩 에이전트입니다. 기본 모델은 DeepSeek Flash, 생각 수준은 high이며, 파일 읽기/쓰기, 명령 실행, 웹 검색이 가능합니다. 자세한 설치 및 설정은 저장소의 docs/setup-guide.md를 참조하세요. 스크립트는 ~/tools/pi-call/(저장소의 bin/ 디렉토리)에 있습니다.

사용량 정책

Bot 자체의 모델 사용량은 제한적이지만, Pi는 사용자 자신의 모델 계정(기본 DeepSeek)을 사용하므로 사용량이 Bot과 별도로 계산됩니다. 따라서 무거운 작업은 기본적으로 Pi에 위임하고, Bot은 스케줄링과 최종 확인만 수행합니다.

Pi에 위임:

• 대량 파일 처리: 파일 일괄 수정, 데이터 정리, 형식 변환
• 코드 작성: 스크립트, 소형 도구, 테스트, 디버깅
• 장기 조사 및 웹 검색
• 긴 문서 초안: 문서, 보고서, 글의 첫 번째 버전
• 사용자가 Pi에게 직접 처리, 두 번째 의견 또는 동일 주제 비교를 요청한 경우

Bot이 직접 처리:

• 짧은 대화 및 한두 단계로 답변 가능한 질문
• 커넥터 작업(Gmail, X, GitHub 등). Pi에는 이러한 커넥터가 없음
• 전송, 게시, 푸시, 배포 전 확인 및 사용자에게 보고

방법:

• 지침은 간결하게: 목표, 입력 위치, 출력 파일 경로, 완료 기준을 몇 줄로 명확히 작성. 긴 원문을 프롬프트에 붙여넣지 말고 Pi가 직접 파일을 읽도록 함
• 결과는 직접 파일로 저장: 프롬프트에서 출력 경로를 지정하고 Pi가 파일을 작성하게 함. Bot은 확인 후 이 파일을 직접 전달하며, 다시 작성하지 않음. 수정이 필요하면 동일 세션에서 Pi가 수정하도록 함
• 핵심 결론은 기록에 남김: 작업의 중요한 결론, 결정 또는 데이터는 Bot이 적극적으로 메모리나 관련 문서에 기록해야 하며, Pi의 세션에만 남겨두지 않음

절차

1. 작업 디렉토리 결정: Pi에게 작업 완료에 필요한 디렉토리만 제공(저장소 또는 /tmp/<작업>). / 또는 전체 홈 디렉토리를 제공하지 마십시오.
2. 세션 이름 지정: 짧은 영어 kebab-case로, 작업당 하나의 이름(예: news-i18n). 동일 작업의 후속 수정은 동일 이름을 사용하고, 처음부터 다시 시작하려면 새 이름을 사용합니다.
3. 출력 위치 지정: 더 적합한 대상 위치가 없으면 /tmp/pi-out/<세션명>/을 사용합니다. 보관하거나 동기화해야 하는 결과물은 해당 위치(해당 저장소, 문서 또는 노트 디렉토리)에 직접 작성합니다.
4. 프롬프트 작성: 짧고 완전하게, 목표, 제약 조건, 출력 파일 경로, 완료 기준을 설명하고 마지막에는 작성한 파일과 한 줄 결론을 보고하도록 요청합니다. Pi는 채팅 기록을 볼 수 없으므로 필요한 배경은 한두 문장으로 설명하고, 긴 자료는 파일 경로를 제공합니다.
5. 호출. 1~2분을 초과하는 작업은 항상 pi-task를 사용합니다. 작업 번호를 부여하고 상태와 진행 상황을 기록하며 결과를 파일로 저장합니다:

   ~/tools/pi-call/pi-task run <작업 디렉토리> "<프롬프트>" --session <세션명> --owner <your-agent-id> [--timeout 초] [--no-write] [--no-web]
   

   --owner는 반드시 작성해야 합니다. 작업을 요청한 Bot에 표시하고, 완료 알림을 받을 수 있도록 하며, pending/ack도 이를 통해 다른 Bot이 서로의 작업을 가로채거나 승인하는 것을 방지합니다. 작성하지 않아도 실행은 되지만(owner는 null로 기록되고 stderr에 경고 메시지가 출력됨), 알림은 전달되지 않습니다. (환경 변수 PI_TASK_OWNER로 기본값을 제공할 수도 있지만, 명시적으로 전달하는 것이 더 안정적입니다.) 자신의 agent id는 자신의 프로필 경로(/home/box/agent-data/agents/<your-agent-id>/profile.json 형식)에 있습니다. Shell 도구의 내장 백그라운드 실행을 사용하고(차단하지 않음), nohup, & 또는 setsid를 사용하지 마십시오. 출력 첫 줄은 TASK <작업 ID>입니다. 완료 시 상태와 result.md 경로를 출력합니다. 종료 코드: 0 완료, 1 실패, 124 시간 초과, 130 취소. 기타 하위 명령어: status <ID>(상태, owner, 소요 시간, 최근 이벤트), log <ID> [-n 30], list [--all] [--owner <id>|none], cancel <ID>, pending [--owner <id>|none](종료되었지만 아직 보고되지 않은 작업), ack <ID> [--owner <id>|none](보고 완료 표시, owner가 일치하지 않으면 거부, 종료 코드 1). 작업 데이터는 ~/.pi/tasks/<작업 ID>/에 저장됩니다: status.json, events.jsonl, result.md, prompt-<n>.txt. Bot 컴퓨터가 재시작되면 실행 중이던 작업은 interrupted로 표시되고 사용자에게 재실행 여부를 묻습니다. 완료 알림: 환경에 PI_NOTIFY_URL과 PI_NOTIFY_SECRET이 있을 때(Bot 컴퓨터의 환경 변수로 저장, 파일에 기록하지 않음), pi-task는 작업이 완료될 때마다 이 Webhook에 {source, id, owner, state, exit_code}를 전송합니다(작업 내용 제외). 이를 수신하는 정기 작업이 깨어나면 pending --owner <자신의 id>를 실행하여 확인, 보고, ack --owner <자신의 id>를 수행합니다. owner가 자신인 작업만 처리합니다. 다른 Bot의 작업은 확인하거나 승인하지 않고, SendToAgent(priority true)를 사용하여 해당 owner Bot에 전달합니다. 정기 작업 환경에서 메시지를 보낼 수 없으면 Bot 본체에 전달을 위임합니다. owner가 없는 작업은 사용자에게만 알리고 승인하지 않습니다. 다른 Bot에서 전달된, owner가 자신인 작업은 직접 확인, 보고 및 ack을 수행합니다. 설정이 없으면 자동으로 건너뛰며, 전송 결과는 events.jsonl의 notify 이벤트에 기록됩니다. PI_NOTIFY_OFF=1을 설정하면 임시로 비활성화할 수 있습니다. 최종 보고: 완료 알림을 받지 못할 수 있습니다. 따라서 깨어날 때마다(사용자 메시지, 정기 작업 등) Pi에 위임한 작업이 있으면 먼저 pi-task pending --owner <자신의 id>를 실행하여 자신이 위임한 작업 중 종료되었지만 아직 보고되지 않은 작업을 확인하고 전달한 후 ack <ID> --owner <자신의 id>를 수행합니다. 자신의 작업만 승인하고, 다른 사람의 작업은 위임한 Bot이 처리하도록 남겨둡니다. 수십 초 내에 완료할 수 있는 짧은 질문/답변은 포그라운드에서 직접 호출할 수 있습니다:

   ~/tools/pi-call/pi-run <작업 디렉토리> "<프롬프트>" --session <세션명> [--timeout 초]
   

   읽기 전용이 필요하거나 모델을 변경해야 하는 경우 기본 스크립트를 사용합니다:

   ~/tools/pi-call/pi-call.mjs <작업 디렉토리> deepseek/deepseek-flash "<프롬프트>" --thinking high [--allow-write] [--no-web] [--session <세션명>] [--timeout 초]
   

   pi-run 및 pi-call.mjs: 표준 출력은 Pi의 마지막 응답만 포함합니다. 기본 시간 초과는 300초입니다. 종료 코드: 0 성공, 1 오류, 124 시간 초과, 127 Pi를 찾을 수 없음. 권한: pi-task run 및 pi-run은 기본적으로 모든 도구(읽기, 검색, 명령 실행, 파일 쓰기, 웹 검색)를 허용합니다. pi-call.mjs는 --allow-write가 없으면 읽기 전용 도구만 허용합니다.
6. 결과 확인: Pi의 응답은 단지 Pi의 진술일 뿐입니다. git diff, 테스트 실행 또는 파일 읽기를 통해 실제로 수행되었는지 확인한 후 사용자에게 전달합니다. 확인되지 않은 결론을 사실로 제시하지 마십시오.
7. 계속 수정: pi-task 작업의 경우 pi-task reply <작업 ID> "<수정할 내용>"을 사용합니다(동일 세션, 동일 디렉토리, 원래 작업의 owner 유지, 작업이 아직 실행 중이면 거부됨). pi-run 작업의 경우 동일한 --session을 사용하여 다시 호출합니다. 두 경우의 세션은 별도로 저장되며 서로 이어서 사용할 수 없습니다.

규칙

• 사용자 자신의 모델 사용량을 사용합니다(웹 검색은 사용자 자신의 검색 서비스 사용량 사용). 필요에 따라 호출하며, 무의미한 반복이나 대규모 공회전을 하지 않습니다.
• 코드 푸시, 배포, DNS 또는 온라인 서비스 변경, 메시지 또는 이메일 전송, 중요한 파일 삭제는 Pi에 위임하지 않습니다. 이러한 작업은 Bot이 직접 수행하고 사용자 동의를 먼저 받습니다.
• Pi가 ~/.pi/agent/auth.json, 키 파일 또는 환경 변수의 key를 읽거나 출력하도록 하지 마십시오.
• 다른 사람의 작업을 승인하지 않음: pending/ack 모두 --owner <자신의 id>를 사용하며, owner가 일치하지 않으면 작업을 위임한 Bot에 전달합니다.
• 사용자에게 표시되는 응답에는 "Pi가 X를 수행하도록 함"이라고 말하고, 결과와 확인한 내용을 설명합니다.

문제 해결

• pi: command not found: 먼저 export PATH=$HOME/.local/bin:$HOME/.node22/bin:$PATH를 실행합니다.
• 사용 가능한 모델이 없음: DeepSeek 로그인이 만료되었습니다. 사용자가 데스크톱 터미널에서 pi를 실행하고 /login으로 다시 로그인해야 합니다. Bot이 사용자를 대신하여 로그인할 수 없습니다.
• 시간 초과: 작업을 더 작게 나누거나 --timeout을 늘립니다.
• 오류 또는 결과 불일치: 먼저 종료 코드와 --verbose 로그를 확인합니다. 작업 자체가 잘못된 경우 동일 세션에서 문제를 지적하고 Pi가 다시 수행하도록 하되, 최대 한두 번 재시도합니다. 그래도 안 되면 Bot이 직접 처리하고 사용자에게 Pi가 어떤 부분을 잘못했는지 알리며, 반복적으로 공회전하지 않습니다.