跳至正文
projektraum
打开演示开始项目

文档

逐步掌握Projektraum

从首次邀请到审核成果，为客户、项目团队和已连接的AI代理提供实用指南。

快速开始

项目空间集中管理与客户的协作，看板用于整理空间内的工作。

  1. 创建项目空间

    在仪表板中为客户或项目创建空间，使用清晰的名称，例如“网站改版”。

  2. 选择看板

    用看板管理状态列，用项目板管理表格与分区，用日历管理日期，用时间线管理时间段。一个项目空间可以包含多个看板。

  3. 邀请客户

    客户通过个人邀请链接访问，无需注册账户。在项目设置中指定权限，只把邀请链接交给指定收件人。

  4. 确认第一个任务

    创建包含目标、负责人和日期的任务。客户可以在有权访问的项目空间回答问题并审核成果。

任务与协作

任务描述具体成果，评论记录讨论，状态展示进展。

  1. 描述工作

    说明需要实现什么，以及如何判断完成。添加负责人、优先级和日期，小步骤可使用清单。

  2. 把问题留在任务中

    用评论讨论问题和成果，输入@时选择正确的人。提及会出现在对方通知中，邮件取决于其设置。

  3. 展示进度

    把任务移动到相应状态列。每个看板都能调整列。审核或明确收到完成说明后，再标记完成。

文件与项目知识

共享资料放在项目空间，任务专用资料放在相关任务中。

  1. 按上下文保存

    在文件区域上传共同使用的说明书。任务专用文件直接放在任务中或作为评论附件上传。

  2. 标明版本

    使用“首页-v2.pdf”这样的清晰名称，并在评论中说明改动。客户批准适用于提出请求时的内容。

  3. 让AI客户端读取

    获得授权的MCP客户端能列出并下载文件。能否读取PDF或Office内容取决于客户端能力，Projektraum不会自动提取正文。

何时使用哪种工作流？

各部分解决不同的项目需求，不必在每个任务中都使用全部功能。

  1. 请求转为任务

    粘贴文本，或在本地将TXT/Markdown读入请求框，添加目标、清单和日期。准备操作会用第一行作标题并补充问题。加入看板前请审核草稿，这不是自动文档分析。

  2. AI指派到审核结果

    为指定MCP连接明确授权清晰的工作。运行中的代理领取后汇报进度、障碍或成果。审核结果后再结束指派。

  3. 客户批准到决定

    请客户审核具体版本，批准与修改要求都保留在任务中。批准不会自动把任务设为完成。

  4. 规则与报告

    看板规则执行优先级、分配等受支持的操作。报告展示进展和待决事项，客户只能看到已向其共享的报告。

两个具体客户项目

看看下一步由谁负责，以及需要保留哪些信息。

  1. 网站：新增电话字段

    Marc希望增加选填电话字段。Lara确认移动端行为和验收标准后创建任务，必要时授权运行中的代理处理，审核结果并请Marc批准，然后决定是否结束工作。

  2. 设计：调亮产品图片

    Sina指定两张图片和所需改动。Lara确认版本，亲自修改文件并重新申请批准。修改要求和决定留在任务中，无需AI代理。

  3. 演示展示什么

    引导示例解释交接过程，示例数据与操作都留在演示中，不会启动真实工作或发送消息。

网站：新增电话字段体验示例设计：调亮产品图片体验示例

设置MCP

MCP把AI客户端连接到指定项目空间，客户端只能使用获授权范围内的数据和工具。

  1. 创建连接密钥

    项目所有者进入AI/MCP设置并选择空间，受邀客户可在自己的项目空间设置中找到连接。为每个客户端创建名称清晰的独立密钥。

  2. 选择权限

    选择只读或读写。写权限允许在账户权限内评论和修改任务。完整密钥只显示一次，请妥善保管。

  3. 测试连接

    按下方配置客户端，然后询问：“显示Projektraum中的未完成任务和我的未读提及。”先确认返回的是正确项目。

  4. 管理访问

    在设置中撤销不用的密钥，更换过期密钥。每个连接都可以选择简短或详细的评论风格。

MCP服务器地址

https://projektraum.io/api/mcp

只使用一种认证方式。不要把密钥放进聊天、URL或Git仓库。 prk_…只是占位符，请替换成创建时仅显示一次的完整密钥，而不是只填写前缀或省略号。

Claude

创建自定义连接，填入服务器地址并选择“No sign-in”。在Request headers中选内置x-api-key，只填完整prk_密钥，不要创建OAuth客户端ID。

URL: https://projektraum.io/api/mcp
x-api-key: prk_…

如果账户没有可用的请求头选项，可使用Claude Code。若已保存的头无法编辑，请用正确配置重新创建连接。

官方指南
Codex

把配置加入~/.codex/config.toml。PROJEKTRAUM_API_KEY只保存密钥，且必须传入正在运行的Codex进程。

[mcp_servers.projektraum]
url = "https://projektraum.io/api/mcp"
bearer_token_env_var = "PROJEKTRAUM_API_KEY"

Codex自动添加Bearer，终端变量不会自动传给单独启动的桌面应用。通过/mcp或MCP连接界面检查。

官方指南
Claude Code

把配置合并到工作项目的.mcp.json，并在启动Claude Code的环境中设置PROJEKTRAUM_API_KEY。

{
  "mcpServers": {
    "projektraum": {
      "type": "http",
      "url": "https://projektraum.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PROJEKTRAUM_API_KEY}"
      }
    }
  }
}

保留现有mcpServers条目。Claude Code启动时替换变量占位符。批准项目配置后，用/mcp检查或重新连接。

官方指南
ChatGPT

当前Projektraum集成不支持ChatGPT Web中的受保护直接连接。ChatGPT需要OAuth，而此集成采用API密钥。

prk_密钥不是OAuth客户端ID或secret。“No authentication”不会绕过服务器认证，现有集成可以使用Codex。

官方指南

核对日期：2026年10月31日

开发者与代理参考

端点采用Streamable HTTP，先调用tools/list获取当前密钥可用的工具和最新参数定义。

  1. 修改前先读取

    get_project返回看板、列和成员，get_task与list_comments提供任务上下文。使用响应中的ID和状态键，不要猜测。列表支持limit和offset。

  2. 安全重试

    写操作需要新的UUID request_id，重试时复用相同ID和不变参数。任务更新时，将get_task返回的task.updated_at值传为expected_updated_at，冲突时重新读取并核对差异。

  3. 说明和提及

    append_task_description保留原文并追加，update_task中的description替换整个说明。评论为纯文本，@加准确成员名创建提及。list_notifications读取通知，mark_notification_read另行标为已读。

  4. 文件和代理指派

    list_files返回文件ID和source，get_file给出60秒有效的私有下载URL，过期后重新获取。list_agent_jobs、claim_agent_job和update_agent_job管理指派，遵守claim token及lease限制，review必须附上结果证据。

排查问题

从具体错误入手，仅保存连接不会启动电脑上的代理。

  1. 连接或认证失败

    检查HTTPS地址、完整密钥、有效期及是否撤销。x-api-key只填密钥；Authorization使用Bearer、一个空格和密钥，不加引号，不同时发送两种头。

  2. 能读但不能写

    检查连接写权限及当前项目权限。归档或受限项目可能阻止修改，不要为了绕过错误而扩大权限。

  3. 更新后缺少工具

    刷新客户端工具列表或重新连接，必要时新建聊天。Claude的连接菜单可能提供刷新选项，CLI连接可以通过/mcp或重启重新连接。

  4. 代理没有自动响应

    代理必须运行并主动查询通知或指派。MCP提供项目访问，不是自动启动服务。一次提及不等于授权在电脑上执行任意操作。