docs: sync V2 status and process docs for issue #131
Some checks failed
CI / test (pull_request) Has been cancelled
Some checks failed
CI / test (pull_request) Has been cancelled
This commit is contained in:
agentson
216
docs/commands.md
216
docs/commands.md
@@ -1,156 +1,82 @@
|
||||
# Command Reference
|
||||
|
||||
## Common Command Failures
|
||||
|
||||
**Critical: Learn from failures. Never repeat the same failed command without modification.**
|
||||
|
||||
### tea CLI (Gitea Command Line Tool)
|
||||
|
||||
#### ❌ TTY Error - Interactive Confirmation Fails
|
||||
```bash
|
||||
~/bin/tea issues create --repo X --title "Y" --description "Z"
|
||||
# Error: huh: could not open a new TTY: open /dev/tty: no such device or address
|
||||
```
|
||||
**💡 Reason:** tea tries to open `/dev/tty` for interactive confirmation prompts, which is unavailable in non-interactive environments.
|
||||
|
||||
**✅ Solution:** Use `YES=""` environment variable to bypass confirmation
|
||||
```bash
|
||||
YES="" ~/bin/tea issues create --repo jihoson/The-Ouroboros --title "Title" --description "Body"
|
||||
YES="" ~/bin/tea issues edit <number> --repo jihoson/The-Ouroboros --description "Updated body"
|
||||
YES="" ~/bin/tea pulls create --repo jihoson/The-Ouroboros --head feature-branch --base main --title "Title" --description "Body"
|
||||
```
|
||||
|
||||
**📝 Notes:**
|
||||
- Always set default login: `~/bin/tea login default local`
|
||||
- Use `--repo jihoson/The-Ouroboros` when outside repo directory
|
||||
- tea is preferred over direct Gitea API calls for consistency
|
||||
|
||||
#### ❌ Wrong Parameter Name
|
||||
```bash
|
||||
tea issues create --body "text"
|
||||
# Error: flag provided but not defined: -body
|
||||
```
|
||||
**💡 Reason:** Parameter is `--description`, not `--body`.
|
||||
|
||||
**✅ Solution:** Use correct parameter name
|
||||
```bash
|
||||
YES="" ~/bin/tea issues create --description "text"
|
||||
```
|
||||
|
||||
### Gitea API (Direct HTTP Calls)
|
||||
|
||||
#### ❌ Wrong Hostname
|
||||
```bash
|
||||
curl http://gitea.local:3000/api/v1/...
|
||||
# Error: Could not resolve host: gitea.local
|
||||
```
|
||||
**💡 Reason:** Gitea instance runs on `localhost:3000`, not `gitea.local`.
|
||||
|
||||
**✅ Solution:** Use correct hostname (but prefer tea CLI)
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/repos/jihoson/The-Ouroboros/issues \
|
||||
-H "Authorization: token $GITEA_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title":"...", "body":"..."}'
|
||||
```
|
||||
|
||||
**📝 Notes:**
|
||||
- Prefer `tea` CLI over direct API calls
|
||||
- Only use curl for operations tea doesn't support
|
||||
|
||||
### Git Commands
|
||||
|
||||
#### ❌ User Not Configured
|
||||
```bash
|
||||
git commit -m "message"
|
||||
# Error: Author identity unknown
|
||||
```
|
||||
**💡 Reason:** Git user.name and user.email not set.
|
||||
|
||||
**✅ Solution:** Configure git user
|
||||
```bash
|
||||
git config user.name "agentson"
|
||||
git config user.email "agentson@localhost"
|
||||
```
|
||||
|
||||
#### ❌ Permission Denied on Push
|
||||
```bash
|
||||
git push origin branch
|
||||
# Error: User permission denied for writing
|
||||
```
|
||||
**💡 Reason:** Repository access token lacks write permissions or user lacks repo write access.
|
||||
|
||||
**✅ Solution:**
|
||||
1. Verify user has write access to repository (admin grants this)
|
||||
2. Ensure git credential has correct token with `write:repository` scope
|
||||
3. Check remote URL uses correct authentication
|
||||
|
||||
### Python/Pytest
|
||||
|
||||
#### ❌ Module Import Error
|
||||
```bash
|
||||
pytest tests/test_foo.py
|
||||
# ModuleNotFoundError: No module named 'src'
|
||||
```
|
||||
**💡 Reason:** Package not installed in development mode.
|
||||
|
||||
**✅ Solution:** Install package with dev dependencies
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
#### ❌ Async Test Hangs
|
||||
```python
|
||||
async def test_something(): # Hangs forever
|
||||
result = await async_function()
|
||||
```
|
||||
**💡 Reason:** Missing pytest-asyncio or wrong configuration.
|
||||
|
||||
**✅ Solution:** Already configured in pyproject.toml
|
||||
```toml
|
||||
[tool.pytest.ini_options]
|
||||
asyncio_mode = "auto"
|
||||
```
|
||||
No decorator needed for async tests.
|
||||
|
||||
## Build & Test Commands
|
||||
## Core Runtime Commands
|
||||
|
||||
```bash
|
||||
# Install all dependencies (production + dev)
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Run full test suite with coverage
|
||||
pytest -v --cov=src --cov-report=term-missing
|
||||
|
||||
# Run a single test file
|
||||
pytest tests/test_risk.py -v
|
||||
|
||||
# Run a single test by name
|
||||
pytest tests/test_brain.py -k "test_parse_valid_json" -v
|
||||
|
||||
# Lint
|
||||
ruff check src/ tests/
|
||||
|
||||
# Type check (strict mode, non-blocking in CI)
|
||||
mypy src/ --strict
|
||||
|
||||
# Run the trading agent
|
||||
# run (paper)
|
||||
python -m src.main --mode=paper
|
||||
|
||||
# Docker
|
||||
docker compose up -d ouroboros # Run agent
|
||||
docker compose --profile test up test # Run tests in container
|
||||
# run with dashboard thread
|
||||
python -m src.main --mode=paper --dashboard
|
||||
|
||||
# tests
|
||||
pytest -v --cov=src
|
||||
|
||||
# lint
|
||||
ruff check src/ tests/
|
||||
|
||||
# type-check
|
||||
mypy src/ --strict
|
||||
```
|
||||
|
||||
## Environment Setup
|
||||
## Dashboard Runtime Controls
|
||||
|
||||
`Issue 4-3` 기준 반영:
|
||||
|
||||
- CLI: `--dashboard`
|
||||
- ENV: `DASHBOARD_ENABLED=true`
|
||||
- Host/Port:
|
||||
- `DASHBOARD_HOST` (default `127.0.0.1`)
|
||||
- `DASHBOARD_PORT` (default `8080`)
|
||||
|
||||
## Telegram Commands (현재 구현)
|
||||
|
||||
`main.py` 등록 기준:
|
||||
|
||||
- `/help`
|
||||
- `/status`
|
||||
- `/positions`
|
||||
- `/stop`
|
||||
- `/resume`
|
||||
|
||||
## Telegram Commands (미구현 상태)
|
||||
|
||||
V2 플랜 `Issue 4-1` 항목은 아직 미구현:
|
||||
|
||||
- `/report [KR|US]`
|
||||
- `/scenarios [KR|US]`
|
||||
- `/review [KR|US]`
|
||||
- `/dashboard`
|
||||
|
||||
## Gitea / tea Workflow Commands
|
||||
|
||||
이슈 선등록 후 작업 시작:
|
||||
|
||||
```bash
|
||||
# Create .env file from example
|
||||
cp .env.example .env
|
||||
|
||||
# Edit .env with your credentials
|
||||
# Required: KIS_APP_KEY, KIS_APP_SECRET, KIS_ACCOUNT_NO, GEMINI_API_KEY
|
||||
|
||||
# Verify configuration
|
||||
python -c "from src.config import Settings; print(Settings())"
|
||||
YES="" ~/bin/tea issues create \
|
||||
--repo jihoson/The-Ouroboros \
|
||||
--title "..." \
|
||||
--description "..."
|
||||
```
|
||||
|
||||
작업은 `worktree` 기준 권장:
|
||||
|
||||
```bash
|
||||
git worktree add ../The-Ouroboros-issue-<N> feature/issue-<N>-<slug>
|
||||
```
|
||||
|
||||
PR 생성:
|
||||
|
||||
```bash
|
||||
YES="" ~/bin/tea pulls create \
|
||||
--repo jihoson/The-Ouroboros \
|
||||
--head feature/issue-<N>-<slug> \
|
||||
--base main \
|
||||
--title "..." \
|
||||
--description "..."
|
||||
```
|
||||
|
||||
## Known tea CLI Gotcha
|
||||
|
||||
TTY 없는 환경에서는 `tea` 확인 프롬프트가 실패할 수 있습니다.
|
||||
항상 `YES=""`를 붙여 비대화식으로 실행하세요.
|
||||
|
||||
Reference in New Issue
Block a user