From b88ccc51952567a8aff870b48af885b280d87a80 Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 24 May 2026 06:05:57 +0900 Subject: [PATCH] update README files --- README.md | 35 +++++++++++++++++++++++++++++------ services/core/README.md | 23 +++++++++++++---------- 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 211776f..f2258fb 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,35 @@ NomadCode is a monorepo for AI-assisted development workflows. It brings togethe The repository is currently an early product scaffold. The core service owns task orchestration and persistence, the web and mobile apps provide initial operator surfaces, and `agent-ops/` keeps the rules and roadmap that AI agents need before changing the workspace. +NomadCode is the development-workflow shell that consumes IOP. It structures user and provider requests into development tasks, tracks project/session/workspace state, and shows execution results to users. It does not own the model runtime, model routing, RAG, MCP policy, or output-validation engine; those responsibilities belong to IOP. + ## Current Status -- `services/core` has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, model/A2A client paths, and Plane/Mattermost adapter stubs. -- `apps/web` is a React/Vite scaffold for Agent, Projects, and Settings views. Some state and integration status areas are still mocked or stubbed. -- `apps/mobile` is a Flutter app scaffold with Firebase Messaging, local notifications, and HTTP client dependencies. +- `services/core` has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, an IOP OpenAI-compatible Responses client path, future A2A agent-delegation scaffolding, and Plane/Mattermost adapter stubs. +- `apps/web` is a React/Vite scaffold for Agent, Projects, Settings, and browser-based project workspace views. Some state and integration status areas are still mocked or stubbed. +- `apps/mobile` is a Flutter app scaffold for mobile and desktop client surfaces, Firebase Messaging, local notifications, and HTTP client dependencies. - `packages/contracts` is a placeholder for future shared OpenAPI, protobuf, generated client, fixture, and compatibility assets. - Active planning lives under `agent-ops/roadmap/`; this README links to that context instead of duplicating milestone state. +## Product Boundary + +NomadCode owns the product and workflow layer: + +- agent chat, project workspace management, task queue state, and execution status. +- Plane/Jira-style work item intake, provider projection, comments, and status updates. +- user-facing file change, diff, branch, commit, and PR flows. +- desktop and mobile project management surfaces, including project-level desktop windows and mobile top-tab workflows. +- task metadata prepared for IOP calls. + +IOP owns the execution and optimization layer: + +- OpenAI-compatible model calls, with Responses API support as the current NomadCode integration target. +- local/cloud model routing, model profiles, runtime selection, usage logs, and quality signals. +- CLI agent/runtime adapters such as OpenCode, Aider, Claude Code, Gemini CLI, and Codex CLI. +- RAG, context compression, MCP/tool policy, output validation, retry/fallback, and token/speed/quality optimization. + +NomadCode should call IOP through its supported external surfaces. The current NomadCode path is IOP's OpenAI-compatible Responses API. A2A is reserved for later external agent delegation work, and IOP native protocol is not a NomadCode default external call path. + ## Quick Start Install only the runtimes needed for the part of the workspace you are using. @@ -73,7 +94,7 @@ flutter run |------|------| | `services/core/` | Go backend for orchestration, persistence, scheduling, HTTP APIs, and external service adapters. | | `apps/web/` | React/Vite operator console and browser-based agent/project workspace UI. | -| `apps/mobile/` | Flutter mobile/desktop client and notification integration surface. | +| `apps/mobile/` | Flutter mobile/desktop client, project management surface, and notification integration surface. | | `packages/contracts/` | Future shared API/schema contracts and generated client boundary. | | `docs/` | Architecture and operations notes. | | `bin/` | Root test, lint, build, and dev helper commands. | @@ -95,6 +116,8 @@ For workspace-level files such as this README, also check: Keep detailed roadmap state in `agent-ops/roadmap/` and detailed domain rules in `agent-ops/rules/project/domain/`. Do not read `agent-task/archive/**` unless the user explicitly asks for it. +IOP boundary work should be checked against the sibling IOP repository when it is available in the same workspace. NomadCode roadmap documents should remain the source of truth for NomadCode product/workflow scope; IOP roadmap documents should remain the source of truth for execution/runtime scope. + ## Development Flow - Prefer the root `bin/test`, `bin/lint`, `bin/build`, and `bin/dev` entrypoints for whole-workspace work. @@ -109,8 +132,8 @@ Keep detailed roadmap state in `agent-ops/roadmap/` and detailed domain rules in | Core | `DATABASE_URL` | No, with scripts | Core scripts provide local defaults; set it when running the binary directly or using a different PostgreSQL database. | | Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | No, with scripts | Core scripts provide local defaults for worker/queue state; set them when running outside those scripts. | | Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | No | `AUTH_PASSWORD` enables HTTP Basic Auth for `/readyz` and `/api/*`. | -| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | No | Configure the OpenAI-compatible model endpoint used by worker execution. | -| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | No | Configure the A2A-compatible agent call path. | +| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | No | Configure the IOP Edge OpenAI-compatible Responses endpoint used by worker execution. Legacy direct model endpoint compatibility may exist in local scripts, but the target runtime path is IOP. | +| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | No | Configure the future A2A-compatible agent delegation path. This is not the current default execution path. | | Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | No | Reserved for Mattermost adapter integration. | | Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | No | Configure Plane work item lookup, comment, and state update integration. | | Web | `VITE_NOMADCODE_API_BASE_URL` | No | The web client falls back to `http://localhost:8080`; `apps/web/.env.example` documents the same local value. | diff --git a/services/core/README.md b/services/core/README.md index 057e07a..a7ed0ff 100644 --- a/services/core/README.md +++ b/services/core/README.md @@ -2,7 +2,7 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 저장하며, 비동기 Agent 작업 흐름을 관리하기 위한 서버입니다. -초기 목표는 작업 생성과 조회, PostgreSQL 기반 작업 상태 저장, River 기반 비동기 작업 실행, Plane/Mattermost Adapter stub 구성, 이후 IOP / Agent Integrator와 연결 가능한 구조 확보입니다. +초기 목표는 작업 생성과 조회, PostgreSQL 기반 작업 상태 저장, River 기반 비동기 작업 실행, Plane/Mattermost Adapter stub 구성, IOP OpenAI-compatible Responses 호출 경로 확보입니다. NomadCode Core는 직접 모델 런타임, 모델 라우팅, RAG, MCP, output validation, fallback 정책을 소유하지 않고 IOP를 실행/최적화 계층으로 사용합니다. ## 현재 구현 범위 @@ -13,8 +13,8 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 - goose migration - sqlc 기반 DB query 생성 구조 - River task job -- IOP Edge/OpenAI-compatible 모델 호출 경로(Ollama direct fallback 가능) -- IOP Edge/A2A-compatible agent 호출 인터페이스 +- IOP Edge/OpenAI-compatible Responses 모델 호출 경로 +- 향후 A2A-compatible agent delegation을 위한 client 경로 - Plane work item lookup, comment, and state update adapter - Mattermost Adapter stub - 선택적 Docker Compose 실행 환경(PostgreSQL, Redis) @@ -23,7 +23,7 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 - 실제 Mattermost 메시지 발송 - IOP native protocol 연동 -- Agent Integrator 연동 +- Agent Integrator 연동 또는 대체 여부 확정 - Outline / Forgejo / Nextcloud 연동 - MCP 서버 - Web Agent UI @@ -33,7 +33,9 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 ## 실행 방법 -로컬 실행은 현재 개발 호스트의 Go와 `code-server` compose에 붙은 PostgreSQL/Redis가 있다는 전제로 진행합니다. local 기본 `DATABASE_URL`은 `postgres://nomadcode:nomadcode@code-server-postgres:5432/nomadcode-core-local?sslmode=disable` 이고, local 기본 `REDIS_URL`은 `redis://code-server-redis:6379/3`, `REDIS_KEY_PREFIX`는 `nomadcode-core:local` 입니다. dev 배포는 Docker Compose로 실행하며, 같은 `code-server-postgres` Postgres와 `code-server-redis` Redis를 사용합니다. dev DB명은 `nomad-core-dev` 이고, dev 기본 `REDIS_URL`은 `redis://code-server-redis:6379/4`, `REDIS_KEY_PREFIX`는 `nomadcode-core:dev` 입니다. `AUTH_PASSWORD`를 설정하면 `/readyz`와 `/api/*`에 HTTP Basic Auth가 적용됩니다. 모델 호출의 장기 대상은 IOP Edge의 OpenAI-compatible input surface이며, 현재 core model client는 Responses API 형식을 사용합니다. fallback 기본값은 direct Ollama `MODEL_BASE_URL=http://192.168.0.91:11434`, `MODEL_NAME=qwen3.6:35b-a3b-bf16`, `MODEL_CONTEXT_SIZE=262144`, `MODEL_TIMEOUT_SEC=300` 입니다. A2A agent 호출 endpoint는 `A2A_EDGE_URL`로 설정하고, 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. bearer token은 `A2A_TOKEN`, timeout은 `A2A_TIMEOUT_SEC`로 설정합니다. Plane 연동은 `PLANE_BASE_URL`, `PLANE_TOKEN`으로 설정하며, toki-labs dev Plane 기본 URL은 `https://plane.toki-labs.com` 입니다. +로컬 실행은 현재 개발 호스트의 Go와 `code-server` compose에 붙은 PostgreSQL/Redis가 있다는 전제로 진행합니다. local 기본 `DATABASE_URL`은 `postgres://nomadcode:nomadcode@code-server-postgres:5432/nomadcode-core-local?sslmode=disable` 이고, local 기본 `REDIS_URL`은 `redis://code-server-redis:6379/3`, `REDIS_KEY_PREFIX`는 `nomadcode-core:local` 입니다. dev 배포는 Docker Compose로 실행하며, 같은 `code-server-postgres` Postgres와 `code-server-redis` Redis를 사용합니다. dev DB명은 `nomad-core-dev` 이고, dev 기본 `REDIS_URL`은 `redis://code-server-redis:6379/4`, `REDIS_KEY_PREFIX`는 `nomadcode-core:dev` 입니다. `AUTH_PASSWORD`를 설정하면 `/readyz`와 `/api/*`에 HTTP Basic Auth가 적용됩니다. + +모델 호출의 기본 방향은 IOP Edge의 OpenAI-compatible Responses input surface입니다. `MODEL_BASE_URL`은 IOP Edge listener를 가리키고, 해당 listener는 non-streaming `POST /v1/responses`를 제공해야 합니다. 현재 코드와 local script에는 개발 호환용 direct model endpoint/Ollama 기본값이 남아 있을 수 있지만, 로드맵과 운영 기준의 기본 실행 경로는 IOP 경유 호출입니다. A2A agent 호출 endpoint는 `A2A_EDGE_URL`로 설정하고, 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. bearer token은 `A2A_TOKEN`, timeout은 `A2A_TIMEOUT_SEC`로 설정합니다. A2A는 향후 외부 agent delegation 표면이며 현재 기본 실행 경로는 아닙니다. Plane 연동은 `PLANE_BASE_URL`, `PLANE_TOKEN`으로 설정하며, toki-labs dev Plane 기본 URL은 `https://plane.toki-labs.com` 입니다. `code-server` PostgreSQL 컨테이너에 DB를 생성하는 예시: @@ -68,19 +70,20 @@ DATABASE_URL="postgres://user:password@localhost:5432/dbname?sslmode=disable" ./ DATABASE_URL="postgres://user:password@localhost:5432/dbname?sslmode=disable" ./bin/run ``` -다른 모델 endpoint를 사용할 경우: +IOP Edge OpenAI-compatible endpoint를 사용할 경우: ```bash -MODEL_BASE_URL="http://localhost:11434" \ -MODEL_NAME="qwen3.6:35b-a3b-bf16" \ +MODEL_BASE_URL="http://" \ +MODEL_API_KEY="" \ +MODEL_NAME="" \ MODEL_CONTEXT_SIZE="262144" \ MODEL_TIMEOUT_SEC="300" \ ./bin/run ``` -모델 호출은 OpenAI-compatible Responses API의 non-streaming `POST /v1/responses` 형식을 사용합니다. IOP Edge OpenAI-compatible listener를 `MODEL_BASE_URL`로 쓰려면 해당 listener가 `/v1/responses`를 제공해야 합니다. direct Ollama fallback에서는 `MODEL_CONTEXT_SIZE`를 Ollama 전용 option인 `options.num_ctx`로 전달합니다. +모델 호출은 OpenAI-compatible Responses API의 non-streaming `POST /v1/responses` 형식을 사용합니다. IOP Edge OpenAI-compatible listener를 `MODEL_BASE_URL`로 쓰려면 해당 listener가 `/v1/responses`를 제공해야 합니다. direct Ollama 호환 경로에서는 `MODEL_CONTEXT_SIZE`를 Ollama 전용 option인 `options.num_ctx`로 전달하지만, 이 경로는 IOP Responses listener가 준비되기 전의 local development compatibility로만 취급합니다. -A2A agent 호출 인터페이스는 JSON-RPC 2.0 `message/send`, `tasks/get`, `tasks/cancel`을 우선 지원합니다. `A2A_EDGE_URL`을 설정하면 worker는 A2A `message/send`를 blocking 호출하고, 완료된 task/message 응답만 local task completion으로 반영합니다. 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. 설정하지 않으면 기존 OpenAI-compatible 모델 호출 경로를 사용합니다. +A2A agent 호출 인터페이스는 JSON-RPC 2.0 `message/send`, `tasks/get`, `tasks/cancel`을 우선 지원합니다. `A2A_EDGE_URL`을 설정하면 worker는 A2A `message/send`를 blocking 호출하고, 완료된 task/message 응답만 local task completion으로 반영합니다. 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. 현재 NomadCode의 기본 실행 경로는 OpenAI-compatible Responses 호출이며, A2A는 후속 agent delegation 작업에서 기본화 여부를 다시 결정합니다. Plane 연동은 Plane API key를 `PLANE_TOKEN`으로 받고 `X-Api-Key` header로 호출합니다. 현재 toki-labs dev Plane은 `https://plane.toki-labs.com`에 있고, 예시 workspace/project 값은 `workspace_slug=general`, `project_id=a6beb42f-7a8a-410c-b50f-ea3ca94828f3` 입니다.