Skip to content

参与 AxonX 贡献 ​

English · 简体中文

欢迎修复问题、开发研究插件、补充实验证据和文档。先搜索已有 Issue,提供复现步骤、预期/实际行为、版本与脱敏日志。大规模公开契约变更先讨论设计,每个 PR 聚焦一个问题。

开发环境 ​

macOS 或 Linux 使用 Python 3.12+,从源码仓库根目录执行:

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

Studio 使用 Node.js 22.13+(22.x)、24.x 或 26+:

bash
cd axonx_studio
npm ci
npm run dev

另开终端,从仓库根目录启动 Python 服务:

bash
export AXONX_SERVICE_TOKEN='replace-with-your-service-token'
axonx app --service.host 127.0.0.1

默认端口为 1024,运行数据位于 .axonx/,Task 日志保存在各自 Task 目录,服务/启动日志位于 logs/。可选凭据与内置配置变量见 example.env。CLI 启动时从当前目录或最多五级父目录加载最近的 .env,保留已有环境变量。代理与构建设置见 Studio 开发。

YAML 继承与安装配置见服务端配置,执行选项见 CLI 参考。自定义配置只有显式声明 extends: default 才继承默认值。凭据和运行产物不得提交。

选择修改位置 ​

位置职责
axonx/task/类型模型、开发基类、同步运行时、存储与内置 Task
axonx/plugin/插件发现、wheel 校验与安装
axonx/utils/共享环境、日志、值转换与异步清理
axonx/app/、axonx/client/应用能力、Job、传输和客户端连接
axonx/cli/、axonx/daemon/命令路由、服务监督与定时进程归属
plugins/研究算法、manifest 与插件测试
axonx_studio/界面、表单、API 客户端与研究视图
docs/、github-pages/双语指南、图片、导航与站点工具

算法放在 Task/插件中。Task 执行不依赖 App、Plugin 或 CLI,由启动层装配目录并注入宿主能力。app/core/composition.py 选择具体 Provider 并编排受管生命周期,Step 通过组件基类契约适配 Job。HTTP/MCP 客户端保持独立于 App。从所属模块导入,数据契约不执行运行时操作,资源须明确清理。详见架构、框架扩展和依赖图。

开发插件 ​

研究算法放在插件中。Task 开发遵循开发与运行指南,安装和远程部署见插件管理,Studio 接入见产物契约。先从源码安装 qlib_a158;qlib_factor 和 qlib_strategy 分别独立扩展它。

Agent 编写的代码遵循相同检查。改进结论需保留代码/数据版本、窗口、参数、成本、Task ID 和 started_at,并遵循实验设计。

验证改动 ​

先运行受影响检查,再运行相关测试集。在 PR 中记录命令、结果和未运行的检查。

范围检查
框架python -m pytest tests
插件对应测试目录,例如 python -m pytest plugins/qlib_factor/tests
Studio在 axonx_studio/ 执行 npm test、npm run lint、npm run format:check、npm run build
Python 传输契约在 axonx_studio/ 执行 npm run contracts:generate 和 npm run contracts:check
文档示例python -m pytest tests/unit/test_documentation_contracts.py

另用 python -m scripts.sync_agent_guides --check 检查 Agent 资源;架构变更运行 python -m pytest tests/unit/test_module_boundaries.py。

裸命令 pytest 还会收集插件测试,需准备研究依赖。默认不执行集成测试;运行 python -m pytest tests/integration -m integration 前,准备所需服务和凭据并检查外部影响。

契约生成同时更新 axonx_studio/src/shared/api/contracts.ts 和 axonx_studio/src/playground/job-contracts.json。修改 Python 序列化模型、默认 Job 后重新生成,不手改生成文件。

测试使用临时工作区,不提交凭据、私有数据、.axonx/、日志或研究生成产物。界面检查覆盖中英文、空数据和请求失败。将实际文件路径传入 pre-commit run --files <changed-files>,检查自动修复结果。Hooks 使用 Ruff 整理导入、Black 格式化,并执行其他 lint 检查。

更新文档 ​

文档只描述本框架、仓库内组件和插件,示例使用仓库内实现。外部插件的业务规则、存储布局和部署由其自身文档说明。

修改 docs/{en,zh}/ 的中英文规范来源,或由站点导入的根目录/插件 README。操作步骤放在指南,字段放在参考,算法放在插件 README,实验证据放在案例;通过链接引用归属文档,避免复制正文。导航位于 docs/.vitepress/navigation.mjs,共享图示位于 docs/figures/。

Job 入参以 axonx/app/config/default.yaml 为准,CLI 语法属于 axonx/cli/parser.py,执行属于 commands.py/remote.py,Task 契约属于 axonx/task。同步更新受影响示例和图示,保留历史研究结果及来源。

修改 docs/{en,zh}/dev_guide.md 后运行 python -m scripts.sync_agent_guides 和 python -m scripts.sync_agent_guides --check,生成包内指南与 skills/axonx/SKILL.md。这些独立资源有意保留完整指南。

在 axonx_studio/ 和 github-pages/ 安装依赖后运行:

bash
npm --prefix github-pages test
npm --prefix github-pages run build

构建验证双语导航、链接、锚点、资源和 Markdown 导出。生成、图示、部署和 Vercel 设置见站点维护。

提交 Pull Request ​

说明问题、改动后的行为、受影响的契约与验证结果。可见界面改动附截图,注明文档更新情况,推荐 Conventional Commits 标题。贡献遵循 Apache License 2.0。

发布 ​

主包与 Studio 共用 axonx/_version.py 中的版本号,统一使用 Release / AxonX 工作流:

  1. 只编辑并提交 axonx/_version.py。Studio Python 打包通过源码符号链接读取它,Vite 在构建时注入版本,npm 打包时生成临时清单。更新版本无需改动元数据、契约或文档。稳定版使用 X.Y.Z,预发布版使用 X.Y.Z-{alpha,beta,rc}.N;Python 包元数据会规范化预发布版本格式。
  2. CI 通过后推送 v<version> 并发布对应 GitHub Release,默认 both:同时发布 PyPI 的 axonx、axonx-studio 和 npm 的 @flowllm-ai/axonx-studio。
  3. 如需选择发布范围,手动运行同一个工作流,输入已有标签的版本号(不带 v)。publish_target 提供 both(默认,全部)、backend(仅 AxonX PyPI)和 studio(Studio PyPI 与 npm)。选项位于 Actions → Release / AxonX → Run workflow;GitHub Release 表单没有包选择项。

每次运行都会从同一标签测试并构建前后端,上传前校验标签与源码版本一致。构建会验证研究插件,但不会发布它们。Studio 先发 PyPI 再发 npm;稳定版 npm 标签为 latest,预发布版为 next。

为两个 PyPI 项目和 npm 包配置 Trusted Publisher,工作流文件名统一为 release.yml,分别使用 pypi/npm 环境。已有版本会发布失败,标签不可移动。跨仓库上传不是原子操作。某个发布 job 失败时,在原 workflow 重跑失败 job,以复用产物并避免重新发布已成功的 job。

PyPI 发布矩阵统一使用 Twine 内置的 Trusted Publishing 身份认证,并在生成 Sigstore 签名证明之前检查包元数据。如果签名证明生成失败或超过两分钟,工作流会发出警告,然后不带签名证明继续上传。元数据、身份认证、版本重复和上传错误仍会使发布失败。

AxonX Skill 随同一仓库和 AxonX 版本标签分发。发布前按上文同步 Agent 指南,并执行 gh skill publish --dry-run。复用 AxonX Release;不带 --dry-run 的 gh skill publish 会创建 GitHub Release,v<version> 发布会触发统一发布工作流。

Agent-native quant research.