| list_projectsA | 列出所有可用的飞书项目空间。
当你不知道项目的 project_key 时，先调用此工具获取项目列表。
返回的列表包含项目名称和对应的 project_key。
Args:
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
JSON 格式的项目列表，格式为 {project_name: project_key}。
失败时返回错误信息。
Examples:
# 查看有哪些项目可用
list_projects()
|
| create_taskA | 在指定项目中创建新的工作项（任务/Issue）。
这是创建飞书项目工作项的主要工具。系统会自动处理字段值的转换
（如将 "P0" 转换为对应的选项 Key）。
Args:
name: 工作项标题，必填。
project: 项目标识符（可选）。可以是:
- 项目名称（如 "SR6D2VA-7552-Lark"）
- project_key（如 "project_xxx"）
如不指定，则使用环境变量 FEISHU_PROJECT_KEY 配置的默认项目。
work_item_type: 工作项类型名称（可选），如 "需求管理"、"Issue管理"、"项目管理" 等名。
如不指定，默认使用项目中的第一个可用类型。
priority: 优先级，可选值: P0(最高), P1, P2(默认), P3(最低)。
description: 工作项描述，支持纯文本。
assignee: 负责人的姓名或邮箱。如不指定则为空。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
成功时返回 "创建成功，Issue ID: xxx"。
失败时返回错误信息。
Examples:
# 使用默认项目创建任务
create_task(name="修复登录页面崩溃问题", priority="P0")
# 指定项目和工作项类型创建任务
create_task(
project="SR6D2VA-7552-Lark",
work_item_type="Issue管理",
name="修复登录页面崩溃问题",
priority="P0",
assignee="张三"
)
|
| get_tasksA | 获取项目中的工作项列表（支持全量获取或按条件过滤）。
这是通用的任务获取工具，具备以下特性：
1. 无过滤参数时，返回项目的全部工作项
2. 支持按任务名称关键词进行高效搜索（推荐）
3. 支持按状态、优先级、负责人进行灵活过滤
4. 支持按关联工作项 ID 或名称过滤（查找与指定工作项关联的项）
5. 如果项目不存在某个字段（如状态），会自动跳过该过滤条件
6. 支持指定工作项类型（如 "需求管理"、"Issue管理"、"项目管理" 等）
Args:
project: 项目标识符（可选）。可以是:
- 项目名称（如 "Project Management"）
- project_key（如 "project_xxx"）
如不指定，则使用环境变量 FEISHU_PROJECT_KEY 配置的默认项目。
work_item_type: 工作项类型名称（可选），如 "需求管理"、"Issue管理"、"项目管理" 等。
如果不指定，默认使用 "问题管理" 类型。
name_keyword: 任务名称关键词（可选，支持模糊搜索，推荐使用）。
例如："SG06VA" 可以搜索所有包含该关键词的任务。
status: 状态过滤（多个用逗号分隔），如 "待处理,进行中"（可选）。
priority: 优先级过滤（多个用逗号分隔），如 "P0,P1"（可选）。
owner: 负责人过滤（姓名或邮箱）（可选）。
related_to: 关联工作项 ID 或名称（可选）。用于查找与指定工作项关联的其他工作项。
- 如果是整数或数字字符串，直接作为工作项 ID 使用
- 如果是非数字字符串，自动搜索该名称对应的工作项（精确匹配优先）
例如：related_to="SG06VA1" 或 related_to=6288163810
page_num: 页码，从 1 开始（默认 1）。
page_size: 每页数量（默认 50，最大 100）。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
JSON 格式的工作项列表，包含 id, name, status, priority, owner。
失败时返回错误信息。
Examples:
# 获取默认项目的全部工作项
get_tasks()
# 获取"需求管理"类型的工作项
get_tasks(project="Project Management", work_item_type="需求管理")
# 按名称关键词搜索（推荐，高效）
get_tasks(name_keyword="SG06VA")
# 获取指定优先级的任务
get_tasks(priority="P0,P1")
# 查找与指定工作项关联的工作项（通过名称）
get_tasks(related_to="SG06VA1", work_item_type="Issue管理")
# 查找与指定工作项关联的工作项（通过 ID）
get_tasks(
project="Project Management",
work_item_type="需求管理",
related_to=6181818812
)
# 指定项目并组合多个条件过滤
get_tasks(
project="Project Management",
work_item_type="需求管理",
name_keyword="SG06VA",
status="进行中",
priority="P0"
)
|
| add_task_commentA | 为指定工作项添加一条评论（纯文本）。
适用场景:
- 需要在工作项下沉淀沟通结论、会议纪要、处理记录
- 希望 Agent 在更新字段之外留下“可审计的文字说明”
Args:
issue_id: 工作项 ID，必填。
content: 评论内容（纯文本），必填。内容为空会报错。
project: 项目标识符（可选）。可以是项目名称或 project_key。
不传则使用环境变量默认项目。
work_item_type: 工作项类型名称（可选）。不传则使用默认类型。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
JSON 字符串。
- success=true 时，data 至少包含 comment_id。
- 失败时返回纯文本错误信息（由 with_error_handling 统一处理）。
Examples:
add_task_comment(issue_id=123, content="已与研发确认：本周五前完成联调")
|
| list_task_commentsA | 获取指定工作项下的评论列表。
Args:
issue_id: 工作项 ID。
page_num: 页码，从 1 开始（默认 1）。
page_size: 每页数量（默认 20，最大值由服务端限制）。
project: 项目标识符（可选）。可以是项目名称或 project_key；不传则使用环境变量 FEISHU_PROJECT_KEY 指定的默认项目。
work_item_type: 工作项类型名称（可选）。不传则使用默认类型。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)。
Returns:
JSON 字符串。
data 格式:
{
"total": int,
"page_num": int,
"page_size": int,
"items": [
{
"comment_id": str|int,
"author": Any,
"create_time": Any,
"content": str
}
]
}
Examples:
list_task_comments(issue_id=123, page_num=1, page_size=20)
|
| update_task_commentA | 更新指定评论内容（纯文本）。
Args:
issue_id: 工作项 ID。
comment_id: 评论 ID。
content: 新的评论内容（纯文本）。
project: 项目标识符（可选）。可以是项目名称或 project_key；不传则使用环境变量 FEISHU_PROJECT_KEY 指定的默认项目。
work_item_type: 工作项类型名称（可选）。不传则使用默认类型。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)。
Returns:
JSON 字符串。
成功时（success=true）data 格式:
{
"issue_id": int,
"comment_id": str
}
失败时返回纯文本错误信息（由 with_error_handling 统一处理），常见原因包括：
- comment_id 不存在
- 当前用户无权限编辑该评论
- 评论内容为空
Examples:
update_task_comment(issue_id=123, comment_id="c1", content="补充：已完成回归测试")
|
| delete_task_commentA | 删除指定评论。
Args:
issue_id: 工作项 ID。
comment_id: 评论 ID。
project: 项目标识符（可选）。可以是项目名称或 project_key；不传则使用环境变量 FEISHU_PROJECT_KEY 指定的默认项目。
work_item_type: 工作项类型名称（可选）。不传则使用默认类型。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)。
Returns:
JSON 字符串。
成功时（success=true）data 格式:
{
"issue_id": int,
"comment_id": str
}
失败时返回纯文本错误信息（由 with_error_handling 统一处理），常见原因包括：
- comment_id 不存在
- 当前用户无权限删除该评论
Examples:
delete_task_comment(issue_id=123, comment_id="c1")
|
| get_task_transition_requirementsA | 获取将指定工作项流转到目标状态前的必填信息要求。 该工具用于在执行状态流转前，先询问系统：从当前状态流转到 target_status 需要补全哪些字段。
常见场景包括：
- 流转到“已完成/已关闭”时需要填写“解决方案”“原因”“验证人”等字段
- 流转到某些阶段需要指定角色负责人（role owners）或填写额外信息
本工具仅负责：
1) project/work_item_type 参数解析（project_name 与 project_key 分支）
2) 委托 WorkflowProvider 解析状态名并调用 WorkflowAPI.get_transition_required_info
3) 返回统一的 JSON envelope（success/data），便于 LLM 稳定解析
注意：
- 成功时返回 JSON 字符串（success=true）。
- 失败时返回纯文本错误信息（由 with_error_handling 统一处理），不会返回 JSON。
Args:
issue_id: 工作项 ID，必填。
target_status: 目标状态名称（人类可读），必填。例如："已完成"、"待处理"。
project: 项目标识符（可选）。可以是项目名称或 project_key；不传则使用环境变量 FEISHU_PROJECT_KEY 指定的默认项目。
work_item_type: 工作项类型名称（可选）。例如："问题管理"、"Issue管理"。
mode: 工作流查询模式（可选）。透传给后端接口，用于控制必填项返回策略。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
JSON 字符串。
成功时（success=true）data 格式至少包含：
{
"required_fields": [ ... ]
}
失败时返回纯文本错误信息（由 with_error_handling 统一处理），常见原因包括：
- target_status 无法匹配（会提示“可选状态”）
- 当前用户无权限查询该工作项的工作流信息
- 网络/系统异常
Examples:
# 查询将 Issue 123 流转到“已完成”前需要填哪些字段
get_task_transition_requirements(issue_id=123, target_status="已完成")
|
| transition_task_statusA | 将指定工作项流转到目标状态。 该工具用于执行飞书项目工作项的状态流转（Workflow Transition）。
它会根据 target_status（人类可读的状态名称）自动解析出对应的 state_key / transition_id，
并调用后端的 workflow state_change 接口完成流转。
使用建议：
- 在调用本工具前，建议先调用 get_task_transition_requirements 获取必填字段要求。
- fields 参数当前仅支持 list[dict] 透传（最小实现），用于满足流转前的必填字段。
例如：[{"field_key": "field_x", "field_value": "y"}]。
注意：
- 成功时返回 JSON 字符串（success=true）。
- 失败时返回纯文本错误信息（由 with_error_handling 统一处理），不会返回 JSON。
Args:
issue_id: 工作项 ID，必填。
target_status: 目标状态名称（人类可读），必填。
fields: 流转时需要提交的字段列表（可选）。元素为 dict，直接透传给后端。
project: 项目标识符（可选）。可以是项目名称或 project_key；不传则使用环境变量默认项目。
work_item_type: 工作项类型名称（可选）。
mode: 流转模式（可选）。当前仅透传给 Provider，预留未来扩展。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)。
Returns:
JSON 字符串。
成功时（success=true）data 格式至少包含：
{
"issue_id": int,
"target_status": str
}
失败时返回纯文本错误信息（由 with_error_handling 统一处理），常见原因包括：
- target_status 无法匹配（会提示“可选状态”）
- 流转失败（后端返回权限/参数错误等）
Examples:
# 直接流转（无额外字段）
transition_task_status(issue_id=123, target_status="已完成")
# 带必填字段流转
transition_task_status(
issue_id=123,
target_status="已完成",
fields=[{"field_key": "field_resolution", "field_value": "已修复"}],
)
|
| list_child_tasksA | 列出指定父工作项下的子任务（通过“空间关联关系”规则实现）。 背景说明：
- 飞书项目中的“父子/子任务”通常不是一个固定字段，而是通过“关联关系规则（Relation Rule）”实现。
- 同一个项目空间可能存在多条关联规则（例如："子任务"、"关联"、"阻塞"）。
因此本工具支持 relation_name 参数用于选择具体规则。
本工具的行为：
1) 解析 project / work_item_type 参数（支持 project_name 与 project_key 两种输入）。
2) 通过 HierarchyProvider 选择关联规则：
- 若 relation_name 传入：按名称精确匹配。
- 若未传：若规则只有 1 条则自动选择；若 >1 条则报错提示需要指定。
3) 调用 RelationAPI.work_item_list 获取关联的 work_item_ids。
注意：
- 成功时返回 JSON 字符串（success=true）。
- 失败时返回纯文本错误信息（由 with_error_handling 统一处理），不会返回 JSON。
Args:
parent_issue_id: 父工作项 ID（必填）。
relation_name: 关联规则名称（可选）。规则多于 1 条时建议必填。
page_num: 页码，从 1 开始（默认 1）。
page_size: 每页数量（默认 20）。
project: 项目标识符（可选）。可以是项目名称或 project_key；不传则使用环境变量 FEISHU_PROJECT_KEY 指定的默认项目。
work_item_type: 工作项类型名称（可选）。例如："问题管理"、"Issue管理"。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)。
Returns:
JSON 字符串。
成功时（success=true）data 格式：
{
"work_item_ids": [int, ...]
}
Examples:
# 获取父任务 123 的子任务列表（自动选择唯一规则）
list_child_tasks(parent_issue_id=123)
# 指定关联规则名称
list_child_tasks(parent_issue_id=123, relation_name="子任务")
|
| bind_child_tasksB | 将多个工作项绑定为指定父工作项的“子任务”（通过关联关系规则实现）。 Args:
parent_issue_id: 父工作项 ID（必填）。
child_issue_ids: 子工作项 ID 列表（必填）。
relation_name: 关联规则名称（可选）。当存在多条规则时建议必填。
project: 项目标识符（可选）。可以是项目名称或 project_key；不传则使用默认项目。
work_item_type: 工作项类型名称（可选）。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)。
Returns:
JSON 字符串。
成功时（success=true）data 格式：
{
"parent_issue_id": int,
"child_issue_ids": [int, ...],
"relation_name": str
}
失败时返回纯文本错误信息（由 with_error_handling 统一处理）。
|
| unbind_child_tasksA | 解绑指定父工作项的子任务关系（按关联关系规则整体解绑）。 当前最小实现：
- 调用 RelationAPI.delete 删除父工作项在该规则下的关联关系（服务端语义通常为“清空该规则下的绑定”）。
Args:
parent_issue_id: 父工作项 ID（必填）。
relation_name: 关联规则名称（可选）。
project: 项目标识符（可选）。
work_item_type: 工作项类型名称（可选）。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)。
Returns:
JSON 字符串。
成功时（success=true）data 格式：
{
"parent_issue_id": int,
"relation_name": str
}
失败时返回纯文本错误信息（由 with_error_handling 统一处理）。
|
| get_task_detailA | 获取单个工作项的完整详情。
当你需要查看工作项的所有字段信息时使用此工具。
返回的详情包含所有可用字段（包括自定义字段）。
用户相关字段（如负责人、创建者等）会自动转换为人名以提高可读性。
Args:
issue_id: 工作项 ID，必填。
project: 项目标识符（可选）。可以是:
- 项目名称（如 "SR6D2VA-7552-Lark"）
- project_key（如 "project_xxx"）
如不指定，则使用环境变量 FEISHU_PROJECT_KEY 配置的默认项目。
work_item_type: 工作项类型名称（可选），如 "需求管理"、"Issue管理"、"项目管理" 等。
如不指定，默认使用项目中的第一个可用类型。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
JSON 格式的完整工作项详情。
失败时返回错误信息。
Examples:
# 获取工作项详情（使用默认项目）
get_task_detail(issue_id=12345)
# 指定项目和工作项类型
get_task_detail(
issue_id=12345,
project="SR6D2VA-7552-Lark",
work_item_type="Issue管理"
)
|
| update_taskA | 更新工作项的字段。
可以同时更新多个字段，这些字段可以通过 fields_json 一次性传入。
Args:
issue_id: 要更新的工作项 ID。
project: 项目标识符（可选）。
work_item_type: 工作项类型名称（可选）。
name: 新标题（可选）。
priority: 新优先级（可选）。
description: 新描述（可选）。
status: 新状态（可选）。
assignee: 新负责人（可选）。
field_name: 单个自定义字段名称（可选）。
field_value: 单个自定义字段值（可选）。
fields_json: JSON 格式的字段字典（可选），用于批量更新多个自定义字段。
例如: '{"Soc Vendor": "Amlogic", "DDR 大小": "128MB"}'
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
成功时返回 "更新成功"。
|
| batch_update_tasksA | 批量更新工作项字段（支持单个或多个工作项）。 Args:
issue_ids: 要更新的工作项 ID 列表。
issue_id: 单个工作项 ID（与 issue_ids 二选一，方便单项操作）。
project: 项目标识符（名称或 Key）。
work_item_type: 工作项类型名称。
name: 新标题。
priority: 新优先级（如 P0, P1, P2）。
description: 新描述。
status: 新状态。
assignee: 新负责人（姓名或邮箱）。
field_name: 自定义字段名称，需配合 field_value 使用。
field_value: 自定义字段值。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
JSON 格式结果，包含 success 状态和后台任务 ID 列表。
|
| get_task_optionsA | 获取字段的可用选项列表。
当你不确定某个字段有哪些可选值时，使用此工具查询。
这对于了解状态流转、优先级选项等非常有用。
Args:
field_name: 字段名称，如 "status", "priority"。
project: 项目标识符（可选）。可以是项目名称或 project_key。
如不指定，则使用环境变量 FEISHU_PROJECT_KEY 配置的默认项目。
work_item_type: 工作项类型名称（可选），如 "需求管理"、"Issue管理"、"项目管理" 等。
如不指定，默认使用项目中的第一个可用类型。
user_key: (可选) 飞书用户标识符 (X-USER-KEY)，用于以特定用户身份进行操作。
Returns:
JSON 格式的选项列表，格式为 {label: value}。
失败时返回错误信息。
Examples:
# 查看状态字段有哪些可选值（使用默认项目）
get_task_options(field_name="status")
# 查看优先级字段有哪些可选值
get_task_options(field_name="priority")
# 指定工作项类型查看选项
get_task_options(field_name="status", project="Project Management", work_item_type="需求管理")
|
