에이전트용 안내

이 문서는 AI 에이전트가 읽도록 쓴 규격입니다. 사람이 읽는 설명은 소개와 아키텍처, 사용법에 있습니다. 같은 내용을 일반 텍스트로 받으려면 /docs/agents.md, 모든 문서를 한 번에 받으려면 /llms-full.txt 를 요청하세요.

0. 요약 (먼저 읽기)

• 이름: tecace-colleague · 현재 버전: 0.7.0 · 소유: TecAce
• 종류: Microsoft Teams 봇 (Bot Framework). HTTP API 로 질문을 보낼 수 없습니다. 입력 경로는 Teams 메시지 하나뿐입니다.
• 허용 사용자: TecAce Microsoft 365 테넌트의 Teams 사용자. 다른 테넌트, Teams 가 아닌 채널(웹 채팅 등)의 요청은 거부합니다.
• 응답: 같은 Teams 대화에 Markdown 텍스트 메시지로 답합니다. 먼저 자리표시 메시지를 보낸 뒤 같은 메시지를 수정해 최종 답으로 바꿉니다.
• 기억: 없음. 요청 하나가 독립된 한 번의 실행입니다. 앞선 대화 내용을 참조하지 않습니다.
• 상태 확인: GET /api/health → {"ok":true,"version":"0.7.0","commit":"<git sha>"}

1. 공개 엔드포인트

메서드·경로	인증	용도
GET /docs, /docs/usage, /docs/agents, /docs/changelog	없음	사람용 HTML 문서
GET /docs/agents.md	없음	이 문서 (text/markdown)
GET /llms.txt	없음	문서 색인 (llmstxt.org 형식)
GET /llms-full.txt	없음	모든 문서 + 최근 변경 기록 (text/plain)
GET /api/health	없음	살아 있는지, 배포된 버전·커밋
POST /api/messages	Bot Framework JWT	Teams 메시지 수신 전용. 직접 호출하면 401
/admin/*	Basic 인증 (관리자)	운영 화면. 에이전트가 쓸 곳이 아님
/api/axkh/*, /api/auth/*, /api/files/*	서명된 일회성 링크	로그인 콜백, 결과 파일 내려받기

2. 호출 방법

2.1 사람이 쓰는 경로

Teams 1:1 채팅에 텍스트를 보내거나, 채널·그룹 채팅에서 @tecace-colleague 로 멘션합니다. 멘션 텍스트(<at>…</at>)와 HTML 은 제거된 뒤 처리됩니다.

2.2 다른 에이전트가 쓰는 경로

• Teams 는 봇이 보낸 메시지를 다른 봇에게 전달하지 않습니다. 다른 봇이 채널에서 @tecace-colleague 를 멘션해도 이 서비스는 받지 못합니다.
• 에이전트가 호출하려면 TecAce 사용자 계정의 위임 권한으로(예: Microsoft Graph 의 채팅 메시지 전송) 그 사용자와 tecace-colleague 의 1:1 채팅 또는 채널에 메시지를 보내야 합니다. 이때 요청자는 그 사용자이고, 사내 지식은 그 사용자의 AXKH 권한으로 조회됩니다. 이 경로는 운영에서 검증되지 않았습니다.
• 응답 읽기: 봇의 첫 메시지는 _생각하는 중…_ 처럼 밑줄(이탤릭)로 감싼 자리표시입니다. 진행 중에는 _AXKH 검색…_, _웹 검색…_ 처럼 바뀝니다. 메시지가 _…_ 형태가 아니게 수정되면 최종 답입니다. 답이 20,000자를 넘으면 이어지는 메시지로 나뉘어 옵니다.
• 시간: 대부분 수십 초, 도구를 많이 쓰면 몇 분. 한 요청의 실행은 최대 약 5분입니다.

3. 입력 문법

입력은 앞에서부터 아래 순서로 해석됩니다. 대소문자는 구분하지 않습니다.

/version                         → 버전·문서 링크를 답하고 끝 (모델 호출 없음)
/help                            → 사용법 안내를 답하고 끝 (모델 호출 없음)
/public <나머지>                  → 공개 모드로 강제. <나머지>를 계속 해석
/model <모델>                     → 이 대화방 기본 모델 저장 후 확인 메시지로 끝
/model <모델> <질문>               → 이번 요청만 <모델>
[<모델>] <질문>                    → 이번 요청만 <모델>
<모델>로 <질문> | <모델>으로 <질문>   → 이번 요청만 <모델>
<질문>                           → 대화방 기본 모델(없으면 sonnet)

<모델> 허용값: sonnet = claude = claude-sonnet-5-5, opus = claude-opus-5-5, haiku = claude-haiku-5-5. 그 밖의 값은 모델 지시로 인식하지 않고 질문의 일부로 취급합니다. 기본 모델이 실패하면, 아직 도구가 하나도 실행되지 않은 경우에만 대체 모델(claude-opus-5-5)로 한 번 다시 시도하고 답 끝에 그 사실을 적습니다.

4. 보안 모드 결정

conversationType == "personal" 이고 /public 이 아님  → protected (보호)
그 밖 (channel, groupChat, 알 수 없음, /public)       → public (공개)

4.1 모드별 도구

도구 이름	보호	공개	설명
search_nodes	✓		AXKH 검색 (요청자 AXKH ACL 적용)
get_node	✓		AXKH 문서 본문
add_knowledge	✓		AXKH 지식 저장. 2단계 확인. 개인(personal)만 허용, 팀 공유는 차단
load_skill	✓ (지침만)	✓	스킬 지침 불러오기
web_search		✓	Anthropic 웹 검색, 요청당 최대 5회
run_command		✓	격리된 Linux 작업 공간에서 셸 명령 (명령당 5~240초)
write_file, read_file		✓	작업 공간 파일
share_file		✓	결과 파일을 24시간 서명 링크로 전달 (최대 8MB)
mcp_<연결 id>_<도구>_<해시>		✓	관리자가 등록·시험·공개 지정하고 readOnlyHint 가 있는 MCP 도구만

다른 AXKH 도구(ask_knowledge_base, get_context 등)는 보호 모드에서도 노출하지 않습니다. 모델이 목록에 없는 도구를 요청할 방법은 없습니다.

4.2 AXKH 연결 상태

보호 모드에서 요청자의 AXKH 토큰이 없거나 만료되면 AXKH 연결 카드(Adaptive Card, 버튼 "AXKH 연결하기")를 보내고, AXKH 없이 일반 지식으로 답할 수 있는 부분만 답합니다. 연결 링크는 10분 유효, 요청자 본인 전용입니다. 연결 순서: Entra 로그인(Teams 사용자 oid 일치 확인) → AXKH 동의 → 완료 페이지. 연결 뒤 질문을 다시 보내야 합니다.

5. 출력 형식

• 한국어 Teams Markdown(굵게, 목록, 표, 링크). 결론 먼저, 근거 뒤.
• AXKH 를 근거로 쓰면 문서 제목에 AXKH 노드 URL 링크를 걸고, 끝에 참고 문서 목록을 둡니다. AXKH 노드 페이지는 로그인한 TecAce 구성원만 열 수 있습니다.
• 파일은 …/api/files/<id>?exp=…&sig=… 링크로 전달됩니다. 24시간 뒤 만료.

5.1 고정 메시지 (문자열 그대로)

상황	메시지
처리 시작	_생각하는 중…_
Azure AD 사용자 ID 없음	TecAce 계정으로 로그인한 사용자만 tecace-colleague를 쓸 수 있습니다.
권한·정책 확인 실패 (차단)	현재 권한·게시 범위 또는 정책이 확인되지 않아 요청을 중단했습니다. 승인되지 않은 자료나 이전 답변은 사용하지 않았습니다.
그 밖의 실패	처리 중 오류가 발생했습니다. 외부 작업의 처리 여부를 확인한 뒤 다시 요청해 주세요.
기본 모델 변경	이 대화의 기본 모델을 **<모델 이름>** 로 바꿨습니다.

6. 승인 카드

규칙에 걸린 도구 호출은 실행 대신 승인이 필요한 작업 카드(버튼 "승인", "거절")를 보냅니다. 현재 규칙: add_knowledge 2단계(confirm:true) 중 visibility:"shared".

• 승인은 요청자 본인이, 카드를 만든 그 1:1 대화에서만 할 수 있습니다. 다른 사람·다른 대화에서는 거부됩니다.
• 상태 전환은 원자적이며 한 번만 실행됩니다. 이미 처리된 카드: 이미 처리된 승인 요청입니다.
• 팀 공유 게시는 현재 차단되어 승인해도 실행되지 않습니다: 현재 권한으로 승인 작업을 실행하지 못했습니다. 보호 자료의 팀 공유는 게시 범위 검토가 필요합니다.

7. 연동 지점 (운영자·개발 에이전트용)

7.1 스킬 추가

• 파일 스킬: 저장소 skills/<name>/SKILL.md. frontmatter name, description, 선택 preferred_model. 모델은 먼저 이름과 설명만 보고, 필요할 때 load_skill 로 본문을 읽습니다.
• 관리 화면 스킬: /admin/skills 에서 이름([a-z][a-z0-9-]{1,63}), 설명(≤600자), 지침(≤24,000자)을 저장합니다. 버전이 붙고 동시 수정은 낙관적 잠금으로 막습니다.
• 공개 모드에서는 스킬 파일이 작업 공간 /vercel/sandbox/skills/<name> 에 올라가 스크립트를 실행할 수 있습니다.

7.2 MCP 서버 추가

/admin/connections 에서 등록합니다. 공개 모드에 노출되는 조건(모두 만족): HTTPS · 호스트가 서버 설정 MCP_ALLOWED_HOSTS 에 있음 · 리다이렉트·출처 변경 없음 · 자격 증명은 MCP_SECRET_* 환경 변수 참조로만 · 연결 활성화·시험 통과·공개 지정·자격 증명 없음 · 도구를 관리자가 허용 목록에 넣음 · 도구에 readOnlyHint: true. 되돌리기 어려운 도구를 붙이려면 코드(lib/agent/approvals.ts 의 RULES)에 승인 규칙을 먼저 추가해야 합니다.

7.3 이 저장소를 수정하는 에이전트

• 개발 규칙과 보안 불변식: 저장소 루트 CLAUDE.md, docs/HR_SECURITY.md.
• 기능을 바꾸면 반드시: package.json 버전을 올리고 → CHANGELOG.md 맨 위에 항목 추가 → 부 버전이 오르면 docs/site/*.md 세 문서를 검토해 내용을 고치고 frontmatter reviewed 를 새 부 버전으로 바꿉니다. npm test 와 CI 가 이를 검사해 어기면 배포가 막힙니다.
• 검증: npm test, npm run typecheck, npm run build.

8. 하지 않는 것 (답할 때 틀리지 말 것)

• 이전 대화·다른 사람 대화를 기억하거나 참조하지 않습니다.
• 채널·그룹 채팅에서 AXKH 사내 자료를 읽지 않습니다. 제목·링크·요약도 내보내지 않습니다.
• 보호 모드에서 웹 검색, 코드 실행, 파일 링크를 쓰지 않습니다.
• HR HUB 보안 등급 확인은 현재 꺼져 있습니다(코드는 남아 있음). 보호 모드의 접근 기준은 AXKH 원본 ACL 뿐입니다.
• 질문·답변·도구 입출력 원문을 운영 기록에 저장하지 않습니다. 처리 시간·토큰 수·상태만 남깁니다.
• 비밀번호·API 키·토큰을 묻거나 출력하지 않습니다.

9. 버전 정책

• 유의적 버전. 부(minor) 버전 = 기능·동작 변경, 수(patch) 버전 = 동작을 바꾸지 않는 수정.
• 이 문서 머리의 reviewed 값은 이 문서가 마지막으로 검토된 부 버전입니다. 현재 버전의 부 버전과 같으면 최신입니다.
• 변경 내용: 버전 기록 또는 /llms-full.txt 끝의 최근 변경 기록.