Mcpt Marketing

mcpt营销

   ](https://nodejs.org/)

MCPT工具的确定性营销基础设施： 可证伪的主张, 哈希验证证据，以及 通道就绪消息 随着产品的发展，这些信息会保持可追溯性。

此repo定义 市场 IR --一种小型的、版本化的“营销中间表示”，旨在供生成器和公共网站使用(mcptoolshop.com)而不会将营销变成一个手动的、脆弱的过程。

______________________________________________________________________

这是什么（不是什么）

这是：

• 产品信息的结构化真实来源
• 明确标记的声明 已验证的 vs 励志的
• 证据文物 sha256哈希+来源
• 消息如下 必须追溯到索赔 --没有驱动力断言

这不是：

• 博客
• CMS
• 一个无法测试的基于振动的副本的地方

______________________________________________________________________

核心理念

______________________________________________________________________

仓库布局

marketing/
  schema/           # MarketIR JSON Schema (2020-12, versioned)
  data/
    tools/          # One file per tool (claims, messages, positioning)
    audiences/      # One file per audience (pain points, context)
    campaigns/      # One file per campaign (phases, channel sequences)
    marketing.index.json   # Root index — everything starts here
  evidence/         # Evidence artifacts (screenshots, reports), hash-addressed
  manifests/
    evidence.manifest.json   # Evidence registry with sha256 + provenance
    marketing.lock.json      # Lockfile pinning all files by hash
  scripts/          # validate, hash, gen-lock
test/               # node:test suites (see Testing section for the per-suite breakdown)

编写vs生成

一切都必须从 marketing/data/marketing.index.json。没有孤儿档案。

______________________________________________________________________

决定论契约

ID是稳定和永久的

ID遵循命名空间模式 从未重命名 --相反，请弃用。

tool.              → tool.zip-meta-map
aud.               → aud.ci-maintainers
claim..      → claim.zip-meta-map.deterministic-output
ev...v    → ev.zip-meta-map.build-screenshot.v1
msg..        → msg.zip-meta-map.web-blurb
camp..       → camp.zip-meta-map.launch

所有ID在整个图中必须是唯一的。

索赔状态明确

证据经过哈希验证

每件证据制品都包括 sha256, bytes和a provenance 对象（生成器、源代码提交、注释）。这使得证据篡改明显且可重复。

锁文件是规范的

marketing.lock.json 按哈希值固定每个包含的文件。CI重新生成锁文件，如果它与提交的不同，则失败。每次都是相同的数据，相同的构建。

消息可追踪到索赔

每条消息都引用了以下声明 claimRefs如果消息断言了未表示为声明的内容，则验证失败。

确定性序列化

所有JSON都使用排序键、稳定的数组顺序和尾随换行符。这可以防止“相同数据，不同差异”的噪音。

______________________________________________________________________

本地工作流

npm install

# Format check (Prettier)
npm run fmt:check

# Schema + invariant validation
npm run validate

# Lockfile drift check (CI mode)
npm run lock:check

# Tests (version + structure invariants)
npm test

典型开发循环：

1. 编辑或添加以下文件 marketing/data/**
2. 将证据条目添加到 marketing/manifests/evidence.manifest.json （以及文物 marketing/evidence/ 如果适用）
3. 重新生成锁文件： node marketing/scripts/gen-lock.mjs
4. 验证： npm run validate
5. 格式： npm run fmt:check （用 npm run fmt)
6. 运行测试： npm test

______________________________________________________________________

脚本引用

中每个脚本的一行示例 package.json:

______________________________________________________________________

故障排除

常见故障模式和每种模式的单线修复：

______________________________________________________________________

消费市场IR（现场桥梁）

公共网站将此仓库视为 只读上游。没有运行时获取——一切都在构建时解决。

mcpt-marketing (MarketIR, this repo)
        │
        │  fetch + sha256 verification (lockfile-enforced)
        ▼
vendor snapshot (build-time, gitignored in site repo)
        │
        │  Astro static build
        ▼
mcptoolshop.com

网站的 fetch-marketir.mjs 脚本下载lockfile中引用的文件，验证每个哈希值，并写入本地快照。如果任何哈希不匹配，构建将中止。这使营销可追溯和可复制。

消费合同

对于销售MarketIR的消费者（公共网站、未来发电机、其他任何人）来说，稳定的表面是：

• 对消费者来说稳定:

- marketing/data/** --工具、受众、活动和根索引(marketing.index.json) - marketing/manifests/marketing.lock.json --锁文件（规范库存+每个文件sha256） - marketing/manifests/evidence.manifest.json --sha256+字节+出处的证据注册表 - marketing/schema/** --JSON模式定义（用于验证摄入的数据）

• 内部-不依赖:

- marketing/scripts/** --生成/验证脚本（可能会重命名或重新构造，恕不另行通知） - test/**, node_modules/，顶级配置(.prettierrc等等）

如何取回

消费者应该通过锁文件而不是硬编码路径来解析文件。一个典型的食谱：

1. 获取 marketing/manifests/marketing.lock.json 来自已知的提交（标签或分支）。
2. 阅读 schemaVersion 如果主版本与消费者期望的不同，则从锁文件中删除并拒绝接收（请参阅下面的版本控制）。
3. 对于锁文件中的每个条目，获取引用的文件（例如，从 `https://raw.githubusercontent.com/mcp-tool-shop/mcpt-marketing//

`)并验证其sha256是否与锁文件条目匹配。

1. 在任何哈希不匹配的情况下中止构建——数据不再具有自一致性。

现场桥梁(fetch-marketir.mjs)是此配方的参考实现。看 examples/consume.mjs 对于一个可运行的引用消费者，它演示了锁文件优先遍历、sha256验证和端到端的工具摘要，而无需离开此仓库。

别名和弃用

ID从不重命名；它们已被弃用。当工具、声明或消息在精神上被重命名时，旧的ID将保留在 status: "deprecated" 审计线索完好无损。未来的模式修订可能会添加一个显式的 aliases 更清洁的消费者迁移领域；在那之前，消费者应该对待任何 deprecated 实体作为终端——如果您的消费者选择，请继续显示它，但不要默默地重写ID。

______________________________________________________________________

出资规则

质量标准很简单，不容讨价还价：

• 每一项主张都必须是可证伪的 --原则上可测试，而不仅仅是感觉良好的副本
• 升级愿景→ 已验证的 只有当你添加证据时
• 消息必须引用声明 --如果有人说，就必须声称
• 添加反索赔 每当工具可能被误用或误解时
• 没有孤儿内容 --所有内容都必须可以从索引中访问

______________________________________________________________________

测试

npm test

在以下五个套件中运行46个测试 test/ 通过Node内置测试运行器（无外部测试框架）：

• test/version.test.mjs --5个版本一致性测试

- package.json 版本是规范的semver（X.Y.Z\[-pre\]\[+build\]） - package.json MAJOR匹配最新 ## [X.Y.Z] 航向 CHANGELOG.md - CHANGELOG.md 包含当前版本的节标题（而不仅仅是链接引用） - LICENSE 以“MIT许可证”开头 - marketing/ 存在并包含 schema/, data/, manifests/ 子目录

• test/gen-lock.test.mjs --7个确定性+锁文件测试（锁文件漂移检测、字节稳定序列化、引用遍历硬化）
• test/validate.test.mjs --10个模式+不变测试（无证据证明的负路径覆盖率、孤立文件、哈希不匹配、禁止短语、消息长度等）
• test/hash-file.test.mjs --4个哈希实用程序测试（已知向量、空文件、POSIX路径规范化、使用错误）
• test/_paths.test.mjs --20次路径穿越防护测试(assertSafeRef 和 assertSafePath 拒绝+接受路径）

CI运行 npm test 在每次推送和拉取请求中。

______________________________________________________________________

版本控制

MarketIR变更通过以下方式进行版本控制 schemaVersion 在模式和数据文件中。目前的专业是 1.

什么算作破碎、添加剂或化妆品

如果一个更改使以前有效的文档对新模式无效，那么无论它看起来有多小，它都会崩溃。

弃用生命周期（架构字段）

当模式字段过时时：

1. 在架构中将其标记为已弃用(description: "Deprecated as of vX.Y; …")在a 次要的 释放。继续接受它。
2. 更新 CHANGELOG.md 随着 consumer-impact: yes 以及明确的移民指导。
3. 在接下来的…… 主要的 释放后，该字段可能会被删除。消费者有一个完整的主要版本可以迁移。

仅当字段可证明未使用时才允许单步删除（在同一版本中弃用+删除），即零数据文件引用它，没有公共消费者依赖它。在变更日志中记录审计。

ID弃用生命周期（数据实体）

ID本身永远不会被重命名或删除。将不再是最新的索赔、工具、消息或证据记录设置为 status: "deprecated" （实体支持状态字段）或移动到已弃用的部分，但保留在索引中进行审核。这与模式字段弃用相反：模式字段可以消失；实体ID是永久的。

与消费者的协调

当发布包含突破性更改时，更改日志条目必须：

• 说明新的主要版本。
• 列出每个被删除或重组的字段，并附上一句话的迁移说明。
• 标记条目 consumer-impact: yes 因此，下游供应商（站点网桥、未来的生成器）可以搜索有影响力的版本。

消费者应固定在特定标签上，阅读 schemaVersion 从获取的锁文件中提取，如果主文件与它们的构建目标不同，则拒绝摄取。

______________________________________________________________________

安全

此回购中不包含机密、私有URL、API密钥或客户标识符。证据是指公共工件——屏幕截图、CI链接、测试结果——而不是内部日志或凭据。如果某些东西不能公开展示，那就不是证据。

完整的数据范围表（已触摸数据、未触摸数据、权限、网络、遥测）位于 安全.md，这也是您报告漏洞的地方。SECURITY.md是威胁模型的唯一真实来源。

______________________________________________________________________

记分卡

得分：42/50 （经过诚实的重新审计后，从50/50下调；见 SCORECARD.md 方法论）。 全面审计： 发货日期.md · SCORECARD.md （最后审查+审计节奏在SCORECARD.md中作为唯一真实来源）。

______________________________________________________________________

许可证

麻省理工学院（见 许可证).

______________________________________________________________________

Built by MCP Tool Shop