PANGKAIFENG StyleWork 云效工作项提报
中文速查
- 中文名：StyleWork 云效工作项提报
- 英文稳定名：
stylework-yunxiao-workitem-submitter - 分类：产品与 PRD
- 你可以这样叫我：
把这次排查提成云效缺陷、创建云效需求并附上证据、先预览再提交工作项 - 适合：把讨论或排查结论整理成一个颗粒度合适、证据可追溯的云效需求或缺陷，经确认后创建、上传附件并回读验证。
- 不适合：批量排期、云效数据导出、更新已有工作项，或未经确认直接写入云效。
Overview
把讨论、排查或产品判断整理成一个颗粒度合适、证据可追溯的云效需求或缺陷。先生成完整预览，经用户对精确内容明确确认后，再通过当前运行时已配置的云效 MCP 创建并回读验证。
Hard Boundaries
- V1 只创建需求和缺陷，不更新、删除、关闭、移动或批量修改已有工作项。
- 默认一次确认创建一个工作项。批量输入可以拆成多个草稿，但必须展示精确数量和逐项内容后再确认。
- 预览不是提交授权。只有用户在看过最终预览后明确说“确认提交”“按以上内容创建”等等价表达，才能写入云效。
- 标题、类型、项目、描述、附件清单或其他已确认字段发生变化后，旧确认立即失效，必须重新预览和确认。
- 云效 MCP 不可用、工具 schema 不明确、目标项目或工作项类型无法唯一定位时，停止外部写入链路；不得改用浏览器、
curl、私有 HTTP API 或猜测 ID 绕过。MCP 缺失只阻塞提交，不阻塞生成完整的本地 Markdown 草稿和预览。 - 不上传原始日志、截图或附件，除非用户明确要求且 MCP 明确支持。上传前检查敏感信息、文件类型和大小；任一检查失败时在首次外部写入前停止。
- 不写入密钥、Token、Cookie、个人隐私、客户敏感数据或未经脱敏的内部 payload。
Context Intake
优先从当前对话、用户正在查看的云效页面、已提供 URL 和排查证据中提取信息，不重复追问。进入外部创建前至少确认：
- 目标云效项目的稳定 ID；
- 工作项类型：
需求或缺陷； - 标题和完整描述；
- 优先级：
紧急、高、中、低； - 用户明确要求上传的附件文件名；未要求时附件清单为空。
迭代、负责人、子模块和客户名称是可选字段。能够通过 MCP 列表或解析页面 URL 唯一定位时先形成候选并让用户确认；不能唯一定位时保持空白，不补造。只生成本地草稿时允许项目、迭代、负责人和子模块标为“待解析”，但类型、标题、优先级、完整描述和证据边界仍必须给出。最多集中询问 1-3 个会改变目标、类型或验收边界的问题。
Workflow
1. Decide type and granularity
读取 references/workitem-field-contract.md。
- 已有能力不符合预期、发生回归、报错或需要绕路才能使用，通常提
缺陷。 - 新增能力、扩展使用范围或治理完整生命周期，通常提
需求。 - 一个用户可感知问题优先对应一个主工作项；根因修复、测试和观测属于研发子任务或描述中的实现建议。
- 只有不同结果能够独立交付、独立验收或由不同责任方承接时，才拆成多个工作项。
先向用户说明建议类型和颗粒度；不要把每个技术动作拆成独立需求。
2. Build an evidence ledger
读取 references/evidence-description-contract.md，将材料分为：
已验证：日志、代码、接口结果、截图、复现或用户明确事实直接支持；有依据的推断：多项证据共同支持，但尚未完成直接验证；弱推断：主要依赖经验或不完整现象；待验证：会影响结论或验收，但当前没有证据。
每条证据至少记录类型、来源引用、观察结果和它支持的结论。日志使用路径与行号、trace/session ID 或时间戳；代码使用文件与行号；接口使用请求类型、时间和关键结果；截图说明画面中可直接观察到什么。无法复核的口述标为“用户陈述”，不要升级成系统事实。需要上传截图时，描述只写最终附件文件名和可观察结论，不写本机临时路径。
3. Draft the work item
按 references/evidence-description-contract.md 生成描述。缺陷至少包含：
【问题现象】、【期望结果】、【排查证据】、【排查结论】、【验收标准】
需求至少包含：
【需求背景】、【目标与价值】、【范围】、【排查证据】、【验收标准】
没有排查证据时明确写“本轮未提供可复核证据”，不得删除证据章节来制造确定感。
即使当前缺少云效 MCP 或稳定项目 ID，也先输出完整 Markdown 草稿，不得只给标题、证据摘要或恢复步骤。此时把无法解析的字段标为“待解析”，明确重复检查未完成和未发生外部写入；在稳定 ID 补齐前不要伪造 JSON 校验通过。
完成下一步的身份解析与重复检查后，再把工作项保存为本地临时 JSON 草稿。附件元数据至少包含最终文件名、MIME、字节数、SHA256 和敏感性检查结果；这些字段属于确认载荷。然后运行：
python3 <this-skill>/scripts/validate_workitem_draft.py /path/to/draft.json
校验失败时只修正草稿，不调用 MCP。
4. Resolve MCP identities and check duplicates
读取 references/mcp-submission-playbook.md。
- 检查当前运行时云效 MCP 的实时工具 schema，不依赖记忆中的参数名。
- 用项目、工作项类型、迭代、成员和模块的稳定 ID 调用创建工具；显示名只用于预览。
- 若 MCP 提供搜索或列表能力，在目标项目内按类型和规范化标题检查重复项。
- 找到疑似重复项时展示 ID、标题、状态和 URL，默认停止创建；用户明确说明差异后重新生成预览。
- 无法完成重复检查时，在预览中明确标记“重复检查未完成”，不得静默略过。
- MCP 缺失或身份解析失败时，到完整本地预览为止并停止外部流程；不要因此省略描述正文或验收标准。
5. Show the exact preview
用以下顺序展示：
类型：需求/缺陷
项目：<名称>（<稳定 ID>）
标题：<最终标题>
优先级：<紧急/高/中/低>
迭代：<名称与 ID，或未指定>
负责人：<名称与 ID，或未指定>
子模块：<名称与 ID，或未指定>
附件：<最终文件名、类型、大小；或无>
重复检查：<通过/发现候选/未完成>
描述：
<将要原样写入云效的完整描述>
随后只问一个确认问题：确认按以上内容创建 1 个云效<需求/缺陷>吗？
6. Freeze and validate the confirmed payload
用户确认后，将确认人、确认时间和预览校验产生的 fingerprint 写入草稿，再运行。fingerprint 必须覆盖附件元数据，确保确认后不能替换附件：
python3 <this-skill>/scripts/validate_workitem_draft.py \
/path/to/draft.json --require-confirmed
fingerprint 不一致说明确认后的字段发生变化，必须回到预览步骤。不得手工忽略校验错误。
7. Create exactly once
- 使用云效 MCP 中等价于
CreateWorkitem的工具创建一次。 - 记录请求时间、目标项目、返回 ID 和原始成功/失败状态。
- 创建调用超时、断连或返回结果不明确时，不得立即重试；先用搜索或读取工具确认是否已经创建。
- 无法确认远端状态时报告“提交结果未知”，保留草稿和 fingerprint，等待恢复后查证，避免生成重复工作项。
8. Upload confirmed attachments
- 只有工作项返回稳定 ID 后才上传附件；远程 HTTP MCP 使用
fileContent的 base64 与fileName，仅同机 stdio MCP 才使用本地路径。 - 按确认清单逐项上传，不上传未预览的文件。附件失败时保留已创建的工作项，不重复创建、不自动删除，也不盲目重传。
- 上传失败报告“工作项已创建，附件上传失败”，列出工作项 ID、URL、成功/失败文件名和可恢复动作。
9. Read back and verify
使用等价于 GetWorkitem 的工具按稳定 ID 回读，至少核对：
- 项目和工作项类型；
- 标题、优先级和描述；
- 迭代、负责人、子模块等本轮明确提交的可选字段；
- 稳定工作项 ID 与可访问 URL；
- 用户确认上传的每个附件文件名。
字段或附件列表不一致时报告“已创建但验证失败”或“工作项已创建，附件上传失败”，列出差异；不要自动修改远端工作项。
Output Contract
预览阶段输出：类型与颗粒度判断、完整字段、证据分级、完整描述、附件文件名/类型/大小、重复检查结果、待确认问题和 fingerprint。
创建完成后输出：工作项类型、标题、稳定 ID、URL、创建时间、字段回读、附件回读、未填写字段和任何剩余风险。
阻塞时说明完成到哪一步、阻塞原因、是否发生外部写入、下一次恢复必须先做的一个检查。若用户已经提供足够的现象或目标，阻塞输出仍必须附上完整可填的工作项草稿；只有连类型、用户问题或目标都无法判断时才可以只报告阻塞。
Evaluation
evals/evals.json 覆盖缺陷与需求草稿、证据分级、确认失效、重复检查、截图/PDF 附件、敏感或超大附件、附件部分失败、模糊创建结果、批量拆分、MCP 缺失和相邻 Skill 非触发场景。真实生产写入属于 L3 验证，必须在专用测试项目完成；结构测试和模拟输出不能替代真实 MCP 回读证据。
Definition of Done
- 工作项类型和颗粒度有明确理由，不把实现步骤平铺成多个需求。
- 描述包含所需章节，已验证事实、推断和待验证项没有混写。
- 目标项目和工作项类型使用稳定 ID，重复检查结果已公开。
- 用户确认对应最终 fingerprint，确认后载荷没有漂移。
- MCP 创建最多执行一次；模糊失败没有盲目重试。
- 附件在上传前完成敏感性、类型和大小检查；描述只引用最终文件名，不泄露本机路径。
- 创建结果已按稳定 ID 回读，附件已按列表回读，或被明确标记为未验证/部分成功/结果未知。
- 输出包含 ID、URL、回读结果和未完成项；没有泄露敏感数据。
Resource Guide
references/workitem-field-contract.md：需求/缺陷判断、颗粒度和字段规则。references/evidence-description-contract.md：证据等级、脱敏要求和描述模板。references/mcp-submission-playbook.md：实时 schema、去重、确认、创建一次、附件上传和回读规则。references/provenance.md：已发布来源、MIT 许可证、公开披露边界和后续权威维护位置。scripts/validate_workitem_draft.py：写入前的草稿结构与 fingerprint 校验。scripts/test_validate_workitem_draft.py：validator 的确定性回归测试。evals/evals.json：触发、回归、边界、迁移和非触发场景。