로그인·수집 상태와 백그라운드 수집 데몬 상태를 반환합니다.

status(healthy/degraded/failed)와 last_error.code 를 보고 문제가 있으면 recovery.instruction/command 를 사용자에게 안내하세요(예: telegramlens-doctor).

더 오래된 과거 데이터를 소급 수집하도록 백그라운드 데몬에 요청합니다.

자동 수집은 기본 7일까지. 더 오래 비웠을 때(telegram_status 의 backfill_offer) 사용자 동의 시에만 호출하세요. 무거운 작업이라 동의 없이 호출 금지.

Args: days: 소급 수집할 일수(1~90). 예: 14면 최근 14일치.

과거 데이터 추가 수집 제안을 거절(제안 플래그 제거)합니다.

데일리 브리핑 등을 사용자 본인 텔레그램 'Saved Messages(나에게)'로 전송합니다.

• messages: plain-text 문자열 리스트. 각 원소 = 텔레그램 메시지 1개. 예) telegram_send_me(["오늘 시황 요약 ...", "버즈: 많이 언급 vs 급증 ..."])

• 마크다운/HTML 미적용 — 텔레그램에 기호가 그대로 보이므로 plain text 로 작성(별표·표 금지).

• 수신자는 항상 본인(Saved Messages)으로 고정 — 남에게는 보낼 수 없습니다(ToS 안전).

• 전송은 수집 데몬을 통해 이뤄집니다(수집용 세션과 충돌 방지). 데몬 미가동이면 에러 반환.

• 4096자 초과 메시지는 자동 분할. 반환: 성공 여부 + 전송된 메시지 수.

'아침 주식 비서'처럼 스케줄(매일 07:00) 작업에서 브리핑을 작성해 이 도구로 보냅니다. 내용·개수·구성(시황/버즈/시세/공시)은 호출하는 쪽에서 자유롭게 정합니다.

★ 한 번에 완성해 단 한 번만 호출하세요. 보내기 전에 한글 오타·깨진 글자를 검토하고, 전송 후에는 어떤 경우에도 재발송/정정 재호출하지 마세요(중복 메시지 방지). ★ 수치·사실은 데이터(텔레그램 원문/도구 결과)에 있는 것만 쓰세요. 출처에 없는 숫자를 지어내지 말고, 가능하면 근거 채널/원문을 함께 밝히세요.

최근 N분간의 텔레그램 메시지를 수집·구조화해 로컬 DB에 저장합니다.

평소엔 백그라운드 수집 데몬이 DB를 채우므로 수동 호출은 보통 불필요합니다. 데몬이 가동 중이면 그쪽이 텔레그램 세션을 소유하므로(동시 접속 시 충돌) 직접 sync는 건너뛰고 DB 신선도만 보고합니다. 데몬이 없을 때만 직접 1회 수집합니다.

Args: minutes: 수집 대상 시간 범위(분). 기본 60. per_channel_limit: 채널당 최대 조회 메시지 수. 기본 500.

기간 내 텔레그램 언급량 상위 종목을 반환합니다.

종목코드 매칭 전용 — 거시·지정학·테마(예: "미국 이란", "금리") 질문은 telegram_search 사용.

Args: hours: 집계 시간 범위(시간). 기본 24. top: 상위 N개. 기본 20. kind: 종목 종류 — "stock"(개별주만)/"etf"(ETF만)/"all"(전체). 기본 all.

최근 언급이 기준 구간 대비 급증한 종목(새 내러티브)을 반환합니다.

종목코드 매칭 전용 — 거시·지정학·테마(예: "미국 이란", "금리") 질문은 telegram_search 사용.

Args: hours: 최근 구간(시간). 기본 6. baseline_hours: 비교 기준 구간(시간). 기본 72. top: 상위 N개. 기본 15. kind: 종목 종류 — "stock"(개별주만)/"etf"(ETF만)/"all"(전체). 기본 all.

'오늘 브리핑 / 장전 / (텔레그램) 시황 / 시장 브리핑' 등을 요청받으면 호출하세요.

시장 브리핑용 텔레그램 언급 데이터를 한 번에 모아 반환합니다:

• trending_많이언급: 기간 내 '많이 언급된' 종목

• momentum_급증: 평소 대비 '갑자기 급증한' 종목(새 내러티브)

반환값의 _playbook 지침대로 plain-text 메시지를 작성해 telegram_send_me 로 '한 번만' 보내세요. 내용 작성·전송 규칙은 _playbook 과 telegram_send_me docstring 을 따르세요.

Args: hours: 집계 시간 범위(시간). 장전이면 12 권장(간밤~아침). 기본 12.

'내 종목/보유 종목'이 텔레그램에서 어떻게 거론되는지 — 언급 원문·요약 근거를 반환합니다.

'내 종목 분석/소식/여론/뭐래/텔레그램에서 어때' 류 요청에 호출하세요. 종가·차트·이동평균· 기술지표가 아니라 텔레그램에서 그 종목을 두고 무슨 말이 도는지(원문·채널·링크)를 줍니다. 이 데이터로 종목별 '여론·이슈'를 요약하세요(기술지표는 사용자가 원할 때만 StockLens 로). 종목 등록/삭제는 텔레그램 '!보유 설정 …' 명령으로.

Args: hours: 집계 시간 범위(시간). 기본 24.

종목별 언급의 시간대별 흐름과 급등(velocity)을 반환합니다.

시간 버킷별 독립 언급을 집계해 직전 대비 증가율과 spike 여부를 봅니다. 베이스라인 배율(baseline_ratio) 동봉.

Args: query: 종목명/6자리 코드(생략 시 velocity 상위 top 종목). bucket_minutes: 시간 버킷 크기(분). 기본 30. window_hours: 집계 윈도우(시간). 기본 6. spike_min: 최근 버킷 급등 임계값(건수). 기본 5. top: query 미지정 시 상위 N개. 기본 15.

특정 종목의 버즈 전개(타임라인)를 반환합니다.

이 종목이 언제 어느 채널에서 처음 터져 어떻게 번졌나(종단): 최초 언급 채널·시각, 시간대별 독립 언급·확산 채널 수·velocity·베이스라인 배율·원문 샘플.

종목코드 매칭 전용 — 거시·지정학·테마(예: "미국 이란", "금리") 질문은 telegram_search 사용.

Args: query: 종목명 또는 6자리 종목코드. hours: 윈도우(시간). 기본 72. bucket_minutes: 시간 버킷 크기(분). 기본 60.

종목별 종합 버즈 스코어(독립언급×tier×확산×velocity). 감성·유형 필터 지원.

종목코드 매칭 전용 — 거시·지정학·테마(예: "미국 이란", "금리") 질문은 telegram_search 사용.

Args: window_hours: 집계 윈도우(시간). 기본 24. only_types: 포함할 메시지 유형(예: ["report"]). 생략 시 전체. exclude_gossip: only_types 미지정 시 gossip 제외. 기본 False. sentiment: positive/negative/neutral 중 하나만. 생략 시 전체. top: 상위 N개. 기본 20. kind: 종목 종류 — "stock"(개별주만)/"etf"(ETF만)/"all"(전체). 기본 all.

특정 종목의 텔레그램 언급 요약과 원문 샘플을 반환합니다.

Args: query: 종목명 또는 6자리 종목코드. hours: 집계 시간 범위(시간). 기본 24. samples: 원문 샘플 개수. 기본 8.

원문 메시지를 그대로 조회합니다(drill-down).

Args: channel: 채널 username(@ 제외). 생략 시 전체 채널. hours: 시간 범위(시간). 기본 6. limit: 최대 메시지 수. 기본 30.

원문 메시지를 키워드/주제로 전문검색합니다('내용' 축 도구).

종목코드가 안 붙은 거시·산업·테마 글도 본문 키워드로 찾습니다(예: "반도체 HBM", "금리 인하"). 여러 단어는 공백 구분 AND 매칭, 3글자 이상이 정확·빠름.

Args: query: 검색 키워드(여러 단어는 공백 구분, AND 매칭). hours: 검색 시간 범위(시간). 기본 72. limit: 최대 결과 수. 기본 30. channel: 특정 채널 username(@ 제외)으로 한정. 생략 시 전체.

가입한 모든 채널을 스캔해 채널별 '종목 언급 밀도'를 측정·리포트합니다.

어느 채널이 종목 위주이고 어느 채널이 거시·잡담 위주인지 보여주는 진단 도구. 수집 대상을 제한하지는 않습니다(전 채널 자동 포함). 전 채널을 훑어 느리니 필요할 때만.

Args: sample: 채널당 샘플링 메시지 수. 기본 80. threshold: 주식채널 판정 밀도(0~1). 기본 0.05(5%). min_mentions: 최소 누적 언급 수. 기본 3.

수집된 채널 목록과 채널별 누적 메시지 수·tier(분류)·weight 를 반환합니다.

채널 tier(성격)를 수동 지정합니다. 자동시드를 덮어쓰며 이후 재시드가 보존합니다.

tier 는 버즈 집계의 채널 가중치 근거입니다.

Args: channel: 채널 username(@ 제외) 또는 6자리가 아닌 숫자 channel_id. tier: analyst(애널리스트) | research(독립리서치) | info(종합·속보) | gossip(찌라시). weight: 가중 계수(생략 시 기본 analyst1.0/research0.8/info0.5/gossip0.3). note: 메모(선택).

오탐(잘못 잡힌 종목명) 후보를 반환합니다.

코드 없이 이름만으로 자주 잡힌 짧은 종목명 → 일반명사/은어 충돌 의심. 검토 후 telegram_block_name 으로 차단 목록에 추가하세요.

Args: days: 분석 기간(일). 기본 7. max_name_len: 검사할 최대 이름 길이. 기본 3. min_count: 최소 이름단독 매칭 수. 기본 3. top: 상위 N개. 기본 40.

누락된 별칭 후보를 반환합니다.

텍스트에 이름(123456) 형태로 나오지만 현재 사전이 그 이름을 해당 코드로 매칭하지 못하는 토큰. 코드가 정답을 알려주므로 고정밀. 검토 후 telegram_add_alias 로 등록하세요.

Args: days: 분석 기간(일). 기본 7. min_count: 최소 등장 횟수. 기본 2. top: 상위 N개. 기본 40.

별칭을 사전에 등록합니다(통용어/약어 → 6자리 코드). 즉시 반영됩니다.

Args: alias: 텔레그램에서 쓰이는 통용어/약어 (예: 현대차). code: 6자리 종목코드 (예: 005380).

종목을 모호어 차단 목록에 추가합니다(이름 단독 매칭 차단, 코드 동반 시만 인정).

Args: code: 6자리 종목코드 (예: 001680). note: 메모(예: '대상 = target/object 충돌').