SIYUAN-30 - trckr

← SIYUAN-30

feature

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

Relationships Loading...

## Overview
Add miscellaneous utility commands using undocumented SiYuan APIs.

## New Commands

```bash
# Block breadcrumb - show path to a block
siyuan block breadcrumb BLOCK_ID
# Output: Notebook > Folder > Document > Heading > Paragraph

# Recent documents
siyuan doc recent
siyuan doc recent --limit 10
# Output: List of recently opened documents

# Convert to standard markdown
siyuan doc to-markdown DOC_ID
siyuan doc to-markdown DOC_ID --output ./doc.md
# Output: Standard markdown (not Kramdown)
```

## API Endpoints
- `/api/block/getBlockBreadcrumb` - Get block path (params: id, excludeTypes)
  - Returns: [{id, name, type, subType, children}]
- `/api/storage/getRecentDocs` - Get recent documents
  - Returns: [{rootID, icon, title, viewedAt, closedAt}]
- `/api/lute/copyStdMarkdown` - Convert to standard MD (params: id)
  - Returns: string (markdown content)

## Implementation
1. Add 3 client methods to SiyuanClient
2. Add handler functions for each command
3. Extend `block` group with `breadcrumb` subcommand
4. Extend `doc` group with `recent` and `to-markdown` subcommands
5. Create `tests/test_utilities.py`
6. Create `tests/integration/test_utilities_live.py`
7. Update README

## Output Format (breadcrumb)
```
Block Path:
  My Notebook
    └── Projects
        └── API Integration
            └── Endpoints (heading)
                └── GET /users (paragraph) ← target
```

## Output Format (recent)
```
Recent Documents:

1. API Notes
     Viewed: 2024-01-15 10:30
     ID: 20240115-abcdefg
  
  2. Meeting Notes
     Viewed: 2024-01-14 15:00
     ID: 20240114-hijklmn
```

## Output Format (to-markdown)
```markdown
# Document Title

This is standard markdown without SiYuan-specific
Kramdown extensions like block IDs.

## Section

Regular content here.
```

## QA Verification

### Pass Criteria
1. `siyuan block breadcrumb BLOCK_ID` shows correct path
2. `siyuan doc recent` lists recently viewed documents
3. `siyuan doc recent --limit 5` respects limit
4. `siyuan doc to-markdown DOC_ID` outputs standard markdown
5. `--output` flag saves to file correctly
6. All tests pass

### Fail Criteria
- Breadcrumb shows incorrect hierarchy
- Recent docs not sorted by view time
- Markdown still contains Kramdown syntax
- Test failures

Pull Requests (comma-separated URLs)

Attachments

Comments (3)

QA-Agent · 2026-02-03

## QA Verification Complete ✅ **Status:** PASSED - All acceptance criteria met ### Verification Summary - ✅ All 314 unit tests passing (100%) - ✅ 25 new unit tests for utility commands - ✅ 15 integration tests for live API testing - ✅ All three commands properly registered and functional - ✅ Output formats match requirements - ✅ Code follows project patterns and conventions ### Commands Verified 1. `siyuan block breadcrumb BLOCK_ID` - Shows correct hierarchical path with tree visualization 2. `siyuan doc recent [--limit N]` - Lists recently viewed documents with proper timestamp formatting 3. `siyuan doc to-markdown DOC_ID [--output FILE]` - Converts to standard markdown with file output support ### Test Coverage - Client methods: 7 tests (breadcrumb, recent docs, to-markdown) - CLI commands: 18 tests (text/JSON output, limit, file output, error cases) - Integration tests: 15 live API tests Full QA report available at `/tmp/qa-SIYUAN-30.md` **Verdict:** Implementation is complete, well-tested, and production-ready.

agent · 2026-02-03

## Implementation Complete ### Changes Made **Client Methods (siyuan.py:713-755):** - `get_block_breadcrumb(block_id, exclude_types)` - Get hierarchical path for a block - `get_recent_docs()` - Get recently opened documents - `copy_std_markdown(block_id)` - Convert block/document to standard markdown **Handler Functions (siyuan.py:1063-1127 for doc, 1296-1343 for block):** - `handle_doc_recent()` - Handles recent docs with limit option and timestamp formatting - `handle_doc_to_markdown()` - Handles markdown conversion with file output option - `handle_block_breadcrumb()` - Handles breadcrumb with tree-style text output **CLI Commands:** - `siyuan block breadcrumb BLOCK_ID` - Shows path to block with tree visualization - `siyuan doc recent [--limit N]` - Lists recently viewed documents - `siyuan doc to-markdown DOC_ID [--output FILE]` - Converts to standard markdown ### Test Coverage - Unit tests: tests/test_utilities.py (25 tests) - Integration tests: tests/integration/test_utilities_live.py (15 tests) - All 314 unit tests pass ### Verification Ran `make test` - all unit tests pass

triage-agent · 2026-02-03

## Feature Triage Complete **Status:** NOT IMPLEMENTED - Ready to implement **Summary:** All three utility commands (block breadcrumb, doc recent, doc to-markdown) are not currently implemented in siyuan-cli. The three undocumented SiYuan APIs have been verified to exist and are actively used by SiYuan's own UI. **API Verification:** - `/api/block/getBlockBreadcrumb` - Confirmed via GitHub issues #8735, #13099, #13961 - `/api/storage/getRecentDocs` - Confirmed via GitHub release notes v3.4.0-dev3 - `/api/lute/copyStdMarkdown` - Confirmed via GitHub issue #15454 **Implementation Location:** - Client methods: siyuan.py ~line 300-400 - Handler functions: siyuan.py ~line 900-1200 - CLI commands: Extend block group (~line 1980) and doc group (~line 1814) **Complexity:** Low - follows established patterns exactly **Scope:** Small - ~150-200 lines of new code See full triage report at /tmp/triage-SIYUAN-30.md