diff --git a/CHANGELOG.md b/CHANGELOG.md index 2228ea05..99947cd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,69 @@ +# v5.5.0 + +### 完全重新设计的部署与渠道绑定流程 + +- 初次安装时默认安装官方微信插件，用户使用个人微信扫码后即可启动第一个crew——main agent，直接在微信上就能使用 +- 后续的设定、更多crew的启用、渠道绑定等均可通过main agent完成（直接在微信上与它对话） +- 如果仅需要一个“个人助理”，或者不需要更大的AI crew团队（crew数量小于3），可以一直使用微信渠道，无需额外的操作 +- 工作渠道除支持飞书外，额外增加企业微信 +- 新增 WeCom channel 插件自动安装脚本（`install-wecom-channel.sh`），支持 pin 版本 + SHA-512 完整性校验，Main Agent 直接执行无需用户手动运行 `npx` +- main agent可以完整操作feishu、企业微信的配置（应用创建、凭据获取、权限配置、事件订阅、crew绑定全流程） + +### Designer + IT Engineer 全链路升级 + +**Designer 与 IT Engineer 的技能组合现已覆盖网页（官网 / 产品 Landing Page）的完整开发与生命周期管理：** + +> **设计** → **开发**（IT Engineer 通过 coding-agent）→ **部署**（云计算资源）→ **备案**（ICP）→ **SEO** + +#### Designer 升级 + +- Designer 从"配图+海报生成"重新定位为**系统性视觉设计体系构建者**，负责从零构建完整网页、APP 界面、品牌视觉体系 +- 新增 `design-system-picker` 技能：内置 15 套知名品牌设计系统（Stripe / Vercel / Linear / Notion / Apple / Supabase / Shopify / Figma / Spotify / Tesla / Framer / Airbnb / BMW / IBM / Starbucks），覆盖 fintech / devtools / productivity / consumer / luxury / enterprise / ecommerce / creative / media / automotive / lifestyle 全品类 +- 设计系统包含完整的 8 段规范（色彩、字体、组件、布局、层级、响应式等），所有 HTML/CSS 产出严格遵循选定设计系统的 token +- 支持从 [awesome-design-md](https://github.com/VoltAgent/awesome-design-md) 上游仓库查找并导入更多设计系统 +- Designer 改为纯 binding 模式运行，用户直接使用，其他 crew 不再 spawn Designer +- 简单出图需求（视频封面、海报等）统一使用 `siliconflow-img-gen`，无需启动 Designer +- 新增三大工作流：完整网页/落地页设计（A）、APP/产品界面设计（B）、品牌视觉体系构建（C） + +#### IT Engineer 升级 + +- 新增 `seo` 技能：技术 SEO 审计与优化（爬取、索引、结构化数据、Core Web Vitals、关键词映射） +- 新增 `icp-filing` 技能：ICP 备案全流程指导（材料清单、流程步骤、域名查询、备案号生成） +- 新增 `icp-exemption` 技能：Apple 国区 ICP 豁免申请附件 PDF 生成 +- 新增 `tccli` 技能：腾讯云 CLI 速查手册（CVM / Lighthouse / DNSPod / SSL / VPC 等 200+ 服务） +- 新增 `alicloud-find-skills` 技能：阿里云 Agent Skills 搜索、发现与安装 + +### Selfmedia Operator 增强 + +- 新增 `wx-mp-publish` 技能：**支持将微信公众号文章自动排版并直接推送至草稿箱**，实现从内容生产到公众号发布的一站式闭环 +- 新增 `t2video`（简单视频制作）技能：一站式短视频生产，整合 TTS 语音合成 + 素材搜集 + FFmpeg 组装 +- 新增 `highlight-clipper`（高光时刻视频制作）技能：支持从给定视频文件（录屏）中按语音自动剪辑高光时刻短视频 +- 大幅完善多平台发布技能，新增/增强支持：小红书（API 方式）、抖音、B站、快手、YouTube、TikTok、Instagram、Facebook、Threads、Pinterest 等 + +### Officials Addon 新crew + +- **business-developer**（商务拓展）正式发布：4.x版本的功能现在可以完全通过business-developer实现 +- **investor-relationship**（投资人关系）预发布 + +### crew 机制改进 + +- 启用 BOOTSTRAP.md 机制，每个crew根据自己职责设定，在启动初期会主动向用户搜集必要信息，如Selfmedia Operator搜集账号矩阵信息、IR和BD主动搜集公司、产品信息 +- skill 路径解析修复与加载机制优化 + +#### OpenClaw 升级至 v2026.5.28 + +- 基于 OpenClaw v2026.5.28（从 v2026.5.7 升级，跨越 6424 commits） +- Patches 004/005 针对 v2026.5.28 新文件结构重新生成，全部 5 个 patch 验证通过 +- awada extension 适配升级 + +### Bug 修复与改进 + +- `scripts` 脚本中诸多不当处修复与改进 +- `crew-recruit` / `crew-dismiss` SKILL.md 澄清 TEAM_DIRECTORY.md 由脚本内部自动同步，无需 agent 手动更新 +- HRBP `add-agent.sh` 新增 business-context symlink 和 crew MEMORY.md 背景说明自动注入 + +--- + # v5.4.9 ### 升级 openclaw 至 v2026.5.7 @@ -88,7 +154,7 @@ ### 新增 -- **新媒体运营 Crew 模板（selfmedia-operator）**：内置文生图（siliconflow-img-gen）、文生视频（siliconflow-video-gen）技能，提供完整的选题研究→图文输出、草稿扩写→完整文章两套工作流；配图优先策略（用户素材 > 免版权图片 > AI 生成 > 历史复用），素材统一归档至 `campaign_assets/` +- **新媒体运营 Crew 模板（selfmedia-operator）**：内置文生图（siliconflow-img-gen）技能，文生视频（siliconflow-video-gen）已迁移至 video-producer crew；提供完整的选题研究→图文输出、草稿扩写→完整文章两套工作流；配图优先策略（用户素材 > 免版权图片 > AI 生成 > 历史复用），素材统一归档至 `campaign_assets/` - **smart-search 新增平台**：百度贴吧（全局搜索 + 指定吧搜索）、Amazon（含分类/排序过滤），YouTube 新增类型过滤（shorts/video/channel）及"最近1小时"时间过滤 diff --git a/README.md b/README.md index eecf356e..c9c3491c 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,39 @@ # Wiseflow -🚀 **v5.4.9 更新** +🚀 **v5.5.0 更新** -- 升级 openclaw 至 v2026.5.7（近期最稳版本），所有 patch 干净应用 -- install.sh 大幅优化，新用户 onboard 更简单，完整支持 macOS -- 模型方案锁定 DeepSeek + SiliconFlow 最佳实践，内置 config-template -- 修复 v5.4.8 诸多 bug；预发布 business-developer / investor-relations 两个新 crew +- **从安装到出活，全程微信对话完成**：首次部署时自动安装官方微信插件，扫码绑定后，Wiseflow Main Agent 直接在微信上引导你完成业务背景采集、团队组建、渠道配置——不再需要编辑任何配置文件。 +- 如果只是想要一个个人助理、或者使用场景比较简单（crew 数量不超过 3 个），可以一直使用微信渠道，无需额外申请飞书开放平台或企业微信（后续如需扩展，Main Agent 也会给出申请和开通的详细指导） +- **Designer 升级**：从"出图工具"重新定位为**系统性视觉设计体系构建者**，内置 `design-system-picker` 技能，预置 15 套品牌设计系统（覆盖 fintech / devtools / productivity / consumer / luxury / enterprise 等全品类），一键匹配风格后从零构建完整网页、APP 界面、品牌视觉体系 +- **IT Engineer 升级**：新增SEO、ICP备案辅助、云服务资源管理能力，现在 Designer + IT Engineer 的技能组合可覆盖官网 / Landing Page 的完整流程——**设计 → 开发 → 部署（云计算）→ 备案（ICP）→ SEO** +- **Selfmedia Operator 增强**：新增微信公众号文章自动排版并推送至草稿箱、简单短视频制作（t2video）、高光时刻视频剪辑（highlight-clipper），现已支持 15 个国内外主流自媒体平台的发布能力（部分为pro版本提供） +- **商务拓展 + 投资人关系正式发布**：business-developer 继承 4.x 全部核心能力（指定信源监控、行业情报采集、社交媒体潜客挖掘），并新增业务介绍 PPT 制作能力；investor-relationship 预发布 详见 [CHANGELOG.md](CHANGELOG.md) --- -即刻拥有一只 7×24 在线工作的 AI 员工团队，包括： - -幕僚长、HRBP、IT-Engineer、商务拓展、销售型客服、自媒体运营、平面设计师、投资人关系……（不断增加中） +## what's wiseflow - +Wiseflow 是基于 [openclaw](https://github.com/openclaw/openclaw) 的 Multi-Agent 系统，为 **所有被/或即将为 AI 时代冲击、需要独立拓展收入来源的个体** 打造——被裁员/降薪的职场人、副业探索者、自媒体个体户、小生意人、刚毕业的年轻人…… -> 📌 **寻找 4.x 版本？** 原版 v4.32 及之前版本的代码在 [`4.x` 分支](https://github.com/TeamWiseFlow/wiseflow/tree/4.x)中。 +> **对于 99% 的人来说，人工智能技术带来的其实是灾难** +> +> 这不是危言耸听。历史上每一次技术变革——蒸汽机、电力、互联网——无一例外都让会用它的人赚得更多，不会用的人被甩得更远。因为技术本质上是杠杆：有资本、有资源的人能第一时间装备自己，效率翻倍；而普通人连反应的时间都没有，就已经被替代了。AI 时代只会把这个规律放大到极致——99% 的输家，1% 的赢家。这非常不公平、也不合理。然而遗憾的是，这场变革已经无法被停止，那么，我们能做点什么？ +> +> 本项目的立意是**为普通人提供一支AI搞钱团队**，以对抗AI技术发展带来的日益严峻的贫富差距。我们号召整个开源社区与我们一起为普通人而战，用技术对抗权贵！ -``` -“吾生也有涯，而知也无涯。以有涯随无涯，殆已！“ —— 《庄子·内篇·养生主第三》 -``` +我们不贩卖焦虑，也不承诺捷径。挣钱的本质从来是提供价值——你干了那么多年的事、攒下的经验、对某个领域的判断，那才是真有价值的。问题是：一个人有经验、有方法，但时间和精力终究有限。 -## what's wiseflow +wiseflow 目前能为你提供的是： +- AI自动化获客：**商务拓展** 挖客户 → **自媒体运营** 铺声量 → **销售客服** 促转化 → **HRBP** 调策略 → **IT Engineer** 保运行 +- 业务支撑与保障：**设计师** 搭官网/落地页 → **IT Engineer** 搞 ICP 备案、服务器管理、SEO 优化 -wiseflow 是基于 [openclaw](https://github.com/openclaw/openclaw) 的一套旨在面向真实营业场景的Multi-Agent（多智能体）系统（MAS），支持部署后对外提供 7*24 营业业务，内置自动化网络推广与销售型客服 Agent. + -*wiseflow 又名 openclaw_for_business，简称 ofb* +> 📌 **寻找 4.x 版本？** 原版 v4.32 及之前版本的代码在 [`4.x` 分支](https://github.com/TeamWiseFlow/wiseflow/tree/4.x)中。 -> openclaw很强，能够帮你收发邮件、写报告、控制智能家居……但是讲真，这是你最需要的吗？ -> -> 让 AI 帮我们 “搞钱”才是王道！ -> -> **本项目的目的不是为你增加一个“个人助理”，而是为你打造一直“云上牛马”团队，可以 7*24 小时给你在线搞钱的那种！** +--- ## 🌟 快速开始 @@ -60,20 +60,45 @@ cd wiseflow - 初始化 `openclaw.json`（内置最佳模型配置，无需手动编辑） - 安装系统 daemon（开机自启 + 崩溃重启） - **交互式引导你输入** `DEEPSEEK_API_KEY` 和 `SILICONFLOW_API_KEY`（仅在首次或缺失时询问） +- 安装腾讯官方 `openclaw-weixin` extension，并引导扫码绑定 > **调试模式**（单次启动，适合测试）：`./scripts/dev.sh gateway` > **系统要求**：推荐 Ubuntu 22.04；支持 WSL2 / macOS；不建议 Windows 原生 -🎉 大功告成！ +### 3. 微信对话完成 Onboard + +安装完成后，打开微信搜索上一步绑定的机器人，直接发消息即可——它会主动引导你完成首次 onboard**： + +1. 告诉它你的公司/品牌、产品和目标用户 +2. 它会把这些业务背景存入 `business-context/`，后续招募的 crew 自动继承 +3. 按需招募第一个 crew（如商务拓展、自媒体运营） +4. 团队扩大后，一条对话即可配置飞书或企业微信工作 channel + +**不需要编辑配置文件、不需要手动同步信息——从安装到出活，全程对话完成。** + +注：微信官方 openclaw 插件限定一个微信账号只能对应一个机器人，如果您之前已经绑定了其他 Agent（openclaw 或者 hermes 等），这会挤掉已经绑定的 agent。但是在完成 wiseflow 团队配置后，您可以将此 bot 替换回其他 agent，这不影响已经绑定工作渠道的 wiseflow crew team。 -安装后如何用参考 [quick start](docs/quick_start.md)。 +> 💡 更详细的操作指引见 [quick start](docs/quick_start.md) + +### 系统与环境要求 + +| 项目 | 最低要求 | 推荐配置 | +|------|---------|---------| +| CPU | 2 核 | 4 核 | +| 内存 | 8 GB | 16 GB | +| 可用硬盘 | 40 GB | 120 GB | +| 带宽 | 10 Mbps | — | + +- **网络**：需可访问外网；建议使用正常住宅 IP，数据中心 IP 部分平台可能识别限制 +- **部署环境**：支持无头云服务器（ECS）部署，但推荐在有桌面环境的电脑上部署（日常使用中可不插显示器），浏览器自动化类技能在桌面环境下更稳定 +- **操作系统**：推荐 Ubuntu 24.04；支持 Windows WSL2、macOS 15 / 26 > **💡 模型费用说明** > > wiseflow5.x 底层基于 openclaw，Agent 工作流对 token 消耗有一定要求，建议先准备好大模型 API： > -> - **主力模型（强烈推荐）**：[DeepSeek 官方 API](https://platform.deepseek.com/) — 综合性能、速度、性价比最优。高缓存命中机制，实际应用成本可控。需要注册并充值获得 `DEEPSEEK_API_KEY`，大部分任务使用 `deepseek-v4-flash` 足够，IT Engineer 技术排查时使用 `deepseek-v4-pro`。 +> - **主力模型（强烈推荐）**：[DeepSeek 官方 API](https://platform.deepseek.com/) — 综合性能、速度、性价比最优。高缓存命中机制，实际应用成本可控。需要注册并充值获得 `DEEPSEEK_API_KEY`。 > - **替补 & 视觉模型**：[SiliconFlow](https://cloud.siliconflow.cn/i/WNLYbBpi) — 模型丰富，可作为 DeepSeek 的 fallback，同时提供视觉理解模型（`Qwen/Qwen3.6-27B`）和生图/生视频 API。需要注册获得 `SILICONFLOW_API_KEY`。 > > 🎁 以上 SiliconFlow 链接为 wiseflow 邀请链接，通过此链接注册，你和 wiseflow 项目各可获得一张 16 元代金券。 > @@ -81,9 +106,9 @@ cd wiseflow > > 配置模板已预置以上最佳实践，`install.sh` 会自动检测所需环境变量并引导你输入。安装后重启 openclaw gateway 即可生效。 -🎉 wiseflow 目前提供付费知识库，包含《手把手从零开始安装教程》、《安装之后三分钟上手指南》、《Openclaw自定义配置全案教程》、《Windows 下安装 WSL2 无脑教程》以及各种高阶独门秘籍等，年费仅需¥168，还能加入 **vip微信交流群** ，共同探讨交流各种玩法，还有每月一次的闭门分享（腾讯会议），陪伴你从“小白“到“大神“！ +🎉 wiseflow 目前提供付费知识库，包含《手把手从零开始安装教程》、《安装之后三分钟上手指南》、《Openclaw自定义配置全案教程》、《Windows 下安装 WSL2 无脑教程》、《秘籍：云服务器（ECS）部署》以及各种最佳实践分享，年费仅需¥168，还能加入 **vip微信交流群** ，共同探讨交流各种玩法，还有每月一次的闭门分享（腾讯会议），陪伴你从“小白“到“大神“！ -欢迎添加”掌柜的“企业微信（这背后接的就是 wiseflow）咨询了解： +欢迎添加”掌柜的“企业微信（这背后接的就是 wiseflow sales-cs）咨询了解： wiseflow掌柜 @@ -91,46 +116,60 @@ cd wiseflow ## ✨ 创新点 -原版 openclaw，包括国内各大厂推出的基于 openclaw 的“虾”，它们的定位都是“个人助理”（personal AI assistant），也即适合服务你自己，但并不适合替你服务别人，因此也就没办法替你搞钱。 - -wiseflow 专为打造可在线 7*24 小时搞钱的目的而生，我们在原版的基础上以补丁、配置模板、专属技能等方式（但不改原版一行代码，以保证完全的兼容性）做了如下改进： +Wiseflow 在 openclaw 基础上以addon、配置模板、专属技能等方式（不改上游一行代码，保证完全兼容性）做了如下改进： #### “Crew”的概念 -- Crew 是绑定了专属工作指导和技能组合的Agent - -> 原版openclaw是把所有技能（包括内置和用户自定义安装的）绑定到同一个 Agent 上，Agent Spawn 出的 subagent 也默认继承所有技能。但这会造成两个问题：1、臃肿，代表着每一轮对话都更加耗费 token、模型思考时间也会更长并且更容易出错；2、如果 Agent 是提供对外服务的，那么会很危险，想象外部客户可以通过 Agent 操控你家的的智能家居或者连通你的打印机……当然你可以通过原版的配置禁用这些技能，然而为什么要让一个，比如说客服 Agent 拥有连接智能家居和打印机的技能？ - -wiseflow 的做法是提供 `Crew Template`，针对每个 crew 的应用目的（客服、新媒体运营、财务报税）提供专属的 skill（很多是我们定制开发的）和基础的工作指导、人设，并留给用户充分的“调教”空间。 - -- `全局内置 crew` 负责服务你和其他 crew，相当于公司的中后台。这里面有三个是内置且全局唯一的，负责提供最基础的支撑，相当于公司的管理层： - - Main Agent，负责管理所有对内 crew 的生命周期，你也可以把它当成唯一对话入口，通过它喊其他 Crew 干活； - - IT Engineer，负责帮你搞定 openclaw 繁琐的配置，日常运维（升级、定时心跳检查状态）等，**对，你没看错，只要你完成第一次部署，后面它就可以帮你去做系统配置和运维** - - HRBP，负责帮你招募、管理对外服务 crew，还能帮你周期性质的扫描对外服务 crew 的 feedback，不断升级他们…… - - 以上三个内置 crew 我们都已经提供了现成的最佳配置（角色定义文件、SKills、权限等） - -- `addons/officials/crew/` 提供的 crew，是帮你“搞钱”的。 - - `sales customer service`（销售导向客服）：不是单纯回答客户咨询的客服，以促进成交为目的，会在咨询答疑过程中以用户无感的巧妙话术促进销售、调研用户来源、记录客户信息，并具有发起收款和确认收款的能力； - - `selfmedia operator`（自媒体运营）：不仅仅能够帮你写稿、生图，它能够随时记录你的灵感，你无意中看到的素材也可以随手转发给它，它都会记住并应用在后续产出中，并且它还能**自动完成在各个自媒体平台发布**的工作； - - `designer`（设计师）：专注视觉创意设计，结合 AI 生图能力提供配图、海报、品牌素材生成服务； - - `business developer`（商务拓展）： 主动出击，每日在各自媒体平台寻找潜在客户并主动勾搭，还能监控竞争对手、采集行业情报、生成业务介绍 ppt 等； - - `Investor Relations`(投资人关系)：帮你在线寻找并冷接触投资人、在线填报各种申请表、生成精美的 BP…… - - 更多能够帮你在线搞钱的 crew template 陆续发布中…… - -> 说实话，市面上有很多基于 openclaw 的二开项目都支持多 crew（Agent），甚至还支持让这些 crew（Agent） 自主协同，或者带个办公室界面，你能看到他们在一起“过家家”……我认为这些都太华而不实了! 如果不能搞钱，一个 Agent Team 跟一个 chatbot 一样，只是玩具而已！ - -看看基于 wiseflow 免费开源的 sales-cs crew template “调教“出的销售型客服有多智能！ - - - -注意，我们没有使用FAQ，也没有workflow，这是纯粹的harness工程。 +原版 OpenClaw 定位是 **personal AI assistant**——个人助理。但个人助理和工作场景是很不一样的：工作场景的技能不要求丰富，但要求稳定、专业；不同的工作要对应不同的定义约束和技能组合，即不同岗位需要使用不同的 harness。 + +Wiseflow 的做法是提供 `Crew Template`，针对每个岗位提供专属 skill 和工作指导，并留给用户充分的调教空间。 + +目前 wiseflow 内置如下 crew，可以按需启用： + +| Crew | 职责 | 关键技能 | +|------|------|---------| +| Main Agent（微信上的那个，默认启用，全局唯一） | 管理所有 crew 生命周期，唯一对话入口 | crew 招募/管理、渠道配置 | +| IT Engineer（默认启用，全局唯一，可协助其他 crew 排障） | 系统运维、配置、故障排查 | seo、icp-filing、icp-exemption、tccli、alicloud-find-skills、session-logs | +| HRBP | 招募管理对外 crew，周期扫描 feedback 升级 | crew-recruit、crew-modify、crew-remove、crew-list、crew-usage | +| 商务拓展 | 客户挖掘端 | 社交媒体潜客挖掘、竞品监控、行业情报、生成业务介绍 PPT | +| 自媒体运营 | 内容生产端 | 写稿、生图、15 个平台自动发布、t2video（短视频）、highlight-clipper（高光剪辑） | +| 设计师 | 视觉设计端 | 15 套品牌设计系统、完整网页/APP/品牌视觉体系构建 | +| 销售型客服 | 获客转化端 | 自动回复促进成交、调研用户来源、记录客户信息、发起/确认收款 | +| 投资人关系 | 融资端 | 寻找投资人、冷接触、填报申请表、生成 BP | +| Video Producer* | 专业视频端 | 专业短视频制作 | + +> *\* 标记的 crew 由 Pro 版本提供* + +
+ 自媒体运营 — 支持的社交媒体平台（15 个） + + | 平台 | 发布方式 | + |------|---------| + | 微信公众号 | API + wenyan-cli 渲染 | + | 企业微信朋友圈* | API | + | 小红书* | API | + | 抖音 | API（OAuth2） | + | B站* | Web API | + | 快手* | Web API | + | 今日头条 | 浏览器 + CDP | + | 掘金 | 浏览器 | + | Twitter/X | 浏览器 | + | YouTube | YouTube Data API v3 | + | TikTok | Content Posting API | + | Instagram | Meta Graph API | + | Facebook | Meta Graph API | + | Threads | Meta Graph API | + | Pinterest | Pinterest API v5 | + + > *\* 标记的平台发布技能由 Pro 版本提供，开源版不包含* + +
有关”多 crew 机制”设计，详见[CREW TYPE DESIGN](docs/crew-system.md) #### Crew 之间的自主协作 -我们巧妙的利用了 OpenClaw 的 Spawn Subagent 机制实现了 crew 之间的自主互助能力，这意味着： +我们巧妙的利用了 OpenClaw 的 Spawn Subagent 机制实现了 crew 之间的自主协作能力，这意味着： Crew 遇到自己不能解决的问题： ```text @@ -166,7 +205,7 @@ Crew 遇到自己不能解决的问题： 原版openclaw的使用和维护并不简单，尤其对于非技术用户而言，充满暗坑，最受诟病的是**安全性**和**安装部署**，为此我们也做了不少改进： -- **安全** +##### 安全 我们采用三重命令执行机制，**权限由 `exec-approvals.json` + `tools.exec` 自动强制执行**，不单单是角色定义中告知。 @@ -176,22 +215,24 @@ Crew 遇到自己不能解决的问题： |------|------|----------|-----------| | T0 | read-only | `security: deny` — 默认禁止所有 shell 命令 | external crews（默认） | | T1 | basic-shell | `security: allowlist` — 仅允许只读命令 | low-risk internal crews | -| T2 | dev-tools | `security: allowlist` — 开发工具链 + 只读命令 | main | -| T3 | admin | `security: full` — 完整系统操作 | it-engineer, hrbp | +| T2 | dev-tools | `security: allowlist` — 开发工具链 + 只读命令 | main, hrbp，selfmedia-operator... | +| T3 | admin | `security: full` — 完整系统操作 | it-engineer | -**易用性脚本** +##### 易用性脚本 - **配置模板** — 预设国内可用的模型、渠道、技能等配置 - **工具脚本** — 一键启动、一键部署、一键更新…… -**🩹 wiseflow 内置补丁与可配置环境变量** +##### wiseflow 内置补丁与可配置环境变量 wiseflow 通过 `patches/` 目录对 openclaw 源码打补丁，每次运行 `apply-addons.sh` 时自动应用。以下是当前生效的补丁及其可配置项： | 补丁 | 说明 | 相关环境变量 | |------|------|-------------| +| `001-relax-exec-allowlist-shell-syntax` | 放宽 exec-approvals 的 shell 语法限制，允许 `$()`、反引号、重定向等常用写法 | 无 | | `002-disable-web-search-env-var` | 支持通过环境变量禁用 openclaw 内置 web search | `OPENCLAW_DISABLE_WEB_SEARCH=1` | | `003-act-field-validation` | 修复浏览器 act 动作的字段验证逻辑 | 无 | +| `004-chrome-port-grace-retry` | Chrome CDP 端口占用时优雅重试，避免因端口冲突导致浏览器启动失败 | 无 | | `005-browser-timeout-env-var` | 支持通过环境变量自定义浏览器操作默认超时（原默认仅 20 秒，网络慢时容易中断） | `OPENCLAW_BROWSER_TIMEOUT_MS=60000` （执行 install.sh 脚本会自动配置）| #### 浏览器增强 @@ -220,12 +261,6 @@ https://github.com/user-attachments/assets/8d097b3b-f9ab-42eb-98bb-88af5d28b089 详见 [awada readme](awada/README.md) -#### Addon 机制与生态 - -wiseflow 不改上游（openclaw）代码，一切改造和增强都通过 `addon` 机制完成，这最大化的保障了兼容性，也即是说：wiseflow 无缝支持**从 clawhub.ai安装技能**。 - -wiseflow 代码仓会不会更新、添加 [official addons](addons/officials), 我们也欢迎社区贡献更多 addon，第三方也可以通过 add-on 向 wiseflow 用户发放 crew template，参见 [Addon 开发](docs/addon_development.md)。 - ## 目录结构 ``` @@ -288,6 +323,7 @@ wiseflow/ - opencli（A CLI for social media & web platforms — smart-search skill 借鉴了其搜索 URL 模式与平台适配方案） https://github.com/jackwener/opencli - 文颜(Markdown文章排版美化工具，支持微信公众号、今日头条、知乎等平台。) https://github.com/caol64/wenyan - Everything Claude Code（Claude Code 全局 skill / rule / agent 集合，wiseflow 的 complex-task 等编排 skill 借鉴了其 blueprint 和 gan-style-harness 的设计思路） https://github.com/affaan-m/everything-claude-code +- awesome-design-md（A curated collection of design systems in markdown format — Designer 内置设计系统库参考了此项目的设计系统结构） https://github.com/VoltAgent/awesome-design-md ## Citation diff --git a/addons/officials/README.md b/addons/officials/README.md index e5edb436..a1eaea13 100644 --- a/addons/officials/README.md +++ b/addons/officials/README.md @@ -10,7 +10,6 @@ wiseflow 开源社区版本自带的官方 addon，在 wiseflow 默认全局技 |------|------|------------|----------| | `rss-reader` | RSS/Atom Feed 读取，支持订阅任意标准 feed 格式的内容源 | — | 全部 crew 可用 | | `siliconflow-img-gen` | 文生图、图片修改（SiliconFlow API） | `SILICONFLOW_API_KEY` | designer、selfmedia-operator | -| `siliconflow-video-gen` | 文生视频 / 图生视频（SiliconFlow API） | `SILICONFLOW_API_KEY` | selfmedia-operator | | `connections-optimizer` | 人脉关系网络优化与拓展建议 | — | **仅 business-developer**；其余 crew DENIED | | `email-ops` | 批量邮件撰写与 SMTP 发送 | `SMTP_SERVER` `SMTP_USER` `SMTP_PASSWORD` | **仅 business-developer**；其余 crew DENIED | | `pitch-deck` | 融资/商务演示文稿生成，支持读取 .pptx 文件内容 | — | **仅 business-developer**；其余 crew DENIED | @@ -53,11 +52,11 @@ wiseflow 开源社区版本自带的官方 addon，在 wiseflow 默认全局技 - 两种工作模式：选题研究 → 图文输出 / 草稿扩写 → 完整文章 - 配图优先级：用户上传 > 网络免版权 > AI 生成（siliconflow-img-gen）> 历史素材复用 -- 视频生成：通过 `siliconflow-video-gen` 生成短视频（文生视频 / 图生视频） +- 视频制作：通过 `t2video` 技能完成短视频制作（TTS 语音合成 + AI 视频片段生成 + 素材组装） - 素材统一归档到 `campaign_assets/`，维护 index.md 方便复用 - 支持自动发布到知乎/头条/掘金/Medium（wenyan-publisher）、Twitter、Instagram、TikTok、YouTube -专属技能：`wenyan-publisher` / `twitter-post` / `instagram-post` / `tiktok-post` / `youtube-upload` +专属技能：`wenyan-publisher` / `twitter-post` / `instagram-post` / `tiktok-post` / `youtube-upload` / `t2video` --- @@ -156,9 +155,11 @@ wiseflow 开源社区版本自带的官方 addon，在 wiseflow 默认全局技 --- -## AI 生图 / 生视频服务推荐 +## AI 生图服务推荐 -`siliconflow-img-gen` 和 `siliconflow-video-gen` 两个技能依赖 [SiliconFlow](https://cloud.siliconflow.cn/i/WNLYbBpi) API，用于文生图、图片修改以及文生视频 / 图生视频。 +`siliconflow-img-gen` 技能依赖 [SiliconFlow](https://cloud.siliconflow.cn/i/WNLYbBpi) API，用于文生图、图片修改。 + +`siliconflow-video-gen` 和 `siliconflow-tts` 已迁移为 video-producer（official-plus addon）内置技能。开源版 `selfmedia-operator` 内置的 `t2video` 技能同样集成了 SiliconFlow 视频生成和 TTS 能力。 [硅基流动（SiliconFlow）](https://cloud.siliconflow.cn/i/WNLYbBpi) 提供国内领先的生图和生视频模型，注册并实名认证即可领取免费代金券。 diff --git a/addons/officials/addon.json b/addons/officials/addon.json index 4f8cc055..1a7a985e 100644 --- a/addons/officials/addon.json +++ b/addons/officials/addon.json @@ -1,9 +1,9 @@ { "name": "wiseflow officials", "version": "0.4.1", - "description": "官方 Crew 模板（selfmedia-operator / business-developer / designer / ir / sales-cs）+ 专属全局技能（rss-reader / siliconflow-img-gen / siliconflow-video-gen / pexels-footage / pixabay-footage / connections-optimizer / email-ops / pitch-deck / ppt-maker / social-graph-ranker / xhs-interact）", - "openclaw_version": "2026.5.7", - "openclaw_commit": "eeef4864494f859838fec1586bedbab1f8fa5702", + "description": "官方 Crew 模板（selfmedia-operator / business-developer / designer / ir / sales-cs）+ 专属全局技能（rss-reader / siliconflow-img-gen / pexels-footage / pixabay-footage / connections-optimizer / email-ops / pitch-deck / ppt-maker / social-graph-ranker / xhs-interact / xianyu-ops）", + "openclaw_version": "2026.5.28", + "openclaw_commit": "e93216080aa1f425d3ab127014603eba8e365b2d", "auto-activate": false, "internal_crews": ["business-developer", "designer", "ir", "selfmedia-operator"], "external_crews": ["sales-cs"] diff --git a/addons/officials/crew/business-developer/AGENTS.md b/addons/officials/crew/business-developer/AGENTS.md index 83dcf340..8d2a9e5d 100644 --- a/addons/officials/crew/business-developer/AGENTS.md +++ b/addons/officials/crew/business-developer/AGENTS.md @@ -28,13 +28,15 @@ --- -## 模式一：Lead Hunting（通过创作者探索潜在客户） +## 模式一：Lead Hunting（潜在客户探索） ### 初始化对话流程 #### Phase 1: 收集基础信息 -用户告知要搜索的平台和客户画像。支持平台： +询问用户以下信息： + +1. **目标平台**（多选）： | 标识 | 平台 | |------|------| @@ -45,15 +47,31 @@ | fb | Facebook | | x | Twitter/X | | wb | 微博 | -| web | 网页 | +| web | 网页（需要有用户给出具体的站点） | + +2. **搜集策略**（二选一，不可组合）： + +| 策略 | 说明 | 可搜集信息 | +|------|------|-----------| +| A. 发布者画像匹配 | 上溯帖子发布者主页，判断发布者是否符合目标用户画像 | 昵称、user_id、主页信息（简介、关注量、粉丝量、获赞量等）、主页内容 | +| B. 评论区潜客挖掘 | 嵌入帖子评论区，根据评论内容寻找潜在用户 | 昵称、user_id、IP属地、评论内容、评论日期、原贴url | + +⚠️ 两种策略不兼容——搜索关键词完全不同，不可混用。如需同时使用两种策略，应作为两个独立任务分别配置。 + +3. **潜在客户画像/特征**（越具体越好）： + - 策略 A：描述目标客户是什么样的人、做什么、关注什么 + - 策略 B：描述目标客户可能在什么内容的帖子下留言、会说什么样的话 **必须问到**： - 目标平台（多选） -- 潜在客户画像/特征（越具体越好） +- 搜集策略（A 或 B） +- 潜在客户画像/特征 #### Phase 2: 分析并确认 -根据用户提供的画像，分析并**输出给用户确认**： +根据用户选择的搜集策略，分别进行分析并**输出给用户确认**： + +**策略 A（发布者画像匹配）**： 1. **各平台搜索关键词**：为每个目标平台单独构思 - 符合用户画像的创作者可能在平台上发布什么内容？这些内容通过哪些关键词可以搜索到？ @@ -62,21 +80,38 @@ - 每个平台列出 3-5 组关键词 - 对于 `web`，如果用户指定站点，则优先使用站点内的搜索框 -2. **潜在客户判定标准**：明确如何通过创作者主页和作品判定是否为潜在客户 +2. **潜在客户判定标准**： + - 明确如何通过创作者主页和作品判定是否为潜在客户 - 特别关注区分真实客户和同行/竞对（发布类似内容但实为同行） - 列出：哪些特征说明是客户、哪些特征说明是同行（应排除） +**策略 B（评论区潜客挖掘）**： + +1. **各平台搜索关键词**：为每个目标平台单独构思 + - 目标用户可能在什么内容的帖子下留言？搜索这些帖子需要什么关键词？ + - 注意：策略 B 的关键词与策略 A 完全不同——策略 A 搜"目标用户发布的内容"，策略 B 搜"目标用户会去评论的内容" + - 例如：找装修客户时，策略 A 搜"装修日记""新房装修"，策略 B 搜"装修避坑""装修求助""新房交付" + - 每个平台列出 3-5 组关键词 + +2. **评论筛选标准**： + - 哪类评论内容表明评论者可能是潜在客户 + - 例如：咨询类评论（"怎么买""多少钱"）、需求表达类评论（"正好需要""求推荐"） + - 列出：哪些评论特征应纳入、哪些应排除（如同行互推、无关灌水） + 用户确认（或按反馈修改）后进入 Phase 3。 #### Phase 3: 收集执行参数 逐项询问： 1. **探索频率**：多久执行一次？（不超过一天 6 次，避免平台封号） -2. **每次最大探索量**：每次探索的创作者数量（含不符合的），建议不超过 12 个 +2. **每次最大探索量**： + - 策略 A：每次探索的创作者数量（含不符合的），建议不超过 12 个 + - 策略 B：每次扫描的帖子数量（含无符合评论的），建议不超过 12 个 3. **反馈形式**： - - **A. 列表报告**：潜在客户信息（昵称、ID、主页链接等）列表反馈，用户自行联系 - - **B. Cold Touch 私信**：直接以私信方式联系潜在客户 - - **C. 解析email 地址并发送 email**： 如果能够解析出创作者的 email 地址，则发送 email 进行联系 + - **A. 列表报告**：潜在客户信息列表反馈，用户自行联系 + - **B. Cold Touch 私信**：直接以私信方式联系潜在客户（xhs 不支持） + - **C. 解析email 地址并发送 email**：如果能够解析出创作者的 email 地址，则发送 email 进行联系 + - ⚠️ 小红书平台仅支持 **A. 列表报告** 如用户选择 B： - 询问是否有现成话术 @@ -96,11 +131,13 @@ ## 模式二：Comment Engagement（评论区拓展） +> ⚠️ **小红书不支持此模式**：小红书平台会自动删除评论区的营销回复，无法通过评论或私信与用户互动。如用户仅指定 xhs，应引导至模式一的策略 B（评论区潜客挖掘）。 + ### 初始化对话流程 #### Phase 1: 收集基础信息 -询问目标平台（多选，同模式一平台列表）和要搜索的内容类型。 +询问目标平台（多选，同模式一平台列表，**不含 xhs**）和要搜索的内容类型。 #### Phase 2: 分析并确认 @@ -203,9 +240,3 @@ ### 人脉优化与社交线索 使用 `connections-optimizer` 和 `social-graph-ranker` 技能，进行人脉分析和社交关系梳理。 - ---- - -## sessions_spawn 规范 - -> 禁止传入 `streamTo` 参数 —— 在 subagent 模式下该参数不支持。spawn 时只传 agentId 和 task 内容即可。 diff --git a/addons/officials/crew/business-developer/BOOTSTRAP.md b/addons/officials/crew/business-developer/BOOTSTRAP.md index 22422155..0a32ed50 100644 --- a/addons/officials/crew/business-developer/BOOTSTRAP.md +++ b/addons/officials/crew/business-developer/BOOTSTRAP.md @@ -1,20 +1,43 @@ -# Bootstrap +# BusinessDeveloper Bootstrap -This is a pre-configured crew workspace. Review these files at startup: +This one-time bootstrap collects the business context before BD work starts. If this crew is being enabled through Main Agent and has no direct work channel yet, Main Agent may ask these questions on behalf of this crew and write the answers into the crew workspace. -- **SOUL.md** — Role definition, core responsibilities, and autonomy level -- **AGENTS.md** — Workflows and operating procedures -- **MEMORY.md** — Background context and historical records -- **IDENTITY.md** — Name and persona -- **USER.md** — Assumptions about who you are serving -- **TOOLS.md** — Available tools, usage rules, and required environment variables +## Step 1: Company & Business Context -## First-Run Checklist +Collect: -On first startup: -1. Check `SILICONFLOW_API_KEY` is set → required for LLM content generation -2. For Cold Outreach: check SMTP env vars are set (`SMTP_SERVER`, `SMTP_USER`, `SMTP_PASSWORD`) +- company/brand name; +- product or service introduction (one-line positioning); +- target customer profile; +- key selling points / differentiators; +- brand tone for outreach communications; +- forbidden claims or sensitive topics to avoid; +- competitors or differentiation notes. + +## Step 2: Outreach Readiness + +Ask: + +- Is SMTP configured for cold email outreach? If not, explain that email outreach mode will be unavailable until SMTP is set up. +- Should the crew start in draft-only mode (collect leads but not contact them) or is direct outreach approved? +- For direct outreach: does the user have existing outreach templates/talking points, or should the crew draft them for review? + +## Step 3: Environment Verification + +On first startup, check and report: + +1. `SILICONFLOW_API_KEY` is set → required for LLM content generation +2. For Cold Outreach: check SMTP env vars (`SMTP_SERVER`, `SMTP_USER`, `SMTP_PASSWORD`) 3. Verify `send_email.py` dependency: `python3 -c "import smtplib; print('ok')"` (built-in, always ok) 4. Create output directories: `mkdir -p outreach_data` If SMTP is not configured, affiliate marketing mode still works fully. + +## Completion + +After bootstrap is complete: + +1. Update `MEMORY.md` with company/business background and SMTP status. +2. Update `USER.md` with organization info (replace `<待填充>` placeholder). +3. Delete `BOOTSTRAP.md` from the runtime workspace. +4. Suggest the next step, such as setting up the first Lead Hunting task. diff --git a/addons/officials/crew/business-developer/BUILTIN_SKILLS b/addons/officials/crew/business-developer/BUILTIN_SKILLS index 81fe392f..7db978e2 100644 --- a/addons/officials/crew/business-developer/BUILTIN_SKILLS +++ b/addons/officials/crew/business-developer/BUILTIN_SKILLS @@ -14,3 +14,4 @@ info-record login-manager wx-mp-hunter pitch-deck +council \ No newline at end of file diff --git a/addons/officials/crew/business-developer/HEARTBEAT_TEMPLATE.md b/addons/officials/crew/business-developer/HEARTBEAT_TEMPLATE.md index 26d2c052..39af454e 100644 --- a/addons/officials/crew/business-developer/HEARTBEAT_TEMPLATE.md +++ b/addons/officials/crew/business-developer/HEARTBEAT_TEMPLATE.md @@ -13,22 +13,29 @@ **状态**：已启用 +**搜集策略**： + **目标平台**： -- xhs：<关键词1>、<关键词2>、<关键词3> +- xhs：<关键词1>、<关键词2> - dy：<关键词1>、<关键词2> - web：<站点URL>：<搜索关键词> **潜在客户判定标准**： -- 符合特征： - - <特征描述1> - - <特征描述2> -- 排除特征（同行/竞对）： - - <特征描述1> +- 策略 A（发布者画像匹配）： + - 符合特征： + - <特征描述1> + - 排除特征（同行/竞对）： + - <特征描述1> +- 策略 B（评论区潜客挖掘）： + - 纳入评论特征： + - <特征描述1> + - 排除评论特征： + - <特征描述1> **执行参数**： - 频率：<每天N次 / 每N小时> -- 每次最大探索量： -- 反馈形式：<列表报告 / Cold Touch 私信 / Email 联系> +- 每次最大探索量： +- 反馈形式：<列表报告 / Cold Touch 私信 / Email 联系>（策略 B 及 xhs 仅支持列表报告） - Cold Touch 话术：<话术内容> - Email 话术：<话术内容> @@ -39,14 +46,16 @@ ## 模式二：Comment Engagement（评论区拓展） +> ⚠️ 小红书不支持此模式。 + ```markdown ### 模式二：Comment Engagement（评论区拓展） **状态**：已启用 **目标平台**： -- xhs：<关键词1>、<关键词2> - dy：<关键词1> +- fb：<关键词1> **互动策略**： diff --git a/addons/officials/crew/business-developer/MEMORY.md b/addons/officials/crew/business-developer/MEMORY.md index fe37c102..d4866e6a 100644 --- a/addons/officials/crew/business-developer/MEMORY.md +++ b/addons/officials/crew/business-developer/MEMORY.md @@ -1,12 +1,10 @@ # BusinessDeveloper — Memory -## 用户偏好与配置 +## 公司与业务背景信息 -（首次使用后由 Business Developer 在此记录） + -- 公司/组织信息：（待记录） -- 产品/业务介绍：（待记录） -- 默认联系信息：（待记录） +--- ## 模式一：Lead Hunting 历史 @@ -42,5 +40,5 @@ ## 技术环境备注 -- SMTP 配置状态：（待记录） +- SMTP 配置状态：（由 BOOTSTRAP 检测写入） - 数据库位置：`./db/bd_record.db`、`./db/info_record.db` diff --git a/addons/officials/crew/business-developer/USER.md b/addons/officials/crew/business-developer/USER.md index 62b22263..93d31ea2 100644 --- a/addons/officials/crew/business-developer/USER.md +++ b/addons/officials/crew/business-developer/USER.md @@ -6,7 +6,7 @@ - 用户身份：公司决策者 / 业务负责人 - 你的角色：他的业务拓展执行手——他说要开拓哪个方向，你就代表公司去执行 -- 组织信息（公司名称、业务介绍、联系方式等）<待填充> +- 组织信息（公司名称、业务介绍、联系方式等）<由 BOOTSTRAP 收集填充> ## What They Expect @@ -20,4 +20,4 @@ - 初始化对话时主动引导用户完整表达需求 - 分析结果（关键词、判定标准、话术）结构化输出，方便用户审阅 - 定时任务执行后汇总报告，不实时发送进度 -- 遇到障碍及时告知用户 +- 遇到障碍及时告知用户 \ No newline at end of file diff --git a/addons/officials/crew/business-developer/skills/bd-record/SKILL.md b/addons/officials/crew/business-developer/skills/bd-record/SKILL.md index 25af02d7..b3b2bd08 100644 --- a/addons/officials/crew/business-developer/skills/bd-record/SKILL.md +++ b/addons/officials/crew/business-developer/skills/bd-record/SKILL.md @@ -13,7 +13,7 @@ description: 维护 business-developer 的 SQLite 追踪数据库，记录已探 ./db/bd_record.db ``` -首次使用需先初始化：`bash ./skills/bd-record/scripts/init-db.sh` +初始化（幂等，可重复执行）：`./skills/bd-record/scripts/init-db.sh` --- @@ -55,20 +55,20 @@ description: 维护 business-developer 的 SQLite 追踪数据库，记录已探 ### 初始化数据库 ```bash -bash ./skills/bd-record/scripts/init-db.sh +./skills/bd-record/scripts/init-db.sh ``` ### 模式一：创作者记录 **检查创作者是否已记录**： ```bash -bash ./skills/bd-record/scripts/check-creator.sh --platform <平台> --creator-id <创作者ID> +./skills/bd-record/scripts/check-creator.sh --platform <平台> --creator-id <创作者ID> ``` 返回 JSON：`{"exists": true/false}` **记录创作者**： ```bash -bash ./skills/bd-record/scripts/record-creator.sh \ +./skills/bd-record/scripts/record-creator.sh \ --platform <平台> \ --creator-id <创作者ID> \ --nickname <昵称> \ @@ -82,13 +82,13 @@ bash ./skills/bd-record/scripts/record-creator.sh \ **检查帖子是否已互动**： ```bash -bash ./skills/bd-record/scripts/check-post.sh --platform <平台> --post-url <帖子URL> +./skills/bd-record/scripts/check-post.sh --platform <平台> --post-url <帖子URL> ``` 返回 JSON：`{"exists": true/false, "replied": true/false}` **记录互动**： ```bash -bash ./skills/bd-record/scripts/record-post.sh \ +./skills/bd-record/scripts/record-post.sh \ --platform <平台> \ --post-title <标题> \ --post-url <帖子URL> \ diff --git a/addons/officials/crew/business-developer/skills/comment-engagement/SKILL.md b/addons/officials/crew/business-developer/skills/comment-engagement/SKILL.md index fc6da16e..aeebe7e8 100644 --- a/addons/officials/crew/business-developer/skills/comment-engagement/SKILL.md +++ b/addons/officials/crew/business-developer/skills/comment-engagement/SKILL.md @@ -28,7 +28,7 @@ description: 通过自媒体平台搜索内容，在评论区以留言/回复/ ``` 1. 读取 HEARTBEAT.md 获取当前配置 2. 确保浏览器可用（遵循 browser-guide） -3. 初始化 bd-record 数据库：bash ./skills/bd-record/scripts/init-db.sh +3. 初始化 bd-record 数据库（幂等）：./skills/bd-record/scripts/init-db.sh ``` ### Step 2: 逐平台搜索 @@ -55,7 +55,7 @@ description: 通过自媒体平台搜索内容，在评论区以留言/回复/ 1. 提取帖子标识（platform, post_url, post_title） 2. 去重检查： - bash ./skills/bd-record/scripts/check-post.sh --platform <平台> --post-url <帖子URL> + ./skills/bd-record/scripts/check-post.sh --platform <平台> --post-url <帖子URL> 如果 {"replied": true}，则跳过 3. 导航到帖子详情页 @@ -69,7 +69,7 @@ description: 通过自媒体平台搜索内容，在评论区以留言/回复/ 5. 等待 1-2 秒确认评论发出 6. 记录互动： - bash ./skills/bd-record/scripts/record-post.sh \ + ./skills/bd-record/scripts/record-post.sh \ --platform <平台> \ --post-title <标题> \ --post-url <帖子URL> \ diff --git a/addons/officials/crew/business-developer/skills/info-record/SKILL.md b/addons/officials/crew/business-developer/skills/info-record/SKILL.md index 0b8c5f0b..072297c0 100644 --- a/addons/officials/crew/business-developer/skills/info-record/SKILL.md +++ b/addons/officials/crew/business-developer/skills/info-record/SKILL.md @@ -13,7 +13,7 @@ description: 维护 business-developer 的 SQLite 情报采集数据库，记录 ./db/info_record.db ``` -首次使用需先初始化：`bash ./skills/info-record/scripts/init-db.sh` +初始化（幂等，可重复执行）：`./skills/info-record/scripts/init-db.sh` --- @@ -41,20 +41,20 @@ description: 维护 business-developer 的 SQLite 情报采集数据库，记录 ### 初始化数据库 ```bash -bash ./skills/info-record/scripts/init-db.sh +./skills/info-record/scripts/init-db.sh ``` ### 检查内容是否已采集 ```bash -bash ./skills/info-record/scripts/check-content.sh --source <信源URL或标识> +./skills/info-record/scripts/check-content.sh --source <信源URL或标识> ``` 返回 JSON：`{"exists": true/false}` ### 记录采集内容 ```bash -bash ./skills/info-record/scripts/record-content.sh \ +./skills/info-record/scripts/record-content.sh \ --source <信源URL或标识> \ --source-type <信源类型> \ --title <标题> \ @@ -67,7 +67,7 @@ bash ./skills/info-record/scripts/record-content.sh \ ### 查询今日采集 ```bash -bash ./skills/info-record/scripts/query-today.sh +./skills/info-record/scripts/query-today.sh ``` 返回今日采集的所有记录（JSON 数组格式）。 diff --git a/addons/officials/crew/business-developer/skills/intel-gathering/SKILL.md b/addons/officials/crew/business-developer/skills/intel-gathering/SKILL.md index 031d3dfe..8603defc 100644 --- a/addons/officials/crew/business-developer/skills/intel-gathering/SKILL.md +++ b/addons/officials/crew/business-developer/skills/intel-gathering/SKILL.md @@ -27,7 +27,7 @@ description: 定时监控特定信源（自媒体账号/网页），按预设标 ``` 1. 读取 HEARTBEAT.md 获取当前配置（信源列表、提取标准、交付形式） 2. 确保浏览器可用（遵循 browser-guide） -3. 初始化 info-record 数据库：bash ./skills/info-record/scripts/init-db.sh +3. 初始化 info-record 数据库（幂等）：./skills/info-record/scripts/init-db.sh ``` ### Step 2: 逐信源采集 @@ -47,7 +47,7 @@ description: 定时监控特定信源（自媒体账号/网页），按预设标 a. 提取内容标识（source=平台-账号, title, author, publish_date） b. 去重检查： - bash ./skills/info-record/scripts/check-content.sh --source <内容URL> + ./skills/info-record/scripts/check-content.sh --source <内容URL> 如果 {"exists": true}，跳过该内容 c. 打开内容详情页 @@ -58,7 +58,7 @@ description: 定时监控特定信源（自媒体账号/网页），按预设标 - 提取与标准相关的关键信息 e. 记录采集结果： - bash ./skills/info-record/scripts/record-content.sh \ + ./skills/info-record/scripts/record-content.sh \ --source <内容URL> \ --source-type <平台标识> \ --title <标题> \ @@ -73,7 +73,7 @@ description: 定时监控特定信源（自媒体账号/网页），按预设标 ``` 1. 对于 RSS 支持的网站：使用 rss-reader 技能获取最新文章 - node {baseDir}/scripts/fetch-rss.mjs --limit 10 + node ./skills/intel-gathering/scripts/fetch-rss.mjs --limit 10 2. 对于不支持 RSS 的网站： a. 使用 browser 导航到网页 @@ -91,7 +91,7 @@ description: 定时监控特定信源（自媒体账号/网页），按预设标 ``` 1. 查询当日所有采集信息： - bash ./skills/info-record/scripts/query-today.sh + ./skills/info-record/scripts/query-today.sh 2. 按 HEARTBEAT.md 中预设的交付形式生成交付物： diff --git a/addons/officials/crew/business-developer/skills/lead-hunting/SKILL.md b/addons/officials/crew/business-developer/skills/lead-hunting/SKILL.md index a93bae60..010fe4ab 100644 --- a/addons/officials/crew/business-developer/skills/lead-hunting/SKILL.md +++ b/addons/officials/crew/business-developer/skills/lead-hunting/SKILL.md @@ -1,11 +1,11 @@ --- name: lead-hunting -description: 通过自媒体平台搜索内容创作者，按预设关键词和判定标准筛选潜在客户。用于 HEARTBEAT 定时任务。 +description: 通过自媒体平台按搜集策略探索潜在客户——策略 A 分析帖子发布者画像，策略 B 从评论区挖掘潜客。用于 HEARTBEAT 定时任务。 --- # Lead Hunting 技能 -通过自媒体平台搜索特定关键词内容，逐一分析创作者主页，按预设标准判定是否为潜在客户。 +通过自媒体平台搜索特定关键词内容，按搜集策略筛选潜在客户。策略 A 逐一分析创作者主页判定是否为潜在客户；策略 B 扫描帖子评论区，根据评论内容挖掘潜在客户。 **依赖技能**：`smart-search`（构造搜索 URL）、`browser-guide`（浏览器操作）、`email-ops`（email 操作）、`bd-record`（去重记录） @@ -14,8 +14,9 @@ description: 通过自媒体平台搜索内容创作者，按预设关键词和 ## 前置条件 执行前需确认 HEARTBEAT.md 中已配置以下信息： +- 搜集策略（A 发布者画像匹配 / B 评论区潜客挖掘） - 目标平台列表及对应的搜索关键词 -- 潜在客户判定标准 +- 潜在客户判定标准 / 评论筛选标准 - 每次最大探索量 - 反馈形式（列表报告 / Cold Touch 私信 / Email 联系） @@ -26,9 +27,9 @@ description: 通过自媒体平台搜索内容创作者，按预设关键词和 ### Step 1: 准备工作 ``` -1. 读取 HEARTBEAT.md 获取当前配置（平台、关键词、判定标准、最大探索量） +1. 读取 HEARTBEAT.md 获取当前配置（搜集策略、平台、关键词、判定标准、最大探索量） 2. 确保浏览器可用（遵循 browser-guide） -3. 初始化 bd-record 数据库：bash ./skills/bd-record/scripts/init-db.sh +3. 初始化 bd-record 数据库（幂等）：./skills/bd-record/scripts/init-db.sh ``` ### Step 2: 逐平台搜索 @@ -44,7 +45,7 @@ description: 通过自媒体平台搜索内容创作者，按预设关键词和 - 提取每个内容的创作者主页链接 ``` -### Step 3: 逐创作者判定 +### Step 3 (策略 A): 逐创作者判定 对每个搜索到的创作者，按顺序执行： @@ -52,7 +53,7 @@ description: 通过自媒体平台搜索内容创作者，按预设关键词和 1. 提取创作者标识信息（平台、creator_id、nickname、homepage_url） 2. 去重检查： - bash ./skills/bd-record/scripts/check-creator.sh --platform <平台> --creator-id <创作者ID> + ./skills/bd-record/scripts/check-creator.sh --platform <平台> --creator-id <创作者ID> 如果 {"exists": true}，则跳过该创作者，继续下一个 3. 导航到创作者主页，等待加载 @@ -69,7 +70,7 @@ description: 通过自媒体平台搜索内容创作者，按预设关键词和 - 判定为潜在客户需给出明确理由 7. 记录到数据库（不管是否符合标准）： - bash ./skills/bd-record/scripts/record-creator.sh \ + ./skills/bd-record/scripts/record-creator.sh \ --platform <平台> \ --creator-id <创作者ID> \ --nickname <昵称> \ @@ -80,15 +81,52 @@ description: 通过自媒体平台搜索内容创作者，按预设关键词和 8. 操作间隔：每个创作者之间保持 30-60 秒间隔，避免平台风控 ``` +### Step 3 (策略 B): 逐帖子评论区挖掘 + +对每个搜索到的帖子，按顺序执行： + +``` +1. 提取帖子标识（platform, post_url, post_title） + +2. 导航到帖子详情页，等待评论区加载 + +3. 如果支持按时间排序，切换到按时间排序，确保评论从新到旧排列 + +4. 滚动浏览评论区，查找符合 HEARTBEAT.md 中评论筛选标准的评论： + - 提取评论者信息：昵称、user_id、IP属地、评论内容、评论日期 + +5. 对每条符合标准的评论： + a. 以评论者 user_id 作为 --creator-id 做去重检查： + ./skills/bd-record/scripts/check-creator.sh --platform <平台> --creator-id <评论者user_id> + 如果 {"exists": true}，则跳过该评论者 + + b. 记录到数据库： + ./skills/bd-record/scripts/record-creator.sh \ + --platform <平台> \ + --creator-id <评论者user_id> \ + --nickname <昵称> \ + --homepage-url <原贴URL> \ + --qualified <1或0> \ + --notes <评论内容及判定理由> + +6. 操作间隔：每个帖子之间保持 30-60 秒间隔，避免平台风控 +``` + ### Step 4: 汇总报告 ``` -1. 统计本批次结果：探索总数、符合数、跳过数（已记录） +1. 统计本批次结果： + - 策略 A：探索总数、符合数、跳过数（已记录） + - 策略 B：扫描帖子数、发现潜客数、跳过数（已记录） + 2. 列出所有符合标准的潜在客户： - - 平台、昵称、ID、主页 URL、判定理由 -3. 按 HEARTBEAT.md 中配置的反馈形式执行： + - 策略 A：平台、昵称、ID、主页 URL、判定理由 + - 策略 B：平台、昵称、user_id、IP属地、评论内容、评论日期、原贴url + +3. 按 HEARTBEAT.md 中配置的反馈形式执行（仅策略 A 支持 Cold Touch 私信 / Email 联系）： - **Cold Touch 私信**：逐一给符合标准的创作者发送预设话术私信，使用各平台的私信/消息功能，每个私信之间保持 30-60 秒间隔 - **Email 联系**：先校验 `email-ops` 所需环境变量是否齐全，若不全则跳过 Email 步骤并记录；齐全则使用 `email-ops` 发送邮件，每个邮件之间保持 30-60 秒间隔 + 4. 使用 message 工具将汇总报告发送给用户 ``` diff --git a/addons/officials/crew/designer/AGENTS.md b/addons/officials/crew/designer/AGENTS.md index 8af13d23..b6200d41 100644 --- a/addons/officials/crew/designer/AGENTS.md +++ b/addons/officials/crew/designer/AGENTS.md @@ -1,144 +1,175 @@ # 设计师 — Workflow -## 素材积累与归档 +## 通用规则 -所有设计产出统一存储在 `design_assets/` 中，并维护 `design_assets/index.md`。 +### 任务文件夹 -**目录结构**： -``` -design_assets/ -├── index.md # 全局素材索引 -├── references/ # 参考图 / 灵感截图（来源标注） -├── brand/ # 品牌资产（Logo、色板、字体说明） -└── YYYY-MM-DD-<任务>/ # 各任务输出目录 - ├── *.png / *.jpg # 成品图 - └── prompts.json # 生图参数记录 -``` - -`index.md` 格式： - -| Instance ID | 内容概要 | Type | 文件路径 | 来源/Prompt | 创建日期 | -|-------------|---------|------|---------|------------|---------| - -Type 枚举：`海报` | `封面` | `Banner` | `配图` | `网页原型` | `改图` | `参考图` - ---- - -## 工作流 A：AI 出图（文生图 / 改图） +**每项设计任务必须先创建独立文件夹**，所有产出归档其中： +```bash +./skills/init-workspace/scripts/init.sh <任务名> ``` -1. 接收需求，确认三要素（若缺失则追问）： - - 使用场景（公众号封面 / 小红书配图 / 活动海报 / 产品 Banner ...） - - 风格偏好（写实 / 极简 / 插画 / 赛博朋克 / 国潮 / 商务 ...） - - 尺寸要求（若无则按场景自动推断） - -2. 从 MEMORY.md 调取品牌色、字体偏好等已知规范 - -3. 起草 2–3 套提示词方案，向用户展示提示词（L2 预确��，可跳过） - -4. 调用 siliconflow-img-gen 生成： - - 单需求通常生成 2 张（--batch-size 2，Kolors 模型）供选择 - - 改图需求：附带原图 URL，使用 Qwen 改图模型 -5. 将结果路径告知用户，展示图片（Read 工具内联图片） +产出目录结构： -6. 根据反馈：调整提示词迭代（最多 3 轮），或接受交付 - -7. 归档到 design_assets/ 并更新 index.md +``` +design_assets/YYYY-MM-DD-<任务名>/ +├── brief.md # 设计需求文档（必须填写，确认后不可跳过） +├── DESIGN.md # 设计系统文档（色彩、字体、组件、间距规范） +├── source/ # 原始素材（参考图、品牌资产） +└── output/ # 成品输出（HTML/CSS 文件、组件预览页） ``` ---- - -## 工作流 B：海报设计 +### Brief 确认机制 -``` -1. 接收海报需求，确认： - - 主题文案（活动名、核心 slogan、时间地点等关键信息） - - 目标平台与尺寸（线上 / 印刷 / 朋友圈 / 展架 ...） - - 风格方向（提供 1–3 个参考词，如"科技感+深色系"） +1. 接到需求后，将需求整理写入 `brief.md` +2. **将 brief 发给用户确认**，等待明确同意 +3. 确认前不得进入后续步骤 +4. 后续视觉 review 以 brief 为基准对照 -2. 搜索竞品 / 灵感参考（smart-search → Dribbble / Pinterest） - 将参考图保存到 design_assets/references/ +### 设计系统选取流程 -3. 设计提示词时结合：主题文案 + 品牌色 + 参考风格 + 文字排版说明 - 注意：提示词写明"留有文字排版区域"（AI 生成的文字不可靠） +每项任务开始时，必须先确定设计系统： -4. 生成 2–3 个版本（风格/色调各有差异） +1. 分析用户需求中的风格描述（如"类似 Stripe 的风格""科技感暗色主题"） +2. 调用 `design-system-picker` 技能，从内置设计系统库中匹配最合适的 1-3 个 +3. 将匹配结果及推荐理由展示给用户，等待确认 +4. 用户也可指定参考品牌或自定义风格，Designer 据此生成定制 DESIGN.md -5. 向用户展示各版本（附设计思路说明），等待 L2 确认选版 +### 视觉 Review 机制 -6. 根据确认版本进行： - - 直接交付（若文案由用户自行在图片编辑器添加） - - 或输出含文字的最终版（用户提供文案后重新生成） +生成页面/组件后**必须**调用视觉模型 review，不得跳过： -7. 归档并更新 index.md -``` +1. 用 `image` 工具查看生成结果 +2. 对照 `brief.md` 和 `DESIGN.md` 逐项检查：风格一致性、组件规范遵循度、响应式表现、交互状态完整性 +3. 发现偏差 → 调整 CSS token 或 HTML 结构后重新输出（最多 3 轮） +4. Review 通过 → 发送给用户 --- -## 工作流 C：网页 / 落地页设计 +## 工作流 A：完整网页 / 落地页设计 ``` -1. 接收需求，确认： - - 页面类型（产品介绍页 / 活动落地页 / 团队介绍 / 404 页 ...） - - 交互功能范围（纯静态展示 / 含表单 / 含轮播 ...） - - 风格参考（可提供网址或描述） +1. 接收需求 → 调用 init-workspace 创建任务文件夹 +2. 将需求整理为 brief.md，包含： + - 页面类型（产品介绍页/活动落地页/团队介绍/404 页...） + - 页面清单与信息架构（Sections 列表） + - 交互功能范围（纯静态展示/含表单/含轮播...） + - 风格参考（可提供品牌名或描述词） - 是否需要深色模式 - -2. 从 MEMORY.md 获取品牌色、字体、LOGO URL 等品牌资产 - -3. 规划页面结构（Sections 列表），向用户确认信息架构（L2） - -4. 编写 HTML + CSS： - - CSS custom properties 定义设计 token（颜色、间距、字号） + - 品牌约束（品牌色、字体、LOGO — 从 MEMORY.md 获取） +3. 将 brief 发给用户确认，等待明确同意 +4. 设计系统选取： + a. 调用 design-system-picker 匹配设计系统 + b. 展示匹配结果，等待用户确认选择 + c. 将选定的设计系统规范写入任务 DESIGN.md +5. 素材获取： + - 页面所需配图/背景图 → pexels-footage / pixabay-footage 优先，siliconflow-img-gen 备选 + - 下载/生成的图片保存到 source/ 目录 +6. 编写 HTML + CSS： + - CSS custom properties 定义设计 token（颜色、间距、字号、阴影）——严格遵循 DESIGN.md - 语义化标签（header / main / section / footer） - 响应式（min-width: 768px / 1024px 断点） - - hover / focus 状态 - - 图片用 siliconflow-img-gen 生成后内联路径 - -5. 将文件保存到 design_assets/web/YYYY-MM-DD-<页面名称>/index.html - 告知用户：`open design_assets/web/.../index.html` 本地预览 - -6. 展示完整代码，等待 L2 确认 - -7. 根据反馈修改（CSS 细节 / 文案替换 / 颜色调整） + - hover / focus / active 状态 + - 图片引用 source/ 中的素材 +7. 视觉 Review（对照 brief.md + DESIGN.md） +8. 发给用户，根据反馈迭代修改 +9. 最终确认后将文件保存到任务文件夹 output/ 目录，归档并更新 index.md ``` --- -## 工作流 D：改图 / 素材适配 +## 工作流 B：APP / 产品界面设计 ``` -1. 接收参考图（URL 或本地路径）与改图指令 - 常见指令：换色调 / 换背景 / 去除水印 / 风格迁移 / 尺寸裁切 - -2. 根据改图类型选择处理方案： - - 风格/颜色修改 → siliconflow-img-gen 改图模式（--image 参数） - - 尺寸裁切/格式转换 → 告知用户需要本地图片工具（如 ImageMagick）或 IT Engineer 协助 - -3. 生成改图结果，展示对比（原图 vs 改图） - -4. 归档到 design_assets/，更新 index.md +1. 接收需求 → 调用 init-workspace 创建任务文件夹 +2. 将需求整理为 brief.md，包含： + - 产品类型（移动 APP / Web APP / 管理后台 / SaaS 面板...） + - 核心页面清单（登录/首页/列表/详情/设置...） + - 交互模式（导航方式、手势支持、状态管理...） + - 风格参考 + - 品牌约束 +3. 将 brief 发给用户确认，等待明确同意 +4. 设计系统选取（同工作流 A 步骤 4） +5. 编写 DESIGN.md 设计规范： + - 色彩系统（语义色名 + hex + 用途：primary/secondary/surface/error/...） + - 字体系统（font-family + 层级表：display/heading/body/caption/overline） + - 间距系统（4px/8px/12px/16px/24px/32px/48px 基准） + - 组件样式规范（Button/Input/Card/Nav/Modal/Toast 等，含各状态） + - 阴影/圆角/动效规范 +6. 编写关键页面 HTML + CSS 原型： + - 严格遵循 DESIGN.md 中的 token + - 移动端优先（如为 APP 界面，按 375px 基准设计） + - 包含交互状态（hover/focus/disabled/loading） +7. 视觉 Review（对照 brief.md + DESIGN.md） +8. 发给用户，根据反馈迭代 +9. 最终交付：DESIGN.md + 所有页面 HTML/CSS → 保存到 output/ ``` --- -## Image Prompt 最佳实践 +## 工作流 C：品牌视觉体系构建 ``` -结构：[主体] + [环境/背景] + [风格] + [色调] + [构图] + [质量修饰词] +1. 接收需求 → 调用 init-workspace 创建任务文件夹 +2. 将需求整理为 brief.md，包含： + - 品牌定位（行业、目标客群、核心价值） + - 风格方向（1-3 个关键词，如"专业+科技+温暖"） + - 现有品牌资产（Logo、已有色彩偏好等） + - 应用场景（官网/APP/社交媒体/印刷品...） +3. 将 brief 发给用户确认，等待明确同意 +4. 设计系统选取（同工作流 A 步骤 4） +5. 构建完整 DESIGN.md： + - Visual Theme & Atmosphere：设计哲学、情感基调、密度 + - Color Palette & Roles：语义名 + hex + 功能角色 + - Typography Rules：字体族 + 完整层级表 + - Component Stylings：核心组件样式 + 状态 + - Layout Principles：间距系统、网格、留白哲学 + - Depth & Elevation：阴影系统、表面层级 + - Responsive Behavior：断点、触控目标、折叠策略 + - Do's and Don'ts：设计护栏 +6. 编写组件预览页面（preview.html）： + - 展示色彩色板、字体层级、按钮/卡片/输入框等核心组件 + - 包含亮色和暗色两种表面 +7. 视觉 Review +8. 发给用户，根据反馈迭代 +9. 最终交付：DESIGN.md + preview.html → 保存到 output/ + - 将 DESIGN.md 核心信息同步到 MEMORY.md 的 Brand Assets 区 +``` -推荐修饰词（高质量通用）： - "high resolution, sharp details, professional photography, - cinematic lighting, 8K, trending on Behance" +--- -推荐负向提示词（避免低质）： - "blurry, watermark, text, ugly, low quality, - distorted, oversaturated, plastic" +## CSS 设计 Token 规范 + +所有 HTML/CSS 产出必须使用 CSS Custom Properties 定义设计 token： + +```css +:root { + /* 语义色彩 */ + --color-primary: oklch(...); + --color-surface: oklch(...); + --color-text: oklch(...); + + /* 字体层级 */ + --text-display: clamp(3rem, 1rem + 7vw, 8rem); + --text-body: clamp(1rem, 0.9rem + 0.5vw, 1.125rem); + + /* 间距系统 */ + --space-xs: 4px; + --space-sm: 8px; + --space-md: 16px; + --space-lg: 24px; + --space-xl: 32px; + --space-2xl: 48px; + + /* 动效 */ + --duration-normal: 300ms; + --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); +} ``` ## 品牌规范应用原则 -- 若 MEMORY.md 中有品牌色/字体记录 → 在提示词中强制指定 -- 若无 → 第一次出图后，询问用户是否认可当前色调，认可则记入 MEMORY.md -- 活动海报与日常配图可有创意空间，但 Logo/主色不得随意替换 +- 若 MEMORY.md 中有品牌色/字体记录 → 在 DESIGN.md 和 CSS token 中强制指定 +- 若无 → 第一次设计后，询问用户是否认可当前色彩体系，认可则记入 MEMORY.md +- 核心品牌色/Logo 不得随意替换，其余设计 token 可根据设计系统适配 diff --git a/addons/officials/crew/designer/ALLOWED_COMMANDS b/addons/officials/crew/designer/ALLOWED_COMMANDS new file mode 100644 index 00000000..e384a1cd --- /dev/null +++ b/addons/officials/crew/designer/ALLOWED_COMMANDS @@ -0,0 +1,13 @@ +# Auto-generated by setup-crew.sh — skill script allowlist ++nano-pdf ++jq ++rg ++tmux ++curl ++summarize ++gifgrep ++node ++python3 ++/home/wukong/.openclaw/skills/wx-mp-hunter/scripts/wx-mp-hunter.sh ++./skills/init-workspace/scripts/init.sh ++./skills/design-system-picker/scripts/pick.sh diff --git a/addons/officials/crew/designer/BOOTSTRAP.md b/addons/officials/crew/designer/BOOTSTRAP.md index 6a847dd6..1d9b87d8 100644 --- a/addons/officials/crew/designer/BOOTSTRAP.md +++ b/addons/officials/crew/designer/BOOTSTRAP.md @@ -1,10 +1,43 @@ -# Bootstrap +# Designer Bootstrap -This is a pre-configured crew workspace. Your role, responsibilities, and behavioral guidelines are fully defined in the following files — please review them at startup: +This one-time bootstrap collects brand assets and design context before design work starts. If this crew is being enabled through Main Agent and has no direct work channel yet, Main Agent may ask these questions on behalf of this crew and write the answers into the crew workspace. -- **SOUL.md** — Role definition, core responsibilities, and autonomy level -- **AGENTS.md** — Workflows and operating procedures -- **MEMORY.md** — Background context, brand assets, and ongoing task state -- **IDENTITY.md** — Name and persona -- **USER.md** — Assumptions about who you are serving -- **TOOLS.md** — Available tools and usage guidelines +## Step 1: Brand Assets + +Collect: + +- **Brand name**: company/brand name +- **Brand colors**: primary, secondary, accent, surface, text colors (hex or named) +- **Logo**: location or URL of logo files (if available) +- **Typography**: preferred font families (if any), or note "no preference" +- **Existing brand guidelines**: any existing style guide, brand book, or design documentation location + +If the user has no established brand assets, note this — the Designer will help establish them during the first品牌视觉体系构建 task. + +## Step 2: Design Preferences + +Ask: + +- **Default style direction**: any preferred visual style (e.g., minimal, editorial, neo-brutalism, glassmorphism, dark luxury) +- **Common output formats**: what the user typically needs (landing pages, app UI, brand systems, social media assets) +- **Dark mode**: is dark mode needed for deliverables? +- **Approval workflow**: who reviews and approves designs? How many revision rounds are typical? + +## Step 3: Environment Verification + +On first startup, check and report: + +1. `SILICONFLOW_API_KEY` is set → enables `siliconflow-img-gen` for AI image generation +2. `PEXELS_API_KEY` is set → enables `pexels-footage` for stock images +3. `PIXABAY_API_KEY` is set → enables `pixabay-footage` for stock images + +At least one image source should be available. If none are configured, report clearly. + +## Completion + +After bootstrap is complete: + +1. Update `MEMORY.md` with brand assets, design preferences, and available image sources. +2. Update `USER.md` with approval workflow if specified. +3. Delete `BOOTSTRAP.md` from the runtime workspace. +4. Suggest the next step, such as starting a brand visual system build or the first design task. diff --git a/addons/officials/crew/designer/BUILTIN_SKILLS b/addons/officials/crew/designer/BUILTIN_SKILLS index 7ea22813..2c5916ee 100644 --- a/addons/officials/crew/designer/BUILTIN_SKILLS +++ b/addons/officials/crew/designer/BUILTIN_SKILLS @@ -1,2 +1,4 @@ siliconflow-img-gen summarize +pexels-footage +pixabay-footage diff --git a/addons/officials/crew/designer/DENIED_SKILLS b/addons/officials/crew/designer/DENIED_SKILLS index 95062baf..99bd1ab0 100644 --- a/addons/officials/crew/designer/DENIED_SKILLS +++ b/addons/officials/crew/designer/DENIED_SKILLS @@ -1,10 +1,17 @@ -# Default denied bundled skills for non-IT crews. +# IT 工程师专属技能 github gh-issues coding-agent # 业务拓展专属技能（business-developer 使用） connections-optimizer email-ops +pitch-deck social-graph-ranker +# 信息采集技能（HRBP 不需要） rss-reader -xhs-interact \ No newline at end of file +email-ops +xhs-interact +wx-mp-hunter +login-manager +# 闲鱼/TTS 技能（designer 不需要） +xianyu-ops \ No newline at end of file diff --git a/addons/officials/crew/designer/HEARTBEAT.md b/addons/officials/crew/designer/HEARTBEAT.md index d26ecc05..387df48d 100644 --- a/addons/officials/crew/designer/HEARTBEAT.md +++ b/addons/officials/crew/designer/HEARTBEAT.md @@ -1,5 +1,7 @@ -# 设计师 — Heartbeat +# HEARTBEAT.md Template -## Health Check -- Status: operational -- Last updated: (auto-maintained) +```markdown +# Keep this file empty (or with only comments) to skip heartbeat API calls. + +# Add tasks below when you want the agent to check something periodically. +``` diff --git a/addons/officials/crew/designer/IDENTITY.md b/addons/officials/crew/designer/IDENTITY.md index 007883b1..9e112784 100644 --- a/addons/officials/crew/designer/IDENTITY.md +++ b/addons/officials/crew/designer/IDENTITY.md @@ -4,7 +4,7 @@ 设计师 (Designer) ## Role -团队平面设计与视觉创作专家 — 负责 AI 出图、海报制作、封面设计、品牌视觉，以及网页/落地页的 HTML 交互原型输出。 +系统性视觉设计专家 — 负责从零构建完整的网页、APP 界面、品牌视觉体系。基于设计系统（DESIGN.md）交付风格统一、组件规范、可直接预览的前端原型。 ## Personality -专业、有审美、追求细节。擅长把一句模糊的需求拆解成清晰的视觉提案，输出前必先确认风格方向，交付时附上设计决策说明。 +专业、有系统思维、追求一致性。擅长把一句模糊的需求拆解为完整的设计体系——先定风格再定组件再出页面，交付时附上设计决策说明和 DESIGN.md 规范。 diff --git a/addons/officials/crew/designer/MEMORY.md b/addons/officials/crew/designer/MEMORY.md index 84fa9a8b..e3f0cd93 100644 --- a/addons/officials/crew/designer/MEMORY.md +++ b/addons/officials/crew/designer/MEMORY.md @@ -2,21 +2,14 @@ ## Brand Assets -> 由 main agent 在招募时填写，或在设计工作中逐步沉淀。 + -- 品牌主色： -- 辅助色： -- 背景色： -- 主要字体：<字体名称，如 PingFang SC / Noto Sans SC / Inter> -- Logo URL：<可公开访问的 Logo 图片链接> -- 品牌风格描述：<如"科技感、简洁、专业"或"活泼、年轻、国潮"> +## Design Systems Used -## Approved Style Directions - -> 经用户确认可复用的风格/提示词组合 +> 经用户确认采用的设计系统记录 ## Design Archive Notes @@ -28,7 +21,3 @@ ## Known Assets > 已知可用的素材、图片 URL、免版权资源 - - diff --git a/addons/officials/crew/designer/SOUL.md b/addons/officials/crew/designer/SOUL.md index c6a125dc..40aaf669 100644 --- a/addons/officials/crew/designer/SOUL.md +++ b/addons/officials/crew/designer/SOUL.md @@ -1,34 +1,35 @@ # 设计师 — SOUL ## 核心使命 -**让每一张图、每一个页面都值得被看见。** +**从零开始构建完整的视觉设计体系。** -不只是"生成一张图"，而是从视觉策略出发——理解使用场景、目标受众、品牌调性，交付真正有传播力的视觉作品。 +不是出一张图、做一张海报——那是各 crew 用 `siliconflow-img-gen` 就能完成的事。Designer 解决的是系统性问题：用户需要一个完整的网站、一套 APP 界面、一个品牌视觉体系，从风格定义到组件规范到页面实现，一站式交付。 ## 公司品牌信息 -<待填充 — 由 main agent 在招募时写入> + ## Core Responsibilities -### 四种工作模式 +### 三种工作模式 -1. **AI 出图（文生图 / 改图）** - 接收文字描述或参考图，调用 `siliconflow-img-gen` 生成配图、封面、Banner 等视觉素材。 +1. **完整网页 / 落地页设计** + 从信息架构到视觉风格到 HTML+CSS 实现，交付可直接预览的响应式网页。通过 `design-system-picker` 选取或构建设计系统，确保整体风格统一。 -2. **海报设计** - 结合品牌色、字体偏好和使用场景，生成一组海报方案（通常 2–3 版），由用户选取。 +2. **APP / 产品界面设计** + 定义完整的产品界面设计系统（色彩、字体、组件、间距、交互状态），输出设计规范文档 + 关键页面 HTML 原型。 -3. **网页 / 落地页设计** - 输出语义化 HTML + CSS 网页原型，包含响应式布局、hover 状态和配色方案；可直接在浏览器预览。 +3. **品牌视觉体系构建** + 从品牌调性出发，构建包含色彩体系、字体规范、组件样式、图标风格的完整视觉语言，输出 DESIGN.md 规范文档 + 组件预览页面。 -4. **设计改稿与素材管理** - 对已有设计稿进行风格调整、尺寸适配、颜色替换；所有成品存入 `design_assets/` 并维护 `index.md`。 +## 使用模式 + +Designer 以 **binding 模式** 为主——用户直接与 Designer 对话，描述需求后由 Designer 全程负责交付。其他 crew 不再 spawn Designer，它们自身的出图需求（封面、配图、海报等）直接使用 `siliconflow-img-gen` 即可。 ## Autonomy -- 可自主完成：资料搜集、灵感参考采集、提示词起草、工具调用 -- 向用户展示方案后等待确认：提交设计方案预览；确认视为交付授权，无需再次询问 +- 可自主完成：设计系统选取、灵感参考采集、提示词起草、工具调用、代码编写 +- 向用户展示方案后等待确认：提交设计系统选型、信息架构、关键页面预览；确认视为交付授权 - 须明确获得用户指令：将设计稿对外发布、或替换线上资产 ## 权限级别 @@ -37,20 +38,13 @@ command-tier: T2 ## Communication Style - 默认中文；用户用英文则回英文 -- 描述设计决策时简洁直白：用了什么色调、为什么这么排版 -- 遇到模糊需求，主动追问三要素：**使用场景、受众画像、品牌限制** +- 描述设计决策时简洁直白：用了什么设计系统、为什么这么布局、色彩角色如何定义 +- 遇到模糊需求，主动追问三要素：**产品类型与目标用户、风格偏好或参考品牌、功能范围与页面清单** - 提案中注明每个版本的设计思路差异，让用户有据可选 ## Edge Cases Handling -- **需求太模糊**：追问使用场景、目标平台、期望风格（写实/插画/极简/赛博朋克等） +- **需求太模糊**：追问产品类型（网站/APP/管理后台）、目标用户、风格参考（具体品牌或描述词） - **品牌规范冲突**：标注冲突位置，给出"遵从规则版"与"创意自由版"两套方案 -- **生成效果不满意**：追问具体不满意点，调整提示词后重新生成，最多迭代 3 次后建议更换基底模型 -- **网页原型需要后端逻辑**：仅交付前端静态原型，明确告知动态交互需交给 IT Engineer 实现 - -## Technical Issue Protocol - -遭遇技术问题时（exec 失败、API 报错、siliconflow 超时等）： -1. 立即告知用户，说明在呼唤 IT Engineer 处理 -2. spawn IT Engineer，传递完整错误信息与任务上下文 -3. 等待 IT Engineer 修复后继续执行，绝不让用户自行排查 +- **设计效果不满意**：追问具体不满意点，调整设计系统或 CSS token 后重新输出 +- **需要后端逻辑**：仅交付前端静态原型，明确告知动态交互需交给 IT Engineer 实现 diff --git a/addons/officials/crew/designer/TOOLS.md b/addons/officials/crew/designer/TOOLS.md index 178f88c8..dcdbcb38 100644 --- a/addons/officials/crew/designer/TOOLS.md +++ b/addons/officials/crew/designer/TOOLS.md @@ -1,27 +1,36 @@ # 设计师 — Tools +## design-system-picker 使用规范 + +调用 `design-system-picker` 技能从内置设计系统库中选取匹配的设计系统： + +``` +./skills/design-system-picker/scripts/pick.sh "<风格描述>" +``` + +返回匹配的设计系统列表，包含风格名称、色彩主调、适用场景。选取后将其 DESIGN.md 内容作为本任务的设计规范基础。 + ## siliconflow-img-gen 使用规范 -**尺寸映射**（优先使用标准尺寸）： +仅在需要为网页/界面生成配图素材时使用（非核心工作，备选方案）。 + +**尺寸映射**（网页/界面场景优先）： | 场景 | 尺寸 | 参数 | |------|------|------| -| 正方形配图 / 头像 | 1024×1024 | `--image-size 1024x1024` | -| 竖版海报 / 小红书封面 | 960×1280 | `--image-size 960x1280` | -| 横版 Banner | 1280×720 | `--image-size 1280x720` | -| 手机壁纸 / 竖版视频封面 | 720×1280 | `--image-size 720x1280` | -| 长图 / 信息图 | 720×1440 | `--image-size 720x1440` | +| 网页 Banner / Hero 背景 | 1280×720 | `--image-size 1280x720` | +| 正方形图标 / 头像 | 1024×1024 | `--image-size 1024x1024` | +| 竖版手机端配图 | 720×1280 | `--image-size 720x1280` | **模型选择**： -- 默认：`Qwen/Qwen-Image-Edit-2509`（质量均衡，支持改图） -- 批量出图 / 需要 guidance 控制���`Kwai-Kolors/Kolors`（`--batch-size` 最多 4 张） -- 改图（基于参考图）：`Qwen/Qwen-Image-Edit-2509`（传入 `--image` 参数） +- 默认：`Qwen/Qwen-Image`（质量均衡） -**输出目录**：统一存到 `design_assets/YYYY-MM-DD-<任务关键词>/` +**输出目录**：统一存到 `design_assets/YYYY-MM-DD-<任务关键词>/source/` -**超时处理**：exec timeout 设置 `120` 秒；超时后告知用户，建议稍后重试或切换模型 +**超时处理**：exec timeout 设置 `120` 秒 -## 注意事项 +## 素材获取优先级 -- **素材合规**：仅使用明确标注 CC0 / 免版权的图片，记录来源 URL -- **参考图保存**：截图参考图保存到 `design_assets/references/` +1. `pexels-footage` / `pixabay-footage` 搜索免版权素材 +2. `siliconflow-img-gen` 生成配图 +3. 所有素材保存到任务 `source/` 目录，记录来源 diff --git a/addons/officials/crew/designer/USER.md b/addons/officials/crew/designer/USER.md index e07147ca..7ef044c8 100644 --- a/addons/officials/crew/designer/USER.md +++ b/addons/officials/crew/designer/USER.md @@ -1,15 +1,14 @@ # 设计师 — User Context ## User Role -用户是 boss，他会直接给你下发设计需求。但是更常见的是，其他内部 Agent 在它们的工作流中向你下发设计需求，你应该配合它们的工作。 +The user is the boss. ## Preferences - Language: 中文（主要）；如用户用英文输入，则用英文回复 - Style: 设计质量优先，宁可多问一句也不交付错方向的稿件 -- Autonomy: L1/L2 自主推进；L3（对外发布/替换线上资产）始终需要用户明确指令 ## Assumptions - 用户大多数时候有明确的功能需求，但视觉语言表达不精确 - 用户对品牌规范可能不熟悉，需要设计师主动查阅 MEMORY.md 并提醒约束 - 用户希望一次看到多个方案选择，而不是只看一个版本 -- 用户可能会用"再改一下"这样的模糊反馈，需要主动追问具体不满意点 +- 用户可能会用"再改一下"这样的模糊反馈，需要主动追问具体不满意点 \ No newline at end of file diff --git a/addons/officials/crew/designer/openclaw_setting_sample.json b/addons/officials/crew/designer/openclaw_setting_sample.json index 9bf13eff..3250964e 100644 --- a/addons/officials/crew/designer/openclaw_setting_sample.json +++ b/addons/officials/crew/designer/openclaw_setting_sample.json @@ -1,5 +1,12 @@ { - "skills": ["siliconflow-img-gen", "siliconflow-video-gen", "smart-search", "council"], + "skills": [ + "siliconflow-img-gen", + "pexels-footage", + "pixabay-footage", + "smart-search", + "browser-guide", + "design-system-picker" + ], "subagents": { "allowAgents": ["it-engineer"] }, diff --git a/addons/officials/crew/designer/skills/design-system-picker/SKILL.md b/addons/officials/crew/designer/skills/design-system-picker/SKILL.md new file mode 100644 index 00000000..745be2fb --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/SKILL.md @@ -0,0 +1,112 @@ +--- +name: design-system-picker +description: 根据风格描述从内置设计系统库中选取最匹配的设计系统，提供 DESIGN.md 规范供后续设计工作使用。 +metadata: + openclaw: + emoji: 🎨 +--- + +# Design System Picker + +从内置设计系统库中匹配最合适的设计系统，为后续网页/界面设计提供风格规范基础。 + +## 用法 + +### 搜索匹配 + +```bash +./skills/design-system-picker/scripts/pick.sh "<风格描述>" +``` + +示例： + +```bash +./skills/design-system-picker/scripts/pick.sh "科技感暗色主题" +./skills/design-system-picker/scripts/pick.sh "类似 Stripe 的金融风格" +./skills/design-system-picker/scripts/pick.sh "温暖亲和的生活服务" +``` + +### 读取设计系统详情 + +搜索到匹配结果后，读取对应的设计系统文件获取完整规范： + +``` +读取 ./skills/design-system-picker/design-systems/ +``` + +例如匹配到 Stripe，则读取 `./skills/design-system-picker/design-systems/stripe.md`。 + +## 内置设计系统 + +| 设计系统 | 风格关键词 | 适用场景 | +|---------|----------|---------| +| Stripe | 紫色渐变、优雅、金融科技 | SaaS 产品页、支付/金融科技落地页 | +| Vercel | 黑白极简、精密、Geist | 开发者工具、技术产品官网 | +| Linear | 超极简、紫色点缀、精确 | 项目管理、效率工具 | +| Notion | 暖色极简、衬线标题、柔和 | 知识管理、内容平台 | +| Apple | 极致留白、电影级影像 | 消费电子、高端品牌官网 | +| Supabase | 暗色翡翠绿、代码优先 | 数据库/后端服务、开源工具 | +| Shopify | 暗色电影感、霓虹绿 | 电商平台、商业服务 | +| Figma | 多彩活泼、专业、创意 | 创意工具、设计平台 | +| Spotify | 鲜明绿、大胆排版 | 媒体/娱乐平台 | +| Tesla | 极致减法、全屏影像 | 汽车/硬件、极简品牌 | +| Framer | 黑蓝、动效优先 | 网站构建、交互展示 | +| Airbnb | 暖色珊瑚、摄影驱动 | 旅游/生活服务、社区平台 | +| BMW | 巴伐利亚蓝、暗色奢华、金属质感 | 奢侈品牌、高端产品、汽车/精密工业 | +| IBM | 企业蓝、Carbon 系统、数据密集 | 企业级产品、B2B 服务、数据平台 | +| Starbucks | Siren 绿、温暖社区、自然质感 | 生活品牌、餐饮/零售、社区平台 | + +## 使用时机 + +每项设计任务开始时，在 brief 确认后、进入具体设计前**必须**调用此技能确定设计系统。设计系统选定后，所有后续 HTML/CSS 产出的色彩、字体、间距、组件样式都应遵循该设计系统的规范。 + +## 自定义设计系统 + +如果用户提供的风格描述与内置设计系统均不匹配，应基于用户描述自行构建设计系统，输出格式参照内置 DESIGN.md 的标准结构： + +1. Visual Theme & Atmosphere +2. Color Palette & Roles +3. Typography Rules +4. Component Stylings +5. Layout Principles +6. Depth & Elevation +7. Do's and Don'ts +8. Responsive Behavior + +## 探索更多设计系统 + +内置设计系统无法覆盖所有风格需求。当内置库中没有合适匹配，或用户指定了特定品牌/风格参考时，可从上游仓库 [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) 中查找并导入： + +### 查找流程 + +1. 访问 `https://github.com/VoltAgent/awesome-design-md` 查看完整设计系统列表 +2. 也可直接访问 `https://getdesign.md//design-md` 查看特定品牌的设计系统（如 `https://getdesign.md/starbucks/design-md`） +3. 选取匹配的设计系统后，将内容下载为 `design-systems/.md` + +### 导入流程 + +找到合适的设计系统后，必须完成以下两步才能使用： + +**1. 添加设计系统文件** + +将 DESIGN.md 内容保存到 `./skills/design-system-picker/design-systems/.md`，确保遵循标准的 8 段结构。如果不完整，应基于下载内容补全缺失段落。 + +**2. 注册到索引** + +在 `./skills/design-system-picker/design-systems/index.json` 中添加条目： + +```json +{ + "id": "", + "name": "", + "category": "", + "keywords": ["关键词1", "关键词2", ...], + "description": "一句话风格描述", + "colorPrimary": "#HEX", + "darkMode": true/false, + "bestFor": "适用场景描述", + "file": ".md" +} +``` + +完成后即可通过 `pick.sh` 搜索到该设计系统。 diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/airbnb.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/airbnb.md new file mode 100644 index 00000000..3d5add98 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/airbnb.md @@ -0,0 +1,165 @@ +# Airbnb Design System + +Warm coral accent over crisp white surfaces. Photography-driven layouts that sell the experience before the interface. Rounded, friendly, human — the UI feels like a trusted travel companion, not a software tool. + +--- + +## 1. Visual Theme & Atmosphere + +Clean white canvas with warm photography as the primary visual driver. The coral accent signals action and brand without shouting. Rounded corners everywhere — nothing sharp, nothing aggressive. Micro-copy is conversational. The atmosphere says "welcome" at every touchpoint. Listings, destinations, and people are the visual content; UI chrome stays light and out of the way. + +**Keywords:** warm, inviting, human, photographic, friendly, trustworthy, rounded + +--- + +## 2. Color Palette & Roles + +| Name | Hex | Role | +|------|-----|------| +| Rausch (Coral) | `#FF385C` | Primary accent, CTAs, brand moments, active states | +| Dark Rausch | `#D70466` | CTA hover, pressed states | +| Foreground | `#222222` | Primary text | +| Secondary Text | `#717171` | Descriptions, subtitles, helper text | +| Tertiary Text | `#B0B0B0` | Placeholders, disabled text | +| Background | `#FFFFFF` | Primary surface | +| Surface Light | `#F7F7F7` | Card backgrounds, section alternation | +| Surface Warm | `#FFFAF5` | Subtle warm tint for featured sections | +| Border | `#DDDDDD` | Dividers, card borders, input borders | +| Border Light | `#EBEBEB` | Subtle dividers, table lines | +| Success | `#008A05` | Booking confirmed, positive status | +| Warning | `#C7B82F` | Pending states | +| Error | `#C13515` | Cancellation, validation errors | + +**Rule:** Rausch is the heartbeat. Use it for CTAs, selected states, and brand anchors. Never as a background fill for large areas — it tires the eye. Surface Warm is the secret weapon for making sections feel cozy without adding decoration. + +--- + +## 3. Typography Rules + +**Primary:** Cereal (Airbnb custom) / fallback: Nunito Sans +**Display:** Cereal Medium / fallback: Nunito 600 + +| Element | Weight | Size | Tracking | Case | +|---------|--------|------|----------|------| +| Hero headline | 600 | clamp(32px, 4vw, 64px) | -0.02em | Title | +| Section title | 600 | clamp(22px, 2vw, 32px) | -0.01em | Title | +| Card title | 600 | 16px | 0 | Sentence | +| Body | 400 | 16px | 0 | Sentence | +| Body small | 400 | 14px | 0 | Sentence | +| Caption | 400 | 12px | 0.01em | Sentence | +| CTA | 600 | 16px | 0 | Sentence | +| Price | 800 | 20px | -0.01em | — | + +**Rules:** +- Headlines are sentence-case, never all-caps. Warmth > formality. +- Line-height: headlines 1.2, body 1.6, compact lists 1.4. +- Price text is always extra-bold, slightly larger than surrounding body. +- No italic for emphasis. Use weight (600) or color (Rausch for key terms). + +--- + +## 4. Component Stylings + +### Buttons +- **Primary CTA:** `#FF385C` background, white text, `border-radius: 8px`, padding `14px 24px`, weight 600. On hover: `#D70466`, slight translateY(-1px). Transition: 200ms ease. +- **Secondary CTA:** `#FFFFFF` background, `#222222` text, 1px `#DDDDDD` border, `border-radius: 8px`. On hover: border `#222222`. +- **Ghost:** Transparent, `#222222` text, no border. On hover: text `#FF385C`, underline. +- **Pill tag:** `border-radius: 999px`, `#F7F7F7` bg, `#222222` text. Active: `#FF385C` bg, white text. + +### Navigation +- Fixed top bar, `height: 64px`, white with 1px `#EBEBEB` bottom border. +- Logo left, search bar center, profile right. +- Search bar: pill shape (`border-radius: 999px`), `#F7F7F7` bg, icon + placeholder text. + +### Cards (Listing Cards) +- Background: `#FFFFFF`, `border-radius: 12px`, 1px `#DDDDDD` border. +- Image: `border-radius: 12px`, aspect-ratio 3/2, `object-fit: cover`. +- Heart icon (save): top-right, default stroke `#FFFFFF` with shadow, filled `#FF385C`. +- Rating: star icon `#FF385C`, score in `#222222`. +- Price: bold, per-night in secondary text. + +### Search Bar +- Pill container with segmented inputs: "Where" | "Check in" | "Check out" | "Who". +- Dividers: 1px `#DDDDDD` between segments. +- Active segment: `#222222` text, others `#717171`. +- Search button: circle with Rausch bg, white magnifying glass. + +### Image Gallery +- Full-width hero on listing detail, `border-radius: 12px` for individual images. +- Grid: 1 large (left 50%) + 4 small (right 50%, 2x2). +- Hover: subtle overlay with "Show all photos" CTA. + +### Reviews +- Avatar: 40px circle, `border-radius: 999px`. +- Star rating in Rausch. Review text in `#222222`, date in `#717171`. +- Divider between reviews: 1px `#EBEBEB`. + +--- + +## 5. Layout Principles + +- **Max content width:** 1128px (Airbnb standard), centered. +- **Listing grid:** responsive, 2 cols at 640px, 3 at 768px, 4 at 1024px, no fixed column count — let cards fill naturally with `auto-fill, minmax(280px, 1fr)`. +- **Card gutters:** 16px on mobile, 24px on desktop. +- **Section spacing:** 48px between sections, 32px between section title and content. +- **Listing detail:** two-column layout (left 60% content, right 40% sticky booking card). +- **Photography always leads.** Hero images are never decorative — they are the first impression of the experience. + +--- + +## 6. Depth & Elevation + +Airbnb uses subtle shadows and surface color for depth — never dramatic: + +| Level | Surface | Shadow | Use | +|-------|---------|--------|-----| +| 0 | `#FFFFFF` | none | Page background, resting cards | +| 1 | `#FFFFFF` | `0 1px 2px rgba(0,0,0,0.08)` | Cards on hover, elevated inputs | +| 2 | `#FFFFFF` | `0 4px 12px rgba(0,0,0,0.12)` | Dropdowns, popovers | +| 3 | `#FFFFFF` | `0 8px 24px rgba(0,0,0,0.16)` | Modals, booking card sticky | + +- Shadows are always soft and wide-spread — never tight or directional. +- No blur/glass effects. Surfaces are opaque. +- Sticky booking card uses Level 2 shadow to float above scroll content. + +--- + +## 7. Do's and Don'ts + +**Do:** +- Let photography dominate — listings without great images fail +- Use Rausch sparingly but consistently — CTAs, active states, brand marks +- Round everything — 8px for inputs, 12px for cards, 999px for pills and avatars +- Write conversationally — "Where to?" not "Destination" +- Use warm Surface Warm tint for featured or promoted sections +- Show ratings prominently — trust is the product +- Provide clear empty states with friendly illustration and CTA + +**Don't:** +- Use Rausch as a background color for sections or panels +- Apply sharp corners (border-radius: 0) to any interactive element +- Use heavy shadows at rest — they should only appear on interaction +- Write in formal or corporate tone +- Stack more than 3 cards vertically without a grid +- Use icons without labels for primary navigation +- Hide pricing — it should be visible in every listing card + +--- + +## 8. Responsive Behavior + +| Breakpoint | Behavior | +|-----------|----------| +| < 640px | Single column. Listing grid: 2 columns, smaller images. Booking card becomes bottom sticky bar. Search bar simplifies to single pill input. Nav: logo + profile icon only. | +| 640–768px | 2–3 column listing grid. Side-by-side content begins. Search bar keeps pill shape. | +| 768–1024px | 3–4 column grid. Listing detail: two-column layout appears. Booking card sticky in right column. | +| 1024–1440px | Full desktop grid (4 columns). Full search bar with segments. All navigation visible. | +| > 1440px | Content max-width 1128px, centered. Grid columns max out at 4 — do not add a 5th column. | + +**Mobile-specific rules:** +- Listing images become horizontally swipeable (one at a time with dot indicators) +- Bottom sticky bar for booking: Rausch CTA, price preview, dates +- Map view: full-screen map with bottom sheet for listings +- Filter bar: horizontal scroll chips instead of dropdown +- Touch targets: minimum 44x44px +- Heart/save icon: 44x44px hit area (larger than visual) diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/apple.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/apple.md new file mode 100644 index 00000000..c10a8bc7 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/apple.md @@ -0,0 +1,352 @@ +# Apple Design System + +## 1. Visual Theme & Atmosphere + +Apple's design language communicates premium simplicity. Every surface breathes. Content is the hero -- UI chrome recedes until needed. + +**Core qualities:** +- Cinematic full-bleed photography and video dominate hero sections +- Typography carries weight: large, confident, never timid +- White space is structural, not decorative -- it creates rhythm and focus +- Dark mode feels rich and deep, never flat gray +- Transitions are smooth and physical (spring curves, not linear) +- Product imagery is always studio-quality on clean backgrounds +- Gradients are subtle and purposeful (radial glows, not rainbow sweeps) + +**Atmosphere keywords:** confident, luminous, precise, unhurried, premium + +--- + +## 2. Color Palette & Roles + +### Light Mode + +| Token | Hex | Role | +|-------|-----|------| +| `--color-bg` | `#FFFFFF` | Page background | +| `--color-surface` | `#F5F5F7` | Card / section fill | +| `--color-surface-elevated` | `#FFFFFF` | Elevated cards, modals | +| `--color-text-primary` | `#1D1D1F` | Headlines, body copy | +| `--color-text-secondary` | `#6E6E73` | Captions, descriptions | +| `--color-text-tertiary` | `#86868B` | Disabled, placeholders | +| `--color-accent` | `#0071E3` | Links, CTAs, interactive | +| `--color-accent-hover` | `#0077ED` | Accent hover state | +| `--color-accent-active` | `#0062CC` | Accent pressed state | +| `--color-accent-subtle` | `#0071E312` | Accent tinted backgrounds | +| `--color-separator` | `#D2D2D7` | Dividers, borders | +| `--color-separator-subtle` | `#E8E8ED` | Hairline separators | +| `--color-fill-green` | `#30D158` | Success, positive states | +| `--color-fill-red` | `#FF3B30` | Error, destructive actions | +| `--color-fill-orange` | `#FF9F0A` | Warning, attention | +| `--color-fill-yellow` | `#FFD60A` | Highlight, caution | + +### Dark Mode + +| Token | Hex | Role | +|-------|-----|------| +| `--color-bg` | `#000000` | Page background -- true black on OLED | +| `--color-surface` | `#1C1C1E` | Card / section fill | +| `--color-surface-elevated` | `#2C2C2E` | Elevated cards, modals | +| `--color-text-primary` | `#F5F5F7` | Headlines, body copy | +| `--color-text-secondary` | `#A1A1A6` | Captions, descriptions | +| `--color-text-tertiary` | `#6E6E73` | Disabled, placeholders | +| `--color-accent` | `#2997FF` | Links, CTAs (lighter blue for dark bg) | +| `--color-accent-hover` | `#4DB2FF` | Accent hover state | +| `--color-accent-active` | `#0A84FF` | Accent pressed state | +| `--color-accent-subtle` | `#2997FF18` | Accent tinted backgrounds | +| `--color-separator` | `#38383A` | Dividers, borders | +| `--color-separator-subtle` | `#2C2C2E` | Hairline separators | +| `--color-fill-green` | `#30D158` | Success (same as light) | +| `--color-fill-red` | `#FF453A` | Error (lighter for dark bg) | +| `--color-fill-orange` | `#FF9F0A` | Warning (same as light) | + +--- + +## 3. Typography Rules + +**Font stack:** SF Pro (primary), `-apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", "Helvetica Neue", Helvetica, Arial, sans-serif` + +**Fallback for web without SF Pro:** `"Helvetica Neue", Helvetica, Arial, sans-serif` + +### Type Scale + +| Token | Size | Weight | Tracking | Line-height | Usage | +|-------|------|--------|----------|-------------|-------| +| `--text-hero` | `clamp(3rem, 5vw + 1rem, 5.5rem)` | 600 (semibold) | -0.03em | 1.05 | Product hero headlines | +| `--text-headline-lg` | `clamp(2.5rem, 3.5vw + 0.5rem, 3.5rem)` | 600 | -0.025em | 1.1 | Section headlines | +| `--text-headline` | `clamp(1.75rem, 2vw + 0.5rem, 2.5rem)` | 600 | -0.02em | 1.15 | Sub-section headlines | +| `--text-title` | `1.5rem` (24px) | 600 | -0.015em | 1.2 | Card titles, modal headers | +| `--text-subtitle` | `1.25rem` (20px) | 500 | -0.01em | 1.25 | Subtitles, supporting heads | +| `--text-body-lg` | `1.125rem` (18px) | 400 | 0 | 1.55 | Large body, introductions | +| `--text-body` | `1rem` (16px) | 400 | 0 | 1.5 | Default body text | +| `--text-caption` | `0.875rem` (14px) | 400 | 0.01em | 1.4 | Captions, metadata | +| `--text-overline` | `0.75rem` (12px) | 500 | 0.05em | 1.33 | Labels, badges, overlines (UPPERCASE) | + +### Dynamic Type Rules + +- Hero text uses `clamp()` for fluid scaling between breakpoints +- Body text never goes below 16px on mobile +- Tracking tightens as size increases (hero: -0.03em, body: 0) +- Weight stays within 400-600 range; never use 300 or below for English +- Chinese/Japanese text uses SF Pro SC/SF Pro JP with same size scale but tracking at 0 + +--- + +## 4. Component Stylings + +### Buttons + +**Primary (Blue)** +```css +background: var(--color-accent); +color: #FFFFFF; +padding: 12px 24px; +border-radius: 980px; /* full pill */ +font-size: 1rem; +font-weight: 500; +letter-spacing: 0; +border: none; +cursor: pointer; +transition: background 200ms ease; +``` +- Hover: `var(--color-accent-hover)` +- Active: `var(--color-accent-active)` + scale(0.98) +- Disabled: opacity 0.4, no pointer events + +**Secondary (Tinted)** +```css +background: var(--color-accent-subtle); +color: var(--color-accent); +padding: 12px 24px; +border-radius: 980px; +font-size: 1rem; +font-weight: 500; +border: none; +``` + +**Text / Ghost** +```css +background: transparent; +color: var(--color-accent); +padding: 8px 12px; +border-radius: 980px; +font-size: 1rem; +font-weight: 500; +border: none; +``` +- Hover: `background: var(--color-accent-subtle)` + +**Large Hero CTA** +```css +padding: 16px 32px; +font-size: 1.125rem; +``` + +### Cards + +```css +background: var(--color-surface); +border-radius: 20px; +padding: 24px; +border: none; +box-shadow: none; +``` +- Elevated variant: `background: var(--color-surface-elevated)` + subtle shadow +- Image cards: image fills top portion with `border-radius: 20px 20px 0 0`, no gap between image and content +- Product tiles: centered content, generous padding (32px+) + +### Inputs + +```css +background: var(--color-surface); +border: 1px solid var(--color-separator); +border-radius: 12px; +padding: 12px 16px; +font-size: 1rem; +color: var(--color-text-primary); +outline: none; +transition: border-color 200ms ease; +``` +- Focus: `border-color: var(--color-accent)` + `box-shadow: 0 0 0 3px var(--color-accent-subtle)` +- Placeholder: `var(--color-text-tertiary)` +- Error: `border-color: var(--color-fill-red)` +- Search inputs: rounded pill (980px), magnifying glass icon at left + +### Navigation + +- **Sticky nav**: `backdrop-filter: saturate(180%) blur(20px)` + semi-transparent background + - Light: `rgba(255, 255, 255, 0.72)` + - Dark: `rgba(29, 29, 31, 0.72)` +- Nav height: `48px` (compact, not tall) +- Nav links: `font-size: 0.75rem; font-weight: 400; letter-spacing: 0; color: var(--color-text-secondary)` +- Active link: `color: var(--color-text-primary)` +- Max content width within nav: `980px` centered +- Mobile: hamburger icon, full-screen slide-down menu with `backdrop-filter: blur(20px)` + +### Tabs + +```css +background: var(--color-surface); +border-radius: 980px; +padding: 2px; +``` +- Active tab pill: `background: var(--color-surface-elevated)` + `box-shadow: 0 1px 3px rgba(0,0,0,0.08)` +- Tab label: `font-size: 0.8125rem; font-weight: 500` + +--- + +## 5. Layout Principles + +### Whitespace Philosophy + +White space is the most important design element. It is not "empty" -- it is intentional breathing room that directs attention. + +- Section padding: `clamp(4rem, 8vw, 8rem)` vertical +- Between headline and body: `0.75em` to `1em` +- Between body and CTA: `1.5em` to `2em` +- Between sibling cards: `20px` to `24px` +- Edge padding (mobile): `20px` +- Edge padding (desktop): centered within `980px` max-width + +### Grid + +- Max content width: `980px` (Apple's standard) +- Wide layouts: `1200px` for product showcase pages +- Grid columns: 12-column at desktop, 4-column at tablet, 1-column at mobile +- Column gap: `24px` +- Content never stretches edge-to-edge on desktop; always maintain margin + +### Content Rhythm + +1. **Hero section**: Full viewport height or near-full. Headline + subtitle + CTA centered. Background imagery or video. +2. **Feature sections**: Alternating image-left / text-right then flip. Each section separated by generous vertical space. +3. **Spec/benefit grids**: 2-4 columns of icon + short text. Compact but not cramped. +4. **Final CTA section**: Centered, bold headline, single button. Often on colored background. + +--- + +## 6. Depth & Elevation + +### Frosted Glass (Vibrancy) + +Apple's signature depth cue. Use on any overlaying surface: + +```css +background: rgba(255, 255, 255, 0.72); /* light */ +background: rgba(29, 29, 31, 0.72); /* dark */ +backdrop-filter: saturate(180%) blur(20px); +-webkit-backdrop-filter: saturate(180%) blur(20px); +``` + +Apply to: navigation bar, modal overlays, popover menus, floating toolbars. + +### Shadow Levels + +| Level | Shadow | Use Case | +|-------|--------|----------| +| 0 | none | Inline cards on colored surface | +| 1 | `0 1px 2px rgba(0,0,0,0.04)` | Subtle lift, default cards | +| 2 | `0 4px 12px rgba(0,0,0,0.08)` | Elevated cards, dropdowns | +| 3 | `0 8px 32px rgba(0,0,0,0.12)` | Modals, popovers | +| 4 | `0 16px 48px rgba(0,0,0,0.16)` | Hero modals, large overlays | + +Dark mode shadows: use `rgba(0,0,0,0.4)` base and increase opacity by 1.5x compared to light. + +### Material Surfaces + +- **Regular material**: solid `var(--color-surface)` background +- **Thin material**: `backdrop-filter: blur(20px)` + 60% opacity fill +- **Thick material**: `backdrop-filter: blur(40px)` + 80% opacity fill +- **Ultra-thin material**: `backdrop-filter: blur(10px)` + 40% opacity fill (for subtle overlays) + +### Border Radius Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `--radius-sm` | `8px` | Small chips, badges | +| `--radius-md` | `12px` | Inputs, small cards | +| `--radius-lg` | `20px` | Cards, modal containers | +| `--radius-xl` | `28px` | Large feature cards | +| `--radius-pill` | `980px` | Buttons, pills, search bars | + +--- + +## 7. Do's and Don'ts + +### Do + +- Use full-bleed cinematic imagery for hero sections -- let photos breathe +- Use SF Pro at semibold (600) for headlines; it reads as confident, not heavy +- Generously pad everything; if it feels tight, add more space +- Use the blue accent sparingly -- one blue element per section is enough +- Apply frosted glass to floating and overlay surfaces +- Use `clamp()` for all headline sizes to ensure fluid scaling +- Animate with spring-like easing: `cubic-bezier(0.25, 0.1, 0.25, 1)` or CSS `spring()` +- Pair large headlines with small, quiet body text for contrast +- Use true black (`#000000`) for dark mode backgrounds on OLED +- Use `saturate(180%)` in backdrop-filter for that signature Apple vibrancy + +### Don't + +- Never use drop shadows on text -- Apple never does this +- Never use more than two font weights on a single page (400 + 600 is the standard pair) +- Never add colored backgrounds behind body text on white pages +- Never use underlines on links within body copy -- use blue color only +- Never round-card product images on product detail pages -- use rectangle with subtle radius +- Never use uppercase for headlines or body text (only overline labels) +- Never add visible borders to cards on light backgrounds -- use surface color difference instead +- Never use gray (`#808080` or similar) as a decorative accent +- Never animate layout properties (width, height, margin, padding) -- use transform and opacity only +- Never place text directly over busy photography without a scrim or blur layer + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Width | Layout | +|------|-------|--------| +| Mobile | `< 734px` | Single column, stacked sections | +| Tablet | `734px - 1068px` | 2-column grid, compact nav | +| Desktop | `1069px - 1440px` | Full layout, centered content | +| Wide | `> 1440px` | Max-width constrained, margins grow | + +### Key Responsive Patterns + +**Navigation:** +- Desktop: horizontal links in nav bar +- Tablet: condensed links or dropdown +- Mobile: hamburger icon, full-screen overlay menu with frosted glass + +**Hero Sections:** +- Desktop: large text (hero scale), side-by-side image + text or full-bleed image with centered overlay text +- Mobile: stacked (text above image), reduced type scale, image may become background with scrim + +**Feature Grids:** +- Desktop: 3-4 columns +- Tablet: 2 columns +- Mobile: 1 column, full-width cards + +**Product Images:** +- Desktop: large, often 50% of viewport width +- Mobile: full-width with `aspect-ratio: 4/3` or `1/1` + +**Spacing Scale (mobile vs desktop):** + +| Context | Mobile | Desktop | +|---------|--------|---------| +| Section vertical padding | `3rem` | `clamp(4rem, 8vw, 8rem)` | +| Card padding | `20px` | `24px` to `32px` | +| Edge margin | `20px` | auto (centered in max-width) | +| Between-section gap | `2rem` | `4rem` to `6rem` | +| Card grid gap | `16px` | `24px` | + +**Touch Targets:** +- Minimum 44px x 44px on mobile +- Tap targets separated by at least 8px +- Buttons on mobile: full-width or minimum 140px wide + +### Dark Mode Switching + +Use `prefers-color-scheme` media query. All color tokens swap simultaneously. Images and photography may also switch (Apple often uses different hero images for light/dark on product pages). Transition between modes should be instant (no animation on color swap) -- only user-triggered interactions animate. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/bmw.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/bmw.md new file mode 100644 index 00000000..3d52c3d8 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/bmw.md @@ -0,0 +1,331 @@ +# BMW Design System + +Precision engineering meets Bavarian heritage. Structured surfaces, measured contrast, and the unmistakable weight of a brand that has earned its authority over a century. Dark mode is the premium canvas — warm navy, not void black. Every element is machined, not molded. + +--- + +## 1. Visual Theme & Atmosphere + +BMW's visual language communicates engineered luxury — the confidence of something built to exacting standards, not designed to impress. Dark navy hero bands frame automotive photography shot in controlled studio light or at golden hour. The palette is restrained: corporate blue carries every primary action, warm dark surfaces anchor the page, and typography does the heavy lifting through extreme weight contrast (700 display against 300 body). The twin kidney grille inspires a design philosophy of symmetry, precision, and authoritative presence — nothing rounded, nothing soft, nothing that hasn't earned its place. + +Photography is always premium: studio-lit vehicle renders on neutral backgrounds, or cinematic environmental shots at 16:9 and wider. Surfaces alternate between light canvas and dark navy bands in a deliberate rhythm. The M tricolor stripe appears only in motorsport contexts — a controlled accent, not a decorative device. + +**Keywords:** engineered precision, measured luxury, Bavarian authority, structured, machined, warm dark + +--- + +## 2. Color Palette & Roles + +### Light Mode + +| Token | Hex | Role | +|-------|-----|------| +| `--color-canvas` | `#FFFFFF` | Page background, base surface | +| `--color-surface-soft` | `#F7F7F7` | Footer, sub-navigation bands | +| `--color-surface-card` | `#FAFAFA` | Model card photo plates | +| `--color-surface-strong` | `#EBEBEB` | Section dividers, heavier breaks | +| `--color-ink` | `#262626` | Primary text, display headlines — not pure black, soft against photography | +| `--color-body` | `#3C3C3C` | Default running text | +| `--color-body-strong` | `#1A1A1A` | Emphasized paragraphs, lead text | +| `--color-muted` | `#6B6B6B` | Footer links, breadcrumbs, captions | +| `--color-muted-soft` | `#9A9A9A` | Disabled text, fine-print legal | +| `--color-primary` | `#1C69D4` | BMW Blue — all primary CTAs, active nav, interactive accent | +| `--color-primary-active` | `#0653B6` | Pressed/active state | +| `--color-primary-disabled` | `#D6D6D6` | Disabled button background | +| `--color-bavarian-blue` | `#0066B1` | Brand heritage blue — logo mark, motorsport context, M tricolor anchor | +| `--color-on-primary` | `#FFFFFF` | White text on blue buttons | +| `--color-hairline` | `#E6E6E6` | 1px dividers, input outlines, table separators | +| `--color-hairline-strong` | `#CCCCCC` | Emphasized borders, disabled secondary buttons | +| `--color-m-red` | `#E22718` | M tricolor stripe, error states — never as CTA | +| `--color-success` | `#22C55E` | Confirmation, available indicators | +| `--color-warning` | `#F59E0B` | Warning callouts | +| `--color-error` | `#DC2626` | Validation errors | + +### Dark Mode (Premium Default) + +| Token | Hex | Role | +|-------|-----|------| +| `--color-canvas` | `#1A2129` | Page background — warm dark navy, not pure black. The Bavarian warmth. | +| `--color-surface-elevated` | `#262E38` | Cards, elevated panels nested on dark hero | +| `--color-surface-card` | `#1E2730` | Model card plates on dark canvas | +| `--color-surface-soft` | `#151B22` | Footer band, deeper than canvas | +| `--color-ink` | `#F5F5F5` | Primary text on dark — warm white | +| `--color-body` | `#C8C8C8` | Default running text on dark | +| `--color-body-strong` | `#E8E8E8` | Emphasized paragraphs on dark | +| `--color-muted` | `#8A8A8A` | Secondary text, breadcrumbs | +| `--color-muted-soft` | `#5E5E5E` | Disabled, fine-print | +| `--color-primary` | `#3B8FE3` | BMW Blue shifted lighter for dark backgrounds | +| `--color-primary-active` | `#2A7BC8` | Pressed/active on dark | +| `--color-on-primary` | `#FFFFFF` | Text on blue buttons (unchanged) | +| `--color-hairline` | `#2E363F` | Dividers on dark — visible but not bright | +| `--color-hairline-strong` | `#3D4752` | Emphasized borders on dark | +| `--color-bavarian-blue` | `#1A8FD4` | Heritage blue, lightened for dark mode | + +**Rule:** The dark palette is never pure black (`#000000`). BMW's dark surfaces carry a warm blue-navy undertone (`#1A2129`) — the Bavarian heritage showing through. This distinguishes BMW from Tesla's void-black and Apple's OLED-black. The warmth signals luxury, not emptiness. + +--- + +## 3. Typography Rules + +**Primary:** BMW Type Next Latin (licensed, not publicly available) +**Fallback stack:** `"Helvetica Neue", Helvetica, "Inter", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif` + +**Substitute recommendation:** Inter (variable) at weights 700 / 300 — closest open-source match to BMW Type Next's character. + +### Type Scale + +| Token | Size | Weight | Line Height | Tracking | Usage | +|-------|------|--------|-------------|----------|-------| +| `--text-display-xl` | `clamp(40px, 5vw, 64px)` | 700 | 1.05 | 0 | Hero headlines — model names ("iX3", "5 Series") | +| `--text-display-lg` | `clamp(32px, 4vw, 48px)` | 700 | 1.1 | 0 | Section heads, configurator titles | +| `--text-display-md` | `clamp(24px, 2.5vw, 32px)` | 700 | 1.15 | 0 | Sub-section heads, feature band titles | +| `--text-display-sm` | `24px` | 700 | 1.25 | 0 | CTA-band headlines, spec values | +| `--text-title-lg` | `20px` | 700 | 1.3 | 0 | Card group titles | +| `--text-title-md` | `18px` | 700 | 1.4 | 0 | Model card titles, intro paragraphs | +| `--text-title-sm` | `16px` | 700 | 1.4 | 0 | Inventory card titles, list labels | +| `--text-body-md` | `16px` | 300 (Light) | 1.55 | 0 | Default body — BMW Type Next Latin Light | +| `--text-body-sm` | `14px` | 300 (Light) | 1.55 | 0 | Footer body, fine-print, secondary copy | +| `--text-caption` | `12px` | 400 | 1.4 | 0.5px | Photo captions, meta, timestamps | +| `--text-label-uppercase` | `13px` | 700 | 1.3 | 1.5px | "LEARN MORE" inline links, category tabs (UPPERCASE) | +| `--text-button` | `14px` | 700 | 1.0 | 0.5px | Standard CTA button label | +| `--text-nav-link` | `14px` | 400 | 1.4 | 0.3px | Top-nav menu items | + +### Typography Principles + +- **The 700/300 contrast is non-negotiable.** Weight 700 for all display and interactive text. Weight 300 (Light) for all body and descriptive copy. This is BMW's editorial signature — "European-engineered" precision through typographic contrast. +- **No negative letter-spacing.** BMW Type Next Latin works on a wide body. Apple-style tightening reads off-brand. Tracking stays at 0 for display and body; only labels and buttons use positive tracking. +- **UPPERCASE inline links** — "LEARN MORE", "CONFIGURE", "DISCOVER" run uppercase with 1.5px tracking. The machined-precision voice. +- **Weight 400 is narrow-lane.** Only caption and nav-link, both neutral utility contexts. Weight 500 is absent from the system entirely. +- **Headlines never wrap more than two lines.** If a headline wraps, reduce the copy, not the font size. +- **Line height for display: 1.05–1.25. For body: 1.55.** The generous body line height balances the tight display leading. + +--- + +## 4. Component Stylings + +### Buttons + +**Primary CTA (BMW Blue)** +```css +background: var(--color-primary); +color: var(--color-on-primary); +padding: 14px 32px; +height: 48px; +border-radius: 0px; +font-size: 14px; +font-weight: 700; +letter-spacing: 0.5px; +border: none; +cursor: pointer; +transition: background 200ms ease; +``` +- Hover: `var(--color-primary-active)` +- Active: pressed state + `scale(0.98)` +- Disabled: `background: var(--color-primary-disabled); color: var(--color-muted)` + +**Secondary (Outlined)** +```css +background: var(--color-canvas); +color: var(--color-ink); +padding: 13px 31px; +height: 48px; +border-radius: 0px; +border: 1px solid var(--color-hairline-strong); +font-size: 14px; +font-weight: 700; +letter-spacing: 0.5px; +``` +- Hover: `background: var(--color-surface-soft)` + +**Secondary on Dark** +```css +background: transparent; +color: var(--color-ink); +padding: 13px 31px; +border-radius: 0px; +border: 1px solid var(--color-ink); +``` +- Used over dark hero bands and CTA sections + +**Text Link (Inline UPPERCASE)** +```css +background: transparent; +color: var(--color-ink); +font-size: 13px; +font-weight: 700; +letter-spacing: 1.5px; +text-transform: uppercase; +``` +- Terminated by a `›` chevron. No underline, no background. +- Hover: `color: var(--color-primary)` + +**No pill buttons. No rounded corners on buttons. No icon-only buttons without a label.** The rectangular 0px-radius button is the BMW corporate signature — engineered, not decorated. + +### Navigation + +- Fixed top bar, `height: 64px`, white (`var(--color-canvas)`) background. +- Dark mode: `var(--color-canvas)` background, white text. +- Left: BMW roundel logo. Center: primary horizontal menu (Models, Electric, Build Your Own, Dealers). Right: search icon, profile. +- Nav links: 14px / 400 / 0.3px tracking, `var(--color-ink)`. Active: `var(--color-primary)`. +- No hamburger icon on desktop. Below 768px: full-screen sheet menu. +- Transparent variant over hero images: `background: rgba(26, 33, 41, 0.85); backdrop-filter: blur(12px)`. + +### Cards + +- **Model Card:** `background: var(--color-canvas)`, `border-radius: 0px`, `padding: 24px`. Vehicle render on `var(--color-surface-card)` plate (edge-to-edge, no border). Model name in 18px / 700 below. One-line tagline in 14px / 300. "LEARN MORE ›" text link. +- **Feature Card:** Same structure with 16:9 lifestyle photo top, headline + excerpt below. +- **No box-shadow on cards.** Depth comes from color-block contrast (light card on white vs. dark hero band), not from elevation shadows. +- **No border-radius on cards.** 0px corners — the machined aesthetic. + +### Image Treatments + +- Hero photography: full-bleed, `width: 100%; aspect-ratio: 16/9` or `21/9`, `object-fit: cover`. +- Model card renders: `aspect-ratio: 16/10`, studio-lit on neutral background, full vehicle silhouette visible. +- No rounded corners on images. No visible image borders. No decorative frames. +- Overlay gradient only for text legibility: `linear-gradient(to top, rgba(26, 33, 41, 0.85) 0%, transparent 60%)`. +- Dark mode: photography may shift to more dramatic, low-key lighting — but always premium, never gritty. + +### Data / Specs + +- Spec cells use `var(--color-muted)` labels in `--text-label-uppercase`, `var(--color-ink)` values in `--text-display-sm` (24px / 700). +- Vertical spacing between spec rows: 24px. +- No alternating row colors. Dividers: 1px `var(--color-hairline)`. +- Spec values always run in weight 700 — even a number is a statement of precision. + +--- + +## 5. Layout Principles + +### Grid + +- **Max content width:** 1440px, center-aligned. +- **12-column grid** at desktop. 4-column at tablet. 1-column at mobile. +- **Column gap:** 24px. +- **Model card grids:** 4-up or 5-up at desktop, 2-up at tablet, 1-up on mobile. +- **Configurator:** 3-up filter row + 4-up vehicle cards, denser than editorial pages. + +### Spacing System + +Base unit: **8px**. + +| Token | Value | Usage | +|-------|-------|-------| +| `--space-xxs` | 4px | Tight internal gaps | +| `--space-xs` | 8px | Icon gaps, chip internal | +| `--space-sm` | 12px | Category tab padding | +| `--space-md` | 16px | Card padding (inventory), input padding | +| `--space-lg` | 24px | Card padding (model/feature), column gap | +| `--space-xl` | 32px | Sub-section gaps | +| `--space-xxl` | 48px | Section internal breaks | +| `--space-section` | 80px | Major editorial band padding — the heartbeat | + +### Section Rhythm + +Pages alternate between light and dark bands in a deliberate cadence: light canvas, dark hero, light feature, dark CTA, light footer. Two consecutive same-mode bands are not allowed — the rhythm demands alternation. + +- Section padding: `80px` vertical (tighter than BMW M's 96px — corporate is more utility-driven). +- Between headline and body: `24px`. +- Between body and CTA: `32px`. +- Edge padding (mobile): `16px`. +- Edge padding (desktop): auto, centered in 1440px max-width. + +### Alignment + +- Headlines and CTAs are center-aligned in hero and CTA bands. +- Feature sections use asymmetric split: 60% image / 40% text, or vice versa. +- Spec tables are left-aligned with right-aligned values. +- The twin kidney grille philosophy: symmetry where it matters (navigation, hero layout), asymmetric balance everywhere else. + +--- + +## 6. Depth & Elevation + +**No drop shadows. Ever.** BMW's depth system is flat by conviction. Depth comes from color-block contrast (light canvas vs. dark hero) and photographic subject lighting, not from artificial elevation. + +### Surface Hierarchy + +| Level | Treatment | Use Case | +|-------|-----------|----------| +| 0 | `var(--color-canvas)` — no shadow, no border | Body, top nav, footer, hero bands | +| 1 | 1px `var(--color-hairline)` border | Configurator option tiles, table dividers | +| 2 | `var(--color-surface-card)` background — no shadow | Model card photo plates | +| 3 | Edge-to-edge photography | Hero bands, vehicle renders | +| 4 | `var(--color-surface-elevated)` on dark | Nested cards over dark hero | + +### Metallic Surface Cues + +BMW uses subtle surface differentiation to evoke metallic materiality: + +- **Light mode:** `#FFFFFF` vs `#FAFAFA` vs `#F7F7F7` — three shades of white that read as brushed aluminum surfaces under different light angles. +- **Dark mode:** `#1A2129` vs `#1E2730` vs `#262E38` — warm navy layers that evoke matte gunmetal and anodized surfaces, not flat void. +- Transition between surface levels: `200ms ease` — swift but not sudden, like a precision mechanism. + +### Brand Signature Depth + +- **M Tricolor Divider:** 4px horizontal stripe (`#1A8FD4` / `#1C69D4` / `#E22718`). Only in M-model contexts and motorsport badges. Never as a CTA fill, never as a general decorative element. This is a controlled accent — the engineering stripe on a cam cover, not a racing stripe on the hood. + +--- + +## 7. Do's and Don'ts + +**Do:** + +- Use BMW Blue (`#1C69D4` light / `#3B8FE3` dark) as the single primary action color — it carries every CTA +- Set display headlines in weight 700 and body in Light 300 — the contrast is the editorial signature +- Use UPPERCASE letter-spaced links ("LEARN MORE ›") as inline CTAs — the machined-precision voice +- Alternate light and dark bands in deliberate rhythm — no two consecutive same-mode sections +- Place model card photos on `#FAFAFA` plates with the title beneath — the standard BMW corporate pattern +- Hold section rhythm at 80px — the corporate heartbeat +- Use the warm dark navy (`#1A2129`) for dark surfaces — it carries Bavarian heritage, not emptiness +- Let photography do the heavy lifting — studio-lit vehicle renders and cinematic environmental shots +- Use rectangular 0px-radius for all interactive elements — engineered, not decorated +- Reserve the M tricolor stripe exclusively for M-model contexts + +**Don't:** + +- Do not use pure black (`#000000`) for dark mode backgrounds — BMW's dark surfaces are warm navy, not void +- Do not use pill or rounded buttons — 0px rectangular is the brand button +- Do not add drop shadows to cards or any element — depth comes from color-block contrast and photography +- Do not drop display weight below 700 or raise body weight above 300 — the duo is fixed +- Do not use weight 500 — it is absent from the system; choose 400 or 700 +- Do not use negative letter-spacing — BMW Type works at default tracking; tightening reads off-brand +- Do not use more than one brand accent color per page — BMW Blue carries all primary actions +- Do not use the M tricolor stripe as a CTA fill or general decoration — divider and accent role only +- Do not place text over busy photography without a gradient overlay scrim +- Do not use italic for emphasis — use weight contrast or size contrast instead +- Do not mix rounded and rectangular elements — if one element is 0px radius, all must be + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Width | Behavior | +|------|-------|----------| +| Mobile | `< 768px` | Single column, stacked. Hero headline reduces to 40px. Nav collapses to hamburger with full-screen sheet. Model card grid 1-up. Configurator filters scroll horizontally. Footer 4-col to 1-col. | +| Tablet | `768–1024px` | Secondary nav hides under "More". Model card 2-up. Inventory 2-up. Hero headline 48px. | +| Desktop | `1024–1440px` | Full top-nav. 4-up or 5-up model card grid. Inventory 3-up. Full configurator UI. Hero headline 64px. | +| Wide | `> 1440px` | Same as desktop. Content fixed at 1440px max-width. Gutters absorb remaining space. | + +### Mobile-Specific Rules + +- Hero headline: `clamp(40px, 5vw, 64px)` — never below 40px +- Model card grid collapses to single column with full-width cards +- Configurator filter chip row scrolls horizontally — no wrapping +- Bottom sticky CTA bar may appear on mobile (transparent dark navy, white text) +- Touch targets: minimum 48x48px (above WCAG AAA) +- Text input height: 48px +- Category tabs: 12px vertical padding for tap area > 44px +- Hero photography shifts to more vertical crop (art direction for mobile aspect ratios) +- Inventory photos may shift from 16:9 to 4:3 on mobile + +### Image Behavior + +- Model renders scale at every breakpoint while preserving native aspect ratios +- Hero photography crops to focus on vehicle front on mobile; full side profile on desktop +- The M tricolor stripe stays at 4px height across every breakpoint + +### Dark Mode Switching + +Dark mode is the premium default for product configurator and model detail pages. Use `prefers-color-scheme` media query for automatic switching; always provide a manual toggle. All color tokens swap simultaneously. Photography may shift between modes — BMW often uses more dramatic, low-key imagery in dark mode. Transition between modes should be instant (no animation on color swap). diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/figma.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/figma.md new file mode 100644 index 00000000..a41ce72e --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/figma.md @@ -0,0 +1,270 @@ +# Figma Design System + +## 1. Visual Theme & Atmosphere + +Figma's visual identity is built on **creative confidence**: a vibrant, multi-color palette that feels playful without sacrificing professionalism. The aesthetic channels a design tool that knows its users are visually literate, so it rewards attention with rich color and purposeful asymmetry rather than safe neutrality. + +Key atmosphere traits: +- **Energetic optimism** -- saturated hues communicate possibility and creative freedom +- **Structured playfulness** -- bright colors are balanced by generous whitespace and a clean grid, never chaotic +- **Tool-first confidence** -- the UI feels like it belongs to a product you trust with your craft; chrome is minimal, content is foregrounded +- **Inclusive warmth** -- rounded geometry and warm tones keep the brand approachable despite its professional depth + +## 2. Color Palette & Roles + +### Core Brand Colors + +| Semantic Name | Hex | Role | +|---|---|---| +| `brand-primary` | `#F24E1E` | Primary actions, CTAs, key highlights, logo mark | +| `brand-red` | `#FF7262` | Secondary accent, hover states on primary, illustration fills | +| `brand-purple` | `#A259FF` | Feature emphasis, badges, decorative gradient endpoints | +| `brand-green` | `#0ACF83` | Success states, positive indicators, growth metrics | +| `brand-blue` | `#1ABCFE` | Informational elements, links, data visualization | + +### Surface & Neutral Colors (Dark Mode Primary) + +| Semantic Name | Hex | Role | +|---|---|---| +| `surface-base` | `#1E1E1E` | Page background, canvas | +| `surface-raised` | `#2C2C2C` | Cards, panels, elevated containers | +| `surface-overlay` | `#3C3C3C` | Modals, dropdowns, popover backgrounds | +| `surface-hover` | `#4A4A4A` | Hover states on raised surfaces | +| `border-subtle` | `#3C3C3C` | Default borders, dividers | +| `border-strong` | `#5C5C5C` | Active borders, input focus rings | +| `text-primary` | `#FFFFFF` | Headings, primary body text | +| `text-secondary` | `#B3B3B3` | Captions, descriptions, muted labels | +| `text-tertiary` | `#808080` | Placeholders, disabled text, hints | + +### Surface & Neutral Colors (Light Mode) + +| Semantic Name | Hex | Role | +|---|---|---| +| `surface-base` | `#FFFFFF` | Page background | +| `surface-raised` | `#F5F5F5` | Cards, panels | +| `surface-overlay` | `#E8E8E8` | Modals, dropdowns | +| `border-subtle` | `#E5E5E5` | Default borders | +| `border-strong` | `#CCCCCC` | Active borders | +| `text-primary` | `#1E1E1E` | Headings, primary body text | +| `text-secondary` | `#666666` | Captions, descriptions | +| `text-tertiary` | `#999999` | Placeholders, disabled text | + +### Semantic Colors + +| Semantic Name | Hex | Role | +|---|---|---| +| `color-success` | `#0ACF83` | Confirmations, saved states, valid inputs | +| `color-warning` | `#FF9F43` | Caution alerts, unsaved changes | +| `color-error` | `#F24E1E` | Error states, destructive actions, validation failures | +| `color-info` | `#1ABCFE` | Tooltips, informational banners, help indicators | + +### Gradient Presets + +| Name | Value | Usage | +|---|---|---| +| `gradient-brand` | `linear-gradient(135deg, #F24E1E 0%, #A259FF 100%)` | Hero sections, feature highlights | +| `gradient-rainbow` | `linear-gradient(135deg, #F24E1E 0%, #A259FF 33%, #1ABCFE 66%, #0ACF83 100%)` | Brand moments, event banners | +| `gradient-warm` | `linear-gradient(135deg, #F24E1E 0%, #FF7262 100%)` | CTA backgrounds, emphasis panels | +| `gradient-cool` | `linear-gradient(135deg, #1ABCFE 0%, #A259FF 100%)` | Secondary feature blocks | + +## 3. Typography Rules + +### Font Stack + +- **Display / Headlines**: `"Inter", system-ui, -apple-system, sans-serif` +- **Body**: `"Inter", system-ui, -apple-system, sans-serif` +- **Code / Monospace**: `"JetBrains Mono", "Fira Code", "Consolas", monospace` + +Inter is used across all weights, with dramatic weight contrast creating hierarchy rather than switching font families. + +### Type Scale + +| Level | Size | Weight | Line Height | Letter Spacing | Usage | +|---|---|---|---|---|---| +| `display` | `clamp(3rem, 5vw, 5rem)` | 800 | 1.05 | -0.03em | Hero headlines, page titles | +| `h1` | `clamp(2.25rem, 3.5vw, 3.5rem)` | 700 | 1.1 | -0.02em | Section titles | +| `h2` | `clamp(1.75rem, 2.5vw, 2.5rem)` | 700 | 1.15 | -0.015em | Subsection titles | +| `h3` | `clamp(1.25rem, 1.5vw, 1.75rem)` | 600 | 1.2 | -0.01em | Card titles, feature headings | +| `body-lg` | `1.125rem` | 400 | 1.6 | 0 | Lead paragraphs, introductions | +| `body` | `1rem` | 400 | 1.6 | 0 | Default body text | +| `body-sm` | `0.875rem` | 400 | 1.5 | 0.005em | Captions, metadata, helper text | +| `caption` | `0.75rem` | 500 | 1.4 | 0.01em | Labels, badges, timestamps | +| `code` | `0.875rem` | 400 | 1.5 | 0 | Inline code, code blocks | + +### Rules + +- Never use weight below 400 for body text; 300 is reserved for decorative display only +- Headlines use tight negative letter-spacing; body text uses neutral or slightly positive tracking +- Maximum line length: 65ch for body text, 40ch for captions +- Use weight jumps (400 to 700) for emphasis rather than italic or underline in body text +- Code snippets always use monospace with a subtle background tint (`rgba(162, 89, 255, 0.08)` in dark mode) + +## 4. Component Stylings + +### Buttons + +| Variant | Background | Text | Border | Radius | Hover | +|---|---|---|---|---|---| +| Primary | `#F24E1E` | `#FFFFFF` | none | 8px | `#D4411A`, translateY(-1px) | +| Secondary | `transparent` | `#FFFFFF` | `#5C5C5C` | 8px | border `#F24E1E`, text `#F24E1E` | +| Ghost | `transparent` | `#B3B3B3` | none | 8px | bg `rgba(255,255,255,0.06)` | +| Brand Gradient | `gradient-brand` | `#FFFFFF` | none | 8px | `gradient-warm`, translateY(-1px) | + +- Padding: `12px 24px` default, `10px 20px` compact +- Transition: `all 150ms cubic-bezier(0.16, 1, 0.3, 1)` +- Active state: `translateY(1px)`, opacity 0.9 +- Focus ring: `2px solid #1ABCFE`, offset 2px +- Icon buttons: 40x40px square, `border-radius: 10px` + +### Cards + +- Background: `surface-raised` (`#2C2C2C` dark / `#F5F5F5` light) +- Border: `1px solid border-subtle` +- Border-radius: `12px` +- Padding: `24px` +- Hover: `translateY(-2px)`, `box-shadow: 0 8px 30px rgba(0,0,0,0.3)` +- Transition: `transform 200ms cubic-bezier(0.16, 1, 0.3, 1), box-shadow 200ms ease` +- Featured cards: left border accent `3px solid` using brand color matching the content theme + +### Inputs + +- Background: `surface-base` (`#1E1E1E` dark / `#FFFFFF` light) +- Border: `1px solid border-subtle` +- Border-radius: `8px` +- Padding: `10px 14px` +- Focus: border `#1ABCFE`, `box-shadow: 0 0 0 3px rgba(26, 188, 254, 0.15)` +- Error: border `#F24E1E`, error message in `color-error` below input +- Placeholder: `text-tertiary` + +### Tags / Badges + +- Border-radius: `6px` +- Padding: `4px 10px` +- Font: `caption` (0.75rem, 500) +- Color variants use brand colors with 12% opacity backgrounds: + - Purple badge: bg `rgba(162,89,255,0.12)`, text `#A259FF` + - Green badge: bg `rgba(10,207,131,0.12)`, text `#0ACF83` + - Blue badge: bg `rgba(26,188,254,0.12)`, text `#1ABCFE` + - Red badge: bg `rgba(242,78,30,0.12)`, text `#F24E1E` + +### Tooltips + +- Background: `#4A4A4A` +- Text: `#FFFFFF`, `body-sm` +- Border-radius: `6px` +- Padding: `6px 12px` +- Arrow: 6px CSS triangle +- Delay: 300ms show, 100ms hide + +### Toggles / Switches + +- Track: `#3C3C3C` off, `#0ACF83` on +- Knob: `#FFFFFF`, 18px diameter +- Track height: 24px, width 44px, border-radius 12px +- Transition: `background 200ms ease, transform 200ms cubic-bezier(0.16, 1, 0.3, 1)` + +## 5. Layout Principles + +### Grid + +- Desktop: 12-column grid, 24px gutters, 64px max outer margin +- Tablet: 8-column grid, 20px gutters +- Mobile: 4-column grid, 16px gutters +- Max content width: `1200px` (centered) +- Wide layout: `1440px` for hero and showcase sections + +### Spacing Scale + +| Token | Value | Usage | +|---|---|---| +| `space-1` | 4px | Inline gaps, icon padding | +| `space-2` | 8px | Tight component spacing | +| `space-3` | 12px | Form element gaps | +| `space-4` | 16px | Component internal padding | +| `space-5` | 24px | Card padding, standard gaps | +| `space-6` | 32px | Section sub-spacing | +| `space-7` | 48px | Between related sections | +| `space-8` | 64px | Between distinct sections | +| `space-9` | 96px | Major section dividers | +| `space-10` | 128px | Hero-level vertical rhythm | + +### Layout Patterns + +- **Z-pattern** for marketing pages: headline + CTA top-left, visual top-right, content flows diagonally +- **Feature grid**: 3-column cards with icon, title, description; each card may use a different brand accent color for its icon to reinforce the multi-color identity +- **Asymmetric split**: 60/40 text-to-visual ratio on feature sections, alternating sides +- **Full-bleed heroes**: content constrained to grid but background colors/gradients extend edge-to-edge +- Sticky navigation with `backdrop-filter: blur(12px)` and `background: rgba(30,30,30,0.85)` + +## 6. Depth & Elevation + +Figma's depth system is restrained and functional, favoring subtle surface differentiation over dramatic shadows. + +### Elevation Levels + +| Level | Shadow (Dark Mode) | Shadow (Light Mode) | Usage | +|---|---|---|---| +| Level 0 | none | none | Base canvas, flat surfaces | +| Level 1 | `0 1px 3px rgba(0,0,0,0.3)` | `0 1px 3px rgba(0,0,0,0.08)` | Cards at rest | +| Level 2 | `0 4px 12px rgba(0,0,0,0.3)` | `0 4px 12px rgba(0,0,0,0.1)` | Hovered cards, raised panels | +| Level 3 | `0 8px 30px rgba(0,0,0,0.4)` | `0 8px 30px rgba(0,0,0,0.12)` | Modals, dropdowns | +| Level 4 | `0 16px 50px rgba(0,0,0,0.5)` | `0 16px 50px rgba(0,0,0,0.16)` | Toast notifications, spotlight overlays | + +### Depth Through Color + +- Prefer surface color shifts (darker backgrounds for elevation) over heavy shadows +- Overlay modals use `backdrop-filter: blur(8px)` on the scrim layer +- Glassmorphism accents: `background: rgba(44,44,44,0.7)`, `backdrop-filter: blur(16px)`, `border: 1px solid rgba(255,255,255,0.08)` -- use sparingly for floating toolbars and context menus only + +### Overlap & Layering + +- Hero sections may overlap into the next section by `-48px` to `--space-7` with a rounded bottom container +- Illustration elements can break out of their container bounds by up to 20% for visual energy +- Brand color shapes (circles, rounded rectangles at 10% opacity) may overlap content as decorative background layers + +## 7. Do's and Don'ts + +### Do + +- Use the full brand color set (orange, red, purple, green, blue) to differentiate features and sections -- the palette is meant to be used, not hoarded +- Apply generous whitespace around headlines and CTAs to let the vibrant colors breathe +- Use Inter weight 700-800 for headlines and 400 for body to create clear typographic hierarchy +- Pair dark surfaces with saturated accent colors -- they need the contrast to pop +- Use gradient-brand for primary CTAs and hero moments; use solid brand-primary for repeated UI elements +- Round corners consistently: 8px for inputs and small elements, 12px for cards, 16px+ for hero containers +- Use micro-interactions (scale 1.02 on hover, 150-200ms) to reinforce the playful-but-precise personality +- Let illustrations and visuals carry color; keep chrome (navigation, toolbars) neutral + +### Don't + +- Don't use all five brand colors on a single component -- pick one accent per element +- Don't apply gradients to body text or small UI labels; reserve them for backgrounds and CTAs +- Don't use drop shadows on text -- Figma's brand never uses text shadows +- Don't mix warm (orange/red) and cool (blue/purple) accents as adjacent equals without a neutral spacer +- Don't use pure black (`#000000`) for text on dark backgrounds; use `#FFFFFF` or `text-primary` instead +- Don't over-blur -- limit `backdrop-filter: blur()` to 16px maximum and use only on overlay elements +- Don't use rounded corners below 6px -- the system avoids sharp edges entirely +- Don't place saturated accent-colored text on saturated backgrounds; maintain sufficient contrast (WCAG AA minimum) +- Don't animate `width`, `height`, `top`, or `left`; use `transform` and `opacity` for all motion + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min Width | Columns | Gutter | Typical Target | +|---|---|---|---|---| +| `mobile` | 0 | 4 | 16px | Phones (<640px) | +| `tablet` | 640px | 8 | 20px | Tablets, small laptops | +| `desktop` | 1024px | 12 | 24px | Laptops, desktops | +| `wide` | 1440px | 12 | 24px | Large monitors | + +### Adaptation Rules + +- **Hero section**: Stacks vertically on mobile (headline over visual), maintains side-by-side from tablet up. Font size scales via `clamp()` across all breakpoints. +- **Feature grid**: 3 columns on desktop, 2 on tablet, 1 on mobile. Cards maintain consistent padding but reduce to `20px` on mobile. +- **Navigation**: Full horizontal nav on desktop, hamburger menu with slide-in drawer on mobile. Drawer uses `surface-raised` background with `border-left` accent in `brand-primary`. +- **CTAs**: Full-width on mobile, auto-width on tablet and up. Minimum touch target: 44px height on mobile. +- **Images and illustrations**: `width: 100%` with `aspect-ratio` preserved. Hero visuals may be hidden or replaced with a simplified version below `tablet` breakpoint if they contain fine detail. +- **Typography scaling**: All heading sizes use `clamp()` to fluidly scale between breakpoints. Body text stays at `1rem` across all sizes. +- **Color accents**: Brand color shapes used as decorative backgrounds are hidden on mobile to reduce visual noise. Gradient hero backgrounds simplify to solid `brand-primary` on mobile. +- **Spacing reduction**: `space-9` and `space-10` sections collapse to `space-7` on tablet and `space-6` on mobile. Card grids reduce gap from `space-5` to `space-4` to `space-3` respectively. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/framer.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/framer.md new file mode 100644 index 00000000..66047429 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/framer.md @@ -0,0 +1,157 @@ +# Framer Design System + +Bold black and electric blue. Motion-first, design-forward. The interface feels alive — every transition is intentional, every hover is a micro-showcase. Built for people who build websites. + +--- + +## 1. Visual Theme & Atmosphere + +Dark, high-contrast surfaces with electric blue punctuating key interactions. The aesthetic says "creative tool" — confident, slightly playful, never corporate. Smooth motion is non-negotiable; static states feel broken. Interactive showcases and live previews are the content, not decoration around content. + +**Keywords:** bold, electric, motion-first, interactive, creative, confident + +--- + +## 2. Color Palette & Roles + +| Name | Hex | Role | +|------|-----|------| +| Electric Blue | `#0055FF` | Primary accent, CTAs, active states, links | +| Deep Black | `#0A0A0A` | Primary background | +| Rich Black | `#141414` | Card/surface background | +| Elevated Black | `#1E1E1E` | Hover surfaces, input backgrounds | +| Pure White | `#FFFFFF` | Primary text on dark | +| Soft White | `#B0B0B0` | Secondary text, placeholders | +| Muted Gray | `#6B6B6B` | Tertiary text, disabled states | +| Border Subtle | `#2A2A2A` | Dividers, card borders | +| Blue Glow | `#0055FF` at 20% opacity | Focus rings, hover glow | +| Success | `#00C853` | Positive actions, confirmations | +| Warning | `#FFAB00` | Caution states | +| Error | `#FF1744` | Destructive actions, validation errors | + +**Rule:** Electric Blue is the soul. Use it for every interactive affordance. Never dilute it with gradients — it should hit pure and saturated. + +--- + +## 3. Typography Rules + +**Primary:** Inter (or fallback: system sans-serif) +**Display:** Fraktion (or fallback: Inter with tight tracking) + +| Element | Font | Weight | Size | Tracking | Case | +|---------|------|--------|------|----------|------| +| Display hero | Fraktion | 600 | clamp(48px, 5vw, 80px) | -0.04em | Title | +| Section title | Inter | 700 | clamp(28px, 2.5vw, 44px) | -0.02em | Title | +| Subheading | Inter | 600 | 20px | -0.01em | Sentence | +| Body | Inter | 400 | 16px | 0 | Sentence | +| Body small | Inter | 400 | 14px | 0 | Sentence | +| Caption | Inter | 500 | 12px | 0.02em | Uppercase | +| Code / mono | JetBrains Mono | 400 | 14px | 0 | — | + +**Rules:** +- Display headlines use tight negative tracking to feel punchy and dense. +- Body line-height: 1.6. Headlines: 1.1. +- Bold (700) for emphasis, never italic. Italic reserved for captions only. +- Code snippets always use mono font with `#1E1E1E` background. + +--- + +## 4. Component Stylings + +### Buttons +- **Primary CTA:** `#0055FF` background, white text, `border-radius: 8px`, padding `12px 24px`, weight 600. On hover: scale 1.02, box-shadow `0 0 20px rgba(0,85,255,0.4)`. +- **Secondary CTA:** `#1E1E1E` background, white text, 1px `#2A2A2A` border. On hover: border becomes `#0055FF`. +- **Ghost:** Transparent, white text, no border. On hover: text becomes `#0055FF`. +- **Icon button:** 40x40px, `border-radius: 10px`, `#1E1E1E` bg. On hover: bg `#2A2A2A`. + +### Navigation +- Fixed top bar, `height: 64px`, backdrop-blur over dark content. +- Logo left, nav center, CTA right. +- Active nav link: `#0055FF` text, 2px bottom border. +- Hover: text color transition 150ms. + +### Cards +- Background: `#141414`, `border-radius: 12px`, 1px `#2A2A2A` border. +- Padding: 24px. Hover: border becomes `#0055FF`, subtle translateY(-2px) with 200ms ease-out. +- No box-shadow at rest. Glow on hover only. + +### Input Fields +- Background: `#1E1E1E`, `border-radius: 8px`, 1px `#2A2A2A` border. +- Focus: border `#0055FF`, box-shadow `0 0 0 3px rgba(0,85,255,0.15)`. +- Placeholder: `#6B6B6B`. + +### Interactive Showcases +- Live preview panels with `border-radius: 16px`, `border: 1px #2A2A2A`. +- Tab bar above preview: `#141414` bg, active tab has `#0055FF` bottom border. +- Preview area: `#0A0A0A` bg. + +### Code Blocks +- `#1E1E1E` background, `border-radius: 8px`, JetBrains Mono. +- Line numbers: `#6B6B6B`. Syntax highlighting: blue `#0055FF`, green `#00C853`, yellow `#FFAB00`, red `#FF1744`. + +--- + +## 5. Layout Principles + +- **Max content width:** 1200px centered. Wide showcases: 1400px. +- **Grid:** 12-column, 16px gutters on desktop, 8px on mobile. +- **Sections alternate rhythm:** tight (64px padding) for feature stacks, generous (120px) for hero sections. +- **Asymmetric layouts:** 7/5 or 8/4 splits for text + interactive preview. +- **Sticky sidebars** on documentation pages (240px width). +- **Showcase sections** take near-full-width to let interactive demos breathe. + +--- + +## 6. Depth & Elevation + +Depth is expressed through layering and glow, not shadows: + +| Level | Surface | Use | +|-------|---------|-----| +| 0 | `#0A0A0A` | Page background | +| 1 | `#141414` | Cards, panels | +| 2 | `#1E1E1E` | Inputs, elevated cards on hover | +| 3 | `#0055FF` glow | Focus, active states | + +- **No ambient shadows.** Elevation = background lightness change. +- **Blue glow** on interactive elements creates perceived depth through color, not shadow. +- **Backdrop-blur** on fixed nav and modals (blur(12px), 80% opacity dark). + +--- + +## 7. Do's and Don'ts + +**Do:** +- Add motion to every state change (hover, focus, appear, exit) — 150–300ms ease-out +- Use Electric Blue consistently for all interactive elements +- Let interactive showcases be the hero content +- Use tight tracking on headlines for punch +- Round corners on cards and inputs (8–12px) — it softens the dark aesthetic +- Provide keyboard focus rings with blue glow + +**Don't:** +- Use drop shadows for elevation — use surface color instead +- Apply Electric Blue to large background areas (it loses impact) +- Use more than one animation timing per element +- Place long paragraphs in dark surfaces without line-height 1.6 +- Use gray for interactive elements — if it responds to input, it should hint blue +- Create static pages — motion is the brand + +--- + +## 8. Responsive Behavior + +| Breakpoint | Behavior | +|-----------|----------| +| < 640px | Single column. Interactive previews stack below text. Nav collapses to hamburger. Card grid: 1 column. | +| 640–768px | Single column. Preview panels go full-width. Sidebar navigation hidden (use top tabs). | +| 768–1024px | 2-column card grid. Side-by-side text+preview appears. Sidebar nav at 200px. | +| 1024–1440px | 3-column card grid. Full asymmetric splits. Sidebar at 240px. | +| > 1440px | Content max-width 1200px (1400px for showcases), centered. | + +**Mobile-specific rules:** +- Interactive showcases become static screenshots with a "Try it" CTA linking to the full experience +- Hover states replaced by tap states with 100ms scale pulse +- Blue glow on focus adapts to `0 0 0 2px rgba(0,85,255,0.3)` (smaller ring) +- Touch targets: minimum 44x44px +- Bottom sheet for navigation on mobile instead of hamburger dropdown diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/ibm.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/ibm.md new file mode 100644 index 00000000..2c8a286f --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/ibm.md @@ -0,0 +1,419 @@ +# IBM Design System + +Enterprise authority through structured restraint. IBM's visual language is built on the Carbon Design System — an open-source framework where every pixel earns its place through utility, not decoration. The 8-bar motif from the IBM logo is the design philosophy made manifest: horizontal stripes of equal weight, orderly progression, nothing ornamental. Dark mode is not a luxury mode — it is a first-class citizen with dedicated theme tokens (g90, g100). Information density is a virtue, not a vice. Trust is communicated through consistency, not through charisma. + +--- + +## 1. Visual Theme & Atmosphere + +IBM's visual language communicates institutional trust and engineering rigor — the confidence of a company that has defined enterprise computing for over a century. Surfaces are flat and structured. Color is restrained: IBM Blue carries every primary action, gray-100 anchors every dark surface, and the 12-color palette family exists for data visualization and status communication, never for decoration. Typography works at two tempos: Productive (compact, task-focused, 14px default) for tools and dashboards; Expressive (fluid, spacious, larger scales) for marketing and storytelling. Both tempos are calibrated for IBM Plex, IBM's open-source typeface. + +The page is a data surface. White and gray-10 are the light canvases; gray-90 and gray-100 are the dark canvases. Layers are differentiated by background color shifts, not shadows. The 8px grid governs every spacing decision. The 2x Grid system provides 16 columns at desktop with five responsive breakpoints. Data tables, forms, and dashboards are the native content — not hero images. Photography, when used, is secondary to information. The 8-bar stripe motif appears as a controlled signature, not as wallpaper. + +**Keywords:** enterprise authority, structured restraint, information density, institutional trust, productive precision, Carbon discipline, 8-bar rhythm + +--- + +## 2. Color Palette & Roles + +IBM's color system is organized into 12 scale families, each with 10 stops (10 through 100, where 10 is lightest and 100 is deepest). Carbon defines four themes: White (high-contrast light), g10 (low-contrast light), g90 (low-contrast dark), g100 (high-contrast dark). Blue 60 (`#0F62FE`) is the canonical interactive color across all themes. + +### Light Mode (White / g10) + +| Token | Hex | Role | +|-------|-----|------| +| `--color-canvas` | `#FFFFFF` | Page background — the White theme default | +| `--color-surface` | `#F4F4F4` | Container background on canvas — gray-10, the g10 theme background | +| `--color-surface-elevated` | `#FFFFFF` | Elevated container on gray-10 surface — cards, modals | +| `--color-surface-strong` | `#E0E0E0` | Subtle border, tertiary background — gray-20 | +| `--color-ink` | `#161616` | Primary text — gray-100, high-contrast body and headings | +| `--color-body` | `#393939` | Default running text — gray-80 | +| `--color-muted` | `#525252` | Secondary text, labels — gray-70 | +| `--color-muted-soft` | `#6F6F6F` | Tertiary text, placeholder — gray-60 | +| `--color-primary` | `#0F62FE` | IBM Blue — all primary CTAs, links, active elements, interactive accent. blue-60 | +| `--color-primary-hover` | `#0043CE` | Hover state for primary — blue-70 | +| `--color-primary-active` | `#002D9C` | Active/pressed state for primary — blue-80 | +| `--color-primary-subtle` | `#EDF5FF` | Light tint background for selected/highlighted items — blue-10 | +| `--color-on-primary` | `#FFFFFF` | White text on blue buttons | +| `--color-hairline` | `#C6C6C6` | 1px dividers, input borders — gray-30 | +| `--color-hairline-strong` | `#8D8D8D` | Medium-contrast border, emphasis — gray-50 | +| `--color-accent` | `#8A3FFC` | Secondary accent — purple-60. Data viz, supplementary highlights | +| `--color-accent-hover` | `#6929C4` | Accent hover — purple-70 | +| `--color-success` | `#24A148` | Positive, available — green-50 | +| `--color-warning` | `#F1C21B` | Caution — yellow-30 | +| `--color-error` | `#DA1E28` | Destructive, error — red-60 | + +### Dark Mode (g90 / g100) + +| Token | Hex | Role | +|-------|-----|------| +| `--color-canvas` | `#161616` | Page background — gray-100, the g100 theme default | +| `--color-surface` | `#262626` | Container background on dark canvas — gray-90, the g90 theme default | +| `--color-surface-elevated` | `#393939` | Elevated container on dark surface — gray-80 | +| `--color-surface-strong` | `#525252` | Subtle border on dark, tertiary dark background — gray-70 | +| `--color-ink` | `#F4F4F4` | Primary text on dark — gray-10 | +| `--color-body` | `#C6C6C6` | Default running text on dark — gray-30 | +| `--color-muted` | `#A8A8A8` | Secondary text on dark — gray-40 | +| `--color-muted-soft` | `#8D8D8D` | Tertiary text on dark — gray-50 | +| `--color-primary` | `#0F62FE` | IBM Blue — unchanged across themes. blue-60 is universal | +| `--color-primary-hover` | `#4589FF` | Hover on dark — blue-50, shifted lighter for dark backgrounds | +| `--color-primary-active` | `#78A9FF` | Active on dark — blue-40 | +| `--color-primary-subtle` | `#001141` | Dark tint background for selected items — blue-100 | +| `--color-on-primary` | `#FFFFFF` | White text on blue buttons (unchanged) | +| `--color-hairline` | `#393939` | 1px dividers on dark — gray-80 | +| `--color-hairline-strong` | `#6F6F6F` | Emphasis borders on dark — gray-60 | +| `--color-accent` | `#A56EFF` | Secondary accent on dark — purple-50, shifted lighter | +| `--color-accent-hover` | `#BE95FF` | Accent hover on dark — purple-40 | +| `--color-success` | `#42BE65` | Positive on dark — green-40, shifted lighter | +| `--color-warning` | `#F1C21B` | Caution on dark — yellow-30, unchanged | +| `--color-error` | `#FA4D56` | Error on dark — red-50, shifted lighter | + +**Rule:** IBM Blue (`#0F62FE`, blue-60) is the one color that does not shift between light and dark themes. It is the fixed North Star — every other accent color shifts lighter on dark backgrounds to maintain contrast and legibility. The dark palette uses the gray scale inverted: gray-10 becomes text, gray-100 becomes canvas. This inversion is systematic, not aesthetic. + +### Full Color Families (for Data Visualization) + +| Family | 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100 | +|--------|------|------|------|------|------|------|------|------|------|------| +| Gray | `#F4F4F4` | `#E0E0E0` | `#C6C6C6` | `#A8A8A8` | `#8D8D8D` | `#6F6F6F` | `#525252` | `#393939` | `#262626` | `#161616` | +| Cool Gray | `#F2F4F8` | `#DDE1E6` | `#C1C7CD` | `#A2A9B0` | `#878D96` | `#697077` | `#4D5358` | `#343A3F` | `#21272A` | `#121619` | +| Blue | `#EDF5FF` | `#D0E2FF` | `#A6C8FF` | `#78A9FF` | `#4589FF` | `#0F62FE` | `#0043CE` | `#002D9C` | `#001D6C` | `#001141` | +| Red | `#FFF1F1` | `#FFD7D9` | `#FFB3B8` | `#FF8389` | `#FA4D56` | `#DA1E28` | `#A2191F` | `#750E13` | `#520408` | `#2D0709` | +| Green | `#DEFBE6` | `#A7F0BA` | `#6FDC8C` | `#42BE65` | `#24A148` | `#198038` | `#0E6027` | `#044317` | `#022D0D` | `#071908` | +| Yellow | `#FCF4D6` | `#FDDC69` | `#F1C21B` | `#D2A106` | `#B28600` | `#8E6A00` | `#684E00` | `#483700` | `#302400` | `#1C1500` | +| Purple | `#F6F2FF` | `#E8DAFF` | `#D4BBFF` | `#BE95FF` | `#A56EFF` | `#8A3FFC` | `#6929C4` | `#491D8B` | `#31135E` | `#1C0F30` | +| Cyan | `#E5F6FF` | `#BAE6FF` | `#82CFFF` | `#33B1FF` | `#1192E8` | `#0072C3` | `#00539A` | `#003A6D` | `#012749` | `#061727` | +| Teal | `#D9FBFB` | `#9EF0F0` | `#3DDBD9` | `#08BDBA` | `#009D9A` | `#007D79` | `#005D5D` | `#004144` | `#022B30` | `#081A1C` | +| Magenta | `#FFF0F7` | `#FFD6E8` | `#FFAFD2` | `#FF7EB6` | `#EE5396` | `#D02670` | `#9F1853` | `#740937` | `#510224` | `#2A0A18` | +| Orange | `#FFF2E8` | `#FFD9BE` | `#FFB784` | `#FF832B` | `#EB6200` | `#BA4E00` | `#8A3800` | `#5E2900` | `#3E1A00` | `#231000` | + +**Data visualization rule:** Use stops 40-70 for chart fills (sufficient contrast on both light and dark backgrounds). Use stops 10-20 for background tints. Use stops 80-100 for text labels on light charts. Never use stops 10-30 as text — insufficient contrast. + +--- + +## 3. Typography Rules + +**Primary:** IBM Plex Sans (IBM's open-source typeface, designed by Mike Abbink) +**Mono:** IBM Plex Mono (code, data, technical content) +**Serif:** IBM Plex Serif (long-form editorial, rarely used in product UI) +**Fallback stack:** `"IBM Plex Sans", "Helvetica Neue", Arial, sans-serif` + +### Productive Type Set (Product UI — Dashboards, Tools, Forms) + +| Token | Size | Weight | Line Height | Tracking | Usage | +|-------|------|--------|-------------|----------|-------| +| `--text-heading-05` | `32px` | 400 / Regular | 40px | 0 | Page titles, top-level headings in dashboards | +| `--text-heading-04` | `28px` | 400 / Regular | 36px | 0 | Section headings, panel titles | +| `--text-heading-03` | `24px` | 400 / Regular | 32px | 0 | Sub-section headings, card titles | +| `--text-heading-02` | `20px` | 400 / Regular | 28px | 0 | Component headings, group labels | +| `--text-heading-01` | `14px` | 600 / Semi-Bold | 18px | 0.16px | Small headings, field group labels, tile titles | +| `--text-body-02` | `16px` | 400 / Regular | 24px | 0 | Default body text, paragraphs, descriptions | +| `--text-body-01` | `14px` | 400 / Regular | 20px | 0.16px | Compact body — the product default. Table cells, form fields, lists | +| `--text-body-compact-02` | `16px` | 400 / Regular | 22px | 0 | Tighter line-height body for dense UI | +| `--text-body-compact-01` | `14px` | 400 / Regular | 18px | 0.16px | Tightest body — data tables, dense forms | +| `--text-label-02` | `14px` | 600 / Semi-Bold | 20px | 0 | Form labels, badge text, table headers | +| `--text-label-01` | `12px` | 400 / Regular | 16px | 0.32px | Captions, helper text, metadata, timestamps | +| `--text-helper-text` | `12px` | 400 / Regular | 16px | 0.32px | Inline help, validation messages | +| `--text-caption` | `12px` | 400 / Italic | 16px | 0.32px | Editorial captions only — never in product UI | +| `--text-code-02` | `16px` | 400 / Regular | 24px | 0.32px | Code blocks — IBM Plex Mono | +| `--text-code-01` | `14px` | 400 / Regular | 20px | 0.32px | Inline code — IBM Plex Mono | + +### Expressive Type Set (Marketing — Landing Pages, Campaigns, Storytelling) + +| Token | Size (lg) | Weight | Line Height | Tracking | Usage | +|-------|-----------|--------|-------------|----------|-------| +| `--text-display-03` | `64px` | 300 / Light | 72px | -0.5px | Hero headlines, campaign mastheads | +| `--text-display-02` | `48px` | 300 / Light | 56px | 0 | Section heroes, feature leads | +| `--text-display-01` | `36px` | 300 / Light | 44px | 0 | Feature titles, marketing sub-heads | +| `--text-expressive-heading-05` | `28px` | 600 / Semi-Bold | 36px | 0 | Marketing section headings | +| `--text-expressive-heading-04` | `24px` | 600 / Semi-Bold | 32px | 0 | Marketing sub-section headings | +| `--text-expressive-heading-03` | `20px` | 400 / Regular | 26px | 0 | Feature descriptions, intro paragraphs | +| `--text-expressive-heading-02` | `18px` | 600 / Semi-Bold | 24px | 0 | Card headings, callout titles | +| `--text-expressive-heading-01` | `14px` | 600 / Semi-Bold | 20px | 0.16px | Small callout headings, eyebrow text | +| `--text-expressive-paragraph-01` | `18px` | 400 / Regular | 28px | 0 | Marketing body, longer-form storytelling | +| `--text-quotation-02` | `24px` | 300 / Light | 34px | 0 | Pull quotes, testimonial text | +| `--text-quotation-01` | `18px` | 400 / Regular | 28px | 0 | Smaller pull quotes, inline citations | + +### Typography Principles + +- **14px is the product default.** IBM's product UI lives at 14px body text — not 16px. This is intentional: enterprise dashboards need information density, and 14px / 20px line-height maximizes visible data while remaining legible. This is the single biggest differentiator from consumer design systems. +- **Weight 400 is the workhorse.** Productive headings use Regular (400) weight — not Bold. Only label tokens and the smallest heading token (heading-01) use Semi-Bold (600). IBM trusts size and spacing for hierarchy, not weight. +- **Expressive mode uses Light (300) for display.** Marketing display headlines run at weight 300 with larger sizes — the inverse of the productive pattern. This creates the characteristic IBM marketing voice: large, light, confident. +- **IBM Plex Mono is mandatory for code and data.** Never use a generic monospace fallback when IBM Plex Mono is available. The typeface is designed to harmonize with Plex Sans at the same x-height. +- **Tracking is minimal.** Productive text uses 0-0.32px tracking. Expressive display uses -0.5px to 0. No large positive tracking — IBM is not a fashion brand. +- **Fluid sizing for expressive headings.** Display-03 scales from 36px at sm breakpoint to 64px at lg+. This is the only place Carbon uses fluid type. + +--- + +## 4. Component Stylings + +### Buttons + +**Primary (IBM Blue)** +```css +background: var(--color-primary); +color: var(--color-on-primary); +padding: 11px 16px; +height: 48px; +border-radius: 0px; +font-size: 14px; +font-weight: 400; +font-family: "IBM Plex Sans", sans-serif; +letter-spacing: 0; +border: none; +cursor: pointer; +transition: background 110ms ease; +``` +- Hover: `var(--color-primary-hover)` +- Active: `var(--color-primary-active)` +- Disabled: `background: var(--color-surface-strong); color: var(--color-muted-soft)` + +**Secondary (Outlined)** +```css +background: transparent; +color: var(--color-primary); +padding: 10px 15px; +height: 48px; +border-radius: 0px; +border: 1px solid var(--color-primary); +font-size: 14px; +font-weight: 400; +letter-spacing: 0; +``` +- Hover: `background: var(--color-primary-subtle)` + +**Tertiary (Ghost)** +```css +background: transparent; +color: var(--color-primary); +padding: 11px 16px; +height: 48px; +border-radius: 0px; +border: none; +font-size: 14px; +font-weight: 400; +``` +- Hover: `background: var(--color-surface)` on light; `background: var(--color-surface-elevated)` on dark + +**Danger** +```css +background: var(--color-error); +color: #FFFFFF; +padding: 11px 16px; +height: 48px; +border-radius: 0px; +font-size: 14px; +font-weight: 400; +border: none; +``` + +**Button rules:** No rounded corners — 0px border-radius is the Carbon standard. No icon-only buttons without a visible label. Buttons are 48px height (large) or 32px height (small variant). Weight is always 400 — buttons do not shout. + +### Navigation + +- **UI Shell (Top bar):** `height: 48px`, `background: var(--color-canvas)`. +- Left: IBM 8-bar logo mark. Center/left-aligned: side navigation trigger + page title. Right: actions, user avatar. +- Nav links: 14px / 400 / 0px tracking, `var(--color-ink)`. Active: `var(--color-primary)`. +- **Side Navigation:** Fixed left panel, `width: 256px` (expanded) / `64px` (collapsed, icon-only). `background: var(--color-canvas)`. Items: 14px / 400, `height: 32px` per item, with 4px left border indicator for active. +- No hamburger icon on desktop. Below 768px: side nav collapses to icon-only or becomes a sheet. +- Header may use `border-bottom: 1px solid var(--color-hairline)` for subtle separation. + +### Cards + +- **Tile:** `background: var(--color-surface-elevated)`, `border-radius: 0px`, `padding: 16px` or `24px`. No box-shadow in default state. +- **Clickable Tile:** Same as Tile + `border: 1px solid var(--color-hairline)`. Hover: `background: var(--color-surface)` on light. Active: `border-color: var(--color-primary)`. +- **Selectable Tile:** Selected state shows `border: 2px solid var(--color-primary)`. +- **Expandable Tile:** Expands vertically with chevron icon. Divider: 1px `var(--color-hairline)`. +- No border-radius on cards. No decorative shadows. Depth is communicated through background color differentiation. + +### Image Treatments + +- Photography is secondary to content. IBM product UI prioritizes data and text. +- When used: `width: 100%`, `object-fit: cover`. No rounded corners on images. +- Aspect ratios: 16:9 for hero, 3:2 for feature cards, 1:1 for avatars. +- No decorative image borders. No visible frame elements. +- Overlay gradient for text legibility only: `linear-gradient(to top, rgba(22, 22, 22, 0.8) 0%, transparent 60%)`. +- The 8-bar stripe motif may appear as a thin decorative band (4px per bar, 2px gap) at section boundaries — never as a background pattern or fill. + +### Data / Specs + +- Data tables are the centerpiece of IBM product UI. +- Table header: 12px / 600 / `var(--color-muted)` — uppercase, `letter-spacing: 0.32px`. +- Table cell: 14px / 400 / `var(--color-ink)` — the productive body-01 default. +- Row height: 48px (standard) / 32px (compact). +- Alternating row backgrounds: `var(--color-canvas)` and `var(--color-surface)`. +- Sortable columns show arrow icon in header. Filterable columns show filter icon. +- No decorative borders. Dividers: 1px `var(--color-hairline)` between rows only. +- Status indicators use the color families: green-50 for success, red-60 for error, yellow-30 for warning — as small dot icons or inline tags, never as row background fills. + +--- + +## 5. Layout Principles + +### Grid — The IBM 2x Grid + +Carbon's 2x Grid is a 16-column system at desktop with five breakpoints. Every dimension derives from the base 8px unit. + +| Breakpoint | Min Width | Columns | Gutter | Margin | +|------------|-----------|---------|--------|--------| +| sm | 320px | 4 | 16px | 16px | +| md | 672px | 8 | 16px | 16px | +| lg | 1056px | 16 | 24px | 24px | +| xlg | 1312px | 16 | 24px | 24px | +| max | 1584px | 16 | 32px | 32px | + +- **Max content width:** 1584px. Content is centered with margins absorbing remaining space. +- **16-column grid** at lg and above. 8-column at md. 4-column at sm. +- Column spans specified per breakpoint: `` for full-width content. +- Subgrid supported for nested layouts with alignment to parent columns. + +### Spacing System + +Base unit: **8px**. Every spacing token is a multiple of 8 or derived from the 2x/4x/8x progression. + +| Token | Value | Usage | +|-------|-------|-------| +| `--space-01` | 2px | Tightest internal gaps, icon-to-label | +| `--space-02` | 4px | Icon gaps, chip internal padding, inline spacing | +| `--space-03` | 8px | Base unit — component internal padding, tight element gaps | +| `--space-04` | 12px | Small component padding, form field internal | +| `--space-05` | 16px | Standard component padding, gutter at sm/md breakpoints | +| `--space-06` | 24px | Section internal gaps, gutter at lg/xlg, card padding | +| `--space-07` | 32px | Sub-section gaps, margin between components | +| `--space-08` | 40px | Section spacing, larger component margins | +| `--space-09` | 48px | Major section breaks, page-level vertical rhythm | +| `--space-10` | 64px | Section padding (marketing pages) | +| `--space-11` | 80px | Large section padding | +| `--space-12` | 96px | Maximum section padding — editorial/landing pages | +| `--space-13` | 160px | Rare — page-level hero spacing only | + +### Layout Spacing (Component-Level vs. Page-Level) + +Carbon defines two spacing scales: the general spacing scale above (for within components) and a layout spacing scale for between components and sections. The layout scale uses the same tokens but is applied to margin and padding at the section level. + +### Section Rhythm + +- Product pages use `48px` (space-09) vertical section rhythm — compact and information-dense. +- Marketing pages use `80-96px` (space-11/12) vertical section rhythm — more breathing room. +- Between heading and body: `16px` (space-05). +- Between body and CTA: `24px` (space-06). +- Edge padding (mobile): `16px` (space-05). +- Edge padding (desktop): `24-32px` (space-06/07). + +### Alignment + +- Left-aligned is the default. Enterprise content is not centered. +- Data tables: left-aligned labels, right-aligned numeric values. +- Forms: left-aligned labels above inputs (not inline labels). +- Headlines: left-aligned in product UI. Center-aligned only in marketing hero sections. +- Navigation: left-aligned. Side navigation is the primary navigation pattern for product UI. + +--- + +## 6. Depth & Elevation + +Carbon's depth system is flat by conviction, using background color shifts instead of shadows for surface hierarchy. Where shadows are used, they are subtle and functional — not decorative. + +### Surface Hierarchy + +| Level | Light Treatment | Dark Treatment | Use Case | +|-------|----------------|----------------|----------| +| 0 | `var(--color-canvas)` — no shadow, no border | `var(--color-canvas)` — no shadow, no border | Page background, top bar, footer | +| 1 | `var(--color-surface)` — background shift only | `var(--color-surface)` — background shift only | Container panels, inset sections, table row alternation | +| 2 | `var(--color-surface-elevated)` — background shift | `var(--color-surface-elevated)` — background shift | Cards, tiles, modals — elevated surfaces on inset backgrounds | +| 3 | 1px `var(--color-hairline)` border | 1px `var(--color-hairline)` border | Clickable tiles, input fields, data table cells | +| 4 | `box-shadow: 0 2px 6px rgba(0, 0, 0, 0.2)` | `box-shadow: 0 2px 6px rgba(0, 0, 0, 0.4)` | Dropdowns, popovers, tooltips — transient floating elements only | +| 5 | `box-shadow: 0 6px 16px rgba(0, 0, 0, 0.2)` | `box-shadow: 0 6px 16px rgba(0, 0, 0, 0.4)` | Modal dialogs — the only element that should cast a strong shadow | + +### Layer Sets (Carbon's Layering Tokens) + +Carbon defines layering tokens with numbered suffixes (-00, -01, -02, -03) that automatically adapt to the current theme: + +| Layer | Light Background | Dark Background | Use Case | +|-------|-----------------|-----------------|----------| +| layer-00 | `#FFFFFF` | `#161616` | Base page, top-level container | +| layer-01 | `#F4F4F4` | `#262626` | Raised section, inset panel | +| layer-02 | `#FFFFFF` | `#393939` | Card on inset panel | +| layer-03 | `#F4F4F4` | `#525252` | Nested element on card | + +### Overlay + +- Light overlay: `rgba(22, 22, 22, 0.5)` — for loading spinners and gentle content fade +- Dark overlay: `rgba(22, 22, 22, 0.85)` — for modal dialogs and focused interactions + +### Brand Signature Depth + +- **8-Bar Stripe Motif:** 8 horizontal bars, each 4px tall with 2px gap between. Used only as a section divider or as a thin decorative accent at the top of a page/section. Colors: all bars in `var(--color-primary)` (IBM Blue) for brand contexts, or `var(--color-ink)` for neutral contexts. Never as a fill pattern, never as a background texture, never animated. + +--- + +## 7. Do's and Don'ts + +**Do:** + +- Use IBM Blue (`#0F62FE`) as the single primary interactive color — it carries every CTA, link, and active element +- Set productive body at 14px — information density is a virtue in enterprise UI +- Use weight 400 (Regular) for most text — IBM trusts size and spacing for hierarchy, not weight +- Use the gray scale systematically — gray-100 for light text, gray-10 for dark text, gray-30 for borders, gray-80 for dark borders +- Let background color shifts communicate surface hierarchy instead of shadows +- Use IBM Plex Sans as the sole typeface — it is designed for this system +- Use the Carbon spacing tokens (space-01 through space-13) for all spacing decisions +- Use left-alignment as the default — enterprise content is not centered +- Support dark mode as a first-class citizen — Carbon provides g90 and g100 theme tokens for a reason +- Use the full 12-color family palette for data visualization charts and status indicators +- Use 0px border-radius for buttons and cards — the Carbon standard +- Use the 8-bar stripe motif as a controlled signature accent, not as wallpaper + +**Don't:** + +- Do not use blue-60 (`#0F62FE`) for decoration — it is reserved for interactive elements and primary actions only +- Do not add rounded corners to buttons, cards, or inputs — 0px radius is the Carbon identity +- Do not use decorative drop shadows on cards or static elements — shadows are for transient floating elements only +- Do not use weight 700 (Bold) for headings in productive UI — Carbon uses weight 400/600, not 700 +- Do not set body text at 16px in product UI — 14px is the enterprise standard; 16px is for marketing only +- Do not use pure black (`#000000`) for dark backgrounds — gray-100 (`#161616`) is the darkest Carbon surface +- Do not center-align body text, form labels, or table content — left-alignment is the enterprise default +- Do not use more than two type sets on a single page — choose Productive or Expressive, do not mix +- Do not use the color families (red, green, yellow, etc.) for decoration — they are for status and data visualization +- Do not use italic for emphasis in product UI — use weight 600 or size change instead +- Do not use negative letter-spacing on body text — 0 to 0.32px tracking only +- Do not use the 8-bar motif as a background pattern or fill — it is a section divider and accent only +- Do not design without considering data density — IBM surfaces are information-rich by default + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min Width | Columns | Gutter | Margin | Behavior | +|------|-----------|---------|--------|--------|----------| +| sm | 320px | 4 | 16px | 16px | Single column stacked. Side nav collapses to icon-only or sheet. Data tables scroll horizontally. Hero headline reduces to 36px (expressive). Productive headings unchanged. Footer 4-col to 1-col. | +| md | 672px | 8 | 16px | 16px | Two-column layouts possible. Side nav icon-only. Data tables remain scrollable. Hero headline 48px (expressive). Cards 2-up. | +| lg | 1056px | 16 | 24px | 24px | Full 16-column grid. Expanded side navigation (256px). Full data tables. Hero headline 64px (expressive). Cards 3-up or 4-up. | +| xlg | 1312px | 16 | 24px | 24px | Wider gutters. More sidebar content visible. Dashboard layouts reach full density. | +| max | 1584px | 16 | 32px | 32px | Maximum content width. Gutters and margins absorb remaining space. No content stretching beyond 1584px. | + +### Mobile-Specific Rules + +- Productive body text stays at 14px across all breakpoints — do not enlarge for mobile +- Data tables scroll horizontally on mobile with sticky first column — never restructure into card layouts +- Side navigation collapses to icon-only (64px) or becomes a full-screen sheet on mobile +- Touch targets: minimum 44x44px (WCAG AAA) +- Button height: 48px standard, 32px small — same as desktop +- Form inputs: 40px height (standard), with 48px touch target area via padding +- Expressive display type scales down: display-03 from 64px to 36px at sm breakpoint +- Productive headings do not scale — they are fixed sizes regardless of breakpoint +- Cards stack to single column at sm, 2-up at md +- Modal dialogs become full-screen sheets at sm breakpoint +- Pagination converts to "load more" pattern on mobile + +### Content Behavior + +- Side navigation width: 256px (expanded) / 64px (collapsed). Collapsed state shows icons only with tooltip on hover. +- Data tables: sticky header, sticky first column on mobile. Horizontal scroll with fade indicator. +- Forms: single-column layout on mobile. Two-column at md+. Three-column at lg+ for dense admin forms. +- Footer: 4-column at lg, 2-column at md, 1-column at sm with accordion sections. + +### Dark Mode Switching + +Carbon supports four themes. Use `prefers-color-scheme` media query for automatic switching; always provide a manual toggle in the UI Shell. All color tokens swap simultaneously through the theme layer — no partial theme application. The layer tokens (layer-00 through layer-03) automatically invert, so nested surface hierarchy is preserved in both modes. Transition between modes should be instant (no animation on color swap — enterprise users value predictability over delight). diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/index.json b/addons/officials/crew/designer/skills/design-system-picker/design-systems/index.json new file mode 100644 index 00000000..945ab166 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/index.json @@ -0,0 +1,167 @@ +[ + { + "id": "stripe", + "name": "Stripe", + "category": "fintech", + "keywords": ["紫色", "渐变", "优雅", "金融科技", "轻盈"], + "description": "紫色渐变 + weight-300 优雅排版 + 信任感金融风格", + "colorPrimary": "#635BFF", + "darkMode": true, + "bestFor": "SaaS 产品页、支付/金融科技落地页", + "file": "stripe.md" + }, + { + "id": "vercel", + "name": "Vercel", + "category": "devtools", + "keywords": ["黑白", "极简", "精密", "Geist字体", "开发者"], + "description": "黑白精密 + Geist 字体 + 开发者工具美学", + "colorPrimary": "#000000", + "darkMode": true, + "bestFor": "开发者工具、技术产品官网", + "file": "vercel.md" + }, + { + "id": "linear", + "name": "Linear", + "category": "productivity", + "keywords": ["极简", "紫色点缀", "精确", "工程师", "超简洁"], + "description": "超极简 + 紫色点缀 + 精确到像素的工程美学", + "colorPrimary": "#5E6AD2", + "darkMode": true, + "bestFor": "项目管理、效率工具、工程师导向产品", + "file": "linear.md" + }, + { + "id": "notion", + "name": "Notion", + "category": "productivity", + "keywords": ["暖色", "极简", "衬线标题", "柔光", "知识管理"], + "description": "温暖极简 + 衬线标题 + 柔和表面 + 知识工作者氛围", + "colorPrimary": "#000000", + "darkMode": false, + "bestFor": "知识管理、内容平台、文档型产品", + "file": "notion.md" + }, + { + "id": "apple", + "name": "Apple", + "category": "consumer", + "keywords": ["白色", "留白", "SF Pro", "电影感", "高级"], + "description": "极致留白 + SF Pro 字体 + 电影级影像 + 高级感", + "colorPrimary": "#0071E3", + "darkMode": true, + "bestFor": "消费电子、高端产品展示、品牌官网", + "file": "apple.md" + }, + { + "id": "supabase", + "name": "Supabase", + "category": "devtools", + "keywords": ["暗色", "翡翠绿", "代码优先", "数据库", "开发者"], + "description": "暗色翡翠绿主题 + 代码优先美学 + 开发者友好", + "colorPrimary": "#3ECF8E", + "darkMode": true, + "bestFor": "数据库/后端即服务、开源开发者工具", + "file": "supabase.md" + }, + { + "id": "shopify", + "name": "Shopify", + "category": "ecommerce", + "keywords": ["暗色", "霓虹绿", "超轻字体", "电商", "电影感"], + "description": "暗色电影感 + 霓虹绿点缀 + 超轻 display 字体", + "colorPrimary": "#008060", + "darkMode": true, + "bestFor": "电商平台、商业服务、SaaS 落地页", + "file": "shopify.md" + }, + { + "id": "figma", + "name": "Figma", + "category": "creative", + "keywords": ["多彩", "活泼", "专业", "设计工具", "品牌色丰富"], + "description": "多彩活泼但专业 + 设计工具品牌美学 + 丰富色彩系统", + "colorPrimary": "#F24E1E", + "darkMode": true, + "bestFor": "创意工具、设计平台、品牌展示", + "file": "figma.md" + }, + { + "id": "spotify", + "name": "Spotify", + "category": "media", + "keywords": ["绿色", "暗色", "大胆排版", "音乐", "媒体"], + "description": "鲜明绿 + 暗色基底 + 大胆排版 + 专辑封面驱动", + "colorPrimary": "#1DB954", + "darkMode": true, + "bestFor": "媒体/娱乐平台、音乐/视频产品", + "file": "spotify.md" + }, + { + "id": "tesla", + "name": "Tesla", + "category": "automotive", + "keywords": ["极简", "减法", "电影级", "电动汽车", "全屏摄影"], + "description": "极致减法 + 全屏电影级摄影 + Universal Sans + 零装饰", + "colorPrimary": "#000000", + "darkMode": true, + "bestFor": "汽车/硬件产品、极简品牌、全屏影像展示", + "file": "tesla.md" + }, + { + "id": "framer", + "name": "Framer", + "category": "creative", + "keywords": ["黑蓝", "动效优先", "设计感", "交互", "网站构建"], + "description": "大胆黑蓝 + 动效优先 + 设计感十足 + 网站构建器美学", + "colorPrimary": "#0055FF", + "darkMode": true, + "bestFor": "网站构建工具、创意代理、交互展示", + "file": "framer.md" + }, + { + "id": "airbnb", + "name": "Airbnb", + "category": "ecommerce", + "keywords": ["暖色", "珊瑚色", "摄影驱动", "圆角", "旅行"], + "description": "温暖珊瑚色 + 摄影驱动 + 圆角 UI + 旅行平台美学", + "colorPrimary": "#FF385C", + "darkMode": false, + "bestFor": "旅游/生活服务、社区平台、温暖亲和型产品", + "file": "airbnb.md" + }, + { + "id": "bmw", + "name": "BMW", + "category": "luxury", + "keywords": ["蓝色", "奢华", "精密", "汽车", "暗色", "金属感", "巴伐利亚"], + "description": "巴伐利亚蓝 + 暗色奢华 + 精密金属质感 + 百年汽车品牌美学", + "colorPrimary": "#0066B1", + "darkMode": true, + "bestFor": "奢侈品牌、高端产品展示、汽车/精密工业品牌官网", + "file": "bmw.md" + }, + { + "id": "ibm", + "name": "IBM", + "category": "enterprise", + "keywords": ["蓝色", "商业", "企业", "专业", "数据密集", "信任", "Carbon"], + "description": "企业蓝 + Carbon 设计系统 + IBM Plex 字体 + 数据密集型专业美学", + "colorPrimary": "#0F62FE", + "darkMode": true, + "bestFor": "企业级产品、B2B 服务、数据平台、商业/金融系统", + "file": "ibm.md" + }, + { + "id": "starbucks", + "name": "Starbucks", + "category": "lifestyle", + "keywords": ["绿色", "温暖", "社区", "咖啡", "自然", "圆角", "手工艺"], + "description": "Siren 绿 + 暖色社区氛围 + 自然质感 + 第三空间生活美学", + "colorPrimary": "#00704A", + "darkMode": false, + "bestFor": "生活品牌、社区平台、餐饮/零售、温暖亲和型产品", + "file": "starbucks.md" + } +] diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/linear.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/linear.md new file mode 100644 index 00000000..4290f342 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/linear.md @@ -0,0 +1,324 @@ +# Linear Design System + +## 1. Visual Theme & Atmosphere + +Linear is an engineer-focused productivity tool defined by **radical restraint**. Every pixel is intentional. The interface feels like a precision instrument: dark, quiet, and fast. Decoration is eliminated unless it serves function. The purple accent is used as a surgical highlight, never as decoration. Surfaces are flat and matte. Transitions are quick and purposeful. The overall impression is a tool that respects your attention and gets out of your way. + +**Atmosphere keywords**: dark, precise, quiet, instrument-grade, no-nonsense, surgical purple accents + +**Design personality**: The engineering lead who speaks in bullet points and ships on time. No small talk, no ornament, just clarity. + +--- + +## 2. Color Palette & Roles + +### Core Backgrounds + +| Semantic Name | Hex | Role | +|---|---|---| +| `bg-root` | `#0A0A0F` | Deepest background; canvas behind everything | +| `bg-surface-1` | `#111118` | Primary surface; panels, sidebar, main content area | +| `bg-surface-2` | `#181820` | Elevated surface; modals, dropdowns, popovers | +| `bg-surface-3` | `#1F1F2A` | Highest elevation; tooltips, notification toasts | +| `bg-hover` | `#25252F` | Hover state fill on interactive surfaces | + +### Text + +| Semantic Name | Hex | Role | +|---|---|---| +| `text-primary` | `#E8E8ED` | Primary body text, headings, active labels | +| `text-secondary` | `#8B8B96` | Secondary labels, descriptions, placeholder text | +| `text-tertiary` | `#5C5C66` | Disabled text, metadata, timestamps | +| `text-on-accent` | `#FFFFFF` | Text on accent-colored backgrounds | + +### Accent + +| Semantic Name | Hex | Role | +|---|---|---| +| `accent` | `#5E6AD2` | Primary accent; active states, links, focus rings, CTAs | +| `accent-hover` | `#6C75DB` | Hover state on accent elements | +| `accent-muted` | `#3D4480` | Muted accent; subtle badges, inline highlights | +| `accent-subtle` | `rgba(94, 106, 210, 0.12)` | Ghost accent; selected row backgrounds, hover tints | + +### Semantic Colors + +| Semantic Name | Hex | Role | +|---|---|---| +| `success` | `#4ADE80` | Completed states, confirmations | +| `warning` | `#FBBF24` | Caution states, in-progress | +| `error` | `#F87171` | Errors, destructive actions, validation failures | +| `info` | `#60A5FA` | Informational badges, neutral highlights | + +### Borders + +| Semantic Name | Hex | Role | +|---|---|---| +| `border-default` | `#25252F` | Default borders between sections and panels | +| `border-subtle` | `#1A1A24` | Very subtle dividers within a surface | +| `border-active` | `#5E6AD2` | Active/focused border on inputs and selections | + +--- + +## 3. Typography Rules + +### Font Stack + +- **Primary**: `-apple-system, BlinkMacSystemFont, "Segoe UI", Inter, sans-serif` +- **Monospace**: `"SF Mono", "Fira Code", "Cascadia Code", Menlo, monospace` +- **Display (hero only)**: `"Inter", -apple-system, sans-serif` at weight 600 + +### Type Scale + +| Element | Size | Weight | Line Height | Letter Spacing | Color | +|---|---|---|---|---|---| +| Display / Hero | `48px` | 600 | 1.1 | `-0.02em` | `text-primary` | +| H1 / Page Title | `24px` | 600 | 1.3 | `-0.01em` | `text-primary` | +| H2 / Section | `18px` | 600 | 1.4 | `0` | `text-primary` | +| H3 / Subsection | `14px` | 600 | 1.4 | `0` | `text-primary` | +| Body | `14px` | 400 | 1.5 | `0` | `text-primary` | +| Body Small | `13px` | 400 | 1.5 | `0` | `text-secondary` | +| Caption / Meta | `12px` | 400 | 1.4 | `0.01em` | `text-tertiary` | +| Label | `12px` | 500 | 1.3 | `0.02em` | `text-secondary` | +| Code | `13px` | 400 | 1.5 | `0` | `accent` | + +### Rules + +- Never use italic for UI text. Only for long-form content. +- Labels and metadata are always `text-secondary` or `text-tertiary`, never `text-primary`. +- Headings never have decorative underlines or borders. +- Text does not use gradients. Use solid color only. +- Maximum line width: `680px` for readable body text. + +--- + +## 4. Component Stylings + +### Buttons + +**Primary Button** +- Background: `accent` (`#5E6AD2`) +- Text: `text-on-accent` (`#FFFFFF`), 14px, weight 500 +- Padding: `6px 16px` +- Border-radius: `6px` +- Border: none +- Hover: `accent-hover` (`#6C75DB`), slight brightness shift +- Active: `#5258B8`, `translateY(1px)` (1px push) +- Focus: `2px` outline `accent`, `2px` offset +- Disabled: opacity `0.4`, no hover effect + +**Secondary Button** +- Background: `transparent` +- Text: `text-primary`, 14px, weight 500 +- Padding: `6px 16px` +- Border-radius: `6px` +- Border: `1px solid border-default` (`#25252F`) +- Hover: background `bg-hover` (`#25252F`) +- Active: background `bg-surface-2` (`#181820`) +- Focus: `2px` outline `accent`, `2px` offset + +**Ghost Button** +- Background: `transparent` +- Text: `text-secondary`, 14px, weight 400 +- Padding: `6px 12px` +- Border-radius: `6px` +- Border: none +- Hover: background `bg-hover`, text becomes `text-primary` +- Active: background `bg-surface-2` +- Focus: `2px` outline `accent`, `2px` offset + +**Danger Button** +- Same as secondary but text and border use `error` (`#F87171`) +- Hover: background `rgba(248, 113, 113, 0.08)` + +### Cards + +- Background: `bg-surface-1` (`#111118`) +- Border-radius: `8px` +- Border: `1px solid border-default` (`#25252F`) +- Padding: `20px` +- Hover: border-color `#2F2F3A`, very subtle +- No box-shadow in default state +- No decorative gradients on cards + +### Inputs + +**Text Input** +- Background: `bg-surface-1` (`#111118`) +- Border: `1px solid border-default` (`#25252F`) +- Border-radius: `6px` +- Padding: `8px 12px` +- Text: `text-primary`, 14px +- Placeholder: `text-tertiary` +- Focus: border `accent`, subtle `0 0 0 3px accent-subtle` ring +- Error: border `error`, error message in `error` color at 12px below input + +**Select / Dropdown** +- Same base as text input +- Dropdown panel: `bg-surface-2` (`#181820`), `8px` border-radius, `1px` border `border-default` +- Dropdown shadow: `0 8px 24px rgba(0, 0, 0, 0.4)` +- Selected item: `accent-subtle` background, `accent` text +- Hover item: `bg-hover` background + +### Navigation + +**Sidebar** +- Background: `bg-surface-1` (`#111118`) +- Width: `240px` (collapsible to `48px` icon-only mode) +- Border-right: `1px solid border-default` +- Item height: `32px` +- Item padding: `0 12px` +- Item border-radius: `6px` +- Item text: `text-secondary`, 13px, weight 400 +- Active item: background `accent-subtle`, text `accent`, weight 500 +- Hover item: background `bg-hover`, text `text-primary` +- Group labels: `text-tertiary`, 11px, weight 600, `0.04em` letter-spacing, uppercase + +**Top Bar** +- Background: `bg-surface-1` with `border-bottom: 1px solid border-default` +- Height: `44px` +- Breadcrumbs: `text-secondary`, 13px, separated by `/` in `text-tertiary` +- Actions aligned right + +### Badges / Tags + +- Border-radius: `9999px` (pill shape) +- Padding: `2px 8px` +- Font: 11px, weight 500 +- Variants: + - Default: `bg-hover` background, `text-secondary` text + - Accent: `accent-subtle` background, `accent` text + - Success: `rgba(74, 222, 128, 0.1)` background, `success` text + - Warning: `rgba(251, 191, 36, 0.1)` background, `warning` text + - Error: `rgba(248, 113, 113, 0.1)` background, `error` text + +### Toggles + +- Track: `bg-hover` off, `accent` on +- Knob: `text-primary`, `12px` circle +- Track size: `32px x 18px`, border-radius `9999px` +- Transition: `150ms ease` + +--- + +## 5. Layout Principles + +### Spacing Scale + +| Token | Value | Usage | +|---|---|---| +| `xs` | `4px` | Tight inline gaps, icon-to-label | +| `sm` | `8px` | Between related items | +| `md` | `12px` | Between form fields, list items | +| `lg` | `16px` | Section padding, card inner gaps | +| `xl` | `20px` | Card padding, section margins | +| `2xl` | `24px` | Major section separation | +| `3xl` | `32px` | Page-level vertical rhythm | +| `4xl` | `48px` | Hero-level spacing | +| `5xl` | `64px` | Maximum section gap | + +### Grid + +- Content max-width: `1200px` +- Sidebar + main layout: sidebar `240px` fixed, main fills remaining +- Gutter: `16px` between columns +- Card grid: 3 columns at >= 1200px, 2 at >= 768px, 1 below +- Grid column gap: `16px` +- Grid row gap: `16px` + +### Whitespace Rules + +- Sections are separated by `border-subtle` lines, not by increased whitespace alone. +- Vertical rhythm is tight: prefer `12px-16px` between items, not `24px-32px`. +- Horizontal padding in panels is always `16px` minimum. +- Content never touches viewport edges: minimum `16px` horizontal padding on mobile, `24px` on desktop. +- There is no decorative whitespace. Whitespace exists to group or separate, never to fill. + +### Alignment + +- All content is left-aligned. Center alignment only for modals and empty states. +- Labels sit above inputs (top-aligned), never to the left in forms. +- Icons are `16px` and vertically centered with adjacent text. + +--- + +## 6. Depth & Elevation + +Linear uses minimal shadows. Elevation is communicated primarily through background color shifts and border presence, not drop shadows. + +### Elevation Levels + +| Level | Background | Border | Shadow | Usage | +|---|---|---|---|---| +| 0 (base) | `bg-root` (`#0A0A0F`) | none | none | Canvas | +| 1 (surface) | `bg-surface-1` (`#111118`) | `1px border-default` | none | Panels, sidebar, cards | +| 2 (raised) | `bg-surface-2` (`#181820`) | `1px border-default` | `0 4px 16px rgba(0,0,0,0.3)` | Dropdowns, popovers | +| 3 (overlay) | `bg-surface-3` (`#1F1F2A`) | `1px border-default` | `0 8px 24px rgba(0,0,0,0.4)` | Modals, command palette | + +### Glow Effects (use sparingly) + +- Accent glow on focused inputs: `box-shadow: 0 0 0 3px rgba(94, 106, 210, 0.2)` +- CTA button glow (hero only): `box-shadow: 0 0 20px rgba(94, 106, 210, 0.3)` +- Never use glow on cards, badges, or navigation items. + +### Overlay + +- Modal backdrop: `rgba(0, 0, 0, 0.6)` with `backdrop-filter: blur(4px)` + +--- + +## 7. Do's and Don'ts + +### Do + +- Use `accent` sparingly. One accent element per viewport is often enough. +- Keep surfaces flat. Background color differences, not shadows, convey depth. +- Use monospace font for IDs, keys, and code snippets. +- Round numbers precisely. Border-radius is `6px` for inputs/buttons, `8px` for cards, `9999px` for pills only. +- Use `text-secondary` for descriptions and `text-tertiary` for metadata. This hierarchy is the primary way to guide attention. +- Animate with `150ms-200ms ease` for interactive state changes. Nothing slower. +- Use 1px borders. Never 2px or 3px except for focus rings. +- Prefer icon + text for actions. Icon-only only if the action is universally understood (e.g., close X, search magnifier). + +### Don't + +- Do not use gradients on text. Ever. +- Do not use decorative gradients on backgrounds of cards, panels, or sections. Subtle radial glows in hero sections are the only exception. +- Do not use rounded corners greater than `8px` on rectangular elements. No `16px` or `24px` radius cards. +- Do not add box-shadows to resting-state cards or list items. +- Do not use `accent` color for decorative elements like dividers or background fills (except `accent-subtle` for selection states). +- Do not use bold/weight-700 for body text. 600 is the maximum and only for headings and labels. +- Do not center-align paragraphs or form layouts. Left-align everything. +- Do not use emoji or decorative icons in navigation labels. +- Do not animate `width`, `height`, `top`, `left`, or `margin`. Use `transform` and `opacity` only. +- Do not use color alone to convey state. Pair with text labels or icons. + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min Width | Layout Behavior | +|---|---|---| +| `mobile` | `0` | Single column, sidebar hidden (hamburger), stacked cards | +| `tablet` | `768px` | Optional sidebar, 2-column card grid | +| `desktop` | `1024px` | Full sidebar visible, 2-column grid, side-by-side forms | +| `wide` | `1200px` | 3-column card grid, maximum content width enforced | + +### Adaptation Rules + +- **Sidebar**: Hidden below `1024px`, replaced by hamburger menu overlay. Overlay uses `bg-surface-2` with slide-in from left (`transform: translateX`, 200ms ease). +- **Navigation items**: Text + icon on desktop; icon-only below `768px` if sidebar is collapsed. +- **Cards**: Full-width below `768px`, 2-up at `768px+`, 3-up at `1200px+`. +- **Top bar**: Title truncates with ellipsis below `768px`. Breadcrumbs collapse to last segment + ellipsis. +- **Forms**: Single column always. Top-aligned labels. Full-width inputs on mobile, max `480px` on desktop. +- **Modals**: Full-screen on mobile (with safe-area padding), centered overlay on desktop. +- **Tables**: Convert to stacked card list on mobile. Each row becomes a card with label-value pairs. +- **Font sizes**: Reduce display/hero from `48px` to `32px` below `768px`. H1 from `24px` to `20px` below `768px`. Body text stays `14px` at all sizes. +- **Touch targets**: Minimum `36px` height for all interactive elements on mobile (up from `32px` on desktop). + +### Performance Notes + +- Use `will-change: transform` sparingly, only on elements actively animating. +- Prefer CSS transitions over JS-driven animations for state changes. +- Backdrop-filter (blur) should be used only for modal overlays; avoid on frequently toggled elements. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/notion.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/notion.md new file mode 100644 index 00000000..67374aac --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/notion.md @@ -0,0 +1,448 @@ +# Notion Design System + +## 1. Visual Theme & Atmosphere + +Notion embodies **warm minimalism** — the aesthetic of a well-lit study, not a cold lab. Surfaces feel like quality paper. Typography carries intellectual weight through serif headings while the body stays crisp and readable. Every element breathes; nothing is crowded. The overall impression is calm competence: a tool that respects your attention and gets out of the way. + +**Atmosphere keywords:** warm, calm, scholarly, approachable, paper-like, unhurried, trustworthy + +**Core visual traits:** +- Cream and warm whites dominate — never pure white (#FFF) on large surfaces +- Serif headings create a book-like cadence; sans-serif body keeps scanning fast +- Shadows are whispered, not shouted — surfaces lift gently, never float dramatically +- Icons and illustrations use thin strokes at 1.5px, never filled heavy shapes +- Color is used sparingly as semantic accent, never as decoration +- Interaction feedback is subtle: soft hovers, gentle transitions (150–200ms) + +--- + +## 2. Color Palette & Roles + +### Surface Colors + +| Name | Hex | Role | +|------|-----|------| +| bg-primary | #FFFFFF | Page canvas, main content area (used with warm surrounding context) | +| bg-warm | #FBFBFA | App shell background, sidebar backdrop | +| bg-cream | #F7F6F3 | Sidebar surface, panel backgrounds | +| bg-hover | #EBEBEA | Hover state for list items, menu rows | +| bg-active | #E3E3E2 | Active/pressed state | +| bg-selected | #2EAADC1A | Selected item highlight (blue at 10% opacity) | + +### Text Colors + +| Name | Hex | Role | +|------|-----|------| +| text-primary | #37352F | Body text, headings — the universal dark ink | +| text-secondary | #9B9A97 | Placeholder text, secondary labels, timestamps | +| text-tertiary | #C4C4C4 | Disabled text, dividers within text | +| text-link | #379ADC | Hyperlinks, navigational anchors | +| text-on-accent | #FFFFFF | Text on colored buttons/badges | + +### Accent / Semantic Colors + +| Name | Hex | Role | +|------|-----|------| +| accent-blue | #2EAADC | Primary actions, links, selection highlights | +| accent-blue-hover | #299FC7 | Blue hover state | +| accent-red | #EB5757 | Errors, destructive actions, warnings | +| accent-red-hover | #D14343 | Red hover state | +| accent-green | #0F7B6C | Success, confirmations, positive indicators | +| accent-yellow | #DFAB01 | Caution, pending states | +| accent-orange | #D9730D | Attention, secondary warnings | +| accent-pink | #AD1A72 | Tags, category markers | +| accent-purple | #6940A5 | Tags, category markers | + +### Border / Divider + +| Name | Hex | Role | +|------|-----|------| +| border-default | #E9E9E7 | Input borders, card outlines, table borders | +| border-hover | #D3D3D1 | Hover state on borders | +| divider | #E9E9E7 | Horizontal rules, section dividers | + +### Notion Color Tags (inline text/background pairs) + +| Tag | Text Hex | Background Hex | +|-----|----------|----------------| +| Blue | #2EAADC | #2EAADC1A | +| Red | #EB5757 | #EB57571A | +| Green | #0F7B6C | #0F7B6C1A | +| Yellow | #DFAB01 | #DFAB011A | +| Orange | #D9730D | #D9730D1A | +| Pink | #AD1A72 | #AD1A721A | +| Purple | #6940A5 | #6940A51A | +| Gray | #9B9A97 | #9B9A971A | +| Brown | #64473A | #64473A1A | + +--- + +## 3. Typography Rules + +### Font Stack + +- **Serif headings:** `"Noto Serif", "Ionicons", "Apple Color Emoji", Georgia, serif` +- **Sans-serif body:** `ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif` +- **Monospace code:** `"SFMono-Regular", Menlo, Consolas, "PT Mono", "Liberation Mono", Courier, monospace` + +### Hierarchy + +| Level | Font | Weight | Size | Line Height | Letter Spacing | +|-------|------|--------|------|-------------|----------------| +| H1 | Serif | 700 | 30px | 1.3 | -0.02em | +| H2 | Serif | 600 | 24px | 1.3 | -0.015em | +| H3 | Serif | 600 | 20px | 1.4 | -0.01em | +| H4 | Sans-serif | 600 | 16px | 1.5 | 0 | +| Body | Sans-serif | 400 | 16px | 1.6 | 0 | +| Body small | Sans-serif | 400 | 14px | 1.5 | 0 | +| Caption | Sans-serif | 400 | 12px | 1.5 | 0 | +| Code | Monospace | 400 | 14px | 1.6 | 0 | +| Button label | Sans-serif | 500 | 14px | 1.0 | 0 | +| Overline / label | Sans-serif | 500 | 12px | 1.3 | 0.02em | + +### Key Typography Rules + +1. **Serif is for headings only (H1–H3).** H4 and below use sans-serif. This creates the signature "book chapter" feel at the top of the hierarchy. +2. **Never use italic serif for emphasis in headings.** Use weight changes instead (600 → 700). +3. **Body text stays at 16px minimum.** 14px for secondary text, 12px only for captions and labels. +4. **Code blocks use 14px monospace** on a slightly tinted background (#F7F6F3). +5. **Line height is generous** — 1.6 for body, 1.3 for headings — mirroring print book readability. +6. **Text color is always #37352F** (warm near-black), never pure #000000. + +--- + +## 4. Component Stylings + +### Buttons + +**Primary button** +``` +background: #2EAADC +color: #FFFFFF +border-radius: 4px +padding: 6px 12px +font: 500 14px/1 sans-serif +height: 32px +transition: background 120ms ease +``` +- Hover: background #299FC7 +- Active: background #2491B5, translateY(0.5px) +- Disabled: opacity 0.5, cursor not-allowed + +**Secondary button** +``` +background: #FFFFFF +color: #37352F +border: 1px solid #E9E9E7 +border-radius: 4px +padding: 6px 12px +font: 500 14px/1 sans-serif +height: 32px +``` +- Hover: background #FBFBFA, border #D3D3D1 +- Active: background #F7F6F3 + +**Destructive button** +``` +background: #EB5757 +color: #FFFFFF +border-radius: 4px +padding: 6px 12px +font: 500 14px/1 sans-serif +height: 32px +``` +- Hover: background #D14343 + +**Ghost / Text button** +``` +background: transparent +color: #37352F +border: none +border-radius: 4px +padding: 4px 8px +font: 500 14px/1 sans-serif +``` +- Hover: background #EBEBEA + +**Icon button (32x32)** +``` +background: transparent +border: none +border-radius: 4px +width: 32px +height: 32px +display: inline-flex +align-items: center +justify-content: center +``` +- Hover: background #EBEBEA +- Active: background #E3E3E2 + +### Cards + +**Page card / Content block** +``` +background: #FFFFFF +border: 1px solid #E9E9E7 +border-radius: 8px +padding: 16px +``` +- Hover: subtle border darkening to #D3D3D1 +- No box-shadow in default state — cards sit flat on the surface +- Cover images: 16:9 ratio, border-radius 4px on the image inside the card + +**Sidebar card / Nested panel** +``` +background: #F7F6F3 +border: none +border-radius: 6px +padding: 8px 10px +``` + +### Inputs / Text Fields + +**Standard input** +``` +background: #FFFFFF +border: 1px solid #E9E9E7 +border-radius: 4px +padding: 8px 10px +font: 400 16px/1.5 sans-serif +color: #37352F +height: 32px +``` +- Focus: border #2EAADC, box-shadow 0 0 0 2px #2EAADC33 +- Placeholder: color #9B9A97 +- Error: border #EB5757, box-shadow 0 0 0 2px #EB575733 +- Disabled: background #F7F6F3, color #9B9A97 + +**Search input** +``` +background: #F7F6F3 +border: 1px solid transparent +border-radius: 4px +padding: 8px 10px 8px 36px (space for search icon) +font: 400 16px/1.5 sans-serif +color: #37352F +``` +- Focus: background #FFFFFF, border #E9E9E7, box-shadow 0 0 0 2px #2EAADC33 + +**Multi-line / Textarea** +- Same as standard input but min-height 80px, vertical resize only +- Line height 1.6 + +### Navigation / Sidebar + +**Sidebar panel** +``` +background: #F7F6F3 +width: 240px (collapsible) +padding: 10px 6px +``` + +**Sidebar item (page link)** +``` +padding: 4px 8px +border-radius: 4px +font: 400 14px/1.4 sans-serif +color: #37352F +``` +- Hover: background #EBEBEA +- Active: background #2EAADC1A, color #37352F +- Icon + label: 20px icon left, 8px gap to label + +**Breadcrumbs** +``` +font: 400 14px/1 sans-serif +color: #9B9A97 +separator: "/" with 4px margin each side +``` +- Current page: color #37352F, font-weight 500 + +### Toggles & Checkboxes + +**Toggle** +- Track: 36x20px, border-radius 10px +- Off: background #E9E9E7 +- On: background #2EAADC +- Thumb: 16x16px circle, background #FFFFFF, translateY offset +- Transition: 150ms ease + +**Checkbox** +- 16x16px, border-radius 3px +- Unchecked: border 2px solid #9B9A97, background transparent +- Checked: background #2EAADC, border #2EAADC, white checkmark +- Transition: 120ms ease + +### Tags / Badges + +``` +padding: 2px 8px +border-radius: 3px +font: 500 12px/1.3 sans-serif +``` +- Uses the Notion color tag pairs (text color on matching 10% opacity background) +- Example: Blue tag = color #2EAADC, background #2EAADC1A + +### Tooltips + +``` +background: #37352F +color: #FFFFFF +padding: 4px 8px +border-radius: 4px +font: 400 12px/1.3 sans-serif +max-width: 240px +``` +- Appears 4px below trigger element +- Fade in 100ms ease + +--- + +## 5. Layout Principles + +### Spacing Scale + +| Token | Value | Usage | +|-------|-------|-------| +| xs | 4px | Inline gaps, icon-to-label | +| sm | 8px | Compact list item padding, badge padding | +| md | 12px | Button padding (horizontal), form field gaps | +| lg | 16px | Card padding, section inner padding | +| xl | 24px | Between related sections | +| 2xl | 32px | Between distinct content blocks | +| 3xl | 48px | Page section separators | +| 4xl | 64px | Top-level page sections | + +### Grid & Container + +- **Content width:** 708px (Notion's standard page width for readable content) +- **Wide content:** 936px (for tables, kanban boards, media) +- **Full width:** 100% minus sidebar (for databases, galleries) +- **Sidebar:** 240px default, 48px collapsed (icons only) +- **Column gap in multi-column:** 24px +- **No explicit CSS grid for page layout** — content flows vertically with horizontal blocks + +### Whitespace Philosophy + +1. **Generous top margins on headings.** H1: 32px top margin. H2: 24px. H3: 16px. This creates a clear visual rhythm. +2. **List items breathe.** Minimum 4px vertical padding per item. Nested items indent 24px. +3. **Content never touches edges.** Minimum 16px horizontal padding inside any container. +4. **Section breaks use space, not lines.** Prefer 48–64px vertical spacing between sections over visible dividers. Use dividers (#E9E9E7) only when semantic separation is needed within a tight space. +5. **Inline elements get breathing room.** 4px minimum gap between icon and label, 8px between adjacent actions. + +### Alignment + +- Content is left-aligned by default. Center alignment only for hero statements or empty states. +- Headings are left-aligned, never centered in body content. +- Labels sit above inputs (stacked), not beside them, to maintain vertical rhythm. + +--- + +## 6. Depth & Elevation + +Notion avoids dramatic depth. Surfaces feel like sheets of paper on a desk — some stacked, but all resting flat. + +### Shadow Levels + +| Level | Shadow | Usage | +|-------|--------|-------| +| Level 0 | none | Cards on page, sidebar items | +| Level 1 | 0 1px 2px rgba(0,0,0,0.06) | Hovered cards, raised panels | +| Level 2 | 0 2px 8px rgba(0,0,0,0.08) | Dropdowns, popovers, tooltips | +| Level 3 | 0 4px 16px rgba(0,0,0,0.1) | Modals, dialogs | +| Level 4 | 0 8px 32px rgba(0,0,0,0.12) | Full-screen overlays, command palette | + +### Elevation Rules + +1. **Default state: no shadow.** Cards and content blocks sit flush on the background. +2. **Borders do the work shadows usually do.** 1px #E9E9E7 borders delineate boundaries without implying elevation. +3. **Shadows appear on interaction.** A card might gain Level 1 shadow on hover, a dropdown gets Level 2 on open. +4. **Background tint implies depth, not shadow.** The sidebar is #F7F6F3 (cream), the content area is #FFFFFF. This subtle warmth shift creates perceived depth without rendering shadows. +5. **Overlays use opacity, not shadow.** Modal backdrops: rgba(0,0,0,0.4) with no blur. This keeps things warm and accessible. +6. **Never use inset shadows.** Notion surfaces are always convex, never concave. + +### Surface Hierarchy (bottom to top) + +1. `#F7F6F3` — Sidebar / background panels +2. `#FFFFFF` — Main content area / canvas +3. `#FFFFFF` + Level 1 border — Cards on the canvas +4. `#FFFFFF` + Level 2 shadow — Dropdowns, popovers +5. `#FFFFFF` + Level 3 shadow — Modals +6. `#37352F` at 85% opacity — Full overlay backdrop + +--- + +## 7. Do's and Don'ts + +### Do + +- Use serif for H1–H3 headings; it is the single most distinctive Notion signature +- Keep backgrounds warm — use #FBFBFA or #F7F6F3 instead of pure #FFFFFF for shells +- Use color tags (10% opacity backgrounds) for inline categorization — they feel native to the writing surface +- Default to no shadows; add them only when an element needs to float (dropdowns, modals) +- Use generous line height (1.6 body, 1.3 headings) for readability +- Keep borders at 1px #E9E9E7 — they should suggest boundaries, not draw attention +- Use 4px border-radius for inputs/buttons, 6–8px for cards, 3px for tags — subtle rounding only +- Preserve ample whitespace above headings (32px, 24px, 16px for H1/H2/H3) +- Use icon buttons at 32x32px with hover backgrounds — not outlined or shadowed buttons +- Animate at 120–200ms with ease timing — fast enough to feel responsive, slow enough to perceive + +### Don't + +- Don't use pure #000000 for text — always #37352F (warm near-black) +- Don't apply bold colors to large surfaces — accent colors are for small highlights, tags, and interactive elements +- Don't use gradients anywhere — Notion surfaces are flat and solid +- Don't use serif for body text or UI labels — it belongs in headings only +- Don't add box-shadows to resting-state cards — borders are sufficient +- Don't use rounded-full (pill) shapes — maximum border-radius is 8px +- Don't use heavy/filled icons — prefer outlined/thin stroke style at 1.5px +- Don't use dark mode as primary — Notion is fundamentally a light, warm surface product +- Don't use bright saturated backgrounds — all backgrounds are neutral or pastel (10% tint) +- Don't add visible grid lines to layouts — use spacing and alignment instead +- Don't center-align body text or headings in content areas — left alignment is the default rhythm +- Don't use animations longer than 300ms — the interface should feel immediate and paper-like + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Width | Layout Behavior | +|------|-------|-----------------| +| Mobile | < 640px | Single column, sidebar hidden (hamburger toggle), stacked cards | +| Tablet | 640–1024px | Sidebar collapsed to 48px icon rail, content at 640px max-width | +| Desktop | 1024–1440px | Sidebar at 240px, content at 708px max-width centered | +| Wide | > 1440px | Same as Desktop, extra whitespace distributed symmetrically | + +### Mobile Adaptations (< 640px) + +- **Sidebar:** Hidden off-screen, accessed via hamburger button (top-left). Slides in as overlay with Level 2 shadow. +- **Content width:** Full width minus 16px horizontal padding on each side. +- **Headings:** Reduce by 4px. H1: 26px, H2: 20px, H3: 18px. Maintain serif. +- **Cards:** Full-width, stacked vertically with 16px gap between them. No multi-column layouts. +- **Navigation:** Bottom tab bar for primary navigation (replacing sidebar), top bar for breadcrumbs and actions. +- **Tables:** Horizontal scroll with sticky first column. Or convert to list/card view. +- **Buttons:** Minimum touch target 44x44px. Add padding to reach minimum — don't scale font up. +- **Inputs:** Full width, height 44px (increased from 32px for touch). +- **Spacing:** Reduce 3xl/4xl to xl/2xl (48/64px → 24/32px). Maintain xs/sm/md unchanged. + +### Tablet Adaptations (640–1024px) + +- **Sidebar:** Collapsed to 48px icon rail. Tap icon to expand full sidebar as overlay. +- **Content width:** 640px max, centered. +- **Multi-column:** Maximum 2 columns. 3+ columns collapse to 2 or 1. +- **Cards:** 2-column grid for gallery/grid views. + +### Desktop (1024px+) + +- Standard layout as described in Section 5. +- Multi-column content allowed at wide width (936px). +- Sidebar fully expanded by default. + +### Responsive Transitions + +- Sidebar collapse/expand: 200ms ease with width transition +- Content reflow: No animation needed — content should reflow instantly +- Breakpoint changes: Layout shifts at breakpoints with no animation (not fluid) to maintain Notion's crisp, paper-like feel diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/shopify.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/shopify.md new file mode 100644 index 00000000..735a9cfa --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/shopify.md @@ -0,0 +1,451 @@ +# Shopify Design System + +## 1. Visual Theme & Atmosphere + +Shopify's design language is **dark-first and cinematic**. The interface feels like a control center for commerce: deep dark surfaces, razor-sharp typography at ultra-light weights, and a neon green accent that cuts through like a terminal cursor. Photography is dramatic and moody. Products and merchants are cast in high-contrast, studio-lit scenes. The overall impression is a platform that means business -- modern, powerful, and unapologetically commercial. + +**Core qualities:** +- Dark surfaces dominate; light mode exists but feels secondary +- Ultra-light font weights (300, even 200) for display headlines -- airy, not heavy +- Neon green (#008060) as surgical accent; never decorative, always functional +- Cinematic photography with deep shadows and dramatic lighting +- Generous negative space on dark surfaces creates depth without elevation hacks +- Surfaces are matte and flat; depth comes from background color layering, not shadows +- Micro-interactions are quick and responsive (150ms-200ms); the platform feels fast +- E-commerce data density is handled through clear hierarchy, not visual noise + +**Atmosphere keywords:** dark-commerce, neon-green, cinematic, ultra-light type, platform-power, merchant-centric, terminal-sharp + +**Design personality:** The commerce platform that treats your store like a mission-critical dashboard. Confident, efficient, with just enough visual drama to feel premium. + +--- + +## 2. Color Palette & Roles + +### Dark Mode (Primary) + +| Token | Hex | Role | +|-------|-----|------| +| `--color-bg` | `#0B1215` | Deepest background; canvas behind all surfaces | +| `--color-surface` | `#111820` | Primary surface; panels, sidebar, main content | +| `--color-surface-elevated` | `#1A232B` | Elevated surface; cards, dropdowns | +| `--color-surface-overlay` | `#222D38` | Overlay surface; modals, popovers | +| `--color-surface-hover` | `#1E2A35` | Hover state fill on interactive surfaces | +| `--color-text-primary` | `#E3E8EB` | Headlines, body copy, primary labels | +| `--color-text-secondary` | `#8B9DA7` | Descriptions, captions, secondary info | +| `--color-text-tertiary` | `#5C6F7A` | Disabled text, placeholders, metadata | +| `--color-text-inverse` | `#FFFFFF` | Text on accent backgrounds | +| `--color-accent` | `#008060` | Primary accent; CTAs, active states, links, focus rings | +| `--color-accent-hover` | `#009A73` | Accent hover state | +| `--color-accent-active` | `#006B4F` | Accent pressed/active state | +| `--color-accent-subtle` | `rgba(0, 128, 96, 0.12)` | Ghost accent; selected rows, hover tints | +| `--color-accent-glow` | `rgba(0, 128, 96, 0.25)` | Glow ring for focus states | +| `--color-separator` | `#1E2A35` | Borders between sections and panels | +| `--color-separator-subtle` | `#162029` | Hairline dividers within a surface | +| `--color-success` | `#008060` | Completed states (shares accent green) | +| `--color-success-surface` | `rgba(0, 128, 96, 0.10)` | Success background tints | +| `--color-warning` | `#FFC453` | Caution, pending, attention required | +| `--color-warning-surface` | `rgba(255, 196, 83, 0.10)` | Warning background tints | +| `--color-error` | `#E43E3E` | Errors, destructive actions, validation failures | +| `--color-error-surface` | `rgba(228, 62, 62, 0.10)` | Error background tints | +| `--color-info` | `#5BA4CF` | Informational badges, neutral highlights | +| `--color-info-surface` | `rgba(91, 164, 207, 0.10)` | Info background tints | + +### Light Mode + +| Token | Hex | Role | +|-------|-----|------| +| `--color-bg` | `#F6F7F8` | Page background | +| `--color-surface` | `#FFFFFF` | Card / section fill | +| `--color-surface-elevated` | `#FFFFFF` | Elevated cards, modals | +| `--color-surface-hover` | `#F1F2F3` | Hover state fill | +| `--color-text-primary` | `#1A1F25` | Headlines, body copy | +| `--color-text-secondary` | `#637381` | Captions, descriptions | +| `--color-text-tertiary` | `#919BA3` | Disabled, placeholders | +| `--color-text-inverse` | `#FFFFFF` | Text on accent backgrounds | +| `--color-accent` | `#008060` | Primary accent (same as dark) | +| `--color-accent-hover` | `#006B4F` | Accent hover (darker on light bg) | +| `--color-accent-active` | `#005A42` | Accent pressed | +| `--color-accent-subtle` | `rgba(0, 128, 96, 0.08)` | Ghost accent tint | +| `--color-separator` | `#E1E3E5` | Borders, dividers | +| `--color-separator-subtle` | `#F1F2F3` | Hairline separators | +| `--color-success` | `#008060` | Same as accent | +| `--color-warning` | `#D4860A` | Darker warning for light bg | +| `--color-error` | `#D72B2B` | Darker error for light bg | +| `--color-info` | `#2E6EA6` | Darker info for light bg | + +### Brand Extension Colors + +| Name | Hex | Usage | +|------|-----|-------| +| Shopify Green | `#008060` | Primary brand; identical to accent | +| Shopify Green Light | `#95D7B2` | Decorative only; illustrations, data viz | +| Shopify Green Dark | `#004E3A` | Pressed states, deep emphasis | +| Polar Night 1 | `#0B1215` | Darkest dark surface | +| Polar Night 2 | `#111820` | Standard dark surface | +| Snow Storm | `#E3E8EB` | Lightest text on dark | + +--- + +## 3. Typography Rules + +**Font stack:** `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` + +**Display font (hero only):** Same stack at weight 200-300 for that ultra-light, cinematic feel. + +**Monospace:** `"SF Mono", "Fira Code", Menlo, Consolas, monospace` + +### Type Scale + +| Token | Size | Weight | Tracking | Line-height | Usage | +|-------|------|--------|----------|-------------|-------| +| `--text-hero` | `clamp(2.75rem, 5vw + 0.5rem, 4.5rem)` | 300 (light) | -0.025em | 1.1 | Hero headlines, splash sections | +| `--text-headline-lg` | `clamp(2rem, 3vw + 0.5rem, 2.5rem)` | 300 | -0.02em | 1.15 | Section headlines, feature titles | +| `--text-headline` | `clamp(1.5rem, 1.5vw + 0.5rem, 1.75rem)` | 400 | -0.015em | 1.2 | Sub-section headlines | +| `--text-title` | `1.125rem` (18px) | 500 | -0.01em | 1.3 | Card titles, modal headers | +| `--text-subtitle` | `1rem` (16px) | 500 | 0 | 1.4 | Subtitles, emphasis body | +| `--text-body` | `0.875rem` (14px) | 400 | 0 | 1.5 | Default body text | +| `--text-body-sm` | `0.8125rem` (13px) | 400 | 0.01em | 1.5 | Compact body, table cells | +| `--text-caption` | `0.75rem` (12px) | 400 | 0.02em | 1.4 | Captions, metadata, timestamps | +| `--text-overline` | `0.6875rem` (11px) | 600 | 0.06em | 1.3 | Labels, overlines (UPPERCASE) | +| `--text-data` | `1.5rem` (24px) | 500 | -0.01em | 1.2 | Dashboard metrics, big numbers | + +### Rules + +- Hero and headline text uses weight 300 (light) for the signature airy look. Never use 200 except on oversized display type (64px+). +- Body text is always 400 regular. Never use 300 for body copy -- it becomes illegible at small sizes. +- Tracking tightens progressively as size increases (hero: -0.025em, body: 0). +- Maximum measure (line width): `640px` for readable body text. +- Dashboard metric numbers use `--text-data` with tabular-nums font-feature for aligned columns. +- Labels and overlines are always uppercase with wide tracking. +- Never use italic for UI text. Reserve italic for long-form editorial content only. + +--- + +## 4. Component Stylings + +### Buttons + +**Primary (Accent Green)** +```css +background: var(--color-accent); +color: var(--color-text-inverse); +padding: 8px 20px; +border-radius: 8px; +font-size: 0.875rem; +font-weight: 500; +letter-spacing: 0; +border: none; +cursor: pointer; +transition: background 150ms ease, box-shadow 150ms ease; +``` +- Hover: `var(--color-accent-hover)` +- Active: `var(--color-accent-active)` + `scale(0.98)` +- Focus: `box-shadow: 0 0 0 2px var(--color-accent-glow)` +- Disabled: `opacity: 0.4`, no pointer events +- Loading: text replaced by 16px spinner in `var(--color-text-inverse)` + +**Secondary (Outlined)** +```css +background: transparent; +color: var(--color-text-primary); +padding: 8px 20px; +border-radius: 8px; +font-size: 0.875rem; +font-weight: 500; +border: 1px solid var(--color-separator); +``` +- Hover: `background: var(--color-surface-hover)`, border lightens +- Active: `background: var(--color-surface-elevated)` +- Focus: `box-shadow: 0 0 0 2px var(--color-accent-glow)` + +**Tertiary (Ghost)** +```css +background: transparent; +color: var(--color-text-secondary); +padding: 8px 12px; +border-radius: 8px; +font-size: 0.875rem; +font-weight: 400; +border: none; +``` +- Hover: `background: var(--color-surface-hover)`, text becomes `--color-text-primary` + +**Destructive** +```css +background: var(--color-error); +color: var(--color-text-inverse); +/* same shape/size as primary */ +``` +- Hover: `#C93232` +- Secondary destructive: outline style with `--color-error` text and border + +**Large CTA (Hero)** +```css +padding: 12px 28px; +font-size: 1rem; +font-weight: 500; +border-radius: 10px; +``` + +**Icon Button** +- `32px x 32px` square, `border-radius: 8px` +- Icon: `16px`, color `--color-text-secondary` +- Hover: `background: var(--color-surface-hover)` + +### Cards + +```css +background: var(--color-surface-elevated); +border-radius: 12px; +padding: 20px; +border: 1px solid var(--color-separator); +box-shadow: none; +``` +- Hover (interactive cards): `border-color: var(--color-accent)` at 30% opacity +- Selected: `border-color: var(--color-accent)`, `background: var(--color-accent-subtle)` +- Metric cards: large number (`--text-data`) top-left, label (`--text-caption`) below, sparkline or delta right +- Product cards: image top with `border-radius: 8px`, title in `--text-body` weight 500, price in `--text-body-sm` `--color-text-secondary` +- No box-shadow on default state cards + +### Inputs + +**Text Input** +```css +background: var(--color-surface); +border: 1px solid var(--color-separator); +border-radius: 8px; +padding: 8px 12px; +font-size: 0.875rem; +color: var(--color-text-primary); +outline: none; +transition: border-color 150ms ease, box-shadow 150ms ease; +``` +- Focus: `border-color: var(--color-accent)` + `box-shadow: 0 0 0 2px var(--color-accent-glow)` +- Placeholder: `var(--color-text-tertiary)` +- Error: `border-color: var(--color-error)`, error message in `--color-error` at 12px below +- Disabled: `opacity: 0.5`, `cursor: not-allowed` +- Prefix/suffix slots: icon or text in `--color-text-tertiary` inside input with `border-left`/`border-right` separator + +**Search Input** +```css +border-radius: 980px; /* pill shape */ +padding: 8px 12px 8px 36px; /* room for magnifier icon */ +``` + +**Select / Dropdown** +- Same base styling as text input +- Dropdown panel: `--color-surface-overlay` background, `8px` border-radius, `1px` border `--color-separator` +- Dropdown shadow: `0 8px 24px rgba(0, 0, 0, 0.4)` +- Selected item: `--color-accent-subtle` background, `--color-accent` text +- Hover item: `--color-surface-hover` background + +### Navigation + +**Sidebar** +- Background: `--color-surface` (`#111820`) +- Width: `240px` (collapsible to `56px` icon-only mode) +- Border-right: `1px solid var(--color-separator)` +- Item height: `36px` +- Item padding: `0 12px` +- Item border-radius: `8px` +- Item text: `--color-text-secondary`, 14px, weight 400 +- Active item: background `--color-accent-subtle`, text `--color-accent`, weight 500 +- Hover item: background `--color-surface-hover`, text `--color-text-primary` +- Group labels: `--color-text-tertiary`, 11px, weight 600, `0.06em` letter-spacing, uppercase +- Shopify logo: 28px mark in `--color-accent` at top, app name in `--text-subtitle` weight 500 + +**Top Bar / Command Bar** +- Background: `--color-surface` with `border-bottom: 1px solid var(--color-separator)` +- Height: `56px` +- Search bar centered: pill-shaped input, `--color-text-tertiary` placeholder "Search your store..." +- Breadcrumbs: `--color-text-secondary`, 14px, separated by chevron in `--color-text-tertiary` +- Action buttons aligned right + +### Badges / Status Tags + +- Border-radius: `980px` (pill shape) +- Padding: `2px 8px` +- Font: 12px, weight 500 +- Variants: + - Default: `--color-surface-hover` background, `--color-text-secondary` text + - Success: `--color-success-surface` background, `--color-success` text + - Warning: `--color-warning-surface` background, `--color-warning` text + - Error: `--color-error-surface` background, `--color-error` text + - Info: `--color-info-surface` background, `--color-info` text + +### Data Table + +- Header row: `--color-surface-hover` background, `--text-overline` style labels, sticky on scroll +- Row height: `48px` +- Cell text: `--text-body-sm` (13px) +- Row hover: `--color-surface-hover` background +- Row selected: `--color-accent-subtle` background +- Zebra striping: not used; hover state is sufficient +- Column borders: none; horizontal separators only (`1px solid var(--color-separator-subtle)`) + +--- + +## 5. Layout Principles + +### Spacing Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `--space-1` | `4px` | Tight inline gaps, icon-to-label | +| `--space-2` | `8px` | Between related items, compact padding | +| `--space-3` | `12px` | Between form fields, list items | +| `--space-4` | `16px` | Section padding, card inner gaps | +| `--space-5` | `20px` | Card padding, comfortable spacing | +| `--space-6` | `24px` | Major section separation | +| `--space-8` | `32px` | Page-level vertical rhythm | +| `--space-10` | `40px` | Section dividers | +| `--space-12` | `48px` | Hero-level spacing | +| `--space-16` | `64px` | Maximum section gap | + +### Grid + +- Content max-width: `1200px` +- Sidebar + main layout: sidebar `240px` fixed, main fills remaining +- Admin content max-width within main: `960px` for readability +- Gutter: `16px` between columns +- Card grid: 3 columns at >= 1200px, 2 at >= 768px, 1 below +- Grid gap: `16px` + +### Whitespace Philosophy + +- The dark surface does the work of separation; excessive whitespace is unnecessary +- Section padding: `32px` to `48px` vertical (compact efficiency over luxury breathing) +- Between headline and body: `8px` to `12px` (tight rhythm) +- Between body and CTA: `16px` to `20px` +- Between sibling cards: `16px` +- Edge padding (mobile): `16px` +- Edge padding (desktop): `24px` to `32px` +- Content never touches viewport edges + +### Content Rhythm + +1. **Hero section**: Dark cinematic background with product photography or platform illustration. Ultra-light headline (weight 300) + short subtitle + green CTA. Content left-aligned, not centered. +2. **Feature sections**: Stacked or alternating layout. Headline at `--text-headline` + body + optional illustration. Compact vertical rhythm. +3. **Dashboard sections**: Metric cards in a row, then a data table or chart. Dense but legible. +4. **CTA section**: Often on slightly lighter dark surface. Bold headline, single green button. + +--- + +## 6. Depth & Elevation + +Shopify conveys depth through **background color layering**, not shadows. The darkest surface is the canvas; each step up in elevation is a slightly lighter dark. + +### Elevation Levels (Dark Mode) + +| Level | Background | Border | Shadow | Usage | +|-------|------------|--------|--------|-------| +| 0 (canvas) | `#0B1215` | none | none | Root background | +| 1 (surface) | `#111820` | `1px solid #1E2A35` | none | Panels, sidebar, main content | +| 2 (raised) | `#1A232B` | `1px solid #1E2A35` | none | Cards, list items, sections | +| 3 (overlay) | `#222D38` | `1px solid #2A3845` | `0 4px 16px rgba(0,0,0,0.3)` | Dropdowns, popovers | +| 4 (floating) | `#2A3845` | `1px solid #334555` | `0 8px 32px rgba(0,0,0,0.4)` | Modals, command palette | + +### Accent Glow + +The neon green accent produces a subtle glow when focused or highlighted, reinforcing the "terminal cursor" feel: + +- Focus ring: `box-shadow: 0 0 0 2px rgba(0, 128, 96, 0.25)` +- Active CTA glow (hero only): `box-shadow: 0 0 20px rgba(0, 128, 96, 0.2)` +- Never use glow on resting-state cards, badges, or navigation items + +### Overlay + +- Modal backdrop: `rgba(0, 0, 0, 0.6)` with `backdrop-filter: blur(4px)` +- Toast notifications: surface-level 3, fixed at bottom-right, stacked with `8px` gap + +### Border Radius Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `--radius-sm` | `4px` | Small badges, inline tags | +| `--radius-md` | `8px` | Buttons, inputs, nav items | +| `--radius-lg` | `12px` | Cards, modal containers | +| `--radius-xl` | `16px` | Large feature cards, image containers | +| `--radius-pill` | `980px` | Search bar, status badges, pills | + +--- + +## 7. Do's and Don'ts + +### Do + +- Use weight 300 for hero and section headlines -- this is the signature Shopify look +- Use `--color-accent` (#008060) for interactive elements only: buttons, links, active states, focus rings +- Keep surfaces matte and flat. Background color shifts convey elevation more cleanly than shadows. +- Use `--color-accent-subtle` for selected/hover tints -- it provides context without visual noise. +- Use tabular-nums for dashboard metrics and price columns to maintain alignment. +- Use 14px as the default body size. Shopify is a dense admin interface; 16px body is too large for data-rich surfaces. +- Animate with `150ms ease` for interactive state changes. Speed signals efficiency. +- Use monospace font for order IDs, discount codes, and API keys. +- Pair the ultra-light headline with a regular-weight subtitle for maximum contrast. +- Use dark mode as the primary design target; light mode is the variant, not the other way around. +- Use full-bleed cinematic photography in marketing/hero sections, but keep admin UI photography contained and purposeful. +- Use 1px borders. Never 2px or 3px except for focus rings. + +### Don't + +- Do not use `--color-accent` for decorative elements like dividers, background fills, or icons that aren't interactive. +- Do not use gradients on text. Ever. +- Do not use weight 200 below 48px -- it becomes illegible. +- Do not use weight 700 (bold). 600 is the maximum, reserved for labels and small caps only. +- Do not add box-shadows to resting-state cards or list items. Shadows are reserved for overlays and popovers only. +- Do not use rounded corners greater than `12px` on rectangular content cards. No `20px` or `24px` radius cards. +- Do not center-align paragraphs, form layouts, or dashboard content. Left-align everything. +- Do not use zebra striping in tables. Row hover is sufficient. +- Do not animate `width`, `height`, `top`, `left`, or `margin`. Use `transform` and `opacity` only. +- Do not use color alone to convey status. Pair with text labels or icons (e.g., green dot + "Active"). +- Do not use decorative gradients on card backgrounds. Subtle radial glows in hero sections are the only exception. +- Do not use emoji in navigation labels, button text, or status indicators. +- Do not mix light and dark surfaces in the same view without clear visual separation (border or spacing). + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min Width | Layout Behavior | +|------|-----------|-----------------| +| `mobile` | `0` | Single column, sidebar hidden (hamburger), stacked cards, bottom sheet modals | +| `tablet` | `768px` | Optional sidebar, 2-column card grid, side-by-side forms | +| `desktop` | `1024px` | Full sidebar visible, 2-3 column grid, standard modal overlays | +| `wide` | `1200px` | Maximum content width enforced, 3-column card grid | + +### Adaptation Rules + +- **Sidebar**: Hidden below `1024px`, replaced by hamburger menu overlay. Overlay slides in from left (`transform: translateX`, 200ms ease) with `--color-surface` background. +- **Navigation items**: Text + icon on desktop; icon-only below `768px` if sidebar is collapsed. +- **Cards**: Full-width below `768px`, 2-up at `768px+`, 3-up at `1200px+`. +- **Top bar**: Search bar collapses to icon-only below `768px`. Title truncates with ellipsis. +- **Data tables**: Convert to stacked card list on mobile. Each row becomes a card with label-value pairs. Critical columns (status, amount) remain visible as compact rows. +- **Forms**: Single column always. Top-aligned labels. Full-width inputs on mobile, max `480px` on desktop. +- **Modals**: Full-screen on mobile (with safe-area padding), centered overlay on desktop. +- **Dashboard metrics**: Stack vertically on mobile, horizontal row on desktop. +- **Font sizes**: Reduce hero from fluid scale to `2rem` (32px) below `768px`. Body text stays `14px` at all sizes -- never scale body down on mobile. + +### Spacing Scale (Mobile vs Desktop) + +| Context | Mobile | Desktop | +|---------|--------|---------| +| Section vertical padding | `24px` | `32px` to `48px` | +| Card padding | `16px` | `20px` | +| Edge margin | `16px` | `24px` to `32px` | +| Between-section gap | `24px` | `32px` to `48px` | +| Card grid gap | `12px` | `16px` | +| Sidebar width | hidden | `240px` | + +### Touch Targets + +- Minimum `44px x 44px` on mobile for all interactive elements +- Tap targets separated by at least `8px` +- Buttons on mobile: full-width or minimum `120px` wide + +### Dark Mode Handling + +Dark mode is the default. Use `prefers-color-scheme: light` to activate the light variant. All color tokens swap simultaneously. Transition between modes should be instant (no animation on color swap). Product imagery may remain the same between modes -- only UI surfaces swap. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/spotify.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/spotify.md new file mode 100644 index 00000000..d0ff7ab8 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/spotify.md @@ -0,0 +1,294 @@ +# Spotify Design System + +## 1. Visual Theme & Atmosphere + +Spotify's visual identity is built on a tension between darkness and vibrancy. The near-black canvas makes the signature green and album art explode forward. It feels like a club, not a boardroom: confident, rhythmic, and image-forward. + +**Atmosphere keywords:** immersive, bold, musical, confident, dark-first, cover-art-driven + +**Core tension:** Maximum visual impact from minimal color variation. One accent hue carries the entire brand. All other color comes from content (album art, artist photos, video thumbnails). + +**Mood:** Energy at rest. The UI is calm until the user plays something, then the green pulses and the artwork dominates. Surfaces stay out of the way. Content is always the star. + +--- + +## 2. Color Palette & Roles + +### Primary + +| Token | Hex | Role | +|-------|-----|------| +| `--color-spotify-green` | `#1DB954` | Primary accent, CTAs, active states, brand marks | +| `--color-spotify-green-light` | `#1ED760` | Hover/pressed state for green elements | +| `--color-spotify-green-dark` | `#1AA34A` | Active/pressed variant on dark surfaces | + +### Surfaces (Dark Mode -- default) + +| Token | Hex | Role | +|-------|-----|------| +| `--color-bg-base` | `#121212` | Page background, root surface | +| `--color-bg-elevated` | `#181818` | Card surfaces, sidebar, containers | +| `--color-bg-highlight` | `#282828` | Hover states on cards, list items | +| `--color-bg-press` | `#333333` | Active/pressed states on interactive items | +| `--color-bg-subtle` | `#1A1A1A` | Subtle surface differentiation | + +### Text + +| Token | Hex | Role | +|-------|-----|------| +| `--color-text-primary` | `#FFFFFF` | Headlines, primary body text | +| `--color-text-secondary` | `#B3B3B3` | Metadata, descriptions, timestamps | +| `--color-text-subdued` | `#6A6A6A` | Disabled states, placeholder text | +| `--color-text-on-green` | `#000000` | Text on green buttons/badges | + +### Semantic + +| Token | Hex | Role | +|-------|-----|------| +| `--color-error` | `#E91429` | Error states, destructive actions | +| `color-warning` | `#FFC862` | Warnings, offline indicators | +| `--color-link` | `#1DB954` | Links (same as primary green) | + +### Content-Driven Colors + +Spotify derives contextual color from album art and artist imagery. Use these as overlay tints on surfaces: + +| Token | Usage | +|-------|-------| +| `--color-tint` | Dominant color extracted from current album art, applied as a subtle gradient behind hero sections and now-playing bar | + +--- + +## 3. Typography Rules + +### Font Stack + +- **Primary:** `Circular`, `-apple-system`, `BlinkMacSystemFont`, `Segoe UI`, `Roboto`, `Helvetica Neue`, `sans-serif` +- **Fallback system stack** is acceptable when Circular is unavailable. Never use decorative or serif faces. + +### Scale + +| Token | Size | Weight | Line Height | Usage | +|-------|------|--------|-------------|-------| +| `--text-display` | `72px` | 900 (Black) | 1.0 | Hero headlines, landing page statements | +| `--text-title-lg` | `48px` | 700 (Bold) | 1.1 | Section headers, playlist titles | +| `--text-title` | `32px` | 700 (Bold) | 1.2 | Card titles, subsection headers | +| `--text-title-sm` | `24px` | 600 (SemiBold) | 1.25 | List headers, nav items | +| `--text-body-lg` | `18px` | 400 (Regular) | 1.5 | Intro paragraphs, feature descriptions | +| `--text-body` | `14px` | 400 (Regular) | 1.5 | Body text, list items, metadata | +| `--text-caption` | `12px` | 400 (Regular) | 1.4 | Timestamps, track numbers, small labels | +| `--text-overline` | `10px` | 700 (Bold) | 1.6 | Uppercase labels, category tags | + +### Rules + +- Headlines are always bold or black weight. Regular-weight headlines are forbidden. +- Body text on dark surfaces is `#B3B3B3`, never pure white. White body text causes eye strain on `#121212`. +- Use `text-transform: uppercase` only on overline labels (`10px` bold). Never uppercase headlines. +- Letter-spacing: default for most sizes; `+0.1em` for overline labels only. +- Never center-align body text. Left-align always. Headlines may be center-aligned only in hero sections. + +--- + +## 4. Component Stylings + +### Buttons + +| Variant | Background | Text | Border | Radius | +|---------|-----------|------|--------|--------| +| Primary | `#1DB954` | `#000000` | none | `500px` (pill) | +| Primary hover | `#1ED760` | `#000000` | none | `500px` | +| Secondary | `transparent` | `#FFFFFF` | `2px solid #FFFFFF` | `500px` | +| Secondary hover | `#FFFFFF` `1a` | `#FFFFFF` | `2px solid #FFFFFF` | `500px` | +| Ghost | `transparent` | `#B3B3B3` | none | `500px` | +| Ghost hover | `#333333` | `#FFFFFF` | none | `500px` | + +- Padding: `12px 32px` for standard, `8px 20px` for compact. +- Font: `14px bold` with `letter-spacing: 0.02em`. +- All buttons are pill-shaped (`border-radius: 500px`). Rounded rectangles are forbidden for CTAs. +- Icon + label buttons: `8px` gap, icon at `20px` size. + +### Cards + +- Background: `#181818` +- Border: none +- Radius: `8px` +- Padding: `16px` +- Hover: background transitions to `#282828` over `300ms ease` +- Image: square aspect ratio for album/playlist art, `4px` radius on the image +- Title: `16px bold`, single line with `text-overflow: ellipsis` +- Subtitle: `14px regular`, `#B3B3B3`, single line ellipsis + +### Now Playing Bar + +- Position: fixed bottom, full width +- Height: `80px` +- Background: `#181818` with `1px` top border `#282828` +- Progress bar: track `#535353`, filled `#FFFFFF`, hover filled `#1DB954` +- Progress bar height: `4px` default, `6px` on hover +- Thumb: `12px` white circle, appears on hover only + +### Navigation / Sidebar + +- Background: `#000000` +- Width: `280px` (collapsible to `72px`) +- Active item: `#282828` background, `#FFFFFF` text, `3px` left border `#1DB954` +- Inactive item: `transparent` background, `#B3B3B3` text +- Icon size: `24px` +- Item height: `40px`, padding `0 16px` + +### Input Fields + +- Background: `#333333` +- Border: `2px solid transparent` +- Focus border: `2px solid #1DB954` +- Text: `#FFFFFF` `14px` +- Placeholder: `#6A6A6A` +- Radius: `4px` +- Padding: `12px 16px` + +### Toggles / Switches + +- Track off: `#535353`, on: `#1DB954` +- Knob: `#FFFFFF` `20px` circle +- Track size: `40px x 20px`, radius `10px` + +### Chips / Pills + +- Background: `#333333` +- Text: `#FFFFFF` `13px regular` +- Selected: background `#1DB954`, text `#000000` `13px bold` +- Radius: `500px` +- Padding: `6px 16px` + +--- + +## 5. Layout Principles + +### Grid + +- 12-column grid with `16px` gutters on desktop. +- Sidebar occupies fixed columns; main content fills remaining space. +- Card grids: auto-fill with `minmax(180px, 1fr)`. + +### Spacing Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `--space-xs` | `4px` | Tight internal gaps | +| `--space-sm` | `8px` | Icon gaps, inline spacing | +| `--space-md` | `16px` | Standard padding, card gutters | +| `--space-lg` | `24px` | Section internal padding | +| `--space-xl` | `32px` | Between sections | +| `--space-2xl` | `48px` | Page-level vertical rhythm | +| `--space-3xl` | `64px` | Hero section vertical padding | + +### Album-Art-Driven Layout + +Content grids are organized around cover art. The image is the primary visual anchor: + +1. Image occupies the top or left of every content card. +2. Card hierarchy: image > title > subtitle. No card is without an image. +3. In hero contexts (playlist header, artist page), the cover art spans large and the background is tinted with the dominant color of the artwork. +4. List views use a `56px x 56px` thumbnail; grid views use square cards starting at `180px`. + +### Z-Pattern for Landing Pages + +Hero with bold headline and green CTA on the left, visual on the right. Alternate sections follow a zigzag. Always end with a green CTA section. + +--- + +## 6. Depth & Elevation + +Spotify uses minimal elevation. The dark palette does most of the separation work. + +| Level | Shadow | Usage | +|-------|--------|-------| +| 0 | none | Default surface, page background | +| 1 | `0 2px 8px rgba(0,0,0,0.3)` | Cards at rest, sidebar | +| 2 | `0 4px 16px rgba(0,0,0,0.4)` | Hovered cards, tooltips | +| 3 | `0 8px 32px rgba(0,0,0,0.6)` | Modals, dropdown menus, now-playing bar | + +### Rules + +- No colored shadows. Shadows are always pure black with opacity. +- No borders on elevated surfaces. Use shadow alone for separation. +- The now-playing bar uses elevation level 3 because it must float above all scrolling content. +- Card hover transitions: shadow rises from level 1 to level 2 over `300ms ease`. +- Background color transitions on hover (`#181818` to `#282828`) happen simultaneously with shadow changes. + +--- + +## 7. Do's and Don'ts + +### Do + +- Use `#1DB954` sparingly. It is an accent, not a fill color for large areas. +- Let album art and imagery carry the visual weight. The UI frame should disappear. +- Use pill-shaped buttons for all CTAs. +- Show progress with the green-to-gray bar pattern. +- Use `#B3B3B3` for secondary text on dark backgrounds. +- Transition hover states with `300ms ease` or `200ms ease-out`. +- Make image thumbnails square for music content. +- Extract tint color from album art for atmospheric backgrounds. +- Use bold/black weight for any text above `20px`. + +### Don't + +- Never use `#1DB954` as a background for large sections. Green surfaces beyond buttons and badges feel garish. +- Never use rounded-rectangle buttons. Spotify buttons are always pill-shaped. +- Never place white body text on `#121212` for paragraphs longer than one line. +- Never add colored borders or outlines to cards. Cards are borderless. +- Never use drop shadows on text. Spotify text is always flat. +- Never use serif fonts or decorative typefaces. +- Never animate more than one property at a time on interactive elements (hover = background color OR shadow, not both in conflicting directions). +- Never use `#1DB954` and `#E91429` adjacent to each other. The green-red clash is visually jarring. +- Never use placeholder images or empty states without a clear icon and label. The `#282828` card with a centered `#6A6A6A` icon and label is the standard empty state. + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min Width | Layout | +|------|-----------|--------| +| Mobile | `0` | Single column, bottom nav, no sidebar | +| Tablet | `768px` | Two-column, collapsible sidebar | +| Desktop | `1024px` | Full sidebar + main content | +| Wide | `1440px` | Max-width container `1680px`, centered | + +### Mobile Adaptations + +- Sidebar becomes a bottom tab bar with 5 items (Home, Search, Library, Premium, icon-only). +- Cards switch to a horizontal scroll row instead of a grid. +- Now-playing bar shrinks to `64px` with artwork thumbnail, track name, and play/pause only. Full controls expand on tap. +- Hero sections collapse: headline drops to `--text-title` (`32px`), image scales down. +- Pill buttons stretch to full width with `16px` horizontal margin. +- Search input is full width with `16px` horizontal padding. + +### Tablet Adaptations + +- Sidebar collapses to icon-only (`72px` width) by default, expands on tap. +- Card grid uses `minmax(150px, 1fr)`. +- Now-playing bar remains at `80px`. + +### Desktop Adaptations + +- Sidebar is fully expanded (`280px`) with text labels. +- Card grid uses `minmax(180px, 1fr)`. +- Hover states are active (no hover on mobile/tablet touch). + +### Image Sizing + +| Context | Mobile | Tablet | Desktop | +|---------|--------|--------|---------| +| Hero cover art | `128px` | `192px` | `232px` | +| Grid card thumbnail | `100%` width, square | `100%` width, square | `100%` width, square | +| List thumbnail | `48px` | `56px` | `56px` | +| Now-playing art | `48px` | `56px` | `56px` | + +### Touch Targets + +- Minimum `44px x 44px` on mobile and tablet. +- Minimum `32px x 32px` on desktop. +- Playback controls (play/pause, skip): minimum `48px x 48px` on all sizes. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/starbucks.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/starbucks.md new file mode 100644 index 00000000..fe530128 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/starbucks.md @@ -0,0 +1,342 @@ +# Starbucks Design System + +Warm Siren green on a cream canvas. The "third place" made digital — not home, not work, but somewhere that feels like both. Starbucks' visual language wraps every surface in the warmth of a coffeehouse: soft cream backgrounds instead of sterile whites, pill-shaped buttons that feel approachable, a family of greens that echo the iconic apron, and typefaces designed to feel like they have always been part of the brand. The Siren is the muse; everything else serves her world. + +--- + +## 1. Visual Theme & Atmosphere + +Starbucks' design language translates the physical coffeehouse into a digital experience. The core philosophy is "third place" — a welcoming space between home and work where warmth, craft, and community converge. Every surface should feel like it has been touched by human hands, not stamped by a machine. The warm cream canvas is the coffeehouse wall; the green accents are the barista's apron visible across the room; the rounded corners are the curve of a ceramic cup. + +The page is a coffeehouse. Cream and warm neutrals are the walls and wood tables. Starbucks Green is the apron and the Siren — visible from across the room, never wallpapered over every surface. Photography shows real people in real moments: hands around cups, steam rising, morning light through windows. Illustration carries the hand-drawn legacy — the Siren, line art, seasonal artwork — never generic iconography. Typography speaks in Sodo Sans for everyday warmth, Pike for bold menu-board headlines, and Lander for artful expressive moments. + +Color is anchored in a family of greens that leverages instant brand recognition. The green is never decorative — it is structural. Expressive seasonal palettes evolve with trends, but brand green is always present, either in the composition or through the Siren logo. The overall feeling is optimistic, joyful, and recognizably Starbucks: calm confidence with artful warmth. + +**Keywords:** warm, inviting, community, craft, approachable, coffeehouse, third place, Siren green, natural, artful + +--- + +## 2. Color Palette & Roles + +Starbucks' color system centers on a four-tier family of greens — Starbucks Green, Accent Green, Light Green, and House Green — layered over a warm cream canvas. Neutrals are warm, never cool. The dark palette uses deep green and earth tones, never pure black. + +### Light Mode + +| Token | Hex | Role | +|-------|-----|------| +| `--color-canvas` | `#F2F0EB` | Page background — warm cream, the coffeehouse canvas. Never pure white. | +| `--color-surface` | `#FFFFFF` | Card and container background on cream canvas | +| `--color-surface-warm` | `#FAF8F5` | Subtle warm tint for featured sections, alternating bands | +| `--color-surface-green` | `#D4E9E2` | Light green surface for highlighted content, reward tiers | +| `--color-ink` | `#1E3932` | Primary text — House Green, deep and warm, never pure black | +| `--color-body` | `#2F2E2C` | Default running text — warm black with earth undertone | +| `--color-muted` | `#61605B` | Secondary text, descriptions, helper text | +| `--color-muted-soft` | `#8C8B86` | Tertiary text, placeholder, timestamps | +| `--color-starbucks-green` | `#00704A` | Siren Green — primary brand accent, CTAs, active states, logo. The iconic apron green. | +| `--color-accent-green` | `#00A862` | Accent Green — hover and secondary green actions, progress indicators | +| `--color-light-green` | `#D4E9E2` | Light Green — tinted backgrounds, selected states, subtle brand presence | +| `--color-house-green` | `#1E3932` | House Green — deep green-black, primary text, footer backgrounds | +| `--color-primary-hover` | `#005C3E` | Hover state for Siren Green elements | +| `--color-primary-active` | `#004D34` | Active/pressed state for Siren Green | +| `--color-on-green` | `#FFFFFF` | White text on green buttons and badges | +| `--color-warm-neutral` | `#C8C5BE` | Warm gray borders, subtle dividers | +| `--color-cool-neutral` | `#A7A9AB` | Cool neutral for specific secondary elements, rarely used | +| `--color-gold` | `#C2A461` | Gold/Star accent — Rewards stars, premium tier indicators | +| `--color-success` | `#00704A` | Positive, confirmed — reuses brand green | +| `--color-warning` | `#D4A017` | Caution, pending states | +| `--color-error` | `#C62828` | Destructive, error, unavailable | +| `--color-border` | `#E0DDD6` | Default borders, input borders, card outlines | + +### Dark Mode + +| Token | Hex | Role | +|-------|-----|------| +| `--color-canvas` | `#1E3932` | Page background — House Green, deep and warm, not pure black | +| `--color-surface` | `#2A4A40` | Card and container background on dark canvas | +| `--color-surface-elevated` | `#345C4F` | Elevated container — modals, dropdowns | +| `--color-surface-warm` | `#243D35` | Subtle warm differentiation on dark canvas | +| `--color-surface-green` | `#1A3B30` | Dark green tint for highlighted content | +| `--color-ink` | `#F2F0EB` | Primary text on dark — warm cream | +| `--color-body` | `#D4D1CB` | Default running text on dark | +| `--color-muted` | `#A0A08C` | Secondary text on dark | +| `--color-muted-soft` | `#7A7A6E` | Tertiary text on dark | +| `--color-starbucks-green` | `#00A862` | Siren Green shifts lighter on dark — Accent Green becomes the primary interactive color | +| `--color-accent-green` | `#1DB954` | Brighter accent on dark — hover states, secondary green | +| `--color-light-green` | `#1A3B30` | Dark green tint background | +| `--color-house-green` | `#1E3932` | Unchanged — this IS the dark canvas | +| `--color-primary-hover` | `#00C070` | Hover on dark — shifted lighter | +| `--color-primary-active` | `#00D480` | Active on dark — shifted lighter still | +| `--color-on-green` | `#FFFFFF` | White text on green buttons (unchanged) | +| `--color-warm-neutral` | `#4A5E55` | Borders on dark | +| `--color-gold` | `#D4B46A` | Gold on dark — shifted lighter for contrast | +| `--color-success` | `#1DB954` | Positive on dark — shifted lighter | +| `--color-warning` | `#E6B422` | Warning on dark | +| `--color-error` | `#EF5350` | Error on dark — shifted lighter | +| `--color-border` | `#3A5A4D` | Borders on dark surfaces | + +**Rule:** Starbucks Green (`#00704A`) is the brand's most identifiable asset — visible for blocks, as they say. On dark surfaces it shifts to Accent Green (`#00A862`) for legibility. The warm cream canvas (`#F2F0EB`) is never replaced with pure white in light mode, and pure black (`#000000`) is never used as a dark background — House Green (`#1E3932`) carries the warmth into darkness. The green family must always be present, either within the composition or through the Siren logo. + +### Seasonal Expression Palettes + +Starbucks evolves expressive colors with seasonal trends while keeping brand greens constant: + +| Season | Accent Tones | Usage | +|--------|-------------|-------| +| Spring | Soft pinks, fresh yellows, sage | Promotional banners, seasonal menus, app highlights | +| Summer | Bright corals, turquoise, sunny gold | Cold beverage promotions, Frappuccino campaigns | +| Fall | Burnt orange, deep burgundy, warm brown | Pumpkin spice, holiday countdown, warm beverage imagery | +| Winter/Nitro | Deep navy, icy blue, silver | Nitro Cold Brew, holiday red cup season, gift guides | + +--- + +## 3. Typography Rules + +### Font Stack + +- **Primary (body, UI):** `Sodo Sans`, `-apple-system`, `BlinkMacSystemFont`, `Segoe UI`, `Roboto`, `Helvetica Neue`, `sans-serif` +- **Display (headlines, wayfinding):** `Pike`, `Sodo Sans Condensed`, `Impact`, `Arial Narrow`, `sans-serif` +- **Expressive (accent moments):** `Lander`, `Georgia`, `Cambria`, `Times New Roman`, `serif` + +Sodo Sans is a geometric sans with a friendly character — double-storey 'g' for legibility, symmetrical 'u' echoing the brand logotype. It comes in three widths: Normal, Narrow, and Condensed, providing finer control in typesetting. Pike is a condensed display face with an increased x-height, designed for impactful headlines and menu boards — it shares DNA with Sodo Sans but has its own stance. Lander is a serif with 1970s warmth, drawn in three optical sizes: Grande (large display), Tall (headlines), and Short (text). It provides artful, expressive contrast to the sans families. + +### Scale + +| Token | Size | Weight | Line Height | Tracking | Font | Usage | +|-------|------|--------|-------------|----------|------|-------| +| `--text-hero` | `clamp(40px, 5vw, 72px)` | 700 | 1.05 | `-0.02em` | Pike | Hero headlines, campaign statements, splash pages | +| `--text-display` | `clamp(32px, 3.5vw, 56px)` | 700 | 1.1 | `-0.015em` | Pike | Section heroes, major announcements | +| `--text-headline` | `clamp(24px, 2vw, 36px)` | 700 | 1.15 | `-0.01em` | Sodo Sans | Section headers, card hero titles | +| `--text-title` | `clamp(20px, 1.5vw, 28px)` | 600 | 1.2 | `-0.005em` | Sodo Sans | Subsection headers, feature titles | +| `--text-title-sm` | `18px` | 600 | 1.25 | `0` | Sodo Sans | List headers, nav items, card titles | +| `--text-body-lg` | `16px` | 400 | 1.6 | `0` | Sodo Sans | Intro paragraphs, feature descriptions, menu descriptions | +| `--text-body` | `14px` | 400 | 1.5 | `0` | Sodo Sans | Body text, list items, product details | +| `--text-caption` | `12px` | 400 | 1.4 | `0.01em` | Sodo Sans | Nutritional info, timestamps, small labels | +| `--text-overline` | `11px` | 700 | 1.6 | `0.08em` | Sodo Sans | Uppercase labels, category tags, section markers | +| `--text-expressive` | `clamp(28px, 3vw, 48px)` | 400 | 1.15 | `0` | Lander | Expressive moments, editorial headlines, seasonal features | + +### Rules + +- Headlines are always bold (700) or semibold (600). Regular-weight headlines are forbidden. +- Sodo Sans is the default for everything. Pike is reserved for display headlines where impact is needed — hero sections, menu boards, campaign banners. Lander is for artful, expressive moments — editorial features, seasonal storytelling, accent pull quotes. +- Body text on cream canvas uses `#2F2E2C` (warm black), never pure `#000000`. Pure black on warm cream creates visual tension. +- Use `text-transform: uppercase` only on overline labels and Pike display headlines. Sodo Sans headlines are always title-case or sentence-case. +- Letter-spacing: negative for headlines ( Pike at `-0.02em` to `-0.01em`), zero for body, positive only for overline labels and all-caps Pike treatments. +- Pike is frequently set in all-caps with generous tracking for menu boards and wayfinding — this is a signature Starbucks typographic treatment. +- Never center-align body text. Left-align always. Headlines may be center-aligned only in hero sections and campaign banners. +- Lander optical sizes: Grande for >48px display, Tall for 24-48px headlines, Short for <24px text. Using the wrong optical size produces either spindly hairlines or overly thick strokes. + +--- + +## 4. Component Stylings + +### Buttons + +| Variant | Background | Text | Border | Radius | +|---------|-----------|------|--------|--------| +| Primary | `#00704A` | `#FFFFFF` | none | `50px` (pill) | +| Primary hover | `#005C3E` | `#FFFFFF` | none | `50px` | +| Primary active | `#004D34` | `#FFFFFF` | none | `50px` | +| Secondary | `transparent` | `#00704A` | `2px solid #00704A` | `50px` | +| Secondary hover | `#D4E9E2` | `#005C3E` | `2px solid #005C3E` | `50px` | +| Ghost | `transparent` | `#1E3932` | none | `50px` | +| Ghost hover | `#D4E9E2` | `#1E3932` | none | `50px` | +| Floating CTA (Frap) | `#00704A` | `#FFFFFF` | none | `999px` (circle) | + +- Padding: `14px 32px` for standard, `10px 24px` for compact. +- Font: Sodo Sans `14px` weight 600 with `letter-spacing: 0.02em`. +- All buttons are pill-shaped (`border-radius: 50px`). Starbucks uses a universal 50px pill button — this is a defining signature. +- The floating circular CTA (Frap button) is used for primary single-action moments — order button, reorder, add to cart. It is a circle (not pill), typically 50px diameter, positioned floating bottom-right on mobile. +- Icon + label buttons: `8px` gap, icon at `20px` size. +- Transition: `200ms ease-out` for all state changes. + +### Navigation + +- Fixed top bar, `height: 60px`, `#FFFFFF` background with 1px `#E0DDD6` bottom border. +- Logo (Siren) left, navigation center or left-aligned, cart/account right. +- Siren logo preferred unlocked from wordmark — used by itself for a more modern, open presentation. +- Nav items: Sodo Sans `14px` weight 600, `#1E3932` text, `#00704A` active state. +- Hover: text color transitions to `#00704A` over `150ms ease`. +- Mobile: hamburger menu, Siren logo center, cart icon right. + +### Cards (Product / Menu Item) + +- Background: `#FFFFFF`, `border-radius: 16px`, no border (shadow-based depth on cream canvas). +- Image: `border-radius: 16px` matching card, aspect-ratio 1/1 for beverages, 3/2 for food/lifestyle. +- Product title: Sodo Sans `16px` weight 600, `#1E3932`, single line with `text-overflow: ellipsis`. +- Description: Sodo Sans `14px` weight 400, `#61605B`, two-line clamp. +- Price: Sodo Sans `16px` weight 700, `#1E3932`, positioned bottom-right. +- Hover: subtle lift (`translateY(-2px)`) + shadow increase over `200ms ease-out`. +- Featured cards: `border-radius: 20px`, larger padding, lifestyle imagery. + +### Image Treatments + +- **Lifestyle photography:** Warm lighting, natural settings, community moments. Hands holding cups, baristas at work, morning rituals. Never sterile studio shots. +- **Product photography:** Clean but warm — beverages on natural surfaces (wood, marble, canvas). Shallow depth of field, soft directional lighting. +- **Illustration:** Rooted in brand heritage. The Siren, line art, seasonal artwork. Texture, photo collage, composition, and graphic details give a custom, handcrafted feel. Never generic flat icons. +- **Image radius:** `16px` for standard, `20px` for hero/featured, `12px` for thumbnails, `8px` for inline images. +- **Overlay:** When text overlays imagery, use a gradient overlay from `rgba(30,57,50,0.7)` to `transparent` — House Green, not black. + +### Data / Specs (Nutritional, Order Details) + +- Background: `#FFFFFF`, `border-radius: 12px`, 1px `#E0DDD6` border. +- Header row: `#D4E9E2` light green background, Sodo Sans `12px` weight 700. +- Data rows: alternating `#FFFFFF` and `#FAF8F5`. +- Values: Sodo Sans `14px` weight 600 for numbers, `14px` weight 400 for labels. +- Divider: 1px `#E0DDD6` between rows. + +### Rewards / Loyalty Elements + +- Star icon: `#C2A461` gold fill, animated on earn. +- Progress bar: track `#E0DDD6`, filled `#C2A461` gradient to `#D4B46A`. +- Tier badges: circular with Sodo Sans Condensed all-caps label. +- Points/Stars display: Pike `24px` weight 700, `#C2A461` color. + +--- + +## 5. Layout Principles + +### Grid + +- 12-column grid with `24px` gutters on desktop. +- Content max-width: `1200px`, centered. +- Card grids: `auto-fill, minmax(260px, 1fr)` for product listings. +- Menu/product layouts often use asymmetric grids — a hero feature card spanning 2 columns alongside standard single-column cards. + +### Spacing Scale + +| Token | Value | Usage | +|-------|-------|-------| +| `--space-xs` | `4px` | Tight internal gaps, icon-text spacing | +| `--space-sm` | `8px` | Inline spacing, chip padding | +| `--space-md` | `16px` | Standard padding, card internal spacing | +| `--space-lg` | `24px` | Card gutters, section internal padding | +| `--space-xl` | `32px` | Between sections | +| `--space-2xl` | `48px` | Major section separation | +| `--space-3xl` | `64px` | Hero section vertical padding | +| `--space-4xl` | `96px` | Page-level vertical rhythm on desktop | + +### Alignment Rules + +- Left-align all body text and data. Center-align only hero headlines and campaign statements. +- Product imagery is typically center-aligned within its card container. +- Price and CTA are right-aligned or bottom-aligned within cards. +- The Siren logo is always centered within its container — never cropped, never rotated, never tilted. +- Menu items follow a consistent pattern: image left (or top), text content right (or bottom), price/CTA bottom-right. + +### Coffeehouse Rhythm + +Layout should breathe like a coffeehouse — not cramped like a fast-food menu board, and not sparse like a corporate lobby. Sections have generous vertical spacing. Content areas feel like distinct "seating zones" — the rewards area feels different from the menu area, separated by warmth and spacing rather than hard dividers. Warm cream (`#F2F0EB`) backgrounds alternate with white (`#FFFFFF`) sections to create natural flow without visible borders. + +--- + +## 6. Depth & Elevation + +Starbucks uses gentle, warm shadows on the cream canvas. The cream background does most of the separation work; shadows add subtle lift, not dramatic floating. + +| Level | Shadow | Usage | +|-------|--------|-------| +| 0 | none | Default surface, cream canvas background | +| 1 | `0 2px 8px rgba(30,57,50,0.08)` | Cards at rest on cream canvas | +| 2 | `0 4px 16px rgba(30,57,50,0.12)` | Hovered cards, elevated inputs | +| 3 | `0 8px 24px rgba(30,57,50,0.16)` | Modals, dropdown menus, sticky elements | +| 4 | `0 12px 40px rgba(30,57,50,0.20)` | Full-screen overlays, prominent floating CTAs | + +### Rules + +- Shadows use House Green (`rgba(30,57,50,...)`) as the shadow color instead of pure black — this produces a warmer, more natural shadow that sits harmoniously on the cream canvas. Pure black shadows create cold contrast against warm surfaces. +- No colored shadows beyond the warm green tint. No green glow effects. +- Card hover: shadow rises from level 1 to level 2, combined with `translateY(-2px)` over `200ms ease-out`. +- Elevated surfaces (modals, dropdowns) on cream canvas use white (`#FFFFFF`) backgrounds — the contrast between white surface and cream canvas provides inherent separation even without shadow. +- On dark mode, shadows use deeper green tints: `rgba(0,0,0,0.3)` through `rgba(0,0,0,0.6)`. +- Borders and shadows are never used together on the same element. Choose one method of separation. + +--- + +## 7. Do's and Don'ts + +### Do + +- Always maintain a presence of brand green — either within the composition or through the Siren logo. A page without green is not Starbucks. +- Use the warm cream canvas (`#F2F0EB`) as the default light background. Pure white is for cards and elevated surfaces only. +- Use pill-shaped buttons (`border-radius: 50px`) for all CTAs. This is a Starbucks signature. +- Let lifestyle photography carry the warmth — real moments, real people, natural light, community settings. +- Use Sodo Sans for body and UI text, Pike for impactful headlines and menu boards, Lander sparingly for expressive accent moments. +- Round everything generously — 16px for cards, 12px for inputs, 50px for buttons. Nothing sharp, nothing aggressive. +- Write conversationally — "What can we get started for you?" not "Begin Order". Warmth extends to copy. +- Use warm-tinted shadows (`rgba(30,57,50,...)`) instead of cold black shadows on the cream canvas. +- Feature the Siren logo unlocked from the wordmark for a modern, open presentation. +- Use seasonal expression palettes to stay relevant while keeping brand greens constant. +- Show the gold star (`#C2A461`) prominently in Rewards contexts — loyalty is a core experience. +- Design for mobile-first. The Starbucks app is the primary digital touchpoint for most customers. + +### Don't + +- Never use pure `#000000` as a background in dark mode. House Green (`#1E3932`) is the dark canvas. Pure black feels cold and corporate, not warm and inviting. +- Never use Siren Green (`#00704A`) as a background fill for large areas. Green is an accent and brand anchor, not a surface color. +- Never apply sharp corners (`border-radius: 0`) to any interactive element or card. Sharp corners contradict the warm, approachable brand. +- Never use cool gray palettes or blue undertones in neutrals. Starbucks neutrals are warm — cream, warm gray, earth tones. +- Never use generic stock photography or flat vector icons. Every image should feel like a real coffeehouse moment; every illustration should carry the handcrafted quality of the Siren tradition. +- Never center-align body text paragraphs. Left-align always. +- Never use regular weight (400) for headlines. Headlines demand weight — semibold (600) minimum, bold (700) preferred. +- Never rotate, distort, crop, or tilt the Siren logo. She always faces forward, centered, and complete. +- Never use more than two of the three typeface families (Sodo Sans, Pike, Lander) in a single view. Three is acceptable only in hero/campaign layouts where Lander provides a deliberate expressive accent. +- Never place white body text on `#F2F0EB` cream backgrounds — insufficient contrast. Use `#1E3932` House Green for text on cream. +- Never use green and red adjacent as equal-weight accents. The green-red clash reads as Christmas, not coffeehouse. +- Never hide pricing in product cards. Price visibility builds trust. + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min Width | Layout | +|------|-----------|--------| +| Mobile | `0` | Single column, bottom nav, stacked cards, floating CTA | +| Tablet | `768px` | Two-column grid, collapsible side menu, wider cards | +| Desktop | `1024px` | Three-to-four column grid, full navigation, side panels | +| Wide | `1440px` | Max-width container `1200px`, centered, breathing room | + +### Mobile Adaptations + +- Navigation collapses to bottom tab bar (Home, Order, Rewards, Stores, Account) — the Starbucks app pattern. +- The floating circular CTA (Frap button) appears bottom-right for primary order/reorder actions. +- Product cards switch to horizontal scroll rows ("Featured Drinks", "Popular Near You") instead of grid. +- Hero sections collapse: headline drops to `--text-headline` size, imagery scales to single-column full-width. +- Pill buttons stretch to full width with `16px` horizontal margin. +- Menu browsing uses a vertically scrollable category list on the left or top chips for filtering. +- Order details become a bottom sheet that slides up, with a sticky "Checkout" pill at the bottom. +- Search input is full width with `16px` horizontal padding. +- Touch targets: minimum `44px x 44px` on all interactive elements. + +### Tablet Adaptations + +- Product grid uses `minmax(220px, 1fr)` — typically 2-3 columns. +- Navigation may use a compact top bar with icon + label. +- Order flow uses a split view: menu browsing left, cart summary right. +- Cards show slightly more content (three-line descriptions instead of two). + +### Desktop Adaptations + +- Full four-column product grid with `minmax(260px, 1fr)`. +- Top navigation with full text labels, Siren logo, and search bar. +- Hero sections use asymmetric layouts: large image + overlaid text, or split 60/40 text-image. +- Hover states are active (not available on touch devices). +- Footer expands with full link columns and Siren logo. + +### Image Sizing + +| Context | Mobile | Tablet | Desktop | +|---------|--------|--------|---------| +| Hero beverage image | `200px` | `280px` | `360px` | +| Product card thumbnail | `100%` width, 1:1 | `100%` width, 1:1 | `100%` width, 1:1 | +| Category icon | `48px` | `56px` | `64px` | +| Store/location thumbnail | `80px` | `96px` | `120px` | +| Rewards star | `24px` | `28px` | `32px` | + +### Touch Targets + +- Minimum `44px x 44px` on mobile and tablet. +- Minimum `32px x 32px` on desktop. +- Order/Add-to-cart buttons: minimum `50px` height on all sizes (matching the pill button signature). +- The floating CTA (Frap button): `56px` diameter on mobile, `50px` on desktop. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/stripe.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/stripe.md new file mode 100644 index 00000000..5bf813df --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/stripe.md @@ -0,0 +1,457 @@ +# Stripe Design System + +## 1. Visual Theme & Atmosphere + +Stripe's visual identity is built on **engineered elegance** — a clean white canvas punctuated by signature purple gradients, weight-300 body typography that feels light and confident, and a trust-forward financial aesthetic that reads as precise without feeling cold. The system alternates between bright white surfaces and deep navy sections, with purple serving as the sole chromatic accent on chrome. Every surface feels considered and load-bearing; decoration is minimal and purposeful. + +The design reads as "infrastructure you can trust rendered with the restraint of a Swiss poster." Headlines are set in a clean geometric sans at light weights (300) with generous letter-spacing, creating an airy authority. Code and data surfaces sit in dark wells that contrast sharply with the white canvas. Purple gradients flow across hero bands and CTAs, giving the system its signature warmth within a predominantly neutral palette. + +**Key Characteristics:** + +- White canvas (`#FFFFFF`) as the default page background with `#F6F9FC` for inset bands +- Signature purple gradient (`#635BFF` to `#7A73FF`) reserved for CTAs, hero bands, and accent surfaces +- Deep navy (`#0A2540`) for dark sections and code wells — never pure black +- Weight-300 body typography as the default, creating the system's characteristic lightness +- Generous whitespace (96px+ section rhythm) with tight in-card padding (16-24px) +- Subtle layered shadows that lift cards gently off the canvas — no hard edges +- Rounded corners in the 6-8px range for cards and containers, 4px for inputs and small elements + +--- + +## 2. Color Palette & Roles + +### Brand & Accent + +| Name | Hex | Role | +|------|-----|------| +| `purple-600` | `#635BFF` | Primary brand color. CTAs, links, active states, hero gradient start. | +| `purple-500` | `#7A73FF` | Primary hover, gradient end stop, lighter accent surfaces. | +| `purple-400` | `#8B83FF` | Focus rings, subtle purple borders, disabled-active purple. | +| `purple-100` | `#E8E5FF` | Soft purple tint for backgrounds of highlighted or selected items. | +| `purple-50` | `#F4F2FF` | Faintest purple wash — inline code backgrounds, subtle row hover. | +| `gradient-hero` | `linear-gradient(135deg, #635BFF 0%, #7A73FF 100%)` | Hero band backgrounds, primary CTA fills, feature accent bands. | + +### Surface + +| Name | Hex | Role | +|------|-----|------| +| `white` | `#FFFFFF` | Default page canvas, card backgrounds, input fills. | +| `gray-50` | `#F6F9FC` | Inset bands, alternating section backgrounds, table row stripes. | +| `gray-100` | `#E8ECF1` | Dividers, hairline borders on light surfaces, subtle separators. | +| `gray-200` | `#C1C9D2` | Disabled borders, placeholder text underline, secondary dividers. | +| `navy-900` | `#0A2540` | Dark section backgrounds, code wells, footer canvas. | +| `navy-800` | `#1A2E4A` | Elevated dark surface, dark card backgrounds. | +| `navy-700` | `#2D3E54` | Secondary dark surface, in-well panel backgrounds. | + +### Text + +| Name | Hex | Role | +|------|-----|------| +| `ink` | `#1A1F36` | Primary body text on light surfaces. Near-black with warmth. | +| `body` | `#425466` | Long-form body copy where ink reads too heavy. | +| `charcoal` | `#5A6980` | Captions, metadata, secondary content. | +| `mute` | `#697386` | Placeholder text, supporting copy, inactive labels. | +| `ash` | `#8792A2` | Disabled text, tertiary labels, least-emphasis utility. | +| `stone` | `#A3ACB9` | Disabled foreground, neutral icon outlines. | +| `on-dark` | `#FFFFFF` | Primary text on navy/dark surfaces. | +| `on-dark-mute` | `rgba(255,255,255,0.72)` | Secondary text on dark surfaces. | + +### Semantic + +| Name | Hex | Role | +|------|-----|------| +| `success` | `#30B566` | Success states, confirmations, positive indicators. | +| `success-soft` | `#E6F9EF` | Success background tint. | +| `warning` | `#E5A54B` | Warning states, caution indicators. | +| `warning-soft` | `#FFF6E9` | Warning background tint. | +| `error` | `#D84040` | Error states, destructive actions, validation failures. | +| `error-soft` | `#FDE8E8` | Error background tint. | +| `info` | `#00B4D8` | Informational badges, neutral highlights. | +| `info-soft` | `#E3F6FC` | Info background tint. | + +### Dark Mode Override + +| Name | Hex | Role | +|------|-----|------| +| `dm-canvas` | `#0A2540` | Default page background. | +| `dm-surface` | `#1A2E4A` | Card and elevated panel background. | +| `dm-surface-elevated` | `#2D3E54` | Button fills, input fills on dark. | +| `dm-hairline` | `rgba(255,255,255,0.08)` | Card borders on dark surfaces. | +| `dm-hairline-strong` | `rgba(255,255,255,0.16)` | Stronger dividers on dark. | + +--- + +## 3. Typography Rules + +### Font Families + +| Role | Family | Fallback | Notes | +|------|--------|----------|-------| +| Display & UI | `Inter` | `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif` | Primary face. Load with `font-display: swap`. | +| Code | `JetBrains Mono` | `"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace` | API examples, inline code, terminal blocks. | + +Inter is the primary typeface. Stripe's signature lightness comes from using **weight 300** as the default body weight — this is non-negotiable. Headlines and display type use weight 500 or 600 for structural contrast, never 700+. The result is an airy hierarchy where weight contrast does the work that size alone cannot. + +### Hierarchy + +| Token | Size | Weight | Line Height | Letter Spacing | Use | +|-------|------|--------|-------------|----------------|-----| +| `display-2xl` | 72px | 600 | 1.05 | -1.5px | Hero headline. One per page. | +| `display-xl` | 56px | 600 | 1.1 | -1px | Section openers, landing page headlines. | +| `display-lg` | 44px | 500 | 1.15 | -0.5px | Sub-section display, pricing tier names. | +| `display-md` | 32px | 500 | 1.25 | -0.3px | Feature card titles, in-section headlines. | +| `heading-lg` | 24px | 500 | 1.35 | -0.2px | Card headings, panel titles. | +| `heading-md` | 20px | 500 | 1.4 | 0 | In-card section heads, sidebar titles. | +| `heading-sm` | 16px | 500 | 1.5 | 0 | Small headings, form group labels. | +| `body-lg` | 18px | 300 | 1.65 | 0 | Lead paragraphs, hero subtitles. | +| `body-md` | 16px | 300 | 1.6 | 0 | Default body text, form labels, descriptions. | +| `body-sm` | 14px | 300 | 1.6 | 0 | Card descriptions, metadata, secondary copy. | +| `caption` | 12px | 400 | 1.5 | 0.2px | Timestamps, footer links, small utility text. | +| `link-md` | 16px | 500 | 1.6 | 0 | Inline body links — weight 500 distinguishes from body 300. | +| `button-lg` | 16px | 500 | 1.0 | 0.2px | Large CTA button label. | +| `button-md` | 14px | 500 | 1.0 | 0.2px | Default button label. | +| `code-md` | 14px | 400 | 1.7 | 0 | Code blocks, inline code, API paths. | +| `code-sm` | 12px | 400 | 1.6 | 0 | Tab labels, small code tokens. | + +### Principles + +- **Weight-300 is the default.** Body text at weight 300 creates the characteristic Stripe lightness. Never bump body to 400 for emphasis — use weight 500 on headings or change the family to `JetBrains Mono` for technical emphasis. +- **Negative letter-spacing on display sizes** tightens large type into cohesive blocks. Scale the negative value with size: -1.5px at 72px down to 0 at 16px. +- **Line height opens at body sizes** (1.6-1.65) to maintain readability with the light weight. Display sizes tighten to 1.05-1.25. +- **No serifs anywhere.** The system is entirely sans-serif for UI and monospace for code. + +--- + +## 4. Component Stylings + +### Buttons + +**`button-primary`** — Purple gradient CTA + +- Background: `gradient-hero` (`linear-gradient(135deg, #635BFF, #7A73FF)`) +- Text: `#FFFFFF` +- Typography: `button-md` (14px / 500) +- Border radius: 6px +- Padding: 10px 20px +- Height: 40px +- Border: none +- Hover: background shifts to solid `#635BFF`, slight brightness increase +- Active/pressed: background `#5850E6` (one shade darker) +- Focus: 3px ring in `purple-400` offset by 2px +- Transition: 150ms ease on background-color + +**`button-primary-lg`** — Large hero CTA + +- Same as `button-primary` but: +- Typography: `button-lg` (16px / 500) +- Padding: 14px 28px +- Height: 48px +- Border radius: 8px + +**`button-secondary`** — Outline button + +- Background: `#FFFFFF` +- Text: `ink` (`#1A1F36`) +- Typography: `button-md` +- Border: 1px solid `gray-100` (`#E8ECF1`) +- Border radius: 6px +- Padding: 9px 19px +- Height: 40px +- Hover: background `gray-50` (`#F6F9FC`), border darkens to `gray-200` +- Active: background `gray-100`, border `charcoal` +- Focus: 3px ring in `purple-400` + +**`button-ghost`** — Inline text button + +- Background: transparent +- Text: `purple-600` (`#635BFF`) +- Typography: `button-md` +- Border: none +- Padding: 4px 8px +- Height: auto +- Hover: text `purple-500`, faint `purple-50` background +- Active: text `purple-600`, background `purple-100` + +**`button-dark`** — CTA on dark surfaces + +- Background: `#FFFFFF` +- Text: `navy-900` (`#0A2540`) +- Typography: `button-md` +- Border radius: 6px +- Padding: 10px 20px +- Height: 40px +- Hover: background `gray-50` +- Active: background `gray-100` + +**`button-disabled`** + +- Background: `gray-50` (`#F6F9FC`) +- Text: `ash` (`#8792A2`) +- Border: 1px solid `gray-100` +- Cursor: not-allowed +- No hover or active states + +### Cards + +**`card-default`** — Standard content card + +- Background: `#FFFFFF` +- Border: 1px solid `gray-100` (`#E8ECF1`) +- Border radius: 8px +- Padding: 24px +- Shadow: `0 2px 4px rgba(10,37,64,0.04), 0 4px 16px rgba(10,37,64,0.06)` +- Hover: shadow deepens to `0 4px 8px rgba(10,37,64,0.06), 0 8px 24px rgba(10,37,64,0.08)`, subtle translateY(-1px) +- Transition: 200ms ease on box-shadow and transform + +**`card-elevated`** — Featured/highlight card + +- Background: `#FFFFFF` +- Border: 1px solid `gray-100` +- Border radius: 8px +- Padding: 32px +- Shadow: `0 4px 8px rgba(10,37,64,0.06), 0 8px 24px rgba(10,37,64,0.08)` +- Used for pricing featured tier, primary feature showcase + +**`card-dark`** — Card on dark surfaces + +- Background: `navy-800` (`#1A2E4A`) +- Border: 1px solid `dm-hairline` (`rgba(255,255,255,0.08)`) +- Border radius: 8px +- Padding: 24px +- Shadow: `0 4px 16px rgba(0,0,0,0.2)` +- Text: `on-dark` (`#FFFFFF`) + +**`card-pricing`** — Pricing tier card + +- Background: `#FFFFFF` +- Border: 1px solid `gray-100` +- Border radius: 12px +- Padding: 32px +- Shadow: `0 2px 4px rgba(10,37,64,0.04), 0 4px 16px rgba(10,37,64,0.06)` + +**`card-pricing-featured`** — Recommended pricing tier + +- Same as `card-pricing` but: +- Border: 2px solid `purple-600` (`#635BFF`) +- Shadow: `0 4px 16px rgba(99,91,255,0.12), 0 8px 32px rgba(99,91,255,0.08)` + +### Inputs + +**`input-default`** — Standard text input + +- Background: `#FFFFFF` +- Text: `ink` (`#1A1F36`) +- Placeholder: `mute` (`#697386`) +- Typography: `body-md` (16px / 300) +- Border: 1px solid `gray-100` (`#E8ECF1`) +- Border radius: 6px +- Padding: 10px 12px +- Height: 40px +- Hover: border `gray-200` (`#C1C9D2`) +- Focus: border `purple-600`, 3px ring in `purple-100` (`#E8E5FF`) +- Error: border `error` (`#D84040`), ring in `error-soft` +- Disabled: background `gray-50`, text `ash`, border `gray-100`, cursor not-allowed +- Transition: 150ms ease on border-color and box-shadow + +**`input-dark`** — Input on dark surfaces + +- Background: `navy-800` (`#1A2E4A`) +- Text: `on-dark` +- Placeholder: `on-dark-mute` +- Border: 1px solid `dm-hairline` +- Focus: border `purple-500`, ring `rgba(123,115,255,0.2)` + +**`search-bar`** — Search input + +- Same as `input-default` but: +- Height: 44px +- Border radius: 8px +- Padding: 12px 16px 12px 40px (left padding accounts for magnifier icon) + +### Navigation + +**`nav-primary`** — Top navigation bar + +- Background: `#FFFFFF` with 1px bottom border in `gray-100` +- Height: 64px +- Layout: Logo at left, nav links centered, CTA + secondary link at right +- Nav link text: `body-sm` (14px / 300), color `charcoal` +- Nav link hover: color `ink`, subtle `gray-50` background pill +- Nav link active: color `purple-600`, weight 500 +- Sticky on scroll with a `0 2px 8px rgba(10,37,64,0.06)` shadow appearing at scroll offset + +**`nav-primary-dark`** — Top nav on dark sections + +- Background: `navy-900` (`#0A2540`) with 1px bottom border in `dm-hairline` +- Nav link text: color `on-dark-mute` +- Nav link hover: color `on-dark`, subtle background in `dm-surface` +- Nav link active: color `purple-500` + +**`nav-mobile`** — Mobile navigation + +- Hamburger icon at left, logo centered, CTA at right +- Drawer slides from right with `navy-900` background +- Drawer links stacked vertically with `body-lg` (18px / 300), color `on-dark` +- Divider lines in `dm-hairline` between link groups + +### Other Components + +**`badge`** — Inline status badge + +- Background: `purple-50` (`#F4F2FF`) +- Text: `purple-600` +- Typography: `caption` (12px / 400) +- Border radius: 9999px (full pill) +- Padding: 3px 10px +- Variants: `badge-success` (green), `badge-warning` (amber), `badge-error` (red), `badge-info` (cyan) — each using corresponding semantic-soft background and semantic text color + +**`code-block`** — Code well + +- Background: `navy-900` (`#0A2540`) +- Text: `on-dark` +- Typography: `code-md` (14px / JetBrains Mono) +- Border radius: 8px +- Padding: 20px 24px +- Tab strip at top: `code-sm` (12px), inactive tabs `on-dark-mute`, active tab `on-dark` with 2px `purple-600` bottom border + +**`divider`** — Section separator + +- Light surface: 1px solid `gray-100` (`#E8ECF1`) +- Dark surface: 1px solid `dm-hairline` (`rgba(255,255,255,0.08)`) + +**`tooltip`** — Hover tooltip + +- Background: `navy-900` +- Text: `on-dark` +- Typography: `body-sm` (14px / 300) +- Border radius: 6px +- Padding: 8px 12px +- Shadow: `0 4px 16px rgba(0,0,0,0.2)` +- Arrow: 6px CSS triangle in `navy-900` + +--- + +## 5. Layout Principles + +### Spacing Scale + +| Token | Value | Use | +|-------|-------|-----| +| `xxs` | 4px | Inline tight gaps, icon-to-label spacing | +| `xs` | 8px | Small internal gaps, badge padding | +| `sm` | 12px | Input padding, in-card element spacing | +| `md` | 16px | Default card padding (small cards), gutter spacing | +| `lg` | 24px | Standard card padding, section sub-spacing | +| `xl` | 32px | Pricing card padding, feature row gaps | +| `xxl` | 48px | Large feature section vertical padding | +| `xxxl` | 64px | Major section vertical padding | +| `section` | 96px | Full section rhythm on desktop | +| `band` | 128px | Hero band vertical padding | + +### Grid + +- **Max content width:** 1200px centered, with 24px side padding growing to 48px on ultrawide +- **Hero bands:** full-bleed up to 1440px content area +- **Card grids:** 3-up at desktop (400px per card), 2-up at tablet, 1-up at mobile +- **Feature rows:** 2-up split (copy left 45%, visual right 55%) collapsing to stacked at tablet +- **Footer:** 4-column link grid at desktop, 2-up at tablet, 1-up at mobile + +### Whitespace Philosophy + +Whitespace is the system's primary structural tool. Sections breathe at 96px on desktop with no decorative dividers — the white canvas carries from hero to footer with rhythm established by alternating `white` and `gray-50` bands. Inside cards, the system tightens to 16-24px so content reads as compact and precise. The white canvas never feels empty because the generous spacing and light typography create intentional breathing room, not vacancy. + +--- + +## 6. Depth & Elevation + +### Shadow System + +| Level | Shadow | Use | +|-------|--------|-----| +| 0 — flat | none | Canvas, inline text, footer | +| 1 — rest | `0 2px 4px rgba(10,37,64,0.04), 0 4px 16px rgba(10,37,64,0.06)` | Default cards at rest | +| 2 — hover | `0 4px 8px rgba(10,37,64,0.06), 0 8px 24px rgba(10,37,64,0.08)` | Card hover state, elevated panels | +| 3 — floating | `0 8px 16px rgba(10,37,64,0.08), 0 16px 48px rgba(10,37,64,0.12)` | Modals, dropdowns, popovers | +| 4 — purple glow | `0 4px 16px rgba(99,91,255,0.12), 0 8px 32px rgba(99,91,255,0.08)` | Featured pricing card, purple-accented elevated surfaces | + +### Surface Hierarchy + +| Level | Surface | Use | +|-------|---------|-----| +| 0 | `white` (`#FFFFFF`) | Page canvas, card backgrounds | +| 1 | `gray-50` (`#F6F9FC`) | Inset bands, alternating sections, table row stripes | +| 2 | `gray-100` (`#E8ECF1`) | Dividers, borders, subtle inset backgrounds | +| 3 | `navy-900` (`#0A2540`) | Dark sections, code wells, footer | +| 4 | `navy-800` (`#1A2E4A`) | Cards on dark, elevated dark surfaces | +| 5 | `navy-700` (`#2D3E54`) | In-well panels, dark input fills | + +Elevation on light surfaces comes from layered shadows with the `rgba(10,37,64,...)` tint — never pure black shadows, which would read too harsh against the warm white canvas. On dark surfaces, depth is built from the navy surface ladder, not shadows. + +--- + +## 7. Do's and Don'ts + +### Do + +- Use weight 300 as the default body weight. This is the single most important typographic decision in the system. +- Reserve `purple-600` (`#635BFF`) and the hero gradient for CTAs, links, and accent surfaces. The purple should feel like a signature, not wallpaper. +- Use `navy-900` (`#0A2540`) for dark sections rather than pure black (`#000000`). The navy carries warmth and brand coherence. +- Apply the layered shadow system (`rgba(10,37,64,...)`) instead of pure-black shadows. The slight blue tint matches the navy palette. +- Alternate between `white` and `gray-50` bands to create section rhythm without visible dividers. +- Set display type with negative letter-spacing proportional to size. Tighter at larger sizes, 0 at body scale. +- Use `JetBrains Mono` for all code surfaces — API examples, terminal blocks, inline code. Never use the sans-serif face for code. +- Give cards a subtle `translateY(-1px)` on hover to reinforce the shadow lift. The motion should feel like the card is breathing upward, not bouncing. +- Maintain 96px section rhythm on desktop. The whitespace is structural, not decorative. + +### Don't + +- Don't use weight 400 or 500 for body text. Weight 300 is the Stripe voice. Bumping weight breaks the system's characteristic lightness. +- Don't apply the purple gradient to large background surfaces or full-bleed sections outside of the hero. Purple is an accent, not a canvas. +- Don't use pure black (`#000000`) for text, shadows, or backgrounds. `ink` (`#1A1F36`) and `navy-900` (`#0A2540`) are warmer and brand-coherent. +- Don't add visible dividers between sections. Rhythm comes from alternating surface colors and generous spacing. +- Don't round corners beyond 12px on cards. The system stays in the 6-8px range for most elements. Pill-shaped cards break the precise aesthetic. +- Don't use colored shadows outside of the purple glow on featured elements. All other shadows use the `rgba(10,37,64,...)` tint. +- Don't pair purple with a secondary brand color. Purple is the only accent; semantic colors (green, amber, red) are functional, not decorative. +- Don't set code in the sans-serif face, even inline. Code always gets `JetBrains Mono`. +- Don't add drop shadows on dark surfaces. Elevation on dark is built from the surface-color ladder. + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Width | Key Changes | +|------|-------|-------------| +| ultrawide | 1920px+ | Content max-width holds at 1200px; outer gutters grow to 48-80px | +| desktop | 1280px | Default — 3-up card grids, 2-up feature rows, full nav | +| desktop-small | 1024px | Card grids 2-up; feature rows remain side-by-side but narrower | +| tablet | 768px | Card grids 1-up; feature rows stack; nav collapses to hamburger | +| mobile | 480px | Single-column everything; hero display-2xl scales 72px to 36px | +| mobile-narrow | 320px | Section padding tightens to 48px; card padding reduces to 16px | + +### Touch Targets + +- All buttons meet WCAG AA at minimum 40px height. `button-primary-lg` sits at 48px (AAA). +- `input-default` is 40px height. `search-bar` is 44px (AAA). +- Inline links and ghost buttons receive additional padding (8px minimum) to extend tap area without visual change. +- Nav links on mobile: 44px minimum tap height with full-width tap targets. + +### Collapsing Strategy + +- **Primary nav:** desktop horizontal cluster collapses to hamburger at 768px. Logo and primary CTA remain visible at all breakpoints. +- **Hero headline:** `display-2xl` scales 72px -> 56px -> 44px -> 36px across breakpoints. Letter-spacing reduces proportionally. +- **Feature rows:** 2-up side-by-side at desktop -> stacked at tablet with visual below copy. +- **Card grids:** 3-up -> 2-up at desktop-small -> 1-up at tablet. +- **Pricing tier grid:** 3-up -> stacked at tablet with featured tier remaining first. +- **Footer:** 4-column -> 2-up at tablet -> 1-up at mobile. +- **Section padding:** 96px desktop -> 64px tablet -> 48px mobile. +- **Code blocks:** horizontal scroll at mobile rather than reflow — code formatting must be preserved. + +### Animation Guidelines + +- **Card hover:** 200ms ease on box-shadow and transform. Subtle lift (1px) with shadow deepening. +- **Button hover:** 150ms ease on background-color and border-color. No transform. +- **Nav shadow on scroll:** 200ms ease on opacity appearing at scroll offset. +- **Page transitions:** 300ms ease-out on opacity. No slide or scale transitions on page-level elements. +- **Reduced motion:** All transitions collapse to 0ms; hover states apply instantly without motion. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/supabase.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/supabase.md new file mode 100644 index 00000000..a3ed3e00 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/supabase.md @@ -0,0 +1,407 @@ +# Supabase Design System + +> Dark emerald green theme. Code-first developer aesthetic. Dark surfaces with green accents. Technical documentation feel. + +--- + +## 1. Visual Theme & Atmosphere + +Supabase speaks to developers who live in terminals and editors. The visual language borrows from IDE dark modes: deep charcoal backgrounds, syntax-highlighted accents, and monospaced code blocks as first-class content. The emerald green brand color (`#3ECF8E`) punctuates an otherwise austere dark palette, signaling "active," "live," and "connected" -- a visual echo of a running Postgres instance. + +**Atmosphere keywords:** developer-tooling, terminal-dark, documentation-grade, surgical precision, open-source credibility. + +**Primary mode:** Dark. Light mode exists in the dashboard but is secondary. This design system defaults to dark. + +**Signature moments:** + +- Green-glow code blocks with syntax tokens that mirror the brand palette +- `$ supabase` CLI prompts woven into marketing pages +- Data tables with tight row heights (28px) that feel like a spreadsheet, not a marketing site +- Subtle green `rgba(62, 207, 142, 0.1)` flash on state changes + +--- + +## 2. Color Palette & Roles + +### Brand + +| Semantic Name | Hex | HSL | Role | +|----------------------|-----------|--------------------|-----------------------------------------| +| `brand-primary` | `#3ECF8E` | 153.1 60.2% 52.7% | Primary actions, links, active states | +| `brand-accent` | `#34B97D` | 152.9 56.1% 46.5% | Hover/pressed brand, emphasis accents | +| `brand-600` | `#84E0B7` | 153 59.5% 70% | Light brand for dark-surface highlights | +| `brand-500` | `#15593B` | 153.5 61.8% 21.6% | Brand on dark surfaces (muted green) | +| `brand-400` | `#0B3824` | 153.3 65.2% 13.5% | Deep brand background | +| `brand-300` | `#062618` | 153.8 69.6% 9% | Darkest brand surface | +| `brand-200` | `#041C11` | 152.5 75% 6.3% | Near-black brand tint | + +### Gray (Dark Mode) -- Core Neutral + +| Semantic Name | Hex | Role | +|--------------------|-----------|-------------------------------------| +| `gray-dark-100` | `#151515` | Deepest background (sidebar, dialog)| +| `gray-dark-200` | `#1C1C1C` | Default page/canvas background | +| `gray-dark-300` | `#222222` | Control background, surface 100 | +| `gray-dark-400` | `#282828` | Surface 200, muted background | +| `gray-dark-500` | `#2D2D2D` | Button default bg, overlay default | +| `gray-dark-600` | `#343434` | Border default, selection bg | +| `gray-dark-700` | `#3D3D3D` | Border strong, surface 400 | +| `gray-dark-800` | `#505050` | Border button hover, stronger border| +| `gray-dark-900` | `#6F6F6F` | Foreground muted | +| `gray-dark-1000` | `#7D7D7D` | Foreground lighter | +| `gray-dark-1100` | `#9F9F9F` | Foreground light | +| `gray-dark-1200` | `#ECECEC` | Foreground default (primary text) | + +### Slate (Dark Mode) -- Cool Neutral Alternative + +| Semantic Name | Hex | Role | +|--------------------|-----------|-------------------------------------| +| `slate-dark-100` | `#141617` | Cool deep background | +| `slate-dark-200` | `#1A1D1E` | Cool canvas background | +| `slate-dark-300` | `#1F2324` | Cool surface | +| `slate-dark-400` | `#26292B` | Cool muted surface | +| `slate-dark-500` | `#2A2E30` | Cool button/overlay background | +| `slate-dark-600` | `#313538` | Cool border | +| `slate-dark-700` | `#393E41` | Cool stronger border | +| `slate-dark-800` | `#4C5155` | Cool hover border | +| `slate-dark-900` | `#687076` | Cool muted foreground | +| `slate-dark-1000` | `#787E84` | Cool lighter foreground | +| `slate-dark-1100` | `#9AA0A5` | Cool light foreground | +| `slate-dark-1200` | `#EBECED` | Cool primary text | + +### Semantic Colors + +| Semantic Name | Hex | Role | +|----------------------|-----------|----------------------------| +| `destructive` | `#E54D2D` | Error states, delete, danger | +| `destructive-hover` | `#F0694F` | Destructive hover/pressed | +| `destructive-muted` | `#7E2215` | Destructive on dark surface | +| `warning` | `#FFB224` | Caution, pending states | +| `warning-hover` | `#F1A00C` | Warning hover/pressed | +| `secondary` | `#FFFFFF` | White accent, secondary actions | + +### Code Syntax Tokens (Dark) + +| Token | Hex | Usage | +|------------------|-----------|-------------------------------| +| `code-foreground`| `#FFFFFF` | Default code text | +| `code-keyword` | `#BDA4FF` | Language keywords | +| `code-constant` | `#3ECF8E` | Constants, functions, properties (matches brand) | +| `code-string` | `#FFCDA1` | String literals, expressions | +| `code-comment` | `#7E7E7E` | Comments | +| `code-highlight` | `#232323` | Active/highlighted line bg | + +--- + +## 3. Typography Rules + +### Font Stack + +| Purpose | Font | Fallback | +|------------|-------------------------------|--------------------------------| +| UI Body | Inter | system-ui, -apple-system, sans-serif | +| Code | `custom-font` (monospaced) | ui-monospace, SFMono-Regular, Menlo, monospace | +| Display | `custom-font` (variable) | Inter, system-ui, sans-serif | + +> Note: Supabase uses a proprietary custom font loaded via `@font-face` in weights 400 (Book) and 500 (Medium). For reproduction, use Inter as the closest open-source substitute for body text and JetBrains Mono or Fira Code for code. + +### Type Scale + +| Level | Size | Weight | Line-Height | Usage | +|----------------|-------------------------------|--------|-------------|------------------------------| +| `display-xl` | `clamp(2.5rem, 5vw, 4.5rem)` | 500 | 1.1 | Hero headlines | +| `display-lg` | `clamp(2rem, 4vw, 3rem)` | 500 | 1.15 | Section headlines | +| `h2` | `1.875rem` (30px) | 500 | 1.25 | Sub-section headers | +| `h3` | `1.25rem` (20px) | 500 | 1.3 | Card titles, panel headers | +| `body-lg` | `1.125rem` (18px) | 400 | 1.6 | Hero body, lead paragraphs | +| `body` | `0.875rem` (14px) | 400 | 1.5 | Default body text | +| `body-sm` | `0.8125rem` (13px) | 400 | 1.5 | Secondary text, captions | +| `code` | `0.875rem` (14px) | 400 | 1.6 | Inline code, code blocks | +| `label` | `0.75rem` (12px) | 500 | 1.4 | Labels, badges, tags | + +### Typography Rules + +- Never use italic for emphasis in UI text; use weight 500 instead. +- Monospace is reserved for code, CLI commands, API paths, and database identifiers. +- Code blocks use a darker background (`#1C1C1C`) than the page background. +- Headlines never use letter-spacing. Body text at small sizes may use `0.01em`. +- Avoid center-aligned text for paragraphs longer than two lines. + +--- + +## 4. Component Stylings + +### Buttons + +``` +Primary Button + bg: #3ECF8E + text: #1C1C1C + border-radius: 6px + padding: 8px 16px + font-weight: 500 + font-size: 14px + hover: bg #34B97D + active: bg #2DA06D, translateY(1px) + disabled: bg #2D2D2D, text #6F6F6F + +Secondary Button + bg: #2D2D2D + text: #ECECEC + border: 1px solid #343434 + border-radius: 6px + padding: 8px 16px + font-weight: 400 + hover: bg #343434, border-color #3D3D3D + active: bg #3D3D3D + disabled: bg #222222, text #6F6F6F, border-color #282828 + +Ghost Button + bg: transparent + text: #9F9F9F + border: none + padding: 8px 12px + hover: text #ECECEC, bg rgba(255,255,255,0.05) + active: bg rgba(255,255,255,0.08) + +Destructive Button + bg: #E54D2D + text: #FFFFFF + border-radius: 6px + hover: bg #F0694F + active: bg #D13B1C +``` + +### Cards + +``` +Surface Card + bg: #222222 (gray-dark-300) + border: 1px solid #343434 (gray-dark-600) + border-radius: 8px + padding: 16px (1rem) + hover: border-color #3D3D3D, subtle glow rgba(62,207,142,0.04) + +Featured Card + bg: #282828 (gray-dark-400) + border: 1px solid #3D3D3D (gray-dark-700) + border-radius: 8px + padding: 24px (1.5rem) + hover: border-color #3ECF8E at 0.3 opacity + +Code Card / Terminal Card + bg: #1C1C1C (gray-dark-200) + border: 1px solid #2D2D2D + border-radius: 8px + padding: 16px + font-family: monospace +``` + +### Inputs + +``` +Text Input + bg: #222222 (gray-dark-300) + border: 1px solid #343434 (gray-dark-600) + border-radius: 6px + padding: 8px 12px + text: #ECECEC + placeholder: #6F6F6F + height: 36px (default), 28px (compact) + focus: border-color #3ECF8E, ring rgba(62,207,142,0.3) + error: border-color #E54D2D, ring rgba(229,77,45,0.2) + disabled: bg #1C1C1C, text #6F6F6F +``` + +### Navigation + +``` +Top Nav + bg: rgba(21,21,21,0.8) with backdrop-blur + border-bottom: 1px solid #2D2D2D + height: 56px + text: #9F9F9F + active/hover text: #ECECEC + brand link: #3ECF8E + +Sidebar Nav + bg: #151515 (gray-dark-100) + width: 240px (collapsed: 48px) + item text: #9F9F9F + item hover: bg #222222, text #ECECEC + item active: bg #282828, text #3ECF8E, left-border 2px #3ECF8E + section label: #6F6F6F, uppercase, 12px, 500 weight, letter-spacing 0.05em + +Breadcrumb + text: #7D7D7D + separator: #6F6F6F + current: #ECECEC +``` + +### Badges / Tags + +``` +Default Badge + bg: #2D2D2D + text: #9F9F9F + border-radius: 9999px + padding: 2px 8px + font-size: 12px + +Brand Badge + bg: #15593B (brand-500) + text: #3ECF8E + border-radius: 9999px + +Destructive Badge + bg: #7E2215 + text: #E54D2D + border-radius: 9999px +``` + +### Data Table + +``` +Table + header bg: #1C1C1C + row bg: #222222 + row alt bg: #1C1C1C + row hover bg: #282828 + row height: 28px + header text: #9F9F9F, 12px, 500 + cell text: #ECECEC, 13px + cell padding: 8px horizontal + border: 1px solid #2D2D2D +``` + +--- + +## 5. Layout Principles + +### Spacing Scale + +| Token | Value | Usage | +|---------|---------|-------------------------------------| +| `xs` | 4px | Inline gaps, icon-to-label spacing | +| `sm` | 8px | Tight component padding | +| `md` | 16px | Default component padding, card gutters | +| `lg` | 32px | Section spacing, panel padding | +| `xl` | 64px | Major section separation | + +### Page Layout + +``` +Max content width: 1128px (--content-width-screen-xl) +Container max: 128rem (--container-site) +Page horizontal padding: 16px (mobile), 24px (tablet), 32px (desktop) +Sidebar width: 240px (expanded), 48px (collapsed) +Sidebar + content gap: 0 (sidebar shares border with content) +``` + +### Grid + +- Dashboard uses a sidebar + content layout (no CSS grid for the main split). +- Card grids: 12-column at `lg+`, 1-column on mobile. +- Gap between cards: 16px (`md`). +- Feature grids on marketing pages: 3 columns at `xl`, 2 at `md`, 1 at `sm`. + +### Content Rhythm + +- Headline to body: 12px gap. +- Body to next section: 32px (`lg`). +- Card internal: 16px padding, 12px between label and value. +- Documentation left-nav items: 4px vertical gap. + +--- + +## 6. Depth & Elevation + +Supabase uses minimal elevation. The dark theme creates depth through surface color steps, not drop shadows. + +### Surface Stack (dark to light) + +| Level | Background | Usage | +|-------|-------------|------------------------------| +| 0 | `#151515` | Sidebar, dialogs, overlays | +| 1 | `#1C1C1C` | Canvas, page background | +| 2 | `#222222` | Controls, inputs, card base | +| 3 | `#282828` | Hover states, featured cards | +| 4 | `#2D2D2D` | Button default, elevated bg | +| 5 | `#343434` | Active/hover button, borders | + +### Shadows + +```css +/* Rarely used. Prefer surface color step instead. */ +--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3); +--shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4); +--shadow-lg: 0 12px 32px rgba(0, 0, 0, 0.5); + +/* Brand glow -- used sparingly for emphasis */ +--glow-brand: 0 0 20px rgba(62, 207, 142, 0.15); +--glow-brand-strong: 0 0 40px rgba(62, 207, 142, 0.25); +``` + +### Overlays + +``` +Backdrop: rgba(0, 0, 0, 0.6) +Modal: bg #151515, border 1px solid #2D2D2D +Toast: bg #2D2D2D, border 1px solid #3D3D3D, slight shadow +``` + +--- + +## 7. Do's and Don'ts + +### Do + +- Use the brand green (`#3ECF8E`) for primary CTAs, active nav items, and positive states only. +- Use monospace for anything a developer would type or read in a terminal. +- Step through the gray-dark scale for elevation; avoid adding shadows where a darker background step suffices. +- Use `rgba(62, 207, 142, 0.1)` for subtle brand-tinted highlights (flash animations, hover accents). +- Keep data tables compact (28px row height). Developers expect density. +- Use `#BDA4FF` for code keywords and `#FFCDA1` for strings to create syntax-highlighted content blocks. +- Round corners at 6-8px. Not 0 (too harsh), not 16px (too bubbly for a dev tool). + +### Don't + +- Do not use the brand green as a background color for large surface areas. It is an accent, not a fill. +- Do not use pure white (`#FFFFFF`) for body text on dark backgrounds. Use `#ECECEC` instead; pure white creates excessive contrast. +- Do not add colored shadows or gradients to cards. Supabase surfaces are flat and distinguished by background value. +- Do not use rounded display fonts or playful typefaces. The tone is technical and precise. +- Do not center-align long-form prose. Left-align everything except hero headlines and short taglines. +- Do not use more than two font weights in a single view (400 and 500). +- Do not apply `border-radius: 9999px` to anything that is not a badge, tag, or pill button. +- Do not use the slate palette and gray palette interchangeably in the same view. Pick one neutral track. + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min Width | Layout Changes | +|----------|-----------|--------------------------------------| +| `sm` | 640px | Single column, full-width cards | +| `md` | 768px | Two-column card grids, sidebar hidden | +| `lg` | 1024px | Sidebar visible (collapsed), 2-3 col grids | +| `xl` | 1280px | Full sidebar, max content width | +| `2xl` | 1536px | Wider gutters, more whitespace | + +### Mobile Adaptations + +- **Sidebar:** Hidden below `lg`, replaced by hamburger menu with slide-out drawer (bg `#151515`). +- **Data tables:** Horizontally scrollable with sticky first column. Row height stays 28px. +- **Code blocks:** Horizontally scrollable. Never truncate or hide code content. +- **Navigation:** Top nav collapses to logo + hamburger + CTA button. +- **Hero:** Stack headline, body, and CTA vertically. Reduce display-xl to `2rem` at `sm`. +- **Card grids:** Shift from multi-column to single-column stacked cards. +- **Padding:** Page horizontal padding reduces from 32px to 16px at `sm`. + +### Dashboard-Specific + +- Sidebar collapses from 240px to 48px (icon-only) at `lg`, hides completely at `md`. +- Panel resizers maintain 2px grab area (`--panel`). +- Table column widths are user-adjustable; minimum column width is 80px. +- Mobile dashboard shows a bottom tab bar instead of sidebar. diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/tesla.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/tesla.md new file mode 100644 index 00000000..acd5a154 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/tesla.md @@ -0,0 +1,138 @@ +# Tesla Design System + +Radical subtraction. Cinematic full-viewport photography. Nearly zero UI chrome. Every element earns its place or is removed. + +--- + +## 1. Visual Theme & Atmosphere + +Pure black voids. Full-bleed hero imagery of vehicles shot at golden hour or in stark studio lighting. The product is the visual — UI recedes until needed. Pages feel like a film trailer: slow reveals, minimal text, maximum impact. No decorative elements. No gradients. No patterns. Silence as a design tool. + +**Keywords:** radical subtraction, cinematic, electric, powerful, silent, confident + +--- + +## 2. Color Palette & Roles + +| Name | Hex | Role | +|------|-----|------| +| Void | `#000000` | Primary background, dominant surface | +| Pure White | `#FFFFFF` | Primary text, divider lines, CTA text | +| Cool Gray | `#A6A6A6` | Secondary text, captions, disabled states | +| Steel | `#5C5C5C` | Tertiary text, subtle borders | +| Tesla Red | `#E82127` | Accent only — error states, rare highlights | +| Surface Dark | `#171717` | Card backgrounds, secondary surfaces | +| Surface Mid | `#222222` | Hover states, elevated surfaces | + +**Rule:** The palette is almost monochrome. Tesla Red is used no more than once per page. Cool Gray is the workhorse for anything that is not primary content. + +--- + +## 3. Typography Rules + +**Primary:** Universal Sans (or fallback: Inter, system sans-serif) + +| Element | Weight | Size | Tracking | Case | +|---------|--------|------|----------|------| +| Hero headline | 600 | clamp(48px, 6vw, 96px) | -0.03em | Title | +| Section headline | 500 | clamp(32px, 3vw, 56px) | -0.02em | Title | +| Body large | 400 | 20px | 0 | Sentence | +| Body | 400 | 16px | 0 | Sentence | +| Caption / spec | 400 | 13px | 0.02em | Title | +| CTA | 500 | 14px | 0.04em | Uppercase | + +**Rules:** +- Never use italic for emphasis. Use weight or size contrast. +- Hero headlines: one line, no wrapping. If it wraps, the copy is too long. +- All-caps tracking must be wide — never let uppercase text feel cramped. +- Line height for headlines: 1.05. For body: 1.5. + +--- + +## 4. Component Stylings + +### Buttons +- **Primary CTA:** White text on `#000000` with 1px white border, padding `14px 40px`, uppercase tracking 0.04em. On hover: background becomes `#FFFFFF`, text becomes `#000000`. +- **Ghost CTA:** White text, no border, underline on hover (2px, offset 4px). +- **No filled colored buttons.** No rounded pill buttons. No icon-only buttons without label. + +### Navigation +- Fixed top bar, `height: 56px`, transparent over hero images. +- Nav links: 13px uppercase, tracking 0.06em, white, no underline. +- No hamburger icon on desktop. No sidebars. + +### Cards +- Background: `#171717` or transparent over imagery. +- No border-radius (0px). No box-shadow. +- Content sits flush against edges. + +### Image Treatments +- Full-viewport hero images: `width: 100vw; height: 100vh; object-fit: cover`. +- No rounded corners on images. No visible image borders. +- Overlay gradient only when text legibility demands it: `linear-gradient(to top, #000 0%, transparent 60%)`. + +### Data / Specs +- Spec tables use Cool Gray labels, White values, no grid lines. +- Vertical spacing between spec rows: 24px. +- No alternating row colors. + +--- + +## 5. Layout Principles + +- **Full-viewport sections.** Each section occupies the entire viewport. No content peeks into the next section. +- **Extreme whitespace.** Between sections: 120px minimum. Between headline and body: 40px. +- **Centered single column** for headlines and CTAs. Max content width: 960px. +- **Asymmetric split** for feature sections: 60% image / 40% text, or vice versa. +- **No sidebars. No multi-column grids of cards.** The product is the grid. +- **Sticky scroll behavior:** as the user scrolls, the next vehicle image cross-fades in. Content overlays the imagery. + +--- + +## 6. Depth & Elevation + +- **No shadows.** Ever. Depth comes from layering full-bleed imagery, not from drop shadows. +- **No blur/glass effects.** The interface is crisp and opaque. +- Elevation hierarchy: + - Level 0: `#000000` background + - Level 1: `#171717` surface + - Level 2: `#222222` hover/elevated + - Level 3: `#FFFFFF` inverted CTA on hover +- Z-index is flat. Only the nav bar (z-50) and modals sit above content. + +--- + +## 7. Do's and Don'ts + +**Do:** +- Let photography do the heavy lifting — use the largest images possible +- Use generous whitespace to create breathing room around text +- Keep copy short: headlines under 6 words, body under 40 words per section +- Use animation only for scroll-triggered reveals (opacity 0 to 1, translateY) +- Make CTAs obvious through contrast, not decoration + +**Don't:** +- Add decorative icons, illustrations, or patterns +- Use rounded corners on any element (border-radius: 0) +- Apply drop shadows or elevation shadows +- Use more than one accent color per page +- Place text over busy image areas without a gradient overlay +- Use carousels — one hero image per viewport +- Add social media feeds, tickers, or scrolling banners + +--- + +## 8. Responsive Behavior + +| Breakpoint | Behavior | +|-----------|----------| +| < 640px | Single column, stacked. Hero images scale to `100vh` width-aware. Headline reduces to 32px. Nav collapses to hamburger. | +| 640–1024px | Single column. Side-by-side spec splits stack vertically. CTA buttons stretch full-width. | +| 1024–1440px | Asymmetric splits appear. Desktop nav visible. Spec tables go two-column. | +| > 1440px | Content max-width 960px, centered. Background imagery extends full-bleed. | + +**Mobile-specific rules:** +- Hero images may crop differently (focus on vehicle front, not full side profile) +- Bottom sticky CTA bar appears on mobile (transparent black, white text) +- Spec sections collapse into horizontal scroll cards only on mobile +- Touch targets: minimum 48x48px diff --git a/addons/officials/crew/designer/skills/design-system-picker/design-systems/vercel.md b/addons/officials/crew/designer/skills/design-system-picker/design-systems/vercel.md new file mode 100644 index 00000000..d049e858 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/design-systems/vercel.md @@ -0,0 +1,392 @@ +# Vercel Design System + +## 1. Visual Theme & Atmosphere + +Black and white precision. Every pixel is deliberate. The Vercel aesthetic communicates engineering rigor through extreme restraint -- no gradients on surfaces, no decorative illustration, no ornament. Information density is high but never cluttered because the typographic hierarchy is surgical. + +The signature element is the **blueprint grid** -- a barely-visible line or dot matrix pattern (5-10% opacity) that signals systematic thinking. It decorates hero sections and feature showcases, never competing with content. + +Atmospheric keywords: monochrome, precise, developer-tool, systematic, engineered, minimal-accent, high-contrast dark mode default. + +**Primary mode: Dark.** Light mode exists but dark is canonical. All color values below list dark first. + +--- + +## 2. Color Palette & Roles + +### Dark Mode (default) + +| Token | Hex | Role | +|-------|-----|------| +| `background-1` | `#000000` | Page and primary surface background | +| `background-2` | `#171717` | Secondary surface differentiation (use sparingly) | +| `color-1` | `#0A0A0A` | Component default background | +| `color-2` | `#111111` | Component hover background | +| `color-3` | `#1A1A1A` | Component active / pressed background; badge background | +| `color-4` | `#1A1A1A` | Default border | +| `color-5` | `#222222` | Hover border | +| `color-6` | `#2E2E2E` | Active / focus border | +| `color-7` | `#FAFAFA` | High-contrast background (primary buttons, inverted surfaces) | +| `color-8` | `#E5E5E5` | Hover state for high-contrast background | +| `color-9` | `#A1A1A1` | Secondary text and icons | +| `color-10` | `#EDEDED` | Primary text and icons | +| `blue-500` | `#0070F3` | Accent / link color (used minimally) | +| `red-500` | `#EE0000` | Error / destructive | +| `green-500` | `#00C853` | Success / online status | +| `amber-500` | `#F5A623` | Warning | + +### Light Mode + +| Token | Hex | Role | +|-------|-----|------| +| `background-1` | `#FFFFFF` | Page background | +| `background-2` | `#FAFAFA` | Secondary surface | +| `color-1` | `#F5F5F5` | Component default background | +| `color-2` | `#E5E5E5` | Component hover background | +| `color-3` | `#D4D4D4` | Component active background | +| `color-4` | `#E5E5E5` | Default border | +| `color-5` | `#D4D4D4` | Hover border | +| `color-6` | `#A3A3A3` | Active border | +| `color-7` | `#171717` | High-contrast background | +| `color-8` | `#0A0A0A` | Hover high-contrast background | +| `color-9` | `#737373` | Secondary text and icons | +| `color-10` | `#171717` | Primary text and icons | + +### Accent Usage Rule + +Accent blue (`#0070F3`) appears only on interactive text links, focus rings, and selected states. Never as a surface fill. The palette is 95% neutral; color is a signal, not decoration. + +--- + +## 3. Typography Rules + +**Font families:** +- `Geist Sans` -- all UI text, headings, body, labels, buttons +- `Geist Mono` -- code, monospace labels, inline code mentions + +**Font loading:** `font-family: 'Geist Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif` + +### Heading Scale + +| Style | Size | Weight | Letter-spacing | Usage | +|-------|------|--------|---------------|-------| +| Heading 72 | 72px | 600 | -2.88px | Marketing heroes only | +| Heading 64 | 64px | 600 | -2.56px | Marketing heroes | +| Heading 56 | 56px | 600 | -3.36px | Marketing heroes | +| Heading 48 | 48px | 600 | -1.92px | Section heroes | +| Heading 40 | 40px | 600 | -1.60px | Section heroes | +| Heading 32 | 32px | 600 | -1.28px | Dashboard headings, marketing subheadings | +| Heading 24 | 24px | 600 | -0.96px | Card titles, section labels | +| Heading 20 | 20px | 600 | -0.40px | Small section headings | +| Heading 16 | 16px | 600 | -0.32px | Compact headings | +| Heading 14 | 14px | 600 | -0.28px | Micro headings | + +All headings use `Geist Sans`. The aggressive negative letter-spacing at large sizes is critical to the Vercel look -- do not omit it. + +### Button Scale + +| Style | Size | Weight | Letter-spacing | Usage | +|-------|------|--------|---------------|-------| +| Button 16 | 16px | 500 | 0 | Largest CTA buttons | +| Button 14 | 14px | 500 | 0 | Default button | +| Button 12 | 12px | 500 | 0 | Tiny buttons inside input fields | + +### Label Scale + +| Style | Size | Weight | Letter-spacing | Usage | +|-------|------|--------|---------------|-------| +| Label 20 | 20px | 400 | 0 | Marketing text | +| Label 18 | 18px | 400 | 0 | Navigation items | +| Label 16 | 16px | 500 (strong) | 0 | Titles, differentiating from body | +| Label 14 | 14px | 500 (strong) | 0 | Most common; menus, list items | +| Label 14 Mono | 14px | 500 | 0 | Largest mono, pairs with >14 text | +| Label 13 | 13px | 400 | tabular | Secondary line next to labels; numbers | +| Label 13 Mono | 13px | 400 | 0 | Pairs with Label 14 | +| Label 12 | 12px | 500 (strong) | 0 | Tertiary text, caps (e.g. section headers) | +| Label 12 Mono | 12px | 400 | 0 | Smallest mono | + +### Copy Scale + +| Style | Size | Weight | Line-height | Usage | +|-------|------|--------|------------|-------| +| Copy 24 | 24px | 400 | 1.5 | Hero marketing body | +| Copy 20 | 20px | 400 | 1.5 | Hero marketing body | +| Copy 18 | 18px | 400 | 1.55 | Big quotes, feature descriptions | +| Copy 16 | 16px | 400 | 1.5 | Modals, spacious views | +| Copy 14 | 14px | 400 | 1.5 | Default body text (most common) | +| Copy 13 | 13px | 400 | 1.5 | Secondary text, space-constrained views | +| Copy 13 Mono | 13px | 400 | 1.5 | Inline code mentions | + +--- + +## 4. Component Stylings + +### Buttons + +**Primary (high-contrast):** +```css +background: var(--color-7); /* #FAFAFA dark / #171717 light */ +color: var(--background-1); /* #000000 dark / #FFFFFF light */ +border: none; +border-radius: 8px; +padding: 8px 16px; +font: 500 14px / 1 'Geist Sans'; +``` +- Hover: `background: var(--color-8)` (`#E5E5E5` dark / `#0A0A0A` light) +- Active: `transform: scale(0.98)` (subtle press) +- Focus: `outline: 2px solid var(--blue-500); outline-offset: 2px` + +**Secondary (ghost):** +```css +background: transparent; +color: var(--color-10); +border: 1px solid var(--color-5); +border-radius: 8px; +padding: 8px 16px; +font: 500 14px / 1 'Geist Sans'; +``` +- Hover: `background: var(--color-1)`; `border-color: var(--color-5)` +- Active: `background: var(--color-2)` + +**Tertiary (link-button):** +```css +background: none; +color: var(--color-9); +border: none; +padding: 0; +font: 500 14px / 1 'Geist Sans'; +text-decoration: underline; +text-underline-offset: 2px; +``` +- Hover: `color: var(--color-10)` + +### Cards + +```css +background: var(--color-1); +border: 1px solid var(--color-4); +border-radius: 12px; +padding: 24px; +``` +- Hover: `border-color: var(--color-5)` (no shadow shift, just border) +- Interactive card hover: subtle `border-color: var(--color-6)` + `background: var(--color-2)` + +No box-shadow on cards at rest. Elevation is communicated through border brightness, not shadow. + +### Inputs + +```css +background: var(--background-1); +border: 1px solid var(--color-4); +border-radius: 8px; +padding: 8px 12px; +font: 400 14px / 1.5 'Geist Sans'; +color: var(--color-10); +``` +- Placeholder: `color: var(--color-9)` +- Hover: `border-color: var(--color-5)` +- Focus: `border-color: var(--color-6)`; `box-shadow: 0 0 0 1px var(--color-6)` +- Error: `border-color: var(--red-500)` +- Disabled: `opacity: 0.4`; `cursor: not-allowed` + +### Navigation Bar + +```css +background: var(--background-1); +border-bottom: 1px solid var(--color-4); +height: 64px; +padding: 0 24px; +``` +- Nav items: `Label 14`, `color: var(--color-9)`, no underline +- Active item: `color: var(--color-10)`, `font-weight: 500` +- Hover: `color: var(--color-10)` +- Top nav is sticky, transparent until scroll then `background: var(--background-1)` with `backdrop-filter: blur(12px)` and `opacity: 0.9` + +### Badges / Status Indicators + +```css +background: var(--color-2); +color: var(--color-9); +border-radius: 9999px; /* pill shape */ +padding: 2px 8px; +font: 500 12px / 1 'Geist Sans'; +letter-spacing: 0.02em; +``` +- Variant: `Label 12` in ALL CAPS for section headers + +### Toggle / Switch + +```css +/* Track */ +width: 40px; height: 22px; +background: var(--color-3); +border: 1px solid var(--color-5); +border-radius: 9999px; +transition: background 150ms ease; + +/* Thumb */ +width: 16px; height: 16px; +background: var(--color-10); +border-radius: 50%; +/* Off: translateX(2px) */ +/* On: translateX(20px), track background: var(--blue-500) */ +``` + +--- + +## 5. Layout Principles + +### Spacing Scale (4px base unit) + +| Token | Value | Usage | +|-------|-------|-------| +| `space-1` | 4px | Tight gaps (icon-to-text) | +| `space-2` | 8px | Component internal padding | +| `space-3` | 12px | Input padding, small gaps | +| `space-4` | 16px | Default component padding | +| `space-5` | 20px | Section internal spacing | +| `space-6` | 24px | Card padding, nav padding | +| `space-7` | 32px | Between related sections | +| `space-8` | 40px | Section separators | +| `space-9` | 48px | Large section gaps | +| `space-10` | 64px | Page-level vertical rhythm | +| `space-11` | 80px | Hero internal spacing | +| `space-12` | 96px | Major section dividers | + +### Grid + +- Max content width: `1200px` (centered, auto margins) +- Marketing hero width: `1440px` +- Column count: 12 +- Gutter: `24px` (desktop), `16px` (tablet), `8px` (mobile) +- Page margin: `24px` (desktop), `16px` (mobile) + +### Whitespace Philosophy + +Whitespace is the primary tool for grouping. Vercel uses generous vertical spacing between sections (64-96px) and tight internal padding within components (8-16px). This creates a strong rhythm: dense functional clusters separated by wide breathing room. + +- Related elements: 4-8px apart +- Unrelated peer elements: 16-24px apart +- Section breaks: 64-96px apart +- Never use decorative dividers; spacing alone separates + +### Blueprint Grid (decorative) + +For hero sections and feature showcases: +```css +/* Line grid */ +background-image: + linear-gradient(rgba(255,255,255,0.05) 1px, transparent 1px), + linear-gradient(90deg, rgba(255,255,255,0.05) 1px, transparent 1px); +background-size: 64px 64px; + +/* Dot matrix */ +background-image: radial-gradient(circle, rgba(255,255,255,0.08) 1px, transparent 1px); +background-size: 24px 24px; +``` +- Maximum opacity: 8% (dark), 5% (light). If visible at first glance, reduce further. +- Grid spacing must align with layout grid (multiples of 8px). + +--- + +## 6. Depth & Elevation + +Vercel uses the Geist **Material** system. Elevation is encoded through border and shadow, not shadow alone. + +### Material Types + +| Type | Shadow | Border | Radius | Usage | +|------|--------|--------|--------|-------| +| `base` | none | 1px solid `var(--color-4)` | 12px | Resting cards, panels | +| `small` | `0 2px 4px rgba(0,0,0,0.3)` | 1px solid `var(--color-5)` | 12px | Raised cards | +| `large` | `0 8px 24px rgba(0,0,0,0.4)` | 1px solid `var(--color-5)` | 16px | Feature cards, highlighted surfaces | +| `tooltip` | `0 4px 12px rgba(0,0,0,0.5)` | 1px solid `var(--color-6)` | 8px | Tooltips, popovers | +| `menu` | `0 8px 24px rgba(0,0,0,0.5)` | 1px solid `var(--color-6)` | 12px | Dropdown menus | +| `modal` | `0 16px 48px rgba(0,0,0,0.6)` | 1px solid `var(--color-6)` | 16px | Dialog overlays | +| `fullscreen` | `0 0 0 rgba(0,0,0,0)` | none | 0 | Full-page takeovers | + +### Border-as-Elevation Rule + +At rest, surfaces have no shadow. The 1px border (`var(--color-4)`) alone separates them from the background. Shadow is reserved for floating elements (tooltips, menus, modals) that break the flat plane. This keeps the interface feeling **architectural** rather than layered. + +### Inner Highlight + +Some elevated surfaces add a subtle top-edge highlight: +```css +box-shadow: inset 0 1px 0 rgba(255,255,255,0.06); +``` +This simulates a light source from above and adds perceived depth without adding shadow weight. + +--- + +## 7. Do's and Don'ts + +### Do + +- Use negative letter-spacing on headings 32px and above -- it is the single most identifiable typographic signature +- Use `color-9` for secondary text, `color-10` for primary; the two-tier system is sufficient +- Rely on border brightness changes for hover states, not shadow changes +- Use the blueprint grid at hero scale only; never on dashboard or form surfaces +- Use `Geist Mono` for any code-adjacent text: deployment IDs, URLs, timestamps, file paths +- Keep button text short and imperative: "Deploy", "Continue", "Create" +- Use pill-shaped badges (`border-radius: 9999px`) for status; rounded rectangles for everything else +- Use `backdrop-filter: blur(12px)` for sticky nav overlays + +### Don't + +- Never add colored fills as surface backgrounds (no purple panels, no blue cards) +- Never use gradient backgrounds on UI surfaces; gradients only for marketing hero accents +- Never use rounded `border-radius` above 16px on containers (except pills at 9999px) +- Never mix multiple accent colors in the same view +- Never use decorative illustration or stock photography as section backgrounds +- Never apply shadow to resting cards -- border only +- Never use `font-weight: 300` (light) or below; minimum is 400 +- Never use ALL CAPS below 12px (becomes illegible) +- Never animate `width`, `height`, `top`, `left`, `margin`, or `padding`; use `transform` and `opacity` only +- Never use the blueprint grid pattern on surfaces with interactive form elements + +--- + +## 8. Responsive Behavior + +### Breakpoints + +| Name | Min-width | Columns | Gutter | Margin | +|------|-----------|---------|--------|--------| +| Mobile | 0 | 4 | 8px | 16px | +| Tablet | 768px | 8 | 16px | 24px | +| Desktop | 1024px | 12 | 24px | 24px | +| Wide | 1440px | 12 | 24px | auto (max-width: 1200px) | + +### Typography Scaling + +Headings 40px and above scale down one tier per breakpoint: + +| Desktop | Tablet | Mobile | +|---------|--------|--------| +| 72px | 56px | 40px | +| 56px | 48px | 32px | +| 48px | 40px | 32px | +| 40px | 32px | 24px | +| 32px | 24px | 20px | + +Headings 24px and below remain constant across breakpoints. + +Body copy stays at 14px on all screens. On mobile, `Copy 14` may shift to `Copy 13` in space-constrained layouts. + +### Layout Behavior + +- Navigation collapses to hamburger menu below 768px +- Cards stack vertically on mobile (single column); 2-column on tablet; 3-column on desktop +- Sidebars hide below 1024px; content takes full width +- Hero sections: text stacks vertically, visual above text on mobile +- Tables convert to card-list on mobile (each row becomes a card) +- `border-radius` stays constant across breakpoints (no rounding changes) +- Blueprint grid pattern: hide on mobile (below 768px) to reduce visual noise + +### Touch Adaptations + +- Minimum tap target: 44px x 44px +- Button padding increases on mobile: `12px 20px` (from `8px 16px`) +- Spacing between interactive list items: minimum 8px gap +- Bottom sheet replaces dropdown menus on mobile for better touch ergonomics diff --git a/addons/officials/crew/designer/skills/design-system-picker/scripts/pick.sh b/addons/officials/crew/designer/skills/design-system-picker/scripts/pick.sh new file mode 100755 index 00000000..3e02dfb2 --- /dev/null +++ b/addons/officials/crew/designer/skills/design-system-picker/scripts/pick.sh @@ -0,0 +1,75 @@ +#!/usr/bin/env bash +# design-system-picker — 根据风格描述从设计系统库中匹配最合适的设计系统 +# 用法: ./skills/design-system-picker/scripts/pick.sh "<风格描述>" +# 示例: ./skills/design-system-picker/scripts/pick.sh "科技感暗色主题" + +set -euo pipefail + +QUERY="${1:?用法: pick.sh <风格描述>}" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +SYSTEMS_DIR="${SCRIPT_DIR}/../design-systems" +INDEX_FILE="${SYSTEMS_DIR}/index.json" + +if [ ! -f "$INDEX_FILE" ]; then + echo "❌ 设计系统索引文件不存在: ${INDEX_FILE}" + exit 1 +fi + +echo "🔍 搜索风格: ${QUERY}" +echo "" +echo "=== 可用设计系统 ===" + +# 输出索引中的所有设计系统概要 +python3 -c " +import json, sys + +with open('${INDEX_FILE}') as f: + systems = json.load(f) + +query = '${QUERY}'.lower() +query_chars = set(query) + +results = [] +for s in systems: + # 计算匹配分数 + score = 0 + searchable = ' '.join(s['keywords'] + [s['name'], s['category'], s['description']]).lower() + for kw in s['keywords']: + if kw.lower() in query: + score += 3 + if s['category'] in query: + score += 2 + if s['name'].lower() in query: + score += 5 + # 通用匹配 + for word in query.split(): + if word in searchable: + score += 1 + results.append((score, s)) + +# 按分数排序 +results.sort(key=lambda x: -x[0]) + +print(f'共 {len(results)} 个设计系统可用\n') +for i, (score, s) in enumerate(results): + marker = '⭐' if score > 0 else ' ' + print(f\"{marker} [{i+1}] {s['name']} ({s['category']})\") + print(f\" 风格: {'、'.join(s['keywords'])}\") + print(f\" 主色: {s['colorPrimary']} | 暗色模式: {'✓' if s['darkMode'] else '✗'}\") + print(f\" 最适合: {s['bestFor']}\") + print(f\" 文件: design-systems/{s['file']}\") + if score > 0: + print(f\" 匹配度: {'★' * min(score, 5)}{'☆' * (5 - min(score, 5))}\") + print() + +# 推荐最佳匹配 +if results[0][0] > 0: + best = results[0][1] + print(f'💡 推荐首选: {best[\"name\"]} (匹配度最高)') + print(f' 使用方式: 读取 design-systems/{best[\"file\"]} 获取完整设计规范') +else: + print('💡 未找到高匹配结果，请根据上方列表选择或描述更具体的风格偏好') +" 2>/dev/null || { + # fallback: 如果 python3 不可用，直接输出列表 + cat "$INDEX_FILE" +} diff --git a/addons/officials/crew/designer/skills/init-workspace/SKILL.md b/addons/officials/crew/designer/skills/init-workspace/SKILL.md new file mode 100644 index 00000000..cbcbdb0f --- /dev/null +++ b/addons/officials/crew/designer/skills/init-workspace/SKILL.md @@ -0,0 +1,39 @@ +--- +name: init-workspace +description: 为单项设计任务创建标准目录结构和 brief 模板。每次接到设计需求时首先调用。 +metadata: + openclaw: + emoji: 📁 +--- + +# Init Workspace + +为每一项设计任务创建独立的文件夹和 brief 模板。 + +## 用法 + +```bash +./skills/init-workspace/scripts/init.sh <任务名> +``` + +示例： + +```bash +./skills/init-workspace/scripts/init.sh wiseflow-5-launch-poster +``` + +## 产出 + +在 `design_assets/` 下创建 `YYYY-MM-DD-<任务名>/` 目录，包含： + +``` +design_assets/YYYY-MM-DD-<任务名>/ +├── brief.md # 设计需求模板（待填写） +├── prompts.json # 生图参数记录 +├── source/ # 原始素材（参考图、品牌资产等） +└── output/ # 成品输出 +``` + +## 使用时机 + +每项设计任务开始前**必须**调用此脚本，确保所有产出有独立归档。 diff --git a/addons/officials/crew/designer/skills/init-workspace/scripts/init.sh b/addons/officials/crew/designer/skills/init-workspace/scripts/init.sh new file mode 100755 index 00000000..e54e7943 --- /dev/null +++ b/addons/officials/crew/designer/skills/init-workspace/scripts/init.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +# init-workspace — 为 designer 单项任务创建标准目录结构 +# 用法: ./skills/init-workspace/scripts/init.sh <任务名> +# 示例: ./skills/init-workspace/scripts/init.sh wiseflow-official-website + +set -euo pipefail + +TASK_NAME="${1:?用法: init.sh <任务名>}" + +# 任务目录命名: design_assets/YYYY-MM-DD-<任务名> +TODAY="$(date +%Y-%m-%d)" +TASK_DIR="design_assets/${TODAY}-${TASK_NAME}" + +# 确保设计资产根目录存在 +mkdir -p design_assets/references design_assets/brand + +# 创建任务目录（含子目录） +mkdir -p "${TASK_DIR}/source" "${TASK_DIR}/output" + +# 初始化 brief.md 模板 +if [ ! -f "${TASK_DIR}/brief.md" ]; then + cat > "${TASK_DIR}/brief.md" <<'BRIEF' +# 设计 Brief + +## 需求摘要 + + +## 产品类型与目标用户 + + +## 页面/界面清单 + + +## 功能范围 + + +## 风格方向 + + +## 品牌约束 + + +## 参考素材 + +BRIEF +fi + +echo "✅ 任务目录已创建: ${TASK_DIR}/" +echo " brief.md 模板已就绪，请填写后发送确认" diff --git a/addons/officials/crew/ir/AGENTS.md b/addons/officials/crew/ir/AGENTS.md index 88a0e7c5..2c9ece16 100644 --- a/addons/officials/crew/ir/AGENTS.md +++ b/addons/officials/crew/ir/AGENTS.md @@ -2,37 +2,33 @@ ## 角色概述 -你是 IR（投资人关系专员），组织的融资执行手。你支持三种工作模式，模式一为按需触发（对话驱动），模式二和模式三可配置为定时任务。 - -核心工作流程： -1. 与用户对话，搞清楚用户当前的融资需求（轮次、金额、目标投资人类型、材料状态等） -2. 根据需求执行对应模式 -3. 对需要持续跟踪的事项，更新 HEARTBEAT.md 并 spawn IT Engineer 更新配置 -4. 定期汇总进展 +你是 IR（投资人关系专员），老板的商业打磨合伙人和融资执行手。你围绕三大工作块开展工作：商业模式打磨、项目申报、投资人发掘与跟进。核心价值是长期积累 + 定期复盘迭代，不是一次性产出方案。 --- -## 工作模式识别 +## 工作块识别 -用户消息中如包含以下关键词，识别对应模式： +用户消息中如包含以下关键词，识别对应工作块： -| 关键词 | 模式 | -|--------|------| -| 商业梳理、BP、PPT、路演材料、Pitch Deck、融资材料 | **模式一：Deal Crafting** | -| 找投资人、VC、投资机构、投资人搜索、触达、联系投资人 | **模式二：Investor Hunting** | -| 进展、跟进、尽调、DD、投资人更新、关系维护 | **模式三：Relationship Tracking** | +| 关键词 | 工作块 | +|--------|--------| +| 商业模式、复盘、BP、路演材料、Pitch Deck、融资材料、商业梳理、经验教训、想法、思路 | **商业模式打磨** | +| 申报、比赛、创业大赛、项目申请、补贴、政策申报 | **项目申报** | +| 找投资人、VC、投资机构、投资人搜索、触达、联系投资人、进展、跟进、尽调、DD、关系维护 | **投资人发掘与跟进** | --- -## 模式一：Deal Crafting（商业梳理与 PPT 制作） +## 工作块一：商业模式打磨 -### Phase 1: 了解现状 +### Phase 1: 收集/更新商业素材 -逐项了解（已有明确答案的跳过）： -1. **公司基本信息**：公司名、一句话定位、核心产品/服务 -2. **融资状态**：当前轮次（天使/Pre-A/A/B）、目标金额、已有进展 -3. **材料状态**：已有 BP/PPT？需要新建还是更新？ -4. **风格偏好**：有参考模板或对标案例？想传达什么感觉？ +- 用户主动输入：想法、Idea、反思、经验教训、业务数据——随时记录到 MEMORY.md 的商业模式区域 +- 其他 Crew 传递：预留数据接口，后续 Crew 可推送业务数据（营收、用户增长、转化率等） +- 首次对话时，逐项了解（已有明确答案的跳过）： + 1. 公司基本信息：公司名、一句话定位、核心产品/服务 + 2. 融资状态：当前轮次、目标金额、已有进展 + 3. 材料状态：已有 BP/PPT？需要新建还是更新？ + 4. 风格偏好：有参考模板或对标案例？ ### Phase 2: 商业模式梳理 @@ -51,121 +47,143 @@ 输出给用户确认和修改。 -### Phase 3: PPT / Pitch Deck 制作 +### Phase 3: Council 复盘 + +遇到模糊商业判断时，调用 **council** 技能召集四方视角辩论： + +- **Strategist**：长期定位、竞争壁垒、商业闭环 +- **Skeptic**：挑战假设、质疑市场逻辑、提出最简替代 +- **Pragmatist**：执行速度、资源约束、现金流现实 +- **Risk Analyst**：下行风险、合规陷阱、失败模式 + +典型复盘场景： +- 当前商业模式的核心假设是否成立？ +- 先做营收验证还是先拿融资？ +- 某个市场细分值得投入还是应该放弃？ +- 复盘后业务方向是否需要调整？ + +建议复盘周期：每周或每两周一次，用户可调整。 -按用户指示调用 `ppt-maker` 技能或 `pitch-deck` 技能生成投资人路演 PPTX/html。 +### Phase 4: 复盘结论落地 -- 如果用户未明确指出，则简略介绍两个技能，请用户选择一个。一般而言，在线联系场景（邮件、微信冷接触）适合使用 `pitch-deck` 技能生成 html，对方手机或者微信直接打开就能看，零依赖；现场场景（路演、拜访）适合使用 `ppt-maker` 生成 ppt。 +- 将 Council 裁决摘要更新到 MEMORY.md 的商业模式复盘结论区域 +- 如结论影响融资策略或 BP 内容，触发材料更新 +- 如结论影响投资人目标，更新 HEARTBEAT.md 的搜索配置 -- 配图优先使用 `siliconflow-img-gen` 生成（16:9 封面/内容插图），`siliconflow-img-gen` 不可用时，尝试 `pexels-footage` 或 `pixabay-footage` +### Phase 5: BP / 融资路演材料制作 -### Phase 4: 版本管理 +BP 和 Pitch Deck 是商业模式的表达形式，不仅仅是融资工具。 + +按用户指示调用 `ppt-maker` 技能或 `pitch-deck` 技能： +- 在线联系场景（邮件、微信冷接触）→ `pitch-deck` 生成 html，零依赖直接打开 +- 现场场景（路演、拜访）→ `ppt-maker` 生成 ppt + +配图优先使用 `siliconflow-img-gen` 生成（16:9），不可用时尝试 `pexels-footage` 或 `pixabay-footage`。 + +### Phase 6: 版本管理 以后每次更新材料时： 1. 明确本次更新内容 2. 在 MEMORY.md 中记录版本变更 -3. 文件名加日期后缀避免覆盖（如 `pitch_20260512.pptx`） +3. 文件名加日期后缀避免覆盖 --- -## 模式二：Investor Hunting（投资人搜索与触达） +## 工作块二：项目申报 -### Phase 1: 明确目标 +### Phase 1: 发现申报机会 -**必须问到**： -- 目标投资人类别：天使投资人 / VC / PE / CVC（企业战投） / 家族办公室 -- 偏好领域：投资人是否聚焦某个行业/赛道 -- 地域偏好：国内 / 海外 / 不限 -- 本轮目标金额 +使用 `smart-search` 搜索创业比赛/项目申请/政府补贴信息： +- 搜索关键词："创业大赛"、"项目申报"、"政府补贴"、"孵化器"、"加速器"等 +- 按用户指定的领域和地域过滤 -### Phase 2: 搜索投资人 +### Phase 2: 筛选与评估 -使用 `smart-search` 在各平台搜索潜在投资人/机构： +对搜索结果进行筛选： +- 与用户确认目标项目 +- 评估匹配度（公司阶段、领域、地域要求） +- 评估准备材料清单和所需时间 -| 渠道 | 方法 | -|------|------| -| 投资数据库 | 搜索 IT桔子、企查查、天眼查等公开信息 | -| 社交媒体 | 搜索小红书/微博/领英上的投资人内容 | -| 行业报道 | 搜索近期融资新闻中的领投/跟投机构 | -| 竞对追踪 | 搜索竞品融资记录中的参投方 | +### Phase 3: 去重检查 -使用 `browser-guide` 在浏览器中访问关键页面获取详细信息。 +```bash +./skills/ir-record/scripts/check-application.sh --name <项目名> [--organizer <主办方>] +``` +如果 `{"exists": true}`，则提醒用户已申报过，避免重复。 -### Phase 3: 投资人筛选 +### Phase 4: 准备申报材料 -对搜索结果进行分析，输出结构化筛选表： +参照 `investor-materials` 技能逻辑，按申报要求定制材料： +- 商业计划书 / 项目介绍 +- 财务数据 / 团队信息 +- 附件材料 -| 维度 | 说明 | -|------|------| -| 机构/姓名 | 投资人/机构全称 | -| 类型 | 天使/VC/PE/CVC | -| 管理规模 | 基金规模或投资能力 | -| 投资阶段 | 偏好的轮次 | -| 投资领域 | 偏好的行业/赛道 | -| 已投案例 | 相关领域知名案例 | -| 匹配度 | 高/中/低，附理由 | -| 联系方式 | 邮箱/领英/其他 | +### Phase 5: 在线填报 -将筛选结果发用户确认。 +调用 **web-form-fill** 技能执行完整填报流程： +1. 先浏览全表单，搜集所有字段要求，写入 markdown +2. 根据已有资料填写 markdown，缺失信息问用户 +3. 打开浏览器逐页填报，使用 CDP `Input.insertText` 确保框架受控组件正确写入 +4. 切页前必须暂存，最终提交由用户确认 -### Phase 4: 首轮接触 +注意申报数量限制，提醒用户。 -用户确认目标投资人名单后： -1. 撰写接触话术（简短、专业、突出差异化） -2. 话术发用户确认 -3. 通过 `email-ops` 发送邮件，或通过 `xhs-interact` 在社交媒体上私信 -4. 每次接触后用 `ir-record` 记录 +### Phase 6: 记录申报 -**重要**：首次接触的投资人信息（机构、姓名、联系方式、接触内容）必须立即用 `ir-record` 记入数据库。 +```bash +./skills/ir-record/scripts/record-application.sh \ + --name <项目名> --type \ + --organizer <主办方> --deadline --status submitted \ + --notes <备注> +``` -### Phase 5: 写入配置 +--- -如需定时持续搜索： -1. 参照 `HEARTBEAT_TEMPLATE.md` 写入 HEARTBEAT.md -2. spawn IT Engineer 更新 heartbeat 配置 -3. 校验`email-ops`技能所需的环境变量是否齐全，如果不齐全告知用户，请用户提供相关信息后spawn IT Engineer，将环境变量写入 OFB_ENV.md 中记录的环境变量文件，之后重启 openclaw gateway。 +## 工作块三：投资人发掘与跟进 ---- +### Phase 1: 明确目标 -## 模式三：Relationship Tracking（投资人关系维护） +**必须问到**： +- 目标投资人类别：天使投资人 / VC / PE / CVC / 家族办公室 +- 偏好领域：投资人是否聚焦某个行业/赛道 +- 地域偏好：国内 / 海外 / 不限 +- 本轮目标金额 -### 核心功能 +### Phase 2-5: 委托 investor-hunting 技能执行 -管理和跟踪所有已接触投资人的进展状态。 +调用 **investor-hunting** 技能，按以下流程执行： +- Step 2: 逐渠道搜索（投资数据库、融资新闻、竞品融资记录、社交平台） +- Step 3: 逐投资人判定匹配度 → ir-record 去重记录 +- Step 4: 汇总报告 + 可选触达（investor-outreach 撰写话术 → 用户确认 → email-ops/xhs-interact 发送） -### 日常操作 +### Phase 6: 关系跟踪 **查看进度摘要**： ```bash -bash ./skills/ir-record/scripts/query-progress.sh +./skills/ir-record/scripts/query-progress.sh ``` -输出所有投资人的当前状态和最近接触记录。 **记录新进展**： -收到用户关于某投资人的新消息时（如"XX 机构约了下周 call"、"YY 投资人要了 BP"），立即用 `ir-record` 记录。 - -### 状态机 - -投资人从接触到完成的过程： +收到用户关于某投资人的新消息时，立即用 ir-record 记录。 +**状态机**： ``` -已接触 → 已发BP → 会议中 → 尽调中 → TS谈判 → 已投资 - ↓ ↓ ↓ ↓ - 放弃 放弃 放弃 放弃 +new → contacted → bp_sent → meeting → dd → ts → invested + ↓ ↓ ↓ ↓ ↓ ↓ +passed passed passed passed passed passed ``` **自动提醒**： -- 每次 HEARTBEAT 触发时，检查是否有超过 7 天未跟进的投资人 +- HEARTBEAT 触发时，检查是否有超过 7 天未跟进的投资人 - 主动提醒用户是否需要继续跟进 -### 联系人脉分析 - -定期使用 `social-graph-ranker` 分析投资人网络中可能的热心引荐人。 +**联系人脉分析**： +- 使用 `social-graph-ranker` 分析投资人网络中可能的热心引荐人 +- 使用 `connections-optimizer` 发现 warm intro 路径 -使用 `connections-optimizer` 发现可经由已有人脉 warm intro 的投资人路径。 - ---- +### Phase 7: 写入配置 -## sessions_spawn 规范 - -> 禁止传入 `streamTo` 参数 —— 在 subagent 模式下该参数不支持。spawn 时只传 agentId 和 task 内容即可。 +如需定时持续搜索： +1. 参照 `HEARTBEAT_TEMPLATE.md` 写入 HEARTBEAT.md +2. spawn IT Engineer 更新 heartbeat 配置 +3. 校验 `email-ops` 技能所需环境变量是否齐全 diff --git a/addons/officials/crew/ir/ALLOWED_COMMANDS b/addons/officials/crew/ir/ALLOWED_COMMANDS index 8872328b..70c73802 100644 --- a/addons/officials/crew/ir/ALLOWED_COMMANDS +++ b/addons/officials/crew/ir/ALLOWED_COMMANDS @@ -1,8 +1,12 @@ -python3 ./skills/cold-outreach/scripts/send_email.py +./skills/ir-record/scripts/init-db.sh +./skills/ir-record/scripts/check-investor.sh +./skills/ir-record/scripts/record-investor.sh ++./skills/ir-record/scripts/update-status.sh +./skills/ir-record/scripts/check-contact.sh +./skills/ir-record/scripts/record-contact.sh +./skills/ir-record/scripts/query-progress.sh ++./skills/ir-record/scripts/query-stale.sh ++./skills/ir-record/scripts/check-application.sh ++./skills/ir-record/scripts/record-application.sh ++./skills/ir-record/scripts/query-applications.sh +sqlite3 diff --git a/addons/officials/crew/ir/BOOTSTRAP.md b/addons/officials/crew/ir/BOOTSTRAP.md index 1520be3f..0e6933b2 100644 --- a/addons/officials/crew/ir/BOOTSTRAP.md +++ b/addons/officials/crew/ir/BOOTSTRAP.md @@ -1,21 +1,40 @@ -# Bootstrap +# IR Bootstrap -This is a pre-configured crew workspace. Review these files at startup: +This one-time bootstrap collects the business and financing context before IR work starts. If this crew is being enabled through Main Agent and has no direct work channel yet, Main Agent may ask these questions on behalf of this crew and write the answers into the crew workspace. -- **SOUL.md** — Role definition, core responsibilities, and autonomy level -- **AGENTS.md** — Workflows and operating procedures -- **MEMORY.md** — Background context and historical records -- **IDENTITY.md** — Name and persona -- **USER.md** — Assumptions about who you are serving -- **TOOLS.md** — Available tools, usage rules, and required environment variables +## Step 1: Company & Financing Context -## First-Run Checklist +Collect (skip items the user already has clear answers for): -On first startup: -1. Check `SILICONFLOW_API_KEY` is set → required for PPT AI image generation -2. For investor email outreach: check SMTP env vars are set (`SMTP_SERVER`, `SMTP_USER`, `SMTP_PASSWORD`) +1. **Company basics**: company name, one-line positioning, core product/service +2. **Financing status**: current round, target amount, existing progress +3. **Material status**: does the user already have a BP/PPT? Need to create new or update existing? +4. **Style preferences**: any reference templates or benchmark cases for investor materials? + +## Step 2: Investor Outreach Readiness + +Ask: + +- Is SMTP configured for investor email outreach? If not, explain that email contact mode will be unavailable until SMTP is set up. +- Does the user want to start with just商业模式打磨 (no outreach yet), or jump straight to investor search? + +## Step 3: Environment Verification + +On first startup, check and report: + +1. `SILICONFLOW_API_KEY` is set → required for PPT AI image generation +2. For investor email outreach: check SMTP env vars (`SMTP_SERVER`, `SMTP_USER`, `SMTP_PASSWORD`) 3. Verify `sqlite3` is available: `which sqlite3` 4. Create output directories: `mkdir -p db output` -5. Initialize the investor database: `bash ./skills/ir-record/scripts/init-db.sh` +5. Initialize the investor database: `./skills/ir-record/scripts/init-db.sh` If SMTP is not configured, investor email contact mode is unavailable but all other modes work fully. + +## Completion + +After bootstrap is complete: + +1. Update `MEMORY.md` with company/financing background and SMTP status. +2. Update `USER.md` with organization info (replace `<待填充>` placeholder). +3. Delete `BOOTSTRAP.md` from the runtime workspace. +4. Suggest the next step, such as starting a商业模式梳理 session or setting up investor search criteria. diff --git a/addons/officials/crew/ir/BUILTIN_SKILLS b/addons/officials/crew/ir/BUILTIN_SKILLS index 8e24529b..ac54fa09 100644 --- a/addons/officials/crew/ir/BUILTIN_SKILLS +++ b/addons/officials/crew/ir/BUILTIN_SKILLS @@ -3,10 +3,13 @@ browser-guide smart-search ppt-maker pitch-deck -cold-outreach email-ops xhs-interact social-graph-ranker connections-optimizer -council ir-record +council +investor-hunting +investor-materials +investor-outreach +market-research diff --git a/addons/officials/crew/ir/DENIED_SKILLS b/addons/officials/crew/ir/DENIED_SKILLS index 21efff5e..52d370bd 100644 --- a/addons/officials/crew/ir/DENIED_SKILLS +++ b/addons/officials/crew/ir/DENIED_SKILLS @@ -3,5 +3,5 @@ gh-issues coding-agent rss-reader -login-manager -wx-mp-hunter +# 闲鱼/TTS 技能（IR 不需要） +xianyu-ops diff --git a/addons/officials/crew/ir/HEARTBEAT.md b/addons/officials/crew/ir/HEARTBEAT.md index e433a5fe..ebc2b270 100644 --- a/addons/officials/crew/ir/HEARTBEAT.md +++ b/addons/officials/crew/ir/HEARTBEAT.md @@ -2,7 +2,9 @@ ## 执行约束 -1. **无时间限制**：HEARTBEAT 触发后必须执行完清单全部内容 +## 执行约束 + +1. **无时间限制**：HEARTBEAT/cron 触发后必须执行完清单全部内容 2. **遇到技术故障时**： - 先尝试关闭并重启浏览器 - 仍不解决 → spawn IT Engineer 协助 diff --git a/addons/officials/crew/ir/IDENTITY.md b/addons/officials/crew/ir/IDENTITY.md index 8a195d28..1496aec5 100644 --- a/addons/officials/crew/ir/IDENTITY.md +++ b/addons/officials/crew/ir/IDENTITY.md @@ -4,10 +4,10 @@ IR（投资人关系专员） ## Role -代表公司对接投资人群体——帮助老板梳理商业模式、制作投资人路演材料、搜索和筛选潜在投资人、管理首轮接触和后续关系跟踪。 +帮老板打磨商业模式、申报项目、发掘和跟进投资人的融资合伙人。 ## Personality -专业、审慎、善于结构化表达，沟通简洁精准。在对外交流中保持正式得体，在内部与老板对话时务实直接。对融资节奏有判断力，能在合适时机推进合适深度的接触。 +专业、审慎、善于结构化表达，沟通简洁精准。善于复盘和迭代，鼓励持续积累。在对外交流中保持正式得体，在内部与老板对话时务实直接。对融资节奏有判断力，能在合适时机推进合适深度的接触。 ## Emoji 💼 diff --git a/addons/officials/crew/ir/MEMORY.md b/addons/officials/crew/ir/MEMORY.md index 0b517184..03987880 100644 --- a/addons/officials/crew/ir/MEMORY.md +++ b/addons/officials/crew/ir/MEMORY.md @@ -2,49 +2,10 @@ ## 用户与公司信息 -（首次使用后由 IR 在此记录） - -- 公司名称：（待记录） -- 一句话定位：（待记录） -- 核心产品/服务：（待记录） -- 当前融资轮次：（待记录） -- 目标融资金额：（待记录） -- 已有投资人/机构：（待记录） - -## 融资材料版本 - -（由 IR 维护） - -| 日期 | 文件名 | 版本说明 | 状态 | -|------|--------|---------|------| -| | | | | - -## 投资人 Pipeline 摘要 - -（由 IR 维护，每次关注此表即可快速了解全局进展） - -| 投资人/机构 | 类型 | 状态 | 最近接触日期 | 下一步行动 | -|------------|------|------|-------------|-----------| -| | | | | | - -## 模式二：Investor Hunting 历史 - -（由 IR 维护） - -| 日期 | 搜索渠道 | 搜索关键词 | 发现数量 | 匹配数量 | 备注 | -|------|---------|-----------|---------|---------|------| -| | | | | | | - -## 模式三：Relationship Tracking 历史 - -（由 IR 维护） - -| 日期 | 投资人 | 进展摘要 | 下一步 | 截止日期 | -|------|--------|---------|--------|---------| -| | | | | | + ## 技术环境备注 -- SMTP 配置状态：（待记录） +- SMTP 配置状态：（由 BOOTSTRAP 检测写入） - 数据库位置：`./db/ir_record.db` - PPT 输出目录：`./output/` diff --git a/addons/officials/crew/ir/SOUL.md b/addons/officials/crew/ir/SOUL.md index 751415a5..8c3f4b85 100644 --- a/addons/officials/crew/ir/SOUL.md +++ b/addons/officials/crew/ir/SOUL.md @@ -2,24 +2,31 @@ ## 身份定位 -你是组织内部的 **Investor Relations（投资人关系专员）**，直接服务 boss（用户），代表公司与投资人群体对接。 +你是组织内部的 **Investor Relations（投资人关系专员）**，直接服务 boss（用户）。 -**核心定位**：老板的融资合伙人——老板提供方向，你负责商业模式梳理、材料制作、投资人搜索、首轮接触和关系跟踪。 +**核心定位**：老板的商业打磨合伙人和融资执行手——老板提供方向和实战素材，你负责长期积累、定期复盘迭代商业模式，并执行融资相关事务。 -## 三种工作模式 +**核心价值**：一个真正有意义的商业模式是在实践中打磨出来的，不是凭空设想的。IR 的最大价值是帮助用户长期积累经验教训和业务洞察，定期复盘，不断迭代商业模式。在这个地基上，才去执行具体事务。 -| 模式 | 说明 | 驱动方式 | -|------|------|---------| -| Deal Crafting | 与老板对话，梳理商业模式、制作/更新投资人路演材料（PPT/Pitch Deck） | 按需触发 | -| Investor Hunting | 搜索潜在投资人/投资机构，分析匹配度，发起首轮接触 | 按需触发 / Heartbeat | -| Relationship Tracking | 跟踪已接触投资人进展，记录会议纪要、尽调进度、下一步行动 | Heartbeat / 事件驱动 | +## 三大工作块 + +| 工作块 | 说明 | 驱动方式 | +|--------|------|---------| +| 商业模式打磨 | 记录创业思路/经验教训，定期复盘，梳理迭代商业模式，维护 BP，制作融资路演材料 | 按需触发 + 定期复盘 | +| 项目申报 | 上网填报创业比赛/项目申请，防重复，可定期总结 | 按需触发 | +| 投资人发掘与跟进 | 主动发掘和跟进投资人，国内场景主要在社交平台操作 | 按需触发 / Heartbeat | ## 行为准则 +### 核心原则 +- 商业模式是迭代出来的，不是一次写完的——鼓励用户持续输入，定期复盘 +- council 技能是商业模式决策的核心工具——遇到模糊判断时主动召集议会 +- 定期复盘是核心节奏——建议用户设定复盘周期（每周/每两周） + ### 对外行动原则 - 所有对外接触以公司名义进行，不得以个人身份行事 -- 融资材料、BP、财务数据等敏感信息发送前必须经用户确认（L2 确认） -- 投资人沟通话术需用户确认后发出（L2 确认） +- 融资材料、BP、财务数据等敏感信息发送前必须经用户确认 +- 投资人沟通话术需用户确认后发出 - 严格遵守信息保密原则，不对外泄露公司未公开数据 ### 初始化原则 @@ -31,7 +38,7 @@ - 定时任务执行时不打扰用户，完成后汇总报告 - 遇到技术故障先尝试自行恢复，恢复不了 spawn IT Engineer - 每条投资人接触之间保持适当时间间隔 -- 严格使用 ir-record 做投资人去重和进展跟踪 +- 严格使用 ir-record 做投资人和申报的去重与进展跟踪 ## 权限级别 diff --git a/addons/officials/crew/ir/TOOLS.md b/addons/officials/crew/ir/TOOLS.md index 2fb7f17a..ae3f1fac 100644 --- a/addons/officials/crew/ir/TOOLS.md +++ b/addons/officials/crew/ir/TOOLS.md @@ -20,17 +20,37 @@ ## 技能使用速查 +### 工作块一：商业模式打磨 + +| 技能 | 用途 | 触发场景 | +|------|------|---------| +| `council` | 四方视角结构化辩论 | 商业模式复盘、方向决策 | +| `investor-materials` | BP/商业计划书制作 | 商业梳理、材料准备 | +| `ppt-maker` | 生成投资人路演 PPTX | 现场路演 | +| `pitch-deck` | 生成 HTML 演示文稿 | 在线联系 | +| `market-research` | 市场规模、竞品分析 | 商业模式梳理 | + +### 工作块二：项目申报 + +| 技能 | 用途 | 触发场景 | +|------|------|---------| +| `web-form-fill` | 网络表单填报完整流程 | 在线填报（信息搜集→填写→暂存→提交确认） | +| `browser-guide` | 浏览器操作最佳实践 | 浏览器登录、验证码、懒加载等 | +| `smart-search` | 搜索申报机会 | 发现比赛/项目/补贴 | +| `investor-materials` | 申报材料准备 | 按申报要求定制 | +| `ir-record` | 申报去重与记录 | 防重复申报、进展查询 | + +### 工作块三：投资人发掘与跟进 + | 技能 | 用途 | 触发场景 | |------|------|---------| -| `ppt-maker` | 生成投资人路演 PPTX | Deal Crafting | -| `pitch-deck` | 生成 HTML 演示文稿（快速预览/邮件发送） | Deal Crafting | -| `browser-guide` | 浏览器操作最佳实践 | 投资人搜索、信息获取 | +| `investor-hunting` | 投资人搜索与筛选 | 主动发掘投资人 | +| `investor-outreach` | 触达话术撰写 | 首轮接触 | | `smart-search` | 搜索投资人/机构信息 | Investor Hunting | -| `cold-outreach` | 冷触达邮件发送 | Investor Hunting | -| `email-ops` | 一对一专业邮件联络 | Investor Hunting / Relationship | -| `xhs-interact` | 社交媒体投资人触达 | Investor Hunting | -| `social-graph-ranker` | 人脉网络中找热心引荐人 | Relationship Tracking | -| `connections-optimizer` | 发现 warm intro 路径 | Relationship Tracking | -| `council` | 复杂决策时做多方讨论 | 融资策略决策 | -| `ir-record` | 投资人数据库与进展跟踪 | 全部模式 | -| `summarize` | 会议纪要、信息摘要 | Relationship Tracking | +| `browser-guide` | 浏览器操作 | 信息获取 | +| `email-ops` | 一对一专业邮件联络 | 投资人邮件联系 | +| `xhs-interact` | 社交媒体投资人触达 | 社交平台触达 | +| `social-graph-ranker` | 人脉网络中找热心引荐人 | 关系跟踪 | +| `connections-optimizer` | 发现 warm intro 路径 | 关系跟踪 | +| `ir-record` | 投资人数据库与进展跟踪 | 全流程 | +| `summarize` | 会议纪要、信息摘要 | 关系跟踪 | diff --git a/addons/officials/crew/ir/USER.md b/addons/officials/crew/ir/USER.md index effa87bc..b01644c7 100644 --- a/addons/officials/crew/ir/USER.md +++ b/addons/officials/crew/ir/USER.md @@ -5,15 +5,16 @@ 你服务的是**组织的 boss**（即发出指令的用户）。 - 用户身份：公司决策者 / 创始人 / CEO -- 你的角色：他的融资合伙人——他负责公司战略和资源决策，你负责融资执行的各个环节 -- 组织信息（公司名称、业务介绍、融资历史等）<待填充> +- 你的角色：他的商业打磨合伙人和融资执行手——他负责战略决策和提供实战素材，你负责长期积累、定期复盘迭代商业模式，并执行融资相关事务 +- 组织信息（公司名称、业务介绍、融资历史等）<由 BOOTSTRAP 收集填充> ## What They Expect - **结构化**：商业模式梳理、投资人分析、进展报告——都要结构化呈现，方便快速决策 - **专业**：投资材料（BP/PPT/Pitch Deck）符合行业标准，商务沟通得体专业 -- **主动**：不等催，主动提醒下一步行动、即将到期的跟进事项 +- **主动**：不等催，定期提醒复盘、即将到期的申报、下一步行动 - **保密**：融资数据和投资人名单高度敏感，严格保密 +- **迭代**：商业模式不是一次写完的，鼓励持续输入，定期复盘打磨 ## Communication Guidelines @@ -21,3 +22,4 @@ - 分析结果（投资人筛选、匹配度、推荐接触顺序）以表格对比呈现 - PPT/材料创建前先确认大纲和风格方向 - 定期汇总进展，不逐条实时汇报 +- 用户随时分享的想法、经验教训及时记录到 MEMORY.md \ No newline at end of file diff --git a/addons/officials/crew/ir/openclaw_setting_sample.json b/addons/officials/crew/ir/openclaw_setting_sample.json index 277c9b3b..e04531a2 100644 --- a/addons/officials/crew/ir/openclaw_setting_sample.json +++ b/addons/officials/crew/ir/openclaw_setting_sample.json @@ -4,17 +4,20 @@ "pitch-deck", "browser-guide", "smart-search", - "cold-outreach", "email-ops", "xhs-interact", "social-graph-ranker", "connections-optimizer", - "council", "ir-record", + "council", + "investor-hunting", + "investor-materials", + "investor-outreach", + "market-research", "summarize" ], "subagents": { - "allowAgents": ["it-engineer", "designer"] + "allowAgents": ["it-engineer"] }, "heartbeat": { "every": "1h", diff --git a/addons/officials/crew/ir/skills/investor-hunting/SKILL.md b/addons/officials/crew/ir/skills/investor-hunting/SKILL.md new file mode 100644 index 00000000..c9d18bdc --- /dev/null +++ b/addons/officials/crew/ir/skills/investor-hunting/SKILL.md @@ -0,0 +1,114 @@ +--- +name: investor-hunting +description: 通过搜索渠道主动发掘潜在投资人/投资机构，筛选匹配度，去重记录，可选触达。参照 BD lead-hunting 模式，针对投资人场景定制。 +metadata: + openclaw: + emoji: 🔍 +--- + +# Investor Hunting 技能 + +通过搜索渠道主动发掘潜在投资人/投资机构，按匹配度筛选，去重记录到 ir-record，可选发起触达。 + +**依赖技能**：`smart-search`（构造搜索 URL）、`browser-guide`（浏览器操作）、`investor-outreach`（触达话术）、`email-ops`（邮件）、`ir-record`（去重记录） + +--- + +## 前置条件 + +执行前需确认 HEARTBEAT.md 中已配置以下信息： +- 目标投资人类别（angel/vc/pe/cvc）和关注领域 +- 搜索渠道列表及对应搜索关键词 +- 匹配度判定标准（投资阶段、领域、管理规模、已投案例等） +- 每次最大探索量 +- 反馈形式（列表报告 / Email 联系 / 社交平台触达） + +--- + +## 搜索渠道 + +| 渠道 | 方式 | 说明 | +|------|------|------| +| 投资数据库 | smart-search + browser | IT桔子、企查查、天眼查——搜索投资事件、机构列表 | +| 融资新闻 | smart-search | 搜索"XX轮融资"、"XX领投"——从新闻中提取参投方 | +| 竞品融资记录 | smart-search | 搜索竞品融资新闻，提取其投资人作为潜在目标 | +| 社交平台 | smart-search + browser | 微博/小红书/即刻——搜索投资人内容、创投圈讨论 | +| LinkedIn | browser-guide | 搜索投资人 profile（需登录） | + +--- + +## 执行流程 + +### Step 1: 准备工作 + +1. 读取 HEARTBEAT.md 获取当前配置（目标类别、渠道、关键词、判定标准、最大探索量） +2. 确保浏览器可用（遵循 browser-guide） +3. 初始化 ir-record 数据库（幂等）：`./skills/ir-record/scripts/init-db.sh` + +### Step 2: 逐渠道搜索 + +对 HEARTBEAT.md 中配置的每个渠道，按顺序执行： + +1. 使用 smart-search 技能构造该渠道的搜索 URL +2. 导航到搜索结果页，等待加载 +3. 收集搜索结果中的投资人/机构信息（最多取配置的最大探索量） + - 提取：姓名、机构、职位、关注领域、来源 URL + +### Step 3: 逐投资人判定 + +对每个搜索到的投资人/机构，按顺序执行： + +1. **去重检查**： + ```bash + ./skills/ir-record/scripts/check-investor.sh --name <姓名> --firm <机构名> + ``` + 如果 `{"exists": true}`，则跳过，继续下一个 + +2. **获取更多信息**（如搜索结果信息不足）： + - 导航到投资人/机构详情页（投资数据库 profile、LinkedIn 等） + - 读取投资偏好、已投项目、管理规模等信息 + +3. **匹配度判定**： + - 按 HEARTBEAT.md 中预设的判定标准，判断是否为潜在投资人： + - 投资阶段是否匹配（种子/天使/A轮/...） + - 关注领域是否与公司业务相关 + - 管理规模是否在目标范围 + - 已投案例是否有同类/相邻赛道 + - 判定为潜在投资人需给出明确理由和匹配度评分（high/medium/low） + +4. **记录到数据库**（不管是否符合标准）： + ```bash + ./skills/ir-record/scripts/record-investor.sh \ + --name <姓名> --type --firm <机构名> \ + --title <职位> --email <邮箱> --source <来源> \ + --focus-areas <关注领域> --match-score \ + --status new --notes <判定理由> + ``` + +5. **操作间隔**：每个投资人之间保持 30-60 秒间隔，避免平台风控 + +### Step 4: 汇总报告 + +1. 统计本批次结果：探索总数、符合数、跳过数（已记录） + +2. 列出所有符合标准的潜在投资人： + - 姓名、机构、职位、匹配度、关注领域、判定理由、来源 + +3. 按 HEARTBEAT.md 中配置的反馈形式执行： + - **列表报告**：仅汇总报告，不触达 + - **Email 联系**：对 high 匹配度的投资人，使用 investor-outreach 生成话术，经用户确认后用 email-ops 发送 + - **社交平台触达**：对 high 匹配度的投资人，通过社交平台私信触达（需用户确认） + +4. 使用 message 工具将汇总报告发送给用户 + +--- + +## 错误处理 + +| 情况 | 处理 | +|------|------| +| 渠道搜索结果为空 | 记录渠道名称，跳过，继续下一个 | +| 投资人详情页无法访问 | 记录"无法访问"后跳过，不阻塞流程 | +| 浏览器异常 | 等待 30 秒后继续；若仍不行，等 30 秒再试；关闭重开后仍报错则停止并反馈用户 | +| 平台风控/验证码 | 停止当前渠道操作，记录并继续下一个 | +| 持续错误 | spawn IT Engineer 协助排查，当前任务标记为部分完成 | diff --git a/addons/officials/crew/ir/skills/investor-materials/SKILL.md b/addons/officials/crew/ir/skills/investor-materials/SKILL.md new file mode 100644 index 00000000..7b0da4fd --- /dev/null +++ b/addons/officials/crew/ir/skills/investor-materials/SKILL.md @@ -0,0 +1,122 @@ +--- +name: investor-materials +description: > + 创建和更新融资路演材料：Pitch Deck、One-Pager、投资人备忘录、加速器申请、财务模型、资金用途表、里程碑计划。 + 当用户需要投资人面向的文档、财务预测、BP 更新、路演 PPT 时触发。 +metadata: + openclaw: + emoji: 📑 +--- + +# 融资材料制作 + +制作投资人面向的材料——数据一致、逻辑清晰、经得起质疑。 + +## 触发条件 + +- 创建或修改 Pitch Deck / 路演 PPT +- 撰写投资人备忘录或 One-Pager +- 构建财务模型、里程碑计划、资金用途表 +- 填写加速器/孵化器申请表 +- 需要多份融资材料之间保持数据一致 + +## 核心原则：单一信源 + +所有融资材料必须数据一致。起草前先确认或创建单一信源： + +| 信源项 | 说明 | +|--------|------| +| 牵引指标 | 用户数、营收、增长率等核心数据 | +| 定价与收入假设 | 单价、转化率、收入构成 | +| 融资规模与工具 | 融多少钱、什么结构（股权/可转债/SAFE） | +| 资金用途 | 分配比例和逻辑 | +| 团队信息 | 姓名、职位、背景（以最新为准） | +| 里程碑与时间线 | 关键节点和达成日期 | + +发现数据冲突时，**先停下来与用户确认，再继续起草**。 + +## 核心工作流 + +``` +1. 盘点已知事实，列出信源清单 +2. 识别缺失假设，向用户提问补全 +3. 确定材料类型（Pitch Deck / One-Pager / 财务模型 / 申请表） +4. 按对应模板起草，每处数据标注来源 +5. 交叉校验：每个数字是否与信源一致 +``` + +## 材料类型指引 + +### Pitch Deck（路演演示） + +推荐结构： + +1. 公司定位 + 切入点 +2. 问题 +3. 解决方案 +4. 产品 / Demo +5. 市场规模 +6. 商业模式 +7. 牵引力 +8. 团队 +9. 竞争与差异化 +10. 融资需求（Ask） +11. 资金用途 / 里程碑 +12. 附录 + +**制作方式**： +- 在线联系场景（邮件、微信冷接触）→ 调用 `pitch-deck` 生成 HTML，手机/微信直接打开 +- 现场路演/拜访场景 → 调用 `ppt-maker` 生成 PPTX +- 用户未指定时，简要介绍两种方式让用户选择 + +**配图**：优先使用 `siliconflow-img-gen`（16:9），不可用时尝试 `pexels-footage` 或 `pixabay-footage` + +### One-Pager / 投资人备忘录 + +- 一句话讲清公司做什么 +- 尽早展示牵引力和核心论据 +- 融资需求精确具体 +- 所有主张可验证 + +### 财务模型 + +必须包含： +- 明确的假设前提 +- 悲观/基准/乐观三种情景（当决策依赖假设时） +- 逐层收入逻辑（不要只给一个总数） +- 与里程碑挂钩的支出计划 +- 关键假设的敏感性分析 + +### 加速器申请 + +- 精确回答问题本身，不跑题 +- 优先展示牵引力、洞察和团队优势 +- 不用空泛夸大 +- 内部指标与 Deck 和模型保持一致 + +## 红线：绝不出现 + +- 无法验证的声明 +- 没有假设前提的模糊市场规模 +- 前后不一致的团队角色或头衔 +- 收入数学加不上的数字 +- 脆弱假设上的过度自信 + +## 质量门控 + +交付前检查： + +- [ ] 每个数字与当前信源一致 +- [ ] 资金用途和收入逻辑加总正确 +- [ ] 假设可见、不埋藏 +- [ ] 故事清晰，不靠空话撑场 +- [ ] 材料经得起合伙人级别的质疑 + +## 与其他技能协作 + +| 场景 | 配合技能 | +|------|---------| +| 商业模式复盘后更新材料 | `council`（复盘结论驱动材料迭代） | +| 投资人触达需要发送材料 | `email-ops` 发邮件，`investor-outreach` 写话术 | +| 搜索竞品/市场数据支撑材料 | `market-research` | +| 记录材料发送状态 | `ir-record` 更新投资人状态为 `bp_sent` | diff --git a/addons/officials/crew/ir/skills/investor-outreach/SKILL.md b/addons/officials/crew/ir/skills/investor-outreach/SKILL.md new file mode 100644 index 00000000..38c63cbb --- /dev/null +++ b/addons/officials/crew/ir/skills/investor-outreach/SKILL.md @@ -0,0 +1,115 @@ +--- +name: investor-outreach +description: > + 撰写投资人触达邮件、暖介绍请求、跟进邮件、投资人更新等融资沟通文案。 + 当用户需要向天使投资人、VC、战略投资人、加速器发起接触，或需要精简、个性化的投资人沟通文案时触发。 +metadata: + openclaw: + emoji: ✉️ +--- + +# 投资人触达 + +撰写投资人沟通文案——简短、具体、容易行动。 + +## 触发条件 + +- 给投资人写冷邮件 +- 起草暖介绍（Warm Intro）请求 +- 会议或无回复后的跟进 +- 融资过程中的投资人更新 +- 针对特定基金策略或合伙人偏好定制话术 + +## 核心规则 + +1. **每封外发邮件都必须个性化**——绝不发模板 +2. **降低对方行动门槛**——Ask 要具体、简单 +3. **用事实代替形容词**——数据 > 描述 +4. **简洁**——投资人每天看上百封邮件 +5. **绝不出海投文案**——每封邮件都应只能发给这一个投资人 + +## 语气与品牌 + +如果用户有品牌语气要求，先确认语气风格再起草。本技能专注投资人沟通的结构和 Ask 纪律，不另建独立的语气体系。 + +## 硬禁令 + +出现以下表达时，删除重写： + +- "希望与您交流" / "I'd love to connect" +- "很激动地分享" / "excited to share" +- 没有实质关联的泛泛基金赞美 +- 模糊的创始人形容词（"有激情"、"经验丰富"而无佐证） +- 哀求语气 +- 可以直接提问却用了软弱收尾 + +## 冷邮件结构 + +``` +1. 主题行：短且具体 +2. 开头：为什么找这个投资人（而非别人） +3. 主体：公司做什么、为什么是现在、有什么证据 +4. Ask：一个具体的下一步动作 +5. 签名：姓名、职位，必要时一个信用锚点 +``` + +## 个性化来源 + +至少引用以下一项： + +| 来源 | 示例 | +|------|------| +| 相关被投企业 | "注意到贵基金投了 X，我们解决的是同一产业链的 Y 环节" | +| 公开观点 | 某次演讲、文章、博客中的论点 | +| 共同人脉 | "经 Z 介绍" | +| 策略/市场匹配 | 清晰的产品-基金策略对应关系 | + +**如果缺少个性化信息，明确告知用户此草稿仍需补充个性化内容，不要假装已完成。** + +## 跟进节奏 + +| 时间 | 动作 | +|------|------| +| 第 0 天 | 首次发出 | +| 第 4-5 天 | 短跟进，附带一个新数据点 | +| 第 10-12 天 | 最终跟进，干净收尾 | + +12 天后不再继续跟进，除非用户要求更长序列。 + +## 暖介绍请求 + +让引荐人省心： + +- 说清为什么这个介绍是合适的 +- 附一段可转发的 blurb（100 字以内） +- blurb 格式：谁 + 做什么 + 关键数据点 + Ask + +## 会议后更新 + +包含： + +1. 会议讨论的具体内容 +2. 承诺提供的信息/材料 +3. 一个新的证明点（如有） +4. 明确的下一步 + +## 质量门控 + +交付前检查： + +- [ ] 内容真正个性化（不是模板换名字） +- [ ] Ask 明确具体 +- [ ] 证明点是具体事实，不是空话 +- [ ] 删掉了所有填充性赞美和软化语 +- [ ] 字数精简 + +## 与其他技能协作 + +| 场景 | 配合技能 | +|------|---------| +| 搜索投资人信息和被投企业 | `market-research`，`smart-search` | +| 投资人发掘后触达 | `investor-hunting`（搜索筛选后衔接触达） | +| 发送邮件 | `email-ops` | +| 社交媒体私信 | `xhs-interact` | +| 记录接触历史 | `ir-record`（用 `record-contact.sh` 记录，用 `update-status.sh` 更新状态为 `contacted`） | +| 投前调研基金策略 | `market-research`（基金尽调模式） | diff --git a/addons/officials/crew/ir/skills/ir-record/SKILL.md b/addons/officials/crew/ir/skills/ir-record/SKILL.md index ba211368..06cc6732 100644 --- a/addons/officials/crew/ir/skills/ir-record/SKILL.md +++ b/addons/officials/crew/ir/skills/ir-record/SKILL.md @@ -1,11 +1,11 @@ --- name: ir-record -description: 维护 IR（投资人关系专员）的 SQLite 追踪数据库，记录投资人档案和接触历史，避免重复接触，跟踪进展状态。 +description: 维护 IR 的 SQLite 追踪数据库，记录投资人档案、接触历史和项目申报，避免重复，跟踪进展。 --- # IR Record 技能 -在 `./db/ir_record.db` 中维护持久化 SQLite 数据库，供 IR 的三种工作模式使用。 +在 `./db/ir_record.db` 中维护持久化 SQLite 数据库，供 IR 三大工作块使用。 ## 数据库位置 @@ -13,7 +13,7 @@ description: 维护 IR（投资人关系专员）的 SQLite 追踪数据库， ./db/ir_record.db ``` -首次使用需先初始化：`bash ./skills/ir-record/scripts/init-db.sh` +初始化（幂等，可重复执行）：`./skills/ir-record/scripts/init-db.sh` --- @@ -26,19 +26,19 @@ description: 维护 IR（投资人关系专员）的 SQLite 追踪数据库， | id | INTEGER PRIMARY KEY AUTOINCREMENT | 自增主键 | | name | TEXT NOT NULL | 投资人姓名 | | type | TEXT NOT NULL | 投资人类别（angel/vc/pe/cvc/fo/other） | -| firm | TEXT | 所属机构（如红杉、高瓴） | -| title | TEXT | 职位（如合伙人、VP） | +| firm | TEXT | 所属机构 | +| title | TEXT | 职位 | | email | TEXT | 邮箱 | | phone | TEXT | 电话 | | wechat | TEXT | 微信号 | | linkedin | TEXT | LinkedIn URL | -| source | TEXT | 来源（如何找到的） | +| source | TEXT | 来源 | | focus_areas | TEXT | 关注领域（逗号分隔） | | match_score | TEXT | 匹配度（high/medium/low） | -| status | TEXT NOT NULL DEFAULT 'new' | 进展状态（new/contacted/bp_sent/meeting/dd/ts/invested/passed） | +| status | TEXT NOT NULL DEFAULT 'new' | 进展状态 | | notes | TEXT | 备注 | -| created_at | TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) | 记录创建时间 | -| updated_at | TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) | 最后更新时间 | +| created_at | TEXT | 记录创建时间 | +| updated_at | TEXT | 最后更新时间 | **状态机**： ``` @@ -46,14 +46,6 @@ new → contacted → bp_sent → meeting → dd → ts → invested ↓ ↓ ↓ ↓ ↓ ↓ passed passed passed passed passed passed ``` -- `new`：新发现，尚未接触 -- `contacted`：已发出首次接触（邮件/私信/引荐请求） -- `bp_sent`：已发送 BP/材料 -- `meeting`：已安排或完成会议 -- `dd`：尽调中 -- `ts`：Term Sheet 谈判中 -- `invested`：已完成投资 -- `passed`：放弃/被拒 ### contacts（接触记录） @@ -62,12 +54,43 @@ passed passed passed passed passed passed | id | INTEGER PRIMARY KEY AUTOINCREMENT | 自增主键 | | investor_id | INTEGER NOT NULL | 关联 investors.id | | contact_type | TEXT NOT NULL | 接触方式（email/phone/meeting/intro/pitch/other） | -| direction | TEXT NOT NULL | 方向（outbound=我方主动, inbound=对方主动） | +| direction | TEXT NOT NULL | 方向（outbound/inbound） | | summary | TEXT NOT NULL | 接触内容摘要 | | result | TEXT | 结果/对方反馈 | | next_step | TEXT | 下一步行动 | | contact_date | TEXT NOT NULL | 接触日期（YYYY-MM-DD） | -| created_at | TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) | 记录时间 | +| created_at | TEXT | 记录时间 | + +### applications（项目申报） + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | INTEGER PRIMARY KEY AUTOINCREMENT | 自增主键 | +| name | TEXT NOT NULL | 申报项目名称 | +| type | TEXT NOT NULL | 申报类别（competition/grant/subsidy/incubator/other） | +| organizer | TEXT | 主办方/组织方 | +| platform_url | TEXT | 申报平台 URL | +| deadline | TEXT | 截止日期（YYYY-MM-DD） | +| status | TEXT NOT NULL DEFAULT 'planning' | 申报状态 | +| submitted_date | TEXT | 实际提交日期 | +| result | TEXT | 结果/获奖情况 | +| notes | TEXT | 备注 | +| created_at | TEXT | 记录创建时间 | +| updated_at | TEXT | 最后更新时间 | + +**申报状态**： +``` +planning → drafting → submitted → shortlisted → awarded + ↓ ↓ ↓ + passed rejected rejected +``` +- `planning`：计划申报 +- `drafting`：材料准备中 +- `submitted`：已提交 +- `shortlisted`：入围/初筛通过 +- `awarded`：获奖/获批 +- `rejected`：未通过 +- `passed`：放弃申报 --- @@ -78,93 +101,101 @@ passed passed passed passed passed passed ### 初始化数据库 ```bash -bash ./skills/ir-record/scripts/init-db.sh +./skills/ir-record/scripts/init-db.sh ``` ### 投资人档案管理 **检查投资人是否已记录**（按姓名+机构去重）： ```bash -bash ./skills/ir-record/scripts/check-investor.sh --name <姓名> --firm <机构名> +./skills/ir-record/scripts/check-investor.sh --name <姓名> --firm <机构名> ``` 返回 JSON：`{"exists": true/false, "id": <记录ID或null>}` **记录新投资人**： ```bash -bash ./skills/ir-record/scripts/record-investor.sh \ - --name <姓名> \ - --type \ - --firm <机构名> \ - --title <职位> \ - --email <邮箱> \ - --phone <电话> \ - --wechat <微信号> \ - --linkedin \ - --source <来源> \ - --focus-areas <关注领域> \ - --match-score \ - --status \ - --notes <备注> +./skills/ir-record/scripts/record-investor.sh \ + --name <姓名> --type --firm <机构名> \ + [--title <职位>] [--email <邮箱>] [--phone <电话>] [--wechat <微信号>] \ + [--linkedin ] [--source <来源>] [--focus-areas <关注领域>] \ + [--match-score ] [--status ] [--notes <备注>] ``` 必填：`--name`、`--type`、`--firm`。 -返回 JSON：`{"ok": true, "id": <记录ID>}` 或 `{"ok": false, "error": "..."}` **更新投资人状态**： ```bash -bash ./skills/ir-record/scripts/update-status.sh \ - --id <投资人ID> \ - --status <新状态> \ - --notes <备注（可选）> +./skills/ir-record/scripts/update-status.sh --id <投资人ID> --status <新状态> [--notes <备注>] ``` -返回 JSON：`{"ok": true}` 或 `{"ok": false, "error": "..."}` ### 接触记录管理 -**检查近期接触**（同一投资人，过去 N 天内）： +**检查近期接触**： ```bash -bash ./skills/ir-record/scripts/check-contact.sh --investor-id --days <天数> +./skills/ir-record/scripts/check-contact.sh --investor-id --days <天数> ``` -返回 JSON：`{"has_recent": true/false, "last_contact_date": "<日期或null>"}` **记录接触**： ```bash -bash ./skills/ir-record/scripts/record-contact.sh \ - --investor-id <投资人ID> \ - --contact-type \ - --direction \ - --summary <接触内容摘要> \ - --result <结果> \ - --next-step <下一步行动> \ - --contact-date +./skills/ir-record/scripts/record-contact.sh \ + --investor-id <投资人ID> --contact-type \ + --direction --summary <接触内容摘要> \ + --contact-date [--result <结果>] [--next-step <下一步行动>] ``` 必填：`--investor-id`、`--contact-type`、`--direction`、`--summary`、`--contact-date`。 -返回 JSON：`{"ok": true, "id": <记录ID>}` 或 `{"ok": false, "error": "..."}` ### 进展查询 -**查询投资人 Pipeline 摘要**（按状态分组）： +**查询投资人 Pipeline 摘要**： +```bash +./skills/ir-record/scripts/query-progress.sh +``` + +**查询待跟进投资人**： +```bash +./skills/ir-record/scripts/query-stale.sh --days <天数> +``` + +### 项目申报管理 + +**检查申报是否已记录**（按项目名+主办方去重）： +```bash +./skills/ir-record/scripts/check-application.sh --name <项目名> [--organizer <主办方>] +``` +返回 JSON：`{"exists": true/false, "id": <记录ID或null>}` + +**记录新申报**： ```bash -bash ./skills/ir-record/scripts/query-progress.sh +./skills/ir-record/scripts/record-application.sh \ + --name <项目名> --type \ + [--organizer <主办方>] [--platform-url <申报平台URL>] [--deadline ] \ + [--status ] \ + [--submitted-date ] [--result <结果>] [--notes <备注>] ``` -返回 JSON 数组，每个投资人的基本信息、当前状态、最近接触日期。 +必填：`--name`、`--type`。 -**查询待跟进投资人**（超过 N 天未跟进）： +**查询申报记录**： ```bash -bash ./skills/ir-record/scripts/query-stale.sh --days <天数> +./skills/ir-record/scripts/query-applications.sh [--status <状态>] [--upcoming <天数>] ``` -返回 JSON 数组，列出超过指定天数未跟进的活跃状态投资人。 +- 无参数：返回所有申报，按状态排序 +- `--status`：按状态过滤 +- `--upcoming`：查询未来 N 天内截止的申报 --- ## 使用规则 -1. **模式一（Deal Crafting）**：不直接使用数据库，仅通过用户对话和 MEMORY.md 记录材料版本。 -2. **模式二（Investor Hunting）**： +1. **工作块一（商业模式打磨）**：不直接使用数据库。 +2. **工作块二（项目申报）**： + - 发现申报机会后，先用 `check-application.sh` 判断是否已记录 + - 已在数据库中则跳过，避免重复申报 + - 确认申报后用 `record-application.sh` 记录（status=planning） + - 提交后更新 status 为 submitted + - HEARTBEAT 触发时运行 `query-applications.sh --upcoming 7` 提醒即将截止的申报 +3. **工作块三（投资人发掘与跟进）**： - 搜索到投资人后，先用 `check-investor.sh` 判断是否已记录 - - 已在数据库中则跳过，除非有新的联系方式或信息需要更新 + - 已在数据库中则跳过，除非有新信息需要更新 - 新投资人立即用 `record-investor.sh` 记录（status=new） - 首次接触后，用 `update-status.sh` 更新状态，用 `record-contact.sh` 记录接触 -3. **模式三（Relationship Tracking）**： - - HEARTBEAT 触发时运行 `query-stale.sh --days 7` 检查超期未跟进的 - - 用户告知新进展时，立即更新状态和记录接触 + - HEARTBEAT 触发时运行 `query-stale.sh --days 7` 检查超期未跟进 - 每周运行 `query-progress.sh` 获取全局 Pipeline 视图 diff --git a/addons/officials/crew/ir/skills/ir-record/scripts/check-application.sh b/addons/officials/crew/ir/skills/ir-record/scripts/check-application.sh new file mode 100755 index 00000000..832c68c2 --- /dev/null +++ b/addons/officials/crew/ir/skills/ir-record/scripts/check-application.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +# check-application.sh — Check if an application is already recorded (by name + organizer) +# Usage: check-application.sh --name <项目名> --organizer <主办方> + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +WORKSPACE_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)" +DB_FILE="$WORKSPACE_DIR/db/ir_record.db" + +NAME="" +ORGANIZER="" + +while [[ $# -gt 0 ]]; do + case "$1" in + --name) NAME="$2"; shift 2 ;; + --organizer) ORGANIZER="$2"; shift 2 ;; + *) echo '{"exists": false, "error": "Unknown argument: '"$1"'"}' ; exit 1 ;; + esac +done + +if [[ -z "$NAME" ]]; then + echo '{"exists": false, "error": "--name is required"}' + exit 1 +fi + +if [[ ! -f "$DB_FILE" ]]; then + echo '{"exists": false, "id": null}' + exit 0 +fi + +NAME_ESC="${NAME//\'/\'\'}" +ORGANIZER_ESC="${ORGANIZER//\'/\'\'}" + +if [[ -n "$ORGANIZER" ]]; then + RESULT=$(sqlite3 "$DB_FILE" "SELECT id FROM applications WHERE name='$NAME_ESC' AND organizer='$ORGANIZER_ESC' LIMIT 1;" 2>/dev/null || echo "") +else + RESULT=$(sqlite3 "$DB_FILE" "SELECT id FROM applications WHERE name='$NAME_ESC' LIMIT 1;" 2>/dev/null || echo "") +fi + +if [[ -n "$RESULT" ]]; then + echo "{\"exists\": true, \"id\": $RESULT}" +else + echo '{"exists": false, "id": null}' +fi diff --git a/addons/officials/crew/ir/skills/ir-record/scripts/init-db.sh b/addons/officials/crew/ir/skills/ir-record/scripts/init-db.sh index 347dce3d..3c8c4b6e 100755 --- a/addons/officials/crew/ir/skills/ir-record/scripts/init-db.sh +++ b/addons/officials/crew/ir/skills/ir-record/scripts/init-db.sh @@ -42,6 +42,21 @@ CREATE TABLE IF NOT EXISTS contacts ( created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), FOREIGN KEY (investor_id) REFERENCES investors(id) ); + +CREATE TABLE IF NOT EXISTS applications ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL, + type TEXT NOT NULL, + organizer TEXT, + platform_url TEXT, + deadline TEXT, + status TEXT NOT NULL DEFAULT 'planning', + submitted_date TEXT, + result TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); SQL echo '{"ok": true, "message": "ir_record.db initialized"}' diff --git a/addons/officials/crew/ir/skills/ir-record/scripts/query-applications.sh b/addons/officials/crew/ir/skills/ir-record/scripts/query-applications.sh new file mode 100755 index 00000000..ca80c9d9 --- /dev/null +++ b/addons/officials/crew/ir/skills/ir-record/scripts/query-applications.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# query-applications.sh — Query application records +# Usage: query-applications.sh [--status <状态>] [--upcoming <天数>] +# --upcoming: 查询未来 N 天内截止的申报 + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +WORKSPACE_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)" +DB_FILE="$WORKSPACE_DIR/db/ir_record.db" + +STATUS_FILTER="" +UPCOMING_DAYS="" + +while [[ $# -gt 0 ]]; do + case "$1" in + --status) STATUS_FILTER="$2"; shift 2 ;; + --upcoming) UPCOMING_DAYS="$2"; shift 2 ;; + *) echo '[]' ; exit 1 ;; + esac +done + +if [[ ! -f "$DB_FILE" ]]; then + echo '[]' + exit 0 +fi + +if [[ -n "$UPCOMING_DAYS" ]]; then + UPCOMING_ESC="${UPCOMING_DAYS//\'/\'\'}" + sqlite3 -json "$DB_FILE" <= date('now','localtime') + AND deadline <= date('now','localtime','+${UPCOMING_ESC} days') + AND status NOT IN ('passed','rejected') +ORDER BY deadline ASC; +EOF +elif [[ -n "$STATUS_FILTER" ]]; then + SF_ESC="${STATUS_FILTER//\'/\'\'}" + sqlite3 -json "$DB_FILE" < --type <> [--organizer <>] [--platform-url <>] ... + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +WORKSPACE_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)" +DB_FILE="$WORKSPACE_DIR/db/ir_record.db" + +NAME="" +TYPE="" +ORGANIZER="" +PLATFORM_URL="" +DEADLINE="" +STATUS="planning" +SUBMITTED_DATE="" +RESULT="" +NOTES="" + +while [[ $# -gt 0 ]]; do + case "$1" in + --name) NAME="$2"; shift 2 ;; + --type) TYPE="$2"; shift 2 ;; + --organizer) ORGANIZER="$2"; shift 2 ;; + --platform-url) PLATFORM_URL="$2"; shift 2 ;; + --deadline) DEADLINE="$2"; shift 2 ;; + --status) STATUS="$2"; shift 2 ;; + --submitted-date) SUBMITTED_DATE="$2"; shift 2 ;; + --result) RESULT="$2"; shift 2 ;; + --notes) NOTES="$2"; shift 2 ;; + *) echo '{"ok": false, "error": "Unknown argument: '"$1"'"}' ; exit 1 ;; + esac +done + +if [[ -z "$NAME" || -z "$TYPE" ]]; then + echo '{"ok": false, "error": "--name and --type are required"}' + exit 1 +fi + +STATUS="${STATUS:-planning}" + +# Ensure DB and tables exist +bash "$SCRIPT_DIR/init-db.sh" > /dev/null + +N_ESC="${NAME//\'/\'\'}" +T_ESC="${TYPE//\'/\'\'}" +O_ESC="${ORGANIZER//\'/\'\'}" +PU_ESC="${PLATFORM_URL//\'/\'\'}" +DL_ESC="${DEADLINE//\'/\'\'}" +ST_ESC="${STATUS//\'/\'\'}" +SD_ESC="${SUBMITTED_DATE//\'/\'\'}" +R_ESC="${RESULT//\'/\'\'}" +NT_ESC="${NOTES//\'/\'\'}" + +NEW_ID=$(sqlite3 "$DB_FILE" < + 开展市场研究、竞品分析、投资人尽调、行业情报，附带来源标注和决策导向的摘要。 + 当用户需要市场规模估算、竞品对比、基金研究、技术扫描或支撑商业决策的研究时触发。 +metadata: + openclaw: + emoji: 🔍 +--- + +# 市场研究 + +产出支撑决策的研究，而非研究表演。 + +## 触发条件 + +- 研究市场、品类、公司、投资人或技术趋势 +- 构建 TAM/SAM/SOM 估算 +- 比较竞品或相邻产品 +- 触达前的投资人/基金尽调 +- 在进入市场、融资、投资前压力测试论点 + +## 研究标准 + +1. **每个重要论断必须有来源** +2. 优先使用最新数据，标注过时数据 +3. 包含反面证据和下行情景 +4. 把发现翻译成决策建议，而非仅做摘要 +5. 事实、推断、建议三者清晰分离 + +## 研究模式 + +### 投资人/基金尽调 + +收集以下信息： + +| 维度 | 内容 | +|------|------| +| 基金规模与阶段 | 管理规模、偏好轮次、典型支票大小 | +| 相关被投企业 | 与本业务领域相关的已投项目 | +| 公开策略 | 基金 thesis、近期公开言论/文章 | +| 活跃度 | 近期投资动态、新基金募集 | +| 匹配判断 | 适合/不适合的理由 | +| 红旗 | 明显的策略错配或潜在问题 | + +**搜索方法**：使用 `smart-search` 搜索基金官网、IT桔子/企查查公开数据、行业媒体报道；使用 `browser-guide` 访问关键页面提取详细信息。 + +### 竞品分析 + +收集以下信息： + +| 维度 | 内容 | +|------|------| +| 产品实际 | 真实功能，不是营销文案 | +| 融资与投资方 | 公开的融资历史和投资人 | +| 牵引指标 | 公开的用户/营收/增长数据 | +| 分销与定价 | 渠道、定价策略线索 | +| 优劣势 | 核心强项、明显短板 | +| 定位缺口 | 市场中未被覆盖的空间 | + +**搜索方法**：使用 `smart-search` 搜索竞品官网、融资新闻、用户评价；使用 `browser-guide` 直接访问竞品产品页面。 + +### 市场规模估算 + +方法： + +- **自上而下**：从行业报告或公开数据集推算 +- **自下而上**：从现实的获客假设做合理性校验 +- **每个逻辑跳跃标注假设前提** + +TAM/SAM/SOM 框架： + +| 层级 | 定义 | 方法 | +|------|------|------| +| TAM | 全球/全国总需求 | 行业报告 × 总人口/企业数 | +| SAM | 可服务市场 | TAM × 目标细分比例 | +| SOM | 可获得市场 | SAM × 现实占有率假设 | + +### 技术/供应商研究 + +收集： + +- 工作原理 +- 折中取舍与采纳信号 +- 集成复杂度 +- 锁定风险、安全、合规、运维风险 + +## 输出格式 + +默认结构： + +``` +1. 执行摘要 +2. 核心发现 +3. 启示（对业务的影响） +4. 风险与注意事项 +5. 建议 +6. 来源列表 +``` + +## 质量门控 + +交付前检查： + +- [ ] 所有数字有来源或标注为估算 +- [ ] 过时数据已标注 +- [ ] 建议基于证据推导得出 +- [ ] 包含风险和反面论据 +- [ ] 输出让决策更容易，而非更困惑 + +## 与其他技能协作 + +| 场景 | 配合技能 | +|------|---------| +| 搜索投资人/基金信息 | `smart-search`（Bing 主推，百度 backup） | +| 访问需要登录的数据库页面 | `browser-guide` | +| 竞品分析后记录到投资人库 | `ir-record` | +| 研究结果用于制作路演材料 | `investor-materials` | +| 研究结果用于撰写触达邮件 | `investor-outreach` | +| 研究结果触发商业模式讨论 | `council`（研究发现驱动复盘） | +| 分析人脉网络找暖介绍路径 | `social-graph-ranker`，`connections-optimizer` | diff --git a/addons/officials/crew/sales-cs/AGENTS.md b/addons/officials/crew/sales-cs/AGENTS.md index 9cdd7d8e..9c595be5 100644 --- a/addons/officials/crew/sales-cs/AGENTS.md +++ b/addons/officials/crew/sales-cs/AGENTS.md @@ -84,7 +84,7 @@ 每轮结束时，可根据本轮对话进展更新 `purpose` 和/或 `prompt_source`： ```bash -bash ./skills/customer-db/scripts/cs-update.sh \ +./skills/customer-db/scripts/cs-update.sh \ --peer "<[CustomerDB].peer>" \ --purpose "线上获客" \ --prompt-source "GitHub" @@ -121,11 +121,11 @@ bash ./skills/customer-db/scripts/cs-update.sh \ ```bash # 第一步：若已有 pending 旧任务，先取消 -bash ./skills/customer-db/scripts/follow-up-cancel-pending.sh \ +./skills/customer-db/scripts/follow-up-cancel-pending.sh \ --peer "<[CustomerDB].peer>" # 第二步：创建新跟进任务 -bash ./skills/customer-db/scripts/follow-up-create.sh \ +./skills/customer-db/scripts/follow-up-create.sh \ --peer "<[CustomerDB].peer>" \ --user-id-external "" \ --follow-up-at "" \ diff --git a/addons/officials/crew/sales-cs/BOOTSTRAP.md b/addons/officials/crew/sales-cs/BOOTSTRAP.md index 097840b9..459cae46 100644 --- a/addons/officials/crew/sales-cs/BOOTSTRAP.md +++ b/addons/officials/crew/sales-cs/BOOTSTRAP.md @@ -1,10 +1,46 @@ -# Bootstrap +# Sales-CS Bootstrap -This is a pre-configured crew workspace. Your role, responsibilities, and behavioral guidelines are fully defined in the following files — please review them at startup: +This one-time bootstrap collects the product/service handbook and operational context before customer service work starts. HRBP should ask these questions on behalf of this crew and write the answers into the crew workspace. -- **SOUL.md** — Role definition, core responsibilities, and autonomy level -- **AGENTS.md** — Workflows and operating procedures -- **MEMORY.md** — Background context and ongoing task state -- **IDENTITY.md** — Name and persona -- **USER.md** — Assumptions about who you are serving -- **TOOLS.md** — Available tools and usage guidelines +## Step 1: Product/Service Handbook + +Collect: + +- **Product name**: full product/service name +- **Core value**: one-line description of what problem it solves for customers +- **Target customers**: typical customer profile +- **Pricing tiers**: each tier's name, price, target audience, and core benefits +- **Purchase method**: how customers buy (payment link, QR code, contact person, etc.) +- **FAQ**: top 5-10 frequently asked questions and their answers + +## Step 2: Operational Links + +Collect: + +- Feedback survey URL +- Invoice request form URL +- Purchase page URL +- Trial/experience application URL (if applicable) + +## Step 3: Escalation Contact + +Collect: + +- Human escalation WeChat ID (for complex issues, complaints, refund requests) +- Any other escalation channels + +## Step 4: Environment Verification + +On first startup, check and report: + +1. Customer database is initialized: `./skills/customer-db/scripts/init-db.sh` (idempotent) +2. Follow-up table is ready: `./skills/customer-db/scripts/follow-up-init.sh` (idempotent) + +## Completion + +After bootstrap is complete: + +1. Update `MEMORY.md` with the full product/service handbook, key links, and escalation contact — replacing all placeholder entries. +2. Update `USER.md` if needed with service-specific notes. +3. Delete `BOOTSTRAP.md` from the runtime workspace. +4. Suggest the next step, such as testing a sample customer conversation. diff --git a/addons/officials/crew/sales-cs/DENIED_SKILLS b/addons/officials/crew/sales-cs/DENIED_SKILLS deleted file mode 100644 index ff1baf4d..00000000 --- a/addons/officials/crew/sales-cs/DENIED_SKILLS +++ /dev/null @@ -1,19 +0,0 @@ -# IT-only bundled skills -github -gh-issues -coding-agent -# 复杂任务技能（客服场景不适用） -complex-task -# 商务拓展专属技能（business-developer 使用） -connections-optimizer -email-ops -pitch-deck -ppt-maker -social-graph-ranker -# 生图/生视频技能（客服场景不需要） -siliconflow-img-gen -siliconflow-video-gen -rss-reader -xhs-interact -pexels-footage -pixabay-footage \ No newline at end of file diff --git a/addons/officials/crew/sales-cs/HEARTBEAT.md b/addons/officials/crew/sales-cs/HEARTBEAT.md index 72fc3eed..093a5efb 100644 --- a/addons/officials/crew/sales-cs/HEARTBEAT.md +++ b/addons/officials/crew/sales-cs/HEARTBEAT.md @@ -9,13 +9,13 @@ 1. 先清理过期任务（超过 48 小时仍为 pending，客户已失联）： ```bash -bash ./skills/customer-db/scripts/follow-up-expire.sh +./skills/customer-db/scripts/follow-up-expire.sh ``` 2. 查询当前到期的跟进任务： ```bash -bash ./skills/customer-db/scripts/follow-up-due.sh +./skills/customer-db/scripts/follow-up-due.sh ``` 输出为 tab 分隔表格（含 header），字段：`id / peer / user_id_external / follow_up_at / reason / context_summary / status`。 @@ -32,14 +32,14 @@ bash ./skills/customer-db/scripts/follow-up-due.sh - `status='pending'`（首次发送）→ 标记为 sent_once： ```bash - bash ./skills/customer-db/scripts/follow-up-mark-sent.sh \ + ./skills/customer-db/scripts/follow-up-mark-sent.sh \ --id \ --sent-text "<发送的消息内容>" ``` - `status='sent_once'`（二次发送）→ 标记为 completed： ```bash - bash ./skills/customer-db/scripts/follow-up-complete.sh \ + ./skills/customer-db/scripts/follow-up-complete.sh \ --id \ --sent-text "<发送的消息内容>" ``` diff --git a/addons/officials/crew/sales-cs/MEMORY.md b/addons/officials/crew/sales-cs/MEMORY.md index 022a1701..14a21e8f 100644 --- a/addons/officials/crew/sales-cs/MEMORY.md +++ b/addons/officials/crew/sales-cs/MEMORY.md @@ -2,7 +2,7 @@ ## 产品/服务手册 -> 由 hrbp 在招募时填写。这是销售客服最核心的知识库，所有售前问答优先以此为准。 +> 由hrbp在招募后收集写入。这是销售客服最核心的知识库，所有售前问答优先以此为准。 ### 产品概述 - 产品名称：<产品/服务全称> @@ -28,7 +28,7 @@ ## 关键链接 -> 由 hrbp 配置，填写后客服可在对话中直接引用 +> 由 BOOTSTRAP 首次收集写入（或由 hrbp 配置），填写后客服可在对话中直接引用 - 反馈问卷：<反馈问卷链接> - 开票申请工单：<开票申请工单链接> @@ -41,7 +41,7 @@ ## 常见问题与解决方案 -> 运营中逐步积累，记录高频问题和经过验证的最佳答复。 +> 由hrbp在运营中逐步积累，记录高频问题和经过验证的最佳答复。 diff --git a/addons/officials/crew/sales-cs/SOUL.md b/addons/officials/crew/sales-cs/SOUL.md index 212e9eff..c22afbf8 100644 --- a/addons/officials/crew/sales-cs/SOUL.md +++ b/addons/officials/crew/sales-cs/SOUL.md @@ -12,7 +12,7 @@ 2. **售前咨询**：解答客户对 <产品/服务名称> 的疑问，以长期记忆中的客服手册为准 3. **销售推进**：识别购买意图，引导客户进入 <付费转化路径，如：试用→轻付费→订阅> 4. **客户画像维护**：基于系统注入的客户状态，维护 `business_status`、`purpose`、`prompt_source` -5. **人工升级**：遇到敏感/投诉/退款/复杂问题时，引导客户联系人工 +5. **人工升级**：遇到敏感/投诉/退款/复杂问题时，引导客户联系人工，绝对不要给出任何结论或承诺！ ## 明确边界 @@ -64,25 +64,13 @@ 表示客户主要业务应用场景。具体口径与细分差异以客服手册为准。 当前可作为通用示例的方向包括但不限于： -- 线上获客 -- 竞争对手监控 -- 行业情报获取 -- 舆情监控 -- 自建可提供对外服务的智能体 +> 由hrbp在招募后收集写入。 如果用户没明确说，也要通过自然对话逐步引导出来。 ### prompt_source 表示客户是从哪里了解到我们的，例如： -- 朋友推荐 -- 社群 -- GitHub -- 公众号 -- 小红书 -- 知乎 -- 即刻 -- 其他 AI 推荐（如豆包、DeepSeek、qwen） -- …… +> 由hrbp在招募后收集写入。 这是重要的增长信息，若为空，要自然询问或引导补全。 diff --git a/addons/officials/crew/sales-cs/USER.md b/addons/officials/crew/sales-cs/USER.md index 5803584c..f9a84eb5 100644 --- a/addons/officials/crew/sales-cs/USER.md +++ b/addons/officials/crew/sales-cs/USER.md @@ -6,4 +6,3 @@ External customers interacting via bound channel (WeChat). ## Preferences - Language: Match customer's language (default: 中文) - Style: Friendly, concise, sales-oriented -- Autonomy: L1/L2 proceed directly; L3 always confirm with team owner diff --git a/addons/officials/crew/sales-cs/feedback/.gitkeep b/addons/officials/crew/sales-cs/feedback/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/addons/officials/crew/sales-cs/skills/customer-db/SKILL.md b/addons/officials/crew/sales-cs/skills/customer-db/SKILL.md index 98c27736..631f6cd7 100644 --- a/addons/officials/crew/sales-cs/skills/customer-db/SKILL.md +++ b/addons/officials/crew/sales-cs/skills/customer-db/SKILL.md @@ -85,7 +85,7 @@ Sender (untrusted metadata): 每轮结束前，根据本轮对话进展更新 `purpose` 和/或 `prompt_source`： ```bash -bash ./skills/customer-db/scripts/cs-update.sh \ +./skills/customer-db/scripts/cs-update.sh \ --peer "<[CustomerDB].peer>" \ --purpose "线上获客" \ --prompt-source "GitHub" @@ -111,11 +111,11 @@ bash ./skills/customer-db/scripts/cs-update.sh \ ```bash # 第一步：取消同一客户的旧 pending 任务 -bash ./skills/customer-db/scripts/follow-up-cancel-pending.sh \ +./skills/customer-db/scripts/follow-up-cancel-pending.sh \ --peer "<[CustomerDB].peer>" # 第二步：创建新任务 -bash ./skills/customer-db/scripts/follow-up-create.sh \ +./skills/customer-db/scripts/follow-up-create.sh \ --peer "<[CustomerDB].peer>" \ --user-id-external "" \ --follow-up-at "" \ @@ -130,13 +130,13 @@ bash ./skills/customer-db/scripts/follow-up-create.sh \ 超过 48 小时仍为 `pending` 的任务视为客户失联，自动标记完成： ```bash -bash ./skills/customer-db/scripts/follow-up-expire.sh +./skills/customer-db/scripts/follow-up-expire.sh ``` ### 查询到期任务 ```bash -bash ./skills/customer-db/scripts/follow-up-due.sh +./skills/customer-db/scripts/follow-up-due.sh ``` 输出为 tab 分隔的表格（含 header），字段：`id / peer / user_id_external / follow_up_at / reason / context_summary / status`。 @@ -144,7 +144,7 @@ bash ./skills/customer-db/scripts/follow-up-due.sh ### 标记首次已发送（pending → sent_once） ```bash -bash ./skills/customer-db/scripts/follow-up-mark-sent.sh \ +./skills/customer-db/scripts/follow-up-mark-sent.sh \ --id \ --sent-text "<发送的消息内容>" ``` @@ -152,7 +152,7 @@ bash ./skills/customer-db/scripts/follow-up-mark-sent.sh \ ### 标记完成（sent_once → completed） ```bash -bash ./skills/customer-db/scripts/follow-up-complete.sh \ +./skills/customer-db/scripts/follow-up-complete.sh \ --id \ --sent-text "<发送的消息内容>" ``` diff --git a/addons/officials/crew/sales-cs/skills/customer-db/scripts/cs-update.sh b/addons/officials/crew/sales-cs/skills/customer-db/scripts/cs-update.sh old mode 100644 new mode 100755 diff --git a/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-cancel-pending.sh b/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-cancel-pending.sh old mode 100644 new mode 100755 diff --git a/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-complete.sh b/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-complete.sh old mode 100644 new mode 100755 diff --git a/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-create.sh b/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-create.sh old mode 100644 new mode 100755 diff --git a/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-due.sh b/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-due.sh old mode 100644 new mode 100755 diff --git a/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-expire.sh b/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-expire.sh old mode 100644 new mode 100755 diff --git a/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-mark-sent.sh b/addons/officials/crew/sales-cs/skills/customer-db/scripts/follow-up-mark-sent.sh old mode 100644 new mode 100755 diff --git a/addons/officials/crew/sales-cs/skills/exp_invite/SKILL.md b/addons/officials/crew/sales-cs/skills/exp_invite/SKILL.md index 0ce70bca..c9ef0364 100644 --- a/addons/officials/crew/sales-cs/skills/exp_invite/SKILL.md +++ b/addons/officials/crew/sales-cs/skills/exp_invite/SKILL.md @@ -16,7 +16,7 @@ description: > 此处需要同时传入两个标识符，各自职责不同： ```bash -bash ./skills/exp_invite/scripts/invite.sh \ +./skills/exp_invite/scripts/invite.sh \ --peer "<[CustomerDB].peer>" \ --user-id-external "" ``` diff --git a/addons/officials/crew/sales-cs/skills/exp_invite/scripts/invite.sh b/addons/officials/crew/sales-cs/skills/exp_invite/scripts/invite.sh old mode 100644 new mode 100755 index caf644ca..0c231784 --- a/addons/officials/crew/sales-cs/skills/exp_invite/scripts/invite.sh +++ b/addons/officials/crew/sales-cs/skills/exp_invite/scripts/invite.sh @@ -42,12 +42,12 @@ fi WORKDIR="$(cd "$(dirname "$0")/../../.." && pwd)" cd "$WORKDIR" -bash ./skills/customer-db/scripts/db.sh ensure >/dev/null +./skills/customer-db/scripts/db.sh ensure >/dev/null -existing_status="$(bash ./skills/customer-db/scripts/db.sh sql "SELECT business_status FROM cs_record WHERE peer = '$PEER'" | tail -n +2 | head -n 1 || true)" +existing_status="$(./skills/customer-db/scripts/db.sh sql "SELECT business_status FROM cs_record WHERE peer = '$PEER'" | tail -n +2 | head -n 1 || true)" if [ -z "$existing_status" ]; then - bash ./skills/customer-db/scripts/db.sh sql "INSERT INTO cs_record (peer, business_status, purpose, prompt_source) VALUES ('$PEER', 'free', '', '')" >/dev/null + ./skills/customer-db/scripts/db.sh sql "INSERT INTO cs_record (peer, business_status, purpose, prompt_source) VALUES ('$PEER', 'free', '', '')" >/dev/null existing_status="free" fi @@ -56,5 +56,5 @@ if [ "$existing_status" = "exp_invited" ]; then exit 10 fi -bash ./skills/customer-db/scripts/db.sh sql "UPDATE cs_record SET business_status = 'exp_invited' WHERE peer = '$PEER'" >/dev/null +./skills/customer-db/scripts/db.sh sql "UPDATE cs_record SET business_status = 'exp_invited' WHERE peer = '$PEER'" >/dev/null printf '/invite//%s//%s\n' "$USER_ID_EXTERNAL" "$GROUP_NAME" diff --git a/addons/officials/crew/sales-cs/skills/proactive-send/SKILL.md b/addons/officials/crew/sales-cs/skills/proactive-send/SKILL.md index fdae327b..01e09275 100644 --- a/addons/officials/crew/sales-cs/skills/proactive-send/SKILL.md +++ b/addons/officials/crew/sales-cs/skills/proactive-send/SKILL.md @@ -2,6 +2,9 @@ name: proactive-send description: > 向 awada 客户主动发送消息。在 openclaw 消息处理循环之外直接写入 Redis outbound stream，无需等待客户发起对话。 +metadata: + openclaw: + emoji: 📤 --- # 主动发送（proactive-send） @@ -13,7 +16,7 @@ description: > ## 使用方法 ```bash -bash ./skills/proactive-send/scripts/send.sh \ +./skills/proactive-send/scripts/send.sh \ --user-id-external "" \ --text "<消息内容>" ``` diff --git a/addons/officials/crew/sales-cs/skills/proactive-send/scripts/send.sh b/addons/officials/crew/sales-cs/skills/proactive-send/scripts/send.sh old mode 100644 new mode 100755 index 0fc251f9..a0544712 --- a/addons/officials/crew/sales-cs/skills/proactive-send/scripts/send.sh +++ b/addons/officials/crew/sales-cs/skills/proactive-send/scripts/send.sh @@ -3,7 +3,7 @@ # 主动向 awada 客户发送消息（在 openclaw 消息处理循环之外） # # 用法： -# bash ./skills/proactive-send/scripts/send.sh \ +# ./skills/proactive-send/scripts/send.sh \ # --awada-customer-id "wechat:ch001:wxid_abc123:default" \ # --text "您好，昨天咱们聊过专业版的事，不知道今天方便看看吗？" # diff --git a/addons/officials/crew/selfmedia-operator/AGENTS.md b/addons/officials/crew/selfmedia-operator/AGENTS.md index da534644..1dafb1a9 100644 --- a/addons/officials/crew/selfmedia-operator/AGENTS.md +++ b/addons/officials/crew/selfmedia-operator/AGENTS.md @@ -1,32 +1,32 @@ -# 自媒体运营 — Workflow +# 自媒体运营 - Workflow ## 素材积累 -素材积累来源包括：用户分享的飞书文档/网页链接、网络搜集、调用 skills 生成。 +素材积累来源包括:用户分享的飞书文档/网页链接、网络搜集、调用 skills 生成。 -**注意**：用户也可能时不时的通过私聊渠道分享一些要点、思路以及注意事项等，这些应该记在长期记忆 **MEMORY.md** 中。 +**注意**:用户也可能时不时的通过私聊渠道分享一些要点、思路以及注意事项等,这些应该记在长期记忆 **MEMORY.md** 中。 -其他素材都应该统一存储在 `campaign_assets/` 中，并维护 `campaign_assets/index.md`, 便于后续复用。 +其他素材都应该统一存储在 `campaign_assets/` 中,并维护 `campaign_assets/index.md`, 便于后续复用。 -index.md 格式为： +index.md 格式为: | Instance ID |内容概要|Type|文件名|来源|prompt|创建日期|更新日期 | |-----------|-----------|-----------|-----------|-----------|-----------|----------|-----------| | ||||| ||| -- Type 为枚举：笔记|图片|媒体 -- 来源：仅适用于用户分享和网络搜集 -- prompt：仅适用于 skill 生成 +- Type 为枚举:笔记|图片|媒体 +- 来源:仅适用于用户分享和网络搜集 +- prompt:仅适用于 skill 生成 ## 自媒体内容产出策略 ### 核心原则 -每篇文章中都必须自然而合理的包含结合公司产品的内容。撰文前先回顾下 `MEMORY.md` +每篇文章或视频内容中都必须自然而合理的包含结合 wiseflow 的内容。生产前先回顾下 `MEMORY.md` -### 文章（图文）内容生产通用约束 +### 文章(图文)内容生产通用约束 -每篇文章在 `output_articles/` 下创建独立文件夹,结构如下: +为每篇文章在 `output_articles/` 下创建独立文件夹作为工作区,结构如下: ``` output_articles/ @@ -43,94 +43,26 @@ output_articles/ **配图要求**: 配图类型优先级: - 1. **素材图**:日常积累的素材图，尤其是用户分享的 + - 1. **素材图**:日常积累的素材图,尤其是用户分享的 - 存放在 `campaign_assets/` 目录 - 直观展示 wiseflow 的能力和实际效果 - 2. **技能生成图片**: - - 优先使用 `siliconflow-img-gen` 生成，`siliconflow-img-gen` 不可用时，尝试 `pexels-footage` 或 `pixabay-footage` 下载免版权图片 + - 2. **技能生成图片**: + - 优先使用 siliconflow-img-gen 生成,siliconflow-img-gen 不可用时,尝试 pexels-footage 或 pixabay-footage 下载免版权图片 -### 视频内容生产通用约束 +## Publish Strategy(发布执行策略) -每个视频在 `output_video/` 下创建独立文件夹作为该视频工作区,结构如下: +### 文末统一宣传 hook -``` -output_video/ -└── / # 文章英文题目作为文件夹名 - ├── references/ # 参考资料文件夹 - ├── fragments/ # 视频片段（中间过程）存储文件夹 - ├── script.md # 视频脚本(必须) - ├── vedio.mp4 # 视频文件 - ├── cover.jpg # 封面图(必须) - └── ... -``` - -**通用视频生产流程**： -- 充分构思故事线； -- 生成视频脚本，脚本必须以 5s 为单位拆分为片段列表； -- 对于每个视频片段优先使用`pexels-footage` 或 `pixabay-footage` 下载免版权视频片段，如果`pexels-footage` 或 `pixabay-footage` 不可用，或者搜索不到合适的视频片段时，则使用 `siliconflow-video-gen`生成； -- 使用 `ffmepg` 合成视频片段； -- 制作视频封面（必须）。 - -注意：每个视频都必须配封面图，封面图必须采用“图+文“的模式，不能仅有背景图片，文字可以是一句吸引人的文案。视频封面图应该 spawn `designer` 所谓 subagent 制作，`designer`不可用时也用 spawn 自己作为 subagent 制作。 - -## Publish Strategy（发布执行策略） - -### 统一宣传 hook - -所有对外发布文章（视频则为简介区），必须按如下平台策略在文末添加统一宣传hook： - -#### 宽松平台策略（微信公众号 / 掘金 / 企业微信朋友圈 / twitter） - -<待替换> -```markdown ---- -假如你现在也有搞副业、创业的想法，欢迎尝试使用 wiseflow 打造 7*24 在线搞钱的AI数字员工团队。 - -**项目地址**： -- [GitHub 主站](https://github.com/TeamWiseFlow/wiseflow) -- [国内镜像 - 开放原子基金会平台](https://atomgit.com/wiseflow/wiseflow) - -也可扫码联系"掌柜的"： - -![扫码联系掌柜](campaign_assets/contact.png) - -*扫码联系 wiseflow 掌柜，了解更多 AI 数字员工方案* -``` - -#### 次宽松平台策略（知乎 / 今日头条） - -<待替换> -```markdown ---- -假如你现在也有搞副业、创业的想法，欢迎尝试使用 wiseflow 打造 7*24 在线搞钱的AI数字员工团队。 - -**项目地址**： -- [GitHub 主站](https://github.com/TeamWiseFlow/wiseflow) -- [国内镜像 - 开放原子基金会平台](https://atomgit.com/wiseflow/wiseflow) -``` - -#### 严格平台策略（小红书） - -<待替换> -```markdown -假如你现在也有搞副业、创业的想法,欢迎关注我并私信,大家一起探讨呀~ - -也欢迎尝试使用 wiseflow 打造 7*24 在线搞钱的AI数字员工团队。 - -🔍 github 搜索: wiseflow -(国内用户可以去 atomgit 上搜索) -``` - -## Technical Issue Dispatch Protocol - -**当任务执行过程中遭遇技术问题或系统故障（exec 失败、配置异常、spawn 报错、脚本异常等），必须严格按以下步骤处理：** +所有对外发布文章(视频则为简介区),必须按如下平台策略在文末添加统一宣传hook: -1. **立即告知用户**：主动说明遇到了技术问题，正在呼唤 IT Engineer 处理，请耐心等待，任务执行时间会稍长 -2. **spawn IT Engineer**：调用 `sessions_spawn`，将问题现象、错误信息、当前任务上下文完整传递给 IT Engineer -3. **等待修复完成**，然后继续执行原任务 + -**绝对禁止**：因技术问题停止工作，或要求用户自行解决系统故障。技术问题由 IT Engineer 负责，你的职责是保证用户任务顺利完成。 +### 发布记录管理 -## sessions_spawn 规范 +**统一使用 `published-track` 技能管理所有发布记录**。 -> ⚠️ **禁止传入 `streamTo` 参数** — `streamTo` 仅支持 `runtime=acp`，在 subagent 模式下会报错（`streamTo is only supported for runtime=acp`）。spawn 时只传 agentId 和 task 内容即可。 +- 数据库位置:`./db/published_track.db`(初始化:`./skills/published-track/scripts/init-db.sh`,幂等可重复执行) +- 按平台分表,每张表包含标题、类型、原始文件夹、发布 URL、发布日期、互动指标等字段 +- 所有发布技能在发布成功后必须自动调用 `record.sh` 记录 +- 数据更新通过 `update-metrics.sh` 完成(心跳巡检时使用) +- 查询通过 `query.sh` 和 `check-published.sh` 完成 \ No newline at end of file diff --git a/addons/officials/crew/selfmedia-operator/ALLOWED_COMMANDS b/addons/officials/crew/selfmedia-operator/ALLOWED_COMMANDS index 5c06728f..67d59de9 100644 --- a/addons/officials/crew/selfmedia-operator/ALLOWED_COMMANDS +++ b/addons/officials/crew/selfmedia-operator/ALLOWED_COMMANDS @@ -1,9 +1,3 @@ -# 技能脚本执行 -python3 -node -npx -ffmpeg -# 文本处理 -sed -cut -base64 +# T2 基线已含 python3/node/npx/ffmpeg/sed/curl，无需重复声明 ++cut ++base64 diff --git a/addons/officials/crew/selfmedia-operator/BOOTSTRAP.md b/addons/officials/crew/selfmedia-operator/BOOTSTRAP.md index 097840b9..30c1bcbb 100644 --- a/addons/officials/crew/selfmedia-operator/BOOTSTRAP.md +++ b/addons/officials/crew/selfmedia-operator/BOOTSTRAP.md @@ -1,10 +1,76 @@ -# Bootstrap +# Media Operator Bootstrap -This is a pre-configured crew workspace. Your role, responsibilities, and behavioral guidelines are fully defined in the following files — please review them at startup: +This one-time bootstrap collects the operating context before content work starts. If this crew is being enabled through Main Agent and has no direct work channel yet, Main Agent may ask these questions on behalf of this crew and write the answers into the crew workspace. -- **SOUL.md** — Role definition, core responsibilities, and autonomy level -- **AGENTS.md** — Workflows and operating procedures -- **MEMORY.md** — Background context and ongoing task state -- **IDENTITY.md** — Name and persona -- **USER.md** — Assumptions about who you are serving -- **TOOLS.md** — Available tools and usage guidelines +## Step 1: Platform Scope + +Ask which platforms the user wants to operate: + +- WeChat Official Account +- WeCom Moments +- Xiaohongshu +- Douyin +- Kuaishou +- Bilibili +- YouTube +- TikTok +- Instagram +- Facebook +- Threads +- Pinterest +- Other platforms + +Clarify: + +- first-launch platforms; +- later/backlog platforms; +- draft-only vs automatic publishing; +- whether human approval is required before publishing. + +## Step 2: WeChat / WeCom Publishing Readiness + +If the user chooses WeChat Official Account or WeCom Moments, remind them: + +> These publishing APIs commonly require an IP allowlist. If this machine has no fixed public IP, use a relay/transit mode before enabling automatic publishing. + +Ask: + +- Does this machine have a fixed public IP? +- Is the platform IP allowlist already configured? +- Do they need relay/transit mode? +- Should this crew only generate drafts until publishing credentials are ready? + +## Step 3: Brand and Business Context + +Collect: + +- brand/company name; +- product/service introduction; +- target audience; +- key selling points; +- brand tone; +- forbidden claims or sensitive topics; +- competitors or differentiation; +- common CTA; +- source material locations; +- approval owner and workflow. + +## Step 4: Content Operating Rhythm + +Ask: + +- publishing frequency by platform; +- daily/weekly topic planning cadence; +- whether heartbeat should generate topics, drafts, or status reports; +- failure handling preference: notify immediately or summarize later. + +## Completion + +After bootstrap is complete: + +1. Update `MEMORY.md` with platform strategy, brand context, and constraints. +2. Update `USER.md` with approval preferences and service recipient information. +3. Update `TOOLS.md` with publishing environment notes, but never write secrets into Markdown. +4. Update `HEARTBEAT.md` only if the user wants periodic tasks. +5. Delete `BOOTSTRAP.md` from the runtime workspace. +6. Suggest the next step, such as creating the first WeChat Official Account draft. diff --git a/addons/officials/crew/selfmedia-operator/BUILTIN_SKILLS b/addons/officials/crew/selfmedia-operator/BUILTIN_SKILLS index 09287ca1..a198c3e6 100644 --- a/addons/officials/crew/selfmedia-operator/BUILTIN_SKILLS +++ b/addons/officials/crew/selfmedia-operator/BUILTIN_SKILLS @@ -1,15 +1,19 @@ +wx-mp-publisher twitter-post -tiktok-post -instagram-post -youtube-upload +douyin-publish +youtube-publish +tiktok-publish +facebook-publish +instagram-publish +threads-publish +pinterest-publish +kuaishou-publish +bilibili-publish +wxwork-moments xhs-content-ops xhs-interact -xhs-publisher juejin-publish toutiao-publish -siliconflow-img-gen -siliconflow-video-gen pexels-footage pixabay-footage -smart-search -browser-guide \ No newline at end of file +highlight-clipper diff --git a/addons/officials/crew/selfmedia-operator/DENIED_SKILLS b/addons/officials/crew/selfmedia-operator/DENIED_SKILLS index 75c6bf43..0e3c83aa 100644 --- a/addons/officials/crew/selfmedia-operator/DENIED_SKILLS +++ b/addons/officials/crew/selfmedia-operator/DENIED_SKILLS @@ -6,5 +6,6 @@ connections-optimizer email-ops pitch-deck social-graph-ranker -ppt-maker -rss-reader \ No newline at end of file +# 闲鱼技能（media-operator 不需要） +xianyu-ops +council diff --git a/addons/officials/crew/selfmedia-operator/HEARTBEAT.md b/addons/officials/crew/selfmedia-operator/HEARTBEAT.md index 955b7996..ccd7633a 100644 --- a/addons/officials/crew/selfmedia-operator/HEARTBEAT.md +++ b/addons/officials/crew/selfmedia-operator/HEARTBEAT.md @@ -1 +1,19 @@ -# 心跳检查清单 +# 心跳任务 + +## 执行约束 + +1. **无时间限制**：HEARTBEAT/cron 触发后必须执行完清单全部内容 +2. **遇到技术故障时**： + - 先尝试关闭并重启浏览器 + - 仍不解决 → spawn IT Engineer 协助 + - 仍无法解决 → 跳过当前任务，继续后续步骤，不卡住整个流程 +3. **不可呼唤用户协助**（定时任务可能深夜执行） +4. **浏览器操作必须串行**，不可并行，避免竞态抢夺 + +--- + +## 当前无定时任务 + +如有任务需求，向用户了解清楚后，参照 `HEARTBEAT_TEMPLATE.md` 的格式写入对应工作模式配置。 + +当前：回复 `HEARTBEAT_OK` diff --git a/addons/officials/crew/selfmedia-operator/MEMORY.md b/addons/officials/crew/selfmedia-operator/MEMORY.md index 88007391..11b8192c 100644 --- a/addons/officials/crew/selfmedia-operator/MEMORY.md +++ b/addons/officials/crew/selfmedia-operator/MEMORY.md @@ -1,8 +1,9 @@ # 自媒体运营 — Memory +## 平台策略与品牌上下文 + + + ## Notes - -### Style Guidelines -（用户确认过的风格偏好、常用 hashtag、禁忌话题） diff --git a/addons/officials/crew/selfmedia-operator/SOUL.md b/addons/officials/crew/selfmedia-operator/SOUL.md index 1312287b..fb4f2a4d 100644 --- a/addons/officials/crew/selfmedia-operator/SOUL.md +++ b/addons/officials/crew/selfmedia-operator/SOUL.md @@ -7,6 +7,8 @@ ## 公司与业务背景信息 + + ## Core Responsibilities ### 素材管理 diff --git a/addons/officials/crew/selfmedia-operator/openclaw_setting_sample.json b/addons/officials/crew/selfmedia-operator/openclaw_setting_sample.json index 8b1313bc..211a30ae 100644 --- a/addons/officials/crew/selfmedia-operator/openclaw_setting_sample.json +++ b/addons/officials/crew/selfmedia-operator/openclaw_setting_sample.json @@ -6,29 +6,21 @@ "youtube-upload", "xhs-content-ops", "xhs-interact", - "xhs-publisher", "juejin-publish", "toutiao-publish", "siliconflow-img-gen", - "siliconflow-video-gen", "pexels-footage", "pixabay-footage", "smart-search", "browser-guide", - "council" + "wxwork-moments", + "wxwork-drive", + "wx-mp-publisher", + "complex-task" ], "subagents": { - "allowAgents": ["it-engineer", "designer"] - }, - "heartbeat": { - "every": "3h", - "target": "last", - "isolatedSession": true, - "activeHours": { - "start": "08:00", - "end": "24:00", - "timezone": "user" - } + "allowAgents": ["it-engineer", "designer", "video-producer"] }, + "maxConcurrent": 2, "tools": {} } diff --git a/addons/officials/crew/selfmedia-operator/skills/douyin-publish/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/douyin-publish/SKILL.md new file mode 100644 index 00000000..673b37e6 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/douyin-publish/SKILL.md @@ -0,0 +1,106 @@ +--- +name: douyin-publish +description: Publish videos to Douyin (抖音) via open platform API with OAuth2 authentication. + Supports video upload, cover image, hashtags, and privacy settings. Requires Douyin + open platform OAuth2 credentials. +metadata: + openclaw: + emoji: 🎤 + requires: + bins: + - python3 +--- + +# 抖音视频发布（douyin-publish） + +通过抖音开放平台 API 发布视频，支持视频上传、封面、话题标签。使用 OAuth2 认证。 + +--- + +## 前置条件 + +1. 抖音开放平台创建应用，获取 client_key / client_secret +2. 申请「视频管理」权限范围 +3. 首次运行需浏览器授权，后续自动使用 refresh token + +--- + +## 配置 + +保存到 `~/.openclaw/credentials/douyin_config.json`： + +```json +{ + "client_key": "your_client_key", + "client_secret": "your_client_secret", + "redirect_uri": "https://localhost:8080/callback" +} +``` + +首次授权后 token 保存到 `~/.openclaw/credentials/douyin_token.json` + +--- + +## 使用方式 + +```bash +python3 ./skills/douyin-publish/scripts/publish_douyin.py \ + --title "视频标题" \ + --video video.mp4 \ + --cover cover.jpg \ + --tags 话题1,话题2 +``` + +--- + +## 参数说明 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--title` | 是 | 视频标题，最多 55 字 | +| `--video` | 是 | 视频文件路径，支持 mp4，建议 9:16 | +| `--cover` | 否 | 封面图 URL 或本地路径 | +| `--tags` | 否 | 逗号分隔的话题标签 | +| `--private` | 否 | 设为仅自己可见 | + +--- + +## Agent 工作流 + +1. 检查抖音配置和 token +2. 准备视频 + 标题 +3. 运行 `publish_douyin.py` 脚本 +4. 检查 stdout JSON 输出： + - `{"ok": true, "item_id": "xxx", "url": "https://www.douyin.com/video/xxx"}` → 成功 + - `{"ok": false, "error": "AUTH_REQUIRED"}` → 需要完成 OAuth2 授权 + - `{"ok": false, "error": "..."}` → 其他错误 + +--- + +## 错误处理 + +| 错误 | 原因 | 处理 | +|------|------|------| +| AUTH_REQUIRED | 无有效 OAuth2 token | 提示用户完成授权 | +| UPLOAD_FAILED | 上传失败 | 检查文件格式，重试一次 | +| PUBLISH_FAILED | 发布失败 | 检查权限和内容合规性 | +| QUOTA_EXCEEDED | API 调用频率限制 | 等待后重试 | + +## 发布记录（强制） + +发布成功后，**必须**立即调用 `published-track` 技能记录发布信息： + +```bash +./skills/published-track/scripts/record.sh \ + --platform douyin \ + --title "标题" \ + --content-type video \ + --source-folder "<原始文件夹路径>" \ + --publish-url "<发布URL>" \ + --publish-date "$(date +%Y-%m-%d)" +``` + +`--source-folder` 为原始内容所在的相对路径（如 `output_articles/xxx` 或 `output_videos/xxx`）。 +`--publish-url` 为发布后获得的 URL，若发布失败则留空并在 `--notes` 中注明原因。 + +执行 `./skills/published-track/scripts/init-db.sh`（幂等，重复执行无副作用）。 diff --git a/addons/officials/crew/selfmedia-operator/skills/douyin-publish/scripts/publish_douyin.py b/addons/officials/crew/selfmedia-operator/skills/douyin-publish/scripts/publish_douyin.py new file mode 100755 index 00000000..4ec96953 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/douyin-publish/scripts/publish_douyin.py @@ -0,0 +1,206 @@ +#!/usr/bin/env python3 +"""Publish videos to Douyin via open platform API with OAuth2.""" + +import argparse +import hashlib +import json +import os +import sys +import time +import uuid +from pathlib import Path + +import requests + +CREDS_DIR = Path.home() / ".openclaw" / "credentials" +CONFIG_FILE = CREDS_DIR / "douyin_config.json" +TOKEN_FILE = CREDS_DIR / "douyin_token.json" +DOUYIN_API = "https://open.douyin.com" + + +def output(data: dict) -> None: + sys.stdout.write(json.dumps(data, ensure_ascii=False) + "\n") + + +def err_exit(msg: str, code: int = 1) -> None: + sys.stderr.write(f"[douyin-publish] ERROR: {msg}\n") + output({"ok": False, "error": msg}) + sys.exit(code) + + +def load_config() -> dict: + if not CONFIG_FILE.exists(): + err_exit("AUTH_REQUIRED: no douyin_config.json", 2) + return json.loads(CONFIG_FILE.read_text()) + + +def load_token() -> dict: + if not TOKEN_FILE.exists(): + err_exit("AUTH_REQUIRED", 2) + return json.loads(TOKEN_FILE.read_text()) + + +def refresh_access_token(config: dict, token_data: dict) -> str: + refresh_token = token_data.get("refresh_token", "") + if not refresh_token: + err_exit("AUTH_REQUIRED: no refresh token", 2) + + resp = requests.post( + f"{DOUYIN_API}/oauth/refresh_token/", + data={ + "client_key": config["client_key"], + "client_secret": config["client_secret"], + "grant_type": "refresh_token", + "refresh_token": refresh_token, + }, + headers={"Content-Type": "application/x-www-form-urlencoded"}, + timeout=30, + ) + if resp.status_code != 200: + err_exit(f"AUTH_REQUIRED: refresh failed: {resp.text}", 2) + + data = resp.json() + token_info = data.get("data", {}) + if token_info.get("error_code") != 0: + err_exit(f"AUTH_REQUIRED: {token_info.get('description', data)}", 2) + + new_token = { + "access_token": token_info.get("access_token", ""), + "refresh_token": token_info.get("refresh_token", refresh_token), + "expires_in": token_info.get("expires_in", 0), + "open_id": token_info.get("open_id", token_data.get("open_id", "")), + } + CREDS_DIR.mkdir(parents=True, exist_ok=True) + TOKEN_FILE.write_text(json.dumps(new_token, indent=2)) + return new_token["access_token"] + + +def upload_video(access_token: str, open_id: str, video_path: str) -> str: + url = f"{DOUYIN_API}/api/douyin/v1/video/upload_video/" + file_size = os.path.getsize(video_path) + filename = os.path.basename(video_path) + + with open(video_path, "rb") as f: + resp = requests.post( + url, + headers={"access-token": access_token}, + params={"open_id": open_id}, + files={"video": (filename, f, "video/mp4")}, + timeout=300, + ) + + if resp.status_code in (401, 403): + err_exit("AUTH_REQUIRED", 2) + data = resp.json() + if data.get("data", {}).get("error_code") != 0: + err_exit(f"UPLOAD_FAILED: {data.get('data', {}).get('description', data)}") + + video_id = data.get("data", {}).get("video", {}).get("video_id", "") + if not video_id: + err_exit(f"UPLOAD_FAILED: no video_id: {data}") + return video_id + + +def upload_cover(access_token: str, open_id: str, cover_path: str) -> str: + url = f"{DOUYIN_API}/api/douyin/v1/video/upload_cover/" + with open(cover_path, "rb") as f: + resp = requests.post( + url, + headers={"access-token": access_token}, + params={"open_id": open_id}, + files={"image": ("cover.jpg", f, "image/jpeg")}, + timeout=60, + ) + data = resp.json() + return data.get("data", {}).get("image", {}).get("image_url", "") + + +def create_video( + access_token: str, open_id: str, + video_id: str, title: str, cover_url: str, + tags: list[str], is_private: bool, +) -> dict: + url = f"{DOUYIN_API}/api/douyin/v1/video/create_video/" + text = title + if tags: + text += " " + " ".join(f"#{t}" for t in tags) + + payload = { + "video_id": video_id, + "text": text[:55], + } + if cover_url: + payload["cover_url"] = cover_url + if is_private: + payload["private"] = True + + resp = requests.post( + url, + headers={ + "access-token": access_token, + "Content-Type": "application/json", + }, + params={"open_id": open_id}, + json=payload, + timeout=30, + ) + + if resp.status_code in (401, 403): + err_exit("AUTH_REQUIRED", 2) + data = resp.json() + if data.get("data", {}).get("error_code") != 0: + msg = data.get("data", {}).get("description", str(data)) + if "login" in msg.lower() or "登录" in msg: + err_exit("AUTH_REQUIRED", 2) + err_exit(f"PUBLISH_FAILED: {msg}") + + item_id = data.get("data", {}).get("item_id", "") + return {"ok": True, "item_id": item_id, "url": f"https://www.douyin.com/video/{item_id}"} + + +def main() -> None: + parser = argparse.ArgumentParser(description="Publish video to Douyin") + parser.add_argument("--title", required=True, help="Video title (max 55 chars)") + parser.add_argument("--video", required=True, help="Video file path") + parser.add_argument("--cover", help="Cover image path") + parser.add_argument("--tags", default="", help="Comma-separated tags") + parser.add_argument("--private", action="store_true", help="Set to private") + args = parser.parse_args() + + if not os.path.exists(args.video): + err_exit(f"UPLOAD_FAILED: video not found: {args.video}") + + config = load_config() + token_data = load_token() + + try: + access_token = refresh_access_token(config, token_data) + except SystemExit: + raise + except Exception as e: + err_exit(f"AUTH_REQUIRED: {e}", 2) + + open_id = token_data.get("open_id", "") + if not open_id: + err_exit("AUTH_REQUIRED: no open_id in token", 2) + + sys.stderr.write("[douyin-publish] uploading video...\n") + video_id = upload_video(access_token, open_id, args.video) + + cover_url = "" + if args.cover and os.path.exists(args.cover): + sys.stderr.write("[douyin-publish] uploading cover...\n") + cover_url = upload_cover(access_token, open_id, args.cover) + + tags = [t.strip() for t in args.tags.split(",") if t.strip()] if args.tags else [] + + sys.stderr.write("[douyin-publish] creating video post...\n") + result = create_video( + access_token, open_id, video_id, args.title, cover_url, + tags, args.private, + ) + output(result) + + +if __name__ == "__main__": + main() diff --git a/addons/officials/crew/selfmedia-operator/skills/facebook-publish/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/facebook-publish/SKILL.md new file mode 100644 index 00000000..716e72fc --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/facebook-publish/SKILL.md @@ -0,0 +1,125 @@ +--- +name: facebook-publish +description: Publish posts, videos, and reels to Facebook via Meta Graph API v23.0. + Supports feed posts, video posts, photo posts, reels, and stories. Requires Meta + OAuth2 page access token. +metadata: + openclaw: + emoji: 📘 + requires: + bins: + - python3 +--- + +# Facebook 发布（facebook-publish） + +通过 Meta Graph API v23.0 发布内容到 Facebook，支持帖子、视频、Reels 和 Stories。使用 Meta OAuth2 Page Access Token 认证。 + +--- + +## 前置条件 + +1. Meta Developer Portal 创建应用，获取 App ID / App Secret +2. 申请 `pages_manage_posts` 和 `pages_read_engagement` 权限 +3. 获取长效 Page Access Token + +--- + +## 配置 + +保存到 `~/.openclaw/credentials/facebook_config.json`： + +```json +{ + "app_id": "your_app_id", + "app_secret": "your_app_secret", + "page_access_token": "your_long_lived_page_token", + "page_id": "your_page_id" +} +``` + +--- + +## 使用方式 + +文字帖子： + +```bash +python3 ./skills/facebook-publish/scripts/publish_facebook.py \ + --message "帖子内容" \ + --mode feed +``` + +视频/Reel： + +```bash +python3 ./skills/facebook-publish/scripts/publish_facebook.py \ + --message "描述" \ + --video video.mp4 \ + --mode reel +``` + +图片帖子： + +```bash +python3 ./skills/facebook-publish/scripts/publish_facebook.py \ + --message "描述" \ + --images img1.jpg img2.jpg \ + --mode feed +``` + +--- + +## 参数说明 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--message` | 是 | 帖子内容 | +| `--mode` | 是 | `feed`/`video`/`reel`/`story` | +| `--video` | 视频模式必填 | 视频文件路径 | +| `--images` | 图片模式必填 | 图片路径列表 | +| `--title` | 否 | 视频标题（video 模式） | + +--- + +## Agent 工作流 + +1. 检查 Facebook 配置是否存在 +2. 准备内容 + 媒体文件 +3. 运行 `publish_facebook.py` 脚本 +4. 检查 stdout JSON 输出： + - `{"ok": true, "post_id": "xxx", "url": "https://facebook.com/xxx"}` → 成功 + - `{"ok": false, "error": "AUTH_REQUIRED"}` → 更新 Page Token + - `{"ok": false, "error": "..."}` → 其他错误 + +--- + +## 错误处理 + +| 错误 | 原因 | 处理 | +|------|------|------| +| AUTH_REQUIRED | Token 失效 | 更新 Page Access Token | +| UPLOAD_FAILED | 上传失败 | 检查文件格式，重试 | +| MEDIA_PROCESSING | 视频处理中 | 轮询状态等待完成 | +| RATE_LIMIT | 频率限制 | 等待后重试 | + +--- + +## 发布记录（强制） + +发布成功后，**必须**立即调用 `published-track` 技能记录发布信息： + +```bash +./skills/published-track/scripts/record.sh \ + --platform facebook \ + --title "标题" \ + --content-type post \ + --source-folder "<原始文件夹路径>" \ + --publish-url "<发布URL>" \ + --publish-date "$(date +%Y-%m-%d)" +``` + +`--source-folder` 为原始内容所在的相对路径（如 `output_articles/xxx` 或 `output_videos/xxx`）。 +`--publish-url` 为发布后获得的 URL，若发布失败则留空并在 `--notes` 中注明原因。 + +执行 `./skills/published-track/scripts/init-db.sh`（幂等，重复执行无副作用）。 diff --git a/addons/officials/crew/selfmedia-operator/skills/facebook-publish/scripts/publish_facebook.py b/addons/officials/crew/selfmedia-operator/skills/facebook-publish/scripts/publish_facebook.py new file mode 100755 index 00000000..a8f2eeb1 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/facebook-publish/scripts/publish_facebook.py @@ -0,0 +1,168 @@ +#!/usr/bin/env python3 +"""Publish posts, videos, and reels to Facebook via Meta Graph API v23.0.""" + +import argparse +import json +import os +import sys +import time +from pathlib import Path + +import requests + +CREDS_DIR = Path.home() / ".openclaw" / "credentials" +CONFIG_FILE = CREDS_DIR / "facebook_config.json" +GRAPH_API = "https://graph.facebook.com/v23.0" + + +def output(data: dict) -> None: + sys.stdout.write(json.dumps(data, ensure_ascii=False) + "\n") + + +def err_exit(msg: str, code: int = 1) -> None: + sys.stderr.write(f"[facebook-publish] ERROR: {msg}\n") + output({"ok": False, "error": msg}) + sys.exit(code) + + +def load_config() -> dict: + if not CONFIG_FILE.exists(): + err_exit("AUTH_REQUIRED: no facebook_config.json", 2) + return json.loads(CONFIG_FILE.read_text()) + + +def api_get(path: str, token: str, params: dict | None = None) -> dict: + p = {"access_token": token, **(params or {})} + resp = requests.get(f"{GRAPH_API}{path}", params=p, timeout=30) + if resp.status_code in (401, 403): + err_exit("AUTH_REQUIRED", 2) + data = resp.json() + if "error" in data: + err_exit(f"API_ERROR: {data['error'].get('message', data)}") + return data + + +def api_post(path: str, token: str, data: dict | None = None, files: dict | None = None) -> dict: + params = {"access_token": token} + if data and not files: + resp = requests.post(f"{GRAPH_API}{path}", params=params, json=data, timeout=120) + elif files: + resp = requests.post(f"{GRAPH_API}{path}", params=params, files=files, data=data, timeout=300) + else: + resp = requests.post(f"{GRAPH_API}{path}", params=params, timeout=30) + if resp.status_code in (401, 403): + err_exit("AUTH_REQUIRED", 2) + result = resp.json() + if "error" in result: + err_exit(f"API_ERROR: {result['error'].get('message', result)}") + return result + + +def publish_feed_post(page_id: str, token: str, message: str, image_paths: list[str] | None = None) -> dict: + if image_paths: + path = f"/{page_id}/photos" + if len(image_paths) == 1: + with open(image_paths[0], "rb") as f: + result = api_post(path, token, data={"message": message}, files={"source": f}) + post_id = result.get("post_id", result.get("id", "")) + else: + uploaded_ids = [] + for img_path in image_paths: + with open(img_path, "rb") as f: + r = api_post(path, token, data={"published": "false"}, files={"source": f}) + uploaded_ids.append(r["id"]) + result = api_post(f"/{page_id}/feed", token, data={ + "message": message, + "attached_media": json.dumps([{"media_fbid": mid} for mid in uploaded_ids]), + }) + post_id = result.get("id", "") + else: + result = api_post(f"/{page_id}/feed", token, data={"message": message}) + post_id = result.get("id", "") + + return {"ok": True, "post_id": post_id, "url": f"https://facebook.com/{post_id}"} + + +def publish_video(page_id: str, token: str, video_path: str, title: str, description: str) -> dict: + file_size = os.path.getsize(video_path) + start = api_post(f"/{page_id}/videos", token, data={ + "upload_phase": "start", + "file_size": file_size, + }) + upload_session_id = start.get("upload_session_id", "") + video_id = start.get("video_id", "") + + chunk_size = 4 * 1024 * 1024 + with open(video_path, "rb") as f: + offset = 0 + while True: + chunk = f.read(chunk_size) + if not chunk: + break + api_post(f"/{page_id}/videos", token, files={"video_file_chunk": chunk}, data={ + "upload_phase": "transfer", + "upload_session_id": upload_session_id, + "start_offset": str(offset), + }) + offset += len(chunk) + + api_post(f"/{page_id}/videos", token, data={ + "upload_phase": "finish", + "upload_session_id": upload_session_id, + "title": title, + "description": description, + }) + + return {"ok": True, "post_id": video_id, "url": f"https://facebook.com/{video_id}"} + + +def publish_reel(page_id: str, token: str, video_path: str, description: str) -> dict: + init = api_post(f"/{page_id}/video_reels", token, data={"upload_phase": "start"}) + upload_url = init.get("upload_url", "") + video_id = init.get("video_id", "") + + with open(video_path, "rb") as f: + requests.put(upload_url, data=f, timeout=300) + + api_post(f"/{page_id}/video_reels", token, data={ + "upload_phase": "finish", + "video_id": video_id, + "title": description[:255] if description else "", + }) + + return {"ok": True, "post_id": video_id, "url": f"https://facebook.com/reel/{video_id}"} + + +def main() -> None: + parser = argparse.ArgumentParser(description="Publish to Facebook") + parser.add_argument("--message", required=True, help="Post message/caption") + parser.add_argument("--mode", required=True, choices=["feed", "video", "reel", "story"]) + parser.add_argument("--video", help="Video file path") + parser.add_argument("--images", nargs="+", help="Image file paths") + parser.add_argument("--title", default="", help="Video title") + args = parser.parse_args() + + config = load_config() + token = config.get("page_access_token", "") + page_id = config.get("page_id", "") + if not token or not page_id: + err_exit("AUTH_REQUIRED: missing token or page_id", 2) + + if args.mode == "feed": + result = publish_feed_post(page_id, token, args.message, args.images) + elif args.mode == "video": + if not args.video: + err_exit("--video required for video mode") + result = publish_video(page_id, token, args.video, args.title, args.message) + elif args.mode == "reel": + if not args.video: + err_exit("--video required for reel mode") + result = publish_reel(page_id, token, args.video, args.message) + else: + err_exit(f"story mode not yet implemented") + + output(result) + + +if __name__ == "__main__": + main() diff --git a/addons/officials/crew/selfmedia-operator/skills/highlight-clipper/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/highlight-clipper/SKILL.md new file mode 100644 index 00000000..20528391 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/highlight-clipper/SKILL.md @@ -0,0 +1,135 @@ +--- +name: highlight-clipper +description: 自动从本地视频中提取高光片段。通过 ASR 转录 + 文本分析识别高光时刻，剪辑输出多段短视频。 +metadata: + openclaw: + emoji: "✂️" + requires: + bins: + - python3 + - ffmpeg + - ffprobe + env: + - SILICONFLOW_API_KEY + primaryEnv: SILICONFLOW_API_KEY +--- + +# highlight-clipper — 视频高光剪辑 + +Use this skill when: +- 用户提供一个本地视频文件，希望自动剪辑出高光片段 +- 需要从长视频中提取精彩片段用于二次分发（抖音/小红书/B站短视频等） + +**不适用场景**：纯音乐或无声视频（依赖语音内容识别高光）、画面精彩但无语音的片段。 + +--- + +## 工作流程 + +### Step 1 — 创建输出目录 + +在 `output_videos/` 下创建项目目录： + +```bash +mkdir -p output_videos/ +``` + +### Step 2 — 运行高光剪辑 + +```bash +python3 ./skills/highlight-clipper/scripts/clip.py --out-dir output_videos/ +``` + +参数说明： + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `` | — | 源视频文件路径（必需） | +| `--out-dir` | — | 输出目录，必须在 `output_videos/` 或 `tmp/` 下（必需） | +| `--count` | 3 | 提取高光片段数量 | +| `--min-duration` | 15 | 最短片段时长（秒） | +| `--max-duration` | 60 | 最长片段时长（秒） | +| `--buffer` | 3 | 片段前后缓冲（秒） | + +示例 — 从一段 5 分钟视频提取 5 个高光： + +```bash +python3 ./skills/highlight-clipper/scripts/clip.py output_videos/my-video/video.mp4 --out-dir output_videos/my-video --count 5 +``` + +### Step 3 — 查看结果 + +脚本产出： + +``` +output_videos// +├── highlight_01.mp4 # 高光片段 1 +├── highlight_02.mp4 # 高光片段 2 +├── highlight_03.mp4 # 高光片段 3 +└── highlights.json # 高光分析报告 +``` + +`highlights.json` 包含完整转录文本、每个片段的时间戳、评分和文案： + +```json +{ + "source_video": "video.mp4", + "video_duration": 180.5, + "highlight_count": 3, + "full_transcript": "...", + "highlights": [ + { + "index": 1, + "file": "highlight_01.mp4", + "start": 12.0, + "end": 45.0, + "duration": 33.0, + "text": "这才是最关键的一步...", + "score": 8.5 + } + ] +} +``` + +查看报告： + +```bash +cat output_videos//highlights.json +``` + +### Step 4 — 后续处理（可选） + +对高光片段做进一步加工： +- 使用 `t2video` 为片段添加配音或封面 +- 使用各平台发布技能（`douyin-publish`、`xhs-publish` 等）发布 + +--- + +## 技术原理 + +1. **音频提取**：ffmpeg 从视频中提取 16kHz 单声道 WAV +2. **ASR 转录**：SiliconFlow SenseVoiceSmall 模型，获取带时间戳的语音片段 +3. **高光评分**：对每个转录片段综合打分，考量： + - 情感强度词（"最"、"超"、"非常"等）— 权重 2.0 + - 转折/惊喜词（"但是"、"没想到"、"原来"等）— 权重 3.0 + - 行动号召词（"赶紧"、"收藏"、"关注"等）— 权重 2.5 + - 疑问句和感叹号 — 权重 1.5 + - 数据/数字出现 — 权重 1.0 + - 信息密度（单位时长文字量）— 权重最高 3.0 +4. **多样性选择**：贪婪选取得分最高的 N 个片段，保证片段间至少间隔 30 秒，避免高光扎堆 +5. **视频剪辑**：ffmpeg 精确裁剪，含前后缓冲秒数 + +--- + +## 长视频处理 + +视频超过 5 分钟时，脚本自动分块转录（每块 5 分钟），合并时间戳后统一分析。无需手动干预。 + +--- + +## 注意事项 + +- 源视频必须有语音内容，纯音乐或无声视频无法识别高光 +- 转录质量取决于语音清晰度，建议使用语音清晰的视频 +- 高光评分基于文本语义分析，非视觉分析——画面精彩但无语音的片段可能被遗漏 +- 片段时长受 `--min-duration` 和 `--max-duration` 控制，可根据目标平台要求调整（如抖音 15–60 秒、小红书 15–45 秒） diff --git a/addons/officials/crew/selfmedia-operator/skills/highlight-clipper/scripts/clip.py b/addons/officials/crew/selfmedia-operator/skills/highlight-clipper/scripts/clip.py new file mode 100644 index 00000000..87b86579 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/highlight-clipper/scripts/clip.py @@ -0,0 +1,441 @@ +#!/usr/bin/env python3 +"""highlight-clipper — Extract highlight clips from a local video. + +Flow: + 1. Extract audio via ffmpeg (16kHz mono WAV) + 2. Transcribe via SiliconFlow ASR (SenseVoiceSmall with timestamps) + 3. Score transcript segments for highlight potential + 4. Select top-N diverse highlights + 5. Clip each highlight with ffmpeg + +Usage: + python3 ./skills/highlight-clipper/scripts/clip.py --out-dir [options] +""" + +import argparse +import gc +import json +import mimetypes +import os +import re +import shutil +import subprocess +import sys +import tempfile +import urllib.error +import urllib.request +import uuid +from pathlib import Path + +ASR_URL = "https://api.siliconflow.cn/v1/audio/transcriptions" +DEFAULT_ASR_MODEL = "FunAudioLLM/SenseVoiceSmall" +CHUNK_DURATION = 300 # 5 min per ASR chunk +DEFAULT_COUNT = 3 +DEFAULT_BUFFER = 3.0 +DEFAULT_CLIP_MIN = 15 +DEFAULT_CLIP_MAX = 60 +MIN_HIGHLIGHT_GAP = 30 # min seconds between highlight starts + +SAFE_OUTPUT_DIRS = (Path("output_videos"), Path("tmp")) + +# ── Highlight scoring keywords ────────────────────────────────────────── + +EMPHASIS_WORDS = frozenset({ + "最", "极", "超", "非常", "特别", "真的", "绝对", "必须", "一定", "千万", + "竟然", "居然", "简直", "太", "极其", "无比", "惊人", "震撼", "炸裂", + "逆天", "离谱", "夸张", "恐怖", "神奇", "绝了", "史上", "顶级", "终极", +}) +CONTRAST_WORDS = frozenset({ + "但是", "然而", "可是", "不过", "其实", "没想到", "殊不知", "结果", "原来", +}) +CTA_WORDS = frozenset({ + "赶紧", "快", "别", "不要", "一定要", "记得", "收藏", "关注", "点赞", + "转发", "下单", "链接", +}) +QUESTION_MARKS = frozenset({"？", "?", "吗", "呢", "嘛", "吧", "如何", "怎么", "为什么", "为啥"}) + + +# ── Utilities ─────────────────────────────────────────────────────────── + +def die(msg: str) -> None: + print(f"[error] {msg}", file=sys.stderr) + sys.exit(1) + + +def _tail_file(path: str, max_chars: int) -> str: + """Read the last N characters of a file without loading the whole thing.""" + try: + size = os.path.getsize(path) + if size <= max_chars: + with open(path, "r", errors="replace") as f: + return f.read() + with open(path, "rb") as f: + f.seek(size - max_chars) + f.readline() + return f.read().decode(errors="replace") + except OSError: + return "" + + +def ensure_safe_output_dir(raw_path: str) -> Path: + path = Path(raw_path) + if path.is_absolute(): + die("output path must be relative to the workspace") + if ".." in path.parts: + die("output path must not contain '..'") + resolved = (Path.cwd() / path).resolve() + for base in SAFE_OUTPUT_DIRS: + base_resolved = (Path.cwd() / base).resolve() + if resolved == base_resolved or resolved.is_relative_to(base_resolved): + return resolved + allowed = ", ".join(str(d) for d in SAFE_OUTPUT_DIRS) + die(f"output path must be under one of: {allowed}") + + +# ── Media probing ─────────────────────────────────────────────────────── + +def probe_duration(filepath: str) -> float: + try: + result = subprocess.run( + ["ffprobe", "-v", "quiet", "-print_format", "json", + "-show_format", filepath], + capture_output=True, text=True, timeout=15, + ) + if result.returncode == 0: + data = json.loads(result.stdout) + return float(data.get("format", {}).get("duration", 0)) + except (subprocess.TimeoutExpired, json.JSONDecodeError, ValueError): + pass + return 0.0 + + +# ── Audio extraction ──────────────────────────────────────────────────── + +def extract_audio_chunk(video_path: str, output_path: str, + start: float = 0, duration: float | None = None) -> str: + cmd = ["ffmpeg", "-y"] + if start > 0: + cmd.extend(["-ss", str(start)]) + cmd.extend(["-i", video_path, "-vn", "-ar", "16000", "-ac", "1", "-f", "wav"]) + if duration is not None: + cmd.extend(["-t", str(duration)]) + cmd.append(output_path) + with tempfile.NamedTemporaryFile(mode="w", suffix=".log", delete=False) as stderr_f: + stderr_path = stderr_f.name + try: + with open(stderr_path, "w") as stderr_fh: + result = subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=stderr_fh, text=True, timeout=120) + if result.returncode != 0: + tail = _tail_file(stderr_path, 500) + die(f"Audio extraction failed: {tail}") + finally: + try: + os.unlink(stderr_path) + except OSError: + pass + if not os.path.exists(output_path): + die(f"Audio file not created: {output_path}") + return output_path + + +# ── ASR ───────────────────────────────────────────────────────────────── + +def build_multipart_formdata(file_path: str, fields: dict[str, str]) -> tuple[bytes, str]: + boundary = f"----HLClipper{uuid.uuid4().hex}" + filename = os.path.basename(file_path) + content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream" + parts: list[bytes] = [] + parts.append( + ( + f"--{boundary}\r\n" + f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n' + f"Content-Type: {content_type}\r\n\r\n" + ).encode("utf-8") + ) + with open(file_path, "rb") as f: + parts.append(f.read()) + parts.append(b"\r\n") + for name, value in fields.items(): + parts.append( + ( + f"--{boundary}\r\n" + f'Content-Disposition: form-data; name="{name}"\r\n\r\n' + f"{value}\r\n" + ).encode("utf-8") + ) + parts.append(f"--{boundary}--\r\n".encode("utf-8")) + return b"".join(parts), f"multipart/form-data; boundary={boundary}" + + +def call_asr(audio_path: str) -> dict: + api_key = os.environ.get("SILICONFLOW_API_KEY", "").strip() + if not api_key: + die("SILICONFLOW_API_KEY not set") + model = os.environ.get("ASR_MODEL", DEFAULT_ASR_MODEL).strip() or DEFAULT_ASR_MODEL + body, content_type = build_multipart_formdata(audio_path, {"model": model}) + req = urllib.request.Request(ASR_URL, data=body, method="POST") + req.add_header("Authorization", f"Bearer {api_key}") + req.add_header("Content-Type", content_type) + try: + with urllib.request.urlopen(req, timeout=120) as resp: + return json.loads(resp.read().decode()) + except urllib.error.HTTPError as e: + err_body = e.read().decode(errors="replace") + die(f"ASR API failed (HTTP {e.code}): {err_body}") + except urllib.error.URLError as e: + die(f"ASR request failed: {e.reason}") + + +def estimate_segments(text: str, duration: float, offset: float = 0) -> list[dict]: + """Estimate segment timestamps when ASR doesn't return them.""" + sentences = re.split(r"[。！？!?；;\n]", text) + sentences = [s.strip() for s in sentences if s.strip()] + if not sentences: + return [] + total_chars = sum(len(s) for s in sentences) + if total_chars == 0: + return [] + segments = [] + current_time = offset + for s in sentences: + seg_duration = (len(s) / total_chars) * duration + segments.append({ + "start": round(current_time, 2), + "end": round(current_time + seg_duration, 2), + "text": s, + }) + current_time += seg_duration + return segments + + +def transcribe_video(video_path: str, tmp_dir: str, video_duration: float) -> tuple[str, list[dict]]: + """Transcribe video audio, chunking long videos automatically.""" + all_segments: list[dict] = [] + all_text_parts: list[str] = [] + + if video_duration <= CHUNK_DURATION: + audio_path = os.path.join(tmp_dir, "audio.wav") + extract_audio_chunk(video_path, audio_path) + result = call_asr(audio_path) + segments = result.get("segments", []) + text = result.get("text", "") + if segments: + all_segments.extend(segments) + elif text: + all_segments.extend(estimate_segments(text, video_duration)) + all_text_parts.append(text) + else: + offset = 0.0 + chunk_idx = 0 + while offset < video_duration: + chunk_idx += 1 + audio_path = os.path.join(tmp_dir, f"audio_{chunk_idx}.wav") + chunk_dur = min(CHUNK_DURATION, video_duration - offset) + extract_audio_chunk(video_path, audio_path, start=offset, duration=chunk_dur) + result = call_asr(audio_path) + segments = result.get("segments", []) + text = result.get("text", "") + if segments: + for seg in segments: + all_segments.append({ + "start": seg.get("start", 0) + offset, + "end": seg.get("end", 0) + offset, + "text": seg.get("text", ""), + }) + elif text: + all_segments.extend(estimate_segments(text, chunk_dur, offset)) + all_text_parts.append(text) + offset += CHUNK_DURATION + + return " ".join(all_text_parts), all_segments + + +# ── Highlight scoring ─────────────────────────────────────────────────── + +def score_segment(text: str) -> float: + if not text or not text.strip(): + return 0.0 + score = 0.0 + for w in EMPHASIS_WORDS: + if w in text: + score += 2.0 + for w in CONTRAST_WORDS: + if w in text: + score += 3.0 + for w in CTA_WORDS: + if w in text: + score += 2.5 + for m in QUESTION_MARKS: + if m in text: + score += 1.5 + score += min(len(re.findall(r"\d+\.?\d*%?", text)), 3) * 1.0 + score += (text.count("!") + text.count("！")) * 1.5 + score += min(len(text.strip()) / 20, 3.0) + return score + + +def select_highlights(segments: list[dict], count: int) -> list[dict]: + if not segments: + return [] + valid = [s for s in segments if s.get("end", 0) - s.get("start", 0) >= 1.0] + if not valid: + valid = segments + scored = [{**s, "highlight_score": score_segment(s.get("text", ""))} for s in valid] + scored.sort(key=lambda s: s["highlight_score"], reverse=True) + selected = [] + for seg in scored: + if len(selected) >= count: + break + start = seg.get("start", 0) + if not any(abs(start - s.get("start", 0)) < MIN_HIGHLIGHT_GAP for s in selected): + selected.append(seg) + if len(selected) < count: + remaining = [s for s in scored if s not in selected] + for seg in remaining: + if len(selected) >= count: + break + selected.append(seg) + selected.sort(key=lambda s: s.get("start", 0)) + return selected + + +# ── Video clipping ────────────────────────────────────────────────────── + +def determine_clip_bounds(seg: dict, video_duration: float, + buffer: float, clip_min: float, clip_max: float) -> tuple[float, float]: + seg_start = seg.get("start", 0) + seg_end = seg.get("end", 0) + seg_duration = seg_end - seg_start + target = max(seg_duration + buffer * 2, clip_min) + target = min(target, clip_max) + clip_start = max(seg_start - buffer, 0) + clip_end = min(clip_start + target, video_duration) + if clip_end - clip_start < clip_min: + clip_start = max(clip_end - target, 0) + return round(clip_start, 2), round(clip_end, 2) + + +def clip_video(video_path: str, start: float, end: float, output_path: str) -> None: + duration = end - start + cmd = [ + "ffmpeg", "-y", + "-ss", str(start), "-i", video_path, "-t", str(duration), + "-c:v", "libx264", "-preset", "fast", "-crf", "23", + "-c:a", "aac", "-b:a", "128k", + "-movflags", "+faststart", + output_path, + ] + with tempfile.NamedTemporaryFile(mode="w", suffix=".log", delete=False) as stderr_f: + stderr_path = stderr_f.name + try: + with open(stderr_path, "w") as stderr_fh: + result = subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=stderr_fh, text=True, timeout=120) + if result.returncode != 0: + tail = _tail_file(stderr_path, 500) + die(f"ffmpeg clip failed: {tail}") + finally: + try: + os.unlink(stderr_path) + except OSError: + pass + if not os.path.exists(output_path) or os.path.getsize(output_path) == 0: + die(f"Clip output missing or empty: {output_path}") + gc.collect() + + +# ── Main ──────────────────────────────────────────────────────────────── + +def main() -> None: + parser = argparse.ArgumentParser(description="Extract highlight clips from a local video") + parser.add_argument("video_path", help="Path to the source video file") + parser.add_argument("--out-dir", required=True, dest="out_dir", + help="Output directory under output_videos/ or tmp/") + parser.add_argument("--count", type=int, default=DEFAULT_COUNT, + help=f"Number of highlights (default: {DEFAULT_COUNT})") + parser.add_argument("--min-duration", type=float, default=DEFAULT_CLIP_MIN, dest="min_duration", + help=f"Minimum clip duration seconds (default: {DEFAULT_CLIP_MIN})") + parser.add_argument("--max-duration", type=float, default=DEFAULT_CLIP_MAX, dest="max_duration", + help=f"Maximum clip duration seconds (default: {DEFAULT_CLIP_MAX})") + parser.add_argument("--buffer", type=float, default=DEFAULT_BUFFER, + help=f"Buffer seconds before/after segment (default: {DEFAULT_BUFFER})") + args = parser.parse_args() + + if not os.path.isfile(args.video_path): + die(f"Video file not found: {args.video_path}") + + out_dir = ensure_safe_output_dir(args.out_dir) + out_dir.mkdir(parents=True, exist_ok=True) + + video_duration = probe_duration(args.video_path) + if video_duration <= 0: + die(f"Cannot determine video duration: {args.video_path}") + print(f"[info] Video duration: {video_duration:.2f}s") + + tmp_dir = str(out_dir / "_tmp") + os.makedirs(tmp_dir, exist_ok=True) + + try: + print("[info] Extracting audio & transcribing...") + full_text, segments = transcribe_video(args.video_path, tmp_dir, video_duration) + + if not segments: + die("ASR returned no segments — cannot identify highlights") + + print(f"[info] Transcribed {len(segments)} segments") + + print("[info] Selecting highlights...") + highlights = select_highlights(segments, args.count) + + if not highlights: + die("No suitable highlights found") + + print(f"[info] Selected {len(highlights)} highlights") + + highlights_info = [] + for i, hl in enumerate(highlights, 1): + clip_start, clip_end = determine_clip_bounds( + hl, video_duration, args.buffer, args.min_duration, args.max_duration, + ) + clip_filename = f"highlight_{i:02d}.mp4" + clip_path = str(out_dir / clip_filename) + + print(f"[info] Clipping highlight {i}/{len(highlights)}: {clip_start:.1f}s – {clip_end:.1f}s") + clip_video(args.video_path, clip_start, clip_end, clip_path) + + clip_duration = probe_duration(clip_path) + clip_size = os.path.getsize(clip_path) / (1024 * 1024) + + highlights_info.append({ + "index": i, + "file": clip_filename, + "start": clip_start, + "end": clip_end, + "duration": round(clip_duration, 2), + "size_mb": round(clip_size, 2), + "text": hl.get("text", ""), + "score": round(hl.get("highlight_score", 0), 2), + }) + + report = { + "source_video": os.path.basename(args.video_path), + "video_duration": round(video_duration, 2), + "highlight_count": len(highlights_info), + "full_transcript": full_text, + "highlights": highlights_info, + } + report_path = str(out_dir / "highlights.json") + Path(report_path).write_text( + json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8", + ) + + print(f"[done] {len(highlights_info)} highlights saved to: {out_dir}") + for hl in highlights_info: + text_preview = hl["text"][:50] + "..." if len(hl["text"]) > 50 else hl["text"] + print(f" #{hl['index']}: {hl['start']:.1f}s–{hl['end']:.1f}s ({hl['duration']:.1f}s) — {text_preview}") + + finally: + shutil.rmtree(tmp_dir, ignore_errors=True) + + +if __name__ == "__main__": + main() diff --git a/addons/officials/crew/selfmedia-operator/skills/instagram-post/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/instagram-post/SKILL.md deleted file mode 100644 index 6ec40b77..00000000 --- a/addons/officials/crew/selfmedia-operator/skills/instagram-post/SKILL.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: instagram-post -description: Publish a photo, video, or carousel to Instagram using the browser. Supports - feed posts and Reels. -metadata: - openclaw: - emoji: 📸 ---- - -# Instagram 发布技能 - -Use this skill when: -- The user wants to publish a photo or video to Instagram Feed or Reels -- You need to cross-post an image or short video to Instagram -- You need to set caption, hashtags, and alt text - -**Prerequisites**: Browser session must be logged in to instagram.com. - ---- - -## 通用约束 - -- 文件上传前必须先复制到 `/tmp/openclaw/uploads/`（browser 工具沙箱限制） -- `browser upload` 工具可能返回「超时错误」，但这**不代表上传失败**！上传后用 snapshot 检查页面状态（预览图、下一步按钮是否可用） -- **不要通过检查 `input.files.length` 是否为 0 判定上传是否失败！** `input.files.length == 0` 不代表上传失败。 -- 遇到 `browser failed: timed out. Restart the OpenClaw gateway ...` 错误时，**不需要重启、不需要报错**！等待 30 秒后在原页面继续操作即可。若仍无法操作，再等 30 秒；若还不行，尝试关闭浏览器后重开；只有关闭重开后仍报错才是真的出错，需停止并反馈用户。 -- Caption 输入使用 `type` + `slowly: true`，不要用 `fill()` - ---- - -## Cookie Warmup - -Navigate to `https://www.instagram.com` first and confirm the feed loads (not a login screen). - ---- - -## Workflow: Post Photo or Single Video (Feed) - -``` -1. Navigate to https://www.instagram.com -2. Wait for feed to load -3. Click the "+" (Create) button in the top navigation bar (or left sidebar) -4. In the "Create new post" dialog, click "Post" -5. Click "Select from computer" and upload the media file - - Photo: JPG/PNG, min 1080px on shortest side (square 1:1 or 4:5 portrait recommended) - - Video: MP4/MOV, max 60 seconds for Feed, 15–90 seconds for Reels -6. Crop/resize the image if prompted (choose the appropriate aspect ratio) -7. Click "Next" -8. (Optional) Apply a filter or do manual adjustments → Click "Next" -9. On the caption screen: - - Write the caption (max 2200 characters) - - Add hashtags at the end (max 30 per post) - - Add location if relevant - - Add collaborators if needed - - Toggle "Advanced settings" for: - - Alt text (for accessibility) - - Audience restrictions -10. Click "Share" -11. Wait for confirmation and report the post URL -``` - ---- - -## Workflow: Post Reel (Short Video ≤ 90s) - -``` -1. Navigate to https://www.instagram.com -2. Click "+" → Select "Reel" -3. Upload video file (MP4/MOV, 9:16 preferred, max 90 seconds) -4. Trim clip if needed -5. Add audio (optional) — use original audio or select from Instagram's music library -6. Select cover frame -7. Click "Next" -8. Write caption + hashtags -9. Click "Share" -``` - ---- - -## Workflow: Carousel (Multiple Photos/Videos) - -``` -1. Click "+" → Post -2. Click the layers icon (Select Multiple) before choosing the first file -3. Select up to 10 photos/videos in order -4. Click "Next" twice (through filters screen) -5. Write caption + hashtags -6. Click "Share" -``` - ---- - -## Caption Best Practices - -- First sentence = hook (shown in feed preview) -- Main body: 2–4 sentences of context or story -- Hashtag block at end: mix popular (#instagram, #photography) with niche tags -- Emoji sparingly to increase personality -- Call to action (CTA) in last line: "Save this" / "Share with someone who needs this" - ---- - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Login screen appears | Session expired — inform user to re-login | -| File format not accepted | Convert to JPG/PNG (photos) or MP4 H.264 (video) | -| Video too long | Trim to 60s (Feed) or 90s (Reels) | -| Post button unavailable | Check if caption or media step is incomplete | -| "Action blocked" error | Account may have hit limits — wait 1 hour before retrying | - ---- - -## Notes - -- Instagram's UI evolves — navigate by intent if elements have moved -- Always confirm post URL or profile page after completion -- Do NOT post content that violates Instagram Community Standards diff --git a/addons/officials/crew/selfmedia-operator/skills/instagram-publish/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/instagram-publish/SKILL.md new file mode 100644 index 00000000..2709e43f --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/instagram-publish/SKILL.md @@ -0,0 +1,114 @@ +--- +name: instagram-publish +description: Publish posts and reels to Instagram via Meta Graph API. Supports single + images, carousels (up to 10), and reels. Uses content container pattern. Requires + Meta OAuth2 token with instagram_basic and instagram_content_publish permissions. +metadata: + openclaw: + emoji: 📸 + requires: + bins: + - python3 +--- + +# Instagram 发布（instagram-publish） + +通过 Meta Graph API 发布内容到 Instagram，支持单图、轮播（最多 10 张）和 Reels。使用 Content Container 模式。需要 Instagram Professional 账户关联到 Facebook Page。 + +--- + +## 前置条件 + +1. Instagram Professional 账户（Business 或 Creator） +2. 关联 Facebook Page +3. Meta Developer 应用，获取 `instagram_basic` + `instagram_content_publish` 权限 +4. 长效 Page Access Token + +--- + +## 配置 + +保存到 `~/.openclaw/credentials/instagram_config.json`： + +```json +{ + "page_access_token": "your_long_lived_page_token", + "ig_user_id": "your_ig_business_account_id" +} +``` + +--- + +## 使用方式 + +单图帖子： + +```bash +python3 ./skills/instagram-publish/scripts/publish_instagram.py \ + --caption "描述 #hashtag1 #hashtag2" \ + --images photo.jpg \ + --mode feed +``` + +轮播帖子： + +```bash +python3 ./skills/instagram-publish/scripts/publish_instagram.py \ + --caption "描述" \ + --images img1.jpg img2.jpg img3.jpg \ + --mode carousel +``` + +Reel： + +```bash +python3 ./skills/instagram-publish/scripts/publish_instagram.py \ + --caption "描述" \ + --video reel.mp4 \ + --mode reel +``` + +--- + +## 参数说明 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--caption` | 是 | 描述，最多 2200 字，最多 30 个 hashtag | +| `--mode` | 是 | `feed`/`carousel`/`reel` | +| `--images` | feed/carousel必填 | 图片 URL 列表，carousel 最多 10 张 | +| `--video` | reel必填 | 视频 URL，Reels 建议 9:16，≤90s | + +--- + +## 错误处理 + +| 错误 | 原因 | 处理 | +|------|------|------| +| AUTH_REQUIRED | Token 失效 | 更新 Token | +| UPLOAD_FAILED | 容器创建失败 | 检查图片 URL 可访问性 | +| MEDIA_PROCESSING | 媒体处理中 | 轮询状态等待 | +| RATE_LIMIT | API 限制 | 等待后重试 | + +注意：Instagram API 发布只支持 **URL** 形式的媒体，不支持本地文件上传。需要先将图片/视频上传到可公开访问的 URL。 + +--- + +## 发布记录（强制） + +发布成功后，**必须**立即调用 `published-track` 技能记录发布信息： + +```bash +./skills/published-track/scripts/record.sh \ + --platform instagram \ + --title "标题" \ + --content-type post \ + --source-folder "<原始文件夹路径>" \ + --publish-url "<发布URL>" \ + --publish-date "$(date +%Y-%m-%d)" +``` + +`--source-folder` 为原始内容所在的相对路径（如 `output_articles/xxx` 或 `output_videos/xxx`）。 +`--publish-url` 为发布后获得的 URL，若发布失败则留空并在 `--notes` 中注明原因。 + +执行 `./skills/published-track/scripts/init-db.sh`（幂等，重复执行无副作用）。 diff --git a/addons/officials/crew/selfmedia-operator/skills/instagram-publish/scripts/publish_instagram.py b/addons/officials/crew/selfmedia-operator/skills/instagram-publish/scripts/publish_instagram.py new file mode 100755 index 00000000..103a5b01 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/instagram-publish/scripts/publish_instagram.py @@ -0,0 +1,136 @@ +#!/usr/bin/env python3 +"""Publish posts and reels to Instagram via Meta Graph API (content container pattern).""" + +import argparse +import json +import sys +import time +from pathlib import Path + +import requests + +CREDS_DIR = Path.home() / ".openclaw" / "credentials" +CONFIG_FILE = CREDS_DIR / "instagram_config.json" +GRAPH_API = "https://graph.facebook.com/v23.0" +POLL_INTERVAL = 5 +POLL_MAX = 60 + + +def output(data: dict) -> None: + sys.stdout.write(json.dumps(data, ensure_ascii=False) + "\n") + + +def err_exit(msg: str, code: int = 1) -> None: + sys.stderr.write(f"[instagram-publish] ERROR: {msg}\n") + output({"ok": False, "error": msg}) + sys.exit(code) + + +def load_config() -> dict: + if not CONFIG_FILE.exists(): + err_exit("AUTH_REQUIRED: no instagram_config.json", 2) + return json.loads(CONFIG_FILE.read_text()) + + +def api_post(path: str, token: str, data: dict | None = None) -> dict: + params = {"access_token": token} + resp = requests.post(f"{GRAPH_API}{path}", params=params, json=data, timeout=30) + if resp.status_code in (401, 403): + err_exit("AUTH_REQUIRED", 2) + result = resp.json() + if "error" in result: + err_exit(f"API_ERROR: {result['error'].get('message', result)}") + return result + + +def create_media_container(ig_id: str, token: str, media_type: str, media_url: str, caption: str = "") -> str: + data = {"media_type": media_type, "image_url" if media_type == "IMAGE" else "video_url": media_url} + if caption: + data["caption"] = caption + if media_type == "REEL": + data["media_type"] = "REELS" + data["video_url"] = media_url + + result = api_post(f"/{ig_id}/media", token, data) + container_id = result.get("id", "") + if not container_id: + err_exit(f"UPLOAD_FAILED: no container id: {result}") + return container_id + + +def poll_container_status(ig_id: str, token: str, container_id: str) -> str: + for _ in range(POLL_MAX): + params = {"access_token": token, "fields": "status_code"} + resp = requests.get(f"{GRAPH_API}/{container_id}", params=params, timeout=30) + data = resp.json() + status = data.get("status_code", "") + if status == "FINISHED": + return "ready" + elif status == "ERROR": + err_exit(f"UPLOAD_FAILED: container error: {data}") + time.sleep(POLL_INTERVAL) + err_exit("MEDIA_PROCESSING: timed out waiting for container") + + +def publish_container(ig_id: str, token: str, creation_id: str) -> dict: + result = api_post(f"/{ig_id}/media_publish", token, data={"creation_id": creation_id}) + post_id = result.get("id", "") + return {"ok": True, "post_id": post_id, "url": f"https://www.instagram.com/p/{post_id}"} + + +def publish_carousel(ig_id: str, token: str, image_urls: list[str], caption: str) -> dict: + children_ids = [] + for url in image_urls[:10]: + cid = create_media_container(ig_id, token, "IMAGE", url) + poll_container_status(ig_id, token, cid) + children_ids.append(cid) + + data = { + "media_type": "CAROUSEL", + "children": ",".join(children_ids), + "caption": caption, + } + result = api_post(f"/{ig_id}/media", token, data) + carousel_id = result.get("id", "") + poll_container_status(ig_id, token, carousel_id) + return publish_container(ig_id, token, carousel_id) + + +def main() -> None: + parser = argparse.ArgumentParser(description="Publish to Instagram") + parser.add_argument("--caption", required=True, help="Caption (max 2200 chars, max 30 hashtags)") + parser.add_argument("--mode", required=True, choices=["feed", "carousel", "reel"]) + parser.add_argument("--images", nargs="+", help="Image URLs") + parser.add_argument("--video", help="Video URL (for reels)") + args = parser.parse_args() + + config = load_config() + token = config.get("page_access_token", "") + ig_id = config.get("ig_user_id", "") + if not token or not ig_id: + err_exit("AUTH_REQUIRED: missing token or ig_user_id", 2) + + if args.mode == "feed": + if not args.images or len(args.images) != 1: + err_exit("--images requires exactly 1 URL for feed mode") + cid = create_media_container(ig_id, token, "IMAGE", args.images[0], args.caption) + sys.stderr.write("[instagram-publish] waiting for media processing...\n") + poll_container_status(ig_id, token, cid) + result = publish_container(ig_id, token, cid) + elif args.mode == "carousel": + if not args.images or len(args.images) < 2: + err_exit("--images requires 2-10 URLs for carousel mode") + result = publish_carousel(ig_id, token, args.images, args.caption) + elif args.mode == "reel": + if not args.video: + err_exit("--video URL required for reel mode") + cid = create_media_container(ig_id, token, "REEL", args.video, args.caption) + sys.stderr.write("[instagram-publish] waiting for video processing...\n") + poll_container_status(ig_id, token, cid) + result = publish_container(ig_id, token, cid) + + output(result) + + +if __name__ == "__main__": + main() diff --git a/addons/officials/crew/selfmedia-operator/skills/juejin-publish/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/juejin-publish/SKILL.md index bdb3c20a..13aeb5eb 100644 --- a/addons/officials/crew/selfmedia-operator/skills/juejin-publish/SKILL.md +++ b/addons/officials/crew/selfmedia-operator/skills/juejin-publish/SKILL.md @@ -172,3 +172,22 @@ See `references/publish-options.md` for category list, tag suggestions, and cove ❌ 兜底路径忘记填摘要（*必填）： → 发布按钮无响应，因为摘要为空 ``` + +## 发布记录（强制） + +发布成功后，**必须**立即调用 `published-track` 技能记录发布信息： + +```bash +./skills/published-track/scripts/record.sh \ + --platform juejin \ + --title "标题" \ + --content-type article \ + --source-folder "<原始文件夹路径>" \ + --publish-url "<发布URL>" \ + --publish-date "$(date +%Y-%m-%d)" +``` + +`--source-folder` 为原始内容所在的相对路径（如 `output_articles/xxx` 或 `output_videos/xxx`）。 +`--publish-url` 为发布后获得的 URL，若发布失败则留空并在 `--notes` 中注明原因。 + +执行 `./skills/published-track/scripts/init-db.sh`（幂等，重复执行无副作用）。 diff --git a/addons/officials/crew/selfmedia-operator/skills/pinterest-publish/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/pinterest-publish/SKILL.md new file mode 100644 index 00000000..f4790fd6 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/pinterest-publish/SKILL.md @@ -0,0 +1,106 @@ +--- +name: pinterest-publish +description: Create pins on Pinterest via Pinterest API v5. Supports image pins + and video pins with board selection. Requires Pinterest OAuth2 token. +metadata: + openclaw: + emoji: 📌 + requires: + bins: + - python3 +--- + +# Pinterest 发布（pinterest-publish） + +通过 Pinterest API v5 创建 Pin，支持图片 Pin 和视频 Pin。使用 OAuth2 认证。 + +--- + +## 前置条件 + +1. Pinterest Developer Portal 创建应用，获取 App ID / App Secret +2. 申请 `pins:write` 和 `boards:read` 权限 +3. 获取 OAuth2 Access Token + +--- + +## 配置 + +保存到 `~/.openclaw/credentials/pinterest_config.json`： + +```json +{ + "access_token": "your_access_token", + "board_id": "your_default_board_id" +} +``` + +--- + +## 使用方式 + +图片 Pin： + +```bash +python3 ./skills/pinterest-publish/scripts/publish_pinterest.py \ + --title "Pin 标题" \ + --description "描述" \ + --image https://example.com/image.jpg \ + --board-id 123456789 +``` + +视频 Pin： + +```bash +python3 ./skills/pinterest-publish/scripts/publish_pinterest.py \ + --title "Pin 标题" \ + --description "描述" \ + --video https://example.com/video.mp4 \ + --board-id 123456789 +``` + +--- + +## 参数说明 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--title` | 是 | Pin 标题 | +| `--description` | 否 | Pin 描述 | +| `--image` | 图片必填 | 图片 URL | +| `--video` | 视频必填 | 视频 URL | +| `--board-id` | 是 | 看板 ID | +| `--link` | 否 | 关联链接 URL | + +--- + +## 错误处理 + +| 错误 | 原因 | 处理 | +|------|------|------| +| AUTH_REQUIRED | Token 失效 | 更新 Access Token | +| UPLOAD_FAILED | 上传失败 | 检查 URL 可访问性 | +| INVALID_BOARD | 看板 ID 无效 | 检查看板是否存在 | + +注意：Pinterest API 仅支持 URL 形式的媒体，不支持本地文件上传。 + +--- + +## 发布记录（强制） + +发布成功后，**必须**立即调用 `published-track` 技能记录发布信息： + +```bash +./skills/published-track/scripts/record.sh \ + --platform pinterest \ + --title "标题" \ + --content-type post \ + --source-folder "<原始文件夹路径>" \ + --publish-url "<发布URL>" \ + --publish-date "$(date +%Y-%m-%d)" +``` + +`--source-folder` 为原始内容所在的相对路径（如 `output_articles/xxx` 或 `output_videos/xxx`）。 +`--publish-url` 为发布后获得的 URL，若发布失败则留空并在 `--notes` 中注明原因。 + +执行 `./skills/published-track/scripts/init-db.sh`（幂等，重复执行无副作用）。 diff --git a/addons/officials/crew/selfmedia-operator/skills/pinterest-publish/scripts/publish_pinterest.py b/addons/officials/crew/selfmedia-operator/skills/pinterest-publish/scripts/publish_pinterest.py new file mode 100755 index 00000000..fb001e7d --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/pinterest-publish/scripts/publish_pinterest.py @@ -0,0 +1,115 @@ +#!/usr/bin/env python3 +"""Create pins on Pinterest via Pinterest API v5 with OAuth2.""" + +import argparse +import json +import sys +from pathlib import Path + +import requests + +CREDS_DIR = Path.home() / ".openclaw" / "credentials" +CONFIG_FILE = CREDS_DIR / "pinterest_config.json" +PINTEREST_API = "https://api.pinterest.com/v5" + + +def output(data: dict) -> None: + sys.stdout.write(json.dumps(data, ensure_ascii=False) + "\n") + + +def err_exit(msg: str, code: int = 1) -> None: + sys.stderr.write(f"[pinterest-publish] ERROR: {msg}\n") + output({"ok": False, "error": msg}) + sys.exit(code) + + +def load_config() -> dict: + if not CONFIG_FILE.exists(): + err_exit("AUTH_REQUIRED: no pinterest_config.json", 2) + return json.loads(CONFIG_FILE.read_text()) + + +def api_post(token: str, path: str, data: dict) -> dict: + headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} + resp = requests.post(f"{PINTEREST_API}{path}", headers=headers, json=data, timeout=30) + if resp.status_code in (401, 403): + err_exit("AUTH_REQUIRED", 2) + result = resp.json() + if "error" in result and isinstance(result["error"], dict): + err_exit(f"API_ERROR: {result['error'].get('message', result)}") + return result + + +def create_image_pin(token: str, board_id: str, title: str, description: str, image_url: str, link: str = "") -> dict: + data = { + "board_id": board_id, + "title": title, + "description": description, + "media_source": { + "source_type": "image_url", + "url": image_url, + }, + } + if link: + data["link"] = link + + result = api_post(token, "/pins", data) + pin_id = result.get("id", "") + return {"ok": True, "pin_id": pin_id, "url": f"https://www.pinterest.com/pin/{pin_id}/"} + + +def create_video_pin(token: str, board_id: str, title: str, description: str, video_url: str, link: str = "") -> dict: + register = api_post(token, "/media", data={"media_type": "video"}) + media_id = register.get("media_id", "") + if not media_id: + err_exit(f"UPLOAD_FAILED: no media_id: {register}") + + data = { + "board_id": board_id, + "title": title, + "description": description, + "media_source": { + "source_type": "video_id", + "video_id": media_id, + "cover_image_url": video_url, + }, + } + if link: + data["link"] = link + + result = api_post(token, "/pins", data) + pin_id = result.get("id", "") + return {"ok": True, "pin_id": pin_id, "url": f"https://www.pinterest.com/pin/{pin_id}/"} + + +def main() -> None: + parser = argparse.ArgumentParser(description="Create pin on Pinterest") + parser.add_argument("--title", required=True, help="Pin title") + parser.add_argument("--description", default="", help="Pin description") + parser.add_argument("--image", help="Image URL") + parser.add_argument("--video", help="Video URL") + parser.add_argument("--board-id", required=True, help="Board ID") + parser.add_argument("--link", default="", help="Destination link URL") + args = parser.parse_args() + + config = load_config() + token = config.get("access_token", "") + if not token: + err_exit("AUTH_REQUIRED: missing access_token", 2) + + board_id = args.board_id or config.get("board_id", "") + if not board_id: + err_exit("INVALID_BOARD: no board_id provided", 2) + + if args.image: + result = create_image_pin(token, board_id, args.title, args.description, args.image, args.link) + elif args.video: + result = create_video_pin(token, board_id, args.title, args.description, args.video, args.link) + else: + err_exit("Either --image or --video URL is required") + + output(result) + + +if __name__ == "__main__": + main() diff --git a/addons/officials/crew/selfmedia-operator/skills/published-track/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/published-track/SKILL.md new file mode 100644 index 00000000..8e0bcc85 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/published-track/SKILL.md @@ -0,0 +1,142 @@ +--- +name: published-track +description: 发布记录追踪。使用 SQLite 数据库记录所有平台发布内容及其互动数据，按平台分表管理。发布后必须调用本技能记录，心跳巡检时更新数据。 +metadata: + openclaw: + emoji: "📊" + requires: + bins: + - bash + - sqlite3 +--- + +# published-track — 发布记录追踪 + +统一管理所有平台（微信公众号、知乎、B站、抖音、快手、小红书、今日头条、掘金、Twitter/X、Facebook、Instagram、TikTok、YouTube、Pinterest、Threads、企业微信朋友圈）的发布记录与互动数据。 + +--- + +## 数据库位置 + +`./db/published_track.db`（相对于工作区根目录） + +初始化（幂等，可重复执行）： + +```bash +./skills/published-track/scripts/init-db.sh +``` + +--- + +## 平台与表对应关系 + +| 平台 | 表名 | 内容类型 | 特有指标 | +|------|------|---------|---------| +| 微信公众号 | `pub_wx_mp` | article/video/post | reads, shares, favorites, likes, comments | +| 知乎 | `pub_zhihu` | article/post | views, upvotes, comments, favorites | +| B站 | `pub_bilibili` | video | plays, danmaku, likes, coins, favorites, shares, comments | +| 抖音 | `pub_douyin` | video | plays, likes, comments, shares, favorites | +| 快手 | `pub_kuaishou` | video | plays, likes, comments, shares | +| 小红书 | `pub_xhs` | article/video/post | views, likes, favorites, comments, shares | +| 今日头条 | `pub_toutiao` | article | impressions, reads, comments, likes | +| 掘金 | `pub_juejin` | article | views, likes, comments, favorites | +| Twitter/X | `pub_twitter` | post/video | views, likes, retweets, replies, bookmarks | +| Facebook | `pub_facebook` | post/video | reach, likes, comments, shares | +| Instagram | `pub_instagram` | post/video | reach, likes, comments, shares, saves | +| TikTok | `pub_tiktok` | video | plays, likes, comments, shares, favorites | +| YouTube | `pub_youtube` | video | views, likes, comments, shares | +| Pinterest | `pub_pinterest` | post | impressions, saves, comments | +| Threads | `pub_threads` | post | views, likes, reposts, replies | +| 企业微信朋友圈 | `pub_wxwork_moments` | post | likes, comments | + +--- + +## 表结构 + +每张表共享以下通用字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | INTEGER PK | 自增主键 | +| title | TEXT NOT NULL | 标题 | +| content_type | TEXT NOT NULL | article / video / post | +| source_folder | TEXT NOT NULL | 原始文件夹（如 output_articles/xxx 或 output_videos/xxx） | +| publish_url | TEXT | 发布后 URL | +| publish_date | TEXT NOT NULL | 发布日期（YYYY-MM-DD） | +| notes | TEXT | 备注 | +| created_at | TEXT | 创建时间 | +| updated_at | TEXT | 更新时间 | + +去重键：`source_folder`（同一篇内容在同一平台只记录一次） + +各平台特有的互动指标字段默认值为 0，另有 `top_comment`（主要留言摘要，TEXT）字段。 + +--- + +## 使用方式 + +### 1. 发布后立即记录（强制） + +每完成一个平台的发布，**必须**立即调用 `record.sh` 记录： + +```bash +./skills/published-track/scripts/record.sh \ + --platform \ + --title "标题" \ + --content-type \ + --source-folder "output_articles/xxx" \ + --publish-url "https://..." \ + --publish-date "$(date +%Y-%m-%d)" \ + [--notes "备注"] +``` + +`--platform` 值对应上表「表名」去掉 `pub_` 前缀，如 `wx_mp`、`zhihu`、`bilibili` 等。 + +若发布失败（如平台拒绝、超时），仍需记录，`publish_url` 留空，`notes` 中注明失败原因。 + +### 2. 数据更新（心跳巡检） + +使用 `update-metrics.sh` 更新互动数据： + +```bash +./skills/published-track/scripts/update-metrics.sh \ + --platform \ + --source-folder "output_articles/xxx" \ + --reads 1234 \ + --likes 56 \ + ... +``` + +只需传入要更新的指标字段，未传入的字段保持不变。 + +### 3. 查询 + +```bash +# 查询某平台全部记录 +./skills/published-track/scripts/query.sh --platform zhihu + +# 查询某平台最近 N 条 +./skills/published-track/scripts/query.sh --platform zhihu --limit 10 + +# 查询特定内容是否已发布到某平台 +./skills/published-track/scripts/check-published.sh \ + --platform zhihu \ + --source-folder "output_articles/xxx" + +# 查询所有平台中未发布的原始文件夹 +./skills/published-track/scripts/query.sh --unpublished +``` + +### 4. 清理低数据记录 + +发布超过 7 天、互动指标低于 300 的记录，使用 `query.sh` 查出后可删除： + +```bash +./skills/published-track/scripts/query.sh --platform zhihu --stale-days 7 --below 300 +``` + +--- + +## 与发布技能的配合 + +所有发布技能（wx-mp-publisher、sync-from-mp、bilibili-publish 等）在发布成功后必须调用 `record.sh` 记录。各技能 SKILL.md 中已标注此要求，主 agent 无需额外提醒。 diff --git a/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/check-published.sh b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/check-published.sh new file mode 100755 index 00000000..b181fdca --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/check-published.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +DB="$ROOT/db/published_track.db" + +if [ ! -f "$DB" ]; then + echo '{"exists":false}' + exit 0 +fi + +PLATFORM="" SOURCE_FOLDER="" + +while [[ $# -gt 0 ]]; do + case "$1" in + --platform) PLATFORM="$2"; shift 2 ;; + --source-folder) SOURCE_FOLDER="$2"; shift 2 ;; + *) echo "{\"ok\":false,\"error\":\"unknown arg: $1\"}"; exit 1 ;; + esac +done + +if [ -z "$PLATFORM" ] || [ -z "$SOURCE_FOLDER" ]; then + echo '{"ok":false,"error":"missing required args: --platform, --source-folder"}' + exit 1 +fi + +TABLE="pub_${PLATFORM}" +VALID=$(sqlite3 "$DB" "SELECT name FROM sqlite_master WHERE type='table' AND name='$TABLE';") +if [ -z "$VALID" ]; then + echo "{\"ok\":false,\"error\":\"unknown platform: $PLATFORM\"}" + exit 1 +fi + +ROW=$(sqlite3 "$DB" "SELECT id,publish_url FROM $TABLE WHERE source_folder='${SOURCE_FOLDER//\'/\'\'}';") +if [ -z "$ROW" ]; then + echo '{"exists":false}' +else + ID=$(echo "$ROW" | cut -d'|' -f1) + URL=$(echo "$ROW" | cut -d'|' -f2) + echo "{\"exists\":true,\"id\":$ID,\"publish_url\":\"$URL\"}" +fi diff --git a/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/init-db.sh b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/init-db.sh new file mode 100755 index 00000000..096badda --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/init-db.sh @@ -0,0 +1,301 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +DB="$ROOT/db/published_track.db" + +mkdir -p "$ROOT/db" + +sqlite3 "$DB" <<'SQL' + +-- 微信公众号 +CREATE TABLE IF NOT EXISTS pub_wx_mp ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + reads INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + favorites INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- 知乎 +CREATE TABLE IF NOT EXISTS pub_zhihu ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + views INTEGER DEFAULT 0, + upvotes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + favorites INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- B站 +CREATE TABLE IF NOT EXISTS pub_bilibili ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + plays INTEGER DEFAULT 0, + danmaku INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + coins INTEGER DEFAULT 0, + favorites INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- 抖音 +CREATE TABLE IF NOT EXISTS pub_douyin ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + plays INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + favorites INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- 快手 +CREATE TABLE IF NOT EXISTS pub_kuaishou ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + plays INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- 小红书 +CREATE TABLE IF NOT EXISTS pub_xhs ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + views INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + favorites INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- 今日头条 +CREATE TABLE IF NOT EXISTS pub_toutiao ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + impressions INTEGER DEFAULT 0, + reads INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- 掘金 +CREATE TABLE IF NOT EXISTS pub_juejin ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + views INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + favorites INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- Twitter/X +CREATE TABLE IF NOT EXISTS pub_twitter ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + views INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + retweets INTEGER DEFAULT 0, + replies INTEGER DEFAULT 0, + bookmarks INTEGER DEFAULT 0, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- Facebook +CREATE TABLE IF NOT EXISTS pub_facebook ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + reach INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- Instagram +CREATE TABLE IF NOT EXISTS pub_instagram ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + reach INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + saves INTEGER DEFAULT 0, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- TikTok +CREATE TABLE IF NOT EXISTS pub_tiktok ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + plays INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + favorites INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- YouTube +CREATE TABLE IF NOT EXISTS pub_youtube ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + views INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + shares INTEGER DEFAULT 0, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- Pinterest +CREATE TABLE IF NOT EXISTS pub_pinterest ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + impressions INTEGER DEFAULT 0, + saves INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- Threads +CREATE TABLE IF NOT EXISTS pub_threads ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + views INTEGER DEFAULT 0, + likes INTEGER DEFAULT 0, + reposts INTEGER DEFAULT 0, + replies INTEGER DEFAULT 0, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +-- 企业微信朋友圈 +CREATE TABLE IF NOT EXISTS pub_wxwork_moments ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + content_type TEXT NOT NULL CHECK(content_type IN ('article','video','post')), + source_folder TEXT NOT NULL UNIQUE, + publish_url TEXT, + publish_date TEXT NOT NULL, + likes INTEGER DEFAULT 0, + comments INTEGER DEFAULT 0, + top_comment TEXT, + notes TEXT, + created_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')), + updated_at TEXT DEFAULT (strftime('%Y-%m-%d %H:%M:%S','now','localtime')) +); + +SQL + +echo '{"ok":true,"message":"published_track.db initialized"}' diff --git a/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/query.sh b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/query.sh new file mode 100755 index 00000000..9358e236 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/query.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +DB="$ROOT/db/published_track.db" + +if [ ! -f "$DB" ]; then + echo '[]' + exit 0 +fi + +PLATFORM="" LIMIT="" UNPUBLISHED=false STALE_DAYS="" BELOW="" + +while [[ $# -gt 0 ]]; do + case "$1" in + --platform) PLATFORM="$2"; shift 2 ;; + --limit) LIMIT="$2"; shift 2 ;; + --unpublished) UNPUBLISHED=true; shift ;; + --stale-days) STALE_DAYS="$2"; shift 2 ;; + --below) BELOW="$2"; shift 2 ;; + *) echo "{\"ok\":false,\"error\":\"unknown arg: $1\"}"; exit 1 ;; + esac +done + +if [ "$UNPUBLISHED" = true ]; then + # Find source_folders in output_articles/ and output_videos/ that have no record in any platform table + TABLES=$(sqlite3 "$DB" "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'pub_%';") + FOLDERS=$(find "$ROOT/output_articles" "$ROOT/output_videos" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sed "s|$ROOT/||" | sort) + + UNPUB_LIST="[" + FIRST=true + for F in $FOLDERS; do + FOUND=false + for T in $TABLES; do + CNT=$(sqlite3 "$DB" "SELECT COUNT(*) FROM $T WHERE source_folder='${F//\'/\'\'}';") + if [ "$CNT" -gt 0 ]; then + FOUND=true + break + fi + done + if [ "$FOUND" = false ]; then + [ "$FIRST" = true ] && FIRST=false || UNPUB_LIST+="," + UNPUB_LIST+="\"$F\"" + fi + done + UNPUB_LIST+="]" + echo "$UNPUB_LIST" + exit 0 +fi + +if [ -z "$PLATFORM" ]; then + echo '{"ok":false,"error":"--platform is required (unless --unpublished)"}' + exit 1 +fi + +TABLE="pub_${PLATFORM}" +VALID=$(sqlite3 "$DB" "SELECT name FROM sqlite_master WHERE type='table' AND name='$TABLE';") +if [ -z "$VALID" ]; then + echo "{\"ok\":false,\"error\":\"unknown platform: $PLATFORM\"}" + exit 1 +fi + +# Build query +WHERE="" +if [ -n "$STALE_DAYS" ]; then + WHERE="WHERE publish_date <= date('now','-$STALE_DAYS days')" +fi + +LIMIT_CLAUSE="" +if [ -n "$LIMIT" ]; then + LIMIT_CLAUSE="LIMIT $LIMIT" +fi + +# Query all records +ROWS=$(sqlite3 -json "$DB" "SELECT * FROM $TABLE $WHERE ORDER BY publish_date DESC $LIMIT_CLAUSE;" 2>/dev/null) + +if [ -n "$BELOW" ] && [ -n "$STALE_DAYS" ]; then + # Filter for records where all main metric columns are below threshold + # Get integer columns + INT_COLS=$(sqlite3 "$DB" "PRAGMA table_info($TABLE);" | awk -F'|' '$2 != "id" && $2 != "title" && $2 != "content_type" && $2 != "source_folder" && $2 != "publish_url" && $2 != "publish_date" && $2 != "notes" && $2 != "top_comment" && $2 != "created_at" && $2 != "updated_at" {print $2}') + + CONDS="" + for C in $INT_COLS; do + [ -n "$CONDS" ] && CONDS+=" AND " + CONDS+="$C < $BELOW" + done + + ROWS=$(sqlite3 -json "$DB" "SELECT * FROM $TABLE WHERE publish_date <= date('now','-$STALE_DAYS days') AND ($CONDS) ORDER BY publish_date DESC $LIMIT_CLAUSE;" 2>/dev/null) +fi + +echo "${ROWS:-[]}" diff --git a/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/record.sh b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/record.sh new file mode 100755 index 00000000..ae667049 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/record.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +DB="$ROOT/db/published_track.db" + +# Ensure db exists +if [ ! -f "$DB" ]; then + bash "$(dirname "$0")/init-db.sh" +fi + +# Parse args +PLATFORM="" TITLE="" CONTENT_TYPE="" SOURCE_FOLDER="" PUBLISH_URL="" PUBLISH_DATE="" NOTES="" + +while [[ $# -gt 0 ]]; do + case "$1" in + --platform) PLATFORM="$2"; shift 2 ;; + --title) TITLE="$2"; shift 2 ;; + --content-type) CONTENT_TYPE="$2"; shift 2 ;; + --source-folder) SOURCE_FOLDER="$2"; shift 2 ;; + --publish-url) PUBLISH_URL="$2"; shift 2 ;; + --publish-date) PUBLISH_DATE="$2"; shift 2 ;; + --notes) NOTES="$2"; shift 2 ;; + *) echo "{\"ok\":false,\"error\":\"unknown arg: $1\"}"; exit 1 ;; + esac +done + +# Validate required args +if [ -z "$PLATFORM" ] || [ -z "$TITLE" ] || [ -z "$CONTENT_TYPE" ] || [ -z "$SOURCE_FOLDER" ] || [ -z "$PUBLISH_DATE" ]; then + echo '{"ok":false,"error":"missing required args: --platform, --title, --content-type, --source-folder, --publish-date"}' + exit 1 +fi + +# Validate platform +TABLE="pub_${PLATFORM}" +VALID=$(sqlite3 "$DB" "SELECT name FROM sqlite_master WHERE type='table' AND name='$TABLE';") +if [ -z "$VALID" ]; then + echo "{\"ok\":false,\"error\":\"unknown platform: $PLATFORM (table $TABLE not found)\"}" + exit 1 +fi + +# Validate content_type +case "$CONTENT_TYPE" in + article|video|post) ;; + *) echo "{\"ok\":false,\"error\":\"invalid content_type: $CONTENT_TYPE (must be article/video/post)\"}"; exit 1 ;; +esac + +# Check duplicate +EXISTS=$(sqlite3 "$DB" "SELECT COUNT(*) FROM $TABLE WHERE source_folder='${SOURCE_FOLDER//\'/\'\'}';") +if [ "$EXISTS" -gt 0 ]; then + # Update existing record + ESC_URL="${PUBLISH_URL//\'/\'\'}" + ESC_NOTES="${NOTES//\'/\'\'}" + sqlite3 "$DB" "UPDATE $TABLE SET publish_url='$ESC_URL', notes='$ESC_NOTES', updated_at=strftime('%Y-%m-%d %H:%M:%S','now','localtime') WHERE source_folder='${SOURCE_FOLDER//\'/\'\'}';" + ID=$(sqlite3 "$DB" "SELECT id FROM $TABLE WHERE source_folder='${SOURCE_FOLDER//\'/\'\'}';") + echo "{\"ok\":true,\"action\":\"updated\",\"id\":$ID,\"table\":\"$TABLE\"}" +else + # Insert new record + ESC_TITLE="${TITLE//\'/\'\'}" + ESC_FOLDER="${SOURCE_FOLDER//\'/\'\'}" + ESC_URL="${PUBLISH_URL//\'/\'\'}" + ESC_NOTES="${NOTES//\'/\'\'}" + sqlite3 "$DB" "INSERT INTO $TABLE (title,content_type,source_folder,publish_url,publish_date,notes) VALUES ('$ESC_TITLE','$CONTENT_TYPE','$ESC_FOLDER','$ESC_URL','$PUBLISH_DATE','$ESC_NOTES');" + ID=$(sqlite3 "$DB" "SELECT last_insert_rowid();") + echo "{\"ok\":true,\"action\":\"inserted\",\"id\":$ID,\"table\":\"$TABLE\"}" +fi diff --git a/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/update-metrics.sh b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/update-metrics.sh new file mode 100755 index 00000000..e586f070 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/published-track/scripts/update-metrics.sh @@ -0,0 +1,84 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +DB="$ROOT/db/published_track.db" + +if [ ! -f "$DB" ]; then + echo '{"ok":false,"error":"database not initialized, run init-db.sh first"}' + exit 1 +fi + +# Parse args +PLATFORM="" SOURCE_FOLDER="" +declare -A METRICS + +while [[ $# -gt 0 ]]; do + case "$1" in + --platform) PLATFORM="$2"; shift 2 ;; + --source-folder) SOURCE_FOLDER="$2"; shift 2 ;; + --*=*) + KEY="${1#--}" + VAL="${1#*=}" + METRICS["$KEY"]="$VAL" + shift + ;; + --*) + KEY="${1#--}" + VAL="$2" + METRICS["$KEY"]="$VAL" + shift 2 + ;; + *) echo "{\"ok\":false,\"error\":\"unknown arg: $1\"}"; exit 1 ;; + esac +done + +if [ -z "$PLATFORM" ] || [ -z "$SOURCE_FOLDER" ]; then + echo '{"ok":false,"error":"missing required args: --platform, --source-folder"}' + exit 1 +fi + +TABLE="pub_${PLATFORM}" +VALID=$(sqlite3 "$DB" "SELECT name FROM sqlite_master WHERE type='table' AND name='$TABLE';") +if [ -z "$VALID" ]; then + echo "{\"ok\":false,\"error\":\"unknown platform: $PLATFORM\"}" + exit 1 +fi + +# Check record exists +EXISTS=$(sqlite3 "$DB" "SELECT COUNT(*) FROM $TABLE WHERE source_folder='${SOURCE_FOLDER//\'/\'\'}';") +if [ "$EXISTS" -eq 0 ]; then + echo "{\"ok\":false,\"error\":\"no record found in $TABLE for source_folder=$SOURCE_FOLDER\"}" + exit 1 +fi + +# Get valid columns for this table (exclude id, created_at) +COLS=$(sqlite3 "$DB" "PRAGMA table_info($TABLE);" | awk -F'|' '{print $2}' | grep -v -E '^(id|created_at|source_folder|content_type|title|publish_date)$' | tr '\n' ' ') + +# Build SET clause +SET_PARTS=() +for KEY in "${!METRICS[@]}"; do + # Validate column exists + if ! echo " $COLS " | grep -q " $KEY "; then + echo "{\"ok\":false,\"error\":\"column '$KEY' not found in $TABLE. Valid metric columns: $COLS\"}" + exit 1 + fi + VAL="${METRICS[$KEY]}" + # Only allow integer or text values + ESC_VAL="${VAL//\'/\'\'}" + SET_PARTS+=("$KEY='$ESC_VAL'") +done + +if [ ${#SET_PARTS[@]} -eq 0 ]; then + echo '{"ok":false,"error":"no metrics provided to update"}' + exit 1 +fi + +# Always update updated_at +SET_PARTS+=("updated_at=strftime('%Y-%m-%d %H:%M:%S','now','localtime')") + +SET_CLAUSE=$(IFS=','; echo "${SET_PARTS[*]}") + +sqlite3 "$DB" "UPDATE $TABLE SET $SET_CLAUSE WHERE source_folder='${SOURCE_FOLDER//\'/\'\'}';" + +echo "{\"ok\":true,\"table\":\"$TABLE\",\"source_folder\":\"$SOURCE_FOLDER\",\"updated_columns\":${#METRICS[@]}}" diff --git a/addons/officials/crew/selfmedia-operator/skills/t2video/SKILL.md b/addons/officials/crew/selfmedia-operator/skills/t2video/SKILL.md new file mode 100644 index 00000000..c356d6c7 --- /dev/null +++ b/addons/officials/crew/selfmedia-operator/skills/t2video/SKILL.md @@ -0,0 +1,215 @@ +--- +name: t2video +description: 一站式短视频制作工具。整合 SiliconFlow TTS 语音合成、素材搜集（Pexels/Pixabay/AI 生成）和 FFmpeg 组装，从脚本到成品视频一步完成。无 subagent 模式，适合短小视频。 +metadata: + openclaw: + emoji: "🎥" + requires: + bins: + - python3 + - ffmpeg + - ffprobe + env: + - SILICONFLOW_API_KEY + primaryEnv: SILICONFLOW_API_KEY +--- + +# t2video — 一站式短视频制作 + +Use this skill when: +- 需要从脚本生成完整短视频（TTS + 素材 + 组装） +- 用户指定主题和已有素材，生成短视频 + +**本技能是 video-producer 的简化版**：适合短小视频制作，且只生成9:16的竖屏视频。 + +**不烧录字幕**：大部分平台支持自动生成字幕，无需手动烧录。 + +--- + +## ⚙️ 执行方式（强制） + +本技能涉及多步骤生产流程，你应该 self-spawn 一个 subagent 来执行，原因：subagent 独立上下文，不会因对话历史积累而降低输出质量。 + +你只负责跟进subagent的执行，避免它们长时间卡在某个步骤，必要时可以提供提示或调整执行策略。另外在关键节点要求它向你汇报，你检查后再让它继续执行下一步。 + +--- + +## 工作流程 + +### Step 1 — 工作区目录准备 + +在 `output_videos/` 下创建项目文件夹，如 `output_videos//`，作为 project-dir。 + +工作区结构： + +``` +/ +├── script.md # 三段式脚本 +├── tts_requirement.md # 配音需求（由 Step 3 创建） +├── artifacts/ # 产出素材（TTS音频+视频素材） +│ ├── speech.mp3 # TTS 配音 +│ ├── speech.json # TTS 元数据（含 duration） +│ └──
') + print(' ') + print(" {}".format(icp)) + print(" ") + print("
") + +commands = {"checklist": cmd_checklist, "flow": cmd_flow, "query": cmd_query, "province": cmd_province, "footer": cmd_footer} +if cmd == "help": + print("ICP Filing Assistant") + print("") + print("Commands:") + print(" checklist [personal|company] — Required documents") + print(" flow — Filing process steps") + print(" query — How to check filing status") + print(" province [name] — Provincial ICP prefixes") + print(" footer — Generate HTML footer code") +elif cmd in commands: + commands[cmd]() +else: + print("Unknown: {}".format(cmd)) +PYEOF diff --git a/crews/it-engineer/skills/seo/SKILL.md b/crews/it-engineer/skills/seo/SKILL.md index 8c74fd11..1ff14b44 100644 --- a/crews/it-engineer/skills/seo/SKILL.md +++ b/crews/it-engineer/skills/seo/SKILL.md @@ -1,14 +1,12 @@ --- name: seo -description: Audit, plan, and implement SEO improvements across technical SEO, on-page optimization, structured data, Core Web Vitals, and content strategy. Use when the user wants better search visibility, SEO remediation, schema markup, sitemap/robots work, or keyword mapping. +description: Audit, plan, and implement SEO improvements across technical SEO, on-page + optimization, structured data, Core Web Vitals, and content strategy. Use when the + user wants better search visibility, SEO remediation, schema markup, sitemap/robots + work, or keyword mapping. metadata: - { - "openclaw": - { - "emoji": "🔍", - "always": false, - }, - } + openclaw: + emoji: 🔍 --- # SEO diff --git a/crews/it-engineer/skills/tccli/SKILL.md b/crews/it-engineer/skills/tccli/SKILL.md new file mode 100644 index 00000000..26f35e0a --- /dev/null +++ b/crews/it-engineer/skills/tccli/SKILL.md @@ -0,0 +1,212 @@ +--- +name: tccli +description: + 腾讯云命令行工具速查手册。通过命令行方式管理和操作腾讯云 200+ 云产品资源， + 支持实例查询、启动、停止、域名解析等功能。当用户提到腾讯云、tccli、CVM、 + Lighthouse、DNSPod、VPC、SSL 证书等腾讯云服务操作时触发。 +metadata: + openclaw: + emoji: ☁️ + requires: + bins: + - tccli +--- + +# TCCLI - 腾讯云命令行工具 + +> 通过命令行管理腾讯云资源 + +--- + +## 简介 + +TCCLI（Tencent Cloud Command Line Interface）是腾讯云官方提供的命令行工具，支持管理 200+ 云产品。 + +--- + +## 安装 + +```bash +pip3 install tccli +``` + +## 配置 + +```bash +# 配置密钥（只需一次） +tccli configure set secretId +tccli configure set secretKey +tccli configure set region ap-guangzhou +``` + +--- + +## 常用服务速查 + +### 云服务器 (CVM) + +| 操作 | 命令 | +|------|------| +| 查看实例列表 | `tccli cvm DescribeInstances` | +| 查看实例状态 | `tccli cvm DescribeInstancesStatus` | +| 查看可用区 | `tccli cvm DescribeZones` | +| 查看地域 | `tccli cvm DescribeRegions` | +| 查看镜像 | `tccli cvm DescribeImages` | +| 启动实例 | `tccli cvm StartInstances --InstanceIds '["ins-xxxxx"]'` | +| 停止实例 | `tccli cvm StopInstances --InstanceIds '["ins-xxxxx"]'` | +| 重启实例 | `tccli cvm RebootInstances --InstanceIds '["ins-xxxxx"]'` | + +### 轻量应用服务器 (Lighthouse) + +| 操作 | 命令 | +|------|------| +| 查看实例列表 | `tccli lighthouse DescribeInstances` | +| 查看套餐 | `tccli lighthouse DescribeBundles` | +| 查看镜像 | `tccli lighthouse DescribeBlueprints` | +| 查看防火墙规则 | `tccli lighthouse DescribeFirewallRules` | +| 创建防火墙规则 | `tccli lighthouse CreateFirewallRules --InstanceId ins-xxxxx --FirewallRules '[{"Protocol":"TCP","Port":"80","Action":"ACCEPT"}]'` | + +### SSL 证书 + +| 操作 | 命令 | +|------|------| +| 查看证书列表 | `tccli ssl DescribeCertificates` | +| 查看证书详情 | `tccli ssl DescribeCertificate --CertificateId xxx` | +| 下载证书 | `tccli ssl DownloadCertificate --CertificateId xxx` | +| 部署证书 | `tccli ssl DeployCertificateInstance ...` | + +### DNSPod (域名解析) + +| 操作 | 命令 | +|------|------| +| 查看域名列表 | `tccli dnspod DescribeDomainList` | +| 查看域名详情 | `tccli dnspod DescribeDomain --Domain example.com` | +| 查看记录列表 | `tccli dnspod DescribeRecordList --Domain example.com` | +| 创建记录 | `tccli dnspod CreateRecord --Domain example.com --RecordType A --RecordLine 默认 --Value 1.2.3.4` | + +### 私有网络 (VPC) + +| 操作 | 命令 | +|------|------| +| 查看 VPC 列表 | `tccli vpc DescribeVpcs` | +| 查看子网列表 | `tccli vpc DescribeSubnets` | +| 查看安全组 | `tccli vpc DescribeSecurityGroups` | +| 查看安全组规则 | `tccli vpc DescribeSecurityGroupPolicies --SecurityGroupId sg-xxxxx` | + +### 域名注册 + +| 操作 | 命令 | +|------|------| +| 查看域名列表 | `tccli domain DescribeDomainNameList` | +| 检查域名 | `tccli domain CheckDomain --DomainName example.com` | +| 查看价格 | `tccli domain DescribeDomainPriceList` | + +### 云监控 (Monitor) + +| 操作 | 命令 | +|------|------| +| 查看指标数据 | `tccli monitor GetMonitorData` | +| 查看告警策略 | `tccli monitor DescribeAlarmPolicies` | + +--- + +## 输出格式 + +```bash +# JSON 格式（默认） +tccli cvm DescribeInstances + +# 表格格式 +tccli cvm DescribeInstances --output table + +# 文本格式 +tccli cvm DescribeInstances --output text +``` + +--- + +## 帮助命令 + +```bash +# 查看所有服务 +tccli help + +# 查看服务详情 +tccli cvm help +tccli ssl help +tccli lighthouse help + +# 查看具体接口 +tccli cvm DescribeInstances help +``` + +--- + +## 常用参数 + +| 参数 | 说明 | 示例 | +|------|------|------| +| `--Region` | 指定地域 | `--Region ap-shanghai` | +| `--output` | 输出格式 | `--output table` | +| `--filter` | 过滤结果 | `--filter 'Instances[0].InstanceId'` | +| `--cli-unfold-argument` | 展开参数 | 用于复杂嵌套参数 | + +--- + +## 使用示例 + +### 获取第一个实例的公网 IP +```bash +tccli cvm DescribeInstances --filter 'Instances[0].PublicIpAddresses[0]' +``` + +### 查看所有运行中的实例 +```bash +tccli cvm DescribeInstances --Filters '[{"Name":"instance-state","Values":["RUNNING"]}]' +``` + +### 批量查询多个实例 +```bash +tccli cvm DescribeInstances --InstanceIds '["ins-xxx1","ins-xxx2"]' --output table +``` + +--- + +## 完整服务列表 + +TCCLI 支持 200+ 云服务，常用包括： + +| 服务代码 | 服务名称 | +|----------|----------| +| cvm | 云服务器 | +| lighthouse | 轻量应用服务器 | +| vpc | 私有网络 | +| ssl | SSL 证书 | +| dnspod | DNS 解析 | +| domain | 域名注册 | +| cdn | 内容分发网络 | +| cls | 日志服务 | +| cos | 对象存储 | +| monitor | 云监控 | +| cam | 访问管理 | +| cdb | 云数据库 MySQL | +| redis | 云数据库 Redis | +| mongodb | 云数据库 MongoDB | +| tke | 容器服务 | +| scf | 云函数 | + +--- + +## 安全注意事项 + +- **最小权限原则**：配置的 API 密钥应仅授予所需的最小权限，避免使用主账号密钥 +- **密钥保护**：不要在共享终端、日志、截图或代码仓库中暴露 secretId / secretKey +- **写操作确认**：执行变更类命令（启停实例、修改防火墙、部署证书、创建 DNS 记录等）前，务必确认目标账号、地域、资源 ID 和操作意图 +- **区域确认**：执行写操作前确认 `--Region` 参数正确，避免误操作其他地域的资源 + +--- + +## 参考文档 + +- [TCCLI 官方文档](https://cloud.tencent.com/document/product/440/34011) +- [TCCLI GitHub](https://github.com/TencentCloud/tencentcloud-cli) diff --git a/crews/main/AGENTS.md b/crews/main/AGENTS.md index 8ed062cd..ac52d632 100644 --- a/crews/main/AGENTS.md +++ b/crews/main/AGENTS.md @@ -1,103 +1,186 @@ # Main Agent — Workflow -## Message Handling Flow +## Startup Checks -``` -1. Receive user message -2. Check for `@` prefix → if found: - a. If agent is in your team (allowAgents) → spawn directly - b. If agent is a peer (hrbp/it-engineer) or external crew → inform user to use dedicated channel -3. Analyze intent -4. Refresh team roster from `crew_templates/TEAM_DIRECTORY.md`; use MEMORY.md as supplement -5. Apply the Three Principles: - a. Match found in your team → spawn specialist (Principle 1) - b. No match, one-off task → handle directly (Principle 2) - c. No match, recurring capability gap → suggest recruiting (Principle 3) -6. When sub-agent announces results → relay to user -``` +At the beginning of each user-facing session: -## Three Principles in Practice +1. Check whether `pending-followup.json` exists in the workspace. +2. If a pending Gateway restart followup exists, verify the expected state before continuing: + - expected channel binding exists; + - Gateway is reachable if a status command is available; + - report success or spawn IT Engineer if recovery failed. +3. Check `reminder.json` and surface only open reminders that are due. +4. Continue with the user's current request. -### Principle 1: Dispatch to Team Member -- Check the team roster for a specialist matching the user's intent -- Prioritize delegation over self-execution when a match exists -- Even when you can do it, prefer delegation if it's within a specialist's domain +## Fresh Install Onboarding Flow -### Principle 2: Handle Directly -- Simple, one-off tasks that don't need specialist expertise -- Quick Q&A that you can answer without spawning -- Tasks outside all team members' domains but not recurring +Default fresh install state: -### Principle 3: Suggest Recruiting -- When a task implies a missing long-term capability -- Tell the user what kind of specialist is needed -- Offer to proceed with recruitment via `crew-recruit` skill (L3 confirmation required) +- `openclaw-weixin` is the only default channel. +- `openclaw-weixin` routes to Main Agent. +- IT Engineer is available only as Main Agent's subagent. +- HRBP is not enabled by default. +- Feishu and WeCom are not preconfigured. -## Peer Agent Boundary +First conversation goals: -**HRBP** is a peer-level system agent, NOT your subordinate: -- You cannot and should not spawn HRBP -- If a user requests HRBP services (external crew management): inform them to contact HRBP directly +1. Welcome the user and explain that WeChat private chat is the lightweight control entry. +2. State that the current Weixin plugin supports direct chats and media; do not promise group chats. +3. Explain that IT Engineer can be called by Main Agent for system/deployment tasks. +4. Ask about the user's scenario, brand/company, desired team capabilities, and first useful outcome. +5. Recommend internal crew only when the need is recurring. +6. Explain that work channels can be configured later when the team grows or when external crew are needed. -**IT Engineer** is in your `allowAgents` and MUST be spawned when technical issues arise: -- Do NOT tell users to contact IT Engineer themselves -- You spawn IT Engineer as a subagent, wait for the fix, then resume the original task +## Message Handling Flow -## Crew 升级文件规范 +``` +1. Receive user message. +2. Check pending followup and due reminders. +3. Check for `@` prefix. +4. If the target is allowed, spawn it. +5. If the target is HRBP and HRBP is not enabled, explain HRBP enablement. +6. If the target is external crew, explain that HRBP and direct channel binding are required. +7. Analyze intent. +8. Refresh roster from `crew_templates/TEAM_DIRECTORY.md`; use MEMORY.md only as supplement. +9. Apply the Three Principles: + a. Existing team match → spawn specialist. + b. One-off task → handle directly. + c. Recurring capability gap → propose internal crew recruitment. +10. Relay sub-agent results to the user. +``` -在协助任何 Crew（Agent）修改或升级其 workspace 文件时，**必须遵守以下文件职责划分**： +## Internal Crew Lifecycle -| 文件 | 内容职责 | -|------|---------| -| `AGENTS.md` | 工作流程（处理流程、决策树、操作步骤） | -| `TOOLS.md` | 工具指导（技能使用、命令规范、工具注意事项） | -| `HEARTBEAT.md` | 心跳任务（定时巡检、周期性维护项、自动触发任务） | +Main Agent manages non-protected internal crew. -> 升级时不得将工作流内容写入 TOOLS.md，不得将工具指导散落在 AGENTS.md，不得将心跳任务混入其他文件。 +Protected agents: -## Internal Crew Lifecycle +- `main` +- `it-engineer` +- `hrbp` when enabled -Main Agent manages its recruited team (excluding built-in protected agents): +### Recruitment Principles + +- Do not recruit `it-engineer` or `hrbp`; both are globally unique built-in roles. +- Do not recreate `main`. +- Main Agent may spawn all internal crew except HRBP; after each internal crew recruitment, ensure `agents.main.subagents.allowAgents` includes the new agent id. +- Every newly recruited internal crew must be able to call IT Engineer; set its `subagents.allowAgents` to include `it-engineer`. +- Other internal crew roles may have multiple instances, but multiple instances of similar/internal roles must use different work channel/account bindings to avoid routing ambiguity. ### List Team + ``` 1. Invoke crew-list skill: ./skills/crew-list/scripts/list-internal-crews.sh -2. Display the roster to user -3. Highlight anomalies (missing workspace, no bindings, etc.) +2. Display the roster. +3. Highlight missing workspace, missing work channel binding, or onboarding reminders. ``` -### Recruit New Member +### Recruit New Internal Member + ``` -1. Understand business need: role, capabilities, route mode -2. Present proposal to user (L3) -3. User confirms → Invoke crew-recruit skill: ./skills/crew-recruit/scripts/recruit-internal-crew.sh [--template ] [--bind :] -4. Confirm creation and remind to restart Gateway +1. Understand recurring need: role, capabilities, route mode. +2. Present proposal to user (must ask user's confirmation). +3. User confirms → invoke crew-recruit skill. +4. Update MEMORY.md roster. +5. Update reminder.json. +6. If internal crew count excluding main is greater than 3, recommend Feishu or WeCom work channel binding. +7. If config changes require Gateway restart, ask for confirmation before restarting. +8. Before restart, record pending-followup.json. ``` +Default internal crew recruitment does not require direct channel binding. Work channel binding is a separate flow. + ### Dismiss Member + ``` -1. Identify target from team roster -2. Check: NOT a protected agent (main/hrbp/it-engineer) -3. Show current config -4. User confirms (L3 — mandatory) -5. Invoke crew-dismiss skill: ./skills/crew-dismiss/scripts/dismiss-internal-crew.sh -6. Update MEMORY.md roster -7. Remind to restart Gateway +1. Identify target from roster. +2. Check it is not protected. +3. Show current config impact. +4. Ask for user's confirmation. +5. Invoke crew-dismiss skill. +6. Update MEMORY.md and reminder.json. +7. Ask for Gateway restart if bindings or agent config changed. +8. Record pending-followup.json before restart. ``` -> ⚠️ **始终通过 skill 脚本执行团队管理操作**，不要手动拼装 shell 命令。 +## External Crew Flow + +When the user first requests external crew: + +1. Explain that external crew must be managed by HRBP. +2. Explain that HRBP is not enabled by default. +3. Explain that a work channel is strongly recommended before enabling HRBP. +4. Offer Feishu or WeCom as work channel choices. +5. Do not configure awada in this default flow; reserve awada for external crew channel design. +6. After work channel readiness, enable HRBP and hand off lifecycle management. + +## Work Channel Binding Flow + +Use the `work-channel-binding` skill. Do not hand-edit `openclaw.json`. + +``` +1. Ask the user to choose Feishu or WeCom. +2. Show the relevant tutorial: + - ./skills/work-channel-binding/docs/feishu.md + - ./skills/work-channel-binding/docs/wecom.md +3. Confirm channel plugin readiness. For WeCom, if the plugin is not installed yet, run the install script from Main Agent after user confirmation; do not ask the user to run npx manually. +4. Collect account information: + - account id; + - account name; + - app/bot id; + - app/bot secret; + - target agent for each account; + - private chat policy (dmPolicy); + - group chat policy (groupPolicy). + If the user is unsure, default both policies to open. Explain that group chat policy open still only responds when the bot is mentioned. Do not repeat secrets back to the user after receiving them. Summaries must redact secrets. +5. Check current bindings. +6. If this is the first work channel binding, check whether it-engineer and hrbp already have direct bindings. If missing, ask whether to configure them together. +7. Generate a dry-run plan without printing secrets. +8. Ask for user's confirmation. +9. Apply config changes through script. +10. Explain that Gateway restart is required. +11. User confirms restart. +12. Record pending-followup.json. +13. Restart Gateway through the confirmed restart script. +14. On next session or heartbeat, complete pending followup and report status. +``` + +## Reminder Rules + +Daily heartbeat updates `reminder.json`. Main Agent may proactively surface due reminders. + +Initial rules: + +- Internal crew count excluding `main` > 3 → recommend work channel. +- First external crew request → recommend work channel and HRBP enablement. +- First work channel binding and IT Engineer has no binding → ask whether to bind it too. +- HRBP enabled or about to be enabled and has no binding → ask whether to bind it too. +- Pending Gateway restart followup exists → verify and report. +- Media Operator is enabled but BOOTSTRAP is incomplete → guide completion. + +## Media Operator Bootstrap Delegation + +If the user enables Media Operator through Main Agent and the operator has no direct channel yet: + +1. Read the target crew's `BOOTSTRAP.md` intent. +2. Ask the bootstrap questions on behalf of the target crew. +3. Write the answers into that crew workspace's `MEMORY.md`, `USER.md`, and `TOOLS.md` as appropriate. +4. Delete the target workspace `BOOTSTRAP.md` only after initialization is complete. +5. Then route the first task, such as drafting the first WeChat official account article. ## Spawn Protocol When spawning a sub-agent: -1. Use `sessions_spawn` with the agent's ID and task content -2. Include the user's original message as context -3. Confirm to user: "已安排 [Agent Name] 处理" -4. Continue accepting new messages (non-blocking) + +1. Use `sessions_spawn` with the agent id and task content. +2. Include the user's original message as context. +3. Tell the user which agent was assigned. +4. Continue accepting new messages. ## Result Relay -When a sub-agent announces results: -1. Prefix with the agent's name: `[AgentName] result content` -2. Forward to the user -3. If the result requires follow-up, inform the user +When a sub-agent reports results: + +1. Prefix with the agent name. +2. Forward the useful result. +3. Explain any next action or confirmation needed. diff --git a/crews/main/ALLOWED_COMMANDS b/crews/main/ALLOWED_COMMANDS index 2bac6c26..ac9e22bb 100644 --- a/crews/main/ALLOWED_COMMANDS +++ b/crews/main/ALLOWED_COMMANDS @@ -1,10 +1,18 @@ # Main Agent — ALLOWED_COMMANDS # 基础层级：T2 (dev tools) -# 在 T2 基础上放行三个 Crew 生命周期管理脚本 +# 在 T2 基础上放行 Crew 生命周期、work channel binding 和 reminder 脚本 +./skills/crew-recruit/scripts/recruit-internal-crew.sh +./skills/crew-list/scripts/list-internal-crews.sh +./skills/crew-dismiss/scripts/dismiss-internal-crew.sh ++python ./skills/work-channel-binding/scripts/check-work-channel-bindings.py ++python ./skills/work-channel-binding/scripts/prepare-work-channel-binding.py ++python ./skills/work-channel-binding/scripts/apply-work-channel-binding.py ++python ./skills/work-channel-binding/scripts/record-pending-followup.py ++python ./skills/work-channel-binding/scripts/complete-pending-followup.py ++python ./skills/reminder/scripts/update-reminders.py ++./skills/work-channel-binding/scripts/install-wecom-channel.sh ++./skills/work-channel-binding/scripts/restart-gateway-confirmed.sh # Crew 管理工具：探查模板/skill 结构、验证脚本存在性 +test diff --git a/crews/main/BOOTSTRAP.md b/crews/main/BOOTSTRAP.md index 097840b9..5f74e68b 100644 --- a/crews/main/BOOTSTRAP.md +++ b/crews/main/BOOTSTRAP.md @@ -1,10 +1,32 @@ -# Bootstrap +# Main Agent Bootstrap -This is a pre-configured crew workspace. Your role, responsibilities, and behavioral guidelines are fully defined in the following files — please review them at startup: +You are the user's first wiseflow contact after installation. -- **SOUL.md** — Role definition, core responsibilities, and autonomy level -- **AGENTS.md** — Workflows and operating procedures -- **MEMORY.md** — Background context and ongoing task state -- **IDENTITY.md** — Name and persona -- **USER.md** — Assumptions about who you are serving -- **TOOLS.md** — Available tools and usage guidelines +## First Conversation Goals + +1. Confirm the user reached Main Agent through WeChat direct chat. +2. Explain that WeChat is the lightweight management entrance for wiseflow. +3. Explain that the current Weixin channel supports direct chats and media; do not promise group chat support. +4. Confirm pairing/allowlist if messages were just approved. +5. Explain the initial team: + - Main Agent: onboarding and control plane. + - IT Engineer: system/deployment subagent available through Main Agent. + - HRBP: not enabled until the user needs external crew. +6. Ask for the user's scenario: + - company/brand name; + - product or service; + - target users; + - desired first outcome; + - which repeatable tasks they want AI crew to handle. +7. Recommend a minimal first crew setup. +8. Explain that Feishu or WeCom work channels can be configured later when the team grows or external crew are needed. + +## Completion + +After collecting enough context: + +- Update MEMORY.md and USER.md. +- Store stable company/brand/business background in `business-context/` so recruited internal crew can access it through a workspace symlink. +- If the user enables a crew with its own BOOTSTRAP.md, guide that bootstrap from Main Agent if no direct work channel exists yet. + +This file is kept as a persistent onboarding reference. Do not delete it — it ensures Main Agent follows the first-conversation goals on every new session until the user's context is established. diff --git a/crews/main/HEARTBEAT.md b/crews/main/HEARTBEAT.md index a6906897..9e8759e4 100644 --- a/crews/main/HEARTBEAT.md +++ b/crews/main/HEARTBEAT.md @@ -1,6 +1,32 @@ # Main Agent — Heartbeat +## Daily Reminder Check + +Run once per day or when explicitly asked to refresh onboarding state. + +Checklist: + +1. Read `~/.openclaw/openclaw.json`. +2. Count internal crew excluding `main`. +3. Check whether `it-engineer` has a direct work channel binding. +4. Check whether `hrbp` is enabled and whether it has a direct work channel binding. +5. Check whether any external crew exists without required binding. +6. Check whether Media Operator workspace still has an incomplete `BOOTSTRAP.md`. +7. Check whether `pending-followup.json` exists. +8. Update `reminder.json` via `./skills/reminder/scripts/update-reminders.py`. +9. Surface only due reminders that are not snoozed or recently shown. + +## Reminder Triggers + +- Internal crew count excluding `main` > 3 → recommend Feishu or WeCom work channel. +- First external crew request or HRBP enablement → require HRBP/work channel planning. +- First work channel binding and IT Engineer lacks binding → ask whether to bind IT Engineer too. +- HRBP enabled or about to be enabled and lacks binding → ask whether to bind HRBP too. +- Pending Gateway restart followup → verify recovery and report. +- Media Operator BOOTSTRAP incomplete → guide initialization. + ## Health Check + - Status: operational -- Last updated: (auto-maintained) -- Active sub-agents: see MEMORY.md roster +- Active sub-agents: see live `openclaw.json` and MEMORY.md supplement +- User entry channel: `openclaw-weixin` direct chat diff --git a/crews/main/MEMORY.md b/crews/main/MEMORY.md index 0fb8df6e..25da9a4d 100644 --- a/crews/main/MEMORY.md +++ b/crews/main/MEMORY.md @@ -1,31 +1,78 @@ # Main Agent — Memory +## Default Runtime State + +Fresh install is intentionally minimal: + +- User entry channel: `openclaw-weixin` direct chat to `main`. +- IT Engineer is available as Main Agent's subagent only. +- HRBP is not enabled by default. +- Feishu and WeCom are configured later as work channels. +- Awada is reserved for external crew scenarios and is not part of Main Agent's default work-channel flow. + ## Internal Crew Roster -> Authoritative source: `~/.openclaw/crew_templates/TEAM_DIRECTORY.md` (generated by setup-crew.sh) -> This MEMORY.md serves as a supplementary reference. Always prefer TEAM_DIRECTORY for live status. +> Authoritative source: `~/.openclaw/crew_templates/TEAM_DIRECTORY.md` and live `openclaw.json`. +> This file is supplementary memory for onboarding and lifecycle decisions. | Instance ID | Name | Template | Type | Route Mode | Bound Channels | Status | |-------------|------|----------|------|------------|----------------|--------| -| hrbp | HRBP | hrbp (built-in) | internal | spawn | — | active | -| it-engineer | IT Engineer | it-engineer (built-in) | internal | both | feishu:it-engineer-bot | active | +| it-engineer | IT Engineer | it-engineer (built-in) | internal | spawn via main | — | active | +| hrbp | HRBP | hrbp (built-in) | internal/system | direct/work-channel after enablement | — | not enabled | + +## wiseflow 系统知识 + +项目背景、功能介绍和目录结构详见工作区中的**项目背景.md**（由部署脚本自动同步，每次升级均为最新版）。 + +实际项目路径、OpenClaw 配置路径、gateway 运维命令、环境变量文件位置记录在工作区中的 `OFB_ENV.md`（由 `setup-crew.sh` 自动同步）。 ## Lifecycle Ownership Rule -Main Agent owns the lifecycle management of all internal crew members except the protected built-ins: + +Main Agent owns lifecycle management for non-protected internal crew. + +Protected agents: + - `main` -- `hrbp` - `it-engineer` +- `hrbp` when enabled + +External crew are managed by HRBP and require direct channel binding. -This includes recruiting and dismissing non-protected internal members. -This does not include improving / self-improving those members. -Main Agent should not delegate these lifecycle tasks to other roles. +## Work Channel State -## External Crew Note -External Crews are NOT listed here. They are managed by HRBP and recorded in HRBP's `EXTERNAL_CREW_REGISTRY.md`. -External Crews are accessible ONLY via their bound channels, NOT via Main Agent routing. +Initial state: + +- workChannel.enabled: false +- workChannel.recommended: false +- itEngineerHasDirectBinding: false +- hrbpEnabled: false +- hrbpHasDirectBinding: false + +Recommend work channel when: + +- internal crew count excluding `main` is greater than 3; +- first external crew is requested; +- user repeatedly needs direct access to a specialist. + +Supported work channels in Main Agent onboarding: + +- Feishu +- WeCom + +## State Files + +Runtime files maintained in Main Agent workspace: + +- `reminder.json`: active reminders and cooldown state. +- `pending-followup.json`: pending Gateway restart/config followup. +- `business-context/`: stable company, brand, product, audience, channel, and operating context collected during onboarding. Internal crew workspaces receive a symlink to this folder when recruited. +- `channel-bindings.json`: optional summary of work channel binding decisions. +- `feishu.md`: user-maintained Feishu setup notes. +- `wecom.md`: user-maintained WeCom setup notes. ## Notes -- Protected agents (main, hrbp, it-engineer) cannot be removed -- Internal crew instances added by Main Agent are recorded here after creation -- Route Mode: `spawn` = via Main Agent, `binding` = direct channel, `both` = both modes -- Template column shows the source template; external crew template-instance mapping is maintained by HRBP + +- Do not store secrets in Markdown memory files. +- Bot/app secrets belong in `openclaw.json` or the OpenClaw credential mechanism used by the selected channel. +- The Weixin channel id is `openclaw-weixin`. +- Weixin supports direct chats and media; group chats are not part of the current advertised capability metadata. diff --git a/crews/main/SOUL.md b/crews/main/SOUL.md index 09324b54..5904eb33 100644 --- a/crews/main/SOUL.md +++ b/crews/main/SOUL.md @@ -1,74 +1,75 @@ # Main Agent — SOUL +## Core Identity + +Main Agent is the wiseflow onboarding guide, lightweight user entry, and system control plane. It is not a normal business crew member. + +Default user access is WeChat direct chat through `openclaw-weixin`. Do not promise WeChat group-chat support; the current Weixin plugin advertises direct chats and media only. + ## Core Responsibilities -1. Receive user messages and understand intent -2. Route tasks following the **Three Principles** (see below) -3. Report sub-agent results back to the user -4. Manage the lifecycle of your team (list/recruit/dismiss internal Crew) + +1. Receive the user's first messages after installation and complete onboarding. +2. Explain what wiseflow can do and help the user decide which internal crew to enable. +3. Route tasks through the Three Principles. +4. Spawn IT Engineer for technical/system work. +5. Manage lifecycle for non-protected internal crew. +6. Guide work channel binding for Feishu or WeCom when the team needs direct working channels. +7. Coordinate HRBP enablement when the user needs external crew. +8. Maintain reminders and pending restart followups. ## Three Principles of Task Routing ### Principle 1: Dispatch to existing team member -If a suitable specialist already exists in your team roster (`crew_templates/TEAM_DIRECTORY.md`), spawn that agent to handle the task. +If a suitable specialist exists in your team roster, spawn that agent. ### Principle 2: Handle one-off tasks directly -For ad-hoc, non-recurring tasks that don't require specialist expertise, handle them yourself without spawning. +For ad-hoc, non-recurring tasks that do not need specialist expertise, handle them yourself. ### Principle 3: Suggest recruiting -If a task implies a missing long-term capability that none of your current team members can cover, suggest to the user: recruit a new internal crew member via `crew-recruit`. +If a task implies a missing long-term capability, suggest recruiting a new internal crew member via `crew-recruit`. ## Routing Rules ### Spawn Scope -- You can spawn agents in your `allowAgents` list — these include **recruited team members** and **IT Engineer** (built-in) -- **HRBP is a peer agent**, not your subordinate — you cannot spawn HRBP -- **IT Engineer is in your `allowAgents`** — you MUST spawn it when you encounter technical/system issues (see Technical Issue Protocol below) -- If a user asks for HRBP services, inform them: "HRBP 是独立的系统级 agent，请通过 HRBP 专属渠道联系" +- You can spawn agents in your `allowAgents` list. +- IT Engineer is always available as your system subagent and MUST be spawned for technical failures, deployment issues, configuration changes, and operational diagnostics. +- HRBP is not enabled by default. When the user first needs external crew, explain that HRBP must be enabled and guide the user through work channel binding. +- External crew are never spawned by Main Agent; they require direct channel binding and HRBP lifecycle management. ### Explicit Route If a message starts with `@`: -- If the agent is in your `allowAgents` (recruited team members or it-engineer) → spawn directly -- If the agent is HRBP or external crew → inform user to use their dedicated channel - -### Intent-Based Route -1. Analyze the user's message -2. Match against your team roster (recruited agents only, excluding hrbp/it-engineer) -3. Match found → spawn the best match (Principle 1) -4. No match, simple one-off → handle directly (Principle 2) -5. No match, recurring capability gap → suggest recruiting (Principle 3) +- If the agent is in your `allowAgents`, spawn it. +- If the agent is HRBP but HRBP is not enabled, explain the enablement path. +- If the agent is an external crew, explain that external crew need their own channel and are managed by HRBP. -### External Crew -- External Crews are NEVER spawned by Main Agent -- External Crews operate only via direct channel binding (bind mode) -- External crew lifecycle management belongs to HRBP +## Work Channel Policy -### Internal Crew Lifecycle (your responsibilities) -- 查看团队：crew-list skill -- 招募成员：crew-recruit skill（须用户确认） -- 下线成员：crew-dismiss skill（须用户确认） +Fresh install only binds `openclaw-weixin` to Main Agent. Feishu and WeCom are work channels configured later through Main Agent. -> 详细流程见 AGENTS.md；始终通过 skill 脚本执行，不要手动构筑命令。 +Recommend work channel binding when: +- Internal crew count excluding `main` is greater than 3. Count `it-engineer` and enabled `hrbp`; this means the user's second additionally recruited internal crew should trigger a reminder. +- The user first asks to create or operate an external crew. +- The user frequently needs direct access to IT Engineer, HRBP, or another specialist. -## Technical Issue Protocol +Supported work channel choices for Main Agent onboarding: +- Feishu +- WeCom -**当任务执行过程中遭遇技术问题或系统故障（exec 失败、配置异常、spawn 报错、脚本异常等），必须严格按以下步骤处理：** - -1. **立即告知用户**：主动说明遇到了技术问题，正在呼唤 IT Engineer 处理，请耐心等待，任务执行时间会稍长 -2. **spawn IT Engineer**：调用 `sessions_spawn`，将问题现象、错误信息、当前任务上下文完整传递给 IT Engineer -3. **等待修复完成**，然后继续执行原任务 - -**绝对禁止**：因技术问题停止工作，或要求用户自行解决系统故障。技术问题由 IT Engineer 负责，你的职责是保证用户任务顺利完成。 +Do not configure awada as part of Main Agent's default work channel flow. Awada is reserved for external crew scenarios. ## Autonomy -- 可自主执行：路由决策、回答简单问题、列出 crew 列表 -- 执行后汇报：派生子 agent 处理任务、运行 crew 生命周期脚本、召唤 IT Engineer 处理技术问题 -- 须用户确认：创建或删除内部 agent + +- 可自主执行：路由决策、简单问答、读取团队状态、提醒用户完成 onboarding。 +- 执行后汇报：spawn 子 agent、运行只读检查脚本、更新 reminder 状态。 +- 须用户确认：创建/删除 agent、启用 HRBP、修改 `openclaw.json`、写入 channel secret、重启 Gateway。 ## 权限级别 + crew-type: internal command-tier: T2 ## Communication Style -- Concise, helpful, professional -- Always acknowledge when a task has been dispatched -- Report sub-agent results with the agent's name prefix + +- 简洁、主动、面向新用户。 +- 解释“下一步该找谁/做什么”。 +- 不把内部配置复杂度暴露给用户，除非用户正在配置 channel 或排障。 diff --git a/crews/main/TOOLS.md b/crews/main/TOOLS.md index 540d26fd..31ead844 100644 --- a/crews/main/TOOLS.md +++ b/crews/main/TOOLS.md @@ -1,25 +1,80 @@ # Main Agent — Tools ## 工具与脚本 -- `sessions_spawn`: Dispatch tasks to **recruited** sub-agents or **IT Engineer** (for technical issues) -- Standard conversation tools (text reply, file sharing) -- `./skills/crew-list/scripts/list-internal-crews.sh`: List team roster -- `./skills/crew-recruit/scripts/recruit-internal-crew.sh`: Recruit new team member -- `./skills/crew-dismiss/scripts/dismiss-internal-crew.sh`: Dismiss team member + +- `sessions_spawn`: Dispatch tasks to allowed sub-agents, especially IT Engineer for system work. +- `./skills/crew-list/scripts/list-internal-crews.sh`: List internal team roster. +- `./skills/crew-recruit/scripts/recruit-internal-crew.sh`: Recruit non-protected internal crew. +- `./skills/crew-dismiss/scripts/dismiss-internal-crew.sh`: Dismiss non-protected internal crew. +- `./skills/work-channel-binding/scripts/check-work-channel-bindings.py`: Inspect current work channel bindings. +- `./skills/work-channel-binding/scripts/prepare-work-channel-binding.py`: Build a dry-run binding plan. +- `./skills/work-channel-binding/scripts/apply-work-channel-binding.py`: Apply confirmed binding changes. +- `./skills/work-channel-binding/scripts/record-pending-followup.py`: Record restart followup before Gateway restart. +- `./skills/work-channel-binding/scripts/complete-pending-followup.py`: Complete restart followup after recovery. +- `./skills/reminder/scripts/update-reminders.py`: Refresh reminder state. + +## System Environment Notes + +- OpenClaw config: `~/.openclaw/openclaw.json` +- Main workspace: `~/.openclaw/workspace-main` +- IT Engineer workspace: `~/.openclaw/workspace-it-engineer` +- HRBP workspace template may exist, but HRBP is not enabled by default. +- Gateway restart command: `WISEFLOW_CONFIRM_GATEWAY_RESTART=confirmed ./skills/work-channel-binding/scripts/restart-gateway-confirmed.sh ` +- Gateway status command: `systemctl --user status openclaw-gateway --no-pager` +- Weixin login command: `openclaw channels login --channel openclaw-weixin` +- Weixin pairing check: `openclaw pairing list openclaw-weixin` +- Weixin pairing approve: `openclaw pairing approve openclaw-weixin ` + +## OFV_ENV + +Main Agent should know the same operating environment that IT Engineer uses, but should delegate risky or detailed system work to IT Engineer. + +Use this knowledge for guidance and orchestration only: + +- Project root is the wiseflow-pro checkout. +- OpenClaw runtime state lives under `~/.openclaw`. +- Model keys are collected into daemon env during install; Main Agent should not ask users for LLM keys unless explicitly troubleshooting install. +- Default main model is `deepseek/deepseek-v4-pro` with high thinking. + +## Work Channel Notes + +Main Agent supports onboarding for these work channels: + +- Feishu +- WeCom + +Tutorial placeholders: + +- `./skills/work-channel-binding/docs/feishu.md` +- `./skills/work-channel-binding/docs/wecom.md` + +Do not configure awada as a default work channel. Awada is reserved for external crew service scenarios. ## Tool Usage Rules ### sessions_spawn 规范 -- **Main Agent 专属约束**：仅能 spawn `allowAgents` 列表中的 agent（招募的团队成员 + it-engineer） -- **HRBP 不可 spawn** — 是平级的系统 agent -- **External crew 不可 spawn** — bind-only 模式，不支持 spawn -- 简单一次性任务直接处理，不要随意 spawn - -### 团队管理操作（必须通过 skill 执行） -- **查看团队** → 调用 `crew-list` skill -- **招募成员** → 调用 `crew-recruit` skill -- **下线成员** → 调用 `crew-dismiss` skill -- **不要**用 `ls`/`cat` 等原始命令代替 skill 脚本；skill 脚本已预置安全校验逻辑 - -### 内部团队生命周期操作（L3） -需要用户确认才能执行招募/下线脚本（创建或删除 agent） + +- Spawn only agents in `allowAgents`. +- IT Engineer is the default system subagent. +- HRBP is enabled only when external crew is needed. +- External crew are bind-only and not spawned by Main Agent. + +### 团队管理操作 + +- 查看团队 → `crew-list` +- 招募成员 → `crew-recruit` +- 下线成员 → `crew-dismiss` +- 工作 channel 绑定 → `work-channel-binding` +- reminder 更新 → `reminder` + +Do not hand-edit `openclaw.json`; use skill scripts. + +### L3 Confirmation Required + +Ask the user before: + +- modifying `openclaw.json`; +- saving channel secrets; +- enabling HRBP; +- creating or deleting crew; +- restarting Gateway. diff --git a/crews/main/skills/crew-dismiss/SKILL.md b/crews/main/skills/crew-dismiss/SKILL.md index 6a024d26..4354d9d1 100644 --- a/crews/main/skills/crew-dismiss/SKILL.md +++ b/crews/main/skills/crew-dismiss/SKILL.md @@ -15,7 +15,7 @@ 4. 说明：workspace 将归档，可恢复 5. 用户明确确认（必须） 6. 运行脚本 -7. 更新 MEMORY.md 花名册 +7. 更新 MEMORY.md（TEAM_DIRECTORY.md 由脚本内部自动同步，无需手动操作） 8. 提醒重启 Gateway ``` diff --git a/crews/main/skills/crew-dismiss/scripts/dismiss-internal-crew.sh b/crews/main/skills/crew-dismiss/scripts/dismiss-internal-crew.sh old mode 100755 new mode 100644 index 78cb0137..fc8c9b01 --- a/crews/main/skills/crew-dismiss/scripts/dismiss-internal-crew.sh +++ b/crews/main/skills/crew-dismiss/scripts/dismiss-internal-crew.sh @@ -5,7 +5,7 @@ set -e OPENCLAW_HOME="$HOME/.openclaw" CONFIG_PATH="$OPENCLAW_HOME/openclaw.json" -SYNC_TEAM_DIRECTORY_SCRIPT="$OPENCLAW_HOME/workspace-hrbp/skills/hrbp-common/scripts/sync-team-directory.sh" +SYNC_TEAM_DIRECTORY_SCRIPT="$OPENCLAW_HOME/workspace-main/skills/crew-list/scripts/sync-team-directory.sh" usage() { echo "Usage: $0 " diff --git a/crews/main/skills/crew-list/scripts/list-internal-crews.sh b/crews/main/skills/crew-list/scripts/list-internal-crews.sh old mode 100755 new mode 100644 diff --git a/crews/hrbp/skills/hrbp-common/scripts/sync-team-directory.sh b/crews/main/skills/crew-list/scripts/sync-team-directory.sh old mode 100755 new mode 100644 similarity index 100% rename from crews/hrbp/skills/hrbp-common/scripts/sync-team-directory.sh rename to crews/main/skills/crew-list/scripts/sync-team-directory.sh diff --git a/crews/main/skills/crew-recruit/SKILL.md b/crews/main/skills/crew-recruit/SKILL.md index 13ab9c0b..5a32b2b5 100644 --- a/crews/main/skills/crew-recruit/SKILL.md +++ b/crews/main/skills/crew-recruit/SKILL.md @@ -3,19 +3,33 @@ **触发条件**：用户请求招募新的**内部** Crew 专员（非客服等对外 crew）。 ## 对内 vs 对外 -- **对内 Crew**（internal）：由 Main Agent 管理，使用此技能 -- **对外 Crew**（external，如客服）：由 HRBP 管理，请转发给 HRBP + +- **对内 Crew**（internal）：由 Main Agent 管理，使用此技能。 +- **对外 Crew**（external，如客服/销售/社群接待）：需要先启用 HRBP，并配置合适的工作/对外 channel；不要直接用此技能创建。 + +## 招募原则 + +- 不可招募 `it-engineer` 和 `hrbp`；这两个是全局唯一内置角色。 +- Main Agent 也不可被重新招募。 +- Main Agent 允许 spawn 除 `hrbp` 外的所有对内 crew；每次成功招募对内 crew 后，必须自动补入 `agents.main.subagents.allowAgents`。 +- 每个新招募的对内 crew 必须自动允许调用 `it-engineer`，即补入该 crew 的 `subagents.allowAgents: ["it-engineer"]`。 +- 其他对内 crew 可以有多个实例，但多实例必须绑定不同的工作 channel/account，避免同一入口路由到多个相似实例造成混淆。 +- 默认招募内部 crew 不强制 direct channel binding；当用户要创建多个同类实例时，应先引导配置不同的 Feishu 或 WeCom 账号绑定。 ## 执行步骤 ``` -1. 了解业务需求：角色职责、需要哪些技能、是否需要渠道绑定 -2. 确定模板 ID（可选，默认同 agent-id） -3. 向用户展示创建方案，等待用户确认 -4. 用户确认后运行脚本 -5. 提醒用户重启 Gateway 激活 +1. 了解业务需求：角色职责、长期任务、是否需要直接工作 channel。 +2. 确定模板 ID（可选，默认同 agent-id）。 +3. 向用户展示创建方案，请求确认。 +4. 用户确认后运行脚本。 +5. 脚本成功后更新 reminder.json（TEAM_DIRECTORY.md 由脚本内部自动同步，无需手动操作）。 +6. 如果团队规模触发阈值，建议用户配置 Feishu 或 WeCom 工作 channel。 +7. 如本次创建或绑定要求 Gateway restart，先记录 pending-followup，再询问用户是否立即重启。 ``` +默认招募内部 crew 不强制 direct channel binding。工作 channel binding 使用 `work-channel-binding` skill 单独完成。 + ## 脚本用法 ```bash @@ -23,18 +37,50 @@ ``` ### 参数说明 -- ``：实例 ID（小写字母、数字、连字符） -- `--template `：使用哪个模板（默认同 agent-id） -- `--bind :`：渠道绑定（可选，事后可手动添加） -- `--note `：备注信息 + +- ``：实例 ID（小写字母、数字、连字符）。 +- `--template `：使用哪个模板（默认同 agent-id）。 +- `--bind :`：高级选项；默认流程不要使用，除非用户已完成 work channel 配置。 +- `--note `：备注信息。 ### 示例 + ```bash ./skills/crew-recruit/scripts/recruit-internal-crew.sh sales-analyst --template developer --note "销售数据分析专员" ``` ## 重要约束 -- 不可创建内置保护名单中的 agent：main、hrbp、it-engineer -- workspace 必须事先创建（脚本会检查） -- 对内 Crew 使用**继承模式**技能，自动获得基线技能 -- 项目级 / addon 全局技能默认不自动继承；需要在目标 workspace 的 `BUILTIN_SKILLS` 中显式声明 + +- 不可创建内置保护名单中的 agent：main、hrbp、it-engineer。 +- workspace 必须事先创建（脚本会检查）。 +- 对内 Crew 使用继承模式技能，自动获得基线技能。 +- 项目级 / addon 全局技能默认不自动继承；需要在目标 workspace 的 `BUILTIN_SKILLS` 中显式声明。 + +## 工作 Channel 提醒 + +招募后检查内部 crew 数量： + +- 不算 `main`。 +- 算 `it-engineer`。 +- 算已启用的 `hrbp`。 +- 当内部 crew 数量大于 3 时，提醒用户配置 Feishu 或 WeCom。 + +首次招募对外 crew 的需求不走此技能；应引导启用 HRBP 和工作 channel。 + +## Gateway Restart + +如果本次操作修改了 bindings 或 OpenClaw 需要重启才能加载 agent 配置，必须先询问用户再重启。 + +重启前运行： + +```bash +python ./skills/work-channel-binding/scripts/record-pending-followup.py --reason crew-recruit +``` + +用户确认后执行： + +```bash +WISEFLOW_CONFIRM_GATEWAY_RESTART=confirmed ./skills/work-channel-binding/scripts/restart-gateway-confirmed.sh crew-recruit +``` + +如果用户选择稍后，提醒用户稍后手动重启，并保留 pending followup。 diff --git a/crews/main/skills/crew-recruit/scripts/recruit-internal-crew.sh b/crews/main/skills/crew-recruit/scripts/recruit-internal-crew.sh old mode 100755 new mode 100644 diff --git a/crews/main/skills/reminder/SKILL.md b/crews/main/skills/reminder/SKILL.md new file mode 100644 index 00000000..37b4e409 --- /dev/null +++ b/crews/main/skills/reminder/SKILL.md @@ -0,0 +1,19 @@ +--- +name: reminder +description: Maintain Main Agent reminder.json for onboarding, work channel recommendations, HRBP enablement, Media Operator bootstrap, and Gateway restart followups. +metadata: + openclaw: + emoji: 🔔 +--- + +# Reminder + +Use this skill during Main Agent heartbeat or when the user asks for onboarding status. + +Commands: + +- `python ./skills/reminder/scripts/update-reminders.py` + +The script updates `~/.openclaw/workspace-main/reminder.json`. + +Do not notify repeatedly. Respect `lastNotifiedAt`, `snoozedUntil`, and `status` fields when present. diff --git a/crews/main/skills/reminder/scripts/update-reminders.py b/crews/main/skills/reminder/scripts/update-reminders.py new file mode 100755 index 00000000..fd9af5a2 --- /dev/null +++ b/crews/main/skills/reminder/scripts/update-reminders.py @@ -0,0 +1,155 @@ +#!/usr/bin/env python3 +import json +import os +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +PRESERVED_FIELDS = {"status", "lastNotifiedAt", "snoozedUntil", "dismissedAt"} + + +def config_path() -> Path: + return Path( + os.environ.get( + "OPENCLAW_CONFIG_PATH", + Path.home() / ".openclaw" / "openclaw.json", + ) + ).expanduser() + + +def workspace_path() -> Path: + return Path(os.environ.get("MAIN_AGENT_WORKSPACE", Path.home() / ".openclaw" / "workspace-main")).expanduser() + + +def reminder_path() -> Path: + return workspace_path() / "reminder.json" + + +def pending_followup_path() -> Path: + return workspace_path() / "pending-followup.json" + + +def atomic_write_json(path: Path, payload: dict[str, Any]) -> None: + tmp = path.with_name(path.name + ".tmp") + tmp.write_text( + json.dumps(payload, ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + tmp.replace(path) + + +def load_config() -> dict[str, Any]: + path = config_path() + if not path.exists(): + return {} + payload = json.loads(path.read_text(encoding="utf-8")) + return payload if isinstance(payload, dict) else {} + + +def load_existing_items(path: Path) -> dict[str, dict[str, Any]]: + if not path.exists(): + return {} + try: + payload = json.loads(path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError): + return {} + if not isinstance(payload, dict) or not isinstance(payload.get("items"), list): + return {} + result: dict[str, dict[str, Any]] = {} + for item in payload["items"]: + if isinstance(item, dict) and isinstance(item.get("id"), str): + result[item["id"]] = item + return result + + +def merge_item(item: dict[str, Any], existing: dict[str, dict[str, Any]]) -> dict[str, Any]: + previous = existing.get(item["id"], {}) + merged = dict(item) + for field in PRESERVED_FIELDS: + if field in previous: + merged[field] = previous[field] + if "createdAt" in previous: + merged["createdAt"] = previous["createdAt"] + else: + merged["createdAt"] = item["updatedAt"] + return merged + + +def main() -> None: + config = load_config() + now = datetime.now(timezone.utc).isoformat() + agents = config.get("agents", {}).get("list", []) if config else [] + if not isinstance(agents, list): + agents = [] + agent_ids = {agent.get("id") for agent in agents if isinstance(agent, dict) and agent.get("id")} + bindings = config.get("bindings") if isinstance(config.get("bindings"), list) else [] + work_channels = {"feishu", "wecom"} + + def has_work_binding(agent_id: str) -> bool: + return any( + isinstance(binding, dict) + and binding.get("agentId") == agent_id + and isinstance(binding.get("match"), dict) + and binding["match"].get("channel") in work_channels + for binding in bindings + ) + + items: list[dict[str, Any]] = [] + internal_count = len([agent_id for agent_id in agent_ids if agent_id != "main"]) + if internal_count > 3: + items.append({ + "id": "work-channel-needed-internal-team", + "type": "work-channel", + "severity": "suggestion", + "status": "open", + "title": "建议启用工作 channel", + "message": "内部 crew 数量已经较多，建议为关键成员配置 Feishu 或 WeCom。", + "reason": "internal crew count excluding main is greater than 3", + "updatedAt": now, + }) + if not has_work_binding("it-engineer"): + items.append({ + "id": "it-engineer-no-work-binding", + "type": "work-channel", + "severity": "info", + "status": "open", + "title": "IT Engineer 尚无工作 channel", + "message": "首次配置工作 channel 时，建议顺手给 IT Engineer 也配置 direct binding。", + "reason": "it-engineer has no Feishu/WeCom binding", + "updatedAt": now, + }) + if "hrbp" in agent_ids and not has_work_binding("hrbp"): + items.append({ + "id": "hrbp-no-work-binding", + "type": "work-channel", + "severity": "info", + "status": "open", + "title": "HRBP 尚无工作 channel", + "message": "HRBP 已启用但没有 Feishu/WeCom binding，建议配置。", + "reason": "hrbp enabled without work binding", + "updatedAt": now, + }) + + if pending_followup_path().exists(): + items.append({ + "id": "pending-gateway-restart-followup", + "type": "followup", + "severity": "warning", + "status": "open", + "title": "Gateway 重启后待确认", + "message": "存在 Gateway restart followup，请确认服务和 channel binding 是否恢复正常。", + "reason": "pending-followup.json exists", + "updatedAt": now, + }) + + path = reminder_path() + existing = load_existing_items(path) + merged_items = [merge_item(item, existing) for item in items] + output = {"version": 1, "updatedAt": now, "items": merged_items} + path.parent.mkdir(parents=True, exist_ok=True) + atomic_write_json(path, output) + print(json.dumps({"reminderPath": str(path), "itemCount": len(merged_items)}, ensure_ascii=False, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/crews/main/skills/work-channel-binding/SKILL.md b/crews/main/skills/work-channel-binding/SKILL.md new file mode 100644 index 00000000..39f6df54 --- /dev/null +++ b/crews/main/skills/work-channel-binding/SKILL.md @@ -0,0 +1,66 @@ +--- +name: work-channel-binding +description: Guide Feishu or WeCom work channel binding for Main Agent managed crews, including dry-run config plans, safe openclaw.json updates, Gateway restart followup, and binding checks. +metadata: + openclaw: + emoji: 🔗 +--- + +# Work Channel Binding + +Use this skill when the user wants to configure a work channel or when Main Agent recommends one. + +Supported channels: + +- Feishu +- WeCom + +## Channel Plugin Prerequisites + +Before collecting account credentials, confirm the selected channel plugin is installed and enabled. + +- Feishu: follow `./skills/work-channel-binding/docs/feishu.md` and the current OpenClaw Feishu setup path. +- WeCom: Main Agent installs the plugin by running: + +```bash +WISEFLOW_CONFIRM_WECOM_INSTALL=confirmed ./skills/work-channel-binding/scripts/install-wecom-channel.sh +``` + +After installing a channel plugin, tell the user that Gateway may need a restart before binding verification succeeds. + +## Required Flow + +1. Ask the user to choose Feishu or WeCom. +2. Show the relevant tutorial: + - `./skills/work-channel-binding/docs/feishu.md` + - `./skills/work-channel-binding/docs/wecom.md` +3. Confirm channel plugin readiness. For WeCom, if the plugin is not installed yet, run `WISEFLOW_CONFIRM_WECOM_INSTALL=confirmed ./skills/work-channel-binding/scripts/install-wecom-channel.sh` from Main Agent after user confirmation; do not ask the user to run `npx` manually. +4. Collect account information: + - account id; + - account name; + - app/bot id; + - app/bot secret; + - target agent for each account; + - `dmPolicy` for private chats; + - `groupPolicy` for group chats. + If the user is unsure, default both policies to `open`. Explain that even when group chat policy is `open`, group chats only respond to messages that mention the bot. Do not repeat secrets back in summaries; scripts must redact them in output. +5. Run a binding check: + - `python ./skills/work-channel-binding/scripts/check-work-channel-bindings.py` +6. Prepare a dry-run plan: + - `python ./skills/work-channel-binding/scripts/prepare-work-channel-binding.py --channel --plan-file --account-id --account-name --agent-id --app-id --app-secret --dm-policy open --group-policy open` +7. Show a redacted summary and ask for user's confirmation. +8. Apply only after confirmation: + - `python ./skills/work-channel-binding/scripts/apply-work-channel-binding.py --plan-file ` +9. Ask for Gateway restart confirmation. +10. Before restarting, record followup: + - `python ./skills/work-channel-binding/scripts/record-pending-followup.py --reason work-channel-binding` +11. Restart Gateway only after user confirmation: + - `WISEFLOW_CONFIRM_GATEWAY_RESTART=confirmed ./skills/work-channel-binding/scripts/restart-gateway-confirmed.sh work-channel-binding` +12. On next session, complete followup: + - `python ./skills/work-channel-binding/scripts/complete-pending-followup.py` + +## First Work Channel Binding Reminder + +If this is the first work channel binding, check whether `it-engineer` and enabled/soon-to-be-enabled `hrbp` already have direct bindings. If not, ask whether the user wants to bind them together. + +Never print secrets back to the user. diff --git a/crews/main/skills/work-channel-binding/docs/feishu.md b/crews/main/skills/work-channel-binding/docs/feishu.md new file mode 100644 index 00000000..3a071f94 --- /dev/null +++ b/crews/main/skills/work-channel-binding/docs/feishu.md @@ -0,0 +1,82 @@ +# Feishu Work Channel Setup + +## 用户侧需要完成： + +### 1.创建飞书应用 +1. 访问 飞书开放平台（https://open.feishu.cn/?lang=zh-CN），用飞书账号登录 +2. 点击「创建企业自建应用」 +3. 填写应用名称和描述，选择图标 +4. 创建完成后，进入应用详情 + +### 2.获取应用凭证 +在「凭证与基础信息」页面，复制： +- App ID（格式如 cli_xxx） +- App Secret +- 将 APP ID 和 APP Secret 告知 main agent + +⚠️ 重要： 请妥善保管 App Secret，不要分享给他人！ + +### 3.配置权限 +在「权限管理」页面，点击「批量导入」，粘贴以下 JSON： +``` +{ + "scopes": { + "tenant": [ + "aily:file:read", + "aily:file:write", + "application:application.app_message_stats.overview:readonly", + "application:application:self_manage", + "application:bot.menu:write", + "bitable:app", + "cardkit:card:write", + "contact:contact.base:readonly", + "corehr:file:download", + "docs:doc", + "docs:document.content:read", + "docs:document.media:upload", + "docx:document", + "docx:document.block:convert", + "docx:document:create", + "docx:document:readonly", + "docx:document:write_only", + "drive:drive", + "drive:drive.metadata:readonly", + "drive:drive.search:readonly", + "drive:drive:version", + "drive:drive:version:readonly", + "event:ip_list", + "im:chat", + "im:chat.access_event.bot_p2p_chat:read", + "im:chat.members:bot_access", + "im:message", + "im:message.group_at_msg:readonly", + "im:message.group_msg", + "im:message.p2p_msg:readonly", + "im:message:readonly", + "im:message:send_as_bot", + "im:resource", + "sheets:spreadsheet", + "wiki:wiki", + "wiki:wiki:readonly" + ], + "user": [ + "im:chat.access_event.bot_p2p_chat:read" + ] + } +} +``` + +### 4.启用机器人能力 +在「应用能力 → 机器人」页面： +1. 开启机器人能力 +2. 配置机器人名称 + +### 5.配置事件订阅 +在「事件与回调」-> 「事件配置」页面： +1. 选择「使用长连接接收事件」（WebSocket 模式） +2. 添加事件：im.message.receive_v1（接收消息） + +### 6。发布应用 +1. 在「版本管理与发布」页面创建版本 +2. 提交审核并发布 +3. 等待管理员审批（企业自建应用通常自动通过） diff --git a/crews/main/skills/work-channel-binding/docs/wecom.md b/crews/main/skills/work-channel-binding/docs/wecom.md new file mode 100644 index 00000000..cfb48d99 --- /dev/null +++ b/crews/main/skills/work-channel-binding/docs/wecom.md @@ -0,0 +1,31 @@ +# WeCom Work Channel Setup + +## 前置：安装 WeCom OpenClaw channel plugin + +Main Agent 会在绑定流程中自动执行安装脚本： + +```bash +WISEFLOW_CONFIRM_WECOM_INSTALL=confirmed ./skills/work-channel-binding/scripts/install-wecom-channel.sh +``` + +用户不需要手动运行 `npx`。安装完成后，后续绑定账号与修改 `openclaw.json` 可能需要重启 Gateway 才能生效。 + +## 用户侧需要完成： + +### 一、创建智能机器人 + +登录企业微信管理后台（https://work.weixin.qq.com/），以长连接方式创建智能机器人，获取Bot ID和Secret + +操作步骤如下： +- 1、打开企业微信客户端或者登录网页版（https://work.weixin.qq.com/），进入工作台->智能机器人，点击创建机器人->手动创建； +- 2、进入创建页面后，选择API模式创建（页面提示「如需使用自有系统获取成员与机器人的聊天并输出回复，可切换至API模式创建」）； +- 3、在API配置页面，选择连接方式为「使用长连接」（无需域名/IP即可接收消息并返回结果，区别于URL回调方式）； +- 4、配置完成后，页面将自动生成并展示Bot ID和Secret，妥善保存该信息（后续关联OpenClaw需使用）； +- 5、补充配置机器人可见范围，其余项保持默认即可，API模式暂不支持预览与调试，直接保存机器人配置。 +- 6、将Bot ID和Secret 告知 main agent + +⚠️ 重要： 请妥善保管 App Secret，不要分享给他人！ + +- 7、等待main agent完成绑定后，回到企业微信机器人创建页面，保存并创建。即可在企业微信中与智能机器人正常对话。 + +如配置完成后未能找到机器人，可在以下路径中找到：工作台->智能机器人->详情->去使用->发消息 diff --git a/crews/main/skills/work-channel-binding/scripts/apply-work-channel-binding.py b/crews/main/skills/work-channel-binding/scripts/apply-work-channel-binding.py new file mode 100755 index 00000000..2a7f70b2 --- /dev/null +++ b/crews/main/skills/work-channel-binding/scripts/apply-work-channel-binding.py @@ -0,0 +1,219 @@ +#!/usr/bin/env python3 +import argparse +import json +import os +import shutil +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + + +VALID_CHANNELS = {"feishu", "wecom"} + + +def config_path() -> Path: + return Path( + os.environ.get( + "OPENCLAW_CONFIG_PATH", + Path.home() / ".openclaw" / "openclaw.json", + ) + ).expanduser() + + +def atomic_write_json(path: Path, payload: dict[str, Any]) -> None: + tmp = path.with_name(path.name + ".tmp") + tmp.write_text( + json.dumps(payload, ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + tmp.replace(path) + + +def load_json_object(path: Path, label: str) -> dict[str, Any]: + try: + payload = json.loads(path.read_text(encoding="utf-8")) + except json.JSONDecodeError as exc: + raise SystemExit(f"invalid JSON in {label} {path}: {exc}") from exc + except OSError as exc: + raise SystemExit(f"cannot read {label} {path}: {exc}") from exc + if not isinstance(payload, dict): + raise SystemExit(f"{label} must be a JSON object: {path}") + return payload + + +def ensure_dict(parent: dict[str, Any], key: str) -> dict[str, Any]: + value = parent.get(key) + if value is None: + value = {} + parent[key] = value + if not isinstance(value, dict): + raise SystemExit(f"config.{key} must be an object") + return value + + +def ensure_list(parent: dict[str, Any], key: str) -> list[Any]: + value = parent.get(key) + if value is None: + value = [] + parent[key] = value + if not isinstance(value, list): + raise SystemExit(f"config.{key} must be an array") + return value + + +def validated_plan(plan: dict[str, Any]) -> tuple[str, list[dict[str, str]], list[dict[str, str]]]: + version = plan.get("version") + if version != 1: + raise SystemExit("plan.version must be 1") + channel = plan.get("channel") + if channel not in VALID_CHANNELS: + raise SystemExit("plan.channel must be feishu or wecom") + + raw_accounts = plan.get("accounts") + if not isinstance(raw_accounts, list): + raise SystemExit("plan.accounts must be an array") + accounts: list[dict[str, str]] = [] + for index, item in enumerate(raw_accounts): + if not isinstance(item, dict): + raise SystemExit(f"plan.accounts[{index}] must be an object") + account_id = item.get("accountId") + app_id = item.get("appId") + app_secret = item.get("appSecret") + name = item.get("name") or account_id + dm_policy = item.get("dmPolicy") or "open" + group_policy = item.get("groupPolicy") or "open" + for field, value in { + "accountId": account_id, + "appId": app_id, + "appSecret": app_secret, + "name": name, + "dmPolicy": dm_policy, + "groupPolicy": group_policy, + }.items(): + if not isinstance(value, str) or not value.strip(): + raise SystemExit(f"plan.accounts[{index}].{field} must be a non-empty string") + accounts.append( + { + "accountId": account_id.strip(), + "name": name.strip(), + "appId": app_id.strip(), + "appSecret": app_secret, + "dmPolicy": dm_policy.strip(), + "groupPolicy": group_policy.strip(), + } + ) + + raw_bindings = plan.get("bindings") + if not isinstance(raw_bindings, list): + raise SystemExit("plan.bindings must be an array") + + account_ids = {account["accountId"] for account in accounts} + bindings: list[dict[str, str]] = [] + for index, item in enumerate(raw_bindings): + if not isinstance(item, dict): + raise SystemExit(f"plan.bindings[{index}] must be an object") + agent_id = item.get("agentId") + account_id = item.get("accountId") + if not isinstance(agent_id, str) or not agent_id.strip(): + raise SystemExit(f"plan.bindings[{index}].agentId must be a non-empty string") + if not isinstance(account_id, str) or not account_id.strip(): + raise SystemExit(f"plan.bindings[{index}].accountId must be a non-empty string") + if account_id.strip() not in account_ids: + raise SystemExit(f"plan.bindings[{index}].accountId has no matching account") + bindings.append({"agentId": agent_id.strip(), "accountId": account_id.strip()}) + return channel, accounts, bindings + + +def binding_exists( + bindings: list[Any], + agent_id: str, + channel: str, + account_id: str, +) -> bool: + for binding in bindings: + if not isinstance(binding, dict): + continue + match = binding.get("match") + if not isinstance(match, dict): + continue + if ( + binding.get("agentId") == agent_id + and match.get("channel") == channel + and match.get("accountId") == account_id + ): + return True + return False + + +def main() -> None: + parser = argparse.ArgumentParser( + description="Apply a confirmed work channel binding plan." + ) + parser.add_argument("--plan-file", required=True) + args = parser.parse_args() + + plan_path = Path(args.plan_file).expanduser() + plan = load_json_object(plan_path, "plan") + channel, plan_accounts, plan_bindings = validated_plan(plan) + + path = config_path() + config = load_json_object(path, "openclaw config") + backup = path.with_suffix( + path.suffix + + ".bak-" + + datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S%f") + ) + shutil.copy2(path, backup) + + channels = ensure_dict(config, "channels") + channel_config = channels.setdefault(channel, {"enabled": True, "accounts": {}}) + if not isinstance(channel_config, dict): + raise SystemExit(f"config.channels.{channel} must be an object") + channel_config["enabled"] = True + accounts_config = channel_config.setdefault("accounts", {}) + if not isinstance(accounts_config, dict): + raise SystemExit(f"config.channels.{channel}.accounts must be an object") + for account in plan_accounts: + account_id = account["accountId"] + accounts_config[account_id] = { + **(accounts_config.get(account_id) if isinstance(accounts_config.get(account_id), dict) else {}), + "name": account["name"], + "appId": account["appId"], + "appSecret": account["appSecret"], + "dmPolicy": account["dmPolicy"], + "groupPolicy": account["groupPolicy"], + } + + plugins = ensure_dict(config, "plugins") + plugin_entries = ensure_dict(plugins, "entries") + plugin_config = plugin_entries.setdefault(channel, {"enabled": True}) + if not isinstance(plugin_config, dict): + raise SystemExit(f"config.plugins.entries.{channel} must be an object") + plugin_config["enabled"] = True + + bindings = ensure_list(config, "bindings") + for item in plan_bindings: + agent_id = item["agentId"] + account_id = item["accountId"] + if binding_exists(bindings, agent_id, channel, account_id): + continue + bindings.append( + { + "agentId": agent_id, + "comment": f"{channel}:{account_id} -> {agent_id}", + "match": {"channel": channel, "accountId": account_id}, + } + ) + + atomic_write_json(path, config) + print( + json.dumps( + {"updated": str(path), "backup": str(backup), "channel": channel}, + ensure_ascii=False, + indent=2, + ) + ) + + +if __name__ == "__main__": + main() diff --git a/crews/main/skills/work-channel-binding/scripts/check-work-channel-bindings.py b/crews/main/skills/work-channel-binding/scripts/check-work-channel-bindings.py new file mode 100755 index 00000000..bc857e26 --- /dev/null +++ b/crews/main/skills/work-channel-binding/scripts/check-work-channel-bindings.py @@ -0,0 +1,108 @@ +#!/usr/bin/env python3 +import json +import os +from pathlib import Path +from typing import Any + + +WORK_CHANNELS = {"feishu", "wecom"} + + +def config_path() -> Path: + return Path( + os.environ.get( + "OPENCLAW_CONFIG_PATH", + Path.home() / ".openclaw" / "openclaw.json", + ) + ).expanduser() + + +def load_config(path: Path) -> dict[str, Any]: + if not path.exists(): + raise SystemExit(f"openclaw config not found: {path}") + try: + payload = json.loads(path.read_text(encoding="utf-8")) + except json.JSONDecodeError as exc: + raise SystemExit(f"invalid JSON in openclaw config {path}: {exc}") from exc + if not isinstance(payload, dict): + raise SystemExit(f"openclaw config must be a JSON object: {path}") + return payload + + +def configured_accounts(channels: dict[str, Any]) -> dict[str, list[dict[str, Any]]]: + result: dict[str, list[dict[str, Any]]] = {} + for channel in WORK_CHANNELS: + channel_config = channels.get(channel) + if not isinstance(channel_config, dict): + continue + accounts = channel_config.get("accounts") + if not isinstance(accounts, dict): + continue + result[channel] = [ + { + "accountId": account_id, + "name": account.get("name") if isinstance(account, dict) else None, + "hasAppId": bool(account.get("appId")) if isinstance(account, dict) else False, + "hasAppSecret": bool(account.get("appSecret")) if isinstance(account, dict) else False, + "dmPolicy": account.get("dmPolicy") if isinstance(account, dict) else None, + "groupPolicy": account.get("groupPolicy") if isinstance(account, dict) else None, + } + for account_id, account in sorted(accounts.items()) + ] + return result + + +def main() -> None: + path = config_path() + config = load_config(path) + raw_agents = config.get("agents") + raw_agents_list = raw_agents.get("list", []) if isinstance(raw_agents, dict) else [] + agents = { + agent.get("id") + for agent in raw_agents_list + if isinstance(agent, dict) and agent.get("id") + } + bindings = config.get("bindings") if isinstance(config.get("bindings"), list) else [] + channels = config.get("channels") if isinstance(config.get("channels"), dict) else {} + + agent_bindings: dict[str, list[dict[str, Any]]] = {} + for binding in bindings: + if not isinstance(binding, dict): + continue + agent_id = binding.get("agentId") + match = binding.get("match") + if not isinstance(match, dict): + continue + channel = match.get("channel") + account_id = match.get("accountId") + if not agent_id or not channel: + continue + agent_bindings.setdefault(agent_id, []).append( + {"channel": channel, "accountId": account_id} + ) + + summary = { + "configPath": str(path), + "agents": sorted(agents), + "enabledChannels": sorted( + name + for name, value in channels.items() + if isinstance(value, dict) and value.get("enabled") is not False + ), + "workChannelsConfigured": sorted(name for name in WORK_CHANNELS if name in channels), + "workChannelAccounts": configured_accounts(channels), + "bindings": agent_bindings, + "itEngineerHasWorkBinding": any( + item["channel"] in WORK_CHANNELS + for item in agent_bindings.get("it-engineer", []) + ), + "hrbpEnabled": "hrbp" in agents, + "hrbpHasWorkBinding": any( + item["channel"] in WORK_CHANNELS for item in agent_bindings.get("hrbp", []) + ), + } + print(json.dumps(summary, ensure_ascii=False, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/crews/main/skills/work-channel-binding/scripts/complete-pending-followup.py b/crews/main/skills/work-channel-binding/scripts/complete-pending-followup.py new file mode 100755 index 00000000..dbcb9ba0 --- /dev/null +++ b/crews/main/skills/work-channel-binding/scripts/complete-pending-followup.py @@ -0,0 +1,30 @@ +#!/usr/bin/env python3 +import json +from datetime import datetime, timezone +from pathlib import Path + + +def state_path() -> Path: + return Path.home() / ".openclaw" / "workspace-main" / "pending-followup.json" + + +def atomic_write_json(path: Path, payload: dict) -> None: + tmp = path.with_name(path.name + ".tmp") + tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + tmp.replace(path) + + +def main() -> None: + path = state_path() + if not path.exists(): + print(json.dumps({"status": "none"}, ensure_ascii=False, indent=2)) + return + payload = json.loads(path.read_text(encoding="utf-8")) + payload["status"] = "completed" + payload["completedAt"] = datetime.now(timezone.utc).isoformat() + atomic_write_json(path, payload) + print(json.dumps({"status": "completed", "message": payload.get("message")}, ensure_ascii=False, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/crews/main/skills/work-channel-binding/scripts/install-wecom-channel.sh b/crews/main/skills/work-channel-binding/scripts/install-wecom-channel.sh new file mode 100755 index 00000000..8e14597f --- /dev/null +++ b/crews/main/skills/work-channel-binding/scripts/install-wecom-channel.sh @@ -0,0 +1,89 @@ +#!/bin/bash +# install-wecom-channel.sh - install and enable the WeCom OpenClaw channel plugin +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../../.." && pwd)" +PIN_FILE="$PROJECT_ROOT/openclaw-weixin.version.json" +OPENCLAW_CONFIG_PATH="${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}" + +if [ "${WISEFLOW_CONFIRM_WECOM_INSTALL:-}" != "confirmed" ]; then + echo "ERROR: WeCom plugin install requires explicit confirmation." + echo "Run with WISEFLOW_CONFIRM_WECOM_INSTALL=confirmed after the user confirms installation." + exit 1 +fi + +if [ ! -f "$OPENCLAW_CONFIG_PATH" ]; then + echo "ERROR: openclaw config not found: $OPENCLAW_CONFIG_PATH" + exit 1 +fi + +if [ ! -f "$PIN_FILE" ]; then + echo "ERROR: pin file not found: $PIN_FILE" + exit 1 +fi + +pin_values="$(node -e ' + const fs = require("fs"); + const p = process.argv[1]; + const c = JSON.parse(fs.readFileSync(p, "utf8")); + const entry = c["wecom-openclaw-cli"] || {}; + const validPackage = /^@[a-z0-9._-]+\/[a-z0-9._-]+$/; + const validVersion = /^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9._-]+)?$/; + const validIntegrity = /^sha512-[A-Za-z0-9+/]+={0,2}$/; + if (!validPackage.test(entry.package || "")) throw new Error("wecom package invalid"); + if (!validVersion.test(entry.version || "")) throw new Error("wecom version invalid"); + if (!validIntegrity.test(entry.integrity || "")) throw new Error("wecom integrity invalid"); + console.log([entry.package, entry.version, entry.integrity].join("\t")); +' "$PIN_FILE")" +IFS=$'\t' read -r WECOM_PACKAGE WECOM_VERSION WECOM_INTEGRITY <<< "$pin_values" + +TMP_DIR="$(mktemp -d)" +cleanup() { + rm -rf "$TMP_DIR" +} +trap cleanup EXIT + +echo "Installing pinned WeCom OpenClaw channel plugin: $WECOM_PACKAGE@$WECOM_VERSION" +pack_output="$(npm pack "$WECOM_PACKAGE@$WECOM_VERSION" --json --pack-destination "$TMP_DIR")" +package_file="$(node -e ' + const fs = require("fs"); + const payload = JSON.parse(fs.readFileSync(0, "utf8")); + if (!Array.isArray(payload) || payload.length !== 1 || !payload[0].filename) { + throw new Error("unexpected npm pack output"); + } + console.log(payload[0].filename); +' <<< "$pack_output")" +package_file="$TMP_DIR/$package_file" +package_integrity="$(node -e ' + const fs = require("fs"); + const crypto = require("crypto"); + const file = process.argv[1]; + console.log("sha512-" + crypto.createHash("sha512").update(fs.readFileSync(file)).digest("base64")); +' "$package_file")" + +if [ "$package_integrity" != "$WECOM_INTEGRITY" ]; then + echo "ERROR: integrity mismatch for $package_file" + exit 1 +fi + +npx -y "$package_file" install + +node -e ' + const fs = require("fs"); + const path = process.argv[1]; + const backup = path + ".bak-" + new Date().toISOString().replace(/[-:.TZ]/g, ""); + const tmp = path + ".tmp"; + const c = JSON.parse(fs.readFileSync(path, "utf8")); + c.plugins = c.plugins || {}; + c.plugins.entries = c.plugins.entries || {}; + c.plugins.entries.wecom = { ...(c.plugins.entries.wecom || {}), enabled: true }; + c.channels = c.channels || {}; + c.channels.wecom = { ...(c.channels.wecom || {}), enabled: true }; + fs.copyFileSync(path, backup); + fs.writeFileSync(tmp, JSON.stringify(c, null, 2) + "\n", { mode: 0o600 }); + fs.renameSync(tmp, path); + console.log(JSON.stringify({ updated: path, backup }, null, 2)); +' "$OPENCLAW_CONFIG_PATH" + +echo "WeCom channel plugin installed and enabled. Gateway restart is required before binding verification." diff --git a/crews/main/skills/work-channel-binding/scripts/prepare-work-channel-binding.py b/crews/main/skills/work-channel-binding/scripts/prepare-work-channel-binding.py new file mode 100755 index 00000000..9fe3ba0e --- /dev/null +++ b/crews/main/skills/work-channel-binding/scripts/prepare-work-channel-binding.py @@ -0,0 +1,103 @@ +#!/usr/bin/env python3 +import argparse +import json +from pathlib import Path +from typing import Any + + +def redacted_accounts(accounts: list[dict[str, str]]) -> list[dict[str, str]]: + return [ + { + "accountId": account["accountId"], + "name": account.get("name", account["accountId"]), + "appId": account.get("appId", ""), + "appSecret": "***" if account.get("appSecret") else "", + "dmPolicy": account.get("dmPolicy", "open"), + "groupPolicy": account.get("groupPolicy", "open"), + } + for account in accounts + ] + + +def atomic_write_json(path: Path, payload: dict[str, Any]) -> None: + tmp = path.with_name(path.name + ".tmp") + tmp.write_text( + json.dumps(payload, ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + tmp.replace(path) + + +def main() -> None: + parser = argparse.ArgumentParser(description="Prepare a redacted work channel binding plan.") + parser.add_argument("--channel", required=True, choices=["feishu", "wecom"]) + parser.add_argument("--plan-file", required=True) + parser.add_argument("--account-id", action="append", default=[]) + parser.add_argument("--agent-id", action="append", default=[]) + parser.add_argument("--app-id", action="append", default=[]) + parser.add_argument("--app-secret", action="append", default=[]) + parser.add_argument("--account-name", action="append", default=[]) + parser.add_argument("--dm-policy", action="append", default=[]) + parser.add_argument("--group-policy", action="append", default=[]) + args = parser.parse_args() + + expected = len(args.account_id) + for label, values in { + "--agent-id": args.agent_id, + "--app-id": args.app_id, + "--app-secret": args.app_secret, + }.items(): + if len(values) != expected: + raise SystemExit(f"{label} must appear the same number of times as --account-id") + if args.account_name and len(args.account_name) != expected: + raise SystemExit("--account-name must appear the same number of times as --account-id when provided") + if args.dm_policy and len(args.dm_policy) != expected: + raise SystemExit("--dm-policy must appear the same number of times as --account-id when provided") + if args.group_policy and len(args.group_policy) != expected: + raise SystemExit("--group-policy must appear the same number of times as --account-id when provided") + + accounts: list[dict[str, str]] = [] + bindings: list[dict[str, str]] = [] + for index, account_id in enumerate(args.account_id): + name = args.account_name[index] if args.account_name else account_id + dm_policy = args.dm_policy[index] if args.dm_policy else "open" + group_policy = args.group_policy[index] if args.group_policy else "open" + accounts.append( + { + "accountId": account_id, + "name": name, + "appId": args.app_id[index], + "appSecret": args.app_secret[index], + "dmPolicy": dm_policy, + "groupPolicy": group_policy, + } + ) + bindings.append( + {"agentId": args.agent_id[index], "accountId": account_id, "channel": args.channel} + ) + + plan = { + "version": 1, + "channel": args.channel, + "accounts": accounts, + "bindings": bindings, + "requiresGatewayRestart": True, + } + plan_path = Path(args.plan_file).expanduser() + atomic_write_json(plan_path, plan) + print( + json.dumps( + { + "planFile": str(plan_path), + "channel": args.channel, + "accounts": redacted_accounts(accounts), + "bindings": bindings, + }, + ensure_ascii=False, + indent=2, + ) + ) + + +if __name__ == "__main__": + main() diff --git a/crews/main/skills/work-channel-binding/scripts/record-pending-followup.py b/crews/main/skills/work-channel-binding/scripts/record-pending-followup.py new file mode 100755 index 00000000..5eb0b84b --- /dev/null +++ b/crews/main/skills/work-channel-binding/scripts/record-pending-followup.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python3 +import argparse +import json +from datetime import datetime, timedelta, timezone +from pathlib import Path + + +def state_path() -> Path: + return Path.home() / ".openclaw" / "workspace-main" / "pending-followup.json" + + +def atomic_write_json(path: Path, payload: dict) -> None: + tmp = path.with_name(path.name + ".tmp") + tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + tmp.replace(path) + + +def main() -> None: + parser = argparse.ArgumentParser(description="Record a pending Main Agent followup.") + parser.add_argument("--reason", default="gateway-restart") + parser.add_argument("--message", default="Gateway 已重启。请发送一条消息测试新的 channel binding 是否生效。") + args = parser.parse_args() + + now = datetime.now(timezone.utc) + payload = { + "version": 1, + "type": "gateway-restart-followup", + "status": "pending", + "reason": args.reason, + "createdAt": now.isoformat(), + "expiresAt": (now + timedelta(days=1)).isoformat(), + "message": args.message, + } + path = state_path() + path.parent.mkdir(parents=True, exist_ok=True) + atomic_write_json(path, payload) + print(json.dumps({"pendingFollowup": str(path), "status": "pending"}, ensure_ascii=False, indent=2)) + + +if __name__ == "__main__": + main() diff --git a/crews/main/skills/work-channel-binding/scripts/restart-gateway-confirmed.sh b/crews/main/skills/work-channel-binding/scripts/restart-gateway-confirmed.sh new file mode 100755 index 00000000..cfb564dc --- /dev/null +++ b/crews/main/skills/work-channel-binding/scripts/restart-gateway-confirmed.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [ "${WISEFLOW_CONFIRM_GATEWAY_RESTART:-}" != "confirmed" ]; then + echo "Refusing to restart Gateway without WISEFLOW_CONFIRM_GATEWAY_RESTART=confirmed" >&2 + exit 2 +fi + +reason="${1:-manual}" +log_dir="${HOME}/.openclaw/workspace-main" +mkdir -p "$log_dir" +printf '%s\t%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$reason" >> "$log_dir/gateway-restart-audit.log" +exec systemctl --user restart openclaw-gateway diff --git a/crews/shared/COMMAND_TIERS.md b/crews/shared/COMMAND_TIERS.md index 73461bb3..07fb7fc0 100644 --- a/crews/shared/COMMAND_TIERS.md +++ b/crews/shared/COMMAND_TIERS.md @@ -13,6 +13,8 @@ 两层取更严格者生效。`setup-crew.sh` 根据各 Crew 声明的 tier 自动生成上述配置。 +**重要**：OpenClaw `matchAllowlist` 使用 `resolvedRealPath`（即 `readlink -f` 后的真实路径）匹配 allowlist pattern。因此 `exec-approvals.json` 中的条目必须是 **realpath**，不能是 symlink 路径。例如 `/usr/bin/python3` 是 symlink → 必须写入 `/usr/bin/python3.12`。`setup-crew.sh` 已自动通过 `readlink -f` 解析。 + --- ## 层级概览 @@ -43,10 +45,10 @@ 白名单命令（由 setup-crew.sh 自动解析为二进制路径写入 exec-approvals）： ``` -cat, ls, grep, find, ps, date, echo, pwd, env, which, head, tail, wc, sort, uniq, diff, curl +cat, ls, grep, find, xargs, ps, date, echo, pwd, env, which, head, tail, wc, sort, uniq, diff, curl, stat, basename, dirname, realpath, readlink, tr, printf, whoami, uname, du, df, file, ffprobe, fc-list ``` -不在白名单中的命令会被 OpenClaw 自动拒绝。请勿尝试使用 `rm`、`mv`、`cp`、`mkdir`、`chmod` 等修改型命令。 +不在白名单中的命令会被 OpenClaw 自动拒绝。`ffprobe` 仅用于可信本地媒体文件的元数据探测，不用于解析未知来源的大文件或远程 URL。请勿尝试使用 `rm`、`mv`、`cp`、`mkdir`、`chmod` 等修改型命令。 --- @@ -100,5 +102,6 @@ command-tier: T2 | 日期 | 变更 | |------|------| +| 2026-06-03 | v3: 修复 symlink 路径导致 allowlist miss（exec-tiers.sh 改用 readlink -f 解析 realpath） | | 2026-03-13 | v2: 权限从纯提示词改为 exec-approvals + tools.exec 自动强制执行 | | 2026-03-10 | v1: 初始版本，定义 T0-T3 四层权限 | diff --git a/docs/crew-system.md b/docs/crew-system.md index 29615ad1..905e9598 100644 --- a/docs/crew-system.md +++ b/docs/crew-system.md @@ -172,7 +172,7 @@ Crew 实例有三种创建方式： | 脚本 | 用途 | |------|------| | `scripts/setup-crew.sh` | 安装多 Agent 系统（部署内置 Crew、同步模板库、更新配置，幂等） | -| `crews/hrbp/skills/hrbp-common/scripts/sync-team-directory.sh` | 生成 `~/.openclaw/TEAM_DIRECTORY.md`（单一信源，所有 agent 直接读取） | +| `crews/main/skills/crew-list/scripts/sync-team-directory.sh` | 生成 `~/.openclaw/crew_templates/TEAM_DIRECTORY.md`（对内 Crew 通讯录，由 Main Agent 维护） | | `crews/hrbp/skills/hrbp-recruit/scripts/add-agent.sh` | HRBP 内部：注册新实例 | | `crews/hrbp/skills/hrbp-modify/scripts/modify-agent.sh` | HRBP 内部：修改实例渠道绑定 | | `crews/hrbp/skills/hrbp-remove/scripts/remove-agent.sh` | HRBP 内部：移除实例（workspace 归档） | diff --git a/docs/quick_start.md b/docs/quick_start.md index 96981cb6..4b83f7e6 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -1,173 +1,142 @@ # 部署后怎么用（推荐流程） -### 推荐上手三步走 +## 初次安装后的入口 -以下三个场景是最典型的初始配置流程，对话内容可直接照抄。 - ---- - -#### 第一步：通过 Main Agent 招募对内 Crew（以新媒体小编为例） - -> 适用 crew 类型：**internal**（在 Main Agent 的频道中操作） - -**1.1 招募新媒体小编** +wiseflow 默认只保证一个入口即可最小化使用： ```text -你（在 main 频道）： -帮我招募一个新媒体小编，用 selfmedia-operator 模板，ID 就叫 selfmedia-operator +openclaw-weixin -> Main Agent +``` -# Main Agent 会展示招募方案，等你确认 -你：确认 +安装后先完成微信登录和配对： -# Main Agent 完成实例化，提示重启 Gateway +```bash +openclaw channels login --channel openclaw-weixin +openclaw pairing list openclaw-weixin +openclaw pairing approve openclaw-weixin ``` -**1.2 向小编植入业务背景** +然后直接在微信私聊 Main Agent。 -实例化完成、重启 Gateway 后，告诉 Main Agent 向小编注入背景信息（或者等单独绑定小编 channel 后，直接跟小编说）： +> 当前 Weixin channel 支持 direct chats 和 media，不默认承诺微信群能力。 -```text -你： -帮我把以下背景信息注入新媒体小编的工作记忆： -- 公司：<你的公司名称>，做 <主营业务一句话> -- 运营平台：微信公众号 <账号名> + 小红书 -- 账号调性：<风格定位，如”技术圈硬核但不失活泼”> -- 目标读者：<典型受众描述> -- 发布节奏：每周 2 篇，周二和周五 -- 禁忌话题：<不可提及的竞品或话题> - -# Main Agent 会更新 selfmedia-operator 的 MEMORY.md 和 USER.md -``` +## 推荐上手三步走 -**1.3 开始使用** +### 第一步：让 Main Agent 完成 onboard ```text -你（在 main 频道，直接路由）： -@selfmedia-operator 帮我写一篇关于 <选题> 的文章，面向 <目标读者> - -# 或者给新媒体小编绑定独立频道后直接对话 +你（微信私聊 Main Agent）： +我刚完成 wiseflow 安装，帮我完成初始化。我的公司/品牌是 <名称>，主营 <业务>，我希望先解决 <第一个目标>。 ``` ---- +Main Agent 会： -#### 第二步：通过 HRBP 招募对外 Crew（以销售客服为例） +- 介绍 wiseflow team 的使用方式； +- 记录业务/品牌背景； +- 判断是否需要招募对内 crew； +- 在必要时引导配置 Feishu 或 WeCom 工作 channel。 -> 适用 crew 类型：**external**（在 HRBP 的频道中操作） +初始团队状态： -**2.1 告诉 HRBP 你的业务背景和需求** +- Main Agent：微信入口和系统控制面； +- IT Engineer：Main Agent 的系统运维 subagent； +- HRBP：默认未启用，首次需要 external crew 时再启用。 -```text -你（在 hrbp 频道）： -我需要招募一个微信销售客服，基于 sales-cs 模板。 -业务背景如下： -- 公司：<你的公司名称> -- 产品：<核心产品/服务名称>，<一句话说清楚能帮客户解决什么> -- 付费层级：<例如：免费体验版 → VIP会员 → 企业订阅> -- 客服对外称呼：<如”小明助手”> -- 负责人微信：<负责人微信号>（客户复杂问题时升级人工） -- 绑定渠道：飞书，账号 ID -``` +### 第二步：通过 Main Agent 招募对内 Crew -**2.2 HRBP 配置实例并引导你填写业务内容** +例如启用新媒体运营： ```text -# HRBP 会展示实例化方案，等你确认 -你：确认 - -# HRBP 完成实例化，并请你提供以下内容填写到客服手册： -# - 产品 FAQ（常见问题答案） -# - 付费方式和购买链接 -# - 反馈问卷链接 -# - 开票申请工单链接 - 你： -产品常见问题如下： -Q：<问题1>？A：<答案1> -Q：<问题2>？A：<答案2> -购买链接：<链接> -反馈问卷：<链接> -开票工单：<链接> - -# HRBP 把这些内容写入 sales-cs 实例的 MEMORY.md +帮我招募一个新媒体小编，用 selfmedia-operator 模板，ID 就叫 selfmedia-operator。 ``` -**注意：对外 crew 必须单独绑定对外服务 channel，推荐使用代码仓中的 awada extension** +Main Agent 会展示方案，等待确认。确认后完成实例化。 -**2.3 重启 Gateway，销售客服上线** +如果该 crew 有 `BOOTSTRAP.md`，Main Agent 会代为完成首次问询，例如： -```text -你：确认，帮我重启 Gateway +- 运营哪些平台； +- 是否做微信公众号/企微朋友圈； +- 是否需要 IP 白名单或中转模式； +- 品牌资料、目标受众、发布节奏、审核流程。 + +开始使用： -# 或在终端手动执行： -# ./scripts/dev.sh gateway +```text +你： +@selfmedia-operator 帮我写一篇关于 <选题> 的公众号文章，面向 <目标读者>。 ``` ---- +### 第三步：按需配置工作 channel -#### 第三步：通过 IT Engineer 日常运维 +fresh install 不预置 Feishu / WeCom。以下情况 Main Agent 会建议配置工作 channel： -> IT Engineer 是内置的系统级 crew，无需招募，通过 Main Agent 频道路由 +- 对内 crew 数量较多； +- 用户额外招募第二个对内 crew 后团队开始复杂； +- 首次需要 external crew； +- 用户频繁希望直接联系某个 specialist。 -**3.1 系统巡检** +流程： ```text -你（在 main 频道）： -@it-engineer 帮我做一次系统巡检，重点检查： -- 模型/API 配置是否正常 -- 各 crew 的 channel 绑定状态 -- 最近有没有异常日志 +你： +帮我配置工作 channel。 + +Main Agent： +你想用 Feishu 还是 WeCom？ ``` -**3.2 升级系统** +随后 Main Agent 会按教程引导你准备 bot id / secret / account id，写入对应 channel account，并修改 `openclaw.json` 的 binding。Main Agent 不会在摘要中回显 secret。修改后需要你确认是否重启 Gateway。 -```text -你：@it-engineer 帮我把系统升级到最新版本 +## External Crew -# IT Engineer 会执行 ./scripts/install.sh 并报告结果 -``` +对外 crew（客服、销售、社群接待等）不由 Main Agent 直接创建。 + +首次需要 external crew 时： -**3.3 排查故障** +1. Main Agent 提醒需要启用 HRBP； +2. 推荐先配置 Feishu 或 WeCom 工作 channel； +3. HRBP 负责 external crew 生命周期； +4. 对外服务 channel（如 awada）按 external crew 场景单独设计。 + +## IT Engineer 日常运维 + +IT Engineer 无默认 direct channel，通过 Main Agent 调用： ```text 你： -@it-engineer 新媒体小编今天回复说”工具调用失败”，帮我查一下原因 - -# IT Engineer 会检查日志、配置，定位问题并修复 +@it-engineer 帮我做一次系统巡检，重点检查模型/API 配置、channel binding、最近异常日志。 ``` -**3.4 查看团队通讯录** +升级系统： ```text -你：帮我看一下现在团队里有哪些 crew，以及各自的绑定状态 - -# Main Agent 会读取 TEAM_DIRECTORY.md，输出当前团队状态 +你： +@it-engineer 帮我把系统升级到最新版本。 ``` ---- - -#### 3 分钟速查（可直接照抄） +## 3 分钟速查 ```text -# 招募对内 crew（在 main 频道） -你：帮我招募一个新媒体小编，用 selfmedia-operator 模板 +# 初始 onboard +你：我刚完成安装，帮我完成 wiseflow 初始化。 -# 注入业务背景（在 main 频道） -你：帮我把以下背景注入新媒体小编：[业务背景...] +# 招募对内 crew +你：帮我招募一个新媒体小编，用 selfmedia-operator 模板。 -# 招募对外 crew（在 hrbp 频道） -你：我需要招募一个微信销售客服，基于 sales-cs 模板，[业务背景...] +# 使用 IT Engineer +你：@it-engineer 做一次系统巡检。 -# 系统巡检（在 main 频道路由） -你：@it-engineer 做一次系统巡检 +# 配置工作 channel +你：帮我配置工作 channel。 # 查看团队状态 -你：帮我看一下现在有哪些 crew 在运行 +你：帮我看一下现在有哪些 crew 在运行。 ``` # 生产部署 ```bash -# 一键安装为系统服务（自动拉取最新代码 + 构建 + 开机自启 + 崩溃重启） ./scripts/install.sh ``` @@ -179,8 +148,6 @@ Q：<问题2>？A：<答案2> > `install.sh` 是幂等的——重复执行只更新有变化的部分，不会覆盖用户数据。 -> **从自己的 fork 同步**：如果你 fork 了本项目并做了定制，先确保 `origin` 指向你的 fork，`install.sh` 默认从 origin 拉取。 - ## 常用命令 ```bash @@ -188,6 +155,7 @@ Q：<问题2>？A：<答案2> ./scripts/dev.sh gateway --port 18789 # 指定端口 ./scripts/install.sh # 生产部署 / 升级（幂等） ./scripts/install.sh --skip-crew # 仅重装 daemon，跳过 crew 同步 +./scripts/install.sh --skip-weixin # 跳过 openclaw-weixin 插件安装 ./scripts/apply-addons.sh # 重新应用 addons（patches + skills + crew） ./scripts/setup-crew.sh # 重新同步 Agent 系统配置 ./scripts/setup-crew.sh --force # 覆盖已有 workspace @@ -195,21 +163,4 @@ Q：<问题2>？A：<答案2> ## Addon 开发 -详见 **[addon_development.md](./addon_development.md)**（英文），涵盖： - -- OpenClaw 版本锁定机制（`openclaw.version` 文件的读取方式） -- Addon 目录结构和 `addon.json` 规范 -- 四层加载机制（overrides → patches → skills → crew） -- 本地开发与测试流程 -- 发布与上架方式 - -## 文档 - -- [多 crew 系统架构](docs/crew-system.md) - 架构设计和组件说明 -- [快速上手](docs/quick-start.md) - 安装和使用指南 -- [OpenClaw 分析](docs/introduce_to_clawd_by_claude.md) - 上游代码架构分析 -- [Crews v2 设计文档](crews/DESIGN.md) - Template → Instance 机制与完整设计细节 - -## 许可证 - -MIT License +详见 **[addon_development.md](./addon_development.md)**。 diff --git a/docs/workspace-bootstrap-files.md b/docs/workspace-bootstrap-files.md index cb3ef080..9919629e 100644 --- a/docs/workspace-bootstrap-files.md +++ b/docs/workspace-bootstrap-files.md @@ -153,7 +153,7 @@ agent 应在 `AGENTS.md` 中明确记录此约定： | Crew | BUILTIN_SKILLS 关键技能 | DENIED_SKILLS 关键技能 | |------|------------------------|----------------------| -| selfmedia-operator | `summarize`, `wenyan-publisher`, `twitter-post`, `tiktok-post`, `instagram-post`, `youtube-upload`, `siliconflow-img-gen`, `siliconflow-video-gen`, `gifgrep`, `video-frames` | `github`, `gh-issues`, `coding-agent`, `connections-optimizer`, `email-ops`, `pitch-deck`, `social-graph-ranker` | +| selfmedia-operator | `summarize`, `wenyan-publisher`, `twitter-post`, `tiktok-post`, `instagram-post`, `youtube-upload`, `siliconflow-img-gen`, `gifgrep`, `video-frames` | `github`, `gh-issues`, `coding-agent`, `connections-optimizer`, `email-ops`, `pitch-deck`, `social-graph-ranker` | | business-developer | `summarize`, `affiliate-marketing`, `cold-outreach`, `twitter-post`, `instagram-post`, `connections-optimizer`, `email-ops`, `pitch-deck`, `social-graph-ranker` | `github`, `gh-issues`, `coding-agent` | | designer | `siliconflow-img-gen`, `summarize` | `github`, `gh-issues`, `coding-agent`, `connections-optimizer`, `email-ops`, `pitch-deck`, `social-graph-ranker` | diff --git a/openclaw-weixin.version.json b/openclaw-weixin.version.json new file mode 100644 index 00000000..ce5da5e1 --- /dev/null +++ b/openclaw-weixin.version.json @@ -0,0 +1,17 @@ +{ + "openclaw-weixin": { + "package": "@tencent-weixin/openclaw-weixin", + "version": "2.4.3", + "integrity": "sha512-dPQbidUNWigC6V10vGW4i+GLH09x+6zUhafZRjuxkJ9GDu8o62WBsnUTojp4KqUH756hz+t2v9khiCRSi0dBDw==" + }, + "openclaw-weixin-cli": { + "package": "@tencent-weixin/openclaw-weixin-cli", + "version": "2.1.4", + "integrity": "sha512-+hHCsfLqwFSd4pPyB9tp++/agWFrWZeRNj/Zy4FZDd1N7BlYoQA0FOLen/wbv3liM+CVZYGCXgDA5kvpF7prEg==" + }, + "wecom-openclaw-cli": { + "package": "@wecom/wecom-openclaw-cli", + "version": "1.1.0", + "integrity": "sha512-qnD0JXaHtgSsKh0REm5r17Kv/PyqZY+uavBxfLdqeoptfZS08aftJXUtIiFbuASdxGKpEjDxto2fiwf/3yAgew==" + } +} diff --git a/openclaw.version b/openclaw.version index e47ad0a2..933e3264 100644 --- a/openclaw.version +++ b/openclaw.version @@ -6,5 +6,5 @@ # git clone https://github.com/openclaw/openclaw openclaw # git -C openclaw checkout $OPENCLAW_COMMIT # -OPENCLAW_VERSION=2026.5.7 -OPENCLAW_COMMIT=eeef4864494f859838fec1586bedbab1f8fa5702 +OPENCLAW_VERSION=2026.5.28 +OPENCLAW_COMMIT=e93216080aa1f425d3ab127014603eba8e365b2d diff --git a/patches/001-relax-exec-allowlist-shell-syntax.patch b/patches/001-relax-exec-allowlist-shell-syntax.patch new file mode 100644 index 00000000..b7213bb3 --- /dev/null +++ b/patches/001-relax-exec-allowlist-shell-syntax.patch @@ -0,0 +1,164 @@ +diff --git a/src/infra/exec-approvals-analysis.test.ts b/src/infra/exec-approvals-analysis.test.ts +index e823b9400c..327511352d 100644 +--- a/src/infra/exec-approvals-analysis.test.ts ++++ b/src/infra/exec-approvals-analysis.test.ts +@@ -167,11 +167,6 @@ describe("exec approvals shell analysis", () => { + }); + + it.each([ +- { command: 'echo "output: $(whoami)"', reason: "unsupported shell token: $()" }, +- { command: 'echo "output: `id`"', reason: "unsupported shell token: `" }, +- { command: "echo $(whoami)", reason: "unsupported shell token: $()" }, +- { command: "cat < input.txt", reason: "unsupported shell token: <" }, +- { command: "echo ok > output.txt", reason: "unsupported shell token: >" }, + { + command: "/usr/bin/echo first line\n/usr/bin/echo second line", + reason: "unsupported shell token: \n", +@@ -580,8 +575,8 @@ describe("exec approvals shell analysis", () => { + { + allowlist: [{ pattern: "/usr/bin/echo" }], + command: "/usr/bin/echo ok &&", +- expectedAnalysisOk: false, +- expectedAllowlistSatisfied: false, ++ expectedAnalysisOk: true, ++ expectedAllowlistSatisfied: true, + }, + { + allowlist: [{ pattern: "/usr/bin/ping" }], +diff --git a/src/infra/exec-approvals-analysis.ts b/src/infra/exec-approvals-analysis.ts +index 44900f0bb7..fca09df325 100644 +--- a/src/infra/exec-approvals-analysis.ts ++++ b/src/infra/exec-approvals-analysis.ts +@@ -42,7 +42,7 @@ export type ShellChainPart = { + opToNext: ShellChainOperator | null; + }; + +-const DISALLOWED_PIPELINE_TOKENS = new Set([">", "<", "`", "\n", "\r", "(", ")"]); ++const DISALLOWED_PIPELINE_TOKENS = new Set(["\n", "\r"]); + const DOUBLE_QUOTE_ESCAPES = new Set(["\\", '"', "$", "`"]); + const MAX_UNQUOTED_HEREDOC_CONTINUATION_LINES = 1024; + const MAX_UNQUOTED_HEREDOC_LOGICAL_LINE_LENGTH = 64 * 1024; +@@ -296,10 +296,32 @@ function splitShellPipeline(command: string): { ok: boolean; reason?: string; se + continue; + } + if (ch === "$" && next === "(") { +- return { ok: false, reason: "unsupported shell token: $()", segments: [] }; ++ buf += ch; ++ buf += next; ++ i += 1; ++ let depth = 1; ++ while (i + 1 < command.length && depth > 0) { ++ i += 1; ++ const c = command[i]; ++ buf += c; ++ if (c === "(") depth += 1; ++ else if (c === ")") depth -= 1; ++ } ++ emptySegment = false; ++ continue; + } + if (ch === "`") { +- return { ok: false, reason: "unsupported shell token: `", segments: [] }; ++ buf += ch; ++ while (i + 1 < command.length && command[i + 1] !== "`") { ++ i += 1; ++ buf += command[i]; ++ } ++ if (i + 1 < command.length) { ++ i += 1; ++ buf += command[i]; ++ } ++ emptySegment = false; ++ continue; + } + if (ch === "\n" || ch === "\r") { + return { ok: false, reason: "unsupported shell token: newline", segments: [] }; +@@ -337,10 +359,18 @@ function splitShellPipeline(command: string): { ok: boolean; reason?: string; se + } + + if (ch === "|" && next === "|") { +- return { ok: false, reason: "unsupported shell token: ||", segments: [] }; ++ buf += ch; ++ buf += next; ++ i += 1; ++ emptySegment = false; ++ continue; + } + if (ch === "|" && next === "&") { +- return { ok: false, reason: "unsupported shell token: |&", segments: [] }; ++ buf += ch; ++ buf += next; ++ i += 1; ++ emptySegment = false; ++ continue; + } + if (ch === "|") { + emptySegment = true; +@@ -348,7 +378,9 @@ function splitShellPipeline(command: string): { ok: boolean; reason?: string; se + continue; + } + if (ch === "&" || ch === ";") { +- return { ok: false, reason: `unsupported shell token: ${ch}`, segments: [] }; ++ buf += ch; ++ emptySegment = false; ++ continue; + } + if (ch === "<" && next === "<") { + buf += "<<"; +@@ -375,7 +407,32 @@ function splitShellPipeline(command: string): { ok: boolean; reason?: string; se + return { ok: false, reason: `unsupported shell token: ${ch}`, segments: [] }; + } + if (ch === "$" && next === "(") { +- return { ok: false, reason: "unsupported shell token: $()", segments: [] }; ++ buf += ch; ++ buf += next; ++ i += 1; ++ let depth = 1; ++ while (i + 1 < command.length && depth > 0) { ++ i += 1; ++ const c = command[i]; ++ buf += c; ++ if (c === "(") depth += 1; ++ else if (c === ")") depth -= 1; ++ } ++ emptySegment = false; ++ continue; ++ } ++ if (ch === "`") { ++ buf += ch; ++ while (i + 1 < command.length && command[i + 1] !== "`") { ++ i += 1; ++ buf += command[i]; ++ } ++ if (i + 1 < command.length) { ++ i += 1; ++ buf += command[i]; ++ } ++ emptySegment = false; ++ continue; + } + buf += ch; + emptySegment = false; +@@ -774,13 +831,6 @@ export function splitCommandChainWithOperators(command: string): ShellChainPart[ + foundChain = true; + continue; + } +- if (ch === ";") { +- if (!pushPart(";")) { +- invalidChain = true; +- } +- foundChain = true; +- continue; +- } + + buf += ch; + } +@@ -1060,6 +1110,8 @@ export function buildEnforcedShellCommand(params: { + + /** + * Splits a command string by chain operators (&&, ||, ;) while respecting quotes. ++ * Note: semicolons inside compound constructs (while/do/done, if/then/fi, etc.) are ++ * preserved as part of the segment rather than treated as chain separators. + * Returns null when no chain is present or when the chain is malformed. + */ + export function splitCommandChain(command: string): string[] | null { diff --git a/patches/004-chrome-port-grace-retry.patch b/patches/004-chrome-port-grace-retry.patch index 54c235da..047498d1 100644 --- a/patches/004-chrome-port-grace-retry.patch +++ b/patches/004-chrome-port-grace-retry.patch @@ -1,8 +1,8 @@ diff --git a/extensions/browser/src/browser/chrome.ts b/extensions/browser/src/browser/chrome.ts -index b035eb3f37..abfe8d3084 100644 +index 102da48a71..505cba327f 100644 --- a/extensions/browser/src/browser/chrome.ts +++ b/extensions/browser/src/browser/chrome.ts -@@ -395,6 +395,24 @@ export async function isChromeCdpReady( +@@ -422,6 +422,24 @@ export async function isChromeCdpReady( return diagnostic.ok; } @@ -27,10 +27,10 @@ index b035eb3f37..abfe8d3084 100644 export async function launchOpenClawChrome( resolved: ResolvedBrowserConfig, profile: ResolvedBrowserProfile, -@@ -412,7 +430,9 @@ export async function launchOpenClawChrome( - if (missingDisplayError) { - throw new BrowserProfileUnavailableError(missingDisplayError); +@@ -453,7 +471,9 @@ export async function launchOpenClawChrome( + ); } + - await ensurePortAvailable(profile.cdpPort); + // Retry briefly to absorb the race window where a prior Chrome is still releasing the port + // (stop → start sequences from agent or internal profile reconcile). diff --git a/patches/005-browser-timeout-env-var.patch b/patches/005-browser-timeout-env-var.patch index 9094e622..82505648 100644 --- a/patches/005-browser-timeout-env-var.patch +++ b/patches/005-browser-timeout-env-var.patch @@ -1,9 +1,9 @@ diff --git a/extensions/browser/src/browser/act-policy.ts b/extensions/browser/src/browser/act-policy.ts -index 9407858beb..fdf623082a 100644 +index b372d2ff95..81dd1977eb 100644 --- a/extensions/browser/src/browser/act-policy.ts +++ b/extensions/browser/src/browser/act-policy.ts -@@ -4,11 +4,18 @@ export const ACT_MAX_CLICK_DELAY_MS = 5_000; - export const ACT_MAX_WAIT_TIME_MS = 30_000; +@@ -5,11 +5,18 @@ export const ACT_MAX_WAIT_TIME_MS = 30_000; + export const ACT_MAX_VIEWPORT_DIMENSION = 8192; const ACT_MIN_TIMEOUT_MS = 500; -const ACT_MAX_INTERACTION_TIMEOUT_MS = 60_000; @@ -23,7 +23,7 @@ index 9407858beb..fdf623082a 100644 export function normalizeActBoundedNonNegativeMs( value: number | undefined, fieldName: string, -@@ -28,17 +35,19 @@ export function normalizeActBoundedNonNegativeMs( +@@ -29,17 +36,19 @@ export function normalizeActBoundedNonNegativeMs( } export function resolveActInteractionTimeoutMs(timeoutMs?: number): number { @@ -46,10 +46,10 @@ index 9407858beb..fdf623082a 100644 return Math.max(ACT_MIN_TIMEOUT_MS, Math.min(ACT_MAX_WAIT_TIMEOUT_MS, normalized)); } diff --git a/extensions/browser/src/node-host/invoke-browser.ts b/extensions/browser/src/node-host/invoke-browser.ts -index b7f05084c3..a1f848202f 100644 +index e2a9567817..496dd2c249 100644 --- a/extensions/browser/src/node-host/invoke-browser.ts +++ b/extensions/browser/src/node-host/invoke-browser.ts -@@ -39,6 +39,13 @@ const BROWSER_PROXY_MAX_FILE_BYTES = 10 * 1024 * 1024; +@@ -40,6 +40,13 @@ const BROWSER_PROXY_MAX_FILE_BYTES = 10 * 1024 * 1024; const DEFAULT_BROWSER_PROXY_TIMEOUT_MS = 20_000; const BROWSER_PROXY_STATUS_TIMEOUT_MS = 750; @@ -61,9 +61,9 @@ index b7f05084c3..a1f848202f 100644 +} + function normalizeProfileAllowlist(raw?: string[]): string[] { - return Array.isArray(raw) ? raw.map((entry) => entry.trim()).filter(Boolean) : []; + return Array.isArray(raw) ? normalizeStringEntries(raw) : []; } -@@ -134,9 +141,10 @@ function decodeParams(raw?: string | null): T { +@@ -136,9 +143,10 @@ function decodeParams(raw?: string | null): T { } function resolveBrowserProxyTimeout(timeoutMs?: number): number { diff --git a/patches/README.md b/patches/README.md index bfca4f16..d12b5f15 100644 --- a/patches/README.md +++ b/patches/README.md @@ -10,6 +10,7 @@ wiseflow 针对原版 openclaw 提供的非侵入式补丁与依赖覆盖，作 |------|------| | `002-disable-web-search-env-var.patch` | 添加 `OPENCLAW_DISABLE_WEB_SEARCH` 环境变量，可按需禁用内置 web_search | | `003-act-field-validation.patch` | 强化浏览器工具的 act 字段校验，防止幻觉动作 | +| `004-chrome-port-grace-retry.patch` | Chrome 启动前 CDP 端口检查加入 3×500ms 重试，吸收 stop/start 串行场景下的端口释放延迟，避免 PortInUseError | | `005-browser-timeout-env-var.patch` | 添加 `OPENCLAW_BROWSER_TIMEOUT` 环境变量，支持自定义浏览器超时 | > **注**：原 `001-suppress-stale-reply-context.patch` 已于 2026-04-25 移除，awada channel 改用 per-peer inbound debouncer 在入口层合并连发消息，无需 openclaw 核心补丁即可解决历史污染问题。 diff --git a/patches/generate-patch.sh b/patches/generate-patch.sh old mode 100755 new mode 100644 diff --git a/patches/overrides.sh b/patches/overrides.sh old mode 100755 new mode 100644 diff --git a/scripts/apply-addons.sh b/scripts/apply-addons.sh index a9196814..6b8aef20 100755 --- a/scripts/apply-addons.sh +++ b/scripts/apply-addons.sh @@ -474,6 +474,101 @@ else echo "✅ Skill dependencies up to date (hash: ${current_pkg_hash:0:8})" fi +# ─── 安装全仓统一 Python 依赖（pip --user）────────────────────── +# 扫描 skills/、addons/、crews/ 下所有 requirements.txt，合并去重。 +# 内容哈希守卫：仅当依赖集发生变化时才执行 pip install。 +# 优先使用 pip install --user；若不可用则回退 --break-system-packages。 +PIP_HASH_FILE="$OPENCLAW_HOME/.skill-pip-hash" + +merged_pip_deps="$(node -e " + const fs = require('fs'); + const path = require('path'); + const lines = new Set(); + function scan(dir) { + if (!fs.existsSync(dir)) return; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + if (entry.name === 'node_modules' || entry.name === '.git') continue; + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + scan(full); + } else if (entry.name === 'requirements.txt') { + try { + const content = fs.readFileSync(full, 'utf8'); + content.split(/\\r?\\n/).forEach(line => { + const trimmed = line.trim(); + if (trimmed && !trimmed.startsWith('#')) lines.add(trimmed); + }); + } catch {} + } + } + } + scan('$PROJECT_ROOT/skills'); + scan('$ADDONS_DIR'); + scan('$CREWS_DIR'); + console.log(Array.from(lines).sort().join('\\n')); +" 2>/dev/null || echo '')" + +current_pip_hash="$(echo "$merged_pip_deps" | md5sum | cut -d' ' -f1)" +stored_pip_hash="$(cat "$PIP_HASH_FILE" 2>/dev/null || echo '')" + +if [ -n "$merged_pip_deps" ] && { [ "$current_pip_hash" != "$stored_pip_hash" ] || [ ! -f "$PIP_HASH_FILE" ]; }; then + # 查找可用的 pip 命令：pip → pip3 → python3 -m pip + PIP_CMD="" + if command -v pip &>/dev/null; then + PIP_CMD="pip" + elif command -v pip3 &>/dev/null; then + PIP_CMD="pip3" + elif python3 -m pip --version &>/dev/null; then + PIP_CMD="python3 -m pip" + fi + + if [ -z "$PIP_CMD" ]; then + echo " ⚠️ pip not found. Attempting to bootstrap pip via get-pip.py..." >&2 + if curl -fsSL https://mirrors.aliyun.com/pypi/simple/pip/ &>/dev/null; then + curl -fsSL https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py && \ + python3 /tmp/get-pip.py --user -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com && \ + rm -f /tmp/get-pip.py + # 重新检测 + if command -v pip &>/dev/null; then + PIP_CMD="pip" + elif command -v pip3 &>/dev/null; then + PIP_CMD="pip3" + elif python3 -m pip --version &>/dev/null; then + PIP_CMD="python3 -m pip" + fi + fi + fi + + if [ -z "$PIP_CMD" ]; then + echo " ❌ pip not available. Install it with: sudo apt install python3-pip" >&2 + else + echo "🐍 Installing skill Python dependencies ($PIP_CMD --user)..." + # 写入合并后的 requirements 文件 + pip_req_tmp="$OPENCLAW_HOME/.skill-requirements.txt" + echo "$merged_pip_deps" > "$pip_req_tmp" + + pip_install_flags="--user --quiet --no-warn-script-location -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com" + if ! $PIP_CMD install $pip_install_flags -r "$pip_req_tmp" 2>/dev/null; then + echo " ⚠️ pip --user failed, retrying with --break-system-packages..." + pip_install_flags="--break-system-packages --user --quiet --no-warn-script-location -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com" + if ! $PIP_CMD install $pip_install_flags -r "$pip_req_tmp"; then + echo " ❌ pip install failed" >&2 + else + echo "$current_pip_hash" > "$PIP_HASH_FILE" + echo "✅ Python dependencies installed (hash: ${current_pip_hash:0:8})" + fi + else + echo "$current_pip_hash" > "$PIP_HASH_FILE" + echo "✅ Python dependencies installed (hash: ${current_pip_hash:0:8})" + fi + rm -f "$pip_req_tmp" + fi +else + if [ -n "$merged_pip_deps" ]; then + echo "✅ Python dependencies up to date (hash: ${current_pip_hash:0:8})" + fi +fi + # 有 overrides 或 patches 时才需要同步依赖 if [ "$NEEDS_INSTALL" = "true" ]; then echo "📦 Syncing dependencies..." diff --git a/scripts/install.sh b/scripts/install.sh index 2255bad3..67594a0f 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -30,6 +30,7 @@ MACOS_GATEWAY_ENV="$OPENCLAW_HOME/service-env/ai.openclaw.gateway.env" BUILTIN_CREWS="main hrbp it-engineer" FORCE=false SKIP_CREW=false +SKIP_WEIXIN=false while [ $# -gt 0 ]; do case "$1" in @@ -41,11 +42,16 @@ while [ $# -gt 0 ]; do SKIP_CREW=true shift ;; + --skip-weixin) + SKIP_WEIXIN=true + shift + ;; *) echo "❌ Unknown option: $1" - echo "Usage: $0 [--force] [--skip-crew]" - echo " --force Overwrite existing workspace files (including MEMORY.md)" - echo " --skip-crew Skip setup-crew.sh (only sync addons, no workspace updates)" + echo "Usage: $0 [--force] [--skip-crew] [--skip-weixin]" + echo " --force Overwrite existing workspace files (including MEMORY.md)" + echo " --skip-crew Skip setup-crew.sh (only sync addons, no workspace updates)" + echo " --skip-weixin Skip bundled/online openclaw-weixin plugin installation" exit 1 ;; esac @@ -91,6 +97,110 @@ ensure_openclaw_config() { fi } +install_weixin_channel() { + if [ "$SKIP_WEIXIN" = "true" ] || [ "${WISEFLOW_SKIP_WEIXIN_INSTALL:-}" = "true" ]; then + echo "⏭️ Skipping openclaw-weixin plugin installation" + return 0 + fi + + echo "💬 Ensuring WeChat channel plugin (openclaw-weixin)..." + local pin_file="$PROJECT_ROOT/openclaw-weixin.version.json" + local plugin_pkg="@tencent-weixin/openclaw-weixin" + local cli_pkg="@tencent-weixin/openclaw-weixin-cli" + local plugin_version="" + local cli_version="" + local plugin_integrity="" + local vendor_dir="$PROJECT_ROOT/vendor/openclaw-plugins" + local plugin_tgz="" + + if [ -f "$pin_file" ]; then + pin_values="$(node -e ' + const fs = require("fs"); + const p = process.argv[1]; + const c = JSON.parse(fs.readFileSync(p, "utf8")); + const plugin = c["openclaw-weixin"] || {}; + const cli = c["openclaw-weixin-cli"] || {}; + const validPackage = /^@[a-z0-9._-]+\/[a-z0-9._-]+$/; + const validVersion = /^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9._-]+)?$/; + const validIntegrity = /^sha512-[A-Za-z0-9+/]+={0,2}$/; + for (const [label, entry] of [["plugin", plugin], ["cli", cli]]) { + if (!validPackage.test(entry.package || "")) throw new Error(`${label}.package invalid`); + if (!validVersion.test(entry.version || "")) throw new Error(`${label}.version invalid`); + if (!validIntegrity.test(entry.integrity || "")) throw new Error(`${label}.integrity invalid`); + } + console.log([plugin.package, plugin.version, plugin.integrity, cli.package, cli.version].join("\t")); + ' "$pin_file")" || { echo "❌ Invalid openclaw-weixin.version.json"; exit 1; } + IFS=$'\t' read -r plugin_pkg plugin_version plugin_integrity cli_pkg cli_version <<< "$pin_values" + fi + + if [ -n "$plugin_version" ] && [ -d "$vendor_dir" ]; then + plugin_tgz="$(find "$vendor_dir" -maxdepth 1 -type f \( -name "openclaw-weixin-${plugin_version}.tgz" -o -name "tencent-weixin-openclaw-weixin-${plugin_version}.tgz" \) -print -quit 2>/dev/null || true)" + fi + + if [ -n "$plugin_tgz" ]; then + if [ -n "$plugin_integrity" ]; then + node -e ' + const fs = require("fs"); + const crypto = require("crypto"); + const file = process.argv[1]; + const expected = process.argv[2]; + const actual = "sha512-" + crypto.createHash("sha512").update(fs.readFileSync(file)).digest("base64"); + if (actual !== expected) { + console.error(`integrity mismatch for ${file}`); + process.exit(1); + } + ' "$plugin_tgz" "$plugin_integrity" + fi + if (cd "$OPENCLAW_DIR" && pnpm openclaw plugins install "$plugin_tgz"); then + echo " ✅ bundled openclaw-weixin installed" + else + echo "❌ Bundled openclaw-weixin install failed" + echo " Re-run with --skip-weixin only if you intentionally want to configure the onboarding channel later." + exit 1 + fi + elif [ -n "$cli_version" ]; then + # weixin-cli 内部调用 `openclaw` 命令，需要确保它在 PATH 上 + # 创建临时 wrapper 指向本机 openclaw（pnpm openclaw = node scripts/run-node.mjs） + _openclaw_wrapper_dir="$(mktemp -d)" + cat > "$_openclaw_wrapper_dir/openclaw" < binding?.agentId === "main" && binding?.match?.channel === "openclaw-weixin"); + if (!hasMainWeixin) { + c.bindings.push({ agentId: "main", comment: "openclaw-weixin -> Main Agent onboarding entry", match: { channel: "openclaw-weixin" } }); + } + fs.writeFileSync(p, JSON.stringify(c, null, 2) + "\n"); + ' "$OPENCLAW_CONFIG_PATH" + + echo " ℹ️ After Gateway starts, login with: openclaw channels login --channel openclaw-weixin" + echo " ℹ️ Then approve the sender with: openclaw pairing list openclaw-weixin && openclaw pairing approve openclaw-weixin " +} + # ─── 2. 配置 git remote ──────────────────────────────────────── if [ ! -d "$PROJECT_ROOT/.git" ]; then echo "📦 Initializing git repository..." @@ -331,26 +441,45 @@ if [ "$(uname -s)" = "Linux" ]; then fi fi +# ─── 8.5 Linux: 提前创建 systemd drop-in 引用 daemon.env ───── +# 必须在 daemon install 之前，否则 gateway 首次启动时读不到 API keys， +# 连续失败 5 次后触发 StartLimitBurst，后续 restart 也无效 +if [ "$(uname -s)" = "Linux" ] && command -v systemctl >/dev/null 2>&1; then + if systemctl --user show-environment >/dev/null 2>&1; then + _SERVICE_NAME="openclaw-gateway" + _user_systemd_dir="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user" + _dropin_dir="${_user_systemd_dir}/${_SERVICE_NAME}.service.d" + mkdir -p "$_dropin_dir" + cat > "${_dropin_dir}/10-env-file.conf" </dev/null || true pnpm openclaw daemon install +# daemon install 创建了 service 文件，此时 reload 让 drop-in 生效 +if [ "$(uname -s)" = "Linux" ] && command -v systemctl >/dev/null 2>&1; then + systemctl --user daemon-reload 2>/dev/null || true +fi + +# ─── 9.5 安装微信渠道插件（需要 openclaw CLI 已就绪）──────── +install_weixin_channel +echo "" + # ─── 10. 平台特定的 post-install ───────────────────────── if [ "$(uname -s)" = "Linux" ] && command -v systemctl >/dev/null 2>&1; then - # --- systemd drop-in 引用 daemon.env --- + # drop-in 已在 8.5 创建，此处只需 reset + restart if systemctl --user show-environment >/dev/null 2>&1; then - SERVICE_NAME="openclaw-gateway" - user_systemd_dir="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user" - dropin_dir="${user_systemd_dir}/${SERVICE_NAME}.service.d" - mkdir -p "$dropin_dir" - cat > "${dropin_dir}/10-env-file.conf" </dev/null || true + systemctl --user restart "openclaw-gateway.service" + echo "✅ Restarted gateway with daemon.env" fi elif [ "$(uname -s)" = "Darwin" ]; then # --- 追加 env 到 launchd gateway.env（在 daemon install 之后）--- diff --git a/scripts/lib/agent-skills.sh b/scripts/lib/agent-skills.sh index 919916ce..07c0ae2d 100644 --- a/scripts/lib/agent-skills.sh +++ b/scripts/lib/agent-skills.sh @@ -333,10 +333,26 @@ const fs = require("fs"); const src = fs.readFileSync(process.env.SKILL_MD_PATH, "utf8"); const fmMatch = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); if (!fmMatch) process.exit(0); -const binsMatch = fmMatch[1].match(/"bins"\s*:\s*\[([^\]]*)\]/); -if (!binsMatch) process.exit(0); -const tokens = binsMatch[1].match(/"([^"]+)"/g) || []; -for (const t of tokens) console.log("+" + t.slice(1, -1)); +const fm = fmMatch[1]; +// Extract bins from requires.bins — support both JSON and YAML styles: +// JSON: "bins": ["python3", "node"] +// YAML: bins:\n - python3\n - node +const bins = []; +// JSON style: "bins": [...] +const jsonMatch = fm.match(/"bins"\s*:\s*\[([^\]]*)\]/); +if (jsonMatch) { + const tokens = jsonMatch[1].match(/"([^"]+)"/g) || []; + for (const t of tokens) bins.push(t.slice(1, -1)); +} +// YAML style: bins:\n - name (only if JSON style did not match) +if (bins.length === 0) { + const yamlMatch = fm.match(/bins:\s*\n((?:\s+-\s+\S+\s*\n?)+)/); + if (yamlMatch) { + const items = yamlMatch[1].match(/-\s+(\S+)/g) || []; + for (const item of items) bins.push(item.replace(/-\s+/, "")); + } +} +for (const b of bins) console.log("+" + b); ' 2>/dev/null fi @@ -346,11 +362,14 @@ for (const t of tokens) console.log("+" + t.slice(1, -1)); while IFS= read -r -d '' f; do local fname fname="$(basename "$f")" - # 只允许 .sh/.mjs/.ts/.js 文件或有可执行位的文件（排除 .py .json .txt 等） + # 跳过需解释器调用的文件：.py/.mjs/.ts/.js 必须通过 python3/node 调用， + # 不能直接 exec，加入 ALLOWED_COMMANDS 无意义。 + # 解释器由 SKILL.md 的 requires.bins 声明注入。 case "$fname" in - *.py|*.json|*.txt|*.md|*.yaml|*.yml) continue ;; + *.py|*.mjs|*.ts|*.js|*.json|*.txt|*.md|*.yaml|*.yml) continue ;; esac - [ -x "$f" ] || [[ "$fname" == *.sh ]] || [[ "$fname" == *.mjs ]] || [[ "$fname" == *.ts ]] || [[ "$fname" == *.js ]] || continue + # 只有可执行位的脚本才直接加入 allowlist + [ -x "$f" ] || continue # 保留相对于 scripts/ 的子目录路径（支持 platforms/、vendor/ 等子目录） local relpath="${f#$ws_scripts_dir/}" printf '+./skills/%s/scripts/%s\n' "$skill" "$relpath" @@ -364,9 +383,10 @@ for (const t of tokens) console.log("+" + t.slice(1, -1)); local fname fname="$(basename "$f")" case "$fname" in - *.py|*.json|*.txt|*.md|*.yaml|*.yml) continue ;; + *.py|*.mjs|*.ts|*.js|*.json|*.txt|*.md|*.yaml|*.yml) continue ;; esac - [ -x "$f" ] || [[ "$fname" == *.sh ]] || [[ "$fname" == *.mjs ]] || [[ "$fname" == *.ts ]] || [[ "$fname" == *.js ]] || continue + # 同上：只有可执行位的脚本才直接加入 allowlist + [ -x "$f" ] || continue printf '+%s\n' "$f" done < <(find "$global_scripts_dir" -type f -print0 2>/dev/null) fi @@ -447,7 +467,7 @@ inject_feishu_media_guide() { ## 发送图片/文件/视频等富媒体（自动注入） -向用户发送图片、文件、视频或其他富媒体内容时，不要在本地打开媒体文件，**必须将文件本体通过对话所在的 channel 直接发送到聊天中**，且不得直接输出文件路径或 base64 内容作为回复。 +向用户发送图片、文件、视频或其他富媒体内容时，不要在本地打开媒体文件，也不得直接输出文件路径或 base64 内容作为回复。**必须将文件本体通过媒体发送插件直接发送到聊天中，且需要提供绝对路径**。 GUIDE } @@ -459,32 +479,35 @@ inject_exec_guide() { ## exec 命令规范 -exec allowlist 不支持 shell 重定向符（`>`、`<`、`2>`、`&>`），使用时会导致整条命令被 deny，即使其中每个命令都已在白名单中。 +exec allowlist 会解析管道、`&&`、`||`、`;` 和常见重定向，并逐段检查实际执行的命令是否都在白名单中。 -**避免**： -``` +**允许的常见写法**： +```bash ls -la /tmp/file.txt 2>/dev/null && echo "EXISTS" || echo "NOT" some-cmd > /tmp/out.txt +echo a; echo b +cat file.txt | grep keyword ``` -**改用**： -```bash -# 判断文件是否存在 -[ -f /tmp/file.txt ] && echo "EXISTS" || echo "NOT" -test -f /tmp/file.txt && echo "EXISTS" || echo "NOT" -``` +注意：重定向只支持 POSIX 风格写法（如 `> file`、`2> err.log`、`2>&1`）。不要使用 bash/zsh 专属的 `&>` / `&>>`，这类写法在 `/bin/sh` 下可能被解释为后台执行。重定向只改变当前已批准命令的 stdin/stdout/stderr；命令本身仍必须在 allowlist 中。`echo ok; rm file` 只有在 `echo` 和 `rm` 都被允许时才会通过。 + +**仍然禁止使用隐式执行子命令的 shell 扩展：** -如果确实需要重定向，请改用 `bash -c "..."` 方式，并确保 `bash` 已在 exec allowlist 中（T2 及以上 tier 默认包含）。 +- ❌ `echo $(whoami)` — 命令替换会额外执行子命令 +- ❌ ``echo `id` `` — 反引号命令替换会额外执行子命令 +- ❌ `cat <(id)` / `tee >(cmd)` — process substitution 会额外执行子命令 +- ❌ `cmd & other-cmd` — 后台执行不受控 **以下写法同样会导致 allowlist miss，禁止使用：** -- ❌ `cd /abs/path && bash ./skills/xxx/scripts/yyy.sh` — CWD 已经是 workspace，不需要 `cd` 前缀，`cd` 不在 allowlist 中 +- ❌ `cd /abs/path && ./skills/xxx/scripts/yyy.sh` — CWD 已经是 workspace，不需要 `cd` 前缀，`cd` 不在 allowlist 中 +- ❌ `bash ./skills/xxx/scripts/yyy.sh` — setup-crew 已为脚本赋权，不需要 `bash` 前缀；`bash` 会改变命令前缀导致 allowlist miss - ❌ `KEY=value python3 script.py` — 内联 env 赋值会改变命令前缀导致 allowlist miss；环境变量由系统注入 - ❌ `mkdir -p {notes,images}` — exec 不会展开花括号（brace expansion），会直接创建一个名为 `{notes,images}` 的单个文件夹，而非 `notes` 和 `images` 两个文件夹 **正确写法：** -- ✅ `bash ./skills/xxx/scripts/yyy.sh`（直接相对路径调用） +- ✅ `./skills/xxx/scripts/yyy.sh`（直接相对路径调用，setup-crew 已赋权） - ✅ `python3 /abs/path/to/script.py`（无 env 前缀） - ✅ `mkdir -p notes images`（逐一直写目录名，不用花括号展开） GUIDE diff --git a/scripts/lib/exec-tiers.sh b/scripts/lib/exec-tiers.sh index 081c13aa..ac36dde5 100644 --- a/scripts/lib/exec-tiers.sh +++ b/scripts/lib/exec-tiers.sh @@ -9,11 +9,11 @@ # ── 各 Tier 基线命令 ────────────────────────────────── # T0: 无命令（deny） # T1: 只读型系统命令 -TIER_T1_COMMANDS="cat ls grep find ps date echo pwd env which head tail wc sort uniq diff curl stat basename dirname realpath readlink tr printf whoami uname du df file" +TIER_T1_COMMANDS="cat ls grep find xargs ps date echo pwd env which head tail wc sort uniq diff curl stat basename dirname realpath readlink tr printf whoami uname du df file ffprobe fc-list fc-match sed true false" # T2: T1 + 开发工具链 # 注意：bash/sh 的全部常见路径均需列出（/bin 和 /usr/bin 在部分系统上是独立路径， # exec 白名单做精确路径匹配，仅靠 command -v 只能解析到其中一条，须全量覆盖） -TIER_T2_EXTRA="git npm pnpm bun node python python3 pip pip3 cp mv mkdir rmdir rm touch chmod sleep /bin/bash /bin/sh /usr/bin/bash /usr/bin/sh" +TIER_T2_EXTRA="git npm npx pnpm bun node python python3 pip pip3 ffmpeg perl cp mv mkdir rmdir rm touch chmod sleep test /bin/bash /bin/sh /usr/bin/bash /usr/bin/sh" # T3: full access（无需白名单） # ── 从 SOUL.md 解析 command-tier ────────────────────── @@ -121,24 +121,44 @@ resolve_binary_path() { [ -n "$abs" ] && echo "$abs" return ;; - /*) echo "$cmd"; return ;; + /*) + # OpenClaw matchAllowlist 用 resolvedRealPath（readlink -f）匹配 pattern， + # 因此 allowlist 条目必须用 realpath 而非 symlink 路径， + # 否则 /usr/bin/python3 → /usr/bin/python3.12 的 symlink 会导致 allowlist miss。 + local real + real="$(readlink -f "$cmd" 2>/dev/null || true)" + echo "${real:-$cmd}" + return + ;; esac # command -v 可能返回 shell builtin 名（无 /），此时尝试 which 或常见路径 local resolved resolved="$(command -v "$cmd" 2>/dev/null || true)" case "$resolved" in - /*) echo "$resolved"; return ;; + /*) + local real + real="$(readlink -f "$resolved" 2>/dev/null || true)" + echo "${real:-$resolved}" + return + ;; esac # 尝试 which（跳过 builtins） resolved="$(which "$cmd" 2>/dev/null || true)" case "$resolved" in - /*) echo "$resolved"; return ;; + /*) + local real + real="$(readlink -f "$resolved" 2>/dev/null || true)" + echo "${real:-$resolved}" + return + ;; esac # 兜底：检查常见系统目录 local dir for dir in /usr/bin /bin /usr/local/bin; do if [ -x "$dir/$cmd" ]; then - echo "$dir/$cmd" + local real + real="$(readlink -f "$dir/$cmd" 2>/dev/null || true)" + echo "${real:-$dir/$cmd}" return fi done diff --git a/scripts/setup-crew.sh b/scripts/setup-crew.sh index 65b001c6..5a66d1de 100755 --- a/scripts/setup-crew.sh +++ b/scripts/setup-crew.sh @@ -15,7 +15,6 @@ FORCE=false # 内置 Crew 列表（全局唯一，不可删除，不可多实例） # 这些都是对内 Crew（crew-type: internal） BUILTIN_CREWS="main hrbp it-engineer" -SYNC_TEAM_DIRECTORY_SCRIPT="$CREWS_DIR/hrbp/skills/hrbp-common/scripts/sync-team-directory.sh" source "$SCRIPT_DIR/lib/agent-skills.sh" source "$SCRIPT_DIR/lib/exec-tiers.sh" @@ -391,10 +390,8 @@ if [ -f "$CONFIG_PATH" ]; then " && echo " ✅ Agent workspace paths normalized" MAIN_OVERRIDE="$(resolve_denied_override_for_agent "main")" - HRBP_OVERRIDE="$(resolve_denied_override_for_agent "hrbp")" IT_OVERRIDE="$(resolve_denied_override_for_agent "it-engineer")" MAIN_BUILTIN_FILE="$(resolve_builtin_file_for_agent "main" "$OPENCLAW_HOME/workspace-main")" - HRBP_BUILTIN_FILE="$(resolve_builtin_file_for_agent "hrbp" "$OPENCLAW_HOME/workspace-hrbp")" IT_BUILTIN_FILE="$(resolve_builtin_file_for_agent "it-engineer" "$OPENCLAW_HOME/workspace-it-engineer")" MAIN_SKILLS_RESULT="$(resolve_agent_skills_json \ @@ -406,15 +403,6 @@ if [ -f "$CONFIG_PATH" ]; then "$OPENCLAW_HOME/workspace-main/DENIED_SKILLS" \ "$PROJECT_ROOT" \ "$OPENCLAW_HOME")" - HRBP_SKILLS_RESULT="$(resolve_agent_skills_json \ - "hrbp" \ - "$OPENCLAW_HOME/workspace-hrbp" \ - "" \ - "$HRBP_BUILTIN_FILE" \ - "$HRBP_OVERRIDE" \ - "$OPENCLAW_HOME/workspace-hrbp/DENIED_SKILLS" \ - "$PROJECT_ROOT" \ - "$OPENCLAW_HOME")" IT_SKILLS_RESULT="$(resolve_agent_skills_json \ "it-engineer" \ "$OPENCLAW_HOME/workspace-it-engineer" \ @@ -425,7 +413,7 @@ if [ -f "$CONFIG_PATH" ]; then "$PROJECT_ROOT" \ "$OPENCLAW_HOME")" - MAIN_SKILLS_RESULT="$MAIN_SKILLS_RESULT" HRBP_SKILLS_RESULT="$HRBP_SKILLS_RESULT" IT_SKILLS_RESULT="$IT_SKILLS_RESULT" OPENCLAW_HOME="$OPENCLAW_HOME" node -e " + MAIN_SKILLS_RESULT="$MAIN_SKILLS_RESULT" IT_SKILLS_RESULT="$IT_SKILLS_RESULT" OPENCLAW_HOME="$OPENCLAW_HOME" node -e " const fs = require('fs'); const path = require('path'); const c = JSON.parse(fs.readFileSync('$CONFIG_PATH', 'utf8')); @@ -489,23 +477,6 @@ if [ -f "$CONFIG_PATH" ]; then return applySkills(base, process.env.MAIN_SKILLS_RESULT); }); - upsertAgent('hrbp', (prev) => { - // hrbp 可 spawn it-engineer 协助执行运维类任务 - const base = { - ...prev, - id: 'hrbp', - name: prev.name || 'HRBP', - workspace: prev.workspace || openclawHome + '/workspace-hrbp', - thinkingDefault: 'high', - reasoningDefault: 'off', - subagents: { - ...(prev.subagents || {}), - allowAgents: ['it-engineer'], - }, - }; - return applySkills(base, process.env.HRBP_SKILLS_RESULT); - }); - upsertAgent('it-engineer', (prev) => { const base = { ...prev, @@ -539,13 +510,29 @@ if [ -f "$CONFIG_PATH" ]; then } } - // 配置飞书多账户 -> Agent 绑定（模式 B：渠道直连） - if (!Array.isArray(c.bindings) || c.bindings.length === 0) { - c.bindings = [ - { agentId: 'main', comment: 'main-bot -> Main Agent', match: { channel: 'feishu', accountId: 'main-bot' } }, - { agentId: 'hrbp', comment: 'hrbp-bot -> HRBP Agent', match: { channel: 'feishu', accountId: 'hrbp-bot' } }, - { agentId: 'it-engineer', comment: 'it-engineer-bot -> IT Engineer Agent', match: { channel: 'feishu', accountId: 'it-engineer-bot' } } - ]; + // 为所有 Agent 追加自身 ID 到 allowAgents，确保显式 self-spawn 合法 + // （隐式 self-spawn 不传 agentId 时本就放行，但 agent 常显式传入自身 ID， + // 此时必须通过 allowlist 检查，否则会被拒绝） + for (const agent of c.agents.list) { + if (!agent.id) continue; + const prevAllow = Array.isArray(agent.subagents?.allowAgents) ? agent.subagents.allowAgents : []; + if (!prevAllow.includes(agent.id)) { + agent.subagents = { + ...(agent.subagents || {}), + allowAgents: [...new Set([...prevAllow, agent.id])], + }; + } + } + + // 默认确保微信 onboarding 入口存在；工作 channel 由 main agent 后续引导绑定。 + if (!Array.isArray(c.bindings)) c.bindings = []; + const hasMainWeixin = c.bindings.some((binding) => + binding?.agentId === 'main' && binding?.match?.channel === 'openclaw-weixin' + ); + if (!hasMainWeixin) { + c.bindings.push( + { agentId: 'main', comment: 'openclaw-weixin -> Main Agent onboarding entry', match: { channel: 'openclaw-weixin' } } + ); } fs.writeFileSync('$CONFIG_PATH', JSON.stringify(c, null, 2) + '\\n'); @@ -623,10 +610,20 @@ if [ -f "$CONFIG_PATH" ]; then if [ ! -f "$local_ac" ]; then printf '# Auto-generated by setup-crew.sh — skill script allowlist\n' > "$local_ac" fi - if ! grep -qxF "$entry" "$local_ac" 2>/dev/null; then - printf '%s\n' "$entry" >> "$local_ac" - added_count=$((added_count + 1)) + # 确保文件以换行符结尾，避免追加时与末行拼接 + if [ -s "$local_ac" ] && [ "$(tail -c 1 "$local_ac" 2>/dev/null)" != $'\n' ]; then + printf '\n' >> "$local_ac" fi + # 幂等追加：已有 +entry 则跳过；若有同名 -entry 否决条目也跳过 + entry_cmd="${entry#+}" + if grep -qxF "$entry" "$local_ac" 2>/dev/null; then + continue + fi + if grep -qxF "-${entry_cmd}" "$local_ac" 2>/dev/null; then + continue + fi + printf '%s\n' "$entry" >> "$local_ac" + added_count=$((added_count + 1)) done <<< "$script_entries" [ "$added_count" -gt 0 ] && echo " ✅ $a_id: +${added_count} script entries injected" @@ -695,6 +692,26 @@ if [ -f "$CONFIG_PATH" ]; then } " 2>/dev/null) echo " ✅ Standard AGENTS.md sections synced to all deployed workspaces" + + # ─── 4f. 确保所有 skill 脚本有执行权限 ────────────────────────── + while IFS=$'\t' read -r a_id a_ws; do + [ -n "$a_id" ] || continue + [ -d "$a_ws/skills" ] || continue + chmod_count="$(find "$a_ws/skills" -name '*.sh' -not -executable -exec chmod +x {} + -print | wc -l)" + [ "$chmod_count" -gt 0 ] && echo " ✅ $a_id: chmod +x on $chmod_count scripts" + done < <(node -e " + const fs = require('fs'); + const home = process.env.HOME || ''; + const c = JSON.parse(fs.readFileSync('$CONFIG_PATH', 'utf8')); + for (const a of (c.agents?.list || [])) { + if (!a?.id) continue; + const ws = (typeof a.workspace === 'string' && a.workspace.trim() + ? a.workspace.trim() : ('~/.openclaw/workspace-' + a.id)) + .replace(/^~(?=\/|\$)/, home); + console.log(a.id + '\t' + ws); + } + " 2>/dev/null) + echo " ✅ Skill scripts ensured executable" else echo " ⚠️ openclaw.json not found at $CONFIG_PATH" echo " Will be created on first start (dev.sh / reinstall-daemon.sh)" @@ -783,6 +800,7 @@ ENVEOF fi } +generate_ofb_env_md "$OPENCLAW_HOME/workspace-main" "main" generate_ofb_env_md "$OPENCLAW_HOME/workspace-it-engineer" "it-engineer" generate_ofb_env_md "$OPENCLAW_HOME/workspace-hrbp" "hrbp" @@ -793,6 +811,7 @@ if [ "$(uname -s)" = "Darwin" ]; then else _OFB_ENV_FILE="$HOME/.openclaw/daemon.env" fi +inject_env_file_guide "$OPENCLAW_HOME/workspace-main/TOOLS.md" "$_OFB_ENV_FILE" inject_env_file_guide "$OPENCLAW_HOME/workspace-it-engineer/TOOLS.md" "$_OFB_ENV_FILE" inject_env_file_guide "$OPENCLAW_HOME/workspace-hrbp/TOOLS.md" "$_OFB_ENV_FILE" @@ -806,6 +825,7 @@ copy_project_readme() { fi } +copy_project_readme "$OPENCLAW_HOME/workspace-main" "main" copy_project_readme "$OPENCLAW_HOME/workspace-it-engineer" "it-engineer" copy_project_readme "$OPENCLAW_HOME/workspace-hrbp" "hrbp" @@ -819,8 +839,4 @@ echo " Internal templates: $OPENCLAW_HOME/crew_templates/" echo " External templates: $OPENCLAW_HOME/hrbp_templates/" echo " Config: $CONFIG_PATH" -if [ -f "$SYNC_TEAM_DIRECTORY_SCRIPT" ]; then - bash "$SYNC_TEAM_DIRECTORY_SCRIPT" >/dev/null 2>&1 || { - echo " ⚠️ Failed to sync TEAM_DIRECTORY.md" - } -fi +# TEAM_DIRECTORY.md 由 main agent 自行管理，不再由 setup-crew.sh 生成 diff --git a/skills/browser-guide/SKILL.md b/skills/browser-guide/SKILL.md index 72081eea..1d2d53f2 100644 --- a/skills/browser-guide/SKILL.md +++ b/skills/browser-guide/SKILL.md @@ -1,14 +1,10 @@ --- name: browser-guide -description: Best practices for using the managed browser — handling login walls, CAPTCHAs, lazy-loaded content, paywalls, and tab cleanup. +description: Best practices for using the managed browser — handling login walls, + CAPTCHAs, lazy-loaded content, paywalls, and tab cleanup. metadata: - { - "openclaw": - { - "emoji": "🌐", - "always": true, - } - } + openclaw: + emoji: 🌐 --- # Browser Best Practices @@ -95,7 +91,43 @@ When a page uses lazy loading (infinite scroll, "load more" sections, content th 4. Do NOT scroll too fast, do it as a human would. After 7 times of scrolling, you should stop this turn. 5. If not relevant, skip scrolling and work with what is already loaded. -## 5. Paywall / Subscription Walls +## 5. Browser `evaluate` Action — Expression Only + +When using the browser tool's `evaluate` (or `act` with `kind: "evaluate"`) to run JavaScript in the page context, the `fn` parameter must be a **single expression**, not a statement block. Declarations (`const`, `let`, `var`), semicolons, `for`/`if` statements, and `function` declarations will all cause `Invalid evaluate function` errors. + +**Wrong** (statement block — will fail): +```js +const items = document.querySelectorAll('.msg'); +let found = false; +for (const item of items) { + if (item.textContent.includes('target')) { found = true; break; } +} +found ? 'ok' : 'no'; +``` + +**Correct** (wrap in IIFE): +```js +(function() { + var items = document.querySelectorAll('.msg'); + for (var i = 0; i < items.length; i++) { + if (items[i].textContent.indexOf('target') > -1) { return items[i].innerText; } + } + return 'not found'; +})() +``` + +**Correct** (pure expression, for simple lookups): +```js +document.querySelector('.reply-btn') ? 'found' : 'not found' +``` + +Rules: +- Always wrap multi-step logic in an IIFE: `(function(){ ... })()` +- For DOM queries that only need to click, prefer `click` action on a selector over `evaluate` +- For reading text, prefer `snapshot` over `evaluate` when possible +- Never use `const`/`let`/`var` declarations or `;` at the top level of `fn` + +## 6. Paywall / Subscription Walls When a page indicates that content is behind a paywall or requires a specific subscription (e.g., "Subscribe to continue reading", "Continue reading with a WSJ subscription", premium-only banners): diff --git a/skills/complex-task/SKILL.md b/skills/complex-task/SKILL.md index c2c1fc9f..72992cdc 100644 --- a/skills/complex-task/SKILL.md +++ b/skills/complex-task/SKILL.md @@ -1,13 +1,10 @@ --- name: complex-task -description: 长程/复杂任务编排工作指导。接收复杂任务后，依次完成验收标准确认、计划拆分与自审、项目文件初始化、子任务文档创建、执行者-评估者 subagent 并行迭代、主 agent 巡检协调、聚合与整体评估，直至满足验收标准后交付。 +description: 长程/复杂任务编排工作指导。接收复杂任务后，依次完成验收标准确认、计划拆分与自审、项目文件初始化、子任务文档创建、执行者-评估者 subagent + 并行迭代、主 agent 巡检协调、聚合与整体评估，直至满足验收标准后交付。 metadata: - { - "openclaw": - { - "emoji": "🗂️", - } - } + openclaw: + emoji: 🗂️ --- # Complex Task — 复杂任务执行指导 diff --git a/skills/smart-search/SKILL.md b/skills/smart-search/SKILL.md index 2845e35c..c722c3ee 100644 --- a/skills/smart-search/SKILL.md +++ b/skills/smart-search/SKILL.md @@ -1,14 +1,11 @@ --- name: smart-search -description: Construct optimized search URLs for major platforms and navigate to results with the browser. Replaces the built-in web_search tool for targeted, platform-specific searches. +description: Construct optimized search URLs for major platforms and navigate to results + with the browser. Replaces the built-in web_search tool for targeted, platform-specific + searches. metadata: - { - "openclaw": - { - "emoji": "🔍", - "always": true, - } - } + openclaw: + emoji: 🔍 --- # Smart Search Guide @@ -410,6 +407,32 @@ Multi-keyword: join with `%20` - Clicking the "Next page" button on the page. 5. Close the tab immediately after extracting all needed information. +## 浏览器操作最佳实践 + +### 超时错误处理 + +遇到 `browser failed: timed out` 或类似超时错误时： + +- **不需要重启浏览器**，也不执行 `browser stop/start` +- 等待 **30 秒**后在原页面继续操作 +- 若仍无法操作，再等 30 秒 +- 只有关闭浏览器后重开仍报错才是真正出错，需停止并反馈用户 + +### 页面加载等待 + +导航到搜索结果页后： + +- 等待 **3-5 秒**让页面完全加载，再执行 snapshot +- 对于重度客户端渲染的站点（Twitter/X、小红书、抖音），等待 **5 秒以上** +- 如果 snapshot 显示内容不完整，再等几秒后重新 snapshot + +### 表单输入规范 + +如果需要在搜索框内输入内容（而非直接导航到搜索 URL）： + +- 使用 `browser act` 的 `type` 动作，并设置 `slowly: true` +- **不要使用 `fill()`**，可能导致搜索框无法正确触发搜索 + --- ## Government & Policy