docs: apply hierarchy across the corpus
This commit is contained in:
Turtle
@@ -68,80 +68,31 @@ Waterfalls are around-middleware: listeners delegate with `next()`; returning wi
|
||||
|
||||
## Default Loop Lifecycle
|
||||
|
||||
A **session** is append-only. An ordinary **turn** claims one queued `send()` item; injection claims none. A successor awaits its predecessor's checkpoint but may share its `running` interval ([decision](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)). A turn ends when model or plugins stop it; a **step** is one model request plus tools. Quotes in the [sequence below](agent-lifecycle.md) mark durable events.
|
||||
|
||||
Creation without an id mints `<config-id>-session-<uuid>`; `sessionId` resumes or creates, while `resumeSessionId` requires history. Resume restores lineage and delegation depth before publication. Setup failures emit `agent-loop/config-start-failed`; teardown is silent.
|
||||
A **session** is append-only. An ordinary **turn** claims one queued `send()` item; injection claims none. A turn ends when the model or plugins stop it; a **step** is one model request plus its tool calls. Agent and session publication happen only after private setup and resume state are ready.
|
||||
|
||||
### Turn Flow
|
||||
|
||||
```text
|
||||
choose declarative identity and fresh/resume path
|
||||
-> prepare private session + agent.ctx -> await unpublished setup -> invoke optional synchronous setup commit
|
||||
-> enter session + agent -> session/created -> agent/created
|
||||
-> enable driving -> agent/session-start(source) -> start driver
|
||||
forever:
|
||||
wait for queued occurrence
|
||||
claim (edit/remove end) -> emit agent/status(running) if starting an interval
|
||||
open the next-step acceptance window
|
||||
-> agent/prompt-submit
|
||||
blocked or failed prompt -> close the window without opening a turn
|
||||
append a context-only caller batch immediately
|
||||
keep steering and context staged beside it pending for a later admitted turn
|
||||
allowed prompt:
|
||||
'turn/start'
|
||||
append prompt + additional contexts as separate 'user/message' events
|
||||
STEP loop:
|
||||
agent/step
|
||||
assemble system prompt and tools
|
||||
materialize changed runtime context as sourced 'user/message'
|
||||
drain injected context and provisional steering (steering bypasses prompt-submit)
|
||||
snapshot the derived messages (the reconstruction boundary)
|
||||
'step/start'
|
||||
admit the drained steering receipts
|
||||
agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
|
||||
'assistant/chunk'
|
||||
'assistant/message'
|
||||
schedule tool calls by ctx.tools.executionMode:
|
||||
exclusive -> barrier
|
||||
parallel -> rolling pool, <= maxParallelToolCalls; reclassify-at-start; scheduler failure -> stop starts, drain dispatches
|
||||
start -> 'tool/call' -> ordered tools/pre-execute -> concurrent tools/execute
|
||||
model-order result -> ordered tools/post-execute -> 'tool/result'
|
||||
drain accepted tool context after all results; keep steering provisional
|
||||
'step/end'
|
||||
continue for tools or steering unless a result concluded the turn and rejects pending steering
|
||||
otherwise agent/turn-stopping -> drain context -> continue only for steering
|
||||
close the next-step acceptance window
|
||||
'turn/end' -> agent/settled
|
||||
start the next waking queued message, or emit agent/status(idle)
|
||||
queued input -> prompt admission -> turn/start
|
||||
-> [agent/step -> request -> chunks/message -> tools -> step/end]*
|
||||
-> turn/end
|
||||
|
||||
idle inject:
|
||||
append 'user/message'
|
||||
do not open a turn or run the model
|
||||
idle injection -> user/message
|
||||
```
|
||||
|
||||
Each step assembles ordered stable system sections, cache-safe dynamic contexts, tool schemas, and variables; unknown references fail the turn. `dsh-system-prompt` owns identity and persona; the loop supplies `provider`, `model`, and `cwd` ([prompt ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)).
|
||||
|
||||
Admission-time and active-turn `inject()` stage for the next step; tool-time injection and post-tool `additionalContexts` settle after results. Steering shares the outbox but remains provisional until a request admits it. `steer()` returns a message-owned receipt: after `agent/step` and asynchronous prompt assembly succeed, the loop commits the stable batch, snapshots request history, opens `step/start`, then resolves its receipts as admitted with the turn and step; later arrivals wait. A turn-concluding tool result, broad cancellation, disposal, or a claimed idle-steering turn that never opens a step rejects affected receipts, while `cancel(..., { keepInbox: true })` and non-terminal routing preserve pending delivery. Idle `inject()` appends immediately without changing turn numbers; persistence drains eagerly.
|
||||
|
||||
Before driver claim, `updateInbox()` may edit or remove a queued occurrence, or strictly transfer its immutable message into an open next-step window. That transfer ends the queued occurrence and accepts a new steering occurrence; a closed window leaves Queue unchanged. Direct `steer()` remains best-effort for newly submitted input and falls back to a waking follow-up outside the window ([decision](../.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.md)).
|
||||
|
||||
Pruning precedes summaries; overflow retries require durable progress. `agent/request-error` may authorize one retry turn between failed-step and turn close; cancellation wins. Adapter-owned `retryPolicy` makes normal mode bounded; always mode delegates specialized recovery before retrying until success or cancellation ([compaction](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md), [retry foundation](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md), [provider policy](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)).
|
||||
Each step assembles the prompt, tools, runtime context, adapter settings, and model history before recording its reconstruction boundary. Tool calls then run through the shared execution pipeline. `inject()` adds context without opening an idle turn; `steer()` targets a next-step admission window; queued input remains the source of ordinary turns. The generated [agent lifecycle](agent-lifecycle.md) owns exact event order, and the [agent-loop README](../packages/core/agent-loop/README.md) owns queue, steering, retry, and cancellation mechanics.
|
||||
|
||||
### Failure Boundaries
|
||||
|
||||
Adapter failures close their step before `agent/request-error` receives the exact `Error`, normalized `LlmFailure`, and signal. A handled failure closes its turn and opens a retry turn from durable history without an idle notification; exhaustion leaves terminal `turn/end`. Failed chunks commit neither messages nor tool calls.
|
||||
|
||||
Other failures use `agent/error`. Cancellation and disposal beat recovery. Before request-header commit, the turn signal cancels asynchronous model-capability preparation; undispatched tools get synthetic `tool/call`/`ABORTED_BEFORE_DISPATCH` pairs. Effective `cancel(cause)` emits its cause before queue clearing and abort; observers cannot veto; idle calls emit nothing. Durability records user or parent cancellation as `aborted`, teardown as `disposed`; teardown awaits quiescence. The cause affects reporting, not late result-context handling ([decision](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)).
|
||||
|
||||
Turn and step events are turn-enclosed. Idle `user/message` and standalone `compact/* { turn: null }` consume no turn; their lock-time markers may interleave with injection. Reload synthesizes interrupted turn ends; `session/end-seed` distinguishes stale compaction orphans from live locks. After close, only `agent/error` reports failures. Each turn has one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap).
|
||||
Adapter failures close their step before `agent/request-error` can authorize recovery from durable history. Other failures use `agent/error`; cancellation and disposal take precedence over recovery. Failed model attempts commit no assistant message or tool side effect. Turn closure is represented by one [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap); the exact retry contract belongs to [LLM streaming](core-data-structures/llm-streaming.md).
|
||||
|
||||
### Agent Handles
|
||||
|
||||
`ctx.agents` owns agents, returning `AgentHandle { agent, dispose() }`. Plugins use `send()` or `followup()`, receipt-bearing `steer()`, and `inject()` presets; [`reserveTurnAdmission()`](../packages/core/agent/README.md#agent-interface-typests) synchronously reserves idle for durable work without changing queued prompt identity. Await a steering receipt when request admission matters; best-effort UI steering may ignore it. `cancel()` and `whenIdle()` control lifecycle. Caller, factory, and consumer co-own teardown through one awaited disposer.
|
||||
`ctx.agents` owns agents and returns `AgentHandle { agent, dispose() }`. Plugins submit queued work, steering, or injected context through the [agent interface](../packages/core/agent/README.md#agent-interface-typests); cancellation, idleness, and teardown stay behind the same handle.
|
||||
|
||||
### Agent Scope
|
||||
|
||||
Each agent owns scoped `agent.ctx`; shared storage overlays its tool, prompt, and command entries on globals while preserving domain views ([decision](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)). Scoped listeners filter dispatch; contributions unwind with awaited cleanup. `CreateAgentOptions.setup(agentCtx)` composes before publication and may return a synchronous commit that the factory invokes immediately before registry entry, after every setup await. Typed resolvers derive carrier checks from merged `Events` and `scopeTarget` ([semantic gates](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). Details: [agent scope](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md), [subagent composition](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md). `AgentLoop` runs under `ctx.agents.withInitiator()`; private orchestration derives `agent.session`, but turn, step, signal, cwd, and authority stay explicit ([decision](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
|
||||
Each agent owns scoped `agent.ctx`; shared storage overlays its tools, prompts, and commands on global contributions while scoped listeners filter dispatch. Setup composes before publication and cleanup unwinds contributions. The [agent-scope decision](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md) owns the detailed lifecycle.
|
||||
|
||||
## State
|
||||
|
||||
|
||||
@@ -68,80 +68,31 @@ waterfall（瀑布式事件）是环绕中间件：监听器通过 `next()` 委
|
||||
|
||||
## 默认循环生命周期
|
||||
|
||||
**会话**采用仅追加方式。普通**轮次**领取一项已排队的 `send()` 输入；注入不领取输入。后续轮次会等待前一轮次的检查点，但可以与其共用同一个 `running` 区间（[决策](../.agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md)）。模型或插件停止轮次时，该轮次结束；一个**步骤**包含一次模型请求及其工具。[下文时序](agent-lifecycle.md)中的引号标记持久事件。
|
||||
|
||||
创建时若未提供 id，流程会生成 `<config-id>-session-<uuid>`；`sessionId` 用于恢复或创建会话，而 `resumeSessionId` 要求已有历史。恢复流程在发布前还原沿袭关系和委托深度。初始化失败会发出 `agent-loop/config-start-failed`；拆卸过程保持静默。
|
||||
**会话**仅追加。普通**轮次**认领一个排队的 `send()` 项；注入不会认领。轮次在模型或插件停止时结束；一个**步骤**由一次模型请求及其工具调用组成。只有私有设置和恢复状态准备完毕后，系统才会发布 agent 与会话。
|
||||
|
||||
### 轮次流程
|
||||
|
||||
```text
|
||||
choose declarative identity and fresh/resume path
|
||||
-> prepare private session + agent.ctx -> await unpublished setup -> invoke optional synchronous setup commit
|
||||
-> enter session + agent -> session/created -> agent/created
|
||||
-> enable driving -> agent/session-start(source) -> start driver
|
||||
forever:
|
||||
wait for queued occurrence
|
||||
claim (edit/remove end) -> emit agent/status(running) if starting an interval
|
||||
open the next-step acceptance window
|
||||
-> agent/prompt-submit
|
||||
blocked or failed prompt -> close the window without opening a turn
|
||||
append a context-only caller batch immediately
|
||||
keep steering and context staged beside it pending for a later admitted turn
|
||||
allowed prompt:
|
||||
'turn/start'
|
||||
append prompt + additional contexts as separate 'user/message' events
|
||||
STEP loop:
|
||||
agent/step
|
||||
assemble system prompt and tools
|
||||
materialize changed runtime context as sourced 'user/message'
|
||||
drain injected context and provisional steering (steering bypasses prompt-submit)
|
||||
snapshot the derived messages (the reconstruction boundary)
|
||||
'step/start'
|
||||
admit the drained steering receipts
|
||||
agent/request (config only) -> prepare adapter defaults/provenance + context capacity under turn signal -> log request/header (+ request/context on route change) -> llm/stream (frozen, registration-bound)
|
||||
'assistant/chunk'
|
||||
'assistant/message'
|
||||
schedule tool calls by ctx.tools.executionMode:
|
||||
exclusive -> barrier
|
||||
parallel -> rolling pool, <= maxParallelToolCalls; reclassify-at-start; scheduler failure -> stop starts, drain dispatches
|
||||
start -> 'tool/call' -> ordered tools/pre-execute -> concurrent tools/execute
|
||||
model-order result -> ordered tools/post-execute -> 'tool/result'
|
||||
drain accepted tool context after all results; keep steering provisional
|
||||
'step/end'
|
||||
continue for tools or steering unless a result concluded the turn and rejects pending steering
|
||||
otherwise agent/turn-stopping -> drain context -> continue only for steering
|
||||
close the next-step acceptance window
|
||||
'turn/end' -> agent/settled
|
||||
start the next waking queued message, or emit agent/status(idle)
|
||||
queued input -> prompt admission -> turn/start
|
||||
-> [agent/step -> request -> chunks/message -> tools -> step/end]*
|
||||
-> turn/end
|
||||
|
||||
idle inject:
|
||||
append 'user/message'
|
||||
do not open a turn or run the model
|
||||
idle injection -> user/message
|
||||
```
|
||||
|
||||
每个步骤都会组装有序的稳定系统提示词片段、缓存安全的动态上下文、工具 schema 和变量；未知引用会使该轮次失败。`dsh-system-prompt` 负责身份和角色设定；循环提供 `provider`、`model` 和 `cwd`（[提示词归属](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)）。
|
||||
|
||||
接纳期间和活跃轮次内的 `inject()` 会为下一步骤暂存；工具执行期间的注入和工具执行后的 `additionalContexts` 会在结果记录完毕后落定。steering 与其共用 outbox，但在请求接纳前始终处于待准入状态。`steer()` 会返回归属于该消息的回执：`agent/step` 和异步提示词组装成功后，循环提交稳定批次、捕获请求历史并开启 `step/start`，再将其回执解析为已准入并附带轮次与步骤；后续消息继续等待。结束轮次的工具结果、广义取消、dispose（资源释放），以及已领取 idle-steering 消息却从未开启步骤的轮次，都会拒绝受影响的回执；`cancel(..., { keepInbox: true })` 和非终止型路由则保留待处理投递。空闲状态下的 `inject()` 会立即追加，且不改变轮次编号；持久化层会尽快排空。
|
||||
|
||||
驱动器认领之前，`updateInbox()` 可以编辑或移除 queued 单次入队项，也可以严格地把其不可变消息转移到开放的 next-step 窗口。该转移会结束 queued 单次入队项，并接受一个新的 steering 单次入队项；窗口关闭时 Queue 保持不变。直接调用 `steer()` 时，对新提交的输入仍采用尽力而为的语义，并在窗口之外回退为会唤醒 agent 的后续轮次（[决策](../.agents/notes/implemented/feature/2026-07-30-web-queue-steer-action.md)）。
|
||||
|
||||
裁剪先于摘要；溢出重试必须取得持久进展。`agent/request-error` 可以在失败步骤与轮次关闭之间授权一个重试轮次；取消优先。适配器拥有的 `retryPolicy` 使 normal mode 保持有界；always mode 先委托专门恢复，再持续重试直至成功或取消（[压缩](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)、[重试基础](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)、[提供方策略](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)）。
|
||||
每个步骤都会组装提示词、工具、运行时上下文、适配器设置和模型历史，随后记录其重建边界。之后，工具调用通过共享执行流水线运行。`inject()` 添加上下文但不打开空闲轮次；`steer()` 针对下一步骤的准入窗口；排队输入仍是普通轮次的来源。精确事件顺序由生成的 [agent 生命周期](agent-lifecycle.md)定义；队列、steering、重试与取消机制由 [agent-loop README](../packages/core/agent-loop/README.md)定义。
|
||||
|
||||
### 失败边界
|
||||
|
||||
适配器故障会先关闭自身步骤，再由 `agent/request-error` 接收准确的 `Error`、标准化的 `LlmFailure` 和信号。已处理的失败会关闭所在轮次，并从持久历史开启重试轮次，不发出空闲通知；重试耗尽则留下终态 `turn/end`。失败分片既不提交消息，也不提交工具调用。
|
||||
|
||||
其他故障使用 `agent/error`。取消和资源释放优先于恢复。在提交请求头之前，轮次信号会取消异步模型能力准备；尚未分派的工具会得到合成的 `tool/call`/`ABORTED_BEFORE_DISPATCH` 对。实际生效的 `cancel(cause)` 在清空队列和中止前发出原因；观察方不能否决；空闲调用不发事件。持久化层将用户或父级取消记录为 `aborted`，拆卸记录为 `disposed`；拆卸会等待完全停稳。原因只影响报告方式，不影响延迟完成的结果上下文处理（[决策](../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md)）。
|
||||
|
||||
轮次和步骤事件均位于轮次边界内。空闲 `user/message` 与独立的 `compact/* { turn: null }` 不占用轮次；其锁定时刻标记可以与注入交错。重新加载会为中断的轮次合成结束事件；`session/end-seed` 区分陈旧的压缩遗留项与活跃锁。关闭后仅由 `agent/error` 报告故障。每个轮次有一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)。
|
||||
适配器故障会先关闭步骤，再由 `agent/request-error` 授权从持久历史恢复。其他故障使用 `agent/error`；取消和资源释放优先于恢复。失败的模型尝试不会提交 assistant 消息或工具副作用。轮次关闭由一个 [TurnEndReason](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap)表示；准确的重试契约由 [LLM 流式输出](core-data-structures/llm-streaming.md)定义。
|
||||
|
||||
### Agent 句柄
|
||||
|
||||
`ctx.agents` 拥有 agent，返回 `AgentHandle { agent, dispose() }`。插件使用 `send()` 或 `followup()`、带回执的 `steer()` 和 `inject()` 预设；[`reserveTurnAdmission()`](../packages/core/agent/README.md#agent-interface-typests) 为持久工作同步预留空闲状态，同时不改变排队提示词身份。需要确认请求准入时应等待 steering 回执；尽力执行的 UI steering 可以忽略它。`cancel()` 与 `whenIdle()` 控制生命周期。调用方、工厂和消费方通过同一个需等待完成的 disposer 共同拥有拆卸过程。
|
||||
`ctx.agents` 管理 agent，并返回 `AgentHandle { agent, dispose() }`。插件通过 [agent 接口](../packages/core/agent/README.md#agent-interface-typests)提交排队工作、steering 或注入上下文；取消、空闲状态和拆卸也都由同一个句柄封装。
|
||||
|
||||
### Agent 作用域
|
||||
|
||||
每个 agent 都拥有作用域化的 `agent.ctx`；共享存储会将其工具、提示词和命令条目叠加到全局条目之上，同时保留各领域视图（[决策](../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)）。作用域监听器会过滤分派；贡献都会在撤销时等待清理完成。`CreateAgentOptions.setup(agentCtx)` 在发布前完成组合，并可返回一个同步提交操作；所有 setup 的 await 均完成后，工厂会在进入注册表前立即调用该操作。类型化解析器从合并后的 `Events` 和 `scopeTarget` 推导载体检查（[语义门禁](../.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)）。详情见 [agent 作用域](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md)和 [subagent 组合](../.agents/notes/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md)。`AgentLoop` 在 `ctx.agents.withInitiator()` 内运行；私有编排会派生 `agent.session`，但轮次、步骤、信号、cwd 和权限仍保持显式（[决策](../.agents/notes/implemented/architecture/2026-07-15-agent-initiator-scope.md)）。
|
||||
每个 agent 都拥有作用域化的 `agent.ctx`；共享存储会将其工具、提示词和命令叠加到全局贡献之上，作用域监听器则过滤分派。设置过程在发布前完成组合，清理过程会撤销贡献。详细生命周期由 [agent 作用域决策](../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md)定义。
|
||||
|
||||
## 状态
|
||||
|
||||
|
||||
@@ -64,10 +64,10 @@ Every adapter MUST obey these, and every consumer may rely on them:
|
||||
- **Provider stalls are bounded at the transport.** Both shipping remote adapters expose positive finite `streamIdleTimeoutMs` with a five-minute default. The watchdog arms only while iterator `next()` is outstanding, uses one stable signal for the whole request, maps its own expiry to `TIMEOUT`, and keeps an earlier caller abort as `ABORTED`.
|
||||
- **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text.
|
||||
- **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md).
|
||||
- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test (mock server asserting the received header, or the library's header hook for a library-backed adapter).
|
||||
- **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below), the `User-Agent` baseline.
|
||||
- **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmService` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content and provenance without the private state.
|
||||
|
||||
This contract is pinned down by two deliberately independent implementations: `dsh-llm-deepseek` (direct fetch, SSE framing via `eventsource-parser`) and `dsh-llm-pi-ai` (a generic multi-provider adapter through `@earendil-works/pi-ai`). The library-backed adapter exercises the finish-chunk error path, while transport-boundary tests prove each idle watchdog stops its actual request.
|
||||
Two independent implementations obey this contract: `dsh-llm-deepseek` uses direct fetch with SSE framing through `eventsource-parser`, while `dsh-llm-pi-ai` provides a generic multi-provider adapter through `@earendil-works/pi-ai`. Both carry cancellation and the idle watchdog to the provider request.
|
||||
|
||||
## `ResolvedRetryPolicy`
|
||||
|
||||
|
||||
@@ -64,10 +64,10 @@ interface LlmFailure {
|
||||
- **提供方停顿在传输层受到时限约束。** 两个已交付的远程适配器都暴露正数且有限的 `streamIdleTimeoutMs`，默认五分钟。watchdog 只在 iterator `next()` 尚未完成时启动，整个请求使用同一个稳定 signal，把自身到期映射为 `TIMEOUT`，并把更早发生的调用方中止保留为 `ABORTED`。
|
||||
- **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。
|
||||
- **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。
|
||||
- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明（mock 服务器断言收到的 header，或对基于库的适配器使用库的 header 钩子）。
|
||||
- **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送下文的 `attributionHeaders()`，即 `User-Agent` 基线。
|
||||
- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmService` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容与 provenance，不会收到私有状态。
|
||||
|
||||
该契约由两个有意保持独立的实现锁定：`dsh-llm-deepseek`（直接 fetch，SSE（Server-Sent Events）分帧经由 `eventsource-parser`）和 `dsh-llm-pi-ai`（通过 `@earendil-works/pi-ai` 实现的通用多提供方适配器）。基于库的适配器覆盖 finish 分片错误路径，而传输边界测试证明每个空闲 watchdog 都会停止其实际请求。
|
||||
两个彼此独立的实现遵循该契约：`dsh-llm-deepseek` 使用直接 fetch，并通过 `eventsource-parser` 进行 SSE（Server-Sent Events）分帧；`dsh-llm-pi-ai` 则通过 `@earendil-works/pi-ai` 提供通用多提供方适配器。两者都会把取消与空闲 watchdog 传递至提供方请求。
|
||||
|
||||
## `ResolvedRetryPolicy`
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/core-data-structures/persistence.md
|
||||
persistence.md: 237ce268691fa6f4b0546c6c1c14c21eaa462612
|
||||
persistence.zh.md: 9cb555f2e157844704896d9b04feb822428540e5
|
||||
persistence.md: ed19af4e739c153ce1beec7c1e8de06f0c0bca53
|
||||
persistence.zh.md: 83d8ba3c0eabe57b9df661fb86ec05d3db98d8b6
|
||||
|
||||
@@ -4,7 +4,7 @@ English | [中文](persistence.zh.md)
|
||||
|
||||
The **durability seam** for the event log. [session.md](session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its backends, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
|
||||
|
||||
The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session-persistence/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, crash-repairing load, non-mutating inspect, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted type** — and two interchangeable backends that pass the same `runPersistenceContract` suite. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
|
||||
The seam is a textbook [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session-persistence/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, crash-repairing load, non-mutating inspect, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted type** — and two interchangeable backends implementing the same contract. See the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
|
||||
|
||||
## The flush checkpoint
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。
|
||||
|
||||
该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session-persistence/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、会执行崩溃修复的 load、不会修改数据的 inspect，以及轻量的 list/snapshot 观察——**没有平行的持久化类型**——以及两个可互换、通过同一套 `runPersistenceContract` 的后端。见 [session-persistence Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
|
||||
该 seam 是典型的[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session-persistence/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、会执行崩溃修复的 load、不会修改数据的 inspect，以及轻量的 list/snapshot 观察——**没有平行的持久化类型**——以及两个实现同一契约的可互换后端。见 [session-persistence Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。
|
||||
|
||||
## flush 检查点
|
||||
|
||||
|
||||
@@ -98,36 +98,7 @@ The keyless [CI workflow](../.github/workflows/ci.yml) groups independent gates
|
||||
|
||||
## Daily commands
|
||||
|
||||
Use these from the repo root:
|
||||
|
||||
```sh
|
||||
pnpm run test # unit tests
|
||||
pnpm run test:coverage # unit tests with per-file coverage gates
|
||||
pnpm run test:e2e # real-API tests; self-skips without DEEPSEEK_API_KEY
|
||||
pnpm run check:all # comprehensive opt-in gate set; not wired to Git hooks
|
||||
pnpm run typecheck # tsc -b over the root solution: emits package/vendor lib/types, checks both aggregates
|
||||
pnpm run lint # oxlint .
|
||||
pnpm run lint:fix # formatting-only ESLint, then oxlint . --fix
|
||||
pnpm run doc-typecheck # compile checked TypeScript snippets in Markdown docs
|
||||
pnpm run gen-cordis-catalog # regenerate docs/cordis-catalog/events.md + services.md from source
|
||||
pnpm run verify-cordis-catalog # fail if either cordis catalog is stale
|
||||
pnpm run verify-export-jsdoc # fail if a module-level package export lacks complete JSDoc
|
||||
pnpm run gen-doc-graphs # regenerate generated relationship docs from source and curated graph definitions
|
||||
pnpm run verify-doc-graphs # fail if generated relationship docs are stale
|
||||
pnpm run verify-md-wrap # fail on hard-wrapped prose paragraphs in docs/README markdown
|
||||
pnpm run verify-mermaid # fail if a ```mermaid diagram has invalid Mermaid syntax
|
||||
pnpm run verify-type-equiv # fail if a ```ts type-equiv doc block drifts from its source type
|
||||
pnpm run verify-doc-budgets # fail if a budgeted standing doc exceeds its word ceiling
|
||||
pnpm run gen-translation-brief # print the minimal-update briefing for out-of-sync translation pairs (--apply splices code-only edits)
|
||||
pnpm run doc-sync # all Markdown/doc gates, scheduled concurrently; the doc-sync leaf list in scripts/run-gates.ts is the full list
|
||||
pnpm run gen-module-graph # regenerate docs/module-graph.md from package peerDeps
|
||||
pnpm run verify-module-graph # fail if docs/module-graph.md is stale
|
||||
pnpm run build # emit lib/types intermediates, then bundle lib/index.* runtime files
|
||||
pnpm run verify-node-next-types # fail if built declarations are not NodeNext-consumable
|
||||
pnpm run hygiene # knip, publint, workspace constraints, and NodeNext declaration check
|
||||
```
|
||||
|
||||
When changing package public behavior, update the relevant README or JSDoc in the same change. `pnpm run doc-sync` catches checked TypeScript snippets, generated doc freshness, markdown wrap/link drift, type equivalence, translation pairing, Mermaid syntax, and doc budgets, but broader prose/API sync still needs review.
|
||||
The root [contributor instructions](../AGENTS.md#commands) summarize common commands, while [`package.json`](../package.json) and [scripts/run-gates.ts](../scripts/run-gates.ts) own the current script and gate inventories. Select the smallest checks that cover the changed surface. Documentation changes use `pnpm run doc-sync`; package-public behavior changes also update the owning README or JSDoc, and built-artifact checks require `pnpm run build` first.
|
||||
|
||||
## Demos
|
||||
|
||||
|
||||
@@ -98,36 +98,7 @@ keyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若
|
||||
|
||||
## 日常命令
|
||||
|
||||
在仓库根目录使用：
|
||||
|
||||
```sh
|
||||
pnpm run test # unit tests
|
||||
pnpm run test:coverage # unit tests with per-file coverage gates
|
||||
pnpm run test:e2e # real-API tests; self-skips without DEEPSEEK_API_KEY
|
||||
pnpm run check:all # comprehensive opt-in gate set; not wired to Git hooks
|
||||
pnpm run typecheck # tsc -b over the root solution: emits package/vendor lib/types, checks both aggregates
|
||||
pnpm run lint # oxlint .
|
||||
pnpm run lint:fix # formatting-only ESLint, then oxlint . --fix
|
||||
pnpm run doc-typecheck # compile checked TypeScript snippets in Markdown docs
|
||||
pnpm run gen-cordis-catalog # regenerate docs/cordis-catalog/events.md + services.md from source
|
||||
pnpm run verify-cordis-catalog # fail if either cordis catalog is stale
|
||||
pnpm run verify-export-jsdoc # fail if a module-level package export lacks complete JSDoc
|
||||
pnpm run gen-doc-graphs # regenerate generated relationship docs from source and curated graph definitions
|
||||
pnpm run verify-doc-graphs # fail if generated relationship docs are stale
|
||||
pnpm run verify-md-wrap # fail on hard-wrapped prose paragraphs in docs/README markdown
|
||||
pnpm run verify-mermaid # fail if a ```mermaid diagram has invalid Mermaid syntax
|
||||
pnpm run verify-type-equiv # fail if a ```ts type-equiv doc block drifts from its source type
|
||||
pnpm run verify-doc-budgets # fail if a budgeted standing doc exceeds its word ceiling
|
||||
pnpm run gen-translation-brief # print the minimal-update briefing for out-of-sync translation pairs (--apply splices code-only edits)
|
||||
pnpm run doc-sync # all Markdown/doc gates, scheduled concurrently; the doc-sync leaf list in scripts/run-gates.ts is the full list
|
||||
pnpm run gen-module-graph # regenerate docs/module-graph.md from package peerDeps
|
||||
pnpm run verify-module-graph # fail if docs/module-graph.md is stale
|
||||
pnpm run build # emit lib/types intermediates, then bundle lib/index.* runtime files
|
||||
pnpm run verify-node-next-types # fail if built declarations are not NodeNext-consumable
|
||||
pnpm run hygiene # knip, publint, workspace constraints, and NodeNext declaration check
|
||||
```
|
||||
|
||||
修改 package 的公开行为时，请在同一个变更中更新相关 README 或 JSDoc。`pnpm run doc-sync` 能检测到被检查的 TypeScript 片段、生成文档的新鲜度、Markdown 换行/链接漂移、type-equiv、翻译配对、Mermaid 语法和文档预算，但更广泛的行文/API 同步仍需评审把关。
|
||||
根目录的[贡献者说明](../AGENTS.md#commands)概述常用命令，[`package.json`](../package.json) 与 [scripts/run-gates.ts](../scripts/run-gates.ts) 则负责当前脚本和门禁清单。请选择覆盖变更表面的最小检查集。文档变更使用 `pnpm run doc-sync`；package 公开行为变更还需更新所属 README 或 JSDoc，而基于构建产物的检查需要先运行 `pnpm run build`。
|
||||
|
||||
## 演示
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/i18n/README.md
|
||||
README.md: d1fff61a1d3db7fbe93d3c95b144598c2ca41c8b
|
||||
README.zh.md: 9f1d61f1b854ead0ef5851157cce2e9a6de83d89
|
||||
README.md: 2bac578034441bbe786ce54c051cc622bf9275c0
|
||||
README.zh.md: b7566bf6f88e03eb06227b63011f78252b4dcd07
|
||||
|
||||
@@ -43,7 +43,7 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
|
||||
|
||||
**Excluded** (never paired, and the gate rejects a `.zh.md` or `.i18n.yaml` for them):
|
||||
|
||||
- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files; their generators emit English only today, so a hand-written translation would go stale on every regeneration. The planned follow-up is to teach the generators to emit Chinese alongside English, at which point these leave the exclusion list.
|
||||
- `docs/cordis-catalog/`, `docs/tool-catalog/`, `docs/config-catalog.md`, `docs/persistence-catalog.md`, `docs/module-graph.md`, `docs/agent-lifecycle.md`, `docs/capability-seams.md`, `docs/event-producer-consumer.md`, `docs/graph-atlas.md`, and `docs/tool-execution-pipeline.md` — generated files whose generators emit English only; a hand-written translation would go stale on regeneration.
|
||||
- `docs/AGENTS.md`, `.agents/notes/**/AGENTS.md`, and their `CLAUDE.md` instruction symlinks — agent instructions, maintained in English only like the root `AGENTS.md`.
|
||||
- `docs/i18n/terminology.md` and [style-samples.md](style-samples.md) — both are bilingual by construction.
|
||||
- [translation-prompt.md](translation-prompt.md) — the automated pipeline's prompt template; its body is machine-consumed verbatim, so a paired translation would change pipeline behavior.
|
||||
|
||||
@@ -43,7 +43,7 @@
|
||||
|
||||
**排除**（永不配对，门禁拒绝为它们建 `.zh.md` 或 `.i18n.yaml`）：
|
||||
|
||||
- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件；生成器目前只输出英文，手写译文在每次重新生成时必然陈旧。计划中的后续工作是让生成器同时输出中文，届时这些文件移出排除清单。
|
||||
- `docs/cordis-catalog/`、`docs/tool-catalog/`、`docs/config-catalog.md`、`docs/persistence-catalog.md`、`docs/module-graph.md`、`docs/agent-lifecycle.md`、`docs/capability-seams.md`、`docs/event-producer-consumer.md`、`docs/graph-atlas.md` 与 `docs/tool-execution-pipeline.md`：生成文件，其生成器只输出英文；手写译文会在重新生成时变得陈旧。
|
||||
- `docs/AGENTS.md`、`.agents/notes/**/AGENTS.md` 以及指向它们的 `CLAUDE.md` 指令符号链接：agent 指令，与根 `AGENTS.md` 一样只以英文维护。
|
||||
- `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)：二者本身即为中英对照文档。
|
||||
- [translation-prompt.md](translation-prompt.md)：自动翻译流水线的提示词模板；正文逐字进入模型请求，配对翻译会改变流水线行为。
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/typert-catalog-integration-design.md
|
||||
typert-catalog-integration-design.md: c7d601730655f61f3b875ad5ad6997d3c888bfea
|
||||
typert-catalog-integration-design.zh.md: abaddfe1f740d4bd7cff5b2db8fd91e34626aab8
|
||||
@@ -1,133 +0,0 @@
|
||||
# Typert Catalog Integration Design
|
||||
|
||||
English | [中文](typert-catalog-integration-design.zh.md)
|
||||
|
||||
## Current State and Problem
|
||||
|
||||
Typert already provides separate host/client `FaceModel` instances, a `TypeGraph` with explicit cross-face references, and analysis support for services, events, `@typert object`, generics, inheritance, and External types. The TypeScript compiler API should only translate source code into this standard model; downstream consumers should not traverse the TypeScript AST again.
|
||||
|
||||
The repository currently has two catalog pipelines that analyze TypeScript source directly: the static API catalog consumed by `tool-cordis`, and the generation and freshness gate for `docs/cordis-catalog/events.md` and `docs/cordis-catalog/services.md`. They analyze the same services, events, and related types, but maintain separate collection and rendering logic, so they cannot prove that the Typert model is sufficient to represent the existing domain semantics.
|
||||
|
||||
The first phase makes both pipelines consume the Typert model while keeping the three committed artifacts character-for-character identical to their pre-migration versions:
|
||||
|
||||
- `docs/cordis-catalog/events.md`
|
||||
- `docs/cordis-catalog/services.md`
|
||||
- `packages/cordis/tool-cordis/src/api-catalog.ts`
|
||||
|
||||
This phase does not require product plugins to publish Typert subpaths, example applications to load Typert, or changes to the runtime dependencies of `tool-cordis`.
|
||||
|
||||
## Options
|
||||
|
||||
### Drive `tool-cordis` from the Runtime Registry
|
||||
|
||||
Each plugin publishes and loads Typert artifacts, then `tool-cordis` reads the current runtime model from `ctx.typert`. This path reflects the set of plugins actually loaded, but it requires every product package represented in the catalog to add package exports, generated artifacts, registry contributions, and application assembly. That integration surface is much larger than the analysis capability being validated now.
|
||||
|
||||
### Publish Typert Artifacts Repository-Wide, Then Aggregate Them Statically
|
||||
|
||||
All product packages generate host/client JS and DTS during the normal build/typecheck process, then the catalog generator aggregates those artifacts. This path establishes the complete publication protocol up front, but it also changes many package manifests and the build topology at once, coupling catalog migration to repository-wide Typert publication.
|
||||
|
||||
### Analyze at Build Time, Then Project the Catalog
|
||||
|
||||
`WorkspaceAnalyzer` builds a `WorkspaceModel` and `TypeGraph` from the host TypeScript project. The repository-specific `CordisCatalogProjector` consumes only that model and generates the three texts. `tool-cordis` continues to import the committed static `api-catalog.ts`, so the runtime does not need the Typert service.
|
||||
|
||||
This phase uses build-time projection. It directly verifies that the standard Typert model can replace the existing AST collector while leaving runtime publication and automatic loading to separate follow-up decisions.
|
||||
|
||||
## Phase-One Architecture
|
||||
|
||||
```text
|
||||
tsconfig.host.json
|
||||
│
|
||||
▼
|
||||
WorkspaceAnalyzer ── TypeScript compiler API 的唯一边界
|
||||
│
|
||||
▼
|
||||
WorkspaceModel + TypeGraph
|
||||
│
|
||||
▼
|
||||
CordisCatalogProjector ── 不依赖 TypeScript AST
|
||||
├── docs/cordis-catalog/events.md
|
||||
├── docs/cordis-catalog/services.md
|
||||
└── packages/cordis/tool-cordis/src/api-catalog.ts
|
||||
```
|
||||
|
||||
The objects have the following responsibilities:
|
||||
|
||||
- `WorkspaceAnalyzer` analyzes packages, exports, services, events, type declarations, and reference relationships, and produces a compiler-independent model.
|
||||
- `WorkspaceModel` and `TypeGraph` are the standard data structures shared by all generation and scanning analyses. They preserve developer-authored generics, inheritance, and type trees without retaining the TypeScript AST.
|
||||
- The root entry point of `@deepseek-ai/dsh-typert-generator` exports `CordisCatalogProjector`, which performs model-driven selection, sorting, summary extraction, source location handling, JSDoc completeness checks, type-link closure, and rendering in three text formats. Its implementation remains in a dedicated Cordis catalog file, but it does not create another package subpath or embed a list of repository type names.
|
||||
- `scripts/gen-cordis-catalog.ts` provides `LINK_MAP`, `FOUNDATION_TYPE_NAMES`, `TYPE_LINK_EXEMPTIONS`, and the inherited Cordis list, injects them explicitly into the projector through `CordisCatalogPolicy`, and owns the write/check CLI behavior. The vendor Cordis core pages continue to be generated by a separate pinned-source projector.
|
||||
- `tool-cordis` imports only the static `api-catalog.ts` and does not depend on `typert-registry` or `typert-loader`.
|
||||
|
||||
`CordisCatalogProjector` is a repository-specific downstream consumer and is not part of Typert's general-purpose model. When adding another category, first extend the standard model, then add the corresponding projector. The Typert analyzer must not absorb Cordis documentation formats or `tool-cordis` presentation logic.
|
||||
|
||||
## Model Additions
|
||||
|
||||
In addition to type structure, the catalog's character-for-character projection needs the declaration forms written by developers and exact source locations. The standard model therefore retains event/service locations, body-free text for events and members, parameter initializers, and the export status and canonical text of type declarations. `SourceDeclarationModel` also indexes top-level exported declarations for ambiguity checks and static type closure, without promoting them to domain graph roots.
|
||||
|
||||
```ts
|
||||
interface SourceLocation {
|
||||
readonly file: string
|
||||
readonly line: number
|
||||
readonly column: number
|
||||
}
|
||||
|
||||
interface EventModel {
|
||||
readonly location: SourceLocation
|
||||
readonly text: string
|
||||
}
|
||||
```
|
||||
|
||||
Repository-wide analysis supports building bounded `ts.Program` instances in package batches, then merging them through source-location-stable graph ids into a face model equivalent to monolithic analysis. This capability changes only the memory boundary of the compiler program; it does not change package, declaration, or type graph semantics.
|
||||
|
||||
All information required by the projector must come from `WorkspaceModel` or `TypeGraph`. If a fact required for character-for-character compatibility cannot be expressed by the model, extend the standard model; do not reintroduce `ts.Node`, `ts.Symbol`, or `ts.TypeChecker` in the projector or script.
|
||||
|
||||
## Character-for-Character Migration Oracle
|
||||
|
||||
Before migration, retain the three texts produced by the old generator against the same source state. After migration, run the new analyzer and projector and require the three outputs to be byte-for-byte identical. Newlines, spaces, ordering, JSDoc, source pointers, and generated headers are all part of the comparison.
|
||||
|
||||
`pnpm run verify-cordis-catalog` retains its `--check` mode, which reads the three committed artifacts and compares them directly with the newly computed results. A missing file or any differing character makes the artifact stale, and the error points to the single `pnpm run gen-cordis-catalog` repair command.
|
||||
|
||||
Tests pin both of the following layers:
|
||||
|
||||
- Typert fixture snapshots pin the `WorkspaceModel`, `TypeGraph`, JS, DTS, and Zod outputs, proving the behavior of the standard model and general-purpose emitters.
|
||||
- Cordis catalog tests or snapshots pin the projector's three complete texts, proving that the repository-specific product projection does not bypass the standard model and providing directly reviewable textual evidence.
|
||||
|
||||
The three committed artifacts are the migration oracle between the old and new implementations and the continuing freshness oracle after migration. The old `gen-cordis-api` AST collector is removed. The scripts and commands with that name remain only as compatibility entry points for the unified projector because the generated file header itself contains the command; retaining the entry point preserves the character-for-character oracle without creating a second source of truth.
|
||||
|
||||
## Exact Change List
|
||||
|
||||
### Typert Generator
|
||||
|
||||
- Add the locations, authored declaration text, parameter initializers, export status, and top-level source declaration index needed for character-for-character projection, with coverage in analyzer and model snapshots.
|
||||
- Support bounded package-batch analysis and prove that direct and batched models are equivalent.
|
||||
- Confirm that the catalog's required service declarations, public instance members, JSDoc, generics, inheritance, and referenced types are all available from the model.
|
||||
- Keep the TypeScript compiler API encapsulated within the analyzer; the public model and projector inputs do not expose compiler objects.
|
||||
|
||||
### Cordis Catalog Projector
|
||||
|
||||
- Select the complete set of Cordis services and events from the host `WorkspaceModel`.
|
||||
- Preserve the old generator's JSDoc rules: events must have `@mode` and payload `@param` tags; service methods must have a matching `@param` for every parameter; non-void returns must have `@returns`.
|
||||
- Compute the type links used by signatures and the transitive public type closure required by `tool-cordis` from the type graph.
|
||||
- Receive caller-maintained type classifications and the inherited surface through an explicit `CordisCatalogPolicy`; do not maintain the repository documentation taxonomy inside the generator package.
|
||||
- Preserve the existing output rules for source pointers, signatures, summaries, ordering, declaration truncation, and the inherited context catalog.
|
||||
- Project once and render the events Markdown, services Markdown, and TypeScript API catalog, preventing drift between documentation and tool data.
|
||||
|
||||
### Commands and Consumers
|
||||
|
||||
- `scripts/gen-cordis-catalog.ts` maintains repository policy data, assembles the analyzer and projector, and writes/checks all three artifacts together. Parsing, validation, and rendering logic lives in the generator's dedicated Cordis source file and is exported uniformly from the package root entry point.
|
||||
- Narrow `scripts/gen-cordis-api.ts` to a logic-free compatibility entry point for the unified CLI; the root `gen-cordis-api` and `verify-cordis-api` aliases point to that entry point.
|
||||
- Restore the static catalog default in `tool-cordis` and remove its dependencies on `ctx.typert`, `typert-registry`, and runtime package-model completeness.
|
||||
- `gen-doc-graphs` obtains the projector's model-level result once and reuses its services and events; it must not continue to import the AST collector or analyze the repository again.
|
||||
|
||||
### Narrow the Scope of Phase-One Changes
|
||||
|
||||
- Remove the newly added `./typert` and `./client/typert` exports and `lib/typert.*` files from product plugin package.json files.
|
||||
- Remove `typert-registry` and `typert-loader` assembly from examples.
|
||||
- Normal build/typecheck does not run repository-wide `gen-typert` or require product-package Typert artifacts to exist before it runs on a clean tree.
|
||||
- Retain `packages/typert/generator`, `packages/typert/registry`, and `packages/typert/loader`, along with their independent fixture, emitter, and runtime registration tests.
|
||||
|
||||
## Future Extensions
|
||||
|
||||
The runtime registry remains the receiving and query layer for generated JS/Zod, and the loader remains the automatic loading mechanism; neither supplies data to the first-phase static catalog. When product packages need runtime reflection, they can opt in by publishing `package/typert` and `package/client/typert`, which the loader then registers with `ctx.typert`.
|
||||
|
||||
Future integration does not change the phase-one layering: only the analyzer handles TypeScript, the standard model serves both static generation and scan analysis, and the emitter produces runtime artifacts from that same model. Whether to extend publication to more packages, enable the loader by default, or extend the runtime registry's query capabilities are separate review decisions and remain decoupled from the Cordis catalog migration.
|
||||
@@ -1,133 +0,0 @@
|
||||
# Typert catalog 接入设计
|
||||
|
||||
[English](typert-catalog-integration-design.md) | 中文
|
||||
|
||||
## 现状与问题
|
||||
|
||||
Typert 已经具备独立的 host/client `FaceModel`、可显式跨 face 引用的 `TypeGraph`，以及 service、event、`@typert object`、泛型、继承和 External 类型的分析能力。TypeScript compiler API 只应负责把源码转换成这套标准模型；后续消费者不应再次遍历 TypeScript AST。
|
||||
|
||||
仓库目前有两条直接分析 TypeScript 源码的 catalog 链路：`tool-cordis` 使用的静态 API catalog，以及 `docs/cordis-catalog/events.md`、`docs/cordis-catalog/services.md` 的生成与 freshness gate。它们分析的是同一批 service、event 和相关类型，却分别维护收集与渲染逻辑，不能证明 Typert 模型足以承载现有业务语义。
|
||||
|
||||
第一阶段的目标是让这两条链路共同消费 Typert 模型，并保持三份已提交产物与迁移前字符级一致：
|
||||
|
||||
- `docs/cordis-catalog/events.md`
|
||||
- `docs/cordis-catalog/services.md`
|
||||
- `packages/cordis/tool-cordis/src/api-catalog.ts`
|
||||
|
||||
本阶段不要求业务插件发布 Typert 子路径，不要求示例应用加载 Typert，也不改变 `tool-cordis` 的运行时依赖关系。
|
||||
|
||||
## 可选路径
|
||||
|
||||
### 运行时 registry 驱动 `tool-cordis`
|
||||
|
||||
每个插件发布并加载 Typert 产物，`tool-cordis` 再从 `ctx.typert` 读取当前运行时模型。这条路径可以反映实际加载的插件集合，但会要求所有参与 catalog 的业务包增加 package exports、生成产物、registry contribution 和应用装配，接入面远大于当前要验证的分析能力。
|
||||
|
||||
### 全仓发布 Typert 产物后静态汇总
|
||||
|
||||
所有业务包在普通 build/typecheck 中生成 host/client JS 与 DTS，再由 catalog 生成器汇总这些产物。这条路径能够提前建立完整的发布协议，但会同时修改大量 package manifest 和构建拓扑，使 catalog 迁移与 Typert 的全仓发布绑定。
|
||||
|
||||
### 构建期分析后投影 catalog
|
||||
|
||||
`WorkspaceAnalyzer` 从 host TypeScript project 构建 `WorkspaceModel` 与 `TypeGraph`，仓库专用的 `CordisCatalogProjector` 只消费该模型并生成三份文本。`tool-cordis` 继续导入已提交的静态 `api-catalog.ts`，运行时不需要 Typert service。
|
||||
|
||||
本阶段采用构建期投影。它直接验证 Typert 标准模型能否替代现有 AST collector，同时把运行时 publication 和自动加载留在独立的后续决策中。
|
||||
|
||||
## 第一阶段架构
|
||||
|
||||
```text
|
||||
tsconfig.host.json
|
||||
│
|
||||
▼
|
||||
WorkspaceAnalyzer ── TypeScript compiler API 的唯一边界
|
||||
│
|
||||
▼
|
||||
WorkspaceModel + TypeGraph
|
||||
│
|
||||
▼
|
||||
CordisCatalogProjector ── 不依赖 TypeScript AST
|
||||
├── docs/cordis-catalog/events.md
|
||||
├── docs/cordis-catalog/services.md
|
||||
└── packages/cordis/tool-cordis/src/api-catalog.ts
|
||||
```
|
||||
|
||||
各对象的职责如下：
|
||||
|
||||
- `WorkspaceAnalyzer` 负责 package、export、service、event、类型声明和引用关系的分析，并产生 compiler-independent model。
|
||||
- `WorkspaceModel` 与 `TypeGraph` 是所有生成和扫描分析共用的标准数据结构，保留开发者写出的泛型、继承和类型树，不保存 TypeScript AST。
|
||||
- `@deepseek-ai/dsh-typert-generator` 根入口导出的 `CordisCatalogProjector` 负责模型驱动的选择、排序、摘要、源位置、JSDoc 完整性、类型链接闭包和三种文本格式；实现仍单独放在 Cordis catalog 专用文件中，但不形成额外的 package subpath，也不内置仓库类型名单。
|
||||
- `scripts/gen-cordis-catalog.ts` 提供 `LINK_MAP`、`FOUNDATION_TYPE_NAMES`、`TYPE_LINK_EXEMPTIONS` 和 inherited Cordis 清单，通过 `CordisCatalogPolicy` 显式注入 projector，并负责 write/check 的命令行行为；vendor Cordis core 页面仍由独立的 pinned-source projector 生成。
|
||||
- `tool-cordis` 只导入静态 `api-catalog.ts`，不依赖 `typert-registry` 或 `typert-loader`。
|
||||
|
||||
`CordisCatalogProjector` 是仓库业务消费者，不进入 Typert 通用模型。新增其他类别时，先扩展标准模型，再增加对应 projector；Typert analyzer 不吸收 Cordis 文档格式或 `tool-cordis` 展示逻辑。
|
||||
|
||||
## 模型补充
|
||||
|
||||
Catalog 的字符级投影除了类型结构，还需要开发者写下的声明形式和精确源码位置。标准模型因此保留 event/service location、event/member 的 body-free text、parameter initializer，以及 type declaration 的 export 状态和 canonical text；`SourceDeclarationModel` 另外索引顶层导出声明，供歧义检查和静态类型闭包使用，但不把它们提升为业务 graph root。
|
||||
|
||||
```ts
|
||||
interface SourceLocation {
|
||||
readonly file: string
|
||||
readonly line: number
|
||||
readonly column: number
|
||||
}
|
||||
|
||||
interface EventModel {
|
||||
readonly location: SourceLocation
|
||||
readonly text: string
|
||||
}
|
||||
```
|
||||
|
||||
全仓分析支持按 package 分批构建有界 `ts.Program`，再依靠源码位置稳定的 graph id 合并为与一次性分析等价的 face model。该能力只改变 compiler program 的内存边界，不改变 package、declaration 或 type graph 语义。
|
||||
|
||||
projector 所需信息必须来自 `WorkspaceModel` 或 `TypeGraph`。如果字符级兼容需要的事实无法从模型表达，应补充标准模型；不得在 projector 或脚本中重新引入 `ts.Node`、`ts.Symbol` 或 `ts.TypeChecker`。
|
||||
|
||||
## 字符级迁移 oracle
|
||||
|
||||
迁移前，在同一份源码状态下保留旧生成器产生的三份文本。迁移后运行新的 analyzer 与 projector，要求三份输出逐字节相等；换行、空格、排序、JSDoc、source pointer 和生成头都属于比较内容。
|
||||
|
||||
`pnpm run verify-cordis-catalog` 的 `--check` 模式继续读取三份 committed artifact，并与本次计算结果直接比较。任一文件缺失或任一字符不同都视为 stale，错误信息指向统一的 `pnpm run gen-cordis-catalog` 修复命令。
|
||||
|
||||
测试同时固定以下两层：
|
||||
|
||||
- Typert fixture snapshots 固定 `WorkspaceModel`、`TypeGraph`、JS、DTS 与 Zod 输出，证明标准模型和通用 emitter 的行为。
|
||||
- Cordis catalog 测试或 snapshot 固定 projector 的三份完整文本，证明仓库业务投影没有绕过标准模型，并给出可直接评审的文本证据。
|
||||
|
||||
三份 committed artifact 是旧实现与新实现的迁移 oracle，也是迁移完成后的持续 freshness oracle。旧 `gen-cordis-api` AST collector 被删除；同名脚本和命令只作为统一 projector 的兼容入口保留，因为生成文件头本身包含该命令，保留入口可以维持字符级 oracle 而不产生第二套真源。
|
||||
|
||||
## 精确改造清单
|
||||
|
||||
### Typert generator
|
||||
|
||||
- 补齐字符级投影所需的 location、authored declaration text、parameter initializer、export 状态和顶层 source declaration index，并在 analyzer 与 model snapshots 中覆盖。
|
||||
- 支持有界 package batch 分析，并证明 direct 与 batched model 等价。
|
||||
- 确认 catalog 所需的 service 声明、public instance member、JSDoc、泛型、继承和引用类型均可从 model 读取。
|
||||
- 保持 TypeScript compiler API 封装在 analyzer 内；公共 model 和 projector 输入不暴露 compiler 对象。
|
||||
|
||||
### Cordis catalog projector
|
||||
|
||||
- 从 host `WorkspaceModel` 选择完整的 Cordis service/event 集合。
|
||||
- 保留旧生成器的 JSDoc 规则：event 必须有 `@mode` 和 payload `@param`，service method 必须有参数对应的 `@param`，非 void 返回必须有 `@returns`。
|
||||
- 从 type graph 计算签名涉及的类型链接和 `tool-cordis` 所需的传递 public type closure。
|
||||
- 通过显式 `CordisCatalogPolicy` 接收调用方维护的类型分类和 inherited surface，不在 generator 包内维护仓库文档 taxonomy。
|
||||
- 保留 source pointer、签名、摘要、排序、声明截断和 inherited context catalog 的既有输出规则。
|
||||
- 一次投影并渲染 events Markdown、services Markdown 与 TypeScript API catalog，避免文档和工具数据漂移。
|
||||
|
||||
### 命令与消费方
|
||||
|
||||
- `scripts/gen-cordis-catalog.ts` 维护仓库 policy 数据、组装 analyzer/projector，并同时 write/check 三份产物；解析、校验和渲染逻辑位于 generator 的 Cordis 专用源文件，并统一从 package 根入口导出。
|
||||
- 将 `scripts/gen-cordis-api.ts` 收窄为统一 CLI 的无逻辑兼容入口；根目录的 `gen-cordis-api`、`verify-cordis-api` aliases 指向该入口。
|
||||
- `tool-cordis` 恢复静态 catalog 默认值，移除对 `ctx.typert`、`typert-registry` 和运行时 package model 完整性的依赖。
|
||||
- `gen-doc-graphs` 一次取得 projector 的 model-level 结果并复用 services/events，不能继续导入 AST collector 或重复分析全仓。
|
||||
|
||||
### 收窄本阶段改动面
|
||||
|
||||
- 撤销业务插件 package.json 中新增的 `./typert`、`./client/typert` exports 和 `lib/typert.*` files。
|
||||
- 撤销 examples 中的 `typert-registry`、`typert-loader` 装配。
|
||||
- 普通 build/typecheck 不运行全仓 `gen-typert`，也不要求 clean tree 预先存在业务包 Typert artifact。
|
||||
- 保留 `packages/typert/generator`、`packages/typert/registry`、`packages/typert/loader` 及其独立 fixture、emitter 和 runtime registration 测试。
|
||||
|
||||
## 后续扩展
|
||||
|
||||
Runtime registry 继续作为生成 JS/Zod 后的接收与查询层，loader 继续作为自动装载机制；两者不承担第一阶段静态 catalog 的数据来源。业务包需要运行时反射时，可以按 package opt-in 发布 `package/typert` 与 `package/client/typert`，再由 loader 注册到 `ctx.typert`。
|
||||
|
||||
后续接入不改变本阶段的分层：TypeScript 只进入 analyzer，标准模型同时服务静态生成与扫描分析，runtime artifact 由 emitter 从同一模型产生。是否把更多 package 接入 publication、是否默认启用 loader，以及 runtime registry 最终提供哪些查询能力，分别评审，不与 Cordis catalog 迁移捆绑。
|
||||
@@ -120,35 +120,6 @@ export default class MyService extends Service {
|
||||
|
||||
Function form is sufficient in most cases. Use class form when the plugin provides a service to other plugins; see [services and dependencies](../framework/service.md).
|
||||
|
||||
## Complete example
|
||||
|
||||
A minimal tool plugin registers its definition on `ctx.tools`:
|
||||
|
||||
```ts
|
||||
import type { Context } from 'cordis'
|
||||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||||
|
||||
export const name = 'greet-tool'
|
||||
export const inject = ['tools']
|
||||
|
||||
export function apply(ctx: Context) {
|
||||
ctx.tools.register(defineTool({
|
||||
name: 'greet',
|
||||
description: 'Greet the named person.',
|
||||
parameters: {
|
||||
name: { type: 'string', required: true },
|
||||
},
|
||||
output: {
|
||||
schema: { type: 'string' },
|
||||
render: (_args, value) => [{ type: 'text', text: value }],
|
||||
},
|
||||
async execute(args) {
|
||||
return `Hello, ${args.name}!`
|
||||
},
|
||||
}))
|
||||
}
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Build a tool](./tool.md) — learn the tool definition DSL
|
||||
|
||||
@@ -32,10 +32,7 @@ One interface can have multiple implementations selected through `cordis.yml`:
|
||||
# Local execution
|
||||
- name: '@deepseek-ai/dsh-bash-local'
|
||||
|
||||
# Or a future remote sandbox implementation
|
||||
# - name: '@deepseek-ai/dsh-bash-remote'
|
||||
# config:
|
||||
# endpoint: 'https://sandbox.example.com'
|
||||
# Replace this row with another package that implements the same service.
|
||||
```
|
||||
|
||||
The interface and tool remain unchanged while the implementation changes.
|
||||
|
||||
@@ -32,10 +32,7 @@
|
||||
# Local execution
|
||||
- name: '@deepseek-ai/dsh-bash-local'
|
||||
|
||||
# Or a future remote sandbox implementation
|
||||
# - name: '@deepseek-ai/dsh-bash-remote'
|
||||
# config:
|
||||
# endpoint: 'https://sandbox.example.com'
|
||||
# Replace this row with another package that implements the same service.
|
||||
```
|
||||
|
||||
更换实现时，接口和工具均保持不变。
|
||||
|
||||
Reference in New Issue
Block a user