实用提示：WebMCP——当网站变成人工智能工具时
《实用笔记》操作指南：WebMCP——当网站变成人工智能工具时：面向采用该模式的团队提供的合同、检查清单及可直接插入的代码模板。
可将此文档视为《WebMCP：当网站变成人工智能工具》中理念面向操作人员的重构版本：清晰的阶段划分、有序的代码模块以及便于交接时参考的恢复说明。在扩大范围之前，最好将“概览”阶段视为一个可量化的基准，记录一份最佳实践案例、一个故障实例以及对应的回滚说明。应将此阶段视为输入与经过验证的输出之间的契约，为相关成果命名、明确成功标准，并杜绝默许的半完成状态。
各部分如何相互关联
在“各组件如何协同工作”这一阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询的成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
设置步骤
在设置阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 在网关处进行身份验证，在数据层进行重新授权。仅凭承载令牌并不足以界定租户边界。
const mc = document.modelContext; // undefined if WebMCP is off
正常运行时的状态
在“功能实现”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。 在“功能实现”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入参数与经过验证的输出结果之间的契约。为相关成果命名，明确成功判定标准，杜绝无声的半完成状态。
表单本身就已经是一种工具，只需明确指出即可。
在处理“表单已是阶段”这一环节时，首先需写下相关约定：必填输入项、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试循环将会耗费大量时间。
<form id="add-form"
toolname="add-task"
tooldescription="Add a new task to the user's task board."
toolautosubmit>
<input name="title" required maxlength="80"
toolparamdescription="Short description of the task to add.">
<select name="priority"
toolparamdescription="How urgent the task is.">
<option value="low">low</option>
<option value="normal" selected>normal</option>
<option value="high">high</option>
</select>
<button type="submit">Add</button>
</form>
$('#add-form').addEventListener('submit', (e) => {
e.preventDefault();
const task = addTask(new FormData(e.target).get('title'), /* ... */);
if (!e.agentInvoked) {
e.target.reset(); // human — clear the box
} else {
e.respondWith?.(Promise.resolve(
text(`Added task #${task.id}: "${task.title}".`)
));
}
});
临时使用的工具
在使用各种工具时，首先需记录下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合规范。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。
await mc.registerTool({
name: 'list-tasks',
description: 'List the tasks on the board. Use this before acting so you know the task IDs.',
inputSchema: {
type: 'object',
properties: {
status: { type: 'string', enum: ['all', 'open', 'done'] },
},
},
annotations: { readOnlyHint: true },
async execute({ status = 'all' }) {
const rows = visible(tasks, status);
return text(rows.map((t) => `#${t.id} [${t.done ? 'x' : ' '}] ${t.title}`).join('\n'));
},
});
async execute({ id }, { signal }) {
const t = findTask(tasks, id);
if (!t) {
return text(`No task #${id}.`);
}
await sleep(3000, signal); // throws if the agent aborts
return text(
`Task #${t.id} is about ${
t.priority === 'high' ? '2 hours' : '30 minutes'
}.`
);
}
let clearCtl = null;
async function syncClearTool() {
const has = tasks.some((t) => t.done);
if (has && !clearCtl) {
const ctl = new AbortController();
clearCtl = ctl;
await mc.registerTool(
{
name: 'clear-completed',
/* ... */
},
{
signal: ctl.signal
}
);
} else if (!has && clearCtl) {
const ctl = clearCtl;
clearCtl = null;
setTimeout(() => ctl.abort(), 0); // abort() IS unregister
}
}
mc.addEventListener('toolchange', refreshTools);
这与后端MCP服务器有何不同？
在处理“何为不同之处”这一阶段时，首先需写下接口规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续的优化工作。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理时将会浪费大量时间。 在处理“何为不同之处”这一阶段时，首先需写下接口规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。
如何接入真实代理
将“如何搭建舞台”视为可度量的对象来处理时，其效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。 使用结构较为简单且带有明确副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变状态。
node agent.mjs list
node agent.mjs call add-task '{"title":"Ship the demo","priority":"high"}'
{
"mcpServers": {
"webmcp-board": {
"command": "node",
"args": ["C:\\projects\\web-mcp-demo\\mcp-bridge.mjs"],
"env": { "PAGE_URL": "https://tusharkanjariya.github.io/web-mcp-demo/" }
}
}
}
Claude Code
↓
MCP
↓
mcp-bridge.mjs
↓
Chrome DevTools Protocol
↓
WebMCP
↓
my task board
拒绝理由
将拒绝阶段视为可测量的对象来处理效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 应将配置置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 提供具有严格数据结构且带有明确副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。
Chrome与WebMCP规范存在分歧之处
将“Chrome在哪个环节出现分歧”视为可测量的指标最为有效。在扩大范围之前，先记录一份理想状态下的操作日志、一个失败案例以及回滚说明。同时记录正常流程与恢复流程的细节。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。应提供具有明确结构规范和清晰副作用标识的工具，以便主机在自动批准之前能够知道哪些调用会改变系统状态。将“Chrome在哪个环节出现分歧”视为可测量的指标最为有效。在扩大范围之前，先记录一份理想状态下的操作日志、一个失败案例以及回滚说明。应将此环节视为输入与经过验证的输出之间的契约，为相关成果命名、定义成功标准，并拒绝默许部分完成的情况。
关于产品发布的简短补充
关于阶段的问题，建议在修改代码之前先明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询的成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
那些你尚未找到合适答案的问题
对于你要上线的部分，在修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个流程即可进行审计。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
实际应要求执行的操作
在修改代码之前，需明确实际要部署的功能内容、输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。 在修改代码之前，需明确实际要部署的功能内容、输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入参数与经过验证的输出结果之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。
获取代码
在“获取代码”阶段工作时，首先需列出契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。
常见问题
在处理常见问题阶段时，首先需明确合同规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。
运营检查清单
在执行运营检查清单阶段时，同样要首先明确合同规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。
应优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应能指向具体的责任模块，而非复杂的流程链。
记录每次调用的工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试过程将会浪费大量时间。
锁定依赖版本，并记录用于运行演示的镜像摘要。可重复性远比个人经验更重要。
将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的半完成状态。
记录每次调用的工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试过程将会浪费大量时间。
在推广该技术栈之前，先冻结版本，为关键路径保存标准操作记录，并确认回滚步骤。共享环境需要设置速率限制、进行租户检查，同时明确密钥轮换的负责人。与其追求华而不实的临时演示，不如注重扎实可靠的稳定性。
a0176a78f428的批量处理说明：不要将提供者密钥放入代码仓库，设定每会话的令牌上限，并将转录内容存储在评估测试文件旁，以便后续更换模型时仍能保持可比性。
针对强化安全措施的第0阶段，在修改代码之前需明确输入内容、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。优先使用小型、可测试的单元而非冗长的脚本；当某一步骤失败时，故障原因应能指向单一责任点，而非复杂的流程问题。
强化安全措施细节0/771：需统计该步骤的运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该更改。
在处理强化措施的第一阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。
在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外费用。
强化措施细节1/771：为该环节测量实际执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该修改。
将强化措施的第二阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一个理想运行案例、一个失败案例以及回滚说明。
应同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续需要补充的内容。
强化措施细节2/771：记录该任务的执行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
在强化措施的第3阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入参数与验证后输出结果之间的契约，为相关成果命名、定义成功判定条件，并拒绝默许的不完整完成情况。
强化措施细节3/771：记录该任务的执行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
在处理强化措施的第4阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 应将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。
强化措施细节4/771：针对该措施需统计执行耗时、错误类型以及令牌使用情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第5阶段视为可测量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个失败案例以及回滚说明。 相比复杂的脚本，更应采用小型且可测试的单元。当某个步骤出现故障时，故障原因应能明确指向某个具体责任模块，而非整个混乱的流程。
强化措施细节5/771：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施的第6阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录时间以及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
强化措施细节6/771：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在处理强化措施的第7阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。
同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续才添加的完善措施。
强化措施细节7/771：需测量该阶段的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第8阶段视为一个可量化的目标面，效果最佳。在扩大范围之前，先记录一份理想的操作日志、一个故障案例以及回滚说明。
把这一阶段视为输入参数与验证后输出结果之间的契约。为相关文档命名，明确成功判定标准，杜绝无声的半完成状态。
强化细节 8/771：测量该笔记的耗时、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来决定是否保留该变更。