From 6c17f9b10b4d4d18064cc08f87599aa665b5b0c8 Mon Sep 17 00:00:00 2001 From: CD Date: Mon, 16 Mar 2026 14:34:19 +0900 Subject: [PATCH] =?UTF-8?q?refactor(agent):=20.agents=20=ED=86=B5=ED=95=A9?= =?UTF-8?q?=20+=20AGENT.md=20=EC=88=98=EC=B9=99=20=EC=97=85=EB=8D=B0?= =?UTF-8?q?=EC=9D=B4=ED=8A=B8=20+=20STATUS.md=20=EB=8F=84=EC=9E=85=20+=20e?= =?UTF-8?q?nd.md=20Wiki=20=EB=8F=99=EA=B8=B0=ED=99=94=20=EA=B0=9C=ED=8E=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agent/AGENT.md | 29 +++++++++++-- .agent/references/STATUS.md | 68 +++++++++++++++++++++++++++++++ .agent/references/architecture.md | 2 +- .agent/workflows/end.md | 45 +++++++++++++++----- .agent/workflows/pre-task.md | 2 +- .agent/workflows/start.md | 1 + .gitignore | 3 -- docs/devlog/2026-03-16.md | 1 + 8 files changed, 131 insertions(+), 20 deletions(-) create mode 100644 .agent/references/STATUS.md diff --git a/.agent/AGENT.md b/.agent/AGENT.md index aa7f699..506abfa 100644 --- a/.agent/AGENT.md +++ b/.agent/AGENT.md @@ -17,6 +17,9 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. 5. NEVER skip the pre-task checklist defined in `.agent/workflows/pre-task.md` 6. NEVER attempt the same failed approach more than 2 times 7. NEVER truncate error messages — always show the full error output +8. NEVER modify `.env`, secrets, or credential files without explicit user approval +9. NEVER make changes exceeding 3 files without stating the blast radius first +10. NEVER dump large outputs without summarizing — paginate or filter results ## ALWAYS (필수) @@ -26,6 +29,23 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. 4. ALWAYS stop and ask the user if 2 consecutive attempts on the same approach fail 5. ALWAYS use existing helper scripts instead of raw API calls 6. ALWAYS read related existing code (minimum 3 files) before writing new code +7. ALWAYS read `STATUS.md` before starting work to understand the big picture +8. ALWAYS update `STATUS.md` at session end when any module changes +9. ALWAYS state the blast radius (affected files/modules) before multi-file changes +10. ALWAYS verify changes compile/run before reporting completion + +## Security Boundaries (건드리지 않을 것) + +- `.env`, `.env.*` — 환경변수/시크릿 (읽기만 허용, 수정 시 반드시 유저 승인) +- `*.pem`, `*.key` — 인증서/키 파일 +- `.git/` — Git 내부 구조 +- 프로덕션 서비스 직접 조작 금지 (반드시 helper 스크립트 경유) + +## Context Management (컨텍스트 관리) + +- 대용량 출력은 반드시 요약/필터링 (전체 로그 덤프 금지) +- 이전 세션 맥락: `STATUS.md` → devlog → known-issues 순서로 최소한만 로딩 +- 긴 작업 중간에 진행 상황을 devlog entry로 기록 (세션 유실 방지) ## Failure Protocol @@ -42,10 +62,11 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. ## Reference Loading Order 1. `.agent/AGENT.md` (this file — behavior rules) -2. `.agent/references/known-issues.md` (past failure patterns) -3. `.agent/references/` (project-specific knowledge) -4. `.agent/workflows/services.md` (service credentials & protocols) -5. `.agent/workflows/` (action procedures) +2. `.agent/references/STATUS.md` (big picture — system design & features) +3. `.agent/references/known-issues.md` (past failure patterns) +4. `.agent/references/` (project-specific knowledge) +5. `.agent/workflows/services.md` (service credentials & protocols) +6. `.agent/workflows/` (action procedures) ## PowerShell Notes diff --git a/.agent/references/STATUS.md b/.agent/references/STATUS.md new file mode 100644 index 0000000..aead131 --- /dev/null +++ b/.agent/references/STATUS.md @@ -0,0 +1,68 @@ +# Variet Agent — 설계 현황 + +> AI 에이전트는 **세션 시작 시** 이 문서를 읽어 전체 맥락을 파악합니다. +> **세션 종료 시** 변경사항을 이 문서에 반영합니다. +> Last updated: 2026-03-16 + +## 시스템 개요 + +Hybrid Skill-Based AI Agent v3 — 사용자가 디스코드에서 자연어 명령을 내리면, Orchestrator NLU가 분류하여 도구를 실행하거나 AI Agent가 통합 처리합니다. + +``` +Discord 메시지 + → Orchestrator.classify() — NLU 분류 + ├── chat → 즉답 + ├── clarify → 질문 + ├── anime → AnimeTool (파이프라인) + └── task → TaskPipeline.execute() → Gemini CLI agent 모드 +``` + +## 핵심 설계 결정 (불변) + +- **Gemini CLI subprocess 방식 영구 유지** (SDK/API 금지) +- **Vikunja = 태스크 SSOT** (모든 태스크 생성/완료는 Vikunja 경유) +- **`.agent/references/` = 설계 문서 SSOT** (로컬 우선, Wiki에 동기화) + +## 기능 목록 (Feature Inventory) + +| 기능 | 모듈 | 설명 | 상태 | +|------|------|------|:----:| +| 자연어 명령 분류 | `core/orchestrator.py` | Discord 메시지 → chat/clarify/anime/task intent 분류 | ✅ | +| AI 코드 생성 | `core/task_pipeline.py` | 계획→코딩→검증 통합 실행 (Gemini agent 모드) | ✅ | +| Gemini CLI 래퍼 | `core/gemini_caller.py` | text/agent 모드 전환, CLI subprocess 호출 | ✅ | +| 컨텍스트 관리 | `core/context_manager.py` | 관련 파일 선별 + 토큰 예산 제어 | ✅ | +| 프로젝트 인덱싱 | `core/project_indexer.py` | 프로젝트 구조 스캔 + import 관계 파악 | ✅ | +| 애니 자동 다운로드 | `tools/anime_pipeline.py` | 편성표→검색→토렌트→NAS 저장 통합 파이프라인 | ✅ | +| 애니 자막 다운로드 | `tools/subtitle_downloader.py` | Anissia 6개 플랫폼(Google Drive, Tistory, Blog 등) 스크래핑 | ✅ | +| NAS 파일 관리 | `tools/nas_scanner.py` | 에피소드 스캔, 이름 정규화, 릴리스 그룹 감지 | ✅ | +| 토렌트 검색 | `tools/nyaa_client.py` | Nyaa.si 검색 + 6단계 fallback 전략 | ✅ | +| 토렌트 다운로드 | `tools/qbit_client.py` | qBittorrent WebAPI 연동 | ✅ | +| 제목 매칭 | `tools/title_matcher.py` | Romaji 변환 + fuzzy similarity 크로스 언어 매칭 | ✅ | +| Vikunja 태스크 관리 | `.agent/workflows/helpers/vikunja_helper.py` | 태스크 CRUD + 라벨 + 안전 업데이트 | ✅ | +| Gitea Wiki 관리 | `.agent/workflows/helpers/wiki_helper.py` | Wiki 페이지 CRUD | ✅ | +| Discord Bot | `api/discord_bot.py` | 이벤트 핸들러 + NLU 라우팅 (~310줄) | ✅ | +| CLI Bridge | - | Gemini CLI 영속 프로세스 (PTY 미지원으로 보류) | ⏸️ | + +## 모듈 상태 + +| 모듈 | 주요 파일 | 상태 | 최근 변경 | +|------|-----------|:----:|-----------| +| NLU 분류 | `core/orchestrator.py` | ✅ | chat/clarify/anime/task 통합 | +| 태스크 실행 | `core/task_pipeline.py` | ✅ | execute() 1회 + 선택적 review | +| Gemini 래퍼 | `core/gemini_caller.py` | ✅ | text/agent 모드 | +| 컨텍스트 | `core/context_manager.py` | ✅ | 관련 파일 선별 + 토큰 예산 | +| 애니 파이프라인 | `tools/anime_pipeline.py` | ✅ | v2 에피소드 추출, 그룹 필터링, 자막 보호 | +| Discord Bot | `api/discord_bot.py` | ✅ | 레거시 800줄 제거, ~310줄 | +| 에이전트 워크플로우 | `.agent/` | ✅ | STATUS.md + 수칙 업데이트 | + +## 최근 마일스톤 + +- **2026-03-16**: 에이전트 수칙 업데이트 + STATUS.md 도입 + .agents 통합 +- **2026-03-15**: MCP 서버 제거 → CLI 직접 실행 전환 +- **2026-03-15**: 레거시 NLU/핸들러 800줄 제거 +- **2026-03-15**: 애니 파이프라인 버그 5건 수정 + 아키텍처 문서화 +- **2026-03-15**: wiki_client update_page tags 버그 수정 + +## 현재 미해결 + +- **CLI Bridge PoC** (#203) — Windows PTY 미지원으로 보류. pywinpty 또는 Docker 환경 필요 diff --git a/.agent/references/architecture.md b/.agent/references/architecture.md index 47ad6c6..853c176 100644 --- a/.agent/references/architecture.md +++ b/.agent/references/architecture.md @@ -77,4 +77,4 @@ v3: NLU → Agent 1회 (plan+code+verify 통합) → 선택적 Review (1~2 호 ## 아키텍처 결정 (변경 불가) - **Gemini CLI subprocess 영구 유지** (SDK/API 금지) -- 상세: `.agents/references/conventions.md` 참조 +- 상세: `.agent/references/conventions.md` 참조 diff --git a/.agent/workflows/end.md b/.agent/workflows/end.md index 268460f..f3c2470 100644 --- a/.agent/workflows/end.md +++ b/.agent/workflows/end.md @@ -113,22 +113,44 @@ C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\ --- -## 3. Wiki 동기화 (해당 시에만) +## 3. 설계 문서 업데이트 (필수) -| 코드 변경 | 대상 Wiki | -|-----------|----------| -| 서버 변경 | Architecture | -| 프론트엔드 변경 | Architecture | -| 인프라 변경 | Architecture | -| 새 모듈/패키지 추가 | Architecture | +- [ ] `.agent/references/STATUS.md` — 모듈 상태 테이블 업데이트 (변경 있었다면) + - 기능 추가/제거 → 기능 목록 테이블 업데이트 + - 모듈 변경 → 모듈 상태 + 최근 변경 업데이트 + - 마일스톤 달성 → 최근 마일스톤 추가 +- [ ] `.agent/references/architecture.md` — 구조 변경이 있었다면 업데이트 + +## 4. Wiki 동기화 (로컬 변경 기반) + +로컬 references 파일이 변경되었는지 확인합니다: ```powershell -C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md +git diff --name-only .agent/references/ ``` +변경된 파일이 있으면 **파일별로** Wiki에 업로드합니다: + +| 로컬 파일 | Wiki 페이지 | +|-----------|------------| +| `STATUS.md` | "Status" | +| `architecture.md` | "Architecture" | + +```powershell +# STATUS.md가 변경된 경우 +C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Status" .agent\references\STATUS.md +``` +```powershell +# architecture.md가 변경된 경우 +C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Architecture" .agent\references\architecture.md +``` + +> [!TIP] +> 변경된 파일이 없으면 이 단계를 건너뜁니다. + --- -## 4. Git Commit & Push +## 5. Git Commit & Push ```powershell git add -A @@ -151,7 +173,7 @@ scope: (선택) --- -## 5. 최종 체크리스트 +## 6. 최종 체크리스트 > [!WARNING] > 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다. @@ -160,6 +182,7 @@ scope: (선택) - [ ] devlog index 업데이트됨 - [ ] devlog entry 작성됨 (필요한 경우만) - [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반) -- [ ] Wiki 동기화됨 (아키텍처 변경이 있었다면) +- [ ] STATUS.md 업데이트됨 (모듈/기능 변경이 있었다면) +- [ ] Wiki 동기화됨 (변경된 references 파일이 있었다면) - [ ] git push 완료 - [ ] 사용자에게 완료 보고 diff --git a/.agent/workflows/pre-task.md b/.agent/workflows/pre-task.md index 785b263..f57bc26 100644 --- a/.agent/workflows/pre-task.md +++ b/.agent/workflows/pre-task.md @@ -10,7 +10,7 @@ description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트 > [!CAUTION] > **Python 실행 시 반드시 절대경로 사용** (conda 환경이라 `python`이 PATH에 없음): -> `C:\ProgramData\miniforge3\envs\agent_chat\python.exe` +> `C:\ProgramData\miniforge3\envs\variet-agent\python.exe` > 절대로 `python`, `py`, `python.exe`를 단독으로 쓰지 마세요. ## 1단계: 요구사항 정리 diff --git a/.agent/workflows/start.md b/.agent/workflows/start.md index 707b022..0ca4f39 100644 --- a/.agent/workflows/start.md +++ b/.agent/workflows/start.md @@ -14,6 +14,7 @@ description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워 `.agent/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다. `.agent/references/known-issues.md`를 읽어 최근 이슈를 파악합니다. +`.agent/references/STATUS.md`를 읽어 전체 설계 현황과 기능 목록을 파악합니다. ### 1. Devlog 맥락 복구 diff --git a/.gitignore b/.gitignore index cffcded..0a748fd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,9 @@ # 토큰 포함 파일 제외 .agent/workflows/services.md -.agents/workflows/services.md sessions/ __pycache__/ *.pyc .env logs/ -.agent/ tests/verify_output.txt tests/test_output.txt - diff --git a/docs/devlog/2026-03-16.md b/docs/devlog/2026-03-16.md index e64d14d..dec4f8d 100644 --- a/docs/devlog/2026-03-16.md +++ b/docs/devlog/2026-03-16.md @@ -3,3 +3,4 @@ | # | 시간 | 작업 | 커밋 | 상태 | |---|------|------|------|------| | 1 | 23:35~11:14 | 봇 기동 버그 3건 수정 (apscheduler, cp949 인코딩, workspaces 경로) + Vikunja 프로젝트 관리 기능 추가 (projects, report 커맨드) + agent 프롬프트 보강 | `c9068cd` | ✅ | +| 2 | 13:46~14:29 | .agents→.agent 통합 + AGENT.md 수칙 업데이트(Security/Context/Blast Radius) + STATUS.md 도입 + end.md Wiki 동기화 개편 | `TBD` | ✅ |