feat: checkpoint device agent runtime milestones

2026-07-06 17:24:03 +08:00
parent 2d4251e98e
commit 5658735bca
153 changed files with 8060 additions and 65 deletions
@@ -0,0 +1,28 @@
+## Why
+
+Apex Agent's MCP tool server (see change `apex-agent-mvp`) gives the LLM raw device capabilities (tap/swipe/screenshot/...), but it has no notion of reusable, task-specific know-how — e.g. "how to search on Xiaohongshu," or "the tap/swipe/input sequence to place an order on Taobao." Today that knowledge would have to live entirely inside the LLM's own reasoning or be re-derived from scratch on every task. We need a **Skill** concept the AI can discover and pull on demand via MCP, and — since skill content will be authored, versioned, and entitled to specific tenants/devices by a separate, already-planned **Subscription Platform** (统一订阅平台，另一套信息管理系统) — Apex Agent needs a defined contract for consuming that platform's catalog rather than owning skill authoring itself.
+
+## What Changes
+
+- Introduce a **Skill Catalog** capability: a local data model and store for Skills, where a Skill is either a **knowledge skill** (structured instructional/markdown content the AI reads to decide how to act, analogous to Claude Skills) or a **flow-template skill** (a parameterized, predefined sequence of capability calls — e.g. tap/swipe/input steps with placeholders — that the AI mostly fills in parameters for and triggers, rather than re-planning from scratch). Both kinds share common metadata (id, name, description, version, tags) so they can be listed/searched uniformly.
+- Introduce **Skill MCP tools** (`list_skills`, `search_skills`, `get_skill`, `run_skill_flow`-input-resolution helper) exposed through the same MCP surface established in `apex-agent-mvp`'s `mcp-tool-server`, so an LLM can discover which skills are available and fetch their content/flow template without knowing anything about the Subscription Platform underneath.
+- Introduce a **Skill Subscription Sync** capability: a client-side contract for talking to the external Subscription Platform, covering (a) pulling/receiving the catalog of skills a given deployment is entitled to, (b) keeping the local Skill Catalog in sync (create/update/remove on change), and (c) enforcing subscription-based visibility so only skills the current tenant/device/agent is subscribed to are listed or fetchable via the MCP tools.
+- Explicitly out of scope for this change: designing or building the Subscription Platform itself (authoring UI, billing, skill publishing workflow) — it is treated as an existing/external system; this change only defines the integration contract (API shape, sync semantics, auth) Apex Agent needs from it. Also out of scope: automatic skill-authoring/generation by the LLM, and a skill marketplace UI.
+
+## Capabilities
+
+### New Capabilities
+- `skill-catalog`: Local Skill data model (knowledge-doc and flow-template variants), storage, and search/query functions used by both the MCP tools and the sync client.
+- `skill-mcp-tools`: MCP-facing tool surface for listing, searching, and fetching Skill content/flow templates, plus resolving flow-template parameters, without exposing any Subscription Platform or storage detail to the LLM.
+- `skill-subscription-sync`: Contract and client implementation for syncing the Skill Catalog from the external Subscription Platform (pull and/or push), and for enforcing subscription-based visibility/permission scoping per tenant/device/agent.
+
+### Modified Capabilities
+(none — `mcp-tool-server` from the pending `apex-agent-mvp` change is composed with, not modified: this change adds new tools to the same MCP server process rather than changing that capability's existing requirements. If `apex-agent-mvp` has not yet been applied when this change is implemented, the Skill MCP tools should still be registrable on their own MCP server instance and merged in later.)
+
+## Impact
+
+- **New code**: `skills/` package — `skills/models.py` (Skill, KnowledgeSkill, FlowTemplateSkill, SkillMetadata), `skills/catalog.py` (local store + search/query), `skills/sync_client.py` (Subscription Platform client: pull/push, auth, visibility filtering), `skills/mcp_tools.py` (registers `list_skills`/`search_skills`/`get_skill`/flow-param-resolution as MCP tools).
+- **Dependencies**: depends on the `apex-agent-mvp` change for the MCP server process and `tools/`/`runtime/` capability layer that flow-template skills ultimately drive (a flow-template skill's steps still execute through existing `tools/` functions); does not depend on any new external dependency beyond an HTTP client for the sync API.
+- **External systems**: introduces a new external dependency — the Subscription Platform's API (assumed to expose an endpoint to fetch entitled skills and, optionally, a webhook/push channel for change notifications). Exact base URL/auth mechanism is a deployment-time configuration, not a code dependency.
+- **Storage**: adds a local Skill Catalog store (SQLite table(s) alongside the existing task-metadata DB from `apex-agent-mvp`, or an embedded file-based store — to be decided in design) plus a small sync-state table (last-synced version/timestamp per subscription).
+- **Follow-on work explicitly deferred**: Subscription Platform's own design/build, skill-authoring workflows, billing/entitlement logic beyond "is this skill visible to me," and any LLM-driven automatic skill generation.