@tmpxinchen/tmp1 1.0.56 → 1.0.57

package/ai-coding-pilot-multi-project-patch.md

@@ -0,0 +1,1122 @@
+# issue-bot 多 project 最小改造说明
+
+## 0. 目标
+
+把一个 issue-bot 从“只处理一个 project”改成“一个 bot 进程处理多个 project”。
+
+本次只做最小改造：
+
+```text
+一个 bot 进程
+一个 group webhook
+一个 token（可访问所有目标 project）
+多个 project 路径配置
+任务 / state / workspace 按 project 隔离
+```
+
+本次**不做**：
+
+```text
+每 project 一个容器
+每 project 一个 token
+worker pool
+controller + 临时 worker
+多租户框架
+复杂权限模型
+```
+
+---
+
+## 1. 给内部模型的操作要求
+
+内部代码已经和本地分叉，**不要整文件覆盖**。
+
+请按下面的顺序修改：
+
+```text
+1. 先备份
+2. 按函数名 / 代码块定位
+3. 只替换文档中明确指出的函数或代码块
+4. 保留内部已有的标签名、路径、日志、token 方式
+5. 最后用 python3 -m py_compile 和测试清单验证
+```
+
+建议先备份：
+
+```bash
+cp automation/issue_bot.py automation/issue_bot.py.bak-$(date +%Y%m%d%H%M%S)
+cp scripts/gitlab-init.sh scripts/gitlab-init.sh.bak-$(date +%Y%m%d%H%M%S)
+cp scripts/selfcheck.sh scripts/selfcheck.sh.bak-$(date +%Y%m%d%H%M%S)
+```
+
+本次改造只涉及：
+
+```text
+automation/issue_bot.py
+docker-compose.yml
+.env
+.env.example
+scripts/gitlab-init.sh
+scripts/selfcheck.sh
+README.md
+automation/README.md
+docs/自动化流程.md
+```
+
+不涉及：
+
+```text
+GitLab Runner
+CI 模板
+Maven/Nexus
+opencode 镜像
+门禁脚本
+业务仓库
+```
+
+---
+
+## 2. 配置改造
+
+### 2.1 `.env` 和 `.env.example`
+
+在 `AUTOMATION_PROJECT` 下面增加：
+
+```bash
+# 多 project：逗号分隔完整路径，例如 observability/a,observability/b
+# 留空时只处理 AUTOMATION_GROUP/AUTOMATION_PROJECT
+AUTOMATION_PROJECTS=
+```
+
+说明：
+
+- 默认留空，保持单项目行为；
+- 要启用多 project，填完整路径；
+- 路径必须和 GitLab webhook 里的 `project.path_with_namespace` 完全一致；
+- 不要只写项目名，必须带 group，例如 `observability/payment-service`。
+
+示例：
+
+```bash
+AUTOMATION_PROJECTS=observability/metric-ingest-service,observability/payment-service
+```
+
+### 2.2 `docker-compose.yml`
+
+在 issue-bot 的 `environment` 中，`GITLAB_PROJECT_PATH` 后面增加：
+
+```yaml
+      GITLAB_PROJECT_PATH: ${AUTOMATION_GROUP:-observability}/${AUTOMATION_PROJECT:-metric-ingest-service}
+      # 多 project 时填逗号分隔的完整路径；为空则回退到 GITLAB_PROJECT_PATH
+      GITLAB_PROJECTS: ${AUTOMATION_PROJECTS:-}
+```
+
+不要删除原来的 `GITLAB_PROJECT_PATH`，它用于单项目回退。
+
+---
+
+## 3. `automation/issue_bot.py` 改造
+
+### 3.1 常量：新增 `PROJECTS`，删除 `PROJECT_API`
+
+原代码：
+
+```python
+PROJECT_PATH = os.environ.get("GITLAB_PROJECT_PATH", "observability/metric-ingest-service")
+```
+
+改为：
+
+```python
+PROJECT_PATH = os.environ.get("GITLAB_PROJECT_PATH", "observability/metric-ingest-service")
+PROJECTS = list(dict.fromkeys(
+    p.strip()
+    for p in os.environ.get("GITLAB_PROJECTS", "").split(",")
+    if p.strip()
+))
+if not PROJECTS:
+    PROJECTS = [PROJECT_PATH]
+```
+
+然后找到并删除这一行：
+
+```python
+PROJECT_API = "/api/v4/projects/" + urllib.parse.quote(PROJECT_PATH, safe="")
+```
+
+把队列类型改为：
+
+```python
+TASKS: "queue.Queue[tuple[str, int]]" = queue.Queue()
+SEEN = set()
+SEEN_LOCK = threading.Lock()
+```
+
+注意：
+
+- `SEEN` 不再只放 `iid`，后面会放 `(project, iid)`；
+- `TASKS` 不再只放 `iid`，后面会放 `(project, iid)`。
+
+---
+
+### 3.2 新增 project 工具函数
+
+在 `clean()` 后面、`api_raw()` 前面增加：
+
+```python
+def project_key(project):
+    """文件系统安全的 project key。"""
+    return urllib.parse.quote(project, safe="")
+
+
+def project_api(project):
+    return "/api/v4/projects/" + urllib.parse.quote(project, safe="")
+```
+
+用途：
+
+- `project_api()` 用于拼 GitLab API；
+- `project_key()` 用于 state / workspace 目录名，避免 `/` 把目录拆开。
+
+---
+
+### 3.3 `api()` 改成按 project 调用
+
+原代码：
+
+```python
+def api(method, path, data=None, timeout=30):
+    return api_raw(method, PROJECT_API + path, data, timeout)
+```
+
+改为：
+
+```python
+def api(project, method, path, data=None, timeout=30):
+    return api_raw(method, project_api(project) + path, data, timeout)
+```
+
+---
+
+### 3.4 `api_get()` 增加 project
+
+原代码：
+
+```python
+def api_get(path, **params):
+    if params:
+        path += "?" + urllib.parse.urlencode(params)
+    return api("GET", path)
+```
+
+改为：
+
+```python
+def api_get(project, path, **params):
+    if params:
+        path += "?" + urllib.parse.urlencode(params)
+    return api(project, "GET", path)
+```
+
+---
+
+### 3.5 `note_issue()` / `note_mr()` 增加 project
+
+原代码：
+
+```python
+def note_issue(iid, body):
+    try:
+        api("POST", "/issues/%d/notes" % iid, {"body": body})
+    except Exception as e:
+        log.warning("评论 issue #%s 失败: %s", iid, mask(e))
+
+
+def note_mr(mr_iid, body):
+    try:
+        api("POST", "/merge_requests/%d/notes" % mr_iid, {"body": body})
+    except Exception as e:
+        log.warning("评论 MR !%s 失败: %s", mr_iid, mask(e))
+```
+
+改为：
+
+```python
+def note_issue(project, iid, body):
+    try:
+        api(project, "POST", "/issues/%d/notes" % iid, {"body": body})
+    except Exception as e:
+        log.warning("评论 %s issue #%s 失败: %s", project, iid, mask(e))
+
+
+def note_mr(project, mr_iid, body):
+    try:
+        api(project, "POST", "/merge_requests/%d/notes" % mr_iid, {"body": body})
+    except Exception as e:
+        log.warning("评论 %s MR !%s 失败: %s", project, mr_iid, mask(e))
+```
+
+---
+
+### 3.6 state 相关函数增加 project
+
+原代码：
+
+```python
+def state_path(iid):
+    return STATE_DIR / ("issue-%d.json" % iid)
+
+
+def load_state(iid):
+    try:
+        return json.loads(state_path(iid).read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def save_state(iid, data):
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        state_path(iid).write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    except Exception as e:
+        log.warning("保存 issue #%s 状态失败: %s", iid, e)
+
+
+def clear_state(iid):
+    try:
+        state_path(iid).unlink(missing_ok=True)
+    except Exception:
+        pass
+```
+
+改为：
+
+```python
+def state_path(project, iid):
+    return STATE_DIR / project_key(project) / ("issue-%d.json" % iid)
+
+
+def load_state(project, iid):
+    try:
+        return json.loads(state_path(project, iid).read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def save_state(project, iid, data):
+    try:
+        path = state_path(project, iid)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    except Exception as e:
+        log.warning("保存 %s issue #%s 状态失败: %s", project, iid, e)
+
+
+def clear_state(project, iid):
+    try:
+        state_path(project, iid).unlink(missing_ok=True)
+    except Exception:
+        pass
+```
+
+最终目录形态：
+
+```text
+data/automation/state/observability%2Fmetric-ingest-service/issue-1.json
+data/automation/state/observability%2Fpayment-service/issue-1.json
+```
+
+不同项目的 `#1` 不再冲突。
+
+---
+
+### 3.7 `set_labels()` / `set_labels_safe()` / `human_notes()` 增加 project
+
+原代码：
+
+```python
+def set_labels(iid, add=(), remove=()):
+    data = {}
+    if add:
+        data["add_labels"] = ",".join(add)
+    if remove:
+        data["remove_labels"] = ",".join(remove)
+    if data:
+        api("PUT", "/issues/%d" % iid, data)
+
+
+def set_labels_safe(iid, add=(), remove=()):
+    try:
+        set_labels(iid, add=add, remove=remove)
+    except Exception as e:
+        log.warning("更新 issue #%s 状态标签失败: %s", iid, mask(e))
+```
+
+改为：
+
+```python
+def set_labels(project, iid, add=(), remove=()):
+    data = {}
+    if add:
+        data["add_labels"] = ",".join(add)
+    if remove:
+        data["remove_labels"] = ",".join(remove)
+    if data:
+        api(project, "PUT", "/issues/%d" % iid, data)
+
+
+def set_labels_safe(project, iid, add=(), remove=()):
+    try:
+        set_labels(project, iid, add=add, remove=remove)
+    except Exception as e:
+        log.warning("更新 %s issue #%s 状态标签失败: %s", project, iid, mask(e))
+```
+
+`human_notes()` 原代码：
+
+```python
+def human_notes(iid):
+    try:
+        notes = api_get("/issues/%d/notes" % iid, per_page=100, sort="asc")
+    except Exception as e:
+        log.warning("读取 issue #%s 评论失败: %s", iid, mask(e))
+        return []
+```
+
+改为：
+
+```python
+def human_notes(project, iid):
+    try:
+        notes = api_get(project, "/issues/%d/notes" % iid, per_page=100, sort="asc")
+    except Exception as e:
+        log.warning("读取 %s issue #%s 评论失败: %s", project, iid, mask(e))
+        return []
+```
+
+---
+
+### 3.8 `enqueue()` 改为 `(project, iid)`
+
+原代码：
+
+```python
+def enqueue(iid):
+    with SEEN_LOCK:
+        if iid in SEEN:
+            log.info("issue #%s 已在队列/处理中，忽略重复 webhook", iid)
+            return
+        SEEN.add(iid)
+    TASKS.put(iid)
+    log.info("issue #%s 入队", iid)
+```
+
+改为：
+
+```python
+def enqueue(project, iid):
+    key = (project, iid)
+    with SEEN_LOCK:
+        if key in SEEN:
+            log.info("%s issue #%s 已在队列/处理中，忽略重复 webhook", project, iid)
+            return
+        SEEN.add(key)
+    TASKS.put(key)
+    log.info("%s issue #%s 入队", project, iid)
+```
+
+---
+
+### 3.9 `clone_url()` 增加 project
+
+原代码：
+
+```python
+def clone_url():
+    u = urllib.parse.urlparse(GITLAB_URL)
+    tok = urllib.parse.quote(token(), safe="")
+    return "%s://oauth2:%s@%s/%s.git" % (u.scheme, tok, u.netloc, PROJECT_PATH)
+```
+
+改为：
+
+```python
+def clone_url(project):
+    u = urllib.parse.urlparse(GITLAB_URL)
+    tok = urllib.parse.quote(token(), safe="")
+    return "%s://oauth2:%s@%s/%s.git" % (u.scheme, tok, u.netloc, project)
+```
+
+---
+
+### 3.10 `wait_pipeline()` 增加 project
+
+原代码：
+
+```python
+def wait_pipeline(branch, head_sha):
+    ...
+            pipes = api_get("/pipelines", ref=branch, per_page=1)
+```
+
+改为：
+
+```python
+def wait_pipeline(project, branch, head_sha):
+    ...
+            pipes = api_get(project, "/pipelines", ref=branch, per_page=1)
+```
+
+日志也改成：
+
+```python
+log.warning("查询 %s pipeline 失败: %s", project, mask(e))
+```
+
+---
+
+### 3.11 `ensure_runtime_labels()` 增加 project
+
+原代码：
+
+```python
+def ensure_runtime_labels():
+    ...
+            api("POST", "/labels", {"name": name, "color": color})
+        except Exception as e:
+            if "-> 409:" not in str(e):
+                log.warning("创建标签 %s 失败: %s", name, mask(e))
+```
+
+改为：
+
+```python
+def ensure_runtime_labels(project):
+    ...
+            api(project, "POST", "/labels", {"name": name, "color": color})
+        except Exception as e:
+            if "-> 409:" not in str(e):
+                log.warning("创建 %s 标签 %s 失败: %s", project, name, mask(e))
+```
+
+---
+
+### 3.12 `recover_stale_processing()` 增加 project
+
+关键改动：
+
+```python
+def recover_stale_processing(project):
+    try:
+        issues = api_get(project, "/issues", labels=PROCESSING_LABEL, state="opened", per_page=100)
+    ...
+        open_mrs = api_get(project, "/merge_requests", state="opened", per_page=100)
+    ...
+            set_labels_safe(project, iid, add=[DONE_LABEL], remove=[PROCESSING_LABEL])
+    ...
+            set_labels_safe(project, iid, add=[FAILED_LABEL], remove=[PROCESSING_LABEL])
+            note_issue(project, iid, "⚠️ 上一次自动处理中断，已标记为失败。请重新加 `%s` 重试。" % TRIGGER_LABEL)
+```
+
+日志中带上 project：
+
+```python
+log.warning("扫描 %s ai-processing issue 失败: %s", project, mask(e))
+log.warning("查询 %s 打开 MR 失败，跳过启动恢复以避免误标: %s", project, mask(e))
+log.info("%s issue #%s 已有打开 MR，恢复为 ai-done", project, iid)
+```
+
+---
+
+### 3.13 `recover_queued_triggers()` 增加 project
+
+关键改动：
+
+```python
+def recover_queued_triggers(project):
+    try:
+        issues = api_get(project, "/issues", labels=TRIGGER_LABEL, state="opened", per_page=100)
+    ...
+        enqueue(project, iid)
+```
+
+---
+
+### 3.14 `_handle()` 增加 project
+
+函数签名：
+
+```python
+def _handle(project, iid):
+    log.info("开始处理 %s issue #%s", project, iid)
+    issue = api_get(project, "/issues/%d" % iid)
+```
+
+所有内部调用都要加 project：
+
+```python
+note_issue(project, iid, ...)
+set_labels(project, iid, ...)
+set_labels_safe(project, iid, ...)
+state = load_state(project, iid)
+api_get(project, "/merge_requests", state="opened", per_page=100)
+project_info = api_get(project, "")
+human_notes(project, iid)
+save_state(project, iid, state)
+clear_state(project, iid)
+wait_pipeline(project, branch, head_sha)
+note_mr(project, mr_iid, ...)
+```
+
+workspace 路径必须带 project：
+
+```python
+ws = WORKSPACE_ROOT / project_key(project) / ("issue-%s-%d" % (iid, int(time.time())))
+```
+
+clone 前创建父目录：
+
+```python
+ws.parent.mkdir(parents=True, exist_ok=True)
+```
+
+clone 使用：
+
+```python
+clone_url(project)
+```
+
+project 默认分支查询：
+
+```python
+project_info = api_get(project, "")
+target = TARGET_BRANCH or project_info.get("default_branch") or "main"
+```
+
+MR 创建：
+
+```python
+mr = api(project, "POST", "/merge_requests", {
+    ...
+})
+```
+
+标签创建：
+
+```python
+api(project, "POST", "/labels", {"name": "path::ai", "color": "#428bca"})
+```
+
+异常日志：
+
+```python
+log.exception("%s issue #%s 处理失败", project, iid)
+```
+
+---
+
+### 3.15 `handle()` / `worker()` 改为元组任务
+
+原代码：
+
+```python
+def handle(iid):
+    try:
+        _handle(iid)
+    finally:
+        with SEEN_LOCK:
+            SEEN.discard(iid)
+
+
+def worker():
+    while True:
+        iid = TASKS.get()
+        try:
+            handle(iid)
+        except Exception:
+            log.exception("worker 未捕获异常")
+        finally:
+            TASKS.task_done()
+```
+
+改为：
+
+```python
+def handle(project, iid):
+    try:
+        _handle(project, iid)
+    finally:
+        with SEEN_LOCK:
+            SEEN.discard((project, iid))
+
+
+def worker():
+    while True:
+        project, iid = TASKS.get()
+        try:
+            handle(project, iid)
+        except Exception:
+            log.exception("worker 未捕获异常")
+        finally:
+            TASKS.task_done()
+```
+
+---
+
+### 3.16 `Handler.do_POST()` 增加 project 识别
+
+在 payload 解析完成后、判断 `object_kind` 之前增加：
+
+```python
+        # 多 project 的关键：先从 webhook 识别 project，并校验白名单。
+        project = (payload.get("project") or {}).get("path_with_namespace", "")
+        if not project or project not in PROJECTS:
+            self._json(202, {"ignored": "unknown-project", "project": project})
+            return
+```
+
+Note Hook 中所有调用加 project：
+
+```python
+issue = api_get(project, "/issues/%d" % iid)
+...
+enqueue(project, iid)
+self._json(202, {"queued": iid, "project": project, "via": "note"})
+```
+
+Issue Hook 中：
+
+```python
+enqueue(project, iid)
+self._json(202, {"queued": iid, "project": project})
+```
+
+注意：
+
+- 不要只校验 label，必须先校验 project；
+- 不在 `PROJECTS` 里的 project 直接返回 202；
+- 不要把 `project` 写死成 `PROJECT_PATH`。
+
+---
+
+### 3.17 `main()` 遍历所有 project
+
+原代码：
+
+```python
+    ensure_runtime_labels()
+    recover_stale_processing()
+    recover_queued_triggers()
+    threading.Thread(target=worker, daemon=True).start()
+    server = ThreadingHTTPServer(("0.0.0.0", PORT), Handler)
+    log.info("issue-bot 监听 :%s，project=%s，label=%s", PORT, PROJECT_PATH, TRIGGER_LABEL)
+```
+
+改为：
+
+```python
+    for project in PROJECTS:
+        ensure_runtime_labels(project)
+        recover_stale_processing(project)
+        recover_queued_triggers(project)
+    threading.Thread(target=worker, daemon=True).start()
+    server = ThreadingHTTPServer(("0.0.0.0", PORT), Handler)
+    log.info("issue-bot 监听 :%s，projects=%s，label=%s", PORT, ",".join(PROJECTS), TRIGGER_LABEL)
+```
+
+`/healthz` 可以增加：
+
+```python
+"projects": PROJECTS
+```
+
+方便确认 bot 实际加载了哪些 project。
+
+---
+
+## 4. `scripts/gitlab-init.sh` 改造
+
+### 4.1 多 project 的 token 提示
+
+在 `setup_automation()` 里，原来的 bot token 逻辑前增加：
+
+```bash
+  local multi_project=0
+  case ",${AUTOMATION_PROJECTS:-}," in
+    *,*,*) multi_project=1 ;;
+  esac
+```
+
+然后：
+
+- 如果 `AUTOMATION_BOT_TOKEN` 已设置，继续使用；
+- 如果多 project：
+  - 没有 `data/automation/token` 时，提示“project access token 不能跨项目”，暂用 root PAT；
+  - 已有 token 时，提示“确认该 token 可访问所有目标项目”；
+- 单 project 继续原逻辑：优先 project access token，失败降级 root PAT。
+
+替换后的核心逻辑：
+
+```bash
+  local multi_project=0
+  case ",${AUTOMATION_PROJECTS:-}," in
+    *,*,*) multi_project=1 ;;
+  esac
+
+  if [ -n "${AUTOMATION_BOT_TOKEN:-}" ]; then
+    info "使用 .env 里的 AUTOMATION_BOT_TOKEN"
+  elif [ "$multi_project" = "1" ]; then
+    if [ ! -s data/automation/token ]; then
+      warn "多 project 模式：project access token 不能跨项目，先使用 root PAT；生产请换成可访问全部目标项目的 token"
+      cp .gitlab-pat data/automation/token
+      chmod 600 data/automation/token
+      info "bot token 已写入 data/automation/token"
+    else
+      warn "多 project 模式：复用已有 data/automation/token，请确认该 token 可访问所有目标项目"
+    fi
+  elif [ ! -s data/automation/token ]; then
+    # 原 project access token 逻辑保持不变
+    ...
+  else
+    info "复用已有 data/automation/token"
+  fi
+```
+
+注意：
+
+- 这是最小方案，不引入 per-project token；
+- 生产环境应换成有目标项目权限的最小权限 token；
+- 不要为了多 project 自动创建 group owner token。
+
+### 4.2 webhook 改为 group 级
+
+原代码是项目级：
+
+```bash
+  hooks=$(api GET "/projects/${PROJECT_ID}/hooks" ...)
+  api PUT "/projects/${PROJECT_ID}/hooks/${hook_id}" ...
+  api POST "/projects/${PROJECT_ID}/hooks" ...
+```
+
+改为 group 级：
+
+```bash
+  # 多 project 用 group webhook：一次覆盖组内所有项目，bot 再按 project 过滤。
+  local hook_url="http://issue-bot:8080/webhook"
+  local hooks hook_id
+  hooks=$(api GET "/groups/${GROUP_ID}/hooks" 2>/dev/null || echo '[]')
+  hook_id=$(printf '%s' "$hooks" | python3 -c 'import sys,json;d=json.load(sys.stdin);print(next((str(h["id"]) for h in d if h.get("url","").endswith("/webhook")),""))' 2>/dev/null || true)
+
+  if [ -n "${hook_id:-}" ]; then
+    api PUT "/groups/${GROUP_ID}/hooks/${hook_id}" \
+      --data-urlencode "url=${hook_url}" \
+      --data-urlencode "token=${AUTOMATION_WEBHOOK_SECRET}" \
+      --data "issue_events=true" --data "note_events=true" --data "enable_ssl_verification=false" >/dev/null 2>&1 \
+      || warn "更新 group webhook 失败，请检查组 Settings → Webhooks"
+  else
+    api POST "/groups/${GROUP_ID}/hooks" \
+      --data-urlencode "url=${hook_url}" \
+      --data-urlencode "token=${AUTOMATION_WEBHOOK_SECRET}" \
+      --data "issue_events=true" --data "note_events=true" --data "enable_ssl_verification=false" >/dev/null 2>&1 \
+      || warn "创建 group webhook 失败，请检查组 Settings → Webhooks"
+  fi
+
+  info "issue-bot 配置完成：group webhook=${hook_url}"
+```
+
+前提：
+
+- `GROUP_ID` 在 `create_project()` 中已经设置；
+- 如果内部分支没有 `GROUP_ID`，先用 group path 查一次：
+
+```bash
+GROUP_ID=$(api GET "/groups/${AUTOMATION_GROUP:-observability}" \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')
+```
+
+注意：
+
+- 从单项目升级时，旧的 project webhook 可以手工删除，避免同一事件重复投递；
+- bot 侧已有 `(project, iid)` 去重，重复投递不会重复处理，但会产生无意义请求。
+
+---
+
+## 5. `scripts/selfcheck.sh` 改造
+
+原自检只查项目级 webhook：
+
+```bash
+hooks=$(curl ... "${GITLAB_URL}/api/v4/projects/${pid}/hooks" ...)
+```
+
+改为优先查 group webhook，失败再回退项目级：
+
+```bash
+      local hooks hook_ok group_path
+      group_path=$(grep -E '^AUTOMATION_GROUP=' .env 2>/dev/null | cut -d= -f2)
+      group_path=${group_path:-observability}
+      hooks=$(curl -fsS -m 10 --header "PRIVATE-TOKEN: $pat" \
+        "${GITLAB_URL}/api/v4/groups/${group_path}/hooks" 2>/dev/null || echo '[]')
+      hook_ok=$(printf '%s' "$hooks" | python3 -c 'import sys,json;d=json.load(sys.stdin);print(any(h.get("url","").endswith("/webhook") for h in d))' 2>/dev/null || echo False)
+      if [ "$hook_ok" != "True" ]; then
+        # 兼容升级前创建的项目级 webhook
+        hooks=$(curl -fsS -m 10 --header "PRIVATE-TOKEN: $pat" \
+          "${GITLAB_URL}/api/v4/projects/${pid}/hooks" 2>/dev/null || echo '[]')
+        hook_ok=$(printf '%s' "$hooks" | python3 -c 'import sys,json;d=json.load(sys.stdin);print(any(h.get("url","").endswith("/webhook") for h in d))' 2>/dev/null || echo False)
+      fi
+      [ "$hook_ok" = "True" ] && ok "issue webhook 已配置" || bad "issue webhook 未配置（检查组或项目 Settings → Webhooks）"
+```
+
+如果 `AUTOMATION_GROUP` 可能是子组（如 `a/b`），需要先 URL encode：
+
+```bash
+group_enc=$(python3 -c 'import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1], safe=""))' "$group_path")
+# 使用 /groups/${group_enc}/hooks
+```
+
+---
+
+## 6. 文档更新
+
+### 6.1 `automation/README.md`
+
+增加“多 project”章节：
+
+```markdown
+## 多 project
+
+一个 bot 可以处理多个 project，用同一个 group token 即可，不需要每个项目一个容器。
+
+配置：
+
+AUTOMATION_PROJECTS=observability/metric-ingest-service,observability/payment-service
+
+规则：
+
+- GITLAB_PROJECTS 是逗号分隔的完整 group/project 路径；
+- 为空时回退到单个 GITLAB_PROJECT_PATH；
+- webhook 必须来自 GITLAB_PROJECTS 中的 project，否则直接忽略；
+- state / workspace 按 project 分目录，不同项目的 #1 不会冲突；
+- 启动恢复会遍历所有配置项目；
+- gitlab-init.sh 使用 group webhook，组内所有 project 的事件都进同一个 bot，再由 bot 过滤；
+- 多 project 时 data/automation/token 必须是可访问全部目标项目的 token。
+```
+
+### 6.2 `README.md`
+
+在自动化模式说明中增加：
+
+```markdown
+一个 bot 可处理多个 project：在 .env 配置 AUTOMATION_PROJECTS（逗号分隔完整路径），
+webhook 会按 project 过滤，state / workspace 也按 project 隔离。
+多项目需要使用可访问全部目标项目的 token。
+```
+
+### 6.3 `docs/自动化流程.md`
+
+更新：
+
+```text
+- 创建 group webhook（http://issue-bot:8080/webhook）
+- 多 project 时按 AUTOMATION_PROJECTS 逐个创建标签、恢复 ai-processing / ai-fix
+- state 和 workspace 目录带 project 前缀
+```
+
+---
+
+## 7. 测试清单
+
+### 7.1 语法检查
+
+```bash
+python3 -m py_compile automation/issue_bot.py
+bash -n scripts/gitlab-init.sh
+bash -n scripts/selfcheck.sh
+```
+
+### 7.2 单项目兼容
+
+`.env`：
+
+```bash
+AUTOMATION_PROJECTS=
+AUTOMATION_GROUP=observability
+AUTOMATION_PROJECT=metric-ingest-service
+```
+
+启动后：
+
+```bash
+docker logs ai-coding-pilot-issue-bot --tail=50
+```
+
+应看到：
+
+```text
+projects=observability/metric-ingest-service
+```
+
+在 issue 打 `ai-fix`，应正常出 MR。
+
+### 7.3 多项目
+
+`.env`：
+
+```bash
+AUTOMATION_PROJECTS=observability/metric-ingest-service,observability/payment-service
+```
+
+验证：
+
+```text
+1. 两个项目各建一个 issue；
+2. 两个 issue 都打 ai-fix；
+3. 两个项目都能出各自的 MR；
+4. 两个 MR 的 source_branch 都是 ai/issue-1-*，但分别在不同仓库；
+5. state 目录出现：
+   data/automation/state/observability%2Fmetric-ingest-service/
+   data/automation/state/observability%2Fpayment-service/
+6. workspace 目录按 project 分开；
+7. 一个项目失败不影响另一个项目。
+```
+
+### 7.4 webhook 白名单
+
+构造一个来自未配置项目的 webhook：
+
+```json
+{
+  "object_kind": "issue",
+  "project": {"path_with_namespace": "observability/unknown"},
+  "object_attributes": {"iid": 1, "action": "update", "state": "opened"},
+  "labels": [{"title": "ai-fix"}]
+}
+```
+
+应返回：
+
+```json
+{"ignored": "unknown-project", "project": "observability/unknown"}
+```
+
+### 7.5 启动恢复
+
+给两个项目各放一个 `ai-processing` issue：
+
+```text
+项目 A：有打开的 MR → 应恢复 ai-done
+项目 B：没有 MR     → 应恢复 ai-failed 并评论
+```
+
+确认 PUT 请求路径分别带：
+
+```text
+/api/v4/projects/observability%2Fa/issues/...
+/api/v4/projects/observability%2Fb/issues/...
+```
+
+---
+
+## 8. 常见问题
+
+### 8.1 所有事件都返回 `unknown-project`
+
+检查：
+
+- `AUTOMATION_PROJECTS` 是否是逗号分隔的完整路径；
+- webhook 里的 `project.path_with_namespace` 是否和配置完全一致；
+- 是否把项目名写成了短名，例如 `payment-service`，实际应为 `observability/payment-service`；
+- 子组路径是否完整，例如 `group/subgroup/project`。
+
+### 8.2 只有第一个项目能打标签 / 评论
+
+原因通常是 token 只能访问一个项目。
+
+检查：
+
+```bash
+cat data/automation/token
+```
+
+多项目需要：
+
+- 一个能访问全部目标项目的 token；或
+- 明确设置 `AUTOMATION_BOT_TOKEN`。
+
+`gitlab-init.sh` 自动创建的 project access token 只覆盖当前项目，不能跨项目。
+
+### 8.3 两个项目的 issue #1 状态互相覆盖
+
+说明 state / workspace 还没有完全改成 project 维度。
+
+检查这些地方是否都传了 project：
+
+```text
+state_path
+load_state
+save_state
+clear_state
+enqueue
+SEEN
+TASKS
+workspace 路径
+```
+
+不能只改 API，不改 state。
+
+### 8.4 webhook 重复投递
+
+如果之前已经有 project webhook，现在又创建了 group webhook：
+
+- 同一个事件可能进 bot 两次；
+- bot 的 `SEEN=(project, iid)` 会去重；
+- 建议删除旧的项目级 webhook。
+
+### 8.5 多项目仍然是串行
+
+当前还是单 worker：
+
+```python
+threading.Thread(target=worker, daemon=True).start()
+```
+
+多个 project 的任务会排队执行。  
+这是本次最小方案的预期行为，不要在这次改造里引入 worker pool。
+
+---
+
+## 9. 本次不做的内容
+
+明确不要在这次改造中做：
+
+```text
+1. 每 project 一个 token
+2. 每 project 一个容器
+3. controller + worker 容器
+4. 每 project 并发池
+5. pipeline watcher 独立线程
+6. 多项目 measure.py 汇总
+7. 复杂 RBAC / 审计平台
+```
+
+这些可以作为下一阶段，但不要混进这次最小改造。
+
+---
+
+## 10. 完成标准
+
+满足以下条件即可认为改造完成：
+
+```text
+[ ] 一个 bot 能加载多个 project
+[ ] webhook 能按 project 路由
+[ ] 未配置项目被忽略
+[ ] 两个项目的 issue #1 不冲突
+[ ] 两个项目能各自 clone / push / 开 MR
+[ ] state / workspace 按 project 隔离
+[ ] 启动恢复按 project 执行
+[ ] 单项目配置仍能工作
+[ ] gitlab-init.sh 创建 group webhook
+[ ] selfcheck.sh 能识别 group webhook
+[ ] 文档已更新
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmpxinchen/tmp1",
-  "version": "1.0.56",
+  "version": "1.0.57",
   "description": "gitlab-ce-18.11.12.tar transfer chunk 44/44",
   "license": "ISC",
   "author": "xinchen12"