From a7805175390c8ee1da22d1244cdae2418ee844fa Mon Sep 17 00:00:00 2001 From: digua Date: Wed, 3 Jun 2026 20:00:00 +0800 Subject: [PATCH] docs: add contributor development guide --- AGENTS.md | 2 +- CLAUDE.md | 1 + README.md | 7 +- README.zh-CN.md | 7 +- docs/.vitepress/config.mts | 10 +++ docs/cn/contributing/development.md | 105 ++++++++++++++++++++++++++++ docs/cn/index.md | 4 ++ docs/en/contributing/development.md | 105 ++++++++++++++++++++++++++++ docs/en/index.md | 4 ++ scripts/dev-select.mjs | 1 + 10 files changed, 241 insertions(+), 5 deletions(-) create mode 120000 CLAUDE.md create mode 100644 docs/cn/contributing/development.md create mode 100644 docs/en/contributing/development.md diff --git a/AGENTS.md b/AGENTS.md index 188c84d3..e63d1787 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -- 文档：开始开发前，请先查看 `./.docs/README.md`，并阅读与当前需求相关的文档 +- 文档：开始开发前，请先查看公开开发指南 `docs/cn/contributing/development.md`。如果工作区存在 `.docs/`，再查看 `./.docs/README.md` 并阅读与当前需求相关的文档；`.docs/` 是可选的个人或团队私有开发上下文，可用于维护任务、决策、AI 协作记忆和临时规划，公开文档与公开 PR 不应依赖 `.docs/` 才能理解。 - 目标：用最小改动快速交付正确、可维护、可回归的业务结果 - 边界：只解决当前需求，不做与需求无关的重构和"顺手优化" - 每次完成任务后，对产生修改的文件进行类型检查、lint检查和format格式化，指定修改的文件路径去执行，确保代码质量 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/README.md b/README.md index 6bee9032..4cc134b3 100644 --- a/README.md +++ b/README.md @@ -92,10 +92,12 @@ For a deep dive, see the [architecture documentation](https://docs.chatlab.fun/i ## Local Development +For complete contributor instructions, see the [Development Guide](https://docs.chatlab.fun/contributing/development). + ### Requirements -- Node.js >= 20 -- pnpm +- Node.js >= 24 < 25 +- pnpm >= 9 < 10 ### Setup @@ -128,6 +130,7 @@ Please follow these principles before submitting a Pull Request: - Obvious bug fixes can be submitted directly. - For new features, please submit an Issue for discussion first; **PRs submitted without prior discussion will be closed**. - Keep one PR focused on one task; if changes are extensive, consider splitting them into multiple independent PRs. +- For local setup, repository structure, checks, and AI collaboration notes, see the [Development Guide](https://docs.chatlab.fun/contributing/development). Thanks to all contributors: diff --git a/README.zh-CN.md b/README.zh-CN.md index 0b8bac29..fa4d683d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -92,10 +92,12 @@ ChatLab 是一个基于 pnpm monorepo 的工程，桌面端使用 Electron + Vue ## 本地开发 +完整协作者说明见[开发指南](https://docs.chatlab.fun/cn/contributing/development)。 + ### 环境要求 -- Node.js >= 20 -- pnpm +- Node.js >= 24 < 25 +- pnpm >= 9 < 10 ### 启动步骤 @@ -128,6 +130,7 @@ electron-fix start - 明显的 Bug 修复可直接提交 - 对于新功能，请先提交 Issue 进行讨论，**未经讨论直接提交的 PR 会被关闭** - 一个 PR 尽量只做一件事，若改动较大，请考虑拆分为多个独立的 PR +- 本地运行、目录职责、测试检查和 AI 协作说明见[开发指南](https://docs.chatlab.fun/cn/contributing/development) 感谢所有为 ChatLab 做出贡献的人！ diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 7464c3e6..362fa109 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -21,6 +21,10 @@ const enSidebar: DefaultTheme.SidebarItem[] = [ { text: 'ChatLab API', link: '/standard/chatlab-api' }, ], }, + { + text: 'Contributing', + items: [{ text: 'Development Guide', link: '/contributing/development' }], + }, ] const cnSidebar: DefaultTheme.SidebarItem[] = [ @@ -46,6 +50,10 @@ const cnSidebar: DefaultTheme.SidebarItem[] = [ { text: 'Pull 远程数据源协议', link: '/cn/standard/chatlab-pull' }, ], }, + { + text: '贡献', + items: [{ text: '开发指南', link: '/cn/contributing/development' }], + }, ] const twSidebar: DefaultTheme.SidebarItem[] = [ @@ -134,6 +142,7 @@ export default defineConfig({ '/': enSidebar, '/usage/': enSidebar, '/standard/': enSidebar, + '/contributing/': enSidebar, }, editLink: { pattern: 'https://github.com/ChatLab/ChatLab/edit/main/docs/:path', @@ -172,6 +181,7 @@ export default defineConfig({ '/cn/': cnSidebar, '/cn/usage/': cnSidebar, '/cn/standard/': cnSidebar, + '/cn/contributing/': cnSidebar, }, outline: { label: '目录', diff --git a/docs/cn/contributing/development.md b/docs/cn/contributing/development.md new file mode 100644 index 00000000..b1800930 --- /dev/null +++ b/docs/cn/contributing/development.md @@ -0,0 +1,105 @@ +--- +layout: doc +title: 开发指南 +--- + +# 开发指南 + +这份指南面向想参与 ChatLab 开发的协作者，覆盖本地运行、仓库结构、常见改动入口和提交规范。更细的产品使用说明见使用指南；内部任务、草稿和个人维护上下文不作为公开贡献的前置条件。 + +## 开发前先读 + +- 先读本页，了解公开的协作基线。 +- 使用 AI 协作时，让 AI 先读根目录的 `AGENTS.md` 和本页。 +- 如果你的工作区存在 `.docs/`，可以继续阅读 `.docs/README.md` 和相关文档。`.docs/` 是可选的个人或团队私有开发上下文，可用于沉淀任务、决策、AI 协作记忆和临时规划；公开文档和公开 PR 不应依赖 `.docs/` 才能理解。 + +## 环境要求 + +- Node.js `>=24 <25` +- pnpm `>=9 <10` + +安装依赖： + +```bash +pnpm install +``` + +## 本地运行 + +| 命令 | 用途 | +| --- | --- | +| `pnpm dev` | 交互式选择开发目标 | +| `pnpm dev:desktop` | 启动 Electron 桌面端开发模式 | +| `pnpm dev:web` | 启动 CLI Web UI 开发模式 | +| `pnpm docs:dev` | 启动公开文档站开发模式 | +| `pnpm build:desktop` | 构建桌面端 | +| `pnpm build:web` | 构建 Web UI | +| `pnpm docs:build` | 构建公开文档站 | +| `pnpm run type-check:all` | 运行前端和 Node 侧类型检查 | +| `pnpm lint` | 运行 ESLint 并自动修复 | +| `pnpm format` | 运行 Prettier 格式化 | + +小范围改动优先对修改文件或相关子项目做定向检查；跨模块、发布或架构类改动再跑全量检查。 + +## 目录职责 + +| 路径 | 职责 | +| --- | --- | +| `src/` | 共享前端应用代码，包含页面、组件、服务封装、状态和 i18n | +| `src/services/` | 前端访问 Electron、CLI Web API 和平台能力的服务层 | +| `apps/desktop/` | Electron 主进程、preload 和桌面端构建配置 | +| `apps/cli/` | CLI、HTTP API、CLI Web 运行时和导入命令 | +| `packages/core/` | 平台无关的核心数据模型、查询、导入和成员操作 | +| `packages/node-runtime/` | Node.js 运行时服务、数据库、AI、导出、缓存和迁移 | +| `packages/tools/` | 统一 AI 工具定义和数据访问适配 | +| `docs/` | 公开文档站源码 | +| `changelogs/` | 应用内和发布使用的多语言更新日志 | +| `.docs/` | 可选的个人或团队私有开发上下文，不是公开贡献的必需依赖 | + +## 架构边界 + +ChatLab 同时维护 Electron 桌面端和 CLI Web 端。涉及共享业务逻辑时，优先把逻辑放到 `packages/node-runtime/src/services/` 或 `packages/core/`，入口层只做薄适配。 + +- 不要在 Electron IPC handler 或 CLI HTTP route 中重复实现复杂业务流程。 +- 不要在入口层绕过 `packages/core/` 直接写成员合并、删除、别名更新等核心 SQL 写操作。 +- 平台差异通过 adapter 或 service 参数隔离，保持前端获得的数据结构一致。 +- 新增会话、成员、索引、摘要、导出、导入相关能力时，先确认是否能复用或扩展共享 service。 + +## 常见改动入口 + +| 想改什么 | 先看哪里 | +| --- | --- | +| 前端页面和组件 | `src/pages/`、`src/components/`、`src/features/` | +| 图表分析 | `src/features/charts-*`、`src/components/charts/` | +| 数据、消息、会话 API 调用 | `src/services/` | +| Electron 主进程 | `apps/desktop/main/`、`apps/desktop/preload/` | +| CLI 和 Web API | `apps/cli/` | +| 共享业务逻辑 | `packages/node-runtime/src/services/`、`packages/core/` | +| AI 工具和 Agent | `packages/tools/`、`packages/node-runtime/src/ai/`、`src/services/ai*` | +| 导入解析 | `packages/core/`、`apps/cli/src/import/`、`src/services/import/` | +| 文档站 | `docs/`、`docs/.vitepress/config.mts` | +| 更新日志 | `changelogs/` | + +## 测试与检查 + +- 修改 TypeScript 或 Vue 代码后，至少运行相关类型检查。 +- 修改公开文档后，运行 `pnpm docs:build` 或对修改的 Markdown/配置文件运行格式化检查。 +- 修改跨平台共享逻辑后，确认 Electron 和 CLI Web 两端入口没有产生行为分歧。 +- 与单个业务模块强相关的单元测试就近放在被测文件同目录，命名为 `*.test.ts` 或 `*.test.js`。 +- 跨模块、集成、E2E、测试工具或归属不明显的测试放在根目录 `tests/`。 + +## i18n 与文案 + +涉及 UI 文案时，同步维护简体中文、英文、日语和繁体中文翻译。代码中的日志、注释、AI 工具描述、错误消息等非 UI 文本默认使用英文；如果运行时 locale 可用，应支持中英双语返回。 + +## 使用 AI 协作 + +AI 可以帮助阅读代码、生成补丁和补测试，但公开 PR 必须让 reviewer 能在公开上下文中理解。建议让 AI 先读 `AGENTS.md` 和本页；如果你维护了自己的 `.docs/`，可以把它作为额外上下文，但不要让变更说明、测试理由或设计依据只存在于私有 `.docs/` 中。 + +## PR 与提交规范 + +- 明显的 Bug 修复可以直接提交 PR。 +- 新功能请先提交 Issue 讨论；未经讨论直接提交的新功能 PR 可能会被关闭。 +- 一个 PR 尽量只做一件事，较大的改动请拆成多个独立 PR。 +- 提交信息使用 Conventional Commits，例如 `fix(import): handle empty source` 或 `docs: add contributor guide`。 +- 仅当改动是平台特有时使用平台 scope，例如 `electron`、`cli`、`web`；通用改动使用模块名作为 scope。 diff --git a/docs/cn/index.md b/docs/cn/index.md index 6fa34e83..df3584fb 100644 --- a/docs/cn/index.md +++ b/docs/cn/index.md @@ -23,6 +23,10 @@ title: ChatLab - [标准与 API](/cn/standard/chatlab-api) — 使用 ChatLab Format 和本地 REST API 对接外部工具。 +## 贡献 + +- [开发指南](/cn/contributing/development) — 了解本地运行、仓库结构、架构边界和 PR 规范。 + ## 更多 - [官网与路线图](https://chatlab.fun/cn/) — 前往官网下载 ChatLab，查看路线图和社区入口。 diff --git a/docs/en/contributing/development.md b/docs/en/contributing/development.md new file mode 100644 index 00000000..3a77e0bf --- /dev/null +++ b/docs/en/contributing/development.md @@ -0,0 +1,105 @@ +--- +layout: doc +title: Development Guide +--- + +# Development Guide + +This guide is for contributors who want to work on ChatLab code. It covers local setup, repository structure, common change entry points, and contribution rules. Product usage belongs in the usage docs; internal tasks, drafts, and personal maintenance context are not required for public contributions. + +## Read This First + +- Start with this page to understand the public collaboration baseline. +- When using AI while contributing, ask it to read the root `AGENTS.md` file and this page first. +- If your workspace contains `.docs/`, you can also read `.docs/README.md` and related files. `.docs/` is an optional private development context for an individual or team. It can store tasks, decisions, AI collaboration memory, and temporary plans; public docs and public PRs should not require `.docs/` to be understood. + +## Requirements + +- Node.js `>=24 <25` +- pnpm `>=9 <10` + +Install dependencies: + +```bash +pnpm install +``` + +## Local Commands + +| Command | Purpose | +| --- | --- | +| `pnpm dev` | Select a development target interactively | +| `pnpm dev:desktop` | Start the Electron desktop app in development mode | +| `pnpm dev:web` | Start the CLI Web UI in development mode | +| `pnpm docs:dev` | Start the public docs site locally | +| `pnpm build:desktop` | Build the desktop app | +| `pnpm build:web` | Build the Web UI | +| `pnpm docs:build` | Build the public docs site | +| `pnpm run type-check:all` | Run both web and Node type checks | +| `pnpm lint` | Run ESLint with auto-fix | +| `pnpm format` | Run Prettier formatting | + +For small changes, prefer targeted checks for the files or package you changed. For cross-module, release, or architecture changes, run the broader checks. + +## Repository Structure + +| Path | Responsibility | +| --- | --- | +| `src/` | Shared frontend app code, including pages, components, services, stores, and i18n | +| `src/services/` | Frontend service layer for Electron, CLI Web API, and platform capabilities | +| `apps/desktop/` | Electron main process, preload, and desktop build configuration | +| `apps/cli/` | CLI, HTTP API, CLI Web runtime, and import commands | +| `packages/core/` | Platform-independent data model, queries, imports, and member operations | +| `packages/node-runtime/` | Node.js runtime services, database, AI, exports, caches, and migrations | +| `packages/tools/` | Shared AI tool definitions and data access adapters | +| `docs/` | Public documentation site source | +| `changelogs/` | Multilingual changelogs used by the app and releases | +| `.docs/` | Optional private development context for an individual or team, not required for public contributions | + +## Architecture Boundaries + +ChatLab maintains both an Electron desktop app and a CLI Web app. When changing shared business behavior, put the logic in `packages/node-runtime/src/services/` or `packages/core/` first, and keep entry points thin. + +- Do not duplicate complex business flows inside Electron IPC handlers or CLI HTTP routes. +- Do not bypass `packages/core/` in entry points to write core SQL operations such as member merge, delete, or alias updates. +- Isolate platform differences through adapters or service options, and keep returned frontend data shapes consistent. +- For new session, member, index, summary, export, or import behavior, first check whether an existing shared service can be reused or extended. + +## Common Change Entry Points + +| If you want to change | Start here | +| --- | --- | +| Frontend pages and components | `src/pages/`, `src/components/`, `src/features/` | +| Chart analysis | `src/features/charts-*`, `src/components/charts/` | +| Data, message, and session API calls | `src/services/` | +| Electron main process | `apps/desktop/main/`, `apps/desktop/preload/` | +| CLI and Web API | `apps/cli/` | +| Shared business logic | `packages/node-runtime/src/services/`, `packages/core/` | +| AI tools and agents | `packages/tools/`, `packages/node-runtime/src/ai/`, `src/services/ai*` | +| Import parsing | `packages/core/`, `apps/cli/src/import/`, `src/services/import/` | +| Documentation site | `docs/`, `docs/.vitepress/config.mts` | +| Changelog | `changelogs/` | + +## Tests And Checks + +- After changing TypeScript or Vue code, run at least the relevant type check. +- After changing public docs, run `pnpm docs:build` or targeted formatting checks for the changed Markdown/config files. +- After changing shared cross-platform logic, confirm Electron and CLI Web entry points do not diverge in behavior. +- Unit tests tightly coupled to one business module should live next to the tested file and use `*.test.ts` or `*.test.js`. +- Cross-module, integration, E2E, test utility, or unclear-ownership tests should live in the root `tests/` directory. + +## i18n And Copy + +When changing UI copy, update Simplified Chinese, English, Japanese, and Traditional Chinese translations together. Logs, code comments, AI tool descriptions, error messages, and other non-UI text should default to English. If runtime locale is available, support bilingual Chinese/English responses where appropriate. + +## Using AI While Contributing + +AI can help read code, draft patches, and add tests, but public PRs must remain understandable from public context. Ask AI to read `AGENTS.md` and this page first. If you maintain your own `.docs/`, you can use it as extra context, but do not leave change rationale, test reasoning, or design assumptions only in private `.docs/` files. + +## PR And Commit Rules + +- Obvious bug fixes can be submitted directly. +- For new features, open an Issue for discussion first. Feature PRs submitted without prior discussion may be closed. +- Keep one PR focused on one task. Split large changes into independent PRs when possible. +- Use Conventional Commits, such as `fix(import): handle empty source` or `docs: add contributor guide`. +- Use platform scopes such as `electron`, `cli`, or `web` only for platform-specific changes. For general changes, use the module name as the scope. diff --git a/docs/en/index.md b/docs/en/index.md index 14b5f5dc..4d002fab 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -21,6 +21,10 @@ Welcome to the ChatLab documentation. Use the sidebar to browse topics, or jump - [Standards And API](/standard/chatlab-api) — Integrate external tools with ChatLab Format and the local REST API. +## Contributing + +- [Development Guide](/contributing/development) — Learn local setup, repository structure, architecture boundaries, and PR rules. + ## More - [Website And Roadmap](https://chatlab.fun) — Visit the product website for downloads, roadmap, and community links. diff --git a/scripts/dev-select.mjs b/scripts/dev-select.mjs index 9d8c4f5a..185f7108 100644 --- a/scripts/dev-select.mjs +++ b/scripts/dev-select.mjs @@ -22,6 +22,7 @@ const options = [ { key: 'web', label: 'Web (CLI start + frontend)', command: 'pnpm run dev:web' }, { key: 'server', label: 'Server Only (API backend)', command: 'pnpm run dev:serve' }, { key: 'frontend', label: 'Frontend (no backend)', command: 'pnpm run dev:app' }, + { key: 'docs', label: 'Docs (VitePress)', command: 'pnpm run docs:dev' }, ] function loadLastChoice() {