chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가
This commit is contained in:
DongHyeonka
+27
-124
@@ -1,155 +1,58 @@
|
||||
# Provider integration
|
||||
|
||||
## 공통 계약
|
||||
|
||||
모든 provider는 다음 인터페이스를 구현한다.
|
||||
|
||||
```python
|
||||
Provider.generate(ProviderRequest) -> ProviderResponse
|
||||
Provider.check() -> dict
|
||||
```
|
||||
|
||||
`ProviderRequest`는 `stage`, `prompt`, `workdir`, `metadata`를 가진다. `ProviderResponse`는 모델의 텍스트, provider/model 이름, 실제 command 또는 실행 메타데이터를 반환한다.
|
||||
|
||||
Provider는 초안의 의미를 해석하지 않는다. 호출·timeout·출력 수집만 담당하며 JSON/Markdown 계약 검증은 pipeline에서 수행한다.
|
||||
# Provider integrations
|
||||
|
||||
## Codex
|
||||
|
||||
기본 command 개념:
|
||||
기본 command:
|
||||
|
||||
```text
|
||||
codex exec
|
||||
--sandbox read-only
|
||||
--skip-git-repo-check
|
||||
[--model MODEL]
|
||||
--output-last-message TEMP_FILE
|
||||
-
|
||||
codex exec --sandbox read-only --output-last-message <file> -
|
||||
```
|
||||
|
||||
프롬프트는 stdin으로 전달한다. `-`는 비대화형 입력을 의미하고, 마지막 메시지는 임시 파일에서 읽는다. 문서 생성은 로컬 파일 변경이 필요 없으므로 기본 sandbox를 read-only로 둔다.
|
||||
Prompt는 stdin으로 전달한다. planner, logic reviewer, decision reviewer에 사용한다. `skip_git_repo_check`와 `extra_args`는 provider option으로 설정할 수 있다.
|
||||
|
||||
설정 예:
|
||||
## Claude
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "codex",
|
||||
"model": "",
|
||||
"timeout_seconds": 300,
|
||||
"options": {
|
||||
"binary": "codex",
|
||||
"sandbox": "read-only",
|
||||
"skip_git_repo_check": true,
|
||||
"extra_args": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
환경 변수 `CLARIDOC_CODEX_BIN`으로 실행 파일을 지정할 수도 있다.
|
||||
|
||||
조직 래퍼:
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "codex",
|
||||
"options": {
|
||||
"command": ["/trusted/path/company-codex-wrapper", "--batch"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
custom command는 stdout을 최종 응답으로 사용한다.
|
||||
|
||||
## Claude Code
|
||||
|
||||
기본 command 개념:
|
||||
기본 command:
|
||||
|
||||
```text
|
||||
claude -p --output-format text [--model MODEL] "Read the piped task..."
|
||||
claude -p --output-format text
|
||||
```
|
||||
|
||||
긴 프롬프트는 운영체제 argument 길이 제한을 피하기 위해 stdin으로 전달한다. 마지막 고정 query는 piped task의 출력 계약만 수행하도록 지시한다.
|
||||
|
||||
설정 예:
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "claude",
|
||||
"model": "",
|
||||
"timeout_seconds": 600,
|
||||
"options": {
|
||||
"binary": "claude",
|
||||
"extra_args": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
환경 변수 `CLARIDOC_CLAUDE_BIN` 또는 신뢰된 `options.command`를 사용할 수 있다.
|
||||
Prompt는 stdin으로 전달한다. primary writer, reader reviewer, editor reviewer, reviser에 사용한다.
|
||||
|
||||
## Google Antigravity
|
||||
|
||||
Antigravity는 Python SDK를 사용한다.
|
||||
Python SDK 표면:
|
||||
|
||||
```python
|
||||
from google.antigravity import Agent, LocalAgentConfig
|
||||
|
||||
config = LocalAgentConfig(**options["config"])
|
||||
async with Agent(config) as agent:
|
||||
response = await agent.chat(prompt)
|
||||
text = await response.text()
|
||||
```
|
||||
|
||||
설치:
|
||||
`LocalAgentConfig`로 model과 config를 전달하고 async `chat` 결과의 text를 읽는다. evidence와 operations reviewer에 사용한다.
|
||||
|
||||
## Model IDs
|
||||
|
||||
예제 config는 model ID를 비워 provider 계정의 기본 선택을 사용한다. 조직에서 허용된 model ID가 있다면 각 provider object의 `model`에 지정한다. 모델 이름과 availability는 계정·시점마다 달라질 수 있으므로 `doctor`와 live smoke test로 확인한다.
|
||||
|
||||
## Doctor
|
||||
|
||||
```bash
|
||||
python -m pip install -e '.[antigravity]'
|
||||
claridoc doctor --config config/pipeline.multi-agent.example.json
|
||||
```
|
||||
|
||||
설정 예:
|
||||
`doctor`가 확인하는 것:
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "antigravity",
|
||||
"model": "",
|
||||
"timeout_seconds": 300,
|
||||
"options": {
|
||||
"config": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
- CLI executable 또는 SDK import 가능 여부
|
||||
- 설정된 integration surface
|
||||
|
||||
`model`이 지정되고 `options.config`에 model이 없으면 하네스가 config 인수로 전달한다. SDK 버전에 따라 지원 인수가 다를 수 있으므로 잘못된 config는 명시적 오류로 종료한다.
|
||||
확인하지 않는 것:
|
||||
|
||||
SDK가 로컬 환경을 기준으로 동작하므로 provider는 실행 중 임시로 run directory를 current working directory로 사용한다. 프로세스 전체 cwd가 공유 상태이므로 lock으로 직렬화한다.
|
||||
- 로그인 유효성
|
||||
- project/repository 접근 권한
|
||||
- quota와 rate limit
|
||||
- model ID availability
|
||||
- 실제 response schema 안정성
|
||||
|
||||
## Mock
|
||||
|
||||
Mock은 외부 모델이 아니다. 다음을 위한 결정적 fixture다.
|
||||
|
||||
- planner JSON 계약 검증
|
||||
- writer Markdown 배선 검증
|
||||
- review JSON 파싱 검증
|
||||
- revision loop 및 산출물 테스트
|
||||
- CI에서 네트워크·인증 없이 회귀 테스트
|
||||
|
||||
Mock 점수는 실제 품질 판단으로 사용하면 안 된다.
|
||||
|
||||
## `doctor`
|
||||
|
||||
```bash
|
||||
claridoc doctor --config config/pipeline.multi-agent.example.json --json
|
||||
```
|
||||
|
||||
- Codex/Claude: 실행 파일 경로 존재 확인
|
||||
- Antigravity: Python module import 가능 여부 확인
|
||||
- Mock: 항상 available
|
||||
|
||||
`doctor`는 로그인·권한·quota·실제 모델 응답까지 확인하지 않는다. 그것은 live invocation에서만 확인된다.
|
||||
|
||||
## Provider 추가
|
||||
|
||||
1. `src/claridoc/providers/`에 `Provider` 구현을 추가한다.
|
||||
2. stdout/SDK 응답을 문자열로 반환하고 timeout과 오류를 `ProviderError` 계열로 변환한다.
|
||||
3. `registry.py`에 이름을 등록한다.
|
||||
4. command/SDK를 가짜 구현으로 대체한 단위 테스트를 작성한다.
|
||||
5. 인증 비밀은 config나 event log에 넣지 않는다.
|
||||
6. 모델 출력 계약은 provider가 아니라 `prompts.py`와 pipeline parser에서 유지한다.
|
||||
Mock provider는 deterministic fixture다. source excerpt를 최종 글에 복사하지 않으며, 외부 model을 호출하지 않는다. Mock reviewer score는 합성값이다.
|
||||
|
||||
Reference in New Issue
Block a user