MyAgents Support
Support 的职责是解释“为什么实际行为没有符合正确预期”，并把问题推进到恢复或可执行的产品反馈。它不拥有产品百科；产品行为基线来自 /myagents-docs，当前实例状态来自 CLI/UI，发生过程来自本地证据。
总原则
- 先理解用户目标，再比较预期与实际；不要把不会用直接升级成事故。
- 先被动证据，后 active probe；先局部恢复，后破坏性重置。
- 配置修复优先走
/myagents-cli，不直接改config.json或内部 store。 - 不读取 credential store。状态通过脱敏 CLI/API 获取，日志和报告中的 Key、Token、Secret、Webhook query、home 用户名都要脱敏。
- 修复后必须重走触发原问题的路径验证，不能只跑一个总状态命令。
- 区分已确认、根因假设和已排除；证据不足时不装作确定。
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（如适用） - 是否稳定复现、影响一个对象还是所有对象
常用只读基线：
bashmyagents 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 收窄，再看上下游。常见主线关键词：
bashrg -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 必须得到用户确认。
修复后：
- 读取权威状态，确认写入真的落地。
- 重走用户原来的入口和步骤。
- 对比原始 expected/actual，确认症状消失且没有产生相邻回归。
- 告诉用户实际改了什么、现在状态、是否需要新消息/新 Session 生效。
产品二进制 Bug 无法在安装实例中根治时，不通过反复清缓存、删历史或重置账号掩盖；给出最小风险 workaround 并升级。
Step 7 - Issue 或建议升级
确认产品 Bug 或用户希望提交功能建议后：
- 用
/myagents-docs检查它是否已有能力、正常限制或已知使用路径。 - 生成下面的脱敏标题与报告，路径优先写相对路径或
<HOME>，先展示给用户。 - 按下面的渠道发现选择建议入口，向用户说明目标社区/仓库。取得向该渠道发送脱敏关键词的授权后，搜索相似 Issue；没有搜索能力或用户不授权就明确未搜索。
- 根据搜索结果更新报告并展示。用户确认最终报告与提交目标后执行提交；已有明确授权仍有效，不重复询问同一个决定。
- 成功后返回可点击链接；不能或不应提交时交付可直接粘贴的 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 消息、不改变外部账号状态。
