百炼成金 SZYTree0312/dsh-bailian-gold

百炼成金模式（bailian-gold）

挂在 DeepSeek Harness（dsh）上的 agent preset，为阿里云百炼（Model Studio）这条路线做前缀缓存优化。
不是独立运行时、不是 fork。

上游基线：0.2.0-rc.2（必须 pin，上游明示会有破坏性变更）。

名字化用成语「百炼成钢」：百炼是平台，成金是结果——反复锤炼，省的是金子。

适用范围：一个 preset，全部模型

这份 preset 的差异化与模型厂商无关，只跟端点的隐式前缀缓存有关。所以百炼上的 Qwen / DeepSeek / Kimi / GLM / MiniMax 全部共用同一个 preset。

每个模型的差异落在两处，都不需要第二个 preset、更不需要 git branch：

- 窗口大小、是否支持思考 → route 的 models 条目（Host 层）
- 压缩比例 → modelPolicies（按 provider + model 精确覆盖）

为什么百炼上的 DeepSeek 比官方 DeepSeek 更需要它

dsh 的 standard preset 是为官方 DeepSeek API 设计的，那个端点有
systemPromptUpdate: in-history 兜底——系统提示变更时追加在缓存历史之后，而不是重写开头。

百炼两条路都拿不到这个能力（原因见下文「协议层」）。于是 standard 在百炼上会放任系统提示重写、前缀缓存整体失效。本 preset 不依赖它——前缀稳定性由 harness 侧自己保证。
这就是「阿里云下的 DeepSeek 和官方的用起来不一样」的根源。

一句话原理

百炼对缓存命中的输入按输入单价的折扣计费 —— 隐式命中 20%，显式命中 10%。
所以这个 preset 的一等指标不是 token 数，是 prefix cache hit rate。

由此推出三条与其他 harness 相反的做法：

1. 工具目录全程固定，不按阶段裁剪或扩展。上游 plan-mode 提示词里已经写着 "The tool catalog stays the same across modes for request-cache stability"——这里把它从 plan mode 推广到整个会话。
2. 历史只追加，压缩只做定点区间替换，系统提示永不进压缩区。
3. 动态状态一律推到尾部，绝不注入系统提示。

已实测（2026-09-30）

在同一实例上发三次同一段 10391 token 的前缀：

| | 第 1 次 | 第 2 次 | 第 3 次 |
| OpenAI 壳（隐式）| cached 0 | cached 10240 | cached 10240 |
| Anthropic 端点（显式）| create 10377 | read 10377 | read 10377 |

两种缓存都通，隐式覆盖 98.5%、显式覆盖 99.9%。 完整数据、计费对照与推算见 docs/verify-prefix-cache.md。

成本核算：三条杠杆，按大小排

| token 类别 | 单价 | 谁在管 |
| 命中缓存的输入 | 输入价 × 20%（隐式）/ 10%（显式）| 本 preset 的全部设计 |
| 未命中的输入（每轮新增）| 输入价 × 100% | 压缩期减压阀 + 提示词纪律 |
| 输出（含思考）| 输出价，不参与缓存 | 提示词纪律（部分）|

输入是绝对大头。 一段稳定前缀每轮原样重发，会话越长，缓存折扣的杠杆越大。

杠杆一：把隐式缓存换成显式缓存

设一段 T token 的稳定前缀连续重复 N 轮：

隐式 = 1.00 + 0.20 × (N−1) 显式 = 1.25 + 0.10 × (N−1) ← 创建贵 25%，命中便宜一半转折点：N ≥ 4

| 轮数 | 隐式 | 显式 | 显式省 |
| 3 | 1.40 | 1.45 | −3.6% |
| 10 | 2.80 | 2.15 | 23.2% |
| 50 | 10.80 | 6.15 | 43.1% |
| 100 | 20.80 | 11.15 | 46.4% |

渐近上限 50%。本 preset 的设计恰好落在显式缓存的最优区 —— 它的全部功力都花在「让前缀字节稳定、每轮原样重发」上，而稳定前缀重复轮数越多，显式越划算。

→ 走 examples/aliyun-anthropic-route.patch.yml。
这条路线以前只作为「更接近原生」的备选写着，它的第一价值其实是省钱。

代价：显式缓存有效期固定 5 分钟（命中后重置）；隐式由系统不定期清理、没有明确上限。
交互密集的会话选显式；搁置型会话两者差别不大。

杠杆二：别让压缩触发

压缩是唯一会主动把前缀打断的操作，而它的触发点由 route 的 contextWindow 决定 ——这一项没填对，上面所有设计都白搭，见下文。

杠杆三：思考是笔隐形输出开销

qwen3.8-flash 在百炼上默认开思考，而 llm-pi-ai 对未声明 reasoningEfforts 的模型判定为「不思考」（源码注释原话：a hand-declared model has none and does not reason），于是既不发控制参数，也不在 harness 视野里。实测一次普通提问， 80 个输出 token 里 55 个是思考（69%）。官方明确「思维链内容全部计入输出 Token 统计」。

输出价是缓存命中价的几十倍，这是一条每轮都在跑的开销。怎么控制见 docs/verify-prefix-cache.md 第 4 节（配置写法未验证，且关掉思考是否划算取决于它换来的轮数 —— 是取舍，不是纯赚）。

与梁神模式的关系

形态相同（都是一个 @deepseek-ai/dsh-agent-preset 声明，经 bundle patch 装入 profile）， Mechanism is reversed. Liang-shen mode relies on switching the tool directory for first-round anchoring—it pays off on the official DeepSeek API, but on Bailian a single session would destroy the prefix cache twice. Here we instead use "tool directory resident + first-round output budget (bootstrapMaxTokens, which only changes sampling parameters and has zero impact on the cache) + tail anchoring instruction" to achieve the same goal.

Directory

presets/bailian-gold.patch.yml preset definition, main artifact (0.1.7+ / 0.2.x)
compat/0.1.5/ compatible version for dsh 0.1.5-rc.x (old preset mechanism)
examples/aliyun-route.patch.yml Aliyun route (OpenAI-compatible shell)
examples/aliyun-anthropic-route.patch.yml Aliyun route (Anthropic endpoint, closer to native)
docs/spike-01-.md source-level verification of whether the prefix can be locked
docs/verify-prefix-cache.md measured: cache hits, explicit vs implicit billing, thinking overhead
docs/compare-whale-elite.md item-by-item comparison with Whale-Elite mode
.ref/ upstream reference source (gitignore, read-only)

Version compatibility

Covers multiple official dsh releases (rc line, alpha not counted). The dividing point is 0.1.7-rc.1:

| dsh version | preset mechanism | Which to use |
| 0.1.7-rc.1 and later (including 0.2.0-rc.x) | @deepseek-ai/dsh-agent-preset plugin line, installed via profile patch | presets/bailian-gold.patch.yml |
| 0.1.5-rc.1 ~ rc.3 | @deepseek-ai/dsh-agent-presets (plural) scans /.agent-presets/ | compat/0.1.5/ |

Starting from 0.1.7-rc.1, upstream split the preset into two packages, agent-preset-registry + agent-preset, and the preset also changed from "a standalone file" to "a one-line plugin declaration".

The 0.1.5 installation method is different (the old mechanism does not go through the plugin command; instead it copies the directory to ~/.dsh/.agent-presets//). For the difference list and operation steps, see compat/README.md.

Integration

A complete working setup requires two parts, with different responsibilities:

| Part | Layer | What it manages |
| presets/bailian-gold.patch.yml | Agent (preset) | Tool surface, prompts, compaction strategy |
| examples/aliyun-route.patch.yml | Host (profile patch) | Model routing and capacity |

Route names must be aligned

The provider identifier takes the route name from the llm-pi-ai configuration in the profile. On this machine it is aliyun (not dashscope—a typo will not raise an error, modelPolicies will silently fail, and the entire strategy will fall back to upstream defaults). Both modelPolicies.provider and summarizationProvider in the preset are written according to this.

Why the route's contextWindow is the key number

The actual trigger point of compaction is:

min(contextWindow × thresholdRatio, messageBudget − headroomTokens)
messageBudget = contextWindow − per-request output reservation

When the window is not large enough, the right-hand term is the one that actually takes effect, and thresholdRatio is effectively useless. Substituting this machine's defaults (defaultContextWindow 262144, defaultMaxTokens 32768, headroom 65536):

messageBudget = 262144 − 32768 = 229376
pressureBudget = 229376 − 65536 = 163840
trigger point = min(262144 × 0.92 = 241172, 163840) = 163840

The 241172 expected from thresholdRatio: 0.92 can never be reached. Set contextWindow to the maximum input of Qwen3.8-Flash official standard mode, 991808, and the trigger point rises to about 893504, which a normal session simply cannot reach—so the prefix cache will not be entirely invalidated by a single replace.

⚠️ Not filling in contextWindow is equivalent to giving up the main benefit of this preset. It falls back to defaultContextWindow 262144, and the trigger point is only 163840—a normal coding session can reach it, and compaction (along with prefix cache invalidation) will really happen. It is already written in examples/; it only counts once you copy it into the profile's cordis.patch.yml.

Do not set the model's maxTokens: it will simultaneously become the per-request output default, lower messageBudget, and make compaction trigger earlier, which is the opposite of this preset's goal.

Protocol layer: two paths, and one that cannot be patched

Bailian provides both an OpenAI-compatible shell (/compatible-mode/v1) and an Anthropic-compatible endpoint (/apps/anthropic, POST …/v1/messages). The latter is the one closer to native:

| | OpenAI shell | Anthropic endpoint |
| Thinking output | reasoning_content field (non-standard parameters must be intercepted into headers to pass through) | Native thinking content blocks |
| Tool calls | OpenAI function call | Native tool_use / tool_result blocks |
| Cache | Implicit only | Implicit + cache_control: {type: ephemeral} explicit breakpoint |
| systemPromptUpdate: in-history | ✗ | ✗ |
| /v1/models 发现 | ✓ | ✗（须手写 models）|

配置见 examples/aliyun-anthropic-route.patch.yml。

in-history 补不了，两边都堵：官方 DeepSeek 靠它保证“系统提示变更时追加而非重写开头”，是保前缀缓存的关键。但百炼 Anthropic 文档明确“system 是顶层参数， messages 数组不接受 system 角色*”，端点语义就不支持；pi-ai 侧的 supportsMidConvoSystemMessages / supportsMidConvoToolAdditions 两个能力位在 compat 表里是 withhold（只能由 pi-ai 内置 catalog 声明），手申报路由拿不到。

照搬 llm-deepseek 的默认 catalog 声明 in-history，打这个端点会让系统提示直接失效。

替代方案是把前缀稳定性交给 harness 侧——本 preset 的三条设计本就是在保证系统提示不变，不需要端点配合。这条原生机制是用设计绕过去的，不是补出来的。

安装

前提：profile 里已有 llm-pi-ai 的 aliyun route（见 examples/，OpenAI 壳与 Anthropic 端点两种方案按需选一）。

dsh plugin --profile web add github:SZYTree0312/dsh-bailian-gold

装完后在会话预设选择器里选 百炼成金模式。卸载：

dsh plugin --profile web remove dsh-bailian-gold

部分实机验证。 前缀缓存是否可命中已用真实请求测通（见 docs/verify-prefix-cache.md）；其余结论来自对上游 0.2.0-rc.2 源码的静态分析。本 preset 本身还没有跑过一次完整真实会话 ——工具目录是否真的全程不变、压缩触发点是否如预期、真实会话的命中率，都待实测。

状态

- [x] 源码级验证：前缀可锁（见 docs/spike-01-context-compaction.md）
- [x] preset 第一版：纯配置，基于 upstream standard 改造
- [x] provider 校准为 aliyun，route 配套配置见 examples/
- [x] 定位修正：从「Qwen 专用」改为「百炼全平台」——差异化在缓存，不在厂商
- [x] 对比鲸英模式并采纳 includeRuntimeContext: false 与 prompt 纪律；
工具结果裁剪一项经 2026-09-30 复核降级为「压缩期减压阀」，且其取值等于上游默认（见 docs/compare-whale-elite.md）
- [x] 实测：前缀缓存可命中（隐式 98.5% / 显式 99.9%），
并算出隐式→显式的成本转折点在第 4 轮（见 docs/verify-prefix-cache.md）
- [ ] 把 examples/ 的 route（尤其 contextWindow）真正落到 profile —— 不填等于放弃主要收益
- [ ] 实机验证：装进 profile 跑一次完整会话，确认 preset 加载与压缩触发点
- [ ] 思考开销的控制（reasoningEfforts + compat.thinkingFormat）—— 写法未验证
- [ ] bootstrapMaxTokens 落点（已定位到 llm-pi-ai，具体参数待确认）
- [ ] 缓存命中率可观测：把 cached_tokens 暴露到 telemetry