飞书项目OpenAPI技能

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

Security Scan

The skill's documented Feishu Project API operations match its name, but the instructions omit how to authenticate or where to send requests (and the skill has no declared source/homepage), creating an unexplained gap you should resolve before use.

Purpose & Capability

The name/description list project management operations (query/create/update/delete work items, templates, views, etc.) and the SKILL.md describes matching OpenAPI endpoints — capability and purpose are consistent. However, the skill provides no base URL or authentication details, which are necessary for any real Feishu Open API calls.

Instruction Scope

The SKILL.md is an instruction-only specification of API paths and request bodies and does not ask for unrelated files or environment data. It does, however, assume the existence of a feishu_project_api(...) call and instructs extracting project_key from URLs; it never explains who/what will perform HTTP requests or how tokens are obtained, leaving runtime behavior unspecified.

Install Mechanism

No install spec and no code files — instruction-only. This minimizes disk-write/installation risk.

Credentials

No required environment variables or primary credential are declared, yet Feishu Open API requires authentication (app/client credentials or access tokens). The absence of declared credentials is an incoherence: the skill either (a) relies on an out-of-band platform connector (not documented), or (b) expects the agent to find credentials elsewhere, which would be inappropriate. This should be clarified.

Persistence & Privilege

The skill is not always-enabled and is user-invocable (defaults). It does not request persistent presence or claim to modify other skills or system-wide settings.

What to consider before installing

This skill appears to be a mapping of Feishu Project API endpoints and could be useful, but it omits how requests are authenticated and where they are sent. Before installing or using it: (1) confirm who provides the Feishu credentials/tokens (the platform, you, or the skill) and avoid granting broad admin tokens; prefer least-privilege tokens scoped to the project; (2) ask the publisher for a homepage or source repository to verify provenance; (3) verify the runtime environment (does the agent platform have a built-in Feishu connector?) and confirm that the skill will not try to read arbitrary local files or other credentials; (4) test in a non-production workspace and audit Feishu logs for unexpected activity; (5) if the skill will perform bulk updates/Deletes, require explicit confirmations and consider role-scoped tokens to limit blast radius.

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

---

⚡ 能力总览

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

---

🔑 快速开始

工具调用格式

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}

---

🚨 常见错误处理

错误码	含义	解决
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	商机工作项

---

📝 分析报告模板

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

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