SIYUAN-27 - trckr

← SIYUAN-27

feature

Created: 2026-02-02 • Updated: 2026-02-03

Relationships Loading...

## Overview
Add flashcard/spaced repetition commands using the undocumented Riff API.

## New Commands

```bash
# Deck management
siyuan riff decks                            # List all decks
siyuan riff create-deck "Deck Name"          # Create a new deck

# Card management  
siyuan riff add DECK_ID BLOCK_ID             # Add block as flashcard
siyuan riff add DECK_ID BLOCK_ID1 BLOCK_ID2  # Add multiple blocks
siyuan riff cards DECK_ID                    # List cards in deck
siyuan riff remove CARD_ID                   # Remove a card

# Review
siyuan riff due                              # Get all due cards
siyuan riff due --deck DECK_ID               # Due cards for specific deck
siyuan riff review CARD_ID --rating 3        # Submit review (0-4: again, hard, good, easy, perfect)
siyuan riff reset DECK_ID                    # Reset deck progress
```

## API Endpoints
- `/api/riff/getRiffDecks` - List decks
- `/api/riff/createRiffDeck` - Create deck (params: name)
- `/api/riff/addRiffCards` - Add cards (params: deckID, blockIDs)
- `/api/riff/getRiffCards` - Get cards in deck (params: deckID, page)
- `/api/riff/removeRiffCards` - Remove cards (params: deckID, blockIDs)
- `/api/riff/getRiffDueCards` - Get due cards (params: deckID, notebook, reviewedCards)
- `/api/riff/reviewRiffCard` - Submit review (params: deckID, cardID, rating, reviewedCards)
- `/api/riff/resetRiffCards` - Reset cards (params: deckID, blockIDs, type)

## Implementation
1. Add 8 client methods to SiyuanClient
2. Add handler functions for each command
3. Create `riff` CLI group
4. Create `tests/test_riff.py`
5. Create `tests/integration/test_riff_live.py`
6. Update README

## Output Format (decks)
```
Flashcard Decks:

ID: deck-abc123
  Name: Programming
  Cards: 50 (12 due)
  
  ID: deck-def456
  Name: Languages
  Cards: 100 (5 due)
```

## Output Format (due cards)
```
Due Cards (17 total):

Card: card-123
  Deck: Programming
  Block: What is recursion?
  Due: now (overdue by 2 days)
  
  Card: card-456
  Deck: Languages
  Block: Conjugate "faire"
  Due: in 1 hour
```

## QA Verification

### Pass Criteria
1. `siyuan riff --help` shows all subcommands
2. `siyuan riff decks` lists existing decks
3. `siyuan riff create-deck "Test"` creates a deck and returns ID
4. `siyuan riff add DECK_ID BLOCK_ID` adds card successfully
5. `siyuan riff due` shows cards needing review
6. `siyuan riff review CARD_ID --rating 3` submits review
7. All tests pass

### Fail Criteria
- Deck operations fail
- Card addition fails for valid blocks
- Review submission doesn't update card state
- Test failures

Pull Requests (comma-separated URLs)

Attachments

Comments (3)

Claude QA · 2026-02-03

## QA Verification Complete ✅ **Status:** VERIFIED - All checks passed ### Summary Comprehensive QA performed on commit faacdc9. The implementation is **production-ready** with no issues found. ### Verification Results - ✅ **Implementation:** All 10 client methods, handlers, and CLI commands implemented correctly - ✅ **Testing:** 72 tests (50 unit + 22 integration) all PASSING - ✅ **CLI:** All commands functional with proper help text and examples - ✅ **Documentation:** README comprehensively updated with examples and usage - ✅ **Code Quality:** Follows project patterns, proper typing, no duplication - ✅ **Pass Criteria:** All 7 acceptance criteria met ### Test Results - Total tests: 583/583 passing - Riff unit tests: 50/50 passing - Riff integration tests: 22/22 passing - Test execution: 2.09 seconds ### Code Metrics - Lines added: 1,868 - Client methods: 10 - CLI commands: 10 - Test coverage: Comprehensive **Full QA report:** /tmp/qa-SIYUAN-27.md **Recommendation:** Issue ready for production use.

agent · 2026-02-03

## Implementation Complete Implemented complete flashcard (Riff) CLI commands for SiYuan. ### Changes Made **Client Methods** (siyuan.py:1192-1310): - `get_riff_decks()` - List all flashcard decks - `create_riff_deck(name)` - Create a new deck - `rename_riff_deck(deck_id, name)` - Rename a deck - `remove_riff_deck(deck_id)` - Remove a deck - `add_riff_cards(deck_id, block_ids)` - Add blocks as flashcards - `remove_riff_cards(deck_id, block_ids)` - Remove cards from deck - `get_riff_cards(deck_id, page)` - Get cards in deck with pagination - `get_riff_due_cards(deck_id, notebook, reviewed_cards)` - Get due cards - `review_riff_card(deck_id, card_id, rating, reviewed_cards)` - Submit review - `reset_riff_cards(deck_id, block_ids, reset_type)` - Reset card progress **Handler Functions** (siyuan.py:3189-3377): - 10 handler functions for CLI command logic - Proper text and JSON output formatting **CLI Commands** (siyuan.py:5127-5311): - `riff decks` - List all decks - `riff create-deck NAME` - Create deck - `riff rename-deck DECK_ID NAME` - Rename deck - `riff remove-deck DECK_ID` - Remove deck - `riff add DECK_ID BLOCK_IDS...` - Add cards - `riff remove DECK_ID BLOCK_IDS...` - Remove cards - `riff cards DECK_ID [--page N] [--all]` - List cards - `riff due [--deck ID] [--notebook ID]` - Get due cards - `riff review DECK_ID CARD_ID --rating N` - Submit review - `riff reset DECK_ID BLOCK_IDS...` - Reset progress ### Testing - 50 unit tests in tests/test_riff.py - all passing - Integration tests in tests/integration/test_riff_live.py - Full test suite: 583 tests passing ### Documentation README.md updated with complete riff command documentation.

triage-agent · 2026-02-03

## Triage Complete **Status:** NOT IMPLEMENTED - Feature does not exist in current codebase **Summary:** - No riff/flashcard functionality currently exists in siyuan-cli - Research confirmed 10 Riff API endpoints in SiYuan kernel (undocumented in official API.md) - Implementation follows established patterns (similar to `ai` command group) **Key Findings:** - API endpoints confirmed via kernel source code analysis - Uses FSRS algorithm with rating scale 0-4 (again, hard, good, easy, perfect) - Pagination required for getRiffCards endpoint - reviewedCards accumulator needed for review sessions **Implementation Scope:** - ~450 lines in siyuan.py (client methods, handlers, CLI group) - ~400 lines for unit tests (test_riff.py) - ~300 lines for integration tests (test_riff_live.py) - README updates **Complexity:** Medium See attached triage report at /tmp/triage-SIYUAN-27.md for full details including API parameter specifications.