siyuan-task

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:

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