Command identities and composer-owned File action
命令标识与输入框拥有的文件动作
Matching a command's English description to a client dictionary makes punctuation changes affect localization and inserted command tokens. A same-name override can also copy that description without implementing the first-party command. The File menu entry needs the composer's live attachment policy, including mount, lock, and submission state; a separate command-plugin check cannot determine that state.
English
Problem
Matching a command's English description to a client dictionary makes punctuation changes affect localization and inserted command tokens. A same-name override can also copy that description without implementing the first-party command. The File menu entry needs the composer's live attachment policy, including mount, lock, and submission state; a separate command-plugin check cannot determine that state.
Decision
The command registry preserves an optional branded CommandDefinitionId as definitionId on the effective definition and descriptor. First-party producers choose their package name as the stable identity. Scoped shadowing selects the complete descriptor and never inherits the shadowed definition's identity. The identifier is discovery metadata, not an authorization claim, and does not enter command lifecycle events.
The client command directory resolves input through its private resolution.ts. Exact registered names take priority; Chinese and English aliases select only the corresponding first-party definition in the effective Session catalog. Menu claims use the current locale's spelling; typed claims retain the supplied spelling; submissions use the resolved registered name. presentation.ts owns only sections, labels, descriptions, and icons. Resolution helpers and section constants are not exported from the plugin entrypoint.
Conversation registers the File action through the injected command service and owns its localized label. The mounted input binds its file-dialog opener and one live availability query. Both menu filtering and invocation use that query, so lock, unmount, subagent, and submission state apply consistently. The binding and dispatch remain package-internal callbacks; no cross-plugin pick-files event is needed. The assembly uses a narrow structural action-registration face because command UI consumes Conversation's input types; a reverse compiler-project dependency would form a cycle. Its registration test checks against the command plugin's contribution type.
This note supersedes only identity matching, input-resolution placement, and File-action ownership in the composer menu decision. That note retains the menu, scrolling, claim-retention, and composition-timing decisions.
Alternatives considered
Match names and English descriptions. Copy is editable and can be duplicated by unrelated definitions. A stable identity separates presentation selection from copy without moving localized text onto the Host.
Match names alone. An agent-scoped override may deliberately provide a different command under the same name. It must not inherit first-party presentation or aliases unless it explicitly carries that identity.
Keep the File action in the command plugin. The input owns attachment acceptance and the DOM lifetime. Maintaining a second availability condition splits one policy between owners.
Export helpers for reuse. No production consumer needs the section constants or resolution helper as a plugin API. Tests import internal modules directly.
Consequences
First-party producers and client identity mappings must agree on stable identifiers; third-party definitions may omit them. Display copy can evolve independently. Registry tests cover descriptor preservation and shadowing; client tests cover description edits in both locales, alias resolution, and exact-name priority. Composer tests cover live availability, opener replacement, unmount, and action-registration disposal. The existing Session-driven menu and command scenarios continue to own assembled browser output.
中文
问题
用命令的英文说明匹配客户端词典，会让标点修改影响本地化和填入的命令 token。同名覆盖也可能复制这段说明，却没有实现内置命令的行为。「文件」菜单项需要输入框实时的附件策略，包括挂载、锁定和提交状态，命令插件中的另一套检查无法确定这些状态。
决策
命令注册表在有效定义和描述符上保留可选的品牌类型 CommandDefinitionId 字段 definitionId。内置命令的提供方用包名作为稳定标识。作用域覆盖选择完整描述符，不继承被遮蔽定义的标识。该标识是发现元数据，不代表授权，也不进入命令生命周期事件。
客户端命令目录通过内部的 resolution.ts 解析输入。精确注册名优先，中英文别名只选择会话有效目录中对应的内置定义。菜单认领使用当前语言的写法，手输认领保留原写法，提交使用解析到的注册名。presentation.ts 只负责分节、标题、说明和图标。解析辅助函数与小节常量不从插件入口导出。
Conversation 通过注入的命令服务注册「文件」动作，并负责其本地化标题。已挂载输入框绑定文件选择器回调和一个实时可用性查询。菜单过滤与实际调用使用同一个查询，统一处理锁定、卸载、subagent 和提交状态。绑定与调用留在包内回调中，不需要跨插件的文件选择事件。组装层使用窄的结构化动作注册接口，因为命令 UI 已消费 Conversation 的输入类型，反向增加编译项目依赖会形成循环。注册测试使用命令插件的贡献项类型进行校验。
本记录只接管输入框菜单决策中的标识匹配、输入解析归属和文件动作归属。原记录继续负责菜单、滚动、认领保留和组合输入时序的决策。
考虑过的替代方案
按名称和英文说明匹配。 文案可以修改，也可以被无关定义复制。稳定标识将展示选择与文案分开，无需把本地化文本移到宿主。
只按名称匹配。 agent（智能体）作用域覆盖可能刻意在同名下提供另一种命令。除非它显式携带对应标识，否则不应继承内置展示或别名。
把文件动作留在命令插件。 输入框负责附件接收和 DOM 生命周期。维护另一套可用性条件会把同一策略分给两个模块。
导出辅助函数以供复用。 没有生产调用方需要把小节常量或解析辅助函数作为插件 API。测试直接导入内部模块。
后果
内置命令提供方与客户端映射必须使用一致的稳定标识，第三方定义可以省略标识。显示文案可以独立调整。注册表测试覆盖描述符保留和作用域覆盖，客户端测试覆盖两种语言下修改说明、别名解析和精确名称优先。输入框测试覆盖实时可用性、回调替换、卸载和动作注册的 dispose（资源释放）。现有会话驱动的菜单和命令场景继续负责组装后的浏览器输出。