@hupan56/wlkj 3.0.0 → 3.1.3

package/templates/qoder/scripts/protocol/mcp/zentao_mcp_server.py

@@ -0,0 +1,1920 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+"""ZenTao (禅道) MCP Server - 对接禅道项目管理, 替代本地 task。
+
+禅道自建内网开源版 REST API (v1, 开源版 16.5+)。
+禅道为唯一事实源; /wl-task 的底层走禅道, 本地 task.json 仅作离线缓存。
+
+工具按禅道资源分组 (产品/计划/版本/需求/项目/执行/任务/Bug/用户):
+  - 产品: list_products, get_product, create_product, update_product, delete_product
+  - 计划: list_plans, get_plan, create_plan, link_story_to_plan, unlink_story_from_plan, ...
+  - 版本: list_builds, get_build, create_build, link_story_to_build, link_bug_to_build
+  - 需求: list_stories, get_story_detail, create_story, update_story, assign_story, ...
+  - 任务: list_tasks, get_task, create_task, start/pause/restart/finish/close_task, log_effort
+  - Bug:  list_bugs, get_bug, create_bug, confirm/resolve/activate/close_bug, ...
+  - 用户: list_users, get_user
+  - 辅助: check_zentao_status, get_zentao_url
+
+v3.1: 迁移到 @tool 装饰器模式 (元类自动收集 TOOLS + 自动分发), 消除 if-elif 链。
+
+认证: 用户名密码 → token (config.yaml zentao 段配, 团队共享; 真值不进源码)
+"""
+import os
+import sys
+import json
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+# 配置 (真值只在 config.yaml, 由 mcp_launcher 注入 env; 此处不留明文 fallback)
+# 对齐 mysql_mcp_server 风格: 未配置就报清晰错误, 不硬编码凭据(避免随 npm 包泄露)
+# ZENTAO_USER/PASSWORD 由 ZentaoClient.from_env() 直接从 env 读取, 不留模块级变量。
+ZENTAO_URL = os.environ.get('ZENTAO_URL', '')  # 部分 tool (get_zentao_url) 直接引用
+# 当前开发者的禅道账号 (mcp_launcher 从 member.json 注入)。禅道是共享账号,
+# 靠此区分"谁在操作" → list 默认只看我的, 写操作可校验归属。未注入则为空
+# (兼容独立运行/旧环境), 此时 list 不过滤, 退回旧行为。
+MY_ACCOUNT = os.environ.get('ZENTAO_MY_ACCOUNT', '')
+
+# ★ 自修复: launcher 没注入 ZENTAO_MY_ACCOUNT 时, server 自己从 developer 身份读。
+# 原因: 旧版 launcher / 缓存的 launcher 进程可能不注入此变量 → 归属过滤全失效
+# (list 把全队任务都拉回来, 标记 [我]/[队友] 也错乱)。本段让 server 自给自足。
+if not MY_ACCOUNT:
+    try:
+        from foundation.core.paths import get_developer
+        from foundation.identity.identity import get_member
+        _dev = get_developer()
+        if _dev:
+            _mem = get_member(_dev)
+            if _mem:
+                _acc = (_mem.get('zentao_account') or '').strip()
+                if _acc:
+                    MY_ACCOUNT = _acc
+                    os.environ['ZENTAO_MY_ACCOUNT'] = _acc
+    except Exception:
+        pass  # 读不到就保持空, 退回旧行为(不过滤)
+
+# ── 禅道客户端 (HTTP 逻辑收敛在 common.zentao_client.ZentaoClient，与 zentao_sync 共享同一份) ──
+# ZENTAO_URL / MY_ACCOUNT 保留为模块级常量：部分 tool 直接引用 (get_zentao_url / 归属过滤)。
+# PING_HOST/PING_PORT 不再需要（client 内部解析）。
+# stdout 重定向 + 协议层由 BaseMCPServer 接管 (v3.0 重构)。
+from foundation.integrations.zentao_client import ZentaoClient
+
+CLIENT = ZentaoClient.from_env()
+
+
+def check_intranet():
+    """内网连通性 (委托 ZentaoClient)。CLIENT 未配置时直接判不通。"""
+    if CLIENT is None:
+        return False, '禅道凭据未配置，无法探测连通性。'
+    return CLIENT.check_intranet()
+
+
+def _check_credentials():
+    """凭据完整性 (委托 ZentaoClient)。"""
+    if CLIENT is None:
+        return False, ('禅道凭据未注入 (ZENTAO_URL/USER/PASSWORD)。'
+                       '请检查 mcp_launcher / .qoder/config.yaml 的 zentao 段，重启 MCP 生效。')
+    ok, msg = CLIENT.credentials_ok()
+    if not ok:
+        return False, msg + ' 重启 MCP 生效。'
+    return True, ''
+
+
+def _api(method, path, data=None):
+    """调禅道 API (委托 ZentaoClient，含 401 自动重登)。_gate 已挡 CLIENT=None。"""
+    return CLIENT.api(method, path, data)
+
+
+def _upload_file(file_path, title='', extra_fields=None):
+    """上传文件到禅道 (multipart)。_gate 已挡 CLIENT=None。"""
+    return CLIENT.upload_file(file_path, title=title, extra_fields=extra_fields)
+
+
+def _err_text(r):
+    """从 response 提取错误文本 (委托 ZentaoClient)。"""
+    return ZentaoClient.err_text(r)
+
+
+# ── MCP Server (继承 BaseMCPServer, @tool 装饰器自动分发) ──────────────
+
+from foundation.protocol.mcp_base import BaseMCPServer, tool
+
+
+def _assignee_account(item):
+    """从任务/Bug 提取指派人账号 (兼容禅道两种返回格式)。
+
+    禅道 API 的 assignedTo 可能是:
+      - dict: {'id':14,'account':'zhengkang','realname':'郑康'} (列表接口常见)
+      - str: 'zhengkang' (详情接口常见)
+      - None/其它: 返回空串
+    旧代码用 str(dict)==account 比较, 永远匹配不上 → 过滤全失效。本函数统一取 account。
+    """
+    a = item.get('assignedTo') if isinstance(item, dict) else None
+    if isinstance(a, dict):
+        return str(a.get('account', ''))
+    if isinstance(a, str):
+        return a
+    return ''
+
+
+def _openedby_account(item):
+    """从任务/Bug 提取创建人账号 (openedBy 字段, 同 _assignee_account 的兼容逻辑)。
+
+    用途: Bug 的归属判定 —— 团队习惯提了 bug 不指派 (assignedTo=None), bug 留在创建人头上。
+    "我的 bug" 应包含 openedBy==我 (我提的), 不能只认 assignedTo。
+    openedBy 在禅道里通常是字符串 (账号), 兼容 dict 格式。
+    """
+    o = item.get('openedBy') if isinstance(item, dict) else None
+    if isinstance(o, dict):
+        return str(o.get('account', ''))
+    if isinstance(o, str):
+        return o
+    return ''
+
+
+class ZentaoMCPServer(BaseMCPServer):
+    """禅道 MCP Server。
+
+    v3.1: 每个工具用 @tool 装饰, 元类自动收集 TOOLS + 自动 handle_tool 分发。
+    新增工具 = 加一个 @tool 方法, 无需改 TOOLS 列表或 if 链。
+
+    健壮性三道门 (复用现有模式, 推广到全部工具):
+      ① 内网不通 → check_intranet 友好提示, 不崩
+      ② 凭据未配 → _check_credentials 友好提示
+      ③ 写操作失败 → 返回 ⚠️ 不抛异常 (权限不足/字段缺失不影响其它操作)
+    """
+
+    SERVER_NAME = "qoder-zentao"
+    SERVER_VERSION = "1.1.0"
+
+    # ── 复用辅助方法 (消除工具样板重复, 仿 mysql _execute_query) ───────
+
+    def _gate(self):
+        """三道门: 内网 + 凭据。不通返回提示字符串, 通返回 None。"""
+        ok, msg = check_intranet()
+        if not ok:
+            return msg
+        ok, msg = _check_credentials()
+        if not ok:
+            return msg
+        return None
+
+    def _require_my_account(self):
+        """归属铁门: "看我的"类工具必须先过此门 (v3.1.5 起从静默降级改为直接拒绝)。
+
+        历史: 旧版 MY_ACCOUNT 为空时 list 工具静默返回全队 + 全标[队友], 用户无法察觉
+        归属失效 → 看错数据(用户实测踩坑: 本以为看的是自己的, 实际是全队的)。
+        现改为: 读不到我的禅道账号 → 直接拒绝并给修复指引, 不静默降级。
+
+        返回 None=放行, 字符串=拒绝原因(直接 return 给用户)。
+        """
+        gate = self._gate()
+        if gate:
+            return gate
+        if not MY_ACCOUNT:
+            return ('🚫 未识别禅道身份: member.json 缺 zentao_account 字段, 无法区分"我的/队友的"。\n'
+                    '  修复: 跑 /wl-init 配置当前开发者的禅道账号, 或编辑\n'
+                    '        workspace/members/<我>/member.json 加 "zentao_account": "<禅道账号>"\n'
+                    '        (账号可在禅道→用户列表查到, 如 hupan) 后重启 MCP。')
+        return None
+
+    def _assert_owner(self, kind, item_id):
+        """归属校验 (写操作前调用): 查 item 详情, 校验归属。
+
+        防止误改队友任务/Bug。返回 None=放行, 字符串=拒绝原因。
+        - 未配置 MY_ACCOUNT (兼容旧环境): 不校验, 返回 None (放行, 退回旧行为)。
+        - 查询失败: 放行 (不因网络抖动阻塞用户, 禅道侧权限仍兜底)。
+        - 归属语义 (v3.1.6): task 只认 assignedTo==我; bug/story 认 assignedTo==我 OR openedBy==我
+          (原因: bug/story 创建后 assignedTo 常为空, 用户提的自己能 resolve/close 是合理的;
+          task 则不放宽 —— task 的 openedBy 是组长拆的, 归属以 assignedTo 为准)。
+        - 归属不匹配: 返回拒绝提示 (含归属人, 提示用户确认)。
+
+        Args:
+            kind: 'task' / 'bug' (决定查 /tasks/N 或 /bugs/N; 也决定是否放宽 openedBy)
+            item_id: 任务/Bug ID
+        """
+        if not MY_ACCOUNT:
+            return None  # 未配置归属 → 不强制 (兼容)
+        r = _api('GET', '/%ss/%s' % (kind, item_id))
+        if r.status_code not in (200, 201):
+            return None  # 查询失败不阻塞 (禅道权限兜底)
+        data = r.json()
+        asg = _assignee_account(data)
+        # task: 只认 assignedTo; bug/story: 认 assignedTo OR openedBy
+        allow = (asg == MY_ACCOUNT)
+        if kind in ('bug', 'story') and not allow:
+            allow = (_openedby_account(data) == MY_ACCOUNT)
+        if not allow:
+            owner = asg or '空'
+            return ('🚫 拒绝: 这条%s指派给 %s, 不是你(%s)。共享账号下不静默改队友的。'
+                    '\n  确实要改? 请用户明确确认, 或先 assign 给你再操作。'
+                    % (kind, owner, MY_ACCOUNT))
+        return None
+
+    # ── 聚合辅助: "我的"全景查询 (跨执行/产品全量扫描) ──────────────────
+    # 背景: 禅道无 "assignedTo=我的全部任务" 单接口, 只能逐执行/产品拉。
+    # 旧工作流只查最近几个执行 → 漏掉早期任务 (用户实测: 61 执行只查 12 个,
+    # 漏 9 个未开始任务)。这些辅助方法封装全量扫描, 供 my_workbench 等工具复用。
+
+    def _fetch_all_executions(self, limit=200):
+        """全量拉执行列表 (默认 200, 覆盖团队历史执行量)。返回 [(id,name,status),...] 或 None。"""
+        r = _api('GET', '/executions', {'limit': limit})
+        if r.status_code not in (200, 201):
+            return None
+        data = r.json()
+        execs = data.get('executions') if isinstance(data, dict) else None
+        if not isinstance(execs, list):
+            return None
+        return [(e.get('id'), str(e.get('name', ''))[:20], e.get('status', '')) for e in execs]
+
+    def _collect_my_tasks(self, status_filter=None):
+        """全量扫所有执行, 收集指派给我(MY_ACCOUNT)的任务。
+
+        Args:
+            status_filter: 可选, 只保留该状态 (如 'wait'/'doing'); None=全部非终态。
+        Returns:
+            (任务列表, 执行映射) 或 (None, 错误提示)。任务为统一 dict:
+              {id,name,status,pri,execution,execution_name,estimate,left,deadline,story}
+        """
+        execs = self._fetch_all_executions()
+        if execs is None:
+            return None, '查询执行列表失败, 稍后重试。'
+        emap = {eid: ename for eid, ename, _ in execs}
+        mine = []
+        for eid, ename, _ in execs:
+            r = _api('GET', '/executions/%s/tasks' % eid, {'limit': 200})
+            if r.status_code not in (200, 201):
+                continue
+            data = r.json()
+            tasks = data.get('tasks') if isinstance(data, dict) else None
+            if not isinstance(tasks, list):
+                continue
+            for t in tasks:
+                if not isinstance(t, dict):
+                    continue
+                if _assignee_account(t) != MY_ACCOUNT:
+                    continue
+                if status_filter and t.get('status') != status_filter:
+                    continue
+                t2 = dict(t)
+                t2['execution'] = eid
+                t2['execution_name'] = ename
+                mine.append(t2)
+        return mine, None
+
+    def _collect_my_bugs(self):
+        """扫活跃产品, 收集"我的"Bug。
+
+        归属语义 (v3.1.6 修复): 认 assignedTo==我 **或** openedBy==我。
+        原因: 实测团队习惯——提了 bug 不指派 (assignedTo=None), bug 留在创建人头上。
+        只认 assignedTo 会让用户提的 bug 永远查不到 (实测: hupan 提了 2 个 bug 全部
+        assignedTo=None → 旧逻辑 Bug=0, 用户"明明有 BUG"却查不到)。
+        返回 (bug列表, None) 或 (None, 错误)。bug dict 加 _why 字段标记归属来源。
+        """
+        r = _api('GET', '/products', None)
+        if r.status_code not in (200, 201):
+            return None, '查询产品列表失败。'
+        data = r.json()
+        prods = data.get('products') if isinstance(data, dict) else None
+        if not isinstance(prods, list):
+            return None, '产品列表响应异常。'
+        mine = []
+        for p in prods:
+            pid = p.get('id')
+            r = _api('GET', '/products/%s/bugs' % pid, {'limit': 500})
+            if r.status_code not in (200, 201):
+                continue
+            data = r.json()
+            bugs = data.get('bugs') if isinstance(data, dict) else None
+            if not isinstance(bugs, list):
+                continue
+            for b in bugs:
+                if not isinstance(b, dict):
+                    continue
+                asg = _assignee_account(b)
+                opn = _openedby_account(b)
+                why = None
+                if asg == MY_ACCOUNT:
+                    why = '指派给我'
+                elif opn == MY_ACCOUNT:
+                    why = '我提的'
+                if why:
+                    b2 = dict(b)
+                    b2['product_id'] = pid
+                    b2['_why'] = why
+                    mine.append(b2)
+        return mine, None
+
+    def _collect_my_stories(self):
+        """扫活跃产品, 收集"我的"需求 (指派给我 OR 我提的, 同 Bug 语义)。
+
+        归属语义 (v3.1.6): 认 assignedTo==我 OR openedBy==我。需求创建后 assignedTo 常为空,
+        只认 assignedTo 会让用户提的需求查不到 (同 Bug 的踩坑)。
+        返回 (story列表, None) 或 (None, 错误)。story dict 加 _why 字段标记来源。
+        """
+        r = _api('GET', '/products', None)
+        if r.status_code not in (200, 201):
+            return None, '查询产品列表失败。'
+        data = r.json()
+        prods = data.get('products') if isinstance(data, dict) else None
+        if not isinstance(prods, list):
+            return None, '产品列表响应异常。'
+        mine = []
+        for p in prods:
+            pid = p.get('id')
+            r = _api('GET', '/products/%s/stories' % pid, {'limit': 500})
+            # ★ 禅道列表接口可能返回 201 (Created), 不能只认 200
+            if r.status_code not in (200, 201):
+                continue
+            data = r.json()
+            sts = data.get('stories') if isinstance(data, dict) else None
+            if not isinstance(sts, list):
+                continue
+            for s in sts:
+                if not isinstance(s, dict):
+                    continue
+                asg = _assignee_account(s)
+                opn = _openedby_account(s)
+                why = '指派给我' if asg == MY_ACCOUNT else ('我提的' if opn == MY_ACCOUNT else None)
+                if why:
+                    s2 = dict(s)
+                    s2['product_id'] = pid
+                    s2['_why'] = why
+                    mine.append(s2)
+        return mine, None
+
+    def _safe_get(self, path, params, title, formatter, empty_msg=None):
+        """列表/详情类读取的统一封装。
+
+        Args:
+            path: API 路径 (如 '/products')
+            params: GET 参数 dict
+            title: 结果标题 (如 '禅道产品 (3 个):')
+            formatter: 函数 (item) -> 一行字符串
+            empty_msg: 列表为空时的提示 (None 则用 title)
+        """
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', path, params)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        data = r.json()
+        # 响应可能是 {key: [...]} 或直接是 dict(详情)
+        items = None
+        key = None
+        for k in ('products', 'stories', 'plans', 'executions', 'tasks',
+                  'bugs', 'builds', 'releases', 'projects', 'users'):
+            if isinstance(data.get(k), list):
+                items = data[k]
+                key = k
+                break
+        if items is None:
+            # 单对象详情, 原样交给 formatter
+            return formatter(data)
+        if not items:
+            return empty_msg or title
+        lines = [title % len(items) if '%' in title else title]
+        for it in items:
+            lines.append(formatter(it))
+        return '\n'.join(lines)
+
+    def _safe_write(self, method, path, payload, ok_msg, fail_hint, ok_codes=(200, 201)):
+        """写操作 (POST/PUT/DELETE) 的统一封装。
+
+        成功返回 ✅ ok_msg; 失败返回 ⚠️ 不抛异常 (权限不足/字段缺失不影响其它操作)。
+        """
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api(method, path, payload)
+        if r.status_code in ok_codes:
+            try:
+                d = r.json()
+                sid = d.get('id', '')
+                return ok_msg(d) if callable(ok_msg) else ok_msg
+            except Exception:
+                return ok_msg if isinstance(ok_msg, str) else ok_msg(d) if callable(ok_msg) else '✅ 操作成功'
+        return '⚠️ %s\n(%s)' % (_err_text(r), fail_hint)
+
+    # ── 通用辅助 (2) ──────────────────────────────────────────────────
+
+    @tool("check_zentao_status",
+          "禅道健康检查: 探测内网连通 + 凭据是否配好。给交互壳子/启动诊断用。例: check_zentao_status()",
+          {"type": "object", "properties": {}})
+    def _t_check_status(self, args):
+        ok, msg = check_intranet()
+        if not ok:
+            return '❌ ' + msg
+        ok2, msg2 = _check_credentials()
+        if not ok2:
+            return '❌ ' + msg2
+        return '✅ 禅道可达, 凭据已配置 (%s)' % ZENTAO_URL
+
+    @tool("get_zentao_url",
+          "返回禅道前端地址(给'在禅道打开'链接用)。例: get_zentao_url()",
+          {"type": "object", "properties": {}})
+    def _t_get_url(self, args):
+        if not ZENTAO_URL:
+            return '禅道地址未配置。'
+        return ZENTAO_URL
+
+    # ── 产品 Product (5) ──────────────────────────────────────────────
+
+    @tool("list_products",
+          "列禅道产品(找到需求归属)。例: list_products()",
+          {"type": "object", "properties": {}})
+    def _t_list_products(self, args):
+        return self._safe_get(
+            '/products', None,
+            '禅道产品 (%d 个):',
+            lambda p: '  [%s] %s' % (p.get('id'), str(p.get('name', ''))[:20]),
+            empty_msg='禅道暂无产品。',
+        )
+
+    @tool("get_product",
+          "查产品详情。例: get_product(product_id=1)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+          }, "required": ["product_id"]})
+    def _t_get_product(self, args):
+        pid = args.get('product_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/products/%s' % pid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        p = r.json()
+        return '产品 #%s: %s\n状态: %s\n类型: %s' % (
+            pid, p.get('name', ''), p.get('status', ''), p.get('type', ''))
+
+    @tool("create_product",
+          "创建产品。例: create_product(name='车险管理', code='cxgl', type='normal')",
+          {"type": "object", "properties": {
+              "name": {"type": "string", "description": "产品名称"},
+              "code": {"type": "string", "description": "产品代号"},
+              "type": {"type": "string", "description": "类型: normal(正常)/branch(多分支)/platform(平台), 默认normal"},
+          }, "required": ["name", "code"]})
+    def _t_create_product(self, args):
+        name = args.get('name', '')
+        code = args.get('code', '')
+        if not name or not code:
+            return '⚠️ 缺少必填字段: name 和 code 不能为空。'
+        payload = {'name': name, 'code': code, 'type': args.get('type', 'normal')}
+        return self._safe_write(
+            'POST', '/products', payload,
+            lambda d: '✅ 产品已创建! ID=%s' % d.get('id', '?'),
+            '可能权限不足或字段缺失')
+
+    @tool("update_product",
+          "修改产品(名称等)。权限不足返回提示不报错。例: update_product(product_id=1, name='车险管理(改)')",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+              "name": {"type": "string", "description": "新名称(可选)"},
+          }, "required": ["product_id"]})
+    def _t_update_product(self, args):
+        pid = args.get('product_id', 0)
+        payload = {}
+        if args.get('name'):
+            payload['name'] = args['name']
+        if not payload:
+            return '⚠️ 没有要更新的字段(可选: name)。'
+        return self._safe_write(
+            'PUT', '/products/%s' % pid, payload,
+            '✅ 产品 #%s 已更新' % pid,
+            '可能权限不足或字段缺失')
+
+    @tool("delete_product",
+          "删除产品。权限不足返回提示不报错。例: delete_product(product_id=1)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+          }, "required": ["product_id"]})
+    def _t_delete_product(self, args):
+        pid = args.get('product_id', 0)
+        return self._safe_write(
+            'DELETE', '/products/%s' % pid, None,
+            '✅ 产品 #%s 已删除' % pid,
+            '可能权限不足或有关联需求/任务无法删除')
+
+    # ── 计划 Plan (7) ─────────────────────────────────────────────────
+
+    @tool("list_plans",
+          "查某产品的计划/迭代列表(让用户选归属)。例: list_plans(product_id=1)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+          }, "required": ["product_id"]})
+    def _t_list_plans(self, args):
+        pid = args.get('product_id', 1)
+        return self._safe_get(
+            '/products/%s/plans' % pid, None,
+            '产品 %s 的计划 (%%d 个):' % pid,
+            lambda p: '  [%s] %s (%s~%s)' % (
+                p.get('id'), str(p.get('title', ''))[:20], p.get('begin', ''), p.get('end', '')),
+            empty_msg='产品 %s 暂无计划。可在禅道里创建计划/迭代。' % pid,
+        )
+
+    @tool("get_plan",
+          "查计划详情(含关联的需求)。例: get_plan(plan_id=12)",
+          {"type": "object", "properties": {
+              "plan_id": {"type": "integer", "description": "计划ID"},
+          }, "required": ["plan_id"]})
+    def _t_get_plan(self, args):
+        pid = args.get('plan_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/plans/%s' % pid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        p = r.json()
+        return '计划 #%s: %s\n周期: %s ~ %s\n描述: %s' % (
+            pid, p.get('title', ''), p.get('begin', ''), p.get('end', ''),
+            str(p.get('desc', ''))[:200])
+
+    @tool("create_plan",
+          "创建计划(产品规划用)。例: create_plan(product_id=1, title='2026Q3车险v2', begin='2026-07-01', end='2026-09-30')",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+              "title": {"type": "string", "description": "计划标题"},
+              "begin": {"type": "string", "description": "开始日期 YYYY-MM-DD"},
+              "end": {"type": "string", "description": "结束日期 YYYY-MM-DD"},
+              "desc": {"type": "string", "description": "计划描述(可选)"},
+          }, "required": ["product_id", "title", "begin", "end"]})
+    def _t_create_plan(self, args):
+        pid = args.get('product_id', 1)
+        title = args.get('title', '')
+        begin = args.get('begin', '')
+        end = args.get('end', '')
+        if not title or not begin or not end:
+            return '⚠️ 缺少必填字段: title/begin/end 都不能为空。'
+        payload = {'title': title, 'begin': begin, 'end': end}
+        if args.get('desc'):
+            payload['desc'] = args['desc']
+        return self._safe_write(
+            'POST', '/products/%s/plans' % pid, payload,
+            lambda d: '✅ 计划已创建! ID=%s' % d.get('id', '?'),
+            '可能权限不足或字段缺失')
+
+    @tool("link_story_to_plan",
+          "把需求关联到计划(产品把需求归入计划)。权限不足返回提示不报错。例: link_story_to_plan(plan_id=12, stories=[761,762])",
+          {"type": "object", "properties": {
+              "plan_id": {"type": "integer", "description": "计划ID"},
+              "stories": {"type": "array", "items": {"type": "integer"}, "description": "需求ID列表"},
+          }, "required": ["plan_id", "stories"]})
+    def _t_link_story_plan(self, args):
+        pid = args.get('plan_id', 0)
+        stories = args.get('stories', [])
+        if not stories:
+            return '⚠️ 缺少必填字段: stories(需求ID列表)不能为空。'
+        return self._safe_write(
+            'POST', '/plans/%s/linkStory' % pid, {'stories': stories},
+            '✅ %d 个需求已关联到计划 #%s' % (len(stories), pid),
+            '可能权限不足, 需在禅道手动关联')
+
+    @tool("unlink_story_from_plan",
+          "从计划移除需求。权限不足返回提示不报错。例: unlink_story_from_plan(plan_id=12, stories=[761])",
+          {"type": "object", "properties": {
+              "plan_id": {"type": "integer", "description": "计划ID"},
+              "stories": {"type": "array", "items": {"type": "integer"}, "description": "需求ID列表"},
+          }, "required": ["plan_id", "stories"]})
+    def _t_unlink_story_plan(self, args):
+        pid = args.get('plan_id', 0)
+        stories = args.get('stories', [])
+        if not stories:
+            return '⚠️ 缺少必填字段: stories(需求ID列表)不能为空。'
+        return self._safe_write(
+            'POST', '/plans/%s/unlinkStory' % pid, {'stories': stories},
+            '✅ %d 个需求已从计划 #%s 移除' % (len(stories), pid),
+            '可能权限不足, 需在禅道手动移除')
+
+    @tool("link_bug_to_plan",
+          "把Bug关联到计划。权限不足返回提示不报错。例: link_bug_to_plan(plan_id=12, bugs=[101])",
+          {"type": "object", "properties": {
+              "plan_id": {"type": "integer", "description": "计划ID"},
+              "bugs": {"type": "array", "items": {"type": "integer"}, "description": "Bug ID列表"},
+          }, "required": ["plan_id", "bugs"]})
+    def _t_link_bug_plan(self, args):
+        pid = args.get('plan_id', 0)
+        bugs = args.get('bugs', [])
+        if not bugs:
+            return '⚠️ 缺少必填字段: bugs(Bug ID列表)不能为空。'
+        return self._safe_write(
+            'POST', '/plans/%s/linkBug' % pid, {'bugs': bugs},
+            '✅ %d 个Bug已关联到计划 #%s' % (len(bugs), pid),
+            '可能权限不足, 需在禅道手动关联')
+
+    @tool("unlink_bug_from_plan",
+          "从计划移除Bug。权限不足返回提示不报错。例: unlink_bug_from_plan(plan_id=12, bugs=[101])",
+          {"type": "object", "properties": {
+              "plan_id": {"type": "integer", "description": "计划ID"},
+              "bugs": {"type": "array", "items": {"type": "integer"}, "description": "Bug ID列表"},
+          }, "required": ["plan_id", "bugs"]})
+    def _t_unlink_bug_plan(self, args):
+        pid = args.get('plan_id', 0)
+        bugs = args.get('bugs', [])
+        if not bugs:
+            return '⚠️ 缺少必填字段: bugs(Bug ID列表)不能为空。'
+        return self._safe_write(
+            'POST', '/plans/%s/unlinkBug' % pid, {'bugs': bugs},
+            '✅ %d 个Bug已从计划 #%s 移除' % (len(bugs), pid),
+            '可能权限不足, 需在禅道手动移除')
+
+    # ── 发布 Release (2) ──────────────────────────────────────────────
+
+    @tool("list_releases",
+          "查某产品的发布列表(已发布的版本里程碑)。例: list_releases(product_id=1)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+          }, "required": ["product_id"]})
+    def _t_list_releases(self, args):
+        pid = args.get('product_id', 1)
+        return self._safe_get(
+            '/products/%s/releases' % pid, None,
+            '产品 %s 的发布 (%%d 个):' % pid,
+            lambda rel: '  [%s] %s (date=%s build=%s)' % (
+                rel.get('id'), str(rel.get('name', ''))[:20],
+                rel.get('date', ''), rel.get('build', '')),
+            empty_msg='产品 %s 暂无发布。' % pid,
+        )
+
+    @tool("get_release",
+          "查发布详情。例: get_release(release_id=5)",
+          {"type": "object", "properties": {
+              "release_id": {"type": "integer", "description": "发布ID"},
+          }, "required": ["release_id"]})
+    def _t_get_release(self, args):
+        rid = args.get('release_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/releases/%s' % rid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        d = r.json()
+        return '发布 #%s: %s\n日期: %s\nbuild: %s' % (
+            rid, d.get('name', ''), d.get('date', ''), d.get('build', ''))
+
+    # ── 版本 Build (5) ── ★"把需求放进版本" ────────────────────────────
+
+    @tool("list_builds",
+          "查版本/构建列表(项目/产品/执行维度, 三选一)。例: list_builds(project_id=9) 或 list_builds(product_id=1) 或 list_builds(execution_id=73)",
+          {"type": "object", "properties": {
+              "project_id": {"type": "integer", "description": "项目ID(★最常用, 看项目级按周版本, 三选一优先)"},
+              "product_id": {"type": "integer", "description": "产品ID(与project_id/execution_id三选一)"},
+              "execution_id": {"type": "integer", "description": "执行ID(与project_id/product_id三选一)"},
+          }})
+    def _t_list_builds(self, args):
+        # 维度优先级: project > execution > product(默认)
+        if args.get('project_id'):
+            path = '/projects/%s/builds' % args['project_id']
+            scope = '项目 %s' % args['project_id']
+        elif args.get('execution_id'):
+            path = '/executions/%s/builds' % args['execution_id']
+            scope = '执行 %s' % args['execution_id']
+        else:
+            pid = args.get('product_id', 1)
+            path = '/products/%s/builds' % pid
+            scope = '产品 %s' % pid
+        return self._safe_get(
+            path, None,
+            '%s 的版本 (%%d 个):' % scope,
+            lambda b: '  [%s] %s (date=%s)' % (
+                b.get('id'), str(b.get('name', ''))[:20], b.get('date', '')),
+            empty_msg='%s 暂无版本(build)。' % scope,
+        )
+
+    @tool("get_build",
+          "查版本/构建详情。例: get_build(build_id=8)",
+          {"type": "object", "properties": {
+              "build_id": {"type": "integer", "description": "版本ID"},
+          }, "required": ["build_id"]})
+    def _t_get_build(self, args):
+        bid = args.get('build_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/builds/%s' % bid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        b = r.json()
+        return '版本 #%s: %s\n日期: %s\n执行: %s' % (
+            bid, b.get('name', ''), b.get('date', ''), b.get('execution', ''))
+
+    @tool("create_build",
+          "创建版本/构建(发版里程碑)。例: create_build(product_id=1, name='2.5.0', build='build2')",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+              "name": {"type": "string", "description": "版本名称"},
+              "build": {"type": "string", "description": "构建标识"},
+              "execution_id": {"type": "integer", "description": "所属执行ID(可选)"},
+          }, "required": ["product_id", "name"]})
+    def _t_create_build(self, args):
+        pid = args.get('product_id', 1)
+        name = args.get('name', '')
+        if not name:
+            return '⚠️ 缺少必填字段: name(版本名称)不能为空。'
+        payload = {'name': name}
+        if args.get('build'):
+            payload['build'] = args['build']
+        if args.get('execution_id'):
+            payload['execution'] = args['execution_id']
+        return self._safe_write(
+            'POST', '/products/%s/builds' % pid, payload,
+            lambda d: '✅ 版本已创建! ID=%s' % d.get('id', '?'),
+            '可能权限不足或字段缺失')
+
+    @tool("link_story_to_build",
+          "把需求关联到版本(需求定版本/收进发布)。权限不足返回提示不报错。例: link_story_to_build(build_id=8, stories=[761])",
+          {"type": "object", "properties": {
+              "build_id": {"type": "integer", "description": "版本ID"},
+              "stories": {"type": "array", "items": {"type": "integer"}, "description": "需求ID列表"},
+          }, "required": ["build_id", "stories"]})
+    def _t_link_story_build(self, args):
+        bid = args.get('build_id', 0)
+        stories = args.get('stories', [])
+        if not stories:
+            return '⚠️ 缺少必填字段: stories(需求ID列表)不能为空。'
+        return self._safe_write(
+            'POST', '/builds/%s/linkStory' % bid, {'stories': stories},
+            '✅ %d 个需求已关联到版本 #%s' % (len(stories), bid),
+            '可能权限不足, 需在禅道手动关联')
+
+    @tool("link_bug_to_build",
+          "把Bug关联到版本。权限不足返回提示不报错。例: link_bug_to_build(build_id=8, bugs=[101])",
+          {"type": "object", "properties": {
+              "build_id": {"type": "integer", "description": "版本ID"},
+              "bugs": {"type": "array", "items": {"type": "integer"}, "description": "Bug ID列表"},
+          }, "required": ["build_id", "bugs"]})
+    def _t_link_bug_build(self, args):
+        bid = args.get('build_id', 0)
+        bugs = args.get('bugs', [])
+        if not bugs:
+            return '⚠️ 缺少必填字段: bugs(Bug ID列表)不能为空。'
+        return self._safe_write(
+            'POST', '/builds/%s/linkBug' % bid, {'bugs': bugs},
+            '✅ %d 个Bug已关联到版本 #%s' % (len(bugs), bid),
+            '可能权限不足, 需在禅道手动关联')
+
+    # ── 项目 Project (3) ──────────────────────────────────────────────
+
+    @tool("list_projects",
+          "查项目列表(执行/任务的父级)。例: list_projects()",
+          {"type": "object", "properties": {}})
+    def _t_list_projects(self, args):
+        return self._safe_get(
+            '/projects', None,
+            '禅道项目 (%d 个):',
+            lambda p: '  [%s] %s (status=%s)' % (
+                p.get('id'), str(p.get('name', ''))[:20], p.get('status', '')),
+            empty_msg='禅道暂无项目。',
+        )
+
+    @tool("get_project",
+          "查项目详情。例: get_project(project_id=11)",
+          {"type": "object", "properties": {
+              "project_id": {"type": "integer", "description": "项目ID"},
+          }, "required": ["project_id"]})
+    def _t_get_project(self, args):
+        pid = args.get('project_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/projects/%s' % pid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        p = r.json()
+        return '项目 #%s: %s\n状态: %s\n周期: %s ~ %s' % (
+            pid, p.get('name', ''), p.get('status', ''),
+            p.get('begin', ''), p.get('end', ''))
+
+    @tool("create_project",
+          "创建项目。例: create_project(name='车险v2', code='cxv2', begin='2026-07-01', end='2026-09-30')",
+          {"type": "object", "properties": {
+              "name": {"type": "string", "description": "项目名称"},
+              "code": {"type": "string", "description": "项目代号"},
+              "begin": {"type": "string", "description": "开始日期 YYYY-MM-DD"},
+              "end": {"type": "string", "description": "结束日期 YYYY-MM-DD"},
+              "project_id": {"type": "integer", "description": "所属项目集ID(可选)"},
+          }, "required": ["name", "code"]})
+    def _t_create_project(self, args):
+        name = args.get('name', '')
+        code = args.get('code', '')
+        if not name or not code:
+            return '⚠️ 缺少必填字段: name 和 code 不能为空。'
+        payload = {'name': name, 'code': code}
+        if args.get('begin'):
+            payload['begin'] = args['begin']
+        if args.get('end'):
+            payload['end'] = args['end']
+        return self._safe_write(
+            'POST', '/projects', payload,
+            lambda d: '✅ 项目已创建! ID=%s' % d.get('id', '?'),
+            '可能权限不足或字段缺失')
+
+    # ── 执行 Execution (5) ────────────────────────────────────────────
+
+    @tool("list_executions",
+          "查活跃的执行/迭代(按周划分的后端/前端/移动端)。默认全量(100), 查'我的全部任务'靠这个拿全执行别漏。例: list_executions() / list_executions(limit=5)",
+          {"type": "object", "properties": {
+              "limit": {"type": "integer", "description": "返回数量(默认100, 团队历史执行多, 旧版默认10会漏早期执行里的任务)"},
+          }})
+    def _t_list_executions(self, args):
+        limit = args.get('limit', 100)
+        return self._safe_get(
+            '/executions', {'limit': limit},
+            '活跃执行/迭代 (%d 个):',
+            lambda ex: '  [%s] %s (%s~%s project=%s)' % (
+                ex.get('id'), str(ex.get('name', ''))[:15],
+                ex.get('begin', ''), ex.get('end', ''), ex.get('project', '')),
+        )
+
+    @tool("get_execution",
+          "查执行详情。例: get_execution(execution_id=73)",
+          {"type": "object", "properties": {
+              "execution_id": {"type": "integer", "description": "执行ID"},
+          }, "required": ["execution_id"]})
+    def _t_get_execution(self, args):
+        eid = args.get('execution_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/executions/%s' % eid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        e = r.json()
+        return '执行 #%s: %s\n状态: %s\n周期: %s ~ %s\n项目: %s' % (
+            eid, e.get('name', ''), e.get('status', ''),
+            e.get('begin', ''), e.get('end', ''), e.get('project', ''))
+
+    @tool("create_execution",
+          "创建执行/迭代。例: create_execution(project_id=11, name='车险v2后端第1周', code='cxv2be1', begin='2026-07-01', end='2026-07-07')",
+          {"type": "object", "properties": {
+              "project_id": {"type": "integer", "description": "所属项目ID"},
+              "name": {"type": "string", "description": "执行名称"},
+              "code": {"type": "string", "description": "执行代号"},
+              "begin": {"type": "string", "description": "开始日期 YYYY-MM-DD"},
+              "end": {"type": "string", "description": "结束日期 YYYY-MM-DD"},
+          }, "required": ["project_id", "name", "code"]})
+    def _t_create_execution(self, args):
+        pid = args.get('project_id', 0)
+        name = args.get('name', '')
+        code = args.get('code', '')
+        if not pid or not name or not code:
+            return '⚠️ 缺少必填字段: project_id/name/code 都不能为空。'
+        payload = {'project': pid, 'name': name, 'code': code}
+        if args.get('begin'):
+            payload['begin'] = args['begin']
+        if args.get('end'):
+            payload['end'] = args['end']
+        return self._safe_write(
+            'POST', '/executions', payload,
+            lambda d: '✅ 执行已创建! ID=%s' % d.get('id', '?'),
+            '可能权限不足或字段缺失')
+
+    @tool("update_execution",
+          "修改执行(改名称/周期等)。权限不足返回提示不报错。例: update_execution(execution_id=73, name='车险v2后端第1周(改)')",
+          {"type": "object", "properties": {
+              "execution_id": {"type": "integer", "description": "执行ID"},
+              "name": {"type": "string", "description": "新名称(可选)"},
+              "begin": {"type": "string", "description": "新开始日期(可选)"},
+              "end": {"type": "string", "description": "新结束日期(可选)"},
+          }, "required": ["execution_id"]})
+    def _t_update_execution(self, args):
+        eid = args.get('execution_id', 0)
+        payload = {}
+        for k in ('name', 'begin', 'end'):
+            if args.get(k):
+                payload[k] = args[k]
+        if not payload:
+            return '⚠️ 没有要更新的字段(可选: name/begin/end)。'
+        return self._safe_write(
+            'PUT', '/executions/%s' % eid, payload,
+            '✅ 执行 #%s 已更新' % eid,
+            '可能权限不足或字段缺失')
+
+    @tool("delete_execution",
+          "删除执行。权限不足返回提示不报错。例: delete_execution(execution_id=73)",
+          {"type": "object", "properties": {
+              "execution_id": {"type": "integer", "description": "执行ID"},
+          }, "required": ["execution_id"]})
+    def _t_delete_execution(self, args):
+        eid = args.get('execution_id', 0)
+        return self._safe_write(
+            'DELETE', '/executions/%s' % eid, None,
+            '✅ 执行 #%s 已删除' % eid,
+            '可能权限不足或有任务关联无法删除')
+
+    @tool("unlink_story_from_execution",
+          "从执行移除需求。权限不足返回提示不报错。例: unlink_story_from_execution(execution_id=73, stories=[761])",
+          {"type": "object", "properties": {
+              "execution_id": {"type": "integer", "description": "执行ID"},
+              "stories": {"type": "array", "items": {"type": "integer"}, "description": "需求ID列表"},
+          }, "required": ["execution_id", "stories"]})
+    def _t_unlink_story_exec(self, args):
+        eid = args.get('execution_id', 0)
+        stories = args.get('stories', [])
+        if not stories:
+            return '⚠️ 缺少必填字段: stories(需求ID列表)不能为空。'
+        return self._safe_write(
+            'POST', '/executions/%s/unlinkStory' % eid, {'stories': stories},
+            '✅ %d 个需求已从执行 #%s 移除' % (len(stories), eid),
+            '可能权限不足, 需在禅道手动移除')
+
+    # ── 需求 Story (8) ────────────────────────────────────────────────
+
+    @tool("list_stories",
+          "查某产品的需求列表。默认只看指派给我的(assignedTo=我), 防看错队友; 要看全队加 all=true。"
+          "★查'我的禅道需求'直接用这个, 不要逐个 get_story_detail 枚举。"
+          "例: list_stories(product_id=1) / list_stories(product_id=1, all=true)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+              "limit": {"type": "integer", "description": "返回数量(默认50, 过滤后)"},
+              "all": {"type": "boolean", "description": "true=看全队(默认false只看我的)"},
+          }, "required": ["product_id"]})
+    def _t_list_stories(self, args):
+        pid = args.get('product_id', 1)
+        limit = args.get('limit', 50)
+        see_all = bool(args.get('all', False))
+        filter_mine = not see_all  # 默认只看我的
+        # 归属铁门: 看我的就必须有账号 (v3.1.5 起拒绝而非静默降级)
+        if filter_mine:
+            guard = self._require_my_account()
+            if guard:
+                return guard
+        else:
+            gate = self._gate()
+            if gate:
+                return gate
+        resp = _api('GET', '/products/%s/stories' % pid, {'limit': limit})
+        if resp.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(resp)
+        data = resp.json()
+        items = data.get('stories') if isinstance(data, dict) else None
+        if items is None:
+            # 未知结构 → 回显顶层 key 便于排障 (不再笼统报"异常")
+            topkeys = list(data.keys()) if isinstance(data, dict) else type(data).__name__
+            return '产品 %s 的需求响应无 stories 字段 (顶层 keys: %s)。' % (pid, topkeys)
+        if not items:
+            return '产品 %s 暂无需求。' % pid
+        if filter_mine:
+            total = len(items)
+            # v3.1.6: "我的需求" = 指派给我 OR 我提的 (同 Bug 语义, 需求创建后 assignedTo 常为空)
+            items = [s for s in items if isinstance(s, dict) and (
+                _assignee_account(s) == MY_ACCOUNT or _openedby_account(s) == MY_ACCOUNT)]
+            scope = '我的(指派给我或我提的, %s)' % MY_ACCOUNT
+            if not items:
+                return '产品 %s 没有指派给你或你提的需求。\n(全队 %d 个, 要看全队加 all=true)' % (pid, MY_ACCOUNT, total)
+        else:
+            scope = '全队' if see_all else '全部'
+        lines = ['产品 %s 的需求 [%s, %d 个]:' % (pid, scope, len(items))]
+        for s in items:
+            if isinstance(s, dict):
+                acc = _assignee_account(s)
+                opn = _openedby_account(s)
+                if filter_mine:
+                    tag = ''
+                else:
+                    tag = ('  [指派给我]' if acc == MY_ACCOUNT else
+                           ('  [我提的]' if opn == MY_ACCOUNT else '  [队友]'))
+                acc_show = acc or ('(空,我提的)' if opn == MY_ACCOUNT and not acc else acc)
+                lines.append('  [#%s] %s (pri=%s status=%s assignedTo=%s)%s' % (
+                    s.get('id'), str(s.get('title', ''))[:30], s.get('pri'),
+                    s.get('status', ''), acc_show, tag))
+            else:
+                lines.append('  ' + str(s)[:60])
+        return '\n'.join(lines)
+
+    @tool("get_story_detail",
+          "查需求详情(完整描述+状态+关联)。例: get_story_detail(story_id=761)",
+          {"type": "object", "properties": {
+              "story_id": {"type": "integer", "description": "需求ID"},
+          }, "required": ["story_id"]})
+    def _t_get_story_detail(self, args):
+        sid = args.get('story_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/stories/%s' % sid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        s = r.json()
+        return '需求 #%s: %s\n状态: %s\n优先级: %s\n描述: %s' % (
+            sid, s.get('title', ''), s.get('status', ''),
+            s.get('pri', ''), str(s.get('spec', ''))[:200])
+
+    @tool("create_story",
+          "在禅道创建需求(PRD发布→禅道需求)。权限不足会返回友好提示不报错。例: create_story(product_id=1, title='品质案件催办', spec='需求详情', pri=3, module=104)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+              "title": {"type": "string", "description": "需求标题"},
+              "spec": {"type": "string", "description": "需求描述"},
+              "pri": {"type": "integer", "description": "优先级 1-4(1最高, 默认3)"},
+              "module": {"type": "integer", "description": "模块ID(可选)"},
+              "category": {"type": "string", "description": "类别(feature/interface/optimization, 默认feature)"},
+          }, "required": ["product_id", "title", "spec"]})
+    def _t_create_story(self, args):
+        pid = args.get('product_id', 1)
+        title = args.get('title', '')
+        spec = args.get('spec', '')
+        if not title or not spec:
+            return '⚠️ 缺少必填字段: title(标题) 和 spec(描述) 都不能为空。'
+        payload = {
+            'title': title, 'spec': spec,
+            'category': args.get('category', 'feature'),
+            'pri': args.get('pri', 3),
+        }
+        if args.get('module'):
+            payload['module'] = args['module']
+
+        def ok_msg(d):
+            sid = d.get('id', '?')
+            return '✅ 需求已创建! ID=%s\n禅道地址: %s/story-view-%s.html' % (
+                sid, ZENTAO_URL.rstrip('/'), sid)
+
+        return self._safe_write(
+            'POST', '/products/%s/stories' % pid, payload, ok_msg,
+            '可能权限不足或字段缺失, 不影响其它操作')
+
+    @tool("assign_story",
+          "指派需求给某人(设负责人)。权限不足返回提示不报错。例: assign_story(story_id=761, account='hupan')",
+          {"type": "object", "properties": {
+              "story_id": {"type": "integer", "description": "需求ID"},
+              "account": {"type": "string", "description": "禅道账号"},
+          }, "required": ["story_id", "account"]})
+    def _t_assign_story(self, args):
+        sid = args.get('story_id', 0)
+        account = args.get('account', '')
+        return self._safe_write(
+            'POST', '/stories/%s/assign' % sid, {'assignedTo': account},
+            '✅ 需求 #%s 已指派给 %s' % (sid, account),
+            '可能权限不足, 需在禅道手动指派')
+
+    @tool("change_story_status",
+          "变更需求状态(draft→reviewing→active→closed)。权限不足返回提示不报错。例: change_story_status(story_id=761, status='active')",
+          {"type": "object", "properties": {
+              "story_id": {"type": "integer", "description": "需求ID"},
+              "status": {"type": "string", "description": "目标状态(draft/reviewing/active/closed)"},
+          }, "required": ["story_id", "status"]})
+    def _t_change_story_status(self, args):
+        sid = args.get('story_id', 0)
+        status = args.get('status', '')
+        return self._safe_write(
+            'POST', '/stories/%s/change' % sid, {'status': status},
+            '✅ 需求 #%s 状态变更为 %s' % (sid, status),
+            '可能权限不足或状态转换不合法')
+
+    @tool("link_story_to_execution",
+          "把需求关联到执行/迭代(让开发能看到)。权限不足返回提示不报错。例: link_story_to_execution(story_id=761, execution_id=73)",
+          {"type": "object", "properties": {
+              "story_id": {"type": "integer", "description": "需求ID"},
+              "execution_id": {"type": "integer", "description": "执行ID"},
+          }, "required": ["story_id", "execution_id"]})
+    def _t_link_story_exec(self, args):
+        sid = args.get('story_id', 0)
+        eid = args.get('execution_id', 0)
+        return self._safe_write(
+            'POST', '/executions/%s/stories' % eid, {'stories': [sid]},
+            '✅ 需求 #%s 已关联到执行 #%s' % (sid, eid),
+            '可能权限不足, 需在禅道手动关联')
+
+    @tool("upload_file",
+          "上传文件到禅道附件(原型图/PRD等)。注意: 禅道开源版 REST API 的文件上传支持有限, "
+          "HTML/PNG/MD 等常被拒('格式不在范围')。失败时本工具会返回明确提示+降级方案, 不闷头失败。"
+          "例: upload_file(file_path='/abs/prototype-x.png', object_type='story', object_id=812)",
+          {"type": "object", "properties": {
+              "file_path": {"type": "string", "description": "本地文件绝对路径"},
+              "title": {"type": "string", "description": "文件标题(可选, 默认取文件名)"},
+              "object_type": {"type": "string", "description": "关联对象类型: story/task/bug(可选)"},
+              "object_id": {"type": "integer", "description": "关联对象ID(可选, 配合object_type)"},
+          }, "required": ["file_path"]})
+    def _t_upload_file(self, args):
+        import os
+        fpath = args.get('file_path', '')
+        if not fpath:
+            return '⚠️ 缺少必填字段 file_path。'
+        if not os.path.isfile(fpath):
+            return '⚠️ 文件不存在: %s' % fpath
+        gate = self._gate()
+        if gate:
+            return gate
+        extra = None
+        ot = args.get('object_type')
+        oid = args.get('object_id')
+        if ot and oid:
+            extra = {'objectType': ot, 'objectID': str(oid)}
+        r = _upload_file(fpath, title=args.get('title', ''), extra_fields=extra)
+        if r.status_code in (200, 201):
+            d = r.json() if r.text else {}
+            return '✅ 文件已上传! ID=%s (%s)\n禅道附件可在需求/任务详情的"附件"区查看' % (
+                d.get('id', '?'), os.path.basename(fpath))
+        # 上传失败 → 明确降级指引 (禅道开源版 REST 上传常被拒, 不闷头失败)
+        err = _err_text(r)
+        return ('⚠️ 禅道文件上传失败 (%s): %s\n'
+                '  这通常是禅道开源版 REST API 不支持文件上传 (限制: 格式/端点)。\n'
+                '  ★降级方案(二选一):\n'
+                '   1. 手动上传: 打开禅道需求 → 附件标签 → 拖入文件 (web 端支持所有格式)\n'
+                '   2. 嵌入截图: 截取原型图关键界面 → 粘贴到需求描述 (禅道 web 端支持图片粘贴)\n'
+                '  本地原型文件仍可用浏览器打开预览: %s'
+                % (r.status_code, err, os.path.basename(fpath)))
+
+    @tool("update_story",
+          "修改需求(标题/描述/优先级等)。权限不足返回提示不报错。例: update_story(story_id=761, title='新标题', pri=2)",
+          {"type": "object", "properties": {
+              "story_id": {"type": "integer", "description": "需求ID"},
+              "title": {"type": "string", "description": "新标题(可选)"},
+              "spec": {"type": "string", "description": "新描述(可选)"},
+              "pri": {"type": "integer", "description": "新优先级 1-4(可选)"},
+          }, "required": ["story_id"]})
+    def _t_update_story(self, args):
+        sid = args.get('story_id', 0)
+        payload = {}
+        for k in ('title', 'spec', 'pri'):
+            if args.get(k) is not None:
+                payload[k] = args[k]
+        if not payload:
+            return '⚠️ 没有要更新的字段(可选: title/spec/pri)。'
+        return self._safe_write(
+            'PUT', '/stories/%s' % sid, payload,
+            '✅ 需求 #%s 已更新' % sid,
+            '可能权限不足或字段缺失')
+
+    @tool("delete_story",
+          "删除需求。权限不足返回提示不报错。例: delete_story(story_id=761)",
+          {"type": "object", "properties": {
+              "story_id": {"type": "integer", "description": "需求ID"},
+          }, "required": ["story_id"]})
+    def _t_delete_story(self, args):
+        sid = args.get('story_id', 0)
+        return self._safe_write(
+            'DELETE', '/stories/%s' % sid, None,
+            '✅ 需求 #%s 已删除' % sid,
+            '可能权限不足或有关联任务无法删除')
+
+    # ── 任务 Task (10) ── ★"组长拆任务" ───────────────────────────────
+
+    @tool("list_execution_tasks",
+          "查某执行的任务列表。默认只看指派给我的(assignedTo=我), 防看错队友; "
+          "要看全队加 all=true。★查'我的全部任务(跨执行)'请用 list_my_tasks 或 my_workbench, 别逐执行查会漏。"
+          "例: list_execution_tasks(execution_id=73) / list_execution_tasks(execution_id=73, all=true)",
+          {"type": "object", "properties": {
+              "execution_id": {"type": "integer", "description": "执行ID"},
+              "limit": {"type": "integer", "description": "返回数量"},
+              "all": {"type": "boolean", "description": "true=看全队(默认false只看我的)"},
+          }, "required": ["execution_id"]})
+    def _t_list_exec_tasks(self, args):
+        eid = args.get('execution_id', 1)
+        limit = args.get('limit', 20)
+        see_all = bool(args.get('all', False))
+        filter_mine = not see_all  # 默认只看我的
+        # 归属铁门 (v3.1.5 起拒绝而非静默降级, 堵"看错队友"且无察觉)
+        if filter_mine:
+            guard = self._require_my_account()
+            if guard:
+                return guard
+        else:
+            r = self._gate()
+            if r:
+                return r
+        resp = _api('GET', '/executions/%s/tasks' % eid, {'limit': limit})
+        if resp.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(resp)
+        data = resp.json()
+        items = data.get('tasks') if isinstance(data, dict) else None
+        if items is None:
+            topkeys = list(data.keys()) if isinstance(data, dict) else type(data).__name__
+            return '执行 %s 的任务响应无 tasks 字段 (顶层 keys: %s)。' % (eid, topkeys)
+        if not items:
+            return '执行 %s 暂无任务。' % eid
+        if filter_mine:
+            total = len(items)
+            items = [t for t in items if isinstance(t, dict)
+                     and _assignee_account(t) == MY_ACCOUNT]
+            scope = '指派给我(%s)' % MY_ACCOUNT
+            if not items:
+                return '执行 %s 没有指派给你(%s)的任务。\n(全队 %d 个, 要看全队加 all=true)' % (eid, MY_ACCOUNT, total)
+        else:
+            scope = '全队' if see_all else '全部'
+        lines = ['执行 %s 的任务 [%s, %d 个]:' % (eid, scope, len(items))]
+        for t in items:
+            if isinstance(t, dict):
+                acc = _assignee_account(t)
+                mine_flag = '' if filter_mine else ('  [我]' if acc == MY_ACCOUNT else '  [队友]')
+                lines.append('  [#%s] %s (assignedTo=%s status=%s)%s' % (
+                    t.get('id'), str(t.get('name', ''))[:25],
+                    acc, t.get('status', ''), mine_flag))
+            else:
+                lines.append('  ' + str(t)[:60])
+        return '\n'.join(lines)
+
+    @tool("get_task",
+          "查任务详情(含工时:预计/消耗/剩余)。例: get_task(task_id=301)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+          }, "required": ["task_id"]})
+    def _t_get_task(self, args):
+        tid = args.get('task_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/tasks/%s' % tid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        t = r.json()
+        asg = _assignee_account(t) or '空'
+        opn = _openedby_account(t) or '空'
+        return ('任务 #%s: %s\n状态: %s | 类型: %s | 优先级: %s\n'
+                '指派: %s | 创建: %s\n'
+                '工时: 预计=%s 消耗=%s 剩余=%s\n截止: %s\n需求: %s 执行: %s') % (
+            tid, t.get('name', ''), t.get('status', ''), t.get('type', ''),
+            t.get('pri', ''), asg, opn,
+            t.get('estimate', ''), t.get('consumed', ''), t.get('left', ''),
+            t.get('deadline', ''), t.get('story', ''), t.get('execution', ''))
+
+    @tool("create_task",
+          "创建任务(组长拆需求为任务)。必填: execution, name, assignedTo。可选 type(devel/test/design等), pri, estimate(预计工时h), deadline, story(关联需求)。权限不足返回提示不报错。例: create_task(execution_id=73, name='导出PDF接口', assignedTo='zhangsan', type='devel', estimate=6, story=761)",
+          {"type": "object", "properties": {
+              "execution_id": {"type": "integer", "description": "执行ID"},
+              "name": {"type": "string", "description": "任务名称"},
+              "assignedTo": {"type": "string", "description": "指派给(禅道账号, 不填默认指派给当前开发者自己)"},
+              "type": {"type": "string", "description": "类型: devel(开发)/test(测试)/design(设计)/discuss(讨论)/study(研究)等, 默认devel"},
+              "pri": {"type": "integer", "description": "优先级 1-4(默认3)"},
+              "estimate": {"type": "number", "description": "预计工时(小时)"},
+              "deadline": {"type": "string", "description": "截止日期 YYYY-MM-DD(可选)"},
+              "story": {"type": "integer", "description": "关联需求ID(可选)"},
+              "desc": {"type": "string", "description": "任务描述(可选)"},
+          }, "required": ["execution_id", "name"]})
+    def _t_create_task(self, args):
+        eid = args.get('execution_id', 0)
+        name = args.get('name', '')
+        # 默认指派给当前开发者 (防共享账号误派给别人); 显式传 assignedTo 才派别人
+        assignedTo = args.get('assignedTo') or MY_ACCOUNT
+        if not eid or not name or not assignedTo:
+            return '⚠️ 缺少必填字段: execution_id/name 必填, assignedTo 不填则需先配 member.json 的 zentao_account。'
+        payload = {'execution': eid, 'name': name, 'assignedTo': assignedTo,
+                   'type': args.get('type', 'devel'), 'pri': args.get('pri', 3)}
+        for k in ('estimate', 'deadline', 'story', 'desc'):
+            if args.get(k) is not None:
+                payload[k] = args[k]
+        return self._safe_write(
+            'POST', '/tasks', payload,
+            lambda d: '✅ 任务已创建! ID=%s\n禅道地址: %s/task-view-%s.html' % (
+                d.get('id', '?'), ZENTAO_URL.rstrip('/'), d.get('id', '?')),
+            '可能权限不足或字段缺失')
+
+    @tool("update_task",
+          "修改任务(名称/指派/工时/截止等)。权限不足返回提示不报错。例: update_task(task_id=301, name='导出PDF接口(改)', left=3)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+              "name": {"type": "string", "description": "新名称(可选)"},
+              "assignedTo": {"type": "string", "description": "新指派(可选)"},
+              "estimate": {"type": "number", "description": "预计工时(可选)"},
+              "left": {"type": "number", "description": "剩余工时(可选)"},
+              "deadline": {"type": "string", "description": "截止日期(可选)"},
+          }, "required": ["task_id"]})
+    def _t_update_task(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        payload = {}
+        for k in ('name', 'assignedTo', 'estimate', 'left', 'deadline'):
+            if args.get(k) is not None:
+                payload[k] = args[k]
+        if not payload:
+            return '⚠️ 没有要更新的字段(可选: name/assignedTo/estimate/left/deadline)。'
+        return self._safe_write(
+            'PUT', '/tasks/%s' % tid, payload,
+            '✅ 任务 #%s 已更新' % tid,
+            '可能权限不足或字段缺失')
+
+    @tool("delete_task",
+          "删除任务。权限不足返回提示不报错。例: delete_task(task_id=301)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+          }, "required": ["task_id"]})
+    def _t_delete_task(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'DELETE', '/tasks/%s' % tid, None,
+            '✅ 任务 #%s 已删除' % tid,
+            '可能权限不足或状态不允许删除')
+
+    @tool("assign_task",
+          "指派任务给某人。权限不足返回提示不报错。例: assign_task(task_id=301, account='lisi')",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+              "account": {"type": "string", "description": "禅道账号"},
+          }, "required": ["task_id", "account"]})
+    def _t_assign_task(self, args):
+        tid = args.get('task_id', 0)
+        account = args.get('account', '')
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'POST', '/tasks/%s/assign' % tid, {'assignedTo': account},
+            '✅ 任务 #%s 已指派给 %s' % (tid, account),
+            '可能权限不足, 需在禅道手动指派')
+
+    @tool("start_task",
+          "开始任务(未开始→进行中)。需填剩余工时left。权限不足返回提示不报错。例: start_task(task_id=301, left=6)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+              "left": {"type": "number", "description": "剩余工时(小时, 默认取预计)"},
+              "consumed": {"type": "number", "description": "已消耗工时(默认0)"},
+          }, "required": ["task_id"]})
+    def _t_start_task(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        payload = {}
+        if args.get('left') is not None:
+            payload['left'] = args['left']
+        if args.get('consumed') is not None:
+            payload['consumed'] = args['consumed']
+        return self._safe_write(
+            'POST', '/tasks/%s/start' % tid, payload,
+            '✅ 任务 #%s 已开始' % tid,
+            '可能权限不足或当前状态不允许开始')
+
+    @tool("pause_task",
+          "暂停任务(进行中→已暂停)。权限不足返回提示不报错。例: pause_task(task_id=301)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+          }, "required": ["task_id"]})
+    def _t_pause_task(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'POST', '/tasks/%s/pause' % tid, {},
+            '✅ 任务 #%s 已暂停' % tid,
+            '可能权限不足或当前状态不允许暂停')
+
+    @tool("restart_task",
+          "继续任务(已暂停→进行中)。可填剩余工时。权限不足返回提示不报错。例: restart_task(task_id=301, left=4)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+              "left": {"type": "number", "description": "剩余工时(可选)"},
+          }, "required": ["task_id"]})
+    def _t_restart_task(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        payload = {}
+        if args.get('left') is not None:
+            payload['left'] = args['left']
+        return self._safe_write(
+            'POST', '/tasks/%s/restart' % tid, payload,
+            '✅ 任务 #%s 已继续' % tid,
+            '可能权限不足或当前状态不允许继续')
+
+    @tool("finish_task",
+          "完成任务(进行中→已完成)。需填消耗工时consumed和剩余0。权限不足返回提示不报错。例: finish_task(task_id=301, consumed=6)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+              "consumed": {"type": "number", "description": "本次消耗工时(小时)"},
+              "left": {"type": "number", "description": "剩余工时(完成时填0, 默认0)"},
+          }, "required": ["task_id"]})
+    def _t_finish_task(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        payload = {'left': args.get('left', 0)}
+        if args.get('consumed') is not None:
+            payload['consumed'] = args['consumed']
+        return self._safe_write(
+            'POST', '/tasks/%s/finish' % tid, payload,
+            '✅ 任务 #%s 已完成' % tid,
+            '可能权限不足或当前状态不允许完成')
+
+    @tool("close_task",
+          "关闭任务(已完成→已关闭, 通常由负责人确认)。权限不足返回提示不报错。例: close_task(task_id=301)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+          }, "required": ["task_id"]})
+    def _t_close_task(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'PUT', '/tasks/%s/close' % tid, {},
+            '✅ 任务 #%s 已关闭' % tid,
+            '可能权限不足或当前状态不允许关闭')
+
+    @tool("log_effort",
+          "记录任务工时(每日填写消耗/剩余)。权限不足返回提示不报错。例: log_effort(task_id=301, consumed=2, left=4)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+              "consumed": {"type": "number", "description": "本次消耗工时(小时)"},
+              "left": {"type": "number", "description": "剩余工时(小时)"},
+          }, "required": ["task_id", "consumed", "left"]})
+    def _t_log_effort(self, args):
+        tid = args.get('task_id', 0)
+        guard = self._assert_owner('task', tid)
+        if guard:
+            return guard
+        payload = {'consumed': args.get('consumed', 0), 'left': args.get('left', 0)}
+        return self._safe_write(
+            'POST', '/tasks/%s/estimate' % tid, payload,
+            '✅ 任务 #%s 已记录工时 (消耗%s 剩余%s)' % (tid, payload['consumed'], payload['left']),
+            '可能权限不足')
+
+    @tool("list_effort",
+          "查任务的工时记录。例: list_effort(task_id=301)",
+          {"type": "object", "properties": {
+              "task_id": {"type": "integer", "description": "任务ID"},
+          }, "required": ["task_id"]})
+    def _t_list_effort(self, args):
+        tid = args.get('task_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/tasks/%s/estimate' % tid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        data = r.json()
+        efforts = []
+        for k in ('efforts', 'estimates', 'records'):
+            if isinstance(data.get(k), list):
+                efforts = data[k]
+                break
+        if not efforts:
+            return '任务 #%s 暂无工时记录。' % tid
+        lines = ['任务 #%s 的工时 (%d 条):' % (tid, len(efforts))]
+        for e in efforts:
+            lines.append('  %s 消耗=%s 剩余=%s (%s)' % (
+                e.get('date', ''), e.get('consumed', ''), e.get('left', ''),
+                e.get('account', '')))
+        return '\n'.join(lines)
+
+    # ── Bug (8) ── ★"加BUG" ───────────────────────────────────────────
+
+    @tool("list_bugs",
+          "查Bug列表(产品或执行维度)。默认只看指派给我的(assignedTo=我), 防看错队友; 要看全队加 all=true。★查'我的全部Bug(跨产品)'请用 list_my_bugs 或 my_workbench。例: list_bugs(product_id=1) / list_bugs(execution_id=73, all=true)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID(与execution_id二选一)"},
+              "execution_id": {"type": "integer", "description": "执行ID(与product_id二选一)"},
+              "limit": {"type": "integer", "description": "返回数量(默认20)"},
+              "all": {"type": "boolean", "description": "true=看全队(默认false只看我的)"},
+          }})
+    def _t_list_bugs(self, args):
+        limit = args.get('limit', 20)
+        see_all = bool(args.get('all', False))
+        filter_mine = not see_all
+        if args.get('execution_id'):
+            path = '/executions/%s/bugs' % args['execution_id']
+            scope = '执行 %s' % args['execution_id']
+        else:
+            pid = args.get('product_id', 1)
+            path = '/products/%s/bugs' % pid
+            scope = '产品 %s' % pid
+        # 归属铁门 (v3.1.5 起拒绝而非静默降级)
+        if filter_mine:
+            guard = self._require_my_account()
+            if guard:
+                return guard
+        else:
+            r = self._gate()
+            if r:
+                return r
+        resp = _api('GET', path, {'limit': limit})
+        if resp.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(resp)
+        data = resp.json()
+        items = data.get('bugs') if isinstance(data, dict) else data
+        if not isinstance(items, list):
+            topkeys = list(data.keys()) if isinstance(data, dict) else type(data).__name__
+            return '%s 的Bug响应无 bugs 字段 (顶层 keys: %s)。' % (scope, topkeys)
+        if not items:
+            return '%s 暂无Bug。' % scope
+        if filter_mine:
+            total = len(items)
+            # v3.1.6: "我的Bug" = 指派给我 OR 我提的 (团队习惯提了不指派, assignedTo 常为空)
+            items = [b for b in items if isinstance(b, dict) and (
+                _assignee_account(b) == MY_ACCOUNT or _openedby_account(b) == MY_ACCOUNT)]
+            scope = '%s [我的(指派给我或我提的, %s)]' % (scope, MY_ACCOUNT)
+            if not items:
+                return '%s 没有指派给你或你提的Bug。\n(全队 %d 个, 要看全队加 all=true)' % (scope, MY_ACCOUNT, total)
+        else:
+            scope = '%s [%s]' % (scope, '全队' if see_all else '全部')
+        lines = ['%s 的Bug (%d 个):' % (scope, len(items))]
+        for b in items:
+            if isinstance(b, dict):
+                asg = _assignee_account(b)
+                opn = _openedby_account(b)
+                # 归属来源标记: 区分"指派给我"和"我提的"
+                if filter_mine:
+                    tag = '  [指派给我]' if asg == MY_ACCOUNT else ('  [我提的]' if opn == MY_ACCOUNT else '')
+                else:
+                    tag = ('  [指派给我]' if asg == MY_ACCOUNT else
+                           ('  [我提的]' if opn == MY_ACCOUNT else '  [队友]'))
+                asg_show = asg or ('(空,我提的)' if opn == MY_ACCOUNT and not asg else asg)
+                lines.append('  [#%s] %s (severity=%s status=%s assignedTo=%s)%s' % (
+                    b.get('id'), str(b.get('title', ''))[:25],
+                    b.get('severity', ''), b.get('status', ''), asg_show, tag))
+        return '\n'.join(lines) if items else '%s 暂无Bug。' % scope
+
+    @tool("get_bug",
+          "查Bug详情。例: get_bug(bug_id=101)",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+          }, "required": ["bug_id"]})
+    def _t_get_bug(self, args):
+        bid = args.get('bug_id', 0)
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/bugs/%s' % bid)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        b = r.json()
+        asg = _assignee_account(b) or '空'
+        opn = _openedby_account(b) or '空'
+        return ('Bug #%s: %s\n状态: %s | 严重度: %s | 优先级: %s | 解决方案: %s\n'
+                '指派: %s | 创建: %s | 影响版本: %s | 解决版本: %s\n'
+                '关联需求: %s | 类型: %s\n描述: %s') % (
+            bid, b.get('title', ''), b.get('status', ''),
+            b.get('severity', ''), b.get('pri', ''), b.get('resolution', ''),
+            asg, opn, b.get('openedBuild', ''), b.get('resolvedBuild', ''),
+            b.get('story', ''),
+            b.get('type', ''), str(b.get('steps', ''))[:200])
+
+    @tool("create_bug",
+          "提Bug。必填: product, title, openedBuild(影响版本)。可选 severity(1-4,1最严重), pri(1-4), type, story(关联需求), assignedTo。权限不足返回提示不报错。例: create_bug(product_id=1, title='导出PDF乱码', openedBuild='8', severity=2, story=761)",
+          {"type": "object", "properties": {
+              "product_id": {"type": "integer", "description": "产品ID"},
+              "title": {"type": "string", "description": "Bug标题"},
+              "openedBuild": {"type": "string", "description": "影响版本(build ID 或名称)"},
+              "steps": {"type": "string", "description": "重现步骤(可选)"},
+              "severity": {"type": "integer", "description": "严重度 1-4(1最严重, 默认3)"},
+              "pri": {"type": "integer", "description": "优先级 1-4(默认3)"},
+              "type": {"type": "string", "description": "类型: codegen/interface/config/security等, 默认codeerror"},
+              "story": {"type": "integer", "description": "关联需求ID(可选)"},
+              "assignedTo": {"type": "string", "description": "指派给(可选)"},
+          }, "required": ["product_id", "title", "openedBuild"]})
+    def _t_create_bug(self, args):
+        pid = args.get('product_id', 1)
+        title = args.get('title', '')
+        openedBuild = args.get('openedBuild', '')
+        if not title or not openedBuild:
+            return '⚠️ 缺少必填字段: title 和 openedBuild(影响版本) 都不能为空。'
+        # v3.1.6: 默认指派给提交人 (当前开发者), 防提交后 assignedTo=None 查不到自己的 bug
+        # (历史踩坑: 不传 assignedTo → 禅道默认空 → 用户"明明提了 bug"却查不到)
+        assignedTo = args.get('assignedTo') or MY_ACCOUNT
+        payload = {'title': title, 'openedBuild': openedBuild,
+                   'severity': args.get('severity', 3), 'pri': args.get('pri', 3),
+                   'type': args.get('type', 'codeerror'), 'assignedTo': assignedTo}
+        if args.get('steps'):
+            payload['steps'] = args['steps']
+        if args.get('story'):
+            payload['story'] = args['story']
+        return self._safe_write(
+            'POST', '/products/%s/bugs' % pid, payload,
+            lambda d: '✅ Bug已提交! ID=%s (指派给 %s)\n禅道地址: %s/bug-view-%s.html' % (
+                d.get('id', '?'), assignedTo, ZENTAO_URL.rstrip('/'), d.get('id', '?')),
+            '可能权限不足或字段缺失')
+
+    @tool("update_bug",
+          "修改Bug(标题/严重度/影响版本等)。权限不足返回提示不报错。例: update_bug(bug_id=101, severity=2)",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+              "title": {"type": "string", "description": "新标题(可选)"},
+              "severity": {"type": "integer", "description": "新严重度 1-4(可选)"},
+              "pri": {"type": "integer", "description": "新优先级 1-4(可选)"},
+              "openedBuild": {"type": "string", "description": "新影响版本(可选)"},
+          }, "required": ["bug_id"]})
+    def _t_update_bug(self, args):
+        bid = args.get('bug_id', 0)
+        payload = {}
+        for k in ('title', 'severity', 'pri', 'openedBuild'):
+            if args.get(k) is not None:
+                payload[k] = args[k]
+        if not payload:
+            return '⚠️ 没有要更新的字段(可选: title/severity/pri/openedBuild)。'
+        return self._safe_write(
+            'PUT', '/bugs/%s' % bid, payload,
+            '✅ Bug #%s 已更新' % bid,
+            '可能权限不足或字段缺失')
+
+    @tool("delete_bug",
+          "删除Bug。权限不足返回提示不报错。例: delete_bug(bug_id=101)",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+          }, "required": ["bug_id"]})
+    def _t_delete_bug(self, args):
+        bid = args.get('bug_id', 0)
+        return self._safe_write(
+            'DELETE', '/bugs/%s' % bid, None,
+            '✅ Bug #%s 已删除' % bid,
+            '可能权限不足')
+
+    @tool("assign_bug",
+          "指派Bug给某人。权限不足返回提示不报错。例: assign_bug(bug_id=101, account='zhangsan')",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+              "account": {"type": "string", "description": "禅道账号"},
+          }, "required": ["bug_id", "account"]})
+    def _t_assign_bug(self, args):
+        bid = args.get('bug_id', 0)
+        account = args.get('account', '')
+        guard = self._assert_owner('bug', bid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'POST', '/bugs/%s/assign' % bid, {'assignedTo': account},
+            '✅ Bug #%s 已指派给 %s' % (bid, account),
+            '可能权限不足, 需在禅道手动指派')
+
+    @tool("confirm_bug",
+          "确认Bug(开发认领)。权限不足返回提示不报错。例: confirm_bug(bug_id=101)",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+          }, "required": ["bug_id"]})
+    def _t_confirm_bug(self, args):
+        bid = args.get('bug_id', 0)
+        guard = self._assert_owner('bug', bid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'POST', '/bugs/%s/confirm' % bid, {},
+            '✅ Bug #%s 已确认' % bid,
+            '可能权限不足或当前状态不允许确认')
+
+    @tool("resolve_bug",
+          "解决Bug(开发标记已修复)。可选 resolution(bydesign/duplicate/notrepro/postponed/willnotfix/codeerror), resolvedBuild(解决版本)。权限不足返回提示不报错。例: resolve_bug(bug_id=101, resolution='fixed', resolvedBuild='9')",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+              "resolution": {"type": "string", "description": "解决方案: fixed(已解决,默认)/bydesign/duplicate/notrepro/postponed/willnotfix"},
+              "resolvedBuild": {"type": "string", "description": "解决版本(build ID或名称)"},
+              "comment": {"type": "string", "description": "解决说明(可选)"},
+          }, "required": ["bug_id"]})
+    def _t_resolve_bug(self, args):
+        bid = args.get('bug_id', 0)
+        guard = self._assert_owner('bug', bid)
+        if guard:
+            return guard
+        payload = {'resolution': args.get('resolution', 'fixed')}
+        if args.get('resolvedBuild'):
+            payload['resolvedBuild'] = args['resolvedBuild']
+        if args.get('comment'):
+            payload['comment'] = args['comment']
+        return self._safe_write(
+            'POST', '/bugs/%s/resolve' % bid, payload,
+            '✅ Bug #%s 已解决' % bid,
+            '可能权限不足或当前状态不允许解决')
+
+    @tool("activate_bug",
+          "激活Bug(验证未通过,重新打开)。权限不足返回提示不报错。例: activate_bug(bug_id=101)",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+          }, "required": ["bug_id"]})
+    def _t_activate_bug(self, args):
+        bid = args.get('bug_id', 0)
+        guard = self._assert_owner('bug', bid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'POST', '/bugs/%s/activate' % bid, {},
+            '✅ Bug #%s 已激活' % bid,
+            '可能权限不足或当前状态不允许激活')
+
+    @tool("close_bug",
+          "关闭Bug(测试验证通过后关闭)。权限不足返回提示不报错。例: close_bug(bug_id=101)",
+          {"type": "object", "properties": {
+              "bug_id": {"type": "integer", "description": "Bug ID"},
+          }, "required": ["bug_id"]})
+    def _t_close_bug(self, args):
+        bid = args.get('bug_id', 0)
+        guard = self._assert_owner('bug', bid)
+        if guard:
+            return guard
+        return self._safe_write(
+            'PUT', '/bugs/%s/close' % bid, {},
+            '✅ Bug #%s 已关闭' % bid,
+            '可能权限不足或当前状态不允许关闭')
+
+    # ── 我的全景 (3) ── ★"看我的活" 跨执行/产品全量聚合 ──────────────────
+    # 禅道无 "assignedTo=我的全部任务" 单接口, 这里全量扫描聚合。
+    # 旧工作流逐执行查会漏 (用户实测: 61 执行只查 12 个, 漏 9 个未开始任务)。
+
+    @tool("my_workbench",
+          "★我的禅道工作台: 一次返回指派给我的【任务+需求+Bug】, 跨所有执行/产品全量聚合, 按紧急度排序。"
+          "回答'我手头有什么活/我的任务/这周干啥/我的禅道'直接用这个, 不要逐执行查。"
+          "例: my_workbench()",
+          {"type": "object", "properties": {
+              "include_closed": {"type": "boolean", "description": "true=含已关闭/取消历史项(默认false只看活的)"},
+          }})
+    def _t_my_workbench(self, args):
+        guard = self._require_my_account()
+        if guard:
+            return guard
+        include_closed = bool(args.get('include_closed', False))
+        # 并行收集三域 (内部串行调 _api, 但每个都是必要查询)
+        tasks, terr = self._collect_my_tasks()
+        if terr:
+            return terr
+        bugs, berr = self._collect_my_bugs()
+        if berr:
+            return berr
+        stories, serr = self._collect_my_stories()
+        if serr:
+            return serr
+
+        # 过滤掉终态 (除非显式要看历史)
+        LIVE_TASK = {'wait', 'doing', 'pause'}
+        LIVE_BUG = {'active', 'resolved'}
+        if not include_closed:
+            tasks = [t for t in tasks if t.get('status') in LIVE_TASK]
+            bugs = [b for b in bugs if b.get('status') in LIVE_BUG]
+            stories = [s for s in stories if s.get('status') not in ('closed',)]
+
+        lines = ['📋 我(%s)的禅道工作台 — 任务 %d · 需求 %d · Bug %d' % (
+            MY_ACCOUNT, len(tasks), len(stories), len(bugs))]
+
+        # ── 任务 (按状态分组: 进行中 > 未开始) ──
+        if tasks:
+            doing = [t for t in tasks if t.get('status') == 'doing']
+            waiting = [t for t in tasks if t.get('status') in ('wait', 'pause')]
+            if doing:
+                lines.append('\n🔴 进行中 (%d):' % len(doing))
+                for t in doing:
+                    lines.append('  ' + self._fmt_task_line(t))
+            if waiting:
+                lines.append('\n🟡 未开始 (%d):' % len(waiting))
+                for t in waiting:
+                    lines.append('  ' + self._fmt_task_line(t))
+        else:
+            lines.append('\n✅ 没有指派给你的活动任务。')
+
+        # ── 需求 ──
+        if stories:
+            lines.append('\n🔵 指派给我的需求 (%d):' % len(stories))
+            for s in stories:
+                lines.append('  [#%s] %s (status=%s pri=%s)' % (
+                    s.get('id'), str(s.get('title', ''))[:32], s.get('status'), s.get('pri')))
+        # 需求为空不单独提示 (任务段已给总览)
+
+        # ── Bug ──
+        if bugs:
+            lines.append('\n🐛 我的Bug (%d, 指派给我或我提的):' % len(bugs))
+            for b in bugs:
+                lines.append('  [#%s] %s (severity=%s status=%s) [%s]' % (
+                    b.get('id'), str(b.get('title', ''))[:32], b.get('severity'),
+                    b.get('status'), b.get('_why', '')))
+
+        # 提示下一步
+        n_active = len([t for t in tasks if t.get('status') in ('doing', 'wait')])
+        lines.append('\n💡 下一步: 说"看任务#XXXX详情" / "开始做#XXXX" / "看需求#XXXX"')
+        if not include_closed:
+            lines.append('   (以上只列活动项; 看含已取消的历史加 include_closed=true)')
+        return '\n'.join(lines)
+
+    def _fmt_task_line(self, t):
+        """格式化任务为一行 (带工时/截止/执行提示)。"""
+        extras = []
+        if t.get('pri'):
+            extras.append('P%s' % t.get('pri'))
+        if t.get('left'):
+            extras.append('余%s h' % t.get('left'))
+        if t.get('deadline'):
+            extras.append('截止%s' % t.get('deadline'))
+        suffix = (' (' + ' '.join(extras) + ')') if extras else ''
+        ename = str(t.get('execution_name', ''))[:12]
+        return '[#%s] %s%s  ←执行%s' % (
+            t.get('id'), str(t.get('name', ''))[:34], suffix, ename)
+
+    @tool("list_my_tasks",
+          "查指派给我的全部任务(跨所有执行, 全量不漏)。支持按状态过滤。"
+          "★回答'我的全部任务'用这个; 只看某执行用 list_execution_tasks。"
+          "例: list_my_tasks() / list_my_tasks(status='wait') / list_my_tasks(status='doing')",
+          {"type": "object", "properties": {
+              "status": {"type": "string", "description": "只看某状态: wait(未开始)/doing(进行中)/pause/done/closed/cancel。不填=全部"},
+          }})
+    def _t_list_my_tasks(self, args):
+        guard = self._require_my_account()
+        if guard:
+            return guard
+        status_filter = args.get('status')
+        tasks, err = self._collect_my_tasks(status_filter=status_filter)
+        if err:
+            return err
+        if not tasks:
+            hint = '状态=%s' % status_filter if status_filter else '任何状态'
+            return '没有指派给你(%s)的任务(%s)。' % (MY_ACCOUNT, hint)
+        # 按状态分组打印
+        from collections import OrderedDict
+        order = ['doing', 'wait', 'pause', 'done', 'closed', 'cancel']
+        grouped = OrderedDict((s, []) for s in order)
+        for t in tasks:
+            grouped.setdefault(t.get('status'), []).append(t)
+        lines = ['我的任务(%s) 共 %d 个:' % (MY_ACCOUNT, len(tasks))]
+        for st, arr in grouped.items():
+            if not arr:
+                continue
+            label = {'doing': '🔴 进行中', 'wait': '🟡 未开始', 'pause': '⏸ 暂停',
+                     'done': '✅ 已完成', 'closed': '🔒 已关闭', 'cancel': '⚫ 已取消'}.get(st, st)
+            lines.append('\n%s (%d):' % (label, len(arr)))
+            for t in arr:
+                lines.append('  ' + self._fmt_task_line(t))
+        lines.append('\n💡 说"看任务#XXXX详情"或"开始做#XXXX"')
+        return '\n'.join(lines)
+
+    @tool("list_my_bugs",
+          "查'我的'全部Bug(跨所有产品, 全量不漏)——指派给我的 或 我提的都算。"
+          "★回答'我的全部Bug'用这个; 只看某产品用 list_bugs。例: list_my_bugs()",
+          {"type": "object", "properties": {}})
+    def _t_list_my_bugs(self, args):
+        guard = self._require_my_account()
+        if guard:
+            return guard
+        bugs, err = self._collect_my_bugs()
+        if err:
+            return err
+        if not bugs:
+            return '没有指派给你(%s)或你提的Bug。' % MY_ACCOUNT
+        # 按状态分组
+        from collections import OrderedDict
+        order = ['active', 'resolved', 'closed']
+        grouped = OrderedDict((s, []) for s in order)
+        for b in bugs:
+            grouped.setdefault(b.get('status'), []).append(b)
+        lines = ['我的Bug(%s) 共 %d 个 (指派给我 或 我提的):' % (MY_ACCOUNT, len(bugs))]
+        for st, arr in grouped.items():
+            if not arr:
+                continue
+            label = {'active': '🐛 待解决', 'resolved': '🛠 已解决待验证',
+                     'closed': '✅ 已关闭'}.get(st, st)
+            lines.append('\n%s (%d):' % (label, len(arr)))
+            for b in arr:
+                why = b.get('_why', '')
+                lines.append('  [#%s] %s (severity=%s 产品%s) [%s]' % (
+                    b.get('id'), str(b.get('title', ''))[:32], b.get('severity'),
+                    b.get('product_id'), why))
+        lines.append('\n💡 说"看Bug#XXXX"或"Bug解决了"')
+        return '\n'.join(lines)
+
+    # ── 用户 User (2) ── (指派任务/Bug 必须知道有哪些账号) ─────────────
+
+    @tool("list_users",
+          "查禅道用户列表(指派任务/Bug时选账号)。例: list_users()",
+          {"type": "object", "properties": {}})
+    def _t_list_users(self, args):
+        return self._safe_get(
+            '/users', None,
+            '禅道用户 (%d 个):',
+            lambda u: '  %s (%s role=%s)' % (
+                u.get('account', ''), str(u.get('realname', ''))[:10], u.get('role', '')),
+            empty_msg='禅道暂无用户。',
+        )
+
+    @tool("get_user",
+          "查用户详情。例: get_user(account='hupan')",
+          {"type": "object", "properties": {
+              "account": {"type": "string", "description": "禅道账号"},
+          }, "required": ["account"]})
+    def _t_get_user(self, args):
+        account = args.get('account', '')
+        gate = self._gate()
+        if gate:
+            return gate
+        r = _api('GET', '/users/%s' % account)
+        if r.status_code not in (200, 201):
+            return '查询失败: %s' % _err_text(r)
+        u = r.json()
+        return '用户 %s: %s\n角色: %s\n部门: %s\n邮箱: %s' % (
+            account, u.get('realname', ''), u.get('role', ''),
+            u.get('dept', ''), u.get('email', ''))
+
+    def on_initialize_hook(self, info):
+        # 启动时内网校验, 不通塞 warning (与旧版行为一致)
+        ok, msg = check_intranet()
+        if not ok:
+            info['warning'] = msg
+
+
+if __name__ == '__main__':
+    ZentaoMCPServer().run()