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,53 @@
+## ADDED Requirements
+
+### Requirement: Unified Skill data model
+The system SHALL represent every Skill with shared metadata (id, name, description, version, tags, source/subscription id, updated_at) and a `kind` discriminator of either `knowledge` or `flow_template`, so both kinds can be listed and searched through one catalog.
+
+#### Scenario: Knowledge skill has content
+- **WHEN** a Skill with `kind = knowledge` is stored
+- **THEN** it includes a `content` field (structured instructional text/markdown) in addition to the shared metadata
+
+#### Scenario: Flow-template skill has steps and parameters
+- **WHEN** a Skill with `kind = flow_template` is stored
+- **THEN** it includes an ordered `steps` list (each referencing a tool name and an args template that may contain `{param}` placeholders) and a `parameters` schema (name, type, required, description) in addition to the shared metadata
+
+### Requirement: Local skill storage
+The system SHALL persist the synced Skill Catalog locally so that skills can be listed and fetched without a live round-trip to the Subscription Platform for every query.
+
+#### Scenario: Skill readable after sync
+- **WHEN** a skill has been synced from the Subscription Platform into the local catalog
+- **THEN** subsequent list/search/get operations return that skill without requiring a new network call to the Subscription Platform
+
+#### Scenario: Local catalog is not independently authored
+- **WHEN** a caller attempts to create or edit a skill directly in the local catalog (outside of a sync operation)
+- **THEN** the system SHALL reject or ignore the write, since the Subscription Platform is the sole source of truth for skill content
+
+### Requirement: Skill search and query
+The system SHALL provide functions to list all currently visible skills, search skills by name/tag/description text, and fetch a single skill by id.
+
+#### Scenario: List returns only visible skills
+- **WHEN** the catalog is queried for the list of skills visible to the current caller
+- **THEN** it returns only skills whose subscription is currently active for that caller, sorted in a stable order (e.g. by name)
+
+#### Scenario: Search matches on name, tags, or description
+- **WHEN** a search query string matches a skill's name, a tag, or its description
+- **THEN** that skill is included in the search results
+
+#### Scenario: Get by id returns full content
+- **WHEN** a caller fetches a skill by its id
+- **THEN** the system returns the full skill record, including `content` for knowledge skills or `steps`/`parameters` for flow-template skills
+
+#### Scenario: Get by id for unknown or invisible skill
+- **WHEN** a caller fetches a skill id that does not exist, or exists but is not currently visible to them (subscription inactive)
+- **THEN** the system returns a clear "not found" result rather than leaking the skill's existence or content
+
+### Requirement: Flow-template tool reference validation
+The system SHALL validate that a flow-template skill's referenced tool names correspond to currently registered device-capability tools, and SHALL mark a flow-template skill as invalid/unavailable rather than allowing it to be fetched successfully if a referenced tool does not exist.
+
+#### Scenario: Valid flow template
+- **WHEN** every step in a flow-template skill references a tool name that is currently registered
+- **THEN** the skill is fetchable and returned normally
+
+#### Scenario: Flow template references an unknown tool
+- **WHEN** a flow-template skill's steps reference a tool name that is not currently registered (e.g. renamed or removed)
+- **THEN** fetching that skill returns a clear "skill unavailable/invalid" result instead of a step list containing a dangling tool reference