# ifpp-skill-crewai-agent **Repository Path**: ifpp-agent/ifpp-skill-crewai-agent ## Basic Information - **Project Name**: ifpp-skill-crewai-agent - **Description**: 后端使用crewai挂载ifpp-skill - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-17 - **Last Updated**: 2026-06-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # IFPP Skill CrewAI Agent 基于 CrewAI 和本地 `fault-and-anomaly-ml` skill 的数据挖掘执行项目。系统可以从 CSV 数据生成 Profile 和 DAG，校验 DAG 中引用的 capability/recipe，生成并执行 `run_pipeline.py`，最后输出模型、指标、审计记录和报告。 项目发行名称为 `ifpp-skill-crewai-agent`，Python 包和源码目录为： ```text src/ifpp_skill_crewai_agent/ ``` ## 处理流程 ```text CSV 数据 -> 数据画像 Profile -> mock 或 CrewAI 生成 DAG -> DAG normalize / enrich / validate / repair -> 复制本次 DAG 所需的 skill helper 和输入数据 -> template 或 LLM 生成 run_pipeline.py -> py_compile / static_guard / contract_check -> 执行 Pipeline -> repair 或分层 fallback -> 指标、模型、报告和审计产物 ``` ## 安装与检查 项目要求 Python `>=3.11,<3.12`。 ```bash uv sync uv run ifpp-check ``` `ifpp-check` 会读取数据、生成 Profile，并在 `outputs/<时间戳>/` 中写入 `check_status.json`。 ## 核心参数 ### DAG 生成方式 ```text --mode mock 使用本地规则生成 DAG，不调用 LLM，默认值 --mode crew CrewAI 挂载本地 skill 后生成 DAG ``` ### 执行方式 ```text --execution-mode generated 生成并执行 run_pipeline.py，默认值 --execution-mode executor 由 executor.py 直接执行 DAG ``` ### Pipeline 代码生成方式 ```text --codegen-mode template 使用确定性模板生成，默认值 --codegen-mode llm 使用 LLM 生成 run_pipeline.py ``` ### LLM codegen 编排方式 该参数仅在 `--codegen-mode llm` 时生效： ```text --codegen-orchestrator local 本地 LLM 生成 + guard + repair loop，默认值 --codegen-orchestrator crew CrewAI 多代理生成、审计、诊断和修复 ``` 其他参数： ```text --llm-codegen-max-repairs N 最大修复次数，默认 2 --generated-timeout-seconds N Pipeline 执行超时，默认 300 秒 --plan-only 只生成 Profile、DAG 和校验结果 --data PATH 指定 CSV 数据文件 ``` ## 推荐运行方式 ### 方案 B：稳定 template 主链路 离线 mock： ```bash uv run ifpp-full --mode mock --execution-mode generated --codegen-mode template ``` CrewAI 生成 DAG，template 生成 Pipeline： ```bash uv run ifpp-full --mode crew --execution-mode generated --codegen-mode template ``` template 是默认路径，适合回归测试和稳定交付。 ### 方案 C：LLM codegen 本地编排： ```bash uv run ifpp-full \ --mode mock \ --execution-mode generated \ --codegen-mode llm \ --codegen-orchestrator local ``` CrewAI 多代理编排： ```bash uv run ifpp-full \ --mode crew \ --execution-mode generated \ --codegen-mode llm \ --codegen-orchestrator crew ``` ```bash uv run ifpp-full --mode crew --execution-mode generated --codegen-mode llm --codegen-orchestrator crew ``` Windows PowerShell 可以将命令写成单行，或使用反引号续行。 ## CrewAI Codegen 编排 `--codegen-orchestrator crew` 使用以下角色： - `Pipeline Code Writer`：根据 DAG 和结构化上下文生成代码。 - `Pipeline Code Auditor`：审计 import、调用、安全规则和数据流。 - `Contract Reviewer`：检查 capability 间的状态契约。 - `Runtime Diagnoser`：分析运行失败、stdout、stderr 和 traceback。 - `Pipeline Repairer`：根据诊断重写 Pipeline。 代码中预留了 `Fallback Advisor` 角色；当前版本达到最大修复次数后，由主流程确定性回退到 template。 每次 LLM 尝试会独立保存，避免 template fallback 覆盖失败现场： ```text llm_attempt_0.run_pipeline.py llm_attempt_0.audit.json llm_attempt_0.contract_review.json llm_attempt_0.static_guard.json llm_attempt_0.contract_check.json llm_attempt_0.status.json llm_attempt_0.stdout.txt llm_attempt_0.stderr.txt llm_attempt_1.diagnosis.json codegen_attempts.jsonl ``` ## 安全和契约检查 LLM 只能生成 `run_pipeline.py`，不能修改： - `_skill_helpers/` - `skills/` 源码 - `run_inputs/` 生成代码执行前必须通过： 1. Python 编译检查。 2. `static_guard` AST 和文本安全检查。 3. `contract_check` 文件、import、DAG 和状态流契约检查。 `static_guard` 禁止的主要能力包括： - `subprocess` - `os.system` - `eval` / `exec` / `compile` - `requests` / `httpx` / `socket` / `urllib` - `open` - 原始 `skills/` 路径 - Windows 或 POSIX 本机绝对路径 状态流契约包括： - `train_lgb` 返回 `(model, report)`。 - 评估和解释必须使用 `report["X_test"]`。 - 不允许从原始 `test_df` 重新构造评估特征。 - LLM Pipeline 必须跳过尚未支持的 `cap_diagnose_and_tune`。 - recipe 特征必须调用 vendored `feat_from_recipe()`。 ## Repair 与 Fallback LLM 生成或执行失败后的顺序为： ```text LLM initial -> LLM repair，最多 2 次 -> template generated fallback -> executor.py fallback ``` 运行摘要会记录： - `codegen_orchestrator` - `llm_attempt_count` - `final_pipeline_source` - `codegen_fallback_used` - `execution_fallback_used` - `failure_reason` ## 输出目录 每次运行创建独立的时间目录；同一秒内重复运行会追加 `_01`、`_02`： ```text outputs/20260618_111511/ sample_pump_telemetry.profile.json ifpp_dag_plan.json ifpp_dag_validation.json ifpp_dag_run_status.json ifpp_run_summary.json run_pipeline.py run_pipeline_status.json run_pipeline.stdout.txt run_pipeline.stderr.txt run.log vendor_manifest.json fallback_summary.json final_report.md 30s_guide.json run_inputs/ _skill_helpers/ run_artifacts/ ``` LLM 模式还会生成： ```text codegen_context.json codegen_attempts.jsonl static_guard.json contract_check.json llm_attempt_*.* ``` local 编排还会写入 `codegen_prompt.md` 和 `codegen_repair_prompt_*.md`。 `run.log` 在每次 `ifpp-full` 和 `ifpp-check` 运行时自动创建，汇总主进程 stdout/stderr、CrewAI verbose 输出、未捕获异常、运行完成事件，以及 generated Pipeline 子进程的 stdout/stderr。子进程原始输出仍同时保留在 `run_pipeline.stdout.txt` 和 `run_pipeline.stderr.txt`。 template/generated 输出目录包含输入数据和 vendored helper，可以复制到独立目录后执行： ```bash python run_pipeline.py ``` ## 项目结构 ```text src/ifpp_skill_crewai_agent/ main.py CLI 和主流程 planner.py CrewAI DAG 生成与 DAG repair profile_builder.py CSV 数据画像 validation.py DAG 校验和默认参数补全 vendor.py 输入数据与 skill helper vendoring pipeline_codegen.py template Pipeline 生成 pipeline_runner.py 子进程执行、超时和状态落盘 run_logging.py 每次运行的统一 stdout/stderr 和事件日志 codegen_context.py LLM 结构化上下文 codegen_flow.py CrewAI codegen/audit/diagnose/repair 编排 codegen_attempts.py 每次 LLM 尝试独立归档 code_agent.py local LLM 初次生成 code_repair.py local LLM repair static_guard.py AST 和文本安全检查 contract_check.py Pipeline 契约检查 artifact_validator.py 最终产物完整性验证工具 executor.py DAG 直接执行 fallback reporter.py final_report 和 30s guide llm.py CrewAI LLM 配置 ``` ## 环境变量 复制示例配置： ```powershell Copy-Item .env.example .env ``` OpenAI： ```env MODEL=gpt-4o-mini OPENAI_API_KEY=sk-xxxx CREWAI_TRACING_ENABLED=false ``` OpenAI-compatible： ```env MODEL=deepseek/deepseek-chat OPENAI_API_KEY=your_key OPENAI_BASE_URL=https://api.deepseek.com CREWAI_TRACING_ENABLED=false ``` `mock + template` 不需要 API Key；`--mode crew` 或 `--codegen-mode llm` 需要可用的 LLM 配置。 ## 测试与构建 运行完整测试： ```bash uv run python -m unittest discover -s tests ``` 构建发行包： ```bash uv build ``` 当前共有 24 个测试，覆盖 template 回归、codegen context、attempt ledger、状态流契约、static guard、contract check、repair、runner timeout 和产物验证。 ## 设计文档 - [方案 B 与方案 C 对比](docs/方案B_vs_方案C_对比.md) - [方案 C LLM Pipeline 升级规划](docs/planning/20260617_方案C_LLM生成Pipeline升级规划.md) - [CrewAI 管理 Pipeline 代码生成审计重写规划](docs/planning/20260618_CrewAI管理Pipeline代码生成审计重写_完整修复规划文档.md)