# Workflow (workflow.games) — 全文语料

> 全部使用指南的正文,拼成一个文件,供 LLM 一次抓取。
> 索引与产品事实卡见 https://workflow.games/llms.txt;API 行为的单一真值是 https://workflow.games/openapi/gameflow.v1.yaml。
> generated by tools/help-site-build.mjs — do not edit

## 目录

1. 快速上手：从注册到第一个需求 —— 注册账号、创建组织与项目、邀请成员，到建出第一条需求的完整路径
2. 需求评审与流转 —— 需求从需求池到已完成的状态流转：谁能流转、哪些动作要填原因、如何回溯
3. 状态流转与自定义工作流 —— 需求、缺陷、子需求各自在哪里改状态，按钮为什么是灰的，槽位认领，以及给项目配自己的工作流
4. 缺陷提报、流转与关单 —— 三个提报入口、严重程度与优先级的分工、关单结论四选一，以及缺陷为什么关不掉
5. 排期依赖与甘特 —— 给甘特上的条目建前后置依赖、理解延期传播，以及为什么改依赖不会自动改日期
6. 里程碑 —— 用里程碑标记评审、集成、冻结、发布等关键节点，状态自动派生，不用手动维护
7. 通知中心与飞书集成 —— 铃铛通知都有哪几类、怎么全部已读，以及飞书群机器人报缺陷、私聊提醒怎么配
8. 安装 Agent 插件 —— 给 Claude Code / Codex 一键装上 Workflow 技能包，Agent 自己完成接入、项目操作与安全反馈
9. 成员与角色 —— 项目权限的两套开关：治理权限与模块访问级别，以及部门标签、最后管理员保护
10. 附件上传与安全下载 —— 了解可上传文件类型、大小限制、强制下载规则与常见报错

---

## 快速上手：从注册到第一个需求

- 页面: https://workflow.games/wiki/guides/getting-started
- markdown 源: https://workflow.games/md/guides/getting-started.md
- 适用角色: 所有人
- 最后更新: 2026-08-30

Workflow 是面向游戏研发团队的研发协作平台：需求、缺陷、排期、追溯在同一个地方闭环。这篇带你从零开始，十分钟内建出第一条需求。

### 注册与登录

```steps
在 `workflow.games` 点击**免费注册**，填入邮箱——我们会发送一封带验证码的邮件，填回验证码完成验证。
设置密码后登录。忘记密码时用登录页的「忘记密码」走同一套邮箱验证找回。
首次登录会引导你**创建组织**——组织是团队的容器，项目都挂在组织之下。
```

### 创建项目

```steps
在组织页点击**新建项目**，填项目名并选择一个**子域前缀**——项目开通后，团队通过 `你的前缀.workflow.games` 访问这个项目。
进入项目后完成**四步初始化引导**：确认你的角色与权限、补齐项目基本信息、按需调整默认配置。
引导完成后你会落在项目概览，左侧核心导航依次是：概览、需求、需求室、甘特排期、里程碑、缺陷；下方「数据与报表」组依次是：数据、报表、需求图谱。
```

```tip
「需求图谱」已经可用。「文档」「数据」「报表」仍标着「即将上线」，点进去只有预告卡，暂时还没有可用功能。
```

```tip
一个组织可以开多个项目，项目之间数据完全隔离。你在 A 项目的角色、权限、通知都不会带到 B 项目。
```

### 邀请成员

在「项目设置 → 成员管理」填同事的邮箱、选好角色，点「邀请成员」——邀请邮件会直接发到那个邮箱。对方接受后即成为项目成员，拿到你在邀请里指定的角色。角色决定他能看到、能操作哪些模块——详见[成员与角色](/wiki/guides/members-roles)。

### 建出第一条需求

```steps
点击顶栏的**新建**按钮(或需求列表的「新建需求」)，打开统一创建面板。
选择类别「需求」，填标题——只有标题是必填的；负责人不填默认是你，优先级默认 P1。
提交后需求落在**需求池**(backlog)状态，等待评审。它会拿到一个 `R-` 开头的单号，全项目可搜索。
```

创建成功后，打开需求详情就能看到完整的字段、动态流，以及推进状态用的「需求流程」区。下一步：读[需求评审与流转](/wiki/guides/requirement-transitions)，了解需求怎么从需求池走到已完成。

### 常见问题

```faq
注册需要付费吗？
当前阶段注册即可使用，无需付费。平台如暂停开放注册，登录页会有公告说明。

必须用飞书吗？
不必须。飞书是可选集成：绑定后可以收私聊通知、在群里 @机器人 报缺陷。不绑定不影响任何核心功能。

项目子域填错了怎么办？
子域前缀是项目的访问入口，开通后如需调整请联系组织管理员处理，避免自行反复改动导致成员链接失效。
```

---

## 需求评审与流转

- 页面: https://workflow.games/wiki/guides/requirement-transitions
- markdown 源: https://workflow.games/md/guides/requirement-transitions.md
- 适用角色: 所有项目角色
- 最后更新: 2026-07-30

需求从「需求池」到「已完成」的每一步状态变更都通过**流转**完成——谁、在什么时候、因为什么原因推进了状态，全部留痕，随时可以回溯。

### 需求会经历哪些状态

```status-flow
需求池 | neutral
评审中 | warning
已评审 | neutral
实现中 | accent
验收中 | neutral
已完成 | success
已否决 | danger | terminal
```

这是内置的 7 状态流程。如果你的项目配置了自定义工作流，状态名称和顺序可能不同——原理相同。需求卡片上的「进入某状态多久」徽标，显示的就是当前状态的停留时长。

### 如何流转一条需求

```steps
打开需求详情，找到「需求流程」区：点当前状态徽章(带 ▾)展开可去的状态，或直接点下面那排流转按钮。两处都只列从当前状态出发的动作。
选择目标状态。**评审相关的动作会要求填写原因**(提交评审、评审驳回、否决)——原因会永久记录在需求动态里，供日后回溯。
确认后状态立即生效，相关人会收到通知(站内 + 飞书，如已绑定)。
```

```tip
同一区还有「⇄ 查看流程图」，能把本项目当前生效的那张状态图整张摊开看——想知道「从这里还能去哪」时比逐个点按钮快。
```

### 谁能执行哪些动作

```perm-table
提交评审 | 需要「需求」模块 edit 以上——通常是策划 / 需求负责人。
评审通过 / 驳回 | 需要「甘特排期」模块 edit 以上——通常是制作人 / PM。这与提交评审刻意分开，同一个人不该既提审又拍板。
否决 | 任何有权限的角色都必须填写原因才能否决。
```

```tip
这里说的模块级别由项目管理员在「项目设置 → 权限设置」按角色配(那张矩阵是改角色定义的唯一地方)；某位成员当下是什么角色，在「项目设置 → 成员管理」看和换。两页的分工详见[成员与角色](/wiki/guides/members-roles)。
```

### 常见问题

```faq
流转按钮是灰色的？
悬停可以看到被阻止的原因——通常是权限不足，或该状态之间没有配置流转路径。

提示「状态已被他人修改」？
有同事在你之前刚刚流转了这条需求。刷新页面看到最新状态后再操作即可，不会产生脏数据。

找不到文档里说的某个状态？
你的项目可能使用了自定义工作流。在「项目设置 → 工作流」查看当前生效的状态集。
```

---

## 状态流转与自定义工作流

- 页面: https://workflow.games/wiki/guides/work-item-workflow
- markdown 源: https://workflow.games/md/guides/work-item-workflow.md
- 适用角色: 所有项目角色；配置工作流需「管理工作流配置」
- 最后更新: 2026-08-11

项目里的三类对象——需求、缺陷、需求下的子需求——状态变更都走同一套**工作流引擎**：每一步流转有权限守卫、有留痕、可回溯。但三者的操作入口不在一处，这篇先把入口说清楚，再讲项目管理员怎么定制自己的工作流。

```tip
左侧导航里没有「任务」这一项，这是有意的：执行拆解已经收进需求详情的**子需求清单**，缺陷去「缺陷」页。找不到任务列表不是权限问题，产品里就没有这个入口。
```

### 三类对象，三个入口

```steps
**需求**：进需求详情的「需求流程」区——点当前状态徽章(带 ▾)展开可去的状态，或点下面那排流转按钮。详见[需求评审与流转](/wiki/guides/requirement-transitions)。
**缺陷**：进「缺陷」页，在看板上把卡片拖到目标状态列，或点卡片上的状态点选一条出边；也可以打开缺陷详情，用「流程」区里的流转按钮。全项目只有缺陷页有看板。
**子需求**：子需求没有独立页面，它挂在需求详情概览里的清单上，那份清单是只读的。要改子需求状态，去「甘特排期」——在图上点中那一行，右侧检查器的「流程」区就是它的流转入口。
```

不管从哪个入口进，列表里只出现**从当前状态出发**的动作；选中目标状态，需要时填原因，原因会进入对象动态供回溯。默认缺陷/子需求流程里的「取消」强制填写原因，并进入已取消终态；完成或已取消后再次取消会明确返回 422，不会静默当成成功。流转后状态立即生效；如果工作流配了处理人路由，「当前处理人」会随之切换，轮到的人会收到站内通知。

### 按钮为什么是灰的

灰色动作代表「流转路径存在，但当前被拦住」。悬停能看到人话原因，常见三类：

```perm-table
权限不足 | 你的角色在这个模块的访问级别不够——找项目管理员在「项目设置 → 权限设置」调，级别与模块的对应关系见[成员与角色](/wiki/guides/members-roles)。
必填字段为空 | 目标状态要求某个字段先填好(比如缺陷关单前要填处理结论)。
不能连续经手 | 工作流配置了「同一人不能连续两步经手」的岗位分离守卫，换个人来执行。
```

### 槽位与认领

工作流可以给状态配**角色槽位**(比如「开发」「QA」)：槽位里是一组候选人，谁来处理靠**认领**。

- 卡片处于待认领状态时，槽位成员在详情页的「流程」区点「认领」即成为当前处理人；其他成员随后认领会提示已被抢先。
- 认领只改「当前处理人」，不改槽位成员名单；负责人(owner)单独由「负责人」字段管理，不走槽位。

### 自定义工作流(项目管理员)

内置工作流不够用时，在「项目设置 → 工作流」自己配：

```steps
**新建模板**：可从系统种子模板起步，也可从空白开始。一个模板服务一类对象——需求，或缺陷与子需求。
**编辑草稿**：增删状态、连流转边、配守卫(权限/必填字段/岗位分离)与槽位路由。草稿随便改，不影响线上。
**校验并发布**：发布前引擎会校验图的完整性(可达性、终态等)；发布产生一个新版本，**在途对象平滑迁移**——已有卡片按映射落到新状态集，不丢数据。
**绑定类型**：把模板绑定到对象类型上，之后这类对象走新工作流。
```

```tip
状态名可以随便起，但每个状态都要归到一档统一的**进度分类**(待分类 / 待办 / 未开始 / 进行中 / 已完成 / 已取消 / 重复)。看板列色、统计口径、通知徽章的颜色都取自这档分类——所以自定义状态再多，全局视图的颜色语言依然是一套。
```

### 常见问题

```faq
改了工作流，旧卡片会怎样？
发布时你会先看到迁移预览：每个旧状态映射到哪个新状态、影响多少张卡。确认后一次性平滑迁移，历史动态保持不变。

我用 API Token 调流转接口被拒？
早期用 all scope 签发的 token 可能不含工作流管理权限。在「项目设置 → API Token」重新生成即可；token 的实际权限永远不会超过你本人当下的角色权限。

需求和缺陷的工作流是一套吗？
同一个引擎、各自的模板。需求默认走内置 7 状态流程，缺陷与子需求默认走 6 状态流程（含需要原因的「已取消」终态），都可以被自定义模板替换。

为什么子需求只能在甘特图上改状态？
子需求是需求下的执行拆解，没有自己的列表页；甘特图是它唯一有流转入口的地方。需求详情里的子需求清单只做进度回显，点不动状态。
```

---

## 缺陷提报、流转与关单

- 页面: https://workflow.games/wiki/guides/bug-lifecycle
- markdown 源: https://workflow.games/md/guides/bug-lifecycle.md
- 适用角色: 查看需「缺陷」模块 read；关单需「执行验收」
- 最后更新: 2026-08-11

缺陷单号以 `B-` 开头，可以挂在某条需求下，也可以独立存在——线上冒烟发现的问题往往还没有对应需求。它和需求下的子需求走同一套工作流引擎，但多两个只属于缺陷的字段：**严重程度**与**关单结论**。

### 三个提报入口

```steps
**顶栏「新建」**：在统一创建面板里把类别选成「缺陷」，填标题即可提交，其余字段都能后补。
**需求详情的「＋提缺陷」**：从需求页发起，来源需求自动预填，省掉回头再关联的一步。
**飞书群 @机器人**：在绑定的飞书群里 @机器人 加一句话描述，机器人直接建单并回帖单号；消息里的截图会自动采集成附件。配置方式见[通知中心与飞书集成](/wiki/guides/notifications-feishu)。
```

```tip
标题写**现象**，别写猜测的原因。「战斗结算界面数值对不上」比「结算逻辑写错了」有用得多——原因要靠排查确定，现象才是提报人唯一确知的事实。描述里补上重现步骤、发生环境和期望结果，再拖一张截图上来，处理人能少问三轮。
```

### 严重程度不是优先级

两个维度同时存在于一张缺陷单上，各回答一个不同的问题：

```perm-table
严重程度 severity | 「坏得有多厉害」——阻断 / 严重 / 一般。描述客观影响面，发现的人如实填。
优先级 priority | 「先修哪个」——P0 / P1 / P2 / P3。描述当前的排期意图，由负责人按版本节奏定，会随节奏变。
```

一个阻断级缺陷可能因为发生在下个版本才开放的玩法里而被排成 P2；一个只影响单行文案的一般级缺陷，也可能因为在发布会演示路径上而被顶成 P0。两者不联动，不要拿其中一个推断另一个。

### 状态怎么走

缺陷默认走内置的六状态流程。如果项目配置了自己的工作流，状态名与顺序以「项目设置 → 工作流」里当前生效的那一版为准。

```status-flow
待办 | neutral
进行中 | accent
待验证 | warning
验收 | neutral
完成 | success | terminal
已取消 | neutral | terminal
```

「取消」是一条从任意非终态进入**已取消**的明确动作，必须填写原因；完成和已取消都不能重复取消。取消表示这条缺陷不再继续处理，不等于「已修复 / 不修复 / 无法复现 / 重复缺陷」中的任何一种关单结论，所以进入已取消时结论保持为空；若缺陷曾完成后重开，取消还会清掉旧结论。

改状态有三个地方：缺陷页看板上把卡片拖到目标状态列、点卡片上的状态点选一条出边、或者打开缺陷详情用「流程」区里的流转按钮。灰掉的动作悬停能看到人话原因，判读方法见[状态流转与自定义工作流](/wiki/guides/work-item-workflow)。

### 关单要给结论

缺陷以**完成**收尾时，在详情页「流程」区把**关单结论**选上——它回答「这条是怎么完成的」，四选一：

```perm-table
已修复 fixed | 问题真的改掉了，并且验证过。
不修复 wontfix | 确认是问题但决定不改（成本、优先级、功能即将下线等），理由写进原因里。
无法复现 cannot_reproduce | 按单上的步骤复现不出来。回帖说明你试过的环境与版本，别直接关掉了事。
重复缺陷 duplicate | 与另一条是同一个问题。在评论里贴上保留的那条单号，方便日后回溯。
```

完成态的结论字段允许留空，但留空等于没人知道它是怎么完成的——统计与复盘时只能靠人去猜。已取消缺陷是例外：取消原因在动态流与流转日志里，结论必须为空，不能拿 fixed / duplicate 等值冒充取消原因。

```tip
把缺陷推进**完成**需要「执行验收」权限，缺这个权限时引擎会挡下流转并返回 403。这是刻意的：提报的人和判定「修好了」的人应当分开。推进**已取消**不要求执行验收权限，但必须填写取消原因。
```

### 从一堆缺陷里找到你要处理的那批

缺陷页默认落在**待处理**视图，它会把已经收束的缺陷整批藏起来——列表上方会明说藏了几条，一键切到「所有的」。另外三个视图是「所有的」「我处理的」「我创建的」。

在此之上还有六个筛选维度：部门 / 状态 / 处理人 / 严重程度 / 优先级 / 里程碑，以及项目自己定义的缺陷自定义字段。六维筛选会写进地址栏，所以筛完直接把链接发给同事，他打开看到的就是你看到的那一批。当前筛选与排序后的结果还能一键导出 CSV。

### 常见问题

```faq
缺陷必须关联需求吗？
不必须。这是缺陷与子需求最大的区别——子需求必须挂在某条需求下，缺陷可以独立存在。有对应需求时关联上，验收与里程碑的风险汇总才能把它算进去。

看不到「缺陷」模块？
你的角色在这个模块上的访问级别是 none。模块访问与治理权限是两套互不重叠的开关，详见[成员与角色](/wiki/guides/members-roles)。

改了严重程度，优先级会跟着变吗？
不会。早期版本里严重度确实由优先级派生，现在两者独立采集、独立筛选，改一个不动另一个。

飞书建出来的缺陷，负责人是谁？
是「项目设置 → 飞书集成」里指定的缺陷默认负责人。机器人不猜人，建完你再改派即可。
```

---

## 排期依赖与甘特

- 页面: https://workflow.games/wiki/guides/schedule-dependencies
- markdown 源: https://workflow.games/md/guides/schedule-dependencies.md
- 适用角色: 「甘特排期」模块 edit 及以上
- 最后更新: 2026-07-30

**排期依赖**把甘特上的两个条目(需求下的子需求、缺陷)串在时间线上：前置完成后，后继才能开始。依赖驱动关键路径计算和延期传播——甘特图上那条最长的红线，就是依赖串出来的。

### 建一条依赖

```steps
在甘特图上从前置条目拖到后继条目(或在详情页的排期区添加前置)。
需要间隔时设置 **lag 天数**：0 表示前置一完成就能开始，2 表示完成后再等两天。不支持负数(不允许重叠抢跑)。
填写原因(比如「联调必须等接口先合入」)。每次依赖变更都进变更流，可回溯。
```

两种情况会被当场拒绝，并给出人话原因：

- **自己依赖自己**：不能把一个条目设成它自己的前置。
- **成环**：这条依赖会形成循环——目标条目已经(直接或间接)依赖了它的前置。检测覆盖间接环(A→B→C→A)，不止两点互指。

### 改依赖不会自动改日期

加/删依赖只改变「推导出的排期」，**不会自己动任何条目的日期**。要把下游日期真正推过去，走两步：

```steps
**预览传播**：看到哪些条目会被推到什么日期——这一步不写库，只是演算。
**确认应用**：填写原因后一次性落库，产生变更记录，相关人收到排期变动通知。
```

```tip
这是刻意设计：延期传播动辄改一串人的日期，必须有人看过影响面再确认，不让系统悄悄改你的排期。
```

### 常见问题

```faq
删依赖需要重新校验吗？
不需要。删除不可能制造循环，直接生效；删掉的依赖同样留痕。

依赖只支持「完成-开始」吗？
是，当前只支持 finish_to_start(前置完成后开始)，这是游戏研发排期里最常用的一种；其余三种关系暂不支持。

我看不到「添加依赖」入口？
依赖读写要求排期模块 edit 及以上权限。找项目管理员确认你的角色的模块访问级别。
```

---

## 里程碑

- 页面: https://workflow.games/wiki/guides/milestones
- markdown 源: https://workflow.games/md/guides/milestones.md
- 适用角色: 查看需「里程碑」模块 read；新建与编辑需 edit；删除需 manage
- 最后更新: 2026-07-30

**里程碑**是项目时间线上的检查点——评审、集成、冻结、发布，或任何你自定义的节点。它把一组需求圈在一个目标日期下，进度和风险自动算给你看。

### 里程碑怎么用

```steps
在排期模块**新建里程碑**：起名、定目标日期，按需写说明。不挂需求的里程碑也成立，当作项目级节点用。
把需求**归属到里程碑**：在需求详情单选里程碑即可(一条需求同一时间只属于一个里程碑)；选空则移出。每次变更要填原因，进变更流。
之后看板和甘特上就能看到：里程碑的**状态由挂在它下面的需求进度自动派生**——全没开工是未开始、有在途是进行中、全完成是已达成——不能也不需要手动改。
```

```tip
里程碑还会自动汇总**风险项**：关联需求里的高风险需求和它们下面的阻塞缺陷。里程碑进入风险态时，相关人会收到「里程碑存在风险项 N 个」的通知。
```

### 编辑与删除

- **编辑**：标题、说明、目标日、关联需求都可改；只有非空字段会被更新，清空说明要用显式的「清除说明」。
- **删除**：软删，**不影响任何需求**——只是节点消失、关联解除，需求本身和它们的排期原样保留。

### 常见问题

```faq
为什么不能直接改里程碑状态？
状态是从关联需求的进度派生的事实，手改会造成两套真相。想让里程碑「完成」，把它下面的需求推到完成。

一条需求能挂多个里程碑吗？
界面上是单选：归属新里程碑会自动解除旧归属。保持「一条需求一个当前节点」让进度归属清晰。

里程碑和版本(Release Window)什么关系？
版本是发布窗口(时间段)，里程碑是检查点(时间点)；里程碑可以关联到某个版本，在甘特上一起看。
```

---

## 通知中心与飞书集成

- 页面: https://workflow.games/wiki/guides/notifications-feishu
- markdown 源: https://workflow.games/md/guides/notifications-feishu.md
- 适用角色: 所有项目角色；集成配置需管理员
- 最后更新: 2026-07-28

Workflow 的通知不是第二套消息系统——每条通知都是一条真实业务变更(谁把什么从 A 流转到 B)投影给「应该看到它的人」。所以通知永远可回溯：点进去就是那条变更本身。

### 你会收到哪些通知

```perm-table
指派给我 | 我名下的子需求或缺陷被创建、修改或指派。
我负责的需求 | 我名下需求的状态流转。
轮到我处理 | 工作流路由把卡片流到我的槽位/我认领的岗位。
@提及我 | 有人在评论里 @我。
排期变动 | 传播应用后我的条目日期被推移(通知里带旧→新日期)。
里程碑风险 | 我相关的里程碑进入风险态(带风险项计数)。
项目接管 | 项目管理职责被接管的项目级通告。
```

- **项目内铃铛**：显示当前项目的通知与未读数。
- **中央面铃铛**(workflow.games 根域)：聚合你在**所有项目**的通知，点击跨子域直达对象；「全部已读」一键清所有项目——个别项目标记失败时会明确提示并可重试，不会假装成功。

### 飞书集成能做什么

两条独立能力，都在「项目设置 → 飞书集成」由管理员配置：

**① 群机器人收缺陷**：在绑定的飞书群里 **@机器人 + 一句话描述**(可带截图)，机器人自动在项目里建一条缺陷并回帖 `已创建 B-00123`。截图会作为附件带进缺陷；下载失败不影响缺陷创建，会在描述里标注。

**② 消息投递**：高优先级变更(如流转、排期变动)渲染成飞书卡片投到群里；绑定了飞书身份的成员还能收到**私聊提醒**，私聊不可达时自动降级为群内提名，再不行只留站内通知——层层降级，不静默丢失。

```steps
管理员在飞书开放平台建**企业自建应用**，开机器人能力，按最小权限申请三项：接收群 @ 消息、以机器人身份回复、读取消息资源(下载截图用)。
在「项目设置 → 飞书集成」填入应用凭据、绑定群 Chat ID、指定缺陷默认负责人，启用集成。
成员在个人设置里**绑定飞书身份**(OAuth 授权)，之后就能收私聊提醒；不绑定只影响私聊，群播报与站内通知照常。
```

```tip
机器人只处理**绑定群**里 **@它** 的消息，其他群聊内容一概不读；应用权限按最小集申请即可，清单见项目设置页内的权限说明。
```

### 常见问题

```faq
通知太多怎么办？
铃铛支持只看未读；「全部已读」一键清空。通知按「与我相关」投影，不是全项目广播——如果你收到大量通知，通常说明你名下在途对象太多，值得先收敛负载。

飞书群里 @机器人 没反应？
按顺序检查：应用版本是否已发布并过审、机器人是否在群里且能发言、事件订阅是否配置了「接收消息」、群 Chat ID 是否与设置页一致。

为什么有的通知点开显示的名字是邮箱前缀？
显示名优先用飞书资料名，拿不到时退回邮箱前缀——不会显示机器 id，也不会编造名字。
```

---

## 安装 Agent 插件

- 页面: https://workflow.games/wiki/guides/agent-plugin
- markdown 源: https://workflow.games/md/guides/agent-plugin.md
- 适用角色: 所有项目角色
- 最后更新: 2026-08-11

Workflow Agent 插件是一组给 AI Agent 用的技能包：装进 Claude Code 或 Codex 之后，你的 Agent 就知道怎么接入 Workflow、怎么调 API。你只管用自然语言下指令——「帮我记个 bug」「把这条需求流转到评审中」「今天我名下有什么」——接入配置、查文档、调接口都由插件里的技能引导 Agent 自己完成。

插件能做的事：

- **接入引导**：没有账号会一步步带你注册建项目；有账号会带你签发 API token 并写好本机配置。
- **业务操作**：建需求、记缺陷、查询与指派、状态流转、评论、传附件。
- **查文档**：接口细节实时指回官网机器可读文档(llms.txt 与 OpenAPI 合同)，不靠过期的本地快照。
- **提交反馈**：先展示完整报告并脱敏，等你明确确认后匿名送进客服收件箱，不使用项目 token。
- **自更新**：插件自己能检查新版本并完成升级。

### 前置条件

没有硬前置——**有没有 Workflow 账号都可以先装**。装好后第一次使用时，接入技能(workflow-setup)会探测本机配置：已配好就直接可用；没配过会按「注册 → 建项目 → 签发 token → 写配置」引导你完成，全程明说哪几步需要你在浏览器操作。

### Claude Code 安装

在 Claude Code 里执行两条命令：

```text
/plugin marketplace add LumioGames/workflow-plugin
/plugin install workflow@workflow-plugin
```

装完即生效，插件市场会自动保持更新。

**团队预装(可选)**：把下面的片段合入仓库的 `.claude/settings.json`，团队成员打开 Claude Code 时自动安装，不必人人手动执行命令：

```json
{
  "extraKnownMarketplaces": {
    "workflow-plugin": {
      "source": { "source": "github", "repo": "LumioGames/workflow-plugin" }
    }
  },
  "enabledPlugins": ["workflow@workflow-plugin"]
}
```

### Codex 安装

有 shell 时一行装好：

```bash
curl -fsSL https://workflow.games/plugin/install.sh | bash
```

没有 shell(或想让 Agent 全程自己来)时，把下面的安装 prompt 原样发给 Agent，由它抓取版本清单、逐文件校验后落盘：

```text
请为我安装 Workflow（workflow.games）Agent 插件：
1. 抓取 https://workflow.games/plugin/version.json?cb=<当前时间戳>，读出 version 与 files 字段；
2. 抓取 files 指向的清单（加同样的 cb 参数），逐个下载清单中的文件并校验 sha256，不符则停止并告诉我；
3. 跑插件自带的安装器（默认 --mode full）：完整树落到 $XDG_DATA_HOME/workflow/plugin，~/.codex/skills/<skill> 指过去。技能渠道只允许 Markdown 与 VERSION；full 允许清单白名单内的 .mjs。备份不进 skills。旧 files.json 不能当完整运行时；
4. 列出安装的技能与版本；
5. 然后直接开始 workflow-setup 技能的接入流程：先检测本机 ~/.config/workflow/config.toml 是否已有可用配置。
```

```tip
默认完整运行时：规则、工具、reviewer 一并就位。`--mode skills` 仍只含 Markdown 与 VERSION。凭证只写进本机 `~/.config/workflow/config.toml`(权限 0600)，不会上传到别处。
```

### 首次使用示例

装好后直接对 Agent 说：**「帮我记个 bug：登录页在 Safari 上点登录没反应」**。会发生什么：

```steps
Agent 先探测本机配置：`~/.config/workflow/config.toml` 里有可用的 token 就直接进入下一步；没有则先走接入引导(注册或签发 token)。
Agent 调 Workflow API 在当前项目里创建一条缺陷，标题与描述来自你那句话。
Agent 回给你缺陷单号(如 `B-00123`)和链接，你可以在项目的缺陷看板里看到它。
```

之后就是日常用法：查询(「我名下有哪些在途需求」)、流转(「把 R-00045 流转到评审中」)、评论、传附件，都是一句话的事。

### 向 Workflow 提交产品反馈

如果你遇到 Workflow 本身的问题，可以说：**「向 Workflow 反馈：调用 createRequirement 返回 503，traceId 是 trace_example_01」**。Claude Code 也可用 `/workflow:feedback <描述>` 薄入口；两种宿主最终执行的是同一份 `workflow-feedback` 技能。

```steps
Agent 只整理你主动提供的标题、描述、公开 operationId、ProblemDetails traceId、插件与宿主版本，以及已脱敏的最小复现。它不会为了补上下文搜索仓库。
Agent 展示最终完整报告、目标 Host、每个附件的文件名与大小，以及不发送清单。只有你针对这一版确切报告明确确认后，才会发请求；内容或附件变化必须重新确认。
Agent 调公开匿名客服端点，不读取 WORKFLOW_TOKEN，不带 Authorization 或 Cookie，不获得项目权限。附件只允许你在本次对话中明确点名的文件。
服务返回 202 后，Agent 展示 sup_* 收件编号并说明状态仍是 pending。它只进入人工审核收件箱，不会自动创建正式 Bug 或 Requirement。
```

确认前的不发送清单至少包括：token、Authorization、Cookie、`.workflow`、`config.toml`、环境变量、邮箱、项目文件与正文、跨租户数据、账户或会话、完整 HTTP 请求体，以及未明确点名的附件。客户端先扫描一次，服务端还会再次扫描；命中敏感信息时返回 422，只指出字段，不回显秘密。

每次确认后的确切报告会生成随机 UUID 幂等 key。同一报告遇到网络错误或 5xx 时，Agent 不会换 key 盲重发；恢复时复用同一 key，服务端返回同一个 `sup_*`，避免重复收件与重复附件。409 表示同一 key 的内容发生变化，422 表示字段或敏感信息不合规，429 会附等待时间，503 表示该部署未开通收件或附件存储不可用；这些 ProblemDetails 都会直接显示，不会被伪装成成功。

```tip
客服反馈与项目操作是两条独立边界。`workflow-ops` 使用绑定项目的 PAT 并受角色权限约束；`workflow-feedback` 只访问公开客服收件端点，不读取 PAT，也不能指定支持项目、负责人或审核结果。
```

### 更新方式

- **Claude Code**：插件市场自动更新(autoUpdate)，无需手动操作；也可随时执行 `/plugin` 查看当前版本。
- **Codex**：对 Agent 说**「更新 workflow 插件」**，更新技能会对比本地版本与官网版本清单，有新版则覆盖式重装，只动 `workflow-` 前缀的技能目录。

### 常见问题

```faq
plainToken 只显示一次，当时没复制怎么办？
token 明文只在创建那一刻显示，之后任何页面只能看到前缀，服务端也只存哈希、无法找回。处理办法：到「项目设置 → API Token」把那枚 token 吊销，重新创建一枚并立刻复制。

调 API 返回 403 是什么意思？
403 表示 token 有效但权限不够，常见两种原因：一是 token 的 scopeMode 是 read_only(只读哨兵)却在做写操作，需要换一枚 all 的 token；二是有效权限 = token scope ∩ 你此刻在项目里的角色权限，你的角色最近被管理员调小了。找项目管理员确认角色即可，不建议借他人 token 绕过权限。

反馈返回 sup_* 后为什么项目里没有 Bug？
`sup_*` 是客服收件编号，不是正式 Bug 单号。反馈先进入 pending 收件箱，只有平台运营人员审核并执行「转正式单」后才会在预先配置的支持项目里产生 Bug 或 Requirement；Agent 不能跳过这一步，也没有公开的收件进度查询入口。

我在多个项目里工作，怎么配？
插件全局只装一份，不必按项目重复装。token 绑定「本人 × 单个项目」，每个项目在该项目的设置页各建一枚 token，本机 `~/.config/workflow/config.toml` 里各占一节 `[profiles.<名>]`；再在每个项目的仓库根放一个 `.workflow` 标记文件(内容一行 `profile = "<profile 名>"`，不含 token，可提交进版本库与全队共享)。Agent 取凭证按「环境变量 → `.workflow` 标记 → 全局 `current_profile` 兜底」三级解析，在哪个项目目录里干活就自动连哪个项目。最省事的做法：在项目目录里对 Agent 说「接入 Workflow」，接入技能会带你建好 token 并问你要不要写入 `.workflow`。
```

```tip
接口层面想了解更多(token 权限模型、限流、端点清单)，看 [Agent 接入](/wiki/agents)与在线 [API 参考](/wiki/api)。
```

---

## 成员与角色

- 页面: https://workflow.games/wiki/guides/members-roles
- markdown 源: https://workflow.games/md/guides/members-roles.md
- 适用角色: 查看需「查看项目」；换成员角色需「管理成员」；改角色定义需「管理角色」
- 最后更新: 2026-07-30

「他为什么看不到缺陷模块？」「为什么有权限改设置的人反而动不了需求？」——十有八九是把项目权限的**两套开关**混为一谈了。这篇讲清楚它们怎么分工。

### 一个角色，两套权限

每个项目角色身上有两套**互不重叠**的权限：

```perm-table
治理权限 | 管「项目本身」：项目设置、成员、角色、验收配置、工作流配置、审计。
模块访问 | 管「业务数据」：需求、需求室、甘特排期、缺陷、里程碑、文档六个模块，每个模块单独一档。
```

这六个模块名与项目左侧导航一一对应——导航里有的模块，权限矩阵里就有同名的一行。

两套互不越界：模块全 manage 的角色照样改不了项目设置；拿满治理权限的角色，若「需求」模块是 none，连一条需求都看不到。

### 模块访问的四个级别

```status-flow
none 不可见 | neutral
read 只读 | neutral
edit 可编辑 | accent
manage 可管理 | success
```

- **none**：导航里直接看不到该模块，直连也会被拒。
- **read**：看、搜、下载。
- **edit**：创建、编辑、评论、传附件、普通流转——日常干活够用。
- **manage**：再加删除、批量操作、重新归属和高影响动作(比如应用排期传播、删里程碑)。

### 日常操作

```steps
**看成员**：「项目设置 → 成员管理」列出所有成员——邮箱、角色、部门标签、飞书绑定状态一目了然。
**调角色**：在同一页给成员换角色即换权限，立即生效。系统会拒绝把**最后一个有管理能力的成员**降级或移除——项目永远至少留一个能管事的人。
**改角色定义**：角色定义不在成员管理里，在隔壁的「项目设置 → 权限设置」——那张矩阵才是改治理权限与模块访问级别的地方。编辑模块访问时六个模块要**整组提交**(读出来、改一档、整组存回)，不存在「漏填就是不变」。
```

```tip
**部门**(前端/服务器/引擎/策划/美术/UI…)只是展示与筛选标签，不参与任何权限判断。移除成员后，他的历史记录与名下对象原样保留，工作不会被自动转派。
```

### API Token 的权限从哪来

用 API Token(PAT)访问时，实际权限 = **token 的 scope ∩ 你此刻的角色权限**，每次请求实时计算：

- 只读 token 把六个模块全部钳到 read，写命令一律拒绝；
- 你的角色被降级，手里所有 token 立即跟着降，不需要吊销重发；token 永远做不了你本人在界面里做不了的事。

### 常见问题

```faq
为什么我看不到某个模块的导航入口？
你的角色在该模块是 none。这是刻意设计：无权限的模块整个隐藏，而不是点进去再报错。

403 了怎么区分「没权限看」和「只能看不能改」？
报错信息会区分这两种情况，按提示找管理员调对应模块的级别即可。

能给某个人单独开权限、不动角色吗？
不能。权限只挂在角色上——想精细化就建一个新角色。这保证权限审计只看角色一处。
```

---

## 附件上传与安全下载

- 页面: https://workflow.games/wiki/guides/attachments
- markdown 源: https://workflow.games/md/guides/attachments.md
- 适用角色: 所有项目成员
- 最后更新: 2026-08-11

项目里的附件用于保存截图、录屏、日志、文档与诊断材料。服务端按文件扩展名判定类型，不信任浏览器声明的 MIME。

### 允许的类型

<!-- BEGIN GENERATED ATTACHMENT FILE TYPE POLICY -->
当前允许扩展名（由 OpenAPI 单一策略源自动生成）：`.bmp`、`.csv`、`.doc`、`.docx`、`.gif`、`.gz`、`.html`、`.jpeg`、`.jpg`、`.js`、`.json`、`.log`、`.md`、`.mov`、`.mp4`、`.pdf`、`.png`、`.ppt`、`.pptx`、`.txt`、`.webm`、`.webp`、`.xls`、`.xlsx`、`.zip`。

其中 `.md`、`.html`、`.js` 按不可信文本或源码保存，规范 MIME 固定为 `application/octet-stream`，任何 `disposition=inline` 请求都强制下载。
<!-- END GENERATED ATTACHMENT FILE TYPE POLICY -->

SVG、可执行文件和未列出的脚本类型仍会被拒绝。扩大清单需要单独的安全决策。

### 大小与下载

- 单个文件最多 25 MiB，服务端按实际读入字节复核。
- 图片和视频可以在附件区内联预览。
- 其他文件默认下载；受控文本与源码即使请求内联也会强制下载。
- 所有下载响应都带 `X-Content-Type-Options: nosniff`，不让浏览器猜测并执行文件内容。

### 类型不支持时

类型不受支持会返回 `422`。响应里的 `rejectedExtension` 是被拒扩展名，`allowedExtensions` 是服务端当前允许清单，`docsUrl` 指回本指南。上传控件会显示同一份允许清单，修改文件扩展名并不会改变文件内容是否安全，请选择真正受支持的文件格式。

```faq
为什么 HTML 和 JavaScript 可以保存，却不能内联打开？
它们只作为不可信的诊断材料或源码存储。强制下载可以避免同源页面执行附件里的脚本。

为什么 SVG 仍不能上传？
SVG 能嵌入脚本和外部资源，风险边界不同，因此当前不在允许清单里。
```