siyuan-task-skill

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.

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:

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:

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:

# 任务描述

# 任务附件

# 下一步

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:

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:

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):

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:

python3 task_ops.py list

Find tasks by status:

python3 task_ops.py find "进行中"

Change task status (pass row_id from list output):

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):

python3 task_ops.py rename <row_id> "新名称"

Attach image to task sub-document (uploads file and inserts into section):

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:

python3 task_ops.py list-docs

Delete a task (also deletes sub-document):

python3 task_ops.py delete <row_id>

Migrate database (apply schema changes and reorder columns):

python3 task_ops.py migrate

Programmatic Usage

For complex workflows, import TaskManager directly in 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