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.json；否则传入 --in <project> 或叶子命令帮助中显示的作用范围。
• Agent 操作应使用非交互式输出。不要让有歧义的选择器阻塞执行。
• 如果结果报告了内容附件或描述附件，请下载并检查。图像往往包含任务的关键信息。
• 优先遵循已安装命令的帮助，不要依赖对早期 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。

私聊

私聊是账号内人员之间的私密对话，不属于任何项目：两个人之间是直接对话，人数更多时则是群组对话。它不是项目聊天，因此 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> 可以是私聊 ID、私聊 URL（/circles/<id> 或 /circles/<id>@<line>），也可以是某个人。单独的数字始终表示私聊 ID，而不是人员 ID。
• 私聊中有消息后，pings list 才会显示它。刚创建的私聊暂时不会列出；pings start 会打印它。
• pings start 会复用已有私聊：每个人对应一个直接私聊，每组人员对应一个群组私聊，除非使用 --new-group。可用它查找已有的私聊。
• 对某个人使用 pings messages 和 pings show，会读取已有的直接私聊，绝不会创建新私聊；如果私聊不存在，pings post 和 pings upload 会创建它。
• pings post 中的 @提及会在该私聊的参与者中解析。
• 消息 URL（/circles/<id>@<line>）可用于 basecamp show 和 chat line；也可在该 URL 上使用 chat update 或 chat delete 编辑或删除此类消息。

Spotlight

Spotlight 会将某条录制内容的卡片放到其所属项目主页的 Spotlights 区域。它不是置顶：messages pin 只会将消息固定在其 Message Board 顶部。spotlight 是顶层命令，位于所有录制类型命令组之外，可接受消息、文档、文件、待办事项列表、待办事项、卡片、卡片列、签到问题、日程条目等的 ID 或 URL。unspotlight 会移除 Spotlight，对应 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 需要身份验证，并会重定向到图像；它不是公开的图片链接。

内容和标准输入

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

对于多行、非 ASCII 或对 shell 敏感的内容，请在文档说明的内容位置传入 -，并通过管道传递标准输入：

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

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

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

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，并概述所做的更改。

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