Add structured cache option with dir support and validation (docs, types, core, tests)

[yuyutaotao]

Motivation

• Provide a structured cache option (replacing ambiguous cacheId usage) so callers can configure cache behavior and directory explicitly.
• Allow writing cache files to a custom directory separate from <MIDSCENE_RUN_DIR>/cache to isolate cache from logs/reports.
• Add input validation for cache configuration to surface misconfiguration early.

Description

• Updated public docs (apps/site/docs/en/api.mdx and apps/site/docs/zh/api.mdx) to document the new cache?: false | { id: string; strategy?: 'read-only' | 'read-write' | 'write-only'; dir?: string } shape and mark cacheId as deprecated.
• Extended types in packages/core/src/types.ts by adding dir?: string to CacheConfig and normalizing the cache union type.
• Implemented processCacheConfig in packages/core/src/agent/agent.ts to validate cache inputs (disallow cache: true, require id, validate non-empty dir) and return directory in the normalized config.
• Propagated the directory into TaskCache by adding cacheDirectory to its constructor options and using it to compute cacheFilePath in packages/core/src/agent/task-cache.ts.
• Added unit tests in packages/web-integration/tests/unit-test/agent.test.ts covering custom cache directory behavior and the empty-dir validation error.

Testing

• Ran the agent unit tests in packages/web-integration including the new cache-dir cases and the tests passed.
• Ran core package unit tests covering TaskCache behavior and they passed.

---

Codex Task

[cloudflare-workers-and-pages]

Deploying midscene with    Cloudflare Pages

Latest commit:	a861698
Status:	✅  Deploy successful!
Preview URL:	https://23aba89c.midscene.pages.dev
Branch Preview URL:	https://codex-verify-cache-directory.midscene.pages.dev

View logs