kph

kph 是什么

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

kph 的能力

与 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 类型化工具与审批语义（fail-closed）：

• 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 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 重算）：

⚠️ 该 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

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 话题，便于被发现。