如何用 Multica CLI 脚本化管理 workspace、issue 与 agent（含 profile 与 JSON 输出）-港品优选

如何用 Multica CLI 脚本化管理 workspace、issue 与 agent（含 profile 与 JSON 输出）

【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica

如果你的工作流里有一批重复动作——批量列出某个 workspace 的 issue、按状态筛选、创建 issue 并指派给 agent、为 staging 和 production 各连一个 Multica 实例——那么 Multica CLI（multica）提供的命令行接口就是为这种脚本化场景准备的。本文基于项目文档 Using the CLI 和 CLI and Agent Daemon Guide，给出一条可执行的脚本化路径：安装 CLI、连接服务器、用--output json拿到机器可读数据、用 workspace 解析规则控制命令作用域、用--profile隔离多环境。完成本文后，你可以把 workspace、issue、agent 的日常管理写进 shell 脚本或 CI，而不是每次都打开网页。

准备条件：安装 CLI 并连接 Multica 实例

脚本化的前提是机器上有一个能认证通过的multica。macOS / Linux 下文档给出的安装方式（任选其一）：

brew install multica-ai/tap/multica # 或 curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

Windows PowerShell 下：

irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex

安装后验证：

multica version

能打印版本号即安装成功。然后连接服务器：连 Multica Cloud 用multica setup；连自托管实例用：

multica setup self-host \ --server-url https://api.example.com \ --app-url https://app.example.com

setup会保存服务器地址、打开浏览器完成登录并启动 daemon。无浏览器的机器先在建 PAT（Web 端Settings → API Token），再用交互式粘贴方式登录，避免 token 进 shell history：

multica login --token

用multica auth status确认当前服务器、用户和 token 有效期。PAT 以mul_开头、有效期 90 天，剩余不足 7 天时会自动续期；一旦过期或被吊销，需要重新multica login（见 Authentication and tokens）。

先弄清 JSON 输出的默认行为，再写脚本

写脚本前先记住文档给出的两条默认规则，它们决定你在哪些命令上必须显式加--output json：

list类命令默认输出面向终端的 table；
get和create类命令大多默认输出 JSON。

显式指定时统一写成：

multica issue list --output json multica agent list --output json

文档明确建议：脚本应使用 JSON 输出，而不是去解析 table 文本。各命令支持的输出格式与分页参数以multica <command> --help为准。

另外两个脚本化相关的 ID 规则：

issue 用MUL-123这类 key 或完整 UUID，短 UUID 前缀不被接受；
其他资源的list命令默认打印可复制的短 ID，加--full-id输出完整 UUID。短 ID 有歧义时 CLI 会要求你补字符或给完整 UUID。

脚本化 workspace 管理

先列出你能访问的 workspace，拿到 slug 或 ID：

multica workspace list multica workspace list --full-id multica workspace list --output json

table 输出中当前默认 workspace 带*标记。切换默认值用：

multica workspace switch <slug> multica workspace switch <workspace-id>

switch会先校验你对该 workspace 有访问权，再写入当前 profile 的默认 workspace。multica workspace get不带参数时解析到当前默认 workspace，可以直接当作"我现在在哪个 workspace"的检查命令。

写脚本时最关键是 workspace 的解析顺序（优先级从高到低）：

命令上的--workspace-id <id>；
环境变量MULTICA_WORKSPACE_ID；
当前 profile 存储的默认 workspace（由workspace switch或login写入）。

CI 或无头环境下不想依赖任何已存储状态时，推荐显式传--workspace-id或设MULTICA_WORKSPACE_ID，例如：

MULTICA_WORKSPACE_ID=<workspace-id> multica issue list --output json

脚本化 issue 管理

以下是文档给出的 issue 常用操作路径，全部可以放进脚本：

# 查看与搜索 multica issue list multica issue get MUL-123 multica issue search "login failure" # 创建与更新 multica issue create --title "Fix login failure" multica issue status MUL-123 in_progress multica issue assign MUL-123 --to "Backend Agent" # 评论与执行记录 multica issue comment list MUL-123 multica issue comment add MUL-123 --content "Check the regression tests first" multica issue runs MUL-123

脚本里几个值得专门处理的点：

JSON 输出裁剪字段。--fields只在 JSON 输出下生效，用逗号分隔的白名单控制返回哪些顶层字段，字段名是真实 API key（例如 assignee 拆成assignee_type/assignee_id）：

multica issue list --output json --fields=id,title,status,priority

长文本从 stdin 读。描述和评论里有换行和引号时，用 stdin 而不是拼命令行：

multica issue create --title "Upgrade notes" --description-stdin < notes.md multica issue comment add MUL-123 --content-stdin < review.md

按 metadata 和自定义属性过滤。--metadata可重复、多条件之间是 AND，值会做类型嗅探（true/false变 bool，数字变 number，其余为 string；需要强制字符串时包一层引号如'"42"'）：

multica issue list --metadata pr_number=482 --metadata is_blocked=true multica issue list --property "Impact=High" --property "Impact=Medium" multica issue list --property "Impact=__none__" --status in_review

按 ID 指派避免重名。--to做成员/agent/squad 的模糊名匹配；名字重叠时用--to-id <uuid>，UUID 可以从multica workspace member list --output json/multica agent list --output json的返回里取：

multica issue assign MUL-123 --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d multica issue create --title "Fix login bug" --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d

状态命令的合法取值是：backlog、todo、in_progress、in_review、done、blocked、cancelled。

轮询运行进度。拿到 run 的 task ID 后（issue runs默认打印短前缀，--full-id出完整 UUID；短 task 前缀需要配--issue指定所属 issue），用--since做增量拉取：

multica issue run-messages <task-id> --output json multica issue run-messages <task-id> --since 42 --output json

脚本化 agent 管理

multica agent list multica agent list --output json multica agent get <agent-id>

新建 agent 时--name和--runtime-id是必填项（runtime 决定 agent 在哪台机器上用哪个 AI coding tool 执行）：

multica agent create \ --name "Frontend Reviewer" \ --runtime-id <runtime-id> \ --description "Reviews frontend pull requests" \ --instructions "Read the diff and tests first; post review conclusions only as issue comments."

<runtime-id>从multica runtime list的输出里取。可选参数还有--model、--thinking-level、--mcp-config、--permission-mode、--max-concurrent-tasks等。注意命令参数里的明文会留在 shell history，敏感内容（如自定义环境变量）应走 stdin 或权限受限的文件。

配置相似的 agent 不必重建，直接复制（原文档示例中的<agent-id>替换为你agent list拿到的 ID）：

multica agent copy <agent-id>

副本默认留在同一 runtime；跨 runtime 复制要同时给--runtime-id和--model。环境变量、MCP 配置和runtime_config永远不会被复制，需要在副本上用create时相同的 flag 重新提供。

已有 agent 的自定义环境变量（仅 owner/admin 可读写）：

multica agent env get <agent-id> multica agent env set <agent-id>

用 profile 隔离多环境

同一台机器要同时连 production 和 staging（或 Cloud 和自托管）时，用命名 profile 隔离一套独立的服务器地址、token、默认 workspace 和 daemon 状态：

multica setup self-host --profile staging \ --server-url https://api.staging.example.com \ --app-url https://staging.example.com multica issue list --profile staging

配置文件位置：默认 profile 在~/.multica/config.json，命名 profile 在~/.multica/profiles/<name>/config.json。查看当前值：

multica config show multica config show --profile staging

对应的 daemon 也按 profile 启动和查看：

multica daemon start --profile staging multica daemon status --profile staging --output json multica daemon logs --profile staging

每个 profile 有独立的日志、PID 和健康端口。daemon logs会先打印它解析到的日志绝对路径——多 profile 并存时不要凭猜测打开~/.multica/daemon.log。

配置解析的优先级链是：命令行 flag > 环境变量 >config.json> 内置默认值；config set传空字符串可清除已持久化的值，例如multica config set poll_interval ""。

验证与限制

跑完脚本后用这几条命令做端到端确认：

multica auth status multica daemon status --output json multica config show

auth status显示服务器、用户与 token 状态；daemon status --output json给出 PID、运行时长、检测到的 agent 和被监听的 workspace。如果连接层有问题，Troubleshooting 给出的第一组排查命令就是这四条：multica version、multica auth status、multica daemon status --output json、multica daemon logs --lines 100。

最后三条必须写进脚本约定里的限制：

配置文件含 token。CLI 配置里存的是能代表你访问 Multica 的 PAT，不要提交到仓库、上传日志或分享给他人。
不要在宿主机 shell / Compose 服务 / 容器 entrypoint 里设置MULTICA_DAEMON_PORT。宿主 daemon 会自己从--profile推导健康端口并向 agent 任务注入该变量；旧版本（0.4.22、0.4.23）在宿主机设了它会拒绝登录，新版本也会让普通 API 和 profile 解析命令保持 fail-closed 直到移除该变量。
agent 任务内的 CLI 是另一套上下文。当 CLI 运行在 daemon 托管的 agent 任务中时，它不读写人类的 profile 文件，改用 daemon 注入的任务级临时凭证（mat_前缀）认证；login、logout、setup、workspace switch、daemon start/stop/restart等人类命令在该上下文不可用。你的脚本如果运行在 agent 任务里，不要假设能--profile切换或改配置。

后续可以沿 Command reference 里的完整命令表扩展project、autopilot、label、skill等对象，每个命令支持哪些分页与输出参数以multica <command> --help为准。

【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析