scrum-skills 0.2.3 → 0.2.5

package/tools/ai.mjs

@@ -8,6 +8,8 @@
  *      边收 SSE 边把 text / reasoning / tool 事件吐给前端，浏览器不必碰 Key 也不受 CORS 限制。
  *   3. 工具循环：模型要 search_agile / update_agile 就执行，结果回灌再来一轮；
  *      到轮数上限强制收口（最后一轮不带工具），否则模型会一直调下去。
+ *   4. 多模态：前端可以把图片按 OpenAI 的 image_url 一起塞进 user content 数组，
+ *      这里原样透传；图片没有文字可估，按 IMAGE_TOKEN_ESTIMATE 计入上下文预算。
  *
  * 审核策略（reviewMode）在这里落地：manual 只调 tools.propose 产待审变更，
  * auto 直接 tools.patch 落盘（写入方自己带校验与回滚）。
@@ -42,6 +44,8 @@ export const BASE_SYSTEM = [
   '2. 不要凭空编 id、状态、日期、人名，也不要造测试数据。',
   '3. 改数据前用一句话说明要改什么，改完说明改了哪几条。',
   '4. 用简体中文，直接给结论：不复述问题、不做自我介绍、不寒暄。',
+  '5. 故事状态只有 draft / ready / in-progress / review / done / cancelled（已取消）这六种：'
+    + 'cancelled 是终态，表示这事不做了，要在回答里说清为什么取消；不做了的故事就标 cancelled，不要塞进 done 充数。',
 ].join('\n');
 
 export const DEFAULT_CONFIG = {
@@ -123,7 +127,21 @@ export function estimateTokens(text) {
   return cjk * 0.7 + rest / 4;
 }
 
-const costOf = messages => messages.reduce((sum, m) => sum + estimateTokens(m.content) + 8, 0);
+/**
+ * 一张图在请求里没有文字可估，按固定额度算。
+ * 不估（当成 0）会让「塞一堆截图」的对话永远不触发裁剪，请求体越滚越大直到接口 413；
+ * 估得偏高则是安全的：多裁几轮老对话，总比请求发不出去强。
+ */
+export const IMAGE_TOKEN_ESTIMATE = 800;
+
+const contentCost = content => (Array.isArray(content)
+  ? content.reduce(
+    (sum, part) => sum + (part?.type === 'image_url' ? IMAGE_TOKEN_ESTIMATE : estimateTokens(part?.text ?? '')),
+    0,
+  )
+  : estimateTokens(content));
+
+const costOf = messages => messages.reduce((sum, m) => sum + contentCost(m.content) + 8, 0);
 
 /**
  * 上下文预算：保留系统提示词与最后一块（当前提问），从最早处整块丢弃。
@@ -328,7 +346,11 @@ export function createAiService({ root, store = defaultStore, token = '', tools,
         });
         if (!response.ok) {
           const detail = await response.text().catch(() => '');
-          yield { type: 'error', message: `模型接口返回 ${response.status}：${detail.slice(0, 300) || response.statusText}` };
+          // 带图被拒最常见的原因是模型不是多模态：DeepSeek 的 chat / reasoner 都不收 image_url。
+          // 不点破的话用户只看到一行 400，会以为是 Key 或网络问题。
+          const withImages = convo.some(m => Array.isArray(m.content) && m.content.some(p => p?.type === 'image_url'));
+          const hint = withImages ? '（这一轮带了图片：当前模型可能不支持图片输入，请在设置里换成支持视觉模型的接口，或去掉图片再发）' : '';
+          yield { type: 'error', message: `模型接口返回 ${response.status}：${detail.slice(0, 300) || response.statusText}${hint}` };
           return;
         }
 

package/tools/projects.mjs

@@ -5,6 +5,7 @@ import { execFile, execFileSync } from 'node:child_process';
 import { promisify } from 'node:util';
 import { randomBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { createAgileTools } from './agile-tools.mjs';
 
 const exec = promisify(execFile);
 const validator = fileURLToPath(new URL('./validate.mjs', import.meta.url));
@@ -58,6 +59,24 @@ try {
   }
 }
 
+/**
+ * 故事状态单向车道。看板卡片的「下一步 / 退回」就按这条线走，
+ * done 是终点、cancelled 是另一条终点，两者都不许再动。
+ */
+export const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done'];
+
+const ACTION_LABEL = { next: '推进到下一状态', prev: '退回上一状态', cancel: '标记为已取消' };
+
+/** 按动作算出目标状态；算不出来（已是终点 / 动作不认识）返回 null */
+export function statusAfter(from, action) {
+  if (action === 'cancel') return ['draft', 'ready', 'in-progress', 'review'].includes(from) ? 'cancelled' : null;
+  if (!STORY_FLOW.includes(from)) return null;
+  const i = STORY_FLOW.indexOf(from);
+  if (action === 'next') return STORY_FLOW[i + 1] ?? null;
+  if (action === 'prev') return STORY_FLOW[i - 1] ?? null;
+  return null;
+}
+
 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() } };
@@ -78,18 +97,12 @@ export function createProjects({ root, store = defaultStore, pick = pickDirector
     const saved = JSON.parse(readFileSync(store, 'utf8'));
     if (Array.isArray(saved.recent)) recent = saved.recent.filter(x => typeof x === 'string').slice(0, 10);
   } catch {}
+  // 启动目录优先：从哪个目录起服务，看板就打开哪个目录。
+  // 最近列表只是「切回上次那个项目」的入口，不许顶替启动目录——
+  // 否则在 A 项目里 serve，会悄悄打开上一次的 B 项目数据（JSON 看着像是 A 的，其实全错）。
   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);
+  recent = [...new Set([current, ...recent])].slice(0, 10);
   let selecting = false;
   const list = () => ({ recent: [...recent], root: current, token });
   const read = (path = current) => {
@@ -115,7 +128,25 @@ export function createProjects({ root, store = defaultStore, pick = pickDirector
       return selected ? await open(selected) : null;
     } finally { selecting = false; }
   };
-  return { list, read, open, select };
+  // 写盘复用 AI 助手那套「文本补丁 + 写后校验 + 失败回滚」，
+  // 不另写一份：改一个状态只差一行字符，校验不过自动还原。
+  const tools = createAgileTools({ root: () => current });
+  const setStoryStatus = ({ id, action } = {}) => {
+    if (!id) throw new Error('缺少故事 id');
+    const { backlog } = snapshot(current);
+    const story = (backlog.stories ?? []).find(s => s.id === id);
+    if (!story) throw new Error(`找不到故事 ${id}`);
+    const from = story.status;
+    const to = statusAfter(from, action);
+    if (!to) throw new Error(`${id} 当前是 ${from}，没法${ACTION_LABEL[action] ?? `执行 ${action}`}`);
+    const patches = [{ path: `stories.${id}.status`, value: to }];
+    // 取消一条还被阻塞的故事：阻塞标记要一起摘掉。
+    // 校验器不许「已取消却还标着 blocked」，不摘会整条改动作废。
+    if (to === 'cancelled' && story.blocked) patches.push({ op: 'remove', path: `stories.${id}.blocked` });
+    tools.patch({ file: 'backlog', patches, reason: `看板卡片操作：${from} → ${to}` });
+    return { id, from, to };
+  };
+  return { list, read, open, select, setStoryStatus };
 }
 
 export async function handleProjectApi(projects, { method, path, headers, body }) {
@@ -130,6 +161,10 @@ export async function handleProjectApi(projects, { method, path, headers, body }
     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();
+    // 看板卡片的退回 / 下一步 / 取消：改的是当前打开项目的 backlog.json
+    if (url.pathname === '/api/agile/story-status') {
+      return { status: 200, body: projects.setStoryStatus({ id: body?.id, action: body?.action }) };
+    }
     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('该项目不在最近列表中，请选择文件夹。');

package/tools/serve.mjs

@@ -112,7 +112,7 @@ const server = createServer(async (req, res) => {
     return;
   }
 
-  if (pathname === '/api/agile' || pathname.startsWith('/api/projects')) {
+  if (pathname.startsWith('/api/agile') || pathname.startsWith('/api/projects')) {
     try {
       let text = '';
       for await (const chunk of req) {

package/tools/validate.mjs

@@ -50,7 +50,9 @@ const sprints = Array.isArray(sprintsFile.sprints) ? sprintsFile.sprints : [];
 const milestones = Array.isArray(sprintsFile.milestones) ? sprintsFile.milestones : [];
 const journals = Array.isArray(journalFile.journals) ? journalFile.journals : [];
 
-const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done'];
+const STORY_FLOW = ['draft', 'ready', 'in-progress', 'review', 'done', 'cancelled'];
+// 终态：done 与 cancelled 都不再往前走，也不再要求验收 / 任务全部做完
+const STORY_TERMINAL = ['done', 'cancelled'];
 const TASK_FLOW = ['todo', 'red', 'green', 'refactored', 'done'];
 const EPIC_FLOW = ['draft', 'active', 'done', 'cancelled'];
 const MILESTONE_FLOW = ['planned', 'at-risk', 'reached', 'missed'];
@@ -136,7 +138,8 @@ for (const s of stories) {
   else if (!(epicById.get(epicId).stories ?? []).includes(id))
     err(`story ${id}: 挂在 ${epicId} 上，但该 epic 的 stories 里没有它（双向引用不一致）`);
 
-  if (!STORY_FLOW.includes(status) && status !== 'cancelled') err(`story ${id}: 非法状态 ${status}`);
+  if (!STORY_FLOW.includes(status))
+    err(`story ${id}: 非法状态 ${status}（合法：${STORY_FLOW.join('/')}）`);
   if (!Number.isFinite(points)) err(`story ${id}: points 必须是数字`);
   else if (![1, 2, 3, 5, 8, 13].includes(points)) warn(`story ${id}: points ${points} 不在斐波那契序列`);
 
@@ -153,7 +156,8 @@ for (const s of stories) {
     }
   }
 
-  if ((status === 'ready' || STORY_FLOW.indexOf(status) > 1) && (!acceptance || acceptance.length === 0))
+  // 取消掉的故事不会再交付，别逼着为它补验收标准
+  if (['ready', 'in-progress', 'review', 'done'].includes(status) && (!acceptance || acceptance.length === 0))
     err(`story ${id}: 状态 ${status} 但验收标准为空`);
   for (const [i, a] of (acceptance ?? []).entries()) {
     if (!a.given || !a.when || !a.then) err(`story ${id}: 第 ${i + 1} 条验收标准缺 given/when/then`);
@@ -163,7 +167,8 @@ for (const s of stories) {
       if (!hit) err(`story ${id}: 第 ${i + 1} 条验收的 verifyBy ${tid} 不存在`);
       else if (hit.story.id !== id) err(`story ${id}: 第 ${i + 1} 条验收的 verifyBy ${tid} 属于 ${hit.story.id}`);
     }
-    if (!(a.verifyBy ?? []).length && status !== 'draft') warn(`story ${id}: 第 ${i + 1} 条验收没有 verifyBy（没绑定验证任务）`);
+    if (!(a.verifyBy ?? []).length && !['draft', 'cancelled'].includes(status))
+      warn(`story ${id}: 第 ${i + 1} 条验收没有 verifyBy（没绑定验证任务）`);
   }
 
   // 阻塞 / 依赖
@@ -175,7 +180,9 @@ for (const s of stories) {
     if (!s.blocked.reason) err(`story ${id}: blocked 缺少 reason（堵在哪要说清）`);
     if (!DATE_RE.test(s.blocked.since ?? '')) err(`story ${id}: blocked.since 格式应为 YYYY-MM-DD`);
     if (status === 'done') err(`story ${id}: 已 done 却还标着 blocked`);
-    if (sprintId) warn(`story ${id}: 处于 ${sprintId} 但被阻塞（${s.blocked.reason}），站会必须处理`);
+    if (status === 'cancelled') err(`story ${id}: 已取消却还标着 blocked（不做了就别再挂着阻塞）`);
+    if (sprintId && !STORY_TERMINAL.includes(status))
+      warn(`story ${id}: 处于 ${sprintId} 但被阻塞（${s.blocked.reason}），站会必须处理`);
   }
 
   // 范围变更标记
@@ -191,7 +198,8 @@ for (const s of stories) {
     if (!sp) err(`story ${id}: sprintId ${sprintId} 不存在`);
     else if (!(sp.stories ?? []).includes(id))
       err(`story ${id}: 指向 ${sprintId}，但该 sprint 的 stories 里没有它（双向引用不一致）`);
-    if (!acceptance || acceptance.length === 0) err(`story ${id}: 已进 sprint 但无验收标准（不满足 ready）`);
+    if (status !== 'cancelled' && (!acceptance || acceptance.length === 0))
+      err(`story ${id}: 已进 sprint 但无验收标准（不满足 ready）`);
   }
 
   if (s.schedule) {
@@ -230,8 +238,14 @@ for (const sp of sprints) {
     const st = storyById.get(sid);
     if (!st) { err(`sprint ${sp.id}: 引用 story ${sid} 不存在`); continue; }
     if (st.sprintId !== sp.id) err(`sprint ${sp.id}: story ${sid} 的 sprintId 是 ${st.sprintId}，双向引用不一致`);
+    if (st.status === 'cancelled')
+      warn(`story ${sid}: 已取消但仍排在 ${sp.id} 里，建议从迭代移出（点数已不计入承诺）`);
   }
-  const committed = (sp.stories ?? []).reduce((a, sid) => a + (storyById.get(sid)?.points ?? 0), 0);
+  // 已取消的故事不再占迭代容量：承诺点数只算还可能交付的
+  const committed = (sp.stories ?? []).reduce((a, sid) => {
+    const st = storyById.get(sid);
+    return st && st.status !== 'cancelled' ? a + (st.points ?? 0) : a;
+  }, 0);
   if (Number.isFinite(sp.capacity) && committed > sp.capacity)
     warn(`sprint ${sp.id}: 承诺 ${committed} 点超过容量 ${sp.capacity} 点`);
   if (sp.start <= today && sp.end >= today) active++;