# 项目结构 > 最后更新：2026-06-17 ``` KiloStar/ ├── main.py # 应用入口（standalone / distributed 双模式） ├── pyproject.toml # Python 依赖与项目元数据（uv 管理） ├── Dockerfile / docker-compose.yml # 容器化部署 ├── alembic/ # 数据库迁移脚本（顺序编号 0001~0009） ├── config/ # 环境配置模板 │ ├── .env.example # 环境变量模板 │ ├── config.yml # 应用配置（provider/node 默认值） │ ├── workflow.yaml # 工作流重试策略 │ └── sandbox.yaml # 沙箱策略（路径白名单/命令过滤） │ ├── kilostar/ # ===== 后端核心包 ===== │ │ │ ├── api/ # FastAPI 路由层（每个文件一个 APIRouter） │ │ ├── __init__.py # app 实例、中间件、异常处理、路由挂载 │ │ ├── system.py # GET /health + /api/v1/system 系统信息 │ │ ├── workflow.py # /api/v1/workflow CRUD / SSE / resume │ │ ├── chat.py # /api/v1/chat 对话（含历史上下文注入） │ │ ├── agent.py # /api/v1/agent Worker CRUD / 模板 │ │ ├── resource.py # /api/v1/resource Toolset / Skill / Artifact │ │ ├── plugin.py # /api/v1/plugin 重型插件 submit/status/stream │ │ ├── provider.py # /api/v1/provider 模型供应商 CRUD │ │ ├── auth.py # /api/v1/auth 登录/注册/改密 │ │ └── platform/ # 平台接入 │ │ ├── frontend.py # SPA 静态资源 fallback │ │ └── onebot.py # OneBot v11 协议适配 │ │ │ ├── core/ # 核心业务逻辑 │ │ ├── individual/ # 系统 Agent 节点 │ │ │ ├── consciousness_node/ # 意识节点：接收用户命令 → 设计工作流 DAG │ │ │ │ ├── consciousness_node.py │ │ │ │ └── template.py # structured output 模板 │ │ │ ├── regulatory_node/ # 监管节点：直面用户对话、质量把关 │ │ │ │ ├── regulatory_node.py │ │ │ │ └── template.py │ │ │ ├── control_node/ # 控制节点（已废弃，名字保留给未来远程探针节点） │ │ │ │ ├── control_node.py │ │ │ │ └── template.py │ │ │ └── growth_node/ # 生长节点：能力自扩展（占位） │ │ │ │ │ ├── work/ # 工作执行层 │ │ │ ├── workflow/ # 工作流引擎 │ │ │ │ ├── workflow_engine.py # 轮询 + 调度主循环 │ │ │ │ ├── workflow.py # pydantic-graph 节点定义 │ │ │ │ ├── model.py # WorkflowState / StepResult 等 │ │ │ │ └── graph_persistence.py # 执行状态持久化到 PG │ │ │ ├── chat/ # 对话处理（占位） │ │ │ └── task/ # 短任务执行（占位） │ │ │ │ │ ├── global_state_machine/ # 全局状态机 Actor（系统唯一真相源） │ │ │ ├── global_state_machine.py # GSM 主体：初始化、注册表读写、toolset 补种 │ │ │ ├── gsm_snapshot.py # 不可变快照（放入 Ray Object Store 供快读） │ │ │ ├── individual_manager.py # Individual 注册/查询/删除 │ │ │ ├── provider_manager.py # Provider 注册/CRUD/test_connection │ │ │ ├── tool_manager.py # Toolset 加载（读 manifest.json）+ 工具分发 │ │ │ ├── skill_manager.py # Skill 元数据注册/查询 │ │ │ └── model_provider/ # Provider 适配（per-vendor 子类） │ │ │ ├── base_provider.py # 抽象基类 │ │ │ ├── openai_provider.py # OpenAI / 兼容接口 │ │ │ ├── claude_provider.py # Anthropic Claude │ │ │ ├── gemini_provider.py # Google Gemini │ │ │ └── deepseek_provider.py # DeepSeek │ │ │ │ │ ├── global_workflow_manager/ # 工作流调度 Actor │ │ │ └── global_workflow_manager.py # 消息队列、pending workflow 轮询 │ │ │ │ │ └── postgres_database/ # PostgreSQL DAO 层（Actor 门面模式） │ │ ├── postgres.py # 统一门面：组合所有子 DAO，ready_event 守卫 │ │ ├── database_exception.py# @database_exception 装饰器（统一异常包装） │ │ ├── model/ # SQLAlchemy ORM 模型 │ │ │ ├── base.py # DeclarativeBase │ │ │ ├── user.py # User + UserAuthority │ │ │ ├── provider.py # ProviderModel │ │ │ ├── individual.py # Base/Specialist/Ordinary/Special Individual │ │ │ ├── workflow.py # Workflow + Context + GraphState │ │ │ ├── chat_history.py # ChatHistoryRegister + Message │ │ │ ├── system_node.py # SystemNodeConfigModel │ │ │ ├── mcp_server.py # MCPServerModel │ │ │ ├── tool_config.py # ToolConfigModel │ │ │ ├── custom_toolset.py# CustomToolsetModel │ │ │ ├── persona_template.py# PersonaTemplate │ │ │ ├── system_event_log.py# SystemEventLog │ │ │ ├── org_task.py # OrgTask（重型插件任务） │ │ │ └── org_task_event.py# OrgTaskEvent（任务事件流） │ │ └── module/ # 各表 DAO 实现（async session + CRUD） │ │ ├── user.py / provider.py / individual.py / ... │ │ └── org_task.py # 重型插件任务 + 事件 DAO │ │ │ ├── plugin_runtime/ # 重型插件（Organization）运行时 │ │ ├── base_organization.py # 基类：asyncio.Queue 消费、dispatch/submit 双通道 │ │ │ # react 循环、consult 工具、PG 持久化 │ │ ├── plugin_manager.py # GlobalPluginManager Actor：bootstrap/install/reload │ │ ├── loader.py # discover_plugins + load_plugin + uv 依赖安装 │ │ ├── tool_bridge.py # make_dispatch_tool() → 生成 dispatch_to_ 函数 │ │ ├── manifest.py # OrgManifest pydantic 模型 │ │ ├── agents_config.py # AgentsConfig / AgentDef / orchestration │ │ └── event.py # OrgEvent / OrgEventType / TaskState │ │ │ ├── adapter/ # 模型适配器 │ │ └── model_adapter/ │ │ ├── agent_factory.py # AgentFactory：根据 provider+model 构建 pydantic-ai Agent │ │ └── deepseek_reasoner.py # DeepSeek R1 reasoning 特殊适配 │ │ │ ├── utils/ # ===== 工具函数层 ===== │ │ ├── settings.py # AppSettings（pydantic-settings）+ 路径工具 │ │ │ # get_settings / get_toolset_dir / get_plugin_dir / get_artifact_dir │ │ ├── config_loader.py # 多 YAML 统一加载 → AppConfig（workflow/sandbox/应用配置） │ │ ├── ray_compat.py # standalone/distributed 兼容层 │ │ │ # @actor_class 装饰器、StandaloneProxy、_STANDALONE 标志 │ │ ├── ray_hook.py # ray_actor_hook()：按名字获取 Actor 句柄（两种模式统一） │ │ ├── access.py # JWT 认证 + RBAC 鉴权（Accessor / TokenData / RoleChecker） │ │ ├── crypto.py # Fernet 对称加密（API key 等敏感字段落盘加密） │ │ ├── error.py # 统一异常体系：KiloStarError / BusinessError / InfraError │ │ ├── logger.py # loguru + rich 日志（get_logger 按模块名取 logger） │ │ ├── request_context.py # contextvars 双层 ID：request_id + trace_id 传播 │ │ ├── get_tool.py # 按工具名动态加载函数（扫描 manifest → importlib） │ │ ├── mcp_helper.py # MCP Server 实例创建（stdio/sse/http 三种传输） │ │ ├── sandbox.py # 工具沙箱：路径校验、命令黑名单、Python AST 检查 │ │ ├── agent_model.py # Agent 通用 pydantic 响应模型（ResponseModel 等） │ │ ├── prompts.py # 系统节点 system prompt 模板（按角色×locale） │ │ ├── rate_limit.py # 滑动窗口内存限流器（按 IP，单实例用） │ │ ├── retry.py # @retry_on_retryable_error 装饰器（指数退避） │ │ ├── banner.py # 启动 banner ASCII art │ │ └── i18n.py # 国际化翻译（t() 函数，accept-language 解析） │ │ │ ├── worker_cluster/ # Worker 集群管理 │ │ └── worker_cluster.py # WorkerCluster Actor：按资源标签管理 worker 池 │ │ # CPU / Core / GPU 三类，分布式下各一个 Actor │ │ │ └── worker_individual/ # Worker 个体 │ ├── base_individual.py # 抽象基类（生命周期 + 工具绑定） │ ├── ordinary_individual.py # 通用 Worker（接受任意 system prompt） │ ├── skill_individual.py # Skill Worker（加载指定 skill 执行） │ └── special_individual.py # 特殊 Worker（embedding/TTS/图像，占位） │ ├── data/ # ===== 数据/插件目录（运行时读取）===== │ ├── toolset/ # 工具集（每个子目录 = 一个 toolset） │ │ ├── base_toolset/ # 系统基础工具 │ │ │ ├── manifest.json # 声明 7 个工具的元数据 │ │ │ ├── shell_executor.py # Shell 命令执行 │ │ │ ├── file_reader.py # 文件读取 │ │ │ ├── edit_file.py # 文件编辑（diff patch） │ │ │ ├── write_file.py # 文件写入 │ │ │ ├── search_file.py # 文件搜索（glob + grep） │ │ │ ├── python_executor.py # Python 代码执行（沙箱内） │ │ │ └── tavily_search.py # Tavily 网络搜索 │ │ └── interactive_toolset/ # 交互工具（需要人/系统介入） │ │ ├── manifest.json │ │ ├── approval.py # 人工审批节点 │ │ └── send_file.py # 文件下发（存 artifact + 推 SSE） │ │ │ └── plugin/ # 重型插件（每个子目录 = 一个 Organization） │ └── example_dept/ # 示例插件（开发模板） │ ├── manifest.json # 插件元数据（name/entry/concurrency/...） │ ├── agents.json # 内部 agent 定义（analyst + executor） │ ├── README.md │ ├── core/ # 业务逻辑入口 │ │ └── organization.py # ExampleOrganization(BaseOrganization) │ ├── toolset/ # 插件本地工具（可选） │ ├── skills/ # 插件本地技能（可选） │ └── dashboard/ # 前端面板（占位，Tauri 化后接通） │ ├── frontend/ # ===== React 前端（Vite + TypeScript + Tailwind）===== │ └── src/ │ ├── api/ # Axios client + SSE 封装 + 类型化请求 │ ├── assets/ # 静态资源（图标/字体） │ ├── hooks/ # 自定义 React hooks │ ├── components/ # UI 组件 │ │ ├── Chat/ # 工作流面板 + 实时日志 + 文件卡片 │ │ ├── Agent/ # Worker / Provider 管理 │ │ ├── Plugin/ # Skill / Toolset / MCP 配置 │ │ ├── Auth/ # 登录 / 注册 │ │ ├── Layout/ # 布局骨架 + 导航 │ │ └── Settings/ # 系统设置 │ ├── i18n/ # 国际化 │ │ └── locales/ # zh.json / en.json │ ├── store/ # Zustand 状态管理 │ └── types/ # TypeScript 类型定义 │ ├── tests/ # ===== 测试套件（331 用例）===== │ ├── unit/ # 单元测试（纯逻辑，mock 外部依赖） │ └── integration/ # 集成测试（启动真实服务） │ └── subprojects/ # ===== 子项目 ===== └── stardomain/ # Skill 脚本沙箱执行（local + Docker 双模式） ``` --- ## 关键设计模式 | 模式 | 说明 | |:--|:--| | `@actor_class` | 装饰器统一 standalone（普通对象）和 distributed（Ray Actor）两种运行形态 | | `ray_actor_hook(name)` | 按名字获取 actor 句柄，两种模式下接口一致 | | `StandaloneProxy` | 将普通方法调用包装为 `.remote()` 语法兼容 | | GSM Snapshot | 不可变快照放入 Object Store，各节点快速读取无需 RPC | | DAO 门面 | `PostgresDatabase` 组合所有子 DAO，`ready_event` 确保初始化后才放行 | | manifest.json 声明式 | 工具集/插件元数据与代码分离，支持热发现和前端展示 | | dispatch / submit 双通道 | 重型插件对内阁阻塞（dispatch），对用户射后不管（submit） |