feat: enhance work item management with new detail retrieval and readability features

- Introduced `get_task_detail` method to fetch complete details of a work item, including user-friendly field names.
- Removed the deprecated `filter_tasks` method, consolidating functionality into `get_tasks`.
- Enhanced `get_tasks` to support improved readability features, automatically converting user-related fields to names.
- Updated documentation to reflect changes in API methods and added examples for new features.
- Implemented caching mechanisms for user and work item data to optimize performance and reduce API calls.

Author: Wulnut

AGENTS.md

@@ -72,6 +72,7 @@ src/
 - **架构设计**：考虑代码的可维护性、可扩展性和性能需求
 - **版本控制**：编写有意义的提交信息，保持逻辑相关的更改在同一提交中
 - **异常处理**：正确处理边缘情况和错误，提供有用的错误信息
+- **实际调用原则**：如果涉及api调用接口开发可以在scripts目录中实现简单测试脚本，确保接口调用正确
 
 ---
 

README.md

@@ -21,9 +21,10 @@
 
 | 工具名 | 功能描述 | 示例用法 |
 |--------|---------|---------|
+| `list_projects` | 列出所有可用项目 | "有哪些可用的飞书项目？" |
 | `create_task` | 创建新的工作项 | "帮我创建一个 P0 优先级的 Bug：登录页面崩溃" |
-| `get_active_tasks` | 获取活跃的工作项（未完成状态） | "查看当前有哪些进行中的任务" |
-| `filter_tasks` | 高级过滤查询 | "找出所有张三负责的 P0 任务" |
+| `get_tasks` | 获取工作项列表（支持过滤） | "查看当前有哪些进行中的任务" |
+| `get_task_detail` | 获取单个工作项完整详情 | "查看任务 12345 的详细信息" |
 | `update_task` | 更新工作项 | "把任务 12345 的状态改为已完成" |
 | `get_task_options` | 获取字段可用选项 | "状态字段有哪些可选值？" |
 
@@ -33,8 +34,9 @@
 
 ```
 参数:
-  - project_key: 项目空间 Key (必填)
   - name: 工作项标题 (必填)
+  - project: 项目标识符（可选，支持项目名称或 project_key）
+  - work_item_type: 工作项类型（可选），如 "需求管理"、"Issue管理"
   - priority: 优先级，可选 P0/P1/P2/P3，默认 P2
   - description: 描述
   - assignee: 负责人（姓名或邮箱）
@@ -44,55 +46,63 @@
 
 **使用示例：**
 ```
-用户: 帮我在 project_xxx 创建一个任务"修复首页加载慢的问题"，优先级 P1，指派给张三
-AI: 调用 create_task(project_key="project_xxx", name="修复首页加载慢的问题", priority="P1", assignee="张三")
+用户: 帮我创建一个任务"修复首页加载慢的问题"，优先级 P1，指派给张三
+AI: 调用 create_task(name="修复首页加载慢的问题", priority="P1", assignee="张三")
 ```
 
-#### 2. get_active_tasks - 获取活跃任务
+#### 2. get_tasks - 获取工作项列表
 
 ```
 参数:
-  - project_key: 项目空间 Key (必填)
-  - page_size: 返回数量，默认 20，最大 100
+  - project: 项目标识符（可选）
+  - work_item_type: 工作项类型（可选）
+  - name_keyword: 名称关键词搜索（推荐）
+  - status: 状态过滤，多个用逗号分隔，如 "待处理,进行中"
+  - priority: 优先级过滤，多个用逗号分隔，如 "P0,P1"
+  - owner: 负责人过滤（姓名或邮箱）
+  - related_to: 关联工作项 ID 或名称
+  - page_num: 页码，从 1 开始
+  - page_size: 每页数量，默认 50
 
 返回: JSON 格式的工作项列表
 ```
 
 **使用示例：**
 ```
-用户: 看看 project_xxx 里有哪些正在进行的任务
-AI: 调用 get_active_tasks(project_key="project_xxx")
+用户: 找出所有 P0 优先级的待处理任务
+AI: 调用 get_tasks(status="待处理", priority="P0")
+
+用户: 李四负责的进行中任务有哪些
+AI: 调用 get_tasks(status="进行中", owner="李四")
+
+用户: 搜索包含 "登录" 关键词的任务
+AI: 调用 get_tasks(name_keyword="登录")
 ```
 
-#### 3. filter_tasks - 高级过滤查询
+#### 3. get_task_detail - 获取工作项详情
 
 ```
 参数:
-  - project_key: 项目空间 Key (必填)
-  - status: 状态过滤，多个用逗号分隔，如 "待处理,进行中"
-  - priority: 优先级过滤，多个用逗号分隔，如 "P0,P1"
-  - owner: 负责人过滤（姓名或邮箱）
-  - page_num: 页码，从 1 开始
-  - page_size: 每页数量，默认 20
+  - issue_id: 工作项 ID (必填)
+  - project: 项目标识符（可选）
+  - work_item_type: 工作项类型（可选）
 
-返回: JSON 格式的过滤结果
+返回: JSON 格式的完整工作项详情
 ```
 
 **使用示例：**
 ```
-用户: 找出所有 P0 优先级的待处理任务
-AI: 调用 filter_tasks(project_key="project_xxx", status="待处理", priority="P0")
-
-用户: 李四负责的进行中任务有哪些
-AI: 调用 filter_tasks(project_key="project_xxx", status="进行中", owner="李四")
+用户: 查看任务 12345 的详细信息
+AI: 调用 get_task_detail(issue_id=12345)
 ```
 
 #### 4. update_task - 更新工作项
 
 ```
 参数:
-  - project_key: 项目空间 Key (必填)
   - issue_id: 工作项 ID (必填)
+  - project: 项目标识符（可选）
+  - work_item_type: 工作项类型（可选）
   - name: 新标题
   - priority: 新优先级
   - description: 新描述
@@ -105,29 +115,55 @@ AI: 调用 filter_tasks(project_key="project_xxx", status="进行中", owner="
 **使用示例：**
 ```
 用户: 把任务 12345 的状态改为已完成
-AI: 调用 update_task(project_key="project_xxx", issue_id=12345, status="已完成")
+AI: 调用 update_task(issue_id=12345, status="已完成")
 
 用户: 把任务 12345 的优先级提升到 P0，并转给王五
-AI: 调用 update_task(project_key="project_xxx", issue_id=12345, priority="P0", assignee="王五")
+AI: 调用 update_task(issue_id=12345, priority="P0", assignee="王五")
 ```
 
 #### 5. get_task_options - 获取字段可用选项
 
 ```
 参数:
-  - project_key: 项目空间 Key (必填)
-  - field_name: 字段名称，如 "status", "priority"
+  - field_name: 字段名称，如 "status", "priority" (必填)
+  - project: 项目标识符（可选）
+  - work_item_type: 工作项类型（可选）
 
 返回: JSON 格式的选项列表
 ```
 
 **使用示例：**
 ```
 用户: 状态字段有哪些可选值
-AI: 调用 get_task_options(project_key="project_xxx", field_name="status")
-返回: {"field": "status", "options": {"待处理": "opt_1", "进行中": "opt_2", "已完成": "opt_3"}}
+AI: 调用 get_task_options(field_name="status")
+ 返回: {"field": "status", "options": {"待处理": "opt_1", "进行中": "opt_2", "已完成": "opt_3"}}
 ```
 
+### ✨ 可读性特性
+
+为了提升用户体验，本系统对工作项数据进行了智能可读性转换：
+
+1. **`get_tasks` 列表视图**：
+   - 自动提取负责人、状态、优先级等关键字段的可读标签
+   - 用户相关字段（负责人）显示为人名而非内部 ID
+   - 返回简化格式，节省 Token 消耗
+
+2. **`get_task_detail` 详情视图**：
+   - 返回完整的工作项详情，包含所有字段
+   - 自动转换用户字段为人名（负责人、创建者、更新者等）
+   - 在 `readable_fields` 字段中提供所有字段的可读版本
+   - 为常用字段提供顶级别名（`readable_owner`, `readable_creator` 等）
+
+3. **智能字段解析**：
+   - 自动处理多种字段格式（列表、字典、选项等）
+   - 支持复杂字段值的可读提取
+   - 保持原始数据完整，仅添加可读增强
+
+**示例对比**：
+- 原始数据：`"owner": [{"name": "张三", "user_key": "u_123"}]`
+- 可读版本：`"owner": "张三"` (在 `get_tasks` 中)
+- 增强详情：包含原始数据和 `"readable_owner": "张三"` (在 `get_task_detail` 中)
+
 ## 🚀 快速开始
 
 ### 方式一：通过 uv tool install（推荐，最简单）