null-object-0000 · null-object-0000 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.turbo/
+.DS_Store
+*.log
+*.tsbuildinfo
diff --git a/.pnpm-store/v11/index.db b/.pnpm-store/v11/index.db
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,44 @@
+# DataRecipe Agent Architecture
+
+DataRecipe is an **Agent Tool Layer**, not a fixed-flow Skill generator.
+
+The primary user experience is the browser side panel's real conversational Agent. Users configure an OpenAI-compatible Provider and state goals in natural language; the side-panel Agent plans through `/v1/chat/completions` tool calls and uses the same Agent Tool Layer that future external Agents can reuse.
+
+## Responsibility boundaries
+
+- The browser extension captures authorized page/API activity and exposes bounded tools.
+- The side-panel Agent (or a future external Agent) decides which captures to inspect, how much content to read, how to refine a recipe, and how to write `SKILL.md` for the user's actual goal.
+- The user authorizes browser access and confirms sensitive execution/export actions.
+- The final artifact is a ZIP **Data Skill Package** containing `SKILL.md`, `workflow.json`, one or more `recipes/*.json`, examples, and human-readable documentation. `.data-skill.json` is development/import interchange only.
+- Provider credentials stay in `chrome.storage.local`; never pass them to a tool, model message, capture, recipe, or package.
+
+## Agent-facing tools
+
+Keep these names and responsibilities stable:
+
+- `listCapturedSources`: discover captured sources without loading every response.
+- `readCapture`: read request/response content using preview, page, range, or full mode.
+- `inspectResponse`: inspect response structure and selected content using the same bounded read modes.
+- `buildRecipe`: produce a rule-derived recipe draft in RecipeStore, optionally applying Agent edits by `recipeId`.
+- `runRecipe`: execute or dry-run a stored recipe by `recipeId` through the Browser RPC Bridge.
+- `exportSkillPackage`: package Agent-authored `SKILL.md`, all referenced `recipeIds`, and `workflow.json` as a real ZIP.
+
+Never silently expand a bounded read to a full read. Never expose Cookie, Authorization headers, or equivalent browser credentials to the Agent.
+
+`readCapture` / `inspectResponse` full reads, every `runRecipe`, and every `exportSkillPackage` require action-time user confirmation. Model-provided flags do not count as user confirmation.
+
+## Runtime durability
+
+- Prefer streaming Chat Completions and aggregate incremental text and `tool_calls`; fall back to non-streaming only when the Provider explicitly rejects streaming.
+- Checkpoint conversation messages immediately after every assistant message and tool result.
+- Store active conversation history and RecipeStore snapshots in `chrome.storage.session`, scoped by `tabId + conversationId`.
+- Never clear history on model changes or failures. Only the explicit “新建对话” action clears the active conversation.
+- The model never sends a complete recipe back to the plugin. `buildRecipe` creates a `recipeId`; patch, run, and export operations reference that ID.
+- Validate every tool input and return structured errors with `code`, `message`, `retryable`, and `expectedInput`.
+- Stop repeated identical failed calls, enforce per-tool budgets, and request a `tool_choice: none` failure summary instead of discarding history at the iteration limit.
+- Persist UI history as ordered `ConversationEvent`s: user/assistant messages, tool calls, tool results, statuses, artifacts, and outcomes. Create a tool-call event before execution and update that event in place.
+- Treat `AgentRunOutcome` as authoritative. Carry it into the next model turn; never let prose contradict structured tool errors. Budget pauses preserve pending steps and offer continuation.
+
+## Artifact policy
+
+Files under `recipes/` are machine-oriented execution configurations. Rules and tools generate initial drafts; the Agent may inspect and modify them. `workflow.json` expresses ordered input/output dependencies across recipes, including list → filter → detail → optional diff flows. Never describe multiple interfaces in `SKILL.md` while exporting only one recipe. `SKILL.md` is authored by the configured model from tool results and user intent, and must not be constrained to a deterministic template. Mock generation is test/development-only and must never appear in the user-facing path.
diff --git a/PR_TESTING.md b/PR_TESTING.md
@@ -0,0 +1,82 @@
+# PR Testing — Real side-panel Agent Runtime
+
+This round makes the real OpenAI-compatible Agent the only user-facing chat path.
+
+## Automated checks
+
+```bash
+pnpm typecheck
+pnpm test:agent-runtime
+pnpm build:extension
+```
+
+The following packages and surfaces must compile:
+
+- `@data-recipe/agent-runtime`
+- `@data-recipe/agent-tools-core`
+- `@data-recipe/skill-builder`
+- the Chrome side panel and its six tool handlers
+
+## Manual verification
+
+### Provider settings
+
+1. Open the side panel with no saved configuration.
+2. Confirm the chat input is disabled and asks the user to configure a model.
+3. Open “模型设置” and save `baseUrl`, `apiKey`, and a tool-capable `model`.
+4. Reopen the side panel and confirm the configuration was restored from `chrome.storage.local`.
+
+### Agent tool loop
+
+1. Open `docs/test-page.html` and click “开始学习页面”.
+2. Trigger a fetch or XHR request.
+3. Ask the Agent to create a data skill.
+4. Confirm the configured provider receives streaming `/v1/chat/completions` requests with messages and function tools.
+5. Confirm SSE text appears incrementally and incremental tool call arguments are aggregated before execution.
+6. Confirm returned `tool_calls` execute locally and collapsed tool results are sent back as `role: tool` messages with matching `tool_call_id`.
+7. Confirm the loop ends only when the model returns final assistant text or a protected termination generates a `tool_choice: none` summary.
+8. Confirm each call appears in the timeline immediately, updates in place on completion, and its result follows it in actual occurrence order.
+9. Confirm streamed Markdown headings, lists, tables, code blocks, quotes, and links refresh incrementally and unsafe HTML is removed.
+
+### Conversation recovery
+
+- Close and reopen the side panel after at least one tool result; history and recipe IDs should remain usable.
+- Simulate a Provider failure after a tool result; the partial history must remain in the next request.
+- Changing model settings must not clear history.
+- Clicking “新建对话” must create a new conversation ID and clear the active history.
+
+### Automated regressions
+
+- streaming text delta aggregation;
+- streaming `tool_calls` name/arguments aggregation;
+- explicit streaming rejection fallback;
+- partial recipe validation without undefined-property errors;
+- `runRecipe` requiring `recipeId`;
+- failed tool results present in the next model turn;
+- `AgentRunError.partialMessages` after a later Provider failure;
+- repeated identical failure termination;
+- max-iteration fault summary with history retained.
+- `AgentRunOutcome` fields and budget-pause continuation state;
+- multi-recipe weekly-report workflow and valid standalone ZIP structure.
+
+### Safety confirmations
+
+- `readCapture` and `inspectResponse` preview/page/range modes do not silently expand to full reads.
+- Full capture/response reads require a visible user confirmation.
+- Every `runRecipe` requires a visible user confirmation.
+- Every `exportSkillPackage` requires a visible user confirmation.
+- A recipe whose API URL is not present in current captures is rejected.
+- Cookie, Authorization, API key, password, secret, and token-shaped captured fields are redacted before model exposure.
+- Provider credentials are never included in tool inputs, tool results, recipes, or exported packages.
+
+### Skill package path
+
+- `buildDataSkillPackage` rejects empty Agent-authored `skillMarkdown`.
+- The side panel does not call the Mock development helper.
+- Export uses the `SKILL.md` supplied by the model to `exportSkillPackage`.
+- Formal export has MIME `application/zip` and contains `workflow.json` plus every referenced `recipes/*.json` file.
+- A weekly-report goal containing only “池佳 W25” resolves person/year/week dynamically, obtains `empCode`, `uid`, and `weekId` from prior step outputs, then reads detail and optional diff without hardcoded identities.
+
+## Known limitation
+
+Non-dry-run Browser RPC execution remains a typed placeholder and returns `blocked` until the real bridge transport is connected.
diff --git a/README.en.md b/README.en.md
@@ -4,8 +4,7 @@
 
 Operate once. Generate reusable data recipes for AI agents.
 
-DataRecipe turns web page queries, API responses, query parameters, pagination rules, and field meanings into reusable data recipes.
-Any AI agent can later use these recipes to collect, organize, and analyze data.
+DataRecipe is a browser-resident tool layer for AI agents. It turns authorized page queries, API responses, parameters, pagination rules, and field meanings into reusable recipes while letting the Agent decide what to read and how to build the final package.
 
 ## Why DataRecipe
 
@@ -129,10 +128,14 @@ data-recipe/
 ├── apps/
 │   └── extension/          # Browser sidebar extension
 ├── packages/
+│   ├── browser-rpc-core/   # Browser RPC Bridge protocol types
+│   ├── agent-runtime/      # OpenAI-compatible Agent Runtime
+│   ├── agent-tools-core/   # Agent-facing tool contracts
 │   ├── detector/           # API request detection
 │   ├── recipe-core/        # Core Data Recipe model
 │   ├── recipe-runner/      # Recipe runtime
-│   └── recipe-exporter/    # MCP / OpenAPI / JSON exporter
+│   ├── skill-builder/      # Data Skill Package generation
+│   └── skill-exporter/     # Data Skill Package export
 ├── docs/
 │   ├── vision.md
 │   ├── data-recipe-spec.md
@@ -145,3 +148,140 @@ data-recipe/
 ## License
 
 TBD
+
+## Run the MVP locally
+
+### Install dependencies
+
+```bash
+pnpm install
+```
+
+### Build the browser extension
+
+```bash
+pnpm build:extension
+```
+
+The extension output is:
+
+```text
+apps/extension/dist
+```
+
+### Load it in Chrome
+
+1. Open `chrome://extensions`;
+2. Enable Developer mode;
+3. Click "Load unpacked";
+4. Select `apps/extension/dist`;
+5. Click the "AI 有数" extension icon to open the side panel.
+
+### Manual verification
+
+1. Open `docs/test-page.html`;
+2. Click "开始学习页面" in the conversational side panel;
+3. Click the fetch or XHR test button on the test page;
+4. State a goal in natural language; the side-panel Agent should create a plan and call the local tools;
+5. Tool results remain collapsed, while "高级信息" contains data-source details and the recipe draft.
+
+The side panel is the primary workspace for ordinary users: conversation is the main UI, while sources, recipes, test output, and tool traces are secondary. Users first configure an OpenAI-compatible Provider (`baseUrl`, `apiKey`, and a tool-capable `model`). The side panel then runs a real Agent through `/v1/chat/completions`; future external Agents can reuse the same Agent Tool Layer.
+
+You can also start discovery on any page you are authorized to access and then trigger a page query. This MVP only performs low-frequency local detection. It does not bypass login, captchas, risk controls, or dynamic signatures.
+
+### Development mode
+
+```bash
+pnpm dev:extension
+```
+
+This watches and rebuilds `apps/extension/dist`. Refresh the unpacked extension in Chrome before testing updated code.
+
+### Export a Data Skill Package
+
+After one discovery flow, use the side panel to:
+
+1. Fill in the data skill name and purpose;
+2. Confirm or rename returned fields;
+3. Check "试运行结果" to confirm data can be read;
+4. Check "技能包预览" to confirm required files are present;
+5. Click "导出技能包".
+
+Production export downloads a real ZIP with MIME type `application/zip` and real paths:
+
+```text
+SKILL.md
+workflow.json
+recipes/
+  people-list.json
+  week-list.json
+  week-detail.json
+examples.md
+README.md
+```
+
+`.data-skill.json` remains available only as a development/import interchange format, not the primary user export.
+
+### Data Skill Package acceptance checks
+
+An exported package should at least:
+
+* Include `SKILL.md`, `workflow.json`, one or more `recipes/*.json`, `examples.md`, and `README.md`;
+* Use `SKILL.md` to explain what the data skill is useful for;
+* Use each recipe to hold its data source, query inputs, returned fields, and test-run information;
+* Use `workflow.json` to express list → filter → detail → optional diff dependencies, with one packaged recipe for every interface used;
+* Show a data preview in the side panel test-run result;
+* Show no missing required files before export.
+
+### Validate an exported skill package
+
+After exporting a ZIP, run:
+
+```bash
+pnpm validate:skill-package path/to/your-data-skill.zip
+```
+
+The command checks required files, the recipes directory, and workflow references. It exits with a non-zero status when the package is invalid.
+
+## Artifact Hierarchy
+
+* **The plugin provides tools:** `listCapturedSources`, `readCapture`, `inspectResponse`, `buildRecipe`, `runRecipe`, and `exportSkillPackage`. Read tools support preview, page, range, and explicit full modes.
+* **Streaming and recovery:** the Runtime aggregates SSE text/tool deltas, checkpoints every assistant/tool message, and stores conversations in `chrome.storage.session` by tab and conversation ID.
+* **A real conversation timeline:** user messages, AI messages, tool calls, tool results, statuses, outcomes, and ZIP artifacts are ordered `ConversationEvent`s. Markdown refreshes incrementally and is sanitized with DOMPurify.
+* **recipeId protocol:** complete recipes stay inside the plugin RecipeStore; the model patches, runs, and exports by `recipeId` instead of retransmitting full recipes.
+* **The Agent makes judgments:** it selects sources, decides how much to read, reviews and edits the recipe, and freely authors `SKILL.md` from tool evidence and the user's goal.
+* **The user authorizes and confirms:** browser-session access, origin permissions, recipe runs, and protected export actions remain user-controlled.
+* **Multi-recipe workflow:** rules and tools generate `recipes/*.json`; the Agent reviews them, while `workflow.json` defines cross-recipe dependencies. Production export is ZIP.
+* **Structured stopping:** `AgentRunOutcome` distinguishes completion, budget pause, tool failure, and user/safety blocking. Paused progress can be continued.
+* **Mock is not a production path:** the configured model must author `SKILL.md` in the user flow. Mock helpers are restricted to tests and development support.
+* **The final deliverable is a Data Skill Package:** Agent-authored `SKILL.md`, `workflow.json`, reviewed `recipes/`, examples, and documentation.
+
+## Long-term Runtime Architecture
+
+DataRecipe's long-term execution path is:
+
+```text
+User ↔ AI Agent → Agent-facing tools → Browser RPC Bridge → authorized Chrome session
+                    ↓
+             Data Skill Package
+```
+
+Meaning:
+
+* `AI Agent` is the controller: it plans tool calls, reads progressively, edits the recipe, and authors SKILL.md for the user goal;
+* `Agent-facing tools` expose capture discovery, bounded reads, response inspection, recipe build/run, and package export;
+* `Browser RPC Bridge` is the runtime behind `runRecipe`, forwarding only validated recipe runs to the extension;
+* `Chrome Extension` executes requests inside the user's authorized browser session;
+* `authorized browser session` means a page session the user has already logged into and is allowed to access.
+
+This architecture does not expose Cookie, Authorization header, or other sensitive credentials to AI agents, and it is not an arbitrary request proxy. The project will not implement bypasses for login, captchas, risk controls, dynamic signatures, or anti-bot systems.
+
+See [`docs/agent-tool-architecture.md`](./docs/agent-tool-architecture.md) and [`AGENTS.md`](./AGENTS.md) for the detailed responsibility, tool, and phase design.
+
+## Current MVP Status
+
+* Done: API detection / Agent tool contracts / OpenAI-compatible Agent Runtime / side-panel model settings / six local tool handlers.
+* Done: the Agent uses tool calls to read selectively, inspect/edit recipes, test runs, and author SKILL.md.
+* Done: `recipe-runner.runRecipeWithBrowserRpc` is defined, with its types wired to `BrowserRunRecipeResult` from `@data-recipe/browser-rpc-core`.
+* Not yet implemented: real browser RPC execution. The MVP only completes the wire protocol and the skill package draft; `runRecipeWithBrowserRpc` currently returns `blocked` until the bridge transport is connected in a follow-up PR.
+