codebee 0.1.46 → 0.1.48

package/app/ui/index.html

@@ -115,6 +115,10 @@
         <span class="kbd" aria-hidden="true">Ctrl K</span>
       </button>
       <div class="side-quick">
+        <button class="qitem" id="btn-q-overview" title="概览" data-i18n-title="概览">
+          <svg class="ico" aria-hidden="true"><use href="#i-gauge"></use></svg>
+          <span data-i18n="概览">概览</span>
+        </button>
         <button class="qitem" id="btn-q-automation" title="自动化" data-i18n-title="自动化">
           <svg class="ico" aria-hidden="true"><use href="#i-calendar-days"></use></svg>
           <span data-i18n="自动化">自动化</span>
@@ -174,10 +178,13 @@
       <button id="btn-set-back" class="set-back" data-i18n="返回 CodeBee">
         <svg class="ico" aria-hidden="true"><use href="#i-arrow-left"></use></svg>返回 CodeBee
       </button>
+      <div data-i18n="工作台" class="set-group">工作台</div>
+      <button class="set-item" data-sub="overview" data-i18n="概览"><svg class="ico" aria-hidden="true"><use href="#i-gauge"></use></svg>概览</button>
       <div data-i18n="编排" class="set-group">编排</div>
       <button class="set-item active" data-sub="tasks" data-i18n="任务"><svg class="ico" aria-hidden="true"><use href="#i-tasks"></use></svg>任务</button>
       <button class="set-item" data-sub="runs" data-i18n="运行记录"><svg class="ico" aria-hidden="true"><use href="#i-history"></use></svg>运行记录</button>
       <button class="set-item" data-sub="automation" data-i18n="自动化"><svg class="ico" aria-hidden="true"><use href="#i-calendar-days"></use></svg>自动化</button>
+      <button class="set-item" data-sub="hooks" data-i18n="钩子"><svg class="ico" aria-hidden="true"><use href="#i-link"></use></svg>钩子</button>
       <button class="set-item" data-sub="__wxdigest" data-i18n="微信群聊汇报"><svg class="ico" aria-hidden="true"><use href="#i-bee"></use></svg>微信群聊汇报</button>
       <button class="set-item" data-sub="zentao" data-i18n="禅道"><svg class="ico" aria-hidden="true"><use href="#i-search"></use></svg>禅道</button>
       <button class="set-item" data-sub="usage" data-i18n="用量统计"><svg class="ico" aria-hidden="true"><use href="#i-chart"></use></svg>用量统计</button>
@@ -243,6 +250,53 @@
     <main>
     <!-- ================= 设置页（导航在左栏，内容为居中窄栏） ================= -->
     <section id="page-settings" class="page">
+      <!-- 概览首页：日期 → 一句话概览 → KPI 卡 → 趋势 + 快捷入口 → 最近运行。
+           全页数据来自真实台账（/api/usage）与运行记录（/api/state），无占位假数。 -->
+      <div id="sub-overview" class="subpage hidden">
+        <div class="ov-head">
+          <div class="ov-head-text">
+            <div id="ov-date" class="ov-eyebrow"></div>
+            <h1 id="ov-title" class="ov-title" data-i18n="概览">概览</h1>
+            <p id="ov-sub" class="ov-sub"></p>
+          </div>
+          <div class="ov-head-act">
+            <button class="ghost" onclick="switchTab('runs')">
+              <svg class="ico" aria-hidden="true"><use href="#i-history"></use></svg><span data-i18n="运行记录">运行记录</span>
+            </button>
+            <button class="primary" onclick="exitSettings()">
+              <svg class="ico" aria-hidden="true"><use href="#i-plus"></use></svg><span data-i18n="新建任务">新建任务</span>
+            </button>
+          </div>
+        </div>
+        <div id="ov-kpis" class="ov-kpis"></div>
+        <div class="ov-row">
+          <div class="panel ov-trend">
+            <div class="panel-head">
+              <h2 data-i18n="用量趋势">用量趋势</h2>
+              <div class="actions" id="ov-ranges">
+                <div class="seg" role="group" aria-label="时间范围" data-i18n-aria="时间范围">
+                  <button class="seg-btn active" data-days="7" data-i18n="近 7 天" onclick="setOvDays(7)">近 7 天</button>
+                  <button class="seg-btn" data-days="30" data-i18n="近 30 天" onclick="setOvDays(30)">近 30 天</button>
+                </div>
+              </div>
+            </div>
+            <div id="ov-trend-body" class="ov-trend-body"></div>
+          </div>
+          <div class="panel ov-quick">
+            <div class="panel-head"><h2 data-i18n="快捷入口">快捷入口</h2></div>
+            <div id="ov-quick-body" class="ov-quick-body"></div>
+          </div>
+        </div>
+        <div class="panel wide ov-recent">
+          <div class="panel-head">
+            <h2 data-i18n="最近运行">最近运行</h2>
+            <div class="actions">
+              <button class="ghost small" onclick="switchTab('runs')" data-i18n="查看全部">查看全部</button>
+            </div>
+          </div>
+          <div id="ov-recent-body" class="ov-recent-body"></div>
+        </div>
+      </div>
       <div id="sub-tasks" class="subpage">
       <div class="panel wide composer">
         <div class="hero-row">
@@ -595,6 +649,24 @@
       </div>
       </div>
 
+      <!-- 钩子：任务生命周期事件挂本机命令（stdin JSON / stdout 注入） -->
+      <div id="sub-hooks" class="subpage hidden">
+      <div class="panel wide">
+        <div class="panel-head">
+          <h2 data-i18n="钩子">钩子</h2>
+          <div class="actions">
+            <button id="btn-hooks-add" class="primary small" title="加一条钩子" data-i18n-title="加一条钩子"><span data-i18n="新建钩子">新建钩子</span></button>
+          </div>
+        </div>
+        <p class="hint" data-i18n="在任务生命周期的关键点执行本机命令：命令从标准输入收到 JSON（事件与任务上下文），标准输出回 {&quot;inject&quot;: &quot;文本&quot;} 即把文本注入提示词（run_end 的输出被忽略，适合回写知识库）。命令按空格分词执行，不支持管道；失败或超时自动跳过，绝不挡主流程。">在任务生命周期的关键点执行本机命令：命令从标准输入收到 JSON（事件与任务上下文），标准输出回 {"inject": "文本"} 即把文本注入提示词（run_end 的输出被忽略，适合回写知识库）。命令按空格分词执行，不支持管道；失败或超时自动跳过，绝不挡主流程。</p>
+        <div id="hooks-list" class="cards"></div>
+        <div id="hooks-empty" class="empty hidden" data-i18n="还没有钩子——点「新建钩子」在任务开始 / 消息送达 / 运行结束时挂你自己的脚本。">还没有钩子——点「新建钩子」在任务开始 / 消息送达 / 运行结束时挂你自己的脚本。</div>
+        <div class="actions" style="margin-top:10px">
+          <button id="btn-hooks-save" class="primary small" title="保存全部钩子" data-i18n-title="保存全部钩子"><span data-i18n="保存钩子">保存钩子</span></button>
+        </div>
+      </div>
+      </div>
+
       <!-- 禅道：Bug 自动扫描修复 -->
       <div id="sub-zentao" class="subpage hidden">
       <div class="panel wide">

package/app/ui/style.css

@@ -5708,3 +5708,163 @@ button.request-busy > * { opacity: .18; }
   padding: 1px 7px; border-radius: 6px; }
 .chat-act:hover { background: color-mix(in srgb, var(--text) 8%, transparent);
   color: var(--text); }
+
+/* 屏蔽顶部滑动加载线（用户拍板 2026-09-22）：后台/长请求（如禅道内网不可达
+   15-30s）会让线一直滑，观感差；操作反馈由「操作状态」中心承担，不丢信息 */
+#request-progress { display: none !important; }
+
+/* 钩子管理卡片（设置 → 钩子，2026-09-22）：名称/事件/开关一行，命令整行，
+ * 底部超时+测试。mono 字体命令输入便于读路径 */
+.hook-card .hook-head { display: flex; align-items: center; gap: 10px; }
+.hook-card .hook-head .hook-name { flex: 1 1 140px; min-width: 0; }
+.hook-card .hook-head .hook-event { flex: none; }
+.hook-card .hook-cmd { width: 100%; margin-top: 10px; font-family: var(--mono); font-size: 12px; }
+.hook-card .hook-foot { display: flex; align-items: center; gap: 8px; margin-top: 10px; }
+.hook-card .hook-timeout { width: 64px; }
+.hook-card .hook-test-out { flex: 1 1 auto; min-width: 0; overflow: hidden;
+  text-overflow: ellipsis; white-space: nowrap; }
+.hook-card .switch { display: inline-flex; align-items: center; cursor: pointer; }
+.hook-card .switch input { appearance: none; width: 34px; height: 19px; border-radius: 999px;
+  background: var(--border, rgba(128,128,128,.4)); position: relative; cursor: pointer;
+  transition: background .15s; margin: 0; }
+.hook-card .switch input:checked { background: var(--accent); }
+.hook-card .switch input::after { content: ""; position: absolute; top: 2px; left: 2px;
+  width: 15px; height: 15px; border-radius: 50%; background: #fff; transition: left .15s; }
+.hook-card .switch input:checked::after { left: 17px; }
+
+/* ==========================================================================
+   概览首页 + KPI 卡三件套（2026-09-22）
+   配色一律走变量（--accent/--ok/--warn/--bad/--accent2），所以 7 套皮肤
+   与日间/夜间都自动成立，无需为皮肤另写规则。
+   ========================================================================== */
+
+/* ---------- KPI 卡：图标块 / 环比徽章 / 迷你走势 ---------- */
+/* .kpi 定位上下文：走势图绝对定位钉在右下角 */
+.kpi { position: relative; }
+.kpi.has-top { padding-top: 11px; }
+.kpi-top {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 8px; margin-bottom: 9px;
+}
+/* 图标独立成块（淡彩底 + 本色图标），不再是标签行里的装饰性小图标 */
+.kpi-ico {
+  width: 26px; height: 26px; flex: none; border-radius: 8px;
+  display: inline-flex; align-items: center; justify-content: center;
+}
+.kpi-ico .ico { width: 15px; height: 15px; stroke-width: 2; }
+.kpi-ico.t-accent { color: var(--accent); background: color-mix(in srgb, var(--accent) 14%, transparent); }
+.kpi-ico.t-ok { color: var(--ok); background: color-mix(in srgb, var(--ok) 14%, transparent); }
+.kpi-ico.t-warn { color: var(--warn); background: color-mix(in srgb, var(--warn) 14%, transparent); }
+.kpi-ico.t-bad { color: var(--bad); background: color-mix(in srgb, var(--bad) 14%, transparent); }
+.kpi-ico.t-calm { color: var(--accent2); background: color-mix(in srgb, var(--accent2) 14%, transparent); }
+
+.kpi-delta {
+  flex: none; font-size: 11px; font-weight: 600; white-space: nowrap;
+  padding: 2px 8px; border-radius: 999px;
+}
+.kpi-delta.good { color: var(--ok); background: color-mix(in srgb, var(--ok) 14%, transparent); }
+.kpi-delta.bad { color: var(--bad); background: color-mix(in srgb, var(--bad) 14%, transparent); }
+.kpi-delta.flat { color: var(--muted); background: color-mix(in srgb, var(--muted) 14%, transparent); }
+
+/* 走势图钉在右下；副行文字给它让位（.kpi-s 本就 nowrap + 省略号） */
+.kpi.has-spark { padding-bottom: 34px; }
+.kpi.has-spark .kpi-s { padding-right: 80px; }
+.kpi-spark { position: absolute; right: 10px; bottom: 8px; width: 72px; height: 24px; }
+.kspark { display: block; width: 100%; height: 100%; overflow: visible; }
+.kspark .ks-line { fill: none; stroke-width: 1.6; stroke-linejoin: round; stroke-linecap: round; }
+.kspark .ks-area { stroke: none; opacity: .16; }
+.kspark.t-accent .ks-line { stroke: var(--accent); }
+.kspark.t-accent .ks-area { fill: var(--accent); }
+.kspark.t-ok .ks-line { stroke: var(--ok); }
+.kspark.t-ok .ks-area { fill: var(--ok); }
+.kspark.t-warn .ks-line { stroke: var(--warn); }
+.kspark.t-warn .ks-area { fill: var(--warn); }
+.kspark.t-bad .ks-line { stroke: var(--bad); }
+.kspark.t-bad .ks-area { fill: var(--bad); }
+.kspark.t-calm .ks-line { stroke: var(--accent2); }
+.kspark.t-calm .ks-area { fill: var(--accent2); }
+
+/* ---------- 概览页版式 ---------- */
+/* #sub-overview 本身就是 .subpage（纵向 flex + 20px 间距），
+   所以下列各块不再自带外边距，避免出现双倍留白 */
+.ov-head {
+  display: flex; align-items: flex-end; justify-content: space-between;
+  gap: 16px; flex-wrap: wrap;
+}
+.ov-eyebrow { color: var(--muted); font-size: 12px; margin-bottom: 6px; }
+.ov-title { margin: 0; font-size: 26px; font-weight: 700; letter-spacing: -.02em; }
+.ov-sub { margin: 9px 0 0; color: var(--muted); font-size: 13px; }
+.ov-head-act { display: flex; gap: 8px; flex: none; }
+.ov-head-act button { display: inline-flex; align-items: center; gap: 6px; }
+.ov-head-act .ico { width: 14px; height: 14px; }
+
+.ov-kpis { display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; }
+.ov-row {
+  display: grid; gap: 12px; align-items: start;
+  grid-template-columns: minmax(0, 1.62fr) minmax(0, 1fr);
+}
+
+/* ---------- 快捷入口：图标块 + 主副标题 + 右上箭头 ---------- */
+.ov-quick-body { display: flex; flex-direction: column; gap: 2px; }
+.ov-q {
+  display: flex; align-items: center; gap: 10px; width: 100%;
+  text-align: left; background: none; border: none; cursor: pointer;
+  color: var(--text); font-family: inherit; padding: 8px 9px; border-radius: 10px;
+  transition: background-color .15s;
+}
+.ov-q:hover { background: var(--panel2); }
+.ov-q-ico {
+  width: 28px; height: 28px; flex: none; border-radius: 9px;
+  display: inline-flex; align-items: center; justify-content: center;
+  color: var(--accent); background: color-mix(in srgb, var(--accent) 13%, transparent);
+}
+.ov-q-ico .ico { width: 15px; height: 15px; stroke-width: 2; }
+.ov-q-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; flex: 1 1 auto; }
+.ov-q-text b { font-size: 13px; font-weight: 600; }
+.ov-q-text i {
+  font-size: 11.5px; font-style: normal; color: var(--muted);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+/* ↗ 复用 i-arrow-up 旋转 45°，不再单加一个精灵图标 */
+.ov-q-go { flex: none; display: inline-flex; color: var(--muted); opacity: .5; transform: rotate(45deg); }
+.ov-q:hover .ov-q-go { opacity: .9; }
+/* 四行各自分色：一列同色图标太平 */
+.ov-q:nth-child(2) .ov-q-ico { color: var(--accent2); background: color-mix(in srgb, var(--accent2) 13%, transparent); }
+.ov-q:nth-child(3) .ov-q-ico { color: var(--ok); background: color-mix(in srgb, var(--ok) 13%, transparent); }
+.ov-q:nth-child(4) .ov-q-ico { color: var(--warn); background: color-mix(in srgb, var(--warn) 13%, transparent); }
+
+/* ---------- 最近运行：发丝线分隔的行 ---------- */
+.ov-recent-body { display: flex; flex-direction: column; }
+.ov-recent .panel-head { margin-bottom: 8px; }
+.ov-run {
+  display: flex; align-items: center; gap: 12px; width: 100%;
+  text-align: left; background: none; border: none; cursor: pointer;
+  color: var(--text); font-family: inherit; padding: 11px 8px;
+  border-top: 1px solid var(--border); transition: background-color .15s;
+}
+.ov-run:first-child { border-top: none; }
+.ov-run:hover { background: var(--panel2); }
+.ov-run-ico { flex: none; width: 16px; display: inline-flex; align-items: center; justify-content: center; }
+.ov-run-main { flex: 1 1 auto; min-width: 0; display: flex; flex-direction: column; gap: 3px; }
+.ov-run-main b { font-size: 13px; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ov-run-main i {
+  font-size: 11.5px; font-style: normal; color: var(--muted);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.ov-run-meta { flex: none; display: flex; align-items: center; gap: 10px; }
+.ov-run-time { min-width: 54px; text-align: right; color: var(--muted); font-size: 11.5px; white-space: nowrap; }
+
+/* ---------- 窄屏：KPI 两列 → 一列，趋势与快捷入口改纵向 ---------- */
+@media (max-width: 1080px) {
+  .ov-kpis { grid-template-columns: repeat(2, 1fr); }
+  .ov-row { grid-template-columns: 1fr; }
+}
+@media (max-width: 640px) {
+  .ov-kpis { grid-template-columns: 1fr; }
+  .ov-head { flex-direction: column; align-items: flex-start; }
+  /* 窄屏放不下并排：走势图落到卡片底部通栏，副行不再让位 */
+  .kpi-spark { position: static; width: 100%; margin-top: 8px; }
+  .kpi.has-spark { padding-bottom: 12px; }
+  .kpi.has-spark .kpi-s { padding-right: 0; }
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebee",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "CodeBee · 多智能体编排台 — 统一编排本机 AI 编码 CLI（Codex / Claude Code / QwenCode / OpenCode / Aider…）：目标→拆解→路由→执行→验证→跨厂商评审→修复→报告。纯 Python 标准库实现，本地 Web UI。",
   "license": "MIT",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "app",
     "bin",
+    "tools/wx_reader.py",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"

package/tools/wx_reader.py

@@ -0,0 +1,261 @@
+# -*- coding: utf-8 -*-
+"""微信读取 sidecar：由 64 位 Python ≥3.9（配 wechatauto-replica）运行，
+把本机微信 4.x 群消息增量拉成本仓库已有的「导出 txt」格式。
+
+为什么是独立进程：wechatauto 依赖链（winsdk 等）需要 64 位 Python ≥3.9，
+而 CodeBee 服务钉在 3.8-32。sidecar 通过文件与主程序解耦——拉到的新消息
+按「2024-01-01 12:34:56 昵称」行格式追加进监控文件夹，wxdigest 现有的
+解析/增量游标/摘要/桌宠提醒整条链路零改动复用。
+
+用法（两个模式，互斥）：
+  列群（供前端选择）：
+    python wx_reader.py --list-groups --result OUT.json
+  拉增量（每次扫描前调用）：
+    python wx_reader.py --pull --out DIR --state STATE.json \
+                        --groups-file GROUPS.json --result OUT.json
+    GROUPS.json = [{"username": "...@chatroom", "name": "群名"}, ...]
+
+只读保证：只调用 get_groups/get_new_messages/get_group_members/get_self_info，
+不调用任何发送/删除接口。
+结果 JSON 写 --result 文件（stdout 被库日志污染，不作为契约）。
+语法保持 3.8 兼容（测试解释器要 import 本文件的纯函数）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+
+# 群消息 content 自带「<wxid>: 前缀」，剥掉后用成员表翻译成昵称
+_PREFIX_RE = re.compile(r"^([A-Za-z0-9_+@\-.]{3,}):\s*\n?")
+_ILLEGAL_FN = re.compile(r'[\\/:*?"<>|]')
+
+SELF_NAME = "我"
+
+
+def sanitize_filename(name):
+    """群名 → 合法文件名（Windows 非法字符换下划线；空名回落 username）。"""
+    out = _ILLEGAL_FN.sub("_", str(name or "").strip())
+    return out[:80] or "unnamed"
+
+
+def strip_sender_prefix(content, sender_username):
+    """群消息正文剥掉自带的「wxid: 」前缀（前缀与发送者一致才可信地剥）。"""
+    text = str(content or "")
+    m = _PREFIX_RE.match(text)
+    if m and (not sender_username or m.group(1) == sender_username):
+        return text[m.end():].strip()
+    return text.strip()
+
+
+def member_map(members):
+    """get_group_members 结果 → {username: 显示名}。备注优先（微信 UI 同款）。"""
+    out = {}
+    for m in members or []:
+        if not isinstance(m, dict):
+            continue
+        uid = m.get("username") or ""
+        if not uid:
+            continue
+        out[uid] = m.get("remark") or m.get("nick_name") or uid
+    return out
+
+
+def format_line(ts_epoch, sender_name, text):
+    """一条消息 → 导出格式行（时间戳行与正文之间不留空行，与现有解析器对齐）。"""
+    stamp = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(ts_epoch or 0))
+    return "%s %s\n%s\n" % (stamp, sender_name or "?", str(text or "").strip())
+
+
+def type_placeholder(mtype):
+    """非文本消息 → 占位符（摘要时让模型知道有图/语音存在）。None=跳过不入正文。"""
+    t = str(mtype or "")
+    if "文本" in t:
+        return None            # 文本走正文，不是占位符
+    for key, ph in (("图片", "[图片]"), ("语音", "[语音]"), ("视频", "[视频]"),
+                    ("文件", "[文件]"), ("链接", "[链接]"), ("名片", "[名片]"),
+                    ("位置", "[位置]"), ("动画表情", "[表情]"), ("系统", None)):
+        if key in t:
+            return ph
+    return "[%s]" % t if t and len(t) <= 8 else None
+
+
+def _quiet_lib_logs():
+    try:
+        import logging
+        logging.getLogger("wechatauto").setLevel(logging.WARNING)
+    except Exception:
+        pass
+
+
+def _write_result(path, obj):
+    tmp = str(path) + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(obj, f, ensure_ascii=False)
+    os.replace(tmp, path)
+
+
+def _load_json(path, default):
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return default
+
+
+def load_state(path):
+    return _load_json(path, {}) or {}
+
+
+def save_state(path, state):
+    tmp = str(path) + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(state, f, ensure_ascii=False)
+    os.replace(tmp, path)
+
+
+def cmd_list_groups(result_path):
+    _quiet_lib_logs()
+    import wechatauto
+    db = wechatauto.WeChatDB()
+    groups, seen = [], set()
+    for g in db.get_groups():
+        if isinstance(g, dict) and g.get("username"):
+            groups.append({"username": g["username"],
+                           "name": g.get("name") or g["username"],
+                           "member_count": str(g.get("member_count") or "")})
+            seen.add(g["username"])
+    # 新群兜底（2026-09-21 用户实测「缺一个新建的群」）：刚建的群可能还没
+    # 落进 chat_room/contact，但只要有过消息就在会话列表里——合并补进，
+    # 昵称未同步时先显示 wxid，微信同步后「刷新群列表」即见真名。
+    try:
+        for s in db.get_sessions(200):
+            u = str((s or {}).get("username") or "")
+            if u.endswith("@chatroom") and u not in seen:
+                groups.append({"username": u,
+                               "name": db.get_nickname(u) or u,
+                               "member_count": ""})
+                seen.add(u)
+    except Exception:
+        pass   # 会话库不可用不影响主清单
+    _write_result(result_path, {"ok": True, "groups": groups, "count": len(groups)})
+
+
+def cmd_pull(out_dir, state_path, groups_file, result_path):
+    _quiet_lib_logs()
+    import wechatauto
+    sel = _load_json(groups_file, [])
+    sel = [g for g in (sel or []) if isinstance(g, dict) and g.get("username")]
+    state = load_state(state_path)
+    os.makedirs(out_dir, exist_ok=True)
+    db = wechatauto.WeChatDB()
+    try:
+        self_wxid = db.wxid
+    except Exception:
+        self_wxid = ""
+    pulled, errors = {}, []
+    for g in sel:
+        username, name = g["username"], g.get("name") or g["username"]
+        since = 0
+        try:
+            since = int((state.get(username) or {}).get("since_seq") or 0)
+        except (TypeError, ValueError):
+            since = 0
+        try:
+            msgs = db.get_new_messages(username, since_seq=since, limit=500)
+        except Exception as e:
+            errors.append("%s: %s" % (name, e))
+            continue
+        if not msgs:
+            pulled[username] = 0
+            continue
+        members = {}
+        try:
+            members = member_map(db.get_group_members(username))
+        except Exception:
+            members = {}
+        # 昵称缓存：退群成员不在成员表里，靠 get_nickname 兜底一次后永久缓存
+        gstate = state.get(username) or {}
+        names = dict(gstate.get("names") or {})
+
+        def resolve(uid):
+            if not uid:
+                return "?"
+            if self_wxid and uid == self_wxid:
+                return SELF_NAME
+            if uid in members:
+                return members[uid]
+            if uid in names:
+                return names[uid]
+            try:
+                nick = str(db.get_nickname(uid) or "").strip()
+            except Exception:
+                nick = ""
+            name2 = nick or uid
+            if len(names) < 5000:          # 缓存上限防无限膨胀
+                names[uid] = name2
+            return name2
+
+        fname = os.path.join(out_dir, sanitize_filename(name) + ".txt")
+        header = "【%s】\n" % name
+        need_header = not os.path.exists(fname)
+        lines = []
+        max_seq = since
+        for m in msgs:
+            seq = m.get("sort_seq") or 0
+            if seq <= since:
+                continue
+            max_seq = max(max_seq, seq)
+            uid = m.get("sender_username") or ""
+            who = resolve(uid)
+            mtype = m.get("type")
+            text = None
+            if "文本" in str(mtype or ""):
+                text = strip_sender_prefix(m.get("content"), uid)
+            else:
+                text = type_placeholder(mtype)
+            if not text:
+                continue
+            lines.append(format_line(m.get("create_time"), who, text))
+        if lines:
+            with open(fname, "a", encoding="utf-8") as f:
+                if need_header:
+                    f.write(header)
+                f.write("\n".join(lines) + "\n")
+        state[username] = {"name": name, "since_seq": max_seq,
+                           "names": names, "t": time.time()}
+        pulled[username] = len(lines)
+    save_state(state_path, state)
+    _write_result(result_path, {"ok": not errors, "pulled": pulled,
+                                "errors": errors, "count": sum(pulled.values())})
+
+
+def main():
+    ap = argparse.ArgumentParser(description="CodeBee 微信群消息只读 sidecar")
+    ap.add_argument("--list-groups", action="store_true")
+    ap.add_argument("--pull", action="store_true")
+    ap.add_argument("--out", default="")
+    ap.add_argument("--state", default="")
+    ap.add_argument("--groups-file", default="")
+    ap.add_argument("--result", required=True, help="结果 JSON 落点（stdout 不可靠）")
+    args = ap.parse_args()
+    try:
+        if args.list_groups:
+            cmd_list_groups(args.result)
+        elif args.pull:
+            cmd_pull(args.out, args.state, args.groups_file, args.result)
+        else:
+            ap.error("需要 --list-groups 或 --pull")
+    except Exception as e:
+        # 顶层异常也落 result：微信未登录/DB 锁住等真实原因必须透传给主程序
+        _write_result(args.result, {"ok": False, "errors": [str(e)],
+                                    "groups": [], "pulled": {}, "count": 0})
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())