@dtt_siye/atool 1.3.1 → 1.5.0

package/skills/ai-project-architecture/rules/architecture-validation.md

@@ -0,0 +1,200 @@
+# Architecture Validation - 架构验证
+
+## 验证原则
+
+所有 AI 项目必须遵循 `PROJECT_STRUCTURE.md` 中定义的架构。偏差需要明确文档化和批准。
+
+## 关键架构检查点
+
+### 1. 目录结构验证
+```bash
+# 必需目录
+agents/
+apps/
+core/
+configs/
+
+# 条件目录（按需）
+models/  # 仅当共享模型时
+tests/   # 推荐
+```
+
+### 2. 代理结构验证
+每个 `agents/{agent_name}/` 必须：
+- `nodes/` - 处理节点
+- `services/` - 业务服务
+- `models/api.py` - API 模型
+- `tools/` - 工具函数
+
+条件必需（按需）：
+- `graph.py` - LangGraph 图定义
+- `checkpoint.py` - 状态持久化
+- `views.py` - HTTP 端点
+- `models/orm.py` - ORM 模型
+- `models/state.py` - 自定义状态
+
+### 3. 命名约定
+- 目录：小写，kebab-case（`user-notifications`）
+- 文件：小写，snake_case（`user_notifications.py`）
+- 类：PascalCase（`UserNotifications`）
+- 函数：snake_case（`send_notification`）
+- 常量：UPPER_SNAKE_CASE
+
+### 4. 关注点分离
+```
+core/          # 横切关注点（日志、异常等）
+apps/          # 应用程序逻辑
+agents/        # 业务代理
+├── nodes/      # 纯函数，无副作用
+├── services/    # 业务逻辑，可依赖 nodes
+└── models/     # 数据模型和 API
+configs/       # 配置管理
+```
+
+## 验证流程
+
+### 1. 结构扫描
+```bash
+find . -type d -name "agents" | head -1
+find . -type d -name "apps" | head -1
+find . -type d -name "core" | head -1
+find . -type d -name "configs" | head -1
+```
+
+### 2. 代理深度检查
+对每个代理：
+```bash
+agent_path="agents/{agent_name}"
+required_dirs=["nodes", "services", "tools"]
+for dir in required_dirs; do
+    test -d "$agent_path/$dir" || echo "Missing: $dir"
+done
+```
+
+### 3. 导入验证
+```bash
+# 检查绝对导入
+grep -r "from apps\." agents/
+grep -r "from core\." agents/
+grep -r "from agents\." agents/
+
+# 检查相对导入
+grep -r "from \.\." agents/
+```
+
+### 4. 依赖分析
+```bash
+# 生成依赖图
+grep -r "import.*agents\." . | grep -v "__pycache__" > dependencies.txt
+grep -r "import.*apps\." . | grep -v "__pycache__" >> dependencies.txt
+```
+
+## 常见架构问题
+
+### 1. 循环依赖
+```python
+# agents/user_agent/services.py
+from agents/order_agent.services import OrderService
+
+# agents/order_agent/services.py
+from agents/user_agent.services import UserService  # 循环！
+```
+
+**解决方案**：提取共享服务到 `apps/`
+
+### 2. 关注点混合
+```python
+# agents/chatbot/nodes.py
+# 错误：包含业务逻辑
+def process_message(message):
+    # 数据库操作
+    db.session.add(...)
+    # 业务逻辑
+    response = generate_response(...)
+    # 调用其他服务
+    payment_service.charge(...)
+    return response
+```
+
+**解决方案**：
+```python
+# agents/chatbot/nodes.py
+def process_message(message):
+    # 仅协调逻辑
+    processed = message_processor.run(message)
+    response = responder.generate(processed)
+    return response
+
+# agents/chatbot/services/message_processor.py
+def run(message):
+    # 业务逻辑
+    # 数据库操作
+    # 调用其他服务
+```
+
+### 3. 配置硬编码
+```python
+# 错误
+API_KEY = "sk-123456"
+```
+
+**解决方案**：
+```python
+# 正确
+from configs.app_config import get_config
+API_KEY = get_config().openai_api_key
+```
+
+## 架构违规严重等级
+
+| 等级 | 描述 | 行动 |
+|------|------|------|
+| CRITICAL | 缺少必需目录/结构 | 阻止开发，必须修复 |
+| HIGH | 违反关注点分离 | 影响维护性，尽快修复 |
+| MEDIUM | 命名约定违规 | 影响可读性，计划修复 |
+| LOW | 次优结构 | 信息性，可选修复 |
+
+## 验证工具
+
+### 1. 结构验证脚本
+```python
+#!/usr/bin/env python3
+import os
+from pathlib import Path
+
+def validate_structure(root):
+    errors = []
+    required = ["agents", "apps", "core", "configs"]
+
+    for dir in required:
+        if not (root / dir).exists():
+            errors.append(f"Missing required directory: {dir}")
+
+    return errors
+```
+
+### 2. 导入验证脚本
+```python
+#!/usr/bin/env python3
+import ast
+import sys
+
+def check_imports(file_path):
+    with open(file_path) as f:
+        tree = ast.parse(f.read())
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                print(f"Import: {alias.name}")
+        elif isinstance(node, ast.ImportFrom):
+            print(f"From: {node.module} names: {[alias.name for alias in node.names]}")
+```
+
+## 通过标准
+- 无 CRITICAL 架构违规
+- 所有必需目录存在
+- 代理结构正确
+- 无循环依赖
+- 导入路径正确
+- 关注点分离正确

package/skills/ai-project-architecture/rules/compliance-check.md

@@ -0,0 +1,83 @@
+# Compliance Assessment - 合规性评估
+
+## 执行步骤
+
+### 1. 组件分类（按需求层级）
+**Tier 1（必需组件）** - 缺失 = CRITICAL
+- 顶层：`agents/`, `apps/`, `core/`, `configs/`
+- 每个代理：`nodes/`, `services/`, `models/api.py`, `tools/`
+
+**Tier 2（条件必需组件）** - 条件满足时缺失 = HIGH
+- `models/` 根目录（仅当跨代理共享 ORM 模型时）
+- 代理的 `models/orm.py`（仅当代理有独立数据库表时）
+- 代理的 `models/state.py`（仅当代理使用自定义 LangGraph 状态时）
+- 代理的 `graph.py`（仅当代理使用 LangGraph 时）
+- 代理的 `checkpoint.py`（仅当代理使用状态持久化时）
+- 代理的 `views.py`（仅当代理暴露 HTTP 端点时）
+- 代理的 `constants.py`（可选）
+
+**Tier 3（可选组件）** - 缺失 = LOW（信息性）
+- `tests/`, `bin/`, `docs/`, `logs/`, `temp/`
+
+### 2. Tier 2 组件条件检测
+- 检查数据库操作 → 需要 `models/` 根目录
+- 检查导入 StateGraph → 需要 `graph.py`
+- 检查使用 @router 或 APIRouter → 需要 `views.py`
+- 检查使用 checkpoint/checkpointer → 需要 `checkpoint.py`
+- 检查有 ORM 模型 → 需要 `models/orm.py`
+- 检查使用 TypedDict 或自定义状态 → 需要 `models/state.py`
+
+### 3. 目录结构扫描
+- 检查 Tier 1 目录
+- 检查 Tier 2 目录（条件满足时）
+- 检查 Tier 3 目录
+
+### 4. 代理结构验证
+对每个 `agents/{agent_name}/`：
+- Tier 1：`nodes/`, `services/`, `models/api.py`, `tools/`
+- Tier 2：`graph.py`, `checkpoint.py`, `views.py`, `models/orm.py`, `models/state.py`
+- Tier 3：`constants.py`
+
+### 5. 合规缺口识别
+- 缺失 Tier 1 组件（CRITICAL）
+- 缺失条件满足的 Tier 2 组件（HIGH）
+- 命名约定违规
+- 关注点混合
+
+### 6. 生成合规报告
+- 整体合规得分（百分比）
+- 严重等级：CRITICAL/HIGH/MEDIUM/LOW
+- 组件分类
+- 建议和优先级
+
+## 输出示例
+
+```
+## Compliance Report: AI Project Structure
+
+### Overall Score: 65%
+
+### Critical Issues (3)
+- Missing `core/` directory
+- Agent 'chatbot' missing required `tools/` directory
+- Missing `configs/app_config.py`
+
+### High Issues (5)
+- Agent 'chatbot' missing `graph.py` (uses LangGraph)
+- Missing shared `models/` directory
+- Agent 'payment' missing `views.py` (exposes API endpoints)
+- Naming violation: 'Services' should be 'services'
+
+### Recommendations
+1. Create missing Tier 1 directories
+2. Add required agent components
+3. Fix naming conventions
+```
+
+## 质量检查清单
+- [ ] 所有组件按 Tier 分类
+- [ ] Tier 2 条件已检测
+- [ ] 目录结构已扫描
+- [ ] 代理结构已验证
+- [ ] 合规缺口已识别
+- [ ] 合规报告已生成

package/skills/ai-project-architecture/rules/iron-laws.md

@@ -0,0 +1,188 @@
+# Iron Laws - 铁律
+
+## 核心原则
+
+违反以下铁律即违反技能精神，必须立即停止。
+
+### Iron Law 1: NO FABRICATION
+```
+绝不假设或编造代码行为
+仅处理已验证、存在的代码
+```
+
+**违规示例**：
+```python
+# 错误：假设函数存在
+def migrate_agent(agent_name):
+    # 假设 agent 有 settings 属性
+    if agent.settings.enabled:  # 可能不存在！
+        migrate_features(agent)
+
+# 正确：先验证
+def migrate_agent(agent_name):
+    agent = load_agent(agent_name)
+    if hasattr(agent, 'settings') and agent.settings.enabled:
+        migrate_features(agent)
+```
+
+### Iron Law 2: NO NEW FEATURES DURING REFACTORING
+```
+重构 = 仅结构变更
+任何行为变更都是违规
+```
+
+**违规示例**：
+```python
+# 错误：重构时添加新功能
+def old_process_data(data):
+    return data.strip()
+
+def new_process_data(data):
+    # 重构时添加了新逻辑
+    cleaned = data.strip()
+    if not cleaned:
+        return "EMPTY"  # 新增行为！
+    return cleaned
+
+# 正确：仅结构变更
+def new_process_data(data):
+    return data.strip()  # 完全相同
+```
+
+### Iron Law 3: INCREMENTAL EXECUTION
+```
+分单代理批次执行
+每批后自检
+```
+
+**违规示例**：
+```python
+# 错误：一次性迁移所有代理
+def migrate_all_agents():
+    # 同时迁移 10 个代理
+    migrate_user_agent()
+    migrate_order_agent()
+    migrate_payment_agent()
+    # ... 7 个更多
+    verify_all()  # 太晚了！
+
+# 正确：分批执行
+def migrate_all_agents():
+    # 批次 1
+    migrate_user_agent()
+    verify_user_agent()
+
+    # 批次 2
+    migrate_order_agent()
+    verify_order_agent()
+```
+
+### Iron Law 4: MANDATORY QUALITY GATES
+```
+systematic-debugging 审查是必需的
+每个代码完成阶段后必须调用
+```
+
+**违规示例**：
+```python
+# 错误：跳过质量检查
+def migrate_agent(agent_name):
+    migrate_files(agent_name)
+    # 跳过检查！
+    return "done"
+
+# 正确：必需调用
+def migrate_agent(agent_name):
+    migrate_files(agent_name)
+    systematic_debugging.review("迁移完成", get_changes())
+    return "done"
+```
+
+### Iron Law 5: SKILL INTEGRATION
+```
+此技能不能独立运行
+必须在指定点调用所需技能
+```
+
+**违规示例**：
+```python
+# 错误：独立运行
+def refactor_project():
+    # 未调用必需技能
+    scan_structure()
+    migrate_files()
+    return "done"
+
+# 正确：调用必需技能
+def refactor_project():
+    scan_structure()
+    software_architecture.validate()
+    migrate_files()
+    test_driven_development.write_tests()
+```
+
+## 红旗标志 - 停止并重新评估
+
+如果出现以下想法，立即停止：
+
+| 想法 | 现实 | 行动 |
+|------|------|------|
+| "就这一次，我会添加这个小改进" | 违反 Iron Law 2 - 立即停止 | 删除改进，正确迁移 |
+| "我以后会正确重构" | 以后永远不会 - 技术债务累积 | 现在就做对，或者不做 |
+| "这个小功能不会影响迁移" | 违反精确迁移原则 | 功能蔓延 = 迁移失败 |
+| "迁移后测试更快" | 未测试的迁移是未验证的迁移 | 使用 test-driven-development，无例外 |
+| "systematic-debugging 太耗时" | 比调试生产问题更快 | 质量关卡不可协商 |
+
+## 质量关卡检查
+
+### 每个迁移批次后
+1. 自检清单完成
+2. **调用 systematic-debugging（必需）**
+3. 所有导入正确解析
+4. 无语法错误
+5. 现有测试通过
+
+### 迁移完成后
+1. **调用 systematic-debugging（必需）**
+2. 所有验证检查通过
+3. 无行为变更
+4. 所有交叉引用已更新
+
+## 违反处理
+
+### 发现违规时
+1. **立即停止**当前操作
+2. 记录违规行为
+3. 决定：
+   - 如果小错误：修复并继续
+   - 如果严重违规：回滚并重新开始
+
+### 回滚策略
+```bash
+# 回滚单个代理
+git checkout HEAD~1  # 回到上一个提交
+rm -rf agents/new_agent  # 删除新结构
+git add agents/old_agent  # 恢复旧结构
+```
+
+## 例外情况
+
+**例外需要用户明确覆盖**：
+```python
+# 仅当用户明确允许时
+if user_explicit_override:
+    # 可以临时违反铁律
+    pass
+else:
+    # 严格执行
+    raise ViolationError("Iron Law violated")
+```
+
+## 记录和报告
+
+所有违规必须记录：
+- 违律的铁律编号
+- 违规描述
+- 如何检测到的
+- 如何修复的
+- 最终结果

package/skills/ai-project-architecture/rules/migration.md

@@ -0,0 +1,94 @@
+# Structure Migration - 结构迁移
+
+## 核心原则（不可协商）
+
+### Iron Laws
+1. **NO FABRICATION** - 不假设或编造代码行为
+2. **NO NEW FEATURES** - 仅结构变更，无功能添加
+3. **INCREMENTAL EXECUTION** - 单代理批次执行
+4. **MANDATORY QUALITY GATES** - 每阶段后必须调用 systematic-debugging
+5. **SKILL INTEGRATION** - 必须调用必需技能
+
+## 执行步骤
+
+### 1. 创建新目录结构
+- 按 `PROJECT_STRUCTURE.md` 创建标准目录
+- 不要删除旧结构
+- 使用并行结构：`new_agents/`, `new_apps/` 等
+
+### 2. 迁移共享组件（优先）
+迁移顺序：
+1. `apps/`（LLM 管理、utils、logs API）
+2. `core/`（异常、中间件、日志等）
+3. `models/`（共享 ORM 模型）
+4. `configs/`（所有配置文件）
+5. 更新所有导入语句
+
+### 3. 迁移代理（按优先级）
+对每个代理：
+1. 创建 `agents/{agent_name}/` 及子目录
+2. 迁移 `nodes/` → `agents/{agent_name}/nodes/`
+3. 迁移 `services/` → `agents/{agent_name}/services/`
+4. 迁移 `models/` → `agents/{agent_name}/models/`
+5. 迁移 `tools/` → `agents/{agent_name}/tools/`
+6. 迁移可选文件（graph.py, checkpoint.py, views.py, constants.py）
+7. 更新所有导入语句：
+   - 旧：`from old_apps.xyz import ABC`
+   - 新：`from apps.xyz import ABC`
+
+### 4. 更新交叉引用
+- 更新所有迁移文件的导入
+- 更新配置文件中的引用
+- 更新文档中的引用
+- 搜索旧路径并替换为新路径
+
+### 5. 验证每个批次
+```bash
+# 语法检查
+python -m py_compile
+
+# 运行现有测试
+pytest
+
+# 验证导入解析
+python -c "import agents.{agent_name}"
+```
+
+## 禁止事项（违反即停止）
+
+| 禁止行为 | 原因 | 正确做法 |
+|---------|------|---------|
+| 添加新功能 | 违反 exact preservation | 仅做结构迁移 |
+| "顺手修复" | 功能蔓延 | 保持原样，后期专门处理 |
+| 优化代码 | 可能改变行为 | 完全保持原逻辑 |
+| 跳过测试 | 无法验证正确性 | 必须运行测试 |
+| 忽略导入更新 | 会导致运行时错误 | 立即更新并验证 |
+
+## 验证清单
+- [ ] 新目录结构已创建
+- [ ] 共享组件已迁移
+- [ ] 代理按优先级迁移
+- [ ] 所有导入已更新并验证
+- [ ] 无语法错误
+- [ ] 现有测试通过
+- [ ] 无新功能添加
+- [ ] 无行为变更
+- [ ] 调用了 software-architecture 技能
+- [ ] 调用了 test-driven-development 技能
+
+## 常见问题
+
+### Q: 遇到循环依赖怎么办？
+A: 迁移被依赖的代理 first，然后依赖的代理
+
+### Q: 导入路径不明确怎么办？
+A: 使用 `grep` 搜索所有导入，逐个验证
+
+### Q: 测试失败怎么办？
+A: 立即停止，修复导入或路径问题，不要继续迁移
+
+## 紧急停止条件
+- 发现任何功能改变
+- 无法修复的导入错误
+- 测试失败且无法快速修复
+- 需要添加新功能

package/skills/ai-project-architecture/rules/refactoring.md

@@ -0,0 +1,91 @@
+# Refactoring Planning - 重构规划
+
+## 执行步骤
+
+### 1. 记录当前结构
+创建 `old_structure.md` 包含：
+- 当前目录树
+- 当前代理列表
+- 当前文件位置
+- 导入依赖图
+
+### 2. 创建迁移映射
+文件/目录映射：old_path → new_path
+- 识别共享/公共组件
+- 识别代理特定组件
+- 标记任何模糊情况
+
+### 3. 按优先级排序迁移
+顺序：
+1. 共享组件（apps/, core/, models/）
+2. 独立代理（不依赖其他代理）
+3. 依赖代理（依赖已迁移的代理）
+4. 代理特定配置和工具
+
+### 4. 定义迁移批次
+- 每个批次 = 可独立验证单元
+- 优先：每个代理一个批次
+- 大型代理：拆分为 nodes/, services/, models/, tools/ 批次
+- 每个批次必须有明确的入口/退出条件
+
+### 5. 创建回滚计划
+- 每个批次：失败时如何回滚
+- 检查点：每个成功批次后提交
+- 验证：必须通过测试才能继续
+
+## 迁移映射示例
+
+```yaml
+migration_mapping:
+  shared_components:
+    old/old_apps/ → new/apps/
+    old/old_core/ → new/core/
+    old/shared_models/ → new/models/
+
+  agents:
+    agent_chatbot:
+      old/chatbot/ → new/agents/chatbot/
+      old/chatbot_nodes/ → new/agents/chatbot/nodes/
+      old/chatbot_services/ → new/agents/chatbot/services/
+
+  dependencies:
+    old/chatbot_payment/ → new/agents/chatbot_payment/
+    # 依赖 chatbot 已先迁移
+```
+
+## 迁移批次示例
+
+```yaml
+migration_batches:
+  batch_1:
+    components: ["apps", "core", "models"]
+    dependencies: []
+    rollback: "删除 new_ 前缀目录"
+
+  batch_2:
+    components: ["agents/chatbot"]
+    dependencies: ["batch_1"]
+    rollback: "删除 agents/chatbot，恢复旧导入"
+
+  batch_3:
+    components: ["agents/payment"]
+    dependencies: ["batch_1", "batch_2"]
+    rollback: "删除 agents/payment，恢复旧导入"
+```
+
+## 风险评估
+
+| 风险级别 | 描述 | 应对措施 |
+|---------|------|---------|
+| HIGH | 跨代理依赖 | 提前识别依赖顺序，先迁移被依赖方 |
+| MEDIUM | 导入路径更新 | 使用全局搜索替换，验证每个导入 |
+| LOW | 配置文件引用 | 迁移后立即测试配置加载 |
+
+## 验证清单
+- [ ] 当前结构已记录
+- [ ] 迁移映射已创建
+- [ ] 迁移顺序已定义
+- [ ] 批次已识别
+- [ ] 回滚计划已定义
+- [ ] software-architecture 技能已咨询
+- [ ] 用户批准已获得（必需）