intent-engineering

intent-engineering

intent-engineering 是一个 MCP 服务，提供三个工具——audit_intent_spec、generate_intent_spec_scaffold 和 assess_retrofit_level——让任何支持 MCP 的客户端（Claude Desktop、Cursor、Anti-Gravity）都能依据一个包含 9 个部分的统一模板，审查、搭建和分流 Agent 意图规范；该模板综合了生产环境中 Agent 的研究成果。

大多数 Agent 失败并非因为推理出错，而是因为意图出了问题。规范含糊不清，缺少停止规则，结果描述的是一项活动，却伪装成一种状态。这个服务让 Agent 可以在现有运行环境中审计这一差距。完整的推理过程、被否决的替代方案，以及 v0 中可能出问题的地方，都记录在 docs/EXPLANATION.md 中。

首先，了解信任边界

• 它会审计自身，而它现在发布过错误数字，也发布过对此数字的错误更正。 在 2026-08-29 对规范技能进行完整评分后，得分为 23/25，且没有反模式。本页曾有一天声称得分为 14/25，而这一更正是基于一个 32,356 字符文件的前 10,000 个字符测得的。原始数字是正确的；更正才是错误，而这两者都源于同一个盲区。完整测量表见自测结果。
• 设计上只读。 没有工具会写入文件。改造工具只会提出建议，不会实际应用。
• 文件读取受到保护。 早期版本可以读取你提供的任意路径，因此 /etc/passwd 的确构成了信息泄露漏洞。现在，所有磁盘读取都会经过同一项防护：扩展名允许列表、符号链接解析、根目录限制和大小上限。
• 构建过程会拒绝常见的失败模式。 SDK 固定在稳定的 v1.x 系列；prepublishOnly 防护会在 src/ 中发现任何 console.log 时中止构建；变更日志规则要求：未经事先书面批准，不得更改范围。
• 明确列出限制，不加以隐藏。 仅支持 Stdio；标题解析器带有明确记录的别名表，且立场坦诚：映射器可以识别等效意图，但不会凭空编造意图。

为什么要做这个项目

问题

工程团队把 AI Agent 当作可靠的同事，但当意图描述不够明确时，Agent 会悄无声息地失败。代价是发布了无法解决正确问题的功能——而且直到进入生产环境才会发现这种失败。PM 会两次感受到这种痛苦：先是编写规范时，然后是 Agent 自信地交付了不符合目标的结果时。对于“在 Agent 执行前审计这份规范”，目前没有通用协议。

解决方案

这是一个模型上下文协议服务，提供三个工具，任何支持 MCP 的客户端（Claude Desktop、Cursor 等）都可以调用：audit_intent_spec 根据一份包含 25 项的评分标准审计规范，generate_intent_spec_scaffold 按类型搭建新规范，assess_retrofit_level 改造旧文档。项目以 @swins/intent-engineering-mcp 发布到 npm，并通过 DNS 验证的命名空间以 com.seanwinslow/intent-engineering 发布到官方 MCP 注册表。

权衡与决策

• 选择 TypeScript 而非 Python：MCP TS SDK 支持的客户端最广（Claude Desktop、Cursor），代价是无法覆盖原生使用 Python 的数据科学群体。
• 选择 stdio 传输而非 HTTP：v0 无需基础设施，但会让服务与绑定进程的客户端耦合。v1 将为云端 Agent 添加 SSE。
• 选择 DNS 验证的命名空间（com.seanwinslow/*），而非 GitHub 用户名命名空间：将品牌范围绑定到我控制的域名；这需要额外生成一对 Ed25519 密钥，并添加 apex TXT 记录，前期操作比 mcp-publisher login github 更繁琐。

我的收获

MCP 协议本质上是一份契约：“我是一个工具，大模型可以调用我，而无需我编写包装器。”理解这一点后，服务就成了现有技能之上的轻量协议适配器；我在另一个知识图谱项目中开发的可选字段模式也能直接沿用。

我犯错的那部分才是更有价值的教训，而且我一共犯了两次。最初，我发布的 dogfood 评分是 23/25。四个月后，我认定那是把部分读取结果当成了整份文件的评分，于是撤回原结果，改为发布 14/25。真正的错误是撤回：原评分针对的是整份文件，而我替换上去的数字才是部分读取结果。两个数字都曾发布，是因为工具无法说明刚刚评分的文档有多长，因此要核实任何一个数字，都得回到源文件。一个能用自己的工具自测的工具，很快就能赢得信任。一个能让作者的错误经得起证伪的工具，赢得的信任更多，而这也更难做到。

三个工具

工具	输入	输出
audit_intent_spec	一份规范（spec_text 或 file_path）	满分 25 的评分、各部分的检查结果、检测到的反模式、3 条最优建议
generate_intent_spec_scaffold	kind（blank / level-1-mvr / full-9-section），可选提示	可直接粘贴的 YAML 框架 + 后续操作
assess_retrofit_level	现有提示词或 SKILL.md	推荐的改造级别（L1 / L2 / L3），并说明影响范围、复杂度和自主性方面的理由

25 项验证清单、5 种致命反模式、4 个自主性级别和 9 部分模板，均来自规范的 intent-engineering 技能。MCP 服务是一个轻量协议适配器，并非分叉版本。

快速开始

需要 Node 20+ 和支持 MCP 的客户端（Claude Desktop、Cursor 等）。

只需添加一条配置，无需克隆。 将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "intent-engineering": {
      "command": "npx",
      "args": ["-y", "@swins/intent-engineering-mcp"]
    }
  }
}

或从源代码开始：

git clone https://github.com/seanwinslow28/sw-mcp-intent-engineering.git
cd sw-mcp-intent-engineering
npm install
npm run build

然后将配置中的 command 指向 node，并设置 args: ["<ABSOLUTE_PATH_TO_REPO>/build/index.js"]。

重启 Claude Desktop。打开 Settings → Developer，确认服务显示为 running：

随后，在任何新对话中，三个工具都会显示在工具列表的 intent-engineering 下。

试试看

连接服务后，将以下内容粘贴到 Claude Desktop：

对以下规范运行 audit_intent_spec：

## Objective
Make support tickets resolve faster.

## Outcomes
- Tickets close in <2h
- CSAT stays high

## Stop Rules
(none)

你会得到满分 25 的评分、检测到的反模式列表（这份规范至少触发了三种），以及三条具体的修正建议。完整的输入/输出契约见 docs/v0-scope.md §4。

Dogfood 测试结果，以及随之而来的更正

已于 2026-08-29 重新测量整份文件。规范的 intent-engineering SKILL.md 得分为 23/25，未检测到任何反模式。 七个部分通过，两个部分有警告，没有缺失部分。这是对全部 32,356 个字符的评分，响应中的 coverage 块也说明了这一点。

一次调用即可复现：

audit_intent_spec({ file_path: "<path>/.claude/skills/intent-engineering/SKILL.md" })

本页先是刊登了错误数字，随后又刊登了错误的更正

上文的 23/25 是本页于 2026 年 5 月发布、于 2026-08-28 撤回，并于 2026-08-29 恢复的数字。撤回才是错误。以下列出这句话背后的每项测量结果，以便核查推理，而不是只能信任它：

评分对象	分数	反模式
5 月时期的文件（17,885 个字符），全文	23/25	无
5 月时期的文件，前 10,000 个字符	17/25	1
今天的文件（32,356 个字符），全文	23/25	无
今天的文件，前 10,000 个字符	14/25	2
从文件末尾之后开始的任何读取	当时为 1/25，之后为 0/25	2

原始判断为何正确。 5 月时，这项技能有 17,885 个字符。max_length 上限为 20,000，因此整个文件可以在一次调用中读完，Phase 3 的“第一个块”就是整份文档。该次会话往返表中 1/25 的条目，是从文件末尾之后开始读取、评分字符数为零的结果，并非对真实内容的部分评分。（这个 1/25 本身也是一个小错误，已在这次重新更正的同一天修复：一个条件评分项把“不适用”当成通过，因此未识别的文档也得了一分。现在，完全没有被识别的文档会得 0/25。）

分数从未变过。 对全文评分时，这项技能在 git 历史中的每个版本都得到相同分数：

修订版本	字符数	全文得分	能否装入一次 20,000 字符的调用
ebf41b3d 2026-03-03	17,942	23/25，无反模式	能
9c76e762 2026-05-04	17,885	23/25，无反模式	能
d0117843 2026-06-10	17,900	23/25，无反模式	能
c8f90d79 2026-07-05	32,356	23/25，无反模式	不能

这个分数在五个月间始终稳定，即使文件长度几乎翻倍的提交也不例外。2026-06-17 的一次工作会话也独立确认了这一点，当时文件仍可在一次调用中读完。2026-07-05 发生变化的不是评分，而是可测量性：文件超过了上限，从那以后，单次调用再也无法验证公布的分数。

尽管如此，为何还是撤回了原判断。 到 7 月，这项技能已增长到 32,356 个字符，超过了 20,000 个字符的上限，因此无法再通过单次调用为其评分。2026-08-28 的重新测量采用默认值 10,000，得到 14/25，发现它与 23/25 不符，于是认定原始结果是把一个块误当成了文件。对错误的描述完全正确，却用在了错误的测量结果上。新结果才是那个块。

两次错误根源相同。 四个月来，这个工具无法告诉你某个分数是否涵盖整份文档，其作者也做不到。5 月的结论和 8 月的撤回都在没有明确标注这一事实的情况下发布。一个碰巧是对的，一个是错的，而这恰恰是最没用的正确方式。

作为一款规范审计工具，有两点值得直言：

• 工具从未出错；错的是解读，而且两次方向相反。 "14/25" 和 "23/25" 的字符串形式完全相同。响应中没有任何信息能区分对 10,000 个字符的评分和对 32,356 个字符的评分，因此只看一眼无法证伪这两种解读，而两者都被发布了。
• 更正本身也是一种主张，需要和它所更正的内容一样有据可查。 撤回声明写得很谨慎，引用了本次会话的表格，但它仍然是错的，因为它从未核实替代分数实际评了哪些内容。发现自己错了并非终点。用明确说明分母的测量结果发现自己错了，才是。

于 2026-08-29 修复，这也说明了为何必须修复。 audit_intent_spec 现在默认对整份文档评分，而且每个响应都会附带一个 coverage 区块，注明模式、已评分的字符数、可用字符数，以及评分是否完整。仍然可以请求部分评分，但部分评分再也不会被误认为完整评分。 在大规模场景下：同一服务评估了我的 Claude Code Superuser Pack 中全部 118 个第一方技能，耗时不到一秒，且未出现解析错误——两次测量均于 2026-08-28 重新进行（耗时 94 ms，0 个错误，对同样的 118 个文件运行 scripts/audit-superuser-pack.ts 逻辑）。在随附的 CSV examples/superuser-pack-retrofit-assessment.csv（2026-05）中，24% 评分为 L1-mvr（规范只需一个意图标题），36% 为 L2-structured（需要 Health Metrics + Decision Authority），40% 为 L3-full（自主循环或影响范围较大的技能，适合转换为 9 个章节）。这些文件按现状重新评估后，比例为 20% / 38% / 42%——变化的是语料，而不是工具。assess_retrofit_level 从未存在上文所述的隐患：它一直会读取整个文件，并明确拒绝任何超过 1 MiB 的文件，因此 CSV 中的批量评级从未基于不完整读取结果。截至 2026-08-29，audit_intent_spec 默认采用相同的全文档行为。

局限性

这项审计对标题结构有明确倾向，但现在除规范标题外，也能识别一组保守设定的别名标题——## Purpose / ## When to Use 对应 Objective，## Success Criteria / ## Definition of Done 对应 Desired Outcomes，## Completion / ## Exit Criteria 对应 Stop Rules，等等（完整对照表见 src/intent/parser.ts）。当审计根据非规范标题识别章节时，会在备注中注明，因此评分依然清晰易懂。此前，采用不同标题体系的技能得分为 1/25，因为系统无法识别其中任何现有章节；这个误报已修复。仍有两项明确边界：不属于真正意图等价项的标题（例如 ## How to Apply、## Instructions、## Usage 等流程性标题）会有意保持未映射状态，不会被错误地计入其他章节；而真正缺少九个意图章节的规范仍会得分偏低——映射器能识别等价意图，但不会凭空创造意图。

其他值得提前说明的 v0 边界：

• 只读。 没有工具会写入文件。assess_retrofit_level 只会提出建议，不会执行改造。v0.2 的 apply_retrofit 会要求用户明确确认才能运行。
• 仅支持 Stdio 传输。 不支持 Streamable HTTP、SSE 或远程托管。请在客户端旁边本地运行。
• 不提供 prompts 或 resources 基元。 只有三个工具，不多不少。在接口稳定之前添加更多内容为时尚早。

项目布局

sw-mcp-intent-engineering/
├── src/
│   ├── index.ts                    # MCP server boot + tool registration
│   └── intent/
│       ├── audit.ts                # audit_intent_spec logic
│       ├── scaffold.ts             # generate_intent_spec_scaffold logic
│       ├── retrofit.ts             # assess_retrofit_level logic
│       ├── checklist.ts            # 25-item validation checklist
│       ├── anti-patterns.ts        # 5 fatal anti-pattern detectors
│       ├── parser.ts               # YAML frontmatter + markdown heading parser
│       └── templates/              # YAML scaffolds (blank / level-1-mvr / full-9-section)
├── docs/
│   ├── v0-scope.md                 # binding scope-lock for v0
│   ├── EXPLANATION.md              # 4Q comprehension artifact (why MCP, what would break, what I learned)
│   └── claude-code-responses-and-tests/   # archived phase-verification outputs
├── package.json
├── tsconfig.json
├── server.json                     # registry metadata
├── CHANGELOG.md
├── README.md
└── LICENSE

src/index.ts 是一个精简的协议适配器。所有工具逻辑都位于 src/intent/*。

构建规范

• SDK 固定为 @modelcontextprotocol/[email protected]（稳定的 v1.x 系列，不是 v2 预览版）
• 所有日志都输出到 console.error。如果 src/ 中出现任何 console.log，prepublishOnly grep 守卫就会导致构建失败
• 工具实现从本地模块导入验证清单、反模式定义和模板字符串；这些模块与技能内容保持一致。它们不会改述或重新编造技能内容
• 更改范围前必须先在 CHANGELOG.md 中获得明确批准，然后才能编写代码

延伸阅读

• docs/EXPLANATION.md — 4Q 理解说明（这是什么、为何采用此方法、什么会出问题、我学到了什么）
• docs/v0-scope.md — 具有约束力的 v0 范围锁定与发布门槛
• seanwinslow.com/transactions/intent-engineering-mcp — 深度解析文章，附 Loom 演示

许可证

MIT。请参阅 LICENSE。