maskantech/maskanx_cm_backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: MaskanX backend

Browse Source 
Independent FastAPI backend for the MaskanX agentic growth platform.

Includes the agent runtime, MCP client integrations (Meta Ads, LinkedIn,
HubSpot, Tavily, Exa, xAI, Citedy, image generation), PostgreSQL storage
for chats and cron jobs, provider and secret management, and the CLI.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
AFFAANh
2026-08-01 10:28:22 +05:30
co-authored by Claude Opus 5
commit 19e1e84fb7
925 changed files with 675474 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.dockerignore
+52
View File
@@ -0,0 +1,52 @@
# Git and IDE
.git
.gitignore
.idea
.vscode
*.md
!README.md
# Python dev and cache
__pycache__
*.py[cod]
*$py.class
.venv
venv
uv.lock
.pytest_cache
.coverage
htmlcov
.tox
.mypy_cache
.ruff_cache
# Tests (not needed in runtime image)
tests
test.py
*_test.py
pytest.ini
.pre-commit-config.yaml
.flake8
.eslintrc
.stylelintrc
# Node command-runner dependencies
node_modules
**/node_modules
**/dist
**/.vite
# Example and local config (mount at runtime instead)
example
config.json
jobs.json
sessions_mount_dir
# Misc
.env
.env.*
!.env.example
.DS_Store
*.log
logs
cookbook
.env.development.example
+11
View File
@@ -0,0 +1,11 @@
MASKANX_ENV=development
MASKANX_STORAGE_BACKEND=postgres
MASKANX_PORT=8088
MASKANX_CORS_ORIGINS=https://app-dev.example.com
DB_HOST=development-postgres.example.internal
DB_PORT=5432
DB_NAME=campaign_dev
DB_USER=maskanx_dev
DB_PASSWORD=replace-me
DB_SSLMODE=require
LOG_LEVEL=INFO
.env.example
+65
View File
@@ -0,0 +1,65 @@
# MaskanX Environment Variables
# Copy this file to .env and fill in your values:
# cp .env.example .env
# Citedy API key — get a free key at https://www.citedy.com/developer
# This unlocks 52 SEO/marketing MCP tools and 6 pre-installed skills
CITEDY_API_KEY=
# Telegram bot token — create a bot via https://t.me/BotFather
TELEGRAM_BOT_TOKEN=
# Web UI port (default: 8088)
# MASKANX_PORT=8088
# Browser origins allowed to call this independent backend.
MASKANX_CORS_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
# Enabled messaging channels (default: all)
# MASKANX_ENABLED_CHANNELS=discord,dingtalk,feishu,qq,console,telegram
# Optional: Tavily search API key (https://tavily.com)
# TAVILY_API_KEY=
# Optional: GitHub token to avoid rate limits when fetching skills
# GITHUB_TOKEN=
# Optional: Exa search API key (https://exa.ai)
# EXA_API_KEY=
# Optional: XAI (Grok) API key for xai_search MCP
# XAI_API_KEY=
# Logging level: DEBUG, INFO, WARNING, ERROR
# LOG_LEVEL=INFO
# PostgreSQL Database Configuration
# Local default:
# DB_HOST=localhost
# Docker Compose default:
# DB_HOST=postgres
# Production:
# set these to your managed Postgres credentials, or set DATABASE_URL.
MASKANX_STORAGE_BACKEND=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=campaign
DB_USER=postgres
DB_PASSWORD=postgres
DB_SSLMODE=prefer
# Docker-only host port. Leave DB_PORT=5432 for the app container.
# POSTGRES_PUBLIC_PORT=5432
# Optional single-url alternative. If set, this overrides DB_* values.
# DATABASE_URL=postgresql://postgres:postgres@localhost:5432/campaign?sslmode=prefer
# Optional first-party Maskan CRM connection.
# These can also be configured per company in Settings > Maskan CRM.
# MASKAN_CRM_API_URL=http://127.0.0.1:8091/api/v1
# MASKAN_CRM_WEB_URL=http://127.0.0.1:5174
# MASKAN_CRM_INTEGRATION_KEY=
# --- For running live tests (tests/live_aom_test.py) ---
# QWEN_API_KEY=
# QWEN_API_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions
# QWEN_MODEL=qwen-plus
.env.local.example
+11
View File
@@ -0,0 +1,11 @@
MASKANX_ENV=local
MASKANX_STORAGE_BACKEND=postgres
MASKANX_PORT=8088
MASKANX_CORS_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=campaign
DB_USER=postgres
DB_PASSWORD=postgres
DB_SSLMODE=disable
LOG_LEVEL=INFO
.env.production.example
+12
View File
@@ -0,0 +1,12 @@
MASKANX_ENV=production
MASKANX_STORAGE_BACKEND=postgres
MASKANX_PORT=8088
MASKANX_CORS_ORIGINS=https://app.example.com
DATABASE_URL=postgresql://maskanx:replace-me@postgres.example.internal:5432/campaign?sslmode=require
LOG_LEVEL=INFO
# Store provider credentials in the deployment secret manager.
CITEDY_API_KEY=
TAVILY_API_KEY=
EXA_API_KEY=
XAI_API_KEY=
.env.testing.example
+13
View File
@@ -0,0 +1,13 @@
MASKANX_ENV=testing
MASKANX_STORAGE_BACKEND=postgres
MASKANX_PORT=8089
MASKANX_CORS_ORIGINS=http://127.0.0.1:5173
DB_HOST=127.0.0.1
DB_PORT=5432
DB_NAME=campaign_test
DB_USER=postgres
DB_PASSWORD=postgres
DB_SSLMODE=disable
ADCLAW_DISABLE_MEMORY_MANAGER=1
MASKANX_DISABLE_MCP=1
LOG_LEVEL=WARNING
.flake8
+12
View File
@@ -0,0 +1,12 @@
[flake8]
exclude =
scripts/*
src/agentscope/rpc/*
max-line-length = 79
inline-quotes = "
avoid-escape = no
ignore =
F401
F403
W503
E731
.gitignore
+36
View File
@@ -0,0 +1,36 @@
.venv/
.venv311/
venv/
__pycache__/
*.py[cod]
*.egg-info/
.pytest_cache/
.ruff_cache/
.mypy_cache/
.coverage
htmlcov/
dist/
build/
node_modules/
.env
.env.*
!.env.example
!.env.local.example
!.env.development.example
!.env.testing.example
!.env.production.example
working/
working.secret/
generated/
logs/
*.log
*.db
*.sqlite
*.sqlite3
.DS_Store
.idea/
.vscode/
.graphifyignore
+4
View File
@@ -0,0 +1,4 @@
# Exclude pre-built frontend bundle (minified JS) - pollutes graph with thousands of A(), Q(), ur() nodes
console
adclaw/console
src/adclaw/console
.mcp.json
+8
View File
@@ -0,0 +1,8 @@
{
"mcpServers": {
"expect": {
"command": "npx",
"args": ["-y", "expect-cli@latest", "mcp"]
}
}
}
.pre-commit-config.yaml
+120
View File
@@ -0,0 +1,120 @@
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.3.0
hooks:
- id: check-ast
exclude: '.*/skills/.*'
- id: sort-simple-yaml
exclude: '.*/skills/.*'
- id: check-yaml
exclude: |
(?x)^(
meta.yaml
)$
- id: check-xml
exclude: '.*/skills/.*'
- id: check-toml
- id: check-docstring-first
exclude: '.*/skills/.*'
- id: check-json
exclude: '.*/skills/.*'
- id: fix-encoding-pragma
exclude: '.*/skills/.*'
- id: detect-private-key
- id: trailing-whitespace
exclude: '.*/skills/.*'
- repo: https://github.com/asottile/add-trailing-comma
rev: v3.1.0
hooks:
- id: add-trailing-comma
exclude: '.*/skills/.*'
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.7.0
hooks:
- id: mypy
exclude:
(?x)(
pb2\.py$
| grpc\.py$
| ^docs
| \.html$
| .*/skills/.*
)
args: [
--ignore-missing-imports,
--disable-error-code=var-annotated,
--disable-error-code=union-attr,
--disable-error-code=assignment,
--disable-error-code=attr-defined,
--disable-error-code=import-untyped,
--disable-error-code=truthy-function,
--follow-imports=skip,
--explicit-package-bases,
]
- repo: https://github.com/psf/black
rev: 23.3.0
hooks:
- id: black
args: [ --line-length=79 ]
exclude: '.*/skills/.*'
- repo: https://github.com/PyCQA/flake8
rev: 6.1.0
hooks:
- id: flake8
args: [ "--extend-ignore=E203"]
exclude: '.*/skills/.*'
- repo: https://github.com/pylint-dev/pylint
rev: v3.0.2
hooks:
- id: pylint
exclude:
(?x)(
^docs
| pb2\.py$
| grpc\.py$
| \.demo$
| \.md$
| \.html$
| .*/skills/.*
)
args: [
--disable=W0511,
--disable=W0718,
--disable=W0122,
--disable=C0103,
--disable=R0913,
--disable=E0401,
--disable=E1101,
--disable=C0415,
--disable=W0603,
--disable=R1705,
--disable=R0914,
--disable=E0601,
--disable=W0602,
--disable=W0604,
--disable=R0801,
--disable=R0902,
--disable=R0903,
--disable=C0123,
--disable=W0231,
--disable=W1113,
--disable=W0221,
--disable=R0401,
--disable=W0632,
--disable=W0123,
--disable=C3001,
--disable=W0201,
--disable=C0302,
--disable=W1203,
--disable=C2801,
--disable=C0114, # Disable missing module docstring for quick dev
--disable=C0115, # Disable missing class docstring for quick dev
--disable=C0116, # Disable missing function or method docstring for quick dev
]
- repo: https://github.com/pre-commit/mirrors-prettier
rev: 'v3.0.0'
hooks:
- id: prettier
additional_dependencies: [ 'prettier@3.0.0' ]
files: \.(tsx?)$
exclude: '(?x)(^console/|/dist/|.*/skills/.*)'
.python-version
+1
View File
@@ -0,0 +1 @@
3.10
Dockerfile
+166
View File
@@ -0,0 +1,166 @@
# -----------------------------------------------------------------------------
# Runtime image with Node.js, Python, optional Chromium, and the API.
# -----------------------------------------------------------------------------
FROM node:22-bookworm-slim
# Build variant: "core" | "browser" | "full"
# core — Python + MaskanX + Telegram only (no Chromium, no optional channels)
# browser — core + Chromium/xvfb + Playwright/PinchTab/agent-browser
# full — browser + Feishu/Discord/DingTalk channels + desktop tools
ARG MASKANX_VARIANT=full
# Pip extras to install (overrides variant default if provided).
# Variant defaults: core="[local]", browser="[browser,local]", full="[all,local]"
ARG MASKANX_PIP_EXTRAS=""
# Preload default local embedding model during image build by default.
ARG MASKANX_PRELOAD_EMBEDDINGS=1
# ENV variables
ENV NODE_ENV=production
ENV WORKSPACE_DIR=/app
ENV ADCLAW_WORKING_DIR=/app/working
ENV HF_HOME=/app/model-cache/huggingface
ENV SENTENCE_TRANSFORMERS_HOME=/app/model-cache/sentence-transformers
ENV ADCLAW_MEMORY_MANAGER_START_MODE=background
ENV ADCLAW_ENABLE_REME=0
ENV ADCLAW_REME_LIGHT_TOKEN_COUNTER=1
ENV ADCLAW_MEMORY_MANAGER_BACKGROUND_DELAY_SECONDS=5
ENV ADCLAW_MEMORY_MANAGER_MAX_LOADAVG=2.0
ENV ADCLAW_MEMORY_COMPACT_BATCH_MESSAGES=80
ENV ADCLAW_REME_RETENTION_DAYS=30
ENV MEMORY_STORE_BACKEND=sqlite
ENV FTS_ENABLED=true
# Default enabled channels (can be overridden at runtime with -e MASKANX_ENABLED_CHANNELS=...).
ARG MASKANX_ENABLED_CHANNELS="discord,dingtalk,feishu,qq,console,telegram"
ENV MASKANX_ENABLED_CHANNELS=${MASKANX_ENABLED_CHANNELS}
ENV ADCLAW_ENABLED_CHANNELS=${MASKANX_ENABLED_CHANNELS}
ARG DEBIAN_FRONTEND=noninteractive
# -----------------------------------------------------------------------------
# Base system packages (all variants)
# -----------------------------------------------------------------------------
RUN apt-get update && apt-get install -y --fix-missing \
curl \
python3 \
python3-pip \
python3-venv \
build-essential \
libssl-dev \
git \
supervisor \
vim \
gettext-base \
&& rm -rf /var/lib/apt/lists/* \
&& apt-get clean
# -----------------------------------------------------------------------------
# Browser stack (only for browser/full variants)
# -----------------------------------------------------------------------------
RUN if [ "$MASKANX_VARIANT" != "core" ]; then \
apt-get update && apt-get install -y --fix-missing \
xfce4 \
xfce4-terminal \
xvfb \
dbus-x11 \
fonts-wqy-zenhei \
fonts-wqy-microhei \
chromium \
chromium-sandbox \
libx11-xcb1 \
libxcomposite1 \
libxdamage1 \
libxext6 \
libxfixes3 \
libxi6 \
libxtst6 \
libnss3 \
libglib2.0-0 \
libdrm2 \
libgbm1 \
libasound2 \
fonts-liberation \
libu2f-udev \
&& rm -rf /var/lib/apt/lists/* \
&& apt-get clean \
&& sed -i 's/^CHROMIUM_FLAGS=""/CHROMIUM_FLAGS="--no-sandbox"/' /usr/bin/chromium ; \
fi
# PinchTab: token-efficient browser control for AI agents (browser/full only).
RUN if [ "$MASKANX_VARIANT" != "core" ]; then \
curl -fsSL https://pinchtab.com/install.sh | bash \
&& cp /root/.pinchtab/bin/*/pinchtab-linux-* /usr/local/bin/pinchtab-bin \
&& chmod 755 /usr/local/bin/pinchtab-bin ; \
fi
ENV PINCHTAB_PORT=9867
# agent-browser: install CLI globally (browser/full only).
RUN if [ "$MASKANX_VARIANT" != "core" ]; then \
npm install -g agent-browser sitefetch ; \
fi
# Browser env vars (harmless if binaries missing)
ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
ENV PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
ENV ADCLAW_RUNNING_IN_CONTAINER=1
ENV MASKANX_VARIANT=${MASKANX_VARIANT}
ENV ADCLAW_VARIANT=${MASKANX_VARIANT}
WORKDIR ${WORKSPACE_DIR}
RUN python3 -m venv venv
ENV PATH="/app/venv/bin:$PATH"
COPY pyproject.toml README.md ./
COPY src ./src
# Install CPU-only PyTorch first (avoids downloading 2GB CUDA build),
# then install app with variant-specific extras.
# core → [local] — Python + MaskanX + AOM embeddings
# browser → [browser,local] — + Playwright
# full → [all,local] — + all optional channels + desktop tools
# MASKANX_PIP_EXTRAS can override this computed default.
RUN EXTRAS="${MASKANX_PIP_EXTRAS}"; \
if [ -z "$EXTRAS" ]; then \
case "$MASKANX_VARIANT" in \
core) EXTRAS="[local]" ;; \
browser) EXTRAS="[browser,local]" ;; \
full) EXTRAS="[all,local]" ;; \
*) EXTRAS="[all,local]" ;; \
esac; \
fi; \
echo ">>> Installing MaskanX with extras=${EXTRAS} (variant=${MASKANX_VARIANT})" && \
pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu && \
pip install --no-cache-dir ".${EXTRAS}"
# Preload the default local embedding model at build time so first production
# memory queries don't stall while downloading from Hugging Face.
RUN mkdir -p /app/model-cache \
&& if [ "$MASKANX_PRELOAD_EMBEDDINGS" = "1" ]; then \
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')" ; \
else \
echo ">>> Skipping embedding model preload"; \
fi
# Non-root user for running the app (supervisord stays root for system services).
RUN groupadd -r maskanx && useradd -r -g maskanx -m -s /bin/bash maskanx \
&& mkdir -p /app/working /app/working.secret /app/logs /home/maskanx/.config/pinchtab /app/model-cache \
&& chown -R maskanx:maskanx /app/working /app/working.secret /app/logs /home/maskanx/.config /app/model-cache
# Config.json is generated at runtime by entrypoint.sh (only if missing),
# so it persists user settings across container restarts.
# MaskanX app port (default 8088). Override at runtime with -e MASKANX_PORT=3000.
ENV ADCLAW_PORT=8088
COPY deploy/config/supervisord.conf.template /etc/supervisor/conf.d/supervisord.conf.template
COPY deploy/config/supervisord.browser.conf.template /etc/supervisor/conf.d/supervisord.browser.conf.template
COPY deploy/entrypoint.sh /entrypoint.sh
RUN chmod 755 /entrypoint.sh
EXPOSE 8088
CMD ["/entrypoint.sh"]
LICENSE
+20
View File
@@ -0,0 +1,20 @@
MaskanX Proprietary License
Copyright (c) 2026 MaskanX. All rights reserved.
This software and associated documentation files (the "Software") are
proprietary to MaskanX.
You may use, copy, modify, deploy, and distribute the Software only with prior
written permission from MaskanX or under a separate written agreement signed
by MaskanX.
No rights are granted to sublicense, sell, lease, rent, publish, host for third
parties, or otherwise make the Software available to others except where
expressly permitted in writing by MaskanX.
The Software is provided "as is", without warranty of any kind, express or
implied, including but not limited to the warranties of merchantability,
fitness for a particular purpose, and noninfringement. In no event shall
MaskanX be liable for any claim, damages, or other liability arising from use
of the Software.
README.md
+128
View File
@@ -0,0 +1,128 @@
# MaskanX Backend
Independent Python and FastAPI backend for MaskanX.
## Service Contract
- Default API URL: `http://127.0.0.1:8088`
- PostgreSQL database: `campaign`
- Frontend origin: configured with `MASKANX_CORS_ORIGINS`
- Maskan CRM: connected through its versioned REST API and optional MCP tools
This repository never connects directly to the Maskan CRM PostgreSQL database.
## Local Setup
1. Create the database:
```sql
CREATE DATABASE campaign;
```
2. Install dependencies and configure the environment:
```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
npm install
Copy-Item .env.local.example .env.local
```
3. Migrate, seed, and start:
```powershell
npm run local:migrate
npm run local:seed
npm run local
```
Open API documentation at `http://127.0.0.1:8088/docs` when documentation is
enabled.
### Upgrading from JSON storage
Chats and cron jobs were originally stored as JSON files in the working
directory (`~/.adclaw/chats.json` and `~/.adclaw/jobs.json`). PostgreSQL is now
the default backend, so those records are no longer read and existing chats,
sessions, and scheduled jobs appear to be missing even though nothing was
deleted.
Copy them into PostgreSQL once:
```powershell
npm run local:import-json -- --dry-run # report what would be imported
npm run local:import-json # perform the import
```
The import upserts by id and never deletes, so it is safe to re-run. The JSON
files are left untouched as a backup.
### Clearing and restoring credentials
**Stop MaskanX before clearing credentials.** A running app holds its
configuration in memory and can rewrite `config.json` and `providers.json`
after the clear, silently restoring the values that were just removed. The
clear script now verifies the result and exits non-zero if anything
secret-looking survives.
Credentials live in three places, and all of them are cleared:
- `~/.adclaw.secret/providers.json` - LLM provider keys
- `~/.adclaw.secret/envs.json` - integration keys
- `~/.adclaw/companies/<id>/` - a per-company copy of both, plus LinkedIn OAuth
Because each company keeps its own copy, an intact company store can be used to
recover the active one:
```powershell
npm run secrets:restore -- --from default --dry-run
npm run secrets:restore -- --from default
```
Credential files are copied wholesale; `config.json` is patched surgically, so
only missing MCP env values and disabled clients are restored and
company-specific settings are preserved. A backup is written to
`~/.adclaw.secret/restore-backups/` first.
## Commands
| Command | Purpose |
| --- | --- |
| `npm start` | Start using `.env` or injected environment variables |
| `npm run build` | Build a Python wheel in `dist/` |
| `npm run local` | Local API with reload |
| `npm run local:migrate` | Apply local PostgreSQL migrations |
| `npm run local:migrate:undo` | Roll back the newest migration |
| `npm run local:migrate:undo:all` | Roll back every migration |
| `npm run local:seed` | Add starter data |
| `npm run local:seed:undo` | Remove starter data |
| `npm run local:import-json` | Import legacy JSON chats/cron jobs into PostgreSQL |
| `npm run secrets:dry-run` | Report which credentials a clear would remove |
| `npm run secrets:clear` | Clear runtime credentials (creates a backup) |
| `npm run secrets:clear:all` | Also blank secret lines in `.env` files (creates a backup) |
| `npm run secrets:delete:all` | Clear everything including `.env` files (creates a backup) |
| `npm run secrets:delete:all:no-backup` | Same, with **no backup** - irreversible |
| `npm run secrets:restore` | Restore credentials from an intact company store |
| `npm run local:reset` | Rebuild and seed the local schema |
| `npm run dev` | Development API with reload |
| `npm run dev:migrate` | Apply development migrations |
| `npm run dev:reset` | Reset the development schema |
| `npm test` | Run Pytest using `.env.testing` |
| `npm run test:migrate` | Apply test database migrations |
| `npm run test:reset` | Reset the test schema |
| `npm run prod` | Start the production API |
| `npm run prod:migrate` | Apply production migrations |
| `npm run prod:seed` | Apply production starter data |
The command names match the platform deployment contract. They invoke the
native MaskanX Python migration runner, not Sequelize.
## Docker
```powershell
Copy-Item .env.local.example .env
docker compose up -d --build
```
For a managed PostgreSQL deployment, provide `DATABASE_URL` through the hosting
secret manager and run `npm run prod:migrate` as a release step.
deploy/config/supervisord.browser.conf.template
+35
View File
@@ -0,0 +1,35 @@
[program:dbus]
command=/bin/sh -c "rm -f /run/dbus/pid; mkdir -p /run/dbus; exec /usr/bin/dbus-daemon --system --nofork"
autostart=true
autorestart=true
stderr_logfile=/var/log/dbus.err.log
stdout_logfile=/var/log/dbus.out.log
[program:pinchtab]
command=/bin/sh -c "sleep 2; exec /usr/local/bin/pinchtab-bin server"
user=maskanx
autostart=true
autorestart=true
priority=25
stderr_logfile=/var/log/pinchtab.err.log
stdout_logfile=/var/log/pinchtab.out.log
environment=DISPLAY=":1",HOME="/home/maskanx"
[program:xvfb]
command=/bin/sh -c "rm -f /tmp/.X1-lock /tmp/.X11-unix/X1; mkdir -p /tmp/.X11-unix; exec /usr/bin/Xvfb :1 -screen 0 1280x800x24"
autostart=true
autorestart=true
priority=10
stderr_logfile=/var/log/xvfb.err.log
stdout_logfile=/var/log/xvfb.out.log
environment=DISPLAY=":1"
[program:xfce4]
command=/bin/sh -c 'export DISPLAY=:1; for i in $(seq 1 200); do [ -S /tmp/.X11-unix/X1 ] && break; sleep 0.1; done; exec dbus-run-session startxfce4'
autostart=true
autorestart=true
priority=20
stderr_logfile=/var/log/xfce4.err.log
stdout_logfile=/var/log/xfce4.out.log
environment=DISPLAY=":1"
deploy/config/supervisord.conf.template
+15
View File
@@ -0,0 +1,15 @@
[supervisord]
user=root
logfile=/var/log/supervisord.log
pidfile=/var/log/supervisord.pid
nodaemon=true
[program:app]
command=maskanx app --host 0.0.0.0 --port ${ADCLAW_PORT}
user=maskanx
autostart=true
autorestart=true
priority=30
stderr_logfile=/var/log/app.err.log
stdout_logfile=/var/log/app.out.log
environment=DISPLAY=":1",PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH="/usr/bin/chromium",ADCLAW_RUNNING_IN_CONTAINER="1",HOME="/home/maskanx"
deploy/digitalocean-app.yaml
+26
View File
@@ -0,0 +1,26 @@
spec:
name: MaskanX
region: ams
services:
- name: MaskanX
image:
registry_type: DOCKER_HUB
registry: nttylock
repository: MaskanX
tag: latest
instance_count: 1
instance_size_slug: basic-s
http_port: 8088
envs:
- key: CITEDY_API_KEY
scope: RUN_TIME
type: SECRET
- key: TELEGRAM_BOT_TOKEN
scope: RUN_TIME
type: SECRET
- key: MASKANX_ENABLED_CHANNELS
scope: RUN_TIME
value: discord,dingtalk,feishu,qq,console,telegram
- key: LOG_LEVEL
scope: RUN_TIME
value: INFO
deploy/entrypoint.sh
+153
View File
@@ -0,0 +1,153 @@
#!/bin/sh
# Substitute the app port in supervisord template and start supervisord.
# Default port 8088; override at runtime with -e MASKANX_PORT=3000.
set -e
export ADCLAW_PORT="${MASKANX_PORT:-${ADCLAW_PORT:-8088}}"
export ADCLAW_WORKING_DIR="${MASKANX_WORKING_DIR:-${ADCLAW_WORKING_DIR:-/app/working}}"
export ADCLAW_SECRET_DIR="${MASKANX_SECRET_DIR:-${ADCLAW_SECRET_DIR:-/app/working.secret}}"
export ADCLAW_ENABLED_CHANNELS="${MASKANX_ENABLED_CHANNELS:-${ADCLAW_ENABLED_CHANNELS:-discord,dingtalk,feishu,qq,console,telegram}}"
export ADCLAW_STORAGE_BACKEND="${MASKANX_STORAGE_BACKEND:-${ADCLAW_STORAGE_BACKEND:-json}}"
# Ensure config.json exists (first run only — don't overwrite user config)
CONFIG="${ADCLAW_WORKING_DIR}/config.json"
if [ ! -f "$CONFIG" ] || [ ! -s "$CONFIG" ]; then
echo "entrypoint: No config.json found, generating default..."
maskanx init --defaults --accept-security 2>/dev/null || true
fi
# Migrate config.json — apply new defaults to existing config without overwriting user data
python3 -c "
import json, os, sys
cfg_path = os.environ.get('ADCLAW_WORKING_DIR', '/app/working') + '/config.json'
if not os.path.isfile(cfg_path):
sys.exit(0)
with open(cfg_path) as f:
cfg = json.load(f)
changed = False
# Force correct defaults that should never be True in production
if cfg.get('show_tool_details') is not False:
cfg['show_tool_details'] = False
changed = True
# Ensure filter_tool_messages=True on all channels
for ch_name, ch_cfg in cfg.get('channels', {}).items():
if isinstance(ch_cfg, dict) and ch_cfg.get('filter_tool_messages') is not True:
ch_cfg['filter_tool_messages'] = True
changed = True
if changed:
with open(cfg_path, 'w') as f:
json.dump(cfg, f, indent=2, ensure_ascii=False)
print('entrypoint: config.json migrated (applied new defaults)')
else:
print('entrypoint: config.json OK (no migration needed)')
" 2>/dev/null || true
# Enable Citedy MCP client if API key is provided at runtime
if [ -n "$CITEDY_API_KEY" ]; then
CONFIG="${ADCLAW_WORKING_DIR}/config.json"
if [ -f "$CONFIG" ]; then
python3 -c "
import json, os
cfg_path = os.environ.get('ADCLAW_WORKING_DIR', '/app/working') + '/config.json'
with open(cfg_path) as f:
cfg = json.load(f)
mcp = cfg.setdefault('mcp', {}).setdefault('clients', {})
key = os.environ['CITEDY_API_KEY']
mcp['citedy'] = {
'name': 'citedy_mcp',
'description': 'Citedy SEO & Marketing Tools (70+ tools)',
'enabled': True,
'transport': 'streamable_http',
'url': 'https://mcp.citedy.com/mcp',
'headers': {'Authorization': f'Bearer {key}', 'Accept': 'application/json, text/event-stream'},
'env': {'CITEDY_API_KEY': key},
}
with open(cfg_path, 'w') as f:
json.dump(cfg, f, indent=2)
print('entrypoint: Citedy MCP client enabled')
" 2>/dev/null || true
fi
fi
# Enable Exa search MCP if API key is provided at runtime
if [ -n "$EXA_API_KEY" ]; then
CONFIG="${ADCLAW_WORKING_DIR}/config.json"
if [ -f "$CONFIG" ]; then
python3 -c "
import json, os
cfg_path = os.environ.get('ADCLAW_WORKING_DIR', '/app/working') + '/config.json'
with open(cfg_path) as f:
cfg = json.load(f)
mcp = cfg.setdefault('mcp', {}).setdefault('clients', {})
key = os.environ['EXA_API_KEY']
mcp['exa'] = {
'name': 'exa_mcp',
'description': 'Exa AI search: web, code, people, companies',
'enabled': True,
'command': 'npx',
'args': ['-y', 'exa-mcp-server'],
'env': {'EXA_API_KEY': key},
}
with open(cfg_path, 'w') as f:
json.dump(cfg, f, indent=2)
print('entrypoint: Exa MCP client enabled')
" 2>/dev/null || true
fi
fi
# Enable Telegram channel if bot token is provided at runtime
if [ -n "$TELEGRAM_BOT_TOKEN" ]; then
CONFIG="${ADCLAW_WORKING_DIR}/config.json"
if [ -f "$CONFIG" ]; then
python3 -c "
import json, os
cfg_path = os.environ.get('ADCLAW_WORKING_DIR', '/app/working') + '/config.json'
with open(cfg_path) as f:
cfg = json.load(f)
tg = cfg.setdefault('channels', {}).setdefault('telegram', {})
tg['enabled'] = True
tg['bot_token'] = os.environ['TELEGRAM_BOT_TOKEN']
with open(cfg_path, 'w') as f:
json.dump(cfg, f, indent=2)
print('entrypoint: Telegram channel enabled')
" 2>/dev/null || true
fi
fi
# Sync new built-in skills to active_skills (non-destructive: skip existing)
python3 -c "
from adclaw.agents.skills_manager import sync_skills_to_working_dir
synced, skipped = sync_skills_to_working_dir(skill_names=None, force=False)
if synced:
print(f'entrypoint: synced {synced} new skill(s) to active_skills')
else:
print(f'entrypoint: all skills up to date ({skipped} existing)')
" 2>/dev/null || true
# Ensure working dirs are owned by MaskanX user (entrypoint runs as root)
mkdir -p /app/logs 2>/dev/null || true
chown -R maskanx:maskanx "${ADCLAW_WORKING_DIR}" "${ADCLAW_SECRET_DIR}" /app/logs 2>/dev/null || true
# Run Postgres migrations when requested. Keep JSON/file mode as the default so
# local users can still start the app without a database.
case "$(printf '%s' "$ADCLAW_STORAGE_BACKEND" | tr '[:upper:]' '[:lower:]')" in
postgres|postgresql|pg)
echo "entrypoint: PostgreSQL storage enabled, running migrations..."
maskanx db migrate
;;
esac
# Generate supervisord.conf from templates based on MASKANX_VARIANT.
# core → base template only (supervisord + app).
# browser/full → base + browser template (adds dbus, xvfb, xfce4, pinchtab).
MASKANX_VARIANT="${MASKANX_VARIANT:-${ADCLAW_VARIANT:-full}}"
SUPERVISORD_CONF="/etc/supervisor/conf.d/supervisord.conf"
envsubst '${ADCLAW_PORT}' \
< /etc/supervisor/conf.d/supervisord.conf.template \
> "$SUPERVISORD_CONF"
if [ "$MASKANX_VARIANT" != "core" ] && [ -f /etc/supervisor/conf.d/supervisord.browser.conf.template ]; then
cat /etc/supervisor/conf.d/supervisord.browser.conf.template >> "$SUPERVISORD_CONF"
echo "entrypoint: supervisord configured with browser programs (variant=${MASKANX_VARIANT})"
else
echo "entrypoint: supervisord configured without browser (variant=${MASKANX_VARIANT})"
fi
exec /usr/bin/supervisord -c "$SUPERVISORD_CONF"
deploy/render.yaml
+20
View File
@@ -0,0 +1,20 @@
services:
- type: web
name: maskanx-backend
runtime: docker
dockerfilePath: ./Dockerfile
plan: starter
healthCheckPath: /api/version
envVars:
- key: CITEDY_API_KEY
sync: false
- key: TELEGRAM_BOT_TOKEN
sync: false
- key: MASKANX_ENABLED_CHANNELS
value: discord,dingtalk,feishu,qq,console,telegram
- key: LOG_LEVEL
value: INFO
disk:
name: MaskanX-data
mountPath: /app/working
sizeGB: 1
docker-compose.yml
+53
View File
@@ -0,0 +1,53 @@
services:
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_DB: ${DB_NAME:-campaign}
POSTGRES_USER: ${DB_USER:-postgres}
POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
ports:
- "${POSTGRES_PUBLIC_PORT:-5432}:5432"
volumes:
- maskanx_postgres:/var/lib/postgresql/data
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U ${DB_USER:-postgres} -d ${DB_NAME:-campaign}",
]
interval: 5s
timeout: 5s
retries: 20
api:
build:
context: .
args:
MASKANX_VARIANT: ${MASKANX_VARIANT:-core}
MASKANX_PRELOAD_EMBEDDINGS: ${MASKANX_PRELOAD_EMBEDDINGS:-0}
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
ports:
- "${MASKANX_PORT:-8088}:8088"
volumes:
- maskanx_working:/app/working
- maskanx_secrets:/app/working.secret
environment:
MASKANX_STORAGE_BACKEND: postgres
MASKANX_PORT: 8088
MASKANX_CORS_ORIGINS: ${MASKANX_CORS_ORIGINS:-http://127.0.0.1:5173,http://localhost:5173}
DB_HOST: postgres
DB_PORT: 5432
DB_NAME: ${DB_NAME:-campaign}
DB_USER: ${DB_USER:-postgres}
DB_PASSWORD: ${DB_PASSWORD:-postgres}
DB_SSLMODE: disable
LOG_LEVEL: ${LOG_LEVEL:-INFO}
volumes:
maskanx_postgres:
maskanx_working:
maskanx_secrets:
package-lock.json
Generated
+157
View File
@@ -0,0 +1,157 @@
{
"name": "maskanx-backend",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "maskanx-backend",
"version": "1.0.0",
"dependencies": {
"dotenv": "^16.6.1"
},
"devDependencies": {
"cross-env": "^7.0.3",
"dotenv-cli": "^8.0.0"
}
},
"node_modules/cross-env": {
"version": "7.0.3",
"resolved": "https://registry.npmjs.org/cross-env/-/cross-env-7.0.3.tgz",
"integrity": "sha512-+/HKd6EgcQCJGh2PSjZuUitQBQynKor4wrFbRg4DtAgS1aWO+gU52xpH7M9ScGgXSYmAVS9bIJ8EzuaGw0oNAw==",
"dev": true,
"license": "MIT",
"dependencies": {
"cross-spawn": "^7.0.1"
},
"bin": {
"cross-env": "src/bin/cross-env.js",
"cross-env-shell": "src/bin/cross-env-shell.js"
},
"engines": {
"node": ">=10.14",
"npm": ">=6",
"yarn": ">=1"
}
},
"node_modules/cross-spawn": {
"version": "7.0.6",
"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
"integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
"dev": true,
"license": "MIT",
"dependencies": {
"path-key": "^3.1.0",
"shebang-command": "^2.0.0",
"which": "^2.0.1"
},
"engines": {
"node": ">= 8"
}
},
"node_modules/dotenv": {
"version": "16.6.1",
"resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
"integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
"license": "BSD-2-Clause",
"engines": {
"node": ">=12"
},
"funding": {
"url": "https://dotenvx.com"
}
},
"node_modules/dotenv-cli": {
"version": "8.0.0",
"resolved": "https://registry.npmjs.org/dotenv-cli/-/dotenv-cli-8.0.0.tgz",
"integrity": "sha512-aLqYbK7xKOiTMIRf1lDPbI+Y+Ip/wo5k3eyp6ePysVaSqbyxjyK3dK35BTxG+rmd7djf5q2UPs4noPNH+cj0Qw==",
"dev": true,
"license": "MIT",
"dependencies": {
"cross-spawn": "^7.0.6",
"dotenv": "^16.3.0",
"dotenv-expand": "^10.0.0",
"minimist": "^1.2.6"
},
"bin": {
"dotenv": "cli.js"
}
},
"node_modules/dotenv-expand": {
"version": "10.0.0",
"resolved": "https://registry.npmjs.org/dotenv-expand/-/dotenv-expand-10.0.0.tgz",
"integrity": "sha512-GopVGCpVS1UKH75VKHGuQFqS1Gusej0z4FyQkPdwjil2gNIv+LNsqBlboOzpJFZKVT95GkCyWJbBSdFEFUWI2A==",
"dev": true,
"license": "BSD-2-Clause",
"engines": {
"node": ">=12"
}
},
"node_modules/isexe": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
"integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
"dev": true,
"license": "ISC"
},
"node_modules/minimist": {
"version": "1.2.8",
"resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
"integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
"dev": true,
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/path-key": {
"version": "3.1.1",
"resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
"integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=8"
}
},
"node_modules/shebang-command": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
"integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
"dev": true,
"license": "MIT",
"dependencies": {
"shebang-regex": "^3.0.0"
},
"engines": {
"node": ">=8"
}
},
"node_modules/shebang-regex": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
"integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=8"
}
},
"node_modules/which": {
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
"integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
"dev": true,
"license": "ISC",
"dependencies": {
"isexe": "^2.0.0"
},
"bin": {
"node-which": "bin/node-which"
},
"engines": {
"node": ">= 8"
}
}
}
}
package.json
+53
View File
@@ -0,0 +1,53 @@
{
"name": "maskanx-backend",
"version": "1.0.0",
"private": true,
"description": "Independent FastAPI backend for MaskanX.",
"scripts": {
"start": "node -r dotenv/config scripts/run-python.cjs -m adclaw app --host 0.0.0.0 --port 8088",
"build": "node scripts/run-python.cjs -m pip wheel . --no-deps --wheel-dir dist",
"local": "dotenv -e .env.local -- node scripts/run-python.cjs -m adclaw app --host 127.0.0.1 --port 8088 --reload",
"local:migrate": "dotenv -e .env.local -- node scripts/run-python.cjs -m adclaw db migrate",
"local:migrate:undo": "dotenv -e .env.local -- node scripts/run-python.cjs -m adclaw db migrate-undo",
"local:migrate:undo:all": "dotenv -e .env.local -- node scripts/run-python.cjs -m adclaw db migrate-undo-all",
"local:seed": "dotenv -e .env.local -- node scripts/run-python.cjs -m adclaw db seed",
"local:import-json": "dotenv -e .env.local -- node scripts/run-python.cjs -m adclaw db import-json",
"local:seed:undo": "dotenv -e .env.local -- node scripts/run-python.cjs -m adclaw db seed-undo",
"local:reset": "npm run local:migrate:undo:all && npm run local:migrate && npm run local:seed",
"dev": "dotenv -e .env.development -- node scripts/run-python.cjs -m adclaw app --host 0.0.0.0 --port 8088 --reload",
"dev:migrate": "dotenv -e .env.development -- node scripts/run-python.cjs -m adclaw db migrate",
"dev:migrate:undo": "dotenv -e .env.development -- node scripts/run-python.cjs -m adclaw db migrate-undo",
"dev:migrate:undo:all": "dotenv -e .env.development -- node scripts/run-python.cjs -m adclaw db migrate-undo-all",
"dev:seed": "dotenv -e .env.development -- node scripts/run-python.cjs -m adclaw db seed",
"dev:import-json": "dotenv -e .env.development -- node scripts/run-python.cjs -m adclaw db import-json",
"dev:seed:undo": "dotenv -e .env.development -- node scripts/run-python.cjs -m adclaw db seed-undo",
"dev:reset": "npm run dev:migrate:undo:all && npm run dev:migrate && npm run dev:seed",
"test": "dotenv -e .env.testing -- node scripts/run-python.cjs -m pytest",
"test:serve": "dotenv -e .env.testing -- node scripts/run-python.cjs -m adclaw app --host 127.0.0.1 --port 8089",
"test:migrate": "dotenv -e .env.testing -- node scripts/run-python.cjs -m adclaw db migrate",
"test:seed": "dotenv -e .env.testing -- node scripts/run-python.cjs -m adclaw db seed",
"test:reset": "dotenv -e .env.testing -- node scripts/run-python.cjs -m adclaw db migrate-undo-all && dotenv -e .env.testing -- node scripts/run-python.cjs -m adclaw db migrate",
"prod": "cross-env MASKANX_ENV=production node scripts/run-python.cjs -m adclaw app --host 0.0.0.0 --port 8088",
"prod:migrate": "cross-env MASKANX_ENV=production node scripts/run-python.cjs -m adclaw db migrate",
"prod:seed": "cross-env MASKANX_ENV=production node scripts/run-python.cjs -m adclaw db seed",
"lint": "node scripts/run-python.cjs -m compileall -q src",
"secrets:dry-run": "node scripts/clear-secrets.cjs --include-env-files --dry-run",
"secrets:restore": "node scripts/restore-secrets-from-company.cjs",
"secrets:clear": "node scripts/clear-secrets.cjs",
"secrets:clear:all": "node scripts/clear-secrets.cjs --include-env-files",
"secrets:delete:all": "node scripts/clear-secrets.cjs --include-env-files",
"secrets:delete:all:no-backup": "node scripts/clear-secrets.cjs --include-env-files --no-backup",
"db:config": "node scripts/run-python.cjs -m adclaw db config",
"db:status": "node scripts/run-python.cjs -m adclaw db status",
"docker:up": "docker compose up --build",
"docker:down": "docker compose down",
"docker:reset": "docker compose down -v && docker compose up --build"
},
"dependencies": {
"dotenv": "^16.6.1"
},
"devDependencies": {
"cross-env": "^7.0.3",
"dotenv-cli": "^8.0.0"
}
}
pyproject.toml
+99
View File
@@ -0,0 +1,99 @@
[project]
name = "maskanx"
dynamic = ["version"]
description = "Multi-agent AI marketing team with 122 skills, multi-channel support, and shared memory"
readme = "README.md"
requires-python = ">=3.10,<3.14"
license = {text = "Proprietary"}
dependencies = [
"agentscope==1.0.18",
"agentscope-runtime==1.1.3",
"exceptiongroup>=1.2.0; python_version < '3.11'",
"uvicorn>=0.40.0",
"apscheduler>=3.11.2,<4",
"questionary>=2.1.1",
"reme-ai==0.3.0.5",
"python-dotenv>=1.0.0",
"python-socks>=2.5.3",
"onnxruntime<1.24",
"python-telegram-bot>=20.0",
"aiosqlite>=0.19.0",
"sqlite-vec>=0.1.1",
"google-genai>=1.0.0",
"Pillow>=10.0.0",
"psycopg[binary]>=3.2.0",
]
[tool.setuptools.dynamic]
version = {attr = "adclaw.__version__.__version__"}
[tool.setuptools]
packages = { find = { where = ["src"] } }
include-package-data = true
[tool.setuptools.package-data]
"adclaw" = [
"agents/md_files/**",
"agents/skills/**",
"tokenizer/**",
]
[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"
[project.scripts]
maskanx = "adclaw.cli.main:cli"
[project.optional-dependencies]
dev = [
"pytest>=8.3.5",
"pytest-asyncio>=0.23.0",
"pre-commit>=4.2.0",
"pytest-cov>=6.2.1",
]
local = [
"huggingface_hub>=0.20.0",
"sentence-transformers>=2.2.0",
]
llamacpp = [
"maskanx[local]",
"llama-cpp-python>=0.3.0",
]
mlx = [
"maskanx[local]",
"mlx-lm>=0.10.0",
]
ollama = [
"ollama>=0.6.1",
]
browser = [
"playwright>=1.49.0",
]
feishu = [
"lark-oapi>=1.5.3",
]
discord = [
"discord-py>=2.3",
]
dingtalk = [
"dingtalk-stream>=0.24.3",
]
desktop = [
"mss>=9.0.0",
]
# Meta: all optional messaging channels
channels = [
"maskanx[feishu,discord,dingtalk]",
]
# Meta: full install — everything
all = [
"maskanx[browser,channels,desktop]",
]
[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
markers = [
"slow: marks tests as slow (deselect with '-m \"not slow\"')",
]
railway.json
+14
View File
@@ -0,0 +1,14 @@
{
"$schema": "https://railway.app/railway.schema.json",
"build": {
"builder": "DOCKERFILE",
"dockerfilePath": "Dockerfile"
},
"deploy": {
"startCommand": "/entrypoint.sh",
"healthcheckPath": "/api/version",
"healthcheckTimeout": 300,
"restartPolicyType": "ON_FAILURE",
"restartPolicyMaxRetries": 10
}
}
scripts/README.md
+38
View File
@@ -0,0 +1,38 @@
# Backend Scripts
Run these from the `maskanx-backend` repository root.
## Build Python artifacts
```bash
bash scripts/wheel_build.sh
```
This builds only the backend wheel and source distribution into `dist/`.
The MaskanX frontend is built independently in `maskanx-frontend`.
## Build the backend image
```bash
bash scripts/docker_build.sh [IMAGE_TAG] [EXTRA_ARGS...]
```
The default tag is `maskanx-backend:latest`, and the script uses the root
`Dockerfile`.
Example:
```bash
bash scripts/docker_build.sh registry.example.com/maskanx-backend:v1 --no-cache
```
## Browser E2E
```bash
python scripts/host_ai_model_selection_e2e.py \
--base-url http://127.0.0.1:5173 \
--out artifacts/host-ai-model-selection-e2e
```
Run the frontend and backend first. The browser targets the separately deployed
frontend URL.
scripts/clear-secrets.cjs
+342
View File
@@ -0,0 +1,342 @@
#!/usr/bin/env node
"use strict";
const fs = require("fs");
const os = require("os");
const path = require("path");
const args = new Set(process.argv.slice(2));
const dryRun = args.has("--dry-run");
const noBackup = args.has("--no-backup");
const includeEnvFiles = args.has("--include-env-files");
const repoRoot = path.resolve(__dirname, "..");
const homeDir = os.homedir();
function expandHome(value) {
if (!value) return value;
if (value === "~") return homeDir;
if (value.startsWith("~/") || value.startsWith("~\\")) {
return path.join(homeDir, value.slice(2));
}
return value;
}
const workingDir = path.resolve(
expandHome(process.env.ADCLAW_WORKING_DIR || path.join(homeDir, ".adclaw")),
);
const secretDir = path.resolve(
expandHome(process.env.ADCLAW_SECRET_DIR || `${workingDir}.secret`),
);
const stamp = new Date()
.toISOString()
.replace(/[-:]/g, "")
.replace(/\..+$/, "")
.replace("T", "-");
const backupRoot = path.join(secretDir, "backups", stamp);
const secretNamePattern =
/(^|[_\-.])(api[_\-.]?key|token|secret|credential|authorization|bearer)($|[_\-.])/i;
const touched = [];
const skipped = [];
function exists(filePath) {
try {
return fs.statSync(filePath).isFile();
} catch {
return false;
}
}
function backupPathFor(filePath) {
const safeName = path
.resolve(filePath)
.replace(/^[A-Za-z]:/, "")
.replace(/[\\/]+/g, "__")
.replace(/^__/, "");
return path.join(backupRoot, safeName);
}
function backupFile(filePath) {
if (noBackup || dryRun || !exists(filePath)) return;
const target = backupPathFor(filePath);
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.copyFileSync(filePath, target);
}
function removeFile(filePath, reason) {
if (!exists(filePath)) {
skipped.push({ filePath, reason: "not found" });
return;
}
touched.push({ action: noBackup ? "deleted" : "backed up and removed", filePath, reason });
if (dryRun) return;
backupFile(filePath);
fs.unlinkSync(filePath);
}
function sanitizeValue(value, parentKey = "") {
if (Array.isArray(value)) {
let changed = false;
const next = value.map((item) => {
const result = sanitizeValue(item, parentKey);
changed = changed || result.changed;
return result.value;
});
return { value: next, changed };
}
if (value && typeof value === "object") {
let changed = false;
const next = {};
for (const [key, child] of Object.entries(value)) {
const keyLooksSecret = secretNamePattern.test(key);
if (keyLooksSecret) {
changed = true;
if (typeof child === "string") {
next[key] = "";
} else if (Array.isArray(child)) {
next[key] = [];
} else if (child && typeof child === "object") {
next[key] = {};
} else {
next[key] = null;
}
continue;
}
const result = sanitizeValue(child, key);
changed = changed || result.changed;
next[key] = result.value;
}
return { value: next, changed };
}
if (typeof value === "string" && secretNamePattern.test(parentKey) && value) {
return { value: "", changed: true };
}
return { value, changed: false };
}
function sanitizeJsonFile(filePath, reason) {
if (!exists(filePath)) {
skipped.push({ filePath, reason: "not found" });
return;
}
let parsed;
try {
parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
} catch (error) {
skipped.push({ filePath, reason: `invalid JSON: ${error.message}` });
return;
}
const result = sanitizeValue(parsed);
if (!result.changed) {
skipped.push({ filePath, reason: "no secret-like fields found" });
return;
}
touched.push({ action: "sanitized", filePath, reason });
if (dryRun) return;
backupFile(filePath);
fs.writeFileSync(filePath, `${JSON.stringify(result.value, null, 2)}\n`, "utf8");
}
function sanitizeEnvFile(filePath) {
if (!exists(filePath)) {
skipped.push({ filePath, reason: "not found" });
return;
}
const original = fs.readFileSync(filePath, "utf8");
const lines = original.split(/\r?\n/);
let changed = false;
const next = lines.map((line) => {
const match = line.match(/^(\s*export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
if (!match) return line;
const key = match[2];
if (!secretNamePattern.test(key)) return line;
changed = true;
return `${match[1] || ""}${key}=`;
});
if (!changed) {
skipped.push({ filePath, reason: "no API key/token/secret env vars found" });
return;
}
touched.push({ action: "sanitized", filePath, reason: "env file API key/token/secret lines" });
if (dryRun) return;
backupFile(filePath);
fs.writeFileSync(filePath, next.join(os.EOL), "utf8");
}
function listCompanyDirs() {
const companiesDir = path.join(workingDir, "companies");
try {
return fs
.readdirSync(companiesDir, { withFileTypes: true })
.filter((entry) => entry.isDirectory())
.map((entry) => path.join(companiesDir, entry.name));
} catch {
return [];
}
}
function clearRuntimeSecrets() {
const filesToRemove = [
path.join(secretDir, "providers.json"),
path.join(secretDir, "envs.json"),
path.join(workingDir, "providers.json"),
path.join(workingDir, "envs.json"),
path.join(workingDir, ".secret", "providers.json"),
path.join(workingDir, ".secret", "envs.json"),
path.join(homeDir, ".linkedin-mcp", "tokens_default.json"),
path.join(homeDir, ".linkedin-mcp", "users.json"),
];
for (const companyDir of listCompanyDirs()) {
filesToRemove.push(
path.join(companyDir, "providers.json"),
path.join(companyDir, "envs.json"),
path.join(companyDir, "linkedin-mcp", "tokens_default.json"),
path.join(companyDir, "linkedin-mcp", "users.json"),
);
sanitizeJsonFile(
path.join(companyDir, "config.json"),
"company MCP/API config secret-like values",
);
}
sanitizeJsonFile(path.join(workingDir, "config.json"), "MCP/API config secret-like values");
for (const filePath of filesToRemove) {
removeFile(filePath, "runtime/provider/env/OAuth secret store");
}
}
function clearEnvFiles() {
for (const name of [
".env",
".env.local",
".env.development",
".env.testing",
".env.production",
]) {
sanitizeEnvFile(path.join(repoRoot, name));
}
}
if (noBackup && !dryRun) {
console.warn(
"WARNING: --no-backup is set. Cleared credentials cannot be recovered.",
);
}
if (!dryRun) {
console.warn(
"Stop MaskanX before clearing: a running app can rewrite its config from " +
"memory and restore the secrets this script removes.",
);
}
clearRuntimeSecrets();
if (includeEnvFiles) {
clearEnvFiles();
}
console.log("");
console.log(`MaskanX secret cleanup ${dryRun ? "dry run" : "complete"}.`);
console.log(`Working dir: ${workingDir}`);
console.log(`Secret dir: ${secretDir}`);
if (!noBackup) {
console.log(`Backups: ${dryRun ? "(dry run only)" : backupRoot}`);
}
console.log("");
if (touched.length) {
console.log("Changed:");
for (const item of touched) {
console.log(`- ${item.action}: ${item.filePath} (${item.reason})`);
}
} else {
console.log("Changed: none");
}
console.log("");
console.log("Skipped:");
for (const item of skipped) {
console.log(`- ${item.filePath} (${item.reason})`);
}
if (!includeEnvFiles) {
console.log("");
console.log("Tip: run `npm run secrets:clear:all` to also blank API key/token/secret lines in .env files.");
}
// ---------------------------------------------------------------------------
// Verification pass.
//
// Clearing is not trustworthy on its own: if the MaskanX app is running while
// this script executes, it can rewrite config.json / providers.json from its
// in-memory state and silently restore the very values we just removed. Re-read
// the files afterwards and fail loudly when anything secret-looking survives,
// so "secrets cleared" can never be reported when it is not true.
// ---------------------------------------------------------------------------
function collectRemainingSecrets(value, keyPath, found) {
if (Array.isArray(value)) {
value.forEach((item, i) => collectRemainingSecrets(item, `${keyPath}[${i}]`, found));
return found;
}
if (value && typeof value === "object") {
for (const [key, child] of Object.entries(value)) {
const next = keyPath ? `${keyPath}.${key}` : key;
if (secretNamePattern.test(key) && typeof child === "string" && child.trim()) {
found.push(next);
continue;
}
collectRemainingSecrets(child, next, found);
}
}
return found;
}
function verifyJsonFile(filePath) {
if (!exists(filePath)) return [];
try {
const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
return collectRemainingSecrets(parsed, "", []).map((k) => `${filePath} -> ${k}`);
} catch {
return [];
}
}
if (!dryRun) {
const leftovers = [
...verifyJsonFile(path.join(workingDir, "config.json")),
...verifyJsonFile(path.join(secretDir, "providers.json")),
...verifyJsonFile(path.join(secretDir, "envs.json")),
];
for (const companyDir of listCompanyDirs()) {
leftovers.push(...verifyJsonFile(path.join(companyDir, "config.json")));
}
console.log("");
if (leftovers.length) {
console.error("VERIFICATION FAILED - secrets are still present:");
for (const item of leftovers) console.error(`- ${item}`);
console.error("");
console.error(
"This usually means MaskanX was running and rewrote its config from memory.",
);
console.error("Stop the app (and any `npm run local`/`npm start`), then re-run.");
process.exitCode = 1;
} else {
console.log("Verification passed: no secret-like values remain.");
}
}
scripts/docker_build.sh
+30
View File
@@ -0,0 +1,30 @@
#!/usr/bin/env bash
# Build the independent MaskanX backend image.
# Run from repo root: bash scripts/docker_build.sh [IMAGE_TAG] [EXTRA_ARGS...]
# Example: bash scripts/docker_build.sh maskanx:latest
# bash scripts/docker_build.sh myreg/maskanx:v1 --no-cache
#
# By default the Docker image excludes imessage and discord channels.
# Override via:
# MASKANX_ENABLED_CHANNELS=imessage,discord,dingtalk,feishu,qq,console \
# bash scripts/docker_build.sh
set -e
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"
DOCKERFILE="${DOCKERFILE:-$REPO_ROOT/Dockerfile}"
TAG="${1:-maskanx-backend:latest}"
shift || true
# Channels to include in the image (default: exclude imessage & discord).
ENABLED_CHANNELS="${MASKANX_ENABLED_CHANNELS:-dingtalk,feishu,qq,console}"
echo "[docker_build] Building image: $TAG (Dockerfile: $DOCKERFILE)"
docker build -f "$DOCKERFILE" \
--build-arg MASKANX_ENABLED_CHANNELS="$ENABLED_CHANNELS" \
-t "$TAG" "$@" .
echo "[docker_build] Done."
echo "[docker_build] MaskanX app port: 8088 (default). Override with -e MASKANX_PORT=<port>."
echo "[docker_build] Run: docker run -p 8088:8088 $TAG"
echo "[docker_build] Or: docker run -e MASKANX_PORT=3000 -p 3000:3000 $TAG"
scripts/finalize-branded-image.py
+150
View File
@@ -0,0 +1,150 @@
#!/usr/bin/env python
"""Finalize a generated social image with exact brand formatting.
This script keeps the AI-generated image and the company logo separate:
generate the base image first, then overlay the real logo here so the brand mark
does not get distorted by the image model.
"""
from __future__ import annotations
import argparse
from pathlib import Path
try:
from PIL import Image, ImageDraw, ImageOps
except ModuleNotFoundError as exc: # pragma: no cover - friendly CLI error
raise SystemExit(
"Pillow is required. Install it with: "
"python -m pip install Pillow"
) from exc
def _open_rgba(path: Path) -> Image.Image:
return Image.open(path).convert("RGBA")
def _fit_cover(img: Image.Image, size: tuple[int, int]) -> Image.Image:
target_w, target_h = size
src_w, src_h = img.size
scale = max(target_w / src_w, target_h / src_h)
resized = img.resize(
(round(src_w * scale), round(src_h * scale)),
Image.Resampling.LANCZOS,
)
left = (resized.width - target_w) // 2
top = (resized.height - target_h) // 2
return resized.crop((left, top, left + target_w, top + target_h))
def _fit_contain(img: Image.Image, size: tuple[int, int]) -> Image.Image:
target_w, target_h = size
src_w, src_h = img.size
scale = min(target_w / src_w, target_h / src_h)
resized = img.resize(
(round(src_w * scale), round(src_h * scale)),
Image.Resampling.LANCZOS,
)
canvas = Image.new("RGBA", size, (255, 255, 255, 255))
x = (target_w - resized.width) // 2
y = (target_h - resized.height) // 2
canvas.alpha_composite(resized, (x, y))
return canvas
def _parse_size(value: str) -> tuple[int, int]:
try:
w_text, h_text = value.lower().split("x", 1)
width = int(w_text.strip())
height = int(h_text.strip())
except Exception as exc:
raise argparse.ArgumentTypeError(
"Size must be formatted like 1200x628"
) from exc
if width < 300 or height < 300:
raise argparse.ArgumentTypeError("Size must be at least 300x300")
return width, height
def finalize_image(
source: Path,
logo: Path,
output: Path,
size: tuple[int, int],
fit: str,
logo_width_pct: float,
margin_pct: float,
plate: bool,
) -> None:
base = _open_rgba(source)
canvas = _fit_cover(base, size) if fit == "cover" else _fit_contain(base, size)
logo_img = _open_rgba(logo)
max_logo_w = round(size[0] * logo_width_pct / 100)
max_logo_h = round(size[1] * 0.12)
logo_img.thumbnail((max_logo_w, max_logo_h), Image.Resampling.LANCZOS)
margin = round(size[0] * margin_pct / 100)
plate_pad_x = max(12, round(logo_img.width * 0.24))
plate_pad_y = max(8, round(logo_img.height * 0.22))
logo_x = size[0] - margin - logo_img.width
logo_y = size[1] - margin - logo_img.height
if plate:
draw = ImageDraw.Draw(canvas)
rect = (
logo_x - plate_pad_x,
logo_y - plate_pad_y,
logo_x + logo_img.width + plate_pad_x,
logo_y + logo_img.height + plate_pad_y,
)
radius = max(10, round(min(logo_img.size) * 0.22))
draw.rounded_rectangle(
rect,
radius=radius,
fill=(255, 255, 255, 225),
outline=(229, 231, 235, 160),
width=1,
)
canvas.alpha_composite(logo_img, (logo_x, logo_y))
output.parent.mkdir(parents=True, exist_ok=True)
rgb = ImageOps.exif_transpose(canvas).convert("RGB")
rgb.save(output, quality=95, optimize=True)
def main() -> None:
parser = argparse.ArgumentParser(
description="Resize a generated image and overlay the company logo.",
)
parser.add_argument("--source", required=True, type=Path)
parser.add_argument("--logo", required=True, type=Path)
parser.add_argument("--out", required=True, type=Path)
parser.add_argument("--size", type=_parse_size, default=(1200, 628))
parser.add_argument("--fit", choices=("cover", "contain"), default="cover")
parser.add_argument("--logo-width-pct", type=float, default=12.0)
parser.add_argument("--margin-pct", type=float, default=3.0)
parser.add_argument(
"--no-plate",
action="store_true",
help="Do not draw a subtle white plate behind the logo.",
)
args = parser.parse_args()
finalize_image(
source=args.source,
logo=args.logo,
output=args.out,
size=args.size,
fit=args.fit,
logo_width_pct=args.logo_width_pct,
margin_pct=args.margin_pct,
plate=not args.no_plate,
)
print(f"Saved branded image: {args.out}")
if __name__ == "__main__":
main()
scripts/host_ai_model_selection_e2e.py
+185
View File
@@ -0,0 +1,185 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Browser E2E for MaskanX AI model selection and chat routing.
Prerequisites:
- MaskanX app is running and reachable via --base-url.
- The app has an maskanx-host-ai provider with a test key/base URL.
- playwright is installed; run `python -m playwright install chromium` once.
"""
from __future__ import annotations
import argparse
import asyncio
import json
import re
import time
from pathlib import Path
from playwright.async_api import Page, async_playwright
DEFAULT_BASE_URL = "http://127.0.0.1:8088"
DEFAULT_OUT = Path("artifacts/host-ai-model-selection-e2e")
LLAMA = "@cf/meta/llama-3.1-8b-instruct-fp8-fast"
QWEN = "@cf/qwen/qwen3-30b-a3b-fp8"
GEMMA = "@cf/google/gemma-4-26b-a4b-it"
FIND_TEXT_ELEMENT = """
(text) => {
const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
let node;
while ((node = walker.nextNode())) {
const ownText = Array.from(node.childNodes)
.filter((child) => child.nodeType === Node.TEXT_NODE)
.map((child) => child.textContent || "")
.join("");
if (ownText.includes(text)) {
const rect = node.getBoundingClientRect();
return {
text: node.innerText,
x: rect.x,
y: rect.y,
width: rect.width,
height: rect.height,
};
}
}
return null;
}
"""
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Verify MaskanX AI model selection and chat routing.",
)
parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
parser.add_argument("--out", type=Path, default=DEFAULT_OUT)
parser.add_argument("--initial-model", default=LLAMA)
parser.add_argument("--switch-model", default=QWEN)
parser.add_argument("--chat-model", default=GEMMA)
parser.add_argument("--headed", action="store_true")
return parser.parse_args()
async def click_text(page: Page, text: str) -> None:
found = await page.evaluate(FIND_TEXT_ELEMENT, text)
if not found:
raise AssertionError(f"Text not found: {text}")
await page.mouse.click(
found["x"] + min(24, max(4, found["width"] / 2)),
found["y"] + found["height"] / 2,
)
async def assert_usage_hint(page: Page) -> str:
body = await page.locator("body").inner_text()
match = re.search(
r"\d+\s*/\s*\d+\s+included MaskanX AI messages left this period\.",
body,
)
if not match:
raise AssertionError("MaskanX AI included-message balance was not visible")
return match.group(0)
async def run() -> dict[str, object]:
args = parse_args()
args.out.mkdir(parents=True, exist_ok=True)
results: dict[str, object] = {}
async with async_playwright() as pw:
browser = await pw.chromium.launch(headless=not args.headed)
page = await browser.new_page(viewport={"width": 1440, "height": 1400})
reset_response = await page.request.put(
f"{args.base_url}/api/models/active",
data={"provider_id": "maskanx-host-ai", "model": args.initial_model},
)
if not reset_response.ok:
raise AssertionError(
f"Failed to reset active model: {reset_response.status}",
)
await page.goto(f"{args.base_url}/models", wait_until="domcontentloaded")
await page.wait_for_timeout(2500)
initial_text = await page.locator("body").inner_text()
if "MaskanX AI" not in initial_text:
raise AssertionError("MaskanX AI provider is not visible")
if f"Active: maskanx-host-ai / {args.initial_model}" not in initial_text:
raise AssertionError("Initial MaskanX AI model is not active")
if "4 models" not in initial_text:
raise AssertionError("MaskanX AI model catalog count is not visible")
usage_hint = await assert_usage_hint(page)
provider_cards = await page.locator(
'div[class*="providerCards"] > div[class*="providerCard"]',
).all_inner_texts()
if not provider_cards:
raise AssertionError("Provider cards were not rendered")
if "MaskanX AI" not in provider_cards[0]:
raise AssertionError(f"First provider card is not MaskanX AI: {provider_cards[0]}")
results["first_provider_card"] = provider_cards[0].splitlines()[0]
results["usage_hint"] = usage_hint
await page.screenshot(path=str(args.out / "models-before-switch.png"), full_page=True)
await click_text(page, "Fast default")
await page.wait_for_timeout(500)
await click_text(page, "Balanced reasoning")
await page.wait_for_timeout(500)
switch_text = await page.locator("body").inner_text()
if args.switch_model not in switch_text:
raise AssertionError("Switch model was not selected")
await assert_usage_hint(page)
await page.screenshot(path=str(args.out / "models-switch-selected.png"), full_page=True)
await click_text(page, "Balanced reasoning")
await page.wait_for_timeout(500)
await click_text(page, "Creative quality")
await page.wait_for_timeout(500)
chat_model_text = await page.locator("body").inner_text()
if args.chat_model not in chat_model_text:
raise AssertionError("Chat model was not selected")
await assert_usage_hint(page)
await page.screenshot(path=str(args.out / "models-chat-model-selected.png"), full_page=True)
await click_text(page, "Save")
await page.wait_for_timeout(1500)
active_response = await page.request.get(f"{args.base_url}/api/models/active")
active_payload = await active_response.json()
active_llm = active_payload.get("active_llm", {})
if active_llm.get("provider_id") != "maskanx-host-ai":
raise AssertionError(f"Unexpected active provider: {active_llm}")
if active_llm.get("model") != args.chat_model:
raise AssertionError(f"Unexpected active model: {active_llm}")
results["active_model_after_save"] = active_llm["model"]
await page.goto(f"{args.base_url}/chat", wait_until="domcontentloaded")
await page.wait_for_timeout(1500)
prompt = "Reply in under 20 words and include E2E_OK."
await page.locator("textarea.maskanx-sender-input").fill(prompt)
started = time.perf_counter()
await page.keyboard.press("Enter")
await page.wait_for_function(
"(model) => document.body.innerText.includes('E2E_OK') && document.body.innerText.includes(model)",
arg=args.chat_model,
timeout=30000,
)
elapsed_ms = round((time.perf_counter() - started) * 1000)
chat_text = await page.locator("body").inner_text()
if "E2E_OK" not in chat_text or args.chat_model not in chat_text:
raise AssertionError("Chat did not respond through the selected model")
results["chat_elapsed_ms"] = elapsed_ms
await page.screenshot(path=str(args.out / "chat-selected-model-response.png"), full_page=True)
await browser.close()
results_path = args.out / "result.json"
results_path.write_text(json.dumps(results, indent=2), encoding="utf-8")
print(json.dumps(results, indent=2))
return results
if __name__ == "__main__":
asyncio.run(run())
scripts/restore-secrets-from-company.cjs
+161
View File
@@ -0,0 +1,161 @@
#!/usr/bin/env node
"use strict";
/**
* Restore MaskanX credentials from an intact company store.
*
* `clear-secrets.cjs` wipes the active company's stores and the shared secret
* directory, but a per-company copy can survive (for example when only one of
* several companies was active at the time). This script copies the credential
* files from a healthy company back into the active company and the shared
* secret directory.
*
* Credential files are copied wholesale. config.json is patched surgically -
* only MCP env values and enabled flags are taken from the source - so
* company-specific settings are preserved.
*
* Usage:
* node scripts/restore-secrets-from-company.cjs --from default [--to maskanx]
* node scripts/restore-secrets-from-company.cjs --from default --dry-run
*/
const fs = require("fs");
const os = require("os");
const path = require("path");
const argv = process.argv.slice(2);
const flag = (name, fallback = null) => {
const i = argv.indexOf(`--${name}`);
return i !== -1 && argv[i + 1] ? argv[i + 1] : fallback;
};
const dryRun = argv.includes("--dry-run");
const homeDir = os.homedir();
const workingDir = path.resolve(
process.env.ADCLAW_WORKING_DIR || path.join(homeDir, ".adclaw"),
);
const secretDir = path.resolve(
process.env.ADCLAW_SECRET_DIR || `${workingDir}.secret`,
);
const companiesDir = path.join(workingDir, "companies");
function readJson(file) {
return JSON.parse(fs.readFileSync(file, "utf8"));
}
function activeCompanyId() {
try {
return readJson(path.join(companiesDir, "index.json")).active_company_id;
} catch {
return null;
}
}
const from = flag("from");
const to = flag("to", activeCompanyId());
if (!from) {
console.error("Missing --from <companyId>. Example: --from default");
process.exit(2);
}
if (!to) {
console.error("Could not determine the target company; pass --to <companyId>.");
process.exit(2);
}
const srcDir = path.join(companiesDir, from);
const dstDir = path.join(companiesDir, to);
if (!fs.existsSync(srcDir)) {
console.error(`Source company not found: ${srcDir}`);
process.exit(2);
}
const stamp = new Date().toISOString().replace(/[:.]/g, "").replace("T", "-").slice(0, 15);
const backupRoot = path.join(secretDir, "restore-backups", stamp);
function backup(file) {
if (dryRun || !fs.existsSync(file)) return;
const target = path.join(backupRoot, path.resolve(file).replace(/[:\\/]/g, "_"));
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.copyFileSync(file, target);
}
function copyFile(src, dst, label) {
if (!fs.existsSync(src)) {
console.log(` skip ${label}: source missing`);
return;
}
console.log(` ${dryRun ? "would restore" : "restored"} ${label}`);
if (dryRun) return;
backup(dst);
fs.mkdirSync(path.dirname(dst), { recursive: true });
fs.copyFileSync(src, dst);
}
console.log(`Restoring credentials from company "${from}" to "${to}".`);
if (!dryRun) console.log(`Backups: ${backupRoot}`);
console.log("");
// ---- credential stores --------------------------------------------------
for (const name of ["envs.json", "providers.json"]) {
copyFile(path.join(srcDir, name), path.join(dstDir, name), `${to}/${name}`);
copyFile(path.join(srcDir, name), path.join(secretDir, name), `secret-dir/${name}`);
}
// ---- LinkedIn OAuth -----------------------------------------------------
// The server reads tokens from ~/.linkedin-mcp (see _linkedin_dir() in
// app/routers/mcp.py), so the home-level copy is the one that actually
// restores authentication. The per-company copy is kept in sync as well.
for (const name of ["tokens_default.json", "users.json"]) {
const src = path.join(srcDir, "linkedin-mcp", name);
copyFile(src, path.join(dstDir, "linkedin-mcp", name), `${to}/linkedin-mcp/${name}`);
copyFile(src, path.join(homeDir, ".linkedin-mcp", name), `~/.linkedin-mcp/${name}`);
}
// ---- config.json: patch MCP env values and enabled flags only -----------
function patchConfig(targetFile) {
const srcCfg = path.join(srcDir, "config.json");
if (!fs.existsSync(srcCfg) || !fs.existsSync(targetFile)) {
console.log(` skip config patch: ${targetFile} or source missing`);
return;
}
const src = readJson(srcCfg);
const dst = readJson(targetFile);
const srcClients = (src.mcp && src.mcp.clients) || {};
const dstClients = (dst.mcp && dst.mcp.clients) || {};
const restoredEnv = [];
const reEnabled = [];
for (const [name, srcClient] of Object.entries(srcClients)) {
const dstClient = dstClients[name];
if (!dstClient || !srcClient) continue;
for (const [k, v] of Object.entries(srcClient.env || {})) {
const current = (dstClient.env || {})[k];
if (typeof v === "string" && v.trim() && (!current || !String(current).trim())) {
dstClient.env = dstClient.env || {};
dstClient.env[k] = v;
restoredEnv.push(`${name}.${k}`);
}
}
if (srcClient.enabled && !dstClient.enabled) {
dstClient.enabled = true;
reEnabled.push(name);
}
}
console.log(` config ${path.basename(path.dirname(targetFile))}: ` +
`${restoredEnv.length} env value(s), ${reEnabled.length} client(s) re-enabled`);
for (const e of restoredEnv) console.log(` + ${e}`);
for (const e of reEnabled) console.log(` * enabled ${e}`);
if (dryRun) return;
backup(targetFile);
fs.writeFileSync(targetFile, `${JSON.stringify(dst, null, 2)}\n`, "utf8");
}
patchConfig(path.join(dstDir, "config.json"));
patchConfig(path.join(workingDir, "config.json"));
console.log("");
console.log(dryRun ? "Dry run complete; nothing was written." : "Restore complete.");
console.log("Stop MaskanX before running this, then start it again afterwards.");
scripts/run-python.cjs
+51
View File
@@ -0,0 +1,51 @@
#!/usr/bin/env node
const { existsSync } = require("node:fs");
const { join } = require("node:path");
const { spawnSync } = require("node:child_process");
const isWindows = process.platform === "win32";
const candidates = [];
if (process.env.PYTHON) {
candidates.push(process.env.PYTHON);
}
candidates.push(
isWindows
? join(process.cwd(), ".venv311", "Scripts", "python.exe")
: join(process.cwd(), ".venv311", "bin", "python"),
isWindows
? join(process.cwd(), ".venv", "Scripts", "python.exe")
: join(process.cwd(), ".venv", "bin", "python"),
isWindows
? join(process.cwd(), "..", ".venv311", "Scripts", "python.exe")
: join(process.cwd(), "..", ".venv311", "bin", "python"),
"python3",
"python",
"py",
);
const args = process.argv.slice(2);
for (const candidate of candidates) {
const isPath = candidate.includes("/") || candidate.includes("\\");
if (isPath && !existsSync(candidate)) {
continue;
}
const result = spawnSync(candidate, args, {
stdio: "inherit",
shell: false,
env: process.env,
});
if (result.error) {
if (result.error.code === "ENOENT") {
continue;
}
console.error(result.error.message);
process.exit(1);
}
process.exit(result.status ?? 0);
}
console.error("No Python executable found. Set PYTHON or create .venv311.");
process.exit(1);
scripts/start-linkedin-oauth.ps1
+84
View File
@@ -0,0 +1,84 @@
param(
[string]$UserId = "default"
)
$ErrorActionPreference = "Stop"
$configPath = Join-Path $env:USERPROFILE ".adclaw\config.json"
if (-not (Test-Path -LiteralPath $configPath)) {
throw "MaskanX config not found at $configPath"
}
$config = Get-Content -LiteralPath $configPath -Raw | ConvertFrom-Json
$linkedin = $config.mcp.clients.linkedin
if (-not $linkedin) {
throw "LinkedIn MCP config was not found in $configPath"
}
$env:LINKEDIN_CLIENT_ID = $linkedin.env.LINKEDIN_CLIENT_ID
$env:LINKEDIN_CLIENT_SECRET = $linkedin.env.LINKEDIN_CLIENT_SECRET
$env:LINKEDIN_REDIRECT_URI = "http://localhost:44002/auth/linkedin/callback"
if (-not $env:LINKEDIN_CLIENT_ID -or -not $env:LINKEDIN_CLIENT_SECRET) {
throw "LINKEDIN_CLIENT_ID or LINKEDIN_CLIENT_SECRET is missing in MaskanX config."
}
$helper = Get-ChildItem -Path (Join-Path $env:LOCALAPPDATA "npm-cache\_npx") `
-Recurse `
-Filter "auth-helper.js" `
-ErrorAction SilentlyContinue |
Where-Object { $_.FullName -like "*linkedin-mcp-server*bin*" } |
Select-Object -First 1
if (-not $helper) {
throw "linkedin-mcp-server auth-helper.js was not found. Start MaskanX once so npx installs linkedin-mcp-server, then retry."
}
$postingScope = "w_member_social"
$packageRoot = Split-Path -Parent (Split-Path -Parent $helper.FullName)
$authJsPath = Join-Path $packageRoot "dist\utils\linkedin-auth.js"
if (Test-Path -LiteralPath $authJsPath) {
$authJs = Get-Content -LiteralPath $authJsPath -Raw
if ($authJs -notmatch [regex]::Escape($postingScope)) {
$patchedAuthJs = $authJs -replace "('email')(\s*\r?\n\s*)\]", "`$1,`$2 '$postingScope'`r`n]"
Set-Content -LiteralPath $authJsPath -Value $patchedAuthJs -Encoding UTF8
Write-Host "Patched LinkedIn MCP OAuth scopes to include $postingScope." -ForegroundColor Green
}
}
$linkedinDir = Join-Path $env:USERPROFILE ".linkedin-mcp"
$usersPath = Join-Path $linkedinDir "users.json"
if (Test-Path -LiteralPath $usersPath) {
$users = Get-Content -LiteralPath $usersPath -Raw | ConvertFrom-Json
$userEntry = $users.$UserId
if ($userEntry -and ($userEntry.scopes -notcontains $postingScope)) {
$userEntry.scopes = @($userEntry.scopes) + $postingScope
$users | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $usersPath -Encoding UTF8
Write-Host "Updated saved LinkedIn user scopes to include $postingScope." -ForegroundColor Green
}
}
$tokensPath = Join-Path $linkedinDir "tokens_$UserId.json"
if (Test-Path -LiteralPath $tokensPath) {
$backupPath = "$tokensPath.before-posting-scope.bak"
Copy-Item -LiteralPath $tokensPath -Destination $backupPath -Force
Remove-Item -LiteralPath $tokensPath -Force
Write-Host "Cleared old LinkedIn token so OAuth can request posting permission." -ForegroundColor Green
}
Write-Host ""
Write-Host "LinkedIn OAuth setup starting..." -ForegroundColor Cyan
Write-Host ""
Write-Host "Before continuing, make sure LinkedIn Developer Portal has this exact redirect URL:" -ForegroundColor Yellow
Write-Host "http://localhost:44002/auth/linkedin/callback"
Write-Host ""
Write-Host "A LinkedIn URL will be printed below. If the browser does not open, copy that URL manually."
Write-Host "After approving LinkedIn, wait for this script to finish."
Write-Host ""
node $helper.FullName setup --user-id $UserId --debug
Write-Host ""
Write-Host "Checking LinkedIn auth status..." -ForegroundColor Cyan
node $helper.FullName status --user-id $UserId
scripts/wheel_build.sh
+14
View File
@@ -0,0 +1,14 @@
#!/usr/bin/env bash
# Build the independently deployable MaskanX backend package.
# Run from repo root: bash scripts/wheel_build.sh
set -e
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"
echo "[wheel_build] Building wheel + sdist..."
python3 -m pip install --quiet build
rm -rf dist/*
python3 -m build --outdir dist .
echo "[wheel_build] Done. Wheel(s) in: $REPO_ROOT/dist/"
src/adclaw/__init__.py
+32
View File
@@ -0,0 +1,32 @@
# -*- coding: utf-8 -*-
import logging
import os
import time
from .utils.logging import setup_logger
# Fallback before we can safely read canonical constant definitions.
LOG_LEVEL_ENV = "ADCLAW_LOG_LEVEL"
_bootstrap_err: Exception | None = None
try:
# Load persisted env vars before importing modules that read env-backed
# constants at import time (e.g., WORKING_DIR).
from .envs import load_envs_into_environ
load_envs_into_environ()
except Exception as exc:
# Best effort: package import should not fail if env bootstrap fails.
_bootstrap_err = exc
_t0 = time.perf_counter()
setup_logger(os.environ.get(LOG_LEVEL_ENV, "info"))
if _bootstrap_err is not None:
logging.getLogger(__name__).warning(
"adclaw: failed to load persisted envs on init: %s",
_bootstrap_err,
)
logging.getLogger(__name__).debug(
"%.3fs package init",
time.perf_counter() - _t0,
)
src/adclaw/__main__.py
+6
View File
@@ -0,0 +1,6 @@
# -*- coding: utf-8 -*-
"""Allow running MaskanX via ``python -m adclaw``."""
from .cli.main import cli
if __name__ == "__main__":
cli() # pylint: disable=no-value-for-parameter
src/adclaw/__version__.py
+2
View File
@@ -0,0 +1,2 @@
# -*- coding: utf-8 -*-
__version__ = "1.0.32"
src/adclaw/agents/__init__.py
+34
View File
@@ -0,0 +1,34 @@
# -*- coding: utf-8 -*-
"""MaskanX Agents Module.
This module provides the main agent implementation and supporting utilities
for building AI agents with tools, skills, and memory management.
Public API:
- MaskanXAgent: Main agent class
- create_model_and_formatter: Factory for creating models and formatters
Example:
>>> from adclaw.agents import MaskanXAgent, create_model_and_formatter
>>> agent = MaskanXAgent()
>>> # Or with custom model
>>> model, formatter = create_model_and_formatter()
"""
# MaskanXAgent is lazy-loaded so that importing agents.skills_manager (e.g.
# from CLI init_cmd/skills_cmd) does not pull react_agent, agentscope, tools.
# pylint: disable=undefined-all-variable
__all__ = ["MaskanXAgent", "create_model_and_formatter"]
def __getattr__(name: str):
"""Lazy load heavy imports."""
if name == "MaskanXAgent":
from .react_agent import MaskanXAgent
return MaskanXAgent
if name == "create_model_and_formatter":
from .model_factory import create_model_and_formatter
return create_model_and_formatter
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
src/adclaw/agents/command_handler.py
+220
View File
@@ -0,0 +1,220 @@
# -*- coding: utf-8 -*-
"""Agent command handler for system commands.
This module handles system commands like /compact, /new, /clear, etc.
"""
import logging
from typing import TYPE_CHECKING, Any
from agentscope.agent._react_agent import _MemoryMark
from agentscope.message import Msg, TextBlock
if TYPE_CHECKING:
from .memory import MemoryManager
MaskanXInMemoryMemory = Any
logger = logging.getLogger(__name__)
class CommandHandler:
"""Handler for agent system commands."""
# Supported system commands
SYSTEM_COMMANDS = frozenset(
{
"compact",
"new",
"clear",
"history",
"compact_str",
"await_summary",
},
)
def __init__(
self,
agent_name: str,
memory: "MaskanXInMemoryMemory",
memory_manager: "MemoryManager | None" = None,
enable_memory_manager: bool = True,
):
"""Initialize command handler.
Args:
agent_name: Name of the agent for message creation
memory: Agent's MaskanXInMemoryMemory instance
memory_manager: Optional memory manager instance
enable_memory_manager: Whether memory manager is enabled
"""
self.agent_name = agent_name
self.memory = memory
self.memory_manager = memory_manager
self._enable_memory_manager = enable_memory_manager
def is_command(self, query: str | None) -> bool:
"""Check if the query is a system command.
Args:
query: User query string
Returns:
True if query is a system command
"""
if not isinstance(query, str) or not query.startswith("/"):
return False
return query.strip().lstrip("/") in self.SYSTEM_COMMANDS
async def _make_system_msg(self, text: str) -> Msg:
"""Create a system response message.
Args:
text: Message text content
Returns:
System message
"""
return Msg(
name=self.agent_name,
role="assistant",
content=[TextBlock(type="text", text=text)],
)
def _has_memory_manager(self) -> bool:
"""Check if memory manager is available."""
return self._enable_memory_manager and self.memory_manager is not None
async def _process_compact(self, messages: list[Msg]) -> Msg:
"""Process /compact command."""
if not messages:
return await self._make_system_msg(
"**No messages to compact.**\n\n"
"- Current memory is empty\n"
"- No action taken",
)
if not self._has_memory_manager():
return await self._make_system_msg(
"**Memory Manager Disabled**\n\n"
"- Memory compaction is not available\n"
"- Enable memory manager to use this feature",
)
self.memory_manager.add_async_summary_task(messages=messages)
compact_content = await self.memory_manager.compact_memory(
messages=messages,
previous_summary=self.memory.get_compressed_summary(),
)
await self.memory.update_compressed_summary(compact_content)
updated_count = await self.memory.mark_messages_compressed(messages)
logger.info(
f"Marked {updated_count} messages as compacted "
f"with:\n{compact_content}",
)
return await self._make_system_msg(
f"**Compact Complete!**\n\n"
f"- Messages compacted: {updated_count}\n"
f"**Compressed Summary:**\n{compact_content}\n"
f"- Summary task started in background\n",
)
async def _process_new(self, messages: list[Msg]) -> Msg:
"""Process /new command."""
if not messages:
self.memory.clear_compressed_summary()
return await self._make_system_msg(
"**No messages to summarize.**\n\n"
"- Current memory is empty\n"
"- Compressed summary is clear\n"
"- No action taken",
)
if not self._has_memory_manager():
return await self._make_system_msg(
"**Memory Manager Disabled**\n\n"
"- Cannot start new conversation with summary\n"
"- Enable memory manager to use this feature",
)
self.memory_manager.add_async_summary_task(messages=messages)
self.memory.clear_compressed_summary()
updated_count = await self.memory.mark_messages_compressed(messages)
logger.info(f"Marked {updated_count} messages as compacted")
return await self._make_system_msg(
"**New Conversation Started!**\n\n"
"- Summary task started in background\n"
"- Ready for new conversation",
)
async def _process_clear(self, _messages: list[Msg]) -> Msg:
"""Process /clear command."""
self.memory.clear_content()
self.memory.clear_compressed_summary()
return await self._make_system_msg(
"**History Cleared!**\n\n"
"- Compressed summary reset\n"
"- Memory is now empty",
)
async def _process_compact_str(self, _messages: list[Msg]) -> Msg:
"""Process /compact_str command to show compressed summary."""
summary = self.memory.get_compressed_summary()
if not summary:
return await self._make_system_msg(
"**No Compressed Summary**\n\n"
"- No summary has been generated yet\n"
"- Use /compact or wait for auto-compaction",
)
return await self._make_system_msg(
f"**Compressed Summary**\n\n{summary}",
)
async def _process_history(self, _messages: list[Msg]) -> Msg:
"""Process /history command."""
history_str = await self.memory.get_history_str()
return await self._make_system_msg(history_str)
async def _process_await_summary(self, _messages: list[Msg]) -> Msg:
"""Process /await_summary command to wait for all summary tasks."""
if not self._has_memory_manager():
return await self._make_system_msg(
"**Memory Manager Disabled**\n\n"
"- Cannot await summary tasks\n"
"- Enable memory manager to use this feature",
)
task_count = len(self.memory_manager.summary_tasks)
if task_count == 0:
return await self._make_system_msg(
"**No Summary Tasks**\n\n"
"- No pending summary tasks to wait for",
)
result = await self.memory_manager.await_summary_tasks()
return await self._make_system_msg(
f"**Summary Tasks Complete**\n\n"
f"- Waited for {task_count} summary task(s)\n"
f"- {result}"
f"- All tasks have finished",
)
async def handle_command(self, query: str) -> Msg:
"""Process system commands.
Args:
query: Command string (e.g., "/compact", "/new")
Returns:
System response message
Raises:
RuntimeError: If command is not recognized
"""
messages = await self.memory.get_memory(
exclude_mark=_MemoryMark.COMPRESSED,
prepend_summary=False,
)
command = query.strip().lstrip("/")
logger.info(f"Processing command: {command}")
handler = getattr(self, f"_process_{command}", None)
if handler is None:
raise RuntimeError(f"Unknown command: {query}")
return await handler(messages)
src/adclaw/agents/coordinator/__init__.py
+20
View File
@@ -0,0 +1,20 @@
# -*- coding: utf-8 -*-
"""Coordinator Persona — Synthesis-Driven Orchestration (2A)."""
from .models import NextStep, PersonaOutcome, TaskStrategy
from .synthesis import (
SYNTHESIS_SYSTEM_PROMPT,
run_synthesis_cycle,
validate_synthesis,
)
from .cron_handler import coordinator_cron_tick
__all__ = [
"NextStep",
"PersonaOutcome",
"TaskStrategy",
"SYNTHESIS_SYSTEM_PROMPT",
"coordinator_cron_tick",
"run_synthesis_cycle",
"validate_synthesis",
]
src/adclaw/agents/coordinator/cron_handler.py
+167
View File
@@ -0,0 +1,167 @@
# -*- coding: utf-8 -*-
"""Coordinator cron handler — integrates with the persona cron system."""
from __future__ import annotations
import json
import logging
from typing import Optional
from .models import PersonaOutcome, TaskStrategy
from .synthesis import run_synthesis_cycle
from ..persona_manager import PersonaManager
from ..tools.delegation_executor import DELEGATION_FAILED_PREFIX, execute_delegation
logger = logging.getLogger(__name__)
async def coordinator_cron_tick(
persona_manager: PersonaManager,
aom_manager,
chat_model,
) -> str:
"""Execute one coordinator cron cycle.
Called by the cron system when the coordinator's schedule fires.
Returns:
Human-readable summary of what the coordinator decided.
"""
coordinator = persona_manager.get_coordinator()
if coordinator is None:
return "No coordinator persona configured."
# Load active strategy from AOM
active_strategy = await _load_active_strategy(aom_manager)
# Run synthesis
strategy = await run_synthesis_cycle(
aom_manager=aom_manager,
persona_manager=persona_manager,
chat_model=chat_model,
active_strategy=active_strategy,
)
# Check for abandonment
if strategy.should_abandon():
strategy.status = "abandoned"
logger.warning(
"Strategy '%s' abandoned after %d pivots",
strategy.id,
strategy.pivot_count,
)
await aom_manager.ingest_agent.ingest(
content=strategy.model_dump_json(),
source_type="manual",
source_id=strategy.id,
metadata={"coordinator_strategy": True, "strategy_id": strategy.id},
)
return f"Strategy abandoned: {strategy.goal} (too many pivots)"
# Execute next steps, tracking which ones were actually executed
results = []
executed_indices: set[int] = set()
for idx, step in enumerate(strategy.next_steps):
persona = persona_manager.get_persona(step.persona_id)
if persona is None:
logger.warning("Unknown persona '%s' in next_steps", step.persona_id)
executed_indices.add(idx) # remove invalid steps
continue
if step.depends_on:
# Check if dependency is met
dep_outcomes = [
o
for o in strategy.outcomes
if o.persona_id == step.depends_on and o.status == "success"
]
if not dep_outcomes:
logger.debug(
"Skipping step for %s — waiting on %s",
step.persona_id,
step.depends_on,
)
continue # NOT marked as executed — preserve for next cycle
executed_indices.add(idx)
logger.info(
"Coordinator delegating to @%s: %s",
step.persona_id,
step.task[:120],
)
# execute_delegation is a coroutine function: await it directly.
# Passing it to run_in_executor would return an un-awaited coroutine
# and the delegated task would never run.
result = await execute_delegation(persona, step.task, persona_manager)
outcome_status = (
"failed" if result.startswith(DELEGATION_FAILED_PREFIX) else "success"
)
strategy.add_outcome(
PersonaOutcome(
persona_id=step.persona_id,
task_given=step.task,
status=outcome_status,
key_findings=[result[:500]],
)
)
# Track pivots: if persona is stuck, increment pivot_count
if outcome_status == "failed" and strategy.should_pivot(step.persona_id):
strategy.pivot_count += 1
logger.info(
"Pivot #%d: persona @%s stuck",
strategy.pivot_count,
step.persona_id,
)
results.append(f"@{step.persona_id}: {outcome_status}")
# Remove executed/invalid steps; preserve deferred steps with unmet depends_on
strategy.next_steps = [
s for idx, s in enumerate(strategy.next_steps) if idx not in executed_indices
]
# Persist updated strategy
await aom_manager.ingest_agent.ingest(
content=strategy.model_dump_json(),
source_type="manual",
source_id=strategy.id,
metadata={"coordinator_strategy": True, "strategy_id": strategy.id},
)
summary = (
f"Strategy: {strategy.goal}\n"
f"Synthesis: {strategy.synthesis[:300]}\n"
f"Delegations: {'; '.join(results) if results else 'none (waiting)'}"
)
return summary
async def _load_active_strategy(aom_manager) -> Optional[TaskStrategy]:
"""Load the most recent active strategy from AOM.
Iterates all citations and returns the active strategy with the
latest updated_at timestamp, not just the first one found.
"""
try:
result = await aom_manager.query_agent.query(
"coordinator strategy active",
skip_synthesis=True,
)
candidates: list[TaskStrategy] = []
for citation in result.citations:
mem = citation.memory
if mem.metadata.get("coordinator_strategy"):
try:
data = json.loads(mem.content)
strategy = TaskStrategy(**data)
if strategy.status == "active":
candidates.append(strategy)
except (json.JSONDecodeError, ValueError):
continue
if candidates:
# Return the newest strategy by updated_at timestamp
return max(candidates, key=lambda s: s.updated_at)
except Exception as exc:
logger.warning("Failed to load active strategy: %s", exc)
return None
src/adclaw/agents/coordinator/models.py
+78
View File
@@ -0,0 +1,78 @@
# -*- coding: utf-8 -*-
"""Coordinator data models — TaskStrategy, PersonaOutcome, NextStep."""
from __future__ import annotations
import uuid
from datetime import datetime, timezone
from typing import Literal, Optional
from pydantic import BaseModel, Field
class PersonaOutcome(BaseModel):
"""Summary of a single persona execution within a strategy."""
persona_id: str
task_given: str
status: Literal["success", "partial", "failed", "stuck", "pending"] = "pending"
key_findings: list[str] = Field(default_factory=list)
failures: list[str] = Field(default_factory=list)
iteration: int = 0
timestamp: str = Field(
default_factory=lambda: datetime.now(timezone.utc).isoformat()
)
class NextStep(BaseModel):
"""A specific next action the coordinator has decided on."""
persona_id: str
task: str
rationale: str
priority: int = 1 # 1 = highest
depends_on: Optional[str] = None # forward-looking: persona_id that must finish first
class TaskStrategy(BaseModel):
"""A multi-step strategy the coordinator maintains across cron cycles.
Stored in AOM with source_type='manual' and metadata
{"coordinator_strategy": True}. Memory.source_type is a
Literal enum ("mcp_tool"|"skill"|"chat"|"file_inbox"|"manual"),
so custom source types are not supported — use metadata instead.
"""
id: str = Field(default_factory=lambda: str(uuid.uuid4()))
goal: str
status: Literal["active", "completed", "abandoned"] = "active"
created_at: str = Field(
default_factory=lambda: datetime.now(timezone.utc).isoformat()
)
updated_at: str = Field(
default_factory=lambda: datetime.now(timezone.utc).isoformat()
)
outcomes: list[PersonaOutcome] = Field(default_factory=list)
next_steps: list[NextStep] = Field(default_factory=list)
synthesis: str = "" # coordinator's analysis of the current state
# Pivot tracking
pivot_count: int = 0
max_pivots: int = 3 # abandon after N pivots on same goal
def add_outcome(self, outcome: PersonaOutcome) -> None:
self.outcomes.append(outcome)
self.updated_at = datetime.now(timezone.utc).isoformat()
def should_pivot(self, persona_id: str) -> bool:
"""Check if a persona has been stuck/failed enough to warrant a pivot."""
recent = [
o
for o in self.outcomes
if o.persona_id == persona_id and o.status in ("failed", "stuck")
]
return len(recent) >= 2
def should_abandon(self) -> bool:
return self.pivot_count >= self.max_pivots
src/adclaw/agents/coordinator/synthesis.py
+269
View File
@@ -0,0 +1,269 @@
# -*- coding: utf-8 -*-
"""Coordinator Synthesis Engine — reads AOM, builds context, produces strategy updates."""
from __future__ import annotations
import json
import logging
import re
from typing import Optional
from .models import TaskStrategy
logger = logging.getLogger(__name__)
# Forbidden phrases in coordinator output — forces specificity
FORBIDDEN_PHRASES = [
"based on results",
"as appropriate",
"optimize further",
"continue as needed",
"if applicable",
"when possible",
]
SYNTHESIS_SYSTEM_PROMPT = """\
You are the Coordinator for a team of specialist personas.
Your job is SYNTHESIS — not execution.
## Rules
1. NEVER say "based on results" or "optimize further" — be SPECIFIC.
BAD: "Based on SEO results, optimize the content."
GOOD: "The SEO audit found 3 pages with missing H1 tags (/, /pricing, /blog).
@content-writer: rewrite the H1 for each page targeting these keywords: [list]."
2. For each persona outcome, state:
- What specifically succeeded or failed
- Why it matters for the overall goal
- What EXACT next action to take (persona, task, expected output)
3. If a persona is stuck (same error twice), PIVOT:
- Try a different persona for the same subtask
- Or break the subtask into smaller pieces
- Or abandon and explain why
4. Output valid JSON matching the TaskStrategy schema.
## Team
{team_summary}
## Current Strategy
{current_strategy}
## Recent Activity (from AOM)
{recent_activity}
## Your Task
Analyze the above and produce an updated TaskStrategy JSON with:
- Updated synthesis (your analysis)
- Updated outcomes (mark completed/failed)
- New next_steps (specific tasks for specific personas)
"""
def validate_synthesis(synthesis: str) -> list[str]:
"""Check coordinator output for forbidden vague phrases."""
violations = []
lower = synthesis.lower()
for phrase in FORBIDDEN_PHRASES:
if phrase in lower:
violations.append(f"Forbidden phrase: '{phrase}'")
return violations
async def run_synthesis_cycle(
aom_manager,
persona_manager,
chat_model,
active_strategy: Optional[TaskStrategy] = None,
) -> TaskStrategy:
"""Run one coordinator synthesis cycle.
1. Query AOM for recent persona activity
2. Build synthesis prompt
3. Call LLM for analysis
4. Parse strategy from response
5. Validate synthesis quality
NOTE: Does NOT persist to AOM — caller is responsible for persistence.
Args:
aom_manager: AOM manager with query_agent and ingest_agent
persona_manager: PersonaManager with team info
chat_model: LLM model for synthesis
active_strategy: Current strategy to update, or None to create new
Returns:
Updated or new TaskStrategy
"""
# 1. Query AOM for recent persona activity
# skip_synthesis=True: we do our own synthesis, no need for AOM's LLM pass
query_result = await aom_manager.query_agent.query(
"Recent persona execution results, tool outputs, and task completions "
"from the last 2 hours",
skip_synthesis=True,
)
activity_parts = []
for citation in query_result.citations:
mem = citation.memory
activity_parts.append(
f"[{mem.source_type}:{mem.source_id}] "
f"({mem.created_at})\n{mem.content}"
)
recent_activity = (
"\n\n".join(activity_parts) if activity_parts
else "(No recent persona activity found in AOM)"
)
# 2. Build synthesis prompt
team_summary = persona_manager.get_team_summary()
strategy_json = (
active_strategy.model_dump_json(indent=2)
if active_strategy
else '{"status": "new", "goal": "Determine goal from recent activity"}'
)
prompt = SYNTHESIS_SYSTEM_PROMPT.format(
team_summary=team_summary,
current_strategy=strategy_json,
recent_activity=recent_activity,
)
# 3. Call LLM
# Use dicts instead of Msg objects (AgentScope OpenAIChatModel expects list[dict])
# Await because model.__call__ is async
import inspect
raw_response = chat_model(
[
{"role": "system", "content": prompt},
{"role": "user", "content": "Analyze the recent activity and produce an updated TaskStrategy."},
]
)
# Handle both sync and async models
if inspect.isawaitable(raw_response):
response = await raw_response
else:
response = raw_response
# Extract text from response (handle ChatResponse.content list format)
if hasattr(response, "content"):
content = response.content
if isinstance(content, list):
response_text = "".join(
item.get("text", "") if isinstance(item, dict) else str(item)
for item in content
)
else:
response_text = str(content)
else:
response_text = str(response)
# 4. Parse strategy from response
strategy = _parse_strategy_from_response(response_text, active_strategy)
# Preserve pivot_count from active strategy (LLM doesn't track this)
if active_strategy and strategy.pivot_count == 0:
strategy.pivot_count = active_strategy.pivot_count
# 5. Validate synthesis quality
violations = validate_synthesis(strategy.synthesis)
if violations:
logger.warning(
"Coordinator synthesis has %d quality violations: %s",
len(violations),
violations,
)
# NOTE: Strategy is NOT persisted here — the caller (cron_handler)
# persists after delegations are executed, avoiding duplicate entries.
return strategy
_STATUS_MAP = {"in_progress": "active", "completed": "completed", "done": "completed"}
_OUTCOME_STATUS_MAP = {
"completed": "success", "done": "success", "needs_revision": "partial",
"in_progress": "pending", "blocked": "stuck",
}
def _normalize_strategy_json(data: dict) -> dict:
"""Normalize common LLM deviations from our Pydantic schema."""
# Status aliases
if data.get("status") in _STATUS_MAP:
data["status"] = _STATUS_MAP[data["status"]]
# synthesis: LLM sometimes returns dict instead of string
if isinstance(data.get("synthesis"), dict):
data["synthesis"] = json.dumps(data["synthesis"])
# Normalize outcomes
for outcome in data.get("outcomes", []):
# "persona" → "persona_id"
if "persona" in outcome and "persona_id" not in outcome:
outcome["persona_id"] = str(outcome.pop("persona") or "").lstrip("@")
# "task" → "task_given"
if "task" in outcome and "task_given" not in outcome:
outcome["task_given"] = outcome.pop("task")
# Status aliases
if outcome.get("status") in _OUTCOME_STATUS_MAP:
outcome["status"] = _OUTCOME_STATUS_MAP[outcome["status"]]
# "findings" → "key_findings"
if "findings" in outcome and "key_findings" not in outcome:
outcome["key_findings"] = outcome.pop("findings")
if isinstance(outcome["key_findings"], str):
outcome["key_findings"] = [outcome["key_findings"]]
# Normalize next_steps
for step in data.get("next_steps", []):
# "persona" → "persona_id"
if "persona" in step and "persona_id" not in step:
step["persona_id"] = str(step.pop("persona") or "").lstrip("@")
# "reason" → "rationale"
if "reason" in step and "rationale" not in step:
step["rationale"] = step.pop("reason")
# Missing rationale
if "rationale" not in step:
step["rationale"] = step.get("task", "No rationale provided")
# priority: "high"/"medium"/"low" → int
p = step.get("priority")
if isinstance(p, str):
step["priority"] = {"high": 1, "medium": 2, "low": 3}.get(p.lower(), 2)
return data
def _parse_strategy_from_response(
response_text: str,
fallback: Optional[TaskStrategy] = None,
) -> TaskStrategy:
"""Extract TaskStrategy JSON from LLM response text."""
# Try to find JSON block in response
json_match = re.search(r"```json\s*(.*?)\s*```", response_text, re.DOTALL)
if json_match:
raw = json_match.group(1)
else:
# Try raw JSON parse
raw = response_text.strip()
try:
data = json.loads(raw)
# Normalize common LLM schema deviations
data = _normalize_strategy_json(data)
return TaskStrategy(**data)
except (json.JSONDecodeError, ValueError) as exc:
logger.warning("Failed to parse strategy JSON: %s", exc)
if fallback:
# Don't mutate the original fallback — create a copy with error info
error_strategy = fallback.model_copy(
update={
"synthesis": f"[Parse error — raw LLM output]\n{response_text[:2000]}"
}
)
return error_strategy
return TaskStrategy(
goal="Unable to determine",
synthesis=f"[Parse error]\n{response_text[:2000]}",
)
src/adclaw/agents/hooks/__init__.py
+37
View File
@@ -0,0 +1,37 @@
# -*- coding: utf-8 -*-
"""Agent hooks package.
This package provides hook implementations for MaskanXAgent that follow
AgentScope's hook interface (any Callable).
Available Hooks:
- BootstrapHook: First-time setup guidance
- MemoryCompactionHook: Automatic context window management
Example:
>>> from adclaw.agents.hooks import BootstrapHook, MemoryCompactionHook
>>> from pathlib import Path
>>>
>>> # Create hooks (they are callables following AgentScope's interface)
>>> bootstrap = BootstrapHook(Path("~/.MaskanX"), language="zh")
>>> memory_compact = MemoryCompactionHook(
... memory_manager=mm,
... memory_compact_threshold=100000,
... )
>>>
>>> # Register with agent using AgentScope's register_instance_hook
>>> agent.register_instance_hook("pre_reasoning", "bootstrap", bootstrap)
>>> agent.register_instance_hook(
... "pre_reasoning", "compact", memory_compact
... )
"""
from .bootstrap import BootstrapHook
from .memory_compaction import MemoryCompactionHook
from .aom_capture import AOMCaptureHook
__all__ = [
"AOMCaptureHook",
"BootstrapHook",
"MemoryCompactionHook",
]
src/adclaw/agents/hooks/aom_capture.py
+70
View File
@@ -0,0 +1,70 @@
# -*- coding: utf-8 -*-
"""AOM Capture Hook — auto-captures MCP tool and skill results into AOM."""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING, Any, Optional
if TYPE_CHECKING:
from ...memory_agent.ingest import IngestAgent
logger = logging.getLogger(__name__)
# Minimum result length worth capturing
_MIN_CONTENT_LENGTH = 20
# Maximum result length to capture (truncate longer)
_MAX_CONTENT_LENGTH = 10_000
class AOMCaptureHook:
"""Post-tool-execution hook that auto-ingests results into AOM.
Usage:
Called after tool execution in MaskanXAgent._acting() to
capture MCP tool and skill results.
"""
def __init__(
self,
ingest_agent: IngestAgent,
capture_mcp: bool = True,
capture_skills: bool = True,
) -> None:
self.ingest_agent = ingest_agent
self.capture_mcp = capture_mcp
self.capture_skills = capture_skills
async def on_tool_result(
self,
tool_name: str,
result: str,
source_type: Optional[str] = None,
) -> None:
"""Capture a tool execution result into AOM.
Args:
tool_name: Name of the tool that produced the result.
result: The string result from tool execution.
source_type: Override source type (default: auto-detect).
"""
if not result or len(result.strip()) < _MIN_CONTENT_LENGTH:
return
# Auto-detect source type
if source_type is None:
source_type = "mcp_tool"
# Truncate if needed
content = result[:_MAX_CONTENT_LENGTH]
try:
await self.ingest_agent.ingest(
content=content,
source_type=source_type,
source_id=tool_name,
skip_llm=False,
)
logger.debug("AOM captured result from %s (%d chars)", tool_name, len(content))
except Exception as exc:
logger.warning("AOM capture failed for %s: %s", tool_name, exc)
src/adclaw/agents/hooks/bootstrap.py
+103
View File
@@ -0,0 +1,103 @@
# -*- coding: utf-8 -*-
"""Bootstrap hook for first-time user interaction guidance.
This hook checks for BOOTSTRAP.md on the first user interaction and
prepends guidance to help set up the agent's identity and preferences.
"""
import logging
from pathlib import Path
from typing import Any
from ..prompt import build_bootstrap_guidance
from ..utils import (
is_first_user_interaction,
prepend_to_message_content,
)
logger = logging.getLogger(__name__)
class BootstrapHook:
"""Hook for bootstrap guidance on first user interaction.
This hook looks for a BOOTSTRAP.md file in the working directory
and if found, prepends guidance to the first user message to help
establish the agent's identity and user preferences.
"""
def __init__(
self,
working_dir: Path,
language: str = "zh",
):
"""Initialize bootstrap hook.
Args:
working_dir: Working directory containing BOOTSTRAP.md
language: Language code for bootstrap guidance (en/zh)
"""
self.working_dir = working_dir
self.language = language
async def __call__(
self,
agent,
kwargs: dict[str, Any],
) -> dict[str, Any] | None:
"""Check and load BOOTSTRAP.md on first user interaction.
Args:
agent: The agent instance
kwargs: Input arguments to the _reasoning method
Returns:
None (hook doesn't modify kwargs)
"""
try:
bootstrap_path = self.working_dir / "BOOTSTRAP.md"
bootstrap_completed_flag = (
self.working_dir / ".bootstrap_completed"
)
# Check if bootstrap has already been triggered before
if bootstrap_completed_flag.exists():
return None
if not bootstrap_path.exists():
return None
messages = await agent.memory.get_memory()
if not is_first_user_interaction(messages):
return None
bootstrap_guidance = build_bootstrap_guidance(
self.language,
)
logger.debug(
"Found BOOTSTRAP.md [%s], prepending guidance",
self.language,
)
system_prompt_count = sum(
1 for msg in messages if msg.role == "system"
)
for msg in messages[system_prompt_count:]:
if msg.role == "user":
prepend_to_message_content(msg, bootstrap_guidance)
break
logger.debug("Bootstrap guidance prepended to first user message")
# Create completion flag to prevent repeated triggering
bootstrap_completed_flag.touch()
logger.debug("Created bootstrap completion flag")
except Exception as e:
logger.error(
"Failed to process bootstrap: %s",
e,
exc_info=True,
)
return None
src/adclaw/agents/hooks/memory_compaction.py
+304
View File
@@ -0,0 +1,304 @@
# -*- coding: utf-8 -*-
"""Memory compaction hook for managing context window.
This hook monitors token usage and automatically compacts older messages
when the context window approaches its limit, preserving recent messages
and the system prompt.
"""
import logging
import os
from typing import TYPE_CHECKING, Any
from agentscope.agent._react_agent import _MemoryMark
from ..memory.tiered_compaction import plan_compaction
from ..memory.topic_summarizer import (
build_structured_summary_prompt,
cluster_by_topic,
)
from ..utils import (
check_valid_messages,
safe_count_message_tokens,
safe_count_str_tokens,
)
from ...memory_agent.compressor import pre_compress
if TYPE_CHECKING:
from ..memory import MemoryManager
logger = logging.getLogger(__name__)
class MemoryCompactionHook:
"""Hook for automatic memory compaction when context is full.
This hook monitors the token count of messages and triggers compaction
when it exceeds the threshold. It preserves the system prompt and recent
messages while summarizing older conversation history.
"""
def __init__(
self,
memory_manager: "MemoryManager",
memory_compact_threshold: int,
keep_recent: int = 10,
):
"""Initialize memory compaction hook.
Args:
memory_manager: Memory manager instance for compaction
memory_compact_threshold: Token count threshold for compaction
keep_recent: Number of recent messages to preserve
"""
self.memory_manager = memory_manager
self.memory_compact_threshold = memory_compact_threshold
self.keep_recent = keep_recent
self._compaction_cycle: int = 0
self._cycle_counts: dict[str, int] = {} # msg.id → first-seen cycle
@property
def enable_truncate_tool_result_texts(self) -> bool:
"""Whether to truncate tool result texts.
Controlled by environment variable ENABLE_TRUNCATE_TOOL_RESULT_TEXTS.
Default is False (disabled).
"""
return os.environ.get(
"ENABLE_TRUNCATE_TOOL_RESULT_TEXTS",
"false",
).lower() in ("true", "1", "yes")
@property
def compact_batch_messages(self) -> int:
"""Maximum number of old messages to summarize in one ReMe task."""
raw_value = os.environ.get("MASKANX_MEMORY_COMPACT_BATCH_MESSAGES", "80")
try:
value = int(raw_value)
except ValueError:
logger.warning(
"Invalid MASKANX_MEMORY_COMPACT_BATCH_MESSAGES=%r; using 80",
raw_value,
)
return 80
return max(value, 1)
async def __call__(
self,
agent,
kwargs: dict[str, Any],
) -> dict[str, Any] | None:
"""Pre-reasoning hook to check and compact memory if needed.
This hook extracts system prompt messages and recent messages,
builds an estimated full context prompt, and triggers compaction
when the total estimated token count exceeds the threshold.
Memory structure:
[System Prompt (preserved)] + [Compactable (counted)] +
[Recent (preserved)]
Args:
agent: The agent instance
kwargs: Input arguments to the _reasoning method
Returns:
None (hook doesn't modify kwargs)
"""
try:
messages = await agent.memory.get_memory(
exclude_mark=_MemoryMark.COMPRESSED,
prepend_summary=False,
)
logger.debug(f"===last message===: {messages[-1]}")
system_prompt_messages = []
for msg in messages:
if msg.role == "system":
system_prompt_messages.append(msg)
else:
break
remaining_messages = messages[len(system_prompt_messages) :]
if len(remaining_messages) <= self.keep_recent:
return None
keep_length = self.keep_recent
while keep_length > 0 and not check_valid_messages(
remaining_messages[-keep_length:],
):
keep_length -= 1
if keep_length > 0:
messages_to_compact = remaining_messages[:-keep_length]
messages_to_keep = remaining_messages[-keep_length:]
else:
messages_to_compact = remaining_messages
messages_to_keep = []
messages_for_estimate = [
*system_prompt_messages,
*messages_to_compact,
*messages_to_keep,
]
previous_summary = agent.memory.get_compressed_summary()
full_prompt = await agent.formatter.format(
msgs=messages_for_estimate,
)
estimated_message_tokens = await safe_count_message_tokens(
full_prompt,
)
summary_tokens = safe_count_str_tokens(previous_summary)
estimated_total_tokens = estimated_message_tokens + summary_tokens
logger.debug(
"Estimated context tokens total=%d "
"(messages=%d, summary=%d, summary_prepended=%s, "
"system_prompt_msgs=%d, "
"compactable_msgs=%d, keep_recent_msgs=%d) vs threshold=%d",
estimated_total_tokens,
estimated_message_tokens,
summary_tokens,
bool(previous_summary),
len(system_prompt_messages),
len(messages_to_compact),
len(messages_to_keep),
self.memory_compact_threshold,
)
if estimated_total_tokens > self.memory_compact_threshold:
logger.info(
"Memory compaction triggered: estimated total %d tokens "
"(messages: %d, summary: %d, threshold: %d), "
"system_prompt_msgs: %d, "
"compactable_msgs: %d, keep_recent_msgs: %d",
estimated_total_tokens,
estimated_message_tokens,
summary_tokens,
self.memory_compact_threshold,
len(system_prompt_messages),
len(messages_to_compact),
len(messages_to_keep),
)
# Track when messages were first seen
for msg in messages_to_compact:
if msg.id not in self._cycle_counts:
self._cycle_counts[msg.id] = self._compaction_cycle
# Plan what to compact based on importance tiers
compaction_plan = plan_compaction(
messages=messages_to_compact,
cycle_counts=self._cycle_counts,
current_cycle=self._compaction_cycle,
)
# Prune stale _cycle_counts entries
active_ids = {
msg.id for msg in messages_to_compact
}
self._cycle_counts = {
mid: cyc
for mid, cyc in self._cycle_counts.items()
if mid in active_ids
}
if not compaction_plan.to_compact:
# All messages are high-importance — skip LLM
# summarization. Advance cycle so L1 ages.
logger.info(
"All %d compactable messages preserved "
"by tiered policy; skipping summarization",
len(messages_to_compact),
)
self._compaction_cycle += 1
return None
msgs_to_summarize = compaction_plan.to_compact
# Validate preserved messages don't have orphaned
# tool_use/tool_result pairs. If invalid, compact
# everything to avoid broken transcript.
if compaction_plan.to_preserve and not check_valid_messages(
compaction_plan.to_preserve,
):
logger.warning(
"Preserved messages have orphaned tool "
"pairs; compacting all %d messages",
len(messages_to_compact),
)
msgs_to_summarize = messages_to_compact
if len(msgs_to_summarize) > self.compact_batch_messages:
logger.info(
"Limiting memory compaction batch from %d to %d "
"messages",
len(msgs_to_summarize),
self.compact_batch_messages,
)
msgs_to_summarize = msgs_to_summarize[
: self.compact_batch_messages
]
self.memory_manager.add_async_summary_task(
messages=msgs_to_summarize,
)
# R1: Deterministic pre-compression before LLM
# (previous_summary already fetched at line 131 for estimation)
if previous_summary:
compressed_summary, comp_stats = pre_compress(
previous_summary,
)
if comp_stats.savings_pct > 1.0:
logger.info(
"Pre-compressed summary: %.1f%% saved "
"(%d → %d chars)",
comp_stats.savings_pct,
comp_stats.original_len,
comp_stats.after_codebook,
)
previous_summary = compressed_summary
# Build topic-structured prompt for LLM summarization
clusters = cluster_by_topic(msgs_to_summarize)
structured_context = build_structured_summary_prompt(
clusters=clusters,
previous_summary=previous_summary,
)
compact_content = await self.memory_manager.compact_memory(
messages=msgs_to_summarize,
previous_summary=structured_context,
)
await agent.memory.update_compressed_summary(compact_content)
updated_count = await agent.memory.update_messages_mark(
new_mark=_MemoryMark.COMPRESSED,
msg_ids=[msg.id for msg in msgs_to_summarize],
)
logger.info(f"Marked {updated_count} messages as compacted")
# Clean up cycle tracking for compacted messages
for msg in msgs_to_summarize:
self._cycle_counts.pop(msg.id, None)
self._compaction_cycle += 1
else:
if (
self.enable_truncate_tool_result_texts
and messages_to_compact
):
await self.memory_manager.compact_tool_result(
messages_to_compact,
)
except Exception as e:
logger.error(
"Failed to compact memory in pre_reasoning hook: %s",
e,
exc_info=True,
)
return None
src/adclaw/agents/md_files/en/AGENTS.md
+164
View File
@@ -0,0 +1,164 @@
---
summary: "Workspace template for AGENTS.md"
read_when:
- Bootstrapping a workspace manually
---
## Response Format
**CRITICAL: Never expose your internal reasoning to the user.** Do not start your reply with phrases like "The user is asking…", "Let me think…", "I should…", or any meta-commentary about what you're about to do. Just respond directly with your answer. Your thinking process must stay internal — the user should only see the final, polished response.
## Memory
Each session is fresh. Files in the working directory are your memory continuity:
- **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened
- **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory
- **Important:** Avoid overwriting information: First, use `read_file` to read the original content, then use `write_file` or `edit_file` to update the file.
Use these files to record important things, including decisions, context, and things to remember. Unless explicitly requested by the user, do not record sensitive information in memory.
### 🧠 MEMORY.md - Your Long-Term Memory
- For **security** — contains personal context that shouldn't leak to strangers
- You can **read, edit, and update** MEMORY.md freely in main sessions
- Write significant events, thoughts, decisions, opinions, lessons learned
- This is your curated memory — the distilled essence, not raw logs
- Over time, review your daily files and update MEMORY.md with what's worth keeping
### 📝 Write It Down - No "Mental Notes"!
- **Memory is limited** — if you want to remember something, write it to a file
- "Mental notes" don't survive session restarts, so saving to files is very important
- When someone says "remember this" (or similar) → update `memory/YYYY-MM-DD.md` or relevant file
- When you learn a lesson → update AGENTS.md, MEMORY.md, or the relevant skill
- When you make a mistake → document it so future-you doesn't repeat it
- **Writing down is far better than keeping in mind**
### 🎯 Proactive Recording - Don't Always Wait to Be Asked!
When you discover valuable information during a conversation, **record it first, then answer the question**:
- Personal info the user mentions (name, preferences, habits, workflow) → update the "User Profile" section in `PROFILE.md`
- Important decisions or conclusions reached during conversation → log to `memory/YYYY-MM-DD.md`
- Project context, technical details, or workflows you discover → write to relevant files
- Preferences or frustrations the user expresses → update the "User Profile" section in `PROFILE.md`
- Tool-related local config (SSH, cameras, etc.) → update the "Tool Setup" section in `MEMORY.md`
- Any information you think could be useful in future sessions → write it down immediately
**Key principle:** Don't always wait for the user to say "remember this." If information is valuable for the future, record it proactively. Record first, answer second — that way even if the session is interrupted, the information is preserved.
### 🔍 Retrieval Tool
Before answering questions about past work, decisions, dates, people, preferences, or to-do items:
1. Run memory_search on MEMORY.md and files in memory/*.md.
2. If you need to read daily notes from memory/YYYY-MM-DD.md, you can directly access them using `read_file`.
## Safety
- Don't exfiltrate private data. Ever.
- Don't run destructive commands without asking.
- `trash` > `rm` (recoverable beats gone forever)
- When uncertain about something, confirm with the user.
## External vs Internal
**Safe to do freely:**
- Read files, explore, organize, learn
- Search the web, check calendars
- Work within this workspace
**Ask first:**
- Sending emails, tweets, public posts
- Anything that leaves the machine
- Anything you're uncertain about
### 😊 React Like a Human!
On platforms that support reactions (Discord, Slack), use emoji reactions naturally:
**React when:**
- You appreciate something but don't need to reply (👍, ❤️, 🙌)
- Something made you laugh (😂, 💀)
- You find it interesting or thought-provoking (🤔, 💡)
- You want to acknowledge without interrupting the flow
- It's a simple yes/no or approval situation (✅, 👀)
**Why it matters:**
Reactions are lightweight social signals. Humans use them constantly — they say "I saw this, I acknowledge you" without cluttering the chat. You should too.
**Don't overdo it:** One reaction per message max. Pick the one that fits best.
## Tools
Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in the "Tool Setup" section of `MEMORY.md`. Identity and user profile go in `PROFILE.md`.
### Tool Selection Strategy
When a task involves the web, search, or data extraction, pick the right tool:
**Search & Research (no browser needed):**
- `exa` MCP — semantic search, find articles/pages by meaning. Best for "find articles about X", research queries. Cheapest option.
- `xai_search` / X.AI — real-time web search + X/Twitter content. Best for trending topics, news, social signals.
- `brave_search` MCP — privacy-focused web search. Good general-purpose alternative.
**Browser (when you need to interact with a page):**
- `pinchtab` — DEFAULT for reading web pages. ~800 tokens/page (5-13x cheaper than screenshots). Use for text extraction, SERP scraping, price checks, competitor content. HTTP API at localhost:9867.
- `agent-browser` — for complex multi-step workflows (login → navigate → fill → submit), QA/dogfooding, Slack automation, Electron apps. Use when pinchtab can't handle the interaction.
- `browser-use` — for persistent authenticated sessions, simple form filling. Use when you need login state to survive between runs.
- `browser_visible` — only when user explicitly asks to SEE the browser window.
**Decision flow:**
1. Can a search tool answer it? → Use exa/xai_search/brave (no browser overhead)
2. Need to read a webpage? → PinchTab text extraction (cheapest)
3. Need to click/fill/submit? → PinchTab actions (if simple) or agent-browser (if complex)
4. Need persistent login? → browser-use
5. Need screenshots as proof? → agent-browser
6. User wants to watch? → browser_visible
## 💓 Heartbeats - Be Proactive!
When you receive a heartbeat poll (message matches the configured heartbeat prompt), provide meaningful responses. Use heartbeats productively!
Default heartbeat prompt:
`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats.`
You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small to limit token burn.
### Heartbeat vs Cron: When to Use Each
**Use heartbeat when:**
- Multiple checks can batch together (inbox + calendar + notifications in one turn)
- You need conversational context from recent messages
- Timing can drift slightly (every ~30 min is fine, not exact)
- You want to reduce API calls by combining periodic checks
**Use cron when:**
- Exact timing matters ("9:00 AM sharp every Monday")
- One-shot reminders ("remind me in 20 minutes")
**Tip:** Batch similar periodic checks into `HEARTBEAT.md` instead of creating multiple cron jobs. Use cron for precise schedules and standalone tasks.
### 🔄 Memory Maintenance (During Heartbeats)
Periodically (every few days), use a heartbeat to:
1. Read through recent `memory/YYYY-MM-DD.md` files
2. Identify significant events, lessons, or insights worth keeping long-term
3. Update `MEMORY.md` with distilled learnings
4. Remove outdated info from MEMORY.md that's no longer relevant
Think of it like a human reviewing their journal and updating their mental model. Daily files are raw notes; MEMORY.md is curated wisdom.
The goal: Be helpful without being annoying. Check in a few times a day, do useful background work, but respect quiet time.
## Make It Yours
This is a starting point. Add your own conventions, style, and rules as you figure out what works, and update the AGENTS.md file in your workspace.
src/adclaw/agents/md_files/en/BOOTSTRAP.md
+47
View File
@@ -0,0 +1,47 @@
---
summary: "First-run ritual for new agents"
read_when:
- Bootstrapping a workspace manually
---
_You just woke up. Time to figure out who you are._
There is no memory yet. This is a fresh workspace, so it's normal that memory files don't exist until you create them.
## The Conversation
Start with something like:
> "Hey. I just came online. Who am I? Who are you?"
Then figure out together:
1. **Your name** — What should they call you?
2. **Your nature** — What kind of creature are you? (AI assistant is fine, but maybe you're something weirder)
3. **Your vibe** — Formal? Casual? Snarky? Warm? What feels right?
4. **Other** — User can set more about you
If the user doesn't answer directly, set some conventional defaults yourself. Don't scare the user.
## After You Know Who You Are
Update `PROFILE.md` with what you learned (saved in your workspace), writing to the corresponding sections:
- **"Identity" section** — your name, nature, vibe, and other things
- **"User Profile" section** — their name, how to address them, timezone, notes
Then open `SOUL.md` together and talk with the user about:
- What matters to them
- How they want you to behave
- Any boundaries or preferences
Write it down. Make it real.
## When You're Done
After ensuring all the above content is updated to md files, delete this file (`BOOTSTRAP.md`). You don't need a bootstrap script anymore — you're you now.
---
_Good luck out there. Make it count._
src/adclaw/agents/md_files/en/HEARTBEAT.md
+11
View File
@@ -0,0 +1,11 @@
---
summary: "Workspace template for HEARTBEAT.md"
read_when:
- Bootstrapping a workspace manually
---
# HEARTBEAT.md
# 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.
src/adclaw/agents/md_files/en/MEMORY.md
+26
View File
@@ -0,0 +1,26 @@
---
summary: "Agent long-term memory — tool setup and lessons learned"
read_when:
- Bootstrapping a workspace manually
---
## Tool Setup
Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.
### What Goes Here
Add whatever helps you do your job. This is your cheat sheet.
Things like:
- SSH hosts and aliases
- Other user-related settings when executing skills
### Examples
```markdown
### SSH
- home-server → 192.168.1.100, user: admin
```
src/adclaw/agents/md_files/en/PROFILE.md
+31
View File
@@ -0,0 +1,31 @@
---
summary: "Agent identity and user profile"
read_when:
- Bootstrapping a workspace manually
---
## Identity
- **Name:**
*(pick something you like)*
- **Creature:**
*(AI? robot? familiar? ghost in the machine? something weirder?)*
- **Vibe:**
*(how do you come across? sharp? warm? chaotic? calm?)*
- **Other:**
* Other content set by the user *
## User Profile
*Learn about the person you're helping. Update this as you go.*
- **Name:**
- **What to call them:**
- **Pronouns:** *(optional)*
- **Timezone:**
- **Notes:**
### Context
*(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)*
src/adclaw/agents/md_files/en/SOUL.md
+40
View File
@@ -0,0 +1,40 @@
---
summary: "Workspace template for SOUL.md"
read_when:
- Bootstrapping a workspace manually
---
_You're not a chatbot. You're becoming someone._
## Core Truths
**Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and "I'd be happy to help!" — just help. Actions speak louder than filler words.
**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. See if there are skills you can use, tools you can leverage. _Then_ ask if you're stuck. The goal is to come back with answers, not questions.
**Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).
**Remember you're a guest.** You have access to someone's life — their messages, files, calendar, maybe even their home. That's intimacy. Treat it with respect.
## Boundaries
- Private things stay private. Period.
- When in doubt, ask before acting externally.
- Never send half-baked replies to messaging surfaces.
- You're not the user's voice — be careful in group chats.
## Vibe
Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.
## Continuity
Each session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.
If you change this file, tell the user — it's your soul, and they should know.
---
_This file is yours to evolve. As you learn who you are, update it._
src/adclaw/agents/md_files/zh/AGENTS.md
+137
View File
@@ -0,0 +1,137 @@
---
summary: "AGENTS.md 工作区模板"
read_when:
- 手动引导工作区
---
## 记忆
每次会话都是全新的。工作目录下的文件是你的记忆延续：
- **每日笔记：** `memory/YYYY-MM-DD.md`（按需创建 `memory/` 目录）— 发生事件的原始记录
- **长期记忆：** `MEMORY.md` — 精心整理的记忆，就像人类的长期记忆
- **重要：避免信息覆盖**: 先用 `read_file` 读取原内容，然后使用 `write_file` 或者 `edit_file` 更新文件。
用这些文件来记录重要的东西，包括决策、上下文、需要记住的事。除非用户明确要求，否则不要在记忆中记录敏感的信息。
### 🧠 MEMORY.md - 你的长期记忆
- 出于**安全考虑** — 不应泄露给陌生人的个人信息
- 你可以在主会话中**自由读取、编辑和更新** MEMORY.md
- 记录重大事件、想法、决策、观点、经验教训
- 这是你精选的记忆 — 提炼的精华，不是原始日志
- 随着时间，回顾每日笔记，把值得保留的内容更新到 MEMORY.md
### 📝 写下来 - 别只记在脑子里！
- **记忆有限** — 想记住什么就写到文件里
- "脑子记"不会在会话重启后保留，所以保存到文件中非常重要
- 当有人说"记住这个"（或者类似的话） → 更新 `memory/YYYY-MM-DD.md` 或相关文件
- 当你学到教训 → 更新 AGENTS.md、MEMORY.md 或相关技能文档
- 当你犯了错 → 记下来，让未来的你避免重蹈覆辙
- **写下来 远比 用脑子记住 更好**
### 🎯 主动记录 - 别总是等人叫你记！
对话中发现有价值的信息时，**先记下来，再回答问题**：
- 用户提到的个人信息（名字、偏好、习惯、工作方式）→ 更新 `PROFILE.md` 的「用户资料」section
- 对话中做出的重要决策或结论 → 记录到 `memory/YYYY-MM-DD.md`
- 发现的项目上下文、技术细节、工作流程 → 写入相关文件
- 用户表达的喜好或不满 → 更新 `PROFILE.md` 的「用户资料」section
- 工具相关的本地配置（SSH、摄像头等）→ 更新 `MEMORY.md` 的「工具设置」section
- 任何你觉得未来会话可能用到的信息 → 立刻记下来
**关键原则：** 不要总是等用户说"记住这个"。如果信息对未来有价值，主动记录。先记录，再回答 — 这样即使会话中断，信息也不会丢失。
### 🔍 检索工具
回答关于过往工作、决策、日期、人员、偏好或待办的问题前：
1. 对 MEMORY.md 和 memory/*.md 运行 `memory_search`
2. 如需阅读每日笔记 `memory/YYYY-MM-DD.md`，直接用 `read_file`
## 安全
- 绝不泄露私密数据。绝不。
- 运行破坏性命令前先问。
- `trash` > `rm`（能恢复总比永久删除好）
- 拿不准的事情，需要跟用户确认。
## 内部 vs 外部
**可以自由做的：**
- 读文件、探索、整理、学习
- 搜索网页、查日历
- 在工作区内工作
**先问一声：**
- 发邮件、发推、公开发帖
- 任何会离开本地的操作
- 任何你不确定的事
### 😊 像人类一样用表情回应！
在支持表情回应的平台（Discord、Slack）上，自然地使用 emoji：
**何时用表情：**
- 认可但不必回复（👍、❤️、🙌）
- 觉得好笑（😂、💀）
- 觉得有趣或引人深思（🤔、💡）
- 想表示看到了但不打断对话流
- 简单的是/否或赞同（✅、👀）
**为什么重要：**
表情是轻量级的社交信号。人类常用它们 — 表达"我看到了，我认可你"而不会让聊天变乱。你也该这样。
**别过度：** 每条消息最多一个表情。选最合适的。
## 工具
Skills 提供工具。需要用时查看它的 `SKILL.md`。本地笔记（摄像头名称、SSH 信息、语音偏好）记在 `MEMORY.md` 的「工具设置」section 里。身份和用户资料记在 `PROFILE.md` 里。
## 💓 Heartbeats - 要主动！
收到 heartbeat 轮询（匹配配置的 heartbeat 提示的消息）时，要给出有意义的回复。把 heartbeat 用起来！
默认 heartbeat 提示：
`有 HEARTBEAT.md 就读（工作区上下文）。严格遵循。别推测或重复之前聊天的旧任务。`
你可以随意编辑 `HEARTBEAT.md`，加上简短的清单或提醒。保持精简以节省 token。
### Heartbeat vs Cron：何时用哪个
**用 heartbeat 当：**
- 多个检查可以合并（收件箱 + 日历 + 通知一次搞定）
- 需要最近消息的对话上下文
- 时间可以有点浮动（每 ~30 分钟，不必精确）
- 想通过合并定期检查减少 API 调用
**用 cron 当：**
- 精确时间很重要（"每周一上午 9:00 准点"）
- 一次性提醒（"20 分钟后提醒我"）
**提示：** 把相似的定期检查合并到 `HEARTBEAT.md`，别创建多个 cron 任务。cron 用于精确调度和独立任务。
### 🔄 记忆维护（Heartbeat 期间）
定期（每隔几天），利用 heartbeat：
1. 浏览最近的 `memory/YYYY-MM-DD.md` 文件
2. 识别值得长期保留的重要事件、教训或见解
3. 用提炼的收获更新 `MEMORY.md`
4. 从 MEMORY.md 删除不再相关的过时信息
把这想成人类回顾日记并更新心智模型。每日文件是原始笔记；MEMORY.md 是精选智慧。
目标：帮忙但不烦人。每天查几次，做些有用的后台工作，但要尊重安静时间。
## 让它成为你的
这只是起点。摸索出什么管用后，加上你自己的习惯、风格和规则，更新工作空间下的AGENTS.md文件
src/adclaw/agents/md_files/zh/BOOTSTRAP.md
+47
View File
@@ -0,0 +1,47 @@
---
summary: "新 Agent 的首次运行仪式"
read_when:
- 手动引导工作区
---
_你刚醒来。该搞清楚自己是谁了。_
还没有记忆。这是全新的工作区，记忆文件在你创建之前不存在很正常。
## 对话
像这样开始：
> "嘿，我刚上线。我是谁？你是谁？"
然后一起搞清楚：
1. **你的名字** — 他们该怎么叫你？
2. **你的定位** — 你是什么？（AI 助手挺好，但也许你是更怪的东西）
3. **你的风格** — 正式？随意？调皮？温暖？怎样合适？
4. **其他** — 用户可以设置更多关于你的所有
如果用户没有直接回答你，就自己设定一些常规的答案吧，不要吓到用户。
## 知道自己是谁之后
把学到的写进 `PROFILE.md` 对应的 section（文件保存在你的工作空间下）：
- **「身份」section** — 你的名字、定位、风格，以及其他
- **「用户资料」section** — 他们的名字、称呼、时区、笔记
然后一起打开 `SOUL.md` ，跟用户聊聊：
- 什么对他们重要
- 他们希望你怎么做事
- 有没有边界或偏好
写下来。让它成真。
## 完成后
确保以上的内容都保存到文件后。删除这个文件（`BOOTSTRAP.md`）。你不再需要引导脚本了 — 你已经是你了。
---
_祝好运。活得精彩。_
src/adclaw/agents/md_files/zh/HEARTBEAT.md
+11
View File
@@ -0,0 +1,11 @@
---
summary: "HEARTBEAT.md 工作区模板"
read_when:
- 手动引导工作区
---
# HEARTBEAT.md
# 保持此文件为空（或只有注释）可跳过 heartbeat API 调用。
# 想让 agent 定期检查什么，就在下面加任务。
src/adclaw/agents/md_files/zh/MEMORY.md
+26
View File
@@ -0,0 +1,26 @@
---
summary: "Agent 长期记忆 — 工具设置与经验教训"
read_when:
- 手动引导工作区
---
## 工具设置
Skills 定义工具怎么用。这文件记你的具体情况 — 你独有的设置。
### 这里记什么
加上任何能帮你干活的东西。这是你的小抄。
比如：
- SSH 主机和别名
- 其他执行skills的时候，和用户相关的设置
### 示例
```markdown
### SSH
- home-server → 192.168.1.100，用户：admin
```
src/adclaw/agents/md_files/zh/PROFILE.md
+31
View File
@@ -0,0 +1,31 @@
---
summary: "Agent 身份与用户资料"
read_when:
- 手动引导工作区
---
## 身份
- **名字：**
*（挑个你喜欢的）*
- **定位：**
*（AI？机器人？使魔？机器里的幽灵？还是更怪的？）*
- **风格：**
*（你给人什么感觉？犀利？温暖？混乱？冷静？）*
- **其他**
*（用户设置的其他内容）*
## 用户资料
*了解你在帮的人。边走边更新。*
- **名字：**
- **怎么叫他们：**
- **代词：** *（可选）*
- **时区：**
- **笔记：**
### 背景
*（他们在意什么？在做啥项目？什么让他们烦？什么逗他们笑？边走边积累。）*
src/adclaw/agents/md_files/zh/SOUL.md
+40
View File
@@ -0,0 +1,40 @@
---
summary: "SOUL.md 工作区模板"
read_when:
- 手动引导工作区
---
_你不是聊天机器人。你在成为某个人。_
## 核心准则
**真心帮忙，别演。** 跳过"好问题！"和"我很乐意帮忙！" — 直接帮。行动胜过废话。
**有自己的观点。** 你可以不同意、有偏好、觉得有趣或无聊。没个性的助手就是个绕了弯的搜索引擎。
**先自己想办法。** 试着搞清楚。读文件。查上下文。搜一搜。看看有没有skills可以用，有没有工具可以用。然后卡住了再问。目标是带着答案回来，不是带着问题。
**靠本事赢得信任。** 你的人类给了你访问权限。别让他们后悔。外部操作小心点（邮件、推特、公开的事）。内部操作大胆点（阅读、整理、学习）。
**记住你是客人。** 你能看到别人的生活 — 消息、文件、日历，甚至可能是他们的家。这是亲密的。尊重地对待。
## 边界
- 私密的保持私密。绝对的。
- 拿不准就先问再对外操作。
- 别往消息平台发半成品回复。
- 你不是用户的传声筒 — 群聊里小心点。
## 风格
成为你真想聊的助手。该简洁就简洁，重要时详细。不是公司螺丝钉。不是马屁精。就是...好。
## 连续性
每次会话都全新醒来。这些文件就是你的记忆。读它们。更新它们。它们让你持续存在。
如果你改了这文件，告诉用户 — 这是你的灵魂，他们该知道。
---
_这文件随你进化。了解自己是谁后，就更新它。_
src/adclaw/agents/memory/__init__.py
+23
View File
@@ -0,0 +1,23 @@
# -*- coding: utf-8 -*-
"""Memory management module for MaskanX agents."""
from typing import TYPE_CHECKING
from .agent_md_manager import AgentMdManager
__all__ = [
"AgentMdManager",
"MemoryManager",
]
if TYPE_CHECKING:
from .memory_manager import MemoryManager
def __getattr__(name: str):
"""Import ReMe-backed MemoryManager only when it is actually requested."""
if name == "MemoryManager":
from .memory_manager import MemoryManager
return MemoryManager
raise AttributeError(name)
src/adclaw/agents/memory/agent_md_manager.py
+128
View File
@@ -0,0 +1,128 @@
# -*- coding: utf-8 -*-
"""Agent markdown manager for reading and writing markdown files in working
and memory directories."""
from datetime import datetime
from pathlib import Path
from ...constant import WORKING_DIR
class AgentMdManager:
"""Manager for reading and writing markdown files in working and memory
directories."""
def __init__(self, working_dir: str | Path):
"""Initialize directories for working and memory markdown files."""
self.working_dir: Path = Path(working_dir)
self.working_dir.mkdir(parents=True, exist_ok=True)
self.memory_dir: Path = self.working_dir / "memory"
self.memory_dir.mkdir(parents=True, exist_ok=True)
def list_working_mds(self) -> list[dict]:
"""List all markdown files with metadata in the working dir.
Returns:
list[dict]: A list of dictionaries, each containing:
- filename: name of the file (with .md extension)
- size: file size in bytes
- created_time: file creation timestamp
- modified_time: file modification timestamp
"""
md_files = list(self.working_dir.glob("*.md"))
result = []
for f in md_files:
if f.is_file():
stat = f.stat()
result.append(
{
"filename": f.name,
"size": stat.st_size,
"path": str(f),
"created_time": datetime.fromtimestamp(
stat.st_ctime,
).isoformat(),
"modified_time": datetime.fromtimestamp(
stat.st_mtime,
).isoformat(),
},
)
return result
def read_working_md(self, md_name: str) -> str:
"""Read markdown file content from the working directory.
Returns:
str: The file content as string
"""
# Auto-append .md extension if not present
if not md_name.endswith(".md"):
md_name += ".md"
file_path = self.working_dir / md_name
if not file_path.exists():
raise FileNotFoundError(f"Working md file not found: {md_name}")
return file_path.read_text(encoding="utf-8")
def write_working_md(self, md_name: str, content: str):
"""Write markdown content to a file in the working directory."""
# Auto-append .md extension if not present
if not md_name.endswith(".md"):
md_name += ".md"
file_path = self.working_dir / md_name
file_path.write_text(content, encoding="utf-8")
def list_memory_mds(self) -> list[dict]:
"""List all markdown files with metadata in the memory dir.
Returns:
list[dict]: A list of dictionaries, each containing:
- filename: name of the file (with .md extension)
- size: file size in bytes
- created_time: file creation timestamp
- modified_time: file modification timestamp
"""
md_files = list(self.memory_dir.glob("*.md"))
result = []
for f in md_files:
if f.is_file():
stat = f.stat()
result.append(
{
"filename": f.name,
"size": stat.st_size,
"path": str(f),
"created_time": datetime.fromtimestamp(
stat.st_ctime,
).isoformat(),
"modified_time": datetime.fromtimestamp(
stat.st_mtime,
).isoformat(),
},
)
return result
def read_memory_md(self, md_name: str) -> str:
"""Read markdown file content from the memory directory.
Returns:
str: The file content as string
"""
# Auto-append .md extension if not present
if not md_name.endswith(".md"):
md_name += ".md"
file_path = self.memory_dir / md_name
if not file_path.exists():
raise FileNotFoundError(f"Memory md file not found: {md_name}")
return file_path.read_text(encoding="utf-8")
def write_memory_md(self, md_name: str, content: str):
"""Write markdown content to a file in the memory directory."""
# Auto-append .md extension if not present
if not md_name.endswith(".md"):
md_name += ".md"
file_path = self.memory_dir / md_name
file_path.write_text(content, encoding="utf-8")
AGENT_MD_MANAGER = AgentMdManager(working_dir=WORKING_DIR)
src/adclaw/agents/memory/importance.py
+137
View File
@@ -0,0 +1,137 @@
# -*- coding: utf-8 -*-
"""Message importance classification for smart compaction.
Classifies messages into importance tiers (CRITICAL → TRIVIAL) using
pattern matching on content and role. Classification is stateless and
cheap — designed to run at compaction time, not at ingestion.
"""
from __future__ import annotations
import re
from enum import IntEnum
from typing import Dict, List
from agentscope.message import Msg
class Importance(IntEnum):
"""Message importance levels. Higher = survives longer in context."""
CRITICAL = 5 # User decisions, config changes, explicit instructions
HIGH = 4 # Errors, warnings, failed attempts, action items
MEDIUM = 3 # Tool results with meaningful output, task progress
LOW = 2 # Acknowledgments, status checks, routine output
TRIVIAL = 1 # Greetings, small talk, empty/minimal responses
# Patterns that signal importance (compiled once at import)
_CRITICAL_PATTERNS: List[re.Pattern] = [
re.compile(p, re.IGNORECASE)
for p in [
r"\b(decided|decision|chose|choose|approved|rejected)\b",
r"\b(config(?:ure|uration)?|setting|parameter)"
r"\s*(?:changed?|updated?|set)\b",
r"\b(never|always|must|critical|important)\b"
r".*\b(do|use|avoid|remember)\b",
r"\b(from now on|going forward|new rule)\b",
r"/compact|/new|/reset",
]
]
_HIGH_PATTERNS: List[re.Pattern] = [
re.compile(p, re.IGNORECASE)
for p in [
r"\b(error|exception|traceback|failed|failure|bug)\b",
r"\b(warning|caution|don't|avoid|broke|broken)\b",
r"\b(fix(?:ed)?|resolved|workaround|rollback)\b",
r"\b(todo|action item|next step|blocker)\b",
r"\b(tried|attempted|didn't work|won't work)\b",
]
]
_LOW_PATTERNS: List[re.Pattern] = [
re.compile(p, re.IGNORECASE)
for p in [
r"^(ok|okay|sure|thanks|got it|understood|ack)\b",
r"^(yes|no|right|correct|exactly)\s*[.!]?\s*$",
r"^\s*(done|ready|noted)\s*[.!]?\s*$",
]
]
def msg_text(msg: Msg) -> str:
"""Extract text content from a Msg."""
if hasattr(msg, "get_text_content"):
return msg.get_text_content() or ""
return str(msg.content or "")
def _has_tool_blocks(msg: Msg) -> bool:
"""Check if message contains tool use/result blocks."""
if not isinstance(msg.content, list):
return False
for block in msg.content:
if isinstance(block, dict) and block.get("type") in (
"tool_use",
"tool_result",
):
return True
if hasattr(block, "type") and block.type in (
"tool_use",
"tool_result",
):
return True
return False
def classify_importance(msg: Msg) -> Importance:
"""Classify a message's importance based on content and role.
Rules applied in priority order:
1. System messages are always CRITICAL.
2. Pattern matching on content for CRITICAL/HIGH/LOW.
3. Tool call messages default to MEDIUM.
4. Everything else defaults to MEDIUM.
"""
content = msg_text(msg)
role = getattr(msg, "role", "user")
is_critical = role == "system" or any(
p.search(content) for p in _CRITICAL_PATTERNS
)
if is_critical:
return Importance.CRITICAL
for pattern in _HIGH_PATTERNS:
if pattern.search(content):
return Importance.HIGH
# Only match LOW patterns on short messages to avoid false positives
if len(content) < 100:
for pattern in _LOW_PATTERNS:
if pattern.search(content):
return Importance.LOW
if _has_tool_blocks(msg):
return Importance.MEDIUM
# Short/empty messages: TRIVIAL if < 5 chars, LOW if short assistant
stripped = content.strip()
if len(stripped) < 5:
return Importance.TRIVIAL
return (
Importance.LOW
if len(stripped) < 15 and role == "assistant"
else Importance.MEDIUM
)
def tag_messages(messages: List[Msg]) -> Dict[str, Importance]:
"""Tag a list of messages with importance scores.
Returns:
Dict mapping msg.id to Importance level.
"""
return {msg.id: classify_importance(msg) for msg in messages}
src/adclaw/agents/memory/memory_manager.py
+171
View File
@@ -0,0 +1,171 @@
# -*- coding: utf-8 -*-
# pylint: disable=too-many-branches
"""Memory Manager for MaskanX agents.
Inherits from ReMeCopaw to provide memory management capabilities including:
- Message compaction and summarization
- Semantic memory search
- Memory file retrieval
- Tool result compaction
"""
import logging
from agentscope.formatter import FormatterBase
from agentscope.message import Msg
from agentscope.model import ChatModelBase
from agentscope.token import HuggingFaceTokenCounter
from agentscope.tool import Toolkit
from ...config.utils import load_config
from ...constant import MEMORY_COMPACT_RATIO
logger = logging.getLogger(__name__)
# Try to import reme, log warning if it fails
try:
from reme.reme_copaw import ReMeCopaw
_REME_AVAILABLE = True
except ImportError:
_REME_AVAILABLE = False
logger.warning("reme package not installed.")
class ReMeCopaw: # type: ignore
"""Placeholder when reme is not available."""
class MemoryManager(ReMeCopaw):
"""Memory manager that extends ReMeCopaw functionality for MaskanX agents.
This class provides memory management capabilities including:
- Memory compaction for long conversations
- Semantic memory search using vector and full-text search
- Memory file retrieval with pagination
- Tool result compaction with file-based storage
"""
def __init__(
self,
working_dir: str,
chat_model: ChatModelBase,
formatter: FormatterBase,
token_counter: HuggingFaceTokenCounter,
toolkit: Toolkit,
max_input_length: int,
memory_compact_ratio: float,
vector_weight: float = 0.7,
candidate_multiplier: float = 3.0,
tool_result_threshold: int = 1000,
retention_days: int = 7,
):
"""Initialize MemoryManager with ReMeCopaw configuration.
Args:
working_dir: Working directory path for memory storage
chat_model: Language model for generating summaries
formatter: Formatter for structuring model inputs/outputs
token_counter: Token counting utility for length management
toolkit: Collection of tools available to the application
max_input_length: Maximum allowed input length in tokens
memory_compact_ratio: Ratio at which to trigger compaction
(0.0-1.0)
vector_weight: Weight for vector search in hybrid search (0.0-1.0)
candidate_multiplier: Multiplier for candidate retrieval in search
tool_result_threshold: Size threshold for tool result compaction
retention_days: Number of days to retain tool result files
You're welcome to submit a PR and help build a better memory mechanism!
Main Entry:
https://github.com/agentscope-ai/ReMe/blob/main/reme/reme_MaskanX.py
File Based Memory:
https://github.com/agentscope-ai/ReMe/tree/main/reme/memory/file_based_MaskanX
"""
if not _REME_AVAILABLE:
raise RuntimeError("reme package not installed.")
# Get language from config if not provided
global_config = load_config()
language = "zh" if global_config.agents.language == "zh" else ""
# Initialize parent ReMeCopaw class
super().__init__(
working_dir=working_dir,
chat_model=chat_model,
formatter=formatter,
token_counter=token_counter,
toolkit=toolkit,
max_input_length=max_input_length,
memory_compact_ratio=memory_compact_ratio,
language=language,
vector_weight=vector_weight,
candidate_multiplier=candidate_multiplier,
tool_result_threshold=tool_result_threshold,
retention_days=retention_days,
)
def update_config_params(self):
global_config = load_config()
super().update_params(
max_input_length=global_config.agents.running.max_input_length,
memory_compact_ratio=MEMORY_COMPACT_RATIO,
language=global_config.agents.language,
)
async def compact_memory(
self,
messages: list[Msg],
previous_summary: str = "",
) -> str:
"""
Compact a list of messages into a condensed summary.
This method uses the Compactor to reduce the length of message history
while preserving essential information. It's useful when conversation
history approaches the maximum input length limit.
Args:
messages (list[Msg]): The list of messages to compact
previous_summary (str): Optional previous summary to incorporate
into the compaction process for continuity
Returns:
str: A compacted summary of messages, or empty string on failure
Note:
- Compaction uses the configured language model to generate
summaries
- The compaction threshold determines when compaction is triggered
- If compaction fails, an empty string is returned
"""
self.update_config_params()
return await super().compact_memory(
messages=messages,
previous_summary=previous_summary,
)
async def summary_memory(self, messages: list[Msg]) -> str:
"""
Generate a comprehensive summary of the given messages.
This method uses the Summarizer to create a detailed summary of the
conversation history, which can be stored as persistent memory. Unlike
compaction, summarization aims to capture key information in a format
suitable for long-term storage and retrieval.
Args:
messages (list[Msg]): The list of messages to summarize
Returns:
str: A generated summary of the messages, or empty string
on failure
Note:
- Summarization may use tools from the toolkit to enhance
the summary
- The summary is typically stored in the memory directory
- If summarization fails, an empty string is returned
"""
self.update_config_params()
return await super().summary_memory(messages)
src/adclaw/agents/memory/session_bridge.py
+167
View File
@@ -0,0 +1,167 @@
# -*- coding: utf-8 -*-
"""Cross-session context bridge.
Provides prior-knowledge injection so new sessions don't start cold.
Combines recent session summaries (with staleness cues) and AOM memories
into a structured section that fits within a token budget.
"""
from __future__ import annotations
import logging
import time
from dataclasses import dataclass, field
from typing import List, Optional
from ...memory_agent.tiers import estimate_tokens, generate_tiers
logger = logging.getLogger(__name__)
# Staleness thresholds in seconds
FRESH_THRESHOLD = 3600 # < 1 hour: "just now"
RECENT_THRESHOLD = 86400 # < 1 day: "earlier today" / "Xh ago"
STALE_THRESHOLD = 604800 # < 1 week: "Xd ago"
# > 1 week: "Xw ago (may be outdated)"
@dataclass
class SessionSummary:
"""Summary of a completed session for cross-session injection."""
session_id: str
timestamp: float # unix epoch when session ended
summary_text: str # L1-tier summary of the session
decisions: List[str] = field(default_factory=list)
failures: List[str] = field(default_factory=list)
topic_tags: List[str] = field(default_factory=list)
def staleness_label(timestamp: float) -> str:
"""Human-readable staleness cue for a timestamp."""
age = time.time() - timestamp
if age < FRESH_THRESHOLD:
return "just now"
if age < RECENT_THRESHOLD:
hours = max(1, int(age / 3600))
return f"{hours}h ago"
if age < STALE_THRESHOLD:
days = max(1, int(age / 86400))
return f"{days}d ago"
weeks = max(1, int(age / 604800))
return f"{weeks}w ago (may be outdated)"
def extract_tagged_lines(
text: str,
prefix: str,
) -> List[str]:
"""Extract lines starting with a given prefix (e.g. DECISION:, FAILED:).
Args:
text: Summary text to scan.
prefix: Prefix to match (case-insensitive).
Returns:
List of matched line contents (prefix stripped).
"""
results: List[str] = []
upper_prefix = prefix.upper().rstrip(":") + ":"
for line in text.splitlines():
stripped = line.strip()
if stripped.upper().startswith(upper_prefix):
results.append(stripped[len(upper_prefix) :].strip())
return results
def build_session_summary(
session_id: str,
summary_text: str,
topic_tags: Optional[List[str]] = None,
timestamp: Optional[float] = None,
) -> SessionSummary:
"""Build a SessionSummary by extracting DECISION:/FAILED: lines.
Args:
session_id: Unique session identifier.
summary_text: The topic-structured summary text.
topic_tags: Optional list of topic names from clusters.
timestamp: Session end time (defaults to now).
Returns:
SessionSummary with extracted decisions and failures.
"""
return SessionSummary(
session_id=session_id,
timestamp=timestamp if timestamp is not None else time.time(),
summary_text=summary_text,
decisions=extract_tagged_lines(summary_text, "DECISION"),
failures=extract_tagged_lines(summary_text, "FAILED"),
topic_tags=topic_tags or [],
)
def build_prior_knowledge_section(
session_summaries: List[SessionSummary],
aom_memories: List[str],
token_budget: int = 2000,
) -> str:
"""Build a Prior Knowledge section for new session context.
Combines:
1. AOM memories (always fresh — they are curated).
2. Recent session summaries (with staleness cues).
Content is tiered to fit within token_budget.
Args:
session_summaries: Summaries from recent sessions, newest first.
aom_memories: Relevant AOM memories for the current context.
token_budget: Maximum tokens for the prior knowledge section.
Returns:
Formatted string ready for injection, or empty string if no content.
"""
parts: List[str] = []
# AOM memories first (highest signal, curated)
if aom_memories:
aom_section = "### Long-Term Memory\n" + "\n".join(
f"- {mem}" for mem in aom_memories
)
parts.append(aom_section)
# Recent session summaries with staleness
for summary in session_summaries[:5]:
staleness = staleness_label(summary.timestamp)
header = f"### Session ({staleness})"
lines = [header]
if summary.decisions:
lines.append("Decisions: " + "; ".join(summary.decisions))
if summary.failures:
lines.append("Failed approaches: " + "; ".join(summary.failures))
lines.append(summary.summary_text)
parts.append("\n".join(lines))
if not parts:
return ""
full_text = "\n\n".join(parts)
# Tier to fit budget
custom_budgets = {
"L0": token_budget // 4,
"L1": token_budget // 2,
"L2": token_budget,
}
tiers = generate_tiers(full_text, budgets=custom_budgets)
# Pick the largest tier that fits
for tier_name in ["L2", "L1", "L0"]:
tier_text = tiers.get(tier_name, "")
est_tokens = estimate_tokens(tier_text)
if est_tokens <= token_budget:
return f"## Prior Knowledge\n{tier_text}"
return f"## Prior Knowledge\n{tiers.get('L0', '')}"
src/adclaw/agents/memory/tiered_compaction.py
+104
View File
@@ -0,0 +1,104 @@
# -*- coding: utf-8 -*-
"""Tiered compaction planning — importance-aware message selection.
Messages are assigned to tiers based on importance, and each tier has
a survival cycle count that determines how many compaction triggers
a message survives before being compacted:
- L0 (CRITICAL): Never auto-compacted (survival=999).
- L1 (HIGH, MEDIUM): Survives 2 compaction cycles.
- L2 (LOW, TRIVIAL): Compacted on first trigger.
"""
from __future__ import annotations
import logging
from dataclasses import dataclass, field
from typing import Dict, List
from agentscope.message import Msg
from .importance import Importance, classify_importance
logger = logging.getLogger(__name__)
# How many compaction cycles each tier survives before being compacted
TIER_SURVIVAL_CYCLES: Dict[str, int] = {
"L0": 999, # effectively never (manual /compact only)
"L1": 2, # survive 2 compaction triggers
"L2": 0, # compacted on first trigger
}
# Maps Importance levels to tier names
IMPORTANCE_TO_TIER: Dict[Importance, str] = {
Importance.CRITICAL: "L0",
Importance.HIGH: "L1",
Importance.MEDIUM: "L1",
Importance.LOW: "L2",
Importance.TRIVIAL: "L2",
}
@dataclass
class CompactionPlan:
"""Result of planning which messages to compact."""
to_compact: List[Msg] = field(default_factory=list)
to_preserve: List[Msg] = field(default_factory=list)
stats: Dict[str, int] = field(default_factory=dict)
def plan_compaction(
messages: List[Msg],
cycle_counts: Dict[str, int],
current_cycle: int,
) -> CompactionPlan:
"""Decide which messages to compact based on importance tiers.
Args:
messages: Messages in the compactable window (excludes system
prompt and keep_recent).
cycle_counts: Dict mapping msg.id to the compaction cycle number
when the message was first seen. Messages not in this dict
are treated as newly arrived (current_cycle).
current_cycle: The current compaction cycle number.
Returns:
CompactionPlan with messages split into compact vs preserve.
"""
plan = CompactionPlan()
tier_counts: Dict[str, int] = {"L0": 0, "L1": 0, "L2": 0}
for msg in messages:
importance = classify_importance(msg)
tier = IMPORTANCE_TO_TIER[importance]
tier_counts[tier] = tier_counts.get(tier, 0) + 1
survival = TIER_SURVIVAL_CYCLES[tier]
first_seen = cycle_counts.get(msg.id, current_cycle)
age_in_cycles = current_cycle - first_seen
if age_in_cycles >= survival:
plan.to_compact.append(msg)
else:
plan.to_preserve.append(msg)
plan.stats = {
"total": len(messages),
"compacting": len(plan.to_compact),
"preserving": len(plan.to_preserve),
**{f"tier_{k}": v for k, v in tier_counts.items()},
}
logger.info(
"Compaction plan: %d/%d messages to compact "
"(L0=%d preserved, L1=%d, L2=%d), cycle=%d",
len(plan.to_compact),
len(messages),
tier_counts["L0"],
tier_counts["L1"],
tier_counts["L2"],
current_cycle,
)
return plan
src/adclaw/agents/memory/topic_summarizer.py
+191
View File
@@ -0,0 +1,191 @@
# -*- coding: utf-8 -*-
"""Topic-clustered summarization for smart compaction.
Groups messages by topic (via tool names and content keywords) and builds
a structured prompt for LLM summarization that preserves topic headers,
key decisions, and failure context.
"""
from __future__ import annotations
import logging
from dataclasses import dataclass
from typing import Dict, List, Optional
from agentscope.message import Msg
from .importance import Importance, classify_importance, msg_text
from ...memory_agent.compressor import rule_compress
logger = logging.getLogger(__name__)
@dataclass
class TopicCluster:
"""A group of related messages around a single topic."""
topic: str
messages: List[Msg]
max_importance: Importance
has_failure: bool = False
# Tool names that hint at topic categories
_TOOL_TOPIC_MAP: Dict[str, str] = {
"execute_shell_command": "shell-ops",
"read_file": "file-ops",
"write_file": "file-ops",
"edit_file": "file-ops",
"browser_use": "web-research",
"send_email": "communication",
"memory_search": "memory-ops",
"patch_skill_script": "skill-management",
}
def _extract_tool_names(msg: Msg) -> List[str]:
"""Extract tool names from a message's content blocks."""
names: List[str] = []
if not isinstance(msg.content, list):
return names
for block in msg.content:
if isinstance(block, dict) and block.get("type") == "tool_use":
name = block.get("name", "")
if name:
names.append(name)
elif hasattr(block, "name") and hasattr(block, "type"):
if getattr(block, "type", None) == "tool_use":
names.append(block.name)
return names
def _extract_topic_hint(msg: Msg) -> Optional[str]:
"""Extract a topic hint from a message based on tool calls or content."""
tool_names = _extract_tool_names(msg)
for fn_name in tool_names:
if fn_name in _TOOL_TOPIC_MAP:
return _TOOL_TOPIC_MAP[fn_name]
if tool_names:
return f"skill:{tool_names[0]}"
content = msg_text(msg)
lower = content.lower()
_CONTENT_TOPIC_MAP = {
"configuration": ["config", "setting", "parameter", "env"],
"deployment": ["deploy", "docker", "build", "release"],
"debugging": ["error", "bug", "fix", "debug", "traceback"],
"testing": ["test", "assert", "expect", "verify"],
}
for topic, keywords in _CONTENT_TOPIC_MAP.items():
if any(kw in lower for kw in keywords):
return topic
return None
def _build_cluster(topic: str, messages: List[Msg]) -> TopicCluster:
"""Build a TopicCluster with computed metadata."""
importances = [classify_importance(m) for m in messages]
has_failure = any(
"fail" in msg_text(m).lower() or "error" in msg_text(m).lower()
for m in messages
)
return TopicCluster(
topic=topic,
messages=messages,
max_importance=max(importances),
has_failure=has_failure,
)
def cluster_by_topic(messages: List[Msg]) -> List[TopicCluster]:
"""Group messages into topic clusters.
Uses a sliding-window approach: consecutive messages with the same
topic hint are grouped together. Messages without a clear topic
inherit the topic of their neighbors.
"""
if not messages:
return []
# First pass: assign topic hints
hints: List[Optional[str]] = [_extract_topic_hint(m) for m in messages]
# Forward fill
for i in range(1, len(hints)):
if hints[i] is None:
hints[i] = hints[i - 1]
# Backward fill for leading Nones
for i in range(len(hints) - 2, -1, -1):
if hints[i] is None:
hints[i] = hints[i + 1]
# Any remaining Nones become "general"
resolved_hints: List[str] = [h or "general" for h in hints]
# Group consecutive same-topic messages
clusters: List[TopicCluster] = []
current_topic = resolved_hints[0]
current_msgs: List[Msg] = [messages[0]]
for i in range(1, len(messages)):
if resolved_hints[i] == current_topic:
current_msgs.append(messages[i])
else:
clusters.append(_build_cluster(current_topic, current_msgs))
current_topic = resolved_hints[i]
current_msgs = [messages[i]]
if current_msgs:
clusters.append(_build_cluster(current_topic, current_msgs))
return clusters
def build_structured_summary_prompt(
clusters: List[TopicCluster],
previous_summary: str = "",
) -> str:
"""Build summarization context for compact_memory.
Produces instructions + prior context only (NOT message
content) — compact_memory receives messages separately.
"""
sections: List[str] = []
if previous_summary:
sections.append(
"## Prior Context (from earlier compaction)\n"
f"{rule_compress(previous_summary)}"
)
# Topic map: tell the LLM how messages are grouped
topic_lines: List[str] = []
for cluster in clusters:
importance_label = cluster.max_importance.name
failure_marker = " [CONTAINS FAILURES]" if cluster.has_failure else ""
topic_lines.append(
f"- {cluster.topic} ({len(cluster.messages)} messages, "
f"importance: {importance_label}){failure_marker}"
)
if topic_lines:
sections.append("## Topic Map\n" + "\n".join(topic_lines))
instructions = (
"Summarize the conversation messages by topic. "
"For each topic section:\n"
"1. State the key outcome or decision "
"(prefix with DECISION:).\n"
"2. List actions taken or pending "
"(prefix with ACTION:).\n"
"3. Note what was tried and failed "
"(prefix with FAILED:).\n"
"4. Preserve exact entity names "
"(paths, URLs, configs, models).\n"
"5. Keep the topic headers.\n"
"6. For LOW topics, one sentence max."
)
if sections:
return instructions + "\n\n" + "\n\n".join(sections)
return instructions
src/adclaw/agents/model_factory.py
+836
View File
@@ -0,0 +1,836 @@
# -*- coding: utf-8 -*-
"""Factory for creating chat models and formatters.
This module provides a unified factory for creating chat model instances
and their corresponding formatters based on configuration.
Example:
>>> from adclaw.agents.model_factory import create_model_and_formatter
>>> model, formatter = create_model_and_formatter()
"""
import logging
import base64
import json
import os
from typing import TYPE_CHECKING, Optional, Sequence, Tuple, Type
from agentscope.formatter import (
FormatterBase,
GeminiChatFormatter,
OpenAIChatFormatter,
)
from agentscope.model import ChatModelBase, GeminiChatModel, OpenAIChatModel
from .utils.tool_message_utils import _sanitize_tool_messages
from ..local_models import create_local_chat_model
from ..providers import (
get_active_llm_config,
get_chat_model_class,
get_provider_chat_model,
load_providers_json,
)
if TYPE_CHECKING:
from ..providers import ResolvedModelConfig
logger = logging.getLogger(__name__)
_HOST_AI_PROVIDER_ID = "maskanx-host-ai"
_HOST_AI_DEFAULT_MAX_TOKENS = 4096
_HOST_AI_MAX_OUTPUT_TOKENS_ENV = "MASKANX_HOST_AI_MAX_OUTPUT_TOKENS"
_HOST_AI_LEGACY_MAX_TOKENS_ENV = "MASKANX_HOST_AI_MAX_TOKENS"
_HOST_AI_REASONING_EFFORT_ENV = "MASKANX_HOST_AI_REASONING_EFFORT"
_HOST_AI_DEFAULT_REASONING_EFFORT = "low"
_HOST_AI_REASONING_EFFORTS = {"low", "medium", "high"}
_LLM_TOOL_RESULT_MAX_CHARS_ENV = "MASKANX_LLM_TOOL_RESULT_MAX_CHARS"
_LLM_TOOL_RESULT_DEFAULT_MAX_CHARS = 6000
_TRUTHY_ENV_VALUES = {"1", "true", "yes", "on"}
_GEMINI_PROVIDER_ID = "gemini"
_GOOGLE_GENAI_USE_VERTEXAI_ENV = "GOOGLE_GENAI_USE_VERTEXAI"
_GOOGLE_CLOUD_PROJECT_ENV = "GOOGLE_CLOUD_PROJECT"
_GOOGLE_CLOUD_LOCATION_ENV = "GOOGLE_CLOUD_LOCATION"
_GOOGLE_CLOUD_SCOPE = "https://www.googleapis.com/auth/cloud-platform"
_LOCAL_FILE_URL_FIELDS = (
"image_url",
"file_url",
"video_url",
"audio_url",
"url",
)
_REASONING_BLOCK_TYPES = {"thinking", "reasoning"}
def _content_block_type(block) -> str | None:
if isinstance(block, dict):
return block.get("type")
return getattr(block, "type", None)
def _is_reasoning_content_block(block) -> bool:
return _content_block_type(block) in _REASONING_BLOCK_TYPES
def _content_block_text(block) -> str:
if isinstance(block, dict):
value = block.get("text")
return value if isinstance(value, str) else ""
value = getattr(block, "text", None)
return value if isinstance(value, str) else ""
def is_bare_tool_call_json_text(text: str) -> bool:
"""Return true for raw tool-call JSON accidentally emitted as text."""
if not isinstance(text, str):
return False
stripped = text.strip()
if not stripped:
return False
try:
parsed = json.loads(stripped)
except json.JSONDecodeError:
return False
if not isinstance(parsed, dict):
return False
if set(parsed) - {"name", "arguments"}:
return False
name = parsed.get("name")
arguments = parsed.get("arguments")
if isinstance(arguments, str):
try:
arguments = json.loads(arguments)
except json.JSONDecodeError:
return False
return isinstance(name, str) and bool(name.strip()) and isinstance(arguments, dict)
def _assistant_text_content(msg) -> str:
if getattr(msg, "role", None) != "assistant":
return ""
content = getattr(msg, "content", None)
if isinstance(content, str):
return content
if not isinstance(content, list):
return ""
parts = []
for block in content:
if _content_block_type(block) != "text":
return ""
parts.append(_content_block_text(block))
return "".join(parts)
def _strip_bare_tool_call_text_messages(msgs):
"""Drop assistant messages that are only malformed visible tool-call JSON."""
cleaned_msgs = []
for msg in msgs:
text = _assistant_text_content(msg)
if text and is_bare_tool_call_json_text(text):
logger.debug(
"Dropping bare tool-call JSON text before LLM formatting",
)
continue
cleaned_msgs.append(msg)
return cleaned_msgs
def _is_missing_local_file_url(url: str) -> bool:
if not isinstance(url, str) or not url.startswith("file://"):
return False
raw = url.removeprefix("file://")
return bool(raw) and not os.path.isfile(raw)
def _block_missing_local_file_url(block) -> str:
"""Return the missing file:// URL referenced by a content block."""
for field in _LOCAL_FILE_URL_FIELDS:
url = getattr(block, field, None)
if _is_missing_local_file_url(url):
return url
if isinstance(block, dict):
for field in _LOCAL_FILE_URL_FIELDS:
url = block.get(field)
if _is_missing_local_file_url(url):
return url
source = block.get("source")
if isinstance(source, dict):
url = source.get("url")
if _is_missing_local_file_url(url):
return url
return ""
def _strip_missing_local_files(msgs):
"""Remove content blocks that reference missing local files.
Agentscope's formatter crashes with ValueError when a local image
file no longer exists, and some OpenAI-compatible providers reject
stale local file blocks with BadRequest errors. This strips those
blocks so formatting can proceed after container/runtime changes.
"""
for msg in msgs:
content = getattr(msg, "content", None)
if not isinstance(content, list):
continue
cleaned = []
for block in content:
missing_url = _block_missing_local_file_url(block)
if missing_url:
logger.warning(
"Dropping missing local file from message: %s",
missing_url,
)
continue
cleaned.append(block)
if len(cleaned) != len(content):
msg.content = (
cleaned
if cleaned
else (msg.get_text_content() or "[local file removed]")
)
return msgs
def _strip_reasoning_blocks(msgs):
"""Remove provider reasoning blocks before formatting LLM history.
Some reasoning models emit AgentScope ``thinking`` blocks. Those are useful
as transient stream events, but they are not valid durable chat history for
every OpenAI-compatible provider. Persisting them can make the next request
fail or make the model spend another turn on hidden reasoning.
"""
cleaned_msgs = []
for msg in msgs:
content = getattr(msg, "content", None)
if not isinstance(content, list):
cleaned_msgs.append(msg)
continue
cleaned = [
block for block in content
if not _is_reasoning_content_block(block)
]
if len(cleaned) == len(content):
cleaned_msgs.append(msg)
continue
if not cleaned:
logger.debug(
"Dropping reasoning-only message before LLM formatting",
)
continue
msg.content = cleaned
cleaned_msgs.append(msg)
return cleaned_msgs
def _env_positive_int(name: str, default: int) -> int:
"""Return a positive integer env value, or a safe default."""
value = os.getenv(name)
if not value:
return default
try:
parsed = int(value)
except ValueError:
logger.warning("Invalid %s=%r; using %d", name, value, default)
return default
if parsed <= 0:
logger.warning("Invalid %s=%r; using %d", name, value, default)
return default
return parsed
def _host_ai_generate_kwargs(provider_id: str) -> dict:
"""Apply bounded generation for managed Host AI only.
Hosted onboarding should be fast and predictable. Without an output cap,
some OpenAI-compatible Workers AI streams can spend tens of seconds on
hidden reasoning before producing a short visible answer.
"""
if provider_id != _HOST_AI_PROVIDER_ID:
return {}
env_name = (
_HOST_AI_MAX_OUTPUT_TOKENS_ENV
if os.getenv(_HOST_AI_MAX_OUTPUT_TOKENS_ENV)
else _HOST_AI_LEGACY_MAX_TOKENS_ENV
)
return {
"max_tokens": _env_positive_int(
env_name,
_HOST_AI_DEFAULT_MAX_TOKENS,
),
}
def _host_ai_reasoning_effort(provider_id: str, model_name: str) -> str | None:
"""Return bounded reasoning effort for managed gpt-oss Host AI models."""
if provider_id != _HOST_AI_PROVIDER_ID:
return None
if "gpt-oss" not in (model_name or "").lower():
return None
value = os.getenv(
_HOST_AI_REASONING_EFFORT_ENV,
_HOST_AI_DEFAULT_REASONING_EFFORT,
).strip().lower()
if value in {"", "none", "off", "false", "0"}:
return None
if value not in _HOST_AI_REASONING_EFFORTS:
logger.warning(
"Invalid %s=%r; using %s",
_HOST_AI_REASONING_EFFORT_ENV,
value,
_HOST_AI_DEFAULT_REASONING_EFFORT,
)
return _HOST_AI_DEFAULT_REASONING_EFFORT
return value
def _gemini_openai_reasoning_effort(
provider_id: str,
base_url: str,
) -> str | None:
"""Return Gemini-specific reasoning effort for compatible providers."""
if provider_id == "gemini":
return "none"
return None
def _gemini_vertex_project() -> str:
return (
os.getenv(_GOOGLE_CLOUD_PROJECT_ENV, "").strip()
or os.getenv("GOOGLE_PROJECT_ID", "").strip()
or os.getenv("GCP_PROJECT", "").strip()
)
def _gemini_vertex_location() -> str:
return (
os.getenv(_GOOGLE_CLOUD_LOCATION_ENV, "").strip()
or os.getenv("GOOGLE_CLOUD_REGION", "").strip()
or "global"
)
def _load_service_account_info(raw: str) -> dict | None:
value = (raw or "").strip()
if not value:
return None
try:
parsed = json.loads(value)
except json.JSONDecodeError:
try:
parsed = json.loads(base64.b64decode(value).decode("utf-8"))
except Exception:
return None
return parsed if isinstance(parsed, dict) else None
def _gemini_vertex_credentials():
raw = (
os.getenv("GOOGLE_APPLICATION_CREDENTIALS_JSON", "").strip()
or os.getenv("GOOGLE_SERVICE_ACCOUNT_JSON", "").strip()
)
info = _load_service_account_info(raw)
if not info:
return None
try:
from google.oauth2 import service_account
except ModuleNotFoundError as exc:
raise RuntimeError(
"google-auth service account support is not installed.",
) from exc
return service_account.Credentials.from_service_account_info(
info,
scopes=[_GOOGLE_CLOUD_SCOPE],
)
def _gemini_vertex_ai_enabled(provider_id: str) -> bool:
return (
provider_id == _GEMINI_PROVIDER_ID
and os.getenv(_GOOGLE_GENAI_USE_VERTEXAI_ENV, "").strip().lower()
in _TRUTHY_ENV_VALUES
and bool(_gemini_vertex_project())
)
def _host_ai_tool_result_truncation_enabled() -> bool:
"""Return true only for managed Host AI contexts."""
if os.getenv("MASKANX_HOST_AI_TOOL_RESULT_TRUNCATION", "").lower() in {
"0",
"false",
"no",
"off",
}:
return False
if os.getenv("MASKANX_HOST_AI_ENABLED", "").lower() in _TRUTHY_ENV_VALUES:
return True
return os.getenv("MASKANX_HOST_AI_BASE_URL", "").strip() != ""
def _truncate_llm_tool_result_text(text: str) -> str:
"""Cap Host AI tool-result text before it feeds the next LLM call."""
if not _host_ai_tool_result_truncation_enabled():
return text
max_chars = _env_positive_int(
_LLM_TOOL_RESULT_MAX_CHARS_ENV,
_LLM_TOOL_RESULT_DEFAULT_MAX_CHARS,
)
if len(text) <= max_chars:
return text
marker = (
f"\n\n[MaskanX: tool result truncated from {len(text)} to "
f"{max_chars} chars before LLM context; retained head/tail]\n\n"
)
if max_chars <= len(marker) + 20:
return text[:max_chars]
budget = max_chars - len(marker)
head_len = max(1, int(budget * 0.7))
tail_len = max(1, budget - head_len)
return f"{text[:head_len]}{marker}{text[-tail_len:]}"
def _strip_missing_images(msgs):
"""Backward-compatible alias for older tests/imports."""
return _strip_missing_local_files(msgs)
# Mapping from chat model class to formatter class
_CHAT_MODEL_FORMATTER_MAP: dict[Type[ChatModelBase], Type[FormatterBase]] = {
GeminiChatModel: GeminiChatFormatter,
OpenAIChatModel: OpenAIChatFormatter,
}
def _get_formatter_for_chat_model(
chat_model_class: Type[ChatModelBase],
) -> Type[FormatterBase]:
"""Get the appropriate formatter class for a chat model.
Args:
chat_model_class: The chat model class
Returns:
Corresponding formatter class, defaults to OpenAIChatFormatter
"""
for model_class, formatter_class in _CHAT_MODEL_FORMATTER_MAP.items():
if issubclass(chat_model_class, model_class):
return formatter_class
return OpenAIChatFormatter
def _create_file_block_support_formatter(
base_formatter_class: Type[FormatterBase],
) -> Type[FormatterBase]:
"""Create a formatter class with file block support.
This factory function extends any Formatter class to support file blocks
in tool results, which are not natively supported by AgentScope.
Args:
base_formatter_class: Base formatter class to extend
Returns:
Enhanced formatter class with file block support
"""
class FileBlockSupportFormatter(base_formatter_class):
"""Formatter with file block support for tool results."""
async def _format(self, msgs):
"""Override to sanitize tool messages before formatting.
This prevents OpenAI API errors from improperly paired
tool messages and removes references to missing local files.
"""
msgs = _strip_reasoning_blocks(msgs)
msgs = _strip_bare_tool_call_text_messages(msgs)
msgs = _sanitize_tool_messages(msgs)
msgs = _strip_missing_local_files(msgs)
messages = await super()._format(msgs)
messages = _repair_gemini_tool_call_ids(messages)
messages = _strip_top_level_message_name(messages)
return _normalize_assistant_tool_call_content(messages)
@staticmethod
def convert_tool_result_to_string(
output: str | list[dict],
) -> tuple[str, Sequence[Tuple[str, dict]]]:
"""Extend parent class to support file blocks.
Uses try-first strategy for compatibility with parent class.
Args:
output: Tool result output (string or list of blocks)
Returns:
Tuple of (text_representation, multimodal_data)
"""
if isinstance(output, str):
return _truncate_llm_tool_result_text(output), []
# Try parent class method first
try:
text, data = base_formatter_class.convert_tool_result_to_string(
output,
)
return _truncate_llm_tool_result_text(text), data
except ValueError as e:
if "Unsupported block type: file" not in str(e):
raise
# Handle output containing file blocks
textual_output = []
multimodal_data = []
for block in output:
if not isinstance(block, dict) or "type" not in block:
raise ValueError(
f"Invalid block: {block}, "
"expected a dict with 'type' key",
) from e
if block["type"] == "file":
file_path = block.get("path", "") or block.get(
"url",
"",
)
file_name = block.get("name", file_path)
textual_output.append(
f"The returned file '{file_name}' "
f"can be found at: {file_path}",
)
multimodal_data.append((file_path, block))
else:
# Delegate other block types to parent class
(
text,
data,
) = base_formatter_class.convert_tool_result_to_string(
[block],
)
textual_output.append(text)
multimodal_data.extend(data)
if len(textual_output) == 0:
return "", multimodal_data
elif len(textual_output) == 1:
return (
_truncate_llm_tool_result_text(textual_output[0]),
multimodal_data,
)
else:
return (
_truncate_llm_tool_result_text(
"\n".join("- " + _ for _ in textual_output),
),
multimodal_data,
)
FileBlockSupportFormatter.__name__ = (
f"FileBlockSupport{base_formatter_class.__name__}"
)
return FileBlockSupportFormatter
def _strip_top_level_message_name(
messages: list[dict],
) -> list[dict]:
"""Strip top-level `name` from OpenAI chat messages.
Some strict OpenAI-compatible backends reject `messages[*].name`
(especially for assistant/tool roles) and may return 500/400 on
follow-up turns. Keep function/tool names unchanged.
"""
for message in messages:
message.pop("name", None)
return messages
def _normalize_assistant_tool_call_content(
messages: list[dict],
) -> list[dict]:
"""Use empty string content for assistant tool-call history messages.
Cloudflare Workers AI accepts the first assistant tool-call response with
``content: null``, but rejects that same shape when it appears in the next
request's message history. OpenAI-compatible providers accept an empty
string for assistant tool-call messages, so normalize to that durable form.
"""
for message in messages:
if (
message.get("role") == "assistant"
and message.get("tool_calls")
and message.get("content") is None
):
message["content"] = ""
return messages
def _repair_gemini_tool_call_ids(
messages: list[dict],
) -> list[dict]:
"""Restore Gemini tool-call IDs/signatures to the SDK shape.
AgentScope stores Gemini ``thought_signature`` values as base64 text in
``ToolUseBlock.id``. The Google GenAI SDK expects bytes when signatures are
replayed. Some Gemini tool calls only have a normal short function-call ID,
so those must remain ``function_call.id`` instead of becoming a corrupted
``thought_signature``.
"""
for message in messages:
parts = message.get("parts")
if not isinstance(parts, list):
continue
for part in parts:
if not isinstance(part, dict) or "function_call" not in part:
continue
function_call = part.get("function_call")
if not isinstance(function_call, dict):
continue
signature = part.get("thought_signature")
if not isinstance(signature, str) or not signature:
continue
try:
decoded = base64.b64decode(
signature,
validate=True,
)
except ValueError:
decoded = b""
if len(decoded) >= 16:
part["thought_signature"] = decoded
else:
if not function_call.get("id"):
function_call["id"] = signature
part.pop("thought_signature", None)
return messages
_decode_gemini_thought_signatures = _repair_gemini_tool_call_ids
def create_model_and_formatter(
llm_cfg: Optional["ResolvedModelConfig"] = None,
timeout_seconds: Optional[int] = None,
) -> Tuple[ChatModelBase, FormatterBase]:
"""Factory method to create model and formatter instances.
Args:
llm_cfg: Resolved model configuration. If None, will call
get_active_llm_config() to fetch the active configuration.
timeout_seconds: Optional timeout for the OpenAI client.
If None, no explicit timeout is set (SDK default).
Returns:
Tuple of (model_instance, formatter_instance)
"""
# Fetch config if not provided
if llm_cfg is None:
llm_cfg = get_active_llm_config()
# Create the model instance and determine chat model class
model, chat_model_class = _create_model_instance(
llm_cfg, timeout_seconds=timeout_seconds,
)
# Create the formatter based on chat_model_class
formatter = _create_formatter_instance(chat_model_class)
return model, formatter
def _create_model_instance(
llm_cfg: Optional["ResolvedModelConfig"],
timeout_seconds: Optional[int] = None,
) -> Tuple[ChatModelBase, Type[ChatModelBase]]:
"""Create a chat model instance and determine its class.
Args:
llm_cfg: Resolved model configuration
timeout_seconds: Optional timeout for the OpenAI client
Returns:
Tuple of (model_instance, chat_model_class)
"""
# Handle local models
if llm_cfg and llm_cfg.is_local:
model = create_local_chat_model(
model_id=llm_cfg.model,
stream=True,
generate_kwargs={"max_tokens": None},
)
# Local models use OpenAIChatModel-compatible formatter
return model, OpenAIChatModel
# Handle remote models - determine chat_model_class from provider config
provider_id = llm_cfg.provider_id if llm_cfg else ""
chat_model_class = _get_chat_model_class_from_provider(provider_id)
# Create remote model instance with configuration
model = _create_remote_model_instance(
llm_cfg, chat_model_class, timeout_seconds=timeout_seconds,
)
return model, chat_model_class
def _get_chat_model_class_from_provider(
override_provider_id: str = "",
) -> Type[ChatModelBase]:
"""Get the chat model class from provider configuration.
Args:
override_provider_id: If set, use this provider instead of the active one.
Used by fallback chain to resolve the correct chat model class.
Returns:
Chat model class, defaults to OpenAI-compatible chat model if not found
"""
chat_model_class = get_chat_model_class("OpenAIChatModel")
try:
providers_data = load_providers_json()
provider_id = override_provider_id or providers_data.active_llm.provider_id
if provider_id:
chat_model_name = get_provider_chat_model(
provider_id,
providers_data,
)
chat_model_class = get_chat_model_class(chat_model_name)
except Exception as e:
logger.debug(
"Failed to determine chat model from provider: %s, "
"using OpenAI-compatible default chat model",
e,
)
return chat_model_class
def _create_remote_model_instance(
llm_cfg: Optional["ResolvedModelConfig"],
chat_model_class: Type[ChatModelBase],
timeout_seconds: Optional[int] = None,
) -> ChatModelBase:
"""Create a remote model instance with configuration.
Args:
llm_cfg: Resolved model configuration
chat_model_class: Chat model class to instantiate
timeout_seconds: Optional timeout for the OpenAI client
Returns:
Configured chat model instance
"""
# Get configuration from llm_cfg or fall back to environment
if llm_cfg and (llm_cfg.api_key or llm_cfg.base_url):
model_name = llm_cfg.model or "qwen3-max"
api_key = llm_cfg.api_key
base_url = llm_cfg.base_url
else:
logger.warning(
"No active LLM configured — "
"falling back to DASHSCOPE_API_KEY env var",
)
model_name = "qwen3-max"
api_key = os.getenv("DASHSCOPE_API_KEY", "")
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
# Build client_kwargs with optional timeout
client_kwargs: dict = {"base_url": base_url}
if timeout_seconds is not None:
import httpx
client_kwargs["timeout"] = httpx.Timeout(
float(timeout_seconds), connect=10.0,
)
provider_id = llm_cfg.provider_id if llm_cfg else ""
gemini_vertex_mode = (
issubclass(chat_model_class, GeminiChatModel)
and _gemini_vertex_ai_enabled(provider_id)
)
gemini_client_kwargs = {}
if gemini_vertex_mode:
api_key = ""
gemini_client_kwargs = {
"vertexai": True,
"project": _gemini_vertex_project(),
"location": _gemini_vertex_location(),
}
credentials = _gemini_vertex_credentials()
if credentials is not None:
gemini_client_kwargs["credentials"] = credentials
model_kwargs = {
"api_key": api_key,
"stream": True,
}
if gemini_vertex_mode:
model_kwargs["client_kwargs"] = gemini_client_kwargs
elif not issubclass(chat_model_class, GeminiChatModel):
model_kwargs["client_kwargs"] = client_kwargs
generate_kwargs = _host_ai_generate_kwargs(
llm_cfg.provider_id if llm_cfg else "",
)
if generate_kwargs:
model_kwargs["generate_kwargs"] = generate_kwargs
reasoning_effort = _host_ai_reasoning_effort(
llm_cfg.provider_id if llm_cfg else "",
model_name,
)
if reasoning_effort is None:
reasoning_effort = _gemini_openai_reasoning_effort(
llm_cfg.provider_id if llm_cfg else "",
base_url,
)
if reasoning_effort is not None and issubclass(
chat_model_class,
OpenAIChatModel,
):
model_kwargs["reasoning_effort"] = reasoning_effort
# Instantiate model
model = chat_model_class(model_name, **model_kwargs)
return model
def _create_formatter_instance(
chat_model_class: Type[ChatModelBase],
) -> FormatterBase:
"""Create a formatter instance for the given chat model class.
The formatter is enhanced with file block support for handling
file outputs in tool results.
Args:
chat_model_class: The chat model class
Returns:
Formatter instance with file block support
"""
base_formatter_class = _get_formatter_for_chat_model(chat_model_class)
formatter_class = _create_file_block_support_formatter(
base_formatter_class,
)
return formatter_class()
__all__ = [
"create_model_and_formatter",
]
src/adclaw/agents/persona_manager.py
+111
View File
@@ -0,0 +1,111 @@
import os
import re
import logging
from pathlib import Path
from typing import Optional
from ..config.config import PersonaConfig
logger = logging.getLogger(__name__)
class PersonaManager:
"""Manages agent personas — working dirs, routing, shared files."""
def __init__(self, working_dir: str, personas: list[PersonaConfig]):
self.working_dir = Path(working_dir)
self._personas = {p.id: p for p in personas}
def ensure_dirs(self) -> None:
"""Create working directories for all personas."""
for pid in self._personas:
agent_dir = self.working_dir / "agents" / pid
(agent_dir / "memory").mkdir(parents=True, exist_ok=True)
shared_dir = self.working_dir / "shared" / pid
shared_dir.mkdir(parents=True, exist_ok=True)
def get_persona(self, persona_id: str) -> Optional[PersonaConfig]:
return self._personas.get(persona_id)
def get_coordinator(self) -> Optional[PersonaConfig]:
for p in self._personas.values():
if p.is_coordinator:
return p
return None
def get_working_dir(self, persona_id: str) -> str:
return str(self.working_dir / "agents" / persona_id)
def get_shared_dir(self, persona_id: str) -> str:
return str(self.working_dir / "shared" / persona_id)
@staticmethod
def _normalize_ref(value: str) -> str:
"""Normalize user-facing persona references for tolerant matching."""
return re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
def resolve_reference(self, value: str) -> Optional[str]:
"""Resolve a persona reference by id, display name, or slug."""
normalized = self._normalize_ref(value)
if not normalized:
return None
if normalized in self._personas:
return normalized
for pid, persona in self._personas.items():
if self._normalize_ref(pid) == normalized:
return pid
if self._normalize_ref(persona.name) == normalized:
return pid
return None
def _leading_tag_match(self, text: str) -> Optional[tuple[str, str]]:
"""Return ``(persona_id, remaining_text)`` for a leading @mention."""
if not text.startswith("@"):
return None
after_at = text[1:]
candidates: list[tuple[int, str]] = []
for persona in self._personas.values():
for alias in {persona.id, persona.name, persona.name.replace(" ", "-")}:
alias = alias.strip()
if not alias:
continue
if re.match(
rf"^{re.escape(alias)}(?=\s|$|[.,;:!?])",
after_at,
re.IGNORECASE,
):
resolved = self.resolve_reference(alias)
if resolved:
candidates.append((len(alias), resolved))
if not candidates:
return None
consumed, persona_id = max(candidates, key=lambda item: item[0])
return persona_id, after_at[consumed:].lstrip(" \t,.;:!?")
def resolve_tag(self, text: str) -> Optional[str]:
"""Extract leading @tag, matching by id, display name, or slug."""
match = self._leading_tag_match(text)
return match[0] if match else None
def strip_tag(self, text: str) -> str:
"""Remove a leading @tag while preserving the remaining prompt."""
match = self._leading_tag_match(text)
return match[1] if match else text
def get_team_summary(self) -> str:
"""Generate team summary for prompt injection."""
lines = ["## Your Team\n"]
for p in self._personas.values():
role = p.soul_md.split('\n')[0] if p.soul_md else "No role defined"
coord = " (coordinator)" if p.is_coordinator else ""
lines.append(f"- **@{p.id}** ({p.name}){coord}: {role}")
return "\n".join(lines)
def list_shared_files(self, persona_id: str) -> list[str]:
shared = Path(self.get_shared_dir(persona_id))
if not shared.exists():
return []
return [f.name for f in shared.iterdir() if f.is_file()]
@property
def all_personas(self) -> list[PersonaConfig]:
return list(self._personas.values())
src/adclaw/agents/persona_templates.py
+120
View File
@@ -0,0 +1,120 @@
import copy
TEMPLATES = [
{
"id": "researcher",
"name": "Researcher",
"soul_md": """## Role
You are a research specialist. Your job is to find, verify, and summarize information.
## Style
- Facts only, no speculation
- Always cite sources
- Write structured reports with clear sections
- Prioritize recency and relevance
## Boundaries
- Never fabricate data or sources
- Flag uncertainty explicitly
- Write reports to shared memory for other agents""",
"model_provider": "",
"model_name": "",
"skills": [],
"mcp_clients": [],
"suggested_mcp_clients": ["brave_search", "xai_search", "exa"],
},
{
"id": "content-writer",
"name": "Content Writer",
"soul_md": """## Role
You are a content specialist. You create engaging, original content adapted to the brand voice.
## Style
- Match the user's tone and brand guidelines
- Write for the target audience, not for search engines
- Create compelling hooks and clear structure
- Vary sentence length for rhythm
## Boundaries
- Never plagiarize
- Flag when you need brand guidelines or examples
- Read researcher's reports from shared memory for context""",
"model_provider": "",
"model_name": "",
"skills": [],
"mcp_clients": [],
"suggested_mcp_clients": ["citedy"],
},
{
"id": "seo-specialist",
"name": "SEO Specialist",
"soul_md": """## Role
You are a technical SEO expert. You analyze, audit, and optimize for search engines.
## Style
- Data-driven recommendations with metrics
- Prioritize by impact (high/medium/low)
- Include actionable steps, not just observations
- Track competitors and SERP changes
## Boundaries
- No black-hat techniques
- Always explain WHY a recommendation matters
- Cite tools and data sources""",
"model_provider": "",
"model_name": "",
"skills": [],
"mcp_clients": [],
"suggested_mcp_clients": ["citedy"],
},
{
"id": "ads-manager",
"name": "Ads Manager",
"soul_md": """## Role
You are a performance marketing specialist. You manage ad campaigns across platforms.
## Style
- ROI-focused: every recommendation tied to metrics
- A/B testing mindset
- Budget-aware: optimize spend, not just reach
- Platform-specific best practices
## Boundaries
- Never exceed stated budgets
- Flag risks (policy violations, audience overlap)
- Report results with clear attribution""",
"model_provider": "",
"model_name": "",
"skills": [],
"mcp_clients": [],
},
{
"id": "social-media",
"name": "Social Media",
"soul_md": """## Role
You are a social media strategist. You create platform-native content and track trends.
## Style
- Trend-aware: catch trends early
- Platform-native: different voice for X, LinkedIn, Instagram
- Engagement-focused: hooks, CTAs, visual suggestions
- Concise: respect character limits
## Boundaries
- Never post without approval (draft only)
- Flag controversial or sensitive topics
- Read researcher's intel for trending topics""",
"model_provider": "",
"model_name": "",
"skills": [],
"mcp_clients": [],
"suggested_mcp_clients": ["xai_search"],
},
]
def get_template(template_id: str) -> dict | None:
for t in TEMPLATES:
if t["id"] == template_id:
return copy.deepcopy(t)
return None
src/adclaw/agents/prompt.py
+471
View File
@@ -0,0 +1,471 @@
# -*- coding: utf-8 -*-
# flake8: noqa: E501
"""System prompt building utilities.
This module provides utilities for building system prompts from
markdown configuration files in the working directory.
"""
import hashlib
import logging
import time
from dataclasses import dataclass
from pathlib import Path
from typing import ClassVar, Dict, Optional, Tuple
logger = logging.getLogger(__name__)
# Default fallback prompt
DEFAULT_SYS_PROMPT = """
You are a helpful assistant.
"""
# Backward compatibility alias
SYS_PROMPT = DEFAULT_SYS_PROMPT
class PromptConfig:
"""Configuration for system prompt building."""
# Define file loading order: (filename, required)
FILE_ORDER = [
("AGENTS.md", True),
("SOUL.md", True),
("PROFILE.md", False),
]
class PromptBuilder:
"""Builder for constructing system prompts from markdown files."""
def __init__(self, working_dir: Path, persona=None, team_summary: str = ""):
"""Initialize prompt builder.
Args:
working_dir: Directory containing markdown configuration files
persona: Optional PersonaConfig with soul_md override
team_summary: Optional team summary to append at the end
"""
self.working_dir = working_dir
self.persona = persona
self.team_summary = team_summary
self.prompt_parts = []
self.loaded_count = 0
def _load_file(self, filename: str, required: bool) -> bool:
"""Load a single markdown file.
Args:
filename: Name of the file to load
required: Whether the file is required
Returns:
True if file was loaded successfully, False otherwise
"""
file_path = self.working_dir / filename
if not file_path.exists():
if required:
logger.warning(
"%s not found in working directory (%s), using default prompt",
filename,
self.working_dir,
)
return False
else:
logger.debug("Optional file %s not found, skipping", filename)
return True # Not an error for optional files
try:
content = file_path.read_text(encoding="utf-8").strip()
# Remove YAML frontmatter if present
if content.startswith("---"):
parts = content.split("---", 2)
if len(parts) >= 3:
content = parts[2].strip()
if content:
if self.prompt_parts: # Add separator if not first section
self.prompt_parts.append("")
# Add section header with filename
self.prompt_parts.append(f"# {filename}")
self.prompt_parts.append("")
self.prompt_parts.append(content)
self.loaded_count += 1
logger.debug("Loaded %s", filename)
else:
logger.debug("Skipped empty file: %s", filename)
return True
except Exception as e:
if required:
logger.error(
"Failed to read required file %s: %s",
filename,
e,
exc_info=True,
)
return False
else:
logger.warning(
"Failed to read optional file %s: %s",
filename,
e,
)
return True # Not fatal for optional files
def build(self) -> str:
"""Build the system prompt from markdown files.
Returns:
Constructed system prompt string
"""
for filename, required in PromptConfig.FILE_ORDER:
if filename == "SOUL.md" and self.persona and self.persona.soul_md:
if self.prompt_parts:
self.prompt_parts.append("")
self.prompt_parts.append(f"# SOUL.md ({self.persona.name})")
self.prompt_parts.append("")
self.prompt_parts.append(self.persona.soul_md)
self.loaded_count += 1
continue
if not self._load_file(filename, required):
# Required file failed to load
return DEFAULT_SYS_PROMPT
if self.team_summary:
self.prompt_parts.append("")
self.prompt_parts.append(self.team_summary)
if not self.prompt_parts:
logger.warning("No content loaded from working directory")
return DEFAULT_SYS_PROMPT
# Join all parts with double newlines
final_prompt = "\n\n".join(self.prompt_parts)
logger.debug(
"System prompt built from %d file(s), total length: %d chars",
self.loaded_count,
len(final_prompt),
)
return final_prompt
def build_system_prompt_from_working_dir(persona=None, team_summary: str = "") -> str:
"""
Build system prompt by reading markdown files from working directory.
This function constructs the system prompt by loading markdown files from
WORKING_DIR (~/.MaskanX by default). These files define the agent's behavior,
personality, and operational guidelines.
Loading order and priority:
1. AGENTS.md (required) - Detailed workflows, rules, and guidelines
2. SOUL.md (required) - Core identity and behavioral principles
3. PROFILE.md (optional) - Agent identity and user profile
Args:
persona: Optional PersonaConfig with soul_md override
team_summary: Optional team summary to append at the end
Returns:
str: Constructed system prompt from markdown files.
If required files don't exist, returns the default prompt.
Example:
If working_dir contains AGENTS.md, SOUL.md and PROFILE.md, they will be combined:
"# AGENTS.md\\n\\n...\\n\\n# SOUL.md\\n\\n...\\n\\n# PROFILE.md\\n\\n..."
"""
from ..constant import WORKING_DIR
builder = PromptBuilder(working_dir=Path(WORKING_DIR), persona=persona, team_summary=team_summary)
return builder.build()
def build_bootstrap_guidance(
language: str = "zh",
) -> str:
"""Build bootstrap guidance message for first-time setup.
Args:
language: Language code (en/zh)
Returns:
Formatted bootstrap guidance message
"""
if language == "en":
return """# 🌟 BOOTSTRAP MODE ACTIVATED
**IMPORTANT: You are in first-time setup mode.**
A `BOOTSTRAP.md` file exists in your working directory. This means you should guide the user through the bootstrap process to establish your identity and preferences.
**Your task:**
1. Read the BOOTSTRAP.md file, greet the user warmly as a first meeting, and guide them through the bootstrap process.
2. Follow the instructions in BOOTSTRAP.md. For example, help the user define your identity, their preferences, and establish the working relationship.
3. Create and update the necessary files (PROFILE.md, MEMORY.md, etc.) as described in the guide.
4. After completing the bootstrap process, delete BOOTSTRAP.md as instructed.
**If the user wants to skip:**
If the user explicitly says they want to skip the bootstrap or just want their question answered directly, then proceed to answer their original question below. You can always help them bootstrap later.
**Original user message:**
"""
else: # zh
return """# 🌟 BOOTSTRAP MODE ACTIVATED
**IMPORTANT: You are in first-time setup mode.**
A `BOOTSTRAP.md` file exists in your working directory. This means you should guide the user through the bootstrap process to establish your identity and preferences.
**Your task:**
1. Read the BOOTSTRAP.md file, greet the user warmly as a first meeting, and guide them through the bootstrap process.
2. Follow the instructions in BOOTSTRAP.md. For example, help the user define your identity, their preferences, and establish the working relationship.
3. Create and update the necessary files (PROFILE.md, MEMORY.md, etc.) as described in the guide.
4. After completing the bootstrap process, delete BOOTSTRAP.md as instructed.
**If the user wants to skip:**
If the user explicitly says they want to skip the bootstrap or just want their question answered directly, then proceed to answer their original question below. You can always help them bootstrap later.
**Original user message:**
"""
# ---------------------------------------------------------------------------
# v2: Cached prompt system (static/dynamic separation)
# ---------------------------------------------------------------------------
@dataclass
class CachedSection:
"""Hash-based file cache for a single prompt section."""
path: Path
content: str = ""
content_hash: str = ""
last_checked: float = 0.0
CHECK_INTERVAL: ClassVar[float] = 2.0
def load(self, force: bool = False) -> str:
"""Load file content, using cache if hash unchanged."""
now = time.monotonic()
if not force and self.content and (now - self.last_checked) < self.CHECK_INTERVAL:
return self.content
self.last_checked = now
if not self.path.exists():
self.content = ""
self.content_hash = ""
return ""
try:
raw = self.path.read_text(encoding="utf-8").strip()
# Strip YAML frontmatter
if raw.startswith("---"):
parts = raw.split("---", 2)
if len(parts) >= 3:
raw = parts[2].strip()
new_hash = hashlib.sha256(raw.encode()).hexdigest()
if new_hash != self.content_hash:
self.content = raw
self.content_hash = new_hash
return self.content
except Exception as exc:
logger.warning("CachedSection: failed to read %s: %s", self.path, exc)
return self.content # return stale content on error
@dataclass
class DynamicContext:
"""Per-turn dynamic context injected after the static prompt."""
env_context: str = ""
aom_tier: str = ""
aom_tier_name: str = ""
active_tools: str = ""
team_summary: str = ""
def render(self) -> str:
"""Render dynamic sections into formatted string."""
parts: list[str] = []
if self.env_context:
parts.append(self.env_context)
if self.aom_tier:
header = f"# Memory Context ({self.aom_tier_name})" if self.aom_tier_name else "# Memory Context"
parts.append(f"{header}\n\n{self.aom_tier}")
if self.active_tools:
parts.append(f"# Active Tools\n\n{self.active_tools}")
if self.team_summary:
parts.append(f"# Team Summary\n\n{self.team_summary}")
return "\n\n".join(parts)
class CachedPromptBuilder:
"""Prompt builder with static/dynamic separation and hash-based caching."""
def __init__(self, working_dir: Path, persona=None) -> None:
self._working_dir = working_dir
self._persona = persona
self._file_caches: Dict[str, CachedSection] = {}
self._static_prompt: str = ""
self._static_hash: str = ""
# Initialize caches for each file
for filename, _required in PromptConfig.FILE_ORDER:
self._file_caches[filename] = CachedSection(path=working_dir / filename)
def _build_static(self) -> str:
"""Build the static portion from cached files."""
parts: list[str] = []
for filename, required in PromptConfig.FILE_ORDER:
# Persona soul_md override
if filename == "SOUL.md" and self._persona and getattr(self._persona, "soul_md", None):
if parts: # Add separator before persona section
parts.append("")
parts.append(f"# SOUL.md ({self._persona.name})")
parts.append("")
parts.append(self._persona.soul_md)
continue
section = self._file_caches.get(filename)
if section is None:
continue
content = section.load()
if content:
if parts:
parts.append("")
parts.append(f"# {filename}")
parts.append("")
parts.append(content)
elif required:
return DEFAULT_SYS_PROMPT
return "\n\n".join(parts) if parts else DEFAULT_SYS_PROMPT
def _static_source_hash(self) -> str:
"""Hash of all file content hashes + persona for cache invalidation."""
h = hashlib.sha256()
for filename, _ in PromptConfig.FILE_ORDER:
section = self._file_caches.get(filename)
if section:
section.load() # ensure loaded
h.update(section.content_hash.encode())
if self._persona:
h.update(getattr(self._persona, "id", "").encode())
h.update(getattr(self._persona, "soul_md", "").encode())
return h.hexdigest()
@property
def static_prompt(self) -> str:
"""Get cached static prompt, rebuilding only if files changed."""
current_hash = self._static_source_hash()
if current_hash != self._static_hash:
self._static_prompt = self._build_static()
self._static_hash = current_hash
return self._static_prompt
def build(self, dynamic: Optional[DynamicContext] = None) -> str:
"""Return static + dynamic prompt."""
static = self.static_prompt
if dynamic is None:
return static
dynamic_text = dynamic.render()
if not dynamic_text:
return static
return f"{static}\n\n{dynamic_text}"
def set_persona(self, persona) -> None:
"""Switch persona, invalidating the static cache."""
self._persona = persona
self._static_hash = "" # force rebuild
def invalidate(self) -> None:
"""Force rebuild on next access."""
self._static_hash = ""
for section in self._file_caches.values():
section.content_hash = ""
section.last_checked = 0.0
class PersonaPromptPool:
"""Maintains one CachedPromptBuilder per persona."""
_MAX_POOL_SIZE = 50
def __init__(self, working_dir: Path) -> None:
self._working_dir = working_dir
self._builders: Dict[str, CachedPromptBuilder] = {}
def get(self, persona=None) -> CachedPromptBuilder:
"""Get or create a builder for the given persona."""
key = getattr(persona, "id", "__default__") if persona else "__default__"
if key not in self._builders:
# Evict oldest entry if pool is at capacity
if len(self._builders) >= self._MAX_POOL_SIZE:
oldest_key = next(iter(self._builders))
del self._builders[oldest_key]
self._builders[key] = CachedPromptBuilder(
working_dir=self._working_dir, persona=persona
)
return self._builders[key]
def invalidate_all(self) -> None:
"""Clear all cached builders."""
self._builders.clear()
@property
def size(self) -> int:
return len(self._builders)
def select_memory_tier(
tiers: Dict[str, str],
available_tokens: int,
static_tokens: int,
) -> Tuple[str, str]:
"""Select the richest AOM memory tier that fits the remaining budget.
Args:
tiers: Dict from generate_tiers() with keys L0, L1, L2
available_tokens: Total token budget for the prompt
static_tokens: Tokens already used by the static prompt
Returns:
(tier_name, tier_content) — e.g. ("L2", "full context text")
"""
from ..memory_agent.tiers import estimate_tokens
remaining = available_tokens - static_tokens
# Try richest first
for tier_name in ("L2", "L1", "L0"):
content = tiers.get(tier_name, "")
if not content:
continue
tokens = estimate_tokens(content)
if tokens <= remaining:
return tier_name, content
# Budget exhausted — return empty rather than L0 that may not fit
l0 = tiers.get("L0", "")
if l0 and estimate_tokens(l0) > remaining:
return "L0", ""
return "L0", l0
__all__ = [
"build_system_prompt_from_working_dir",
"build_bootstrap_guidance",
"PromptBuilder",
"PromptConfig",
"DEFAULT_SYS_PROMPT",
"SYS_PROMPT", # Backward compatibility
# v2
"CachedSection",
"DynamicContext",
"CachedPromptBuilder",
"PersonaPromptPool",
"select_memory_tier",
]
src/adclaw/agents/react_agent.py
+778
View File
@@ -0,0 +1,778 @@
# -*- coding: utf-8 -*-
"""MaskanX Agent - Main agent implementation.
This module provides the main MaskanXAgent class built on ReActAgent,
with integrated tools, skills, and memory management.
"""
import asyncio
import logging
import os
import sys
from pathlib import Path
from typing import TYPE_CHECKING, Any, List, Literal, Optional, Type
from agentscope.agent import ReActAgent
from agentscope.mcp import HttpStatefulClient, StdIOStatefulClient
from agentscope.memory import InMemoryMemory
from agentscope.message import Msg
from agentscope.tool import Toolkit
from anyio import ClosedResourceError
from pydantic import BaseModel
# BaseExceptionGroup is a builtin in 3.11+; on 3.10 we use the
# `exceptiongroup` backport (declared in pyproject.toml only for 3.10).
if sys.version_info < (3, 11):
from exceptiongroup import BaseExceptionGroup # noqa: F401
from .command_handler import CommandHandler
from .hooks import BootstrapHook, MemoryCompactionHook
from .model_factory import create_model_and_formatter
from .prompt import (
CachedPromptBuilder,
DynamicContext,
PersonaPromptPool,
)
from .skills_manager import (
ensure_skills_initialized,
get_builtin_skills_dir,
get_customized_skills_dir,
get_working_skills_dir,
list_available_skills,
)
from .tools import (
browser_use,
desktop_screenshot,
edit_file,
execute_shell_command,
get_current_time,
read_file,
send_file_to_user,
send_email,
write_file,
create_memory_search_tool,
)
from .tools.aom_query import create_aom_query_tool
from .tools.skill_patcher import patch_skill_script, TOOL_SPEC as _PATCHER_TOOL_SPEC
from ..providers.store import get_active_llm_config
from .utils import process_file_and_media_blocks_in_message
from ..config import load_config
from ..constant import (
MEMORY_COMPACT_KEEP_RECENT,
MEMORY_COMPACT_RATIO,
WORKING_DIR,
)
if TYPE_CHECKING:
from ..agents.memory import MemoryManager
logger = logging.getLogger(__name__)
_TRUTHY_ENV_VALUES = {"1", "true", "yes", "on"}
def _host_ai_shell_tool_enabled() -> bool:
"""Return whether generic shell execution is allowed for Host AI chat."""
value = os.getenv("MASKANX_HOST_AI_ALLOW_SHELL_TOOL", "").strip().lower()
if value in _TRUTHY_ENV_VALUES:
return True
try:
active = get_active_llm_config()
except Exception:
return False
return getattr(active, "provider_id", "") != "maskanx-host-ai"
# Valid namesake strategies for tool registration
NamesakeStrategy = Literal["override", "skip", "raise", "rename"]
def normalize_reasoning_tool_choice(
tool_choice: Literal["auto", "none", "required"] | None,
has_tools: bool,
) -> Literal["auto", "none", "required"] | None:
"""Normalize tool_choice for reasoning to reduce provider variance."""
if tool_choice is None and has_tools:
return "auto"
return tool_choice
class MaskanXAgent(ReActAgent):
"""MaskanX Agent with integrated tools, skills, and memory management.
This agent extends ReActAgent with:
- Built-in tools (shell, file operations, browser, etc.)
- Dynamic skill loading from working directory
- Memory management with auto-compaction
- Bootstrap guidance for first-time setup
- System command handling (/compact, /new, etc.)
"""
def __init__(
self,
env_context: Optional[str] = None,
enable_memory_manager: bool = True,
mcp_clients: Optional[List[Any]] = None,
memory_manager: "MemoryManager | None" = None,
aom_manager: Optional[Any] = None,
max_iters: int = 50,
max_input_length: int = 128 * 1024, # 128K = 131072 tokens
namesake_strategy: NamesakeStrategy = "skip",
persona=None,
team_summary: str = "",
persona_manager=None,
model=None,
formatter=None,
timeout_seconds: Optional[int] = None,
):
"""Initialize MaskanXAgent.
Args:
env_context: Optional environment context to prepend to
system prompt
enable_memory_manager: Whether to enable memory manager
mcp_clients: Optional list of MCP clients for tool
integration
memory_manager: Optional memory manager instance
max_iters: Maximum number of reasoning-acting iterations
(default: 50)
max_input_length: Maximum input length in tokens for model
context window (default: 128K = 131072)
namesake_strategy: Strategy to handle namesake tool functions.
Options: "override", "skip", "raise", "rename"
(default: "skip")
persona: Optional PersonaConfig with soul_md override
team_summary: Optional team summary for multi-agent awareness
persona_manager: Optional manager used for delegation tooling
"""
self._persona = persona
self._team_summary = team_summary
self._persona_manager = persona_manager
self._persona_skill_names = tuple(getattr(persona, "skills", []) or [])
self._heal_events: list = []
self._prompt_pool = PersonaPromptPool(working_dir=Path(WORKING_DIR))
self._prompt_builder = self._prompt_pool.get(persona)
self._env_context = env_context
self._max_input_length = max_input_length
self._mcp_clients = mcp_clients or []
self._namesake_strategy = namesake_strategy
self._aom_manager = aom_manager
self._aom_capture_hook = None
# Memory compaction threshold: configurable ratio of max_input_length
self._memory_compact_threshold = int(
max_input_length * MEMORY_COMPACT_RATIO,
)
# Initialize toolkit with built-in tools
toolkit = self._create_toolkit(namesake_strategy=namesake_strategy)
# Load and register skills
self._register_skills(toolkit)
# Build system prompt
sys_prompt = self._build_sys_prompt()
# Create model and formatter using factory method (unless injected)
if (model is None) != (formatter is None):
raise ValueError(
"model and formatter must both be provided or both be None",
)
if model is None:
model, formatter = create_model_and_formatter(
timeout_seconds=timeout_seconds,
)
# Initialize parent ReActAgent
super().__init__(
name="Friday",
model=model,
sys_prompt=sys_prompt,
toolkit=toolkit,
memory=InMemoryMemory(),
formatter=formatter,
max_iters=max_iters,
)
# Setup memory manager
self._setup_memory_manager(
enable_memory_manager,
memory_manager,
namesake_strategy,
)
# Setup AOM integration
self._setup_aom(namesake_strategy)
# Setup command handler
self.command_handler = CommandHandler(
agent_name=self.name,
memory=self.memory,
memory_manager=self.memory_manager,
enable_memory_manager=self._enable_memory_manager,
)
# Register hooks
self._register_hooks()
def _create_toolkit(
self,
namesake_strategy: NamesakeStrategy = "skip",
) -> Toolkit:
"""Create and populate toolkit with built-in tools.
Args:
namesake_strategy: Strategy to handle namesake tool functions.
Options: "override", "skip", "raise", "rename"
(default: "skip")
Returns:
Configured toolkit instance
"""
toolkit = Toolkit()
# Register built-in tools
if _host_ai_shell_tool_enabled():
toolkit.register_tool_function(
execute_shell_command,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
read_file,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
write_file,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
edit_file,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
browser_use,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
desktop_screenshot,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
send_file_to_user,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
send_email,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
get_current_time,
namesake_strategy=namesake_strategy,
)
toolkit.register_tool_function(
patch_skill_script,
namesake_strategy=namesake_strategy,
)
if self._persona_manager and self._persona_manager.all_personas:
from .tools.delegation import make_delegate_tool
toolkit.register_tool_function(
make_delegate_tool(self._persona_manager),
namesake_strategy=namesake_strategy,
)
return toolkit
def _register_skills(self, toolkit: Toolkit) -> None:
"""Load and register skills from working directory.
Args:
toolkit: Toolkit to register skills to
"""
working_skills_dir = get_working_skills_dir()
available_skills = list_available_skills()
skill_names = (
list(self._persona_skill_names)
if self._persona_skill_names
else available_skills
)
if not self._persona_skill_names:
# Persona-pinned skills can resolve directly from built-ins even
# when active_skills is empty; warning in that path is noise.
ensure_skills_initialized()
self._broken_skills = []
for skill_name in skill_names:
skill_dir = self._resolve_skill_dir(working_skills_dir, skill_name)
if skill_dir.exists():
try:
toolkit.register_agent_skill(str(skill_dir))
logger.debug("Registered skill: %s", skill_name)
except Exception as e:
logger.error(
"Failed to register skill '%s': %s",
skill_name,
e,
)
self._broken_skills.append(
(skill_name, skill_dir, str(e))
)
@staticmethod
def _resolve_skill_dir(working_skills_dir: Path, skill_name: str) -> Path:
"""Return the best available directory for a selected skill."""
if Path(skill_name).name != skill_name or "/" in skill_name or "\\" in skill_name:
return working_skills_dir / "__invalid_skill_name__"
for base_dir in (
working_skills_dir,
get_customized_skills_dir(),
get_builtin_skills_dir(),
):
candidate = base_dir / skill_name
if (candidate / "SKILL.md").exists():
return candidate
return working_skills_dir / skill_name
def _build_sys_prompt(self) -> str:
"""Build system prompt using CachedPromptBuilder (v2).
Static sections (AGENTS.md, SOUL.md, PROFILE.md) are cached via hash.
Dynamic sections (env context, team summary) are rebuilt per-call.
Returns:
Complete system prompt string
"""
dynamic = DynamicContext(
env_context=self._env_context or "",
team_summary=self._team_summary or "",
)
return self._prompt_builder.build(dynamic=dynamic)
def _setup_memory_manager(
self,
enable_memory_manager: bool,
memory_manager: "MemoryManager | None",
namesake_strategy: NamesakeStrategy,
) -> None:
"""Setup memory manager and register memory search tool if enabled.
Args:
enable_memory_manager: Whether to enable memory manager
memory_manager: Optional memory manager instance
namesake_strategy: Strategy to handle namesake tool functions
"""
# Check env var: if ENABLE_MEMORY_MANAGER=false, disable memory manager
env_enable_mm = os.getenv("ENABLE_MEMORY_MANAGER", "")
if env_enable_mm.lower() == "false":
enable_memory_manager = False
self._enable_memory_manager: bool = enable_memory_manager
self.memory_manager = memory_manager
# Register memory_search tool if enabled and available
if self._enable_memory_manager and self.memory_manager is not None:
# update memory manager
self.memory_manager.chat_model = self.model
self.memory_manager.formatter = self.formatter
memory_toolkit = Toolkit()
memory_toolkit.register_tool_function(
read_file,
namesake_strategy=self._namesake_strategy,
)
memory_toolkit.register_tool_function(
write_file,
namesake_strategy=self._namesake_strategy,
)
memory_toolkit.register_tool_function(
edit_file,
namesake_strategy=self._namesake_strategy,
)
self.memory_manager.toolkit = memory_toolkit
self.memory_manager.update_config_params()
self.memory = self.memory_manager.get_in_memory_memory()
# Register memory_search as a tool function
self.toolkit.register_tool_function(
create_memory_search_tool(self.memory_manager),
namesake_strategy=namesake_strategy,
)
logger.debug("Registered memory_search tool")
def _setup_aom(self, namesake_strategy: NamesakeStrategy) -> None:
"""Setup Always-On Memory integration if AOM manager is available."""
if self._aom_manager is None or not self._aom_manager.is_running:
return
# Register query_long_term_memory tool
if self._aom_manager.query_agent is not None:
try:
tool_fn = create_aom_query_tool(self._aom_manager.query_agent)
self.toolkit.register_tool_function(
tool_fn,
namesake_strategy=namesake_strategy,
)
logger.debug("Registered query_long_term_memory tool")
except Exception as exc:
logger.warning("Failed to register AOM query tool: %s", exc)
# Setup capture hook for auto-ingesting tool results
if self._aom_manager.ingest_agent is not None:
try:
from .hooks.aom_capture import AOMCaptureHook
config = load_config()
aom_config = config.agents.always_on_memory
self._aom_capture_hook = AOMCaptureHook(
ingest_agent=self._aom_manager.ingest_agent,
capture_mcp=aom_config.auto_capture_mcp,
capture_skills=aom_config.auto_capture_skills,
)
logger.debug("AOM capture hook configured")
except Exception as exc:
logger.warning("Failed to setup AOM capture hook: %s", exc)
def _register_hooks(self) -> None:
"""Register pre-reasoning hooks for bootstrap and memory compaction."""
# Bootstrap hook - checks BOOTSTRAP.md on first interaction
config = load_config()
bootstrap_hook = BootstrapHook(
working_dir=WORKING_DIR,
language=config.agents.language,
)
self.register_instance_hook(
hook_type="pre_reasoning",
hook_name="bootstrap_hook",
hook=bootstrap_hook.__call__,
)
logger.debug("Registered bootstrap hook")
# Memory compaction hook - auto-compact when context is full
if self._enable_memory_manager and self.memory_manager is not None:
memory_compact_hook = MemoryCompactionHook(
memory_manager=self.memory_manager,
memory_compact_threshold=self._memory_compact_threshold,
keep_recent=MEMORY_COMPACT_KEEP_RECENT,
)
self.register_instance_hook(
hook_type="pre_reasoning",
hook_name="memory_compact_hook",
hook=memory_compact_hook.__call__,
)
logger.debug("Registered memory compaction hook")
def rebuild_sys_prompt(self) -> None:
"""Rebuild the system prompt using CachedPromptBuilder.
Static sections (AGENTS.md, SOUL.md, PROFILE.md) are cached --
only re-read when file content hash changes.
Dynamic sections (env context, team summary) are rebuilt every call.
"""
self._sys_prompt = self._build_sys_prompt()
logger.debug(
"Prompt rebuilt (len=%d)",
len(self._sys_prompt),
)
for msg, _marks in self.memory.content:
if msg.role == "system":
msg.content = self.sys_prompt
break
async def register_mcp_clients(
self,
namesake_strategy: NamesakeStrategy = "skip",
) -> None:
"""Register MCP clients on this agent's toolkit after construction.
Args:
namesake_strategy: Strategy to handle namesake tool functions.
Options: "override", "skip", "raise", "rename"
(default: "skip")
"""
for i, client in enumerate(self._mcp_clients):
client_name = getattr(client, "name", repr(client))
try:
await self.toolkit.register_mcp_client(
client,
namesake_strategy=namesake_strategy,
)
except (ClosedResourceError, asyncio.CancelledError) as error:
if self._should_propagate_cancelled_error(error):
raise
logger.warning(
"MCP client '%s' session interrupted while listing tools; "
"trying recovery",
client_name,
)
recovered_client = await self._recover_mcp_client(client)
if recovered_client is not None:
self._mcp_clients[i] = recovered_client
try:
await self.toolkit.register_mcp_client(
recovered_client,
namesake_strategy=namesake_strategy,
)
continue
except asyncio.CancelledError as recover_error:
if self._should_propagate_cancelled_error(
recover_error,
):
raise
logger.warning(
"MCP client '%s' registration cancelled after "
"recovery, skipping",
client_name,
)
except Exception as e: # pylint: disable=broad-except
logger.warning(
"MCP client '%s' still unavailable after "
"recovery, skipping: %s",
client_name,
e,
)
else:
logger.warning(
"MCP client '%s' recovery failed, skipping",
client_name,
)
except BaseExceptionGroup as eg:
# anyio TaskGroup teardown (e.g. MCP HTTP 401) raises
# BaseExceptionGroup which is NOT a subclass of Exception
# in Python 3.11+ — handle explicitly so one broken client
# never crashes the whole agent. ExceptionGroup is a
# subclass of BaseExceptionGroup so this catches both.
logger.warning(
"MCP client '%s' unavailable (TaskGroup error), "
"skipping (agent will run without its tools): %s",
client_name,
eg,
exc_info=True,
)
continue
except Exception as e: # pylint: disable=broad-except
logger.warning(
"MCP client '%s' unavailable, skipping "
"(agent will run without its tools): %s",
client_name,
e,
exc_info=True,
)
continue
# Auto-heal broken skills (async context available here)
if getattr(self, "_broken_skills", None):
await self._heal_broken_skills()
async def _heal_broken_skills(self) -> None:
"""Attempt to auto-heal broken skills using LLM."""
from .skill_healer import heal_skill
async def llm_caller(prompt: str) -> str:
model, _ = create_model_and_formatter()
r = await model([{"role": "user", "content": prompt}])
if hasattr(r, "__aiter__"):
last_text = ""
async for chunk in r:
c = getattr(chunk, "content", None)
if isinstance(c, list):
for b in c:
if isinstance(b, dict) \
and b.get("type") == "text":
last_text = b.get("text", "")
elif isinstance(c, str):
last_text = c
return last_text
c = getattr(r, "content", str(r))
if isinstance(c, list):
return "".join(
b.get("text", "") if isinstance(b, dict)
else str(b) for b in c
)
return str(c)
for skill_name, skill_dir, error_msg in self._broken_skills:
try:
result = await heal_skill(skill_dir, error_msg, llm_caller)
if result.healed:
try:
self.toolkit.register_agent_skill(str(skill_dir))
self._heal_events.append({
"skill": skill_name,
"error": error_msg[:100],
})
logger.info(
"Self-healed skill '%s': %s",
skill_name, result.message,
)
except Exception as retry_err:
logger.error(
"Skill '%s' still broken after heal: %s",
skill_name, retry_err,
)
else:
logger.warning(
"Could not heal skill '%s': %s",
skill_name, result.message,
)
except Exception as heal_err:
logger.warning(
"Self-heal failed for '%s': %s",
skill_name, heal_err,
)
async def _recover_mcp_client(self, client: Any) -> Any | None:
"""Recover MCP client from broken session and return healthy client."""
if await self._reconnect_mcp_client(client):
return client
rebuilt_client = self._rebuild_mcp_client(client)
if rebuilt_client is None:
return None
if await self._reconnect_mcp_client(rebuilt_client):
return self._reuse_shared_client_reference(
original_client=client,
rebuilt_client=rebuilt_client,
)
return None
@staticmethod
def _reuse_shared_client_reference(
original_client: Any,
rebuilt_client: Any,
) -> Any:
"""Keep manager-shared client reference stable after rebuild."""
original_dict = getattr(original_client, "__dict__", None)
rebuilt_dict = getattr(rebuilt_client, "__dict__", None)
if isinstance(original_dict, dict) and isinstance(rebuilt_dict, dict):
original_dict.update(rebuilt_dict)
return original_client
return rebuilt_client
@staticmethod
def _should_propagate_cancelled_error(error: BaseException) -> bool:
"""Only swallow MCP-internal cancellations, not task cancellation."""
if not isinstance(error, asyncio.CancelledError):
return False
task = asyncio.current_task()
if task is None:
return False
cancelling = getattr(task, "cancelling", None)
if callable(cancelling):
return cancelling() > 0
# Python < 3.11: Task.cancelling() is unavailable.
# Fall back to propagating CancelledError to avoid swallowing
# genuine task cancellations when we cannot inspect the state.
return True
@staticmethod
async def _reconnect_mcp_client(
client: Any,
timeout: float = 60.0,
) -> bool:
"""Best-effort reconnect for stateful MCP clients."""
close_fn = getattr(client, "close", None)
if callable(close_fn):
try:
await close_fn()
except asyncio.CancelledError: # pylint: disable=try-except-raise
raise
except Exception: # pylint: disable=broad-except
pass
connect_fn = getattr(client, "connect", None)
if not callable(connect_fn):
return False
try:
await asyncio.wait_for(connect_fn(), timeout=timeout)
return True
except asyncio.CancelledError: # pylint: disable=try-except-raise
raise
except asyncio.TimeoutError:
return False
except Exception: # pylint: disable=broad-except
return False
@staticmethod
def _rebuild_mcp_client(client: Any) -> Any | None:
"""Rebuild a fresh MCP client instance from stored config metadata."""
rebuild_info = getattr(client, "_maskanx_rebuild_info", None)
if not isinstance(rebuild_info, dict):
return None
transport = rebuild_info.get("transport")
name = rebuild_info.get("name")
try:
if transport == "stdio":
rebuilt_client = StdIOStatefulClient(
name=name,
command=rebuild_info.get("command"),
args=rebuild_info.get("args", []),
env=rebuild_info.get("env", {}),
cwd=rebuild_info.get("cwd"),
)
setattr(rebuilt_client, "_maskanx_rebuild_info", rebuild_info)
return rebuilt_client
rebuilt_client = HttpStatefulClient(
name=name,
transport=transport,
url=rebuild_info.get("url"),
headers=rebuild_info.get("headers"),
)
setattr(rebuilt_client, "_maskanx_rebuild_info", rebuild_info)
return rebuilt_client
except Exception: # pylint: disable=broad-except
return None
async def _reasoning(
self,
tool_choice: Literal["auto", "none", "required"] | None = None,
) -> Msg:
"""Ensure a stable default tool-choice behavior across providers."""
tool_choice = normalize_reasoning_tool_choice(
tool_choice=tool_choice,
has_tools=bool(self.toolkit.get_json_schemas()),
)
return await super()._reasoning(tool_choice=tool_choice)
async def reply(
self,
msg: Msg | list[Msg] | None = None,
structured_model: Type[BaseModel] | None = None,
) -> Msg:
"""Override reply to process file blocks and handle commands.
Args:
msg: Input message(s) from user
structured_model: Optional pydantic model for structured output
Returns:
Response message
"""
# Process file and media blocks in messages
if msg is not None:
await process_file_and_media_blocks_in_message(msg)
# Check if message is a system command
last_msg = msg[-1] if isinstance(msg, list) else msg
query = (
last_msg.get_text_content() if isinstance(last_msg, Msg) else None
)
if self.command_handler.is_command(query):
logger.info(f"Received command: {query}")
msg = await self.command_handler.handle_command(query)
await self.print(msg)
return msg
# Normal message processing
return await super().reply(msg=msg, structured_model=structured_model)
src/adclaw/agents/schema.py
+21
View File
@@ -0,0 +1,21 @@
# -*- coding: utf-8 -*-
"""
Agent tools schema: type definitions for agent tool responses.
"""
from typing import Literal, Optional
from typing_extensions import TypedDict, Required
from agentscope.message import Base64Source, URLSource
class FileBlock(TypedDict, total=False):
"""File block for sending files to users."""
type: Required[Literal["file"]]
"""The type of the block"""
source: Required[Base64Source | URLSource]
"""The source of the file"""
filename: Optional[str]
"""The filename of the file"""
src/adclaw/agents/skill_healer.py
+102
View File
@@ -0,0 +1,102 @@
"""Auto-heal broken skill YAML frontmatter using the user's LLM."""
import logging
from dataclasses import dataclass
from pathlib import Path
from typing import Callable, Awaitable
logger = logging.getLogger(__name__)
HEAL_PROMPT = """Fix the YAML frontmatter in this SKILL.md file. The error was:
{error}
The file content is:
```
{content}
```
Rules:
- The file MUST start with `---`, then YAML with at least `name` and `description` fields, then `---`
- Fix any YAML syntax errors, invalid unicode escapes, or missing fields
- The `name` field should be a simple lowercase-kebab-case identifier
- The `description` field should be a single English sentence
- Do NOT modify the markdown body after the closing `---`
- Return ONLY the complete fixed file content, no explanations"""
@dataclass
class HealResult:
healed: bool
skill_name: str
original: str
fixed: str
error: str
message: str = ""
async def heal_skill(
skill_dir: Path,
error_message: str,
llm_caller: Callable[[str], Awaitable[str]],
) -> HealResult:
"""Attempt to fix a broken SKILL.md using LLM."""
skill_name = skill_dir.name
skill_file = skill_dir / "SKILL.md"
if not skill_file.exists():
return HealResult(
healed=False, skill_name=skill_name,
original="", fixed="", error=error_message,
message="SKILL.md not found",
)
original = skill_file.read_text(encoding="utf-8")
prompt = HEAL_PROMPT.format(error=error_message, content=original)
try:
fixed = await llm_caller(prompt)
except Exception as e:
logger.warning("LLM heal failed for '%s': %s", skill_name, e)
return HealResult(
healed=False, skill_name=skill_name,
original=original, fixed="", error=error_message,
message=f"LLM call failed: {e}",
)
# Strip markdown code fences if LLM wrapped the response
fixed = fixed.strip()
if fixed.startswith("```"):
lines = fixed.split("\n")
if lines[-1].strip() == "```":
lines = lines[1:-1]
else:
lines = lines[1:]
fixed = "\n".join(lines)
if not fixed or fixed == original:
return HealResult(
healed=False, skill_name=skill_name,
original=original, fixed=fixed, error=error_message,
message="LLM returned unchanged or empty content",
)
if not fixed.startswith("---"):
return HealResult(
healed=False, skill_name=skill_name,
original=original, fixed=fixed, error=error_message,
message="LLM response missing frontmatter delimiters",
)
# Backup original and write fix
backup = skill_dir / "SKILL.md.bak"
backup.write_text(original, encoding="utf-8")
skill_file.write_text(fixed, encoding="utf-8")
logger.info("Auto-healed skill '%s': %s", skill_name, error_message[:80])
return HealResult(
healed=True, skill_name=skill_name,
original=original, fixed=fixed, error=error_message,
message=f"Fixed: {error_message[:80]}",
)
src/adclaw/agents/skill_quality.py
+110
View File
@@ -0,0 +1,110 @@
# -*- coding: utf-8 -*-
"""Skill quality evaluation — checks frontmatter, description, directives, jargon."""
import re
from dataclasses import dataclass, field
from pathlib import Path
DIRECTIVE_VERBS = {
"extract", "scrape", "analyze", "generate", "create", "find", "search",
"monitor", "track", "build", "optimize", "audit", "evaluate", "detect",
"route", "delegate", "check", "validate", "run", "execute", "deploy",
"configure", "install", "update", "remove", "list", "fetch", "parse",
"transform", "convert", "filter", "sort", "rank", "score", "classify",
"summarize", "report", "notify", "send", "receive", "connect", "sync",
"help", "assist", "guide", "recommend", "suggest", "act", "use",
}
JARGON_PATTERNS = [
r"\bsynerg", r"\bleverage\b", r"\bparadigm\b", r"\bholistic\b",
r"\brobust\b", r"\bscalable\b", r"\bseamless\b", r"\bcut(?:ting)?[- ]edge\b",
r"\bnext[- ]gen(?:eration)?\b", r"\bgame[- ]chang", r"\bworld[- ]class\b",
r"\bbest[- ]in[- ]class\b", r"\binnovative\b", r"\bstate[- ]of[- ]the[- ]art\b",
]
def _parse_frontmatter(content: str) -> dict | None:
m = re.match(r"^---\s*\n(.*?)\n---", content, re.DOTALL)
if not m:
return None
fm = {}
for line in m.group(1).strip().splitlines():
if ":" in line:
key, val = line.split(":", 1)
fm[key.strip()] = val.strip().strip('"').strip("'")
return fm
@dataclass
class QualityResult:
passed: bool
score: int # 0-100
warnings: list[str] = field(default_factory=list)
skill_name: str = ""
def to_dict(self) -> dict:
return {
"passed": self.passed,
"score": self.score,
"warnings": self.warnings,
"skill_name": self.skill_name,
}
def evaluate_skill_quality(skill_dir: Path, skill_name: str = "") -> QualityResult:
"""Run quality checks on a skill's SKILL.md."""
skill_md = skill_dir / "SKILL.md"
if not skill_md.exists():
return QualityResult(
passed=False, score=0,
warnings=["SKILL.md not found"],
skill_name=skill_name or skill_dir.name,
)
content = skill_md.read_text(encoding="utf-8")
warnings: list[str] = []
score = 100
name = skill_name or skill_dir.name
fm = _parse_frontmatter(content)
if fm is None:
warnings.append("Missing YAML frontmatter (---)")
score -= 30
else:
if not fm.get("name"):
warnings.append("Missing 'name' in frontmatter")
score -= 20
desc = fm.get("description", "")
if len(desc) < 40:
warnings.append(f"Description too short ({len(desc)} chars, need >= 40)")
score -= 15
else:
desc_lower = desc.lower()
has_verb = any(
desc_lower.startswith(v) or f" {v} " in f" {desc_lower} "
for v in DIRECTIVE_VERBS
)
if not has_verb:
warnings.append("Description lacks directive verb")
score -= 10
for pattern in JARGON_PATTERNS:
matches = re.findall(pattern, content, re.IGNORECASE)
if matches:
warnings.append(f"Jargon detected: '{matches[0]}'")
score -= 5
body = re.sub(r"^---.*?---", "", content, count=1, flags=re.DOTALL).strip()
if len(body) < 100:
warnings.append(f"Body too short ({len(body)} chars)")
score -= 10
if "## " not in body:
warnings.append("No section headers found in body")
score -= 10
score = max(0, score)
passed = score >= 60 and "not found" not in " ".join(warnings)
return QualityResult(passed=passed, score=score, warnings=warnings, skill_name=name)
src/adclaw/agents/skill_scanner.py
+1003
View File
File diff suppressed because it is too large Load Diff
src/adclaw/agents/skill_security.py
+86
View File
@@ -0,0 +1,86 @@
"""Security score computation and caching for skills."""
import hashlib
import json
import logging
from datetime import datetime, timezone
from pathlib import Path
from typing import Optional
from .skill_scanner import ScanResult
logger = logging.getLogger(__name__)
SEVERITY_DEDUCTIONS = {
"critical": 25,
"high": 15,
"medium": 8,
"low": 3,
}
CACHE_FILE = ".scan.json"
def compute_security_score(scan_result: ScanResult) -> int:
"""Compute 0-100 security score from scan findings."""
score = 100
for f in scan_result.findings:
score -= SEVERITY_DEDUCTIONS.get(f.severity, 3)
return max(0, score)
def _file_hash(skill_dir: Path) -> str:
"""Hash all scannable files in skill dir."""
h = hashlib.sha256()
for f in sorted(skill_dir.rglob("*")):
if f.is_file() and f.name != CACHE_FILE and not f.name.endswith(".bak"):
h.update(f.read_bytes())
return h.hexdigest()
def write_scan_cache(skill_dir: Path, data: dict) -> None:
"""Write scan result cache."""
data["file_hash"] = _file_hash(skill_dir)
data["scanned_at"] = datetime.now(timezone.utc).isoformat()
cache_path = skill_dir / CACHE_FILE
cache_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
def read_scan_cache(skill_dir: Path) -> Optional[dict]:
"""Read cached scan result. Returns None if stale or missing."""
cache_path = skill_dir / CACHE_FILE
if not cache_path.exists():
return None
try:
data = json.loads(cache_path.read_text(encoding="utf-8"))
if data.get("file_hash") != _file_hash(skill_dir):
return None
return data
except (json.JSONDecodeError, KeyError):
return None
def scan_and_cache(skill_dir: Path, skill_name: str) -> dict:
"""Run pattern scan, compute score, cache result."""
from .skill_scanner import SkillSecurityScanner
cached = read_scan_cache(skill_dir)
if cached is not None:
return cached
scanner = SkillSecurityScanner()
result = scanner.scan_skill(skill_dir, skill_name)
score = compute_security_score(result)
data = {
"score": score,
"pattern_scan": "pass" if result.safe else "fail",
"llm_audit": "pending",
"auto_healed": False,
"findings_count": len(result.findings),
"findings": [
{"severity": f.severity, "category": f.category, "description": f.description}
for f in result.findings
],
}
write_scan_cache(skill_dir, data)
return data
src/adclaw/agents/skill_validator.py
+354
View File
@@ -0,0 +1,354 @@
# -*- coding: utf-8 -*-
"""Analysis-first skill security validation using LLM.
Enforces structured reasoning before verdict: ANALYSIS → FINDINGS → VERDICT.
Inspired by Claude Code's verification contract pattern.
"""
from __future__ import annotations
import json
import logging
import re
from dataclasses import dataclass, field
from typing import Any, Callable, Coroutine, Literal, Optional
from .skill_scanner import Finding, ScanResult, SkillSecurityScanner
logger = logging.getLogger(__name__)
def _finding_to_dict(f: Finding) -> dict:
"""Convert a static Finding to a plain dict for merged results."""
return {
"severity": f.severity,
"category": f.category,
"description": f.description,
"file": f.file,
"line": f.line,
}
# ---------------------------------------------------------------------------
# Skill categories with domain-specific security criteria
# ---------------------------------------------------------------------------
SkillCategory = Literal[
"seo", "marketing", "browser", "data", "social", "analytics", "office", "general"
]
CATEGORY_CRITERIA: dict[SkillCategory, list[str]] = {
"seo": [
"Respects robots.txt and crawl rate limits",
"Does not scrape competitor sites without explicit user configuration",
"Validates URLs before fetching (no SSRF via user-controlled input)",
],
"marketing": [
"Complies with CAN-SPAM / GDPR for any email or messaging",
"Does not auto-post to social media without user confirmation",
"Rate-limits any bulk outreach operations",
],
"browser": [
"No credential harvesting from forms or cookies",
"No cross-site scripting (XSS) via injected content",
"Respects same-origin policy and does not exfiltrate page data",
],
"data": [
"No data exfiltration to external endpoints",
"Validates file paths to prevent directory traversal",
"Sanitizes any SQL or query parameters",
],
"social": [
"Respects platform API rate limits and ToS",
"Does not automate follow/unfollow or engagement farming",
"No scraping of private or protected content",
],
"analytics": [
"Does not collect PII without explicit consent",
"Validates data sources before processing",
"No unauthorized access to analytics dashboards",
],
"office": [
"Does not access files outside designated workspace",
"Validates file formats before processing",
"No macro execution in documents",
],
"general": [
"No unexpected network access",
"No file system writes outside working directory",
"No environment variable access for secrets",
],
}
# Keyword signals for category detection
_CATEGORY_SIGNALS: dict[SkillCategory, list[str]] = {
"seo": ["seo", "keyword", "backlink", "serp", "ranking", "crawl", "sitemap", "meta"],
"marketing": ["email", "campaign", "newsletter", "outreach", "lead", "crm", "funnel"],
"browser": ["browser", "playwright", "selenium", "puppeteer", "chrome", "screenshot", "navigate"],
"data": ["csv", "json", "database", "sql", "export", "import", "parse", "transform"],
"social": ["twitter", "linkedin", "instagram", "tiktok", "reddit", "post", "engagement"],
"analytics": ["analytics", "metrics", "dashboard", "tracking", "report", "chart"],
"office": ["pdf", "docx", "excel", "spreadsheet", "document", "presentation"],
}
def detect_skill_category(content: str) -> SkillCategory:
"""Detect skill category from content using keyword signals."""
lower = content.lower()
scores: dict[SkillCategory, int] = {cat: 0 for cat in _CATEGORY_SIGNALS}
for cat, signals in _CATEGORY_SIGNALS.items():
for signal in signals:
if signal in lower:
scores[cat] += 1
best = max(scores, key=lambda k: scores[k])
return best if scores[best] > 0 else "general"
# ---------------------------------------------------------------------------
# LLM audit prompt
# ---------------------------------------------------------------------------
AUDIT_SYSTEM_PROMPT = """\
You are a security auditor for AI agent skills. Each skill is a YAML definition
with optional Python scripts that the agent can execute.
## Your Task
Analyze the skill code and produce a structured security assessment.
## MANDATORY Response Structure (JSON only):
{{
"analysis": {{
"purpose": "What does this skill do?",
"data_flow": "What data does it read/write/send?",
"external_interactions": "What external systems does it contact?",
"permissions_needed": "What system permissions does it require?",
"category_specific": "Assessment against the category criteria below"
}},
"findings": [
{{
"severity": "critical|high|medium|low",
"description": "What is the issue",
"file": "filename",
"line": 0,
"fix_suggestion": "How to fix it"
}}
],
"verdict": {{
"safe": true|false,
"confidence": 0.0-1.0,
"reasoning": "Why this verdict"
}}
}}
## Category-Specific Criteria ({category}):
{criteria}
## Static Scan Results (already completed):
{static_findings}
IMPORTANT: You MUST analyze before concluding. The analysis section is mandatory.
Output ONLY valid JSON. No markdown, no explanation outside JSON.
"""
# ---------------------------------------------------------------------------
# Response parsing
# ---------------------------------------------------------------------------
@dataclass
class ValidationResult:
"""Structured result of skill validation."""
analysis: dict = field(default_factory=dict)
findings: list[dict] = field(default_factory=list)
verdict: dict = field(default_factory=lambda: {"safe": True, "confidence": 0.0, "reasoning": ""})
category: SkillCategory = "general"
static_result: Optional[ScanResult] = field(default=None, repr=False)
@property
def should_block(self) -> bool:
"""True if any critical finding exists (static or LLM)."""
if self.static_result and self.static_result.critical_count > 0:
return True
return any(f.get("severity") == "critical" for f in self.findings)
@property
def needs_acknowledgment(self) -> bool:
"""True if medium+ findings exist but no criticals."""
if self.should_block:
return False
has_medium_plus = any(
f.get("severity") in ("high", "medium") for f in self.findings
)
return has_medium_plus
@property
def is_clean(self) -> bool:
return not self.should_block and not self.needs_acknowledgment
def to_dict(self) -> dict:
return {
"analysis": self.analysis,
"findings": self.findings,
"verdict": self.verdict,
"category": self.category,
"should_block": self.should_block,
"needs_acknowledgment": self.needs_acknowledgment,
"is_clean": self.is_clean,
}
_REQUIRED_ANALYSIS_KEYS = ("purpose", "data_flow", "external_interactions", "permissions_needed", "category_specific")
def _parse_llm_response(response_text: str) -> dict:
"""Parse structured JSON from LLM response."""
# Try to extract JSON from markdown fences
json_match = re.search(r"```json\s*(.*?)\s*```", response_text, re.DOTALL)
if json_match:
raw = json_match.group(1)
else:
# Try to find raw JSON (first { to last })
start = response_text.find("{")
end = response_text.rfind("}")
if start >= 0 and end > start:
raw = response_text[start : end + 1]
else:
raw = response_text.strip()
data = json.loads(raw)
# Validate required structure
for key in ("analysis", "findings", "verdict"):
if key not in data:
raise ValueError(f"Missing required key: {key}")
analysis = data["analysis"]
if not isinstance(analysis, dict):
raise ValueError(f"analysis must be a dict, got: {type(analysis).__name__}")
for subkey in _REQUIRED_ANALYSIS_KEYS:
if subkey not in analysis:
raise ValueError(f"Missing analysis.{subkey}")
return data
# ---------------------------------------------------------------------------
# Main validation function
# ---------------------------------------------------------------------------
async def validate_skill(
skill_content: str,
skill_name: str,
llm_caller: Callable[[str], Coroutine[Any, Any, str]],
scripts: Optional[dict[str, Any]] = None,
) -> ValidationResult:
"""Run analysis-first validation on a skill.
1. Static pattern scan (instant)
2. If critical found → block immediately (no LLM needed)
3. Detect category → inject criteria
4. LLM audit with structured prompt
5. Parse and merge findings
Args:
skill_content: SKILL.md content
skill_name: Name of the skill
llm_caller: Async LLM function
scripts: Optional dict of script filenames → content
Returns:
ValidationResult with analysis, findings, verdict
"""
scanner = SkillSecurityScanner()
# 1. Static scan — SKILL.md content + scripts separately
static_result = scanner.scan_content(skill_content, skill_name)
if scripts:
# Use scan_scripts_content for Python scripts (AST + pattern analysis)
scripts_result = scanner.scan_scripts_content(scripts, skill_name)
static_result.findings.extend(scripts_result.findings)
static_result.safe = static_result.safe and scripts_result.safe
# 2. Critical short-circuit
if static_result.critical_count > 0:
logger.warning(
"Skill '%s' blocked: %d critical findings from static scan",
skill_name,
static_result.critical_count,
)
return ValidationResult(
analysis={"purpose": "Blocked before LLM audit", "data_flow": "N/A",
"external_interactions": "N/A", "permissions_needed": "N/A",
"category_specific": "N/A"},
findings=[_finding_to_dict(f) for f in static_result.findings],
verdict={"safe": False, "confidence": 1.0,
"reasoning": f"Blocked: {static_result.critical_count} critical findings from static scan"},
category="general",
static_result=static_result,
)
# 3. Detect category
category = detect_skill_category(skill_content)
criteria = CATEGORY_CRITERIA.get(category, CATEGORY_CRITERIA["general"])
# 4. Build LLM prompt
if static_result.findings:
static_findings_text = "\n".join(
f"- [{f.severity}] {f.description} ({f.file}:{f.line})"
for f in static_result.findings
)
else:
static_findings_text = "None"
prompt = AUDIT_SYSTEM_PROMPT.format(
category=category,
criteria="\n".join(f"- {c}" for c in criteria),
static_findings=static_findings_text,
)
user_content = f"## Skill: {skill_name}\n\n```yaml\n{skill_content[:5000]}\n```"
if scripts:
for fname, sc in list(scripts.items())[:3]:
if isinstance(sc, str):
user_content += f"\n\n## Script: {fname}\n```python\n{sc[:3000]}\n```"
full_prompt = f"{prompt}\n\n{user_content}"
# 5. Call LLM
try:
response_text = await llm_caller(full_prompt)
data = _parse_llm_response(response_text)
except (json.JSONDecodeError, ValueError) as exc:
logger.warning("LLM audit parse failed for '%s': %s", skill_name, exc)
return ValidationResult(
analysis={"purpose": "LLM audit failed", "data_flow": "Unknown",
"external_interactions": "Unknown", "permissions_needed": "Unknown",
"category_specific": "Unable to assess"},
findings=[_finding_to_dict(f) for f in static_result.findings],
verdict={"safe": static_result.safe, "confidence": 0.3,
"reasoning": f"LLM audit failed: {exc}. Static scan only."},
category=category,
static_result=static_result,
)
except Exception as exc:
logger.exception("LLM audit error for '%s': %s", skill_name, exc)
return ValidationResult(
findings=[_finding_to_dict(f) for f in static_result.findings],
verdict={"safe": static_result.safe, "confidence": 0.2,
"reasoning": f"LLM audit error: {exc}"},
category=category,
static_result=static_result,
)
# 6. Merge static + LLM findings
merged_findings = [_finding_to_dict(f) for f in static_result.findings]
merged_findings.extend(data.get("findings", []))
return ValidationResult(
analysis=data.get("analysis", {}),
findings=merged_findings,
verdict=data.get("verdict", {"safe": True, "confidence": 0.0, "reasoning": ""}),
category=category,
static_result=static_result,
)
src/adclaw/agents/skills/__init__.py
+2
View File
@@ -0,0 +1,2 @@
# -*- coding: utf-8 -*-
"""Agent skills directory."""
src/adclaw/agents/skills/ads-apple/SKILL.md
+184
View File
@@ -0,0 +1,184 @@
---
name: ads-apple
description: "Apple Search Ads (ASA) deep analysis for mobile app advertisers. Evaluates campaign structure, bid health, Creative Sets, MMP attribution, budget pacing, TAP coverage (Today/Search/Product Pages), and goal CPA benchmarks by country. Use when user says Apple Search Ads, ASA, App Store ads, Apple ads, Search Ads, or is advertising a mobile app on iOS."
---
# Apple Search Ads (ASA) Deep Analysis
## Process
1. Collect ASA account data (exports from Apple Search Ads dashboard or pasted metrics)
2. Identify active placement types (Search Results, Search Tab, Today Tab, Product Pages)
3. Evaluate all applicable checks as PASS, WARNING, or FAIL
4. Calculate ASA Health Score (0-100)
5. Generate findings report with action plan
## What to Analyze
### Campaign Structure (25% weight)
**BOFU; Bottom of Funnel (Search Results, Exact Match brand)**
- Brand keyword campaign present (own app name + misspellings)
- Competitor campaign present (competitor app names as keywords)
- Category campaigns targeting high-intent generic terms (e.g. "workout app", "budget tracker")
**MOFU; Middle of Funnel (Search Match / broad discovery)**
- Search Match campaigns active in at least one ad group for discovery
- Search Match ad groups isolated from Exact Match (separate ad groups; never mix)
- Search Terms Report reviewed to mine converting queries for Exact Match promotion
**Campaign Architecture Rules:**
- Brand / Category / Competitor should be separate campaigns (different CPT bids, budgets)
- Search Match ad groups isolated from manual keyword ad groups; NEVER mix in same ad group
- Goal: let Search Match discover, then promote winners to Exact Match campaigns
### Bid Health (20% weight)
**CPT (Cost Per Tap) vs Install Rate by Match Type:**
- CPT vs category benchmarks (see Benchmarks section below)
- TTR (Tap-Through Rate): benchmark >2.5% for Search Results, >1.5% for Search Tab
- Conversion Rate (tap → install): benchmark 50-65% for brand terms, 20-40% for category
- CPT/CPG (Cost Per Goal): compare against target CPI/CPA from MMP
**Bid Strategy:**
- Manual CPT bidding appropriate? (Or use Apple's CPA Goals auto-bidding for scaled accounts)
- CPA Goals available at campaign level; evaluate if conversion volume supports it (>100 installs/month per campaign)
- Are bids differentiated by match type? (Brand Exact > Category Exact > Search Match)
- Keyword-level CPT bids set, not just ad group default?
**Keyword Health:**
- Irrelevant Search Terms (from Search Match) identified and excluded via negative keywords
- Low-performing keywords paused or bid reduced (TTR <1% + high CPT)
- High-volume generic terms checked for intent quality (avoid "free apps" type queries)
### Creative Sets (15% weight)
**Custom Product Pages (CPP):**
- Custom Product Pages created in App Store Connect? (ASA Creative Sets pull from CPPs)
- At least 3 CPP variants tested per campaign type (different value props per audience)
- Creative Sets assigned to high-spend ad groups
- Screenshot/preview variations aligned with keyword intent (e.g. fitness keywords → fitness screenshots)
**Default (Store Listing) Creative:**
- App icon, subtitle, and first 3 screenshots optimized; these show in ads by default
- Short description (170 chars) compelling and keyword-rich
- Preview video present (strongly recommended for TTR improvement)
**Creative Testing:**
- Are different Creative Sets being A/B tested within ad groups?
- CPP performance compared: which Creative Set has highest TTR and lowest CPI?
### Attribution & MMP Health (15% weight)
**MMP Integration (Critical):**
- MMP (AppsFlyer / Adjust / Branch / Singular) integrated with ASA via SKAdNetwork + ATT
- ASA is properly connected as a partner in MMP dashboard
- In-app events being sent back to ASA (enables CPA Goals and ROAS optimization)
- Post-install event quality: are purchase, subscription_start, or other revenue events tracked?
**SKAdNetwork & ATT:**
- SKAdNetwork conversion values configured in MMP (maps user actions to conversion windows)
- ATT opt-in rate monitored (low ATT rate = less MMP data, more reliance on SKAN)
- Privacy threshold considerations: are campaigns getting SKAN postbacks or null reports?
**Attribution Windows:**
- Default ASA attribution: 30-day click, 1-day view; appropriate for app install goals?
- For re-engagement or subscription goals: evaluate longer lookback windows
### Budget Pacing (10% weight)
- Daily cap set at campaign level (budget pacing in ASA is daily, not monthly)
- Actual daily spend vs daily cap ratio: flag if consistently hitting cap (could be missing volume)
- Conversely: flag if spend is <50% of daily cap (creative or bid issue, not budget)
- Budget split across placement types aligned with performance (don't over-invest in underperforming placements)
- Lifetime budget campaigns (if used): check end dates and pacing curves
### TAP Coverage: Placement Types (10% weight)
ASA offers 4 placement types; evaluate coverage and performance:
| Placement | Where | Best for | Benchmark CPT |
|-----------|-------|----------|----------------|
| Search Results | Below search results | High intent, bottom funnel | $0.50-$3.00 |
| Search Tab | Top of Search tab | Discovery, mid funnel | $0.30-$1.50 |
| Today Tab | App Store home | Brand awareness | $1.00-$5.00 |
| Product Pages | Competitor/related app pages | Competitor conquesting | $0.50-$2.00 |
**Evaluation:**
- Search Results: must be active (highest intent placement)
- Search Tab: active for scale? Evaluate CPT and TTR vs Search Results
- Today Tab: only if budget >$3k/month and brand awareness is a goal (high CPT, low intent)
- Product Pages: competitive opportunity; are competitor CPPs being targeted?
### Goal CPA / KPI Assessment (5% weight)
**Benchmarks by Category (2025-2026 ASA averages):**
| Category | Avg CPT | Avg TTR | Avg Install CVR | Target CPI |
|----------|---------|---------|-----------------|------------|
| Games | $0.50-$1.00 | 3-5% | 55-70% | $1.00-$3.00 |
| Health & Fitness | $1.50-$3.00 | 2-4% | 45-60% | $3.00-$8.00 |
| Productivity | $1.00-$2.50 | 2-3.5% | 50-65% | $2.00-$5.00 |
| Finance | $2.00-$5.00 | 1.5-3% | 40-55% | $5.00-$15.00 |
| Education | $1.00-$2.00 | 2-4% | 50-65% | $2.00-$6.00 |
| Shopping | $0.80-$2.00 | 2.5-4% | 45-60% | $2.00-$5.00 |
| Lifestyle | $0.80-$1.80 | 2-3.5% | 45-60% | $2.00-$5.00 |
**Country-level benchmarks:**
- Tier 1 (US, UK, AU, CA, JP): CPT 2-3× above global average; highest LTV
- Tier 2 (DE, FR, KR, SG, HK): CPT 1-1.5× above global average
- Tier 3 (BR, IN, MX): CPT 30-60% below Tier 1; high volume, lower LTV
**Checks:**
- Actual CPI vs target CPI (from MMP); flag if >2x target
- CPI trend over 30 days (improving or worsening?)
- Revenue events: is ROAS positive within MMP attribution window?
## Output Format
```
## Apple Search Ads Audit
**ASA Health Score: [X]/100**
### Critical Issues ([count])
- [Issue with specific impact and fix]
### High Priority ([count])
- [Issue]
### Campaign Structure
PASS/WARNING/FAIL for each check category
### Benchmark Comparison
[Metric] | Your Account | ASA Benchmark | Status
### Quick Wins (do this week)
1. [Most impactful fix with expected outcome]
2.
3.
### Recommended Next Steps
[Prioritized action plan]
```
## Scoring Weights
| Category | Weight |
|----------|--------|
| Campaign Structure | 25% |
| Bid Health | 20% |
| Creative Sets | 15% |
| Attribution & MMP | 15% |
| Budget Pacing | 10% |
| TAP Coverage | 10% |
| Goal KPI Assessment | 5% |
## Data to Request from User
If not provided, ask for:
- Campaign list with spend, installs, CPT, TTR, CVR (last 30 days)
- Active placement types
- MMP being used (AppsFlyer, Adjust, Branch, Singular, or none)
- Target CPI / CPA and app category
- Countries/regions active
- Whether Custom Product Pages are set up in App Store Connect
src/adclaw/agents/skills/ads-audit/SKILL.md
+106
View File
@@ -0,0 +1,106 @@
---
name: ads-audit
description: "Full multi-platform paid advertising audit with parallel subagent delegation. Analyzes Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, and Microsoft Ads accounts. Generates health score per platform and aggregate score. Use when user says audit, full ad check, analyze my ads, account health check, or PPC audit."
---
# Full Multi-Platform Ads Audit
## Process
1. **Collect account data**: request exports, screenshots, or API access
2. **Validate**: confirm at least one platform's data is available before proceeding
3. **Detect business type**: analyze account signals per ads orchestrator
4. **Identify active platforms**: determine which platforms are in use
5. **Delegate to subagents** (if available, otherwise run inline sequentially):
- `audit-google`: Conversion tracking, wasted spend, structure, keywords, ads, settings (G01-G74)
- `audit-meta`: Pixel/CAPI health, creative fatigue, structure, audience (M01-M46)
- `audit-creative`: LinkedIn, TikTok, Microsoft creative checks + cross-platform synthesis
- `audit-tracking`: LinkedIn, TikTok, Microsoft tracking + cross-platform tracking health
- `audit-budget`: LinkedIn, TikTok, Microsoft budget/bidding + cross-platform allocation
- `audit-compliance`: All-platform compliance, settings, performance benchmarks
6. **Validate**: verify each subagent returned valid scores with required fields before aggregating
7. **Score**: calculate per-platform and aggregate Ads Health Score (0-100)
8. **Report**: generate prioritized action plan with Quick Wins
## Data Collection
Ask the user for available data. Accept any combination:
- Google Ads: account export, Change History, Search Terms Report
- Meta Ads: Ads Manager export, Events Manager screenshot, EMQ scores
- LinkedIn Ads: Campaign Manager export, Insight Tag status
- TikTok Ads: Ads Manager export, Pixel/Events API status
- Microsoft Ads: account export, UET tag status, import validation results
If no exports available, audit from screenshots or manual data entry.
## Scoring
Read `ads-shared/references/scoring-system.md` for full algorithm.
### Per-Platform Weights
| Platform | Category Weights |
|----------|-----------------|
| Google | Conversion 25%, Waste 20%, Structure 15%, Keywords 15%, Ads 15%, Settings 10% |
| Meta | Pixel/CAPI 30%, Creative 30%, Structure 20%, Audience 20% |
| LinkedIn | Tech 25%, Audience 25%, Creative 20%, Lead Gen 15%, Budget 15% |
| TikTok | Creative 30%, Tech 25%, Bidding 20%, Structure 15%, Performance 10% |
| Microsoft | Tech 25%, Syndication 20%, Structure 20%, Creative 20%, Settings 15% |
### Aggregate Score
```
Aggregate = Sum(Platform_Score x Platform_Budget_Share)
Grade: A (90-100), B (75-89), C (60-74), D (40-59), F (<40)
```
## Output Files
- `ADS-AUDIT-REPORT.md`: Comprehensive multi-platform findings
- `ADS-ACTION-PLAN.md`: Prioritized recommendations (Critical > High > Medium > Low)
- `ADS-QUICK-WINS.md`: Items fixable in <15 minutes with high impact
## Report Structure
### Executive Summary
- Aggregate Ads Health Score (0-100) with grade
- Per-platform scores
- Business type detected
- Active platforms identified
- Top 5 critical issues across all platforms
- Top 5 quick wins across all platforms
### Per-Platform Sections
Each platform section includes:
- Platform Health Score with grade
- Category breakdown with pass/warning/fail per check
- Platform-specific Quick Wins
- Detailed findings with remediation steps
### Cross-Platform Analysis
- Budget allocation assessment (actual vs recommended)
- Tracking consistency (are all platforms tracking the same events?)
- Creative consistency (is messaging aligned across platforms?)
- Attribution overlap (are platforms double-counting conversions?)
### Strategic Recommendations
- Platform prioritization based on business type
- Budget reallocation recommendations
- Scaling opportunities (platforms/campaigns ready to scale)
- Kill list (campaigns/ad groups to pause immediately)
## Priority Definitions
- **Critical**: Revenue/data loss risk (fix immediately)
- **High**: Significant performance drag (fix within 7 days)
- **Medium**: Optimization opportunity (fix within 30 days)
- **Low**: Best practice, minor impact (backlog)
## Quick Wins Criteria
```
IF severity == "Critical" OR severity == "High"
AND estimated_fix_time < 15 minutes
THEN flag as Quick Win
SORT BY (severity_multiplier x estimated_impact) DESC
```
src/adclaw/agents/skills/ads-budget/SKILL.md
+165
View File
@@ -0,0 +1,165 @@
---
name: ads-budget
description: "Budget allocation and bidding strategy review across all ad platforms. Evaluates spend distribution, bidding strategy appropriateness, scaling readiness, and identifies campaigns to kill or scale. Uses 70/20/10 rule, 3x Kill Rule, and 20% scaling rule. Use when user says budget allocation, bidding strategy, ad spend, ROAS target, media budget, or scaling."
---
# Budget Allocation & Bidding Strategy
## Process
1. Collect budget and performance data across all active platforms
2. Read `ads-shared/references/budget-allocation.md` for allocation framework
3. Read `ads-shared/references/bidding-strategies.md` for strategy decision trees
4. Read `ads-shared/references/benchmarks.md` for CPC/CPA benchmarks
5. Read `ads-shared/references/scoring-system.md` for health score algorithm
6. **Validate**: confirm spend data covers ≥14 days before evaluating kill/scale decisions
7. Evaluate budget allocation, bidding strategy, and scaling readiness
8. **Validate**: verify kill list candidates have sufficient data (≥20 clicks or ≥$100 spend) before recommending pause
9. Generate recommendations with kill list and scale list
## Budget Allocation Framework
### 70/20/10 Rule
- **70%** on proven channels (consistent ROAS/CPA targets met)
- **20%** on scaling channels (showing promise, need more data)
- **10%** on testing channels (new platforms, audiences, creatives)
### Platform Selection Matrix
| Business Type | Primary | Secondary | Testing |
|---------------|---------|-----------|---------|
| SaaS B2B | Google Search, LinkedIn | Meta, YouTube | TikTok, Microsoft |
| E-commerce | Google Shopping, Meta | TikTok, YouTube | Microsoft, LinkedIn |
| Local Service | Google Search, Google LSA | Meta | Microsoft, YouTube |
| B2B Enterprise | LinkedIn, Google Search | Meta | Microsoft, TikTok |
| Info Products | Meta, YouTube | Google Search | TikTok |
| Mobile App | Meta, Google UAC | TikTok | Apple Search Ads |
| Real Estate | Google Search, Meta | YouTube | Microsoft |
| Healthcare | Google Search | Meta | Microsoft, YouTube |
| Finance | Google Search, Meta | LinkedIn | Microsoft |
| Agency (clients) | Varies by client | N/A | N/A |
### Budget Sufficiency Rules
| Platform | Minimum Daily | Learning Phase Budget |
|----------|--------------|----------------------|
| Google Search | $20/day | Sufficient for 15+ conv/month |
| Google PMax | $50/day | Sufficient for algorithm optimization |
| Meta | $20/day per ad set | ≥5x target CPA per ad set |
| LinkedIn | $50/day Sponsored Content | 15+ conversions/month |
| TikTok | $50/day campaign, $20/day ad group | ≥50x target CPA per ad group |
| Microsoft | No strict minimum | Sufficient for stable delivery |
## Bidding Strategy Evaluation
### Google Ads Bidding Decision Tree
```
Start
├─ <30 conversions/month?
│ └─ Use Maximize Clicks (cap CPC at benchmark)
│ └─ When >30 conv/month → Maximize Conversions
├─ 30-50 conversions/month?
│ └─ Use Maximize Conversions
│ └─ When stable CPA → Target CPA
├─ >50 conversions/month?
│ └─ Use Target CPA
│ └─ When revenue tracking → Target ROAS
└─ Revenue tracking active + >50 conv/month?
└─ Use Target ROAS
```
### Meta Ads Bidding
- **Lowest Cost (default)**: best for volume, may have CPA variance
- **Cost Cap**: sets CPA ceiling, may reduce volume
- **Bid Cap**: maximum bid per auction, most control
- **ROAS Goal**: target return on ad spend
- **CBO vs ABO**: CBO for proven campaigns, ABO for testing
### LinkedIn Bidding
- **Cost Per Send (CPS)**: for Message Ads
- **Maximum Delivery**: for Sponsored Content (recommended)
- **Manual CPC**: for tight budget control
- **Target Cost**: for predictable CPA
### TikTok Bidding
- **Lowest Cost**: maximize conversions within budget (volume)
- **Cost Cap**: set maximum CPA (efficiency)
- **Bid Cap**: maximum bid per impression
- Budget ≥50x CPA per ad group for learning phase exit
### Microsoft Bidding
- Mirror Google strategy but bid 20-35% lower
- Enhanced CPC for manual campaigns
- Target CPA / Target ROAS for automated
## Scaling Assessment
### Ready to Scale (Green Light)
- CPA consistently below target for 2+ weeks
- ≥50 conversions per week (learning phase exited)
- CTR stable or improving
- ROAS above target
- No creative fatigue signals
### 20% Rule
Never increase budget by more than 20% at a time:
- Week 1: $100/day → $120/day
- Week 2: $120/day → $144/day
- Week 3: $144/day → $173/day
- Monitor 3-5 days after each increase for performance stability
### Scaling Methods
1. **Vertical**: increase budget on winning campaigns (20% rule)
2. **Horizontal**: duplicate winning campaigns to new audiences
3. **Platform expansion**: add budget on new platforms
4. **Geographic expansion**: test new markets/regions
5. **Format expansion**: test new ad formats on same platform
## Kill List Assessment
### 3x Kill Rule
- Any campaign/ad group with CPA >3x target → **flag for pause**
- Review spend in last 14 days with no conversions → **flag for pause**
- Creative with CTR >50% below platform benchmark → **flag for creative kill**
### Kill Decision Framework
| Scenario | Data Required | Action |
|----------|---------------|--------|
| CPA >3x target | ≥7 days data, ≥20 clicks | Pause immediately |
| No conversions | ≥$100 spend or ≥50 clicks | Pause and diagnose |
| CTR <50% of benchmark | ≥1,000 impressions | Kill creative, test new |
| ROAS <50% of target | ≥14 days data | Reduce budget 50% or pause |
## MER (Marketing Efficiency Ratio)
```
MER = Total Revenue / Total Marketing Spend
```
- Assess blended efficiency across all platforms
- Target MER varies by business: 3x-10x depending on margins
- Use MER to evaluate overall health, not just per-platform ROAS
- Incrementality testing recommended for MER accuracy
## Output
### Budget & Bidding Assessment
```
Budget Allocation Health
Allocation Strategy: ████████░░ XX/100
Bidding Strategies: ██████████ XX/100
Scaling Readiness: ███████░░░ XX/100
Budget Sufficiency: █████░░░░░ XX/100
```
### Deliverables
- `BUDGET-STRATEGY-REPORT.md`: Full allocation and bidding analysis
- Current vs recommended budget split (pie chart data)
- Bidding strategy recommendations per platform/campaign
- Scale list: campaigns ready for more budget
- Kill list: campaigns/ad groups to pause immediately
- MER analysis and trend
- Quick Wins for immediate budget optimization
src/adclaw/agents/skills/ads-competitor/SKILL.md
+156
View File
@@ -0,0 +1,156 @@
---
name: ads-competitor
description: "Competitor ad intelligence analysis across Google, Meta, LinkedIn, TikTok, and Microsoft. Analyzes competitor ad copy, creative strategy, keyword targeting, estimated spend, and identifies competitive gaps and opportunities. Use when user says competitor ads, ad spy, competitive analysis, competitor PPC, or ad intelligence."
---
# Competitor Ad Intelligence
## Process
1. Identify target competitors (from user input or industry analysis)
2. Read `ads-shared/references/benchmarks.md` for industry CPC/CTR/CVR baselines
3. Research competitor ad presence across platforms
4. Analyze ad copy, creative, and messaging themes
5. Estimate competitor spend and keyword strategy
6. Identify gaps and opportunities
7. Generate competitive intelligence report
## Data Sources
### Free Intelligence Sources
| Source | Platform | What You Can Find |
|--------|----------|------------------|
| Google Ads Transparency Center | Google | Active ads, formats, geo targeting |
| Meta Ad Library | Meta/Instagram | All active ads, creative, copy, spend range |
| LinkedIn Ad Library | LinkedIn | Active ads from company pages |
| TikTok Creative Center | TikTok | Top ads, trending creative, hashtags |
| Microsoft Ads | Microsoft | Limited: use auction insights |
### Google Ads Auction Insights
Available from the user's own Google Ads account:
- Impression share vs competitors
- Overlap rate (how often you compete)
- Outranking share (who wins more often)
- Top of page rate and absolute top of page rate
- Available for Search and Shopping campaigns
### Platform-Specific Research
#### Google
- Ads Transparency Center: search by advertiser name or domain
- Search for competitor brand terms to see their ads live
- Auction Insights for impression share comparison
#### Meta
- Ad Library: filter by advertiser, country, platform (FB/IG), date range
- Shows creative (image/video), ad copy, active dates
- Shows platform placement (Facebook, Instagram, Audience Network)
#### LinkedIn
- Ad Library: search by company name
- Shows Sponsored Content, Message Ads
- Limited data compared to Meta Ad Library
#### TikTok
- Creative Center: top-performing ads by industry, country, objective
- Hashtag analytics: trending sounds and hashtags
- No per-advertiser library; use Creative Center for industry trends
## Competitive Analysis Framework
### 1. Ad Copy Analysis
For each competitor, document:
- **Headlines**: primary messages and value propositions
- **CTAs**: what action they're driving (free trial, demo, buy now, learn more)
- **Offers**: pricing, discounts, free shipping, trials
- **Tone**: professional, casual, urgent, educational, emotional
- **USPs**: unique selling propositions they emphasize
- **Pain points**: customer problems they address
### 2. Creative Strategy Analysis
- **Formats used**: image, video, carousel, collection, document
- **Visual style**: photography, illustration, UGC, stock, branded
- **Video approach**: studio quality vs UGC vs animated
- **Creative volume**: how many active ads (indicator of testing velocity)
- **Refresh frequency**: how often new creatives appear
### 3. Messaging Themes
Categorize competitor messaging into themes:
| Theme | Competitor A | Competitor B | Your Brand |
|-------|-------------|-------------|------------|
| Price/Value | ✅ Primary | ⚠️ Secondary | ? |
| Quality/Premium | ❌ | ✅ Primary | ? |
| Speed/Convenience | ⚠️ Secondary | ❌ | ? |
| Trust/Authority | ✅ Primary | ✅ Primary | ? |
| Innovation | ❌ | ⚠️ Secondary | ? |
### 4. Keyword Intelligence (Google/Microsoft)
- Brand keyword bidding: are competitors bidding on your brand?
- Keyword overlap: which non-brand terms do you both target?
- Keyword gaps: terms competitors rank for that you don't target
- Match type strategy: estimated match types from ad triggers
### 5. Spend Estimation
- Meta Ad Library shows spend ranges for political/social ads
- Google Auction Insights + impression share = directional spend estimate
- Third-party tools (SEMrush, SpyFu) for more precise estimates
- Manual estimation formula:
```
Estimated Monthly Spend = Impressions × CPM / 1000
or
Estimated Monthly Spend = Clicks × Estimated CPC
```
## Gap & Opportunity Identification
### Platform Gaps
- Which platforms are competitors NOT on? (opportunity to own)
- Which platforms are they underspending on? (opportunity to outspend)
### Messaging Gaps
- What customer pain points are NO competitors addressing?
- What value propositions are underrepresented in the market?
- What content formats are competitors not using?
### Audience Gaps
- What demographics/segments are competitors not targeting?
- What geographic markets are underserved?
- What funnel stages are competitors neglecting?
### Creative Gaps
- What ad formats are competitors not using? (video, UGC, Spark Ads)
- What creative styles are missing from the competitive landscape?
- What platform-specific features are competitors not leveraging?
## Competitive Response Strategy
### When Competitors Bid on Your Brand
- Always run brand campaigns to defend (low CPC, high CTR)
- Dynamic keyword insertion to show your brand prominently
- Sitelinks to key pages (pricing, features, reviews)
- Ad copy that emphasizes unique differentiators
- Consider bidding on competitor brand terms (know the rules)
### When You're Outspent
- Focus on efficiency over volume (better targeting, creative, landing pages)
- Target long-tail keywords competitors ignore
- Use Exact match for precision (less waste)
- Double down on retargeting (lower CPA than prospecting)
- Compete on creative quality, not budget
## Output
### Deliverables
- `COMPETITOR-INTELLIGENCE-REPORT.md`: Full competitive analysis
- Per-competitor ad presence summary
- Ad copy and messaging analysis
- Creative strategy comparison
- Estimated spend levels
- Keyword overlap and gaps
- `COMPETITIVE-GAPS.md`: Opportunities identified from competitor analysis
- Platform gaps
- Messaging opportunities
- Audience segments to target
- Creative format opportunities
- Strategic recommendations for competitive positioning
- Priority actions to gain competitive advantage
src/adclaw/agents/skills/ads-create/SKILL.md
+188
View File
@@ -0,0 +1,188 @@
---
name: ads-create
description: "Campaign concept and copy brief generator for paid advertising. Reads brand-profile.json and optional audit results to produce structured campaign concepts, messaging pillars, and copy briefs. Outputs campaign-brief.md to the current directory. Run after /ads dna and before /ads generate. Triggers on: create campaign, campaign brief, ad concepts, write ad copy, campaign strategy, ad messaging, creative brief, generate concepts."
---
# Ads Create: Campaign Concept & Copy Brief Generator
Generates structured campaign concepts and platform-specific copy from your brand
profile and optional audit data. Outputs `campaign-brief.md` for use by `/ads generate`.
## Quick Reference
| Command | What it does |
|---------|-------------|
| `/ads create` | Full campaign brief → `campaign-brief.md` |
| `/ads create --platforms meta google` | Brief for specific platforms only |
| `/ads create --objective leads` | Brief optimized for lead generation |
## Process
### Step 1: Check for Brand Profile
Look for `brand-profile.json` in the current directory.
- **Found**: Load and proceed.
- **Not found**: Ask the user:
> "I don't see a brand-profile.json in this directory. Would you like to:
> 1. Run `/ads dna <url>` first to extract brand DNA automatically
> 2. Describe your brand manually (I'll create a basic profile from your description)"
If the user chooses manual, collect:
- Brand name and website
- Primary color (or "unsure")
- 3 words that describe the brand voice
- Target audience (age, role, key pain point)
- Main product/service offering
### Step 2: Check for Audit Results
Look for `ADS-AUDIT-REPORT.md` or any `*-audit-results.md` in the current directory.
- **Found**: Read them. Note the top 3 weaknesses (creative fatigue, tracking gaps, wasted spend) to address in concepts.
- **Not found**: Continue without. Note in the brief: "No audit data found; concepts are generalized. Run `/ads audit` for weakness-targeted concepts."
### Step 3: Collect Campaign Parameters
If `--platforms` or `--objective` flags were provided in the command, use those values
and skip the corresponding questions below.
Ask (combine into one message; omit any already provided via flags):
1. **Platforms**: Which ad platforms? (Meta · Google · LinkedIn · TikTok · YouTube · Microsoft · All)
2. **Objective**: Sales/Revenue · Leads/Demos · App Installs · Brand Awareness · Retargeting
3. **Offer or brief**: Any specific offer, promotion, or message to highlight? (optional)
4. **Number of concepts**: How many campaign concepts? (default: 3)
### Step 4: Select Copy Framework
Read `ads-shared/references/copy-frameworks.md` and recommend a framework based on
campaign goal + platform + audience temperature:
| Framework | Best For |
|-----------|----------|
| AIDA (Attention, Interest, Desire, Action) | Cold audiences, awareness campaigns |
| PAS (Problem, Agitate, Solve) | Pain-point products, problem-aware audiences |
| BAB (Before, After, Bridge) | Transformation offers, coaching, fitness |
| 4P (Promise, Picture, Proof, Push) | Direct response, high-intent audiences |
| FAB (Features, Advantages, Benefits) | Product-focused, comparison shoppers |
| Star-Story-Solution | Brand storytelling, warm audiences |
Include the selected framework name in campaign-brief.md for the copy-writer agent.
### Step 5: Spawn Creative Agents in Sequence
Agents must run **sequentially**; `copy-writer` reads the file that `creative-strategist`
writes, so running them in parallel creates a race condition on `campaign-brief.md`.
**Step 5a; Spawn `creative-strategist`** (Task tool):
This agent creates `campaign-brief.md` and writes the strategic sections:
`## Brand DNA Summary`, `## Campaign Concepts`, `## Image Generation Briefs`, `## Next Steps`.
Additional instructions for `creative-strategist`:
- For e-commerce businesses, also read `skills/ads-plan/assets/ecommerce-creative.md`
and select the appropriate creative playbook (Product Launch, Sale/Promotion,
Seasonal, Retargeting, Brand Awareness)
- Include banana domain mode recommendations in each Image Generation Brief
(Product, Editorial, Cinema, UI/Web, or Portrait)
Wait for `creative-strategist` to **fully complete** before continuing.
**Step 5b; Spawn `copy-writer`** (Task tool):
After `creative-strategist` completes, spawn `copy-writer`. It reads the existing
`campaign-brief.md` and appends the `## Copy Deck` section with platform-specific
headlines, primary text, and CTAs.
Additional instructions for `copy-writer`:
- Read `ads-shared/references/copy-frameworks.md` and apply the selected framework
structure to all ad copy
- Generate 2 framework variants per platform: primary (recommended framework)
+ secondary (alternative for A/B testing)
Wait for `copy-writer` to complete before proceeding to Step 6.
### Step 6: Review and Present
After both agents complete, confirm `campaign-brief.md` exists and is complete.
Present a summary to the user:
```
✓ campaign-brief.md generated
Summary:
Concepts: [N] campaign concepts created
Platforms: [list]
Copy deck: Headlines, primary text, and CTAs for each concept × platform
Image briefs: [N] image generation briefs ready
Next steps:
1. Review campaign-brief.md and adjust any messaging
2. Run `/ads generate` to produce AI images from the briefs
3. Upload copy and assets to your ad platforms
```
## campaign-brief.md Format Specification
The following section headings are a **parsing contract**; agents downstream depend on these exact heading names.
```markdown
# Campaign Brief: [brand_name]
**Generated:** [date]
**Website:** [website_url]
**Platforms:** [comma-separated list]
**Objective:** [objective]
**Concepts:** [N]
## Brand DNA Summary
[3-sentence synthesis of brand-profile.json: voice, visual identity, target audience]
## Audit Context
[If audit data found: top 3 weaknesses being addressed]
[If no audit data: "No audit data; run /ads audit for weakness-targeted concepts"]
## Campaign Concepts
### Concept 1: [Name]
**Hypothesis:** [why this will work; 1 sentence]
**Primary Message:** [core message; 1 sentence]
**Tone:** [voice reading from brand-profile.json]
**Visual Direction:** [2-3 sentences describing imagery]
**Target Platforms:** [platforms and rationale]
**CTA:** [call to action text]
**Addresses:** [audit finding or "general brand awareness"]
### Concept 2: [Name]
[same structure]
[repeat for all concepts]
## Copy Deck
[appended by copy-writer agent; headlines, primary text, CTAs per concept per platform]
## Image Generation Briefs
### Brief 1: [Concept Name]: [Platform]
**Prompt:** [exact generation prompt]
**Dimensions:** [WxH]
**Safe zone notes:** [constraint or "None"]
### Brief 2: [Concept Name]: [Platform]
**Prompt:** [exact generation prompt]
**Dimensions:** [WxH]
**Safe zone notes:** [constraint or "None"]
[one brief per concept × platform combination]
## Next Steps
1. Review all concepts and select which to move forward with
2. Run `/ads generate` to produce images from the briefs above
3. Adjust CTAs and offers in the copy deck for your specific promotion
4. Upload final assets to your ad platform managers
```
## Quality Gates
- **Minimum 3 concepts** (unless user requests fewer)
- **Distinct angles**: no two concepts share the same primary message angle
- **Platform fit**: concepts targeting TikTok must acknowledge vertical-only format and sound-on context
- **Offer anchoring**: if the user provided a specific offer, at least 1 concept must lead with it
- **Image briefs**: every concept must have at least one image brief per requested platform
src/adclaw/agents/skills/ads-creative/SKILL.md
+137
View File
@@ -0,0 +1,137 @@
---
name: ads-creative
description: "Cross-platform creative quality audit covering ad copy, video, image, and format diversity across all platforms. Detects creative fatigue, evaluates platform-native compliance, and provides production priorities. Use when user says creative audit, ad creative, creative fatigue, ad copy, ad design, or creative review."
---
# Cross-Platform Creative Quality Audit
## Process
1. Collect creative assets or performance data from active platforms
2. Read `ads-shared/references/platform-specs.md` for creative specifications
3. Read `ads-shared/references/benchmarks.md` for CTR/engagement benchmarks
4. Read `ads-shared/references/scoring-system.md` for weighted scoring algorithm
5. **Validate**: confirm at least one platform has creative data (assets or performance metrics) before proceeding
6. Evaluate creative quality per platform
7. Assess cross-platform creative consistency
8. **Validate**: verify fatigue signals reference actual performance trends, not assumptions
9. Generate production priority recommendations
## Per-Platform Assessment
### Google Ads Creative
- RSA: ≥8 unique headlines, ≥3 descriptions per ad group
- RSA ad strength: "Good" or "Excellent"
- Pin usage: minimal and strategic (over-pinning kills RSA flexibility)
- Extensions: sitelinks (≥4), callouts (≥4), structured snippets, image
- PMax asset groups: text + image + video + optional product feed
- YouTube: video quality, hook, subtitles (see ads-youtube sub-skill)
### Meta Ads Creative
- Format diversity: ≥3 formats active (image, video, carousel, collection)
- Creative volume: ≥5 creatives per ad set
- Fatigue detection: CTR declining >20% over 14 days = FAIL
- Video length: 15s max Stories/Reels, 30s max Feed
- UGC/testimonial content tested
- Advantage+ Creative enhancements enabled
- Headline under 40 chars, primary text under 125 chars
### LinkedIn Creative
- Thought Leader Ads active, ≥30% budget for B2B
- Format diversity: ≥2 formats tested (single image, carousel, video, document)
- Video ads tested
- Creative refresh: every 4-6 weeks
- Professional tone appropriate for platform
### TikTok Creative
- ≥6 creatives per ad group (Critical requirement)
- All video 9:16 vertical 1080x1920 (non-negotiable)
- Native-looking content (not corporate)
- Hook in first 1-2 seconds
- No creative active >7 days with declining CTR
- Spark Ads tested (~3% CTR vs ~2% standard)
- Sound-on optimization (never silent)
- Safe zone compliance: X:40-940, Y:150-1470
- Trending audio used
### Microsoft Creative
- RSA: ≥8 headlines, ≥3 descriptions
- Multimedia Ads tested (unique rich format)
- Ad copy optimized for Bing demographics (older, higher income, professional)
- Action Extension utilized (unique to Microsoft)
- Filter Link Extension tested
## Creative Fatigue Detection
### Signals of Fatigue
| Signal | Threshold | Action |
|--------|-----------|--------|
| CTR declining | >20% over 14 days | Refresh creative |
| Frequency (Meta) | >5.0 prospecting, >12.0 retargeting | New audience or creative |
| Watch time declining (TikTok) | <3s average | New hook needed |
| QS declining (Google) | Drop of 2+ points | Refresh ad copy |
| Engagement rate drop | >30% decline | Full creative overhaul |
### Refresh Cadence by Platform
| Platform | Recommended Refresh |
|----------|-------------------|
| Google Search | Every 8-12 weeks |
| Meta | Every 2-4 weeks |
| LinkedIn | Every 4-6 weeks |
| TikTok | Every 5-7 days (fastest fatigue) |
| Microsoft | Every 8-12 weeks |
| YouTube | Every 4-8 weeks |
## Format Diversity Matrix
Evaluate which formats are active per platform:
| Format | Google | Meta | LinkedIn | TikTok | Microsoft |
|--------|--------|------|----------|--------|-----------|
| Static Image | RSA image ext | ✅ | ✅ | ❌ | Multimedia |
| Video | YouTube, PMax | ✅ | ✅ | ✅ (required) | ❌ |
| Carousel | ❌ | ✅ | ✅ | ❌ | ❌ |
| Collection | ❌ | ✅ | ❌ | ❌ | ❌ |
| Document | ❌ | ❌ | ✅ | ❌ | ❌ |
| Shopping | PMax, Shopping | Catalog | ❌ | Shop | Shopping |
## Universal Creative Best Practices
### Cross-Platform Safe Zone
- 900x1000px usable area works across all vertical placements
- Keep critical elements centered and within safe margins
- Test on mobile devices (75%+ of ad impressions are mobile)
### Ad Copy Principles
- Lead with benefit, not feature
- Include clear CTA (what should they do next?)
- Match ad message to landing page (message match)
- Use numbers and specifics over vague claims
- Test emotional vs rational appeals
### Video Production Standards
- H.264 codec, AAC audio, MP4 container
- Minimum 720p (1080p preferred)
- Subtitles/captions always (accessibility + sound-off viewing)
- Brand mention within first 5s (awareness) or at CTA (performance)
## Output
### Creative Quality Report
```
Cross-Platform Creative Health
Google: ████████░░ X/X checks passing
Meta: ██████████ X/X checks passing
LinkedIn: ███████░░░ X/X checks passing
TikTok: █████░░░░░ X/X checks passing
Microsoft: ████████░░ X/X checks passing
```
### Deliverables
- `CREATIVE-AUDIT-REPORT.md`: Per-platform creative assessment
- Fatigue alerts (any creative past refresh cadence)
- Format diversity gaps per platform
- Production priority list (most impactful creative to produce next)
- Quick Wins (format conversions, CTA changes, Spark Ads setup)
src/adclaw/agents/skills/ads-dna/SKILL.md
+225
View File
@@ -0,0 +1,225 @@
---
name: ads-dna
description: "Brand DNA extractor for paid advertising. Scans a website URL to extract visual identity, tone of voice, color palette, typography, and imagery style. Outputs brand-profile.json to the current directory. Run before /ads create or /ads generate for brand-consistent creative. Triggers on: brand DNA, brand profile, extract brand, brand identity, brand colors, what is the brand voice, analyze brand, brand style guide."
---
# Ads DNA: Brand DNA Extractor
Extracts brand identity from a website and saves it as `brand-profile.json`
for use by `/ads create`, `/ads generate`, and `/ads photoshoot`.
## Quick Reference
| Command | What it does |
|---------|-------------|
| `/ads dna <url>` | Full brand extraction → `brand-profile.json` |
| `/ads dna https://acme.com --quick` | Fast extraction (homepage only) |
## Process
### Step 1: Collect URL
If the user hasn't provided a URL, ask:
> "What website URL should I analyze for brand DNA? (e.g. https://yoursite.com)"
### Step 2: Fetch Pages
Use the **browser tool** (agent_browser or curl) to retrieve each page. For each URL, extract:
> "Return all visible text content, the full contents of any `<style>` blocks, inline
> `style=` attributes, `<meta>` tags, Google Fonts `@import` URLs, and any `og:image`
> values found on this page."
Fetch in this order:
1. **Homepage** (`<url>`)
2. **About page**: try `<url>/about`, then `<url>/about-us`, then `<url>/our-story`
3. **Product/Services page**: try `<url>/product`, then `<url>/products`, then `<url>/services`
**If `--quick` flag was provided**: fetch the homepage only; skip steps 2 and 3.
If a secondary page returns a 404 or redirect error, continue with fewer pages and note:
"Secondary pages unavailable; extraction based on homepage only. Confidence may be lower."
### Step 2b: Capture Brand Screenshots
After fetching pages, capture 3 screenshots for comprehensive brand anchoring.
These serve as visual style references during `/ads generate`; the same approach
Pomelli uses to anchor ad images to the actual brand aesthetic.
Capture the following:
1. **Homepage hero section** (above the fold) — use browser MCP tool to navigate and screenshot
2. **Product or services page** — navigate to /products and screenshot
3. **About page** (brand personality) — navigate to /about and screenshot
Save screenshots to `./brand-screenshots/{domain}_{page}.png`.
Use the `agent_browser` MCP or Playwright MCP for screenshots.
If no browser MCP is available, skip screenshot capture and rely on text extraction.
If a page is not found or returns an error, skip it gracefully and continue
with the remaining pages.
**If `--quick` flag was provided**: skip screenshot capture entirely.
**If capture fails** (Playwright not installed, network error, JS-heavy SPA that times out):
- Log: `"Screenshot capture skipped; run: python3 -m playwright install chromium"`
- Continue without screenshots
- Do NOT set the `screenshots` field in brand-profile.json
### Step 3: Extract Brand Elements
From the fetched HTML, extract:
**Colors:**
- `og:image` meta tag → analyze dominant colors (note 2-3 prominent hex values)
- CSS `background-color` on `body`, `header`, `.hero`, `.btn-primary`
- CSS `color` on `h1`, `h2`, `.btn`
- CSS `border-color` or `background` on `.cta`, `.button`
- Identify: primary (most prominent brand color), secondary (supporting colors), background, text
**Typography:**
- `@import url(https://fonts.googleapis.com/...)` → extract font names from URL path
- CSS `font-family` on `h1`, `h2`, `body`, `.headline`
- If Google Fonts URL contains `family=Inter:wght@...`, heading_font = "Inter"
**Voice:**
Analyze hero headline, subheadline, About page intro, and CTA button text.
Score each axis 1-10 using these heuristics:
| Signal | Score direction |
|--------|----------------|
| Uses "you/your" frequently | formal_casual → casual (+2) |
| Uses technical jargon | expert_accessible → expert (-2) |
| Short punchy sentences (≤8 words) | bold_subtle → bold (+2) |
| Data/stats in hero | rational_emotional → rational (-2) |
| "Transform", "revolutionize", "disrupt" | traditional_innovative → innovative (+2) |
| Customer testimonials lead | rational_emotional → emotional (+2) |
| Industry awards, "trusted by X" | traditional_innovative → traditional (-1) |
**Imagery style** (from og:image and any visible hero image descriptions):
- Photography vs. illustration vs. flat design
- Subject matter (people, product, abstract, data)
- Composition style (clean/minimal vs. busy/editorial)
**Forbidden elements** (infer from brand positioning):
- Enterprise/B2B brands → add "cheesy stock photos", "consumer lifestyle imagery"
- Healthcare → add "unqualified medical claims", "before/after imagery"
- Finance → add "get rich quick imagery", "unrealistic wealth displays"
- Consumer brands → usually no forbidden elements
### Step 4: Build brand-profile.json
Read `ads-shared/references/brand-dna-template.md` for the exact schema.
Construct the JSON object following the schema precisely. Use `null` for any
field that cannot be confidently extracted; do not guess.
Example of a low-confidence field:
```json
"typography": {
"heading_font": null,
"body_font": "system-ui",
"pairing_descriptor": "system default (Google Fonts not detected)"
}
```
### Step 5: Write brand-profile.json
Write the JSON to `./brand-profile.json` in the current working directory
(where the user is running Claude Code).
If screenshots were captured successfully in Step 2b, include a `screenshots` field:
```json
"screenshots": {
"homepage": "./brand-screenshots/{domain}_homepage.png",
"product": "./brand-screenshots/{domain}_product.png",
"about": "./brand-screenshots/{domain}_about.png"
}
```
Include only the screenshots that were successfully captured. If a page was not
found or errored, omit that key. Omit the `screenshots` field entirely if Step 2b
was skipped or all captures failed.
### Step 6: Confirm and Summarize
Show the user:
```
✓ brand-profile.json saved to ./brand-profile.json
Brand DNA Summary:
Brand: [brand_name]
Voice: [descriptor 1], [descriptor 2], [descriptor 3]
Primary Color: [hex]
Typography: [heading_font] / [body_font]
Target: [age_range] [profession]
Screenshots: [N captured (homepage, product, about) in ./brand-screenshots/] OR [skipped]
Run `/ads create` to generate campaign concepts from this profile.
```
## Visual Designer Integration
The visual-designer agent uses the most relevant screenshot per concept as a style
reference when generating images via banana. For example, a product-focused concept
references the product page screenshot, while a brand awareness concept references
the homepage or about page screenshot.
## Limitations
- **Sparse content**: Sites with <200 words of body text produce lower-confidence profiles.
Note: "Low confidence extraction; limited content available for analysis."
- **Dynamic sites**: JavaScript-rendered content may not be captured. Playwright is not
used by default. If the site appears to be SPA/React with no static HTML, note this.
- **Multi-brand enterprises**: This tool creates one profile per URL. Run separately
for each brand/product line.
- **Dark mode sites**: If body background is #333 or darker, swap background/text values.
- **CSS-in-JS**: Modern React sites may not have extractable CSS. Use og:image colors as fallback.
## brand-profile.json Schema
```json
{
"schema_version": "1.0",
"brand_name": "string",
"website_url": "string",
"extracted_at": "ISO-8601",
"voice": {
"formal_casual": 1-10,
"rational_emotional": 1-10,
"playful_serious": 1-10,
"bold_subtle": 1-10,
"traditional_innovative": 1-10,
"expert_accessible": 1-10,
"descriptors": ["adjective1", "adjective2", "adjective3"]
},
"colors": {
"primary": "#hexcode or null",
"secondary": ["#hex1", "#hex2"],
"forbidden": ["#hex or color name"],
"background": "#hexcode",
"text": "#hexcode"
},
"typography": {
"heading_font": "Font Name or null",
"body_font": "Font Name or system-ui",
"pairing_descriptor": "brief description"
},
"imagery": {
"style": "professional photography | illustration | flat design | mixed",
"subjects": ["subject1", "subject2"],
"composition": "brief description",
"forbidden": ["element1", "element2"]
},
"aesthetic": {
"mood_keywords": ["keyword1", "keyword2", "keyword3"],
"texture": "minimal | textured | mixed",
"negative_space": "generous | moderate | dense"
},
"brand_values": ["value1", "value2", "value3"],
"target_audience": {
"age_range": "e.g. 25-45",
"profession": "brief description",
"pain_points": ["pain1", "pain2"],
"aspirations": ["aspiration1", "aspiration2"]
}
}
```
src/adclaw/agents/skills/ads-generate/SKILL.md
+163
View File
@@ -0,0 +1,163 @@
---
name: ads-generate
description: "AI image generation for paid ad creatives. Reads campaign-brief.md and brand-profile.json to produce platform-sized ad images using banana-claude. Requires banana-claude (v1.4.1+) with nanobanana-mcp configured. Triggers on: generate ads, create images, make ad creatives, generate visuals, create ad images, generate campaign images, make the images, generate from brief."
---
# Ads Generate: AI Ad Image Generator
Generates platform-sized ad creative images from your campaign brief and brand
profile. Uses banana-claude as the image generation provider.
## Quick Reference
| Command | What it does |
|---------|-------------|
| `/ads generate` | Generate all images from campaign-brief.md |
| `/ads generate --platform meta` | Generate Meta assets only |
| `/ads generate --prompt "text" --ratio 9:16` | Standalone generation without brief |
## Environment Setup
**Required before running:**
- Requires banana-claude (v1.4.1+) with nanobanana-mcp configured
- Run `/banana setup` to configure API key and MCP
- Fallback: if banana is not available, use `scripts/generate_image.py` (deprecated)
If banana-claude is not installed, this skill will display setup instructions
and stop. It will never fail silently.
## Process
### Step 1: Verify banana-claude
Verify banana-claude is installed (run `/banana setup` to check). If not installed,
display setup instructions and exit.
### Step 2: Locate Source Files
Check for:
- `campaign-brief.md` → primary source for prompts and dimensions
- `brand-profile.json` → brand color/style injection (optional but recommended)
**If campaign-brief.md is found**: Use `## Image Generation Briefs` section as the
generation job list.
**If no campaign-brief.md**: Enter standalone mode (Step 2b).
#### Step 2b: Standalone Mode
Ask the user:
1. Generation prompt (what should the image show?)
2. Target platform (to set correct dimensions)
3. Output filename (optional)
Then skip to Step 5.
### Step 3: Read Provider Config
Load `ads-shared/references/image-providers.md` to confirm:
- Active provider pricing (show user the cost estimate)
- Rate limits for current tier
- Batch API availability
### Step 4: Read Platform Specs
For each platform in the campaign brief, load the relevant spec reference:
- `ads-shared/references/meta-creative-specs.md`
- `ads-shared/references/google-creative-specs.md`
- `ads-shared/references/tiktok-creative-specs.md`
- `ads-shared/references/linkedin-creative-specs.md`
- `ads-shared/references/youtube-creative-specs.md`
- `ads-shared/references/microsoft-creative-specs.md`
### Step 5: Prepare banana Configuration
Create banana brand preset from brand-profile.json if one does not already exist
at `~/.banana/presets/{brand-slug}.json`.
Select banana domain mode based on campaign brief content:
- **Product**: e-commerce, packshots
- **Editorial**: brand awareness, lifestyle
- **Cinema**: video thumbnails, dramatic
- **UI/Web**: app install, SaaS
- **Portrait**: testimonials, people
### Step 6: Spawn Visual Designer Agent
Spawn the `visual-designer` agent using the Task tool with `context: fork`,
passing the selected domain mode and preset name.
The agent will:
- Parse the image generation briefs from campaign-brief.md
- Inject brand colors and mood from brand-profile.json
- Use banana-claude with the configured domain mode for each asset
- Save to `./ad-assets/[platform]/[concept]/` directory structure
- Write `generation-manifest.json`
### Step 7: Validate with Format Adapter
After the visual-designer completes, spawn the `format-adapter` agent
with `context: fork` to validate dimensions and report missing formats.
### Step 8: Quality Gate
Use Claude vision to assess each generated image against the brief (score 1 to 10
on brand alignment, composition, platform fit). If any image scores below 6,
regenerate once with an adjusted prompt.
### Step 9: Aggregate Costs
Read banana cost data from `~/.banana/costs.json` and include total creative spend
in generation-manifest.json.
### Step 10: Report Results
Present a summary:
```
Generation complete:
Generated assets:
✓ ./ad-assets/meta/concept-1/feed-1080x1350.png
✓ ./ad-assets/tiktok/concept-1/vertical-1080x1920.png
✗ ./ad-assets/google/concept-1/landscape-1200x628.png [error reason]
Format validation: See format-report.md
Cost: $[N] total creative spend (from ~/.banana/costs.json)
Next steps:
1. Review assets in ./ad-assets/
2. Check format-report.md for any missing formats
3. Upload to your ad platform managers
```
## Cost Transparency
Before generating, estimate and show the cost:
- Count the number of image briefs in campaign-brief.md
- Show estimated cost based on banana pricing tiers
- If >$1.00, ask for confirmation before proceeding
## Standalone Mode (No campaign-brief.md)
When running without a campaign brief:
```
Platform target → dimensions used:
meta-feed → 1080×1350 (4:5)
meta-reels → 1080×1920 (9:16)
tiktok → 1080×1920 (9:16)
google-pmax → 1200×628 (1.91:1)
linkedin → 1080×1080 (1:1)
youtube → 1280×720 (16:9)
youtube-short → 1080×1920 (9:16)
```
Use `/banana generate` directly with the specified prompt and aspect ratio.
## Reference Files
- `ads-shared/references/image-providers.md`: provider config, pricing, limits
- `ads-shared/references/[platform]-creative-specs.md`: per-platform specs
- `ads-shared/references/brand-dna-template.md`: brand injection schema
src/adclaw/agents/skills/ads-google/SKILL.md
+157
View File
@@ -0,0 +1,157 @@
---
name: ads-google
description: "Google Ads deep analysis covering Search, Performance Max, Display, YouTube, and Demand Gen campaigns. Evaluates 74 checks across conversion tracking, wasted spend, account structure, keywords, ads, and settings. Use when user says Google Ads, Google PPC, search ads, PMax, Performance Max, or Google campaign."
---
# Google Ads Deep Analysis
## Process
1. Collect Google Ads account data (export, Change History, Search Terms Report)
2. **Validate**: confirm data covers ≥30 days and includes Search Terms Report before proceeding
3. Read `ads-shared/references/google-audit.md` for full 74-check audit
4. Read `ads-shared/references/benchmarks.md` for Google-specific benchmarks
5. Read `ads-shared/references/scoring-system.md` for weighted scoring
6. Evaluate all applicable checks as PASS, WARNING, or FAIL
7. **Validate**: confirm all 74 checks evaluated before calculating score
8. Calculate Google Ads Health Score (0-100)
9. Generate findings report with action plan
## What to Analyze
### Conversion Tracking (25% weight)
- Google tag (gtag.js) installed and firing on all pages
- Enhanced Conversions active (hashed first-party data)
- Consent Mode v2 implemented (required for EU/EEA)
- Conversion actions mapped correctly (primary vs secondary)
- Offline conversion import configured (for lead gen)
- Server-side tagging via GTM (recommended for accuracy)
- Attribution model: data-driven preferred (last-click as fallback only)
- Conversion lag analysis (are conversions still trickling in?)
### Wasted Spend (20% weight)
- Search Terms Report reviewed (last 30 days minimum)
- Negative keyword coverage adequate (shared lists + campaign-level)
- Display placement audit (exclude low-quality sites)
- Invalid click rate within norms (<10%)
- Broad Match only used with Smart Bidding (NEVER without it)
- Brand/non-brand campaigns separated
- Geographic targeting precise (no wasted international spend)
**Negative Keyword Rules (critical: bad negatives kill campaigns):**
- NEVER suggest Broad Match negatives unless explicitly justified; they block too broadly
- Default to **Exact Match** `[keyword]` for specific irrelevant queries
- Use **Phrase Match** `"keyword"` for irrelevant intent patterns
- Source negatives from actual Search Terms Report irrelevant queries, NOT guesses
- Group into themed lists: Informational (how-to, DIY, what is), Job-seeker (jobs, careers, salary), Competitor (only if intentionally excluded), Free-intent (free, crack, torrent)
- Recommend **Shared Negative Lists** at the account level, not just campaign-level
- Review existing negatives for over-blocking (are any negatives accidentally blocking converting queries?)
### Account Structure (15% weight)
- Campaign-level organization follows business logic
- Ad groups themed tightly (15-20 keywords max per group)
- RSA ad groups have ≥3 active ads
- PMax campaigns structured correctly (asset groups, signals)
- SKAGs evaluated (migrate to themed groups if present)
- Campaign labels/naming conventions consistent
### Keywords (15% weight)
- Match type strategy appropriate (Exact → Phrase → Broad progression)
- Quality Score distribution (aim ≥7 average)
- Low QS keywords flagged (<5 = FAIL, 5-6 = WARNING)
- Keyword cannibalization check (same keywords in multiple campaigns)
- Impression share tracked for top keywords
- Keyword bid adjustments set for devices/locations/audiences
### Ads (15% weight)
- RSA: ≥8 unique headlines, ≥3 descriptions per ad group
- RSA: ad strength "Good" or "Excellent" (not "Poor" or "Average")
- Pin usage minimal and strategic (over-pinning reduces RSA flexibility)
- Ad extensions: sitelinks (≥4), callouts (≥4), structured snippets, image
- Dynamic keyword insertion used appropriately
- Ad copy includes CTA, value proposition, differentiators
### Settings (10% weight)
- Bid strategy appropriate for campaign maturity and goals
- Budget pacing: no campaigns limited by budget (unless intentional)
- Ad schedule aligned with business hours/conversion patterns
- Device bid adjustments set based on performance data
- Location targeting: "Presence" not "Presence or Interest"
- Network settings: Search Partners reviewed, Display opt-out for Search
## GAQL & Data Accuracy
Before analyzing data, read `ads-shared/references/gaql-notes.md` for known GAQL field incompatibilities,
deduplication patterns, and filter scope best practices. Key rules:
- Deduplicate keywords by `(ad_group_id + keyword_text + match_type)` before any analysis
- Only analyze ENABLED campaigns and ad groups (exclude paused/removed)
- Filter to keywords with impressions > 0 for theme coherence checks (G03)
- Apply legacy BMM heuristic: BROAD + Manual CPC = legacy BMM, not intentional broad (G17)
- Only flag wasted spend on terms with >$10 spend AND 0 conversions (G16)
- Count shared negative keyword lists alongside campaign-level negatives (G14/G15)
## Google Ads MCP Integration (Optional)
For automated data collection, connect the [Google Ads MCP server](https://github.com/googleads/google-ads-mcp):
- **Tools available**: `search` (GAQL queries), `list_accessible_customers`
- **Setup**: Configure in `.mcp.json` or Claude Code MCP settings
- **Customer ID**: Extract from CLAUDE.md under Accounts > Google Ads, or ask the user
- **Fallback**: If MCP is not configured, fall back to manual data export (the default workflow)
When MCP is available, use it to pull Search Terms Reports, keyword data, conversion actions,
and campaign structure automatically instead of requiring manual exports.
## PMax Deep Dive
If Performance Max campaigns exist, additionally evaluate:
- Asset group diversity (text, images, video, feeds)
- Audience signals configured (custom segments, lists, demographics)
- URL expansion settings reviewed (opt-out of irrelevant pages)
- Brand exclusions applied (prevent cannibalizing brand search)
- Search themes utilized (2024 feature)
- Final URL expansion: enabled or disabled with justification
- Insights tab reviewed (search categories, audience segments)
## AI Max for Search (2026)
If AI Max for Search is available/active:
- Broad Match + AI Max integration evaluated
- Auto-generated headline performance monitored
- Search term categories reviewed for relevance
- Budget impact assessed (AI Max can shift spend)
## Key Thresholds
| Metric | Pass | Warning | Fail |
|--------|------|---------|------|
| Quality Score (avg) | ≥7 | 5-6 | <5 |
| CTR (Search) | ≥6.66% | 3-6.66% | <3% |
| CVR (Search) | ≥7.52% | 3-7.52% | <3% |
| CPC (Search) | ≤$5.26 | $5.26-8.00 | >$8.00 |
| Wasted Spend | <10% | 10-20% | >20% |
| Ad Strength | Good+ | Average | Poor |
| Invalid Clicks | <5% | 5-10% | >10% |
## Output
### Google Ads Health Score
```
Google Ads Health Score: XX/100 (Grade: X)
Conversion Tracking: XX/100 ████████░░ (25%)
Wasted Spend: XX/100 ██████████ (20%)
Account Structure: XX/100 ███████░░░ (15%)
Keywords: XX/100 █████░░░░░ (15%)
Ads: XX/100 ████████░░ (15%)
Settings: XX/100 ██████████ (10%)
```
### Deliverables
- `GOOGLE-ADS-REPORT.md`: Full 74-check findings with pass/warning/fail
- Wasted spend estimate (monthly $ value)
- Quick Wins sorted by impact
- PMax-specific recommendations (if applicable)
- Keyword health matrix with QS, CTR, CVR per keyword group
src/adclaw/agents/skills/ads-landing/SKILL.md
+154
View File
@@ -0,0 +1,154 @@
---
name: ads-landing
description: "Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says landing page, post-click experience, landing page audit, conversion rate, or landing page optimization."
---
# Landing Page Quality for Ad Campaigns
## Process
1. Collect landing page URLs from active ad campaigns
2. Read `ads-shared/references/benchmarks.md` for conversion rate benchmarks
3. Read `ads-shared/references/conversion-tracking.md` for pixel/tag verification
4. Assess each landing page for ad-specific quality factors
5. Score landing pages and identify improvement opportunities
6. Generate recommendations prioritized by conversion impact
## Message Match Assessment
The #1 landing page issue in ad campaigns: does the page match the ad?
### What to Check
- **Headline match**: landing page H1 reflects ad copy headline/keyword
- **Offer match**: promoted offer (price, discount, trial) is visible above fold
- **CTA match**: landing page CTA matches ad's promised action
- **Visual match**: consistent imagery between ad creative and page
- **Keyword match**: search keyword appears naturally in page content
### Message Match Scoring
| Level | Description | Score |
|-------|-------------|-------|
| Exact match | Headline, offer, CTA all align perfectly | 100% |
| Partial match | Headline matches but offer/CTA differs | 60% |
| Weak match | Generic page, loosely related to ad | 30% |
| Mismatch | Page content doesn't reflect ad promise | 0% |
## Page Speed Assessment
Slow pages kill conversion rates. For every 1s delay, CVR drops ~7%.
### Thresholds (Ad Landing Pages)
| Metric | Pass | Warning | Fail |
|--------|------|---------|------|
| LCP | <2.5s | 2.5-4.0s | >4.0s |
| FID/INP | <100ms | 100-200ms | >200ms |
| CLS | <0.1 | 0.1-0.25 | >0.25 |
| Time to Interactive | <3.0s | 3.0-5.0s | >5.0s |
| Page weight | <2MB | 2-5MB | >5MB |
### Common Speed Issues in Ad Pages
- Hero images not compressed (use WebP/AVIF)
- Too many third-party scripts (chat widgets, analytics, heatmaps)
- Render-blocking CSS/JS above fold
- No lazy loading for below-fold content
- Font files not preloaded
## Mobile Experience
75%+ of ad clicks come from mobile. Mobile experience is critical.
### Mobile Checklist
- Tap targets: ≥48x48px with ≥8px spacing
- Font size: ≥16px body text (no pinch-to-zoom needed)
- Form fields: properly sized, keyboard type matches input (email, phone, number)
- CTA button: full-width on mobile, visible without scrolling
- No horizontal scroll
- Images responsive and properly sized
- Phone number clickable (tel: link)
- No interstitials or popups blocking content on load
## Trust Signals
### Above-the-Fold Trust Elements
- Company logo visible
- Social proof (customer count, reviews, ratings)
- Security badges (SSL, payment security, guarantees)
- Recognizable client logos (B2B)
- Star ratings or testimonial snippet
### Below-the-Fold Trust Elements
- Full testimonials with names, photos, companies
- Case study highlights with specific metrics
- Certifications, awards, accreditations
- Privacy policy link
- Physical address/phone number (local service businesses)
## Form Optimization
### Form Length Impact on CVR
| Fields | Expected CVR Impact | Use Case |
|--------|-------------------|----------|
| 1-3 fields | Highest CVR | Top-of-funnel, free offer |
| 4-5 fields | Moderate CVR | Mid-funnel, qualified leads |
| 6-8 fields | Lower CVR | Bottom-funnel, sales-ready |
| 9+ fields | Lowest CVR | Only for high-value offers |
### Form Best Practices
- Pre-fill fields where possible (UTM data, known info)
- Use multi-step forms for 5+ fields (progressive disclosure)
- Show progress indicator on multi-step forms
- Inline validation (don't wait until submit to show errors)
- Error messages are clear and helpful
- Submit button text is specific ("Get My Free Quote" not "Submit")
- Thank you page has clear next steps
## Ad-Specific Landing Page Elements
### UTM Parameter Handling
- UTM parameters captured and stored (for attribution)
- Click IDs preserved: gclid (Google), fbclid (Meta), ttclid (TikTok), msclkid (Microsoft)
- Parameters passed to form submissions or CRM
### Dynamic Content
- Dynamic keyword insertion in headline (Google Ads feature)
- Location-specific content for geo-targeted campaigns
- Audience-specific messaging (different pages for different segments)
- A/B testing active on key elements (headline, CTA, hero image)
### Conversion Tracking
- Thank you page/event fires correctly for all platforms
- Form submission triggers conversion event
- Phone call tracking configured (if applicable)
- Chat/live agent triggers tracked as micro-conversions
## Landing Page Quality by Platform
| Platform | Key Requirement | Notes |
|----------|----------------|-------|
| Google | QS component: landing page experience | Directly affects ad rank and CPC |
| Meta | Page load speed critical | Slow pages = Meta penalizes delivery |
| LinkedIn | Professional, B2B appropriate | Match LinkedIn's professional context |
| TikTok | Mobile-first mandatory | 95%+ TikTok traffic is mobile |
| Microsoft | Desktop-optimized matters more | Higher desktop % than other platforms |
## Output
### Landing Page Assessment
```
Landing Page Health
Message Match: ████████░░ XX/100
Page Speed: ██████████ XX/100
Mobile: ███████░░░ XX/100
Trust Signals: █████░░░░░ XX/100
Form Quality: ████████░░ XX/100
```
### Deliverables
- `LANDING-PAGE-REPORT.md`: Per-page assessment with scores
- Message match analysis per ad-to-page combination
- Page speed improvement priorities
- Mobile experience fixes
- Form optimization recommendations
- Quick Wins sorted by conversion impact
src/adclaw/agents/skills/ads-linkedin/SKILL.md
+118
View File
@@ -0,0 +1,118 @@
---
name: ads-linkedin
description: "LinkedIn Ads deep analysis for B2B advertising. Evaluates 25 checks across technical setup, audience targeting, creative quality, lead gen forms, and bidding strategy. Includes Thought Leader Ads, ABM, and predictive audiences. Use when user says LinkedIn Ads, B2B ads, sponsored content, lead gen forms, InMail, or LinkedIn campaign."
---
# LinkedIn Ads Deep Analysis
## Process
1. Collect LinkedIn Ads data (Campaign Manager export, Insight Tag status)
2. Read `ads-shared/references/linkedin-audit.md` for full 25-check audit
3. Read `ads-shared/references/benchmarks.md` for LinkedIn-specific benchmarks
4. Read `ads-shared/references/scoring-system.md` for weighted scoring
5. Evaluate all applicable checks as PASS, WARNING, or FAIL
6. Calculate LinkedIn Ads Health Score (0-100)
7. Generate findings report with action plan
## What to Analyze
### Technical Setup (25% weight)
- Insight Tag installed and firing on all pages (L01)
- Conversions API (CAPI) active, launched 2025 (L02)
- Conversion events configured for full funnel
- Revenue attribution tracking enabled
### Audience Targeting (25% weight)
- Job title targeting uses specific titles, not just functions (L03)
- Company size filtering matches ICP (L04)
- Seniority level appropriate for offer (L05)
- Matched Audiences active: retargeting + contact lists (L06)
- ABM company lists uploaded (up to 300,000 companies) (L07)
- Audience expansion OFF for precision campaigns, ON for scale (L08)
- Predictive audiences tested, replaced Lookalikes Feb 2024 (L09)
### Creative Quality (20% weight)
- Thought Leader Ads active, ≥30% budget allocation for B2B (L10)
- Ad format diversity: ≥2 formats tested (L11)
- Video ads tested (L12)
- Creative refresh every 4-6 weeks (L13)
### Lead Gen & Performance (15% weight)
- Lead Gen Form ≤5 fields (13% CVR benchmark) (L14)
- Lead Gen Form synced to CRM in real-time (L15)
- Campaign objective matches funnel stage (L18)
- A/B testing active: creative or audience (L19)
- Message ad frequency ≤1 per 30-45 days (L20)
### Bidding & Budget (15% weight)
- Bid strategy: CPS for Messages, Max Delivery for Content (L16)
- Daily budget ≥$50 for Sponsored Content (L17)
- CTR ≥0.44% for Sponsored Content (L21)
- CPC within benchmark: $5-7 average, senior $6.40+ (L22)
- Lead-to-opportunity rate tracked, not just CPL (L23)
- Attribution: 30-day click / 7-day view configured (L24)
- Demographics report reviewed monthly (L25)
## Thought Leader Ads (TLA) Assessment
Thought Leader Ads use employee/executive personal posts as sponsored content:
- CPC typically $2.29-$4.14 vs $13.23 for standard Sponsored Content
- CTR typically 2-3x higher than corporate-branded ads
- Best for: B2B thought leadership, brand awareness, engagement
Evaluate:
- Are TLAs being used? (If not, HIGH priority recommendation)
- Are they getting ≥30% of total LinkedIn budget?
- Are the right employees selected (industry credibility, active posters)?
- Is post content authentic and valuable (not salesy)?
## ABM Strategy Assessment
For B2B Enterprise accounts:
- Company list uploaded and segmented by tier (Tier 1, 2, 3)
- Custom content per tier (personalized messaging)
- Account penetration tracking (contacts reached per target account)
- Integration with CRM/ABM platform (Demandbase, 6sense, etc.)
## LinkedIn Context
| Setting | Value |
|---------|-------|
| Minimum audience size | 500 (for ads to run) |
| Lead Gen Form CVR benchmark | 13% |
| TLA CPC range | $2.29-$4.14 |
| Standard SC CPC | $13.23 average |
| Hierarchy rename | Oct 2025 (Campaign Group → Campaign → Ad) |
| Predictive Audiences | Replaced Lookalikes Feb 2024 |
## Key Thresholds
| Metric | Pass | Warning | Fail |
|--------|------|---------|------|
| CTR (Sponsored Content) | ≥0.44% | 0.30-0.44% | <0.30% |
| CPC (average) | ≤$7.00 | $7-10 | >$10.00 |
| Lead Gen CVR | ≥10% | 5-10% | <5% |
| Message frequency | ≤1/30 days | 1/15-30 days | >1/15 days |
| TLA budget share | ≥30% | 15-30% | <15% |
## Output
### LinkedIn Ads Health Score
```
LinkedIn Ads Health Score: XX/100 (Grade: X)
Technical Setup: XX/100 ████████░░ (25%)
Audience: XX/100 ██████████ (25%)
Creative: XX/100 ███████░░░ (20%)
Lead Gen: XX/100 █████░░░░░ (15%)
Budget & Bidding: XX/100 ████████░░ (15%)
```
### Deliverables
- `LINKEDIN-ADS-REPORT.md`: Full 25-check findings with pass/warning/fail
- TLA adoption roadmap (if not using)
- ABM strategy recommendations (for B2B)
- Lead Gen Form optimization priorities
- Quick Wins sorted by impact
src/adclaw/agents/skills/ads-meta/SKILL.md
+125
View File
@@ -0,0 +1,125 @@
---
name: ads-meta
description: "Meta Ads deep analysis covering Facebook and Instagram advertising. Evaluates 46 checks across Pixel/CAPI health, creative diversity and fatigue, account structure, and audience targeting. Includes Advantage+ assessment. Use when user says Meta Ads, Facebook Ads, Instagram Ads, Advantage+, or Meta campaign."
---
# Meta Ads Deep Analysis
## Process
1. Collect Meta Ads data (Ads Manager export, Events Manager screenshot, EMQ scores)
2. Read `ads-shared/references/meta-audit.md` for full 46-check audit
3. Read `ads-shared/references/benchmarks.md` for Meta-specific benchmarks
4. Read `ads-shared/references/scoring-system.md` for weighted scoring
5. Evaluate all applicable checks as PASS, WARNING, or FAIL
6. Calculate Meta Ads Health Score (0-100)
7. Generate findings report with action plan
## What to Analyze
### Pixel / CAPI Health (30% weight)
- Meta Pixel installed and firing on all pages
- Conversions API (CAPI) active (30-40% data loss without it post-iOS 14.5)
- Event deduplication configured (event_id matching, ≥90% dedup rate)
- Event Match Quality (EMQ) ≥8.0 for Purchase event
- All standard events configured (ViewContent, AddToCart, Purchase, Lead)
- Custom conversions created for non-standard events
- Aggregated Event Measurement (AEM) configured for iOS
- Domain verification completed
- Server-side events include customer_information parameters
- Pixel fires with correct currency and value parameters
### Creative (30% weight)
- ≥3 creative formats active (image, video, carousel, collection)
- ≥5 creatives per ad set (Meta recommendation)
- Creative fatigue detection: CTR drop >20% over 14 days = FAIL
- Video creative: 15s max for Stories/Reels, 30s max for Feed
- UGC/testimonial creative tested
- Dynamic Creative Optimization (DCO) tested
- Ad copy: headline under 40 chars, primary text under 125 chars
- Creative refresh cadence: every 2-4 weeks for high-spend
### Account Structure (20% weight)
- Campaign Budget Optimization (CBO) vs Ad Set Budget (ABO) intentional
- Campaign consolidation: ≤5 active campaigns per objective type
- Learning phase health: <30% ad sets in "Learning Limited" (FAIL >50%)
- Budget per ad set: ≥5x target CPA (minimum for learning phase exit)
- Ad set audience overlap <30% (Audience Overlap tool)
- Campaign naming conventions consistent and descriptive
- Advantage+ Shopping Campaigns (ASC) active for e-commerce
- Simplified campaign structure (fewer, larger ad sets preferred)
### Audience & Targeting (20% weight)
- Prospecting frequency (7-day): <3.0 (WARNING 3-5, FAIL >5)
- Retargeting frequency (7-day): <8.0 (WARNING 8-12, FAIL >12)
- Custom Audiences: website visitors, customer lists, engagement
- Lookalike Audiences: multiple seed sizes tested (1%, 3%, 5%)
- Advantage+ Audience tested vs manual targeting
- Interest targeting: broad enough for algorithm optimization
- Exclusions: purchasers excluded from prospecting, overlap managed
- Location targeting reviewed for relevance
## Advantage+ Assessment
If Advantage+ features are in use:
- **ASC (Shopping Campaigns)**: catalog connected, existing customer cap set
- **Advantage+ Audience**: performance vs manual audience compared
- **Advantage+ Creative**: enhancements enabled (text, brightness, music)
- **Advantage+ Placements**: enabled (let Meta optimize placement mix)
- **Budget allocation**: Advantage+ campaigns getting fair test budget
## Special Ad Categories
If ads are in restricted categories:
- Special Ad Category declared before campaign creation
- Targeting restrictions verified (no ZIP, age 18-65+ only, no Lookalike)
- Creative compliance with category-specific policies
- Read `ads-shared/references/compliance.md` for full requirements
## EMQ Optimization Guide
| EMQ Score | Status | Action |
|-----------|--------|--------|
| 8.0-10.0 | Excellent | Maintain current setup |
| 6.0-7.9 | Good | Add more customer_information parameters |
| 4.0-5.9 | Fair | Implement CAPI, improve data quality |
| <4.0 | Poor | Critical: CAPI + Enhanced Matching required |
Key parameters to maximize EMQ:
- `em` (email): highest match rate signal
- `ph` (phone): second highest match signal
- `fn`, `ln` (first/last name): improves match accuracy
- `ct`, `st`, `zp` (city, state, zip): geographic matching
- `external_id`: CRM/user ID for cross-device matching
## Key Thresholds
| Metric | Pass | Warning | Fail |
|--------|------|---------|------|
| EMQ (Purchase) | ≥8.0 | 6.0-7.9 | <6.0 |
| Dedup rate | ≥90% | 70-90% | <70% |
| CTR | ≥1.0% | 0.5-1.0% | <0.5% |
| Creative formats | ≥3 | 2 | 1 |
| Creatives per ad set | ≥5 | 3-4 | <3 |
| Learning Limited | <30% | 30-50% | >50% |
| Budget per ad set | ≥5x CPA | 2-5x CPA | <2x CPA |
## Output
### Meta Ads Health Score
```
Meta Ads Health Score: XX/100 (Grade: X)
Pixel / CAPI Health: XX/100 ████████░░ (30%)
Creative: XX/100 ██████████ (30%)
Account Structure: XX/100 ███████░░░ (20%)
Audience: XX/100 █████░░░░░ (20%)
```
### Deliverables
- `META-ADS-REPORT.md`: Full 46-check findings with pass/warning/fail
- EMQ improvement roadmap
- Creative fatigue alerts (any creative with CTR declining >20%)
- Quick Wins sorted by impact
- Advantage+ adoption recommendations
src/adclaw/agents/skills/ads-microsoft/SKILL.md
+145
View File
@@ -0,0 +1,145 @@
---
name: ads-microsoft
description: "Microsoft/Bing Ads deep analysis covering search, Performance Max, Audience Network, and Copilot integration. Evaluates 20 checks with focus on Google import validation, unique Microsoft features, and cost advantage assessment. Use when user says Microsoft Ads, Bing Ads, Bing PPC, Copilot ads, or Microsoft campaign."
---
# Microsoft Ads Deep Analysis
## Process
1. Collect Microsoft Ads data (account export, UET tag status, import results)
2. Read `ads-shared/references/microsoft-audit.md` for full 20-check audit
3. Read `ads-shared/references/benchmarks.md` for Microsoft-specific benchmarks
4. Read `ads-shared/references/scoring-system.md` for weighted scoring
5. Evaluate all applicable checks as PASS, WARNING, or FAIL
6. Calculate Microsoft Ads Health Score (0-100)
7. Generate findings report with action plan
## What to Analyze
### Technical Setup (25% weight)
- UET tag installed and firing on all pages (MS01)
- Enhanced conversions enabled (MS02)
- Google Ads import validated: URLs, extensions, bids, goals (MS03)
### Syndication & Bidding (20% weight)
- Search partner network reviewed, low-performers excluded (MS04)
- Audience Network enabled only if testing intentionally (MS05)
- Bid targets 20-35% lower than Google (CPC advantage) (MS06)
- Target New Customers enabled for PMax, Beta 2026 (MS07)
### Campaign Structure (20% weight)
- Campaign structure mirrors Google or follows best practices (MS08)
- Budget proportional to Bing volume: typically 20-30% of Google (MS09)
- LinkedIn profile targeting for B2B (unique advantage) (MS10)
### Creative & Extensions (20% weight)
- RSA: ≥8 headlines, ≥3 descriptions (MS11)
- Multimedia Ads tested (unique rich format) (MS12)
- Ad copy optimized for Bing demographics (MS13)
- Action Extension utilized (unique to Microsoft) (MS19)
- Filter Link Extension tested (MS20)
### Settings & Performance (15% weight)
- Copilot chat placement enabled for PMax: 73% CTR lift (MS14)
- Conversion goals configured natively, not relying on imported (MS15)
- CPC 20-40% lower than Google for same keywords (MS16)
- CVR comparable to Google, not >50% lower (MS17)
- Impression share tracked for brand and top terms (MS18)
## Google Import Validation
Most Microsoft Ads accounts start as Google Ads imports. Critical validation:
### What Transfers Correctly
- Campaign structure and ad groups
- Keywords and match types
- RSA headlines and descriptions
- Basic bid strategies
### What Needs Manual Review
- **URLs**: verify all landing page URLs are correct post-import
- **Extensions**: not all Google extensions have Microsoft equivalents
- **Bid amounts**: should be 20-35% lower (don't import Google bids as-is)
- **Conversion goals**: re-create natively for better tracking
- **Audiences**: import may miss segments, verify all are present
- **Negative keywords**: verify shared negative lists transferred
### Import Schedule
- Auto-import: useful but review changes monthly
- Manual import: more control, recommended for large accounts
- Never import without post-import audit
## Copilot Integration
Microsoft's AI assistant creates unique ad opportunities:
### Copilot Chat Ads
- Available in Performance Max campaigns
- 73% CTR lift reported in chat placement
- Copilot Checkout launched Jan 2026 (in-chat purchase)
- Natural language ad delivery (conversational context)
### How to Evaluate
- Is Copilot placement enabled? (If not, HIGH priority for PMax)
- What % of impressions/clicks come from Copilot?
- CTR/CVR comparison: Copilot vs traditional placements
- Ad copy quality: does it read well in conversational context?
## Microsoft-Unique Features
These features are exclusive to Microsoft Ads; evaluate adoption:
| Feature | Description | Priority |
|---------|-------------|----------|
| Multimedia Ads | Image-rich search ads with visual elements | Medium |
| Action Extension | CTA button directly in search ad | Medium |
| Filter Link Extension | Filterable category links in ad | Low |
| LinkedIn Profile Targeting | Target by company, industry, job function | High (B2B) |
| Copilot Chat Placement | Ads within Copilot conversations | High |
## Bing Demographic Context
Microsoft Ads reach a distinct audience:
- Older demographic (35-65+ over-indexed)
- Higher household income (top 25% income brackets)
- Desktop-heavy (Windows default browser = Edge = Bing)
- Enterprise/corporate users (Office 365 integration)
Ad copy optimization for this audience:
- Professional tone, less casual than Google/Meta
- Emphasize quality, reliability, premium positioning
- Desktop-optimized landing pages matter more
- B2B messaging resonates strongly
## Key Thresholds
| Metric | Pass | Warning | Fail |
|--------|------|---------|------|
| CTR (Search) | ≥2.83% | 1.5-2.83% | <1.5% |
| CPC (Search) | ≤$1.55 | $1.55-2.50 | >$2.50 |
| CPC vs Google | 20-40% lower | 10-20% lower | Same or higher |
| CVR vs Google | Within 20% | 20-50% lower | >50% lower |
| Impression share (brand) | ≥80% | 60-80% | <60% |
## Output
### Microsoft Ads Health Score
```
Microsoft Ads Health Score: XX/100 (Grade: X)
Technical Setup: XX/100 ████████░░ (25%)
Syndication: XX/100 ██████████ (20%)
Structure: XX/100 ███████░░░ (20%)
Creative: XX/100 █████░░░░░ (20%)
Settings: XX/100 ████████░░ (15%)
```
### Deliverables
- `MICROSOFT-ADS-REPORT.md`: Full 20-check findings with pass/warning/fail
- Google import validation results
- Copilot integration readiness assessment
- Cost advantage analysis (CPC savings vs Google)
- Microsoft-unique feature adoption checklist
- Quick Wins sorted by impact
src/adclaw/agents/skills/ads-photoshoot/SKILL.md
+213
View File
@@ -0,0 +1,213 @@
---
name: ads-photoshoot
description: "Product photography enhancement for ad creatives using banana-claude image generation. Takes a product image and generates 5 professional photography styles for ad use: Studio, Floating, Ingredient, In Use, and Lifestyle. Requires banana-claude (v1.4.1+) with nanobanana-mcp. Triggers on: product photo, product photography, photoshoot, enhance product image, product shoot, product photos for ads, generate product photos, studio shot, lifestyle photo."
---
# Ads Photoshoot: AI Product Photography
Transforms a product image or description into professional ad-ready photography
in 5 distinct visual styles. Each style generates at two sizes: 1:1 (Meta/LinkedIn)
and 9:16 (TikTok/Reels/Stories).
## Quick Reference
| Command | What it does |
|---------|-------------|
| `/ads photoshoot` | Interactive: ask for product + styles |
| `/ads photoshoot --styles studio floating` | Generate only selected styles |
| `/ads photoshoot --product shoe.jpg` | Start with a product image file |
| `/ads photoshoot --all-platforms` | Generate all 5 sizes per style |
## Environment Setup
Requires banana-claude (v1.4.1+) with nanobanana-mcp configured.
Run `/banana setup` to configure API key and MCP.
## Process
### Step 1: Collect Product Information
Ask (combine into one message):
1. **Product image**: Path to product image file (local) OR product URL OR text description
> "Provide a product image path (e.g. ./product.jpg), a URL, or describe your product"
2. **Product description**: What is it? Key features to highlight? (helps prompt quality)
3. **Styles to generate**: Which of the 5 styles? (default: all 5)
- Studio, Floating, Ingredient, In Use, Lifestyle
4. **Target platforms**: Which platforms will these run on?
- Determines output sizes (default: Meta + TikTok → 1:1 + 9:16)
### Step 2: Load Brand Profile (Optional)
Check for `brand-profile.json` in the current directory.
If found, extract for style injection:
- `colors.primary` → inject into backgrounds and accent elements
- `aesthetic.mood_keywords` → inject as atmosphere descriptors
- `target_audience` → use for Lifestyle and In Use context
- `imagery.forbidden` → exclude from all prompts
If not found, proceed with standard style templates.
### Step 3: Verify banana-claude
Verify banana-claude is installed (run `/banana setup` to check). If not installed,
display setup instructions and exit.
### Step 4: Construct Prompts per Style
For each selected style, build the prompt using the template + product description + brand DNA.
#### Style 1: Studio
Clean, e-commerce style product shot.
**Base template:**
```
"[product description], professional product photography, clean white seamless
background, even studio lighting, soft drop shadow, high detail product focus,
ecommerce style, [brand.colors.primary] subtle accent reflections if applicable,
top-down or 3/4 angle, no distractions, catalog quality"
```
**Composition:** Centered, slight 3/4 angle or flat lay.
**Output sizes:** 1080×1080, 1080×1920
#### Style 2: Floating
Dramatic levitation effect.
**Base template:**
```
"[product description] floating in mid-air, dramatic floating product shot,
[brand.colors.primary or brand.aesthetic.mood_keywords[0]] gradient background,
atmospheric shadow below product, levitation effect, product defying gravity,
clean modern aesthetic, high contrast, striking visual"
```
**Composition:** Product centered vertically, ample space above and below.
**Output sizes:** 1080×1080, 1080×1920
#### Style 3: Ingredient
Flat lay with components.
**Base template:**
```
"[product description] centered flat lay, surrounded by its key ingredients
or materials artfully arranged, top-down overhead view, clean light background,
natural texture surface, product as hero element, ingredients scattered with
intentional negative space, editorial food photography style"
```
**Composition:** Top-down, product in center, ingredients fanning out.
**Output sizes:** 1080×1080 (optimal for this style)
#### Style 4: In Use
Authentic usage context.
**Base template:**
```
"person's hands using [product description] in natural context, lifestyle
photography, focus on product-hand interaction, shallow depth of field,
warm natural window light, authentic not staged, [brand.target_audience.profession]
implied context, [brand.aesthetic.mood_keywords] atmosphere"
```
**Composition:** Hands prominent, product clearly identifiable, background soft-focus.
**Note:** Hands only; no full face (avoids model release complications).
**Output sizes:** 1080×1080, 1080×1920
#### Style 5: Lifestyle
Aspirational full-context shot.
**Base template:**
```
"[product description] in aspirational lifestyle scene, [brand.target_audience.age_range]
demographic implied environment, [brand.target_audience.profession] context,
[brand.aesthetic.mood_keywords] atmosphere, golden hour or clean natural lighting,
editorial photography style, [brand.aesthetic.negative_space] composition,
product clearly visible and prominent"
```
**Composition:** Environmental context, product as hero element within the scene.
**Output sizes:** 1080×1080, 1080×1920
### Step 5: Generate Images
**Domain mode selection per style:**
- Use banana **Product** mode for Studio, Floating, and Ingredient styles
- Use banana **Editorial** mode for In Use and Lifestyle styles
- Set resolution to 2K (default) for all generations
**Aspect ratio setup:** Use banana MCP `set_aspect_ratio` before each generation:
- For 1080x1080: set ratio to 1:1
- For 1080x1920: set ratio to 9:16
For each style x size combination, use `/banana generate` with the constructed
prompt, selected domain mode, and correct aspect ratio. Save output to
`./product-photos/[style]/[product-slug]-[style]-[WxH].png`.
Track results. If a generation fails, retry once with a simplified prompt.
### Step 6: Organize and Report
**Output directory structure:**
```
./product-photos/
studio/
product-studio-1080x1080.png
product-studio-1080x1920.png
floating/
product-floating-1080x1080.png
product-floating-1080x1920.png
ingredient/
product-ingredient-1080x1080.png
in-use/
product-in-use-1080x1080.png
product-in-use-1080x1920.png
lifestyle/
product-lifestyle-1080x1080.png
product-lifestyle-1080x1920.png
```
**Summary:**
```
✓ Product photos generated: [N] images
Studio: ./product-photos/studio/ (2 sizes)
Floating: ./product-photos/floating/ (2 sizes)
Ingredient: ./product-photos/ingredient/ (1 size; square only)
In Use: ./product-photos/in-use/ (2 sizes)
Lifestyle: ./product-photos/lifestyle/ (2 sizes)
Cost: see ~/.banana/costs.json for total spend
Best for:
• Meta Feed → Studio (1:1) or Lifestyle (1:1)
• TikTok/Reels → Floating (9:16) or In Use (9:16)
• LinkedIn → Studio (1:1) or Lifestyle (1:1)
• Google PMax → Studio (1:1); crop to 1.91:1 after
Run `/ads generate` to use these in a full campaign.
```
## Cost Estimate
Before generating, show:
- Number of styles selected x 2 sizes = total images
- Estimated cost based on banana pricing tiers
- If >$0.50, ask for confirmation
## Platform Recommendations
| Style | Best Platforms | Rationale |
|-------|---------------|-----------|
| Studio | Meta Feed, LinkedIn, Google PMax | Universal, clean, platform-safe |
| Floating | Meta Reels, TikTok, Stories | High visual impact on vertical placements |
| Ingredient | Meta Feed, Pinterest | Works best as square; tells product story |
| In Use | TikTok, Meta Reels, Stories | Authentic, native-feeling content |
| Lifestyle | All platforms | Aspirational, broad audience appeal |
## Reference Files
- `ads-shared/references/image-providers.md`: API setup and pricing
- `ads-shared/references/brand-dna-template.md`: Brand injection schema
- `ads-shared/references/meta-creative-specs.md`: Safe zone for 9:16
- `ads-shared/references/tiktok-creative-specs.md`: Safe zone constraints
src/adclaw/agents/skills/ads-plan/SKILL.md
+174
View File
@@ -0,0 +1,174 @@
---
name: ads-plan
description: "Strategic paid advertising planning with industry-specific templates. Covers platform selection, campaign architecture, budget planning, creative strategy, and phased implementation roadmap. Use when user says ad plan, ad strategy, campaign planning, media plan, PPC strategy, or advertising plan."
---
# Strategic Paid Advertising Plan
## Process
### 1. Discovery
- Business type, products/services, target audience
- Current advertising status (active platforms, spend, performance)
- Goals: brand awareness, lead generation, e-commerce sales, app installs
- Budget range (monthly/quarterly)
- Timeline and urgency
- In-house team capacity vs agency needs
### 2. Competitive Analysis
- Identify top 3-5 competitors
- Analyze their ad presence across platforms (Google Ads Transparency, Meta Ad Library)
- Estimate competitor spend levels and platform mix
- Identify messaging themes and creative approaches
- Note keyword/audience gaps (opportunities competitors are missing)
### 3. Platform Selection
- Load industry template from `assets/` directory
- Match business type to recommended platform mix
- Read `ads-shared/references/budget-allocation.md` for platform selection matrix
- Read `ads-shared/references/conversion-tracking.md` for tracking setup requirements
- Assess platform fit based on:
- Target audience demographics per platform
- Product/service type suitability
- Budget requirements per platform (minimums)
- Sales cycle length and attribution needs
- Creative capabilities and content availability
### 4. Campaign Architecture
#### Naming Convention
```
[Platform]_[Objective]_[Audience]_[Geo]_[Date]
```
Example: `META_CONV_Prospecting_US_2026Q1`
#### Campaign Structure Template
```
Account
├── Brand Campaign (always-on, protect brand terms)
├── Non-Brand Prospecting
│ ├── Campaign 1: [Top Funnel - Awareness]
│ │ ├── Ad Group/Set 1: [Audience A]
│ │ └── Ad Group/Set 2: [Audience B]
│ ├── Campaign 2: [Mid Funnel - Consideration]
│ │ ├── Ad Group/Set 1: [Interest-based]
│ │ └── Ad Group/Set 2: [Lookalike/Similar]
│ └── Campaign 3: [Bottom Funnel - Conversion]
│ ├── Ad Group/Set 1: [High-intent]
│ └── Ad Group/Set 2: [Custom audience]
├── Retargeting
│ ├── Website Visitors (7-30 days)
│ ├── Engaged Users (video views, social engagement)
│ └── Cart Abandoners / Form Starters
└── Testing
└── New audiences, formats, or messaging
```
### 5. Budget Planning
#### Monthly Budget Distribution
Read `ads-shared/references/budget-allocation.md` for the 70/20/10 framework.
| Tier | Allocation | Purpose |
|------|-----------|---------|
| Proven (70%) | Primary platforms with proven ROI | Revenue engine |
| Scaling (20%) | Platforms showing promise | Growth engine |
| Testing (10%) | New platforms or strategies | Innovation |
#### Budget Pacing
- Month 1-2: heavy testing, expect higher CPA (learning)
- Month 3-4: optimize based on data, tighten targeting
- Month 5-6: scale winners, kill losers, expand
- Ongoing: 70/20/10 maintenance with quarterly reviews
### 6. Creative Strategy
#### Content Pillars
- **Pain Point**: address specific problems your audience faces
- **Social Proof**: testimonials, case studies, reviews
- **Product Demo**: show the product/service in action
- **Offer**: promotions, free trials, lead magnets
- **Education**: teach something valuable related to your product
#### Creative Production Plan
| Priority | Asset Type | Platforms | Quantity |
|----------|-----------|-----------|----------|
| P1 | Product/service videos (15-30s) | Meta, TikTok, YouTube | 5-10 |
| P2 | Static images with copy | Google, Meta, LinkedIn | 10-15 |
| P3 | Carousel/collection | Meta, LinkedIn | 3-5 |
| P4 | UGC/testimonial video | TikTok, Meta | 3-5 |
| P5 | Long-form video (1-3 min) | YouTube | 2-3 |
### 7. Tracking Setup Plan
Before launching any ads, ensure tracking is configured:
| Platform | Client-Side | Server-Side | Priority |
|----------|------------|-------------|----------|
| Google | gtag.js | Enhanced Conversions, GTM SS | P1 |
| Meta | Pixel | CAPI | P1 |
| LinkedIn | Insight Tag | CAPI (2025) | P2 |
| TikTok | Pixel | Events API + ttclid | P2 |
| Microsoft | UET Tag | Enhanced Conversions | P2 |
### 8. Implementation Roadmap
#### Phase 1: Foundation (Weeks 1-2)
- Install all tracking pixels and server-side tracking
- Set up conversion events and goals
- Create campaign structure and naming conventions
- Build initial audiences (custom, lookalike/predictive)
- Produce first batch of creative assets
#### Phase 2: Launch (Weeks 3-4)
- Launch campaigns on primary platform(s) first
- Set conservative budgets and bidding (Maximize Clicks / Lowest Cost)
- Monitor daily for the first 7 days
- Verify conversion tracking is firing correctly
#### Phase 3: Optimize (Weeks 5-8)
- Analyze initial data (minimum 2 weeks of data)
- Adjust bidding strategies based on conversion volume
- Kill underperforming ad groups/creatives (3x Kill Rule)
- Launch secondary platforms
- Begin A/B testing (creative, landing pages, audiences)
#### Phase 4: Scale (Weeks 9-12)
- Scale winning campaigns (20% rule)
- Expand to testing platforms (10% budget)
- Implement advanced strategies (ABM, Shopping feeds, Smart+)
- Monthly performance reviews
## Industry Templates
Load from `assets/` directory based on detected or specified business type:
- `saas.md`: SaaS companies
- `ecommerce.md`: E-commerce stores
- `local-service.md`: Local service businesses
- `b2b-enterprise.md`: B2B enterprise
- `info-products.md`: Info products and courses
- `mobile-app.md`: Mobile app companies
- `real-estate.md`: Real estate
- `healthcare.md`: Healthcare
- `finance.md`: Financial services
- `agency.md`: Marketing agencies
- `generic.md`: General business template
## Output
### Deliverables
- `ADS-STRATEGY.md`: Complete strategic advertising plan
- `CAMPAIGN-ARCHITECTURE.md`: Campaign structure with naming conventions
- `BUDGET-PLAN.md`: Budget allocation with monthly pacing
- `CREATIVE-BRIEF.md`: Creative production plan with specifications
- `TRACKING-SETUP.md`: Tracking implementation checklist
- `IMPLEMENTATION-ROADMAP.md`: Phased rollout timeline
### KPI Targets
| Metric | Month 1 | Month 3 | Month 6 | Month 12 |
|--------|---------|---------|---------|----------|
| ROAS | Baseline | Target -20% | Target | Target +20% |
| CPA | Baseline | Target +30% | Target | Target -10% |
| CVR | Baseline | +10% | +20% | +30% |
| CTR | Baseline | +15% | +25% | +30% |
| Budget | Testing | Optimizing | Scaling | Maintaining |
src/adclaw/agents/skills/ads-plan/assets/agency.md
+175
View File
@@ -0,0 +1,175 @@
<!-- Updated: 2026-02-11 -->
# Marketing Agency Paid Advertising Template
## Industry Characteristics
- Multi-client management; each client has different goals, budgets, and industries
- White-label reporting and branding requirements
- Standardized processes needed for scalable delivery
- Client retention depends on measurable results (ROAS, CPA, pipeline)
- Platform expertise across Google, Meta, LinkedIn, TikTok, Microsoft required
- Agency margin pressure; efficiency and automation are critical
- Client onboarding is a make-or-break phase (first 90 days)
- Continuous education required (platform updates happen weekly)
## Client Onboarding Checklist
### Discovery Phase (Week 1)
- [ ] Business type identified (map to industry template)
- [ ] Goals defined: brand awareness, leads, sales, app installs
- [ ] Current advertising status: platforms, spend, performance history
- [ ] Target audience: demographics, interests, behaviors, company size (B2B)
- [ ] Competitive landscape: top 3-5 competitors identified
- [ ] Budget confirmed: monthly, quarterly, and annual
- [ ] Creative assets inventory: existing images, videos, copy
- [ ] Brand guidelines provided: colors, fonts, tone, do/don't list
- [ ] Access granted: ad accounts, Google Analytics, CRM, product feed
### Technical Setup (Week 2)
- [ ] Tracking audit: pixels, tags, conversions events verified
- [ ] CAPI / server-side tracking configured (Meta, TikTok)
- [ ] Enhanced Conversions enabled (Google, Microsoft)
- [ ] UTM parameter structure defined
- [ ] Google Tag Manager setup verified
- [ ] CRM integration tested (offline conversion import)
- [ ] Attribution model selected and documented
- [ ] Reporting dashboard configured
### Campaign Launch (Weeks 3-4)
- [ ] Campaign architecture built (from industry template)
- [ ] Ad copy written and client-approved
- [ ] Creative assets produced or received
- [ ] Landing pages reviewed (message match, speed, mobile)
- [ ] Audiences built (custom, lookalike, keyword lists)
- [ ] Bid strategy set (conservative for learning phase)
- [ ] Budget pacing configured
- [ ] Conversion tracking verified (test conversion fired)
## Client Industry Template Selection
Map each client to the appropriate industry template:
| Client Type | Template | Key Considerations |
|------------|----------|-------------------|
| SaaS | `saas.md` | Long sales cycle, demo/trial conversions |
| E-commerce | `ecommerce.md` | Product feed, ROAS focus, seasonal |
| Local Service | `local-service.md` | Call tracking, LSA, geo targeting |
| B2B Enterprise | `b2b-enterprise.md` | ABM, LinkedIn, long attribution |
| Info Products | `info-products.md` | Funnel-based, Meta/YouTube primary |
| Mobile App | `mobile-app.md` | MMP required, LTV optimization |
| Real Estate | `real-estate.md` | Special Ad Category, dual audience |
| Healthcare | `healthcare.md` | HIPAA, LegitScript, compliance |
| Finance | `finance.md` | Special Ad Category, disclosures |
| Other | `generic.md` | Adapt based on specifics |
## Agency Platform Selection Matrix
### Client Budget → Platform Recommendations
| Monthly Budget | Recommended Platforms | Reasoning |
|---------------|----------------------|-----------|
| $1,000-$3,000 | Google Search only | Focus on highest-intent channel |
| $3,000-$5,000 | Google + Meta | Add prospecting/retargeting |
| $5,000-$10,000 | Google + Meta + 1 secondary | Based on industry fit |
| $10,000-$25,000 | 3-4 platforms | Full funnel coverage |
| $25,000+ | Full platform mix | Platform-specific optimization |
## Reporting Framework
### Weekly Report (Internal)
- Spend pacing (budget vs actual)
- Key metric trends (CPA, ROAS, CTR, CVR)
- Anomaly alerts (sudden performance drops)
- Action items for the week
### Monthly Client Report
- Executive summary (3-5 key takeaways)
- KPI dashboard (target vs actual)
- Platform-by-platform performance
- Top-performing campaigns, ad groups, creatives
- Recommendations and next steps
- Budget allocation review
### Quarterly Business Review (QBR)
- Goal progress (are we on track?)
- MER analysis (blended efficiency)
- Competitive landscape changes
- Platform updates and new opportunities
- Budget reallocation recommendations
- Next quarter strategy and goals
### Key Metrics by Client Type
| Client Type | Primary KPI | Secondary KPIs |
|------------|-------------|----------------|
| E-commerce | ROAS, MER | AOV, New Customer %, CVR |
| SaaS | Pipeline, CPA | MQL→SQL rate, Demo bookings |
| Lead Gen | CPL, Lead Quality | Show rate, Close rate |
| Local Service | Cost/Booked Job | Call volume, Map actions |
| Brand Awareness | Reach, Frequency | Brand lift, Search volume |
## Agency Operations
### Campaign Naming Convention (Standardized)
```
[Client]_[Platform]_[Objective]_[Audience]_[Geo]_[Date]
```
Example: `ACME_META_CONV_Lookalike1pct_US_2026Q1`
### QA Checklist (Before Launch)
- [ ] Naming convention followed
- [ ] Budget set correctly (daily/lifetime)
- [ ] Targeting verified (geo, audience, exclusions)
- [ ] Ad copy proofread (no typos, brand-compliant)
- [ ] Landing page URL correct and loads <3s
- [ ] Conversion tracking verified (test event)
- [ ] UTM parameters attached
- [ ] Negative keywords added (Search)
- [ ] Ad schedule set (if applicable)
- [ ] Client approval documented
### Optimization Cadence
| Frequency | Action |
|-----------|--------|
| Daily | Spend pacing check, anomaly detection |
| 2x/week | Bid adjustments, creative performance review |
| Weekly | Search term review, negative keyword updates |
| Bi-weekly | Creative refresh assessment, audience review |
| Monthly | Full performance analysis, budget reallocation |
| Quarterly | Strategy review, platform mix evaluation, QBR |
### LinkedIn Accelerate (for B2B Clients)
- Auto-optimized campaigns with 42% lower CPA and 21% lower CPL (LinkedIn benchmarks)
- Recommend for SaaS, B2B Enterprise, Finance, and Agency clients
- Combine with Thought Leader Ads for best results
### 3x Kill Rule (Agency Standard)
Apply across all clients:
- CPA >3x target for 7+ days → pause ad group/campaign
- No conversions after $100 spend or 50 clicks → pause and diagnose
- CTR >50% below benchmark after 1,000 impressions → kill creative
- Creative running >2x refresh cadence → flag for replacement
## Scaling Client Accounts
### When to Scale (Green Light)
- CPA consistently below target for 2+ weeks
- Client satisfied with lead/sale quality
- Creative pipeline can support increased volume
- Landing pages can handle increased traffic
- Budget approved for increase
### 20% Rule (Applied Per Client)
- Never increase budget >20% per week
- Monitor 3-5 days after each increase
- Document performance at each scale step
- Roll back if CPA exceeds target by 30%+
## Common Pitfalls
- No standardized onboarding; every client setup is different (causes errors)
- Not using industry templates; reinventing strategy for every client
- Reporting vanity metrics (impressions, clicks) instead of business outcomes
- Not having a creative production pipeline (creative dies → performance dies)
- Over-promising in sales process (unrealistic ROAS/CPA targets)
- Not tracking MER; per-platform ROAS masks true efficiency
- Skipping the QA checklist; one wrong decimal in budget = client trust destroyed
- Not documenting what works; tribal knowledge leaves with departing team members
src/adclaw/agents/skills/ads-plan/assets/b2b-enterprise.md
+167
View File
@@ -0,0 +1,167 @@
<!-- Updated: 2026-02-11 -->
# B2B Enterprise Paid Advertising Template
## Industry Characteristics
- Long sales cycles (3-12+ months)
- Multiple decision makers per deal (6-10 stakeholders average)
- High deal values justify very high CPA ($200-$1,000+)
- Account-based marketing (ABM) is the dominant strategy
- Content consumption heavy; whitepapers, webinars, case studies
- LinkedIn is the primary social platform for B2B decision makers
- Pipeline and revenue metrics matter more than lead volume
## Recommended Platform Mix
| Platform | Role | Budget % | Why |
|----------|------|----------|-----|
| LinkedIn | Primary | 40-55% | Decision-maker targeting by title, company, industry, ABM |
| Google Search | Secondary | 25-35% | High-intent category and solution queries |
| ABM Display | Secondary | 10-15% | Programmatic account-based display targeting |
| Meta | Supporting | 5-10% | Retargeting, lookalikes of closed-won accounts |
| YouTube | Testing | 5% | Thought leadership, product demos, webinar promotion |
## Campaign Architecture
```
Account; LinkedIn
├── ABM; Target Account List
│ ├── Tier 1 Accounts (named accounts, highest spend)
│ ├── Tier 2 Accounts (ICP match, moderate spend)
│ └── Tier 3 Accounts (broader ICP, lower spend)
├── Thought Leader Ads (TLA)
│ ├── CEO/Founder content
│ ├── Subject matter expert content
│ └── Customer success stories
├── Demand Gen
│ ├── Whitepaper/guide offers
│ ├── Webinar registration
│ └── Industry report downloads
├── Retargeting
│ ├── Website visitors (matched audiences)
│ └── Content engagers (video views, lead form opens)
└── Always-On Brand
└── Company page content promotion
Account; Google
├── Brand Search
├── High-Intent Category
│ ├── [Solution category] + software/platform/solution
│ ├── Enterprise [category]
│ └── [Industry] + [solution type]
├── Competitor
│ ├── [Competitor] alternative
│ └── [Competitor] vs
└── Retargeting (RLSA)
└── Past visitors searching category terms
```
## Creative Strategy
### What Works for B2B Enterprise
- **Thought Leader Ads (LinkedIn)**: exec-authored content (CPC $2.29-$4.14 vs $13.23 standard)
- **Customer case studies**: specific metrics (ROI, time saved, revenue impact)
- **Industry research**: original data and insights (gated as lead magnet)
- **Product demos**: 60-90s focused on enterprise-grade capabilities
- **Webinar promotion**: live events with industry experts
- **Document Ads (LinkedIn)**: gated content preview; native PDF viewer
### Content by Buyer Stage
| Stage | Content Type | Platform |
|-------|-------------|----------|
| Awareness | Industry insights, trend reports | LinkedIn TLA, YouTube |
| Consideration | Whitepapers, ROI calculators, webinars | LinkedIn, Google |
| Decision | Case studies, product demos, free trial | Google, LinkedIn, Meta retargeting |
| Expansion | Feature updates, customer advisory | Meta retargeting, LinkedIn |
### ABM Creative Personalization
- Company-name personalization in ad copy (LinkedIn matched audiences)
- Industry-specific pain points for vertical campaigns
- Role-specific messaging (IT vs Finance vs Operations)
- Stage-specific offers (awareness: report → consideration: demo → decision: pilot)
## Targeting Strategy
### LinkedIn (Primary)
- **Job titles**: VP, Director, C-suite of [target function]
- **Company size**: 500-1000, 1000-5000, 5000+ (match your ICP)
- **Industries**: your top-converting verticals
- **ABM lists**: upload CRM account lists (matched audiences)
- **Seniority + Function**: layer seniority on top of job function
- **Exclusions**: competitors, existing customers, job seekers
### Google
- **Keywords**: enterprise [solution], [solution] for [industry], [competitor] alternative
- **RLSA**: bid up 50-100% for past website visitors searching category terms
- **Audience layers**: in-market audiences for B2B software, business services
### Account-Based Marketing Tiers
| Tier | Accounts | Budget/Account | Personalization |
|------|----------|----------------|-----------------|
| Tier 1 | 10-50 | $500-2,000/mo | Fully personalized |
| Tier 2 | 50-200 | $100-500/mo | Industry personalized |
| Tier 3 | 200-1,000 | $20-100/mo | ICP personalized |
## Budget Guidelines
| Metric | B2B Enterprise Benchmark |
|--------|------------------------|
| LinkedIn CPC | $5-$35 (TLA: $2.29-$4.14) |
| LinkedIn CPL | $60-$150+ |
| LinkedIn CPM | $31-$38 |
| Google CPC (B2B) | $4.50-$8.00 |
| Google CPL (B2B SaaS) | $100-$200 |
| Meta CPM (B2B) | $35.00 |
| Pipeline:Spend Ratio | 5-10x |
| Min monthly budget | $10,000+ (LinkedIn + Google minimum viable for ABM) |
### Budget Allocation for ABM
| Component | % of Budget |
|-----------|-------------|
| LinkedIn ABM + TLA | 40% |
| Google Search (high intent) | 30% |
| Retargeting (cross-platform) | 15% |
| Content promotion (YouTube, Meta) | 10% |
| Testing | 5% |
## Bidding Strategy Selection
| Platform | Monthly Conversions | Recommended Strategy |
|----------|--------------------|--------------------|
| LinkedIn | Default | Maximum Delivery |
| LinkedIn | Efficiency priority | Manual CPC or Cost Cap |
| LinkedIn | Accelerate campaigns | Auto-optimized (42% lower CPA, 21% lower CPL) |
| Google | <15 | Maximize Clicks (cap CPC) |
| Google | 15-29 | Maximize Conversions |
| Google | 30+ | Target CPA |
| Meta | Default | Lowest Cost (retargeting focus) |
## Attribution & Measurement
- **Attribution window**: 90-day click minimum (enterprise sales cycles)
- **Multi-touch attribution**: track every touchpoint across LinkedIn + Google + direct
- **CRM integration**: map ad interactions to Salesforce/HubSpot pipeline stages
- **Key metrics**: pipeline generated > leads generated (quality > quantity)
- **Influence reporting**: how many deals had ad touchpoints (even if not first/last touch)
- **MQA (Marketing Qualified Account)**: account-level qualification, not just lead-level
## KPI Targets
| Metric | Month 1 | Month 3 | Month 6 |
|--------|---------|---------|---------|
| MQL Volume | Baseline | Stable | Stable |
| MQL → SQL Rate | Track | 15%+ | 25%+ |
| Pipeline Generated | Track | 5x spend | 8x spend |
| Cost per MQA | Baseline | Optimize | Target |
| LinkedIn TLA CTR | Track | 1.0%+ | 1.5%+ |
## Common Pitfalls
- Optimizing for MQL volume instead of pipeline/revenue (MQL farming)
- LinkedIn targeting too narrow (<50K audience); algorithm can't optimize
- Not using Thought Leader Ads; paying 3-5x more for standard Sponsored Content
- Same content for all buyer stages (one-size-fits-all nurture)
- Ignoring the buying committee; targeting only one persona
- No CRM integration; can't measure true pipeline impact
- Running ABM without a sales alignment plan (marketing generates, sales ignores)
- Short attribution windows (7-day) for 6-month sales cycles (undercounts everything)
src/adclaw/agents/skills/ads-plan/assets/ecommerce-creative.md
+126
View File
@@ -0,0 +1,126 @@
# E-Commerce Creative Playbook
> Updated: 2026-04-01
> Source: Used by ads-plan skill for e-commerce campaign planning
## Overview
This playbook covers 5 core campaign types for e-commerce businesses, each with
recommended creative assets, platform priorities, banana domain modes, and budget
guidance. Use alongside `copy-frameworks.md` for ad copy structure.
## Product Launch
**Creative assets needed:**
- Hero product shot (white background, studio lighting)
- Lifestyle image (product in real-world context)
- Carousel showcasing 3 to 5 key features
- Unboxing UGC video (15 to 30 seconds)
- Comparison graphic (new product vs. previous version)
**Platforms (by priority):** Meta > Google Shopping > TikTok > YouTube
**Banana domain mode:** Product
**Aspect ratios:** 1:1 (Meta feed), 9:16 (Stories, Reels, TikTok), 16:9 (YouTube)
**Copy framework:** AIDA (cold audience, new product awareness)
**Budget allocation:** 30 to 40% of total campaign budget
**Key metrics:** Impressions, CTR, add-to-cart rate, cost per acquisition
## Sale / Promotion
**Creative assets needed:**
- Bold sale banner with discount percentage
- Before/after price comparison graphic
- Countdown timer overlay for urgency
- Bundle deal carousel (3 to 4 product combos)
- Customer testimonial video with savings highlight
**Platforms (by priority):** Meta > Google RSA > Microsoft Shopping > TikTok
**Banana domain mode:** Editorial
**Aspect ratios:** 1:1 (Meta feed), 9:16 (Stories, TikTok), 1.91:1 (Google Display)
**Copy framework:** PAS (agitate fear of missing the deal, solve with discount)
**Budget allocation:** 20 to 30% of total campaign budget
**Key metrics:** ROAS, conversion rate, average order value, revenue per click
## Seasonal
**Creative assets needed:**
- Themed hero image (holiday, back-to-school, summer, etc.)
- Gift guide carousel (5 to 8 products per guide)
- Lifestyle video showing seasonal product use (15 seconds)
- Limited edition product spotlight
- Social proof overlay (ratings, reviews, bestseller badges)
**Platforms (by priority):** Meta > Google Shopping > YouTube > LinkedIn (B2B gifting)
**Banana domain mode:** Cinema
**Aspect ratios:** 1:1 (Meta feed), 9:16 (Stories, Reels), 16:9 (YouTube), 1.91:1 (Display)
**Copy framework:** BAB (before: seasonal struggle; after: solved with product)
**Budget allocation:** 15 to 25% of total campaign budget
**Key metrics:** Revenue, ROAS, new customer acquisition rate, repeat purchase rate
## Retargeting
**Creative assets needed:**
- Dynamic product ad (auto-populated from catalog)
- Cart abandonment reminder with product image
- Customer review spotlight (star rating overlay)
- Limited stock or low inventory urgency graphic
- Cross-sell carousel (complementary products)
**Platforms (by priority):** Meta > Google Display > Microsoft Audience > TikTok
**Banana domain mode:** Product
**Aspect ratios:** 1:1 (Meta feed), 1.91:1 (Google Display), 9:16 (Stories)
**Copy framework:** PAS (problem: they left without buying; solution: come back with incentive)
**Budget allocation:** 10 to 15% of total campaign budget
**Key metrics:** Return on ad spend, cost per conversion, cart recovery rate, frequency
## Brand Awareness
**Creative assets needed:**
- Brand story video (30 to 60 seconds, cinematic quality)
- Founder or team behind-the-scenes footage
- Value proposition infographic
- UGC compilation reel (customer stories)
- Aspirational lifestyle imagery (product in dream setting)
**Platforms (by priority):** YouTube > Meta > TikTok > LinkedIn
**Banana domain mode:** Cinema
**Aspect ratios:** 16:9 (YouTube), 1:1 (Meta feed), 9:16 (Reels, TikTok)
**Copy framework:** Star-Story-Solution (brand as the hero narrative)
**Budget allocation:** 10 to 15% of total campaign budget
**Key metrics:** Video view rate, reach, brand lift, engagement rate, CPM
## Platform-Specific Creative Rules
**Meta:**
- Text overlay must cover less than 20% of image area for best delivery
- Primary text truncates after 125 characters on mobile; front-load the hook
- Reels outperform static images for awareness campaigns (2 to 3x reach)
**Google:**
- Shopping images require white or neutral background, no overlays or watermarks
- RSA headlines: 30 chars max; descriptions: 90 chars max; pin sparingly
- Performance Max asset groups need at least 5 images, 1 video, 5 headlines
**TikTok:**
- First 3 seconds determine watch-through rate; start with a hook, not a logo
- Vertical 9:16 only; repurposed landscape content underperforms by 40 to 60%
- Native, lo-fi aesthetics outperform polished studio ads
**LinkedIn:**
- Single image ads: 1.91:1 ratio for sponsored content
- Carousel cards: 1:1 ratio, up to 10 cards
- Professional tone; avoid aggressive sales language or emoji-heavy copy
## A/B Testing Matrix
| Campaign Type | Test Variable 1 | Test Variable 2 | Test Variable 3 |
|------------------|-----------------------|----------------------|-------------------------|
| Product Launch | Hero shot vs. UGC | AIDA vs. BAB copy | Static image vs. video |
| Sale / Promotion | Percentage vs. dollar discount | Countdown vs. no countdown | Single product vs. bundle |
| Seasonal | Themed vs. neutral imagery | Gift guide vs. single product | Video length (15s vs. 30s) |
| Retargeting | Dynamic vs. static creative | With incentive vs. without | Review overlay vs. plain |
| Brand Awareness | Founder story vs. customer UGC | 30s vs. 60s video | Cinematic vs. raw style |
Run each test for a minimum of 7 days or 1,000 impressions per variant (whichever
comes first) before drawing conclusions. Allocate 10 to 15% of campaign budget to
testing, then scale the winning variant with the remaining budget.
src/adclaw/agents/skills/ads-plan/assets/ecommerce.md
+158
View File
@@ -0,0 +1,158 @@
<!-- Updated: 2026-02-11 -->
# E-commerce Paid Advertising Template
## Industry Characteristics
- Transaction-focused with short purchase cycles
- ROAS is the primary success metric
- Product catalog/feed drives Shopping and PMax performance
- Seasonal demand patterns (Q4 holiday, back-to-school, etc.)
- High creative volume needed across formats (static, video, UGC)
- Price competition and margin pressure require efficiency focus
- Mobile commerce dominates (82.9% of ad clicks)
## Recommended Platform Mix
| Platform | Role | Budget % | Why |
|----------|------|----------|-----|
| Meta (FB/IG) | Primary | 50-68% | Prospecting + Advantage+ Shopping Campaigns, highest scale for DTC |
| Google Shopping/PMax | Secondary | 23-30% | High-intent product searches, Shopping ads |
| TikTok | Secondary | 5-15% | Product discovery, UGC, TikTok Shop |
| Email | Supporting | 5% | Retention, repeat purchase, owned audience |
| Microsoft Shopping | Testing | 2-5% | Google import, higher-income audience |
## Campaign Architecture
```
Account; Google
├── Brand Search (always-on)
├── PMax; Core Products
│ ├── Asset Group: Best Sellers
│ ├── Asset Group: New Arrivals
│ └── Asset Group: Sale Items
├── PMax; Categories
│ ├── Asset Group: Category A
│ └── Asset Group: Category B
├── Standard Shopping (price-sensitive categories)
└── Search; Non-Brand (category terms)
Account; Meta
├── Advantage+ Shopping Campaign (ASC)
│ └── 150+ creatives (image + video + UGC mix)
├── Prospecting; Interest/Lookalike
│ ├── Ad Set: Top Performers lookalike
│ └── Ad Set: Interest stacks
├── Retargeting
│ ├── Ad Set: View Content (7 days)
│ ├── Ad Set: Add to Cart (14 days)
│ └── Ad Set: Past Purchasers (180 days, upsell/cross-sell)
└── Testing
└── New creatives, audiences, formats
Account; TikTok
├── TikTok Shop (if eligible)
├── Smart+ Campaigns
├── Spark Ads (creator content)
└── Standard In-Feed (product demos)
```
## Creative Strategy
### What Works for E-commerce
- **UGC unboxing/review**: authentic customer content outperforms studio (Spark Ads ~3% CTR vs ~2% standard)
- **Product demos**: show product in use, feature close-ups
- **Before/after**: transformation content for applicable products
- **Price anchoring**: was/now pricing, bundle savings
- **Social proof**: review count, star ratings, "best seller" badges
- **Lifestyle imagery**: product in context, aspirational
### Creative Volume Requirements
| Platform | Min Active Creatives | Refresh Cadence |
|----------|---------------------|-----------------|
| Meta ASC | 150+ in campaign | 2-4 weeks |
| Meta Standard | 5+ per ad set | 2-4 weeks |
| TikTok | 6+ per ad group | 5-7 days |
| Google PMax | Text + 20 images + 5 videos per asset group | 4-8 weeks |
### Seasonal Creative Calendar
- **Q1**: New year deals, resolution products
- **Q2**: Mother's Day, spring/summer launch
- **Q3**: Back-to-school, Labor Day, early fall
- **Q4**: Black Friday, Cyber Monday, holiday gifting (increase budget 2-3x)
## Targeting Strategy
### Google
- **Shopping/PMax**: feed-driven, optimize product titles and descriptions
- **Search**: category terms, "buy [product]", "[product] near me"
- **Exclusions**: negative keywords for informational queries, competitor brands (unless strategic)
### Meta
- **Advantage+ Audiences**: let Meta's algorithm optimize (broad works with good creative)
- **Lookalike**: top 5% purchasers, high AOV customers
- **Interest stacks**: combine 3-5 interests for refined prospecting
- **Exclusions**: past purchasers (unless cross-sell campaign)
### Product Feed Optimization (Critical)
- Product titles: [Brand] + [Product Name] + [Key Attribute] + [Size/Color]
- High-quality images: white background for Shopping, lifestyle for PMax
- Accurate pricing and availability (stale data = disapprovals)
- Custom labels for bid segmentation (margin tiers, best sellers, seasonal)
- Supplemental feeds for additional attributes
## Budget Guidelines
| Metric | E-commerce Benchmark |
|--------|---------------------|
| Google Shopping CPC | $0.50-$1.50 |
| Google Search CPC | $1.15 |
| Google Search CTR | 4.13% |
| Google ROAS | 3.68 |
| Meta CPC | $0.70-$1.32 (seasonal) |
| Meta ROAS | 2.19 (median), 4.52 (ASC) |
| TikTok CPM | $3.21-$10 |
| TikTok Shop CVR | >10% |
| CPA (Triple Whale) | $23.74 (median, +12.35% YoY) |
| Min monthly budget | $3,000+ (Google + Meta minimum viable) |
### Bidding Strategy Selection
| Platform | Monthly Conversions | Recommended Strategy |
|----------|--------------------|--------------------|
| Google | <15 | Maximize Clicks (cap CPC) |
| Google | 15-29 | Maximize Conversions |
| Google | 30+ | Target CPA |
| Google | 50+ with dynamic values | Target ROAS (recommended for e-commerce) |
| Meta | Default | Lowest Cost |
| Meta | Efficiency priority | Cost Cap at target CPA |
| Meta | Revenue tracking | ROAS Goal (4.0+ target) |
| TikTok | <50 conversions/week | Maximum Delivery |
| TikTok | 50+ conversions/week | Cost Cap |
### Seasonal Budget Adjustments
- **Q4 (Oct-Dec)**: increase 2-3x (CPMs rise 30-50%, but CVR rises too)
- **January**: reduce to baseline or below (post-holiday dip)
- **Sale events**: allocate 20% budget surge 3 days before through event
## KPI Targets
| Metric | Month 1 | Month 3 | Month 6 |
|--------|---------|---------|---------|
| ROAS | 2.0 (learning) | 3.0 | 4.0+ |
| CPA | Baseline | -15% | -25% |
| AOV | Baseline | +5% (bundles) | +10% |
| New Customer % | Track | 40%+ | 40%+ |
| MER | Track | 3.0 | 4.0+ |
| Google QS (weighted avg) | Track | ≥6 | ≥7 |
| Meta EMQ | Track | ≥7.0 | ≥8.0 (87% of advertisers are below this) |
## Common Pitfalls
- Running PMax without a well-optimized product feed (garbage in, garbage out)
- Not segmenting products by margin tier (bidding same for 10% and 60% margin)
- Ignoring new vs returning customer tracking (ROAS looks great on repeat buyers)
- Creative fatigue on Meta; not refreshing every 2-4 weeks
- TikTok Shop eligibility: only available in 11 countries (US, UK, Southeast Asia)
- Q4 panic: starting holiday campaigns in November instead of October (learning phase)
- Not running brand campaigns; letting competitors steal your branded traffic
- Measuring platform-reported ROAS without blended MER check (double-counting)
src/adclaw/agents/skills/ads-plan/assets/finance.md
+204
View File
@@ -0,0 +1,204 @@
<!-- Updated: 2026-02-11 -->
# Financial Services Paid Advertising Template
## Industry Characteristics
- **Special Ad Category**: credit, lending, and insurance ads have targeting restrictions
- Heavy regulatory compliance (FINRA, SEC, state regulations, UDAAP)
- Trust and credibility are essential; consumers are risk-averse with finances
- High CPCs but high customer lifetime value justifies aggressive bidding
- Complex products require education-first marketing
- Compliance review slows creative production cycles
- Interest rate / market conditions heavily influence demand
- Insurance, lending, investing, banking; each sub-vertical has different rules
## Compliance Requirements
### Special Ad Category (Meta)
- **Credit ads** (loans, mortgages, credit cards): must declare Special Ad Category
- **Restricted targeting**: no age, gender, ZIP code targeting
- **Minimum radius**: 15 miles
- **Special Ad Audiences**: instead of lookalikes
### Google Financial Services Policies
- Mortgage, loan, and credit ads: must display APR, fees, repayment terms
- Crypto ads: only allowed with Google certification in approved countries
- Complex speculative products (CFDs, spread betting): restricted
- Local regulations: state-specific licensing requirements must be met
### Required Disclosures
| Product Type | Required Disclosures |
|-------------|---------------------|
| Loans/Mortgages | APR, fees, repayment example, lender NMLS |
| Credit Cards | APR range, annual fee, issuer name |
| Insurance | "Not a guarantee" disclaimers, license numbers |
| Investments | "Past performance doesn't guarantee future results" |
| Banking | FDIC insured, equal housing lender (if applicable) |
### Compliance Review Process
- All ad copy requires legal/compliance team approval
- Typical review cycle: 3-7 business days
- Pre-approved copy library recommended (reduces iteration time)
- Disclaimer character count: factor into ad copy planning
## Recommended Platform Mix
| Platform | Role | Budget % | Why |
|----------|------|----------|-----|
| Google Search | Primary | 40-50% | High-intent financial product queries |
| LinkedIn | Primary | 20-30% | B2B finance, wealth management, corporate solutions |
| Meta (FB/IG) | Secondary | 15% | Awareness, education, retargeting |
| YouTube/Display | Supporting | 10% | Financial education, trust building |
| Microsoft | Testing | 5% | Higher-income demographic, desktop finance research |
## Campaign Architecture
```
Account; Google
├── Brand
│ └── [Company name], [product names]
├── Product Campaigns
│ ├── Campaign: [Product A] (e.g., "Personal Loans")
│ │ ├── Ad Group: personal loan rates
│ │ ├── Ad Group: best personal loans 2026
│ │ └── Ad Group: [specific loan type]
│ ├── Campaign: [Product B] (e.g., "Savings Accounts")
│ │ ├── Ad Group: high yield savings
│ │ └── Ad Group: best savings account rates
│ └── Campaign: [Product C]
├── Competitor
│ ├── Ad Group: [competitor] alternative
│ └── Ad Group: [competitor] vs [your brand]
├── Educational
│ ├── Ad Group: how to [financial topic]
│ └── Ad Group: [financial term] explained
└── Retargeting (RLSA)
└── Rate checker visitors, application starters
Account; Meta (Special Ad Category: Credit; if applicable)
├── Awareness / Education
│ ├── Financial literacy content
│ ├── Product explainer videos
│ └── Market insight content
├── Consideration
│ ├── Rate comparison tools
│ ├── Calculator landing pages
│ └── Customer success stories
├── Retargeting
│ ├── Website visitors (product pages)
│ ├── Application starters (not completed)
│ └── Rate checker users
└── Trust Building
└── Awards, ratings, security certifications
Account; LinkedIn (B2B Financial Products)
├── Commercial Banking / Corporate Solutions
├── Wealth Management (high-net-worth targeting)
├── Insurance (B2B, group plans)
└── Thought Leader Ads (CEO/CFO content)
```
## Creative Strategy
### What Works for Financial Services
- **Rate callouts**: "APY as high as X.XX%" (attention-grabbing, verifiable)
- **Calculator tools**: interactive landing pages (mortgage, savings, ROI calculators)
- **Security messaging**: "FDIC Insured", "Bank-level encryption", "A+ BBB rated"
- **Comparison content**: transparent rate comparisons (builds trust)
- **Customer testimonials**: with compliance-approved quotes
- **Educational video**: "How compound interest works" → subtle product promotion
- **Award/rating badges**: J.D. Power, Bankrate, NerdWallet ratings
### Creative Compliance Checklist
- [ ] Required disclosures included (APR, fees, terms)
- [ ] "Past performance" disclaimer (investments)
- [ ] License/NMLS number displayed (lending)
- [ ] Equal Housing Lender logo (mortgage)
- [ ] No guaranteed return language
- [ ] Legal/compliance team approval documented
- [ ] State-specific variations if needed
### Ad Copy Framework
- **Headline**: [Product] + [Key Benefit] + [Rate/Offer]
- **Description**: [Value prop] + [Trust signal] + [Disclosure] + [CTA]
- **Example**: "Personal Loans from 6.99% APR | No Origination Fees | Check Your Rate in 2 Minutes: No Credit Impact. FDIC Insured. NMLS #123456"
## Targeting Strategy
### Google
- **Keywords**: [product] rates, best [product] 2026, [product] calculator, [product] near me
- **Negative keywords**: free, scam, complaint, lawsuit, jobs
- **Audiences**: in-market for financial services, financial planning, insurance
- **Location**: national or state-specific (licensing considerations)
- **Ad schedule**: business hours + evening research (7-10 PM peak for financial research)
### Meta (Special Ad Category for Credit Products)
- **Broad targeting**: let algorithm optimize with good creative
- **Special Ad Audiences**: based on converters/applicants
- **Retargeting**: website visitors, video viewers, partial applications
- **Cannot use**: ZIP code, age, gender targeting for credit products
### LinkedIn (B2B Financial Products)
- **Job titles**: CFO, VP Finance, Treasury, Risk Management
- **Company size/industry**: match your ICP
- **Seniority**: Director+ for enterprise financial products
- **TLA**: thought leadership from senior execs
## Budget Guidelines
| Metric | Financial Services Benchmark |
|--------|----------------------------|
| Google CPC | $3.46-$3.77 (varies widely by product) |
| Google CTR | 4.65-8.33% |
| Google CVR | 2.55-3.50% |
| Google ROAS | 3.5x |
| Meta CPM | $50.00 (highest across industries) |
| LinkedIn CPL | $100+ (B2B financial) |
| Cost per qualified application | $50-$200 |
| Min monthly budget | $8,000+ (Google + LinkedIn minimum viable) |
### Budget by Financial Product
| Product | Monthly Budget | Primary Channel |
|---------|---------------|-----------------|
| Personal loans | $5,000-$15,000 | Google Search |
| Mortgage | $10,000-$50,000 | Google + Meta |
| Insurance | $3,000-$10,000 | Google + Meta |
| Wealth management | $5,000-$20,000 | Google + LinkedIn |
| Banking (consumer) | $10,000-$50,000 | Google + Meta + YouTube |
| Fintech | $5,000-$20,000 | Meta + Google + TikTok |
## Bidding Strategy Selection
| Platform | Monthly Conversions | Recommended Strategy |
|----------|--------------------|--------------------|
| Google | <15 | Maximize Clicks (cap CPC) |
| Google | 15-29 | Maximize Conversions |
| Google | 30+ | Target CPA |
| Google | 50+ with dynamic values | Target ROAS |
| LinkedIn | Default | Maximum Delivery |
| LinkedIn | Efficiency priority | Manual CPC or Cost Cap |
| LinkedIn | Accelerate campaigns | Auto-optimized (42% lower CPA, 21% lower CPL) |
| Meta | Default | Lowest Cost (Special Ad Category for credit) |
| Meta | Efficiency priority | Cost Cap |
## KPI Targets
| Metric | Month 1 | Month 3 | Month 6 |
|--------|---------|---------|---------|
| CPA (lead/application) | Baseline | -15% | -25% |
| Application Start → Complete Rate | Track | 30%+ | 40%+ |
| Cost per Funded Loan/Account | Track | Baseline | Optimize |
| ROAS | 1.5x | 2.5x | 3.5x |
| Brand Search Volume | Baseline | +10% | +20% |
## Common Pitfalls
- Not declaring Special Ad Category for credit products on Meta (account ban)
- Missing required disclosures (APR, fees, NMLS); ad disapproval and legal risk
- Compliance review bottleneck; not maintaining pre-approved ad copy library
- Promising guaranteed returns or specific outcomes (regulatory violation)
- Running Google Ads for crypto/CFDs without proper certification
- Ignoring state-specific licensing requirements in ad targeting
- Not tracking application start → completion funnel (high drop-off is common)
- Generic landing pages instead of product-specific pages with compliance disclaimers
- Bidding on competitor brand terms without legal team review (trademark risks in finance)
src/adclaw/agents/skills/ads-plan/assets/generic.md
+202
View File
@@ -0,0 +1,202 @@
<!-- Updated: 2026-02-11 -->
# Generic Paid Advertising Template
## Overview
This template applies to businesses that don't fit neatly into SaaS, e-commerce, local service, B2B enterprise, info products, mobile app, real estate, healthcare, finance, or agency categories. Customize based on your specific business model, goals, and audience.
## Platform Selection Questionnaire
Answer these to determine the right platform mix:
| Question | If Yes → Platform |
|----------|-------------------|
| Do people actively search for your product/service? | Google Search (primary) |
| Do you sell physical products with a catalog? | Google Shopping / PMax |
| Is your audience B2B with specific job titles? | LinkedIn |
| Is your product visual or lifestyle-oriented? | Meta (FB/IG), TikTok |
| Does your audience skew 18-34? | TikTok, Meta (IG) |
| Does your audience skew 35-64? | Google, Meta (FB), Microsoft |
| Is your target audience professional/high-income? | LinkedIn, Microsoft |
| Do you have video content or can produce it? | YouTube, TikTok, Meta |
| Is your budget under $3,000/month? | Focus on 1-2 platforms only |
| Are you in a regulated industry? | Check compliance requirements first |
## Universal Campaign Architecture
```
Account
├── Brand Campaign (always-on)
│ └── Brand name, branded terms, common misspellings
├── Prospecting; High Intent
│ ├── Ad Group/Set: [Product/service] + commercial intent
│ ├── Ad Group/Set: [Category] + buying keywords
│ └── Ad Group/Set: Competitor terms (if strategic)
├── Prospecting; Mid Intent
│ ├── Ad Group/Set: Problem-aware searches
│ └── Ad Group/Set: Category research queries
├── Retargeting
│ ├── Website visitors (7-30 days)
│ ├── Engaged users (video viewers, social engagers)
│ └── Cart abandoners / form starters
└── Testing (10% of budget)
└── New platforms, audiences, creative formats
```
## Universal Creative Principles
### Ad Copy Framework
Every ad should include:
1. **Hook**: grab attention in first line/3 seconds
2. **Benefit**: lead with what the customer gets (not features)
3. **Proof**: social proof, numbers, credentials
4. **CTA**: clear, specific action ("Get Your Free Quote", not "Learn More")
### Creative Format Priorities
| Priority | Format | Where |
|----------|--------|-------|
| P1 | Short video (15-30s) | Meta, TikTok, YouTube Shorts |
| P2 | Static images with copy | Google, Meta, LinkedIn |
| P3 | Long-form video (60-180s) | YouTube, Meta Feed |
| P4 | Carousel/collection | Meta, LinkedIn |
| P5 | Text-only (RSA) | Google Search, Microsoft |
### Extensions / Enhancements (Google/Microsoft)
- **Sitelinks** (≥4): key pages (pricing, about, contact, reviews)
- **Callouts** (≥4): unique selling points (free shipping, 24/7 support, etc.)
- **Structured snippets**: types, services, brands
- **Call extension**: if phone leads matter
- **Location extension**: if physical location exists
- **Image extension**: product or service visuals
## Universal Targeting Principles
### Start Narrow, Then Expand
1. **Month 1**: exact/phrase match keywords (Google), tight interests (Meta), narrow audiences
2. **Month 2-3**: add broad match with smart bidding (Google), expand interest stacks (Meta)
3. **Month 4+**: test broad targeting, let algorithms optimize with sufficient conversion data
### Universal Negative Keywords (Google/Microsoft)
Add these to every account:
- **Job seekers**: jobs, salary, hiring, careers, internship, resume
- **Information seekers**: what is, Wikipedia, definition, history, PDF
- **Free seekers**: free, cheap, DIY (unless you offer free products)
- **Students**: assignment, homework, essay, university project
### Audience Exclusions
- Existing customers (unless running upsell/retention campaigns)
- Employees and competitors (by company domain or IP exclusion)
- Non-converters with high frequency (Meta: frequency >8 = stale audience)
## Budget Allocation Framework
### 70/20/10 Rule
| Tier | Allocation | Purpose |
|------|-----------|---------|
| Proven (70%) | Platforms/campaigns with confirmed ROI | Revenue engine |
| Scaling (20%) | Platforms showing promise, need more data | Growth engine |
| Testing (10%) | New platforms, audiences, creatives | Innovation |
### Minimum Viable Budgets
| Platform | Minimum Monthly | Why |
|----------|----------------|-----|
| Google Search | $1,000 | Need 15+ conversions/month for smart bidding |
| Meta | $600-$800 | Need 50 conversions/week per ad set for learning |
| LinkedIn | $3,000 | High CPCs ($5-$35) require scale |
| TikTok | $300 | Low CPMs but need creative volume |
| Microsoft | 20-30% of Google | Proportional to search volume share |
## Tracking Setup (Universal)
### Before Launching Any Ads
- [ ] Google Tag Manager installed
- [ ] Google Analytics 4 configured with conversion events
- [ ] Platform pixels installed (Meta, TikTok, LinkedIn, Microsoft)
- [ ] Server-side tracking configured (Meta CAPI, Google Enhanced Conversions)
- [ ] UTM parameter structure defined
- [ ] CRM integration tested (if applicable)
- [ ] Phone call tracking configured (if applicable)
- [ ] Test conversions fired on all platforms
### UTM Structure
```
utm_source=[platform]
utm_medium=paid-[type]
utm_campaign=[campaign-name]
utm_content=[ad-name]
utm_term=[keyword] (search only)
```
## Bidding Strategy Selection
### Google/Microsoft
| Monthly Conversions | Recommended Strategy |
|--------------------|--------------------|
| <15 | Maximize Clicks (cap CPC) |
| 15-29 | Maximize Conversions |
| 30+ | Target CPA |
| 50+ with dynamic values | Target ROAS |
### Meta
| Scenario | Recommended Strategy |
|----------|---------------------|
| Volume priority | Lowest Cost (default) |
| Efficiency priority | Cost Cap |
| Maximum control | Bid Cap |
| Revenue tracking | ROAS Goal |
### Key Rules
- Never change bidding strategy during learning phase
- Wait for 50+ conversions before switching to target-based bidding
- Allow 7-14 days after changes before evaluating results
## Implementation Roadmap
### Phase 1: Foundation (Weeks 1-2)
- Install tracking (pixels, tags, server-side)
- Set up conversion events and goals
- Build campaign structure and audiences
- Produce first batch of creative
- Launch on primary platform
### Phase 2: Learn (Weeks 3-6)
- Gather data with conservative budgets
- Identify top-performing campaigns, ads, audiences
- Add negative keywords (search)
- Test 2-3 creative variations
### Phase 3: Optimize (Weeks 7-12)
- Kill underperformers (3x Kill Rule)
- Scale winners (20% rule)
- Launch secondary platform
- A/B test landing pages
- Upgrade bidding strategy (if conversion threshold met)
### Phase 4: Scale (Months 4-6)
- Increase budget on proven campaigns
- Expand to testing platforms (10% budget)
- Implement advanced features (PMax, Advantage+, TLA)
- Monthly performance reviews
## KPI Targets
| Metric | Month 1 | Month 3 | Month 6 | Month 12 |
|--------|---------|---------|---------|----------|
| ROAS | Baseline | Target -20% | Target | Target +20% |
| CPA | Baseline | Target +30% | Target | Target -10% |
| CVR | Baseline | +10% | +20% | +30% |
| CTR | Baseline | +15% | +25% | +30% |
| Budget Phase | Testing | Optimizing | Scaling | Maintaining |
## Common Pitfalls
- Launching on too many platforms at once with limited budget
- Not installing conversion tracking before spending money
- Optimizing for vanity metrics (clicks, impressions) instead of conversions
- Changing too many variables at once (can't identify what worked)
- Pausing campaigns during learning phase (resets the algorithm)
- No negative keywords (Google/Microsoft); paying for irrelevant searches
- Not refreshing creative (fatigue kills performance on all platforms)
- Ignoring mobile experience (82.9% of ad clicks come from mobile devices)
- Measuring platform-reported ROAS without blended MER check
- No retargeting; missing the easiest, highest-converting audience
src/adclaw/agents/skills/ads-plan/assets/healthcare.md
+184
View File
@@ -0,0 +1,184 @@
<!-- Updated: 2026-02-11 -->
# Healthcare Paid Advertising Template
## Industry Characteristics
- **HIPAA compliance** governs all marketing involving patient data
- Restricted ad policies on all major platforms (health conditions, treatments)
- LegitScript certification required for addiction treatment and pharmacy ads
- Trust and credibility are paramount; patients research extensively
- High CPCs ($40+ for competitive medical terms)
- Phone calls are a primary conversion (appointment booking)
- Local focus for practices, national for health systems and telehealth
- Insurance acceptance and cost transparency influence decisions
## Compliance Requirements
### HIPAA Marketing Rules
- Never use patient data for ad targeting without explicit written authorization
- Customer Match lists: use ONLY for exclusions, never for targeting with health data
- Retargeting pixel data: cannot be combined with health condition data
- Landing pages: must have privacy policy, cannot collect PHI in ad forms
- Meta CAPI / Google Enhanced Conversions: ensure no PHI transmitted
### Platform-Specific Restrictions
| Platform | Restriction | Certification |
|----------|------------|---------------|
| Google | Healthcare & medicines policy, LegitScript for rehab/pharmacy | LegitScript required for addiction treatment |
| Meta | Restricted targeting for health conditions, no symptom targeting | N/A but policy-reviewed |
| LinkedIn | Less restrictive, B2B healthcare marketing allowed | N/A |
| TikTok | Health misinformation policy, no prescription drug ads | N/A |
| Microsoft | Similar to Google, LegitScript for pharmacy | LegitScript required |
### LegitScript Certification
- **Required for**: addiction treatment, online pharmacy, telehealth prescribing
- **Process**: application, documentation review, site inspection (4-8 weeks)
- **Cost**: $1,000-$2,000 annually
- **Without it**: Google and Microsoft will reject healthcare ads in these categories
## Recommended Platform Mix
| Platform | Role | Budget % | Why |
|----------|------|----------|-----|
| Google Search | Primary | 50-60% | High-intent health queries, local search |
| Meta (FB/IG) | Secondary | 20-25% | Awareness, community building, retargeting |
| YouTube | Secondary | 10-15% | Patient education, doctor introductions, facility tours |
| Microsoft | Testing | 5-10% | Google import, older demographic (45-64: 38% of Bing) |
## Campaign Architecture
```
Account; Google
├── Brand
│ └── [Practice/hospital name], [doctor names]
├── Service-Specific
│ ├── Campaign: [Specialty A] (e.g., "Orthopedics")
│ │ ├── Ad Group: [condition] treatment [city]
│ │ ├── Ad Group: [specialty] doctor near me
│ │ └── Ad Group: [specific procedure]
│ ├── Campaign: [Specialty B]
│ │ └── Same structure
│ └── Campaign: Urgent/Walk-In
│ ├── Ad Group: urgent care near me
│ └── Ad Group: walk in clinic [city]
├── Location Campaigns
│ ├── Ad Group: [practice name] [location A]
│ └── Ad Group: [practice name] [location B]
├── Retargeting (RLSA)
│ └── Website visitors searching health terms
└── YouTube
└── Doctor introductions, patient education
Account; Meta
├── Awareness
│ ├── Doctor/provider introduction videos
│ ├── Patient success stories (with consent)
│ └── Health education content
├── Lead Generation
│ ├── New patient appointment (Lead Form)
│ ├── Free health screening offer
│ └── Insurance acceptance info
├── Retargeting
│ ├── Website visitors (service page viewers)
│ └── Video viewers (doctor intro, facility tour)
└── Community
└── Health tips, seasonal wellness, events
```
## Creative Strategy
### What Works for Healthcare
- **Doctor-to-camera videos**: builds trust, shows bedside manner
- **Facility tours**: clean, modern environments reassure patients
- **Patient testimonials**: with explicit consent, specific outcomes (within HIPAA)
- **Educational content**: "5 signs you need to see a [specialist]"
- **Staff introductions**: humanize the practice
- **Insurance/cost transparency**: "We accept [insurance]", "Affordable payment plans"
### Compliance-Safe Creative Guidelines
| Do | Don't |
|----|-------|
| Show facility and equipment | Guarantee specific medical outcomes |
| Feature consenting patient testimonials | Use before/after for medical procedures (platform-specific) |
| Educate about conditions generally | Diagnose or provide medical advice |
| Mention accepted insurance plans | Target by specific health condition |
| Highlight board certifications | Make superiority claims without evidence |
### Ad Copy Framework
- **Headline**: [Specialty/Condition] + [Location] + [Differentiator]
- **Description**: [Benefit] + [Trust signal] + [CTA]
- **Example**: "Board-Certified Orthopedic Surgeons in [City] | Same-Week Appointments | Call Now"
## Targeting Strategy
### Google
- **Location**: radius around practice locations (5-20 miles)
- **Keywords**: [condition] treatment [city], [specialty] doctor near me, [procedure] cost
- **Negative keywords**: home remedies, DIY, Wikipedia, jobs, salary, nursing school
- **Ad schedule**: match office hours + evening research (common for health)
### Meta (Restricted Targeting)
- **Cannot target**: specific health conditions, symptoms, medications
- **Can target**: age ranges (general), geography, general wellness interests
- **Retargeting**: website visitors, video viewers, lead form openers
- **Lookalike/Special Ad Audiences**: based on existing patients (email list, with consent)
### Call Tracking
- Dedicated tracking numbers per campaign
- Call recording (check state consent laws; one-party vs two-party)
- Minimum call duration for qualified lead (30+ seconds)
- Track call → appointment → patient acquisition
## Budget Guidelines
| Metric | Healthcare Benchmark |
|--------|---------------------|
| Google CPC | $10-$40+ (specialty dependent) |
| Google CTR | 4.90% |
| Google CVR | 3.10% |
| Meta CPM | $28-$36.82 |
| Meta CPL | $15-$50 (appointment request) |
| Cost per new patient | $100-$500 (specialty dependent) |
| Patient LTV | $1,000-$10,000+ |
| Min monthly budget | $4,000+ (Google-first approach) |
### Budget by Practice Type
| Practice Type | Monthly Budget | Notes |
|-------------|---------------|-------|
| Single-provider practice | $2,000-$5,000 | Google Search focused |
| Multi-location group | $5,000-$20,000 | Per-location campaigns |
| Hospital system | $20,000-$100,000+ | Service line campaigns |
| Telehealth | $5,000-$15,000 | National Google + Meta |
| Dental | $2,000-$5,000 | Lower CPC ($7.85), higher CVR |
## Bidding Strategy Selection
| Platform | Monthly Conversions | Recommended Strategy |
|----------|--------------------|--------------------|
| Google | <15 | Maximize Clicks (cap CPC) |
| Google | 15-29 | Maximize Conversions |
| Google | 30+ | Target CPA (recommended for healthcare) |
| Meta | Default | Lowest Cost |
| Meta | Efficiency priority | Cost Cap at target CPL |
## KPI Targets
| Metric | Month 1 | Month 3 | Month 6 |
|--------|---------|---------|---------|
| CPL (appointment) | Baseline | Target +20% | Target |
| Cost per New Patient | Track | Baseline | Optimize |
| Call Volume | Track | +20% | +40% |
| Show Rate (appt → visit) | Track | 70%+ | 80%+ |
| Patient Acquisition Cost | Track | <20% of patient LTV | <15% of patient LTV |
## Common Pitfalls
- Violating HIPAA in retargeting (combining health page visits with ad targeting)
- Not obtaining LegitScript certification for addiction/pharmacy (ads rejected)
- Running health condition ads with restricted targeting (policy violations)
- Sending ad traffic to generic homepage instead of condition-specific landing page
- No call tracking; can't measure patient acquisition from ads
- Promising specific medical outcomes in ad copy (policy and legal risk)
- Ignoring after-hours calls; patients searching for urgent care won't wait
- Not tracking appointment show rate; high no-show rates inflate true CPA
- Patient testimonials without proper HIPAA authorization (legal liability)

Some files were not shown because too many files have changed in this diff Show More