多策略、多交易所、多加密资产
官方对自己的定位就是这三多。因此它的架构取舍是：通用逻辑留在主仓库，与某个策略或某家交易所绑定的逻辑下沉到对应 tentacle。
OctoBot 项目研究站 · 二次开发
OctoBot 二次开发：改哪里、怎么构建、按什么约定写
想给 OctoBot 加策略或加交易所支持，先接受一个前提：这是一个用 Pants 2.30.0 构建、按 16 个子包拆分、要求 Python 3.13 的工程化仓库。官方把开发约定写进了 CLAUDE.md（枚举放 enums.py、常量放 constants.py、用 typed error 层级、结构化 dict 用 TypedDict），把贡献流程写进了 CONTRIBUTING.md（PR 打 dev 分支、配套 pytest、PEP8 行长 120）。这一页把它们摊平，作为动手前的检查单。
octobot/ 主包api / automation / backtesting / channels…
packages/ 16 子包tentacles / trading / evaluators…
构建与依赖Pants 2.30.0、无 lockfile、3.13
测试与提交pytest、dev 分支、PEP8 120
Philosophy
OctoBot 二次开发的官方哲学是什么：先看这三条
CONTRIBUTING.md 开头就把「改动放哪」讲清楚了。
策略改动进策略 tentacle
官方原文：任何与某个策略相关的改动都应放在该策略自己的代码里，通常在该策略的 tentacle 中；与某交易所相关的改动放进该交易所的 tentacle。
与币种/交易对绑定的改动会被拒
官方明确：与某个加密货币或交易对绑定的改动，除非在通用代码中有充分理由，否则会被拒绝。这一条直接影响你 PR 的设计方式。
Structure
OctoBot 的仓库结构：主包与 16 个子包怎么分工
下表按目录列出 OctoBot 的来源；本站只说明其存在与名称含义，未逐包核验实现。
| 位置 | 包含 | 什么时候会改到 | 注意点 |
|---|---|---|---|
octobot/ | api、automation、backtesting、channels、community、config、producers、storage、strategy_optimizer、updater 十个子目录 + cli/commands/initializer/octobot_node/task_manager 等模块 | 改引擎行为、启动流程、配置管理 | 属于通用代码，改动影响面较广 |
packages/ | agents、async_channel、backtesting、binary、client、commons、copy、evaluators、flow、node、protocol、services、sync、tentacles、tentacles_manager、trading | 按职责定位改动位置 | Pants 以包为单位管理依赖 |
docs/ | Docusaurus 3 站点（content/、blog/、i18n/、static/、sidebars.ts、docusaurus.config.ts、wrangler 部署配置） | 写文档时（包文档放 docs/content/developers/packages/<pkg>/） | 官方要求文档写「为什么」而不是逐行解释代码 |
tests/ + additional_tests/ | 单元/功能测试目录，含独立 Dockerfile 与 docker-entrypoint.sh | 任何改动都要求配套测试 | CONTRIBUTING 要求变更通过 tests 目录下对应 pytest 用例验证 |
bin/ | start.spec（PyInstaller 打包配置）与 favicon | 改打包产物时 | 影响官方可执行文件的构建 |
.claude/agents/ | tentacle-manager 与 test-runner 两个 agent 定义 | 导出/安装 tentacles、跑测试 | 用 @agent-<name> 触发 |
| 根文件 | start.py、setup.py、requirements.txt/full_requirements.txt、pants.toml、BUILD、Dockerfile、docker-compose.yml、CHANGELOG.md、CLAUDE.md、Cargo.toml、package.json、octobot.hcl | 改依赖、构建、容器或文档规则 | 仓库没有 pyproject.toml，元数据在 setup.py/setup.cfg |
Env
怎么搭 OctoBot 的本地环境：三条命令与一个路径陷阱
顺序来自 CLAUDE.md，照做能避开最常见的失败。
装 Pants 启动器
官方下载
scie-pants到/usr/local/bin/pants，赋可执行权限后运行pants --version触发引导，打印 2.30.0 表示就绪。若内网取不到 pex，官方给出临时把pex-cli.url_template指向本地文件的方案（明确要求不要提交）。建虚拟环境装依赖
python3.13 -m venv .venv，再.venv/bin/pip install -r requirements.txt -r full_requirements.txt；官方建议用.venv/bin/python作为运行与调试解释器。设置 PYTHONPATH（最容易踩的一步）
必须包含仓库根目录与各 packages 子目录：不装 tentacles 时 15 项，装完后 16 项（多出
packages/tentacles）。官方强调必须用绝对路径——因为构建子进程会从 tentacle 子目录里运行。
为什么没有 lockfile：
pants.toml 里 enable_resolves = false，仓库不提交锁定文件，Pants 每次按 python_requirement 目标直接解析依赖。这意味着依赖版本以清单里的钉死版本为准，改动要谨慎。Conventions
OctoBot 的代码约定有哪些（CLAUDE.md 里的硬要求）
这些不是建议，而是仓库内的既有约定。
| 约定 | 官方要求 | 为什么 | 反例 |
|---|---|---|---|
| 枚举位置 | 放 <package_root>/enums.py | 统一查找与复用 | 在模块文件里就地定义枚举 |
| 常量位置 | 模块级常量放 constants.py；仅本文件用的私有常量可留在原文件并以 _ 前缀 | 区分公共与私有 | 公共常量散落在各模块 |
| 错误类型 | 定义 typed error 层级（如 FeatureError → SpecificError），从包 __init__.py 再导出 | 便于按类型捕获 | 抛裸 ValueError/KeyError，或靠 str(err).lower() 判断 |
| 结构化字典 | 固定 schema 的 dict 用 TypedDict，放在产出它的模块里、类之前 | 类型可读性与静态检查 | 用裸 dict 传结构化数据 |
| tentacle 导入优先级 | 先试 tentacles.Services.Interfaces.*，失败再回退裸导入；同一 tentacle 包内保持一致 | 兼容安装态与构建态两条路径 | 同一包里混用两种导入顺序 |
| 日志级别 | debug/info/warning/error/exception 各有明确语义；exception 除顶层兜底外要重新抛出 | 日志可被依赖 | 吞掉异常只打一行 log |
| 共享工具 | 多处复用的过滤逻辑放共享模块（官方举例 workflows_util.py），命名用动词（如 filter_by_wallet） | 避免复制粘贴 | 各模块内重复实现同一过滤 |
Contribute
给 OctoBot 提交 PR 前：测试与流程要求
CONTRIBUTING.md 的要点，逐条对应到动作。
| 环节 | 要求 | 适用场景 | 注意点 |
|---|---|---|---|
| 目标分支 | OctoBot 与 Tentacles 仓库的 PR 打 dev 分支，其他仓库打 master | 给上游提 PR | 打错分支会被直接要求重开 |
| 测试 | 变更必须通过 tests 目录下对应的 pytest 用例验证 | 任何功能改动 | 没有配套测试的 PR 很难推进 |
| 代码风格 | PEP8，行长上限 120；官方偏好用生成器与推导式替代循环、在「if 99% 为真」时用 try/except | 写完准备提交前 | 这些是官方明示的偏好，不是可选项 |
| 新增依赖 | 只有在系统级必需时才允许加入主代码；否则先开 issue 讨论，或把该依赖做成可选导入 | 你的功能需要第三方库 | 直接加进 requirements 大概率被拒 |
| 文档 | 写在 docs/content/，包文档放对应子目录；每篇 .md 需 Docusaurus frontmatter | 改动需要说明时 | 官方明确不要贴函数签名、目录树、版本号这类会过期的内容 |
| 一键云端开发 | README 提供 Ona（原 Gitpod）按钮，.gitpod.yml 在仓库中 | 不想配本地环境 | 仓库还提供 VSCode/PyCharm 的开发者环境指南 |
仓库里有现成的 agent 可用：
.claude/agents/ 定义了 tentacle-manager（导出/安装 tentacles、从 CCXT 生成交易所 tentacle）与 test-runner（跑并调试测试）。官方说明用 @agent-<name> 触发，例如 @agent-test-runner run node tests。FAQ
OctoBot 二次开发常见问题：改哪里、怎么提交
我不会 Pants，能用 pip 直接开发吗？
可以，但有限制：仓库的构建与依赖管理以 Pants 为中心（无 lockfile、pants.toml 定义解释器约束），官方文档仍给出用 venv + pip install -r requirements.txt -r full_requirements.txt 做本地 IDE/调试的解释器方案。要跑测试或提交 PR，建议按官方环境搭建。
为什么一定要 Python 3.13？
因为 setup.py 声明 REQUIRES_PYTHON = '>=3.13'，分类器只列 3.13，pants.toml 的解释器约束是 ==3.13.*。官方特别提醒约束要带通配符，写成 ==3.13 会只匹配 3.13.0。用低版本解释器会在依赖解析阶段就失败。
我加的策略能直接进主仓库吗？
按官方哲学，策略专属逻辑应放进该策略自己的 tentacle（通常在 OctoBot-tentacles 仓库）。主仓库只接受通用能力；与特定币种/交易对绑定的改动会被拒绝，除非在通用代码中有充分理由。
改运行时的 tentacles/ 目录行不行？
不行。官方明确 tentacles/ 是从 packages/tentacles/ 导出并安装生成的，直接编辑会被覆盖。改动一律写在源码真值目录，然后跑导出+安装。
提交前除了测试还要准备什么？
按 CONTRIBUTING：PR 打 dev 分支、通过对应 pytest 用例、符合 PEP8（120 行长）。如果涉及新依赖，先按官方要求走讨论或做成可选导入；如果涉及文档，写进 docs/content/ 并带 frontmatter。
本站读过源码了吗？
本站只抓取了仓库公开的配置、文档与目录结构（README、setup.py、requirements、Dockerfile、CLAUDE.md、CONTRIBUTING.md 与目录列表），未逐模块阅读实现代码，也未在本机构建运行。页面描述以官方仓库当前版本为准。