OneOS1.2/.claude/skills/YunxiaoPM/references/live-api.md

云效实写 API（YunxiaoPMapp 已验证）

verified_at: 2026-07-25 · 项目须门禁 PJ 点选（见 project-selection.md）；历史验证样本项目为 01_ONEOS / 原「统一运营管理平台」（last_selected.spaceIdentifier 见 assets/runtime-ids.json，禁止未点选即使用）。

本文件只记已跑通的写法；禁止再盲试 updateStatus / 错误 updateFieldValue POST。

认证

• Cookie：Chrome 域 .aliyun.com / devops.aliyun.com（browser_cookie3 或 Playwright storage）
• Header：x-xsrf-token = cookie XSRF-TOKEN（URL 解码后）
• Origin / Referer：https://devops.aliyun.com

建单

POST|PUT /projex/api/workitem/workitem?_input_charset=utf-8

创建响应 result.identifier / serialNumber 即编号真相；禁止按标题查重。

改负责人（已通）

PATCH /projex/api/workitem/workitem/{id}?_input_charset=utf-8
{"propertyKey":"assignedTo","propertyValue":"<userId>","operateType":"COVER"}

交棒：【交付】propertyValue = 何斐 ID。

打标签（已通）

PATCH /projex/api/workitem/workitem/{id}?_input_charset=utf-8
{"workitemIdentifier":"{id}","propertyKey":"tag","propertyValue":"<tagId>[,<tagId>]","operateType":"COVER"}

改状态（已通 · 唯一推荐）

POST /projex/api/workitem/workitem/{id}/status/transit?_input_charset=utf-8
{"fromStatus":"<当前status.identifier>","toStatus":"<目标status.identifier>"}

成功：code=200 且 result=true。失败时 errorMsg 含「不能流转」。

需求状态 ID（本项目）

显示名	identifier
待处理	100005
已确认	32
分析中	154395
设计中	156603
设计完成	307012
待开发	1582fc929d429111b925309493

任务状态 ID

显示名	identifier
待处理	100005
已完成	100014

极速交棒跳转（工作流允许）

从「待处理」菜单可见直达「设计完成」；推荐最少跳：

待处理 → 设计完成 → 待开发

标准路径若需看板留痕，可走完整链：已确认→分析中→设计中→设计完成→待开发（仍用本 API，勿开 UI）。

禁止（已证伪）

写法	结果
PATCH …/updateStatus + statusIdentifier	400 不能为空
PATCH …/{id} + propertyKey=status	property not found
Playwright 点左侧/列表上的状态色块（x<1100）	假成功、状态不落库

仅当 status/transit 不可用时，才用 UI：右侧详情状态钮（getBoundingClientRect().x > 1100）+ .next-menu-item。

计划开始/完成 · 提交部门/人 · 预计工时（2026-07-27 修订）

通用字段写入（已通）：

POST /projex/api/workitem/workitem/field/value/{workitemId}?_input_charset=utf-8
Content-Type: application/x-www-form-urlencoded

fieldValueList=[{"fieldIdentifier":"79","value":"2026-07-27 12:00:00"},{"fieldIdentifier":"3132597a9718d1c282b7ba5a0c","value":"业务管理部"},{"fieldIdentifier":"9e01269e96f91fbb97d36bf5b3","value":"何苗苗"}]

字段	fieldIdentifier	value
计划开始	79	YYYY-MM-DD HH:mm:ss（推荐正午）或 epoch ms 字符串
计划完成	80	同上
提交部门	3132597a9718d1c282b7ba5a0c	纯文本
提交人	9e01269e96f91fbb97d36bf5b3	纯文本

预计工时 101586：禁止直接改字段（报「不可直接修改」）。须登记：

POST /projex/api/workitem/workitem/time/estimate?_input_charset=utf-8
{"workitemIdentifier":"<id>","spentTime":8,"type":"develop","description":"阶段日历工时","recordUserIdentifier":"<userId>","forCreate":false,"containsRestDay":false}

删除多余预估：DELETE /projex/api/workitem/workitem/time/estimate/{workitemId}/{estimateId}
列表：GET …/time/estimate/list?workitemIdentifier=

旧写法 PATCH …/updateWorkitemFieldValue 对上述自定义字段常 400 不能为空，勿再优先使用。

父子 / 子项 / 关联项（已通 · 2026-07-23 修订 · 子项优先）

关联项（【交付】强制 · ASSOCIATED）

任务详情「关联项」只认 ASSOCIATED。仅【交付】建单时 createWorkitemRelationInfo 必须指向需求：

{
  "createWorkitemRelationInfo": {
    "relatedWorkitemIdentifier": "<需求id>",
    "relatedToRelationIdentifier": "ASSOCIATED"
  }
}

校验：

GET /projex/api/workitem/v2/workitem/{交付id}/relation/workitem/list/by-relation-category?category=ASSOCIATED&isForward=true

result 含该需求即通过。

禁止（关联项）

写法	结果
relatedToRelationIdentifier=PARENT 把交付挂需求	详情可能有 parent，关联项仍为空
分析/设计只用 ASSOCIATED→需求 + parentIdentifier	关联项可能有，交付子项仍为空（ONEOS-246/247）
建后再 POST …/relation/record 补关系	Cookie 路径下常报「不能关联相同的工作项」
createWorkitemRelationList	不落 ASSOCIATED

子项（【分析】/【设计】强制 · TASK_SUB）

「子项」页读 PARENT_SUB / TASK_SUB，分析/设计必须：

{
  "parent": "<交付id>",
  "parentIdentifier": "<交付id>",
  "createWorkitemRelationInfo": {
    "relatedWorkitemIdentifier": "<交付id>",
    "relatedToRelationIdentifier": "TASK_SUB"
  }
}

同一 create 只能带一条 createWorkitemRelationInfo。
ASSOCIATED→需求 与 TASK_SUB→交付 不能同时写。

产品优先级：交付「子项」tab > 阶段任务「关联项」。
交付本身仍必须 ASSOCIATED→需求。标准路径下分析/设计的「关联项」允许为空。

无单快轨例外（设计双挂）： create 用 TASK_SUB→交付 后，须再补 ASSOCIATED→原始需求，使设计详情「关联项」可见需求。

POST /projex/api/workitem/workitem/{设计id}/relation/record?_input_charset=utf-8
{"relationIdentifier":"ASSOCIATED","toWorkitemIdentifier":"<需求id>"}

已证伪（Cookie · 2026-07-27）： 凡工作项已创建后再 relation/record 补挂（含 ASSOCIATED / TASK_SUB），常报「不能关联相同的工作项」；与是否已有父项无关。createWorkitemRelationList 亦不落 ASSOCIATED。
可行路径：

目标	做法
交付「子项」可见设计（优先）	create 带 TASK_SUB→交付
设计「关联项」可见需求	create 带 ASSOCIATED→需求（与上互斥，同 create 只能一条）
双挂	需个人 x-yunxiao-token OpenAPI；Cookie 路径不得声称成功

产品默认：子项优先；关联项失败须在回报中标红并列出缺项。

校验子项：

GET /projex/api/workitem/v2/workitem/{交付id}/relation/workitem/list/by-relation-category?category=PARENT_SUB&isForward=true

结果须含对应分析/设计 identifier。

校验设计关联项：

GET /projex/api/workitem/v2/workitem/{设计id}/relation/workitem/list/by-relation-category?category=ASSOCIATED&isForward=true

result 须含原始需求 identifier。

无单快轨字段默认（2026-07-27）

对象	规则
【设计】描述	复制需求 document HTML
【设计】79/80	当日 12:00:00 / 23:59:59，create 后 field/value（勿 create 同时带 79+80）
【交付】描述	手工同步需求正文，或原型→AutoPRD；禁止无故占位
【交付】79	创建当日；不写 80
【交付】/【设计】标签	与需求相同，PATCH propertyKey=tag
需求预计工时	time/estimate spentTime=2（先删多余预估）
需求实际工时	POST …/workitem/time，body 用 actualTime（非 spentTime）+ gmtStart/gmtEnd epoch ms 字符串；见 runtime-ids.json fields.actual_hours
描述更新	PATCH …/workitem/{id}/document，{"content":"<html>","formatType":"RICHTEXT"}

迭代挂接（已通 · 2026-07-27 · 只挂交付）

创建迭代：POST /projex/api/workspace/sprint（必填 staffIds；可写 capacityHours）。

挂【交付】到迭代：

PATCH /projex/api/workitem/workitem/{交付id}?_input_charset=utf-8
{"workitemIdentifier":"{交付id}","propertyKey":"sprint","propertyValue":"{sprintId}","operateType":"COVER"}

清空误挂（如需求）：propertyValue:"" + operateType:"COVER"。

校验必须读 /extra（详情主接口常不含 sprint 字段，禁止据此判失败）：

GET /projex/api/workitem/workitem/{id}/extra?_input_charset=utf-8
→ result.sprint[].identifier / name

产品规则：只挂【交付】；需求 / 分析 / 设计默认不挂（除非口令显式）。

极速建单注意

1. Cookie 只刷一次；全程纯 HTTP，默认不开浏览器。
2. 交付建完后，【分析】与【设计】并行创建（均 TASK_SUB→交付）；标准/快轨两树可并行。
3. 状态用 transit + 本地追踪 fromStatus（禁止每次 GET）；负责人在交棒场景下创建时即何斐。
4. 建单 fieldValueList 可带计划开始 79；不要在 create 同时写 79+80（同日会 400）。
5. 标签必须 PATCH（create 带 tag 不落库）；可与建子任务重叠；快轨交付/设计须与需求同标签。
6. requests.Session keep-alive；禁止对共享 opener 加全局锁。
7. 脚本入口：scripts/live_create_fast.py（v5：快轨描述/计划/标签/工时 2+2/设计 ASSOCIATED 补挂）。