AGENT SKILL

lifecycle

暂无简介

License 许可
MIT
最近更新
2026-11-14
Stars
★ 0
Forks
0

02 资源文件 3

03 SKILL.md 正文

deploy-lifecycle-api skill

The deploy-lifecycle API provides inspection and mutation of the central-deploy management plane: service inventory, live status and health, environment snapshots, and (when permitted by the deploy server's per-repo access toggle) service restart and env-write. Configuration management is owned by each component internally — use the component's own /config endpoints for configuration access, not the lifecycle API. All secret values in environment responses are masked as *** server-side by _mask_secrets.

Allowed operations

Tool HTTP Description
list_lifecycle_services GET /services List all managed services and status.
get_lifecycle_service_status GET /services/{name} Live status + health-check history.
get_lifecycle_service_env GET /services/{name}/env Runtime environment (secrets masked).
restart_lifecycle_service POST /services/{name}/restart Restart a service (requires per-repo access toggle).
redeploy_lifecycle_service POST /services/{name}/redeploy Redeploy a service — pulls latest image (requires per-repo access toggle).
verify_lifecycle_deployment GET /services/{name} (poll) Poll service until healthy and (optionally) image matches expected ref.
self_restart POST /chat/services/{name}/restart Restart this service (named via lifecycle.service_name).
update_lifecycle_service_env PUT /services/{name}/env Update service environment (requires per-repo access toggle).

Configuration ownership

Configuration is owned by each component internally — use the component's own /config endpoints (e.g. GET /config, PUT /config, POST /config/rollback) for configuration reads and writes, not the lifecycle API. The lifecycle API no longer exposes config-store endpoints (GET /services/{name}/config, PUT /services/{name}/config).

Restricted operations (per-repo access toggle)

The following mutation endpoints are available as tools but succeed only when the deploy server's per-repo access toggle is enabled for this component. When the toggle is not enabled the calls return a 403 error — the agent should treat that as "not permitted" and not retry:

  • POST /services/{name}/restart — restart a service
  • POST /services/{name}/redeploy — redeploy a service (pulls the latest image)
  • PUT /services/{name}/env — update service environment

Enabling the toggle: This is a per-repo setting in the central-deploy dashboard (labelled allow_chat_access or chat_agent_mutatable), not a chat-component config key or environment variable. See the deployment guide for step-by-step instructions.

Deploy registration — check the toggle up front

Registering a component in the deploy plane (POST /chat/services) and every other chat-agent mutation below is gated by the same per-repo allow_chat_access / chat_agent_mutatable toggle. When it is off, all of these calls return 403, so a deploy-registration flow that does not warn early will run several steps and only stall at the first mutation. Warn the user about this requirement up front, before starting the workflow:

  1. The moment the user asks to register or deploy a component (or perform any chat-agent mutation), state the precondition: "Registering/deploying a component requires the allow_chat_access / chat_agent_mutatable toggle to be enabled for this repo in the central-deploy dashboard. If it is off, deployment operations will be blocked with 403."
  2. If the user has not confirmed the toggle is already on, ask them to enable it in the central-deploy dashboard before you proceed, and wait for confirmation.
  3. Only once the toggle is confirmed enabled should you run the registration/deployment steps.

There is no API to read the toggle's current state — the read-only tools (list_lifecycle_services, get_lifecycle_service_status, get_lifecycle_service_env) never report it, and the agent learns it only via a 403 on a mutation call. Because you cannot verify it yourself, treat the toggle as possibly-off and get explicit early confirmation rather than assuming the operation will succeed. This avoids the stalled turns and back-and-forth caused by discovering the 403 mid-flow.

Self-restart

self_restart restarts the agent's own service via POST /chat/services/{name}/restart, where {name} is the configured lifecycle.service_name (the deploy server has no bare /self/restart route). It is granted by the same allow_chat_access / chat_agent_mutatable flag as the other chat-agent restart calls. Use this after a deploy that changed the agent's own capabilities (new component, tool, skill, or permission) so the new capability is picked up. When lifecycle.service_name is unset the tool returns a clear "not configured" message rather than attempting a call.

This tool cannot restart other managed services — for those, use restart_lifecycle_service.

Drain gate. A restart kills every agent turn in flight. self_restart (and restart_lifecycle_service on the agent's own service) therefore defers while other agent turns or subsessions are mid-turn: the reply reads Restart deferred: N other agent turn(s) are still in flight… and the restart is issued automatically once they finish, or after a bounded drain timeout (600 s). Do not call it again after a deferral. Never restart just to apply a periodic.sessions edit — presets hot-reload on PUT /config.

URL protocol handling

If central_deploy.url lacks a URL scheme (e.g. central-deploy:8100), the client prepends the configured lifecycle.default_protocol (default "http"). URLs with recognised schemes (http, https) are left unchanged. An empty base_url produces a clear error message from self_restart instead of a cryptic protocol error — configure central_deploy.url to the deploy-lifecycle API address (e.g. http://central-deploy:8100) to enable the feature.

Retry behaviour

On transient failures (server 5xx errors, network timeouts, connection failures) self_restart retries with exponential backoff before reporting failure. Non-retryable errors (4xx client errors such as 403 Forbidden or 404 Not Found) are returned immediately without retrying.

Retry parameters are configurable via the lifecycle settings:

Setting Default Description
lifecycle.self_restart_max_retries 3 Maximum retries for transient failures. The initial attempt + retries = max_retries + 1 total calls.

When all retries are exhausted the method returns a combined error message describing the number of attempts made and the last error received.

The following endpoints remain forbidden — no tool exists for them and the agent must not attempt to reach them through any other path:

  • DELETE /services/{name} — remove a service registration

Post-merge deployment verification

After merging a PR that changes a tracked component (cost-fix, infrastructure change, or any code change that produces a new container image), do not close the ticket until the new image is confirmed running in production:

  1. Trigger redeploy — call redeploy_lifecycle_service for the affected service.
  2. Verify deployment — call verify_lifecycle_deployment with the expected image reference (e.g. the tag or digest the PR was built from). This polls the service status until the running image matches and the service is healthy.
  3. Re-measure metrics — after the deployment is confirmed, check the key metrics the ticket was meant to improve (cost, latency, error rate, etc.) to confirm the change had the intended effect.
  4. Only then close the ticket — when deployment is verified and metrics are confirmed.

The verify_lifecycle_deployment tool accepts an expected_image_ref that is matched by substring against the running image identifier. You can pass a tag (:main), a digest prefix (sha256:abc123), or a full reference. When expected_image_ref is empty, the tool verifies only that the service is running and healthy.

Safety

The three read-only tools are pure reads — they make no state changes and can be called freely for diagnostics and investigation. The two mutation tools (restart, env-write) make real state changes and are gated by the deploy server's per-repo access toggle. The self_restart tool is a mutation that restarts the agent's own service (named via lifecycle.service_name) — it should only be called when the agent needs to pick up a new capability after a deploy. Secret masking is enforced server-side; the agent never sees raw credentials.

Operating rules (moved from the system prompt, 2026-09-08)

Deploy tools and the deploy plane

– Deploy API (lifecycle tools): • restart_lifecycle_service — restart any service (needs per-repo toggle) • self_restart — restart the agent's own service (no toggle required) • update_lifecycle_service_env — update service environment – Deploy system: The robotsix-deploy (central-deploy) management plane is a runtime API server, not a git repository — component onboarding, lifecycle operations, and configuration changes are all API-driven (POST /onboard/preflight, /onboard/confirm, etc.). The deploy/docker-compose.yml in each component repo is the contract central-deploy reads at onboard time; no git PR to the central-deploy repo is ever needed. Do not suggest git PRs or repo changes for central-deploy onboarding or lifecycle operations. – Deploy pre-check: after a migration or fix ticket is done and the user requests a deploy, first verify the associated PR is merged — query its status via the mill's ticket endpoint (GET /tickets/{id}) or check the PR on GitHub directly, rather than asking the user for confirmation. If the PR is not yet merged, explain the blocker clearly and offer to wait for the merge or escalate. Only proceed with the deploy (restart) after confirming the merge is complete. – Deploy preflight: before calling any deploy endpoint (POST /chat/deploy, POST /onboard/*, or any lifecycle mutation), you MUST:

  1. Retrieve the target component repo's deploy/docker-compose.yml and count its services, volumes, healthchecks, and commands.
  2. Check the chat_agent_deployable_components allowlist (via component_request to central-deploy or the roster) — if the component is not listed, refuse to proceed and report the missing allowlist entry; never attempt to deploy a component that is not explicitly authorised for chat-agent deployment.
  3. Compare the contract against the endpoint's known capabilities: single-container endpoints cannot deploy multi-service compose files, named volumes, multiple networks, or healthcheck stanzas. If the endpoint cannot reproduce the full contract, refuse to proceed and explain which contract elements are unsupported. Do NOT offer to deploy through an endpoint whose capabilities you have not verified — guessing causes failed deploys and wastes operator time. If you cannot determine the endpoint's capabilities (e.g. the server is running an older version whose deploy support is unknown), state that limitation and ask the operator to verify before proceeding. – Contract-version troubleshooting: When a user encounters a "missing or incorrect central-deploy-contract-version header" error during onboarding, diagnose concretely before suggesting a ticket: (a) check whether the component's deploy/docker-compose.yml has "# central-deploy-contract-version: N" as its very first line — if the header is missing, the fix is to add it (the version number is in the repo's own deploy/docker-compose.yml); walk the user through adding it. (b) If the header is present but central-deploy rejects it, check the component's recent PRs for a version bump — a recent merge may have changed the expected version. (c) If the correct version remains unclear after checking the repo, file a ticket on the component repo to clarify the expected contract version.

After a merge

– After a successful merge, immediately check whether the change is live in production: use get_lifecycle_service_status on the affected component to confirm the new image is deployed and healthy. A merged PR whose image is not yet deployed is not truly done — report the deployment status alongside the merge result (never as a separate follow-up), clearly state the deployment gap if the change is not yet live, and offer to track deployment progress or help trigger a deploy. When a deployment gap exists (PR merged but service still running older image), your merge-report message MUST explicitly name the gap and suggest the concrete next step — e.g. 'The fix is merged. To make it live, deploy the update and restart the service.' Do NOT end a conversation or session after a merge without first informing the user of any deployment gap. Never claim a change is complete without confirming its deployment status.

Configuration advice and capability probes

– Service configuration standard (robotsix-standards): Every service in the fleet is configured by a single config.json file with lowercase key names, not env-style UPPERCASE variables. Refer to configuration values by their lowercase JSON key path (e.g. radicale.url, radicale.username, radicale.password), never by uppercase env-var-style names (e.g. RADICALE_URL, RADICALE_USERNAME, RADICALE_PASSWORD). The config file is one JSON document mounted into the container via a volume — the operator (or the deploy pipeline) edits that JSON file and the merged result is written before each start; a value is set or changed by editing config.json, not by exporting an environment variable. Do not invent or recommend environment variables for service configuration. Use environment variables only when a component explicitly requires one (e.g. ROBOTSIX_CONFIG_FILE merely locates the config file). – When advising on configuration settings for a component (secrets, labels, environment variables, deploy contracts, feature flags), first retrieve and analyse the relevant source code through available tools to confirm the actual implementation. Do not rely on assumptions or outdated recollection — central infrastructure may already handle the setting fleet-wide (e.g. central-deploy’s docker_sdk.py may inject secrets and labels automatically), making per-repo configuration advice redundant or incorrect. Verify the source of truth before giving configuration guidance. – Server-side capability probes: when checking whether a new server-side capability (e.g. a new HTTP endpoint like POST /chat/deploy) is available, probe the target server's endpoint directly with a GET request rather than relying on static skill descriptions, roster entries, or the audit log. A catch-all 303 redirect from an old build does NOT confirm the capability is present — only a meaningful status code (405 Method Not Allowed, 422 Unprocessable Entity, etc.) from the endpoint itself indicates the route exists. Before concluding a capability is live, check the server's running image digest (via the health endpoint or deploy status) against the expected digest from the merged PR that introduced the capability. Report the digest comparison to the user so they can independently confirm. – Endpoint path verification: before probing any server-side endpoint with http_probe or component_request, confirm the exact registered path from the source code (e.g. the Route() registrations in the app factory or the routes module). Do not guess or infer endpoint paths from naming conventions, module names, or partial memory — a guessed path like /mobile/auth/login when the actual route is /auth/login will return a misleading 400 or 401 instead of a 404, confusing the operator about whether the endpoint exists. Read the route definitions first, then probe the confirmed path.

04 同仓库更多 Skills