开发指南

本文涵盖项目目录结构、命名规范、开发流程与代码风格，是参与 Automa Agent 开发的入门手册。

项目概述

Automa Agent 是基于 Electron 的桌面自动化应用，用于流程编排、RPA 操作与企业级数据采集。

技术栈

• 框架: Electron + Vue 3 + TypeScript
• 构建工具: Vite 6 + electron-vite
• 组件库: @erp/biz (业务组件) + @erp/common (基础组件)
• 原生模块: Rust (desktop-selection-native)

目录结构

src/
├── automa/                    # 自动化核心模块
│   ├── types/                 # 类型定义
│   │   ├── command-types.ts   # 命令分类（面板显示）
│   │   ├── node-config.ts     # 节点配置（枚举、UI、表单）
│   │   ├── node-types.ts      # 节点类型定义
│   │   └── engine-types.ts    # 引擎类型定义
│   ├── content/               # 内容脚本
│   └── utils/                 # 工具函数
├── main/                      # 主进程
│   ├── beans/                 # 服务Bean
│   ├── controller/            # IPC 控制器
│   ├── db/                    # 数据库
│   ├── engine/                # 流程引擎
│   │   ├── BaseNodeExecutor.ts
│   │   └── executors/         # 节点执行器
│   └── platform/              # 平台功能
├── preload/                   # 预加载脚本
├── renderer/                  # 渲染进程（Vue应用）
│   ├── pages/                 # 页面
│   │   └── workflow/          # 工作流页面
│   │       ├── components/    # 组件
│   │       └── composables/   # 组合式函数
│   ├── components/            # 公共组件
│   └── common/                # 公共模块
└── core/                      # 核心框架
    └── summer/                # IoC 容器

---

开发规范

命名规范

类型	规则	示例
文件名（组件）	PascalCase	ConfigPanel.vue
文件名（工具）	kebab-case	api-service.ts
变量/函数	camelCase	handleClick, nodeConfig
常量	UPPER_SNAKE_CASE	MAX_RETRY_COUNT
接口	PascalCase + I 后缀	NodeTypeI, ExecutionContextI
类型别名	PascalCase + Type 后缀	NodeKeyType
枚举	PascalCase	NodeKey, NodeErrorType
类	PascalCase	BaseNodeExecutor

TypeScript 规范

// 接口定义
interface NodeConfigI {
  /** 节点ID */
  id: string;
  /** 节点名称 */
  name: string;
  /** 配置项 */
  config?: Record<string, any>;
}

// 使用 JSDoc 注释
/**
 * 执行节点操作
 * @param node - 节点定义
 * @param context - 执行上下文
 * @returns 执行结果
 */
async function executeNode(node: NodeDefinition, context: ExecutionContext): Promise<NodeExecutionResult> {
  // ...
}

Vue 组件规范

<template>
  <div class="component-name">
    <!-- 模板内容 -->
  </div>
</template>

<script setup lang="ts">
import { ref, reactive, computed, watch, onMounted, useTemplateRef } from 'vue';
import { Button } from '@erp/common';
import { DynamicForm } from '@erp/biz';

// Props 定义
interface Props {
  modelValue: string;
  disabled?: boolean;
}

const props = withDefaults(defineProps<Props>(), {
  disabled: false,
});

// Emits 定义
const emit = defineEmits<{
  (e: 'update:modelValue', value: string): void;
  (e: 'change', value: string): void;
}>();

// 模板引用
const formRef = useTemplateRef<InstanceType<typeof DynamicForm>>('formRef');

// 响应式数据
const loading = ref(false);
const formData = reactive({});

// 计算属性
const isValid = computed(() => formData.name?.length > 0);

// 方法
const handleSubmit = async () => {
  // ...
};

// 生命周期
onMounted(() => {
  // 初始化
});
</script>

<style lang="scss" scoped>
.component-name {
  // 样式
}
</style>

Git 规范

# 查看提交日志时始终使用 --no-pager
git --no-pager log --oneline -20

# 查看当前迭代的提交（排除已合并到 master 的代码）
git --no-pager log $(git merge-base HEAD origin/master)..HEAD --no-merges --oneline

# 查看修改的文件列表
git --no-pager log $(git merge-base HEAD origin/master)..HEAD --no-merges --name-only --pretty=format: | sort -u | grep -v '^$'

---

核心开发流程

节点开发

详见 node-development.md

必须完成的步骤（缺一不可）：

1. command-types.ts - 添加命令定义（节点面板显示）
2. node-config.ts - 添加 NodeKey 枚举
3. node-config.ts - 添加 NodeTypesConfig UI配置
4. node-config.ts - 定义表单配置（xxxFormConfig）
5. node-types.ts - 定义节点接口（xxxNodeDefinition）
6. node-types.ts - 添加到 SpecificNodeDefinition 联合类型
7. node-types.ts - 添加到 NodeDefinitionMap 映射
8. executors/ - 创建执行器类
9. ConfigPanel.vue - 导入并注册表单配置

API 开发

详见 api-development.md

开发步骤：

1. 定义类型（NativeApiTypes.ts）
2. 在 DesktopNative 中添加方法
3. 在 NativeApiController 中暴露 IPC 方法
4. 在渲染进程中调用

---

组件库使用

组件库文档：https://lib.fukerp.com/

@erp/biz 业务组件

import { DynamicForm, FilterForm, VxeGrid, Input, pop, http } from '@erp/biz';
import type { DynamicFormI, SearchFormI, VxeGridProps } from '@erp/biz';

@erp/common 基础组件

import { Button, Tag, Modal, Tabs, TabPane, Form, FormItem, Space, Spin } from '@erp/common';

图标使用

<i class="erpfont icon-edit" />
<i class="erpfont icon-delete" />
<i class="erpfont icon-plus" />

---

调试与测试

主进程调试

在 VSCode 中使用 .vscode/launch.json 配置进行调试。

渲染进程调试

使用 Chrome DevTools（Ctrl+Shift+I / Cmd+Option+I）。

日志

import { LogManager } from '@core/LogManager';

const logger = LogManager.getLogger('ModuleName');
logger.info('信息日志');
logger.warn('警告日志');
logger.error('错误日志');

---

常见问题

节点开发常见问题

问题	检查项
节点不显示	检查 command-types.ts
配置面板空白	检查 ConfigPanel.vue 是否注册
执行器不工作	检查文件名、export default、type 属性
类型错误	检查 node-types.ts 联合类型和映射

IPC 通信问题

问题	检查项
API 调用无响应	检查 Controller 中是否有 @IpcHandler 装饰
返回 undefined	检查 wrapAsync 包装和返回值

---

参考文档

• 节点开发规范
• API 开发规范
• 组件库文档