create-yss-spec 2.1.8 → 2.1.10

package/README.md

@@ -33,7 +33,7 @@ npx create-yss-spec@latest
 - 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
 - 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
 
-本次模板适配按 `2.1.6` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次模板适配按 `2.1.10` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
 
 ## 接管已有项目
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "2.1.8",
+  "version": "2.1.10",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -18,6 +18,15 @@ const TEMPLATE_MANIFEST = JSON.parse(TEMPLATE_MANIFEST_TEXT);
 const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
 const ROOT_EXCLUDED_FILES = new Set(TEMPLATE_MANIFEST.excludeRootFiles);
 const EXCLUDED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.excludePaths);
+const INIT_EXCLUDED_ROOT_ENTRIES = new Set(
+  TEMPLATE_MANIFEST.initExcludeRootEntries || [],
+);
+const INIT_EXCLUDED_ROOT_FILES = new Set(
+  TEMPLATE_MANIFEST.initExcludeRootFiles || [],
+);
+const INIT_EXCLUDED_RELATIVE_PATHS = new Set(
+  TEMPLATE_MANIFEST.initExcludePaths || [],
+);
 const RENDERED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.renderPaths);
 const EXAMPLE_DOC_PATHS = new Set(TEMPLATE_MANIFEST.exampleDocPaths);
 const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
@@ -323,12 +332,20 @@ function targetPath(targetDir, relativePath) {
   return resolved;
 }
 
-function shouldExcludeRelativePath(relativePath) {
-  return EXCLUDED_RELATIVE_PATHS.has(normalizeRelativePath(relativePath));
+function shouldExcludeRelativePath(relativePath, mode = "managed") {
+  const normalized = normalizeRelativePath(relativePath);
+  return EXCLUDED_RELATIVE_PATHS.has(normalized) ||
+    (mode === "init" &&
+      (INIT_EXCLUDED_RELATIVE_PATHS.has(normalized) ||
+        INIT_EXCLUDED_ROOT_FILES.has(normalized)));
 }
 
-function shouldSkipRootEntry(entryName) {
-  return ROOT_EXCLUDED_ENTRIES.has(entryName) || ROOT_EXCLUDED_FILES.has(entryName);
+function shouldSkipRootEntry(entryName, mode = "managed") {
+  return ROOT_EXCLUDED_ENTRIES.has(entryName) ||
+    ROOT_EXCLUDED_FILES.has(entryName) ||
+    (mode === "init" &&
+      (INIT_EXCLUDED_ROOT_ENTRIES.has(entryName) ||
+        INIT_EXCLUDED_ROOT_FILES.has(entryName)));
 }
 
 function parseRepositoryIdentity(content) {
@@ -438,12 +455,18 @@ function renderTemplateFile(relativePath, content, variables) {
   return content;
 }
 
-function buildCopyPlan(sourceDir, targetDir, variables, relativeDir = "") {
+function buildCopyPlan(
+  sourceDir,
+  targetDir,
+  variables,
+  relativeDir = "",
+  mode = "managed",
+) {
   const operations = [];
   const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
 
   for (const entry of entries) {
-    if (!relativeDir && shouldSkipRootEntry(entry.name)) {
+    if (!relativeDir && shouldSkipRootEntry(entry.name, mode)) {
       continue;
     }
 
@@ -452,7 +475,7 @@ function buildCopyPlan(sourceDir, targetDir, variables, relativeDir = "") {
       : entry.name;
     const relativePath = logicalTemplatePath(bundledRelativePath);
 
-    if (shouldExcludeRelativePath(relativePath)) {
+    if (shouldExcludeRelativePath(relativePath, mode)) {
       continue;
     }
 
@@ -466,7 +489,13 @@ function buildCopyPlan(sourceDir, targetDir, variables, relativeDir = "") {
     if (entry.isDirectory()) {
       operations.push({ type: "mkdir", relativePath, targetPath: targetPathValue });
       operations.push(
-        ...buildCopyPlan(sourcePath, targetDir, variables, bundledRelativePath),
+        ...buildCopyPlan(
+          sourcePath,
+          targetDir,
+          variables,
+          bundledRelativePath,
+          mode,
+        ),
       );
       continue;
     }
@@ -567,14 +596,14 @@ function buildSyncVariables(metadata) {
   };
 }
 
-function buildDesiredManagedOperations(targetDir, variables) {
-  return buildCopyPlan(BUNDLED_TEMPLATE_ROOT, targetDir, variables)
+function buildDesiredManagedOperations(targetDir, variables, mode = "managed") {
+  return buildCopyPlan(BUNDLED_TEMPLATE_ROOT, targetDir, variables, "", mode)
     .filter((operation) => operation.type === "copy" || operation.type === "render")
     .map((operation) => buildDesiredManagedFile(operation, { variables }));
 }
 
 function buildSyncDesiredOperations(targetDir, variables, identity) {
-  return buildDesiredManagedOperations(targetDir, variables).map((operation) => {
+  return buildDesiredManagedOperations(targetDir, variables, "init").map((operation) => {
     if (
       operation.relativePath !== "yss-project.yaml" ||
       identity.state !== "valid" ||
@@ -1096,7 +1125,12 @@ function runTemplateVerification(targetDir, scriptPath) {
   }
 }
 
-function verifyGeneratedTemplate(targetDir) {
+function verifyGeneratedTemplate(targetDir, mode = "managed") {
+  if (mode === "init") {
+    verifyGeneratedInstance(targetDir);
+    return;
+  }
+
   for (const scriptPath of [
     "scripts/sync-skills",
     "scripts/update-skill-lock",
@@ -1106,6 +1140,33 @@ function verifyGeneratedTemplate(targetDir) {
   }
 }
 
+function verifyGeneratedInstance(targetDir) {
+  const forbiddenPaths = [
+    ...[...INIT_EXCLUDED_ROOT_ENTRIES],
+    ...[...INIT_EXCLUDED_ROOT_FILES],
+    ...[...INIT_EXCLUDED_RELATIVE_PATHS],
+  ];
+  for (const relativePath of forbiddenPaths) {
+    if (pathKind(targetPath(targetDir, relativePath)) !== "missing") {
+      throw new Error(`初始化结果包含禁止分发的模板源资产：${relativePath}`);
+    }
+  }
+
+  const identity = readTargetIdentity(targetDir);
+  if (
+    identity.state !== "valid" ||
+    identity.fields.repository_mode !== "project-instance"
+  ) {
+    throw new Error("初始化结果的 yss-project.yaml 必须是 project-instance");
+  }
+
+  const agentsContent = fs.readFileSync(targetPath(targetDir, "AGENTS.md"), "utf8");
+  const readmeContent = fs.readFileSync(targetPath(targetDir, "README.md"), "utf8");
+  if (agentsContent.includes("[填写]") || readmeContent.includes("[填写]")) {
+    throw new Error("初始化结果仍包含模板占位信息");
+  }
+}
+
 function loadTemplateMetadata(targetDir) {
   const metadataPath = targetPath(targetDir, TEMPLATE_METADATA_FILENAME);
   const metadataKind = pathKind(metadataPath);
@@ -1483,7 +1544,13 @@ function runInit(argv = []) {
     readTemplateSnapshot();
     const targetDir = normalizeTargetDir(promptedOptions.targetDir);
     const targetState = inspectTargetDir(targetDir, promptedOptions.force);
-    const operations = buildCopyPlan(BUNDLED_TEMPLATE_ROOT, targetDir, promptedOptions);
+    const operations = buildCopyPlan(
+      BUNDLED_TEMPLATE_ROOT,
+      targetDir,
+      promptedOptions,
+      "",
+      "init",
+    );
 
     if (promptedOptions.dryRun) {
       console.log("dry-run 预览");
@@ -1496,7 +1563,7 @@ function runInit(argv = []) {
 
     prepareTargetDir(targetDir, targetState);
     executePlan(operations, promptedOptions);
-    verifyGeneratedTemplate(targetDir);
+    verifyGeneratedTemplate(targetDir, "init");
     writeTemplateMetadata(
       targetDir,
       buildMetadata(promptedOptions, operations.filter((operation) => operation.type !== "mkdir"), targetDir),
@@ -1671,7 +1738,7 @@ function runSync(argv = []) {
       applyManagedOperation(operation, transaction);
     }
     applyMigrationPlan(migrationPlan, transaction);
-    verifyGeneratedTemplate(targetDir);
+    verifyGeneratedTemplate(targetDir, "init");
     writeTemplateMetadata(
       targetDir,
       buildNextSyncMetadata(metadata, syncPlan, targetDir),

package/template/.agents/skills/ask-matt/SKILL.md

@@ -80,7 +80,6 @@ Off the main flow entirely.
 - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
 - **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
 - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
-- **`/wizard`** — for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
 - **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
 - **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.

package/template/.agents/skills/code-review/SKILL.md

@@ -10,7 +10,7 @@ Two-axis review of a pinned candidate against a fixed point:
 
 Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
 
-The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## Process
 

package/template/.agents/skills/diagnosing-bugs/SKILL.md

@@ -127,7 +127,7 @@ If a correct seam exists:
 4. Watch it pass.
 5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
 
-## Phase 6 — Cleanup + post-mortem
+## Phase 6 — Cleanup
 
 Required before declaring done:
 
@@ -135,6 +135,4 @@ Required before declaring done:
 - [ ] Regression test passes (or absence of seam is documented)
 - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
 - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns

package/template/.agents/skills/domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-modeling
-description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
 ---
 
 # Domain Modeling

package/template/.agents/skills/grill-me/SKILL.md

@@ -4,4 +4,4 @@ description: A relentless interview to sharpen a plan or design.
 disable-model-invocation: true
 ---
 
-Run a `/grilling` session.
+Call the Skill tool with `grilling`.

package/template/.agents/skills/grill-with-docs/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: grill-with-docs
 description: Use when the user explicitly requests a relentless design interview that must preserve resolved glossary terms, ADR-worthy decisions, and factual research evidence.
+disable-model-invocation: true
 ---
 
-Run a `grilling` session with `domain-modeling` active.
+Call the Skill tool with `grilling`, then call it separately with `domain-modeling`.
 
 ## Output Contract
 

package/template/.agents/skills/grilling/SKILL.md

@@ -7,11 +7,17 @@ Interview the user relentlessly until you reach a shared understanding. Map this
 
 Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
 
-Each question should be formatted like so:
+Format a round like so:
 
 ```
 ❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
 
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
 ➡️ <your recommended answer>
 ```
 

package/template/.agents/skills/maintaining-skills/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: maintaining-skills
+description: Use when creating, modifying, validating, or retiring reusable Agent skills.
+---
+
+# Maintaining Skills
+
+Create skills that add useful, non-obvious guidance without constraining unrelated work.
+
+## Working Contract
+
+1. Inspect the skill's callers, ownership, projections, and validation policy before editing. Preserve user intent, authorization boundaries, supported runtimes, and existing metadata unless the requested change requires otherwise.
+2. Assume the Agent already has general reasoning and tool competence. Record only domain knowledge, decision criteria, fragile invariants, or repeatable operations that materially improve outcomes. Do not turn one example or past failure into a universal rule.
+3. Keep discovery precise: use a lowercase hyphenated name and a concise description that states the capability and when it applies. Avoid catchalls that attract unrelated requests.
+4. Keep `SKILL.md` as short as the task permits. Put conditional detail in `references/`, deterministic repeated operations in `scripts/`, and files intended for generated output in `assets/`. Create only resources with a concrete use.
+5. Match specificity and validation to risk. Prefer outcome and decision criteria when several approaches are valid; use fixed steps or absolute rules only for correctness, safety, permissions, or genuinely fragile workflows.
+6. Follow the repository's declared maintenance and review policy. If none exists, run structural validation plus focused checks of the behavior or invariant changed. Use independent forward testing only when complexity or risk makes it meaningful; do not require a failing baseline for every ordinary edit.
+7. After changes, validate frontmatter, naming, references, scripts, projections, locks, and affected callers. Retire obsolete names and resources unless the repository explicitly requires compatibility.
+
+## Boundaries
+
+- Project rules belong in the project's authoritative instructions, not duplicated inside a generic skill.
+- Platform-private skills or absolute local paths are not portable shared dependencies.
+- A validation command proves only what it checks; structural validation alone does not prove good Agent decisions.
+- Do not create README files, changelogs, examples, routers, or placeholder directories without a concrete requirement.

package/template/.agents/skills/product-design-prototype/SKILL.md

@@ -36,7 +36,7 @@ If no Spec baseline exists, route back to `yss-product-lifecycle` / `grill-with-
 
 | Need | Add skill/tool |
 |---|---|
-| Low-fidelity page or flow sketch | `wireframe-prototype` |
+| Low-fidelity page or flow sketch | `product-design:index` |
 | Figma work or existing Figma file | `figma` / `figma-use` |
 | YSS implementation constraints | `yss-router`, then `yss-ui`, `yss-formily`, `yss-page-module-development` as needed |
 

package/template/.agents/skills/to-spec/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## Process
 

package/template/.agents/skills/to-tickets/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## Process
 

package/template/.agents/skills/triage/SKILL.md

@@ -40,7 +40,7 @@ For a PR, the same states read against the attached code: `ready-for-agent` mean
 
 Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
 
-These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+These are canonical role names. The actual label strings used in the issue tracker may differ. The mapping should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
 
 State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
 
@@ -73,7 +73,7 @@ Show counts and a one-line summary per item. Let the maintainer pick.
 
 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
 
-4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling", and grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
 
 5. **Apply the outcome:**
    - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).

package/template/.agents/skills/wait-what/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wait-what
-description: Stop. That last message did not land — re-pitch it.
+description: "Stop. That last message did not land: re-pitch it."
 disable-model-invocation: true
 ---
 
-Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.
+Wait, I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md` (follow `CONTEXT-MAP.md` to the right one if the repo has more than one).

package/template/.agents/skills/wayfinder/SKILL.md

@@ -22,7 +22,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
 
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
 
 ### The map body
 

package/template/.agents/skills/yss-components/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "yss-components"
-description: Use when YSS UI 组件开发规范与最佳实践。涉及页面布局、YTable、YssFormily、YTree、Header 区块、空态与弹窗等页面搭建场景时必须使用。
+description: Use when YSS Vue 页面涉及布局、YTable、YEditTable、YFormily、YTree、ConditionBuilder、空态、弹窗或业务组件选型。
 ---
 
 # YSS 页面组件开发标准
@@ -9,11 +9,32 @@ description: Use when YSS UI 组件开发规范与最佳实践。涉及页面布
 
 ## 0. 权威资料与边界
 
-- YSS UI 组件文档：`http://192.168.164.27:3200/components`
+- YSS UI 组件文档：`http://192.168.164.27:3200/components`（组件契约以该手册为准；本技能依据 2026-08-18 可见内容整理）
 - 本地引用索引：`references/frontend-docs.md`
 
 本技能只负责页面组件、布局和交互呈现规范。请求、分页参数、接口映射交给 `yss-hook` 或 `api-integration`；完整页面生成流程交给 `yss-page-module-development`；表格/树高度细节交给 `yss-use-table-height` 或 `yss-use-tree-height`。
 
+组件文档与当前项目的已验证用法冲突时，先检查当前项目代码和依赖版本，再决定是否迁移；不得把上游 Ant Design Vue、vxe-table、Univer 或 Monaco 的未验证 API 当作 YSS 顶层契约。
+
+## 0.1 组件选型速查
+
+| 场景 | 首选组件 | 关键边界 |
+| --- | --- | --- |
+| 常规动作、权限控制、操作下拉 | `YButton`、`AuthorityDropdown` | 用 `permissionCode` + `fallback` 控制隐藏/禁用；按需导入下拉必须使用 `AuthorityDropdown`，不使用仅全量注册的 `YDropdown` 别名。 |
+| 信息分组、统计卡片 | `YCard` | 组件不处理卡片布局；使用 CSS Grid/Flex 排版，`padding` 与 `bodyStyle.padding` 同时提供时以后者为准。 |
+| 左树右表、上下内容区 | `YSplitPane` | 轻内容使用默认实时拖拽；树、宽表、编辑器、图表等重内容使用 `resize-mode="deferred"` + `collapse-animation="transform"`。 |
+| 树、目录、资源导航 | `YTree` | 受控选择使用 `v-model:selected-keys`；大量节点必须给 `height`，再按需设置 `virtual`，不能只靠 CSS 高度。 |
+| 查询、编辑、详情表单 | `YFormily` | 新代码使用公开导出 `YFormily`；`YssFormily` 仅为历史兼容名。查询动作、展开状态和跨字段联动都以 schema / `scope` / `x-reactions` 表达。 |
+| 常规展示、选择、分页、筛选、操作列 | `YTable` | 远程分页和远程筛选由 Hook 管理；多选必须声明业务 `row-config.keyField`，不能依赖内部 `_X_ROW_KEY`。 |
+| 行内编辑、单元格校验、拖拽排序 | `YEditTable` | 只在确有编辑闭环时使用；保存前调用 `validate()`，以 `v-model:data` 与公开 `updateRow` 事件接回受控数据。 |
+| 嵌套 AND/OR、字段-操作符-值联动 | `YConditionBuilder` | 保存和请求映射在 Hook；组件只维护 `ConditionGroup`。复杂筛选不是把字段硬编码回普通 `YFormily` 模板。 |
+| 月视图、排班、日程状态 | `YMonthCalendar` | 是单日期选择与展示月份的独立状态，不是日期范围输入器；范围查询继续在 `YFormily` 的日期字段完成。 |
+| SQL / JSON / 配置编辑、日志阅读 | `YMonaco` / `YMonacoDiff` | 容器变更后必要时调用 `layout()`；日志追加使用 `appendContent()`，不反复 `setValue()`。 |
+| Cron 配置 | `YCron` | 输出为七段 `秒 分 时 天 月 周 年`；只使用其 `v-model`、`disabled`、`show-second`、`show-year` 公开契约。 |
+| 类 Excel 协作编辑 | `YSheet` | 必须给明确高度；只通过 Facade API 更新工作簿，卸载后释放实例；评估 Univer/React/RxJS 的包体影响。 |
+| 两步文件导入与失败结果下载 | `YFileImport` | 默认阻止 Upload 自动上传；在 `nextStep` / `finalImport` 事件中由业务实现校验、上传和结果回显。 |
+| 图表 | `YssEcharts` | 先阅读当前版本组件页面与项目现有图表实践，再确定 option、数据更新和容器尺寸方案。 |
+
 ## 1. 触发场景
 
 当需求涉及以下任一内容时，优先按本技能执行：
@@ -21,7 +42,7 @@ description: Use when YSS UI 组件开发规范与最佳实践。涉及页面布
 - 新建页面或重构页面结构
 - 左树右表、左右分栏、主从布局
 - YTable 列渲染、分页、空态
-- YssFormily 查询区与 schema 配置
+- YFormily（或历史代码中的 YssFormily）查询区与 schema 配置
 - 页面级弹窗、详情抽屉、Header 信息区
 
 ## 2. 页面目录规范
@@ -49,9 +70,9 @@ views/PageName/
 - `index.vue` 仅编排页面，不承载复杂数据转换
 - `components/` 放展示型或区块型组件
 - `hooks/` 放页面业务逻辑 Hook
-- `schemas/` 放 YssFormily 元数据定义
+- `schemas/` 放 YFormily 元数据定义
 
-## 3. 页面骨架规范
+## 3. 页面骨架规范（YSplitPane + YTree）
 
 页面容器使用 `YSplitPane`，并提供宽度边界与 `storage-key`。
 
@@ -81,13 +102,17 @@ views/PageName/
 - 左侧区域承载目录、筛选树、统计导航
 - 右侧区域按顺序组织 Header、查询区、数据区
 - 右侧无选中对象时必须提供明确空态
+- 尺寸需要受控时使用 `v-model:left-width`（纵向使用 `v-model:top-height`）；`storage-key` 仅保存用户尺寸，不替代页面状态。
+- 左树使用业务主键配置 `field-names`，选中状态使用 `v-model:selected-keys`。树数据量大时传入明确 `height`，必要时启用虚拟滚动；搜索区通过 `#search`、`#header-left`、`#header-right` 扩展，不复制内置搜索逻辑。
+- 节点“更多”操作使用 `get-node-actions` 和 `@action`；默认点击更多会选中该节点，若不应改变主内容选择，显式设置 `:select-on-action-click="false"`。
+- 折叠树时默认保留内容状态（`destroy-on-collapse=false`）。只有确需释放重 DOM、且允许丢失树展开/勾选/滚动状态时才设为 `true`。
 
-## 4. 查询区规范（YssFormily）
+## 4. 查询区规范（YFormily）
 
 查询表单必须采用 schema 驱动，页面中只负责绑定 `schema`、`scope`、初始值与插槽。
 
 ```vue
-<YssFormily
+<YFormily
   ref="formRef"
   :schema="searchSchema"
   :model-value="initialValues"
@@ -99,7 +124,7 @@ views/PageName/
       <a-input v-model:value="searchVal" />
     </a-input-group>
   </template>
-</YssFormily>
+</YFormily>
 ```
 
 schema 约束：
@@ -107,6 +132,10 @@ schema 约束：
 - 使用 `FormLayout + FormGrid + FormItem` 组织字段
 - 按钮区使用 `AutoButtonGroup + Submit`
 - 行为通过 `onSubmit: '{{ handleQuery }}'` 等 scope 方法绑定
+- 新页面统一使用 `YFormily`；`YssFormily` 不作为新代码的组件名或类型来源。
+- 查询表单需要折叠时启用 `collapsible`，并用 `v-model:expanded` 管理外部状态。使用 `#actions` 自定义操作区后，组件会把折叠入口置于其左侧；不要再手写第二套展开逻辑。
+- 字段显隐、禁用、数据源联动使用 `x-reactions`；单字段输入优先监听底层组件的 `onUpdate:value`，选择/失焦事件以 Ant Design Vue 对应事件为准。复杂异步、副作用和跨页面可复用逻辑下沉到 Hook。
+- 详情页使用 `mode="2"`，字段插槽固定为 `#detail-<path>`（路径中的 `.` 替换为 `-`）；不要为只读页另建一套模板。
 
 ## 5. 数据区规范（YTable）
 
@@ -133,6 +162,22 @@ schema 约束：
 - 先固定序号列，再拼接动态列
 - 列字段名与接口字段保持一致
 - 长文本列优先 `showOverflow` 或省略显示
+- 按业务主键设置 `:row-config="{ keyField: 'id', useKey: true }"`；涉及刷新、树表、勾选或批量操作时这是必需项。
+- 分页数据来自服务端时在 `pagination` 中明确 `remote: true`，由 Hook 响应 `page-change` / `size-change` 后刷新数据和 `total`；不得让组件在远程数据上再次切片。
+- 远程列筛选监听 `filter-change`，列上提供稳定的 `filters`，并设置 `filterMethod: () => true` 禁用 vxe-table 本地过滤；本地筛选才编写真实 `filterMethod`。
+- 多选首列为 `type: 'checkbox'`，用 `v-model:selected-row-keys` 或 `v-model:selected-rows` 受控。批量动作放在 `#toolbar-right`，成功后重置选中键或调用 `clearSelection()`。
+- 插槽统一使用 kebab-case：`#<field>-header`、`#<field>-filter`、`#expand-row`、`#group-header`、`#toolbar-left`、`#toolbar-right`。不要把 camelCase 旧兼容写法用于新模板。
+- 最后一列宽度必须精确控制时设置 `:auto-flex-column="false"`；默认自动填满余宽。数据量达到组件阈值时让默认 `virtualXConfig` / `virtualYConfig` 生效，避免手动拼接分页假象。
+
+### 5.1 可编辑表格的升级条件
+
+只有同时满足“用户需要在行内编辑”和“编辑前校验、保存或取消回退”时，从 `YTable` 升级到 `YEditTable`：
+
+- 列通过 `component`（可为纯函数）声明编辑器；按行差异由 `cellProps(ctx)` 决定，函数不得有副作用。
+- 必填和自定义校验通过 `editRules` / `customRule` 声明，提交前调用 `tableRef.value.validate()`；校验失败不得发起保存请求。
+- 以 `v-model:data` 接收完整数据，或在 Vue 模板监听公开 `updateRow` 事件的 kebab-case 写法 `@update-row` 接收单元格变更；保存失败由业务层回退受控数据或保持编辑态，不能假定组件自动持久化。
+- 行级候选项优先级为“行对象 `rowOptionsFieldName`（默认 `options`）→ 列 `options` → `optionsMap[field]`”。字段联动、异步候选和清空关联值必须落在 Hook 的单一数据流中。
+- 编辑表的表头筛选仍是 `filterable + filters + filterMethod`；编辑态 `filterOptions` 只过滤该行下拉候选，二者不可混用。
 
 ## 6. 交互状态规范
 
@@ -143,6 +188,36 @@ schema 约束：
 - `selected`：依赖选中节点时，未选中显示引导空态
 - `error`：请求失败提示 `message.error`
 
+### 6.1 复杂条件、日历和导入的状态契约
+
+#### `YConditionBuilder`
+
+- 用于可嵌套的 AND/OR 条件树，根值必须是 `ConditionGroup`：`{ id, type: 'GROUP', logicalOp: 'AND' | 'OR', children }`；叶子是 `{ id, type: 'LEAF', field, operator, value, betweenValue1?, betweenValue2? }`。
+- 静态操作符使用 `operator-options`；字段切换需改变操作符或值候选时使用 `get-operators(field)` 与 `load-values({ q, field, operator })`。远程字段搜索使用 `load-fields(q)`。
+- 默认严格校验；提交前调用 `ref.validate()`。只有明确允许未完成草稿时才能关闭 `strict-mode`。
+- 嵌套深度由 `max-depth` 限制（默认 3）。条件树到接口筛选 DSL 的序列化、恢复与错误兜底必须放在 `hooks/useXxx.ts`，保留组件内的标准模型。
+- `readonly` 已废弃且不生效；展示态统一传 `disabled`。
+
+#### `YMonthCalendar`
+
+- `v-model` 管理一个选中 `Dayjs`，`v-model:month` 管理展示月份；两者不要混为一个日期范围字段。
+- `valid-range` 限制可选范围，`disabled-date` 处理业务禁用日期。`validRange` 起止传反时组件会自动交换，但业务仍应在 Hook 中规范化输入。
+- 需要连续假期/日程视觉时使用 `cell-layout="grid"` 和 `#date-cell` / `#date-cell-extra`；自定义单元格必须根据 `isToday`、`isSelected`、`isDisabled` 等上下文自行保留状态语义。
+- 父容器高度确定且需要填满时才使用 `fill-height`；它要求父容器有明确高度。键盘、右键或双击动作接入 `select`、`cell-contextmenu`、`cell-dblclick`，不覆盖组件默认焦点行为。
+
+#### `YFileImport`
+
+- 以 `v-model` 管理弹窗显示；选择文件、`nextStep` 校验/预检、结果回显、`finalImport` 确认构成两步流程。事件会提供 `fileList`、`loadingName` 和 `close`。
+- 默认 `beforeUpload` 始终返回 `false`，因此不能期待 `action` 自动上传。需要直传时只在 `upload-props.customRequest` 实现，文件类型规则由 `accept` 或 `file-type-list` 统一配置。
+- `importResult` 用于展示成功、失败和总数；失败文件下载用 `exportErrorData` 事件。遮罩、居中等弹窗配置只放 `modal-props`，上传器配置只放 `upload-props`。
+
+### 6.2 编辑器、Cron、Sheet 与图表
+
+- `YMonaco` 默认 `auto-layout`；在分栏折叠、抽屉打开等容器尺寸变化后确认编辑器已布局。只读日志使用 `language="log"` 或 `"yss-log"`，并用 `appendContent()` 追加；超大内容避免频繁重设完整字符串。
+- `YCron` 的业务值就是七段表达式。页面仅负责双向绑定和禁用态；Cron 到后端调度模型的转换、时区和生效校验属于接口/Hook 层。
+- `YSheet` 的 `modelValue` 是工作簿数据；初始化后经 `getUniverAPI()` / `getWorkbook()` 的 Facade 修改并用 `save()` 取值，禁止直接改 `IWorkbookData`。必须设置容器高度；使用前确认 optionalDependencies 已被私服安装成功。
+- `YssEcharts` 的 option、数据更新策略和容器尺寸以当前版本手册与项目既有实践为准；不得把原生 ECharts 初始化、实例销毁和 ResizeObserver 再复制进页面层。
+
 ## 7. 组件编码规范
 
 - 使用 `<script setup lang="ts">`
@@ -220,7 +295,7 @@ schema 约束：
 满足任一条件即可触发本技能：
 
 - 用户提到“页面搭建、页面重构、页面区块拆分”
-- 用户提到“YTable、YssFormily、YTree、YSplitPane”
+- 用户提到“YTable、YEditTable、YFormily、YTree、YSplitPane、ConditionBuilder”
 - 用户提到“左树右表、查询区、表格区、空态、详情弹窗”
 - 用户要求“参考 QualityReportData 做一个新页面”
 
@@ -234,7 +309,7 @@ schema 约束：
 应触发示例：
 
 - “帮我按 QualityReportData 的结构搭一个新页面，左侧树右侧表格。”
-- “把这个页面查询区改成 YssFormily schema 驱动。”
+- “把这个页面查询区改成 YFormily schema 驱动。”
 - “YTable 需要加分页和空态，顺便补一个详情弹窗。”
 
 不应优先触发示例：

package/template/.agents/skills/yss-design-system/SKILL.md

@@ -80,7 +80,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage` → `product-design:index` |
 | 低保真原型进入高保真前评审 | `prototype-review` |
 | 低保真评审通过后的高保真 HTML 原型 | `yss-prototype-stage`；`high-fidelity-html-prototype` 仅兼容入口 |
-| 低保真线框或流程图 | `product-design:index` 或 `wireframe-prototype` 兼容入口 |
+| 低保真线框或流程图 | `product-design:index` |
 | 前端页面实现 | `yss-ui` / `yss-page-module-development` |
 | 表单 schema | `yss-formily` |
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |