search_workitems

Instructions

Implementation Reference

• tool-handlers/project-management.ts:128-159 (handler)

  Tool handler case for 'search_workitems' that parses arguments, calls searchWorkitemsFunc, and returns JSON stringified results.

  case "search_workitems": {
    const args = types.SearchWorkitemsSchema.parse(request.params.arguments);
    const workItems = await workitem.searchWorkitemsFunc(
      args.organizationId,
      args.category,
      args.spaceId,
      args.subject ?? undefined,
      args.status ?? undefined,
      args.createdAfter ?? undefined,
      args.createdBefore ?? undefined,
      args.updatedAfter ?? undefined,
      args.updatedBefore ?? undefined,
      args.creator ?? undefined,
      args.assignedTo ?? undefined,
      args.sprint ?? undefined,
      args.workitemType ?? undefined,
      args.statusStage ?? undefined,
      args.tag ?? undefined,
      args.priority ?? undefined,
      args.subjectDescription ?? undefined,
      args.finishTimeAfter ?? undefined,
      args.finishTimeBefore ?? undefined,
      args.updateStatusAtAfter ?? undefined,
      args.updateStatusAtBefore ?? undefined,
      args.advancedConditions ?? undefined,
      args.orderBy ?? "gmtCreate",
      args.includeDetails ?? false
    );
    return {
      content: [{ type: "text", text: JSON.stringify(workItems, null, 2) }],
    };
  }

• operations/projex/types.ts:288-317 (schema)

  Zod schema definition for SearchWorkitems input parameters, including all filters and options.

  export const SearchWorkitemsSchema = z.object({
    organizationId: z.string().describe("Organization ID"),
    category: z.string().describe("Search for work item types, such as Req (requirement), Task (task), Bug (defect), etc., multiple values separated by commas"),
    spaceId: z.string().describe("Project ID, project unique identifier"),
  
    // Simplified search parameters
    subject: z.string().nullable().optional().describe("Text contained in the title"),
    status: z.string().nullable().optional().describe("Status ID, multiple separated by commas. Status names and their IDs: Pending Confirmation (28), Pending Processing (100005), Reopened (30), Deferred Fix (34), Confirmed (32), Selected (625489), In Analysis (154395), Analysis Complete (165115), In Progress (100010), In Design (156603), Design Complete (307012), In Development (142838), Development Complete (100011), In Testing (100012)"),
    createdAfter: z.string().nullable().optional().describe("Created not earlier than, format: YYYY-MM-DD"),
    createdBefore: z.string().nullable().optional().describe("Created not later than, format: YYYY-MM-DD"),
    updatedAfter: z.string().nullable().optional().describe("Updated not earlier than, format: YYYY-MM-DD"),
    updatedBefore: z.string().nullable().optional().describe("Updated not later than, format: YYYY-MM-DD"),
    creator: z.string().nullable().optional().describe("Creator user ID, multiple values separated by commas. Special value 'self' can be used to represent the current user"),
    assignedTo: z.string().nullable().optional().describe("Assignee user ID, multiple values separated by commas. Special value 'self' can be used to represent the current user"),
    sprint: z.string().nullable().optional().describe("Sprint ID, multiple values separated by commas"),
    workitemType: z.string().nullable().optional().describe("Work item type ID, multiple values separated by commas"),
    statusStage: z.string().nullable().optional().describe("Status stage ID, multiple values separated by commas"),
    tag: z.string().nullable().optional().describe("Tag ID, multiple values separated by commas"),
    priority: z.string().nullable().optional().describe("Priority ID, multiple values separated by commas"),
    subjectDescription: z.string().nullable().optional().describe("Text contained in title or description"),
    finishTimeAfter: z.string().nullable().optional().describe("Finish time not earlier than, format: YYYY-MM-DD"),
    finishTimeBefore: z.string().nullable().optional().describe("Finish time not later than, format: YYYY-MM-DD"),
    updateStatusAtAfter: z.string().nullable().optional().describe("Status update time not earlier than, format: YYYY-MM-DD"),
    updateStatusAtBefore: z.string().nullable().optional().describe("Status update time not later than, format: YYYY-MM-DD"),
  
    // Advanced parameters
    advancedConditions: z.string().nullable().optional().describe("Advanced filter conditions, JSON format"),
    orderBy: z.string().optional().default("gmtCreate").describe("Sort field, default is gmtCreate. Possible values: gmtCreate, subject, status, priority, assignedTo"),
    includeDetails: z.boolean().optional().describe("Set to true when you need work item descriptions/detailed content. This automatically fetches missing descriptions instead of requiring separate get_work_item calls. RECOMMENDED: Use includeDetails=true when user asks for 'detailed content', 'descriptions', or 'full information' of work items. This is more efficient than calling get_work_item multiple times. Default is false")
  });

• tool-registry/project-management.ts:51-55 (registration)

  Tool registration entry defining name, description, and input schema for 'search_workitems'.

  {
    name: "search_workitems",
    description: "[Project Management] Search work items with various filter conditions",
    inputSchema: zodToJsonSchema(types.SearchWorkitemsSchema),
  },

• operations/projex/workitem.ts:30-151 (helper)

  Core helper function implementing the search logic: handles 'self', builds conditions, calls API, parses response, optionally fetches details.

  export async function searchWorkitemsFunc(
    organizationId: string,
    category: string,
    spaceId: string,
    subject?: string,
    status?: string,
    createdAfter?: string,
    createdBefore?: string,
    updatedAfter?: string,
    updatedBefore?: string,
    creator?: string,
    assignedTo?: string,
    sprint?: string,
    workitemType?: string,
    statusStage?: string,
    tag?: string,
    priority?: string,
    subjectDescription?: string,
    finishTimeAfter?: string,
    finishTimeBefore?: string,
    updateStatusAtAfter?: string,
    updateStatusAtBefore?: string,
    advancedConditions?: string,
    orderBy: string = "gmtCreate",
    includeDetails: boolean = false // 新增参数：是否自动补充缺失的description等详细信息
  ): Promise<z.infer<typeof WorkItemSchema>[]> {
    // 处理assignedTo为"self"的情况，自动获取当前用户ID
    let finalAssignedTo = assignedTo;
    let finalCreator = creator;
    
    if (assignedTo === "self" || creator === "self") {
      try {
        const currentUser = await getCurrentUserFunc();
        if (currentUser.id) {
          if (assignedTo === "self") {
            finalAssignedTo = currentUser.id;
          }
          if (creator === "self") {
            finalCreator = currentUser.id;
          }
        } else {
          finalAssignedTo = assignedTo;
          finalCreator = creator;
        }
      } catch (error) {
        finalAssignedTo = assignedTo;
        finalCreator = creator;
      }
    }
  
    const url = `/oapi/v1/projex/organizations/${organizationId}/workitems:search`;
  
    const payload: Record<string, any> = {
      category: category,
      spaceId: spaceId,
    };
  
    const conditions = buildWorkitemConditions({
      subject,
      status,
      createdAfter,
      createdBefore,
      updatedAfter,
      updatedBefore,
      creator: finalCreator,
      assignedTo: finalAssignedTo,
      sprint,
      workitemType,
      statusStage,
      tag,
      priority,
      subjectDescription,
      finishTimeAfter,
      finishTimeBefore,
      updateStatusAtAfter,
      updateStatusAtBefore,
      advancedConditions
    });
    
    if (conditions) {
      payload.conditions = conditions;
    }
  
    payload.orderBy = orderBy;
  
    const response = await yunxiaoRequest(url, {
      method: "POST",
      body: payload,
    });
  
    if (!Array.isArray(response)) {
      return [];
    }
  
    const workItems = response.map(workitem => WorkItemSchema.parse(workitem));
  
    // 如果需要补充详细信息，使用分批并发方式获取
    if (includeDetails) {
      const itemsNeedingDetails = workItems.filter(item => 
        item.id.length > 0 &&
        (item.description === null || item.description === undefined || item.description === "")
      );
  
      if (itemsNeedingDetails.length > 0) {
        // 分批并发获取详情
        const descriptionMap = await batchGetWorkItemDetails(organizationId, itemsNeedingDetails);
  
        // 更新workItems中的description
        return workItems.map(item => {
          if (descriptionMap.has(item.id)) {
            return {
              ...item,
              description: descriptionMap.get(item.id) || item.description
            };
          }
          return item;
        });
      }
    }
  
    return workItems;
  }