@tmpxinchen/tmp1 1.0.56 → 1.0.58

package/ai-coding-pilot-company-gitlab-mirror.md

@@ -0,0 +1,1088 @@
+# issue-bot 对接公司 GitLab 8.16 改造说明
+
+## 0. 目标与边界
+
+目标是把当前本地 `ai-coding-pilot` 改成：
+
+```text
+本地 GitLab：issue / 队列 / AI 工作区 / 本地门禁
+公司 GitLab：真实代码 / AI 分支 / 正式 MR
+```
+
+并使用一个单向只读镜像，让本地 GitLab 也能看到公司代码和分支。
+
+```text
+公司 GitLab（代码主库）
+        ↓ 只读镜像
+本地 GitLab（issue + 公司代码镜像）
+        ↑
+        │ 本地 issue 触发
+   issue-bot
+        │ clone / push / API v3
+        ↓
+公司 GitLab（正式 MR）
+```
+
+本次涉及：
+
+```text
+automation/issue_bot.py
+automation/company-projects.example.json
+scripts/mirror-company.sh
+docker-compose.yml
+.env
+.env.example
+scripts/gitlab-init.sh
+scripts/selfcheck.sh
+start.sh
+README.md
+automation/README.md
+docs/自动化流程.md
+```
+
+本次不做：
+
+```text
+公司 GitLab issue 接入
+公司 GitLab webhook 配置
+公司 GitLab runner 管理
+公司 CI 变量修改
+双向同步
+main 自动同步
+整仓 mirror 到公司
+本地正式 MR
+自动合并
+```
+
+前提已经确认：
+
+```text
+公司 GitLab 8.16.8 API v3 可访问
+PAT 可用
+可以 push feature 分支
+可以创建 MR
+```
+
+---
+
+## 1. 给内部模型的操作要求
+
+内部代码已经分叉，**不要整文件覆盖 `automation/issue_bot.py`**。
+
+请按函数/代码块修改：
+
+```text
+1. 先备份
+2. 用 grep 找函数
+3. 只替换本文明确指出的函数/代码块
+4. 保留内部已有的标签名、路径、日志、变量名
+5. 不要删除内部已有的其他功能
+6. 改完执行 py_compile / bash -n / 端到端测试
+```
+
+建议先定位：
+
+```bash
+grep -n '^def \|^class \|^PROJECT_PATH\|^TASKS\|^SEEN' automation/issue_bot.py
+grep -n 'issue-bot:' docker-compose.yml
+grep -n 'setup_automation\|ensure_mirror_token' scripts/gitlab-init.sh
+```
+
+如果内部已有 `COMPANY_*` 或类似变量，保持语义一致即可，不要求和本文变量名完全相同。
+
+---
+
+# 第一部分：配置
+
+## 2. `.env` 和 `.env.example`
+
+增加：
+
+```bash
+# 公司 GitLab 模式：配置后代码和 MR 都走公司 GitLab，本地只保留 issue
+COMPANY_GITLAB_URL=http://gitlab.company.internal
+COMPANY_TOKEN=
+COMPANY_TOKEN_FILE=/run/automation/company-token
+COMPANY_PROJECTS_FILE=/run/automation/company-projects.json
+
+# 本地 GitLab 只读镜像 token
+GITLAB_MIRROR_TOKEN_FILE=/run/automation/mirror-token
+MIRROR_INTERVAL_SECONDS=300
+
+# 门禁脚本：默认用公司仓库内的 scripts/check-convention.sh
+# 公司仓库没有该脚本时，改成挂载进来的绝对路径
+AUTOMATION_GATE_SCRIPT=scripts/check-convention.sh
+```
+
+说明：
+
+- `COMPANY_TOKEN` 可以留空，优先用 `COMPANY_TOKEN_FILE`；
+- `COMPANY_TOKEN_FILE` 和 `COMPANY_PROJECTS_FILE` 在容器内路径；
+- 本地 issue 仍由 `AUTOMATION_PROJECTS` 和 `GITLAB_PROJECTS` 控制；
+- `MIRROR_INTERVAL_SECONDS` 只影响镜像服务。
+
+## 3. 公司项目映射
+
+新增：
+
+```text
+automation/company-projects.example.json
+```
+
+内容：
+
+```json
+{
+  "local-ai/ai-tasks-payment": {
+    "project_id": 456,
+    "path": "company-group/payment-service",
+    "target_branch": "main"
+  }
+}
+```
+
+部署时复制到：
+
+```bash
+cp automation/company-projects.example.json \
+   data/automation/company-projects.json
+```
+
+规则：
+
+```text
+key                  = 本地 GitLab 的 project 路径
+project_id           = 公司 GitLab 的 project ID（数字）
+path                 = 公司 GitLab 的 project 路径
+target_branch        = 公司目标分支
+clone_url            = 可选，SSH clone 地址
+```
+
+本地 project、公司 project、group 名字都不需要一致。
+
+必须一致的是：
+
+```text
+本地实际 project 路径
+=
+AUTOMATION_PROJECTS 中的本地路径
+=
+company-projects.json 的 key
+```
+
+公司侧：
+
+```text
+company-projects.json 的 path
+=
+公司实际 project 路径
+```
+
+`project_id` 必须是公司项目 ID，不是本地 `.gitlab-project-id`。
+
+## 4. token 文件
+
+公司 token：
+
+```bash
+printf '%s' '公司PAT' > data/automation/company-token
+chmod 600 data/automation/company-token
+```
+
+本地镜像 token：
+
+```bash
+# 由 gitlab-init.sh 生成，见后文
+data/automation/mirror-token
+```
+
+不要：
+
+```text
+把 token 写进 git remote URL
+把 token 提交到仓库
+把 token 打到日志
+```
+
+---
+
+# 第二部分：`automation/issue_bot.py`
+
+## 5. 新增公司模式常量
+
+在 `GITLAB_URL`、`PROJECT_PATH` 附近增加：
+
+```python
+COMPANY_GITLAB_URL = os.environ.get("COMPANY_GITLAB_URL", "").rstrip("/")
+COMPANY_TOKEN_FILE = os.environ.get("COMPANY_TOKEN_FILE", "/run/automation/company-token")
+COMPANY_PROJECTS_FILE = Path(os.environ.get(
+    "COMPANY_PROJECTS_FILE", "/run/automation/company-projects.json"))
+COMPANY_PROJECTS = {}
+```
+
+`Path` 已经由原文件导入，不要重复导入。
+
+增加门禁脚本常量：
+
+```python
+# 门禁脚本：默认用仓库内的 scripts/check-convention.sh；
+# 公司仓库没有该脚本时，挂载本地门禁并配成绝对路径。
+GATE_SCRIPT = os.environ.get("AUTOMATION_GATE_SCRIPT", "scripts/check-convention.sh")
+```
+
+---
+
+## 6. 加载公司项目映射
+
+在 `log = logging.getLogger(...)` 后面增加：
+
+```python
+def load_company_projects():
+    """加载本地 issue 到公司 GitLab 项目的映射。"""
+    global COMPANY_PROJECTS
+    COMPANY_PROJECTS = {}
+    if not COMPANY_PROJECTS_FILE.exists():
+        return
+    try:
+        raw = json.loads(COMPANY_PROJECTS_FILE.read_text(encoding="utf-8"))
+    except Exception as e:
+        log.error("读取公司 GitLab 项目映射失败 %s: %s", COMPANY_PROJECTS_FILE, e)
+        return
+    if not isinstance(raw, dict):
+        log.error("公司 GitLab 项目映射必须是 JSON 对象: %s", COMPANY_PROJECTS_FILE)
+        return
+    for local_project, cfg in raw.items():
+        if not isinstance(cfg, dict):
+            continue
+        project_id = cfg.get("project_id")
+        project_path = cfg.get("path")
+        if not isinstance(project_id, int) or not project_path:
+            log.error("公司 GitLab 项目映射缺少 project_id/path: %s", local_project)
+            continue
+        COMPANY_PROJECTS[local_project] = {
+            "project_id": project_id,
+            "path": project_path,
+            "target_branch": cfg.get("target_branch") or TARGET_BRANCH or "main",
+            "clone_url": cfg.get("clone_url") or "",
+        }
+```
+
+注意：
+
+- `project_id` 必须是 int；
+- 映射文件损坏时只记日志，不要杀掉进程；
+- 真正执行任务时如果公司模式已开启但项目没有映射，要 fail closed，见 `company_for()`。
+
+---
+
+## 7. 公司 token / 项目路由 / API v3
+
+新增：
+
+```python
+def company_token():
+    t = os.environ.get("COMPANY_TOKEN", "").strip()
+    if t:
+        return t
+    try:
+        return Path(COMPANY_TOKEN_FILE).read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+
+
+def company_for(project):
+    """公司 GitLab 模式：返回该项目配置；未配置公司地址时返回 None。"""
+    if not COMPANY_GITLAB_URL:
+        return None
+    cfg = COMPANY_PROJECTS.get(project)
+    if not cfg:
+        raise RuntimeError("公司 GitLab 模式未配置本地 project 映射: " + project)
+    if not company_token():
+        raise RuntimeError("公司 GitLab token 为空：检查 COMPANY_TOKEN 或 " + COMPANY_TOKEN_FILE)
+    return cfg
+
+
+def company_clone_url(cfg):
+    if cfg.get("clone_url"):
+        return cfg["clone_url"]
+    u = urllib.parse.urlparse(COMPANY_GITLAB_URL)
+    tok = urllib.parse.quote(company_token(), safe="")
+    return "%s://oauth2:%s@%s/%s.git" % (u.scheme, tok, u.netloc, cfg["path"])
+
+
+def company_api_raw(cfg, method, path, data=None, params=None, timeout=30):
+    t = company_token()
+    if not t:
+        raise RuntimeError("公司 GitLab token 为空：检查 COMPANY_TOKEN 或 " + COMPANY_TOKEN_FILE)
+    q = {"private_token": t}
+    if params:
+        q.update(params)
+    url = COMPANY_GITLAB_URL + "/api/v3/projects/%d%s" % (int(cfg["project_id"]), path)
+    url += "?" + urllib.parse.urlencode(q)
+    body = urllib.parse.urlencode(data).encode("utf-8") if data is not None else None
+    req = urllib.request.Request(url, data=body, method=method)
+    if body is not None:
+        req.add_header("Content-Type", "application/x-www-form-urlencoded")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            raw = r.read()
+            return json.loads(raw) if raw else {}
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", "replace")[:500]
+        raise RuntimeError("Company GitLab API %s %s -> %s: %s" %
+                           (method, path, e.code, mask(detail)))
+
+
+def company_api(cfg, method, path, data=None, params=None, timeout=30):
+    return company_api_raw(cfg, method, path, data=data, params=params, timeout=timeout)
+
+
+def company_note_mr(cfg, mr_iid, body):
+    try:
+        company_api(cfg, "POST", "/merge_requests/%d/notes" % mr_iid, {"body": body})
+    except Exception as e:
+        log.warning("评论公司 MR !%s 失败: %s", mr_iid, mask(e))
+```
+
+关键点：
+
+```text
+公司 API 固定 /api/v3，不要用 /api/v4
+认证参数用 private_token
+POST 用 application/x-www-form-urlencoded
+project_id 用公司 ID
+```
+
+如果公司 8.16 对 `private_token` 参数有限制，可以在 `company_api_raw()` 里改成已验证可用的认证方式，但不要把 token 打到日志。
+
+---
+
+## 8. 日志中屏蔽公司 token
+
+找到原 `mask()`：
+
+```python
+def mask(text):
+    t = token()
+    if t:
+        return str(text).replace(t, "***")
+    return str(text)
+```
+
+改为：
+
+```python
+def mask(text):
+    out = str(text)
+    for value in (token(), company_token()):
+        if value:
+            out = out.replace(value, "***")
+    return out
+```
+
+---
+
+## 9. 门禁脚本可配置
+
+原 `build_prompt()` 中：
+
+```text
+4. 完成后运行 ./scripts/check-convention.sh，确保通过；
+```
+
+改为：
+
+```text
+4. 完成后运行 %s，确保通过；
+```
+
+并把 `GATE_SCRIPT` 加入格式化参数。
+
+原 `_handle()` 中：
+
+```python
+r = run(["bash", "scripts/check-convention.sh"], cwd=ws, timeout=300)
+```
+
+改为：
+
+```python
+gate = GATE_SCRIPT
+if not os.path.isabs(gate):
+    gate = str(ws / gate)
+r = run(["bash", gate], cwd=ws, timeout=300)
+```
+
+公司仓库没有 `scripts/check-convention.sh` 时：
+
+```bash
+AUTOMATION_GATE_SCRIPT=/opt/automation/check-convention.sh
+```
+
+并把脚本挂进 issue-bot 容器。
+
+---
+
+## 10. `_handle()`：公司模式和重复 MR 检查
+
+原 `_handle()` 在加载 state 后、发送“已接单”前，增加：
+
+```python
+    # 公司 GitLab 模式：代码从公司仓库拉，MR 也开到公司；本地 GitLab 只保留 issue。
+    company = company_for(project)
+    company_mode = company is not None
+
+    if not company_mode:
+        # 同一 issue 已有打开的本地 MR 时不再重复开
+        for mr in api_get(project, "/merge_requests", state="opened", per_page=100):
+            if mr.get("source_branch", "").startswith("ai/issue-%d-" % iid) or \
+               ("Closes #%d" % iid) in (mr.get("description") or ""):
+                note_issue(project, iid, "已有打开的 MR：%s，跳过重复处理。" % mr.get("web_url", ""))
+                set_labels_safe(project, iid, add=[DONE_LABEL], remove=[PROCESSING_LABEL])
+                return
+    else:
+        # 公司模式下必须查公司 MR，避免重启/重复触发后重复开 MR
+        try:
+            open_mrs = company_api(company, "GET", "/merge_requests",
+                                   params={"state": "opened"})
+        except Exception as e:
+            raise RuntimeError("查询公司 MR 失败，已停止以避免重复开 MR: " + mask(e))
+        for mr in open_mrs:
+            if mr.get("source_branch", "").startswith("ai/issue-%d-" % iid):
+                note_issue(project, iid, "已有打开的公司 MR：%s，跳过重复处理。"
+                           % mr.get("web_url", ""))
+                set_labels_safe(project, iid, add=[DONE_LABEL], remove=[PROCESSING_LABEL])
+                return
+```
+
+注意：
+
+- 公司模式必须查公司 MR，不能查本地 MR；
+- 查询失败时停止，不要盲目重复创建；
+- 重复时本地 issue 标 `ai-done`，不重新推送。
+
+---
+
+## 11. `_handle()`：clone 来源
+
+原代码：
+
+```python
+        project_info = api_get(project, "")
+        target = TARGET_BRANCH or project_info.get("default_branch") or "main"
+        ws.parent.mkdir(parents=True, exist_ok=True)
+        log.info("clone %s 到 %s", project, ws)
+        r = run(["git", "clone", "--depth", "1", "--branch", target, clone_url(project), str(ws)],
+                cwd="/tmp", timeout=300, log_cmd=False)
+```
+
+改为：
+
+```python
+        if company_mode:
+            target = company["target_branch"]
+            source_url = company_clone_url(company)
+            log.info("使用公司 GitLab 仓库: %s", company["path"])
+        else:
+            project_info = api_get(project, "")
+            target = TARGET_BRANCH or project_info.get("default_branch") or "main"
+            source_url = clone_url(project)
+        ws.parent.mkdir(parents=True, exist_ok=True)
+        log.info("clone %s 到 %s", project, ws)
+        r = run(["git", "clone", "--depth", "1", "--branch", target, source_url, str(ws)],
+                cwd="/tmp", timeout=300, log_cmd=False)
+```
+
+这样公司模式会直接从公司仓库 clone，不再碰本地仓库代码。
+
+---
+
+## 12. `_handle()`：推送和开 MR
+
+原代码在 `git push` 之后，会创建本地 MR 并等待本地 pipeline。
+
+公司模式必须改成：
+
+```text
+push 到公司 origin
+→ 调公司 API v3 创建 MR
+→ 本地 issue 评论公司 MR 链接
+→ 本地 issue 标 ai-done
+→ 不创建本地 MR
+→ 不等待本地 pipeline
+```
+
+在 `git push` 成功后，先提取 assumptions：
+
+```python
+        assumptions = extract_block(output, "ASSUMPTIONS", "END_ASSUMPTIONS")
+```
+
+然后插入公司模式分支：
+
+```python
+        if company_mode:
+            desc = "由 AI 自动化生成，关联本地任务 #%d。" % iid
+            if assumptions:
+                desc += "\n\n### AI 假设与待确认点\n\n" + assumptions[:4000]
+            mr = company_api(company, "POST", "/merge_requests", {
+                "source_branch": branch,
+                "target_branch": target,
+                "title": "feat(ai): %s (#%d)" % (title, iid),
+                "description": desc,
+            })
+            mr_iid = mr.get("iid")
+            mr_url = mr.get("web_url", "")
+            clear_state(project, iid)
+            set_labels_safe(project, iid, add=[DONE_LABEL],
+                            remove=[PROCESSING_LABEL, TRIGGER_LABEL, RESUME_LABEL,
+                                    WAIT_LABEL, FAILED_LABEL])
+            note_issue(project, iid, "✅ 公司 MR 已创建：%s" % mr_url)
+            if mr_iid:
+                company_note_mr(company, mr_iid,
+                               "🤖 本 MR 由本地 issue #%d 自动生成。" % iid)
+            log.info("%s issue #%s 完成，公司 MR=%s", project, iid, mr_url)
+            return
+```
+
+本地模式的原有逻辑保留在 `return` 之后：
+
+```python
+        # 以下只用于未配置公司模式的本地模式
+        try:
+            api(project, "POST", "/labels", {"name": "path::ai", "color": "#428bca"})
+        except Exception:
+            pass
+        ...
+```
+
+注意：
+
+- 公司 MR 描述不要写 `Closes #iid`，因为公司 issue 编号和本地不同；
+- 公司模式不调用 `wait_pipeline()`；
+- 公司 CI 由公司 GitLab 自己执行。
+
+---
+
+## 13. 启动恢复
+
+原 `recover_stale_processing()` 只查本地 MR：
+
+```python
+        open_mrs = api_get(project, "/merge_requests", state="opened", per_page=100)
+```
+
+改为：
+
+```python
+    try:
+        company = company_for(project)
+    except Exception as e:
+        log.warning("恢复 %s 时检查公司 GitLab 配置失败: %s", project, mask(e))
+        return
+    try:
+        if company:
+            open_mrs = company_api(company, "GET", "/merge_requests",
+                                   params={"state": "opened"})
+        else:
+            open_mrs = api_get(project, "/merge_requests", state="opened", per_page=100)
+    except Exception as e:
+        log.warning("查询 %s 打开 MR 失败，跳过启动恢复以避免误标: %s", project, mask(e))
+        return
+```
+
+其余判断保持不变：
+
+```python
+        has_mr = any(
+            m.get("source_branch", "").startswith("ai/issue-%d-" % iid)
+            or ("Closes #%d" % iid) in (m.get("description") or "")
+            for m in open_mrs
+        )
+```
+
+这样：
+
+```text
+公司模式：查看公司 MR
+本地模式：查看本地 MR
+```
+
+## 14. `main()` 加载公司配置
+
+在 `main()` 开始处增加：
+
+```python
+    load_company_projects()
+```
+
+并增加日志：
+
+```python
+    if COMPANY_GITLAB_URL:
+        if not company_token():
+            log.error("COMPANY_GITLAB_URL 已配置，但公司 GitLab token 为空")
+        log.info("公司 GitLab 模式：%s，映射 %d 个本地 project",
+                 COMPANY_GITLAB_URL, len(COMPANY_PROJECTS))
+```
+
+`/healthz` 可以增加：
+
+```python
+                        "company": bool(COMPANY_GITLAB_URL),
+                        "company_projects": sorted(COMPANY_PROJECTS)
+```
+
+方便验证配置是否加载。
+
+---
+
+# 第三部分：本地只读镜像
+
+## 15. 新增 `scripts/mirror-company.sh`
+
+新增完整文件：
+
+```bash
+#!/usr/bin/env bash
+# ============================================================================
+# 公司 GitLab → 本地 GitLab 单向只读镜像
+#
+# 只同步公司仓库的分支和 tag 到本地同名 project。
+# 本地 project 只用于查看代码和 issue，不允许在本地提交/开正式 MR。
+#
+# 用法：
+#   ./scripts/mirror-company.sh --once
+#   ./scripts/mirror-company.sh --loop
+# ============================================================================
+set -euo pipefail
+umask 077
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+COMPANY_GITLAB_URL=${COMPANY_GITLAB_URL:-}
+COMPANY_TOKEN_FILE=${COMPANY_TOKEN_FILE:-/run/automation/company-token}
+COMPANY_PROJECTS_FILE=${COMPANY_PROJECTS_FILE:-/run/automation/company-projects.json}
+LOCAL_GITLAB_URL=${LOCAL_GITLAB_URL:-${GITLAB_URL:-http://gitlab.local:8929}}
+LOCAL_TOKEN_FILE=${GITLAB_MIRROR_TOKEN_FILE:-/run/automation/mirror-token}
+MIRROR_CACHE_DIR=${MIRROR_CACHE_DIR:-data/mirror}
+MIRROR_INTERVAL_SECONDS=${MIRROR_INTERVAL_SECONDS:-300}
+
+log() { echo "[$(date '+%F %T')] $*"; }
+
+read_secret() {
+  local file=$1
+  [ -s "$file" ] && tr -d '\r\n' < "$file" || true
+}
+
+repo_url() {
+  local base=${1%/} path=$2
+  printf '%s/%s.git\n' "$base" "$path"
+}
+
+write_askpass() {
+  local script=$1 token_file=$2
+  cat > "$script" <<-ASKPASS
+#!/bin/sh
+case "$1" in
+  *Username*) printf '%s\n' oauth2 ;;
+  *Password*) cat "$token_file" ;;
+  *) exit 1 ;;
+esac
+ASKPASS
+  chmod 700 "$script"
+}
+
+sync_one() {
+  local local_project=$1 company_path=$2
+  local cache company_url local_url hash
+  hash=$(printf '%s' "$local_project" | sha256sum | cut -c1-16)
+  cache="$MIRROR_CACHE_DIR/$hash.git"
+  company_url=$(repo_url "$COMPANY_GITLAB_URL" "$company_path")
+  local_url=$(repo_url "$LOCAL_GITLAB_URL" "$local_project")
+
+  mkdir -p "$MIRROR_CACHE_DIR"
+  chmod 700 "$MIRROR_CACHE_DIR" 2>/dev/null || true
+  if [ ! -d "$cache" ]; then
+    log "初始化镜像 $local_project ← $company_path"
+    GIT_ASKPASS="$COMPANY_ASKPASS" GIT_ASKPASS_REQUIRE=force GIT_TERMINAL_PROMPT=0 \
+      git clone --mirror "$company_url" "$cache" >/dev/null 2>&1 || {
+      log "ERROR clone 公司仓库失败：$company_path"
+      return 1
+    }
+  else
+    git -C "$cache" remote set-url origin "$company_url" >/dev/null 2>&1 || return 1
+    # clone --mirror 的 fetch refspec 是 +refs/*:refs/*，--prune 会删除公司已删的分支/tag
+    GIT_ASKPASS="$COMPANY_ASKPASS" GIT_ASKPASS_REQUIRE=force GIT_TERMINAL_PROMPT=0 \
+      git -C "$cache" fetch --prune origin >/dev/null 2>&1 || {
+      log "ERROR fetch 公司仓库失败：$company_path"
+      return 1
+    }
+  fi
+  chmod 700 "$cache" 2>/dev/null || true
+
+  GIT_ASKPASS="$LOCAL_ASKPASS" GIT_ASKPASS_REQUIRE=force GIT_TERMINAL_PROMPT=0 \
+    git -C "$cache" push --mirror "$local_url" >/dev/null 2>&1 || {
+    log "ERROR push 本地镜像失败：$local_project"
+    return 1
+  }
+  log "OK $local_project ← $company_path"
+}
+
+sync_all() {
+  if [ -z "$COMPANY_GITLAB_URL" ]; then
+    log "COMPANY_GITLAB_URL 为空，跳过镜像"
+    return 0
+  fi
+  if [ ! -s "$COMPANY_TOKEN_FILE" ] && [ -z "${COMPANY_TOKEN:-}" ]; then
+    log "公司 token 为空，跳过镜像"
+    return 1
+  fi
+  if [ ! -s "$LOCAL_TOKEN_FILE" ] && [ -z "${GITLAB_MIRROR_TOKEN:-}" ]; then
+    log "本地镜像 token 为空：$LOCAL_TOKEN_FILE"
+    return 1
+  fi
+
+  COMPANY_TOKEN=${COMPANY_TOKEN:-$(read_secret "$COMPANY_TOKEN_FILE")}
+  LOCAL_TOKEN=${GITLAB_MIRROR_TOKEN:-$(read_secret "$LOCAL_TOKEN_FILE")}
+
+  ASKPASS_DIR=$(mktemp -d)
+  trap 'rm -rf "$ASKPASS_DIR"' RETURN
+  printf '%s' "$COMPANY_TOKEN" > "$ASKPASS_DIR/company.token"
+  printf '%s' "$LOCAL_TOKEN" > "$ASKPASS_DIR/local.token"
+  chmod 700 "$ASKPASS_DIR"; chmod 600 "$ASKPASS_DIR"/*.token
+  COMPANY_ASKPASS="$ASKPASS_DIR/company-askpass"
+  LOCAL_ASKPASS="$ASKPASS_DIR/local-askpass"
+  write_askpass "$COMPANY_ASKPASS" "$ASKPASS_DIR/company.token"
+  write_askpass "$LOCAL_ASKPASS" "$ASKPASS_DIR/local.token"
+
+  local lines
+  lines=$(python3 - "$COMPANY_PROJECTS_FILE" <<'PY'
+import json, sys
+try:
+    data = json.load(open(sys.argv[1], encoding="utf-8"))
+except Exception as e:
+    print("ERROR\t%s" % e)
+    raise SystemExit(1)
+for local_project, cfg in data.items():
+    if isinstance(cfg, dict) and cfg.get("path"):
+        print("%s\t%s" % (local_project, cfg["path"]))
+PY
+) || { log "读取 $COMPANY_PROJECTS_FILE 失败"; return 1; }
+
+  local failed=0
+  while IFS=$'\t' read -r local_project company_path; do
+    [ -n "$local_project" ] || continue
+    sync_one "$local_project" "$company_path" || failed=1
+  done <<< "$lines"
+  return "$failed"
+}
+
+case "${1:-}" in
+  --once)
+    sync_all
+    ;;
+  --loop|"")
+    while true; do
+      sync_all || true
+      sleep "$MIRROR_INTERVAL_SECONDS"
+    done
+    ;;
+  *)
+    echo "用法: $0 [--once|--loop]" >&2
+    exit 2
+    ;;
+esac
+```
+
+关键点：
+
+```text
+公司 → 本地 单向
+clone --mirror + fetch --prune + push --mirror
+token 用 GIT_ASKPASS 临时提供，不写进 git remote
+缓存目录 700，token 文件 600
+公司删分支，本地也删
+```
+
+本地 project 必须提前创建，否则 push 镜像会失败。
+
+本地镜像 project 建议：
+
+```text
+关闭 CI/CD
+不要在本地提交
+不要在本地创建正式 MR
+```
+
+---
+
+## 16. `docker-compose.yml` 增加 company-mirror
+
+在 issue-bot 服务后面增加：
+
+```yaml
+  company-mirror:
+    image: ${AUTOMATION_BASE_IMAGE:-ai-coding-python:2026.10}
+    container_name: ai-coding-pilot-company-mirror
+    profiles: ["automation"]
+    restart: unless-stopped
+    depends_on:
+      gitlab:
+        condition: service_started
+    networks:
+      - internal
+    extra_hosts:
+      - "gitlab.local:host-gateway"
+    environment:
+      GITLAB_URL: http://${GITLAB_HOST:-gitlab.local}:${GITLAB_PORT:-8929}
+      GITLAB_MIRROR_TOKEN_FILE: /run/automation/mirror-token
+      GITLAB_MIRROR_TOKEN: ${GITLAB_MIRROR_TOKEN:-}
+      COMPANY_GITLAB_URL: ${COMPANY_GITLAB_URL:-}
+      COMPANY_TOKEN: ${COMPANY_TOKEN:-}
+      COMPANY_TOKEN_FILE: /run/automation/company-token
+      COMPANY_PROJECTS_FILE: /run/automation/company-projects.json
+      MIRROR_CACHE_DIR: /mirror
+      MIRROR_INTERVAL_SECONDS: ${MIRROR_INTERVAL_SECONDS:-300}
+      HOME: /root
+    volumes:
+      - ./scripts/mirror-company.sh:/usr/local/bin/mirror-company.sh:ro
+      - ./data/automation:/run/automation:ro
+      - ./data/mirror:/mirror
+    entrypoint: ["bash", "/usr/local/bin/mirror-company.sh", "--loop"]
+```
+
+如果内部 compose 没有 `AUTOMATION_BASE_IMAGE`，就用实际包含 `git/bash/python3/sha256sum` 的镜像。不要使用没有 `git` 的纯 Python 镜像。
+
+同时 issue-bot 环境变量增加：
+
+```yaml
+      COMPANY_GITLAB_URL: ${COMPANY_GITLAB_URL:-}
+      COMPANY_TOKEN: ${COMPANY_TOKEN:-}
+      COMPANY_TOKEN_FILE: /run/automation/company-token
+      COMPANY_PROJECTS_FILE: /run/automation/company-projects.json
+      AUTOMATION_GATE_SCRIPT: ${AUTOMATION_GATE_SCRIPT:-scripts/check-convention.sh}
+```
+
+---
+
+## 17. `scripts/gitlab-init.sh` 生成本地镜像 token
+
+增加函数：
+
+```bash
+ensure_mirror_token() {
+  mkdir -p data/automation
+  if [ -n "${GITLAB_MIRROR_TOKEN:-}" ]; then
+    info "使用 .env 里的 GITLAB_MIRROR_TOKEN"
+    return 0
+  fi
+  if [ -s .gitlab-pat ] && [ ! -s data/automation/mirror-token ]; then
+    cp .gitlab-pat data/automation/mirror-token
+    chmod 600 data/automation/mirror-token
+    info "本地 GitLab 镜像 token 已写入 data/automation/mirror-token"
+  elif [ -s data/automation/mirror-token ]; then
+    info "复用已有 data/automation/mirror-token"
+  fi
+}
+```
+
+调用位置：
+
+```bash
+start_stack
+mint_pat
+ensure_mirror_token
+create_project
+```
+
+生产环境建议换成：
+
+```text
+只对镜像 project 有 write_repository 权限的专用 token
+```
+
+不要长期使用 root PAT。
+
+---
+
+## 18. `start.sh` 自动启动镜像
+
+在启动 issue-bot 后增加：
+
+```bash
+  if grep -qE '^COMPANY_GITLAB_URL=.' .env; then
+    echo "启动公司 GitLab 只读镜像 ..."
+    docker compose --profile automation up -d company-mirror \
+      || { echo -e "${RED}✘ company-mirror 启动失败，检查 automation/README.md${NC}"; exit 1; }
+  fi
+```
+
+---
+
+## 19. `scripts/selfcheck.sh`
+
+### 19.1 group webhook 路径编码
+
+原来自检用 group path 直接拼 URL，子组会失败。改成：
+
+```bash
+      local hooks hook_ok group_path group_enc
+      group_path=$(grep -E '^AUTOMATION_GROUP=' .env 2>/dev/null | cut -d= -f2)
+      group_path=${group_path:-observability}
+      group_enc=$(python3 -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1],safe=""))' "$group_path")
+      hooks=$(curl -fsS -m 10 --header "PRIVATE-TOKEN: $pat" \
+        "${GITLAB_URL}/api/v4/groups/${group_enc}/hooks" 2>/dev/null || echo '[]')
+```
+
+保留原来的项目级 webhook 回退逻辑。
+
+### 19.2 检查 company-mirror
+
+在 automation 检查块中增加：
+
+```bash
+    if grep -qE '^COMPANY_GITLAB_URL=.' .env 2>/dev/null; then
+      if docker ps --format '{{.Names}}' | grep -q '^ai-coding-pilot-company-mirror$'; then
+        ok "company-mirror 容器在跑"
+      else
+        bad "COMPANY_GITLAB_URL 已配置，但 company-mirror 容器没跑"
+      fi
+    fi
+```
+
+---
+
+# 第四部分：测试与验收
+
+## 20. 语法检查
+
+```bash
+python3 -m py_compile automation/issue_bot.py
+bash -n scripts/mirror-company.sh
+bash -n scripts/gitlab-init.sh
+bash -n scripts/selfcheck.sh
+bash -n start.sh
+docker compose --profile automation config >/dev/null
+```
+
+## 21. 公司 API v3 验证
+
+先在公司内网验证：
+
+```bash
+curl -i -sS -G "$COMPANY_GITLAB_URL/api/v3/user" \
+  --data-urlencode "private_token=$COMPANY_TOKEN"
+```
+
+以及：
+
+```bash
+curl -i -sS -G \
+  "$COMPANY_GITLAB_URL/api/v3/projects/$COMPANY_PROJECT_ID" \
+  --data-urlencode "private_token=$COMPANY_TOKEN"
+```
+
+## 22. 公司模式端到端
+
+1. 本地建 project；
+2. `.env` 配 `AUTOMATION_PROJECTS`；
+3. `company-projects.json` 配映射；
+4. 放公司 token；
+5. 启动 issue-bot；
+6. 本地 issue 打 `ai-fix`；
+7. 预期：
+
+```text
+本地 issue：ai-processing
+公司 GitLab：出现 ai/issue-xxx 分支
+公司 GitLab：出现正式 MR
+本地 issue：评论公司 MR 链接
+本地 issue：ai-done
+本地 GitLab：不出现新 MR
+```
+
+## 23. 镜像验收
+
+```bash
+docker compose --profile automation up -d company-mirror
+docker logs -f ai-coding-pilot-company-mirror
+```
+
+应看到：
+
+```text
+OK local-ai/ai-tasks-payment ← company-group/payment-service
+```
+
+本地 project 的 Code / Branches 应出现公司分支。
+
+测试分支新增和删除：
+
+```text
+公司新增 feature 分支 → 本地出现
+公司删除 feature 分支 → 本地删除
+```
+
+## 24. 失败场景
+
+必须验证：
+
+```text
+公司 project_id 写错       → 不 push、不开 MR、ai-failed
+公司 path 写错             → clone 失败、ai-failed
+target_branch 不存在       → clone/MR 失败、ai-failed
+token 无权限               → 401/403、ai-failed
+重复打 ai-fix              → 已有公司 MR 时不重复开
+处理中重启                 → 有公司 MR 恢复 ai-done
+门禁失败                   → 不 push、ai-failed
+```
+
+---
+
+# 第五部分：安全与限制
+
+## 25. 安全要求
+
+```text
+公司 token 只放文件，600 权限
+本地镜像 token 只放文件，600 权限
+不要把 token 写进 git remote
+不要把 token 打进日志
+本地镜像 project 只读
+本地镜像 project 关闭 CI/CD
+不自动合并
+不 force push main
+不双向同步
+```
+
+## 26. 当前限制
+
+```text
+只支持同 project 的 source_branch → target_branch
+fork MR 需要额外适配 source_project_id
+公司 GitLab 8.16 API 的 MR 字段需以实测为准
+镜像默认只支持 HTTP(S) clone；SSH 需挂私钥
+镜像默认 300 秒同步一次，不是实时
+镜像会 force update，不能用于本地开发仓库
+issue-bot 配置启动时加载，新增映射后需重启
+公司 issue 不接入
+公司 webhook / runner / CI 配置不修改
+```
+
+## 27. 完成标准
+
+```text
+[ ] /api/v3 验证通过
+[ ] 公司模式 healthz 显示 company=true
+[ ] 本地 issue 能触发公司仓库修改
+[ ] 公司只出现一个正式 MR
+[ ] 本地不出现正式 MR
+[ ] 本地 issue 收到公司 MR 链接
+[ ] 公司分支能镜像回本地
+[ ] 重复触发不会重复开 MR
+[ ] 重启恢复能识别公司 MR
+[ ] 门禁失败不会 push
+[ ] 本地镜像 project 只读/关闭 CI
+```

package/package.json

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