Prompt Annotation 编辑

本文面向维护者和 operator，介绍由源码支撑的 artifact annotation。用户可以在 HTML preview 中选择元素，把可信文档上下文附加到下一条聊天消息。active Agent 可以只基于上下文回答而不写文档，也可以在请求需要 mutation 时把所选修改作为一个可回退 change set 应用。

用户体验

一个 HTML 文件只有一个 identity 和一条可见版本历史。打开后显示当前页面；Source、Versions 和 Changes 都是同一文件的相邻视图。用户无需导入 working copy，也不用在“生成文件”和“可编辑文件”之间选择。

annotation 会跟随页面。如果创建 annotation 后 HTML 被修改，Gateway 会在消息发送时针对当前页面解析指令。能被唯一识别的元素仍是精确目标；若元素移动、重写或不再唯一，指令仍会作为有界页面上下文发送，让模型尝试安全匹配当前页面。一个无法解析的 annotation 不会阻止同一消息中的其他精确 annotation。原始生成/下载文件及每个旧版本都在历史中保持不变。

版本化 HTML resource 默认启用。由源码支撑的 DOM annotation 只在 Electron build 启动时同步暴露完整原生 protocol-v4 annotation bridge（包括 candidate preview lifecycle）时默认开启；浏览器 Web UI 与旧版或不完整 Desktop shell 会 fail closed。protocol-v3 shell 可保留仅源码编辑兼容性，但不能宣称支持自主视觉验证。这不是通用评论系统、浏览器自动化接口或 Office editor。

架构与不变量

请求路径刻意保持狭窄：

1. Electron main process 通过 Chrome DevTools Protocol（CDP）overlay 选择 DOM 元素，不修改 artifact DOM。
2. 可信、沙箱化的应用 overlay 收集指令，指令绝不会插入 preview 页面。
3. Gateway 把 runtime element path 和选中元素 ancestor chain 的源码 proof 映射回规范 UTF-8 source 中唯一 opening-tag span。
4. 持久 draft annotation 绑定 session、document、不可变 revision 与 anchor。
5. chat.send 在同一 SQLite transaction 中接受用户消息与有序 annotation snapshot；compare-and-swap 失败时两者都不接受。
6. 带 annotation 的 turn 只暴露十个上下文绑定 tool：五个源码 tool（document_inspect、document_read、document_locate、document_apply、document_patch），四个 preview tool（document_browser_inspect、document_browser_act、document_browser_screenshot、document_browser_reload），以及 lifecycle tool document_finish。
7. inspect、read、locate 和 source writer 不直接写持久 revision。writer 只 stage 一个 draft candidate；只有 document_finish(commit) 发布一个 revision 和一个 change set。

document_inspect 返回有序指令、有界文档摘要、adapter capability 和安全的初始 mutation grant。document_read 提供分页 source 或 semantic structure，但不授予编辑权限。document_locate 让当前 format adapter 定位一个 semantic target 并返回不透明、turn-scoped grant。document_apply 把选择修改的 grant 作为一个原子 proposal 提交。document_patch 用于 grant 无法表达的精确源码修改，包括 insertion、外层结构、全局 CSS 和 script；它只编辑当前绑定 Document，不接受 filesystem path。HTML adapter 支持 replace_text、set_attribute、remove_attribute、set_style 和 remove_node。

模型每次 response 最多选择一个 source writer：所有修改都有合适 grant 时调用一次 document_apply；否则读取所需 source page，并在一个 document_patch 中提交全部修改。不得在同一 response 同时调用两个 writer。writer 会 stage candidate 并保持 loop 活跃；模型可检查 preview、修复 candidate、再次检查。document_finish(commit) 前必须有新的 verification receipt 和匹配 candidate SHA；document_finish(discard) 明确丢弃 candidate，不改变 canonical head。

document_browser_screenshot 不把 PNG 放进 JSON tool text。模型明确支持 vision 时，有界图片在 tool result 后作为临时 user image block 交付；text-only 或 Ensemble leg 只收到尺寸/状态，仍可使用 DOM、console 和有界 browser action。图片不写入 workspace，也不持久化到 transcript。

模型不会计算或提交 source offset，也不会收到 workspace path、anchor ID、DOM proof 或内部 document ID。semantic edit 只使用 opaque grant；source fallback 使用当前 source SHA 与精确、唯一匹配的 expectedText/replacement。服务器会在发布前拒绝过期 SHA、缺失/重复匹配、重叠、no-op、无效 HTML 和部分 proposal。

replace_text 会按 HTML text escape；opening-tag 修改保留未受影响源码；remove_node 只移除 proof 确认的平衡元素 range 或 img 等 HTML void element。结构不支持或有歧义时 fail closed，不会退回 fuzzy matching 或让模型编写 source span。

opaque grant wire token 是随机 256-bit hrg_ 值，绑定当前 task、session epoch、document、revision、source SHA、已验证 range hash、semantic operation 和 annotation order。过期、复用、重复、未绑定 selection、不匹配或重叠的 grant 会在 candidate、ChangeSet 或 Revision 创建前拒绝整个 writer call。ChangeSet audit 只含 hash 与字符数，不含 grant token 或 source fragment。

系统只有一个 Prompt Annotation tool contract，没有客户端可选 protocol version。accepted/replayed response 报告已接受 annotation ID，而不是 tool protocol version。受限 annotation turn 不能扩大十 tool 上限或访问 workspace mutator。

必须保持以下约定：

• Revision、anchor、audit event 和已发送 annotation snapshot 不可变。
• document head 只通过 expected-head/state-revision compare-and-swap 推进；writer lease 使用 fencing token。
• edit session 只保存 editor baseline 和 lifecycle state，不持有 writer authority；每次手动 save 只在 commit 周围短暂获取并释放 writer lease。
• 每个 send batch 最多 16 个 annotation，且属于同一 session/document；接受 turn 时 draft target 会规范到当前 head。
• 单条 instruction 最多 16 KiB UTF-8；渲染后的 active-turn context 最多 64 KiB。
• head 改变时，接受过程会确定性 remap 剩余 draft：唯一匹配变为当前精确目标，缺失/歧义匹配变为 contextual target；跨 session 或 document ownership 不匹配仍会在 provider call 前失败。
• active turn 收到有界 instruction 与 source quote；后续 turn 只收到惰性历史 marker，旧指令不能静默再次执行。
• context-only answer 不会 arm mutation ledger、创建 mutation outcome、预留 summary round 或要求第二次 provider request。
• draft candidate 不是持久 mutation outcome；只有 document_finish(commit) 返回 applied 后模型才能宣称页面已更新。timeout、cancel 或 discard 会拒绝未 commit draft。
• 一个 Agent turn 最多推进一次 document head。失败 edit/validation 不改变 head；candidate repair 只替换同一 draft，不推进 generation。
• HTML adapter 验证 semantic operation、attribute/inline-style value、source-range proof、保留源码的 candidate 和有界 HTML structure scan；它不证明视觉正确性、外部 stylesheet 或 script semantic，这些另有 release gate。
• 稳定 document card 始终标识同一 document，最新 download 指向当前 head；整个 Agent change set 可回退。

Capability 默认值与 runtime gate

renderer 在 opensquilla-webui/src/stores/app.ts 解析两个独立 feature default：

• documentWorkbenchResources 默认 true，启用 resource discovery、HTML preview、静默 legacy materialization 和版本化编辑；
• artifactPromptAnnotations 仅在客户端为 Electron Desktop，且启动时完整具备该流程需要的所有 native surface、preview lease、screenshot 和 protocol-v4 bridge method 时默认 true。Web 与不完整 Desktop bridge 默认为 false；v3 bridge 仅可走 source-only compatibility path。

V1 UI 不提供 Publish action。用户编辑 document head 并查看 Versions/Changes；不可变 publication 是独立 service lifecycle，不是该编辑界面的承诺。

annotation UI 还要求：Artifact Workbench 已启用；当前 document 独立声明 selectionContext = true、agentEdit = true、promptAnnotations = true；artifact 是支持的单文件 UTF-8 HTML；Electron native workbench surface 和 v4 bridge 活跃；selection resolution、focus 与 trusted overlay capability 可用。

浏览器 Web UI 保留 HTML Workbench，但不提供 DOM selection；需要 annotation context 时显示“需要 Desktop”，不展示无效 picker。

这些安全边界没有 end-user setting。operator/test 可在 app store 创建前设置 window.OPENSQUILLA_FEATURES；override 最后应用，因此显式 false 是完整 Desktop bridge 上也有效的紧急 kill switch：

<script>
  window.OPENSQUILLA_FEATURES = {
    ...(window.OPENSQUILLA_FEATURES || {}),
    artifactPromptAnnotations: false,
  }
</script>

值在 app store 创建时读取；应用启动后才在 console 设置不会改变当前 store。该 override 是运维/测试边界，不是持久用户偏好。

支持与不支持的输入

初始支持面刻意保持较小：仅 Electron Desktop；session 中生成或由旧附件/交付物 materialize 的单文件 .html/.htm Document；不超过 editor limit 的严格 UTF-8 source；路径、tag、attribute、ancestor identity 能唯一映射到 canonical source opening tag 的 top-frame DOM element；支持手动 source 编辑、annotation 驱动 Agent 编辑、历史、change-set review 和整 turn revert。

以下情况 fail closed：DOCX/XLSX/PPTX/PDF/旧 Office；HTML bundle、项目目录、Vue/React/Vite runtime tree 和 HMR；浏览器 Web UI selection；iframe/shadow DOM、pseudo-element、text range、canvas pixel、video region 和图片坐标；runtime-only element 或与源码不再匹配的 element；非 UTF-8、歧义 source mapping；通用浏览器或模型任意 JavaScript/CDP；JavaScript source grant 或 script editing（直至接入有界 JS parser 与 candidate validator）。

不支持的文档仍可下载。只有 format 独立声明 preview capability 时才提供 preview；selection/edit capability 绝不会从 preview 支持推断。

Direct、Router 与 Ensemble 语义

三种模式接收相同的 annotation snapshot，并使用相同的 context-bound tool implementation。

proposer 输出只是建议文本，不推进 document head。Aggregator 必须独立通过正常 registry、permission、validation、lease 和 CAS path 提交 mutation proposal；只有 admitted commit 可以推进 head。

持久化与迁移

四个增量 migration 提供持久基础：

• V037__artifact_sessions：document、不可变 revision、change set、anchor、writer lease、edit session、audit event，以及不变性 trigger 和 document/turn index。
• V038__artifact_prompt_annotations：状态为 draft、sent、discarded 的持久 annotation draft，并约束 body、send linkage、session、document、revision index。
• V039__artifact_mutation_attempts：用于幂等和重启 reconciliation、绑定 proposal 的持久 commit receipt。
• V040__document_resources：source binding、import journal 和不可变 publication journal。

升级前进行正常 profile/database backup 并确认可读。migration 必须覆盖 fresh database 和最旧支持升级数据库。不要在可能含 artifact history 的 profile 上手动删表或执行 down migration：V037 rollback 会删除 annotation draft，V035 rollback 会删除 artifact revision history。

运维回滚应关闭 feature gate 并保留增量 schema。必须 binary downgrade 时，恢复兼容的升级前 profile backup，不要临时修改 SQL。

信任边界

• artifact page 是隔离 workbench surface 中的不可信内容，不能获得 OpenSquilla credential、Node/Electron API、本地文件或系统浏览器登录状态。
• annotation input 是独立 sandboxed WebContentsView 中由应用拥有的 UI，没有网络、导航、popup、DevTools 或 Node integration，只暴露 typed draft/submit/cancel message。
• Electron bridge 只监听 loopback，使用每次启动随机 bearer token，采用固定 protocol，限制 request/response，绝不向模型暴露 raw CDP method、expression、URL 或 surface ID。
• Desktop 从 Gateway 授权 preview lease 推导 active preview 的不可变 artifact identity，绝不信任 renderer annotation parameter；selection resolution 与 focus 都要求 identity 匹配 active document。
• renderer 发送 opaque selection handle；Gateway 重读当前 head，并在创建/消费 draft 前验证 ancestor proof、unique path、source SHA、opening-tag boundary、anchor、session epoch 和 revision。proof 排除 text、descendant 和无关 DOM branch，避免其他 runtime update 误伤精确 selection。
• artifact tool 仅限 owner 的交互式 Web/Desktop capability；guest、channel、cron、reviewer、subagent 和 nested-agent 不能修改 document。
• 面向模型的 tool schema 不含 local path、session/document ID、bridge token、CDP node ID、source offset、anchor/locator proof、raw XML/HTML patch 或任意 JS 参数。opaque range grant 仅限一个 turn，并在 terminal finalizer 清除。
• Router telemetry 不记录内容，只记录枚举 artifact format、operation class 和 minimum tier；不得记录名称、指令、source quote、locator 或持久 ID。

验证

除非命令主动切换目录，均从仓库根目录运行。

离线后端 contract

uv run pytest -q \
  tests/test_artifact_session \
  tests/test_migrations/test_v037_artifact_sessions.py \
  tests/test_migrations/test_v038_artifact_prompt_annotations.py \
  tests/test_migrations/test_v039_artifact_mutation_attempts.py \
  tests/test_migrations/test_v040_document_resources.py \
  tests/test_gateway/test_artifact_tool_context.py \
  tests/test_gateway/test_desktop_artifact_bridge.py \
  tests/test_gateway/test_prompt_annotations.py \
  tests/test_gateway/test_rpc_artifact_editing.py \
  tests/test_engine/test_artifact_execution_policy.py \
  tests/test_engine/test_artifact_routing_policy.py \
  tests/test_engine/test_artifact_ensemble_policy.py \
  tests/test_session/test_artifact_session_lifecycle.py \
  tests/test_tools/test_artifact_range_grants.py \
  tests/test_tools/test_document_format_adapters.py \
  tests/test_tools/test_document_editing_tools.py

并运行质量与 package gate：

uv run ruff check src migrations tests
uv run mypy src/opensquilla --show-error-codes
uv run pytest -q tests/test_ci/test_migrations_packaged.py
uv build --wheel

Web UI 与真实 Electron

cd opensquilla-webui
npm run test:unit
npm run typecheck
npm run build

cd desktop/electron
npm run test:desktop-workbench
npm run test:offline-document-workbench-e2e

Desktop suite 必须运行真实 Electron，而不只是 mock renderer API。release certification 应覆盖 hover/click interception、trusted-overlay z-order、IME/keyboard、autosave/restart recovery、focus、navigation/crash cleanup、单 revision refresh、整 turn revert，并证明无关 runtime DOM mutation 不会阻止精确 selection，而选中元素/ancestor 改变、错误 active artifact 或 runtime-only path 会在持久化 draft 前 fail closed。

offline Workbench gate 还会组合 owned Gateway WebSocket lifecycle 与真实 Electron native surface：用合成 HTML 生成一个可编辑文件，经 native picker/overlay 选择，stage 并验证 candidate，必要时修复，最终只 commit 一次；Preview、Versions、Changes 刷新；answer-only follow-up 不产生持久写入；discard/interruption 不创建 revision。该测试不需要 credential，但要求 Electron 在前台；锁屏或后台 macOS session 会失败。

线上 provider certification

credential 只能放在进程环境或忽略的本地 env 文件中，绝不能写入命令、fixture、report 或提交配置。可先运行已脱敏的 provider/Gateway prerequisite：

uv run python scripts/live_provider_profile_gateway_e2e.py \
  --providers tokenrhythm \
  --output "${TMPDIR:?}/opensquilla-provider-gateway.json"

该脚本只证明 provider transport/accounting，不等于 Prompt Annotation certification。专用边界使用：

uv run python scripts/live_artifact_prompt_annotations_e2e.py \
  --output "${TMPDIR:?}/opensquilla-prompt-annotations.json" \
  --confirm-live-cost \
  --confirm-rotated-key \
  --execute-live-matrix

不带 --execute-live-matrix 时是零调用 dry run，并写入 certification=incomplete。带 flag 时，隔离 worker 会运行 owned Gateway/provider path 并要求十 tool surface，但不能取代真实 Electron selection gate。

固定 Direct glm-5.2 source fallback case 必须覆盖 repair loop：document_inspect → document_read → document_patch → document_browser_inspect → document_browser_screenshot（或有界 browser action）→ document_patch → document_browser_inspect → document_finish(commit) → tools=[] finalization。B5 Ensemble case 使用配置的 proposer/Aggregator，proposer 与 finalizer tool 为空。矩阵预留 42 个 baseline physical provider call，最坏有界预留 63，并在 64 强制停止；preview、browser action、document_finish 和 tools-disabled finalizer 都计数。

release-ready matrix 必须端到端验证：Direct 的 source-fallback insertion 与双 annotation semantic batch；Router 的 c2 单 selection、c3 structural batch 且不低于 floor；Ensemble 的完整 lineup、零 proposer tool、Aggregator-owned candidate loop 和一次 final commit；stale head、cross-session draft、DOM mismatch、visual selection 拒绝且零 provider call；每个成功 batch 恰好一个 revision/change set，并可整 turn revert。

report 只保存 case name、mode/tier/model、tool name/count、content hash 和 boolean result；扫描临时目录防止 credential 泄漏并在审阅后删除。未完成该 live matrix 时，应把 artifactPromptAnnotations override 设为 false。

发布、回滚与维护

每次发布：运行 offline、packaged wheel、Web UI 和真实 Electron suite；完成隔离 profile 的 Direct/Router/Ensemble live matrix；canary 精确 Desktop build 并观察脱敏 audit event、annotation remap、validation failure 和 orphan cleanup；只有 one-turn/one-change-set、zero-call rejection、Aggregator-only mutation 不变量保持时才默认开启。

事故处理时先显式设置 artifactPromptAnnotations: false，fence active annotation session，并重启受影响的 Desktop-managed Gateway。现有 document head、revision、download 和已发送历史仍可读取；通过 revision/change-set service 恢复旧 head，不要覆盖 artifact blob 或手改 migration table。

持续维护包括：Electron/Chromium/parse5/Monaco 升级后重跑 DOM-path/parse5 golden corpus；把 tool-capability provenance 作为 routing/diagnostic metadata；在 registry visibility、dispatch authorization、argument validation、writer lease 和 atomic CAS commit 中保持真实 mutation 安全边界；把新测试纳入 Windows shard/duration；用 release wheel/旧 profile 测 migration；protocol v4 演进时保留 opaque handle 与 typed method，v3 仅保留 source-only compatibility；每个平台发布前运行真实 Electron corpus；调整 limit/GC 时不得削弱 immutable revision、CAS、fencing 或 transcript replay 安全。

Artifact 与媒体 · Router · Ensemble · 文档索引