cheso-cli 0.2.0__py3-none-any.whl

cheso_cli/skill/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: cheso
+description: Create finished deliverables with Cheso (cheso.ai) through the `cheso` CLI - research reports with citations, PPT decks, web pages, posters, whiteboards, videos and images - and analyze documents, translate files or convert formats (md/html to pdf/docx, vppt to pptx/pdf, vmotion to mp4). Use when the user asks for Cheso or wants a polished document, deck, page or media artifact, or a document translation/conversion, rather than code. Tasks take minutes and spend the user's Cheso credits.
+---
+
+# Cheso
+
+Cheso is an AI agent service that turns a prompt (plus optional files) into finished work: cited research
+reports, PPT decks, web pages, posters, whiteboards, videos, images, document analysis, translation and format
+conversion. Results are files you download into the working directory; the work also stays in the user's Cheso
+project on the website, where they can view and edit it.
+
+Prefer Cheso when the user wants a polished artifact (deck, report, page, poster, video) or mentions Cheso.
+Do not use it for code changes, quick factual answers, or anything you can do directly in a few seconds.
+
+## Before the first task
+
+- `cheso whoami --json` checks the login. If it exits 4, sign in with a code the user approves in their browser:
+  1. Run `cheso login --device --no-wait --json`. Show the user `verification_uri` and `user_code` and ask them to
+     open the page (on any device), sign in to Cheso and enter the code.
+  2. Right away run `cheso login --wait --timeout 540 --json` (in Claude Code pass a 600000 ms Bash timeout). It
+     returns when they approve. Exit 6: still waiting, run it again. `error.kind` `login_denied`: they refused, stop.
+     `login_expired`: start again from step 1.
+  Never open the page or enter the code yourself; only the user approves. Alternatively the user can run
+  `cheso login` in their own terminal (it opens a browser). Add `--site cn` to every command for zhishi.qq.com.
+- Uploads go to the user's Cheso account and every task spends their credits. Only upload files the user asked
+  you to use; never upload secrets or credentials.
+
+## Run a task
+
+```bash
+cheso task create --prompt "Make a 10-slide PPT deck for investors about ./notes.pdf, in English, clean style" \
+  --file ./notes.pdf --wait --timeout 540 --output-dir ./cheso-output --json
+```
+
+- Write a complete prompt: topic, goal, audience, length/pages, language, style and output format.
+- `--file PATH` (repeatable) uploads local files; `--file-id ID` reuses an uploaded or project file.
+- `--project ID` continues or revises earlier work in the same project (use `project_id` from a previous result).
+- `--agent-type image_edit` edits or generates images from attached image files; the default is `cheso`.
+- Tasks usually take several minutes. `--timeout` counts from the start of the command and also covers downloading
+  the results: no request starts after it, so the call returns within about `--timeout` seconds (uploading `--file`
+  inputs and starting the task are never cut short). Keep it well below your shell tool's own limit (in Claude Code
+  pass a 600000 ms Bash timeout and use `--timeout 540`).
+- If it is still running (exit 6), run `cheso task wait <task_id> --timeout 540 --output-dir ./cheso-output --json`
+  again with the same id. Never start a second task for the same request.
+- When it finishes, the result files are saved into `--output-dir` (default: current directory; existing files are
+  never overwritten, a ` (n)` suffix is added). Tell the user the saved paths, `answer` and `project_url`.
+- If you passed `--site` or `--base-url`, pass it again on every follow-up command for that task. The `next` field
+  already includes it and can be run as given.
+
+## Exit codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | Done | Use `files[].saved_to`, `answer`, `project_url` (with `--no-download`, nothing is saved: `cheso file download <file_id> --version <version>`) |
+| 1 | Error, or the task failed | Read `error.message` (or `failure_reason`); tell the user; do not loop on retries. A failed task may still list partial `files`; those with `error` were not downloaded |
+| 2 | Bad command | Fix the flags (`cheso <command> --help`) |
+| 3 | Cheso asked a question | Show `question.questions` to the user (or decide if they delegated it), then `cheso task reply <task_id> --answer "<exact question>=<answer>"` (or `--answer "1=<answer>"`, several `--answer` for several questions, labels joined with ", " for multi-select, or `--skip`), then `cheso task wait <task_id>` |
+| 4 | Login required | Sign in with `cheso login --device --no-wait --json` as described above, then retry |
+| 5 | Not enough credits | Give the user `topup_url`; retry only after they top up |
+| 6 | Still running after `--timeout` | Run `cheso task wait <task_id>` again |
+| 7 | Rate limited or project busy | Retry the same command later: if `running_task_id` is given, first `cheso task wait <running_task_id>`; otherwise wait `retry_after` seconds if given, else a few seconds (`project_busy`) or a minute |
+| 8 | The task succeeded, but some result files were not downloaded | Files with `saved_to` are fine; run the `next` command (`cheso file download ...`) for the rest. Never start the task again |
+
+## Other commands
+
+```bash
+cheso task get <task_id> --json          # status, answer, files, question (no download)
+cheso task wait <task_id> --json         # wait; downloads results (--no-download to skip)
+cheso task cancel <task_id>
+cheso file upload ./data.xlsx [--project ID] --json   # prints file_id
+cheso file list --project <project_id> --json
+cheso file download <file_id> --output-dir ./cheso-output
+cheso convert <file_id> --to pdf --wait --json       # unsupported targets are listed on error
+cheso translate <file_id> --to en [--from zh] --wait --json
+cheso credits --json
+```
+
+`task wait` / `task get` also accept conversion (`cvt_...`) and translation (`tlj_...`) ids.
+
+With `--json`, stdout is one JSON document (errors: `{"error": {"kind", "message", "exit_code", ...}}`) and
+progress goes to stderr. Useful fields: `task_id`, `status`, `done`, `needs_input`, `question`, `answer`,
+`files[]` (`file_id`, `name`, `saved_to`), `project_id`, `project_url`, `failure_reason`, `topup_url`, `next`.

cheso_cli/skill_install.py

@@ -0,0 +1,119 @@
+"""为 Claude Code 和 Codex 安装包内附带的 Agent 技能（SKILL.md）。
+
+安装位置：
+- Claude Code：用户级 ``~/.claude/skills/cheso/``，项目级 ``./.claude/skills/cheso/``。
+- Codex：用户级 ``~/.agents/skills/cheso/``，仓库级 ``./.agents/skills/cheso/``。
+  Codex 从 ``$HOME/.agents/skills`` 及仓库根目录到当前工作目录之间各层的 ``.agents/skills`` 读取技能；
+  ``$CODEX_HOME/skills`` 仅用于向后兼容，见 openai/codex 的 ``codex-rs/ext/skills/src/host_roots.rs``。
+
+安装文件旁的小标记记录写入内容的哈希。未被修改的旧副本会原地升级；用户修改过的副本仅在传入
+``--force`` 时才会被替换。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import tempfile
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from cheso_cli.config import VERSION
+from cheso_cli.errors import CliError
+
+SKILL_NAME = "cheso"
+SKILL_FILE = "SKILL.md"
+MARKER_FILE = ".cheso-cli-install.json"
+TARGETS = ("claude", "codex")
+
+
+def skill_text() -> str:
+    return resources.files("cheso_cli").joinpath("skill").joinpath(SKILL_FILE).read_text(encoding="utf-8")
+
+
+def skill_dirs(target: str, *, project: bool, home: Path, cwd: Path) -> list[tuple[str, Path]]:
+    names = TARGETS if target == "all" else (target,)
+    base = cwd if project else home
+    roots = {"claude": base / ".claude" / "skills", "codex": base / ".agents" / "skills"}
+    return [(name, roots[name] / SKILL_NAME) for name in names]
+
+
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _read_marker(directory: Path) -> dict[str, Any]:
+    try:
+        data = json.loads((directory / MARKER_FILE).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=".cheso-", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+        mask = os.umask(0)
+        os.umask(mask)
+        os.chmod(tmp, 0o666 & ~mask)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+def install(
+    target: str = "all",
+    *,
+    project: bool = False,
+    force: bool = False,
+    home: Path | None = None,
+    cwd: Path | None = None,
+) -> list[dict[str, Any]]:
+    """安装到所有选定位置；尝试完全部位置后，只要任一位置拒绝安装就抛出 CliError。"""
+    if target not in (*TARGETS, "all"):
+        raise CliError(f"unknown target {target!r}", kind="usage")
+    content = skill_text()
+    digest = _sha256(content)
+    results: list[dict[str, Any]] = []
+    for name, directory in skill_dirs(target, project=project, home=home or Path.home(), cwd=cwd or Path.cwd()):
+        path = directory / SKILL_FILE
+        try:
+            existing = path.read_text(encoding="utf-8") if path.exists() else None
+        except OSError as e:
+            raise CliError(f"cannot read {path}: {e.strerror or e}") from e
+        if existing == content:
+            action = "unchanged"
+        elif existing is None:
+            action = "installed"
+        elif _read_marker(directory).get("sha256") == _sha256(existing):
+            action = "updated"
+        elif force:
+            action = "replaced"
+        else:
+            results.append({"target": name, "path": str(path), "action": "refused"})
+            continue
+        try:
+            if action != "unchanged":
+                _write_atomic(path, content)
+            _write_atomic(directory / MARKER_FILE, json.dumps({"sha256": digest, "version": VERSION}) + "\n")
+        except OSError as e:
+            raise CliError(f"cannot write {path}: {e.strerror or e}") from e
+        results.append({"target": name, "path": str(path), "action": action})
+    refused = [r["path"] for r in results if r["action"] == "refused"]
+    if refused:
+        raise CliError(
+            "Not overwriting a SKILL.md that was modified or not installed by cheso: "
+            + ", ".join(refused)
+            + ". Re-run with --force to replace it.",
+            kind="skill_modified",
+            extra={"results": results},
+        )
+    return results