> ## Documentation Index
> Fetch the complete documentation index at: https://ai-novel-writing-assistant.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 参与贡献

> 反馈问题、提交代码、开发约定与社区链接

欢迎参与 Biz Novel Studio 的改进。本文面向希望反馈问题、提交代码或进行二次开发的贡献者。

## 反馈问题的模板

到 [GitHub Issues](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/issues) 提交问题时，请尽量使用以下模板填写，方便维护者快速复现和定位。

```markdown theme={null}
## 版本与环境
- 应用版本：（顶部栏版本号，如 v0.8.1）
- 操作系统：（Windows / macOS / Linux，以及版本号）
- 模型提供商：（OpenAI / Claude / 自定义等）

## 复现步骤
1. 从哪个入口进入（如「自动导演」「大纲工作台」）
2. 做了哪些操作（点击了什么、输入了什么）
3. 触发问题的具体节点

## 期望结果
（描述你期望应用如何响应）

## 实际结果
（描述实际出现的异常，如暂停、报错、内容不符合预期等）

## 日志或截图
- 桌面版日志包：在「版本与更新」中保存并上传
- 报错原文或截图（可脱敏后粘贴）
```

> [!NOTE]
>
> 仓库已配置 PR 模板，提交代码时系统会自动加载。Issue 暂无强制模板，但按上述结构填写可显著缩短沟通周期。

更完整的反馈清单见 [常见问题](https://ai-novel-writing-assistant.mintlify.site/faq.md)。

## 新手可以先做的事

如果你刚接触本项目，以下贡献方式不需要深入代码即可开始：

* **文档勘误与补充**：发现错别字、步骤过时或截图与界面不符，直接在对应页面提交修改
* **反馈可复现的 Bug**：使用上面的模板在 Issues 中提交带步骤的问题，帮助维护者建立复现清单
* **Prompt 调优建议**：在「自动导演」「风格引擎」等模块中，如果你发现某类提示词对特定模型输出不稳定，可以在 Issues 中附上模型版本、输入示例和期望输出格式
* **翻译与术语统一**：界面文案、文档或 Prompt 中的术语不一致时，可提出统一建议

这些贡献同样会被记录在仓库的贡献者列表中。准备好深入代码后，再阅读下方的开发约定与提交规范。

## 提交 PR 前须知

### 许可证与 CLA

* 本项目默认基于 GNU Affero General Public License v3.0（AGPL-3.0-only）授权
* 提交贡献前请阅读 [CONTRIBUTING.md](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/blob/main/CONTRIBUTING.md) 与 [CLA.md](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/blob/main/CLA.md)
* 第三方代码、素材、数据需说明来源、许可证和必要归属信息，并补充到 NOTICE 文件
* 维护者可将贡献纳入单独授权的商业发行

### 开发约定摘要

以下规则摘自仓库的 [AGENTS.md](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/blob/main/AGENTS.md)，对贡献者保持代码质量和产品一致性有帮助：

* **数据保护优先。** 执行任何破坏性数据操作前，先完成备份并验证备份文件存在。
* **AI 优先，不用关键词硬匹配。** 核心行为由 AI 结构化理解实现，不为 AI 失误添加关键词兜底分支。
* **单文件约 1,200 行上限需拆分。** 超过 1,300 行时强制拆分为职责明确的模块，禁止仅按行数平铺为无归属的 helper / utils 文件。
* **运行记录（任务中心）只读。** 不在任务中心放置继续、恢复、取消等操作，相关动作放在来源工作台。
* **界面文案从用户角度写。** 不写「现在/不再/已经升级」这类变更叙述，用「你可以做什么」「下一步是什么」描述。
* **低边框视觉。** 普通内容分组依赖排版、间距和底色，不套多层带边框的卡片。
* **维护开发 Wiki。** 涉及导演、章节生产、Prompt Schema、任务恢复等核心链路的改动，同步更新 `docs/wiki/` 中对应页面。

### 提交前自检

```bash theme={null}
pnpm typecheck
pnpm lint
pnpm test
```

如果改动涉及导演或 Prisma，大改动后务必本地跑通 `pnpm test` 再提交。

## 优先关注方向

项目 README 中明确提到的优先关注方向包括：

* 连续生成与恢复
* 新手开书体验
* 长篇一致性
* 可追溯的模型用量

如果你计划在这些方向提 PR，可以先在 Issues 中说明方案，减少后续返工。

## 社区链接

* [GitHub Issues](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/issues)：问题反馈与功能讨论
* [LINUX DO 社区讨论帖](https://linux.do/t/topic/2738271)：中文社区交流

> [card] [架构与源码](https://ai-novel-writing-assistant.mintlify.site/developers/architecture.md)
>
> 技术栈、目录结构与常用命令

> [card] [环境变量](https://ai-novel-writing-assistant.mintlify.site/developers/environment-variables.md)
>
> 服务端与前端配置项说明

> [card] [常见问题](https://ai-novel-writing-assistant.mintlify.site/faq.md)
>
> 反馈问题前的自查清单


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.