trae-coding-engine 0.1.0

package/templates/scripts/run-mr-hygiene.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# Run all MR hygiene checks and print a compact failure summary at the end.
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+# shellcheck source=scripts/lib/cli-args.sh
+. scripts/lib/cli-args.sh
+
+DESC_FILE=""
+TARGET_BRANCH="${CI_MERGE_REQUEST_TARGET_BRANCH:-release}"
+FRESHNESS_TARGET=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --description-file)
+      DESC_FILE=$(require_value --description-file "${2:-}"); shift 2 ;;
+    --description-file=*)
+      DESC_FILE="${1#--description-file=}"; shift ;;
+    --target-branch)
+      TARGET_BRANCH=$(require_value --target-branch "${2:-}"); shift 2 ;;
+    --target-branch=*)
+      TARGET_BRANCH="${1#--target-branch=}"; shift ;;
+    --freshness-target)
+      FRESHNESS_TARGET=$(require_value --freshness-target "${2:-}"); shift 2 ;;
+    --freshness-target=*)
+      FRESHNESS_TARGET="${1#--freshness-target=}"; shift ;;
+    -h|--help)
+      sed -n '2,28p' "$0"; exit 0 ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -z "$FRESHNESS_TARGET" ]; then
+  FRESHNESS_TARGET="${MR_TARGET_REF:-origin/${TARGET_BRANCH}}"
+fi
+
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT INT TERM
+
+FAILURES=()
+SETUP_FAILURES=()
+
+record_failure() {
+  local name=$1 rc=$2 hint=$3
+  if [ "$rc" -eq 2 ]; then
+    SETUP_FAILURES+=("${name}: setup error (exit ${rc})")
+  else
+    FAILURES+=("${name}: failed (exit ${rc})")
+  fi
+  HINTS+=("${name}: ${hint}")
+}
+
+HINTS=()
+
+run_check() {
+  local name=$1 hint=$2
+  shift 2
+  local out="$TMP_DIR/${name//[^a-zA-Z0-9_]/_}.log"
+
+  printf '\n========== MR hygiene: %s ==========\n' "$name"
+  local rc
+  if "$@" >"$out" 2>&1; then
+    rc=0
+  else
+    rc=$?
+  fi
+  cat "$out"
+
+  if [ "$rc" -eq 0 ]; then
+    printf '[OK] %s\n' "$name"
+    return 0
+  fi
+
+  printf '[FAIL] %s exited with %d\n' "$name" "$rc"
+  record_failure "$name" "$rc" "$hint"
+  return 0
+}
+
+TITLE_CMD=(bash scripts/check-mr-title.sh)
+DESC_CMD=(bash scripts/check-mr-desc.sh)
+if [ -n "$DESC_FILE" ]; then
+  DESC_CMD+=(--description-file "$DESC_FILE")
+fi
+
+SIZE_BASE="origin/${TARGET_BRANCH}"
+SIZE_CMD=(bash scripts/check-mr-size.sh --base "$SIZE_BASE")
+FRESHNESS_CMD=(bash scripts/check-mr-target-merged.sh --target "$FRESHNESS_TARGET")
+
+run_check "title" \
+  "Fix the MR title, or test locally with: make check-mr-title TITLE=\"<title>\"" \
+  "${TITLE_CMD[@]}"
+run_check "description" \
+  "Fill ## 变更说明 with real prose, then test locally with: make check-mr-desc FILE=<desc.md>" \
+  "${DESC_CMD[@]}"
+run_check "diff size" \
+  "Split the MR or inspect locally with: make check-mr-size BASE=${SIZE_BASE}" \
+  "${SIZE_CMD[@]}"
+run_check "release freshness" \
+  "Merge latest target locally: git fetch origin ${TARGET_BRANCH} && git merge ${FRESHNESS_TARGET}" \
+  "${FRESHNESS_CMD[@]}"
+
+total_failures=$((${#FAILURES[@]} + ${#SETUP_FAILURES[@]}))
+if [ "$total_failures" -eq 0 ]; then
+  printf '\n========== MR hygiene passed ==========\n'
+  exit 0
+fi
+
+cat >&2 <<EOF
+
+!!!!!!!!!! MR hygiene failed (${total_failures} check(s)) !!!!!!!!!!
+EOF
+
+if [ "${#FAILURES[@]}" -gt 0 ]; then
+  printf '\nBlocking check failures:\n' >&2
+  for failure in "${FAILURES[@]}"; do
+    printf '  - %s\n' "$failure" >&2
+  done
+fi
+
+if [ "${#SETUP_FAILURES[@]}" -gt 0 ]; then
+  printf '\nSetup errors:\n' >&2
+  for failure in "${SETUP_FAILURES[@]}"; do
+    printf '  - %s\n' "$failure" >&2
+  done
+fi
+
+printf '\nHow to fix / reproduce:\n' >&2
+for hint in "${HINTS[@]}"; do
+  printf '  - %s\n' "$hint" >&2
+done
+
+cat >&2 <<EOF
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+EOF
+
+if [ "${#SETUP_FAILURES[@]}" -gt 0 ]; then
+  exit 2
+fi
+exit 1

package/templates/scripts/runbook.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# runbook.sh — oncall keyword lookup over docs/runbooks/. Read-only, grep-only.
+#
+#   scripts/runbook.sh <keyword>
+#
+# Case-insensitive search across every runbook's FILENAME and BODY; prints each
+# matching runbook path with a one-line context snippet. With no argument it
+# prints usage and lists every runbook. When exactly one runbook matches it also
+# prints a copy-paste hint to open it — but never auto-opens anything (so it is
+# safe to run mid-incident without launching a pager you didn't ask for).
+#
+# All comments English (check-comment-i18n gate).
+set -euo pipefail
+
+# Force a UTF-8 locale: runbooks contain multibyte text (em-dash, CJK). Under a
+# C / non-UTF-8 locale, BSD grep aborts with "illegal byte sequence".
+for _loc in C.UTF-8 en_US.UTF-8; do
+  if locale -a 2>/dev/null | grep -qx "$_loc"; then
+    export LC_ALL="$_loc" LANG="$_loc"
+    break
+  fi
+done
+
+cd "$(dirname "$0")/.."
+RUNBOOK_DIR="docs/runbooks"
+
+# Runbooks only — exclude the front-door READMEs, the copy-me TEMPLATE, and the
+# append-only INCIDENTS log from the searchable set.
+list_runbooks() {
+  find "$RUNBOOK_DIR" -maxdepth 1 -name '*.md' \
+    ! -name 'README.md' ! -name 'README.*.md' \
+    ! -name 'TEMPLATE.md' ! -name 'INCIDENTS.md' \
+    | sort
+}
+
+usage() {
+  cat <<EOF
+Usage: scripts/runbook.sh <keyword>
+
+  Case-insensitive search across docs/runbooks/ filenames and bodies.
+
+Available runbooks:
+EOF
+  while IFS= read -r f; do
+    # First H1 line, stripped of the leading '# ', as a human title.
+    title=$(grep -m1 -E '^# ' "$f" | sed -E 's/^#[[:space:]]*//')
+    printf "  %-52s %s\n" "$f" "$title"
+  done < <(list_runbooks)
+}
+
+# No argument (or an empty one) -> usage + full list.
+if [ "$#" -eq 0 ] || [ -z "${1:-}" ]; then
+  usage
+  exit 0
+fi
+
+KEYWORD=$1
+
+# Collect matches: a runbook matches if its filename OR any body line contains
+# the keyword (case-insensitive). Keep the match list ordered and unique.
+matches=()
+while IFS= read -r f; do
+  base=$(basename "$f")
+  if printf '%s\n' "$base" | grep -qiF -- "$KEYWORD"; then
+    matches+=("$f")
+    continue
+  fi
+  if grep -qiF -- "$KEYWORD" "$f"; then
+    matches+=("$f")
+  fi
+done < <(list_runbooks)
+
+if [ "${#matches[@]}" -eq 0 ]; then
+  echo "No runbook matches '$KEYWORD'."
+  echo "Run 'scripts/runbook.sh' with no argument to list all runbooks."
+  exit 1
+fi
+
+for f in "${matches[@]}"; do
+  echo "$f"
+  # One-line body context: first matching line (filename-only matches may have
+  # none), trimmed and truncated so the output stays a single tidy line.
+  ctx=$(grep -m1 -iF -- "$KEYWORD" "$f" 2>/dev/null | sed -E 's/^[[:space:]]+//' | cut -c1-100 || true)
+  [ -n "$ctx" ] && echo "    $ctx"
+done
+
+# Exactly one match -> offer a copy-paste open hint (do NOT auto-open).
+if [ "${#matches[@]}" -eq 1 ]; then
+  echo
+  echo "Open it:  ${PAGER:-less} ${matches[0]}"
+fi

package/templates/scripts/self-maintenance-digest.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Aggregate open self-maintenance issues into one finder-grouped heartbeat markdown.
+
+Read-only: consumes the issue store (open + a bounded closed scan) and renders
+markdown. No issue writes, no artifact passing.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+SEVERITY_ORDER = {"Critical": 0, "Major": 1, "Minor": 2}
+LIB = "scripts/lib/codebase-json.py"
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Render the self-maintenance heartbeat markdown.")
+    p.add_argument("--open-json", required=True, help="open issue list JSON file")
+    p.add_argument("--closed-json", required=True, help="closed issue list JSON file (recurrence)")
+    p.add_argument("--health", default="healthy", choices=("healthy", "unhealthy", "unknown"))
+    return p.parse_args()
+
+
+def run_codebase_json(subcommand: str, json_path: str) -> str:
+    data = Path(json_path).read_bytes() if Path(json_path).exists() else b""
+    if not data.strip():
+        return ""
+    result = subprocess.run(
+        [sys.executable, LIB, subcommand],
+        input=data, capture_output=True, check=False,
+    )
+    if result.returncode != 0:
+        # Fail loud: a parser/schema failure must NOT be silently treated as an
+        # empty issue store (that would emit a false "no backlog" / silent card).
+        sys.stderr.write(
+            f"error: {LIB} {subcommand} failed (exit {result.returncode}): "
+            f"{result.stderr.decode('utf-8', errors='replace')}\n"
+        )
+        raise SystemExit(result.returncode)
+    return result.stdout.decode("utf-8", errors="replace")
+
+
+def parse_rows(text: str) -> list[dict[str, str]]:
+    rows: list[dict[str, str]] = []
+    for line in text.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 6:
+            continue
+        rows.append({
+            "number": parts[0], "finder": parts[1], "severity": parts[2],
+            "dedup": parts[3], "evidence": parts[4], "title": parts[5],
+        })
+    return rows
+
+
+def parse_counts(text: str) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for line in text.splitlines():
+        parts = line.split("\t")
+        if len(parts) == 2 and parts[1].isdigit():
+            counts[parts[0]] = int(parts[1])
+    return counts
+
+
+def cluster_flags(rows: list[dict[str, str]]) -> dict[str, int]:
+    # evidence path -> number of distinct finders that touch it
+    by_path: dict[str, set[str]] = {}
+    for r in rows:
+        for path in filter(None, r["evidence"].split(",")):
+            by_path.setdefault(path, set()).add(r["finder"])
+    return {p: len(f) for p, f in by_path.items() if len(f) > 1}
+
+
+def build_digest_markdown(rows, recurrence, health) -> str:
+    health_banner = (
+        f"## ⚠️ 平台健康：{health}\n\n本拍跳过 deep 派发；坍缩为单卡。"
+        if health != "healthy"
+        else ""
+    )
+    if not rows:
+        # Fail-noisy: an abnormal platform-health verdict must still surface a
+        # card even when the open backlog is empty (never silently skip).
+        if health_banner:
+            return health_banner + "\n\n---\n\n（本拍无 open self-maintenance issue。）"
+        return "(no open self-maintenance issues)"
+
+    clusters = cluster_flags(rows)
+    sections: list[str] = [health_banner] if health_banner else []
+
+    groups: dict[str, list[dict[str, str]]] = {}
+    for r in rows:
+        groups.setdefault(r["finder"], []).append(r)
+
+    for finder in sorted(groups):
+        # Documented two-level ordering: severity first, then recurrence count
+        # descending (a repeatedly-recurring item outranks a first-seen one of
+        # the same severity).
+        items = sorted(
+            groups[finder],
+            key=lambda r: (SEVERITY_ORDER.get(r["severity"], 2), -recurrence.get(r["dedup"], 0)),
+        )
+        lines = [f"## {finder} ({len(items)})", ""]
+        for r in items:
+            rec = recurrence.get(r["dedup"], 0)
+            rec_str = f" · 复发×{rec}" if rec >= 2 else ""
+            cluster_hit = [p for p in r["evidence"].split(",") if p in clusters]
+            cl_str = f" · 🔗{cluster_hit[0]}" if cluster_hit else ""
+            lines.append(f"- `[{r['severity']}]` #{r['number']} {r['title']}{rec_str}{cl_str}")
+        sections.append("\n".join(lines))
+
+    return "\n\n---\n\n".join(sections)
+
+
+def main() -> int:
+    args = parse_args()
+    rows = parse_rows(run_codebase_json("issue-digest-rows", args.open_json))
+    recurrence = parse_counts(run_codebase_json("issue-dedup-counts", args.closed_json))
+    print(build_digest_markdown(rows, recurrence, args.health))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/scripts/send-self-maintenance-lark-card.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Send the single self-maintenance heartbeat card to a Lark custom bot."""
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import hmac
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+MAX_MARKDOWN_CHARS = 14000
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Send the self-maintenance heartbeat card.")
+    p.add_argument("--markdown-file", help="digest markdown file; default reads stdin")
+    p.add_argument("--title", default=os.getenv("HEARTBEAT_CARD_TITLE", "Coding 自维护心跳"))
+    p.add_argument("--webhook", default=os.getenv("LARK_CUSTOM_BOT_WEBHOOK"))
+    p.add_argument("--secret", default=os.getenv("LARK_CUSTOM_BOT_SECRET"))
+    p.add_argument("--dry-run", action="store_true")
+    return p.parse_args()
+
+
+def build_payload(*, title: str, markdown: str, secret: str | None) -> dict[str, object]:
+    unhealthy = "平台健康" in markdown
+    # Never silently drop content: if the body exceeds the card limit, truncate
+    # but append a visible notice pointing at the durable issue list.
+    if len(markdown) > MAX_MARKDOWN_CHARS:
+        notice = "\n\n…（内容过长已截断，完整 backlog 见 issue 列表）"
+        markdown = markdown[: MAX_MARKDOWN_CHARS - len(notice)] + notice
+    payload: dict[str, object] = {
+        "msg_type": "interactive",
+        "card": {
+            "schema": "2.0",
+            "config": {"update_multi": True},
+            "header": {
+                "template": "red" if unhealthy else "blue",
+                "title": {"tag": "plain_text", "content": title},
+            },
+            "body": {
+                "direction": "vertical",
+                "padding": "12px 12px 12px 12px",
+                "elements": [{"tag": "markdown", "content": markdown[:MAX_MARKDOWN_CHARS]}],
+            },
+        },
+    }
+    if secret:
+        timestamp = str(int(time.time()))
+        payload["timestamp"] = timestamp
+        payload["sign"] = sign(timestamp, secret)
+    return payload
+
+
+def sign(timestamp: str, secret: str) -> str:
+    string_to_sign = f"{timestamp}\n{secret}".encode("utf-8")
+    digest = hmac.new(string_to_sign, b"", hashlib.sha256).digest()
+    return base64.b64encode(digest).decode("utf-8")
+
+
+def send(webhook: str, payload: dict[str, object]) -> int:
+    data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    request = urllib.request.Request(
+        webhook, data=data,
+        headers={"Content-Type": "application/json; charset=utf-8"}, method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            body = response.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        print(f"error: webhook HTTP {exc.code}: {body}", file=sys.stderr)
+        return 1
+    except urllib.error.URLError as exc:
+        print(f"error: webhook request failed: {exc}", file=sys.stderr)
+        return 1
+    try:
+        decoded = json.loads(body)
+    except json.JSONDecodeError:
+        print(f"error: webhook returned non-JSON: {body}", file=sys.stderr)
+        return 1
+    code = decoded.get("code")
+    status_code = decoded.get("StatusCode")
+    if code != 0 and status_code != 0:
+        print(f"error: webhook rejected message: {body}", file=sys.stderr)
+        return 1
+    print("sent self-maintenance heartbeat card to Lark custom bot")
+    return 0
+
+
+def main() -> int:
+    args = parse_args()
+    if args.markdown_file:
+        markdown = Path(args.markdown_file).read_text(encoding="utf-8").strip()
+    else:
+        markdown = sys.stdin.read().strip()
+    if not markdown or markdown == "(no open self-maintenance issues)":
+        print("no open self-maintenance issues; skip Lark notification")
+        return 0
+    payload = build_payload(title=args.title, markdown=markdown, secret=args.secret)
+    if args.dry_run:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return 0
+    if not args.webhook:
+        print("error: missing webhook. Set LARK_CUSTOM_BOT_WEBHOOK or pass --webhook.", file=sys.stderr)
+        return 2
+    return send(args.webhook, payload)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/scripts/skill-graph.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Generates a Graphviz DOT graph of cross-references between coding-* skills.
+#
+# Usage:
+#   bash scripts/skill-graph.sh                # write to docs/assets/skill-graph.dot, render PNG if dot is available
+#   bash scripts/skill-graph.sh --check        # regenerate to a temp file, diff against committed; non-zero exit on drift
+#   bash scripts/skill-graph.sh --stdout       # print DOT to stdout (no file write)
+#
+# Edges are extracted by grepping each SKILL.md for occurrences of other
+# `coding-<known>` skill names (excluding self). A "known" skill is any
+# directory under .agents/skills/coding-*/. Non-skill `coding-*` tokens
+# (coding-server, coding-gateway, coding-worker — deployment names) are
+# automatically filtered because they don't match a directory.
+
+set -euo pipefail
+shopt -s nullglob
+
+SKILLS_ROOT=".agents/skills"
+DOT_PATH="docs/assets/skill-graph.dot"
+PNG_PATH="docs/assets/skill-graph.png"
+
+mode="write"
+case "${1:-}" in
+    --check)  mode="check" ;;
+    --stdout) mode="stdout" ;;
+    "")       mode="write" ;;
+    *) echo "usage: $0 [--check | --stdout]" >&2; exit 2 ;;
+esac
+
+# Collect known skill names from filesystem
+known=()
+for dir in "$SKILLS_ROOT"/coding-*; do
+    [[ -d "$dir" ]] || continue
+    known+=("$(basename "$dir")")
+done
+
+if [[ "${#known[@]}" -eq 0 ]]; then
+    echo "[ERROR] no skills found under $SKILLS_ROOT" >&2
+    exit 1
+fi
+
+# Build a regex alternation of known names for filtering
+known_regex="^($(IFS='|'; echo "${known[*]}"))$"
+
+# Emit DOT to a string we can either write or compare
+emit_dot() {
+    cat <<EOF
+// Skill cross-reference graph for coding-engine.
+// Auto-generated by scripts/skill-graph.sh — do not edit by hand.
+// Regenerate via: make skill-graph
+//
+// Render to PNG locally:    dot -Tpng docs/assets/skill-graph.dot -o docs/assets/skill-graph.png
+// Render to SVG locally:    dot -Tsvg docs/assets/skill-graph.dot -o docs/assets/skill-graph.svg
+EOF
+    echo ""
+    echo "digraph SkillCrossRefs {"
+    echo "    rankdir=LR;"
+    echo "    node [shape=box, style=\"rounded,filled\", fillcolor=\"#f5f5f5\", fontname=\"Helvetica\"];"
+    echo "    edge [fontname=\"Helvetica\", color=\"#666666\"];"
+    echo ""
+
+    for src in "${known[@]}"; do
+        echo "    \"$src\";"
+    done
+    echo ""
+
+    for src in "${known[@]}"; do
+        local skill_md="$SKILLS_ROOT/$src/SKILL.md"
+        [[ -f "$skill_md" ]] || continue
+
+        # Extract all coding-* tokens, dedup, filter to known set, drop self.
+        # Pattern is intentionally permissive (incl. digits / extra hyphens);
+        # known_regex below rejects anything not actually under .agents/skills/.
+        while IFS= read -r tgt; do
+            [[ -z "$tgt" ]] && continue
+            [[ "$tgt" == "$src" ]] && continue                # skip self
+            [[ "$tgt" =~ $known_regex ]] || continue          # filter unknown
+            echo "    \"$src\" -> \"$tgt\";"
+        done < <(grep -oE 'coding-[a-z0-9][a-z0-9-]*' "$skill_md" | sort -u)
+    done
+
+    echo "}"
+}
+
+case "$mode" in
+    stdout)
+        emit_dot
+        ;;
+    check)
+        if [[ ! -f "$DOT_PATH" ]]; then
+            echo "[FAIL] $DOT_PATH does not exist — run \`make skill-graph\` to create it"
+            exit 1
+        fi
+        if ! diff -q <(emit_dot) "$DOT_PATH" >/dev/null 2>&1; then
+            echo "[STALE] $DOT_PATH does not match current SKILL.md cross-references"
+            echo "        Run \`make skill-graph\` to regenerate, then commit the diff"
+            exit 1
+        fi
+        ;;
+    write)
+        mkdir -p "$(dirname "$DOT_PATH")"
+        emit_dot > "$DOT_PATH"
+        echo "  [OK] wrote $DOT_PATH"
+
+        if command -v dot >/dev/null 2>&1; then
+            dot -Tpng "$DOT_PATH" -o "$PNG_PATH"
+            echo "  [OK] rendered $PNG_PATH"
+        else
+            echo "  [SKIP] graphviz \`dot\` not in PATH — PNG render skipped"
+            echo "         install via:  brew install graphviz   (macOS)"
+            echo "                       apt-get install graphviz  (Debian/Ubuntu)"
+        fi
+        ;;
+esac