autoclaw 1.3.6 → 1.3.7

package/README.md

@@ -144,7 +144,7 @@ Scopes (later shadows earlier on name collision): built-in `skills/` (ships with
 autoclaw skill list                     # show discovered skills with scope and version
 autoclaw skill install <zip|dir|https-url>  # install into ~/.autoclaw/skills/ (zip-slip protected)
 autoclaw skill remove <name>            # remove a user-installed skill (built-ins are protected)
-autoclaw skill pack <dir>               # zip a skill dir (skills/<name>/ root) for store upload
+autoclaw skill pack <dir>               # zip a skill dir -> <name>-skill-<version>.zip (SKILL.md at zip root)
 ```
 
 Install accepts any SKILL.md-compatible package: a local directory, a local zip, or an https download URL. It tolerates third-party layout variance (SKILL.md at the zip root, a plain folder, or a `skills/<name>/` wrapper, macOS `__MACOSX`/`.DS_Store` junk) and always installs under the skill's frontmatter `name`, so discovery and the manifest stay consistent.
@@ -301,7 +301,7 @@ autoclaw batch render-jobs.jsonl -y -c 4
 
 Tool choice: use `render_image` / `render_pdf` when exact text, layout and branding matter (cards, banners, badges, documents); use `generate_image` for artistic or photographic imagery. Emoji in templates are fetched from the Twemoji CDN by default, so fully offline environments should keep templates text-only.
 
-Runnable examples with committed previews: [examples/render](examples/render/README.md) (OG cards, social posters, KPI cards, weekly-report PDFs, SVG badges, certificates, animations, multi-page invoices — plus a real agent one-shot run under `agent-run/`). The same capability ships as a portable [WorkBuddy skill](skills/code2media/SKILL.md) (`code2media-skill.zip`) that renders HTML → image/SVG/PDF/animation via a standalone Node script on any machine with Node >= 20.19.
+Runnable examples with committed previews: [examples/render](examples/render/README.md) (OG cards, social posters, KPI cards, weekly-report PDFs, SVG badges, certificates, animations, multi-page invoices — plus a real agent one-shot run under `agent-run/`). The same capability ships as a portable [WorkBuddy skill](skills/code2media/SKILL.md) (`code2media-skill-1.2.1.zip`) that renders HTML → image/SVG/PDF/animation via a standalone Node script on any machine with Node >= 20.19.
 
 ## Docker Support
 

package/README.zh-CN.md

@@ -1,348 +1,348 @@
-# AutoClaw 🦞
-
-[![NPM Version](https://img.shields.io/npm/v/autoclaw.svg?style=flat-square)](https://www.npmjs.com/package/autoclaw)
-[![NPM Downloads](https://img.shields.io/npm/dm/autoclaw.svg?style=flat-square)](https://www.npmjs.com/package/autoclaw)
-[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github&style=flat-square)](https://github.com/tsingliuwin/autoclaw)
-[![License](https://img.shields.io/npm/l/autoclaw.svg?style=flat-square)](https://github.com/tsingliuwin/autoclaw/blob/main/LICENSE)
-[![Safety](https://img.shields.io/badge/Safety-Notice-yellow?style=flat-square)](./SAFETY.md)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
-
-**稳定、高工程化、易规模化：专为无界面系统设计的高效自动化 Agent 框架。**
-
-[English](./README.md) | 简体中文
-
----
-
-🔗 **GitHub 仓库**: [https://github.com/tsingliuwin/autoclaw](https://github.com/tsingliuwin/autoclaw)
-
----
-
-AutoClaw 是一款针对 **“无界面系统” (Headless Systems)** 的高稳定性自动化 Agent 开源框架。
-
-相比于 OpenClaw 等需要“看屏幕”的 Agent（如视觉解析），AutoClaw 采用纯指令驱动，具有更强的**工程化**属性、更高的**稳定性**，以及极易**规模化**的特点。它专为在各种复杂环境中执行确定性的自动化任务而设计——无论是本地服务器、CI/CD 流水线，还是成千上万个容器节点。
-
-## 为什么选择 AutoClaw?
-
-- 🐳 **Docker 友好**: 专为容器化环境设计，无 GUI 依赖，极致轻量（Node.js/Alpine 友好）。
-- 🚀 **更强工程化 (Better Engineering)**: 并非依赖不稳定的视觉识别，而是通过系统 API 和 Shell 指令精准操作，确保任务执行的确定性。
-- 🛡️ **高稳定性 (Superior Stability)**: 摆脱了图形界面渲染、屏幕分辨率、网络延迟对视觉识别的影响，即便在极端的 Headless 环境下也能稳定运行。
-- 📈 **易于规模化 (Massive Scalability)**: 低资源占用使得你可以同时编排成千上万个 Agent 实例（如在 Kubernetes 集群中），实现真正的自动化蜂群。
-- 🔌 **集群就绪 (Swarm Ready)**: 无状态设计，支持通过 K8s、Docker Swarm 或简单的 Shell 脚本进行大规模调度。
-- 🧩 **可扩展集成**: 内置支持网页搜索 (Tavily)、邮件发送 (SMTP) 以及通知钩子 (飞书、钉钉、企业微信)。
-
-## 特性
-
-- 📜 **无头执行 (Headless Execution)**: 无需图形界面，纯终端运行。核心流程仅依赖 Shell 与文件操作；可选的网页工具在无头 Chromium 中运行。
-- 🤖 **非交互模式**: 支持自动化标志（`-y`, `--no-interactive`），完美适配零干预的自动化流程。
-- 📂 **全方位控制 (Universal Control)**: 从基础的文件 I/O 到复杂的系统管理。
-- 🖥️ **后台进程**: 后台启动长期命令(开发服务器、watcher)并轮询输出,不阻塞任务运行。
-- 🛡️ **安全护栏**: 破坏性命令闸、凭据文件防线、步数上限、墙钟超时与 API 重试——为没有人看着的机器而设计。
-- 🧠 **上下文感知 (Context Aware)**: 提供精确的操作系统与时间上下文，正确处理"今天"、"下周一"等相对时间。
-- 🌐 **网页搜索**: 集成 Tavily，支持实时信息检索。
-- 🌍 **网页阅读与截图**: 提取文章正文、截取页面图片（需先执行 `npx playwright install chromium`）。
-- 🎨 **图像生成**: 通过任意 OpenAI 兼容的图像接口生成图片（兼容 DALL-E）。
-- 🖼️ **确定性图像渲染** (`render_image`): HTML + Tailwind 模板直接渲染为 PNG/JPEG/WebP/SVG,并支持动图(由 CSS `@keyframes` 采样的动画 WebP/GIF/APNG)。完全离线、无浏览器、毫秒级渲染——适合 OG 分享卡、横幅、徽章、数据卡片等对文字与排版精度有要求的场景。
-- 📄 **PDF 渲染** (`render_pdf`): HTML 模板直接渲染为分页 PDF，文字可选中、页眉页脚逐页重复、支持页码计数。完全离线、无浏览器——适合发票、报表、证书等结构化文档。
-- 🕒 **时间精准**: 内置工具获取精确系统日期和时间，确保正确的时间上下文。
-- 📧 **通讯能力**: 自动发送电子邮件并将通知推送至聊天群组。
-
-## 技术栈
-- **运行时**: Node.js
-- **语言**: TypeScript
-- **框架**: Commander.js
-- **UI**: Inquirer (交互), Chalk (样式), Ora (加载动画)
-- **AI**: OpenAI SDK（任意 OpenAI 兼容端点：DeepSeek、Kimi、Qwen、GLM、Ollama 等）
-- **网页工具**: Playwright（无头 Chromium，用于 `read_website` / `take_screenshot`）
-- **渲染引擎**: Takumi（Rust 引擎，经原生绑定驱动 `render_image` / `render_pdf`，无需浏览器）
-
-## 安装
-
-### 用户安装
-通过 npm 全局安装：
-```bash
-npm install -g autoclaw
-```
-
-### 开发安装
-1.  克隆仓库：
-    ```bash
-    git clone https://github.com/tsingliuwin/autoclaw.git
-    cd autoclaw
-    ```
-2.  安装依赖：
-    ```bash
-    npm install
-    ```
-3.  构建项目：
-    ```bash
-    npm run build
-    ```
-4.  全局链接 (可选)：
-    ```bash
-    npm link
-    ```
-
-## 快速上手
-
-1.  **配置**: 运行交互式设置向导以配置您的 API 密钥和集成插件。向导会现场做连接测试(失败映射到最可能出错的字段:401=key 错、404=URL 错、400=模型名错),并能拉取服务商的模型列表供你直接选择。
-    ```bash
-    autoclaw setup
-    ```
-2.  **运行**: 在交互模式下启动 Agent。
-    ```bash
-    autoclaw
-    ```
-
-## 使用方法
-
-### 交互模式
-直接运行 `autoclaw` 进入对话循环。
-```bash
-autoclaw
-> 列出 src 文件夹中所有的 TypeScript 文件。
-```
-交互命令：`exit` / `quit` 退出；`/view` 用分页器查看上一次工具的完整输出——超过 20 行的工具输出会在屏幕上折叠，并保存到 `~/.autoclaw/output/`。
-
-### 无头模式 (一次性任务)
-执行单个指令后立即退出。
-```bash
-autoclaw "检查磁盘使用情况并将报告保存到 usage.txt" --no-interactive
-```
-退出码向编排器报告结果：`0` 完成，`1` 硬性失败（如 API 错误），`2` 触发步数上限（任务未完成）。
-
-### 机器可读输出 (--json)
-加 `--json` 后，stdout 每行输出一个 JSON 事件（run_start、tool_call、tool_result、usage、run_end）；人类可读输出（包括工具自己打印的内容）全部转到 stderr。
-```bash
-autoclaw "执行部署并汇报" -y -n --json
-```
-Token 用量仅在设置 `AUTOCLOW_INCLUDE_USAGE=1`（或 `true`）时才收集——这是可选项，因为并非所有 OpenAI 兼容端点都接受 `stream_options.include_usage`。
-
-### 批处理模式 (蜂群工人)
-把 JSONL 任务清单交给 AutoClaw；每个任务在全新的隔离 Agent 中执行（任务之间上下文互不污染），结果逐行写入 JSONL 文件：
-```bash
-autoclaw batch tasks.jsonl -y                          # 结果 -> tasks.results.jsonl
-autoclaw batch tasks.jsonl -o out.jsonl --fail-fast
-```
-清单每行为 `{"id": "...", "task": "..."}`——`id` 可省略（默认 `task-N`）；空行和 `#` 注释行会跳过。可选的每任务覆盖项：`maxSteps`、`model`、`provider`。
-
-单个任务失败不会中断批次（需要中断用 `--fail-fast`）。全部完成时进程退出 `0`，否则 `1`，cron 和 K8s Job 由此感知批次成败。任务输出保持人类可读——结果文件才是机器可读契约，含每个任务的 `status`、`steps`、`message`、`error`、`usage`。
-
-长批次可以中途停、从断点继续，也可以本地并行：
-```bash
-autoclaw batch big.jsonl -y --resume        # 跳过结果文件中已完成的任务
-autoclaw batch big.jsonl -y -c 4            # 最多 4 个任务并行
-```
-未执行的任务不会出现在结果文件里，所以 `--fail-fast` 之后接 `--resume` 就是天然的重试循环。
-
-AutoClaw 同时会自动给提示词瘦身：可选工具（网页搜索、邮件、群通知、图像生成）只在凭据配置后才会注册进工具定义；长循环中较早的工具结果会被替换为短摘要。
-
-### 技能（可移植能力包）
-AutoClaw 支持 `SKILL.md` 技能包——与 WorkBuddy 技能商店相同的格式，一份技能包既能在 AutoClaw 内运行，也能发布到其它平台。system prompt 里每个技能只占一行清单；任务匹配时 agent 才去读取该技能的 `SKILL.md` 并照做，全程走普通的文件与 shell 工具。技能没有特权运行时：脚本同样经过破坏性命令闸、沙箱与步数上限。
-
-作用域（同名后者遮蔽前者）：内置 `skills/`（随 npm 包发布）→ `~/.autoclaw/skills/` → `.autoclaw/skills/`。
-
-```bash
-autoclaw skill list                     # 列出发现的技能(含作用域与版本)
-autoclaw skill install <zip|目录|https地址>  # 安装到 ~/.autoclaw/skills/(含 zip-slip 防护)
-autoclaw skill remove <name>            # 移除用户级技能(内置技能受保护)
-autoclaw skill pack <目录>               # 打包为商店上传 zip(zip 根为 skills/<name>/)
-```
-
-安装兼容任意 SKILL.md 格式的第三方包：本地目录、本地 zip 或 https 下载地址均可。对第三方布局差异做了容错（SKILL.md 位于 zip 根部、普通文件夹、`skills/<name>/` 包装、macOS 的 `__MACOSX`/`.DS_Store` 垃圾文件），并且始终按技能 frontmatter 的 `name` 安装，保证发现与清单的一致性。
-
-内置三个技能，分层协作：[`code2media`](skills/code2media/SKILL.md)（代码转多媒体）是通用渲染引擎——独立 Node 脚本把任意 HTML 变成图片/SVG/分页 PDF/动图；[`poster-maker`](skills/poster-maker/SKILL.md)（海报生成器）与 [`invoice-maker`](skills/invoice-maker/SKILL.md)（发票生成器）是独立优化的场景技能，各自沉淀了平台尺寸表、票据版式规范与质量清单。同一个 zip 可直接发布到任何兼容 SKILL.md 的商店。技能与 batch 模式天然组合：清单里一行 `{"id":"cert-042","task":"用 invoice-maker 技能根据 orders-042.json 生成发票 invoices/042.pdf"}` 就能让一个隔离的 swarm worker 跑同一个技能。
-
-### 实战配方
-
-Linux 定时巡检（crontab）：
-```cron
-0 9 * * * autoclaw batch /opt/ops/daily.jsonl -y -n --resume >> /var/log/autoclaw.log 2>&1
-```
-
-Windows 计划任务：
-```bash
-schtasks /create /tn "AutoClaw Daily" /tr "autoclaw batch C:\ops\daily.jsonl -y -n" /sc daily /st 09:00
-```
-
-一个清单内的流水线——前一个任务写文件,后一个任务读：
-```jsonl
-{"id": "sweep", "task": "检查磁盘与关键服务状态,报告写入 report/sweep.md"}
-{"id": "notify", "task": "读取 report/sweep.md,用三句话总结后推送到飞书"}
-```
-
-新机器或 CI 环境自检：
-```bash
-autoclaw doctor   # 退出 0 = 就绪;退出 1 = 打印缺失项
-```
-
-### 自动确认 (CI/CD)
-自动批准所有工具执行（危险操作，请谨慎使用或在沙箱环境下运行）。
-```bash
-autoclaw "将 src/index.ts 重构为使用 ES 模块" -y
-```
-
-### CLI 选项
-- `-m, --model <model>`: 指定 LLM 模型 (默认: `gpt-5.6`)。
-- `-P, --provider <name>`: 使用 provider 预设 (见 [Provider 预设](#provider-预设))。
-- `-n, --no-interactive`: 处理完初始查询后退出 (无头模式)。
-- `-y, --yes`: 自动确认所有工具执行 (例如 Shell 命令)。
-- `--allow-dangerous`: 允许 `-y` 直接执行内置安全闸拦截的明显破坏性命令 (rm -rf、format、shutdown 等)。
-- `--json`: 在 stdout 输出 NDJSON 事件流 (供编排器使用,配合 `-n`)。
-
-### 诊断
-`autoclaw doctor` 无头完成全面自检,逐项打印 ✓/✗:配置文件、解析出的 provider/baseUrl/model、API key、真实连接测试、解析出的 shell、已注册工具、playwright 浏览器状态。退出 `0` = 就绪,`1` = 有关键项失败(会打印是哪项)。适合 CI 或新机器。
-
-### 沙箱
-命令执行可通过 `config.sandbox` / `AUTOCLOW_SANDBOX` 加以约束(词汇借鉴自 DeepSeek Harness):
-- `danger-full-access`(默认):命令不受约束地运行。
-- `workspace-write`:命令只能在当前工作目录和 `/tmp` 内写入。
-- `read-only`:命令无法在任何位置写入。
-
-后端:Linux 使用 bubblewrap(`apt install bubblewrap`),macOS 使用 `sandbox-exec`。**Windows 暂无后端**——非默认模式会"失败关闭"(直接拒绝命令并给出明确错误),而不是假装约束;在 Windows 上请暂用 `danger-full-access`。此词汇不约束读取与网络。
-- `--json`: 在 stdout 输出 NDJSON 事件流 (供编排器使用,配合 `-n`)。
-
-### Provider 预设
-AutoClaw 可对接任意 OpenAI 兼容端点。内置预设可自动填好 Base URL 和默认模型：
-```bash
-autoclaw -P deepseek "检查磁盘使用情况并保存报告" -y -n
-```
-可用预设：`openai`、`deepseek`、`moonshot` (Kimi)、`dashscope` (Qwen)、`zhipu` (GLM)、`ark` (火山方舟)、`siliconflow` (硅基流动)、`openrouter`、`ollama` (本地)。模型仍可用 `-m` 或配置覆盖。未设置 `OPENAI_API_KEY` 时，会自动读取各家自己的环境变量 (如 `DEEPSEEK_API_KEY`、`MOONSHOT_API_KEY`、`DASHSCOPE_API_KEY`、`ZHIPU_API_KEY`、`ARK_API_KEY`、`SILICONFLOW_API_KEY`、`OPENROUTER_API_KEY`)。
-
-## 配置
-
-AutoClaw 使用层级配置系统。
-
-**优先级排序 (从高到低):**
-1.  **CLI 参数**: (例如 `-m gpt-5.6`)
-2.  **环境变量**: (`OPENAI_API_KEY`, `.env` 文件)
-3.  **项目配置**: (当前目录下的 `./.autoclaw/setting.json`)
-4.  **全局配置**: (`~/.autoclaw/setting.json`)
-
-### 支持的配置键 (JSON)
-- `provider`: Provider 预设名 (如 `deepseek`)。
-- `apiKey`: 您的 OpenAI API 密钥。
-- `baseUrl`: 自定义 API 基础地址 (例如 DeepSeek 或本地 LLM)。
-- `model`: 默认使用的模型。
-- `maxSteps`: 单任务最大 LLM 轮数，超出后自动停止 (默认: `25`)。
-- `shellTimeout`: Shell 命令超时时间（毫秒）(默认: `120000`)。
-- `taskTimeoutMs`: 单任务整体墙钟超时（毫秒，默认关闭；会中断进行中的 API 调用并以 `timeout` 状态停止）。
-- `sandbox`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`；默认 `danger-full-access`）。
-- `skillsEnabled`: 设为 `false` 关闭技能系统（默认开启）。
-- `shell`: 强制 `execute_shell_command` 使用的 shell (`bash`、`powershell`、`cmd`、`sh`；默认自动检测——Windows 上优先 Git Bash > PowerShell > cmd)。
-- `tavilyApiKey`: Tavily 网页搜索的 API 密钥。
-- `smtpHost`, `smtpPort`, `smtpUser`, `smtpPass`, `smtpFrom`: SMTP 邮件设置。
-- `feishuWebhook`, `dingtalkWebhook`, `wecomWebhook`: 通知钩子地址。
-
-### 项目级配置示例
-在 `.autoclaw/setting.json` 创建文件：
-```json
-{
-  "model": "gpt-5.6",
-  "baseUrl": "https://api.deepseek.com/v1"
-}
-```
-
-> **⚠️ 安全警告**: 如果您在 `.autoclaw/setting.json` 中存储了 `apiKey` 或机密信息，请务必将 `.autoclaw/` 添加到您的 `.gitignore` 文件中，以防泄露！
-
-### 环境变量
-- `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`: 主模型设置。
-- `AUTOCLOW_PROVIDER`: 未传 `-P` 时使用的 provider 预设。
-- `AUTOCLOW_MAX_STEPS`, `AUTOCLOW_SHELL_TIMEOUT`: 稳定性限制（单任务最大轮数；Shell 超时毫秒数）。
-- `AUTOCLOW_TASK_TIMEOUT_MS`: 单任务整体墙钟超时（毫秒）。
-- `AUTOCLOW_SANDBOX`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`）。
-- `AUTOCLOW_SHELL`: 强制 shell 命令使用的 shell (`bash`、`powershell`、`cmd`、`sh`)。
-- `AUTOCLOW_INCLUDE_USAGE`: 设为 `1`/`true` 时向 API 请求 token 用量（可选开启）。
-- `TAVILY_API_KEY`, `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASS`, `FEISHU_WEBHOOK`/`FEISHU_KEYWORD`, `DINGTALK_WEBHOOK`/`DINGTALK_KEYWORD`, `WECOM_WEBHOOK`/`WECOM_KEYWORD`: 工具凭据，可作为 setup 的替代方式。
-
-## 集成功能
-
-### 网页搜索 (Tavily)
-如果您在设置中提供了 Tavily API 密钥，AutoClaw 可以搜索网页。
-- **示例**: "搜索最新的 Node.js 发布说明。"
-
-### 邮件 (SMTP)
-配置 SMTP 设置以允许 Agent 发送邮件。
-- **示例**: "向 user@example.com 发送一封包含日志文件摘要的邮件。"
-
-### 通知 (飞书/钉钉/企业微信)
-配置 Webhook 以在团队聊天应用中接收警报或报告。
-- **示例**: "在飞书上通知团队构建已完成。"
-
-### 日期与时间
-内置工具为 Agent 提供当前系统时间，确保准确处理相对时间请求。
-- **示例**: "今天是几号？" 或 "提醒我下周一检查日志。"
-
-### 确定性渲染 (Takumi)
-`render_image` 将 HTML 模板渲染为精确的图像——PNG、JPEG、WebP 或矢量 SVG——全程离线，不依赖浏览器或 AI 模型。`render_pdf` 将 HTML 模板渲染为分页 PDF，文字可选中，页眉/页脚逐页重复，并支持 `<span class="pageNumber">` / `<span class="totalPages">` 页码计数。模板样式支持内联 CSS、`<style>` 块，或通过 `tw` 属性使用 Tailwind v4 工具类（`<div tw="w-full h-full bg-blue-500">`）；普通 `class` 属性仅匹配常规 CSS 选择器。两个工具都会自动探测常见系统字体（含中日韩与 Emoji）；也可通过 `font_paths` 注册指定字体文件。
-
-典型工作流——用自然语言描述任务，模板由 agent 自己编写：
-
-```bash
-# 博客 SEO:为每篇文章生成 OG 分享图
-autoclaw "读取 content/posts/ 下每篇 .md 的标题和摘要,为每篇文章渲染一张 OG 分享图(1200x630)到 public/og/" -y -n
-
-# 财务/电商:从订单表批量生成 PDF 发票并邮件发送
-autoclaw "读取 orders.csv,为每个订单生成 PDF 发票保存到 invoices/(A4,页脚带页码),然后把每张发票邮件发送给该行记录的客户邮箱" -y
-
-# 培训/HR:为学员名单批量生成结业证书
-autoclaw "读取 attendees.json,为每位学员渲染一张结业证书(1414x1000)保存到 certs/,编号从 AC-2026-0001 起" -y -n
-
-# cron/CI 定时报告:输出确定——相同输入得到完全相同的 PDF,可做校验
-autoclaw "汇总本周 nginx 访问日志,生成一页 A4 的 PDF 流量周报(含指标表格),保存为 report.pdf" -y -n
-```
-
-集群规模用 batch 模式——每个任务在隔立的 agent 中渲染:
-
-```bash
-cat > render-jobs.jsonl <<'EOF'
-{"id": "og-001", "task": "为 post-001.md 渲染 OG 分享图到 public/og/001.png"}
-{"id": "og-002", "task": "为 post-002.md 渲染 OG 分享图到 public/og/002.png"}
-EOF
-autoclaw batch render-jobs.jsonl -y -c 4
-```
-
-选型提示:需要精确文字、排版与品牌一致性(卡片、横幅、徽章、文档)时用 `render_image` / `render_pdf`;艺术创作、照片类图像用 `generate_image`。模板中的 Emoji 默认从 Twemoji CDN 在线获取,完全离线的环境请让模板保持纯文本。
-
-可运行案例与渲染效果预览:[examples/render](examples/render/README.zh-CN.md)(OG 分享卡、社媒海报、KPI 指标卡、周报 PDF、SVG 徽章、证书、动图、多页采购订单——`agent-run/` 下还有一次真实 agent 无头运行的产物)。同一能力也打包成了可移植的 [WorkBuddy 技能](skills/code2media/SKILL.md)(`code2media-skill.zip`):一个独立 Node 脚本,任何装有 Node >= 20.19 的机器都能把 HTML 渲染成图片/SVG/PDF/动图。
-
-## Docker 支持
-
-### 构建与运行
-仓库自带多阶段构建的 `Dockerfile`（node:22-alpine，跳过浏览器下载保持镜像苗条）。容器内直接运行无头一次性任务，配合目录挂载操作当前目录：
-```bash
-docker build -t autoclaw .
-docker run --rm -v "$PWD":/workspace -w /workspace -e OPENAI_API_KEY=sk-... autoclaw "检查磁盘使用情况并保存报告" -y -n
-```
-注意：默认镜像中未内置浏览器，基于浏览器的工具（`read_website` / `take_screenshot`）不可用——它们会返回友好的安装提示，而不是报错崩溃。
-
-### 截图与渲染输出中的中文显示问题
-在 Docker 容器（尤其是 Alpine 或 Debian Slim）中运行时，网页截图中的中文可能会显示为方块（"豆腐块"）。表情符号（如 🔥）也可能显示为方块。`render_image` / `render_pdf` 输出中包含中日韩文字时同样受影响。
-
-**解决方案:** 在容器中安装 CJK（中日韩）和 Emoji 字体。渲染工具会自动探测同一批字体路径，因此安装这些字体包可以同时修复截图与渲染输出的中文显示。
-
-**Debian/Ubuntu:**
-```bash
-apt-get update && apt-get install -y fonts-noto-cjk fonts-wqy-zenhei fonts-noto-color-emoji
-```
-
-**Alpine Linux:**
-```bash
-apk add font-noto-cjk font-noto-emoji
-```
-
-## 开源协议
-
-MIT
-
-## 贡献指南
-
-欢迎贡献！请随时提交 Pull Request。
-
-1.  Fork 本项目
-2.  创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
-3.  提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
-4.  推送至分支 (`git push origin feature/AmazingFeature`)
-5.  开启一个 Pull Request
-
----
+# AutoClaw 🦞
+
+[![NPM Version](https://img.shields.io/npm/v/autoclaw.svg?style=flat-square)](https://www.npmjs.com/package/autoclaw)
+[![NPM Downloads](https://img.shields.io/npm/dm/autoclaw.svg?style=flat-square)](https://www.npmjs.com/package/autoclaw)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github&style=flat-square)](https://github.com/tsingliuwin/autoclaw)
+[![License](https://img.shields.io/npm/l/autoclaw.svg?style=flat-square)](https://github.com/tsingliuwin/autoclaw/blob/main/LICENSE)
+[![Safety](https://img.shields.io/badge/Safety-Notice-yellow?style=flat-square)](./SAFETY.md)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+
+**稳定、高工程化、易规模化：专为无界面系统设计的高效自动化 Agent 框架。**
+
+[English](./README.md) | 简体中文
+
+---
+
+🔗 **GitHub 仓库**: [https://github.com/tsingliuwin/autoclaw](https://github.com/tsingliuwin/autoclaw)
+
+---
+
+AutoClaw 是一款针对 **“无界面系统” (Headless Systems)** 的高稳定性自动化 Agent 开源框架。
+
+相比于 OpenClaw 等需要“看屏幕”的 Agent（如视觉解析），AutoClaw 采用纯指令驱动，具有更强的**工程化**属性、更高的**稳定性**，以及极易**规模化**的特点。它专为在各种复杂环境中执行确定性的自动化任务而设计——无论是本地服务器、CI/CD 流水线，还是成千上万个容器节点。
+
+## 为什么选择 AutoClaw?
+
+- 🐳 **Docker 友好**: 专为容器化环境设计，无 GUI 依赖，极致轻量（Node.js/Alpine 友好）。
+- 🚀 **更强工程化 (Better Engineering)**: 并非依赖不稳定的视觉识别，而是通过系统 API 和 Shell 指令精准操作，确保任务执行的确定性。
+- 🛡️ **高稳定性 (Superior Stability)**: 摆脱了图形界面渲染、屏幕分辨率、网络延迟对视觉识别的影响，即便在极端的 Headless 环境下也能稳定运行。
+- 📈 **易于规模化 (Massive Scalability)**: 低资源占用使得你可以同时编排成千上万个 Agent 实例（如在 Kubernetes 集群中），实现真正的自动化蜂群。
+- 🔌 **集群就绪 (Swarm Ready)**: 无状态设计，支持通过 K8s、Docker Swarm 或简单的 Shell 脚本进行大规模调度。
+- 🧩 **可扩展集成**: 内置支持网页搜索 (Tavily)、邮件发送 (SMTP) 以及通知钩子 (飞书、钉钉、企业微信)。
+
+## 特性
+
+- 📜 **无头执行 (Headless Execution)**: 无需图形界面，纯终端运行。核心流程仅依赖 Shell 与文件操作；可选的网页工具在无头 Chromium 中运行。
+- 🤖 **非交互模式**: 支持自动化标志（`-y`, `--no-interactive`），完美适配零干预的自动化流程。
+- 📂 **全方位控制 (Universal Control)**: 从基础的文件 I/O 到复杂的系统管理。
+- 🖥️ **后台进程**: 后台启动长期命令(开发服务器、watcher)并轮询输出,不阻塞任务运行。
+- 🛡️ **安全护栏**: 破坏性命令闸、凭据文件防线、步数上限、墙钟超时与 API 重试——为没有人看着的机器而设计。
+- 🧠 **上下文感知 (Context Aware)**: 提供精确的操作系统与时间上下文，正确处理"今天"、"下周一"等相对时间。
+- 🌐 **网页搜索**: 集成 Tavily，支持实时信息检索。
+- 🌍 **网页阅读与截图**: 提取文章正文、截取页面图片（需先执行 `npx playwright install chromium`）。
+- 🎨 **图像生成**: 通过任意 OpenAI 兼容的图像接口生成图片（兼容 DALL-E）。
+- 🖼️ **确定性图像渲染** (`render_image`): HTML + Tailwind 模板直接渲染为 PNG/JPEG/WebP/SVG,并支持动图(由 CSS `@keyframes` 采样的动画 WebP/GIF/APNG)。完全离线、无浏览器、毫秒级渲染——适合 OG 分享卡、横幅、徽章、数据卡片等对文字与排版精度有要求的场景。
+- 📄 **PDF 渲染** (`render_pdf`): HTML 模板直接渲染为分页 PDF，文字可选中、页眉页脚逐页重复、支持页码计数。完全离线、无浏览器——适合发票、报表、证书等结构化文档。
+- 🕒 **时间精准**: 内置工具获取精确系统日期和时间，确保正确的时间上下文。
+- 📧 **通讯能力**: 自动发送电子邮件并将通知推送至聊天群组。
+
+## 技术栈
+- **运行时**: Node.js
+- **语言**: TypeScript
+- **框架**: Commander.js
+- **UI**: Inquirer (交互), Chalk (样式), Ora (加载动画)
+- **AI**: OpenAI SDK（任意 OpenAI 兼容端点：DeepSeek、Kimi、Qwen、GLM、Ollama 等）
+- **网页工具**: Playwright（无头 Chromium，用于 `read_website` / `take_screenshot`）
+- **渲染引擎**: Takumi（Rust 引擎，经原生绑定驱动 `render_image` / `render_pdf`，无需浏览器）
+
+## 安装
+
+### 用户安装
+通过 npm 全局安装：
+```bash
+npm install -g autoclaw
+```
+
+### 开发安装
+1.  克隆仓库：
+    ```bash
+    git clone https://github.com/tsingliuwin/autoclaw.git
+    cd autoclaw
+    ```
+2.  安装依赖：
+    ```bash
+    npm install
+    ```
+3.  构建项目：
+    ```bash
+    npm run build
+    ```
+4.  全局链接 (可选)：
+    ```bash
+    npm link
+    ```
+
+## 快速上手
+
+1.  **配置**: 运行交互式设置向导以配置您的 API 密钥和集成插件。向导会现场做连接测试(失败映射到最可能出错的字段:401=key 错、404=URL 错、400=模型名错),并能拉取服务商的模型列表供你直接选择。
+    ```bash
+    autoclaw setup
+    ```
+2.  **运行**: 在交互模式下启动 Agent。
+    ```bash
+    autoclaw
+    ```
+
+## 使用方法
+
+### 交互模式
+直接运行 `autoclaw` 进入对话循环。
+```bash
+autoclaw
+> 列出 src 文件夹中所有的 TypeScript 文件。
+```
+交互命令：`exit` / `quit` 退出；`/view` 用分页器查看上一次工具的完整输出——超过 20 行的工具输出会在屏幕上折叠，并保存到 `~/.autoclaw/output/`。
+
+### 无头模式 (一次性任务)
+执行单个指令后立即退出。
+```bash
+autoclaw "检查磁盘使用情况并将报告保存到 usage.txt" --no-interactive
+```
+退出码向编排器报告结果：`0` 完成，`1` 硬性失败（如 API 错误），`2` 触发步数上限（任务未完成）。
+
+### 机器可读输出 (--json)
+加 `--json` 后，stdout 每行输出一个 JSON 事件（run_start、tool_call、tool_result、usage、run_end）；人类可读输出（包括工具自己打印的内容）全部转到 stderr。
+```bash
+autoclaw "执行部署并汇报" -y -n --json
+```
+Token 用量仅在设置 `AUTOCLOW_INCLUDE_USAGE=1`（或 `true`）时才收集——这是可选项，因为并非所有 OpenAI 兼容端点都接受 `stream_options.include_usage`。
+
+### 批处理模式 (蜂群工人)
+把 JSONL 任务清单交给 AutoClaw；每个任务在全新的隔离 Agent 中执行（任务之间上下文互不污染），结果逐行写入 JSONL 文件：
+```bash
+autoclaw batch tasks.jsonl -y                          # 结果 -> tasks.results.jsonl
+autoclaw batch tasks.jsonl -o out.jsonl --fail-fast
+```
+清单每行为 `{"id": "...", "task": "..."}`——`id` 可省略（默认 `task-N`）；空行和 `#` 注释行会跳过。可选的每任务覆盖项：`maxSteps`、`model`、`provider`。
+
+单个任务失败不会中断批次（需要中断用 `--fail-fast`）。全部完成时进程退出 `0`，否则 `1`，cron 和 K8s Job 由此感知批次成败。任务输出保持人类可读——结果文件才是机器可读契约，含每个任务的 `status`、`steps`、`message`、`error`、`usage`。
+
+长批次可以中途停、从断点继续，也可以本地并行：
+```bash
+autoclaw batch big.jsonl -y --resume        # 跳过结果文件中已完成的任务
+autoclaw batch big.jsonl -y -c 4            # 最多 4 个任务并行
+```
+未执行的任务不会出现在结果文件里，所以 `--fail-fast` 之后接 `--resume` 就是天然的重试循环。
+
+AutoClaw 同时会自动给提示词瘦身：可选工具（网页搜索、邮件、群通知、图像生成）只在凭据配置后才会注册进工具定义；长循环中较早的工具结果会被替换为短摘要。
+
+### 技能（可移植能力包）
+AutoClaw 支持 `SKILL.md` 技能包——与 WorkBuddy 技能商店相同的格式，一份技能包既能在 AutoClaw 内运行，也能发布到其它平台。system prompt 里每个技能只占一行清单；任务匹配时 agent 才去读取该技能的 `SKILL.md` 并照做，全程走普通的文件与 shell 工具。技能没有特权运行时：脚本同样经过破坏性命令闸、沙箱与步数上限。
+
+作用域（同名后者遮蔽前者）：内置 `skills/`（随 npm 包发布）→ `~/.autoclaw/skills/` → `.autoclaw/skills/`。
+
+```bash
+autoclaw skill list                     # 列出发现的技能(含作用域与版本)
+autoclaw skill install <zip|目录|https地址>  # 安装到 ~/.autoclaw/skills/(含 zip-slip 防护)
+autoclaw skill remove <name>            # 移除用户级技能(内置技能受保护)
+autoclaw skill pack <目录>               # 打包为商店上传 zip(默认 <name>-skill-<version>.zip,SKILL.md 位于 zip 根目录)
+```
+
+安装兼容任意 SKILL.md 格式的第三方包：本地目录、本地 zip 或 https 下载地址均可。对第三方布局差异做了容错（SKILL.md 位于 zip 根部、普通文件夹、`skills/<name>/` 包装、macOS 的 `__MACOSX`/`.DS_Store` 垃圾文件），并且始终按技能 frontmatter 的 `name` 安装，保证发现与清单的一致性。
+
+内置三个技能，分层协作：[`code2media`](skills/code2media/SKILL.md)（代码转多媒体）是通用渲染引擎——独立 Node 脚本把任意 HTML 变成图片/SVG/分页 PDF/动图；[`poster-maker`](skills/poster-maker/SKILL.md)（海报生成器）与 [`invoice-maker`](skills/invoice-maker/SKILL.md)（发票生成器）是独立优化的场景技能，各自沉淀了平台尺寸表、票据版式规范与质量清单。同一个 zip 可直接发布到任何兼容 SKILL.md 的商店。技能与 batch 模式天然组合：清单里一行 `{"id":"cert-042","task":"用 invoice-maker 技能根据 orders-042.json 生成发票 invoices/042.pdf"}` 就能让一个隔离的 swarm worker 跑同一个技能。
+
+### 实战配方
+
+Linux 定时巡检（crontab）：
+```cron
+0 9 * * * autoclaw batch /opt/ops/daily.jsonl -y -n --resume >> /var/log/autoclaw.log 2>&1
+```
+
+Windows 计划任务：
+```bash
+schtasks /create /tn "AutoClaw Daily" /tr "autoclaw batch C:\ops\daily.jsonl -y -n" /sc daily /st 09:00
+```
+
+一个清单内的流水线——前一个任务写文件,后一个任务读：
+```jsonl
+{"id": "sweep", "task": "检查磁盘与关键服务状态,报告写入 report/sweep.md"}
+{"id": "notify", "task": "读取 report/sweep.md,用三句话总结后推送到飞书"}
+```
+
+新机器或 CI 环境自检：
+```bash
+autoclaw doctor   # 退出 0 = 就绪;退出 1 = 打印缺失项
+```
+
+### 自动确认 (CI/CD)
+自动批准所有工具执行（危险操作，请谨慎使用或在沙箱环境下运行）。
+```bash
+autoclaw "将 src/index.ts 重构为使用 ES 模块" -y
+```
+
+### CLI 选项
+- `-m, --model <model>`: 指定 LLM 模型 (默认: `gpt-5.6`)。
+- `-P, --provider <name>`: 使用 provider 预设 (见 [Provider 预设](#provider-预设))。
+- `-n, --no-interactive`: 处理完初始查询后退出 (无头模式)。
+- `-y, --yes`: 自动确认所有工具执行 (例如 Shell 命令)。
+- `--allow-dangerous`: 允许 `-y` 直接执行内置安全闸拦截的明显破坏性命令 (rm -rf、format、shutdown 等)。
+- `--json`: 在 stdout 输出 NDJSON 事件流 (供编排器使用,配合 `-n`)。
+
+### 诊断
+`autoclaw doctor` 无头完成全面自检,逐项打印 ✓/✗:配置文件、解析出的 provider/baseUrl/model、API key、真实连接测试、解析出的 shell、已注册工具、playwright 浏览器状态。退出 `0` = 就绪,`1` = 有关键项失败(会打印是哪项)。适合 CI 或新机器。
+
+### 沙箱
+命令执行可通过 `config.sandbox` / `AUTOCLOW_SANDBOX` 加以约束(词汇借鉴自 DeepSeek Harness):
+- `danger-full-access`(默认):命令不受约束地运行。
+- `workspace-write`:命令只能在当前工作目录和 `/tmp` 内写入。
+- `read-only`:命令无法在任何位置写入。
+
+后端:Linux 使用 bubblewrap(`apt install bubblewrap`),macOS 使用 `sandbox-exec`。**Windows 暂无后端**——非默认模式会"失败关闭"(直接拒绝命令并给出明确错误),而不是假装约束;在 Windows 上请暂用 `danger-full-access`。此词汇不约束读取与网络。
+- `--json`: 在 stdout 输出 NDJSON 事件流 (供编排器使用,配合 `-n`)。
+
+### Provider 预设
+AutoClaw 可对接任意 OpenAI 兼容端点。内置预设可自动填好 Base URL 和默认模型：
+```bash
+autoclaw -P deepseek "检查磁盘使用情况并保存报告" -y -n
+```
+可用预设：`openai`、`deepseek`、`moonshot` (Kimi)、`dashscope` (Qwen)、`zhipu` (GLM)、`ark` (火山方舟)、`siliconflow` (硅基流动)、`openrouter`、`ollama` (本地)。模型仍可用 `-m` 或配置覆盖。未设置 `OPENAI_API_KEY` 时，会自动读取各家自己的环境变量 (如 `DEEPSEEK_API_KEY`、`MOONSHOT_API_KEY`、`DASHSCOPE_API_KEY`、`ZHIPU_API_KEY`、`ARK_API_KEY`、`SILICONFLOW_API_KEY`、`OPENROUTER_API_KEY`)。
+
+## 配置
+
+AutoClaw 使用层级配置系统。
+
+**优先级排序 (从高到低):**
+1.  **CLI 参数**: (例如 `-m gpt-5.6`)
+2.  **环境变量**: (`OPENAI_API_KEY`, `.env` 文件)
+3.  **项目配置**: (当前目录下的 `./.autoclaw/setting.json`)
+4.  **全局配置**: (`~/.autoclaw/setting.json`)
+
+### 支持的配置键 (JSON)
+- `provider`: Provider 预设名 (如 `deepseek`)。
+- `apiKey`: 您的 OpenAI API 密钥。
+- `baseUrl`: 自定义 API 基础地址 (例如 DeepSeek 或本地 LLM)。
+- `model`: 默认使用的模型。
+- `maxSteps`: 单任务最大 LLM 轮数，超出后自动停止 (默认: `25`)。
+- `shellTimeout`: Shell 命令超时时间（毫秒）(默认: `120000`)。
+- `taskTimeoutMs`: 单任务整体墙钟超时（毫秒，默认关闭；会中断进行中的 API 调用并以 `timeout` 状态停止）。
+- `sandbox`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`；默认 `danger-full-access`）。
+- `skillsEnabled`: 设为 `false` 关闭技能系统（默认开启）。
+- `shell`: 强制 `execute_shell_command` 使用的 shell (`bash`、`powershell`、`cmd`、`sh`；默认自动检测——Windows 上优先 Git Bash > PowerShell > cmd)。
+- `tavilyApiKey`: Tavily 网页搜索的 API 密钥。
+- `smtpHost`, `smtpPort`, `smtpUser`, `smtpPass`, `smtpFrom`: SMTP 邮件设置。
+- `feishuWebhook`, `dingtalkWebhook`, `wecomWebhook`: 通知钩子地址。
+
+### 项目级配置示例
+在 `.autoclaw/setting.json` 创建文件：
+```json
+{
+  "model": "gpt-5.6",
+  "baseUrl": "https://api.deepseek.com/v1"
+}
+```
+
+> **⚠️ 安全警告**: 如果您在 `.autoclaw/setting.json` 中存储了 `apiKey` 或机密信息，请务必将 `.autoclaw/` 添加到您的 `.gitignore` 文件中，以防泄露！
+
+### 环境变量
+- `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`: 主模型设置。
+- `AUTOCLOW_PROVIDER`: 未传 `-P` 时使用的 provider 预设。
+- `AUTOCLOW_MAX_STEPS`, `AUTOCLOW_SHELL_TIMEOUT`: 稳定性限制（单任务最大轮数；Shell 超时毫秒数）。
+- `AUTOCLOW_TASK_TIMEOUT_MS`: 单任务整体墙钟超时（毫秒）。
+- `AUTOCLOW_SANDBOX`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`）。
+- `AUTOCLOW_SHELL`: 强制 shell 命令使用的 shell (`bash`、`powershell`、`cmd`、`sh`)。
+- `AUTOCLOW_INCLUDE_USAGE`: 设为 `1`/`true` 时向 API 请求 token 用量（可选开启）。
+- `TAVILY_API_KEY`, `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASS`, `FEISHU_WEBHOOK`/`FEISHU_KEYWORD`, `DINGTALK_WEBHOOK`/`DINGTALK_KEYWORD`, `WECOM_WEBHOOK`/`WECOM_KEYWORD`: 工具凭据，可作为 setup 的替代方式。
+
+## 集成功能
+
+### 网页搜索 (Tavily)
+如果您在设置中提供了 Tavily API 密钥，AutoClaw 可以搜索网页。
+- **示例**: "搜索最新的 Node.js 发布说明。"
+
+### 邮件 (SMTP)
+配置 SMTP 设置以允许 Agent 发送邮件。
+- **示例**: "向 user@example.com 发送一封包含日志文件摘要的邮件。"
+
+### 通知 (飞书/钉钉/企业微信)
+配置 Webhook 以在团队聊天应用中接收警报或报告。
+- **示例**: "在飞书上通知团队构建已完成。"
+
+### 日期与时间
+内置工具为 Agent 提供当前系统时间，确保准确处理相对时间请求。
+- **示例**: "今天是几号？" 或 "提醒我下周一检查日志。"
+
+### 确定性渲染 (Takumi)
+`render_image` 将 HTML 模板渲染为精确的图像——PNG、JPEG、WebP 或矢量 SVG——全程离线，不依赖浏览器或 AI 模型。`render_pdf` 将 HTML 模板渲染为分页 PDF，文字可选中，页眉/页脚逐页重复，并支持 `<span class="pageNumber">` / `<span class="totalPages">` 页码计数。模板样式支持内联 CSS、`<style>` 块，或通过 `tw` 属性使用 Tailwind v4 工具类（`<div tw="w-full h-full bg-blue-500">`）；普通 `class` 属性仅匹配常规 CSS 选择器。两个工具都会自动探测常见系统字体（含中日韩与 Emoji）；也可通过 `font_paths` 注册指定字体文件。
+
+典型工作流——用自然语言描述任务，模板由 agent 自己编写：
+
+```bash
+# 博客 SEO:为每篇文章生成 OG 分享图
+autoclaw "读取 content/posts/ 下每篇 .md 的标题和摘要,为每篇文章渲染一张 OG 分享图(1200x630)到 public/og/" -y -n
+
+# 财务/电商:从订单表批量生成 PDF 发票并邮件发送
+autoclaw "读取 orders.csv,为每个订单生成 PDF 发票保存到 invoices/(A4,页脚带页码),然后把每张发票邮件发送给该行记录的客户邮箱" -y
+
+# 培训/HR:为学员名单批量生成结业证书
+autoclaw "读取 attendees.json,为每位学员渲染一张结业证书(1414x1000)保存到 certs/,编号从 AC-2026-0001 起" -y -n
+
+# cron/CI 定时报告:输出确定——相同输入得到完全相同的 PDF,可做校验
+autoclaw "汇总本周 nginx 访问日志,生成一页 A4 的 PDF 流量周报(含指标表格),保存为 report.pdf" -y -n
+```
+
+集群规模用 batch 模式——每个任务在隔立的 agent 中渲染:
+
+```bash
+cat > render-jobs.jsonl <<'EOF'
+{"id": "og-001", "task": "为 post-001.md 渲染 OG 分享图到 public/og/001.png"}
+{"id": "og-002", "task": "为 post-002.md 渲染 OG 分享图到 public/og/002.png"}
+EOF
+autoclaw batch render-jobs.jsonl -y -c 4
+```
+
+选型提示:需要精确文字、排版与品牌一致性(卡片、横幅、徽章、文档)时用 `render_image` / `render_pdf`;艺术创作、照片类图像用 `generate_image`。模板中的 Emoji 默认从 Twemoji CDN 在线获取,完全离线的环境请让模板保持纯文本。
+
+可运行案例与渲染效果预览:[examples/render](examples/render/README.zh-CN.md)(OG 分享卡、社媒海报、KPI 指标卡、周报 PDF、SVG 徽章、证书、动图、多页采购订单——`agent-run/` 下还有一次真实 agent 无头运行的产物)。同一能力也打包成了可移植的 [WorkBuddy 技能](skills/code2media/SKILL.md)(`code2media-skill-1.2.1.zip`):一个独立 Node 脚本,任何装有 Node >= 20.19 的机器都能把 HTML 渲染成图片/SVG/PDF/动图。
+
+## Docker 支持
+
+### 构建与运行
+仓库自带多阶段构建的 `Dockerfile`（node:22-alpine，跳过浏览器下载保持镜像苗条）。容器内直接运行无头一次性任务，配合目录挂载操作当前目录：
+```bash
+docker build -t autoclaw .
+docker run --rm -v "$PWD":/workspace -w /workspace -e OPENAI_API_KEY=sk-... autoclaw "检查磁盘使用情况并保存报告" -y -n
+```
+注意：默认镜像中未内置浏览器，基于浏览器的工具（`read_website` / `take_screenshot`）不可用——它们会返回友好的安装提示，而不是报错崩溃。
+
+### 截图与渲染输出中的中文显示问题
+在 Docker 容器（尤其是 Alpine 或 Debian Slim）中运行时，网页截图中的中文可能会显示为方块（"豆腐块"）。表情符号（如 🔥）也可能显示为方块。`render_image` / `render_pdf` 输出中包含中日韩文字时同样受影响。
+
+**解决方案:** 在容器中安装 CJK（中日韩）和 Emoji 字体。渲染工具会自动探测同一批字体路径，因此安装这些字体包可以同时修复截图与渲染输出的中文显示。
+
+**Debian/Ubuntu:**
+```bash
+apt-get update && apt-get install -y fonts-noto-cjk fonts-wqy-zenhei fonts-noto-color-emoji
+```
+
+**Alpine Linux:**
+```bash
+apk add font-noto-cjk font-noto-emoji
+```
+
+## 开源协议
+
+MIT
+
+## 贡献指南
+
+欢迎贡献！请随时提交 Pull Request。
+
+1.  Fork 本项目
+2.  创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
+3.  提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
+4.  推送至分支 (`git push origin feature/AmazingFeature`)
+5.  开启一个 Pull Request
+
+---
 GitHub: [https://github.com/tsingliuwin/autoclaw](https://github.com/tsingliuwin/autoclaw)

package/dist/skills.js

@@ -110,7 +110,7 @@ export function buildSkillsManifest(config, scopes) {
     const visible = skills.filter(s => s.disableModelInvocation !== true);
     if (visible.length === 0)
         return null;
-    const lines = visible.map(s => `- ${s.name}${s.version ? ` (v${s.version})` : ''}: ${truncate(s.description, 160)} [read ${s.skillMdPath}]`);
+    const lines = visible.map(s => `- ${s.name}${s.version ? ` (v${s.version})` : ''}: ${truncate(s.description, 400)} [read ${s.skillMdPath}]`);
     return [
         'INSTALLED SKILL PACKAGES (procedural capabilities bundling instructions, scripts and templates).',
         'When a task matches a skill, first read its SKILL.md and follow it — skills run through your normal file and shell tools, no special API:',
@@ -246,7 +246,7 @@ export function removeSkill(name, opts) {
     fs.rmSync(dir, { recursive: true, force: true });
     return 'removed';
 }
-// ---- pack (store-upload artifact: zip with skills/<name>/ at its root) ----
+// ---- pack (store-upload artifact: SKILL.md sits at the zip root) ----
 export function packSkill(dir, outPath) {
     const abs = path.resolve(dir);
     const skillMdPath = path.join(abs, 'SKILL.md');
@@ -254,8 +254,10 @@ export function packSkill(dir, outPath) {
         throw new Error(`${abs} is not a skill (no SKILL.md)`);
     const parsed = parseSkillMd(fs.readFileSync(skillMdPath, 'utf-8'));
     const name = parsed?.frontmatter.name || path.basename(abs);
-    if (!/^[A-Za-z0-9._-]+$/.test(name))
+    if (!isSafeSkillName(name))
         throw new Error(`unsafe skill name: ${name}`);
+    const version = parsed?.frontmatter.version;
+    const versionTag = version ? version.replace(/[^A-Za-z0-9._-]/g, '-') : undefined;
     const files = [];
     const walk = (current, rel) => {
         for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
@@ -266,11 +268,11 @@ export function packSkill(dir, outPath) {
             if (entry.isDirectory())
                 walk(child, childRel);
             else if (entry.isFile())
-                files.push({ path: `skills/${name}/${childRel}`, data: fs.readFileSync(child) });
+                files.push({ path: childRel, data: fs.readFileSync(child) });
         }
     };
     walk(abs, '');
-    const zipPath = outPath || path.resolve(process.cwd(), `${name}-skill.zip`);
+    const zipPath = outPath || path.resolve(process.cwd(), versionTag ? `${name}-skill-${versionTag}.zip` : `${name}-skill.zip`);
     fs.writeFileSync(zipPath, createZip(files));
-    return { zipPath, fileCount: files.length, name };
+    return { zipPath, fileCount: files.length, name, version };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autoclaw",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -57,7 +57,7 @@
     "dotenv": "^16.4.7",
     "inquirer": "^13.2.2",
     "jsdom": "^28.0.0",
-    "nodemailer": "^8.0.0",
+    "nodemailer": "^9.1.1",
     "openai": "^6.18.0",
     "ora": "^9.3.0",
     "playwright": "^1.58.2",
@@ -68,7 +68,7 @@
     "@types/inquirer": "^9.0.9",
     "@types/jsdom": "^27.0.0",
     "@types/node": "^25.2.1",
-    "@types/nodemailer": "^7.0.9",
+    "@types/nodemailer": "^8.0.1",
     "@vitest/coverage-v8": "^4.1.11",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",

package/skills/code2media/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: code2media
-display_name: 代码转多媒体（HTML → 图片/PDF/动图）
-display_name_en: Code to Media (HTML → images/PDF/animations)
-description: Universal renderer — turn any HTML into pixel-perfect PNG/JPEG/WebP images, vector SVG, paged PDFs and animated WebP/GIF. Offline, no browser. Use when the user wants to 把内容/代码/数据变成图片或PDF, 生成图片/OG图/徽章/数据卡片/动图, 生成PDF/报告/发票/工单, or render HTML to image or PDF. For deep scenario optimization see sibling skills (posters, invoices, certificates).
-description_zh: 通用多媒体渲染:把任意 HTML 变成精确的图片(PNG/JPEG/WebP)、矢量 SVG、分页 PDF 和动图(WebP/GIF)。离线渲染,无需浏览器,毫秒级出图,文字排版 100% 精确。通用兜底;海报/发票/证书等具体场景有专属技能时优先用专属技能。
-description_en: Universal multimedia renderer — any HTML becomes precise images (PNG/JPEG/WebP), vector SVG, paged PDFs and animations (WebP/GIF). Offline, no browser, millisecond-per-render. General fallback; prefer dedicated scenario skills (posters, invoices, certificates) when available.
+display_name: 代码转多媒体
+display_name_en: Code to Media
+description: "Universal media renderer with no fixed template — any custom layout, size or style becomes pixel-perfect images (PNG/JPEG/WebP), vector SVG, paged PDFs or animations (WebP/GIF). Use when no dedicated scenario skill fits: 自定义图形/任意尺寸图片/数据图表卡片/一次性版式/长文转PDF/出动图/GIF动画/内容可视化. Do not use for posters or covers (poster-maker) or invoices/quotes/receipts (invoice-maker)."
+description_zh: 通用多媒体渲染:不限模板、尺寸与风格,把内容渲染成精确的图片、矢量 SVG、分页 PDF 和动图。离线渲染,无需浏览器,毫秒级出图,文字排版 100% 精确。
+description_en: The universal media renderer — no fixed templates, any layout, size or style, rendered as precise images, vector SVG, paged PDFs and animations. Offline, no browser, millisecond-per-render.
 category: image
-version: 1.2.0
+version: 1.2.2
 author: AutoClaw
 ---
 

package/skills/invoice-maker/SKILL.md

@@ -2,11 +2,11 @@
 name: invoice-maker
 display_name: 发票生成器（报价单/收据/采购单）
 display_name_en: Invoice Maker (quotes, receipts, purchase orders)
-description: Generate formal business documents as paged PDFs — invoices, quotes, purchase orders, receipts, statements — with proper tables, tax lines, page numbers and bilingual layouts. Use when the user wants to 开发票/生成发票/报价单/收据/采购单/对账单/账单/付款通知 or make an invoice/quote/receipt PDF.
+description: 开发票/生成发票/报价单/收据/采购单/对账单/账单/付款通知 — formal business documents as paged PDFs with proper tables, right-aligned amounts, tax lines, repeating headers and page-number footers. Offline, batch-ready, bilingual layouts.
 description_zh: 生成正式商务票据 PDF:发票、报价单、收据、采购单、对账单、账单。金额右对齐、税行规范、表格跨页表头重复、页码页脚,中英双语排版可选。离线毫秒级渲染,支持按订单数据批量出票。
 description_en: Generate formal business document PDFs — invoices, quotes, purchase orders, receipts, statements. Right-aligned amounts, tax lines, repeating table headers across pages, page-number footers, optional bilingual layouts. Offline, batch-ready.
 category: office
-version: 1.0.0
+version: 1.0.1
 author: AutoClaw
 ---
 

package/skills/poster-maker/SKILL.md

@@ -2,11 +2,11 @@
 name: poster-maker
 display_name: 海报生成器（社媒封面/分享卡/OG图）
 display_name_en: Poster Maker (social covers, share cards, OG images)
-description: Generate social-ready visual posters, WeChat article covers, OG/share cards and community post images with big-type layouts and brand gradients — pixel-exact, offline. Use when the user wants to 生成海报/做海报/公众号封面/小红书配图/朋友圈配图/OG图/分享卡/头图/横幅/banner/封面图.
+description: 生成海报/做海报/公众号封面/小红书配图/朋友圈配图/OG图/分享卡/头图/横幅/banner — social-ready posters, covers and share cards with big-type layouts, brand gradients and platform size specs. Pixel-exact, offline, no browser.
 description_zh: 生成社媒视觉物料:海报、公众号封面、小红书/朋友圈配图、OG 分享卡、头图、横幅。大字排版 + 品牌渐变,像素精确、离线毫秒级出图,内置封面/OG/方图等现成模板与尺寸规范。
 description_en: Generate social-ready posters, article covers, OG/share cards and banners with big-type layouts and brand gradients. Pixel-exact, offline, milliseconds per render, with ready-made templates and platform size specs.
 category: image
-version: 1.0.0
+version: 1.1.1
 author: AutoClaw
 ---
 
@@ -24,15 +24,33 @@ author: AutoClaw
 
 | 场景 | 尺寸 | 模板 |
 | :--- | :--- | :--- |
-| 小红书/朋友圈方图 | 1080 × 1080 | `social-post.html` |
+| 小红书封面(3:4 占屏最大) | 1080 × 1440 | `social-post.html` 改尺寸 |
+| 朋友圈/通用方图 | 1080 × 1080 | `social-post.html` |
 | 公众号首图封面 | 900 × 383 | `cover.html` |
 | 博客/官网 OG 分享卡 | 1200 × 630 | `og-card.html` |
 | 竖版海报(印刷感) | 1080 × 1440 | 改方图模板尺寸即可 |
 | 视频封面 | 1280 × 720 | 改封面模板尺寸即可 |
 
+> 小红书只支持 1:1、3:4、4:3 三种比例,3:4 观感最好;多图笔记的配图先统一尺寸,否则系统自动补白边。
+
+## 场景速查
+
+不同场景的构图、配色和视觉重心完全不同,先对号入座(信息层级与易错点详见 `@references/scenario-playbook.md`):
+
+| 场景 | 构图 | 配色 | 第一视觉 |
+| :--- | :--- | :--- | :--- |
+| 促销/电商 | 左对齐或强分裂 | 红橙黄高饱和 | 折扣/价格数字 |
+| 活动/会议 | 居中 | 主题色+深底 | 活动名 |
+| 招聘 | 左对齐 | 品牌蓝/绿 | 岗位名+薪资 |
+| 餐饮/美食 | 图左文右 | 暖色(红橙黄) | 菜品实拍 |
+| 节日/节气 | 居中 | 传统配色 | 节日符号+大字 |
+| 知识/课程 | 左对齐 | 低饱和+强调色 | 收益式标题 |
+| 地产/政务 | 居中 | 蓝金/红金/深灰 | 机构名或主标 |
+| 品牌/发布 | 大面积留白 | 深色高级感 | 产品本身 |
+
 ## 工作流程
 
-1. **选模板**:从 `templates/` 选最接近的,把文案/配色/品牌元素替换掉。没有合适的就从零写。
+1. **定场景、选模板**:先确定海报场景(促销/活动/招聘/节日…),按上方速查表定构图与配色;再从 `templates/` 选最接近的,把文案/配色/品牌元素替换掉。没有合适的就从零写。
 2. **写 HTML**:语法三条铁律(详见 `@references/syntax-guide.md`):
    - Tailwind 工具类写 **`tw` 属性**(`class` 不编译 Tailwind);
    - 用 v4 规范名(渐变 `bg-linear-to-br`,不是 `bg-gradient-to-br`);
@@ -47,10 +65,13 @@ author: AutoClaw
 
 - **文字层级 ≤ 3 级**:主标题(最大)/副标题/说明文字,一眼能分清主次;主标题占画面高度 ≥ 1/5
 - **留白要狠**:内边距不小于画布短边的 5%(如 1080 宽至少 54px);元素之间用 `gap`/`mt` 拉开呼吸感
-- **对比度**:文字与背景必须有足够对比;浅色文字配深色渐变,或深色文字配浅色底
+- **对比度**:文字与背景必须有足够对比;浅色文字配深色渐变,或深色文字配浅色底;文字压图三招(挪干净处/背景压暗/色块描边)见场景手册
+- **配色 ≤ 3 种**:主色+辅助色+强调色;拿不准就用品牌色的深浅渐变家族
+- **分组要明显**:相关元素贴近、无关元素拉远,组间距差距 ≥ 2 倍,一眼扫出信息块
 - **中文不斜体**(斜体在无衬线中文里很丑),强调用加粗/变色/字号
 - **一图一重点**:不要把所有信息塞进一张图;胶囊标签 ≤ 3 个
 - **品牌一致性**:有品牌色/Logo 就放角标位,颜色用品牌色的渐变家族
+- **渲染后目检样式**:某元素样式没生效(字号/间距突然不对),先查是否把工具类写进了 `class`——工具类必须写 `tw`,`class` 里的会静默失效不报错
 - 字体:`style="font-family:msyh,NotoSansCJK-Regular,wqy-zenhei"`,离线环境 Emoji 保持纯文本
 
 ## 批量与变体

package/skills/poster-maker/references/scenario-playbook.md

@@ -0,0 +1,85 @@
+# 场景化海报手册
+
+SKILL.md 的质量清单管"合格",本手册管"像行家"。顺序:先定场景 → 套构图与配色 → 按信息层级填内容 → 用易错点自检。
+
+## 构图公式
+
+九个排版公式其实是一族:**对齐轴(居中/左/右) × 图文关系(底图衬托 / 图文上下对称 / 图片穿插)**。
+
+- **居中对齐**:正式、庄重 → 政务公告、地产、节日、发布会邀请
+- **左对齐**:信息量大、阅读效率最高,中文海报的默认首选 → 促销、招聘、知识类
+- **右对齐**:常配"图左文右"的变体 → 美食、产品特写
+- 图文占比:5:5 均势或 3:7 主次;说明性小字(时间地点备注等)可以不守栅格
+- 同一公式换图、换配色、换字体组合,气质完全不同——先套公式定骨架,再换皮调气质
+
+## 场景速查
+
+| 场景 | 构图 | 配色 | 第一视觉 |
+| :--- | :--- | :--- | :--- |
+| 促销/电商 | 左对齐或强分裂 | 红橙黄高饱和 | 折扣/价格数字 |
+| 活动/会议 | 居中 | 主题色+深底 | 活动名 |
+| 招聘 | 左对齐 | 品牌蓝/绿 | 岗位名+薪资 |
+| 餐饮/美食 | 图左文右或大图打底 | 暖色(红橙黄) | 菜品实拍 |
+| 节日/节气 | 居中 | 传统配色 | 节日符号+大字 |
+| 知识/课程 | 左对齐 | 低饱和底+一个强调色 | 收益式标题 |
+| 地产/政务公告 | 居中 | 蓝金/红金/深灰 | 机构名或主标 |
+| 品牌/产品发布 | 大面积留白 | 深色高级感或纯白 | 产品本身 |
+
+## 各场景信息层级与易错点
+
+信息层级按"→"递减,排前面的必须视觉最大。
+
+**促销/电商**
+- 层级:活动主标 → 到手价/折扣 → 限时词(限时/秒杀/仅剩 N 件) → 商品图 → 二维码
+- 价格锚定:原价划线做锚点,到手价放大加粗,对比越直白数字越有效
+- 易错:折扣数字不够大(它是唯一主角);原价没划线;商品图堆太多张
+
+**活动/会议/演出**
+- 层级:活动名 → 时间 → 地点 → 票价/报名方式 → 主办方
+- 时间地点是报名转化的命门,字号不能小于主标的一半
+- 易错:时间地点埋进底部小字;缺报名入口(二维码/链接)
+
+**招聘**
+- 层级:公司(Logo 信任位) → 岗位名(最大) → 薪资范围+城市 → 福利亮点(胶囊标签 ≤3) → 投递二维码
+- 蓝绿传达稳定信任;信息真实比浮夸更重要,虚假薪资毁品牌
+- 易错:不写薪资范围;二维码太小扫不出;岗位堆超过 3 个
+
+**餐饮/美食**
+- 层级:菜品实拍 → 品名 → 卖点(鲜/辣/手作) → 价格/优惠 → 门店与营业时间
+- 暖色刺激食欲;图片必须高饱和明亮,发灰的图直接毁掉整张海报
+- 易错:菜品太多塞满画面(一图 1-3 道招牌即可);用冷色调
+
+**节日/节气**
+- 层级:节日名+符号 → 情绪文案 → 放假安排/活动信息 → 品牌角标
+- 传统配色有惯性:春节红金、中秋蓝金月白、圣诞红绿、端午粽绿;放错色系会很怪
+- 易错:放假日期不标调休;装饰元素抢过文字;用了与节日无关的符号
+
+**知识/课程/讲座**
+- 层级:收益式标题("7 天学会 XX",不是课程名) → 讲师/机构背书 → 数字背书(课时/学员数/年限) → 时间与报名码
+- 低饱和底色+一个强调色,显得克制可信
+- 易错:标题写课程名不写用户收益;背书数字造假
+
+**地产/政务/正式公告**
+- 层级:机构名/主标 → 事项 → 时间地点 → 落款+日期
+- 居中构图、稳重字体、大量留白;蓝金/红金显庄重
+- 易错:花哨字体和撞色;缺落款或日期
+
+**品牌/产品发布**
+- 层级:产品图/产品名 → 一句话卖点 → 发布时间 → 品牌角标
+- 深色底或纯白+大留白,文案越少越高级;产品即主角
+- 易错:卖点罗列超过一条;文字抢过产品
+
+## 社媒封面规范
+
+- **小红书**:只支持 1:1、3:4、4:3 三种比例,**3:4(1080×1440)占屏最大、观感最好**,做封面默认选它;标题大字+亮色关键字;同一账号封面风格统一(影响人设与推荐流量);多图笔记所有配图先统一尺寸,否则系统自动补白边
+- **公众号首图(900×383)**:在手机信息流里是缩略图,标题 3-8 字、元素 ≤2 个,缩小到拇指大小仍要可读
+- **OG 分享卡(1200×630)**:文字占比 ≤20%,品牌角标固定一角,链接预览里它只有指甲盖大
+- **视频封面(1280×720)**:主标题放左侧 1/3(右侧常被时长标签遮挡)
+
+## 文字压图三招
+
+文字必须叠在图片上时(识别性原则):① 放到背景干净简单的地方;② 背景压暗、模糊或统一色调;③ 文字底部加不透明色块,或给文字加描边/投影。黑底配白字/黄字对比最强。
+
+---
+
+经验来源:2026-09 调研——Canva 设计学院《海报设计 5 大原则》《9 个万能公式解决海报排版》《小红书封面尺寸》,主流活动平台信息规范,促销定价的行为经济学常识(锚定效应)。