@tencent-rtc/trtc-agent-skills 0.1.3 → 0.1.4

package/skills/trtc-ai-service/scripts/lib/injector.py

@@ -0,0 +1,347 @@
+"""Execute / plan code injection per manifest injection point descriptions.
+
+The position field uses three unified formats (P2 standardized spec):
+    before:<function_name>     Insert before the specified function definition
+    after:<function_name>      Insert after the specified function definition
+    replace:<function_name>    Replace the specified function
+
+For cross-language compatibility, matching uses relaxed "line-level + function keyword" heuristics:
+    Python:    def func_name(...)        / class func_name(
+    JS/TS:     function func_name(... )  / func_name = (...) =>
+    Java:      \\bfunc_name\\s*\\(
+
+The skeleton conversation-core injection points are currently only declared in .py source,
+so this module's default implementation is Python-focused. Injection for other languages
+only returns "suggested patches" for the Agent to apply.
+
+API:
+    plan(injection_points, extensions, source_root) -> List[InjectionPlan]
+    apply_plans(plans, dry_run=True) -> List[ApplyResult]
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# 数据模型
+# ---------------------------------------------------------------------------
+@dataclass
+class InjectionPoint:
+    id: str
+    target: str          # 相对于骨架根的源文件路径
+    position: str        # before:xxx / after:xxx / replace:xxx
+    description: str = ""
+
+
+@dataclass
+class Extension:
+    inject_at: str           # 引用 InjectionPoint.id
+    code_template: str = ""  # 模板路径，相对能力包根
+    inline_code: str = ""    # 直接以字符串形式提供的代码
+    capability: str = ""     # 来源能力包名（拼装日志使用）
+
+
+@dataclass
+class InjectionPlan:
+    point: InjectionPoint
+    extension: Extension
+    target_abs_path: Path
+    op: str                  # before | after | replace
+    anchor: str              # 函数 / 类名
+    code: str                # 真正注入的代码片段
+    valid: bool = True
+    error: str = ""
+
+
+@dataclass
+class ApplyResult:
+    plan: InjectionPlan
+    applied: bool
+    dry_run: bool
+    diff_preview: str = ""
+    error: str = ""
+
+
+# ---------------------------------------------------------------------------
+# 解析
+# ---------------------------------------------------------------------------
+_POSITION_RE = re.compile(r"^(before|after|replace):(.+)$")
+
+
+def _parse_position(position: str) -> Optional[tuple]:
+    m = _POSITION_RE.match(position.strip())
+    if not m:
+        return None
+    return m.group(1), m.group(2).strip()
+
+
+def _load_template(capability_root: Path, ext: Extension) -> str:
+    if ext.inline_code:
+        return ext.inline_code
+    if ext.code_template:
+        p = capability_root / ext.code_template
+        if p.exists():
+            return p.read_text(encoding="utf-8")
+    return ""
+
+
+def plan(
+    skeleton_root: Path,
+    injection_points: List[Dict],
+    capabilities: List[tuple],
+) -> List[InjectionPlan]:
+    """构造注入计划。
+
+    Parameters
+    ----------
+    skeleton_root
+        conversation-core 根目录（用于解析 target 相对路径）。
+    injection_points
+        骨架 manifest 声明的 injection_points 列表（dict 形式）。
+    capabilities
+        list of (capability_root: Path, extensions: List[dict])
+    """
+    points: Dict[str, InjectionPoint] = {}
+    for raw in injection_points:
+        if not raw.get("id") or not raw.get("position") or not raw.get("target"):
+            continue
+        points[raw["id"]] = InjectionPoint(
+            id=raw["id"],
+            target=raw["target"],
+            position=raw["position"],
+            description=raw.get("description", ""),
+        )
+
+    plans: List[InjectionPlan] = []
+    for cap_root, exts in capabilities:
+        for raw in exts or []:
+            inject_id = raw.get("inject_at")
+            if not inject_id or inject_id not in points:
+                # 引用未知点：放一条无效计划，由 resolver 阶段已拦截，这里兜底
+                plans.append(
+                    InjectionPlan(
+                        point=InjectionPoint(id=inject_id or "?", target="", position=""),
+                        extension=Extension(
+                            inject_at=inject_id or "",
+                            code_template=raw.get("code_template", ""),
+                            inline_code=raw.get("inline_code", ""),
+                            capability=str(cap_root.name),
+                        ),
+                        target_abs_path=Path("/dev/null"),
+                        op="",
+                        anchor="",
+                        code="",
+                        valid=False,
+                        error=f"unknown injection point: {inject_id}",
+                    )
+                )
+                continue
+            pt = points[inject_id]
+            parsed = _parse_position(pt.position)
+            if not parsed:
+                plans.append(
+                    InjectionPlan(
+                        point=pt,
+                        extension=Extension(inject_at=inject_id, capability=cap_root.name),
+                        target_abs_path=skeleton_root / pt.target,
+                        op="",
+                        anchor="",
+                        code="",
+                        valid=False,
+                        error=f"invalid position format: {pt.position!r}",
+                    )
+                )
+                continue
+            op, anchor = parsed
+            ext = Extension(
+                inject_at=inject_id,
+                code_template=raw.get("code_template", ""),
+                inline_code=raw.get("inline_code", ""),
+                capability=cap_root.name,
+            )
+            code = _load_template(cap_root, ext)
+            plans.append(
+                InjectionPlan(
+                    point=pt,
+                    extension=ext,
+                    target_abs_path=skeleton_root / pt.target,
+                    op=op,
+                    anchor=anchor,
+                    code=code,
+                    valid=True,
+                )
+            )
+    return plans
+
+
+# ---------------------------------------------------------------------------
+# 应用：仅支持 Python 源码定位（骨架现状）
+# ---------------------------------------------------------------------------
+_PY_DEF_RE_TPL = (
+    r"^(?P<indent>[ \t]*)(async\s+def|def|class)\s+{name}\b[^\n]*:?\s*$"
+)
+
+
+def _locate_py_anchor(src: str, anchor: str):
+    """First try strict def/class anchor; fallback to 'line-level generic anchor'.
+
+    Generic anchor applies to plain call statements like ``app.include_router``, ``return foo()``;
+    before/after means 'insert before/after that line'; replace means 'replace the entire line'.
+    """
+    pattern = re.compile(_PY_DEF_RE_TPL.format(name=re.escape(anchor)), re.MULTILINE)
+    m = pattern.search(src)
+    if m:
+        return m, "block"
+    # Fallback: capture the entire line containing the anchor
+    loose = re.compile(
+        r"^(?P<indent>[ \t]*)[^\n]*\b" + re.escape(anchor) + r"\b[^\n]*$",
+        re.MULTILINE,
+    )
+    m2 = loose.search(src)
+    if m2:
+        return m2, "line"
+    return None, None
+
+
+def _apply_python(plan_item: InjectionPlan, src: str):
+    """Execute a single injection on Python source; always returns ``(ApplyResult, new_src_or_none)``.
+
+    Idempotency Protection
+    ----------------------
+    If ``plan_item.code`` already exists in the source (checked by ``# [<capability>]`` comment marker,
+    or full snippet substring match), this injection is skipped and returns ``applied=False`` with
+    ``error="already_injected"``, preventing duplicate inserts on repeated ``add-capability`` runs.
+    """
+    target = plan_item.target_abs_path
+    # Idempotency check: use first comment line in inline_code (containing [cap-name]) as fingerprint.
+    # Cannot solely rely on `# [{capability}]` because a single capability may have multiple
+    # injection points (e.g., agent.before_push_text + agent.after_start) sharing the same
+    # marker, which would cause the second injection to be falsely skipped.
+    snippet_stripped = (plan_item.code or "").strip()
+    fingerprint = next(
+        (ln.strip() for ln in (plan_item.code or "").splitlines() if ln.strip()),
+        "",
+    )
+    cap_marker_loose = f"# [{plan_item.extension.capability}]"
+    already = False
+    if snippet_stripped and snippet_stripped in src:
+        already = True
+    elif fingerprint and fingerprint in src:
+        already = True
+    elif cap_marker_loose in plan_item.code and snippet_stripped in src:
+        already = True
+    if already:
+        return (
+            ApplyResult(
+                plan=plan_item, applied=False, dry_run=True,
+                diff_preview=f"skip (already injected): {plan_item.extension.capability} -> {target.name}",
+                error="already_injected",
+            ),
+            None,
+        )
+    m, kind = _locate_py_anchor(src, plan_item.anchor)
+    if not m:
+        return (
+            ApplyResult(
+                plan=plan_item, applied=False, dry_run=True,
+                error=f"anchor '{plan_item.anchor}' not found in {target.name}",
+            ),
+            None,
+        )
+    indent = m.group("indent") or ""
+    snippet = "\n".join(
+        f"{indent}{line}" if line.strip() else line
+        for line in plan_item.code.splitlines()
+    )
+    if kind == "block":
+        if plan_item.op == "before":
+            new_src = src[: m.start()] + snippet + "\n" + src[m.start():]
+        elif plan_item.op == "after":
+            rest = src[m.end():]
+            end_in_rest = _find_block_end(rest, indent)
+            end_pos = m.end() + end_in_rest
+            new_src = src[:end_pos] + "\n" + snippet + "\n" + src[end_pos:]
+        else:  # replace 整个 def/class 块
+            rest = src[m.end():]
+            end_in_rest = _find_block_end(rest, indent)
+            end_pos = m.end() + end_in_rest
+            new_src = src[: m.start()] + snippet + "\n" + src[end_pos:]
+    else:  # 行级 anchor：before/after 在该行前/后插，replace 替换整行
+        line_start = m.start()
+        line_end = m.end()
+        # 行级匹配未含尾随换行，定位到 \n 位置以保证拼接正确
+        if line_end < len(src) and src[line_end] == "\n":
+            line_end += 1
+        if plan_item.op == "before":
+            new_src = src[:line_start] + snippet + "\n" + src[line_start:]
+        elif plan_item.op == "after":
+            new_src = src[:line_end] + snippet + "\n" + src[line_end:]
+        else:  # replace 整行
+            new_src = src[:line_start] + snippet + "\n" + src[line_end:]
+    diff = f"{plan_item.op}({kind}) {plan_item.anchor}\n{snippet[:200]}"
+    return (
+        ApplyResult(plan=plan_item, applied=True, dry_run=True, diff_preview=diff),
+        new_src,
+    )
+
+
+def _find_block_end(rest: str, indent: str) -> int:
+    """在函数体之后定位下一个同级/更低缩进的非空行起点。"""
+    pos = 0
+    for line in rest.splitlines(keepends=True):
+        if line.strip() == "":
+            pos += len(line)
+            continue
+        line_indent = len(line) - len(line.lstrip(" \t"))
+        if line_indent <= len(indent) and line.strip():
+            return pos
+        pos += len(line)
+    return len(rest)
+
+
+def apply_plans(
+    plans: List[InjectionPlan],
+    *,
+    dry_run: bool = True,
+) -> List[ApplyResult]:
+    """Execute injection plans. dry_run=True only produces diff previews without writing to disk."""
+    results: List[ApplyResult] = []
+    grouped: Dict[Path, List[InjectionPlan]] = {}
+    for p in plans:
+        if not p.valid:
+            results.append(ApplyResult(plan=p, applied=False, dry_run=dry_run, error=p.error))
+            continue
+        grouped.setdefault(p.target_abs_path, []).append(p)
+
+    for path, group in grouped.items():
+        if not path.exists():
+            for p in group:
+                results.append(ApplyResult(
+                    plan=p, applied=False, dry_run=dry_run,
+                    error=f"target not found: {path}",
+                ))
+            continue
+        # 仅支持 .py 文件原地注入；其他语言由 Agent 自行处理
+        if path.suffix != ".py":
+            for p in group:
+                results.append(ApplyResult(
+                    plan=p, applied=False, dry_run=dry_run,
+                    diff_preview=f"non-python target {path.name}: hand off to adapter",
+                ))
+            continue
+        current = path.read_text(encoding="utf-8")
+        # 倒序处理，避免位置偏移
+        sorted_group = sorted(group, key=lambda x: x.anchor)
+        for p in sorted_group:
+            res, new_src = _apply_python(p, current)
+            if res.applied and new_src is not None:
+                current = new_src
+            res.dry_run = dry_run
+            results.append(res)
+        if not dry_run:
+            path.write_text(current, encoding="utf-8")
+    return results

package/skills/trtc-ai-service/scripts/lib/manifest_resolver.py

@@ -0,0 +1,288 @@
+"""Capability manifest loading / dependency graph / topological sort / circular dependency detection.
+
+Corresponding risks:
+- P1 manifest dependency resolution boundary not covered: use topological sort to detect circular dependencies;
+  block installation on semver major version incompatibility.
+
+Conventions:
+- Each capability directory must contain ``manifest.yaml``.
+- ``type`` field is ``skeleton`` | ``capability``; skeleton packages must exist and be unique.
+- ``dependencies`` entries are of the form ``{name: conversation-core, version: ">=1.0.0,<2.0.0"}``.
+- ``injection_points`` and ``extensions[*].inject_at`` are aligned via the ``id`` field.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+
+import yaml
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+class ManifestError(RuntimeError):
+    """Manifest load or validation failure."""
+
+
+class CircularDependencyError(ManifestError):
+    """Circular dependency detected."""
+
+
+class VersionConflictError(ManifestError):
+    """Semver major version incompatible."""
+
+
+class UnknownInjectionPointError(ManifestError):
+    """Capability references an injection point not declared by the skeleton."""
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class DependencySpec:
+    name: str
+    version: str = "*"  # semver range, e.g., ">=1.0.0,<2.0.0"
+
+
+@dataclass
+class Manifest:
+    name: str
+    version: str
+    type: str  # skeleton | capability
+    description: str = ""
+    dependencies: List[DependencySpec] = field(default_factory=list)
+    injection_points: List[Dict] = field(default_factory=list)
+    extensions: List[Dict] = field(default_factory=list)
+    config: Dict = field(default_factory=dict)
+    integration: Dict = field(default_factory=dict)
+    security: Dict = field(default_factory=dict)
+    endpoints: List[Dict] = field(default_factory=list)
+    path: Optional[Path] = None  # filled in at load time
+
+    @property
+    def is_skeleton(self) -> bool:
+        return self.type == "skeleton"
+
+
+# ---------------------------------------------------------------------------
+# Loading
+# ---------------------------------------------------------------------------
+def _coerce_dep(raw) -> DependencySpec:
+    if isinstance(raw, str):
+        return DependencySpec(name=raw)
+    if isinstance(raw, dict):
+        if "name" not in raw:
+            raise ManifestError(f"dependency missing 'name': {raw}")
+        return DependencySpec(name=raw["name"], version=str(raw.get("version", "*")))
+    raise ManifestError(f"unsupported dependency form: {raw!r}")
+
+
+def load_manifest(manifest_path: Path) -> Manifest:
+    if not manifest_path.exists():
+        raise ManifestError(f"manifest not found: {manifest_path}")
+    with manifest_path.open("r", encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+    if not isinstance(raw, dict):
+        raise ManifestError(f"{manifest_path}: top-level must be mapping")
+    for key in ("name", "version", "type"):
+        if key not in raw:
+            raise ManifestError(f"{manifest_path}: missing required field '{key}'")
+    if raw["type"] not in ("skeleton", "capability"):
+        raise ManifestError(
+            f"{manifest_path}: invalid type '{raw['type']}', expected skeleton|capability"
+        )
+    deps = [_coerce_dep(d) for d in (raw.get("dependencies") or [])]
+    return Manifest(
+        name=str(raw["name"]),
+        version=str(raw["version"]),
+        type=str(raw["type"]),
+        description=str(raw.get("description", "")),
+        dependencies=deps,
+        injection_points=list(raw.get("injection_points") or []),
+        extensions=list(raw.get("extensions") or []),
+        config=dict(raw.get("config") or {}),
+        integration=dict(raw.get("integration") or {}),
+        security=dict(raw.get("security") or {}),
+        endpoints=list(raw.get("endpoints") or []),
+        path=manifest_path,
+    )
+
+
+def discover_manifests(capabilities_root: Path) -> List[Manifest]:
+    """Scan all capability manifests under capabilities/."""
+    manifests: List[Manifest] = []
+    if not capabilities_root.exists():
+        return manifests
+    for child in sorted(capabilities_root.iterdir()):
+        if not child.is_dir():
+            continue
+        mf = child / "manifest.yaml"
+        if mf.exists():
+            manifests.append(load_manifest(mf))
+    return manifests
+
+
+# ---------------------------------------------------------------------------
+# Semver compatibility
+# ---------------------------------------------------------------------------
+_SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)")
+
+
+def _parse_version(v: str) -> Tuple[int, int, int]:
+    m = _SEMVER_RE.match(v.strip())
+    if not m:
+        raise ManifestError(f"invalid semver: {v!r}")
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))
+
+
+_RANGE_RE = re.compile(r"^\s*(>=|<=|>|<|=|\^|~)?\s*(\d+(?:\.\d+){0,2})\s*$")
+
+
+def _check_single(actual: Tuple[int, int, int], spec: str) -> bool:
+    spec = spec.strip()
+    if spec in ("", "*"):
+        return True
+    m = _RANGE_RE.match(spec)
+    if not m:
+        # Unparseable range treated as pass-through (conservative strategy, logged by caller)
+        return True
+    op = m.group(1) or "="
+    parts = [int(p) for p in m.group(2).split(".")]
+    while len(parts) < 3:
+        parts.append(0)
+    target = (parts[0], parts[1], parts[2])
+    if op == "=":
+        return actual == target
+    if op == ">":
+        return actual > target
+    if op == ">=":
+        return actual >= target
+    if op == "<":
+        return actual < target
+    if op == "<=":
+        return actual <= target
+    if op == "^":  # major version compatible
+        return actual >= target and actual[0] == target[0]
+    if op == "~":  # minor version compatible
+        return actual >= target and actual[:2] == target[:2]
+    return True
+
+
+def satisfies(actual_version: str, spec: str) -> bool:
+    """Check whether actual falls within spec (supports ','-joined AND relations)."""
+    if not spec or spec == "*":
+        return True
+    actual = _parse_version(actual_version)
+    return all(_check_single(actual, part) for part in spec.split(","))
+
+
+# ---------------------------------------------------------------------------
+# Topological sort / circular dependency detection
+# ---------------------------------------------------------------------------
+@dataclass
+class ResolvedGraph:
+    order: List[str]               # Topologically sorted capability names
+    manifests: Dict[str, Manifest]
+    skeleton: Manifest
+
+
+def resolve(manifests: Sequence[Manifest]) -> ResolvedGraph:
+    """Build dependency graph, validate version compatibility, and return topological order.
+
+    Raises
+    ------
+    ManifestError
+        No skeleton / multiple skeletons / reference to unknown capability / version incompatible.
+    CircularDependencyError
+        Cycle detected.
+    """
+    # 1) Uniqueness + skeleton identification
+    by_name: Dict[str, Manifest] = {}
+    for m in manifests:
+        if m.name in by_name:
+            raise ManifestError(f"duplicate capability name: {m.name}")
+        by_name[m.name] = m
+    skeletons = [m for m in manifests if m.is_skeleton]
+    if len(skeletons) == 0:
+        raise ManifestError("no skeleton capability found (expected conversation-core)")
+    if len(skeletons) > 1:
+        raise ManifestError(
+            f"multiple skeleton capabilities found: {[s.name for s in skeletons]}"
+        )
+    skeleton = skeletons[0]
+
+    # 2) Reference + version validation
+    for m in manifests:
+        for dep in m.dependencies:
+            if dep.name not in by_name:
+                raise ManifestError(
+                    f"{m.name} depends on unknown capability '{dep.name}'"
+                )
+            target = by_name[dep.name]
+            if not satisfies(target.version, dep.version):
+                raise VersionConflictError(
+                    f"{m.name} requires {dep.name}@{dep.version} but found "
+                    f"{target.version}"
+                )
+
+    # 3) Injection point reference validation (only validates injections into skeleton)
+    skeleton_ids = {p.get("id") for p in skeleton.injection_points if p.get("id")}
+    for m in manifests:
+        for ext in m.extensions:
+            inject_id = ext.get("inject_at")
+            if not inject_id:
+                continue
+            # Allow references to injection points exposed by other capabilities (prefix cap:<capability>/<injection_id>)
+            if ":" in inject_id:
+                continue
+            if inject_id not in skeleton_ids:
+                raise UnknownInjectionPointError(
+                    f"{m.name} references unknown injection point '{inject_id}' "
+                    f"(skeleton declares: {sorted(skeleton_ids)})"
+                )
+
+    # 4) Topological sort (Kahn's algorithm)
+    indeg: Dict[str, int] = {n: 0 for n in by_name}
+    adj: Dict[str, List[str]] = {n: [] for n in by_name}
+    for m in manifests:
+        for dep in m.dependencies:
+            adj[dep.name].append(m.name)
+            indeg[m.name] += 1
+    queue = sorted([n for n, d in indeg.items() if d == 0])
+    order: List[str] = []
+    while queue:
+        n = queue.pop(0)
+        order.append(n)
+        for nxt in sorted(adj[n]):
+            indeg[nxt] -= 1
+            if indeg[nxt] == 0:
+                queue.append(nxt)
+    if len(order) != len(by_name):
+        remaining = [n for n, d in indeg.items() if d > 0]
+        raise CircularDependencyError(
+            f"circular dependency detected among: {remaining}"
+        )
+
+    # Skeleton must come first
+    if skeleton.name not in order or order[0] != skeleton.name:
+        order = [skeleton.name] + [n for n in order if n != skeleton.name]
+    return ResolvedGraph(order=order, manifests=by_name, skeleton=skeleton)
+
+
+# ---------------------------------------------------------------------------
+# Utility: export dependency graph as DOT
+# ---------------------------------------------------------------------------
+def to_dot(graph: ResolvedGraph) -> str:
+    lines = ["digraph capabilities {", "  rankdir=LR;"]
+    for name, mf in graph.manifests.items():
+        shape = "box" if mf.is_skeleton else "ellipse"
+        lines.append(f'  "{name}" [shape={shape}, label="{name}\\n{mf.version}"];')
+    for name, mf in graph.manifests.items():
+        for dep in mf.dependencies:
+            lines.append(f'  "{name}" -> "{dep.name}";')
+    lines.append("}")
+    return "\n".join(lines)