yugoo-design 0.1.2 → 0.2.2

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/function_modules/reference/artifact-contract.md

@@ -0,0 +1,204 @@
+# function_modules output contract
+
+For canvas generation or revision, read [the canvas guide](canvas-guide.md).
+It supplements the existing methods and output contract; it applies to both
+new design and reconstruction without replacing domain-specific rules.
+
+## Source-to-capability judgment
+
+For new design, derive candidate capabilities from established user outcomes;
+a source product is evidence or inspiration, not automatic approval to copy its
+scope. For reconstruction, trace a visible entry through its reachable behavior
+and outcome before naming the capability. A folder, route, dependency, disabled
+control or mock alone does not establish that the product offers that behavior.
+Group by user purpose, not the source tree. Preserve evidenced administrative
+capabilities when administration is part of the actual product.
+
+Keep intended, implemented and runtime-observed behavior distinct. Record
+material source locations and limits in existing explanatory text or the handoff;
+do not put external repository paths into Design File pinned references.
+For a revision, reconcile source findings with saved user decisions, rejected
+cards and local details rather than replacing the map with a fresh inventory.
+Missing source coverage is an uncertainty, not proof that a capability is absent.
+Do not invent features to complete a journey or erase established features to
+make the map smaller; report the concrete gap within the requested scope.
+
+Shared by ordinary design and reconstruction. Canonical state is
+`function_modules/function_modules.json`; the installed schema and validation remain
+authoritative. This reference describes representation and semantic checks,
+not permission to invent facts, choose new policy or trigger user review.
+Examples and design recommendations below are not source evidence. In
+reconstruction, preserve observed behavior and supported uncertainty; report
+required facts that cannot be represented rather than fabricating a value.
+
+Functions express user-visible capabilities at a coherent granularity, not a directory inventory. Preserve evidenced scope; do not remove a real product capability because a template example omits it. Product-facing administration can be a capability; internal deployment work alone is not.
+
+## Output contract
+
+Persist only the declared function fields below. Functions are the entities;
+`function_epic` is a grouping label. Optional details enrich that function, not
+a second story collection. Rejected functions remain in rejected/full views.
+
+### Purpose
+
+Produce a concise, user-facing function map. A function is the only persisted
+entity. `function_epic` is merely its grouping label; the panel groups
+functions by that label when it renders.
+
+### Usage
+
+Maintain the function map as complete state JSON, preserving unaffected fields.
+Run `design_validate({outcome:"complete"})`, repair named state defects, and
+publish through `design_publish({action:"complete"})`. The panel renders from
+the published Design File. Panel saves already persist the user's card edits;
+do not repeat them.
+
+### Data contract
+
+Keep the existing overview shape. The current contract uses a single usage scenario;
+do not send it to a differently pinned validator or rewrite its retained state.
+
+```json
+{
+  "functions": {
+    "F-001": {
+      "function_id": "F-001",
+      "function_name": "记账录入",
+      "function_description": "记录收入、支出及其分类。",
+      "function_epic": "账本管理",
+      "priority": "High",
+      "rejected": false,
+      "source": "ai",
+      "reason": "家庭账本的核心使用动作"
+    }
+  }
+}
+```
+
+- `function_id`, `function_name`, `function_description`, `function_epic`
+  are required for every function. `priority` is optional (panel default Medium).
+- `rejected` means the user rejected the function. It remains visible in the
+  rejected filter and may be restored. It is not deletion.
+- `source` identifies the card's origin. Optional `reason`, shown as Notes, can
+  contain the proposal's basis, design rationale, tradeoffs, supplementary context
+  and unresolved points. It does not establish user approval.
+- Never persist Epic as a separate entity or duplicate function membership in
+  additional lists.
+
+### Optional local specification
+
+`details` is a closed object with one optional `situation` string (Usage scenario),
+plus optional `behaviors`, `inputs`, `outputs`, `limits`, `exceptions` maps.
+The first four maps have stable keys and closed values `{ "description": "..." }`.
+Exceptions have closed values `{ "condition": "...", "response": "..." }`.
+Their required fields apply only to existing entries; no dimension is required.
+Do not add approval, completeness, formal story, or per-field status metadata.
+Stable map keys are identities, not names or ordering positions; preserve them
+when editing. Card description remains a short capability overview. The usage
+scenario explains who uses it, under which circumstances and for what outcome;
+it combines the former purpose and situation. Notes supplement the design, not
+replace core behaviors, inputs, outcomes, boundaries or exception handling.
+The Panel displays fixed optional inputs, directly editable without a read/edit
+switch or dimension add/delete. Empty/absent dimensions remain legitimate;
+collection item add/delete still operates on stable keys.
+
+Example added to an existing function (hypothetical, not user evidence):
+
+```json
+{
+  "details": {
+    "situation": "用户整理综述中的论点时，查看已保存的材料及原文，判断依据是否充分。",
+    "behaviors": { "B-001": { "description": "选择论点后查看已关联的文献摘录和笔记。" } },
+    "inputs": { "I-001": { "description": "用户选中的论点和已有材料关联。" } },
+    "outputs": { "O-001": { "description": "依据及原文位置，没有依据则明确告知。" } },
+    "limits": { "L-001": { "description": "不把 AI 推测当作原文已支持论点的证明。" } },
+    "exceptions": { "E-001": { "condition": "关联原文不可读取。", "response": "保留来源标识，告知暂不可读，不虚构摘录。" } }
+  }
+}
+```
+
+The local usage scenario is not a second product background authority. Local conditions,
+limits and failure responses are permitted even if testable; shared rules,
+cross-function flows, common data/access definitions and formal acceptance
+retain their existing owning Bundles. Refer to them only when actually present.
+Do not force those Bundles to run just to explain known local behavior.
+
+### Optional pinned sources
+
+`references` is a stable-key map. Each closed record has required `file` and
+`revision`, optional `pointer`, `note`, and `subject_pointer` strings. No other
+fields exist. `file` is confined relative to this project's Design Files, never
+an absolute path, traversal, host transcript, or `.git` path. `revision` is a
+real full project commit hash (40 or 64 lowercase hexadecimal characters),
+not HEAD or a placeholder. `pointer` is an RFC 6901 JSON Pointer; omit it for a
+whole-file source. JSON Pointer is only valid for a JSON file. `note` explains
+why the source matters, not a copy of its content or evidence of confirmation.
+
+`subject_pointer` optionally locates a detail in the current owning function,
+for example `/details/behaviors/B-001`. It must exist there, not in the target
+file, and must not traverse an array position. Omit it to refer from the whole
+function. A map source pointer keeps identity through display renaming; an
+array-element pointer remains historical evidence only in this version, even
+if the array contains ID fields. Do not guess current identity from an index.
+
+Unsafe formats or missing local subjects fail mechanical validation. A valid
+source's history or current target may later become unavailable; preserve the
+reference and report unreadability/deletion, never invent an endpoint. The
+source browser must distinguish the pinned evidence from a later edited source;
+old content is not stronger than a later explicit user decision. References
+provide location, not causal/support semantics or automatic confirmation.
+
+Preserve all optional detail and source fields during overview editing, panel
+save, complete-state publication, and reconstruction. Source is not approval;
+`source: ai`/`user` and nonempty content do not introduce a confirmation state.
+Overview-only cards need no empty templates or changed IDs. Viewing never
+converts retained state. During internal development, manifest versions stay
+at 1.0; that label does not mean an edited schema accepts every earlier shape.
+Adopting changed definitions must explicitly validate existing data against the
+actual loaded contract. Convert split fields before saving under this contract;
+do not assume selecting the Mindset alone transforms old data. Preserve retained
+snapshots and historical evidence rather than overwriting them to force a refresh.
+
+### Explicit conversion of split purpose/situation
+
+Only for an authorized conversion from the split-field contract,
+`scripts/merge-usage-scenario.mjs` accepts
+the complete old state as JSON on stdin and emits a transformed copy on stdout.
+It is a Bundle resource, not a Core migration hook or an automatic Panel load
+operation. Invoke it through the existing confined script capability when
+available; the executor then validates and publishes the returned state through
+its normal WorkingCopy. A script receipt alone is not a saved migration.
+
+The converter joins both original strings verbatim with a blank line, removes
+`details.purpose`, and keeps the existing `details.situation` when purpose is
+absent. It does not invent a scenario for an empty card. Local reference
+`subject_pointer: /details/purpose` moves to the present `/details/situation`;
+stable keys, other content, file/revision and source `pointer` remain unchanged.
+Pinned source pointers describe historical evidence and must not be rewritten.
+Invalid split values fail rather than being stringified or silently dropped.
+After conversion, use the target schema and source-location validation, check
+the complete diff, and settle the explicit project upgrade using the existing
+project flow. Never retarget another active project or edit its history.
+
+### Quality rules
+
+- Make the function set complete, non-overlapping, and at a consistent level
+  of granularity.
+- Every active function needs a clear, user-facing description and one Epic
+  label.
+- Keep active function names unique.
+- Do not turn internal deployment or infrastructure work into product functions.
+  If managing deployments or servers is the actual user-facing product capability,
+  retain it; judge the product boundary, not the technical vocabulary.
+
+### Example
+
+```text
+// the function_modules state JSON you output:
+{
+  "functions": {
+    "F-001": {"function_id": "F-001", "function_name": "记账录入", "function_description": "记录收入、支出及其分类。", "function_epic": "账本管理", "priority": "High", "rejected": false, "source": "ai", "reason": "核心记账动作"},
+    "F-002": {"function_id": "F-002", "function_name": "账目浏览", "function_description": "按日期和分类查看历史账目。", "function_epic": "账本管理", "priority": "High", "rejected": false, "source": "ai", "reason": "用于回顾收支"}
+  }
+}
+```

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/function_modules/reference/canvas-guide.md

@@ -0,0 +1,52 @@
+# Function capability-map canvas guide
+
+Read [the output contract](artifact-contract.md) for the complete function,
+local specification, pinned-source and explicit-conversion methods. This guide
+supplements those methods; examples are not evidence about the user's product.
+
+## Purpose and evidence
+
+Use the map to orient the user among product capabilities and their Epic groups,
+not to describe Agent collaboration or implementation dependencies. In new design,
+derive capabilities from user outcomes; in reconstruction, follow evidenced entries,
+behavior and outcomes. During revision preserve saved decisions, rejected functions,
+local details and references. Missing coverage is uncertainty, not an absent feature.
+
+## Representation and canonical facts
+
+The implemented `record_board` contains a read-only navigation mindmap as well as
+the grouped cards. Each function is one canonical entity. `function_epic` is a
+grouping label; the canvas projects group-to-function membership from it. Epic
+nodes and connecting edges are display objects, not new persisted entities.
+Do not add edge collections, graph coordinates, separate Epic records or duplicate
+membership lists to the state. A group label is not an independently verified
+business relationship. Keep stable function keys when labels change.
+
+## Generation and layout responsibility
+
+First identify user-facing functions at consistent granularity, then group them
+by user purpose, then check the canvas and cards against the same facts. Retain
+real administrative capabilities when administration is part of the product.
+The current renderer lays out a horizontal mindmap; it owns temporary node
+positions and routes. The Agent authors the function map, not view geometry.
+Do not impose AI three-band anatomy or infer sequence from the map's positions.
+
+## Interaction, uncertainty and density
+
+The current map is navigation, not a draggable or connectable graph editor.
+Use supported selection/detail affordances and the existing card/form save path;
+viewing must not migrate state or erase optional details. Rejected functions remain
+canonical records and use the existing filter/restore behavior, not deletion.
+Unknown details can remain absent. Preserve readable group labels and node titles;
+dense content needs navigation/zoom or filtering, not removal of evidenced functions.
+Pinned references locate historical evidence; they do not establish approval.
+
+## Examples and checks
+
+The two bookkeeping functions in the output contract share one Epic label: expect
+one projected group and two function nodes, not a second Epic JSON collection.
+Negative cases: reorganizing by repository folders, fabricating a capability to
+complete a journey, writing mindmap geometry into state, or dropping rejected and
+optional detail records during overview editing. Validate actual schema/source
+locations and compare retained state. Distinguish resource loading, rendered map
+navigation, durable save/reopen and native generation; one does not prove another.

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/function_modules/reference/preview.json

@@ -0,0 +1,32 @@
+{
+  "functions": {
+    "F-PREVIEW-001": {
+      "function_id": "F-PREVIEW-001",
+      "function_name": "保存阅读材料",
+      "function_description": "合成预览示例：记录材料标题和链接，方便以后继续阅读。不是用户已确认需求。",
+      "function_epic": "个人阅读",
+      "priority": "High",
+      "source": "ai",
+      "reason": "仅用于展示功能卡片与嵌套详情。",
+      "rejected": false,
+      "details": {
+        "situation": "合成示例中的读者遇到暂时没有时间阅读的材料时，保存阅读入口，方便以后继续阅读。",
+        "behaviors": {"B-001": {"description": "填写标题与链接后保存材料。"}},
+        "inputs": {"I-001": {"description": "材料标题和链接。"}},
+        "outputs": {"O-001": {"description": "可再次打开的材料记录。"}},
+        "limits": {"L-001": {"description": "此示例不承诺自动抓取全文。"}},
+        "exceptions": {"E-001": {"condition": "链接为空。", "response": "提示补充链接，保留已填标题。"}}
+      }
+    },
+    "F-PREVIEW-002": {
+      "function_id": "F-PREVIEW-002",
+      "function_name": "查找已存材料",
+      "function_description": "合成预览示例：按标题关键词查找已保存的材料，并返回阅读入口。",
+      "function_epic": "个人阅读",
+      "priority": "Medium",
+      "source": "ai",
+      "reason": "与保存材料构成可理解的示例旅程，不代表用户确认。",
+      "rejected": false
+    }
+  }
+}

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/function_modules/schema.yaml

@@ -0,0 +1,93 @@
+# function_modules Design Files data contract (write-time validation).
+# Faithful declarative translation of sdk-pilot
+# skill/design_skills/function_modules/schema.py (Pydantic, extra="forbid").
+#
+# Functions are the only persisted entities. `function_epic` is a label on a
+# function; the Epic -> functions hierarchy is an emit-time projection. Epic
+# is never an entity. The current contract combines local purpose/situation into one
+# usage scenario; pinned sources and other local detail maps retain their meaning.
+type: object
+additional_properties: false
+properties:
+  skill_name: { knowledge: { role: metadata }, type: string }
+  functions:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [function_id, function_name, function_description, function_epic]
+      properties:
+        function_id: { type: string }
+        function_name: { type: string }
+        function_description: { type: string }
+        function_epic: { type: string }
+        priority: { type: enum, values: [High, Medium, Low] }   # default Medium
+        rejected: { type: boolean }                              # default false
+        source: { type: enum, values: [ai, user] }               # default ai
+        reason: { type: string } # Optional notes: rationale, tradeoffs and unresolved points.
+        details:
+          type: object
+          additional_properties: false
+          knowledge: { role: content, granularity: container, label: 功能详情 }
+          properties:
+            situation: { type: string } # Who, in which situation, seeking which outcome.
+            behaviors:
+              type: map
+              value:
+                type: object
+                knowledge: { role: content, granularity: unit, label: 核心行为 }
+                additional_properties: false
+                required: [description]
+                properties:
+                  description: { type: string }
+            inputs:
+              type: map
+              value:
+                type: object
+                knowledge: { role: content, granularity: unit, label: 输入 }
+                additional_properties: false
+                required: [description]
+                properties:
+                  description: { type: string }
+            outputs:
+              type: map
+              value:
+                type: object
+                knowledge: { role: content, granularity: unit, label: 结果 }
+                additional_properties: false
+                required: [description]
+                properties:
+                  description: { type: string }
+            limits:
+              type: map
+              value:
+                type: object
+                knowledge: { role: content, granularity: unit, label: 范围边界 }
+                additional_properties: false
+                required: [description]
+                properties:
+                  description: { type: string }
+            exceptions:
+              type: map
+              value:
+                type: object
+                knowledge: { role: content, granularity: unit, label: 异常处理 }
+                additional_properties: false
+                required: [condition, response]
+                properties:
+                  condition: { type: string }
+                  response: { type: string }
+        references:
+          # Source locator mechanics are not standalone product-content nodes.
+          knowledge: { role: metadata, source_reference: true }
+          type: map
+          value:
+            type: object
+            additional_properties: false
+            required: [file, revision]
+            properties:
+              file: { type: string }
+              pointer: { type: string }
+              revision: { type: string }
+              note: { type: string }
+              subject_pointer: { type: string }

package/payload/shared/authoring/studio-creators/source/packages/skills-web-app/bundles/function_modules/validation.yaml

@@ -0,0 +1,21 @@
+# function_modules validation contract.
+# Issue codes, messages and repair hints ported verbatim from sdk-pilot
+# skill/design_skills/function_modules/validation.py.
+skill: function_modules
+
+rules:
+  - id: empty
+    scope: [state]
+    code: function_modules.empty
+    message: "At least one function module is required."
+    repair_hint: "Add the product's smallest useful set of function cards."
+    check: { non_empty_map: functions }
+
+  - id: source-locations
+    scope: [state, completion]
+    code: function_modules.source_location
+    message: "Source locations require confined paths, exact commits and valid pointers; a subject must exist in its owning function."
+    repair_hint: "Repair the locator, or omit an unsupported reference without fabricating a target. Missing historical data is shown by source reading, not guessed."
+    check: { for_each_in_map: functions, source_reference_map: references }
+
+  # Rich card-quality checks remain Producer self-checks in SKILL.md.