开发者
Claude 与 MCP
Claude 在 VentionDesk 中像员工一样工作：领取任务、完成任务并反馈——权限恰好等同于所给密钥的权限。VentionDesk 为此不运行自己的模型，也不收取任何费用：自带 Claude 即可（Claude Code，配合您的 Claude 订阅或 Anthropic 密钥）。
有两种方式：MCP 服务器——推荐用于 Claude Code——以及直接使用 API，例如从自己的脚本调用。不用密钥也可以：每个人都可以用自己的登录连接 Claude、ChatGPT、Cursor 或 Codex——参见 连接 AI 应用。
1. 创建代理密钥
设置 › API 密钥 › “新密钥”，类型选 “代理”：
- 权限： 处理任务需要
projects:read、tasks:read和tasks:write；如果 Claude 要创建笔记，需要notes:write；如果要记录运行，需要agent:run。工单、回复客户、发票和报价单草稿、错误、工时、关键指标、路线图和想法，只在明确需要时才开启（见下文）。 - 项目： 全部，或仅限 Claude 要处理的项目。
- 过期时间： 建议 365 天。
密钥（vd_live_…）只显示一次。紧接其下是 “连接 Claude” 卡片，内含带有密钥的现成命令。
工单、回复、财务和报告——由您决定
默认情况下，代理密钥看不到工单、错误、工时和关键指标，不给任何客户写信，也不触碰发票、报价单、路线图或想法。这些权限范围需要按密钥逐一自行开启——在创建时，或之后在密钥列表的 “权限” 中。表单会说明每项权限开启后密钥可以做什么。
| 权限范围 | 开启后密钥可以做什么 |
|---|---|
tickets:read | 读取其项目的工单，包括历史记录、姓名、电子邮件地址和截图。读取的内容会传给录入该密钥的 AI 服务——为此需要与其服务商签订数据处理协议（Art. 28 DSGVO）。 |
tickets:write | 创建工单，撰写内部备注和回复草稿。这些内容都不会发给客户。 |
tickets:reply | 通过电子邮件回复客户——立即发送，无人事先审阅。与“发送回复”方式相同：您的发件人、您的页脚、同一邮件会话。每条回复都始终附有由 AI 助手撰写的提示。每小时最多 20 条回复，每个工单每天最多 3 条。需要 tickets:read。 |
invoices:write | 在其项目中创建发票草稿——也可根据未计费工时创建——并修改其明细。定稿、发送、冲销和付款仍由您处理；这一点由数据库强制执行，而不仅仅是界面。 |
quotes:write | 在其项目中创建和修改报价单草稿，维护其明细并可再次删除。发送（以及由此产生的编号）、接受、拒绝和将报价单转为发票仍由您处理。 不会为没有客户记录的潜在客户创建报价单。 |
errors:read | 从错误追踪器读取其项目的错误：标题、级别、状态、事件数和受影响用户数、时间、链接。不含堆栈跟踪，也不含错误追踪器的访问凭据。 |
errors:write | 将未解决的错误标记为已解决——先在错误追踪器中标记（使用错误来源的访问凭据），成功后才在 VentionDesk 中标记。如果凭据只有读取权限，错误保持未解决，Claude 会收到原因。如果错误再次出现，则视为回归（铃铛中显示“错误再次出现”，超过阈值后创建新任务）。隐藏和删除仍由您处理。需要 errors:read。 |
time:read | 读取其项目的工时记录：日期、时长、描述、任务、是否可计费和是否已计费、人员姓名。不含小时费率，不含金额。 员工的姓名因此会传给 AI 服务。 |
stats:read | 其项目用于报告的关键指标：进度、各状态的任务数、未解决和逾期的工单、路线图、监控、部署、未合并的拉取请求。不含营收、预算和成本。 |
roadmap:write | 读取、创建、重命名、移动、排序其项目的路线图阶段并将其勾选完成——下一个未完成的阶段即驾驶舱中的里程碑。删除仍由您处理。 |
ideas:write | 创建新想法，关联其某个项目或（在“所有项目”下）不关联项目。读取、修改和删除仍由您处理——包括它自己创建的想法。 |
在工单的历史记录中，代理发出的每条回复都标有 “由 AI 发送” 和密钥名称。
2. 连接 Claude Code
安装 Claude Code 并登录，然后在项目文件夹的终端中执行：
claude mcp add --transport http ventiondesk https://api.ventiondesk.com/mcp --header "Authorization: Bearer vd_live_…"将 vd_live_… 替换为您的密钥——或直接从“连接 Claude”卡片复制命令。随后 Claude Code 通过 HTTP 与 VentionDesk 的 MCP 服务器通信（POST https://api.ventiondesk.com/mcp，无状态）。服务器接受代理密钥和 已连接 AI 应用 的登录凭据；拒绝在浏览器中登录的人员的令牌。
之后直接问 Claude 即可：“VentionDesk 里有哪些未完成的任务？”或“接下项目 shop 中的下一个任务。”
3. 工具
MCP 服务器提供 38 个工具。每个工具都用您的密钥调用 API——因此工具可以做什么，由密钥决定。缺少权限范围时，工具会返回权限不足。
| 工具 | 作用 |
|---|---|
ventiondesk_list_projects | 列出密钥可以看到的项目，可按状态筛选。 |
ventiondesk_get_project | 按 slug 获取项目——包括代码仓库、分支、技术栈和任务数。 |
ventiondesk_list_tasks | 列出任务，可按项目、状态以及当前是否可领取筛选。 |
ventiondesk_get_task | 获取任务，包括描述、反馈、项目背景，以及按需提供的图片。 |
ventiondesk_claim_next_task | 按 runner 的规则认领下一个未完成的任务并完整显示。 |
ventiondesk_claim_task | 认领任务——原子操作，两次运行绝不会拿到同一个任务。 |
ventiondesk_report_task_result | 反馈任务状态，并据此设置任务状态。 |
ventiondesk_create_task | 为工作中发现的问题创建新任务（标题至少 25 个字符）。 |
ventiondesk_start_run | 开启一次运行，认领和结果都记录在其名下。 |
ventiondesk_finish_run | 以状态和一行总结结束运行。 |
ventiondesk_list_tickets | 列出项目的工单。 |
ventiondesk_get_ticket | 获取工单，包括其历史记录。 |
ventiondesk_add_ticket_note | 在工单历史记录中写一条内部备注。 |
ventiondesk_draft_ticket_reply | 创建客户回复的 草稿——不会发送。 |
ventiondesk_send_ticket_reply | 通过电子邮件向客户发送回复——仅限 tickets:reply。 |
ventiondesk_list_invoice_drafts | 列出密钥所属项目的发票草稿。 |
ventiondesk_get_invoice_draft | 获取发票草稿，包括明细。 |
ventiondesk_create_invoice_draft | 在项目中创建发票草稿。 |
ventiondesk_invoice_from_unbilled | 将项目的未计费工时转为草稿，每个条目一个明细。 |
ventiondesk_add_invoice_position | 向草稿添加明细。 |
ventiondesk_update_invoice_position | 修改草稿的明细。 |
ventiondesk_delete_invoice_position | 从草稿中删除明细。 |
ventiondesk_list_quote_drafts | 列出密钥所属项目的报价单草稿——仅限 quotes:write。 |
ventiondesk_get_quote_draft | 获取报价单草稿，包括明细。 |
ventiondesk_create_quote_draft | 在项目中创建报价单草稿；收件人为项目的客户。 |
ventiondesk_update_quote_draft | 修改报价单草稿的标题或有效期。 |
ventiondesk_delete_quote_draft | 删除报价单草稿——它还没有编号。 |
ventiondesk_add_quote_position | 向报价单草稿添加明细。 |
ventiondesk_update_quote_position | 修改报价单草稿的明细。 |
ventiondesk_delete_quote_position | 从报价单草稿中删除明细。 |
ventiondesk_list_project_errors | 项目中未解决的错误——仅限 errors:read。 |
ventiondesk_resolve_error | 在错误追踪器和此处将未解决的错误标记为已解决——仅限 errors:write。 |
ventiondesk_list_time_entries | 项目的工时记录，不含费率和金额——仅限 time:read。 |
ventiondesk_get_project_report | 用于报告的项目状态，不含金额——仅限 stats:read。 |
ventiondesk_list_roadmap | 项目的路线图阶段——仅限 roadmap:write。 |
ventiondesk_create_roadmap_phase | 创建路线图阶段。 |
ventiondesk_update_roadmap_phase | 修改、排序阶段或将其勾选完成。 |
ventiondesk_create_idea | 创建新想法——仅限 ideas:write。 |
没有 tickets:reply 时，Claude 将回复准备为草稿，由人工发送。没有用于定稿、发送或支付发票的工具，也没有用于发送、接受或拒绝报价单、隐藏或删除错误、删除阶段，或读取、修改和删除想法的工具。
4. 反馈
Claude 对每个任务都以六种结果之一反馈：
| 反馈 | 显示为 | 效果 |
|---|---|---|
arbeitet | 仍在处理 | 进度更新。任务保持“进行中”。 |
kontrolle | 需要审核 | 已实现并交付。状态为“待审核”（审核列）；需要证据。 |
frage | 待您答复 | 提问。状态为“待答复”；在有人回答之前，任务不会再被领取。 |
master | 需所有者处理 | 交给所有者，不改变状态——例如 Claude 无权执行的步骤。 |
blockiert | 受阻 | 无法继续。任务保持“进行中”，由人来处理。 |
erledigt | 已完成 | 完成。状态为“已完成”；需要证据。 |
对于“待答复”“需要审核”“需所有者处理”和“受阻”，在任务详情视图中以批准或驳回作答——参见 任务与看板。之后任务回到 Claude 手中。
像 /aufgaben 一样完成一轮，无需文件系统（浏览器或应用中的 Claude）：只需说“Work on the next open VentionDesk task”。Claude 会领取下一个任务——与 runner 的选择规则相同——读取描述、包括驳回在内的历史记录以及项目（仓库、线上地址、看板链接），仅在需要时获取截图（withAttachments，最多三张、每张 1 MB，其他文件以链接提供，有效期一小时），带凭证反馈结果并结束这一轮（领取、反馈和结束运行见上表）。Claude 会把领取时得到的 runId 传给反馈和结束；30 分钟没有心跳的运行会被标记为超时。
Claude 只领取未分配或已分配给 Claude、且不处于“搁置”“待审核”或“已完成”状态的任务。Claude 已失败达到允许次数的任务（默认三次尝试，可通过 maxAttempts 调整），VentionDesk 不再提供；人工的每次答复都会重置计数器。
5. 将提交关联到任务
如果提交说明中包含这一行
VentionDesk-Task: <task ID>
VentionDesk 就会将该提交关联到任务——前提是 GitHub 已连接 且项目中填写了代码仓库。ID 是任务的 UUID，即 API 和工具返回的那个。
6. 不用 MCP：任务 runner 和 API
如果让 Claude 或其他工具在不使用 MCP 的情况下工作，它会直接使用相同的端点：
- 开始运行（可选，权限范围
agent:run）：POST /v1/agent/runs；工作期间调用POST /v1/agent/runs/:id/heartbeat，结束时调用POST /v1/agent/runs/:id/finish。一段时间内没有存活信号的运行会被标记为已中止。 - 领取：
GET /v1/tasks?projectSlug=<slug>&claimable=true，然后POST /v1/tasks/:id/claim。 - 反馈：
POST /v1/tasks/:id/result，带上state（arbeitet、kontrolle、frage、master、blockiert、erledigt）、summaryMd、detailsMd，使用kontrolle和erledigt时在evidence中附上证据。 - 新建：
POST /v1/tasks。
VentionDesk 自身为此使用一个由无依赖 Node 脚本组成的小型任务 runner（pull.mjs 领取，push.mjs 以 --state 反馈，create.mjs 创建，finish.mjs 结束运行），通过环境变量 VENTIONDESK_API_KEY 和 VENTIONDESK_API_URL 控制。它没有作为软件包发布；对于 Claude Code，上面的 MCP 方式更简单。
所有端点及其参数：API 参考。