manmankan 0.3.0__tar.gz

manmankan-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: 🐛 Bug 上报
+about: 报告慢慢看的 bug · 中文优先
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## 现象
+
+<!-- 你看到了什么？最好贴 terminal 完整输出（敏感信息脱敏）-->
+
+## 复现步骤
+
+1.
+2.
+3.
+
+## 期望行为
+
+<!-- 你认为应该是什么样？ -->
+
+## 环境
+
+- 操作系统（macOS / Linux / Windows）：
+- Python 版本（`python --version`）：
+- manmankan 版本（`kan --version`）：
+- 终端宽度（列数 · 影响表格渲染）：
+- 终端类型（iTerm / Terminal.app / Windows Terminal / VS Code 等）：
+
+## 数据相关
+
+- 你跑的命令：
+- 自选股池大小（`kan list | wc -l`）：约 N 只
+- 数据是今天的吗（看 `kan scan` 标题"X 更新"）？
+
+## 其他线索
+
+<!-- 截图 / 异常 traceback / 你的推测 -->

manmankan-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: ✨ 功能建议
+about: 建议新功能或改进
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## 你想解决什么问题？
+
+<!-- 不要直接说"加 X 功能" · 先描述使用场景和痛点 -->
+
+## 你的建议
+
+<!-- 想要什么样的解决方案？怎么个调用方式？ -->
+
+## 替代方案
+
+<!-- 有其他可能的实现方式吗？为什么这个更好？ -->
+
+## 合规自检（金融工具必须）
+
+慢慢看的设计哲学：**位置感入口 ≠ 决策出口**。新功能必须满足：
+
+- [ ] 不涉及「建议买卖」「推荐持仓」「目标价」等决策性输出
+- [ ] 不涉及预测涨跌 / 选股推荐 / AI 选股
+- [ ] 仅展示客观数据 + 让用户自行判断
+- [ ] 措辞严守「位置 / 区间 / 触及 / 共振」等中性词
+
+如果建议本身违反上述任一条 · 请理解我们不会接受（参见 README §法律免责）。

manmankan-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## 概述
+
+<!-- 1-2 句话说清楚改了什么 / 为什么 -->
+
+## 类型
+
+- [ ] 🐛 bug 修复
+- [ ] ✨ 新功能
+- [ ] ♻️ 重构（不改行为）
+- [ ] 📝 文档
+- [ ] ✅ 测试
+- [ ] ⚠️ Breaking change（必填 Migration guide）
+
+## 验证
+
+- [ ] `uv run pytest` 全绿
+- [ ] `uv run ruff check kan/ tests/` 无新增 F/E/B/N 类真技术债
+- [ ] **实际跑过 CLI** 验证（不仅看代码 · 见 CONTRIBUTING.md）
+
+## 合规自检（金融工具必须）
+
+- [ ] 不涉及买卖建议 / 选股推荐
+- [ ] 输出严守「位置 / 区间 / 触及 / 共振」中性措辞
+- [ ] 风险提示完整保留（不可关闭）
+
+## 相关 issue
+
+Closes #
+
+## Migration（如 Breaking change）
+
+| v0.x 写法 | v0.y 写法 |
+|---|---|
+| | |

manmankan-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # trusted publisher OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: '3.12'
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

manmankan-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/**'
+      - 'fix/**'
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run tests
+        run: uv run pytest -q
+      - name: Lint
+        run: uv run ruff check kan/

manmankan-0.3.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual env
+.venv/
+venv/
+.uv/
+
+# Environment variables
+.env
+.env.local
+
+# Database / Data
+*.db
+*.sqlite
+data/
+*.parquet
+
+# Testing
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local / private (any user-private files we don't want to track)
+*.local
+*.private
+*.secret
+*.bak

manmankan-0.3.0/CHANGELOG.md

@@ -0,0 +1,157 @@
+# Changelog
+
+本项目所有重大变更记录在此文件中。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
+
+## [0.3.0] - 2026-05-08
+
+> v0.2 全功能体验 review 驱动 · 聚焦 80 列终端适配（P0 痛点）+ 自选股名称搜索 + 竞品学习。
+
+### Added
+
+- **`kan add` 支持名称搜索** · `kan add 茅台` 自动查找代码并添加
+  - 精确匹配 1 只 → 直接添加
+  - 多只匹配 → 展示候选前 10 只 + 提示用代码添加
+- **`kan remove` 支持名称 + 批量** · `kan remove 茅台 五粮液` 一次删多只
+- **`kan list` 显示总数** · 标题 "自选股列表 · 共 N 只"
+- **终端宽度自适应** · scan 表根据终端宽度自动选择周期子集
+  - 130+ 列：全部 10 周期 · 100 列：6 周期 · 90 列：5 周期 · 80 列：4 周期
+  - 共振列在任何宽度下始终可见（v0.2 80 列下被完全截断）
+  - 窄屏时底部提示 "显示 N/10 周期 · 加宽终端可见全部"
+- **trend --latest 宽度自适应** · 日期列数量根据终端宽度自动调整
+  - 80 列约 3 天 · 120 列约 7 天 · 列头和数值不再截断为 "…"
+- **版本体验 review 机制** · `docs/reviews/` 存档 + 流程模板（每版本迭代前 AI 自动执行）
+- 新增 15 项测试 · 93 → 108 项全绿（终端宽度 11 + 名称搜索 4）
+
+### Changed
+
+- **info 表移除空"状态"列** · 位置列 `[x%]` 颜色已传达触及信息 · 表格更紧凑
+- **trend 范围校验中文化** · `--down 1` 从 typer 英文 "Invalid value" 改为中文 "❌ 值必须在 2-30 之间"
+- **数据目录迁移到 XDG 规范** · `~/.kan/` → `~/.local/share/kan/`（`$XDG_DATA_HOME/kan/`）
+  - 首次运行自动从旧路径迁移 · 旧目录留 `_MIGRATED.txt` 标记
+  - 新增 `kan/paths.py` 集中管理所有路径
+- **渲染逻辑拆分到 `kan/render.py`** · cli.py 803 → 752 行
+  - 周期选择 / 百分比格式化 / 日期列数计算独立为 render 模块
+
+### Fixed
+
+- v0.2 P0-1: scan 表 80 列截断 · 共振列不可见 → 自适应周期选择
+- v0.2 P0-2: trend --latest 列头截断 "现…" "连…" "累…" → 日期列数量自适应
+- v0.2 P3-1: 数据目录 `~/.kan/` 不符合 XDG 规范 → 迁移到 `~/.local/share/kan/`
+- v0.2 P3-2: cli.py 720 行未拆模块 → 渲染逻辑拆分到 render.py
+- v0.2 P3-3: scan 标题日期被截断 → 表格宽度自适应后标题自然完整
+
+### Migration Guide (v0.2 → v0.3)
+
+**数据目录自动迁移**：v0.3 起数据目录从 `~/.kan/` 迁移到 `~/.local/share/kan/`（XDG Base Directory 规范）。首次运行 `kan` 时自动迁移，旧目录留 `_MIGRATED.txt` 标记，确认数据无误后可手动删除旧 `~/.kan/`。
+
+**v0.2 移除项已稳定**：`--streak` / `kan scan -p N` 在 v0.2 已移除，v0.3 不再相关。详见 [v0.2 Migration Guide](#migration-guide-v01--v02)（如有）。
+
+## [0.2.0] - 2026-05-08
+
+> v0.1 早期使用反馈驱动迭代 · 聚焦 `kan trend` + `kan scan` 体验 + 排序逻辑重设计。
+
+### Changed (BREAKING)
+
+- **`kan --help` 走中文速记** · 与 `kan` / `kan help` 等价（v0.1 走 typer 默认英文混杂）
+  - 反 UNIX 习惯 · 但早期用户基数小 + 慢慢看是 CN-only CLI · 一致性 > 习惯
+  - 子命令 `--help` 不影响（如 `kan scan --help` 仍走 typer 默认）
+  - v0.1 用户脚本/别名/muscle memory 中 `kan --help | grep ...` 输出会变
+- **`kan scan -p / --period N` 选项已移除**（maintainer 拍板 · 站在用户角度判断 -p N 多余 · 与 `kan low/high N` 重叠）
+  - 想看单周期触及极值 → `kan low N` / `kan high N`
+  - 想看自选股全周期位置 → `kan scan`
+- **`kan scan` 排序重设计 · 共振优先 + PERIODS 字典序 tie-break**
+  - low：`-low_resonance` → 3 日 pct 升序 → 5 日 → ... → 180 日
+  - high：`-high_resonance` → 3 日 pct 降序 → 5 日 → ... → 180 日
+  - v0.1 行为：共振优先 → 任意周期 max/min（tie-break 不区分周期）
+- **`kan trend` 排序加二级 tie-break · 同天数按累计幅度 abs 降序**
+  - 5 天连跌 -15% 排在 5 天连跌 -3% 之前（同天数下幅度大的在前）
+  - v0.1 行为：仅按天数 abs 排序 · 同天数顺序随机
+- **`kan scan` 表格列宽修复（v0.1 真截断 bug）**
+  - 周期列 `min_width` 5 → 6（容纳 [100%] 6 chars · 之前显示 [100…）
+  - 现价/N日最低/N日最高/位置列加 `min_width=8`（容纳 4 位数股价 1371.05 + [100.0%] 8 chars）
+  - 涉及 scan / low / high / info 共 4 命令
+- `--streak` 选项移除（语义合并到 `--down N` / `--up N`）
+
+### Added
+
+- `kan trend --up N` 短写（与 `--down N` 对称）
+- `kan help` 文案明确标注「以上参数可任意组合」+ 给出组合示例
+- sys.argv 预处理逻辑（`kan.cli._normalize_streak_args`）· 让 `--down`/`--up` 不带值时注入默认 3 · 兼容 v0.1 调用方式
+- 测试覆盖大幅提升：v0.1 baseline 46 → v0.2 87+ 项（trend CLI 19 + scan 列宽 8 + 排序逻辑 11）
+  - `tests/test_trend_cli.py` · trend CLI 集成测试
+  - `tests/test_scan_cli.py` · scan/low/high/info 列宽回归测试
+  - `tests/test_sort_logic.py` · scan/trend 排序逻辑测试
+
+### Migration Guide
+
+| v0.1 写法 | v0.2 写法 |
+|---|---|
+| `kan trend` | `kan trend`（不变） |
+| `kan trend --down` | `kan trend --down`（不变） |
+| `kan trend --up` | `kan trend --up`（不变） |
+| `kan trend --down --streak 5` | `kan trend --down 5` |
+| `kan trend --up --streak 7` | `kan trend --up 7` |
+| `kan scan -p 60` | `kan low 60` 或 `kan high 60`（视场景） |
+| `kan scan --period 60` | 同上 |
+| `kan --help` | 输出从 typer 默认变中文速记（与 `kan` / `kan help` 等价） |
+
+### Internal
+
+- entry_point 从 `kan.cli:app` 改为 `kan.cli:cli_main`（包了一层 sys.argv 预处理）
+- `kan.scanner._period_pct_key` 新增 · 字典序排序辅助
+- `kan.cli._normalize_help_args` 新增 · root-level `--help` 重定向到 `help` 子命令
+- pytest: 46 → **93** 项（+47 · trend CLI 19 + scan 列宽 8 + 排序逻辑 11 + help 一致性 9）
+- 代码质量门禁：__version__ 同步 · F811 重命名 · F821 import · B904 chaining (3) · B905 strict zip · JSON utf-8 (6)
+
+[0.2.0]: https://github.com/piklen/manmankan/releases/tag/v0.2.0
+
+## [0.1.0] - 2026-05-05
+
+首次开源发布。
+
+### Added
+
+**位置扫描**
+- `kan scan` 全景扫描自选股 10 周期位置（3/5/7/10/15/30/60/90/120/180 日）
+- `kan scan --high` 高点模式
+- `kan scan -S` / `--signal` 仅显示有共振信号的股票
+- `kan scan --diff` 增量模式（与上次扫描对比）
+- `kan scan -p N` 单周期模式
+- `kan scan --exclude-st` 排除 ST/*ST 股票
+- 多周期共振信号自动高亮（×N 标记）
+
+**筛选模式**
+- `kan low N [N2 N3...]` 筛选 N 日低点（支持多周期）
+- `kan high N [N2 N3...]` 筛选 N 日高点
+- 触及阈值：≤5% 低点 / ≥95% 高点
+
+**连续涨跌看板**
+- `kan trend` 连续涨跌天数 + 累计涨跌幅
+- `kan trend --latest N` 展示近 N 天走势详情
+- `kan trend --down` / `--up` 筛选连续涨/跌
+- `kan trend --streak N` 自定义最少连续天数
+- `kan trend --candle` 阳线阴线口径
+- 涨跌停自动标记
+- 平盘穿透不断连续（行业惯例）
+
+**单只详情**
+- `kan info <代码>` 单只股票全周期位置 + 涨跌 + 共振统计
+
+**自选股管理**
+- `kan add` / `kan remove` / `kan list` / `kan import` / `kan clear`
+- 支持 6 位代码 / 带交易所前缀（sh600519 / sz000858）
+- A 股代码-名称本地缓存（7 天有效期）
+
+**数据层**
+- AKShare 直调获取前复权日 K 线
+- 本地 Parquet 缓存（`~/.kan/data/`）
+- 数据过期自动更新（无感）
+- `kan fetch [--force]` 手动刷新
+
+**合规**
+- 每次输出强制风险提示
+- 关键词黑名单
+- ST/*ST 涨跌停按 2026-07-06 政策日期切换（5% → 10%）
+- 板块差异化涨跌停限制（主板/科创创业/北交所/ST）
+
+[0.1.0]: https://github.com/piklen/manmankan/releases/tag/v0.1.0

manmankan-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# 贡献指南
+
+感谢你对慢慢看的兴趣！
+
+## 开发环境
+
+要求 Python 3.11+，推荐使用 [uv](https://docs.astral.sh/uv/)：
+
+```bash
+git clone https://github.com/piklen/manmankan.git
+cd manmankan
+uv sync
+```
+
+## 运行测试
+
+```bash
+uv run pytest
+uv run pytest --cov=kan          # 带覆盖率
+```
+
+## 代码风格
+
+- 使用 [ruff](https://docs.astral.sh/ruff/) 做 lint 和格式化：`uv run ruff check kan/`
+- 类型注解：所有公开函数应有类型注解
+- 命名：小写 + 下划线
+- Pydantic v2 用于数据模型
+
+## 合规红线（重要）
+
+本项目严格定位为**行情数据展示工具**，PR 不应引入任何形式的：
+
+- 买卖建议 / 评分评级 / 策略推荐
+- 涨跌预测 / 目标价
+- "建议关注 / 低估 / 见底 / 抄底"等暗示性词汇
+
+详见 [`docs/compliance.md`](docs/compliance.md)。
+
+## 提交流程
+
+1. Fork 本仓库
+2. 创建功能分支：`git checkout -b feat/your-feature`
+3. 提交改动：`git commit -m "feat: ..."`
+4. 推送到 fork：`git push origin feat/your-feature`
+5. 在 GitHub 上发起 Pull Request
+
+## Commit Message 规范
+
+```
+feat: 新功能
+fix: 修复 bug
+docs: 文档变更
+refactor: 重构（不改变功能）
+test: 测试相关
+chore: 构建/依赖等杂项
+```
+
+## 报告问题
+
+通过 [GitHub Issues](https://github.com/piklen/manmankan/issues) 报告 bug 或提出功能建议。
+
+请提供：
+- 复现步骤
+- 期望行为 vs 实际行为
+- Python 版本、操作系统
+- 相关日志或截图

manmankan-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 piklen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.