Docs · v0.7.0

tecace-colleague 소개와 아키텍처

무엇을 하는 서비스인지, 요청이 어떤 경로로 처리되는지, 어떤 보안 경계가 있는지 설명합니다.

문서 검토 버전 0.7

tecace-colleague 는 TecAce 직원이 Microsoft Teams 에서 부르는 AI 동료입니다. Teams 에서 @tecace-colleague 로 부르면 Claude 가 답하고, 1:1 대화에서는 요청자 본인의 AXKH(사내 지식허브) 권한으로 사내 자료를 찾아 근거와 함께 답합니다.

현재 버전: 0.7.0 · 변경 내용은 버전 기록에서 확인합니다.

한눈에 보기

항목	내용
부르는 곳	Microsoft Teams 1:1 채팅, 그룹 채팅, 팀 채널 (TecAce 테넌트 사용자만)
부르는 방법	`@tecace-colleague 질문` (1:1 에서는 멘션 없이 바로 입력)
답하는 모델	Claude Sonnet 5.5 (기본), Claude Opus 5.5 (요청 시·대체), Claude Haiku 5.5
사내 지식	AXKH. 1:1 에서만, 요청자 본인의 AXKH 로그인 권한으로 조회
그 밖의 도구	웹 검색, 회사 스킬, 격리된 Linux 작업 공간(코드 실행·파일 작업), 관리자가 승인한 읽기 전용 MCP 도구
운영 화면	`/admin` (관리자 로그인 필요): 설치 점검, 스킬, MCP 연결, Activity, 성능
공개 문서	`/docs` (이 사이트), 에이전트용 일반 텍스트 `/llms.txt`

무엇을 잘하나

사내 지식 질문: "고객 A 프로젝트 현재 상태 알려줘" → AXKH 에서 본인이 볼 수 있는 문서만 찾아 요약하고, 문서 링크를 "참고 문서"로 붙입니다.
지식 저장: "이 내용 내 AXKH 메모로 저장해줘" → 확인 질문을 거쳐 개인 지식으로 저장합니다.
조사·작성: 채널이나 /public 요청에서는 웹 검색과 작업 공간으로 자료를 찾고, 문서·표·코드를 만들어 24시간 유효한 파일 링크로 전달합니다.
반복 업무: 관리자가 등록한 스킬(회사 업무 절차)을 요청에 맞게 불러와 따릅니다.

아키텍처

요청 하나가 처리되는 경로. 보호 모드와 공개 모드는 서로 다른 도구만 받습니다.

요청 처리 순서

받기 (/api/messages): Bot Framework 가 서명한 JWT 를 검증하고, serviceurl 이 토큰과 일치하는지, 채널이 msteams 이고 TecAce 테넌트인지 확인합니다. 통과하면 바로 200 을 돌려주고 나머지는 뒤에서 처리합니다.
자리표시: Teams 에 "생각하는 중…" 을 먼저 보내고, 도구를 쓸 때마다 "AXKH 검색…" 처럼 진행 상황으로 바꿉니다.
명령 해석: /model, [opus], /public, /version, /help 같은 명령을 먼저 처리합니다.
보안 모드 선택: 1:1 이고 /public 이 아니면 보호 모드, 나머지는 공개 모드입니다.
도구 준비: 모드에 허용된 도구만 모델에게 줍니다. 모델이 다른 도구를 요청할 방법은 없습니다.
답변 생성: Claude 가 최대 40단계까지 도구를 쓰며 답을 만듭니다. 기본 모델이 실패하면, 아직 아무 도구도 실행되지 않은 경우에만 대체 모델로 한 번 더 시도합니다(외부 작업이 두 번 실행되지 않도록).
답하기: 자리표시 메시지를 답으로 바꿉니다. 길면 Teams 한도에 맞춰 나눠 보냅니다.
기록: 처리 시간, 토큰 수, 성공·실패·차단 여부만 agent_runs 에 남깁니다. 질문·답변·도구 입출력 원문은 남기지 않습니다.

보안 모드

	보호 모드	공개 모드
언제	Teams 1:1 대화 (`/public` 없이)	채널, 그룹 채팅, 알 수 없는 대화 유형, `/public` 요청
사내 지식(AXKH)	요청자 본인 권한으로 조회	사용하지 않음
웹 검색	없음	있음
작업 공간·파일 링크	없음	있음
스킬	지침 읽기만	지침 + 스킬 파일을 작업 공간에 올려 실행
추가 MCP 도구	없음	관리자가 승인한 읽기 전용 도구만

왜 나누나: 채널에 있는 모든 사람이 답을 봅니다. 요청자 한 명의 권한으로 읽은 사내 자료가 권한 없는 동료에게 보이지 않도록, 채널·그룹에서는 사내 지식 도구 자체를 주지 않습니다. 사내 자료를 읽는 동안 웹 검색·외부 명령을 막는 것은 자료가 외부로 새는 경로를 없애기 위해서입니다.

지키는 원칙

권한은 코드로 강제합니다. 프롬프트로 "보여 주지 마"라고 하는 대신, 허용되지 않은 도구와 결과를 모델에게 아예 주지 않습니다. AXKH 의 원본 접근 권한(ACL)이 최종 기준입니다.
확인이 안 되면 막습니다. 권한·정책이 확인되지 않으면 요청을 중단하고 "현재 권한·게시 범위 또는 정책이 확인되지 않아 요청을 중단했습니다"라고 답합니다.
되돌리기 어려운 작업은 승인 카드. AXKH 팀 공유 저장 같은 작업은 요청자 본인이 같은 1:1 대화에서 승인해야 실행됩니다. 승인은 한 번만 처리됩니다. 현재 팀 공유 게시는 공개 범위 검토 절차가 마련될 때까지 막혀 있고, 개인 지식 저장만 됩니다.
비밀값은 암호화. AXKH 토큰과 갱신 토큰은 AES-256-GCM 으로 암호화해 저장합니다. 로그에는 오류 코드만 남깁니다.

구성 요소

구성 요소	역할
Next.js 16 웹 앱	Teams 메시지 수신, 에이전트 실행, 관리 화면, 이 문서 사이트
Hostinger VPS + Docker + Traefik	운영 서버. HTTPS 종단, 무중단 교체 배포
GitHub Actions + GHCR	PR 은 검사(typecheck·test·build·버전 확인), `main` 은 이미지 빌드 후 VPS 배포
Neon Postgres	암호화된 토큰, 승인 대기 작업, 스킬·MCP 설정, 채널별 기본 모델, 실행 기록, 임시 결과 파일
Anthropic API	Claude 모델, 웹 검색 서버 도구
AXKH (MCP + OAuth)	사내 지식. 사용자별 OAuth(PKCE, 동적 클라이언트 등록)
Microsoft Entra ID	AXKH 로그인 전에 Teams 사용자와 같은 사람인지 확인(oid 일치)
Vercel Sandbox	공개 모드의 격리된 Linux 작업 공간 (15분 유지, 명령당 최대 240초)

현재 한계

대화를 기억하지 않습니다. 매 요청을 처음 듣는 것처럼 처리합니다. 앞선 대화 내용이 필요하면 질문에 다시 적어 주세요. 출처별 권한 검증을 갖춘 기억 기능을 설계 중입니다.
HR HUB 보안 등급 확인이 꺼져 있습니다. 보호 모드는 AXKH 원본 권한만 적용합니다.
채널·그룹에서는 사내 지식을 쓰지 않습니다. 사내 자료가 필요하면 1:1 로 요청합니다.
직접 호출 API 가 없습니다. 사람과 다른 에이전트 모두 Teams 대화로 사용합니다. 자세한 내용은 에이전트용 안내를 봅니다.