@qilin-agent/sdk-client 0.0.0-stage → 3.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.i18n.yaml +55 -0
- package/README.md +135 -2
- package/README.zh.md +136 -0
- package/lib/index.js +886 -0
- package/lib/types/api.d.ts +127 -0
- package/lib/types/client.d.ts +163 -0
- package/lib/types/dispose.d.ts +27 -0
- package/lib/types/index.d.ts +17 -0
- package/lib/types/launch.d.ts +58 -0
- package/lib/types/types.d.ts +77 -0
- package/package.json +43 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 kkutysllb
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.i18n.yaml
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
|
|
2
|
+
# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
|
|
3
|
+
# After editing either side, bring the other along and re-record with:
|
|
4
|
+
# pnpm run verify-translation-pairing --write packages/sdk/client/README.md
|
|
5
|
+
/:
|
|
6
|
+
en: 3569bd04353e236f
|
|
7
|
+
zh: 3775cf221a0d95b3
|
|
8
|
+
/qilin-agent-sdk-client:
|
|
9
|
+
en: 2518c7e7142a83a6
|
|
10
|
+
zh: 545d4928b779b606
|
|
11
|
+
/qilin-agent-sdk-client/summary:
|
|
12
|
+
en: 296fd5fa9e2d56ca
|
|
13
|
+
zh: 89f81af039e90708
|
|
14
|
+
/qilin-agent-sdk-client/table-of-contents:
|
|
15
|
+
en: d152484eb41ac6b4
|
|
16
|
+
zh: 09388d293f9be9cb
|
|
17
|
+
/qilin-agent-sdk-client/use-this-package:
|
|
18
|
+
en: 316b142489dd050f
|
|
19
|
+
zh: 2b37ae57b2a52b5e
|
|
20
|
+
/qilin-agent-sdk-client/use-this-package/running-agent-turns-with-deepseekharness:
|
|
21
|
+
en: 01c58dddd7e62de2
|
|
22
|
+
zh: 6dbd46e244f3f135
|
|
23
|
+
/qilin-agent-sdk-client/use-this-package/lower-level-control-with-harnessclient:
|
|
24
|
+
en: eb8d1958801816b6
|
|
25
|
+
zh: 1a6087e2dd1a9347
|
|
26
|
+
/qilin-agent-sdk-client/understand-the-implementation:
|
|
27
|
+
en: 8773f50c51da85f0
|
|
28
|
+
zh: 4649ebc69357deb0
|
|
29
|
+
/qilin-agent-sdk-client/understand-the-implementation/design-concept:
|
|
30
|
+
en: 109a9c832204693c
|
|
31
|
+
zh: 6af985fe4abe57e2
|
|
32
|
+
/qilin-agent-sdk-client/understand-the-implementation/source-map:
|
|
33
|
+
en: a3c7978a80f5aba3
|
|
34
|
+
zh: fdc4dfdafd2eccfa
|
|
35
|
+
/qilin-agent-sdk-client/understand-the-implementation/owned-activity-flow:
|
|
36
|
+
en: 94a42babac5f1c7d
|
|
37
|
+
zh: df9e42ed02f7d002
|
|
38
|
+
/qilin-agent-sdk-client/understand-the-implementation/errors-and-teardown:
|
|
39
|
+
en: 165364de2cee0a9f
|
|
40
|
+
zh: c4dc37b44e1e621e
|
|
41
|
+
/qilin-agent-sdk-client/further-exploration:
|
|
42
|
+
en: f6384d7642f7ec43
|
|
43
|
+
zh: dd147c57bfe422a2
|
|
44
|
+
/qilin-agent-sdk-client/model-experience:
|
|
45
|
+
en: e82a55513d3cd30e
|
|
46
|
+
zh: ecd8c0875ff2fb87
|
|
47
|
+
/qilin-agent-sdk-client/model-experience/kv-cache-effect:
|
|
48
|
+
en: 7abe0be104a791e7
|
|
49
|
+
zh: 445311f78b1069ca
|
|
50
|
+
/qilin-agent-sdk-client/known-limitations-and-deferred-work:
|
|
51
|
+
en: 7b24f3cd40fd7971
|
|
52
|
+
zh: bdb0f7c37f1658da
|
|
53
|
+
/qilin-agent-sdk-client/known-limitations-and-deferred-work/dev-note:
|
|
54
|
+
en: 6177a56f053936a4
|
|
55
|
+
zh: 0f4b20228c2d15da
|
package/README.md
CHANGED
|
@@ -1,3 +1,136 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
description: "The TypeScript SDK client for callers that spawn a QiLin runtime subprocess and drive agent turns over stdio JSON-RPC: the DeepSeekHarness run API and the lower-level HarnessClient."
|
|
3
|
+
kind: "package-library"
|
|
4
|
+
---
|
|
2
5
|
|
|
3
|
-
|
|
6
|
+
# @qilin-agent/sdk-client
|
|
7
|
+
|
|
8
|
+
English | [中文](README.zh.md)
|
|
9
|
+
|
|
10
|
+
## Summary
|
|
11
|
+
|
|
12
|
+
`qilin-sdk-client` lets TypeScript programs start and drive a complete QiLin runtime over stdio JSON-RPC. Use `DeepSeekHarness` to open sessions, send text or image prompts, collect event and notification streams, and obtain the last committed assistant response when the runtime becomes idle; use `HarnessClient` for direct protocol requests and subscriptions. Callers may provide `qilinBin`; otherwise the client resolves the same-version `@qilin-agent/cli` executable. The client owns the subprocess across runs, exposes typed transport and protocol failures, and reaps it on `close()` or `await using`. It is suitable when the caller can choose the runtime profile and launch settings.
|
|
13
|
+
|
|
14
|
+
## Table of Contents
|
|
15
|
+
|
|
16
|
+
- [Use this package](#use-this-package)
|
|
17
|
+
- [Understand the implementation](#understand-the-implementation)
|
|
18
|
+
- [Further Exploration](#further-exploration)
|
|
19
|
+
- [Model Experience](#model-experience)
|
|
20
|
+
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
|
|
21
|
+
- [Dev Note](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## Use this package
|
|
27
|
+
|
|
28
|
+
`HarnessSession.getWorkingDirectory()` reads the effective directory; `setWorkingDirectory(path)` changes it and returns the validated absolute path. Either method creates an unknown Session without starting a model turn. Relative paths use the Session's current directory. Origin metadata, permissions, and existing processes remain unchanged. `HarnessClient` exposes the same methods with a leading `sessionId` argument.
|
|
29
|
+
|
|
30
|
+
Use this client when TypeScript code must drive a complete Harness runtime from another process and you can name the runtime executable explicitly. The common path is minimal: construct a `DeepSeekHarness` with a launch spec, run prompts, and close it so the child process is always reaped.
|
|
31
|
+
|
|
32
|
+
### Running agent turns with DeepSeekHarness
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { DeepSeekHarness } from '@qilin-agent/sdk-client'
|
|
36
|
+
import { ReasoningEffortId } from '@qilin-agent/llm'
|
|
37
|
+
|
|
38
|
+
await using harness = new DeepSeekHarness({
|
|
39
|
+
profile: 'sdk',
|
|
40
|
+
patches: ['./automation.cordis.yml'],
|
|
41
|
+
provider: 'deepseek-official',
|
|
42
|
+
model: 'deepseek-v4-flash',
|
|
43
|
+
reasoningEffort: ReasoningEffortId('max'),
|
|
44
|
+
maxTokens: 49_152,
|
|
45
|
+
})
|
|
46
|
+
const result = await harness.run('say hi')
|
|
47
|
+
console.log(result.finalResponse)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; call `close()` (or use `await using`) so the child is always reaped. `start()` memoizes the bounded `initialize` handshake, which carries the workspace cwd, provider/model route, optional adapter-owned `reasoningEffort`, and optional positive `maxTokens` output cap. The server validates that exact route before it accepts prompts; an omitted effort preserves the model's default. `initializeTimeoutMs` defaults to 10 seconds, and its diagnostic names the selected profile with the retained stderr tail. `run(input, { sessionId?, onNotification? })` accepts text or `SdkPromptContentBlock[]`; an inline raster block carries canonical base64 plus `mimeType` and becomes a durable attachment inside the runtime. The call owns one activity interval: it queues the prompt, waits until its message id appears in a durable inbox receipt, then collects through the next whole-agent `idle`. It returns `RunResult { sessionId, finalResponse, events, notifications }`, where `finalResponse` is the last committed root-session assistant text in that interval — not a response causally assigned to the prompt, because steering, injected context, and other queued work may contribute before idle. `session(id?)` opens a named or fresh session handle. When a failed handshake is cleaned up successfully, the instance installs a fresh client so a later call retries with a new process until terminal `close()`; if initialization and cleanup both fail, `start()` returns an ordered `AggregateError` and retains the failed client instead of spawning beside a process whose exit is unproved. `maxTokens` caps each root-agent request output and is inherited by in-process descendants; compaction plugins own their separate summary limits.
|
|
51
|
+
|
|
52
|
+
### Lower-level control with HarnessClient
|
|
53
|
+
|
|
54
|
+
`HarnessClient` is the protocol client under the run API: explicit `start()`, `initialize()`, `prompt()`, `request()`, and `close()`, plus notification subscriptions. `prompt()` returns the queued message id as soon as the runtime accepts it and never waits for agent activity. `subscribe(filter?)` returns a `NotificationSubscription` (awaitable `next()`, non-blocking `tryNext()`, async iteration); `subscribeSessionTree(id)` scopes to one session and the descendants discovered from `subagent.started` lineage edges — the runtime notifies for every session in its context, and scoping is client-side, exactly like the Python SDK.
|
|
55
|
+
|
|
56
|
+
The client exports typed errors for every failure mode: `JsonRpcResponseError` (a wire error response, code and data preserved), `RequestTimeoutError` (a configured bound elapsed), `SdkProtocolError` (a response outside the documented protocol), and `TransportClosedError` (the runtime is gone — the message carries the exit code and a bounded stderr tail). `close()` requests protocol `shutdown` (bounded by `shutdownTimeoutMs`, default 1000 ms), then walks a stdin-EOF → SIGTERM → SIGKILL ladder until the process has exited; it is idempotent, and a closed client refuses reuse. `HarnessClientOptions.env` replaces the child environment entirely when given (`undefined` inherits the parent's); callers own credential policy — `scrubbedParentEnv` from `qilin-subprocess` is the shared scrub base for isolation-minded launches.
|
|
57
|
+
|
|
58
|
+
-----
|
|
59
|
+
|
|
60
|
+
<a id="understand-the-implementation"></a>
|
|
61
|
+
## Understand the implementation
|
|
62
|
+
|
|
63
|
+
<details>
|
|
64
|
+
<summary>Implementation internals — click to expand</summary>
|
|
65
|
+
|
|
66
|
+
This section explains the design behind the client; the observable behavior is fully covered in [Use this package](#use-this-package).
|
|
67
|
+
|
|
68
|
+
### Design concept
|
|
69
|
+
|
|
70
|
+
The client is two layers over one wire: `DeepSeekHarness` (owned runs) over `HarnessClient` (the protocol client), mirroring the Python SDK's layering. It runs outside any harness context, so it spawns the runtime directly rather than through the `qilin-subprocess` service — the seam's documented exception for SDK-managed transports — and its teardown ladder lives in this package. The runtime notifies for every session in its context; session-tree scoping is a client-side filter over `subagent.started` lineage edges.
|
|
71
|
+
|
|
72
|
+
### Source map
|
|
73
|
+
|
|
74
|
+
| File | Role |
|
|
75
|
+
|---|---|
|
|
76
|
+
| [`src/api.ts`](src/api.ts) | `DeepSeekHarness` + `HarnessSession`: owned runs, receipt-to-idle collection, `finalResponse` |
|
|
77
|
+
| [`src/client.ts`](src/client.ts) | `HarnessClient`: spawn, handshake, requests, subscription fan-out, typed errors |
|
|
78
|
+
| [`src/dispose.ts`](src/dispose.ts) | Private teardown ladder: stdin EOF → SIGTERM → SIGKILL to actual exit |
|
|
79
|
+
| [`src/types.ts`](src/types.ts) | Launch and timeout options, notification shapes, `RunResult` |
|
|
80
|
+
| [`src/index.ts`](src/index.ts) | Consumer interface: the two client layers and caller-facing types |
|
|
81
|
+
|
|
82
|
+
### Owned activity flow
|
|
83
|
+
|
|
84
|
+
A run subscribes to the session tree, queues the prompt, waits until the prompt's message id appears in a durable `agent/inbox/spliced` receipt, then collects notifications until the whole agent reports `idle`. `finalResponse` is derived from the last `assistant/message` in the collected events. Transport loss, timeout, and protocol violations reject the run; model outcomes remain observable in the event stream without being attributed to one input.
|
|
85
|
+
|
|
86
|
+
### Errors and teardown
|
|
87
|
+
|
|
88
|
+
Every failure mode maps to one exported error class — a wire error response, an elapsed request bound, a response outside the documented protocol, or a dead runtime — so callers branch on failure type; the four classes are exported from [src/index.ts](src/index.ts). Teardown is a private, idempotent escalation (stdin EOF → SIGTERM → SIGKILL) in [src/dispose.ts](src/dispose.ts) that ends only at actual process exit.
|
|
89
|
+
|
|
90
|
+
</details>
|
|
91
|
+
|
|
92
|
+
-----
|
|
93
|
+
|
|
94
|
+
<a id="further-exploration"></a>
|
|
95
|
+
## Further Exploration
|
|
96
|
+
|
|
97
|
+
Read these pages when the client contract is not enough. They move from the wire protocol to the serving plugin and the applications that use this client.
|
|
98
|
+
|
|
99
|
+
- [SDK wire protocol](../protocol/README.md) — the JSON-RPC methods and payload shapes this client speaks.
|
|
100
|
+
- [JSON-RPC serving plugin](../server/README.md) — the runtime plugin that serves this client.
|
|
101
|
+
- [Python SDK](../../../python/README.md) — the design twin that shares the same runtime peer and protocol.
|
|
102
|
+
- [SDK subagent backend](../../subagent/subagent-qilin-sdk/README.md) — a harness-internal consumer of this client.
|
|
103
|
+
- [SDK application bundle](../../bundle/sdk-app/README.md) — the `qilin --profile sdk` runtime application this client launches.
|
|
104
|
+
|
|
105
|
+
-----
|
|
106
|
+
|
|
107
|
+
<a id="model-experience"></a>
|
|
108
|
+
## Model Experience
|
|
109
|
+
|
|
110
|
+
None, as this is a client-process library; model-facing behavior lives in the spawned runtime's composed plugins.
|
|
111
|
+
|
|
112
|
+
#### KV Cache effect
|
|
113
|
+
|
|
114
|
+
None in the client process. Profile, patch, provider, model, and history choices determine cache reuse in the child.
|
|
115
|
+
|
|
116
|
+
## Known Limitations and Deferred Work
|
|
117
|
+
|
|
118
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
These limits define when the client is a poor fit or needs special care. They are current package constraints, not a comparison with other SDK clients or a task backlog.
|
|
122
|
+
|
|
123
|
+
- **No bundled-runtime resolution** — the client resolves the same-version `@qilin-agent/cli` package (or a caller-provided `qilinBin`); packaged-executable discovery stays Python-side until a TypeScript distribution consumer exists.
|
|
124
|
+
- **No mid-turn cancel** — the wire has no prompt-cancel method; abandoning a turn means closing the runtime (see the [protocol limitations](../protocol/README.md#known-limitations-and-deferred-work)).
|
|
125
|
+
- **No per-prompt result** — low-level `prompt()` returns only an enqueue receipt; high-level `run()` owns receipt-to-idle collection, and abandoning it means closing the runtime.
|
|
126
|
+
- **Client→server notifications and server→client requests are unimplemented** on both wire ends; the transport carries them for future approval flows.
|
|
127
|
+
|
|
128
|
+
<a id="dev-note"></a>
|
|
129
|
+
### Dev Note
|
|
130
|
+
|
|
131
|
+
<details>
|
|
132
|
+
<summary>Working context for maintainers — click to expand</summary>
|
|
133
|
+
|
|
134
|
+
This Dev Note is working context for maintainers and is explicitly non-authoritative — shipped behavior and limits live in the sections above and in the code. The launch spec is intentionally fully explicit: no bundled-runtime resolution is planned for TypeScript until a distribution consumer exists. Keep the dispose ladder and the error vocabulary in sync with the Python client, which drives the same runtime. No other unresolved design questions are recorded.
|
|
135
|
+
|
|
136
|
+
</details>
|
package/README.zh.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "面向以子进程方式启动 QiLin 运行时、并通过 stdio JSON-RPC 驱动 agent(智能体)轮次的调用方的 TypeScript SDK 客户端:DeepSeekHarness 运行 API 与低层 HarnessClient。"
|
|
3
|
+
kind: "package-library"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @qilin-agent/sdk-client
|
|
7
|
+
|
|
8
|
+
[English](README.md) | 中文
|
|
9
|
+
|
|
10
|
+
## 概述
|
|
11
|
+
|
|
12
|
+
`qilin-sdk-client` 让 TypeScript 程序通过 stdio JSON-RPC 启动并驱动完整的 QiLin 运行时。使用 `DeepSeekHarness` 可打开会话、发送文本或图像提示词、收集事件与通知流,并在运行时进入 idle 后取得最后提交的助手响应;使用 `HarnessClient` 可直接发送协议请求和订阅通知。调用方可以提供 `qilinBin`;否则客户端解析同版本的 `@qilin-agent/cli` 可执行文件。客户端跨多次运行持有子进程,公开类型化的传输与协议错误,并在 `close()` 或 `await using` 时回收进程。它适用于调用方能够选择运行时 profile 和启动设置的场景。
|
|
13
|
+
|
|
14
|
+
## 目录
|
|
15
|
+
|
|
16
|
+
- [使用本包](#use-this-package)
|
|
17
|
+
- [理解实现](#understand-the-implementation)
|
|
18
|
+
- [进一步探索](#further-exploration)
|
|
19
|
+
- [模型体验](#model-experience)
|
|
20
|
+
- [已知限制与延期工作](#known-limitations-and-deferred-work)
|
|
21
|
+
- [开发备注](#dev-note)
|
|
22
|
+
|
|
23
|
+
-----
|
|
24
|
+
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## 使用本包
|
|
27
|
+
|
|
28
|
+
`HarnessSession.getWorkingDirectory()` 读取有效目录;`setWorkingDirectory(path)` 修改目录并返回校验后的绝对路径。两个方法都可创建未知 Session,而不启动模型轮次。相对路径以 Session 当前目录解析。起始目录元数据、权限与已有进程保持不变。`HarnessClient` 提供同名方法,并以 `sessionId` 作为首个参数。
|
|
29
|
+
|
|
30
|
+
当 TypeScript 代码需要从另一进程驱动完整 Harness 运行时、且你能显式指名运行时可执行文件时,使用本客户端。常用路径极简:用启动规格构造 `DeepSeekHarness`,运行提示词,然后关闭它,使子进程总能被回收。
|
|
31
|
+
|
|
32
|
+
### 用 DeepSeekHarness 运行 agent 轮次
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { DeepSeekHarness } from '@qilin-agent/sdk-client'
|
|
36
|
+
import { ReasoningEffortId } from '@qilin-agent/llm'
|
|
37
|
+
|
|
38
|
+
await using harness = new DeepSeekHarness({
|
|
39
|
+
profile: 'sdk',
|
|
40
|
+
patches: ['./automation.cordis.yml'],
|
|
41
|
+
provider: 'deepseek-official',
|
|
42
|
+
model: 'deepseek-v4-flash',
|
|
43
|
+
reasoningEffort: ReasoningEffortId('max'),
|
|
44
|
+
maxTokens: 49_152,
|
|
45
|
+
})
|
|
46
|
+
const result = await harness.run('say hi')
|
|
47
|
+
console.log(result.finalResponse)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
子进程在首次使用时惰性启动,并在多次 `run()` 调用之间持续归实例所有;请调用 `close()`(或使用 `await using`),子进程才总能被回收。`start()` 会记忆化有界的 `initialize` 握手,其中包含工作区 cwd、提供方/模型路由、可选且由适配器持有的 `reasoningEffort`,以及可选的正整数 `maxTokens` 输出上限。服务器会在接受提示词前校验该确切路由;省略推理强度时保留模型自身的默认值。`initializeTimeoutMs` 默认 10 秒,诊断会写明所选 profile 并附带保留的 stderr 尾部。`run(input, { sessionId?, onNotification? })` 接受文本或 `SdkPromptContentBlock[]`;内联栅格图像块携带规范 base64 与 `mimeType`,并在运行时内变成持久附件。该调用拥有一个活动区间:它将提示词排入队列,等待其消息 id 出现在持久入队回执中,然后持续收集到整个 agent 下一次进入 `idle`。它返回 `RunResult { sessionId, finalResponse, events, notifications }`,其中 `finalResponse` 是该区间内根会话最后提交的助手文本——并非因果上归属于该提示词的响应,因为 steering(中途引导)、注入的上下文和其他排队工作都可能在 idle 前参与其中。`session(id?)` 打开具名或全新的会话句柄。握手失败且清理成功时,实例会换入全新客户端,使后续调用用新进程重试,直到终结性的 `close()`;如果初始化和清理均失败,`start()` 会返回保留两个原因的有序 `AggregateError`,并继续保留失败的客户端,避免在原进程退出尚未得到证明时启动另一个进程。`maxTokens` 限制每个根 agent 请求的输出量,并由进程内后代继承;压缩(compaction)插件单独持有摘要上限。
|
|
51
|
+
|
|
52
|
+
### 用 HarnessClient 做低层控制
|
|
53
|
+
|
|
54
|
+
`HarnessClient` 是运行 API 之下的协议客户端:显式 `start()`、`initialize()`、`prompt()`、`request()` 与 `close()`,外加通知订阅。`prompt()` 在运行时接受排队消息后立即返回该消息的 id,绝不等待 agent 活动。`subscribe(filter?)` 返回 `NotificationSubscription`(可等待的 `next()`、非阻塞 `tryNext()`、异步迭代);`subscribeSessionTree(id)` 把范围限定到一个会话及从 `subagent.started` 血缘边发现的后代——运行时对上下文内每个会话都发通知,范围限定在客户端完成,与 Python SDK 完全一致。
|
|
55
|
+
|
|
56
|
+
本客户端为每种失败模式导出类型化错误:`JsonRpcResponseError`(协议错误响应,保留 code 与 data)、`RequestTimeoutError`(配置的时限已到)、`SdkProtocolError`(响应超出文档化协议)、`TransportClosedError`(运行时已消失——消息携带退出码与有界 stderr 尾部)。`close()` 先请求协议 `shutdown`(受 `shutdownTimeoutMs` 约束,默认 1000 毫秒),然后走 stdin-EOF → SIGTERM → SIGKILL 阶梯直到进程退出;幂等,已关闭的客户端拒绝复用。`HarnessClientOptions.env` 给定时整体替换子进程环境(`undefined` 原样继承父进程环境);凭据策略归调用方——`qilin-subprocess` 的 `scrubbedParentEnv` 是面向隔离启动的共享擦除基底。
|
|
57
|
+
|
|
58
|
+
-----
|
|
59
|
+
|
|
60
|
+
<a id="understand-the-implementation"></a>
|
|
61
|
+
## 理解实现
|
|
62
|
+
|
|
63
|
+
<details>
|
|
64
|
+
<summary>实现细节——点击展开</summary>
|
|
65
|
+
|
|
66
|
+
本节解释客户端背后的设计;可观察行为已在[使用本包](#use-this-package)中完整说明。
|
|
67
|
+
|
|
68
|
+
### 设计理念
|
|
69
|
+
|
|
70
|
+
客户端是同一协议上的两层:`DeepSeekHarness`(自有运行)叠加在 `HarnessClient`(协议客户端)之上,与 Python SDK 的分层一致。它运行在任何 harness 上下文之外,因此直接 spawn 运行时而非经由 `qilin-subprocess` 服务——即该 seam 记录的 SDK 托管传输例外——其关闭阶梯也位于本包。运行时对上下文内每个会话都发通知;会话树范围限定是客户端对 `subagent.started` 血缘边的过滤。
|
|
71
|
+
|
|
72
|
+
### 源码地图
|
|
73
|
+
|
|
74
|
+
| 文件 | 职责 |
|
|
75
|
+
|---|---|
|
|
76
|
+
| [`src/api.ts`](src/api.ts) | `DeepSeekHarness` + `HarnessSession`:自有运行、从回执到 idle 的收集、`finalResponse` |
|
|
77
|
+
| [`src/client.ts`](src/client.ts) | `HarnessClient`:spawn、握手、请求、订阅扇出、类型化错误 |
|
|
78
|
+
| [`src/dispose.ts`](src/dispose.ts) | 私有关闭阶梯:stdin EOF → SIGTERM → SIGKILL 直到真正退出 |
|
|
79
|
+
| [`src/types.ts`](src/types.ts) | 启动与超时选项、通知结构、`RunResult` |
|
|
80
|
+
| [`src/index.ts`](src/index.ts) | 消费方接口:两层客户端与面向调用方的类型 |
|
|
81
|
+
|
|
82
|
+
### 自有活动流程
|
|
83
|
+
|
|
84
|
+
一次运行会订阅会话树、把提示词排入队列,等待提示词的消息 id 出现在持久的 `agent/inbox/spliced` 回执中,然后持续收集通知,直到整个 agent 报告 `idle`。`finalResponse` 从收集到的事件中最后一条 `assistant/message` 派生。传输丢失、超时与协议违例会使本次运行被拒绝;模型结果仍可在事件流中观察,但不会归属于某一输入。
|
|
85
|
+
|
|
86
|
+
### 错误与关闭
|
|
87
|
+
|
|
88
|
+
每种失败模式都映射到一个导出的错误类——协议错误响应、请求时限已到、响应超出文档化协议、运行时死亡——调用方可以按失败类型分支处理;这四个类从 [src/index.ts](src/index.ts) 导出。关闭采用私有的幂等阶梯(stdin EOF → SIGTERM → SIGKILL),位于 [src/dispose.ts](src/dispose.ts),只在进程真正退出时结束。
|
|
89
|
+
|
|
90
|
+
</details>
|
|
91
|
+
|
|
92
|
+
-----
|
|
93
|
+
|
|
94
|
+
<a id="further-exploration"></a>
|
|
95
|
+
## 进一步探索
|
|
96
|
+
|
|
97
|
+
当客户端约定不够用时阅读以下页面。它们从协议格式进入服务插件与使用本客户端的应用。
|
|
98
|
+
|
|
99
|
+
- [SDK 协议格式](../protocol/README.zh.md)——本客户端使用的 JSON-RPC 方法与载荷结构。
|
|
100
|
+
- [JSON-RPC 服务插件](../server/README.zh.md)——服务本客户端的运行时插件。
|
|
101
|
+
- [Python SDK](../../../python/README.zh.md) — 共享同一运行时对端与协议的设计孪生。
|
|
102
|
+
- [SDK subagent 后端](../../subagent/subagent-qilin-sdk/README.zh.md) — harness 内部消费本客户端的例子。
|
|
103
|
+
- [SDK 应用组合包](../../bundle/sdk-app/README.zh.md) — 本客户端启动的 `qilin --profile sdk` 运行时应用。
|
|
104
|
+
|
|
105
|
+
-----
|
|
106
|
+
|
|
107
|
+
<a id="model-experience"></a>
|
|
108
|
+
## 模型体验
|
|
109
|
+
|
|
110
|
+
无,因为这是客户端进程库;模型可见行为存在于所 spawn 运行时组合的插件中。
|
|
111
|
+
|
|
112
|
+
#### KV Cache 影响
|
|
113
|
+
|
|
114
|
+
客户端进程中无影响。子进程的 profile、patch、提供方、模型与历史决定缓存复用。
|
|
115
|
+
|
|
116
|
+
## 已知限制与延期工作
|
|
117
|
+
|
|
118
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
这些限制说明本客户端何时不合适或需要特别注意。它们是当前包约束,不是与其他 SDK 客户端的对比或任务积压。
|
|
122
|
+
|
|
123
|
+
- **无捆绑运行时解析**——客户端解析同版本 `@qilin-agent/cli` 包(或调用方提供的 `qilinBin`);打包可执行文件的发现留在 Python 侧,直到出现 TypeScript 发行版消费方。
|
|
124
|
+
- **无轮次中取消**——协议层没有提示词取消方法;放弃轮次意味着关闭运行时(见[协议限制](../protocol/README.zh.md#known-limitations-and-deferred-work))。
|
|
125
|
+
- **没有逐提示词结果**——低层 `prompt()` 只返回入队回执;高层 `run()` 负责从回执到 idle 的收集,放弃该过程意味着关闭运行时。
|
|
126
|
+
- **客户端→服务端通知与服务端→客户端请求**在协议两端都未实现;传输层为未来审批流程保留了承载能力。
|
|
127
|
+
|
|
128
|
+
<a id="dev-note"></a>
|
|
129
|
+
### 开发备注
|
|
130
|
+
|
|
131
|
+
<details>
|
|
132
|
+
<summary>维护者的工作上下文——点击展开</summary>
|
|
133
|
+
|
|
134
|
+
本开发备注是维护者的工作上下文,明确不具权威性——已交付的行为与限制见上文各节与代码。启动规格有意保持完全显式:在出现 TypeScript 发行版消费方之前,不计划做捆绑运行时解析。请让关闭阶梯与错误词汇与驱动同一运行时的 Python 客户端保持同步。没有记录其他未解决的开放设计问题。
|
|
135
|
+
|
|
136
|
+
</details>
|