page-harness 0.1.10 → 0.1.12

package/AGENTS.md

@@ -0,0 +1,43 @@
+# 给改这个仓库的代理
+
+用户文档在 [README.md](./README.md) 和 [README.zh-CN.md](./README.zh-CN.md)。目录、命令和开发约定在 [docs/development.md](./docs/development.md)。这里只写改代码时容易踩错的约束。
+
+## 先跑什么
+
+Node 20.11+。根目录 `npm ci` 之后：
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+```
+
+改了 `dsh-plugin/` 还要在该目录跑 `npm run check` 和 `npm test`。改了页面上能看见的行为，再 `npm run build && npm run test:e2e`。`dist/` 被 gitignore，不要提交构建产物。
+
+## 两个包，两条运行路径
+
+- 根包 `page-harness` 是 CLI。它代理用户的页面，注入 overlay，并用本机的 agent CLI 改源码。
+- `dsh-plugin/` 是 DeepSeek Harness 插件 `page-harness-dsh`。预览由 DSH 调 CLI，参数带 `--no-agent`。候选由 DSH 模型调用 `page_harness_propose`，不要在插件里启动 page-harness 自己的 agent，也不要把几版同时写进源码。
+
+插件装进 DSH profile 后是文件副本，不是源码目录的符号链接。改 `dsh-plugin/lib/` 不会自动出现在正在跑的 DSH 里。
+
+## 不要改的行为
+
+- 预览端口保持独立。DSH 用自己的端口（常见 3080）。页面预览默认 `17994`，面板和 `/__ph/ws` 用下一个端口。不要把这两个端口反代进 3080，也不要加路径前缀。
+- 回环或 HTTPS 上的面板 cookie 是 `SameSite=None; Secure; Partitioned`。公网 HTTP 保持 `SameSite=Strict`。无 cookie 的 WebSocket 必须继续 403。
+- `POST /__ph/api/review/resolve` 只给本机 curl / 复制出的提示词。带 `Origin`、跨站 `Sec-Fetch-Site` 或面板 session cookie 的请求返回 403。面板改意见走 WebSocket，不走这个地址。
+- DSH 里采用某一版时，输入框里的 `<page-element>` 不带内部 HTML。选择器、标签和文本放在属性上，具体改动写在后面的句子里。
+
+## 插件客户端
+
+`dsh-plugin/lib/client.js` 是一个没有 import 的浏览器脚本。和它对应的纯函数在 `propose.js`、`preview-bar.js`、`share-bar.js`。改其中一份时，另一份必须保持函数体一致；`dsh-plugin/test/` 会比对。`npm test` 不会执行 `client.js`，所以还要过 `npm run check`。
+
+## 提交
+
+功能 PR 不要改 `package.json` 的 `version`。提交说明用英文祈使句，说明为什么改。没有明确要求就不要 push，也不要开新的发布 tag。
+
+## 发版
+
+只发布根包 `page-harness`。tag 必须是 `v` 加 `package.json` 里的版本，例如 `v0.1.12`。不要给 `page-harness-dsh` 单独发版，也不要改它的版本号。
+
+DSH 直接安装 npm 上的 `page-harness@<该版本>`。插件源码留在 `dsh-plugin/`，运行时用这个 CLI 包。以后每次发版都这样。

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/logo.svg" width="72" alt="page-harness logo">
+  <img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/logo.svg" width="72" alt="page-harness logo">
 </p>
 
 <h1 align="center">page-harness</h1>
@@ -24,19 +24,13 @@
   <a href="#development">Development</a>
 </p>
 
-<p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/hero.webp" width="720" alt="page-harness">
-</p>
-
-<p align="center">
-  <video src="https://cdn.jsdelivr.net/npm/page-harness@0.1.8/docs/hero.mp4" width="720" controls playsinline></video>
-</p>
+https://github.com/user-attachments/assets/113f12e7-c287-45d2-9f27-cb9158c539b2
 
 ## Overview
 
 **Turn any running web page into a workspace for your coding agent.**
 
-Click the thing you want changed and tell your agent what to do, right on the page: Pick, Chat and Artifacts, driven by the agent CLI already on your machine (Claude Code, Codex, Cursor Agent, CodeBuddy Code, OpenCode). For feedback only, `--no-agent` keeps just Pick and Notes; run it with no URL and you get a home page with a **✦ Page-Harness** bookmarklet that works on any site.
+Start with one command—no project config changes, no extra accounts or API keys. Click the element you want changed on the live page to talk to your agent (Pick, Chat, Live candidates, and Artifacts), edit text and styles inline with a live preview, or pass `--share` so teammates can leave notes and approvals on the same page in real time. Behind the scenes it drives the agent CLI already on your machine (Claude Code, Codex, Cursor Agent, CodeBuddy Code, OpenCode), or embeds directly into the right pane of [DeepSeek Harness](./dsh-plugin/README.md). For feedback only, `--no-agent` keeps just Pick and Notes; run it with no URL and you get a home page with a **✦ Page-Harness** bookmarklet that works on any site.
 
 Describing UI in a terminal is painful: "the second button in the card on the left, make it a bit softer". With page-harness you just click the thing on the page and talk to your agent right there. It writes the code, your dev server reloads, you see the result on the same page.
 
@@ -46,6 +40,7 @@ One line. Point it at your dev server:
 
 ```bash
 npx page-harness http://localhost:5173 --project ./my-app
+npx page-harness http://localhost:5173 --share      # team review: invite link for teammates
 npx page-harness --no-agent http://localhost:5173   # review only: Pick and Notes, no agent CLI
 npx page-harness                                    # no URL: home page with a bookmarklet
 ```
@@ -56,60 +51,61 @@ Open **http://127.0.0.1:17990**. That is your app as usual, plus a dock in the b
 - The target can be a bare port (`3000`), `host:port` or a full URL. HMR (Vite, webpack, Next.js…) keeps working through the proxy.
 - No sandbox, no accounts, no changes to your app. Everything stays in `<project>/.page-harness/`.
 
-| Service | URL |
-|---|---|
-| Your app + dock | `http://127.0.0.1:17990` |
-| Panel / API (control port) | `http://127.0.0.1:17991` |
-| Chat history | `http://127.0.0.1:17991/__ph/history` |
-| Bookmarklet home (no URL) | `http://127.0.0.1:17991` |
-
 ### Other ways to run
 
 | Option | When to use it |
 |---|---|
-| `npx page-harness <url>` | The standard setup above: your app behind the proxy, with Pick, Chat and Artifacts driven by an agent CLI |
-| `--no-agent <url>` | Feedback only: Pick and Notes, no agent CLI needed ([details](#review-only---no-agent)) |
+| `npx page-harness <url>` | The standard setup above: your app behind the proxy, with Pick, Chat, Live candidates and Artifacts driven by an agent CLI |
+| `--share` | Teammates on your network join as reviewers with a link, leave notes, edit inline and approve ([details](#team-review---share)) |
+| `--no-agent <url>` | Feedback & inline edits only: Pick and Notes, no agent CLI needed ([details](#review-only---no-agent)) |
 | no URL | A home page with the **✦ Page-Harness** bookmarklet, to leave notes on any site without a proxy ([details](#bookmarklet-no-url)) |
-| `--share` | Teammates on your network join as reviewers with a link ([details](#team-review---share)) |
+| `dsh plugin --profile web add page-harness-dsh` | Embed the running page in the right pane of DeepSeek Harness, pick elements into chat, and share with teammates ([details](./dsh-plugin/README.md)) |
 
 ## Product tour
 
-### Review only
+### DeepSeek Harness right-pane preview
 
-**Pick and Notes, nothing else.** With `--no-agent` no agent CLI is started. Pick an element, leave a comment or an edit, reply, resolve and approve per page. [Details →](#review-only---no-agent)
+**Preview beside your chat.** With [`page-harness-dsh`](./dsh-plugin/README.md), the page opens in a resizable right pane inside DeepSeek Harness: pick elements straight into the prompt box, leave notes on the page, and share the preview with teammates.
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/review-only.png" width="720" alt="Page notes panel in review-only mode"></p>
+<p align="center"><img src="./docs/dsh-preview-light.png" width="720" alt="DeepSeek Harness right-pane preview"></p>
+
+### Review only & inline editing
+
+**Pick, edit inline, and leave notes.** With `--no-agent` no agent CLI is started. Pick an element, leave a comment or edit its text and styles in place with a live preview, reply, resolve and approve per page. [Details →](#review-only---no-agent)
+
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/review-only.png" width="720" alt="Page notes panel in review-only mode"></p>
 
 ### Bookmarklet home
 
 **One button to drag.** Run `npx page-harness` with no URL and the home page has a single **✦ Page-Harness** button. Drag it to the bookmarks bar. [Details →](#bookmarklet-no-url)
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/home.png" width="520" alt="Home page with the ✦ Page-Harness button"></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/home.png" width="520" alt="Home page with the ✦ Page-Harness button"></p>
 
 ### Notes on any site
 
 **Click the bookmark on any page.** The dock is injected into that page in a Shadow DOM, with no proxy, and notes are saved to your local server, grouped by site.
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/bookmarklet.png" width="720" alt="Bookmarklet dock on a plain page"></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/bookmarklet.png" width="720" alt="Bookmarklet dock on a plain page"></p>
 
 ### My notes
 
 **Every site's notes in one place.** Sites on the left, that site's notes on the right, with Export Markdown, Export JSON and Copy prompt for your agent.
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/home-notes.png" width="720" alt="My notes view"></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/home-notes.png" width="720" alt="My notes view"></p>
 
 ## How it works
 
 ```text
-browser ──► :17990  app port      reverse proxy to your dev server; injects /__ph/overlay.js into HTML
-        └─► :17991  control port  panel UI, history page, JSON API, WebSocket, MCP endpoint
-                       │
-                       └─ spawns the agent CLI per turn (claude -p / codex app-server / cursor-agent -p /
-                          codebuddy -p / opencode run --format json)
-                          with a local MCP server for page_*, artifacts, questions and Live
+Running web page ──► In-page dock (Pick / Inline edit / Notes / Chat / Artifacts)
+                          │
+                          ▼
+             Local coding agent CLI (Claude Code / Codex / Cursor / CodeBuddy / OpenCode)
+                          │
+                          ▼
+             Edits source or renders Live variants ──► Instant HMR preview & team review
 ```
 
-- The overlay lives in a Shadow DOM so its styles and your app's styles do not leak into each other. The chat and artifacts windows are iframes from the control port and talk to the page over a `MessagePort` handshake.
+- The overlay lives in a Shadow DOM so its styles and your app's styles do not leak into each other.
 - Each chat keeps the agent's session id, so follow-up messages resume the same agent session. Messages sent while a turn runs are queued per chat.
 - Agents get a short system prompt describing the page context, the MCP tools and the Live protocol. Nothing is written to your project except `.page-harness/` (ignored by git through its own `.gitignore`) and, during Live, temporary candidate markup.
 
@@ -170,6 +166,8 @@ npx page-harness https://example.com --share
 
 Send the Share link (also in Settings → Team) to teammates on the same network. Opening it gives them a reviewer session for that browser; they enter a display name once and then see the page with everyone's notes and changes in real time. Reviewers can comment, edit (review mode), reply, resolve and approve. They cannot run or see the agent, chats, history, uploads or page control. Other machines without the link get `403`.
 
+Teammates need both ports: the app port and the control port. On a cloud machine, open both ports and pass `--public-host <public IP or domain>` so the invite link points there. To start a share preview from DeepSeek Harness, see [`dsh-plugin/`](./dsh-plugin/README.md).
+
 ## Features
 
 | Area | Highlights |
@@ -231,6 +229,9 @@ page-harness [frontend-url] [options]
                          The dock is Pick and Notes. Implied when no URL is given.
   --lang <zh|en>         Home page and dock language. Omit it and each browser keeps its own.
   --share                Let teammates on your network join as reviewers (listens on 0.0.0.0)
+  --public-host <name>   Hostname or IP teammates use; goes into the invite link and the Host allow-list
+  --json                 Print one JSON line with the URLs to stdout once listening
+  --embed-origin <origin>  Let this origin frame the page and panels; Pick quotes are posted to it (repeatable)
   --verbose / --quiet
 ```
 
@@ -272,7 +273,7 @@ There is no login: it is a local developer tool and binds to `127.0.0.1` by defa
 - **Two origins.** Your app (and any script on it) runs on the app port; the panel, API and agent endpoints are on the control port, so page scripts cannot read them.
 - **Owner and reviewers.** Without `--share` only this machine can connect and everything behaves as one user. With `--share`, the owner session is only issued to loopback requests; other machines need the invite link, which sets signed (HMAC) reviewer cookies for the panel and the app port; without them both ports answer `403`. Reviewers are limited to the review actions on the WebSocket and to reading artifacts; everything else returns `403`. Name the owner in Settings → Team.
 - **Session cookie.** The panel gets an `HttpOnly`, `SameSite=Strict` cookie scoped to `/__ph`; the cookie is stripped before requests are forwarded to your dev server.
-- **API.** Reads require a same-origin `Sec-Fetch-Site`; writes require a matching `Origin` plus a custom `X-PH` header. The WebSocket checks the cookie and `Origin`. The bookmarklet is the exception: cross-origin review reads and writes need the per-run `X-PH-Token`, and the response reflects that page's `Origin` (never `*`). `GET /__ph/api/review` stays callable from curl without CORS headers.
+- **API.** Reads require a same-origin `Sec-Fetch-Site`; writes require a matching `Origin` plus a custom `X-PH` header. The WebSocket checks the cookie and `Origin`. The bookmarklet is the exception: cross-origin review reads and writes need the per-run `X-PH-Token`, and the response reflects that page's `Origin` (never `*`). `GET /__ph/api/review` stays callable from curl without CORS headers. `POST /__ph/api/review/resolve` is the local agent's endpoint, so it takes no cookie and no token: it accepts only requests without an `Origin` (curl, the copied prompt), and refuses browsers, cross-site requests and session cookies with `403`.
 - **MCP.** Every agent turn gets its own bearer token (passed through an environment variable or a private temp file, never on the command line) that is revoked when the turn ends. Browser requests to the MCP endpoint are rejected.
 - **Host allow-list.** Requests with unexpected `Host` headers get `421` (DNS rebinding). Add names with `--allow-host` if you expose it on a LAN.
 - **Framing.** The panel may only be framed by the app origin; the history page cannot be framed at all.
@@ -327,10 +328,14 @@ Delete `<project>/.page-harness/`.
 | [Security model](#security-model) | What is locked down and how |
 | [Data](#data) | What is stored in `.page-harness/` |
 | [FAQ](#faq) | Common questions |
+| [Development](./docs/development.md) | Repository map, commands, and conventions |
+| [Homepage](https://cocofhu.github.io/page-harness-site/) | Product tour and install |
 | [npm package](https://www.npmjs.com/package/page-harness) | Released versions |
 
 ## Development
 
+Contributor guide: [docs/development.md](./docs/development.md). Agent notes: [AGENTS.md](./AGENTS.md).
+
 ```bash
 npm install
 npm run dev            # rebuild client bundles and the CLI on change
@@ -338,13 +343,11 @@ node dist/cli.js http://localhost:5173 --project ../some-app
 
 npm run lint
 npm run typecheck
-npm test               # unit + server integration tests (scripted agent)
+npm test               # unit + server integration tests
 npx playwright install chromium
 npm run build && npm run test:e2e   # browser tests against a fixture app
 ```
 
-`PH_FAKE_AGENT=1` adds a scripted `fake` agent used by the tests; it drives the real MCP endpoint, so the whole pipeline is exercised without an LLM.
-
 ## Contributing
 
 Issues and pull requests are welcome at [Tencent/page-harness](https://github.com/Tencent/page-harness).

package/README.zh-CN.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/logo.svg" width="72" alt="page-harness logo">
+  <img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/logo.svg" width="72" alt="page-harness logo">
 </p>
 
 <h1 align="center">page-harness</h1>
@@ -24,19 +24,13 @@
   <a href="#开发">开发</a>
 </p>
 
-<p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/hero-zh.webp" width="720" alt="page-harness">
-</p>
-
-<p align="center">
-  <video src="https://cdn.jsdelivr.net/npm/page-harness@0.1.8/docs/hero-zh.mp4" width="720" controls playsinline></video>
-</p>
+https://github.com/user-attachments/assets/7fe5d123-58e2-4aa2-a5e3-f7fe9eae51b7
 
 ## 概览
 
 **把正在跑的网页，直接变成编码 Agent 的工作台。**
 
-在页面上点一下要改的地方，就能跟 Agent 说怎么改：取点、聊天、看产物，背后用的就是你电脑上已经装好的 Agent CLI（Claude Code、Codex、Cursor Agent、CodeBuddy Code、OpenCode）。只想收集意见的话，`--no-agent` 只留取点和意见；不给地址直接跑，会打开一个书签主页，把 **✦ Page-Harness** 拖到书签栏，任何网页都能标。
+一行命令启动，不用改项目配置，也不用额外注册账号或填 API Key。直接在页面上点选要改的元素就能跟 Agent 对话（取点、聊天、Live 多套候选方案、看产物），或者原地在线修改文字与样式实时预览；加个 `--share` 还能生成分享链接，拉上产品、设计与测试同事在同一个页面上实时批注和审批。背后直接驱动你电脑上已经装好的 Agent CLI（Claude Code、Codex、Cursor Agent、CodeBuddy Code、OpenCode），也可以装进 [DeepSeek Harness](./dsh-plugin/README.md) 在对话右栏直接预览。只想收集意见的话，`--no-agent` 只留取点和意见；不给地址直接跑，会打开一个书签主页，把 **✦ Page-Harness** 拖到书签栏，任何网页都能标。
 
 在终端里描述界面挺折磨人的：“左边卡片里第二个按钮，颜色再柔和一点”。我就想直接在页面上点一下，跟 Agent 说改成什么样。它改代码，dev server 刷新，结果就在同一个页面上看。page-harness 干的就是这件事。
 
@@ -46,7 +40,8 @@
 
 ```bash
 npx page-harness http://localhost:5173 --project ./my-app
-npx page-harness --no-agent http://localhost:5173   # 只评审：取点 + 意见，不启动 Agent CLI
+npx page-harness http://localhost:5173 --share      # 团队评审：生成分享链接让同事一起看
+npx page-harness --no-agent http://localhost:5173   # 只评审：取点 + 在线编辑 + 意见，不启动 Agent CLI
 npx page-harness                                    # 不给地址：打开书签主页
 ```
 
@@ -56,60 +51,61 @@ npx page-harness                                    # 不给地址：打开书
 - 地址可以只写端口（`3000`）、`host:port` 或完整 URL。Vite、webpack、Next.js 这些的热更新照常能用，WebSocket 也代理过去了。
 - 不要沙箱，不要注册账号，也不碰你的项目代码。数据都放在 `<project>/.page-harness/` 里。
 
-| 服务 | 地址 |
-|---|---|
-| 你的应用 + 底栏 | `http://127.0.0.1:17990` |
-| 面板 / API（控制端口） | `http://127.0.0.1:17991` |
-| 对话历史 | `http://127.0.0.1:17991/__ph/history` |
-| 书签主页（不给地址时） | `http://127.0.0.1:17991` |
-
 ### 其他跑法
 
 | 方式 | 什么时候用 |
 |---|---|
-| `npx page-harness <地址>` | 上面这种标准用法：应用走代理，取点、对话、产物都由 Agent CLI 驱动 |
-| `--no-agent <地址>` | 只收意见：取点 + 意见，不需要 Agent CLI（[详细](#仅评审--no-agent)） |
+| `npx page-harness <地址>` | 上面这种标准用法：应用走代理，取点、对话、Live 候选、产物都由 Agent CLI 驱动 |
+| `--share` | 同一网络的同事拿链接进来当评审，实时留意见、在线改样式、按页审批（[详细](#团队评审--share)） |
+| `--no-agent <地址>` | 只收意见与在线改样式：取点 + 意见，不需要 Agent CLI（[详细](#仅评审--no-agent)） |
 | 不给地址 | 打开带 **✦ Page-Harness** 书签的主页，不走代理也能在任意网站上留意见（[详细](#书签不给地址)） |
-| `--share` | 同一网络的同事拿链接进来当评审（[详细](#团队评审--share)） |
+| `dsh plugin --profile web add page-harness-dsh` | 在 DeepSeek Harness 对话右侧直接预览页面、取点引用回填输入框、一键分享给同事（[详细](./dsh-plugin/README.md)） |
 
 ## 上手看看
 
-### 仅评审
+### DeepSeek Harness 右栏预览
 
-**只有取点和意见。** 加 `--no-agent` 就不启动 Agent CLI。点元素留评论或者直接改，回复、解决、按页面审批都行。[详细 →](#仅评审--no-agent)
+**边聊边看。** 装上 [`page-harness-dsh`](./dsh-plugin/README.md) 后，页面直接嵌在 DeepSeek Harness 对话右侧：点元素一键引用到输入框，在页面上留批注后说一句「按意见改」，还能一键分享给同事评审。
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/review-only-zh.png" width="720" alt="仅评审模式下的页面意见面板"></p>
+<p align="center"><img src="./docs/dsh-preview-light.png" width="720" alt="DeepSeek Harness 对话右侧预览页面"></p>
+
+### 仅评审与在线编辑
+
+**取点、在线改样式、留意见。** 加 `--no-agent` 就不启动 Agent CLI。点元素留评论或者原地修改文字、颜色、字号、圆角实时预览，回复、解决、按页面审批都行。[详细 →](#仅评审--no-agent)
+
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/review-only-zh.png" width="720" alt="仅评审模式下的页面意见面板"></p>
 
 ### 书签主页
 
 **就一个按钮，拖走就行。** 不给地址直接跑 `npx page-harness`，主页上只有一个 **✦ Page-Harness** 按钮，拖到书签栏。[详细 →](#书签不给地址)
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/home-zh.png" width="520" alt="主页上的 ✦ Page-Harness 按钮"></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/home-zh.png" width="520" alt="主页上的 ✦ Page-Harness 按钮"></p>
 
 ### 任意网站留意见
 
 **打开哪个网页都能点。** 底栏直接注入到当前页面（放在 Shadow DOM 里，不走代理），意见存到本机服务，按网站分好。
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/bookmarklet-zh.png" width="720" alt="书签注入到普通页面上的底栏"></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/bookmarklet-zh.png" width="720" alt="书签注入到普通页面上的底栏"></p>
 
 ### 我的标记
 
 **所有网站的意见都在这。** 左边网站，右边这个网站的意见，可以导出 Markdown、导出 JSON，或者复制 Prompt 丢给 Agent。
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.6/docs/home-notes-zh.png" width="720" alt="我的标记页"></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/page-harness@0.1.10/docs/home-notes-zh.png" width="720" alt="我的标记页"></p>
 
 ## 原理
 
 ```text
-浏览器 ──► :17990  应用端口  反向代理到你的开发服务器，在 HTML 里注入 /__ph/overlay.js
-       └─► :17991  控制端口  面板 UI、聊天记录页、JSON API、WebSocket、MCP
-                      │
-                      └─ 每一轮对话启动一次 Agent CLI（claude -p / codex app-server / cursor-agent -p /
-                        codebuddy -p / opencode run --format json），
-                         并接入本地 MCP：page_*、产物、提问、Live
+正在运行的网页 ──► 页面悬浮底栏（取点 / 在线编辑 / 团队意见 / 对话 / 产物）
+                        │
+                        ▼
+               连接本机 Agent CLI（Claude Code / Codex / Cursor / CodeBuddy / OpenCode）
+                        │
+                        ▼
+               修改源码或生成多套候选方案 ──► 页面实时热更新预览 & 团队评审闭环
 ```
 
-- 底栏在 Shadow DOM 里，和你的样式互不影响。对话窗、产物窗是来自控制端口的 iframe，通过 `MessagePort` 握手和页面通信。
+- 底栏在 Shadow DOM 里，和你的样式互不影响。
 - 每个会话记住 Agent 的 session id，后续消息续接同一个 Agent 会话；一轮还在跑时发的消息进入该会话的队列。
 - Agent 会收到一段简短的系统提示，说明页面上下文、MCP 工具和 Live 协议。除了 `.page-harness/`（自带 `.gitignore`）和 Live 期间的临时候选标记外，不会往你的项目里写东西。
 
@@ -170,6 +166,8 @@ npx page-harness https://example.com --share
 
 把 Share 链接（设置 → 团队里也有）发给同一网络的同事。打开后这个浏览器获得评审者身份，填一次显示名，就能实时看到页面上所有人的意见和修改。评审者可以评论、编辑（评审模式）、回复、解决、审批；不能使用或看到 Agent、对话、聊天记录、上传和页面控制。没有链接的其他机器一律 `403`。
 
+同事需要能访问两个端口：应用端口和控制端口。在云主机上，放行这两个端口，并加 `--public-host <公网 IP 或域名>`，邀请链接就会指向它。想在 DeepSeek Harness 里一键启动分享预览，见 [`dsh-plugin/`](./dsh-plugin/README.md)。
+
 ## 功能
 
 | 模块 | 亮点 |
@@ -231,6 +229,9 @@ page-harness [前端地址] [选项]
                          不给前端地址时默认就是这个模式。
   --lang <zh|en>         主页和底栏的语言。不写时，每个浏览器沿用自己的选择。
   --share                允许同一网络的同事以评审者身份加入（监听 0.0.0.0）
+  --public-host <name>   同事访问用的主机名或 IP，写进邀请链接并加入 Host 白名单
+  --json                 监听成功后往 stdout 打一行包含各地址的 JSON
+  --embed-origin <origin>  允许这个源用 iframe 嵌入页面和面板，取点引用会 postMessage 给它（可重复）
   --verbose / --quiet
 ```
 
@@ -272,7 +273,7 @@ GET http://127.0.0.1:17991/__ph/api/review?scope=all&path=%2F&page=1&pageSize=20
 - **两个源。** 你的应用（以及其中任何脚本）在应用端口；面板、API、Agent 接口在控制端口，页面脚本读不到。
 - **所有者与评审者。** 不加 `--share` 时只有本机能连，一切按单用户处理。加了 `--share` 后，所有者会话只发给本机回环请求；其他机器必须通过邀请链接拿到带 HMAC 签名的评审者 Cookie（面板和应用端口各一个），没有就两个端口都返回 `403`。评审者在 WebSocket 上只能做评审操作，API 只能读产物，其余一律 `403`。所有者名字在设置 → 团队里修改。
 - **会话 Cookie。** 面板拿到 `HttpOnly`、`SameSite=Strict`、作用于 `/__ph` 的 Cookie；转发到你的开发服务器前会去掉它。
-- **API。** 读请求要求同源的 `Sec-Fetch-Site`；写请求要求匹配的 `Origin` 加自定义 `X-PH` 头。WebSocket 校验 Cookie 和 `Origin`。书签是例外：跨源读写意见必须带本次运行的 `X-PH-Token`，响应会反射该页面的 `Origin`（不会是 `*`）。`GET /__ph/api/review` 仍给 curl 用，不带 CORS 头。
+- **API。** 读请求要求同源的 `Sec-Fetch-Site`；写请求要求匹配的 `Origin` 加自定义 `X-PH` 头。WebSocket 校验 Cookie 和 `Origin`。书签是例外：跨源读写意见必须带本次运行的 `X-PH-Token`，响应会反射该页面的 `Origin`（不会是 `*`）。`GET /__ph/api/review` 仍给 curl 用，不带 CORS 头。`POST /__ph/api/review/resolve` 是本机 Agent 的接口，既不带 Cookie 也不带令牌：只接受不带 `Origin` 的请求（curl、复制出的提示词），浏览器、跨站请求和会话 Cookie 一律返回 `403`。
 - **MCP。** 每一轮 Agent 调用都发一个独立的 Bearer token（通过环境变量或私有临时文件传递，不出现在命令行），回合结束即作废。来自浏览器的 MCP 请求一律拒绝。
 - **Host 白名单。** `Host` 头不符的请求返回 `421`（防 DNS rebinding）。在局域网使用时用 `--allow-host` 添加。
 - **嵌入限制。** 面板只允许被应用源嵌入；聊天记录页不允许被任何页面嵌入。
@@ -327,10 +328,14 @@ team.json                   邀请 token、签名密钥和评审者名字（权
 | [安全模型](#安全模型) | 哪些地方锁住了，怎么锁的 |
 | [数据](#数据) | `.page-harness/` 里存了什么 |
 | [常见问题](#常见问题) | 大家常问的 |
+| [开发说明](./docs/development.md) | 仓库地图、命令和开发约定 |
+| [官网](https://cocofhu.github.io/page-harness-site/) | 产品演示与安装 |
 | [npm 包](https://www.npmjs.com/package/page-harness) | 已发布的版本 |
 
 ## 开发
 
+贡献说明见 [docs/development.md](./docs/development.md)，改代码时的约束见 [AGENTS.md](./AGENTS.md)。
+
 ```bash
 npm install
 npm run dev            # 监听并重建前端脚本与 CLI
@@ -338,13 +343,11 @@ node dist/cli.js http://localhost:5173 --project ../some-app
 
 npm run lint
 npm run typecheck
-npm test               # 单元测试 + 服务端集成测试（脚本化 Agent）
+npm test               # 单元测试 + 服务端集成测试
 npx playwright install chromium
 npm run build && npm run test:e2e   # 基于示例应用的浏览器测试
 ```
 
-设置 `PH_FAKE_AGENT=1` 会多出一个脚本化的 `fake` Agent，测试用它走真实的 MCP 接口，不需要大模型就能覆盖整条链路。
-
 ## 参与贡献
 
 欢迎到 [Tencent/page-harness](https://github.com/Tencent/page-harness) 提 Issue 和 PR。