mopr 0.0.98__tar.gz → 0.0.111.dev167__tar.gz

{mopr-0.0.98 → mopr-0.0.111.dev167}/.gitignore

@@ -44,6 +44,8 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+# CMake 在仓库根生成的一次性"系统信息"工程(工具链探测的副产物, 不是源码)
+__cmake_systeminformation/
 develop-eggs/
 dist/
 downloads/

mopr-0.0.111.dev167/AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md — AI 助手入口
+
+> **本仓库的规范源是 [CONTRIBUTING.md](CONTRIBUTING.md)**：规则、约定与判据全部在那里。
+> 本文件只做三件事 —— 告诉 AI 该读什么、哪些线不能踩、改完怎么验。**与 CONTRIBUTING.md 冲突时
+> 以后者为准**；本文件不复制细则，只给指针。
+
+## 1. 开工前必读
+
+按顺序读，读完再动手：
+
+| 顺序 | 读什么 | 为什么 |
+| --- | --- | --- |
+| 1 | [CONTRIBUTING.md](CONTRIBUTING.md) | 规范全集：语言角色、命名、注释、文档、测试、提交 |
+| 2 | 目标模块的 `README.md` 与同名 `.md` | 该模块的口径、跨语言对照、已知缺口（`§5 TODO`） |
+| 3 | **该语义的 Python 实现（spec）与 Python 用例** | 语义以此为准；不要拿其它语言的既有实现反推 spec |
+
+## 2. 硬约束
+
+| # | 约束 | 细则 |
+| --- | --- | --- |
+| 1 | **Python 是 spec**，语义、API、默认行为、失败约定一律以它为准；生产实现为 **C++ / Rust**（可互为替代），Go / Zig / Java 等为扩展 | [§2.3](CONTRIBUTING.md#23-语言角色与演进顺序) |
+| 2 | **不自己造东西**：不造 Python 里没有的结构 / 函数名 / 逻辑；需要新能力先补 Python spec，再推广 | [§4.1](CONTRIBUTING.md#41-总纲snake_case-优先) |
+| 3 | **读 spec 代码，不读注释猜**；怀疑 spec 有错时先跑 Python 验证，再与用户商定是否改 spec | [§2.3](CONTRIBUTING.md#23-语言角色与演进顺序) |
+| 4 | **注释只说"是什么 / 怎么做 / 为什么这样"**，不写"本轮改了啥、上一版是什么" | [§5.1](CONTRIBUTING.md#51-注释只说是什么怎么做) |
+| 5 | **通用能力先查 `base/`**，不写私有副本；缺就补 base | [§5.2](CONTRIBUTING.md#52-通用能力优先落-base) |
+| 6 | **不擅自加开关**；调试开关一律 `debug_` 前缀 | [§5.3](CONTRIBUTING.md#53-调试开关) |
+| 7 | **写盘必须幂等**：同一批输入跑多遍，产物一致 | [§5.4](CONTRIBUTING.md#54-重复触发与幂等) |
+| 8 | **文档与代码同批**：新目录带 `README.md`，跨语言模块带同名 `.md` | [§6](CONTRIBUTING.md#6-文档规范) |
+| 9 | **编码与行尾**：UTF-8 无 BOM、LF、末尾一个换行 | [§5.8](CONTRIBUTING.md#58-文件编码与行尾) |
+| 10 | **不擅自 `git commit` / `push` / `rebase`**；提交信息按模板，Windows 下用 `-F` 传文件 | [§8](CONTRIBUTING.md#8-git-提交规范) |
+| 11 | **对照表列序固定** `python → c++ → rust → go → zig → java`；前四门必须实现，`zig` / `java` 可选（缺失不影响状态） | [§2.3](CONTRIBUTING.md#23-语言角色与演进顺序) |
+
+## 3. 主题索引
+
+| 我要… | 去哪 |
+| --- | --- |
+| 查语言最低版本 / 编译器基线 | [§2](CONTRIBUTING.md#2-语言与版本基线) |
+| 决定文件放哪、叫什么 | [§3](CONTRIBUTING.md#3-目录与多语言布局) |
+| 定函数名 / 命名空间 / 头文件守卫宏 | [§4](CONTRIBUTING.md#4-命名与数据契约) |
+| 定整型 / 浮点的跨语言名与宽度 | [§4.6](CONTRIBUTING.md#46-标量类型整型-浮点) |
+| 写注释、判断该不该写某句 | [§5.1](CONTRIBUTING.md#51-注释只说是什么怎么做) |
+| 找某个通用能力该不该落 `base/` | [§5.2](CONTRIBUTING.md#52-通用能力优先落-base) |
+| 处理重复触发 / 幂等 | [§5.4](CONTRIBUTING.md#54-重复触发与幂等) |
+| 跑 Python、写 import | [§5.5](CONTRIBUTING.md#55-python-包形态与导入) |
+| 写 `#include` | [§5.6](CONTRIBUTING.md#56-c-头文件引用) |
+| 处理字符串 | [§5.7](CONTRIBUTING.md#57-c-字符串处理复用) |
+| 写模块文档 / 判"算不算完成" | [§6](CONTRIBUTING.md#6-文档规范) |
+| 写测试 | [§7](CONTRIBUTING.md#7-测试规范) |
+| 写提交信息 | [§8.1](CONTRIBUTING.md#81-提交信息) |
+| 判断要不要立提案 | [§9](CONTRIBUTING.md#9-提案与验证工作流) |
+| 构建 / 依赖 / 发布 | [BUILDING.md](BUILDING.md) |
+
+## 4. 常用命令
+
+| 目的 | 命令 |
+| --- | --- |
+| C++ 全量构建 | `cmake --build build/debug-dynamic --config Debug --target mopr_tests` |
+| C++ 跑用例 | `./build/debug-dynamic/tests/Debug/mopr_tests.exe --gtest_filter="<Suite>.*"` |
+| 联网用例（默认跳过） | 置 `MOPR_FOREX_ONLINE=1`，且只跑在临时 home 内 |
+| Python 包化跑用例 | `python -m mopr.<模块>.<子模块>_test`（禁止 `pytest <目录>`） |
+| 跨语言一致性对照 | `python -m tools.crosscheck`（用例见 `tests/fixtures/`） |
+| 编码自查 | 见 [§5.8](CONTRIBUTING.md#58-文件编码与行尾) 的 PowerShell 片段 |
+| 提交（Windows） | 写入 `.git/commit-msg.tmp` 后 `git commit -F .git/commit-msg.tmp` |
+
+## 5. 交付前自检
+
+1. **语义**：与 Python spec 逐值对拍过（不是"看起来一样"）；有差异先改实现，或与用户商定改 spec。
+2. **构建与用例**：全量编译通过、相关用例通过；跳过项（在线 / 依赖外部数据）要能说明原因。
+3. **注释**：没有"本轮 / 上一版 / 原来 / 曾经"这类变更叙事（[§5.1](CONTRIBUTING.md#51-注释只说是什么怎么做)）。
+4. **文档**：目录 `README.md`、模块 `.md` 的路线图 / 功能表 / 测试 / TODO 与实际一致，无陈旧条目。
+5. **编码**：UTF-8 无 BOM、LF、末尾换行（[§5.8](CONTRIBUTING.md#58-文件编码与行尾)）。
+6. **提交信息**：符合 `type[language]:summary`，正文分条，无版本号 / 代理署名。

{mopr-0.0.98 → mopr-0.0.111.dev167}/BUILDING.md

@@ -300,18 +300,18 @@ powershell -ExecutionPolicy Bypass -File .\refresh-clangd.ps1
 
 > 注意：clangd 只是编辑器提示，**与编译结果无关**——构建始终以 VS preset / Build 按钮为准；若 clangd 报错而构建通过，以构建为准。
 
-### 2.8 版本发布（autochangelog）
+### 2.8 版本发布（auto-changelog）
 
-mopr 的版本号不写死：CMake（`cmake/git_tag_info.cmake`）与 Conan（`conanfile.py` 的 `set_version`）均自动取 git 仓库最新 `v0.0.x` tag 作为构建版本；tag 与 CHANGELOG 由 **[autochangelog](https://gitee.com/quant1x/autochangelog)** 统一生成，Agent 与协作者不手动打 tag（见 AGENTS.md）。
+mopr 的版本号不写死：CMake（`cmake/git_tag_info.cmake`）与 Conan（`conanfile.py` 的 `set_version`）均自动取 git 仓库最新 `v0.0.x` tag 作为构建版本；tag 与 CHANGELOG 由 **[auto-changelog](https://github.com/quant1x/auto-changelog)** 统一生成，Agent 与协作者不手动打 tag（见 CONTRIBUTING.md）。
 
-**安装 autochangelog**（需要 Go 工具链，对应 mopr 的 Go 基线 1.27+）：
+**安装 auto-changelog**（需要 Go 工具链，对应 mopr 的 Go 基线 1.27+）：
 
 ```powershell
-go install gitee.com/quant1x/autochangelog@latest
+go install github.com/quant1x/auto-changelog@latest
 ```
 
-- 产物位于 `%USERPROFILE%\go\bin\autochangelog.exe`；若命令找不到，把该目录加入 PATH 后重开终端；
-- 如需安装指定版本，将 `@latest` 替换为版本号即可，例如 `go install gitee.com/quant1x/autochangelog@v1.4.3`。
+- 产物位于 `%USERPROFILE%\go\bin\auto-changelog.exe`；若命令找不到，把该目录加入 PATH 后重开终端；
+- 如需安装指定版本，将 `@latest` 替换为版本号即可，例如 `go install github.com/quant1x/auto-changelog@v1.4.3`。
 
 **发布前刷新第三方声明**：conan 依赖变更后，先按 6「第三方声明与许可证归档」运行 `python -m tools.license_audit cpp`，确认无「缺失 / 待人工补录」输出；`THIRD-PARTY-NOTICES.md` 与 `third_party/licenses/` 随发布产物一并附带。
 
@@ -655,7 +655,7 @@ use mopr::distributed;
 
 #### 3.5.2 安装
 
-前置：Rust 工具链可用（`cargo --version` 不低于本仓基线 1.98.1+，见 AGENTS.md）。三个外部工具都是 cargo 子命令插件，统一经 `cargo install` 编译安装到 `%USERPROFILE%\.cargo\bin`（rustup 通常已将该目录写入 PATH，新装后重开终端生效）：
+前置：Rust 工具链可用（`cargo --version` 不低于本仓基线 1.98.1+，见 CONTRIBUTING.md）。三个外部工具都是 cargo 子命令插件，统一经 `cargo install` 编译安装到 `%USERPROFILE%\.cargo\bin`（rustup 通常已将该目录写入 PATH，新装后重开终端生效）：
 
 ```powershell
 cargo install --locked cargo-deny
@@ -792,7 +792,7 @@ mvn -Pbench -Dtest=ringbuffer_LMAXDisruptorBenchmark test    # 只跑基准
 
 | 约束 | 值 | 说明 |
 | --- | --- | --- |
-| Go 最低版本 | **1.27.0** | `go.mod` 已声明 `go 1.27.0`；本仓库 Go 基线 1.27+，与 README「语言与版本要求」、AGENTS.md 一致 |
+| Go 最低版本 | **1.27.0** | `go.mod` 已声明 `go 1.27.0`；本仓库 Go 基线 1.27+，与 README「语言与版本要求」、CONTRIBUTING.md 一致 |
 
 本机工具链版本用 `go version` 核对，应不低于 `go1.27.0`（当前验证环境：Windows + `go1.27.0`）。