op7418

Open Source

CodePilot

<img src="docs/icon-readme.png" width="32" height="32" alt="CodePilot" style="vertical-align: middle; margin-right: 8px;" /> CodePilot === **A multi-model AI agent desktop client** -- connect any AI provider, extend with MCP & skills, control from your phone, and let your assistant learn your workflow. [![GitHub release](https://img.shields.io/github/v/release/op7418/CodePilot)](https://github.com/op7418/CodePilot/releases) [![Downloads](https://img.shields.io/github/downloads/op7418/CodePilot/total)](https://github.com/op7418/CodePilot/releases) [![GitHub stars](https://img.shields.io/github/stars/op7418/CodePilot)](https://github.com/op7418/CodePilot/stargazers) [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com/op7418/CodePilot/releases) [![License](https://img.shields.io/badge/license-BSL--1.1-orange)](LICENSE) [中文文档](./README_CN.md) | [日本語](./README_JA.md) --- ![CodePilot](https://github.com/user-attachments/assets/9750450a-9f6f-49ce-acd4-c623a4e24281) --- [Download](#download) | [Quick Start](#quick-start) | [Documentation](#documentation) | [Contributing](#contributing) | [Community](#community) --- ## Download | Platform | Download | Architecture | |---|---|---| | macOS | [Apple Silicon (.dmg)](https://github.com/op7418/CodePilot/releases/latest) · [Intel (.dmg)](https://github.com/op7418/CodePilot/releases/latest) | arm64 / x64 | | Windows | [Installer (.exe)](https://github.com/op7418/CodePilot/releases/latest) | x64 + arm64 | | Linux | Build from source | x64 + arm64 | Or visit the [Releases](https://github.com/op7418/CodePilot/releases) page for all versions. --- ## Why CodePilot ### Multi-provider, one interface Connect to **17+ AI providers** out of the box. Switch providers and models mid-conversation without losing context. | Category | Providers | |---|---| | Direct API | Anthropic, OpenRouter | | Cloud platforms | AWS Bedrock, Google Vertex AI | | Chinese AI providers | Zhipu GLM (CN/Global), Kimi, Moonshot, MiniMax (CN/Global), Volcengine Ark (Doubao), Xiaomi MiMo, Aliyun Bailian (Qwen) | | Local & self-hosted | Ollama, LiteLLM | | Custom | Any Anthropic-compatible or OpenAI-compatible endpoint | | Media | Google Gemini (image generation) | ### Beyond coding — a full AI agent CodePilot started as a coding tool but has grown into a **general-purpose AI agent desktop**: - **Assistant Workspace** — Persona files, persistent memory, onboarding flows, and daily check-ins. Your assistant learns your preferences and adapts over time. - **Generative UI** — AI can create interactive dashboards, charts, and visual widgets rendered live in-app. - **Remote Bridge** — Connect to Telegram, Feishu, Discord, QQ, and WeChat. Send messages from your phone, get responses on your desktop. - **MCP + Skills** — Add MCP servers (stdio / sse / http) with runtime monitoring. Define reusable skills or install from the skills.sh marketplace. - **Media Studio** — AI image generation with batch tasks, gallery, and tagging. - **Task Scheduler** — Schedule recurring tasks with cron expressions or intervals. ### Built for daily use - Pause, resume, and **rewind sessions to any checkpoint** - **Split-screen** dual sessions side by side - Track **token usage and costs** with daily charts - Import Claude Code CLI session history - Dark / Light theme toggle - English + Chinese interface --- ## Quick Start ### Path A: Download a release (most users) 1. Download the installer for your platform from the [Download](#download) section above 2. Launch CodePilot 3. **Configure a Provider** in **Settings > Providers** — add your API key for any supported provider 4. Start a conversation > **Note:** Installing the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) (`npm install -g @anthropic-ai/claude-code`) unlocks additional capabilities like direct file editing, terminal commands, and git operations. It is recommended but not required for basic chat. ### Path B: Build from source (developers) | Prerequisite | Minimum version | |---|---| | Node.js | 18+ | | npm | 9+ (ships with Node 18) | ```bash git clone https://github.com/op7418/CodePilot.git cd CodePilot npm install npm run dev # browser mode at http://localhost:3000 # -- or -- npm run electron:dev # full desktop app ``` --- ## Core Capabilities ### Conversation & Interaction | Capability | Details | |---|---| | Interaction modes | Code / Plan / Ask | | Reasoning effort | Low / Medium / High / Max + Thinking mode | | Permission control | Default / Full Access, per-action approval | | Session control | Pause, resume, rewind to checkpoint, archive | | Model switching | Change model mid-conversation | | Split screen | Side-by-side dual sessions | | Attachments | Files and images with multimodal vision support | | Slash commands | /help /clear /cost /compact /doctor /review and more | ### Extensions & Integrations | Capability | Details | |---|---| | Providers | 17+ providers: Anthropic, OpenRouter, Bedrock, Vertex, Zhipu GLM, Kimi, Moonshot, MiniMax, Volcengine, MiMo, Bailian, Ollama, LiteLLM, custom endpoints | | MCP servers | stdio / sse / http, runtime status monitoring | | Skills | Custom / project / global skills, skills.sh marketplace | | Bridge | Telegram / Feishu / Discord / QQ / WeChat remote control | | CLI import | Import Claude Code CLI .jsonl session history | | Image generation | Gemini image gen, batch tasks, gallery | ### Data & Workspace | Capability | Details | |---|---| | Assistant Workspace | Persona files (soul.md, user.md, claude.md, memory.md), onboarding, daily check-ins, persistent memory | | Generative UI | AI-created interactive dashboards and visual widgets | | File browser | Project file tree with syntax-highlighted preview | | Git panel | Status, branches, commits, worktree management | | Usage analytics | Token counts, cost estimates, daily usage charts | | Task scheduler | Cron-based and interval scheduling with persistence | | Local storage | SQLite (WAL mode), all data stays on your machine | | i18n | English + Chinese | | Themes | Dark / Light, one-click toggle | --- ## First Launch 1. **Configure a Provider** — Go to **Settings > Providers** and add credentials for the provider you want to use. CodePilot includes presets for all major providers — just pick one and enter your API key. 2. **Create a conversation** — Pick a working directory, select a mode (Code / Plan / Ask), and choose a model. 3. **Set up Assistant Workspace** (optional) — Go to **Settings > Assistant**, choose a workspace directory, and enable Onboarding. CodePilot creates `soul.md`, `user.md`, `claude.md`, and `memory.md` at the workspace root. 4. **Add MCP servers** (optional) — Go to the **MCP** page in the sidebar to add and manage MCP servers. Custom skills are managed on the separate **Skills** page. 5. **Install Claude Code CLI** (optional) — For advanced features like file editing and terminal commands, install the CLI: `npm install -g @anthropic-ai/claude-code` --- ## Platform & Installation Notes macOS builds are code-signed with a Developer ID certificate but not notarized, so Gatekeeper may still prompt on first launch. Windows and Linux builds are unsigned. <details> <summary>macOS: Gatekeeper warning on first launch</summary> **Option 1** -- Right-click `CodePilot.app` in Finder > Open > confirm. **Option 2** -- System Settings > Privacy & Security > scroll to Security > click Open Anyway. **Option 3** -- Run in Terminal: ```bash xattr -cr /Applications/CodePilot.app ``` </details> <details> <summary>Windows: SmartScreen blocks the installer</summary> **Option 1** -- Click "More info" on the SmartScreen dialog, then "Run anyway". **Option 2** -- Settings > Apps > Advanced app settings > set App Install Control to allow apps from anywhere. </details> --- ## Documentation 📖 **Full documentation:** [English](https://www.codepilot.sh/docs) | [中文](https://www.codepilot.sh/zh/docs) **Getting started:** - [Quick Start](#quick-start) -- Download or build from source - [First Launch](#first-launch) -- Provider setup, workspace configuration - [Installation Guide](https://www.codepilot.sh/docs/installation) -- Detailed setup instructions **User guides:** - [Providers](https://www.codepilot.sh/docs/providers) -- Configuring AI providers and custom endpoints - [MCP Servers](https://www.codepilot.sh/docs/mcp) -- Adding and managing Model Context Protocol servers - [Skills](https://www.codepilot.sh/docs/skills) -- Custom skills, project skills, and the skills.sh marketplace - [Bridge](https://www.codepilot.sh/docs/bridge) -- Remote control via Telegram, Feishu, Discord, QQ, WeChat - [Assistant Workspace](https://www.codepilot.sh/docs/assistant-workspace) -- Persona files, onboarding, memory, daily check-ins - [FAQ](https://www.codepilot.sh/docs/faq) -- Common issues and solutions **Developer docs:** - [ARCHITECTURE.md](./ARCHITECTURE.md) -- Architecture, tech stack, directory structure, data flow - [docs/handover/](./docs/handover/) -- Design decisions and handover documents - [docs/exec-plans/](./docs/exec-plans/) -- Execution plans and tech debt tracker --- ## FAQ <details> <summary>Do I need the Claude Code CLI?</summary> No. You can use CodePilot with any supported provider (OpenRouter, Zhipu GLM, Volcengine, Ollama, etc.) without the Claude Code CLI. The CLI is only needed if you want Claude to directly edit files, run terminal commands, or use git operations on your machine. For chat and assistant features, just configure a provider and start a conversation. </details> <details> <summary>Configured a Provider but no models appear</summary> Verify the API key is valid and the endpoint is reachable. Some providers (Bedrock, Vertex) require additional environment variables or IAM configuration beyond the API key. Use the built-in diagnostics (**Settings > Providers > Run Diagnostics**) to check connectivity. </details> <details> <summary>What is the difference between <code>npm run dev</code> and <code>npm run electron:dev</code>?</summary> `npm run dev` starts only the Next.js dev server -- you use CodePilot in your browser at `http://localhost:3000`. `npm run electron:dev` starts both Next.js and the Electron shell, giving you the full desktop app experience with native window controls. </details> <details> <summary>Where are the Assistant Workspace files?</summary> When you set up a workspace, CodePilot creates four Markdown files at the **workspace root directory**: `soul.md` (personality), `user.md` (user profile), `claude.md` (rules), and `memory.md` (long-term notes). State tracking (onboarding progress, check-in dates) is stored in the `.assistant/` subdirectory. Daily memories go to `memory/daily/`. </details> <details> <summary>Bridge requires additional setup per platform</summary> Each Bridge channel (Telegram, Feishu, Discord, QQ, WeChat) requires its own bot token or app credentials. Go to the **Bridge** page in the sidebar to configure channels. You will need to create a bot on the target platform first and provide the token to CodePilot. </details> --- ## Community <img src="docs/wechat-group-qr.png" width="240" alt="WeChat Group QR Code" /> Scan the QR code to join the WeChat user group for discussions, feedback, and updates. - [GitHub Issues](https://github.com/op7418/CodePilot/issues) -- Bug reports and feature requests - [GitHub Discussions](https://github.com/op7418/CodePilot/discussions) -- Questions and general discussion --- ## Contributing 1. Fork the repository and create a feature branch 2. `npm install` and `npm run electron:dev` to develop locally 3. Run `npm run test` before opening a PR 4. Submit a PR against `main` with a clear description Keep PRs focused -- one feature or fix per pull request. <details> <summary>Development commands</summary> ```bash npm run dev # Next.js dev server (browser) npm run electron:dev # Full Electron app (dev mode) npm run build # Production build npm run electron:build # Build Electron distributable npm run electron:pack:mac # macOS DMG (arm64 + x64) npm run electron:pack:win # Windows NSIS installer npm run electron:pack:linux # Linux AppImage, deb, rpm (local build only — not a GitHub Release download) ``` **CI/CD:** Pushing a `v*` tag builds the macOS and Windows packages and creates a GitHub Release automatically. Linux is not part of the release build — build it locally with `npm run electron:pack:linux`. **Notes:** - Electron forks a Next.js standalone server on `127.0.0.1` with a random free port - Chat data is stored in `~/.codepilot/codepilot.db` (dev mode: `./data/`) - SQLite uses WAL mode for fast concurrent reads </details> --- ## License [Business Source License 1.1 (BSL-1.1)](LICENSE) - **Personal / academic / non-profit use**: free and unrestricted - **Commercial use**: requires a separate license — contact [@op7418 on X](https://x.com/op7418) - **Change date**: 2029-03-16 — after which the code converts to Apache 2.0

AI Agents Code Editors & IDEs

6K Github Stars

Open Source

guizang-ppt-skill

# Guizang PPT Skill · 网页 PPT / 配图 / 封面 ![GitHub stars](https://img.shields.io/github/stars/op7418/guizang-ppt-skill?style=flat-square) ![License](https://img.shields.io/github/license/op7418/guizang-ppt-skill?style=flat-square) ![Skill](https://img.shields.io/badge/Skill-Agent-111111?style=flat-square) ![HTML Deck](https://img.shields.io/badge/HTML-Deck-0A7CFF?style=flat-square) ![Claude Code](https://img.shields.io/badge/Claude%20Code-Supported-6B5B95?style=flat-square) ![Codex](https://img.shields.io/badge/Codex-Supported-222222?style=flat-square) [![由真格 Token Grant 资助](https://img.shields.io/static/v1?label=%E7%94%B1%E7%9C%9F%E6%A0%BC%20Token%20Grant&message=%E8%B5%84%E5%8A%A9&color=FF4D00&style=flat-square)](https://zhenfund.feishu.cn/share/base/form/shrcn1lAANF659o7EpWnxlR1VOh?sessionid=) ![360 安全龙虾金牌赞助](https://img.shields.io/static/v1?label=360%E5%AE%89%E5%85%A8%E9%BE%99%E8%99%BE&message=%E9%87%91%E7%89%8C%E8%B5%9E%E5%8A%A9&color=1677FF&style=flat-square) > 🌏 **English version: [README.en.md](./README.en.md)** 一个适配 Claude Code / Codex 等 Agent 环境的网页 PPT 技能,用于生成**单文件 HTML 横向翻页 PPT**、PPT 配图和多平台封面。内置两套视觉系统: - **Style A: 电子杂志 × 电子墨水**。像 *Monocle* 贴上了代码,适合叙事、观点、分享、个人风格表达。 - **Style B: 瑞士国际主义**。网格至上、单一高饱和锚点色、直角、发丝线、极致字号对比,适合事实、产品、分析、方法论表达。 > 由 [歸藏](https://x.com/op7418) 在"一人公司:被 AI 折叠的组织"、"一种新的工作方式"等线下分享中沉淀而成,踩过的每一个坑都写进了 `checklist.md`。 > 赞助与支持信息见 [SPONSORS.md](./SPONSORS.md)。 **旧主题 · Style A 电子杂志风** ![Style A 电子杂志风效果展示](https://github.com/user-attachments/assets/5dc316a2-401c-4e37-9123-ea081b6ae470) **新主题 · Style B 瑞士国际主义** ![Style B 瑞士国际主义效果展示](https://github.com/user-attachments/assets/8960e78c-69bb-4b7e-aa95-6fad64b70314) ## 30 秒开始 ```bash npx skills add https://github.com/op7418/guizang-ppt-skill --skill guizang-ppt-skill ``` 也可以直接把这段话发给有 shell 权限的 AI Agent: ```text 帮我安装 guizang-ppt-skill。请把 https://github.com/op7418/guizang-ppt-skill 克隆到 ~/.claude/skills/guizang-ppt-skill,安装完成后检查 SKILL.md、assets/、references/ 是否存在。 ``` 已经安装过的话,用这段话更新: ```text 帮我更新 guizang-ppt-skill。请进入 ~/.claude/skills/guizang-ppt-skill 执行 git pull,然后告诉我当前最新 commit。 ``` 安装后直接对 Agent 说: ```text 帮我基于这篇文章做一份瑞士风 PPT,控制在 7 页左右,需要 2-3 张配图。 ``` 也可以试这些请求: ```text 帮我把这份 Markdown 做成杂志风演讲 PPT。基于这份 PPT 的核心观点,生成一张公众号 21:9 头图。把这张产品截图重新设计成适合 PPT 的 16:10 配图。 ``` ## 赞助与支持 <a href="./SPONSORS.md"> <img src="https://github.com/user-attachments/assets/5b0c22c8-aff4-4219-900d-6af8604c57a8" alt="360 安全龙虾金牌赞助" width="100%"> </a> Guizang PPT Skill 的持续迭代获得 **360 安全龙虾** 金牌赞助和 [真格 Token Grant](https://zhenfund.feishu.cn/share/base/form/shrcn1lAANF659o7EpWnxlR1VOh?sessionid=) 支持。更多信息见 [SPONSORS.md](./SPONSORS.md)。 ## 效果 - 🖋 **双视觉系统**:电子杂志风负责叙事,瑞士风负责事实表达 - 📐 **横向左右翻页**:键盘 ← → / 滚轮 / 触屏滑动 / 底部圆点 / ESC 索引 - 🧩 **Style A 10 种布局**:封面、章节、数据大字报、图文、图片网格、Pipeline、对比等 - 🧱 **Style B 22 种锁定版式**:Cover、Statement、KPI Tower、Loop Diagram、Duo Compare、Image Hero、Closing Manifesto 等 - 🎨 **主题色预设**:Style A 5 套电子墨水主题,Style B 4 套瑞士高饱和锚点色 - 🖼 **Codex 可选配图流程**:可用 GPT-Image 2.0 / GPT-M 2.0 生成纪实照片、信息图、流程图、系统关系图、UI 情景图,并按模板比例插入 - 📰 **多平台封面**:可用同一套视觉规则生成公众号 21:9、公众号分享卡 1:1、小红书 3:4、视频号横版等封面 - 📴 **低性能静态模式**:按 `B` 可关闭 WebGL / canvas 动画,让动态内容退回静态背景 - 📄 **单文件 HTML**:不需要构建、不需要服务器,浏览器直接打开 ## 适合 / 不适合 **✅ 合适**:线下分享 / 行业内部讲话 / 私享会 / AI 产品发布 / demo day / 带强烈个人风格的演讲 **❌ 不合适**:大段表格数据 / 培训课件(信息密度不够)/ 需要多人协作编辑(静态 HTML) ## 常见使用场景 | 任务 | 推荐方式 | |------|---------| | 长文章变演讲 PPT | 先抽核心观点,再按 6-10 页节奏生成 deck | | 方法论 / 产品分析 | 用 Style B 瑞士风,优先使用锁定版式和 21:9 主图 | | 个人分享 / 观点表达 | 用 Style A 电子杂志风,保留更强叙事感 | | PPT 配图 | 在 Codex 中用 GPT-Image 2.0 / GPT-M 2.0 生成照片、信息图、流程图、UI 情景图 | | 多平台封面 | 从同一份内容生成公众号 21:9、1:1 分享卡、小红书 3:4、视频号横版封面 | | 截图统一风格 | 把原始截图重新生成到模板需要的比例,再插入 PPT | ## 为什么是 HTML PPT - **更适合 Agent 生成和修改**:HTML / CSS 是文本,Agent 能直接读、改、验证。 - **表现力比 Markdown 更高**:可以做精细排版、空间定位、动画、交互和响应式封面。 - **交付更轻**:单文件 HTML 可以直接打开、演示、发送、截图。 - **更容易做质量控制**:瑞士风可以用脚本校验版式、图片槽位、标题对齐和危险 SVG。 - **更适合视觉内容链路**:同一套主题能覆盖 PPT、配图、封面和截图再设计。 ## 平台支持 | 平台 | 状态 | 说明 | |------|------|------| | Claude Code | 支持 | 原生 Skill 工作流,适合生成和迭代 HTML deck | | Codex | 支持 | 适合生成 PPT、调用图片生成能力、做浏览器视觉检查 | | Cursor / 其他本地 Agent | 可用 | 需要能读写文件并执行 shell 命令 | | WorkBuddy | 适配中 | 单独整理上架版本,去掉平台不需要的渠道差异 | | 普通 Chatbot | 不推荐 | 没有文件系统和浏览器预览时,很难稳定生成完整 deck | ## 安装 ### 方式一:一行命令安装(推荐) ```bash npx skills add https://github.com/op7418/guizang-ppt-skill --skill guizang-ppt-skill ``` ### 方式二:把下面这段话直接发给 AI > 帮我安装 `guizang-ppt-skill` 这个 Claude Code skill。请按下面步骤做: > > 1. 确保 `~/.claude/skills/` 目录存在(不存在就创建) > 2. 执行 `git clone https://github.com/op7418/guizang-ppt-skill.git ~/.claude/skills/guizang-ppt-skill` > 3. 验证:`ls ~/.claude/skills/guizang-ppt-skill/` 应该看到 `SKILL.md`、`assets/`、`references/` 三项 > 4. 告诉我安装好了,之后我说"做一份杂志风 PPT"之类的话就会触发这个 skill 把这段话复制粘贴给 Claude Code / Cursor / 任何有 shell 权限的 AI Agent,它会自动完成安装。 ### 方式三:手动命令行 ```bash git clone https://github.com/op7418/guizang-ppt-skill.git ~/.claude/skills/guizang-ppt-skill ``` ### 触发方式装好后,Claude Code 会在对话里自动发现并调用这个 skill。触发关键词: - "帮我做一份杂志风 PPT" - "帮我做一份瑞士风 PPT" - "生成一个 horizontal swipe deck" - "editorial magazine style presentation" - "electronic ink 风格演讲 slides" - "基于这篇文章做一张公众号 21:9 封面" - "基于这份 PPT 生成一张 1:1 分享卡" ## 使用流程 Skill 本身是结构化工作流,Agent 会逐步引导: 1. **选择风格** — Style A 电子杂志风,或 Style B 瑞士国际主义 2. **需求澄清** — 7 问清单:风格、受众、时长、素材、图片/截图需求、主题色、硬约束 3. **拷贝模板** — Style A 用 `assets/template.html`,Style B 用 `assets/template-swiss.html` 4. **填充内容** — 先做主题节奏表,再从对应 layout 骨架里挑、粘、改文案 5. **可选配图** — 在 Codex 中询问是否用 GPT-Image 2.0 / GPT-M 2.0 生成配图,再按页面比例插入 6. **自检** — 对照 `references/checklist.md`,P0 级问题必须全过；瑞士风还要运行版式校验器 7. **预览** — 浏览器直接打开 8. **迭代** — inline style 改字号/高度/间距详细说明见 [`SKILL.md`](./SKILL.md)。 ## Style B 瑞士风瑞士风是这次新增的结构化主题。它不是"换一套 CSS",而是一套更严格的版式系统。 - **22 个具名版式**:正文页只能从 `S01` 到 `S22` 中选择,不能临时发明页面结构 - **4 套锚点色**:克莱因蓝 IKB、柠檬黄、柠檬绿、安全橙 - **网格锁定**:16 列 grid、直角色块、1px 发丝线、无阴影、无渐变、无圆角 - **中文字号收敛**:全中文大标题需要降一档,避免占掉正文和图片空间 - **图文底对齐**:左文右图 / 左图右文场景优先让正文块与图片底部对齐,同时避开页脚翻页组件 - **图片槽位绑定**:图片必须进入模板预留的 `data-image-slot`,常见主图按 21:9 或 16:10 生成 - **强校验**:用脚本拦住居中标题、实验版式、SVG 内写字、图片脱离槽位等问题瑞士风校验命令: ```bash node scripts/validate-swiss-deck.mjs path/to/index.html ``` ## Codex 配图能力在 Codex 环境中,完成 deck 初稿后可以主动询问用户是否需要生成配图。用户确认后,再询问图片类型或风格,常用类型包括: - 人文纪实照片:富士 / 徕卡感的真实场景,增加人文表现力 - 信息图 / 流程图 / 对比图 / 系统关系图:用于解释无法用实拍照片说明的概念 - 截图美化 / 截图再设计:原始截图优先用内置背景资产做 CleanShot X 式背景画布适配;需要重构时再生成 UI 情景图 - 数据大字报 / 数据图表:把关键数字做成可直接插入 PPT 的视觉素材 - 多图拼贴:用于极宽图片槽位,避免把三张 16:9 图片硬塞进三列生成图片时要遵守四个关键规则: - 图片是 PPT 中的嵌入素材,不要自带页脚、页底、标题、角标、页码或装饰边框 - 图片语言跟随 deck 语言:中文 deck 的信息图用中文标签,英文 deck 用英文标签 - 图片比例必须先匹配落位:瑞士风主图常用 21:9,通用主图常用 16:9 / 16:10,截图再设计常用 16:10,多图网格统一高度 - 用户截图需要保真时,先读 `references/screenshot-framing.md`,用 `assets/screenshot-backgrounds/` 内置背景 + 程序化缩放/留边/对齐处理,不要默认重画截图内容配图提示词见 [`references/image-prompts.md`](./references/image-prompts.md),截图适配见 [`references/screenshot-framing.md`](./references/screenshot-framing.md)。 ## 封面生成这个 Skill 也可以基于文章或 PPT 核心观点生成平台封面。典型规格: - **公众号头图**:21:9,主标题优先,右侧或边缘保留视觉锚点 - **公众号分享卡**:1:1,与头图共用主题色、关键词和视觉元素 - **小红书封面 / 轮播**:3:4,大标题优先,多张时统一字号和视觉节奏 - **视频号 / 横版封面**:16:9,适合标题 + 副标题 + 单一视觉焦点封面原则和 PPT 一样:只用少量关键词,视觉重心落在大标题上,不要把正文堆满。 ## 示例请求复制下面任意一条给 Agent,再附上你的文章、Markdown 或素材文件: ```text 帮我基于这篇文章生成一份 8 页左右的瑞士风 PPT,需要 3 张配图,图片比例跟模板槽位匹配。 ``` ```text 帮我把这个产品分析文档做成电子杂志风 PPT,重点突出观点和叙事节奏。 ``` ```text 基于这份 PPT 的主题,做两张封面:公众号 21:9 头图和 1:1 分享卡,视觉保持一致。 ``` ```text 把这些产品截图重新设计成统一的 16:10 PPT 配图,保留关键信息,不要画页脚和标题。 ``` ## 目录结构 ``` guizang-ppt-skill/ ├── SKILL.md ← Skill 主文件:工作流、原则、常见错误 ├── README.md ← 本文件 ├── assets/ │ ├── template.html ← Style A 电子杂志风模板 │ ├── template-swiss.html ← Style B 瑞士国际主义模板 │ └── screenshot-backgrounds/ ← 截图美化内置背景(WebP):style-a 5 套 / style-b 4 套 ├── scripts/ │ └── validate-swiss-deck.mjs ← 瑞士风版式校验器 └── references/ ├── components.md ← 组件手册(字体、色、网格、图标、callout、stat、pipeline) ├── layouts.md ← 10 种页面布局骨架(可直接粘贴) ├── layouts-swiss.md ← 22 种瑞士风锁定版式 ├── swiss-layout-lock.md ← 瑞士风还原度和版式硬约束 ├── themes.md ← 5 套主题色预设(只能选不能自定义) ├── themes-swiss.md ← 4 套瑞士风锚点色 ├── image-prompts.md ← GPT-Image 2.0 / GPT-M 2.0 配图类型、比例和基础提示词 ├── screenshot-framing.md ← CleanShot X 式截图适配语义 └── checklist.md ← 质量检查清单(P0 / P1 / P2 / P3 分级) ``` ## 主题色预设从 `references/themes.md` 里选一套——**不允许自定义 hex 值**,保护美学比给自由更重要。 ### Style A 电子杂志主题 | 预览 | 主题 | 核心色与适合场景 | |------|------|------------------| | <img src="https://github.com/user-attachments/assets/df21dbcb-5fe4-4852-a91a-a9cf00aceeb4" width="260" alt="墨水经典主题预览"> | 🖋 **墨水经典** | `#0a0a0b` / `#f1efea`。通用默认、商业发布、不知道选啥时最稳。 | | <img src="https://github.com/user-attachments/assets/99ce0fd2-72a6-4368-a75a-a8e21657a537" width="260" alt="靛蓝瓷主题预览"> | 🌊 **靛蓝瓷** | `#0a1f3d` / `#f1f3f5`。科技、研究、AI、技术发布会。 | | <img src="https://github.com/user-attachments/assets/bcc1cc4c-5e8e-4467-ae8d-f5801ae73657" width="260" alt="森林墨主题预览"> | 🌿 **森林墨** | `#1a2e1f` / `#f5f1e8`。自然、可持续、文化、非虚构内容。 | | <img src="https://github.com/user-attachments/assets/dfea080e-e916-417e-93cd-0a3628de84ca" width="260" alt="牛皮纸主题预览"> | 🍂 **牛皮纸** | `#2a1e13` / `#eedfc7`。怀旧、人文、阅读、历史、文学分享。 | | <img src="https://github.com/user-attachments/assets/f3705592-9a72-4dbc-9818-df3aea61bc75" width="260" alt="沙丘主题预览"> | 🌙 **沙丘** | `#1f1a14` / `#f0e6d2`。艺术、设计、创意、时尚和画廊感内容。 | 切换主题只需替换 `template.html` 开头 `:root{}` 里的 6 行变量,其他 CSS 全走 `var(--...)`。 ### Style B 瑞士主题瑞士风从 `references/themes-swiss.md` 里选一套,同样**不允许自定义 hex 值**。 | 预览 | 主题 | 锚点色与适合场景 | |------|------|------------------| | <img src="https://github.com/user-attachments/assets/c02d02f7-ce6f-4e16-b8a6-778c96851f94" width="260" alt="克莱因蓝瑞士主题预览"> | 🔵 **克莱因蓝 IKB** | `#002FA7`。通用默认、商业发布、AI 产品、方法论。 | | <img src="https://github.com/user-attachments/assets/c310a8c4-5d28-450e-b49a-6ac5b6ba4785" width="260" alt="柠檬黄瑞士主题预览"> | 🟡 **柠檬黄** | `#FFD500`。年轻、运动、零售、消费品、Y2K 复古。 | | <img src="https://github.com/user-attachments/assets/65f7b3f9-3358-419e-b513-f7f2cc24ec76" width="260" alt="柠檬绿瑞士主题预览"> | 🟢 **柠檬绿** | `#C5E803`。生态、可持续、健康、Z 世代品牌。 | | <img src="https://github.com/user-attachments/assets/9c3319c9-a134-4657-9a56-211c23411f7f" width="260" alt="安全橙瑞士主题预览"> | 🟠 **安全橙** | `#FF6B35`。警示、新闻、工业、运动、活力主题。 | 如果用户说"瑞士风 PPT"但没有指定颜色,默认推荐克莱因蓝 IKB。 ## 核心设计原则 1. **克制优于炫技** — WebGL 背景只在 hero 页透出 2. **结构优于装饰** — 信息靠字号 + 字体对比 + 网格留白,不用阴影和浮动卡片 3. **图片是第一公民** — 图片要对齐正文内容区,比例稳定,只裁底部,顶部和左右完整 4. **配图只做素材** — 生成图只保留核心照片 / 图表 / UI,不要把 PPT 页脚、标题和角标画进图片里 5. **节奏靠 hero 页** — hero / non-hero 交替,才不累眼睛 6. **低性能可退场** — 按 `B` 能切换到静态模式,动态效果不能成为阅读负担 7. **术语统一** — Skills 就是 Skills,不中英混译 8. **瑞士风必须守版式** — Style B 优先还原原始 22P 版式,不要为了"多样"发明不存在的页面 ## 视觉参考 - [*Monocle*](https://monocle.com) 杂志的版式 - YC Garry Tan "Thin Harness, Fat Skills" - Massimo Vignelli / Helvetica Forever / 瑞士国际主义网格系统 - 歸藏线下分享 PPT 系列 ## Roadmap - 补充更多真实案例和可打开的 HTML deck 示例 - 扩展封面规格,覆盖更多内容平台 - 增加更多瑞士风版式校验规则 - 优化截图再设计和信息图生成工作流 - 整理 WorkBuddy 等平台上架版本 - 增加更多主题包,但继续限制自定义颜色 ## FAQ **可以导出 PPTX 吗?** 当前核心交付是 HTML。你可以用浏览器演示、截图或录屏。如果需要 PPTX,建议把 HTML 页面作为视觉稿再转换,但这不是当前主流程。 **为什么不允许自定义颜色?** 这个 Skill 的重点是稳定产出。自由选色很容易破坏整体风格,所以只允许从预设主题里选。 **我能加自己的版式吗?** 可以。Style A 可以在 `references/layouts.md` 里扩展；Style B 更严格,需要同步更新 `template-swiss.html`、`layouts-swiss.md`、`swiss-layout-lock.md` 和校验器。 **Codex 配图是必须的吗?** 不是。没有配图也能生成 PPT。配图流程只在需要照片、信息图、UI 情景图或封面时使用。 **怎么更新到最新版?** 重新运行安装命令,或在本地 skill 目录执行 `git pull`。 ## 贡献 Bug、排版问题、新布局需求——欢迎开 Issue 或 PR。改动请优先: - 在 `template.html` 里补类,不要让 layouts.md 使用未定义的类 - 在 `template-swiss.html` 里补类时,同步更新 `layouts-swiss.md` 和 `swiss-layout-lock.md` - 瑞士风新增规则后,同步更新 `scripts/validate-swiss-deck.mjs` - 把踩过的坑写到 `checklist.md` 对应的 P0 / P1 / P2 / P3 级别 - 新主题色进 `themes.md` 并给出适合的场景 ## License AGPL-3.0 © 2026 [op7418](https://github.com/op7418)

Frontend Templates AI Agents

16K Github Stars

Open Source

guizang-social-card-skill

# Guizang Social Card Skill · 小红书图文 / 公众号封面对 ![GitHub stars](https://img.shields.io/github/stars/op7418/guizang-social-card-skill?style=flat-square) ![License](https://img.shields.io/github/license/op7418/guizang-social-card-skill?style=flat-square) ![Skill](https://img.shields.io/badge/Skill-Agent-111111?style=flat-square) ![Social Cards](https://img.shields.io/badge/Social-Cards-FF4D6D?style=flat-square) ![Claude Code](https://img.shields.io/badge/Claude%20Code-Supported-6B5B95?style=flat-square) ![Codex](https://img.shields.io/badge/Codex-Supported-222222?style=flat-square) [English README](./README.en.md) 一个适配 Claude Code / Codex 等 Agent 环境的图文卡片技能,用于从文章、文案、截图、产品笔记、字幕或照片生成**小红书 / Rednote 图文组图**与**公众号 21:9 + 1:1 封面对**。内置两套视觉系统,共用一份图文工作流: - **电子杂志风(Editorial)**。像 *Monocle* / *Kinfolk* / *Cereal* 那样克制的版面,适合叙事、生活方式、旅行、阅读、影视、个人观察。 - **瑞士国际主义(Swiss)**。网格、单一锚点色、直角发丝线、极致字号对比,适合产品测评、数据、方法论、教程、AI 工具。 > 这个 Skill 是 [guizang-ppt-skill](https://github.com/op7418/guizang-ppt-skill) 的姊妹项目,共享美学语言但独立维护。PPT 解决"横向翻页演讲",这里解决"静态信息流图文"。 ![Guizang Social Card Skill 效果展示](https://github.com/user-attachments/assets/d370abcc-1fc4-4de1-903a-09020a6556ce) ## 30 秒开始 ```bash npx skills add https://github.com/op7418/guizang-social-card-skill --skill guizang-social-card-skill ``` 也可以直接把这段话发给有 shell 权限的 AI Agent: ```text 帮我安装 guizang-social-card-skill。请把 https://github.com/op7418/guizang-social-card-skill 克隆到 ~/.claude/skills/guizang-social-card-skill,安装完成后检查 SKILL.md、assets/、references/ 是否存在。 ``` 已经安装过的话,用这段话更新: ```text 帮我更新 guizang-social-card-skill。请进入 ~/.claude/skills/guizang-social-card-skill 执行 git pull,然后告诉我当前最新 commit。 ``` 安装后直接对 Agent 说: ```text 帮我基于这篇文章做一套瑞士风小红书图文,5 张,IKB 蓝。 ``` 也可以试这些请求: ```text 基于这份产品测评做一套小红书 3:4,标题用电子杂志风。帮我把这篇文章做成公众号封面对:21:9 头图 + 1:1 分享卡,视觉保持一致。我有 3 张露营照片,帮我做一套全图风格的小红书图文。把这段游戏攻略文案做成一套小红书图文,需要从 wallhaven 拿点游戏原画。 ``` ## 效果 - 🖋 **双视觉系统**:电子杂志风做氛围与叙事,瑞士风做事实与结构,两套共用同一份工作流 - 📐 **3 个画板尺寸**:`.poster.xhs` 1080×1440(小红书 3:4)、`.poster.wide` 2100×900(公众号 21:9)、`.poster.square` 1080×1080(公众号 1:1) - 🧩 **28 个版式骨架**:Editorial 16 个(`M01-M16`,含 Image-Led Cover、Pipeline、Before/After 等)+ Swiss 12 个(`S01-S12`,含 KPI Tower、H-Bar Chart、Matrix + Hero 等) - 🎨 **10 套主题预设**:Editorial 6 套(墨水经典、靛蓝瓷、森林墨、牛皮纸、沙丘、**Midnight Ink** 暗色)+ Swiss 4 套锚点色(IKB Klein Blue、柠檬黄、柠檬绿、安全橙) - 🖼 **图源工作流**:用户图优先;无图时按 Unsplash → Pexels → Flickr CC → Wallhaven → 直接搜索的优先级取图,落本地 + 自动写 `SOURCES.md` - 🌫 **WebGL 墨流背景**:杂志风 hero 页可挂动态墨流;低性能或截图时可禁用 - 🪧 **图片底图遮罩 + 人脸避让**:满铺图必须叠遮罩,文字落点要避开主体,`references/image-overlay.md` 给硬规则 - 🧰 **截图美化资产**:9 张 WebP 真实材质背景(Editorial 5 / Swiss 4),配套 `.frame-shot` / `.device-browser` / `.device-phone` 工具类 - 🗺 **地图组件**:MapLibre + OSM 真实瓦片,支持多 pin + 连线,适合旅行攻略 - ✅ **校验脚本**:`validate-social-deck.mjs` 自动检测溢出、字号上限、4 横带密度、footer 碰撞 - 📄 **单文件 HTML + Playwright 渲染**:不需要前端构建链,`node render.mjs` 直接出 PNG ## 适合 / 不适合 **✅ 合适**:小红书图文组图 / 公众号封面对 / 微信朋友圈封面 / 视频号封面 / 文章配图 / 教程拆页 / 数据回顾 / 旅行攻略 / 产品测评 / 截图说明 **❌ 不合适**:横向翻页 PPT(用 [guizang-ppt-skill](https://github.com/op7418/guizang-ppt-skill))/ 长视频生成 / 纯图片修图 / 无版式诉求的纯文字编辑 ## 11 个小红书品类适配按"能力圈"分三档,详见 [`references/category-cookbook.md`](./references/category-cookbook.md): **端到端强势**(文 / 结构 / 图都在能力圈内): - 旅行、职场、推荐(指定子类后) **文与结构强势,图依赖用户或搜图源:** - 游戏、影视、美食(食谱方向)、彩妆(教程方向)、健身、家居、穿搭(精选方向) **能力圈外,主动说清**(不强行接): - OOTD 实拍流 / 梦核 / 仿胶片调色 / 真实测肤美妆等强烈依赖摄影或后期的细分赛道 ## 常见使用场景 | 任务 | 推荐方式 | |------|---------| | 长文章 → 小红书图文 | 抽核心观点,Editorial 走叙事节奏,Swiss 走拆条数据 | | 产品测评 / 工具回顾 | Swiss + IKB 蓝,优先 `S09 KPI Tower` / `S10 H-Bar Chart` | | 旅行 / 生活方式分享 | Editorial + Midnight Ink 或 Dune,`M16 Image-Led Cover` 满铺主图 | | 公众号封面对 | 同一份内容渲两块:`.poster.wide` 21:9 + `.poster.square` 1:1,视觉一致 | | 截图教程 / 工具说明 | `.frame-shot` + `.device-browser` 包壳,优先 Swiss 网格底 | | 游戏攻略 / 影视回顾 | Editorial + Midnight Ink,从 Wallhaven 取游戏原画做满铺 | | 数据回顾 / 年终总结 | Swiss + Lemon 或 Safety Orange,矩阵 + ledger 组合 | ## 为什么是单文件 HTML 渲 PNG - **Agent 友好**:HTML + CSS 是文本,Agent 能直接写、读、改、验证 - **版式精确**:CSS Grid + 严格字号 / 留白 / 网格,远超 Markdown 排版能力 - **图源开放**:可以接 Unsplash / Pexels / Wallhaven / Mapbox / OSM 等任意网络资源 - **质量可校验**:`validate-social-deck.mjs` 用 Playwright 跑真实 DOM 测量,不是猜 - **交付简单**:`output/*.png` 直接发,不需要部署、不需要导出工具 ## 平台支持 | 平台 | 状态 | 说明 | |------|------|------| | Claude Code | 支持 | 原生 Skill 工作流,适合生成 + 迭代图文 | | Codex | 支持 | 适合长流程图文生成、调用图片源、做视觉检查 | | Cursor / 其他本地 Agent | 可用 | 需要能读写文件 + 执行 shell | | 普通 Chatbot | 不推荐 | 没有文件系统和渲染管线时无法稳定出图 | ## 安装 ### 方式一:一行命令安装(推荐) ```bash npx skills add https://github.com/op7418/guizang-social-card-skill --skill guizang-social-card-skill ``` ### 方式二:把下面这段话直接发给 AI > 帮我安装 `guizang-social-card-skill` 这个 Claude Code skill。请按下面步骤做: > > 1. 确保 `~/.claude/skills/` 目录存在(不存在就创建) > 2. 执行 `git clone https://github.com/op7418/guizang-social-card-skill.git ~/.claude/skills/guizang-social-card-skill` > 3. 验证:`ls ~/.claude/skills/guizang-social-card-skill/` 应该看到 `SKILL.md`、`assets/`、`references/` 三项 > 4. 告诉我装好了,之后我说"做一套小红书图文"之类的话就会触发这个 skill 把这段话复制粘贴给 Claude Code / Cursor / 任何有 shell 权限的 AI Agent,它会自动完成安装。 ### 方式三:手动命令行 ```bash git clone https://github.com/op7418/guizang-social-card-skill.git ~/.claude/skills/guizang-social-card-skill ``` ### 触发方式装好后,Claude Code 会自动发现并调用这个 skill。触发关键词: - "帮我做一套小红书图文 / Xiaohongshu 图文" - "帮我做一套 Rednote 卡片" - "做一个公众号 21:9 头图 + 1:1 分享卡" - "生成一套 social cards / 杂志风社交卡片" - "把这篇文章做成轮播图文 / 教程拆页" - "做一套瑞士风的小红书测评 / IKB 风格图文" ## 使用流程 Skill 本身是结构化工作流,Agent 会按 7 步走: 1. **Intake** — 抓 4 件事:目标平台 / 风格 / 内容素材 / 用户图。无图时一次性给 A/B/C 三选(自己拍图 / AI 生图 / 网络取图),不二次劝导 2. **Style & Theme** — 选 Editorial 还是 Swiss,再从 10 套预设里选主题色。不允许自定义 hex 3. **Layout Selection** — 根据内容结构从 28 个版式骨架里挑、粘、改文案。Editorial 16 个 / Swiss 12 个 4. **Asset Prep** — 取图(Unsplash / Pexels / Flickr CC / Wallhaven / 直接搜索),落本地 + 写 `SOURCES.md`;问用户要不要标来源 5. **Compose & Render** — 拷种子模板 → 替换 `` → `node render.mjs` 6. **Deliver & Review** — 先把 PNG 给用户看,询问"你自己看还是我先帮你跑 validator",默认不自动核查 7. **Iterate** — 用户提反馈,改 inline 样式或 swap 版式 / 替图,重渲详细说明见 [`SKILL.md`](./SKILL.md)。深度细节去看对应 `references/*.md`。 ## 校验脚本 ```bash node validate-social-deck.mjs path/to/task-dir ``` 6 条规则,基于 Playwright 真实渲染测量,不是静态扫描: - **R1** Overflow — 任何 section 超出 `.poster` 立刻报错 - **R2** Type Caps — `.h-xl` / `.h-display` 字号 + 字重组合超出种子定义 - **R3** Footer Collision — 内容压到底部 footer / page-number - **R4** 4-Band Density — 1440 高画布切 4 横带,每带应有内容或主动留白理由 - **R5** Frame Overflow — `.frame-img` / `.frame-shot` 子元素溢出框 - **R6** Swiss Identity — Swiss 模板里 inline `font-weight >= 700` 警告(违反"越大越细") `SKILL.md` 第 7 步明确**默认不自动跑** validator —— 等用户先看完图再问,避免每轮多花数十秒。 ## 主题色预设从 [`references/theme-presets.md`](./references/theme-presets.md) 里选一套——**不允许自定义 hex 值**,保护美学比给自由更重要。 ### Editorial 6 套 | 主题 | 色调 | 适合场景 | |------|------|---------| | 🖋 **墨水经典 Ink Classic** | `#0a0a0b` / `#f1efea` | 通用默认、商业话题、不知道选啥时最稳 | | 🌊 **靛蓝瓷 Indigo Porcelain** | `#0a1f3d` / `#f1f3f5` | 科技、研究、AI、技术分享 | | 🌿 **森林墨 Forest Ink** | `#1a2e1f` / `#f5f1e8` | 自然、可持续、户外、非虚构 | | 🍂 **牛皮纸 Kraft Paper** | `#2a1e13` / `#eedfc7` | 怀旧、人文、阅读、文学 | | 🌙 **沙丘 Dune** | `#1f1a14` / `#f0e6d2` | 艺术、设计、创意、时尚 | | ⚫ **午夜墨 Midnight Ink** | `#0e0d0c` / `#ece2cf` / `#d4a04a` | 游戏 key art / 夜景 / 影调封面 / 黑神话 · 艾尔登法环类深色题材 | ### Swiss 4 套 | 主题 | 锚点色 | 适合场景 | |------|--------|---------| | 🔵 **克莱因蓝 IKB** | `#002FA7` | 通用默认、商业发布、AI 产品、方法论 | | 🟡 **柠檬黄 Lemon** | `#FFD500` | 年轻、运动、零售、消费品、Y2K | | 🟢 **柠檬绿 Lemon Green** | `#C5E803` | 生态、健康、Z 世代、绿色品牌 | | 🟠 **安全橙 Safety Orange** | `#FF6B35` | 警示、新闻、工业、活力主题 | 切主题只需替换种子模板的 `<section class="poster" data-theme="...">` 属性,所有 CSS 走 `var(--...)`。 ## 目录结构 ``` guizang-social-card-skill/ ├── SKILL.md ← Skill 主文件:7 步工作流 ├── README.md ← 本文件 ├── HANDOFF.md ← 交接文档:事实 + 版本历史 ├── PRODUCT.md ← 产品文档:思考 + 决策 + roadmap ├── validate-social-deck.mjs ← Playwright 版式校验脚本 ├── assets/ │ ├── template-editorial-card.html ← Editorial 种子(6 主题 / 3 画板) │ ├── template-swiss-card.html ← Swiss 种子(4 accent / 3 画板) │ ├── magazine-bg-webgl.js ← WebGL 墨流背景 │ └── screenshot-backgrounds/ ← 9 张截图舞台底(WebP) │ ├── style-a/ ← Editorial 5 套 │ └── style-b/ ← Swiss 4 套 └── references/ ├── platform-specs.md ← 平台 × 分辨率 × 命名 ├── style-system.md ← 两种风格的硬规则与反模式 ├── theme-presets.md ← 10 套色票详解 ├── layout-recipes.md ← 28 个版式骨架(M01-M16 + S01-S12) ├── components.md ← 字体 / 卡片 / 间距 / 图标 ├── background-systems.md ← 墨流 / 网格 / 纸纹层 ├── portrait-fill.md ← 3:4 板的留白对策 ├── content-planning.md ← 钩子 / 拆页 / 文案压缩 ├── category-cookbook.md ← 11 个小红书品类路由表 ├── image-overlay.md ← 满铺图遮罩 + 人脸避让规则 ├── screenshot-treatment.md ← `.frame-shot` 工具类 + 截图美化 ├── map-component.md ← `.map-block` MapLibre 地图 ├── title-shortener.md ← 1:1 封面的短标题策略 ├── production-workflow.md ← Playwright 渲染管线 └── qa-checklist.md ← 质量检查清单 ``` ## 核心设计原则 1. **克制优于喊话** — 信息流里克制色板反而最显眼,不要堆饱和度 2. **结构优于装饰** — 字号 + 字体对比 + 网格留白撑起信息层级,不靠阴影和卡片 3. **版式优于自由** — 28 个版式骨架先选后改,不要发明不存在的页面 4. **图片优先用户的** — Intake 时一次性给 A/B/C,不二次劝导用户拍图 5. **遮罩与避让** — 满铺图必加遮罩,文字落点必须避开主体(人脸 / 产品 / 文字密集区) 6. **越大越细** — Swiss `.h-xl` 字号上去 → 字重必须下来。Editorial 同此原则 7. **默认不自动核查** — 把"先看图、再决定要不要 validate"做成工作流,省每轮几十秒 8. **Skill 是产品不是 Prompt** — 有 PRODUCT.md、有版本号、有 CHANGELOG、有能力边界 9. **本地测试不进 git** — 所有 demo / 冒烟测试归 `local-tests/`,被 gitignore ## 视觉参考 - *Monocle* / *Kinfolk* / *Cereal* 杂志的版式与字距 - Massimo Vignelli / Helvetica Forever / 瑞士国际主义网格系统 - Apartamento / The Gentlewoman 的图文比与人物纪实 - 小红书 / Rednote 信息流里"克制反而吃香"的内容样本 - 歸藏的图文卡片实践 ## Roadmap - 补充更多 Editorial 长内容下的字号上限冒烟测试 - 扩展 Swiss 数据类版式(更多图表骨架) - AI 出图后处理:渲染后主动询问是否做局部修复 / 整张重出 - 增加更多小红书品类的官方推荐版式包(目前 11 个里 7 个端到端可用) - 整理 WorkBuddy 等平台上架版本 ## FAQ **可以批量出图吗?** 可以。一个 task 目录下的 `index.html` 包含多个 `.poster`,`node render.mjs` 会逐个截 PNG。一次出小红书 3-9 张组图很常见。 **为什么不允许自定义颜色?** 和 PPT skill 同样的理由——这个 Skill 的核心价值是稳定产出。自由选色会破坏整体风格,只允许从 10 套预设里挑。 **能用其他模型生图吗?** 可以。生图本身不在 Skill 范围内,但 SKILL.md Step 4 写清了取图协议:用户图 → AI 生图 → 网络取图。AI 生图能力依赖你当前 Agent 接的模型。 **Codex 写出来不合规怎么办?** v0.12 起把"种子模板与 components.md 表格保持一致"做成了硬规则。如果还是出现违规,大概率是 seed template 默认值与 `references/style-system.md` 不一致——开 Issue 给我们。 **怎么更新到最新版?** 重新运行安装命令,或在本地 skill 目录执行 `git pull`。 **支持英文图文吗?** 支持。Editorial 的 Playfair Display + Noto Serif、Swiss 的 Inter + Helvetica 都同时覆盖中英文。版式骨架未做语言绑定。 ## 贡献 Bug、排版问题、新版式需求——欢迎开 Issue 或 PR。改动请优先: - 改种子模板时,同步更新 `references/components.md` 的对照表(字号 / 字距 / 字重) - 新增版式时,在 `references/layout-recipes.md` 加完整 recipe(文案上限 + minimum density) - 新增主题色时,同步更新种子模板的 `[data-theme="..."]` 块 + `references/theme-presets.md` - 新增 Swiss 规则时,同步更新 `validate-social-deck.mjs` 的对应规则 - 踩过的坑写到 `references/qa-checklist.md` - 测试与 demo 一律放在 `local-tests/` 下,不要污染 skill 根目录 ## License AGPL-3.0 © 2026 [op7418](https://github.com/op7418) 本项目采用 **GNU AGPL-3.0** 协议,要点: 1. **必须署名** — 保留版权声明 2. **衍生品必须开源** — 任何修改版本、Fork、二次分发,必须以 AGPL-3.0(或兼容协议)公开发布,提供完整源代码 3. **网络服务也要开源** — 即使你只是把修改版本部署成 SaaS / Web 服务给别人用而不分发代码,也要公开源代码(这是 AGPL 区别于 GPL 的核心) 4. **不允许闭源、专有化、仅付费分发** 完整条款见 [`LICENSE`](./LICENSE)。

AI Agents Image Editing

3.2K Github Stars

Open Source

ai-desk-card

# AI Desk Card · 桌面 AI 副屏 Skill ![GitHub stars](https://img.shields.io/github/stars/op7418/ai-desk-card?style=flat-square) ![License](https://img.shields.io/github/license/op7418/ai-desk-card?style=flat-square) ![Skill](https://img.shields.io/badge/Skill-Agent-111111?style=flat-square) ![M5Paper](https://img.shields.io/badge/M5Paper-V1.1-0A7CFF?style=flat-square) ![Claude Code](https://img.shields.io/badge/Claude%20Code-Supported-6B5B95?style=flat-square) ![Codex](https://img.shields.io/badge/Codex-Supported-222222?style=flat-square) > 🌏 **English version: [README.en.md](./README.en.md)** 一个适配 Claude Code / Codex 等 Agent 的桌面副屏 Skill。把 [M5Paper V1.1](https://docs.m5stack.com/en/core/m5paper) 4.7 寸墨水屏立在显示器旁边，由 AI Agent 推送 widget：天气、日程、todo、PR 队列、AI 状态、休息提醒…… **装上 Skill 后，烧固件 / 配 Wi-Fi / 推内容 / 设置定时全部由 Agent 引导**，你不用自己跑一行 `pio` 或 `curl`。 ![AI Desk Card 桌面效果](https://github.com/user-attachments/assets/b4777ba7-d668-42c1-9920-3e6d8bef534e) ``` 你 ──说自然语言──▶ AI Agent ──触发──▶ Skill ──自动执行──▶ M5Paper 屏上 ``` ## 30 秒开始 ```bash npx skills add https://github.com/op7418/ai-desk-card --skill ai-desk-card ``` 也可以把下面这段话直接发给有 shell 权限的 AI Agent： ```text 帮我安装 ai-desk-card Skill。把 https://github.com/op7418/ai-desk-card 克隆到 ~/.claude/skills/ai-desk-card，安装完成后检查 SKILL.md、flows/、daemon/、src/、assets/ 是否存在。 ``` 已经装过想更新： ```text 帮我更新 ai-desk-card。请进入 ~/.claude/skills/ai-desk-card 执行 git pull，然后告诉我当前最新 commit。 ``` 装完之后，假设你手上有 M5Paper V1.1 + USB-C 数据线，直接对 Agent 说： ```text 帮我把 ai-desk-card 装上。我手上是 M5Paper V1.1，USB-C 已经插好了。 ``` Skill 会自动： 1. 探测当前状态（PlatformIO / USB 设备 / daemon / Wi-Fi 配没配） 2. 缺啥装啥（PlatformIO 没装就 `pipx install`） 3. 编译 + 烧 CJK 字体 + 烧固件（约 1 分钟） 4. 启动 daemon 5. 问你 Wi-Fi 密码 → 自动配上 6. 推第一个 widget 上去之后日常使用就是和 Agent 自然对话： ```text 在卡片上显示今天北京的天气。让卡片每 30 分钟刷新天气和未读邮件，工作日 8 点到 22 点。现在卡片上是啥？晚上 11 点之后自动息屏显示我的名片。 ``` ## 效果 - 🖥 **桌面 ambient 副屏**：540×960 墨水屏立在显示器旁，瞥一眼就知道今天的状态 - 🤖 **AI 主动推送**：Agent 决定推什么 widget、什么时候推；你不用自己开浏览器查天气 - 📦 **16 种 widget**：weather / calendar / todo / focus / inbox / pr-queue / ai-status / git-status / now-playing / break-reminder / scratch / messages / deadlines / next-meeting / system / ai-tasks - 🎨 **服务端渲染**：daemon 用 Python + Pillow 渲染像素帧，固件只负责显示；想加新 widget 只改 Python，不用动 C++ - 🔌 **三种供电模式自动切换**：USB 常开 / USB 数据线 / 电池 + BLE 待机（几个月续航） - 🌐 **Wi-Fi LAN 0.2 秒一帧**：本地 HTTP 直推，无云依赖 - 💤 **关屏 0 功耗保留最后一帧**：墨水屏特性，电池续航 6 个月（架构 C） - 👆 **底栏触屏 chip**：点"睡眠"推电子名片 + 深度休眠；点"设置"翻设置页。150ms 点击态反馈 - ⏰ **定时自动息屏**：到 quiet hours 自动切到电子名片，daemon 不需要 Agent 在线 ## 适合 / 不适合 **✅ 合适**： - 想要 always-on 桌面副屏，但不想再开第二台亮屏显示器 - 已经在用 Claude Code / Codex / Cursor 等 Agent，想给它一个物理 ambient 输出 - 喜欢墨水屏低疲劳感（不刺眼、不抢注意力） - 接受第一次 ~10 分钟硬件配置（之后 0 维护） **❌ 不合适**： - 需要快速刷新内容（股票实时、视频、动效）— 墨水屏不行 - 不想买硬件 / 不想烧固件 - 需要复杂触屏交互（墨水屏触屏可用但慢） ## 常见使用场景 | 你说 | Agent 干什么 | |------|------| | "帮我把 ai-desk-card 装上" | 完整入职流程：探测状态 → 烧固件 → 起 daemon → 配 Wi-Fi | | "在卡片上显示今天的天气" | 推 weather widget | | "把日程贴上去" | 推 calendar widget，自动读 macOS 日历 | | "显示我现在在做的任务" | 推 focus widget | | "让卡片每 30 分钟刷新" | 写 `~/.ai-desk-card/interests.yaml` + 注册 loop | | "23 点自动息屏显示名片" | 配 quiet_hours，daemon 后台自动处理 | | "卡片连不上" | 触发诊断 flow：探测 → 定位问题 → 给修复建议 | | "我换 Wi-Fi 了" | 重新走 wifi-setup flow | | "卡片现在显示啥" | curl daemon 拿当前帧的 PNG 预览 | ## 平台支持 | 平台 | 状态 | 说明 | |------|------|------| | Claude Code | ✅ 主力测试 | 原生 Skill 工作流 + slash 命令兼容层 | | Codex CLI | 🟡 同 SKILL.md 格式 | 应该可用，未深度测试 | | Gemini CLI | 🟡 应该可用 | 同上 | | Cursor | 🟡 可用 | 需要 shell 权限 | | Aider | 🟡 可用 | 同上 | | 自写 Agent | ✅ | 只要识别 SKILL.md + 有 shell 权限就行 | ## 硬件准备 | 项目 | 说明 | |------|------| | **M5Paper V1.1** | 主力支持。约 ¥600 / $90。[官方店](https://shop.m5stack.com/products/m5paper-v1-1) / Amazon / AliExpress | | M5Paper V1.0 | 大概率可用，电池阈值参数 (`4150 mV`) 可能要调 | | M5Paper S3 | 需要 1-2 天移植（BLE stack 不同）| | USB-C **数据线** | 烧固件时用一次。普通"只充电"线不行 | | (可选) USB-C 充电器 | 想用"常插电 + Wi-Fi 常开"模式需要 | > ⚠️ **不需要事先装 PlatformIO / 编译器 / Python 环境** — Skill 检测到缺什么会让 Agent 自己装。 ## 安装 ### 方式一：一行命令（推荐） ```bash npx skills add https://github.com/op7418/ai-desk-card --skill ai-desk-card ``` ### 方式二：让 AI 帮你装把下面这段话复制粘贴给 Claude Code / Cursor / 任何有 shell 权限的 AI Agent： > 帮我装 `ai-desk-card` 这个 Skill。请按下面步骤做： > > 1. 确保 `~/.claude/skills/` 目录存在（不存在就创建） > 2. 执行 `git clone https://github.com/op7418/ai-desk-card.git ~/.claude/skills/ai-desk-card` > 3. 验证：`ls ~/.claude/skills/ai-desk-card/` 应该看到 `SKILL.md`、`flows/`、`plugin/`、`daemon/`、`src/`、`assets/` > 4. 装好告诉我，之后我说"帮我把卡片装上"就会触发这个 Skill ### 方式三：手动 clone ```bash git clone https://github.com/op7418/ai-desk-card.git ~/.claude/skills/ai-desk-card ``` ### 触发关键词装好后 Agent 会在你说这些时自动唤起 Skill： - "卡片" / "副屏" / "墨水屏" / "桌面卡片" - "把 X 显示在卡片上" / "show X on my card" - "刚拿到 M5Paper" / "first-time setup" / "刷固件" - "每 N 分钟刷新" / "auto-refresh" - "卡片息屏" / "显示名片" / "睡眠" - "ai-desk-card" ## 使用流程 Skill 是结构化工作流，Agent 会按下面顺序自动跑（你不用记每一步）： 1. **入职 (flow 01)** — 探测 PlatformIO / USB 设备 → 引导你烧固件 2. **传输诊断 (flow 02)** — 设备连不上时定位问题 3. **配 Wi-Fi (flow 03)** — 把 Wi-Fi 凭证写进设备 NVS 4. **写偏好 (flow 04)** — 第一次问"你想看哪些卡片，多久刷一次" 5. **推 widget (flow 05)** — 日常推送的热路径 6. **设定时 (flow 06)** — Agent 用自己的 loop / cron 定时刷 7. **息屏 (flow 07)** — 推电子名片 + 设备深度休眠 0 功耗完整子流程在 [`flows/`](./flows/) 目录。Skill 主路由在 [`SKILL.md`](./SKILL.md)。 ## 16 种 Widget **工作日常**： - `weather` 天气 · `calendar` 今日日程 · `next-meeting` 下个会 - `todo` 待办 · `focus` 当前专注任务 · `deadlines` deadline 提醒 - `inbox` 收件箱 · `messages` 消息 · `pr-queue` PR 队列 - `git-status` git 状态 · `system` 系统状态 · `now-playing` 正在播放 **笔记 / 节奏**： - `scratch` 便签 · `break-reminder` 休息提醒 **AI 监控**： - `ai-status` 当前 AI session · `ai-tasks` AI 任务列表 **4 个槽位 / 2-1-1 布局**： ``` ┌────────────┬────────────┐ │ top-left │ top-right │ ← 270×280 各占半 ├────────────┴────────────┤ │ middle │ ← 540×340 整条 ├─────────────────────────┤ │ bottom │ ← 540×280 整条 ├─────────────────────────┤ │ bottom bar (chip 区) │ ← 60 px，含"睡眠""设置"chip └─────────────────────────┘ ``` 还有一个 `full`（540×960）覆盖全屏，用来推电子名片 / 启动 splash 等。完整 schema 在 [`plugin/skills/card-widget/schemas/`](./plugin/skills/card-widget/schemas/)。 ## 自动刷新（可选） Skill 第一次问你"想看哪些卡片、什么时段刷"时，会帮你写 `~/.ai-desk-card/interests.yaml`： ```yaml version: 1 slots: top-left: weather top-right: calendar middle: todo bottom: inbox schedule: cadence: "30m" # 5m / 15m / 30m / 1h / 2h hours: "08-22" days: "mon-fri" timezone: "Asia/Shanghai" data_sources: weather: city: "Beijing" calendar: source: "macos" # 或 google / ics-url todo: source: "reminders" # 或 things3 / todoist git_status: repo: "/Users/you/code/main-project" # 到 quiet_hours.start 自动切到电子名片 + deep sleep # daemon 后台自动处理，不需要 Agent 在线 quiet_hours: enabled: true start: "23:00" end: "07:00" ``` 定时触发方式： - **Agent 原生 loop（推荐）**：Claude Code 的 `/loop 30m`、`ScheduleWakeup` 等 - **cron**：`crontab -e` 加一行 `*/30 8-21 * * 1-5 bash /path/to/ai-desk-card/plugin/skills/card-refresh/scripts/refresh_loop.sh` - **纯 Python 无 AI 兜底**：weather / system / git 这几个不需要 AI，直接跑 `fallback_refresh.py` ## 三种供电模式 | 模式 | 状态 | 推帧延迟 | 续航 | |------|------|---------|------| | **A** 常插电 | USB-C 供电 + Wi-Fi 长开 | 0.2 s | n/a（供电中）| | **B** USB only | USB 数据线（还没配 Wi-Fi） | 1 s 区域 / 32 s 全帧 | n/a（供电中）| | **C** 电池 + BLE 待机 | Wi-Fi 关，daemon 通过 BLE 唤醒 | 5 s 唤醒 + 0.2 s 推 | ~6 个月 | 架构 C 是最爱：屏挂在桌边几个月不充电，AI Agent 推内容时 BLE 唤醒一次 → 拉 Wi-Fi → HTTP 推帧 → 30 秒 linger 后断 Wi-Fi。一次推送约 0.2 mAh，24 次/天 × 6 个月 = 1150 mAh 电池。 ## 目录结构 ``` ai-desk-card/ ├── SKILL.md ← 任意 Agent 的入口 ├── scripts/state.sh ← 状态探测：JSON 输出 daemon/transport/wifi/device/interests 状态 ├── flows/ ← 7 个子流程（每个 ~60-100 行） │ ├── 01_install.md 零状态硬件 + 固件烧录 │ ├── 02_transport.md daemon 连不上设备的诊断 │ ├── 03_wifi.md Wi-Fi 配网 │ ├── 04_interests.md interests.yaml 引导写入 │ ├── 05_push.md 推 widget 热路径 │ ├── 06_schedule.md 定时刷新协议 │ └── 07_sleep.md 电子名片 + deep sleep ├── plugin/ ← Claude Code 兼容层（slash 命令 + 共享脚本） │ ├── plugin.json │ ├── commands/ ← /card-* 命令 │ ├── scripts/ ← start.sh / stop.sh / status.sh │ └── skills/ ← 子 skill，由主 SKILL.md 间接调用 ├── daemon/ │ ├── card_daemon.py ← HTTP 桥 + 传输层 + 后台 loop │ ├── card_render.py ← widget view 渲染 │ ├── card_render_settings.py │ └── card_render_sleep.py ← 电子名片渲染 ├── src/ ← 固件 (frame_receiver / wifi / http / ble / 触屏 poll) ├── assets/ │ ├── profile.yaml ← 你的电子名片信息（息屏时显示） │ ├── qr.png ← 可选 QR │ └── avatar.png ← 可选头像 ├── data/cjk.ttf ← CJK 字体（首次烧到 LittleFS） ├── platformio.ini ├── partitions.csv ├── HANDOVER.md ← 工程交接 └── PRODUCT.md ← 产品定位 ``` ## 工作原理（一图看懂） ``` 你说话 M5Paper │ ▲ ▼ │ AI Agent ──────┐ │ │ 触发 Skill │ ▼ │ SKILL.md 路由表 │ │ │ │ scripts/state.sh 探测： │ │ · pio / firmware / daemon │ │ · device.alive / wifi │ │ · interests.yaml │ │ │ └─▶ 选 7 个子 flow 之一 │ │ │ ▼ │ Agent 自动执行 │ │ │ ▼ │ POST 到 daemon (127.0.0.1:9877) │ │ │ ▼ │ daemon 渲染（Python + Pillow） │ │ │ ▼ │ HTTP / USB / BLE 推帧 ───────────────┘ ``` ## FAQ **Q: 真的不用我自己烧固件？** 不用。装完 Skill 后跟 Agent 说"帮我装卡片"，Agent 会探测状态 → 装 PlatformIO（如果没装）→ `pio run -t upload` → 烧 CJK 字体 → 全程告诉你它在干什么。 **Q: 我没有 M5Paper V1.1，别的硬件可以吗？** M5Paper V1.0 大概率能用。M5Paper S3 需要移植（BLE stack 不同）。Inkplate / Waveshare 等其他 ESP32 + e-ink 板还没支持，roadmap 上有。 **Q: 必须用 Claude Code 吗？** 不必。`SKILL.md` 是 agent-agnostic 入口，任何识别这格式 + 有 shell 权限的 Agent 都能用（Codex / Cursor / Aider / 自写 Agent）。`plugin/` 里的 slash 命令是 Claude Code 用户的便利层，不是核心。 **Q: 网络情况？** 全本地。daemon 在你电脑上跑 (127.0.0.1:9877)，设备和电脑同 Wi-Fi LAN 直连。**ESP32 只支持 2.4 GHz**，5 GHz only 的 SSID 连不上。 **Q: 中文显示豆腐块？** 漏了烧 LittleFS 字体。跟 Agent 说"再跑一次 uploadfs"就好。 **Q: 怎么更新固件？** 跟 Agent 说"帮我更新 ai-desk-card 然后重新烧一次"。Skill 会拉新代码 + build + upload。 **Q: 不在 macOS 上能用吗？** daemon 在 Linux 也应该能跑（未深度测试）。Windows 需要 WSL2。烧固件部分 PlatformIO 跨平台。 **Q: 数据会上云吗？** 不会。daemon 默认绑 127.0.0.1（除了 device→daemon 的 status_report 走 LAN）。Wi-Fi 凭证写在设备 NVS，不会进 daemon 日志、不会进 git。 ## Roadmap - M5Paper V1.0 / S3 移植验证 - Inkplate / Waveshare 等其他 e-ink 板支持 - Captive portal Wi-Fi 配网（不用通过 daemon） - 硬件按钮长按 2s 关机时拦截 → 先推名片再 deep_sleep（Plan C） - 更多 widget schema（feishu / 微信 / Linear / Notion） - 多设备 dashboard 同步 ## 贡献欢迎 Issue 和 PR：https://github.com/op7418/ai-desk-card 最有价值的贡献： - 硬件实拍照 / 视频（帮新用户看清产品形态） - Linux / Windows 上 daemon 测试报告 - M5Paper V1.0 / S3 移植验证 - 新 widget schema + 渲染器 - 翻译 / 文档优化 ## License GPL-3.0 with attribution clause · 见 [LICENSE](./LICENSE) 内嵌 EPDGUI 框架（来自上游 M5Paper_FactoryTest）：MIT，© 2020 m5stack

IoT & Embedded AI Agents

101 Github Stars

Open Source

Claude-to-IM-skill

# Claude-to-IM Skill Bridge Claude Code / Codex to IM platforms — chat with AI coding agents from Telegram, Discord, Feishu/Lark, QQ, or WeChat. [中文文档](README_CN.md) > **Want a desktop GUI instead?** Check out [CodePilot](https://github.com/op7418/CodePilot) — a full-featured desktop app with visual chat interface, session management, file tree preview, permission controls, and more. This skill was extracted from CodePilot's IM bridge module for users who prefer a lightweight, CLI-only setup. --- ## How It Works This skill runs a background daemon that connects your IM bots to Claude Code or Codex sessions. Messages from IM are forwarded to the AI coding agent, and responses (including tool use, permission requests, streaming previews) are sent back to your chat. ``` You (Telegram/Discord/Feishu/QQ/WeChat) ↕ Bot API Background Daemon (Node.js) ↕ Claude Agent SDK or Codex SDK (configurable via CTI_RUNTIME) Claude Code / Codex → reads/writes your codebase ``` ## Features - **Five IM platforms** — Telegram, Discord, Feishu/Lark, QQ, WeChat — enable any combination - **Interactive setup** — guided wizard collects tokens with step-by-step instructions - **Permission control** — tool calls require explicit approval via inline buttons (Telegram/Discord) or text `/perm` commands / quick `1/2/3` replies (Feishu/QQ/WeChat) - **Streaming preview** — see Claude's response as it types (Telegram & Discord) - **Session persistence** — conversations survive daemon restarts - **Secret protection** — tokens stored with `chmod 600`, auto-redacted in all logs - **Zero code required** — install the skill and run `/claude-to-im setup`, or tell Codex `claude-to-im setup` ## Prerequisites - **Node.js >= 20** - **Claude Code CLI** (for `CTI_RUNTIME=claude` or `auto`) — installed and authenticated (`claude` command available) - **Codex CLI** (for `CTI_RUNTIME=codex` or `auto`) — `npm install -g @openai/codex`. Auth: run `codex auth login`, or set `OPENAI_API_KEY` (optional, for API mode) ## Installation Choose the section that matches the AI agent product you actually use. ### Claude Code #### Recommended: `npx skills` ```bash npx skills add op7418/Claude-to-IM-skill ``` After installation, tell Claude Code: ```text /claude-to-im setup ``` If you want WeChat specifically, you can also say: ```text 帮我接微信 ``` #### Alternative: clone directly into Claude Code skills ```bash git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.claude/skills/claude-to-im ``` Claude Code discovers it automatically. #### Alternative: symlink for development ```bash git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill mkdir -p ~/.claude/skills ln -s ~/code/Claude-to-IM-skill ~/.claude/skills/claude-to-im ``` ### Codex #### Recommended: use the Codex install script ```bash git clone https://github.com/op7418/Claude-to-IM-skill.git ~/code/Claude-to-IM-skill bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh ``` For local development with a live checkout: ```bash bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh --link ``` The install script places the skill under `~/.codex/skills/claude-to-im`, installs dependencies, and builds the daemon. After installation, tell Codex: ```text claude-to-im setup ``` If you want WeChat specifically, you can also say: ```text 帮我接微信桥接 ``` #### Alternative: clone directly into Codex skills ```bash git clone https://github.com/op7418/Claude-to-IM-skill.git ~/.codex/skills/claude-to-im cd ~/.codex/skills/claude-to-im npm install npm run build ``` ### Verify installation **Claude Code:** Start a new session and type `/` — you should see `claude-to-im` in the skill list. Or ask Claude: "What skills are available?" **Codex:** Start a new session and say `claude-to-im setup`, `start bridge`, or `帮我接微信桥接`. ## Updating the Skill Choose the update flow that matches both your AI agent product and your installation method. ### Claude Code If you installed with `npx skills`, re-run: ```bash npx skills add op7418/Claude-to-IM-skill ``` If you installed via `git clone` or symlink: ```bash cd ~/.claude/skills/claude-to-im git pull npm install npm run build ``` Then tell Claude Code: ```text /claude-to-im doctor /claude-to-im start ``` ### Codex If you installed with the Codex install script in copy mode: ```bash rm -rf ~/.codex/skills/claude-to-im bash ~/code/Claude-to-IM-skill/scripts/install-codex.sh ``` If you installed with `--link` or cloned directly into the Codex skills directory: ```bash cd ~/.codex/skills/claude-to-im git pull npm install npm run build ``` Then tell Codex: ```text claude-to-im doctor start bridge ``` ## Quick Start ### 1. Setup **Claude Code** ```text /claude-to-im setup ``` **Codex** ```text claude-to-im setup ``` The wizard will guide you through: 1. **Choose channels** — pick Telegram, Discord, Feishu, QQ, WeChat, or any combination 2. **Enter credentials** — the wizard explains exactly where to get each token, which settings to enable, and what permissions to grant 3. **Set defaults** — working directory, model, and mode 4. **Validate** — tokens are verified against platform APIs immediately ### 2. Start **Claude Code** ```text /claude-to-im start ``` **Codex** ```text start bridge ``` The daemon starts in the background. You can close the terminal — it keeps running. ### 3. Chat Open your IM app and send a message to your bot. Claude Code / Codex will respond through the bridge. When Claude needs to use a tool (edit a file, run a command), you'll see a permission prompt with **Allow** / **Deny** buttons right in the chat (Telegram/Discord), or a text `/perm` command prompt / quick `1/2/3` replies (Feishu/QQ/WeChat). ## Commands All commands are run inside Claude Code or Codex: | Claude Code | Codex (natural language) | Description | |---|---|---| | `/claude-to-im setup` | "claude-to-im setup" / "配置" | Interactive setup wizard | | `/claude-to-im start` | "start bridge" / "启动桥接" | Start the bridge daemon | | `/claude-to-im stop` | "stop bridge" / "停止桥接" | Stop the bridge daemon | | `/claude-to-im status` | "bridge status" / "状态" | Show daemon status | | `/claude-to-im logs` | "查看日志" | Show last 50 log lines | | `/claude-to-im logs 200` | "logs 200" | Show last 200 log lines | | `/claude-to-im reconfigure` | "reconfigure" / "修改配置" | Update config interactively | | `/claude-to-im doctor` | "doctor" / "诊断" | Diagnose issues | ## Platform Setup Guides The `setup` wizard provides inline guidance for every step. Here's a summary: ### Telegram 1. Message `@BotFather` on Telegram → `/newbot` → follow prompts 2. Copy the bot token (format: `123456789:AABbCc...`) 3. Recommended: `/setprivacy` → Disable (for group use) 4. Find your User ID: message `@userinfobot` ### Discord 1. Go to [Discord Developer Portal](https://discord.com/developers/applications) → New Application 2. Bot tab → Reset Token → copy it 3. Enable **Message Content Intent** under Privileged Gateway Intents 4. OAuth2 → URL Generator → scope `bot` → permissions: Send Messages, Read Message History, View Channels → copy invite URL ### Feishu / Lark 1. Go to [Feishu Open Platform](https://open.feishu.cn/app) (or [Lark](https://open.larksuite.com/app)) 2. Create Custom App → get App ID and App Secret 3. **Batch-add permissions**: go to "Permissions & Scopes" → use batch configuration to add all required scopes (the `setup` wizard provides the exact JSON) 4. Enable Bot feature under "Add Features" 5. **Events & Callbacks**: select **"Long Connection"** as event dispatch method → add `im.message.receive_v1` event 6. **Publish**: go to "Version Management & Release" → create version → submit for review → approve in Admin Console 7. **Important**: The bot will NOT work until the version is approved and published ### QQ > QQ currently supports **C2C private chat only**. No group/channel support, no inline permission buttons, no streaming preview. Permissions use text `/perm ...` commands. Image inbound only (no image replies). 1. Go to [QQ Bot OpenClaw](https://q.qq.com/qqbot/openclaw) 2. Create a QQ Bot or select an existing one → get **App ID** and **App Secret** (only two required fields) 3. Configure sandbox access and scan QR code with QQ to add the bot 4. `CTI_QQ_ALLOWED_USERS` takes `user_openid` values (not QQ numbers) — can be left empty initially 5. Set `CTI_QQ_IMAGE_ENABLED=false` if the underlying provider doesn't support image input ### WeChat / Weixin > WeChat currently uses QR login, single-account mode, text-based permissions, and no streaming preview. 1. Run the local QR helper from your installed skill directory: - Claude Code default install: `cd ~/.claude/skills/claude-to-im && npm run weixin:login` - Codex default install: `cd ~/.codex/skills/claude-to-im && npm run weixin:login` 2. The helper writes `~/.claude-to-im/runtime/weixin-login.html` and tries to open it in your browser automatically 3. Scan the QR code with WeChat and confirm on your phone 4. On success, the linked account is stored in `~/.claude-to-im/data/weixin-accounts.json` 5. Running the helper again replaces the previously linked WeChat account Additional notes: - `CTI_WEIXIN_MEDIA_ENABLED` controls inbound image/file/video downloads only - Voice messages only use WeChat's own built-in speech-to-text text - If WeChat does not provide `voice_item.text`, the bridge replies with an error instead of downloading/transcribing raw voice audio - Permission approvals use text `/perm ...` commands or quick `1/2/3` replies ## Architecture ``` ~/.claude-to-im/ ├── config.env ← Credentials & settings (chmod 600) ├── data/ ← Persistent JSON storage │ ├── sessions.json │ ├── bindings.json │ ├── permissions.json │ └── messages/ ← Per-session message history ├── logs/ │ └── bridge.log ← Auto-rotated, secrets redacted └── runtime/ ├── bridge.pid ← Daemon PID file └── status.json ← Current status ``` ### Key components | Component | Role | |---|---| | `src/main.ts` | Daemon entry — assembles DI, starts bridge | | `src/config.ts` | Load/save `config.env`, map to bridge settings | | `src/store.ts` | JSON file BridgeStore (30 methods, write-through cache) | | `src/llm-provider.ts` | Claude Agent SDK `query()` → SSE stream | | `src/codex-provider.ts` | Codex SDK `runStreamed()` → SSE stream | | `src/sse-utils.ts` | Shared SSE formatting helper | | `src/permission-gateway.ts` | Async bridge: SDK `canUseTool` ↔ IM buttons | | `src/logger.ts` | Secret-redacted file logging with rotation | | `scripts/daemon.sh` | Process management (start/stop/status/logs) | | `scripts/doctor.sh` | Health checks | | `SKILL.md` | Claude Code skill definition | ### Permission flow ``` 1. Claude wants to use a tool (e.g., Edit file) 2. SDK calls canUseTool() → LLMProvider emits permission_request SSE 3. Bridge sends inline buttons to IM chat: [Allow] [Deny] 4. canUseTool() blocks, waiting for user response (5 min timeout) 5. User taps Allow → bridge resolves the pending permission 6. SDK continues tool execution → result streamed back to IM ``` ## Troubleshooting Run diagnostics: ``` /claude-to-im doctor ``` This checks: Node.js version, config file existence and permissions, token validity (live API calls), log directory, PID file consistency, and recent errors. | Issue | Solution | |---|---| | `Bridge won't start` | Run `doctor`. Check if Node >= 20. Check logs. | | `Messages not received` | Verify token with `doctor`. Check allowed users config. | | `Permission timeout` | User didn't respond within 5 min. Tool call auto-denied. | | `Stale PID file` | Run `stop` then `start`. daemon.sh auto-cleans stale PIDs. | See [references/troubleshooting.md](references/troubleshooting.md) for more details. ## Security - All credentials stored in `~/.claude-to-im/config.env` with `chmod 600` - Tokens are automatically redacted in all log output (pattern-based masking) - Allowed user/channel/guild lists restrict who can interact with the bot - The daemon is a local process with no inbound network listeners - See [SECURITY.md](SECURITY.md) for threat model and incident response ## Development ```bash npm install # Install dependencies npm run dev # Run in dev mode npm run typecheck # Type check npm test # Run tests npm run build # Build bundle ``` ## License [MIT](LICENSE)

Developer Tools AI Agents Live Chat & Chatbots

2.7K Github Stars

Software by op7418

CodePilot

guizang-ppt-skill

guizang-social-card-skill

ai-desk-card

Claude-to-IM-skill