qi-coding-agent 0.1.0__py3-none-any.whl

qi_agent/loader.py

@@ -0,0 +1,299 @@
+"""内容装载器(P2):agent 目录发现(两层)、agent.md/技能解析、校验、import。
+
+对齐 design/agent-config-design.md §3/§6/§10:
+- 位置: ~/.qi/agents + <项目>/.qi/agents + 包内置 qi_agent/builtin/agents
+- 优先级: 项目 > 用户 > 内置(静默覆盖);同层重复报错
+- 校验: name==目录名 / description 非空 / tools 存在 / include 存在 / 技能同名冲突
+- import: 与装载共用同一校验器;明文凭证扫描
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import yaml
+
+from . import paths
+from .models import Skill
+from .settings import (
+    QiSettings,
+    load_settings_by_scope,
+    settings_exclude_paths,
+    settings_include_paths,
+)
+
+AGENT_FILE = "agent.md"
+SKILL_FILE = "SKILL.md"
+ASSETS_DIR = "assets"
+SKILLS_DIR = "skills"
+# Agent Skills 标准的跨工具目录(~/.agents/skills、.agents/skills);
+# 不对应单一工具,见 design/agent-config-design.md。
+CROSS_TOOL_DIR = ".agents"
+SYSTEM_FILE_NAME = "SYSTEM.md"  # 基座提示词覆盖文件
+
+_PLAINTEXT_KEY_RE = re.compile(
+    r'("?(?:api[_-]?key|password|secret|access_token|auth_config)"?\s*[:=]\s*["\'])([^"\']{6,})'
+    r'|(["\']Bearer\s+)([A-Za-z0-9._~+/=-]{12,})',
+    re.IGNORECASE,
+)
+
+
+class LoadError(Exception):
+    pass
+
+
+def split_frontmatter(text: str) -> tuple[dict, str]:
+    """解析 '---' 包裹的 YAML frontmatter + 正文。"""
+    if not text.startswith("---"):
+        return {}, text
+    lines = text.splitlines()
+    end = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end = i
+            break
+    if end is None:
+        return {}, text
+    meta = yaml.safe_load("\n".join(lines[1:end])) or {}
+    body = "\n".join(lines[end + 1 :]).strip()
+    return (meta if isinstance(meta, dict) else {}), body
+def _skill_from_file(skill_file: Path, *, fallback_name: str, source: str) -> Skill | None:
+    """从 SKILL.md(或根级 *.md)读出一个技能;frontmatter 无 description 时返回 None。"""
+    try:
+        meta, _body = split_frontmatter(skill_file.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, yaml.YAMLError):
+        return None
+    desc = str(meta.get("description") or "").strip()
+    if not desc:
+        return None
+    name = str(meta.get("name") or fallback_name)
+    return Skill(name=name, description=desc, path=skill_file, source=source)
+
+
+def scan_skills(agent_dir: Path, source: str = "") -> list[Skill]:
+    """agent 自带技能:`<agent_dir>/skills/<name>/SKILL.md`(单层,同名报错)。"""
+    skills: dict[str, Skill] = {}
+    label = source or f"agent:{agent_dir.name}"
+    skills_root = agent_dir / SKILLS_DIR
+    if skills_root.is_dir():
+        for skill_dir in sorted(skills_root.iterdir()):
+            skill_file = skill_dir / SKILL_FILE
+            if not skill_file.is_file():
+                continue
+            meta, _body = split_frontmatter(skill_file.read_text(encoding="utf-8"))
+            name = meta.get("name") or skill_dir.name
+            desc = str(meta.get("description", "")).strip()
+            if name in skills:
+                raise LoadError(f"{skill_file}:技能 {name!r} 在 {agent_dir} 内重复")
+            skills[name] = Skill(name=name, description=desc or "(无描述)",
+                                 path=skill_file, source=label)
+    return list(skills.values())
+
+
+def scan_skill_root(root: Path, *, label: str, out: list[Skill],
+                    allow_root_md: bool = True) -> None:
+    """递归扫描一个技能根(对齐 pi):
+
+      - 含 SKILL.md 的目录即技能,**不再向内递归**
+      - 无 SKILL.md 的子目录继续向内找(支持分组目录)
+      - `allow_root_md` 时,根下带 description 的 `*.md` 也算独立技能
+    """
+    if root.is_file():
+        if root.suffix == ".md":
+            skill = _skill_from_file(root, fallback_name=root.stem, source=label)
+            if skill:
+                out.append(skill)
+        return
+    if not root.is_dir():
+        return
+
+    def walk(directory: Path, *, is_root: bool) -> None:
+        try:
+            children = sorted(directory.iterdir())
+        except OSError:
+            return
+        for child in children:
+            if child.is_dir():
+                nested = child / SKILL_FILE
+                if nested.is_file():
+                    skill = _skill_from_file(nested, fallback_name=child.name, source=label)
+                    if skill:
+                        out.append(skill)
+                    continue          # 已是技能,不再向内递归
+                walk(child, is_root=False)
+            elif is_root and allow_root_md and child.suffix == ".md":
+                skill = _skill_from_file(child, fallback_name=child.stem, source=label)
+                if skill:
+                    out.append(skill)
+
+    walk(root, is_root=True)
+
+
+def _skill_layer_entries(cwd: Path,
+                         scopes: dict[str, QiSettings],
+                         ) -> list[tuple[Path, str, bool]]:
+    """构造技能层列表(低 → 高);`scopes` 必须是各作用域**各自**的设置。"""
+    entries: list[tuple[Path, str, bool]] = [
+        (Path.home() / CROSS_TOOL_DIR / SKILLS_DIR, "agents-global", False),
+        (paths.global_home() / SKILLS_DIR, "qi-global", True),
+    ]
+    entries += [(p, "settings-global", True)
+                for p in settings_include_paths(scopes.get("user"), "user", "skills", cwd)]
+    for ancestor in reversed(paths.project_context_ancestors(cwd)):   # 远 → 近
+        entries.append((ancestor / CROSS_TOOL_DIR / SKILLS_DIR, "agents-project", False))
+    entries.append((paths.project_home(cwd) / SKILLS_DIR, "qi-project", True))
+    entries += [(p, "settings-project", True)
+                for p in settings_include_paths(scopes.get("project"), "project", "skills", cwd)]
+    return entries
+
+
+def top_level_skill_dirs(cwd: Path | None = None,
+                         settings: QiSettings | None = None,
+                         ) -> list[tuple[Path, str, bool]]:
+    """顶层技能根的完整优先级顺序(低 → 高),返回 (目录, 层标签, 允许根级 md)。
+
+    对齐 pi 的发现规则,并叠上 qi 的私有层:
+
+      1. `~/.agents/skills`            跨工具共享(全局,永远视为已信任)
+      2. `~/.qi/agent/skills`          qi 全局私有
+      3. user settings 的 `skills[]`    追加路径(相对 `~/.qi/agent`)
+      4. `.agents/skills`(cwd→git 根,远→近)  跨工具共享(项目,需信任)
+      5. `<git根>/.qi/skills`          qi 项目私有
+      6. project settings 的 `skills[]` 追加路径(相对 `<git根>/.qi`)
+
+    同一标签内的同名技能视为冲突(报错);跨标签同名则高优先级静默覆盖。
+    `settings` 参数只为兼容旧调用保留 —— 两个作用域的 `skills[]` 一律从各自的
+    原始文件读取,因为相对路径必须按各自所在目录解析。
+    """
+    del settings           # 保留参数以兼容调用方;实际按作用域各读各的
+    root = Path(cwd) if cwd else Path.cwd()
+    return _skill_layer_entries(root, load_settings_by_scope(root))
+
+
+def load_top_level_skills(cwd: Path | None = None,
+                          settings: QiSettings | None = None,
+                          extra_paths: list[Path] | None = None,
+                          enabled: bool = True) -> list[Skill]:
+    """装载顶层技能(低 → 高覆盖);`extra_paths`(CLI `--skill`)最高优先。
+
+    `enabled=False` 时跳过目录发现,但仍装载 extra_paths —— 对齐 pi 的
+    `--no-skills`:`--skill <path>` 在禁用发现时依然生效。
+
+    来源取值见 `top_level_skill_dirs`;返回值按优先级从低到高,可见项在后。
+
+    `settings` 只为兼容旧调用保留(实际按作用域各读各的)。
+    """
+    merged: dict[str, Skill] = {}
+    labels: dict[str, str] = {}          # 技能名 → 已占用的层标签
+    root = Path(cwd) if cwd else Path.cwd()
+    scopes = load_settings_by_scope(root)
+    # 排除项(`!pat` / `-pat`)作用于**整个发现集**,不只是数组里纳入的根
+    excludes: list[Path] = []
+    for scope in ("user", "project"):
+        for path in settings_exclude_paths(scopes.get(scope), scope, "skills", root):
+            if path not in excludes:
+                excludes.append(path)
+
+    def excluded(skill: Skill) -> bool:
+        return any(skill.path == ex or ex in skill.path.parents for ex in excludes)
+
+    def add(skill: Skill) -> None:
+        if excluded(skill):
+            return
+        owner = labels.get(skill.name)
+        if owner is not None and owner == skill.source:
+            raise LoadError(
+                f"技能名 {skill.name!r} 在 {skill.source} 层重复(冲突文件:{skill.path})"
+            )
+        if owner is not None:
+            merged.pop(skill.name, None)      # 高优先级覆盖低优先级
+        labels[skill.name] = skill.source
+        merged[skill.name] = skill
+
+    if enabled:
+        for layer_root, label, allow_root_md in _skill_layer_entries(root, scopes):
+            found: list[Skill] = []
+            scan_skill_root(layer_root, label=label, out=found, allow_root_md=allow_root_md)
+            for skill in found:
+                add(skill)
+
+    for raw in (extra_paths or []):
+        found = []
+        scan_skill_root(Path(raw).expanduser(), label="cli", out=found, allow_root_md=True)
+        for skill in found:
+            add(skill)
+
+    return list(merged.values())
+def system_file_candidates(cwd: Path | None = None) -> list[tuple[Path, str]]:
+    """可能的 SYSTEM.md 路径,按优先级从高到低返回 (文件, 来源)。"""
+    return [
+        (paths.project_home(cwd) / SYSTEM_FILE_NAME, "project"),
+        (paths.global_home() / SYSTEM_FILE_NAME, "user"),
+    ]
+
+
+def resolve_base_prompt(cwd: Path | None = None) -> tuple[str, str]:
+    """解析**自定义**基座,返回 `(文本, 来源说明)`;来源取值 `project|user|builtin`。
+
+    文本为空串表示没有自定义基座 —— 调用方改用代码内默认
+    (`system_prompt.default_base_prompt()`),所以基座层永不为空。
+    空文件/读取失败视为未配置,继续往下一层找(不会静默降级成空提示词)。
+    """
+    for path, source in system_file_candidates(cwd):
+        if not path.is_file():
+            continue
+        try:
+            text = path.read_text(encoding="utf-8").strip()
+        except (OSError, UnicodeDecodeError):
+            continue
+        if text:
+            return text, f"{source}:{path}"
+    return "", "builtin"
+
+
+# ── 项目上下文(AGENTS.md / CLAUDE.md,对齐 pi 的 project_context)────
+#
+# 每级目录按候选顺序取**第一个**命中的文件(顺序照搬 pi);全局(agent 目录)在最前,
+# 项目祖先链由远到近追加 —— 近者可覆盖远者的同义约定。
+# 与 pi 的两点差异:祖先链止于 **git 根**(qi 的 project_context_ancestors 约定,
+# 与 .agents/skills 的继承范围一致;pi 一路走到文件系统根),空文件视为未配置。
+
+CONTEXT_FILE_NAMES = ("AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD")
+
+
+def load_context_file_from_dir(directory: Path) -> tuple[Path, str] | None:
+    """目录内按候选顺序取第一个 AGENTS/CLAUDE 文件;空文件/读失败视为没有。"""
+    for name in CONTEXT_FILE_NAMES:
+        path = directory / name
+        try:
+            if not path.is_file():
+                continue
+            text = path.read_text(encoding="utf-8").strip()
+        except (OSError, UnicodeDecodeError):
+            continue
+        if text:
+            return path, text
+    return None
+
+
+def load_project_context(cwd: Path | None = None) -> list[tuple[Path, str]]:
+    """项目上下文文件 `(路径, 正文)`:全局 → 远祖先 → 近祖先(含 cwd);按路径去重。"""
+    out: list[tuple[Path, str]] = []
+    seen: set[Path] = set()
+
+    def take(directory: Path) -> None:
+        found = load_context_file_from_dir(directory)
+        if found is None:
+            return
+        key = found[0].resolve(strict=False)
+        if key in seen:
+            return
+        seen.add(key)
+        out.append(found)
+
+    take(paths.global_home())
+    for ancestor in reversed(paths.project_context_ancestors(cwd)):   # 远 → 近
+        take(ancestor)
+    return out

qi_agent/model_catalog.py

@@ -0,0 +1,108 @@
+"""从 provider 的 OpenAI 兼容 `/models` 端点拉模型列表(给 `qi init --refresh`)。
+
+**为什么需要它**:`presets.py` 里那张表是**种子** —— 离线可用、带核过的 `contextWindow` /
+`maxTokens`,但**模型 id 会漂**(上新 / 下线 / 改名)。实测例子:DeepSeek 把
+`deepseek-v4-flash` 换成了 `deepseek-flash`(V4.1 Flash,旧名仍路由到新模型)——
+这种变更只能靠厂商公告或接口,写死的表迟早落后一拍。所以另给一条**从接口拉**的路。
+
+全部国产 provider 都提供 OpenAI 兼容的 `GET {baseUrl}/models`(返回 `{"data": [{"id": …}]}`),
+拿同一个 API key 鉴权即可。这里**不做网络以外的猜测**:接口返回什么 id 就用什么 id;
+`contextWindow` / `maxTokens` 接口不返回,新加进来的条目先用 qi 的默认值(要精确就照厂商文档补)。
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+#: 一次刷新的超时(秒)。厂商的 /models 通常几十毫秒,20s 只用于兜住挂死的网络。
+DEFAULT_TIMEOUT = 20.0
+
+
+class CatalogError(Exception):
+    """拉取失败(网络 / HTTP 状态 / 返回体不是预期的形状)。"""
+
+
+def models_url(base_url: str) -> str:
+    """`baseUrl` → `/models` 端点。
+
+    规则就是拼一个 `/models`:各家的 OpenAI 兼容前缀都直接支持 ——
+    `https://api.deepseek.com` → `/models`,`…/compatible-mode/v1` → `/compatible-mode/v1/models`。
+
+    **只认 http(s)** —— `baseUrl` 来自用户的 `models.json`,与其它配置同信任域,但
+    `urlopen` 遇到 `file://` 会去读本地文件,那种“靠配置读盘”的口子不值得留
+    (`ftp://` / `data:` 同理)。写错了就报错,不静默换个东西去读。
+    """
+    url = base_url.rstrip("/") + "/models"
+    if not url.lower().startswith(("http://", "https://")):
+        raise CatalogError(f"baseUrl 必须是 http(s),拿到的是:{base_url!r}")
+    return url
+
+
+def model_ids_from_payload(payload: Any) -> list[str]:
+    """从 `/models` 的返回体里取模型 id(去重、保序)。
+
+    认三种形状:OpenAI 的 `{"data": [{"id": …}]}`、裸列表 `[{…}]`、以及
+    `{"data": ["id", …]}`(少数网关直接给字符串)。取不到就抛 `CatalogError`
+    —— 不静默返回空列表(那会让人以为“厂商没有模型”)。
+    """
+    items = payload.get("data") if isinstance(payload, dict) else payload
+    if not isinstance(items, list):
+        raise CatalogError("返回体里没有 `data` 列表")
+    ids: list[str] = []
+    for item in items:
+        if isinstance(item, dict):
+            value = item.get("id") or item.get("model")
+        else:
+            value = item
+        text = str(value or "").strip()
+        if text and text not in ids:
+            ids.append(text)
+    if not ids:
+        raise CatalogError("返回体里没有任何模型 id")
+    return ids
+
+
+def fetch_model_ids(base_url: str, api_key: str | None, *,
+                    timeout: float = DEFAULT_TIMEOUT) -> list[str]:
+    """`GET {baseUrl}/models` 并取出模型 id。失败一律抛 `CatalogError`。
+
+    只读、需要网络:**只由显式的 `qi init --refresh` 调用** —— qi 的启动路径不做任何网络请求。
+    """
+    if not base_url:
+        raise CatalogError("这个 provider 没有 baseUrl,拉不了模型列表")
+    url = models_url(base_url)          # 顺带把非 http(s) 的 baseUrl 挡在外面
+    request = urllib.request.Request(url, headers={"Accept": "application/json"})  # noqa: S310
+    if api_key:
+        request.add_header("Authorization", f"Bearer {api_key}")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 URL 已过 scheme 检查
+            raw = response.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as exc:
+        hint = "API key 不对或没权限" if exc.code in (401, 403) else exc.reason
+        raise CatalogError(f"{url} 返回 HTTP {exc.code}({hint})") from exc
+    except (urllib.error.URLError, OSError) as exc:
+        raise CatalogError(f"连不上 {url}: {exc}") from exc
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CatalogError(f"{url} 返回的不是 JSON") from exc
+    return model_ids_from_payload(payload)
+
+
+def merge_model_ids(entry: dict[str, Any], ids: list[str]) -> tuple[list[str], list[str]]:
+    """把接口来的 id 并进 provider 段(`entry` 原地改),返回 `(新增, 本地有但接口没返回)`。
+
+    **只加不删**:厂商的 `/models` 有可能只列你**有权限**的模型、或者干脆列不全,
+    所以本地多出来的条目保留(调用方可以提示用户,但不替他删配置)。
+    新加的条目只写 `id` —— `contextWindow` / `maxTokens` 走 qi 的默认值,
+    要精确就照厂商文档在 `models.json` 里补(或让 `--preset` 的种子覆盖它)。
+    """
+    models: list[Any] = entry.setdefault("models", [])
+    existing = [str(m.get("id")) for m in models if isinstance(m, dict) and m.get("id")]
+    added = [model_id for model_id in ids if model_id not in set(existing)]
+    for model_id in added:
+        models.append({"id": model_id})
+    return added, [model_id for model_id in existing if model_id not in ids]

qi_agent/models.py

@@ -0,0 +1,103 @@
+"""核心数据模型:Skill / Message / 事件 / 工具结果。
+
+角色相关类型(AgentConfig / AgentUnit / DataSource / McpServerSpec)随 P-E4c 移出 core ——
+它们属于 qi-agents / qi-mcp(E1.1/E15)。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str          # 进 system prompt(渐进披露)
+    path: Path                # SKILL.md 位置(用时 read 全文)
+    source: str = ""          # 来源标签(诊断用:qi-global / agents-project / agent …)
+
+
+@dataclass
+@dataclass
+@dataclass
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    args: dict
+
+
+# 工具执行状态(ToolOutcome.status)
+TOOL_OK = "ok"
+TOOL_ERROR = "error"
+
+
+@dataclass
+class ToolOutcome:
+    """一次工具执行的**结构化**结果。
+
+    前端渲染工具卡片(status 点、耗时、退出码)只依赖这些字段,不再靠解析 `result`
+    字符串前缀。`result` 保留为**模型可见文本**,与旧版 `execute()` 的返回值逐字一致,
+    因此模型行为不变。
+
+    `duration_ms` 由 AgentRunner 统一计时,工具自己不必上报。
+    需要上报退出码的进程型工具(bash)返回本对象;其余工具继续返回 `str` 即可,
+    由 AgentRunner 包成 `ok`。
+    """
+
+    status: str = TOOL_OK               # ok | error
+    result: str = ""                    # 模型可见文本
+    duration_ms: int = 0
+    exit_code: int | None = None        # 仅进程型工具有意义
+    error: str | None = None            # 机器可读原因: unknown_tool|tool_error|exception|timeout|denied
+    details: dict | None = None         # 给**客户端**看的自由结构;不进 LLM 上下文
+
+    # `details` 是插件与 UI 之间**唯一的**下行通道(见 design/web.md §16)。
+    # 为什么需要它:`result` 是给模型看的散文,UI 不该去解析它;而
+    # status/duration_ms/exit_code 只够画一个状态点,画不了插件自己的东西
+    # (todo 清单、查询结果、进度……)。给它一个开放字典,宿主就不必为每个插件改接口。
+    #
+    # 约定:想画结构化 UI 时放 `details["ui"]`,词汇表见 design/web.md §16.2;
+    # 不认识 `ui` 的客户端会退回"折叠显示原始 JSON",所以**永不会白屏或报错**。
+
+    @property
+    def ok(self) -> bool:
+        return self.status == TOOL_OK
+
+
+@dataclass
+class Message:
+    role: str                       # user | assistant | tool
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_call_id: str | None = None
+    agent_id: str | None = None
+
+
+@dataclass
+class AgentEvent:
+    kind: str                       # agent_start|text_delta|assistant_message|tool_start|tool_end|text|agent_end|dispatch|opening|error
+    agent: str | None = None
+    tool: str | None = None
+    text: str = ""
+    data: dict = field(default_factory=dict)
+
+    # 事件 data 的字段约定(消费者据此渲染,不必解析 text):
+    #   text_delta → 逐字增量(在 text 上;Web 端打字靠它。CLI/TUI 只读回合末尾的 text 事件)
+    #   assistant_message → 每轮 LLM 回复完成一次;{"step": int, "tool_calls": [名字]}。
+    #                 宣布了工具调用的那条属于"过程"(runtime 落成 custom entry),
+    #                 不带工具调用的那条才是最终回答(落成 message entry);也供轨迹视图分段
+    #   tool_start → {"args": {...}}
+    #   tool_end   → {"status": "ok|error", "duration_ms": int,
+    #                 "exit_code": int|None, "error": str|None}
+    #   agent_end  → {"messages": [...], "usage": {"prompt_tokens": int,
+    #                 "completion_tokens": int, "total_tokens": int,
+    #                 "llm_calls": int, "turns": int}}
+    #   dispatch   → {"confidence", "source", "agent", "display_name", "reasoning"}
+    #   opening    → {"suggestions": [...]}
+    #
+    # 顺序不变量:一轮里 text_delta* 与 tool_start/tool_end 按**真实发生顺序**穿插
+    # (工具调用之间的叙述不再丢弃)。消费端不得把所有 text_delta 提到开头、
+    # 把所有工具行推到末尾 —— 那样会失去因果顺序。