@xdxer/dingtalk-agent 0.1.4-beta.8 → 0.1.4

package/skills/platforms/multica-dingtalk/multica-external/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: multica-external
+description: External Python wrapper defining the full developer chain for delivering an agent on the Multica (DingTalk-FDE fork) platform — workspace bootstrap, runtime/agent provisioning, skill assembly (push/pull), DingTalk robot & account binding, execution-trace observability, cron scheduling (autopilot), and health checks. Use when provisioning, operating, debugging, or observing a Multica-managed agent from the command line with only an endpoint and a token.
+metadata:
+  version: "0.1.0"
+---
+
+# Multica FDE External Skill
+
+This skill is the **Multica adapter** of the Managed Agent Platform developer
+chain: everything a developer needs to take an agent from nothing to a
+customer-facing DingTalk bot, then observe, schedule, and health-check it.
+Multica may be only one of several managed platforms; this skill defines
+exactly which capabilities the Multica backend provides and wraps each one as
+a script command. An external orchestrator can fetch this skill (see
+*Skill logistics*) and execute its scripts.
+
+Deliberately **decoupled from the Go CLI**: nothing patches `multica`;
+everything is plain HTTPS against the server. Only two inputs are needed —
+**server URL** and **token** — both reusable from the CLI's stored config.
+
+- Script: `scripts/multica_ext.py` — single file, stdlib only, Python >= 3.9.
+- Proxy-immune: the script ignores `HTTP(S)_PROXY` env vars by design (unlike
+  curl or the Go CLI), so an exported shell proxy cannot break pre/intranet
+  endpoints.
+- All commands print JSON to stdout (status notes on stderr) — pipe to `jq`.
+- Global flags may appear before or after the command.
+
+## Credentials
+
+Resolution order (first hit wins):
+
+1. Flags: `--server-url`, `--token`, `--workspace <slug|uuid>`
+2. Env: `MULTICA_SERVER_URL`, `MULTICA_TOKEN`, `MULTICA_WORKSPACE_ID`
+3. `--profile <name>` → `~/.multica/profiles/<name>/config.json`
+4. `~/.multica/config.json` (keys: `server_url`, `workspace_id`, `token`)
+
+The token is a `mul_` personal access token or login JWT; mint PATs with
+`POST /api/tokens`.
+
+```bash
+PY=".agents/skills/multica-external/scripts/multica_ext.py"
+python3 $PY --help
+python3 $PY whoami --profile pre-fde
+```
+
+## The developer chain
+
+### 1 — Provision: workspace, runtime, agent
+
+```bash
+python3 $PY workspace-init --profile pre-fde --name "FDE 团队" --slug fde-team \
+  --repo https://code.example.com/org/repo.git --complete-onboarding
+python3 $PY runtime-create-fc --workspace fde-team --template-id <id>   # cloud FC-E2B runtime
+python3 $PY agent-create --workspace fde-team --name "FDE 教练" \
+  --instructions "..." --model claude-sonnet-5                          # sole runtime auto-picked
+```
+
+`workspace-init` is idempotent (409 → reuse when you are a member); repos
+merge, never clobber; repo registration needs owner/admin. Slugs:
+`^[a-z0-9]+(-[a-z0-9]+)*$`, reserved list enforced. An agent needs a runtime:
+FC-E2B cloud (`runtime-create-fc`, requires server-side FC-E2B enablement) or
+a local daemon. `runtime-templates` lists templates; when `--template-id` is
+omitted and exactly one exists it is auto-picked.
+
+### 2 — Define & assemble: where the agent comes from, what skills it has
+
+- `agent-source --agent <uuid>` — which git repo backs the agent (the
+  per-agent `agent_sources` link: `github` or `managed_git`; `null` = not
+  git-backed). `agent-source-sync` re-syncs github-sourced agents
+  (`managed_git` refuses with 409 by design — updated by the platform).
+- Skills: `skill-list`, `skill-get`, `skill-push --dir <path>`
+  (local directory → workspace, `--on-conflict overwrite` replaces content
+  AND files wholesale), `skill-pull --skill <id-or-name> --dest <dir>`
+  (workspace → local directory). Assign skills to an agent with the Go CLI
+  (`multica agent skills add`) or `PUT /api/agents/{id}/skills`.
+- Gap to know: there is no API to bind an *arbitrary* git URL to an agent;
+  per-agent git links are created only by the GitHub publish flow or the
+  managed FDE provision flow. Workspace-level repos (`workspace-repos`) and
+  the two flows above are the supported paths.
+
+### 3 — Deliver: bind the agent to a customer-facing DingTalk bot
+
+The binding is a **channel installation** (one robot app per agent), not a
+Skill object. AppKey/AppSecret are `client_id`/`client_secret` on the wire;
+the secret is encrypted at rest (`MULTICA_DINGTALK_SECRET_KEY`) and never
+returned. Inbound messages use DingTalk Stream Mode — no public webhook
+registration needed.
+
+```bash
+# Self-service: inject an existing robot app's credentials (owner/admin)
+python3 $PY dingtalk-bind --agent <uuid> --client-id <AppKey> --client-secret-stdin < secret.txt
+# Or scan-to-create: DingTalk mints the app, server captures credentials
+python3 $PY dingtalk-begin --agent <uuid> --wait
+python3 $PY dingtalk-list ; python3 $PY dingtalk-revoke --installation <uuid>
+# Personal-account binding family (dingtalk_account):
+python3 $PY dingtalk-account-begin --agent <uuid>   # prints QR URL
+python3 $PY dingtalk-account-list ; python3 $PY dingtalk-account-unbind --installation <uuid>
+```
+
+Bind and unbind always come in pairs: robot `dingtalk-bind`/`dingtalk-begin`
+↔ `dingtalk-revoke`; account `dingtalk-account-begin` ↔
+`dingtalk-account-unbind`. `dingtalk-account-begin` returns the binding link
+(`qr_code_url`) directly — hand it to the counterpart to scan; check the
+result with `dingtalk-account-list` (`dws_identity` carries the bound
+account's org/display name).
+
+Server rules: one robot per agent; re-binding the same `client_id` **moves**
+the installation; cross-workspace `client_id` reuse → 409. Error map for
+`dingtalk-bind`: **502** "dingtalk credentials check failed" = wrong
+AppKey/AppSecret; **409** = ownership/agent conflict; **404** = agent not in
+this workspace; `configured: false` in `dingtalk-list` = server lacks the
+secret key. Deletes are audit-kept (`status: revoked`).
+
+### 4 — Observe: the agent's working and reasoning process
+
+The full step-by-step trace (reasoning text, every tool call with input JSON,
+every tool result, errors) is **persisted forever** in `task_messages` and
+retrievable by REST — no backend changes needed:
+
+```bash
+python3 $PY agent-tasks --agent <uuid>                 # run history (status, error, failure_reason, kind)
+python3 $PY task-trace --task <uuid> --text            # full reasoning/tool trace, human-readable
+python3 $PY task-trace --task <uuid> --follow --text   # live: polls until the task ends
+python3 $PY issue-tasks --issue FDE-1                  # all runs for an issue (uuid or identifier)
+python3 $PY issue-timeline --issue FDE-1               # comments + activity log merged (status changes, task_completed...)
+python3 $PY issue-usage --issue FDE-1                  # aggregated token usage
+python3 $PY task-snapshot                              # workspace-wide: active tasks + each agent's latest outcome
+```
+
+Chat surfaces are REST-pollable too (`/api/chat/sessions/...` — session
+messages, `pending-task`); realtime push is WebSocket `/ws` only (no SSE),
+but a poll-only client fully reconstructs any past run from `task-trace`.
+
+### 5 — Schedule: cron automations (autopilot)
+
+```bash
+python3 $PY autopilot-create --title "每日巡检" --agent <uuid> \
+  --description "<the prompt for each run>" --cron "0 9 * * 1-5" --timezone Asia/Shanghai
+python3 $PY autopilot-trigger --autopilot <uuid>       # run once, now
+python3 $PY autopilot-runs --autopilot <uuid>          # history: status, linked issue/task
+python3 $PY autopilot-set-status --autopilot <uuid> --status paused   # pause / active
+python3 $PY autopilot-list ; python3 $PY autopilot-get --autopilot <uuid>
+```
+
+Cron is standard 5-field (no seconds, no `@daily`), IANA timezone (default
+UTC in the API; this script defaults `Asia/Shanghai`). `create_issue` mode
+creates an issue per run (title template supports `{{date}}`) and enqueues an
+agent task; `run_only` enqueues a task with no issue. Runs are idempotent per
+(trigger, planned time); missed fires collapse to the latest, >5 min late is
+skipped. Webhook triggers also exist (`POST /api/autopilots/{id}/triggers`
+with `kind: webhook`).
+
+### 6 — Check: doctor report
+
+```bash
+python3 $PY agent-check --agent <uuid>
+```
+
+Composite JSON report: agent status/archived, runtime health (online /
+unstable = offline but seen <5 min ago / offline / missing), active tasks +
+last outcome (with `failure_reason`), recent failure count, DingTalk robot +
+account binding state, plus a `checks[]` verdict list; `healthy` = no `fail`
+(warns don't fail the check).
+
+### 7 — Basics: issues, comments, chat, members, tokens
+
+Everyday Multica operations so an orchestrator needs nothing but this script:
+
+```bash
+python3 $PY issue-create --title "..." --assignee-agent <uuid>   # assigning an agent triggers a run
+python3 $PY issue-get --issue FDE-1 ; python3 $PY issue-list --open-only --assignee <uuid>
+python3 $PY issue-update --issue FDE-1 --status done
+python3 $PY comment-add --issue FDE-1 --content "..."            # "/note " prefix suppresses agent triggering
+python3 $PY comment-list --issue FDE-1 --recent 10
+python3 $PY chat-send --agent <uuid> --content "你好" --wait      # direct conversation — the no-DingTalk e2e test path
+python3 $PY member-list ; python3 $PY member-invite --email a@b.c --role member
+python3 $PY token-create --name ci-bot --expires-days 90         # plaintext token shown once
+```
+
+`chat-send` creates a session when `--session` is omitted and with `--wait`
+polls `pending-task` until the assistant reply lands — the fastest way to
+smoke-test a freshly provisioned agent before binding any channel.
+
+## Skill logistics: how skills move (the three planes)
+
+- **Up (local → workspace):** `skill-push --dir` (this script);
+  `multica skill import --url|--file` (URL / `.skill`/`.zip` archive);
+  or the runtime *local-skills* API — the daemon scans the machine's
+  home-level skill dirs (`~/.claude/skills`, `~/.codex/skills`, the
+  cross-tool universal root `~/.agents/skills`, Claude plugin roots, etc.;
+  a "skill" = a directory with `SKILL.md`) and the workspace can list and
+  import them (`POST /api/runtimes/{id}/local-skills[/import]`, owner-only
+  for import).
+- **Store:** workspace DB (`content` = SKILL.md, `files[]` = supporting
+  files; `SKILL.md` is a reserved file path).
+- **Down (workspace → local):** automatic — the daemon materializes assigned
+  skills into each task's exec env (per-provider dirs, e.g.
+  `.claude/skills`, ephemeral, task-scoped). Manual/persistent — the Go CLI
+  has **no** download command; `skill-pull` (this script) is the downlink:
+  it writes `SKILL.md` + files into a local directory, byte-identical to
+  what was pushed. An external orchestrator can therefore
+  `skill-pull --skill multica-external --dest <dir>` and execute the
+  scripts it receives.
+
+## Command → API map
+
+| Command | API |
+| --- | --- |
+| `whoami` | `GET /api/me` |
+| `workspace-list` / `workspace-create` / `workspace-init` | `GET`/`POST /api/workspaces` (+ `PUT /api/workspaces/{id}`, `POST /api/me/onboarding/complete`) |
+| `workspace-repos` | `GET`/`PUT /api/workspaces/{id}` (`repos` JSONB) |
+| `runtime-list` / `runtime-templates` / `runtime-create-fc` | `GET /api/runtimes`, `GET`/`POST /api/runtimes/fc-e2b(/templates)` |
+| `agent-list` / `agent-get` / `agent-create` | `GET`/`POST /api/agents` |
+| `agent-source` / `agent-source-sync` | `GET /api/agents/{id}/source`, `POST .../source/sync` |
+| `agent-tasks` | `GET /api/agents/{id}/tasks` |
+| `task-trace` | `GET /api/tasks/{taskId}/messages?since=` (+ `GET /api/agent-task-snapshot` for follow-stop) |
+| `issue-tasks` / `issue-timeline` / `issue-usage` | `GET /api/issues/{id}/task-runs` / `/timeline` / `/usage` |
+| `task-snapshot` | `GET /api/agent-task-snapshot` |
+| `autopilot-*` | `GET`/`POST`/`PATCH /api/autopilots`, `POST .../trigger`, `GET .../runs`, `POST .../triggers` |
+| `agent-check` | composite of agents/runtimes/snapshot/tasks/dingtalk endpoints |
+| `dingtalk-bind` / `dingtalk-begin` | `POST /api/workspaces/{id}/dingtalk/install/manual` / `install/begin` + status poll |
+| `dingtalk-list` / `dingtalk-revoke` | `GET`/`DELETE .../dingtalk/installations` |
+| `dingtalk-account-*` | `POST`/`GET`/`DELETE .../dingtalk/account-bindings` |
+| `skill-list` / `skill-get` / `skill-pull` / `skill-push` | `GET /api/skills(/{id})`, `POST /api/skills`, `PUT /api/skills/{id}` |
+| `issue-create` / `issue-get` / `issue-list` / `issue-update` | `POST`/`GET`/`PUT /api/issues(/{id})` |
+| `comment-add` / `comment-list` | `POST`/`GET /api/issues/{id}/comments` |
+| `chat-send` | `POST /api/chat/sessions(/{id}/messages)` + `GET .../pending-task` + `GET .../messages` |
+| `member-list` / `member-invite` | `GET`/`POST /api/workspaces/{id}/members` |
+| `token-create` | `POST /api/tokens` |
+
+Auth: `Authorization: Bearer <token>`; workspace-scoped generic routes use
+the `X-Workspace-ID` header, `/api/workspaces/{id}/...` routes take the UUID
+in the path. No cookies, no CSRF.
+
+## Distribution
+
+This directory is self-contained (SKILL.md + scripts):
+
+- Import into any Multica workspace: `multica skill import` from a URL or
+  `.skill`/`.zip` archive, or `skill-push` from this script. Files land in
+  agent envs without the exec bit — always invoke via
+  `python3 .../multica_ext.py` / `sh .../bootstrap.sh`, never `./x`.
+- Or vendor into a dedicated git repo later; nothing depends on this
+  monorepo.
+
+### Bootstrap: getting this skill onto a fresh machine
+
+The workspace itself is the registry — no extra storage needed. `skill-pull`
+lives inside the skill, so the first fetch uses `scripts/bootstrap.sh`
+(copy it from a runbook, teammate, or this repo):
+
+```bash
+# Path A — authenticated multica CLI (no pull command needed: skill get
+# outputs everything; bootstrap just writes it to disk):
+sh bootstrap.sh --profile pre-fde --workspace-id <uuid> [--dest <dir>]
+
+# Path B — no CLI at all, just endpoint + token (+ curl, python3):
+MULTICA_SERVER_URL=... MULTICA_TOKEN=... MULTICA_WORKSPACE_ID=... \
+  sh bootstrap.sh --curl [--dest <dir>]
+```
+
+Both paths produce a byte-identical copy of what `skill-push` uploaded, and
+bootstrap.sh ships inside the bundle, so a pulled copy can bootstrap the
+next machine. After bootstrap, stay current with
+`python3 scripts/multica_ext.py skill-pull --skill multica-external --dest . --force`.
+
+Equivalent one-liner where bootstrap.sh is unavailable:
+
+```bash
+multica skill get <skill-id> --output json | python3 -c '
+import json,sys,pathlib
+sk=json.load(sys.stdin); d=pathlib.Path(sk["name"]); d.mkdir(exist_ok=True)
+(d/"SKILL.md").write_text(sk.get("content") or "")
+for f in sk.get("files") or []:
+    p=d/f["path"]; p.parent.mkdir(parents=True,exist_ok=True); p.write_text(f.get("content") or "")'
+```
+
+OSS (or any object store) is an optional *anonymous* channel — useful only
+when the target machine has no Multica credentials yet. It needs a publish
+step on every update and bucket/ACL management, so prefer the
+workspace-as-registry paths above when a token exists.

package/skills/platforms/multica-dingtalk/multica-external/scripts/bootstrap.sh

@@ -0,0 +1,78 @@
+#!/bin/sh
+# Bootstrap: fetch the multica-external skill from a Multica workspace
+# onto this machine. Solves the chicken-and-egg problem (skill-pull lives
+# inside the skill) using only tools already present: the multica CLI, or
+# curl with endpoint+token. python3 is required either way (the skill's
+# script needs it too).
+#
+#   Path A (default) — authenticated multica CLI:
+#     sh bootstrap.sh [--profile <name>] [--workspace-id <uuid>] [--dest <dir>]
+#   Path B — no CLI, just endpoint + token:
+#     MULTICA_SERVER_URL=... MULTICA_TOKEN=... MULTICA_WORKSPACE_ID=... \
+#       sh bootstrap.sh --curl [--dest <dir>]
+#
+# curl runs with --noproxy '*' so an exported shell proxy cannot break
+# intranet/pre endpoints (the Go CLI needs proxies unset by the caller).
+set -eu
+
+SKILL_NAME="multica-external"
+DEST=""
+PROFILE=""
+WS_ID=""
+MODE="cli"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --profile) PROFILE="$2"; shift 2 ;;
+    --workspace-id) WS_ID="$2"; shift 2 ;;
+    --dest) DEST="$2"; shift 2 ;;
+    --name) SKILL_NAME="$2"; shift 2 ;;
+    --curl) MODE="curl"; shift ;;
+    *) echo "unknown argument: $1" >&2; exit 1 ;;
+  esac
+done
+
+RESOLVE='
+import json, sys
+name = sys.argv[1]
+ids = [s.get("id") for s in json.load(sys.stdin) if isinstance(s, dict) and s.get("name") == name]
+print(ids[0] if ids else "", end="")
+'
+
+UNPACK='
+import json, sys, pathlib
+sk = json.load(sys.stdin)
+dest = sys.argv[1] if len(sys.argv) > 1 and sys.argv[1] else sk["name"]
+d = pathlib.Path(dest)
+d.mkdir(parents=True, exist_ok=True)
+(d / "SKILL.md").write_text(sk.get("content") or "", encoding="utf-8")
+count = 1
+for f in sk.get("files") or []:
+    rel = f.get("path") or ""
+    parts = pathlib.Path(rel).parts
+    if not parts or pathlib.Path(rel).is_absolute() or ".." in parts or rel == "SKILL.md":
+        continue
+    p = d / rel
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(f.get("content") or "", encoding="utf-8")
+    count += 1
+print("pulled %d file(s) -> %s" % (count, d.resolve()))
+'
+
+if [ "$MODE" = "cli" ]; then
+  CLI="multica"
+  [ -n "$PROFILE" ] && CLI="$CLI --profile $PROFILE"
+  [ -n "$WS_ID" ] && CLI="$CLI --workspace-id $WS_ID"
+  SID=$($CLI skill list --output json | python3 -c "$RESOLVE" "$SKILL_NAME")
+  [ -n "$SID" ] || { echo "skill \"$SKILL_NAME\" not found in the workspace" >&2; exit 1; }
+  $CLI skill get "$SID" --output json | python3 -c "$UNPACK" "$DEST"
+else
+  : "${MULTICA_SERVER_URL:?set MULTICA_SERVER_URL}"
+  : "${MULTICA_TOKEN:?set MULTICA_TOKEN}"
+  : "${MULTICA_WORKSPACE_ID:?set MULTICA_WORKSPACE_ID}"
+  AUTH="Authorization: Bearer $MULTICA_TOKEN"
+  WS="X-Workspace-ID: $MULTICA_WORKSPACE_ID"
+  SID=$(curl -fsS --noproxy '*' -H "$AUTH" -H "$WS" "$MULTICA_SERVER_URL/api/skills" | python3 -c "$RESOLVE" "$SKILL_NAME")
+  [ -n "$SID" ] || { echo "skill \"$SKILL_NAME\" not found in the workspace" >&2; exit 1; }
+  curl -fsS --noproxy '*' -H "$AUTH" -H "$WS" "$MULTICA_SERVER_URL/api/skills/$SID" | python3 -c "$UNPACK" "$DEST"
+fi