feat: 更新模块文档，添加详细说明和使用示例

tests/test_permissions.py

@@ -30,7 +30,7 @@ class TestToolPermission:
             name="test_tool",
             danger_level=DangerLevel.SAFE,
         )
-        
+
         assert perm.requires_confirmation is False
         assert perm.rate_limit is None
 
@@ -45,7 +45,7 @@ class TestPermissionManager:
     def test_get_default_permission(self):
         """测试获取默认权限"""
         perm = self.manager.get_permission("read_file")
-        
+
         assert perm is not None
         assert perm.danger_level == DangerLevel.SAFE
 
@@ -57,7 +57,7 @@ class TestPermissionManager:
             description="自定义工具",
         )
         self.manager.register_tool(perm)
-        
+
         result = self.manager.get_permission("custom_tool")
         assert result is not None
         assert result.danger_level == DangerLevel.MEDIUM
@@ -65,13 +65,13 @@ class TestPermissionManager:
     def test_check_permission_allowed(self):
         """测试权限检查 - 允许"""
         allowed, reason = self.manager.check_permission("read_file")
-        
+
         assert allowed is True
 
     def test_check_permission_unknown_tool(self):
         """测试权限检查 - 未知工具"""
         allowed, reason = self.manager.check_permission("unknown_tool")
-        
+
         assert allowed is False
         assert "未知工具" in reason
 
@@ -83,12 +83,12 @@ class TestPermissionManager:
             denied_paths=["/etc/", "/root/"],
         )
         self.manager.register_tool(perm)
-        
+
         allowed, reason = self.manager.check_permission(
             "restricted_read",
             params={"path": "/etc/passwd"},
         )
-        
+
         assert allowed is False
         assert "禁止访问" in reason
 
@@ -96,7 +96,7 @@ class TestPermissionManager:
         """测试确认要求 - 按等级"""
         # HIGH 级别需要确认
         assert self.manager.requires_confirmation("delete_file") is True
-        
+
         # SAFE 级别不需要确认
         assert self.manager.requires_confirmation("read_file") is False
 
@@ -108,7 +108,7 @@ class TestPermissionManager:
             requires_confirmation=True,
         )
         self.manager.register_tool(perm)
-        
+
         assert self.manager.requires_confirmation("explicit_confirm") is True
 
     @pytest.mark.asyncio
@@ -119,9 +119,9 @@ class TestPermissionManager:
             tool_name="delete_file",
             params={"path": "/test.txt"},
         )
-        
+
         assert request.status == ConfirmationStatus.PENDING
-        
+
         # 批准
         self.manager.approve_confirmation("req-1")
         assert request.status == ConfirmationStatus.APPROVED
@@ -134,7 +134,7 @@ class TestPermissionManager:
             tool_name="delete_file",
             params={"path": "/test.txt"},
         )
-        
+
         self.manager.deny_confirmation("req-2")
         assert request.status == ConfirmationStatus.DENIED
 
@@ -146,7 +146,7 @@ class TestPermissionManager:
             tool_name="test",
             params={},
         )
-        
+
         pending = self.manager.get_pending_confirmations()
         assert len(pending) >= 1
 
@@ -157,48 +157,48 @@ class TestToolRegistry:
     def test_import_registry(self):
         """测试导入注册中心"""
         from minenasai.agent import ToolRegistry, get_tool_registry
-        
+
         registry = get_tool_registry()
         assert isinstance(registry, ToolRegistry)
 
     def test_register_builtin_tools(self):
         """测试注册内置工具"""
         from minenasai.agent import get_tool_registry, register_builtin_tools
-        
+
         registry = get_tool_registry()
         initial_count = len(registry.list_tools())
-        
+
         register_builtin_tools()
-        
+
         # 应该有更多工具
         new_count = len(registry.list_tools())
         assert new_count >= initial_count
 
     def test_tool_decorator(self):
         """测试工具装饰器"""
-        from minenasai.agent import tool, get_tool_registry
-        
+        from minenasai.agent import get_tool_registry, tool
+
         @tool(name="decorated_tool", description="装饰器测试")
         async def decorated_tool(param: str) -> dict:
             return {"result": param}
-        
+
         registry = get_tool_registry()
         tool_obj = registry.get("decorated_tool")
-        
+
         assert tool_obj is not None
         assert tool_obj.description == "装饰器测试"
 
     @pytest.mark.asyncio
     async def test_execute_tool(self):
         """测试执行工具"""
-        from minenasai.agent import get_tool_registry, DangerLevel
-        
+        from minenasai.agent import DangerLevel, get_tool_registry
+
         registry = get_tool_registry()
-        
+
         # 注册测试工具
         async def echo(message: str) -> dict:
             return {"echo": message}
-        
+
         registry.register(
             name="echo",
             description="回显消息",
@@ -210,18 +210,18 @@ class TestToolRegistry:
             },
             danger_level=DangerLevel.SAFE,
         )
-        
+
         result = await registry.execute("echo", {"message": "hello"})
-        
+
         assert result["success"] is True
         assert result["result"]["echo"] == "hello"
 
     def test_get_stats(self):
         """测试获取统计"""
         from minenasai.agent import get_tool_registry
-        
+
         registry = get_tool_registry()
         stats = registry.get_stats()
-        
+
         assert "total_tools" in stats
         assert "categories" in stats