Obsidian TickTick Sync

Use this skill to keep a two-system workflow stable:

• Long-term project context in Obsidian notes
• Short-term tasks with deadlines/recurrence in TickTick (or Dida365)

This skill uses TickTick/Dida365 official OpenAPI and writes ticktick_task_id back to source markdown task lines. It also syncs completion state for existing pushed tasks by default (sync:: pushed + ticktick_task_id).

Load References When Needed

• Read references/metadata-schema.md before parsing/updating markdown inline fields.
• Read references/runbook.md for rollout strategy (pending first, then skip) and retry handling.
• Read references/openapi-notes.md if project/list mapping or recurrence mapping needs tuning.

Quick Start

1) Preflight

python3 skills/obsidian-ticktick-sync/scripts/doctor.py \
  --vault-root "/path/to/Obsidian/Vault" \
  --check-api \
  --provider dida365 \
  --access-token "$DIDA365_ACCESS_TOKEN"

2) Dry run (no remote write, no markdown mutation)

python3 skills/obsidian-ticktick-sync/scripts/sync.py \
  --vault-root "/path/to/Obsidian/Vault" \
  --provider dida365 \
  --dry-run \
  --sync-values pending

3) Real sync (push + writeback)

python3 skills/obsidian-ticktick-sync/scripts/sync.py \
  --vault-root "/path/to/Obsidian/Vault" \
  --provider dida365 \
  --access-token "$DIDA365_ACCESS_TOKEN" \
  --sync-values pending

# disable existing-task updates if you only want create-wave behavior
#  --no-sync-existing

Typical Workflow

1. Keep actionable checklist lines in project notes with inline fields (sync, ticktick, ddl, recur, action_id).
2. Run sync.py with --sync-values pending for first wave.
3. Existing pushed tasks (sync:: pushed + ticktick_task_id) are updated in place (including completion status from checkbox).
4. Review generated report in <vault>/scripts/ticktick_sync_report_*.md.
5. Run second wave with --sync-values pending,skip when ready.

Script Map

• scripts/sync.py: One-command orchestrator (extract -> push -> writeback -> report)
• scripts/extract.py: Select candidate tasks from markdown
• scripts/push.py: Push selected tasks to TickTick/Dida365
• scripts/writeback.py: Write sync:: pushed and ticktick_task_id:: ... back to markdown
• scripts/report.py: Render markdown report from JSON artifacts
• scripts/doctor.py: Environment and API preflight checks

Execution Rules

• Prefer running sync.py first; call lower-level scripts only when debugging.
• Default filter is ticktick=yes and sync in {pending}.
• Default also runs an update wave for existing tasks (sync in {pushed}) to sync completion/open status.
• Default requires schedule signal: at least one of ddl or recur.
• Existing tasks with ticktick_task_id are updated by default in sync.py; use --skip-existing to disable that.
• Keep writeback immediate after successful push to avoid duplicate exports.

Common Commands

Export only (no push)

python3 skills/obsidian-ticktick-sync/scripts/extract.py \
  --vault-root "/path/to/Obsidian/Vault" \
  --sync-values pending \
  --output /tmp/ticktick_extract.json

Push only (from extracted JSON)

python3 skills/obsidian-ticktick-sync/scripts/push.py \
  --provider dida365 \
  --access-token "$DIDA365_ACCESS_TOKEN" \
  --input /tmp/ticktick_extract.json \
  --output /tmp/ticktick_push.json

Sync existing pushed tasks only (completion/status)

python3 skills/obsidian-ticktick-sync/scripts/sync.py \
  --vault-root "/path/to/Obsidian/Vault" \
  --provider dida365 \
  --access-token "$DIDA365_ACCESS_TOKEN" \
  --sync-values pushed \
  --existing-sync-values pushed \
  --sync-existing

Writeback only

python3 skills/obsidian-ticktick-sync/scripts/writeback.py \
  --input /tmp/ticktick_push.json \
  --output /tmp/ticktick_writeback.json

Notes

• Providers supported: dida365, ticktick.
• Token input supports either --access-token or --token-file.
• API errors are kept in JSON reports with per-task context.