aiecs 1.0.1__py3-none-any.whl → 1.7.6__py3-none-any.whl

aiecs/scripts/tools_develop/README_CONFIG_CHECKER.md

@@ -0,0 +1,273 @@
+# 工具配置检查器使用指南
+
+这个脚本用于检查所有注册工具的配置设置是否正确，并生成配置模板和文档，方便开发者配置和使用。
+
+## 功能特性
+
+✅ **配置验证**
+- 检查所有工具是否正确使用 `self._config_obj`
+- 验证 `__init__` 方法是否调用 `super().__init__()`
+- 检测错误的配置模式
+
+✅ **配置信息展示**
+- 显示每个工具的配置字段
+- 标识必需字段和可选字段
+- 显示字段类型、默认值和描述
+
+✅ **模板生成**
+- 生成 JSON 格式的配置模板
+- 生成 Markdown 格式的配置文档
+- 提供配置示例和环境变量映射
+
+## 使用方法
+
+### 1. 基本检查
+
+检查所有工具的配置是否正确：
+
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py
+```
+
+输出示例：
+```
+================================================================================
+检查所有注册工具的配置设置
+================================================================================
+
+找到 29 个工具文件
+
+✅ 正确配置 (29 个)
+❌ 需要修复 (0 个)
+📝 无需配置 (0 个)
+```
+
+### 2. 显示详细配置信息
+
+查看每个工具的详细配置字段：
+
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --show-config
+```
+
+输出示例：
+```
+✓ APISourceTool
+  文件: ../tools/apisource/tool.py
+  配置字段 (11 个):
+    • fred_api_key: Optional[str]
+      🔴 必需
+      默认值: None
+      说明: API key for FRED API
+    • newsapi_api_key: Optional[str]
+      🟢 可选
+      默认值: None
+      说明: API key for News API
+    ...
+```
+
+### 3. 生成 JSON 配置模板
+
+生成 JSON 格式的配置模板文件：
+
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --generate-template
+```
+
+默认输出文件：`tools_config_template.json`
+
+自定义输出路径：
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --generate-template --output /path/to/config.json
+```
+
+### 4. 生成 Markdown 配置文档
+
+生成 Markdown 格式的配置文档：
+
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --generate-markdown
+```
+
+默认输出文件：`TOOLS_CONFIG_GUIDE.md`
+
+自定义输出路径：
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --generate-markdown --markdown-output /path/to/guide.md
+```
+
+### 5. 组合使用
+
+同时执行多个操作：
+
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py \
+  --show-config \
+  --generate-template \
+  --generate-markdown
+```
+
+## 输出文件说明
+
+### 1. tools_config_template.json
+
+JSON 格式的配置模板，包含所有工具的配置字段：
+
+```json
+{
+  "APISourceTool": {
+    "fred_api_key": {
+      "value": "your_fred_api_key_here",
+      "type": "Optional[str]",
+      "required": true,
+      "description": "API key for FRED API"
+    },
+    ...
+  }
+}
+```
+
+### 2. TOOLS_CONFIG_GUIDE.md
+
+Markdown 格式的完整配置指南，包含：
+- 目录索引
+- 每个工具的配置表格
+- 配置示例代码
+- 环境变量映射
+
+## 命令行参数
+
+| 参数 | 说明 |
+|------|------|
+| `--show-config` | 显示每个工具的详细配置信息 |
+| `--generate-template` | 生成 JSON 格式配置模板文件 |
+| `--generate-markdown` | 生成 Markdown 格式配置文档 |
+| `--output PATH` | 指定 JSON 模板输出路径 |
+| `--markdown-output PATH` | 指定 Markdown 文档输出路径 |
+| `-h, --help` | 显示帮助信息 |
+
+## 配置状态说明
+
+脚本会检查并报告以下状态：
+
+### ✅ 正确配置 (CORRECT)
+工具正确使用了 `self._config_obj` 模式：
+```python
+self.config = self._config_obj if self._config_obj else self.Config()
+```
+
+### ❌ 错误配置 (INCORRECT)
+工具直接创建了 Config 对象，未使用 `self._config_obj`
+
+### ⚠️ 混合模式 (MIXED)
+工具同时包含正确和错误的配置模式
+
+### 📝 无 Config 类 (NO_CONFIG)
+工具没有定义 Config 类（可能不需要配置）
+
+### 📝 无 __init__ 方法 (NO_INIT)
+工具没有自定义的 `__init__` 方法
+
+## 最佳实践
+
+### 1. 定期检查
+
+在开发过程中定期运行检查，确保所有工具配置正确：
+
+```bash
+# 在提交代码前运行
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py
+```
+
+### 2. 更新文档
+
+当添加或修改工具配置时，重新生成文档：
+
+```bash
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --generate-markdown
+```
+
+### 3. 使用配置模板
+
+新项目或环境配置时，使用生成的 JSON 模板作为起点：
+
+```bash
+# 生成模板
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --generate-template
+
+# 根据模板配置工具
+# 编辑 tools_config_template.json
+```
+
+### 4. 查阅配置文档
+
+配置工具前，先查阅 `TOOLS_CONFIG_GUIDE.md` 了解各字段含义：
+
+```bash
+# 生成配置文档
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --generate-markdown
+
+# 查看文档
+less TOOLS_CONFIG_GUIDE.md
+```
+
+## 故障排查
+
+### 问题：脚本无法找到工具文件
+
+**解决方案**：确保在项目根目录运行脚本
+
+```bash
+cd /path/to/python-middleware-dev
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py
+```
+
+### 问题：配置检查失败
+
+**解决方案**：查看详细错误信息，修正工具的 `__init__` 方法
+
+```bash
+# 查看详细信息
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --show-config
+```
+
+### 问题：生成的文档不完整
+
+**解决方案**：检查工具的 Config 类是否正确定义，字段是否有完整的类型注解
+
+## 开发说明
+
+### 扩展功能
+
+如需扩展脚本功能，可修改以下函数：
+
+- `extract_config_fields()`: 提取配置字段信息
+- `generate_config_template()`: 生成 JSON 模板
+- `generate_markdown_doc()`: 生成 Markdown 文档
+- `print_config_details()`: 打印配置详情
+
+### 测试
+
+确保脚本能正确处理各种配置模式：
+
+```bash
+# 运行完整测试
+poetry run python aiecs/scripts/tools_develop/check_all_tools_config.py --show-config --generate-template --generate-markdown
+```
+
+## 相关文件
+
+- `check_all_tools_config.py`: 主脚本
+- `test_all_tools_config_runtime.py`: 运行时配置测试
+- `tools_config_template.json`: 生成的 JSON 配置模板
+- `TOOLS_CONFIG_GUIDE.md`: 生成的 Markdown 配置文档
+
+## 总结
+
+这个工具帮助开发者：
+- ✅ 确保所有工具配置正确
+- 📝 快速查看工具配置参数
+- 🚀 快速生成配置模板
+- 📖 自动生成配置文档
+
+使其成为 AIECS 项目开发和部署的重要辅助工具。