mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
aa0ca6c836
core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow. Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
109 lines
4.8 KiB
Markdown
109 lines
4.8 KiB
Markdown
# 会话引用
|
||
|
||
[English](session-reference.md) | 中文
|
||
|
||
结构化的跨会话引用请求与准备后的消息上下文。[包契约](../../packages/context/session-reference) 负责规范 URI、当前表层投影、标签安全的 JSON 与字节保留、稳定错误和不可信的模型提示词。宿主适配器使用这些类型，而不会把各自 UI 的提及语法传入 agent（智能体）核心。
|
||
|
||
来源：[`packages/context/session-reference/src/types.ts`](../../packages/context/session-reference/src/types.ts)
|
||
|
||
## 输入与候选项
|
||
|
||
`SessionReferenceInput` 是与宿主无关的选择。id 具有权威性；label 是随快照携带的显示元数据。
|
||
|
||
```ts type-equiv
|
||
/** One source session selected by a host. */
|
||
interface SessionReferenceInput {
|
||
/** Opaque source session identity. */
|
||
sessionId: SessionId
|
||
/** Optional user-facing mention label. */
|
||
label?: string
|
||
}
|
||
```
|
||
|
||
`SessionReferenceCandidate` 是面向宿主的发现输出。存在最新会话标题时，它的 label 使用该标题；筛选仍只搜索 session id 和 cwd，绝不搜索 transcript（文本记录）。
|
||
|
||
```ts type-equiv
|
||
/** One host-facing candidate from exact session metadata. */
|
||
interface SessionReferenceCandidate {
|
||
/** Opaque source session identity. */
|
||
sessionId: SessionId
|
||
/** Latest log-backed title, falling back to the opaque session id. */
|
||
label: string
|
||
/** Source session working directory, when recorded. */
|
||
cwd?: string
|
||
/** Source session creation time in Unix epoch milliseconds. */
|
||
createdAt: number
|
||
}
|
||
```
|
||
|
||
## 准备后的消息
|
||
|
||
准备过程保留可读的当前消息内容，并最多返回一个聚合上下文。
|
||
|
||
```ts type-equiv
|
||
/** Direct message content and optional referenced-session context. */
|
||
interface PreparedReferencedMessage {
|
||
/** Readable message content after host mention tokens are removed. */
|
||
content: ContentBlock[]
|
||
/** Aggregated untrusted snapshot, absent when the message has no references. */
|
||
additionalContext?: UserMessage
|
||
}
|
||
```
|
||
|
||
## 错误
|
||
|
||
`SessionReferenceError.code` 区分无效配置或输入、自引用、数量限制、源读取失败、预算失败和取消。宿主协议会把这些 code 映射到各自的错误封装，无需检查提示词字节。
|
||
|
||
```ts type-equiv
|
||
/** Stable failure codes exposed to host adapters. */
|
||
type SessionReferenceErrorCode =
|
||
| 'SESSION_REFERENCE_INVALID_CONFIG'
|
||
| 'SESSION_REFERENCE_INVALID_REFERENCE'
|
||
| 'SESSION_REFERENCE_SELF_REFERENCE'
|
||
| 'SESSION_REFERENCE_TOO_MANY'
|
||
| 'SESSION_REFERENCE_READ_FAILED'
|
||
| 'SESSION_REFERENCE_BUDGET_EXCEEDED'
|
||
| 'SESSION_REFERENCE_CANCELLED'
|
||
```
|
||
|
||
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
|
||
|
||
<a id="cordis-surface"></a>
|
||
|
||
## Cordis surface
|
||
|
||
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
|
||
|
||
<a id="ctxsessionreferences--sessionreferenceservice"></a>
|
||
|
||
### `ctx.sessionReferences` — `SessionReferenceService`
|
||
|
||
Exact-read consumer that prepares immutable cross-session message context.
|
||
|
||
```ts cordis-catalog
|
||
/**
|
||
* List reference candidates, ranked by working-directory affinity.
|
||
* @param agent - target agent; self is excluded and its cwd drives ranking.
|
||
* @param query - optional case-insensitive session-id/cwd/title substring.
|
||
* @param limit - optional positive result cap.
|
||
* @param signal - optional cancellation boundary for host autocomplete teardown.
|
||
* @returns candidates labeled by latest title or, when absent, session id.
|
||
*/
|
||
async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
|
||
|
||
/**
|
||
* Snapshot all references before enqueue and return one aggregated durable context.
|
||
* @param agent - target agent; references to it are rejected.
|
||
* @param content - already host-normalized readable message content.
|
||
* @param references - structured source sessions in mention order.
|
||
* @param signal - optional cancellation boundary for host request teardown.
|
||
* @returns detached content and optional referenced-session context.
|
||
*/
|
||
async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>
|
||
```
|
||
|
||
Types: [Agent](core.md) · [ContentBlock](llm-streaming.md)
|
||
|
||
Source: [`packages/context/session-reference/src/index.ts:70`](../../packages/context/session-reference/src/index.ts)
|
||
<!-- END GENERATED cordis-surface -->
|