From 6a081d0c391745187fc79857563b7fe11fe84f2f Mon Sep 17 00:00:00 2001 From: liliziOSclaw Date: Thu, 2 Apr 2026 08:02:26 -0700 Subject: [PATCH] docs: add CONTRIBUTING.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 开发环境搭建步骤 - 技术栈说明 - 架构概览 - Prompt 治理规范 - AI-First 路由原则 - 贡献流程与当前可接任务清单 --- CONTRIBUTING.md | 219 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..506389b0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,219 @@ +# 贡献指南 + +感谢你关注 AI 小说创作工作台！本文档帮助你了解项目、搭建开发环境，并找到合适的贡献方式。 + +> 如果你有任何疑问，欢迎提 Issue 或 Discussion。 + +--- + +## 项目概述 + +这是一个面向长篇小说的 AI 生产系统，目标用户是**完全不懂写作的新手**，让他们在 AI 的引导下完成从灵感到整本小说的创作。 + +核心功能：AI 自动导演开书 → 世界观/角色构建 → 卷战略/拆章 → 章节执行/审校/修复 → 整本生产。 + +--- + +## 技术栈 + +| 层级 | 技术 | +|------|------| +| 前端 | React 19 + Vite + TypeScript + TailwindCSS | +| 编辑器 | Plate（基于 Slate 的富文本编辑器）| +| 后端 | Express 5 + TypeScript | +| 数据库 | Prisma ORM + SQLite（默认）/ PostgreSQL | +| AI 编排 | LangChain / LangGraph | +| RAG | Qdrant 向量数据库 | +| 包管理 | pnpm monorepo | + +--- + +## 开发环境搭建 + +### 前置要求 + +- Node.js ≥ 20.0.0 +- pnpm ≥ 9.7.0（`npm install -g pnpm`） +- Git + +### 步骤 + +```bash +# 1. 克隆仓库 +git clone https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant.git +cd AI-Novel-Writing-Assistant + +# 2. 安装依赖 +pnpm install + +# 3. 配置环境变量 +cp .env.example server/.env +cp .env.example client/.env +# 编辑 server/.env，填入至少一个 AI API Key（如 DEEPSEEK_API_KEY） + +# 4. 初始化数据库 +pnpm db:migrate +# 如果 migrate 失败，尝试：pnpm --filter @ai-novel/server prisma db push + +# 5. 启动开发服务器 +pnpm dev +# 访问 http://localhost:5173 +``` + +### 常用脚本 + +```bash +pnpm dev # 启动全部服务（前端 + 后端 + shared） +pnpm build # 构建全部包 +pnpm typecheck # 类型检查 +pnpm lint # Lint +pnpm db:studio # 打开 Prisma Studio 查看数据库 +pnpm db:migrate # 运行数据库迁移 +pnpm test # 运行全部测试 +pnpm test:planner # 只跑 planner 测试 +``` + +--- + +## 架构概览 + +``` +AI-Novel-Writing-Assistant/ +├── client/ React 前端（AI 协作界面） +├── server/ Express 后端（AI 编排核心） +│ └── src/ +│ ├── agents/ LangGraph Agent、工具定义 +│ ├── graphs/ LangGraph 状态机定义 +│ ├── prompting/ Prompt 资产唯一入口（⚠️ 见下方 Prompt 治理规则） +│ ├── routes/ REST API 路由 +│ ├── services/ 业务逻辑（novel/ 世界观/ 角色/ 写作引擎等） +│ └── prisma/ 数据库 Schema +├── shared/ 前后端共用 TypeScript 类型和 Zod Schema +└── scripts/ 工具脚本 +``` + +--- + +## 核心开发规范 + +### ⚠️ Prompt 治理（必须遵守） + +`server/src/prompting/` 是产品级 Prompt 的**唯一新增入口**。 + +所有产品级 Prompt 必须： +1. 定义为 `PromptAsset`，放在 `server/src/prompting/prompts//` 下 +2. 在 `server/src/prompting/registry.ts` 注册 +3. 必须提供：`id`、`version`、`taskType`、`mode`、`contextPolicy`、`render()` + +**禁止：** +- 在 service 文件里直接拼 `systemPrompt` 后调用 `invokeStructuredLlm` +- 在 service 里直接用裸 `getLLM()` 发起产品级 Prompt 调用 + +详见 [`server/src/prompting/README.md`](server/src/prompting/README.md)。 + +### ⚠️ AI-First 路由原则 + +产品中的意图识别、任务分类、路由决策**必须用 AI 实现**，禁止用： +- 固定关键词匹配 +- 硬编码正则路由 +- 手工分支表 + +只有以下场景例外： +- 输入验证或安全守卫 +- 对已结构化 AI 输出的确定性后处理 + +### ⚠️ 单文件行数限制 + +单个源文件超过 **700 行** 必须拆分。目标：500-600 行。推荐阈值：600 行。 + +### 📝 README 更新工作流 + +提交代码时，如果改动有用户可见影响，**先更新 README.md 再提交 Git**。 + +--- + +## 如何贡献 + +### 找到合适的任务 + +**新手友好（无需深度熟悉代码库）：** +- 写/改进文档（CONTRIBUTING.md、API 文档、功能说明） +- 给 Issue 打标签（目前 3 个 open issue 均无标签） +- 复现 Bug 并提供更详细的复现步骤 + +**功能开发（需要熟悉代码库）：** +- 添加新的 Prompt 资产（参照现有 PromptAsset 结构） +- 实现 Issue 里记录的功能需求 +- 优化 LangGraph 状态机 + +**架构/体验改进（需要深度熟悉）：** +- 重构超长源文件 +- 改进 RAG 检索效果 +- 优化 Creative Hub 的 Agent 行为 + +### 贡献流程 + +1. **Fork 仓库** 到你的 GitHub 账号 +2. **创建分支**：`git checkout -b feat/你的功能名` 或 `fix/问题描述` +3. **开发**：遵守上面的架构规范 +4. **自测**：运行 `pnpm typecheck && pnpm lint` +5. **提 PR**：描述清楚改动目的、做了什么、测试方式 +6. **等待 Review**：维护者会在合理时间内处理 + +### Commit 信息格式（推荐） + +``` +feat: 新功能描述 +fix: 问题修复描述 +docs: 文档改动 +refactor: 代码重构 +test: 测试相关 +chore: 构建/工具改动 +``` + +--- + +## 当前可接任务 + +查看 [Open Issues](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/issues) 获取最新任务列表。以下是已知可行动项： + +| 任务 | 类型 | 难度 | +|------|------|------| +| 创建 CONTRIBUTING.md（本文档）| 文档 | ⭐ 入门 | +| 给 Open Issue 打标签 | 文档/元数据 | ⭐ 入门 | +| 增加 Ollama 本地模型支持 | 功能 | ⭐⭐ 中等 | +| 调查/修复文档上传 2MB 限制 | Bug/功能 | ⭐⭐ 中等 | +| 编写模块设计文档（解决功能分散问题）| 文档 | ⭐⭐ 中等 | +| Review UI 改进 PR [#7](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/pull/7) | 代码审查 | ⭐ 入门 | + +--- + +## 数据库开发提示 + +```bash +# 查看数据 +pnpm db:studio + +# 重置数据库（⚠️ 会清除所有数据！） +pnpm --filter @ai-novel/server prisma db push --force-reset + +# 添加迁移（修改 schema.prisma 后） +pnpm db:migrate +``` + +> ⚠️ **危险操作**：执行任何数据删除操作前，确保已有完整备份。 + +--- + +## 遇到问题？ + +1. 先搜 [Existing Issues](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/issues) +2. 如果没找到，提一个新 Issue，请包含： + - 环境信息（Node 版本、操作系统） + - 复现步骤 + - 期望行为 vs 实际行为 + - 相关日志或截图 + +--- + +再次感谢你的贡献！ 🙏