Nzssm1/dsh-factor-investing

dsh-factor-investing · 多因子选股量化研究员

一个面向 A 股多因子选股模型构建 的 DeepSeek Harness（DSH）社区 Agent preset。它把券商金工/私募的机构级流水线做成一个"懂纪律"的研究员：内置从数据层到实盘监控的完整方法论知识库，并附带一个 Rust 编写的确定性核心计算引擎，用于保证因子分析结果的可复现性。

这是社区项目，不是 DeepSeek 官方 preset，不代表 DeepSeek 认可或背书。详见文末《与 DeepSeek 官方的关系声明》。

1. 项目简介

- preset id：dsh-factor-investing（即目录名，需符合 [a-z0-9][a-z0-9-]）
- 显示名称：多因子选股量化研究员
- 定位：多因子选股模型从数据 → 因子 → 检验 → 合成 → 组合 → 回测 → 监控的机构级研究助手
- 适用场景：因子挖掘与检验（IC/IR、Fama-MacBeth、增量 Alpha）、因子预处理与合成、Barra 风险模型、组合优化、回测与实盘监控、量化研究代码复现
- 计算架构：核心数值计算全部由 Rust CLI（scripts/factor-stats）完成；Agent 只写因子定义与胶水代码，不得自行实现核心统计算法

2. 为什么需要这个 preset

普通对话模型谈多因子，往往退化成"把几个因子加起来打分"，并默认"历史回测好看 = 因子有效"。而机构多因子是工业化流水线，其与散户最本质的差异在统计纪律：

- 单因子 IC 好看 ≠ 有用——新因子必须通过增量 Alpha 检验（对已知因子回归，截距 α 显著）才算真正的新信息；
- 不做市值中性化 = 隐性小盘策略；不做行业中性化 = 估值因子永远选银行股；
- 多重检验校正（新颖因子 t>3）、样本外纪律、成本与成交率假设，决定了回测结论是否可信。

本 preset 用 persona 把这些纪律写进系统提示词，把方法论细节做成 skill 按需加载，并用 Rust 固定核心算法实现，让模型的每一步都先按流程审问、再给结论，且同一份数据在同一版本下得到完全一致的数字。

3. 核心工作原理

preset 由三部分组成，全部随仓库分发：

1. persona（系统提示词）：agent.cordis.yml 通过 @deepseek-ai/dsh-persona 注入一个"多因子量化研究员"身份，内嵌完整流水线、核心纪律与"Agent 只写因子定义/胶水代码，核心计算调 Rust，Rust 核心只读"的硬约束。
2. skill（按需加载的方法论）：skills/factor-investing-pipeline/ 是知识库，通过 @deepseek-ai/dsh-skill-filesystem 的 customSkillDirs 随 preset 注册。需要具体做法（中性化、因子合成、Fama-MacBeth、增量 Alpha、Barra CNE6、拥挤度、多重检验等）时，模型调用 skill 工具加载对应章节。
3. Rust 核心计算引擎：src/ + Cargo.toml 实现去极值（MAD/3σ/百分位）、标准化、中性化、IC/ICIR、Fama-MacBeth 两阶段回归、Gram-Schmidt 正交化等纯计算；scripts/factor-stats 是稳定的 JSON-in/JSON-out CLI，也是 Agent 唯一的计算入口。

工具面沿用 DSH standard 的完整编码能力（shell、文件、检索、skills、目标、计划、子代理、工作流等），只替换身份与知识，不改工具目录，因此请求前缀缓存稳定。

4. Rust CLI 用法

所有命令从 stdin 读一个 JSON 对象，向 stdout 输出 JSON；null 同时表示输入/输出中的缺失值（NaN）。错误写入 stderr 并以非零码退出。完整命令清单与 JSON 字段见 RUST_CORE.md。

第一次使用会自动 cargo build --release（之后直接执行 target/release/factor-stats）
echo '{"values":[1,2,3,4,5]}' | scripts/factor-stats zscore
echo '{"values":[1,2,3,4,5,6,7,8,9,1000]}' | scripts/factor-stats winsorize-mad
echo '{"factor":[1,2,3,4,5,6,7,8],"exposures":[[1],[2],[3],[4],[5],[6],[7],[8]]}' | scripts/factor-stats neutralize
echo '{"factors":[[1,2,3,4],[1,2,3,4]],"returns":[[2,4,6,8],[1,2,3,4]]}' | scripts/factor-stats ic-series
echo '{"values":[0.05,0.06,0.04,0.05,0.07,0.03]}' | scripts/factor-stats icir
echo '{"exposures":[[[1],[2]],[[1],[2]]],"returns":[[0.5,0.9],[0.6,1.2]]}' | scripts/factor-stats fama-macbeth

支持命令：mean、std、median、mad、quantile、rank、corr、spearman、winsorize-mad、winsorize-sigma、winsorize-percentile、zscore、neutralize、ols、pearson-ic、spearman-rank-ic、ic-series、icir、ic-tstat、fama-macbeth、gram-schmidt。

5. 目录结构

dsh-factor-investing/
├── preset.yml                    # preset 显示元数据（name + description）
├── agent.cordis.yml              # Cordis 组合：persona + 工具 + skill 注册
├── skills/factor-investing-pipeline/
│   ├── SKILL.md                  # 核心框架 + 章节/主题索引
│   ├── chapters/ch00…ch09.md     # 十大环节详解
│   ├── glossary.md               # 术语表
│   ├── patterns.md               # 方法与模式（含 Trade-offs）
│   └── cheatsheet.md             # 阈值速查、决策规则、陷阱对照
├── src/stats.rs / src/main.rs    # Rust 核心算法与 CLI
├── Cargo.toml / Cargo.lock       # Rust 依赖锁定（可复现构建）
├── RUST_CORE.md                  # Rust 核心接口与只读策略
├── scripts/factor-stats          # Rust CLI 包装脚本（bash / cmd）
├── package.json                  # npm test（cargo test --locked）、build:rust
├── README.md / README.zh-CN.md
├── LICENSE                       # MIT
├── NOTICE                        # 改编来源声明
├── .gitignore
└── .github/workflows/test.yml    # CI：Rust 全量测试

6. 安装方法

DSH 的本地 preset 根目录为 /.agent-presets/（dshHome 默认 ~/.dsh，Windows 为 %USERPROFILE%\.dsh）。preset 的 id 即目录名，因此把仓库克隆为该目录即可。

Linux / macOS：

mkdir -p ~/.dsh/.agent-presets
git clone https://github.com/Nzssm1/dsh-factor-investing.git \
~/.dsh/.agent-presets/dsh-factor-investing

Windows（PowerShell）：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.dsh\.agent-presets"
git clone https://github.com/Nzssm1/dsh-factor-investing.git
"$env:USERPROFILE\.dsh\.agent-presets\dsh-factor-investing"

克隆后重启 DSH，在 preset 选择器中选择「多因子选股量化研究员」开始新会话。若部署配置了自定义 preset 根目录，请把仓库放到该根目录下（dsh-agent-presets 的 roots 配置）。

Rust 工具链要求：首次调用 scripts/factor-stats 需要 cargo（Rust stable）。安装见 。

7. 验证方法

1. persona 已生效：新会话的首条系统提示应包含"严谨的多因子选股量化研究员"与机构流水线/纪律，以及"Agent 只写因子定义与胶水代码、核心计算调 Rust、Rust 核心只读"。
2. skill 已注册：询问模型"有哪些技能"，应能看到 factor-investing-pipeline；或直接让它"加载 factor-investing-pipeline 的 ch04"。
3. Rust 核心可用：在项目目录执行 cargo test --locked，应看到 24 个 Rust 用例通过；或执行 echo '{"values":[1,2,3,4]}' | scripts/factor-stats mean 得到 2.5。
4. 全量测试：执行 npm test（即 cargo test --locked）全部通过。

8. 重要行为说明

- 本 preset 不改工具目录：它保留 standard 的全部工具，仅替换 persona 与注册 skill，因此没有"引导阶段/完整阶段"的切换，前缀缓存稳定。
- 计算纪律：固定计算全部由 Rust 核心负责，Agent 的计算入口只有 scripts/factor-stats；Agent 不得用 Python/JS 重新实现这些算法，也不得用 pandas/numpy 代替 Rust 计算。
- Rust 核心只读：src/、Cargo.toml、Cargo.lock、scripts/factor-stats 属于固定计算层，Agent 不得创建、修改或删除；缺少新计算能力时只能向用户/维护者提出需求。
- Rust 边界：Rust 核心只包含通用数学/统计原语；佣金、滑点、成交率、T+1、股票池、市场规则、组合参数等用户差异项不得进入 Rust，只能由 Agent 在胶水/配置层处理。
- 知识库中的 阈值是粗启发值（|IC|>0.03 保留、>0.05 基本可用、ICIR 0.2–0.5 常见、成本 20–40bp 等），与股票池宽度、市场离散度、IC 频率强相关，不可直接当作目标标准；引用前必须核验样本内/外、成本口径、年化口径与多重检验。
- 知识库中的券商实证数字（如湘财"59 筛 22"、多空 Sharpe 2.92）仅作量级参考，单一样本、口径未知。
- Rust CLI 输入输出使用 JSON；null 表示缺失值（NaN）。如需与 pandas/numpy 交互，可在胶水层完成 DataFrame → JSON → Rust → JSON → DataFrame 的转换。

9. 兼容性说明

- 基于 DeepSeek Harness 0.1.0-rc.6 的 preset 机制开发：preset.yml（显示元数据）+ agent.cordis.yml（Cordis 组合）+ @deepseek-ai/dsh-persona（persona）+ @deepseek-ai/dsh-skill-filesystem 的 customSkillDirs（随 preset 分发 skill）。
- 本项目是领域专家 preset，不采用旧版（0.1.0-rc.5 / commit 47f9438）中 system-prompt/assemble 手写监听 + 两阶段工具目录（bootstrap→完整）那套写法；当前版本中"系统提示词"由 @deepseek-ai/dsh-persona 提供，"工具目录只变一次"由"不动工具目录"天然满足。
- 需手动确认的点：① 仓库名与 preset id 是否一致（不一致则需改名目录）；② LICENSE 中的版权人（当前为 Nzssm1）；③ 部署是否配置了自定义 preset 根目录（默认 ~/.dsh/.agent-presets/）；④ 部署版本若非 rc.6，customSkillDirs / dsh-persona 字段名可能不同，需对照该版本的 dsh-agent-presets / dsh-persona README。

10. 与 DeepSeek 官方的关系声明

- 这是社区项目，作者是 GitHub 用户 Nzssm1；
- 不是 DeepSeek 官方 preset，未托管在 DeepSeek 官方仓库，DeepSeek 官方仓库也不接受外部 PR；
- 不代表 DeepSeek 认可或背书；
- agent.cordis.yml 改编自 DeepSeek Harness 随附的 standard preset（Copyright (c) 2026 DeepSeek，MIT），已按 MIT 要求保留声明（见 NOTICE）；方法论知识库改编自作者本人的调研报告，原文引用的券商研报与《因子投资：方法与实践》版权归原作者/出版社所有。

11. 测试

Rust 核心全量测试
npm test

Rust 测试 / release 构建
npm run test:rust
npm run build:rust

12. 发布到 GitHub 的 checklist

1. 在 GitHub 创建仓库 Nzssm1/dsh-factor-investing；
2. 推送到 main 分支（下方命令）；
3. 在仓库 Settings → Topics 添加 topic：dsh-plugin（这是被社区目录/主题页发现的关键）；
4. 确认 Actions 中的 test.yml 通过（含 Rust 测试）；
5. （可选）发布 release。

git init
git add .
git commit -m "feat: dsh-factor-investing preset with Rust core"
git branch -M main
git remote add origin https://github.com/Nzssm1/dsh-factor-investing.git
git push -u origin main

添加 topic：仓库页面 → 右侧 About 齿轮 → Topics 输入 dsh-plugin（同时建议加 deepseek-harness、dsh、factor-investing、quant、rust）。