docs(tools): document the abort message and the background call card; pin both with tests

This commit is contained in:
Huanqi Cao
2026-08-02 20:07:43 +08:00
parent ed39ff096f
commit efcee43c7d
11 changed files with 33 additions and 14 deletions

View File

@@ -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 packages/bash/tool-pwsh/README.md
README.md: b5acc73a68d3b309860554d4c1e8d979eb8d1eec
README.zh.md: 4d678c42194b78da8b4b10e01f8b9e666d6236d8
README.md: dfe26a63684d61dcdd6f969c2c2261dac79325c7
README.zh.md: 2344f8477e5b15f2c4d366dd82b46358eacbc1b7

View File

@@ -36,7 +36,7 @@ When `run_in_background` is true, this plugin preflights `ctx.tasks.start()` bef
## UI presentation
The tool owns its `presentCall`/`presentResult` render intent. A call is a `terminal` card carrying command, description, and optional cwd; a completed result is a `generic` card with the rendered output in a `console` fence. The bash tool's terminal card with its parsed exit-status pill has no pwsh counterpart yet — a PowerShell-aware presentation is roadmap work. These presenters are pure and replay-safe.
The tool owns its `presentCall`/`presentResult` render intent. A foreground call is a `terminal` card carrying command, description, and optional cwd; a `run_in_background` call is a `generic` card with the raw command, mirroring the bash tool's background presentation. A completed result is a `generic` card with the rendered output in a `console` fence. The bash tool's terminal card with its parsed exit-status pill has no pwsh counterpart yet — a PowerShell-aware presentation is roadmap work. These presenters are pure and replay-safe.
## Model Experience

View File

@@ -36,7 +36,7 @@
## UI presentation
工具拥有自己的 `presentCall`/`presentResult` 呈现意图。调用是携带命令、描述与可选 cwd 的 `terminal` 卡;完成的结果是以 `console` 围栏包裹渲染输出的 `generic` 卡。bash 工具那种带解析退出状态 pill 的 terminal 卡在 pwsh 侧暂无对应——PowerShell 感知的呈现属于路线图工作。这些 presenter 是纯函数且可重放。
工具拥有自己的 `presentCall`/`presentResult` 呈现意图。前台调用是携带命令、描述与可选 cwd 的 `terminal` 卡;`run_in_background` 调用是携带原始命令的 `generic` 卡,镜像 bash 工具的后台呈现。完成的结果是以 `console` 围栏包裹渲染输出的 `generic` 卡。bash 工具那种带解析退出状态 pill 的 terminal 卡在 pwsh 侧暂无对应——PowerShell 感知的呈现属于路线图工作。这些 presenter 是纯函数且可重放。
## Model Experience

View File

@@ -537,6 +537,22 @@ describe('UI presentation', () => {
.toMatchObject({ cwd: 'C:\\work' })
})
it('a background pending call renders the generic card like the bash tool', async () => {
const { ctx } = await setup()
const definition = ctx.tools.get('pwsh')
expect(definition?.presentCall?.({
command: 'Start-Sleep -Seconds 60',
description: 'long wait',
run_in_background: true,
})).toEqual({
card: 'generic',
title: 'Start-Sleep -Seconds 60',
kind: 'execute',
rawInput: 'Start-Sleep -Seconds 60',
content: [{ type: 'text', text: 'long wait' }],
})
})
it('presentResult falls back to undefined for multi-block or non-text content', async () => {
const { ctx } = await setup()
const definition = ctx.tools.get('pwsh')