feishu-project-api（feishu project API 文档）

飞书项目 Open API 技能

适用场景：工作项全生命周期管理、流程模板配置、自定义字段管理、视图管理、商机进度与风险分析、批量任务操作。 核心价值：无需手动操作，自动化完成项目管理工作，输出结构化分析报告。

⚡ 能力总览

🔑 快速开始

工具调用格式

feishu_project_api({
  method: "POST",
  path: "/work_item/{type_key}/filter",
  body: { work_item_type_keys: ["xxx"], page_size: 50 }
})

必知概念

• {project_key} — 项目唯一标识，从 URL 中提取（如 wrza2p）
• {work_item_type_key} — 工作项类型 ID（如商机 67da250a6f31f4ecc390a619）
• {work_item_id} — 具体工作项实例 ID（如 5982710249）
• {template_id} — 流程模板 ID

📋 工作项管理

查询单个工作项详情

POST /open_api/{project_key}/work_item/{work_item_type_key}/query
body: { work_item_ids: [工作项ID] }

批量筛选工作项

POST /open_api/{project_key}/work_item/filter
body: {
  work_item_type_keys: ["type_key1", "type_key2"],
  page_size: 50
}

创建工作项

POST /open_api/{project_key}/work_item/create
body: {
  work_item_type: "type_key",
  fields: { title: "工作项标题", assignee: { user_key: "负责人user_key" } }
}

更新工作项

PUT /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}
body: { fields: { 字段key: 新值 } }

删除工作项

DELETE /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}

终止/恢复工作项

PUT /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/abort

🔧 流程模板管理（重点能力）

获取工作项下的所有流程模板

GET /open_api/{project_key}/template_list/{work_item_type_key}

获取单个流程模板的详细配置

GET /open_api/{project_key}/template_detail/{template_id}

返回节点信息配置、节点流转配置（角色负责人、节点条件等）

新增流程模板

POST /open_api/template/v2/create_template
body: {
  project_key: "wrza2p",
  work_item_type_key: "67da250a6f31f4ecc390a619",
  name: "新流程模板名称",
  description: "模板描述",
  // 其他模板配置字段
}

更新流程模板

PUT /open_api/template/v2/update_template
body: {
  template_id: "template_id",
  name: "更新后的模板名称",
  // 需要更新的字段
}

删除流程模板

DELETE /open_api/template/v2/delete_template/{project_key}/{template_id}

🗂️ 自定义字段管理（重点能力）

获取空间或工作项类型下的所有字段

POST /open_api/{project_key}/field/all
body: { work_item_type_key: "type_key" }

在工作项类型下创建自定义字段

POST /open_api/{project_key}/field/{work_item_type_key}/create
body: {
  field_name: "字段名称",
  field_type: "text",  // text/number/date/user/select 等
  required: false,
  description: "字段说明"
}

更新自定义字段配置

PUT /open_api/{project_key}/field/{work_item_type_key}
body: {
  field_id: "字段ID",
  field_name: "更新后名称",
  // 其他可更新配置
}

工作项类型基础信息更新

PUT /open_api/{project_key}/work_item/type/{work_item_type_key}
body: { name: "类型新名称", description: "类型描述" }

📊 视图管理（重点能力）

获取视图列表

POST /open_api/{project_key}/view_conf/list
body: { page_size: 20 }

创建固定视图

POST /open_api/{project_key}/{work_item_type_key}/fix_view
body: { name: "视图名称", filters: [...] }

创建条件视图

POST /open_api/view/v1/create_condition_view
body: {
  project_key: "wrza2p",
  work_item_type_key: "type_key",
  name: "条件视图名称",
  conditions: [{ field_key: "status", operator: "is", value: ["open"] }]
}

更新条件视图

POST /open_api/view/v1/update_condition_view
body: { view_id: "视图ID", conditions: [...], collaborators: [...] }

删除视图

DELETE /open_api/{project_key}/fix_view/{view_id}

🔁 节点与流转管理

获取工作项工作流详情（含节点信息）

GET /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/workflow/query

获取 WBS 工作流详情

GET /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/wbs_view

更新节点（负责人、排期、表单）

PUT /open_api/{project_key}/workflow/{work_item_type_key}/{work_item_id}/node/{node_id}
body: {
  assignee: { user_key: "user_key" },
  due: "2026-04-30",
  fields: { 字段key: 新值 }
}

节点完成/回滚

POST /open_api/{project_key}/workflow/{work_item_type_key}/{work_item_id}/node/{node_id}/operate
body: { action: "complete" }  // 或 "rollback"

状态流转

POST /open_api/{project_key}/workflow/{work_item_type_key}/{work_item_id}/node/state_change
body: { target_state: "done", fields: {...} }

🧒 子任务管理

创建子任务

POST /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/workflow/task
body: { node_id: "节点ID", title: "子任务标题", assignee: {...} }

更新子任务

POST /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/workflow/{node_id}/task/{task_id}
body: { title: "更新标题", status: "done" }

子任务完成/回滚

POST /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/subtask/modify
body: { task_id: "task_id", action: "complete" }

💬 评论管理

添加评论

POST /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/comment/create
body: { content: "评论内容" }

查询评论

GET /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/comments

⏱️ 工时管理

添加工时记录

POST /open_api/{project_key}/work_item/{work_item_type_key}/{work_item_id}/work_hour_record
body: { hours: 4, date: "2026-04-04", user_key: "user_key" }

查询工时记录

POST /open_api/work_item/man_hour/records
body: { work_item_ids: ["id1", "id2"] }

🔍 进度与风险分析（标准分析流程）

第1步：获取全量工作项

POST /open_api/{project_key}/work_item/filter
body: { work_item_type_keys: ["type_key"], page_size: 100 }

第2步：提取关键字段

返回数据中提取：
- id / name / sub_stage / state_name / progress
- current_owners / fields（字典格式）

第3步：进度分组统计

按 state_name 分组 → 计算各状态占比
识别停滞节点（>30天无更新 → 黄色预警）

第4步：风险识别

单负责人 >5个子项 → 负载风险
停滞 >60天 → 红色预警
100%停滞在同一节点 → 系统性瓶颈

第5步：生成分析报告

输出结构：执行摘要 → 现状 → 风险 → 建议

🔗 工作项关联关系管理

获取空间下所有关联关系

GET /open_api/{project_key}/work_item/relation

新增关联关系

POST /open_api/work_item/relation/create
body: { name: "关系名称", source_type: "type1", target_type: "type2" }

绑定/解绑关联工作项

POST /open_api/{project_key}/relation/{work_item_type_key}/{work_item_id}/batch_bind
DELETE /open_api/{project_key}/relation/{work_item_type_key}/{work_item_id}

🚨 常见错误处理

📁 已知项目配置

📝 分析报告模板

# {项目名} 进度与风险分析报告

## 执行摘要
## 工作项概览
## 进度分析（按状态节点）
## 风险识别
## 负责人负载分析
## 行动建议