session-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/session-create - Open a Context Session

/session-create - 开启上下文会话

Description

描述

Opens a new context session at the beginning of a leader agent's workflow. The session record tracks token usage, agent identity, and story context across multi-agent workflows. Workers inherit this session via the companion

session-inherit

skill.

Session tracking is telemetry — it must never gate or block a workflow. If the session cannot be created (DB unavailable, null return), the leader emits a warning and continues normally.

在主Agent工作流的起始阶段开启一个新的上下文会话。会话记录会跟踪多Agent工作流全流程的Token使用量、Agent身份和需求上下文。Worker可以通过配套的

session-inherit

技能继承该会话。

会话追踪属于遥测功能——绝对不能限制或阻塞工作流执行。如果无法创建会话（数据库不可用、返回空值），主Agent只需输出警告并正常继续执行即可。

Usage

使用方法

/session-create                                      # called at start of leader workflow
/session-create storyId=WINT-1234 phase=execute      # with story and phase context

/session-create                                      # 在主工作流启动时调用
/session-create storyId=WINT-1234 phase=execute      # 携带需求和阶段上下文调用

Parameters

参数

Parameter	Required	Default	Description
`agentName`	Yes	(current agent name)	The name of the leader agent opening the session
`storyId`	No	null	Story ID for this workflow (e.g. `WINT-1234` )
`phase`	No	null	Current workflow phase (e.g. `execute` , `plan` , `qa` )
`sessionId`	No	(auto-generated UUID)	Override the session UUID (rarely needed)

参数	必填	默认值	描述
`agentName`	是	(当前Agent名称)	开启会话的主Agent名称
`storyId`	否	null	本次工作流对应的需求ID（例如 `WINT-1234` ）
`phase`	否	null	当前工作流所处阶段（例如 `execute` 、 `plan` 、 `qa` ）
`sessionId`	否	(自动生成的UUID)	手动指定会话UUID（极少需要使用）

What It Does

功能说明

This skill:

Calls

mcp__postgres-knowledgebase__sessionCreate

with

agentName

storyId

, and

phase

Records the returned
```
session_id
```
and emits the structured
```
SESSION CREATED
```
output block
Handles null returns (DB error) gracefully — emits
```
SESSION UNAVAILABLE
```
and continues

本技能会执行以下操作：

传入

agentName

、

storyId

和

phase

调用

mcp__postgres-knowledgebase__sessionCreate

接口

记录返回的
```
session_id
```
并输出结构化的
```
SESSION CREATED
```
输出块
优雅处理空返回（数据库错误）——输出
```
SESSION UNAVAILABLE
```
并继续执行

Execution Steps

执行步骤

Step 1: Invoke sessionCreate

步骤1：调用sessionCreate接口

Call the MCP tool with required and optional fields:

javascript

const result = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',   // required — name of THIS agent
  storyId: 'WINT-2090',              // optional
  phase: 'execute',                  // optional
  // sessionId: crypto.randomUUID()  // omit to auto-generate
})

SessionCreateInput fields:

Field	Type	Required	Notes
`agentName`	string (min 1)	Yes	Name of the leader agent
`sessionId`	UUID string	No	Auto-generated if omitted
`storyId`	string \| null	No	Story identifier
`phase`	string \| null	No	Workflow phase label
`inputTokens`	int >= 0	No	Default: 0
`outputTokens`	int >= 0	No	Default: 0
`cachedTokens`	int >= 0	No	Default: 0
`startedAt`	Date	No	Defaults to now()

传入必填和可选字段调用MCP工具：

javascript

const result = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',   // 必填 —— 当前Agent的名称
  storyId: 'WINT-2090',              // 可选
  phase: 'execute',                  // 可选
  // sessionId: crypto.randomUUID()  // 省略则自动生成
})

SessionCreateInput 字段说明：

字段	类型	必填	说明
`agentName`	字符串（最小长度1）	是	主Agent的名称
`sessionId`	UUID字符串	否	省略则自动生成
`storyId`	字符串 \| 空	否	需求标识符
`phase`	字符串 \| 空	否	工作流阶段标签
`inputTokens`	整数 >= 0	否	默认值：0
`outputTokens`	整数 >= 0	否	默认值：0
`cachedTokens`	整数 >= 0	否	默认值：0
`startedAt`	日期	否	默认值为当前时间now()

Step 2: Handle the result

步骤2：处理返回结果

Success path —

result

is not null:

javascript

if (result && result.sessionId) {
  // Emit the structured output block (see Output section below)
}

Null-return path — DB error or connection failure:

javascript

if (result === null) {
  // Emit SESSION UNAVAILABLE warning and continue
}

成功路径 ——

result

不为空：

javascript

if (result && result.sessionId) {
  // 输出结构化输出块（参考下文输出部分）
}

空返回路径 —— 数据库错误或连接失败：

javascript

if (result === null) {
  // 输出SESSION UNAVAILABLE警告并继续执行
}

Step 3: Emit structured output

步骤3：输出结构化结果

On success, always emit the following block so workers can parse the session ID:

SESSION CREATED
  session_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  agent:      dev-execute-leader
  story_id:   WINT-2090
  phase:      execute

The
session_id
line must match the regex:
/SESSION CREATED\n\s+session_id:\s+([0-9a-f-]{36})/

调用成功时必须输出以下块，方便Worker解析会话ID：

SESSION CREATED
  session_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  agent:      dev-execute-leader
  story_id:   WINT-2090
  phase:      execute

session_id
行必须匹配正则表达式：
/SESSION CREATED\n\s+session_id:\s+([0-9a-f-]{36})/

Output

输出

Success

成功场景

After a successful

sessionCreate

call, emit:

SESSION CREATED
  session_id: {uuid returned by sessionCreate}
  agent:      {agentName}
  story_id:   {storyId or "—"}
  phase:      {phase or "—"}

sessionCreate

调用成功后输出：

SESSION CREATED
  session_id: {sessionCreate返回的uuid}
  agent:      {agentName}
  story_id:   {storyId 不存在则为 "—"}
  phase:      {phase 不存在则为 "—"}

Null Return (Graceful Degradation)

空返回场景（优雅降级）

sessionCreate

returns

null

(DB unavailable or insertion error):

SESSION UNAVAILABLE — continuing without session tracking

Then continue the workflow normally. Do not block, retry, or raise an error. Session tracking is telemetry, not a gate.

如果

sessionCreate

null

（数据库不可用或插入错误）：

SESSION UNAVAILABLE — continuing without session tracking

输出后正常继续工作流即可。不要阻塞、重试或抛出错误。会话追踪是遥测功能，不是执行前置条件。

Session Lifecycle

会话生命周期

The full session lifecycle across a multi-agent workflow:

Leader opens — calls

session-create

→

sessionCreate

→ emits

SESSION CREATED

Workers inherit — each worker calls

session-inherit

→

sessionQuery(activeOnly: true)

→ emits

SESSION INHERITED

Workers update tokens — call

sessionUpdate({ sessionId, mode: 'incremental', inputTokens, outputTokens })

Leader closes — the leader (and ONLY the leader that opened the session) calls
```
sessionComplete
```
Periodic cleanup —
```
sessionCleanup({ retentionDays: 90 })
```
archives old sessions (future: WINT-2100)

Workers MUST NOT call
sessionComplete
. See the
session-inherit
skill for the full restriction.

多Agent工作流的完整会话生命周期如下：

主Agent开启会话 —— 调用
```
session-create
```
→ 执行
```
sessionCreate
```
→ 输出
```
SESSION CREATED
```
Worker继承会话 —— 每个Worker调用
```
session-inherit
```
→ 执行
```
sessionQuery(activeOnly: true)
```
→ 输出
```
SESSION INHERITED
```

Worker更新Token用量 —— 调用

sessionUpdate({ sessionId, mode: 'incremental', inputTokens, outputTokens })

主Agent关闭会话 —— 主Agent（且仅限开启会话的主Agent）调用
```
sessionComplete
```
定期清理 ——
```
sessionCleanup({ retentionDays: 90 })
```
归档历史会话（后续迭代：WINT-2100）

Worker禁止调用
sessionComplete
。完整限制规则请查看
session-inherit
技能文档。

Graceful Degradation

优雅降级

Session tracking is purely telemetry. The following conditions must NOT block the workflow:

Condition	Behavior
DB connection unavailable	Emit `SESSION UNAVAILABLE — continuing without session tracking` and proceed
`sessionCreate` returns null	Same as above
MCP tool unavailable	Log warning, proceed without session
Network timeout	Log warning, proceed without session

The leader's downstream work (plan execution, file writes, code generation) must continue regardless of session state.

会话追踪仅为遥测功能，以下场景绝对不能阻塞工作流执行：

场景	处理逻辑
数据库连接不可用	输出 `SESSION UNAVAILABLE — continuing without session tracking` 并继续执行
`sessionCreate` 返回空值	同上
MCP工具不可用	记录警告，不启用会话功能继续执行
网络超时	记录警告，不启用会话功能继续执行

无论会话状态如何，主Agent的下游任务（计划执行、文件写入、代码生成）都必须正常执行。

Examples

示例

Minimal invocation

最简调用

javascript

const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
})
// Emits:
// SESSION CREATED
//   session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
//   agent:      dev-execute-leader
//   story_id:   —
//   phase:      —

javascript

const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
})
// 输出：
// SESSION CREATED
//   session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
//   agent:      dev-execute-leader
//   story_id:   —
//   phase:      —

Full invocation with context

携带完整上下文调用

javascript

const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
  storyId: 'WINT-2090',
  phase: 'execute',
})
// Emits:
// SESSION CREATED
//   session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
//   agent:      dev-execute-leader
//   story_id:   WINT-2090
//   phase:      execute

javascript

const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
  storyId: 'WINT-2090',
  phase: 'execute',
})
// 输出：
// SESSION CREATED
//   session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
//   agent:      dev-execute-leader
//   story_id:   WINT-2090
//   phase:      execute

Null-return path

空返回场景

javascript

const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
  storyId: 'WINT-2090',
  phase: 'execute',
})

if (!session) {
  // Emit:
  // SESSION UNAVAILABLE — continuing without session tracking
  // then continue with the rest of the workflow normally
}

javascript

const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
  storyId: 'WINT-2090',
  phase: 'execute',
})

if (!session) {
  // 输出：
  // SESSION UNAVAILABLE — continuing without session tracking
  // 然后正常继续执行剩余工作流
}

Integration Notes

集成说明

The
```
session_id
```
from
```
SESSION CREATED
```
should be passed to spawned workers via their prompt context so they can call
```
session-inherit
```
Workers use
```
sessionQuery({ activeOnly: true, limit: 50 })
```
and filter client-side — they do NOT receive a
```
sessionId
```
filter directly
The leader is solely responsible for calling
```
sessionComplete
```
at the end of its workflow

```
SESSION CREATED
```
返回的
```
session_id
```
需要通过提示词上下文传递给生成的Worker，方便它们调用
```
session-inherit
```
Worker调用
```
sessionQuery({ activeOnly: true, limit: 50 })
```
后在客户端过滤——不会直接收到
```
sessionId
```
过滤参数
主Agent全权负责在工作流结束时调用
```
sessionComplete
```