Vibeflow

Vibeflow

面向 AI 编码 Agent 的任务管理——内置批注与验证功能。

Vibeflow 为你的编码 Agent 提供有序、可领取的工作：包含层级结构的任务、原子化的 --next 领取操作，以及带验证结论的审核关卡——所有内容都保存在仓库中的本地优先看板上。你还可以点击 UI 元素，直接创建附有精确选择器、URL 和源文件位置的工单，让视觉反馈以结构化任务而非文字说明的形式呈现。

🌐 网站 · 📖 教程

▶ 观看完整动态演示（MP4）

---

为什么重要

AI Agent 编写代码很快，但理解要改什么却很慢。用文字描述 UI 问题会浪费 token，还容易导致修复出错。

Vibeflow 将视觉反馈转化为结构化任务：

• 点击任意元素 → 立即创建附有 CSS 选择器、URL 和源文件位置的任务
• 在看板上跟踪 → 一目了然地查看所有内容，并在列之间拖动任务
• Agent 根据上下文实现 → 无需猜测、不选错元素、不浪费迭代

非常适合小型 UI 修复、布局问题、间距问题，以及任何指点比解释更快的情况。

---

安装

使用 npx 运行一次即可，无需安装：

npx @vibeflow-tools/cli kanban

也可以全局安装，方便之后使用。这会添加简短别名 vf：

npm install -g @vibeflow-tools/cli
vibeflow kanban                  # or: vf kanban

要求： Node.js >= 22。采用 Apache-2.0 许可。无需账户，也不使用云端服务——每个任务都是仓库中的一个 JSON 文件。

---

快速开始

# 1. Start the local server and open the Kanban board
npx @vibeflow-tools/cli kanban

# 2. Annotate a running app: open http://localhost:3700/inject and drag the
#    bookmarklet onto your bookmarks bar (or use the script tag / console snippet)

# 3. Click elements in your app to create tasks — the CSS selector, URL and
#    source location are captured for you. You can also create tasks on the board.

# 4. Let your agent pick up the next task with full context
npx @vibeflow-tools/cli tasks --next

---

查看实际效果

在看板上拖动任务——Backlog → Todo → In Progress → Review → Done。拖动卡片即可更改其状态；即使重新加载页面，看板也会保留更新后的列和顺序。标签、用户和类型筛选器会在移动任务时保留状态，每次更改都会直接写入任务存储，因此 CLI 和你的 Agent 会立即看到更新。

将工作拆分为父子任务树——将大型任务拆分为子任务，每个子任务都保留自己的状态、优先级和历史记录。可以在卡片中展开任务树，也可以在终端中使用 vibeflow tasks --add --title "..." --parent <id> 创建子任务。使用 vibeflow tasks --get <id> 获取任务时也会返回相同的层级结构，因此 Agent 可以领取叶子任务，同时保留其父任务信息。

在一个面板中查看完整工单——打开任意卡片即可查看完整工单：状态、描述、标签、优先级、作者、关联关系（子任务和相关任务）、活动动态以及文件附件。更改会自动保存；在面板的任意位置粘贴截图或文件，都会将其附加到任务，而不是保存到 Downloads 文件夹。

---

MCP 服务

Vibeflow 通过 MCP 暴露任务工具，因此 Agent 可以直接读取和更新工单。每个项目配置一个服务：服务在启动时解析一次项目根目录，所有工具调用都会使用该根目录，因此无法写入错误的项目。

stdio（推荐——无需端口，无需保持运行）：

{
  "mcpServers": {
    "vibeflow": {
      "command": "npx",
      "args": ["-y", "@vibeflow-tools/cli", "mcp", "--project", "/path/to/project"]
    }
  }
}

--project 为必需项：启动的客户端的工作目录（通常是你的主目录）始终不可信，并且在创建任何内容之前都会验证根目录。将此配置放在项目中——放在仓库根目录的 .mcp.json 中，或放在编辑器的工作区配置中并使用 ${workspaceFolder}。

HTTP（需要持续运行的服务）：

vibeflow serve --project ./my-project    # MCP endpoint at /api/mcp

配置令牌前仅限回环访问。两种传输方式挂载的工具集完全相同；只有传输方式不同。

不要运行一个全局服务并在每次调用时指定项目参数——这是有意不支持的。一个进程只服务一个根目录，该目录在启动时解析。

type:"Research" 任务在附加 .md 报告之前会被拒绝审核，并返回 RESEARCH_REPORT_REQUIRED。通过 MCP 附加报告的方式是使用文件名以 .md 结尾的 attach_file——检查机制会在任务文件中查找 .md 文件，因此起作用的是文件名。此接口没有对应的 --report-file 选项；拒绝响应中的 suggestion 仅为 CLI 调用方列出该 CLI 标志。Research 任务不得带有验证结论（RESEARCH_VERIFY_NOT_ALLOWED）——它没有可供验证的标注界面。

MCP 结果

工具结果会将有效负载作为一份 JSON 文档放在 content[0].text 中——这适用于每种工具级成功和工具级拒绝。只有两种情况不是 JSON：协议级错误——工具自身的架构拒绝的参数，或不存在的工具名称——会以 result.isError === true 返回，且 content[0].text = MCP error -32602: …，没有可解析的封装。因此应先检查 isError，仅在该字段不存在时才将文本解析为 JSON。

这两种协议级错误通过消息中指出的对象区分，而不是通过代码区分——SDK 通过相同的输入验证路径报告未知工具，因此两者都带有 -32602，尽管 JSON-RPC 为“未找到方法”保留了 -32601：

你发送的内容	消息指出的对象	解决方法
工具架构拒绝的参数	有问题的字段（… at title）	发送该字段，并使用架构要求的类型
不存在的工具名称	该工具	查看 tools/list；你发送的名称不在此服务公开的工具中

架构错误类别（-32602）——按设计不含 vibeflow 代码

工具自身架构拒绝的输入（create_task 未提供 title、attach_file 未提供 contentB64、list_tasks 的 limit:-1）会在 MCP SDK 的输入验证阶段被拒绝，且发生在任何 vibeflow 处理程序运行之前。因此 vibeflow 从未收到该调用，也无法为其附加 code 或 suggestion。返回内容如下：

result.isError === true
content[0].text = "MCP error -32602: Input validation error: Invalid arguments for tool
                   create_task: Invalid input: expected string, received undefined at title"

以下三点都是有意为之，且至关重要：

• 它不会出现在下方的代码表中，今后也不会。 该表中的每个代码都是处理程序有意生成的 vibeflow 领域代码。-32602 是 JSON-RPC 的参数无效代码；它不属于 vibeflow 的代码体系，且永远不会作为表中的一行出现。
• 它会指出有问题的字段（… at title、… at contentB64）——消息的最后一个词就是出错的字段。
• 其代码字符串取决于客户端，因此不要用它作为判断依据。 有些客户端会将此类别规范化为自己的字符串（例如，Pi MCP 适配器会将其报告为 call_failed）。该标签属于客户端，而非 vibeflow：普通 JSON-RPC 客户端会将相同的拒绝报告为 MCP error -32602；在其他客户端的输出中搜索某个客户端专用标签，会让使用方误以为行为有所不同，实际并非如此。 **根据错误的形态识别类别，而不是依据代码字符串：**结果满足 isError === true，且其文本包含一条指出字段名称的输入验证消息。补救方法始终相同——发送它指出的字段，并使用架构要求的类型。未知工具不属于这一类别：它没有指出任何字段，因此不符合上述规则，补救方法也不同（见上表）。仅依据代码判断会把两者归为一类，让读者去检查输入字段，而真正的问题其实是工具名称。

由于 tools/list 是客户端在失败前唯一能读取契约的地方，输入形状会为每个 Agent 常弄错的字段提供 description——每个任务工具上的 id（大多数工具接受完整 ID 或唯一前缀）、setVerify/verifyReason 这一对字段、limit、contentB64、评论正文，以及 filename（其扩展名决定是否接受）。请在那里查看；没有第二次机会。

JSON 场景有三条规则，它们都是 CLI 自身的惯例：

• 拒绝请求时使用 CLI 封装格式。 {ok:false, error:{code, message, retryable, suggestion?}}——与 tasks --json 写入 stderr 的格式相同，因此同一个解析器可以处理两种接口。工具级拒绝不会设置 isError；它是一个普通结果，其 JSON 为 {ok:false, …}。

• 每次拒绝都带有 suggestion，其含义是“要改什么”。代码告诉你触发了哪条规则；建议则告诉你满足规则的输入是什么。每次工具级拒绝中的 error.suggestion 都是非空字符串——包括通用 catch 包装器（LIST_TASKS_ERROR、GET_TASK_ERROR、CREATE_TASK_ERROR、UPDATE_TASK_ERROR、ADD_COMMENT_ERROR、ATTACH_FILE_ERROR、VERIFY_TASK_ERROR、PUSH_TASKS_ERROR、CLAIM_TASK_ERROR）——并且会指出同一门槛可通过的两种接口：MCP 输入或工具，以及 CLI 标志。CLI 和 MCP update_task 会读取同一个门槛的建议，因此仅适用于 CLI 的建议是 MCP 客户端无法执行的答案。（verify_task 是唯一会返回 CLI 验证引擎自身代码的工具——E_NOT_FOUND、E_NO_BASELINE、E_NO_SELECTOR 等。代码保持不变；如果引擎没有附带自己的说明，工具会改为提供通用恢复提示，而不会返回一个无从着手的代码。）唯一不带 suggestion 的类别是上文提到的架构错误，它永远不会到达处理程序。

• “没有可认领项”表示成功。在空看板上调用 claim_next_task，或使用有效筛选条件但没有匹配到任何任务，都会返回 ok，且载荷为 null，而不是错误。认领操作的载荷就是 Task 本身，因此对象表示已认领任务，null 表示没有可认领项；这与 vibeflow tasks --next --json 返回 task:null 且退出码为 0 的结果相同。dryRun 预览也会返回相同结果，因此预览不会与实际调用不一致。不存在 NO_TASKS_AVAILABLE 代码。

• 必须了解的非失败情况会放在 notices 中，这是一个由 {code, message} 对象构成的数组，也是 CLI 在 --json 成功载荷中使用的同一个键。提示信息是非致命信号，不是部分成功的同义词——应根据 code 分支判断，绝不能仅凭数组存在与否判断：

  code	含义
  DRY_RUN	这是一次预览；没有写入任何内容
  GIT_COMMIT_FAILED	任务已写入，但没有创建提交
  GIT_COMMITTED	仅供参考——提交已成功；message 是 sha
  dryRun:true 预览会携带 notices:[{code:"DRY_RUN", message:"Task would be updated"}]（或相应的短语——Task would be created / claimed、Comment would be added、
  File would be attached、Verification would run）；评审状态转换在自动提交成功时会携带含有 sha 的 GIT_COMMITTED，自动提交失败时则携带 {code:"GIT_COMMIT_FAILED", message:"…"}。此处不再包含 steps 键，notices 中也不会出现裸字符串。（warning 字符串是不同的字段，不会出现在这里。）

---

相关软件包

• @vibeflow-tools/prototyping — React 应用内变体切换，并通过 URL 持久化。npm install @vibeflow-tools/prototyping
• Live kanban demo — 在浏览器中试用 vibeflow 看板。

---

命令

命令	描述
vibeflow kanban [dir]	启动服务并在浏览器中打开实时 Kanban 看板
vibeflow serve [target]	提供 HTML 文件并叠加实时标注，或为现有应用运行仅 API 的任务服务
vibeflow tasks	列出、筛选、创建、编辑任务并添加评论
vibeflow mcp [--project <dir>]	通过 stdio 运行 MCP 服务（由 MCP 客户端启动）
vibeflow telemetry	管理 CLI 使用遥测（可随时选择退出）

vibeflow kanban [dir]

vibeflow kanban                   # open Kanban board for current directory
vibeflow kanban ./my-project      # open Kanban for a specific project

Kanban 看板提供可视化任务跟踪器，包含可拖放的列、父子任务树、Agent 状态显示和文件附件。可直接在看板上创建任务，也可从带标注的原型中导入任务。

vibeflow serve [target]

vibeflow serve .                  # serve all HTML files in current directory
vibeflow serve dashboard.html     # serve a single file
vibeflow serve -p 4000 .          # custom port
vibeflow serve --no-open .        # don't open browser automatically
vibeflow serve                    # API-only mode — connects to an existing hosted app

提供 HTML 原型并叠加标注层——点击任意元素，即可创建包含其 CSS 选择器、URL 和源位置的任务。

vibeflow tasks

通过命令行全面管理任务——专为方便 Agent 使用而设计。

# Pick the next task (auto-claims a todo task)
vibeflow tasks --next                             # picks highest-priority todo task
vibeflow tasks --next --type Bug                  # next bug task only

# List tasks
vibeflow tasks                                    # tasks (default: 5 most recent)
vibeflow tasks --limit 0                          # show all tasks (no limit)
vibeflow tasks --json                             # machine-readable JSON output

# Filter
vibeflow tasks --status todo                      # by status
vibeflow tasks --type Bug                         # by type (Task, Bug, Feature, Enhancement, Research)
vibeflow tasks --user [email protected]             # by author email
vibeflow tasks --tag frontend --tag urgent        # by tags (AND matching)

# Get full details of a single task
vibeflow tasks --get <id>                         # supports partial ID prefix

# Create a task, or a child of an existing one
vibeflow tasks --add --title "Fix header" --description "Button overflows on mobile"
vibeflow tasks --add --title "Adjust the tour copy" --parent <id>

# Edit a task
vibeflow tasks --edit <id> --set-status in-progress
vibeflow tasks --edit <id> --title "Updated title" --description "More detail"

# Verification verdict (agent attestation — pass/fail/cannot, one only)
vibeflow tasks --edit <id> --set-verify pass                   # task IS implemented correctly (green badge)
vibeflow tasks --edit <id> --set-verify fail                   # task is NOT correct (amber badge; blocks review)
vibeflow tasks --edit <id> --set-verify cannot --verify-reason "<why>"  # unverifiable here (no badge; reason recorded)
# Research tasks must NOT carry a verdict — they have no annotated UI to verify, and the CLI REJECTS it (RESEARCH_VERIFY_NOT_ALLOWED)

# Mark as review (requires implementation report; annotated URL+selector tasks also need a verdict)
vibeflow tasks --edit <id> --set-status review --set-verify pass \
  --commit-message "fix: header layout" \
  --comment "Fixed the alignment issue by adjusting flex-wrap"

JSON 输出（--json）： 一个封套，一个 ok 判别字段。成功时向 stdout 写入 {ok:true, …payload}——tasks → {ok:true, tasks:[…], hiddenChildren}，--get → {ok:true, task:{…}}，--add/--edit/--next → {ok:true, task:{…}, next_actions:[…]}。失败时向 stderr 写入 {ok:false, error:{code, message, retryable, suggestion}} 并以非零状态码退出。所有非零退出都会输出该封套——此前拒绝操作时只打印说明文字，导致机器端消费者拿到空的 stdout，且没有错误代码。在 --json 模式下，所有执行路径的 stdout 都为空或恰好包含一个 JSON 文档，无一例外。

“没有可处理的任务”属于成功。 在空看板上运行 --next，或使用有效筛选条件（--type Bug、--tag）但未匹配到任何待办任务时，会向 stdout 写入 {ok:true, task:null, next_actions:[]}，并以 0 退出。其键集合与成功认领任务时相同，因此可通过 task === null 判断分支：已认领的任务始终是对象。筛选条件未匹配到任何任务，与看板为空的情况相同，不是特殊情况。不使用 --json 时，No todo tasks found. Nothing to work on. 这句话和以 0 退出的行为均保持不变。MCP 工具 claim_next_task 对同一情况也会以相同方式响应——见下文。（这推翻了早先在 --json 模式下打印该句子的规定；NO_TASKS_AVAILABLE 已不再使用。）

--user 是例外，而且一直如此：tasks --next --user … 会以 E_USAGE（退出码 2）拒绝操作，而不是报告看板为空，因为该筛选条件要根据候选作者列表进行验证，而 --next 不会生成此列表。此拒绝行为早已存在，不受上述空看板成功行为的影响。

每种含义对应一个代码：

code	含义	可重试
E_USAGE	标志值错误，或标志组合不可能（例如，没有 --set-status review 却使用 --report-file、使用 --edit 但没有 id 且没有要编辑的内容、在在线看板上使用 --parent）	否
TASK_NOT_FOUND	任务或父任务不存在（与 MCP 工具使用相同的代码）	否
E_NOT_FOUND	缺少其他内容，例如 --report-file 路径	否
E_BACKEND_UNAVAILABLE	在线后端调用失败——仅当主机无法访问时，retryable: true	仅在无法访问时
E_NOT_AUTHENTICATED	没有令牌，或会话被拒绝（HTTP 401/403）	否
E_COMMENT_SAVE	任务已写入，但请求的文本未保存：--comment，或 cannot 判定的 --verify-reason	否
GIT_COMMIT_FAILED	在 error.code 中表示没有提交任何内容；在 notices[].code 中表示任务已写入，只是没有执行提交	否
REINDEX_WRITE_FAILED	--reindex-sort-keys 计划写入 sortKey，但一项也未写入——没有任务文件发生更改	否
REVIEW_COMMENT_REQUIRED、COMMIT_MESSAGE_REQUIRED、BRANCH_REQUIRED、VERIFY_REQUIRED、VERIFY_FAILED_ATTESTED、VERIFY_REASON_REQUIRED、RESEARCH_REPORT_REQUIRED、RESEARCH_VERIFY_NOT_ALLOWED	审查门禁拒绝（参见 vibeflow tasks --edit --set-status review）	否

代码按命令划分作用域，并非全局通用：tasks 中的 TASK_NOT_FOUND 表示“没有此任务”， 而 tasks 中的 E_NOT_FOUND 表示“没有此文件”（例如 --report-file）；这两种接口有 各自的代码方案。请读取你调用的命令所返回的代码。

此表是领域代码词汇表——每一行都表示 vibeflow 处理程序有意产生的一种拒绝，每种拒绝都带有说明如何纠正的 suggestion。这里有意不包含架构错误类别：如果工具自身的架构拒绝某项输入，MCP SDK 会在任何处理程序运行前拒绝该输入，因此不会有 vibeflow 代码或 suggestion——如何识别这类错误，请参见上文 架构错误类别（-32602）。

notices 是 CLI 中用于结构化表示调用方应知晓的非致命信号，并通过 code 区分的字段——它并非“部分成功”的同义词，而且该数组的存在本身并不表示出了问题。在成功负载中，它是一个可选的 {code, message} 数组；运行顺利时不会出现：

code	含义
GIT_COMMIT_FAILED	任务已写入，只是审查后的自动提交未能执行
REINDEX_INCOMPLETE	sortKey 重新键入已完成，但其后置断言未通过
SET_STATUS_DONE	一条策略说明：Agent 应将工作标记为 review；只有人工可以将任务标记为 done
RESEARCH_NO_IMPLEMENT	Research 任务没有可移交的实现
ALREADY_IN_PROGRESS	任务已处于进行中状态；未作任何更改

该字段始终是数组（不会是单独的对象，也不会拆分成复数形式的 notices/warnings）。本地 --edit 路径会发出所有这些信号；在线 --edit 路径只能产生 SET_STATUS_DONE（其余信号是针对本地任务文件判定的，而在线看板没有对应项）——因此应将 notices 理解为“可能存在也可能不存在的数组”，而不是固定的一组代码。MCP 接口也使用此名称，表示相同概念以及它独有的两项：DRY_RUN 和 GIT_COMMITTED，CLI 不会发出这两项（提交成功时 CLI 不会返回任何信息）。参见 MCP 结果。

warning 是另一个字段，并且因接口而异——在所有情况下都是单独的字符串，但在具有此字段的两个接口中含义不同：

• 在线看板的在线 --edit 负载中的服务器透传字符串；以及
• 验证接口中页面范围的 vibeflow verify <id> <tool> --json 结果里的捕获截断说明（truncated:true 结果会包含 warning，解释视图为何不完整）。 因此，warning 永远不是对象，也永远不表示“部分成功”：消费者按 notices[].code 分支时，不会被它绊住。

tasks --commit --json 还会携带 autoPush: {attempted, ok, error?}。自动推送在两种模式下都会运行——--json 会抑制进度输出，但绝不会阻止推送——因此机器消费者可以通过此字段获知推送结果，而不是从文字说明中读取。attempted: false 表示没有新内容需要推送：已有提交已关联，或设置中已关闭 autoPush。即使推送失败，仍会返回 ok:true 和退出码 0，因为提交本身已成功写入；失败的推送可以单独重试。

自 0.18.0 起的破坏性变更：tasks --json 以前返回一个裸数组，--get --json 返回一个扁平对象，成功负载使用 success:true 而非 ok:true；即使任务已写入，自动提交失败仍会以退出码 1 退出。本地提示字段是 notices（数组），而不是 warning。

vibeflow verify <id> 只收集页面健康状况证据（元素可解析，且没有新增控制台错误）；它不会设置判定结果。Agent 会判断正确性，并在将任务移至 review 时通过 --set-verify 进行确认——pass（实现正确）、fail（不正确，会阻止进入 review），或 cannot 搭配 --verify-reason（在此处无法验证，会记录在任务的活动记录中）。

**任务类型：**Task · Bug · Feature · Enhancement · Research
**任务状态：**backlog → todo → in-progress → review → done
**优先级：**Critical · High · Medium · Low

同步存储安全：.vibeflow 存储由 Git 跟踪并在多台机器间同步——存在未解决的合并冲突时，切勿对其运行 git add -A。仍包含冲突标记（<<<<<<< / ======= / >>>>>>>）的任务文件无法解析，因此 CLI 会将其隔离，任务也会悄然从所有列表中消失。规则是：解决合并冲突、拉取、验证，然后再添加。预提交钩子会运行 pnpm check:store（每个 .vibeflow/tasks JSON 文件都必须能解析且不含冲突标记；如检查失败，会显示问题文件的路径），而 tasks --normalize 会明确报告无法解析和已隔离的记录，而不是将其丢弃。隔离记录也绝不会悄无声息：每次运行 pull、list 和 push 都会各输出一条警告，说明数量和首个原因（输出到 stderr，并在使用 --json 时写入封装中的 notices）——这是警告，不是失败，因此退出码仍为 0。

vibeflow telemetry

vibeflow telemetry              # show current status
vibeflow telemetry --disable    # opt out of usage tracking
vibeflow telemetry --enable     # opt back in

绝不会收集个人身份信息（PII）。用户身份会经过哈希处理。

**收集内容。**每次调用会记录一个 command_run 事件，并附带少量粗粒度属性：

• command — 顶层命令（tasks、serve、kanban……）
• subcommand — 对包含子命令的命令，表示其运行模式：tasks 会记录 list / get / add / edit / next / reindex，serve 会记录 api（仅 API 的任务服务）或 prototype（提供了 HTML 目标）
• from_status / to_status — 仅用于 tasks --edit：编辑前后的任务状态，取值自 backlog | todo | in-progress | review | done，因此可将状态转换作为漏斗进行查询

绝不会收集：任务 ID、标题、描述、文件路径、选择器、URL 或任何其他任务内容。

---

浏览器叠加层

该叠加层是一个注入任意页面的 Shadow DOM 面板——适用于 HTML 原型或线上应用：

• 点击添加注释 — 点击任意元素即可打开任务表单，并预填 CSS 选择器、URL 和源位置
• 任务侧边栏 — 列出未完成的任务并显示状态徽标；点击即可跳转到添加注释的元素
• 任务指示标记 — 在添加注释的元素上显示编号标记
• 实时同步 — 通过 WebSocket 和实时文件监视实现
• 截图捕获 — 通过叠加层将截图附加到任务
• 深色主题 — 精致的深色 UI，无需配置
• 键盘快捷键 — 按 Alt+A 切换注释模式
• 兼容 CSP 的注入 — 书签脚本可绕过 script-src 限制

注入方法

可通过以下三种方式将覆盖层注入任意页面：

方法	最适用于	CSP 安全
书签脚本（推荐）	任意页面，包括生产环境应用	是
脚本标签	你可以控制 HTML 的页面	否
DevTools 控制台	快速进行一次性会话	是

访问运行中的服务上的 /inject，即可获取可直接使用的书签脚本和代码片段。

---

工作原理

You browse your app  →  click to annotate  →  task created with context
          ↑                                         ↓
    browser reloads  ←  agent implements  ←  vibeflow tasks --next

1. 覆盖层 — 将书签脚本或脚本嵌入应用，点击任意元素即可添加注释
2. 看板 — 打开看板，一览所有任务，也可直接创建新任务
3. 任务 — vibeflow tasks --next 会为你的 Agent 选出优先级最高且上下文完整的任务
4. 迭代 — Agent 完成实现，浏览器重新加载，再次添加注释

---

Agent 集成

Vibeflow 任务为 AI Agent 提供了完整上下文：

• CSS 选择器 — 精确定位元素，无需猜测
• 源代码位置 — 元素定义所在的文件、行和列
• 屏幕截图 — 附加到任务的视觉上下文
• 评论 — 每项任务均可进行串联讨论
• 文件附件 — 研究报告、规格说明和参考资料
• Git 提交 — 通过提交信息中的 [proto:task-id] 将更改关联回任务

Agent 也可以直接从看板运行，调用 POST /api/agent/run，并在完整任务上下文中启动 opencode。

---

API

http://localhost:3700 提供 REST API 和 tRPC 路由器，供集成和浏览器覆盖层使用。主要端点：

• /kanban — 实时看板
• GET/POST /api/tasks — 列出和创建任务
• GET/PATCH/DELETE /api/tasks/:id — 管理单个任务
• GET/POST /api/tasks/:id/comments — 任务评论
• GET/POST/DELETE /api/tasks/:id/files — 文件附件
• POST /api/agent/run — 为任务启动 AI Agent
• /inject — 覆盖层注入辅助页面

完整 API 请参阅 src/server/server.ts。

---

贡献

pnpm install          # install dependencies
pnpm build            # build CLI
pnpm test             # unit tests
pnpm test:integration # integration tests (verify flow across a temp project)
pnpm test:e2e         # end-to-end tests
pnpm test:browser     # Playwright browser tests (kanban board, overlay)
pnpm test:coverage    # unit coverage only
pnpm test:coverage:e2e  # unit + e2e coverage MERGED (see below)

test:browser 需要先安装一次浏览器：npx playwright install chromium。

变更必需检查

每个测试套件只能通过自己的脚本运行——没有脚本会运行其他套件——因此，pnpm test 通过并不代表 e2e、集成测试或浏览器测试也通过。提交变更前，请运行所有测试：

命令	覆盖内容
pnpm run lint:symbols	对 packages/*/src/** 运行 ESLint
pnpm --filter @vibeflow-tools/cli run lint	tsc --noEmit
pnpm run test	单元测试
pnpm run test:integration	集成测试（验证流程）
pnpm run test:e2e	端到端测试（将 CLI 作为子进程启动）
pnpm run test:browser	浏览器测试（Playwright）——任何 UI 变更都必须运行
pnpm run build	为发布的 CLI 打包 tsup

前 3 项以及 build 是 pre-commit 钩子运行的检查。集成测试、e2e 和浏览器测试不在钩子中，因此只有这份列表能告诉你它们是否被跳过。

test:coverage 报告进程内单元测试执行的内容。对于这个包来说，这并不能说明全部情况：src/index.ts 几乎完全负责命令分发，而这些命令由 e2e 套件测试。该套件会将 CLI 作为 子进程 启动，v8 覆盖率无法跟踪这个子进程——因此，尽管数百条 e2e 断言都经过了 src/index.ts，它的行覆盖率仍只有约 16%。test:coverage:e2e 修正了这一测量方式：它会将带有源映射且未压缩的 CLI 构建到 .coverage-cli/（发布的 bundle 已压缩，且其源映射会被删除，因此无法将覆盖率归因到 src/**），然后通过 NODE_V8_COVERAGE 使用该 CLI 运行 e2e 套件，转换并重新映射子进程计数器，最后按源码位置将它们与单元测试计数器合并到 coverage/merged/（text、json、lcov）。它会在 stdout 上输出 src/index.ts 的单元测试独有、e2e 独有和合并后的覆盖率数据。合并工具链已经作为 @vitest/coverage-v8 的传递依赖存在；没有向 package.json 添加任何内容。

---

许可证

Apache-2.0 — 第三方归属信息请参阅 NOTICE。