JoySafeter

Category: Content & Multimedia | Uploader: jd-opensource | Downloads: 0 | Version: v1.0（Latest）

SKILL（技能）模块是平台的核心功能之一，用于管理和组织可复用的技能资源。每个技能可以包含描述、内容、标签、文件等丰富的信息，支持公开分享和私有管理。

Changelog: Source: GitHub https://github.com/jd-opensource/JoySafeter

Directory Structure

Current level: backend/app/

📁 api/
- 📁 graph/
  - 📄 variables.py 9.0 KB
- 📁 v1/
  - 📁 memory/
    
    📄 __init__.py 66 B
    
    📄 memory.py 16.0 KB
    
    📄 schemas.py 4.1 KB
  - 📄 __init__.py 2.5 KB
  - 📄 api_keys.py 2.5 KB
  - 📄 auth.py 15.1 KB
  - 📄 chat.py 52.1 KB
  - 📄 conversations.py 33.5 KB
  - 📄 copilot_deepagents.py 6.4 KB
  - 📄 custom_tools.py 3.8 KB
  - 📄 environment.py 3.9 KB
  - 📄 files.py 25.5 KB
  - 📄 graph_deployments.py 6.9 KB
  - 📄 graph_schemas.py 4.8 KB
  - 📄 graph_tests.py 3.1 KB
  - 📄 graphs.py 35.9 KB
  - 📄 mcp.py 12.5 KB
  - 📄 MODEL.md 5.3 KB
  - 📄 model_credentials.py 4.3 KB
  - 📄 model_providers.py 2.7 KB
  - 📄 models.py 5.3 KB
  - 📄 oauth.py 14.2 KB
  - 📄 openapi_graph.py 4.8 KB
  - 📄 openclaw_chat.py 3.6 KB
  - 📄 openclaw_devices.py 3.7 KB
  - 📄 openclaw_instances.py 4.5 KB
  - 📄 openclaw_proxy.py 7.4 KB
  - 📄 organizations.py 7.6 KB
  - 📄 sandboxes.py 7.7 KB
  - 📄 sessions.py 5.1 KB
  - 📄 skills.py 8.2 KB
  - 📄 tools.py 2.6 KB
  - 📄 traces.py 7.7 KB
  - 📄 users.py 10.5 KB
  - 📄 workspace_files.py 4.9 KB
  - 📄 workspace_folders.py 8.1 KB
  - 📄 workspaces.py 12.7 KB
- 📄 __init__.py 286 B
- 📄 schemas.py 3.2 KB
📁 common/
- 📄 constants.py 243 B
- 📄 dependencies.py 9.6 KB
- 📄 exceptions.py 9.7 KB
- 📄 logging.py 4.7 KB
- 📄 openapi_auth.py 2.1 KB
- 📄 pagination.py 2.0 KB
- 📄 rate_limit.py 3.6 KB
- 📄 response.py 1.8 KB
📁 core/
- 📁 a2a/
  - 📄 __init__.py 518 B
  - 📄 client.py 16.0 KB
- 📁 agent/
  - 📁 backends/
    
    📁 utils/
    
    📄 __init__.py 459 B
    
    📄 command_executor.py 3.6 KB
    
    📄 __init__.py 1.2 KB
    
    📄 constants.py 1.2 KB
    
    📄 filesystem_sandbox.py 3.4 KB
    
    📄 pydantic_adapter.py 26.8 KB
    
    📄 runtime_config.py 6.5 KB
    
    📄 state_sandbox.py 2.6 KB
  - 📁 checkpointer/
    
    📄 checkpointer.py 8.4 KB
  - 📁 code_agent/
    
    📁 executor/
    
    📄 __init__.py 1.2 KB
    
    📄 backend_executor.py 10.5 KB
    
    📄 base.py 5.6 KB
    
    📄 docker_executor.py 10.8 KB
    
    📄 local_executor.py 9.5 KB
    
    📄 router.py 9.7 KB
    
    📁 interpreter/
    
    📄 __init__.py 1.1 KB
    
    📄 ast_evaluator.py 46.3 KB
    
    📄 security.py 10.4 KB
    
    📁 prompts/
    
    📄 planning.md 2.3 KB
    
    📄 system.md 4.0 KB
    
    📄 __init__.py 6.6 KB
    
    📄 agent.py 17.3 KB
    
    📄 compensator.py 14.2 KB
    
    📄 data_analysis.py 14.5 KB
    
    📄 loop.py 17.5 KB
    
    📄 memory.py 15.5 KB
    
    📄 monitoring.py 18.0 KB
    
    📄 parser.py 8.7 KB
    
    📄 planning.py 16.0 KB
    
    📄 tools.py 18.1 KB
    
    📄 utils.py 12.2 KB
  - 📁 memory/
    
    📁 strategies/
    
    📄 __init__.py 486 B
    
    📄 base.py 1.9 KB
    
    📄 summarize.py 8.0 KB
    
    📄 types.py 1.2 KB
    
    📄 __init__.py 580 B
    
    📄 manager.py 83.9 KB
  - 📁 midware/
    
    📄 __init__.py 358 B
    
    📄 context_enhancement.py 20.0 KB
    
    📄 logging.py 24.1 KB
    
    📄 memory_iteration_with_db.py 20.0 KB
    
    📄 performance_monitor.py 18.4 KB
    
    📄 skill_adapter.py 7.0 KB
    
    📄 SKILL_MIDDLEWARE.md 15.7 KB
    
    📄 tagging_middleware.py 334 B
  - 📄 __init__.py 346 B
  - 📄 langfuse_callback.py 8.1 KB
  - 📄 node_tools.py 11.1 KB
  - 📄 sample_agent.py 11.9 KB
- 📁 copilot/
  - 📁 tools/
    
    📄 __init__.py 1.9 KB
    
    📄 analysis.py 7.8 KB
    
    📄 context.py 1.2 KB
    
    📄 core.py 13.2 KB
    
    📄 layout.py 7.4 KB
    
    📄 models.py 2.2 KB
    
    📄 registry.py 3.6 KB
    
    📄 think.py 14.5 KB
  - 📄 __init__.py 2.7 KB
  - 📄 action_applier.py 8.8 KB
  - 📄 action_types.py 4.6 KB
  - 📄 action_validator.py 7.5 KB
  - 📄 agent.py 5.7 KB
  - 📄 exceptions.py 3.7 KB
  - 📄 graph_analyzer.py 17.5 KB
  - 📄 message_builder.py 1.6 KB
  - 📄 prompt_builder.py 19.2 KB
  - 📄 response_parser.py 10.9 KB
  - 📄 tool_output_parser.py 3.5 KB
- 📁 copilot_deepagents/
  - 📄 __init__.py 1.9 KB
  - 📄 artifacts.py 11.1 KB
  - 📄 layout.py 8.7 KB
  - 📄 manager.py 40.9 KB
  - 📄 schemas.py 5.3 KB
  - 📄 streaming.py 1.8 KB
  - 📄 subagents.py 2.2 KB
- 📁 graph/
  - 📁 deep_agents/
    
    📄 __init__.py 44 B
    
    📄 backend_factory.py 3.8 KB
    
    📄 node_config.py 7.9 KB
    
    📄 node_factory.py 13.7 KB
    
    📄 skills_manager.py 10.6 KB
  - 📁 executors/
    
    📄 action.py 4.3 KB
    
    📄 agent.py 23.9 KB
    
    📄 logic.py 24.4 KB
    
    📄 state_management.py 4.0 KB
    
    📄 tool.py 12.6 KB
    
    📄 transform.py 7.9 KB
  - 📄 __init__.py 1.3 KB
  - 📄 base_graph_builder.py 41.2 KB
  - 📄 code_generator.py 11.8 KB
  - 📄 deep_agents_builder.py 12.6 KB
  - 📄 expression_evaluator.py 20.7 KB
  - 📄 graph_builder_factory.py 3.6 KB
  - 📄 graph_compiler.py 18.5 KB
  - 📄 graph_schema.py 15.2 KB
  - 📄 graph_state.py 9.3 KB
  - 📄 mapping_utils.py 4.9 KB
  - 📄 node_executors.py 1.5 KB
  - 📄 node_secrets.py 4.3 KB
  - 📄 node_type_registry.py 12.1 KB
  - 📄 node_wrapper.py 12.4 KB
  - 📄 route_types.py 1.3 KB
  - 📄 standard_graph_builder.py 4.5 KB
  - 📄 state_variable_tracker.py 21.2 KB
  - 📄 trace_utils.py 6.3 KB
- 📁 model/
  - 📁 models/
    
    📄 __init__.py 343 B
    
    📄 base.py 2.1 KB
    
    📄 chat_model.py 1.0 KB
    
    📄 embedding_model.py 1.1 KB
    
    📄 rerank_model.py 2.4 KB
  - 📁 providers/
    
    📄 __init__.py 2.8 KB
    
    📄 Anthropic.py 7.6 KB
    
    📄 base.py 4.1 KB
    
    📄 Custom.py 13.0 KB
    
    📄 Gemini.py 8.2 KB
    
    📄 OpenaiApiCompatible.py 10.2 KB
    
    📄 PROVIDERS.md 11.6 KB
    
    📄 Zhipu.py 2.9 KB
  - 📁 utils/
    
    📄 __init__.py 464 B
    
    📄 credential_resolver.py 6.9 KB
    
    📄 encryption.py 3.5 KB
    
    📄 model_ref.py 4.5 KB
  - 📄 __init__.py 1.0 KB
  - 📄 factory.py 8.8 KB
  - 📄 MODEL.md 6.3 KB
- 📁 oauth/
  - 📁 protocols/
    
    📄 __init__.py 594 B
    
    📄 base.py 3.3 KB
    
    📄 jd_sso.py 6.5 KB
    
    📄 oauth2.py 7.5 KB
  - 📄 __init__.py 811 B
  - 📄 config.py 12.4 KB
  - 📄 factory.py 2.4 KB
- 📁 skill/
  - 📄 __init__.py 678 B
  - 📄 ARCHITECTURE.md 32.1 KB
  - 📄 exceptions.py 1.3 KB
  - 📄 formatter.py 7.4 KB
  - 📄 sandbox_loader.py 19.6 KB
  - 📄 validators.py 3.6 KB
  - 📄 yaml_parser.py 8.5 KB
- 📁 skill_developer_deepagents/
  - 📄 __init__.py 0 B
  - 📄 tools.py 2.6 KB
- 📁 tools/
  - 📁 buildin/
    
    📄 file.py 10.1 KB
    
    📄 network_tools.py 2.2 KB
    
    📄 postgres.py 11.3 KB
    
    📄 python.py 9.7 KB
    
    📄 research_tools.py 4.2 KB
    
    📄 skill_management.py 2.2 KB
    
    📄 sleep.py 641 B
    
    📄 tavily.py 10.3 KB
    
    📄 time_tools.py 1.9 KB
  - 📁 mcp/
    
    📄 __init__.py 290 B
    
    📄 mcp.py 19.2 KB
    
    📄 multi_mcp.py 19.8 KB
    
    📄 params.py 666 B
  - 📁 sandbox/
    
    📄 __init__.py 2.4 KB
    
    📄 modal.py 4.9 KB
    
    📄 runloop.py 5.0 KB
    
    📄 sandbox_factory.py 13.3 KB
  - 📁 skill/
    
    📄 __init__.py 213 B
  - 📄 agent_tool_selector.py 6.3 KB
  - 📄 mcp_tool_utils.py 8.0 KB
  - 📄 tool.py 10.9 KB
  - 📄 tool_registry.py 24.3 KB
  - 📄 toolkit.py 9.8 KB
- 📄 __init__.py 169 B
- 📄 ai_adapter.py 18.2 KB
- 📄 constants.py 441 B
- 📄 database.py 2.6 KB
- 📄 password_validation.py 1.8 KB
- 📄 rate_limit.py 5.3 KB
- 📄 redis.py 8.3 KB
- 📄 security.py 4.8 KB
- 📄 settings.py 14.6 KB
📁 models/
- 📄 __init__.py 2.6 KB
- 📄 access_control.py 3.7 KB
- 📄 api_key.py 2.0 KB
- 📄 auth.py 6.1 KB
- 📄 base.py 1.7 KB
- 📄 chat.py 2.8 KB
- 📄 conversation.py 1.7 KB
- 📄 custom_tool.py 1.2 KB
- 📄 execution_trace.py 9.0 KB
- 📄 graph.py 7.7 KB
- 📄 graph_deployment_version.py 1.9 KB
- 📄 graph_execution.py 1.9 KB
- 📄 graph_test.py 1.5 KB
- 📄 mcp.py 2.8 KB
- 📄 memory.py 2.3 KB
- 📄 message.py 17.7 KB
- 📄 MODEL.md 6.5 KB
- 📄 model_credential.py 3.0 KB
- 📄 model_instance.py 3.2 KB
- 📄 model_provider.py 2.5 KB
- 📄 oauth_account.py 2.8 KB
- 📄 openclaw_instance.py 1.6 KB
- 📄 organization.py 2.8 KB
- 📄 security_audit_log.py 2.3 KB
- 📄 settings.py 3.1 KB
- 📄 skill.py 3.5 KB
- 📄 user_sandbox.py 2.1 KB
- 📄 workspace.py 4.6 KB
- 📄 workspace_files.py 2.9 KB
📁 repositories/
- 📄 __init__.py 650 B
- 📄 api_key.py 1.0 KB
- 📄 auth_session.py 1.2 KB
- 📄 auth_user.py 1.9 KB
- 📄 base.py 6.0 KB
- 📄 custom_tool.py 1.1 KB
- 📄 graph.py 5.1 KB
- 📄 graph_deployment_version.py 7.1 KB
- 📄 graph_execution.py 839 B
- 📄 mcp_server.py 7.3 KB
- 📄 MODEL.md 8.5 KB
- 📄 model_credential.py 3.0 KB
- 📄 model_instance.py 2.6 KB
- 📄 model_provider.py 840 B
- 📄 organization.py 3.1 KB
- 📄 skill.py 3.6 KB
- 📄 user.py 1.9 KB
- 📄 workspace.py 6.2 KB
- 📄 workspace_file.py 2.9 KB
- 📄 workspace_folder.py 2.9 KB
📁 schemas/
- 📄 __init__.py 1.9 KB
- 📄 base.py 377 B
- 📄 chat.py 842 B
- 📄 common.py 1.5 KB
- 📄 conversation.py 3.2 KB
- 📄 graph_deployment_version.py 2.3 KB
- 📄 knowledge.py 1.2 KB
- 📄 mcp.py 4.4 KB
- 📄 memory.py 2.1 KB
- 📄 skill.py 5.7 KB
- 📄 user.py 1.0 KB
- 📄 validators.py 4.4 KB
📁 services/
- 📄 __init__.py 1.3 KB
- 📄 agent_service.py 4.1 KB
- 📄 api_key_service.py 4.7 KB
- 📄 auth_service.py 16.3 KB
- 📄 auth_session_service.py 6.4 KB
- 📄 base.py 489 B
- 📄 copilot_service.py 48.5 KB
- 📄 custom_tool_service.py 3.4 KB
- 📄 email_service.py 10.1 KB
- 📄 environment_service.py 2.8 KB
- 📄 graph_deployment_version_service.py 21.4 KB
- 📄 graph_service.py 32.3 KB
- 📄 login_init.py 1.4 KB
- 📄 mcp_client_service.py 6.1 KB
- 📄 mcp_server_service.py 9.4 KB
- 📄 mcp_toolkit_manager.py 6.1 KB
- 📄 memory_service.py 22.3 KB
- 📄 MODEL.md 10.8 KB
- 📄 model_credential_service.py 17.8 KB
- 📄 model_provider_service.py 20.2 KB
- 📄 model_service.py 14.8 KB
- 📄 oauth_service.py 20.0 KB
- 📄 openapi_graph_service.py 11.2 KB
- 📄 openclaw_instance_service.py 23.2 KB
- 📄 organization_service.py 15.8 KB
- 📄 sandbox_manager.py 8.1 KB
- 📄 sandbox_pool.py 5.3 KB
- 📄 schema_service.py 15.0 KB
- 📄 security_audit_service.py 4.5 KB
- 📄 session_service.py 7.4 KB
- 📄 skill_service.py 28.9 KB
- 📄 test_service.py 6.9 KB
- 📄 tool_service.py 20.8 KB
- 📄 trace_service.py 9.2 KB
- 📄 user_service.py 3.9 KB
- 📄 workflow_variable_manager.py 11.8 KB
- 📄 workspace_file_service.py 11.3 KB
- 📄 workspace_folder_service.py 13.6 KB
- 📄 workspace_permission.py 1.9 KB
- 📄 workspace_service.py 39.1 KB
📁 utils/
- 📄 __init__.py 443 B
- 📄 backend_utils.py 2.1 KB
- 📄 datetime.py 513 B
- 📄 mcp.py 14.6 KB
- 📄 mcp_tool_builder.py 4.5 KB
- 📄 media.py 16.1 KB
- 📄 message_serializer.py 5.8 KB
- 📄 path_utils.py 4.5 KB
- 📄 prompts.py 5.5 KB
- 📄 stream_event_handler.py 36.0 KB
- 📄 string.py 8.0 KB
- 📄 task_manager.py 3.1 KB
- 📄 token_usage.py 6.4 KB
- 📄 tokens.py 4.8 KB
📁 websocket/
- 📄 auth.py 1.9 KB
- 📄 chat_handler.py 9.9 KB
- 📄 connection_manager.py 3.8 KB
- 📄 copilot_handler.py 11.3 KB
- 📄 notification_manager.py 3.8 KB
- 📄 openclaw_handler.py 3.6 KB
📄 __init__.py 50 B
📄 main.py 18.2 KB
📄 MODEL.md 10.5 KB
📄 SKILL.md 13.3 KB

SKILL.md

# SKILL 后端功能说明文档

## 概述

SKILL（技能）模块是平台的核心功能之一，用于管理和组织可复用的技能资源。每个技能可以包含描述、内容、标签、文件等丰富的信息，支持公开分享和私有管理。

## 架构设计

### 分层架构

SKILL 模块采用经典的分层架构设计：

```
API Layer (api/v1/skills.py)
    ↓
Service Layer (services/skill_service.py)
    ↓
Repository Layer (repositories/skill.py)
    ↓
Model Layer (models/skill.py)
```

### 核心组件

1. **模型层 (Models)**
   - `Skill`: 技能主表模型
   - `SkillFile`: 技能文件关联表模型

2. **仓库层 (Repositories)**
   - `SkillRepository`: 技能数据访问层
   - `SkillFileRepository`: 技能文件数据访问层

3. **服务层 (Services)**
   - `SkillService`: 技能业务逻辑和权限校验

4. **API层 (API)**
   - RESTful API 端点，提供完整的 CRUD 操作

## 数据模型

### Skill 模型

技能主表，存储技能的核心信息：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 主键，自动生成 |
| `name` | String(255) | 技能名称，必填 |
| `description` | Text | 技能描述，必填 |
| `content` | Text | 技能内容，必填 |
| `tags` | JSONB | 标签列表，默认为空列表 |
| `source_type` | String(50) | 来源类型，默认为 "local" |
| `source_url` | String(1024) | 来源 URL，可选 |
| `root_path` | String(512) | 根路径，可选 |
| `owner_id` | String(255) | 拥有者 ID，外键关联 user.id |
| `created_by_id` | String(255) | 创建者 ID，外键关联 user.id，必填 |
| `is_public` | Boolean | 是否公开，默认为 False |
| `license` | String(100) | 许可证信息，可选 |
| `created_at` | DateTime | 创建时间 |
| `updated_at` | DateTime | 更新时间 |

**约束和索引：**
- 唯一约束：`(owner_id, name)` - 同一拥有者的技能名称必须唯一
- 索引：
  - `skills_owner_idx`: 拥有者索引
  - `skills_created_by_idx`: 创建者索引
  - `skills_public_idx`: 公开状态索引
  - `skills_tags_idx`: 标签 GIN 索引（支持 JSONB 查询）

### SkillFile 模型

技能文件关联表，存储技能关联的文件信息：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 主键，自动生成 |
| `skill_id` | UUID | 技能 ID，外键关联 skills.id |
| `path` | String(512) | 文件路径，必填 |
| `file_name` | String(255) | 文件名，必填 |
| `file_type` | String(50) | 文件类型，必填 |
| `content` | Text | 文件内容，可选 |
| `storage_type` | String(20) | 存储类型，默认为 "database" |
| `storage_key` | String(512) | 存储键（如对象存储的 key），可选 |
| `size` | Integer | 文件大小（字节），默认为 0 |
| `created_at` | DateTime | 创建时间 |
| `updated_at` | DateTime | 更新时间 |

**索引：**
- `skill_files_skill_idx`: 技能 ID 索引
- `skill_files_path_idx`: 技能 ID + 路径复合索引

## 核心功能

### 1. 技能列表查询

**功能描述：** 获取技能列表，支持按用户、公开状态、标签过滤。

**权限控制：**
- 未登录用户：只能查看公开技能
- 已登录用户：可查看自己的技能 + 公开技能

**查询参数：**
- `include_public` (bool): 是否包含公开技能，默认 True
- `tags` (List[str]): 标签过滤，支持多标签筛选

**实现位置：**
- API: `GET /v1/skills`
- Service: `SkillService.list_skills()`
- Repository: `SkillRepository.list_by_user()`

**查询逻辑：**
1. 如果 `user_id` 存在且 `include_public=True`：返回 `owner_id == user_id` 或 `is_public == True` 或 `owner_id == None`（系统级公共技能）
2. 如果 `user_id` 存在且 `include_public=False`：只返回 `owner_id == user_id` 的技能
3. 如果 `user_id` 不存在且 `include_public=True`：返回所有公开技能
4. 如果 `user_id` 不存在且 `include_public=False`：不返回任何结果
5. 如果指定了 `tags`，使用 JSONB 的 `contains` 操作符进行标签过滤

### 2. 技能详情查询

**功能描述：** 根据技能 ID 获取技能详情，包含关联的文件列表。

**权限控制：**
- 拥有者：可以访问自己的技能
- 其他用户：只能访问公开的技能
- 未登录用户：只能访问公开的技能

**实现位置：**
- API: `GET /v1/skills/{skill_id}`
- Service: `SkillService.get_skill()`
- Repository: `SkillRepository.get_with_files()`

**权限检查逻辑：**
```python
if skill.owner_id and skill.owner_id != current_user_id and not skill.is_public:
    raise ForbiddenException("You don't have permission to access this skill")
```

### 3. 创建技能

**功能描述：** 创建新的技能，支持同时创建关联的文件。

**权限要求：** 需要登录

**实现位置：**
- API: `POST /v1/skills`
- Service: `SkillService.create_skill()`

**业务规则：**
1. 如果未指定 `owner_id`，则使用 `created_by_id` 作为拥有者
2. 检查同一拥有者下是否存在同名技能，如果存在则抛出异常
3. 支持在创建时同时添加文件列表
4. 文件通过 `files` 参数传入，每个文件包含：
   - `path`: 文件路径
   - `file_name`: 文件名
   - `file_type`: 文件类型
   - `content`: 文件内容（可选）
   - `storage_type`: 存储类型（默认 "database"）
   - `storage_key`: 存储键（可选）
   - `size`: 文件大小（默认 0）

**请求体示例：**
```json
{
  "name": "Python 数据分析",
  "description": "使用 Python 进行数据分析的技能",
  "content": "详细的技能内容...",
  "tags": ["python", "data-analysis"],
  "source_type": "local",
  "is_public": false,
  "files": [
    {
      "path": "/examples",
      "file_name": "example.py",
      "file_type": "python",
      "content": "print('Hello World')",
      "storage_type": "database",
      "size": 20
    }
  ]
}
```

### 4. 更新技能

**功能描述：** 更新已存在的技能信息。

**权限要求：** 只有拥有者可以更新自己的技能

**实现位置：**
- API: `PUT /v1/skills/{skill_id}`
- Service: `SkillService.update_skill()`

**业务规则：**
1. 权限检查：只有拥有者可以更新
2. 如果更新名称，需要检查新名称在同一拥有者下是否已存在
3. 支持部分更新，所有字段都是可选的
4. 更新后自动刷新技能信息

**可更新字段：**
- `name`: 技能名称
- `description`: 技能描述
- `content`: 技能内容
- `tags`: 标签列表
- `source_type`: 来源类型
- `source_url`: 来源 URL
- `root_path`: 根路径
- `owner_id`: 拥有者 ID
- `is_public`: 是否公开
- `license`: 许可证

### 5. 删除技能

**功能描述：** 删除技能及其关联的所有文件。

**权限要求：** 只有拥有者可以删除自己的技能

**实现位置：**
- API: `DELETE /v1/skills/{skill_id}`
- Service: `SkillService.delete_skill()`

**业务规则：**
1. 权限检查：只有拥有者可以删除
2. 级联删除：删除技能时自动删除所有关联的文件（通过外键约束）
3. 使用 `SkillFileRepository.delete_by_skill()` 显式删除文件记录

### 6. 添加文件

**功能描述：** 向已存在的技能添加文件。

**权限要求：** 只有拥有者可以向自己的技能添加文件

**实现位置：**
- API: `POST /v1/skills/{skill_id}/files`
- Service: `SkillService.add_file()`

**业务规则：**
1. 权限检查：只有拥有者可以添加文件
2. 文件信息包括路径、文件名、类型、内容等
3. 支持多种存储类型（默认 "database"）

### 7. 删除文件

**功能描述：** 删除技能关联的特定文件。

**权限要求：** 只有拥有者可以删除自己技能的文件

**实现位置：**
- API: `DELETE /v1/skills/files/{file_id}`
- Service: `SkillService.delete_file()`

**业务规则：**
1. 权限检查：通过文件的 `skill_id` 找到对应的技能，检查拥有者权限
2. 删除指定的文件记录

## 权限控制

### 访问权限

| 操作 | 拥有者 | 其他用户 | 未登录用户 |
|------|--------|----------|------------|
| 查看自己的技能 | ✅ | ❌ | ❌ |
| 查看公开技能 | ✅ | ✅ | ✅ |
| 创建技能 | ✅ | ❌ | ❌ |
| 更新自己的技能 | ✅ | ❌ | ❌ |
| 删除自己的技能 | ✅ | ❌ | ❌ |
| 添加文件 | ✅ | ❌ | ❌ |
| 删除文件 | ✅ | ❌ | ❌ |

### 权限检查实现

所有权限检查都在 `SkillService` 层实现：

1. **查看权限：** 在 `get_skill()` 方法中检查
2. **更新权限：** 在 `update_skill()` 方法中检查
3. **删除权限：** 在 `delete_skill()` 方法中检查
4. **文件操作权限：** 在 `add_file()` 和 `delete_file()` 方法中检查

## 数据访问层

### SkillRepository

提供技能数据访问方法：

- `list_by_user()`: 根据用户 ID、公开状态、标签查询技能列表
- `get_with_files()`: 获取技能及其关联的文件（使用 `selectinload` 预加载）
- `count_by_user()`: 统计用户拥有的技能数量
- `get_by_name_and_owner()`: 根据名称和拥有者查询技能（用于唯一性检查）

### SkillFileRepository

提供技能文件数据访问方法：

- `list_by_skill()`: 获取技能的所有文件
- `delete_by_skill()`: 删除技能的所有文件（批量删除）

## API 端点

### 基础路径

所有技能相关的 API 端点都在 `/v1/skills` 路径下。

### 端点列表

| 方法 | 路径 | 说明 | 需要认证 |
|------|------|------|----------|
| GET | `/v1/skills` | 获取技能列表 | 可选 |
| POST | `/v1/skills` | 创建技能 | ✅ |
| GET | `/v1/skills/{skill_id}` | 获取技能详情 | 可选 |
| PUT | `/v1/skills/{skill_id}` | 更新技能 | ✅ |
| DELETE | `/v1/skills/{skill_id}` | 删除技能 | ✅ |
| POST | `/v1/skills/{skill_id}/files` | 添加文件 | ✅ |
| DELETE | `/v1/skills/files/{file_id}` | 删除文件 | ✅ |

### 响应格式

所有 API 响应都遵循统一的格式：

**成功响应：**
```json
{
  "success": true,
  "data": { ... }
}
```

**错误响应：**
```json
{
  "success": false,
  "error": "错误信息"
}
```

## 异常处理

技能模块使用以下自定义异常：

- `NotFoundException`: 资源不存在（如技能或文件不存在）
- `ForbiddenException`: 权限不足（如非拥有者尝试修改技能）
- `BadRequestException`: 请求参数错误（如同名技能已存在）

所有异常都在 `SkillService` 层抛出，由 API 层的全局异常处理器统一处理。

## 数据库关系

### 外键关系

1. **Skill → AuthUser (owner)**
   - `owner_id` → `user.id`
   - `ondelete="SET NULL"`: 用户删除时，拥有者设为 NULL

2. **Skill → AuthUser (created_by)**
   - `created_by_id` → `user.id`
   - `ondelete="CASCADE"`: 用户删除时，删除其创建的所有技能

3. **SkillFile → Skill**
   - `skill_id` → `skills.id`
   - `ondelete="CASCADE"`: 技能删除时，级联删除所有关联文件

### 关系加载策略

- `Skill.owner`: `lazy="selectin"` - 使用 selectin 加载
- `Skill.created_by`: `lazy="selectin"` - 使用 selectin 加载
- `Skill.files`: `lazy="selectin"` - 使用 selectin 加载，支持级联删除
- `SkillFile.skill`: `lazy="selectin"` - 使用 selectin 加载

## 使用示例

### 创建技能

```python
from app.services.skill_service import SkillService

service = SkillService(db)
skill = await service.create_skill(
    created_by_id="user123",
    name="Python 爬虫",
    description="使用 Python 进行网页爬取的技能",
    content="详细的技能内容...",
    tags=["python", "web-scraping"],
    is_public=True,
    files=[
        {
            "path": "/examples",
            "file_name": "scraper.py",
            "file_type": "python",
            "content": "import requests\n...",
            "storage_type": "database",
            "size": 1024
        }
    ]
)
```

### 查询技能列表

```python
# 获取当前用户的所有技能（包括公开的）
skills = await service.list_skills(
    current_user_id="user123",
    include_public=True,
    tags=["python"]
)
```

### 更新技能

```python
skill = await service.update_skill(
    skill_id=skill.id,
    current_user_id="user123",
    description="更新后的描述",
    is_public=False
)
```

## 扩展性考虑

### 未来可能的扩展

1. **版本管理：** 支持技能版本控制，记录历史版本
2. **评分系统：** 允许用户对公开技能进行评分和评论
3. **使用统计：** 记录技能的使用次数和频率
4. **导入导出：** 支持技能的批量导入和导出
5. **模板系统：** 支持从模板创建技能
6. **协作功能：** 支持多人协作编辑技能
7. **搜索优化：** 使用全文搜索提升搜索性能
8. **文件存储优化：** 支持大文件使用对象存储（S3、OSS 等）

## 注意事项

1. **唯一性约束：** 同一拥有者的技能名称必须唯一，创建和更新时都会检查
2. **权限边界：** 所有权限检查都在服务层实现，确保数据安全
3. **级联删除：** 删除技能时会自动删除所有关联文件，注意数据备份
4. **标签查询：** 使用 PostgreSQL 的 JSONB GIN 索引，支持高效的标签查询
5. **关系加载：** 使用 `selectinload` 策略，避免 N+1 查询问题
6. **事务管理：** 所有写操作都在事务中执行，确保数据一致性

## 相关文件

- 模型定义：`app/models/skill.py`
- 数据访问：`app/repositories/skill.py`
- 业务逻辑：`app/services/skill_service.py`
- API 端点：`app/api/v1/skills.py`
- 数据库迁移：`alembic/versions/`

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

JoySafeter

Directory Structure

SKILL.md

Report

Notice