ituac-crypto-hub/AGENTS.md

ituac-crypto-hub 开发约定

定位与边界

• 本仓库提供 ETH、后续 BTC 等链相关操作的 Python 能力库，不是交易所、交易策略或资产托管系统。
• 默认中文沟通和文档，英文代码标识；仅修改本仓库内与当前任务相关的文件。
• 开始前检查 git status --short --branch、HEAD（新仓库可能不存在）及相关差异。 保留用户已有的工作树和暂存区内容，不自动提交、推送、重置、清理、部署或操作数据库。
• 仅讨论或只读请求不构成开发授权。新增依赖、框架和真实链操作应与明确需求匹配。

架构约束

• 使用 Python 3.11+、src/core、src/eth 同级包布局及 pyproject.toml 构建配置。
• core 仅容纳已被实际需求证明的公共原语；不能反向依赖币种包或链 SDK。
• eth、未来 btc 等包同级且互不依赖，各自拥有链模型、用例和适配器。
• 不把 ETH 的账户、nonce、gas 等概念强加给其他链；不提前实现万能基类、注册中心或空服务层。
• 外部节点、SDK、签名器接入时放入对应链的适配器，通过明确接口注入；导入包不得发起网络请求。
• 只导出稳定公共接口；新增能力、依赖、执行方式或边界时同步更新 README 和架构文档。

金额、资金与安全

• 链上金额用最小单位整数；人类可读金额只接受明确的十进制字符串或 Decimal。 拒绝 float、非法数、负金额和不可精确表示的最小单位，不隐式四舍五入。
• 不手写密码学算法，不把通用地址格式检查描述成完整校验；代币精度不能套用 ETH 原生币精度。
• 不读取、打印、硬编码或提交真实私钥、助记词、RPC 凭据。忽略规则不能替代秘密审查。
• 网络和 chain ID 必须显式指定并核验，不默认连接主网；测试默认离线，集成测试明确选择加入。
• 签名、广播、授权合约、转账属于独立高风险操作，必须明确目标网络、账户、金额、费用及用户授权。
• 后续实现必须分离构建、签名、广播、回执和最终确认；广播超时是结果未知，不代表失败，不能盲目重试。
• 未支持或状态未知时明确报错，不能伪造余额、交易成功或确认状态。

代码与最小验证

• 公共函数需类型注解和契约说明；模块小而职责单一，异常类型明确，避免吞掉外部错误。

• 单元测试使用标准库 unittest，按币种组织；先覆盖实际行为、错误边界与金额精度， 不为增加测试数量堆积相同断言。网络替身的结果不能被描述为真实链验证。

• 保留 tests/__init__.py，测试发现使用 -t .，避免 tests/eth 被当作顶层 eth 遮蔽源码包。

• 当前不安装依赖即可在根目录执行：

  PYTHONPATH=src python3 -m unittest discover -s tests -t . -v
  python3 -m compileall -q src tests
  git diff --check
  

• 修改打包配置时，在本地虚拟环境验证安装与包导入，不修改全局 Python 环境。

• 交付时检查新增文件和最终差异，说明已完成、实际验证、未验证范围；不把离线测试通过宣称为真实资金闭环。