给 Agent 准备数据：别只喂文档，要设计可行动的上下文

mkdir -p docs
cat > docs/restart-api.md <<'EOF'
# Restart API Service

## Preconditions
User must have production operator permission. Check current incident status before restart.

## Restart command
Run `kubectl rollout restart deployment/api -n prod`.

## Health check
Call `https://api.example.com/healthz` and expect HTTP 200 within 120 seconds.

## Rollback
If health check fails, rollback the deployment and page the owner.
EOF

from pathlib import Path
import hashlib
import json
import re

DOC_DIR = Path("docs")
OUT_FILE = Path("agent_chunks.jsonl")

heading_re = re.compile(r"^(#{1,3})\s+(.+)$", re.MULTILINE)


def stable_id(text: str) -> str:
    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]


def infer_risk(text: str) -> dict:
    lower = text.lower()
    destructive_words = ["delete", "drop", "rollback", "restart", "shutdown"]
    requires_approval = any(word in lower for word in destructive_words)
    return {
        "requires_approval": requires_approval,
        "risk": "high" if requires_approval else "normal",
    }


def split_markdown(path: Path):
    text = path.read_text(encoding="utf-8")
    matches = list(heading_re.finditer(text))

    if not matches:
        yield {
            "id": stable_id(str(path) + text),
            "source": str(path),
            "title": path.stem,
            "content": text.strip(),
            **infer_risk(text),
        }
        return

    for i, match in enumerate(matches):
        start = match.start()
        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
        title = match.group(2).strip()
        content = text[start:end].strip()
        if not content:
            continue
        yield {
            "id": stable_id(str(path) + title + content),
            "source": str(path),
            "title": title,
            "content": content,
            "content_type": "runbook" if "restart" in str(path).lower() else "doc",
            **infer_risk(content),
        }


def main():
    chunks = []
    for path in sorted(DOC_DIR.glob("**/*.md")):
        chunks.extend(split_markdown(path))

    with OUT_FILE.open("w", encoding="utf-8") as f:
        for chunk in chunks:
            f.write(json.dumps(chunk, ensure_ascii=False) + "\n")

    print(f"wrote {len(chunks)} chunks to {OUT_FILE}")


if __name__ == "__main__":
    main()

python prepare_agent_data.py
head -n 3 agent_chunks.jsonl

{"id":"...","source":"docs/restart-api.md","title":"Restart command","content":"## Restart command\nRun `kubectl rollout restart deployment/api -n prod`.","content_type":"runbook","requires_approval":true,"risk":"high"}

tools:
  - name: restart_kubernetes_deployment
    description: Restart a Kubernetes deployment in an approved namespace.
    side_effect: true
    requires_approval: true
    allowed_namespaces:
      - staging
      - prod
    input_schema:
      type: object
      required: [namespace, deployment]
      properties:
        namespace:
          type: string
          enum: [staging, prod]
        deployment:
          type: string
          pattern: "^[a-z0-9-]+$"
    success_check:
      type: http
      timeout_seconds: 120
      expected_status: 200
    retry_policy:
      max_attempts: 1