yidaconnector 2026.6.11

package/scripts/validate-skills.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+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 MAX_RECOMMENDED_LINES = 500;
+
+const errors = [];
+const warnings = [];
+
+function toRelative(filePath) {
+  return path.relative(ROOT, filePath).split(path.sep).join('/');
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function collectMarkdownFiles(dir, files) {
+  if (!fs.existsSync(dir)) {
+    return;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectMarkdownFiles(fullPath, files);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(fullPath);
+    }
+  }
+}
+
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== '---') {
+    return null;
+  }
+
+  const endIndex = lines.findIndex(function(line, index) {
+    return index > 0 && line === '---';
+  });
+
+  if (endIndex < 0) {
+    return null;
+  }
+
+  return lines.slice(1, endIndex).join('\n');
+}
+
+function frontmatterField(frontmatter, fieldName) {
+  const match = frontmatter.match(new RegExp('^' + fieldName + ':\\s*(.*)$', 'm'));
+  if (!match) {
+    return null;
+  }
+
+  return match[1].trim();
+}
+
+function validateSkillFrontmatter(skillDirName, skillFile) {
+  const content = readText(skillFile);
+  const frontmatter = parseFrontmatter(content);
+
+  if (!frontmatter) {
+    errors.push(toRelative(skillFile) + ': missing YAML frontmatter');
+    return;
+  }
+
+  const name = frontmatterField(frontmatter, 'name');
+  const description = frontmatterField(frontmatter, 'description');
+
+  if (!name) {
+    errors.push(toRelative(skillFile) + ': missing frontmatter field "name"');
+  } else if (name !== skillDirName) {
+    errors.push(toRelative(skillFile) + ': frontmatter name must match directory name "' + skillDirName + '"');
+  }
+
+  if (!description) {
+    errors.push(toRelative(skillFile) + ': missing frontmatter field "description"');
+  }
+
+  const lineCount = content.split(/\r?\n/).length;
+  if (lineCount > MAX_RECOMMENDED_LINES) {
+    warnings.push(
+      toRelative(skillFile) + ': ' + lineCount + ' lines, consider moving rarely used details into references/'
+    );
+  }
+}
+
+function validateRootSkillFrontmatter() {
+  const content = readText(INDEX_FILE);
+  const frontmatter = parseFrontmatter(content);
+
+  if (!frontmatter) {
+    errors.push(toRelative(INDEX_FILE) + ': missing YAML frontmatter');
+    return;
+  }
+
+  const fieldNames = frontmatter.split(/\r?\n/).filter(function(line) {
+    return /^[a-zA-Z0-9_-]+:\s*/.test(line);
+  }).map(function(line) {
+    return line.split(':')[0];
+  });
+
+  const allowedFields = ['name', 'description'];
+  const unexpectedFields = fieldNames.filter(function(fieldName) {
+    return !allowedFields.includes(fieldName);
+  });
+
+  if (unexpectedFields.length > 0) {
+    errors.push(toRelative(INDEX_FILE) + ': Wukong root skill frontmatter must only contain name and description');
+  }
+
+  const name = frontmatterField(frontmatter, 'name');
+  if (name !== 'yidaconnector') {
+    errors.push(toRelative(INDEX_FILE) + ': root skill name must be "yidaconnector"');
+  }
+
+  const description = frontmatterField(frontmatter, 'description');
+  if (!description) {
+    errors.push(toRelative(INDEX_FILE) + ': missing frontmatter field "description"');
+  } else {
+    const normalizedDescription = frontmatter.replace(/^description:\s*>?\s*/m, '').trim();
+    if (!/不要触发|不触发|DO NOT TRIGGER/i.test(normalizedDescription)) {
+      errors.push(toRelative(INDEX_FILE) + ': root description must include a do-not-trigger boundary');
+    }
+  }
+}
+
+function validateIndexEntry(skillDirName, skillFile) {
+  if (!fs.existsSync(INDEX_FILE)) {
+    errors.push(toRelative(INDEX_FILE) + ': missing root skill index');
+    return;
+  }
+
+  const indexText = readText(INDEX_FILE);
+  const expectedPath = 'skills/' + skillDirName + '/SKILL.md';
+  if (!indexText.includes(expectedPath)) {
+    errors.push(toRelative(skillFile) + ': missing from yida-skills/SKILL.md index as ' + expectedPath);
+  }
+}
+
+function isExternalLink(target) {
+  return /^(https?:|mailto:|tel:|app:\/\/|plugin:\/\/|#)/i.test(target);
+}
+
+function normalizeMarkdownTarget(rawTarget) {
+  const trimmed = rawTarget.trim().replace(/^<|>$/g, '');
+  const targetWithoutTitle = trimmed.split(/\s+/)[0];
+  const targetWithoutAnchor = targetWithoutTitle.split('#')[0];
+
+  if (!targetWithoutAnchor) {
+    return null;
+  }
+
+  try {
+    return decodeURIComponent(targetWithoutAnchor);
+  } catch (_error) {
+    return targetWithoutAnchor;
+  }
+}
+
+function validateMarkdownLinks(markdownFile) {
+  const content = readText(markdownFile);
+  const linkPattern = /!?\[[^\]\n]*\]\(([^)\n]+)\)/g;
+  let match = linkPattern.exec(content);
+
+  while (match) {
+    const rawTarget = match[1];
+    const normalizedTarget = normalizeMarkdownTarget(rawTarget);
+
+    if (normalizedTarget && !isExternalLink(normalizedTarget)) {
+      if (/^file:/i.test(normalizedTarget) || path.isAbsolute(normalizedTarget)) {
+        errors.push(
+          toRelative(markdownFile) + ': non-portable markdown link "' + rawTarget + '"'
+        );
+        match = linkPattern.exec(content);
+        continue;
+      }
+
+      const absoluteTarget = path.resolve(path.dirname(markdownFile), normalizedTarget);
+      if (!fs.existsSync(absoluteTarget)) {
+        errors.push(
+          toRelative(markdownFile) + ': broken markdown link "' + rawTarget + '"'
+        );
+      }
+    }
+
+    match = linkPattern.exec(content);
+  }
+}
+
+function run() {
+  if (!fs.existsSync(SKILLS_DIR)) {
+    errors.push(toRelative(SKILLS_DIR) + ': missing skills directory');
+  } else {
+    validateRootSkillFrontmatter();
+
+    const skillDirNames = fs.readdirSync(SKILLS_DIR).filter(function(name) {
+      const fullPath = path.join(SKILLS_DIR, name);
+      return fs.statSync(fullPath).isDirectory();
+    }).sort();
+
+    for (const skillDirName of skillDirNames) {
+      const skillFile = path.join(SKILLS_DIR, skillDirName, 'SKILL.md');
+      if (!fs.existsSync(skillFile)) {
+        errors.push('yida-skills/skills/' + skillDirName + ': missing SKILL.md');
+        continue;
+      }
+
+      validateSkillFrontmatter(skillDirName, skillFile);
+      validateIndexEntry(skillDirName, skillFile);
+    }
+  }
+
+  const markdownFiles = [];
+  collectMarkdownFiles(SKILLS_ROOT, markdownFiles);
+  for (const markdownFile of markdownFiles.sort()) {
+    validateMarkdownLinks(markdownFile);
+  }
+
+  if (warnings.length > 0) {
+    console.warn('Skill validation warnings:');
+    for (const warning of warnings) {
+      console.warn('  warn ' + warning);
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error('Skill validation failed:');
+    for (const error of errors) {
+      console.error('  error ' + error);
+    }
+    process.exit(1);
+  }
+
+  console.log('Skill validation OK: checked ' + markdownFiles.length + ' markdown files');
+}
+
+run();

package/scripts/validate-structure.js

@@ -0,0 +1,66 @@
+const fs = require('fs');
+const path = require('path');
+
+const requiredDirs = ['bin', 'lib', 'project', 'yida-skills', 'scripts'];
+const requiredFiles = [
+  'bin/yida.js',
+  'package.json',
+  'project/config.json',
+  'README.md',
+  'LICENSE',
+  'CONTRIBUTING.md',
+  '.eslintrc.json',
+];
+
+let hasError = false;
+
+for (const dir of requiredDirs) {
+  if (!fs.existsSync(dir)) {
+    console.error('Missing directory: ' + dir);
+    hasError = true;
+  }
+}
+
+for (const file of requiredFiles) {
+  if (!fs.existsSync(file)) {
+    console.error('Missing file: ' + file);
+    hasError = true;
+  }
+}
+
+if (hasError) {
+  process.exit(1);
+}
+
+// Validate package.json engines field
+const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+const nodeEngine = packageJson.engines && packageJson.engines.node;
+if (!nodeEngine) {
+  console.error('package.json missing engines.node field');
+  process.exit(1);
+}
+console.log('engines.node: ' + nodeEngine);
+
+const skillsDir = 'yida-skills/skills';
+if (fs.existsSync(skillsDir)) {
+  const skills = fs.readdirSync(skillsDir).filter(function(name) {
+    return fs.statSync(path.join(skillsDir, name)).isDirectory();
+  });
+  console.log('yida-skills sub-skills: ' + skills.length);
+}
+
+function countJsFiles(dir) {
+  let count = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.isDirectory()) {
+      count += countJsFiles(path.join(dir, entry.name));
+    } else if (entry.name.endsWith('.js')) {
+      count++;
+    }
+  }
+  return count;
+}
+console.log('lib/ modules: ' + countJsFiles('lib'));
+console.log('Project structure OK');

package/yida-skills/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: yidaconnector
+description: >
+  宜搭数据查询与登录态管理技能。通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）查询宜搭表单、流程、任务数据并管理登录态。
+  包含表单/流程/任务/子表单数据查询、登录、登出、环境检测等能力。
+  当用户提到"宜搭"、"yida"、"查询数据"、"表单数据"、"流程数据"、"登录宜搭"等关键词时，使用此技能；以下情况不要触发：只是讨论通用前端/后端代码、非宜搭平台产品、或只需要解释概念而不操作宜搭资源。
+---
+
+# 宜搭数据查询与登录态管理指南
+
+## 概述
+
+本技能通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）查询宜搭低代码平台的表单、流程、任务数据，并管理登录态。
+
+所有操作通过 **`yidaconnector`** 命令行工具统一执行，无需关心脚本路径或运行环境差异。
+
+**登录态说明**：所有命令自动读取 `.cache/cookies.json`，首次运行或 Cookie 失效时自动触发登录流程，也可手动执行登录命令。
+
+---
+
+## 环境依赖
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| Node.js | ≥ 16 | 运行 yidaconnector |
+
+```bash
+# 安装 yidaconnector（首次使用前执行）
+npm install -g yidaconnector
+
+# 更新 yidaconnector 到最新版本
+npm install -g yidaconnector@latest
+```
+
+---
+
+## ⚡ 首要步骤：检测运行环境（必须先执行）
+
+**在执行任何宜搭操作前，必须先运行环境检测命令**，确认当前 AI 工具环境和登录态：
+
+```bash
+yidaconnector env --json
+yidaconnector login --check-only --json
+```
+
+`yidaconnector env --json` 用于确认当前 AI 工具、项目根目录、配置文件和登录态拆解项；`yidaconnector login --check-only --json` 只读取本地登录缓存，不触发登录、不打开浏览器、不创建任何资源。
+
+若用户明确要求登录某个宜搭入口 URL，登录命令必须携带该 URL 或对应环境 flag。例如 `https://yida-group.alibaba-inc.com/` 是阿里内网宜搭，应执行 `yidaconnector login https://yida-group.alibaba-inc.com/` 或 `yidaconnector login --alibaba`，不要退化成裸 `yidaconnector login`，否则会落到默认公有云 `www.aliwork.com`。
+
+**输出解读**：
+
+| 字段 | 说明 |
+|------|------|
+| AI 工具检测 | 显示当前活跃的 AI 工具（悟空/OpenCode/Aone Copilot 等） |
+| 当前生效环境 | 显示项目根目录路径 |
+| 登录态检测 | 显示是否已登录、域名、组织 ID |
+
+> **若显示"未登录"，先执行 `yidaconnector login`。Codex 中默认返回内置浏览器 handoff：用 Browser Use 打开 `login_url`，让钉钉/宜搭页面承接扫码和组织选择。页面登录完成后必须再次执行 `yidaconnector login --check-only --json` 验证缓存写入。**
+
+---
+
+## 何时使用
+
+当用户提出以下需求时，使用本技能：
+- 查询宜搭表单数据、流程实例、任务列表、子表单明细
+- 查看/创建/更新表单或流程数据
+- 执行流程任务（同意/驳回）
+- 管理宜搭登录态（登录/退出/切换组织/切换环境）
+
+---
+
+## 子技能速查
+
+> 每个子技能均有独立的 SKILL.md。执行时先选定一个最匹配的子技能，只读取该子技能文档；references 按文档提示按需读取，避免一次性加载全量文档。
+
+| 技能 | SKILL.md 路径 | 用途 | 典型命令 |
+|------|--------------|------|---------|
+| `yida-data-management` | `skills/yida-data-management/SKILL.md` | 表单/子表/流程/任务数据查询与变更 | `yidaconnector data query form <appType> <formUuid>` |
+| `yida-login` | `skills/yida-login/SKILL.md` | 登录态管理（通常自动触发） | `yidaconnector login` |
+| `yida-logout` | `skills/yida-logout/SKILL.md` | 退出登录 / 切换账号 | `yidaconnector logout` |
+| `large-file-write` | `skills/large-file-write/SKILL.md` | 大文件可靠写入辅助技能 | 详见 SKILL.md |
+
+---
+
+## 关键规则
+
+### 1. 执行子技能前必须读取其 SKILL.md
+
+每个子技能的详细参数、注意事项、示例均在其 SKILL.md 中。**执行任何子技能前，必须先读取对应的 SKILL.md**，不要凭记忆猜测参数格式。
+
+### 2. 性能与正确性规则（必须遵守）
+
+- **只读必要文档**：先根据用户意图选定 1 个主技能；只有该技能明确要求时，才读取对应 `references/` 文档，禁止一次性读取全部技能文档。
+- **优先复用缓存**：已知的 `appType`、`formUuid`、`formInstId`、`fieldId` 优先复用；缺失或不确定时再查询。
+- **避免无效重试**：同一命令失败后，先根据错误信息检查登录态、组织、参数和字段 ID；不要无修改地连续重试超过 1 次。
+- **分页注意**：宜搭 API 单页最大 100 条，`--all` 会自动翻页拉取全量；数据量大时留意 `pagesFetched` 与 `totalCount`。
+
+### 3. corpId 一致性检查（必须遵守）
+
+查询数据前，**必须对比目标应用的 corpId 与 `.cache/cookies.json` 中的 corpId 是否一致**：
+
+- **一致** → 继续执行
+- **不一致** → 询问用户：重新登录到正确组织，还是切换组织？
+
+### 4. 临时文件规范
+
+所有临时文件（cookies、查询结果、字段映射、一次性脚本等）**必须写在项目根目录的 `.cache/` 文件夹中**，不要写到仓库根目录，也不要写在系统其他位置。
+
+推荐路径：
+
+| 工件类型 | 推荐位置 |
+|---------|---------|
+| 查询结果 / 数据导出 | `.cache/yidaconnector/data-export/` |
+| 字段 ID 映射 | `.cache/<项目名>-schema.json` |
+| 一次性 Python / JS 执行脚本 | `.cache/yidaconnector/scripts/` |
+
+> 若只是为了调用 `yidaconnector` 命令临时生成的 `*.json`、`*.js`、`*.py`、`*.csv` 文件，一律放入 `.cache/yidaconnector/` 子目录。
+
+---
+
+## 宜搭应用 URL 规则
+
+| 页面类型 | URL 格式 |
+|---------|---------|
+| 应用首页 | `{base_url}/{appType}/workbench` |
+| 表单提交页 | `{base_url}/{appType}/submission/{formUuid}` |
+| 表单详情页 | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}` |
+| 表单详情页（编辑模式） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&mode=edit` |
+
+> 所有地址拼接 `&corpid={corpId}` 可自动切换到对应组织。
+
+---
+
+## 常见问题
+
+**Q：查询时提示登录失效？**
+
+重新登录后再查询：
+```bash
+yidaconnector login
+yidaconnector data query form <appType> <formUuid>
+```
+
+**Q：如何切换到其他组织？**
+
+```bash
+yidaconnector org list
+yidaconnector org switch --corp-id <corpId>
+```
+
+**Q：如何切换到私有化/国际版环境？**
+
+```bash
+yidaconnector env list
+yidaconnector env switch <name>
+# 或登录时直接指定
+yidaconnector login --intl
+yidaconnector login --alibaba
+```
+
+**Q：完整 API 参考在哪里？**
+
+宜搭 API 完整字段与端点参考见 [references/yida-api.md](references/yida-api.md)。