openyida 2026.7.8 → 2026.7.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.7.8",
+  "version": "2026.7.10",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",

package/scripts/postinstall.js

@@ -251,32 +251,32 @@ openyida copy
 
 ## 子技能索引
 
-根据用户意图选择最匹配的子技能，并在执行前读取对应 \`SKILL.md\`：
+根据用户意图选择最匹配的子技能。支持 \`use_skill\` / \`search_skills\` 的宿主中，必须调用 \`use_skill("<技能名>", "<本次目的>")\` 加载子技能；不要用 Read / read_file / cat 读取 SKILL.md 路径。\`skills-index.json\` 仅供 yida-agent 或同构宿主机器发现，不支持该索引的宿主忽略它。完全没有 \`use_skill\` 的本地工具，才允许按根技能路由表和技能包相对路径逐个读取当前阶段唯一必要的 SKILL.md，禁止并发批量读取多个 SKILL.md。
 
 | 意图 | 子技能 |
 | --- | --- |
-| 完整应用开发编排 | \`../yida-app/SKILL.md\` |
-| 登录态管理 | \`../yida-login/SKILL.md\` |
-| 退出登录 / 切换账号 | \`../yida-logout/SKILL.md\` |
-| 创建应用 | \`../yida-create-app/SKILL.md\` |
-| 创建自定义页面 | \`../yida-create-page/SKILL.md\` |
-| 创建 / 更新表单页面 | \`../yida-create-form-page/SKILL.md\` |
-| 创建流程表单 | \`../yida-create-process/SKILL.md\` |
-| 获取单个 / 全部表单 Schema | \`../yida-get-schema/SKILL.md\` |
-| 自定义页面 JSX 开发 | \`../yida-custom-page/SKILL.md\` |
-| 发布自定义页面 | \`../yida-publish-page/SKILL.md\` |
-| 页面公开访问 / 分享配置 | \`../yida-page-config/SKILL.md\` |
-| 表单权限 | \`../yida-form-permission/SKILL.md\` |
-| 数据查询与管理 | \`../yida-data-management/SKILL.md\` |
-| 流程规则 | \`../yida-process-rule/SKILL.md\` |
-| 集成自动化 | \`../yida-integration/SKILL.md\` |
-| HTTP 连接器 | \`../yida-connector/SKILL.md\` |
-| 图表页面 | \`../yida-chart/SKILL.md\` |
-| 原生报表 | \`../yida-report/SKILL.md\` |
-| 公式字段 | \`../yida-formula/SKILL.md\` |
-| 公式静态检查 | \`../yida-formula-evaluate/SKILL.md\` |
-| VOC 反馈整理 | \`../yida-voc/SKILL.md\` |
-| 闪记 / 会议纪要转 PRD | \`../yida-flash-note-to-prd/SKILL.md\` |
+| 完整应用开发编排 | \`yida-app\` |
+| 登录态管理 | \`yida-login\` |
+| 退出登录 / 切换账号 | \`yida-logout\` |
+| 创建应用 | \`yida-create-app\` |
+| 创建自定义页面 | \`yida-create-page\` |
+| 创建 / 更新表单页面 | \`yida-create-form-page\` |
+| 创建流程表单 | \`yida-create-process\` |
+| 获取单个 / 全部表单 Schema | \`yida-get-schema\` |
+| 自定义页面 JSX 开发 | \`yida-custom-page\` |
+| 发布自定义页面 | \`yida-publish-page\` |
+| 页面公开访问 / 分享配置 | \`yida-page-config\` |
+| 表单权限 | \`yida-form-permission\` |
+| 数据查询与管理 | \`yida-data-management\` |
+| 流程规则 | \`yida-process-rule\` |
+| 集成自动化 | \`yida-integration\` |
+| HTTP 连接器 | \`yida-connector\` |
+| 图表页面 | \`yida-chart\` |
+| 原生报表 | \`yida-report\` |
+| 公式字段 | \`yida-formula\` |
+| 公式静态检查 | \`yida-formula-evaluate\` |
+| VOC 反馈整理 | \`yida-voc\` |
+| 闪记 / 会议纪要转 PRD | \`yida-flash-note-to-prd\` |
 
 ## 执行规则
 

package/scripts/validate-skills.js

@@ -9,6 +9,7 @@ const ROOT = path.resolve(__dirname, '..');
 const SKILLS_ROOT = path.join(ROOT, 'yida-skills');
 const SKILLS_DIR = path.join(SKILLS_ROOT, 'skills');
 const INDEX_FILE = path.join(SKILLS_ROOT, 'SKILL.md');
+const SKILLS_INDEX_FILE = path.join(SKILLS_ROOT, 'skills-index.json');
 const MAX_RECOMMENDED_LINES = 500;
 
 const errors = [];
@@ -22,6 +23,10 @@ function readText(filePath) {
   return fs.readFileSync(filePath, 'utf8');
 }
 
+function readJson(filePath) {
+  return JSON.parse(readText(filePath));
+}
+
 function collectMarkdownFiles(dir, files) {
   if (!fs.existsSync(dir)) {
     return;
@@ -159,6 +164,158 @@ function validateIndexEntry(skillDirName, skillFile) {
   }
 }
 
+function validateSkillsIndex(skillDirNames) {
+  if (!fs.existsSync(SKILLS_INDEX_FILE)) {
+    errors.push(toRelative(SKILLS_INDEX_FILE) + ': missing machine-readable skills index');
+    return;
+  }
+
+  let index;
+  try {
+    index = readJson(SKILLS_INDEX_FILE);
+  } catch (error) {
+    errors.push(toRelative(SKILLS_INDEX_FILE) + ': invalid JSON: ' + error.message);
+    return;
+  }
+
+  if (index.version !== 1) {
+    errors.push(toRelative(SKILLS_INDEX_FILE) + ': version must be 1');
+  }
+  if (index.source !== 'openyida') {
+    errors.push(toRelative(SKILLS_INDEX_FILE) + ': source must be "openyida"');
+  }
+  if (index.entry !== 'openyida') {
+    errors.push(toRelative(SKILLS_INDEX_FILE) + ': entry must be "openyida"');
+  }
+  if (!Array.isArray(index.skills)) {
+    errors.push(toRelative(SKILLS_INDEX_FILE) + ': skills must be an array');
+    return;
+  }
+
+  const expectedPaths = new Set(skillDirNames.map(function(skillDirName) {
+    return 'skills/' + skillDirName + '/SKILL.md';
+  }));
+  const seenNames = new Set();
+  const seenPaths = new Set();
+
+  for (let i = 0; i < index.skills.length; i++) {
+    const entry = index.skills[i];
+    const entryLabel = toRelative(SKILLS_INDEX_FILE) + ': skills[' + i + ']';
+
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      errors.push(entryLabel + ': entry must be an object');
+      continue;
+    }
+
+    if (!entry.name || typeof entry.name !== 'string') {
+      errors.push(entryLabel + ': missing string field "name"');
+    } else if (seenNames.has(entry.name)) {
+      errors.push(entryLabel + ': duplicate name "' + entry.name + '"');
+    } else {
+      seenNames.add(entry.name);
+    }
+
+    if (!entry.path || typeof entry.path !== 'string') {
+      errors.push(entryLabel + ': missing string field "path"');
+      continue;
+    }
+    if (seenPaths.has(entry.path)) {
+      errors.push(entryLabel + ': duplicate path "' + entry.path + '"');
+    } else {
+      seenPaths.add(entry.path);
+    }
+
+    if (!/^skills\/[a-z0-9-]+\/SKILL\.md$/.test(entry.path)) {
+      errors.push(entryLabel + ': path must look like skills/<skill-name>/SKILL.md');
+      continue;
+    }
+
+    const skillFile = path.join(SKILLS_ROOT, entry.path);
+    if (!fs.existsSync(skillFile)) {
+      errors.push(entryLabel + ': path does not exist: ' + entry.path);
+      continue;
+    }
+
+    const content = readText(skillFile);
+    const frontmatter = parseFrontmatter(content);
+    const frontmatterName = frontmatter ? frontmatterField(frontmatter, 'name') : null;
+    if (frontmatterName && entry.name !== frontmatterName) {
+      errors.push(entryLabel + ': name "' + entry.name + '" does not match frontmatter name "' + frontmatterName + '"');
+    }
+
+    const pathSkillName = entry.path.split('/')[1];
+    if (entry.name && entry.name !== pathSkillName) {
+      errors.push(entryLabel + ': name "' + entry.name + '" does not match path skill name "' + pathSkillName + '"');
+    }
+
+    if (!entry.display_name || typeof entry.display_name !== 'string') {
+      errors.push(entryLabel + ': missing string field "display_name"');
+    }
+    if (!entry.description || typeof entry.description !== 'string') {
+      errors.push(entryLabel + ': missing string field "description"');
+    }
+    if (!entry.category || typeof entry.category !== 'string') {
+      errors.push(entryLabel + ': missing string field "category"');
+    }
+    if (!Array.isArray(entry.tags) || entry.tags.length === 0) {
+      errors.push(entryLabel + ': tags must be a non-empty array');
+    }
+  }
+
+  for (const expectedPath of expectedPaths) {
+    if (!seenPaths.has(expectedPath)) {
+      errors.push(toRelative(SKILLS_INDEX_FILE) + ': missing skill path "' + expectedPath + '"');
+    }
+  }
+}
+
+function validateSkillLoadingInstructions(instructionFiles) {
+  const forbiddenPatterns = [
+    {
+      pattern: /skills\/[a-z0-9-]+\/SKILL\.md/,
+      message: 'must load subskills via use_skill instead of source skill paths',
+    },
+    {
+      pattern: /\.\.\/[a-z0-9-]+\/SKILL\.md/,
+      message: 'must load sibling subskills via use_skill instead of relative SKILL.md paths',
+    },
+    {
+      pattern: /(?:先读|先读取|完整读取|完整学习|读它的|详见|参考|查阅).{0,60}SKILL\.md/,
+      message: 'must not instruct agents to read SKILL.md directly',
+    },
+    {
+      pattern: /未读取.{0,60}SKILL\.md/,
+      message: 'must express prerequisites as loaded skills, not direct SKILL.md reads',
+    },
+    {
+      pattern: /一次性(?:读取|加载).{0,40}(?:全部|多个|全量).{0,20}技能|全部技能文档/,
+      message: 'must not describe bulk loading multiple skills',
+    },
+  ];
+
+  for (const instructionFile of instructionFiles) {
+    const content = readText(instructionFile);
+    const lines = content.split(/\r?\n/);
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
+      const isAllowedFallback = /没有\s*`?use_skill\/search_skills`?|当前阶段唯一必要/.test(line);
+      const isAllowedBan = /禁止.*(?:Read|read_file|cat).*SKILL\.md/.test(line);
+      if (isAllowedFallback || isAllowedBan) {
+        continue;
+      }
+
+      for (const rule of forbiddenPatterns) {
+        if (rule.pattern.test(line)) {
+          errors.push(
+            toRelative(instructionFile) + ':' + (lineIndex + 1) + ': ' + rule.message
+          );
+          break;
+        }
+      }
+    }
+  }
+}
+
 function isExternalLink(target) {
   return /^(https?:|mailto:|tel:|app:\/\/|plugin:\/\/|#)/i.test(target);
 }
@@ -220,6 +377,7 @@ function run() {
       return fs.statSync(fullPath).isDirectory();
     }).sort();
 
+    const skillDirNamesWithSkillFile = [];
     for (const skillDirName of skillDirNames) {
       const skillFile = path.join(SKILLS_DIR, skillDirName, 'SKILL.md');
       if (!fs.existsSync(skillFile)) {
@@ -227,9 +385,12 @@ function run() {
         continue;
       }
 
+      skillDirNamesWithSkillFile.push(skillDirName);
       validateSkillFrontmatter(skillDirName, skillFile);
       validateIndexEntry(skillDirName, skillFile);
     }
+
+    validateSkillsIndex(skillDirNamesWithSkillFile);
   }
 
   const markdownFiles = [];
@@ -238,6 +399,20 @@ function run() {
     validateMarkdownLinks(markdownFile);
   }
 
+  const instructionFiles = [INDEX_FILE];
+  if (fs.existsSync(SKILLS_DIR)) {
+    const skillDirNames = fs.readdirSync(SKILLS_DIR).filter(function(name) {
+      return fs.statSync(path.join(SKILLS_DIR, name)).isDirectory();
+    }).sort();
+    for (const skillDirName of skillDirNames) {
+      const skillFile = path.join(SKILLS_DIR, skillDirName, 'SKILL.md');
+      if (fs.existsSync(skillFile)) {
+        instructionFiles.push(skillFile);
+      }
+    }
+  }
+  validateSkillLoadingInstructions(instructionFiles);
+
   if (warnings.length > 0) {
     console.warn('Skill validation warnings:');
     for (const warning of warnings) {

package/yida-skills/SKILL.md

@@ -12,6 +12,15 @@ description: >
 
 ---
 
+## 宿主能力适配
+
+- 如果当前宿主提供 `use_skill` / `search_skills`：必须通过 `use_skill("<技能名>", "<本阶段目的>")` 加载主技能和子技能，禁止用 `Read` / `read_file` / `cat` 读取 `SKILL.md` 路径；`use_skill` 会稳定返回技能内容和可读取的辅助文件列表。
+- `skills-index.json` 仅供 yida-agent 或同构宿主做机器可读发现；不支持该索引的宿主忽略它，不要把它当作运行前置条件。
+- 如果当前宿主没有 `use_skill` / `search_skills`：按本文的技能路由表选定技能名，再按技能包相对路径逐个读取当前阶段唯一必要的 `SKILL.md`；禁止并发批量读取多个 `SKILL.md`；禁止预读未来阶段技能。
+- `references/`、`scripts/`、`assets/` 等辅助文件只能在已加载对应技能后按需读取。
+
+---
+
 ## 第一步：环境与登录态检测（必做必读，先于一切操作）
 
 > ⚡ **前置门槛**：确认 openyida 已安装、Node/npm 依赖达标、登录态就绪。**未通过只读验证前，禁止创建应用/页面/表单或发布等任何真实资源操作。**
@@ -36,13 +45,14 @@ description: >
 | 用户诉求信号 | 判定 | 走哪条路线 |
 |------------|------|-----------|
 | 创建/搭建/做一个 + 应用/系统/管理系统；或明确表达从零开始 | **全量搭建** | 走 [完整开发流程](#完整开发流程全量搭建)，从 Step 1 顺序执行 |
-| 对已有应用/表单/页面的单点操作（加字段、查改数据、配公式、建报表、改权限、发布、美化…） | **单一 / 增量任务** | 到 [技能路由](#技能路由单一--增量任务) 选定 **1 个**，只读其 SKILL.md 执行，不回退流程 |
+| 对已有应用/表单/页面的单点操作（加字段、查改数据、配公式、建报表、改权限、发布、美化…） | **单一 / 增量任务** | 到 [技能路由](#技能路由单一--增量任务) 选定 **1 个**，加载对应子技能执行，不回退流程 |
 
 ---
 
 ## 完整开发流程（全量搭建）
 
 > 📌 仅当第二步判定为「全量搭建」时进入；单一/增量任务请跳「技能路由」。
+> 在支持 `use_skill` 的宿主中，先加载 `yida-app` 流程编排技能；进入每个阶段前，再加载该阶段唯一需要的子技能，不要预读未来阶段技能。
 
 ```
 [Step 1] 创建应用 → openyida create-app          → 获得 appType
@@ -50,9 +60,9 @@ description: >
 [Step 2] 需求分析 → 写入 prd/<项目名>.md
               ↓      （必须含 MVP 边界、角色权限、核心旅程、状态机、数据约束、验收标准）
               ↓
-[Step 3] 创建自定义页面 → openyida create-page    → 获得 formUuid（看板用 --mode dashboard）
+[Step 3]（按需）创建/更新表单 → openyida create-form → 获得 formUuid + fieldId（表单）
               ↓
-[Step 4]（按需）创建/更新表单 → openyida create-form → 获得 formUuid（表单）
+[Step 4] 创建自定义页面 → openyida create-page    → 获得 formUuid（看板用 --mode dashboard）
               ↓
 [Step 5] 编写自定义页面代码 → 先按「自定义页面选路」定链路（**默认 Code Canvas yida-canvas-custom-page**，含开放 API 读数据页；仅强依赖原生实例数据桥的页回退 native yida-custom-page）
               ↓  （首次生成面向用户的页必做：先用 yida-page-uiux 产出「视觉方向决策块」，避免统一灰白圆角的 AI 味模板脸，再交所选链路落地）
@@ -70,18 +80,18 @@ description: >
 [Step 10] 输出访问链接，用系统浏览器打开
 ```
 
-> **Step 5 先定视觉方向（首次生成面向用户页必做）**：写 JSX 前先用 `yida-page-uiux` 锁定视觉方向（页面类型判定 → 意图解码 → 差异化决策 → 去 AI 味自检），产出「视觉方向决策块」，再交所选链路（默认 `yida-canvas-custom-page`，回退 `yida-custom-page`）按 `design-system.md` token 落地。跳过此步会直接套用统一灰白圆角模板，生成有 AI 味的平庸页面。详见 `skills/yida-page-uiux/SKILL.md`。
+> **Step 5 先定视觉方向（首次生成面向用户页必做）**：写 JSX 前调用 `use_skill("yida-page-uiux", "确定自定义页面视觉方向并产出决策块")` 锁定视觉方向（页面类型判定 → 意图解码 → 差异化决策 → 去 AI 味自检），产出「视觉方向决策块」，再交所选链路（默认 `yida-canvas-custom-page`，回退 `yida-custom-page`）按 `design-system.md` token 落地。跳过此步会直接套用统一灰白圆角模板，生成有 AI 味的平庸页面。
 >
-> **Step 7 导航整理（含看板/多页面时必做）**：首次生成完整应用后，必须基于业务信息架构重排导航，不能保留创建时的默认顺序。默认原则：面向决策者的**总览/驾驶舱看板作为应用门面靠前**，数据录入/明细表单在其后；同级多个专题看板按业务优先级排，不要把所有页面无脑堆最前。详见 `skills/yida-nav-group/SKILL.md`。
+> **Step 7 导航整理（含看板/多页面时必做）**：首次生成完整应用后，必须基于业务信息架构重排导航，不能保留创建时的默认顺序。默认原则：面向决策者的**总览/驾驶舱看板作为应用门面靠前**，数据录入/明细表单在其后；同级多个专题看板按业务优先级排，不要把所有页面无脑堆最前。进入本阶段前调用 `use_skill("yida-nav-group", "整理应用导航顺序")`。
 >
-> **Step 8 灌入示例数据（有表单时默认执行）**：新建应用的表单默认无数据，看板会空。导航整理完成后，默认向核心表单灌入 **2-3 条**覆盖关键维度（如不同活动/渠道/日期）的示例记录，让看板首屏可展示真实聚合效果。`DateField`/`CascadeDateField` 必须用 13 位毫秒时间戳；灌后执行 `openyida data query` 抽查至少 1 条，确认字段值非空。详见 `skills/yida-data-management/SKILL.md`。
+> **Step 8 灌入示例数据（有表单时默认执行）**：新建应用的表单默认无数据，看板会空。导航整理完成后，默认向核心表单灌入 **2-3 条**覆盖关键维度（如不同活动/渠道/日期）的示例记录，让看板首屏可展示真实聚合效果。`DateField`/`CascadeDateField` 必须用 13 位毫秒时间戳；灌后执行 `openyida data query` 抽查至少 1 条，确认字段值非空。进入本阶段前调用 `use_skill("yida-data-management", "写入和抽查示例数据")`。
 
 ---
 
 ## 技能路由（单一 / 增量任务）
 
 > 选定 **1 个**最匹配的项执行。表**按业务域分组**，每组内既可能是 skill 也可能是 CLI：
-> - 行名为 `yida-xxx` / `sls-log-workbench` / `large-file-write` 的是 **skill** → 先读对应子技能文档再执行；
+> - 行名为 `yida-xxx` / `sls-log-workbench` / `large-file-write` 的是 **skill** → 在支持 `use_skill` 的宿主中调用 `use_skill("<技能名>", "<本次目的>")` 加载后执行；
 > - 行名为 `openyida xxx` 并标 **`CLI`** 的**无 SKILL.md** → 识别到诉求直接执行命令、**不要当 skill 去 read**。
 >
 > 按分组 +「何时选择」内联区别对号入座即可。
@@ -95,56 +105,56 @@ description: >
 >
 > 依据（源码核实）：Canvas 代码在宿主页真实 `window` 中 `new Function` 执行，但物料只透传 `code/runtimeCode/importedModules/pageType`，**无 `this` 上下文、无 `dataSourceMap`**，`this.utils.yida.*` 不可用；宿主 window 全局（`__yida_plugin_runtime__` 插件系统、`__VcDeepYidaUtils__`）均非表单数据桥，也无 `window.Deep` 字段组件。Canvas 读宜搭数据 = 在 `YidaComp` 内自写 HTTP 调开放 API。只有需要免费 `this` 实例桥的页才留 native。
 
-| 分组 | 技能 | 何时选择（关键区别已内联） |
+| 分组 | 加载目标 | 何时选择（关键区别已内联） |
 |------|------|--------------------------|
-| **应用与登录** | `yida-app` | 从零搭建整个应用（多步骤全流程编排） |
-| | `yida-create-app` | 只需创建应用、拿 appType |
-| | `yida-login` | 手动触发登录（通常自动触发） |
-| | `yida-logout` | 切换账号或组织 |
-| **页面与表单** | `yida-create-page` | 创建空白自定义页面拿 formUuid，后续写 JSX |
-| | `yida-create-form-page` | 创建/更新表单、增删改**字段结构**（普通表单，无审批） |
-| | `yida-create-process` | 从零建**带审批**流程表单（表单还不存在，一步到位） |
-| | `yida-page-uiux` | 写自定义页面 UI 前先定视觉方向、去 AI 味（工作台/看板/列表/详情/官网落地页；产出决策块，不写代码；canvas / native 两链路通用） |
-| | `yida-canvas-custom-page` | **自定义页面默认链路**：现代 React 交互 / hooks / 可视化 / AI 页，含只需开放 API HTTP 读数据的页（Code Canvas，`runtimeCode` + `importedModules`，真 React18 + 崩溃隔离） |
-| | `yida-custom-page` | 回退项：仅当强依赖原生实例数据桥（`this.$(fieldId)` 双向绑定 / `this.utils.yida.*` / `dataSourceMap` / 提交流程深度耦合）时才用（native `.oyd.jsx` 链路） |
-| | `yida-canvas-upgrade` | 将已有普通 `.oyd.jsx` / `Jsx` 页面升级迁移到 Code Canvas / `YidaCodeCanvas` 链路 |
-| | `yida-nav-shell` | 自定义页**隐藏应用导航**（`isRenderNav=false`，沉浸/门户/大屏/分享）后，页面内用 JSX 自绘侧边/顶部/浮动/标签导航壳；发布后要配置隐藏原导航，跨页导航项要拼完整 URL 并合并 `isRenderNav=false` / `corpid` / 业务参数（**区别** `yida-nav-group` 平台左侧菜单分组：那是真实导航树，本项是页面内自建导航） |
-| | `yida-publish-page` | JSX 写完后编译并发布 |
-| | `yida-openyida-publish-guard` | 发布已有自定义页面前检查线上设计器状态，避免本地旧源码覆盖用户在线改动 |
-| | `yida-table-form` | Excel 式表格批量录入提交 |
-| | `yida-ppt-slider` | 全屏幻灯片页面（分享/路演/培训/演示） |
+| **应用与登录** | 加载子技能 `yida-app` | 从零搭建整个应用（多步骤全流程编排） |
+| | 加载子技能 `yida-create-app` | 只需创建应用、拿 appType |
+| | 加载子技能 `yida-login` | 手动触发登录（通常自动触发） |
+| | 加载子技能 `yida-logout` | 切换账号或组织 |
+| **页面与表单** | 加载子技能 `yida-create-page` | 创建空白自定义页面拿 formUuid，后续写 JSX |
+| | 加载子技能 `yida-create-form-page` | 创建/更新表单、增删改**字段结构**（普通表单，无审批） |
+| | 加载子技能 `yida-create-process` | 从零建**带审批**流程表单（表单还不存在，一步到位） |
+| | 加载子技能 `yida-page-uiux` | 写自定义页面 UI 前先定视觉方向、去 AI 味（工作台/看板/列表/详情/官网落地页；产出决策块，不写代码；canvas / native 两链路通用） |
+| | 加载子技能 `yida-canvas-custom-page` | **自定义页面默认链路**：现代 React 交互 / hooks / 可视化 / AI 页，含只需开放 API HTTP 读数据的页（Code Canvas，`runtimeCode` + `importedModules`，真 React18 + 崩溃隔离） |
+| | 加载子技能 `yida-custom-page` | 回退项：仅当强依赖原生实例数据桥（`this.$(fieldId)` 双向绑定 / `this.utils.yida.*` / `dataSourceMap` / 提交流程深度耦合）时才用（native `.oyd.jsx` 链路） |
+| | 加载子技能 `yida-canvas-upgrade` | 将已有普通 `.oyd.jsx` / `Jsx` 页面升级迁移到 Code Canvas / `YidaCodeCanvas` 链路 |
+| | 加载子技能 `yida-nav-shell` | 自定义页**隐藏应用导航**（`isRenderNav=false`，沉浸/门户/大屏/分享）后，页面内用 JSX 自绘侧边/顶部/浮动/标签导航壳；发布后要配置隐藏原导航，跨页导航项要拼完整 URL 并合并 `isRenderNav=false` / `corpid` / 业务参数（**区别** `yida-nav-group` 平台左侧菜单分组：那是真实导航树，本项是页面内自建导航） |
+| | 加载子技能 `yida-publish-page` | JSX 写完后编译并发布 |
+| | 加载子技能 `yida-openyida-publish-guard` | 发布已有自定义页面前检查线上设计器状态，避免本地旧源码覆盖用户在线改动 |
+| | 加载子技能 `yida-table-form` | Excel 式表格批量录入提交 |
+| | 加载子技能 `yida-ppt-slider` | 全屏幻灯片页面（分享/路演/培训/演示） |
 | | `openyida aggregate-table` `CLI` | 聚合表 / 虚拟视图（virtualView）：`list` 列出 · `create-empty` 建空白（返回设计器 URL）· `preview` 预览不保存 · `publish` 发布配置 |
-| **数据可视化** | `yida-report` | 普通报表/统计，开箱即用（原生 16 组件） |
-| | `yida-chart` | 更美观/定制化/数据大屏（ECharts） |
-| | `yida-dashboard` | 完整看板 / 驾驶舱产品化交付 |
-| **连接器** | `yida-connector` | 创建/管理连接器、配鉴权 |
-| | `yida-connector-safe-actions` | 连接器已有，从 API 代码生成执行动作 |
-| | `yida-data-source-connectors` | 自定义页面中通过数据源调用连接器 |
-| **数据与公式** | `yida-data-management` | 增删改查**数据记录**，不动字段结构 |
-| | `yida-get-schema` | **只读**查 Schema / 字段 ID，不改结构 |
-| | `yida-formula` | 配在**字段属性**上的实时计算/默认值/校验 |
-| | `yida-formula-evaluate` | 公式语法与字段引用静态检查 |
-| | `yida-business-rule` | 提交后**跨表**高级函数 INSERT/UPDATE/DELETE |
-| **流程与自动化** | `yida-process-rule` | **改已有**流程节点/分支/字段权限（表单已存在） |
-| | `yida-integration` | 提交后**逻辑编排**（图形化自动化流，推荐） |
-| | `yida-agent-center` | 流程代理（在职/离职代理人） |
+| **数据可视化** | 加载子技能 `yida-report` | 普通报表/统计，开箱即用（原生 16 组件） |
+| | 加载子技能 `yida-chart` | 更美观/定制化/数据大屏（ECharts） |
+| | 加载子技能 `yida-dashboard` | 完整看板 / 驾驶舱产品化交付 |
+| **连接器** | 加载子技能 `yida-connector` | 创建/管理连接器、配鉴权 |
+| | 加载子技能 `yida-connector-safe-actions` | 连接器已有，从 API 代码生成执行动作 |
+| | 加载子技能 `yida-data-source-connectors` | 自定义页面中通过数据源调用连接器 |
+| **数据与公式** | 加载子技能 `yida-data-management` | 增删改查**数据记录**，不动字段结构 |
+| | 加载子技能 `yida-get-schema` | **只读**查 Schema / 字段 ID，不改结构 |
+| | 加载子技能 `yida-formula` | 配在**字段属性**上的实时计算/默认值/校验 |
+| | 加载子技能 `yida-formula-evaluate` | 公式语法与字段引用静态检查 |
+| | 加载子技能 `yida-business-rule` | 提交后**跨表**高级函数 INSERT/UPDATE/DELETE |
+| **流程与自动化** | 加载子技能 `yida-process-rule` | **改已有**流程节点/分支/字段权限（表单已存在） |
+| | 加载子技能 `yida-integration` | 提交后**逻辑编排**（图形化自动化流，推荐） |
+| | 加载子技能 `yida-agent-center` | 流程代理（在职/离职代理人） |
 | | `openyida ai-form-setting` `CLI` | 流程表单 AI 审批提示：`models` 查模型 · `fields` 查可插入字段（TEXT/IMAGE/ATTACHMENT）· `get` 查配置 |
-| **权限与访问** | `yida-corp-manager` | **组织级**权限（平台/子管理员、通讯录，影响整个组织） |
-| | `yida-app-permission` | **单应用级**权限（应用管理员/开发成员） |
-| | `yida-form-permission` | **单表单级**权限（权限组/数据范围） |
-| | `yida-page-config` | **页面级**：公开访问 / 组织内分享 |
-| **应用配置与平台** | `yida-nav-group` | 应用**左侧菜单**分组/排序（真实导航树；页面内自绘导航壳见 `yida-nav-shell`） |
-| | `yida-form-detail` | 只注 **CSS** 美化详情页，不改字段 |
-| | `yida-density` | 列表/表格信息密度选择 |
-| | `yida-i18n` | 应用多语言 / 国际化 |
-| | `yida-basic-info` | 组织版本/容量/域名/额度查询 |
-| | `yida-corp-efficiency` | 企业效能 / 低代码学习成果 |
-| **辅助工具** | `yida-flash-note-to-prd` | 会议纪要/闪记转 PRD |
-| | `yida-export-conversation` | 导出当前对话为 Markdown |
-| | `yida-voc` | 整理故障/需求反馈材料 |
-| | `sls-log-workbench` | SLS 平台问题日志查询 |
-| | `yida-db-seq-fix` | PostgreSQL 主键冲突 / Sequence 修复 |
-| | `large-file-write` | 可靠写入 100+ 行大文件 |
+| **权限与访问** | 加载子技能 `yida-corp-manager` | **组织级**权限（平台/子管理员、通讯录，影响整个组织） |
+| | 加载子技能 `yida-app-permission` | **单应用级**权限（应用管理员/开发成员） |
+| | 加载子技能 `yida-form-permission` | **单表单级**权限（权限组/数据范围） |
+| | 加载子技能 `yida-page-config` | **页面级**：公开访问 / 组织内分享 |
+| **应用配置与平台** | 加载子技能 `yida-nav-group` | 应用**左侧菜单**分组/排序（真实导航树；页面内自绘导航壳见 `yida-nav-shell`） |
+| | 加载子技能 `yida-form-detail` | 只注 **CSS** 美化详情页，不改字段 |
+| | 加载子技能 `yida-density` | 列表/表格信息密度选择 |
+| | 加载子技能 `yida-i18n` | 应用多语言 / 国际化 |
+| | 加载子技能 `yida-basic-info` | 组织版本/容量/域名/额度查询 |
+| | 加载子技能 `yida-corp-efficiency` | 企业效能 / 低代码学习成果 |
+| **辅助工具** | 加载子技能 `yida-flash-note-to-prd` | 会议纪要/闪记转 PRD |
+| | 加载子技能 `yida-export-conversation` | 导出当前对话为 Markdown |
+| | 加载子技能 `yida-voc` | 整理故障/需求反馈材料 |
+| | 加载子技能 `sls-log-workbench` | SLS 平台问题日志查询 |
+| | 加载子技能 `yida-db-seq-fix` | PostgreSQL 主键冲突 / Sequence 修复 |
+| | 加载子技能 `large-file-write` | 可靠写入 100+ 行大文件 |
 | | `openyida ai` `CLI` | 调用宜搭 AI 通用能力：文生文（文本生成）/ 识图（图片识别） |
 | | `openyida batch` `CLI` | 批量顺序执行多条 OpenYida 命令（读 tasks 文件，支持 `--json --quiet`） |
 
@@ -154,20 +164,21 @@ description: >
 
 ### 致命规则（FATAL，违反即失败/报错）
 
-1. **先读后执行**：执行任何子技能前，必须先读取其 SKILL.md，不凭记忆猜参数格式。
+1. **技能加载唯一入口**：执行任何子技能前，支持 `use_skill` 的宿主必须调用 `use_skill("<技能名>", "<本阶段目的>")` 加载对应技能；不要用 `Read` / `read_file` / `cat` 读取 SKILL.md 路径，不凭记忆猜参数格式。
 2. **corpId 一致性检查**：创建页面前对比 prd 与 `.cache/cookies.json` 的 corpId，不一致必须询问用户（重新登录 or 当前组织新建）。
 3. **发布前本地校验**：自定义页面发布前跑 `openyida check-page` + `openyida compile`；JSON 配置写盘后先解析校验，再调用平台命令。
+4. **命令输入文件禁止 shell 写入**：当 OpenYida 命令需要 JSON/YAML/CSV/config/script 文件参数时，先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）创建文件，再把路径传给命令；禁止用 shell heredoc、`cat`/`echo`/`printf`/`tee` 加输出重定向，或把命令 stdout 重定向成业务文件。
 
 ### 重要规则（IMPORTANT，影响质量/性能/可维护性）
 
-1. **只读必要文档**：按意图选 1 个主技能，禁止一次性读取全部技能文档。
+1. **按阶段加载必要技能**：按意图选 1 个主技能；完整应用按阶段加载当下唯一需要的子技能，禁止并发批量读取多个 `SKILL.md` 或预读未来阶段技能。
 2. **优先复用缓存**：`appType`/`formUuid`/`fieldId` 优先从 `.cache/<项目名>-schema.json` 读，缺失再 `get-schema`。
 3. **模板优先**：复杂产物先用 `openyida sample` 或现有示例生成骨架，再做最小改动。
 4. **配置承载优先于代码**：字段/公式/联动/报表/审批/集成交给对应技能，自定义页面只做展示与胶水。
 5. **数据性能优先**：统计聚合用 `yida-report` 服务端聚合，不在前端拉全量后自行聚合。
 6. **避免无效重试**：失败先查登录态/组织/参数/字段 ID，无修改不连续重试超 1 次。
 7. **配置分两处存**：业务语义 → `prd/<项目名>.md`；Schema ID → `.cache/<项目名>-schema.json`（prd 不记 ID）。
-8. **临时文件入 `.cache/`**：cookies/schema/配置/脚本一律放 `.cache/openyida/`，不写仓库根目录。
+8. **临时文件入 project `.cache/`**：OpenYida 业务中间文件写入 `<projectRoot>/.cache/openyida/<项目名或任务名>/`；Schema ID 映射仍写 `<projectRoot>/.cache/<项目名>-schema.json`。从 workspace 根执行命令时使用 `project/.cache/...`，从 project 工作目录内执行时使用 `.cache/...`；不要写仓库根目录或系统临时目录。
 9. **报表美化先问方案**：用户说"优化/美化报表"时先问选原生报表(`yida-report`)还是 ECharts(`yida-chart`)。
 10. **按 schema 证据选技能**：先看 `formType`、组件树、`dataSource.online`；`receipt/process/report` 分别落到表单/流程/报表技能。
 11. **官方示例范式优先**：蒸馏官方示例时先理解脱敏 schema 承载方式，不凭截图/标题/视觉判断。

package/yida-skills/references/development-rules.md

@@ -1,10 +1,10 @@
 # 核心规则详解
 
-> 逐条展开主 SKILL.md「核心规则」的操作细节，编号与主文件一一对应（FATAL 1–3 / IMPORTANT 1–11）。需要更多篇幅的规则指向文末专节。
+> 逐条展开主 SKILL.md「核心规则」的操作细节，编号与主文件一一对应（FATAL 1–4 / IMPORTANT 1–11）。需要更多篇幅的规则指向文末专节。
 
 ## 致命规则（FATAL）
 
-**F1 先读后执行**：执行任何子技能前，必须先读取对应子技能文档`skills/<技能名>/SKILL.md`，按文档里的参数格式操作，不凭记忆猜。
+**F1 技能加载唯一入口**：执行任何子技能前，支持 `use_skill` 的宿主必须调用 `use_skill("<技能名>", "<本阶段目的>")` 加载对应技能；不要用 `Read` / `read_file` / `cat` 读取 `SKILL.md` 路径。`skills-index.json` 仅供 yida-agent 或同构宿主机器发现，不支持该索引的宿主忽略它。完全没有 `use_skill` / `search_skills` 的本地工具，才允许按根技能路由表和技能包相对路径逐个读取当前阶段唯一必要的技能文档；禁止并发批量读取多个 `SKILL.md`，禁止预读未来阶段技能。
 
 **F2 corpId 一致性检查**：创建页面前对比 prd 文档与 `.cache/cookies.json` 的 corpId——
 - 一致 → 继续；
@@ -15,18 +15,20 @@
 - 发布时留意"同名双副本内容不一致"警告，必要时加 `--health-check` 做首屏 HTTP 健康检查；
 - 任何 JSON 配置写盘后先做 JSON 解析校验，再调用平台命令。
 
+**F4 命令输入文件禁止 shell 写入**：当 OpenYida 命令需要 JSON/YAML/CSV/config/script 文件参数时，必须先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）创建文件，再把文件路径传给命令。禁止用 shell heredoc、`cat`/`echo`/`printf`/`tee` 加输出重定向，或把 `openyida` 命令 stdout 重定向成业务配置、Schema、导入数据或一次性脚本。
+
 ## 重要规则（IMPORTANT）
 
 | # | 规则 | 操作细节 |
 |---|------|---------|
-| 1 | 只读必要文档 | 按意图选定 1 个主技能，仅在该技能明确要求时才读对应 `references/`；禁止一次性读全部技能文档。 |
+| 1 | 按阶段加载必要技能 | 按意图选定 1 个主技能；完整应用按阶段加载当下唯一需要的子技能，仅在已加载技能明确要求时才读对应 `references/`。 |
 | 2 | 优先复用缓存 | `appType`/`formUuid`/`fieldId`/`reportId` 先从 `.cache/<项目名>-schema.json` 读，缺失或不确定再 `openyida get-schema`。 |
 | 3 | 模板优先 | 自定义页面、表单字段、报表配置等复杂产物先用 `openyida sample` 或现有示例生成骨架，再做最小改动。 |
 | 4 | 配置承载优先于代码 | 字段结构/公式/联动/报表聚合/审批/集成/连接器动作交给对应技能承载；自定义页面代码只做展示、事件分发和必要胶水。 |
 | 5 | 数据性能优先 | 统计聚合用 `yida-report` 服务端聚合；不在自定义页面前端分页拉全量后自行聚合。 |
 | 6 | 避免无效重试 | 失败先按错误信息查登录态/组织/参数/字段 ID；无修改不连续重试超 1 次。 |
 | 7 | 配置分两处存 | 详见 [配置信息分两处存储](#配置信息分两处存储) 与 [PRD 质量门槛](#prd-质量门槛)。 |
-| 8 | 临时文件入 `.cache/` | 详见 [临时文件规范](#临时文件规范)。 |
+| 8 | 临时文件入 project `.cache/` | 详见 [临时文件规范](#临时文件规范)。 |
 | 9 | 报表美化先问方案 | 详见 [报表优化 / 美化提示规则](#报表优化--美化提示规则)。 |
 | 10 | 按 schema 证据选技能 | 先看 `formType`、组件树、`dataSource.online`；`receipt/process/report` 分别落到表单/流程/报表技能，只有默认页是自定义展示页、或确需列表/看板/工具页交互时才落到 `yida-custom-page`。 |
 | 11 | 官方示例范式优先 | 蒸馏宜搭示例中心时，先按 [官方示例 Schema 范式](official-example-schema-patterns.md) 理解脱敏 schema 的承载方式，不凭截图/卡片标题/页面视觉判断。 |
@@ -55,14 +57,16 @@
 
 ## 临时文件规范
 
-所有临时文件（cookies、schema 缓存、字段/报表/流程配置、导入数据、一次性脚本等）**必须写在项目根目录的 `.cache/` 下**，不写仓库根目录或系统其他位置。
+所有 OpenYida 业务中间文件（cookies、schema 缓存、字段/报表/流程配置、导入数据、一次性脚本等）**必须写在 OpenYida project 工作目录的 `.cache/` 下**，不写业务仓库根目录、系统 `/tmp` 或其他位置。源码中的 `<projectRoot>` 指 OpenYida project 工作目录；从 workspace 根执行命令时路径通常是 `project/.cache/...`，从 project 工作目录内执行时路径是 `.cache/...`。
+
+文件必须由 agent 的结构化文件写入工具创建，再传给 OpenYida 命令。不要通过 `execute_shell` 加 heredoc、`cat`/`echo`/`printf`/`tee`、管道或重定向来生成 JSON/YAML/CSV/config/script 文件。`/tmp` 只允许用于外部工具强制要求的系统临时路径，OpenYida 业务配置、schema、导入数据和一次性脚本不写 `/tmp`。
 
 | 工件类型 | 推荐位置 |
 |---------|---------|
-| Schema / ID 映射 | `.cache/<项目名>-schema.json` |
-| 字段 / 报表 / 流程配置 | `.cache/openyida/<项目名>/` |
-| 批量导入数据（JSON/JSONL/CSV） | `.cache/openyida/data-import/` |
-| 一次性 Python / JS 脚本 | `.cache/openyida/scripts/` |
+| Schema / ID 映射 | `<projectRoot>/.cache/<项目名>-schema.json` |
+| 字段 / 报表 / 流程 / 连接器配置 | `<projectRoot>/.cache/openyida/<项目名或任务名>/` |
+| 批量导入数据（JSON/JSONL/CSV） | `<projectRoot>/.cache/openyida/<项目名或任务名>/data-import/` |
+| 一次性 Python / JS 脚本 | `<projectRoot>/.cache/openyida/<项目名或任务名>/scripts/` |
 
 > 只有需长期维护的 PRD、页面源码、示例资源才写入 `prd/`、`pages/src/`、`project/` 等正式目录。
 

package/yida-skills/skills/large-file-write/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: large-file-write
-description: 解决 heredoc 或 shell 命令写入大文件内容被截断的问题。通过 Node.js 脚本将内容作为模板字符串写入，绕过 shell 截断限制。适用于需要可靠写入超过 100 行文本文件时。
+description: 解决 heredoc 或 shell 命令写入大文件内容被截断的问题。优先使用 agent 结构化文件写入工具；超大文件可用该工具创建 Node.js payload 后执行。适用于需要可靠写入超过 100 行文本文件时。
 ---
 
 # Large File Write Skill
 
 ## 问题背景
 
-在 AI Agent 模式下，使用 heredoc（`<< 'EOF'`）或 shell 命令向文件写入大块内容时，经常出现：
+在 AI Agent 模式下，使用 shell here-document 或其他 shell 命令向文件写入大块内容时，经常出现：
 - 内容被截断（工具输出超过 token 限制）
 - heredoc 内容未生效（zsh 特殊字符转义问题）
 - 多次追加导致重复内容或语法错误
@@ -15,20 +15,22 @@ description: 解决 heredoc 或 shell 命令写入大文件内容被截断的问
 
 ## 解决方案
 
-使用 Node.js 脚本 `scripts/write.js`，将内容作为 JS 字符串变量传入，绕过 shell 截断限制。
+优先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）直接创建目标文件。内容过大、单次写入可能截断时，再用结构化写入工具创建 Node.js payload 脚本，由 payload 调用 `fs.writeFileSync` 写目标文件。
+
+OpenYida 业务场景下，payload、内容片段和验证脚本必须放在 `<projectRoot>/.cache/openyida/<项目名或任务名>/scripts/`，不要写系统临时目录、仓库根目录或 `.cache/` 顶层。
 
 ## 使用方式
 
 三种写入模式的完整代码示例，详见 [references/write-patterns.md](./references/write-patterns.md)：
 
-- **模式一**：创建内容脚本后执行（推荐）— 用 `create_file` 创建临时 JS 脚本，再 `node` 执行
+- **模式一**：创建内容脚本后执行（推荐）— 用结构化文件写入工具创建临时 JS 脚本，再 `node` 执行
 - **模式二**：追加内容到已有文件 — 用 `fs.appendFileSync` 追加大块内容
-- **模式三**：使用通用写入脚本（stdin 模式）— 通过管道传入内容
+- **模式三**：使用通用写入脚本（content-file 模式）— 内容文件也先由结构化文件写入工具创建
 
 ### 快速示例
 
 ```js
-// /tmp/content-payload.js
+// <projectRoot>/.cache/openyida/<任务名>/scripts/content-payload.js
 const fs = require('fs');
 const content = `// 你的大块内容（支持任意长度）
 export function myFunction() { ... }
@@ -38,17 +40,17 @@ console.log('写入完成，行数：', content.split('\n').length);
 ```
 
 ```bash
-node /tmp/content-payload.js
+node .cache/openyida/<任务名>/scripts/content-payload.js
 wc -l /path/to/target.js   # 验证行数
 ```
 
 ## 核心原则
 
-1. **永远不要用 heredoc 写大文件** — 改用 `create_file` 工具创建临时 JS 脚本
+1. **永远不要用 heredoc 写大文件** — 改用结构化文件写入工具创建临时 JS 脚本
 2. **永远不要用 PowerShell JSON 化大文件** — 禁止 `Get-Content -Raw <file> | ConvertTo-Json`、`ConvertFrom-Json` 处理 `.oyd.jsx/.jsx/.js` 页面源码
 3. **内容放在 JS 模板字符串里** — 支持任意长度，不受 shell 限制
 4. **写完立即验证** — `wc -l` 检查行数，`tail` 检查末尾内容
-5. **分段写入大文件** — 超过 300 行的内容，拆分为多个 `create_file` + `node` 执行
+5. **分段写入大文件** — 超过 300 行的内容，拆分为多个结构化写入 + `node` 执行
 6. **本技能不读写 memory**：文件写入为纯本地操作，不依赖跨会话的 memory 状态
 
 ## 适用场景
@@ -88,4 +90,4 @@ Get-Content -Raw project\pages\src\vendor-section.oyd.jsx | ConvertTo-Json
 | `node: command not found` | Node.js 未安装 | 先安装 Node.js ≥ 16 |
 | 脚本执行后文件为空 | 模板字符串语法错误 | 检查反引号是否闭合，特殊字符是否转义 |
 | 写入不完整 | 内容超过单次 create_file 限制 | 按「分段写入」方式拆分为多个脚本 |
-| 权限拒绝 | 目标路径无写权限 | 检查目录权限，或改用 `/tmp/` 路径 |
+| 权限拒绝 | 目标路径无写权限 | 检查目标目录权限；OpenYida 业务文件仍应留在 project 工作目录内 |