assistant/tools/learning/README.md

# 本机协作学习入口

由维护者在学习后台创建任务、打开专用浏览器并完成官方页面登录。本地 Codex 可通过本目录的受限控制入口继续观察和记录，所有动作绑定后台中的任务与会话，不另开一份账号资料。这里没有通用自主 Agent。

入口只连接本机维护 API，复用后台鉴权、CSRF、动作预算和证据记录。维护者账号通过当前进程的 `ASSISTANT_MAINTAINER_USERNAME`、`ASSISTANT_MAINTAINER_PASSWORD` 环境变量提供；不要放入命令行参数、任务内容或版本库。`ASSISTANT_CONTROL_URL` 默认为 `http://127.0.0.1:8810`，仅接受本机 HTTP 地址。平台的手机号、密码、验证码不经过此入口。

标准输入为一个 JSON 请求，或最多 30 个请求的数组；一次输入不超过 64 KiB。标准输出为 JSON 结果。顺序执行遇错即停，已经完成的动作会保留，超时和失败不自动重放。`health` 不需要维护者凭据：

```powershell
'{"operation":"health"}' | pnpm --silent learning:control
```

已有任务的观察与操作示例（替换任务 ID，并在当前进程配置维护者凭据）：

```json
[
  {"operation":"tasks.get","task_id":"learn_example"},
  {"operation":"browser.capture","task_id":"learn_example","data":{"note":"读取当前页面"}},
  {"operation":"browser.action","task_id":"learn_example","data":{"kind":"scroll","selector":"body","direction":"down","pixels":500,"max_scrolls":1}}
]
```

将 JSON 文件作为标准输入执行 `node tools/learning/control.mjs`。需要先查看页面证据，再选择其中的 CSS 定位，不能从示例推断真实平台定位。操作集合为：

- `tasks.list / get / create`：学习任务。
- `browser.open / ready / capture / action / close`：专用会话、人工确认、证据和动作。
- `candidates.create / get / check / verify / publish_check`：冻结候选、固定校验、试跑及发布预检。
- `validations.list`：验证账本。
- `quality.append`：向指定 `validation_id` 追加人工观察，后台保留历史和时间门禁。
- `routes.list / resolve / verify`：与行业无关的学习候选目录、固定版本召回和变参组合验证。`resolve` 只读选择，`verify` 使用已确认会话串行执行搜索和一篇详情/评论，不调用业务模型；失败不自动重放，汇总留在现有验证记录。
- `discovery.list / get / create`：装修内容初筛历史、指定 `run_id` 详情及新建；新建复用已确认会话和冻结搜索候选，失败不自动重试。
- `readings.list / get / create`：指定初筛 `run_id` 的阅读历史、指定 `reading_id` 详情，以及单篇阅读；新建 `data` 仅传 `detail_candidate_id` 和该初筛实际保留的 `note_id`，标题/URL/关键词由后台取原记录。
- `model.config`：需求分析的安全配置状态，不返回接口地址或 Key；已配置不等于已验证连通。
- `reviews.list / create / summary / get`：指定 `analysis_id` 的核对历史、显式追加核对、按每源最新版本统计，以及按 `review_id` 查看。只保存维护者判断，不调用模型、重读平台或覆盖原分析。
- `briefs.list / get / create / confirm / discover`：商家需求历史、按 `brief_id` 读取、由 `data.request_text` 解析草稿、显式确认完整条件，以及用确认版本初筛。`discover` 仅接受 `search_candidate_id/max_selected`，使用确认条件的第一个搜索词，不接收条件覆盖；不会自动调度其他搜索词或开启浏览器。
- `analyses.list / create`：指定 `reading_id` 的分析历史或新分析；新建仅传空 `data:{}`，不接受外部正文/标题/来源。`analyses.get` 以 `analysis_id` 读取独立事实。

## 固定执行模式与实际合同

学习与未来 Electron 桌面共用 Playwright 固定步骤和同一执行协议，不另建 browser-use `Agent.run` 路径。新小红书任务默认“有界网页操作（原生通信）”；受限入口 `tasks.create` 可显式传 `execution_profile:"playwright-xhs-native-ui-v1"`。省略仍为 legacy，旧任务不会自动升级；其他平台不能使用这个小红书 profile。没有任意框架名或自定义策略配置入口。

新模式固定合同为 `execution_contract:{engine:"playwright",action_policy:"xhs-bounded-readonly-v1",network_policy:"xhs-page-native-v1"}`，三字段和值须完全一致。任务顶层 profile 只是选定模式；`browser_readiness` 中的 profile/contract 来自当前已核验会话，未打开会话不填。`open/status/ready` 原始响应也回显实际合同；候选 `manifest` 保存冻结配置，浏览器验证 `environment` 保存执行器实际返回值，初筛和阅读复制各自验证的实际合同。旧记录缺字段不补造，固定规则校验合同不冒充已实际运行；错配停止，不降级为 legacy。

schema 10 仅新增可空任务 `execution_profile`，旧值保持空且 API 省略。新模式候选必须以该模式实际记录的成功步骤和证据独立冻结，不把旧步骤或旧验证改写为新模式通过。当前新模式已完成9条成功实录，搜索四步和详情八步候选分别静态通过；详情候选一次独立探索回放取得正文1条、首层评论2条及正确实际合同，读取范围仍截断。09阶段搜索四步尚未独立初筛回放，笔记来源沿用既有初筛。10阶段已通过通用组合独立搜索取得新来源，再用新七步修订读得正文和有限评论；两个阶段分别留档。两条短评论已按维护者对话确认由Codex代录旧版五轴纠错，保留为待核实咨询意向，但不确认自身装修需求、身份或地区，正文仍未人工核对。原模型和核对保持不变。新上下文、咨询意向及六轴核对合同已实现并完成离线目标验证；当前服务已加载，新版本后续独立真实分析取得两条咨询yes且保留待核实的结果，需求、身份、地区及匹配仍未确认；首轮输出合同失败保留、原因未重现，未建立线索库。当前暂停扩展上述业务识别；通用轻量路由、隔离变参与一个真实新词组合探索已通过，接下来按整体方案第14.0–14.1节补更多范围及正式运行反馈；不自动重读或执行联系。

新模式的动作只允许官网声明页面内已观察且当前唯一可用的搜索输入/`Enter`、已固定实际对象的同站标准笔记锚点，以及普通非交互、不可编辑、非敏感区域的有界读取、等待和滚动。点击前后核对笔记编号，搜索提交后核对实际关键词结果页，读取持续核对页面来源、根及输出；关注、私信、评论输入和发布不在该合同内。

网页自身通信与上述工具动作分别约束。最长15秒的当前动作窗口内，当前主框架自然发起、无凭据URL且标准端口的第一方 HTTPS（`xiaohongshu.com` 或其子域）`xhr/fetch POST` 正常通信，包括页面安全通信，不再用逐接口名单判断其业务副作用。非第一方、子框架、其他需策略授权的方法、非HTTPS、其他资源类型、来源漂移或窗口过期仍拒绝；窗口不续签，动作结束撤销。只允许搜索转入同关键词结果页、点击进入固定笔记这两类已声明来源转换。

这不是网络沙箱，也不证明第一方请求绝无服务端副作用；不直接调用平台 API、不执行任意 JavaScript、不读取请求头/正文，不加指纹伪装或防检测策略。不能据通信允许判定动作成功，也不能据本地阻断认定平台提醒或账号权重；仍以真实页面结果、来源、截图及任务后人工反馈分别核验。GET/HEAD/OPTIONS 等原有被动通信规则不因本模式被改称“所有网络请求均受隔离”。

动作支持 `fill / press / click / read / scroll / wait / extract`。`press` 只允许已观察的普通搜索框按一次 `Enter`，不接受任意按键、评论输入框或 POST 表单。滚动有次数和距离上限，等待有明确条件和超时，动态对象可用文本、来源链接或允许的业务属性精确匹配；多匹配或无匹配时停止。结构化提取按相对 CSS 字段映射读取文本、同源 HTTP 链接或允许的业务属性，并报告本次范围。不能执行任意 JavaScript、任意接口或读取登录凭据。实际字段约束由 `action-contract.mjs` 与后台契约校验。

`candidates.create` 的 `data` 可传 `{name,step_ids:["step_..."]}`。显式选步须为本任务已有的 1–30 个唯一成功步骤编号，按传入顺序冻结；新清单保存 `source_step_ids` 和原步骤完整证据，不接受原始清单或字段覆盖。省略 `step_ids` 仍冻结全部步骤。新组合不继承旧候选验证，须重新检查和回放；选步证据完整不代表新顺序的前置条件已通过。

`scroll.until_selector` 为可选的容器内相对 CSS 条件，目标完整可见时停止，可为 0 次；条件仍受实际滚动次数、距离和等待预算限制，边界内未满足时保留失败证据。`extract.complete_only:true` 只跳过字段真实存在但尚未完整进入视口/裁剪范围的行，返回 `skipped_incomplete_count`，遗漏时 `truncated:true`。真实缺字段、敏感或多匹配不能靠此选项通过，空输出也不能通过内容断言。两个选项分别仅适用滚动/提取，省略时保持旧合同，已有候选不会被改写。

可见等待可显式设置 `min_count:1..100`，等待集合中达到指定数量的可见对象；默认省略仍要求唯一目标。录制和冻结检查仍绑定实际观察到的集合证据；回放允许结果尚未加载时从零项开始等待，实际出现的对象逐次检查，敏感对象、过大范围、超时或未授权请求仍失败。

容器内提取使用 `selector` 指向已观察的唯一普通容器，另设相对 `row_selector`。可选 `batch:{scroll_selector,pixels,max_batches,dedupe_field}` 先读取首批，再向下有界滚动；最多 5 批（含首批），每次 1–1600 像素，批次时间预算 15 秒。必须启用完整行模式，以声明为必填的安全 `id/data-*` 业务属性去重；同一标识内容冲突时失败，不能静默覆盖。滚动根须为已观察的普通纵向滚动容器，属于读取容器且包含所有目标行；来源或根对象变化立即停止。每批都有真实截图引用，成功步骤的 `batch_evidence_ids` 参与候选摘要，部分失败也保留已得证据。输出额外含 `batch_summary`，结束原因区分条数、边界、批数和时间预算；始终标记有界范围，零新增不等于已读完。裁剪跳过计数是各批行观察次数，不能当作唯一评论数。

明确空态使用 `allow_empty:true` 和容器内 `empty_state:{selector,text}`，与批次模式互斥。只有行数为零、唯一普通空态文字精确匹配且完整可见、容器非忙碌、会话可用并经短时再次核对，才返回确认空态；输出附 `empty_state:{confirmed:true,selector,text}`。预期结果必须显式写为 `{"state":"empty"}` 才能通过空态断言；普通文本预期仍要求真实非空内容。单纯零匹配、尚未加载、退出登录、验证页面、裁剪或去重后零新增均不能当作正常空态。平台实际空态定位需要另外学习，不能直接套用本机示例。

搜索初筛使用严格的 `{"state":"nonempty"}` 结构预期，仅适用于合法 `extract` 输出：条数大于零、字段及必填值、来源和批次元数据须符合合同。它不判断标题语义、作者身份或采购意图；可选标题缺失时即使结构验证通过，业务层仍不自动选择该笔记。

新修订可将评论正文明确声明为 `source:"content"`，同时配置内容根 `selector`（省略表示当前行）、根内 `text_selector`、`media_selector` 及 `max_media:1..4`，并保持 `required:true`。媒体定位须根据实际观察选择正文区域，不能把头像当作评论内容。文字可以不存在，但必须有实际可读文字或已加载、可见的图像/视频；真正缺内容、未加载、敏感或歧义仍失败，裁剪与离屏按原完整行规则处理。旧 `source:"text"` 不能携带这些新选项，原文字必填语义不变。

此时 `body` 是 `{kind,text,media,media_truncated}`：`kind` 为 `text / media / mixed`，无文字时 `text:null`，媒体条目仅含 `kind:image|video` 与内容根内相对 CSS。超出媒体上限会明确截断，不返回媒体 URL、替代文字或原媒体文件，也不做 OCR。真实证据使用同批截图；“存在媒体”表示内容未解释，不能推断无需求。`nonempty` 只核对该结构，普通文字预期只比较真实文字，不使用媒体类型或 CSS 充当内容。

来源链接与普通文本分别脱敏：仅 `https://www.xiaohongshu.com` 无凭据、标准端口、精确 `/explore/{24hex}` 或 `/search_result/{24hex}` 的公开笔记路径保留编号，防止编号中的连续数字被误当手机号；查询/片段及其他 URL、普通文本仍按原规则处理。后台接收浏览器文本时仅修复无效 UTF-16 片段，防止长文本截断表情导致 UTF-8 保存失败，合法 Unicode 和历史摘要保持不变。

`discovery.create` 的 `data` 为 `{search_candidate_id,keyword,service,target_customer,region,max_selected}`。当前为装修样例，使用“填写关键词 → 搜索回车 → 可见集合等待 → search_results 提取”四步合同，输出标题/作者（可选）和笔记链接（必填）。地区为空不推断；最多保留 1–3 篇，保存规则模式、冻结摘要、验证、证据与未选理由。无会话时保存失败记录，不自动开启浏览器。新记录追加保存，历史不随规则变更重算；随后由单篇阅读入口接续正文/评论，再以独立分析入口处理文字需求，联系动作尚未接入。

单篇阅读支持已有七步详情候选，以及在点击前增加一次有界目标滚动的八步修订合同，使用其已确认会话，一次请求只读一篇并单独保存。后台只信任初筛 `selected` 中的编号/标题/来源。可选 `note_binding:{note_id}` 仅允许这两种合同：滚动定位及唯一标题点击前核对实际链接 ID，点击后、读取前后和每批检查当前页面 ID；输出的 `note_binding_result` 五项为 `note_id/href_checked/url_checked/source_url/title`。绑定时两个提取输出与核对记录的来源均为实际 origin + pathname，不含查询/片段；截图 URL 仍按原规则脱敏，无绑定的旧执行语义不变。后台再次比对实际编号、标题与提取来源并记录 `note_source_binding` 断言；这不是独立身份的业务读回。

八步合同为 `fill → press → wait → scroll → click → wait → extract → extract`。目标滚动须声明已观察、唯一的普通纵向容器，以及 `until_target:{selector,field,parameter}`（或固定 `value`），并设置 `direction/pixels/max_scrolls/timeout_ms`。目标仅在固定容器后代中匹配，定位与随后点击使用相同 CSS 和目标参数；与 `until_selector` 互斥，不允许整个 body 作为该步骤根。目标已经完整可见且可操作时可以零滚动；否则只按声明距离移动当前容器，在次数、时间或边界内未找到就失败，不更换对象或直跳详情链接。重复目标、编号不符、遮挡、来源/根变化均停止。

整页滚动的页面可在该有界目标动作中显式加入 `scroll_scope:"viewport"`。`selector` 仍是已观察、唯一、非敏感的普通容器，目标仅在其后代中寻找，不能使用 body/html；实际移动固定的 `document.scrollingElement` 所对应页面视口。普通容器可以没有自己的滚动条，但当前及前次视口元信息须有效，页面、根容器和文档滚动对象均持续核对，实际位移按相同次数、距离和时间预算保存。该字段不能用于普通滚动、等待、批次提取或无 `until_target` 的动作，不隐式切换；省略时旧容器滚动语义不变。后台录制表单提供“滚动整页寻找容器内目标”，历史摘要显示“整页”。

回放的 `seek_results` 按步骤保存实际滚动次数、逐次位置/高度、是否找到和停止原因，不保存匹配原文或账号数据，也不代替来源绑定。已有七步候选省略该字段，旧候选与失败不改写。仅八步绑定回放在原 90 秒总预算上增加声明的滚动预算（最多 15 秒），不扩大其他动作或工作进程调用上限；单步滚动预算仍最多 10 次、每次 1600 像素、15 秒。总预算覆盖动作和取证，到期关闭本次浏览器上下文并返回 `VERIFY_BUDGET` 及已完成的内容、证据和定位记录；确认关闭后撤销后台就绪状态，资料保留，重新运行须先打开并确认会话，不自动续跑。真实平台样本与工程测试分别见开发进度。

阅读记录状态区分 `completed / partial / failed`。只有对象核对通过的正文才能作为本篇内容展示；评论失败时可保留已得正文和真实证据。旧文字必填合同遇到纯图片/表情仍会失败，不能用作者或整行冒充正文，也不靠完整行模式跳过真实缺文字；新内容合同须另录候选，平台图像/视频的实际覆盖分别见进度。未学习评论空态的候选仍以非空合同验证，零条/缺字段不当作“确认无评论”。可用 `#/discovery/{run_id}?reading={reading_id}` 回看；跨初筛或失效阅读 ID 不展示错归属结果。超时/失败后先查阅读历史与验证，不自动重试。

明确点击产生的同源新窗口可接续为当前页面；人工确认前的同源新页可接续，但仍须确认后才能采集。未知或出域弹窗关闭并暂停，`block_reason` 说明实际阻断，不能仅显示登录确认。最多保留 10 条脱敏 `popup_observations` 页面事件，不将未知来源伪装成网络请求。

动作失败会保留真实前后观察与安全诊断，`source:action_failure` 不算成功步骤。诊断最多 12 类被阻止请求摘要，按方法、来源、泛化路径和资源类型去重，阻止总数保留；观察另含最多 30 条新执行器运行期间的被动请求摘要。不保存查询参数、请求体、请求头或凭据，不追溯补写旧执行器的请求。

新执行器的被阻止摘要另附固定 `policy_reason`，可选 `active_policy_version` 及仅资源类型不符时的 `expected_resource_types`；相同请求与拒因去重。它解释当前本地策略决定，不能证明接口副作用或平台已发出提醒。`evaluatePlatformRequest` 与原 `matchPlatformRequest` 共享判断；legacy 四类版本和原到期边界不变，新模式按上节独立合同判断。自动动作结束后页面恢复普通通信，不能将本步阻止解释为所有后续通信仍持续被阻止。

失败回放可返回 `failure_diagnostics:{step_position,kind,code,diagnostics}`，诊断包括原受限阶段、阻止总数及最多12类摘要。服务端核对步位/动作/实际错误码，只在真实失败时追加保存到验证和阅读；非法字段丢弃，成功和旧记录缺省不补。总截止同步深复制当时状态，不等待额外诊断或接受迟到成功。后台验证和阅读详情显示失败概要并折叠摘要；旧记录明确未记录，不由错误码猜具体拒因，无放开规则或重试入口。新代码的加载和真实验证状态以进度为准。

## legacy 实验请求模式

以下四类策略只描述未声明新 profile 的旧模式，用于历史复现及对照，不套用到原生通信模式。`platform-policy.mjs` 保留四类实验策略，均限定小红书官网、当前主框架、经现有固定检查核验的实际目标及最长 15 秒动作窗口：`xhs-search-experimental-v3` 允许搜索框填写/回车自然触发的七类精确请求，包含实际观察到的 APM `fetch` 与 `xhr` 两种发送类型；`xhs-note-open-experimental-v2` 只允许点击已观察的同源 `/explore/{24位十六进制标识}` 或 `/search_result/{同类标识}` 笔记链接，并允许八类精确请求，包括已实测的正常浏览历史上报；`xhs-readonly-ui-experimental-v1` 在实际非敏感、非表单根的读取/提取/等待/滚动期间，只允许 `collect xhr` 和 `apm_data fetch` 两类辅助流量，body 仍只适用原有的滚动/等待例外。第四类 `xhs-search-scroll-experimental-v1` 仅对官网精确 `/search_result` 或 `/search_result_ai`、已观察唯一普通根、显式 `scroll_scope:"viewport"` 且解析后非空文字 `until_target` 的定位动作额外允许既有精确 `search_notes xhr`，共三条规则；不含搜索历史、onebox、dqa、APM xhr 或任何用户互动写入。私有状态绑定签发时的完整页面地址与时间，页面/查询变化、早到、到期、非当前主框架或动作结束均不能使用。普通读取和滚动不继承该例外；历史版本证据按各自原规则清洗。

legacy 集合链接必须经精确目标匹配和执行前再次核对，得到唯一实际对象，不能用集合本身授权多次点击。规则均固定方法、origin、pathname 和资源类型，不能相互借用；通用只读辅助策略不能放行检索、feed 或历史接口，搜索分页只适用上述独立动作范围，未知请求和其他点击继续受保护。

策略不会主动请求接口，动作结束即撤销。请求摘要记录匹配版本和规则，后台兼容历史搜索 v1、笔记打开 v1 证据。它允许普通页面操作的有限辅助请求，不声称这些操作在服务端绝对没有状态变化。不能据放行或 URL 认定搜索/详情成功，须另查实际笔记卡、标题、来源和详情正文；规则放行本身不代表完整链路正确或正式可用；当前各候选的执行与质量状态见开发进度。

## 通用证据、质量与读取合同

观察的 `elements` 还提供有界的可读定位：实际可见的普通 id、语义容器/标题、纵向滚动容器，以及从当前 DOM 的 id 族或重复安全 class 核对得到的集合。`selector_basis/source_selectors` 记录定位来源，`read_hints` 最多给出 12 个真实后代的相对 CSS 和有限字段提示；`scroll_y` 说明当前容器高度、位置和是否可继续滚动。总候选不超过 120、离屏最多 30，这些提示不保证网站以后保持同一结构。调用方先核对实际页面，再为字段命名和配置有限提取；旧的独立单批输出分别保留来源，新批次模式只按核对过的业务标识聚合，不把多批数量相加当作唯一评论数。

`open/status/ready` 返回 `login_detection`，只根据可见页面区分已登录、未登录、需要验证或不确定；不读取 Cookie、存储或表单值。已登录无需重新扫码，仍需明确确认当前账号；发现退出或验证会撤销当前可执行状态，恢复后再次确认。不确定不等于未登录，也不会撤销仍有效的人工确认。

候选验证的 `mode` 为 `exploration` 或 `runtime`。后者必须有运行前基线 `baseline_note`，并配置 `observation_window_minutes`。质量观察的 `waiting / clear / alert / uncertain` 是维护者手工复查结果；`clear` 还要求试跑成功、配置窗口已到期且过程审核通过，若填写实际复查时间，该时间也须已到期。提醒晚到时继续追加到原验证记录，原记录和候选摘要不被改写。窗口是复查范围，不是平台安全阈值；维护验证状态不等于桌面交付或正式发布。

能力详情提供“正式模式试跑”直达入口，复用配置弹窗并预选正式模式；原“配置测试”入口保留探索默认值。验证详情说明下一次复查时间和官方消息/搜索/详情/评论功能检查项；账号本人可将实际结果告知本地 Codex，由其代为追加记录。窗口到期不自动通过，也不把运行前“正常”代填为任务后的无异常结果。回放保留受限 `error_codes` 及原错误文字，缺字段、等待超时或登录失效不会转换为空态。

新回放附 `step_timings` 与 `verify_timing`，阅读和验证页面可回看。前者按真实已执行步骤保存 `step_position/kind/status/duration_ms/phase_ms`，阶段限定为输入核验、当前检查、前置取证、目标解析、执行、等待就绪、请求核验、后置取证、失败取证及批次截图；阶段独占计时，未进入的阶段不补零。后者记录总耗时、入口耗时及预算关闭耗时，`close_ms:null` 表示未尝试关闭。失败只保留实际执行前缀，中断不能迟到改成成功；旧记录没有这些字段时显示未记录。耗时不含页面文字或业务参数，也不代表全部是平台响应时间。

已观察定位的当前检查只查询该定位或批次滚动根，复用整页观察的元信息构造、定位语义及敏感判断；普通定位仍须保持原 canonical CSS，集合仍核对类型、数量与代表对象。最新观察、动态唯一匹配、固定实际对象、来源、只读请求和预算检查保留。每步后与每批仍做完整观察和真实截图，限定检查不代替这些证据；测试与真实候选追加验证分别记录。

需求分析不调用浏览器，只使用当前维护者已有、来源核对通过且具正文的完整/部分阅读。模型输入最多 21 个来源、16,000 字，包含文字、临时来源引用、服务端固定的 `context_refs`、未解释媒体标记及必要商家条件，不发作者、真实对象 ID、链接、图片或凭据。`note.context_refs=[]`，每条 `comment_N.context_refs=["note"]`；笔记正文只提供一次，不复制到每条评论，也不接受调用方传入背景。后台逐项核对分类、覆盖、本源逐字依据和独立背景依据，媒体无文字不发模型、由程序标为信息不足；身份始终待核实。结果、固定错误、主/备槽位、实际已返回 Token 与未知费用追加保存到 `analysis_runs`，旧阅读不变。

`analyses.create` 的 `data` 可传 `business_brief_id`，须为同维护者已确认版本；不传则继承阅读绑定的版本，旧阅读沿用原初筛条件。当前模型输入另含必要业务条件，保存独立的角色、表达、自身需求及相关性；服务端派生匹配、理由与展示建议，不执行关注、私信或评论。上下文摘要参与复用，旧结果不重写；地区未知不能当作全国或已匹配。

新分析使用 `renovation-demand-v4 / demand-result-v3`，每项新增 `consultation:{value:"yes"|"no"|"unclear",evidence:[],context_evidence:[]}`。yes/no需1–3条本源逐字依据；yes须业务相关，表达含提问、求建议或自身需求；评论yes另须 `context_evidence:[{source_ref:"note",evidence:["笔记逐字依据"]}]`。最多一个背景来源，每条引用不超过1000字；禁止引其他评论、外部来源或把背景当本条自身事实，模型额外输出动作、匹配等未声明字段会拒绝。`lead_disposition` 和有限 `next_step:review_consultation` 由服务端派生；保留咨询待核不会把自身需求、身份、地区或 `match` 升为已确认。上述字段保存在现有JSON事实中，不改数据库schema或新增线索表；旧分析不补字段，复用须匹配新提示/结果版本。

`reviews.create` 的旧五轴 `data` 为 `{source_ref,previous_review_id,decision,labels,evidence,note}`；新六轴另有 `context_evidence`。`previous_review_id` 首次为 null，修订须回传该来源最新核对编号；过期返回 `REVIEW_STALE`，先重新读取再由维护者决定，不能自动重发。`decision` 为 `confirmed/corrected/uncertain/unreviewable`；前两者传完整标签，后两者传 null 并说明原因，新合同另传空背景依据，旧合同省略背景字段。`demand-result-v2` 只接受原五轴 `labels:{role,demand,expressions,business_relevance,match}`，禁止加咨询/背景字段；`demand-result-v3` 要求六轴新增 `consultation:"yes"|"no"|"unclear"`，本源 `evidence` 与关联笔记 `context_evidence` 分开校验。评论yes必须有真实笔记背景依据，no须本源依据，unclear可为空。修正至少改变一轴，须说明和1–3条本源逐字依据；confirmed须与该版本原模型各轴相同。纯媒体不得标确定结论，地区不足不得标匹配，更早结果结构保持只读。

旧分析核对保存 `analysis-review-v1`，新分析保存 `analysis-review-v2`，均绑定分析/来源摘要、原标签、维护者和前版引用，沿用schema 9的 `analysis_reviews` 追加保护；旧记录不迁移或补值。`reviews.summary` 按分析版本返回最新核对、分状态数量、五/六轴差异和已判定标注一致率；分母只含 confirmed/corrected，无样本为 null，不等于精确率或召回率。真实人工标注不能由合成验收或 Codex 自动生成代替。

确认体所有字段必填：`platform:"xiaohongshu"`、`service:"装修服务"`、`target_customer:"有装修需求的业主"`、`search_terms`（1–3 项）、`region`（文字或 null）、`region_scope:"unspecified"|"specified"|"unrestricted"`、`exclude_service_promotions`（布尔）。指定地区须有文字，另两种须为 null；不限地区必须显式选择，确认不再调用模型。解析和确认以 schema 8 的 `business_briefs` 追加保存，维护者补充来源注明 `maintainer_edit`，不伪造原文依据。

模型通过服务端 `ASSISTANT_MODEL_*` 配置；主/备用只切不同 Key，不升级型号，不重放浏览器。限定错误最多转一次备用，单请求最多 30 秒、整次最多 60 秒；格式/业务依据错误不切换来掩盖失败。相同阅读摘要、配置及提示/结果版本已完成时复用原分析；进行中返回 `ANALYSIS_BUSY`，失败或超时先查历史，再由维护者决定是否另发请求。Token 汇总不包含未返回的未知用量，不能当作实付费用或商家扣费。

批次时间上限仍为 15 秒，包含读取、滚动和批次取证，并不晚于当前动作请求策略的到期时间；在上限内预留最多 2 秒关闭。截止会中断当前浏览器上下文、撤销策略和 ready，返回 `BATCH_BUDGET`，不续签窗口或自动重放。仅实际关闭事件确认才报告 `session_closed:true`，录制和验证都撤销后台就绪。总试跑预算先到时仍为 `VERIFY_BUDGET`。每批先暂存数据，实际完整观察与 PNG 完成、来源/根/登录/请求复查通过且未到期后才提交；截止时只可保留已提交批次的深复制前缀，`truncated:true / stop_reason:time_budget`，关联验证仍失败、业务阅读仍为部分完成。没有完成批次不返回评论，不能据此确认无评论；来源变化、冲突或不符合当前模式通信合同的请求，均不能借部分输出冒充成功。

完整观察仅在单次同步 DOM 求值中缓存重复的节点几何、样式、敏感判断和文本遍历，不跨调用、页面或滚动保存缓存；原筛选、上限、全文/视口、敏感掩码及逐批真实截图保留。`test-observation-cache.mjs` 使用显式提供的修改前基线做隔离浏览器等价比较；`test-batch-deadline.mjs` 在本机夹具验证取消与部分结果。内部缩短预算只供模块测试，维护 API 和 JSONL 不开放预算覆盖。

legacy 官网 `wait` 在进入自动化前预检现有只读策略；新 profile 在相同根/目标检查后独立建立原生通信动作窗口。未声明范围时，最新观察未包含目标集合、当前实际根为空或其他前置不满足，返回 `READONLY_WAIT_NOT_READY` 并保留失败证据，不进入无策略的自动化等待；敏感对象仍为 `SENSITIVE_OUTPUT`。策略窗口和规则均不扩展，不继承上一搜索步骤权限；非官网示例等待行为与原 body 例外保留。

加载过渡可显式声明 `{"kind":"wait","selector":"#global a.title","wait_scope":"#global","state":"visible","min_count":1,"timeout_ms":10000}`。这里的 CSS 仅为格式示例，真实使用须先观察并学习当前页面。`wait_scope` 只允许可见集合等待，根须来自最新观察的唯一、可见、非敏感普通读取容器；body/html/form 等不适用。目标可以尚未出现，只在固定根内查询，范围外同名对象不计数；计数仅含可见、在视口且非忙碌对象。根/页面来源变化、敏感对象或超过100项停止；完整后置观察与截图后再次核对根及条件，冻结根的真实证据。旧步骤不自动获得新字段，阅读仍支持原七/八步结构。

范围等待的 `timeout_ms` 覆盖轮询与根/集合/登录检查，最长15秒且不晚于当前策略到期，在内部预留最多2秒关闭。到期返回 `WAIT_TIMEOUT`、撤销 ready 和策略，实际关闭确认才回传 `session_closed:true`；不自动重开或重试。后置取证在撤销自动化和策略后执行，沿用原截图限制与整轮总预算；总截止先到为 `VERIFY_BUDGET`。`test-scoped-wait.mjs` 只用本机隔离浏览器与官网元数据纯用例，不能代替真实平台学习与回放；加载状态及实际结果见进度。

`pnpm test:control` 只验证隔离的本机传输夹具，`pnpm test:session` 验证合成 DOM 登录状态，`pnpm test:platform-policy` 验证实验策略的纯函数边界。真实浏览器工具与完整 API/UI 验证分别由 `node tools/learning/test-browser-worker.mjs` 和 `pnpm test:learning` 覆盖；均使用本机合成页面，不访问真实账号。

## 浏览器工作进程协议与生命周期

维护 API 以标准输入输出的逐行 JSON 调用 `browser-worker.mjs`，不把工作进程直接开放给网页。输入为 `{ "id":"request-id", "method":"capture", "params":{"task_id":"task-id"} }`，输出为同一 `id` 的 `result` 或含 `message/code` 的 `error`。标准输出只用于协议，调用按顺序执行；工作进程不调用模型。

- `open` 接收 `task_id/account_key/entry_url`，打开固定资料目录，等待人工登录；`ready` 记录 `identity_label`，之后必须显式 `capture` 才开始录制。
- `capture` 返回当前文本、视口文本、定位候选、视口截图和证据路径，优先当前视口，限制离屏候选数量并排除隐藏文字；`action` 执行上述受限动作并保留成功或失败前后证据。
- `verify` 从入口重放冻结步骤，以参数替换输入和目标，按预期文本或明确空态核对实际读取结果，报告真实系统和浏览器版本。
- `status` 查询 `awaiting_user/observing/closed`；`close` 关闭上下文并释放账号占用，保留资料目录。

关闭标准输入或输出管道断开会立即关闭进程持有的浏览器上下文，执行中的试跑自然中断。关闭入口等待同一个清理过程，不重放排队动作；调用方须等待实际退出，再重开同一资料目录。相同账号资料同一时刻只能由一个任务持有。

`ASSISTANT_LEARNING_HOME` 默认为 `.runtime/learning`，浏览器资料按 origin 和后台限定的账号引用散列分目录。`ASSISTANT_BROWSER_CHANNEL` 默认 `chromium`，可指定已安装的 `msedge`；浏览器缺失时返回明确错误，不自动安装。`ASSISTANT_BROWSER_HEADLESS=1` 用于隔离测试，维护者登录正常使用可见浏览器。

首期限定入口同一 origin，不支持跨站 SSO。人工确认前不采集页面；证据过滤敏感表单/输入值，截图遮盖输入区。持久化 Cookie 与人工声明均不等于自动身份核验。legacy 自动动作期间默认拦截非 GET/HEAD/OPTIONS 请求，仅允许上述四类实验策略的精确匹配例外；显式新 profile 按本页固定动作/原生通信合同执行，不将未知第一方 POST 一概认定为业务写入。其他平台取数适配须另行观察确认。

浏览器回归使用 `.tmp/worker-regression-*` 的隔离页面和资料目录，覆盖会话确认、互斥、敏感字段、受限动作、变参读取、错误断言、Cookie 重开及执行中 EOF 清理。成功后默认清理；`node tools/learning/test-browser-worker.mjs --keep-artifacts` 可保留报告与截图。关闭后再次试跑仍须重新打开会话并人工确认。

新模型合同诊断只对实际输出失败追加 `output_diagnostics:{check}`，仅接受16个固定无文本枚举；成功与旧记录不补造。它不包含原始模型输出、来源编号、URL或供应商错误，不改变允许范围或触发自动重试。当前有限真实验证见进度：一条首轮合同失败保留，后续独立新分析通过，不能倒推首次具体原因或整体稳定性。


## 通用链路复用验证

后台入口为“学习 → 链路复用”，地址 /#/routes。先选同任务/站点/执行配置的搜索和详情候选，填新关键词，再“召回并锁定版本”→“执行变参验证”。召回只固定ID/摘要；执行复用当前已确认的会话，不自动开启浏览器，不调用业务模型。当前详情候选仍含重搜前缀，组合会搜索两次。

routes.resolve 的 data 为 {platform,task_type:"search_note_comments",search_candidate_id?,detail_candidate_id?}。routes.verify 再传两个固定引用、search_digest/detail_digest和keyword，可选note_id只从本次实际结果选择，不能传外部标题或动作。未指定ID且有多对时409。组合kind=route在原验证历史保存；默认呈现usable_outputs，原始actual_outputs仅作失败取证。route不晋级正式质量或发布。

维护者已明确持续授权固定学习账号；本地Codex后续检测同资料目录仍已登录即可沿用授权完成ready，不再重复询问账号。登录失效、需验证或会话异常时暂停并提示；不把持久Cookie单独当作登录有效或自动身份核验。

## 功能入口与页面层级盘点

后台“学习 → 平台路径”（`/#/platform-paths`）按五组展示首批33个功能模板。它不是平台功能总数；每项以功能路径盘点任务中的官方页面、当前可见非敏感元素、分类标记及已登记截图引用共同核对，只有标记或文字不算完成。页面不加载私人截图或展示昵称/原文，读取账本不会操作平台。已有搜索/正文/首层评论的组合验证独立展示，不将观察入口晋级成已固化能力。

盘点任务显式选择 `playwright-xhs-navigation-ui-v1`，合同为 `engine:playwright / action_policy:xhs-observed-navigation-readonly-v1 / network_policy:xhs-page-navigation-v1`。支持已观察且实际唯一可用的发现/搜索/标准笔记/公开主页/通知同站锚点；点击前固定实际href，动作后核对目标。笔记仅允许同官方站点、相同24位编号的标准笔记路径别名与跟踪参数变化。公开主页只允许实际省略原链接中各最多一个channel_type/parent_page_channel_type，必须确实省略至少一项；其余有序query、xsec、路径/对象/hash保持一致，无省略仍完整地址相同，其他目标继续按完整地址核对。页面新开窗口必须属于本步明确点击的opener与目标，实际主框架沿用原动作策略及截止时间，不续签；旧v1与legacy不获得这些权限。

发布者和评论者的主页入口分开记录。按当前页面→可见入口→下级控件→关闭/返回→参数化候选→独立验证推进，动态对象取样。`更多`、非语义标签和回复展开等控件尚待固定识别及真实状态断言，不将未捕获算作不存在；消息窗口、关注/取关、评论/回复发布和私信发送尚未学会，本轮不实际发送或改变关系。

工程检查分别使用 `pnpm test:navigation-profile` 和 `pnpm test:platform-paths-ui`；本机合成导航、纯合同判断、真实平台观察及冻结回放分别报告，不互相替代。实际样本与缺口见开发进度。