작업 공간 도구

웹 채팅의 모델이 대화에 묶인 GitLab 프로젝트에서 evo workflow·git·glab·파일을 쓰는 방법을 적는다. 도구는 모델에게 함수로 노출되고, 실행은 서버가 workspace-runner.md 의 /v1/* API 로 넘긴다. 토큰·인증은 workspace-token.md 를 따른다.

1. 켜는 조건

조건	설명
WORKSPACE_ENABLED=true	작업 공간 기능.
WORKSPACE_RUNNER_URL·WORKSPACE_RUNNER_TOKEN	실행기 주소(http/https)와 서비스 토큰.
기능 권한 workspace	사용자의 역할(또는 그룹 역할)에 있어야 한다. 기본 역할에는 넣지 않는다(기본 꺼짐). 관리자는 항상 쓸 수 있다.

셋 중 하나라도 없으면 도구 목록이 비어 모델에게 아무것도 노출되지 않는다(채팅은 그대로 동작한다).

환경 변수	기본값	설명
WORKSPACE_RUNNER_URL	(비움)	실행기 주소. http(s) 가 아니거나 토큰이 없으면 기동 때 경고만 남기고 도구를 내보내지 않는다.
WORKSPACE_RUNNER_TOKEN	(비움)	실행기 서비스 토큰(Bearer). 비밀 — 문서·로그·이슈·MR 에 값을 적지 않는다.
WORKSPACE_RUNNER_TIMEOUT	180s	실행기 호출 한 번의 대기 상한.
WORKSPACE_MAX_FILE_WRITE_BYTES	262144	모델이 파일 하나에 쓸 수 있는 최대 바이트(256 KiB).

2. 대화 ↔ 프로젝트 묶기

도구는 대화마다 하나의 프로젝트를 작업 공간으로 쓴다(conversation_workspaces, V28).

• workspace_open(project, base_branch?) — 프로젝트(group/project)를 이 대화에 묶고 clone·worktree 를 준비한다. 승인이 필요하다(원격 읽기 + 로컬 쓰기). 주소는 받지 않는다 — 서버가 WORKSPACE_GITLAB_HOST 와 검증한 프로젝트 경로로 만든다.
• 프로젝트 경로는 group/project 형식만 받는다(2~10 조각). 주소·..·.git·//·공백·:·@ 는 거절한다.
• 기본 브랜치는 main 이다. 대화의 작업 브랜치는 chat/<대화 id> 이고 push 는 이 브랜치만 올린다.
• workspace_info — 묶인 프로젝트·폴더·브랜치를 승인 없이 보여 준다.
• 묶인 프로젝트가 없으면 다른 도구는 no_workspace 로 실패하고 workspace_open 을 안내한다.

3. 도구 목록

도구	동작	승인
workspace_open	프로젝트 묶기 + clone·worktree 준비	필요
workspace_info	묶인 프로젝트 확인	없음
workspace_file_read	worktree 안 파일 읽기(텍스트)	없음
workspace_file_write	worktree 안 파일 쓰기(UT, 덮어씀)	필요 — diff 표시
git_workspace	status·diff·log·branch_list / branch_create·stage·commit·push	앞은 없음, 뒤는 필요
glab_workspace	issue_list·issue_view·mr_list·mr_view / mr_create	앞은 없음, mr_create 만 필요
evo_workflow	status·list·show·search·validate·issue draft/publish/lifecycle	issue 만 필요

3.1 evo workflow 허용 목록

• 실행 파일은 evo-workflow 하나이고, 첫 인자(하위 명령)가 status·list·show·search·validate·issue 중 하나여야 한다.
• issue 는 두 번째 인자가 draft·publish·lifecycle 중 하나여야 한다.
• --yes·--yes=…·--session-agent·--session-agent=… 는 어느 위치에도 쓸 수 없다(서버가 거절).
• 서버는 사용자가 등록한 에이전트 ID(workspace_agent_ids)를 issue draft·publish 실행에만 --session-agent 로 붙인다. 다른 하위 명령에는 붙이지 않는다(evo 가 받지 않는다).
• issue publish 를 --yes 없이 실행하면 확인 대기로 기록되어 사람 확인 화면에 뜬다 — workspace-human-confirm.md.
• init·new·upgrade·bootstrap 은 첫 인자 허용 목록에 없어 거절된다. 제목·본문 같은 나머지 인자는 데이터이므로 new 같은 낱말을 막지 않는다.
• 인자는 1~50개, 하나 2000자 이하, 전체 8000자 이하. NUL·제어문자(줄바꿈·탭 제외)는 거절한다.

3.2 git·glab

• git 은 정해진 인자만 조립한다. branch_create 는 main·chat/ 접두 이름을 거절하고, stage 경로는 worktree 상대 경로만 받는다.
• push 는 서버가 대화 브랜치(chat/<대화 id>)만 올린다 — 모델이 브랜치나 원격을 고르지 않는다.
• glab 은 조회와 MR 생성만 있다. glab auth status -t(토큰 노출)·glab api(임의 API 호출)는 도구에 아예 없다.
• mr_create 는 source 를 chat/<대화 id>, target 을 기본 브랜치(또는 지정 브랜치)로 고정한다.

3.3 파일

• 경로는 worktree 안 상대 경로만 받는다. 절대 경로·\·..·빈 조각·NUL 은 거절한다(runner 가 홈 기준으로 다시 검사한다).
• 읽기는 바이너리·너무 큰 파일이면 내용 대신 크기와 이유(binary·too_large)만 돌려준다.
• 쓰기는 content 가 UT 텍스트여야 하고 상한(WORKSPACE_MAX_FILE_WRITE_BYTES)을 넘으면 거절한다. 기존 파일이면 미리 읽어 diff 를 만들어 승인 화면에 싣는다. 파일이 없으면 /dev/null 기준 diff 다.

4. 승인

• 쓰기·네트워크 동작은 승인 흐름을 그대로 쓴다: 승인 id 발급 → 화면에 동작·인자 표시 → 사용자가 승인해야 실행. 거부되거나 120초가 지나면 실행하지 않고 모델에 거부를 알린다(모델은 사용자가 다시 요청하기 전까지 재시도하지 않는다).
• 인자 검증은 승인 전에 한다 — 잘못된 인자로 승인을 묻지 않는다.
• 파일 쓰기 승인에는 path·bytes·diff 가, git·glab·evo 승인에는 조립한 command 가 보인다.

5. 출력 가림과 감사

• 모델에게 돌려주는 모든 출력(파일 내용·stdout·stderr·diff·오류 메시지)에서 토큰 모양 문자열을 가린다: glpat-·glrt- 등 GitLab 토큰 접두, Authorization: Bearer|Basic, PRIVATE-TOKEN, JWT, AWS·Slack 키, token|password|secret|api-key=… 형태, 그리고 설정에 있는 토큰 원문.
• 감사(mcp.tool.call)에는 도구·동작 이름·승인 여부·결과·오류 코드만 남긴다. 경로·인자·파일 내용·토큰은 넣지 않는다.
• 실행기 호출이 실패하면 runner 의 오류 코드를 그대로 쓰되(no_workspace·busy·disk_quota·timeout·unauthorized 등) 주소·토큰은 메시지에 넣지 않는다.

6. 아직 없는 것

• 사용자 파일 창(내 작업 공간의 사용량·파일 보기·삭제·초기화)은 으로 추가했다 — workspace-user-window.md.
• 사람 확인 화면(이슈 게시·에이전트 ID 등록·MR 머지)은 으로 추가했다 — workspace-human-confirm.md.
• 관리자 사용자 관리의 작업 공간 사용량·초기화와 계정 삭제 연동은 로 추가했다 — workspace-admin.md.
• 사용자별 GitLab 토큰(나머지)과 실행기 이미지 구성은 각 문서를 따른다.