@cnbmtech/dsh-zentao-session 0.0.0-stage → 0.2.0

package/index.js

@@ -0,0 +1,755 @@
+import Schema from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createZentaoSessionClient } from './src/client.js'
+
+export const name = 'zentao-session'
+
+// credentials is injected explicitly so ZENTAO_* refs can be resolved during apply(),
+// matching the official pattern used by dsh-authorization / dsh-client-connection.
+export const inject = ['tools', 'credentials']
+
+/** 注册过程诊断记录：把被 catch 吞掉的真实错误暴露给 zentao_plugin_status 工具。 */
+const diagnostics = []
+const note = (step, ok, detail) => {
+  diagnostics.push({ step, ok, ...(detail === undefined ? {} : { detail: String(detail) }) })
+  if (diagnostics.length > 40) diagnostics.shift()
+}
+
+/**
+ * @typedef {object} Config
+ * @property {string} baseUrl    禅道地址（不含末尾斜杠）；为空时读 DSH 凭据 ZENTAO_BASE_URL 或环境变量
+ * @property {string} account    禅道账号；为空时读 DSH 凭据 ZENTAO_ACCOUNT 或环境变量
+ * @property {string} password   禅道密码；建议存 DSH 凭据 ZENTAO_PASSWORD，不要写进 cordis.patch.yml
+ * @property {number} timeoutMs  单次请求超时（毫秒）
+ * @property {number} defaultLimit 列表工具默认返回条数
+ */
+
+export const Config = Schema.object({
+  baseUrl: Schema.string()
+    .default('')
+    .description('禅道地址，例如 https://zentao.example.com（不含末尾斜杠）；为空时读 DSH 凭据 ZENTAO_BASE_URL（~/.dsh/.credentials.yaml）或环境变量。未配置时插件休眠，不影响 profile 启动。'),
+  account: Schema.string()
+    .default('')
+    .description('禅道账号；为空时读 DSH 凭据 ZENTAO_ACCOUNT 或环境变量。'),
+  password: Schema.string()
+    .default('')
+    .description('禅道密码；建议存入 DSH 凭据 ZENTAO_PASSWORD（~/.dsh/.credentials.yaml）或环境变量，不要写进 cordis.patch.yml。'),
+  timeoutMs: Schema.number()
+    .default(30000)
+    .description('单次 HTTP 请求超时（毫秒）。'),
+  defaultLimit: Schema.number()
+    .default(20)
+    .description('列表类工具默认返回条数。'),
+})
+
+function makeCredentialResolver(ctx) {
+  const service = typeof ctx.get === 'function' ? ctx.get('credentials') : undefined
+  if (!service || typeof service.resolve !== 'function') return undefined
+  return async (ref) => {
+    const hit = await service.resolve(ref)
+    return hit && typeof hit.value === 'string' && hit.value.length > 0 ? hit.value : undefined
+  }
+}
+
+/** 工具输出必须是 content block 数组（宿主会对其调用 .some 等数组方法）。 */
+function textBlock(text) {
+  return [{ type: 'text', text: String(text) }]
+}
+
+/** 工具返回值必须是 lossless JSON：丢弃 undefined、把不安全数字转成字符串。 */
+function toLosslessJson(value, seen) {
+  if (value === undefined) return undefined
+  if (value === null) return null
+  const type = typeof value
+  if (type === 'number') {
+    if (!Number.isFinite(value)) return String(value)
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) return String(value)
+    return value
+  }
+  if (type === 'string' || type === 'boolean') return value
+  if (type === 'bigint') return value.toString()
+  const guard = seen || new WeakSet()
+  if (type === 'object') {
+    if (guard.has(value)) return '[circular]'
+    guard.add(value)
+    if (value instanceof Date) return value.toISOString()
+    if (Array.isArray(value)) {
+      // 数组里的 undefined 也要消掉：宿主对 canonical value 有强制校验，null 才是合法占位
+      return value.map((item) => (item === undefined ? null : toLosslessJson(item, guard)))
+    }
+    if (value instanceof Map) return `[Map size=${value.size}]`
+    if (value instanceof Set) return `[Set size=${value.size}]`
+    const out = {}
+    for (const [key, item] of Object.entries(value)) {
+      if (item === undefined) continue
+      out[key] = toLosslessJson(item, guard)
+    }
+    return out
+  }
+  return String(value)
+}
+
+/** 包一层客户端：保证所有工具返回的值都是 lossless JSON。 */
+function wrapClientLossless(client) {
+  return new Proxy(client, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver)
+      if (typeof value !== 'function') return value
+      return async (...args) => toLosslessJson(await value.apply(target, args))
+    },
+  })
+}
+
+/** 浏览范围 → 界面/输出里的中文名（与禅道 tab 逐一对应，避免模型误解范围）。 */
+const SCOPE_LABEL = {
+  bug: { assignedTo: '指派给我', openedBy: '由我创建', resolvedBy: '由我解决', closedBy: '由我关闭' },
+  task: { assignedTo: '指派给我', openedBy: '由我创建', finishedBy: '由我完成', closedBy: '由我关闭', canceledBy: '由我取消' },
+  story: { assignedTo: '指派给我', openedBy: '我创建', reviewedBy: '我评审', closedBy: '我关闭' },
+}
+
+/** 需求所处阶段（禅道 story.stage 的取值 → 中文）。 */
+const STORY_STAGE = {
+  wait: '未开始', planned: '已计划', projected: '已立项', developing: '研发中', developed: '研发完毕',
+  testing: '测试中', tested: '测试完毕', verified: '已验收', released: '已发布', closed: '已关闭',
+}
+
+/** 列表头：说清范围与"本次只返回前 N 条"，避免把一页/一个 limit 当成全部。 */
+function listHead(kind, value, shown, unit) {
+  const scope = SCOPE_LABEL[kind]?.[value?.type] || value?.type || ''
+  const total = Number(value?.recTotal) > 0 ? Number(value.recTotal) : shown
+  const body = total > shown ? `共 ${total} 条，本次返回前 ${shown} 条` : `${shown} 条`
+  return `「${scope}」的${unit}：${body}`
+}
+
+function renderBugList(value) {
+  const rows = Array.isArray(value?.bugs) ? value.bugs : []
+  const head = listHead('bug', value, rows.length, 'BUG')
+  if (!rows.length) return textBlock(`${head}，没有符合条件的 BUG。`)
+  return textBlock([
+    `${head}：`,
+    ...rows.map((b) => `#${b.id} [${b.status}] pri=${b.pri} ${b.title}`),
+  ].join('\n'))
+}
+
+function renderTaskList(value) {
+  const rows = Array.isArray(value?.tasks) ? value.tasks : []
+  const head = listHead('task', value, rows.length, '任务')
+  if (!rows.length) return textBlock(`${head}，没有符合条件的任务。`)
+  return textBlock([
+    `${head}：`,
+    ...rows.map((t) => `#${t.id} [${t.status}] pri=${t.pri} ${t.name}`),
+  ].join('\n'))
+}
+
+function renderStoryList(value) {
+  const rows = Array.isArray(value?.stories) ? value.stories : []
+  const head = listHead('story', value, rows.length, '需求')
+  if (!rows.length) return textBlock(`${head}，没有符合条件的需求。`)
+  return textBlock([
+    `${head}：`,
+    ...rows.map((s) => `#${s.id} [${s.status}] pri=${s.pri} 阶段=${STORY_STAGE[s.stage] || s.stage || '-'} ${s.title}`),
+  ].join('\n'))
+}
+
+function renderStory(value) {
+  if (!value || !value.id) return textBlock('未取到需求信息。')
+  const s = value.story || {}
+  return textBlock([
+    `#${value.id} ${s.title || ''}`,
+    `状态=${s.status} 阶段=${STORY_STAGE[s.stage] || s.stage} 优先级=${s.pri} 指派=${s.assignedTo} 创建=${s.openedBy} ${s.openedDate || ''}`,
+    `产品=${value.productName || s.productTitle || s.product || ''} 模块=${value.modulePath || ''}`,
+    s.spec || s.desc ? `描述：${String(s.spec || s.desc).replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 300)}` : '',
+  ].filter(Boolean).join('\n'))
+}
+
+function renderBug(value) {
+  if (!value || !value.id) return textBlock('未取到BUG信息。')
+  return textBlock([
+    `#${value.id} ${value.title}`,
+    `状态=${value.status} 已确认=${value.confirmed} 类型=${value.type} 优先级=${value.pri} 指派=${value.assignedTo}`,
+    `创建=${value.openedBy} ${value.openedDate || ''}`,
+  ].join('\n'))
+}
+
+function renderWrite(value) {
+  const parts = [`已提交 #${value?.id}（HTTP ${value?.httpStatus}）`]
+  if (value?.alert) parts.push(`禅道返回提示：${value.alert}`)
+  if (value?.note) parts.push(value.note)
+  return textBlock(parts.join('\n'))
+}
+
+function renderPing(value) {
+  const story = value.myStoryCount === null || value.myStoryCount === undefined
+    ? '需求接口不可用'
+    : `我的需求 ${value.myStoryCount} 条`
+  return textBlock(`禅道连通正常：${value.baseUrl}｜我的BUG ${value.myBugCount} 条｜我的任务 ${value.myTaskCount} 条｜${story}`)
+}
+
+/**
+ * @param {ReturnType<typeof createZentaoSessionClient>} client
+ * @param {{ defaultLimit?: number }} config
+ */
+export function buildTools(rawClient, config = {}) {
+  const client = wrapClientLossless(rawClient)
+  const baseUrl = config.baseUrl || ''
+  const defaultLimit = Number(config.defaultLimit) > 0 ? Number(config.defaultLimit) : 20
+
+  const ping = defineTool({
+    name: 'zentao_ping',
+    description: '测试禅道连接：用账号密码登录并返回我的BUG/任务条数，用于验证凭据与会话是否可用。',
+    parameters: {},
+    isConcurrencySafe: () => true,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderPing(value),
+    },
+    async execute(_args, exec) {
+      return client.ping({ signal: exec && exec.signal })
+    },
+  })
+
+  const myBugs = defineTool({
+    name: 'zentao_my_bugs',
+    description: '列出当前禅道账号的BUG（"我的 Bug"），返回 id、标题、状态、优先级、类型等。用户问"我有哪些 Bug/BUG"时使用；默认范围是"指派给我"。',
+    parameters: {
+      limit: { type: 'integer', description: `返回条数上限，默认 ${defaultLimit}，0 表示全部。` },
+      type: { type: 'string', description: '范围（默认 assignedTo）：assignedTo=指派给我，openedBy=由我创建，resolvedBy=由我解决，closedBy=由我关闭。' },
+    },
+    isConcurrencySafe: () => true,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderBugList(value),
+    },
+    async execute(args, exec) {
+      const limit = Number.isFinite(args?.limit) ? Number(args.limit) : defaultLimit
+      return client.myBugs({ type: args?.type, limit, signal: exec && exec.signal })
+    },
+  })
+
+  const myTasks = defineTool({
+    name: 'zentao_my_tasks',
+    description: '列出当前禅道账号的任务（"我的任务"），返回 id、名称、状态、优先级、预计/已耗工时、截止日期等；默认范围是"指派给我"。',
+    parameters: {
+      limit: { type: 'integer', description: `返回条数上限，默认 ${defaultLimit}，0 表示全部。` },
+      type: { type: 'string', description: '范围（默认 assignedTo）：assignedTo=指派给我，openedBy=由我创建，finishedBy=由我完成，closedBy=由我关闭，canceledBy=由我取消。' },
+    },
+    isConcurrencySafe: () => true,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderTaskList(value),
+    },
+    async execute(args, exec) {
+      const limit = Number.isFinite(args?.limit) ? Number(args.limit) : defaultLimit
+      return client.myTasks({ type: args?.type, limit, signal: exec && exec.signal })
+    },
+  })
+
+  const myStories = defineTool({
+    name: 'zentao_my_stories',
+    description: '列出当前禅道账号的需求（"我的需求"），返回 id、标题、状态、阶段、优先级、创建/指派等。默认范围是"指派给我"；多数账号更常用 reviewedBy=我评审、openedBy=我创建。',
+    parameters: {
+      limit: { type: 'integer', description: `返回条数上限，默认 ${defaultLimit}，0 表示全部。` },
+      type: { type: 'string', description: '范围（默认 assignedTo）：assignedTo=指派给我，openedBy=我创建，reviewedBy=我评审，closedBy=我关闭。' },
+    },
+    isConcurrencySafe: () => true,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderStoryList(value),
+    },
+    async execute(args, exec) {
+      const limit = Number.isFinite(args?.limit) ? Number(args.limit) : defaultLimit
+      return client.myStories({ type: args?.type, limit, signal: exec && exec.signal })
+    },
+  })
+
+  const storyView = defineTool({
+    name: 'zentao_story_view',
+    description: '按 ID 读取一条禅道需求的完整详情（标题、状态、阶段、优先级、产品/模块、描述、相关人与操作历史）。',
+    parameters: {
+      id: { type: 'string', required: true, description: '需求 ID，例如 13126。' },
+    },
+    isConcurrencySafe: () => true,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderStory(value),
+    },
+    async execute(args, exec) {
+      return client.storyFull({ id: args.id, signal: exec && exec.signal })
+    },
+  })
+
+  const bugView = defineTool({
+    name: 'zentao_bug_view',
+    description: '按 ID 读取一条禅道BUG的详情（状态、是否已确认、类型、优先级、指派人、解决情况、重现步骤）。',
+    parameters: {
+      id: { type: 'string', required: true, description: 'BUG ID，例如 200601。' },
+    },
+    isConcurrencySafe: () => true,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderBug(value),
+    },
+    async execute(args, exec) {
+      return client.bugView({ id: args.id, signal: exec && exec.signal })
+    },
+  })
+
+  const bugConfirm = defineTool({
+    name: 'zentao_bug_confirm',
+    description: '确认一条禅道BUG（把"是否确认"置为已确认）。注意：禅道确认只设置 confirmed=1，BUG状态仍为 active（激活/待解决），这是正常语义。可选附带确认说明。',
+    parameters: {
+      id: { type: 'string', required: true, description: 'BUG ID。' },
+      comment: { type: 'string', description: '可选的确认说明（写入该操作的备注）。' },
+    },
+    isConcurrencySafe: () => false,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderWrite(value),
+    },
+    async execute(args, exec) {
+      return client.bugConfirm({ id: args.id, comment: args.comment, signal: exec && exec.signal })
+    },
+  })
+
+  const bugComment = defineTool({
+    name: 'zentao_bug_comment',
+    description: '给一条禅道BUG添加备注（回复）。用户常见的三段式格式为「问题原因：…／解决方案：…／解决时间：…」，段间保留空行。注意：该版本禅道不支持删除备注。',
+    parameters: {
+      id: { type: 'string', required: true, description: 'BUG ID。' },
+      comment: { type: 'string', required: true, description: '备注正文，可含换行。' },
+    },
+    isConcurrencySafe: () => false,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => renderWrite(value),
+    },
+    async execute(args, exec) {
+      return client.bugComment({ id: args.id, comment: args.comment, signal: exec && exec.signal })
+    },
+  })
+
+  const status = defineTool({
+    name: 'zentao_plugin_status',
+    description: '读取禅道插件的注册诊断信息：可选服务（connection / webServer）是否可见、RPC 通道与 HTTP 路由的注册结果及真实错误。侧边栏面板取数失败时用它排查。',
+    parameters: {},
+    isConcurrencySafe: () => true,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => textBlock(
+        [
+          `baseUrl=${value.baseUrl || '-'}`,
+          // 面板当前可用通道：RPC 在本版宿主注册失败是已知现象，HTTP 前缀路由才是实际通道
+          `面板数据通道=${(value.diagnostics || []).some((i) => i.step === 'http.registered' && i.ok) ? 'HTTP 前缀路由（可用）' : '不可用'}｜RPC=${(value.diagnostics || []).some((i) => i.step === 'rpc.registered' && i.ok) ? '已注册' : '未注册（本版 connection.rpc.handle 报 webServer 注入错误，已知现象）'}`,
+          ...(value.diagnostics || []).map((item) => `${item.ok ? '[ok]' : '[FAIL]'} ${item.step}${item.detail ? ` :: ${item.detail}` : ''}`),
+        ].join('\n')
+      ),
+    },
+    async execute() {
+      return { diagnostics: diagnostics.slice(), baseUrl }
+    },
+  })
+
+  return [ping, myBugs, myTasks, myStories, bugView, storyView, bugConfirm, bugComment, status]
+}
+
+/** 写操作集合：RPC 通道与 HTTP 通道必须共用，否则两条路径对同一请求的处理不一致。 */
+const WRITE_ACTIONS = new Set(['confirm', 'comment', 'bugaction', 'login', 'logout'])
+
+export async function apply(ctx, config) {
+  try {
+    const settings = config || {}
+    const resolveCredential = makeCredentialResolver(ctx)
+    const credentials = (ctx && typeof ctx.get === 'function' ? ctx.get('credentials') : undefined) || (ctx && ctx.credentials)
+    if (credentials) note('credentials.service', true, `set=${typeof credentials.set} unset=${typeof credentials.unset}`)
+    else note('credentials.service', false, 'credentials 服务不可用，登录后无法保存凭据')
+
+    const baseUrl = settings.baseUrl
+      || (resolveCredential ? await resolveCredential('ZENTAO_BASE_URL') : undefined)
+      || process.env.ZENTAO_BASE_URL
+      || ''
+    // 说明：没有 baseUrl 时**不再休眠**——否则首次安装时面板无法弹出登录卡片。
+    // 工具与路由照常注册，未登录期间由 dynamicClient 给出明确提示。
+    if (!baseUrl) note('apply.pending-login', true, '尚未配置 baseUrl，等待在面板中登录')
+
+    const resolveAccount = async () => settings.account
+      || (resolveCredential ? await resolveCredential('ZENTAO_ACCOUNT') : undefined)
+      || process.env.ZENTAO_ACCOUNT
+      || ''
+    const resolvePassword = async () => settings.password
+      || (resolveCredential ? await resolveCredential('ZENTAO_PASSWORD') : undefined)
+      || process.env.ZENTAO_PASSWORD
+      || ''
+
+    // 客户端可热替换：首次登录/切换账号后重建，工具与路由都通过 holder 取当前实例。
+    const holder = {
+      baseUrl,
+      client: createZentaoSessionClient({
+        baseUrl: baseUrl || 'http://127.0.0.1',
+        timeoutMs: settings.timeoutMs,
+        resolveAccount,
+        resolvePassword,
+      }),
+    }
+    const NEED_LOGIN = '尚未配置禅道地址，请在侧边栏「禅道」面板中登录'
+
+    const dynamicClient = new Proxy({}, {
+      get(_target, prop) {
+        if (!holder.baseUrl) {
+          return async () => { throw new Error(NEED_LOGIN) }
+        }
+        const current = holder.client
+        const value = current[prop]
+        return typeof value === 'function' ? (...args) => value.apply(current, args) : value
+      },
+    })
+
+    const tools = buildTools(dynamicClient, { ...settings, baseUrl })
+    for (const tool of tools) ctx.tools.register(tool)
+    note('apply', true, `baseUrl=${baseUrl} tools=${tools.length}`)
+    ctx.logger?.info?.(`[zentao-session] 已注册 ${tools.length} 个禅道工具，baseUrl=${baseUrl}`)
+
+    // 模型侧说明段：告诉模型这些工具何时用、未登录怎么办。
+    // systemPrompt 是可选服务——缺失时插件其余能力照常工作，所以走 ctx.inject 而不是 inject 必填项。
+    ctx.inject(['systemPrompt'], (promptCtx) => {
+      try {
+        const systemPrompt = promptCtx?.systemPrompt
+          || (typeof promptCtx?.get === 'function' ? promptCtx.get('systemPrompt') : undefined)
+        if (!systemPrompt || typeof systemPrompt.section !== 'function') {
+          note('systemPrompt.unavailable', false, 'systemPrompt.section 不可用')
+          return
+        }
+        // 放在工具类段落带里（MCP_SERVERS=3100 之后），紧跟内置工具说明
+        const base = typeof systemPrompt.getSectionOrder === 'function'
+          ? systemPrompt.getSectionOrder('MCP_SERVERS')
+          : undefined
+        const order = (Number.isFinite(base) ? base : 3100) + 1
+        const register = () => systemPrompt.section({
+          name: 'tool:zentao-session',
+          order,
+          text: "## ZenTao (禅道) work items\n\nThe `zentao_*` tools read and update this user's ZenTao items through a session login saved in the DSH credential store:\n- `zentao_my_bugs` / `zentao_my_tasks` / `zentao_my_stories` list the user's items; each accepts `type` for the browse scope (`assignedTo` = 指派给我 by default; also openedBy / resolvedBy / reviewedBy / finishedBy / closedBy / canceledBy depending on the kind).\n- `zentao_bug_view` / `zentao_story_view` read one item in full (status, priority, steps or spec, related people, action history).\n- `zentao_bug_confirm` and `zentao_bug_comment` write back: confirm a bug, or append a remark.\n\nUse them when the user asks about their own bugs, tasks or stories (「我的 BUG/任务/需求」), names a ZenTao item id (for example 200601), or asks to confirm an item or add a 备注; read the real item instead of guessing. If a tool reports that ZenTao is not configured or not logged in, ask the user to sign in once in the sidebar 「禅道」 panel. This ZenTao version cannot delete remarks, and a remark is public in the item history — never post one the user did not ask for.",
+        })
+        // 与路由同理：注册挂在插件自身的 ctx.effect 上，避免派生上下文回收时段落一起消失
+        if (typeof ctx.effect === 'function') ctx.effect(register, 'dsh-zentao-session: system prompt section')
+        else register()
+        note('systemPrompt.registered', true, `order=${order}`)
+      } catch (error) {
+        note('systemPrompt.register-failed', false, error?.message || error)
+      }
+    })
+
+    // 侧边栏面板的数据接口。
+    // 主通道走 connection.rpc（官方机制，桌面版 Electron 的 fetch 走 IPC 桥，自建 HTTP 路由到不了）；
+    // 另注册一条 HTTP 前缀路由，供纯浏览器部署使用。两者共用同一个 dispatch。
+    // connection / webServer 都是可选服务，缺失时插件照常工作（不进 inject 必填项，避免卡启动）。
+    const RPC_CHANNEL = '/dsh-zentao-session'
+
+    const dispatch = async (action, { query, body } = {}) => {
+      const get = (key) => (query && typeof query.get === 'function' ? query.get(key) : undefined) ?? (body ? body[key] : undefined)
+      if (action === '' || action === 'summary') return { ok: true, baseUrl: holder.baseUrl, ...(await holder.client.ping({})) }
+      // 列表类都接受 type（浏览范围）：assignedTo/openedBy/... 与禅道 tab 一致
+      if (action === 'bugs') return { ok: true, baseUrl: holder.baseUrl, ...(await holder.client.myBugs({ type: get('type') })) }
+      if (action === 'tasks') return { ok: true, baseUrl: holder.baseUrl, ...(await holder.client.myTasks({ type: get('type') })) }
+      if (action === 'stories') return { ok: true, baseUrl: holder.baseUrl, ...(await holder.client.myStories({ type: get('type') })) }
+      if (action === 'bug') {
+        const id = get('id')
+        if (!id) return { ok: false, error: '缺少 id 参数' }
+        return { ok: true, baseUrl: holder.baseUrl, bug: await holder.client.bugView({ id }) }
+      }
+      if (action === 'bugfull') {
+        const id = get('id')
+        if (!id) return { ok: false, error: '缺少 id 参数' }
+        const sid = await holder.client.currentSessionId({}).catch(() => '')
+        return { ok: true, sid, ...(await holder.client.bugFull({ id })) }
+      }
+      if (action === 'taskfull') {
+        const id = get('id')
+        if (!id) return { ok: false, error: '缺少 id 参数' }
+        const sid = await holder.client.currentSessionId({}).catch(() => '')
+        return { ok: true, sid, ...(await holder.client.taskFull({ id })) }
+      }
+      if (action === 'storyfull') {
+        const id = get('id')
+        if (!id) return { ok: false, error: '缺少 id 参数' }
+        const sid = await holder.client.currentSessionId({}).catch(() => '')
+        return { ok: true, sid, ...(await holder.client.storyFull({ id })) }
+      }
+      if (action === 'confirm') {
+        if (!body || !body.id) return { ok: false, error: '缺少 id' }
+        return { ok: true, baseUrl: holder.baseUrl, result: await holder.client.bugConfirm({ id: body.id, comment: body.comment }) }
+      }
+      if (action === 'comment') {
+        if (!body || !body.id || !body.comment) return { ok: false, error: '缺少 id 或 comment' }
+        return { ok: true, baseUrl: holder.baseUrl, result: await holder.client.bugComment({ id: body.id, comment: body.comment }) }
+      }
+      // ── 登录态 ─────────────────────────────────────────────────────────────
+      if (action === 'auth') {
+        const account = await resolveAccount()
+        if (!holder.baseUrl) return { ok: true, authenticated: false, baseUrl: '', account, error: '尚未配置禅道地址' }
+        try {
+          const info = await holder.client.ping({})
+          const sid = await holder.client.currentSessionId({}).catch(() => '')
+          return { ok: true, authenticated: true, baseUrl: holder.baseUrl, account, sid, ...info }
+        } catch (error) {
+          return { ok: true, authenticated: false, baseUrl: holder.baseUrl, account, error: String(error?.message || error) }
+        }
+      }
+      if (action === 'login') {
+        const targetBase = String((body && body.baseUrl) || '').trim().replace(/\/+$/, '')
+        const targetAccount = String((body && body.account) || '').trim()
+        const targetPassword = String((body && body.password) || '')
+        if (!targetBase || !targetAccount || !targetPassword) return { ok: false, error: '请填写禅道地址、账号与密码' }
+        const info = await holder.client.login({ baseUrl: targetBase, account: targetAccount, password: targetPassword })
+        const saved = []
+        const saveErrors = []
+        if (credentials && typeof credentials.set === 'function') {
+          // 凭据存进 DSH 凭据库（~/.dsh/.credentials.yaml），不进任何配置文件
+          const pairs = [
+            ['ZENTAO_BASE_URL', targetBase],
+            ['ZENTAO_ACCOUNT', targetAccount],
+            ['ZENTAO_PASSWORD', targetPassword],
+          ]
+          for (const [ref, value] of pairs) {
+            try {
+              await credentials.set(ref, value)
+              saved.push(ref)
+            } catch (error) {
+              saveErrors.push(`${ref}: ${String(error?.message || error)}`)
+            }
+          }
+          note('login.save', saveErrors.length === 0, saveErrors.length ? saveErrors.join(' | ') : saved.join(','))
+        } else {
+          saveErrors.push('credentials 服务不可用，本次登录仅在内存生效')
+        }
+        holder.baseUrl = targetBase
+        holder.client = createZentaoSessionClient({
+          baseUrl: targetBase,
+          timeoutMs: settings.timeoutMs,
+          resolveAccount,
+          resolvePassword,
+        })
+        // 账号脱敏：诊断信息会作为工具输出展示给模型
+        const masked = targetAccount.length > 2 ? `${targetAccount.slice(0, 2)}***` : '***'
+        note('login', true, `baseUrl=${targetBase} account=${masked} 已保存=${saved.length}`)
+        return { ok: true, authenticated: true, baseUrl: targetBase, account: targetAccount, saved, saveErrors, ...info }
+      }
+      if (action === 'logout') {
+        if (credentials && typeof credentials.unset === 'function') {
+          for (const ref of ['ZENTAO_PASSWORD']) {
+            try { await credentials.unset(ref) } catch (error) { note('logout.unset-failed', false, String(error?.message || error)) }
+          }
+        }
+        holder.client = createZentaoSessionClient({
+          baseUrl: holder.baseUrl || 'http://127.0.0.1',
+          timeoutMs: settings.timeoutMs,
+          resolveAccount: async () => '',
+          resolvePassword: async () => '',
+        })
+        note('logout', true)
+        return { ok: true, authenticated: false, baseUrl: holder.baseUrl }
+      }
+      // ── 禅道操作表单（确认/解决/关闭/激活/指派/编辑） ────────────────────────
+      if (action === 'bugops') {
+        const id = get('id')
+        if (!id) return { ok: false, error: '缺少 id 参数' }
+        return { ok: true, ...(await holder.client.bugOps({ id })) }
+      }
+      if (action === 'bugform') {
+        const id = get('id')
+        const op = get('op')
+        if (!id || !op) return { ok: false, error: '缺少 id 或 op' }
+        return { ok: true, ...(await holder.client.bugForm({ id, op })) }
+      }
+      if (action === 'bugaction') {
+        if (!body || !body.id || !body.op) return { ok: false, error: '缺少 id 或 op' }
+        const result = await holder.client.bugAction({ id: body.id, op: body.op, values: body.values || {} })
+        note('bugaction', true, `op=${body.op} id=${body.id}`)
+        return { ok: true, baseUrl: holder.baseUrl, result }
+      }
+      return { ok: false, error: `未知操作：${action}` }
+    }
+
+    const guard = async (action, options) => {
+      try {
+        return toLosslessJson(await dispatch(action, options))
+      } catch (error) {
+        // 运行时失败必须留在宿主日志里（诊断只覆盖注册阶段）
+        try { ctx.logger?.warn?.(`[zentao-session] action=${action} 失败：${error?.stack || error?.message || error}`) } catch { /* 忽略 */ }
+        return { ok: false, baseUrl: holder.baseUrl, error: String(error?.message || error) }
+      }
+    }
+
+    // ① RPC 通道（主通道）
+    ctx.inject(['connection'], (connCtx) => {
+      note('rpc.inject-fired', true)
+      try {
+        const connection = connCtx?.connection
+          || (typeof connCtx?.get === 'function' ? connCtx.get('connection') : undefined)
+        const rpc = connection && connection.rpc
+        note('rpc.service', !!connection, `connection=${!!connection} rpc=${!!rpc} handle=${typeof rpc?.handle}`)
+        if (!rpc || typeof rpc.handle !== 'function') {
+          ctx.logger?.warn?.('[zentao-session] connection.rpc 不可用，侧边栏面板将退回 HTTP 接口')
+          return
+        }
+        const handler = async (endpoint, payload) => {
+          const body = payload && typeof payload === 'object' ? payload : {}
+          // 写操作必须整包传 body：旧写法只认 confirm/comment，会让
+          // bugaction/login/logout 被拍平成 query（嵌套 values 变 "[object Object]"）。
+          const isWrite = WRITE_ACTIONS.has(endpoint)
+          return guard(endpoint, { body: isWrite ? body : undefined, query: isWrite ? undefined : new URLSearchParams(body) })
+        }
+        // 与 HTTP 路由同理：注册必须挂在插件自身的 ctx.effect 上，
+        // 不能挂在 inject 回调的派生上下文上（回调返回后可能连同路由一起被回收）。
+        if (typeof ctx.effect === 'function') ctx.effect(() => rpc.handle(RPC_CHANNEL, handler), 'dsh-zentao-session: rpc channel')
+        else rpc.handle(RPC_CHANNEL, handler)
+        note('rpc.registered', true, RPC_CHANNEL)
+        ctx.logger?.info?.(`[zentao-session] 已注册 RPC 通道 ${RPC_CHANNEL}`)
+      } catch (error) {
+        note('rpc.register-failed', false, error?.message || error)
+        ctx.logger?.warn?.(`[zentao-session] RPC 通道注册失败（不影响工具）：${error?.message || error}`)
+      }
+    })
+
+    // ② HTTP 前缀路由（浏览器部署备用）。注意宿主前缀匹配规则是
+    //    `pathname === prefix || pathname.startsWith(prefix + '/')`，所以 path 不能带尾斜杠。
+    ctx.inject(['webServer'], (webCtx) => {
+      note('http.inject-fired', true)
+      try {
+        const webServer = webCtx?.webServer
+          || (typeof webCtx?.get === 'function' ? webCtx.get('webServer') : undefined)
+        note('http.service', !!webServer, `webServer=${!!webServer} register=${typeof webServer?.register} port=${webServer?.port}`)
+        if (!webServer || typeof webServer.register !== 'function') return
+
+        const WRITE_HEADER = 'x-dsh-zentao-session'
+        const readJsonBody = (req) => new Promise((resolve) => {
+          let raw = ''
+          let done = false
+          const finish = (value) => { if (!done) { done = true; resolve(value) } }
+          req.on('data', (chunk) => {
+            raw += chunk
+            // 超限：立刻判定并 settle，否则 destroy 之后 'end' 不会触发，Promise 永久挂起
+            if (raw.length > 65536) {
+              // 先回 413 再断开：只 destroy 不发响应，调用方只会看到连接被重置
+              try {
+                res.writeHead(413, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+                res.end(JSON.stringify({ ok: false, error: '请求体过大（上限 64KB）' }))
+              } catch { /* 忽略 */ }
+              req.destroy()
+              finish({})
+            }
+          })
+          req.on('end', () => {
+            try { finish(raw ? JSON.parse(raw) : {}) } catch { finish({}) }
+          })
+          req.on('error', () => finish({}))
+          req.on('close', () => finish({}))
+        })
+
+        const handler = async (req, res) => {
+          const send = (payload, status = 200) => {
+            try {
+              res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+              res.end(JSON.stringify(toLosslessJson(payload)))
+            } catch (error) {
+              ctx.logger?.warn?.(`[zentao-session] 响应写出失败：${error?.message || error}`)
+            }
+          }
+          // 回环栅栏：只接受本机 Host（防 DNS rebinding 把本接口当成可跨站读取的同源资源）
+          const host = String(req.headers.host || '').toLowerCase()
+          if (host && !/^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/.test(host)) {
+            send({ ok: false, error: '仅允许本机访问' }, 403)
+            return
+          }
+          if (req.method !== 'GET' && req.method !== 'HEAD' && req.method !== 'POST') {
+            send({ ok: false, error: `不支持的方法：${req.method}` }, 405)
+            return
+          }
+          // 所有 action 都要求自定义头（读也一样）：这是本插件唯一的访问控制。
+          // 自定义头会触发 CORS 预检，跨站页面无法伪造；也避免裸 GET 触发真实登录。
+          if (req.headers[WRITE_HEADER] !== '1') {
+            send({ ok: false, error: `需要请求头 ${WRITE_HEADER}: 1` }, 403)
+            return
+          }
+          let action = ''
+          let query = new URLSearchParams('')
+          try {
+            const parsed = new URL(req.url || '/', 'http://127.0.0.1')
+            action = parsed.pathname.replace(/^\/api\/dsh-zentao-session\/?/, '').replace(/\/+$/, '')
+            query = parsed.searchParams
+          } catch { /* 保留默认空 action */ }
+
+          const body = req.method === 'POST' ? await readJsonBody(req) : undefined
+          send(await guard(action, { query, body }))
+        }
+
+        const route = { kind: 'prefix', path: '/api/dsh-zentao-session', handler }
+        try {
+          // 用插件自身的 ctx.effect（而非注入回调里的派生上下文）：后者可能在回调返回后随即销毁，
+          // 会把刚注册的路由一并回收——这是上一轮「路由不生效」的怀疑根因。
+          if (typeof ctx.effect === 'function') ctx.effect(() => webServer.register(route), 'dsh-zentao-session: api routes')
+          else webServer.register(route)
+          note('http.registered', true, route.path)
+          ctx.logger?.info?.('[zentao-session] 已注册 HTTP 前缀路由 /api/dsh-zentao-session')
+        } catch (error) {
+          note('http.register-failed', false, error?.message || error)
+          ctx.logger?.warn?.(`[zentao-session] HTTP 路由注册失败：${error?.message || error}`)
+        }
+
+        // 截图/附件代理：只放行禅道 /file-read-* 与 /file-download-* 路径，且仅回图片/PDF。
+        // 面板里的 <img src> 直接用它，绕开跨站 Cookie 限制（本机回环 + 路径白名单）。
+        const fileRoute = {
+          kind: 'prefix',
+          path: '/api/dsh-zentao-session-file',
+          handler: async (req, res) => {
+            const respond = (status, contentType, payload, extraHeaders = {}) => {
+              try {
+                res.writeHead(status, {
+                  'content-type': contentType,
+                  // 错误响应不缓存：否则会话恢复后坏图会继续坏 5 分钟
+                  'cache-control': status === 200 ? 'private, max-age=300' : 'no-store',
+                  'x-content-type-options': 'nosniff',
+                  ...extraHeaders,
+                })
+                res.end(payload)
+              } catch (error) {
+                ctx.logger?.warn?.(`[zentao-session] 文件响应写出失败：${error?.message || error}`)
+              }
+            }
+            // HEAD 会白跑一次完整上游取数，没有意义
+            if (req.method !== 'GET') {
+              respond(405, 'text/plain; charset=utf-8', 'method not allowed')
+              return
+            }
+            try {
+              const parsed = new URL(req.url || '/', 'http://127.0.0.1')
+              const file = await holder.client.fetchFile({ path: parsed.searchParams.get('path') || '' })
+              // 只放行位图与 PDF：SVG 属于可执行文档，本路由与 DSH 同源，放行等于给出同源脚本执行面
+              const allowed = ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/bmp', 'application/pdf']
+              if (!allowed.includes(file.contentType)) {
+                respond(415, 'text/plain; charset=utf-8', 'unsupported media type')
+                return
+              }
+              respond(200, file.contentType, file.buffer)
+            } catch (error) {
+              // 对外只给通用文案，细节进日志（避免回显上游 URL / 内部错误）
+              ctx.logger?.warn?.(`[zentao-session] 取文件失败：${error?.message || error}`)
+              respond(404, 'text/plain; charset=utf-8', 'file unavailable')
+            }
+          },
+        }
+        try {
+          if (typeof ctx.effect === 'function') ctx.effect(() => webServer.register(fileRoute), 'dsh-zentao-session: file route')
+          else webServer.register(fileRoute)
+          note('http.file-route', true, fileRoute.path)
+        } catch (error) {
+          note('http.file-route-failed', false, error?.message || error)
+        }
+      } catch (error) {
+        note('http.block-failed', false, error?.message || error)
+        ctx.logger?.warn?.(`[zentao-session] HTTP 接口注册失败（不影响工具）：${error?.message || error}`)
+      }
+    })
+  } catch (error) {
+    // Never let initialization failures abort the profile boot.
+    ctx.logger?.warn?.(`[zentao-session] 初始化失败，插件保持休眠：${error?.message || error}`)
+  }
+}