Yuzhiran Dev
9c37c9a574
Phase 4: org_id 注入 JWT/API 过滤/组织管理 CRUD/前端组织列 测试: tests/test_phase_upgrades.py 97项全覆盖 CSS: theme-modern.css 共享 mobile-card-list/status-dot/search-bar 等模式 修复: initial_data.py LLM配置 NOT NULL 约束, TopicResponse 含 org_id
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## Stack
|
|
- **Backend**: FastAPI 0.104 + SQLAlchemy 2.0 + PostgreSQL 15 (`yzr_nr`)
|
|
- **Frontend**: Vue 3 (CDN, no build step) + Element Plus — static HTML served by FastAPI
|
|
- **Auth**: JWT (`python-jose` + bcrypt), default admin `admin/admin123`
|
|
- **Scheduler**: APScheduler (daily cron: 01:30 collect, 02:30 sync, 03:30 generate, 04:30 optimize, 05:00 optimize_sources)
|
|
- **LLM**: Multi-provider (opencode-go primary, nvidia backup). API keys only in `.env`, not DB.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Start server (with detach to survive shell timeout)
|
|
cd /root/openclaw-workspace/projects/yu-zhi-ran
|
|
setsid ./start-platform.sh 8001
|
|
|
|
# Run full integration test
|
|
cd /root/openclaw-workspace/projects/yu-zhi-ran && python3 tests/test_new_features.py
|
|
|
|
# Run specific scripts (from project root)
|
|
python3 scripts/collector.py
|
|
python3 scripts/creator.py --topic-id B02
|
|
```
|
|
|
|
## Project layout
|
|
|
|
```
|
|
yu-zhi-ran/
|
|
├── platform/
|
|
│ ├── backend/app/main.py # FastAPI entry, mounts frontend at /
|
|
│ ├── backend/app/api/*.py # 21 API routers
|
|
│ ├── backend/app/core/ # nvidia_client.py, scheduler.py, etc.
|
|
│ ├── backend/app/models.py # SQLAlchemy models (593 lines)
|
|
│ ├── backend/app/schemas.py # Pydantic schemas (504 lines)
|
|
│ ├── backend/app/database.py # PG env config + ALTER TABLE migrations
|
|
│ ├── backend/app/initial_data.py
|
|
│ └── backend/.env # API keys, DB creds
|
|
├── scripts/ # creator.py, writer.py, collector.py, etc.
|
|
├── tests/test_new_features.py # 33-test integration suite
|
|
└── PROGRESS.md # Single source of truth for project status
|
|
```
|
|
|
|
## Gotchas & conventions
|
|
|
|
### Server
|
|
- Shell timeout kills background processes — always use `setsid` to start
|
|
- Env in `platform/backend/.env`, loaded via `dotenv` at each module level
|
|
|
|
### Database
|
|
- `init_db()` in `database.py` runs ALTER TABLE migrations at startup (PostgreSQL)
|
|
- `USE_POSTGRES=false` falls back to SQLite (used in tests)
|
|
- Models have timezone-aware `DateTime(timezone=True)` columns
|
|
|
|
### LLM
|
|
- `call_llm()` in `core/nvidia_client.py` — reads active provider from DB `LLMConfig.is_active`, API key from env
|
|
- DeepSeek reasoning models return `reasoning_content` (thinking) + `content` (answer). `call_llm` prefers `content`, falls back to tail of `reasoning_content`
|
|
- `max_tokens` must be generous (≥500 for tags/titles, ≥2000 for article content) — reasoning models consume tokens for thinking
|
|
- Schema (`LLMConfigResponse`) must include `provider`, `base_url`, `api_key` fields or they get silently dropped from API responses
|
|
|
|
### Frontend
|
|
- No npm build step — edit `.html` files directly
|
|
- H5 mobile nav only created when `window.innerWidth <= 768`
|
|
- `navigation-component.js` + `navbar-component.js` injected as Vue components
|
|
- For date filters on topics, use backend `?today=true` (server-side `date.today()`) — client-side `new Date()` gives UTC which differs from Asia/Shanghai by 8h
|
|
|
|
### Tests
|
|
- `test_new_features.py` starts its own uvicorn on port 18503, runs against SQLite
|
|
- Run from project root: `python3 tests/test_new_features.py`
|
|
|
|
### Project status
|
|
- PROGRESS.md is the single truth source for progress — update it after any significant task
|
|
- `archive/` dir keeps historical/outdated docs with `YYYY-MM-DD` date suffix
|