Manage tasks in SiYuan Note via its HTTP API. Create, query, update, and organize tasks stored in the 任务清单 document (with a TASK database) and sub-documents for related materials. Use when the user mentions SiYuan, task management, or needs to track work items.
---
name: siyuan-task
description: Manage tasks in SiYuan Note via its HTTP API. Create, query, update, and organize tasks stored in the 任务清单 document (with a TASK database) and sub-documents for related materials. Use when the user mentions SiYuan, task management, or needs to track work items.
compatibility: Requires Python 3.7+ and network access to SiYuan Note instance.
metadata:
author: walter
version: "1.0"
allowed-tools: Bash(python3:*)
---
# SiYuan Note Task Management
Manage tasks in SiYuan Note (思源笔记) via Python scripts. All connection settings are in `config.env` — modify that file when the SiYuan instance address or credentials change.
## Configuration
Edit `config.env` in the skill root directory. Only 3 items need manual configuration:
```env
SIYUAN_API_URL=http://100.64.0.11:52487
SIYUAN_API_TOKEN=xxxxxxxxxxxxxxxx
SIYUAN_NOTEBOOK_NAME=work
```
Note: `SIYUAN_NOTEBOOK_ID` is auto-resolved from `SIYUAN_NOTEBOOK_NAME` at runtime. You can still set it explicitly to skip the lookup.
Then run `init` to auto-create the database and write remaining config:
```bash
cd <skill_root>/scripts
python3 task_ops.py init
```
This creates the 任务清单 document, the TASK database, all columns, and writes AV_ID / COL_* IDs back to `config.env` automatically. If the 任务清单 document already contains a TASK database (e.g. copied from another notebook), `init` will detect and reuse it instead of creating a duplicate.
## Task Data Model
Tasks are stored as rows in a **TASK database (Attribute View)** block inside the 任务清单 document. Each row has these columns:
| Column | Chinese | Type | Values / Colors |
|--------|---------|------|-----------------|
| 主键 | 任务名称 | block | Primary key — task name |
| 任务内容 | 任务内容 | text | Task description / details (what the task is about) |
| 相关方 | 相关方 | text | Free text |
| 重要程度 | 重要程度 | select | 高(红) / 中(绿) / 低(灰) |
| 紧急程度 | 紧急程度 | select | 高(红) / 中(绿) / 低(灰) |
| 状态 | 状态 | select | 未开始(灰) / 进行中(绿) / 结束(红) / 挂起(蓝) |
| 备注 | 备注 | text | Extra notes / supplementary remarks (not the main task info) |
| 创建时间 | 创建时间 | created | Auto |
| 开始时间 | 开始时间 | date | Timestamp |
| 结束时间 | 结束时间 | date | Timestamp |
| 更新时间 | 更新时间 | updated | Auto |
Database IDs (auto-generated in `config.env` by `init` command):
- `AV_ID` — Attribute View ID
- `AV_BLOCK_ID` — AV block ID
- `COL_*` — Column IDs for each field
Each task automatically gets a sub-document under `/任务清单/{task_name}` with this template:
```markdown
# 任务描述
# 任务附件
# 下一步
```
The sub-document name always matches the task name. The task's primary key in the database is linked to the sub-document (non-detached), showing a document icon. Renaming a task also renames its sub-document. Deleting a task also deletes its sub-document.
## Scripts
All scripts are in the `scripts/` directory. Run from that directory:
```bash
cd <skill_root>/scripts
```
### siyuan_api.py — Base API Client
Low-level client wrapping all SiYuan HTTP API endpoints. Used by `task_ops.py` internally. Can also be imported directly for custom operations:
```python
from siyuan_api import SiYuanClient
client = SiYuanClient()
result = client.sql_query("SELECT * FROM blocks WHERE type = 'd' LIMIT 5")
```
Key methods: `sql_query`, `create_doc`, `append_block`, `update_block`, `delete_block`, `set_block_attrs`, `get_block_attrs`, `get_child_blocks`, `get_block_kramdown`, `export_md`, `upload_asset`, `push_msg`. See `references/API.md` for full SiYuan API reference.
### task_ops.py — Task CRUD Operations
High-level CLI for task management. All commands output JSON.
**Create a task** (auto-creates sub-document with template):
```bash
python3 task_ops.py create "任务名称" content="任务内容" importance="高" urgency="中" notes="备注信息"
```
Parameter mapping:
- `content` → 任务内容 (task description / main information about the task)
- `notes` → 备注 (supplementary remarks, not the main task info)
- `stakeholders` → 相关方
- `importance` → 重要程度 (高/中/低)
- `urgency` → 紧急程度 (高/中/低)
- `status` → 状态 (default: 未开始)
**List all tasks:**
```bash
python3 task_ops.py list
```
**Find tasks by status:**
```bash
python3 task_ops.py find "进行中"
```
**Change task status** (pass row_id from `list` output):
```bash
python3 task_ops.py start <row_id>
python3 task_ops.py complete <row_id>
python3 task_ops.py suspend <row_id>
```
**Rename a task** (also renames sub-document):
```bash
python3 task_ops.py rename <row_id> "新名称"
```
**Attach image to task sub-document** (uploads file and inserts into section):
```bash
python3 task_ops.py attach-image <row_id> /path/to/image.png
python3 task_ops.py attach-image <row_id> /path/to/image.png section="任务描述"
```
Default section is `任务附件`. On macOS, save clipboard image first: `osascript -e 'set png to (the clipboard as «class PNGf»)' -e 'set f to open for access (POSIX file "/tmp/clip.png") with write permission' -e 'write png to f' -e 'close access f'`
**List sub-documents:**
```bash
python3 task_ops.py list-docs
```
**Delete a task** (also deletes sub-document):
```bash
python3 task_ops.py delete <row_id>
```
**Migrate database** (apply schema changes and reorder columns):
```bash
python3 task_ops.py migrate
```
## Programmatic Usage
For complex workflows, import `TaskManager` directly in Python:
```python
import sys; sys.path.insert(0, "<skill_root>/scripts")
from task_ops import TaskManager
tm = TaskManager()
# Create task (auto-creates sub-document with template)
result = tm.create_task("实现用户登录", content="OAuth2 集成", importance="高", urgency="高")
row_id = result["row_id"]
doc_id = result["doc_id"]
# Rename task (also renames sub-document)
tm.rename_task(row_id, "实现OAuth2登录")
# Status transitions
tm.start_task(row_id)
tm.complete_task(row_id)
# Delete task (also deletes sub-document)
tm.delete_task(row_id)
# Attach image to task sub-document (default section: 任务附件)
tm.attach_image_to_task(row_id, "/path/to/image.png")
tm.attach_image_to_task(row_id, "/path/to/image.png", section="任务描述")
```
## Important Notes
1. The 任务清单 document and TASK database are auto-created on first use
2. Tasks are stored as database rows (Attribute View), not plain blocks
3. `row_id` from `list` output is used for all update/delete operations
4. `创建时间` and `更新时间` columns are auto-managed by SiYuan
5. Block references use SiYuan format: `((<block_id> "anchor text"))`
6. All API responses have `code` field — `0` means success
don't have the plugin yet? install it then click "run inline in claude" again.