{"_id":"@buddhilive/dsh-client-ui-commands","name":"@buddhilive/dsh-client-ui-commands","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-client-ui-commands","description":"Client command surface: global directory cache, '/' source, three command UI kinds, popupSelect registry","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/client/ui-commands"},"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"},"./client":{"types":"./lib/types/client/index.d.ts","default":"./lib/client.js"},"./src/*":"./src/*","./package.json":"./package.json"},"dsh":{"client":{"inject":["@buddhilive/dsh-api-remotes","@buddhilive/dsh-client-locale","@buddhilive/dsh-client-ui-input-trigger","@buddhilive/dsh-client-ui-conversation"],"platform":"web"}},"license":"MIT","dependencies":{"clsx":"^2.0.0"},"peerDependencies":{"@deepseek-ai/cordis":"^4.0.2"},"devDependencies":{"@types/react":"~18.3.1","react":"^18.2.0","@buddhilive/dsh-api-remotes":"^0.1.2-alpha.3","@buddhilive/dsh-client-test-runtime":"^0.1.2-alpha.3","@buddhilive/dsh-client-connection":"^0.1.2-alpha.3","@buddhilive/dsh-client-locale":"^0.1.2-alpha.3","@buddhilive/dsh-client-ui-conversation":"^0.1.2-alpha.3","@buddhilive/dsh-client-ui-primitives":"^0.1.2-alpha.3","@buddhilive/dsh-client-ui-slots":"^0.1.2-alpha.3","@buddhilive/dsh-commands":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2","@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@buddhilive/dsh-api-session-controller":"^0.1.2-alpha.3","@buddhilive/dsh-client-ui-input-trigger":"^0.1.2-alpha.3","@buddhilive/dsh-client-store":"^0.1.2-alpha.3","@buddhilive/dsh-session":"^0.1.2-alpha.3","@buddhilive/dsh-client-ui-renderer":"^0.1.2-alpha.3","@buddhilive/dsh-client-ui-session":"^0.1.2-alpha.3"},"scripts":{"bundle":"tsdown","watch":"tsdown --watch"},"_id":"@buddhilive/dsh-client-ui-commands@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-eSRduhZuiQ7xw2xPBI5pOCSiywexAOLdJFpFulEeNn+HAC6OXaXl8CBv5ol6Boloj4kBF1hExyc9gTMLlVkOxQ==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-client-ui-commands-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-client-ui-commands-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-eSRduhZuiQ7xw2xPBI5pOCSiywexAOLdJFpFulEeNn+HAC6OXaXl8CBv5ol6Boloj4kBF1hExyc9gTMLlVkOxQ==","shasum":"be9906ff2d72344a87d73fa0bfe1b62df76af48b","tarball":"https://registry.npmjs.org/@buddhilive/dsh-client-ui-commands/-/dsh-client-ui-commands-0.1.2-alpha.3.tgz","fileCount":17,"unpackedSize":89808,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQChqoBxG3hMsnyOfzVgESaBo419jKeAfVMeVC9B/AXbMgIhAIp8Lmyv+YGrjOhgH3ZB6A38eSSx3d1IVqwa4fZYbuys"}]},"_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-client-ui-commands_0.1.2-alpha.3_1788166106453_0.8863605844789846"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:48:26.233Z","0.1.2-alpha.3":"2026-08-31T08:48:26.575Z","modified":"2026-08-31T08:48:26.827Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Client command surface: global directory cache, '/' source, three command UI kinds, popupSelect registry","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/client/ui-commands"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"Web GUI 的客户端命令 API：/ 命令 source、三类派发、会话级命令目录，以及面向业务包的 popupSelect 注册；供斜杠命令的用户与维护者阅读。\"\nkind: \"package-reference\"\n---\n\n# @buddhilive/dsh-client-ui-commands\n\n[English](README.md) | 中文\n\n## 概述\n\n在 composer 中键入 `/` 命令会打开匹配的表面——已注册的弹窗、宿主命令的输入或直接执行——命令行绝不会被静默降级为普通提示词。业务包经 `ctx.commandUi` 贡献命令表面：注册 popupSelect 贡献项（`/model`、`/permission`），或用选择器装饰既有宿主命令，宿主保留其目录行与参数声明。空格与回车对照会话目录解析命令行：带 `input` 的宿主描述符是 `leadingInput`，注册了 `CommandUiSpec` 的是 `popupSelect`，其余全部是 `execute`。\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与 `ui-input-trigger` 及 `ui-conversation` 一起挂载本插件；`/` source 随即出现在触发菜单中，业务包经 `ctx.commandUi` 注册自己的命令表面。键入 `/model` 打开已注册的弹窗；带参数声明的宿主命令打开其输入或直接执行。\n\n### 种类与装饰\n\n贡献项是客户端自有命令——与宿主命令同名会明确报错。装饰为**已存在的**宿主命令添加裸调用弹窗：宿主命令保留其目录行、参数声明与生命周期记账，被装饰的名字在会话目录中无宿主行时永不触发。菜单查询按顺序且不区分大小写地模糊匹配命令名的子序列；前缀排名最高。\n\n### 带图提交\n\ncomposer 携带图片附件提交时，只有声明了 `input.images` 的宿主命令继续；其余每条命令路径都会抛出本地化的 `imagesUnsupported` 拒绝，以瞬态 toast 呈现，草稿与图片保持原位——命令绝不消费文本却抛下图片。\n\n-----\n\n<a id=\"understand-the-implementation\"></a>\n## 理解实现\n\n<details>\n<summary>实现细节——点击展开</summary>\n\n`src/client/contract.ts` 是固定的业务约定：`CommandUiContract.register(name, spec)` 与 `decorate(name, spec)` 是业务包消费的全部内容。`CommandDirectory` 是唯一的 wire 派生缓存，以会话为 key：普通会话经 `command.list({sessionId})` 拉取；条目由转发的 `commands/change` owner 事件软失效、由 `connection/reset` 硬失效，并以 epoch 把关，被取代的旧拉取永远无法覆盖更新的结果。`matchSpace` 只凭该缓存同步应答；`matchEnter` 在 SubmitAttempt 信号上强等缓存，预热失败即拒绝。`command.execute` 返回匹配结果后，浏览器发布本地 `command/executed` 确认；其他客户端经宿主事件流收到持久命令节点，但收不到这条确认。`PopupSelectController` 是不含界面的外壳状态；`PopupSelectView` 自注册进 `conversation.input.overlay`，按会话解析。决策记录：[Web 命令表面笔记](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)；[模糊发现笔记](../../../.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md) 说明菜单排名。\n\n</details>\n\n-----\n\n<a id=\"further-exploration\"></a>\n## 进一步探索\n\n当命令面不够用时阅读以下页面。它们从命令 API 进入触发流水线与宿主命令注册表。\n\n- [ui-input-trigger](../ui-input-trigger/README.zh.md)——`/` source 注册进的流水线。\n- [ui-conversation](../ui-conversation/README.zh.md)——声明输入浮层槽位并拥有 composer。\n- [Web 命令表面与组装](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)——命令表面背后的设计决策。\n- [Web 斜杠命令模糊发现](../../../.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md)——菜单排名的原理。\n- [客户端包映射](../README.zh.md)——相邻的浏览器 UI 包。\n\n-----\n\n<a id=\"model-experience\"></a>\n## 模型体验\n\n间接影响，经由派发路径触发的宿主 `command.execute` RPC：每个命令 handler 的宿主包拥有任何模型可见效果（`/plan` 的 handler 翻转 plan 模式，其归属包注入 policy 段），而命令行、分离结果与所有菜单和 notice 渲染都留在客户端，永不进入会话日志。\n\n#### KV Cache 影响\n\n无直接影响；该包既不组装也不发送提供方请求。它触发的命令 handler 可能改变归属宿主包对下一个请求系统提示词的贡献——某个 section 的出现或消失会替换较早的请求 token，并使提供方前缀从该点起失效——但这一影响由各命令的宿主包拥有并记录。\n\n## 已知限制与延期工作\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n\n这些限制界定了当前命令表面。它们是当前包约束，不是通用命令行对比或任务积压。\n\n- **脱离会话后，分离结果 notice 回退到 console**——fire-and-forget 路径经 `SessionInput.notify` 把结果送到触发会话的 composer；会话销毁后，console 输出行是仅剩的呈现面。\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-fc60f93d8c0aa57ef9359c56def6fda2"}