贡献指南¶
感谢你有兴趣改进 NovelAI Image MCP!本页介绍实际的工作流程。项目的
行为准则见
CODE_OF_CONDUCT.md。
开始之前¶
开一个 issue 描述你打算做的改动。对于新功能或 API 变更尤其 重要 —— 我们会在你花时间写代码之前先讨论范围与 设计。
查看 issue tracker 了解是否有相关的工作正在进行。
开发环境搭建¶
git clone https://github.com/xinvxueyuan/NovelAI-Image-MCP.git
cd NovelAI-Image-MCP
# Sync the workspace virtualenv (server + docs + dev tools)
uv sync
# (Optional) Install Node-side tooling for husky + markdownlint + turbo
corepack enable pnpm
pnpm install --frozen-lockfile
首次 uv sync 会下载所有传递依赖;后续运行是瞬时的。
工作流¶
# 1. Branch off main
git checkout -b feat/my-feature
# 2. Implement your change.
# - Source under apps/server/src/
# - Tests under apps/server/tests/
# - Docs under apps/docs/source/ (if user-facing)
# 3. Run all checks locally before pushing.
uv run --directory apps/server poe check
# Equivalent to: ruff format-check + ruff check + pyright + pytest
# 4. (If you touched docs) verify the build:
uv run --package novelai-image-mcp-docs sphinx-build -b html apps/docs/source apps/docs/_build/html -W --keep-going
# 5. (If you touched markdown) verify markdownlint:
pnpm exec markdownlint-cli2
# 6. (If you touched licensing) verify REUSE compliance:
uv run reuse lint
# 7. Commit using Conventional Commits + gitmoji:
git commit -m "✨ feat: add support for V5 model ids"
# 8. Push and open a PR:
git push -u origin feat/my-feature
gh pr create --title "..." --body "..."
Pre-commit 钩子¶
如果你安装了 pnpm 依赖,.husky/pre-commit 钩子会在每次 git commit
时自动运行:
prek —— ruff
--fix、ruff-format 以及通用钩子 (trailing-whitespace、end-of-file-fixer 等)。markdownlint —— 仅当有
.md文件被 staged 时。pyright —— 仅当有
.py文件被 staged 时。pytest —— 仅当有
.py文件被 staged 时(最慢的阶段)。
如果 prek 修改了文件,钩子会重新 stage 它们并重试一次。如果任何 阶段失败,提交会以清晰的消息中止。
要为 WIP 提交绕过它(请节制使用):
git commit --no-verify -m "wip: ..."
警告
CI 会运行与钩子相同的检查。--no-verify 提交仍然会在
CI 上失败 —— 只对确实处于 WIP、并且你会在
开 PR 前 rebase 的工作绕过它。
编码规范¶
Python¶
风格:由
ruff(preview 模式)强制执行。规则集见apps/server/pyproject.toml。 运行uv run --directory apps/server ruff format自动 格式化。类型:由
pyright(standard 模式)强制执行。类型检查必须通过。Docstring:Google 风格(本项目的 pydocstyle 约定)。 公开 API 上必需;私有辅助函数上可选。
导入:每个模块顶部都必须有
from __future__ import annotations(PEP 563 + RuffTC规则)。异步:工具是异步的。HTTP 用
httpx.AsyncClient, 测试用pytest-asyncio(asyncio_mode=auto)。
Markdown¶
使用 MyST Markdown(文档站的解析器)。
行长不受限制(
MD013已禁用)。标题不得以
.,;:!结尾(MD026)。允许内联 HTML(
MD033已禁用),用于 callout / details。运行
pnpm exec markdownlint-cli2 --fix自动修复大多数问题。
许可¶
所有文件都必须带有 SPDX 许可证头。
REUSE.toml按 glob 声明它们 —— 通常你不需要手动添加任何东西。运行
uv run reuse lint验证合规。软件代码:MIT。文档:MIT。视觉元素 + 基础设施: CC0-1.0。
测试覆盖率¶
覆盖率下限:70%(由
--cov-fail-under=70强制执行)。测试位于
apps/server/tests/,使用pytest-asyncio+respx(HTTP mock)。每个新的公开函数至少应有一个测试。
Bug 修复应包含一个回归测试。
测试布局与 fixture 策略见 测试。
文档¶
面向用户的改动(新工具、新参数、行为变更)必须 更新文档:
工具 →
apps/docs/source/tools/<tool>.md教程 →
apps/docs/source/tutorials/<tutorial>.md配置 →
apps/docs/source/configuration.mdAPI → 由
sphinx.ext.autodoc从 docstring 自动生成
在本地预览文档:
uv run --package novelai-image-mcp-docs sphinx-autobuild apps/docs/source apps/docs/_build/html --open-browser
贡献技能¶
Agent 技能位于 skills/<name>/SKILL.md,并在仓库根目录的
skills.sh.json 中注册。要新增一个技能:
运行
npx skills init <name>生成SKILL.mdfrontmatter 的脚手架 (只含name+description,不要metadata块)以及## When to use→## Instructions的正文结构。填写内容 —— 按需分发指引,不要重复其他技能 已经覆盖的内容。
把该技能加入
skills.sh.json中合适的分组 (CLI / MCP Tools / Workflows)。如果该技能面向用户,更新 Agent 技能 文档页与 README 技能表。
完整的脚手架约定(frontmatter 规则、H1 = 技能名、description < 200 字符、
YAML 特殊字符的引号规则)见 AGENTS.md → “Agent Skills (skills.sh)”。
翻译文档¶
文档站通过按语言划分的源码树支持多语言。
英文位于 apps/docs/source/ 根目录;每种额外语言
位于 apps/docs/source/<lang-code>/(例如 source/zh/、
source/ja/)。所有语言共享同一份 conf.py。
规则¶
只做完整翻译 —— 不要 stub。 翻译页必须覆盖 完整英文源。代码块保持不变;只翻译散文。 不要创建"翻译中"占位页 —— 它们会破坏构建的
-W告警门禁, 并让用户困惑。toctree 范围 = 仅限已翻译页面。 每个语言目录下的
index.mdtoctree 只能引用该语言目录下实际存在的页面。 如果某个章节(例如tools/、tutorials/)未翻译,就不要把它放进已翻译的 toctree —— 用户可切换到英文查看未翻译的章节。保留 MyST 指令。 保持所有 MyST 语法(
:::tip、=== "Unix"标签页、{toctree}、{image}等)不变。只 翻译其中的散文。标题中的 CJK 标点。
MD026禁止标题以.,;:!结尾 —— 请改用。、!?。(MD013行长限制已禁用, 因此很长的 CJK 行没问题。)
新增语言¶
创建
apps/docs/source/<code>/,至少包含index.md。在
apps/docs/source/conf.py的AVAILABLE_LANGUAGES中加入该语言 ((code, label, base_path)元组)。在
.github/workflows/docs.yml的 matrix 中加入该语言。在本地构建并确认零告警:
uv run --package novelai-image-mcp-docs sphinx-build -b html \ apps/docs/source/<code> apps/docs/_build/<code>/html \ -c apps/docs/source -D language=<code> -W --keep-going
仓库 README¶
项目的权威概览是 README.md(英文)。它的完整
翻译位于 .github/docs/README-zh.md(简体中文)与
.github/docs/README-ja.md(日文),与 Sphinx 源码树
分开存放。根 README-zh.md 是兼容性入口,不是需要维护的
第二份翻译。
每个 README 都包含一个纯文本 Markdown 表格,链接到全部三份
项目概览,列名为 English、简体中文 与 日本語。
请使用适合该文件所在目录的相对链接;已发布的
apps/server/README.md 使用绝对 GitHub URL,因此链接在
PyPI 上也能用。包与发布说明的 README 把这些标注为项目概览
链接,而不是包或发布说明指南本身的翻译。
保持三份完整概览中的所有章节、工具/配置表格与围栏示例
同步。翻译散文,不要翻译可执行示例;
为 .github/docs/ 调整本地文件链接。保留服务器包的
mcp-name: 标记。提交前运行 pnpm readme:check、pnpm readme:test 与
pnpm exec markdownlint-cli2;CI 与本地
pre-commit 钩子会运行同一套 README 检查器。
保持翻译同步¶
当英文源变更时,如果可行,请在同一个 PR 中更新对应的翻译页。 严重失去同步的翻译页应当删除,而不是留着过期 —— 缺少翻译好过误导性的翻译。
提交消息¶
遵循 Conventional Commits + gitmoji:
<emoji> <type>: <subject>
<body>
类型 |
用途 |
|---|---|
|
新功能 |
|
Bug 修复 |
|
仅文档 |
|
格式化、空白,无代码变更 |
|
代码重构,无行为变更 |
|
性能改进 |
|
新增 / 修复测试 |
|
构建系统、依赖、CI |
|
CI 配置变更 |
|
杂项维护 |
常用 emoji:
Emoji |
类型 |
|---|---|
✨ |
feat |
🐛 |
fix |
📝 |
docs |
🎨 |
style |
♻️ |
refactor |
⚡️ |
perf |
✅ |
test |
🏗️ |
build |
🔧 |
chore |
Pull request¶
每个逻辑变更一个 PR。
标题:Conventional Commit 格式(
feat:、fix:等)。描述:关联 issue,概述改动,列出任何破坏性 变更。
合并前所有 CI 检查必须通过。
Squash-and-merge 进
main(默认分支)。
报告 bug¶
开一个 bug report issue。 请包含:
你运行的确切命令。
完整的错误输出(如果是 Python,请附 stack trace)。
服务器版本(通过
uv run python -c "import novelai_image_mcp; print(novelai_image_mcp.__version__)")。你的操作系统、Python 版本与 uv 版本。
一个最小复现(脚本或步骤)。
报告安全问题¶
不要为安全漏洞开公开 issue。 私有披露流程见
SECURITY.md。