@fonlan/dsh-task-kanban 0.1.0 → 0.1.1

package/src/client/kanban-state.ts

@@ -1,32 +1,70 @@
 import { useSyncExternalStore } from 'react'
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 
-let client: ClientContext | null = null
+/**
+ * HMR-safe shared state store keyed on the global symbol registry.
+ *
+ * The client-hmr hot swap re-evaluates this module (a fresh `lib/client.js`
+ * bundle) WITHOUT reloading the page. A module-level singleton would then be
+ * duplicated per evaluation: the session-navigation wrapper installed by the
+ * OLD module copy keeps calling the OLD copy's `exitBoard`, which reads the
+ * OLD copy's `boardOpen`/`boardDisposer` — while a board opened after the swap
+ * writes the NEW copy's state cell. The wrapper would then no-op and clicking
+ * a sidebar session would never leave the board.
+ *
+ * Keeping every field on one `globalThis`-backed record (via `Symbol.for`, so
+ * all bundle copies resolve the same key) makes every copy read/write the same
+ * state cell, so exit works regardless of which module copy performed the
+ * enter.
+ */
+const STATE_KEY = Symbol.for('@fonlan/dsh-task-kanban/state')
+
+interface KanbanState {
+  client: ClientContext | null
+  boardRoot: ((props: Record<string, unknown>) => React.ReactNode) | null
+  boardDisposer: (() => void) | null
+  boardOpen: boolean
+  listeners: Set<() => void>
+}
+
+function getState(): KanbanState {
+  const g = globalThis as unknown as Record<symbol, KanbanState | undefined>
+  let state = g[STATE_KEY]
+  if (state === undefined) {
+    state = {
+      client: null,
+      boardRoot: null,
+      boardDisposer: null,
+      boardOpen: false,
+      listeners: new Set(),
+    }
+    g[STATE_KEY] = state
+  }
+  return state
+}
+
 export function setClient(ctx: ClientContext | null): void {
-  client = ctx
+  getState().client = ctx
 }
 export function getClient(): ClientContext | null {
-  return client
+  return getState().client
 }
 
-let boardRoot: ((props: Record<string, unknown>) => React.ReactNode) | null = null
 export function setBoardRoot(component: (props: Record<string, unknown>) => React.ReactNode): void {
-  boardRoot = component
+  getState().boardRoot = component
 }
 export function getBoardRoot(): ((props: Record<string, unknown>) => React.ReactNode) | null {
-  return boardRoot
+  return getState().boardRoot
 }
 
-let boardDisposer: (() => void) | null = null
-let boardOpen = false
-const listeners = new Set<() => void>()
 function notify(): void {
-  for (const l of listeners) l()
+  for (const listener of getState().listeners) listener()
 }
 export function isBoardOpen(): boolean {
-  return boardOpen
+  return getState().boardOpen
 }
 function subscribe(cb: () => void): () => void {
+  const listeners = getState().listeners
   listeners.add(cb)
   return () => { listeners.delete(cb) }
 }
@@ -35,12 +73,13 @@ export function useBoardOpen(): boolean {
 }
 
 export function enterBoard(): void {
-  const ctx = client
-  const root = boardRoot
-  if (ctx === null || root === null || boardDisposer !== null) return
+  const state = getState()
+  const ctx = state.client
+  const root = state.boardRoot
+  if (ctx === null || root === null || state.boardDisposer !== null) return
   try {
-    boardDisposer = ctx.slots.register({ name: 'conversation', priority: -1, locale: 'task-kanban' } as never, root as never)
-    boardOpen = true
+    state.boardDisposer = ctx.slots.register({ name: 'conversation', priority: -1, locale: 'task-kanban' } as never, root as never)
+    state.boardOpen = true
     notify()
   } catch (error) {
     console.error('[@fonlan/dsh-task-kanban] cannot open the board:', error)
@@ -48,18 +87,19 @@ export function enterBoard(): void {
 }
 
 export function exitBoard(): void {
-  if (boardDisposer !== null) {
-    boardDisposer()
-    boardDisposer = null
+  const state = getState()
+  if (state.boardDisposer !== null) {
+    state.boardDisposer()
+    state.boardDisposer = null
   }
-  if (boardOpen) {
-    boardOpen = false
+  if (state.boardOpen) {
+    state.boardOpen = false
     notify()
   }
 }
 
 export function toggleBoard(): void {
-  if (boardOpen) exitBoard()
+  if (isBoardOpen()) exitBoard()
   else enterBoard()
 }
 
@@ -76,7 +116,9 @@ export function toggleBoard(): void {
  * points covers all of them in one place.
  *
  * The wrapper is idempotent: a `kbBound` marker on the wrapper prevents a
- * second bind (plugin re-apply / HMR) from stacking another layer.
+ * second bind (plugin re-apply / HMR) from stacking another layer. Because the
+ * wrapper's exit goes through the shared state store, a wrapper left over from
+ * a previous (HMR-replaced) module copy still closes the board correctly.
  */
 export function bindSessionNavigation(ctx: ClientContext): void {
   const sessions = ctx.sessions

package/src/client/locales.ts

@@ -41,6 +41,10 @@ export const zh = {
   error: '错误',
   requirementLabel: '需求文本',
   requirementPlaceholder: '描述你要实现的需求……',
+  skillGestureHint: '开头输入 /skill-name 可指定细化时使用的 Skill（如 /grill-me）',
+  skillHint: '细化时将使用 Skill「{skill}」，并可与该会话交流打磨需求',
+  skillMenuUserOnly: '仅用户可调',
+  skillBadge: '细化 Skill：/{skill}',
   modelPlaceholder: '（使用默认模型）',
   noWorkspace: '没有可用工作区，请先在侧边栏添加',
   refresh: '刷新',
@@ -102,6 +106,10 @@ export const en = {
   error: 'Error',
   requirementLabel: 'Requirement',
   requirementPlaceholder: 'Describe what you want to build…',
+  skillGestureHint: 'Start with /skill-name to choose the refinement skill (e.g. /grill-me)',
+  skillHint: 'Refinement will use Skill “{skill}” — talk to this session to refine the requirement',
+  skillMenuUserOnly: 'User-only',
+  skillBadge: 'Refine skill: /{skill}',
   modelPlaceholder: '(use default model)',
   noWorkspace: 'No workspaces available — add one in the sidebar first',
   refresh: 'Refresh',

package/src/index.ts

@@ -15,7 +15,7 @@ import { registerApiRoutes } from './server/rpc.js'
 
 export const name = '@fonlan/dsh-task-kanban'
 
-export const inject = ['webServer', 'agents']
+export const inject = ['webServer', 'agents', 'skills']
 
 export const Config = z.object({})
 

package/src/server/prompts.ts

@@ -18,6 +18,30 @@ ${workspacePath}
 5. 不要向用户提问，自主决策。`
 }
 
+/**
+ * Interactive refinement prompt for a card created with a skill (e.g.
+ * `/grill-me`). The refinement session is explicit — the user can reply —
+ * so instead of deciding autonomously, the agent follows the skill's
+ * interview and asks whatever it needs before writing the plan back.
+ */
+export function interactiveRefinementPrompt(requirement: string, workspacePath: string): string {
+  return `你是一个需求分析师。请分析下面的需求，并为它在指定项目中的实现制定一个可执行的分阶段实现计划。
+
+【需求】
+${requirement}
+
+【项目目录】
+${workspacePath}
+
+【要求】
+1. 先浏览项目目录了解现状（阅读 README、关键源码与文档；本会话只做只读探索，不要修改任何文件）。
+2. 这是一个显式会话，可以且应该与用户交流：按上方 Skill 的指引对需求进行充分打磨，通过提问澄清需求中模糊、缺失或相互矛盾的地方，直到需求足够明确。
+3. 需求打磨完成后，把需求拆解为按顺序串行执行的实现阶段（phase）。简单需求 1 个 phase 即可；复杂需求拆多个 phase，每个 phase 必须是独立的、可串行执行的实现单元，后面的 phase 依赖前面 phase 的产出。
+4. 每个 phase 必须包含：id（如 p1/p2/p3）、标题、目标（goal，说明该 phase 要交付什么）。
+5. 完成后调用 kanban_write_plan 工具把完整计划写回（title、summary、phases）。这是唯一写回方式，不要把计划 JSON 直接输出到对话里。
+6. 用户回复前不要擅自调用 kanban_write_plan；也不要因为用户暂时没有回复就放弃，等待用户回答即可。`
+}
+
 /** Phase implementation session prompt; identical on retries (the model reads git status/diff itself). */
 export function phasePrompt(card: KanbanCard, phaseIndex: number, workdir: string): string {
   const plan = card.plan!

package/src/server/rpc.ts

@@ -131,7 +131,8 @@ export function registerApiRoutes(
     const requirement = requireString(p.requirement, 'requirement')
     const model = typeof p.model === 'string' ? p.model : ''
     const provider = typeof p.provider === 'string' ? p.provider : undefined
-    return runner.createTask({ workspacePath, requirement, model, provider })
+    const skill = typeof p.skill === 'string' && p.skill !== '' ? p.skill : undefined
+    return runner.createTask({ workspacePath, requirement, model, provider, ...(skill !== undefined ? { skill } : {}) })
   })
 
   route('move', async (p) => {

package/src/server/runner.ts

@@ -7,7 +7,7 @@
  */
 import { randomUUID } from 'node:crypto'
 import { appendFile, readFile } from 'node:fs/promises'
-import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
@@ -16,7 +16,8 @@ import type { KanbanCard, ErrorKind, Lane, Plan } from '../shared/card.js'
 import type { TaskStore } from './task-store.js'
 import type { KanbanSettingsFace } from './settings.js'
 import { currentBranch, detectBaseRef, hasStashMessage, isGitRepo, isTreeDirty, revParse, runGit, unmergedPaths } from './git.js'
-import { mergePrompt, phasePrompt, refinementPrompt } from './prompts.js'
+import { interactiveRefinementPrompt, mergePrompt, phasePrompt, refinementPrompt } from './prompts.js'
+import { loadCardSkill, parseSkillGesture, skillInvocationMessage } from './skills.js'
 import { registerKanbanTools, type KanbanToolResolver } from './tools.js'
 import type {} from '@deepseek-ai/dsh-agent-presets'
 
@@ -162,12 +163,20 @@ export class KanbanRunner implements KanbanToolResolver {
     return this.store.list(workspacePath)
   }
 
-  async createTask(input: { workspacePath: string; requirement: string; model: string; provider?: string }): Promise<KanbanCard> {
+  async createTask(input: { workspacePath: string; requirement: string; model: string; provider?: string; skill?: string }): Promise<KanbanCard> {
+    // A leading /skill-name gesture chooses the refinement skill; it is
+    // stripped from the stored requirement so the prose the model sees stays
+    // clean. The explicit `skill` field (client-parsed) wins when both are
+    // present.
+    const parsed = parseSkillGesture(input.requirement)
+    const skill = input.skill !== undefined && input.skill !== '' ? input.skill : parsed.skill
+    const requirement = skill !== undefined ? parsed.requirement : input.requirement.trim()
     const card = await this.store.create({
       workspacePath: input.workspacePath,
-      requirement: input.requirement,
+      requirement,
       model: input.model,
       provider: input.provider,
+      ...(skill !== undefined ? { skill } : {}),
       status: 'refining',
     })
     await this.ensureGitignoreDsh(input.workspacePath)
@@ -334,10 +343,62 @@ export class KanbanRunner implements KanbanToolResolver {
       const handle = await this.createAgent(sessionId, wsPath, route, this.toolResolver())
       this.keepHandle(cardId, handle)
       await this.attachRefinementSession(wsPath, sessionId)
-      handle.agent.followup(this.asUserMessage(refinementPrompt(card.requirement, wsPath)))
+      // The agent scope is the layer where preset skill providers live
+      // (skill-filesystem + tool-skill); load the card's skill through it.
+      const skill = card.skill !== undefined
+        ? await loadCardSkill(this.ctx, card.skill, wsPath, handle.agent)
+        : undefined
+      if (card.skill !== undefined && skill === undefined) {
+        await this.fail(cardId, 'refine_failed', `Skill "${card.skill}" 不存在或不可用于用户调用，请检查后重试`, 'demand')
+        return
+      }
+      if (skill !== undefined) {
+        // Queue the canonical <skill_content> block as injected context for
+        // the same pre-step that claims the refinement prompt (instructions
+        // form with the harness's skill-invocation source).
+        handle.agent.inject(skillInvocationMessage(skill))
+      }
+      const interactive = skill !== undefined
+      handle.agent.followup(this.asUserMessage(
+        interactive ? interactiveRefinementPrompt(card.requirement, wsPath) : refinementPrompt(card.requirement, wsPath),
+      ))
+      await this.driveRefinement(cardId, wsPath, sessionId, handle, interactive)
+    } catch (error) {
+      console.error('[task-kanban] refinement create/drive failed:', String(error))
+      await this.fail(cardId, 'refine_failed', `细化会话失败: ${String(error)}`, 'demand')
+    }
+  }
+
+  /**
+   * Drive the refinement session to a terminal card state. Non-interactive
+   * cards follow the original contract: the agent finishes one turn and must
+   * have written the plan. Interactive cards (created with a refinement
+   * skill) may ask the user clarifying questions — the session is explicit
+   * and visible in the workspace chat, so the runner waits for each reply
+   * instead of failing, and only settles when the plan is written or the
+   * session errors out.
+   */
+  private async driveRefinement(
+    cardId: string,
+    wsPath: string,
+    sessionId: SessionId,
+    handle: AgentHandle,
+    interactive: boolean,
+  ): Promise<void> {
+    while (true) {
+      // Arm the user-reply signal BEFORE waiting so no reply can slip past.
+      const reply = this.waitForUserReply(sessionId)
+      const settlement = this.waitForCardSettlement(cardId, wsPath)
       await handle.agent.whenIdle()
       const fresh = await this.store.get(wsPath, cardId)
-      if (fresh !== undefined && fresh.status === 'refining') {
+      if (fresh === undefined || fresh.status !== 'refining') {
+        reply.dispose()
+        settlement.dispose()
+        return
+      }
+      if (!interactive) {
+        reply.dispose()
+        settlement.dispose()
         // debug: log the session tail regardless
         try {
           const events = handle.agent.session.events
@@ -350,13 +411,57 @@ export class KanbanRunner implements KanbanToolResolver {
           console.error('[task-kanban] could not read session events:', String(error))
         }
         await this.fail(cardId, 'refine_failed', '细化会话结束但未通过 kanban_write_plan 写回计划', 'demand')
+        return
       }
-    } catch (error) {
-      console.error('[task-kanban] refinement create/drive failed:', String(error))
-      await this.fail(cardId, 'refine_failed', `细化会话失败: ${String(error)}`, 'demand')
+      // Interactive: the agent went idle without writing the plan — it asked
+      // the user something and is waiting for a reply. Wait for the next
+      // human message, then drive the agent through it and re-check. Also
+      // escape if the card is externally settled (writePlan/fail) without a
+      // message, so a stuck session cannot pin the card in 'refining'.
+      await Promise.race([reply.promise, settlement.promise])
+      reply.dispose()
+      settlement.dispose()
     }
   }
 
+  /**
+   * A promise resolving when the card stops being 'refining' (planned,
+   * failed, or gone), plus a disposer stopping the polling interval.
+   */
+  private waitForCardSettlement(cardId: string, wsPath: string): { promise: Promise<void>; dispose(): void } {
+    let resolve!: () => void
+    const promise = new Promise<void>((res) => { resolve = res })
+    const timer = setInterval(async () => {
+      const fresh = await this.store.get(wsPath, cardId)
+      if (fresh === undefined || fresh.status !== 'refining') {
+        clearInterval(timer)
+        resolve()
+      }
+    }, 1000)
+    timer.unref?.()
+    return { promise, dispose: () => clearInterval(timer) }
+  }
+
+  /**
+   * A promise resolving when a NEW human message enters the given session,
+   * plus a disposer detaching the listener. Messages injected by plugins with
+   * non-`user` sources (such as our skill-invocation instructions) never
+   * resolve it — only real human replies drive the interactive refinement.
+   */
+  private waitForUserReply(sessionId: SessionId): { promise: Promise<void>; dispose(): void } {
+    let settle!: () => void
+    const promise = new Promise<void>((resolve) => { settle = resolve })
+    const listener = (session: Session, event: SessionEvent): void => {
+      if (session.id !== sessionId) return
+      if (event.type !== 'user/message') return
+      const source = ('source' in event.data ? (event.data as { source?: { kind?: string } }).source : undefined)
+      if (source?.kind === 'user') settle()
+    }
+    const detach = this.ctx.on('session/event', listener)
+    const dispose = (): void => { if (typeof detach === 'function') detach() }
+    return { promise, dispose }
+  }
+
   private async createAgent(
     sessionId: SessionId,
     cwd: string,

package/src/server/skills.ts

@@ -0,0 +1,105 @@
+/**
+ * Skill wiring for requirement refinement.
+ *
+ * A task card may carry a skill name (e.g. `grill-me`) chosen in the
+ * create-task requirement input via a leading `/skill-name` gesture, matching
+ * the harness's user-invocation convention (the same whitespace-bounded token
+ * shape `tool-skill` scans for). The server strips the gesture from the stored
+ * requirement, records the skill on the card, and injects the canonical
+ * `renderSkillContent` block into the refinement session as an instructions-
+ * form user message with the harness's `skill-invocation` source, so the
+ * transcript UI renders it exactly like a user-invoked skill in chat.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { isSkillName, isUserInvocable, renderSkillContent, type SkillDefinition, type SkillSummary } from '@deepseek-ai/dsh-skill'
+
+/**
+ * The public skill-name gesture shape: a whitespace-bounded `/name` token
+ * matching the grammar `tool-skill` uses (kebab-case letters/digits), at the
+ * very start of the input (leading whitespace allowed). A second `/` or
+ * non-boundary character breaks the match, keeping file paths (`/usr/bin`)
+ * and fractions (`5/8`) out.
+ */
+const SKILL_GESTURE = /^\s*\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/
+
+/** A parsed leading skill gesture: the skill name plus the cleaned requirement. */
+export interface SkillGestureParse {
+  /** The skill name from the leading `/name` token, if the input led with one. */
+  skill?: string
+  /** The requirement text with the leading gesture removed. */
+  requirement: string
+}
+
+/**
+ * Extract a leading `/skill-name` gesture from raw create-task input. Only a
+ * token at the very start selects a skill; tokens later in the text are
+ * ordinary requirement prose (the user might legitimately mention paths or
+ * fractions). The name is grammar-validated but not registry-checked here —
+ * unknown names surface as a refinement error with a clear message.
+ */
+export function parseSkillGesture(raw: string): SkillGestureParse {
+  const m = SKILL_GESTURE.exec(raw)
+  if (m === null) return { requirement: raw.trim() }
+  return {
+    skill: m[1],
+    requirement: raw.slice(m[0].length).trim(),
+  }
+}
+
+/**
+ * The minimal view of the hosted skill registry the plugin needs: list for a
+ * summary lookup and get for a full body, both honoring the calling scope.
+ */
+export interface SkillRegistryFace {
+  list(options?: { cwd?: string; scope?: unknown }): Promise<SkillSummary[]>
+  get(name: string, options?: { cwd?: string; scope?: unknown }): Promise<SkillDefinition | undefined>
+}
+
+/** Resolve the host skill registry, or undefined when this profile lacks one. */
+export function skillRegistry(ctx: Context): SkillRegistryFace | undefined {
+  try {
+    return ctx.get('skills') as SkillRegistryFace | undefined
+  } catch {
+    // service not injected/mounted in this context
+    return undefined
+  }
+}
+
+/** Whether the provided skill name is a syntactically valid skill name. */
+export function validSkillName(name: string): boolean {
+  return isSkillName(name)
+}
+
+/**
+ * Build the instructions-form message carrying the rendered skill body, the
+ * same shape a user `/grill-me` invocation injects through `tool-skill`. The
+ * `skill-invocation` source is what the transcript UI decorates as a skill
+ * chip; the content is the canonical `<skill_content>` block.
+ */
+export function skillInvocationMessage(skill: Pick<SkillDefinition, 'name' | 'provider' | 'resourceBase' | 'content'>) {
+  return createUserMessage({
+    content: [{ type: 'text', text: renderSkillContent(skill) }],
+    source: { kind: 'skill-invocation', name: skill.name, form: 'instructions' },
+  })
+}
+
+/**
+ * Load the skill body the card names, scoped to the refinement agent so
+ * preset-layer providers (the filesystem skill roots) are visible. Returns
+ * undefined when the skill is unknown, not user-invocable, or the registry is
+ * absent — the caller decides how to surface that.
+ */
+export async function loadCardSkill(
+  ctx: Context,
+  name: string | undefined,
+  cwd: string,
+  scope: unknown,
+): Promise<Pick<SkillDefinition, 'name' | 'provider' | 'resourceBase' | 'content'> | undefined> {
+  if (name === undefined || !isSkillName(name)) return undefined
+  const registry = skillRegistry(ctx)
+  if (registry === undefined) return undefined
+  const skill = await registry.get(name, { cwd, scope })
+  if (skill === undefined || !isUserInvocable(skill)) return undefined
+  return skill
+}

package/src/server/task-store.ts

@@ -67,6 +67,7 @@ export class TaskStore {
     requirement: string
     model: string
     provider?: string
+    skill?: string
     status?: KanbanCard['status']
   }): Promise<KanbanCard> {
     const id = randomUUID()
@@ -77,6 +78,7 @@ export class TaskStore {
       requirement: input.requirement,
       model: input.model,
       ...(input.provider !== undefined ? { provider: input.provider } : {}),
+      ...(input.skill !== undefined && input.skill !== '' ? { skill: input.skill } : {}),
       status: input.status ?? 'draft',
       currentPhase: 0,
       phaseCount: 0,

package/src/shared/card.ts

@@ -73,6 +73,8 @@ export interface KanbanCard {
   id: string
   workspacePath: string
   requirement: string
+  /** Optional skill (e.g. `grill-me`) used to drive requirement refinement. */
+  skill?: string
   model: string
   /** Provider route for the model (from the modal selection). */
   provider?: string