参与 AxonX 贡献

English · 简体中文

欢迎问题反馈、功能建议、文档改进、研究插件和代码贡献。

开始之前

搜索已有 Issues 和相关代码。反馈问题时，请提供复现步骤、预期与实际行为、环境版本，以及已移除凭据的相关日志。提出功能建议时，请说明研究或开发中遇到的问题和期望行为。

新建 Issue 时，使用问题反馈、功能建议或使用问题表单，其他主题可使用空白 Issue。问题反馈请区分已复现故障、间歇性观察和静态分析推测，注明问题范围及本地或远程 target。分享脱敏片段即可，请勿上传整个 .axonx/ 工作区。

涉及公开 CLI/API/配置契约、持久化任务记录或任务生命周期的较大改动，建议先通过 Issue 讨论设计。每个 PR 聚焦一个完整问题。

选择修改位置

位置	职责
axonx/	Application 组装、Component、Job、CLI、服务与 Task 运行时
plugins/	研究 Task、算法、插件 manifest 与插件测试
axonx_studio/	浏览器 UI、API 客户端、任务表单与研究图表
tests/	框架单元测试与集成测试
docs/en/、docs/zh/、docs/figures/	双语指南与共享截图、示意图
docs/.vitepress/navigation.mjs、github-pages/	文档导航、主题与站点构建工具

实现契约见 Task 开发指南、框架扩展和插件协议。

开发环境

Fork 仓库并克隆自己的 fork。在仓库根目录使用 Python 3.12+，本地开发环境支持 macOS 和 Linux：

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pre-commit install

开发研究插件时，以 editable 模式安装对应插件：

axonx plugin install -e ./plugins/a158
# Or: axonx plugin install -e ./plugins/a158_enhanced

默认 pytest 配置包含 enhanced 插件测试及两个插件的源码路径。运行这些测试时，通过上述安装准备研究依赖。插件发现和重启行为见插件指南。

Studio 使用 Node.js 22.13+（22.x）、24.x 或 26+，运行：

cd axonx_studio
npm ci
npm run dev

按快速开始另行启动 Python 服务。代理配置见 Studio 开发。文档站要求 Node.js 22+。

实现改动

复用已有契约和扩展点。研究算法放在 Task/插件中，框架中的异步资源应保持明确的所有权和清理逻辑。主动变更 CLI 参数、API 响应、配置、任务身份或产物格式时，应同步说明。

测试使用临时工作区。不提交 .env、token、私有数据、运行时 .axonx/ 内容、日志和生成产物。截图中不得包含凭据或私有会话内容。

验证

按改动范围选择检查，在 PR 中说明命令和结果。Python 或插件改动先运行相关测试，再按需要运行非集成测试集：

pytest tests/unit/<affected_test_file>.py
pytest
pre-commit run --all-files

直接运行 pytest 会排除标记为 integration 的测试。运行 pytest -m integration 前，应准备必要凭据与服务，并检查测试对外部系统的影响。无法运行的检查请说明原因。

Studio 改动在 axonx_studio/ 中运行：

npm run test
npm run lint
npm run format:check
npm run build

检查相关界面的中英文流程，包括空数据与请求失败。

文档或主题改动在 github-pages/ 中运行：

npm ci && npm run build

构建会验证渲染页面和 Markdown 导出。根目录及插件 README 和贡献指南由同一构建直接渲染；同步更新中英文，并核查示例命令。

文档贡献

修改 docs/ 下的规范指南，或站点引用的根目录/插件 README 与贡献指南，同步更新中英文。保持相同路径，共享素材放在 docs/figures/。站点导航定义位于 docs/.vitepress/navigation.mjs。

不修改 github-pages/.generated/ 或 github-pages/dist/，它们会重新生成。站点开发与部署见 github-pages/README.md。根目录 README 和贡献指南中的说明变化也应保持双语一致。

提交 Pull Request

使用清晰的标题，推荐 Conventional Commits，例如 fix(tasks): preserve run status 或 docs: clarify quick start。说明问题、改动后的行为、兼容性影响和验证结果。可见 UI 改动附上截图，注明跳过的外部服务测试。

PR 模板会提示这些信息。请列出验证命令和结果，解释未运行检查的原因，并说明中英文文档更新情况。不适用的可选章节可以删除。

贡献遵循项目的 Apache License 2.0。

发布

主包和 Studio 独立发布。发布前提交版本更新并确保相关 CI 通过；集成测试需要模型 API key，仅在本地按需执行。

• AxonX：更新 axonx/_version.py，创建并推送 v<version> 标签。发布该标签的 GitHub Release 会自动上传 axonx 到 PyPI；也可手动运行 Release / AxonX Python package，输入不带 v 的版本号。
• Studio：同步 axonx_studio/pyproject.toml、package.json 和 package-lock.json 的版本，推送到 main。手动运行 Release / AxonX Studio 并选择 main 分支，版本自动读取，不需要标签或版本输入。默认 both 先发布 PyPI 再发布 npm；pypi、npm 可独立发布。npm 标签自动选择：稳定版本使用 latest，预发布版本使用 next。

AxonX 从发布标签构建；Studio 从手动运行时选定的 main 提交构建。两者都校验产物版本。Studio 的 Python/npm 包携带同一份静态资源，预发布版本在 Python 产物中按 PEP 440 规范化。主包发布不会上传研究插件。

打包 CI 还会检查研究插件的 wheel 和 sdist 是否包含全部 Python 模块及 tool.setuptools.package-data 声明的数据文件，并逐字节比较它们与源码的内容。添加运行时资源时，请更新 package-data 声明；声明的模式必须能匹配到源码文件。

在 PyPI 为 axonx 和 axonx-studio 分别配置对应工作流的 Trusted Publisher，环境名为 pypi。在 npm 为 @flowllm-ai/axonx-studio 配置 release-axonx-studio.yml 的 Trusted Publisher，环境名为 npm。新的 npm 包需先完成首次发布，再配置 Trusted Publishing。

版本已存在时发布失败，不覆盖或静默跳过。双发中 npm 失败后，优先在原 workflow run 中重跑失败 job，复用同一份产物。也可单包发布；通过新运行补发时应保持 Studio 源码不变。AxonX 发布标签不可移动。