# @agent-assistant/turn-context 中文文档

规范地址：https://npmcn.com/package/%40agent-assistant/turn-context/

版本：0\.4\.37
npm 元数据更新时间：2026-10-04T06:48:55.992Z
中文译文更新时间：2026-11-05T21:48:57.834Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agent-assistant/turn-context
原文对照：https://npmcn.com/package/%40agent-assistant/turn-context/?lang=original
项目主页：https://github.com/AgentWorkforce/agent-assistant#readme
源码仓库：https://github.com/AgentWorkforce/agent-assistant

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：49.7 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-04-13T20:59:24.255Z
- 最新版本发布：2026-10-04T06:48:55.561Z
- 近 30 天下载量：15613（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 65 个）

## 中文简介

代理助理SDK的转镜上下文组件

## 安装

```sh
npm install @agent-assistant/turn-context
```

也可以使用：`pnpm add @agent-assistant/turn-context`、`yarn add @agent-assistant/turn-context`、`bun add @agent-assistant/turn-context`

## README

# `@agent-assistant/turn-context`

用于代理助理SDK的转向镜上下文组件.

* * *

## 目的

`@agent-assistant/turn-context` 是运行时间原始的,它为一个有边框的转弯组装有效的助手-向上的转弯上下文.

它坐着:

-   **上文** `@agent-assistant/traits` (计算稳定身份默认值)
-   **相邻** 记忆、政策和协调投入
-   **下级** 产品特定提示和 UX 逻辑
-   **上游** `@agent-assistant/harness`

它回答了问题:

> 鉴于这个助手,这个会话,这个会话,这些记忆,以及这些后台信号——可见的助手作为这个会话的有效角色+上下文捆绑,应该得到什么?

* * *

## 它拥有的

-   已打入转折文本组装输入
-   已打入转折文本组装输出
-   身份保留构成规则
-   携带证明浓缩容器
-   机理-投影相容性(`HarnessInstructions` + 键 `HarnessPreparedContext`(中文(简体) )

## 它不拥有的东西

-   模式执行或工具执行
-   会话持久性或内存检索
-   政策评价或核准逻辑
-   专家指挥或浓缩发现
-   产品商业规则, 即时措辞, 或域热度

* * *

## 核心设计规则

> 运行时增益会告知助手对转弯的表达;它不会取代助手身份.

组装输出保留了不同的来源:

-   稳定的身份投入
-   产品授权覆盖
-   运行时间浓缩投入
-   护栏上盖

* * *

## 安装

```bash
npm install @agent-assistant/turn-context
```

* * *

## 最小组装示例

```ts
import { createTurnContextAssembler } from '@agent-assistant/turn-context';

const assembler = createTurnContextAssembler();

const assembly = await assembler.assemble({
  assistantId: 'sage',
  turnId: 'turn-001',
  identity: {
    assistantName: 'Sage',
    baseInstructions: {
      systemPrompt: 'You are Sage, a workspace assistant.',
      developerPrompt: 'Keep answers focused and actionable.',
    },
  },
  shaping: {
    mode: 'review',
    expressionOverrides: { directness: 'high' },
  },
});
```

* * *

## 直接利用预测——需要零转变

```ts
import { createTurnContextAssembler } from '@agent-assistant/turn-context';
import { createHarness } from '@agent-assistant/harness';

const assembler = createTurnContextAssembler();
const harness = createHarness({ model: myModelAdapter });

const assembly = await assembler.assemble(input);

const result = await harness.runTurn({
  assistantId: assembly.assistantId,
  turnId: assembly.turnId,
  sessionId: assembly.sessionId,
  userId: assembly.userId,
  message: incomingMessage,
  instructions: assembly.harnessProjection.instructions,  // direct — no reshaping
  context: assembly.harnessProjection.context,            // direct — no reshaping
  continuation: input.continuation,
});
```

这个 `harnessProjection` 输出总是有效的 `HarnessInstructions` + 键 `HarnessPreparedContext`。不需要适配器或转换 `assemble()` 财务报告和审定财务报表 `harness.runTurn()`。 。 。 .

## 直接执行适配器投影

通过一个 `ExecutionAdapter` 可以将同一组件投射到 犬类 `ExecutionRequest` 形状为 `toExecutionRequest`。 。 。 .

```ts
import {
  createTurnContextAssembler,
  toExecutionRequest,
} from '@agent-assistant/turn-context';

const assembler = createTurnContextAssembler();
const assembly = await assembler.assemble(input);

const request = toExecutionRequest(assembly, incomingMessage, {
  tools: readOnlyToolDescriptors,
  requirements: { toolUse: 'allowed', traceDepth: 'standard' },
  metadata: { route: 'founder-chat' },
});

const negotiation = adapter.negotiate(request);
const result = negotiation.supported
  ? await adapter.execute(request)
  : { status: 'unsupported', degradation: negotiation.reasons };
```

投影保留了助手/会话/用户/线段代号,给出了指令,上下文 块、 响应样式、 消息元数据以及可选工具/ 要求/ 连续元数据. 执行适配器留在转折的下游;产品仍然有自己的特性和政策.

* * *

## 多源装配有内存、浓缩和护栏

```ts
const assembly = await assembler.assemble({
  assistantId: 'sage',
  turnId: 'turn-001',
  sessionId: 'session-abc',
  userId: 'user-xyz',
  identity: {
    assistantName: 'Sage',
    traits: createTraitsProvider({
      voice: 'concise',
      formality: 'professional',
      proactivity: 'medium',
      riskPosture: 'moderate',
    }),
    baseInstructions: {
      systemPrompt: 'You are Sage, a workspace assistant.',
      developerPrompt: 'Keep answers focused and actionable.',
    },
  },
  shaping: {
    mode: 'review',
    instructionOverlays: [
      { id: 'ov-1', source: 'product', text: 'Emphasize key risks.', priority: 'high' },
    ],
    expressionOverrides: { directness: 'high' },
    responseStyle: { preferMarkdown: true },
  },
  memory: {
    // Pre-retrieved candidates from your memory system
    candidates: [
      { id: 'mem-1', text: 'User prefers bullet points.', scope: 'user', relevance: 0.9 },
    ],
  },
  enrichment: {
    // Pre-packaged backstage enrichment from coordination/connectivity
    candidates: [
      {
        id: 'enr-1',
        kind: 'specialist_memo',
        source: 'reviewer',
        content: 'PR has 2 critical issues.',
        importance: 'high',
      },
    ],
  },
  guardrails: {
    overlays: [
      {
        id: 'gr-1',
        source: 'workspace',
        rule: 'Do not speculate about unverified findings.',
        kind: 'truthfulness_constraint',
        priority: 'high',
      },
    ],
  },
});

// Inspect provenance after assembly
console.log(assembly.provenance.usedMemoryIds);     // ['mem-1']
console.log(assembly.provenance.usedEnrichmentIds); // ['enr-1']
console.log(assembly.provenance.usedGuardrailIds);  // ['gr-1']

// Inspect expression profile
console.log(assembly.expression.directness);        // 'high' (from expressionOverrides)
console.log(assembly.expression.humor);             // capped by guardrail if tone_constraint present
```

* * *

## 组成规则

### 层顺序

1.  **基本身份层** —— 说 `identity.baseInstructions` + 键 `identity.traits`
2.  **转向形状** —— 说 `shaping.mode`, (中文(简体) ), `shaping.instructionOverlays`, (中文(简体) ), `shaping.expressionOverrides`
3.  **可选的背景添加** - 会话、记忆、丰富
4.  **护栏上盖** ——最后作为限制重叠,而不是政策决定
5.  **策略投影渲染**

### 身份优先权

-   基础身份是不可逾越的地层.
-   特质可以完善身份默认,但不取代由产品授权的基础指令.
-   转动成形会调制表达式,但不会重新定义助手是谁.
-   浓缩可告知上下文,但不重写身份.
-   Guardrails 限制表达,但不会成为替代身份源.

### 指令命令

系统段 : `[base-system]` (各种高低优先级)

开发者区段 : `[base-developer, ...instructionOverlays sorted by priority, mode-segment]` + 键 `[...guardrailSegments sorted by priority]` (护栏附在开发者迅速投影)

### 列入充实候选人

-   候选人 `audience: 'product'` 被排除于助理化背景(跟踪于 `droppedEnrichmentIds`) (中文(简体) ).
-   其余候选人按重要性下降排序.
-   每转弯8个浓缩块.

### 包含内存候选人

-   排序为 `relevance` 降会.
-   每转弯10个内存块.

* * *

## 非目标

这个软件包是 **没有**数字 :

-   一个内存引擎——它只接受预取的候选人
-   政策引擎——护栏形状表达式;它们不评估允许/拒绝
-   快速管理 CMS 或 DSL
-   一个专业管弦乐手——它接受预先包装的浓缩
-   模式路由器或人物系统
-   产品智能层或域热能系统
-   产品即时工艺的替换

产品仍然拥有:

-   精确的快捷文本和快速装订作者
-   特定域的浓缩排名和选择
-   哪些后台代理存在及其产出的含义
-   商业和商业升级逻辑
-   产品特定政策规则和一体化证书

* * *

## API 参考

### `createTurnContextAssembler(options?)`

回返a `TurnContextAssembler`。 。 。 .

```ts
const assembler = createTurnContextAssembler();
```

### `assembler.assemble(input: TurnContextInput): Promise<TurnContextAssembly>`

集一转上下文. 验证所需输入和投掷 `TurnContextValidationError` 失败.

**所需输入 :**

-   `assistantId` 非空字符串
-   `turnId` 非空字符串
-   `identity` 对象 `baseInstructions` 存在; 至少有一个 `systemPrompt` 或者说 `developerPrompt` 必须是非空字符串

**可选输入 :**

-   `shaping` ——转向镜产品行为塑造
-   `session` - 会话连续性信号
-   `memory.candidates` ——预回记忆文物
-   `enrichment.candidates` 预装后台浓缩
-   `guardrails.overlays` - 表达式护栏上盖
-   `continuation` - 前转接续有效载荷

### `TurnContextValidationError`

违反所需输入限制时投掷.

```ts
try {
  await assembler.assemble(input);
} catch (err) {
  if (err instanceof TurnContextValidationError) {
    console.error(err.field, err.reason);
  }
}
```

### `toExecutionRequest(assembly, userMessage, overrides?)`

项目a `TurnContextAssembly` 和传入峡谷的消息 `@agent-assistant/harness` `ExecutionRequest` 用于执行适配器.

## 常见问题

### @agent-assistant/turn-context 是什么？

代理助理SDK的转镜上下文组件

### 如何安装 @agent-assistant/turn-context？

在项目目录运行 npm install @agent-assistant/turn-context，或使用 pnpm add / yarn add / bun add。

### @agent-assistant/turn-context 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agent-assistant/turn-context 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agent-assistant/turn-context 可以商用吗？

@agent-assistant/turn-context 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-assistant/turn-context 的下载量有多少？

根据 npm 官方下载统计，@agent-assistant/turn-context 在 2026/10/05 – 2026/11/03 这 30 天内被下载 15,613 次，日均约 520 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agent-assistant/turn-context 还在维护吗？

最新版本 0\.4\.37 发布于 2026/10/04（1 个月前）；至今共发布 65 个版本，其中过去 12 个月发布了 65 个；首次发布于 2026/04/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。