Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(browser): 候选验证复用显式保存避免旧定义自动回写

Dash39e0107e2a7f
diff --git a/packages/browser-control-runtime/upstream/MAINTAINING.md b/packages/browser-control-runtime/upstream/MAINTAINING.md
index 2757358f37..8c64bc6fd4 100644
--- a/packages/browser-control-runtime/upstream/MAINTAINING.md
+++ b/packages/browser-control-runtime/upstream/MAINTAINING.md
@@ -199,7 +199,7 @@ pnpm --filter @cindy/browser-control-runtime test # 契约 + SSRF guard
### 配方按使用维护与等待条件(2026-10-23)
-- `recipe` 支持 `site + recipeDraft` 内存试跑;`saveRecipe` 通常接受同一 MCP 会话已通过验证的相同内容与 profile。声明 read 且仅含 navigate、无 fn 的 wait、extract、requests、responseBody 的新流程可用 `deferValidation:true` 保存 candidate(不能覆盖已有 id),下一次真实任务显式执行且 guard/expect 全部通过后转为 active;交互、任意脚本和 adapter 须当次真实操作验证,不能只信 access 标签。保存、发现、执行旧 candidate 共用 `deferredRecipeIssue` 判据;不承诺远端 GET 没有业务副作用,现有逐次审批仍适用。状态写入失败保留本次执行成功,不能重放。active 不证明未测参数组合。正常检查不请求模型,不定时后台刷新;失败交给当前任务模型观察、同 id 一轮修订,失败回普通操作。修复预算为会话内状态,MCP 会话重建后重新计数;暂停状态写进配方,跨重启保留。
+- `recipe` 支持 `site + recipeDraft` 内存试跑;`saveRecipe` 通常接受同一 MCP 会话已通过验证的相同内容与 profile。声明 read 且仅含 navigate、无 fn 的 wait、extract、requests、responseBody 的新流程可用 `deferValidation:true` 保存 candidate(不能覆盖已有 id)。下一次真实执行且 guard/expect 全部通过后仅返回 verified、保留会话内凭证;沿用显式 saveRecipe 启用,不重复试跑。候选执行成功或失败都不回写旧定义,避免覆盖其它任务的新修订;失败只暂停本任务,下个任务仍须验证。不新增锁或版本更新协议。交互、任意脚本和 adapter 须当次真实操作验证,不能只信 access 标签。保存、发现、执行旧 candidate 共用 `deferredRecipeIssue` 判据;不承诺远端 GET 没有业务副作用,现有逐次审批仍适用。状态写入失败保留本次执行成功,不能重放。active 不证明未测参数组合。正常检查不请求模型,不定时后台刷新;失败交给当前任务模型观察、同 id 一轮修订,失败回普通操作。修复预算为会话内状态,MCP 会话重建后重新计数;已启用或旧配方沿用原有持久暂停,跨重启保留。
- 新保存配方的交互/读取步骤须有完整 URL 和可选唯一可见 CSS 元素/文本 `guard`;末步 `expect` 检查数量、必需顶层字段与业务值。extract 将 guard 与读取合成同一次 evaluate;写动作前独立 guard,不能把它当事务或幂等保证。工具不重放步骤,后置失败须先核对写入是否已成功。
- 本地每站 `recipes/<id 的 SHA-256>.json` 支持多个流程,原子替换复用 Desktop 工具;loader 兼容 `recipe.json`、新文件优先。旧配方保留执行兼容,实际失败后暂停;新建/修订必须经过新验证。失败不把候选覆盖到正式配方。跨任务并发修改同一配方仍是最后写入优先,不新增锁/版本管理系统。
- `wait.fn` 补丁在 `sync.mjs`:host 只编译函数,页面执行;传真实 function 给 `waitForFunction`,避免函数源码被当 truthy、重复 eval 被 Trusted Types 拦截。timeout 放第三参数。异步 predicate 明确拒绝,避免 Promise 假成功;evaluate 仍支持 async。
diff --git a/packages/lizi-mcps/src/browser/browserMcpServer.test.ts b/packages/lizi-mcps/src/browser/browserMcpServer.test.ts
index 95fb9c81b4..d9d1808ae9 100644
--- a/packages/lizi-mcps/src/browser/browserMcpServer.test.ts
+++ b/packages/lizi-mcps/src/browser/browserMcpServer.test.ts
@@ -222,7 +222,38 @@ describe('browser experience cache', () => {
} finally { await h.cleanup(); }
});
- it('persists a read candidate without replay and promotes it on a later real invocation', async () => {
+ // Review regression, unit/MCP entry: a candidate finishing after another
+ // task's validated save must not overwrite that revision. Existing lifecycle
+ // tests ran only one tool instance and could not expose the stale write.
+ it.each([true, false])('keeps another task\'s newer revision when an older candidate finishes (ok=%s)', async ok => {
+ let stored: Recipe = { ...readDraft, validation: { site: 'experience.test', state: 'candidate' } };
+ let saves = 0;
+ let entered!: () => void;
+ let release!: () => void;
+ const dispatched = new Promise<void>(resolve => { entered = resolve; });
+ const finish = new Promise<void>(resolve => { release = resolve; });
+ const deps: Partial<BrowserMcpDeps> = {
+ getUserRecipes: async () => ({ version: `interleaved-candidate-${ok}-${saves}`, recipes: new Map([[stored.id, stored]]), siteGuides: new Map() }),
+ saveUserRecipe: async ({ recipe }) => { stored = recipe; saves++; return { ok: true }; },
+ };
+ const oldTask = await makeHarness({ ...deps, getRuntime: () => ({
+ call: async req => { entered(); await finish; return { ok: true, action: req.action, data: { result: { matched: ok, value: extracted } } }; },
+ }) });
+ const newTask = await makeHarness(deps, () => ({ result: { matched: true, value: extracted } }));
+ const pending = invoke(oldTask, { action: 'recipe', recipeId: readDraft.id, inputs: { query: 'book' } });
+ try {
+ await dispatched;
+ const revised: Recipe = { ...readDraft, steps: readDraft.steps.map(step => ({ ...step, extract: { fields: { title: 'h2' } } })) };
+ expect((await invoke(newTask, { action: 'recipe', site: 'experience.test', recipeDraft: revised, inputs: { query: 'book' } })).verified).toBe(true);
+ expect((await invoke(newTask, { action: 'saveRecipe', site: 'experience.test', recipeDraft: revised })).ok).toBe(true);
+ release();
+ expect((await pending).ok).toBe(ok);
+ expect(stored.steps).toEqual(revised.steps);
+ expect(saves).toBe(1);
+ } finally { release(); await pending; await oldTask.cleanup(); await newTask.cleanup(); }
+ });
+
+ it('validates a read candidate on later real use and enables it only on explicit save without replay', async () => {
const draft = readDraft;
let stored: Recipe | undefined;
let version = 0;
@@ -243,9 +274,12 @@ describe('browser experience cache', () => {
expect((await invoke(next, { action: 'recipe', recipeId: draft.id, profile: 'other', inputs: { query: 'book' } })).ok).toBe(false);
expect((await invoke(next, { action: 'recipe', recipeId: draft.id })).ok).toBe(false);
expect(next.calls).toHaveLength(0);
- expect((await invoke(next, { action: 'recipe', recipeId: draft.id, inputs: { query: 'book' } })).output).toEqual(extracted);
+ expect(await invoke(next, { action: 'recipe', recipeId: draft.id, inputs: { query: 'book' } })).toMatchObject({ output: extracted, verified: true });
expect(next.calls).toHaveLength(1);
+ expect(stored?.validation?.state).toBe('candidate');
+ expect((await invoke(next, { action: 'saveRecipe', site: 'experience.test', recipeDraft: draft })).ok).toBe(true);
expect(stored?.validation?.state).toBe('active');
+ expect(next.calls).toHaveLength(1);
} finally { await next.cleanup(); }
});
@@ -260,12 +294,13 @@ describe('browser experience cache', () => {
const result = await invoke(h, { action: 'recipe', recipeId: draft.id, inputs: { query: 'book' } });
if (failure === 'guard') {
expect(result.ok).toBe(false);
- expect(stored.validation?.state).toBe('suspended');
+ expect(stored.validation?.state).toBe('candidate');
expect((await invoke(h, { action: 'recipe', recipeId: draft.id, inputs: { query: 'book' } })).ok).toBe(false);
expect(h.calls).toHaveLength(1);
} else {
- expect(result.ok).toBe(true);
- expect(result.maintenanceMessage).toContain('保存失败');
+ expect(result).toMatchObject({ ok: true, verified: true });
+ expect(result.maintenanceMessage).toBeUndefined();
+ expect((await invoke(h, { action: 'saveRecipe', site: 'experience.test', recipeDraft: draft })).ok).toBe(false);
expect(stored.validation?.state).toBe('candidate');
expect(h.calls).toHaveLength(1);
}
diff --git a/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md b/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md
index f68ad2bf14..3e4bf704cd 100644
--- a/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md
+++ b/packages/lizi-mcps/src/browser/prompts/rules/browser-workflow.md
@@ -63,7 +63,7 @@
7. 任务完成后,可用不带 `proxyServer` 的 `{action:"start"}` 明确恢复普通直连模式。代理 A 切代理 B、代理切直连都会重启浏览器;重复同一代理则保持当前进程。
#### Token 效率(按"最省 → 兜底"的顺序选路)
-1. **优先复用配方**: `open/navigate` 会随结果给出最多三个本地 `recipeSuggestions`,可带简短 `intent` 收窄;同任务相同站点/意图且目录未变不重复提示,不另起模型请求。自行判断业务、账号与参数是否适用,再显式 `recipe(recipeId,inputs)`;候选会在本次真实执行通过校验后转为 active。已知 id 直接复用,无须先导航或查目录。缺少合适候选时可用 `siteguide` + `site` 看完整站点指南,不要默认加载全部目录;`siteguide` 不是网站的 sitemap.xml。
+1. **优先复用配方**: `open/navigate` 会随结果给出最多三个本地 `recipeSuggestions`,可带简短 `intent` 收窄;同任务相同站点/意图且目录未变不重复提示,不另起模型请求。自行判断业务、账号与参数是否适用,再显式 `recipe(recipeId,inputs)`;候选在真实执行通过校验后返回 `verified:true`,需启用时用 `saveRecipe` 保存同一草稿,不重复试跑。已知 id 直接复用,无须先导航或查目录。缺少合适候选时可用 `siteguide` + `site` 看完整站点指南,不要默认加载全部目录;`siteguide` 不是网站的 sitemap.xml。
2. **数据型页面优先读接口,别扒 DOM**:很多列表 / 详情背后是 JSON API,读接口比扒渲染后的 DOM 又稳又省。
- ① `action: "requests"`(带**具体** `filter`,如 `/api/quotes`;别用太宽的 `api`,会撞 `fonts.googleapis.com` 之类)看页面发了哪些 XHR/fetch、拿到接口 URL。这是读**已发生**请求的清单。
- ② 读 body:**GET 接口最稳的姿势是直接 `navigate` 到该 URL**,再用 `extract`(`fields:{ data:"body" }`)或 snapshot 读返回的 JSON。
diff --git a/packages/lizi-mcps/src/browser/prompts/rules/recipe-author.md b/packages/lizi-mcps/src/browser/prompts/rules/recipe-author.md
index 03709426ba..df4a859cc5 100644
--- a/packages/lizi-mcps/src/browser/prompts/rules/recipe-author.md
+++ b/packages/lizi-mcps/src/browser/prompts/rules/recipe-author.md
@@ -10,7 +10,9 @@
4. **抽取**:扒 DOM 字段用 `extract`——**先 scoped `snapshot` 确认选择器在页面上真实存在再写**(别凭空猜选择器、别把属性拼进选择器)。`fields` 的 string 是纯 CSS 选择器(取 textContent),取属性用 `{selector, attr}`,取链接用 `{selector, type:"href"}`。列表用 `from` + `multiple`。
5. **交互步**:`click` / `type` / `select` 直接写**稳定 CSS `selector`**(运行时由 act 解析,不写死 snapshot ref,跨会话不腐烂)。`type` 配 `submit: true` 提交表单。
6. **验证**:用 `action:"recipe", site, recipeDraft, inputs` 当场试跑。交互和读取步骤须有 `guard:{url,selector?,text?}`:完整 URL 精确匹配,标准 CSS selector 须唯一可见匹配,可选 text 精确匹配(去首尾空格)。URL 应包含账号/项目身份;同 URL 多账号时用页面账号元素校验。最后一步须带 `expect:{minCount?,requiredFields?,equals?}`,用 `as` 和 `output:"{{变量}}"` 返回经过验证的结果。expect 检查每条记录的顶层字段,equals 的字符串可插值。guard/expect 不可 optional。
-7. **沉淀**:`action: "saveRecipe"`,传 `site` + `recipeDraft` + 可选 `siteGuideDraft`。通常保存本任务中刚试跑成功的同一份 draft、site 和 profile;不要提供宿主管理的 validation 字段。新流程声明 `access:"read"` 且仅含 `navigate`、无 `fn` 的 `wait`、`extract`、`requests`、`responseBody` 时,可加 `deferValidation:true`,不重新跑当前任务,先存 candidate,等下一次真实任务显式执行并通过所有 guard/expect 后转为 active。交互、`evaluate`、脚本或 adapter 不能凭 read 标签延后验证,须在当次真实操作中验证;不为测试重放写操作。候选不能覆盖已有配方。每站可保存多个 id。
+7. **沉淀**:`action: "saveRecipe"`,传 `site` + `recipeDraft` + 可选 `siteGuideDraft`。通常保存本任务中刚试跑成功的同一份 draft、site 和 profile;不要提供宿主管理的 validation 字段。新流程声明 `access:"read"` 且仅含 `navigate`、无 `fn` 的 `wait`、`extract`、`requests`、`responseBody` 时,可加 `deferValidation:true`,不重新跑当前任务,先存 candidate。下一次真实任务显式执行且 guard/expect 全部通过时返回 `verified:true`,仅保留本任务验证凭证,不自动改写配方文件;需要启用时,在同一任务用相同 site、profile 和 recipeDraft 调用普通 `saveRecipe` 转为 active,无需再次试跑。交互、`evaluate`、脚本或 adapter 不能凭 read 标签延后验证,须在当次真实操作中验证;不为测试重放写操作。候选不能覆盖已有配方。每站可保存多个 id。
+
+尚未启用的 candidate 执行成功或失败都不自动回写磁盘:成功留下本任务凭证,失败暂停本任务并允许单轮修订;若保留为候选,下个任务仍须验证。已启用或旧配方继续沿用失败持久暂停机制。显式保存仍按原规则后写优先,不是跨任务版本合并。
验证用少量组合输入覆盖变化的参数、数量和空结果;优先使用下一次真实需求,不穷举、不承诺未测能力。active 仅证明已执行的检查通过,不代表所有输入都测试过。账号/项目的页面身份必须进入 guard,不能仅靠 profile 或站点名称推断登录身份。参数化所有业务值,不保存实际查询、用户资料、密码或令牌;普通记录只用于判断是否重复,不自动上传或转成内置配方。
diff --git a/packages/lizi-mcps/src/browser/tools.ts b/packages/lizi-mcps/src/browser/tools.ts
index 393dae0dda..62c9a4b310 100644
--- a/packages/lizi-mcps/src/browser/tools.ts
+++ b/packages/lizi-mcps/src/browser/tools.ts
@@ -817,6 +817,7 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browse
}
const id = entry.recipe.id;
const persisted = candidate ? (await recipeRegistry(deps)).get(id)?.recipe : entry.recipe;
+ const verifyingDraft = candidate || entry.recipe.validation?.state === 'candidate';
if (persisted?.validation?.profile !== undefined && persisted.validation.profile !== (args.profile ?? '')) {
return errorResult('recipe', '配方属于另一浏览器 profile;请显式使用原 profile,或为当前身份重新整理配方');
}
@@ -870,23 +871,19 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browse
const contextCurrent = scopeIsCurrent();
if (runResult.ok && !contextCurrent) {
maintenanceMessage = '本次执行成功,但浏览器后端已切换;未保留试跑凭证或更新配方状态,不要重放动作。';
- } else if (runResult.ok && candidate) {
- verifiedDrafts.set(id, { site: args.site!, content: JSON.stringify(entry.recipe), profile: args.profile ?? '' });
- } else if (runResult.ok && persisted?.validation?.state === 'candidate' && deps.saveUserRecipe) {
- // Promotion describes the actual checks on this invocation, not
- // proof of every possible parameter combination. Never replay it.
- try {
- const saved = await deps.saveUserRecipe({ site: persisted.validation.site,
- recipe: { ...persisted, validation: { ...persisted.validation, state: 'active' } } });
- if (!saved.ok) maintenanceMessage = '本次执行成功,候选状态保存失败;下次仍会按候选验证。';
- recipeCache = null;
- } catch { maintenanceMessage = '本次执行成功,候选状态保存失败;下次仍会按候选验证。'; }
+ } else if (runResult.ok && verifyingDraft) {
+ // Reuse explicit saveRecipe after validation. Successful execution
+ // must not write an old snapshot over another task's newer revision.
+ const { validation, ...draft } = entry.recipe;
+ verifiedDrafts.set(id, { site: args.site ?? validation!.site, content: JSON.stringify(draft), profile: args.profile ?? '' });
} else if (contextCurrent && !runResult.ok && lastCallDispatched && runResult.failureKind !== 'input' && runResult.failedStep !== undefined) {
// A failed draft is not evidence that the saved active version is
// stale. Keep its state, while limiting new/previously failed drafts.
if (!candidate || !persisted || suspended) failedRecipes.add(id);
- // Only failure while using the saved definition can suspend it on disk.
- if (!candidate && persisted && deps.saveUserRecipe) {
+ // Unenabled candidates only pause this task. Preserve the existing
+ // disk suspension of active/legacy recipes, never write a candidate
+ // snapshot back after either success or failure.
+ if (!verifyingDraft && persisted && deps.saveUserRecipe) {
try {
// Bundled recipes predate validation metadata; their guide
// supplies the owning site. Never guess from a host substring.
@@ -907,7 +904,7 @@ export function registerBrowserTools(registry: BrowserToolRegistry, deps: Browse
{ type: 'text', text: (scopeIsCurrent() ? textResult : resultText)({ action: 'recipe', provenance: entry.provenance, ...runResult,
...(maintenanceMessage ? { maintenanceMessage } : {}),
...(runResult.ok && lintBrowserOutput(runResult.output).length ? { advisory: lintBrowserOutput(runResult.output) } : {}),
- ...(!runResult.ok ? { recovery, maintenanceMessage } : candidate ? { verified: contextCurrent } : {}) }, { profile: args.profile, targetId: activeTargetId }) },
+ ...(!runResult.ok ? { recovery, maintenanceMessage } : verifyingDraft ? { verified: contextCurrent } : {}) }, { profile: args.profile, targetId: activeTargetId }) },
],
isError: !runResult.ok,
};
diff --git a/scripts/browser-experience-live.mjs b/scripts/browser-experience-live.mjs
index 58ae505b7a..dd278e5e01 100644
--- a/scripts/browser-experience-live.mjs
+++ b/scripts/browser-experience-live.mjs
@@ -278,6 +278,14 @@ try {
assert.equal(use.result.ok, true);
assert.equal(use.result.output.records.length, 2);
assert(use.result.output.records.every((row) => row.text && row.author));
+ assert.equal(use.result.verified, true);
+ assert.equal((await readRecipes()).get(draft.id).validation.state, 'candidate');
+ const enable = await call('candidate-enable', {
+ action: 'saveRecipe',
+ site: 'quotes.toscrape.com',
+ recipeDraft: draft,
+ });
+ assert.equal(enable.runtime.length, 0);
assert.equal((await readRecipes()).get(draft.id).validation.state, 'active');
report.checks.candidateSavedWithoutReplayAndPromotedNextSession = true;
report.experiences = await store.list('quotes.toscrape.com');
@@ -305,7 +313,7 @@ try {
true,
);
assert.equal(failed.result.failureKind, 'guard');
- assert.equal((await readRecipes()).get(broken.id).validation.state, 'suspended');
+ assert.equal((await readRecipes()).get(broken.id).validation.state, 'candidate');
await call('repair-observe', {
action: 'snapshot',
selector: 'body',