About-Intelligence/soku-cli

Soku CLI – 为 AI 代理提供的安全命令行桥梁

它是什么

• 一个基于 Node 的命令行工具 (@soku-ai/cli)，让大型语言模型代理 (Claude, Codex, Cursor 等) 能直接与 Soku 工作区中的服务进行对话，包含广告平台、分析、SEO 托管、自动化等。
• 此 CLI 将 Soku 后端公开的功能转化为具类型、可探索的 Shell 指令，并返回代理程序无需人工介入即可解析的稳定 JSON 封装。

为什么它很重要

• 统一的接口：针对增长堆栈（Google Ads, Meta Ads, TikTok, GA4, PostHog, SEO 托管等），皆可通过相同的 soku … 指令访问。
• 代理优先设计 – 指令具备自我说明性、非交互式，并输出 JSON ({"ok":true,"data":…})，让 LLM 能以程序化方式调用并可靠地处理错误。
• 凭证安全性 – 验证由 Soku 处理；API 密钥绝不会出现在提示词中。
• 人工介入写入 – 任何会变更广告投放的操作都会创建审核请求，必须在执行前手动核准。

入门指南

1. 使用 npm install -g @soku-ai/cli 全局安装（需 Node 20+）或通过 npx 执行。
2. 使用 soku auth login 登录（基于浏览器的设备流程）。
3. 选择工作区 (soku workspace resolve <brand> → soku workspace use-brand <brand>)。
4. 使用 soku skill install <slug> 或 soku skill install --all --global 安装所需的“技能”（特定业务指令集）。
5. 执行 soku --help 查看完整的指令树。

典型使用案例

目标	示例指令	功能说明
查询广告成效	soku ads query-single-dimension --platform google --account-id 123 --dimension campaign --date-start 2026-06-01 --date-end 2026-06-30	从 Google Ads 获取广告活动层级指标并返回 JSON。
结合获客与产品数据	soku ga4 list-properties → soku posthog query --project-id xyz --tool execute-sql --arguments '{"query":"SELECT count() FROM events WHERE event = \"$pageview\""}'	拉取 GA4 资源信息并在 PostHog 事件上执行 SQL 查询，让代理程序能追踪支出 → 流量 → 产品内行为。
创建新广告活动（人工核准）	soku ads meta campaign create --account-id 456 --name "Launch Test" --objective OUTCOME_TRAFFIC --summary "Create paused Meta traffic campaign Launch Test"	产生审核 ID；代理程序可呈现计划，随后由人工执行 soku review approve <id>。
发布 SEO 内容	soku seo-hosting pages put --section blog --slug launch-notes --title "Launch notes" --html-file page.html 接着执行 soku seo-hosting pages publish --section blog --slug launch-notes	通过 Soku 的 SEO 托管服务暂存并发布静态 HTML 页面。
调度周期性代理工作	soku automation create --name "Weekly account health" --prompt "Review paid acquisition performance and flag anomalies" --cron "0 9 * * 1" --timezone America/Los_Angeles	设置一个类似 cron 的自动化任务，让 LLM 每周执行。
提供上下文文件	soku context upload ./campaign-brief.pdf --dir research	将 PDF 上传至工作区的 Context Hub，以便代理程序在回答问题时参考。

运行原理

• 此 CLI 调用 Soku 的 /api/cli/* 端点；无需额外的 MCP 主机。
• 具类型指令是从 src/generated/capabilities.json 自动生成的，该文件反映了后端功能注册表。
• 对于缺乏友好类型指令的功能，可使用通用的 soku call <namespace> <action> … 语法。
• 凭证存储使用选用的 keytar 库；若无法使用，则退回至基于文件的存储方式。

开发与贡献

• 使用 TypeScript, ESM 与 NodeNext 模块解析构建。
• 标准脚本：pnpm install, pnpm typecheck, pnpm test, pnpm build。
• 测试与源代码文件并存 (*.test.ts) 并使用 Node 内置的测试执行器执行。
• 欢迎通过常见的 GitHub 工作流程贡献；请参阅 CONTRIBUTING.md, CODE_OF_CONDUCT.md 与 SECURITY.md 以了解准则。

总结 Soku CLI 是一个实用的桥梁，让 AI 代理能安全且透明地操作真实世界的营销与分析工具，将复杂的增长堆栈转化为一组可预测、由 JSON 驱动的 Shell 指令。