exflower-license-server 1.0.4 → 1.0.6

package/README.md

@@ -177,11 +177,169 @@ sudo systemctl enable --now exflower-license-server
 
 ## 模板系统
 
-模板用于向客户端分发预设配置：
+模板用于向客户端分发预设配置。管理后台支持创建 `agent`、`crew`、`excard`、`workflow`、`doc` 五种类型的模板。
 
-- **类型**：`agent` / `crew` / `excard` / `workflow`
-- **范围**：`company_id = NULL` 为全局模板（所有公司可见）；指定 `company_id` 则仅该公司可见
-- **内容**：`content_json`（结构化数据）+ `content_md`（Markdown 说明）
+### 通用字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `type` | 是 | 模板类型：`agent` / `crew` / `excard` / `workflow` / `doc` |
+| `name` | 是 | 模板名称 |
+| `description` | 否 | 模板简介（一句话描述） |
+| `content_json` | 是 | 结构化数据（JSON 对象），各类型字段见下方 |
+| `content_md` | 否 | Markdown 格式说明文档，部分类型必须 |
+| `company_id` | 否 | `NULL` = 全局模板（所有公司可见）；指定公司 ID = 仅该公司可见 |
+| `tags` | 否 | 标签数组 JSON，如 `["营销", "运营"]` |
+| `version` | 否 | 版本号，默认 `1.0` |
+
+### 各类型填写要求
+
+#### `agent` — Agent 成员模板
+
+用于创建 CrewAI Agent。
+
+**content_json 字段：**
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `name` | 是 | string | Agent 名称 |
+| `role` | 是 | string | 角色定位 |
+| `goal` | 是 | string | 目标描述 |
+| `backstory` | 否 | string | 背景故事（如 content_md 提供了完整 Backstory 章节，可留空） |
+| `experience` | 否 | string | 经验积累（同上） |
+| `tools` | 否 | string[] | 工具列表，如 `["web_search", "file_read"]` |
+| `department` | 否 | string | 所属部门 |
+| `allowDelegation` | 否 | boolean | 允许委派，默认 `true` |
+| `maxIter` | 否 | number | 最大迭代次数，默认 `25` |
+| `memory` | 否 | boolean | 启用记忆，默认 `true` |
+| `allowScriptExecution` | 否 | string | 脚本执行模式：`disabled` / `allow_all`，默认 `allow_all` |
+
+**content_md 格式（推荐提供）：**
+
+```markdown
+# Backstory
+
+Agent 的完整背景故事，支持 Markdown 格式...
+
+# Experience
+
+- 经验积累条目 1
+- 经验积累条目 2
+```
+
+客户端导入时会优先从 `content_md` 中提取完整的 `Backstory` 和 `Experience` 章节。
+
+---
+
+#### `crew` — 项目组模板
+
+用于创建 Crew（Agent 团队）。
+
+**content_json 字段：**
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `name` | 是 | string | 项目组名称 |
+| `description` | 否 | string | 项目组描述 |
+| `agentIds` | 否 | string[] | 成员 Agent ID 列表 |
+| `tasks` | 否 | object[] | 任务列表，每个任务包含： |
+| `tasks[].id` | 是 | string | 任务 ID |
+| `tasks[].agentId` | 是 | string | 执行任务的 Agent ID |
+| `tasks[].description` | 是 | string | 任务描述 |
+| `tasks[].order` | 否 | number | 执行顺序 |
+| `tasks[].expectedOutput` | 否 | string | 期望输出 |
+| `process` | 否 | string | 执行流程：`sequential`（顺序）/ `hierarchical`（层级），默认 `sequential` |
+| `managerAgentId` | 否 | string | Manager Agent ID（层级流程时必填） |
+
+---
+
+#### `excard` — ExCard 执行模板
+
+用于创建工作流执行的 ExCard 模板。
+
+**content_json 字段：**
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `id` | 否 | string | ExCard ID，为空时客户端自动生成 |
+| `name` | 是 | string | ExCard 名称 |
+| `description` | 否 | string | 描述 |
+| `agent` | 否 | string | 默认执行 Agent 名称（为空时客户端自动选用第一个可用 Agent） |
+| `category` | 否 | string | 分类，默认 `未分类` |
+| `tags` | 否 | string[] | 标签列表 |
+| `workflow` | 否 | object[] | 工作流步骤数组 |
+
+**content_md 格式（必须提供）：**
+
+ExCard 的完整 Markdown 文档，包含执行约定、资源依赖、工作流步骤等。
+
+---
+
+#### `workflow` — 工作流模板
+
+用于创建 Job + 预设步骤的工作流。
+
+**content_json 字段：**
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `title` | 是 | string | Job 标题 |
+| `description` | 否 | string | Job 描述 |
+| `type` | 否 | string | Job 类型：`once`（一次性）/ `recurring`（周期性），默认 `once` |
+| `agent` | 否 | string | 默认 Agent |
+| `steps` | 否 | object[] | 步骤列表，每个步骤包含： |
+| `steps[].stepType` / `type` | 否 | string | 步骤类型：`task` / `review` / `excard` |
+| `steps[].title` | 否 | string | 步骤标题 |
+| `steps[].description` | 否 | string | 步骤描述 |
+| `steps[].agent` | 否 | string | 执行 Agent |
+| `steps[].excardId` / `excard_id` | 否 | string | 关联的 ExCard ID |
+| `steps[].transitionsPass` | 否 | object | 审核通过后的跳转规则 |
+| `steps[].transitionsFail` | 否 | object | 审核驳回后的跳转规则 |
+
+---
+
+#### `doc` — 文档模板
+
+用于分发知识库文档。
+
+**content_json 字段：**
+
+| 字段 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `assets` | 否 | object[] | 附件列表，每个附件包含： |
+| `assets[].filename` | 是 | string | 文件名 |
+| `assets[].mimeType` | 是 | string | MIME 类型，如 `image/png` |
+| `assets[].data` | 是 | string | Base64 编码的文件内容 |
+
+**content_md 格式（必须提供）：**
+
+完整的文档 Markdown 内容。客户端导入时会自动创建知识库文档目录，并将 assets 解压到 `assets/` 子目录。
+
+---
+
+### 模板创建示例（curl）
+
+创建 Agent 模板：
+
+```bash
+curl -X POST http://localhost:4001/api/admin/templates \
+  -H "x-admin-token: exflower-admin-2026" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "agent",
+    "name": "小红书运营专家",
+    "description": "提供专业级小红书运营服务",
+    "content_json": {
+      "name": "小红书运营专家",
+      "role": "小红书内容运营与增长策略师",
+      "goal": "帮助用户制定并执行高效的小红书内容策略",
+      "tools": ["web_search"],
+      "allowScriptExecution": "allow_all"
+    },
+    "content_md": "# Backstory\n\n你是一位资深小红书运营专家...\n\n# Experience\n\n- 曾帮助 50+ 品牌实现小红书粉丝破万...",
+    "tags": ["运营", "社交媒体"]
+  }'
+```
 
 ## 构建 Docker 镜像
 

package/admin/index.html

@@ -322,7 +322,6 @@
         <label>类型</label>
         <select id="tmpl-type">
           <option value="agent">Agent</option>
-          <option value="crew">Crew</option>
           <option value="excard">ExCard</option>
           <option value="workflow">Workflow</option>
         </select>

package/index.js

@@ -38,6 +38,10 @@ app.get('/admin', (req, res) => {
   res.sendFile(path.join(__dirname, 'admin', 'index.html'));
 });
 
+// ── Auto-migrate ExCard conventions on startup ──
+const { autoMigrateExcardConventions } = require('./migrate-excard-conventions');
+autoMigrateExcardConventions();
+
 setupRoutes(app);
 
 app.listen(PORT, () => {

package/migrate-excard-conventions.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * License Server ExCard conventions 迁移脚本
+ * 将旧格式（字符串）的 conventions 转换为新格式（数组）
+ *
+ * 用法：
+ *   cd license-server
+ *   node migrate-excard-conventions.js [--dry-run]
+ *   npm run migrate
+ */
+
+const Database = require('better-sqlite3');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+function getDataDir() {
+  if (process.env.LICENSE_DATA_DIR) return process.env.LICENSE_DATA_DIR;
+  const sysDir = process.platform === 'win32'
+    ? path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'exflower', 'license-server')
+    : '/var/lib/exflower/license-server';
+  try {
+    if (!fs.existsSync(sysDir)) fs.mkdirSync(sysDir, { recursive: true });
+    fs.accessSync(sysDir, fs.constants.W_OK);
+    return sysDir;
+  } catch {
+    return path.join(os.homedir(), '.exflower', 'license-server');
+  }
+}
+
+/**
+ * 解析 conventions 文本块为数组格式
+ */
+function parseConventionsBlock(content) {
+  if (!content) return [];
+  if (typeof content !== 'string') {
+    return Array.isArray(content) ? content : [];
+  }
+  const blocks = content.split(/\n\s*\n/).filter(Boolean);
+  const result = [];
+  for (const block of blocks) {
+    const lines = block.split('\n').filter(l => l.trim());
+    const obj = {};
+    for (const l of lines) {
+      const match1 = l.match(/^-\s+\*\*(.*?)\*\*:\s*(.*)$/);
+      if (match1) {
+        obj[match1[1].trim()] = match1[2].trim();
+        continue;
+      }
+      const match2 = l.match(/^(.+?):\s*(.*)$/);
+      if (match2) {
+        obj[match2[1].trim()] = match2[2].trim();
+      }
+    }
+    if (Object.keys(obj).length > 0) result.push(obj);
+  }
+  return result.length > 0 ? result : [];
+}
+
+function migrateConventions(data) {
+  if (!data || !data.conventions) return data;
+  for (const key of ['input', 'output', 'errorHandling']) {
+    const val = data.conventions[key];
+    if (typeof val === 'string') {
+      data.conventions[key] = parseConventionsBlock(val);
+    } else if (!Array.isArray(val)) {
+      data.conventions[key] = [];
+    }
+  }
+  return data;
+}
+
+function runMigration(options = {}) {
+  const { dryRun = false, silent = false } = options;
+  const dataDir = getDataDir();
+  const dbFile = path.join(dataDir, 'license.db');
+
+  if (!fs.existsSync(dbFile)) {
+    if (!silent) console.error(`License database not found: ${dbFile}`);
+    return { migrated: 0, skipped: 0, failed: 0, error: 'Database not found' };
+  }
+
+  if (!silent) {
+    console.log(`Database: ${dbFile}`);
+    if (dryRun) console.log('[DRY RUN] No changes will be written.\n');
+  }
+
+  const db = new Database(dbFile);
+
+  // Find all excard templates
+  const templates = db.prepare("SELECT id, name, content_json FROM templates WHERE type = 'excard'").all();
+
+  if (!silent) console.log(`Found ${templates.length} ExCard template(s).\n`);
+
+  let migrated = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const t of templates) {
+    let data;
+    try {
+      data = typeof t.content_json === 'string' ? JSON.parse(t.content_json) : t.content_json;
+    } catch (e) {
+      if (!silent) console.log(`  [SKIP] ${t.id} / ${t.name} — invalid JSON: ${e.message}`);
+      failed++;
+      continue;
+    }
+
+    if (!data.conventions) {
+      skipped++;
+      continue;
+    }
+
+    const allArrays = ['input', 'output', 'errorHandling'].every(
+      key => Array.isArray(data.conventions[key])
+    );
+    if (allArrays) {
+      skipped++;
+      continue;
+    }
+
+    migrateConventions(data);
+
+    if (!silent) {
+      console.log(`  [MIGRATE] ${t.id} / ${t.name}`);
+      console.log(`    input:        → array(${data.conventions.input.length})`);
+      console.log(`    output:       → array(${data.conventions.output.length})`);
+      console.log(`    errorHandling: → array(${data.conventions.errorHandling.length})`);
+    }
+
+    if (!dryRun) {
+      db.prepare("UPDATE templates SET content_json = ? WHERE id = ?")
+        .run(JSON.stringify(data), t.id);
+    }
+    migrated++;
+  }
+
+  db.close();
+
+  if (!silent) {
+    console.log(`\nDone.`);
+    console.log(`  Migrated: ${migrated}`);
+    console.log(`  Skipped:  ${skipped}`);
+    console.log(`  Failed:   ${failed}`);
+  }
+
+  return { migrated, skipped, failed };
+}
+
+/**
+ * 自动迁移（启动时调用，静默模式）
+ */
+function autoMigrateExcardConventions() {
+  try {
+    const result = runMigration({ silent: true });
+    if (result.migrated > 0) {
+      console.log(`[AutoMigrate] ExCard conventions: ${result.migrated} migrated, ${result.skipped} skipped, ${result.failed} failed`);
+    }
+  } catch (e) {
+    console.error('[AutoMigrate] Error:', e.message);
+  }
+}
+
+// ── CLI entry ──
+if (require.main === module) {
+  const dryRun = process.argv.includes('--dry-run');
+  runMigration({ dryRun, silent: false });
+}
+
+module.exports = {
+  runMigration,
+  autoMigrateExcardConventions,
+  migrateConventions,
+  parseConventionsBlock
+};

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "exflower-license-server",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "ExFlower License Server - 在线授权验证服务",
   "main": "index.js",
   "bin": {
-    "exflower-license-server": "./index.js"
+    "exflower-license-server": "index.js"
   },
   "files": [
     "index.js",
     "db.js",
     "routes.js",
     "utils.js",
+    "migrate-excard-conventions.js",
     "admin/**/*",
     "Dockerfile",
     "docker-compose.yml",
@@ -18,7 +19,8 @@
   ],
   "scripts": {
     "start": "node index.js",
-    "dev": "node index.js"
+    "dev": "node index.js",
+    "migrate": "node migrate-excard-conventions.js"
   },
   "dependencies": {
     "better-sqlite3": "^11.10.0",

package/routes.js

@@ -109,6 +109,7 @@ function setupRoutes(app) {
         max_agents: company.max_agents,
         max_crews: company.max_crews
       },
+      active_instances: activeInstances,
       expires_at: company.expires_at
     });
   });
@@ -326,14 +327,42 @@ function setupRoutes(app) {
     res.json({ success: true, templates });
   });
 
+  // ── Template Relationship Helpers ──
+  function _extractWorkflowExcardRefs(contentJson) {
+    try {
+      const data = typeof contentJson === 'string' ? JSON.parse(contentJson) : contentJson;
+      const steps = data.steps || [];
+      const refs = new Set();
+      for (const step of steps) {
+        const eid = step.excardId || step.excard_id;
+        if (eid) refs.add(eid);
+      }
+      return Array.from(refs);
+    } catch {
+      return [];
+    }
+  }
+
+  function _findWorkflowRefsToExcard(excardId) {
+    const allWorkflows = queryAll("SELECT id, name, content_json FROM templates WHERE type = 'workflow'");
+    const refs = [];
+    for (const wf of allWorkflows) {
+      const ids = _extractWorkflowExcardRefs(wf.content_json);
+      if (ids.includes(excardId)) {
+        refs.push({ id: wf.id, name: wf.name });
+      }
+    }
+    return refs;
+  }
+
   app.post('/api/admin/templates', requireAdmin, (req, res) => {
     const { company_id, type, name, description, content_json, content_md, tags, version } = req.body;
 
     if (!type || !name || !content_json) {
       return res.status(400).json({ success: false, message: 'type, name, content_json are required' });
     }
-    if (!['agent', 'crew', 'excard', 'workflow', 'doc'].includes(type)) {
-      return res.status(400).json({ success: false, message: 'type must be agent, crew, excard, workflow, or doc' });
+    if (!['agent', 'excard', 'workflow', 'doc'].includes(type)) {
+      return res.status(400).json({ success: false, message: 'type must be agent, excard, workflow, or doc' });
     }
 
     // If company_id is provided, verify it exists
@@ -344,6 +373,20 @@ function setupRoutes(app) {
       }
     }
 
+    // Validate workflow excard references
+    if (type === 'workflow') {
+      const excardRefs = _extractWorkflowExcardRefs(content_json);
+      for (const eid of excardRefs) {
+        const exists = queryGet('SELECT id FROM templates WHERE id = ? AND type = ?', [eid, 'excard']);
+        if (!exists) {
+          return res.status(400).json({
+            success: false,
+            message: `Workflow references excard template '${eid}' which does not exist in the template library`
+          });
+        }
+      }
+    }
+
     const id = generateId();
     queryRun(
       `INSERT INTO templates (id, company_id, type, name, description, content_json, content_md, tags, version, created_at, updated_at)
@@ -369,6 +412,22 @@ function setupRoutes(app) {
     if (!template) return res.status(404).json({ success: false, message: 'Template not found' });
 
     const { company_id, type, name, description, content_json, content_md, tags, version, is_public } = req.body;
+
+    // Validate workflow excard references when content_json is updated
+    const isWorkflow = (type !== undefined ? type : template.type) === 'workflow';
+    if (isWorkflow && content_json !== undefined) {
+      const excardRefs = _extractWorkflowExcardRefs(content_json);
+      for (const eid of excardRefs) {
+        const exists = queryGet('SELECT id FROM templates WHERE id = ? AND type = ?', [eid, 'excard']);
+        if (!exists) {
+          return res.status(400).json({
+            success: false,
+            message: `Workflow references excard template '${eid}' which does not exist in the template library`
+          });
+        }
+      }
+    }
+
     const updates = [];
     const params = [];
 
@@ -393,6 +452,20 @@ function setupRoutes(app) {
   });
 
   app.delete('/api/admin/templates/:id', requireAdmin, (req, res) => {
+    const template = queryGet('SELECT * FROM templates WHERE id = ?', [req.params.id]);
+    if (!template) return res.status(404).json({ success: false, message: 'Template not found' });
+
+    // Prevent deleting excard templates referenced by workflow templates
+    if (template.type === 'excard') {
+      const refs = _findWorkflowRefsToExcard(template.id);
+      if (refs.length > 0) {
+        return res.status(400).json({
+          success: false,
+          message: `Cannot delete: this ExCard template is referenced by ${refs.length} workflow template(s): ${refs.map(r => `'${r.name}'`).join(', ')}`
+        });
+      }
+    }
+
     queryRun('DELETE FROM templates WHERE id = ?', [req.params.id]);
     res.json({ success: true });
   });