页面内评审模式

页面内评审模式让你在渲染后的页面上留意见，而不是对着源码树评。反馈落在内容项旁边的 .review/ 文件里，人和 agent 都能按统一结构处理，不需要另建一套评论系统。

本页是操作说明。下面的浮层 chrome 于 2026-08-21 对着 arc#4525 落地的玻璃岛 HUD 核验。能力本身经 arc#2870 在 2.0.0-beta.19 / 2.0.0-beta.20 落地。动机与背景见介绍文章。

什么时候用

适合：

lint / validate / check / build 都绿，但渲染结果仍需要人判断；
希望意见锚定到读者实际看到的字符串，并区分多语言渲染；
后续希望 agent 机械执行 delete / replace / insert-after，或按自由指令修改。

不要当成：

生产环境访客反馈组件；
多人冲突收敛工具（相反意见会并排保留）；
arc dsl lint / validate / blocklet check 的替代品（结构问题仍由这些命令负责）。

开启评审模式

按常规直接运行 blocklet（见预览、构建与发布）：
打开命令打印的页面 URL，再精确追加 ?review=1：只有值为 1 才开启。?review=true、?review=0 或单独的 ?review 都不会开启。
确认页面注入了评审 UI。右下角是一块磨砂玻璃岛，三个图标：选中正文会在选区附近弹出浅色输入框（Add / Cancel）。状态条（Review: open · N planned / N done、Approve page、Run checks）空着时不显示。登录会话读到 .review/.actions/state 之后才填。匿名 ?review=1 仍然能看到岛和输入框。

开启评审后的页面：右下角玻璃岛，Point / Page note / Freeze

玻璃岛 HUD · 本站 in-page-review 文章加 ?review=1 · 1440×900 · 2026-08-21。截取来自 arc#4525 之后的本地 Web Device handler，不是已发布的 CLI 标签。

草稿页与已发布页都可以开启。注入是按请求、显式 opt-in；发布快照里的静态 HTML 不会自动打开评审模式。

提交反馈

动作	做法
锚定反馈	选中页面文字（不必先开 Point），选类型，可选填指令，点 Add
Point 反馈	打开 Point，再点带 `data-aup-id` 的节点。Shift/meta 连点可加节点；拖框可罩住多个节点或空白
整页反馈	点岛上的气泡（Page note），不记录选区
冻住一帧	点 Freeze。再点一次关闭。不改 CSS
关闭面板	Cancel，或按 Escape。清空文字选区也会关掉选字弹出的面板

选中正文后的浅色输入框：instruction、Add / Cancel，岛仍在

markdown 文章正文上的文字选区。Point 是关的。类型为 instruction / delete / replace / insert-after。

Page note 面板：预览为 page note not anchored to a selection

从岛上气泡打开的 Page note。输入框停在岛上方。

Point 只打带 data-aup-id 的节点（AUP 渲染出来的节点）。2026-08-21 在本站这篇 markdown 文章正文上数到零个这样的节点；选字仍然可用。不要把 Point 写成「随处一点」。

反馈类型

`type`	是否锚定	含义
`instruction`	是	对选区的自由指令（如 “写长一点”）
`delete`	是	删除选中内容
`replace`	是	替换选中内容（正文为替换文案）
`insert-after`	是	在选中内容之后插入
`page-note`	否	不锚定的整页意见

这些是可执行指令，不是讨论串。同一段文字的相反意见都会保留，不会自动合并。

会记下什么

锚定类型会记录：

anchor: 读者看到的选中原文；
context: 选区前后约 50 个字符，用 {selected} 标出选区（基于 DOM Range 偏移，不是第一次 indexOf）；
locale: 提交时 URL 上的 locale 段（服务端注入；空表示未标注）；
instruction: 除 delete 外的自由文本。

script / style / noscript 以及评审 UI 自身不会进入 context。

两级状态

层级	文件	取值	单位
页面	`.review/.status.md`	`open` · `approved`	整页是否批准
条目	`.review/<id>.md` 的 `status`	`open` · `done`	单条是否处理完

状态条空着时不显示。登录会话读到 .review/.actions/state 之后：

Approve page / Reopen page 切换页面级状态；
行内 Done / Reopen 切换该条目。

匿名浮层仍可写意见；没有会话上下文时不会画出条目行。

新提交一条反馈会把已是 approved 的页面降回 open。页面批准与条目处理是两层独立语义。

反馈落在哪里

反馈跟着内容项走，不是全站集中评论库。

content/articles/<slug>/
  content.md
  content.zh.md
  .review/
    <id>.md          # 单条反馈
    .status.md       # 页面级状态（首次设置前可不存在）

pages/<slug>/ 下与 layout.aup 同级，相对结构相同。

单条文件示例：

---
status: open
type: instruction
anchor: 页面上选中的文字
context: …前文…{selected}…后文…
locale: zh
author: anonymous
created: 2026-08-02T03:33:00.000Z
---
写长一点

页面状态文件：

---
status: approved
updated: 2026-08-02T04:00:00.000Z
---

id 一律服务端生成（8 位十六进制）。客户端不能指定 id 去覆盖已有条目。

用 AFS 读取与改状态

虚拟路径在 web-device 挂载点下（默认 /web）：

/web/content-sites/<site>/collections/<collection>/<slug>/.review
/web/content-sites/<site>/pages/<slug>/.review

动作（同一内容路径 + /.review/.actions/<action>）：

动作	用途	常用参数
`submit`	新建一条	`type`，可选 `anchor` / `context` / `instruction` / `locale` / `author`
`set-item-status`	条目 `open` / `done`	`id`，`status`
`set-page-status`	页面 `open` / `approved`	`status`
`state`	读页面状态、全部条目、locale 是否存在	（无）

列目录与读取：

# 列出某条内容的结构化反馈（路径按你的站点替换）
arc afs ls /web/content-sites/<site>/collections/articles/<slug>/.review

# 读单条
arc afs read /web/content-sites/<site>/collections/articles/<slug>/.review/<id>

# 状态栏用的快照
arc afs exec /web/content-sites/<site>/collections/articles/<slug>/.review/.actions/state

把 <site> 和 collection 路径换成你实际挂载的内容站点。路径解析不到真实内容项时返回 NOT_FOUND，不会在错误路径下静默创建 .review/。

多语言与自动检查

多语言变体共享同一个 .review/（例如同目录下的 content.md / content.zh.md）。状态栏可显示各声明 locale 是否有对应文件（✓ / ✗）。这是「还有哪些语言值得打开看」，不是按 locale 拆开的评审状态。

每条反馈可带提交时所在页面的 locale。同一字符串出现在多个语言版本时，靠这个字段区分意见针对哪一版。

状态栏的 Run checks 会对该页跑站点级 lint 与 check-seo（只显示本页发现），与人工反馈并排。检查失败显示错误行；空结果表示本页无发现，而不是「检查没跑」。

发布不会带上 `.review/`

发布快照在物理拷贝和已发布树元数据里都会排除名为 .review 的目录（arc#2870 Phase 3）。评审数据留在写作树；不得进入公开部署产物。

这与 ?review=1 查询参数是两件事。即便有人在公开 host 上加了该参数，发布快照里也没有可写的 .review/ 载荷（可写内容面仅限本地/开发工作流）。

边界与失败行为

边界	行为
开启标志	仅 `?review=1` 注入浮层
Point 目标	仅带 `data-aup-id` 的节点。markdown 正文仍用文字选区
空状态条	隐藏（`:empty { display: none }`），直到状态加载
Freeze	暂停 CSS 动画、transition 和视频；HUD 自身排除在外
自由文本长度	`anchor` / `context` / `instruction` 各上限 64 KiB；超限 → `VALIDATION`
非法 type 或 status	`VALIDATION`，从不静默改写成合法值
内容项不存在	`NOT_FOUND`，不在猜测路径下写入
只读 AFS	`READONLY`
非法 `locale` 字符串	丢弃 locale，反馈仍落盘
并发提交	各自服务端 id；不做多人合并
改文后锚点失效	保留条目，可用 `context` 模糊重定位；不自动删除
domain-router 与 portal URL	服务端推导 content-site 路径；站点名错误时动作会显式失败