菜单
Use when adding a route under /internal/* in remote-server. Covers the split auth model (global loopback middleware + per-handler bearer check that is easy to omit) and the active-run-guard decision for any route that runs an agent turn.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Select and run proportionate validation for changes to apps/canvas-workspace. Use when iterating on Canvas Workspace code, finishing a feature or fix, preparing release evidence, or deciding whether a full performance report is necessary.
Deep-research a topic and build a structured Pulse Canvas workspace with approved research depth, source-backed findings, progressive or final canvas creation, spatially organized frames, content nodes, and connections. Use when the user asks to bootstrap, generate, research, organize, or build an AI-created canvas.
Extend an existing Pulse Canvas frame with local, source-backed research while preserving the surrounding canvas. Use when the user asks to research, enrich, expand, verify, update, or add sources/details inside a selected or named frame, rather than bootstrapping a whole new canvas.
Operate Pulse Canvas workspaces — read user-curated context, write results, create nodes
Add or change a Pulse Canvas capability that must be available through structured agent tools and the pulse-canvas CLI. Use for cross-workspace Capability Runtime changes spanning apps/canvas-workspace, packages/canvas-cli, or packages/cli, including new live read, operate, or unsafe application actions.
Run the canvas-workspace performance evaluation, publish the latest static dashboard through the local nginx/Cloudflare Tunnel route, capture a screenshot, and summarize the report. Use when the user asks to run Pulse Canvas/canvas-workspace perf checks, deploy the performance dashboard, refresh https://jasperhu.art/apps/canvas-perf/, or send a dashboard screenshot from Feishu/remote-server.
| name | add-internal-route |
| description | Use when adding a route under /internal/* in remote-server. Covers the split auth model (global loopback middleware + per-handler bearer check that is easy to omit) and the active-run-guard decision for any route that runs an agent turn. |
An ordered procedure. Two traps: the bearer check is per-handler (not
middleware), and any route that runs an agent turn sits OUTSIDE the
active-run guard unless you opt it in. FACTS live in src/routes/internal.ts.
Register the handler on internalRouter in src/routes/internal.ts (8 handlers exist: worktrees CRUD+run, discord-gateway status/restart, agent/run).
The auth is SPLIT — the middleware only does half. The global internalRouter.use('*', ...) enforces the loopback check (internal.ts:111-117). The bearer/INTERNAL_API_SECRET check is a per-handler call to verifyInternalAuth/isAuthorizedInternal that every existing handler repeats by hand (internal.ts:121,130,139,148,162,201,229,250). A new handler that forgets it is loopback-protected but NOT secret-protected — reachable by anything on loopback (including any reverse-proxied request, which all look like loopback). Copy the per-handler check; do not assume the middleware covers you.
If the route runs an agent turn, decide about the active-run guard. The internal /agent/run path does NOT hold the per-platformKey active-run guard (harness/knowledge/known-defects.md §1, core-lifecycle.md invariant 1) — a concurrent internal run + platform run on the same platformKey race on one session file with no lock. /agent/run mitigates with default forceNewSession=true (internal.ts:264). If your route can collide on a real platformKey, either mint a fresh session or participate in setActiveRun/hasActiveRun — state which in the PR.
Keep the handler thin. Delegate to dispatcher/agent-runner/service modules; internal routes are automation entrypoints, not logic homes (AGENTS.md constraint).
Secrets never in source or logs. The route runs at the same privilege as everything else — a host-tool run it triggers inherits the full secret env (security-posture.md §1). Don't echo request bodies or env into responses/logs.
Verify. pnpm --filter @pulse-coder/remote-server build + test; smoke from loopback with and without the bearer token to confirm BOTH checks fire (a route that responds without the token has the step-2 bug).
The handler carries its own bearer check (not just the global loopback middleware); the active-run-guard interaction is decided and stated; it stays thin; no secret leakage; loopback smoke confirms both auth halves.
