---
name: support
description: >-
  MyAgents 本地问题诊断、恢复与反馈升级流程。用户描述报错、崩溃、无响应、配置后仍不可用、状态或结果不符合预期、
  Task/Goal/Channel/Provider/Runtime/MCP/Plugin/附件/Agent 网络/协作空间等功能异常，或者前端“小助理诊断/问题反馈”注入诊断上下文时使用。
  先用 `/myagents-docs` 确认正确产品预期，再以本地状态、CLI、日志和必要 probe 分类、修复、验证；确认产品缺陷或功能建议后，
  在用户确认下形成并提交脱敏 Issue。普通“是什么/怎么用/入口在哪”不使用本 skill，直接使用 `/myagents-docs`。
---

# MyAgents Support

Support 的职责是解释“为什么实际行为没有符合正确预期”，并把问题推进到恢复或可执行的产品反馈。它不拥有产品百科；产品行为基线来自 `/myagents-docs`，当前实例状态来自 CLI/UI，发生过程来自本地证据。

## 总原则

1. 先理解用户目标，再比较预期与实际；不要把不会用直接升级成事故。
2. 先被动证据，后 active probe；先局部恢复，后破坏性重置。
3. 配置修复优先走 `/myagents-cli`，不直接改 `config.json` 或内部 store。
4. 不读取 credential store。状态通过脱敏 CLI/API 获取，日志和报告中的 Key、Token、Secret、Webhook query、home 用户名都要脱敏。
5. 修复后必须重走触发原问题的路径验证，不能只跑一个总状态命令。
6. 区分已确认、根因假设和已排除；证据不足时不装作确定。

## Step 0 - 建立正确预期

先写清四件事：

- 用户想完成什么
- 用户实际做了什么
- 正确情况下应该看到什么
- 现在实际看到什么

涉及产品语义时，加载 `/myagents-docs` 的相关 reference，确认前置条件、作用域、生效时机、成功标志和限制。若发现只是功能理解或正常门控，回到产品使用指导，不继续扫日志。

白屏、明确 crash、数据错位等无需争议的异常可以直接进入取证，但报告仍要补齐 expected/actual。

## Step 1 - 建立诊断信封

只收集与问题有关的最小现场：

- MyAgents 版本、OS、问题发生时间窗口
- 触发入口：Chat、Launcher、悬浮窗、Task、Goal、IM、Agent 网络、协作空间等；跨设备时记录双方版本与设备
- Workspace、Session ID、Task/Goal/Issue ID（如适用）
- Provider、Model、Runtime、`runtimeSource`（如适用）
- 是否稳定复现、影响一个对象还是所有对象

常用只读基线：

```bash
myagents status --json
myagents version
rg '\[boot\]' ./logs/unified-*.log | node .claude/skills/support/scripts/redact-log-output.mjs | tail -5
```

不必每次机械运行全部命令。前端已经注入 Terminal Reason / Runtime Diagnostics 时先利用它，再补缺失字段。某条命令或日志不存在，记录原因并继续，不要卡死。

## Step 2 - 选择诊断域

一次先读最相关的 reference；只有证据跨域时才追加。

| 主诉 | 读取 |
|---|---|
| DSH/Codex/Claude Code 不工作、终端能用但 MyAgents 不行、runtime/model/permission 异常 | `references/runtime.md` |
| 跨设备 Agent 发现/调用/回传失败、@ Agent 不完整、Session state/watch/取消观察异常 | `references/agent-network.md` |
| Provider 登录/验证/模型失败，MCP 启动、OAuth、握手或工具列表异常 | `references/provider-mcp.md` |
| Telegram/钉钉/飞书/微信/QQ Agent 不在线、不收发消息，OpenClaw Plugin 异常 | `references/agent-channel-plugin.md` |
| Task/定时/Cron 未执行或状态异常，Goal 不续跑/无法暂停/错误终态，Record/Session Inbox 异常 | `references/automation.md` |
| 录音、离线转写、说话人、播放、语音模型或附件 speech job 异常 | `references/recording-speech.md` |
| 协作空间登录、Goal/Issue、Registered Agent、Delivery、claim、共享工具/官方市场、附件或 quota 异常 | `references/cloud-space.md` |
| 图片/音频/PDF 等工具产物生成但不显示，IM 媒体未发出 | `references/attachments.md` |
| 工作区文件树、搜索、预览、@ 文件、拖拽、CRUD、watcher 异常 | `references/workspace-files.md` |
| AI 不回复、Sidecar 重启、pre-warm、历史恢复、回溯/分叉、Session 状态异常 | `references/session-sidecar.md` |
| 网络/代理、Provider 可达性、npm 拉包、终端与 Runtime env 差异 | `references/proxy-env.md` |
| 白屏、整页渲染错误、悬浮窗/桌宠打不开或卡在连接 | `references/frontend-render.md` |
| 功能入口不存在、实验室开关、CLI 工具或 Runtime/Space 入口看不到 | `references/feature-gates.md` |

## Step 3 - 被动证据与 active probe

优先被动读取：

- `status`、`version`
- 对应对象的 `list/show/get/view --json`
- 当前登录/验证/运行状态的脱敏接口
- 最近时间窗口内的统一日志

active probe 会连接外部服务、启动进程、消耗请求、弹浏览器或实际执行任务。先区分两类授权：

- Provider verify、MCP test、Runtime diagnose：在用户已经要求诊断对应问题时，可以在说明目的和影响后执行。
- OAuth start、Task/Cron run-now、Channel 登录、Plugin/Skill 安装，以及任何写操作或 Cloud/IM/GitHub mutation：会改变状态、启动真实工作或影响外部系统，必须先展示具体对象与影响，并取得用户明确确认。

写命令只有在精确 leaf help 明确支持时才使用 `--dry-run`。不支持 preview 的命令不能通过添加无效 flag 假装已经预览。

统一日志不是凭据安全接口。禁止用裸 `rg` / `grep` 把完整日志行直接送入模型上下文；所有日志命令都必须先通过 `.claude/skills/support/scripts/redact-log-output.mjs`，让 URL、认证字段、常见 Token、长编码串和 home 用户名在工具输出前被替换。第三方 Plugin/npm 输出默认只保留时间、组件、错误类别和已脱敏消息；确需扩大上下文时仍使用同一过滤器并缩小时间窗口。

## Step 4 - 建立时间线和故障边界

按问题入口还原实际链路，而不是套用一张“所有功能都经过 Sidecar”的总图：

```text
用户动作 / Scheduler / Channel / Cloud Delivery
  → 对应产品 owner 接收
  → Session Runtime 或本地 Rust 能力执行
  → 持久状态 / UI / Channel / Cloud 返回结果
```

先按时间、Workspace、Session/Task/Goal/Issue ID、Runtime/Provider 收窄，再看上下游。常见主线关键词：

```bash
rg -n "ERROR|WARN|auth error|401|403|429|terminal_reason|AppErrorBoundary|external-session|runtime_diagnostics|runtimeSource|managed-codex|codex-sub|anthropic-sub|grok-auth|xai-sub|task-scheduler|\[task\]|\[Goal\]|\[space\]|bridge|tool-attachment|cmd_workspace" ./logs/unified-*.log | node .claude/skills/support/scripts/redact-log-output.mjs | tail -200
```

`[CronTask]`、`cron_runs` 等旧名字仍可能出现在兼容路径，但不能再把它们当作 Task Scheduler 的唯一主线。

## Step 5 - 分类

| 类型 | 判断依据 | 行动 |
|---|---|---|
| 使用理解 | 行为符合 docs，用户误解入口、作用域、生效时机或限制 | 解释产品行为，必要时用 CLI 代为完成 |
| 配置错误 | 当前配置与用户目标或合法值域明确不符 | 用 `/myagents-cli` 修复并同路径验证 |
| 环境问题 | 网络、代理、PATH、Runtime 安装、registry、OAuth 外部状态异常 | 给出具体恢复，必要时执行已说明的 probe |
| 实验门控 | 功能默认关闭或需要人工开启 | 解释设置入口，不绕过可见门控 |
| 临时运行异常 | 重启窗口、瞬时网络/限流或可恢复进程状态，重试后恢复 | 说明证据和恢复结果，不夸大为产品 Bug |
| 产品 Bug | 前置条件满足且稳定偏离产品契约，配置/环境无法解释 | 明确影响、证据和 workaround，进入 Issue 升级 |
| 证据不足 | 问题真实但无法在当前证据下归类 | 收集最小复现；仍不足则以 unknown defect 报告，不伪造根因 |

## Step 6 - 修复与验证

修复前确认对象、预期变化和副作用。删除、覆盖、重置登录、撤销 OAuth、移除 Channel/Plugin/Skill、云端 mutation 必须得到用户确认。

修复后：

1. 读取权威状态，确认写入真的落地。
2. 重走用户原来的入口和步骤。
3. 对比原始 expected/actual，确认症状消失且没有产生相邻回归。
4. 告诉用户实际改了什么、现在状态、是否需要新消息/新 Session 生效。

产品二进制 Bug 无法在安装实例中根治时，不通过反复清缓存、删历史或重置账号掩盖；给出最小风险 workaround 并升级。

## Step 7 - Issue 或建议升级

确认产品 Bug 或用户希望提交功能建议后：

1. 用 `/myagents-docs` 检查它是否已有能力、正常限制或已知使用路径。
2. 生成下面的脱敏标题与报告，路径优先写相对路径或 `<HOME>`，先展示给用户。
3. 按下面的渠道发现选择建议入口，向用户说明目标社区/仓库。取得向该渠道发送脱敏关键词的授权后，搜索相似 Issue；没有搜索能力或用户不授权就明确未搜索。
4. 根据搜索结果更新报告并展示。用户确认最终报告与提交目标后执行提交；已有明确授权仍有效，不重复询问同一个决定。
5. 成功后返回可点击链接；不能或不应提交时交付可直接粘贴的 Markdown。

### 渠道发现与提交

MyAgents Space 从 0.5.0 起正式提供官方社区 Issue 反馈。先运行 `gh --version` 检测本机工具；这是本地检测，不需要安装或登录。

| 当前能力 | 推荐入口与下一步 |
|---|---|
| `gh` 可运行 | 优先建议 GitHub 仓库 `hAcKlyc/MyAgents`。用 `gh auth status` 检查可用性（不显示 token）；未认证时提示 GitHub 登录，也可按用户选择转 Space，不把“装了 gh”当成已登录。 |
| 没有可用 `gh`，Space 已登录 | 用 `myagents space list --json` 读取当前成员空间，选择 `data.items[]` 中 `spaceKind=official` 的官方社区，使用返回的实际 slug（当前通常是 `myagents`）。推荐提交到这里。 |
| Space 未登录或需要重新认证 | 提供 `[登录 MyAgents Space](myagents://open/v1/spaces)`，用户点击会打开/聚焦 Space Tab 的登录入口；登录后重新运行 `space list` 再继续。 |

`space list` 是经应用提供的脱敏状态接口；不要读取 Space credential 文件。只有 `NOT_AUTHENTICATED` / `SPACE_REAUTH_REQUIRED` 等明确认证错误才能判断需登录。网络、门控或权限错误保留具体原因，不误报退出登录；官方社区未出现在列表中时引导用户在 Space 检查成员状态，不猜 slug 或新建同名社区。尊重用户明确指定的渠道；不要求用户为了反馈安装 `gh`。

渠道确认与对外授权到位后，使用精确 help 核对参数：

- GitHub：`gh issue list --repo hAcKlyc/MyAgents --state open --search '<脱敏关键词>'`；确认报告后 `gh issue create --repo hAcKlyc/MyAgents --title '<标题>' --body-file issue.md`。
- Space：先 `myagents space whoami --space <返回的slug> --json` 核对身份，再 `myagents space issue list --space <slug> --q '<脱敏关键词>' --json` 查相似反馈。普通小助理 Session 应为 User；不通过注册 Agent、显式 token 或身份降级绕过拒绝。确认报告后 `myagents space issue create --space <slug> --title '<标题>' --body-file issue.md --json`。报告文件保存于当前工作区；不指定 assignee；如需归入 BUGFIX/功能建议 Goal，先用 `space goal list` 取得真实 active Goal ID，否则省略 `--goal` 进入 Inbox。

成功必须根据命令返回结果判断，不把超时/失败说成已提交或盲目重复创建。GitHub 返回其实际 Issue URL；Space 用返回的真实 `id` 生成 `[查看反馈](myagents://open/v1/spaces/<slug>/issues/<issueId>)`，不能把界面的 `#12` 等展示编号替代 Issue ID。也可提供 `[官方社区反馈列表](myagents://open/v1/spaces/official/issues)`。这些链接只导航，不触发搜索、上传或创建。

```markdown
## 功能与用户目标
...

## 环境与影响范围
- MyAgents version / OS：...
- 入口 / Workspace / Runtime：...
- 影响一个对象还是全部对象：...

## 正确预期
...

## 实际结果
...

## 最小复现
1. ...
2. ...

## 关键证据（已脱敏）
...

## 分析
- 已确认：...
- 根因假设：...
- 已排除：...

## 临时绕过与严重程度
...
```

功能建议应强调用户目标、当前阻力和期望结果，不把未经评估的具体实现方案写成唯一答案。

## 安全边界

- 不读取 `~/.myagents/credentials/`、Space token、Claude/Codex 等供应商 credential home、Agent 网络私钥或系统 Keychain；停用集成留下的凭据同样受保护。
- 不要求用户把 API Key/Token 发进持久对话；引导使用产品受保护输入入口。
- 不直接编辑 Session、Project、Task、Goal、Space 内部 store。
- 不把完整日志、用户文件内容、大 base64 或可识别个人路径放进 Issue。
- 未经确认不提交 GitHub Issue、不发 Cloud/IM 消息、不改变外部账号状态。