@dsh-cc/model-aliases 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,6 @@
1
+ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
2
+ # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
+ # after editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/compat/cc-model-aliases/README.md
5
+ README.md: 282a1cfbed8630fc15c525dfb95b48ef38f911dc
6
+ README.zh.md: 8471c4e71f9f1a004d79240a0355a35b49eb24f8
package/README.md ADDED
@@ -0,0 +1,235 @@
1
+ # @dsh-cc/model-aliases
2
+
3
+ English | [中文](README.zh.md)
4
+
5
+ Claude Code-compatible model alias resolution for the DeepSeek Harness. It maps Claude Code
6
+ frontmatter model aliases (`model: opus`, `model: sonnet`) onto dsh
7
+ `{provider, model, reasoningEffort?}` routes. The package now ships in two shapes:
8
+
9
+ - a **`ccModelRoutes` host service** (the cordis plugin entry) that owns the `model-aliases`
10
+ settings namespace registration and exposes a spawn-time resolver, and
11
+ - the **pure helpers** (`mergeAliasMaps` / `createModelResolver`) for embedding the same
12
+ resolution semantics without mounting the service.
13
+
14
+ ## Why
15
+
16
+ Claude Code agent/CLAUDE.md frontmatter names models by alias. Without an alias
17
+ layer, `model: opus` was passed through verbatim as a provider model id, so an
18
+ adapter that does not know the id (e.g. `llm-pi-ai`) threw `UNKNOWN_MODEL`, and
19
+ `model: inherit` — a valid CC sentinel meaning "use my parent's model" — was
20
+ also handed to `prepareCall` as a literal id and errored.
21
+
22
+ This package adds that layer: an alias resolves to a `{provider, model, reasoningEffort?}` route,
23
+ the unresolvable cases fall back to *inheriting the parent route* (no override),
24
+ and literal ids like `deepseek-chat` keep passing through untouched.
25
+
26
+ ## The `ccModelRoutes` service
27
+
28
+ The plugin entry (`name: 'cc-model-routes'`, `apply`) is what the CC preset mounts via the
29
+ `cc-model-routes` row. It:
30
+
31
+ - registers the `model-aliases` **settings namespace** — but **only when** a settings
32
+ provider (`ctx.get('settings')`) is mounted, so a settings-less host degrades to the config
33
+ defaults plus the builtin fallback (this namespace registration is the single owner of that
34
+ name; the harness throws on a duplicate registration, see `dsh-settings`);
35
+ - registers the namespace with a **write-time `validate`** that rejects a half-written
36
+ `{provider, model}` route (a non-empty cross-field check the dict schema itself cannot
37
+ express);
38
+ - and provides the spawn-time resolver as the **`ccModelRoutes`** value (`ctx.provide`) whose
39
+ `resolve(model)` reads the **live** settings scope on every invocation — a settings write
40
+ applies to the next spawn with no re-registration.
41
+
42
+ Consumers `ctx.get('ccModelRoutes')` **lazily** on every spawn. Lazily means mount order does
43
+ not matter: before the provider's fiber is active, `ctx.get` returns `undefined`, which
44
+ resolves to "inherit the parent route" (the same no-override behavior as before).
45
+
46
+ ## How the cc-shell bundle wires it
47
+
48
+ - `Config.modelAliases` provides **deployment defaults** (alias name → model id
49
+ or `{provider, model}`).
50
+ - The `model-aliases` **settings namespace** registration now lives in the `ccModelRoutes`
51
+ service, layered exactly like every other settings section (user/project/local/flags).
52
+ - cc-shell's `AgentProvider` gains its `resolveModel` as a **trampoline** over the service:
53
+ `(model) => ctx.get('ccModelRoutes')?.resolve(model)` — queried **lazily on every spawn**,
54
+ read fresh (no snapshot captured at apply time), and degrading to inherit when the service
55
+ is not mounted (`undefined` resolution = inherit the parent route, byte-compatible with the
56
+ old no-resolver fallback). cc-shell no longer registers the namespace itself.
57
+ - The Task tool (`@dsh-cc/subagent-task`) is the other consumer: it resolves a
58
+ subagent definition's frontmatter `model` through the same `ccModelRoutes` resolver at
59
+ spawn time.
60
+
61
+ ## Configuration
62
+
63
+ ```yaml
64
+ # ccModelRoutes service config (the preset's cc-model-routes row)
65
+ modelAliases:
66
+ sonnet: deepseek-v4-flash # string form: model only, provider inherits
67
+ opus: { provider: deepseek-official, model: deepseek-v4-pro } # explicit route
68
+ ```
69
+
70
+ ```jsonc
71
+ // settings namespace "model-aliases"
72
+ {
73
+ "fable": { "provider": "anthropic", "model": "claude-fable-5" },
74
+ "sonnet": null // null = delete the same-named config-default alias
75
+ }
76
+ ```
77
+
78
+ ## Resolution semantics
79
+
80
+ Lookup order for an alias: **settings overlay → config defaults → builtin
81
+ fallback**. Alias key matching is **case-insensitive** (keys are folded to
82
+ lowercase at merge and at lookup).
83
+
84
+ | `model` frontmatter | Result |
85
+ |---|---|
86
+ | `undefined` / blank | no override — child inherits the parent route |
87
+ | `inherit` (any case) | no override — child inherits the parent route (**fixes the old pass-through bug**) |
88
+ | configured alias (string form) | `{ model: <target> }` |
89
+ | configured alias (object form) | `{ provider?: <p>, model: <m>, reasoningEffort?: <effort> }` |
90
+ | builtin alias unconfigured (`fable`/`opus`/`sonnet`/`haiku`) | no override — child inherits the parent route ("current model") |
91
+ | dsh-cc lane unconfigured (`sketch`/`draft`/`blueprint`/`masterplan`) | follows the CC peer (`haiku`/`sonnet`/`opus`/`fable`); inherit if that peer is also unconfigured |
92
+ | `architect` unconfigured | no override — inherit the parent (main-thread) route |
93
+ | anything else | passed through **verbatim** as a literal model id; a bare-lowercase-word form (e.g. `turbo`) logs a warning that it looks like an unconfigured alias |
94
+
95
+ ### `reasoningEffort` on object-form aliases
96
+
97
+ An object-form alias may declare an optional `reasoningEffort`: an opaque
98
+ non-empty string whose legal spellings belong to the **target model's adapter**
99
+ (`max`, `xhigh`, `high`, … — not validated against any adapter catalog here).
100
+ When present, the spawn (the Task tool and the plugin-loader's
101
+ `AgentProvider`) stamps it onto the child's options, and the routes service's
102
+ host `agent/request` listener applies it to **every** request of that child,
103
+ overriding any effort restored from a forked parent header. String-form
104
+ aliases cannot carry an effort; `inherit` / unconfigured builtins stamp
105
+ nothing. An effort the target model does not support fails the request with
106
+ `UNSUPPORTED_REASONING_EFFORT` — fail-loud, by design.
107
+
108
+ ```jsonc
109
+ // settings namespace "model-aliases"
110
+ {
111
+ "opus": { "provider": "orchestrix", "model": "glm-5.3", "reasoningEffort": "max" },
112
+ "sonnet": { "provider": "orchestrix", "model": "glm-5.3-flash", "reasoningEffort": "max" }
113
+ }
114
+ ```
115
+
116
+ Changing the opus target to a model with a different effort vocabulary is a
117
+ single settings edit (`"reasoningEffort": "xhigh"`); the agent markdown is
118
+ untouched.
119
+
120
+ ### Null deletion
121
+
122
+ Only the **settings** layer may set an entry to `null`; that deletes a
123
+ same-named **config-default** entry (entry-shallow). Deleting a *builtin* alias
124
+ still falls through to the builtin fallback — `null` cannot turn `sonnet` into an
125
+ error, because the builtin fallback is **inherit the parent route**. Config may
126
+ never hold `null` (rejected by the config schema).
127
+
128
+ ### Merge rules
129
+
130
+ - **Config vs settings is entry-shallow**: a settings entry replaces the config
131
+ entry wholesale. It never field-merges `{provider, model}` objects — so
132
+ `config { provider: A, model: X }` + `settings { model: Y }` yields
133
+ `{ model: Y }`, never a blended `{ provider: A, model: Y }` that no single
134
+ layer declared.
135
+ - **Within the settings 5-cascade the merge is recursively deep** (existing
136
+ cascade behavior). Consequently an object-form alias must be written **whole
137
+ or not at all** across settings layers, or the cascade will field-blend
138
+ `{provider, model}` just as described above — this is a cascade-level
139
+ behavior this package does not change. Prefer string-form aliases, or repeat
140
+ the full route on every layer that mentions the alias.
141
+
142
+ ### Builtin fallback
143
+
144
+ Fresh installs with **zero configuration** still work: `model: sonnet` /
145
+ `model: opus` / `model: draft` agents resolve to *inherit the parent's current
146
+ model* (an unconfigured lane follows a configured CC peer) instead of
147
+ erroring. Builtin names (CC family + dsh-cc lanes) get this fallback; a
148
+ custom alias (`turbo`, `gpt`, …) that is unconfigured has **no** fallback
149
+ and is passed through verbatim (with the warning above).
150
+
151
+ ## `inherit` fix note
152
+
153
+ Prior to this package, `model: inherit` was forwarded as the literal model id
154
+ all the way to `prepareCall`, where it failed. In CC mode the spawn-time resolver
155
+ (from the `ccModelRoutes` service, consumed via the cc-shell trampoline and the
156
+ Task tool) maps `inherit` to "no override", so the child inherits the parent
157
+ route, matching CC semantics. When no resolver is mounted (non-cc consumers of
158
+ `@dsh-cc/plugin-loader` that do not set `resolveModel`), behavior stays
159
+ byte-identical to before — including the old `inherit` pass-through — because the
160
+ no-resolver fallback is preserved exactly. The CC preset unconditionally mounts
161
+ cc-shell (and the routes service), so in CC mode the fix is always active.
162
+
163
+ ## API
164
+
165
+ - `apply(ctx, config?)` / `name` — **cordis plugin entry** (plugin id `cc-model-routes`,
166
+ also re-exported as `applyRoutes` / `routesPluginName`). Mounts the service; config shape is
167
+ `{ modelAliases?: Record<string, AliasTarget> }` (deployment defaults).
168
+ - `ModelRoutes` — the value type of `ctx.get('ccModelRoutes')` (`resolve(model):
169
+ { provider?, model?, reasoningEffort? } | undefined`).
170
+ - `overlayStampedEffort(resolved, stamped)` / `stampedEffortOf(options)` — the
171
+ host-side effort overlay used by the service's `agent/request` listener;
172
+ exported for tests and host embeddings.
173
+ - `mergeAliasMaps(config, settings)` — entry-shallow merge with `null` deletion
174
+ and case-insensitive key folding; returns an effective `ReadonlyMap` of only
175
+ the configured aliases.
176
+ - `createModelResolver(getAliases, { warn })` — build a `resolveModel` closure.
177
+ `getAliases` is a thunk evaluated **per invocation** (liveness). Optional
178
+ `warn` replaces the default `console.warn` used for the unconfigured-custom-alias
179
+ warning.
180
+ - `BUILTIN_ALIASES` — CC family (`fable`/`opus`/`sonnet`/`haiku`) plus dsh-cc lanes (`sketch`/`draft`/`blueprint`/`masterplan`/`architect`).
181
+ - `LANE_PEERS` — unconfigured-lane → CC-family map (`sketch→haiku`, `draft→sonnet`, `blueprint→opus`, `masterplan→fable`; `architect` has no peer).
182
+ - `toAgentOptions(route)` — drop `undefined` fields from a resolved route so
183
+ per-field inheritance survives (never set a field to `undefined` on the child
184
+ request); `undefined` in → `undefined` out, and an all-`undefined` route
185
+ collapses to `undefined` ("no override"). Shared by Task, cc-plugin-loader,
186
+ the hooks bridge, and memory recall.
187
+ - `toOneShotRoute(route, parent?)` — fill a resolved alias into a complete
188
+ `{provider, model}` pair for an independent one-shot `ctx.llm.stream` call:
189
+ alias fields win, missing fields inherit from the parent route, and an
190
+ incomplete pair (no model after inherit) returns `undefined` so callers
191
+ treat it as "unconfigured". Used by the session-title overlay and the
192
+ WebFetch summarizer.
193
+ - `ConfigAliasesSchema` / `SettingsAliasesSchema` (and their record forms) —
194
+ schemastery schemas for the config layer (no `null`) and settings layer
195
+ (`null` allowed), plus `AliasTarget` / `ResolvedRoute` types.
196
+
197
+ ## dsh-cc lanes
198
+
199
+ Five extra builtin names sit alongside the Claude Code family. They are
200
+ configuration, not a second settings namespace. Unconfigured, each lane
201
+ except `architect` follows its CC peer, so a deployment that already maps
202
+ `haiku` does not need a duplicate `sketch` entry:
203
+
204
+ | Lane | Role | Unconfigured peer |
205
+ |---|---|---|
206
+ | `sketch` | Fast, lightweight execution | `haiku` |
207
+ | `draft` | Balanced everyday coding | `sonnet` |
208
+ | `blueprint` | Deep reasoning | `opus` |
209
+ | `masterplan` | Maximum reasoning | `fable` |
210
+ | `architect` | Planning and orchestration | inherit (main thread) |
211
+
212
+ A configured string-form target that names another alias is followed **one
213
+ hop** (`sketch: haiku` shares haiku's object route, including
214
+ `reasoningEffort`). Object-form targets are concrete routes and are not
215
+ followed as names. A second hop is not followed, so `sketch: draft` +
216
+ `draft: haiku` stops at the literal `"haiku"` (cycle-safe).
217
+
218
+ Frontmatter can use either vocabulary (`model: opus` or `model: blueprint`).
219
+ The cheap background classifier lane stays `resolve('haiku')` — hooks and
220
+ recall do not switch to `sketch`.
221
+
222
+ ## The cheap (small-fast) lane
223
+
224
+ There is no second alias name and no `ANTHROPIC_SMALL_FAST_MODEL`. The cheap
225
+ background lane **is** the configured `haiku` alias: consumers that need a
226
+ small, independent one-shot classifier model call `resolve('haiku')` — the
227
+ configured haiku route when set, inherit-the-parent when unconfigured (the
228
+ builtin fallback). Current consumers: the hooks bridge (`prompt`/`agent` hooks
229
+ without an authored `model:`), memory recall with `recallUseSmallFast: true`,
230
+ the session-title overlay, and the WebFetch summarizer.
231
+
232
+ ## Non-goals (tracked in the parity matrix)
233
+
234
+ `/model` interactive command, `ANTHROPIC_MODEL` / `ANTHROPIC_SMALL_FAST_MODEL`
235
+ env vars, and aliasing the main session's default model remain follow-ups.
package/README.zh.md ADDED
@@ -0,0 +1,131 @@
1
+ # @dsh-cc/model-aliases
2
+
3
+ [English](README.md) | 中文
4
+
5
+ 面向 DeepSeek Harness 的 Claude Code 兼容 model alias 解析。把 CC frontmatter 的 model alias(`model: opus`、`model: sonnet`)映射为 dsh 的 `{provider, model, reasoningEffort?}` 路由。本 package 现在以两种形态提供:
6
+
7
+ - **`ccModelRoutes` 宿主服务**(cordis 插件入口),拥有 `model-aliases` settings 命名空间的注册,并暴露派发时的解析器;
8
+ - **纯 helper**(`mergeAliasMaps` / `createModelResolver`),在不挂载服务的情况下内嵌同样的解析语义。
9
+
10
+ ## 为什么
11
+
12
+ Claude Code 的 agent/CLAUDE.md frontmatter 用 alias 命名模型。没有 alias 层时,`model: opus` 会被原样当作 provider model id 透传,因此不认识该 id 的 adapter(如 `llm-pi-ai`)抛 `UNKNOWN_MODEL`;而 `model: inherit`——CC 中意为「用父模型」的合法哨兵——也会被当作字面 id 交给 `prepareCall` 然后报错。
13
+
14
+ 本 package 补上这层:alias 解析为 `{provider, model, reasoningEffort?}` 路由,不可解析的情形回退为*继承父路由*(不 override),而 `deepseek-chat` 之类的字面 id 原样透传不受影响。
15
+
16
+ ## `ccModelRoutes` 服务
17
+
18
+ 插件入口(`name: 'cc-model-routes'`、`apply`)即 CC preset 通过 `cc-model-routes` 行挂载的东西。它:
19
+
20
+ - 注册 `model-aliases` **settings 命名空间**——但**仅当**存在 settings provider(`ctx.get('settings')`)时,因此无 settings 的宿主降级为 config 默认 + builtin fallback(该命名空间注册是此名的唯一属主;重复注册 harness 会 throw,见 `dsh-settings`);
21
+ - 以**写时 `validate`** 注册该命名空间,拒绝半写的 `{provider, model}` 路由(dict schema 本身无法表达的非空跨字段校验);
22
+ - 并把派发时解析器以 **`ccModelRoutes`** 值(`ctx.provide`)提供,其 `resolve(model)` 每次调用**现读** settings scope——settings 写回即在下次派发生效,无需重新注册。
23
+
24
+ 消费者在每次派发时**惰性** `ctx.get('ccModelRoutes')`。惰性意味着挂载顺序无关:provider fiber 激活之前,`ctx.get` 返回 `undefined`,解析为「继承父路由」(与之前的 no-override 行为相同)。
25
+
26
+ ## How the cc-shell bundle wires it(如何接线)
27
+
28
+ - `Config.modelAliases` 提供**部署默认**(alias 名 → model id 或 `{provider, model}`)。
29
+ - `model-aliases` **settings 命名空间**的注册现在住在 `ccModelRoutes` 服务里,与其它 settings section 一样分层(user/project/local/flags)。
30
+ - cc-shell 的 `AgentProvider` 通过**trampoline** 获得 `resolveModel`:`(model) => ctx.get('ccModelRoutes')?.resolve(model)`——**每次派发惰性查询**、现读(apply 时不快照),服务未挂载时降级为继承(`undefined` 解析 = 继承父路由,与旧 no-resolver fallback 字节兼容)。cc-shell 自己不再注册该命名空间。
31
+ - Task 工具(`@dsh-cc/subagent-task`)是另一消费方:它在派发时以同一个 `ccModelRoutes` 解析器解析 subagent 定义 frontmatter 的 `model`。
32
+
33
+ ## 配置
34
+
35
+ ```yaml
36
+ # ccModelRoutes 服务配置(预设的 cc-model-routes 行)
37
+ modelAliases:
38
+ sonnet: deepseek-v4-flash # 字符串形式:仅 model,provider 继承
39
+ opus: { provider: deepseek-official, model: deepseek-v4-pro } # 显式路由
40
+ ```
41
+
42
+ ```jsonc
43
+ // settings 命名空间 "model-aliases"
44
+ {
45
+ "fable": { "provider": "anthropic", "model": "claude-fable-5" },
46
+ "sonnet": null // null = 删除同名的 config-default alias
47
+ }
48
+ ```
49
+
50
+ ## 解析语义
51
+
52
+ alias 的查找顺序:**settings overlay → config 默认 → builtin fallback**。alias key 匹配**大小写不敏感**(merge 与 lookup 时 key 折叠为小写)。
53
+
54
+ | `model` frontmatter | 结果 |
55
+ |---|---|
56
+ | `undefined` / 空 | 无 override——child 继承父路由 |
57
+ | `inherit`(任意大小写) | 无 override——child 继承父路由(**修复旧的透传 bug**) |
58
+ | 已配置 alias(字符串形式) | `{ model: <target> }` |
59
+ | 已配置 alias(对象形式) | `{ provider?: <p>, model: <m>, reasoningEffort?: <effort> }` |
60
+ | 未配置的 builtin alias(`fable`/`opus`/`sonnet`/`haiku`) | 无 override——child 继承父路由(「当前模型」) |
61
+ | 未配置的 dsh-cc lane(`sketch`/`draft`/`blueprint`/`masterplan`) | 跟随 CC 对标名(`haiku`/`sonnet`/`opus`/`fable`);对标也未配置则 inherit |
62
+ | 未配置的 `architect` | 无 override——继承父(主线程)路由 |
63
+ | 其它 | **原样**作为字面 model id 透传;裸小写单词形式(如 `turbo`)记录一条「看起来像未配置 alias」的告警 |
64
+
65
+ ### 对象形式 alias 的 `reasoningEffort`
66
+
67
+ 对象形式 alias 可声明可选的 `reasoningEffort`:一个不透明的非空字符串,其合法拼写属于**目标模型的适配器**(`max`、`xhigh`、`high`、…——此处不对任何适配器目录做校验)。存在时,spawn 侧(Task 工具与 plugin-loader 的 `AgentProvider`)把它 stamp 到 child 的 options 上,routes 服务的宿主 `agent/request` listener 会把它应用到该 child 的**每一个**请求上,覆盖任何从 fork 父 header 恢复的 effort。字符串形式 alias 无法携带 effort;`inherit` / 未配置 builtin 不 stamp 任何东西。目标模型不支持的 effort 会让请求以 `UNSUPPORTED_REASONING_EFFORT` 失败——有意 fail-loud。
68
+
69
+ ```jsonc
70
+ // settings 命名空间 "model-aliases"
71
+ {
72
+ "opus": { "provider": "orchestrix", "model": "glm-5.3", "reasoningEffort": "max" },
73
+ "sonnet": { "provider": "orchestrix", "model": "glm-5.3-flash", "reasoningEffort": "max" }
74
+ }
75
+ ```
76
+
77
+ 把 opus 的目标换成 effort 词表不同的模型,只需改这一条 settings(`"reasoningEffort": "xhigh"`);agent markdown 无需改动。
78
+
79
+ ### 空删除
80
+
81
+ 只有 **settings** 层可把条目置为 `null`;这会**整条删除同名 config-default 条目**(entry-shallow)。删除 *builtin* alias 仍落到 builtin fallback——`null` 无法让 `sonnet` 变成错误,因为 builtin fallback 是**继承父路由**。config 层永不允许 `null`(被 config schema 拒绝)。
82
+
83
+ ### Merge 规则
84
+
85
+ - **config vs settings 是 entry-shallow**:settings 条目整体替换 config 条目,绝不 field-merge `{provider, model}` 对象——因此 `config { provider: A, model: X }` + `settings { model: Y }` 得到 `{ model: Y }`,而不会是没有任何单层声明的混合 `{ provider: A, model: Y }`。
86
+ - **settings 5 级 cascade 内是递归深 merge**(既有 cascade 行为)。因此对象形式 alias 跨 settings 层必须**整写或完全不写**,否则 cascade 会像上面描述的那样 field-blend `{provider, model}`——这是本 package 不改变的 cascade 层行为。优先用字符串形式 alias,或在提及该 alias 的每一层重复完整路由。
87
+
88
+ ### Builtin fallback
89
+
90
+ **零配置**的全新安装也能工作:`model: sonnet` / `model: opus` / `model: draft` 的 agent 解析为*继承父的当前模型*(lane 未配置时跟随已配置的 CC 对标)而非报错。builtin 名(CC 家族 + dsh-cc lane)享受该 fallback;未配置的自定义 alias(`turbo`、`gpt`、…)**没有** fallback,原样透传(带上面的告警)。
91
+
92
+ ## `inherit` 修复说明
93
+
94
+ 本 package 之前,`model: inherit` 会一路原样当作字面 model id 传给 `prepareCall` 然后失败。在 CC 模式下,派发时解析器(来自 `ccModelRoutes` 服务,经 cc-shell trampoline 与 Task 工具消费)把 `inherit` 映射为「无 override」,child 因此继承父路由,符合 CC 语义。未挂载任何解析器时(`@dsh-cc/plugin-loader` 中不设置 `resolveModel` 的非 cc 消费者),行为与之前字节一致——包括旧的 `inherit` 透传——因为无解析器 fallback 被原样保留。CC preset 无条件挂载 cc-shell(以及 routes 服务),因此 CC 模式下该修复始终生效。
95
+
96
+ ## API
97
+
98
+ - `apply(ctx, config?)` / `name` — **cordis 插件入口**(插件 id `cc-model-routes`,另以 `applyRoutes` / `routesPluginName` 再导出)。挂载服务;config 形状为 `{ modelAliases?: Record<string, AliasTarget> }`(部署默认)。
99
+ - `ModelRoutes` — `ctx.get('ccModelRoutes')` 的值类型(`resolve(model): { provider?, model?, reasoningEffort? } | undefined`)。
100
+ - `overlayStampedEffort(resolved, stamped)` / `stampedEffortOf(options)` — 服务 `agent/request` listener 使用的宿主侧 effort overlay;为测试与宿主内嵌而导出。
101
+ - `mergeAliasMaps(config, settings)` — 带 `null` 删除与大小写不敏感 key 折叠的 entry-shallow merge;返回只含已配置 alias 的有效 `ReadonlyMap`。
102
+ - `createModelResolver(getAliases, { warn })` — 构建 `resolveModel` 闭包。`getAliases` 是**每次调用**求值的 thunk(liveness)。可选 `warn` 替换默认的 `console.warn`(用于未配置自定义 alias 告警)。
103
+ - `BUILTIN_ALIASES` — CC 家族(`fable`/`opus`/`sonnet`/`haiku`)加上 dsh-cc lane(`sketch`/`draft`/`blueprint`/`masterplan`/`architect`)。
104
+ - `LANE_PEERS` — 未配置 lane → CC 家族映射(`sketch→haiku`、`draft→sonnet`、`blueprint→opus`、`masterplan→fable`;`architect` 无对标)。
105
+ - `toAgentOptions(route)` — 丢弃 resolved route 中的 `undefined` 字段以保住按字段继承(绝不把 child 请求的字段写成 `undefined`);`undefined` 进 → `undefined` 出,全 `undefined` 的 route 收敛为 `undefined`(「无 override」)。由 Task、cc-plugin-loader、hooks bridge 与 memory recall 共享。
106
+ - `toOneShotRoute(route, parent?)` — 把 resolved alias 填成完整的 `{provider, model}` 二元组,供独立的 one-shot `ctx.llm.stream` 调用使用:alias 字段优先,缺失字段从 `parent` 继承;补不完整(继承后仍无 model)返回 `undefined`,调用方视为「未配置」。session-title overlay 与 WebFetch summarizer 使用。
107
+ - `ConfigAliasesSchema` / `SettingsAliasesSchema`(及其 record 形式)— config 层(无 `null`)与 settings 层(允许 `null`)的 schemastery schema,外加 `AliasTarget` / `ResolvedRoute` 类型。
108
+
109
+ ## dsh-cc lane
110
+
111
+ 五个额外 builtin 名与 Claude Code 家族并列,不是第二套 settings 命名空间。未配置时,除 `architect` 外每个 lane 跟随其 CC 对标,因此已经映射了 `haiku` 的部署不必再写一份 `sketch`:
112
+
113
+ | Lane | 角色 | 未配置时的对标 |
114
+ |---|---|---|
115
+ | `sketch` | 快速轻量执行 | `haiku` |
116
+ | `draft` | 日常均衡编码 | `sonnet` |
117
+ | `blueprint` | 深度推理 | `opus` |
118
+ | `masterplan` | 最强推理 | `fable` |
119
+ | `architect` | 规划与编排 | inherit(主线程) |
120
+
121
+ 已配置的字符串目标若指向另一个 alias,会**跟随一跳**(`sketch: haiku` 共用 haiku 的对象路由,含 `reasoningEffort`)。对象形式目标是具体路由,不作为名字再跟。第二跳不跟,因此 `sketch: draft` + `draft: haiku` 停在字面 `"haiku"`(防环)。
122
+
123
+ frontmatter 两套词都可以写(`model: opus` 或 `model: blueprint`)。后台分类器低价车道仍是 `resolve('haiku')` —— hooks 与 recall 不会改走 `sketch`。
124
+
125
+ ## 低价(small-fast)车道
126
+
127
+ 没有第二个 alias 名,也没有 `ANTHROPIC_SMALL_FAST_MODEL`。低价后台车道**就是**已配置的 `haiku` alias:需要小型独立 one-shot 分类器模型的消费者调用 `resolve('haiku')` —— 配置了 haiku 即其路由,未配置即继承父路由(builtin fallback)。当前消费者:hooks bridge(未写 `model:` 的 `prompt`/`agent` hook)、开启 `recallUseSmallFast: true` 的 memory recall、session-title overlay 与 WebFetch summarizer。
128
+
129
+ ## 非目标(在 parity matrix 中跟踪)
130
+
131
+ `/model` 交互命令、`ANTHROPIC_MODEL` / `ANTHROPIC_SMALL_FAST_MODEL` 环境变量、以及给主会话默认模型加 alias 仍是 follow-up。
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Convert a resolved alias route into spawn `agentOptions` (`toAgentOptions`)
3
+ * or a complete `{provider, model}` pair for an independent one-shot stream
4
+ * (`toOneShotRoute`). Spawn drops `undefined` fields so per-field inheritance
5
+ * survives; one-shots fill missing fields from a parent route and return
6
+ * `undefined` when the pair is still incomplete.
7
+ *
8
+ * @module @dsh-cc/model-aliases/agentOptions
9
+ */
10
+ import type { ResolvedRoute } from './types.ts';
11
+ /**
12
+ * Drop `undefined` fields from a resolved route so per-field inheritance
13
+ * survives (never set a field to `undefined` on the child request).
14
+ * `undefined` in → `undefined` out; an all-`undefined` route → `undefined`.
15
+ * @param route - the resolved route (or `undefined` for no override).
16
+ * @returns the `agentOptions` record, or `undefined` for no override.
17
+ */
18
+ export declare function toAgentOptions(route: ResolvedRoute | undefined): Record<string, string> | undefined;
19
+ export interface OneShotParentRoute {
20
+ readonly provider?: string;
21
+ readonly model?: string;
22
+ }
23
+ /**
24
+ * Fill a resolved alias into a complete `{provider, model}` pair for an
25
+ * independent `ctx.llm.stream` one-shot. Alias fields win; missing fields
26
+ * inherit from `parent`. Returns undefined when the resulting pair is
27
+ * incomplete (no model after inherit) — callers treat that as "unconfigured".
28
+ */
29
+ export declare function toOneShotRoute(route: ResolvedRoute | undefined, parent?: OneShotParentRoute): {
30
+ provider: string;
31
+ model: string;
32
+ } | undefined;
33
+ //# sourceMappingURL=agentOptions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agentOptions.d.ts","sourceRoot":"","sources":["../src/agentOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAQnG;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,MAAM,CAAC,EAAE,kBAAkB,GAC1B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOjD"}