{"_id":"@buddhilive/dsh-tool-ask-user","name":"@buddhilive/dsh-tool-ask-user","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-tool-ask-user","description":"Model-facing ask_user_question tool over the ctx.userQuestions seam","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/interaction/tool-ask-user"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-user-questions":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"devDependencies":{"@buddhilive/dsh-llm":"^0.1.2-alpha.3","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-system-prompt":"^0.1.2-alpha.3","@buddhilive/dsh-agent":"^0.1.2-alpha.3","@buddhilive/dsh-tools":"^0.1.2-alpha.3","@buddhilive/dsh-user-questions":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-tool-ask-user@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-zllG13aeBpuZdd+izdIQXCLQFhRYD363i4DukbOv2eiu8Lhuuf3MEw6QrvKItmDM6byDq4dZtiGHVKuCKUENig==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-tool-ask-user-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-tool-ask-user-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-zllG13aeBpuZdd+izdIQXCLQFhRYD363i4DukbOv2eiu8Lhuuf3MEw6QrvKItmDM6byDq4dZtiGHVKuCKUENig==","shasum":"4bc3965c2f02dd2d5ce910671feb7663bb8e9e18","tarball":"https://registry.npmjs.org/@buddhilive/dsh-tool-ask-user/-/dsh-tool-ask-user-0.1.2-alpha.3.tgz","fileCount":9,"unpackedSize":22919,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCdvRNUasI3DvnpMe0UjxD54v81yC2wicBN6sxi4+egawIhAKqA+NpmJA4iWKe1w74AbTvsA94f29EBF9qAtMkbt88y"}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-tool-ask-user_0.1.2-alpha.3_1788166619323_0.40337194756443884"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:56:59.001Z","0.1.2-alpha.3":"2026-08-31T08:56:59.442Z","modified":"2026-08-31T08:56:59.737Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Model-facing ask_user_question tool over the ctx.userQuestions seam","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/interaction/tool-ask-user"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"基于用户交互 seam 的模型侧 ask_user_question 工具；供组合或排查交互式 agent 表面的用户与维护者阅读。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-tool-ask-user\n\n[English](README.md) | 中文\n\n## 概述\n\n`dsh-tool-ask-user` 为模型提供一个工具——`ask_user_question`——用于在需要确认、选择结果或缺失的信息才能继续时，向用户提出简明问题。工具会暂停，直到首个作用域 answerer 接受请求，然后把回答作为普通工具结果送回 agent loop（智能体循环），因此循环机制没有任何变化。工具返回规范的 `{ answers: [...] }` 结构，并以紧凑的 JSON 文本形式呈现。它自身不渲染 UI，也不了解输入的收集方式；Web Client 通过 Remote Events 提供 answerer。运行时中归属于其他 agent 的子级不能向用户提问；它必须在最终结果中包含尚未解决的问题。\n\n## 目录\n\n- [使用本包](#use-this-package)\n- [理解实现](#understand-the-implementation)\n- [进一步探索](#further-exploration)\n- [模型体验](#model-experience)\n- [已知限制与延期工作](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"use-this-package\"></a>\n## 使用本包\n\n凡模型应当能够暂停等待人类决定的场景，都可组合此插件：它提供 `ask_user_question` 工具，并且需要带有接受作用域请求的 answerer 的 `ctx.userQuestions` seam。没有 answerer 接受时，工具调用会以错误失败，而不是降级。\n\n### 何时调用该工具\n\n当模型需要确认、选择结果或缺失的信息才能继续时，调用 `ask_user_question`。发送一个或多个问题，每个问题携带稳定的 `id`（回答中会原样包含）；推荐选项放在首位，并在标签末尾追加 `(Recommended)`。\n\n```json\n{\n  \"questions\": [\n    {\n      \"id\": \"cleanup\",\n      \"question\": \"Proceed with the destructive cleanup?\",\n      \"header\": \"Confirm\",\n      \"options\": [\n        { \"label\": \"Yes, delete them (Recommended)\", \"description\": \"Removes the three stale files.\" },\n        { \"label\": \"No, keep them\", \"description\": \"Aborts the cleanup.\" }\n      ]\n    }\n  ]\n}\n```\n\n### 模型得到什么\n\n工具为每个问题返回一个回答对象：`selected` 保存选中的选项标签，`custom` 携带自由填写的回答——对多选题补充 `selected`，对单选题覆盖它。Native 渲染器保留紧凑的 JSON 文本形式。\n\n```json\n{ \"answers\": [{ \"id\": \"cleanup\", \"selected\": [\"Yes, delete them (Recommended)\"] }] }\n```\n\n### 调用何时失败\n\n工具调用会阻塞到用户作答，并且只能通过当前轮次的信号取消。没有 answerer 接受、调用被中止、或调用方不是确切的存活运行时根，都会以模型在工具结果中看到的错误结算——最值得注意的是，归属于另一个 agent 的存活子级会被拒绝（`DELEGATED_CALLER`），必须在最终结果中包含尚未解决的问题或决定。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n可观察行为已在[使用本包](#use-this-package)中说明；本节解释工具定义及其与 seam 的关系。\n\n### 源码地图\n\n| 文件 | 职责 |\n|---|---|\n| [`src/index.ts`](src/index.ts) | 工具注册：`ask_user_question` schema、执行路径、结果渲染 |\n| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；执行关系由 seam 拥有） |\n\n### Consumer 角色\n\n该插件以 `['tools', 'userQuestions']` 注入，在 `ctx.tools` 上注册一个 `defineTool` 条目。`execute` 把模型参数映射为 `AskUserQuestionRequest`，转发确切的调用 agent 与当前轮次的信号，并把接受的回答映射回规范的 `answers` 数组。身份检查、意图校验、waterfall 分派与错误分类由 seam 拥有；本包只做转换。\n\n### 结果渲染\n\n`render` 输出把结构化值经 `JSON.stringify` 投影为单个文本块，因此模型侧结果是紧凑 JSON，而非更丰富的内容块词汇。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当包级约定不够用时阅读以下页面。它们从工具表面逐步进入 seam 约定及其 answerer waterfall。\n\n- [用户交互子系统参考](../../../docs/subsystems/user-questions.zh.md)——此工具背后的服务约定、问题词汇与 answerer waterfall。\n- [工具目录](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-ask-user)——生成的 `ask_user_question` schema。\n- [user-questions 包](../user-questions/README.zh.md)——本工具消费的 seam。\n- [交互组映射](../README.zh.md)——相邻的审批与命令表面。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n### 工具 schema\n\n#### 模型看到的内容\n\n模型会看到生成的 [`ask_user_question` schema](../../../docs/tool-catalog.zh.md#buddhilivedsh-tool-ask-user)，其中包含问题 id、提示语、标题、选项与多选标志。\n\n#### Token 影响\n\n工具可见时，每个请求都会产生固定的 schema token 开销。\n\n#### KV Cache 影响\n\n只要定义和可见性保持不变，前缀即可稳定复用。插件生命周期变化或作用域限制可能会使从此 schema 起的缓存复用失效。\n\n### 工具调用历史与结果\n\n#### 模型看到的内容\n\n模型提出的完整问题保留在 assistant 工具调用参数中。用户回答后，下一步会看到精确采用 `{\"answers\":[{\"id\":\"<id>\",\"selected\":[\"<label>\"],\"custom\":\"<text>\"}]}` 形式的紧凑 JSON；不使用 `custom` 时会省略该字段，`selected` 可以包含零个、一个或多个标签。调用等待期间的 UI 交互不属于模型上下文。\n\n#### Token 影响\n\n参数和回答 JSON 是依数据而定的保留 token；等待用户时不会产生 token 开销。\n\n#### KV Cache 影响\n\n仅追加；新出现的可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制说明该工具何时不合适。它们是当前包约束，不是 UI 积压事项。\n\n- **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。\n- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝归属于另一个 agent 的存活子级；该子级必须在最终结果中包含尚未解决的问题或决定。持久谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。\n- **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者的工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-e822e4ddef01670c383ac8dc236ae443"}