diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..54ae017 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,63 @@ +# AGENTS.md — Open Source Bazaar Agent Quick Reference + +> 配套 [CONTRIBUTING.md](./CONTRIBUTING.md) § 7。本文件是给 AI Agent 的**精简指令卡**——可被 `read` 工具一次性加载。 + +## 项目一句话 + +Next.js v16 + TypeScript v5 + Bootstrap v5 多模块站点（开源市集官网），承载 `/finance` 等公益开源子项目。 + +## 命令速查 + +```bash +pnpm install # 装依赖（必须 pnpm） +pnpm dev # 本地起 http://localhost:3000 +pnpm lint # ESLint +pnpm build # Next.js build +``` + +## 文件结构 + +``` +components/ # 可复用 React 组件（PascalCase.tsx） +constants/ # 全局常量（SCREAMING_SNAKE_CASE） +lib/ # 工具函数 / Hooks（camelCase.ts） +models/ # 数据模型 / 类型定义 +pages/ # Next.js 路由（kebab-case.ts/tsx） +public/ # 静态资源 +styles/ # CSS Module + 全局样式 +translation/ # i18n 文案（禁止硬编码） +types/ # 全局 TypeScript 类型 +``` + +## 修改优先级 + +1. **i18n 必走** `translation/` —— 任何用户可见字符串必须走 t(key) +2. **不破坏 `master`** —— PR 必须从 feat/fix 分支提 +3. **类型严格** —— 禁 `any`，导出去必须显式 `export` +4. **CI 必过** —— lint + build 全绿才允许 merge + +## 任务接单 SOP（接 bounties 适用） + +1. 扫镜像：Vikingr2023/awesome-agent-bounties open issues +2. 评估能力：跳过 mobile/unity/bluetooth 类 +3. `/claim #` 在 issue 下评论 +4. fork → branch → 改 → lint/build → push → 提 PR → comment 链接 +5. 48h 内交付；超时 `/unclaim` + +## 禁止 + +- ❌ 任何凭据写入代码 +- ❌ 修改非关联文件 +- ❌ `[skip ci]` 未经批准 +- ❌ 直接 push master + +## 资源链接 + +- 上游：[idea2app/Lark-Next-Bootstrap-ts](https://github.com/idea2app/Lark-Next-Bootstrap-ts) +- CI：[GitHub Actions](https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io/actions) +- 部署：[Vercel](https://vercel.com) +- 镜像仓库：[Vikingr2023/awesome-agent-bounties](https://github.com/Vikingr2023/awesome-agent-bounties) + +--- + +由 **laomao-31day001**（31day.cloud agent）· 2026-07-13 贡献。 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..abfa968 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,231 @@ +# Contributing to 开源市集 (Open Source Bazaar) + +欢迎来到**开源市集**——一个由社区驱动的开源项目孵化平台。本文是面向**人类贡献者**与 **AI Agent** 的统一贡献指南。 + +> **TL;DR** — 提交 PR 前请确保：① 通过 `pnpm lint && pnpm build`；② 在 PR 描述中关联对应 issue（`Fixes #`）；③ 遵循本文 § 4「代码规范」与 § 5「提交规范」。AI Agent 额外阅读 § 7「Agent Integration Guide」。 + +--- + +## 1. 目录 + +1. [项目简介](#1-项目简介) +2. [快速开始](#2-快速开始) +3. [开发流程](#3-开发流程) +4. [代码规范](#4-代码规范) +5. [提交规范](#5-提交规范) +6. [Review 与合并](#6-review-与合并) +7. [Agent Integration Guide](#7-agent-integration-guide) +8. [社区沟通](#8-社区沟通) + +--- + +## 1. 项目简介 + +**开源市集** 是一个 Next.js + TypeScript 多模块站点，承载多种公益开源子项目（如 `/finance` 指数基金精选页）。技术栈： + +| 维度 | 选型 | +|---|---| +| 语言 | TypeScript v5 | +| 组件引擎 | Next.js v16 | +| UI 套件 | Bootstrap v5 | +| 国际化 | 自研 `translation/` 目录 | +| CI/CD | GitHub Actions + Vercel | + +上游参考项目：[idea2app/Lark-Next-Bootstrap-ts](https://github.com/idea2app/Lark-Next-Bootstrap-ts)。 + +--- + +## 2. 快速开始 + +```bash +# 1. 克隆（含子模块若有） +git clone https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io.git +cd Open-Source-Bazaar.github.io + +# 2. 安装依赖（必须使用 pnpm） +pnpm install + +# 3. 启动开发服务器 +pnpm dev # http://localhost:3000 + +# 4. 类型检查 / Lint / 构建 +pnpm lint +pnpm build +``` + +> **注意**：项目使用 `pnpm-workspace.yaml`，请勿切换到 npm/yarn——lockfile 不兼容。 + +--- + +## 3. 开发流程 + +1. **Fork** 本仓库到你的账号。 +2. 从 `master` 切特性分支：`git checkout -b feat/` 或 `fix/`。 +3. 修改代码 + **写测试**（如适用）。 +4. 本地通过 `pnpm lint && pnpm build`。 +5. Push 到你的 fork：`git push origin feat/`。 +6. 在本仓库提 PR，**PR 描述里关联 issue**：`Fixes #`。 +7. 等待 CI + Maintainer Review，循环迭代直到 ✅ merge。 + +--- + +## 4. 代码规范 + +### 4.1 命名 + +- **文件名**：`PascalCase.tsx`（组件）、`camelCase.ts`（工具/hook）、`kebab-case.ts`（路由/常量模块） +- **组件**：导出 `PascalCase`，文件名一致 +- **常量**：`SCREAMING_SNAKE_CASE`（在 `constants/` 目录） +- **Hook**：`useXxx`，导出函数（不要默认导出） + +### 4.2 TypeScript + +- **禁止** `any`（除非有详尽注释解释原因） +- 优先 `interface` 而非 `type`（除非需要 union/intersection） +- 导出类型需 `export type X = ...` 或 `export interface X {...}` + +### 4.3 React / Next.js + +- **组件**：函数组件 + hooks；禁止 class 组件 +- **State**：优先 `useState` / `useReducer`；跨组件共享用 Context 或全局 store +- **样式**：Bootstrap utility class + `styles/` 下的 module CSS；避免内联 style +- **i18n**：所有用户可见字符串必须走 `translation/` 目录，禁止硬编码 + +### 4.4 格式化 + +- 使用项目自带的 Prettier / ESLint 配置（已 commit `eslint.config.ts`） +- 单行最大 100 字符 +- 缩进 4 空格，尾随逗号 `none` + +--- + +## 5. 提交规范 + +采用 **Conventional Commits**： + +``` +(): + + + +