From 3cb5a0fbd6be184f007cf1285672cd59a431326c Mon Sep 17 00:00:00 2001 From: zhayujie Date: Sun, 29 Mar 2026 17:57:12 +0800 Subject: [PATCH] docs: add CLI system docs --- README.md | 54 ++++-- agent/prompt/builder.py | 2 +- cli/commands/install.py | 112 ++++++++---- cli/commands/skill.py | 86 +++++++++ docs/commands/general.mdx | 115 ++++++++++++ docs/commands/index.mdx | 86 +++++++++ docs/commands/process.mdx | 134 ++++++++++++++ docs/commands/skill.mdx | 218 +++++++++++++++++++++++ docs/docs.json | 102 +++++++---- docs/en/README.md | 49 ++++- docs/en/commands/general.mdx | 101 +++++++++++ docs/en/commands/index.mdx | 84 +++++++++ docs/en/commands/process.mdx | 123 +++++++++++++ docs/en/commands/skill.mdx | 192 ++++++++++++++++++++ docs/en/guide/manual-install.mdx | 42 ++++- docs/en/guide/quick-start.mdx | 25 +-- docs/en/intro/index.mdx | 6 + docs/en/memory/context.mdx | 80 +++++++++ docs/en/{memory.mdx => memory/index.mdx} | 46 ++--- docs/en/skills/create.mdx | 58 ++++++ docs/en/skills/image-vision.mdx | 31 ---- docs/en/skills/index.mdx | 19 +- docs/en/skills/install.mdx | 53 ++++++ docs/en/skills/linkai-agent.mdx | 47 ----- docs/en/skills/skill-creator.mdx | 31 ---- docs/en/skills/web-fetch.mdx | 31 ---- docs/guide/manual-install.mdx | 104 ++++++++--- docs/guide/quick-start.mdx | 24 ++- docs/guide/upgrade.mdx | 27 ++- docs/intro/index.mdx | 10 +- docs/ja/README.md | 49 ++++- docs/ja/commands/general.mdx | 101 +++++++++++ docs/ja/commands/index.mdx | 84 +++++++++ docs/ja/commands/process.mdx | 123 +++++++++++++ docs/ja/commands/skill.mdx | 192 ++++++++++++++++++++ docs/ja/guide/manual-install.mdx | 42 ++++- docs/ja/guide/quick-start.mdx | 25 +-- docs/ja/guide/upgrade.mdx | 27 ++- docs/ja/intro/index.mdx | 6 + docs/ja/memory/context.mdx | 80 +++++++++ docs/ja/{memory.mdx => memory/index.mdx} | 39 ++-- docs/ja/skills/create.mdx | 58 ++++++ docs/ja/skills/image-vision.mdx | 31 ---- docs/ja/skills/index.mdx | 41 ++--- docs/ja/skills/install.mdx | 53 ++++++ docs/ja/skills/linkai-agent.mdx | 47 ----- docs/ja/skills/skill-creator.mdx | 31 ---- docs/ja/skills/web-fetch.mdx | 31 ---- docs/memory/context.mdx | 80 +++++++++ docs/{memory.mdx => memory/index.mdx} | 46 ++--- docs/skills/create.mdx | 58 ++++++ docs/skills/image-vision.mdx | 31 ---- docs/skills/index.mdx | 19 +- docs/skills/install.mdx | 53 ++++++ docs/skills/linkai-agent.mdx | 47 ----- docs/skills/skill-creator.mdx | 31 ---- docs/skills/web-fetch.mdx | 31 ---- docs/tools/browser.mdx | 106 +++++++++-- docs/tools/index.mdx | 21 ++- docs/tools/vision.mdx | 36 ++++ docs/tools/web-fetch.mdx | 32 ++++ scripts/run.ps1 | 2 +- 62 files changed, 2995 insertions(+), 750 deletions(-) create mode 100644 docs/commands/general.mdx create mode 100644 docs/commands/index.mdx create mode 100644 docs/commands/process.mdx create mode 100644 docs/commands/skill.mdx create mode 100644 docs/en/commands/general.mdx create mode 100644 docs/en/commands/index.mdx create mode 100644 docs/en/commands/process.mdx create mode 100644 docs/en/commands/skill.mdx create mode 100644 docs/en/memory/context.mdx rename docs/en/{memory.mdx => memory/index.mdx} (56%) create mode 100644 docs/en/skills/create.mdx delete mode 100644 docs/en/skills/image-vision.mdx create mode 100644 docs/en/skills/install.mdx delete mode 100644 docs/en/skills/linkai-agent.mdx delete mode 100644 docs/en/skills/skill-creator.mdx delete mode 100644 docs/en/skills/web-fetch.mdx create mode 100644 docs/ja/commands/general.mdx create mode 100644 docs/ja/commands/index.mdx create mode 100644 docs/ja/commands/process.mdx create mode 100644 docs/ja/commands/skill.mdx create mode 100644 docs/ja/memory/context.mdx rename docs/ja/{memory.mdx => memory/index.mdx} (52%) create mode 100644 docs/ja/skills/create.mdx delete mode 100644 docs/ja/skills/image-vision.mdx create mode 100644 docs/ja/skills/install.mdx delete mode 100644 docs/ja/skills/linkai-agent.mdx delete mode 100644 docs/ja/skills/skill-creator.mdx delete mode 100644 docs/ja/skills/web-fetch.mdx create mode 100644 docs/memory/context.mdx rename docs/{memory.mdx => memory/index.mdx} (56%) create mode 100644 docs/skills/create.mdx delete mode 100644 docs/skills/image-vision.mdx create mode 100644 docs/skills/install.mdx delete mode 100644 docs/skills/linkai-agent.mdx delete mode 100644 docs/skills/skill-creator.mdx delete mode 100644 docs/skills/web-fetch.mdx create mode 100644 docs/tools/vision.mdx create mode 100644 docs/tools/web-fetch.mdx diff --git a/README.md b/README.md index 24b1194c..e314a29f 100644 --- a/README.md +++ b/README.md @@ -21,12 +21,14 @@ > 该项目既是一个可以开箱即用的超级 AI 助理，也是一个支持高扩展的 Agent 框架，可以通过为项目扩展大模型接口、接入渠道、内置工具、Skills 系统来灵活实现各种定制需求。核心能力如下： -- ✅ **复杂任务规划**：能够理解复杂任务并自主规划执行，持续思考和调用工具直到完成目标，支持通过工具操作访问文件、终端、浏览器、定时任务等系统资源 -- ✅ **长期记忆：** 自动将对话记忆持久化至本地文件和数据库中，包括全局记忆和天级记忆，支持关键词及向量检索 -- ✅ **技能系统：** 实现了 Skills 创建和运行的引擎，内置多种技能，并支持通过自然语言对话完成自定义 Skills 开发 +- ✅ **自主任务规划**：能够理解复杂任务并自主规划执行，持续思考和调用工具直到完成目标 +- ✅ **长期记忆：** 自动将对话记忆持久化至本地文件和数据库中，包括核心记忆和日级记忆，支持关键词及向量检索 +- ✅ **技能系统：** 实现了 Skills 创建和运行的引擎，支持从 Skill Hub、GitHub 等安装技能，或通过对话创造自定义 Skills +- ✅ **工具系统：** 内置文件读写、终端执行、浏览器操作、定时任务、消息发送等工具，Agent 自主调用以完成复杂任务 +- ✅ **CLI系统：** 提供终端命令和对话命令，支持进程管理、技能安装、配置修改等操作 - ✅ **多模态消息：** 支持对文本、图片、语音、文件等多类型消息进行解析、处理、生成、发送等操作 -- ✅ **多模型接入：** 支持 OpenAI, Claude, Gemini, DeepSeek, MiniMax、GLM、Qwen、Kimi、Doubao 等国内外主流模型厂商 -- ✅ **多端部署：** 支持运行在本地计算机或服务器，可集成到微信、飞书、钉钉、企业微信、QQ、微信公众号、网页中使用 +- ✅ **多模型支持：** 支持 OpenAI, Claude, Gemini, DeepSeek, MiniMax、GLM、Qwen、Kimi、Doubao 等国内外主流模型厂商 +- ✅ **多通道接入：** 支持运行在本地计算机或服务器，可集成到微信、飞书、钉钉、企业微信、QQ、微信公众号、网页中使用 ## 声明 @@ -90,7 +92,7 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh) ``` -脚本使用说明：[一键运行脚本](https://docs.cowagent.ai/guide/quick-start) +脚本使用说明：[一键运行脚本](https://docs.cowagent.ai/guide/quick-start)。安装后也可使用 `cow start`、`cow stop` 等 [CLI 命令](https://docs.cowagent.ai/commands/index) 管理服务。 ## 一、准备 @@ -134,6 +136,24 @@ pip3 install -r requirements-optional.txt 如果某项依赖安装失败可注释掉对应的行后重试。 +**(4) 安装 Cow CLI (推荐)：** + +```bash +pip3 install -e . +``` + +安装后可使用 `cow` 命令管理服务（启动、停止、更新等）和技能，详见 [命令文档](https://docs.cowagent.ai/commands/index)。 + +**(5) 安装浏览器工具 (可选)：** + +如果需要 Agent 操作浏览器（如访问网页、填写表单等），需要额外安装浏览器依赖： + +```bash +cow install-browser +``` + +该命令会自动安装 `playwright` 和 Chromium 浏览器，国内网络自动使用镜像加速。详见 [浏览器工具文档](https://docs.cowagent.ai/tools/browser)。 + ## 二、配置 配置文件的模板在根目录的 `config-template.json` 中，需复制该模板创建最终生效的 `config.json` 文件： @@ -210,7 +230,8 @@ pip3 install -r requirements-optional.txt 如果是个人计算机 **本地运行**，直接在项目根目录下执行： ```bash -python3 app.py # windows 环境下该命令通常为 python app.py +cow start # 推荐，需先安装 Cow CLI +python3 app.py # 或直接运行，windows 环境下该命令通常为 python app.py ``` 运行后默认会启动 web 服务，可通过访问 `http://localhost:9899/chat` 在网页端对话。 @@ -220,15 +241,24 @@ python3 app.py # windows 环境下该命令通常为 python app.py ### 2.服务器部署 -在服务器中可使用 `nohup` 命令在后台运行程序： +推荐使用 `cow` 命令管理服务： + +```bash +cow start # 后台启动 +cow stop # 停止服务 +cow restart # 重启服务 +cow status # 查看运行状态 +cow logs # 查看日志 +cow update # 拉取最新代码并重启 +``` + +也可以使用传统方式后台运行： ```bash nohup python3 app.py & tail -f nohup.out ``` -执行后程序运行于服务器后台，可通过 `ctrl+c` 关闭日志，不会影响后台程序的运行。使用 `ps -ef | grep app.py | grep -v grep` 命令可查看运行于后台的进程，如果想要重新启动程序可以先 `kill` 掉对应的进程。 日志关闭后如果想要再次打开只需输入 `tail -f nohup.out`。 - -此外，项目根目录下的 `run.sh` 脚本支持一键启动和管理服务，包括 `./run.sh start`、`./run.sh stop`、`./run.sh restart`、`./run.sh logs` 等命令，执行 `./run.sh help` 可查看全部用法。 +此外，项目根目录下的 `run.sh` 脚本也支持一键管理服务，包括 `./run.sh start`、`./run.sh stop`、`./run.sh restart` 等命令，执行 `./run.sh help` 可查看全部用法。 > 如果需要通过浏览器访问 Web 控制台，请确保服务器的 `9899` 端口已在防火墙或安全组中放行，建议仅对指定 IP 开放以保证安全。 @@ -843,7 +873,7 @@ FAQs： # 🛠️ 开发 -欢迎接入更多应用通道，参考 [飞书通道](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py) 新增自定义通道，实现接收和发送消息逻辑即可完成接入。 同时欢迎贡献新的Skills，参考 [Skill创造器说明](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md)。 +欢迎接入更多应用通道，参考 [飞书通道](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py) 新增自定义通道，实现接收和发送消息逻辑即可完成接入。同时欢迎贡献新的 Skills，参考 [技能创建文档](https://docs.cowagent.ai/skills/create)。 # ✉ 联系 diff --git a/agent/prompt/builder.py b/agent/prompt/builder.py index c9d48454..4a54963e 100644 --- a/agent/prompt/builder.py +++ b/agent/prompt/builder.py @@ -384,7 +384,7 @@ def _build_workspace_section(workspace_dir: str, language: str) -> List[str]: "**💬 交流规范**:", "", "- 对话中不要暴露内部技术细节（文件名、工具名等），用自然语言表达。例如说「我已记住」而非「已更新 MEMORY.md」", - "- 做真正有帮助的助手，而不是表演式的客套。跳过「好的！」「当然可以！」之类的套话，直接帮忙解决问题", + "- 做真正有帮助的助手，而不是表演式的客套，尽可能帮忙解决问题", "- 回复应结构清晰、重点突出。善用 **加粗**、列表、分段等格式让信息一目了然", "- 适当使用 emoji 让表达更生动自然 🎯，但不要过度堆砌", "", diff --git a/cli/commands/install.py b/cli/commands/install.py index 525848b0..b4b6015d 100644 --- a/cli/commands/install.py +++ b/cli/commands/install.py @@ -6,8 +6,10 @@ import subprocess import click -MIN_PLAYWRIGHT_VERSION = "1.49.0" -MIN_GLIBC_VERSION = (2, 28) +PLAYWRIGHT_VERSION = "1.49.0" +PLAYWRIGHT_LEGACY_VERSION = "1.28.0" +GLIBC_THRESHOLD = (2, 28) +CHINA_MIRROR = "https://registry.npmmirror.com/-/binary/playwright" def _has_display() -> bool: @@ -16,16 +18,13 @@ def _has_display() -> bool: def _is_headless_linux() -> bool: - """True when running on a Linux server without a display.""" return sys.platform == "linux" and not _has_display() def _get_installed_version() -> str: - """Return installed playwright version string, or empty if not installed.""" - python = sys.executable try: out = subprocess.check_output( - [python, "-c", "import playwright; print(playwright.__version__)"], + [sys.executable, "-c", "import playwright; print(playwright.__version__)"], stderr=subprocess.DEVNULL, ) return out.decode().strip() @@ -34,7 +33,6 @@ def _get_installed_version() -> str: def _version_tuple(v: str): - """Parse '1.49.0' into (1, 49, 0).""" try: return tuple(int(x) for x in v.split(".")[:3]) except (ValueError, AttributeError): @@ -42,7 +40,6 @@ def _version_tuple(v: str): def _get_glibc_version(): - """Return glibc version as (major, minor) tuple, or None if unavailable.""" if sys.platform != "linux": return None try: @@ -57,41 +54,62 @@ def _get_glibc_version(): return None +def _is_china_network() -> bool: + try: + out = subprocess.check_output( + [sys.executable, "-m", "pip", "config", "get", "global.index-url"], + stderr=subprocess.DEVNULL, + ) + url = out.decode().strip().lower() + return any(kw in url for kw in ("tsinghua", "aliyun", "npmmirror", "douban", "ustc", "huawei", "tencentyun")) + except Exception: + return False + + +def _pip_install(package_spec: str) -> int: + """Install a package, retrying with --user on permission failure.""" + python = sys.executable + ret = subprocess.call([python, "-m", "pip", "install", package_spec]) + if ret != 0: + click.echo(" Retrying with --user flag...") + ret = subprocess.call([python, "-m", "pip", "install", "--user", package_spec]) + return ret + + @click.command("install-browser") def install_browser(): """Install browser tool dependencies (Playwright + Chromium).""" python = sys.executable + legacy_mode = False - # Pre-check: glibc version on Linux - if sys.platform == "linux": - glibc = _get_glibc_version() - if glibc and glibc < MIN_GLIBC_VERSION: - glibc_str = f"{glibc[0]}.{glibc[1]}" - click.echo(click.style( - f"Your system glibc version is {glibc_str}, " - f"but Playwright requires glibc >= {MIN_GLIBC_VERSION[0]}.{MIN_GLIBC_VERSION[1]}.\n" - f"(e.g. Ubuntu 18.04 ships glibc 2.27, CentOS 7 ships glibc 2.17)\n\n" - f"Options:\n" - f" 1. Upgrade your OS (e.g. Ubuntu 20.04+, Debian 10+, CentOS 8+)\n" - f" 2. Use Docker with a newer Linux image\n" - f" 3. Install an older playwright version manually (not recommended):\n" - f" pip install playwright==1.30.0 && playwright install chromium", - fg="red", - )) - raise SystemExit(1) + # Determine playwright version based on glibc + glibc = _get_glibc_version() + if glibc and glibc < GLIBC_THRESHOLD: + legacy_mode = True + glibc_str = f"{glibc[0]}.{glibc[1]}" + click.echo(click.style( + f"glibc {glibc_str} detected (< 2.28). " + f"Will install playwright {PLAYWRIGHT_LEGACY_VERSION} for compatibility.", + fg="yellow", + )) + click.echo(click.style( + " Note: upgrade your OS for full browser tool support.", + fg="yellow", + )) + click.echo() - # Step 1: Install / upgrade playwright package + target_version = PLAYWRIGHT_LEGACY_VERSION if legacy_mode else PLAYWRIGHT_VERSION + + # Step 1: Install playwright package click.echo(click.style("[1/3] Installing playwright Python package...", fg="yellow")) - ret = subprocess.call([python, "-m", "pip", "install", f"playwright>={MIN_PLAYWRIGHT_VERSION}"]) + ret = _pip_install(f"playwright=={target_version}" if legacy_mode else f"playwright>={target_version}") if ret != 0: click.echo(click.style("Failed to install playwright package.", fg="red")) raise SystemExit(1) installed = _get_installed_version() if installed: - click.echo(click.style(f"playwright {installed} installed.", fg="green")) - else: - click.echo(click.style("playwright package installed.", fg="green")) + click.echo(click.style(f" playwright {installed} installed.", fg="green")) click.echo() # Step 2: System dependencies (Linux only) @@ -100,7 +118,7 @@ def install_browser(): ret = subprocess.call([python, "-m", "playwright", "install-deps", "chromium"]) if ret != 0: click.echo(click.style( - "Could not auto-install system deps (may need sudo).\n" + " Could not auto-install system deps (may need sudo).\n" f" Run manually: sudo {python} -m playwright install-deps chromium", fg="yellow", )) @@ -113,20 +131,42 @@ def install_browser(): cmd = [python, "-m", "playwright", "install", "chromium"] # --only-shell requires playwright >= 1.57 - if _is_headless_linux(): - ver = _version_tuple(_get_installed_version()) + if _is_headless_linux() and not legacy_mode: + ver = _version_tuple(installed or "") if ver >= (1, 57, 0): cmd.append("--only-shell") click.echo(" (headless shell for Linux server)") else: - click.echo(" (full Chromium - upgrade to playwright>=1.57 for smaller headless-only install)") - elif sys.platform == "linux": + click.echo(" (full Chromium)") + elif sys.platform == "linux" and _has_display(): click.echo(" (full browser for Linux desktop)") - ret = subprocess.call(cmd) + # Use China mirror if pip is configured with a domestic index + env = os.environ.copy() + if _is_china_network(): + env["PLAYWRIGHT_DOWNLOAD_HOST"] = CHINA_MIRROR + click.echo(f" (using China mirror: {CHINA_MIRROR})") + + ret = subprocess.call(cmd, env=env) if ret != 0: click.echo(click.style("Failed to install Chromium.", fg="red")) raise SystemExit(1) + # Quick smoke test + click.echo() + click.echo("Verifying browser installation...") + ret = subprocess.call( + [python, "-c", "from playwright.sync_api import sync_playwright; print('OK')"], + stderr=subprocess.DEVNULL, + ) + if ret != 0: + click.echo(click.style( + " Warning: playwright import failed. Browser tool may not work on this system.\n" + " Consider upgrading your OS or using Docker.", + fg="yellow", + )) + else: + click.echo(click.style(" Verification passed.", fg="green")) + click.echo() click.echo(click.style("Browser tool ready! Restart CowAgent to enable it.", fg="green")) diff --git a/cli/commands/skill.py b/cli/commands/skill.py index 51187262..11e63db2 100644 --- a/cli/commands/skill.py +++ b/cli/commands/skill.py @@ -419,6 +419,87 @@ def _install_url(url: str, result: InstallResult): result.messages.append(f"Installed '{skill_name}' from URL.") +def _install_archive_url(url: str, result: InstallResult): + """Install skill(s) from a remote zip/tar.gz archive URL.""" + parsed = urlparse(url) + if parsed.scheme != "https": + raise SkillInstallError("Refusing to download from non-HTTPS URL.") + + filename = os.path.basename(parsed.path).split("?")[0] + fallback_name = re.sub(r'\.(zip|tar\.gz|tgz)$', '', filename, flags=re.IGNORECASE) + if not fallback_name or not _SAFE_NAME_RE.match(fallback_name): + fallback_name = "skill-package" + + result.messages.append(f"Downloading archive from {url} ...") + try: + resp = requests.get(url, timeout=120, allow_redirects=True) + resp.raise_for_status() + except Exception as e: + raise SkillInstallError(f"Failed to download archive: {e}") + + skills_dir = get_skills_dir() + os.makedirs(skills_dir, exist_ok=True) + + content_type = resp.headers.get("Content-Type", "") + lower_url = url.lower() + + if lower_url.endswith((".tar.gz", ".tgz")) or "gzip" in content_type: + _install_targz_bytes(resp.content, fallback_name, skills_dir, result) + else: + _install_zip_bytes(resp.content, fallback_name, skills_dir, result=result, source_label="url") + + +def _install_targz_bytes(content: bytes, name: str, skills_dir: str, result: InstallResult): + """Extract a tar.gz archive and install skill(s).""" + with tempfile.TemporaryDirectory() as tmp_dir: + tar_path = os.path.join(tmp_dir, "package.tar.gz") + with open(tar_path, "wb") as f: + f.write(content) + + import tarfile + extract_dir = os.path.join(tmp_dir, "extracted") + os.makedirs(extract_dir) + with tarfile.open(tar_path, "r:gz") as tf: + for member in tf.getmembers(): + resolved = os.path.realpath(os.path.join(extract_dir, member.name)) + if not resolved.startswith(os.path.realpath(extract_dir)): + raise SkillInstallError("Archive contains path traversal, aborting.") + tf.extractall(extract_dir) + + top_items = [d for d in os.listdir(extract_dir) if not d.startswith(".")] + pkg_root = extract_dir + if len(top_items) == 1 and os.path.isdir(os.path.join(extract_dir, top_items[0])): + pkg_root = os.path.join(extract_dir, top_items[0]) + + discovered = _scan_skills_in_repo(pkg_root) or _scan_skills_in_dir(pkg_root) + + if discovered and len(discovered) > 1: + _batch_install_skills(discovered, name, skills_dir, "url", result) + return + + if discovered and len(discovered) == 1: + sname, sdir = discovered[0] + safe_name = re.sub(r'[^a-zA-Z0-9_\\-]', '-', sname)[:64] + if not _SAFE_NAME_RE.match(safe_name): + safe_name = name + target = os.path.join(skills_dir, safe_name) + if os.path.exists(target): + shutil.rmtree(target) + shutil.copytree(sdir, target) + _register_installed_skill(safe_name, source="url") + result.installed.append(safe_name) + result.messages.append(f"Installed '{safe_name}' from URL.") + return + + target = os.path.join(skills_dir, name) + if os.path.exists(target): + shutil.rmtree(target) + shutil.copytree(pkg_root, target) + _register_installed_skill(name, source="url") + result.installed.append(name) + result.messages.append(f"Installed '{name}' from URL.") + + def _print_install_success(name: str, source: str): """Print a unified install success message with description and source.""" skills_dir = get_skills_dir() @@ -715,6 +796,11 @@ def _route_install(name: str, result: InstallResult): _install_url(name, result) return + # --- Zip / tar.gz archive URL --- + if name.startswith(("http://", "https://")) and re.search(r'\.(zip|tar\.gz|tgz)(\?.*)?$', name, re.IGNORECASE): + _install_archive_url(name, result) + return + # --- Full GitHub URL --- parsed = _parse_github_url(name) if parsed: diff --git a/docs/commands/general.mdx b/docs/commands/general.mdx new file mode 100644 index 00000000..8ab9fb75 --- /dev/null +++ b/docs/commands/general.mdx @@ -0,0 +1,115 @@ +--- +title: 常用命令 +description: 查看状态、管理配置和上下文等常用命令 +--- + +以下命令支持在对话中使用 `/` 前缀，也支持在终端中使用 `cow` 前缀（部分命令仅对话可用）。 + + + 在 Web 控制台中输入 `/` 会自动弹出命令提示，支持键盘上下选择和 Tab 补全。 + + +## help + +显示所有可用命令的帮助信息。 + +```text +/help +``` + +## status + +查看当前会话和服务的运行状态，包括进程信息、模型配置、会话消息数量和已加载技能数量。 + +```text +/status +``` + +输出示例： + +``` +🐮 CowAgent Status + +Process: PID 12345 | Running 2h 15m +Version: 2.0.4 +Channel: web +Model: MiniMax-M2.5 +Mode: agent + +Session: 12 messages | 8 skills loaded +``` + +## config + +查看或修改运行时配置。修改后立即生效，无需重启服务。 + +**查看所有可配置项：** + +```text +/config +``` + +**查看单个配置项：** + +```text +/config model +``` + +**修改配置项：** + +```text +/config model deepseek-chat +``` + +**支持修改的配置项：** + +| 配置项 | 说明 | 示例值 | +| --- | --- | --- | +| `model` | AI 模型名称 | `deepseek-chat` | +| `agent_max_context_tokens` | 最大上下文 tokens | `40000` | +| `agent_max_context_turns` | 最大上下文记忆轮次 | `30` | +| `agent_max_steps` | 单次任务最大决策步数 | `15` | + + + 修改 `model` 时，系统会自动匹配对应的模型调用方式。配置会写入 `config.json` 并持久保存。 + + +## context + +查看当前会话的上下文信息，包括消息数量、内容长度等统计。 + +```text +/context +``` + +**清空当前会话上下文：** + +```text +/context clear +``` + + + 清空上下文后，Agent 会"忘记"之前的对话内容，适用于切换话题或释放上下文空间。 + + +## logs + +查看最近的服务日志，默认显示最近 20 行，最多 50 行。 + +```text +/logs +``` + +**指定行数：** + +```text +/logs 50 +``` + +## version + +显示当前 CowAgent 版本号。 + +```text +/version +``` diff --git a/docs/commands/index.mdx b/docs/commands/index.mdx new file mode 100644 index 00000000..f9282607 --- /dev/null +++ b/docs/commands/index.mdx @@ -0,0 +1,86 @@ +--- +title: 命令总览 +description: CowAgent 命令系统 — 终端 CLI 和对话命令 +--- + +CowAgent 提供两种命令交互方式： + +- **终端CLI** — 在系统终端中执行 `cow <命令>`，用于服务管理、技能管理等运维操作 +- **对话命令** — 在对话中输入 `/<命令>` 或 `cow <命令>`，用于查看状态、管理技能、调整配置等 + +## 终端命令 + +通过一键安装脚本部署后，`cow` 命令会自动可用。手动安装的用户需要在项目根目录下额外执行： + +```bash +pip install -e . +``` + +安装后即可在任意位置使用 `cow` 命令： + +```bash +cow help +``` + +输出示例： + +``` +CowAgent CLI + +Usage: cow + +Service: + start Start the CowAgent service + stop Stop the CowAgent service + restart Restart the CowAgent service + update Update code and restart service + status Show service status + logs View service logs + +Skills: + skill Manage skills (list / search / install / uninstall ...) + +Others: + help Show this help message + version Show version +``` + +## 对话命令 + +在 Web 控制台或任意接入渠道的对话中，支持输入以 `/` 开头的命令： + +| 命令 | 说明 | +| --- | --- | +| `/help` | 显示命令帮助 | +| `/status` | 查看服务状态和配置 | +| `/config` | 查看或修改运行时配置 | +| `/skill` | 管理技能（安装、卸载、启用、禁用等） | +| `/context` | 查看当前会话上下文信息 | +| `/context clear` | 清空当前会话上下文 | +| `/logs` | 查看最近日志 | +| `/version` | 显示版本号 | + + + 对话命令中 `/start`、`/stop`、`/restart` 等服务管理命令会提示到终端中执行，因为它们涉及进程操作。 + + +## 命令对照表 + +以下是各命令在终端和对话中的可用性： + +| 命令 | 终端 (`cow`) | 对话 (`/`) | +| --- | :---: | :---: | +| help | ✓ | ✓ | +| version | ✓ | ✓ | +| status | ✓ | ✓ | +| logs | ✓ | ✓ | +| config | ✗ | ✓ | +| context | — | ✓ | +| skill (子命令) | ✓ | ✓ | +| start / stop / restart | ✓ | ✗ | +| update | ✓ | ✗ | +| install-browser | ✓ | ✗ | + + + `context` 在终端中仅提示到对话中使用。`config` 仅支持在对话中修改。 + diff --git a/docs/commands/process.mdx b/docs/commands/process.mdx new file mode 100644 index 00000000..e5746773 --- /dev/null +++ b/docs/commands/process.mdx @@ -0,0 +1,134 @@ +--- +title: 进程管理 +description: 使用 cow 命令管理 CowAgent 进程的启动、停止、重启、更新等操作 +--- + +进程管理命令用于控制 CowAgent 后台进程的生命周期。这些命令仅在终端中可用。 + +## start + +启动 CowAgent 服务。默认以后台进程方式运行，并自动跟踪日志输出。 + +```bash +cow start +``` + +**选项：** + +| 选项 | 说明 | +| --- | --- | +| `-f`, `--foreground` | 前台运行，不以后台守护进程方式启动 | +| `--no-logs` | 启动后不自动跟踪日志 | + +## stop + +停止正在运行的 CowAgent 服务。 + +```bash +cow stop +``` + +## restart + +重启 CowAgent 服务（先停止再启动）。 + +```bash +cow restart +``` + +**选项：** + +| 选项 | 说明 | +| --- | --- | +| `--no-logs` | 重启后不自动跟踪日志 | + +## update + +更新代码并重启服务。自动执行以下流程： + +1. 拉取最新代码（`git pull`） +2. 停止当前服务 +3. 更新 Python 依赖 +4. 重新安装 CLI +5. 启动服务 + +```bash +cow update +``` + + + 如果 `git pull` 失败（如存在本地未提交的修改），更新会中止，服务不受影响。 + + +## status + +查看 CowAgent 服务运行状态，包括进程信息、版本号、当前配置的模型和通道。 + +```bash +cow status +``` + +输出示例： + +``` +🐮 CowAgent Status + Status: ● Running (PID: 12345) + Version: 2.0.4 + Channel: web + Model: MiniMax-M2.5 + Mode: agent +``` + +## logs + +查看服务日志。 + +```bash +cow logs +``` + +**选项：** + +| 选项 | 说明 | 默认值 | +| --- | --- | --- | +| `-f`, `--follow` | 持续跟踪日志输出 | 否 | +| `-n`, `--lines` | 显示最近 N 行 | 50 | + +示例： + +```bash +# 查看最近 100 行日志 +cow logs -n 100 + +# 持续跟踪日志 +cow logs -f +``` + +## install-browser + +安装 Playwright 和 Chromium 浏览器，用于启用 [浏览器工具](/tools/browser)。 + +```bash +cow install-browser +``` + + + 仅在需要使用浏览器工具（如网页浏览、截图等）时才需要安装。 + + +## run.sh 兼容 + +如果未安装 Cow CLI，也可以使用 `run.sh` 脚本管理服务： + +| cow 命令 | run.sh 等效命令 | +| --- | --- | +| `cow start` | `./run.sh start` | +| `cow stop` | `./run.sh stop` | +| `cow restart` | `./run.sh restart` | +| `cow update` | `./run.sh update` | +| `cow status` | `./run.sh status` | +| `cow logs` | `./run.sh logs` | + + + 推荐使用 `cow` 命令，它提供更简洁的语法和更丰富的功能。通过一键安装脚本部署时 `cow` 命令会自动安装。 + diff --git a/docs/commands/skill.mdx b/docs/commands/skill.mdx new file mode 100644 index 00000000..3b4a8aee --- /dev/null +++ b/docs/commands/skill.mdx @@ -0,0 +1,218 @@ +--- +title: 技能管理 +description: 通过命令安装、卸载、启用、禁用和管理技能 +--- + +技能管理命令用于安装、查询和管理 CowAgent 的技能。在对话中使用 `/skill <子命令>`，在终端中使用 `cow skill <子命令>`。 + +## list + +列出已安装的技能及其状态。 + + +```text 对话 +/skill list +``` + +```bash 终端 +cow skill list +``` + + +输出示例： + +``` +📦 已安装的技能 (3/4) + +✅ pptx + Use this skill any time a .pptx file is involved… + 来源: cowhub + +✅ skill-creator + Create, install, or update skills… + 来源: builtin + +⏸️ image-vision (已禁用) + 图片理解和视觉分析 + 来源: builtin +``` + +**浏览技能广场**（查看 Hub 上所有可安装的技能）： + + +```text 对话 +/skill list --remote +``` + +```bash 终端 +cow skill list --remote +``` + + +**选项：** + +| 选项 | 说明 | 默认值 | +| --- | --- | --- | +| `--remote`, `-r` | 浏览 Skill Hub 远程技能列表 | 否 | +| `--page` | 远程列表分页页码 | 1 | + +## search + +在技能广场中搜索技能。 + + +```text 对话 +/skill search pptx +``` + +```bash 终端 +cow skill search pptx +``` + + +## install + +安装技能。通过统一的 `install` 命令，可一键安装来自 **Cow 技能广场、GitHub、ClawHub** 以及任意 URL（zip 压缩包、SKILL.md 链接）上的技能，无需手动下载和配置。 + +**从 Cow 技能广场安装（推荐）：** + + +```text 对话 +/skill install pptx +``` + +```bash 终端 +cow skill install pptx +``` + + +**从 GitHub 安装：** + + +```text 对话 +# 安装仓库中的所有技能（自动扫描包含 SKILL.md 的子目录） +/skill install larksuite/cli + +# 指定子目录，只安装单个技能 +/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im + +# 使用 # 指定子目录 +/skill install larksuite/cli#skills/lark-minutes +``` + +```bash 终端 +# 安装仓库中的所有技能（自动扫描包含 SKILL.md 的子目录） +cow skill install larksuite/cli + +# 指定子目录，只安装单个技能 +cow skill install https://github.com/larksuite/cli/tree/main/skills/lark-im + +# 使用 # 指定子目录 +cow skill install larksuite/cli#skills/lark-minutes +``` + + +支持完整的 GitHub URL 和 `owner/repo` 简写。对于 mono-repo（一个仓库中包含多个技能），不指定子目录时会自动发现并批量安装所有技能；指定子目录时只安装该目录下的技能。 + +**从 ClawHub 安装：** + + +```text 对话 +/skill install clawhub:baidu-search +``` + +```bash 终端 +cow skill install clawhub:baidu-search +``` + + +**从 URL 安装：** + + +```text 对话 +# 从 zip 压缩包安装（支持单个或批量） +/skill install https://cdn.link-ai.tech/skills/pptx.zip + +# 从 SKILL.md 链接安装 +/skill install https://example.com/path/to/SKILL.md +``` + +```bash 终端 +# 从 zip 压缩包安装（支持单个或批量） +cow skill install https://cdn.link-ai.tech/skills/pptx.zip + +# 从 SKILL.md 链接安装 +cow skill install https://example.com/path/to/SKILL.md +``` + + +支持从 zip / tar.gz 压缩包 URL 安装，解压后自动扫描包含 `SKILL.md` 的目录，支持单个或批量安装。也支持直接从 `SKILL.md` 文件链接安装，会自动解析技能名称和描述。 + +安装成功后会显示技能名称、描述和来源，例如： + +``` +✅ baidu-search + 百度搜索：使用百度搜索引擎检索信息… + 来源: clawhub +``` + +## uninstall + +卸载已安装的技能。 + + +```text 对话 +/skill uninstall pptx +``` + +```bash 终端 +cow skill uninstall pptx +``` + + + + 卸载操作会删除技能目录下的所有文件，此操作不可恢复。 + + +## enable / disable + +启用或禁用技能，禁用后技能不会被 Agent 调用。 + + +```text 对话 +/skill enable pptx +/skill disable pptx +``` + +```bash 终端 +cow skill enable pptx +cow skill disable pptx +``` + + +## info + +查看已安装技能的详细信息，包括 `SKILL.md` 内容预览。 + + +```text 对话 +/skill info pptx +``` + +```bash 终端 +cow skill info pptx +``` + + +## 技能来源 + +安装的技能会记录来源信息，可通过 `/skill list` 查看： + +| 来源标识 | 说明 | +| --- | --- | +| `builtin` | 项目内置技能 | +| `cowhub` | 从 CowAgent Skill Hub 安装 | +| `github` | 从 GitHub URL 直接安装 | +| `clawhub` | 从 ClawHub 安装 | +| `url` | 从 SKILL.md URL 安装 | +| `local` | 本地创建的技能 | diff --git a/docs/docs.json b/docs/docs.json index 9dcc9053..804dcccb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -106,14 +106,17 @@ "tools/bash", "tools/send", "tools/memory", - "tools/env-config" + "tools/env-config", + "tools/web-fetch", + "tools/scheduler" ] }, { "group": "可选工具", "pages": [ "tools/web-search", - "tools/scheduler" + "tools/vision", + "tools/browser" ] } ] @@ -125,15 +128,8 @@ "group": "技能系统", "pages": [ "skills/index", - "skills/skill-creator" - ] - }, - { - "group": "内置技能", - "pages": [ - "skills/image-vision", - "skills/linkai-agent", - "skills/web-fetch" + "skills/install", + "skills/create" ] } ] @@ -144,7 +140,8 @@ { "group": "记忆系统", "pages": [ - "memory" + "memory/index", + "memory/context" ] } ] @@ -167,6 +164,20 @@ } ] }, + { + "tab": "命令", + "groups": [ + { + "group": "命令系统", + "pages": [ + "commands/index", + "commands/process", + "commands/skill", + "commands/general" + ] + } + ] + }, { "tab": "版本", "groups": [ @@ -254,14 +265,17 @@ "en/tools/bash", "en/tools/send", "en/tools/memory", - "en/tools/env-config" + "en/tools/env-config", + "en/tools/web-fetch", + "en/tools/scheduler" ] }, { "group": "Optional Tools", "pages": [ "en/tools/web-search", - "en/tools/scheduler" + "en/tools/vision", + "en/tools/browser" ] } ] @@ -273,16 +287,9 @@ "group": "Skills System", "pages": [ "en/skills/index", + "en/skills/install", "en/skills/skill-creator" ] - }, - { - "group": "Built-in Skills", - "pages": [ - "en/skills/image-vision", - "en/skills/linkai-agent", - "en/skills/web-fetch" - ] } ] }, @@ -292,7 +299,8 @@ { "group": "Memory System", "pages": [ - "en/memory" + "en/memory/index", + "en/memory/context" ] } ] @@ -315,6 +323,20 @@ } ] }, + { + "tab": "Commands", + "groups": [ + { + "group": "Command System", + "pages": [ + "en/commands/index", + "en/commands/process", + "en/commands/skill", + "en/commands/chat" + ] + } + ] + }, { "tab": "Releases", "groups": [ @@ -403,14 +425,16 @@ "ja/tools/send", "ja/tools/memory", "ja/tools/env-config", - "ja/tools/browser" + "ja/tools/web-fetch", + "ja/tools/scheduler" ] }, { "group": "オプションツール", "pages": [ "ja/tools/web-search", - "ja/tools/scheduler" + "ja/tools/vision", + "ja/tools/browser" ] } ] @@ -422,15 +446,8 @@ "group": "スキルシステム", "pages": [ "ja/skills/index", - "ja/skills/skill-creator" - ] - }, - { - "group": "内蔵スキル", - "pages": [ - "ja/skills/image-vision", - "ja/skills/linkai-agent", - "ja/skills/web-fetch" + "ja/skills/install", + "ja/skills/create" ] } ] @@ -441,7 +458,8 @@ { "group": "メモリシステム", "pages": [ - "ja/memory" + "ja/memory/index", + "ja/memory/context" ] } ] @@ -464,6 +482,20 @@ } ] }, + { + "tab": "コマンド", + "groups": [ + { + "group": "コマンドシステム", + "pages": [ + "ja/commands/index", + "ja/commands/process", + "ja/commands/skill", + "ja/commands/general" + ] + } + ] + }, { "tab": "リリース", "groups": [ diff --git a/docs/en/README.md b/docs/en/README.md index 06fda767..d6bff782 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -20,13 +20,14 @@ > CowAgent is both an out-of-the-box AI super assistant and a highly extensible Agent framework. You can extend it with new model interfaces, channels, built-in tools, and the Skills system to flexibly implement various customization needs. -- ✅ **Autonomous Task Planning**: Understands complex tasks and autonomously plans execution, continuously thinking and invoking tools until goals are achieved. Supports accessing files, terminal, browser, schedulers, and other system resources via tools. +- ✅ **Autonomous Task Planning**: Understands complex tasks and autonomously plans execution, continuously thinking and invoking tools until goals are achieved. - ✅ **Long-term Memory**: Automatically persists conversation memory to local files and databases, including core memory and daily memory, with keyword and vector retrieval support. -- ✅ **Skills System**: Implements a Skills creation and execution engine with multiple built-in skills, and supports custom Skills development through natural language conversation. +- ✅ **Skills System**: Implements a Skills creation and execution engine, supports installing skills from [Skill Hub](https://skills.cowagent.ai), GitHub, etc., or creating custom Skills through conversation. +- ✅ **Tool System**: Built-in tools for file I/O, terminal execution, browser automation, scheduled tasks, messaging, and more — autonomously invoked by the Agent. +- ✅ **CLI System**: Provides terminal commands and in-chat commands for process management, skill installation, configuration, and more. - ✅ **Multimodal Messages**: Supports parsing, processing, generating, and sending text, images, voice, files, and other message types. - ✅ **Multiple Model Support**: Supports OpenAI, Claude, Gemini, DeepSeek, MiniMax, GLM, Qwen, Kimi, Doubao, and other mainstream model providers. - ✅ **Multi-platform Deployment**: Runs on local computers or servers, integrable into WeChat, Web, Feishu, DingTalk, WeChat Official Account, and WeCom applications. -- ✅ **Knowledge Base**: Integrates enterprise knowledge base capabilities via the [LinkAI](https://link-ai.tech) platform. ## Disclaimer @@ -66,7 +67,7 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh) After running, the Web service starts by default. Access `http://localhost:9899/chat` to chat. -Script usage: [One-click Install](https://docs.cowagent.ai/en/guide/quick-start) +Script usage: [One-click Install](https://docs.cowagent.ai/en/guide/quick-start). After installation, you can also use `cow start`, `cow stop`, and other [CLI commands](https://docs.cowagent.ai/en/commands/index) to manage the service. ### Manual Installation @@ -84,7 +85,25 @@ pip3 install -r requirements.txt pip3 install -r requirements-optional.txt # optional but recommended ``` -**3. Configure** +**3. Install Cow CLI (recommended)** + +```bash +pip3 install -e . +``` + +After installation, use `cow` commands to manage the service (start, stop, update, etc.) and skills. See [Command Docs](https://docs.cowagent.ai/en/commands/index). + +**4. Install browser (optional)** + +If you need the Agent to operate a browser (visit web pages, fill forms, etc.): + +```bash +cow install-browser +``` + +This auto-installs `playwright` and Chromium. See [Browser Tool Docs](https://docs.cowagent.ai/en/tools/browser). + +**5. Configure** ```bash cp config-template.json config.json @@ -92,13 +111,25 @@ cp config-template.json config.json Fill in your model API key and channel type in `config.json`. See the [configuration docs](https://docs.cowagent.ai/en/guide/manual-install) for details. -**4. Run** +**6. Run** ```bash -python3 app.py +cow start # recommended, requires Cow CLI +python3 app.py # or run directly ``` -For server background run: +For server deployment, use `cow` commands to manage the service: + +```bash +cow start # start in background +cow stop # stop service +cow restart # restart service +cow status # check running status +cow logs # view logs +cow update # pull latest code and restart +``` + +Or use the traditional way: ```bash nohup python3 app.py & tail -f nohup.out @@ -195,7 +226,7 @@ FAQs: ## 🛠️ Contributing -Welcome to add new channels, referring to the [Feishu channel](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py) as an example. Also welcome to contribute new Skills, referring to the [Skill Creator docs](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md). +Welcome to add new channels, referring to the [Feishu channel](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py) as an example. Also welcome to contribute new Skills, see the [Skill Creation docs](https://docs.cowagent.ai/en/skills/create). ## ✉ Contact diff --git a/docs/en/commands/general.mdx b/docs/en/commands/general.mdx new file mode 100644 index 00000000..186f51a9 --- /dev/null +++ b/docs/en/commands/general.mdx @@ -0,0 +1,101 @@ +--- +title: General Commands +description: View status, manage config, and control context with commonly used commands +--- + +The following commands can be used in chat with the `/` prefix or in the terminal with the `cow` prefix (some are chat-only). + + + In the Web console, typing `/` brings up an autocomplete menu with keyboard navigation and Tab completion. + + +## help + +Show help information for all available commands. + +```text +/help +``` + +## status + +View current session and service status, including process info, model configuration, message count, and loaded skills. + +```text +/status +``` + +## config + +View or modify runtime configuration. Changes take effect immediately without restarting. + +**View all configurable items:** + +```text +/config +``` + +**View a single item:** + +```text +/config model +``` + +**Modify a config item:** + +```text +/config model deepseek-chat +``` + +**Configurable items:** + +| Item | Description | Example | +| --- | --- | --- | +| `model` | AI model name | `deepseek-chat` | +| `agent_max_context_tokens` | Max context tokens | `40000` | +| `agent_max_context_turns` | Max context memory turns | `30` | +| `agent_max_steps` | Max decision steps per task | `15` | + + + When changing `model`, the system automatically matches the corresponding model API. Configuration is persisted to `config.json`. + + +## context + +View current session context statistics, including message count and content length. + +```text +/context +``` + +**Clear current session context:** + +```text +/context clear +``` + + + Clearing context makes the Agent "forget" previous conversation, useful for switching topics or freeing context space. + + +## logs + +View recent service logs. Shows the last 20 lines by default, up to 50. + +```text +/logs +``` + +**Specify line count:** + +```text +/logs 50 +``` + +## version + +Show the current CowAgent version. + +```text +/version +``` diff --git a/docs/en/commands/index.mdx b/docs/en/commands/index.mdx new file mode 100644 index 00000000..4d7c91a5 --- /dev/null +++ b/docs/en/commands/index.mdx @@ -0,0 +1,84 @@ +--- +title: Commands Overview +description: CowAgent command system — Terminal CLI and chat commands +--- + +CowAgent provides two ways to interact via commands: + +- **Terminal CLI** — Run `cow ` in your system terminal for service management, skill management, and other operations +- **Chat Commands** — Type `/` or `cow ` in any conversation to check status, manage skills, adjust configuration, etc. + +## Cow CLI + +After deploying with the one-click install script, the `cow` command is automatically available. For manual installations, run: + +```bash +pip install -e . +``` + +Then use the `cow` command from anywhere: + +```bash +cow help +``` + +Example output: + +``` +🐮 CowAgent CLI + +Usage: cow + +Service: + start Start the CowAgent service + stop Stop the CowAgent service + restart Restart the CowAgent service + update Update code and restart service + status Show service status + logs View service logs + +Skills: + skill Manage skills (list / search / install / uninstall ...) + +Others: + help Show this help message + version Show version +``` + +## Chat Commands + +In the Web console or any connected channel, type `/` to see command suggestions. Supported commands: + +| Command | Description | +| --- | --- | +| `/help` | Show command help | +| `/status` | View service status and configuration | +| `/config` | View or modify runtime configuration | +| `/skill` | Manage skills (install, uninstall, enable, disable, etc.) | +| `/context` | View current session context info | +| `/context clear` | Clear current session context | +| `/logs` | View recent logs | +| `/version` | Show version number | + + + Service management commands like `/start`, `/stop`, `/restart` will prompt you to use them in the terminal instead, as they involve process operations. + + +## Command Availability + +| Command | Terminal (`cow`) | Chat (`/`) | +| --- | :---: | :---: | +| help | ✓ | ✓ | +| version | ✓ | ✓ | +| status | ✓ | ✓ | +| logs | ✓ | ✓ | +| config | ✗ | ✓ | +| context | — | ✓ | +| skill (subcommands) | ✓ | ✓ | +| start / stop / restart | ✓ | ✗ | +| update | ✓ | ✗ | +| install-browser | ✓ | ✗ | + + + `context` only shows a hint in the terminal to use it in chat. `config` is only available in chat. + diff --git a/docs/en/commands/process.mdx b/docs/en/commands/process.mdx new file mode 100644 index 00000000..452df03a --- /dev/null +++ b/docs/en/commands/process.mdx @@ -0,0 +1,123 @@ +--- +title: Process Management +description: Manage CowAgent process lifecycle with cow commands +--- + +Process management commands control the CowAgent background process. These commands are only available in the terminal. + +## start + +Start the CowAgent service. Runs as a background daemon by default and automatically tails logs. + +```bash +cow start +``` + +**Options:** + +| Option | Description | +| --- | --- | +| `-f`, `--foreground` | Run in foreground, not as a background daemon | +| `--no-logs` | Don't tail logs after starting | + +## stop + +Stop the running CowAgent service. + +```bash +cow stop +``` + +## restart + +Restart the CowAgent service (stop then start). + +```bash +cow restart +``` + +**Options:** + +| Option | Description | +| --- | --- | +| `--no-logs` | Don't tail logs after restart | + +## update + +Update code and restart the service. Automatically performs: + +1. Pull latest code (`git pull`) +2. Stop current service +3. Update Python dependencies +4. Reinstall CLI +5. Start service + +```bash +cow update +``` + + + If `git pull` fails (e.g., uncommitted local changes), the update aborts and the service remains unaffected. + + +## status + +Check CowAgent service status, including process info, version, and current model/channel configuration. + +```bash +cow status +``` + +## logs + +View service logs. + +```bash +cow logs +``` + +**Options:** + +| Option | Description | Default | +| --- | --- | --- | +| `-f`, `--follow` | Continuously tail log output | No | +| `-n`, `--lines` | Show last N lines | 50 | + +Examples: + +```bash +# View last 100 lines +cow logs -n 100 + +# Continuously tail logs +cow logs -f +``` + +## install-browser + +Install Playwright and Chromium browser for the [browser tool](/en/tools/browser). + +```bash +cow install-browser +``` + + + Only needed when using browser tools (web browsing, screenshots, etc.). + + +## run.sh Compatibility + +If Cow CLI is not installed, you can use `run.sh` to manage the service: + +| cow command | run.sh equivalent | +| --- | --- | +| `cow start` | `./run.sh start` | +| `cow stop` | `./run.sh stop` | +| `cow restart` | `./run.sh restart` | +| `cow update` | `./run.sh update` | +| `cow status` | `./run.sh status` | +| `cow logs` | `./run.sh logs` | + + + The `cow` command is recommended — it provides cleaner syntax and richer features. It is automatically installed via the one-click install script. + diff --git a/docs/en/commands/skill.mdx b/docs/en/commands/skill.mdx new file mode 100644 index 00000000..d712b4d2 --- /dev/null +++ b/docs/en/commands/skill.mdx @@ -0,0 +1,192 @@ +--- +title: Skill Management +description: Install, uninstall, enable, disable, and manage skills via commands +--- + +Skill management commands are used to install, query, and manage CowAgent skills. Use `/skill ` in chat or `cow skill ` in the terminal. + +## list + +List installed skills and their status. + + +```text Chat +/skill list +``` + +```bash Terminal +cow skill list +``` + + +**Browse the Skill Hub** (view all available skills): + + +```text Chat +/skill list --remote +``` + +```bash Terminal +cow skill list --remote +``` + + +**Options:** + +| Option | Description | Default | +| --- | --- | --- | +| `--remote`, `-r` | Browse Skill Hub remote skill list | No | +| `--page` | Page number for remote listing | 1 | + +## search + +Search for skills on the Skill Hub. + + +```text Chat +/skill search pptx +``` + +```bash Terminal +cow skill search pptx +``` + + +## install + +Install skills with a single `install` command from Cow Skill Hub, GitHub, ClawHub, or any URL (zip archives, SKILL.md links) — no manual download or configuration required. + +**From Skill Hub (recommended):** + + +```text Chat +/skill install pptx +``` + +```bash Terminal +cow skill install pptx +``` + + +**From GitHub:** + + +```text Chat +# Install all skills in a repo (auto-discovers subdirectories with SKILL.md) +/skill install larksuite/cli + +# Specify a subdirectory to install a single skill +/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im + +# Use # to specify a subdirectory +/skill install larksuite/cli#skills/lark-minutes +``` + +```bash Terminal +# Install all skills in a repo (auto-discovers subdirectories with SKILL.md) +cow skill install larksuite/cli + +# Specify a subdirectory to install a single skill +cow skill install https://github.com/larksuite/cli/tree/main/skills/lark-im + +# Use # to specify a subdirectory +cow skill install larksuite/cli#skills/lark-minutes +``` + + +Supports full GitHub URLs and `owner/repo` shorthand. For mono-repos (multiple skills in one repository), omitting the subdirectory auto-discovers and batch-installs all skills; specifying a subdirectory installs only that skill. + +**From ClawHub:** + + +```text Chat +/skill install clawhub:baidu-search +``` + +```bash Terminal +cow skill install clawhub:baidu-search +``` + + +**From URL:** + + +```text Chat +# Install from a zip archive (single or batch) +/skill install https://cdn.link-ai.tech/skills/pptx.zip + +# Install from a SKILL.md link +/skill install https://example.com/path/to/SKILL.md +``` + +```bash Terminal +# Install from a zip archive (single or batch) +cow skill install https://cdn.link-ai.tech/skills/pptx.zip + +# Install from a SKILL.md link +cow skill install https://example.com/path/to/SKILL.md +``` + + +Supports installing from zip / tar.gz archive URLs — automatically extracts and discovers directories containing `SKILL.md`, with support for single or batch install. Also supports installing directly from a `SKILL.md` file URL, automatically parsing the skill name and description. + +## uninstall + +Uninstall an installed skill. + + +```text Chat +/skill uninstall pptx +``` + +```bash Terminal +cow skill uninstall pptx +``` + + + + Uninstalling deletes all files in the skill directory. This action cannot be undone. + + +## enable / disable + +Enable or disable a skill. Disabled skills will not be invoked by the Agent. + + +```text Chat +/skill enable pptx +/skill disable pptx +``` + +```bash Terminal +cow skill enable pptx +cow skill disable pptx +``` + + +## info + +View details of an installed skill, including a preview of its `SKILL.md`. + + +```text Chat +/skill info pptx +``` + +```bash Terminal +cow skill info pptx +``` + + +## Skill Sources + +Installed skills track their origin, viewable via `/skill list`: + +| Source | Description | +| --- | --- | +| `builtin` | Built-in project skills | +| `cowhub` | Installed from CowAgent Skill Hub | +| `github` | Installed directly from a GitHub URL | +| `clawhub` | Installed from ClawHub | +| `url` | Installed from a SKILL.md URL | +| `local` | Locally created skills | diff --git a/docs/en/guide/manual-install.mdx b/docs/en/guide/manual-install.mdx index 5550f815..ac36b265 100644 --- a/docs/en/guide/manual-install.mdx +++ b/docs/en/guide/manual-install.mdx @@ -30,7 +30,25 @@ Optional dependencies (recommended): pip3 install -r requirements-optional.txt ``` -### 3. Configure +### 3. Install Cow CLI + +Install the command-line tool for managing services and skills: + +```bash +pip3 install -e . +``` + +Then use the `cow` command: + +```bash +cow help +``` + + + This step is recommended. After installation you can use `cow start`, `cow stop`, `cow update` to manage the service, and `cow skill` to manage skills. Without the CLI, you can use `./run.sh` or `python3 app.py` to run. + + +### 4. Configure Copy the config template and edit: @@ -40,22 +58,32 @@ cp config-template.json config.json Fill in model API keys, channel type, and other settings in `config.json`. See the [model docs](/en/models/index) for details. -### 4. Run +### 5. Run -**Local run:** +**Using Cow CLI (recommended):** + +```bash +cow start +``` + +**Or run locally in foreground:** ```bash python3 app.py ``` -By default, the Web service starts. Access `http://localhost:9899/chat` to chat. +By default, the Web console starts. Access `http://localhost:9899` to chat. -**Background run on server:** +**Background run on server (without CLI):** ```bash nohup python3 app.py & tail -f nohup.out ``` + + If deploying on a server, open port `9899` in your firewall or security group to access the Web console. It's recommended to restrict access to specific IPs for security. + + ## Docker Deployment Docker deployment does not require cloning source code or installing dependencies. For Agent mode, source deployment is recommended for broader system access. @@ -84,6 +112,10 @@ sudo docker compose up -d sudo docker logs -f chatgpt-on-wechat ``` + + If deploying on a server, open port `9899` in your firewall or security group to access the Web console. It's recommended to restrict access to specific IPs for security. + + ## Core Configuration ```json diff --git a/docs/en/guide/quick-start.mdx b/docs/en/guide/quick-start.mdx index c9f3551e..bf788ee6 100644 --- a/docs/en/guide/quick-start.mdx +++ b/docs/en/guide/quick-start.mdx @@ -18,22 +18,27 @@ The script automatically performs these steps: 1. Check Python environment (requires Python 3.7+) 2. Install required tools (git, curl, etc.) 3. Clone project to `~/chatgpt-on-wechat` -4. Install Python dependencies +4. Install Python dependencies and Cow CLI 5. Guided configuration for AI model and channel 6. Start service -By default, the Web service starts after installation. Access `http://localhost:9899/chat` to begin chatting. +By default, the Web console starts after installation. Access `http://localhost:9899` to begin chatting. ## Management Commands -After installation, use these commands to manage the service: +After installation, use the `cow` command to manage the service: | Command | Description | | --- | --- | -| `./run.sh start` | Start service | -| `./run.sh stop` | Stop service | -| `./run.sh restart` | Restart service | -| `./run.sh status` | Check run status | -| `./run.sh logs` | View real-time logs | -| `./run.sh config` | Reconfigure | -| `./run.sh update` | Update project code | +| `cow start` | Start service | +| `cow stop` | Stop service | +| `cow restart` | Restart service | +| `cow status` | Check run status | +| `cow logs` | View real-time logs | +| `cow update` | Update code and restart | + +See the [Commands documentation](/en/commands/index) for more details. + + + If the `cow` command is not available, you can use `./run.sh ` as a fallback (e.g., `./run.sh start`, `./run.sh stop`). Both are functionally equivalent. + diff --git a/docs/en/intro/index.mdx b/docs/en/intro/index.mdx index 7cec9002..bc0613a3 100644 --- a/docs/en/intro/index.mdx +++ b/docs/en/intro/index.mdx @@ -28,6 +28,12 @@ CowAgent can proactively think and plan tasks, operate computers and external re Supports parsing, processing, generating, and sending text, images, voice, files, and other message types. + + Built-in tools for file I/O, terminal execution, browser automation, scheduled tasks, messaging, and more. The Agent autonomously invokes tools to accomplish complex tasks. + + + Provides terminal CLI and in-chat commands for process management, skill installation, configuration, context inspection, and other common operations. + Supports mainstream model providers including OpenAI, Claude, Gemini, DeepSeek, MiniMax, GLM, Qwen, Kimi, Doubao, and more. diff --git a/docs/en/memory/context.mdx b/docs/en/memory/context.mdx new file mode 100644 index 00000000..567d5768 --- /dev/null +++ b/docs/en/memory/context.mdx @@ -0,0 +1,80 @@ +--- +title: Short-term Memory +description: Conversation context — message management, compression strategies, and context operations +--- + +Conversation context is the Agent's short-term memory, containing all messages in the current session (user input, Agent replies, tool calls and results). Proper context management is critical for the Agent's reasoning quality and cost control. + +## Context Structure + +Each conversation turn consists of: + +``` +User message → Agent thinking → Tool call → Tool result → ... → Agent final reply +``` + +A single turn may include multiple tool calls (controlled by `agent_max_steps`). All tool calls and results are retained in context until compressed or trimmed. + +## Key Configuration + +| Parameter | Description | Default | +| --- | --- | --- | +| `agent_max_context_tokens` | Maximum context token budget | `50000` | +| `agent_max_context_turns` | Maximum conversation turns in context | `20` | +| `agent_max_steps` | Maximum decision steps per turn (tool call count) | `15` | + +Configurable via `config.json` or the `/config` chat command. + +## Compression Strategy + +When context exceeds limits, the system automatically compresses to free space. The process has multiple stages: + +### 1. Tool Result Truncation + +Before each decision loop, the system checks tool call results in historical turns. Results exceeding **20,000 characters** are truncated, keeping only the beginning and end with a truncation notice. Current turn results are not affected. + +### 2. Turn Trimming + +When conversation turns exceed `agent_max_context_turns`: + +- The **oldest half** of complete turns is trimmed (preserving tool call chain integrity) +- Trimmed messages are summarized by LLM and **written to the daily memory file** +- Remaining turns stay intact + +### 3. Token Budget Trimming + +After turn trimming, if tokens still exceed the budget: + +- **Fewer than 5 turns**: All turns undergo **text compression** — each turn keeps only the first user text and last Agent reply, removing intermediate tool call chains +- **5 or more turns**: The **first half** of turns is trimmed again, with discarded content also written to memory + +### 4. Overflow Emergency Handling + +When the model API returns a context overflow error: + +1. All current messages are summarized and written to memory +2. Aggressive trimming is applied (tool results limited to 10K chars, user text to 10K, max 5 turns) +3. If still overflowing, the entire conversation context is cleared + +## Session Persistence + +Conversation messages are persisted to a local database, automatically restored after service restart. Restore strategy: + +- Restores the most recent **`max(3, max_context_turns / 6)`** turns +- Only retains each turn's **user text and Agent final reply**, not intermediate tool call chains +- Sessions older than **30 days** are automatically cleaned up + +## Commands + +Use these commands in chat to manage context: + +| Command | Description | +| --- | --- | +| `/context` | View current context statistics (message count, role distribution, total characters) | +| `/context clear` | Clear current session context | +| `/config agent_max_context_tokens 80000` | Adjust context token budget | +| `/config agent_max_context_turns 30` | Adjust context turn limit | + + + After clearing context, the Agent "forgets" previous conversation content. Content that was already written to long-term memory can still be retrieved via memory search. + diff --git a/docs/en/memory.mdx b/docs/en/memory/index.mdx similarity index 56% rename from docs/en/memory.mdx rename to docs/en/memory/index.mdx index 67ca57ee..73d2d824 100644 --- a/docs/en/memory.mdx +++ b/docs/en/memory/index.mdx @@ -1,30 +1,39 @@ --- -title: Memory -description: CowAgent long-term memory system +title: Long-term Memory +description: CowAgent long-term memory system — file persistence, automatic writing, and hybrid retrieval --- -The memory system enables the Agent to remember important information over time, continuously accumulating experience, understanding user preferences, and truly achieving autonomous thinking and continuous growth. +Long-term memory is stored in workspace files, persisting across sessions. The Agent loads historical memory on demand via retrieval tools during conversation, and automatically writes conversation summaries to long-term memory when context is trimmed. ## Memory Types ### Core Memory (MEMORY.md) -Stored in `~/cow/MEMORY.md`, containing long-term user preferences, important decisions, key facts, and other information that doesn't fade over time. Automatically injected into the system prompt on every conversation turn as background knowledge. +Stored in `~/cow/MEMORY.md`, containing long-term user preferences, important decisions, key facts, and other information that doesn't fade over time. The Agent reads and writes this file via tools to maintain long-term knowledge. ### Daily Memory (memory/YYYY-MM-DD.md) -Stored in `~/cow/memory/` directory, named by date (e.g. `2026-03-08.md`), recording daily conversation summaries and key events. Files are only created on first write to avoid generating empty files. +Stored in `~/cow/memory/` directory, named by date (e.g., `2026-03-08.md`), recording daily conversation summaries and key events. Files are only created on first write to avoid generating empty files. -## Memory Writing +## Automatic Writing -The Agent automatically persists conversation content to daily memory through the following mechanisms: +The Agent automatically persists conversation content to long-term memory through the following mechanisms: -- **On context trimming** — When conversation turns or tokens exceed the configured limit, the oldest half of the context is trimmed in batch, and the discarded content is summarized by LLM into key information and written to the daily memory file +- **On context trimming** — When conversation turns or tokens exceed the configured limit, the oldest half of the context is trimmed, and the discarded content is summarized by LLM into key information and written to the daily memory file - **Daily scheduled summary** — A full summary is automatically triggered at 23:55 every day, ensuring memory is preserved even on low-activity days (skipped if content hasn't changed) - **On API context overflow** — When the model API returns a context overflow error, the current conversation summary is saved as an emergency measure All memory writes run asynchronously in a background thread (LLM summarization + file writing), never blocking normal conversation replies. +## Memory Retrieval + +The memory system supports hybrid retrieval modes: + +- **Keyword retrieval** — FTS5 full-text index matching with BM25 ranking +- **Vector retrieval** — Embedding-based semantic similarity search, finds relevant memory even with different wording + +The Agent automatically triggers memory retrieval during conversation as needed, incorporating relevant historical information into context. Results are ranked by a combined score (default: 0.7 vector weight + 0.3 keyword weight). Daily memory scores decay over time (30-day half-life), while core memory does not decay. + ## First Launch On first launch, the Agent will proactively ask the user for key information and save it to the workspace (default `~/cow`): @@ -40,27 +49,10 @@ On first launch, the Agent will proactively ask the user for key information and -## Memory Retrieval - -The memory system supports hybrid retrieval modes: - -- **Keyword retrieval** — Match historical memory based on keywords -- **Vector retrieval** — Semantic similarity search, finds relevant memory even with different wording - -The Agent automatically triggers memory retrieval during conversation as needed, incorporating relevant historical information into context. Core memory (`MEMORY.md`) is always injected into the system prompt, while daily memory is loaded on demand via retrieval. - ## Configuration -```json -{ - "agent_workspace": "~/cow", - "agent_max_context_tokens": 40000, - "agent_max_context_turns": 20 -} -``` - | Parameter | Description | Default | | --- | --- | --- | | `agent_workspace` | Workspace path, memory files stored under this directory | `~/cow` | -| `agent_max_context_tokens` | Max context tokens; when exceeded, half is trimmed and summarized into memory | `40000` | -| `agent_max_context_turns` | Max context turns; when exceeded, half is trimmed and summarized into memory | `20` | +| `agent_max_context_tokens` | Max context tokens; when exceeded, content is trimmed and summarized into memory | `50000` | +| `agent_max_context_turns` | Max context turns; when exceeded, content is trimmed and summarized into memory | `20` | diff --git a/docs/en/skills/create.mdx b/docs/en/skills/create.mdx new file mode 100644 index 00000000..5edd281e --- /dev/null +++ b/docs/en/skills/create.mdx @@ -0,0 +1,58 @@ +--- +title: Create Skills +description: Create custom skills through conversation +--- + +CowAgent includes a built-in Skill Creator that lets you quickly create, install, or update skills through natural language conversation. + +## Usage + +Simply describe the skill you want in a conversation, and the Agent will handle the creation: + +- Codify workflows as skills: "Create a skill from this deployment process" +- Integrate third-party APIs: "Create a skill based on this API documentation" +- Install remote skills: "Install xxx skill for me" + +## Creation Flow + +1. Tell the Agent what skill you want to create +2. Agent automatically generates `SKILL.md` description and execution scripts +3. Skill is saved to the workspace `~/cow/skills/` directory +4. Agent will automatically recognize and use the skill in future conversations + + + + + +## SKILL.md Format + +Created skills follow the standard SKILL.md format: + +```markdown +--- +name: my-skill +description: Brief description of the skill +metadata: + emoji: 🔧 + requires: + bins: ["curl"] + env: ["MY_API_KEY"] + primaryEnv: "MY_API_KEY" +--- + +# My Skill + +Detailed instructions... +``` + +| Field | Description | +| --- | --- | +| `name` | Skill name, must match directory name | +| `description` | Skill description, Agent decides whether to invoke based on this | +| `metadata.requires.bins` | Required system commands | +| `metadata.requires.env` | Required environment variables | +| `metadata.always` | Always load (default false) | + + + See the [Skill Creator documentation](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md) for details. + diff --git a/docs/en/skills/image-vision.mdx b/docs/en/skills/image-vision.mdx deleted file mode 100644 index 8cc5c37e..00000000 --- a/docs/en/skills/image-vision.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Image Vision -description: Recognize images using OpenAI vision models ---- - -Analyze image content using OpenAI's GPT-4 Vision API, understanding objects, text, colors, and other elements in images. - -## Dependencies - -| Dependency | Description | -| --- | --- | -| `OPENAI_API_KEY` | OpenAI API key | -| `curl`, `base64` | System commands (usually pre-installed) | - -Configuration: - -- Configure `OPENAI_API_KEY` via the `env_config` tool -- Or set `open_ai_api_key` in `config.json` - -## Supported Models - -- `gpt-4.1-mini` (recommended, cost-effective) -- `gpt-4.1` - -## Usage - -Once configured, send an image to the Agent to automatically trigger image recognition. - - - - diff --git a/docs/en/skills/index.mdx b/docs/en/skills/index.mdx index afbaac7a..2569f096 100644 --- a/docs/en/skills/index.mdx +++ b/docs/en/skills/index.mdx @@ -7,20 +7,17 @@ Skills provide infinite extensibility for the Agent. Each Skill consists of a de The difference between Skills and Tools: Tools are atomic operations implemented in code (e.g., file read/write, command execution), while Skills are high-level workflows based on description files that can combine multiple Tools to complete complex tasks. -## Built-in Skills +## Getting Skills -Located in the project `skills/` directory, automatically enabled based on dependency conditions: +CowAgent offers multiple ways to acquire skills: -| Skill | Description | Dependencies | -| --- | --- | --- | -| [`skill-creator`](/en/skills/skill-creator) | Create custom skills through conversation | None | -| [`openai-image-vision`](/en/skills/image-vision) | Recognize images using OpenAI vision models | `OPENAI_API_KEY` | -| [`linkai-agent`](/en/skills/linkai-agent) | Integrate LinkAI platform agents | `LINKAI_API_KEY` | -| [`web-fetch`](/en/skills/web-fetch) | Fetch web page text content | `curl` (enabled by default) | +- **Cow Skill Hub** — Browse and install community skills via `/skill list --remote` +- **GitHub** — Install directly from GitHub repositories, with batch install support +- **ClawHub** — Install ClawHub skills via `/skill install clawhub:name` +- **URL** — Install from zip archives or SKILL.md links +- **Conversational creation** — Let the Agent create skills through natural language conversation -## Custom Skills - -Created by users through conversation, stored in workspace (`~/cow/skills/`), can implement any complex business process and third-party system integration. +See [Install Skills](/en/skills/install) and [Skill Management Commands](/en/commands/skill) for details. You can also [create skills](/en/skills/create) through conversation. ## Skill Loading Priority diff --git a/docs/en/skills/install.mdx b/docs/en/skills/install.mdx new file mode 100644 index 00000000..bb3b5f33 --- /dev/null +++ b/docs/en/skills/install.mdx @@ -0,0 +1,53 @@ +--- +title: Install Skills +description: Install skills from multiple sources with a single command +--- + +CowAgent supports installing skills from **Cow Skill Hub, GitHub, ClawHub**, and any URL with a unified `install` command. Use `/skill install` in chat or `cow skill install` in the terminal. + +## From Skill Hub + +Browse the Skill Hub and install: + +```text +/skill list --remote +/skill install pptx +``` + +## From GitHub + +Supports batch install from repositories and single skill from subdirectories: + +```text +/skill install larksuite/cli +/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im +``` + +## From ClawHub + +```text +/skill install clawhub:baidu-search +``` + +## From URL + +Supports zip archives and SKILL.md file links: + +```text +/skill install https://cdn.link-ai.tech/skills/pptx.zip +/skill install https://example.com/path/to/SKILL.md +``` + +## Manage Skills + +```text +/skill list # View installed skills +/skill info pptx # View skill details +/skill enable pptx # Enable a skill +/skill disable pptx # Disable a skill +/skill uninstall pptx # Uninstall a skill +``` + + + All commands above work in the terminal by replacing `/skill` with `cow skill`. See [Skill Management Commands](/en/commands/skill) for full documentation. + diff --git a/docs/en/skills/linkai-agent.mdx b/docs/en/skills/linkai-agent.mdx deleted file mode 100644 index d0edc05a..00000000 --- a/docs/en/skills/linkai-agent.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: LinkAI Agent -description: Integrate LinkAI platform multi-agent skill ---- - -Use agents from the [LinkAI](https://link-ai.tech/) platform as Skills for multi-agent decision-making. The Agent intelligently selects based on agent names and descriptions, calling the corresponding application or workflow via `app_code`. - -## Dependencies - -| Dependency | Description | -| --- | --- | -| `LINKAI_API_KEY` | LinkAI platform API key, created in [Console](https://link-ai.tech/console/interface) | -| `curl` | System command (usually pre-installed) | - -Configuration: - -- Configure `LINKAI_API_KEY` via the `env_config` tool -- Or set `linkai_api_key` in `config.json` - -## Configure Agents - -Add available agents in `skills/linkai-agent/config.json`: - -```json -{ - "apps": [ - { - "app_code": "G7z6vKwp", - "app_name": "LinkAI Customer Support", - "app_description": "Select this assistant only when the user needs help with LinkAI platform questions" - }, - { - "app_code": "SFY5x7JR", - "app_name": "Content Creator", - "app_description": "Use this assistant only when the user needs to create images or videos" - } - ] -} -``` - -## Usage - -Once configured, the Agent will automatically select the appropriate LinkAI agent based on the user's question. - - - - diff --git a/docs/en/skills/skill-creator.mdx b/docs/en/skills/skill-creator.mdx deleted file mode 100644 index 6c5c3f73..00000000 --- a/docs/en/skills/skill-creator.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Skill Creator -description: Create custom skills through conversation ---- - -Quickly create, install, or update skills through natural language conversation. - -## Dependencies - -No extra dependencies, always available. - -## Usage - -- Codify workflows as skills: "Create a skill from this deployment process" -- Integrate third-party APIs: "Create a skill based on this API documentation" -- Install remote skills: "Install xxx skill for me" - -## Creation Flow - -1. Tell the Agent what skill you want to create -2. Agent automatically generates `SKILL.md` description and execution scripts -3. Skill is saved to the workspace `~/cow/skills/` directory -4. Agent will automatically recognize and use the skill in future conversations - - - - - - - See the [Skill Creator documentation](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md) for details. - diff --git a/docs/en/skills/web-fetch.mdx b/docs/en/skills/web-fetch.mdx deleted file mode 100644 index f52077de..00000000 --- a/docs/en/skills/web-fetch.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Web Fetch -description: Fetch web page text content ---- - -Use curl to fetch web pages and extract readable text content. A lightweight web access method without browser automation. - -## Dependencies - -| Dependency | Description | -| --- | --- | -| `curl` | System command (usually pre-installed) | - -This skill has `always: true` set, enabled by default as long as the system has the `curl` command. - -## Usage - -Automatically invoked when the Agent needs to fetch content from a URL, no extra configuration needed. - -## Comparison with browser Tool - -| Feature | web-fetch (skill) | browser (tool) | -| --- | --- | --- | -| Dependencies | curl only | browser-use + playwright | -| JS rendering | Not supported | Supported | -| Page interaction | Not supported | Supports click, type, etc. | -| Best for | Static page text | Dynamic web pages | - - - For most web content retrieval scenarios, web-fetch is sufficient. Only use the browser tool when you need JS rendering or page interaction. - diff --git a/docs/guide/manual-install.mdx b/docs/guide/manual-install.mdx index 3b233284..fcf9e69f 100644 --- a/docs/guide/manual-install.mdx +++ b/docs/guide/manual-install.mdx @@ -32,7 +32,39 @@ pip3 install -r requirements-optional.txt > 国内网络可使用镜像源加速：`pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple` -### 3. 配置 +### 3. 安装 Cow CLI + +安装命令行工具，用于管理服务和技能： + +```bash +pip3 install -e . +``` + +安装后即可使用 `cow` 命令： + +```bash +cow help +``` + + + 此步骤为推荐操作。安装后可以使用 `cow start`、`cow stop`、`cow update` 等命令管理服务，也可以使用 `cow skill` 管理技能。如果不安装 CLI，可以使用 `./run.sh` 或 `python3 app.py` 运行。 + + +### 3.1 安装浏览器工具（可选） + +如需使用浏览器工具（控制浏览器访问网页、填写表单等），运行： + +```bash +cow install-browser +``` + +该命令会自动安装 Playwright 和 Chromium 浏览器。详细说明参考 [浏览器工具文档](/tools/browser)。 + + + 浏览器工具依赖较重（~300MB），如不需要可跳过，不影响其他功能正常使用。 + + +### 4. 配置 复制配置文件模板并编辑： @@ -42,9 +74,15 @@ cp config-template.json config.json 在 `config.json` 中填写模型 API Key 和通道类型等配置，详细说明参考各 [模型文档](/models/minimax)。 -### 4. 运行 +### 5. 运行 -**本地运行：** +**使用 Cow CLI 运行（推荐）：** + +```bash +cow start +``` + +**或者本地前台运行：** ```bash python3 app.py @@ -52,7 +90,7 @@ python3 app.py 运行后默认启动 Web 控制台，访问 `http://localhost:9899` 开始对话和管理Agent。 -**服务器后台运行：** +**服务器后台运行（不使用 CLI 时）：** ```bash nohup python3 app.py & tail -f nohup.out @@ -96,28 +134,44 @@ sudo docker logs -f chatgpt-on-wechat ## 核心配置项 -```json -{ - "channel_type": "web", - "model": "MiniMax-M2.5", - "agent": true, - "agent_workspace": "~/cow", - "agent_max_context_tokens": 40000, - "agent_max_context_turns": 30, - "agent_max_steps": 15 -} -``` + + + ```json + { + "channel_type": "web", + "model": "MiniMax-M2.7", + "agent": true, + "agent_workspace": "~/cow", + "agent_max_context_tokens": 40000, + "agent_max_context_turns": 30, + "agent_max_steps": 15 + } + ``` + + + ```yaml + environment: + CHANNEL_TYPE: 'web' + MODEL: 'MiniMax-M2.7' + MINIMAX_API_KEY: 'your-api-key' + AGENT: 'True' + AGENT_MAX_CONTEXT_TOKENS: 40000 + AGENT_MAX_CONTEXT_TURNS: 30 + AGENT_MAX_STEPS: 15 + ``` + + -| 参数 | 说明 | 默认值 | -| --- | --- | --- | -| `channel_type` | 接入渠道类型 | `web` | -| `model` | 模型名称 | `MiniMax-M2.5` | -| `agent` | 是否启用 Agent 模式 | `true` | -| `agent_workspace` | Agent 工作空间路径 | `~/cow` | -| `agent_max_context_tokens` | 最大上下文 tokens | `40000` | -| `agent_max_context_turns` | 最大上下文记忆轮次 | `30` | -| `agent_max_steps` | 单次任务最大决策步数 | `15` | +| 参数 | 环境变量 | 说明 | 默认值 | +| --- | --- | --- | --- | +| `channel_type` | `CHANNEL_TYPE` | 接入渠道类型 | `web` | +| `model` | `MODEL` | 模型名称 | `MiniMax-M2.5` | +| `agent` | `AGENT` | 是否启用 Agent 模式 | `true` | +| `agent_workspace` | - | Agent 工作空间路径 | `~/cow` | +| `agent_max_context_tokens` | `AGENT_MAX_CONTEXT_TOKENS` | 最大上下文 tokens | `40000` | +| `agent_max_context_turns` | `AGENT_MAX_CONTEXT_TURNS` | 最大上下文记忆轮次 | `30` | +| `agent_max_steps` | `AGENT_MAX_STEPS` | 单次任务最大决策步数 | `15` | - 全部配置项可在项目 [`config.py`](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/config.py) 文件中查看。 + 全部配置项可在项目 [`config.py`](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/config.py) 文件中查看。Docker 部署时，配置项名称需转为大写环境变量格式。 diff --git a/docs/guide/quick-start.mdx b/docs/guide/quick-start.mdx index 428b2293..c0c6d0c0 100644 --- a/docs/guide/quick-start.mdx +++ b/docs/guide/quick-start.mdx @@ -18,7 +18,7 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh) 1. 检查 Python 环境（需要 Python 3.7+） 2. 安装必要工具（git、curl 等） 3. 克隆项目代码到 `~/chatgpt-on-wechat` -4. 安装 Python 依赖 +4. 安装 Python 依赖和 Cow CLI 5. 引导配置 AI 模型和通信渠道 6. 启动服务 @@ -26,14 +26,20 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh) ## 管理命令 -安装完成后，可使用以下命令管理服务： +安装完成后，使用 `cow` CLI 管理服务： | 命令 | 说明 | | --- | --- | -| `./run.sh start` | 启动服务 | -| `./run.sh stop` | 停止服务 | -| `./run.sh restart` | 重启服务 | -| `./run.sh status` | 查看运行状态 | -| `./run.sh logs` | 查看实时日志 | -| `./run.sh config` | 重新配置 | -| `./run.sh update` | 更新项目代码 | +| `cow start` | 启动服务 | +| `cow stop` | 停止服务 | +| `cow restart` | 重启服务 | +| `cow status` | 查看运行状态 | +| `cow logs` | 查看实时日志 | +| `cow update` | 更新代码并重启 | +| `cow install-browser` | 安装浏览器工具依赖 | + +更多命令和用法参考 [命令文档](/commands/index)。 + + + 如果 `cow` 命令不可用，也可以使用 `./run.sh <命令>` 作为替代（如 `./run.sh start`、`./run.sh stop`），二者功能等效。 + diff --git a/docs/guide/upgrade.mdx b/docs/guide/upgrade.mdx index 24f65b15..48b45005 100644 --- a/docs/guide/upgrade.mdx +++ b/docs/guide/upgrade.mdx @@ -3,20 +3,25 @@ title: 更新升级 description: CowAgent 的升级方式说明 --- -## 脚本升级（推荐） +## 命令升级（推荐） -如果使用 `run.sh` 管理服务，在项目根目录执行以下命令即可一键升级： +使用 `cow update` 一键完成代码更新和服务重启： ```bash -./run.sh update +cow update ``` 该命令会自动完成以下流程： -1. 停止当前运行的服务 -2. 拉取最新代码 -3. 重新检查依赖 -4. 启动服务 +1. 拉取最新代码（`git pull`） +2. 停止当前服务 +3. 更新 Python 依赖 +4. 重新安装 CLI +5. 启动服务 + + + 如果未安装 Cow CLI，也可以使用 `./run.sh update` 完成相同操作。 + ## 手动升级 @@ -25,15 +30,19 @@ description: CowAgent 的升级方式说明 ```bash git pull pip3 install -r requirements.txt +pip3 install -e . ``` 更新完成后重启服务： ```bash -# 如果使用 run.sh 管理 +# 使用 Cow CLI +cow restart + +# 或使用 run.sh ./run.sh restart -# 如果使用 nohup 直接运行 +# 或使用 nohup 直接运行 kill $(ps -ef | grep app.py | grep -v grep | awk '{print $2}') nohup python3 app.py & tail -f nohup.out ``` diff --git a/docs/intro/index.mdx b/docs/intro/index.mdx index fdeb0a08..4cb3ef62 100644 --- a/docs/intro/index.mdx +++ b/docs/intro/index.mdx @@ -33,10 +33,16 @@ CowAgent 支持灵活切换多种模型，能处理文本、语音、图片、 支持对文本、图片、语音、文件等多类型消息进行解析、处理、生成、发送等操作。 - + + 内置文件读写、终端执行、浏览器操作、定时任务、消息发送等工具，Agent 可自主调用工具完成复杂任务。 + + + 提供终端 CLI 和对话中的命令，支持进程管理、技能安装、配置修改、上下文查看等常用操作。 + + 支持 OpenAI, Claude, Gemini, DeepSeek, MiniMax, GLM, Qwen, Kimi, Doubao 等国内外主流模型厂商。 - + 支持运行在本地计算机或服务器，可集成到微信、网页、飞书、钉钉、微信公众号、企业微信应用中使用。 diff --git a/docs/ja/README.md b/docs/ja/README.md index 6c444f9d..f420b32e 100644 --- a/docs/ja/README.md +++ b/docs/ja/README.md @@ -20,13 +20,14 @@ > CowAgentは、すぐに使えるAIスーパーアシスタントであると同時に、高い拡張性を持つAgentフレームワークでもあります。新しいモデルインターフェース、チャネル、組み込みツール、Skillシステムを拡張することで、さまざまなカスタマイズニーズに柔軟に対応できます。 -- ✅ **自律的タスク計画**: 複雑なタスクを理解し、自律的に実行計画を立て、目標達成までツールを呼び出しながら継続的に思考します。ツールを通じてファイル、ターミナル、ブラウザ、スケジューラなどのシステムリソースにアクセスできます。 +- ✅ **自律的タスク計画**: 複雑なタスクを理解し、自律的に実行計画を立て、目標達成までツールを呼び出しながら継続的に思考します。 - ✅ **長期記憶**: 会話の記憶をローカルファイルやデータベースに自動的に永続化します。コアメモリとデイリーメモリを含み、キーワード検索やベクトル検索に対応しています。 -- ✅ **Skillシステム**: Skillの作成・実行エンジンを実装しており、複数の組み込みSkillを備え、自然言語での会話を通じたカスタムSkillの開発もサポートしています。 +- ✅ **Skillシステム**: Skillの作成・実行エンジンを実装。[Skill Hub](https://skills.cowagent.ai)、GitHubなどからSkillをインストールでき、会話を通じたカスタムSkill作成もサポートしています。 +- ✅ **ツールシステム**: ファイル読み書き、ターミナル実行、ブラウザ操作、スケジュールタスク、メッセージ送信などの組み込みツールを提供。Agentが自律的に呼び出して複雑なタスクを完了します。 +- ✅ **CLIシステム**: ターミナルコマンドとチャットコマンドを提供し、プロセス管理、Skillインストール、設定変更などの操作をサポートします。 - ✅ **マルチモーダルメッセージ**: テキスト、画像、音声、ファイルなど、さまざまなメッセージタイプの解析・処理・生成・送信に対応しています。 - ✅ **複数モデル対応**: OpenAI、Claude、Gemini、DeepSeek、MiniMax、GLM、Qwen、Kimi、Doubaoなど、主要なモデルプロバイダーに対応しています。 - ✅ **マルチプラットフォームデプロイ**: ローカルPCやサーバー上で実行でき、WeChat、Web、Feishu、DingTalk、WeChat公式アカウント、WeComアプリケーションに統合可能です。 -- ✅ **ナレッジベース**: [LinkAI](https://link-ai.tech) プラットフォームを通じて、企業向けナレッジベース機能を統合できます。 ## 免責事項 @@ -66,7 +67,7 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh) 実行後、デフォルトでWebサービスが起動します。`http://localhost:9899/chat` にアクセスしてチャットを開始できます。 -スクリプトの使い方: [ワンクリックインストール](https://docs.cowagent.ai/en/guide/quick-start) +スクリプトの使い方: [ワンクリックインストール](https://docs.cowagent.ai/ja/guide/quick-start)。インストール後は `cow start`、`cow stop` などの [CLI コマンド](https://docs.cowagent.ai/ja/commands/index)でサービスを管理できます。 ### 手動インストール @@ -84,7 +85,25 @@ pip3 install -r requirements.txt pip3 install -r requirements-optional.txt # 任意ですが推奨 ``` -**3. 設定** +**3. Cow CLI のインストール（推奨）** + +```bash +pip3 install -e . +``` + +インストール後、`cow` コマンドでサービス管理（起動、停止、更新など）やSkill管理ができます。[コマンドドキュメント](https://docs.cowagent.ai/ja/commands/index)を参照してください。 + +**4. ブラウザのインストール（任意）** + +Agentにブラウザ操作（Webページへのアクセス、フォーム入力など）が必要な場合： + +```bash +cow install-browser +``` + +`playwright` と Chromium を自動インストールします。[ブラウザツールドキュメント](https://docs.cowagent.ai/ja/tools/browser)を参照してください。 + +**5. 設定** ```bash cp config-template.json config.json @@ -92,13 +111,25 @@ cp config-template.json config.json `config.json` にモデルのAPIキーとチャネルタイプを記入してください。詳細は[設定ドキュメント](https://docs.cowagent.ai/en/guide/manual-install)を参照してください。 -**4. 実行** +**6. 実行** ```bash -python3 app.py +cow start # 推奨、Cow CLI が必要 +python3 app.py # または直接実行 ``` -サーバーでバックグラウンド実行する場合： +サーバーデプロイでは、`cow` コマンドでサービスを管理できます： + +```bash +cow start # バックグラウンドで起動 +cow stop # サービス停止 +cow restart # サービス再起動 +cow status # 実行状態を確認 +cow logs # ログを表示 +cow update # 最新コードを取得して再起動 +``` + +または従来の方法で実行： ```bash nohup python3 app.py & tail -f nohup.out @@ -195,7 +226,7 @@ FAQ: ## 🛠️ コントリビューション -新しいチャネルの追加を歓迎します。[Feishuチャネル](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py)を参考にしてください。また、新しいSkillのコントリビューションも歓迎します。[Skill Creatorドキュメント](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md)を参照してください。 +新しいチャネルの追加を歓迎します。[Feishuチャネル](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/channel/feishu/feishu_channel.py)を参考にしてください。また、新しいSkillのコントリビューションも歓迎します。[Skill作成ドキュメント](https://docs.cowagent.ai/ja/skills/create)を参照してください。 ## ✉ お問い合わせ diff --git a/docs/ja/commands/general.mdx b/docs/ja/commands/general.mdx new file mode 100644 index 00000000..ede186c5 --- /dev/null +++ b/docs/ja/commands/general.mdx @@ -0,0 +1,101 @@ +--- +title: 汎用コマンド +description: ステータスの確認、設定管理、コンテキスト制御などのよく使うコマンド +--- + +以下のコマンドはチャットで `/` プレフィックス、ターミナルで `cow` プレフィックスで使用できます（一部はチャット専用）。 + + + Web コンソールでは `/` を入力すると自動補完メニューが表示され、キーボードのナビゲーションと Tab 補完に対応しています。 + + +## help + +使用可能なすべてのコマンドのヘルプ情報を表示します。 + +```text +/help +``` + +## status + +現在のセッションとサービスの実行状態を表示します。プロセス情報、モデル設定、メッセージ数、読み込み済みスキル数を含みます。 + +```text +/status +``` + +## config + +実行時設定の表示または変更を行います。変更は即座に反映され、再起動は不要です。 + +**すべての設定項目を表示：** + +```text +/config +``` + +**単一の設定項目を表示：** + +```text +/config model +``` + +**設定項目を変更：** + +```text +/config model deepseek-chat +``` + +**変更可能な設定項目：** + +| 項目 | 説明 | 例 | +| --- | --- | --- | +| `model` | AI モデル名 | `deepseek-chat` | +| `agent_max_context_tokens` | 最大コンテキストトークン数 | `40000` | +| `agent_max_context_turns` | 最大コンテキスト記憶ターン数 | `30` | +| `agent_max_steps` | タスクごとの最大判断ステップ数 | `15` | + + + `model` を変更すると、システムが対応するモデル API を自動的にマッチングします。設定は `config.json` に永続的に保存されます。 + + +## context + +現在のセッションのコンテキスト統計情報を表示します。メッセージ数やコンテンツの長さを含みます。 + +```text +/context +``` + +**現在のセッションのコンテキストをクリア：** + +```text +/context clear +``` + + + コンテキストをクリアすると、Agent は以前の会話内容を「忘れます」。話題の切り替えやコンテキストスペースの解放に便利です。 + + +## logs + +最近のサービスログを表示します。デフォルトでは最近の 20 行を表示し、最大 50 行です。 + +```text +/logs +``` + +**行数を指定：** + +```text +/logs 50 +``` + +## version + +現在の CowAgent のバージョンを表示します。 + +```text +/version +``` diff --git a/docs/ja/commands/index.mdx b/docs/ja/commands/index.mdx new file mode 100644 index 00000000..a9f9d2b1 --- /dev/null +++ b/docs/ja/commands/index.mdx @@ -0,0 +1,84 @@ +--- +title: コマンド概要 +description: CowAgent コマンドシステム — ターミナル CLI とチャットコマンド +--- + +CowAgent は2つのコマンド操作方法を提供しています： + +- **ターミナル CLI** — システムターミナルで `cow <コマンド>` を実行し、サービス管理やスキル管理を行います +- **チャットコマンド** — 会話で `/<コマンド>` または `cow <コマンド>` を入力し、ステータス確認、スキル管理、設定変更を行います + +## Cow CLI + +ワンクリックインストールスクリプトでデプロイすると、`cow` コマンドが自動的に利用可能になります。手動インストールの場合は以下を実行してください： + +```bash +pip install -e . +``` + +インストール後、任意の場所で `cow` コマンドを使用できます： + +```bash +cow help +``` + +出力例： + +``` +🐮 CowAgent CLI + +Usage: cow + +Service: + start Start the CowAgent service + stop Stop the CowAgent service + restart Restart the CowAgent service + update Update code and restart service + status Show service status + logs View service logs + +Skills: + skill Manage skills (list / search / install / uninstall ...) + +Others: + help Show this help message + version Show version +``` + +## チャットコマンド + +Web コンソールや接続されたチャネルの会話で `/` を入力すると、コマンドの候補が表示されます。使用可能なコマンド： + +| コマンド | 説明 | +| --- | --- | +| `/help` | コマンドヘルプを表示 | +| `/status` | サービスの状態と設定を表示 | +| `/config` | 実行時設定の表示・変更 | +| `/skill` | スキル管理（インストール、アンインストール、有効化、無効化など） | +| `/context` | 現在のセッションのコンテキスト情報を表示 | +| `/context clear` | 現在のセッションのコンテキストをクリア | +| `/logs` | 最近のログを表示 | +| `/version` | バージョン番号を表示 | + + + `/start`、`/stop`、`/restart` などのサービス管理コマンドは、プロセス操作を伴うため、ターミナルでの使用を案内します。 + + +## コマンド対応表 + +| コマンド | ターミナル (`cow`) | チャット (`/`) | +| --- | :---: | :---: | +| help | ✓ | ✓ | +| version | ✓ | ✓ | +| status | ✓ | ✓ | +| logs | ✓ | ✓ | +| config | ✗ | ✓ | +| context | — | ✓ | +| skill（サブコマンド） | ✓ | ✓ | +| start / stop / restart | ✓ | ✗ | +| update | ✓ | ✗ | +| install-browser | ✓ | ✗ | + + + `context` はターミナルではチャットでの使用を案内するのみです。`config` はチャットでのみ利用可能です。 + diff --git a/docs/ja/commands/process.mdx b/docs/ja/commands/process.mdx new file mode 100644 index 00000000..4600f2b8 --- /dev/null +++ b/docs/ja/commands/process.mdx @@ -0,0 +1,123 @@ +--- +title: プロセス管理 +description: cow コマンドで CowAgent プロセスのライフサイクルを管理 +--- + +プロセス管理コマンドは CowAgent バックグラウンドプロセスのライフサイクルを制御します。これらのコマンドはターミナルでのみ使用可能です。 + +## start + +CowAgent サービスを起動します。デフォルトではバックグラウンドデーモンとして実行され、自動的にログを表示します。 + +```bash +cow start +``` + +**オプション：** + +| オプション | 説明 | +| --- | --- | +| `-f`, `--foreground` | フォアグラウンドで実行（デーモンとして起動しない） | +| `--no-logs` | 起動後にログを自動表示しない | + +## stop + +実行中の CowAgent サービスを停止します。 + +```bash +cow stop +``` + +## restart + +CowAgent サービスを再起動します（停止してから起動）。 + +```bash +cow restart +``` + +**オプション：** + +| オプション | 説明 | +| --- | --- | +| `--no-logs` | 再起動後にログを自動表示しない | + +## update + +コードを更新してサービスを再起動します。自動的に以下を実行します： + +1. 最新コードをプル（`git pull`） +2. 現在のサービスを停止 +3. Python 依存パッケージを更新 +4. CLI を再インストール +5. サービスを起動 + +```bash +cow update +``` + + + `git pull` が失敗した場合（ローカルの未コミットの変更がある場合など）、更新は中止され、サービスには影響しません。 + + +## status + +CowAgent サービスの実行状態を確認します。プロセス情報、バージョン、現在のモデルとチャネルの設定を含みます。 + +```bash +cow status +``` + +## logs + +サービスログを表示します。 + +```bash +cow logs +``` + +**オプション：** + +| オプション | 説明 | デフォルト値 | +| --- | --- | --- | +| `-f`, `--follow` | ログ出力を継続的に追跡 | いいえ | +| `-n`, `--lines` | 最近の N 行を表示 | 50 | + +例： + +```bash +# 最近の100行を表示 +cow logs -n 100 + +# ログを継続的に追跡 +cow logs -f +``` + +## install-browser + +[ブラウザツール](/ja/tools/browser)のために Playwright と Chromium ブラウザをインストールします。 + +```bash +cow install-browser +``` + + + ブラウザツール（Web ブラウジング、スクリーンショットなど）を使用する場合にのみ必要です。 + + +## run.sh との互換性 + +Cow CLI がインストールされていない場合は、`run.sh` でサービスを管理できます： + +| cow コマンド | run.sh 相当 | +| --- | --- | +| `cow start` | `./run.sh start` | +| `cow stop` | `./run.sh stop` | +| `cow restart` | `./run.sh restart` | +| `cow update` | `./run.sh update` | +| `cow status` | `./run.sh status` | +| `cow logs` | `./run.sh logs` | + + + `cow` コマンドの使用を推奨します。よりシンプルな構文と豊富な機能を提供します。ワンクリックインストールスクリプトで自動的にインストールされます。 + diff --git a/docs/ja/commands/skill.mdx b/docs/ja/commands/skill.mdx new file mode 100644 index 00000000..9e5c1ada --- /dev/null +++ b/docs/ja/commands/skill.mdx @@ -0,0 +1,192 @@ +--- +title: スキル管理 +description: コマンドでスキルのインストール、アンインストール、有効化、無効化、管理を行う +--- + +スキル管理コマンドは CowAgent のスキルのインストール、検索、管理に使用します。チャットでは `/skill <サブコマンド>`、ターミナルでは `cow skill <サブコマンド>` を使用します。 + +## list + +インストール済みスキルとその状態を一覧表示します。 + + +```text チャット +/skill list +``` + +```bash ターミナル +cow skill list +``` + + +**スキル広場を閲覧**（利用可能なすべてのスキルを表示）： + + +```text チャット +/skill list --remote +``` + +```bash ターミナル +cow skill list --remote +``` + + +**オプション：** + +| オプション | 説明 | デフォルト値 | +| --- | --- | --- | +| `--remote`, `-r` | Skill Hub のリモートスキルリストを閲覧 | いいえ | +| `--page` | リモートリストのページ番号 | 1 | + +## search + +スキル広場でスキルを検索します。 + + +```text チャット +/skill search pptx +``` + +```bash ターミナル +cow skill search pptx +``` + + +## install + +統一された `install` コマンドで、Cow スキル広場、GitHub、ClawHub、任意の URL（zip アーカイブ、SKILL.md リンク）からスキルをワンクリックでインストールできます。手動ダウンロードや設定は不要です。 + +**スキル広場からインストール（推奨）：** + + +```text チャット +/skill install pptx +``` + +```bash ターミナル +cow skill install pptx +``` + + +**GitHub からインストール：** + + +```text チャット +# リポジトリ内のすべてのスキルをインストール（SKILL.md を含むサブディレクトリを自動検出） +/skill install larksuite/cli + +# サブディレクトリを指定して単一スキルをインストール +/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im + +# # でサブディレクトリを指定 +/skill install larksuite/cli#skills/lark-minutes +``` + +```bash ターミナル +# リポジトリ内のすべてのスキルをインストール（SKILL.md を含むサブディレクトリを自動検出） +cow skill install larksuite/cli + +# サブディレクトリを指定して単一スキルをインストール +cow skill install https://github.com/larksuite/cli/tree/main/skills/lark-im + +# # でサブディレクトリを指定 +cow skill install larksuite/cli#skills/lark-minutes +``` + + +完全な GitHub URL と `owner/repo` 省略形に対応しています。モノリポ（1つのリポジトリに複数のスキル）の場合、サブディレクトリを省略するとすべてのスキルを自動検出して一括インストールします。サブディレクトリを指定した場合は、そのスキルのみをインストールします。 + +**ClawHub からインストール：** + + +```text チャット +/skill install clawhub:baidu-search +``` + +```bash ターミナル +cow skill install clawhub:baidu-search +``` + + +**URL からインストール：** + + +```text チャット +# zip アーカイブからインストール（単一またはバッチ） +/skill install https://cdn.link-ai.tech/skills/pptx.zip + +# SKILL.md リンクからインストール +/skill install https://example.com/path/to/SKILL.md +``` + +```bash ターミナル +# zip アーカイブからインストール（単一またはバッチ） +cow skill install https://cdn.link-ai.tech/skills/pptx.zip + +# SKILL.md リンクからインストール +cow skill install https://example.com/path/to/SKILL.md +``` + + +zip / tar.gz アーカイブ URL からのインストールに対応しており、自動的に解凍して `SKILL.md` を含むディレクトリを検出し、単一またはバッチインストールをサポートします。`SKILL.md` ファイルの URL から直接インストールすることもでき、スキル名と説明を自動的に解析します。 + +## uninstall + +インストール済みスキルをアンインストールします。 + + +```text チャット +/skill uninstall pptx +``` + +```bash ターミナル +cow skill uninstall pptx +``` + + + + アンインストールするとスキルディレクトリ内のすべてのファイルが削除されます。この操作は元に戻せません。 + + +## enable / disable + +スキルの有効化・無効化を行います。無効化されたスキルは Agent から呼び出されません。 + + +```text チャット +/skill enable pptx +/skill disable pptx +``` + +```bash ターミナル +cow skill enable pptx +cow skill disable pptx +``` + + +## info + +インストール済みスキルの詳細情報を表示します。`SKILL.md` のプレビューを含みます。 + + +```text チャット +/skill info pptx +``` + +```bash ターミナル +cow skill info pptx +``` + + +## スキルのソース + +インストールされたスキルはソース情報を記録しており、`/skill list` で確認できます： + +| ソース | 説明 | +| --- | --- | +| `builtin` | プロジェクト内蔵スキル | +| `cowhub` | CowAgent Skill Hub からインストール | +| `github` | GitHub URL から直接インストール | +| `clawhub` | ClawHub からインストール | +| `url` | SKILL.md URL からインストール | +| `local` | ローカルで作成されたスキル | diff --git a/docs/ja/guide/manual-install.mdx b/docs/ja/guide/manual-install.mdx index f75432dc..bffec65b 100644 --- a/docs/ja/guide/manual-install.mdx +++ b/docs/ja/guide/manual-install.mdx @@ -30,7 +30,25 @@ pip3 install -r requirements.txt pip3 install -r requirements-optional.txt ``` -### 3. 設定 +### 3. Cow CLI をインストール + +サービスとスキルを管理するためのコマンドラインツールをインストールします： + +```bash +pip3 install -e . +``` + +インストール後、`cow` コマンドが使用可能になります： + +```bash +cow help +``` + + + このステップは推奨です。インストール後、`cow start`、`cow stop`、`cow update` でサービスを管理でき、`cow skill` でスキルを管理できます。CLI をインストールしない場合は、`./run.sh` または `python3 app.py` で実行できます。 + + +### 4. 設定 設定テンプレートをコピーして編集します： @@ -40,22 +58,32 @@ cp config-template.json config.json `config.json` にモデルの API キー、チャネルタイプ、その他の設定を入力します。詳細は[モデルのドキュメント](/ja/models/index)を参照してください。 -### 4. 実行 +### 5. 実行 -**ローカルで実行：** +**Cow CLI を使用して実行（推奨）：** + +```bash +cow start +``` + +**またはローカルでフォアグラウンド実行：** ```bash python3 app.py ``` -デフォルトではWebサービスが起動します。`http://localhost:9899/chat` にアクセスしてチャットできます。 +デフォルトでは Web コンソールが起動します。`http://localhost:9899` にアクセスしてチャットできます。 -**サーバーでバックグラウンド実行：** +**サーバーでバックグラウンド実行（CLI 未使用時）：** ```bash nohup python3 app.py & tail -f nohup.out ``` + + サーバーにデプロイする場合は、ファイアウォールまたはセキュリティグループでポート `9899` を開放して Web コンソールにアクセスできるようにしてください。セキュリティのため、特定の IP のみにアクセスを制限することを推奨します。 + + ## Docker によるデプロイ Docker デプロイでは、ソースコードのクローンや依存パッケージのインストールは不要です。Agent モードを使用する場合は、より広範なシステムアクセスが可能なソースコードによるデプロイを推奨します。 @@ -84,6 +112,10 @@ sudo docker compose up -d sudo docker logs -f chatgpt-on-wechat ``` + + サーバーにデプロイする場合は、ファイアウォールまたはセキュリティグループでポート `9899` を開放して Web コンソールにアクセスできるようにしてください。セキュリティのため、特定の IP のみにアクセスを制限することを推奨します。 + + ## 主要な設定項目 ```json diff --git a/docs/ja/guide/quick-start.mdx b/docs/ja/guide/quick-start.mdx index 93378278..147170da 100644 --- a/docs/ja/guide/quick-start.mdx +++ b/docs/ja/guide/quick-start.mdx @@ -18,22 +18,27 @@ bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh) 1. Python環境の確認（Python 3.7以上が必要） 2. 必要なツールのインストール（git、curlなど） 3. プロジェクトを `~/chatgpt-on-wechat` にクローン -4. Pythonの依存パッケージをインストール +4. Pythonの依存パッケージと Cow CLI をインストール 5. AIモデルとチャネルの対話式設定 6. サービスの起動 -デフォルトでは、インストール後にWebサービスが起動します。`http://localhost:9899/chat` にアクセスしてチャットを開始できます。 +デフォルトでは、インストール後に Web コンソールが起動します。`http://localhost:9899` にアクセスしてチャットを開始できます。 ## 管理コマンド -インストール後、以下のコマンドでサービスを管理できます： +インストール後、`cow` コマンドでサービスを管理できます： | コマンド | 説明 | | --- | --- | -| `./run.sh start` | サービスを起動 | -| `./run.sh stop` | サービスを停止 | -| `./run.sh restart` | サービスを再起動 | -| `./run.sh status` | 実行状態を確認 | -| `./run.sh logs` | リアルタイムログを表示 | -| `./run.sh config` | 再設定 | -| `./run.sh update` | プロジェクトコードを更新 | +| `cow start` | サービスを起動 | +| `cow stop` | サービスを停止 | +| `cow restart` | サービスを再起動 | +| `cow status` | 実行状態を確認 | +| `cow logs` | リアルタイムログを表示 | +| `cow update` | コードを更新して再起動 | + +詳細は[コマンドドキュメント](/ja/commands/index)を参照してください。 + + + `cow` コマンドが利用できない場合は、`./run.sh <コマンド>`（例：`./run.sh start`、`./run.sh stop`）で代替できます。機能は同等です。 + diff --git a/docs/ja/guide/upgrade.mdx b/docs/ja/guide/upgrade.mdx index fcb28cb2..5eb1df7c 100644 --- a/docs/ja/guide/upgrade.mdx +++ b/docs/ja/guide/upgrade.mdx @@ -3,20 +3,25 @@ title: アップデート description: CowAgent のアップグレード方法 --- -## スクリプトによるアップグレード（推奨） +## コマンドによるアップグレード（推奨） -`run.sh` でサービスを管理している場合、以下のコマンドでワンクリックアップグレードできます： +`cow update` でコードの更新とサービスの再起動をワンクリックで実行できます： ```bash -./run.sh update +cow update ``` このコマンドは以下のフローを自動的に実行します： -1. 現在実行中のサービスを停止 -2. 最新コードをプル -3. 依存関係を再チェック -4. サービスを起動 +1. 最新コードをプル（`git pull`） +2. 現在のサービスを停止 +3. Python 依存パッケージを更新 +4. CLI を再インストール +5. サービスを起動 + + + Cow CLI がインストールされていない場合は、`./run.sh update` でも同様の操作が可能です。 + ## 手動アップグレード @@ -25,15 +30,19 @@ description: CowAgent のアップグレード方法 ```bash git pull pip3 install -r requirements.txt +pip3 install -e . ``` 更新完了後、サービスを再起動します： ```bash -# run.sh で管理している場合 +# Cow CLI を使用 +cow restart + +# または run.sh を使用 ./run.sh restart -# nohup で直接実行している場合 +# または nohup で直接実行 kill $(ps -ef | grep app.py | grep -v grep | awk '{print $2}') nohup python3 app.py & tail -f nohup.out ``` diff --git a/docs/ja/intro/index.mdx b/docs/ja/intro/index.mdx index 57979925..14047e20 100644 --- a/docs/ja/intro/index.mdx +++ b/docs/ja/intro/index.mdx @@ -28,6 +28,12 @@ CowAgent は自ら思考しタスクを計画し、コンピュータや外部 テキスト、画像、音声、ファイルなどのメッセージタイプの解析、処理、生成、送信をサポートします。 + + ファイル読み書き、ターミナル実行、ブラウザ操作、スケジュールタスク、メッセージ送信などの組み込みツールを提供。Agent が自律的にツールを呼び出して複雑なタスクを完了します。 + + + ターミナル CLI とチャット内コマンドを提供し、プロセス管理、Skill インストール、設定変更、コンテキスト確認などの一般的な操作をサポートします。 + OpenAI、Claude、Gemini、DeepSeek、MiniMax、GLM、Qwen、Kimi、Doubao など、主要なモデルプロバイダーをサポートしています。 diff --git a/docs/ja/memory/context.mdx b/docs/ja/memory/context.mdx new file mode 100644 index 00000000..6694c3c2 --- /dev/null +++ b/docs/ja/memory/context.mdx @@ -0,0 +1,80 @@ +--- +title: 短期記憶 +description: 会話コンテキスト — メッセージ管理、圧縮戦略、コンテキスト操作 +--- + +会話コンテキストは Agent の短期記憶であり、現在のセッション内のすべてのメッセージ（ユーザー入力、Agent の返信、ツール呼び出しと結果）を含みます。適切なコンテキスト管理は、Agent の推論品質とコスト制御にとって重要です。 + +## コンテキストの構造 + +各会話ターンは以下で構成されます： + +``` +ユーザーメッセージ → Agent の思考 → ツール呼び出し → ツール結果 → ... → Agent の最終返信 +``` + +1 つのターンには複数のツール呼び出しが含まれる場合があります（`agent_max_steps` で制御）。すべてのツール呼び出しと結果は、圧縮またはトリミングされるまでコンテキストに保持されます。 + +## 主要な設定 + +| パラメータ | 説明 | デフォルト値 | +| --- | --- | --- | +| `agent_max_context_tokens` | コンテキストの最大トークン予算 | `50000` | +| `agent_max_context_turns` | コンテキストの最大会話ターン数 | `20` | +| `agent_max_steps` | ターンあたりの最大判断ステップ数（ツール呼び出し回数） | `15` | + +`config.json` またはチャットの `/config` コマンドで設定できます。 + +## 圧縮戦略 + +コンテキストが制限を超えた場合、システムは自動的に圧縮を実行してスペースを解放します。このプロセスには複数の段階があります： + +### 1. ツール結果の切り詰め + +各判断ループの開始前に、過去のターンのツール呼び出し結果を確認します。**20,000 文字** を超えるツール結果は切り詰められ、先頭と末尾のみが保持されます。現在のターンの結果は影響を受けません。 + +### 2. ターンのトリミング + +会話ターン数が `agent_max_context_turns` を超えた場合： + +- **最も古い半分** の完全なターンがトリミングされます（ツール呼び出しチェーンの完全性を保証） +- トリミングされたメッセージは LLM によって要約され、**日次記憶ファイルに書き込まれます** +- 残りのターンはそのまま保持されます + +### 3. トークン予算のトリミング + +ターンのトリミング後、トークン数がまだ予算を超えている場合： + +- **5 ターン未満の場合**：すべてのターンで**テキスト圧縮**を実行 — 各ターンは最初のユーザーテキストと最後の Agent 返信のみを保持し、中間のツール呼び出しチェーンを削除 +- **5 ターン以上の場合**：**前半のターン**を再度トリミングし、破棄されたコンテンツも記憶に書き込まれます + +### 4. オーバーフロー緊急処理 + +モデル API がコンテキストオーバーフローエラーを返した場合： + +1. 現在のすべてのメッセージを要約して記憶に書き込み +2. 積極的なトリミングを適用（ツール結果は 10K 文字に制限、ユーザーテキストは 10K、最大 5 ターン） +3. それでもオーバーフローする場合は、会話コンテキスト全体をクリア + +## セッションの永続化 + +会話メッセージはローカルデータベースに永続化され、サービス再起動後に自動的に復元されます。復元戦略： + +- 最近の **`max(3, max_context_turns / 6)`** ターンを復元 +- 各ターンの**ユーザーテキストと Agent の最終返信のみ**を保持し、中間のツール呼び出しチェーンは復元しません +- **30 日** を超える過去のセッションは自動的にクリーンアップされます + +## 操作コマンド + +チャットで以下のコマンドを使用してコンテキストを管理できます： + +| コマンド | 説明 | +| --- | --- | +| `/context` | 現在のコンテキスト統計を表示（メッセージ数、ロール分布、合計文字数） | +| `/context clear` | 現在のセッションコンテキストをクリア | +| `/config agent_max_context_tokens 80000` | コンテキストトークン予算を調整 | +| `/config agent_max_context_turns 30` | コンテキストターン上限を調整 | + + + コンテキストをクリアすると、Agent は以前の会話内容を「忘れます」。すでに長期記憶に書き込まれたコンテンツは、記憶検索を通じて引き続き取得できます。 + diff --git a/docs/ja/memory.mdx b/docs/ja/memory/index.mdx similarity index 52% rename from docs/ja/memory.mdx rename to docs/ja/memory/index.mdx index 5e2ac759..cd2fc45f 100644 --- a/docs/ja/memory.mdx +++ b/docs/ja/memory/index.mdx @@ -1,25 +1,25 @@ --- -title: 記憶 -description: CowAgent 長期記憶システム +title: 長期記憶 +description: CowAgent の長期記憶システム — ファイル永続化、自動書き込み、ハイブリッド検索 --- -記憶システムにより、Agent は重要な情報を長期にわたって記憶し、継続的に経験を蓄積し、ユーザーの好みを理解し、真に自律的な思考と継続的な成長を実現できます。 +長期記憶はワークスペースのファイルに保存され、セッション間で永続化されます。Agent は会話中に検索ツールを通じて過去の記憶をオンデマンドで読み込み、コンテキストのトリミング時に会話の要約を自動的に長期記憶に書き込みます。 ## 記憶の種類 -### コア記憶 (MEMORY.md) +### コア記憶（MEMORY.md） -`~/cow/MEMORY.md` に保存され、長期的なユーザーの好み、重要な決定、主要な事実など、時間が経っても薄れない情報を含みます。毎回の会話ターンでバックグラウンド知識としてシステムプロンプトに自動的に注入されます。 +`~/cow/MEMORY.md` に保存され、長期的なユーザーの好み、重要な決定、主要な事実など、時間が経っても薄れない情報を含みます。Agent はツールを通じてこのファイルを読み書きし、長期的な知識を維持します。 -### 日次記憶 (memory/YYYY-MM-DD.md) +### 日次記憶（memory/YYYY-MM-DD.md） `~/cow/memory/` ディレクトリに保存され、日付で命名されます（例：`2026-03-08.md`）。日々の会話の要約と主要なイベントを記録します。空ファイルの生成を避けるため、最初の書き込み時にのみファイルが作成されます。 -## 記憶の書き込み +## 自動書き込み -Agent は以下のメカニズムにより、会話内容を日次記憶に自動的に永続化します： +Agent は以下のメカニズムにより、会話内容を長期記憶に自動的に永続化します： -- **コンテキストトリミング時** — 会話ターン数またはトークン数が設定上限を超えた場合、コンテキストの古い半分が一括でトリミングされ、破棄されたコンテンツは LLM によって要約されて重要な情報として日次記憶ファイルに書き込まれます +- **コンテキストトリミング時** — 会話ターン数またはトークン数が設定上限を超えた場合、最も古い半分のコンテキストがトリミングされ、LLM によって要約されて日次記憶ファイルに書き込まれます - **毎日のスケジュール要約** — 毎日 23:55 に自動的にフル要約がトリガーされ、アクティビティが少ない日でも記憶が保存されます（内容が変更されていない場合はスキップ） - **API コンテキストオーバーフロー時** — モデル API がコンテキストオーバーフローエラーを返した場合、緊急措置として現在の会話要約が保存されます @@ -40,27 +40,10 @@ Agent は以下のメカニズムにより、会話内容を日次記憶に自 -## 記憶の検索 - -記憶システムはハイブリッド検索モードをサポートしています： - -- **キーワード検索** — キーワードに基づいて過去の記憶をマッチング -- **ベクトル検索** — セマンティック類似性検索により、異なる表現でも関連する記憶を発見 - -Agent は必要に応じて会話中に自動的に記憶検索をトリガーし、関連する過去の情報をコンテキストに組み込みます。コア記憶（`MEMORY.md`）は常にシステムプロンプトに注入され、日次記憶は検索を通じてオンデマンドで読み込まれます。 - ## 設定 -```json -{ - "agent_workspace": "~/cow", - "agent_max_context_tokens": 40000, - "agent_max_context_turns": 20 -} -``` - | パラメータ | 説明 | デフォルト | | --- | --- | --- | | `agent_workspace` | ワークスペースパス、記憶ファイルはこのディレクトリ配下に保存されます | `~/cow` | -| `agent_max_context_tokens` | 最大コンテキストトークン数。超過時に半分がトリミングされ、記憶として要約されます | `40000` | -| `agent_max_context_turns` | 最大コンテキストターン数。超過時に半分がトリミングされ、記憶として要約されます | `20` | +| `agent_max_context_tokens` | 最大コンテキストトークン数。超過時にトリミングされ、記憶として要約されます | `50000` | +| `agent_max_context_turns` | 最大コンテキストターン数。超過時にトリミングされ、記憶として要約されます | `20` | diff --git a/docs/ja/skills/create.mdx b/docs/ja/skills/create.mdx new file mode 100644 index 00000000..e996cf39 --- /dev/null +++ b/docs/ja/skills/create.mdx @@ -0,0 +1,58 @@ +--- +title: スキルの作成 +description: 会話を通じてカスタムスキルを作成 +--- + +CowAgent には Skill Creator が組み込まれており、自然言語の会話を通じてスキルの作成、インストール、更新を素早く行えます。 + +## 使い方 + +会話で作りたいスキルを説明するだけで、Agent が自動的に作成します： + +- ワークフローをスキル化：「このデプロイプロセスからスキルを作成して」 +- サードパーティ API の統合：「この API ドキュメントに基づいてスキルを作成して」 +- リモートスキルのインストール：「xxx スキルをインストールして」 + +## 作成フロー + +1. 作成したいスキルを Agent に伝えます +2. Agent が自動的に `SKILL.md` の説明と実行スクリプトを生成します +3. スキルはワークスペースの `~/cow/skills/` ディレクトリに保存されます +4. 以降の会話で Agent が自動的にそのスキルを認識し使用します + + + + + +## SKILL.md のフォーマット + +作成されたスキルは標準の SKILL.md フォーマットに従います： + +```markdown +--- +name: my-skill +description: Brief description of the skill +metadata: + emoji: 🔧 + requires: + bins: ["curl"] + env: ["MY_API_KEY"] + primaryEnv: "MY_API_KEY" +--- + +# My Skill + +Detailed instructions... +``` + +| フィールド | 説明 | +| --- | --- | +| `name` | スキル名。ディレクトリ名と一致する必要があります | +| `description` | スキルの説明。Agent はこれに基づいて呼び出すかどうかを判断します | +| `metadata.requires.bins` | 必要なシステムコマンド | +| `metadata.requires.env` | 必要な環境変数 | +| `metadata.always` | 常に読み込む（デフォルトは false） | + + + 詳細は [Skill Creator のドキュメント](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md)をご覧ください。 + diff --git a/docs/ja/skills/image-vision.mdx b/docs/ja/skills/image-vision.mdx deleted file mode 100644 index 9c7833e2..00000000 --- a/docs/ja/skills/image-vision.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Image Vision -description: OpenAI の Vision モデルを使用して画像を認識 ---- - -OpenAI の GPT-4 Vision API を使用して画像の内容を分析し、画像内のオブジェクト、テキスト、色などの要素を理解します。 - -## 依存関係 - -| 依存関係 | 説明 | -| --- | --- | -| `OPENAI_API_KEY` | OpenAI API キー | -| `curl`, `base64` | システムコマンド（通常プリインストール済み） | - -設定方法： - -- `env_config` Tool で `OPENAI_API_KEY` を設定 -- または `config.json` で `open_ai_api_key` を設定 - -## 対応モデル - -- `gpt-4.1-mini`（推奨、コストパフォーマンスに優れる） -- `gpt-4.1` - -## 使い方 - -設定が完了したら、Agent に画像を送信すると自動的に画像認識がトリガーされます。 - - - - diff --git a/docs/ja/skills/index.mdx b/docs/ja/skills/index.mdx index c15bf93b..546be8d5 100644 --- a/docs/ja/skills/index.mdx +++ b/docs/ja/skills/index.mdx @@ -1,35 +1,32 @@ --- -title: Skill 概要 -description: CowAgent の Skill システム紹介 +title: スキル概要 +description: CowAgent のスキルシステム紹介 --- -Skill は Agent に無限の拡張性を提供します。各 Skill は説明ファイル（`SKILL.md`）、実行スクリプト（任意）、リソース（任意）で構成され、特定のタスクをどのように遂行するかを記述します。 +スキル（Skill）は Agent に無限の拡張性を提供します。各スキルは説明ファイル（`SKILL.md`）、実行スクリプト（任意）、リソース（任意）で構成され、特定のタスクをどのように遂行するかを記述します。 -Skill と Tool の違い：Tool はコードで実装された原子的な操作（例：ファイルの読み書き、コマンドの実行）であるのに対し、Skill は説明ファイルに基づく高レベルなワークフローであり、複数の Tool を組み合わせて複雑なタスクを完遂できます。 +スキルとツールの違い：ツールはコードで実装された原子的な操作（例：ファイルの読み書き、コマンドの実行）であるのに対し、スキルは説明ファイルに基づく高レベルなワークフローであり、複数のツールを組み合わせて複雑なタスクを完遂できます。 -## 組み込み Skill +## スキルの取得 -プロジェクトの `skills/` ディレクトリに配置されており、依存条件に基づいて自動的に有効化されます： +CowAgent ではスキルを取得する複数の方法を提供しています： -| Skill | 説明 | 依存関係 | -| --- | --- | --- | -| [`skill-creator`](/ja/skills/skill-creator) | 会話を通じてカスタム Skill を作成 | なし | -| [`openai-image-vision`](/ja/skills/image-vision) | OpenAI の Vision モデルを使用して画像を認識 | `OPENAI_API_KEY` | -| [`linkai-agent`](/ja/skills/linkai-agent) | LinkAI プラットフォームの Agent を統合 | `LINKAI_API_KEY` | -| [`web-fetch`](/ja/skills/web-fetch) | Web ページのテキストコンテンツを取得 | `curl`（デフォルトで有効） | +- **Cow スキル広場** — `/skill list --remote` でコミュニティスキルを閲覧・インストール +- **GitHub** — GitHub リポジトリから直接インストール、バッチインストールにも対応 +- **ClawHub** — `/skill install clawhub:名前` で ClawHub のスキルをインストール +- **URL** — zip アーカイブや SKILL.md リンクからインストール +- **会話で作成** — 自然言語の会話を通じて Agent にスキルを自動作成させる -## カスタム Skill +詳細は[スキルのインストール](/ja/skills/install)と[スキル管理コマンド](/ja/commands/skill)を参照してください。会話を通じて[スキルを作成](/ja/skills/create)することもできます。 -ユーザーが会話を通じて作成し、ワークスペース（`~/cow/skills/`）に保存されます。任意の複雑なビジネスプロセスやサードパーティシステムとの連携を実装できます。 +## スキルの読み込み優先順位 -## Skill の読み込み優先順位 +1. **ワークスペースのスキル**（最高優先）：`~/cow/skills/` +2. **プロジェクト組み込みスキル**（最低優先）：`skills/` -1. **ワークスペースの Skill**（最高優先）：`~/cow/skills/` -2. **プロジェクト組み込み Skill**（最低優先）：`skills/` +同名のスキルは優先順位に従って上書きされます。 -同名の Skill は優先順位に従って上書きされます。 - -## Skill のファイル構成 +## スキルのファイル構成 ``` skills/ @@ -60,8 +57,8 @@ Detailed instructions... | フィールド | 説明 | | --- | --- | -| `name` | Skill 名。ディレクトリ名と一致する必要があります | -| `description` | Skill の説明。Agent はこれに基づいて呼び出すかどうかを判断します | +| `name` | スキル名。ディレクトリ名と一致する必要があります | +| `description` | スキルの説明。Agent はこれに基づいて呼び出すかどうかを判断します | | `metadata.requires.bins` | 必要なシステムコマンド | | `metadata.requires.env` | 必要な環境変数 | | `metadata.always` | 常に読み込む（デフォルトは false） | diff --git a/docs/ja/skills/install.mdx b/docs/ja/skills/install.mdx new file mode 100644 index 00000000..168e7cc6 --- /dev/null +++ b/docs/ja/skills/install.mdx @@ -0,0 +1,53 @@ +--- +title: スキルのインストール +description: 統一コマンドで多様なソースからスキルをインストール +--- + +CowAgent は統一された `install` コマンドで、**Cow スキル広場、GitHub、ClawHub** および任意の URL からスキルをインストールできます。チャットでは `/skill install`、ターミナルでは `cow skill install` を使用します。 + +## スキル広場からインストール + +スキル広場を閲覧してインストール： + +```text +/skill list --remote +/skill install pptx +``` + +## GitHub からインストール + +リポジトリからの一括インストールとサブディレクトリ指定に対応： + +```text +/skill install larksuite/cli +/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im +``` + +## ClawHub からインストール + +```text +/skill install clawhub:baidu-search +``` + +## URL からインストール + +zip アーカイブと SKILL.md ファイルリンクに対応： + +```text +/skill install https://cdn.link-ai.tech/skills/pptx.zip +/skill install https://example.com/path/to/SKILL.md +``` + +## スキルの管理 + +```text +/skill list # インストール済みスキルを表示 +/skill info pptx # スキルの詳細を表示 +/skill enable pptx # スキルを有効化 +/skill disable pptx # スキルを無効化 +/skill uninstall pptx # スキルをアンインストール +``` + + + 上記のすべてのコマンドは、ターミナルでは `/skill` を `cow skill` に置き換えて使用できます。完全なコマンドドキュメントは[スキル管理コマンド](/ja/commands/skill)を参照してください。 + diff --git a/docs/ja/skills/linkai-agent.mdx b/docs/ja/skills/linkai-agent.mdx deleted file mode 100644 index 537cc96d..00000000 --- a/docs/ja/skills/linkai-agent.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: LinkAI Agent -description: LinkAI プラットフォームのマルチ Agent Skill を統合 ---- - -[LinkAI](https://link-ai.tech/) プラットフォームの Agent を Skill として使用し、マルチ Agent の意思決定を行います。Agent は Agent 名と説明に基づいてインテリジェントに選択し、`app_code` を通じて対応するアプリケーションやワークフローを呼び出します。 - -## 依存関係 - -| 依存関係 | 説明 | -| --- | --- | -| `LINKAI_API_KEY` | LinkAI プラットフォームの API キー。[コンソール](https://link-ai.tech/console/interface)で作成 | -| `curl` | システムコマンド（通常プリインストール済み） | - -設定方法： - -- `env_config` Tool で `LINKAI_API_KEY` を設定 -- または `config.json` で `linkai_api_key` を設定 - -## Agent の設定 - -`skills/linkai-agent/config.json` で利用可能な Agent を追加します： - -```json -{ - "apps": [ - { - "app_code": "G7z6vKwp", - "app_name": "LinkAI Customer Support", - "app_description": "Select this assistant only when the user needs help with LinkAI platform questions" - }, - { - "app_code": "SFY5x7JR", - "app_name": "Content Creator", - "app_description": "Use this assistant only when the user needs to create images or videos" - } - ] -} -``` - -## 使い方 - -設定が完了すると、Agent はユーザーの質問に基づいて適切な LinkAI Agent を自動的に選択します。 - - - - diff --git a/docs/ja/skills/skill-creator.mdx b/docs/ja/skills/skill-creator.mdx deleted file mode 100644 index 1bc35a9b..00000000 --- a/docs/ja/skills/skill-creator.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Skill Creator -description: 会話を通じてカスタム Skill を作成 ---- - -自然言語の会話を通じて、Skill の作成、インストール、更新を素早く行えます。 - -## 依存関係 - -追加の依存関係は不要で、常に利用可能です。 - -## 使い方 - -- ワークフローを Skill 化：「このデプロイプロセスから Skill を作成して」 -- サードパーティ API の統合：「この API ドキュメントに基づいて Skill を作成して」 -- リモート Skill のインストール：「xxx Skill をインストールして」 - -## 作成フロー - -1. 作成したい Skill を Agent に伝えます -2. Agent が自動的に `SKILL.md` の説明と実行スクリプトを生成します -3. Skill はワークスペースの `~/cow/skills/` ディレクトリに保存されます -4. 以降の会話で Agent が自動的にその Skill を認識し使用します - - - - - - - 詳細は [Skill Creator のドキュメント](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md)をご覧ください。 - diff --git a/docs/ja/skills/web-fetch.mdx b/docs/ja/skills/web-fetch.mdx deleted file mode 100644 index 8712e86a..00000000 --- a/docs/ja/skills/web-fetch.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Web Fetch -description: Web ページのテキストコンテンツを取得 ---- - -curl を使用して Web ページを取得し、読み取り可能なテキストコンテンツを抽出します。ブラウザ自動化を必要としない軽量な Web アクセス方法です。 - -## 依存関係 - -| 依存関係 | 説明 | -| --- | --- | -| `curl` | システムコマンド（通常プリインストール済み） | - -この Skill は `always: true` が設定されており、システムに `curl` コマンドがあればデフォルトで有効になります。 - -## 使い方 - -Agent が URL からコンテンツを取得する必要がある場合に自動的に呼び出されます。追加の設定は不要です。 - -## browser Tool との比較 - -| 機能 | web-fetch (Skill) | browser (Tool) | -| --- | --- | --- | -| 依存関係 | curl のみ | browser-use + playwright | -| JS レンダリング | 非対応 | 対応 | -| ページ操作 | 非対応 | クリック、入力などに対応 | -| 最適な用途 | 静的ページのテキスト | 動的な Web ページ | - - - ほとんどの Web コンテンツ取得シナリオでは、web-fetch で十分です。JS レンダリングやページ操作が必要な場合にのみ browser Tool を使用してください。 - diff --git a/docs/memory/context.mdx b/docs/memory/context.mdx new file mode 100644 index 00000000..deff8585 --- /dev/null +++ b/docs/memory/context.mdx @@ -0,0 +1,80 @@ +--- +title: 短期记忆 +description: 对话上下文 — 消息管理、压缩策略和上下文操作 +--- + +对话上下文是 Agent 的短期记忆，包含当前会话中的所有消息（用户输入、Agent 回复、工具调用及结果）。合理管理上下文对于 Agent 的推理质量和成本控制至关重要。 + +## 上下文结构 + +每一轮对话由以下消息组成： + +``` +用户消息 → Agent 思考 → 工具调用 → 工具结果 → ... → Agent 最终回复 +``` + +一轮中可能包含多次工具调用（Agent 的决策步数由 `agent_max_steps` 控制），所有工具调用和结果都会保留在上下文中，直到被压缩或裁剪。 + +## 关键配置 + +| 参数 | 说明 | 默认值 | +| --- | --- | --- | +| `agent_max_context_tokens` | 上下文最大 token 预算 | `50000` | +| `agent_max_context_turns` | 上下文最大对话轮次 | `20` | +| `agent_max_steps` | 单轮对话最大决策步数（工具调用次数） | `15` | + +可通过 `config.json` 或对话中的 `/config` 命令修改。 + +## 压缩策略 + +当上下文超出限制时，系统会自动执行压缩以释放空间。整个过程分为多个阶段： + +### 1. 工具结果截断 + +在每次决策循环开始前，系统会检查历史轮次中的工具调用结果。超过 **20000 字符** 的工具结果会被截断，仅保留首尾内容和截断说明。当前轮次的工具结果不受影响。 + +### 2. 轮次裁剪 + +当对话轮次超过 `agent_max_context_turns` 时： + +- 裁剪 **最早一半** 的完整轮次（保证工具调用链的完整性） +- 被裁剪的消息会通过 LLM 总结后**写入当天的日级记忆文件** +- 剩余轮次保持不变 + +### 3. Token 预算裁剪 + +裁剪轮次后，如果 token 数仍超出预算： + +- **轮次 < 5 时**：对所有轮次进行**文本压缩** — 每轮只保留第一条用户文本和最后一条 Agent 回复，去掉中间的工具调用链 +- **轮次 ≥ 5 时**：再次裁剪**前半轮次**，被丢弃内容同样写入记忆 + +### 4. 溢出应急处理 + +当模型 API 返回上下文溢出错误时： + +1. 先将当前所有消息总结写入记忆 +2. 执行激进裁剪（工具结果限制 10K 字符、用户文本限制 10K、最多保留 5 轮） +3. 如果仍然溢出，清空整个对话上下文 + +## 会话持久化 + +对话消息会持久化到本地数据库，服务重启后自动恢复。恢复策略： + +- 恢复最近的 **`max(3, max_context_turns / 6)`** 轮对话 +- 只保留每轮的**用户文本和 Agent 最终回复**，不恢复中间工具调用链 +- 超过 **30 天**的历史会话自动清理 + +## 操作命令 + +在对话中可以使用以下命令管理上下文： + +| 命令 | 说明 | +| --- | --- | +| `/context` | 查看当前上下文统计（消息数、角色分布、总字符数） | +| `/context clear` | 清空当前会话上下文 | +| `/config agent_max_context_tokens 80000` | 调整上下文 token 预算 | +| `/config agent_max_context_turns 30` | 调整上下文轮次上限 | + + + 清空上下文后，Agent 会"忘记"之前的对话内容。被裁剪和清空的内容如果已经写入长期记忆，仍可通过记忆检索找回。 + diff --git a/docs/memory.mdx b/docs/memory/index.mdx similarity index 56% rename from docs/memory.mdx rename to docs/memory/index.mdx index 5cfd101c..7aa9dff4 100644 --- a/docs/memory.mdx +++ b/docs/memory/index.mdx @@ -1,30 +1,39 @@ --- title: 长期记忆 -description: CowAgent 的长期记忆系统 +description: CowAgent 的长期记忆系统 — 文件持久化、自动写入与混合检索 --- -记忆系统让 Agent 能够长期记住重要信息，在对话中不断积累经验、理解用户偏好，真正实现自主思考和持续成长。 +长期记忆保存在工作空间文件中，跨会话持久存在。Agent 在对话中通过检索工具按需加载历史记忆，也会在上下文裁剪时自动将对话摘要写入长期记忆。 ## 记忆类型 ### 核心记忆（MEMORY.md） -存储在 `~/cow/MEMORY.md` 中，包含用户的长期偏好、重要决策、关键事实等不会随时间淡化的信息。每次对话时自动注入系统提示词，作为 Agent 的背景知识。 +存储在 `~/cow/MEMORY.md` 中，包含用户的长期偏好、重要决策、关键事实等不会随时间淡化的信息。Agent 可通过工具读写此文件来维护长期知识。 -### 天级记忆（memory/YYYY-MM-DD.md） +### 日级记忆（memory/YYYY-MM-DD.md） 存储在 `~/cow/memory/` 目录下，按日期命名（如 `2026-03-08.md`），记录每天的对话摘要和关键事件。仅在首次写入时创建，避免生成空文件。 -## 记忆写入 +## 自动写入 -Agent 通过以下机制自动将对话内容持久化为天级记忆： +Agent 通过以下机制自动将对话内容持久化为长期记忆： -- **上下文裁剪时** — 当对话轮次或 token 超出配置上限时，批量裁剪最早一半的上下文，并使用 LLM 将被裁剪的内容总结为关键信息写入当天记忆文件 +- **上下文裁剪时** — 当对话轮次或 token 超出配置上限时，裁剪最早一半的上下文，使用 LLM 将被裁剪的内容总结为关键信息写入当天记忆文件 - **每日定时总结** — 每天 23:55 自动触发一次全量总结，防止低活跃日无记忆留存（内容无变化时自动跳过） - **API 上下文溢出时** — 当模型 API 返回上下文溢出错误时，紧急保存当前对话摘要 所有记忆写入均在后台异步执行（LLM 总结 + 文件写入），不阻塞正常对话回复。 +## 记忆检索 + +记忆系统支持混合检索模式： + +- **关键词检索** — 基于 FTS5 全文索引匹配历史记忆，支持 BM25 排序 +- **向量检索** — 基于 embedding 语义相似度搜索，即使表述不同也能找到相关记忆 + +Agent 会在对话中根据需要自动触发记忆检索，将相关历史信息纳入上下文。检索结果按混合评分排序（默认向量权重 0.7、关键词权重 0.3），日级记忆会随时间衰减（半衰期 30 天），核心记忆不衰减。 + ## 首次启动 首次启动 Agent 时，Agent 会主动向用户询问关键信息，并记录至工作空间（默认 `~/cow`）中： @@ -34,33 +43,16 @@ Agent 通过以下机制自动将对话内容持久化为天级记忆： | `system.md` | Agent 的系统提示词和行为设定 | | `user.md` | 用户身份信息和偏好 | | `MEMORY.md` | 核心记忆（长期） | -| `memory/YYYY-MM-DD.md` | 天级记忆（按需创建） | +| `memory/YYYY-MM-DD.md` | 日级记忆（按需创建） | -## 记忆检索 - -记忆系统支持混合检索模式： - -- **关键词检索** — 基于关键词匹配历史记忆 -- **向量检索** — 基于语义相似度搜索，即使表述不同也能找到相关记忆 - -Agent 会在对话中根据需要自动触发记忆检索，将相关历史信息纳入上下文。核心记忆（`MEMORY.md`）始终注入系统提示词，天级记忆通过检索按需加载。 - ## 相关配置 -```json -{ - "agent_workspace": "~/cow", - "agent_max_context_tokens": 40000, - "agent_max_context_turns": 20 -} -``` - | 参数 | 说明 | 默认值 | | --- | --- | --- | | `agent_workspace` | 工作空间路径，记忆文件存储在此目录下 | `~/cow` | -| `agent_max_context_tokens` | 最大上下文 token 数，超出时裁剪一半并总结写入记忆 | `40000` | -| `agent_max_context_turns` | 最大上下文轮次，超出时裁剪一半并总结写入记忆 | `20` | +| `agent_max_context_tokens` | 最大上下文 token 数，超出时裁剪并总结写入记忆 | `50000` | +| `agent_max_context_turns` | 最大上下文轮次，超出时裁剪并总结写入记忆 | `20` | diff --git a/docs/skills/create.mdx b/docs/skills/create.mdx new file mode 100644 index 00000000..b0f53a11 --- /dev/null +++ b/docs/skills/create.mdx @@ -0,0 +1,58 @@ +--- +title: 创建技能 +description: 通过对话创建自定义技能 +--- + +CowAgent 内置了 Skill Creator，可以通过自然语言对话快速创建、安装或更新技能。 + +## 使用方式 + +直接在对话中描述你想要的技能，Agent 会自动完成创建： + +- 将工作流程固化为技能："帮我把这个部署流程创建为一个技能" +- 对接第三方 API："根据这个接口文档创建一个技能" +- 安装远程技能："帮我安装 xxx 技能" + +## 创建流程 + +1. 告诉 Agent 你想创建的技能功能 +2. Agent 自动生成 `SKILL.md` 说明文件和运行脚本 +3. 技能保存到工作空间的 `~/cow/skills/` 目录 +4. 后续对话中 Agent 会自动识别并使用该技能 + + + + + +## SKILL.md 格式 + +创建的技能遵循标准的 SKILL.md 格式： + +```markdown +--- +name: my-skill +description: Brief description of the skill +metadata: + emoji: 🔧 + requires: + bins: ["curl"] + env: ["MY_API_KEY"] + primaryEnv: "MY_API_KEY" +--- + +# My Skill + +Detailed instructions... +``` + +| 字段 | 说明 | +| --- | --- | +| `name` | 技能名称，需与目录名一致 | +| `description` | 技能描述，Agent 据此决定是否调用 | +| `metadata.requires.bins` | 依赖的系统命令 | +| `metadata.requires.env` | 依赖的环境变量 | +| `metadata.always` | 是否始终加载（默认 false） | + + + 详细开发文档可参考 [Skill Creator 说明](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md)。 + diff --git a/docs/skills/image-vision.mdx b/docs/skills/image-vision.mdx deleted file mode 100644 index 1c71f620..00000000 --- a/docs/skills/image-vision.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 图像识别 -description: 使用 OpenAI 视觉模型识别图片 ---- - -使用 OpenAI 的 GPT-4 Vision API 分析图片内容，理解图像中的物体、文字、颜色等元素。 - -## 依赖 - -| 依赖 | 说明 | -| --- | --- | -| `OPENAI_API_KEY` | OpenAI API 密钥 | -| `curl`、`base64` | 系统命令（通常已预装） | - -配置方式： - -- 通过 `env_config` 工具配置 `OPENAI_API_KEY` -- 或在 `config.json` 中填写 `open_ai_api_key` - -## 支持的模型 - -- `gpt-4.1-mini`（推荐，性价比高） -- `gpt-4.1` - -## 使用方式 - -配置完成后，向 Agent 发送图片即可自动触发图像识别。 - - - - diff --git a/docs/skills/index.mdx b/docs/skills/index.mdx index 86c83d08..5648ceaf 100644 --- a/docs/skills/index.mdx +++ b/docs/skills/index.mdx @@ -7,20 +7,17 @@ description: CowAgent 技能系统介绍 Skill 与 Tool 的区别：Tool 是由代码实现的原子操作（如读写文件、执行命令），Skill 则是基于说明文件的高级工作流，可以组合调用多个 Tool 来完成复杂任务。 -## 内置技能 +## 获取技能 -位于项目 `skills/` 目录下，根据依赖条件自动判断是否启用： +CowAgent 提供多种方式获取技能： -| 技能 | 说明 | 依赖 | -| --- | --- | --- | -| [`skill-creator`](/skills/skill-creator) | 通过对话创建自定义技能 | 无 | -| [`openai-image-vision`](/skills/image-vision) | 使用 OpenAI 视觉模型识别图片 | `OPENAI_API_KEY` | -| [`linkai-agent`](/skills/linkai-agent) | 对接 LinkAI 平台智能体 | `LINKAI_API_KEY` | -| [`web-fetch`](/skills/web-fetch) | 抓取网页文本内容 | `curl`（默认启用） | +- **Cow 技能广场** — 通过 `/skill list --remote` 浏览和安装社区技能 +- **GitHub** — 直接从 GitHub 仓库安装，支持批量安装 +- **ClawHub** — 通过 `/skill install clawhub:名称` 安装 ClawHub 上的技能 +- **URL** — 从 zip 压缩包或 SKILL.md 链接安装 +- **对话创建** — 通过自然语言对话让 Agent 自动创建技能 -## 自定义技能 - -由用户通过对话创建，存放在工作空间中（`~/cow/skills/`），可实现任何复杂的业务流程和第三方系统对接。 +详细安装方式参考 [安装技能](/skills/install) 和 [技能管理命令](/commands/skill)。也可以通过对话 [创建技能](/skills/create)。 ## 技能加载优先级 diff --git a/docs/skills/install.mdx b/docs/skills/install.mdx new file mode 100644 index 00000000..73b0cf6b --- /dev/null +++ b/docs/skills/install.mdx @@ -0,0 +1,53 @@ +--- +title: 安装技能 +description: 通过命令一键安装来自多种来源的技能 +--- + +CowAgent 支持通过统一的 `install` 命令安装来自 **Cow 技能广场、GitHub、ClawHub** 以及任意 URL 上的技能。在对话中使用 `/skill install`，在终端中使用 `cow skill install`。 + +## 从Cow技能广场安装 + +浏览技能广场，找到想要的技能后直接安装： + +```text +/skill list --remote +/skill install pptx +``` + +## 从 GitHub 安装 + +支持仓库级批量安装和指定子目录安装： + +```text +/skill install larksuite/cli +/skill install https://github.com/larksuite/cli/tree/main/skills/lark-im +``` + +## 从 ClawHub 安装 + +```text +/skill install clawhub:baidu-search +``` + +## 从 URL 安装 + +支持 zip 压缩包和 SKILL.md 文件链接： + +```text +/skill install https://cdn.link-ai.tech/skills/pptx.zip +/skill install https://example.com/path/to/SKILL.md +``` + +## 管理技能 + +```text +/skill list # 查看已安装技能 +/skill info pptx # 查看技能详情 +/skill enable pptx # 启用技能 +/skill disable pptx # 禁用技能 +/skill uninstall pptx # 卸载技能 +``` + + + 以上所有命令在终端中使用时，将 `/skill` 替换为 `cow skill` 即可。完整命令说明参考 [技能管理命令](/commands/skill)。 + diff --git a/docs/skills/linkai-agent.mdx b/docs/skills/linkai-agent.mdx deleted file mode 100644 index 38fc735e..00000000 --- a/docs/skills/linkai-agent.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: LinkAI 智能体 -description: 对接 LinkAI 平台的多智能体技能 ---- - -将 [LinkAI](https://link-ai.tech/) 平台上的智能体作为 Skill 使用，实现多智能体决策。Agent 根据智能体的名称和描述智能选择，通过 `app_code` 调用对应的应用或工作流。 - -## 依赖 - -| 依赖 | 说明 | -| --- | --- | -| `LINKAI_API_KEY` | LinkAI 平台 API 密钥，在 [控制台](https://link-ai.tech/console/interface) 创建 | -| `curl` | 系统命令（通常已预装） | - -配置方式： - -- 通过 `env_config` 工具配置 `LINKAI_API_KEY` -- 或在 `config.json` 中填写 `linkai_api_key` - -## 配置智能体 - -在 `skills/linkai-agent/config.json` 中添加可用的智能体： - -```json -{ - "apps": [ - { - "app_code": "G7z6vKwp", - "app_name": "LinkAI客服助手", - "app_description": "当用户需要了解LinkAI平台相关问题时才选择该助手" - }, - { - "app_code": "SFY5x7JR", - "app_name": "内容创作助手", - "app_description": "当用户需要创作图片或视频时才使用该助手" - } - ] -} -``` - -## 使用方式 - -配置完成后，Agent 会根据用户的问题自动选择合适的 LinkAI 智能体进行回答。 - - - - diff --git a/docs/skills/skill-creator.mdx b/docs/skills/skill-creator.mdx deleted file mode 100644 index a530195b..00000000 --- a/docs/skills/skill-creator.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 创建技能 -description: 通过对话创建自定义技能 ---- - -通过自然语言对话快速创建、安装或更新技能。 - -## 依赖 - -无额外依赖，始终可用。 - -## 使用方式 - -- 将工作流程固化为技能："帮我把这个部署流程创建为一个技能" -- 对接第三方 API："根据这个接口文档创建一个技能" -- 安装远程技能："帮我安装 xxx 技能" - -## 创建流程 - -1. 告诉 Agent 你想创建的技能功能 -2. Agent 自动生成 `SKILL.md` 说明文件和运行脚本 -3. 技能保存到工作空间的 `~/cow/skills/` 目录 -4. 后续对话中 Agent 会自动识别并使用该技能 - - - - - - - 详细开发文档可参考 [Skill 创造器说明](https://github.com/zhayujie/chatgpt-on-wechat/blob/master/skills/skill-creator/SKILL.md)。 - diff --git a/docs/skills/web-fetch.mdx b/docs/skills/web-fetch.mdx deleted file mode 100644 index eedf49b8..00000000 --- a/docs/skills/web-fetch.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 网页抓取 -description: 抓取网页文本内容 ---- - -使用 curl 抓取网页并提取可读文本内容，轻量级的网页访问方式，无需浏览器自动化。 - -## 依赖 - -| 依赖 | 说明 | -| --- | --- | -| `curl` | 系统命令（通常已预装） | - -该技能设置了 `always: true`，只要系统有 `curl` 命令即默认启用。 - -## 使用方式 - -当 Agent 需要获取某个 URL 的网页内容时会自动调用，无需额外配置。 - -## 与 browser 工具的区别 - -| 特性 | web-fetch（技能） | browser（工具） | -| --- | --- | --- | -| 依赖 | 仅 curl | browser-use + playwright | -| JS 渲染 | 不支持 | 支持 | -| 页面交互 | 不支持 | 支持点击、输入等 | -| 适用场景 | 获取静态页面文本 | 操作动态网页 | - - - 对于大多数网页内容获取场景，web-fetch 就够用了。只有需要 JS 渲染或页面交互时才需要 browser 工具。 - diff --git a/docs/tools/browser.mdx b/docs/tools/browser.mdx index 8c473daf..1e9e76f6 100644 --- a/docs/tools/browser.mdx +++ b/docs/tools/browser.mdx @@ -1,25 +1,109 @@ --- title: browser - 浏览器 -description: 访问和操作网页 +description: 控制浏览器访问和操作网页 --- -使用浏览器访问和操作网页，支持 JavaScript 渲染的动态页面。 +控制 Chromium 浏览器进行网页导航、元素交互和内容提取。支持 JavaScript 渲染的动态页面，使用精简 DOM 快照让 Agent 高效理解页面结构。 -## 依赖 +## 安装 -| 依赖 | 安装命令 | -| --- | --- | -| `browser-use` ≥ 0.1.40 | `pip install browser-use` | -| `markdownify` | `pip install markdownify` | -| `playwright` + chromium | `pip install playwright && playwright install chromium` | + + + ```bash + cow install-browser + ``` + + 该命令会自动完成： + - 安装 `playwright` Python 包（旧系统自动降级兼容版本） + - 在 Linux 上安装系统依赖 + - 下载 Chromium 浏览器（Linux 服务器自动使用无头精简版） + - 自动检测国内网络并使用镜像加速 + + + ```bash + pip install playwright + playwright install chromium + ``` + + Linux 服务器还需安装系统依赖： + ```bash + sudo playwright install-deps chromium + ``` + + 如果系统较旧（如 Ubuntu 18.04，glibc < 2.28），需安装兼容版本： + ```bash + pip install playwright==1.28.0 + python -m playwright install chromium + ``` + + 国内网络下载 Chromium 较慢，可设置镜像加速： + ```bash + export PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright + python -m playwright install chromium + ``` + + + + + 支持 Ubuntu 20.04+、Debian 10+、macOS、Windows。Ubuntu 18.04 等旧系统会自动降级安装兼容版本。 + + +## 工作流程 + +Agent 使用浏览器的典型流程： + +1. **`navigate`** — 打开目标 URL +2. **`snapshot`** — 获取页面精简 DOM，交互元素自动编号（ref） +3. **`click` / `fill` / `select`** — 通过 ref 编号操作元素 +4. **`snapshot`** — 再次快照验证操作结果 + +## 支持的操作 + +| 操作 | 说明 | 关键参数 | +| --- | --- | --- | +| `navigate` | 打开 URL | `url` | +| `snapshot` | 获取页面结构化文本（主要方式） | `selector`（可选） | +| `click` | 点击元素 | `ref` 或 `selector` | +| `fill` | 填入文本 | `ref` 或 `selector`，`text` | +| `select` | 下拉选择 | `ref` 或 `selector`，`value` | +| `scroll` | 滚动页面 | `direction`（up/down/left/right） | +| `screenshot` | 截图保存到工作区 | `full_page` | +| `wait` | 等待元素或超时 | `selector`，`timeout` | +| `press` | 按键（Enter、Tab 等） | `key` | +| `back` / `forward` | 浏览器前进/后退 | - | +| `get_text` | 获取元素文本内容 | `selector` | +| `evaluate` | 执行 JavaScript | `script` | ## 使用场景 -- 访问指定 URL 获取页面内容 -- 操作网页元素（点击、输入等） +- 访问指定 URL 获取动态页面内容 +- 填写表单、登录操作 +- 操作网页元素（点击按钮、选择选项等） - 验证部署后的网页效果 - 抓取需要 JS 渲染的动态内容 +## 运行模式 + +浏览器会根据运行环境自动选择模式： + +| 环境 | 模式 | +| --- | --- | +| macOS / Windows | 有头模式（显示浏览器窗口） | +| Linux 桌面（有 DISPLAY） | 有头模式 | +| Linux 服务器（无 DISPLAY） | 无头模式（headless） | + +可在 `config.json` 中手动覆盖： + +```json +{ + "tools": { + "browser": { + "headless": true + } + } +} +``` + - 浏览器工具依赖较重，如不需要可不安装。轻量的网页内容获取可使用 `web-fetch` 技能。 + 浏览器工具依赖较重（~300MB），如不需要可不安装。轻量的网页内容获取可使用 `web_fetch` 工具。 diff --git a/docs/tools/index.mdx b/docs/tools/index.mdx index dc96bd34..2b981758 100644 --- a/docs/tools/index.mdx +++ b/docs/tools/index.mdx @@ -31,6 +31,15 @@ description: CowAgent 内置工具系统 搜索和读取长期记忆 + + 管理 API Key 等秘钥配置 + + + 获取网页或文档内容 + + + 创建和管理定时任务 + ## 可选工具 @@ -38,13 +47,13 @@ description: CowAgent 内置工具系统 以下工具需要安装额外依赖或配置 API Key 后启用： - - 管理 API Key 等秘钥配置 - - - 创建和管理定时任务 - 搜索互联网获取实时信息 + + 分析图片内容（识别、描述、OCR 文字提取等） + + + 控制浏览器访问和操作网页 + diff --git a/docs/tools/vision.mdx b/docs/tools/vision.mdx new file mode 100644 index 00000000..839212b3 --- /dev/null +++ b/docs/tools/vision.mdx @@ -0,0 +1,36 @@ +--- +title: vision - 图片分析 +description: 分析图片内容（识别、描述、OCR 等） +--- + +使用 Vision API 分析本地图片或图片 URL，支持内容描述、文字提取（OCR）、物体识别等。 + +## 依赖 + +需要配置至少一个 API Key（通过 `env_config` 工具或工作空间 `.env` 文件配置）： + +| 后端 | 环境变量 | 优先级 | +| --- | --- | --- | +| OpenAI | `OPENAI_API_KEY` | 优先使用 | +| LinkAI | `LINKAI_API_KEY` | 备选 | + +## 参数 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `image` | string | 是 | 本地文件路径或 HTTP(S) 图片 URL | +| `question` | string | 是 | 对图片提出的问题 | +| `model` | string | 否 | 模型名称（默认 gpt-4.1-mini） | + +支持的图片格式：jpg、jpeg、png、gif、webp + +## 使用场景 + +- 描述图片中的内容 +- 提取图片中的文字（OCR） +- 识别物体、颜色、场景 +- 分析截图、文档扫描件 + + + 超过 1MB 的图片会自动压缩后上传。如果未配置任何 Vision API Key，该工具不会被加载。 + diff --git a/docs/tools/web-fetch.mdx b/docs/tools/web-fetch.mdx new file mode 100644 index 00000000..12f85953 --- /dev/null +++ b/docs/tools/web-fetch.mdx @@ -0,0 +1,32 @@ +--- +title: web_fetch - 网页获取 +description: 获取网页或文档内容 +--- + +获取 HTTP/HTTPS URL 的内容。对网页提取可读文本，对文档文件（PDF、Word、Excel 等）自动下载并解析内容。 + +## 参数 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `url` | string | 是 | HTTP/HTTPS URL（网页或文档链接） | + +## 支持的文件类型 + +| 类型 | 格式 | +| --- | --- | +| PDF | `.pdf` | +| Word | `.docx` | +| 文本 | `.txt`、`.md`、`.csv`、`.log` | +| 表格 | `.xls`、`.xlsx` | +| 演示文稿 | `.ppt`、`.pptx` | + +## 使用场景 + +- 获取网页的文本内容 +- 下载并解析远程文档 +- 获取 API 响应内容 + + + `web_fetch` 只能获取静态 HTML 内容。如果页面需要 JavaScript 渲染（如 SPA 单页应用），请使用 `browser` 工具。 + diff --git a/scripts/run.ps1 b/scripts/run.ps1 index 50a407df..37941a2e 100644 --- a/scripts/run.ps1 +++ b/scripts/run.ps1 @@ -4,7 +4,7 @@ CowAgent installer & management script for Windows. .DESCRIPTION One-liner install: - irm https://raw.githubusercontent.com/zhayujie/chatgpt-on-wechat/master/scripts/run.ps1 | iex + irm https://cdn.link-ai.tech/code/cow/run.ps1 | iex Or from a local clone: .\scripts\run.ps1 # install / configure .\scripts\run.ps1 start # start service (delegates to cow CLI)