# 에이전트용 안내

> tecace-colleague 를 호출하거나, 연동하거나, 이 서비스에 대해 답해야 하는 AI 에이전트를 위한 정확한 동작 규격입니다.

이 문서는 AI 에이전트가 읽도록 쓴 규격입니다. 사람이 읽는 설명은 [소개와 아키텍처](https://colleague.srv1153481.hstgr.cloud/docs), [사용법](https://colleague.srv1153481.hstgr.cloud/docs/usage)에 있습니다. 같은 내용을 일반 텍스트로 받으려면 `/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` 값은 이 문서가 마지막으로 검토된 부 버전입니다. 현재 버전의 부 버전과 같으면 최신입니다.
- 변경 내용: [버전 기록](https://colleague.srv1153481.hstgr.cloud/docs/changelog) 또는 `/llms-full.txt` 끝의 최근 변경 기록.