ylouis8

kph

Name: kph
Author: ylouis8

基于dsh的量化研究agent，驱动真实回测与交易。

Stars: 1
Language: Python
Created: Aug 14, 2026
Updated: Aug 14, 2026

Other

GitHub repo

Introduction

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 的关系是三层的：

kph 独立可运行：kph 本体（KP 引擎 + 治理体系 + 数据资产）不依赖 DSH。kp CLI、后端 pytest、StockAutoCN Docker 栈均可脱离 DSH 直接运行（见下方「启动」第 3–4 步）。
路线 A 插件接入：DSH 是 kph 的外层 operator harness。kph 以「路线 A（KP 作为 DSH 插件）」接入，接入面全部位于 harness/ 与 .dsh/skills/，不触碰后端运行链；B 路线（嵌入 DSH runtime）已 REJECT。方案与审批见方案文档，实施结论见接入记忆。
治理权威不变：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 会话

浏览器打开 http://127.0.0.1:3080，新建会话。
preset 选 KP Quant Operator（id：kp），工作目录选 kph 仓库根。
首条消息建议 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 Example：半导体行业周换仓回测

完整 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。

Documentation

文档	定位
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/	统一技能目录（研发规范 + 工作流）

Development

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

Contributing

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

社区与支持

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