mward4/deepseek-harness
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 29 Wiki Activity

docs(agent): clarify model-selection behavior

Browse Source
This commit is contained in:
_Kerman committed 2026-10-16 10:16:18 +08:00
1 parent d16b547843
commit 150a0d0842
9 files changed
+24 -24
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/subsystems/core.i18n.yaml
+2 -2
View File
@@ -12,8 +12,8 @@
en: ab09a38b4e1f0883
zh: 81e2d14c4036ab6c
/core/the-agent-handle:
en: 863bfd7defdd9de6
zh: 389bd9a07c77bb77
en: 5a650b4ad53cf5ab
zh: b73a7dc00bcbe2a1
/core/initiating-agent:
en: 6c8c47ac78de2dde
zh: c9d527a25a85d1d9
docs/subsystems/core.md
+1 -1
View File
@@ -212,7 +212,7 @@ interface AgentOptions {
Step preparation requires `provider` and `model` before prompt assembly. The deprecated `agent/request` hook may change request controls but must preserve that route. An explicit `reasoningEffort` seeds the first request on that route; exact-model resolution validates it, while omission allows the adapter default to materialize. When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. An agent-scoped `deployment:persona-prefix` prompt section may shadow the global default persona.
The Agent registry registers `modelSelection` on `ctx.sessionProjections`. `model/selection` records a complete choice without entering model history. A matching request header clears `pending`; the latest request remains `lastUsed`. Adapter-defaulted effort is omitted so later requests resolve the default again. `next` is null only before either a choice or a request is recorded; in that case `AgentOptions` supplies the route. The [Agent package](../../packages/core/agent/README.md) describes selection helpers and resume policy.
The Agent registry registers `modelSelection` on `ctx.sessionProjections`. `model/selection` records a complete choice without entering model history. A matching request header clears `pending`; the latest request remains `lastUsed`. Adapter-defaulted effort is omitted so later requests resolve the default again. `next` is null only before either a choice or a request is recorded; in that case `AgentOptions` supplies the route. The [Agent package](../../packages/core/agent/README.md) describes selection precedence and resume policy.
```ts type-equiv
/** Complete provider, model, and optional reasoning effort chosen for one Session's model steps. */
docs/subsystems/core.zh.md
+1 -1
View File
@@ -216,7 +216,7 @@ interface AgentOptions {
步骤准备在提示词组装前要求 `provider` 与 `model` 都存在。已弃用的 `agent/request` hook 可以更改请求控制参数，但必须保留该路由。显式 `reasoningEffort` 会为该路由的首次请求提供初始值；确切模型解析会校验该值，省略时则允许填入适配器默认值。提供 `maxTokens` 时，它必须是正安全整数，并限制每次对话模型请求的输出；省略时，系统会在写入请求 header 前填入确切模型的适配器默认值，否则提供方行为保持不变。agent 作用域的 `deployment:persona-prefix` 提示词段落可以遮蔽全局默认 persona。
Agent 注册表在 `ctx.sessionProjections` 上注册 `modelSelection`。`model/selection` 记录完整选择，但不进入模型历史。匹配的请求头会清除 `pending`，最近请求仍保留为 `lastUsed`。适配器默认的推理强度会被省略，使后续请求重新解析默认值。只有尚未记录选择或请求时，`next` 才为 null，此时由 `AgentOptions` 提供路由。[Agent 包](../../packages/core/agent/README.zh.md)说明选择辅助函数与恢复策略。
Agent 注册表在 `ctx.sessionProjections` 上注册 `modelSelection`。`model/selection` 记录完整选择，但不进入模型历史。匹配的请求头会清除 `pending`，最近请求仍保留为 `lastUsed`。适配器默认的推理强度会被省略，使后续请求重新解析默认值。只有尚未记录选择或请求时，`next` 才为 null，此时由 `AgentOptions` 提供路由。[Agent 包](../../packages/core/agent/README.zh.md)说明选择优先级与恢复策略。
```ts type-equiv
/** Complete provider, model, and optional reasoning effort chosen for one Session's model steps. */
packages/core/agent-loop/README.i18n.yaml
+2 -2
View File
@@ -18,8 +18,8 @@
en: 35a960c0100a6aa4
zh: 438e133fb4c24a9e
/deepseek-ai-dsh-agent-loop/use-this-package/configure-declarative-agents:
en: 58e12d7081314a39
zh: 0810b151dbbf956d
en: 057e5f8b0090b1e2
zh: 1133bbcf54e495ed
/deepseek-ai-dsh-agent-loop/use-this-package/create-or-resume-agents-programmatically:
en: 82ec792637e8e57f
zh: e32f8ec5ee17afcf
packages/core/agent-loop/README.md
+1 -1
View File
@@ -48,7 +48,7 @@ Agents declared in config start automatically when the plugin loads. Each entry
| `maxParallelToolCalls` | `10` | Parallel-safe tool calls in flight per step; `1` is serial |
| `agents[].id` | required | Stable label; a fresh session mints `${id}-session-<uuid>` unless `sessionId` is set |
| `agents[].provider` / `agents[].model` | — | Model route; both required before step preparation |
| `agents[].reasoningEffort` | — | Non-empty initial reasoning effort; later choices use `recordModelSelection()` |
| `agents[].reasoningEffort` | — | Non-empty initial reasoning effort; later choices are recorded in the Session |
| `agents[].maxTokens` | — | Positive per-request output-token cap |
| `agents[].cwd` | — | Workspace directory for a fresh session |
| `agents[].sessionId` | — | Exact identity: first use creates, a remount resumes materialized history |
packages/core/agent-loop/README.zh.md
+1 -1
View File
@@ -48,7 +48,7 @@ kind: "package-reference"
| `maxParallelToolCalls` | `10` | 每个步骤同时在途的并行安全工具调用数；`1` 为串行 |
| `agents[].id` | 必填 | 稳定标签；未设置 `sessionId` 时，全新会话会生成 `${id}-session-<uuid>` |
| `agents[].provider` / `agents[].model` | — | 模型路由；步骤准备前两者都必须存在 |
| `agents[].reasoningEffort` | — | 非空的初始推理强度；后续选择使用 `recordModelSelection()` |
| `agents[].reasoningEffort` | — | 非空的初始推理强度；后续选择记录在 Session 中 |
| `agents[].maxTokens` | — | 正数的逐请求输出 token 上限 |
| `agents[].cwd` | — | 全新会话的工作目录 |
| `agents[].sessionId` | — | 确切身份：首次使用创建，重新挂载时恢复已实体化的历史 |
packages/core/agent/README.i18n.yaml
+8 -8
View File
@@ -18,8 +18,8 @@
en: 326904be67f43b86
zh: e143c7d9e1f30bc0
/deepseek-ai-dsh-agent/use-this-package/create-or-resume-an-agent:
en: a11f471882357617
zh: 2158cd792d283c7d
en: adb806cfe9e2e0a4
zh: 8da57f9e62869523
/deepseek-ai-dsh-agent/use-this-package/drive-an-agent-s-conversation:
en: 71e258897e2e7d73
zh: abf0991012faa17e
@@ -27,8 +27,8 @@
en: 2594a1e02adea801
zh: cae8860369728efb
/deepseek-ai-dsh-agent/use-this-package/intercept-or-observe-work-in-flight:
en: 8019485edab3d0d4
zh: 12421a5775a419a6
en: ae14e4c604211d42
zh: 208018c2d017d5ca
/deepseek-ai-dsh-agent/understand-the-implementation:
en: ce7e776e9d516bdb
zh: 59d2751743db7795
@@ -42,8 +42,8 @@
en: f6802c7f94f623b3
zh: cc3885db80765970
/deepseek-ai-dsh-agent/understand-the-implementation/source-map:
en: d88de2a182691dbb
zh: 837d4454f1d7dea0
en: 5385d7a8618df0eb
zh: 35853b9d1a1406f1
/deepseek-ai-dsh-agent/understand-the-implementation/registry-and-lifecycle:
en: df92e97cedd0d02e
zh: f6040c145bffd933
@@ -63,8 +63,8 @@
en: 962c598672b0eed6
zh: d05b3bc936685ad3
/deepseek-ai-dsh-agent/model-experience/user-steering-and-injected-messages/what-the-model-sees:
en: 9703263d210e6246
zh: c5568c930f10fab5
en: b32fa34babcb4ac4
zh: 8bbdabbf2b0a21e1
/deepseek-ai-dsh-agent/model-experience/user-steering-and-injected-messages/token-effect:
en: 5f428bfadaf4394b
zh: 03308df9fd3492a7
packages/core/agent/README.md
+4 -4
View File
@@ -42,7 +42,7 @@ await handle.dispose() // stops the loop, unregisters, removes the session, un
`AgentOptions` supplies the initial provider/model route, optional adapter-owned `reasoningEffort`, and optional positive `maxTokens` output cap. The loop validates exact-model reasoning support, resolves adapter defaults, records the effective values in the request header, and applies them to each conversation request. An optional `setup(agentCtx, agent)` callback composes the agent's scoped world before it is published: `agentCtx` owns registrations, while the explicit unpublished Agent provides its Session; the Context has no reverse Agent property. Scoped tools, prompt sections, and listeners exist before any creation announcement. Setup is composition-only: drive the agent only after creation resolves.
A Session's recorded model selection takes precedence over its latest request route, which takes precedence over `AgentOptions`. Call `recordModelSelection(ctx.sessionProjections, agent, selection)` after validating a new choice; it appends `model/selection` unless the same choice is already recorded. An explicit choice equal to the options fallback is still recorded. `currentModelSelection()` reads this shared state without a separate mutable cache. Resume preserves the recorded choice; deployments that intentionally replace it call `recordDeclaredRoute()` during setup. That helper retains explicit reasoning effort only for the same route, while adapter-defaulted effort is resolved again.
A Session's recorded model selection takes precedence over its latest request route, which takes precedence over `AgentOptions`. Validated choices are stored as `model/selection` events unless the same choice is already recorded; an explicit choice equal to the options fallback is still recorded. Selection reads use the shared projection without a separate mutable cache. Programmatic resume preserves the recorded choice. A deployment can override the route during setup; when its configuration omits reasoning effort, the override retains saved explicit effort only for the same route. Adapter-defaulted effort is resolved again.
### Drive an agent's conversation
@@ -66,7 +66,7 @@ await handle.agent.whenIdle()
### Intercept or observe work in flight
`agent/request` is deprecated and retained for existing listeners. Do not add new listeners. Use `recordModelSelection()` before step preparation for provider, model, and reasoning effort, and `AgentOptions.maxTokens` for the output cap. Other per-request control overrides have no replacement API.
`agent/request` is deprecated and retained for existing listeners. Do not add new listeners. Provider, model, and reasoning effort are selected before step preparation; `AgentOptions.maxTokens` sets the output cap. Other per-request control overrides have no replacement API. See the [migration guide](../../../docs/upgrade-guide/v0.2.1-alpha.3/session-model-selection/guide.md) for affected callers.
The `agent/*` events let plugins act on live work without depending on the loop package. `agent/pre-step` can reject a proposed step or replace the messages entering it; `agent/request-error` lets a listener retry a failed model request; `agent/turn-stopping` runs before an otherwise completed turn closes and can steer to keep it open. `agent/assistant-stream` carries one process-local Assistant attempt's ordered start, transient chunk, and end frames. Start names the attempt's turn and step, chunk indexes are dense from zero, and `end.index` is the next chunk position. The loop commits the complete compact stream as one `assistant/message` or `assistant/attempt` before a committed end frame, so the live event remains presentation data rather than the replay source. `agent/status`, `agent/created`, and `agent/disposed` drive UI and coordination state, and the per-message `agent/inbox/*` notifications keep inbox projections in sync. Exact signatures, dispatch modes, and payload contracts live in the generated region of the [core subsystem page](../../../docs/subsystems/core.md#cordis-surface).
@@ -103,7 +103,7 @@ The package is built on one separation: the public `Agent` surface and registry
| [`src/types.ts`](src/types.ts) | `AgentOptions`, cancellation causes, and inbox projection vocabulary |
| [`src/dispatch.ts`](src/dispatch.ts) | `agentEvents` fused dispatcher and `assembleContextFor(agent)` |
| [`src/consumed-work.ts`](src/consumed-work.ts) | `foldConsumedWork(events)`: what the log's consumed work became |
| [`src/model-selection.ts`](src/model-selection.ts) | Durable model-selection fold, read/write helpers, and optional switch notices |
| [`src/model-selection.ts`](src/model-selection.ts) | Session model-selection state and optional switch notices |
| [`src/archive-admission.ts`](src/archive-admission.ts) | The `turn` family of the Workspace registry's archive admission: a running turn and its user-cause cancel |
### Registry and lifecycle
@@ -144,7 +144,7 @@ The package-level contract is enough for most consumers; read these when you nee
#### What the model sees
`followup`, `steer`, and `inject` feed the owning session as identified user-role messages; accepted content becomes part of the derived history the model reads on later steps. `agent/pre-step` and the other declared events let plugins reject a proposed step or add durable request material. `installModelSwitchNotice` adds `[model changed: assistant turns above this point were generated by <previous>; the session continues with <next>]` to the first step assembled for a different provider/model route that would send a model request; provider names appear only when the switch crosses providers, and reasoning-effort-only changes add nothing. An empty first decision and a decision that removes offered messages remain no-request results. If a request step fails before logging its header, the next request step receives the notice again because the durable previous route has not changed.
`followup`, `steer`, and `inject` feed the owning session as identified user-role messages; accepted content becomes part of the derived history the model reads on later steps. `agent/pre-step` and the other declared events let plugins reject a proposed step or add durable request material. When model-switch notices are enabled, the first step assembled for a different provider/model route that would send a model request receives `[model changed: assistant turns above this point were generated by <previous>; the session continues with <next>]`; provider names appear only when the switch crosses providers, and reasoning-effort-only changes add nothing. An empty first decision and a decision that removes offered messages remain no-request results. If a request step fails before logging its header, the next request step receives the notice again because the durable previous route has not changed.
#### Token effect
packages/core/agent/README.zh.md
+4 -4
View File
@@ -42,7 +42,7 @@ await handle.dispose() // stops the loop, unregisters, removes the session, un
`AgentOptions` 提供初始提供方／模型路由、可选的由适配器定义的 `reasoningEffort`，以及可选的正数 `maxTokens` 输出上限。循环会校验确切模型的推理（reasoning）支持、解析适配器默认值、把生效值记录在请求头中，并将它们应用到每个对话请求。可选的 `setup(agentCtx, agent)` 回调会在 agent 发布之前组合其作用域世界：`agentCtx` 拥有注册，显式的未发布 Agent 则提供其 Session；Context 不含反向 Agent 属性。作用域工具、提示词段与监听器在任何创建公告之前就已存在。Setup 只做组合：创建完成后才能驱动 agent。
Session 中记录的模型选择优先于最近请求的路由，最近请求的路由又优先于 `AgentOptions`。校验新选择后调用 `recordModelSelection(ctx.sessionProjections, agent, selection)`；除非记录中已有相同选择，否则它会追加 `model/selection`。与 options 回退值相同的显式选择仍会记录。`currentModelSelection()` 读取这份共享状态，不使用独立的可变缓存。恢复保留记录中的选择；需要有意覆盖它的部署在 setup 期间调用 `recordDeclaredRoute()`。该辅助函数仅在路由相同时保留显式推理强度，适配器默认的强度则重新解析。
Session 中记录的模型选择优先于最近请求的路由，最近请求的路由又优先于 `AgentOptions`。校验后的选择以 `model/selection` 事件保存，记录中已有相同选择时不重复写入；与 options 回退值相同的显式选择仍会记录。选择读取使用共享投影，不使用独立的可变缓存。程序化恢复保留记录中的选择。部署可以在 setup 期间覆盖路由；配置省略推理强度时，仅在路由相同的情况下保留已保存的显式强度。适配器默认的强度会重新解析。
### 驱动 agent 的对话
@@ -66,7 +66,7 @@ await handle.agent.whenIdle()
### 拦截或观察进行中的工作
`agent/request` 已弃用，仅为现有监听器保留。不要添加新监听器。在步骤准备前使用 `recordModelSelection()` 设置提供方、模型和推理强度，通过 `AgentOptions.maxTokens` 设置输出上限。其他逐请求控制参数覆盖没有替代 API。
`agent/request` 已弃用，仅为现有监听器保留。不要添加新监听器。提供方、模型和推理强度在步骤准备前选定；`AgentOptions.maxTokens` 设置输出上限。其他逐请求控制参数覆盖没有替代 API。受影响的调用方参见[迁移指南](../../../docs/upgrade-guide/v0.2.1-alpha.3/session-model-selection/guide.zh.md)。
`agent/*` 事件让插件无需依赖循环包即可作用于实时工作。`agent/pre-step` 可以拒绝拟进入的步骤或替换进入它的消息；`agent/request-error` 让监听器重试失败的模型请求；`agent/turn-stopping` 在本可完成的轮次关闭前运行，并可通过 steer 使其保持打开。`agent/assistant-stream` 携带一个进程本地 Assistant attempt 的有序 start、瞬态分片与 end frame。start 给出该 attempt 的轮次与步骤，分片索引从零开始密集递增，`end.index` 则是下一个分片位置。loop 会在 committed end frame 前把完整紧凑流提交为一个 `assistant/message` 或 `assistant/attempt`，因此实时事件仍是呈现数据而非回放来源。`agent/status`、`agent/created` 与 `agent/disposed` 驱动 UI 与协调状态，逐消息的 `agent/inbox/*` 通知则让收件箱投影保持同步。确切签名、分发 mode 与 payload 约定见 [core 子系统页](../../../docs/subsystems/core.zh.md#cordis-surface) 的生成区块。
@@ -103,7 +103,7 @@ await handle.agent.whenIdle()
| [`src/types.ts`](src/types.ts) | `AgentOptions`、取消原因与收件箱投影词汇 |
| [`src/dispatch.ts`](src/dispatch.ts) | `agentEvents` 融合分发器与 `assembleContextFor(agent)` |
| [`src/consumed-work.ts`](src/consumed-work.ts) | `foldConsumedWork(events)`：日志消费掉的工作最终怎样了 |
| [`src/model-selection.ts`](src/model-selection.ts) | 持久模型选择归约、读写辅助函数及可选切换提示 |
| [`src/model-selection.ts`](src/model-selection.ts) | Session 模型选择状态与可选切换提示 |
| [`src/archive-admission.ts`](src/archive-admission.ts) | Workspace 注册表归档准入中的 `turn` 族：运行中的回合及其用户原因取消 |
### 注册表与生命周期
@@ -144,7 +144,7 @@ await handle.agent.whenIdle()
#### 模型看到什么
`followup`、`steer` 与 `inject` 以带标识的 user 角色消息馈送所属会话；被接纳的内容成为模型在后续步骤中读取的派生历史的一部分。`agent/pre-step` 与其他已声明事件让插件能够拒绝拟进入的步骤或添加持久请求材料。`installModelSwitchNotice` 会在首次为不同提供方／模型路由组装且原本会发出模型请求的步骤中加入 `[model changed: assistant turns above this point were generated by <previous>; the session continues with <next>]`；仅跨提供方切换时显示提供方名称，只改变推理强度时不添加消息。第一个决策为空时，以及某个决策移除候选消息后为空时，都不会产生请求。如果请求步骤在记录请求头前失败，持久记录中的先前路由没有变化，所以下一个请求步骤会再次收到提示。
`followup`、`steer` 与 `inject` 以带标识的 user 角色消息馈送所属会话；被接纳的内容成为模型在后续步骤中读取的派生历史的一部分。`agent/pre-step` 与其他已声明事件让插件能够拒绝拟进入的步骤或添加持久请求材料。启用模型切换提示时，首次为不同提供方／模型路由组装且原本会发出模型请求的步骤会收到 `[model changed: assistant turns above this point were generated by <previous>; the session continues with <next>]`；仅跨提供方切换时显示提供方名称，只改变推理强度时不添加消息。第一个决策为空时，以及某个决策移除候选消息后为空时，都不会产生请求。如果请求步骤在记录请求头前失败，持久记录中的先前路由没有变化，所以下一个请求步骤会再次收到提示。
#### Token 影响