wecomcli-get-todo-list

intent

fetch a paginated summary of your wecom todo items, optionally filtered by creation time or reminder time. use this when the user asks to browse their todo overview ("show my todo list", "what do i have to do this week", "list all my todos", etc.). the list itself contains only ids and metadata; you must always chain a call to wecomcli-get-todo-detail to show the user actual content and assignee info.

inputs

• wecom-cli binary: must be installed and executable on the system path. verify with which wecom-cli before calling.
• wecom auth: wecom-cli must be pre-authenticated (credentials stored locally). if auth fails, the command will return errcode 40001 or similar. no additional env vars needed.
• optional time parameters:
  • create_begin_time, create_end_time: filter todos by creation window, format YYYY-MM-DD HH:mm:ss.
  • remind_begin_time, remind_end_time: filter todos by reminder window, same format.
  • if user says "this week" or "next month", compute the date range from current date before passing.
• pagination cursor: on first call, omit cursor. on subsequent calls, pass the next_cursor from the previous response.
• limit: max items per page (default 10, max 20). use 20 for efficiency unless user specifies otherwise.

procedure

1. parse user intent and compute time filters (if applicable).

   • input: user utterance (e.g. "todos created in march", "reminders this week").
   • if relative dates mentioned, convert to absolute YYYY-MM-DD HH:mm:ss using current date.
   • output: filter object with zero or more of {create_begin_time, create_end_time, remind_begin_time, remind_end_time}.

2. build wecom-cli command for first page.

   • input: filter object from step 1, limit (default 20 for efficiency), no cursor.
   • construct json payload: {"create_begin_time": "...", ..., "limit": 20} (omit null fields).
   • output: command string wecom-cli todo get_todo_list '<json>'.

3. execute first page request.

   • input: command from step 2.
   • run the command; capture stdout and stderr.
   • if http error (timeout, 5xx, connection refused), retry up to 3 times with 2-second backoff before failing.
   • output: parsed json response with {errcode, errmsg, index_list[], next_cursor, has_more} or error state.

4. check for api errors.

   • input: response from step 3.
   • if errcode != 0, stop and report errmsg to user (e.g. "invalid time format").
   • if request failed after 3 retries, report "unable to fetch todos, wecom service unavailable".
   • output: validated response or error message.

5. extract todo ids and call wecomcli-get-todo-detail (mandatory).

   • input: index_list[] from step 4.
   • if index_list is empty, skip to step 8 (no todos found).
   • collect all todo_id values from index_list.
   • construct call to wecomcli-get-todo-detail with {"todo_id_list": [id1, id2, ...]}.
   • output: detail response with content and assignee for each todo.

6. merge summary and detail data.

   • input: index_list[] (summary) and detail response (content, assignee, etc.).
   • combine metadata from summary (status, create time, remind time) with content and assignee from detail.
   • output: enriched todo records ready to display.

7. check pagination state.

   • input: has_more boolean and next_cursor from step 4.
   • if has_more is true, prepare to offer pagination to user (see decision points below).
   • if has_more is false, all todos fetched.
   • output: pagination state.

8. display results to user.

   • input: enriched todo records from step 6, pagination state from step 7.
   • render todos in user-friendly format (content, assignee, status, times).
   • if has_more is true, append prompt: "there are more todos. would you like to see them?"
   • if no todos found, report "no todos matching your filters".
   • output: formatted message to user.

9. handle pagination continuation (if user says yes).

   • input: user confirmation, next_cursor from step 4, original filters from step 1.
   • rebuild command with cursor and same filters, repeat steps 2-8 for next page.
   • output: next batch of enriched todos with updated pagination state.

decision points

• if has_more is true after displaying page 1: always prompt user ("see more?") before stopping. do not hide the fact that more todos exist. only suppress the prompt if user explicitly says "no" or "that's enough".
• if index_list is empty on first call: do not call wecomcli-get-todo-detail. report "no todos found" directly.
• if http error occurs (timeout, 5xx, connection failure): retry up to 3 times with 2-second delay. after third failure, report error to user and stop (do not fall back to cached data).
• if errcode != 0 (api-level error): stop immediately. do not retry. report the errmsg from response.
• if time parameter is malformed: reject before calling wecom-cli. ask user to clarify (e.g. "please specify a valid date like 2025-03-15").
• if limit is not specified: default to 20 (max allowed) for efficiency.
• if user asks to continue pagination but next_cursor is missing or invalid: report error ("pagination cursor expired, please start over") and stop.

output contract

on success: return structured data to downstream skill (wecomcli-get-todo-detail) and/or render to user:

{
  "status": "success",
  "todos": [
    {
      "todo_id": "...",
      "content": "...",
      "creator_id": "...",
      "assignee": "...",
      "todo_status": 1,
      "user_status": 1,
      "create_time": "2025-01-15 10:30:00",
      "remind_time": "2025-06-01 09:00:00",
      "update_time": "2025-01-16 14:20:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "page_count": 1,
  "total_on_page": 3
}

on error: return error object:

{
  "status": "error",
  "error_code": "...",
  "error_message": "..."
}

file location: not applicable (in-memory response).

time format: all timestamps in response are YYYY-MM-DD HH:mm:ss.

status codes:

• todo_status: 0 (complete), 1 (in progress), 2 (deleted).
• user_status: 0 (rejected), 1 (accepted), 2 (completed).

outcome signal

• user can see their todos with full content, assignee, and metadata in a readable format.
• if more todos exist on next page, user sees explicit prompt asking whether to continue pagination.
• if no todos match filters, user is told so clearly.
• if api error occurs, user sees the error message (not a crash or silent failure).
• user never sees a todo without its content (i.e., wecomcli-get-todo-detail was always called).