npm - page-harness - Versions diffs - 0.1.10 → 0.1.11 - Mend

page-harness 0.1.10 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +35 -35
package/README.zh-CN.md +36 -36
package/dist/cli.js +145 -20
package/dist/cli.js.map +1 -1
package/dist/client/page/overlay.js +16 -16
package/docs/dsh-preview-light.png +0 -0
package/package.json +2 -1

package/README.md CHANGED Viewed

@@ -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
+**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="./docs/dsh-preview-light.png" width="720" alt="DeepSeek Harness right-pane preview"></p>
-**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)
+### Review only & inline editing
-<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>
+**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
 ```
@@ -327,6 +328,7 @@ 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 |
+| [Homepage](https://cocofhu.github.io/page-harness-site/) | Product tour and install |
 | [npm package](https://www.npmjs.com/package/page-harness) | Released versions |
 ## Development
@@ -338,13 +340,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 CHANGED Viewed

@@ -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 右栏预览
+**边聊边看。** 装上 [`page-harness-dsh`](./dsh-plugin/README.md) 后，页面直接嵌在 DeepSeek Harness 对话右侧：点元素一键引用到输入框，在页面上留批注后说一句「按意见改」，还能一键分享给同事评审。
+<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.6/docs/review-only-zh.png" width="720" alt="仅评审模式下的页面意见面板"></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
 ```
@@ -327,6 +328,7 @@ team.json                   邀请 token、签名密钥和评审者名字（权
 | [安全模型](#安全模型) | 哪些地方锁住了，怎么锁的 |
 | [数据](#数据) | `.page-harness/` 里存了什么 |
 | [常见问题](#常见问题) | 大家常问的 |
+| [官网](https://cocofhu.github.io/page-harness-site/) | 产品演示与安装 |
 | [npm 包](https://www.npmjs.com/package/page-harness) | 已发布的版本 |
 ## 开发
@@ -338,13 +340,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。