@wjj865-code/dsh-orchestrator 0.3.4 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wjj865-code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -99,7 +99,7 @@ scoped 包默认是私有，**必须带 `--access public`** 才会公开；开
    @wjj865-code/dsh-orchestrator
    ```
 
-   也可以安装指定版本：`@wjj865-code/dsh-orchestrator@0.3.4`。
+   也可以安装指定版本：`@wjj865-code/dsh-orchestrator@0.4.0`。
 2. 装完彻底退出 DSH 再启动。
 3. 以后升级：`npm version patch` → `npm publish` → 在 DSH 插件页用 registry 包的更新入口升级（DSH 的 plugin manager 对 registry 包支持 `listVersions` / `updateBundle`），不再需要卸了重装 GitHub 版。
 
@@ -134,7 +134,7 @@ scoped 包默认是私有，**必须带 `--access public`** 才会公开；开
 | `spawnProvider` | `spawn` | subagent provider（本地 fresh 子会话用 `spawn`） |
 | `staleMinutes` | `30` | `task_list` 里超过这么多分钟无动静就标 `⚠` |
 | `stallRounds` | `3` | 预留：阶段 3 的连续无进展升级阈值，阶段 1 只校验并保存 |
-| `maxQueue` | `50` | 待派发队列安全阀：`pending` 任务到这个数就拒绝新建（不落库） |
+| `maxQueue` | `50` | 队列安全阀：`pending` + `waiting_dep` 到这个数就拒绝新建（不落库） |
 | `autoResumeQueue` | `true` | 重启后把排队中的任务自动重新入队并派发；关掉则只恢复队列不自动跑 |
 | `maxActive` | — | **已移除**：并发上限改由平台 `ACTIVATION_LIMIT_REACHED` + 插件队列自适应，旧配置里写了也会被忽略 |
 | `mergeWindowMs` | `5000` | 完成通知合并窗口 |
@@ -151,6 +151,20 @@ scoped 包默认是私有，**必须带 `--access public`** 才会公开；开
 - 「协调者会话尚未就绪（`agent.session` 为空）」按可重试处理：任务留在队列，等主会话就绪后重试，不标 failed。
 - 排队中的任务被 `task_stop` 会直接取消并移出队列；`task_message` 对排队任务返回可读提示（还没有子会话可续派）。
 
+## 依赖、分组、写域与优先级（P1）
+
+- `task_create` 新增可选参数：
+  - `dependsOn`：前置任务编号数组（最多 20 个），必须存在且不能是 `failed/cancelled/orphaned`。
+  - `group`：分组名，`task_list({ group })` 可看该组进度；面板行显示分组。
+  - `writeScopes`：写域（目录/文件路径），与活跃任务重叠时返回冲突提示，仅 advisory，不阻断。
+  - `priority`：`-10..10`，高的先派发；同优先级按创建时间 FIFO。
+- 前置未完成时任务落 `waiting_dep`（不派发、不占并发位）；每次 `queue.pump` 先做依赖晋升：
+  - 前置全部 `done` → `pending` 并入队；派发时 brief 追加 `【前置任务】` 摘要和产物路径。
+  - 前置 `failed/cancelled/orphaned` 或不存在 → 下游自动 `failed`，错误写明哪个前置未完成。
+- 只允许依赖已存在的任务，创建时不接受“未来的 id”，因此不会出现环；依赖失败后先 `task_retry` 前置，再重派下游。
+- `maxQueue` 口径包含 `waiting_dep`，避免等待图无限膨胀。
+- 面板/快照行新增 `dependsOn`、`groupId`、`writeScopes`、`priority`；`waiting_dep` 显示「等前置」。
+
 ## 只读子任务（显式 `readOnly`）
 
 - `task_create` 可选 `readOnly: true`（默认 false）；**只认显式 true**，字符串/偏真值不算，不按标题关键词猜。协调者自己判断任务性质（分析/审查/评估）后显式传。用法：
@@ -235,6 +249,7 @@ scoped 包默认是私有，**必须带 `--access public`** 才会公开；开
 17. **记忆闭环**：`memory_note` 写一条 → `history_search` 能查到 → 新建相关任务时 brief 带 `【历史经验】`；`task_report done` 后再 `history_search` 能查到该任务摘要。
 18. **项目上下文**：`project_context` 对项目目录返回 README/package/顶层结构/最近任务；不出现 `.env` 内容；不存在的 target 给可读错误。
 19. **重派与快照**：人为让任务 `failed` 后 `task_retry` 生成新任务、旧任务保留；`snapshots/tasks-YYYY-MM-DD.sqlite` 可打开且含任务；重启同一天不重复覆盖。
+20. **依赖/分组/优先级**：A 运行中建 `dependsOn:[A]` 的 B → B 是 `waiting_dep` 不派发；A `done` 后 B 自动派发且 brief 带 `【前置任务】`；A 失败时 B 自动失败。高 `priority` 任务先派发；同 `group` 可在 `task_list({group})` 看进度；`writeScopes` 重叠只提示不阻断。
 
 
 ## 工具
@@ -243,12 +258,12 @@ scoped 包默认是私有，**必须带 `--access public`** 才会公开；开
 
 | 工具 | 作用 |
 | --- | --- |
-| `task_create` | 建台账 + 渲染 brief + 入队派发子会话；缺验收标准/队列满（`maxQueue`）会拒绝；并发满自动排队，不报错；`readOnly:true` 时子会话沙箱只读 |
-| `task_list` | 默认只列活跃任务；带标题、目标摘要、最近一条消息、排队/陈旧标记；`active:false` 看全量 |
-| `task_status` | 单任务详情 + 最近 3 条消息 + 子会话打开方式 |
-| `task_message` | 续派消息（不新建任务），失败重试 3 次后转 `waiting_user`；排队中的任务返回提示 |
-| `task_stop` | 中断当前一轮并标 `cancelled`；排队中的任务直接取消并移出队列 |
-| `task_retry` | 重派 `failed`/`orphaned` 任务：用原 brief 新建一次尝试（新任务号，`retry_of` 留审计）；旧任务保留 |
+| `task_create` | 建台账 + 渲染 brief + 入队派发；支持 `dependsOn`（前置）、`group`（分组）、`writeScopes`（写域冲突提示）、`priority`（-10..10）；缺验收标准/队列满（`maxQueue`）会拒绝；并发满自动排队，不报错；`readOnly:true` 时子会话沙箱只读 |
+| `task_list` | 默认只列活跃任务（含 `waiting_dep`）；带标题、目标摘要、最近一条消息、排队/缺前置/陈旧标记；`group` 过滤并看组进度；`active:false` 看全量 |
+| `task_status` | 单任务详情 + 依赖/写域/分组/优先级 + 最近 3 条消息 + 子会话打开方式 |
+| `task_message` | 续派消息（不新建任务），失败重试 3 次后转 `waiting_user`；排队/等前置任务返回提示 |
+| `task_stop` | 中断当前一轮并标 `cancelled`；排队中或 `waiting_dep` 的任务直接取消 |
+| `task_retry` | 重派 `failed`/`orphaned` 任务：用原 brief 新建一次尝试（新任务号，`retry_of` 留审计）；保留依赖/分组/写域/优先级 |
 | `history_search` | 查跨项目记忆、历史任务、平台历史会话；给新任务补上下文 |
 | `project_context` | 读项目背景白名单文件、顶层结构、最近任务与相关记忆；只读 |
 | `memory_note` | 记一条跨任务有效的决策/偏好/约束，供之后检索与 brief 注入 |

package/client.js

@@ -18,7 +18,7 @@ window.__ModuleLoader__.load({
     ]
 
     const STATUS_LABEL = {
-      pending: '待派发', running: '进行中', waiting_user: '等你确认', waiting_auth: '要授权',
+      waiting_dep: '等前置', pending: '待派发', running: '进行中', waiting_user: '等你确认', waiting_auth: '要授权',
       done: '已完成', failed: '失败', cancelled: '已取消', orphaned: '会话丢失',
     }
     const TONE_COLOR = {
@@ -186,7 +186,7 @@ window.__ModuleLoader__.load({
       }
 
       const matchFilter = task => filter === 'all' ? true
-        : filter === 'active' ? (task.status === 'pending' || task.status === 'running')
+        : filter === 'active' ? (task.status === 'waiting_dep' || task.status === 'pending' || task.status === 'running')
           : filter === 'waiting' ? (task.status === 'waiting_user' || task.status === 'waiting_auth')
             : filter === 'done' ? task.status === 'done'
               : filter === 'failed' ? task.status === 'failed'
@@ -269,6 +269,10 @@ window.__ModuleLoader__.load({
                   task.targetDir !== null && task.targetDir !== undefined
                     ? h('span', { style: styles.meta, title: task.targetDir }, shortPath(task.targetDir))
                     : null,
+                  task.groupId ? h('span', { style: styles.meta, title: '分组' }, `组 ${task.groupId}`) : null,
+                  task.dependsOn && task.dependsOn.length > 0
+                    ? h('span', { style: styles.meta, title: task.dependsOn.join('、') }, `依赖 ${task.dependsOn.length}`)
+                    : null,
                   task.queued ? h('span', { style: styles.meta }, '排队中') : null,
                   task.stale ? h('span', { style: styles.meta }, '⚠') : null,
                   h('span', { style: styles.meta }, STATUS_LABEL[task.status] || task.status),

package/index.js

@@ -25,6 +25,7 @@ const COORDINATOR_POLICY = `你是 dsh-orchestrator 的协调者。硬性规则
 - 工具表里可能仍列出这些团队工具（agent-scope 自注册，预设层删不掉），看到也不要调用；执行层会直接拒绝并返回原因。
 - 查看进度只用 task_list / task_status。
 - 派任务前可用 history_search 查跨项目记忆与历史任务，用 project_context 读项目背景；长期有效的用户决策/偏好用 memory_note 记下来。
+- 有先后关系时用 task_create 的 dependsOn；同一需求用 group 归组；会改同一批文件时用 writeScopes 标写域；紧急任务用 priority（-10..10）。
 - 任何关于任务数量、重复、冲突、状态的断言，必须先调用 task_list / task_status 拿到工具返回再说话；没有工具输出佐证就不许下结论，不得凭记忆或推断。
 - 子任务完成或需要你决定时会主动通知你；收到通知再行动。
 - 本回合没有别的事就立即结束回合；通知会开启新回合。
@@ -150,6 +151,7 @@ export async function apply(ctx, rawConfig = {}) {
       // 协调者可能比插件晚加载：队列在等它，加载后立刻补跑，并对一次子会话目录。
       queue?.pump()
       reconcileOrphans({ db, dispatcher, coordinatorSessionId: id, isLive: isChildLive, logger, onWarn: warnings })
+        .then(() => queue?.pump())
         .catch(error => warnings(`dsh-orchestrator: 重启对账失败：${error?.message ?? error}`))
     }
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wjj865-code/dsh-orchestrator",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Coordinator + task sessions for DeepSeek Harness: durable task ledger, cross-project memory, project context, progress reports, interrupt-controlled notifications, snapshots, and a browser task panel.",
   "type": "module",
   "license": "MIT",

package/src/card.js

@@ -1,10 +1,10 @@
 // 卡片只描述数据，不关心渲染框架；阶段 2 的客户端直接复用它。
 const STATUS_LABEL = {
-  pending: '待派发', running: '进行中', waiting_user: '等你确认', waiting_auth: '要授权',
+  waiting_dep: '等前置', pending: '待派发', running: '进行中', waiting_user: '等你确认', waiting_auth: '要授权',
   done: '已完成', failed: '失败', cancelled: '已取消', orphaned: '会话丢失',
 }
 const STATUS_TONE = {
-  pending: 'muted', running: 'info', waiting_user: 'warn', waiting_auth: 'warn',
+  waiting_dep: 'muted', pending: 'muted', running: 'info', waiting_user: 'warn', waiting_auth: 'warn',
   done: 'good', failed: 'bad', cancelled: 'muted', orphaned: 'bad',
 }
 

package/src/deps.js

@@ -0,0 +1,133 @@
+// 任务依赖：只允许依赖已存在的任务；创建时把未就绪的任务放进 waiting_dep，
+// 依赖完成后再晋升为 pending 入队；依赖失败/丢失则向下游传播失败。
+import { getTask, listTasks, recentMessages, transition } from './ledger.js'
+import { taskLabelWithId } from './task-label.js'
+
+const STATUS_LABEL = {
+  waiting_dep: '等前置', pending: '待派发', running: '进行中', waiting_user: '等你确认',
+  waiting_auth: '要授权', done: '已完成', failed: '失败', cancelled: '已取消', orphaned: '会话丢失',
+}
+const FAILED_DEP = new Set(['failed', 'cancelled', 'orphaned'])
+const MAX_DEPENDS = 20
+
+const labelOf = status => STATUS_LABEL[status] ?? status
+const short = (value, max = 100) => {
+  const text = String(value ?? '').split('\n')[0].trim()
+  return text.length > max ? `${text.slice(0, max)}…` : text
+}
+
+/**
+ * 校验 dependsOn：去重、最多 20 条、必须存在，且不能依赖已经失败/取消/丢失的任务。
+ * @returns {{ok: true, ids: string[]} | {ok: false, error: string}}
+ */
+export function validateDepends(db, values) {
+  if (values === undefined || values === null) return { ok: true, ids: [] }
+  if (!Array.isArray(values)) return { ok: false, error: 'dependsOn 必须是任务编号数组' }
+  const ids = []
+  for (const value of values) {
+    if (typeof value !== 'string') return { ok: false, error: 'dependsOn 里每一项都必须是任务编号字符串' }
+    const id = value.trim()
+    if (id === '' || ids.includes(id)) continue
+    ids.push(id)
+  }
+  if (ids.length > MAX_DEPENDS) return { ok: false, error: `dependsOn 最多 ${MAX_DEPENDS} 个任务` }
+  for (const id of ids) {
+    const task = getTask(db, id)
+    if (task === undefined) return { ok: false, error: `前置任务不存在：${id}` }
+    if (FAILED_DEP.has(task.status)) {
+      return { ok: false, error: `前置任务「${taskLabelWithId(task)}」当前是${labelOf(task.status)}，不能作为依赖；先 task_retry 或新建一个可用的前置任务` }
+    }
+  }
+  return { ok: true, ids }
+}
+
+/** 依赖状态：missing（不存在）/ failed（终态失败）/ ready（全部 done）。 */
+export function dependencyState(db, task) {
+  const ids = Array.isArray(task?.depends_on) ? task.depends_on : []
+  const deps = []
+  const missing = []
+  const failed = []
+  for (const id of ids) {
+    const dep = getTask(db, id)
+    if (dep === undefined) {
+      missing.push({ id })
+      continue
+    }
+    deps.push(dep)
+    if (FAILED_DEP.has(dep.status)) failed.push(dep)
+  }
+  return {
+    deps,
+    missing,
+    failed,
+    ready: ids.length === 0 || (missing.length === 0 && deps.every(dep => dep.status === 'done')),
+  }
+}
+
+/**
+ * 把 waiting_dep 任务推进到 pending（依赖全 done）或 failed（依赖失败/丢失）；
+ * 循环到稳定，才能把失败沿依赖链传播下去。返回晋升/失败的任务 id。
+ */
+export function promoteDependents(db, { enqueue = () => {}, log = () => {} } = {}) {
+  const promoted = []
+  const failed = []
+  for (let pass = 0; pass < 20; pass += 1) {
+    const waiting = listTasks(db).filter(task => task.status === 'waiting_dep')
+    if (waiting.length === 0) break
+    let changed = false
+    for (const task of waiting) {
+      const state = dependencyState(db, task)
+      if (state.missing.length > 0) {
+        const reason = `前置任务不存在：${state.missing.map(item => item.id).join('、')}`
+        transition(db, task.id, 'failed', { error: reason })
+        failed.push(task.id)
+        changed = true
+        log('task.dep.failed', { taskId: task.id, detail: { reason } })
+        continue
+      }
+      if (state.failed.length > 0) {
+        const names = state.failed.map(dep => `「${taskLabelWithId(dep)}」（${labelOf(dep.status)}）`).join('、')
+        const reason = `前置任务未完成：${names}`
+        transition(db, task.id, 'failed', { error: reason })
+        failed.push(task.id)
+        changed = true
+        log('task.dep.failed', { taskId: task.id, detail: { reason } })
+        continue
+      }
+      if (!state.ready) continue
+      transition(db, task.id, 'pending')
+      enqueue(task.id)
+      promoted.push(task.id)
+      changed = true
+      log('task.dep.ready', { taskId: task.id, detail: { dependsOn: task.depends_on } })
+    }
+    if (!changed) break
+  }
+  return { promoted, failed }
+}
+
+/** 已就绪依赖的摘要块，派发时追加到 brief 后面（创建时依赖可能还没完成）。 */
+export function upstreamBrief(db, dependsOn) {
+  const ids = Array.isArray(dependsOn) ? dependsOn : []
+  if (ids.length === 0) return ''
+  const lines = ['【前置任务】']
+  for (const id of ids) {
+    const dep = getTask(db, id)
+    if (dep === undefined) {
+      lines.push(`- ${id}：不存在`)
+      continue
+    }
+    const report = recentMessages(db, id, 5).find(row => row.kind === 'report')
+    const summary = report === undefined
+      ? (dep.status === 'done' ? dep.goal : `（当前${labelOf(dep.status)}）`)
+      : String(report.rendered).replace(/^\[[^\]]+\]\s*/, '')
+    lines.push(`- 任务「${dep.title}」${dep.status === 'done' ? '已完成' : `当前${labelOf(dep.status)}`}：${short(summary)}`)
+    const artifacts = Array.isArray(dep.artifacts) ? dep.artifacts : []
+    if (artifacts.length > 0) {
+      lines.push(`  产物：${artifacts.slice(0, 8).map(item => item.path).join('、')}`)
+    }
+  }
+  let block = lines.join('\n')
+  if (block.length > 1600) block = `${block.slice(0, 1599)}…`
+  return block
+}

package/src/host-route.js

@@ -5,7 +5,7 @@ import { listTasks, listHistoryTasks } from './ledger.js'
 import { taskCard } from './card.js'
 
 const ENDPOINTS = new Set(['snapshot'])
-const ACTIVE = new Set(['pending', 'running', 'waiting_user', 'waiting_auth'])
+const ACTIVE = new Set(['waiting_dep', 'pending', 'running', 'waiting_user', 'waiting_auth'])
 
 const json = (value, status) => new Response(JSON.stringify(value), {
   status,
@@ -35,6 +35,10 @@ export function createHostRoute({ db, coordinatorStatus, openMain, staleMinutes
           targetDir: task.target_dir ?? null,
           readOnly: task.read_only === true,
           retryOf: task.retry_of ?? null,
+          groupId: task.group_id ?? null,
+          dependsOn: Array.isArray(task.depends_on) ? task.depends_on : [],
+          writeScopes: Array.isArray(task.write_scopes) ? task.write_scopes : [],
+          priority: task.priority ?? 0,
           artifacts: Array.isArray(task.artifacts) ? task.artifacts : [],
           queued: task.status === 'pending' && task.queued_at !== null && task.queued_at !== undefined,
           stale: ACTIVE.has(task.status) && at - task.last_event_at > staleMinutes * 60_000,

package/src/ledger.js

@@ -11,7 +11,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   status TEXT NOT NULL, session_id TEXT, target TEXT, target_dir TEXT, artifacts_json TEXT, coordinator_session TEXT NOT NULL,
   attempts INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
   last_event_at INTEGER NOT NULL, error TEXT, queued_at INTEGER, read_only INTEGER NOT NULL DEFAULT 0,
-  retry_of TEXT
+  retry_of TEXT, depends_json TEXT, group_id TEXT, write_scopes_json TEXT, priority INTEGER NOT NULL DEFAULT 0
 );
 CREATE TABLE IF NOT EXISTS messages (
   task_id TEXT NOT NULL, seq INTEGER NOT NULL, kind TEXT NOT NULL,
@@ -49,6 +49,10 @@ export async function openLedger(stateDir) {
     if (!taskColumns.includes('artifacts_json')) db.exec('ALTER TABLE tasks ADD COLUMN artifacts_json TEXT')
     if (!taskColumns.includes('read_only')) db.exec('ALTER TABLE tasks ADD COLUMN read_only INTEGER NOT NULL DEFAULT 0')
     if (!taskColumns.includes('retry_of')) db.exec('ALTER TABLE tasks ADD COLUMN retry_of TEXT')
+    if (!taskColumns.includes('depends_json')) db.exec('ALTER TABLE tasks ADD COLUMN depends_json TEXT')
+    if (!taskColumns.includes('group_id')) db.exec('ALTER TABLE tasks ADD COLUMN group_id TEXT')
+    if (!taskColumns.includes('write_scopes_json')) db.exec('ALTER TABLE tasks ADD COLUMN write_scopes_json TEXT')
+    if (!taskColumns.includes('priority')) db.exec('ALTER TABLE tasks ADD COLUMN priority INTEGER NOT NULL DEFAULT 0')
     return db
   } catch (error) {
     try { db?.close() } catch { /* 打不开的库不需要再抛关闭错误 */ }
@@ -74,19 +78,52 @@ const parseArtifacts = value => {
   }
 }
 
+const parseStringArray = value => {
+  if (value === null || value === undefined) return []
+  try {
+    const parsed = JSON.parse(value)
+    return Array.isArray(parsed) ? parsed.filter(item => typeof item === 'string' && item !== '') : []
+  } catch {
+    return []
+  }
+}
+
 const taskOf = row => row === undefined ? undefined : ({
   ...row,
   read_only: row.read_only === 1 || row.read_only === true,
   brief: JSON.parse(row.brief_json),
   artifacts: parseArtifacts(row.artifacts_json),
+  depends_on: parseStringArray(row.depends_json),
+  write_scopes: parseStringArray(row.write_scopes_json),
+  priority: Number.isFinite(row.priority) ? row.priority : 0,
 })
 
-export function createTask(db, { brief, coordinatorSession, targetDir, readOnly = false, retryOf = null }) {
+export function createTask(db, {
+  brief,
+  coordinatorSession,
+  targetDir,
+  readOnly = false,
+  retryOf = null,
+  dependsOn = [],
+  groupId = null,
+  writeScopes = [],
+  priority = 0,
+  status = 'pending',
+} = {}) {
   const now = Date.now()
   const id = `t-${randomUUID().slice(0, 8)}`
-  db.prepare(`INSERT INTO tasks (id, title, goal, brief_json, status, coordinator_session, target_dir, read_only, retry_of, created_at, updated_at, last_event_at)
-    VALUES (?, ?, ?, ?, 'pending', ?, ?, ?, ?, ?, ?, ?)`)
-    .run(id, String(brief.title), String(brief.goal), JSON.stringify(brief), String(coordinatorSession ?? ''), targetDir ?? null, readOnly === true ? 1 : 0, retryOf ?? null, now, now, now)
+  db.prepare(`INSERT INTO tasks
+    (id, title, goal, brief_json, status, coordinator_session, target_dir, read_only, retry_of,
+     depends_json, group_id, write_scopes_json, priority, created_at, updated_at, last_event_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+    .run(
+      id, String(brief.title), String(brief.goal), JSON.stringify(brief), status,
+      String(coordinatorSession ?? ''), targetDir ?? null, readOnly === true ? 1 : 0, retryOf ?? null,
+      JSON.stringify(Array.isArray(dependsOn) ? dependsOn : []), groupId ?? null,
+      JSON.stringify(Array.isArray(writeScopes) ? writeScopes : []),
+      Number.isFinite(priority) ? Math.trunc(priority) : 0,
+      now, now, now,
+    )
   return getTask(db, id)
 }
 
@@ -96,7 +133,7 @@ export function getTask(db, id) {
 
 export function listTasks(db, { active = false } = {}) {
   const sql = active
-    ? "SELECT * FROM tasks WHERE status IN ('pending','running','waiting_user','waiting_auth') ORDER BY created_at DESC, rowid DESC"
+    ? "SELECT * FROM tasks WHERE status IN ('waiting_dep','pending','running','waiting_user','waiting_auth') ORDER BY created_at DESC, rowid DESC"
     : 'SELECT * FROM tasks ORDER BY created_at DESC, rowid DESC'
   return db.prepare(sql).all().map(taskOf)
 }
@@ -104,7 +141,7 @@ export function listTasks(db, { active = false } = {}) {
 /** 终态历史：按创建时间倒序取最多 limit 条（面板快照用，避免把活跃任务挤掉）。 */
 export function listHistoryTasks(db, limit = 200) {
   return db.prepare(`SELECT * FROM tasks
-    WHERE status NOT IN ('pending','running','waiting_user','waiting_auth')
+    WHERE status NOT IN ('waiting_dep','pending','running','waiting_user','waiting_auth')
     ORDER BY created_at DESC, rowid DESC LIMIT ?`)
     .all(Math.max(0, Math.floor(limit))).map(taskOf)
 }
@@ -120,14 +157,17 @@ export function clearQueued(db, id) {
   return getTask(db, id)
 }
 
-/** 待派发队列：pending 且还没有子会话，按创建顺序。 */
+/** 待派发队列：pending 且还没有子会话，按优先级降序、创建顺序升序。 */
 export function listPendingQueue(db) {
-  return db.prepare("SELECT * FROM tasks WHERE status = 'pending' AND session_id IS NULL ORDER BY created_at ASC, rowid ASC")
+  return db.prepare(`SELECT * FROM tasks
+    WHERE status = 'pending' AND session_id IS NULL
+    ORDER BY priority DESC, created_at ASC, rowid ASC`)
     .all().map(taskOf)
 }
 
+/** 队列安全阀口径：等待依赖的任务也算占位，避免等待中的图无限膨胀。 */
 export function countPending(db) {
-  return db.prepare("SELECT count(*) AS n FROM tasks WHERE status = 'pending'").get().n
+  return db.prepare("SELECT count(*) AS n FROM tasks WHERE status IN ('pending','waiting_dep')").get().n
 }
 
 /** 任务的渲染文本（派发时用），取第一条 brief 消息。 */

package/src/queue.js

@@ -3,6 +3,7 @@
 import {
   briefText, clearQueued, countPending, getTask, listPendingQueue, listTasks, markQueued, transition,
 } from './ledger.js'
+import { promoteDependents, upstreamBrief } from './deps.js'
 import { taskLabel } from './task-label.js'
 
 export function createQueue({ db, dispatcher, config = {}, logger, notifier, retryDelaysMs = [2000, 5000, 10000, 30000] }) {
@@ -22,7 +23,16 @@ export function createQueue({ db, dispatcher, config = {}, logger, notifier, ret
     return index === -1 ? 0 : index + 1
   }
   const enqueue = id => {
-    if (!ids.includes(id)) ids.push(id)
+    if (ids.includes(id)) return
+    ids.push(id)
+    // 优先级高的先派；同优先级按创建时间 FIFO（JS sort 稳定，等值时保留入队顺序）。
+    ids.sort((left, right) => {
+      const a = getTask(db, left)
+      const b = getTask(db, right)
+      const priorityDelta = (b?.priority ?? 0) - (a?.priority ?? 0)
+      if (priorityDelta !== 0) return priorityDelta
+      return (a?.created_at ?? 0) - (b?.created_at ?? 0)
+    })
   }
   const remove = id => {
     const index = ids.indexOf(id)
@@ -40,6 +50,10 @@ export function createQueue({ db, dispatcher, config = {}, logger, notifier, ret
 
   async function pump() {
     if (stopped) return
+    // 先把依赖已完成的 waiting_dep 晋升为 pending；晋升动作只会发生在等待中的任务上。
+    try { promoteDependents(db, { enqueue, log }) } catch (error) {
+      log('task.dep.promote-failed', { detail: { error: error?.message ?? String(error) } })
+    }
     // 单锁：已有 pump 在跑时，新调用等同一个 promise，避免并发 create 各自提前返回导致漏派。
     if (pumpPromise !== null) return pumpPromise
     pumpPromise = runPump().finally(() => { pumpPromise = null })
@@ -56,7 +70,9 @@ export function createQueue({ db, dispatcher, config = {}, logger, notifier, ret
           ids.shift()
           continue
         }
-        const rendered = briefText(db, id) ?? `【任务】${task.title}\n目标：${task.goal}`
+        const rendered = [briefText(db, id) ?? `【任务】${task.title}\n目标：${task.goal}`, upstreamBrief(db, task.depends_on)]
+          .filter(text => typeof text === 'string' && text !== '')
+          .join('\n')
         let member
         try {
           member = await dispatcher.spawn({
@@ -111,6 +127,8 @@ export function createQueue({ db, dispatcher, config = {}, logger, notifier, ret
             summary: message,
             system: true,
           })
+          // 失败沿依赖链传播：下游 waiting_dep 立即失败，不再假装在等。
+          try { promoteDependents(db, { enqueue, log }) } catch { /* 传播失败只影响下游，不打断队列 */ }
           continue
         }
 

package/src/state.js

@@ -1,8 +1,9 @@
 // 任务状态机。只有子会话的回报能推进 running 之后的状态；
 // 协调者只能创建、续派、停止、重派。
-export const STATUSES = ['pending', 'running', 'waiting_user', 'waiting_auth', 'done', 'failed', 'cancelled', 'orphaned']
+export const STATUSES = ['waiting_dep', 'pending', 'running', 'waiting_user', 'waiting_auth', 'done', 'failed', 'cancelled', 'orphaned']
 
 const TRANSITIONS = {
+  waiting_dep: ['pending', 'failed', 'cancelled'],
   pending: ['running', 'failed', 'cancelled'],
   running: ['waiting_user', 'waiting_auth', 'done', 'failed', 'cancelled', 'orphaned'],
   waiting_user: ['running', 'cancelled', 'failed', 'orphaned'],

package/src/tools.js

@@ -5,6 +5,7 @@ import { validateBrief, renderBrief, validateTargetDir } from './brief.js'
 import { inferWorkspaceTarget } from './workspace-match.js'
 import { taskLabel, taskLabelWithId } from './task-label.js'
 import { canTransition } from './state.js'
+import { dependencyState, promoteDependents, validateDepends } from './deps.js'
 import {
   GLOBAL_PROJECT, addMemory, buildMemoryBlock, memoryTokens, projectKeyOf, remember, searchMemories,
 } from './memory.js'
@@ -25,10 +26,10 @@ const REPORT_STATUS = ['progress', 'done', 'blocked', 'needs_auth']
 const MAX_ARTIFACTS = 20
 const MAX_ARTIFACT_LABEL = 160
 const STATUS_LABEL = {
-  pending: '待派发', running: '进行中', waiting_user: '等你确认', waiting_auth: '要授权',
+  waiting_dep: '等前置', pending: '待派发', running: '进行中', waiting_user: '等你确认', waiting_auth: '要授权',
   done: '已完成', failed: '失败', cancelled: '已取消', orphaned: '会话丢失',
 }
-const ACTIVE_STATUS = new Set(['pending', 'running', 'waiting_user', 'waiting_auth'])
+const ACTIVE_STATUS = new Set(['waiting_dep', 'pending', 'running', 'waiting_user', 'waiting_auth'])
 const WAITING_STATUS = new Set(['waiting_user', 'waiting_auth'])
 const RESUME_STATUS = new Set(['waiting_user', 'waiting_auth', 'failed'])
 const TERMINAL_STATUS = new Set(['done', 'cancelled', 'orphaned'])
@@ -45,6 +46,10 @@ function taskLine(db, task, { staleMinutes = 30 } = {}) {
     `- ${taskLabelWithId(task)}`, task.read_only ? `${labelOf(task.status)}·只读` : labelOf(task.status), `子会话 ${task.target ?? '-'}`,
     `目标：${short(task.goal)}`,
   ]
+  if (task.status === 'waiting_dep') {
+    parts.push(`等前置 ${task.depends_on.length} 个${task.priority ? `｜P${task.priority}` : ''}`)
+  }
+  if (task.group_id) parts.push(`组 ${task.group_id}`)
   const latest = recentMessages(db, task.id, 1)[0]
   parts.push(`最近：${latest === undefined ? '-' : short(latest.rendered)}`)
   if (task.status === 'pending' && task.session_id === null) {
@@ -85,7 +90,47 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
     return undefined
   }
 
-  // 无 target 时相对产物按主会话目录解析（defaultCwd 可以是 getter，主会话重建后跟新目录）。
+  // 分组 / 写域 / 优先级：都只做轻量归一，非法值忽略。
+  const normalizeGroup = value => {
+    if (typeof value !== 'string') return null
+    const text = value.trim()
+    return text === '' ? null : text.slice(0, 80)
+  }
+  const normalizeScopes = value => {
+    if (!Array.isArray(value)) return []
+    const out = []
+    for (const item of value) {
+      if (typeof item !== 'string') continue
+      const text = item.trim().replace(/\\/g, '/').replace(/\/+$/, '')
+      if (text === '' || out.includes(text)) continue
+      out.push(text.slice(0, 200))
+      if (out.length >= 20) break
+    }
+    return out
+  }
+  const normalizePriority = value => {
+    if (!Number.isFinite(value)) return 0
+    return Math.max(-10, Math.min(10, Math.trunc(value)))
+  }
+  const sameScope = (left, right) => left === right
+    || left.startsWith(`${right}/`)
+    || right.startsWith(`${left}/`)
+  const writeScopeConflicts = (scopes, excludeId) => {
+    if (scopes.length === 0) return []
+    const conflicts = []
+    for (const task of listTasks(db, { active: true })) {
+      if (task.id === excludeId) continue
+      const other = Array.isArray(task.write_scopes) ? task.write_scopes : []
+      const overlap = scopes.find(scope => other.some(candidate => sameScope(scope, candidate)))
+      if (overlap !== undefined) conflicts.push({ task, scope: overlap })
+      if (conflicts.length >= 5) break
+    }
+    return conflicts
+  }
+  const conflictsText = conflicts => conflicts.length === 0 ? ''
+    : `写域与活跃任务冲突：${conflicts.map(({ task, scope }) => `${taskLabelWithId(task)}（${scope}）`).join('、')}；建议拆分或串行。`
+
+
   const baseDirOf = task => {
     if (typeof task?.target_dir === 'string' && task.target_dir !== '') return task.target_dir
     let fallback
@@ -276,6 +321,10 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
       user_verbatim: str('用户原话，可空'),
       target: str('目标目录：可空；给了必须是已存在的绝对路径，子会话在该目录运行'),
       readOnly: { type: 'boolean', description: '只读任务：子会话沙箱 read-only（读正常，写文件/写 shell 被拒）；默认 false，只在明确需要时传 true' },
+      dependsOn: strList('前置任务编号数组；依赖全部完成后才派发；任一前置失败则本任务失败'),
+      group: str('可选分组名，如“登录改造”；面板按组汇总进度'),
+      writeScopes: strList('可选写域（目录/文件路径）；与活跃任务重叠时给冲突提示（advisory）'),
+      priority: { type: 'number', description: '优先级，-10..10，默认 0；高的先派发' },
     }), async (args, exec) => {
       const denied = requireMain(exec)
       if (denied !== undefined) return denied
@@ -321,6 +370,17 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
       // 去重、队列容量、创建必须在同一个同步段里，中间不能再 await，否则并发调用会一起通过检查。
       const title = String(args.title).trim()
       const goal = String(args.goal).trim()
+      const depends = validateDepends(db, args.dependsOn)
+      if (depends.ok === false) {
+        log('task.create.rejected', { agentId, detail: { reason: 'depends', message: depends.error, callId } })
+        return `依赖不合法：${depends.error}。`
+      }
+      const groupId = normalizeGroup(args.group)
+      const writeScopes = normalizeScopes(args.writeScopes)
+      const priority = normalizePriority(args.priority)
+      const depState = dependencyState(db, { depends_on: depends.ids })
+      const initialStatus = depState.ready ? 'pending' : 'waiting_dep'
+      const conflicts = writeScopeConflicts(writeScopes)
       const duplicate = listTasks(db, { active: true })
         .find(task => task.title.trim() === title && task.goal.trim() === goal)
       if (duplicate !== undefined) {
@@ -339,8 +399,33 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
         })
         return `待派发队列已满（${maxQueue} 个），先 task_stop 或等队列消化后再派。`
       }
-      const task = createTask(db, { brief, coordinatorSession: current.id ?? coordinatorSession, targetDir: effectiveTarget, readOnly })
-      log('task.create.created', { taskId: task.id, agentId, sessionId: current.id, detail: { title, callId, targetDir: effectiveTarget ?? null, readOnly } })
+      const task = createTask(db, {
+        brief,
+        coordinatorSession: current.id ?? coordinatorSession,
+        targetDir: effectiveTarget,
+        readOnly,
+        dependsOn: depends.ids,
+        groupId,
+        writeScopes,
+        priority,
+        status: initialStatus,
+      })
+      log('task.create.created', {
+        taskId: task.id,
+        agentId,
+        sessionId: current.id,
+        detail: {
+          title,
+          callId,
+          targetDir: effectiveTarget ?? null,
+          readOnly,
+          dependsOn: depends.ids,
+          group: groupId,
+          writeScopes,
+          priority,
+          status: initialStatus,
+        },
+      })
       let memoryBlock = ''
       if (config?.memoryInject !== false) {
         try {
@@ -353,6 +438,12 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
       }
       const rendered = `【任务编号】${task.id}\n${renderBrief(brief)}${memoryBlock === '' ? '' : `\n${memoryBlock}`}`
       addMessage(db, task.id, { kind: 'brief', rendered })
+      const conflictNote = conflictsText(conflicts)
+      const depNames = depends.ids.map(id => {
+        const dep = getTask(db, id)
+        return dep === undefined ? id : `「${dep.title}」（${labelOf(dep.status)}）`
+      }).join('、')
+      const dependencyNote = depends.ids.length === 0 ? '' : `前置任务：${depNames}`
       // 配置的协调者会话失效时直接失败：挂进队列只会永远派不出去。
       if (current.live === false) {
         const message = invalidHint() === '' ? '协调者会话已失效' : invalidHint()
@@ -360,10 +451,15 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
         transition(db, task.id, 'failed', { error: message })
         throw new Error(message)
       }
+      if (initialStatus === 'waiting_dep') {
+        const notes = [dependencyNote, conflictNote].filter(Boolean).join('\n')
+        log('task.dep.waiting', { taskId: task.id, detail: { dependsOn: depends.ids, callId } })
+        return `任务「${taskLabelWithId(task)}」已创建，等待前置任务完成。${notes === '' ? '' : `\n${notes}`}`
+      }
       const outcome = await queue.enqueueAndPump(task.id)
       const resultTask = outcome.task
       const inferredNote = inferred === undefined ? '' : `（目标目录按工作区推断：${inferred.path}）`
-      const notes = [invalidHint(), inferredNote].filter(Boolean).join('\n')
+      const notes = [invalidHint(), inferredNote, conflictNote, dependencyNote].filter(Boolean).join('\n')
       if (resultTask?.status === 'failed') throw new Error(resultTask.error ?? '子会话创建失败')
       if (resultTask?.status === 'running') {
         return `任务「${taskLabelWithId(task)}」已派发，子会话 ${resultTask.target}。${notes === '' ? '' : `\n${notes}`}`
@@ -372,14 +468,23 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
       return `任务「${taskLabelWithId(task)}」已创建，前面还有 ${ahead} 个任务在排队，轮到时自动派发。${notes === '' ? '' : `\n${notes}`}`
     }),
 
-    wrap('task_list', '列出任务。默认只列活跃任务（pending/running/waiting），active=false 时连同历史一起列出。', objectSchema({
+    wrap('task_list', '列出任务。默认只列活跃任务（waiting_dep/pending/running/waiting），active=false 时连同历史一起列出；可按 group 过滤并看组进度。', objectSchema({
       active: { type: 'boolean', description: '是否只看活跃任务，默认 true' },
+      group: str('可选：只看这个分组的任务'),
     }), async (args, exec) => {
       const denied = requireMain(exec)
       if (denied !== undefined) return denied
-      const tasks = listTasks(db, { active: args.active !== false })
-      if (tasks.length === 0) return args.active === false ? '台账里还没有任何任务。' : '没有活跃任务。'
-      return tasks.map(task => taskLine(db, task, { staleMinutes })).join('\n')
+      const all = listTasks(db, { active: args.active !== false })
+      const group = typeof args.group === 'string' ? args.group.trim() : ''
+      const tasks = group === '' ? all : all.filter(task => task.group_id === group)
+      if (tasks.length === 0) {
+        if (group !== '') return `组「${group}」里没有任务。`
+        return args.active === false ? '台账里还没有任何任务。' : '没有活跃任务。'
+      }
+      const header = group === ''
+        ? ''
+        : `组「${group}」：${tasks.filter(task => task.status === 'done').length}/${tasks.length} 完成\n`
+      return header + tasks.map(task => taskLine(db, task, { staleMinutes })).join('\n')
     }),
 
     wrap('task_status', '查看一个任务的详情与最近消息。', objectSchema({ task_id: str('任务编号，如 t-1a2b3c4d') }), async (args, exec) => {
@@ -393,12 +498,27 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
         `任务「${taskLabelWithId(task)}」`,
         `状态：${labelOf(task.status)}`,
         ...(task.read_only ? ['权限：只读（读正常，写文件/写 shell 被拒绝）'] : []),
+        ...(task.group_id ? [`分组：${task.group_id}`] : []),
+        ...(task.priority !== 0 ? [`优先级：${task.priority}`] : []),
         `子会话：${task.target ?? '-'}`,
+        ...(task.status === 'waiting_dep'
+          ? [`等待前置：${task.depends_on.map(id => {
+            const dep = getTask(db, id)
+            return dep === undefined ? id : `${id}（${labelOf(dep.status)}）`
+          }).join('、')}`]
+          : []),
         ...(task.status === 'pending'
           ? [`排队：${task.queued_at === null || task.queued_at === undefined ? '待派发（刚创建）' : '排队中（等待并发槽位）'}`]
           : []),
         `目标：${task.goal}`,
       ]
+      if (task.depends_on.length > 0 && task.status !== 'waiting_dep') {
+        lines.push(`前置任务：${task.depends_on.map(id => {
+          const dep = getTask(db, id)
+          return dep === undefined ? id : `「${dep.title}」（${labelOf(dep.status)}）`
+        }).join('、')}`)
+      }
+      if (task.write_scopes.length > 0) lines.push(`写域：${task.write_scopes.join('、')}`)
       if (task.retry_of) lines.push(`重派自：${task.retry_of}`)
       if (task.error !== null && task.error !== undefined) lines.push(`原因：${task.error}`)
       if (config?.backend !== 'team' && task.session_id !== null && task.session_id !== undefined) {
@@ -418,6 +538,9 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
       const task = getTask(db, args.task_id ?? '')
       if (task === undefined) return `没有任务 ${args.task_id ?? ''}。`
       if (TERMINAL_STATUS.has(task.status)) return `任务「${labelFor(task)}」已结束（${labelOf(task.status)}），不能续派；需要新工作请 task_create。`
+      if (task.status === 'waiting_dep') {
+        return `任务「${labelFor(task)}」还在等待前置任务（${task.depends_on.join('、')}），依赖完成后会派发，暂不能续派；要取消用 task_stop。`
+      }
       if (task.status === 'pending' && (task.target === null || task.target === undefined)) {
         return task.queued_at === null || task.queued_at === undefined
           ? `任务「${labelFor(task)}」还没有子会话，先停止再重建。`
@@ -462,11 +585,14 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
       const task = getTask(db, args.task_id ?? '')
       if (task === undefined) return `没有任务 ${args.task_id ?? ''}。`
       if (TERMINAL_STATUS.has(task.status)) return `任务「${labelFor(task)}」已结束（${labelOf(task.status)}），无需停止。`
-      if (task.status === 'pending') {
+      if (task.status === 'pending' || task.status === 'waiting_dep') {
         queue.remove(task.id)
         transition(db, task.id, 'cancelled')
         releaseTaskSession(task)
-        return `任务「${labelFor(task)}」已取消（还在排队，没有派发出去）。`
+        queue.pump()
+        return task.status === 'waiting_dep'
+          ? `任务「${labelFor(task)}」已取消（还在等待前置任务）。`
+          : `任务「${labelFor(task)}」已取消（还在排队，没有派发出去）。`
       }
       if (task.target !== null && task.target !== undefined) {
         // 停止失败也要把任务标掉：用户要的是「停」，不是让 stop 抛错卡住。
@@ -500,14 +626,26 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
         return `已存在活跃任务「${taskLabelWithId(duplicate)}」（${labelOf(duplicate.status)}），未重复重派。`
       }
       const current = status()
+      const depends = validateDepends(db, task.depends_on)
+      if (depends.ok === false) return `不能重派：${depends.error}。`
+      const depState = dependencyState(db, { depends_on: depends.ids })
       const retried = createTask(db, {
         brief: task.brief,
         coordinatorSession: current.id ?? coordinatorSession,
         targetDir: task.target_dir,
         readOnly: task.read_only === true,
         retryOf: task.id,
+        dependsOn: depends.ids,
+        groupId: task.group_id,
+        writeScopes: task.write_scopes,
+        priority: task.priority,
+        status: depState.ready ? 'pending' : 'waiting_dep',
+      })
+      log('task.retry', {
+        taskId: retried.id,
+        sessionId: current.id,
+        detail: { retryOf: task.id, dependsOn: depends.ids, status: retried.status, callId: exec?.callId },
       })
-      log('task.retry', { taskId: retried.id, sessionId: current.id, detail: { retryOf: task.id, callId: exec?.callId } })
       addMessage(db, retried.id, { kind: 'brief', rendered: `【任务编号】${retried.id}\n${renderBrief(task.brief)}` })
       if (current.live === false) {
         const message = invalidHint() === '' ? '协调者会话已失效' : invalidHint()
@@ -515,6 +653,9 @@ export function createTools({ db, dispatcher, queue, notifier, config, coordinat
         transition(db, retried.id, 'failed', { error: message })
         throw new Error(message)
       }
+      if (retried.status === 'waiting_dep') {
+        return `任务「${labelFor(task)}」已重派为「${taskLabelWithId(retried)}」，等待前置任务完成后派发。`
+      }
       const outcome = await queue.enqueueAndPump(retried.id)
       const resultTask = outcome.task
       if (resultTask?.status === 'failed') throw new Error(resultTask.error ?? '子会话创建失败')