提案：内嵌 MAS Agent 辅助诊断，自动定位用户操作与源码问题并起草规范 Issue #674

目标

在 AUTO-MAS 内嵌一个辅助诊断能力（下称 MAS Agent）：用户遇到问题时，能在软件里发起一次"问诊"，由本机 Agent 自主读取运行日志与代码、结合复现信息，判断是用户操作问题还是软件缺陷，并产出一份符合本项目规范的 Issue 正文——用户只需过目后点提交。

目标是降低用户把"我卡住了"变成"开发者能直接定位的 Issue"的门槛，把现在依赖人工来回追问日志和版本的环节自动化。

现状

• 用户侧出问题后，需要人工引导到「设置 → 日志管理 → 导出日志压缩包」，再补充脚本日志、环境信息；很多 Issue 因缺少日志被关闭。
• 后端日志与脚本日志其实都已在本地落盘，具备自动收集的基础：
  • 本体日志：debug/app.log（Loguru，轮转 1 周 / 保留 1 月，写出前已做敏感字段脱敏）。
  • 脚本运行日志：history/<日期>/<用户>/<脚本名>-<时间>.log（由 build_history_log_path 生成，MAA / MaaEnd / SRC / 通用等专项各自保存）。
  • 脚本宿主日志位置通过环境变量 MAS_SCRIPT_LOG_PATH 暴露，log_box 已封装了增量读取、轮转与截断处理。
• 后端已通过 fastapi-mcp 暴露 /mcp（所有 OpenAPI 路由自动成为 MCP 工具，Delete 标签除外）。
• 仓库已有 .agents/skills/mas-* 工程规范，但面向"开发者让 AI 改代码"，没有面向"用户本地问诊"的技能。

提案

1. 能力定位（重要）

MAS Agent 只做只读诊断与建议，不代替用户改数据、不代替开发者修代码：

• 输出：诊断结论 + 操作指引 + 一份可提交的 Issue 正文（含证据与代码位置）。
• 不做：自动修改用户配置/数据、自动提交 Issue、自动推送代码。
• 依据现有规范，AI 产出的报告应走「AI 提交的 Bug」模板，该分区不承诺处理时间；MAS Agent 生成的正文也必须落到该模板的字段结构里。

2. 结构

1. 采集层（纯本地、无模型）：app/tools/mas_agent/（或 app/services/ 下的独立模块）
   • 复用已有能力：Config.build_history_log_path 定位历史日志、log_box.LogSource 做增量/轮转安全的读取。
   • 显式采集而非整目录打包：本体日志尾部 + 命中的脚本/用户/时间窗日志 + 环境信息（版本、系统、模拟器与分辨率、DPI）。
   • 采集结果先过脱敏，再落成一个受限大小的诊断包（避免把整份 data.db 与全部历史记录塞进上下文）。
2. 分析层（Agent 循环）：以现有的 OpenAI 兼容接口为后端，模型与密钥由用户在设置内自行填写，默认关闭；能力包括读诊断包、按需 grep/读源码、运行只读的 MCP 工具（当前状态、队列、历史、设置）。
3. 提交层（人工确认）：生成 Issue 正文草稿 + 建议标签/模板，在界面上展示 diff 式的"将要提交的内容"，由用户点提交；不自动提交。

3. Skill 与 MCP

• 新增项目附属 Skill（.agents/skills/mas-user-diagnosis/）：
  • 采集与脱敏边界（哪些能进上下文、哪些禁止外发，如凭据、账号、路径中的用户名）；
  • 症状到子系统的最小排查路径（脚本识别、模拟器连接、更新、社区签到、MaaFW 环境等）；
  • Issue 正文写法（复用已有规范，不在此复制权威内容，直接链文档站）。
• MCP 侧新增只读工具（保持现有契约风格）：
  • 取诊断包（当前会话/指定时间窗）；
  • 按关键字检索本体日志与脚本日志；
  • 查询当前版本、运行环境与最近的运行记录；
  • 一律不提供写操作，破坏性路由继续排除在 MCP 之外。

4. 边界与风险

• 隐私：日志可能包含账号、区服、路径等；必须先脱敏再外发，且默认只把脱敏后的片段送模型；是否外发需用户明确同意。
• 成本：模型调用由用户自己的密钥承担，默认关闭，按次计费可见。
• 误判：Agent 结论文本必须标注"仅供参考"，并附证据（日志片段 + 代码位置），无证据不得下结论。
• 越权：Agent 不得执行写操作，不代替用户提交 Issue、不代替开发者改代码。

本方案不做

• 不改动现有日志导出与数据备份链路。
• 不接入项目方的统一模型服务（先做用户自带密钥的本地能力）。
• 不在本期实现自动提交 Issue 或自动修复。

开放问题

1. Agent 运行时放在后端进程内还是独立子进程？（子进程隔离更好，但需另做 IPC 与生命周期管理）
2. 诊断包先只覆盖"本体日志 + 脚本日志 + 环境信息"，还是允许用户勾选加入截图/录屏？
3. 是否需要"复现录屏"这类带用户操作轨迹的采集，还是先依赖日志时间线？