@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/{team_sync.py → domain/task/team_sync.py}

@@ -1,5 +1,16 @@
 #!/usr/bin/env python3
 # -*- 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()
+
 """
 QODER Team Sync - 无感 git 同步引擎
 
@@ -34,8 +45,8 @@ if sys.platform == 'win32':
         pass
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from common.paths import get_repo_root, get_developer
-from common.filelock import FileLock, LockTimeoutError
+from foundation.core.paths import get_repo_root, get_developer
+from foundation.io.filelock import FileLock, LockTimeoutError
 from syncgate import run_gates, SAFE_EXTENSIONS
 
 BASE = str(get_repo_root())
@@ -49,16 +60,31 @@ PUSH_LOCK = os.path.join(BASE, '.qoder', '.runtime', 'team-sync.lock')
 MAX_PUSH_RETRY = 3
 
 
-def git(*args, check=False):
-    """git 命令包装。git 未安装时返回 rc=127 的伪结果, 不崩溃。"""
+def git(*args, check=False, timeout=None):
+    """git 命令包装。git 未安装时返回 rc=127 的伪结果, 不崩溃。
+
+    timeout: 网络/远程操作 (fetch/pull/push/clone) 必须传, 防止认证提示或网络
+    挂起导致整个 sync 无限阻塞。本地操作 (add/commit/status/diff) 不需要。
+    用法: git('fetch', 'origin', timeout=60)
+    """
     try:
-        r = subprocess.run(['git'] + list(args), cwd=BASE, capture_output=True,
-                           text=True, encoding='utf-8', errors='replace')
+        kw = dict(cwd=BASE, capture_output=True, text=True, encoding='utf-8', errors='replace')
+        if timeout:
+            kw['timeout'] = timeout
+        r = subprocess.run(['git'] + list(args), **kw)
     except FileNotFoundError:
         # git 未安装 — 返回伪 CompletedProcess, 让上层把"无 git"当"无远端/无仓库"处理
         import types
         r = types.SimpleNamespace(returncode=127, stdout='', stderr='git not installed',
                                   encoding='utf-8')
+    except subprocess.TimeoutExpired:
+        # 网络操作超时 (常见: 远程要认证但凭证没缓存 / 网络不通)
+        # 返回 rc=124 (与 timeout 命令一致), 不让整个 sync 挂死
+        import types
+        cmd_hint = ' '.join(args[:3])
+        r = types.SimpleNamespace(returncode=124, stdout='',
+                                  stderr='git {} timed out after {}s (网络/认证问题)'.format(cmd_hint, timeout),
+                                  encoding='utf-8')
     if check and r.returncode != 0:
         print('git {} failed: {}'.format(' '.join(args), r.stderr.strip()[:300]))
     return r
@@ -93,7 +119,7 @@ def _notify_prd_publications(staged_files):
     """
     import re as _re
     try:
-        from common.feishu import notify_prd_published, is_enabled
+        from foundation.integrations.feishu import notify_prd_published, is_enabled
     except ImportError as e:
         print('[sync] WARN: feishu 模块缺失, 跳过 PRD 发布通知: %s' % e, file=sys.stderr)
         return
@@ -204,7 +230,8 @@ def _auto_resolve_kg_conflict():
 
 
 def do_pull(quiet=False):
-    """拉取团队最新。安全: autostash 保护未提交改动。"""
+    """拉取团队最新。安全: autostash 保护未提交改动 + 文件锁防与 push 竞态。"""
+    # 前置检查(不需锁): 远程/rebase 状态快速失败, 避免占锁后才发现问题
     if rebase_in_progress():
         print('SYNC_CONFLICT: 仓库处于未完成的 rebase 状态, AI 请先处理 (git rebase --abort 或 --continue)。')
         return 3
@@ -219,8 +246,31 @@ def do_pull(quiet=False):
         print('ERROR: detached HEAD or no branch - AI please check.')
         return 1
 
-    r = git('pull', '--rebase', '--autostash', 'origin', branch)
+    # === 文件锁: 与 do_push 互斥。pull --rebase --autostash 会动工作区 + index,
+    # 若与锁内的 _stage_scopes_safely (git add) 交叉会产生半 staged 状态。 ===
+    os.makedirs(os.path.dirname(PUSH_LOCK), exist_ok=True)
+    try:
+        lock_ctx = FileLock(PUSH_LOCK, timeout=60, stale_seconds=300)
+        lock_ctx.acquire()
+    except LockTimeoutError as e:
+        print('SYNC_BUSY: 另一个同步正在进行, 等待超时。稍后重试。')
+        print('  ' + str(e))
+        return 2  # lock contention
+
+    try:
+        return _do_pull_locked(quiet, branch)
+    finally:
+        lock_ctx.release()
+
+
+def _do_pull_locked(quiet, branch):
+    """锁内的实际 pull 逻辑。"""
+    r = git('pull', '--rebase', '--autostash', 'origin', branch, timeout=90)
     if r.returncode != 0:
+        if r.returncode == 124:
+            print('Pull 超时 (网络/认证问题): ' + (r.stderr or '').strip()[:150])
+            print('检查 git 凭证或团队仓库连通性。继续离线工作, 下次同步自动补推。')
+            return 1
         if 'CONFLICT' in (r.stdout + r.stderr) or rebase_in_progress():
             return report_conflict(r.stderr or r.stdout)
         print('Pull failed (network/remote?): ' + (r.stderr or r.stdout).strip()[:200])
@@ -282,22 +332,25 @@ def _stage_scopes_safely(skip_secret=False):
     只 stage SYNC_SCOPES 下、扩展名在 SAFE_EXTENSIONS 里的文件。
     其他文件 (如误放的 .env/.zip/.docx) 被跳过并打印警告。
 
+    性能: 收集后批量 git add (每批 ~400 个), 避免 N 个文件 = N 次 git 进程 fork。
+    50 人团队大改动 (数百文件) 时, 逐文件 add 在 Windows CreateProcess 开销下
+    会很慢。批量后 push 阶段从 O(N 次 fork) 降到 O(N/400 次 fork)。
+
     Returns:
         (staged_count, skipped_files)
     """
-    staged = 0
+    to_add = []  # 待批量 add 的文件 (已收集, 一次性分批 add)
     skipped = []
     for scope in SYNC_SCOPES:
         scope_path = os.path.join(BASE, scope)
         if not os.path.isdir(scope_path):
             continue
         # 用 git ls-files 拿已跟踪的 + git status 拿未跟踪的, 逐个判断扩展名
-        # 已跟踪文件: 直接 add (它们已经在版本控制, 不可能是新秘密)
+        # 已跟踪文件: 收集 (它们已经在版本控制, 不可能是新秘密)
         r = git('ls-files', '--', scope)
-        tracked = [f for f in r.stdout.strip().splitlines() if f.strip()]
-        for f in tracked:
-            git('add', '--', f)
-            staged += 1
+        for f in r.stdout.strip().splitlines():
+            if f.strip():
+                to_add.append(f)
         # 未跟踪的新文件: 按扩展名过滤
         r = git('status', '--porcelain', '--', scope)
         for line in r.stdout.strip().splitlines():
@@ -313,17 +366,24 @@ def _stage_scopes_safely(skip_secret=False):
                 if 'brainstorm-agent' in basename:
                     skipped.append(fpath + ' (brainstorm 中间文件, 不提交)')
                 elif ext in SAFE_EXTENSIONS:
-                    git('add', '--', fpath)
-                    staged += 1
+                    to_add.append(fpath)
                 else:
                     skipped.append(fpath)
             elif 'D' not in status:
-                # 修改/重命名等 (非删除) —— 已跟踪, 直接 add
+                # 修改/重命名等 (非删除) —— 已跟踪, 收集
                 # 重命名格式 "R  old -> new", 取 new
                 if '->' in fpath:
                     fpath = fpath.split('->')[-1].strip().strip('"')
-                git('add', '--', fpath)
-                staged += 1
+                to_add.append(fpath)
+
+    # 批量 add: 每批最多 400 个文件 (防命令行长度溢出, Windows ~8191 字符限制留余量)
+    BATCH = 400
+    staged = 0
+    for i in range(0, len(to_add), BATCH):
+        batch = to_add[i:i + BATCH]
+        git('add', '--', *batch)
+        staged += len(batch)
+
     if skipped:
         print('[gate] 跳过 {} 个非白名单文件 (可能含二进制/秘密, 手动处理):'.format(len(skipped)))
         for s in skipped[:10]:
@@ -410,7 +470,7 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
         return 1
 
     # 5. 检查是否有待推送的提交
-    git('fetch', 'origin', branch)
+    git('fetch', 'origin', branch, timeout=60)
     r = git('rev-list', '--count', 'origin/{}..HEAD'.format(branch))
     ahead = int(r.stdout.strip() or 0) if r.returncode == 0 else 1
     if ahead == 0:
@@ -420,7 +480,7 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
 
     # 6. pull --rebase + push, 失败重试
     for attempt in range(1, MAX_PUSH_RETRY + 1):
-        r = git('pull', '--rebase', '--autostash', 'origin', branch)
+        r = git('pull', '--rebase', '--autostash', 'origin', branch, timeout=90)
         if r.returncode != 0:
             # kg.duckdb 二进制冲突: 自动解决 (用户无感)
             _auto_resolve_kg_conflict()
@@ -437,11 +497,22 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
                 return report_conflict(r.stderr or r.stdout)
             # 非冲突的 pull 失败
             print('Pull failed (attempt {}): {}'.format(attempt, (r.stderr or r.stdout).strip()[:150]))
+            if r.returncode == 124:
+                print('  (网络/认证超时 — 检查 git 凭证或团队仓库连通性)')
+                break  # 网络挂起重试无意义, 直接退出
+            # 连接性失败 (unable to connect / Could not resolve) 重试也是浪费时间,
+            # 直接退出让用户离线工作, 别让 50 人团队的弱网用户干等 3 倍时间
+            err_txt = (r.stderr or r.stdout or '').lower()
+            if any(k in err_txt for k in ('unable to connect', 'could not resolve',
+                                          'connection refused', 'no route to host',
+                                          'network is unreachable', 'timed out')):
+                print('  (网络不通 — 产出已本地提交, 下次同步自动补推)')
+                break
             if rebase_in_progress():
                 git('rebase', '--abort')
             continue
 
-        r = git('push', 'origin', branch)
+        r = git('push', 'origin', branch, timeout=90)
         if r.returncode == 0:
             touch_pull_marker()
             print('Synced to team. (attempt {})'.format(attempt))
@@ -465,6 +536,13 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
                 pass  # 埋点失败不阻塞同步
             return 0
         if attempt < MAX_PUSH_RETRY:
+            # 网络不通重试无意义, 别让弱网用户干等 (push 超时/连接失败直接退出)
+            err_txt = (r.stderr or r.stdout or '').lower()
+            if r.returncode == 124 or any(k in err_txt for k in (
+                    'unable to connect', 'could not resolve', 'connection refused',
+                    'no route to host', 'network is unreachable', 'timed out')):
+                print('Push failed (网络不通): 产出已本地提交, 下次同步自动补推。')
+                return 1
             print('Push rejected (someone pushed first?), retrying...')
 
     print('Push failed after {} attempts: 产出已本地提交不会丢失, 下次同步自动补推。'.format(MAX_PUSH_RETRY))

package/templates/qoder/scripts/domain/task/zentao_sync.py

@@ -0,0 +1,370 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+zentao_sync.py - 本地任务 ↔ 禅道 双向同步（安全优先）
+
+设计目标 (回应团队最担心的「拉错/覆盖队友」):
+  - 拉取(禅道→本地): 强制 assignedTo == 我的禅道账号 过滤, 物理上拉不到队友任务。
+  - 推送(本地→禅道): 默认 --dry-run, 仅推 creator==我 的任务, 且禅道同名任务
+                     assignedTo 须与我一致才更新, 不一致拒绝 (防误改队友任务)。
+  - 幂等: task.json 的 zentao_id 做主键, 已有则跳过 create。
+
+隔离契约: contracts/isolation.md「禅道同步」红线。
+归属映射: member.json 的 zentao_account 字段 (本地 dev 名 ↔ 禅道 account)。
+
+用法:
+  python .qoder/scripts/domain/task/zentao_sync.py pull <execution_id> [--apply]   # 默认 dry-run 预览
+  python .qoder/scripts/domain/task/zentao_sync.py push [--execution_id N] [--apply]
+  python .qoder/scripts/domain/task/zentao_sync.py status                          # 看同步状态概览
+
+退出码:
+  0 成功 (含 dry-run 预览); 2 busy; 3 配置/归属错误; 4 权限拒绝; 5 网络不通
+"""
+import os
+import sys
+
+# ── 路径自举: 让脚本能独立运行 (复用 bootstrap 模式) ──
+# task_utils/identity 用相对导入 (.paths), 必须从 common 包上下文导入,
+# 因此把 scripts/ 加入 path, 用 common.xxx / task.xxx 访问。
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_SCRIPTS = os.path.dirname(_HERE)          # .qoder/scripts
+_COMMON = os.path.join(_SCRIPTS, 'foundation')
+for _p in (_SCRIPTS, _COMMON):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+try:
+    from bootstrap import setup; setup()
+except Exception:
+    pass
+
+import json
+import argparse
+
+from foundation.core.paths import get_repo_root, get_tasks_dir, get_developer
+from foundation.identity.identity import get_member
+from foundation.data.task_utils import modify_task_json, load_task_json, write_task_json
+from foundation.integrations.zentao_client import ZentaoClient
+from datetime import datetime
+from pathlib import Path
+
+
+def _create_local_task(repo_root, title, slug_seed, zentao_id, developer):
+    """直接创建本地任务目录 + task.json (含 zentao_id), 不走 cmd_create。
+
+    自包含, 避免 cmd_create 的 argparse Namespace 签名 + team_sync stage 副作用。
+    返回新建的 task_dir 或 None。"""
+    date_prefix = datetime.now().strftime("%m-%d")
+    tasks_dir = get_tasks_dir(repo_root)
+    task_dir_name = "%s-%s" % (date_prefix, slug_seed)
+    task_dir = tasks_dir / task_dir_name
+    if task_dir.exists():
+        # 撞名加后缀
+        task_dir_name = "%s-%s-%s" % (date_prefix, slug_seed, developer[:6])
+        task_dir = tasks_dir / task_dir_name
+    task_dir.mkdir(parents=True, exist_ok=True)
+    now_iso = datetime.now().isoformat()
+    task_data = {
+        "title": title, "slug": slug_seed, "status": "planning", "priority": "P2",
+        "assignee": developer, "creator": developer,
+        "created_at": now_iso, "updated_at": now_iso,
+        "branch": None, "base_branch": None, "scope": None,
+        "parent": None, "children": [], "tags": [],
+        "due_date": None, "start_date": None, "estimate_hours": None,
+        "blocked_by": [], "blocks": [],
+        "stage_ts": {"created": now_iso, "started": None, "completed": None},
+        "zentao_id": zentao_id,
+    }
+    if write_task_json(task_dir, task_data):
+        return task_dir
+    return None
+
+
+# ============================================================
+# 配置与归属解析
+# ============================================================
+
+def _zentao_creds():
+    """构建禅道客户端。凭据不全返回 None。
+    底层 HTTP 逻辑收敛在 common.zentao_client.ZentaoClient (与 mcp_server 共享)。"""
+    return ZentaoClient.from_config()
+
+
+def _resolve_my_account(developer):
+    """解析当前本地 developer → 禅道 account。
+    无 member.json 或无 zentao_account → 返回 (None, 原因)。"""
+    mem = get_member(developer)
+    if not mem:
+        return None, '当前开发者 %s 未注册 (无 member.json)。请先 /wl-init。' % developer
+    acc = (mem.get('zentao_account') or '').strip()
+    if not acc:
+        return None, ('%s 的 member.json 未配 zentao_account (本地名↔禅道账号映射)。'
+                      '\n  手动编辑 workspace/members/%s/member.json 加 "zentao_account": "你的禅道账号"。'
+                      % (developer, developer))
+    return acc, None
+
+
+# ============================================================
+# 禅道 HTTP 层已收敛到 common.zentao_client.ZentaoClient (与 mcp_server 共享同一份)
+# 下面 cmd_* 通过 creds (ZentaoClient 实例) 的 .api() / .check_intranet() 调用
+# ============================================================
+
+# ============================================================
+# 本地任务遍历
+# ============================================================
+
+def _iter_local_tasks(repo_root):
+    """遍历 workspace/tasks/*/task.json, yield (task_dir, data)。"""
+    tdir = get_tasks_dir(repo_root)
+    if not tdir.is_dir():
+        return
+    for child in sorted(tdir.iterdir()):
+        if not child.is_dir():
+            continue
+        data = load_task_json(child)
+        if data:
+            yield child, data
+
+
+# ============================================================
+# 拉取: 禅道 → 本地 (归属硬过滤)
+# ============================================================
+
+def cmd_pull(args, creds, my_account):
+    """拉取某执行下 assignedTo==我 的任务到本地。默认 dry-run。"""
+    eid = args.execution_id
+    print('═══ 拉取 执行 #%s (仅 assignedTo=%s) ═══' % (eid, my_account))
+    if not args.apply:
+        print('[DRY-RUN] 仅预览, 不写本地。加 --apply 才真写。\n')
+
+    r = creds.api('GET', '/executions/%s/tasks' % eid, {'limit': 100})
+    if r.status_code != 200:
+        print('查询失败: %s %s' % (r.status_code, r.text[:120]))
+        return 3
+    data = r.json()
+    tasks = data.get('tasks') if isinstance(data, dict) else None
+    if not isinstance(tasks, list):
+        print('响应格式异常 (无 tasks 列表)。')
+        return 3
+
+    # ── 归属硬过滤: 只取 assignedTo == 我 ──
+    mine = [t for t in tasks if isinstance(t, dict)
+            and str(t.get('assignedTo', '')) == my_account]
+    skipped = len(tasks) - len(mine)
+    print('执行 #%s 共 %d 个任务, 归属我的 %d 个 (跳过队友 %d 个, 不拉)。\n'
+          % (eid, len(tasks), len(mine), skipped))
+
+    if not mine:
+        print('没有归属你的任务, 无需同步。')
+        return 0
+
+    # 建立本地 zentao_id 索引 (防重复 create)
+    repo_root = get_repo_root()
+    existing_zids = {}
+    for td, d in _iter_local_tasks(repo_root):
+        zid = d.get('zentao_id')
+        if zid:
+            existing_zids[int(zid)] = td
+
+    created = skipped_dup = 0
+    for t in mine:
+        zid = int(t.get('id', 0))
+        name = str(t.get('name', ''))[:50]
+        status = t.get('status', '')
+        if zid in existing_zids:
+            print('  ⊘ 跳过 #%s「%s」(本地已有 zentao_id=%s)' % (zid, name, zid))
+            skipped_dup += 1
+            continue
+        if not args.apply:
+            print('  ＋ [将创建] #%s「%s」status=%s' % (zid, name, status))
+            created += 1
+            continue
+        # 真写: 直接创建本地任务 (含 zentao_id), 自包含不走 cmd_create
+        slug_seed = 'zentao-%s' % zid
+        new_dir = _create_local_task(repo_root, 'zentao#%s %s' % (zid, name),
+                                     slug_seed, zid, developer)
+        if new_dir:
+            print('  ✅ 创建 #%s「%s」并回填 zentao_id -> %s' % (zid, name, new_dir.name))
+            created += 1
+        else:
+            print('  ⚠️ 创建 #%s 失败' % zid)
+
+    print('\n小结: 创建 %d, 幂等跳过 %d, 队友任务跳过 %d。%s'
+          % (created, skipped_dup, skipped,
+             '(dry-run, 未真写)' if not args.apply else ''))
+    return 0
+
+
+# ============================================================
+# 推送: 本地 → 禅道 (默认 dry-run + 双校验)
+# ============================================================
+
+def cmd_push(args, creds, my_account, developer):
+    """推送本地 creator==我 的任务到禅道。默认 dry-run。"""
+    print('═══ 推送 本地 → 禅道 (仅 creator=%s, 强制 assignedTo=%s) ═══'
+          % (developer, my_account))
+    if not args.apply:
+        print('[DRY-RUN] 仅预览, 不写禅道。加 --apply 才真推。\n')
+
+    repo_root = get_repo_root()
+    candidates = []
+    for td, d in _iter_local_tasks(repo_root):
+        # ── 校验 1: 只推我创建的 (复用本地归属) ──
+        if (d.get('creator') or '') != developer:
+            continue
+        candidates.append((td, d))
+
+    if not candidates:
+        print('没有你创建的本地任务可推送。')
+        return 0
+
+    print('本地归属你的任务 %d 个:\n' % len(candidates))
+    pushed = skipped = 0
+    for td, d in candidates:
+        zid = d.get('zentao_id')
+        title = str(d.get('title', ''))[:50]
+        if zid:
+            # 已有 zentao_id → 更新前校验归属一致性
+            chk = creds.api('GET', '/tasks/%s' % zid)
+            if chk.status_code == 200:
+                remote_assign = str(chk.json().get('assignedTo', ''))
+                if remote_assign != my_account:
+                    print('  🚫 拒绝更新 #%s「%s」: 禅道 assignedTo=%s ≠ 你(%s)'
+                          '  (防误改队友任务)' % (zid, title, remote_assign, my_account))
+                    skipped += 1
+                    continue
+                if not args.apply:
+                    print('  ⟳ [将更新] #%s「%s」' % (zid, title))
+                    pushed += 1
+                    continue
+                payload = {'name': d.get('title', ''), 'assignedTo': my_account}
+                if d.get('estimate_hours'):
+                    payload['estimate'] = d['estimate_hours']
+                if d.get('due_date'):
+                    payload['deadline'] = d['due_date']
+                upd = creds.api('PUT', '/tasks/%s' % zid, payload)
+                print('  %s 更新 #%s「%s」%s'
+                      % ('✅' if upd.status_code in (200, 201) else '⚠️', zid, title,
+                         '' if upd.status_code in (200, 201) else '(%s)' % upd.status_code))
+                pushed += 1
+            else:
+                print('  ⚠️ 查询 #%s 失败 (%s), 跳过' % (zid, chk.status_code))
+                skipped += 1
+        else:
+            # 无 zentao_id → 新建 (强制 assignedTo=我)
+            if not args.execution_id:
+                print('  ⊙ 跳过「%s」(无 zentao_id, 且未给 --execution_id, 无法新建)'
+                      % title)
+                skipped += 1
+                continue
+            if not args.apply:
+                print('  ＋ [将新建]「%s」→ 执行 #%s' % (title, args.execution_id))
+                pushed += 1
+                continue
+            payload = {'execution': args.execution_id, 'name': d.get('title', ''),
+                       'assignedTo': my_account, 'type': 'devel', 'pri': 3}
+            cre = creds.api('POST', '/tasks', payload)
+            if cre.status_code in (200, 201):
+                new_zid = cre.json().get('id')
+                def _set(d, _z=new_zid):
+                    d['zentao_id'] = _z
+                modify_task_json(td, _set)
+                print('  ✅ 新建「%s」→ 禅道 #%s, 回填 zentao_id' % (title, new_zid))
+                pushed += 1
+            else:
+                print('  ⚠️ 新建「%s」失败 (%s)' % (title, cre.status_code))
+                skipped += 1
+
+    print('\n小结: 推送 %d, 跳过 %d。%s'
+          % (pushed, skipped, '(dry-run, 未真写)' if not args.apply else ''))
+    return 0
+
+
+# ============================================================
+# status 概览
+# ============================================================
+
+def cmd_status(args, creds, my_account, developer):
+    """看本地任务与禅道的关联状态概览 (只读)。"""
+    repo_root = get_repo_root()
+    total = mine = linked = unlinked = 0
+    for td, d in _iter_local_tasks(repo_root):
+        total += 1
+        if (d.get('creator') or '') == developer:
+            mine += 1
+            if d.get('zentao_id'):
+                linked += 1
+            else:
+                unlinked += 1
+    print('═══ 同步状态 (%s / 禅道账号 %s) ═══' % (developer, my_account))
+    print('本地任务总数: %d' % total)
+    print('  归属你的:    %d' % mine)
+    print('    已关联禅道 (有 zentao_id): %d' % linked)
+    print('    未关联禅道 (推送时需 --execution_id 新建): %d' % unlinked)
+    ok, _ = creds.check_intranet()
+    print('\n禅道连通: %s (%s)' % ('✅ 可达' if ok else '❌ 不可达', creds.url))
+    return 0
+
+
+# ============================================================
+# 主入口
+# ============================================================
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description='本地任务 ↔ 禅道安全同步',
+                                formatter_class=argparse.RawDescriptionHelpFormatter,
+                                epilog='安全原则: 拉取只取 assignedTo=我; 推送默认 dry-run 且'
+                                       ' 仅推 creator=我, 同名任务归属不一致则拒绝。')
+    sub = p.add_subparsers(dest='cmd')
+
+    pp = sub.add_parser('pull', help='拉取禅道任务到本地 (仅 assignedTo=我)')
+    pp.add_argument('execution_id', type=int, help='执行ID')
+    pp.add_argument('--apply', action='store_true', help='真写 (默认 dry-run 仅预览)')
+
+    sp = sub.add_parser('push', help='推送本地任务到禅道 (默认 dry-run)')
+    sp.add_argument('--execution_id', type=int, help='新建任务落到哪个执行 (无 zentao_id 的任务需要)')
+    sp.add_argument('--apply', action='store_true', help='真推 (默认 dry-run 仅预览)')
+
+    sub.add_parser('status', help='看同步状态概览 (只读)')
+
+    args = p.parse_args(argv)
+    if not args.cmd:
+        p.print_help()
+        return 0
+
+    developer = get_developer()
+    if not developer:
+        print('ERROR: 未设置当前开发者 (无 .developer)。请先 /wl-init。', file=sys.stderr)
+        return 4
+
+    my_account, err = _resolve_my_account(developer)
+    if err:
+        print('ERROR: %s' % err, file=sys.stderr)
+        return 3
+
+    creds = _zentao_creds()
+    if not creds:
+        print('ERROR: 禅道凭据未配置。请在 .qoder/config.yaml 的 zentao: 段填 url/user/password。',
+              file=sys.stderr)
+        return 3
+
+    # 连通性预检
+    ok, msg = creds.check_intranet()
+    if not ok:
+        print('ERROR: %s' % msg, file=sys.stderr)
+        return 5
+
+    try:
+        if args.cmd == 'pull':
+            return cmd_pull(args, creds, my_account)
+        elif args.cmd == 'push':
+            return cmd_push(args, creds, my_account, developer)
+        elif args.cmd == 'status':
+            return cmd_status(args, creds, my_account, developer)
+    except RuntimeError as e:
+        print('ERROR: %s' % e, file=sys.stderr)
+        return 3
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())