Skip to content

AGENTS.md

Latest commit

 

History

History
143 lines (110 loc) · 4.38 KB

AGENTS.md

File metadata and controls

143 lines (110 loc) · 4.38 KB

Agent Instructions (代理指令)

本文档概述了 hotsou 相关项目的开发指南、构建流程和代码规范。所有代理（Agents）和开发人员必须遵守这些规则，以保持代码库的一致性和质量。 项目总体采用 monorepo 的形式组织，包含app和server两个子项目。借助于 npm workspace 实现的。主要的开发语言为typescript。

App 工作区 (app/)

基于 expo 开发的移动端 app，主要是提供各种网站的浏览功能。

  • 框架采用 expo，遵循 expo 官方最佳实践。
  • 路由采用的是 react-navigation，主路由采用的是抽屉路由。
  • 必须遵循业界的 react 最佳实践。
  • 单个组件行数最好不要超过 300 行，必要的时候进行合理的拆分和复用。

项目目录结构：

  • App.tsx: 应用入口。
  • navigation/: 导航配置 (React Navigation)。
  • screens/: 全屏页面视图。
  • components/: 可复用的 UI 组件。
  • store/: 全局状态管理 (使用 react-atomic-store)。
  • utils/: 辅助函数和工具。
  • assets/: 静态资源。

Server 工作区 (server/)

该服务基于 Hono 和 Cloudflare Workers。主要用来为 app 提供 api 接口服务和数据存储。

  • 基于 Hono 框架，部署在 Cloudflare Workers。
  • 接口的输入需要使用 zod 进行验证。
  • zod 返回的变量名必须以 Schema 结尾。
  • 使用 chanfana 处理 OpenAPI 规范(如果适用)。
  • API 设计需要符合 Restful api 的最佳实践。

API 端点开发规范 (参考示例)

在 src/endpoints/ 目录下创建文件，每个文件包含一个继承自 OpenAPIRoute 的类。

1. 定义 Schema (src/types.ts)

import { DateTime, Str } from 'chanfana'
import { z } from 'zod'

export const TaskSchema = z.object({
  name: Str({ example: 'lorem' }),
  slug: Str(),
  description: Str({ required: false }),
  completed: z.boolean().default(false),
  due_date: DateTime(),
})

2. 实现端点 (src/endpoints/taskCreate.ts)

import { Bool, OpenAPIRoute } from 'chanfana'
import { z } from 'zod'
import { type AppContext, TaskSchema } from '../types'

export class TaskCreate extends OpenAPIRoute {
  schema = {
    tags: ['Tasks'],
    summary: 'Create a new Task',
    request: {
      body: {
        content: {
          'application/json': {
            schema: TaskSchema,
          },
        },
      },
    },
    responses: {
      '200': {
        description: 'Returns the created task',
        content: {
          'application/json': {
            schema: z.object({
              series: z.object({
                success: Bool(),
                result: z.object({
                  task: TaskSchema,
                }),
              }),
            }),
          },
        },
      },
    },
  }

  async handle(c: AppContext) {
    const data = await this.getValidatedData<typeof this.schema>()
    const taskToCreate = data.body
    // 业务逻辑实现...
    return {
      success: true,
      task: { ...taskToCreate },
    }
  }
}

3. 注册路由 (src/index.ts)

import { TaskCreate } from './endpoints/taskCreate'
// ...
openapi.post('/api/tasks', TaskCreate)

项目目录结构：

  • src/index.ts: 入口文件。初始化 Hono 应用并注册 OpenAPI 路由。
  • src/endpoints/: 包含端点类。每个端点一个文件 (单文件单类)。
  • src/types.ts: 共享的类型定义。
  • worker-configuration.d.ts: 环境变量 (Bindings) 的类型定义。

格式化 (Formatting)

每次改完代码可以直接运行 npm run format 来进行格式化即可。

TypeScript

对于 server 项目，每次改完必须首先运行 npm run cf-typegen 来重新更新类型。 每次改完代码运行npm run type-check来进行类型校验。

  • 严禁杜撰类型，必须与官方文档和官方类型相符合。
  • 尽量不用类型断言以及 any 类型。
  • 尽量通过用 zod 定义 schema，然后推导出类型。

版本控制与提交

  • 注意[CRITICAL]: 每一轮任务结束时，你必须输出一条符合 Conventional Commits 规范的 git commit message。

文档和注释

  • 注释: 为复杂逻辑和关键功能添加注释。解释“为什么”，而不是“是什么”。

Generated by opencode. Please respect these guidelines to ensure code quality.