Yudong HanandLegGasai
fda98dadd2
* fix(web-search-deepseek): disable thinking for auxiliary search requests The provider discards the generated text of the auxiliary Messages turn, so reasoning tokens have no consumer. DeepSeek enables thinking by default, which adds latency and output tokens to every search. Fixes #6099. * feat(web): add opt-in traditional Search and Fetch APIs * test(web): verify API settings persistence and refresh Session evidence * fix(web): require an explicit Search API base with its route prefix * docs(web): document direct Search and Fetch API decisions * fix(web): keep Messages search default behind the new Web Search API switch - Rename useTraditionalApi/traditionalBaseURL to useSearchApi/searchApiBaseURL and label the switch "Use the new Web Search API"; Messages search stays the default. - Default the Search / Fetch API base to https://api.deepseek.com/v1/tools. - Authenticate the Search API with an API key only: DeepSeek Account tokens returned an empty HTTP 404 on /v1/tools/* when probed on 2026-10-16. - Remove the count setting, which tool-web's maxResults always overrides, and the undocumented DeepSeek-API-Version header. - Name the active API's base URL field and the current settings path in endpoint guidance; re-record the endpoint guidance Session. - Keep WebFetchResult.statusCode required: DeepSeek Fetch reports HTTP 200 and drops the page title, so the fetch-metadata widening and its upgrade guide are removed. * fix(web): accept account sign-in on the live Search API The public Search and Fetch routes went live on 2026-10-16 and accept the DeepSeek Account token, so account-route Sessions send it to the Search API as they do for Messages search, and the settings copy no longer says account sign-in does not apply. Record the live behavior in the README and Agent Note: summaries of 1,000-2,300 characters, an HTTP 500 for an unresolvable Fetch target, and migration notes for gateways without /v1/tools routes. Test doubles now use the live response fields and RFC 3339 offsets. * feat(web): configure Search API result count and send the triggering question - Add web-search-deepseek.count (1-50, default 10, the service default) and show it as "Results per search" in Search API mode, where "Max searches per request" applies only to Messages; a smaller request maxResults still wins. - Send the initiating Session's latest human prompt as ori_question, with whitespace collapsed and cut to the API's 128-character limit; blank or absent prompts omit it, and sendOriginalQuestion: false disables it. The settings hint states that the question is sent. - Match the web search double on the request's query field, since ori_question now carries every query in the prompt. * fix(client): unify web search endpoint override controls * feat(web): configure registered search and fetch providers through shared settings * feat(web): include Exa and Perplexity in provider settings * test(web): cover provider settings branches and refresh plugin snapshots * revert(web): drop the provider dropdown, schema-driven form, and Exa/Perplexity settings Revert aed8c5cb609, d88c47dcd80, and 036a5a337d3. The Web search settings page returns to the DeepSeek toggle; the DeepSeek Search and Fetch API split is reintroduced as one plugin in the following commit. * feat(web): move the DeepSeek Search and Fetch APIs into web-deepseek-api The new web-deepseek-api plugin registers deepseek-search-api and deepseek-fetch-api over one credential and API base, and exports the authentication and redirect-rejecting transport that web-search-deepseek now reuses for Messages search only. The web service reads searchProvider and fetchProvider for each operation, so the Web search settings switch selects both APIs together on save and restores Messages search with local HTTP fetch when turned off. The switch hint links to the DeepSeek search and fetch guide. * refactor(client): keep the web search endpoint fields on the shared override controls Drop the always-visible reset and the inherited-address placeholder from the Web search page, restoring ui-primitives to its base. Each endpoint field shows the selected section's effective value and offers Reset to default only for an override, like every other settings field. * refactor(web): keep Messages search independent of web-deepseek-api Restore dsh-web-search-deepseek to its own credential and transport code, keeping only the disabled-thinking request and the current settings guidance, so the Messages plugin no longer depends on the Search and Fetch API package. dsh-web-deepseek-api keeps its transport internal; the regions that repeat the Messages helpers carry jscpd:ignore markers, with the rationale recorded in the Search and Fetch API Agent Note. * refactor(web): keep the web-deepseek-api request type module-private --------- Co-authored-by: LegGasai <jyc132780208@sina.com>
description
| description |
|---|
| Review and maintain recorded Session persistence-type changes, their schema snapshots, and compatibility decisions. |
Persistence-type change records
English | 中文
Summary
Use this reference to inspect an acknowledged Session persistence-type change and its predecessor. Each record binds a compatibility decision to exact generated schemas. Local checks compare the current source with the recorded history using only files in the checkout. Start with the review cookbook when changing a persisted type.
For older tagged versions, use the prerelease archive. It reconstructs alpha/RC type differences for historical reading and format validation; its observations do not serve as current compatibility acknowledgements.
For complete schemas grouped by Session format, use the format references. Their coverage follows the writer constant, including intermediate formats without a release tag.
Table of Contents
Files and ownership
The generated catalog provides readable declarations and digests; the schema inventory contains the normalized types. Roots cover the logical Session header, the physical JSONL header line, the event envelope, and every repository-declared event. Referenced types contribute transitively to each affected root's digest.
Each dated record has four sibling files:
| File | Owner |
|---|---|
YYYY-MM-DD-slug.md |
English acknowledgement with kind: persistence-change, one machine declaration, compatibility reasoning, and verification evidence |
YYYY-MM-DD-slug.zh.md |
Chinese counterpart with the identical machine declaration |
YYYY-MM-DD-slug.i18n.yaml |
Generated bilingual consistency record |
YYYY-MM-DD-slug.schema.json |
Generated complete after schemas for the affected roots that remain present |
finalized/vN.json records the complete root classifications/digests of an accepted compatibility baseline and semantic hashes of its accepted records. The finalization record requires its checkpoint. Current V4 schemas may evolve compatibly; the checkpoint protects accepted machine declarations and after schemas even after the writer advances, while excluding prose, aliases, and source locations from record hashes.
A maintainer captures an agreed format with createPersistenceFinalizationCheckpoint, writes a new version-named checkpoint without replacing an earlier one, and advances the paired latestFinalizedVersion. The helper requires current schemas to match complete acknowledged history. Run the ordinary verifier before committing.
The record template defines the authored format. Record creation accepts a bilingual prose input and generates the machine declaration, snapshots, catalog pair, and consistency records. The verifier reads the machine declaration once from the English file and checks the Chinese declaration for equality. A declaration names each affected root, its predecessor record, its after digest, and its compatibility decision. A new root has no predecessor; a deletion has no after schema and retains an explicit tombstone.
Compatibility rules
Every detected structural change requires an acknowledgement. Keep the Session version when older readers preserve the required meaning of accepted data, safely ignore optional features while retaining opaque records, or refuse unsupported required data before execution, mutation, or recovery truncation. New readers must preserve historical meaning and readability. Bump only when unsafe interpretation cannot be prevented by an effective discriminator. Unknown fields or values count only when existing readers actually handle them safely; type differences alone cannot establish that behavior. See the reader-compatibility decision.
| Detected change | Recording requirement |
|---|---|
| Add an optional event-body property, including its complete subtree | same-version |
| Make a required event-body property optional | same-version |
| Add an ordinary event type | same-version |
Add a higher numeric data.version to an ordinary event while retaining every old payload alternative under the existing compatibility rules |
same-version |
| Add an explicitly qualified attribution kind to a user/developer source slot whose before and after schemas carry the same supported policy | same-version |
| Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | Compatibility review for same-version, or explicit version-bump |
| Change the Session header or event envelope | Compatibility review for same-version; a header version change requires version-bump |
The classifier identifies established same-version cases and changes requiring compatibility review; it cannot decide semantic safety. The latter require an explicit --decision same-version when recording or updating without a version increase. The acknowledgement’s Compatibility section explains actual reader behavior in both directions, and Verification records the executed checks. Review the complete transition, including simultaneous changes. An explicit version-bump instead requires its own increasing SessionHeader.version transition; a same-version decision cannot waive a header version change. Finalized records remain immutable, so a later record cannot reuse the accepted 3→4 transition.
The CLI requires that explicit choice before generating a flagged same-version record. CI reads the recorded decision: same-version and accepts it when the ordinary history, schema, and header-version constraints hold, whether the record was generated or edited manually. Verification cannot establish how the record was authored or whether a human reviewed it. Reviewers compare base and head inventories with persistence-review; --check validates current-tree consistency and cannot reveal a transition already covered by an acknowledgement.
An ordinary event may add payload alternatives with a required, nonnegative integer data.version greater than every existing payload version, provided every existing alternative remains readable under the established same-version rules above. Optional property additions and required-to-optional changes may accompany the new version; each retained alternative is compared separately. Other payload changes require compatibility review. Older readers may reject the new payload version. The catalog acknowledgement records one such transition.
The extractor accepts an explicit @persistenceSource binding for a core-owned source property on a literal user or developer role; it does not infer a binding from an unannotated type. A producer qualifies its MessageSourceMap entry with @persistenceAttribution. Qualification promises that an unknown kind and its JSON metadata survive reading without the producer, and that the kind imposes no validation, replay, or authority requirement. A producer may inspect its own kind to resume duplicate suppression; other readers must preserve and derive the recorded messages without that projection. The recorded schema retains the binding, policy version, literal kind discriminator, preservation promise, and qualified kind set. Inventory format 2 stores those promises; extraction without a bound policy retains format 1. Session format versions are independent. Both compared snapshots must carry compatible policy state. Existing kind groups still receive ordinary structural comparison; removals, unmarked additions, policy changes, and unrelated structural changes require compatibility review. Multiple context-form alternatives with the same wire kind form one group.
Every same-version explanation states how old records remain readable and how older readers handle new records, including established cases that need no explicit CLI decision. A feature absent from a log must retain the old behavior; dispensable features must be safe to ignore; required features need an effective refusal signal. Unsupported-feature refusal must not become corruption recovery or tail truncation. For required-to-optional changes, explain how readers handle an absent value. Reviewers assess behavior and evidence; the checker validates the declaration and type classification. A version-bump record follows the Session-format procedure.
When a reader rejects a JSON property by name, declare the property as optional never and mark it with argument-free @persistenceReserved. The extractor retains the forbidden field, so allowing a JSON value later requires an existing-field type change. Required or JSON-valued properties cannot carry this marker. Unmarked optional never and undefined properties retain their existing omission behavior.
History and limitations
One baseline records the complete initial inventory. Later records use their predecessor's after schema as the before schema. The verifier rejects missing predecessors, cycles, duplicate successors for one root, digest mismatches, and current roots that disagree with their latest records. Independent roots can advance independently. Two changes to the same predecessor require a single ordered history after integration.
Accepted records describe historical transitions; preserve their machine declarations and schema snapshots when adding a successor. An unaccepted terminal record can be refreshed explicitly; the command rejects baselines, records with dependants, and checkpoint-locked records before producing artifacts. Verification checks retained checkpoint hashes; it does not prove that the checkpoints and their authority record were never edited together. No Git ref, remote service, or released checkout supplies the baseline.
Digests describe declared persistence types, not runtime validation or behavior. Ordinary comments, source locations, alias names, and harmless declaration reordering do not affect them. Compatibility annotations are recorded policy data and do affect digests. Unannotated version-1 snapshots retain their original normalization and fingerprints; policy-bearing graphs use a separate fingerprint domain. Object fields, union alternatives, intersection operands, and index signatures can be reordered when their resolved types stay the same; tuple positions and numeric enum values remain significant. Catalog text and source locations may still change, so regenerate stale artifacts without adding an acknowledgement for an unchanged digest. Opaque types such as unknown expose no hidden structure to compare. Behavior-only changes and structures hidden inside opaque values are outside this mechanism's scope. The decision records these trade-offs.
Dev Note
Working context for maintainers — click to expand
None.