# Stylework Yunxiao Workitem Submitter

> StyleWork 云效工作项提报 / 需求与缺陷创建：当用户要把讨论结论、排查记录、日志、代码、接口结果、截图或复现过程整理成云效需求或缺陷，并要求预览后通过云效 MCP 提交时使用。也适用于判断工作项颗粒度、生成证据化描述和回读创建结果；不用于批量排期、导出到钉钉、静默修改已有工作项，或在未确认时产生外部写入。

- Skill: `pangkaifeng/stylework-yunxiao-workitem-submitter` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add pangkaifeng/stylework-yunxiao-workitem-submitter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pangkaifeng/stylework-yunxiao-workitem-submitter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: PANGKAIFENG (https://skillmd.com/u/pangkaifeng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pangkaifeng/stylework-yunxiao-workitem-submitter

---


# 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 和敏感性检查结果；这些字段属于确认载荷。然后运行：

```bash
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

用以下顺序展示：

```text
类型：需求/缺陷
项目：<名称>（<稳定 ID>）
标题：<最终标题>
优先级：<紧急/高/中/低>
迭代：<名称与 ID，或未指定>
负责人：<名称与 ID，或未指定>
子模块：<名称与 ID，或未指定>
附件：<最终文件名、类型、大小；或无>
重复检查：<通过/发现候选/未完成>

描述：
<将要原样写入云效的完整描述>
```

随后只问一个确认问题：`确认按以上内容创建 1 个云效<需求/缺陷>吗？`

### 6. Freeze and validate the confirmed payload

用户确认后，将确认人、确认时间和预览校验产生的 fingerprint 写入草稿，再运行。fingerprint 必须覆盖附件元数据，确保确认后不能替换附件：

```bash
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`：触发、回归、边界、迁移和非触发场景。