viruagent-cli 0.6.1 → 0.7.0

package/README.ko.md

@@ -29,6 +29,7 @@
 | **Tistory** | Playwright (카카오) | 글 발행, 임시저장, 카테고리, 이미지 업로드 | [가이드](docs/ko/guide-tistory.md) |
 | **Naver Blog** | Playwright (네이버) | 글 발행, 카테고리, SE Editor, 이미지 업로드 | [가이드](docs/ko/guide-naver.md) |
 | **Instagram** | HTTP (브라우저 불필요) | 좋아요, 댓글, 팔로우, 포스팅, 프로필, 피드 | [가이드](docs/ko/guide-instagram.md) |
+| **X (Twitter)** | HTTP (쿠키 인증) | 트윗, 좋아요, 리트윗, 팔로우, 검색, 타임라인, 미디어 업로드 | [가이드](docs/ko/guide-x.md) |
 
 ## 동작 방식
 
@@ -95,6 +96,15 @@ npx viruagent-cli login --provider insta --username <인스타 ID> --password <
 >
 > 전체 API 레퍼런스와 rate limit 규칙은 [Instagram 가이드](docs/ko/guide-instagram.md)를 참고하세요.
 
+### X (Twitter)
+
+```bash
+npx viruagent-cli login --provider x --auth-token <토큰> --ct0 <ct0>
+```
+> 브라우저에서 `auth_token`과 `ct0` 쿠키를 추출하세요. 비밀번호 로그인 없음 — 쿠키 기반 인증만 지원.
+>
+> 전체 API 레퍼런스, GraphQL 동기화, rate limit 규칙은 [X 가이드](docs/ko/guide-x.md)를 참고하세요.
+
 ## 사용법
 
 | 이렇게 말하면 | 에이전트가 알아서 |
@@ -107,12 +117,17 @@ npx viruagent-cli login --provider insta --username <인스타 ID> --password <
 | "이 사람 피드 분석해서 댓글 달아줘" | analyzePost → AI 댓글 생성 → comment |
 | "@user 팔로우해줘" | 로그인 → follow (딜레이 자동 적용) |
 | "인스타 rate limit 확인해줘" | rate-limit-status → 카운터 표시 |
+| "이 내용으로 트윗해줘" | X 로그인 → publish (rate limit 자동 적용) |
+| "X에서 AI 도구 검색해줘" | search → 결과 반환 |
+| "X에서 IT 개발자 좋아요하고 팔로우해줘" | search → like + follow (딜레이 자동 적용) |
+| "내 X 타임라인 보여줘" | getFeed → 최신 트윗 표시 |
 
 ## 플랫폼별 가이드
 
 - **[Tistory 가이드](docs/ko/guide-tistory.md)** — 블로그 발행, 이미지 업로드, 카테고리
 - **[Naver Blog 가이드](docs/ko/guide-naver.md)** — SE Editor, 블로그 발행, 이미지 업로드
 - **[Instagram 가이드](docs/ko/guide-instagram.md)** — 18개 API 메서드, rate limit 규칙, AI 댓글
+- **[X (Twitter) 가이드](docs/ko/guide-x.md)** — GraphQL API, queryId 동적 동기화, rate limit 규칙
 
 ## 지원 환경
 
@@ -129,6 +144,7 @@ npx viruagent-cli login --provider insta --username <인스타 ID> --password <
 | CLI 프레임워크 | Commander.js |
 | 브라우저 자동화 | Playwright (Tistory, Naver만 사용) |
 | Instagram API | 순수 HTTP fetch (브라우저 불필요) |
+| X (Twitter) API | 내부 GraphQL API + queryId 동적 추출 |
 | 세션 관리 | JSON 파일 (`~/.viruagent-cli/`) |
 | Rate Limiting | 유저별 영속 카운터 + 랜덤 딜레이 |
 | 이미지 검색 | DuckDuckGo, Wikimedia Commons |

package/README.md

@@ -29,6 +29,7 @@ Designed not for humans, but for **AI agents**.
 | **Tistory** | Playwright (Kakao) | Publish, Draft, Categories, Image Upload | [Guide](docs/en/guide-tistory.md) |
 | **Naver Blog** | Playwright (Naver) | Publish, Categories, SE Editor, Image Upload | [Guide](docs/en/guide-naver.md) |
 | **Instagram** | HTTP (No Browser) | Like, Comment, Follow, Post, Profile, Feed, Rate Limit | [Guide](docs/en/guide-instagram.md) |
+| **X (Twitter)** | HTTP (Cookie Auth) | Tweet, Like, Retweet, Follow, Search, Timeline, Media Upload | [Guide](docs/en/guide-x.md) |
 
 ## How It Works
 
@@ -95,6 +96,15 @@ npx viruagent-cli login --provider insta --username <id> --password <pw>
 >
 > See the [Instagram Guide](docs/en/guide-instagram.md) for full API reference and rate limit rules.
 
+### X (Twitter)
+
+```bash
+npx viruagent-cli login --provider x --auth-token <token> --ct0 <ct0>
+```
+> Extract `auth_token` and `ct0` cookies from your browser. No password login — cookie-based auth only.
+>
+> See the [X Guide](docs/en/guide-x.md) for full API reference, GraphQL sync, and rate limit rules.
+
 ## Usage
 
 | Say this | Agent handles |
@@ -107,12 +117,17 @@ npx viruagent-cli login --provider insta --username <id> --password <pw>
 | "Analyze and comment on @user's feed" | analyzePost → AI generates comment → comment |
 | "Follow @user" | Login → follow (with delay) |
 | "Check Instagram rate limit" | rate-limit-status → show counters |
+| "Tweet this text" | X login → publish (with rate limit) |
+| "Search X for AI tools" | search → return results |
+| "Like and follow IT devs on X" | search → like + follow (with delays) |
+| "Show my X timeline" | getFeed → show latest tweets |
 
 ## Platform Guides
 
 - **[Tistory Guide](docs/en/guide-tistory.md)** — Blog publishing, image upload, categories
 - **[Naver Blog Guide](docs/en/guide-naver.md)** — SE Editor, blog publishing, image upload
 - **[Instagram Guide](docs/en/guide-instagram.md)** — 18 API methods, rate limits, AI commenting
+- **[X (Twitter) Guide](docs/en/guide-x.md)** — GraphQL API, dynamic queryId sync, rate limits
 
 ## Supported Environments
 
@@ -129,6 +144,7 @@ npx viruagent-cli login --provider insta --username <id> --password <pw>
 | CLI Framework | Commander.js |
 | Browser Automation | Playwright (Tistory, Naver only) |
 | Instagram API | Pure HTTP fetch (no browser) |
+| X (Twitter) API | Internal GraphQL API with dynamic queryId extraction |
 | Session Management | JSON file (`~/.viruagent-cli/`) |
 | Rate Limiting | Per-user persistent counters with random delays |
 | Image Search | DuckDuckGo, Wikimedia Commons |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viruagent-cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "AI-agent-optimized CLI for blog publishing (Tistory, Naver) and Instagram automation",
   "private": false,
   "type": "commonjs",

package/skills/va-insta/SKILL.md

@@ -18,6 +18,7 @@ Instagram 자동화를 위한 viruagent-cli 가이드. 항상 `--provider insta`
 | 명령 | 스킬 | 설명 |
 |------|------|------|
 | login | va-insta-login | 로그인 + 챌린지 해결 |
+| publish | va-insta-publish | 게시물 발행 (어그로 전략 포함) |
 | like, unlike | va-insta-like | 좋아요/좋아요 취소 |
 | comment | va-insta-comment | 댓글 작성 |
 | follow, unfollow | va-insta-follow | 팔로우/언팔로우 |
@@ -61,4 +62,4 @@ INSTA_PASSWORD=
 
 ## See Also
 
-va-shared, va-insta-login, va-insta-like, va-insta-comment, va-insta-follow, va-insta-dm, va-insta-feed
+va-shared, va-insta-login, va-insta-publish, va-insta-like, va-insta-comment, va-insta-follow, va-insta-dm, va-insta-feed

package/skills/va-insta-publish/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: va-insta-publish
+version: 1.0.0
+description: "Instagram 게시물 발행: 어그로 캡션 전략, 이미지 선택, 해시태그"
+metadata:
+  category: "publish"
+  provider: "insta"
+  requires:
+    bins: ["viruagent-cli"]
+---
+
+# va-insta-publish — Instagram 게시물 발행
+
+Instagram에 이미지+캡션을 발행하는 가이드. 어그로(고engagement) 콘텐츠 전략 포함.
+
+## 명령어
+
+```bash
+npx viruagent-cli publish --provider insta \
+  --image-urls "<이미지URL>" \
+  --content "<캡션텍스트>"
+```
+
+또는 키워드로 이미지 자동 검색:
+
+```bash
+npx viruagent-cli publish --provider insta \
+  --related-image-keywords "<키워드>" \
+  --content "<캡션텍스트>"
+```
+
+## 어그로 주제 유형 (인게이지먼트 높은 순)
+
+### 1. 논쟁형 (Controversial) — 저장+댓글 최고
+공감대를 자극하는 주장. 한쪽 편을 들되 반론 여지를 남긴다.
+
+| 예시 주제 | 핵심 앵글 |
+|-----------|-----------|
+| "개발자 월급 현실 폭로" | 기대 vs 실제 연봉 갭 |
+| "운동 유튜버들이 절대 안 말하는 것" | 업계 비밀 폭로 프레임 |
+| "20대에 집 사는 게 정말 답인가" | 세대 갈등 자극 |
+| "직장인이 부업하면 안 되는 이유" | 역발상 |
+| "한국 스타트업이 망하는 진짜 이유" | 내부자 폭로 |
+
+### 2. 공감형 (Relatable) — 저장+공유 최고
+"내 얘기다" 싶게 만드는 콘텐츠.
+
+| 예시 주제 | 핵심 앵글 |
+|-----------|-----------|
+| "개발자라면 공감 100%" | 직군 공감 밈 |
+| "월요일 아침 출근 전 뇌 상태" | 직장인 공감 |
+| "카페에서 노트북 피는 사람 유형" | 유형 분류 |
+| "운동 3개월 전후 마인드셋 변화" | 성장 공감 |
+| "AI 쓰기 전 vs 후 업무량" | 도구 도입 전후 |
+
+### 3. 정보형 (Educational) — 저장 최고, 팔로우 증가
+"몰랐다, 유용하다" 반응 유도.
+
+| 예시 주제 | 핵심 앵글 |
+|-----------|-----------|
+| "Claude AI 프롬프트 꿀팁 5가지" | 즉시 써먹는 팁 |
+| "개발자 연봉 협상 스크립트" | 실전 대화 예시 |
+| "인스타 알고리즘 2026 변화 요약" | 최신 정보 |
+| "노션 템플릿 무료 공유" | 실용 리소스 |
+| "사이드 프로젝트 6개월 수익 공개" | 숫자 공개 |
+
+### 4. 스토리형 (Story) — 댓글+팔로우 최고
+여정과 감정이 있는 서사.
+
+| 예시 주제 | 핵심 앵글 |
+|-----------|-----------|
+| "비전공자가 개발자 되기까지 1년" | 성장 서사 |
+| "월 300만원 부업 만든 방법" | 숫자+여정 |
+| "회사 그만두고 6개월 후기" | 결단+결과 |
+| "AI 에이전트로 블로그 자동화한 결과" | 실험 후기 |
+| "팔로워 0에서 1만까지 걸린 시간" | 성장 수치 |
+
+## 캡션 작성 규칙
+
+### 첫 줄이 전부다 (2줄 이상 "더 보기" 전에 후킹)
+- **숫자**: "3가지만 알면 됩니다"
+- **반전**: "잘못 알고 있었습니다"
+- **질문**: "이거 해보셨나요?"
+- **금지**: "이것만은 하지 마세요"
+- **공감**: "저만 이런 거 아니죠?"
+
+### 구조 (300~500자 최적)
+```
+[첫 줄 후킹 — 1문장]
+
+[본론 — 3~5줄. 줄바꿈 많이. 읽기 쉽게.]
+
+[행동 유도 — 저장/댓글/팔로우 중 하나만]
+
+[해시태그 — 줄바꿈 후 별도로]
+```
+
+### 행동 유도 (CTA) 예시
+- 저장: "나중에 써먹으려면 저장해 두세요 🔖"
+- 댓글: "여러분은 어떻게 생각하세요? 댓글로 알려주세요 👇"
+- 팔로우: "이런 내용 더 보려면 팔로우 ✅"
+- 공유: "이거 꼭 필요한 친구한테 태그해 주세요 🏷️"
+
+### 해시태그 전략 (20~25개)
+- 대형 (100만+): 3~5개 (노출용)
+- 중형 (10만~100만): 10~12개 (타겟용)
+- 소형 (1만~10만): 5~7개 (경쟁 적음)
+- 브랜드/니치: 2~3개 (커뮤니티용)
+
+```
+#개발자 #프로그래밍 #코딩 (대형)
+#개발자일상 #개발자성장 #주니어개발자 (중형)
+#사이드프로젝트 #AI자동화 #viruagent (소형/니치)
+```
+
+## 이미지 선택 기준
+
+| 유형 | 효과 | 권장 상황 |
+|------|------|-----------|
+| 텍스트 카드 | 저장률↑ | 정보형, 팁 |
+| 비포/애프터 | 댓글↑ | 변화, 성장 |
+| 밈/유머 | 공유↑ | 공감형 |
+| 실제 화면캡처 | 신뢰↑ | 후기, 결과 공개 |
+| 얼굴 포함 | 팔로우↑ | 스토리형 |
+
+`--related-image-keywords`에 주제 관련 영어 키워드 사용 권장 (Unsplash 검색):
+- 개발: `developer laptop coding`
+- AI: `artificial intelligence technology`
+- 성장: `growth success motivation`
+- 일상: `coffee work lifestyle`
+
+## 발행 예시
+
+```bash
+# 정보형: Claude 팁 카드
+npx viruagent-cli publish --provider insta \
+  --related-image-keywords "AI technology laptop" \
+  --content "Claude AI 쓰면서 바뀐 것들 🤖
+
+프롬프트 하나로 블로그 글을 자동 발행합니다.
+코드 리뷰도 10초면 끝납니다.
+기획안도 5분 만에 초안이 나옵니다.
+
+아직도 혼자 다 하고 있다면
+도구를 바꿀 때입니다.
+
+나중에 써먹으려면 저장해 두세요 🔖
+
+#AI #Claude #개발자 #업무자동화 #생산성 #개발자일상 #프로그래밍 #코딩 #사이드프로젝트 #AI자동화 #viruagent #개발자성장 #주니어개발자 #테크 #스타트업"
+```
+
+## 주의사항
+
+- caption 최대 2,200자 (초과 시 잘림)
+- 해시태그 최대 30개 (초과 시 인게이지먼트 감소)
+- 발행 간격: 최소 1~2분 (rate limit)
+- 로그인 안 된 경우: `va-insta-login` 먼저 실행

package/skills/va-shared/SKILL.md

@@ -64,6 +64,7 @@ SKILLS_DIR: <viruagent-cli 설치 경로>/skills/
 | va-naver-posts | `va-naver-posts/SKILL.md` | 글 목록/읽기 |
 | va-insta | `va-insta/SKILL.md` | Instagram 개요 + 레이트리밋 |
 | va-insta-login | `va-insta-login/SKILL.md` | 로그인 + 챌린지 |
+| va-insta-publish | `va-insta-publish/SKILL.md` | 게시물 발행 + 어그로 전략 |
 | va-insta-like | `va-insta-like/SKILL.md` | 좋아요 |
 | va-insta-comment | `va-insta-comment/SKILL.md` | 댓글 |
 | va-insta-follow | `va-insta-follow/SKILL.md` | 팔로우/언팔 |

package/skills/va-tistory-publish/SKILL.md

@@ -52,7 +52,7 @@ npx viruagent-cli publish \
 - **소제목 간격**: 600~1,000자(약 300~500단어)마다 h3 1개
 - **목차**: 3개 이상 섹션이면 앵커 링크 목차 삽입 (Featured Snippet 진입 확률 상승)
 - **이미지 alt 태그**: 반드시 `핵심키워드 + 설명` 형식으로 작성
-- **내부 링크**: 관련 글 2~4개 연결 (체류시간 35% 연장 효과)
+- **내부 링크**: 실제 발행된 URL이 제공된 경우에만 삽입. URL 없으면 섹션 전체 생략 (가짜 링크 절대 금지)
 - **E-E-A-T**: 직접 경험 기반 문장, 데이터/출처 인용, 작성자 관점 명시
 
 ### Tistory HTML 규칙
@@ -163,13 +163,7 @@ npx viruagent-cli publish \
 <p>[예상 못한 결과나 부가적 인사이트 — 이 섹션이 인간미를 만듦]</p>
 <p>&nbsp;</p>
 
-<!-- 내부 링크 (2~4개 필수) -->
-<h2>관련 글</h2>
-<ul>
-  <li><a href="[URL1]">[관련 글 1 제목]</a></li>
-  <li><a href="[URL2]">[관련 글 2 제목]</a></li>
-</ul>
-<p>&nbsp;</p>
+<!-- 내부 링크: 실제 발행된 URL만 사용. 모르면 섹션 전체 생략 -->
 
 <p>[핵심 요약 1~2문장] [독자에게 구체적 행동 제안] [공유/댓글 유도]</p>
 ```
@@ -233,13 +227,7 @@ npx viruagent-cli publish \
 <p>[구체적 답변]</p>
 <p>&nbsp;</p>
 
-<!-- 내부 링크 -->
-<h2>관련 글</h2>
-<ul>
-  <li><a href="[URL1]">[관련 글 1]</a></li>
-  <li><a href="[URL2]">[관련 글 2]</a></li>
-</ul>
-<p>&nbsp;</p>
+<!-- 내부 링크: 실제 발행된 URL만 사용. 모르면 섹션 전체 생략 -->
 
 <p>[완료 축하 + 다음 단계 제안]</p>
 ```
@@ -294,13 +282,7 @@ npx viruagent-cli publish \
 <p>[이유]</p>
 <p>&nbsp;</p>
 
-<!-- 내부 링크 -->
-<h2>관련 글</h2>
-<ul>
-  <li><a href="[URL1]">[관련 글 1]</a></li>
-  <li><a href="[URL2]">[관련 글 2]</a></li>
-</ul>
-<p>&nbsp;</p>
+<!-- 내부 링크: 실제 발행된 URL만 사용. 모르면 섹션 전체 생략 -->
 
 <p>[내 개인 픽 + 이유] [댓글 유도 — "여러분이 써본 것 중 좋았던 건?"]</p>
 ```
@@ -360,13 +342,7 @@ npx viruagent-cli publish \
 <p>[맞지 않는 상황도 언급 — 신뢰도 상승]</p>
 <p>&nbsp;</p>
 
-<!-- 내부 링크 -->
-<h2>관련 글</h2>
-<ul>
-  <li><a href="[URL1]">[관련 글 1]</a></li>
-  <li><a href="[URL2]">[관련 글 2]</a></li>
-</ul>
-<p>&nbsp;</p>
+<!-- 내부 링크: 실제 발행된 URL만 사용. 모르면 섹션 전체 생략 -->
 
 <p>[최종 점수나 별점 + 총평 1~2문장]</p>
 ```
@@ -423,13 +399,7 @@ npx viruagent-cli publish \
 </ul>
 <p>&nbsp;</p>
 
-<!-- 내부 링크 -->
-<h2>관련 글</h2>
-<ul>
-  <li><a href="[URL1]">[관련 글 1]</a></li>
-  <li><a href="[URL2]">[관련 글 2]</a></li>
-</ul>
-<p>&nbsp;</p>
+<!-- 내부 링크: 실제 발행된 URL만 사용. 모르면 섹션 전체 생략 -->
 
 <p>[추가 궁금한 점은 댓글로 — 독자 참여 유도]</p>
 ```

package/src/providers/tistory/index.js

@@ -12,7 +12,7 @@ const {
 } = require('./utils');
 const { normalizeThumbnailForPublish } = require('./imageNormalization');
 const { enrichContentWithUploadedImages, resolveMandatoryThumbnail } = require('./imageEnrichment');
-const { createWithProviderSession } = require('./session');
+const { createWithProviderSession, checkAndIncrementRateLimit, getRateLimitStatus } = require('./session');
 const { createAskForAuthentication } = require('./auth');
 
 const createTistoryProvider = ({ sessionPath, account }) => {
@@ -95,6 +95,7 @@ const createTistoryProvider = ({ sessionPath, account }) => {
 
     async publish(payload) {
       return withProviderSession(async () => {
+        checkAndIncrementRateLimit(sessionPath, 'publish');
         const title = payload.title || 'Untitled';
         const rawContent = payload.content || '';
         const visibility = mapVisibility(payload.visibility);
@@ -528,6 +529,14 @@ const createTistoryProvider = ({ sessionPath, account }) => {
       });
     },
 
+    rateLimitStatus() {
+      return {
+        provider: 'tistory',
+        mode: 'rateLimitStatus',
+        ...getRateLimitStatus(sessionPath),
+      };
+    },
+
     async logout() {
       clearProviderMeta('tistory', account);
       return {

package/src/providers/tistory/session.js

@@ -5,6 +5,46 @@ const { sleep, readCredentialsFromEnv, parseSessionError, buildLoginErrorMessage
 const { clickKakaoAccountContinue } = require('./browserHelpers');
 const { extractAllCookies, filterCookies, cookiesToSessionFormat } = require('../chromeManager');
 
+// ── Rate Limit (일일 발행 제한) ──
+const DAILY_LIMIT = { publish: 15 };
+
+const readSessionFile = (sessionPath) => {
+  if (!fs.existsSync(sessionPath)) return null;
+  try { return JSON.parse(fs.readFileSync(sessionPath, 'utf-8')); } catch { return null; }
+};
+const writeSessionFile = (sessionPath, data) => {
+  fs.mkdirSync(path.dirname(sessionPath), { recursive: true });
+  fs.writeFileSync(sessionPath, JSON.stringify(data, null, 2), 'utf-8');
+};
+
+const checkAndIncrementRateLimit = (sessionPath, type) => {
+  const raw = readSessionFile(sessionPath) || {};
+  if (!raw.rateLimits) raw.rateLimits = {};
+  const c = raw.rateLimits[type] || { daily: 0, dayStart: Date.now() };
+
+  const now = Date.now();
+  if (now - c.dayStart > 86400000) { c.daily = 0; c.dayStart = now; }
+
+  const dailyMax = DAILY_LIMIT[type];
+  if (dailyMax && c.daily >= dailyMax) {
+    throw new Error(`daily_limit: ${type} exceeded daily limit of ${dailyMax}. Try again tomorrow.`);
+  }
+
+  c.daily++;
+  raw.rateLimits[type] = { ...c, savedAt: new Date().toISOString() };
+  writeSessionFile(sessionPath, raw);
+};
+
+const getRateLimitStatus = (sessionPath) => {
+  const raw = readSessionFile(sessionPath) || {};
+  const result = {};
+  for (const [type, max] of Object.entries(DAILY_LIMIT)) {
+    const c = raw.rateLimits?.[type] || { daily: 0 };
+    result[type] = { daily: `${c.daily}/${max}` };
+  }
+  return result;
+};
+
 const isLoggedInByCookies = async (context, page) => {
   try {
     // Use CDP to get all cookies including httpOnly (TSSESSION)
@@ -114,4 +154,6 @@ module.exports = {
   waitForLoginFinish,
   persistTistorySession,
   createWithProviderSession,
+  checkAndIncrementRateLimit,
+  getRateLimitStatus,
 };