Llama-FS代码规范：Python与TypeScript风格指南

Llama-FS代码规范：Python与TypeScript风格指南

【免费下载链接】llama-fs A self-organizing file system with llama 3 项目地址: https://gitcode.com/GitHub_Trending/ll/llama-fs

在Llama-FS（A self-organizing file system with llama 3）项目开发中，保持一致的代码风格是确保团队协作效率和代码可维护性的关键。本文档详细介绍了项目中Python和TypeScript的编码规范，帮助开发者编写符合项目标准的高质量代码。

项目架构概览

Llama-FS项目采用Python后端与TypeScript前端分离的架构：

• Python后端：位于项目根目录下的src/文件夹，主要负责文件系统核心逻辑、文档处理和AI交互。关键模块包括：

  • 文件加载与处理：src/loader.py
  • 文件树生成：src/tree_generator.py
  • 文件监控工具：src/watch_utils.py

• TypeScript前端：位于electron-react-app/src/文件夹，基于Electron和React构建桌面应用界面。主要组件包括：

  • 主进程管理：electron-react-app/src/main/main.ts
  • 菜单构建：electron-react-app/src/main/menu.ts
  • UI组件：electron-react-app/src/renderer/components/

Python编码规范

1. 代码风格基础

Python代码应严格遵循PEP 8规范，使用4个空格缩进，行长度限制在79字符以内。文件编码统一为UTF-8，文件末尾需保留一个空行。

2. 命名约定

• 函数/方法：使用小写字母和下划线组合（snake_case），如get_dir_summaries
• 类：使用首字母大写的驼峰命名（PascalCase）
• 变量：使用snake_case命名，如file_path
• 常量：使用全大写字母和下划线，如MAX_RETRIES

示例：

# 良好的函数命名和注释示例 [src/loader.py](https://link.gitcode.com/i/0669f1c1fec1a63f25187f86ba0a2c9c)
@agentops.record_function("get directory summaries")
async def get_dir_summaries(path: str):
    """
    获取指定目录下所有文件的摘要信息
    
    Args:
        path: 要处理的目录路径
        
    Returns:
        包含文件路径和摘要的字典列表
    """
    doc_dicts = load_documents(path)
    summaries = await get_summaries(doc_dicts)
    # Convert path to relative path
    for summary in summaries:
        summary["file_path"] = os.path.relpath(summary["file_path"], path)
    return summaries

3. 类型注解

所有公共函数和方法必须添加类型注解，提高代码可读性和IDE支持。

示例：

# 带类型注解的函数定义 [src/loader.py](https://link.gitcode.com/i/0669f1c1fec1a63f25187f86ba0a2c9c)
def merge_summary_documents(summaries, metadata_list):
    list_summaries = defaultdict(list)
    
    for item in summaries:
        list_summaries[item["file_path"]].append(item["summary"])
        
    file_summaries = {
        path: ". ".join(summaries) for path, summaries in list_summaries.items()
    }
    
    file_list = [
        {"summary": file_summaries[file["file_path"]], **file} for file in metadata_list
    ]
    
    return file_list

4. 错误处理

使用try-except块捕获并妥善处理异常，避免程序崩溃。对于可能失败的操作（如API调用），实现重试机制。

示例：

# 带重试机制的API调用 [src/loader.py](https://link.gitcode.com/i/0669f1c1fec1a63f25187f86ba0a2c9c)
async def summarize_document(doc, client):
    max_retries = 5
    attempt = 0
    while attempt < max_retries:
        try:
            chat_completion = client.chat.completions.create(
                messages=[
                    {"role": "system", "content": PROMPT},
                    {"role": "user", "content": json.dumps(doc)},
                ],
                model="llama-3.1-70b-versatile",
                response_format={"type": "json_object"},
                temperature=0,
            )
            break
        except Exception as e:
            print("Error status {}".format(e.status_code))
            attempt += 1

5. 工具与依赖管理

项目Python依赖统一管理在requirements.txt文件中，主要依赖包括：

• ollama: 用于AI模型交互
• chromadb: 向量数据库
• llama-index: 文档处理框架
• fastapi: Web服务框架
• watchdog: 文件系统监控

添加新依赖时，应指定版本号以确保环境一致性。

TypeScript编码规范

1. 代码风格基础

TypeScript代码遵循ESLint规范，使用2个空格缩进，行长度限制在100字符以内。项目已配置ESLint和Prettier自动格式化工具。

2. 命名约定

• 函数/方法：使用camelCase命名，如resolveHtmlPath
• 类：使用PascalCase命名，如MenuBuilder
• 接口/类型：使用PascalCase命名，并添加"I"前缀，如IFileSummary
• 常量：使用UPPER_SNAKE_CASE命名

示例：

// 类定义示例 [electron-react-app/src/main/menu.ts](https://link.gitcode.com/i/7022e7f62292cdd71353783ef13bfb2e)
export default class MenuBuilder {
  mainWindow: BrowserWindow;

  constructor(mainWindow: BrowserWindow) {
    this.mainWindow = mainWindow;
  }

  buildMenu(): Menu {
    if (
      process.env.NODE_ENV === 'development' ||
      process.env.DEBUG_PROD === 'true'
    ) {
      this.setupDevelopmentEnvironment();
    }

    const template =
      process.platform === 'darwin'
        ? this.buildDarwinTemplate()
        : this.buildDefaultTemplate();

    const menu = Menu.buildFromTemplate(template);
    Menu.setApplicationMenu(menu);

    return menu;
  }
  
  // ...
}

3. 类型定义

优先使用接口(interface)定义对象类型，使用类型别名(type)定义联合类型或交叉类型。

4. 异步编程

使用async/await语法处理异步操作，避免回调地狱。Electron主进程与渲染进程间通信使用IPC机制。

示例：

// Electron IPC通信示例 [electron-react-app/src/main/main.ts](https://link.gitcode.com/i/c8749743bb92c5fa44d49cbef4d4d8d9)
ipcMain.on('ipc-example', async (event, arg) => {
  const msgTemplate = (pingPong: string) => `IPC test: ${pingPong}`;
  console.log(msgTemplate(arg));
  event.reply('ipc-example', msgTemplate('pong'));
});

5. 模块与导入

使用ES6模块系统，导入路径使用相对路径，避免使用绝对路径。

示例：

// 模块导入示例 [electron-react-app/src/main/main.ts](https://link.gitcode.com/i/c8749743bb92c5fa44d49cbef4d4d8d9)
import path from 'path';
import { app, BrowserWindow, shell, ipcMain } from 'electron';
import { autoUpdater } from 'electron-updater';
import log from 'electron-log';
import MenuBuilder from './menu';
import { resolveHtmlPath } from './util';

通用规范

1. 注释规范

• 文件头部：每个文件开头添加文件描述、作者和版权信息
• 函数/方法：复杂逻辑的函数必须添加文档字符串，说明功能、参数、返回值
• 复杂逻辑：对非直观的代码段添加行内注释

2. 错误处理

• Python使用logging模块记录错误信息
• TypeScript使用console.error和Electron的日志模块记录错误

3. 版本控制

• 提交信息应简洁明了，使用现在时态（如"Add feature"而非"Added feature"）
• 每个提交应专注于单一功能或修复
• 提交前运行代码格式化工具和Linter

工具支持

项目已集成以下工具确保代码风格一致性：

Python工具链

• Linter: flake8
• 格式化工具: black
• 类型检查: mypy
• 依赖管理: pip + requirements.txt

TypeScript工具链

• Linter: ESLint，配置见electron-react-app/package.json中的eslintConfig
• 格式化工具: Prettier
• 类型检查: TypeScript编译器，配置见electron-react-app/tsconfig.json
• 构建工具: webpack

运行以下命令检查和格式化代码：

# Python代码检查
flake8 src/

# TypeScript代码检查
cd electron-react-app && npm run lint

# TypeScript代码格式化
cd electron-react-app && npm run format

总结

遵循一致的代码规范是Llama-FS项目成功的关键因素之一。本文档概述的规范旨在提高代码质量、可读性和可维护性。开发团队应严格遵守这些规范，并在日常开发中不断完善和优化。

通过共同遵守这些编码标准，我们能够构建一个更加健壮、高效且易于维护的自组织文件系统。

更多项目详情，请参考：

• 官方文档：README.md
• 项目源码：src/ 和 electron-react-app/src/

【免费下载链接】llama-fs A self-organizing file system with llama 3 项目地址: https://gitcode.com/GitHub_Trending/ll/llama-fs