mini-agent-cli 0.2.0__py3-none-any.whl

mini_agent/skills.py

@@ -0,0 +1,138 @@
+"""Agent Skills：一个目录 + SKILL.md，和 Claude Code / Codex / opencode 同一个格式。
+
+    <name>/SKILL.md     frontmatter 写 name + description，正文是给模型的流程
+    <name>/其他文件      脚本、模板、参考资料。正文里让模型用 bash / read 去用它们
+
+启动时只把 name + description 放进 system prompt；模型觉得用得上，
+才调 skill(name) 把正文读进来。装 100 个 skill 的成本是 100 行描述，不是 100 篇正文。
+
+查找目录（同名先到先得，所以项目的覆盖全局的）：
+    项目：从当前目录往上到 git 根目录，每层的 .agents/skills、.claude/skills、.opencode/skills
+    全局：~/.config/mini-agent/skills、~/.agents/skills、~/.claude/skills、~/.config/opencode/skills
+    内置：mini_agent/skills（mini-agent 自己的几个，比如改配置）
+
+单独跑可以看装了哪些：uv run python -m mini_agent.skills
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import project_dirs
+
+PROJECT_SUBDIRS = (".agents/skills", ".claude/skills", ".opencode/skills")
+GLOBAL_DIRS = ("~/.config/mini-agent/skills", "~/.agents/skills", "~/.claude/skills", "~/.config/opencode/skills")
+BUILTIN_DIR = Path(__file__).resolve().parent / "skills"
+FALSE = {"false", "no", "0", "off"}
+CATALOG_DESC_LIMIT = 160
+
+
+def skill_dirs():
+    project = [d / sub for d in reversed(project_dirs()) for sub in PROJECT_SUBDIRS]
+    return [p for p in [*project, *(Path(g).expanduser() for g in GLOBAL_DIRS), BUILTIN_DIR] if p.is_dir()]
+
+
+def parse_front_matter(text):
+    """--- 包起来的 key: value，外加 YAML 的 > / | 多行块。
+
+    嵌套和列表不支持（缩进的子键直接忽略）—— 不值得为它引一个 yaml 依赖。
+    """
+    if not text.startswith("---"):
+        return {}, text
+    _, _, rest = text.partition("\n")
+    block, separator, body = rest.partition("\n---")
+    if not separator:
+        return {}, text
+
+    meta, block_key, joiner = {}, None, " "
+    for line in block.splitlines():
+        indented = line[:1] in (" ", "\t")
+        if block_key and (indented or not line.strip()):
+            meta[block_key] = (meta[block_key] + joiner + line.strip()).strip()
+            continue
+        block_key = None
+        key, sep, value = line.partition(":")
+        if not sep or indented:
+            continue
+        value = value.strip()
+        if value in (">", "|", ">-", "|-", ">+", "|+"):
+            block_key, joiner = key.strip(), "\n" if value[0] == "|" else " "
+            meta[block_key] = ""
+        else:
+            meta[key.strip()] = value.strip("\"'")
+    return meta, body.partition("\n")[2].lstrip("\n")
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    body: str
+    directory: Path
+
+    def render(self):
+        # 带上目录绝对路径：正文里写 scripts/x.sh 时，模型得知道相对的是哪儿
+        return f"# skill: {self.name}\n（skill 目录：{self.directory}，正文里的相对路径都相对它）\n\n{self.body}"
+
+
+def load_skills(directories=None):
+    """返回 ({name: Skill}, 跳过原因)。坏掉的 skill 只是少一个，不影响启动。"""
+    skills, notes, seen = {}, [], set()
+    for root in directories or skill_dirs():
+        for child in sorted(root.iterdir()):
+            manifest = child / "SKILL.md"
+            if not manifest.is_file() or child.name in seen:
+                continue
+            seen.add(child.name)
+            try:
+                meta, body = parse_front_matter(manifest.read_text(encoding="utf-8"))
+            except OSError as error:
+                notes.append(f"{child.name}：读不了（{error}）")
+                continue
+            name = meta.get("name") or child.name
+            if any(str(meta.get(k, "")).lower() in FALSE for k in ("enabled", "active", "isActive")):
+                notes.append(f"{name}：已关闭")
+            elif not meta.get("description"):
+                notes.append(f"{name}：没写 description，模型不知道什么时候用它")
+            else:
+                skills.setdefault(name, Skill(name, meta["description"], body, child.resolve()))
+    return skills, notes
+
+
+def _clip(text, limit=CATALOG_DESC_LIMIT):
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[:limit] + "…"
+
+
+def catalog(skills):
+    """注入 system prompt 的清单。正文一个字都不在这儿。"""
+    if not skills:
+        return ""
+    lines = "\n".join(f"- {s.name}：{_clip(s.description)}" for s in skills.values())
+    return ("\n\n## Skills\n动手之前先看有没有匹配的 skill，有就先调 skill 工具读出流程再照着做：\n" + lines)
+
+
+SKILL_SCHEMA = {
+    "name": "skill",
+    "description": "读取一个 skill 的完整流程。开始任务前，如果 Skills 清单里有匹配的，先调这个。",
+    "parameters": {
+        "type": "object",
+        "properties": {"name": {"type": "string", "description": "skill 名字，必须来自清单"}},
+        "required": ["name"],
+    },
+}
+
+
+def main():
+    skills, notes = load_skills()
+    print("目录：\n" + "\n".join(f"  {d}" for d in skill_dirs()) + "\n")
+    print(f"skill {len(skills)} 个：")
+    for s in skills.values():
+        print(f"  {s.name:<24} {_clip(s.description, 60)}")
+    if notes:
+        print(f"\n跳过的（{len(notes)} 个）：")
+        for note in notes:
+            print(f"  {note}")
+
+
+if __name__ == "__main__":
+    main()

mini_agent/tools.py

@@ -0,0 +1,137 @@
+"""内置工具。只管干活，要不要先问用户由 agent.py 按 permission 决定。
+
+awk / sed / jq 这类不单独做工具 —— bash 里直接用，模型比我们更熟它们的参数。
+grep / glob 单独做，是因为它们只读、不用每次问，而 bash 每次都要问。
+"""
+
+import difflib
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+READ_LINES = 2000
+MAX_LINE = 2000        # 单行超过这么长就截断（压缩过的 js 之类）
+SEARCH_LIMIT = 200     # grep / glob 最多返回这么多条
+SKIP_DIRS = {".git", "node_modules", ".venv", "__pycache__", "dist", "build", ".next", "target"}
+
+
+def bash(command, timeout=120):
+    try:
+        result = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        return f"命令超过 {timeout} 秒未结束，已终止。"
+    output = (result.stdout + result.stderr).strip()
+    return output or f"(无输出，退出码 {result.returncode})"
+
+
+def read(path, offset=1, limit=READ_LINES):
+    lines = Path(path).expanduser().read_text(encoding="utf-8", errors="replace").splitlines()
+    start = max(offset, 1) - 1
+    chunk = lines[start:start + limit]
+    out = "\n".join(f"{i:>6}\t{line[:MAX_LINE]}" for i, line in enumerate(chunk, start + 1))
+    if start + limit < len(lines):
+        out += f"\n…（共 {len(lines)} 行，用 offset={start + limit + 1} 继续读）"
+    return out or "(空文件)"
+
+
+def write(path, content):
+    target = Path(path).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    return f"已写入 {path}（{len(content.splitlines())} 行）"
+
+
+def edit(path, old_string, new_string, replace_all=False):
+    target = Path(path).expanduser()
+    text = target.read_text(encoding="utf-8")
+    count = text.count(old_string)
+    if count == 0:
+        return "错误：old_string 在文件里找不到，先 read 确认原文（注意缩进和空白）"
+    if count > 1 and not replace_all:
+        return f"错误：old_string 出现了 {count} 次，多带几行上下文让它唯一，或者设 replace_all=true"
+    target.write_text(text.replace(old_string, new_string), encoding="utf-8")
+    return f"已修改 {path}（替换 {count if replace_all else 1} 处）"
+
+
+def grep(pattern, path=".", glob=None, ignore_case=False):
+    """有 ripgrep 用 ripgrep，没有就退回 grep -rn。"""
+    if shutil.which("rg"):
+        cmd = ["rg", "-n", "--no-heading", "--max-columns", "300", pattern, path]
+        cmd[1:1] = ["-i"] * ignore_case + (["-g", glob] if glob else [])
+    else:
+        cmd = ["grep", "-rnE", *(["-i"] * ignore_case), *(f"--exclude-dir={d}" for d in SKIP_DIRS),
+               *([f"--include={glob}"] if glob else []), pattern, path]
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+    if result.returncode > 1:
+        return f"错误：{result.stderr.strip()}"
+    lines = result.stdout.splitlines()
+    more = f"\n…（共 {len(lines)} 条，只显示前 {SEARCH_LIMIT} 条，缩小范围再搜）" if len(lines) > SEARCH_LIMIT else ""
+    return "\n".join(lines[:SEARCH_LIMIT]) + more if lines else "(没有匹配)"
+
+
+def glob(pattern, path="."):
+    """按修改时间倒序，最近改过的在前。"""
+    root = Path(path).expanduser()
+    hits = [p for p in root.glob(pattern) if not SKIP_DIRS & set(p.relative_to(root).parts)]
+    hits.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    more = f"\n…（共 {len(hits)} 个，只显示前 {SEARCH_LIMIT} 个）" if len(hits) > SEARCH_LIMIT else ""
+    return "\n".join(str(p) for p in hits[:SEARCH_LIMIT]) + more if hits else "(没有匹配)"
+
+
+def preview(name, args, max_lines=40):
+    """write / edit 审批时给人看的 diff。"""
+    path = Path(args.get("path", "")).expanduser()
+    old = path.read_text(encoding="utf-8", errors="replace") if path.is_file() else ""
+    if name == "write":
+        new = args.get("content", "")
+    else:
+        count = -1 if args.get("replace_all") else 1
+        new = old.replace(args.get("old_string", ""), args.get("new_string", ""), count)
+    diff = list(difflib.unified_diff(old.splitlines(), new.splitlines(), str(path), str(path), lineterm="", n=2))
+    if len(diff) > max_lines:
+        diff = diff[:max_lines] + [f"…（diff 共 {len(diff)} 行）"]
+    return "\n".join(diff) or "(内容没有变化)"
+
+
+TOOLS = {f.__name__: f for f in (bash, read, write, edit, grep, glob)}
+
+
+def _schema(name, description, properties, required):
+    return {"name": name, "description": description,
+            "parameters": {"type": "object", "properties": properties, "required": required}}
+
+
+_PATH = {"type": "string", "description": "文件路径，相对工作目录或绝对路径"}
+
+TOOL_SCHEMAS = [
+    _schema("bash", "执行 shell 命令（zsh/bash），返回 stdout+stderr。每次都是新进程，cd 不会保留。"
+            "适合 git、构建、测试、awk/sed/jq 等。只读的搜索优先用 grep / glob。", {
+                "command": {"type": "string"},
+                "timeout": {"type": "integer", "description": "秒，默认 120"},
+            }, ["command"]),
+    _schema("read", f"读文本文件，带行号。默认从第 1 行读 {READ_LINES} 行，大文件用 offset 分段。", {
+        "path": _PATH,
+        "offset": {"type": "integer", "description": "起始行号，从 1 开始"},
+        "limit": {"type": "integer", "description": "读多少行"},
+    }, ["path"]),
+    _schema("write", "创建或整体覆盖文件。改已有文件优先用 edit。", {
+        "path": _PATH, "content": {"type": "string", "description": "完整内容"},
+    }, ["path", "content"]),
+    _schema("edit", "精确字符串替换。old_string 必须和原文一字不差（含缩进）且唯一；read 输出里的行号前缀不是原文。", {
+        "path": _PATH,
+        "old_string": {"type": "string"},
+        "new_string": {"type": "string"},
+        "replace_all": {"type": "boolean", "description": "替换全部出现，默认 false"},
+    }, ["path", "old_string", "new_string"]),
+    _schema("grep", "按正则搜文件内容，返回 文件:行号:内容。", {
+        "pattern": {"type": "string", "description": "正则"},
+        "path": {"type": "string", "description": "目录或文件，默认当前目录"},
+        "glob": {"type": "string", "description": "只搜匹配的文件，如 *.py"},
+        "ignore_case": {"type": "boolean"},
+    }, ["pattern"]),
+    _schema("glob", "按通配符找文件，如 **/*.py，最近修改的在前。", {
+        "pattern": {"type": "string"},
+        "path": {"type": "string", "description": "从哪个目录开始，默认当前目录"},
+    }, ["pattern"]),
+]

mini_agent_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.3
+Name: mini-agent-cli
+Version: 0.2.0
+Summary: 终端里的编码 Agent：配置驱动，支持 OpenAI Chat / Responses 与 Anthropic 协议、MCP、Agent Skills
+Keywords: agent,llm,mcp,cli,coding-agent,skills
+Author: zhaomo08
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Dist: mcp>=2.1.1
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/zhaomo08/mini-agent
+Description-Content-Type: text/markdown
+
+# mini-agent
+
+终端里的编码 Agent，面向会写配置的开发者。模型、MCP、权限都写在一个 `mini-agent.json` 里，
+skill 用和 Claude Code / Codex / opencode 相同的 `SKILL.md` 格式。唯一的依赖是 `mcp`。
+
+```
+Agent = LLM + 工具 + 循环
+```
+
+## 安装
+
+三种方式任选，装完都是 `mini-agent` 命令。需要先有 [uv](https://docs.astral.sh/uv/)（`curl -LsSf https://astral.sh/uv/install.sh | sh` 或 `brew install uv`），它会自动准备 Python 3.13：
+
+```bash
+uv tool install mini-agent-cli        # PyPI（包名带 -cli，命令是 mini-agent）
+npm i -g @zhaomo08/mini-agent         # npm（启动器，内部用 uvx 跑同版本的 PyPI 包）
+uvx --from mini-agent-cli mini-agent  # 不安装，直接跑
+```
+
+首次运行会把包里的 `mini-agent.example.json` 复制到 `~/.config/mini-agent/mini-agent.json`，改这份就行。
+
+开发时用 `uv tool install -e .`，改代码即时生效。
+
+## 使用
+
+```bash
+mini-agent                                  # 交互模式，在哪个目录启动就在哪干活
+mini-agent -p "这个仓库是干什么的" > out.md   # 问一句就退出；stdout 只有答案，思考和工具进度走 stderr
+mini-agent -m bailian-anthropic/qwen3.8-flash
+mini-agent --yes                            # ask 类操作全部放行（deny 仍然禁止）
+```
+
+| 命令 | 作用 |
+|---|---|
+| `/model [provider/model]` | 查看或切换模型。对话保留，可以跨厂商、跨协议 |
+| `/reload` | 重新读配置、skills、MCP，对话保留 |
+| `/img [路径]` | 挂一张图，不带路径从剪贴板取；也可以直接把图片文件拖进来 |
+| `/clear` `/tools` `/help` | |
+| Ctrl+C | 回答中：打断这一轮（包括审批提示）；输入时：清空当前行 |
+| Ctrl+D / `exit` | 退出 |
+
+输出是流式的，思考过程以灰色显示。
+
+## 配置：mini-agent.json
+
+完整带注释的示例见 [mini_agent/mini-agent.example.json](mini_agent/mini-agent.example.json)。
+
+| 位置 | 作用 |
+|---|---|
+| `~/.config/mini-agent/mini-agent.json` | 全局（`$MINI_AGENT_CONFIG` 可改） |
+| 项目里的 `mini-agent.json` | 从 git 根目录到当前目录逐层深度合并，越近优先级越高 |
+
+```jsonc
+{
+  "model": "deepseek/deepseek-flash",
+  "provider": {
+    "deepseek": { "api": "openai-chat", "baseURL": "https://api.deepseek.com", "apiKey": "{env:DEEPSEEK_API_KEY}" }
+  },
+  "mcp": {
+    "memory": { "type": "local",  "command": ["npx", "-y", "@modelcontextprotocol/server-memory"] },
+    "amap":   { "type": "remote", "url": "https://mcp.amap.com/mcp?key={env:AMAP_MAPS_API_KEY}" }
+  },
+  "permission": { "bash": "ask", "edit": "ask", "external": "ask", "mcp": "ask" }
+}
+```
+
+**协议**（`api` 字段），baseURL 的写法和各家 SDK 一致：
+
+| api | 请求 | baseURL 示例 |
+|---|---|---|
+| `openai-chat` | `POST {baseURL}/chat/completions` | `https://api.deepseek.com` |
+| `openai-responses` | `POST {baseURL}/responses` | `https://api.openai.com/v1` |
+| `anthropic` | `POST {baseURL}/v1/messages` | `https://api.anthropic.com` |
+
+`options` 原样并进请求体（`enable_thinking`、`max_tokens`、`temperature`…），
+`models.<id>.options` 只对某个模型生效。密钥写 `{env:变量名}`；配置文件支持整行 `//` 注释。
+
+**让模型改配置**：直接说「加一个 xxx MCP」。内置的 `mini-agent-config` skill 会引导模型
+用 edit 改文件、校验 JSON，然后你输入 `/reload` 就生效。
+
+## 工具
+
+| 工具 | 说明 | 权限类别 |
+|---|---|---|
+| `bash` | 执行命令；awk / sed / jq 都走它 | `bash` |
+| `read` | 带行号，默认 2000 行，`offset` 分段 | 工作目录外归 `external` |
+| `write` / `edit` | 整体写入 / 精确字符串替换，确认时显示 diff | `edit` |
+| `grep` | 有 ripgrep 就用 ripgrep，没有就用 grep -rn | 工作目录外归 `external` |
+| `glob` | 按通配符找文件，最近修改的在前 | 工作目录外归 `external` |
+| `skill` | 按需读取 skill 正文 | — |
+| MCP 工具 | 名字以 create / delete / send / run … 开头的 | `mcp` |
+
+权限：`ask` 先问，`allow` 直接放行，`deny` 禁止。非交互模式（管道或 `-p`）下没加 `--yes` 时，ask 一律按拒绝处理。
+
+## Skills
+
+一个目录加一个 `SKILL.md`（frontmatter 写 `name`、`description`），脚本和参考资料放在同一目录，
+正文里让模型用 bash / read 去调用。启动时只把描述放进 system prompt，正文由模型按需读取。
+
+查找顺序，同名的先找到先用：
+
+1. 项目：从当前目录往上到 git 根目录，每层的 `.agents/skills`、`.claude/skills`、`.opencode/skills`
+2. 全局：`~/.config/mini-agent/skills`、`~/.agents/skills`、`~/.claude/skills`、`~/.config/opencode/skills`
+3. 内置：`mini_agent/skills/`
+
+## 中途换模型
+
+参考 pi-ai 的 cross-provider handoff 设计。历史用中立格式保存，每条 assistant 消息都记着它是由哪个协议、哪个模型产生的：
+
+- **同一个模型产生的**：原样回放协议原文，thinking 签名、加密 reasoning 都不会丢
+- **其他模型产生的**：只用中立字段重建。thinking 转成 `<thinking>` 文本，签名丢弃，
+  工具调用 id 规范成 `[A-Za-z0-9_-]{1,64}`（Anthropic 的要求）
+- **中断后留下的"有调用没结果"的工具调用**：补一条占位结果，保证每家接口都接受这段历史
+
+## 上下文预算
+
+- 工具结果超过 3 万字符就截断
+- 只有最新一条消息保留图片
+- 历史超过 40 万字符，就从最旧的一轮开始整轮丢弃
+
+## 代码
+
+```
+mini_agent/
+  __main__.py  命令行 / REPL        agent.py   装配、权限、循环、上下文预算
+  config.py    配置加载与合并        llm.py     三种协议，标准库 urllib
+  tools.py     内置工具              mcp.py     MCP 连接
+  skills.py    skill 发现与加载      images.py  剪贴板 / 文件 → 多模态
+test_agent.py  不调模型的自检：uv run python test_agent.py
+```
+
+排查用：`uv run python -m mini_agent.mcp`、`uv run python -m mini_agent.skills`。
+
+早期的教学版（step1–3、extras/）在 git 历史里：`git show c619ecb`。
+
+## 发布
+
+版本号要在三个地方保持一致：`pyproject.toml`、`npm/package.json` 和 git tag。推送 tag 后，由
+`.github/workflows/release.yml` 依次完成：检查版本号 → 自检 → 验证 wheel 能装 → 发布 PyPI → 发布 npm。
+两边都用 Trusted Publishing（OIDC），仓库里不存任何 token。
+
+```bash
+# 改好两处 version 之后
+git tag v0.2.1 && git push origin v0.2.1
+```

mini_agent_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+mini_agent/__init__.py,sha256=elfF6MIaCV0bQsVcJEGpfFL1t6-dy-QxshITqDcrwzE,529
+mini_agent/__main__.py,sha256=YVV3pks_W3IYo8QODLVwtoUjA1hHsWvL1HgozhXW9L0,6368
+mini_agent/agent.py,sha256=eD-GHLCWXIoBdNqPcgc0xcbkqd7ASjp4V52iz7j2flM,12140
+mini_agent/config.py,sha256=W-VsYdwoIShYKCErJHdlqQ3-g2ratatjJG0IxMxbWyc,2709
+mini_agent/images.py,sha256=rz2krDAReKJRLlNrVxvyCtQ7nt7h0_U3v0ii4JxMH1Q,4800
+mini_agent/llm.py,sha256=7zo5OH7WW9kAV0YZycSzPuXvl2sxAzFJGo4Lis4V4Lk,15328
+mini_agent/mcp.py,sha256=wX8tzPj1VmDeJGP9Zcqef0HmTgXyZVLP86sTaXBZzmM,3095
+mini_agent/mini-agent.example.json,sha256=tB_8QOS2y93N1b6dl-vz1ITiUPmO7ctldOw7yeCnxrM,3095
+mini_agent/skills/mini-agent-config/SKILL.md,sha256=M1XocEwS3VRAE_08bsmC0PQwmr-mWcGmCkNgz6QjkPM,2028
+mini_agent/skills.py,sha256=1tyE4WqwT8pLleCxXJYFQmPKLmU3VN3edySKdCvfjQI,5490
+mini_agent/tools.py,sha256=e2rKyWQgX-9iwQABhuOt-9WnzvtimfL2LZFZFqiFiJU,6800
+mini_agent_cli-0.2.0.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
+mini_agent_cli-0.2.0.dist-info/entry_points.txt,sha256=sEuFhw0cBJk-JDwSo5DQLK6fS_r6t3-cibeXPYg7DP4,57
+mini_agent_cli-0.2.0.dist-info/METADATA,sha256=bFxDySrfsuryaOD-vJP_raeY8L3X2nBbOoiMZgjpqCU,7220
+mini_agent_cli-0.2.0.dist-info/RECORD,,

mini_agent_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.19
+Root-Is-Purelib: true
+Tag: py3-none-any

mini_agent_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mini-agent = mini_agent.__main__:main
+