量化研究流水线 ylouis8/kph

KPH — Knowledge Pipeline 独立开发副本（接入 DeepSeek Harness）

从 PIT 数据到独立回放，把量化研究变成可追溯、可复核、可否决的证据链。
kph 是 knowledge-pipeline 的独立开发副本，以「路线 A」接入 DeepSeek Harness（DSH）作为外层 operator harness。

kph 是什么

kph（本仓库）是从 knowledge-pipeline 物理拷贝出的独立开发副本，默认分支 develop。它保留 KP 的完整引擎与治理体系，并新增了 DSH 集成面（harness/、.dsh/）。详见 docs/memory/kph-fork-develop-copy.md。

kph 的能力

| 能力面 | 说明 | 权威位置 |
| RD Loop | clean-room 策略研发：ResearchPlan、baseline/M3/promotion gate、sealed holdout 预算（burn_budget_guard）、replay 内容寻址签名（replay_protocol） | backend/agents/rd_loop/ |
| DataHub Finance Layer | PIT 语义金融证据聚合（source / observed_at / cache 状态全披露，降级返回结构化 degraded 状态） | backend/finance_layer/ |
| Knowledge Graph | 治理投影与 artifact（ledger / projector / health contract 优先，不绕过治理直写） | backend/knowledge_graph/ |
| StockAutoCN 回测/回放桥 | 权威性能指标只来自 StockAutoCN v4 native metrics；KP 派生指标仅 diagnostic-only，不参与排名/promotion | backend/agents/strategy_loop/backtest_client.py |
| 市场数据面板 | 本地化 A 股日频数据（basic/valuation/margin 三维度，2015–2026），实验不再依赖 akshare 实时拉取 | data/market_panels/（gitignored） |
| kp CLI | kp doctor / gate / artifact / evidence / run / rd 产品化入口，kp.response/v1 信封 + 语义退出码 | backend/cli/ |

与 DeepSeek Harness 的关系

DSH（DeepSeek Harness） 是 DeepSeek AI 开源的外层 agent harness（MIT，developer preview；Cordis「everything is a plugin」内核），提供 Web GUI、会话编排、preset/plugin 机制与 approval policy。kph 与 DSH 的关系是三层的：

1. kph 独立可运行：kph 本体（KP 引擎 + 治理体系 + 数据资产）不依赖 DSH。kp CLI、后端 pytest、StockAutoCN Docker 栈均可脱离 DSH 直接运行（见下方「启动」第 3–4 步）。
2. 路线 A 插件接入：DSH 是 kph 的外层 operator harness。kph 以「路线 A（KP 作为 DSH 插件）」接入，接入面全部位于 harness/ 与 .dsh/skills/，不触碰后端运行链；B 路线（嵌入 DSH runtime）已 REJECT。方案与审批见 方案文档，实施结论见 接入记忆。
3. 治理权威不变：DSH 只调用、只展示、绝不重算。金融计算、评分、gate 判定、StockAutoCN native metrics 仍只由 KP Python 后端执行（git diff backend/ 必须为空）。

调用链：

KP backend（Python，运行链零改动） ← kp CLI（backend/cli，kp.response/v1 + 语义 exit code） ← DSH kp preset（~/.dsh/.agent-presets/kp/） persona + bash/fs/goal 工具 + kp-tools 薄插件（6 个类型化工具） ← DSH 技能发现（kph 仓库根 .dsh/skills/，symlink 镜像 skills/）

接入面组成：

| 组件 | 位置 | 作用 |
| kp preset | harness/dsh/preset/kp/ → 安装到 ~/.dsh/.agent-presets/kp/ | persona + agent-instructions + bash/fs/goal 工具 + kp-tools 插件 |
| kp-tools 薄插件 | harness/dsh/plugin/kp/kp-tools.js（纯 ESM、零第三方 import） | 6 个 kp 类型化工具 + P1 审批拦截 |
| 技能发现面 | .dsh/skills/（symlink 镜像 skills/，单源） | 3 个 KP 技能进入 DSH 会话技能目录，watcher 热更新 |
| 安装脚本 | harness/dsh/install.sh | 幂等同步 preset + 插件到用户 DSH preset 根 |

kp 类型化工具与审批语义（fail-closed）：

| 工具 | 类型 | 映射到 kp CLI | 说明 |
| kp_doctor | P0 只读 | kp doctor | 仓库/环境/运行面健康诊断 |
| kp_gate | P0 只读 | kp gate check/explain/blockers | 治理 gate 状态查询 |
| kp_artifact | P0 只读 | kp artifact ls/inspect/verify | 研究 artifact 查询与内容寻址校验 |
| kp_evidence | P0 只读 | kp evidence list/show | 治理证据查询 |
| kp_run | P1 审批 | kp run validate/start | 任务执行面，全部 action 拦截 |
| kp_rd | 混合 | kp rd list/show/blockers/replay（P0）+ beat（P1 审批） | RD loop 查询/执行面 |

- P0 工具无审批直通；P1 经 DSH approval policy 裁决（policy=ask 弹用户确认、never 自动拒绝），未批准绝不执行。
- 所有工具原样透传 kp.response/v1 / kp.error/v1 信封；插件不重算、不改写任何治理结论。
- 完整操作手册见 docs/operations/KP-DeepSeekHarness接入使用手册.zh.md。

接入：把 kph 装进 DSH（一次性）

前置条件：

- Node.js ≥ 22.19（DSH 要求，engines: ^22.19.0 || >=24.0.0）
- uv（KP 后端 Python 环境）
- Docker Desktop（可选，仅「StockAutoCN 回测栈」需要）

0) 取代码（默认分支 develop）
git clone https://github.com/ylouis8/kph.git
cd kph

1) 安装 kp preset 到用户 DSH preset 根（幂等，重复执行覆盖为仓库最新版） ./harness/dsh/install.sh → ${DSH_HOME:-~/.dsh}/.agent-presets/kp/ {agent.cordis.yml, preset.yml, plugin/kp-tools.js} → 技能面无需安装：DSH 从 kph 仓库根 .dsh/skills/ 自动发现（symlink 镜像 skills/，单源）

- DSH roster 每次调用都重读 preset 根：DSH 进程运行中安装也能被新会话发现，无需重启。
- 更新 = 改 harness/dsh/ 后重跑 ./harness/dsh/install.sh。注意 preset 代际 stamp 只以 agent.cordis.yml 为键：只改插件文件（kp-tools.js）时，需确保组装文件有字节变化或重启 DSH 进程。
- 卸载 = rm -rf ~/.dsh/.agent-presets/kp/（kph 仓库零残留运行依赖）。

启动

1) 启动 DSH Web GUI

npx @deepseek-ai/dsh web # npm 包方式（推荐），默认 http://127.0.0.1:3080

或从 deepseek-harness 源码 checkout 启动：

cd /Users/louis/Documents/louisliu/deepseek-harness
pnpm install && pnpm run build
pnpm dsh web # 或 pnpm run dev:web（HMR 开发模式）

2) 新建 kp 会话

1. 浏览器打开 http://127.0.0.1:3080，新建会话。
2. preset 选 KP Quant Operator（id：kp），工作目录选 kph 仓库根。
3. 首条消息建议 kp_doctor 看健康面；P1 工具（kp_run、kp rd beat）会按 approval policy 弹审批。

3)（可选）启动 kph 专用 StockAutoCN 回测栈

本仓库 data/ 已含 basic/valuation/margin 面板与 1681 回测数据（gitignored）
ls data/market_panels/ data/stock_autocn_runtime/

kph 专用栈（与原 stock_autocn 栈并存，端口 8010/5434/6380/3090；部署规则见 AGENTS.md §6）
cd /Users/louis/Documents/louisliu/stock_autocn
docker compose -p stock_autocn_kph -f docker-compose.yml -f docker-compose.kph.yml up -d postgres redis backend frontend
4) 不经 DSH 直接验证（CLI 路径）

cd backend
uv run pytest -q -m "not live and not e2e" # 后端默认回归
uv run kp doctor # kp CLI 健康面

Demo 示例：半导体行业周换仓回测

完整 demo 脚本：experiments/codex/run_demo_semiconductor_weekly.py 证据落盘：outputs/demo_semiconductor_weekly_20260814/（回测请求/持仓/决策载荷/native 结果）

做了什么：用 kph 能力生成半导体行业持仓（申万二级 801081 ∩ 1681 回测池 = 36 只），每周用前 20 个交易日收益率选 Top 10 等权换仓，提交 kph 专用 StockAutoCN 栈验证 2025-01-02 → 2026-08-07 收益（初始 100 万、周换仓、严格信号滞后）。

半导体成分一次性入库（之后不再调 akshare） data/industry/sw2_semiconductor_801081_members.csv（178 只）跑 demo（生成持仓 + 上传策略 + preflight + 回测 + 轮询结果）
cd backend && uv run python ../experiments/codex/run_demo_semiconductor_weekly.py

回测效果（StockAutoCN v3_rust native metrics，非 KP 重算）：

| 指标 | 数值 |
| 期末资产 | 2,630,127 元（初始 1,000,000） |
| 总收益 / 年化 | +163.01% / 87.7% |
| 同期买入持有对照 | +156.42% |
| Sharpe / Sortino / Calmar | 1.48 / 2.08 / 2.08 |
| 最大回撤 | -42.22%（2026-07-01 → 08-03） |
| 胜率 / 交易数 / 佣金 | 93.85% / 130 笔 / 370 元 |

⚠️ 该 demo 定位 diagnostic_only / not_promotion_evidence：回测窗口与历史 sealed holdout 存在重叠，不构成 challenge 判定；等权 10 只半导体无风控，回撤极深，仅作运营演示。

治理边界（不可弱化）

- clean-room、PIT、baseline、M3、lifecycle、promotion gate 不得弱化；sealed holdout 消耗必须经 burn_budget_guard 记账。
- 权威性能指标只来自 StockAutoCN v4 native persisted metrics；KP 派生指标只能 diagnostic-only。
- 前端不实现核心金融指标计算；无授权不改 Docker/stock_autocn；git 提交需用户明确要求。
- 完整规范见 AGENTS.md。

文档

| 文档 | 定位 |
| AGENTS.md | 项目边界、环境、Git、测试、完成定义的权威事实源 |
| docs/memory/ | 项目级记忆（用户偏好、纠错、可复用结论） |
| docs/planes/governance/current/ | 当前项目状态 |
| docs/architecture/ | 当前架构 |
| docs/plan/ | 计划、spec、runbook |
| docs/plan/KP与DeepSeekHarness结合升华方案-2026-08-14.zh.md | kph 接入 DSH 的方案与审批记录 |
| docs/operations/KP-DeepSeekHarness接入使用手册.zh.md | kph 接入 DSH 的操作手册（安装/工具/验收/FAQ） |
| skills/ | 统一技能目录（研发规范 + 工作流） |

开发

cd backend
uv run ruff check # lint
uv run pytest -q -m "not live and not e2e" # 默认回归

贡献

改动行为变更须按 AGENTS.md §3 流程：上下文发现 → 需求 checkpoint → TDD → 小步实现 → 验证 → 知识沉淀。未经用户要求不自动 commit/push。

社区与支持

- 欢迎通过 GitHub Discussions 提交反馈或 bug 报告。
- 为你的插件仓库添加 dsh-plugin 话题，便于被发现。