# moo-cloud-cli **Repository Path**: charsen/moo-cloud-cli ## Basic Information - **Project Name**: moo-cloud-cli - **Description**: Moo Cloud 本地 CLI:云端问题/待办的身份校验与拉取 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-11 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # moo-cloud-cli 把本地代码仓库和云端项目连起来:查询异常和待办、附图建单、团队讨论、认领与完成回写,并给 Codex / WorkBuddy / DeepSeek Harness 等 AI 客户端提供 MCP 工具。 当前版本 **0.1.4**,业务能力对齐 cloud **0.1.42**。更新内容见 [更新记录](CHANGELOG.md)。 它解决三个具体问题: 1. **对不上号**:确认「这个本地目录」就是「云端那个项目」,防止 AI 改错仓库; 2. **取数**:把云端待处理的异常、慢 SQL、前端错误、App 错误、待办拉到本地,生成一份队列; 3. **给 AI 用**:把同一套云端能力包装成本地 MCP,让 AI 客户端直接调用。 > 它只负责「校验 + 取数 + 提供 MCP」,是否自动改代码由调用方决定。 --- ## 5 分钟上手 如果你只想先跑起来: 1. 从 [GitHub Releases](https://github.com/charsen/moo-cloud-cli/releases/latest) 或 [Gitee Releases](https://gitee.com/charsen/moo-cloud-cli/releases) 下载对应平台的文件; 2. 改名为 `moo-cloud`(Windows 为 `moo-cloud.exe`),加执行权限; 3. 把账号 token 存到 `~/.config/moo-fleet/mcp-token`; 4. 给 AI 使用时,执行 `moo-cloud agent-config --target=codex --write`(WorkBuddy 改用 `--target=workbuddy`),按第 8 节连接并调用 `list_projects`; 5. 需要关联本地仓库时,再配置 `.moo-cloud.json` 并执行 `moo-cloud preflight --offline`。 **只使用 MCP 不需要 `.moo-cloud.json`。** 它仅用于本地仓库预检,不负责连接或授权 MCP;DeepSeek Harness 的插件配置见第 8.3 节。 下面按步骤展开。 --- ## 1. 它适合谁 - 你有一批**本地代码仓库**,云端有一批对应的**项目**,想把两边关联起来; - 你希望 AI 能读取云端的问题/待办,但不想让它瞎猜「哪个仓库对应哪个项目」; - 你希望夜间或手动触发时,只处理「归你负责的类别」,不误关别人的问题。 不适合:只想看云端页面、不打算在本地跑命令的人。 --- ## 2. 准备什么 | 需要 | 说明 | |---|---| | 一台能运行命令的电脑 | macOS / Linux / Windows 都可以 | | `git` | 预检要读仓库状态;`git --version` 能输出版本即可 | | 一个 Moo Cloud 账号 | 默认地址 `https://c.mooeen.com`,自建实例可用 `--cloud` 指定 | | 一个**账号级 token** | 登录 cloud → 「个人 Token」→「生成 Token」 | token 有两种权限: - `mcp:read`:只读,够拉取问题/待办; - `mcp:write`:可创建待办、发表评论、解决异常和认领/完成待办;会自动包含读。范围与策略仍由 cloud 校验。 第一次用建议先生成只读 token。 --- ## 3. 安装 ### 3.1 下载 | 平台 | 下载文件 | |---|---| | macOS Apple Silicon(M1/M2/M3…) | `moo-cloud-darwin-arm64` | | macOS Intel | `moo-cloud-darwin-amd64` | | Linux x86_64 | `moo-cloud-linux-amd64` | | Linux arm64 | `moo-cloud-linux-arm64` | | Windows x86_64 | `moo-cloud-windows-amd64.exe` | | Windows arm64 | `moo-cloud-windows-arm64.exe` | Release 页同时提供 `SHA256SUMS`,可以校验下载是否完整。 ### 3.2 放到一个固定位置 建议放在用户目录下的固定位置,不要放在某个 git 仓库里(仓库重置/切分支可能把文件删掉): macOS / Linux: ```bash mkdir -p ~/.local/bin cp /path/to/downloaded/moo-cloud-darwin-arm64 ~/.local/bin/moo-cloud chmod +x ~/.local/bin/moo-cloud # 让当前 shell 找得到(写进 ~/.zshrc 或 ~/.bashrc 可持久) export PATH="$HOME/.local/bin:$PATH" # macOS 首次运行如果提示“无法打开/已损坏” xattr -d com.apple.quarantine ~/.local/bin/moo-cloud ``` Windows(PowerShell): ```powershell New-Item -ItemType Directory -Force "$env:USERPROFILE\bin" | Out-Null Copy-Item "$env:USERPROFILE\Downloads\moo-cloud-windows-amd64.exe" "$env:USERPROFILE\bin\moo-cloud.exe" # 把 %USERPROFILE%\bin 加进 PATH(当前用户,一次即可) [Environment]::SetEnvironmentVariable( "Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\bin", "User" ) ``` 新开一个终端,确认: ```bash moo-cloud --version ``` Windows 用 `moo-cloud.exe --version`(如果已在 PATH 里,`moo-cloud --version` 也可以)。 后文所有 `moo-cloud ...` 命令,在 Windows 上对应 `moo-cloud.exe ...`。 ### 3.3 从源码构建(开发者) ```bash git clone https://github.com/charsen/moo-cloud-cli.git cd moo-cloud-cli/go make dist # 输出到 ../dist/ go test ./... # 跑测试 ``` 需要 Go 1.22+。发布步骤和产物核对见 [构建与发布](docs/BUILD.md)。 --- ## 4. 配置 token token 只需要存一次,文件内容**只有 token 本身**。 macOS / Linux: ```bash mkdir -p ~/.config/moo-fleet printf '%s' '' > ~/.config/moo-fleet/mcp-token chmod 600 ~/.config/moo-fleet/mcp-token ``` Windows(PowerShell): ```powershell New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\moo-fleet" | Out-Null Set-Content -NoNewline -Encoding ascii ` -Path "$env:USERPROFILE\.config\moo-fleet\mcp-token" ` -Value '' ``` 也可以不用文件,改用环境变量 `MOO_CLOUD_MCP_TOKEN`。 > token 不要提交进任何仓库,也不要贴到聊天/日志里。 --- ## 5. 第一次运行 可以直接进入含 `.moo-cloud.json` 的软件仓库,也可以进入放着若干仓库的工作区,然后: ```bash cd /path/to/software-repo # 1) 只做本地与身份校验,不拉取 moo-cloud preflight --offline # 2) 校验 + 拉取异常队列 moo-cloud preflight --fetch # 3) 待办单独拉(默认类型不含 todo) moo-cloud preflight --fetch --types=todo --out=moo-cloud-reports/todos ``` 也可不切换目录,执行 `moo-cloud preflight --root=/path/to/workspace --offline` 批量检查工作区。扫描范围是指定目录本身、下一层和下两层目录;不会向上寻找配置,也不会无限递归。指向同一实际目录的符号链接只检查一次。 默认会在 `/moo-cloud-reports/<日期>/` 生成: | 文件 | 用途 | |---|---| | `_preflight.json` | 机器可读的校验结果 | | `_preflight.md` | 人读摘要:每个仓库、分支、脏文件、身份是否匹配 | | `_queue.json` | 待处理问题/待办(仅 `--fetch`) | | `_metrics.json` | 本次运行的耗时与条数(仅 `--fetch`) | 下一步:打开 `_preflight.md` 看每个仓库是否对上;再按第 8 节把 MCP 接进 AI 客户端。 ### 如果报「未找到任何 .moo-cloud.json」 先确认当前目录或 `--root` 是否正确。扫描包含该目录本身及下两层,每个要纳管的仓库根目录需要放一个 `.moo-cloud.json`,见第 7 节。 ### 配置错误怎么处理 报告会指出 JSON 格式错误的位置、类型不正确的字段、无效平台,或 `verify[0].file` / `verify[0].contains` 等具体指纹项。先检查字段拼写,再核对文件路径和包名;错误信息不回显指纹内容。 未识别字段只警告,不会单独阻止预检;缺少必需资料、字段值无效或指纹校验失败会记为硬失败,并返回非零退出码。已发现配置的校验失败仍会写入报告,并继续检查其余仓库;未找到配置或命令参数不合法时直接退出。现有配置不增加必填项,`platforms` 仍可省略。 App 的项目、身份校验结果及失败原因会同时显示在 Markdown 和 JSON 报告中;离线模式会明确提示未验证云端归属。后端的 Git 根目录与 marker 位置不匹配时,该仓库不再联网校验或进入队列;同仓库内只有某个环境失败时,其他通过校验的环境仍可拉取。失败环境不参与拉取目标的云端选择;多个已通过校验的云端仍需用 `--cloud` 指定目标。 报告中的本地 origin 和云端仓库 URL 会移除用户信息、查询串和片段,保留仓库位置供排错;比较仓库身份时同样忽略这些部分,不修改 Git 配置。 ### 如果报「app root 不存在或缺 artisan」 后端仓库的 marker 里 `root` 写的是 Laravel 应用所在子目录(常见是 `engine`)。如果没有子目录,写 `.`。 --- ## 6. 命令一览 | 命令 | 作用 | |---|---| | `moo-cloud preflight` | 身份校验 + 拉取问题/待办(主命令) | | `moo-cloud mcp-server` | 本地 stdio MCP 桥,给 AI 客户端用 | | `moo-cloud agent-config` | 生成/写入客户端的 MCP 配置 | | `moo-cloud todo add` | 记录一条云端待办(可选从问题生成;`--batch` 批量建单) | | `moo-cloud todo list` | 列出待办,可按状态/分页/个人处理范围/对账筛选(missing-note、done-by、日期区间) | | `moo-cloud todo show` | 查看单条待办详情、正文摘要与附件清单(含图文核对) | | `moo-cloud todo start` / `todo done` | 受理或完成待办并写回处理结果(done 必填 note) | | `moo-cloud issue list` | 列出异常(按类型/状态/分页/个人处理范围) | | `moo-cloud issue resolve` | 标记异常已解决(写根因/改动/分支 sha/验证) | | `moo-cloud audit` | 只读审计:done 无说明 / 逾期 open / 长期 in_progress / 疑似未关闭异常;`--summary` 只取云端汇总 | | `moo-cloud comment list` | 分页查询某条异常或 TODO 的讨论 | | `moo-cloud comment add` | 发表文字评论,与网页讨论共用数据 | | `moo-cloud --version` | 查看版本 | | `moo-cloud --help` | 查看子命令 | 每个子命令也支持 `--help`,例如 `moo-cloud preflight --help`。 --- ## 7. 核心概念 ### 7.1 云端项目 vs 本地仓库 cloud 项目用于协作和数据隔离,一个项目可包含多个软件;软件是检查更新、反馈和客户端异常的身份。一个软件可以对应多个本地仓库,一个仓库也可能服务多个项目(多环境/多客户)。 `.moo-cloud.json` 就是这张对照表,放在**仓库根目录**,供 `preflight` 预检使用。MCP 连接由账号 Token 和客户端服务器配置建立;`mcp-server` 不读取此文件,文件也不改变账号权限或自动限定工具调用的项目。 预检命令的 `--root` 可指向当前仓库或包含多个仓库的工作区,例如 `moo-cloud preflight --root=/path/to/workspace --offline`;扫描该目录本身及下两层目录。不传 `--root` 则使用当前目录,可在软件仓库内直接运行。这个命令参数与后端 marker 内的 `root` 用途不同。 ### 7.2 后端仓库 marker ```json { "role": "backend", "root": "engine", "deployments": [ { "project": "my-project", "env_file": ".env" }, { "project": "my-project-prod", "env_file": ".env.prod" } ] } ``` - `root`:Laravel 应用相对仓库根的目录;没有子目录写 `.` - `deployments[].project`:云端项目 slug - `deployments[].env_file`:从哪个 env 文件读 host token 校验方式:用该 env 里的 `MOO_MONITOR_CLOUD_TOKEN` 调云端 `/api/v1/summary`,返回的项目 slug 必须与 marker 一致。 ### 7.3 软件仓库 marker(App / 桌面 / Web) ```json { "role": "app", "product": "my-app", "project": "my-project", "platforms": ["android", "ios"], "verify": [ { "file": "android/app/build.gradle", "contains": "com.example.app" } ] } ``` App 默认模板只保留五类字段: | 字段 | 用途 | | --- | --- | | `role` | `app` 明确表示 App / 桌面 / Web 仓库 | | `project` | cloud 项目 slug,确定协作和数据归属 | | `product` | 该项目下的软件 slug,与客户端的 `app` 标识对应 | | `platforms` | 本仓库负责的平台,供报告和 Agent 区分多仓库;不会限制 MCP 权限 | | `verify` | 本地包名指纹:文件存在且包含指定字符串,防止认错仓库 | 同一软件可对应多个本地仓库:分别填写相同 `project`、`product`,用 `platforms` 和各自的 `verify` 区分。不要为了拆 Android / iOS 仓库而拆成两个软件。 App 分支不使用 `root`;本地 `identifiers` 也不参与 CLI 解析,因此默认模板不再填写。cloud 中已有的可选包名资料、仓库链接和现有配置仍保留;后端的 `root`、`deployments`、`env_file` 继续明确配置,不自动猜目录或环境文件。 维护已有 App marker 时,删除未使用的 `root`、`identifiers` 即可,保留原 `project`、`product`、`platforms` 和 `verify`。包名指纹仍通过 `verify[].contains` 校验;Cloud 软件的可选包名资料无需删除。此精简不修改后端 marker 的 `root`、`deployments` 或 `env_file`。 软件版本与安装包在 Cloud 后台维护,各仓保留自身构建说明;marker 不负责发版,不要向其中增加版本、文件、哈希、签名或发布 Token。 App marker 的 `project` 与 `product` 都必填。在线检查使用账号级 Token 调用 `list_apps`,确认软件属于该项目;通过后可独立拉取队列。`--offline` 仅检查本地指纹,不验证云端归属。 ### 7.4 token、范围、策略 - **token**:账号级,一枚覆盖你所有项目;`moo_mcp_` 开头 - **MCP 处理范围**:你在 cloud 里设置「哪些类别归我处理」;范围外的类别不会被自动拉取/回写 - **MCP 处理策略**:问题类可分 `auto`(自动解决)/ `confirm`(需人工确认)/ `hold`(保留不处理);默认 `auto` - **待办策略**:每条待办另有 `ai_policy`,同样是 `auto/confirm/hold` 范围与策略都在 cloud 页面设置,CLI 只读取并执行。 --- ## 8. 接入 AI 客户端 `moo-cloud mcp-server` 是一个本地 stdio MCP 桥:客户端只需要 `command + args`,token 和云端地址由桥自己读取。 本机工具与 cloud 使用相同的请求边界:`jsonrpc` 为 `2.0`,请求 `id` 为字符串或有符号 64 位整数(允许 `0`、空字符串)。非法 ID 不会触发本机更新或图片读取;无 ID 的通知不执行工具。 先生成配置(在目标电脑上执行,它会写入**当前二进制自身的绝对路径**): ```bash moo-cloud agent-config --target=codex --write moo-cloud agent-config --target=workbuddy --write moo-cloud agent-config --target=json # 只打印,给 Claude/Cursor 等 ``` 写入会保留其他客户端设置和 MCP 服务,并先备份原配置;配置文件是软链接时更新并备份真实目标,保留链接。断链或不可读的配置会报错,请先修复文件。 ### 8.1 Codex 1. 首次执行 `moo-cloud agent-config --target=codex --write`;已有配置需刷新只读工具白名单时加 `--force`; 2. 完全退出 Codex 再打开; 3. 验证: ```bash codex mcp list | grep moo_cloud codex exec --skip-git-repo-check "调用 moo_cloud 的 list_projects 工具,只回答项目数量" ``` 生成的配置会对 9 个只读工具自动批准(含 `list_comments`);`post_comment`、`resolve_issue`、`update_todo_status` 等写工具仍会请求人工批准。已有配置需重新生成并重连后才会更新白名单。 ### 8.2 WorkBuddy > WorkBuddy 5.11.2 实测可在 MCP 面板直接加载新配置;首次连接需要「信任」,然后确认连接已启用。 1. `moo-cloud agent-config --target=workbuddy --write --force` 2. 打开「专家·技能·连接器 → 连接器 → 自定义连接器」(部分版本入口叫「设置 → MCP」); 3. 找到 `moo-cloud`,首次连接点「信任」,确认已启用且显示工具数量; 4. 新建会话,输入「只用 moo-cloud 调用 list_projects」,以实际返回项目清单为准。 若面板看不到连接,或更新 CLI 后仍显示旧工具列表,再用 `Cmd+Q` 完全退出 WorkBuddy 后重开,并新建会话。无需每次写入配置都重启。 建议用上面的 CLI 命令合并配置,保留其他连接器。WorkBuddy 的「添加 MCP」编辑器保存的是整份 `mcp.json`,手工粘贴时须保留原有条目。 ### 8.3 DeepSeek Harness(DSH) DSH 通过 `@deepseek-ai/dsh-mcp-client` 插件加载,不使用 `mcp.json`。在 `~/.dsh/profiles/desktop/cordis.patch.yml` 末尾追加: ```yaml - insert: - id: mcp-moo-cloud name: "@deepseek-ai/dsh-mcp-client" config: serverName: moo-cloud transport: stdio command: "/path/to/moo-cloud" args: ["mcp-server"] toolCallTimeoutMs: 120000 ``` 注意:**新增插件必须放在 `- insert:` 里**;直接写 `- id:` 只会覆盖已有条目,不会加载新插件。 保存插件配置后 DSH 会重载;工具会以 `mcp__moo-cloud__list_projects` 形式出现。只替换 CLI 文件不会让已经运行的 MCP 进程自动更新,安装新版后仍需重连插件或完全退出 DSH 后重开。 DSH 会清掉子进程里匹配 `KEY|PASSWORD|SECRET|TOKEN` 的环境变量;桥默认读 token 文件,不受影响。 ### 8.4 Claude / Cursor 把 `moo-cloud agent-config --target=json` 的输出粘到对应客户端的 MCP 配置 (Claude Desktop 是 `claude_desktop_config.json`),重启客户端。 ### 8.5 手工验证桥 ```bash printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | moo-cloud mcp-server ``` 正常返回一行 JSON;报「缺少 token」时检查第 4 节。 --- ## 9. MCP 工具 带 `mcp:write` 的账号通过本地桥可使用云端工具(含只读 `audit_summary`、直传票据 `create_todo_image_tickets` 等)及 2 个本机更新工具(`check_cli_update`、`update_cli`)。**工具数量随 cloud 部署版本变化**——较旧的 cloud 可能没有 `audit_summary`、`create_todo_image_tickets`、`list_todos.mine/assignee_id` 等,以实际 `tools/list` 为准;对旧 cloud 相应功能会自动回退或提示。只读 Token 不暴露云端写工具;本机更新仍需用户明确同意,不能借 Token 权限跳过确认。 **给 Agent 的操作规范**(`mcp-server` 在 MCP 初始化时随 `instructions` 下发的要点,详见 cloud 版本文档): 1. **定位**:先 `list_projects` 拿项目清单、处理范围(handled_types)与策略(type_policies);批量看健康度先 `audit_summary`。 2. **读**:`list_issues --env` 取问题、`get_issue`/`get_issue_markdown` 看详情(markdown 省 token、已脱敏,末尾附团队讨论最近 20 条,更早用 `list_comments` 翻页);`list_todos --mine` 取我负责的待办、`get_todo` 看单条(markdown 同样附最近 20 条讨论)。 3. **领取**:开始处理待办前先 `update_todo_status` 置 `in_progress`(记录领取人),**不要默默处理**。 4. **读图**:待办有截图时,对 `get_todo.attachments` 中每个 `ai_readable=true` 的附件逐张 `get_todo_image` 读全现场,别只看第一张。 5. **写回**:修好并验证后 `update_todo_status` 置 `done` / `resolve_issue` 关闭异常;`note` 必填「根因+改动+分支 sha+验证」;以工具回执为准,**失败或超时不得宣称完成**。 6. **策略**:待办 auto 可受理+完成、confirm 只能受理、hold 不处理;异常 auto 才可 resolve;范围外类别 403;评论属讨论(confirm/hold 也可评论)但仍需用户同意。 7. **批量提交**:一轮测试/排查要建多条待办时,先编好报告文件(`{project, items:[{title, category, priority, description, images}]}`),用 CLI `todo add --batch= --dry-run` 校验图片路径与字段,确认后去掉 `--dry-run` 加 `--yes` 一次性提交;单条失败不打断其余,末尾汇总含每条 `todo_id`/是否去重/新增附件数。 8. **图文核对**:提交或补图用 `create_todo` 的 `image_paths` 直传现场截图;正文声称有截图时附件就必须真传到。用 CLI `todo show --project= --id=` 看回执与附件;正文提到截图却无附件、或有附件正文未提及时有意核对,**别当作已通过**。 9. **终端判定**:非交互环境(pipe/CI/无 TTY)所有写操作必须显式加 `--yes`;桥用真实终端判定(ioctl/GetConsoleMode),不会把重定向或字符设备误当可交互去代你确认。 | 工具 | 用途 | |---|---| | `list_projects` | 项目清单、待处理计数、有效处理范围、策略 | | `list_issues` | 按项目/类型列问题(可按 env 过滤) | | `get_issue` | 单条问题完整上下文(可选 payload;markdown 末尾附团队讨论最近 20 条) | | `get_issue_markdown` | 单条问题的 AI markdown(末尾附团队讨论最近 20 条) | | `list_apps` | 项目下的软件(AppProduct) | | `list_todos` | 待办列表(支持 missing_note/done_by/时间区间筛选) | | `audit_summary` | 只读对账汇总:done 无说明 / 逾期 / 长期 / 异常未关闭计数 | | `get_todo` | 待办详情(含附件;markdown 末尾附团队讨论最近 20 条) | | `get_todo_image` | 读取待办图片 | | `list_comments` | 分页查询异常或 TODO 的团队讨论 | | `post_comment` | 发表文字评论(需 `mcp:write`,先取得用户同意) | | `create_todo` | 记录待办并附图(需 `mcp:write`;`image_paths` 走七牛直传) | | `create_todo_image_tickets` | 为待办附图签发七牛直传票据(`create_todo` 自动调用,无需手调) | | `resolve_issue` | 标记问题已解决(需 `mcp:write`) | | `update_todo_status` | 受理/完成待办并保存完成结果(需 `mcp:write`) | **按场景选命令(CLI 直连,不经 MCP 时)**: | 想做什么 | 命令 | |---|---| | 看某项目健康度总览 | `audit --project=x --summary` | | 找「有完成但没写说明」的待办 | `todo list --project=x --status=done --missing-note` | | 看我名下要处理的待办 | `todo list --project=x --mine` | | 看某类异常(按环境) | `issue list --project=x --type=runtime --env=production` | | 领取/完成待办并写回 | `todo start/done --project=x --id= --note="…" --yes` | | 关闭已修复异常 | `issue resolve --project=x --type=… --key=<12位> --note="…" --yes` | | 本地多仓库预检+落盘 | `preflight --root= --fetch` | 写操作校验项目权限、处理范围和策略:`auto` 待办可受理及完成,`confirm` 待办仅可受理,`hold` 不可处理;解决异常仍需对应策略许可;发表评论不受 ai_policy(auto/confirm/hold 均可),但仍受处理范围与 `mcp:write` 约束。客户端的写操作审批继续生效。 使用本地 `mcp-server` 桥时,还提供两个本机工具(不发送到 cloud): | 工具 | 用途 | |---|---| | `check_cli_update` | 检查运行版本、本机安装版本和最新稳定版,不安装 | | `update_cli` | 用户明确同意目标版本后,下载、校验、备份并更新本机 CLI | --- ### 9.1 记录待办 除了拉取,也可以把发现的问题或后续事项记到云端项目: ```bash # 手动写一条 moo-cloud todo add --project=my-project --title="修复登录页报错" # 带截图,可重复 --image 指定多张 moo-cloud todo add --project=my-project --title="查询没有反应" \ --image="/absolute/path/screenshot.png" --image="/absolute/path/error.png" # 从一条问题生成标题/描述,并带上来源 moo-cloud todo add --project=my-project --from-issue=runtime:abcdef123456 # 指定类型/优先级/指派给项目成员,输出 JSON(自动化需 --yes) moo-cloud todo add --project=my-project --title="补充回归用例" \ --category=task --priority=high --assignee=dev@example.com --yes --json # 批量建单:一次提交一轮测试报告(先 dry-run 校验,再真写) moo-cloud todo add --batch=report.json --dry-run moo-cloud todo add --batch=report.json --yes ``` `report.json` 结构(`project` 可写在顶层对本批生效,单条也可覆盖;`images` 为图片绝对路径): ```json { "project": "my-project", "items": [ {"title": "部门会议详情 422", "description": "现象…证据…", "priority": "high", "images": ["/abs/a.png"]}, {"title": "部门筛选显示部门 ID", "category": "bug", "priority": "normal"} ] } ``` 批量模式逐条创建、单条失败不打断其余,最后输出汇总(含每条 todo_id、是否去重、新增附件数);任一条失败时退出码非 0。含未知字段会被拒绝,避免拼写错误静默生效。 规则: - 首次创建调用只返回项目确认信息,**不写库**;CLI 会显示项目名并询问 `y/N` - 非交互环境(脚本/AI)必须加 `--yes`,否则直接报错 - 需要 `mcp:write` - 同项目、同标题且未完成(`open` / `in_progress`)时复用已有待办,返回 `deduped: true`;带图时追加新图,相同图片不重复保存 - 支持 PNG/JPEG/WebP/GIF,最多 5 张图片(含已有图片),每张原始文件不超过 8 MiB(像素上限由云端校验);图片保存在 cloud 的私有附件区 - 图片无效或保存失败会报错,并回滚本次创建或补图;返回 `images_attached`(已处理的输入张数,含重复)、`images_added`(实际新增张数)和 `todo.attachments_count` - CLI 收不到完整图片保存回执时会报错;若错误带有待办 ID,先检查该记录附件,重试请保留相同标题与图片 - 新待办默认 `ai_policy=auto`;`--assignee` 可填 `me`(默认)或项目成员邮箱 - 免费项目待办配额满时拒绝新建,不会淘汰已有待办;相同标题的未完成待办仍可复用 - `--from-issue` 支持 `runtime` / `slow_query` / `frontend_error` / `app_error` Agent 通过本地 MCP 桥创建待办时,用 `image_paths` 传入截图的**绝对文件路径**,由 CLI 读取并上传: ```json { "project": "my-project", "title": "查询没有反应", "description": "选择筛选条件后,点击查询,列表未刷新。", "image_paths": ["/absolute/path/screenshot.png"] } ``` 首次调用返回项目预览与 `confirm_token`;确认后第二次调用保留相同参数和图片,再加上该令牌。默认走直传:CLI 先申请 `create_todo_image_tickets` 票据,把文件 multipart 直传七牛,再把 `upload_id` 放进 `image_upload_ids`;旧 `images` 数组 base64 仅在 `MOO_CLOUD_TODO_IMAGE_MODE=legacy` 时兼容(`auto` 也会在直传不可用时回退)。 图片上传模式由 `MOO_CLOUD_TODO_IMAGE_MODE` 控制:默认 `direct`(只直传,失败直接报错);`auto` 仅在云端不支持/未配置七牛时回退旧 base64;`legacy` 仅用于兼容旧 cloud。生产 cloud 已关闭旧通道,建议所有客户端保持默认 `direct`。 聊天附件不会自动进入工具参数。Agent 应把用户附图一起传入;如果客户端未提供可读的原图文件,应明确说明图片尚未上传。需要同时使用支持附图的 cloud 和 CLI,更新后重新连接 MCP 才会刷新工具参数。 ### 9.1.1 查看单条待办详情 ```bash moo-cloud todo show --project=my-project --id= moo-cloud todo show --project=my-project --id= --json ``` 展示标题、状态/优先级/分类、领取人与提交人、正文摘要(前 1500 字)、附件清单(id/类型/mime/大小/AI 是否可读)以及完成说明。附件区会做**图文核对**:正文声称带截图但实际无附件、或有附件但正文未提及时会给出提示,帮助发现「截图未随待办上传」的错位。 ### 9.2 受理待办与写回完成结果 Agent 使用已有 `update_todo_status` 工具,不需要创建确认令牌或增加本地配置。 开始处理时受理: ```json {"project":"my-project","id":"<待办 ID>","status":"in_progress","note":"已受理,开始检查查询事件和接口响应。"} ``` 完成并验证后,写回实际结果: ```json {"project":"my-project","id":"<待办 ID>","status":"done","note":"已修复查询按钮事件绑定,筛选条件正确传入接口。定向回归通过;尚未部署生产。"} ``` - 首次完成必须填写非空文字 `note`;受理时选填。完成结果保存为 `done_note`,连同 `done_by`、`done_at` 在 cloud 网页「处理结果」展示。 - 受理(`status=in_progress`)即领取:同时记录领取状态与领取人(已有经办人则保留);`mcp-server` 会在 MCP 初始化说明里提醒「开始处理先领取」,避免静默处理。 - 以成功回执中的状态和完成字段为准;调用失败时不能声称 cloud 已标记完成。 - 重复受理或完成不会重复追加事件、覆盖原结果或刷新完成时间;已完成重试可省略 `note`。重新受理已完成记录也不会把它重开。 - `list_todos` 传 `status=done` 可查完成记录及结果摘要(最多 500 字加省略号);`get_todo` 返回完整结果及时间线,AI markdown 也包含完成结果。 - 需要 `mcp:write` 且在处理范围内;`auto` 可受理及完成,`confirm` 只可受理,`hold` 不可处理。受理记录真实账号及说明,不覆盖人工指派。 上述结果回执需 cloud 部署对应改动后生效,再重连客户端刷新工具说明;现有 CLI 动态转发工具,无需为此重新安装二进制。 ### 9.3 检查与更新 CLI MCP 连接初始化时自动检查发布版本,成功结果缓存 24 小时。有新版或磁盘文件已更新、进程尚未重启时,桥会在 MCP 初始化说明中要求 AI 提醒一次。具体是否展示提醒取决于客户端;也可以直接说:“检查 moo-cloud CLI 是否有更新”,由 AI 调用 `check_cli_update`,手动检查会绕过缓存。 自动检查失败时,也会要求 AI 在会话开始时告知「尚未确认最新版」,业务工具继续可用。手动检查失败会保留已知的运行版本、安装版本和重连状态,并返回明确错误;不会把检查失败报告成「已是最新」。 发现新版后,AI 应先说明目标版本并询问是否安装。用户同意后才调用: ```json {"target_version":"0.1.5","confirm":true} ``` 这里的版本号是示例,以检查返回的实际版本为准。`update_cli` 是本机写操作,不加入自动批准白名单;`confirm` 是客户端根据用户明确答复传入的确认参数,不能代替客户端的用户审批。检查新版不会自行触发更新。 更新读取本项目的 GitHub Release,访问失败或限流时尝试 Gitee;不发送账号 MCP token。Gitee 未提供附件大小时仍可检查更新,实际下载须非空、不得超过 64 MiB,且必须通过官方 `SHA256SUMS`;有声明大小时还须一致。安装前会重新检查目标版本和二进制版本,再在原路径旁保存旧文件备份并替换。多个客户端共用同一文件时,只需更新一次。开发构建不自动覆盖,也不降级。 发布信息或附件下载失败都会尝试备用源,备用源必须提供用户确认的同一版本。更新期间用系统锁防止多个客户端同时替换;进程异常结束后锁自动释放。如果期间被其他方式安装了新文件,本次更新会停止并要求重新检查。 完成后**重新连接 MCP 或重启客户端**,已运行的进程继续使用旧版本。若 Windows 锁住正在运行的程序,或安装目录不可写,会保留原文件并提示手动更新;不会强行退出客户端。 升级后请在每个客户端分别调用 `check_cli_update`,核对 `running_version`、`installed_version` 和 `restart_required`。终端的 `moo-cloud --version` 只说明磁盘文件已更新,不能证明 Codex、WorkBuddy 或 DSH 的旧连接已重启;新建对话也不一定重启客户端共用的 MCP 进程。WorkBuddy 可在 MCP 面板停用再启用 `moo-cloud`;其他客户端重连服务,或完全退出后重开。 ### 9.4 查询与发表评论 沿用现有账号 Token 和 cloud 地址,无需修改 `.moo-cloud.json`。异常使用原有 key,TODO 使用原有 ID: ```bash moo-cloud comment list --project=my-project --type=runtime --key=abcdef123456 moo-cloud comment list --project=my-project --type=todo --id=01ARZ3NDEKTSV4RRFFQ69G5FAV --limit=20 --offset=0 --json moo-cloud comment add --project=my-project --type=runtime --key=abcdef123456 --body="已补充复现步骤" ``` `--type` 支持 `runtime`、`slow_query`、`frontend_error`、`app_error`、`todo`;异常只传 `--key`,TODO 只传 `--id`。查询按时间正序分页,有后续评论时返回 `next_offset`;下一次设置 `--offset`。已有附图返回数量,可在网页讨论查看。 发表文字需 `mcp:write`、有效处理范围(评论不受 ai_policy,confirm/hold 待办也可评论),正文为 1–5000 字。命令会询问确认;自动化调用需先获用户同意,再加 `--yes`。同账号、同记录、相同正文在 2 分钟内复用已有评论,避免重试重复评论或通知。已完成/已解决记录仍可讨论,不改变状态;删除或无权访问的记录不可操作。 MCP 中调用 `list_comments` / `post_comment`,参数为 `project`、`type`、`key` 或 `id`,发表时再传 `body`。写评论不加入自动批准白名单;本次只支持文字发表。cloud 部署评论工具后重连 MCP 获取新工具定义;本地 `comment` 命令需使用包含本轮功能的 CLI。 另外,`get_issue` / `get_issue_markdown` / `get_todo` 返回的 markdown 末尾已附团队讨论最近 20 条(时间正序、正文脱敏);需要全部或更早的评论时再用 `list_comments` 翻页查看。 ### 9.5 命令行闭环与审计 除 `todo add`、`comment` 外,命令行也能直接完成「受理/完成回写/关闭异常」与只读审计,便于脚本与 CI。 > **`preflight` 与 `audit` 的分工**:`preflight` 面向「本地仓库预检 + 按项目拉队列落盘报告」(`_queue.json`/`_metrics.json`,适合夜间巡检与交付留痕);`audit` 面向「云端对账」(done 无说明 / 逾期 / 长期 unfinished / 疑似未关闭异常,输出 Markdown/JSON,`--summary` 只取汇总)。两者都只读、互不改状态;日常看某个项目的健康度用 `audit`,核对本地多仓库基线用 `preflight`。 ```bash # 列出待办(默认 open+in_progress;--status=done 查完成;--mine 只看指派给我) moo-cloud todo list --project=my-project --status=done --limit=20 moo-cloud todo list --project=my-project --mine moo-cloud todo list --project=my-project --assignee=<人员ID> moo-cloud todo list --project=my-project --status=done --missing-note # 对账:done 无处理说明 moo-cloud todo list --project=my-project --created-before=2026-11-01 --done-by=alice # 受理 / 完成并写回处理结果(done 必填 --note:根因/改动/分支 sha/验证) moo-cloud todo start --project=my-project --id= --note="已受理,开始排查" moo-cloud todo done --project=my-project --id= --note="根因…;改动…;fix/x abc1234;回归通过" --yes # 列出异常(类型必填;--status 可选 open/in_progress/resolved;--env 按环境过滤) moo-cloud issue list --project=my-project --type=frontend_error --status=open moo-cloud issue list --project=my-project --type=runtime --env=production # 关闭异常(能力全集四类均可,是否放行由云端范围与策略决定) moo-cloud issue resolve --project=my-project --type=frontend_error --key=<12位key> \ --note="根因…;改动…;fix/x abc1234;验证…" --yes # 只读审计:不写云端、不改状态 moo-cloud audit --project=my-project,other-project --stale-days=7 --out=moo-cloud-audit.md moo-cloud audit --project=my-project --json moo-cloud audit --project=my-project --summary # 只取云端汇总,不翻明细 ``` > **两个维度,不能混**:`--type` 与审计默认覆盖的是**能力全集**(runtime / slow_query / frontend_error / app_error / todo 都可处理);每个使用者用账号默认 + 成员级项目设置(`ai_handled_types`)决定**自己处理哪些**,只影响本人、不改变能力全集。命令行默认按能力全集读写,只有显式 `--respect-scope` 才把读取收窄到「我的处理范围」。`frontend_error` 同样是可勾选的处理类别,若某账号未勾选只是个人设置,不是能力缺失。 `audit` 输出四类可疑项:已完成但无处理说明、open 且超期未处理、in_progress 且超期未完成、open 且长期未再出现(疑似已修复未关闭)的异常。需要 `mcp:write` 的写操作(start/done/resolve)在非交互环境必须加 `--yes`,并仍受云端处理范围与策略(auto/confirm/hold)校验。 - **免填 slug**:`audit`/`todo list` 省略 `--project` 时会从 `--root`(默认当前目录)及下两层的 `.moo-cloud.json` 自动取项目。 - **CI 门禁**:加 `--fail-on-findings`,发现违规时退出码为 2(区别于参数/网络错误的 1)。 - **截断告警**:命中 `--max-pages` 上限会显式提示「可能不完整」,不静默截断。 - **降本**:对支持新接口的 cloud,done 扫描走 `missing_note` 过滤、并可用 `audit_summary` 取汇总(旧 cloud 自动回退,不影响使用)。 CI / 定时示例(发现违规即失败): ```bash # GitHub Actions / cron 里: moo-cloud audit --root=/path/to/workspace --stale-days=7 \ --out=moo-cloud-audit.md --fail-on-findings || exit 1 ``` ```yaml # .github/workflows/audit.yml(示意,token 用 secrets 注入) name: moo-cloud-audit on: { schedule: [{ cron: "0 1 * * *" }], workflow_dispatch: {} } jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: | curl -fsSL -o moo-cloud https://github.com/charsen/moo-cloud-cli/releases/latest/download/moo-cloud-linux-amd64 chmod +x moo-cloud MOO_CLOUD_MCP_TOKEN="${{ secrets.MOO_CLOUD_MCP_TOKEN }}" \ ./moo-cloud audit --project=my-project --out=moo-cloud-audit.md --fail-on-findings - uses: actions/upload-artifact@v4 if: always() with: { name: moo-cloud-audit, path: moo-cloud-audit.md } ``` ## 10. 输出与可观测性 - 前端与 App 错误拉取会持续越过被过滤的开发/调试数据,直到达到 `--limit` 或读完;队列中的 `has_more / next_offset` 保留原始记录的续取位置,不能按过滤后的条数计算偏移量。 - `_metrics.json`:本次运行总耗时、每项目/类型的耗时与条数、跳过/错误 - `--metrics-log=`:每次运行追加一行 JSON,用于趋势 - `mcp-server --log=`:每次 MCP 调用一行(method/tool/ok/duration/error) --- ## 11. 常用参数 | 参数 | 说明 | |---|---| | `--root=` | 当前仓库或工作区目录,默认当前目录;扫描本身及下两层 | | `--date=YYYY-MM-DD` | 输出日期目录,默认上海当天 | | `--out=` | 输出目录 | | `--offline` | 跳过云端身份校验 | | `--fetch` | 拉取队列 | | `--types=` | 默认 `runtime,slow_query,frontend_error,app_error`;待办用 `todo` | | `--token=` | 覆盖 token(默认文件或环境变量) | | `--cloud=` | cloud 地址,默认 `https://c.mooeen.com` | | `--limit=` | 每类最多条数(1–50,默认 5) | | `--concurrency=` | 项目并发数(1–16,默认 4) | | `--json` | 输出机器可读的 preflight 结果 | | `--metrics-log=` | 追加指标日志 | 退出码:`0` 校验与必要输出成功;`1` 参数无效、任意仓库存在硬失败、缺 token、没有通过校验的仓库、整体拉取失败或必要报告落盘失败。其他仓库或环境成功的结果仍会保留。部分类型拉取成功时保留结果并逐项记录 `error`;范围/策略正常跳过不算失败。客户端配置写入或备份失败同样返回非零,不会报告写入成功。 布尔开关(如 `--yes`、`--write`、`--force`、`--offline`、`--fetch`、`--json`)不带值时启用,显式传值时建议使用 `=true` 或 `=false`。也接受 `1/0`、`yes/no`、`on/off`、`t/f`,大小写不敏感;`--yes=0` 不会跳过确认。空值及其他非法值直接报错,不会执行后续写入或联网操作。 带值参数必须使用 `--选项=值`,例如 `--root=/path/to/workspace`;未知选项、缺少值或值为空都会报错,不会静默回退到默认目录、客户端或云端。可选参数不使用时直接省略。 --- ## 12. 常见问题 **Q:`moo-cloud: command not found`** 没放进 PATH。用绝对路径执行,或把所在目录加入 PATH。 **Q:`未找到任何 .moo-cloud.json`** 确认当前目录或 `--root` 本身及下两层内存在 marker,并按第 7 节配置;更深的仓库请直接指定对应目录。 **Q:`app root 不存在或缺 artisan`** marker 的 `root` 写错了;Laravel 在子目录时写子目录名,否则写 `.`。 **Q:`env 缺 MOO_MONITOR_CLOUD_TOKEN`** 该仓库的 `.env*` 里没有云端 host token;找项目管理员要,或检查 `env_file` 是否写对。 **Q:`slug 不一致`** 本地 marker 的 `project` 和云端 token 对应的项目对不上,说明目录/仓库认错了,先别继续。 **Q:拉取失败 / 401** token 失效、被吊销或过期;重新生成。`--cloud` 指向的实例也要对。 **Q:WorkBuddy 里看不到工具** 先到 MCP 面板确认 `moo-cloud` 已信任、已启用并显示工具数量,再新建会话。仍无工具或升级后列表未刷新时,才 `Cmd+Q` 完全退出后重开。 **Q:DSH 里 `server is disconnected`** 确认配置在 `- insert:` 下、`command` 指向真实存在的二进制;改完重启 DSH 或新建会话。 **Q:macOS 提示无法打开** `xattr -d com.apple.quarantine /path/to/moo-cloud`。 **Q:Windows 上 token 读不到** 路径是 `%USERPROFILE%\.config\moo-fleet\mcp-token`,写入时用 ASCII 编码,避免 UTF-16。 **Q:移动了二进制后客户端断连** `agent-config` 写的是绝对路径;移动后重新执行一次 `agent-config --write --force`。 --- ## 13. 安全 - host token 只从本地 `.env*` 读取,不打印、不写日志 - 个人 MCP token 只读文件/环境变量;cloud 侧只存哈希 - 不要把 token 提交进仓库、贴到聊天或日志 - `--cloud`/`MOO_CLOUD_URL` 必须使用 **https**(仅 localhost 允许 http),避免 token 明文出网 - 自更新校验下载文件 SHA-256,且主备发布源 `SHA256SUMS` 需一致;正式签名(公钥)校验需在发布流程额外配置(待办) - 写操作在服务端校验范围与策略,范围外返回 403 --- ## 14. 开发 ```bash cd go make dist # 交叉编译 6 个平台 go test ./... # 单元 + httptest 集成测试 gofmt -w cmd/moo-cloud/*.go ``` 目录: ``` go/cmd/moo-cloud/ main.go / preflight.go / mcp.go / agentconfig.go templates/ 报告模板 ``` 欢迎提 issue / PR。 --- ## License [MIT](LICENSE)