飞书项目OpenAPI技能

飞书项目Open API技能，查询/创建/更新/删除工作项，管理流程模板、节点配置、自定义字段、视图和角色权限，批量分析商机进度与风险。触发：查商机、分析进度、管理工作项模板、批量更新任务、流程配置。

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

---

⚡ 能力总览

能力分类	支持操作
工作项管理	查询、创建、更新、删除、终止/恢复
流程与节点	流转节点、更新节点负责人、获取工作流详情
子任务	创建、更新、完成、删除子任务
模板管理	获取/新增/更新/删除流程模板，配置节点规则
自定义字段	创建、更新、删除字段，管理字段选项
工作项类型	获取类型配置、更新类型基础信息
视图管理	创建/更新/删除固定视图、条件视图、全景视图
角色配置	获取流程角色与人员配置
评论管理	添加/查询/更新/删除工作项评论
工时管理	登记/更新/删除工时记录
进度分析	批量查询工作项，分析停滞风险，生成报告

---

🔑 快速开始

工具调用格式

text

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

---

📋 工作项管理

查询单个工作项详情

text

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

批量筛选工作项

text

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

创建工作项

text

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

更新工作项

text

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

删除工作项

text

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

终止/恢复工作项

text

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

---

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

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

text

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

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

text

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

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

新增流程模板

text

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

更新流程模板

text

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

删除流程模板

text

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

---

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

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

text

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

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

text

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: "字段说明"
}

更新自定义字段配置

text

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

工作项类型基础信息更新

text

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

---

📊 视图管理（重点能力）

获取视图列表

text

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

创建固定视图

text

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

创建条件视图

text

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"] }]
}

更新条件视图

text

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

删除视图

text

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

---

🔁 节点与流转管理

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

text

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

获取 WBS 工作流详情

text

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

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

text

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: 新值 }
}

节点完成/回滚

text

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

状态流转

text

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

---

🧒 子任务管理

创建子任务

text

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

更新子任务

text

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

子任务完成/回滚

text

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

---

💬 评论管理

添加评论

text

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

查询评论

text

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

---

⏱️ 工时管理

添加工时记录

text

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" }

查询工时记录

text

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

---

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

第1步：获取全量工作项

text

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

第2步：提取关键字段

text

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

第3步：进度分组统计

text

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

第4步：风险识别

text

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

第5步：生成分析报告

text

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

---

🔗 工作项关联关系管理

获取空间下所有关联关系

text

GET /open_api/{project_key}/work_item/relation

新增关联关系

text

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

绑定/解绑关联工作项

text

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}

---

🚨 常见错误处理

错误码	含义	解决
20039	缺少 X-USER-KEY	确认 user_key 正确配置
230001	项目不存在	检查 project_key
230002	参数错误	检查请求 body 格式
230003	类型不存在	检查 work_item_type_key
has_more=true	还有数据	用 next_cursor 翻页

---

📁 已知项目配置

项目	project_key	商机type_key	备注
LSOP（小鹏P7+）	wrza2p	67da250a6f31f4ecc390a619	商机工作项

---

📝 分析报告模板

markdown

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

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