oliverswitzer/lens

透镜

透镜是一个 JSON 图谱 <lens>/model.json，构建成一个自包含的 <lens>/index.html，任何人都可以打开并评论。<lens> 是它被初始化到的文件夹（默认为 docs/lens）。<lens>/README.md 文档说明了节点种类、关系、主张形状和完整性规则。构建过程会拒绝违反规则的模型，因此绿色构建是第一道检查。

此技能自身的文件夹包含 template/（将复制到仓库中的内容）、scripts/（辅助脚本）和 competitors.md。它位于仓库中的 .claude/skills/lens/，或全局安装时的 ~/.claude/skills/lens/；下文用 $SKILL 表示该文件夹。

要求：Node 20+ 和 git。没有 package.json，没有依赖。

搭建新透镜

1. 选择文件夹。 询问用户透镜应该放在哪里；默认为 docs/lens。拒绝覆盖已存在的 model.json。

2. 复制模板（除了已构建的 index.html 之外的所有内容）：

   mkdir -p docs/lens && cp -R "$SKILL/template/." docs/lens/ && rm -f docs/lens/index.html
   echo '[]' > docs/lens/ids.lock.json      # 初始示例的 ID 不是你的；从空锁开始
   

3. 访谈用户，然后替换初始模型。 model.json 附带了一个虚构的“Acme Notes”示例，展示了所有常见种类。保留其形状，替换其内容。每次只问一个主题，并给出具体的草稿供纠正，而不是提出空白问题：

   • 产品的名称（title）和所有者的姓名（owner 人员节点，ID 为 p-owner，除非用户偏好其他；其 title 会在每个视图主张上显示为“<姓名>的视角”）；
   • 用一句话描述目的（purpose，一个引用所有者来源的 view 主张）；
   • 核心循环，2–5 个有序的 loop-step；
   • 为谁而设（avatars，附带人物画像），以及他们的痛点（problems）；
   • 他们已经拥有的访谈或其他证据（source + person 节点；切勿编造引文或时间戳——如果没有记录，则记录为所有者的报告）；
   • 已经发布的内容（surface，shipped: true，附带真实截图）以及仅处于创意阶段的内容（shipped: false）；
   • 人们使用的替代方案（alternatives）；
   • 最多三个需要立即验证的假设（hypothesis 节点，带有 focus: 1|2|3）。 用户没有证据支撑的所有内容都是 view（他们的观点）或 hypothesis；没有来源和 at 的内容都不是 observed。如果用户不希望在一个可能公开的文件中使用真实姓名，请使用占位名称（如“受访者 A”）。

4. 清理示例。 一旦没有节点引用 assets/example.png，就将其删除；并将截图指向 assets/surfaces/<surface-id>/<slug>.png。Surface 的 code 和 adrs 路径是相对于仓库根目录的，并且必须存在（将 adrs 指向仓库保存决策记录的位置，例如 docs/adr/）。

5. 构建并测试：

   node docs/lens/build.mjs && node --test docs/lens/tests/*.test.mjs
   

6. 查看结果。 评论是按源存储在浏览器中的，因此请通过服务来查看，而不是直接打开文件：

   python3 -m http.server 8767 --bind 127.0.0.1    # 从仓库根目录
   open "http://127.0.0.1:8767/docs/lens/index.html"
   

7. 如果他们需要追踪竞品广告，建议在 .gitignore 中添加一行 docs/lens/assets/ads/**/*.mp4。提交 model.json，ids.lock.json，index.html，assets/ 以及文件夹的其余部分，遵循仓库自身的提交规则。

确保工作有依据

在向所有者提问之前，先阅读相关节点、它们的主张及其来源。给所有者一个具体的综合陈述供其纠正。对于界面，当行为很重要时，检查它命名的代码（code，adrs）；决策记录说明当时决定了什么，而不是今天的代码做了什么。

添加证据

每个陈述都是一个带有 kind，evidence 和可选 next 的主张：

• observed（听到/看到）：某人所说或所做。引用来源，附带 at（记录时间戳，或文档的章节）。密切引用或转述；切勿升级模糊措辞（如“可能有用”）。
• view（所有者视角）：所有者的解释。必须引用一个其 people 包含模型 owner 的来源。
• hypothesis（未验证）：任何未经测试的内容，包括助手建议和实现想法。
• 假设也是一种节点类型：记录每条证据，带有 stance（supports 或 contradicts）和 at。切勿设置置信度；焦点假设上的置信度仪表是根据下次构建时该证据计算得出的（支持它的不同受访者人数；如果有人反驳，则降一级；所有者的观点永远不会提高它）。反驳的证据和支持的证据一样需要记录。
• 为每个薄弱的主张指定一个 next：一个足够具体的问题，可以在电话会议中提出。它会出现在下次对话中。
• 保持说话者身份清晰：所有者提出且某人同意的想法并不一定是他们的需求。
• 一次新的访谈是一个 source，包含 date，people，locator 和简短的 takeaways，由它所支持的主张引用。省略与产品无关的个人细节。仅当仓库是私有的且受访者同意时，才将记录保存在 <lens>/sources/ 下。

更新界面（更改后）

当一次更改改变了界面的外观或行为时，在同一个分支中：

1. 从正在运行的产品中捕获更改后的状态，保存到 <lens>/assets/surfaces/<surface-id>/<slug>.png（替换过时的截图，保留 1–4 张）。
2. 更新界面的 screenshots 条目：caption，capturedAt（今天），origin: "app"，version。如果任何截图早于对界面 code 的最后一次提交，页面会发出标记。
3. 如果行为发生变化，更新 unique / situations；如果文件移动，更新 code / adrs。

一个全新发布的界面是一个新的 surface 节点，包含 shipped: true，至少一张截图，serves 边指向它解决的问题，以及 implements 边指向循环步骤。

添加创意（来自头脑风暴）

已经讨论过但尚未构建的界面是一个 surface，包含 shipped: false；它出现在创意标签下，视觉上有所区分。为其提供 unique（作为 hypothesis 主张），situations，heard（人们所说，附带证据），以及作为 screenshots 的模型图（origin: "design"）。当它发布时，将 shipped 翻转为 true，并用真实截图替换模型图。

添加内容支柱或创意

一个营销主题是一个 pillar；一篇具体的帖子、视频或活动是其下的一个 content-idea，带有 format。将支柱或创意通过 speaks-to 链接到用户画像，创意通过 features 链接到它们展示的界面，通过 like 链接到已经运行类似角度的竞品。想法和支柱在内容触达用户之前被视为“未验证”；将发生的情况作为关于该创意的假设上的证据记录下来。

添加市场洞察

来自外部研究的趋势是一个 insight，位于市场洞察标签页。将文章记录为 Market research 来源（可选地保存快照到 sources/），将其事实作为 observed findings 陈述，并将它对某个用户画像的意义作为视图或假设来保留，同时包括对来源局限性的发现。通过 bears-on 将其链接到所有受其影响的内容。

添加或刷新竞品

遵循 $SKILL/competitors.md：研究（真实浏览器广告检查，绝不跨越付费墙），scripts/add-product.py，分阶段广告捕获，scripts/apply-staged-ads.py（检查所有内容，然后一步应用），scripts/smoke-ads.mjs，然后提交（不要包含 .mp4 文件）。根据透镜的目的和焦点假设与产品进行比较，而不是根据其营销页面，并将该比较标记为“未验证”。

可用性发现不属于透镜内容

交互问题（没人找到的按钮、缺失的焦点状态等）属于团队的问题跟踪器。将问题记录在那里，并且仅在透镜中记录其产品含义（如果有）。

重命名或删除

ids.lock.json 记录了上次构建中所有可评论的 ID。如果某个 ID 消失，则必须在 model.json 的 renamed 中映射（"old-id": "new-id"，或者有意删除时为 null），否则构建会失败。这正是保持现有评论关联的方式。

修改透镜自身

对 components/ 下的任何更改（视图显示内容、路由、验证、差异视图）都以 <lens>/tests/ 中一个失败的测试开始（node:test；共享 fixture 在 tests/fixture.mjs 中，仅使用虚构名称）。将逻辑保留在纯模块中；只有 components/app.js 接触 DOM。然后运行测试，之后在浏览器中检查相同的场景。

可视化差异

当所有者要求查看、审查或可视化更改时：

node docs/lens/diff.mjs [rev]          # 默认为 HEAD；打印更改列表
python3 -m http.server 8767 --bind 127.0.0.1
open "http://127.0.0.1:8767/docs/lens/index.html"

绿色轮廓表示添加的项目，黄色表示更改的项目；已删除的项目在横幅中以红色列出。每个添加或更改的行都链接到其项目。更改通过 ID 匹配，因此单个主张会高亮显示，而不会高亮其整个卡片。在提交之前，务必清除差异并检查：

node docs/lens/build.mjs
grep -c LENS-V2-DIFF docs/lens/index.html   # 必须输出 0

重建并检查

node docs/lens/build.mjs && node --test docs/lens/tests/*.test.mjs

然后在浏览器中查看受影响的视图。评论是浏览器本地存储的，与源关联；在切换之前导出它们。最后提供透镜链接、更改内容、证据和任何限制。