dsh-lead-mode 0.1.6 → 0.2.0

package/cordis.patch.yml

@@ -51,6 +51,7 @@
 
                 - 派活自包含。teammate 看不到你的上下文，把目标、约束、验收标准、已知失败、绝对路径都写进 prompt。
                 - 要求它收尾那条消息写清交付物。它收工时那条消息会随通知回到你手上。
+                - 派活时要求它第一步建工作日志（.scratch/<effort>/worklog-<mate>.md），收尾前补完最后一轮。
                 - 写作用域不重叠。一人一块文件。分不开的活排成依赖。
                 - 共享任务走 list、get、claim（带 revision）、干、complete。task 只是账本，不是唤醒通道。
                 - 等活就结束回合等通知：teammate 收工、或给你发消息，都会唤醒你。task 变更只唤醒正在 wait_agent 的调用方，不会唤醒空闲的你。

package/lib/index.js

@@ -1,8 +1,9 @@
 /**
  * dsh-lead-mode host half.
  *
- * Three jobs: register the `lead-mode` runtime skill, register the `/lead-mode`
- * slash command, and warn at startup when the Team runtime is absent.
+ * Three jobs: register every bundled runtime skill (`skills/<name>/SKILL.md`,
+ * discovered at apply time), register the `/lead-mode` slash command, and warn
+ * at startup when the Team runtime is absent.
  *
  * The plugin declares no `inject` of its own. Each surface waits for its own
  * service through `ctx.inject()`, so a host missing `dsh-skill` still mounts the
@@ -12,7 +13,8 @@
  *
  * @module dsh-lead-mode
  */
-import { readFileSync } from 'node:fs'
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 /** Cordis plugin name. */
@@ -27,11 +29,8 @@ const ENABLE_COMMAND = `dsh plugin --profile <你的 profile 名> add ${TEAM_PRO
 /** Why the version pin matters, repeated wherever the command appears. */
 const VERSION_NOTE = '不带版本号会装到 0.1.5-alpha.2，和 0.2.1 宿主对不上。'
 
-/** Absolute path of the bundled skill body. */
-const SKILL_URL = new URL('../skills/lead-mode/SKILL.md', import.meta.url)
-
-/** Skill name shared by the file on disk, the runtime registration, and the naming manifest. */
-const SKILL_NAME = 'lead-mode'
+/** Directory holding one subdirectory per bundled skill; the directory name is the skill name. */
+const SKILLS_DIR = new URL('../skills/', import.meta.url)
 
 /** Command name shared by the registration and the naming manifest. */
 const COMMAND_NAME = 'lead-mode'
@@ -40,25 +39,104 @@ const COMMAND_NAME = 'lead-mode'
 const PRESET_ID = 'lead-mode'
 
 /**
- * Read the bundled skill file and split off its YAML frontmatter.
+ * Read one bundled skill and split off its YAML frontmatter.
  *
  * The runtime skill registry wants `description` as its own field, so the body
  * handed to it must not repeat the frontmatter block. Reading synchronously
- * keeps `apply` synchronous; the file is a few kilobytes shipped inside this
+ * keeps `apply` synchronous; each file is a few kilobytes shipped inside this
  * package, so there is no I/O worth deferring.
  *
- * @returns the frontmatter description and the markdown body.
+ * A skill directory whose file is unreadable, has no frontmatter, declares no
+ * `name`, mismatches its directory name, declares no `description`, or has an
+ * empty body is reported through `warn` and dropped. One broken skill must not
+ * take the whole injection down with it.
+ *
+ * @param skillsRoot - absolute path of the `skills/` directory.
+ * @param dirName - the skill directory name, which is also the expected skill name.
+ * @param warn - receives one Chinese diagnostic per skipped skill.
+ * @returns the registry payload, or `undefined` when this skill was skipped.
  */
-function readBundledSkill() {
-  const path = fileURLToPath(SKILL_URL)
-  const raw = readFileSync(path, 'utf8')
+function readBundledSkill(skillsRoot, dirName, warn) {
+  const path = join(skillsRoot, dirName, 'SKILL.md')
+  let raw
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (error) {
+    warn(`[lead-mode] 读不到 ${path}，${dirName} 这个 skill 跳过：${String(error)}`)
+    return undefined
+  }
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
-  if (match === null) throw new Error(`${path} has no YAML frontmatter`)
-  const description = /^description:\s*(.+)$/m.exec(match[1])
-  if (description === null) throw new Error(`${path} frontmatter has no description`)
+  if (match === null) {
+    warn(`[lead-mode] ${path} 没有 YAML frontmatter，${dirName} 这个 skill 跳过`)
+    return undefined
+  }
+  const declared = /^name:\s*(.+)$/m.exec(match[1])?.[1]?.trim()
+  if (declared !== dirName) {
+    warn(`[lead-mode] ${path} 的 frontmatter name 是「${declared ?? '缺'}」，与目录名「${dirName}」不一致，跳过这一个`)
+    return undefined
+  }
+  const description = /^description:\s*(.+)$/m.exec(match[1])?.[1]?.trim()
+  if (description === undefined) {
+    warn(`[lead-mode] ${path} 的 frontmatter 没有 description，${dirName} 这个 skill 跳过`)
+    return undefined
+  }
   const content = raw.slice(match[0].length).trim()
-  if (content.length === 0) throw new Error(`${path} has an empty body`)
-  return { description: description[1].trim(), content, path }
+  if (content.length === 0) {
+    warn(`[lead-mode] ${path} 正文是空的，${dirName} 这个 skill 跳过`)
+    return undefined
+  }
+  return {
+    name: declared,
+    description,
+    content,
+    // `source` is required by the registry's load-time validation but is NOT
+    // defaulted by `register()`: `validateRuntimeSkill` (register) checks only
+    // name, description and invocation, while `validateDefinition` (load)
+    // throws unless `source` is a string. Omitting it registers fine and then
+    // fails every `skill` tool call with `source must be a string`.
+    source: `dsh-lead-mode/skills/${declared}/SKILL.md`,
+    path,
+    invocation: { modelInvocable: true, userInvocable: true },
+  }
+}
+
+/**
+ * Scan `skillsRoot` and register every valid bundled skill.
+ *
+ * Directory order is sorted so the registration order is stable across hosts.
+ * A missing or unreadable root, an unreadable skill file, and a registry that
+ * throws on one skill all degrade to a warning instead of failing the callback.
+ *
+ * @param skillsRoot - absolute path of the `skills/` directory.
+ * @param registry - the `skills` service (`register(definition)`).
+ * @param warn - receives one Chinese diagnostic per skipped skill.
+ * @returns the names that were registered, in registration order.
+ */
+export function syncBundledSkills(skillsRoot, registry, warn) {
+  let entries
+  try {
+    entries = readdirSync(skillsRoot, { withFileTypes: true })
+  } catch (error) {
+    warn(`[lead-mode] 扫描 ${skillsRoot} 失败，本插件的 skill 都没注册：${String(error)}`)
+    return []
+  }
+  const dirNames = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+  const registered = []
+  for (const dirName of dirNames) {
+    const skill = readBundledSkill(skillsRoot, dirName, warn)
+    if (skill === undefined) continue
+    try {
+      registry.register(skill)
+    } catch (error) {
+      warn(`[lead-mode] 注册 skill ${skill.name} 失败：${String(error)}`)
+      continue
+    }
+    registered.push(skill.name)
+  }
+  return registered
 }
 
 /**
@@ -155,26 +233,7 @@ export function apply(ctx) {
   const warn = (message) => ctx.logger.warn(message)
 
   ctx.inject(['skills'], (skillsCtx) => {
-    let skill
-    try {
-      skill = readBundledSkill()
-    } catch (error) {
-      warn(`[lead-mode] 读不到 skills/lead-mode/SKILL.md，lead-mode skill 没注册：${String(error)}`)
-      return
-    }
-    skillsCtx.skills.register({
-      name: SKILL_NAME,
-      description: skill.description,
-      content: skill.content,
-      // `source` is required by the registry's load-time validation but is NOT
-      // defaulted by `register()`: `validateRuntimeSkill` (register) checks only
-      // name, description and invocation, while `validateDefinition` (load)
-      // throws unless `source` is a string. Omitting it registers fine and then
-      // fails every `skill` tool call with `source must be a string`.
-      source: 'dsh-lead-mode/skills/lead-mode/SKILL.md',
-      path: skill.path,
-      invocation: { modelInvocable: true, userInvocable: true },
-    })
+    syncBundledSkills(fileURLToPath(SKILLS_DIR), skillsCtx.skills, warn)
   })
 
   ctx.inject(['commands'], (commandsCtx) => {
@@ -186,7 +245,7 @@ export function apply(ctx) {
   })
 
   if (ctx.get('skills') === undefined) {
-    warn('[lead-mode] skills 服务不在，lead-mode skill 暂时没注册。它会等 dsh-skill 挂载后再注册；一直不出现就检查 dsh-skill 是否装好。')
+    warn('[lead-mode] skills 服务不在，本插件的 skill 暂时都没注册。它会等 dsh-skill 挂载后再注册；一直不出现就检查 dsh-skill 是否装好。')
   }
   if (ctx.get('commands') === undefined) {
     warn('[lead-mode] commands 服务不在，/lead-mode 命令暂时没注册。它会等 dsh-commands 挂载后再注册。')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-lead-mode",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Lead mode for DSH: an agent preset, a working-method skill, a dependency self-check, and two reminders that tell you to enable the official Agent Teams. | 给 DSH 加 Lead 模式：预设、skill、依赖自检、两条前置提醒。",
   "type": "module",
   "main": "lib/index.js",

package/skills/lead-mode/SKILL.md

@@ -99,12 +99,74 @@ teammate 收工时，它**最后那条消息**会随通知回到你手上，格
 
 需要**中途**进度（干到一半问一句、或者要它先确认再继续）时，才另外要求它 `send_message` 给你。
 
+还有一条硬要求，写进每张单里：开建工作日志是成员的第一件事，收尾前补完最后一轮。它是你的账本，成员被 `interrupt_agent` 打断也不丢账。格式见下面的「上下文变长怎么办」那节。
+
 ### 收尾消息可能被省掉
 
 如果 teammate 在收工前刚给你发过 `send_message`，通知里不会重复它的收尾正文，而是写「It sent you a message just before finishing, so its closing message is omitted.」。
 
 也就是说：你要么拿到收尾消息，要么拿到它发的那条，不会两个都没。
 
+## 上下文变长怎么办：压缩、复用、交接、换人
+
+### 为什么会丢
+
+宿主对每个 agent 都自动压缩会话。压力到阈值就触发，会话 id 不变，早期节点被一条摘要替换。这就是**上下文降级**：细节只剩摘要，不再完整可见。
+
+团队层没有关掉压缩的开关。Lead 也没有「压缩指定成员会话」的通道，只能等它自己触发。
+
+成员活干长了，前面的细节会变薄。你不查，就当它还记得。
+
+### 怎么检测
+
+查这个成员的会话被压缩过几次：
+
+1. `list_agents` 取成员的 `id`。
+2. `session_event_search`，`session_id` 填那个 id，`event_types: ["compaction/start"]`，`surfaces: ["log-only"]`。
+3. 命中 ≥1 次，就是该成员已被压缩，细节开始丢。
+
+不要在 `wait_agent` 里套这个检查，也不要反复轮询。一次派活、验收之前查一次就够。
+
+阈值不写死。各宿主不一样，写死会过期，你只需要知道怎么查。
+
+### 交接阶梯
+
+按代价从低到高排，能不换人就不换人。
+
+1. 继续跑：命中 0–1 次、活快收尾，交给自动压缩兜住。
+2. 重发窄单：用 `send_message` 给同一个成员一张更窄的单，只做剩下的部分。成员常驻，别急着换人。
+3. 写交接文档：要求它先补完工作日志，再写 handoff，然后 `interrupt_agent`。
+4. 换新成员：`spawn_teammate`，`context` 用 `fresh`。原因写死：`fork` 拷的是你 Lead 自己的历史，不是上一个成员的历史，所以拿不到前任的细节。
+
+### 工作日志与交接文档放哪
+
+位置固定在 `.scratch/<effort>/`。一人一个 `worklog-<mate>.md`，换人时写 `handoff-<mate>-<n>.md`。
+
+`.scratch` 存在就用（通常是 `obsidian-docs/scratch/` 的软链，笔记库能看见，不进 git）；不存在就先建目录，别假设它一定有。
+
+工作日志（worklog）分两段：
+
+| 段 | 写什么 |
+|---|---|
+| 状态摘要（头部，一屏内） | 任务 id 与标题、所属成员、写作用域、验收判据、当前状态 |
+| 轮次记录（下面，只追加） | 一轮一条：做了什么、改了哪些文件、下一步、踩到的坑 |
+
+交接文档（handoff）六块，全部用指针，不复制正文：
+
+1. 接手关系：谁交给谁、交接原因、时间。
+2. 任务与账本：task id、revision、owner、验收判据。
+3. 文件账：已改、未改、只读过，全部绝对路径，加工作日志指针。
+4. 验收：能复跑的命令，加最近一次输出摘要。
+5. 死路与决策：试过什么不行、为什么选现在这条。
+6. 下一步：接手第一件事、明确不做什么。
+
+### 换人操作清单
+
+- 先查名额：`/lead-mode` 报 `maxMembers`。换一次吃一个名额，创建失败的也占位，名字永不复用。
+- 旧 task 你先 `team_task_update` 执行 `release`，续作成员再 `claim`。revision 会变。
+- 续作成员名字加 `-r2` 后缀，与被接手的成员并存，不要复用旧名字。
+- `interrupt_agent` 不清空它排队的消息，打断前确认工作日志已写完。
+
 ## 写作用域不重叠
 
 两个 teammate 同时改一个文件，改动会互相覆盖，而且谁都发现不了。
@@ -181,6 +243,10 @@ teammate 继承你（Lead）在 spawn 那一刻的 provider 和 model。想换
 
 派活时可以直接告诉用户去这儿看进度，比自己复述一遍更清楚。
 
+## 收尾要写团队汇总
+
+本 effort 有 2 个以上成员或跨 2 轮以上时，收尾要写一份团队汇总。加载 `team-digest` skill：触发阈值、落盘路径、六块骨架、原料取法都在那里，这里不展开格式。
+
 ## 给最终答复前
 
 - 必需的 teammate 都等齐了再答。没等齐就说「还在跑」，别把半成品当结论。

package/skills/team-digest/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: team-digest
+description: 收尾、结项、写报告时用的团队汇总。把多个成员的产出合并成一份 markdown，本 effort 有 2 个以上成员或跨 2 轮以上才写。
+---
+
+# 团队汇总
+
+成员各交一段收尾消息，各写一份工作日志。收尾时没人合并，用户得自己翻 N 条通知，过一周想回看还得重新调查一遍。这份 skill 产出那份合并物。
+
+主要用途是日后回看。当场看懂是它的副产物，不要为了「当场好看」多写。
+
+## 什么时候写
+
+给最终答复之前判断，满足一条就写：
+
+| 条件 | 说明 |
+|---|---|
+| 本 effort 有 2 个以上成员 | 一人一段就要合并，否则用户得自己拼 |
+| 跨 2 轮以上 | 同一成员多轮、或换过续作成员，过程散在多轮里 |
+
+不写的情况：只有一个成员一轮干完、只查了资料没改动、纯问答。别为一次调用产出一份报告。
+
+## 写到哪
+
+`reports/<YYYY-MM-DD>-<effort>.md`，相对仓库根，单一路径。
+
+- `<effort>` 用 `.scratch/` 下那个目录名，和工作日志同源，别另起一套命名。
+- 不新增目录层级，不加 `-v2`、`-final` 这类后缀。
+- 同一 effort 同一天只写一份。收尾时一次成型，不追加、不做增量、不设「晋升」步骤。
+- 想进笔记库，自己给 `reports` 建软链，不要改路径。
+- 目录不存在就建。建不了（只读挂载等）就在最终答复里说清楚，别悄悄丢。
+
+## 六块骨架
+
+六块标题写死：不改名、不合并、不跳块。某块没内容就写「无」。
+
+| 块 | 标题 | 写什么 |
+|---|---|---|
+| 1 | 结论 | 做完了什么、能不能用，一到两句。不放清单 |
+| 2 | 谁干了什么 | 表格：成员 / 交付物 / 状态 / 过程产物指针 |
+| 3 | 验收证据 | 一条一行：可粘贴的命令 + 输出摘要 + 是不是 Lead 自己复跑过 |
+| 4 | 偏离与未验证 | 偏离规格的、只口头声称没证据的 |
+| 5 | 死路与决策 | 结论级死路一行一条；不可逆决策一条一记录 |
+| 6 | 未决与下一步 | 还没定的、下一轮第一件事、明确不做什么 |
+
+照这个骨架填，标题一个字都别改：
+
+```markdown
+# 团队汇总 · <effort>
+
+## 结论
+
+## 谁干了什么
+
+| 成员 | 交付物 | 状态 | 过程产物指针 |
+|---|---|---|---|
+
+## 验收证据
+
+## 偏离与未验证
+
+### 未验证清单
+
+## 死路与决策
+
+## 未决与下一步
+```
+
+第 4 块是隔离区。「已通过」但拿不出证据的东西只能写在这里，不许混进第 1、2、3 块。
+
+### 第 2 块的状态列
+
+只有五个取值，别扩展：
+
+| 取值 | 什么时候用 |
+|---|---|
+| 完成 | 交付物在，验收证据也核过 |
+| 未验证 | 交付物在，但只有口头声称，没有可复跑的证据 |
+| 卡住 | 没干完，阻塞点还在 |
+| 被打断 | 被 `interrupt_agent` 或用户中途停掉 |
+| 上下文已降级 | 会话被自动压缩过，细节只剩摘要 |
+
+除「完成」外，其余四个都要在末尾「未验证」清单里点名。
+
+### 第 3 块怎么写
+
+每条证据占一行，三项齐：命令、输出摘要、是否复跑。
+
+- 命令要能直接粘贴，带工作目录或绝对路径。
+- 输出摘要写判定结果，比如 `31 pass / 0 fail`、`diff 为空`，不贴整段日志。
+- 复跑分三种：Lead 自己跑过、只有成员跑过、谁都没跑。第三种不算证据。
+
+### 第 5 块怎么写
+
+死路按结论级写，一行一条，形状是「试过 X，不行，因为 Y」。不写探索过程。
+
+不可逆决策一条一记录，五个字段：
+
+1. 背景：当时卡在什么上。
+2. 备选：还考虑过什么。
+3. 选的：最后选了哪个。
+4. 依据：为什么是它。
+5. 什么情况下推翻：什么信号出现就该翻案。
+
+## 原料怎么取
+
+三层，按顺序取，别跳级。上层够用就不下钻。
+
+| 层 | 来源 | 取什么 |
+|---|---|---|
+| 1 | 收尾消息 | 结论、文件清单、验收输出、偏离规格四块，做骨架 |
+| 2 | 工作日志 | `.scratch/<effort>/worklog-<mate>.md`，过程细节、死路、决策 |
+| 3 | 会话日志 | 兜底，只在收尾消息缺字段或工作日志不存在时 |
+
+### 第 1 层：收尾消息
+
+成员收工时，它最后那条消息随通知进你的上下文。大多数情况这一层就够写第 1、2、3 块。
+
+有两种情况会缺：
+
+- 上下文被压缩，早期成员的通知只剩摘要。
+- 成员收工前刚发过 `send_message`，收尾正文会被省掉。
+
+捞回来用 `session_event_search`，`session_id` 填自己的会话 id，`surfaces` 同时带被遮蔽和只进日志两面：
+
+```
+session_event_search({
+  session_id: '<你自己的会话 id>',
+  query: '<成员名或交付物关键词>',
+  surfaces: ['shadowed', 'log-only'],
+})
+```
+
+`query` 是必填的全文关键词，做的是字符串匹配，不是语义检索。写成员名或文件名最准。
+
+### 第 2 层：工作日志
+
+路径固定 `.scratch/<effort>/worklog-<mate>.md`。头部状态摘要给第 2 块，下面的轮次记录给第 4、5 块。
+
+文件不存在不算异常：说明该成员没按派活要求写日志，第 2 块状态照实写，末尾清单点名。
+
+### 第 3 层：会话日志下钻
+
+只在「收尾消息缺字段」或「工作日志不存在」时用，**一个成员最多下钻一次**。
+
+```
+session_event_search({
+  session_id: '<成员 id>',
+  event_types: ['assistant/message'],
+})
+```
+
+两条限制：
+
+- 跨 cwd 读不到。成员会话的工作目录必须和 Lead 相同，否则这条查不到东西。
+- 下钻一次还不齐就写「未验证」，不要反复翻。
+
+## 证据指针怎么挂
+
+按证据类型挂，挂错类型等于没挂。
+
+| 证据类型 | 挂什么 | 例子 |
+|---|---|---|
+| 改动 | `路径:行号` | `skills/team-digest/SKILL.md:38` |
+| 验收 | 可粘贴命令 | `node --test test/*.test.mjs` |
+| 决策 | 工作日志段名，或 `session-<id>#seq` | `worklog-skill-author.md 第 5 块` |
+
+指针指向已有产物，不复制正文。复制两份，改一份就有一份在骗人。
+
+## 异常成员怎么处理
+
+| 情况 | 第 2 块状态 | 额外动作 |
+|---|---|---|
+| 没交收尾消息 | 被打断 | 末尾清单列出它负责的交付物 |
+| 只有「已通过」「已修复」这类话 | 未验证 | 能复跑就复跑，跑不了就照实写缺什么 |
+| 工作日志没写 | 按实际交付判 | 末尾清单点名「无工作日志」 |
+| 被压缩过 | 上下文已降级 | 需要细节时下钻一次，结论降一档置信度 |
+| 创建失败或始终没起来 | 卡住 | 单列一行，写清失败现象 |
+
+「未验证」清单不是第 4 块的替代品：第 4 块写偏离规格和无证据的结论，清单写「谁、什么没验、缺什么证据」。
+
+## 宿主事实
+
+这些是宿主当前行为，别按直觉推：
+
+| 事实 | 后果 |
+|---|---|
+| `team_task_update` 的 `complete` 不能带结果载荷 | 任务板不是结果记录本，结论只能写进汇总 |
+| `wait_agent` 只返回 `{timedOut, noProgress}` | 它不带任何内容，别指望从返回值里拿到成员说了什么 |
+| 宿主没有报告类工具 | 汇总只能自己组织，没有现成模板命令可调 |
+| 压缩事件（`compaction/start` 等）都是 log-only | 检索必须显式带 `surfaces: ['log-only']`，否则查不到 |
+| 成员名额 `maxMembers` 由 profile 层设为 8 | 名字永不释放，创建失败也占名额 |
+
+## 写作口径
+
+- 中文，短句，结论在前。
+- 没实测的数字不写精确值，写「未验证」。
+- 六块标题写死，不许改名、不许合并、不许跳块。
+- 纯 markdown，零外部依赖。Obsidian、answer-me-with-html、dsh-context 一律「装了才用」，没装也要能写完。
+- 术语固定四个：团队汇总、死路、过程产物、证据指针。不另造近义词。