ai302 0.1.0__tar.gz

ai302-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# --- Secrets / local config ---
+.env
+.env.*
+*.env
+*.key
+*.pem
+*.p12
+*.pfx
+*.crt
+*.cer
+*.der
+*.jks
+credentials.json
+secrets*.json
+*secret*
+*token*
+
+# Local user config produced by this CLI (default: ~/.ai302)
+# Kept here in case user overrides AI302_CONFIG_DIR into the repo
+.ai302/
+**/.ai302/
+**/history.jsonl
+**/tasks/
+**/config.json
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.pytype/
+.ruff_cache/
+.pyre/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Build / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDEs / editors
+.vscode/
+.idea/
+*.iml
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Claude Code / local tooling
+.claude/

ai302-0.1.0/AGENTS.md

@@ -0,0 +1,65 @@
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## Project-Specific Guidelines
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

ai302-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

ai302-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: ai302
+Version: 0.1.0
+Summary: 302.ai unified CLI
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# ai302 CLI
+
+302.ai 统一命令行工具（输出均为单行 JSON，方便脚本处理）。
+
+## Project architecture
+
+代码按职责拆分为三层：
+
+- `ai302/cli/`：Typer CLI 命令层（参数解析、统一 JSON 输出、写 history/快照）
+  - `ai302/cli/app.py`：CLI 根入口（挂载 model/video/image/tts/history 子命令）
+  - `ai302/cli/common.py`：公共工具（`resolve_api_key` / `print_json` / `parse_extra`）
+  - `ai302/cli/model.py`：默认模型配置（set/list）
+  - `ai302/cli/video.py`：视频异步任务（create/fetch）
+  - `ai302/cli/image.py`：图片同步生成（generate）
+  - `ai302/cli/tts.py`：TTS（refresh/providers/voices/create/fetch）
+  - `ai302/cli/history.py`：本地 history 查询（path/list）
+
+- `ai302/api/`：HTTP API 封装层（只负责请求/返回 JSON，不做 CLI 交互）
+  - `ai302/api/http_client.py`：httpx 客户端、重试、统一错误 `AI302ApiError`、Base URL（`AI302_BASE_URL`）
+  - `ai302/api/video.py`：视频 create/fetch 请求封装
+  - `ai302/api/image.py`：图片 generate 请求封装
+  - `ai302/api/tts.py`：TTS provider/create/fetch 请求封装
+
+- `ai302/core/`：本地能力层（配置/模型表/history/快照/缓存）
+  - `ai302/core/config.py`：本地配置读写（`$AI302_CONFIG_DIR/config.json`，默认模型等）
+  - `ai302/core/models.py`：内置 `SUPPORTED_MODELS` 静态表
+  - `ai302/core/history.py`：`history.jsonl` 追加与查询
+  - `ai302/core/task_store.py`：任务快照 `tasks/<taskid>.json` 写入/更新
+  - `ai302/core/tts_cache.py`：TTS providers 缓存读写与 voices 扁平化
+
+入口文件：
+- `ai302/__main__.py`：支持 `python -m ai302 ...`
+- `pyproject.toml`：安装后命令 `ai302 ...` 的脚本入口
+
+## Install (dev)
+
+```bash
+python -m pip install -U pip
+python -m pip install -e .
+```
+
+## Run (no install)
+
+```bash
+python -m ai302 -h
+```
+
+## Environment
+
+- API Key：`AI302_KEY`（也可以每次传 `--api_key`）
+- Base URL：`AI302_BASE_URL`（默认 `https://api.302.ai`）
+- Config dir：`AI302_CONFIG_DIR`（默认 `~/.ai302`）
+
+PowerShell:
+
+```powershell
+$env:AI302_KEY="YOUR_KEY"
+```
+
+## Models
+
+模型按任务类型分组：
+- 视频：`t2v` / `i2v`
+- 图片：`t2i` / `i2i`
+
+查看当前内置支持模型：
+
+```bash
+python -m ai302 model list t2v
+python -m ai302 model get t2v --random
+python -m ai302 model list t2i
+```
+
+设置默认模型（写入本地配置）：
+
+```bash
+ai302 model set t2v minimaxi-t2v-01
+ai302 model set i2v minimaxi-hailuo-2.3-fast
+ai302 model set t2i flux-kontext-max-t2i
+ai302 model set i2i wan2.6-image
+```
+
+## CLI status enums
+
+异步任务（video / tts）状态枚举固定为：
+- `pending`：准备/排队中
+- `processing`：处理中
+- `completed`：完成
+- `failed`：失败
+
+同步接口（image）只会返回：
+- `completed`：完成
+- `failed`：失败
+
+
+## Video
+
+视频模块提供 **异步视频生成任务**（text-to-video / image-to-video），支持创建任务与查询任务结果。
+
+创建任务：
+
+```bash
+ai302 video create --prompt "a cat run" --model minimaxi-t2v-01 --api_key "sk-..."
+```
+
+返回字段补充：`request` 会包含本次请求的 method/url/headers(仅脱敏 Authorization)/params/body。
+
+查询任务：
+
+```bash
+ai302 video fetch <taskid> --api_key "sk-..."
+# 使用 --short 仅返回关键状态和结果 URL
+ai302 video fetch <taskid> --short
+```
+
+## TTS
+
+首次使用建议先刷新 provider/model/voice 信息到本地缓存（会写入 `$AI302_CONFIG_DIR/tts/providers.json`）：
+
+```bash
+ai302 tts refresh --api_key "sk-..."
+```
+
+查看可用 provider：
+
+```bash
+ai302 tts providers
+ai302 tts providers-get --random
+```
+
+查看可用 voices（建议用 `--provider` 过滤）：
+
+```bash
+ai302 tts voices --provider openai
+ai302 tts voices-get openai --random
+```
+
+创建 TTS 任务（异步）：
+
+```bash
+ai302 tts create --text "生活就像海洋，只有意志坚强的人才能到达彼岸" --provider openai --voice alloy --api_key "sk-..."
+```
+
+返回字段补充：`request` 会包含本次请求的 method/url/headers(仅脱敏 Authorization)/params/body。
+
+查询任务结果：
+
+```bash
+ai302 tts fetch <taskid> --api_key "sk-..."
+# 使用 --short 仅返回关键状态和结果 URL
+ai302 tts fetch <taskid> --short
+```
+
+## Image (sync)
+
+同步生图：
+
+```bash
+ai302 image generate --prompt "sky city" --model flux-kontext-max-t2i --api_key "sk-..."
+```
+
+返回字段补充：`request` 会包含本次请求的 method/url/headers(仅脱敏 Authorization)/params/body。
+
+## Image (async)
+
+异步生图（创建任务）：
+
+```bash
+ai302 image create --prompt "sky city" --model flux-kontext-max-t2i --api_key "sk-..."
+```
+
+查询任务结果：
+
+```bash
+ai302 image fetch <taskid> --api_key "sk-..."
+# 使用 --short 仅返回关键状态和结果 URL
+ai302 image fetch <taskid> --short
+```
+
+图生图（可重复传 `--image`）：
+
+```bash
+ai302 image generate --prompt "添加墨镜" --image "https://..." --api_key "sk-..."
+## Task (YAML editor)
+
+默认目录：`ai302/templates/workspace/tasks`（文件名按时间倒序取最新的 `*.yaml`）。
+
+支持字段编辑、数组元素添加与移除，以及通过 `--path` 指定特定文件：
+
+```bash
+# 修改默认最新文件的字段
+ai302 task edit --set "workflow.steps[step=2].parameters.prompt=生成一只更可爱的小猫"
+
+# 指定特定文件进行编辑
+ai302 task edit --path "./tasks/my_task.yaml" --set "a=b"
+
+# 添加数组元素
+ai302 task edit --add "workflow.running_steps=Node_C"
+...
+```
+
+参数说明：
+- `--set`：设置值，支持 `+=`, `-=` 语法
+- `--add`：追加元素到数组
+- `--remove`：从数组移除元素
+- `--path`：指定要编辑的 YAML 文件路径（如果不提供，则自动寻找默认目录下最新的文件）
+
+# 或者使用 += 语法
+ai302 task edit --set "workflow.running_steps+=Node_C"
+
+# 移除数组元素 (支持精确值匹配)
+ai302 task edit --remove "workflow.pending_steps=Node_C"
+# 或者使用 -= 语法
+ai302 task edit --set "workflow.pending_steps-=Node_C"
+
+# 移除数组元素 (支持对象字段匹配)
+ai302 task edit --remove "workflow.steps=step=1"
+```
+
+`@json=` 用法：当值是数组/对象时，用 `@json` 让 CLI 把值按 JSON 解析，并写回为 YAML 的 **flow style**（数组 `[...]` / 对象 `{...}`）。
+
+- list：`depends_on@json=[1,3]` → `depends_on: [1, 3]`
+- object：`parameters.extra@json={"a":1,"b":[2,3]}` → `extra: {a: 1, b: [2, 3]}`
+
+路径语法：
+- dotted：`a.b.c=...`
+- 列表下标：`steps[0].parameters.prompt=...`
+- 列表筛选（按字段匹配）：`steps[step=2].parameters.prompt=...`
+
+运算符说明：
+- `=`：设置值（默认）
+- `+=`：向数组追加元素
+- `-=`：从数组中移除匹配的元素（值匹配或字段筛选匹配）
+
+## History / Local files
+
+- History（JSONL）：`$AI302_CONFIG_DIR/history.jsonl`
+- Video task snapshots：`$AI302_CONFIG_DIR/tasks/<taskid>.json`
+
+查看 history 路径：
+
+```bash
+ai302 history path
+```
+
+按条件查询（输出匹配的 jsonl 行）：
+
+```bash
+ai302 history list --kind video --op fetch --limit 20
+```

ai302-0.1.0/README.md

@@ -0,0 +1,250 @@
+# ai302 CLI
+
+302.ai 统一命令行工具（输出均为单行 JSON，方便脚本处理）。
+
+## Project architecture
+
+代码按职责拆分为三层：
+
+- `ai302/cli/`：Typer CLI 命令层（参数解析、统一 JSON 输出、写 history/快照）
+  - `ai302/cli/app.py`：CLI 根入口（挂载 model/video/image/tts/history 子命令）
+  - `ai302/cli/common.py`：公共工具（`resolve_api_key` / `print_json` / `parse_extra`）
+  - `ai302/cli/model.py`：默认模型配置（set/list）
+  - `ai302/cli/video.py`：视频异步任务（create/fetch）
+  - `ai302/cli/image.py`：图片同步生成（generate）
+  - `ai302/cli/tts.py`：TTS（refresh/providers/voices/create/fetch）
+  - `ai302/cli/history.py`：本地 history 查询（path/list）
+
+- `ai302/api/`：HTTP API 封装层（只负责请求/返回 JSON，不做 CLI 交互）
+  - `ai302/api/http_client.py`：httpx 客户端、重试、统一错误 `AI302ApiError`、Base URL（`AI302_BASE_URL`）
+  - `ai302/api/video.py`：视频 create/fetch 请求封装
+  - `ai302/api/image.py`：图片 generate 请求封装
+  - `ai302/api/tts.py`：TTS provider/create/fetch 请求封装
+
+- `ai302/core/`：本地能力层（配置/模型表/history/快照/缓存）
+  - `ai302/core/config.py`：本地配置读写（`$AI302_CONFIG_DIR/config.json`，默认模型等）
+  - `ai302/core/models.py`：内置 `SUPPORTED_MODELS` 静态表
+  - `ai302/core/history.py`：`history.jsonl` 追加与查询
+  - `ai302/core/task_store.py`：任务快照 `tasks/<taskid>.json` 写入/更新
+  - `ai302/core/tts_cache.py`：TTS providers 缓存读写与 voices 扁平化
+
+入口文件：
+- `ai302/__main__.py`：支持 `python -m ai302 ...`
+- `pyproject.toml`：安装后命令 `ai302 ...` 的脚本入口
+
+## Install (dev)
+
+```bash
+python -m pip install -U pip
+python -m pip install -e .
+```
+
+## Run (no install)
+
+```bash
+python -m ai302 -h
+```
+
+## Environment
+
+- API Key：`AI302_KEY`（也可以每次传 `--api_key`）
+- Base URL：`AI302_BASE_URL`（默认 `https://api.302.ai`）
+- Config dir：`AI302_CONFIG_DIR`（默认 `~/.ai302`）
+
+PowerShell:
+
+```powershell
+$env:AI302_KEY="YOUR_KEY"
+```
+
+## Models
+
+模型按任务类型分组：
+- 视频：`t2v` / `i2v`
+- 图片：`t2i` / `i2i`
+
+查看当前内置支持模型：
+
+```bash
+python -m ai302 model list t2v
+python -m ai302 model get t2v --random
+python -m ai302 model list t2i
+```
+
+设置默认模型（写入本地配置）：
+
+```bash
+ai302 model set t2v minimaxi-t2v-01
+ai302 model set i2v minimaxi-hailuo-2.3-fast
+ai302 model set t2i flux-kontext-max-t2i
+ai302 model set i2i wan2.6-image
+```
+
+## CLI status enums
+
+异步任务（video / tts）状态枚举固定为：
+- `pending`：准备/排队中
+- `processing`：处理中
+- `completed`：完成
+- `failed`：失败
+
+同步接口（image）只会返回：
+- `completed`：完成
+- `failed`：失败
+
+
+## Video
+
+视频模块提供 **异步视频生成任务**（text-to-video / image-to-video），支持创建任务与查询任务结果。
+
+创建任务：
+
+```bash
+ai302 video create --prompt "a cat run" --model minimaxi-t2v-01 --api_key "sk-..."
+```
+
+返回字段补充：`request` 会包含本次请求的 method/url/headers(仅脱敏 Authorization)/params/body。
+
+查询任务：
+
+```bash
+ai302 video fetch <taskid> --api_key "sk-..."
+# 使用 --short 仅返回关键状态和结果 URL
+ai302 video fetch <taskid> --short
+```
+
+## TTS
+
+首次使用建议先刷新 provider/model/voice 信息到本地缓存（会写入 `$AI302_CONFIG_DIR/tts/providers.json`）：
+
+```bash
+ai302 tts refresh --api_key "sk-..."
+```
+
+查看可用 provider：
+
+```bash
+ai302 tts providers
+ai302 tts providers-get --random
+```
+
+查看可用 voices（建议用 `--provider` 过滤）：
+
+```bash
+ai302 tts voices --provider openai
+ai302 tts voices-get openai --random
+```
+
+创建 TTS 任务（异步）：
+
+```bash
+ai302 tts create --text "生活就像海洋，只有意志坚强的人才能到达彼岸" --provider openai --voice alloy --api_key "sk-..."
+```
+
+返回字段补充：`request` 会包含本次请求的 method/url/headers(仅脱敏 Authorization)/params/body。
+
+查询任务结果：
+
+```bash
+ai302 tts fetch <taskid> --api_key "sk-..."
+# 使用 --short 仅返回关键状态和结果 URL
+ai302 tts fetch <taskid> --short
+```
+
+## Image (sync)
+
+同步生图：
+
+```bash
+ai302 image generate --prompt "sky city" --model flux-kontext-max-t2i --api_key "sk-..."
+```
+
+返回字段补充：`request` 会包含本次请求的 method/url/headers(仅脱敏 Authorization)/params/body。
+
+## Image (async)
+
+异步生图（创建任务）：
+
+```bash
+ai302 image create --prompt "sky city" --model flux-kontext-max-t2i --api_key "sk-..."
+```
+
+查询任务结果：
+
+```bash
+ai302 image fetch <taskid> --api_key "sk-..."
+# 使用 --short 仅返回关键状态和结果 URL
+ai302 image fetch <taskid> --short
+```
+
+图生图（可重复传 `--image`）：
+
+```bash
+ai302 image generate --prompt "添加墨镜" --image "https://..." --api_key "sk-..."
+## Task (YAML editor)
+
+默认目录：`ai302/templates/workspace/tasks`（文件名按时间倒序取最新的 `*.yaml`）。
+
+支持字段编辑、数组元素添加与移除，以及通过 `--path` 指定特定文件：
+
+```bash
+# 修改默认最新文件的字段
+ai302 task edit --set "workflow.steps[step=2].parameters.prompt=生成一只更可爱的小猫"
+
+# 指定特定文件进行编辑
+ai302 task edit --path "./tasks/my_task.yaml" --set "a=b"
+
+# 添加数组元素
+ai302 task edit --add "workflow.running_steps=Node_C"
+...
+```
+
+参数说明：
+- `--set`：设置值，支持 `+=`, `-=` 语法
+- `--add`：追加元素到数组
+- `--remove`：从数组移除元素
+- `--path`：指定要编辑的 YAML 文件路径（如果不提供，则自动寻找默认目录下最新的文件）
+
+# 或者使用 += 语法
+ai302 task edit --set "workflow.running_steps+=Node_C"
+
+# 移除数组元素 (支持精确值匹配)
+ai302 task edit --remove "workflow.pending_steps=Node_C"
+# 或者使用 -= 语法
+ai302 task edit --set "workflow.pending_steps-=Node_C"
+
+# 移除数组元素 (支持对象字段匹配)
+ai302 task edit --remove "workflow.steps=step=1"
+```
+
+`@json=` 用法：当值是数组/对象时，用 `@json` 让 CLI 把值按 JSON 解析，并写回为 YAML 的 **flow style**（数组 `[...]` / 对象 `{...}`）。
+
+- list：`depends_on@json=[1,3]` → `depends_on: [1, 3]`
+- object：`parameters.extra@json={"a":1,"b":[2,3]}` → `extra: {a: 1, b: [2, 3]}`
+
+路径语法：
+- dotted：`a.b.c=...`
+- 列表下标：`steps[0].parameters.prompt=...`
+- 列表筛选（按字段匹配）：`steps[step=2].parameters.prompt=...`
+
+运算符说明：
+- `=`：设置值（默认）
+- `+=`：向数组追加元素
+- `-=`：从数组中移除匹配的元素（值匹配或字段筛选匹配）
+
+## History / Local files
+
+- History（JSONL）：`$AI302_CONFIG_DIR/history.jsonl`
+- Video task snapshots：`$AI302_CONFIG_DIR/tasks/<taskid>.json`
+
+查看 history 路径：
+
+```bash
+ai302 history path
+```
+
+按条件查询（输出匹配的 jsonl 行）：
+
+```bash
+ai302 history list --kind video --op fetch --limit 20
+```

ai302-0.1.0/ai302/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

ai302-0.1.0/ai302/__main__.py

@@ -0,0 +1,5 @@
+from .cli.app import app
+
+
+if __name__ == "__main__":
+    app()