规范文件

2026-06-07 14:21:04 +08:00
parent c83cddbcc4
commit 4bf9461009
8 changed files with 2905 additions and 826 deletions
@@ -0,0 +1,182 @@
+---
+name: Bug 报告
+about: 创建一个 Bug 报告帮助我们改进
+title: "[Bug] "
+labels: bug
+assignees: []
+---
+
+## Bug 描述
+
+请简洁清晰地描述这个 Bug。
+
+## 复现步骤
+
+请提供最简化的复现步骤（代码片段或操作序列）：
+
+1. 
+2. 
+3. 
+4. 
+
+## 预期行为
+
+请描述您期望发生的结果。
+
+## 实际行为
+
+请描述实际发生的结果。包括完整的错误消息、panic 信息或日志输出。
+
+## 环境
+
+| 项目 | 版本 |
+|------|------|
+| Rust 版本 | `rustc --version` 输出 |
+| Crate 版本 | `chanlun` 版本号 |
+| 操作系统 | Linux / macOS / Windows |
+| 数据文件（.nb） | 文件路径或来源 |
+
+## 复现代码
+
+请粘贴可复现问题的最小 Rust 代码或 Python 代码。
+
+**Rust:**
+
+```rust
+use chanlun::config::缠论配置;
+use chanlun::kline::bar::K线;
+use chanlun::business::observer::观察者;
+
+// 复现代码
+```
+
+**Python (绑定层):**
+
+```python
+import chanlun
+
+# 复现代码
+```
+
+## 缠论配置
+
+请提供您使用的完整配置（JSON 或代码形式）。这对于复现问题至关重要。
+
+<details>
+<summary>展开查看配置 JSON</summary>
+
+```json
+{
+  "标识": "btcusd",
+  "缠K合并替换": false,
+  "笔内元素数量": 5,
+  "笔内相同终点取舍": false,
+  "笔内起始分型包含整笔": false,
+  "笔内起始分型包含整笔_包括右": false,
+  "笔内原始K线包含整笔": false,
+  "笔次级成笔": false,
+  "笔弱化": false,
+  "笔弱化_原始数量": 3,
+  "线段_非缺口下穿刺": false,
+  "线段_特征序列忽视老阴老阳": false,
+  "线段_缺口后紧急修正": true,
+  "线段_修正": false,
+  "线段内部中枢图显": true,
+  "扩展线段_当下分析": false,
+  "分析笔": true,
+  "分析线段": true,
+  "分析扩展线段": true,
+  "分析笔中枢": true,
+  "分析线段中枢": true,
+  "手动终止": "",
+  "计算指标": true,
+  "计算BOLL": false,
+  "指标计算方式": "收",
+  "平滑异同移动平均线_快线周期": 13,
+  "平滑异同移动平均线_慢线周期": 31,
+  "平滑异同移动平均线_信号周期": 11,
+  "MACD_参数列表": [],
+  "相对强弱指数_周期": 13,
+  "相对强弱指数_移动平均线周期": 13,
+  "相对强弱指数_超买阈值": 75.0,
+  "相对强弱指数_超卖阈值": 25.0,
+  "RSI_周期列表": [],
+  "随机指标_RSV周期": 13,
+  "随机指标_K值平滑周期": 5,
+  "随机指标_D值平滑周期": 5,
+  "随机指标_超买阈值": 80.0,
+  "随机指标_超卖阈值": 20.0,
+  "KDJ_参数列表": [],
+  "布林带_周期": 20,
+  "布林带_标准差倍数": 2.0,
+  "BOLL_参数列表": [],
+  "均线_类型列表": [],
+  "均线_周期列表": [],
+  "图表展示": true,
+  "推送K线": true,
+  "推送笔": true,
+  "推送线段": true,
+  "推送中枢": true,
+  "图表展示_笔": true,
+  "图表展示_线段": true,
+  "图表展示_扩展线段": true,
+  "图表展示_扩展线段_线段": true,
+  "图表展示_线段_线段": true,
+  "图表展示_中枢_笔": true,
+  "图表展示_中枢_线段": true,
+  "图表展示_中枢_扩展线段": true,
+  "图表展示_中枢_扩展线段_线段": true,
+  "图表展示_中枢_线段_线段": true,
+  "图表展示_中枢_线段内部": true,
+  "买卖点偏移": 1,
+  "买卖点激进识别": false,
+  "买卖点与MACD柱强相关": false,
+  "买卖点错过误差值": 0.01,
+  "买卖点_指标模式": "配置",
+  "买卖点_指标匹配_MACD": true,
+  "买卖点_指标匹配_KDJ": true,
+  "买卖点_指标匹配_RSI": true,
+  "买卖点_背离率": "Infinity",
+  "买卖点_T2_回调阈值": 1.0,
+  "买卖点_T2S_最大层级": 3,
+  "买卖点_峰值条件": false,
+  "买卖点_计算方式": "峰",
+  "买卖点_计算线段BSP1": true,
+  "买卖点_处理BSP2": true,
+  "买卖点_计算线段BSP3": true,
+  "买卖点_依赖T1": true,
+  "买卖点_中枢来源": "合",
+  "买卖点_调试输出": false,
+  "线段内部背驰_MACD": true,
+  "线段内部背驰_斜率": true,
+  "线段内部背驰_测度": true,
+  "线段内部背驰_模式": "相对",
+  "加载文件路径": ""
+}
+```
+
+</details>
+
+> **请修改上述 JSON 为您实际使用的配置值**，或直接粘贴通过 `config.to_json()` 输出的 JSON。
+
+## 上下文
+
+- [ ] 此 Bug 在 `chan.py` (Python 参考实现) 中也存在吗？
+  - Python 版行为：
+- [ ] 此 Bug 是否与特定数据文件相关？
+  - 数据文件名/时间范围：
+
+## 日志 / Panic 输出
+
+<details>
+<summary>展开查看详细输出</summary>
+
+```
+在此粘贴日志或 panic 输出
+```
+
+</details>
+
+## 补充信息
+
+任何其他有助于理解此 Bug 的上下文、截图或补充说明。
@@ -0,0 +1,36 @@
+---
+name: 自定义问题
+about: 其他问题（问题咨询、文档改进、重构建议等）
+title: "[Question] "
+labels: question
+assignees: []
+---
+
+## 问题概述
+
+请描述您的需求。
+
+## 问题类型
+
+- [ ] 问题咨询 — 对 API 或算法的使用存在疑问
+- [ ] 文档 — 文档错误、缺失或改进建议
+- [ ] 重构 — 代码结构或设计调整建议
+- [ ] 兼容性 — Python 绑定层与 `chan.py` 的行为差异
+- [ ] 性能 — 运行效率或内存占用问题
+- [ ] 其他
+
+## 涉及范围
+
+> 可选择一项或多项。
+
+| 层次 | 模块 |
+|------|------|
+| 核心层 | `types` / `kline` / `indicators` / `algorithm` / `structure` / `business` / `config` |
+| 绑定层 | `chanlun-py` (`src/business_py.rs` / `src/config_py.rs` / `src/structure_py.rs`) |
+| 测试 | `chanlun/src/*/tests` / `chanlun-py/tests/test_all.py` |
+| 文档 | `chanlun/README.md` / `CLAUDE.md` / 其他 |
+| 其他 | |
+
+## 补充信息
+
+任何有助于更好理解或解决此问题的信息。
@@ -0,0 +1,62 @@
+---
+name: 功能请求
+about: 提出一个新的功能或增强建议
+title: "[Feature] "
+labels: enhancement
+assignees: []
+---
+
+## 动机
+
+请描述这个功能要解决什么问题，或者满足什么使用场景。
+
+## 提案
+
+请描述您期望的功能或 API。
+
+**Rust 核心层:**
+
+```rust
+// 期望的 API 或行为
+```
+
+**Python 绑定层 (如适用):**
+
+```python
+# 期望的 API 或行为
+```
+
+## 替代方案
+
+是否有其他替代方案或现有机制可以满足需求？如果有，请描述。
+
+## 与 chan.py 的关系
+
+- [ ] `chan.py` (Python 参考实现) 中已有此功能
+  - 相关代码位置: `chan.py` 行号或方法名
+- [ ] 这是绑定层 (`chanlun-py`) 的功能需求
+- [ ] 这是核心层 (`chanlun`) 的算法需求
+- [ ] 这是全新的功能提案
+
+## 影响范围
+
+> 请勾选可能受影响的模块。
+
+- [ ] 类型定义 (`types/`)
+- [ ] K线层 (`kline/`)
+- [ ] 技术指标 (`indicators/`)
+- [ ] 笔划分 (`algorithm/bi`)
+- [ ] 线段划分 (`algorithm/segment`)
+- [ ] 中枢识别 (`algorithm/hub`)
+- [ ] 背驰检测 (`algorithm/divergence`)
+- [ ] 结构体 (`structure/`)
+- [ ] 观察者 (`business/observer`)
+- [ ] 买卖点 (`business/bsp`)
+- [ ] K线合成器 (`business/synthesizer`)
+- [ ] 立体分析器 (`business/multi_frame`)
+- [ ] 配置 (`config`)
+- [ ] Python 绑定 (`chanlun-py`)
+
+## 补充信息
+
+任何参考链接、图表、伪代码或其他有助于说明该功能的内容。
@@ -0,0 +1,70 @@
+---
+name: Pull Request
+about: 提交代码变更
+title: ""
+labels: []
+assignees: []
+---
+
+## 描述
+
+请简洁清晰地描述这个 PR 做了什么。
+
+## 变更类型
+
+- [ ] Bug 修复
+- [ ] 新功能
+- [ ] 重构 / 代码清理
+- [ ] 文档更新
+- [ ] 测试
+- [ ] 其他
+
+## 变更范围
+
+> 勾选涉及的文件或模块。
+
+**核心层 (`chanlun/`)：**
+
+- [ ] `types/` — 基础类型
+- [ ] `kline/` — K线层
+- [ ] `indicators/` — 技术指标
+- [ ] `algorithm/bi` — 笔划分
+- [ ] `algorithm/segment` — 线段划分
+- [ ] `algorithm/hub` — 中枢识别
+- [ ] `algorithm/divergence` — 背驰检测
+- [ ] `structure/` — 结构体
+- [ ] `business/observer` — 观察者
+- [ ] `business/bsp` — 买卖点
+- [ ] `business/synthesizer` — K线合成器
+- [ ] `business/multi_frame` — 立体分析器
+- [ ] `config` — 配置
+
+**绑定层 (`chanlun-py/`)：**
+
+- [ ] `src/lib.rs` — 模块注册
+- [ ] `src/business_py.rs` — 业务绑定
+- [ ] `src/config_py.rs` — 配置绑定
+- [ ] `src/structure_py.rs` — 结构体绑定
+
+**其他：**
+
+- [ ] 测试 (`chanlun/src/*/tests` 或 `chanlun-py/tests/`)
+- [ ] 文档 (`README.md` / `CLAUDE.md` / `.github/`)
+
+## 测试
+
+- [ ] 核心层测试通过 (`cargo test`)
+- [ ] 绑定层测试通过 (`python3 -m pytest chanlun-py/tests/test_all.py -v`)
+- [ ] `cargo clippy` 零警告
+- [ ] 与 `chan.py` 输出一致 (双端对比)
+- [ ] 新增了相关测试
+- [ ] 无新增测试（请说明原因）：
+
+## 破坏性变更
+
+- [ ] 是（请在下文描述迁移步骤）
+- [ ] 否
+
+## 补充信息
+
+任何有助于审查者理解此 PR 的截图、日志或对比数据。
@@ -0,0 +1,94 @@
+
+# 贡献者公约
+
+## 我们的承诺
+
+我们承诺使我们的社区对所有人保持友好、安全且公平。
+
+我们承诺营造一个尊重并促进每位个体尊严、权利与贡献的环境，无论其种族、民族、种姓、肤色、年龄、体貌特征、神经多样性、残疾状况、生理性别或社会性别、性别认同或表达、性取向、语言、哲学或宗教信仰、国籍或社会出身、社会经济地位、教育程度或其他身份属性。所有真诚参与并遵守本公约者，均享有同等的参与权利。
+
+
+## 受鼓励的行为
+
+虽然各自的社会规范可能有差异，但我们都努力达到这个社区对积极行为的期待。我们也了解，因为文化、背景或母语的不同，别人对我们的言行的解读可能不同于我们的初衷。
+
+考虑到以上这些，我们承诺以审慎的态度彼此相待，并以践行以下共同价值为行为准则：
+
+1. 尊重我们**社区的宗旨**、各项活动及集会方式 
+2. 以**善意与诚实**的态度与他人互动
+3. 尊重**不同的观点与经历**  
+4. 对自己的言行及贡献**负责**  
+5. 以得体的方式给予并接受**建设性意见** 
+6. 承诺在造成伤害时进行**弥补** 
+7. 采取其他有益于**社区福祉**的行为
+
+
+## 受限制的行为
+
+我们同意在社区内限制以下行为。出现这些行为、威胁实施这些行为、或宣传这些行为，均视为违反本行为准则。
+
+1. **骚扰**：在明确表达界限后仍侵犯这些界限，或在被清楚要求停止后，仍进行不必要的个人关注。
+2. **人身攻击**：针对社区成员或群体发表侮辱、贬低或带有蔑视性的言论。
+3. **刻板印象或歧视**：基于无法改变的身份或特征，来评判他人的性格或行为。
+4. **性化**：做出在社区场景或宗旨下普遍认为不恰当的亲密举动。
+5. **侵犯保密性**：未经允许分享或利用他人的个人或隐私信息。
+6. **危害行为**：对任何人或群体实施、煽动或威胁施加暴力及其他伤害。
+7. 其他威胁**社区福祉**的行为。
+
+
+### 其他限制行为
+
+1. **虚假身份**：出于任何原因冒充他人，或假扮他人以规避监管措施。
+2. **未正确标明来源**：未正确标明所贡献内容的来源。
+3. **宣传材料**：以不符合社区规范的方式分享营销或其他商业内容。
+4. **不当传播**：未能以负责任的方式呈现包含、链接或描述任何其他受限制行为的内容。
+
+
+## 通报问题
+
+即使社区成员之间尽其所能地合作，也仍然可能发生矛盾。并不是所有冲突都涉及违反行为准则，本准则旨在强化受鼓励的行为与规范，它们有助于预防冲突并将伤害降到最低。
+
+当事件发生时，及时报告非常重要。要报告可能的违规行为，**youwukuncheng@163.com**。
+
+社区管理员会严肃对待违规报告，并尽力及时回应。将对所有违反行为准则的报告展开调查，方式包括查阅消息、日志及录音，或访谈证人及其他相关参与人。社区管理员在优先保障安全与保密性的前提下，会尽可能保持调查与执行过程的透明度。为践行这些价值观，执行措施会在涉事各方的私下环境中进行，但如经各方同意，将事件通报全体社区也可以作为解决方案的一部分。
+
+
+## 处理与弥补伤害
+
+**[注意：下文所列的处理办法与补救措施，是基于行为准则执行过程中的最佳做法而提出的建议。如果你们的社区已经有既定的执行流程，请确保修改本段内容，以描述你们自己的政策。]**
+
+若社区管理员经调查确认存在违反此行为准则的行为，将参照以下"分级处理"机制，根据事件对相关人员及社区整体造成的影响程度，确定最适宜的伤害弥补方案。根据违规严重程度，可跳过较低级别的处理措施。
+
+1) 警告  
+   1) **事件**：单次或连续违规行为  
+   2) **后果**：社区管理员将发出书面私信警告  
+   3) **弥补**：弥补的方式如书面私下致歉、坦承自己的责任，或主动确认清楚今后该如何做才符合期待。
+2) 暂时限制活动
+   1) **事件**：重复造成先前已被警告的违规，或首次发生略为严重的违规行为。
+   2) **后果**：发出私下的书面警告，并设定一个有时间限制的冷静期，旨在强调事态的严重性，并让相关社区成员有时间消化与处理该事件。冷静期可能是限制在特定的交流渠道，或限制与特定社区成员的互动。
+   3) **弥补**：修复的方式可能包括道歉、利用冷静期反思自身行为及其影响，以及充分意识到在冷静期结束后如何重新进入社区空间。
+3) 暂时停权
+   1) **事件**：出现社区管理员已多次警告后仍然重复违规的模式，或一次严重违规行为。
+   2) **后果**：发出私下的书面警告，并附上恢复权限所需满足的条件。通常，临时停权旨在给予被停权者时间，反思其行为以及考虑可能的改正措施。
+   3) **弥补**：弥补的条件包括尊重停权的意旨、达成恢复权限的指定条件，以及充分认识到在停权解除后如何重新融入社区。
+4) 永久封禁
+   1) **事件**：多次违反行为准则，且其他分级处理措施均未能解决问题，或发生严重到社区管理员认定无法在该成员继续存在的情况下保障社区安全的违规行为。
+   2) **后果**：撤销其对所有社区空间、工具及交流渠道的访问权限。一般而言，永久封禁应极少使用，必须有充分且有力的理由，且仅在其他弥补手段未能改变其行为时才作为最后手段实施。
+   3) **弥补**：此类严重情形下，不存在可行的弥补途径。
+
+本分级处理措施旨在作为指导方针，并不限制社区管理者在符合社区最大利益的前提下，运用其自主裁量权与判断力。
+
+
+## 施行范围
+
+本行为准则适用于社区所有空间，同时也适用于个人在公共场合或其他场合正式代表社区的情况。代表社区的行为包括但不限于：使用官方电子邮件地址；通过官方社交媒体账号发布内容；作为指定代表出席线上或线下活动。
+
+
+## 贡献归属
+
+本行为准则改编自 贡献者公约 3.0 版，该公约永久可在此查阅：[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/)。
+
+贡献者公约 由 Organization for Ethical Source 负责维护，并以 CC BY-SA 4.0 许可协议发布。查看该许可协议请访问：[https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)。
+
+关于 贡献者公约 的常见问题解答，请参阅：[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)。各语言版本译文请见：[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations)。更多执行与社区指南资源请见：[https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources)。本分级措施的灵感来源于 [Mozilla 行为准则团队](https://github.com/mozilla/inclusion) 的工作。
+
@@ -0,0 +1,267 @@
+# 贡献指南
+
+感谢你对 `chanlun` 项目的关注！
+
+本项目将 Python 版缠论技术分析库 (`chan.py`) 完整移植为 Rust，同时通过 PyO3 绑定层保持 Python API 兼容。以下指南旨在帮助平滑贡献流程。
+
+---
+
+## 目录
+
+- [角色与分工](#角色与分工)
+- [开发环境](#开发环境)
+- [项目结构](#项目结构)
+- [开发流程](#开发流程)
+- [代码规范](#代码规范)
+- [测试指南](#测试指南)
+- [提交信息](#提交信息)
+- [双端对齐](#双端对齐)
+
+---
+
+## 角色与分工
+
+| 角色 | 范围 | 联系 |
+|------|------|------|
+| 维护者 | 架构决策、代码审查、发布 | @YuWuKunCheng |
+| 贡献者 | 提交 PR、报告 Bug、改进文档 | 任何人 |
+
+---
+
+## 开发环境
+
+### 必需工具
+
+| 工具 | 最低版本 | 用途 |
+|------|---------|------|
+| Rust | 1.85+ | 核心层编译 |
+| Python | 3.10+ | 绑定层测试、对比验证 |
+| maturin | 1.x | PyO3 绑定开发与安装 |
+
+### 初始化
+
+```bash
+# 克隆仓库
+git clone https://github.com/YuYuKunKun/chanlun.rs.git
+cd chanlun.rs
+
+# 核心层
+cd chanlun
+cargo build
+cargo test
+
+# 绑定层
+cd ../chanlun-py
+maturin develop
+python3 -m pytest tests/test_all.py -v
+
+# 确保 clippy 零警告
+cd ../chanlun
+cargo clippy
+```
+
+---
+
+## 项目结构
+
+```
+chanlun.rs/
+├── chan.py                          # Python 参考实现 (~4200 行)
+├── chanlun/                         # Rust 核心层
+│   ├── Cargo.toml
+│   └── src/
+│       ├── lib.rs                   # 模块注册
+│       ├── config.rs                # 缠论配置 (62 字段, serde)
+│       ├── types/                   # 基础类型
+│       ├── kline/                   # K线层
+│       ├── indicators/              # 技术指标
+│       ├── algorithm/               # 核心算法 (笔/线段/中枢/背驰)
+│       ├── structure/               # 结构体 (虚线/分型/特征)
+│       ├── business/                # 业务层 (观察者/合成器/立体分析)
+│       └── utils/                   # 工具
+├── chanlun-py/                      # PyO3 Python 绑定
+│   ├── Cargo.toml
+│   ├── src/
+│   │   ├── lib.rs                   # 模块注册与导出
+│   │   ├── business_py.rs           # 业务层 Python 封装
+│   │   ├── config_py.rs             # 配置 Python 封装
+│   │   └── structure_py.rs          # 结构体 Python 封装
+│   ├── chanlun/                     # Python 存根模块
+│   │   └── __init__.py
+│   └── tests/
+│       └── test_all.py              # 完整测试套件
+├── CLAUDE.md                        # AI 辅助开发指令
+├── .github/                         # GitHub 模板
+│   ├── pull_request_template.md
+│   └── ISSUE_TEMPLATE/
+│       ├── bug_report.md
+│       ├── feature_request.md
+│       └── custom.md
+├── README.md
+├── SECURITY.md
+└── CODE_OF_CONDUCT.md
+```
+
+---
+
+## 开发流程
+
+### 从 Issue 开始
+
+1. 查找或创建相关 Issue
+2. 在 Issue 中讨论方案，达成共识后再开始编码
+3. 避免在没有 Issue 的情况下提交大型 PR
+
+### 分支策略
+
+```bash
+# 从 develop 分支创建功能分支
+git checkout develop
+git pull origin develop
+git checkout -b feature/your-feature-name
+
+# 或从 develop 分支创建修复分支
+git checkout -b fix/your-bug-fix
+```
+
+### 提交 PR
+
+1. 确保所有测试通过
+2. 确保 `cargo clippy` 零警告
+3. 推送到你的分支并发起 PR 到 `develop`
+4. 填写 PR 模板中的所有内容
+5. 等待审查并响应反馈
+
+---
+
+## 代码规范
+
+### 中文标识符
+
+所有类型名、方法名、字段名必须使用中文，与 `chan.py` 保持 1:1 对应：
+
+```rust
+// ✓ 正确
+pub struct 缠论K线 { pub 高: SyncF64, pub 低: SyncF64 }
+pub fn 方向(&self) -> 相对方向 { ... }
+
+// ✗ 错误 — 不允许英文
+pub struct ChanKline { pub high: f64 }
+```
+
+### 许可证头部
+
+每个 `.rs` 文件必须以 MIT 许可证头部开始：
+
+```rust
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026 YuYuKunKun
+ * ...
+ */
+```
+
+### 代码风格
+
+- 使用 `cargo fmt` 自动格式化
+- 遵循 `cargo clippy` 建议（零警告）
+- 仅写必要注释 — 解释"为什么"而非"做什么"
+- 不对仅使用一次的代码做抽象
+- 不添加方案之外的特性和错误处理
+
+### Rust 相关约定
+
+- `#![allow(non_snake_case)]` 和 `#![allow(non_camel_case_types)]` 已在 `lib.rs` 中声明
+- 内部可变性优先用 `AtomicI64`/`AtomicBool`/`SyncF64`，复杂字段用 `RwLock`
+- `Arc<分型>` 通过 `Arc::as_ptr` 比较身份（而非值比较）
+- 全局缓存使用 `LazyLock<Mutex<>>`，不使用 `thread_local!`
+- 读写锁作用域化，防止死锁
+
+---
+
+## 测试指南
+
+### 核心层测试
+
+```bash
+cd chanlun
+cargo test             # 运行所有测试
+cargo test -- <name>   # 运行匹配名称的测试
+```
+
+测试应覆盖：
+- 类型构造/字段读写/Clone 后指针一致性
+- 算法函数的边界情况（空序列、单元素、极端价格）
+- 流式增量结果与静态重新分析的一致性
+- `Send + Sync` 编译期断言
+- 跨线程读写不 panic
+
+### 绑定层测试
+
+```bash
+cd chanlun-py
+maturin develop
+python3 -m pytest tests/test_all.py -v
+```
+
+测试应覆盖：
+- Python API 与 `chan.py` 的接口兼容性
+- 跨线程 `is` 身份一致性
+- 双端（Rust 绑定 vs `chan.py`）关键算法输出对比
+
+### 双端对比
+
+当我们修改算法层代码时，必须验证 Rust 输出与 Python 版一致：
+
+```python
+# 典型双端对比模式
+from chanlun import 观察者 as 观察者Rust
+from chanlun.chan import 观察者 as 观察者Py
+
+# 加载同样的数据
+obs_rust = 观察者Rust("btcusd", 300, config)
+obs_py = 观察者Py("btcusd", 300, config)
+
+# 对比结果
+assert len(obs_rust.笔序列) == len(obs_py.笔序列)
+assert len(obs_rust.线段序列) == len(obs_py.线段序列)
+```
+
+---
+
+## 提交信息
+
+使用简洁的中文，格式为：
+
+```
+<类型>: <简要描述>
+
+<详细说明（可选）>
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
+```
+
+类型示例：
+- `fix:` — Bug 修复
+- `feat:` — 新功能
+- `refactor:` — 重构（行为不变）
+- `test:` — 添加或修改测试
+- `docs:` — 文档更新
+- `chore:` — 构建/工具
+
+所有提交必须以 `Co-Authored-By:` 行结尾，这是本项目对 AI 辅助开发的惯例。
+
+---
+
+## 双端对齐
+
+本项目最核心的质量要求是 Rust 实现与 `chan.py` 行为完全一致。对齐时遵循：
+
+1. **以 `chan.py` 为准** — Python 实现是 golden source
+2. **增量对齐** — 优先修复数量差异（笔数、线段数），再深入字段级对齐
+3. **算法差异分类**：
+   - 核心公式错误：如 MACD 面积计算 `阳+阴` vs `阳+|阴|`
+   - 边界条件遗漏：如 `计算MACD柱子分段` 末尾段未追加
+   - 指针身份 vs 值索引：`position(|k| Arc::as_ptr(k) == ...)` vs `position(|k| k.序号 == ...)`
+4. **使用测试驱动** — 先写双端对比测试，确认差异存在，再改 Rust 代码对齐
@@ -0,0 +1,60 @@
+# 安全策略
+
+## 适用范围
+
+本安全策略适用于 `chanlun` Rust 核心库、`chanlun-py` Python 绑定层，以及本仓库中的相关工具和脚本。
+
+## 免责声明
+
+本项目是一个**技术分析库**，用于价格走势的结构化分析。它不存储用户资金、不处理身份认证、不直接发起交易，但反馈任何潜在安全漏洞（如代码层面的崩溃、死锁、不安全内存操作等）仍非常重要。
+
+## 支持的版本
+
+| 版本 | 支持状态 |
+|------|---------|
+| `26.x` | 积极支持 |
+| `< 26.0` | 不再支持 |
+
+## 报告漏洞
+
+如果您发现了安全漏洞，请**不要**通过公开的 Issue 报告。请通过以下方式私密报告：
+
+- **邮箱**: youwukuncheng@163.com
+- **主题**: `[SECURITY] — <简要描述>`
+
+请在报告中包含：
+
+1. **漏洞描述** — 清晰描述漏洞的性质
+2. **复现步骤** — 最小可复现的代码片段或操作序列
+3. **受影响版本** — 您正在使用的 `chanlun` 版本号
+4. **潜在影响** — 可能产生的后果（崩溃、数据泄露、死锁等）
+5. **建议修复** — 如果您有修复建议
+
+## 处理流程
+
+收到报告后，我们承诺：
+
+1. **确认收到** — 3 个工作日内确认收到报告
+2. **初步评估** — 7 个工作日内完成漏洞严重性评估并通知报告者
+3. **修复时间线** — 根据严重程度：
+   - 严重（可导致崩溃/死锁/未定义行为）: 14 天内发布修复
+   - 中等: 30 天内发布修复
+   - 低风险: 在下一个常规版本中包含修复
+4. **公开披露** — 修复发布后，在 Release Notes 中致谢报告者（需经同意）
+
+## 关注领域
+
+以下类型的漏洞尤其值得关注：
+
+- `unsafe` 代码块中的内存安全问题
+- `RwLock` 死锁（读锁中获取写锁）
+- `LazyLock<Mutex<>>` 全局缓存的锁竞争
+- `panic!` 导致的未预期崩溃
+- `Arc` 循环引用造成的内存泄漏
+- 大端字节序列化 (`to_bytes`/`from_bytes`) 的缓冲区越界
+- PyO3 FFI 边界的类型转换安全
+- `AtomicI64` / `SyncF64` 的 `Ordering::Relaxed` 使用是否合理
+
+## 偏好语言
+
+请使用简体中文或英文撰写报告。