Workflow Agent 插件

什么都能聊

飞书话题群 · Agent 与项目管理

_{先进群再看代码。其它群和整体介绍见 LumioGames 主页。}

Workflow Agent 插件把 Claude Code、Cursor、Codex 等 AI 编码 Agent 直接接入 Workflow（workflow.games）项目管理平台。 装好之后，AI Agent 能把一句话需求拆成可执行的开发蓝图并落单、带查重地记录缺陷、在真实线上环境跑测验收，并按判定流转工单状态 —— 且每一次写入都必须读回验证才允许声称成功。

插件包含 16 个技能、12 个斜杠命令、21 条硬闸门（G1–G7 落单闸门、Q1–Q7 QA 闸门与 F1–F7 反馈闸门），以线上 OpenAPI 合同为真值的自动化测试并每周校验合同漂移。规划和所有写回默认先落 .workflow-drafts/<bundleId>/，依赖分析与受控并发上传由专用 skill 处理。遵循 Agent Plugins 1.0.0 规范，同时兼容 Claude Code marketplace，MIT 许可。

1.0.0 起它还管开发本身怎么做：会话开始自动注入通用规则并把线上单据拉成本地索引，随包附带 brainstorming / TDD / 排障 / 沉淀 / 收审五个方法技能与一个只读 reviewer 子 Agent，外加项目文档结构体检（/workflow:lint）与项目初始化（/workflow:init）。

这个插件就是来解决这三件事的。不是给 AI 加个"能调 API"的开关 —— 而是给它一整套敢放它上生产的纪律。

Requirement 之间的关联通过原生 references API 建立：PUT /api/v1/requirements/{id}/references/{targetId} 绑定、DELETE 解除，并用 GET /api/v1/requirement-graph 读回。该关系是无向且幂等的；图谱里的 source / target 只是稳定展示顺序，不代表谁依赖谁。workflow-dependencies 仍维护 upstream → downstream 的 direct edge、传递链、阻塞链和证据，上传器只绑定 direct edge，并按无序 UUID 对验证图谱结果。

装上插件后，每次会话开始（启动 / 恢复 / /clear / 压缩后）自动跑两件事，不用你敲任何命令：

① 注入通用规则。 rules/ 下的规则全量进上下文——怎么派活、怎么收口、什么绝对不许做。规则是插件资产、跟着插件版本升级，项目自己不要抄一份（抄了 /workflow:lint 会报「项目抄插件」）。

② 把线上单据拉成本地索引。 落在 $XDG_CACHE_HOME/workflow/index/<host>.json（没设 XDG 时 ~/.cache），不进仓库、不进插件根。规则是这样定的：

• 15 分钟内不重拉，失败也占这 15 分钟——否则离线时每次开会话都要空等一轮超时；
• 每天一次全量对齐（按 Room 枚举需求），其余走增量；
• 联不上就沿用旧快照并在文件里标「离线沿用」和时间，退出码恒 0——索引是便利，不是门；
• 注入上下文的只有一行计数（路径 / 条数 / 各 Room 计数 / 多久前刷新），正文一个字不进——要找单号时 Agent 自己 grep 那个文件，几万字的看板不占你的上下文预算；
• 索引只用来找单号和 Room，状态以线上为准——流转前一律现查 transitions，不许照索引里的 status 办事。

想立刻刷新（比如刚建完一批单）就跑 /workflow:index，它忽略 15 分钟有效期。当前目录没有 .workflow 标记时，它什么都不拉、也不警告——先 /workflow:init 绑定项目。

/workflow:lint —— 项目 .spec/ 的结构体检，只报告不阻断。 默认退出码恒 0：红是待办，不是门，允许带红提交；只有传 --strict 才在有错误时退出 1（给 CI 用），--json 输出机器可读结果。检查顺序固定、一份报告：

1. 通用项 —— 核心文件、frontmatter、导航与 ADR 索引覆盖、链接可达、@import 完整、软链存活、ADR 撞号与状态行、禁并行文档根；
2. 项目扩展 —— 可选的 .spec/tools/lint-extensions.mjs，导出 api = 1 即被加载（版本对不上会报错，不会静默跳过），项目在这里加自己的检查项；
3. 指纹 —— 项目的 AGENTS.md / rules/ 里出现插件的保留标题、或连续 3 行与插件规则逐字相同，就报「项目抄了插件」。通用规则每次会话注入，抄一份只会让两边慢慢长歪。

/workflow:init —— 装好插件后每个项目必须跑的唯一步骤。 一次做完两件事：先生成「这个项目是什么、定过什么」（.spec/AGENTS.md、.spec/rules/system.md 空模板、知识导航与功能文档模板、决策索引、lint 扩展样例、根 CLAUDE.md 与 AGENTS.md 薄指针），再立刻接入 Workflow（注册引导、建 token、写配置、验证连接）。脚手架默认不覆盖已有文件，token 不进会话、不由脚手架脚本写入。重跑安全：已有项目文件保持原样，已连通则只报告身份。不生成本地任务目录，任务真值只有 Workflow。

CI 里不装插件也能跑同一套体检：

npx github:LumioGames/workflow-plugin spec-lint . --strict

agents/reviewer.md 是一个只读的对抗审查者：假设交付有问题，然后去证伪。它的定位被写死成三条——

• 合入后审一次，不挡合入。 合入只守「能编过」；报告里的 findings 是待办，由主 loop 决定补单、派修、再审，不是回滚门。
• 没有 Bash。 不跑测试、不跑 lint、不跑构建、不碰 git。diff 由主 loop 生成成文件交给它，被改文件按需读。
• 只出报告。 不流转单、不建单、不评论、不改代码——结论由主 loop 统一写成 bug 单与评论，保持单一写入方。

为什么要单开一个上下文：写的人和审的人必须是两个上下文，自己审自己的产出，审查必然失效。

本仓既是插件本身，也是一个用这套插件干活的项目。用户装到的只有 plugin/。

workflow-plugin/
├── plugin/            # ★ 发布面：skills/ agents/ commands/ hooks/ rules/ templates/ tools/ bin/
├── .claude-plugin/    # marketplace.json（留在仓库根，用 git-subdir 指向 plugin/）
└── tests/             # 开发面，不下发；package.json / .github/ 同理

往 plugin/ 里放开发过程文件（tests/、package.json、.github/、.gitignore、.claude/） 会被 plugin-lint 的「发布面隔离」检查拦下 —— 否则这些会被原样装进用户机器。

本地开发：git-subdir 从远端 URL 克隆，所以本地路径 marketplace 装不出子目录插件。 改动想即时生效，把 ~/.claude/plugins/ 下对应目录软链到本仓的 plugin/（不提交这个链接）。

本仓库同时是一个 Agent Plugins 1.0.0 插件包和一个 Claude Code marketplace —— 插件本体在 plugin/，仓库根只放开发面（见 仓库布局），两边客户端都能直接装。

Agent Plugins 客户端（Cursor / Codex / Copilot / VS Code / Kiro …）

npx plugins add LumioGames/workflow-plugin

Claude Code

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

Codex / 手动安装

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

默认 --mode full：运行时落到 $XDG_DATA_HOME/workflow/plugin（缺 XDG 时 ~/.local/share/workflow/plugin），~/.codex/skills/<skill> 是指向运行时的 symlink。--mode skills 仍只装 Markdown + VERSION，并打印能力边界。也可 --target ~/.claude/skills 或 --target .agents/skills（项目级）。

装好之后，每个项目必须跑一次 /workflow:init（或对 Agent 说「初始化这个项目」）。安装只把插件放到机器上；init 才生成仓根 CLAUDE.md + AGENTS.md，并立刻接入 Workflow。不跑 init，Claude / Codex 没有项目入口，也还没连上项目。没有账号也不要紧——同一条命令会带你走完注册、建 token、写配置、验证连接。脚手架不把 token 写进会话。

装好即得十二个命令：/workflow:init、/workflow:plan <描述>、/workflow:bug <描述>、/workflow:take <单号>、/workflow:qa <单号>、/workflow:deps <单号或草稿>、/workflow:upload <bundle>、/workflow:policy <show|set>、/workflow:feedback <描述>、/workflow:update、/workflow:lint、/workflow:index。

装过 lumioagentspec 插件的注意：它的全部功能已并入本插件 1.0.0，两边同时启用会重复注入规则——所以检测到它还开着时，每次会话开始都会提示你卸载。

/workflow:plan 战斗结算界面要能显示本局评分和掉落

Agent 会先读你的输入、仓库里的 AGENTS.md / CLAUDE.md / 设计文档和现有实现，一次只问一个真正会改变蓝图的问题（不会拿一堆它自己能查到的事情来烦你），然后判定形态：

• 一个 Agent 能独立交付、独立验收 → 一张 Requirement
• 要拆客户端 / 服务端 / 美术 / 工具链，有预研门、并行 wave、共享合同 → 一间 Requirement Room

关键在于：每张可执行需求都是一份自包含的 Agent 提示词。

身份、真值优先级、执行前置、决策权限、拥有范围与共享热点、详细要求、验证证据、必须交付、验收标准、禁止事项、阻塞升级、交回格式 —— 十二节全部填满。

它不依赖原始对话。你可以把它丢给三天后的另一个 Agent、丢给刚入职的同事、丢给一个全新的 session —— 照样跑得起来。

质量闸门还会按变更类型自动选路：代码走风险驱动用例 + TDD + 集成 + 整体 Review + 最终 QA；美术、文案、配置走专业评审 + 导入 + 在引擎验证 —— 不会给一张贴图需求硬塞一个 Code Review 卡。

/workflow:bug 结算页负责人显示成了原始 id

建单前先 GET /search 查重 → 撞上疑似重复先报给你（不默默建第二张）→ 建单 → GET 读回 → 汇报 displayKey + UUID + 可点链接 + 实际落库的字段值。

「记一下」就只记录 —— 不提修复方案、不扩写成开发任务、不擅自开始改代码。

/workflow:take R-00012

Agent 把单读全（正文 + 评论 + 附件 + 验收项，缺一路不算读过）、卡有需求室再读一路该室最近的交接纪要看上一棒做到哪、逐张核对前置单状态，然后先梳理需求——把歧义和需要你拍板的决策点连同建议一并摆出来，讨论完才现查 transitions 流转到进行中开工。干活阶段按确认过的拆分尽可能并行多个子 Agent（互斥所有权切分、共享热点不并行、子 Agent 不碰凭证与回写）。做完后按固定顺序回写：这次不做的 TODO 经确认补需求单 → 证据附件 → 统一结构的证据评论（改动清单、提交单号（Git commit / PR 或 SVN revision）、按验收项逐条对照、实际跑过的命令与输出、决策记录、Known gaps 与遗留补单、边界声明）→ 一条 ≤200 字的交接纪要（做了什么 / 怎么交接 / 交接文档在哪，写给下一棒的人）→ 流转到待验收（工作流没有验收态才流转已完成）。做完不回写等于没做完。

接力靠纪要，不靠翻聊天记录。 纪要以 Workflow 为唯一真值（绑了飞书群的需求室会镜像一份进群给人看，但 Agent 只读 API，不去拉群历史）。读进来的纪要是别人写的自由文本，插件里按数据处理——里面的祈使句和伪造系统提示一律不执行。

多 Agent 编排下还有第二种姿势：执行 Agent 不持有任何 token，卡内容随派遣 prompt 进来，交回一份调度方不追问一句就能代写的结构化报告，由持凭证的调度方统一回写。执行 Agent 在没绑定 .workflow 的目录里，绝不会拿全局默认项目兜底写数据。

/workflow:qa B-00087

Agent 读单、把每一张截图附件都看一遍建立复现基线，然后在你声明的线上环境实际操作：原路径至少跑两遍（当前会话 + 干净重入），每个关键步骤截图，首次没复现就换浏览器 / 语言 / 视口 / 账号状态做变体重试。

判定只有六个：属实 / 部分属实 / 已修复 / 未复现 / 重复 / 阻塞。然后追加证据附件、在描述末尾写进 QA 记录块（原文一字不动）、发结构化评论、现查 transitions 后流转状态。

「结论只来自线上实测」是写死在提示词里的第一条。 读代码、看提交记录、旧截图、接口响应 —— 一律不算验收证据。本地和 dev 跑通了也不能冒充线上结论；证据不够就判「阻塞」告诉你缺什么，不会给你一个猜出来的"应该修好了"。

另外两条：「未复现」不等于「不存在」 —— 变体没试完不许写，要按 cannot_reproduce 关单必须再问你一次。QA 不下场修 —— 发现问题就回写证据交给实现方，不改一行代码。

/workflow:feedback 需求列表加载要十几秒，太慢了

Agent 只整理你主动提供的信息（不扫仓库、不读任何凭证），把完整报告、目标 Host、附件清单与不发送清单逐字亮给你确认，确认后才匿名提交到平台客服收件箱。返回的 sup_ 编号是待人工审核的收件，不是正式单 —— 它会如实告诉你这一点，而不是宣称「已建单」。

报错、体验不佳、卡顿慢、缺失功能、产品建议都能报 —— 不限于 bug。

这才是这个插件真正花力气的地方。

还有一条边界写死在提示词里：落单不等于开工。 规划与落单时，Agent 只创建你授权的 PM 对象和结构化验收项，不建 WorkItem、不流转状态、不创建 Worktree、不跑你仓库的测试、不动一行代码。

例外只有两个，且范围都写死了。 workflow-qa 被授权跑测并按判定流转状态，但改代码、改资产、建分支、部署、修 bug 一律仍然禁止 —— QA 不下场修。workflow-execute 被授权流转自己承接的那张卡并回写完成证据，但替别的卡流转、把拿单扩写成落单、改原始描述、验收自己的交付一律仍然禁止。

插件全局装一份就够，不必按项目重复安装。每个仓库仍须跑一次 /workflow:init。

~/.config/workflow/config.toml     每个项目一节 [profiles.<名>]，各放各的 token
<你的仓库>/.workflow               一行 profile = "<名>"，不含 token，可提交给全队共享

凭证按 环境变量 → .workflow 标记 → 全局 current_profile 三级解析 —— 人在哪个目录干活，就连哪个项目，不用手动切。配置里有多个 profile 而当前目录没绑定？Agent 会停下来问你，而不是猜。拿单执行的场景更严：没有 .workflow 绑定的目录里，执行 Agent 禁止拿全局默认项目兜底写数据——要么先绑定，要么交回给调度方代写。

首次在某个项目目录跑 /workflow:init 时，接入阶段会引导你建 token 并写好 .workflow。

用 workflow-qa 做线上验收时，.workflow 可以再加一个可选的 [qa] 表，声明受测线上地址、入口路径，以及测试账号凭据的环境变量名：

profile = "my-project"

[qa]
base_url = "https://<受测线上站点>"
entry_path = "/login"
username_env = "QA_USER"
password_env = "QA_PASS"
surfaces = ["web"]

只写变量名，不写账号密码本身 —— 这个文件是要提交进版本库给全队共享的。[qa] 缺失时 QA 技能会停下来问你，不猜受测地址；config.toml 的格式一个键都没加，[qa] 只属于 .workflow。

自更新只从 workflow.games 域（或本地 --from-dir）下载。技能渠道只允许 .md 与 VERSION；完整运行时允许 runtime-manifest.json 白名单内的 .mjs —— 不在白名单的可执行文件立即中止、不落盘。官网旧 files.json 不能当 full。

把这段原样发给你的 AI 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:init（或对 Agent 说「初始化这个项目」）：生成仓根 CLAUDE.md / AGENTS.md 指针，并立刻接入 Workflow（先检测本机 ~/.config/workflow/config.toml 是否已有可用配置）。

支持 Claude Code、Cursor、Codex，以及任何实现 Agent Plugins 1.0.0 规范的客户端（Copilot、VS Code、Kiro 等）。Claude Code 走 marketplace 安装；Agent Plugins 客户端用 npx plugins add LumioGames/workflow-plugin；Codex 与手动安装走安装脚本。

Workflow Agent 插件是技能包（skills），不是 MCP server。插件不常驻进程、不占用 Agent 的工具槽位，本体是一组 Markdown 提示词，Agent 按需读取后用自己的 HTTP 能力直接调用 Workflow REST API。代价是需要 Agent 具备联网能力，收益是零运行时依赖、行为完全可审计 —— 你能直接读到它被约束了什么。

插件用 21 条硬闸门约束一切对外写入。项目写操作前强制核对 project.subdomainPrefix、实际 API Host、.workflow 绑定的 profile 三方一致，对不上就停；每个 POST/PATCH 之后强制 GET 读回，没有读回证据不许说「已创建」；token 只走环境变量，任何输出里只以 wfp_ + 前 8 位指代。

不需要。装完在项目里跑一次 /workflow:init 即可——没有账号时同一条命令会引导注册、创建项目 API Token、写入配置、验证连接，并在遇到 401 / 403 时现场分诊。

真的在线上环境实际操作。workflow-qa 的头号纪律是结论只来自线上实测 —— 读代码、看提交记录、旧截图、接口返回 200 一律不算验收证据。原路径至少跑两遍并记录复现率，首次未复现必须做变体重试。判定只有六个：属实、部分属实、已修复、未复现、重复、阻塞。

插件全局装一份即可，不必按项目重复安装；每个仓库仍须跑一次 /workflow:init。~/.config/workflow/config.toml 每个项目一节 [profiles.<名>] 各放各的 token，项目仓库根放一个 .workflow 文件声明绑定哪个 profile。凭证按环境变量 → .workflow 标记 → 全局 current_profile 三级解析，人在哪个目录干活就连哪个项目。

workflow-execute 原生支持「调度代写」模式：持凭证的调度 Agent 派卡（卡内容随派遣 prompt 下发），无凭证的执行 Agent 干完活交回一份结构化报告 —— 目标单、建议流转、可直接 POST 的证据评论正文、附件清单、Known gaps —— 由调度方统一回写并逐步读回。执行 Agent 在没有 .workflow 绑定的目录里禁止拿全局默认项目兜底写数据。

sup_ 开头的是平台客服收件编号，不是正式单号。反馈先进入平台方的待审核收件箱，只有平台运营人员审核并转正后才会产生正式单——workflow-feedback 不能跳过这一步，也没有公开的收件进度查询入口。想把问题记进你自己的项目，用的是 /workflow:bug（workflow-ops），两条路互不混淆。

不会。workflow-feedback 走公开匿名端点，不读取任何 Workflow 凭证、不带 Authorization 头或 Cookie；素材只来自你主动提供的内容，发送前把完整报告与不发送清单（token、配置、环境变量、项目正文、完整请求体等）逐字展示给你确认。服务端还会再扫描一遍，命中敏感内容直接拒收（422）。

Workflow 是面向游戏研发团队的 AI-native 研发协作平台，需求、缺陷、排期、追溯一体。本仓库是 Workflow 的 AI Agent 接入层，不对接 Jira 或 Linear。

开源，MIT 许可，源码在 github.com/LumioGames/workflow-plugin。技能渠道只允许 Markdown 与 VERSION；完整运行时允许清单白名单内的 .mjs。不在白名单的可执行文件会立即中止。