训练守护智能体 Washington5533/guarftrain

训练守护智能体

一行命令，训练脚本零行改动，获得完整守护能力。

One command. Zero changes to your training script. Full guardian capabilities.

guarftrain init && guarftrain watch -- python train.py --epochs 20

v0.3.0 更新内容

| 功能 | 说明 |
| 架构分析 (Arch Analysis) | D3 treemap + backbone 可视化，FLOPs/参数量/瓶颈层检测，参考 archify 设计 |
| 远程通信 (Remote Server) | 算力服务器端 FastAPI 服务，PC Dashboard 远程连接，鉴权 token |
| Sub-agent 自主决策 | --autonomy supervised/auto/full，自主调整参数/干预训练 |
| DSH Web GUI Plugin | DeepSeek Harness 会话头部面板，实时 metrics/GPU/anomalies/decisions/architecture/history（插件文档） |
| CPU 模式兼容 | 无 GPU 时自动降级，训练曲线正常显示，GPU 面板提示不可用 |
| PyTorch >= 1.13 支持 | resource_estimator 回退兼容 PyTorch 1.x |
| MCP 工具扩展 | +1 analyze_architecture 工具（共 36 个） |
| Dashboard 架构分析标签 | 独立「架构分析」标签页，treemap/backbone 双视图 |

v0.2.0 更新内容

| 功能 | 说明 |
| guarftrain CLI | pip install 后全局可用，替换旧 python run.py |
| guarftrain init | 自动扫描训练脚本，生成 contract.yaml |
| guarftrain check | 环境自检：Python/GPU/依赖/项目结构 |
| Dashboard 远程配置 | 外部 Agent 通过 MCP 控制 Dashboard 图表/面板，用户操作受 dirty flag 保护 |
| Agent 图表推荐 | chart_selection 决策点：Agent 分析训练状态，推荐应关注的指标组 |
| MCP 委托模式 | 外部 Claude Code 连接时内置 Agent 进入 provisional 模式，决策可被覆盖 |
| 增量图表更新 | Dashboard 实时推送图表数据，不再全量重建 |
| 依赖瘦身 | 核心安装 ~2MB，torch/anthropic 按需安装 |

它做什么？

| 阶段 | 能力 | 方式 |
| 训练前 Pre-flight | GPU 显存预估 + batch 推荐 | guarftrain preflight |
| 训练中 During | GPU+Loss 监控告警 / 崩溃自动恢复 / LLM 决策 / Sub-agent 自主干预 | guarftrain watch |
| 训练后 Post | 摘要+AI 解读 / Checkpoint 分析 / 模型可视化 / 架构分析 | guarftrain analyze |
| 跨实验 Cross | 自然语言查询 / 实验对比 / 数据导入 | guarftrain query "best lr?" |
| 外部接入 External | MCP 36 工具 + Dashboard 远程配置 + Agent 图表推荐 + 远程通信 | guarftrain start |

快速开始

安装

方式 1: pip 安装（推荐，轻量核心 ~2MB，torch 已有不重装）
pip install guarftrain

方式 2: 从源码安装
git clone https://github.com/Washington5533/Guid-traince.git
cd Guid-traince
pip install .

按需安装可选组件
pip install guarftrain[agent] # AI 决策层 (anthropic)
pip install guarftrain[mcp] # MCP 外部 Agent 接入
pip install guarftrain[dashboard] # Web 控制面板
pip install guarftrain[full] # 全部安装

三步守护

1. 初始化项目（自动扫描训练脚本，生成配置）
cd /path/to/your-project
guarftrain init

2. 守护训练（纯规则，零外部依赖） guarftrain watch -- python train.py --epochs 20

3. 或启用 AI + Dashboard + MCP guarftrain watch --agent --with-dashboard --with-mcp -- python train.py --epochs 20

What does the training script need? · 训练脚本要满足什么？

四项契约（训练脚本的接口约定），每一项控制一个能力——缺任一项只关闭对应能力，不阻断训练。

1. --resume / --ckpt 参数，用于断点续训 → 开启崩溃恢复 + 基于重启的干预
2. cp_{epoch}/model.pth，含 epoch/model_state_dict/optimizer_state_dict → 开启检查点分析 + 训练后工具
3. 结构化日志：epoch {n} loss {v} val_acc {v} lr {v} → 开启 loss 异常检测 + 进度监控
4. 可导入入口：train:build_model / train:get_dataloaders → 开启预检资源估算 + 模型可视化 + 推理

缺任一项？只关闭对应能力——训练照常运行。

四项契约（训练脚本的接口约定），每一项控制一个能力——缺任一项只关闭对应能力，不阻断训练。guarftrain init 会自动扫描你的脚本，逐项报告开启/降级状态。

Architecture · 架构

┌─ Guardian Process (sidecar) ────────────────────────────────────┐
│ │
│ CLI (guarftrain) ──→ 18 subcommands │
│ ├─ watch ──→ Watchdog: Popen + crash recovery + CLI rewrite │
│ │ └─ Monitor: log tail + GPU poll + anomaly detect │
│ │ └─ AgentAdvisor: LLM decide → intervene │
│ │ └─ Sub-agent: --autonomy (supervised/auto/full) │
│ ├─ remote ──→ FastAPI 远程通信服务（算力服务器端） │ │ ├─ serve ──→ MCP Server: 36 tools (25 read + 11 write) │ │ ├─ start ──→ Dashboard + MCP one-click │ │ └─ experiments / query / compare ──→ Cross-experiment analysis │ │ │ │ Decision Layers · 决策分层: │ │ ┌─ Contract (hard boundary, human-defined) │ │ ├─ Agent (LLM, optional, within action space) │ │ ├─ Sub-agent (autonomous, --autonomy supervised/auto/full) │ │ ├─ Rules (deterministic, always-on fallback) │ │ ├─ MCP (external agent access, dual-mode delegation) │ │ └─ Dashboard (remote config, dirty-flag user protection) │ │ │ │ Architecture Analysis · 架构分析: │ │ └─ ArchAnalyzer: forward hooks → FLOPs → tree → D3 render │ │ │ │ Training Process: python train.py (0 changes required) │ └──────────────────────────────────────────────────────────────────┘

CLI Commands · 命令速查

| Command | Description |
| init | 自动探测项目 + 生成 contract.yaml |
| check | 环境就绪检查（依赖、GPU、配置） |
| watch | 守护任意训练命令 |
| start | 仪表盘 + MCP 一键启动 |
| serve | 独立 MCP 服务器 |
| remote | 启动远程通信服务器（计算服务器侧） |
| contract check | 校验训练脚本契约 |
| preflight | GPU 显存估算 + batch 推荐 |
| analyze | 扫描已有 checkpoint |
| analyze_architecture | 分析模型架构（D3 矩形树图/骨干） |
| experiments | 列出全部历史实验 |
| query | 自然语言查询（「最佳 lr？」） |
| compare | 对比两个实验 |
| visualize | 模型结构可视化（D3.js HTML） |
| infer | 用 checkpoint 跑推理 |
| gallery | 图片筛选 + 挑选 |
| dashboard | Web 控制面板（独立运行） |
| project | 项目上下文管理（init/show/scan/fill） |

MCP Tools · MCP 工具

25 个只读工具（始终可用，无需鉴权）：

get_training_status · get_metrics_history · list_checkpoints · compare_checkpoints · get_anomaly_history · get_recovery_history · get_summary · get_agent_decision_log · get_contract_status · list_contract_proposals · list_experiments · query_experiment · compare_experiments · get_model_structure · analyze_architecture · get_guardian_mode · get_gallery_config · get_import_format · inspect_source · get_training_log · get_post_training_checklist · get_pending_decisions · get_dashboard_config · recommend_charts · list_dashboard_templates

11 个写入工具（token 鉴权 + 训练阶段门控）：

trigger_recovery · restart_with_params · stop_training · approve_contract_proposal · reject_contract_proposal · run_visualization · set_gallery_config · run_inference · submit_import · resolve_decision · set_dashboard_config

→ 完整 API 参考：docs/MCP_API_REFERENCE.md

Configuration · 配置

三层配置，YAML 里不存任何密钥：

DEFAULTS < guardian.yaml < GUARDIAN_* env vars < CLI flags

configs/guardian.yaml — only override what you need watchdog: max_retries: 3 monitor: poll_interval: 5 mcp: enable_write_tools: true

Env override: GUARDIAN_ + section + __ + key
export GUARDIAN_WATCHDOG__MAX_RETRIES=5
export GUARDIAN_MCP_TOKEN=your-secret # write tool auth

DSH Web GUI Plugin · DSH 插件

配套 DSH Web GUI 插件 @rrrelink/dsh-client-ui-training-guardian（需 DSH >= 0.2.0-rc.2），在会话头部提供八标签页的 Training Guardian 面板（概览/设备/异常/决策/架构/历史/权限/速查），面板配色跟随 DSH 主题，数据经 SSE 推送 + REST 补拉自 guarftrain remote 服务。

安装插件（profile 目录 ~/.dsh/profiles/web）
dsh plugin add @rrrelink/dsh-client-ui-training-guardian --profile web

训练机侧启动数据源 guarftrain remote --port 8765 guarftrain watch -- python train.py --epochs 50

- 源码：dsh-plugin/dsh-client-ui-training-guardian
- 完整使用说明书：README.zh.md / README.md
- 插件镜像仓库：<https://github.com/Washington5533/Guid-traince>

Project Status · 项目状态

| Metric | Value |
| Version | 0.3.0 |
| Modules | 36 (guardian/*.py, 含 dashboard/remote/sub_agent 子包) |
| Production code | ~17,700 lines (Python) |
| Tests | 280 (CI on push) |
| MCP tools | 36 (25 read + 11 write) |
| CLI commands | 18 |
| Test coverage | ~13% (core paths: 100%) |
| Python | 3.10+ |

Docs · 文档索引

| Document | Content |
| docs/INTRODUCTION.md | 项目介绍（中文） |
| docs/PACKAGES.md | 包分发与 DSH/Agent 集成指南（中文） |
| docs/ARCHITECTURE.md | 架构与工作流（中文） |
| docs/DEPLOYMENT.md | 用户手册（中文） |
| docs/MCP.md | MCP 集成指南（中文） |
| docs/MCP_API_REFERENCE.md | 36 个工具的 API 参考（中文） |
| docs/MCP_QUICKSTART.md | 5 分钟 MCP 上手（中文） |
| docs/IMPLEMENTATION_REPORT.md | 各模块完成情况报告（中文） |
| docs/FIELD_PROBLEM_REVIEW.md | 真实训练现场问题复盘与覆盖度评估（中文） |
| docs/PLUGIN_STANDARDS.md | DSH 社区插件规范（中文） |
| dsh-plugin/…/README.zh.md | DSH 插件用户手册（中文/英文） |

License

MIT