安装 Agent 插件

给 Claude Code / Codex 一键装上 Workflow 技能包，Agent 自己完成接入、项目操作与安全反馈

适用角色：所有项目角色 · 最后更新：2026-08-11 · 约 6 分钟

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

插件能做的事：

前置条件

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

Claude Code 安装

在 Claude Code 里执行两条命令：

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

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

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

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

Codex 安装

有 shell 时一行装好：

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

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

请为我安装 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 是否已有可用配置。

首次使用示例

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

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

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

向 Workflow 提交产品反馈

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

  1. Agent 只整理你主动提供的标题、描述、公开 operationId、ProblemDetails traceId、插件与宿主版本，以及已脱敏的最小复现。它不会为了补上下文搜索仓库。
  2. Agent 展示最终完整报告、目标 Host、每个附件的文件名与大小，以及不发送清单。只有你针对这一版确切报告明确确认后，才会发请求；内容或附件变化必须重新确认。
  3. Agent 调公开匿名客服端点，不读取 WORKFLOW_TOKEN，不带 Authorization 或 Cookie，不获得项目权限。附件只允许你在本次对话中明确点名的文件。
  4. 服务返回 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 都会直接显示，不会被伪装成成功。

更新方式

常见问题

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。
Workflow 正在加载…