toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-task/01_internal_target_naming/plan_cloud_G09_0.log
toki d764adb390 chore: agent-task 변경 사항 반영 
- edge node store 및 console 업데이트
- node adapters(cli, ollama, vllm, mock) 리팩토링
- node router, run_manager, store 개선
- proto 파일(control.proto, runtime.proto) 및 생성 코드 업데이트
- config 업데이트
2026-05-10 20:41:33 +09:00

258 lines
12 KiB
Text
Raw Blame History

<!-- task=01_internal_target_naming plan=0 tag=REFACTOR -->
# Internal Target Naming Refactor
## 이 파일을 읽는 구현 에이전트에게
**구현 완료 후 `CODE_REVIEW-cloud-G09.md`의 모든 섹션을 채우는 것이 필수 마지막 단계입니다.** 체크리스트 완료 여부, 중간/최종 검증 결과, 계획 대비 변경 사항, 주요 설계 결정을 실제 내용으로 채우세요. `CODE_REVIEW-cloud-G09.md`의 `이 파일을 읽는 리뷰 에이전트에게` 섹션에 있는 아카이브 지시는 리뷰 스킬 전용이며 구현 에이전트가 실행하지 않습니다.
## 배경
현재 내부 proto, runtime, router, store, console 경로에서 `model`이 실행 대상 전체를 의미한다. IOP는 모델 서빙뿐 아니라 CLI agent/profile 실행도 같은 adapter execution pipeline에서 처리한다. 외부 OpenAI-compatible API의 `model`은 유지할 수 있지만, 내부 실행 계층은 `adapter + target`으로 읽혀야 한다.
## 분석 결과
### 읽은 파일
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/node/rules.md`
- `agent-ops/rules/project/domain/edge/rules.md`
- `agent-ops/rules/project/domain/platform-common/rules.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `proto/iop/runtime.proto`
- `proto/iop/control.proto`
- `proto/iop/job.proto`
- `packages/config/config.go`
- `packages/jobs/jobs.go`
- `packages/policy/engine.go`
- `configs/edge.yaml`
- `configs/node.yaml`
- `apps/node/internal/runtime/types.go`
- `apps/node/internal/router/router.go`
- `apps/node/internal/node/node.go`
- `apps/node/internal/node/run_manager.go`
- `apps/node/internal/store/store.go`
- `apps/node/internal/adapters/cli/cli.go`
- `apps/node/internal/adapters/cli/codex_exec.go`
- `apps/node/internal/adapters/mock/mock.go`
- `apps/node/internal/adapters/ollama/ollama.go`
- `apps/node/internal/adapters/vllm/vllm.go`
- `apps/edge/cmd/edge/console.go`
- `apps/edge/internal/node/store.go`
- `apps/edge/internal/node/registry.go`
- `apps/edge/internal/node/mapper.go`
- `apps/edge/internal/transport/server.go`
- `apps/node/internal/router/router_test.go`
- `apps/node/internal/node/node_test.go`
- `apps/node/internal/store/store_test.go`
- `apps/node/internal/transport/parser_test.go`
- `apps/edge/cmd/edge/console_test.go`
- `apps/edge/internal/transport/server_test.go`
- `packages/config/config_test.go`
### 테스트 커버리지 공백
- Proto field rename: parser tests cover protobuf round-trip shape, but generated code rename needs broad compile/test verification.
- Runtime `Model -> Target`: router/node/store/CLI tests cover many call sites, but rename is broad enough that compile failures are the main detector.
- Store column rename: `store_test.go` covers old schema migration for `session_id/background`, but not `model -> target` migration. Add/update migration coverage if DB column changes.
- Console compatibility: `console_test.go` covers wire request construction, status, terminate session, and node selection; update it for target naming and legacy alias behavior.
### 심볼 참조
- `RunRequest.model`: `proto/iop/runtime.proto:25`, generated getters, node transport/parser tests, edge console request construction.
- `CancelRequest.model`: `proto/iop/runtime.proto:65`, node cancel flow, console terminate session.
- `NodeCommandRequest.model` / `NodeCommandResponse.model`: `proto/iop/runtime.proto:79`, `proto/iop/runtime.proto:89`, node command mapper, CLI command handler, console status command.
- `ScheduleRequest.model`: `proto/iop/control.proto:17`; control-plane is placeholder, so keep change minimal.
- `runtime.ExecutionSpec.Model`: `apps/node/internal/runtime/types.go:36`; used by router, node store insert, CLI, Ollama, vLLM, tests.
- `runtime.RunRequest.Model`: `apps/node/internal/runtime/types.go:87`; used by router and node request mapping.
- `runtime.Capabilities.Models`: `apps/node/internal/runtime/types.go:79`; CLI currently returns profile names through `Models`.
- `store.RunRecord.Model` and `runs.model`: `apps/node/internal/store/store.go:18`, `apps/node/internal/store/store.go:32`, `apps/node/internal/store/store.go:124`, `apps/node/internal/store/store.go:142`.
- `EdgeConsoleConf.Model`: `packages/config/config.go:43`; legacy fallback is in `packages/config/config.go:155`.
### 범위 결정 근거
- README/docs are excluded because this task is code/config contract cleanup, not roadmap writing.
- `apps/control-plane/**` and `apps/worker/**` remain placeholders; do not implement scheduling or worker semantics.
- `proto/iop/job.proto`, `packages/jobs/jobs.go`, and `packages/policy/engine.go` may contain `model`, but central Job/Policy design is not finalized. Only update them if compile or direct contract consistency requires it.
- External OpenAI-compatible `model` fields, external CLI flags such as `opencode --model`, and adapter-specific model API comments may remain.
### 빌드 등급
build=`cloud-G09`, review=`cloud-G09`. Proto/schema/runtime naming touches cross-domain contracts, generated code, store migration, and many tests.
## 의존 관계 및 구현 순서
1. `[REFACTOR-1]` Proto request/command fields.
2. `[REFACTOR-2]` Runtime/domain structs and call sites.
3. `[REFACTOR-3]` Store/config/console compatibility.
4. `[REFACTOR-4]` Tests and generated code.
### [REFACTOR-1] Proto execution target fields
#### 문제
`proto/iop/runtime.proto:21-25` describes and stores the common execution target as `model`. `CancelRequest` and node command messages repeat that naming at `proto/iop/runtime.proto:65`, `proto/iop/runtime.proto:79`, and `proto/iop/runtime.proto:89`. `proto/iop/control.proto:17` does the same for placeholder scheduling.
#### 해결 방법
Use `target` for internal execution target fields while keeping existing field numbers. Do not implement OpenAI compatibility or control-plane behavior.
```proto
// before: proto/iop/runtime.proto:21-25
// RunRequest initiates a model execution.
message RunRequest {
string run_id = 1;
string adapter = 2;
string model = 3;
}
```
```proto
// after
// RunRequest initiates an adapter execution.
message RunRequest {
string run_id = 1;
string adapter = 2;
string target = 3;
}
```
#### 수정 파일 및 체크리스트
- [ ] `proto/iop/runtime.proto`의 `RunRequest`, `CancelRequest`, `NodeCommandRequest`, `NodeCommandResponse` 필드를 `target`으로 바꾼다.
- [ ] `proto/iop/control.proto`의 `ScheduleRequest.model`을 `target` 또는 최소한의 required target 개념으로 바꾼다.
- [ ] field number는 유지한다.
- [ ] `make proto`로 `proto/gen/iop/*.pb.go`를 갱신한다.
#### 테스트 작성
별도 proto-only 테스트는 추가하지 않는다. parser/console/node tests와 compile로 검증한다.
#### 중간 검증
```bash
make proto
go test ./proto/gen/...
```
예상 결과: generated code가 갱신되고 proto package가 빌드된다.
### [REFACTOR-2] Runtime/domain target naming
#### 문제
`apps/node/internal/runtime/types.go:36`, `apps/node/internal/runtime/types.go:87`, `apps/node/internal/runtime/types.go:123`, and `apps/node/internal/runtime/types.go:133` use `Model` for common execution target. `apps/node/internal/router/router.go:39` maps request model into execution spec model and logs it at `apps/node/internal/router/router.go:53`.
#### 해결 방법
Rename internal runtime fields to `Target`, and update router/node/adapters/tests by compiler feedback. Keep adapter names unchanged.
#### 수정 파일 및 체크리스트
- [ ] `runtime.ExecutionSpec.Model` -> `Target`.
- [ ] `runtime.RunRequest.Model` -> `Target`.
- [ ] `runtime.CommandRequest.Model` / `CommandResponse.Model` -> `Target`.
- [ ] `runtime.Capabilities.Models` -> `Targets` when it lists adapter-selectable execution targets.
- [ ] `runtime.SessionTerminator.TerminateSession(ctx, model, sessionID)` -> `target`.
- [ ] Router logs use `target` key.
- [ ] Node request/domain mapper uses proto `GetTarget()`.
#### 테스트 작성
Existing tests should be updated rather than adding broad new tests. Add focused test only if store migration or legacy config compatibility changes behavior.
#### 중간 검증
```bash
go test ./apps/node/internal/runtime/... ./apps/node/internal/router/... ./apps/node/internal/node/...
```
예상 결과: runtime/router/node packages compile and tests pass.
### [REFACTOR-3] Store, CLI, and console naming boundary
#### 문제
`apps/node/internal/store/store.go:18` persists `runs.model`; CLI profile selection reads `spec.Model` in `apps/node/internal/adapters/cli/cli.go:222-223`; console comments state the wire schema carries selected profile through `model` in `apps/edge/cmd/edge/console.go:164-179`.
#### 해결 방법
Rename internal storage/domain fields to `target` with a small local migration. Console should use target wording while preserving legacy `console.model` fallback from `packages/config/config.go:155-156`.
#### 수정 파일 및 체크리스트
- [ ] Store schema uses `target` for new DBs.
- [ ] Existing local DBs with `model` are migrated without central store design.
- [ ] CLI helper names use target/profile language.
- [ ] Console request builder accepts target/profile and writes proto `Target`.
- [ ] Keep `console.agent` compatibility if needed; keep `console.model` as legacy fallback only.
- [ ] Do not change external CLI command args such as `--model`.
#### 테스트 작성
Update `store_test.go` for migration if column changes. Update console tests for target naming and legacy fallback.
#### 중간 검증
```bash
go test ./apps/node/internal/store/... ./apps/node/internal/adapters/cli/... ./apps/edge/cmd/edge/... ./packages/config/...
```
예상 결과: local store, CLI adapter, console, and config tests pass.
### [REFACTOR-4] Search cleanup and explicit exceptions
#### 문제
Mechanical rename can either miss internal model-as-target uses or incorrectly change legitimate model references.
#### 해결 방법
Search remaining model references and classify each one.
#### 수정 파일 및 체크리스트
- [ ] Run `rg -n "\bmodel\b|\bModel\b" proto/iop apps packages configs --glob '!**/README.md'`.
- [ ] Keep external API boundary, external CLI flags, and model-specific adapter API references if they are truly model-specific.
- [ ] Record any intentional leftovers in `CODE_REVIEW-cloud-G09.md`.
#### 테스트 작성
No extra tests for search classification.
#### 중간 검증
```bash
rg -n "\bmodel\b|\bModel\b" proto/iop apps packages configs --glob '!**/README.md'
```
예상 결과: remaining matches are intentional exceptions or test fixtures.
## 수정 파일 요약
| 파일 | 항목 |
|------|------|
| `proto/iop/runtime.proto` | REFACTOR-1 |
| `proto/iop/control.proto` | REFACTOR-1 |
| `proto/gen/iop/*.pb.go` | REFACTOR-1 |
| `apps/node/internal/runtime/types.go` | REFACTOR-2 |
| `apps/node/internal/router/router.go` | REFACTOR-2 |
| `apps/node/internal/node/node.go` | REFACTOR-2, REFACTOR-3 |
| `apps/node/internal/store/store.go` | REFACTOR-3 |
| `apps/node/internal/adapters/cli/*.go` | REFACTOR-3 |
| `apps/edge/cmd/edge/console.go` | REFACTOR-3 |
| `packages/config/config.go` | REFACTOR-3 |
| related `*_test.go` files | REFACTOR-4 |
## 최종 검증
```bash
make proto
gofmt -w <changed-go-files>
go test ./packages/config ./apps/edge/cmd/edge/... ./apps/node/internal/...
go test ./...
rg -n "\bmodel\b|\bModel\b" proto/iop apps packages configs --glob '!**/README.md'
```
예상 결과: tests pass; remaining `model` matches are explicit exceptions. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 전체 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
Reference in a new issue View git blame Copy permalink