multica-cli

Multica CLI

以本地 multica CLI 为准。本技能用于教外部 Agent 如何安全地使用 Multica；它不会授予权限。权限仅来自用户安装的 CLI、所选配置、工作区，以及用户明确批准运行命令。

安全启动

1. 开始工作前，确认 CLI 和账户状态：

multica version
multica auth status
multica config show

此技能要求使用 multica v0.4.26 或更高版本。 它依赖的多个命令（尤其是 issue status / assign / update 中的 --no-start）在更早版本中不存在，旧版 CLI 会直接拒绝这些参数。如果 multica version 报告的版本低于 0.4.26，请停止并要求用户升级（使用 brew upgrade multica-ai/tap/multica 或 multica update），不要尝试绕过缺失的标志。

如果 multica auth status 报告没有活动会话，说明 CLI 尚未登录。请停止并让用户进行身份验证；不要尝试伪造凭据：

multica login        # interactive auth + workspace setup
multica setup        # alternative: configure CLI, authenticate, start daemon

2. 使用正确的工作区和配置。先查看可用选项；如果用户指定了工作区或配置，优先使用显式标志：

multica workspace list --output json                 # which workspaces exist
multica workspace switch <workspace-id>              # set the default for this profile
multica --profile <profile> --workspace-id <workspace-id> issue list --output json

3. 只要命令支持，就优先使用 --output json。应解析 JSON，而不是抓取表格内容。

4. 切勿泄露或存储令牌、Cookie、API 密钥或 CLI 配置中的机密。不要通过直接调用私有 HTTP API 来绕过工作区权限。

命令参考

以下标志是最常用于问题工作流的通用标志。你无需对这些标志运行 --help。仅在确认某个被拒绝的标志或探索形态各异、此处未重复列出的长尾命名空间时，才运行 --help。[ ] 表示可选标志；| 表示互斥选项。

# Read
multica issue get <id> --output json
multica issue list [--status <s>] [--assignee <name> | --assignee-id <uuid>] [--project <id>] [--priority <p>] [--metadata key=value] [--sort <col>] [--direction asc] [--limit N] [--offset N] --output json
multica issue search <query> [--include-closed] [--limit N] --output json
multica issue children <id> --output json
multica issue pull-requests <id> --output json
multica issue metadata list <id> --output json

# Comments (read) — see Reading Comments below before picking a mode
multica issue comment list <id> --roots-only --summary --compact --output json   # scan threads cheaply
multica issue comment list <id> --thread <comment-id> --tail 30 --compact --output json  # open one thread
multica issue comment list <id> --recent N --compact --output json               # N most active threads
#   also: --since <RFC3339>, --full (unfold resolved threads),
#         --before/--before-id <cursor> for pagination

# Create / update
multica issue create --title "..." [--description-file <path>] [--priority <p>] [--status <s>] [--assignee <name> | --assignee-id <uuid>] [--parent <id>] [--stage N] [--project <id>] [--due-date YYYY-MM-DD] [--start-date YYYY-MM-DD] [--attachment <path>] [--attachment-id <uuid>] [--allow-duplicate] --output json
multica issue update <id> [--title "..."] [--description-file <path>] [--status <s>] [--priority <p>] [--assignee <name> | --assignee-id <uuid>] [--parent <id> | --parent ""] [--stage N] [--due-date YYYY-MM-DD] [--start-date YYYY-MM-DD] [--no-start]

# Status / assignment  (status values: backlog | todo | in_progress | in_review | done | blocked | cancelled)
multica issue status <id> <status> [--no-start]
multica issue assign <id> --to <name> | --to-id <uuid> | --unassign [--no-start]

# Comment (write) — body always via file, see Write Workflow below
# --parent is required when a comment triggered your task; see Issue Comments
multica issue comment add <id> [--parent <comment-id>] --content-file <path> [--attachment <path>]

# Metadata
multica issue metadata set <id> --key <k> --value <v> [--type string|number|bool]
multica issue metadata delete <id> --key <k>

# Labels — issue label add/remove take a label UUID, so list the workspace labels first
multica label list --output json
multica issue label list <issue-id> --output json
multica issue label add <issue-id> <label-id>
multica issue label remove <issue-id> <label-id>

# Custom properties (workspace-defined fields)
multica property list --output json
multica issue property list <issue-id> --output json
multica issue property set <issue-id> --name <name> --value <v>
multica issue property unset <issue-id> --name <name>

# Subscribers (who gets notified; defaults to the caller)
multica issue subscriber list <issue-id> --output json
multica issue subscriber add <issue-id> [--user <name> | --user-id <uuid>]
multica issue subscriber remove <issue-id> [--user <name> | --user-id <uuid>]

# Runs — see Inspecting Runs below
multica issue runs <issue-id> --output json
multica issue run-messages <task-id> [--issue <issue-id>] [--since N] --output json
multica issue usage <issue-id> --output json
multica issue rerun <id> --output json
multica issue cancel-task <task-id> [--issue <issue-id>]

请注意，issue assign 使用 --to / --to-id，而 issue create / issue update 使用 --assignee / --assignee-id。

其他命名空间的结构也相同；任务需要时再查看：

multica project --help
multica agent --help
multica squad --help
multica runtime --help
multica repo --help
multica skill --help
multica autopilot --help
multica attachment --help
multica label --help
multica property --help
multica chat --help
multica user --help

阅读评论

评论历史是最耗令牌的阅读内容，而且不同读取模式不可互换。

• --recent N 限制的是主题串数，而不是评论数，且每个主题串都包含其所有后代。如果问题的根主题串少于 N 个，此命令会返回完整历史，并非轻量读取。
• 建议分两次进行有界读取：先用 --roots-only --summary 扫描（每个根主题串还会报告 reply_count 和 last_activity_at），然后仅使用 --thread <id> --tail N 打开相关主题串。
• 对任何 JSON 读取添加 --compact。它会移除回显字段、空值和记账字段，同时保留内容不变——这始终适用于 Agent 读取。
• 已解决的主题串默认会折叠。 完整主题串模式会将已解决的主题串折叠为根评论和结论，并在根评论中报告省略的数量。这不代表数据丢失；只有在确实需要查看已结束的讨论时，才传入 --full。

multica issue comment list <issue-id> --roots-only --summary --compact --output json
multica issue comment list <issue-id> --thread <comment-id> --tail 30 --compact --output json

查找内容

multica issue search 会搜索标题、描述和评论正文，因此即使某项决定只存在于主题串中，也仍然可以找到。在断定某项内容不存在之前，请先尝试搜索。

multica issue search "retry backoff" --include-closed --output json
multica issue list --metadata pr_number=123 --output json

单独的数字或符合标识符格式的查询（412、AGE-412）会匹配编号相同的问题；前缀不会经过验证——粘贴来自其他跟踪器的标识符，可能会让一个无关的本地问题排在最前面。match_source 字段只是用于显示的提示，不是筛选条件。

写入工作流

将写入视为会产生副作用的操作。如果用户没有明确要求执行写入，请先询问再运行。这包括创建评论或问题、更改状态、分配任务、重新运行、取消、修改标签和属性、提及 Agent 或小组、更改 Webhook 或自动驾驶设置，以及仓库检出操作。

文件路径必须位于工作目录内

--content-file、--description-file 和 --attachment 不接受当前工作目录以外的路径。这是有意为之：这样可以避免误将来自其他运行或环境的旧文件静默读取。请将文件写入当前工作目录，不要写入 /tmp 或共享路径，否则命令会失败。

# correct: relative to the working directory
multica issue comment add <issue-id> --parent <comment-id> --content-file ./reply.md

--allow-external-file 可覆盖此检查。仅当用户明确指定了那个外部路径时才使用它，切勿用它来绕过尚未查明原因的失败。

问题评论

对于 Agent 撰写的评论，请始终将正文写入 UTF-8 文件，并通过 --content-file 传入。对于结构化评论，请勿使用内联 --content：在 CLI 接收内容之前，shell 可能会改写反引号、$() 表达式、变量、引号和换行符。

# Create reply.md with real newlines first, then:
multica issue comment add <issue-id> --parent <comment-id> --content-file ./reply.md
rm ./reply.md

--parent 是有条件要求的，并非总是必需。如果评论触发了你的任务，就必须提供此参数——服务端会拒绝此类任务提交的顶级评论，且其值必须是你正在回复的评论。如果你要在问题中发起新的顶级讨论，则省略此参数。切勿为了满足参数要求而将回复附加到无关的讨论串。

不要用字面量 \n 转义序列伪造换行。

问题和元数据

较长的问题描述请使用文件：

multica issue create --title "..." --description-file ./description.md
multica issue update <issue-id> --description-file ./description.md

如果存在未关闭的重复问题，issue create 会拒绝创建新问题。不要不假思索地使用 --allow-duplicate 重试——请先阅读现有问题，并确认用户确实需要再建一个。

元数据是持久的问题状态，不是日志。进入时请读取元数据，但只写入具有高信息价值、后续运行会再次读取的事实，例如 pr_url、pr_number、pipeline_status、deploy_url、external_issue_url、waiting_on、blocked_reason 或 decision。

multica issue metadata set <issue-id> --key pr_url --value <url>
multica issue metadata delete <issue-id> --key stale_key

元数据是每个问题各自的自由格式键值对。自定义属性则有所不同：它们是工作区定义的类型化字段，在各个问题间共享；创建或归档属性定义属于管理员级别的变更——可以设置属性值，但除非有人提出要求，否则不要改动定义。

使用 --no-start 抑制 Agent 运行

默认情况下，issue status、issue assign 和 issue update 可能会将新的 Agent 运行加入队列——这是交接工作的方式。如果你只是记录已经在进行中的工作的负责人或进度，那么额外运行只会浪费资金并造成重复执行。

multica issue status <id> in_progress --no-start
multica issue assign <id> --to <name> --no-start
multica issue update <id> --status in_review --no-start

简单规则：将新工作交给某人时 → 省略此参数；记录已经在进行的工作时 → 传入 --no-start。

提及的副作用

提及链接会触发操作，不只是装饰：

[@Name](mention://agent/<agent-id>)     # enqueues that agent
[@Name](mention://squad/<squad-id>)     # enqueues the squad leader
[@Name](mention://member/<user-id>)     # NOTIFIES that person
[@all](mention://all/all)               # broadcasts to the workspace
[MUL-123](mention://issue/<issue-id>)   # renders an issue link
[Name](mention://project/<project-id>)  # renders a project link

其中有三种会触达他人。agent 和 squad 会将 Agent 工作加入队列并产生费用；member 会通知一位人工成员，@all 会通知整个工作区。只有 issue 和 project 是不带副作用的链接，可以自由使用。

在构建提及之前，请先通过 JSON 输出查找真实的 UUID：

multica agent list --output json
multica squad list --output json
multica workspace member list --output json

不要只是为了致谢、回应或结束对话而提及 Agent。在回复中再次提及 Agent 可能会触发新的运行并造成循环。对成员也应保持克制：只有在需要他们采取行动时才提及，而不是出于礼貌。

状态和分配的副作用

状态变更并非表面操作，它们可能会启动或停止工作。

• backlog 会将已分配给 Agent 的问题搁置。
• 将 backlog 移至 todo 或其他活动状态可能会启动受派者。
• done 和 cancelled 是终止状态。
• 在 PR 或人工审核等待处理期间，in_review 很有用，但它仍然会写入状态。
• 可在不启动运行的情况下记录上述任何状态——请参阅上文的 --no-start。

为有顺序要求的工作创建子问题时，请使用阶段，并将后续步骤设为 backlog。只有当某个阶段中的所有子问题都完成后，才会唤醒父问题的受派者：

multica issue create --title "Research" --parent <id> --assignee <agent> --stage 1 --status todo
multica issue create --title "Build" --parent <id> --assignee <agent> --stage 2 --status backlog
multica issue children <id> --output json

检查运行记录

当问题看起来卡住或结果令人困惑时，请查看执行历史记录，而不是根据评论猜测。

multica issue runs <issue-id> --output json                       # what ran, and how it ended
multica issue run-messages <task-id> --issue <issue-id> --output json  # what that run actually did
multica issue usage <issue-id> --output json                      # aggregated token cost

--issue 允许你传入较短的任务 ID 前缀，而不是完整的 UUID。

有两项操作会造成实质性影响——请先向用户确认：

multica issue rerun <id> --output json          # re-enqueue the current assignment as a new task
multica issue cancel-task <task-id> --issue <issue-id>   # interrupt a running agent mid-flight

cancel-task 会中断正在运行的 Agent，导致进行中的工作丢失。切勿在尚未查看状态时运行它来“清理”状态。

拉取请求

针对 Multica 问题进行代码更改时，请在 PR 标题、正文或分支中包含可路由的问题键，以便 Multica 将其关联起来。

MUL-123: fix login redirect

仅当合并 PR 应关闭问题时，才使用关闭意图：

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

请从 Multica 读取关联 PR 的状态，而不是根据 GitHub 搜索结果或元数据猜测：

multica issue pull-requests <issue-id> --output json

CLI 无法完成的操作

CLI 未涵盖 Multica 的所有功能。当你需要的命令不存在时，请明确说明这一点，指出具体步骤，并告知用户前往 Multica Web 完成操作。切勿让未完成的运行看起来像已完成，也不要尝试使用 curl 或私有 HTTP API 来弥补缺口。

如实报告实际情况：运行了哪些命令、哪些命令成功，以及还需要用户完成哪些操作。被拒绝或执行失败的命令也是需要报告的结果，而不是绕过的问题。

外部 Agent 的边界

外部 Agent 不会自动获得 Multica 运行时上下文。如果用户要求处理某个具体问题或评论，请获取或推断以下信息：

• 问题 ID 或问题键
• 触发评论的 ID 和父级讨论串（如果要回复）
• 预期的工作区/配置文件（如果配置了多个）
• 是否允许写入
• 是否允许提及用户、更改状态、重新运行或分配任务

如果缺少上述任何信息，且操作会写入状态，请先询问再继续。对于只读调查，请使用 JSON 输出收集上下文，并说明还需要哪些信息。