cs-bots 0.9.0 → 0.9.3

package/src/client.js

@@ -2464,6 +2464,8 @@ window.__ModuleLoader__.load({
       // 后端在「没有执行者」时返回 ok:false + code NO_EXECUTOR，call() 会抛错 ——
       // 那不是故障，是正常空态，要按空态呈现。
       const noExecutor = /NO_EXECUTOR/.test(convQ.error ?? '') || /没有执行者/.test(convQ.error ?? '')
+      // t-40：有执行者但一条记录都没有（既没对话也没补充说明）——也是一种正常空态
+      const noConversation = /NO_CONVERSATION/.test(convQ.error ?? '') || /还没有对话记录/.test(convQ.error ?? '')
 
       /** 跳到执行者的会话（宿主支持就直接开，不支持则复制 ID 兜底）。 */
       const gotoSession = async () => {
@@ -2482,8 +2484,13 @@ window.__ModuleLoader__.load({
       }
 
       const roleLabel = (m) => {
-        if (m.role === 'user') return HUMAN_SELF_LABEL
-        if (m.role === 'assistant') return bot?.name ?? '执行者'
+        // t-40：消息来自两条来源 —— executor（执行者会话）/ note（用户在任务里的补充说明）。
+        // 用户说的话必须一眼可辨，所以 note 来源的 user 消息额外标「任务里」。
+        if (m.role === 'user') {
+          if (m.source === 'note') return `${HUMAN_SELF_LABEL}（任务里）`
+          return HUMAN_SELF_LABEL
+        }
+        if (m.role === 'assistant') return m.speaker && m.speaker !== bot?.name ? m.speaker : (bot?.name ?? '执行者')
         if (m.role === 'tool') return m.toolName ? `工具 · ${m.toolName}` : '工具'
         return m.role ?? '?'
       }
@@ -2496,9 +2503,10 @@ window.__ModuleLoader__.load({
         h(Section, {
           title: '任务对话',
           desc: bot
-            ? `执行者「${bot.name}」的会话记录（最近 ${messages.length} 条${data?.truncated ? '，已截断' : ''}）。`
+            ? `执行者「${bot.name}」的会话 + 你在任务里说的话，按时间合并（共 ${messages.length} 条`
+              + `${data?.counts ? `：执行者 ${data.counts.executor} 条 / 任务说明 ${data.counts.note} 条` : ''}）。`
               + '这里是只读的：要看全部或继续聊，点「去对话」。'
-            : '任务派给 Bot 之后，它的执行过程会出现在这里。',
+            : '任务派给 Bot 之后，它的执行过程和你下的指令都会出现在这里。',
         }, null),
 
         convQ.loading ? h(Skeleton, { n: 2 }) : null,
@@ -2509,7 +2517,13 @@ window.__ModuleLoader__.load({
               title: '还没有执行者',
               hint: '任务派给 Bot 之后才会有对话记录。先在「可以做什么」里派活，或者用 Bot 页的「派发」把任务交给它。',
             })
-          : convQ.error
+          : noConversation
+            ? h(Empty, {
+                icon: '◌',
+                title: '还没有对话记录',
+                hint: '这个任务既没派活、也没有补充说明。派活之后执行过程会出现在这里；你也可以在下面写一条补充说明，它同样会显示在这里。',
+              })
+            : convQ.error
             ? h('div', { className: 'csb-err' }, `读不到对话：${convQ.error}`)
             : null,
 
@@ -6411,6 +6425,38 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // ── 建议编辑（t-40）──
+      // Boss：「用户应该可以修改完善并确定等级范围」。
+      // 只给「采纳/驳回」时，措辞不合意就只能驳回重等 —— 越推越远。
+      const [sgEdit, setSgEdit] = useState(null)
+      const openSgEdit = (sg) => setSgEdit({
+        id: sg.id,
+        rev: sg.rev,
+        kind: sg.kind,
+        layer: sg.layer ?? sg.payload?.layer ?? '',
+        content: sg.payload?.content ?? sg.payload?.name ?? sg.payload?.title ?? '',
+      })
+      const saveSgEdit = async () => {
+        if (!sgEdit) return
+        setErr(null)
+        try {
+          await call('/suggestions/edit', {
+            method: 'POST',
+            body: {
+              id: sgEdit.id,
+              expectedRev: sgEdit.rev,
+              content: sgEdit.content,
+              ...(sgEdit.kind === 'memory' && sgEdit.layer ? { layer: sgEdit.layer } : {}),
+            },
+          })
+          setOk('已保存修改，它仍是待确认状态')
+          setSgEdit(null)
+          reloadSug()
+        } catch (e) {
+          setErr(e.message)
+        }
+      }
+
       const decideSuggestion = async (sg, accept) => {
         setErr(null)
         try {
@@ -6643,10 +6689,11 @@ window.__ModuleLoader__.load({
               footer: [h('button', { key: 'c', className: 'csb-btn', onClick: () => setShowSug(false) }, '关闭')],
             },
             h('p', { style: { color: 'var(--dsw-alias-label-secondary)', fontSize: 12 } },
-              '这些是模型整理的「它认为该记住/该改」的条目。Boss 不点采纳，它就不会生效。'),
+              '这些是模型整理的「它认为该记住/该改」的条目。不点采纳不会生效；措辞或等级不合意，点「编辑」改完再采纳。'),
             suggestions.length === 0
               ? h(Empty, { icon: '✓', title: '没有待确认的建议', hint: '有建议时这里会出现。' })
-              : h('div', { className: 'csb-list' }, suggestions.map((sg) => h('div', { key: sg.id, className: 'csb-card' },
+              : h('div', null,
+                h('div', { className: 'csb-list' }, suggestions.map((sg) => h('div', { key: sg.id, className: 'csb-card' },
                   h('div', { className: 'csb-card-main' },
                     h('div', { className: 'csb-card-t2' }, sg.payload?.content ?? sg.payload?.name ?? sg.payload?.title ?? '（无内容）'),
                     h('div', { className: 'csb-card-m' },
@@ -6655,8 +6702,39 @@ window.__ModuleLoader__.load({
                       sg.reason ? h('span', null, sg.reason) : null,
                       sg.confidence ? h('span', null, `把握 ${Math.round(sg.confidence * 100)}%`) : null)),
                   h('div', { style: { display: 'flex', gap: 6, flex: 'none' } },
+                    h('button', { className: 'csb-btn csb-btn-s', onClick: () => (sgEdit?.id === sg.id ? setSgEdit(null) : openSgEdit(sg)) }, sgEdit?.id === sg.id ? '收起' : '编辑'),
                     h('button', { className: 'csb-btn csb-btn-s csb-btn-p', onClick: () => decideSuggestion(sg, true) }, '采纳'),
-                    h('button', { className: 'csb-btn csb-btn-s', onClick: () => decideSuggestion(sg, false) }, '驳回'))))))
+                    h('button', { className: 'csb-btn csb-btn-s', onClick: () => decideSuggestion(sg, false) }, '驳回')))))),
+            // 编辑面板：与列表平级，不嵌进卡片 —— 改动更小、也不会打乱既有括号结构
+            sgEdit
+              ? h('div', { className: 'csb-card', style: { marginTop: 10, padding: 12 } },
+                  h('div', { style: { fontWeight: 600, marginBottom: 6 } }, `编辑建议 ${sgEdit.id}`),
+                  h('textarea', {
+                    className: 'csb-input',
+                    rows: 4,
+                    value: sgEdit.content,
+                    onInput: (e) => setSgEdit({ ...sgEdit, content: e.target.value }),
+                    style: { width: '100%', fontFamily: 'inherit', marginBottom: 8 },
+                  }),
+                  sgEdit.kind === 'memory'
+                    ? h('div', { style: { display: 'flex', alignItems: 'center', gap: 8, marginBottom: 8 } },
+                        h('span', { style: { fontSize: 12 } }, '等级'),
+                        h('select', {
+                          className: 'csb-input',
+                          value: sgEdit.layer,
+                          onChange: (e) => setSgEdit({ ...sgEdit, layer: e.target.value }),
+                        },
+                          h('option', { value: '' }, '（不指定）'),
+                          h('option', { value: 'L1' }, 'L1 用户偏好'),
+                          h('option', { value: 'L2' }, 'L2 团队全局'),
+                          h('option', { value: 'L3' }, 'L3 项目 key'),
+                          h('option', { value: 'L4' }, 'L4 任务笔记'),
+                          h('option', { value: 'L5' }, 'L5 日札')))
+                    : h('div', { style: { fontSize: 12, opacity: 0.7, marginBottom: 8 } }, '（该类型没有等级可选）'),
+                  h('div', { style: { display: 'flex', gap: 6 } },
+                    h('button', { className: 'csb-btn csb-btn-s csb-btn-p', onClick: saveSgEdit }, '保存修改'),
+                    h('button', { className: 'csb-btn csb-btn-s', onClick: () => setSgEdit(null) }, '取消')))
+              : null)
           : null,
 
         // ── 注入效果 ──

package/src/room.js

@@ -162,10 +162,30 @@ const USER = 'user'
  * 缺省广播把 Boss 自己也算成唤醒目标，每次必失败一条。
  */
 const HUMAN_IDS = Object.freeze(['ui', 'user', 'person'])
-/** 是否为人类身份（房间转发一律跳过）。 */
+
+/**
+ * **规范用户 id**（2026-11-12 t-40 需求⑤）。
+ *
+ * Boss：「以后要统一一下名称……人=用户=boss=user=我」。
+ * 历史数据里同一个人有三种写法（`ui` 来自页面层、`user` 来自 API 层、`person` 来自早期约定），
+ * 于是「这是谁」在每一处都要判三遍，迟早漏一处。
+ *
+ * 采用**读兼容 + 写统一**，而不是一刀切改写历史：
+ *   - 读：`ui`/`person` 一律视为 `user`（`HUMAN_IDS` 仍然认它们，老数据不会失效）；
+ *   - 写：新写入一律用 `user`。
+ * 这样不破坏历史事件流（append-only，改历史等于伪造），又能让新数据只有一个写法。
+ */
+const CANONICAL_USER = 'user'
+
+/** 是否为人类身份（`ui`/`user`/`person` 都认 —— 读侧兼容）。 */
 function isHumanId(id) {
   return typeof id === 'string' && HUMAN_IDS.includes(id)
 }
+
+/** 把任意人类写法归一成规范 id `user`；非人类身份原样返回。 */
+function normalizeHumanId(id) {
+  return isHumanId(id) ? CANONICAL_USER : id
+}
 /** 房间事件类型集合（审计流可枚举）。 */
 const EVENTS = [
   'room_created',
@@ -352,6 +372,64 @@ function collectMentions(message, members) {
   return out
 }
 
+/**
+ * 计算「一条房间消息该唤醒谁」—— **唤醒风暴的唯一真相源**。
+ *
+ * 为什么抽成独立函数（2026-11-12 t-40-B 修复）：
+ * 房间有**两条**唤醒路径，过去各写一份目标计算，于是必然漂移：
+ *   - `room.relay()`（`POST /rooms/relay`）实现了四档规则；
+ *   - `POST /rooms/post`（Bot 用 `bot_room_post`、Boss 用 UI **都走这条**）却是
+ *     裸的 `members.filter((m) => m !== skipSelf)` —— 不看 `mentionOnly`、
+ *     不排除人类 id。实测 6 个房间全设了 `mentionOnly:true`，**一次都没生效**；
+ *     8 成员房间 ⇒ 一条消息 8 次模型调用，其中打给人类 id 的必然失败。
+ *
+ * 所以这里只留**一份**规则，两个调用点都用它。改规则只改这里。
+ *
+ * 四档，**顺序即优先级**（与 relay 原注释一致）：
+ *   ① 显式 targets → 原样采信（剔除人类，并 warn：那是调用方的错）
+ *   ② mentionOnly=true 且 @ 了某人 → 只打给被 @ 的成员（不含发送者/人类）
+ *   ③ mentionOnly=true 但没 @ → **空**（只落消息不唤醒，合法结果，不是错误）
+ *   ④ mentionOnly=false（显式关掉定向）→ 除发送者外的全部成员，**仍排除人类**
+ *
+ * @param {{ members?: string[], settings?: object, from?: string }} room 房间快照
+ * @param {{ from?: string, text?: string, mentions?: string[] }} message 消息
+ * @param {{ targets?: unknown, warn?: (m: string) => void }} [options]
+ *        显式目标（仅 relay 用）；`warn` 注入调用方所在作用域的日志器
+ *        （工厂内部有 `warn`，模块顶层没有 —— 这里显式注入，不靠隐式作用域）
+ * @returns {{ targets: string[], source: 'explicit'|'mention'|'mention-only-no-target'|'broadcast' }}
+ */
+function computeWakeTargets(room, message, options = {}) {
+  const members = Array.isArray(room?.members) ? room.members : []
+  const settings = room?.settings ?? DEFAULT_SETTINGS
+  const mentionOnly = settings.mentionOnly !== false
+  // 发送者自己永远不唤醒（发消息的人不需要被自己的消息叫醒）
+  const sender = message?.from ?? room?.from
+  /** 唤醒排除表：人类一律不算唤醒目标（人没有会话，唤醒必然 agent-not-live）。 */
+  const wakeable = (id) => id !== sender && !isHumanId(id)
+
+  if (options?.targets !== undefined && options?.targets !== null) {
+    let list = stringList(options.targets, 'targets', 'relay')
+    const humans = list.filter((t) => isHumanId(t))
+    if (humans.length > 0) {
+      const say = typeof options.warn === 'function' ? options.warn : () => {}
+      say(`[cs-bots/room] 显式 targets 含人类身份 ${humans.join(',')} —— 已剔除（人不可被唤醒）`)
+      list = list.filter((t) => !isHumanId(t))
+    }
+    return { targets: list, source: 'explicit' }
+  }
+
+  if (mentionOnly) {
+    const mentioned = collectMentions(message, members)
+    const targets = mentioned.filter(wakeable)
+    return targets.length > 0
+      ? { targets, source: 'mention' }
+      : { targets: [], source: 'mention-only-no-target' }
+  }
+
+  // ④ 显式关掉定向才广播 —— 即便如此也不唤醒人类、不唤醒发送者自己
+  return { targets: members.filter(wakeable), source: 'broadcast' }
+}
+
 /** 时间参数归一：缺省 now；支持 ms 数字与 Date。 */
 function normalizeNow(value, where) {
   if (value === undefined || value === null) return Date.now()
@@ -1966,42 +2044,29 @@ export function createRoom(ctx, config = {}) {
     let targetSource
     let noTargetReason
 
-    if (targets !== undefined && targets !== null) {
-      targetList = stringList(targets, 'targets', 'relay')
-      if (targetList.length === 0) {
-        throw new RoomError(
-          `room.relay：targets 是空数组 —— 拒绝空转发（静默无操作），请显式给出目标或省略该字段走缺省`,
-          'ROOM_NO_TARGETS',
-          { roomId: room.id, messageId: mid },
-        )
-      }
-      targetSource = 'explicit'
-      // 显式 targets 可能混进人类 —— 剔除，但这是**调用方的错**，如实 warn 不静默
-      const humans = targetList.filter((t) => isHumanId(t))
-      if (humans.length > 0) {
-        warn(`[cs-bots/room] relay 显式 targets 含人类身份 ${humans.join(',')} —— 已剔除（人不可被唤醒）`)
-        targetList = targetList.filter((t) => !isHumanId(t))
-      }
-    } else if (mentionOnly) {
-      // 从消息里解析「被 @ 的人」：mentions 字段 + text 里的 `@id`（与 admission.isAddressed 同口径）
-      const mentioned = collectMentions(message, room.members)
-      targetList = mentioned.filter(wakeable)
-      targetSource = 'mention'
-      if (targetList.length === 0) {
-        targetSource = 'mention-only-no-target'
-        noTargetReason = 'mention-only-no-target'
-      }
-    } else {
-      targetList = room.members.filter(wakeable)
-      targetSource = 'broadcast'
-      if (targetList.length === 0) {
-        throw new RoomError(
-          `room.relay：房间 ${room.id} 除发送者（${message.from}）外没有其他可唤醒成员，且未显式指定 targets`
-          + ' —— 拒绝空转发（静默无操作）',
-          'ROOM_NO_TARGETS',
-          { roomId: room.id, messageId: mid, from: message.from },
-        )
-      }
+    // 规则统一在 computeWakeTargets（t-40-B）：与 `POST /rooms/post` 共用同一份，
+    // 避免两条唤醒路径各写一套而再度漂移。
+    const decided = computeWakeTargets(room, message, { targets, warn })
+    targetList = decided.targets
+    targetSource = decided.source
+    if (targetSource === 'mention-only-no-target') noTargetReason = 'mention-only-no-target'
+    // 显式 targets 给了空数组 ⇒ 调用方契约违反，抛错（computeWakeTargets 只管剔除人类）
+    if (targetSource === 'explicit' && Array.isArray(targets) && targets.length === 0) {
+      throw new RoomError(
+        `room.relay：targets 是空数组 —— 拒绝空转发（静默无操作），请显式给出目标或省略该字段走缺省`,
+        'ROOM_NO_TARGETS',
+        { roomId: room.id, messageId: mid },
+      )
+    }
+    // 广播档但「除发送者外全是人类」⇒ 这是**配置错误**（没有 bot 可广播），抛错比静默诚实。
+    // 注意：mention 档的空结果不算错（③「只记录不打扰」是合法结果），二者不能混。
+    if (targetSource === 'broadcast' && targetList.length === 0) {
+      throw new RoomError(
+        `room.relay：房间 ${room.id} 除发送者（${message.from}）外没有其他可唤醒成员，且未显式指定 targets`
+        + ' —— 拒绝空转发（静默无操作）',
+        'ROOM_NO_TARGETS',
+        { roomId: room.id, messageId: mid, from: message.from },
+      )
     }
 
     // ── ③「没 @ 到谁」：合法空转发 —— 记事件、返回 relayed:0，**不抛错** ──────
@@ -2304,6 +2369,14 @@ export function createRoom(ctx, config = {}) {
     leave,
     post,
     relay,
+    /**
+     * 计算「这条消息该唤醒谁」（t-40-B）。
+     * 暴露给 `POST /rooms/post` 复用，保证两条唤醒路径共用同一份规则；
+     * 纯函数、不落盘、不唤醒，调用方自己决定要不要投递。
+     * 绑定本实例的 `warn`，这样 HTTP 路径的告警与 relay 走同一个 logger。
+     */
+    computeWakeTargets: (room, message, options = {}) =>
+      computeWakeTargets(room, message, { ...options, warn }),
     readBody,
     listMessages,
     // DESIGN-v2 ①：房间配置 / 归档 / 硬删 / 成员角色（签名见 DESIGN 契约，勿改名）
@@ -2338,5 +2411,6 @@ export const ROOM_DEFAULT_SETTINGS = Object.freeze({ ...DEFAULT_SETTINGS })
 
 /** 用户（人类）发送者 id（`from` 允许的特殊值）。 */
 export const ROOM_USER = USER
+export const ROOM_CANONICAL_USER = CANONICAL_USER
 
 export default createRoom

package/src/roster.js

@@ -100,6 +100,7 @@ const ACTIONS = [
   'create',
   'rename',
   'retire',
+  'purge',
   'set_cwd',
   'claim',
   'release',
@@ -517,6 +518,8 @@ export function createRoster(ctx, config = {}) {
         skipped += 1
         continue
       }
+      // purge 是终态：重放时把它从内存表移除，而不是复活成一条记录
+      if (ev.after.state === 'purged') { bots.delete(ev.botId); events.push(clone(ev)); continue }
       bots.set(ev.botId, clone(ev.after))
       events.push(clone(ev))
     }
@@ -694,7 +697,7 @@ export function createRoster(ctx, config = {}) {
    * @throws {RosterError} 缺字段 / 非法 cwd / 重名 / 会话创建失败 / 事件落盘失败
    */
   async function create(input = {}) {
-    const { name, cwd, label, model, instructions, preset, permission, profile, prepareCommand, byId, now } = input ?? {}
+    const { name, cwd, label, model, instructions, preset, permission, profile, prepareCommand, byId, now, adoptSession } = input ?? {}
     const by = requireString(byId, 'byId', 'create')
     const displayName = requireString(name, 'name', 'create')
     const dir = assertBotCwd(cwd, 'create')
@@ -707,6 +710,28 @@ export function createRoster(ctx, config = {}) {
     // ── 唯一性（校验通过后才动会话，避免「建了会话才发现重名」的资源泄漏）──
     assertNameFree(displayName, undefined, 'create')
 
+    // ── adoptSession：把**已存在的会话**注册成 Bot（2026-11-11 Boss 需求）──
+    // 为什么需要：`create()` 原本只会**新建**会话（`bot-${randomUUID()}`），
+    //   无法接管一个已经在跑、已有上下文的会话。Boss 要把当前会话（带着全部上下文）
+    //   变成可在协作平台派活的 Bot ⇒ 会话 id 必须保持不变。
+    // 语义边界：
+    //   - `adoptSession` 给出时**不建新会话**，注册表直接引用它；
+    //   - 该 sessionId 不能已被别的活跃 Bot 占用（`hasSession` 查重）；
+    //   - 退役 Bot 里的同名 session 不阻止接管（终态已释放名额）。
+    const adopt = optionalString(adoptSession, 'adoptSession', 'create')
+    if (adopt !== undefined) {
+      for (const other of bots.values()) {
+        if (other.state !== 'retired' && other.sessionId === adopt) {
+          throw new RosterError(
+            `roster.create：会话 ${adopt} 已被 Bot「${other.name}」（${other.id}）占用——`
+            + '同一会话不能注册成两个 Bot',
+            'ROSTER_SESSION_TAKEN',
+            { sessionId: adopt, occupiedBy: other.id },
+          )
+        }
+      }
+    }
+
     // ── 同 cwd 提示（非阻塞）：两个活 Bot 共用一个目录会撞 fs 写入边界 ──
     for (const other of bots.values()) {
       if (other.state !== 'retired' && other.cwd === dir) {
@@ -717,29 +742,41 @@ export function createRoster(ctx, config = {}) {
       }
     }
 
-    // ── 会话创建：**唯一能指定 cwd 的路径**（kernel.js:249-287）──
-    const id = `bot-${randomUUID()}`
-    let handle
-    try {
-      handle = await kernel.createSession(ctx, {
-        sessionId: id,
-        cwd: dir,
-        warn,
-        ...(preset !== undefined && preset !== null && preset !== '' ? { agentPreset: String(preset) } : {}),
-      })
-    } catch (error) {
-      throw new RosterError(
-        `roster.create：Bot「${displayName}」的会话创建失败（cwd=${dir}）→ ${error?.message ?? error}`
-        + '——已中止注册（不产生半成品 Bot）',
-        'ROSTER_SESSION_CREATE_FAILED',
-        { name: displayName, cwd: dir, cause: String(error?.message ?? error) },
-      )
-    }
-    const sessionId = pickSessionId(handle, id)
-    if (sessionId !== id) {
-      warn(
-        `[cs-bots/roster] 宿主返回的会话 id（${sessionId}）与请求的（${id}）不同——以宿主返回为准并记入注册表`,
-      )
+    // ── 会话：要么新建，要么接管已有（adoptSession）──
+    //
+    // 新建时这是**唯一能指定 cwd 的路径**（kernel.js:249-287）。
+    // 接管时**不碰会话**：那个会话已经在跑、有自己的 cwd 与上下文，
+    // 我们只是把它登记进注册表 —— 因此 `id` 直接沿用该 sessionId
+    // （不生成 `bot-xxx`），这样 `wake`/任务派活的目标 id 与真实会话对得上。
+    let id
+    let sessionId
+    if (adopt !== undefined) {
+      id = adopt
+      sessionId = adopt
+    } else {
+      id = `bot-${randomUUID()}`
+      let handle
+      try {
+        handle = await kernel.createSession(ctx, {
+          sessionId: id,
+          cwd: dir,
+          warn,
+          ...(preset !== undefined && preset !== null && preset !== '' ? { agentPreset: String(preset) } : {}),
+        })
+      } catch (error) {
+        throw new RosterError(
+          `roster.create：Bot「${displayName}」的会话创建失败（cwd=${dir}）→ ${error?.message ?? error}`
+          + '——已中止注册（不产生半成品 Bot）',
+          'ROSTER_SESSION_CREATE_FAILED',
+          { name: displayName, cwd: dir, cause: String(error?.message ?? error) },
+        )
+      }
+      sessionId = pickSessionId(handle, id)
+      if (sessionId !== id) {
+        warn(
+          `[cs-bots/roster] 宿主返回的会话 id（${sessionId}）与请求的（${id}）不同——以宿主返回为准并记入注册表`,
+        )
+      }
     }
 
     /** @type {Record<string, unknown>} */
@@ -929,6 +966,74 @@ export function createRoster(ctx, config = {}) {
     return committed
   }
 
+  /**
+   * 清理（purge）已退役的 Bot —— **把记录从注册表里真正移走**（2026-11-12 t-40，Boss 要求）。
+   *
+   * 为什么 retire 不够：`retire` 只是把 `state` 置为 `retired`，**记录永远留在注册表里**
+   * （`listRetired()` 能查到、`roster.jsonl` 里一堆测试残留），时间一长注册表就被
+   * 一堆没用的测试 Bot 撑满，管理页看不清到底有哪些在役 Bot。
+   *
+   * 语义边界（必须守住的四条）：
+   *   1. **只能清已退役的** —— 在役 Bot 一律拒绝（`ROSTER_PURGE_ACTIVE`）。
+   *      退役是"我不用它了"，清理是"把这条记录抹掉"；两步分开，避免手滑删在役 Bot。
+   *   2. **只动注册表，绝不动 cwd 目录、绝不动会话** —— Bot 的工作目录里可能有真实产物
+   *      （实测 `/home/ubuntu/output/开发测试001` 里存着 t36 调研报告），
+   *      删目录是不可逆且越权的，本函数**不碰文件系统**。
+   *   3. **事件流仍留档**：往 `roster.jsonl` 追加一条 `purge` 事件（`after` = 清理后的状态），
+   *      重放时据此把该 Bot 从内存表里移除 —— 这样「谁在什么时候清了谁」可审计，
+   *      而不是把历史抹得干干净净。
+   *   4. **幂等**：已清理的再清一次直接跳过（计入 `skipped`），不抛错。
+   *
+   * @param {{ ids?: string[], allRetired?: boolean, reason?: string, byId: string, now?: number }} input
+   *        `ids` 指定要清的 Bot；`allRetired: true` 清全部已退役的（与 `ids` 二选一）
+   * @returns {{ purged: string[], skipped: string[], refused: Array<{id: string, reason: string}> }}
+   */
+  function purge(input = {}) {
+    const { ids, allRetired, reason, byId, now } = input ?? {}
+    const by = requireString(byId, 'byId', 'purge')
+    const note = optionalString(reason, 'reason', 'purge')
+    const at = normalizeNow(now, 'purge')
+
+    let targets = []
+    if (allRetired === true) {
+      for (const b of bots.values()) if (b.state === 'retired') targets.push(b.id)
+    } else if (Array.isArray(ids)) {
+      targets = ids.map((x, i) => requireString(x, `ids[${i}]`, 'purge'))
+    } else {
+      throw new RosterError(
+        'roster.purge：必须给 ids（数组）或 allRetired:true（二选一）—— 拒绝无目标清理',
+        'ROSTER_PURGE_NO_TARGET',
+        {},
+      )
+    }
+
+    const purged = []
+    const skipped = []
+    const refused = []
+    for (const botId of targets) {
+      const current = bots.get(botId)
+      if (!current) { skipped.push(botId); continue }
+      if (current.state !== 'retired') {
+        // 在役 Bot 绝不清理：这是本条 API 最重要的护栏
+        refused.push({ id: botId, reason: `在役（state=${current.state}）—— 先 retire 再 purge` })
+        continue
+      }
+      const before = clone(current)
+      const next = clone(current)
+      next.rev = current.rev + 1
+      next.state = 'purged'
+      next.purgedAt = at
+      next.purgedBy = by
+      if (note !== undefined) next.purgeReason = note
+      // 写事件而不是把它从 jsonl 里抠掉：留档「谁清的、何时清的」
+      commit(botId, 'purge', by, at, before, next)
+      bots.delete(botId)
+      purged.push(botId)
+      info(`[cs-bots/roster] Bot ${botId}（「${current.name}」）已清理出注册表`)
+    }
+    return { purged, skipped, refused }
+  }
+
   /**
    * 换工作目录（**官方完全没有的语义**：teammate 强制继承父 cwd）。
    *
@@ -1461,6 +1566,7 @@ export function createRoster(ctx, config = {}) {
     hasSession,
     rename,
     retire,
+    purge,
     setPreset,
     setCwd,
     setPrepareCommand,

package/src/suggest.js

@@ -1040,6 +1040,115 @@ export function createSuggest(ctx, config = {}) {
     return decided
   }
 
+  /**
+   * 修改一条**待决**建议：内容 / 等级（layer）/ 标题标签都可以改（2026-11-12 t-40）。
+   *
+   * Boss 原话：「自动整理建议中，用户只能接纳和驳回，等级没办法选择、内容没办法修改，
+   * 用户应该可以修改完善并确定等级范围」
+   *
+   * 为什么必须有这个口子：模型归纳出来的文字几乎总是「意思是对的、措辞不是我的」。
+   * 只给「采纳/驳回」两个按钮，用户遇到措辞不合意的建议只能驳回再等它重新提一遍 ——
+   * 而驳回会让同类建议进冷却，等于把「差一点就对」的东西越推越远。
+   *
+   * 语义边界：
+   *   - **只能改 pending**：已采纳/已驳回是终态，改它等于篡改历史（要提新的就 propose）。
+   *   - **改完仍是 pending**：编辑不等于采纳，用户改完可以再想想。
+   *   - **等级仍走同一套白名单**：`layer` 只能是 MEMORY_LAYERS（L0 仍不可写）。
+   *   - **改类型（kind）时 payload 必须一起给**：记忆与技能的 payload 形状不同。
+   *   - **必须 CAS**：`expectedRev` 必填，防两人同时改互相覆盖。
+   *   - **审计留痕**：写 `edit` 事件，before/after 都在事件流里可查。
+   *
+   * @param {{ id: string, expectedRev: number, payload?: object, kind?: string,
+   *           layer?: string, title?: string, content?: string, by: string, now?: number }} input
+   * @returns {object} 修改后的建议（rev 已 +1）
+   */
+  function edit(input = {}) {
+    assertAlive('edit')
+    const { id, expectedRev, kind, title, content, by, now } = input ?? {}
+    let { payload } = input ?? {}
+    const suggestionId = requireString(id, 'id', 'edit')
+    const author = requireString(by, 'by', 'edit')
+    const at = normalizeNow(now, 'edit')
+    const current = requireSuggestion(suggestionId, 'edit')
+
+    if (current.status !== 'pending') {
+      throw new SuggestError(
+        `suggest.edit：建议 [id:${suggestionId}] 已是 ${current.status}（终态不可改）—— `
+        + '要改请重新提一条（propose）',
+        'SUGGEST_NOT_PENDING',
+        { id: suggestionId, status: current.status },
+      )
+    }
+    const rev = Number(expectedRev)
+    if (!Number.isFinite(rev)) {
+      throw new SuggestError(
+        'suggest.edit：expectedRev 必填（修改是覆盖性操作，必须带版本做 CAS）',
+        'SUGGEST_BAD_FIELD',
+        { id: suggestionId, field: 'expectedRev' },
+      )
+    }
+    if (rev !== current.rev) {
+      throw new SuggestError(
+        `suggest.edit：CAS 冲突（期望 rev=${rev}，实际 rev=${current.rev}）—— 有人先改过了，请刷新后重试`,
+        'SUGGEST_REV_CONFLICT',
+        { id: suggestionId, expectedRev: rev, actualRev: current.rev },
+      )
+    }
+
+    const before = clone(current)
+    const next = clone(current)
+    next.rev = current.rev + 1
+
+    const nextKind = kind === undefined || kind === null ? current.kind : requireString(kind, 'kind', 'edit')
+    if (!KINDS.includes(nextKind)) {
+      throw new SuggestError(
+        `suggest.edit：kind 只能是 ${KINDS.join(' | ')}，收到 ${JSON.stringify(nextKind)}`,
+        'SUGGEST_BAD_KIND',
+        { id: suggestionId, kind: nextKind },
+      )
+    }
+    if (nextKind !== current.kind && payload === undefined) {
+      throw new SuggestError(
+        `suggest.edit：改 kind（${current.kind} → ${nextKind}）必须同时给 payload —— `
+        + '记忆与技能的 payload 形状不同，只换类型会留下形状不匹配的脏数据',
+        'SUGGEST_KIND_REQUIRES_PAYLOAD',
+        { id: suggestionId, from: current.kind, to: nextKind },
+      )
+    }
+
+    if (payload === undefined && (title !== undefined || content !== undefined)) {
+      payload = { ...(current.payload ?? {}) }
+      if (title !== undefined) payload.title = title
+      if (content !== undefined) payload.content = content
+    }
+
+    if (payload !== undefined) {
+      const targetLayerForPayload = payload.layer ?? current.payload?.layer ?? null
+      next.payload = normalizePayload(nextKind, payload, 'edit', targetLayerForPayload)
+    }
+    next.kind = nextKind
+
+    if (input.layer !== undefined && input.layer !== null && input.layer !== '') {
+      if (!MEMORY_LAYERS.includes(input.layer)) {
+        throw new SuggestError(
+          `suggest.edit：layer 只能是 ${MEMORY_LAYERS.join(' | ')}（L0 人格仅人可写，不在此列），`
+          + `收到 ${JSON.stringify(input.layer)}`,
+          'SUGGEST_BAD_LAYER',
+          { id: suggestionId, layer: input.layer },
+        )
+      }
+      next.payload = { ...(next.payload ?? {}), layer: input.layer }
+    }
+
+    next.updatedAt = at
+    next.updatedBy = author
+    next.editedAt = at
+    next.editedBy = author
+    next.editCount = (Number(current.editCount) || 0) + 1
+
+    return commit('edit', at, author, before, next)
+  }
+
   /**
    * 批量采纳：**部分失败不中断**（人点「全部采纳」时，一条撞错不该让其余全不处理），
    * 但失败必须逐条回报（`failed[]` 带 code + reason），绝不吞掉。
@@ -1187,6 +1296,7 @@ export function createSuggest(ctx, config = {}) {
     getSuggestion,
     accept,
     reject,
+    edit,
     bulkAccept,
     stats,
     replay,