zhaoxi
6d658b4f4d
- 工具系统从 kilostar/plugin/tool_plugin/ 迁移到 data/toolset/（manifest.json 声明式） - 新增 plugin_runtime 模块：BaseOrganization / GlobalPluginManager / loader / tool_bridge - 新增 org_task + org_task_event 表及 DAO（alembic 0009） - 新增 /api/v1/plugin 路由（submit/status/stream/install/reload） - 新增 data/plugin/example_dept 示例重型插件 - regulatory_node 支持聊天历史上下文注入 - send_file 改为 artifact 存盘 + SSE 推送下载链接 - 前端 WorkflowFileCard 组件 + ToolSettings README 渲染 - utils 整理：合并 access/role_check、standalone_proxy→ray_compat、删除废弃模块 - 项目结构文档移至 docs/STRUCTURE.md 并详细展开 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
205 lines
15 KiB
Markdown
205 lines
15 KiB
Markdown
# 项目结构
|
||
|
||
> 最后更新：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） | |