@playcraft/skills 0.0.2

package/skills/word_connect.aigameplay/ref/reducer.template.ts

@@ -0,0 +1,186 @@
+/**
+ * word_connect.aigameplay — reducer 接口模板
+ *
+ * Agent 生成实际 reducer 时，必须导出以下函数。
+ * 此文件是接口约束模板，不是可执行代码。
+ *
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ⚠️ 重要：渲染层（GameScene）不应直接调用 dispatch()
+ *
+ * dispatch() 是一体化接口，内部完成路径验证 + 单词判定后只返回最终状态，
+ * 中间过程（实时路径连线、逐格高亮、有效/无效动画）全部丢失。
+ *
+ * 渲染层需要实时绘制连线、逐格高亮、播放验证动画，
+ * 因此必须使用下方的「分步函数」逐步驱动，每步之间同步渲染状态。
+ *
+ * dispatch() 的用途：无头测试、AI 模拟、跳过动画等场景。
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+
+// ─── 配置类型 ─────────────────────────────────────────────────────────────────
+
+export type WordConnectConfig = {
+  /** 网格行数 */
+  rows: number;
+  /** 网格列数 */
+  cols: number;
+  /** 目标单词列表（全大写） */
+  wordList: string[];
+  /** 初始网格字母（二维数组，行×列） */
+  initialLetters: string[][];
+  /** 是否允许斜方向连线 */
+  allowDiagonal: boolean;
+  /** 单词最小长度 */
+  minWordLength: number;
+  /** 是否启用计时模式 */
+  timedMode: boolean;
+  /** 计时时长（ms，仅 timedMode=true 时有效） */
+  timeLimitMs?: number;
+  /** 找到单词后是否消除格子并补充 */
+  eliminateFoundLetters: boolean;
+};
+
+// ─── 动作类型 ─────────────────────────────────────────────────────────────────
+
+export type WordConnectAction =
+  | { type: 'startTrace'; row: number; col: number }
+  | { type: 'extendTrace'; row: number; col: number }
+  | { type: 'completeTrace' }
+  | { type: 'tick'; deltaMs: number }
+  | { type: 'reset' };
+
+// ─── 状态类型 ─────────────────────────────────────────────────────────────────
+
+export type GridCell = {
+  letter: string;
+  found: boolean;
+  foundWordId: string | null;
+};
+
+export type CellPos = { row: number; col: number };
+
+export type FoundWord = {
+  word: string;
+  path: CellPos[];
+  score: number;
+};
+
+export type WordConnectState = {
+  grid: GridCell[][];
+  wordList: string[];
+  foundWords: FoundWord[];
+  currentPath: {
+    cells: CellPos[];
+    letters: string;
+  };
+  score: number;
+  timer: number;
+  gameOver: boolean;
+  win: boolean;
+  lastCompleteResult: CompleteTraceResult | null;
+};
+
+// ─── 分步操作返回类型 ─────────────────────────────────────────────────────────
+
+export type ExtendTraceResult = {
+  path: CellPos[];
+  letters: string;
+  valid: boolean;
+  reason: 'ok' | 'not_adjacent' | 'already_in_path';
+};
+
+export type CompleteTraceResult = {
+  word: string;
+  isValid: boolean;
+  reason: 'found' | 'too_short' | 'not_in_list' | 'already_found';
+  score: number;
+  path: CellPos[];
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 必须导出的函数
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ─── 初始化 ──────────────────────────────────────────────────────────────────
+
+/**
+ * init：根据配置初始化游戏状态（构建网格、设置词库和计时器）
+ */
+export declare function init(config: WordConnectConfig): WordConnectState;
+
+// ─── 一体化接口（测试/AI 模拟用） ───────────────────────────────────────────
+
+/**
+ * dispatch：接收动作，返回新状态（纯函数，不得修改原 state）
+ *
+ * ⚠️ 仅用于无头测试和 AI 模拟。渲染层请使用下方分步函数。
+ */
+export declare function dispatch(state: WordConnectState, action: WordConnectAction): WordConnectState;
+
+/**
+ * getState：返回当前状态快照
+ */
+export declare function getState(state: WordConnectState): WordConnectState;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 分步函数（渲染层/场景层必须使用这些函数驱动动画）
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * startTrace：玩家按下某格，开始连线路径
+ * 场景层高亮起始格子，开始绘制连线 Graphics
+ */
+export declare function startTrace(
+  state: WordConnectState,
+  row: number,
+  col: number,
+): { path: CellPos[]; letters: string };
+
+/**
+ * extendTrace：玩家滑动到相邻格子，延伸路径
+ * 场景层实时绘制连线到新格子，高亮选中格
+ *
+ * - valid=false 且 reason='not_adjacent'：目标格不相邻，忽略
+ * - valid=false 且 reason='already_in_path'：格子已在路径中，忽略
+ * - valid=true：格子加入路径，更新 letters
+ */
+export declare function extendTrace(
+  state: WordConnectState,
+  row: number,
+  col: number,
+): ExtendTraceResult;
+
+/**
+ * completeTrace：玩家抬起手指，验证并提交当前路径组成的单词
+ * 场景层根据 isValid 播放有效（绿色消失）或无效（红色闪烁清除）动画
+ */
+export declare function completeTrace(
+  state: WordConnectState,
+): CompleteTraceResult;
+
+/**
+ * validateWord：检查字母串是否为有效单词（在词库中 + 未找到过）
+ * 纯逻辑函数，渲染层一般不直接调用（由 completeTrace 内部使用）
+ */
+export declare function validateWord(
+  letters: string,
+  wordList: string[],
+  foundWords: FoundWord[],
+): { valid: boolean; reason: CompleteTraceResult['reason'] };
+
+/**
+ * markWordFound：将有效单词记录到 foundWords，更新 grid 格子的 found 状态
+ * 场景层根据 path 对格子精灵播放标记动画（颜色变化、锁定图标等）
+ */
+export declare function markWordFound(
+  state: WordConnectState,
+  word: string,
+  path: CellPos[],
+): { foundWords: FoundWord[]; score: number };
+
+/**
+ * checkWin：检查是否找到所有目标单词
+ */
+export declare function checkWin(
+  state: WordConnectState,
+): { win: boolean };

package/src/index.ts

@@ -0,0 +1,10 @@
+export type { Skill, LoadSkillsOptions, LoadSkillsResult, SkillDefinition, RoleDefinition } from './skills.types.js';
+export {
+  loadSkills,
+  loadSkillsFromSandbox,
+  loadSkillsFromDir,
+  formatSkillsForPrompt,
+  parseSkillFrontmatter,
+  parseSkillDefinition,
+  parseRoleDefinition,
+} from './skills.loader.js';

package/src/skills.loader.ts

@@ -0,0 +1,225 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Skill, LoadSkillsOptions, LoadSkillsResult, SkillDefinition } from './skills.types.js';
+
+const SKILL_FILENAME = 'SKILL.md';
+const FALLBACK_SKILLS_DIR = '~/.pi/agent/skills';
+
+function expandTilde(p: string): string {
+  if (p.startsWith('~/')) {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, p.slice(2));
+  }
+  if (p === '~') {
+    return process.env.HOME || process.env.USERPROFILE || '';
+  }
+  return p;
+}
+
+/** 从 SKILL.md 内容解析 name、description、triggers（frontmatter）。供 loader 与 ZIP 解析共用。 */
+export function parseSkillFrontmatter(content: string): {
+  name: string;
+  description: string;
+  triggers?: string;
+} {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) {
+    return { name: 'unknown', description: '' };
+  }
+  const block = match[1];
+  const nameMatch = block.match(/name:\s*(.+)/);
+  const descMatch = block.match(/description:\s*(.+)/);
+  const triggersMatch = block.match(/triggers:\s*(.+)/);
+  return {
+    name: nameMatch ? nameMatch[1].trim().replace(/^['"]|['"]$/g, '') : 'unknown',
+    description: descMatch ? descMatch[1].trim().replace(/^['"]|['"]$/g, '').slice(0, 1024) : '',
+    triggers: triggersMatch ? triggersMatch[1].trim().replace(/^['"]|['"]$/g, '').slice(0, 512) : undefined,
+  };
+}
+
+/**
+ * 从 SKILL.md 内容解析能力定义。
+ * 同时支持新格式 `## Skill Definition` 和旧格式 `## Role Definition`（向后兼容）。
+ * 只解析能力字段（tools, prompt_extension），不再解析身份字段。
+ */
+export function parseSkillDefinition(content: string): SkillDefinition | undefined {
+  // Support both new and legacy section headers
+  const sectionMatch = content.match(/## (?:Skill|Role) Definition\s*\n([\s\S]*?)(?=\n##|$)/);
+  if (!sectionMatch) return undefined;
+
+  const block = sectionMatch[1].trim();
+
+  // Must have at least tools or prompt_extension to be a valid skill definition
+  // Parse tools list
+  const toolsMatch = block.match(/tools:\s*\n((?:\s+-\s+.+\n?)*)/);
+  const tools: string[] = [];
+  if (toolsMatch) {
+    const listText = toolsMatch[1];
+    const items = listText.match(/^\s+-\s+(.+)$/gm) ?? [];
+    for (const item of items) {
+      const val = item.replace(/^\s+-\s+/, '').trim().replace(/^['"]|['"]$/g, '');
+      if (val) tools.push(val);
+    }
+  }
+
+  // Parse prompt_extension (block scalar)
+  const promptExtMatch = block.match(/prompt_extension:\s*\|\s*\n([\s\S]*?)(?=\n\S|$)/);
+  const prompt_extension = promptExtMatch
+    ? promptExtMatch[1]
+        .split('\n')
+        .map((line) => line.replace(/^  /, ''))
+        .join('\n')
+        .trimEnd()
+    : '';
+
+  if (tools.length === 0 && !prompt_extension) return undefined;
+
+  return { tools, prompt_extension };
+}
+
+/**
+ * @deprecated 向后兼容别名，请使用 parseSkillDefinition
+ */
+export function parseRoleDefinition(content: string): SkillDefinition | undefined {
+  return parseSkillDefinition(content);
+}
+
+/** 从沙箱加载 skills */
+export async function loadSkillsFromSandbox(opts: LoadSkillsOptions): Promise<Skill[]> {
+  const { sandboxId, skillsPath, sandboxClient } = opts;
+  if (!sandboxId || !skillsPath || !sandboxClient) return [];
+
+  try {
+    const entries = await sandboxClient.listFiles(sandboxId, skillsPath);
+    const skills: Skill[] = [];
+
+    for (const entry of entries) {
+      const isDir = (entry as { type?: string }).type === 'dir' || !entry.path.includes('.');
+      if (!isDir) continue;
+
+      const skillDirPath = `${skillsPath}/${entry.name}`.replace(/\/+/g, '/');
+      const skillFilePath = `${skillDirPath}/${SKILL_FILENAME}`;
+
+      try {
+        const raw = await sandboxClient.readFile(sandboxId, skillFilePath, { format: 'text' });
+        const content = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
+        const { name, description, triggers } = parseSkillFrontmatter(content);
+        const skillDefinition = parseSkillDefinition(content);
+        skills.push({
+          name,
+          description,
+          ...(triggers ? { triggers } : {}),
+          filePath: skillFilePath,
+          ...(skillDefinition ? { skillDefinition, roleDefinition: skillDefinition } : {}),
+        });
+      } catch {
+        // 跳过无法读取的 SKILL.md
+      }
+    }
+
+    return skills;
+  } catch {
+    return [];
+  }
+}
+
+/** 从本地目录加载 skills */
+export function loadSkillsFromDir(dirPath: string): Skill[] {
+  const expanded = expandTilde(dirPath.trim());
+  if (!fs.existsSync(expanded) || !fs.statSync(expanded).isDirectory()) {
+    return [];
+  }
+
+  const skills: Skill[] = [];
+  const entries = fs.readdirSync(expanded, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const skillFilePath = path.join(expanded, entry.name, SKILL_FILENAME);
+    if (!fs.existsSync(skillFilePath)) continue;
+
+    try {
+      const content = fs.readFileSync(skillFilePath, 'utf-8');
+      const { name, description, triggers } = parseSkillFrontmatter(content);
+      const skillDefinition = parseSkillDefinition(content);
+      skills.push({
+        name,
+        description,
+        ...(triggers ? { triggers } : {}),
+        filePath: skillFilePath,
+        ...(skillDefinition ? { skillDefinition, roleDefinition: skillDefinition } : {}),
+      });
+    } catch {
+      // 跳过无法读取的 SKILL.md
+    }
+  }
+
+  return skills;
+}
+
+/** 加载 skills（优先沙箱，fallback 本地）。支持 system + session 两路径合并。 */
+export async function loadSkills(opts: LoadSkillsOptions): Promise<LoadSkillsResult> {
+  const sandboxSkills: Skill[] = [];
+  if (opts.skillsPath && opts.sandboxId && opts.sandboxClient) {
+    const system = await loadSkillsFromSandbox({ ...opts, skillsPath: opts.skillsPath });
+    sandboxSkills.push(...system);
+  }
+  if (opts.sessionSkillsPath && opts.sandboxId && opts.sandboxClient) {
+    const session = await loadSkillsFromSandbox({ ...opts, skillsPath: opts.sessionSkillsPath });
+    const seen = new Set(sandboxSkills.map((s) => s.name));
+    for (const s of session) {
+      if (!seen.has(s.name)) {
+        seen.add(s.name);
+        sandboxSkills.push(s);
+      }
+    }
+  }
+  if (sandboxSkills.length > 0) {
+    return { skills: sandboxSkills, source: 'sandbox' };
+  }
+
+  const localPaths: string[] = opts.skillPaths ?? [];
+  const envPaths = process.env.AGENT_SKILLS_PATHS?.split(',').map((p) => p.trim()).filter(Boolean) ?? [];
+  const allPaths = [...new Set([...localPaths, ...envPaths, expandTilde(FALLBACK_SKILLS_DIR)])];
+
+  const seen = new Set<string>();
+  const skills: Skill[] = [];
+  for (const p of allPaths) {
+    const fromDir = loadSkillsFromDir(p);
+    for (const s of fromDir) {
+      if (!seen.has(s.name)) {
+        seen.add(s.name);
+        skills.push(s);
+      }
+    }
+  }
+
+  return { skills, source: 'local' };
+}
+
+/**
+ * Format skills as system prompt section (Discovery phase: name + description only).
+ *
+ * 默认 `_skillsBasePath` 取自共享区（`/mnt/shared/skills`），与 AgentSandboxService.getSkillsPath()
+ * 对齐——skills 是跨用户共享内容，物理上挂在共享区。当调用方显式传入 path 时以传入值为准。
+ */
+export function formatSkillsForPrompt(
+  result: LoadSkillsResult,
+  _skillsBasePath: string = '/mnt/shared/skills',
+): string {
+  if (result.skills.length === 0) return '';
+
+  const lines = [
+    '',
+    '## Available Skills',
+    'Use `search_skills` to find relevant skills by keyword before loading. Use `loadSkill` to load a skill when the user\'s request matches:',
+    '',
+    ...result.skills.map((s) => {
+      return `- **${s.name}**: ${s.description || '(no description)'}`;
+    }),
+    '',
+  ];
+
+  return lines.join('\n');
+}

package/src/skills.types.ts

@@ -0,0 +1,42 @@
+/**
+ * Skills 类型定义
+ * pi-skills 标准格式
+ *
+ * 注意：身份字段（role_title, name_pool, avatar, slogan, role_description）已移至
+ * agent_roles 数据库表。SkillDefinition 仅保留能力字段。
+ */
+
+/** @deprecated 向后兼容别名，请使用 SkillDefinition */
+export type RoleDefinition = SkillDefinition;
+
+export type SkillDefinition = {
+  tools: string[];
+  prompt_extension: string;
+};
+
+export type Skill = {
+  name: string;
+  description: string;
+  /** 触发词：用于 search_skills 匹配，逗号/空格分隔，如 "做游戏,创建,打砖块" */
+  triggers?: string;
+  filePath?: string; // 沙箱内路径，如 /mnt/memory/skills/foo/SKILL.md
+  skillDefinition?: SkillDefinition; // 可选，不是所有 skill 都有
+  /** @deprecated 请使用 skillDefinition */
+  roleDefinition?: SkillDefinition;
+};
+
+export type LoadSkillsOptions = {
+  sandboxId?: string | null;
+  skillsPath?: string; // 沙箱内系统 skills 根路径
+  sessionSkillsPath?: string; // 沙箱内会话 skills 路径，如 /mnt/memory/sessions/{id}/skills
+  skillPaths?: string[]; // 本地路径列表（AGENT_SKILLS_PATHS）
+  sandboxClient?: {
+    listFiles(sandboxId: string, path: string): Promise<Array<{ name: string; path: string; type?: string }>>;
+    readFile(sandboxId: string, path: string, opts?: { format?: string }): Promise<string | Uint8Array>;
+  };
+};
+
+export type LoadSkillsResult = {
+  skills: Skill[];
+  source: 'sandbox' | 'local';
+};