命名你的 Actions 和 Tools

状态：强制规范。每个 DCC-MCP crate、Python wheel 和 skill 作者 必须选择能通过 dcc_mcp_core::naming 中两个验证器的名称。 相关规范：MCP draft/server/tools#tool-names。

生态系统中存在两套命名规则。在动手之前，先搞清楚你写的字符串适用哪一套。

概念	用途	谁看到	验证器	正则
Tool name	MCP 线上可见字符串，发布在 tools/list 中	LLM / MCP 客户端	validate_tool_name	^[A-Za-z0-9_-]{1,64}$
Action id	内部稳定标识符，宿主用来路由 tools/call	Rust/Python 代码，手写注册	validate_action_id	^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$

为什么有两套规则？

MCP 规范对 tool name 很宽松，但常见桌面客户端会按更严格的 ^[A-Za-z0-9_-]{1,64}$ 校验。dcc-mcp-core 直接采用这条通用线上约束， 确保 tools/list 能被主流客户端接受。

因此 dcc-mcp-core 保持两层：

1. Tool names 只允许 ASCII 字母、数字、_、-，上限 64 字符。
2. Action ids 更严格：点分、小写、snake_case 段。你手写这些 ID；库在发布时将它们转换为 tool names。

使用验证器

Rust

use dcc_mcp_naming::{validate_tool_name, validate_action_id};

validate_tool_name("geometry_create_sphere")?;
validate_action_id("scene.get_info")?;

两个函数均为 O(n)、无内存分配，返回结构化的 NamingError，指向第一个违规位置。

Python

from dcc_mcp_core import (
    TOOL_NAME_RE,
    ACTION_ID_RE,
    MAX_TOOL_NAME_LEN,
    validate_tool_name,
    validate_action_id,
)

validate_tool_name("hello-world_greet")        # 通过
validate_action_id("scene.get_info")           # 通过

validate_tool_name("bad/name")                 # 抛出 ValueError
validate_action_id("Scene.Get")                # 抛出 ValueError（大写）

正则常量（TOOL_NAME_RE、ACTION_ID_RE）导出供下游工具使用——schema 生成器、lint 规则、文档——它们需要引用模式而不调用 Rust。验证器仍然是权威检查：优先使用 validate_tool_name() 而不是在你的代码中重新实现正则。

速查表

合法的 tool names

create_sphere
geometry_create_sphere
scene_object_transform
hello-world_greet
CamelCaseTool          # MCP 允许混合大小写
_leading               # 前导 `_` 允许
-leading               # 前导 `-` 允许
0              # 单个 ASCII 字母数字也合法

非法的 tool names

输入	原因
""	空字符串
tool.name / .tool	. 不属于通用客户端安全字符集
tool/call	/ 保留给网关前缀
tool name / tool,other / tool@host / tool+v2	[_-] 之外的标点
a * 65	超过 MAX_TOOL_NAME_LEN = 64
工具 / tôol	非 ASCII

合法的 action ids

scene
create_sphere
scene.get_info
maya.geometry.create_sphere
v2.create

非法的 action ids

输入	原因
""	空字符串
Scene.get / scene.Get	大写
1scene.get	前导数字
scene..get / .scene / scene.	空的 . 分隔段
scene-get	action id 中不允许 -（用 _）
scene/get	不允许 /

上限与理由

• MAX_TOOL_NAME_LEN = 64 — 与常见桌面客户端接受的 MCP tool name 上限一致。
• 更严格的 action-id 语法 — 保持手写标识符与 Python 属性约定一致（小写、snake_case、点分命名空间），消除在审计日志、遥测和 IPC 负载中序列化 action id 时的歧义。

何时调用验证器

• 宿主作者 — 在注册时调用 validate_action_id，而不是在调度时。接受错误 id 的注册是 bug 温床。
• 服务器作者 — 在 tools/list 中发布 tool 之前调用 validate_tool_name，包括 skill 派生的 tool（其名称由 skill slug + tool slug 组成）。
• Skill 作者 — 无需显式调用；库在加载 skill 时验证你的 tool name。无效名称会导致 skill 加载失败并显示可读的错误信息。

从自定义规则迁移

早期代码路径偶尔重新发明了这些规则（子串检查、临时正则）。当你修改此类代码时，替换为验证器：

- if !name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
-     return Err("bad tool name");
- }
+ dcc_mcp_naming::validate_tool_name(name)?;

目标是一条规则，一个实现——不要在随机文件中写 name.len() > 100，不要在 crate 之间出现"我觉得应该允许连字符"的分歧。