训练守护智能体 Washington5533/Guid-traince

训练守护智能体 · Training Guardian Agent

PyPI
CI
Python
Streamlit Demo

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

一行命令。无需改动训练脚本。完整的守护能力。

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 按需安装 |

它做什么？ · What does it do?

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

快速开始 · Quick Start

安装 · Install

方式 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] # 全部安装

三步守护 · Three steps to guard

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} → 启用损失异常检测 + 进度监控
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 | Auto-detect project + generate contract.yaml |
| check | Environment readiness check (deps, GPU, config) |
| watch | 守护任意训练命令 |
| start | 仪表盘 + MCP 一键启动 |
| serve | 独立 MCP 服务器 |
| remote | 启动远程通信服务器（计算服务器端） |
| contract check | 验证训练脚本契约 |
| preflight | GPU 显存估算 + 批次推荐 |
| analyze | 扫描现有检查点 |
| analyze_architecture | 分析模型架构（D3 树状图/骨干网络） |
| experiments | 列出所有历史实验 |
| query | 自然语言查询（“最佳学习率？”） |
| compare | 比较两个实验 |
| visualize | 模型结构可视化（D3.js HTML） |
| infer | 使用检查点运行推理 |
| 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 个写入（令牌认证 + 训练阶段门控）：

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

Project Status · 项目状态

| 指标 | 值 |
| 版本 | 0.3.0 |
| 模块 | 21 (cp_1 ~ cp_21) |
| 生产代码 | ~12,500 行 |
| 测试 | 266 (推送时 CI) |
| MCP 工具 | 36 (25 读 + 11 写) |
| CLI 命令 | 18 |
| 测试覆盖率 | ~13% (核心路径：100%) |
| Python | 3.10+ |

Docs · 文档索引

| 文档 | 内容 |
| 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 | 各模块完成报告 (中文) |
| dsh-plugin/…/README.zh.md | DSH 插件用户手册 (中文/英文) |

License

MIT