전체 문서
이 페이지 목차
설정 계약과 우선순위
ARTEX 설정은 실행 flag, process 환경변수, config.json, PostgreSQL settings, LLM profile, agent/task override로 나뉜다. 저장 위치가 같아도 읽는 시점과 적용 방식은 다르다. 전체 이름·타입·기본값·소비자는 런타임 설정 전수표, 빌드와 배포 입력은 의존성·빌드 계약을 본다. config loader
Mermaid 원문
flowchart LR
CLI[process flags] --> Boot[process bootstrap]
Env[environment] --> Boot
File[config.json] --> Boot
Settings[(settings)] --> Runtime[manager / scheduler / interceptor]
Profiles[(LLM profiles)] --> Provider[provider chain]
Agent[agent + task overrides] --> Provider
Runtime --> Rebuild{apply 경계}
Rebuild -->|즉시/다음 tick| Live[현재 process]
Rebuild -->|agent 재조립| Sessions[이후 session/run]
시작 flag
시작 flag · 관계
이 대상을 사용하는 기능·모듈·계약 · 1개
- 의존 / 설정 · 설정 계약과 우선순위 · startup flags · catalog-edge-1
실행 파일이 직접 등록하는 애플리케이션 flag는 3개다. Go flag가 제공하는 -h/-help는 도움말을 출력하고 성공 종료한다. main
| flag | 타입·기본값 | 소비 시점 | 효과 |
|---|---|---|---|
-addr |
string, :8787 |
HTTP server 시작 | API와 embedded UI listen address |
-data |
path string, <BaseDir>/data |
manager/store 생성 | traffic SQLite·body/blob·evidence·transcript·task workspace root |
-proxy |
address string, 127.0.0.1:8788 |
manager 생성 | recording proxy listen address; 빈 문자열이면 proxy를 만들지 않음 |
start.sh와 start.bat는 인자를 그대로 binary에 전달한다. go run의 임시 executable은 BaseDir()가 감지해 CWD를 기준으로 되돌린다. supervisor의 종료 코드 계약은 시작 wrapper에 있다. start wrapper
부팅 설정 우선순위
부팅 설정 우선순위 · 관계
이 대상을 사용하는 기능·모듈·계약 · 1개
- 의존 / 설정 · 설정 계약과 우선순위 · file and environment precedence · catalog-edge-2
| 목적 | 높은 순서 | 기본·실패 |
|---|---|---|
| config path | ARTEX_CONFIG → CWD config.json → executable 옆 config.json |
파일이 없으면 CWD 후보를 진단 path로 반환 |
| PostgreSQL DSN | ARTEX_PG_DSN → database.dsn → database.* 조립 |
유효한 입력이 없으면 startup 실패 |
| skill root | ARTEX_SKILL_DIR → skill_dir → <BaseDir>/skills |
directory 생성을 시도하며 생성 오류는 이 helper가 반환하지 않음 |
| 기본 LLM fallback | DB profile/agent/task binding 경로 → LLM 환경변수 | provider와 key를 해석하지 못하면 fallback provider 없음 |
config.json 읽기 또는 JSON decode 실패는 오류를 반환하지 않고 zero config가 된다. 알 수 없는 JSON field도 무시된다. 따라서 “파일이 있다”는 사실은 DSN이 유효하다는 뜻이 아니다. config.example.json의 port 5433은 예시 값이고 field 조립의 코드 기본은 5432다. config example
런타임 설정 분모
런타임 설정 분모 · 관계
이 대상을 사용하는 기능·모듈·계약 · 1개
- 의존 / 설정 · 설정 계약과 우선순위 · runtime settings · catalog-edge-3
현재 source에서 운영자가 조절하는 설정 계약은 다음처럼 따로 센다. 내부 seed/migration marker는 입력 분모에 섞지 않는다.
| 계열 | 수 | 전수표 |
|---|---|---|
| binary application flag | 3 | CLI |
| Go application runtime env | 13 | process 환경변수 |
| dependency-owned explicit runtime env | 6 | Norma provider/tool 입력 |
config.json field |
8 | 파일 schema |
operator-managed settings key |
31 | DB 런타임 키 |
| internal seed/migration marker | 24 | 내부 marker |
별도 분모인 frontend/build/Compose 환경변수와 script option은 빌드 입력과 정상 운영 명령에 있다. settings의 31개는 일반 설정 API의 21개 field뿐 아니라 intercept 1개, judge 7개, global retry 1개, 관리자 password hash 1개를 포함한다. manager settings
Profile·agent·task override
Profile·agent·task override · 관계
이 대상을 사용하는 기능·모듈·계약 · 1개
- 의존 / 설정 · 설정 계약과 우선순위 · task and agent overrides · catalog-edge-4
Process LLM 환경변수는 fallback 하나를 만든다. DB profile이 있으면 active/default profile, agent profile binding, task의 ordered profile chain, pool/fallback 설정이 provider 선택에 참여한다. llm_retry_policy의 connect/empty/stream 값 위에는 profile별 field override가 올라가고, breaker/intent는 global 값만 쓴다. 이 계층은 config.json field가 아니다. provider routing
Tool·MCP·Skill 노출도 agent visibility와 tools.agents, enabled, deferred 상태가 합성한다. 이름과 역할별 기본 집합은 도구 전수표에 있다.
저장과 적용 경계
저장과 적용 경계 · 관계
이 대상을 사용하는 기능·모듈·계약 · 1개
- 의존 / 설정 · 설정 계약과 우선순위 · configuration apply boundary · catalog-edge-5
| 적용 경계 | 해당 값 | 의미 |
|---|---|---|
| process 재시작 | CLI, config.json, Go runtime env, Norma env gate |
부팅 때 다시 읽음 |
| agent/provider 재조립 | traffic, global proxy, web search, LLM pool, retry의 provider 계층 | settings handler가 applyLLM/profile invalidation을 수행; 이미 진행 중인 turn의 원자적 교체를 뜻하지 않음 |
| 다음 run/task | workers, noa_compaction |
새 engine run이 다시 읽음 |
| 즉시 또는 다음 scheduler tick | task concurrency, llm_record, constraint injection, notify |
in-memory 값 갱신, 매 호출/매 round/매 tick 재조회 |
| 다음 intercept 판정 | enabled tool set, judge config | cache invalidation 또는 판정 시 fresh read |
global_proxy는 egress route이고 scope authorization은 아니다. llm_record는 request/response와 tool schema를 저장할 수 있으며 기본값은 false다. secret 값은 환경변수, settings, LLM profile에 흩어질 수 있으므로 문서나 운영 dump에 실제 값을 복사하지 않는다.
설정 계약과 우선순위 · 관계
이 대상이 사용하는 구현·계약·의존 · 6개
- 계약 사용 · 런타임 설정 전수표 · summary precedence delegates exhaustive names/types/defaults/consumers/effects · config · manager · runtime-settings-server
- 의존 / 설정 · 시작 flag · startup flags · catalog-edge-1
- 의존 / 설정 · 부팅 설정 우선순위 · file and environment precedence · catalog-edge-2
- 의존 / 설정 · 런타임 설정 분모 · runtime settings · catalog-edge-3
- 의존 / 설정 · Profile·agent·task override · task and agent overrides · catalog-edge-4
- 의존 / 설정 · 저장과 적용 경계 · configuration apply boundary · catalog-edge-5
이 대상을 사용하는 기능·모듈·계약 · 1개
- 계약 사용 · 설치·실행·업데이트·복구 · runtime startup가 configuration contract를 소비 · core-edge-16