Merge origin/master into xtr/agent-setup-hook

This commit is contained in:
_Kerman committed 2026-09-09 17:31:17 +08:00
commit 2f7a02022a
243 files changed
+3931 -2186

No files matched your search

@@ -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/feedback/command-feedback/README.md
README.md: 83cb5b759431607a1702b2cc3038532d47db2d32
README.zh.md: 493ddf72b3b22454773dedcfbdd7d6910bf41e02
README.md: ad310f15b5b5b49fe879e063bd7d3c7c5518ebb8
README.zh.md: d0a4ab64a0f41165c291d974684cf2c7b241e7a4
+35 -13
View File
@@ -1,5 +1,5 @@
---
description: "Free-text session feedback through a `/feedback` command, for users and maintainers choosing, composing, or debugging feedback capture."
description: "Session feedback: the `/feedback` command, the `sessionFeedback` Host Remote behind the Web feedback dialog, and the fixed category taxonomy; for users and maintainers choosing, composing, or debugging feedback capture."
kind: "package-reference"
---
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
## Summary
`dsh-command-feedback` lets a user tell the harness what they think of a session: type `/feedback` plus a remark, and the remark is recorded and acknowledged. Recording is immediate and never starts model work, so it is safe at any point in a conversation — the model neither sees the remark nor is interrupted by it. The acknowledgement names the session and the anonymous user. The command ships with the Web client and needs no configuration; headless, ACP, and JSON-RPC entry points do not provide slash commands and cannot run it.
`dsh-command-feedback` lets a user tell the harness what they think of a session. Typing `/feedback` plus a remark records it and acknowledges the session and anonymous user ids; the Web feedback dialog records a category and an optional description through the `sessionFeedback` Host Remote. Recording is immediate and never starts model work: the model neither sees the remark nor is interrupted by it. The package also owns the fixed category taxonomy every feedback surface files under. It ships with the standard `dsh` base and needs no configuration; headless, ACP, and JSON-RPC entry points provide no slash commands.
## Table of Contents
@@ -38,11 +38,30 @@ Type `/feedback` followed by your remark and send it. A successful entry is ackn
Surrounding whitespace is trimmed, but the remark is otherwise kept exactly as typed: no truncation, case folding, or command parsing — `/feedback /plan felt slow` records that literal text. Each command records its own entry; nothing is merged or replaced.
<a id="the-web-feedback-dialog"></a>
### The Web feedback dialog
In the Web client a bare `/feedback` — picked from the composer menu or typed and sent without text — opens the feedback dialog instead of the usage error. The dialog offers the seven categories below and a free-text box; every field is optional and an empty submission is accepted, and the conversation log travels with the recorded event as with every feedback event. It records through `sessionFeedback.record`, which appends the same `feedback/record` event without command bookkeeping and without an acknowledgement row; the dialog shows a toast instead.
| Category id | Meaning |
|---|---|
| `task-result` | The outcome of the task |
| `instruction-following` | Understanding and following instructions |
| `product-interaction` | Product features and interaction |
| `service-stability` | Service stability |
| `resource-cost` | Resource usage and cost |
| `security-privacy-permission` | Security, privacy, and permissions |
| `other` | Anything else |
The ids are durable log vocabulary shared with per-message feedback; each surface owns its localized labels.
### Recording feedback from your own UI
Feedback does not have to come from the slash command: any UI, hook, or host integration can record a remark directly, with the same guarantees and without a model turn. A custom app that wants the slash command mounts the command registry plus this plugin:
Feedback does not have to come from the slash command or the dialog: any UI, hook, or host integration can record a remark directly through `recordFeedback` or the `sessionFeedback` Remote, with the same guarantees and without a model turn. A custom app that wants the slash command mounts the Session store, the command registry, and this plugin; the Session store is what the `sessionFeedback` Remote resolves live Sessions from:
```yaml
- id: session
name: '@deepseek-ai/dsh-session'
- id: commands
name: '@deepseek-ai/dsh-commands'
- id: command-feedback
@@ -61,17 +80,18 @@ The Web client ships the command. Headless mode, ACP automation, and JSON-RPC pr
### Design concept
The remark is one append-only fact in the session log, owned by the event rather than by the command that produced it: feedback can arrive from any trigger, so the fact must not depend on the slash command. The command keeps its own bookkeeping payload-free, so the remark text exists in exactly one place in the log, and the event never surfaces to the model.
The remark is one append-only fact in the session log, owned by the event rather than by the trigger that produced it: feedback can arrive from the command, the dialog, or any integration, so the fact must not depend on the slash command. The command keeps its own bookkeeping payload-free, so the remark text exists in exactly one place in the log, and the event never surfaces to the model.
### How a remark is recorded
The producer trims the text, rejects empty input, and writes one event into the session log; the `/feedback` handler is a thin wrapper over that same producer and starts no model work. The write is eager but not flushed: the acknowledgement means the entry reached the log, not the disk. The first accepted remark for a harness home also mints the anonymous user id the acknowledgement reports. The exact producer contract and event payload live in [`src/index.ts`](src/index.ts).
The producer trims the text, records blank text as absent, and writes one event into the session log even when the entry carries neither text nor category; the `/feedback` handler rejects empty input itself and is otherwise a thin wrapper over that same producer, and the `sessionFeedback.record` Remote resolves the live Session by id and calls it too, answering `session-not-found` when no live owner carries the id. Neither path starts model work. The write is eager but not flushed: the acknowledgement means the entry reached the log, not the disk. The first accepted command remark for a harness home also mints the anonymous user id the acknowledgement reports. The exact producer contract lives in [`src/index.ts`](src/index.ts); the event payload, the taxonomy, and the Remote vocabulary live in [`src/types.ts`](src/types.ts).
### Source map
| File | Role |
|---|---|
| [`src/index.ts`](src/index.ts) | Plugin entry: `feedback/record` event declaration, `recordFeedback` producer, `/feedback` command registration |
| [`src/index.ts`](src/index.ts) | Plugin entry: `recordFeedback` producer, the `sessionFeedback` Remote service, `/feedback` command registration |
| [`src/types.ts`](src/types.ts) | `feedback/record` event declaration, the category taxonomy, and the Remote request and result types |
| — | No runtime invariant companion is published; each `feedback/record` is an independent append-only fact with no cross-event or mutable-data relationship. |
</details>
@@ -86,6 +106,7 @@ Read these pages when the package-level contract is not enough. They cover the c
- [dsh-commands](../../interaction/commands/README.md) — the registry that discovers the global command and its `recordInput` semantics.
- [Session persistence subsystem](../../../docs/subsystems/persistence.md) — how appended events become durable and what a flush barrier means.
- [Anonymous user identity](../../identity/anonymous-user-id/README.md) — the id the acknowledgement reports.
- [ui-message-feedback](../../client/ui-message-feedback/README.md) — the Web feedback dialog that records through the `sessionFeedback` Remote.
- [Feedback package map](../README.md) — where log-only capture sits next to per-message feedback.
-----
@@ -97,7 +118,7 @@ Read these pages when the package-level contract is not enough. They cover the c
#### What the model sees
Nothing. The slash input, `feedback/record`, and the acknowledgement are absent from model requests. The feedback event and registry lifecycle records are log-only and carry no `surfaceOp`, so they never reach the ordered surface, `deriveMessages()`, or a system prompt. Recording feedback during a turn does not change that turn's remaining requests.
Nothing. The slash input, the dialog, `feedback/record`, and the acknowledgement are absent from model requests. The feedback event and registry lifecycle records are log-only and carry no `surfaceOp`, so they never reach the ordered surface, `deriveMessages()`, or a system prompt. Recording feedback during a turn does not change that turn's remaining requests.
#### Token effect
@@ -112,13 +133,14 @@ Independent of the model request path. Recording appends to the session log only
<a id="known-limitations-and-deferred-work"></a>
These limits define where `/feedback` is a poor fit or behaves differently than a user might expect. They are current package constraints, not a task backlog.
These limits define where session feedback is a poor fit or behaves differently than a user might expect. They are current package constraints, not a task backlog.
- **No feedback retrieval or management surface** — there is no retrieval, aggregation, categorization, or model-facing tool for `feedback/record`.
- **No structured fields** — an entry is one free-text string with no category, severity, or referenced-event link, so feedback cannot be filtered by subject without re-reading its text.
- **No feedback retrieval or management surface** — there is no retrieval, aggregation, or model-facing tool for `feedback/record`.
- **Category and text only** — an entry carries at most one category and one free-text string, with no severity or referenced-event link.
- **Live Sessions only through the Remote** — `sessionFeedback.record` answers `session-not-found` for a Session no live owner carries; the Web dialog reports that failure when its Session retires while it is open.
- **No amend or withdraw** — the session log is append-only and this package adds no tombstone, so a mistaken entry stays recorded and can only be superseded by a later one.
- **No explicit durability barrier** — the acknowledgement follows the append, not a flush, so an entry recorded immediately before a crash can be lost with any other unflushed tail. A consumer that needs a barrier awaits `ctx.sessions.flush(session)`.
- **No visible acknowledgement on a fresh session** — the web transcript renders command rows only once a session is active, so `/feedback` on a still-blank session records the event but shows no acknowledgement row. Recording feedback after the first message renders normally.
- **No visible acknowledgement on a fresh session** — the web transcript renders command rows only once a session is active, so a typed `/feedback <text>` on a still-blank session records the event but shows no acknowledgement row; the dialog's toast does not depend on the transcript.
- **Web only among the shipped entry points** — headless mode, ACP automation, and JSON-RPC provide no command adapter, so `/feedback` is unavailable there.
<a id="dev-note"></a>
@@ -129,7 +151,7 @@ These limits define where `/feedback` is a poor fit or behaves differently than
This Dev Note is working context for maintainers; it is explicitly non-authoritative. Shipped behavior, limits, and rationale live in the sections above and the package code.
- The acknowledgement sentences are pinned by [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts); changing them changes user-visible copy.
- Structured fields and a retrieval surface remain the open direction behind the first two limitations; nothing in the current contract reserves a format for them.
- The acknowledgement sentences and the category order are pinned by [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts); changing them changes user-visible copy.
- A retrieval surface remains the open direction behind the first limitation; nothing in the current contract reserves a format for it.
</details>
+35 -13
View File
@@ -1,5 +1,5 @@
---
description: "通过 `/feedback` 命令记录自由文本会话反馈,供用户与维护者选择、组合或排查反馈采集。"
description: "会话反馈:`/feedback` 命令、Web 反馈弹窗背后的 `sessionFeedback` Host Remote,以及固定的分类表;供用户与维护者选择、组合或排查反馈采集。"
kind: "package-reference"
---
@@ -9,7 +9,7 @@ kind: "package-reference"
## 概述
`dsh-command-feedback` 让用户告诉 harness 他们对会话的看法:输入 `/feedback` 加一条评价,评价即被记录并得到确认。记录是即时的,绝不会启动模型工作,因此在对话的任何时刻都是安全的——模型既看不到这条评价,也不会被打断。确认文本会点名会话与匿名用户。命令随 Web 客户端交付,无需任何配置;无头模式、ACP(Agent Client Protocol)与 JSON-RPC 入口不提供斜杠命令,因此无法运行它。
`dsh-command-feedback` 让用户告诉 harness 他们对会话的看法。输入 `/feedback` 加一条评价,评价即被记录,并以会话 id 与匿名用户 id 确认;Web 反馈弹窗通过 `sessionFeedback` Host Remote 记录分类与可选描述。记录是即时的,绝不会启动模型工作:模型既看不到这条评价,也不会被打断。本包同时拥有所有反馈界面共用的固定分类表。它随标准 `dsh` 基础组合交付,无需任何配置;无头模式、ACP(Agent Client Protocol)与 JSON-RPC 入口不提供斜杠命令。
## 目录
@@ -38,11 +38,30 @@ kind: "package-reference"
前后空白会被去除,但除此之外,评价会按输入原样保留:不进行截断、大小写折叠或命令解析——`/feedback /plan felt slow` 记录的就是这段字面文本。每次执行命令都会记录自己的条目;不会发生合并或替换。
<a id="the-web-feedback-dialog"></a>
### Web 反馈弹窗
在 Web 客户端中,不带文本的 `/feedback`(从输入框菜单选中,或直接输入后发送)会打开反馈弹窗,而不是返回用法错误。弹窗提供下表的七个分类和一个自由文本框;每一项都可不填,空提交也会被接受,对话日志和其他反馈事件一样随记录的事件一起投递。弹窗通过 `sessionFeedback.record` 记录,追加的是同一个 `feedback/record` 事件,但没有命令簿记,也没有确认行;弹窗改用 toast 提示。
| 分类 id | 含义 |
|---|---|
| `task-result` | 任务结果 |
| `instruction-following` | 指令理解与遵循 |
| `product-interaction` | 产品功能与交互 |
| `service-stability` | 服务稳定性 |
| `resource-cost` | 资源使用与费用 |
| `security-privacy-permission` | 安全隐私与权限 |
| `other` | 其他 |
这些 id 是日志中的持久词汇,与逐消息反馈共用;各界面自行拥有本地化标签。
### 从自己的 UI 记录反馈
反馈不一定来自斜杠命令:任何 UI、钩子或 host 集成都可以直接记录评价,享有同样的保证且无需模型轮次。想要斜杠命令的自定义应用,把命令注册表与本插件组合在一起即可:
反馈不一定来自斜杠命令或弹窗:任何 UI、钩子或 host 集成都可以通过 `recordFeedback` 或 `sessionFeedback` Remote 直接记录评价,享有同样的保证且无需模型轮次。想要斜杠命令的自定义应用,把 Session 存储、命令注册表与本插件组合在一起即可;`sessionFeedback` Remote 从 Session 存储中解析 live Session:
```yaml
- id: session
name: '@deepseek-ai/dsh-session'
- id: commands
name: '@deepseek-ai/dsh-commands'
- id: command-feedback
@@ -61,17 +80,18 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提
### 设计理念
评价是会话日志中一个仅追加的事实,由事件而非产生它的命令拥有:反馈可能来自任何触发方式,因此事实绝不能依赖斜杠命令。命令自身的簿记不携带载荷,所以评价文本在日志中只存在于一个地方,且该事件绝不会浮出到模型。
评价是会话日志中一个仅追加的事实,由事件而非产生它的触发方式拥有:反馈可能来自命令、弹窗或任何集成,因此事实绝不能依赖斜杠命令。命令自身的簿记不携带载荷,所以评价文本在日志中只存在于一个地方,且该事件绝不会浮出到模型。
### 评价如何被记录
生产方去除文本空白、拒绝空输入,并向会话日志写入一个事件;`/feedback` 处理器是该生产方的薄包装,不启动任何模型工作。写入是即时但未 flush 的:确认文本表示条目已到达日志,而不是已落盘。某个 harness home 首次接受的评价还会铸造确认文本所报告的匿名用户 id。精确的生产方约定与事件载荷见 [`src/index.ts`](src/index.ts)。
生产方去除文本空白,把空白文本记为缺省,并向会话日志写入一个事件,即使条目既无文本也无分类;`/feedback` 处理器自行拒绝空输入,其余部分是该生产方的薄包装,`sessionFeedback.record` Remote 则按 id 找到 live Session 后同样调用它,没有 live 持有者时回答 `session-not-found`。两条路径都不启动模型工作。写入是即时但未 flush 的:确认文本表示条目已到达日志,而不是已落盘。某个 harness home 首次接受的命令评价还会铸造确认文本所报告的匿名用户 id。精确的生产方约定见 [`src/index.ts`](src/index.ts);事件载荷、分类表与 Remote 词汇见 [`src/types.ts`](src/types.ts)。
### 源码地图
| 文件 | 职责 |
|---|---|
| [`src/index.ts`](src/index.ts) | 插件入口:`feedback/record` 事件声明、`recordFeedback` 生产方、`/feedback` 命令注册 |
| [`src/index.ts`](src/index.ts) | 插件入口:`recordFeedback` 生产方、`sessionFeedback` Remote 服务、`/feedback` 命令注册 |
| [`src/types.ts`](src/types.ts) | `feedback/record` 事件声明、分类表,以及 Remote 请求与结果类型 |
| — | 不发布运行时不变式伴生入口;每个事件都是独立的仅追加事实。 |
</details>
@@ -86,6 +106,7 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提
- [dsh-commands](../../interaction/commands/README.zh.md)——发现全局命令并定义 `recordInput` 语义的注册表。
- [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——追加事件如何持久化、flush 屏障的含义。
- [匿名用户身份](../../identity/anonymous-user-id/README.zh.md)——确认文本报告的 id。
- [ui-message-feedback](../../client/ui-message-feedback/README.zh.md)——通过 `sessionFeedback` Remote 记录的 Web 反馈弹窗。
- [反馈包映射](../README.zh.md)——仅写入日志的采集与逐消息反馈并存的组。
-----
@@ -97,7 +118,7 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提
#### 模型看到什么
无。斜杠输入、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志且不携带 `surfaceOp`,因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
无。斜杠输入、弹窗、`feedback/record` 以及确认文本都不出现在模型请求中。反馈事件和注册表生命周期记录仅写入日志且不携带 `surfaceOp`,因此它们绝不会进入有序 surface、`deriveMessages()` 或系统提示词。在某个轮次中记录反馈不会改变该轮次剩余的请求。
#### Token 影响
@@ -112,13 +133,14 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提
<a id="known-limitations-and-deferred-work"></a>
这些限制说明 `/feedback` 何时不合适,或何时行为与用户预期不同。它们是当前包约束,不是任务积压。
这些限制说明会话反馈何时不合适,或何时行为与用户预期不同。它们是当前包约束,不是任务积压。
- **没有反馈检索或管理 surface**——本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。
- **没有结构化字段**——一条条目就是一个自由文本字符串,没有类别、严重程度或关联事件链接,因此无法在不重读文本的情况下按主题过滤反馈。
- **没有反馈检索或管理 surface**——本包不为 `feedback/record` 提供检索、聚合或面向模型的工具。
- **只有分类与文本**——一条条目至多携带一个分类和一个自由文本字符串,没有严重程度或关联事件链接。
- **Remote 只服务 live Session**——没有 live 持有者的 Session,`sessionFeedback.record` 回答 `session-not-found`;弹窗打开期间 Session 退役时,Web 弹窗会报告该失败。
- **不支持修改或撤回**——会话日志是仅追加的,本包也不新增 tombstone,因此错误的条目会一直保留在记录中,只能由后续条目取代。
- **没有显式持久化屏障**——确认文本紧随追加而非 flush,因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。
- **新会话上没有可见的确认**——Web 转录只在会话激活后渲染命令行,因此在仍为空白的新会话上执行 `/feedback` 会记录事件但不会显示确认行。发送首条消息后再记录反馈即可正常渲染。
- **新会话上没有可见的确认**——Web 转录只在会话激活后渲染命令行,因此在仍为空白的新会话上输入 `/feedback <text>` 会记录事件但不会显示确认行;弹窗的 toast 不依赖转录。
- **随附的产品入口中只有 Web 使用此命令**——无头模式、ACP 自动化和 JSON-RPC 不提供命令适配器,因此 `/feedback` 在那里不可用。
<a id="dev-note"></a>
@@ -129,7 +151,7 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提
本开发备注是维护者的工作上下文,明确不具权威性。已交付的行为、限制与理由以上文与包代码为准。
- 确认文本句子由 [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts) 固定;修改它们会改变用户可见文案。
- 结构化字段与检索 surface 仍是前两条限制背后的开放方向;当前约定没有为它们预留任何格式。
- 确认文本句子与分类顺序由 [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts) 固定;修改它们会改变用户可见文案。
- 检索 surface 仍是第一条限制背后的开放方向;当前约定没有为它预留任何格式。
</details>
@@ -1,6 +1,6 @@
{
"name": "@deepseek-ai/dsh-command-feedback",
"description": "Log-only session feedback producer and human-facing slash command",
"description": "Log-only session feedback: the record event, the sessionFeedback Host Remote, and the human-facing slash command",
"version": "0.1.5-alpha.1",
"publishConfig": {
"access": "public"
@@ -18,19 +18,40 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
"./types": {
"types": "./lib/types/types.d.ts",
"default": "./lib/types/types.js"
},
"./typert": {
"types": "./lib/typert.host.d.ts",
"default": "./lib/typert.host.js"
},
"./remote": {
"types": "./lib/typert.remote-client.d.ts",
"default": "./lib/typert.remote-client.js"
},
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
"lib/types/**/*.d.ts"
"lib/types/**/*.js",
"lib/types/**/*.d.ts",
"lib/typert.host.js",
"lib/typert.host.d.ts",
"lib/typert.remote-client.js",
"lib/typert.remote-client.d.ts"
],
"license": "MIT",
"peerDependencies": {
"@deepseek-ai/dsh-commands": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-anonymous-user-id": "workspace:^",
"@deepseek-ai/cordis": "workspace:^"
"@deepseek-ai/cordis": "workspace:^",
"@deepseek-ai/dsh-typert-protocol": "workspace:^"
},
"dependencies": {
"zod": "^4.4.3"
},
"devDependencies": {
"@deepseek-ai/cordis-plugin-include": "workspace:^",
@@ -41,6 +62,7 @@
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-anonymous-user-id": "workspace:^",
"@deepseek-ai/cordis": "workspace:^"
"@deepseek-ai/cordis": "workspace:^",
"@deepseek-ai/dsh-typert-protocol": "workspace:^"
}
}
+77 -20
View File
@@ -1,8 +1,10 @@
/**
* Session feedback event plus the human-facing `/feedback` producer. Recording
* appends one authoritative log-only event and does not start model work. The
* append is eager but unflushed, so acknowledgement reports that the entry is
* logged, not that it reached disk.
* Session feedback: the `feedback/record` event, its command-independent
* producer, the `sessionFeedback` Host Remote a product surface records
* through, and the human-facing `/feedback` command. Recording appends one
* authoritative log-only event and does not start model work. The append is
* eager but unflushed, so acknowledgement reports that the entry is logged,
* not that it reached disk.
* @module @deepseek-ai/dsh-command-feedback
*/
@@ -10,32 +12,54 @@ import type { Context } from '@deepseek-ai/cordis'
import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands'
import type { Session } from '@deepseek-ai/dsh-session'
import { getOrCreateAnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id'
import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol'
import type {
FeedbackCategory,
FeedbackRecord,
SessionFeedbackRecordRequest,
SessionFeedbackRecordResult,
} from './types.ts'
export type * from './types.ts'
/**
* Every feedback category in the order product surfaces present them; each
* surface owns its localized labels.
*/
export const FEEDBACK_CATEGORIES = [
'task-result',
'instruction-following',
'product-interaction',
'service-stability',
'resource-cost',
'security-privacy-permission',
'other',
] as const satisfies readonly FeedbackCategory[]
export const name = 'command-feedback'
export const inject = ['commands']
const USAGE = 'Usage: /feedback <text>'
declare module '@deepseek-ai/dsh-session/types' {
interface SessionEventMap {
/**
* One recorded human remark about this session. Log-only and independent
* of its trigger; it never enters model context or derived history.
*/
'feedback/record': { text: string }
declare module '@deepseek-ai/cordis' {
interface Context {
sessionFeedback: SessionFeedbackService
}
}
/**
* Record feedback independently of any UI trigger.
* Record feedback independently of any UI trigger. Surrounding whitespace is
* discarded and a blank text is recorded as absent; an entry with neither
* text nor category is still recorded.
* @param session - session the feedback describes.
* @param text - human-authored feedback; surrounding whitespace is discarded.
* @throws {TypeError} when the normalized text is empty.
* @param entry - human-authored remark and its category.
*/
export function recordFeedback(session: Session, text: string): void {
const normalized = text.trim()
if (normalized.length === 0) throw new TypeError('feedback text must not be empty')
session.append('feedback/record', { text: normalized })
export function recordFeedback(session: Session, entry: FeedbackRecord): void {
const text = entry.text?.trim() ?? ''
session.append('feedback/record', {
...(text.length === 0 ? {} : { text }),
...(entry.category === undefined ? {} : { category: entry.category }),
})
}
/**
@@ -49,15 +73,48 @@ function executeFeedbackCommand(invocation: CommandInvocation): CommandResult {
if (invocation.rawInput.trim().length === 0) {
return { kind: 'error', text: `Feedback text is required. ${USAGE}` }
}
recordFeedback(invocation.agent.session, invocation.rawInput)
recordFeedback(invocation.agent.session, { text: invocation.rawInput })
return {
kind: 'success',
text: `Feedback recorded for session ${invocation.agent.session.id}\nAnonymous user: ${getOrCreateAnonymousUserId()}.`,
}
}
/** Register the global `/feedback` command for every composed command adapter. */
/** Host Remote through which a product surface records a Session-level remark. */
export class SessionFeedbackService extends TypertRemoteService {
static inject = ['sessions']
/**
* @param ctx - Host context carrying the live Session store.
*/
constructor(ctx: Context) {
super(ctx, 'sessionFeedback')
}
/**
* Record one remark on a live Session.
* @param request - target Session plus the optional text and category.
* @returns the recorded postcondition, or `session-not-found` when no live
* Session carries the id.
*/
@Remote('record')
record(request: SessionFeedbackRecordRequest): Promise<SessionFeedbackRecordResult> {
const session = this.ctx.sessions.get(request.sessionId)
if (session === undefined) {
return Promise.resolve({ ok: false, error: { code: 'session-not-found', sessionId: request.sessionId } })
}
recordFeedback(session, request)
return Promise.resolve({ ok: true, value: { recorded: true } })
}
}
/**
* Register the global `/feedback` command for every composed command adapter
* and mount the `sessionFeedback` Remote.
* @param ctx - Host context.
*/
export function apply(ctx: Context): void {
ctx.plugin(SessionFeedbackService)
ctx.commands.register({
name: 'feedback',
description: 'record feedback about this session',
@@ -0,0 +1,69 @@
/**
* Public vocabulary of Session-level feedback: the fixed category taxonomy,
* the `feedback/record` event payload, and the `sessionFeedback.record`
* Remote request and result types. Types only; the runtime category tuple is
* exported by the package entry, and a browser plugin imports types alone
* because its bundle may not carry Host values.
* @module @deepseek-ai/dsh-command-feedback/types
*/
import type { SessionId } from '@deepseek-ai/dsh-session/types'
/** One of the fixed feedback categories; the ids are durable log vocabulary. */
export type FeedbackCategory =
| 'task-result'
| 'instruction-following'
| 'product-interaction'
| 'service-stability'
| 'resource-cost'
| 'security-privacy-permission'
| 'other'
/**
* One recorded human remark about a Session. Both members are optional: a
* submission with neither still records that the human asked for the
* Session to be reviewed, which is what authorizes log delivery.
*/
export interface FeedbackRecord {
/** Free-text remark with surrounding whitespace removed; never empty when present. */
readonly text?: string
/** Category the human filed the remark under. */
readonly category?: FeedbackCategory
}
declare module '@deepseek-ai/dsh-session/types' {
interface SessionEventMap {
/**
* One recorded human remark about this session. Log-only and independent
* of its trigger; it never enters model context or derived history.
*/
'feedback/record': FeedbackRecord
}
}
/** Record one Session-level remark through the Host Remote. */
export interface SessionFeedbackRecordRequest {
/** Live Session the remark describes. */
readonly sessionId: SessionId
/** Free-text remark; blank text is recorded as absent. */
readonly text?: string
/** Category the human filed the remark under. */
readonly category?: FeedbackCategory
}
/** Stable postcondition of a recorded remark. */
export interface SessionFeedbackRecordValue {
/** The remark is appended to the Session log; flushing follows the Session's own schedule. */
readonly recorded: true
}
/** No live Session carries the requested id. */
export interface SessionFeedbackSessionNotFound {
readonly code: 'session-not-found'
readonly sessionId: SessionId
}
/** Result returned by the `sessionFeedback.record` operation. */
export type SessionFeedbackRecordResult =
| { readonly ok: true; readonly value: SessionFeedbackRecordValue }
| { readonly ok: false; readonly error: SessionFeedbackSessionNotFound }
@@ -6,6 +6,8 @@ import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
import CommandRuntime from '@deepseek-ai/dsh-commands'
import SessionStore, { foldSurface, Session, SessionId } from '@deepseek-ai/dsh-session'
import * as commandFeedback from '@deepseek-ai/dsh-command-feedback'
import type { FeedbackRecord } from '@deepseek-ai/dsh-command-feedback/types'
import { remoteMethods } from '@deepseek-ai/dsh-typert-protocol'
import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
const { USER_ID, getOrCreateAnonymousUserId } = vi.hoisted(() => {
@@ -72,10 +74,15 @@ async function run(test: Harness, suffix = ''): Promise<{ kind: string; text?: s
}
/** Authoritative feedback payloads in log order. */
function feedbackTexts(session: Session): string[] {
function feedbackRecords(session: Session): FeedbackRecord[] {
return session.snapshotEvents()
.filter(event => event.type === 'feedback/record')
.map(event => event.data.text)
.map(event => event.data)
}
/** The text of each authoritative feedback payload in log order. */
function feedbackTexts(session: Session): (string | undefined)[] {
return feedbackRecords(session).map(record => record.text)
}
describe('@deepseek-ai/dsh-command-feedback registration', () => {
@@ -99,6 +106,48 @@ describe('@deepseek-ai/dsh-command-feedback registration', () => {
})
})
describe('sessionFeedback Host Remote', () => {
it('publishes the exact Gateway namespace and Remote method name', async () => {
const test = await harness()
const binding = test.ctx.sessionFeedback.typertRemote
expect(binding.serviceKey).toBe('sessionFeedback')
expect(binding.namespace).toBe('sessionFeedback')
expect(remoteMethods(test.ctx.sessionFeedback)).toEqual([
{ method: 'record', invocation: { kind: 'direct' } },
])
})
it('records a remark on the live Session without command bookkeeping', async () => {
const test = await harness()
await expect(test.ctx.sessionFeedback.record({
sessionId: test.session.id, text: ' the diff view is unreadable ', category: 'product-interaction',
})).resolves.toEqual({ ok: true, value: { recorded: true } })
await expect(test.ctx.sessionFeedback.record({ sessionId: test.session.id }))
.resolves.toEqual({ ok: true, value: { recorded: true } })
expect(test.session.snapshotEvents().map(event => event.type)).toEqual(['feedback/record', 'feedback/record'])
expect(feedbackRecords(test.session)).toEqual([
{ text: 'the diff view is unreadable', category: 'product-interaction' },
{},
])
expect(getOrCreateAnonymousUserId).not.toHaveBeenCalled()
})
it('reports session-not-found for a Session no live owner carries', async () => {
const test = await harness()
const missing = SessionId('no-such-session')
await expect(test.ctx.sessionFeedback.record({ sessionId: missing, text: 'lost' }))
.resolves.toEqual({ ok: false, error: { code: 'session-not-found', sessionId: missing } })
expect(test.session.snapshotEvents()).toEqual([])
})
it('is mounted and unmounted with the plugin', async () => {
const test = await harness()
expect(test.ctx.get('sessionFeedback')).toBeDefined()
await test.plugin.dispose()
expect(test.ctx.get('sessionFeedback')).toBeUndefined()
})
})
describe('/feedback human command', () => {
it('acknowledges feedback and records its payload exactly once in the domain event', async () => {
const test = await harness()
@@ -114,12 +163,24 @@ describe('/feedback human command', () => {
it('exports a command-independent feedback producer', async () => {
const test = await harness()
commandFeedback.recordFeedback(test.session, ' recorded outside a command ')
expect(test.session.snapshotEvents().map(event => event.type)).toEqual(['feedback/record'])
expect(feedbackTexts(test.session)).toEqual(['recorded outside a command'])
expect(() => { commandFeedback.recordFeedback(test.session, ' \n\t ') })
.toThrow('feedback text must not be empty')
expect(feedbackTexts(test.session)).toEqual(['recorded outside a command'])
commandFeedback.recordFeedback(test.session, { text: ' recorded outside a command ' })
commandFeedback.recordFeedback(test.session, { text: ' \n\t ', category: 'service-stability' })
commandFeedback.recordFeedback(test.session, {})
expect(test.session.snapshotEvents().map(event => event.type))
.toEqual(['feedback/record', 'feedback/record', 'feedback/record'])
// Blank text is recorded as absent; an entry with neither member still records.
expect(feedbackRecords(test.session)).toEqual([
{ text: 'recorded outside a command' },
{ category: 'service-stability' },
{},
])
})
it('publishes the fixed category taxonomy in presentation order', () => {
expect(commandFeedback.FEEDBACK_CATEGORIES).toEqual([
'task-result', 'instruction-following', 'product-interaction', 'service-stability',
'resource-cost', 'security-privacy-permission', 'other',
])
})
it('keeps command bookkeeping around the authoritative feedback event', async () => {
@@ -22,6 +22,9 @@
},
{
"path": "../../identity/anonymous-user-id"
},
{
"path": "../../typert/protocol"
}
]
}