zhaoxi
4aa1dab283
- control_node 标注 DEPRECATED：保留目录壳子供未来远程探针节点复用，删除调用路径与相关测试
- 新增 task 表：极简元数据持久化 regulatory_node 完成的短任务（出报告/写文件/查询整理）
- regulatory_node 自标注：MessageResponse 扩展 task_action/title/summary，_run 末尾非阻塞落库
- query_task_list 改查 task 表，符合用户对"任务列表"的直觉，与 workflow 体系解耦
- 新增 /api/v1/task/list|/{id} 只读 API（task 由 regulatory 内部触发，不开放对外创建）
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
KiloStar is a distributed multi-agent system. Python/FastAPI backend with Ray actor orchestration, React 19 frontend, PostgreSQL storage. Supports two deployment modes: standalone (pure asyncio) and distributed (full Ray cluster).
|
|
|
|
## Commands
|
|
|
|
### Backend
|
|
```bash
|
|
uv sync # Install Python deps
|
|
uv run python main.py # Start distributed mode
|
|
KILOSTAR_MODE=standalone uv run python main.py # Start standalone mode
|
|
```
|
|
|
|
### Frontend (this directory)
|
|
```bash
|
|
npm install # Install deps
|
|
npm run dev # Dev server (Vite)
|
|
npm run build # Production build
|
|
npm run lint # ESLint
|
|
npx tsc --noEmit # Type-check without emitting
|
|
```
|
|
|
|
### Database Migrations (from project root)
|
|
```bash
|
|
make db-revision m="description" # Generate migration
|
|
make db-upgrade # Apply to HEAD
|
|
make db-downgrade # Rollback one
|
|
```
|
|
|
|
### Testing (from project root)
|
|
```bash
|
|
uv run pytest tests -q # Full suite
|
|
uv run pytest tests/unit -q # Unit only
|
|
uv run pytest tests/integration -q # Integration (needs DB)
|
|
```
|
|
|
|
### Docker
|
|
```bash
|
|
docker-compose up -d # Full stack (frontend build + backend)
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Dual-Mode Actor System
|
|
|
|
All core components are Ray actors in distributed mode, plain Python instances in standalone mode. Code uses a unified call pattern:
|
|
|
|
```python
|
|
from kilostar.utils.ray_hook import ray_actor_hook
|
|
|
|
# Returns a namespace object with actor handles
|
|
actors = ray_actor_hook("postgres_database")
|
|
await actors.postgres_database.some_method.remote(arg)
|
|
```
|
|
|
|
`StandaloneProxy` (in `kilostar/utils/standalone_proxy.py`) wraps instances to expose the same `.method.remote()` interface via asyncio. The `@actor_class` decorator marks classes that can be Ray actors or standalone instances depending on mode.
|
|
|
|
Mode is set via `KILOSTAR_MODE` env var. Entry point `main.py` branches into `start_standalone()` or `start_distributed()`.
|
|
|
|
### Backend Layout (`kilostar/`)
|
|
|
|
- `api/` — FastAPI routers (auth, chat, agent, workflow, system, resource, platform)
|
|
- `core/individual/` — 4 node types: RegulatoryNode (user-facing QA + short tasks), ConsciousnessNode (workflow planning), ControlNode (deprecated; name reserved for future remote-probe node), GrowthNode (capability expansion, not yet implemented)
|
|
- `core/global_state_machine/` — Provider registry, model config state
|
|
- `core/global_workflow_manager/` — Workflow queue & recovery
|
|
- `core/postgres_database/` — DAO layer: `model/` (SQLAlchemy models), `module/` (CRUD methods), `postgres.py` (facade)
|
|
- `worker_cluster/` — Task queue & worker dispatch
|
|
- `adapter/` — LLM model adapters (pydantic-ai AgentFactory)
|
|
- `plugin/tool_plugin/` — MCP-style tool plugins
|
|
- `utils/` — ray_hook, standalone_proxy, config_loader, access (JWT), i18n
|
|
|
|
### Frontend Layout (`frontend/src/`)
|
|
|
|
- `store/` — Zustand stores (useAppStore, useChatStore, etc.)
|
|
- `components/` — Chat, Agent, Plugin, Settings, Layout
|
|
- `api/client.ts` — Axios instance with auth interceptor
|
|
- `i18n/` — Chinese + English translations
|
|
|
|
### Key Patterns
|
|
|
|
- **Database facade**: `postgres.py` delegates to per-entity modules (`module/chat_history.py`, `module/persona_template.py`, etc.). Always add new DB methods to both the module AND the facade.
|
|
- **pydantic-ai agents**: Regulatory/Consciousness nodes use pydantic-ai with structured output (tool calls). Streaming chat uses direct httpx calls to OpenAI-compatible API instead.
|
|
- **SSE streaming**: Chat stream endpoint uses `StreamingResponse(media_type="text/event-stream")` with `data: {json}\n\n` format.
|
|
- **Config**: Multi-YAML in `config/` directory, loaded via `config_loader.py` at startup.
|
|
- **Alembic migrations**: `alembic/versions/` — naming convention: `YYYY_MM_DD_HHMM-NNNN_description.py`
|
|
|
|
### Environment Variables
|
|
|
|
- `KILOSTAR_MODE` — `standalone` or omit for distributed
|
|
- `KILOSTAR_SECRET_KEY` — JWT signing key
|
|
- `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` — DB connection
|
|
- `KILOSTAR_ENV` — `dev` or `prod`
|