--- 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 /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 /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 python3 task_ops.py complete python3 task_ops.py suspend ``` **Rename a task** (also renames sub-document): ```bash python3 task_ops.py rename "新名称" ``` **Attach image to task sub-document** (uploads file and inserts into section): ```bash python3 task_ops.py attach-image /path/to/image.png python3 task_ops.py attach-image /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 ``` **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, "/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: `(( "anchor text"))` 6. All API responses have `code` field — `0` means success

siyuan-task-skill

Scan your own AI components