KiloStar/docs/STRUCTURE.md

项目结构

最后更新：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_<org> 函数
│   │   ├── 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）