generated from Jerrydai/cultureos-agent-workflow
跨境电商全链路智能物流协同平台，集成国际干线调度，海关清关自动化，海外仓库存管理，跨境支付对账，多国税务筹划多智能体工作流系统
| docs | ||
| examples | ||
| gui | ||
| hermes | ||
| scripts | ||
| src/cultureos | ||
| submission | ||
| tests | ||
| web | ||
| .env.example | ||
| .gitignore | ||
| LICENSE | ||
| PROJECT.md | ||
| pyproject.toml | ||
| README.md | ||
| server.py | ||
CultureOS
面向跨文化内容营销的 AI Agent 工作流系统——把文化 IP / 品牌资产转化为可发布、可测试、可复盘的海外营销 CulturePack。
核心主张：文化适配 ≠ 翻译。 翻译解决语言问题，CultureOS 解决文化错位问题。
W3 评审快速路径
评审只需 3 步：
- 看什么 → 打开 Demo（交互式产品展示） 或向下滚动到 Agent 协作架构图 和 完整 CulturePack 产出
- 跑什么 →
python scripts/run_lucky_deer.py（一键验证：Brief → CulturePack → Trace → Schema 校验 → Smoke Eval） - 预期输出 → 7 个 Agent 依次完成 + 最终 CulturePack + smoke eval score ≥ 80
在线 Demo：
submission/prototype/index.html— 包含 Landing Page（问题 + 7 Agent 管线 + Lucky Deer 案例 + 评分）、交互式工作台（Brief → Agent 运行 → CulturePack → 审查 → 导出）、三语切换（中/EN/ES）。
# 0 前置：安装 + 配置
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env.local # 填入 DEEPSEEK_API_KEY（或用 --mock 跳过 API）
# 1 一键验证（Mock 模式，不需要 API Key）
python scripts/run_lucky_deer.py
# 2 真实 API 验证
python scripts/run_lucky_deer.py --live
# 3 提交包完整性测试
python submission/tests/test_submission.py
Agent 协作架构图
┌─────────────────────────────────────────────────────────────────────┐
│ Campaign Brief │
│ (culture_asset, target_regions, emotional_kernel, risk_boundaries) │
└──────────────────────────┬──────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────────┐
│ OrchestratorAgent │
│ 解析 Brief → 生成 workflow_plan + acceptance_criteria │
│ ★ Context Anchor: 将 Must-Have / Must-Not 约束注入元数据锚 │
└──────────────────────────┬───────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────────┐
│ MarketResearchAgent │
│ 市场信号 + 平台趋势 + 本地化机会 → market_signal_report │
└──────────────────────────┬───────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────────┐
│ CultureAdapterAgent ← 核心差异化 Agent │
│ 文化维度模型(Hofstede) + 知识库检索 + 源-目标意象映射 │
│ → culture_adaptation_plan (local_canons per region) │
└──────────────────────────┬───────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────────┐
│ ContentStrategistAgent │
│ 故事弧 + 传播策略 + A/B 方案 → content_strategy │
└──────────────────────────┬───────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────────┐
│ CopyAgent │
│ 多语言文案 + 音乐 Prompt + 视觉 Prompt + 分镜 → localized_copy │
└──────────────────────────┬───────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────────┐
│ ComplianceAgent │
│ 文化风险 + 禁忌审查 + 版权检查 → risk_report (Pass/Revise/Block) │
│ ★ 对抗式 review: Block 时回退到 ContentStrategist 重做 │
└──────────────────────────┬───────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────────┐
│ EvaluatorAgent │
│ 9 维评分 + 优劣势分析 → evaluation_report + final_recommendation │
└──────────────────────────┬───────────────────────────────────────────┘
▼
┌───────────────┐
│ CulturePack │
│ (最终交付物) │
└───────────────┘
数据持久化层：
runs/<run_id>/trace.json ← 全链路 Trace
runs/<run_id>/artifacts/ ← 每个 Agent 的原始输出
data/cultureos.db ← SQLite (runs, agent_runs, knowledge)
完整 CulturePack 产出（Lucky Deer）
以下是 examples/lucky_deer_na_latam/ 案例的真实产出全链路，证明"这不是简单翻译"：
1. 输入：Campaign Brief
{
"culture_asset": "中国东方幸运小鹿 IP",
"emotional_kernel": ["下班", "疲惫", "陪伴", "幸运", "被理解", "轻松治愈"],
"target_regions": ["North America", "Latin America"],
"risk_boundaries": [
"不使用宗教、政治或族群符号",
"不把北美简化为孤独咖啡",
"不把拉美简化为跳舞派对"
]
}
2. 市场洞察（MarketResearchAgent）
| 市场 | 核心信号 | 文化契合度 |
|---|---|---|
| 北美 | "Quiet self-kindness" 比 "good luck" 更能打动疲惫白领 | ★★★★☆ |
| 拉美 | "Warm companionship" + "everyday hope" 比幸运符号更本土 | ★★★★★ |
避开的陷阱：北美不推"lucky charm"（太轻浮），拉美不推"fiesta"（刻板印象）。
3. 文化适配（CultureAdapterAgent）
| 原始意象 | 北美转译 | 拉美转译 |
|---|---|---|
| 温柔 | Quiet comfort after a long day | Calidez que te acompaña |
| 守护 | A silent presence when you forget to be kind to yourself | Alguien que camina contigo |
| 灵动 | Gentle movement, like light through a window | Gracia natural, como la brisa |
| 幸运 | Not loud luck — soft reassurance | Suerte callada, la que no necesita gritos |
关键：适配不是翻译，是意象重构。 "鹿=幸运"在中文成立，在北美需转为"鹿=安静陪伴"，在拉美需转为"鹿=温暖同行"。
4. 文案产出（CopyAgent）
TikTok（北美）：
A little golden deer for the nights when you forget to be kind to yourself. 🦌✨
Instagram（北美）：
Not every lucky charm is loud. Some just walk beside you quietly.
TikTok（拉美）：
La suerte camina contigo, incluso en los días lentos. 🦌💫
Hashtags： #LuckyDeer #SoftHealing #GentleLuck #AfterWorkRitual
5. 合规审查（ComplianceAgent）
| 风险类型 | 等级 | 说明 | 修正建议 |
|---|---|---|---|
| healing_claim | medium | "spiritual healing" 可能被理解为疗愈承诺 | 替换为 "emotional comfort" 或 "small moment of calm" |
审查结论：ready_with_minor_review — 需人工复核文化风险项后可发布。
6. 评估得分（EvaluatorAgent）
| 维度 | 得分 | 说明 |
|---|---|---|
| 文化契合度 | 4.4/5 | 北美和拉美意象转译到位 |
| 品牌一致性 | 4.6/5 | "温柔陪伴"核心贯穿 |
| 平台适配 | 4.2/5 | TikTok/IG 格式良好 |
| 合规安全 | 4.5/5 | 1 项 medium 风险已标注 |
| 病毒潜力 | 3.8/5 | 缺少强 hook 机制 |
| 综合 | 4.3/5 | 建议发布，人工复核后上线 |
CultureAdapter 适配逻辑详解
CultureAdapterAgent 是 CultureOS 的核心差异化 Agent。它不是换 prompt 的翻译器，而是基于三层机制的文化意象重构引擎：
第一层：文化维度约束（Hofstede Model）
通过 Hofstede 六维度模型为每个目标市场建立文化约束空间：
| 维度 | 北美典型值 | 拉美典型值 | 对文案的影响 |
|---|---|---|---|
| 个人主义 | 高（91） | 中低（30-50） | 北美推"self-care"，拉美推"acompañarte" |
| 不确定性规避 | 低（46） | 高（75-90） | 北美可冒险，拉美要安全感 |
| 长期导向 | 低（26） | 中低（20-40） | 两个市场都偏即时情绪 |
这些约束被注入 CultureAdapter 的 system prompt，作为"文化语法"约束输出的情感方向。
第二层：知识库检索（KB Search）
运行时调用 context_for_agent() 从 SQLite + FTS5 知识库检索：
- 目标市场的文化禁忌（via
cultureos kb ingest --tag safety） - 同类型 IP 的历史案例（via
cultureos kb ingest --tag demo） - 行业合规政策（via
cultureos kb ingest --source-type policy）
检索结果作为 CultureAdapter 的 knowledge_context，确保输出不踩文化红线。
第三层：源-目标意象映射
将源文化的意象拆解为原子情感（emotional_kernel），然后在目标文化中找到等价但不同的表达载体：
中文"鹿"= 幸运 + 灵动 + 温柔
↓ 拆解
北美: quiet comfort (非 loud luck)
拉美: warm companionship (非 fiesta)
这不是翻译"鹿"这个字，而是在目标文化中找到能承载相同情感的不同意象载体。
详见 docs/culture-adapter-logic.md。
我们做什么 / 不做什么
| 做 | 不做 |
|---|---|
| 生成 CulturePack（文案 + 视觉建议 + 投放策略） | 实际投放执行 |
| 文化适配 + 合规风险标注 | 法律合规认证 |
| Smoke Eval 自动评分 + 人工审查建议 | 为 ROI 兜底 |
| 多市场并行生成 | 版权清算 / IP 授权 |
| 知识库辅助的合规审查 | 替代专业法律/文化顾问 |
免责声明： ComplianceAgent 的输出是 AI 辅助参考，不构成法律合规建议。所有 CulturePack 在实际发布前必须经过人工审查。文化敏感性容错率极低，AI 标注的"low risk"不等于"无风险"。
性能基准数据
基于 DeepSeek-Chat（deepseek-chat）运行 lucky_deer_na_latam 案例：
| 指标 | 数值 |
|---|---|
| 端到端耗时 | 3-5 分钟 |
| 总 Token 消耗 | ~15,000-20,000 |
| 单次成本（DeepSeek） | ¥0.3-0.5 |
| Agent 平均延迟 | 20-40s/Agent |
| Mock 模式耗时 | < 3 秒 |
前置依赖：Python 3.10+，无需 GPU，无需商业 API（可用 --mock 模式）。
目标用户
当前聚焦： 小型文化 IP 公司 / 品牌出海团队——有内容资产需要适配、有预算、理解 CulturePack 的价值。
后续扩展： 个人创作者（Wave 3+，轻量化单平台版）。
目录说明
cultureos-agent-workflow/
├── README.md ← 你在这里
├── PROJECT.md ← 项目愿景
├── pyproject.toml ← Python 包配置
├── scripts/
│ └── run_lucky_deer.py ← 一键验证脚本
├── src/cultureos/
│ ├── agents/ ← Agent 定义（base + registry）
│ ├── workflows/ ← CulturePack 工作流
│ ├── runtime/ ← 配置、模型客户端、数据库、知识库、评测
│ └── exporters/ ← Markdown 导出
├── submission/ ← Wave 2 复赛提交包
├── examples/
│ ├── lucky_deer_na_latam/ ← 北美+拉美双市场 Demo
│ └── lucky_deer_latam/ ← 拉美单独对照案例
├── docs/
│ ├── culture-adapter-logic.md ← CultureAdapter 适配逻辑详解
│ ├── quality-evaluation.md ← 质量评价标准
│ ├── local-deployment.md ← 本地部署
│ ├── product-requirements.md ← 产品需求
│ ├── wave2-submission.md ← 提交说明
│ ├── online-preview.md ← 在线预览
│ ├── local-verification.md ← 本地验证
│ ├── hermes-orchestration.md ← Hermes 编排
│ └── synnovator-connection.md ← Synnovator 连接
├── tests/ ← 单元测试
└── hermes/ ← Hermes 编排计划
快速开始
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env.local
配置 .env.local：
AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=your_key_here
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat
运行
# Mock 模式（不需要 API Key）
cultureos run examples/lucky_deer_na_latam/input.json --mock
# 真实 API 模式
cultureos run examples/lucky_deer_na_latam/input.json
# 一键验证（推荐）
python scripts/run_lucky_deer.py # Mock 模式
python scripts/run_lucky_deer.py --live # 真实 API
初始化数据库和知识库：
cultureos db init
cultureos kb ingest ../SAFETY_GATE.md --source-type policy --language zh --tag safety
cultureos kb ingest ../CULTUREPACK_DEMO.md --source-type case --language zh --region "Latin America" --tag demo
cultureos kb search "东方幸运小鹿 Safety Gate" --source-type policy --tag safety
cultureos kb sources
查看 Agent 输出 schema：
cultureos schemas list
运行离线 smoke eval：
cultureos eval run --suite smoke
输出写入：
runs/<run_id>/
input.json
artifacts/*.json
final_culture_pack.md
trace.json
数据库默认写入 data/cultureos.db（支持 Region 隔离，见 docs/culture-adapter-logic.md）。
复赛提交包
Wave 2 复赛提交材料位于 submission/，包含 Skill manifest、3 个关键 Skill、HTML 原型、Specs、Samples、Trace 和完整性测试。
验证提交包：
python submission/tests/test_submission.py
第一版优先可靠和可审查，不做自动发布、不做 Web UI、不自研复杂 Agent runtime。