feat(mcp): descriptor/jasm operand 实参接 shadow token 新槽位

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: luiox/mjbase
-          ref: 9d78607c9acd547c7646d87971477af16727b032
+          ref: 72cc5d72f79da48a6f33107103c528e9cc2d8269
           path: mjbase-src
 
       - name: Install system deps
@@ -82,7 +82,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: luiox/mjbase
-          ref: 9d78607c9acd547c7646d87971477af16727b032
+          ref: 72cc5d72f79da48a6f33107103c528e9cc2d8269
           path: mjbase-src
 
       - name: Setup xmake
@@ -130,7 +130,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: luiox/mjbase
-          ref: 9d78607c9acd547c7646d87971477af16727b032
+          ref: 72cc5d72f79da48a6f33107103c528e9cc2d8269
           path: mjbase-src
 
       - name: Setup Python 3.14 (python314.dll / include / libs for mjt-py)

mjt/mcp/src/tool/mutation.cpp

@@ -899,11 +899,22 @@ std::optional<Json> McpToolService::callMutationTool(
                 const auto slots = slot::loadWorkspaceShadowTable(*current);
                 const auto ownerInternal =
                     mjt::internalNameOfUri(classUri);
+                //描述符槽：member_descriptor 带 `${` 引用形状 → 内嵌类 handle
+                //展开；展开值参与成员核对并覆盖回 resolvedArgs（parseMutation
+                //读展开值，handle 字面量不落下游）。
+                std::string memberDescriptor;
+                if (!slot::resolveDescriptorArgument(
+                        slots,
+                        arguments.value("member_descriptor", std::string{}),
+                        memberDescriptor,
+                        slotError))
+                    return slotError;
+                resolvedArgs["member_descriptor"] = memberDescriptor;
                 slot::SlotName memberSlot;
                 if (!slot::resolveMemberSlot(slots,
                                              ownerInternal,
                                              memberName,
-                                             arguments.value("member_descriptor", std::string{}),
+                                             memberDescriptor,
                                              true,
                                              memberSlot,
                                              slotError))

mjt/mcp/src/tool/query.cpp

@@ -573,7 +573,18 @@ std::optional<Json> McpToolService::callWorkspaceQueryTool(
         //严格切换不给混搭语义）。
         const auto stringKindFilter = arguments.value("string_kind", std::string{});
         const auto mnemonicFilter   = arguments.value("mnemonic", std::string{});
-        const auto operandFilter    = arguments.value("operand", std::string{});
+        auto operandFilter          = arguments.value("operand", std::string{});
+        //JasmBody 槽：operand 过滤器带 `${` 引用形状 → 操作数行展开
+        //（类 handle / owner.name 复合 → raw 文本再子串匹配）；raw 过滤器
+        //原样直通（过滤契约零漂移）。
+        if (!operandFilter.empty() && operandFilter.find("${") != std::string::npos) {
+            const auto  slots = slot::loadWorkspaceShadowTable(*current);
+            std::string resolvedOperand;
+            Json        operandSlotError;
+            if (!slot::resolveJasmBodyArgument(slots, operandFilter, resolvedOperand, operandSlotError))
+                return operandSlotError;
+            operandFilter = std::move(resolvedOperand);
+        }
         const auto cstFilter        = arguments.value("cst", std::string{});
         const bool structured =
             !mnemonicFilter.empty() || !operandFilter.empty() || !cstFilter.empty();

mjt/mcp/src/tool/shadow_slot.cpp

@@ -145,8 +145,13 @@ bool resolveMethodSlots(const WorkspaceShadowTable& slots,
 {
     const auto ownerInput = arguments.value("owner", std::string{});
     const auto nameInput  = arguments.value("name", std::string{});
-    const auto descInput  = arguments.value("descriptor", std::string{});
-    SlotName    ownerSlot;
+    auto       descInput  = arguments.value("descriptor", std::string{});
+    //描述符槽：desc 带 `${` 引用形状 → 内嵌类 handle 展开，展开值参与
+    //成员 descHint 核对与输出；raw desc 原样直通（契约零漂移）。
+    std::string resolvedDesc;
+    if (!resolveDescriptorArgument(slots, descInput, resolvedDesc, error)) return false;
+    descInput = std::move(resolvedDesc);
+    SlotName  ownerSlot;
     if (!resolveClassSlot(slots, ownerInput, verifyRaw, ownerSlot, error)) return false;
     ownerRaw = ownerSlot.raw;
     SlotName nameSlot;
@@ -321,4 +326,42 @@ bool resolveClassUriArgument(mjt::workspace::IWorkspace& workspace,
     return resourceUriOfResolved(workspace, resolved.raw, out, error);
 }
 
+bool resolveDescriptorArgument(const WorkspaceShadowTable& slots,
+                               const std::string&          input,
+                               std::string&                out,
+                               Json&                       error)
+{
+    out = input;
+    //非引用形状（raw 描述符）直通：文法校验与 canonical 错误面在下游，
+    //既有契约零漂移。
+    if (input.empty() || input.find("${") == std::string::npos) return true;
+    mjbase::renamer::ShadowSlotQuery query;
+    query.position = mjbase::renamer::ShadowSlotPosition::Descriptor;
+    const auto result = mjbase::renamer::resolveShadowSlot(slots.table, input, query);
+    if (result.error != ShadowSlotError::None) {
+        error = errorOf(result);
+        return false;
+    }
+    out = result.raw;
+    return true;
+}
+
+bool resolveJasmBodyArgument(const WorkspaceShadowTable& slots,
+                             const std::string&          input,
+                             std::string&                out,
+                             Json&                       error)
+{
+    out = input;
+    if (input.empty() || input.find("${") == std::string::npos) return true;
+    mjbase::renamer::ShadowSlotQuery query;
+    query.position = mjbase::renamer::ShadowSlotPosition::JasmBody;
+    const auto result = mjbase::renamer::resolveShadowSlot(slots.table, input, query);
+    if (result.error != ShadowSlotError::None) {
+        error = errorOf(result);
+        return false;
+    }
+    out = result.raw;
+    return true;
+}
+
 }   //namespace mjt::mcp::slot

mjt/mcp/src/tool/shadow_slot.hpp

@@ -126,6 +126,24 @@ bool resolveClassUriArgument(mjt::workspace::IWorkspace& workspace,
                              std::string&                          out,
                              Json&                                 error);
 
+///@brief 描述符实参槽：值含 `${` 引用形状 → Descriptor 槽展开（内嵌类
+///handle → 真名，四分类错误直传）；否则原样直通（raw 描述符零漂移，其文法
+///校验与 canonical 错误面留在下游，不因槽接线收紧）。空值直通。
+///@return false 时 `error` 已填结构化 toolError。
+bool resolveDescriptorArgument(const WorkspaceShadowTable& slots,
+                               const std::string&          input,
+                               std::string&                out,
+                               Json&                       error);
+
+///@brief jasm 操作数实参槽（指令搜索 operand 过滤器用）：值含 `${` 引用
+///形状 → JasmBody 槽展开（类 handle / owner.name 复合 / 尾随描述符）；
+///否则原样直通。空值直通。
+///@return false 时 `error` 已填结构化 toolError。
+bool resolveJasmBodyArgument(const WorkspaceShadowTable& slots,
+                             const std::string&          input,
+                             std::string&                out,
+                             Json&                       error);
+
 ///@brief 显式描述符失配诊断：name 在宿主类存在但 descriptor 与任一候选都
 ///不符时，给结构化错误并列出该名全部候选描述符（与省略 descriptor 时的
 ///歧义路径同一呈现面）。name 不存在 / owner 不可解析 / descriptor 恰好命中