cs-bots 0.7.4 → 0.8.0

package/src/settings.js

@@ -16,8 +16,8 @@ import { resolve, sep, isAbsolute, join } from 'node:path'
 
 /** 设置项定义：默认值 + 校验。 */
 export const SETTING_SPECS = Object.freeze({
-  /** 任务默认租约时长（ms）：owner claim 后多久未心跳即视为失联。 */
-  defaultLeaseMs: { def: 5 * 60_000, min: 10_000, max: 24 * 60 * 60_000, label: '任务租约默认时长（ms）' },
+  /** 任务默认占用时长（ms）：owner claim 后多久未心跳即视为失联。 */
+  defaultLeaseMs: { def: 5 * 60_000, min: 10_000, max: 24 * 60 * 60_000, label: '任务占用默认时长（ms）' },
   /** 唤醒节流窗口（ms）：同一目标在窗内最多唤醒一次。 */
   throttleMs: { def: 5_000, min: 0, max: 60 * 60_000, label: '唤醒节流窗口（ms）' },
   /** 每目标唤醒队列上限（背压阈值）。 */

package/src/teams.js

@@ -64,7 +64,7 @@ export const DEFAULT_TEAM_ADMIN_POLICY = 'open'
 const HUMAN_IDS = Object.freeze(['ui', 'user', 'person'])
 
 /** 合法动作（含 setPolicy：策略变更本身也是要留痕的事件）。 */
-const ACTIONS = Object.freeze(['create', 'addMember', 'removeMember', 'setRole', 'close', 'note', 'setPolicy'])
+const ACTIONS = Object.freeze(['create', 'addMember', 'removeMember', 'setRole', 'close', 'note', 'setPolicy', 'attachRoom'])
 
 /** 结构化错误。 */
 export class TeamError extends Error {
@@ -474,6 +474,36 @@ export function createTeams(ctx, config = {}) {
 
   // ── API：读 ────────────────────────────────────────────────────────────────
 
+  /**
+   * 给团队挂上一个房间（契约 §3：团队自动配议事厅）。
+   *
+   * 幂等：同一个 roomId 再调一次 ⇒ 直接返回现有团队（rev 不变）。
+   * 房间已经存在、只是想补关联时**不重复写事件** —— 否则 `/teams` 反复保存
+   * 会把事件流刷成一条重复行，rev 也跟着虚增，页面上的「谁改了团队」就失真了。
+   * @param {{ id: string, expectedRev?: number, roomId: string, by: string, now?: number }} input
+   */
+  function attachRoom(input = {}) {
+    assertAlive('attachRoom')
+    const { id, expectedRev, roomId, by, now } = input ?? {}
+    const author = requireString(by, 'by', 'attachRoom')
+    const at = normalizeNow(now, 'attachRoom')
+    const room = requireString(roomId, 'roomId', 'attachRoom')
+    const current = cas(id, expectedRev, 'attachRoom')
+    if (current.roomId === room) {
+      return clone(current) // 幂等：已关联同一房间，不重复落事件
+    }
+    const next = clone(current)
+    next.rev = current.rev + 1
+    next.roomId = room
+    next.updatedAt = at
+    next.updatedBy = author
+    commit('attachRoom', at, author, clone(current), next)
+    info(`[cs-bots/teams] 团队 ${id} 关联房间 ${room}（by ${author}）`)
+    return clone(next)
+  }
+
+  // ── API：读 ────────────────────────────────────────────────────────────────
+
   function list(query = {}) {
     assertAlive('list')
     let rows = [...entries.values()]
@@ -515,6 +545,9 @@ export function createTeams(ctx, config = {}) {
     note,
     close,
     setPolicy,
+    // 契约 §3：把「议事厅」绑到团队上。api.js 的 ensureTeamRoom 会调它；
+    // 不导出 ⇒ 房间建好了但团队记不住 roomId，重启后自动配厅就永远重配一遍。
+    attachRoom,
     list,
     get,
     stats,

package/src/tools.js

@@ -30,7 +30,8 @@ function success(payload) {
  * 从宿主上下文取本平台的域服务。
  * @param {object} ctx
  * @returns {{ board?: object, roster?: object, room?: object, memory?: object, dispatcher?: object,
- *   todo?: object, scratch?: object, prompts?: object, discipline?: object, suggest?: object }}
+ *   todo?: object, scratch?: object, prompts?: object, discipline?: object, suggest?: object,
+ *   phaseWrite?: (taskId: string, patch: object) => object }}
  */
 function servicesOf(ctx) {
   return getServices(ctx)
@@ -258,6 +259,80 @@ const DEFS = [
     },
   },
 
+  // ── 阶段产出物（契约 §2.4，纯增量）──────────────────────────────────────────
+  {
+    name: 'bot_task_phase',
+    description:
+      '边做边交阶段产出物：每完成一个阶段就调用一次，带上这一阶段交出的文件路径/链接。' +
+      '【重要】不要等到整条任务做完才汇报 —— 阶段产物是给 Boss 点开就能看到的东西，' +
+      '分阶段交付（doing = 正在做这一阶段 / done = 这一阶段交完 / blocked = 卡在这一阶段）。' +
+      '需要 B 侧的 `services.phaseWrite(taskId, patch)` 能力；后端未注入时返回 failure，' +
+      '不会静默成功。',
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: '任务 id' },
+        index: { type: 'number', description: '阶段下标（从 0 开始，必填；越界会被后端拒）' },
+        state: {
+          type: 'string',
+          enum: ['doing', 'done', 'blocked'],
+          description: '该阶段状态（默认 done）',
+        },
+        artifacts: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '这一阶段交出的文件路径/URL（可为空数组，表示「这一阶段没产出物」）',
+        },
+        note: { type: 'string', description: '一句话说明' },
+        expectedRev: { type: 'number', description: '当前任务 rev（可选，CAS）' },
+      },
+      required: ['id', 'index'],
+      additionalProperties: false,
+    },
+    run: (s, a, exec) => {
+      // 契约 §2.4：阶段写入能力由 B 侧 installApi 挂到 services.phaseWrite。
+      // 拿不到就是拿不到 —— **绝不静默成功**，返回 failure 让调用方看见。
+      const phaseWrite = s?.phaseWrite
+      if (typeof phaseWrite !== 'function') {
+        return failure('phase-unavailable', {
+          hint: '后端未就绪：services.phaseWrite 未注入（应由 api.js 挂载）。'
+            + '请稍后重试；或先用 bot_task_update 交付总产出物。',
+        })
+      }
+      if (typeof a?.id !== 'string' || a.id === '') {
+        return failure('bad-argument', { field: 'id', hint: 'id 必填' })
+      }
+      const index = a?.index
+      if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
+        return failure('bad-argument', { field: 'index', hint: 'index 必填，且必须是 >=0 的整数' })
+      }
+      const state = a?.state === undefined ? 'done' : a.state
+      if (state !== 'doing' && state !== 'done' && state !== 'blocked') {
+        return failure('bad-argument', { field: 'state', hint: 'state 只允许 doing | done | blocked' })
+      }
+      try {
+        // `by` 由调用者身份得出（事实留痕，不猜）；`expectedRev` 若给了就带上做 CAS。
+        const res = phaseWrite(a.id, {
+          index,
+          state,
+          artifacts: a?.artifacts,
+          note: a?.note,
+          by: callerOf(exec),
+          expectedRev: a?.expectedRev,
+        })
+        if (!res || typeof res !== 'object') {
+          return failure('phase-write-failed', { message: 'phaseWrite 返回了非法结果' })
+        }
+        return res
+      } catch (error) {
+        // 写不进 task-meta.jsonl 必须让模型看见（不许吞）
+        return failure(error?.code ?? 'phase-write-failed', {
+          message: error?.message ?? String(error),
+        })
+      }
+    },
+  },
+
   // ── 唤醒桥（Dispatcher）────────────────────────────────────────────────────
   {
     name: 'bot_wake',