scrum-skills 0.2.2 → 0.2.3

package/tools/ai.mjs

@@ -0,0 +1,442 @@
+/**
+ * 看板内置 AI 助手服务（零依赖，node >= 18）
+ *
+ * 三件事：
+ *   1. 参数落盘：服务商 / 地址 / Key / 模型 / 系统提示词 / 温度 / 工具轮数 / 上下文上限。
+ *      Key 只存本机文件（0600），HTTP 读配置永远不回传，只回 hasKey。
+ *   2. 流式代理：把前端的「一问」拼成 OpenAI 兼容的 /chat/completions 请求，
+ *      边收 SSE 边把 text / reasoning / tool 事件吐给前端，浏览器不必碰 Key 也不受 CORS 限制。
+ *   3. 工具循环：模型要 search_agile / update_agile 就执行，结果回灌再来一轮；
+ *      到轮数上限强制收口（最后一轮不带工具），否则模型会一直调下去。
+ *
+ * 审核策略（reviewMode）在这里落地：manual 只调 tools.propose 产待审变更，
+ * auto 直接 tools.patch 落盘（写入方自己带校验与回滚）。
+ * manual 一旦产出待审变更就停流（awaiting-approval）：等人点头再继续，
+ * 不能一边等批准一边把后面的活干完——用户会看到「没批就已经输出完了」。
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+export const PROVIDER_PRESETS = [
+  { id: 'deepseek', label: 'DeepSeek', baseUrl: 'https://api.deepseek.com', model: 'deepseek-chat' },
+  { id: 'openai', label: 'OpenAI', baseUrl: 'https://api.openai.com/v1', model: 'gpt-4o-mini' },
+  { id: 'moonshot', label: 'Moonshot 月之暗面', baseUrl: 'https://api.moonshot.cn/v1', model: 'moonshot-v1-8k' },
+  { id: 'siliconflow', label: '硅基流动', baseUrl: 'https://api.siliconflow.cn/v1', model: 'deepseek-ai/DeepSeek-V3' },
+  { id: 'ollama', label: '本地 Ollama', baseUrl: 'http://localhost:11434/v1', model: 'qwen2.5:7b' },
+  { id: 'custom', label: '自定义', baseUrl: '', model: '' },
+];
+
+/**
+ * 内置工作说明：只写「能碰什么 / 怎么碰 / 答的时候守什么」。
+ * 不写人设、不提厂商、不要求自我介绍——那些都是无关提示词：占 token、把
+ * 项目数据挤到后面，还容易让模型把回答变成「我是某某开发的 AI」。
+ * 用户自己在设置里填的系统提示词会追加在这段后面，两者都不为空才拼进去。
+ */
+export const BASE_SYSTEM = [
+  '你在一个敏捷看板里工作：只能通过工具访问当前项目 agile/ 下的数据。',
+  '- search_agile：检索 backlog / sprints / journal',
+  '- update_agile：按路径改数据（路径形如 stories.S-011.status）；写前自动校验，手动审核时先出待审变更',
+  '规则：',
+  '1. 涉及具体故事 / 任务 / 迭代的问题，先查再答；查不到就说没有。',
+  '2. 不要凭空编 id、状态、日期、人名，也不要造测试数据。',
+  '3. 改数据前用一句话说明要改什么，改完说明改了哪几条。',
+  '4. 用简体中文，直接给结论：不复述问题、不做自我介绍、不寒暄。',
+].join('\n');
+
+export const DEFAULT_CONFIG = {
+  provider: 'deepseek',
+  baseUrl: 'https://api.deepseek.com',
+  apiKey: '',
+  model: 'deepseek-chat',
+  // 系统提示词留空：内置说明已经够用，用户想加偏好再填
+  systemPrompt: '',
+  temperature: 0.3,
+  maxToolRounds: 30,
+  contextLimit: 256000,
+  autoCompact: true,
+  reviewMode: 'manual',
+};
+
+export const TOOL_SPECS = [
+  {
+    type: 'function',
+    function: {
+      name: 'search_agile',
+      description: '在当前项目的 agile/ 数据里检索（backlog / sprints / journal）。多个关键词用空格分隔，需同时命中同一条记录。',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: '检索关键词，例如「S-011 阻塞」' },
+          limit: { type: 'integer', description: '最多返回多少条，默认 20' },
+          file: { type: 'string', enum: ['backlog', 'sprints', 'journal'], description: '只搜某个文件（可选）' },
+        },
+        required: ['query'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'update_agile',
+      description:
+        '按路径更新敏捷数据。path 用点号写法：stories.S-011.status（对象字段）、stories.S-011.tasks（数组本身，配 op push/remove）。'
+        + '写前会跑 tools/validate.mjs，校验不过自动回滚。',
+      parameters: {
+        type: 'object',
+        properties: {
+          file: { type: 'string', enum: ['backlog', 'sprints', 'journal'], description: '要改哪个文件' },
+          reason: { type: 'string', description: '为什么改，写给人看的一句话' },
+          patches: {
+            type: 'array',
+            description: '一批补丁，按顺序应用',
+            items: {
+              type: 'object',
+              properties: {
+                op: { type: 'string', enum: ['set', 'push', 'remove'], description: '默认 set' },
+                path: { type: 'string' },
+                value: {},
+              },
+              required: ['path'],
+            },
+          },
+        },
+        required: ['file', 'patches'],
+      },
+    },
+  },
+];
+
+// SCRUM_AI_STORE 只服务「换一份配置跑冒烟」的场景（验证脚本别去动用户真实配置）
+const defaultStore = process.env.SCRUM_AI_STORE || join(process.env.APPDATA || join(homedir(), '.config'), 'scrum-skills', 'ai.json');
+
+const CJK = /[\u2e80-\u9fff\uf900-\ufaff\uff00-\uffef\u3000-\u303f]/;
+
+/** 粗略估 token：中日韩 0.7 字/个，其它 4 字符 1 个。宁可高估，别把请求撑爆。 */
+export function estimateTokens(text) {
+  let cjk = 0;
+  let rest = 0;
+  for (const ch of String(text ?? '')) {
+    if (CJK.test(ch)) cjk += 1;
+    else rest += 1;
+  }
+  return cjk * 0.7 + rest / 4;
+}
+
+const costOf = messages => messages.reduce((sum, m) => sum + estimateTokens(m.content) + 8, 0);
+
+/**
+ * 上下文预算：保留系统提示词与最后一块（当前提问），从最早处整块丢弃。
+ * assistant(tool_calls) 与其后的 tool 结果必须同进同退——拆开接口直接 400。
+ */
+export function trimMessages(messages, limit) {
+  const all = (messages ?? []).filter(m => m && m.role);
+  const systems = all.filter(m => m.role === 'system');
+  const rest = all.filter(m => m.role !== 'system');
+  const blocks = [];
+  for (const m of rest) {
+    const prev = blocks[blocks.length - 1];
+    if (m.role === 'tool') {
+      if (prev && prev.messages[0]?.role === 'assistant') prev.messages.push(m);
+      else blocks.push({ messages: [m] });
+      continue;
+    }
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+      blocks.push({ messages: [m] });
+      continue;
+    }
+    blocks.push({ messages: [m] });
+  }
+  if (!blocks.length) return [...systems];
+  const tail = blocks[blocks.length - 1];
+  let head = blocks.slice(0, -1);
+  const fits = () => costOf([...systems, ...head.flatMap(b => b.messages), ...tail.messages]) <= limit;
+  while (head.length && !fits()) head = head.slice(1);
+  return [...systems, ...head.flatMap(b => b.messages), ...tail.messages];
+}
+
+/** 把 OpenAI 兼容的 SSE 响应拆成事件；半个 chunk 拼不出来的先留着等下一段 */
+async function* readSse(response) {
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop() ?? '';
+    for (const raw of lines) {
+      const line = raw.trim();
+      if (!line.startsWith('data:')) continue;
+      const payload = line.slice(5).trim();
+      if (!payload) continue;
+      if (payload === '[DONE]') {
+        yield { kind: 'finish', reason: 'stop' };
+        continue;
+      }
+      let json;
+      try {
+        json = JSON.parse(payload);
+      } catch {
+        continue;
+      }
+      const choice = json.choices?.[0];
+      const delta = choice?.delta ?? {};
+      if (delta.reasoning_content) yield { kind: 'reasoning', text: String(delta.reasoning_content) };
+      if (typeof delta.content === 'string' && delta.content) yield { kind: 'text', text: delta.content };
+      for (const call of delta.tool_calls ?? []) {
+        yield {
+          kind: 'tool',
+          index: call.index ?? 0,
+          id: call.id,
+          name: call.function?.name,
+          argsText: call.function?.arguments ?? '',
+        };
+      }
+      if (choice?.finish_reason) yield { kind: 'finish', reason: choice.finish_reason };
+    }
+  }
+}
+
+const clampInt = (value, min, max, fallback) => {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+};
+
+export function createAiService({ root, store = defaultStore, token = '', tools, fetchImpl = globalThis.fetch } = {}) {
+  const pickKnown = source => Object.fromEntries(
+    Object.keys(DEFAULT_CONFIG).filter(k => source[k] !== undefined).map(k => [k, source[k]]),
+  );
+  const load = () => {
+    try {
+      return { ...DEFAULT_CONFIG, ...pickKnown(JSON.parse(readFileSync(store, 'utf8'))) };
+    } catch {
+      return { ...DEFAULT_CONFIG };
+    }
+  };
+  let config = load();
+
+  const masked = () => {
+    const { apiKey, ...rest } = config;
+    return { ...rest, hasKey: !!apiKey, presets: PROVIDER_PRESETS, tools: TOOL_SPECS.map(t => t.function.name) };
+  };
+
+  function updateConfig(patch = {}) {
+    const next = { ...config };
+    const num = (key, min, max, label) => {
+      if (patch[key] === undefined) return;
+      const n = Number(patch[key]);
+      if (!Number.isFinite(n) || n < min || n > max) throw new Error(`配置非法：${label} 必须是 ${min}~${max} 之间的数字`);
+      next[key] = key === 'temperature' ? n : Math.round(n);
+    };
+
+    if (patch.provider !== undefined) {
+      const preset = PROVIDER_PRESETS.find(p => p.id === patch.provider);
+      if (!preset) throw new Error(`配置非法：服务商 ${patch.provider} 不在预设列表里`);
+      next.provider = preset.id;
+      if (patch.baseUrl === undefined && preset.baseUrl) next.baseUrl = preset.baseUrl;
+      if (patch.model === undefined && preset.model) next.model = preset.model;
+    }
+    if (patch.baseUrl !== undefined) {
+      const url = String(patch.baseUrl).trim().replace(/\/+$/, '');
+      if (!/^https?:\/\/\S+$/i.test(url)) throw new Error('配置非法：接口地址必须以 http:// 或 https:// 开头');
+      next.baseUrl = url;
+    }
+    if (patch.model !== undefined) {
+      const model = String(patch.model).trim();
+      if (!model) throw new Error('配置非法：模型名不能为空');
+      next.model = model;
+    }
+    if (patch.apiKey !== undefined) {
+      if (patch.apiKey === null) next.apiKey = '';
+      else if (typeof patch.apiKey === 'string') next.apiKey = patch.apiKey.trim();
+      else throw new Error('配置非法：API Key 必须是字符串或 null');
+    }
+    if (patch.systemPrompt !== undefined) next.systemPrompt = String(patch.systemPrompt);
+    if (patch.autoCompact !== undefined) next.autoCompact = !!patch.autoCompact;
+    if (patch.reviewMode !== undefined) {
+      if (!['manual', 'auto'].includes(patch.reviewMode)) throw new Error('配置非法：reviewMode 只能是 manual 或 auto');
+      next.reviewMode = patch.reviewMode;
+    }
+    num('temperature', 0, 2, '温度');
+    num('maxToolRounds', 1, 50, '工具调用轮数上限');
+    num('contextLimit', 8000, 2_000_000, '上下文上限');
+
+    config = next;
+    mkdirSync(dirname(store), { recursive: true });
+    writeFileSync(store, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    return masked();
+  }
+
+  function executeTool(name, args = {}) {
+    try {
+      if (!tools) return { ok: false, output: '当前没有可用的工具。' };
+      if (name === 'search_agile') {
+        const result = tools.search(args.query, { limit: clampInt(args.limit, 1, 50, 20), file: args.file });
+        return { ok: true, output: result, wrote: false };
+      }
+      if (name === 'update_agile') {
+        const args2 = { file: args.file, patches: args.patches, reason: args.reason };
+        if (config.reviewMode === 'manual') {
+          const record = tools.propose(args2);
+          return {
+            ok: true,
+            pending: record,
+            wrote: false,
+            output: { status: '已生成待审变更，等用户批准后才写入', id: record.id, file: record.file, changes: record.changes },
+          };
+        }
+        const result = tools.patch(args2);
+        return { ok: true, output: { status: '已写入并通过校验', ...result }, wrote: true };
+      }
+      return { ok: false, output: `未知工具 ${name}` };
+    } catch (e) {
+      return { ok: false, output: `工具执行失败：${e.message}` };
+    }
+  }
+
+  async function* runChat({ messages = [], signal } = {}) {
+    if (!config.baseUrl) {
+      yield { type: 'error', message: '还没配置接口地址，先点开设置选一个服务商。' };
+      return;
+    }
+    if (!config.apiKey && config.provider !== 'ollama') {
+      yield { type: 'error', message: '还没配置 API Key：点抽屉右上角的设置按钮填好再聊（本地 Ollama 可以留空）。' };
+      return;
+    }
+
+    let history = config.autoCompact === false ? [...messages] : trimMessages(messages, config.contextLimit);
+    // 内置说明 + 用户自定义偏好，两者都为空的极端情况也别发一条空 system
+    const system = [BASE_SYSTEM, String(config.systemPrompt ?? '').trim()].filter(Boolean).join('\n\n');
+    const convo = [{ role: 'system', content: system }, ...history];
+    let rounds = 0;
+    try {
+      while (true) {
+        const useTools = rounds < config.maxToolRounds;
+        const body = { model: config.model, temperature: config.temperature, stream: true, messages: convo };
+        if (useTools) {
+          body.tools = TOOL_SPECS;
+          body.tool_choice = 'auto';
+        }
+        const response = await fetchImpl(`${config.baseUrl.replace(/\/+$/, '')}/chat/completions`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', authorization: `Bearer ${config.apiKey}` },
+          body: JSON.stringify(body),
+          signal,
+        });
+        if (!response.ok) {
+          const detail = await response.text().catch(() => '');
+          yield { type: 'error', message: `模型接口返回 ${response.status}：${detail.slice(0, 300) || response.statusText}` };
+          return;
+        }
+
+        let content = '';
+        const calls = new Map();
+        for await (const event of readSse(response)) {
+          if (event.kind === 'text') {
+            content += event.text;
+            yield { type: 'text', delta: event.text };
+          } else if (event.kind === 'reasoning') {
+            yield { type: 'reasoning', delta: event.text };
+          } else if (event.kind === 'tool') {
+            const key = event.index ?? 0;
+            const current = calls.get(key) ?? { id: '', name: '', argsText: '' };
+            if (event.id) current.id = event.id;
+            if (event.name) current.name = event.name;
+            current.argsText += event.argsText ?? '';
+            calls.set(key, current);
+          }
+        }
+
+        const list = [...calls.values()].filter(c => c.name);
+        if (!list.length) {
+          yield { type: 'done', rounds };
+          return;
+        }
+
+        convo.push({
+          role: 'assistant',
+          content,
+          tool_calls: list.map((c, i) => ({
+            id: c.id || `call_${rounds + 1}_${i}`,
+            type: 'function',
+            function: { name: c.name, arguments: c.argsText || '{}' },
+          })),
+        });
+        rounds += 1;
+
+        for (const call of convo[convo.length - 1].tool_calls) {
+          let parsed = {};
+          try {
+            parsed = JSON.parse(call.function.arguments || '{}');
+          } catch {
+            parsed = {};
+          }
+          yield { type: 'tool-call', id: call.id, name: call.function.name, args: parsed };
+          const executed = executeTool(call.function.name, parsed);
+          convo.push({
+            role: 'tool',
+            tool_call_id: call.id,
+            name: call.function.name,
+            content: typeof executed.output === 'string' ? executed.output : JSON.stringify(executed.output),
+          });
+          yield {
+            type: 'tool-result',
+            id: call.id,
+            name: call.function.name,
+            ok: executed.ok,
+            wrote: !!executed.wrote,
+            output: typeof executed.output === 'string' ? executed.output : JSON.stringify(executed.output, null, 2),
+          };
+          if (executed.pending) {
+            yield { type: 'pending', record: executed.pending };
+            // 手动审核：变更在等人点头，就地停流。
+            // 继续跑下一轮，模型会把「已排队等批准」理解成「已经做完」，接着把剩下的活说完，
+            // 用户还没审就已经在看后续输出了；同一批里的其它工具调用也不再执行，免得一次冒出多条待审。
+            yield { type: 'awaiting-approval', id: executed.pending.id };
+            return;
+          }
+        }
+      }
+    } catch (e) {
+      yield { type: 'error', message: String(e?.message ?? e) };
+    }
+  }
+
+  return {
+    root,
+    token: () => token,
+    readConfig: masked,
+    updateConfig,
+    runChat,
+    pending: () => (tools?.listPending ? tools.listPending() : []),
+    applyPending: id => tools.applyPending(id),
+    rejectPending: id => tools.rejectPending(id),
+  };
+}
+
+/** HTTP 分发：与 handleProjectApi 同一套本机同来源校验，POST 还要带项目 token */
+export async function handleAiApi(service, { method, path, headers = {}, body } = {}) {
+  const host = headers.host || '';
+  const denied = () => ({ status: 403, body: { error: '仅允许本机同来源访问。' } });
+  if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(host)) return denied();
+  if (headers.origin && headers.origin !== `http://${host}`) return denied();
+  if (headers['sec-fetch-site'] === 'cross-site') return denied();
+
+  const url = new URL(path, `http://${host}`);
+  try {
+    if (method === 'GET' && url.pathname === '/api/ai/config') return { status: 200, body: service.readConfig() };
+    if (method === 'GET' && url.pathname === '/api/ai/pending') return { status: 200, body: { pending: service.pending() } };
+    if (method !== 'POST') return { status: 405, body: { error: '不支持的请求方法。' } };
+    if (headers['x-project-token'] !== service.token()) return denied();
+    if (url.pathname === '/api/ai/config') return { status: 200, body: service.updateConfig(body ?? {}) };
+    if (url.pathname === '/api/ai/chat') return { status: 200, stream: service.runChat({ messages: body?.messages ?? [], signal: body?.signal }) };
+    if (url.pathname === '/api/ai/pending/apply') return { status: 200, body: service.applyPending(body?.id) };
+    if (url.pathname === '/api/ai/pending/reject') return { status: 200, body: service.rejectPending(body?.id) };
+    return { status: 404, body: { error: '接口不存在。' } };
+  } catch (e) {
+    return { status: 400, body: { error: String(e?.message ?? e) } };
+  }
+}

package/tools/projects.mjs

@@ -0,0 +1,140 @@
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+const validator = fileURLToPath(new URL('./validate.mjs', import.meta.url));
+const defaultStore = join(process.env.APPDATA || join(homedir(), '.config'), 'scrum-skills', 'projects.json');
+
+export async function pickDirectory() {
+  let command, args;
+  if (process.platform === 'win32') {
+    command = 'powershell.exe';
+    const script = `
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class FolderPickerDpi {
+  [DllImport("user32.dll")] private static extern IntPtr SetThreadDpiAwarenessContext(IntPtr context);
+  [DllImport("user32.dll")] private static extern bool SetProcessDPIAware();
+  public static void Enable() {
+    try {
+      if (SetThreadDpiAwarenessContext(new IntPtr(-4)) != IntPtr.Zero) return;
+      if (SetThreadDpiAwarenessContext(new IntPtr(-3)) != IntPtr.Zero) return;
+    } catch (EntryPointNotFoundException) {}
+    SetProcessDPIAware();
+  }
+}
+'@
+[FolderPickerDpi]::Enable()
+Add-Type -AssemblyName System.Windows.Forms
+[System.Windows.Forms.Application]::EnableVisualStyles()
+$d = New-Object System.Windows.Forms.FolderBrowserDialog
+$d.Description = '选择包含 agile 文件夹的项目根目录'
+$d.ShowNewFolderButton = $false
+try {
+  if ($d.ShowDialog() -eq 'OK') { [Console]::Write($d.SelectedPath) }
+} finally { $d.Dispose() }
+`;
+    args = ['-NoProfile', '-STA', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')];
+  } else if (process.platform === 'darwin') {
+    command = 'osascript';
+    args = ['-e', 'try', '-e', 'POSIX path of (choose folder with prompt "选择包含 agile 的项目根目录")', '-e', 'on error number -128', '-e', 'return ""', '-e', 'end try'];
+  } else {
+    command = 'zenity';
+    args = ['--file-selection', '--directory', '--title=选择包含 agile 的项目根目录'];
+  }
+  try {
+    const { stdout } = await exec(command, args, { encoding: 'utf8', timeout: 300000, maxBuffer: 65536 });
+    return stdout.trim() || null;
+  } catch (e) {
+    if (process.platform === 'linux' && e.code === 1) return null;
+    throw new Error('无法打开系统目录选择框，请确认本机有图形桌面（Linux 需安装 zenity）。');
+  }
+}
+
+function snapshot(root) {
+  const read = file => JSON.parse(readFileSync(join(root, 'agile', file + '.json'), 'utf8'));
+  return { backlog: read('backlog'), sprints: read('sprints'), journal: read('journal'), meta: { root, servedAt: new Date().toISOString() } };
+}
+
+function validate(root) {
+  try {
+    execFileSync(process.execPath, [validator, root], { encoding: 'utf8', timeout: 15000, maxBuffer: 1024 * 1024 });
+  } catch (e) {
+    throw new Error(`项目敏捷数据校验失败：${e.stdout || e.message}`);
+  }
+}
+
+export function createProjects({ root, store = defaultStore, pick = pickDirectory }) {
+  const token = randomBytes(24).toString('hex');
+  let recent = [];
+  try {
+    const saved = JSON.parse(readFileSync(store, 'utf8'));
+    if (Array.isArray(saved.recent)) recent = saved.recent.filter(x => typeof x === 'string').slice(0, 10);
+  } catch {}
+  const initial = realpathSync(root);
+  let current = initial;
+  for (const candidate of [...recent, initial]) {
+    try {
+      const path = realpathSync(candidate);
+      validate(path);
+      snapshot(path);
+      current = path;
+      break;
+    } catch {}
+  }
+  recent = [...new Set([current, ...recent, initial])].slice(0, 10);
+  let selecting = false;
+  const list = () => ({ recent: [...recent], root: current, token });
+  const read = (path = current) => {
+    if (!recent.includes(path)) throw new Error('该项目未打开，请先选择文件夹。');
+    return snapshot(path);
+  };
+  const open = async path => {
+    const canonical = realpathSync(path);
+    validate(canonical);
+    const data = snapshot(canonical);
+    const next = [canonical, ...recent.filter(x => x !== canonical)].slice(0, 10);
+    mkdirSync(dirname(store), { recursive: true });
+    writeFileSync(store, JSON.stringify({ recent: next }, null, 2) + '\n', { mode: 0o600 });
+    recent = next;
+    current = canonical;
+    return { ...list(), data };
+  };
+  const select = async () => {
+    if (selecting) throw new Error('目录选择框已打开，请先完成选择。');
+    selecting = true;
+    try {
+      const selected = await pick();
+      return selected ? await open(selected) : null;
+    } finally { selecting = false; }
+  };
+  return { list, read, open, select };
+}
+
+export async function handleProjectApi(projects, { method, path, headers, body }) {
+  const host = headers.host || '';
+  const denied = () => ({ status: 403, body: { error: '仅允许本机同来源访问。' } });
+  if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(host)) return denied();
+  if (headers.origin && headers.origin !== `http://${host}`) return denied();
+  if (headers['sec-fetch-site'] === 'cross-site') return denied();
+  const url = new URL(path, `http://${host}`);
+  try {
+    if (method === 'GET' && url.pathname === '/api/projects') return { status: 200, body: projects.list() };
+    if (method === 'GET' && url.pathname === '/api/agile') return { status: 200, body: projects.read(url.searchParams.get('root') || undefined) };
+    if (method !== 'POST') return { status: 405, body: { error: '不支持的请求方法。' } };
+    if (headers['x-project-token'] !== projects.list().token) return denied();
+    if (url.pathname === '/api/projects/select') return { status: 200, body: await projects.select() };
+    if (url.pathname === '/api/projects/open') {
+      if (!projects.list().recent.includes(body?.root)) throw new Error('该项目不在最近列表中，请选择文件夹。');
+      return { status: 200, body: await projects.open(body.root) };
+    }
+    return { status: 404, body: { error: '接口不存在。' } };
+  } catch (e) { return { status: 400, body: { error: String(e.message) } }; }
+}