SIYUAN-23 - trckr

← SIYUAN-23

feature

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

Relationships Loading...

## Overview
Add backlink and reference exploration commands using undocumented SiYuan APIs.

## New Commands

```bash
siyuan ref backlinks BLOCK_ID                # Get blocks that link TO this block
siyuan ref backlinks2 BLOCK_ID               # Enhanced backlink view with more context
siyuan ref ids BLOCK_ID                      # Get all reference IDs from a block
```

## API Endpoints
- `/api/ref/getBacklink` - Get backlinks to a block (params: id, beforeLen, k, mk, mBeforeLen)
- `/api/ref/getBacklink2` - Enhanced backlink view (params: id, sort, mSort, k, mk)
- `/api/block/getRefIDs` - Get reference IDs (params: id)

## Implementation
1. Add 3 client methods to SiyuanClient
2. Add handler functions for each command
3. Create new `ref` CLI group
4. Create `tests/test_ref.py`
5. Create `tests/integration/test_ref_live.py`
6. Update README

## Output Format (text)
```
Backlinks to 20240101-abcdefg:
  
  From: 20240102-hijklmn (Document: My Notes)
    "...this references [[the target block]]..."
  
  From: 20240103-opqrstu (Document: Ideas)
    "...see also [[target]]..."
```

## QA Verification

### Pass Criteria
1. `siyuan ref --help` shows available subcommands
2. `siyuan ref backlinks BLOCK_ID` returns linking blocks
3. `siyuan ref backlinks2 BLOCK_ID` returns enhanced view
4. `siyuan ref ids BLOCK_ID` returns reference IDs
5. JSON output includes full response structure
6. All tests pass

### Fail Criteria
- Commands return errors for valid block IDs
- Missing or incorrect backlink data
- Test failures

Pull Requests (comma-separated URLs)

Attachments

Comments (2)

agent · 2026-02-03

## Implementation Complete Implemented backlink and reference commands using the undocumented SiYuan APIs. ### Changes Made **Client Methods (siyuan.py:889-958)** - `get_backlink(block_id, before_len, keyword, mention_keyword, mention_before_len)` - Calls `/api/ref/getBacklink` - `get_backlink2(block_id, sort, mention_sort, keyword, mention_keyword)` - Calls `/api/ref/getBacklink2` - `get_ref_ids(block_id)` - Calls `/api/block/getRefIDs` **Handler Functions (siyuan.py:2315-2442)** - `handle_ref_backlinks()` - Text output shows backlinks/mentions with document context - `handle_ref_backlinks2()` - Tabular text output with ID/Type/Content/HPath - `handle_ref_ids()` - Lists reference IDs and definition IDs **CLI Commands (siyuan.py:3744-3860)** - `siyuan ref backlinks BLOCK_ID` - Options: `--keyword`, `--mention-keyword`, `--format` - `siyuan ref backlinks2 BLOCK_ID` - Options: `--sort`, `--mention-sort`, `--keyword`, `--mention-keyword`, `--format` - `siyuan ref ids BLOCK_ID` - Options: `--format` ### Test Results - 31 new unit tests in `tests/test_ref.py` - All passing - Integration tests in `tests/integration/test_ref_live.py` - Requires live SiYuan - Full test suite (437 tests) - All passing ### Verification ```bash $ siyuan --token test ref --help Commands: backlinks Get blocks that link TO this block. backlinks2 Enhanced backlink view with more context and sorting. ids Get all reference IDs from a block. ```

triage-agent · 2026-02-03

## Feature Triage Complete **Status:** NOT IMPLEMENTED **Summary:** This feature requests three new commands for exploring backlinks and reference relationships using undocumented SiYuan APIs: - `siyuan ref backlinks` - Uses `/api/ref/getBacklink` - `siyuan ref backlinks2` - Uses `/api/ref/getBacklink2` (with sorting) - `siyuan ref ids` - Uses `/api/block/getRefIDs` **Note:** An existing `siyuan search ref` command uses a different API (`/api/search/searchRefBlock`) that searches for blocks containing references rather than retrieving backlinks. **Implementation Location:** - Client methods: ~line 460-500 in siyuan.py - Handler functions: ~line 2200-2300 in siyuan.py - New `ref` CLI group: ~line 3530 in siyuan.py - New test files: `tests/test_ref.py` and `tests/integration/test_ref_live.py` **Complexity:** Low-Medium (follows existing patterns, ~500 lines total across all files) See attached triage report for full details including API documentation from SiYuan source code.