Backend API 模块¶

本模块提供 FastAPI 后端服务。

FastAPI 应用¶

FastAPI backend service for AI Social Scientist VSCode extension

关联文件： - @packages/agentsociety2/agentsociety2/backend/run.py - 服务启动脚本 - @extension/src/services/backendManager.ts - VSCode插件后端进程管理 - @extension/src/apiClient.ts - VSCode插件API客户端

路由注册： - @packages/agentsociety2/agentsociety2/backend/routers/prefill_params.py - /api/v1/prefill-params - @packages/agentsociety2/agentsociety2/backend/routers/experiments.py - /api/v1/experiments - @packages/agentsociety2/agentsociety2/backend/routers/replay.py - /api/v1/replay - @packages/agentsociety2/agentsociety2/backend/routers/custom.py - /api/v1/custom - @packages/agentsociety2/agentsociety2/backend/routers/modules.py - /api/v1/modules - @packages/agentsociety2/agentsociety2/backend/routers/agent_skills.py - /api/v1/agent-skills

agentsociety2.backend.app.lifespan(app)[源代码]¶

FastAPI 应用生命周期管理（启动/关闭钩子）。

async agentsociety2.backend.app.root()[源代码]¶

返回:: 后端服务基本信息与 endpoints 列表。

async agentsociety2.backend.app.health_check()[源代码]¶

返回:: 健康状态。

async agentsociety2.backend.app.global_exception_handler(request, exc)[源代码]¶

全局异常处理器。

参数:

request (Request) -- FastAPI 请求对象（用于扩展日志上下文）。
exc (Exception) -- 未捕获异常。

返回:

标准化的 500 JSON 响应。

路由模块¶

预填充参数路由¶

预填充参数查询API路由（只读）

关联文件： - @packages/agentsociety2/agentsociety2/backend/app.py - 主应用，注册此路由 (/api/v1/prefill-params) - @extension/src/prefillParamsViewProvider.ts - VSCode插件前端调用此API - @extension/src/webview/prefillParams/ - 前端展示组件

读取文件： - {workspace}/.agentsociety/prefill_params.json - 预填充参数配置

async agentsociety2.backend.routers.prefill_params.get_prefill_params(workspace_path=Query(PydanticUndefined))[源代码]¶

获取全局预填充参数

返回工作区中所有类（Agent和环境模块）的预填充参数配置。

参数:: workspace_path (str) -- 工作区根目录路径
返回:: Dict[str, Any]: 预填充参数配置，包含： - success: 是否成功 - data: 参数数据，结构为： - version: 配置版本 - env_modules: 环境模块预填充参数字典 - agents: Agent预填充参数字典
抛出:: HTTPException -- 500 - 读取配置文件失败
返回类型:: Dict[str, Any]

备注

如果配置文件不存在，返回空配置结构。

async agentsociety2.backend.routers.prefill_params.get_class_prefill_params(class_kind=Path(PydanticUndefined), class_name=Path(PydanticUndefined), workspace_path=Query(PydanticUndefined))[源代码]¶

获取特定类的预填充参数

返回指定类（Agent或环境模块）的预填充参数配置。

参数:

class_kind (Literal['env_module', 'agent']) -- 类类型，可选值： - env_module: 环境模块 - agent: Agent类
class_name (str) -- 类名，如 mobility_space, basic_agent 等
workspace_path (str) -- 工作区根目录路径

返回:

Dict[str, Any]: 类的预填充参数，包含： - success: 是否成功 - class_kind: 类类型 - class_name: 类名 - params: 该类的预填充参数字典（如无配置则为空字典）

抛出:

HTTPException -- 500 - 读取配置文件失败

返回类型:

Dict[str, Any]

示例

GET /api/v1/prefill-params/env_module/mobility_space?workspace_path=/path/to/workspace

实验路由¶

实验数据 API。

提供实验基本信息与产出文件查询。新 replay 写入格式为 run/replay/_schema.json + sharded JSONL；实验统计通过 agentsociety2.storage.ReplayReader 读取，不再访问 sqlite.db。

class agentsociety2.backend.routers.experiments.ExperimentInfo(*, experiment_id, hypothesis_id, status, start_time=None, end_time=None, agent_count, step_count)[源代码]¶

实验信息。

experiment_id: str¶

hypothesis_id: str¶

status: str¶

start_time: str | None¶

end_time: str | None¶

agent_count: int¶

step_count: int¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async agentsociety2.backend.routers.experiments.get_experiment_info(hypothesis_id, experiment_id, workspace_path=Query(PydanticUndefined))[源代码]¶

获取实验基本信息。

返回指定实验的状态、开始/结束时间、Agent 数量和已执行 step 数。

async agentsociety2.backend.routers.experiments.list_artifacts(hypothesis_id, experiment_id, workspace_path=Query(PydanticUndefined))[源代码]¶

列出实验运行过程中生成的 Markdown 产出文件。

async agentsociety2.backend.routers.experiments.get_artifact(hypothesis_id, experiment_id, artifact_name, workspace_path=Query(PydanticUndefined))[源代码]¶

获取指定 Markdown 产出文件内容。

回放路由¶

Replay data query API for simulation playback.

关联文件： - @extension/src/replayWebviewProvider.ts - VSCode Replay Webview provider - @extension/src/webview/replay/ - VSCode Replay Webview React app

class agentsociety2.backend.routers.replay.ExperimentInfo(*, hypothesis_id, experiment_id, total_steps, start_time, end_time, agent_count)[源代码]¶

hypothesis_id: str¶

experiment_id: str¶

total_steps: int¶

start_time: datetime | None¶

end_time: datetime | None¶

agent_count: int¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.TimelinePoint(*, step, t)[源代码]¶

step: int¶

t: datetime¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.AgentProfile(*, id, name, profile=<factory>)[源代码]¶

id: int¶

name: str¶

profile: Dict[str, Any]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayDatasetColumn(*, column_name, sqlite_type, logical_type=None, analysis_role=None, title=None, description=None, unit=None, nullable, enum_values=None, example=None, tags=<factory>)[源代码]¶

column_name: str¶

sqlite_type: str¶

logical_type: str | None¶

analysis_role: str | None¶

title: str | None¶

description: str | None¶

unit: str | None¶

nullable: bool¶

enum_values: Any | None¶

example: Any | None¶

tags: List[str]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayDatasetInfo(*, dataset_id, table_name, module_name, kind, title='', description='', entity_key=None, step_key=None, time_key=None, default_order=<factory>, capabilities=<factory>, version, created_at, columns=<factory>)[源代码]¶

dataset_id: str¶

table_name: str¶

module_name: str¶

kind: str¶

title: str¶

description: str¶

entity_key: str | None¶

step_key: str | None¶

time_key: str | None¶

default_order: List[str]¶

capabilities: List[str]¶

version: int¶

created_at: datetime¶

columns: List[ReplayDatasetColumn]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayDatasetList(*, datasets)[源代码]¶

datasets: List[ReplayDatasetInfo]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayDatasetRows(*, dataset_id, columns, rows, total)[源代码]¶

dataset_id: str¶

columns: List[str]¶

rows: List[Dict[str, Any]]¶

total: int¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayPanelSchema(*, agent_profile_dataset=None, agent_state_datasets=<factory>, env_state_datasets=<factory>, geo_dataset=None, primary_agent_state_dataset_id=None, layout_hint='random', supports_map=False)[源代码]¶

agent_profile_dataset: ReplayDatasetInfo | None¶

agent_state_datasets: List[ReplayDatasetInfo]¶

env_state_datasets: List[ReplayDatasetInfo]¶

geo_dataset: ReplayDatasetInfo | None¶

primary_agent_state_dataset_id: str | None¶

layout_hint: Literal['map', 'random']¶

supports_map: bool¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayDatasetPanelRef(*, dataset_id, module_name, title='')[源代码]¶

dataset_id: str¶

module_name: str¶

title: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayPosition(*, agent_id, lng=None, lat=None)[源代码]¶

agent_id: int¶

lng: float | None¶

lat: float | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayAgentStateAtStep(*, dataset, rows_by_agent_id=<factory>)[源代码]¶

dataset: ReplayDatasetPanelRef¶

rows_by_agent_id: Dict[str, Dict[str, Any]]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayEnvStateAtStep(*, dataset, row=None)[源代码]¶

dataset: ReplayDatasetPanelRef¶

row: Dict[str, Any] | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.replay.ReplayStepBundle(*, step, t=None, layout_hint='random', positions=<factory>, agent_state_rows=<factory>, env_state_rows=<factory>)[源代码]¶

step: int¶

t: datetime | None¶

layout_hint: Literal['map', 'random']¶

positions: List[ReplayPosition]¶

agent_state_rows: Dict[str, ReplayAgentStateAtStep]¶

env_state_rows: Dict[str, ReplayEnvStateAtStep]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

agentsociety2.backend.routers.replay.get_replay_dir(workspace_path, hypothesis_id, experiment_id)[源代码]¶

agentsociety2.backend.routers.replay.get_replay_reader(replay_dir)[源代码]¶

async agentsociety2.backend.routers.replay.get_experiment_info(hypothesis_id, experiment_id, workspace_path=Query(PydanticUndefined))[源代码]¶

async agentsociety2.backend.routers.replay.get_replay_datasets(hypothesis_id, experiment_id, workspace_path=Query(PydanticUndefined))[源代码]¶

async agentsociety2.backend.routers.replay.get_replay_dataset(hypothesis_id, experiment_id, dataset_id, workspace_path=Query(PydanticUndefined))[源代码]¶

async agentsociety2.backend.routers.replay.get_replay_dataset_rows(hypothesis_id, experiment_id, dataset_id, workspace_path=Query(PydanticUndefined), page=Query(1), page_size=Query(20), order_by=Query(None), desc_order=Query(False), step=Query(None), entity_id=Query(None), start_step=Query(None), end_step=Query(None), max_step=Query(None), columns=Query(None), latest_per_entity=Query(False))[源代码]¶

async agentsociety2.backend.routers.replay.get_replay_panel_schema(hypothesis_id, experiment_id, workspace_path=Query(PydanticUndefined))[源代码]¶

async agentsociety2.backend.routers.replay.get_replay_step_bundle(hypothesis_id, experiment_id, step, workspace_path=Query(PydanticUndefined))[源代码]¶

async agentsociety2.backend.routers.replay.get_timeline(hypothesis_id, experiment_id, workspace_path=Query(PydanticUndefined))[源代码]¶

async agentsociety2.backend.routers.replay.get_agent_profiles(hypothesis_id, experiment_id, workspace_path=Query(PydanticUndefined))[源代码]¶

自定义模块路由¶

自定义模块 API 路由

提供扫描、清理、测试自定义模块的 API 端点。

关联文件： - @extension/src/projectStructureProvider.ts - 前端项目结构视图（调用此API） - @extension/src/apiClient.ts - API客户端

API端点： - POST /api/v1/custom/scan - 扫描自定义模块并生成JSON配置 - POST /api/v1/custom/clean - 清理自定义模块配置 - POST /api/v1/custom/test - 测试自定义模块 - GET /api/v1/custom/list - 列出已注册的自定义模块 - GET /api/v1/custom/status - 获取自定义模块状态

内部服务： - @packages/agentsociety2/agentsociety2/backend/services/custom/scanner.py - 模块扫描 - @packages/agentsociety2/agentsociety2/backend/services/custom/generator.py - JSON生成 - @packages/agentsociety2/agentsociety2/registry/ - 模块注册表

class agentsociety2.backend.routers.custom.ScanRequest(*, workspace_path=None)[源代码]¶

扫描请求

workspace_path: str | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.custom.ScanResponse(*, success, agents_found, envs_found, agents_generated, envs_generated, errors=<factory>, agent_diagnostics=<factory>, env_diagnostics=<factory>, message=None)[源代码]¶

扫描响应

success: bool¶

agents_found: int¶

envs_found: int¶

agents_generated: int¶

envs_generated: int¶

errors: List[str]¶

agent_diagnostics: List[Dict[str, Any]]¶

env_diagnostics: List[Dict[str, Any]]¶

message: str | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.custom.CleanResponse(*, success, removed_count, message)[源代码]¶

清理响应

success: bool¶

removed_count: int¶

message: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.custom.TestRequest(*, workspace_path=None, module_kind=None, module_class_name=None)[源代码]¶

测试请求

workspace_path: str | None¶

module_kind: str | None¶

module_class_name: str | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.custom.ModuleTestResult(*, name, module_kind='env_module', success, output, error=None, checks=<factory>, metadata=<factory>)[源代码]¶

单个模块测试结果

name: str¶

module_kind: str¶

success: bool¶

output: str¶

error: str | None¶

checks: List[Dict[str, Any]]¶

metadata: Dict[str, Any]¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.custom.TestResponse(*, success, test_output, error=None, returncode=None, results=<factory>, total_tests=None, passed_tests=None, failed_tests=None)[源代码]¶

测试响应

success: bool¶

test_output: str¶

error: str | None¶

returncode: int | None¶

results: List[ModuleTestResult]¶

total_tests: int | None¶

passed_tests: int | None¶

failed_tests: int | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.custom.ListResponse(*, success, agents, envs, total_agents, total_envs)[源代码]¶

列表响应

success: bool¶

agents: List[Dict[str, Any]]¶

envs: List[Dict[str, Any]]¶

total_agents: int¶

total_envs: int¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async agentsociety2.backend.routers.custom.scan_custom_modules(request)[源代码]¶

扫描自定义模块并注册到内存

扫描工作区的 custom/agents/ 和 custom/envs/ 目录（跳过 examples/ 子目录），验证发现的模块并将其直接注册到内存中的 registry。

参数:

request (ScanRequest) -- 扫描请求，包含： - workspace_path: 工作区路径（可选，不提供则使用环境变量）

返回:

ScanResponse: 扫描结果，包含： - success: 是否成功 - agents_found: 发现的Agent数量 - envs_found: 发现的环境模块数量 - agents_generated: 成功注册的Agent数量 - envs_generated: 成功注册的环境模块数量 - errors: 错误信息列表 - message: 结果消息

抛出:

HTTPException -- 400 - 未提供工作区路径
HTTPException -- 500 - 扫描失败

备注

此接口不会生成JSON配置文件，模块仅注册到内存中。如需持久化配置，请使用 /api/v1/custom/classes 端点。

async agentsociety2.backend.routers.custom.clean_custom_modules(request)[源代码]¶

清理自定义模块的JSON配置

删除所有标记为 is_custom=true 的JSON配置文件。

参数:

request (ScanRequest) -- 清理请求，包含： - workspace_path: 工作区路径（可选）

返回:

CleanResponse: 清理结果，包含： - success: 是否成功 - removed_count: 删除的配置数量 - message: 结果消息

抛出:

HTTPException -- 400 - 未提供工作区路径
HTTPException -- 500 - 清理失败

async agentsociety2.backend.routers.custom.test_custom_modules(request)[源代码]¶

测试自定义模块

扫描并测试自定义模块，验证其能否正常工作。可以测试所有模块或指定特定模块。

参数:

request (TestRequest) -- 测试请求，包含： - workspace_path: 工作区路径（可选） - module_kind: 模块类型 ('agent' 或 'env_module'，可选） - module_class_name: 要测试的类名（与module_kind配合使用，可选）

返回:

TestResponse: 测试结果，包含： - success: 是否全部通过 - test_output: 测试输出内容 - error: 错误信息（如有） - returncode: 测试进程返回码 - results: 各模块测试结果列表 - total_tests: 总测试数 - passed_tests: 通过数 - failed_tests: 失败数

抛出:

HTTPException -- 400 - 未提供工作区路径
HTTPException -- 500 - 测试失败

备注

如果不指定 module_kind 和 module_class_name，则测试所有发现的模块。

async agentsociety2.backend.routers.custom.list_custom_modules()[源代码]¶

列出当前已注册的自定义模块

从内存注册表中读取所有标记为 is_custom=true 的模块信息。

返回:: ListResponse: 模块列表，包含： - success: 是否成功 - agents: 自定义Agent列表 - envs: 自定义环境模块列表 - total_agents: Agent总数 - total_envs: 环境模块总数
抛出:: HTTPException -- 500 - 获取列表失败

async agentsociety2.backend.routers.custom.get_custom_modules_status()[源代码]¶

获取自定义模块状态概览

返回工作区自定义模块目录的状态信息。

返回:: Dict[str, Any]: 状态信息，包含： - custom_dir_exists: custom目录是否存在 - agents_dir_exists: agents子目录是否存在 - envs_dir_exists: envs子目录是否存在 - agent_files_count: Agent文件数量 - env_files_count: 环境模块文件数量 - registered_agents: 已注册的Agent数量 - registered_envs: 已注册的环境模块数量
抛出:: HTTPException -- 400 - 未设置工作区路径

async agentsociety2.backend.routers.custom.list_available_classes(workspace_path=Query(PydanticUndefined), include_custom=Query(True))[源代码]¶

列出所有可用的Agent类和环境模块类

返回所有可用的类，并标记哪些已配置预填充参数。

参数:

workspace_path (str) -- 工作区路径（必填）
include_custom (bool) -- 是否包含自定义模块，默认True

返回:

Dict[str, Any]: 可用类列表，包含： - success: 是否成功 - env_modules: 环境模块字典，每个模块包含： - type, class_name, description, is_custom, has_prefill - agents: Agent字典，每个Agent包含： - type, class_name, description, is_custom, has_prefill - env_module_count: 环境模块数量 - agent_count: Agent数量

抛出:

HTTPException -- 500 - 获取类列表失败

返回类型:

Dict[str, Any]

async agentsociety2.backend.routers.custom.rescan_custom_modules(workspace_path=Query(PydanticUndefined))[源代码]¶

重新扫描自定义模块

清除内存中的旧模块并重新扫描工作区的自定义模块。

参数:: workspace_path (str) -- 工作区路径（必填）
返回:: Dict[str, Any]: 扫描结果，包含： - success: 是否成功 - scan_result: 扫描详情 - message: 结果消息
抛出:: HTTPException -- 500 - 重新扫描失败
返回类型:: Dict[str, Any]

模块路由¶

Modules API router

Provides endpoints for listing available agent classes and environment modules. Supports both built-in modules and custom modules from the workspace.

关联文件： - @extension/src/apiClient.ts - API客户端（调用getAgentClasses, getEnvModules） - @extension/src/prefillParamsViewProvider.ts - 预填充参数查看器 - @extension/src/simSettingsEditorProvider.ts - SIM_SETTINGS编辑器 - @packages/agentsociety2/agentsociety2/registry/ - 模块注册表

API端点： - GET /api/v1/modules/agent_classes - 获取所有可用的Agent类 - GET /api/v1/modules/env_module_classes - 获取所有可用的Environment模块类 - GET /api/v1/modules/refresh - 刷新模块列表（重新扫描）

async agentsociety2.backend.routers.modules.get_agent_classes(include_custom=Query(True))[源代码]¶

获取所有可用的Agent类列表

返回系统中所有已注册的Agent类，包括内置和自定义模块。

参数:: include_custom (bool) -- 是否包含自定义模块，默认True
返回:: Dict[str, Any]: 包含Agent类信息的响应： - success: 是否成功 - agents: Agent类字典，键为类型名，值为： - type: 类型名 - class_name: 类名 - description: 描述 - is_custom: 是否为自定义模块 - count: Agent类总数
抛出:: HTTPException -- 500 - 获取Agent类失败
返回类型:: Dict[str, Any]

async agentsociety2.backend.routers.modules.get_env_module_classes(include_custom=Query(True))[源代码]¶

获取所有可用的环境模块类列表

返回系统中所有已注册的环境模块类，包括内置和自定义模块。

参数:: include_custom (bool) -- 是否包含自定义模块，默认True
返回:: Dict[str, Any]: 包含环境模块类信息的响应： - success: 是否成功 - modules: 环境模块类字典，键为类型名，值为： - type: 类型名 - class_name: 类名 - description: 描述 - is_custom: 是否为自定义模块 - count: 模块类总数
抛出:: HTTPException -- 500 - 获取环境模块类失败
返回类型:: Dict[str, Any]

async agentsociety2.backend.routers.modules.get_all_modules(include_custom=Query(True))[源代码]¶

获取所有可用的模块类

一次性返回所有Agent类和环境模块类，减少请求次数。

参数:: include_custom (bool) -- 是否包含自定义模块，默认True
返回:: Dict[str, Any]: 包含所有模块信息的响应： - success: 是否成功 - agents: Agent类字典 - agent_count: Agent类数量 - env_modules: 环境模块类字典 - env_module_count: 环境模块类数量
抛出:: HTTPException -- 500 - 获取模块失败
返回类型:: Dict[str, Any]

Agent Skills 路由¶

Agent Skills API 路由

提供 agent skill 的列表、扫描自定义 skill、导入/创建/上传 skill 的 API 端点。

本路由基于 v2 skill 注册表 (agentsociety2.agent.base.skill_registry)，它是一个 只读元数据注册表：skill 是"始终存在"的目录，PersonAgent 在运行时按目录选择激活。因此本路由**没有** enable/disable/reload/remove 端点（v2 模型无此概念）。

关联文件： - @packages/agentsociety2/agentsociety2/agent/base/skill_registry.py - Skill 注册表 - @extension/src/apiClient.ts - VSCode 扩展 API 客户端 - @frontend/src/pages/Skills/index.tsx - Web 前端 Skill 管理页

API 端点： - GET /api/v1/agent-skills/list — 列出所有已发现的 agent skill（built-in + custom + env） - POST /api/v1/agent-skills/scan — 扫描 workspace/custom/skills/ 下的自定义 skill - POST /api/v1/agent-skills/import — 从工作区内路径导入 skill 目录 - POST /api/v1/agent-skills/create — 在线创建新 skill（SKILL.md + 可选脚本） - POST /api/v1/agent-skills/upload — 上传 zip 包导入 skill - GET /api/v1/agent-skills/{skill_id}/info — 获取 SKILL.md 内容

class agentsociety2.backend.routers.agent_skills.SkillItem(*, skill_id, name, namespace, description, source, source_label, path, has_skill_md, script='')[源代码]¶

skill_id: str¶

name: str¶

namespace: str¶

description: str¶

source: str¶

source_label: str¶

path: str¶

has_skill_md: bool¶

script: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.agent_skills.ListResponse(*, success, skills, total)[源代码]¶

success: bool¶

skills: list[SkillItem]¶

total: int¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.agent_skills.ScanRequest(*, workspace_path=None)[源代码]¶

workspace_path: str | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.agent_skills.ScanResponse(*, success, new_skills, total, message)[源代码]¶

success: bool¶

new_skills: list[str]¶

total: int¶

message: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.agent_skills.ImportRequest(*, source_path, workspace_path=None)[源代码]¶

source_path: str¶

workspace_path: str | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.agent_skills.ImportResponse(*, success, name, message)[源代码]¶

success: bool¶

name: str¶

message: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.agent_skills.CreateRequest(*, name, description='', script='', body='', script_content='', workspace_path=None)[源代码]¶

name: str¶

description: str¶

script: str¶

body: str¶

script_content: str¶

workspace_path: str | None¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.backend.routers.agent_skills.SimpleResponse(*, success, message)[源代码]¶

success: bool¶

message: str¶

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async agentsociety2.backend.routers.agent_skills.list_skills()[源代码]¶: 列出所有已发现的 Agent Skill（built-in + custom + env）。

async agentsociety2.backend.routers.agent_skills.scan_custom_skills(req)[源代码]¶

扫描工作区的自定义 Agent Skill（{workspace}/custom/skills/）。

async agentsociety2.backend.routers.agent_skills.import_skill(req)[源代码]¶

从工作区内路径导入 Agent Skill（复制到 custom/skills/）。

async agentsociety2.backend.routers.agent_skills.create_skill(req)[源代码]¶

在线创建新的自定义 Skill。

在 custom/skills/{name}/ 下生成 SKILL.md（+ 可选脚本文件）。

async agentsociety2.backend.routers.agent_skills.upload_skill(file=File(PydanticUndefined), workspace_path=None)[源代码]¶

上传 zip 包导入 Skill。

zip 包应包含一个顶层目录，内含 SKILL.md。

async agentsociety2.backend.routers.agent_skills.get_skill_info(skill_id)[源代码]¶

获取 Skill 的详细信息（含 SKILL.md 内容）。

skill_id 形如 built-in@daily-guidance 或 custom@my-skill，由 SkillRegistry.list_all() 返回。

请求/响应模型¶

SkillItem¶

class agentsociety2.backend.routers.agent_skills.SkillItem(*, skill_id, name, namespace, description, source, source_label, path, has_skill_md, script='')[源代码]

skill_id: str

name: str

namespace: str

description: str

source: str

source_label: str

path: str

has_skill_md: bool

script: str

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ListResponse¶

class agentsociety2.backend.routers.agent_skills.ListResponse(*, success, skills, total)[源代码]

success: bool

skills: list[SkillItem]

total: int

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].