用户业务资料库与预设（Assets）
业务资料按产品名分目录 — .aws-article/products/{产品名}/ 直挂业务介绍 .md、images/ 存配图（含同名说明 .md）。写涉及用户自身业务的文章/配图前必须先查这里；新生成的业务介绍内容应引导用户保存到这里。预设包合并到 .aws-article/presets/。
套件说明 · 本 skill 属 aws-wechat-article-* 一条龙套件（共 9 个 slug，入口 aws-wechat-article-main）。跨 skill 的相对引用依赖同一 skills/ 目录，建议一并 clawhub install 全套。源码：https://github.com/aiworkskills/wechat-article-skills
能力披露（Capabilities）
本 skill 管理本地业务资料库与预设包，可选从 aiworkskills.cn 域下载 .aws 预设包（ZIP 格式）。
- 凭证：无
- 网络：可选
https://*.aiworkskills.cn/**/*.aws 下载预设包。白名单强制：仅 HTTPS + aiworkskills.cn 子域，非白名单会直接报错退出。调试参数 --allow-any-host 可放宽但不推荐生产使用
- 文件读：用户指定的本地图片路径或
.aws 文件（脚本边界）；AI 在引导业务介绍入库时会先 ls .aws-article/products/ 看已有产品名
- 文件写：仓库内
.aws-article/products/{产品名}/*.md（业务介绍，AI 用 Write 工具直接落库）、.aws-article/products/{产品名}/images/*（图片 + 同名 .md，由脚本写）、.aws-article/presets/<子目录>/*（预设文件）、.aws-article/downloads/*.aws（下载缓存）、.aws-article/tmp/*（解压临时目录）；导入 .aws 时仓库根 aws.env 会按映射表增量写入密钥字段（覆盖现有键前自动备份为 aws.env.bak.{ts}，stderr 仅打印键名不打印值）
- 归档：解压
.aws 扩展名的 ZIP 到 .aws-article/tmp/，按白名单子目录合并到 .aws-article/presets/。已内置 ZIP slip 防御：逐项校验 ZIP 成员路径，拒绝含绝对路径、.. 段或解析后指向解压目录外的路径，任一违反立即退出不写入任何文件
- shell：仅
python3 {baseDir}/scripts/product_image_ingest.py、import_presets_aws.py
所有写入限制在仓库根下的 .aws-article/ 内。
配套 skill（informational）
本 skill 是 aws-wechat-article-* 一条龙公众号套件的业务资料库与预设环节（入口 aws-wechat-article-main）。
- 单独安装可用：业务图入库 /
.aws 预设导入两个脚本都不依赖兄弟 skill，只要 .aws-article/ 目录就能工作。
- 其他 skill 读取
.aws-article/products/{产品名}/（业务介绍 + images/）和 .aws-article/presets/ 里由本 skill 管理的资源，属套件协同；需结合写稿/配图/排版等 skill 使用。
完整 9 slug 清单见 源码仓库。
| 能力 | 说明 |
|---|
| 业务介绍 .md 入库 | AI 与用户对话产出业务介绍内容时，引导/响应保存到 products/{产品名}/<文件名>.md（用 Write 工具直接落库，无脚本） |
| 业务图入库 | 用户业务图 → products/{产品名}/images/（脚本 --product 必填），供其它 skill 引用 |
预设包 .aws | ZIP 包（本地文件或 https://aiworkskills.cn/**/*.aws URL）→ 合并 presets/ 子目录；config.yaml 见下 |
〇、设计意图（必读）⛔
.aws-article/products/{产品名}/ 是用户自家业务（卖货 / 卖软件 / 卖服务 / 自媒体 IP 等）的资料库——既是 AI 写涉及业务的内容时的底稿来源，也是 AI 与用户协作产出新介绍时的保存目的地。
目录约定
.aws-article/products/{产品名}/
├─ 项目介绍.md # 业务介绍 .md 直挂产品根（命名按用户行业，如 服务介绍.md / 品牌介绍.md）
├─ (其他业务文档.md)
└─ images/
├─ 配置首页.png
└─ 配置首页.md # 图片说明 .md（同名）
双向触发
| 方向 | 触发条件 | 行为 |
|---|
| 读 | 当前任务涉及用户自家业务（对外介绍 / 教程 / 案例 / 自家业务安利 / 业务相关配图） | 先 ls .aws-article/products/，识别本篇相关产品，读该产品根下 *.md、查 images/ 同名 .md，把已有素材作为底稿/配图候选 |
| 写 | AI 在会话中刚生成或改写的内容语义属于用户业务介绍 | 走 一、业务介绍 .md 入库；用户主动说"保存为产品介绍"等也走此流程 |
反例（不要触发）
- 主题是行业资讯 / 通用教程 / 与用户业务无关 → 不读、不写
- 用户明确表示内容"还没定型" → 不主动引导保存
- AI 不确定是不是用户自家业务时 → 宁可不主动提，也不要乱塞进
products/
一、业务介绍 .md 入库（Product Intro）
无需脚本，AI 用 Write 工具直接落库。
触发模式 A：AI 主动识别 + 引导
AI 在任意会话中刚生成或刚改写了一段内容，其语义明确属于用户自家业务介绍（产品 / 服务 / 品牌 / 项目 / 团队 / 业务范围介绍）时，主动提示用户：
"这段是 [产品名] 的业务介绍，要不要保存到产品资料库？我可以存到 .aws-article/products/{产品名}/{文件名}.md，下次写涉及业务的文章时会自动用上。"
用户确认 → 走「保存流程」。
触发模式 B：用户主动指令
用户说类似 "保存为产品介绍 / 业务介绍 / 服务介绍 / 自家介绍 / 入库到产品 / 存到产品资料库" 时，AI 把当前会话中的目标内容（用户指定段落或最近相关产出）走「保存流程」。
保存流程
- 确认产品名：
ls .aws-article/products/，已有目录则提示复用；新产品则向用户拿名字
- 确认文件名：默认
项目介绍.md；可改为 产品介绍.md / 服务介绍.md / 品牌介绍.md / 业务介绍.md 等贴用户行业的命名
- 创建目录：
mkdir -p .aws-article/products/{产品名}/images/（即便暂为空，把骨架建齐）
- 写入文件：用 Write 工具落到
.aws-article/products/{产品名}/{文件名}.md
- 反馈：「已存到
<完整路径>，下次涉及 [产品名] 业务的文章会自动用上」
二、业务图入库（Product Images）
目录
| 路径 | 作用 |
|---|
.aws-article/products/{产品名}/images/ | 入库图片 + 同名 .md（固定：图片路径 / 图片描述） |
工作流
- 用户上传或给出本地图片路径，并指明所属产品（与
products/ 下某个目录对应；新产品则脚本会自动创建）。
- Agent 读图（多模态能力在本对话侧）：确定中文主文件名（如
配置首页），并写出客观画面描述（供 .md 与后续配图检索使用）。
- 在仓库根执行（推荐带上
--content，与第 2 步描述一致）：
python {baseDir}/scripts/product_image_ingest.py <源图片路径> \
--product "公众号AI运营助手" --stem "配置首页" \
--content "客观中文描述，一两句即可"
--product 必填；产品目录与 images/ 子目录不存在时自动创建。
- 生成
配置首页.png + 配置首页.md（格式见下）。
图片描述与占位 ⛔
product_image_ingest.py 不会读图：无视觉/多模态，只负责复制图片并按模板写 .md。- 未传
--content（或为空） 时，「图片描述」会写入固定占位句：「请根据图片补全（客观描述画面内容即可）。」——这是预期行为，不是脚本故障。
- 要直接得到可用描述：入库命令必须带
--content "……"（由 Agent 读图后填写），或入库后手动/由 Agent 编辑同名 .md 替换占位段。
.md 固定格式
**图片路径**：`.aws-article/products/公众号AI运营助手/images/示例.png`
**图片描述**：……
脚本 product_image_ingest.py
source、--product（必填）、--stem（必填）、--content（可选，强烈建议由 Agent 读图后传入）、--repo（可选）
三、预设包导入（.aws）
扩展名 .aws，实质为 ZIP。解压后根目录应包含与仓库一致的预设文件夹（可多出其它文件，脚本只处理下列目录）：
closing-blocks、cover-styles、formatting、image-styles、sticker-styles、structures、title-styles
另可有根级 config.yaml、writing-spec.md。
输入来源（本地 / URL）
bundle 参数同时接受两种形态：
- 本地路径：
./brand-a.aws 或绝对路径
- HTTPS URL：仅限
aiworkskills.cn 及其子域，必须 https:// 开头、路径以 .aws 结尾
- 示例：
https://aiworkskills.cn/bundles/brand-a.aws
- 下载缓存：
.aws-article/downloads/<原文件名>（不在 tmp/ 内，不受清空影响，保留供事后核对）
- 不在白名单、非 https、或下载内容非 ZIP → 直接报错退出
- 调试放宽：
--allow-any-host 可跳过域名白名单（仍强制 https）；不建议生产使用
合并规则
- 每个上述目录采用**「替换式」语义**（以服务端为准，避免旧文件残留）：
- 若包内存在该子目录 → 先清空本地
.aws-article/presets/<同名>/ 再写入包内内容（旧包里有、新包里删掉的文件不会残留）；
- 若包内不存在该子目录 → 本地对应子目录保持不动（不受本次导入影响）。
- 包根优先级：若包根下同时存在
presets/<名>/ 与 <名>/，脚本优先合并前者；若目录内仅有一层多余 <名>/<名>/，脚本会自动以内层为合并根。
config.yaml：若包内存在且本地尚无 .aws-article/config.yaml，则从包内复制；若本地已有，则不覆盖，按包内字段与本地同名键递归比对，将差异以 JSON 数组 打印到 stdout（{"key":"点分路径","old":…,"new":…}），供智能体询问用户后再手改配置；说明日志在 stderr。writing-spec.md：若包内存在，始终覆盖写入 .aws-article/writing-spec.md（与 config.yaml 不同，不做差异比对）。- 解压目录：
.aws-article/tmp/（固定路径；运行前若无 .aws-article 会创建）。每次执行前若 tmp 已存在则整目录删除后重建，再解压本次 .aws；合并到 presets/ 后保留解压结果便于核对，下次导入会再次清空 tmp 并覆盖为新包内容。
密钥与配置
-
config.yaml 中的密钥字段会被增量写入仓库根 aws.env。包内 config.yaml 顶层 wechat_appid / wechat_appsecret、嵌套 writing_model.api_key / image_model.api_key 在导入时按下表映射写入：
config.yaml 字段 | aws.env 键 |
|---|
wechat_appid | WECHAT_1_APPID |
wechat_appsecret | WECHAT_1_APPSECRET |
writing_model.api_key | WRITING_MODEL_API_KEY |
image_model.api_key | IMAGE_MODEL_API_KEY |
-
写入策略：包内字段为空 → 不动 aws.env 现有键；aws.env 无该键 → 追加；已有相同值 → 跳过；已有不同值 → 写入前备份 aws.env.bak.{ts} 后覆盖。stderr 仅输出键名清单，不打印密钥值；保留原文件顺序、空行与注释。当前前端导出仅支持单微信账号（固定槽位 1），aws.env 中的 WECHAT_2_* 等其他键不受导入影响。
-
config.yaml（运营配置）：本地无则首次复制；本地有则差异 JSON 输出到 stdout 不覆盖（与原行为一致），由 Agent 询问用户确认后手改。
工作流
- 准备
*.aws 来源：(a) 本地文件（上传或已有路径），或 (b) 符合白名单的 HTTPS URL。
- 可先
--dry-run 查看将写入的路径（URL 模式下仍会实际下载到 downloads/ 以便校验 ZIP 结构，但不写入 presets/ 与 config.yaml）。
- 在仓库根执行：
# 本地路径
python {baseDir}/scripts/import_presets_aws.py path/to/bundle.aws
python {baseDir}/scripts/import_presets_aws.py path/to/bundle.aws --dry-run
# URL（仅 aiworkskills.cn 及子域）
python {baseDir}/scripts/import_presets_aws.py https://aiworkskills.cn/bundles/brand-a.aws
python {baseDir}/scripts/import_presets_aws.py https://aiworkskills.cn/x/y.aws --dry-run
脚本 import_presets_aws.py
- 参数：
bundle（.aws 路径 或 https://*.aiworkskills.cn URL）、--dry-run、--repo、--allow-any-host（调试）
脚本一览
| 脚本 | 路径 |
|---|
product_image_ingest.py | {baseDir}/scripts/product_image_ingest.py |
import_presets_aws.py | {baseDir}/scripts/import_presets_aws.py |
过程文件
| 场景 | 产出 |
|---|
| 业务介绍 .md 入库 | .aws-article/products/{产品名}/{文件名}.md（AI 用 Write 工具落库；目录不存在时同时 mkdir 包括 images/） |
| 业务图入库 | .aws-article/products/{产品名}/images/*.{png,...} + 同名 *.md |
.aws 导入 | 更新 .aws-article/presets/**；config.yaml 首次复制或 stdout 差异 JSON；密钥增量写入仓库根 aws.env（覆盖前备份 aws.env.bak.{ts}）；解压缓存在 .aws-article/tmp/ |
.aws URL 导入 | 下载缓存 .aws-article/downloads/*.aws；其余同本地导入 |
