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。

1. 已有能力不符合预期、发生回归、报错或需要绕路才能使用，通常提 缺陷。
2. 新增能力、扩展使用范围或治理完整生命周期，通常提 需求。
3. 一个用户可感知问题优先对应一个主工作项；根因修复、测试和观测属于研发子任务或描述中的实现建议。
4. 只有不同结果能够独立交付、独立验收或由不同责任方承接时，才拆成多个工作项。

先向用户说明建议类型和颗粒度；不要把每个技术动作拆成独立需求。

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。

1. 检查当前运行时云效 MCP 的实时工具 schema，不依赖记忆中的参数名。
2. 用项目、工作项类型、迭代、成员和模块的稳定 ID 调用创建工具；显示名只用于预览。
3. 若 MCP 提供搜索或列表能力，在目标项目内按类型和规范化标题检查重复项。
4. 找到疑似重复项时展示 ID、标题、状态和 URL，默认停止创建；用户明确说明差异后重新生成预览。
5. 无法完成重复检查时，在预览中明确标记“重复检查未完成”，不得静默略过。
6. 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

1. 使用云效 MCP 中等价于 CreateWorkitem 的工具创建一次。
2. 记录请求时间、目标项目、返回 ID 和原始成功/失败状态。
3. 创建调用超时、断连或返回结果不明确时，不得立即重试；先用搜索或读取工具确认是否已经创建。
4. 无法确认远端状态时报告“提交结果未知”，保留草稿和 fingerprint，等待恢复后查证，避免生成重复工作项。

8. Upload confirmed attachments

1. 只有工作项返回稳定 ID 后才上传附件；远程 HTTP MCP 使用 fileContent 的 base64 与 fileName，仅同机 stdio MCP 才使用本地路径。
2. 按确认清单逐项上传，不上传未预览的文件。附件失败时保留已创建的工作项，不重复创建、不自动删除，也不盲目重传。
3. 上传失败报告“工作项已创建，附件上传失败”，列出工作项 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：触发、回归、边界、迁移和非触发场景。