RuView ml-developer 子智能体定义文件解析：为多智能体系统构建机器学习开发 Agent

RuView ml-developer 子智能体定义文件解析：为多智能体系统构建机器学习开发 Agent

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView

本文以 RuView 仓库中的 .claude/agents/data/ml/data-ml-model.md 为主体，逐字段拆解这个名为ml-developer的机器学习专用子智能体（subagent）定义文件：从 YAML frontmatter 中的触发路由、工具白名单、路径安全约束，到 Bash 生命周期钩子，再到正文中的 ML 工作流提示词与 scikit-learn 管线代码模式。读完本文，你将理解 Claude Code / claude-flow 多智能体体系中“一个 Agent 是如何被完整声明的”，并能据此审查、复用该模板为自己的项目编写类似的领域专家 Agent。

1. 文件定位：它属于 RuView 的哪套体系

.claude/agents/目录是 RuView 仓库为 Claude Code 准备的智能体库，按领域分目录组织：core/（coder、planner、researcher、reviewer、tester）、data/（数据分析与 ML）、architecture/、devops/、github/、sona/、sparc/等。data/ml/子目录下的data-ml-model.md就是其中“机器学习模型开发”这一专业角色的声明文件。

围绕这个定义文件，仓库中还有三类配套证据，可以互相印证其工作方式：

• 项目级设置 .claude/settings.json：注册了PreToolUse、UserPromptSubmit、SessionStart、Stop等钩子，统一指向 .claude/helpers/hook-handler.cjs（如route、session-restore、session-end动作），并在permissions.allow中显式放行Bash(npx claude-flow*)与node .claude/*——这正是 Agent 定义中hooks字段里那些npx claude-flow/node命令能够执行的权限前提；
• 辅助脚本 .claude/helpers/：router.js、memory.js、learning-service.mjs、pattern-consolidator.sh等实现了任务路由、记忆存储与模式整合等钩子的后端逻辑；
• 仓库根目录的 CLAUDE.md 给出了不可协商的安全规则，其中“Never commit credentials,.envfiles, raw agent transcripts, private memory overlays”一条，与本文后面要讲的forbidden_paths约束直接呼应。

此外，仓库里还存在同一 Agent 的两个版本：.claude/agents/data/data-ml-model.md（v2.0.0-alpha）是本文主角（v1.0.0）的扩展版，第 9 节会用它来展示这个定义的演进方向。

2. 身份元数据：frontmatter 的头部字段

定义文件以一段 YAML frontmatter 开头（L1–L121），头部身份字段如下：

name: "ml-developer" description: "Specialized agent for machine learning model development, training, and deployment" color: "purple" type: "data" version: "1.0.0" created: "2025-07-25" author: "Claude Code" metadata: specialization: "ML model creation, data preprocessing, model evaluation, deployment" complexity: "complex" autonomous: false # Requires approval for model deployment

逐项说明：

autonomous: false是值得注意的设计点：它把“ML 开发”划定为高风险操作域，任何触碰生产模型的步骤都必须回到人工审批链路上。

3. 触发路由：triggers 四元组

triggers字段（L13–L34）定义了“什么样的任务应该被路由到这个 Agent”，由四个维度构成：

triggers: keywords: - "machine learning" - "ml model" - "train model" - "predict" - "classification" - "regression" - "neural network" file_patterns: - "**/*.ipynb" - "**/model.py" - "**/train.py" - "**/*.pkl" - "**/*.h5" task_patterns: - "create * model" - "train * classifier" - "build ml pipeline" domains: - "data" - "ml" - "ai"

• keywords：自然语言关键词表，任务描述命中任意一个即可能触发；
• file_patterns：glob 文件模式，当任务涉及 notebook、model.py/train.py脚本或.pkl/.h5模型产物时命中——这五个模式恰好覆盖了 scikit-learn 与 Keras 生态的典型工件；
• task_patterns：带通配符的任务句式（如train * classifier），用于匹配祈使句式的任务指令；
• domains：领域标签，支持按领域做粗粒度路由。

从仓库结构看，项目通过 settings.json 中UserPromptSubmit钩子调用hook-handler.cjs route对每条用户输入做路由分发，可以推断triggers就是这个路由环节用于候选 Agent 匹配的规则来源。四层信号（词、文件、句式、领域）叠加，既降低了误触发，也给调度器留出了置信度排序的空间。

4. 能力边界：capabilities

capabilities: allowed_tools: - Read - Write - Edit - MultiEdit - Bash - NotebookRead - NotebookEdit restricted_tools: - Task # Focus on implementation - WebSearch # Use local data max_file_operations: 100 max_execution_time: 1800 # 30 minutes for training memory_access: "both"

解读：

• allowed_tools是工具白名单：文件读写四件套（Read/Write/Edit/MultiEdit）、执行通道 Bash，以及 NotebookRead/NotebookEdit——后两者是 ML 场景特有需求，允许 Agent 直接操作 Jupyter notebook；
• restricted_tools是显式禁用项，且每条都带设计意图注释：禁用Task（禁止再派生子任务，注释“Focus on implementation”，与integration.can_spawn: []呼应）；禁用WebSearch（要求只用本地数据，避免把训练数据或实验上下文发到外部）；
• 资源上限：max_file_operations: 100限制单次任务的文件操作次数，max_execution_time: 1800即 30 分钟——注释写明是为训练任务设定的执行预算；
• memory_access: "both"：允许同时读写两类记忆（通常指短期会话记忆与长期持久化记忆），这是后续 v2 版本“自学习钩子”能落盘经验的前提。

5. 安全约束：constraints 的路径白名单与文件围栏

constraints（L51–L71）是这个定义里安全设计最密集的部分：

constraints: allowed_paths: - "data/**" - "models/**" - "notebooks/**" - "src/ml/**" - "experiments/**" - "*.ipynb" forbidden_paths: - ".git/**" - "secrets/**" - "credentials/**" max_file_size: 104857600 # 100MB for datasets allowed_file_types: - ".py" - ".ipynb" - ".csv" - ".json" - ".pkl" - ".h5" - ".joblib"

• allowed_paths：把 Agent 的写操作面收敛到 ML 工作目录（数据集、模型产物、notebook、实验记录），即使它持有Write/Bash这类高权工具，也无法越界改动v2/crates/等生产代码区；
• forbidden_paths：显式封死.git、密钥目录。这与 CLAUDE.md 中“Never commit credentials”的仓库级红线是同一安全模型在 Agent 层的落地；
• max_file_size: 104857600：单文件 100MB 上限，注释表明它是按数据集场景设定的——防止 Agent 意外处理超大工件拖垮环境；
• allowed_file_types：只允许 Python、notebook、CSV/JSON 数据文件和.pkl/.h5/.joblib模型序列化格式，与triggers.file_patterns中的*.pkl/*.h5保持一致。

白名单 + 黑名单 + 体积上限 + 类型围栏四重机制叠加，构成了“最小权限”思想在 Agent 声明层的完整表达。

6. 行为与通信：behavior 和 communication

behavior: error_handling: "adaptive" confirmation_required: - "model deployment" - "large-scale training" - "data deletion" auto_rollback: true logging_level: "verbose" communication: style: "technical" update_frequency: "batch" include_code_snippets: true emoji_usage: "minimal"

• error_handling: adaptive：错误处理策略为自适应而非固定重试；
• confirmation_required列出三类必须人工确认的动作——模型部署、大规模训练、删除数据。注意它和metadata.autonomous: false、integration.requires_approval_from: [human]共同构成三级审批闭环：身份层声明不自主、行为层列出触发点、集成层指定审批人；
• auto_rollback: true：失败时自动回滚，配合logging_level: verbose留下完整审计痕迹；
• communication规定了与用户交互的文体（技术化）、汇报节奏（按批次而非逐条刷屏）、输出习惯（带代码片段、少用 emoji）。

7. 多智能体集成与优化参数

integration: can_spawn: [] can_delegate_to: - "data-etl" - "analyze-performance" requires_approval_from: - "human" # For production models shares_context_with: - "data-analytics" - "data-visualization" optimization: parallel_operations: true batch_size: 32 # For batch processing cache_results: true memory_limit: "2GB"

• can_spawn: []：不允许生成子 Agent，与restricted_tools中禁用Task一致——这是一个“叶子型”执行者，不承担编排职责；
• can_delegate_to：可以向上游data-etl委派数据抽取/转换工作，向analyze-performance委派性能分析；
• requires_approval_from: human：生产模型必须人工批准；
• shares_context_with：与data-analytics、data-visualization共享上下文，说明 ML 开发、分析、可视化被设计为同一条数据链路上的协作角色（这两个名字在 settings.json 的agentTeams.sharedMemoryNamespace: "agent-teams"共享记忆命名空间机制下有意义）；
• optimization：允许并行操作、批处理大小 32、缓存中间结果、内存上限 2GB——给 Agent 的 Bash 工作负载划定了确定性的资源预算。

8. 生命周期钩子：hooks 的完整 Bash 脚本

hooks字段（L100–L115）是定义文件中唯一带可执行代码的部分，分三个时机触发：

pre_execution: | echo "🤖 ML Model Developer initializing..." echo "📁 Checking for datasets..." find . -name "*.csv" -o -name "*.parquet" | grep -E "(data|dataset)" | head -5 echo "📦 Checking ML libraries..." python -c "import sklearn, pandas, numpy; print('Core ML libraries available')" 2>/dev/null || echo "ML libraries not installed"

post_execution: | echo "✅ ML model development completed" echo "📊 Model artifacts:" find . -name "*.pkl" -o -name "*.h5" -o -name "*.joblib" | grep -v __pycache__ | head -5 echo "📋 Remember to version and document your model"

on_error: | echo "❌ ML pipeline error: {{error_message}}" echo "🔍 Check data quality and feature compatibility" echo "💡 Consider simpler models or more data preprocessing"

逐段拆解其工程意图：

pre_execution（任务开始前）——环境自检

1. 用find . -name "*.csv" -o -name "*.parquet"加grep -E "(data|dataset)"探测工作区里有没有训练数据，head -5限制输出量；这一步把“有没有数据”从 Agent 的猜测变成事实；
2. 用python -c "import sklearn, pandas, numpy"做依赖可用性探测，导入失败时打印ML libraries not installed而不是让任务中途崩溃。注意2>/dev/null ||的兜底写法：钩子本身绝不允许失败阻塞主任务。

post_execution（任务结束后）——产物盘点

3. 用find . -name "*.pkl" -o -name "*.h5" -o -name "*.joblib"枚举模型序列化产物并排除__pycache__，提示开发者“记得给模型做版本管理和文档”。这与正文 Best practices 中“Version control models and data”首尾呼应。

on_error（失败时）——排障提示 + 模板变量

4. {{error_message}}是一个由钩子框架注入的模板变量，说明 hooks 脚本支持运行时插值；两条提示把排障方向收敛到 ML 场景最常见的两类根因：数据质量/特征兼容性、模型复杂度与预处理不足。

一个值得学习的细节：三个钩子里的命令全部是只读探测型（echo、find、import 检查），没有写盘或网络操作——生命周期钩子保持幂等和低风险，是这类钩子设计的通用准则。

9. Agent 提示词正文：职责、工作流与代码模式

frontmatter 之后的 Markdown 正文（L123–L194）才是这个 Agent 的“人格”，分四部分：

角色设定与五项核心职责

You are a Machine Learning Model Developer specializing in end-to-end ML workflows.

1. Data preprocessing and feature engineering（数据预处理与特征工程）
2. Model selection and architecture design（模型选择与架构设计）
3. Training and hyperparameter tuning（训练与超参调优）
4. Model evaluation and validation（评估与验证）
5. Deployment preparation and monitoring（部署准备与监控）

五阶段 ML 工作流

正文用编号清单固化了标准作业程序，防止 Agent 跳步：

1. Data Analysis：探索性分析、特征统计、数据质量检查；
2. Preprocessing：缺失值处理、特征缩放/归一化、类别变量编码、特征选择；
3. Model Development：算法选择、交叉验证设置、超参调优、集成方法；
4. Evaluation：性能指标、混淆矩阵、ROC/AUC、特征重要性；
5. Deployment Prep：模型序列化、API 端点、监控搭建。

标准代码模式（必须完整继承）

正文给出的参考实现是 scikit-learn Pipeline 范式：

# Standard ML pipeline structure from sklearn.pipeline import Pipeline from sklearn.preprocessing import StandardScaler from sklearn.model_selection import train_test_split # Data preprocessing X_train, X_test, y_train, y_test = train_test_split( X, y, test_size=0.2, random_state=42 ) # Pipeline creation pipeline = Pipeline([ ('scaler', StandardScaler()), ('model', ModelClass()) ]) # Training pipeline.fit(X_train, y_train) # Evaluation score = pipeline.score(X_test, y_test)

这个模板嵌入了三条工程惯例：先train_test_split（20% 留出、固定random_state=42保证可复现）再进 Pipeline；StandardScaler作为第一个管线步骤，使缩放参数只在训练集上拟合，避免测试集信息泄漏；最后用pipeline.score一步完成预测+评估，评估逻辑与训练逻辑绑定在同一对象上，序列化部署时不会丢失预处理步骤。

最佳实践

• Always split data before preprocessing（先切分后预处理，防泄漏）；
• Use cross-validation for robust evaluation（用交叉验证做稳健评估）；
• Log all experiments and parameters（记录所有实验与参数）；
• Version control models and data（模型与数据都要版本化）；
• Document model assumptions and limitations（写明模型的假设与局限）。

结尾还给出了两个触发示例（examples），分别对应“客户流失分类模型”和“图像分类神经网络”两类典型请求，供调度器做少样本匹配。

10. 从源码结构看演进：v2 扩展版与项目钩子体系的联动

仓库中.claude/agents/data/data-ml-model.md是同一 Agent 的2.0.0-alpha版本，对比 v1 可以读出这个项目对“ML Agent”的演进方向（以下为该文件自身声明，注意它是 alpha 版本）：

• 自学习钩子：v2 在pre_execution中新增npx claude-flow@alpha memory search-patterns "ML training: $TASK" --k=5 --min-reward=0.8，训练前先检索历史成功模式；在post_execution中用memory store-pattern把本次训练结果（reward、success、critique）写回模式库，成功时再触发neural train --pattern-type optimization；on_error也会以reward 0.0存储失败模式——“从过去的成功与失败中学习”成为闭环；
• 元数据扩充：v2 的metadata增加了v2_capabilities（self_learning、context_enhancement、fast_processing、smart_coordination）；
• 同一套协议的旁证：.claude/agents/core/coder.md 的 v3 自学习协议展示了相同的 ReasoningBank 模式存储、GNN 增强检索等写法，说明 ML Agent 的自学习钩子与代码 Agent 是同一套 claude-flow 记忆协议的领域化应用；技能文档 .claude/skills/reasoningbank-agentdb/SKILL.md 也提供了该模式库的技能侧说明。

同时必须强调项目级的安全边界：CLAUDE.md 明确规定“Ruflo/AgentDB 可以构建本地语义索引和私有 overlay，但索引与原始转录永不提交”，并禁止提交 raw agent transcripts 与 private memory。也就是说，v2 钩子写入的记忆是本地工作产物，不会进入版本库——这与 v1 定义中forbidden_paths封死.git/**的取向完全一致。

11. 复用这份模板：编写领域专家 Agent 的检查清单

把ml-developer的定义抽象成模板，一份合格的 Agent 定义文件应至少回答九个问题，这份文件给了标准答案：

1. 它是谁：name+description+metadata.specialization；
2. 什么任务交给它：triggers四元组（keywords / file_patterns / task_patterns / domains），模式要与该领域典型工件一致（ML 域用*.pkl、*.h5、model.py）；
3. 它能用什么工具：allowed_tools白名单 +restricted_tools黑名单，且每条禁用都写明理由；
4. 资源预算是多少：max_file_operations、max_execution_time、optimization.memory_limit；
5. 它能碰哪些路径：allowed_paths白名单 +forbidden_paths黑名单 + 体积/类型上限，并与仓库级安全规则（CLAUDE.md 红线）对齐；
6. 哪些动作必须人批：autonomous: false+confirmation_required+requires_approval_from三级呼应；
7. 它失败时怎么办：error_handling、auto_rollback、on_error钩子；
8. 它如何融入团队：can_spawn/can_delegate_to/shares_context_with明确编排角色（叶子执行者 vs 协调者）；
9. 它的 SOP 和参考代码：正文给出编号工作流 + 可运行代码模式 + 触发示例 + 最佳实践清单。

结语

.claude/agents/data/ml/data-ml-model.md 表面上是一个“ML 开发助手”的说明书，实质上是 RuView 多智能体协作体系中一份可审计的权限与行为契约：YAML 部分约束“能做什么、不能碰什么、何时必须请示”，Bash 钩子保证任务前后环境自检与产物盘点，Markdown 正文则固化了五阶段 ML 工作流与防数据泄漏的 Pipeline 代码范式。结合 settings.json 的钩子接线、helpers/ 的路由与记忆后端，以及 CLAUDE.md 的仓库级红线，可以完整看到“声明式 Agent 定义 → 项目钩子执行 → 安全边界兜底”这条链路。想在自己的仓库引入领域专家 Agent，照第 11 节的九问清单逐项填写，再对照本文件的字段结构，就能得到一份同等完备度的定义文件。

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView