@chenkai114/dsh-team-admin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenkai2
+
+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

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# dsh-team-admin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 DeepSeek Harness 的「智能体团队（Agent Teams）」补一个**管理面**：在 GUI 里选任意会话，查看它的团队成员，**删除角色并清理该成员的持久会话**。
+
+## 为什么需要
+
+v0.2.x 的内置 Team roster 是 **append-only**：只能 `spawn_teammate` 加人，没有删除 / 改名 / 名字复用（见 `dsh-experimental-agent-team` 的 Known Limitations）。成员上下文耗尽、任务结束或建错时，只能"停手不理会"，名单和名额永久占着。
+
+本插件补上缺失的那一半：
+
+- 列出任意根会话的团队成员（名字、状态、描述、模型、名下任务数）
+- 删除成员：中断运行中的会话 → 成员会话目录**移入回收站** → 写墓碑，管理面标记「已删除」
+- 已删除成员集中展示，回收站路径可复制
+
+## 安装
+
+```sh
+dsh plugin --profile web add @chenkai114/dsh-team-admin
+```
+
+重启 / 重载后，打开 **设置 → 插件 → dsh-team-admin**（或插件管理页里本包的配置卡），即可看到「智能体团队管理」面板。
+
+未发布前用本地源码链接安装：
+
+```sh
+dsh plugin --profile web add link:/Users/chenkai2/data1/www/htdocs/dsh-team-admin
+```
+
+或在 profile 的 `package.json` 里手动加：
+```json
+{
+  "dependencies": { "@chenkai114/dsh-team-admin": "link:/Users/chenkai2/data1/www/htdocs/dsh-team-admin" },
+  "dsh": { "profile": { "bundles": ["...", "@chenkai114/dsh-team-admin"] } }
+}
+```
+
+![团队管理卡片](docs/images/team-admin.png)
+
+## 用法
+
+1. 搜索并选中一个会话（只列根会话）
+2. 面板显示该会话的团队成员
+3. 点某个成员的「删除」→ 行内二次确认 → 确认
+4. 成员会话进回收站，管理面把它移到「已删除」区
+
+## 删除到底做了什么
+
+| 步骤 | 行为 |
+|---|---|
+| 停止 | 运行中的成员会被中断，最多等 15s 变 inactive；超时则报错不动数据 |
+| 清理会话 | 成员会话目录 `~/.dsh/sessions/.../<memberId>/` 移到 `~/.dsh/team-admin/trash/<leadSessionId>/<memberId>-<ms>/`（**移动，不是删除**，可手工恢复） |
+| 墓碑 | 写入 `~/.dsh/team-admin/state.json`，管理面据此显示「已删除」 |
+
+## 边界（重要）
+
+- **内置团队面板仍会显示该成员**：宿主 roster 是 append-only，本插件不（也无法）从 Lead 会话日志里抹掉记录。管理面才是"已删除"的真源。
+- **名额不返还**：内置 `maxMembers` 统计的是历史成员记录，删了也占位；新角色请用新名字（`spawn_teammate`）。真需要重置名额时，fork / 新开会话换一个 Team。
+- **只删成员，不删 Lead**：`lead` 与任意根会话都不受影响。
+- **仅本机**：所有接口只接受回环地址；删除动作不会暴露到网络。
+- **不做的事**：不改内置团队工具的语义、不写 Lead 会话日志、不碰任务板（成员名下的任务仍留在任务板上，需要时用 `team_task_update` reassign）。
+
+## 配置
+
+| 变量 / 字段 | 默认 | 说明 |
+|---|---|---|
+| `DSH_TEAM_ADMIN_DATA_DIR` | `~/.dsh/team-admin` | 墓碑与回收站根目录 |
+
+## 开发
+
+```sh
+npm test          # node:test，纯本地，不依赖运行中的 dsh
+```
+
+模块划分与 HTTP 契约见 [docs/CONTRACT.md](docs/CONTRACT.md)。
+
+## 发布
+
+仓库走 GitHub Actions + npm Trusted Publishing（OIDC），与 dsh-daemon 同构：
+
+1. npm 包页面 → Settings → Trusted Publisher → GitHub Actions，填 `chenkai2` / `dsh-team-admin` / `publish.yml` / `npm-publish`
+2. 升 `package.json` 版本（同时改 `src/index.js` 的 `PLUGIN_VERSION`）→ 打 tag `vX.Y.Z` → 发 GitHub Release
+3. Actions 自动校验 tag/版本、跑测试、`npm publish --provenance --access public`
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-team-admin 打包补丁：把团队管理插件作为单条目注入 profile 根。
+# 宿主半区提供 /api/team-admin/* 路由；client 半区随宿主条目进入客户端模块表，
+# 在「插件管理 → 本包」页渲染管理卡片。
+- insert:
+    - id: team-admin
+      name: '@chenkai114/dsh-team-admin'

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@chenkai114/dsh-team-admin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "DSH 插件：GUI 管理任意会话的智能体团队 —— 查看成员、删除角色并清理其持久会话（进回收站，可恢复）",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    },
+    "requires": {
+      "dsh": ">=0.2.0-alpha.1 <0.3.0"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "agent-team",
+    "team",
+    "admin"
+  ],
+  "license": "MIT",
+  "author": "chenkai2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenkai2/dsh-team-admin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chenkai2/dsh-team-admin/issues"
+  },
+  "homepage": "https://github.com/chenkai2/dsh-team-admin#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "test:e2e": "node tests/e2e/run.mjs",
+    "test:real": "node tests/e2e/real-data.mjs",
+    "test:pack": "npm pack --dry-run"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,133 @@
+// /api/team-admin 路由分发：只做 HTTP 语义（回环校验、JSON 编解码、错误映射），
+// 业务在 team-read.mjs / dismiss.mjs。
+import { AdminError } from './error.mjs'
+
+/** 请求体上限：64KB。 */
+const BODY_MAX_BYTES = 64 * 1024
+/** 默认会话列表条数 / 上限。 */
+const DEFAULT_SESSIONS_LIMIT = 50
+const MAX_SESSIONS_LIMIT = 200
+
+/** 回环来源判定：只有本机可以操作（删除动作不可远程触发）。 */
+export function isLoopbackAddress(address) {
+  if (typeof address !== 'string') return false
+  const normalized = address.startsWith('::ffff:') ? address.slice('::ffff:'.length) : address
+  return normalized === '::1' || normalized === '127.0.0.1' || normalized.startsWith('127.')
+}
+
+/** 写 JSON 响应。 */
+function sendJson(res, status, payload) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(payload))
+}
+
+/** 读完整请求体并解析 JSON 对象。 */
+async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > BODY_MAX_BYTES) {
+      throw new AdminError('请求体超过上限', 'body-too-large', 400)
+    }
+    chunks.push(chunk)
+  }
+  const text = Buffer.concat(chunks).toString('utf8')
+  if (text.trim() === '') return {}
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new AdminError('请求体不是合法 JSON', 'bad-json', 400)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new AdminError('请求体不是合法 JSON', 'bad-json', 400)
+  }
+  return parsed
+}
+
+/** 查询串取单值。 */
+function queryValue(url, key) {
+  const value = url.searchParams.get(key)
+  return value === null || value.trim() === '' ? undefined : value.trim()
+}
+
+/** 整数查询参数（坏值回退默认）。 */
+function queryInt(url, key, fallback) {
+  const raw = queryValue(url, key)
+  if (raw === undefined) return fallback
+  const parsed = Number.parseInt(raw, 10)
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
+}
+
+/**
+ * 建路由处理器。
+ * @param {{ctx: object, getStore: () => Promise<object>, version: string, logSystem: (line: string) => void, services?: object}} deps
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void>}
+ */
+export function createApi({ ctx, getStore, version, logSystem, services }) {
+  if (services === undefined) throw new Error('createApi requires services { listTeamSessions, readTeam, dismissMember }')
+  return async function handle(req, res) {
+    try {
+      if (!isLoopbackAddress(req.socket?.remoteAddress)) {
+        sendJson(res, 403, { error: '仅允许本机访问' })
+        return
+      }
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      const path = url.pathname
+      const method = req.method ?? 'GET'
+
+      if (path === '/api/team-admin/health') {
+        if (method !== 'GET') { sendJson(res, 405, { error: '请求方法不支持' }); return }
+        sendJson(res, 200, { ok: true, name: 'team-admin', version })
+        return
+      }
+
+      if (path === '/api/team-admin/sessions') {
+        if (method !== 'GET') { sendJson(res, 405, { error: '请求方法不支持' }); return }
+        const query = queryValue(url, 'query') ?? ''
+        const limit = Math.min(queryInt(url, 'limit', DEFAULT_SESSIONS_LIMIT), MAX_SESSIONS_LIMIT)
+        const sessions = await services.listTeamSessions(ctx, { query, limit })
+        sendJson(res, 200, { sessions })
+        return
+      }
+
+      if (path === '/api/team-admin/team') {
+        if (method !== 'GET') { sendJson(res, 405, { error: '请求方法不支持' }); return }
+        const sessionId = queryValue(url, 'sessionId')
+        if (sessionId === undefined) { sendJson(res, 400, { error: '缺少 sessionId' }); return }
+        const store = await getStore()
+        sendJson(res, 200, await services.readTeam(ctx, { sessionId, store }))
+        return
+      }
+
+      if (path === '/api/team-admin/dismiss') {
+        if (method !== 'POST') { sendJson(res, 405, { error: '请求方法不支持' }); return }
+        const body = await readJsonBody(req)
+        const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : ''
+        const name = typeof body.name === 'string' ? body.name.trim() : ''
+        if (sessionId === '' || name === '') {
+          sendJson(res, 400, { error: '缺少 sessionId 或 name' })
+          return
+        }
+        const store = await getStore()
+        const result = await services.dismissMember(
+          ctx,
+          { sessionId, name, deleteSession: body.deleteSession !== false },
+          { store, logSystem },
+        )
+        sendJson(res, 200, { ok: true, ...result })
+        return
+      }
+
+      sendJson(res, 404, { error: '接口不存在' })
+    } catch (error) {
+      const status = error instanceof AdminError ? error.status : 500
+      const message = error instanceof AdminError ? error.message : '操作失败（详见服务端日志）'
+      if (!(error instanceof AdminError)) {
+        logSystem('[team-admin] ' + String(error && error.stack || error))
+      }
+      if (!res.headersSent) sendJson(res, status, { error: message })
+    }
+  }
+}