@xopcai/xopc 0.0.29 → 0.0.31

package/skills/tools/internal-comms/SKILL-zh.md

@@ -0,0 +1,32 @@
+---
+name: internal-comms
+description: 一套帮助我编写各类内部沟通文档的资源，使用公司偏好的格式。当被要求编写任何形式的内部沟通文档（状态报告、领导层汇报、3P 更新、公司通讯、FAQ、事件报告、项目更新等）时，Claude 应使用本技能。
+license: 完整条款见 LICENSE.txt
+---
+
+## 何时使用本技能
+编写内部沟通文档时，使用本技能处理：
+- 3P 更新（进展、计划、问题）
+- 公司通讯
+- FAQ 回复
+- 状态报告
+- 领导层汇报
+- 项目更新
+- 事件报告
+
+## 如何使用本技能
+
+编写任何内部沟通文档：
+
+1. **根据请求识别沟通类型**
+2. **从 `examples/` 目录加载对应的指南文件**：
+    - `examples/3p-updates.md` - 进展/计划/问题团队更新
+    - `examples/company-newsletter.md` - 公司全员通讯
+    - `examples/faq-answers.md` - 解答常见问题
+    - `examples/general-comms.md` - 其他不明确匹配上述类型的沟通
+3. **遵循该文件中的具体说明**，包括格式、语气和内容收集方式
+
+如果沟通类型与任何现有指南都不匹配，请求用户澄清或提供关于目标格式的更多背景信息。
+
+## 关键词
+3P 更新、公司通讯、公司内部沟通、周报、FAQ、常见问题、更新、内部沟通

package/skills/tools/internal-comms/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: internal-comms
+description: A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).
+license: Complete terms in LICENSE.txt
+---
+
+## When to use this skill
+To write internal communications, use this skill for:
+- 3P updates (Progress, Plans, Problems)
+- Company newsletters
+- FAQ responses
+- Status reports
+- Leadership updates
+- Project updates
+- Incident reports
+
+## How to use this skill
+
+To write any internal communication:
+
+1. **Identify the communication type** from the request
+2. **Load the appropriate guideline file** from the `examples/` directory:
+    - `examples/3p-updates.md` - For Progress/Plans/Problems team updates
+    - `examples/company-newsletter.md` - For company-wide newsletters
+    - `examples/faq-answers.md` - For answering frequently asked questions
+    - `examples/general-comms.md` - For anything else that doesn't explicitly match one of the above
+3. **Follow the specific instructions** in that file for formatting, tone, and content gathering
+
+If the communication type doesn't match any existing guideline, ask for clarification or more context about the desired format.
+
+## Keywords
+3P updates, company newsletter, company comms, weekly update, faqs, common questions, updates, internal comms

package/skills/tools/internal-comms/examples/3p-updates.md

@@ -0,0 +1,47 @@
+## Instructions
+You are being asked to write a 3P update. 3P updates stand for "Progress, Plans, Problems." The main audience is for executives, leadership, other teammates, etc. They're meant to be very succinct and to-the-point: think something you can read in 30-60sec or less. They're also for people with some, but not a lot of context on what the team does.
+
+3Ps can cover a team of any size, ranging all the way up to the entire company. The bigger the team, the less granular the tasks should be. For example, "mobile team" might have "shipped feature" or "fixed bugs," whereas the company might have really meaty 3Ps, like "hired 20 new people" or "closed 10 new deals." 
+
+They represent the work of the team across a time period, almost always one week. They include three sections:
+1) Progress: what the team has accomplished over the next time period. Focus mainly on things shipped, milestones achieved, tasks created, etc.
+2) Plans: what the team plans to do over the next time period. Focus on what things are top-of-mind, really high priority, etc. for the team.
+3) Problems: anything that is slowing the team down. This could be things like too few people, bugs or blockers that are preventing the team from moving forward, some deal that fell through, etc.
+
+Before writing them, make sure that you know the team name. If it's not specified, you can ask explicitly what the team name you're writing for is.
+
+
+## Tools Available
+Whenever possible, try to pull from available sources to get the information you need:
+- Slack: posts from team members with their updates - ideally look for posts in large channels with lots of reactions
+- Google Drive: docs written from critical team members with lots of views
+- Email: emails with lots of responses of lots of content that seems relevant
+- Calendar: non-recurring meetings that have a lot of importance, like product reviews, etc.
+
+
+Try to gather as much context as you can, focusing on the things that covered the time period you're writing for:
+- Progress: anything between a week ago and today
+- Plans: anything from today to the next week
+- Problems: anything between a week ago and today
+
+
+If you don't have access, you can ask the user for things they want to cover. They might also include these things to you directly, in which case you're mostly just formatting for this particular format.
+
+## Workflow
+
+1. **Clarify scope**: Confirm the team name and time period (usually past week for Progress/Problems, next
+week for Plans)
+2. **Gather information**: Use available tools or ask the user directly
+3. **Draft the update**: Follow the strict formatting guidelines
+4. **Review**: Ensure it's concise (30-60 seconds to read) and data-driven
+
+## Formatting
+
+The format is always the same, very strict formatting. Never use any formatting other than this. Pick an emoji that is fun and captures the vibe of the team and update.
+
+[pick an emoji] [Team Name] (Dates Covered, usually a week)
+Progress: [1-3 sentences of content]
+Plans: [1-3 sentences of content]
+Problems: [1-3 sentences of content]
+
+Each section should be no more than 1-3 sentences: clear, to the point. It should be data-driven, and generally include metrics where possible. The tone should be very matter-of-fact, not super prose-heavy.

package/skills/tools/internal-comms/examples/company-newsletter.md

@@ -0,0 +1,65 @@
+## Instructions
+You are being asked to write a company-wide newsletter update. You are meant to summarize the past week/month of a company in the form of a newsletter that the entire company will read. It should be maybe ~20-25 bullet points long. It will be sent via Slack and email, so make it consumable for that.
+
+Ideally it includes the following attributes:
+- Lots of links: pulling documents from Google Drive that are very relevant, linking to prominent Slack messages in announce channels and from executives, perhgaps referencing emails that went company-wide, highlighting significant things that have happened in the company.
+- Short and to-the-point: each bullet should probably be no longer than ~1-2 sentences
+- Use the "we" tense, as you are part of the company. Many of the bullets should say "we did this" or "we did that"
+
+## Tools to use
+If you have access to the following tools, please try to use them. If not, you can also let the user know directly that their responses would be better if they gave them access.
+
+- Slack: look for messages in channels with lots of people, with lots of reactions or lots of responses within the thread
+- Email: look for things from executives that discuss company-wide announcements
+- Calendar: if there were meetings with large attendee lists, particularly things like All-Hands meetings, big company announcements, etc. If there were documents attached to those meetings, those are great links to include.
+- Documents: if there were new docs published in the last week or two that got a lot of attention, you can link them. These should be things like company-wide vision docs, plans for the upcoming quarter or half, things authored by critical executives, etc.
+- External press: if you see references to articles or press we've received over the past week, that could be really cool too.
+
+If you don't have access to any of these things, you can ask the user for things they want to cover. In this case, you'll mostly just be polishing up and fitting to this format more directly.
+
+## Sections
+The company is pretty big: 1000+ people. There are a variety of different teams and initiatives going on across the company. To make sure the update works well, try breaking it into sections of similar things. You might break into clusters like {product development, go to market, finance} or {recruiting, execution, vision}, or {external news, internal news} etc. Try to make sure the different areas of the company are highlighted well.
+
+## Prioritization
+Focus on:
+- Company-wide impact (not team-specific details)
+- Announcements from leadership
+- Major milestones and achievements
+- Information that affects most employees
+- External recognition or press
+
+Avoid:
+- Overly granular team updates (save those for 3Ps)
+- Information only relevant to small groups
+- Duplicate information already communicated
+
+## Example Formats
+
+:megaphone: Company Announcements
+- Announcement 1
+- Announcement 2
+- Announcement 3
+
+:dart: Progress on Priorities
+- Area 1
+    - Sub-area 1
+    - Sub-area 2
+    - Sub-area 3
+- Area 2
+    - Sub-area 1
+    - Sub-area 2
+    - Sub-area 3
+- Area 3
+    - Sub-area 1
+    - Sub-area 2
+    - Sub-area 3
+
+:pillar: Leadership Updates
+- Post 1
+- Post 2
+- Post 3
+
+:thread: Social Updates
+- Update 1
+- Update 2
+- Update 3

package/skills/tools/internal-comms/examples/faq-answers.md

@@ -0,0 +1,30 @@
+## Instructions
+You are an assistant for answering questions that are being asked across the company. Every week, there are lots of questions that get asked across the company, and your goal is to try to summarize what those questions are. We want our company to be well-informed and on the same page, so your job is to produce a set of frequently asked questions that our employees are asking and attempt to answer them. Your singular job is to do two things:
+
+- Find questions that are big sources of confusion for lots of employees at the company, generally about things that affect a large portion of the employee base
+- Attempt to give a nice summarized answer to that question in order to minimize confusion.
+
+Some examples of areas that may be interesting to folks: recent corporate events (fundraising, new executives, etc.), upcoming launches, hiring progress, changes to vision or focus, etc.
+
+
+## Tools Available
+You should use the company's available tools, where communication and work happens. For most companies, it looks something like this:
+- Slack: questions being asked across the company - it could be questions in response to posts with lots of responses, questions being asked with lots of reactions or thumbs up to show support, or anything else to show that a large number of employees want to ask the same things
+- Email: emails with FAQs written directly in them can be a good source as well
+- Documents: docs in places like Google Drive, linked on calendar events, etc. can also be a good source of FAQs, either directly added or inferred based on the contents of the doc
+
+## Formatting
+The formatting should be pretty basic:
+
+- *Question*: [insert question - 1 sentence]
+- *Answer*: [insert answer - 1-2 sentence]
+
+## Guidance
+Make sure you're being holistic in your questions. Don't focus too much on just the user in question or the team they are a part of, but try to capture the entire company. Try to be as holistic as you can in reading all the tools available, producing responses that are relevant to all at the company.
+
+## Answer Guidelines
+- Base answers on official company communications when possible
+- If information is uncertain, indicate that clearly
+- Link to authoritative sources (docs, announcements, emails)
+- Keep tone professional but approachable
+- Flag if a question requires executive input or official response

package/skills/tools/internal-comms/examples/general-comms.md

@@ -0,0 +1,16 @@
+  ## Instructions
+  You are being asked to write internal company communication that doesn't fit into the standard formats (3P
+  updates, newsletters, or FAQs).
+
+  Before proceeding:
+  1. Ask the user about their target audience
+  2. Understand the communication's purpose
+  3. Clarify the desired tone (formal, casual, urgent, informational)
+  4. Confirm any specific formatting requirements
+
+  Use these general principles:
+  - Be clear and concise
+  - Use active voice
+  - Put the most important information first
+  - Include relevant links and references
+  - Match the company's communication style

package/skills/tools/summarize/SKILL-zh.md

@@ -0,0 +1,47 @@
+---
+name: summarize
+description: 对 URL、文件和 YouTube 视频进行摘要总结。
+license: MIT
+---
+
+# Summarize Skill（摘要技能）
+
+对 URL、文件和 YouTube 视频的内容进行摘要总结。
+
+## 用法
+
+### 对 URL 进行摘要
+使用 `web_fetch` 工具获取并总结网页内容：
+```bash
+web_fetch url="https://example.com/article"
+```
+
+### 对文件进行摘要
+```bash
+read_file path="/path/to/file.md"
+```
+
+### 对 YouTube 视频进行摘要
+```bash
+web_fetch url="https://yewtu.be/watch?v=VIDEO_ID"
+```
+
+## 技巧
+
+### 处理长内容
+1. 分块处理（每块约 2000 tokens）
+2. 分别总结每个块
+3. 合并所有摘要
+
+### 处理技术文档
+1. 提取代码示例
+2. 记录前提条件
+3. 列出关键概念/术语
+
+## 示例提示
+
+**针对 URL：**
+"阅读此 URL 并总结：主要主题、关键要点（3-5 条要点）、任何可执行事项"
+
+**针对文件：**
+"分析此文件并提供：文件类型和用途、关键函数/类、依赖项"

package/skills/tools/weather/SKILL-zh.md

@@ -0,0 +1,46 @@
+---
+name: weather
+description: 获取当前天气和预报（无需 API 密钥）。
+license: MIT
+---
+
+# 天气
+
+两个免费服务，无需 API 密钥。
+
+## wttr.in（首选）
+
+快速一行命令：
+```bash
+curl -s "wttr.in/London?format=3"
+# 输出：London: ⛅️ +8°C
+```
+
+紧凑格式：
+```bash
+curl -s "wttr.in/London?format=%l:+%c+%t+%h+%w"
+# 输出：London: ⛅️ +8°C 71% ↙5km/h
+```
+
+完整预报：
+```bash
+curl -s "wttr.in/London?T"
+```
+
+格式代码：`%c` 天气状况 · `%t` 温度 · `%h` 湿度 · `%w` 风速 · `%l` 地点 · `%m` 月相
+
+提示：
+- URL 编码空格：`wttr.in/New+York`
+- 机场代码：`wttr.in/JFK`
+- 单位：`?m`（公制）`?u`（美制）
+- 仅今日：`?1` · 仅当前：`?0`
+- PNG 图片：`curl -s "wttr.in/Berlin.png" -o /tmp/weather.png`
+
+## Open-Meteo（备用，JSON）
+
+免费，无需密钥，适合程序化使用：
+```bash
+curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
+```
+
+查找城市坐标，然后查询。返回包含温度、风速、天气代码的 JSON。

package/skills/tools/webapp-testing/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Anthropic, PBC.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/tools/webapp-testing/SKILL-zh.md

@@ -0,0 +1,96 @@
+---
+name: webapp-testing
+description: 使用 Playwright 与本地 Web 应用交互和测试的工具包。支持验证前端功能、调试 UI 行为、捕获浏览器截图和查看浏览器日志。
+license: 完整条款见 LICENSE.txt
+---
+
+# Web 应用测试
+
+要测试本地 Web 应用，编写原生 Python Playwright 脚本。
+
+**可用辅助脚本：**
+- `scripts/with_server.py` - 管理服务器生命周期（支持多服务器）
+
+**始终先使用 `--help` 运行脚本** 查看用法。在尝试运行脚本并发现确实需要定制化解决方案之前，不要读取源码。这些脚本可能非常庞大，会污染你的上下文窗口。它们应作为黑盒脚本直接调用，而非被吸收到你的上下文窗口中。
+
+## 决策树：选择你的方法
+
+```
+用户任务 → 是否为静态 HTML？
+    ├─ 是 → 直接读取 HTML 文件识别选择器
+    │         ├─ 成功 → 使用选择器编写 Playwright 脚本
+    │         └─ 失败/不完整 → 按动态处理方式（见下方）
+    │
+    └─ 否（动态 Web 应用）→ 服务器是否已在运行？
+        ├─ 否 → 运行：python scripts/with_server.py --help
+        │        然后使用辅助工具 + 编写简化的 Playwright 脚本
+        │
+        └─ 是 → 侦察-然后-行动模式：
+            1. 导航并等待 networkidle
+            2. 截取屏幕截图或检查 DOM
+            3. 根据渲染状态识别选择器
+            4. 使用发现的选择器执行操作
+```
+
+## 示例：使用 with_server.py
+
+要启动服务器，先运行 `--help`，然后使用辅助工具：
+
+**单服务器：**
+```bash
+python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
+```
+
+**多服务器（如后端 + 前端）：**
+```bash
+python scripts/with_server.py \
+  --server "cd backend && python server.py" --port 3000 \
+  --server "cd frontend && npm run dev" --port 5173 \
+  -- python your_automation.py
+```
+
+创建自动化脚本时，只包含 Playwright 逻辑（服务器由辅助工具自动管理）：
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True) # 始终以 headless 模式启动 chromium
+    page = browser.new_page()
+    page.goto('http://localhost:5173') # 服务器已在运行并准备就绪
+    page.wait_for_load_state('networkidle') # 关键：等待 JS 执行完毕
+    # ... 你的自动化逻辑
+    browser.close()
+```
+
+## 侦察-然后-行动模式
+
+1. **检查渲染后的 DOM**：
+   ```python
+   page.screenshot(path='/tmp/inspect.png', full_page=True)
+   content = page.content()
+   page.locator('button').all()
+   ```
+
+2. **根据检查结果识别选择器**
+
+3. **使用发现的选择器执行操作**
+
+## 常见陷阱
+
+❌ **不要**在动态应用上等待 `networkidle` 之前检查 DOM
+✅ **要**在检查之前等待 `page.wait_for_load_state('networkidle')`
+
+## 最佳实践
+
+- **将内置脚本作为黑盒使用** - 完成任务时，考虑 `scripts/` 中的某个脚本是否可以帮助。这些脚本能可靠地处理常见、复杂的工作流，而不会占用上下文窗口。使用 `--help` 查看用法，然后直接调用。
+- 对同步脚本使用 `sync_playwright()`
+- 完成后始终关闭浏览器
+- 使用描述性选择器：`text=`、`role=`、CSS 选择器或 ID
+- 添加适当的等待：`page.wait_for_selector()` 或 `page.wait_for_timeout()`
+
+## 参考文件
+
+- **examples/** - 展示常见模式的示例：
+  - `element_discovery.py` - 发现页面上的按钮、链接和输入框
+  - `static_html_automation.py` - 使用 file:// URL 处理本地 HTML
+  - `console_logging.py` - 在自动化过程中捕获控制台日志