Mosaic CLI 文档
EN

学习路径

从最简单到复杂（一步一步）

这是完整教学主线。按阶段顺序执行。每个阶段都有目标、命令和完成判定。

运行模式：示例统一使用 --project-state，状态落在当前项目 .mosaic/。

阶段 0：环境与安装校验

mosaic --version
mosaic --help
mosaic --project-state directory --ensure --check-writable

完成判定：CLI 可执行，状态目录可写。

阶段 1：首个 provider 初始化

export OPENAI_API_KEY=<your_key>

mosaic --project-state --profile default setup \
  --base-url https://api.openai.com \
  --api-key-env OPENAI_API_KEY \
  --model gpt-4o-mini

完成判定：setup 成功，配置文件已生成。

阶段 2：连通性与模型基线

mosaic --project-state --profile default models list
mosaic --project-state --profile default models status
mosaic --project-state --profile default health
mosaic --project-state --profile default status

完成判定：models list 返回有效模型，health 无阻断错误。

阶段 3：首个对话链路

mosaic --project-state --profile default ask "hello"
mosaic --project-state --profile default chat
mosaic --project-state session list
mosaic --project-state session show <session_id>

完成判定：至少一个 ask 与一个 chat 会话已记录。

阶段 4：多 profile（Azure 示例）

export AZURE_OPENAI_BASE_URL="https://<resource>.openai.azure.com/openai/v1"
export AZURE_OPENAI_API_KEY="<your_key>"

mosaic --project-state --profile az-openai setup \
  --base-url "$AZURE_OPENAI_BASE_URL" \
  --api-key-env AZURE_OPENAI_API_KEY \
  --model gpt-4o-mini

mosaic --project-state --profile az-openai models list

完成判定：多个 profile 可以独立工作。

模块详解：Models 与 Profiles。

阶段 5：通道与通知

mosaic --project-state channels add --name local-terminal --kind terminal
mosaic --project-state channels list
mosaic --project-state channels test <channel_id>
mosaic --project-state channels send <channel_id> --text "stage-5-ok"

完成判定：至少一个通道 test/send 都成功。

模块详解：Channels 教程。

阶段 6：网关生命周期

mosaic --project-state gateway install --host 127.0.0.1 --port 8787
mosaic --project-state gateway start
mosaic --project-state gateway status
mosaic --project-state gateway probe
mosaic --project-state gateway call status

完成判定：probe 与 call 返回成功状态。

模块详解：Gateway 教程 与 Gateway Call API。

阶段 7：安全策略与门禁

mosaic --project-state approvals get
mosaic --project-state approvals set confirm
mosaic --project-state approvals allowlist add "git status"

mosaic --project-state sandbox get
mosaic --project-state sandbox set standard
mosaic --project-state sandbox explain --profile standard

完成判定：审批与沙箱策略符合预期。

模块详解：Approvals 与 Sandbox。

阶段 8：日常可观测

mosaic --project-state dashboard
mosaic --project-state doctor
mosaic --project-state logs --tail 120
mosaic --project-state system presence

完成判定：dashboard/doctor/logs 输出可用于日常运维。

会话管理参考：Sessions 教程。

阶段 9：Agents 模块入门

mosaic --project-state agents list
mosaic --project-state agents add --name Writer --id writer --set-default --route ask --route chat
mosaic --project-state agents show writer
mosaic --project-state ask --agent writer "summarize this repo"

完成判定：自定义 agent 能创建并用于 ask/chat。

阶段 10：高级检查与发版门禁

mosaic --project-state memory index --path .
mosaic --project-state knowledge ingest --source local_md --path docs --namespace knowledge --incremental
mosaic --project-state knowledge search "retry" --namespace knowledge
mosaic --project-state security audit --path . --deep
mosaic --project-state --json status
  • 核心命令链路可用：setup/models/ask/chat/session。
  • 主通道与网关健康。
  • 策略与诊断输出稳定。
  • --json 输出可被脚本解析。

回归说明：回归测试教程。

10 分钟上手 Models 与 Profiles Sessions 教程 策略教程 Agents 专项 Channels 教程 Memory 教程 Knowledge 教程 Plugins 教程 Skills 教程 Gateway 教程 Gateway Call API 生产运维 回归测试教程