@xihe-lab/tapd-core 2.0.0-rc.1 → 2.0.0-rc.3

package/dist/tools/story.js

@@ -1,32 +1,33 @@
 import { z } from 'zod';
 import { TapdClient } from '../tapd-client.js';
+import { RAW_HTML_FIELD } from '../registry/richtext.js';
 export const storyTools = [
     // 需求 CRUD
     {
         name: 'tapd_get_stories',
-        description: '获取需求列表',
+        description: '按条件查询需求列表，支持标题、状态、处理人、迭代、分类等多字段过滤与分页。只统计数量用数量统计工具；已知多个 ID 要完整详情用批量详情工具。读操作；limit 默认 30。返回需求（Story）数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('需求ID，支持多ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('需求 ID，支持多 ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe('需求标题，支持模糊匹配'),
             priority: z.string().optional().describe('优先级'),
             priority_label: z.string().optional().describe('优先级标签（推荐）'),
             status: z.string().optional().describe('状态'),
             v_status: z.string().optional().describe('状态（中文）'),
-            with_v_status: z.string().optional().describe('设为1返回中文状态'),
+            with_v_status: z.string().optional().describe('设为 1 返回中文状态'),
             label: z.string().optional().describe('标签'),
-            workitem_type_id: z.string().optional().describe('需求类别ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workitem_type_id: z.string().optional().describe('需求类别 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             owner: z.string().optional().describe('处理人，支持模糊匹配'),
             creator: z.string().optional().describe('创建人'),
             developer: z.string().optional().describe('开发人员'),
             cc: z.string().optional().describe('抄送人'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            include_sub_iteration: z.string().optional().describe('包含子迭代：0或1'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            include_sub_iteration: z.string().optional().describe('包含子迭代：0 或 1'),
             category_id: z.string().optional().describe('需求分类；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            include_sub_category: z.string().optional().describe('包含子分类：0或1'),
-            parent_id: z.string().optional().describe('父需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            ancestor_id: z.string().optional().describe('祖先需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            children_id: z.string().optional().describe('子需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            include_sub_category: z.string().optional().describe('包含子分类：0 或 1'),
+            parent_id: z.string().optional().describe('父需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            ancestor_id: z.string().optional().describe('祖先需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            children_id: z.string().optional().describe('子需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             begin: z.string().optional().describe('预计开始日期 YYYY-MM-DD'),
             due: z.string().optional().describe('预计结束日期 YYYY-MM-DD'),
             created: z.string().optional().describe('创建时间 YYYY-MM-DD HH:mm'),
@@ -43,9 +44,9 @@ export const storyTools = [
             source: z.string().optional().describe('需求来源'),
             type: z.string().optional().describe('需求类型'),
             description: z.string().optional().describe('详细描述'),
-            custom_field_one: z.string().optional().describe('自定义字段 (支持1-200)'),
-            limit: z.number().optional().describe('返回数量，默认30'),
-            page: z.number().optional().describe('页码，默认1'),
+            custom_field_one: z.string().optional().describe('自定义字段（支持 1-200）'),
+            limit: z.number().optional().describe('返回数量，默认 30'),
+            page: z.number().optional().describe('页码，默认 1'),
             order: z.string().optional().describe('排序'),
             fields: z.string().optional().describe('返回字段'),
         }),
@@ -64,20 +65,21 @@ export const storyTools = [
     },
     {
         name: 'tapd_create_story',
-        description: '创建需求（也可创建任务：传入 workitem_type_id 为 TASK 类型 ID 即可创建任务，适合仅有 stories::create 权限而无 tasks::create 权限的场景）',
+        description: '创建需求。兼可创建任务：工作项类别参数传「任务型」类别的 ID 即走任务创建（适合仅有需求创建权限而无任务创建权限的场景，类别可用类别查询工具查）。从已有需求复制用复制工具。写操作；name 必填，负责人/创建人缺省取环境变量 TAPD_NICK_NAME。返回新需求。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            name: z.string().describe('需求标题 (必填)'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            name: z.string().describe('需求标题（必填）'),
             description: z.string().optional().describe('详细描述'),
+            raw_html: RAW_HTML_FIELD,
             priority: z.string().optional().describe('优先级'),
             priority_label: z.string().optional().describe('优先级标签（推荐）'),
-            owner: z.string().optional().describe('处理人（默认当前用户）'),
-            creator: z.string().optional().describe('创建人（默认当前用户）'),
+            owner: z.string().optional().describe('处理人（缺省取当前用户）'),
+            creator: z.string().optional().describe('创建人（缺省取当前用户）'),
             developer: z.string().optional().describe('开发人员'),
             cc: z.string().optional().describe('抄送人'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             category_id: z.string().optional().describe('需求分类；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            parent_id: z.string().optional().describe('父需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            parent_id: z.string().optional().describe('父需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             begin: z.string().optional().describe('预计开始日期 YYYY-MM-DD'),
             due: z.string().optional().describe('预计结束日期 YYYY-MM-DD'),
             effort: z.string().optional().describe('预估工时'),
@@ -88,12 +90,12 @@ export const storyTools = [
             source: z.string().optional().describe('需求来源'),
             type: z.string().optional().describe('需求类型'),
             label: z.string().optional().describe('标签'),
-            template_id: z.string().optional().describe('模板ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            template_id: z.string().optional().describe('模板 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             business_value: z.string().optional().describe('业务价值'),
             test_focus: z.string().optional().describe('测试关注点'),
-            size: z.string().optional().describe('规模/大小'),
+            size: z.string().optional().describe('规模'),
             custom_field_one: z.string().optional().describe('自定义字段'),
-            workitem_type_id: z.string().optional().describe('工作项类型ID（可选，默认创建需求；传入 TASK 类型 ID 可创建任务。可通过 tapd_get_workitem_types 查询可用类型）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workitem_type_id: z.string().optional().describe('工作项类型 ID（可选，默认创建需求；传任务型类别 ID 可创建任务，可用类别查询工具查）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const nickName = TapdClient.getNickName();
@@ -124,17 +126,18 @@ export const storyTools = [
     },
     {
         name: 'tapd_update_story',
-        description: '更新需求',
+        description: '按 ID 更新需求的单个或多个字段（状态、处理人、迭代、工时等）。批量改多条用批量更新工具；整条复制用复制工具。写操作；id 必填。返回更新后的需求。',
         inputSchema: z.object({
-            id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
             name: z.string().optional().describe('需求标题'),
             description: z.string().optional().describe('详细描述'),
+            raw_html: RAW_HTML_FIELD,
             status: z.string().optional().describe('状态'),
             owner: z.string().optional().describe('处理人'),
             priority: z.string().optional().describe('优先级'),
             priority_label: z.string().optional().describe('优先级标签'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             category_id: z.string().optional().describe('需求分类；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             begin: z.string().optional().describe('预计开始日期'),
             due: z.string().optional().describe('预计结束日期'),
@@ -163,10 +166,10 @@ export const storyTools = [
     },
     {
         name: 'tapd_get_story_count',
-        description: '获取需求数量',
+        description: '按与需求列表查询相同的过滤条件返回需求数量，不返回列表。只关心「有多少条」时用它，比拉全量列表省流量。读操作。返回 {count}。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe('需求标题'),
             priority: z.string().optional().describe('优先级'),
             priority_label: z.string().optional().describe('优先级标签（推荐）'),
@@ -175,10 +178,10 @@ export const storyTools = [
             creator: z.string().optional().describe('创建人'),
             developer: z.string().optional().describe('开发人员'),
             cc: z.string().optional().describe('抄送人'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             category_id: z.string().optional().describe('需求分类；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            parent_id: z.string().optional().describe('父需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            ancestor_id: z.string().optional().describe('祖先需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            parent_id: z.string().optional().describe('父需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            ancestor_id: z.string().optional().describe('祖先需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             begin: z.string().optional().describe('预计开始日期'),
             due: z.string().optional().describe('预计结束日期'),
             created: z.string().optional().describe('创建时间'),
@@ -202,16 +205,16 @@ export const storyTools = [
     },
     {
         name: 'tapd_copy_story',
-        description: '复制需求',
+        description: '复制已有需求创建新需求，可选连带复制附件、评论、子任务。从零新建用创建工具。写操作；id 必填。返回新需求。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().describe('要复制的需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().describe('要复制的需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe('新需求标题（默认为原标题）'),
             owner: z.string().optional().describe('处理人'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            copy_attachments: z.number().optional().describe('是否复制附件，值=1复制'),
-            copy_comments: z.number().optional().describe('是否复制评论，值=1复制'),
-            copy_sub_tasks: z.number().optional().describe('是否复制子任务，值=1复制'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            copy_attachments: z.number().optional().describe('是否复制附件，值=1 为复制'),
+            copy_comments: z.number().optional().describe('是否复制评论，值=1 为复制'),
+            copy_sub_tasks: z.number().optional().describe('是否复制子任务，值=1 为复制'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -228,10 +231,10 @@ export const storyTools = [
     },
     {
         name: 'tapd_batch_update_stories',
-        description: '批量更新需求',
+        description: '一次批量更新最多 50 条需求。只改一条用单条更新工具。写操作；stories 传 JSON 数组字符串，每项含 id 与要改的字段。返回批量结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            stories: z.string().describe('需求更新数组JSON，最多50条 (必填)'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            stories: z.string().describe('需求更新数组JSON，最多50条（必填）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -244,12 +247,12 @@ export const storyTools = [
     // 需求分类
     {
         name: 'tapd_get_story_categories',
-        description: '获取需求分类列表',
+        description: '查询需求分类列表，支持名称模糊匹配与分页。只统计数量用数量统计工具。读操作。返回分类数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('分类ID，支持多ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('分类 ID，支持多 ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe('分类名称，支持模糊匹配'),
-            parent_id: z.string().optional().describe('父分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            parent_id: z.string().optional().describe('父分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             created: z.string().optional().describe('创建时间'),
             modified: z.string().optional().describe('修改时间'),
             limit: z.number().optional().describe('返回数量'),
@@ -267,12 +270,12 @@ export const storyTools = [
     },
     {
         name: 'tapd_get_story_categories_count',
-        description: '获取需求分类数量',
+        description: '按相同过滤条件返回需求分类数量。要看列表用分类列表查询工具。读操作。返回 {count}。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe('分类名称'),
-            parent_id: z.string().optional().describe('父分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            parent_id: z.string().optional().describe('父分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -284,11 +287,11 @@ export const storyTools = [
     },
     {
         name: 'tapd_add_story_category',
-        description: '创建需求分类',
+        description: '创建需求分类，可指定父分类 ID 挂到父分类下。写操作；name 必填。返回新分类。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            name: z.string().describe('分类名称 (必填)'),
-            parent_id: z.string().optional().describe('父分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            name: z.string().describe('分类名称（必填）'),
+            parent_id: z.string().optional().describe('父分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -300,12 +303,12 @@ export const storyTools = [
     },
     {
         name: 'tapd_update_story_category',
-        description: '更新需求分类',
+        description: '按 ID 更新需求分类（改名或调整父分类）。写操作；id 必填。返回更新后的分类。',
         inputSchema: z.object({
-            id: z.string().describe('分类ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            id: z.string().describe('分类 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
             name: z.string().optional().describe('分类名称'),
-            parent_id: z.string().optional().describe('父分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            parent_id: z.string().optional().describe('父分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -318,9 +321,9 @@ export const storyTools = [
     // 需求类别
     {
         name: 'tapd_get_workitem_types',
-        description: '获取需求类别列表',
+        description: '查询项目工作项类别列表（需求/缺陷/任务等类型及类别 ID）。给创建、工作流类工具取类别 ID 前先查这里。注意：需要 stories::workitem_types 权限，无权限时 403。读操作。返回类别数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -332,11 +335,11 @@ export const storyTools = [
     },
     {
         name: 'tapd_change_workitem_type',
-        description: '更新需求类别',
+        description: '把需求变更到另一个工作项类别（如普通需求转任务型类别）。查类别用类别查询工具；改其他字段用单条更新工具。写操作；id 与新类别 ID 必填。返回变更结果。',
         inputSchema: z.object({
-            id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            workitem_type_id: z.string().describe('新的需求类别ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            workitem_type_id: z.string().describe('新的需求类别 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -354,10 +357,10 @@ export const storyTools = [
     // 字段配置
     {
         name: 'tapd_get_story_fields_info',
-        description: '获取需求字段信息',
+        description: '查询需求可写字段元信息（类型、是否必填、候选值）。拼创建/更新参数前查字段合法性用。读操作。返回字段定义数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            workitem_type_id: z.string().optional().describe('需求类别ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            workitem_type_id: z.string().optional().describe('需求类别 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -369,9 +372,9 @@ export const storyTools = [
     },
     {
         name: 'tapd_get_story_fields_lable',
-        description: '获取需求字段中英文映射',
+        description: '查询需求字段名中英文映射（英文字段名 → 中文标签）。把返回数据转成人类可读表头时用。读操作。返回映射对象。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -384,10 +387,10 @@ export const storyTools = [
     // 模板
     {
         name: 'tapd_get_story_template_list',
-        description: '获取需求模板列表',
+        description: '查询需求模板列表（按类别 ID 过滤）。取默认模板用默认模板查询工具。读操作；支持分页。返回模板数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            workitem_type_id: z.string().optional().describe('需求类别ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            workitem_type_id: z.string().optional().describe('需求类别 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe('返回数量'),
             page: z.number().optional().describe('页码'),
             fields: z.string().optional().describe('返回字段'),
@@ -402,10 +405,10 @@ export const storyTools = [
     },
     {
         name: 'tapd_get_default_story_template',
-        description: '获取需求默认模板',
+        description: '查询指定类别的默认需求模板。要模板清单用模板列表查询工具。读操作。返回默认模板。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            workitem_type_id: z.string().optional().describe('需求类别ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            workitem_type_id: z.string().optional().describe('需求类别 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -418,10 +421,10 @@ export const storyTools = [
     // 关联关系
     {
         name: 'tapd_get_story_related_bugs',
-        description: '获取需求关联的缺陷',
+        description: '查询某需求已关联的缺陷列表。反向（按缺陷找需求）用缺陷侧关联查询工具；建立/解除关联用关联建立/解除工具。读操作；story_id 必填。返回关联缺陷数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe('返回数量'),
             page: z.number().optional().describe('页码'),
             fields: z.string().optional().describe('返回字段'),
@@ -441,11 +444,11 @@ export const storyTools = [
     },
     {
         name: 'tapd_create_story_bug',
-        description: '创建需求缺陷关联',
+        description: '建立需求与缺陷的关联。查询已有关联用需求侧关联缺陷查询工具；解除用关联解除工具。写操作；story_id、bug_id 必填。返回关联结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            bug_id: z.string().describe('缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            bug_id: z.string().describe('缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -463,11 +466,11 @@ export const storyTools = [
     },
     {
         name: 'tapd_remove_story_bug_relations',
-        description: '解除需求缺陷关联',
+        description: '解除需求与缺陷的关联。建立关联用关联建立工具。写操作；story_id、bug_id 必填。返回解除结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            bug_id: z.string().describe('缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            bug_id: z.string().describe('缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -485,11 +488,11 @@ export const storyTools = [
     },
     {
         name: 'tapd_get_story_tcase',
-        description: '获取需求测试用例关联',
+        description: '查询需求已关联的测试用例。建立关联用关联建立工具；反向（按用例找需求）用用例侧反查工具。读操作；story_id 必填。返回关联用例数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            tcase_id: z.string().optional().describe('测试用例ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            tcase_id: z.string().optional().describe('测试用例 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe('返回数量'),
             page: z.number().optional().describe('页码'),
             fields: z.string().optional().describe('返回字段'),
@@ -509,11 +512,11 @@ export const storyTools = [
     },
     {
         name: 'tapd_create_story_tcase',
-        description: '创建需求测试用例关联',
+        description: '建立需求与测试用例的关联。查询用需求侧关联用例查询工具；解除用用例侧解除工具。写操作；story_id、tcase_id 必填。返回关联结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            tcase_id: z.string().describe('测试用例ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            tcase_id: z.string().describe('测试用例 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -531,12 +534,12 @@ export const storyTools = [
     // 前后置关系
     {
         name: 'tapd_get_time_relative_stories',
-        description: '获取需求前后置关系',
+        description: '查询需求前后置（依赖）关系。维护关系用关系保存/删除工具。读操作；story_id、前置 ID、后置 ID 至少给一个。返回关系数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            story_id: z.string().optional().describe('需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            predecessor_id: z.string().optional().describe('前置需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            successor_id: z.string().optional().describe('后置需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            story_id: z.string().optional().describe('需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            predecessor_id: z.string().optional().describe('前置需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            successor_id: z.string().optional().describe('后置需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             relation_type: z.string().optional().describe('关系类型'),
             limit: z.number().optional().describe('返回数量'),
             page: z.number().optional().describe('页码'),
@@ -559,10 +562,10 @@ export const storyTools = [
     },
     {
         name: 'tapd_save_time_relations',
-        description: '批量新增/修改前后置关系',
+        description: '批量新增或修改需求前后置关系（同 ID 覆盖为修改）。查询用关系查询工具；删除用关系删除工具。写操作；relations 传 JSON 数组字符串。返回保存结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            relations: z.string().describe('前后置关系数组JSON (必填)'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            relations: z.string().describe('前后置关系数组JSON（必填）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -574,10 +577,10 @@ export const storyTools = [
     },
     {
         name: 'tapd_delete_time_relations',
-        description: '批量删除前后置关系',
+        description: '批量删除需求前后置关系。新增/修改用关系保存工具。写操作；relations 传 JSON 数组字符串。返回删除结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            relations: z.string().describe('要删除的前后置关系数组JSON (必填)'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            relations: z.string().describe('要删除的前后置关系数组JSON（必填）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -590,10 +593,10 @@ export const storyTools = [
     // 其他
     {
         name: 'tapd_get_removed_stories',
-        description: '获取回收站的需求',
+        description: '查询回收站中的需求（可按删除时间、处理人过滤）。存续需求用列表查询工具。读操作；支持分页。返回已删除需求数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('需求ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('需求 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe('标题'),
             owner: z.string().optional().describe('处理人'),
             creator: z.string().optional().describe('创建人'),
@@ -614,11 +617,11 @@ export const storyTools = [
     },
     {
         name: 'tapd_update_story_parent',
-        description: '更新父需求',
+        description: '设置或取消需求的父子层级（父需求 ID 传 "0" 取消父子关系）。一般字段更新用单条更新工具。写操作；id、parent_id 必填。返回更新结果。',
         inputSchema: z.object({
-            id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            parent_id: z.string().describe('新的父需求ID (必填)，设为0取消父子关系；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            parent_id: z.string().describe('新的父需求 ID（必填），设为 0 取消父子关系；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -637,10 +640,10 @@ export const storyTools = [
     },
     {
         name: 'tapd_get_stories_by_view_conf_id',
-        description: '获取视图需求列表',
+        description: '按视图配置 ID 查询该视图下的需求列表（复用网页端保存的视图条件）。自定义条件查询用列表查询工具。读操作；view_conf_id 必填。返回需求列表。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            view_conf_id: z.string().describe('视图配置ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            view_conf_id: z.string().describe('视图配置 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe('返回数量'),
             page: z.number().optional().describe('页码'),
             fields: z.string().optional().describe('返回字段'),
@@ -655,10 +658,10 @@ export const storyTools = [
     },
     {
         name: 'tapd_get_story_steps',
-        description: '获取需求节点信息',
+        description: '查询需求步骤（验收/拆解节点）信息。读操作；story_id 必填。返回步骤数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe('返回数量'),
             page: z.number().optional().describe('页码'),
             fields: z.string().optional().describe('返回字段'),