docs: add feedback and community entrypoints

2026-07-27 20:27:45 +00:00 · 2026-06-09 16:50:04 +08:00
parent f01f95b905
commit 60cfc45933
24 changed files with 465 additions and 2 deletions
@@ -0,0 +1,20 @@
+name: 正式书建议
+description: 对正式书结构、附录、案例、章节顺序提出建议。
+title: "book-v2: "
+labels:
+  - book-v2
+body:
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: 建议内容
+      description: 请说明你希望正式书增加、删减或重写什么。
+    validations:
+      required: true
+  - type: textarea
+    id: reason
+    attributes:
+      label: 为什么这很重要
+      description: 请说明这个建议会帮助哪类读者。
+    validations:
+      required: true
@@ -0,0 +1,32 @@
+name: 概念没看懂
+description: 反馈某个概念、类比或推导不够清楚。
+title: "clarity: "
+labels:
+  - clarity
+body:
+  - type: input
+    id: chapter
+    attributes:
+      label: 章节
+    validations:
+      required: true
+  - type: input
+    id: section
+    attributes:
+      label: 小节
+    validations:
+      required: true
+  - type: textarea
+    id: confusing
+    attributes:
+      label: 没看懂的内容
+      description: 请粘贴原文，或描述你卡住的位置。
+    validations:
+      required: true
+  - type: textarea
+    id: expectation
+    attributes:
+      label: 希望补充什么
+      description: 例如：需要生活类比、需要公式解释、需要多一个例子。
+    validations:
+      required: true
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 课程与正式书信息
+    url: https://xquant.shop/courses
+    about: 查看 XQuant 课程、正式书和后续更新。
+  - name: 读者群
+    url: https://github.com/xingwudao/xquant-beginner/blob/main/book/feedback.md
+    about: 添加作者微信 xquanter 进入读者群。
@@ -0,0 +1,40 @@
+name: 实验结果不一致
+description: 反馈运行 spec 或 notebook 后，结果和书中不一致。
+title: "experiment: "
+labels:
+  - experiment
+body:
+  - type: input
+    id: chapter
+    attributes:
+      label: 章节
+    validations:
+      required: true
+  - type: input
+    id: spec
+    attributes:
+      label: Spec 或 notebook
+      description: 例如：q5-how-to-validate/specs/spec-02-annual-breakdown.md
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 书中结果
+      description: 请写出书中对应的数字、图表或结论。
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: 你的结果
+      description: 请写出你运行出的数字、图表差异或错误信息。
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: 运行环境
+      description: 操作系统、Python 版本、运行日期、使用的 AI 工具。
+    validations:
+      required: true
@@ -0,0 +1,34 @@
+name: 错别字或排版问题
+description: 报告错别字、标点、链接、图片或排版问题。
+title: "typo: "
+labels:
+  - typo
+body:
+  - type: input
+    id: chapter
+    attributes:
+      label: 章节
+      description: 例如：第 3 章：给 ETF 分钱
+    validations:
+      required: true
+  - type: input
+    id: section
+    attributes:
+      label: 小节
+      description: 例如：3.2 风险平价
+    validations:
+      required: true
+  - type: textarea
+    id: original
+    attributes:
+      label: 原文片段
+      description: 请粘贴需要修正的原文。
+    validations:
+      required: true
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: 建议修改
+      description: 请写出你建议改成什么。
+    validations:
+      required: true
@@ -0,0 +1,19 @@
+## 变更内容
+
+- 
+
+## 影响范围
+
+- 章节：
+- 是否影响图片：
+- 是否影响链接：
+
+## 验证
+
+- [ ] 已检查 Markdown 链接
+- [ ] 已运行 `npm run docs:build`
+- [ ] 未提交 `docs/`、`node_modules/`、`.vitepress/dist/`
+
+## 备注
+
+本书只用于教育和研究，不构成投资建议。
@@ -10,6 +10,8 @@ export default defineConfig({
  themeConfig: {
    nav: [
      { text: '阅读', link: '/book/preface' },
+      { text: '反馈', link: '/book/feedback' },
+      { text: '课程', link: 'https://xquant.shop/courses' },
      { text: '配套练习', link: 'https://github.com/xingwudao/xquant-learning' }
    ],
    sidebar: [
@@ -27,12 +29,13 @@ export default defineConfig({
          { text: '第 6 章：看清好看的回测', link: '/book/q6-avoid-overfitting' },
          { text: '第 7 章：真的下单', link: '/book/q7-execution' },
          { text: '第 8 章：让策略活着', link: '/book/q8-iteration' },
-          { text: '第 9 章：持续寻找盈利机会', link: '/book/q9-daily-work' }
+          { text: '第 9 章：持续寻找盈利机会', link: '/book/q9-daily-work' },
+          { text: '反馈与读者群', link: '/book/feedback' }
        ]
      }
    ],
    socialLinks: [
-      { icon: 'github', link: 'https://github.com/xingwudao/xquant-learning' }
+      { icon: 'github', link: 'https://github.com/xingwudao/xquant-beginner' }
    ],
    outline: {
      label: '本页目录',
@@ -0,0 +1,11 @@
+# Changelog
+
+本文件记录开源书稿的重要修订。小的错别字和格式修复可能合并记录。
+
+## 2026-06-09
+
+- 发布 `xquant-beginner` 开源书稿仓库
+- 上线 GitHub Pages 静态阅读版本
+- 建立 GitBook 同步所需的 `README.md`、`SUMMARY.md`、`.gitbook.yaml`
+- 将书稿内容与配套练习仓库 `xquant-learning` 分离
+- 明确双许可证：书稿内容为 `CC BY-NC-SA 4.0`，构建配置为 `MIT`
@@ -0,0 +1,65 @@
+# 参与反馈
+
+感谢你阅读《XQuant：人人都是量化交易员》开源版。
+
+这个仓库主要收集书稿反馈，帮助正式书继续修订。最有价值的反馈不是
+“这里不好”，而是能定位到具体章节、具体段落、具体问题。
+
+## 反馈入口
+
+请优先使用 GitHub Issue：
+
+`https://github.com/xingwudao/xquant-beginner/issues/new/choose`
+
+如果你只是想加入读者群，可以添加作者微信：
+
+`xquanter`
+
+请备注：
+
+`XQuant 读者`
+
+## 适合提交的反馈
+
+- 错别字、标点、排版问题
+- 某个概念没看懂
+- 某段叙述前后不一致
+- 书中实验结果和你运行出的结果不一致
+- 对正式书结构、案例、附录的建议
+
+## 不适合提交的内容
+
+- 个股、ETF、策略买卖建议
+- 让作者判断某个投资机会是否值得买
+- 和本书无关的工具安装问题
+- 没有上下文的截图或一句话评论
+
+## 提交 Issue 时请写清楚
+
+- 章节名称
+- 小节标题
+- 原文片段
+- 你遇到的问题
+- 你建议如何修改
+
+## Pull Request
+
+欢迎提交小范围 PR，尤其是错别字和链接修复。
+
+PR 请保持聚焦：
+
+- 一个 PR 只解决一类问题
+- 不要混合改多个章节的风格
+- 不要批量重写语气，除非先开 Issue 讨论
+- 不要提交 `docs/`、`node_modules/`、`.vitepress/dist/`
+
+## 主站与课程
+
+课程和后续正式书信息会放在主站：
+
+`https://xquant.shop/courses`
+
+## 风险提示
+
+本书只用于教育和研究，不构成投资建议。历史表现不代表未来收益，
+任何策略都可能亏损。
@@ -7,6 +7,16 @@ spec 与 notebook 不放在这里，统一维护在：

 `https://github.com/xingwudao/xquant-learning`

+在线阅读：
+
+`https://xingwudao.github.io/xquant-beginner/`
+
+课程与正式书信息：
+
+`https://xquant.shop/courses`
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
+
 ## 在线发布

 本仓库支持两种发布方式：
@@ -18,6 +28,18 @@ spec 与 notebook 不放在这里，统一维护在：

 直接从 `SUMMARY.md` 开始阅读，或打开 `book/` 目录下的章节文件。

+## 反馈与读者群
+
+如果你发现错别字、概念不清或实验结果不一致，请提交 Issue：
+
+`https://github.com/xingwudao/xquant-beginner/issues/new/choose`
+
+参与反馈前建议阅读：
+
+`CONTRIBUTING.md`
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
+
 ## 本地预览静态站点

 先安装 Node.js，然后运行：
@@ -50,6 +72,15 @@ npm run docs:preview
 阅读正文时，如果看到类似 `q1-how-to-profit/specs/` 的路径，
 请到 `xquant-learning` 仓库中查看对应文件。

+## 课程与正式书
+
+课程、正式书和后续更新会放在主站：
+
+`https://xquant.shop/courses`
+
+本仓库是开源书稿版本，用于公开阅读和收集反馈。正式书会在吸收
+开源反馈后整理为更稳定的版本。
+
 ## 许可证

 本仓库采用双许可证：
@@ -59,3 +90,8 @@ npm run docs:preview

 也就是说，你可以在署名、非商业、相同方式共享的前提下传播和改编
 书稿内容；构建相关代码和配置可按 MIT 许可证使用。
+
+## 风险提示
+
+本书只用于教育和研究，不构成投资建议。历史表现不代表未来收益，
+任何策略都可能亏损。
@@ -12,3 +12,4 @@
 * [第 7 章：真的下单](book/q7-execution.md)
 * [第 8 章：让策略活着](book/q8-iteration.md)
 * [第 9 章：持续寻找盈利机会](book/q9-daily-work.md)
+* [反馈与读者群](book/feedback.md)
@@ -0,0 +1,39 @@
+# 反馈与读者群
+
+这本开源书会持续吸收读者反馈，用于修订正式书。
+
+如果你读到错别字、概念不清、实验结果不一致，或者对正式书有建议，
+欢迎通过 GitHub Issue 提交：
+
+`https://github.com/xingwudao/xquant-beginner/issues/new/choose`
+
+## 如何提交有效反馈
+
+请尽量写清楚：
+
+- 章节名称
+- 小节标题
+- 原文片段
+- 你遇到的问题
+- 你建议如何修改
+
+## 读者群
+
+添加作者微信：
+
+`xquanter`
+
+请备注：
+
+`XQuant 读者`
+
+## 主站与课程
+
+课程和后续正式书信息会放在主站：
+
+`https://xquant.shop/courses`
+
+## 风险提示
+
+本书只用于教育和研究，不构成投资建议。历史表现不代表未来收益，
+任何策略都可能亏损。
@@ -286,3 +286,15 @@ AI 会自动完成 6 个步骤：装 uv、建虚拟环境、装 7 个依赖包
 ### 下一步

 **第 1 章**，我们会用一个真实的 ETF 带你**走完整个飞轮一圈**——从最简单的定投开始（做），看它能不能赚钱（看），尝试让它“聪明”一些（再做、再看），最后亲眼看到“回测时间段里收益率优美、换段时间就亏损”这种典型情况（疑）。 准备好了吗？翻到下一章，开始你的第一次飞轮转动。
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -174,3 +174,15 @@
 - 量化框架：https://github.com/xingwudao/open-xquant

 地图就到这里。下一节“开始动手之前”是一次性准备——把 AI 编程工具和 Python 环境装好，顺便用“装环境”这件事完整地写一份 spec。一次配完，第 1 章我们就直接跑实验。
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或链接问题，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -671,3 +671,15 @@ AI 帮你做了这些事：把数据按时间顺序在第 60% 的位置一刀切
 | 成本差 | 频繁操作累积成本，可能吃掉一半本金 | 明确规则约束，不频繁操作 |

 量化不能保证赚钱，但能让你在更公平的位置上竞争。
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -432,3 +432,15 @@ ETF 不是唯一的资产类型——它只是新手最该先碰的那个。投
 | **统计套利** | 两个相关的东西价格差异，赚差价 | 日内~几天 |

 价值投资和趋势交易的核心区别在于**时间尺度**——同一只标的，月线看到的是长期价值，日线看到的是短期趋势。同一个世界，不同的视角。不管哪种方式，**先构建投资宇宙、再做分析**这个原则都一样——投资宇宙是所有策略的起点。
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -418,3 +418,15 @@ AI 助手执行完毕后，你的 notebook 里应该出现了新的权重对比
 第二个问题正是本书口号“**做要规则、看要指标、还要怀疑你的指标**”中“疑”的入口——动量排名的累计 179.96% 看起来很漂亮，但你已经隐隐感到不对劲：换段时间还能不能这样？这种警觉，是后面五章要反复训练的主线动作。

 > 本章所有代码的可运行版本见 `notebooks/q3-how-much.ipynb`
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -444,3 +444,15 @@ AI 助手执行完毕后，你的 notebook 里应该出现了止盈规则的工
 ### 为什么“让利润奔跑，截断亏损”是格言而不是定理

 本章 4.3 你已经看到，10% / 20% 这种紧的止盈阈值都让累计收益下降了——多数情况下“落袋为安”输给了“让利润奔跑”；只有放到 30% 这种很少触发的阈值，才偶尔把波动压低、夏普反弹。但这并不意味着任何场景下都不该止盈。**这条格言适用的是“中长周期、跟趋势”的策略，比如本章用的风险平价 + 中频再平衡。** 如果你跑的是短线波段、做反转、或者高杠杆策略，止盈往往是必要的——不止盈就可能在一次回调里把所有浮盈吐光。换句话说：**格言是经验的提炼，不是定理；它把概率告诉你，但需要你结合策略类型 + 阈值去用。**
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -733,3 +733,15 @@ A 股一年大约 250-252 个交易日（节假日不开盘），美股 252 个
 正文说索提诺比 = 年化收益 / 下行波动率。但什么算“下行”？业界常用的定义是：**收益低于某个阈值（叫 MAR，Minimum Acceptable Return，最低可接受收益率）的那部分波动**。

 最常见的两种 MAR 选法：①**MAR = 0**——把“亏损”定义为“日收益率 < 0”，最简单；②**MAR = 无风险利率**（如美债 5%）——把“没跑赢国债”也算“下行”，更严格。本书计算时用的是 MAR = 0（更直观），但你看到不同来源的索提诺比数值有差异时，先确认它们用的是哪种 MAR——否则比的不是同一个东西。
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -576,3 +576,15 @@ AI 助手执行完毕后，你的 notebook 里应该出现了两组实验的完
 **你在第一章撞过那堵墙，第五章手里有了体检表，这一章把怀疑变成了肌肉记忆。下面一章，回测的世界要让位给真实成交的世界——你将带着这四把铲子，走进实盘。**

 > 本章所有代码的可运行版本见 `notebooks/q6-avoid-overfitting.ipynb`
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -579,3 +579,15 @@ Step 1：订单生成 → 权重只能买整数股 → 取整偏差 + 现金残
 **到这里，你完成了飞轮的“执行层”——这一章把“做 + 看”落到了真金白银的边界：“做”是把 35% 的权重翻成 8100 股的订单、把 NEXT_OPEN 当成更诚实的成交假设、再用 LiveBroker 把订单递给 Alpaca；“看”是用执行报告逐笔对账，看清那 1.62% 的平均滑点和 7.08% 的最贵一笔藏在哪里。本书口号“做要规则、看要指标、还要怀疑你的指标”——前两步在这一章贯穿到底，“疑”留到下一章在实盘环境里继续。**

 > 本章所有代码的可运行版本见 `notebooks/q7-execution.ipynb`
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -521,3 +521,15 @@ open-xquant 的 `Strategy` 支持在创建时填写 `hypothesis`（假设）和
 **记录（对应第 3 步 迭代记录表）。** 每次迭代都填迭代记录表。三个月后回头看，你会发现大部分假设都被推翻了——但你从每次推翻中学到的东西比确认更多。这些记录就是你的成长轨迹。

 **一句话：** 策略层面的方法论你已经有了；接下来三年里能不能跑通，取决于你“耐心 / 纪律 / 记录”这三条软纪律守得有多严。这是带得走的“心态地图”。
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -487,3 +487,15 @@ open-xquant 在 `agent/bootstrap/` 目录提供了一套量化研究专用的 ha
 - **神经网络**：能捕捉更复杂的非线性关系，但需要更多数据

 核心思路都一样：把因子当作特征，未来收益当作标签，让模型学出最优的组合方式。这是你未来进入实战后可以深入探索的方向——但本书的主线已经够你跑很久了，**先把第八章的迭代闭环跑顺，再考虑加机器学习**。
+
+---
+
+## 反馈与读者群
+
+如果你发现本章有错别字、概念不清或实验结果不一致，欢迎
+[提交 GitHub Issue](https://github.com/xingwudao/xquant-beginner/issues/new/choose)。
+
+课程、正式书和后续更新见
+[xquant.shop/courses](https://xquant.shop/courses)。
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
@@ -7,6 +7,12 @@ spec 与 notebook 不放在这里，统一维护在：

 `https://github.com/xingwudao/xquant-learning`

+课程与正式书信息：
+
+`https://xquant.shop/courses`
+
+添加作者微信 `xquanter` 进入读者群。请备注：`XQuant 读者`。
+
 ## 开始阅读

 - [前言](book/preface.md)
@@ -15,6 +21,12 @@ spec 与 notebook 不放在这里，统一维护在：

 完整目录见 [SUMMARY.md](SUMMARY.md)。

+## 反馈与读者群
+
+- [提交书稿反馈](book/feedback.md)
+- [参与贡献说明](CONTRIBUTING.md)
+- 添加作者微信 `xquanter` 进入读者群
+
 ## 在线发布

 本仓库支持两种发布方式：
@@ -51,9 +63,20 @@ npm run docs:preview

 `https://github.com/xingwudao/xquant-learning`

+## 课程与正式书
+
+课程、正式书和后续更新会放在主站：
+
+`https://xquant.shop/courses`
+
 ## 许可证

 本仓库采用双许可证：

 - 书稿正文与图片：`CC BY-NC-SA 4.0`
 - 构建脚本、配置文件和自动化工作流：`MIT`
+
+## 风险提示
+
+本书只用于教育和研究，不构成投资建议。历史表现不代表未来收益，
+任何策略都可能亏损。