fix: guide selective file presentation through prompts
This commit is contained in:
creatixchu committed
1 parent
c19d1f12fb
commit
28fbe7433d
17 files changed
+30
-113
No files matched your search
+2
-2
@@ -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 .agents/notes/implemented/feature/2026-09-08-present-workspace-source-files.md
|
||||
2026-09-08-present-workspace-source-files.md: e1bc2bbc56d423741ca53550af2879fed3f01ecf
|
||||
2026-09-08-present-workspace-source-files.zh.md: e4f21172b36a5fef50e44a79adca71011ee90a3b
|
||||
2026-09-08-present-workspace-source-files.md: 1ab40bdf8b88c73ddb40b071281842ef7b2e3ac1
|
||||
2026-09-08-present-workspace-source-files.zh.md: 8f389b97f3a388affc3b49cbb532f69c127336fc
|
||||
@@ -12,7 +12,7 @@ Users need to open and edit the files produced in their workspace, including she
|
||||
|
||||
The [present tool](../../../../packages/deliverables/tool-present/README.md) declares existing regular source files under the [Session filesystem access policy](2026-09-09-present-filesystem-access.md). It records paths and optional descriptions without reading or copying contents. The [deliverables plugin](../../../../packages/client/ui-deliverables/README.md) opens current workspace sources in the Host's default application. Edits are visible on the next open; deletion or movement makes the declaration unavailable. File-content preservation and copy-on-write storage are deferred until a persistence design owns them.
|
||||
|
||||
The tool description requires `present` after writing a file the user asked to receive and before the final response, including files created through Bash or code execution. A prose path reference does not replace the call. The recorded [SVG delivery scenario](../../../../snapshots/web/present-svg/snapshot.yml) uses a user request that does not name `present`, and checks the resulting file, delivery event, and card. Its UI snapshot covers the expanded Chat transcript; navigation and composer controls belong to their own scenarios, so unrelated chrome changes cannot invalidate file-delivery expectations.
|
||||
The [tool description](../../../../packages/deliverables/tool-present/README.md#model-experience) guides the model’s choice of files for explicit delivery. A declaration remains distinct from a prose file reference. The recorded [SVG delivery scenario](../../../../snapshots/web/present-svg/snapshot.yml) uses a user request that does not name `present`, and checks the resulting file, delivery event, and card. Its UI snapshot covers the expanded Chat transcript; navigation and composer controls belong to their own scenarios, so unrelated chrome changes cannot invalidate file-delivery expectations.
|
||||
|
||||
The tool remains an ordinary package with shared filesystem and tool error classes. Its pure type entry owns the delivery event without importing Host code into the browser. The `standard`, `ptc`, and `cordis` presets mount it; `minimal` retains its two tools. Each plugin instance correlates its executions with successful final `tools/result` notifications before appending `deliverables/presented`. Native and nested calls share this rule. A later enclosing program failure does not revoke a completed nested declaration; blocked results publish none, and same-name scoped replacements cannot publish another instance's results.
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Status: implemented
|
||||
|
||||
[present 工具](../../../../packages/deliverables/tool-present/README.zh.md)声明交付[Session 文件系统访问策略](2026-09-09-present-filesystem-access.zh.md)允许的已有普通源文件。它记录路径和可选说明，不读取或复制内容。[交付插件](../../../../packages/client/ui-deliverables/README.zh.md)使用 Host 默认应用打开当前工作区源文件。下次打开会看到编辑后的内容；删除或移动文件会使声明不可用。文件内容保留与写时复制存储延期到有持久化设计负责时实现。
|
||||
|
||||
工具说明要求在写好用户要求接收的文件后、最终回复前调用 `present`，包括通过 Bash 或代码执行创建的文件。正文中的路径引用不能替代调用。录制的 [SVG 交付场景](../../../../snapshots/web/present-svg/snapshot.yml)使用未提及 `present` 的用户请求，检查生成文件、交付事件和卡片。其 UI 快照覆盖展开后的 Chat 对话内容；导航和输入框控件由各自场景负责，避免无关界面改动使文件交付预期失效。
|
||||
[工具说明](../../../../packages/deliverables/tool-present/README.zh.md#model-experience)指导模型选择需要显式交付的文件。交付声明与正文中的文件引用各自独立。录制的 [SVG 交付场景](../../../../snapshots/web/present-svg/snapshot.yml)使用未提及 `present` 的用户请求，检查生成文件、交付事件和卡片。其 UI 快照覆盖展开后的 Chat 对话内容；导航和输入框控件由各自场景负责，避免无关界面改动使文件交付预期失效。
|
||||
|
||||
工具保持为普通包，共享文件系统和工具错误类型。其纯类型入口拥有交付事件，不向浏览器导入 Host 代码。`standard`、`ptc` 与 `cordis` preset 挂载工具；`minimal` 保持两个工具。每个插件实例将其执行与成功的最终 `tools/result` 通知关联，再追加 `deliverables/presented`。原生与嵌套调用遵循同一规则。外层程序随后失败不会撤销已完成的嵌套声明；被阻止的结果不发布声明，同名作用域替换也不能发布其他实例的结果。
|
||||
|
||||
|
||||
@@ -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 .agents/notes/proposed/feature/2026-09-16-delivered-file-single-card.md
|
||||
2026-09-16-delivered-file-single-card.md: 65edb58a97a3c67550df37a4172863faa9d2eae4
|
||||
2026-09-16-delivered-file-single-card.zh.md: c21857071184fc3a5f4d97eb524606f465c82ae1
|
||||
@@ -1,41 +0,0 @@
|
||||
# Agent Note: One card per delivered changed file
|
||||
|
||||
Status: proposed
|
||||
|
||||
English | [中文](2026-09-16-delivered-file-single-card.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
A finished turn ends with two file surfaces: the [changed-files card](../../implemented/feature/2026-09-11-turn-changed-files-card.md) lists every file the turn changed with its line counts and opens the [review tab](../../implemented/feature/2026-09-15-changed-file-diff-preview.md) on that file, and a delivery card for every file the model declared through [present](../../implemented/feature/2026-09-08-present-workspace-source-files.md) previews it in the Sidebar and opens it natively. A file the turn both changed and delivered appears in both, and the second appearance tells the user nothing new; the recorded `changed-files-turn` scenario shows four files as four rows and four cards.
|
||||
|
||||
The two surfaces differ in what they offer and how long they live. The row carries counts and the comparison; the card carries the model's description, the preview, and the native actions. The card's content lives only in the Host process, so a conversation reopened after a Host restart has no changed-files card, while `deliverables/presented` events persist in the Session log and their cards come back.
|
||||
|
||||
## Proposal
|
||||
|
||||
Render a file the turn both changed and delivered once, on its delivery card. The changed-files card drops that file's row and keeps its header, which still names the turn's complete file count and summed counts and still opens the review on the turn; when every changed file was delivered only the header remains. The delivery card gains the file's added and deleted lines, or its binary or oversized label, beside the file name, and that label opens the review tab on the file, so the comparison, the preview, the native actions, and the description stay available from one place. Files only changed or only delivered render as before, and turns never share data.
|
||||
|
||||
Matching is lexical, on the Client, at render time: separators normalized to `/`, `.` segments dropped, `..` folded, and an absolute path under the Session working directory stated relative to it. Repeated deliveries of one file in a turn merge under the same key, keeping the latest description. Two spellings that meet only through a symbolic link stay distinct.
|
||||
|
||||
Nothing durable changes: no Session event, no Host route, and no recorder change; the merge lives in `packages/client/ui-deliverables` beside the card derivation. After a Host restart the changed-files card is absent and the delivery cards render as today, without a special case.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keeping the row and dropping the card** costs less code, but turns a deliverable's default entry from the preview into the comparison: a report or SVG becomes one diff row, and a binary deliverable becomes a `binary` label with no preview at all.
|
||||
|
||||
**Asking the model not to `present` files the changed-files card will list** cannot work: the `workspace/changes` event is never model-visible and its coverage depends on git, ignore rules, the file cap, and temporary-directory exclusion; `present` is shared by the `standard`, `ptc`, and `cordis` presets whose headless and SDK consumers have no changed-files card; and after a Host restart an undelivered file has no entry at all. The tool description also requires delivering every requested output, which the [delivery decision](../../implemented/feature/2026-09-08-present-workspace-source-files.md) settled.
|
||||
|
||||
**One combined card** that lists every changed file with delivery actions on the delivered rows would merge two surfaces with different lifetimes into one and reopen the card design; the proposal keeps both surfaces and moves only the duplicate.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- A file both changed and delivered in one turn renders one delivery card and no changed-files row; the header count and totals still cover it.
|
||||
- The delivery card shows the file's counts, and that label opens the turn's review tab on the file; preview, native actions, and the description remain.
|
||||
- Repeated deliveries of one file in a turn render one card; files with the same basename in different directories render separately.
|
||||
- Reloading the page renders the same result as the first render; after a Host restart the delivery cards render without the changed-files card.
|
||||
- The `changed-files-turn` and `present-svg` recorded scenarios and the package unit tests cover the merge.
|
||||
|
||||
## Risks
|
||||
|
||||
- A delivery spelled through a symbolic link, or with an absolute path outside the working directory that the recorder spelled differently, is not matched and renders twice; the README lists this as a known limitation.
|
||||
- A changed-files card reduced to its header may read as incomplete; the header keeps the complete count so the review still lists every file.
|
||||
- The counts label on a 60px delivery card competes for space with long file names; the design of that label is open until a design is agreed.
|
||||
@@ -1,41 +0,0 @@
|
||||
# Agent Note: 交付的改动文件只显示一张卡片
|
||||
|
||||
Status: proposed
|
||||
|
||||
[English](2026-09-16-delivered-file-single-card.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
一轮结束时有两个文件区块：[改动文件卡片](../../implemented/feature/2026-09-11-turn-changed-files-card.zh.md)列出本轮改动的每个文件及其增删行数，并在该文件上打开 [review tab](../../implemented/feature/2026-09-15-changed-file-diff-preview.zh.md)；模型通过 [present](../../implemented/feature/2026-09-08-present-workspace-source-files.zh.md) 声明的每个文件有一张交付卡片，在 Sidebar 中预览并用原生应用打开。本轮既改动又交付的文件在两处都出现，第二次出现没有给用户任何新信息；录制的 `changed-files-turn` 场景里四个文件显示为四行加四张卡片。
|
||||
|
||||
两个区块提供的东西和寿命都不同。行有行数和对比；卡片有模型写的说明、预览和原生操作。卡片的内容只活在 Host 进程里，Host 重启后重新打开的会话没有改动文件卡片，而 `deliverables/presented` 事件持久化在 Session log 里，它们的卡片会回来。
|
||||
|
||||
## 提议
|
||||
|
||||
本轮既改动又交付的文件只显示一次，显示在交付卡片上。改动文件卡片去掉该文件的行，保留头部；头部仍写本轮完整的文件数和汇总行数，仍在本轮上打开 review；所有改动文件都被交付时只剩头部。交付卡片在文件名旁补上该文件的增删行数，或二进制、过大标签，点击该标签在该文件上打开 review tab，这样对比、预览、原生操作和说明都从同一处可达。只改动或只交付的文件照旧显示，不同轮次之间不共享数据。
|
||||
|
||||
匹配在 Client 渲染时按词法进行：分隔符统一为 `/`，去掉 `.` 段，折叠 `..`，落在 Session 工作目录下的绝对路径改写为相对路径。同一轮内重复交付同一文件按同一个键合并，保留最新的说明。只经软链才相同的两种拼写保持不同。
|
||||
|
||||
持久化的东西都不变：没有新的 Session 事件、没有 Host 路由、recorder 不改；合并逻辑放在 `packages/client/ui-deliverables` 里卡片推导的旁边。Host 重启后改动文件卡片不存在，交付卡片按现在的方式渲染，不需要特殊处理。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**保留行、去掉卡片**代码更少，但交付物的默认入口从预览变成对比：一份报告或 SVG 变成一行 diff，二进制交付物变成一个「二进制」标签，完全没有预览。
|
||||
|
||||
**让模型不要 `present` 改动文件卡片会列出的文件**行不通：`workspace/changes` 事件从不进模型上下文，它的覆盖范围取决于 git、ignore 规则、文件数上限和临时目录排除；`present` 由 `standard`、`ptc`、`cordis` 三个 preset 共用，它们的 headless 和 SDK 消费者没有改动文件卡片；Host 重启后没交付的文件就没有任何入口。工具描述也要求交付用户要的每个产出，这是[交付决定](../../implemented/feature/2026-09-08-present-workspace-source-files.zh.md)定下的。
|
||||
|
||||
**一张合并卡片**，列出每个改动文件并在被交付的行上放交付操作，会把两个寿命不同的区块并成一个，并重开卡片设计；本提议保留两个区块，只挪走重复的那份。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 同一轮既改动又交付的文件只显示一张交付卡片，没有改动文件行；头部的数量和汇总仍包含它。
|
||||
- 交付卡片显示该文件的行数，点击该标签在该文件上打开本轮的 review tab；预览、原生操作和说明都保留。
|
||||
- 同一轮重复交付同一文件只显示一张卡片；不同目录下同名的文件分别显示。
|
||||
- 重新加载页面后的渲染结果与首次一致；Host 重启后交付卡片照常渲染，没有改动文件卡片。
|
||||
- `changed-files-turn` 和 `present-svg` 录制场景以及本包单测覆盖这次合并。
|
||||
|
||||
## 风险
|
||||
|
||||
- 经软链拼写的交付，或 recorder 拼法不同的工作目录外绝对路径，不会被匹配到，仍显示两次；README 把它列为已知限制。
|
||||
- 只剩头部的改动文件卡片可能显得不完整；头部保留完整数量，review 仍列出每个文件。
|
||||
- 60px 高的交付卡片上，行数标签会和长文件名争空间；该标签的样式在设计定下之前保持开放。
|
||||
@@ -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/tool-catalog.md
|
||||
tool-catalog.md: b133f9ba94276878b380999b3023210a5d627c6a
|
||||
tool-catalog.zh.md: 3f63676e4eb379163352a6c6a590f868e53f6efb
|
||||
tool-catalog.md: 232b0ea958bc5797ba2f7d0ec88437928dca89df
|
||||
tool-catalog.zh.md: 264fc1ed397ff4293afec73d9a4fd17b3c98dd5c
|
||||
@@ -627,7 +627,7 @@ The bash tool is the model-facing consumer of the bash executor seam. A `run_in_
|
||||
|
||||
### `present`
|
||||
|
||||
Declare existing files accessible through the Session filesystem as final deliverables. When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. Mentioning its path in your reply does not replace this call. The files must already exist. The user opens the current source files; their contents are not copied or preserved.
|
||||
Declare selected existing files accessible through the Session filesystem as final deliverables. Use present when the user needs a separate file deliverable, especially Office documents, spreadsheets, and slide decks. Prefer showing results in your final response when that is sufficient; creating or editing a file does not by itself require present. Usually select the 1-2 most important deliverables per call; include more when the task calls for them. The files must already exist. The user opens the current source files; their contents are not copied or preserved.
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -631,7 +631,7 @@ bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_bac
|
||||
|
||||
### `present`
|
||||
|
||||
声明交付 Session 文件系统可访问的已有文件。如果你创建或更新的文件是用户要求接收的成果，则必须在写入完成后、最终回复前调用 present，包括通过 Bash 或代码执行创建的文件。在回复中提到文件路径不能替代这次调用。文件必须已存在。用户打开当前源文件；不复制或保存其内容。
|
||||
选择 Session 文件系统可访问的已有文件，声明为最终交付物。当用户需要独立的文件交付物时使用 present，尤其是 Office 文档、电子表格和演示文稿。如果最终回复已经足够展示结果，优先在回复中展示；创建或编辑文件本身不要求调用 present。每次调用通常选择最重要的 1 至 2 项交付物，任务需要时可以更多。文件必须已存在。用户打开当前源文件；不复制或保存其内容。
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -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/client/ui-deliverables/README.md
|
||||
README.md: a5d333353bd9c342be0549c70773ed38123e0ba8
|
||||
README.zh.md: 9704b73e5377491d6379bf8cf3424b4f30b2fda0
|
||||
README.md: ff6031af2a585dc13222a2aae3de78b455db4688
|
||||
README.zh.md: 7bd20c472da8d6571518490bff73babdb1d611e7
|
||||
@@ -38,7 +38,7 @@ The `present` tool row retains the delivery-document glyph while showing running
|
||||
|
||||
Developer tools must be enabled to show this card or request its summary. Turning the preference off removes the card immediately while explicit delivery cards, inline file links, and recorded workspace changes remain available.
|
||||
|
||||
The card renders the summary the Host serves for the turn's latest `workspace/changes` announcement, read once per announcement through the authenticated summary route; while the read is pending, once the Host answers that the summary is gone, or when it lists no file, there is no card. Its header names the complete changed-file count with the summed added and deleted lines, and each row shows one file's display path with its own counts, “binary” for a binary file, or “too large” for a file the Host did not capture. Rows appear in the recorded display order, so repository files above the working directory and files outside it sort first. Three rows show before a fold; a control below reveals every recorded file and, once expanded, collapses the list again from the bottom. Each row opens the turn's review in the right Sidebar on that file, and the header opens it on the first file. The first file section starts 20px below the closing prose, a following explicit-delivery section starts 16px below the card, and the action footer starts 20px below the last file section. Final file deliveries still require `present`.
|
||||
The card renders the summary the Host serves for the turn's latest `workspace/changes` announcement, read once per announcement through the authenticated summary route; while the read is pending, once the Host answers that the summary is gone, or when it lists no file, there is no card. Its header names the complete changed-file count with the summed added and deleted lines, and each row shows one file's display path with its own counts, “binary” for a binary file, or “too large” for a file the Host did not capture. Rows appear in the recorded display order, so repository files above the working directory and files outside it sort first. Three rows show before a fold; a control below reveals every recorded file and, once expanded, collapses the list again from the bottom. Each row opens the turn's review in the right Sidebar on that file, and the header opens it on the first file. The first file section starts 20px below the closing prose, a following explicit-delivery section starts 16px below the card, and the action footer starts 20px below the last file section.
|
||||
|
||||
### The review tab
|
||||
|
||||
@@ -87,11 +87,11 @@ Read these pages when the deliverables surface is not enough. They move from the
|
||||
|
||||
#### What the model sees
|
||||
|
||||
The guidance asks the model to name primary outputs after successful creation or modification and link every existing-file mention outside commands, configuration expressions, and code blocks, including repeats and tables. Labels default to filenames or clear aliases, with only enough parent directories to distinguish files. Precise references display `filename:24` or `filename:24–30`; their destinations retain full relative or absolute paths with `#L24` or `#L24-L30` anchors. The display suffix contains neither `#` nor `L`.
|
||||
The guidance prefers primary results in the final reply: Markdown images display inline, and file links open Sidebar previews. It recommends separate `present` cards for complete file deliverables, especially Office files, usually selecting the most important one or two while allowing more when needed. It treats code changes as already having a diff view and discourages extra commands to inspect its visibility. It asks the model to link every existing-file mention outside commands, configuration expressions, and code blocks, including repeats and tables. Labels default to filenames or clear aliases, with only enough parent directories to distinguish files. Precise references display `filename:24` or `filename:24–30`; their destinations retain full relative or absolute paths with `#L24` or `#L24-L30` anchors. The display suffix contains neither `#` nor `L`.
|
||||
|
||||
#### Token effect
|
||||
|
||||
One fixed paragraph containing an output reminder and file-reference guidance whenever this package is loaded. The [present tool](../../deliverables/tool-present/README.md#model-experience) owns the delivery schema and result text.
|
||||
One fixed paragraph containing output-selection, rendering, and file-reference guidance whenever this package is loaded. The [present tool](../../deliverables/tool-present/README.md#model-experience) owns the delivery schema and result text.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
|
||||
@@ -38,7 +38,7 @@ Web 的 `standard`、`ptc` 与 `cordis` preset 提供 `present` 用于声明交
|
||||
|
||||
只有开启开发者工具才展示此卡片并请求其摘要。关闭该偏好会立即隐藏卡片，同时保留显式交付卡片、行内文件链接和已记录的工作区改动。
|
||||
|
||||
卡片渲染 Host 为本轮最新一条 `workspace/changes` 宣告提供的摘要，每条宣告通过经过认证的摘要路由读取一次；读取尚未完成、Host 答复摘要已不存在，或摘要没有列出任何文件时，没有卡片。标题给出改动文件总数与增删行数合计，每一行显示一个文件的展示路径及其增删行数，二进制文件显示“二进制”，Host 没有捕获的文件显示“过大”。行按记录的展示顺序排列，因此仓库内位于工作目录之上的文件与工作区外的文件排在最前。折叠前显示三行；下方的控件展开全部记录文件，展开后同一位置的控件从底部收起列表。每一行在右侧 Sidebar 中打开本轮的 review 并选中该文件，标题则在第一个文件上打开它。首个文件区块位于收尾正文下方 20px，后续显式交付区块位于卡片下方 16px，操作页脚位于最后一个文件区块下方 20px。最终文件交付仍需调用 `present`。
|
||||
卡片渲染 Host 为本轮最新一条 `workspace/changes` 宣告提供的摘要，每条宣告通过经过认证的摘要路由读取一次；读取尚未完成、Host 答复摘要已不存在，或摘要没有列出任何文件时，没有卡片。标题给出改动文件总数与增删行数合计，每一行显示一个文件的展示路径及其增删行数，二进制文件显示“二进制”，Host 没有捕获的文件显示“过大”。行按记录的展示顺序排列，因此仓库内位于工作目录之上的文件与工作区外的文件排在最前。折叠前显示三行；下方的控件展开全部记录文件，展开后同一位置的控件从底部收起列表。每一行在右侧 Sidebar 中打开本轮的 review 并选中该文件，标题则在第一个文件上打开它。首个文件区块位于收尾正文下方 20px，后续显式交付区块位于卡片下方 16px，操作页脚位于最后一个文件区块下方 20px。
|
||||
|
||||
### review tab
|
||||
|
||||
@@ -87,11 +87,11 @@ Node 半部注册[模型体验](#model-experience)所述的静态 `ui:deliverabl
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
提示词要求模型在成功创建或修改文件后点名主要产出，并链接命令、配置表达式和代码块以外的每次现有文件提及，包括重复提及和表格。标签默认使用文件名或清楚的别名，仅添加足以区分文件的父目录。精确引用显示为 `filename:24` 或 `filename:24–30`；目标保留完整相对路径或绝对路径，以及 `#L24` 或 `#L24-L30` 锚点。显示后缀不含 `#` 或 `L`。
|
||||
提示词建议在最终回复中展示主要结果：Markdown 图片直接显示在正文中，文件链接打开 Sidebar 预览。对于需要完整文件的交付，尤其是 Office 文件，建议使用独立的 `present` 卡片，通常选最重要的一两项，需要时可以更多。提示词按代码改动已有 diff 视图提供建议，并要求避免为确认其显示情况额外运行命令。文件引用要求链接命令、配置表达式和代码块以外的每次现有文件提及，包括重复提及和表格。标签默认使用文件名或清楚的别名，仅添加足以区分文件的父目录。精确引用显示为 `filename:24` 或 `filename:24–30`；目标保留完整相对路径或绝对路径，以及 `#L24` 或 `#L24-L30` 锚点。显示后缀不含 `#` 或 `L`。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
加载本包时增加一段包含产出提醒和文件引用指导的固定提示词。[present 工具](../../deliverables/tool-present/README.zh.md#model-experience)拥有交付 schema 和结果文本。
|
||||
加载本包时增加一段包含产出选择、渲染效果和文件引用指导的固定提示词。[present 工具](../../deliverables/tool-present/README.zh.md#model-experience)拥有交付 schema 和结果文本。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
|
||||
@@ -14,7 +14,11 @@ import { registerPresentOpen } from './present-open.ts'
|
||||
export const inject = ['systemPrompt', 'connection', 'sessionQuery', 'sessionController', 'workspaceFiles', 'fs', 'sandboxPolicy', 'workspaceChanges']
|
||||
|
||||
/** Static Web guidance for primary outputs and existing-file references. */
|
||||
const FILE_REFERENCE_PROMPT = 'When you successfully create or modify files, mention the primary outputs in your final response. '
|
||||
const FILE_REFERENCE_PROMPT = 'Prefer showing the primary results within your final response alongside a brief explanation. '
|
||||
+ 'Markdown images such as  display the image in the reply; Markdown file links such as [Report](path/to/report.html) open the file in the sidebar preview. '
|
||||
+ 'Code changes have a separate diff view; do not call present just to list edited source files, or run commands to check whether the diff will appear. '
|
||||
+ 'Use present when a separate file card helps the user open the complete deliverable, especially Office documents, spreadsheets, and slide decks. Each presented file adds a card below the reply, with preview and native-open actions. '
|
||||
+ 'Usually select the 1-2 most important deliverables; include more when the task calls for them. Avoid repeating results already shown inline unless the separate card adds useful access. '
|
||||
+ 'Outside commands, configuration expressions, and code blocks, link every mention of an existing file, including repeats and tables, to its full path relative to the working directory or absolute; append #L24 or #L24-L30 to the target for known lines. '
|
||||
+ 'Use the filename or a clear alias as the label, adding only enough parent directories to distinguish files; keep full paths out of labels. Default to the name alone; when precise locations matter, append :24 or :24–30, with no # or L in the line suffix.'
|
||||
|
||||
|
||||
@@ -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/deliverables/tool-present/README.md
|
||||
README.md: 93003711545f678336a02c9bf8589176f844af65
|
||||
README.zh.md: 161efcc3931fbf57175064ccf1179b195320d4b9
|
||||
README.md: a1b4d7d3a7cc2fa7449589667667eb322df9b3cc
|
||||
README.zh.md: 71529c5aa1b6ae4e66040fc3f2d76b3633b51262
|
||||
@@ -73,7 +73,7 @@ The pure `./types` entry declares `PresentedFile` and the Session event without
|
||||
|
||||
#### What the model sees
|
||||
|
||||
The [present schema](../../../docs/tool-catalog.md#present) asks for existing accessible files: “Declare existing files accessible through the Session filesystem as final deliverables. When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. Mentioning its path in your reply does not replace this call. The files must already exist. The user opens the current source files; their contents are not copied or preserved.” Results report `Presented <path>` for each file; the program result and durable event contain paths and optional descriptions.
|
||||
The [present schema](../../../docs/tool-catalog.md#present) asks for existing accessible files: “Declare selected existing files accessible through the Session filesystem as final deliverables. Use present when the user needs a separate file deliverable, especially Office documents, spreadsheets, and slide decks. Prefer showing results in your final response when that is sufficient; creating or editing a file does not by itself require present. Usually select the 1-2 most important deliverables per call; include more when the task calls for them. The files must already exist. The user opens the current source files; their contents are not copied or preserved.” Results report `Presented <path>` for each file; the program result and durable event contain paths and optional descriptions.
|
||||
|
||||
#### Token effect
|
||||
|
||||
|
||||
@@ -73,7 +73,7 @@ kind: "package-reference"
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
[present schema](../../../docs/tool-catalog.zh.md#present)要求已有且可访问的文件：“Declare existing files accessible through the Session filesystem as final deliverables. When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. Mentioning its path in your reply does not replace this call. The files must already exist. The user opens the current source files; their contents are not copied or preserved.” 每个文件的结果为 `Presented <path>`；程序结果和持久事件包含路径及可选说明。
|
||||
[present schema](../../../docs/tool-catalog.zh.md#present)要求已有且可访问的文件：“Declare selected existing files accessible through the Session filesystem as final deliverables. Use present when the user needs a separate file deliverable, especially Office documents, spreadsheets, and slide decks. Prefer showing results in your final response when that is sufficient; creating or editing a file does not by itself require present. Usually select the 1-2 most important deliverables per call; include more when the task calls for them. The files must already exist. The user opens the current source files; their contents are not copied or preserved.” 每个文件的结果为 `Presented <path>`；程序结果和持久事件包含路径及可选说明。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
|
||||
@@ -37,10 +37,11 @@ export function apply(ctx: Context, config: Config): void {
|
||||
const pending = new WeakMap<ToolExecution, { session: Session; turn: number; files: PresentedFile[] }>()
|
||||
ctx.tools.register(defineTool({
|
||||
name: 'present',
|
||||
description: 'Declare existing files accessible through the Session filesystem as final deliverables. '
|
||||
+ 'When a file you create or update is an output the user asked to receive, you must call present after writing it and before your final response, including files created through Bash or code execution. '
|
||||
+ 'Mentioning its path in your reply does not replace this call. The files must already exist. '
|
||||
+ 'The user opens the current source files; their contents are not copied or preserved.',
|
||||
description: 'Declare selected existing files accessible through the Session filesystem as final deliverables. '
|
||||
+ 'Use present when the user needs a separate file deliverable, especially Office documents, spreadsheets, and slide decks. '
|
||||
+ 'Prefer showing results in your final response when that is sufficient; creating or editing a file does not by itself require present. '
|
||||
+ 'Usually select the 1-2 most important deliverables per call; include more when the task calls for them. '
|
||||
+ 'The files must already exist. The user opens the current source files; their contents are not copied or preserved.',
|
||||
parameters: {
|
||||
files: {
|
||||
type: 'array', required: true,
|
||||
|
||||
Reference in new issue
Block a user