Nzssm1 / dsh-factor-investing

dsh-factor-investing · Multi-Factor Stock-Selection Quant Researcher

A DeepSeek Harness (DSH) community agent preset for institutional multi-factor stock selection (A-share oriented). It turns the broker/hedge-fund multi-factor pipeline into a discipline-aware researcher: a methodology knowledge base covering the full pipeline, plus a deterministic Rust core for reproducible factor statistics.

Community project — NOT an official DeepSeek preset and not endorsed by DeepSeek. See Relationship with DeepSeek.

1. Introduction

• preset id: dsh-factor-investing (the directory name; must match [a-z0-9][a-z0-9-]*)
• display name: 多因子选股量化研究员 (Multi-Factor Stock-Selection Quant Researcher)
• positioning: institutional research assistant for data → factors → testing → synthesis → portfolio → backtest → monitoring
• scenarios: factor mining & testing (IC/IR, Fama-MacBeth, incremental alpha), factor preprocessing & synthesis, Barra risk models, portfolio optimization, backtesting & live monitoring, quant code reproduction
• computation architecture: all core numeric work is delegated to a Rust CLI (scripts/factor-stats); the Agent writes only factor definitions and glue code

2. Why this preset

A generic chat model reduces "multi-factor" to "sum a few factors" and treats "good backtest = valid factor". Institutional multi-factor is an industrial pipeline, and its real edge over retail practice is statistical discipline:

• A factor's IC looking good ≠ useful — a new factor must pass an incremental-alpha test (regress its returns on known factors; the intercept α must be significant) to be genuinely new information;
• skipping size neutralization = an implicit small-cap bet; skipping industry neutralization = a value factor that always picks banks;
• multiple-testing correction (t>3 for novel factors), out-of-sample discipline, and cost/fill-rate assumptions decide whether a backtest is believable at all.

This preset writes that discipline into the system prompt via the persona, ships the methodology as a skill for on-demand loading, and pins the numeric algorithms in Rust so the same data and version produce the same numbers every time.

3. How it works

Three parts, all shipped with the repo:

1. persona (system prompt) — agent.cordis.yml injects a quant-researcher identity through @deepseek-ai/dsh-persona, embedding the pipeline, core discipline, and the hard rule that the Agent only writes factor definitions/glue code while all core computations go through the Rust CLI.
2. skill (on-demand methodology) — skills/factor-investing-pipeline/ is registered through @deepseek-ai/dsh-skill-filesystem's customSkillDirs; the model loads the relevant chapter with the skill tool.
3. Rust core engine — src/ + Cargo.toml implement winsorization (MAD/3σ/percentile), standardization, neutralization, IC/ICIR, two-stage Fama-MacBeth, Gram-Schmidt orthogonalization; scripts/factor-stats is the stable JSON-in/JSON-out CLI and the Agent's only computation entry point.

The toolset keeps the full standard coding capability; only the identity and knowledge change, so the tool catalog — and thus the request-prefix cache — stays stable.

4. Rust CLI usage

Every command reads one JSON object from stdin and writes JSON to stdout; null represents missing/NaN values in both directions. Errors go to stderr with a non-zero exit. See RUST_CORE.md for the full command list and JSON fields.

# First call auto-builds the release binary (later calls use 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

Commands: 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. Layout

dsh-factor-investing/
├── preset.yml                    # display metadata (name + description)
├── agent.cordis.yml              # Cordis composition: persona + tools + skill
├── skills/factor-investing-pipeline/
│   ├── SKILL.md                  # core framework + chapter/topic index
│   ├── chapters/ch00…ch09.md     # ten pipeline stages
│   ├── glossary.md / patterns.md / cheatsheet.md
├── src/stats.rs / src/main.rs    # Rust core algorithms and CLI
├── Cargo.toml / Cargo.lock       # locked Rust dependencies (reproducible builds)
├── RUST_CORE.md                  # Rust core interface and read-only policy
├── scripts/factor-stats          # Rust CLI wrapper (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. Installation

DSH discovers local presets under <dshHome>/.agent-presets/ (dshHome defaults to ~/.dsh; %USERPROFILE%\.dsh on Windows). The preset id is the directory name, so clone the repo as that directory.

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"

Restart DSH and pick 「多因子选股量化研究员」 for a new session. If your deployment configures custom preset roots, place the repo under that root instead (dsh-agent-presets roots).

Rust toolchain requirement: the first scripts/factor-stats call needs cargo (Rust stable). Install from https://rustup.rs.

7. Verification

1. persona active — the first system prompt of a new session carries the quant-researcher identity, pipeline/discipline, and the Rust-computation rule (including "Rust core is read-only").
2. skill registered — ask "list skills"; factor-investing-pipeline should appear, or ask it to "load chapter ch04 of factor-investing-pipeline".
3. Rust core works — run cargo test --locked (18 Rust tests pass) or echo '{"values":[1,2,3,4]}' | scripts/factor-stats mean → 2.5.
4. full tests — npm test runs cargo test --locked.

8. Important behaviors

• The preset does not change the tool catalog; it keeps standard's tools and only replaces the persona and registers the skill, so there is no bootstrap/full switching and the prefix cache stays stable.
• Computation discipline: all fixed computations are implemented in Rust, and the Agent's only computation entry point is scripts/factor-stats. The Agent must not re-implement these algorithms in Python/JS, and must not use pandas/numpy in place of Rust.
• Rust core is read-only for the Agent: src/, Cargo.toml, Cargo.lock, and scripts/factor-stats* are the fixed computation layer. The Agent must not create, modify, or delete them; if a new fixed computation is needed, the Agent must ask the user/maintainer to extend the Rust core instead of editing it.
• Rust boundary: the Rust core contains only generic mathematical/statistical primitives. Commission, slippage, fill-rate, T+1, stock universe, market rules, and portfolio parameters are user-specific and must stay in the Agent glue/config layer — never in Rust.
• Knowledge-base thresholds are rough heuristics (|IC|>0.03 keep, >0.05 usable, ICIR 0.2–0.5 common, 20–40bp cost), tied to stock-pool breadth, dispersion, and IC frequency — not universal targets; verify sample in/out-of-sample, cost, annualization, and multiple-testing before citing.
• Broker figures (e.g. 湘财 "59 → 22" factors, long-short Sharpe 2.92) are magnitude references from a single, unspecified-cost sample.
• The Rust CLI speaks JSON; null means missing/NaN. Glue code can convert between pandas/numpy DataFrames and this JSON interface.

9. Compatibility

• Built for DeepSeek Harness 0.1.0-rc.6: preset.yml (display metadata) + agent.cordis.yml (Cordis composition) + @deepseek-ai/dsh-persona (persona) + @deepseek-ai/dsh-skill-filesystem customSkillDirs (preset-local skill).
• This is a domain-expert preset, not the older (0.1.0-rc.5 / commit 47f9438) "two-stage tool catalog" pattern that hand-wrote a system-prompt/assemble listener. In the current version the system prompt comes from @deepseek-ai/dsh-persona, and "the catalog changes once" is satisfied by not changing it at all.
• Manual confirmations: ① repo name vs. preset id (rename the directory if they differ); ② the copyright holder in LICENSE (currently Nzssm1); ③ whether your deployment sets custom preset roots (default ~/.dsh/.agent-presets/); ④ on a non-rc.6 deployment, field names for customSkillDirs / dsh-persona may differ — check that version's dsh-agent-presets / dsh-persona README.

10. Relationship with DeepSeek

• This is a community project by GitHub user Nzssm1;
• it is not an official DeepSeek preset, is not hosted in an official DeepSeek repo, and the official repo does not accept external PRs;
• it is not endorsed or sponsored by DeepSeek;
• agent.cordis.yml is adapted from the standard preset shipped with DeepSeek Harness (Copyright (c) 2026 DeepSeek, MIT) and the MIT notice is retained (see NOTICE); the methodology knowledge base is adapted from the author's own research report, whose cited broker research and 《因子投资：方法与实践》 remain the property of their respective authors/publishers.

11. Tests

# Rust core full test suite
npm test

# Rust tests / release build separately
npm run test:rust
npm run build:rust

12. Publishing checklist

1. Create the repo Nzssm1/dsh-factor-investing on GitHub;
2. push to main (commands below);
3. add the topic dsh-plugin under Settings → Topics (this is how community directories and the topic page discover it);
4. confirm the test.yml workflow passes in Actions (including Rust tests);
5. (optional) publish a 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

Adding topics: repo page → right-side About gear → Topics → dsh-plugin (suggest also deepseek-harness, dsh, factor-investing, quant, rust).