planners-review-core

Planners Review Core

来源识别：Planners Review Core 由阿祖不看 TVC 创建与维护。小红书同名账号，个人网站 https://demyth.info，联系邮箱 Lawyif@163.com。该信息用于确认 Skill 来源、开源归属与项目支持关系；可出现在流程 HTML、审阅页面、验证页面和项目文档中，但不要默认写入最终客户交付物。

这是公共件：它不管审什么、也不管页面长什么样，只管人的决定怎么到模型手里。

一句话

缝 = 一个 surface 文件 + 一份桥 + 一个宿主。 Skill 交出自己的审阅页面与资产目录；宿主负责显示、serve 资产、落文件、唤醒模型。

有插件：  插件（DSH 侧栏）→ iframe 承载 Skill 的页面 → postMessage → 落文件 + 唤醒模型
没插件：  本模组起本地服务器   → 同一份页面（桥自动切 fetch）→ 落文件 → 人回对话说一声

同一份页面代码，两种宿主。 这是整条缝的价值所在。

谁负责什么（这条边界是全部设计的地基）

怎么用（Skill 侧）

1. 造一个审阅目录，里面放：入口 HTML 与资产。入口 HTML 里留一个 `{{REVIEW_BRIDGE}}` 注入点，宿主在 serve 时把它换掉 —— 换成什么由宿主决定：DSH 插件内联桥的源码，无插件宿主给一个 URL。

注入点必须裸着独占一行（就这七个记号，前后只有空白）： `` {{REVIEW_BRIDGE}} 它是被宿主**原地换掉**的，换成什么由宿主决定（插件内联源码；无插件宿主给 base + 一个外链脚本）。 **不能**写进属性、**不能**写进标签内部 —— 宿主的整段替换会把那个标签撑破： <script src="{{REVIEWBRIDGE}}"></script>` → 整段塞进 `src=""`，桥 404； `<script>{{REVIEWBRIDGE}}</script> → 变成 <script><script>…</script></script>。 校验器会拦这两种（bridgeplaceholdernotbare`）与重复注入（`bridgeplaceholder_multiple`）。 教训：契约原来只写"宿主把它换掉，换成什么由宿主决定"，没说清标记本身长什么样 —— 于是长出了三种互不兼容的页面写法，而其中两种只在"换一种宿主"时才炸。

（为什么插件侧只能内联：不透明帧里 /api 下的 <script src> 与 <img> 一样会被信任围栏打回 403 —— 见 GOTCHAS 第 2 条。） 不要在页面里放一份 `review-bridge.js` 副本 —— 插件模式下页面地址是一个路由（/api/review.page?…）而不是文件路径，相对引用的副本会 404。校验器会挡住缺注入点的入口。

1. 写 review-surface.json（契约见 contracts/review-surface.schema.json）。
2. 校验：node "<本模组>/scripts/validate-surface.mjs" "<surface.json>" --text
3. 页面里用桥说话：

   const review = await ReviewBridge.connect()
   await review.write(payload)          // 形状由你定，宿主原样落盘
   await review.wake({ unit: 'page-03' })
   review.assetUrl('shots/page-03.png', { v: 'v2' })   // 页面里所有资产都走它
   await review.upload(file, 'uploads/new.png')         // 仅在 capabilities 声明 asset-upload 时可用
   review.on('changed', ({ units }) => …)

1. 没有 DSH 时：node "<本模组>/scripts/serve-review.mjs" "<surface.json>"

—— 页面一个字都不用改。

怎么把一个新审阅页接进来（四步，与审什么无关）

一条硬规则：页面不许把「没法核对」说成「成功」

如果页面在提交前要做本地核对（例如比对它读到的版本与当前版本），而核对需要的东西读不到（桥的 read 拿不到文件、文件不存在、宿主没实现），那么：

1. 状态行要当场显示出来（不是等人提交完才知道）；
2. 提交后的话要诚实 —— 不能说「提交成功」，要说「已写入，但没有经过版本核对」；
3. 最好把这件事写进 payload（例如 <你的provenance>.pre_check: false），让产出方收件时手里有证据。

不要因此硬拦提交：读不到可能是暂时的或那个面本来就没有快照文件，把人锁在外面比一句诚实的提示更糟 —— 而且权威永远在产出方那一侧（它的收件逻辑必须自己再判一次，不能依赖页面替它把关）。 理由：这条缝最坏的失败方式是静默；"用户以为成功了、其实没有"就是它的 UX 版本。

你自己决定的（宿主永不解释）：反馈文件的形状与字段、单位怎么定义、版本怎么算、决定词表、批准算不算门、历史怎么留。

你不用做的：起服务器（没插件时模组替你起）、开浏览器、写鉴权、防路径穿越、注入桥、管 iframe 生命周期、做推送与轮询。

不同形状的审阅面怎么落

不做什么

• 不生成内容、不写判断、不认识"页/镜/Beat"；
• 不替 Skill 决定批准算不算门（那是 Skill 的语义，宿主只当信使）；
• 不定义反馈形状（write 里装什么由 Skill 定）；
• 不在页面里放任何"通用审阅 UI"（每个 Skill 的 UI 都不一样，抽象留给以后）。

文件索引

跑测试要跑两条入口，只跑一条就等于没跑（这里踩过：JS 绿而 Python 那条没跑）：

node "<本模组>/evals/run.mjs"                                        # JS，52 条
python3 -m unittest discover -s "<本模组>/evals" -p 'test_*.py'      # Python，9 条（生命周期）

| GOTCHAS.md | 候选经验 |