mcpField
B
basecamp

basecamp

github.com/basecamp生产力29488 次安装今天更新
代码仓库

关于 basecamp

Basecamp CLI 是一项技能，为使用已安装的 Basecamp 命令行工具制定安全、先查命令的操作规则，面向处理 Basecamp 任务的 Agent，涵盖命令帮助、范围、结构化输出和错误恢复。

主要功能

  1. 01通过定向帮助发现命令
  2. 02选择明确的结构化输出模式
  3. 03遵循项目和账户范围
  4. 04处理 URL、回复和提及
  5. 05按安全规则恢复错误

适用场景

  1. 01为 Basecamp 任务确定合适命令
  2. 02为 Agent 工作流提取结构化结果
  3. 03在正确的项目上下文中发布内容
  4. 04根据错误提示恢复命令执行

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/basecamp/basecamp-cli --skill basecamp

安装后在 Claude Code 中输入/basecamp确认已加载。

详细介绍

Basecamp CLI

使用已安装的 CLI 作为命令参考。本技能定义操作规则；有意不重复 CLI 的命令目录。

先探索再操作的工作流

对于每项任务：

  1. 根据用户的描述推断最具体、最可能的叶子命令。

  2. 如果本次对话中的工具结果尚未明确该命令的确切参数或标志，请直接检查该叶子命令：

    basecamp <group> <subcommand> --agent --help

  3. 如果叶子命令不存在，请检查最接近的父级命令组。只有在顶级命令组本身不明确时，才使用根帮助：

    basecamp <group> --agent --help   # fallback
basecamp --agent --help           # last resort

  4. 将叶子命令的 usage、args、flags 和 notes 视为事实依据。不要猜测位置参数、标志、别名、作用域，或某个命令组是否可以直接运行。

  5. 使用明确的输出模式执行命令，然后先读取结构化错误和操作线索，再决定下一步。

针对叶子命令的帮助信息成本低且范围有限；根帮助会返回完整命令目录，消耗的 token 也更多。不要只为确认本技能已记录的全局标志而加载根帮助。对于显而易见的 Docs & Files 请求，应直接使用 files list、files download 或 files uploads create，不要先尝试父级命令或根帮助。子命令的 inherited_flags 有意保持简短；全局标志（例如 --agent、--jq、--profile 和 --verbose）在受支持的情况下仍然适用。

不容违背的规则

  • 绝不读取、打印或记录 OAuth 令牌或凭据文件。尤其不要打开 ~/.config/basecamp/credentials.json。
  • 绝不将 JSON 通过管道传给外部 jq。请使用 CLI 内置的 --jq。
  • 使用 Basecamp URL 中的 ID 前，先解析 URL： basecamp url parse "<url>" --json。只信任来自已知 Basecamp 主机的 URL。叶子命令帮助明确接受 <id|url> 的只读命令，可以直接使用可信 URL。
  • 评论采用扁平结构。回复会发布到父级记录，而不是评论 ID。如果需要上下文，请对评论 URL 使用 comments show 或 comments thread 来获取 reply_target。
  • 尊重项目上下文。假定项目之前，先运行 basecamp config show --json：其 project_id 是综合标志、环境变量和所有配置层后生效的值，并会注明来源。不要直接读取 .basecamp/config.json；它只是其中一个配置层。如果没有 project_id，请传入 --in <project>，或使用叶子命令帮助所示的作用域。
  • 对 Agent 工作使用非交互式输出。不要让含糊不清的选择器阻塞执行。
  • 如果结果报告包含内容附件或描述附件，请下载并检查。图片通常包含任务的关键信息。
  • 移动到其他容器后，输出会显示该项目的新 ID；之后请使用新 ID，因为旧 ID 将无法再接受写入操作。复制操作会输出副本的 ID，并保留原件不变。绝不要重复复制：Basecamp 会在后台处理文件，因此仍在运行或未返回结果的副本可能已经存在。请使用 basecamp filings show <id> 命令或输出的提示检查副本，绝不要再次复制。
  • 优先遵循已安装命令的帮助信息，而非对早期 CLI 版本的记忆。

输出模式

请根据需要谨慎选择：

目标模式
提取、计数或转换数据--jq '<expression>'
使用完整的结构化响应--json
不带封装地使用数据--agent
直接向用户呈现可移植的输出--md

--jq 会启用 JSON。它通常会筛选 JSON 封装，因此数据通常位于 .data 下。与 --agent --jq 搭配使用时，它会筛选仅含数据的载荷。面向用户的列表请使用 --md，但请注意，仅使用 --md 并不会禁止交互式提示。请提供足够的作用域以消除歧义，或设置 BASECAMP_NONINTERACTIVE=1。

以下是通用转换示例，并非用于探索命令：

basecamp <leaf-command> --jq '.data | length'
basecamp <leaf-command> --jq '[.data[] | {id, name}]'

项目、账户和分页范围

不要根据命令中的名词推断它是针对项目还是整个账户。 请查看叶子帮助和其中的说明。如果用户明确提供了项目或账户，则使用该项目或账户；否则遵循可信的本地配置。

对于分页命令，在组合分页标志前先查看帮助。通常，--limit N 会限制自动分页结果的数量，--all 会遍历所有页面，而 --page N 会请求单个页面；但各个端点可能有所不同，互斥的组合会被拒绝。

命名身份使用配置档案。使用全局 --profile <name> 或 BASECAMP_PROFILE=<name> 选择一个配置档案；不要悄悄切换配置档案或默认账户。

URL 和回复

解析后的 URL 可提供 account_id、project_id、recording_id，如果片段指向评论，还可提供 comment_id。

basecamp url parse "https://3.basecamp.com/123/buckets/456/todos/789" --json

回复时，先获取可用于回复的上下文，而不是向片段 ID 发布内容：

basecamp comments thread "<comment-url>" --json
# Post to .data.reply_target.recording_id

只需获取便于回复的目标和提及标记时，使用 comments show；需要查看周围讨论时，使用 comments thread。

Pings

Ping 是账户内人员之间的私人对话，不属于任何项目：两人之间是直接对话，多人则是群组对话。它不是项目聊天，因此 chat list --all 永远不会显示它。请使用 pings 命令组。

basecamp pings list --agent                  # your pings
basecamp pings start "Jane Smith" --agent    # open your ping with Jane, or start it
basecamp pings post "Jane Smith" "Lunch?" --agent
basecamp pings messages "Jane Smith" --agent
  • <ping> 可以是 ping ID、ping URL（/circles/<id> 或 /circles/<id>@<line>），也可以是人员。纯数字始终表示 ping ID，绝不表示人员 ID。
  • Ping 有消息后，pings list 才会显示它。刚发起的 ping 尚未列出；pings start 会显示它。
  • pings start 会复用已有内容：每人对应一个直接 ping，每组人员对应一个群组 ping，除非使用 --new-group。可用它查找已有的 ping。
  • pings messages 和针对某人的 pings show 会读取已有的直接 ping，绝不会发起新的 ping；如果尚无 ping，pings post 和 pings upload 会发起一个。
  • pings post 中的 @提及会在该 ping 的参与者中解析。
  • 消息 URL（/circles/<id>@<line>）可与 basecamp show 和 chat line 搭配使用；要编辑或删除此类消息，请对该 URL 使用 chat update 或 chat delete。
  • 通用记录命令不会更改 ping 中的任何内容：recordings trash、archive、restore 和 visibility，subscriptions add 和 remove，以及 spotlight 都会被拒绝（退出码 4）。在此处只能通过 subscriptions subscribe 或 subscriptions unsubscribe 更改自己的订阅。

Spotlight

Spotlight 会将记录卡片放入项目主页的 Spotlights 区域。它不是置顶：messages pin 只会将消息固定在消息板顶部。spotlight 是顶级命令，不属于任何记录类型的命令组；它接受消息、文档、文件、待办事项列表、待办事项、卡片、卡片列、签到问题、日程条目等的 ID 或 URL。unspotlight 会移除它，效果与在 Basecamp 中使用“Remove Spotlight”相同。

basecamp spotlight <id|url> --agent
basecamp unspotlight <id|url> --agent

项目壁纸

壁纸是显示在项目页面背景中的图片。projects wallpaper 命令组可为 --in/--project 指定的项目或配置的默认项目设置、调整布局和移除壁纸：

basecamp projects wallpaper set skyline.jpg --mode tile --in "<project>" --json
basecamp projects wallpaper mode fill --in "<project>" --json
basecamp projects wallpaper remove --in "<project>" --json
  • 人员和个人助手遵循项目编辑权限。共享 Agent 会被拒绝（403）；不要重试，也不要绕过此限制。
  • CLI 会在上传前检查文件大小和 MIME 提示；限制详见叶子帮助。服务器仍会执行图片验证。--mode 可设为 fill 或 tile；不指定时会保留当前模式。
  • 每条命令都会返回项目。.data.wallpaper 的格式为 {url, mode}；项目没有壁纸时该字段不存在。projects show 也包含同一字段。此 URL 需要身份验证，并会重定向到图片；它不是公开图片链接。

项目徽标

徽标是显示在项目名称旁边的图片，与项目壁纸分开。projects logo 命令组可为 --in/--project 指定的项目或已配置的默认项目设置或移除徽标：

basecamp projects logo set brand.png --in "<project>" --json
basecamp projects logo remove --in "<project>" --json
  • 可以编辑项目的人员和 Agent 可以更改其徽标。其他人会收到 403，而调用者无法查看的项目会返回 404；不要重试或绕过这两种拒绝。
  • CLI 会在上传前检查文件大小和 MIME 提示；具体限制请查看末级帮助。服务器端仍会执行图片验证。移除没有徽标的项目的徽标也会成功。
  • 每个命令都会返回项目。.data.logo 的值为 {url}；项目没有徽标时，该字段不存在。projects show 也会包含相同字段。此 URL 需要身份验证，并会重定向到图片；它不是公开图片链接。

内容与 stdin

命令帮助会说明内容参数和是否支持 stdin。标题通常为纯文本；富文本字段通常接受 Markdown，并可在文档说明的情况下使用 --format html 选择 HTML。若帮助显示的是位置参数，请勿臆测存在 --title、--body 或 --content 标志。

对于多行、非 ASCII 或对 Shell 敏感的内容，请在文档指定的内容位置传入 -，并通过管道提供 stdin：

printf '%s\n' 'First line' '' 'Second line' |
  basecamp <leaf-command> <other-args> - --json

管道内容绝不会被隐式读取。一次调用中只能有一个输入读取 stdin。请勿在可移植命令中使用 $'line 1\nline 2' 这类特定于 Shell 的 ANSI-C 引号。

富文本字段支持 Mermaid 图表。将源码放入语言标记为 mermaid 的围栏代码块中，Basecamp 就会向阅读帖子的人员显示图表。预览、邮件和导出内容会显示源码；源码无法解析的帖子也会显示源码。对于用图比文字更容易理解的流程、时序、时间线或结构，请使用图表。图表源码会跨越多行，因此请通过 stdin 传入：

basecamp messages create "Release flow" - --in "<project>" --json <<'EOF'
How a release reaches production:

```mermaid
flowchart LR
  Merge --> CI --> Staging --> Production
```
EOF

要嵌入视频、Dash 图表或其他 Basecamp 编辑器在粘贴链接时会嵌入的内容，请在 Markdown 内容中单独一行放置 URL。CLI 会向 Basecamp 请求嵌入内容并等待结果。Basecamp 无法嵌入的 URL 会保留为链接；句子、列表、引用或代码中的 URL 也一样。若要保留指向 Basecamp 可嵌入内容的链接，请写成 [title](url)。

basecamp cards create "Checkout latency" - --in "<project>" --json <<'EOF'
p99 since the deploy:

https://dash.37signals.com/widgets/abc
EOF

使用 --format html 时，系统不会自动为你嵌入内容：请运行 basecamp embeds create <url> --json，并将其 attachment 标签放入 HTML 中。

为确保提及结果一致，建议使用人员或评论结果中机器提供的提及语法，例如 [@Name](mention:SGID)。不同字段对提及功能的支持有所不同；请以末级帮助为准。

错误与恢复

结构化故障包含 error、code、retryable，通常还包含 hint。

  • 仅当 retryable 为 true 时才重试，并使用有限次数的退避策略。
  • retryable: false 表示没有明确的重试信号；已知判定结果和未分类故障都属于此情况。选择恢复方式前，请检查 code、error 和 hint，不要盲目重复相同的调用。
  • 对于用法错误，请查看叶级帮助，并提供其中指定的位置参数。
  • 如果 CLI 将命令或标志判定为未知，请先查看该命令组的帮助，确认当前用法。如果此技能中提到了该命令或标志，但帮助中没有，CLI 与此技能可能来自不同版本：basecamp doctor --json 会报告两者的版本。请向用户指出较旧的一方：如果较旧的是 CLI，请运行 basecamp upgrade；如果较旧的是插件，请更新插件。
  • 对于名称含糊不清的情况，请使用 ID，或补充缺失的项目／容器范围。
  • 诊断身份验证或连接问题时，请先使用 basecamp doctor --json 和 basecamp auth status --json，再更改凭据。
  • 进行任何登录恢复之前，请检查 oauth_type。agent 配置必须通过 CLI 提示中指定的 Agent／客户端凭据流程恢复；普通用户登录可能会替换 Agent 身份。

不要仅仅因为命令失败就擅自调用原始 API。请先查看相关帮助和错误提示。仅当 CLI 没有原生操作，且 API 路径和载荷已知时，才使用 basecamp api。

变更

更改 Basecamp 之前：

  1. 明确且无歧义地确定账户、项目、容器和条目。
  2. 查看叶级帮助，确认必需的位置参数以及可见性或通知行为。
  3. 仅进行用户要求的最小更改。
  4. 返回生成的 ID／URL，并概述所做的更改。

对于破坏性操作或范围较广的操作，如果命令提供试运行，请先预览；不要扩大用户要求的范围。

评论

支持 Markdown