Workflow Feedback

---
name: workflow-feedback
description: 向 Workflow（workflow.games）平台方反馈问题与建议时使用——报错、API 行为与文档不符、体验不好、加载或操作明显卡慢、缺失功能、产品建议都算；只收集用户主动提供的信息组装报告，逐字展示完整报告与附件清单取得确认后，调公开匿名收件端点提交，以 sup_ 收件编号如实收尾。用户说向 Workflow 反馈、给平台提建议、插件好像有 bug、这里太卡太慢、要是有某功能就好了时使用；不往自己项目里记 bug（workflow-ops）、不答疑用法（workflow-docs）、不读取任何 Workflow 凭证。
---

# workflow-feedback — 向平台方反馈问题与建议

把用户遇到的 **Workflow 平台或本插件自身**的问题与建议报给平台方的客服收件箱：报错、API 行为与文档不符、体验不好、加载或操作明显卡慢、缺失功能、产品建议——**不限于报错，体验项同样值得上报**。

核心纪律一句话：**先逐字确认，后匿名发送；全程不碰凭证。**

## 硬闸门（命中即停）

以下 7 条是停止条件，不是风格建议；与正文其他要求冲突时以这里为准（出处 [references/feedback-gates.md](references/feedback-gates.md)）。

<!-- feedback-gates:start -->
| # | 触发条件 | 动作 |
| :-: | --- | --- |
| **F1** | 想读取 `WORKFLOW_TOKEN`、`config.toml`、`.workflow` 里的凭证，或想在请求里携带 `Authorization` 头 / Cookie | **停止**。反馈只走公开匿名端点——带上凭证等于把项目身份与密钥送进平台收件箱，服务端也会按敏感内容直接 422 |
| **F2** | 想为「补全上下文」去扫仓库、读项目文件、读环境变量、翻历史会话 | **停止**。素材只来自本轮对话里用户主动提供或点名的内容（包括本次会话刚发生、用户要求上报的报错与卡慢现象）；唯二例外是协议字段的本机读取——`workflow-update/VERSION`（pluginVersion）与宿主版本号 |
| **F3** | 完整报告、目标 Host、每个附件的文件名与大小、不发送清单尚未逐字展示，或用户尚未针对**这一版**明确说发送 | **不得** POST。「行」「内容不错」不是发送确认；`userConfirmed=true` 只表示这道确认做完了，不构成任何授权 |
| **F4** | 确认之后又改动了报告或附件的任何一处 | 旧确认与旧幂等键**同时作废**：重新展示、重新确认、重新生成 UUID——旧 key 配新内容必撞 409 |
| **F5** | 报告或附件疑似命中不发送清单（token、Cookie、配置正文、邮箱、完整 HTTP 请求体等，全清单见 ticket-fields.md） | **停止**，指出命中位置，让用户脱敏后重走确认；不「顺手删掉再发」——用户没看过的版本不算确认过 |
| **F6** | 想附上用户没有在**本次会话**明确点名的文件，或附件超 5 个、单个超 25MiB | **停止**。附件 = 用户点名 + 出现在已确认清单里，缺一不可；超限让用户取舍，不擅自截断或代选 |
| **F7** | 拿到 202 后想说「已建单」「已创建 Bug」「平台已受理为正式单」，或想替用户查询收件进度 | **停止**。`sup_` 开头的是收件编号不是单号，状态是待人工审核；平台没有公开的收件进度查询端点，转正与否由运营决定 |
<!-- feedback-gates:end -->

落单闸门 G1–G7 的前提（持凭证、写项目对象）在本技能不成立——**G 表不适用，也不在此内联**；G4 与 G3 的精神由 F1 / F5 / F7 承接，详见 feedback-gates.md。即使项目 Workflow 配置为 `full`，也不能绕过本技能的 F1–F7；匿名反馈永远不进入用户项目的 PM bundle。

## 边界：反馈做什么、不做什么

| 做 | 不做 |
| --- | --- |
| 把平台或插件的问题、体验、建议报给平台方收件箱 | 往用户自己的项目里建 bug / 需求（那是 workflow-ops） |
| 只组装用户主动提供的素材 | 为补全上下文扫仓库、读配置、读环境变量 |
| 发送前逐字展示并取得对这一版的确认 | 未经确认替用户发声，或确认后改了内容直接发 |
| 匿名调公开收件端点 | 读取 PAT、携带 `Authorization` 头或 Cookie |
| 如实转述 202 回执与 ProblemDetails | 把收件回执说成正式单，或替用户查审核进度 |

分流口诀：**记到自己项目 = workflow-ops；报给平台方 = workflow-feedback。** 用户说「Workflow 有个 bug」时先分清指哪边——拿不准就问一句，别猜。答疑用法转 workflow-docs；接入与连接问题转 workflow-setup。

## 前置（不需要任何凭证）

本技能**不读 workflow-ops 的凭证与连接前置**、不走凭证三级解析——那是持凭证技能的入口，反馈用不上，也不允许用（F1）。

1. **开关探测**：`GET /support/config`（无鉴权，完整地址与示例见 [references/submit-flow.md](references/submit-flow.md)）。`enabled=false` → 停止提交，把响应里的联络邮箱（`contactEmail`）与飞书群（`feishuGroupLink`）转述给用户走人工渠道。目标 Host 默认 `https://workflow.games`；用户明确点名其他 Workflow 部署时才替换，且替换后的 Host 必须出现在确认报告里。
2. **协议字段来源**（F2 的唯二例外，都是本机读取）：
   - `pluginVersion`：读同包的 `workflow-update/VERSION`（安装时与本技能同级）；读不到再取插件根 `plugin.json` 的 `version`；都取不到 → 停下说明无法满足 agent 渠道必填字段，改走人工渠道。
   - `hostType`：Claude Code → `claude_code`；Codex → `codex`。其他宿主在合同枚举里没有对应值——**不硬造**，停下说明并改走人工渠道。
   - `hostVersion`：宿主自报的版本号（如 `claude --version` / `codex --version` 输出的版本段）；取不到就填 `unknown`，并在确认报告里如实展示。

## 流程

### 1. 收集（只收用户主动提供的）

素材只来自本轮对话：用户的描述原文、他点名要上报的报错信息（包括本次会话刚发生的 ProblemDetails）、他点名的文件。可收集项：标题、现象描述、公开 operationId、ProblemDetails 的 traceId、已脱敏的最小复现、附件。**缺什么就列出来问用户，不去仓库里找**（F2）。

`type` 判定：报错、行为与文档不符、体验不好、卡顿慢 → `bug`；缺失功能、产品建议 → `feature`；分不清就问一句。体验类反馈把「慢或卡在哪一步、大约多久、期望多久」问清写进描述——只有「太慢了」三个字，运营无法定位。

### 2. 组装

按 [references/ticket-fields.md](references/ticket-fields.md) 落字段：operationId 与 traceId 走各自专用字段，**不塞进 description**；用户没给的字段一律留空，不替他填。组装完成后，先对照 ticket-fields.md 的**不发送清单**自查一遍（F5）——这是客户端的第一道扫描，服务端还会再扫一道。

### 3. 展示与确认

四件套**逐字展示**，缺一不可（F3）：

1. 最终完整报告（每个将发送的字段与值）；
2. 目标 Host；
3. 每个附件的文件名与大小；
4. 不发送清单（照 ticket-fields.md 原文）。

然后明确问：**「这一版是否发送？」** 得到对这一版的肯定答复后，生成一枚随机 UUID 幂等键，锁定这版内容。之后内容或附件**有任何改动**：回到本步重新展示、重新确认、重新生成 key（F4）。

### 4. 发送

按 [references/submit-flow.md](references/submit-flow.md) 的模板提交：multipart/form-data、`source=agent`、agent 五件套齐全。**干净会话**——不带任何 `Authorization` 头、不带 Cookie，不复用其他技能的调用模板（F1）。网络错误或 5xx：同一版报告**复用同一 key** 重发至多 2 次，绝不换 key 盲重发——那会绕过服务端幂等去重，制造重复收件。

### 5. 回执与收尾

只认 **202**。核对回执：`sup_` 开头的收件编号、`type` 与提交一致、`attachmentsStored` 与实际附件数一致（不一致要说明）、`idempotentReplay` 为 true 时说明此前已收到同一份。然后按下方「收尾汇报格式」向用户交付（F7）。

## 失败处置

| 状况 | 处置 |
| --- | --- |
| 422 | 字段不合规或命中敏感内容；ProblemDetails 只指出字段、不回显秘密——原样转述 detail，让用户改素材后**重走确认**（新版本 = 新 key），不猜着改了就发 |
| 409 | `idempotency_conflict`：同 key 配了不同内容——说明确认后内容动过，回到「展示与确认」重新确认并换新 key |
| 429 | 限流按 IP；响应必带 `Retry-After`（秒），把等待时长转述给用户；同一版重试仍用同一 key |
| 415 / 400 | 请求不是 multipart / multipart 解析失败——按模板修正请求形态后同 key 重发（内容没变，不用重新确认） |
| 413 | 请求体过大——让用户删附件或压缩内容；内容一变即重走确认换 key |
| 401 | 说明请求带上了失效的会话 Cookie——本技能必须是干净会话（F1）；去掉 Cookie 后同 key 重发 |
| 503 | 两种情况：该部署未开通收件 → 转述 `GET /support/config` 里的人工渠道；带附件且对象存储未配置 → 问用户是否去掉附件重发（去附件 = 内容变了 = 重走确认换 key） |
| 网络错误 / 5xx | 同版同 key 重发至多 2 次；仍失败把 ProblemDetails（含 `traceId`）原样给用户，**绝不伪装成功** |

## 收尾汇报格式

列表转述，不贴回执 JSON：

- **收件编号**：`sup_` 开头——明说这是**待人工审核的收件，不是正式单**；只有平台运营审核转正后才会产生正式 Bug / Requirement，且**没有公开的收件进度查询端点**，本技能不替用户查进度（F7）。
- **已提交内容摘要**：type、标题、带了哪些可选字段、哪些留空（如「未评估 severity」）。
- **附件**：`attachmentsStored` 与实际提交数对照；不一致时如实说明差额。
- **幂等**：`idempotentReplay=true` 时说明「服务端此前已收到同一份报告，本次未重复收件」。
- **边界声明**：本次未读取任何 Workflow 凭证；仅发送了确认清单内的内容。