[moz] impl(§17): issue_assigned steps git 操作具体化 + ToolchainApiSection Git 说明

改动 1: issue_assigned 编码路径 steps 改为具体 git 命令
  (checkout main → pull → checkout -b → add/commit → push)
改动 2: ToolchainApiSection 新增 Git 操作说明段落（含开发目录路径）
改动 3: 测试更新（issue_assigned 断言 + 3 个 Git 说明测试）
466 passed

docs/design/17-toolchain-handler-enforcement.md

@@ -436,7 +436,7 @@ Agent 可能写了 action_report 但没真做。缓解机制：
 | Review 有新提交 → reviewer | review_updated | toolchain | 4 步 | 读 diff + 检查修改 + 提交 Review + report |
 | Review 评论 → PR 作者 | review_comment | toolchain | 3 步 | 查看评论 + 响应（修改/回复）+ report |
 | CI 失败 → PR 作者 | ci_failure | toolchain | 3 步 | 查 CI 日志 + 分支判断（代码问题自己修 / 基础设施问题提 Issue 给姜维）+ report |
-| Issue 指派 → 开发者 | issue_assigned / infrastructure_failure | toolchain | 6 步（编码）或 4 步（运维） | 按 label 分流：type/infrastructure → 运维排查；其他 → 创建分支 + 编码 + push + CI + PR + report |
+| Issue 指派 → 开发者 | issue_assigned / infrastructure_failure | toolchain | 6 步（编码，含具体 git 命令）或 4 步（运维） | 按 label 分流：type/infrastructure → 运维排查；其他 → git checkout main/pull → 创建分支 → 编码 → push → CI → PR + report |
 | 部署失败 → 运维 | deploy_failure | toolchain | 3 步 | 查日志 + 分支判断（代码/配置问题自己修 / 基础设施问题提 Issue 给姜维）+ report |
 | @mention → 被@者 | mention | toolchain | 按 guidance | 按 mention 模板的 response_guidance + report |
 | PR 合并 → PR 作者 | review_merged | toolchain | 0 步 | 纯通知，走 _send_toolchain_task（steps 为空，verify 始终通过） |
@@ -524,10 +524,12 @@ action_type: issue_assigned 或 infrastructure_failure
 steps（按 label 分流）:
 
   # 默认路径（编码任务）:
-  1. 创建分支 fix/{issue_number}-{brief}
+  1. 在开发目录执行 git 操作：
+     a. git checkout main && git pull origin main  （确保从最新代码分叉）
+     b. git checkout -b fix/{issue_number}-{brief}  （创建功能分支）
   2. 编码 + 写 UT
-  3. push → 等 CI
-  4. CI 通过后创建 PR（Gitea API: POST /repos/{repo}/pulls）
+  3. git add -A && git commit -m "[moz] fix: {简述}" && git push origin fix/{issue_number}-{brief}
+  4. CI 通过后创建 PR（Gitea API: POST /repos/{repo}/pulls，head: fix/{issue_number}-{brief}, base: main）
   5. 等 Review
   6. 提交 action report
 
@@ -542,6 +544,8 @@ context:
 
 **label 分流说明**：issue_assigned handler 检查 label 中是否包含 `type/infrastructure`。如果是，走运维排查 steps（event_type 设为 infrastructure_failure，verify 始终 auto-pass 防递归）；否则走编码 steps。
 
+**编码路径 git 操作具体化说明**（§17 v3 补充）：原 steps 只写「创建分支」「push」等抽象指令，agent 需要自己推导具体 git 命令。现在 steps 中写清楚完整 git 操作序列（checkout main → pull → checkout -b → commit → push），降低 agent 出错概率。系统不做分支管理（不通过 Gitea API 预创建分支），分支管理完全由 agent 自己执行。ToolchainApiSection 中新增 Git 操作说明段落作为通用参考。
+
 #### 部署失败 → 运维
 
 ```
@@ -650,6 +654,26 @@ context:
 
 Issue 创建的 API 调用方式（curl 示例）统一在 ToolchainApiSection 中，与 action_report / comment 指引并列。steps 指令中不重复 API 调用方式，只描述"做什么"。
 
+#### Git 操作说明段落
+
+ToolchainApiSection 中新增通用 Git 操作说明段落，作为 agent 执行 git 命令的参考：
+
+```
+### Git 操作说明
+
+你的工作目录是开发目录。
+标准分支操作流程：
+  git checkout main && git pull origin main    # 从最新主干开始
+  git checkout -b fix/{branch_name}           # 创建功能分支
+  # ... 写代码 ...
+  git add -A && git commit -m 'message'        # 提交改动
+  git push origin {branch_name}               # 推送到远程
+
+⚠️ 不要在 main 分支上直接 commit。
+```
+
+**设计原则**：系统不做分支管理（不预创建分支、不做 checkout），分支管理完全由 agent 自己执行。ToolchainApiSection 提供通用 git 操作参考，steps 中写清楚具体操作序列。
+
 #### Red Flags 补充
 
 硬约束 Red Flags 表新增一条：

docs/design/19-skill-lifecycle-and-experience-loop.md

@@ -503,13 +503,13 @@ S1 和 S2 已完成（PR #85）。S3-S5 设计见下方 §11A。
     "message": "L1 自蒸馏 cron。请执行：\n1. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/SKILL.md\n2. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/references/discover-l1.md\n3. 按 discover-l1.md 步骤执行自蒸馏\n4. 如有信号：蒸馏为 HOW 格式，使用 skill_workshop(action=create) 提交 draft proposal\n5. 如无有价值信号：不产出，这是正常的",
     "timeoutSeconds": 600
   },
-  "delivery": { "mode": "none" }
+  "delivery": { "mode": "announce" }
 }
 ```
 
 **设计要点**:
 - `sessionTarget: "isolated"`：每次创建临时 session，不污染 main session context
-- `delivery.mode: "none"`：L1 不需要通知任何人，proposal 存在 skill_workshop 中即可
+- `delivery.mode: "announce"`：执行结果投递到 Control UI，保持可见性（早期使用 `none` 导致 cron 执行后零可见性，已修正）
 - `timeoutSeconds: 600`：10 分钟足够（扫描 JSONL + 蒸馏 + 提交 proposal）
 - message 指引 read SKILL.md + discover-l1.md：agent 按 references 指南执行，不依赖 memory
 
@@ -533,11 +533,12 @@ S1 和 S2 已完成（PR #85）。S3-S5 设计见下方 §11A。
     "message": "L2 整合审查 cron。请执行：\n1. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/references/discover-l2.md\n2. 按 discover-l2.md 步骤执行：\n   a. skill_workshop(action=list, status=pending) 获取所有 L1 draft proposals\n   b. 全量数据源扫描，识别跨 agent 共性模式\n   c. 逐个审查 proposal：approve / merge / reject\n   d. 全局提升检查（Recurrence-Count >= 3 的经验提升为规则）\n   e. 知识缺口反馈到 knowledge-gaps.md",
     "timeoutSeconds": 1200
   },
-  "delivery": { "mode": "none" }
+  "delivery": { "mode": "announce" }
 }
 ```
 
 **设计要点**:
+- `delivery.mode: "announce"`：审查决策结果投递到 Control UI，主公可见
 - `timeoutSeconds: 1200`（20 分钟）：L2 需要扫描全量数据源 + 审查多个 proposal，时间更长
 - 庞统可以访问所有 agent 的 JSONL 和 skill_workshop proposals
 
@@ -561,11 +562,12 @@ S1 和 S2 已完成（PR #85）。S3-S5 设计见下方 §11A。
     "message": "IMPROVE 每周引用追踪 cron。请执行：\n1. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/references/improve.md\n2. 按 improve.md 步骤执行：\n   a. 扫描过去 7 天所有 agent 的 session JSONL，采集 Skill 引用信号\n   b. 生成淘汰候选报告（30 天无引用的 Skill）\n   c. 庞统审阅决策：quarantine / 保留观察 / 更新后保留\n   d. 经验提升检查（被频繁引用 >= 5 次的 Skill）\n   e. 反馈知识缺口到 knowledge-gaps.md",
     "timeoutSeconds": 1800
   },
-  "delivery": { "mode": "none" }
+  "delivery": { "mode": "announce" }
 }
 ```
 
 **设计要点**:
+- `delivery.mode: "announce"`：淘汰/提升报告投递到 Control UI
 - `timeoutSeconds: 1800`（30 分钟）：全量 JSONL 扫描是最重的操作
 - 每周一次频率足够——Skill 引用变化不会很快
 - 淘汰决策通过 skill_workshop quarantine 执行，提升决策通过手动编辑 AGENTS.md

src/api/toolchain_routes.py

@@ -778,9 +778,8 @@ def _send_deploy_failure_task(repo: str, pr_number: int, pr_title: str, reason:
             action_type="deploy_failure",
             steps=[
                 "检查 deploy 日志",
-                "排查失败原因",
-                "修复并重新部署",
-                "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）",
+                "根据 deploy 日志判断失败原因类型：\n  a. 代码/配置问题（rsync 路径错、依赖缺失、启动失败）→ 修复 → 重新部署\n  b. 基础设施问题（Gitea 不可用、网络不通、磁盘满、SSH 故障）→ 在该仓库创建 Issue 指派 jiangwei-infra（见下方「需要创建 Issue 时」），label 必须包含 type/infrastructure",
+                "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）— 报告中说明判断的原因类型和执行的操作",
             ],
             context_data={
                 "repo": repo,
@@ -997,30 +996,58 @@ async def _handle_issues(payload: Dict[str, Any]) -> None:
             "brief": brief,
         })
 
-        title = f"Issue 指派: {issue_title} ({repo}#{issue_number})"
-        _send_toolchain_task(
-            to_agent=assignee,
-            title=title,
-            description=text,
-            event_type="issue_assigned",
-            action_type="issue_assigned",
-            steps=[
-                f"创建分支 fix/{issue_number}-{brief}",
-                "编码 + 写 UT",
-                "push → 等 CI",
-                f"CI 通过后创建 PR（Gitea API: POST /repos/{repo}/pulls）",
-                "等 Review",
+        # 检查是否是基础设施 Issue（按 label 分流）
+        is_infrastructure = any("infrastructure" in lbl.lower() for lbl in labels_list)
+
+        if is_infrastructure:
+            infra_steps = [
+                "根据 Issue body 中的错误来源和日志片段排查问题",
+                "修复基础设施问题（如修复 CI runner 环境、恢复网络、重启服务等）",
+                "修复后在 Issue 上 comment 说明修复方式和结果",
                 "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）",
-            ],
-            context_data={
-                "issue_number": issue_number,
-                "repo": repo,
-                "issue_title": issue_title,
-                "labels": labels,
-                "issue_body": issue_body or "(无描述)",
-                "brief": brief,
-            },
-        )
+            ]
+            title = f"基础设施 Issue: {issue_title} ({repo}#{issue_number})"
+            _send_toolchain_task(
+                to_agent=assignee,
+                title=title,
+                description=text,
+                event_type="infrastructure_failure",
+                action_type="infrastructure_failure",
+                steps=infra_steps,
+                context_data={
+                    "issue_number": issue_number,
+                    "repo": repo,
+                    "issue_title": issue_title,
+                    "labels": labels,
+                    "issue_body": issue_body or "(无描述)",
+                    "brief": brief,
+                },
+            )
+        else:
+            title = f"Issue 指派: {issue_title} ({repo}#{issue_number})"
+            _send_toolchain_task(
+                to_agent=assignee,
+                title=title,
+                description=text,
+                event_type="issue_assigned",
+                action_type="issue_assigned",
+                steps=[
+                    f"在开发目录执行 git 操作：\n  a. git checkout main && git pull origin main\n  b. git checkout -b fix/{issue_number}-{brief}",
+                    "编码 + 写 UT",
+                    f"git add -A && git commit -m \"[moz] fix: {issue_title[:30]}\" && git push origin fix/{issue_number}-{brief}",
+                    f"CI 通过后创建 PR（Gitea API: POST /repos/{repo}/pulls，head: fix/{issue_number}-{brief}, base: main）",
+                    "等 Review",
+                    "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）",
+                ],
+                context_data={
+                    "issue_number": issue_number,
+                    "repo": repo,
+                    "issue_title": issue_title,
+                    "labels": labels,
+                    "issue_body": issue_body or "(无描述)",
+                    "brief": brief,
+                },
+            )
 
     elif action == "opened":
         if "部署失败" in issue_title:
@@ -1043,9 +1070,8 @@ async def _handle_issues(payload: Dict[str, Any]) -> None:
                     action_type="deploy_failure",
                     steps=[
                         "检查 deploy 日志",
-                        "排查失败原因",
-                        "修复并重新部署",
-                        "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）",
+                        "根据 deploy 日志判断失败原因类型：\n  a. 代码/配置问题（rsync 路径错、依赖缺失、启动失败）→ 修复 → 重新部署\n  b. 基础设施问题（Gitea 不可用、网络不通、磁盘满、SSH 故障）→ 在该仓库创建 Issue 指派 jiangwei-infra（见下方「需要创建 Issue 时」），label 必须包含 type/infrastructure",
+                        "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）— 报告中说明判断的原因类型和执行的操作",
                     ],
                     context_data={
                         "repo": repo,
@@ -1126,9 +1152,8 @@ async def _handle_issue_comment(payload: Dict[str, Any]) -> None:
             action_type="ci_failure",
             steps=[
                 "查看完整 CI 日志（PR 页面或 Gitea Actions 页面）",
-                "修复失败的测试",
-                "push → CI 自动重跑",
-                "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）",
+                "根据 CI 日志判断失败原因类型：\n  a. 代码问题（lint/test 失败）→ 修复失败的测试 → push 到原分支 → CI 自动重跑\n  b. 基础设施问题（runner 环境/Python/venv/Gitea/网络故障）→ 在该仓库创建 Issue 指派 jiangwei-infra（见下方「需要创建 Issue 时」），label 必须包含 type/infrastructure",
+                "提交 action report（POST http://localhost:8083/api/projects/_toolchain/tasks/<task_id>/comments，comment_type=action_report）— 报告中说明判断的原因类型和执行的操作",
             ],
             context_data={
                 "pr_number": issue_number,

src/daemon/toolchain_handler.py

@@ -166,6 +166,33 @@ class ToolchainApiSection:
             "",
             "⚠️ 不要使用 Mail API(飞鸽传书)。所有协作通过 Gitea 留痕。",
             "",
+            "### 需要创建 Issue 时",
+            "",
+            "如果步骤中要求创建 Issue 指派他人（如 jiangwei-infra）：",
+            "```bash",
+            f'curl -s -X POST "{_GITEA_BASE}/repos/{{repo}}/issues" \\',
+            '  -H "Authorization: token <your-token>" \\',
+            '  -H "Content-Type: application/json" \\',
+            '  -d \'{"title": "[moz] infra: 简述问题", "body": "## 问题描述\\n\\n<简要描述问题现象>\\n\\n## 错误来源\\n\\n- 仓库: <repo>\\n- PR/Commit: <链接>\\n- CI/Deploy run: <Gitea Actions 页面链接>\\n\\n## 日志关键片段\\n\\n```<错误日志摘要>```\\n\\n## 判断依据\\n\\n<为什么判断为基础设施问题>", "assignees": ["jiangwei-infra"], "labels": [<label_id>]}\'',
+            "```",
+            "",
+            "⚠️ Issue body 必须包含错误来源链接（PR/Commit + CI run），让排查者能直接看到全貌。",
+            "⚠️ label 数字 ID 先 GET /repos/{repo}/labels 查询 type/infrastructure 对应的 ID。",
+            "",
+            "### Git 操作说明",
+            "",
+            "你的工作目录是开发目录（如 ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/）。",
+            "标准分支操作流程：",
+            "```bash",
+            "git checkout main && git pull origin main    # 从最新主干开始",
+            "git checkout -b fix/{branch_name}           # 创建功能分支",
+            "# ... 写代码 ...",
+            "git add -A && git commit -m 'message'        # 提交改动",
+            "git push origin {branch_name}               # 推送到远程",
+            "```",
+            "",
+            "⚠️ 不要在 main 分支上直接 commit。",
+            "",
         ]
         return "\n".join(lines)
 
@@ -218,6 +245,7 @@ class ToolchainConstraintsSection:
             '| “我已经知道了” | ❌ 知道不等于执行。执行步骤 + 提交 action report 才算完成 |',
             '| “步骤太多了，选几个做就行” | ❌ 错！必须逐条执行，不可跳过 |',
             '| “这个步骤不适用于当前情况” | ❌ 如果确实不适用，在 action report 中说明原因，但其他步骤必须执行 |',
+            '| “CI/部署失败不是我代码的问题，我什么也不用做” | ❌ 错！即使是基础设施问题，你也必须创建 Issue 指派 jiangwei-infra（body 含错误来源链接 + 日志 + 判断依据），并在 action report 中说明。不能只报告“不是我的问题”就完事 |',
             "",
         ]
         return "\n".join(lines)

tests/unit/test_toolchain_handler_v2.py

@@ -523,3 +523,98 @@ class TestFullPromptBuild:
         # Must have constraints with Red Flags
         assert "Red Flags" in prompt
         assert "强制要求" in prompt
+
+
+# ---------------------------------------------------------------------------
+# §17 v2: CI/deploy failure branching + issue label routing + Issue API guidance
+# ---------------------------------------------------------------------------
+
+class TestCiFailureBranching:
+    """ci_failure steps should include a/b branching guidance."""
+
+    def test_ci_failure_steps_contain_branching(self):
+        source_file = PROJECT_ROOT / "src" / "api" / "toolchain_routes.py"
+        source = source_file.read_text()
+        assert '基础设施问题' in source
+        assert 'type/infrastructure' in source
+        assert 'jiangwei-infra' in source
+
+
+class TestDeployFailureBranching:
+    """deploy_failure steps should include a/b branching guidance."""
+
+    def test_deploy_failure_steps_contain_branching(self):
+        source_file = PROJECT_ROOT / "src" / "api" / "toolchain_routes.py"
+        source = source_file.read_text()
+        count = source.count('基础设施问题（Gitea 不可用')
+        assert count >= 2, f'Expected >=2 deploy_failure branching, found {count}'
+
+
+class TestIssueAssignedLabelRouting:
+    """issue_assigned handler should route by type/infrastructure label."""
+
+    def test_label_check_in_source(self):
+        source_file = PROJECT_ROOT / "src" / "api" / "toolchain_routes.py"
+        source = source_file.read_text()
+        assert 'is_infrastructure' in source
+        assert 'infrastructure_failure' in source
+        assert '基础设施 Issue' in source
+
+    def test_normal_issue_keeps_coding_steps(self):
+        source_file = PROJECT_ROOT / "src" / "api" / "toolchain_routes.py"
+        source = source_file.read_text()
+        assert 'git checkout -b fix/' in source
+        assert 'issue_assigned' in source
+
+
+class TestToolchainApiIssueGuidance:
+    """ToolchainApiSection should include Issue creation guidance."""
+
+    def test_has_issue_creation_section(self):
+        source_file = PROJECT_ROOT / "src" / "daemon" / "toolchain_handler.py"
+        source = source_file.read_text()
+        assert "需要创建 Issue 时" in source
+        assert "/issues" in source
+        assert "jiangwei-infra" in source
+        assert "type/infrastructure" in source
+
+    def test_issue_body_template_mentions_required_fields(self):
+        source_file = PROJECT_ROOT / "src" / "daemon" / "toolchain_handler.py"
+        source = source_file.read_text()
+        assert "错误来源" in source
+        assert "判断依据" in source
+
+
+class TestRedFlagsInfrastructure:
+    """Red Flags should include the 'not my code' entry."""
+
+    def test_has_infrastructure_red_flag(self):
+        source_file = PROJECT_ROOT / "src" / "daemon" / "toolchain_handler.py"
+        source = source_file.read_text()
+        assert "不是我代码的问题" in source
+        assert "基础设施问题" in source
+
+
+class TestGitOperationGuidance:
+    """ToolchainApiSection should include Git operation guidance."""
+
+    def test_has_git_operation_section(self):
+        source_file = PROJECT_ROOT / "src" / "daemon" / "toolchain_handler.py"
+        source = source_file.read_text()
+        assert "Git 操作说明" in source
+        assert "git checkout main" in source
+        assert "git pull origin main" in source
+        assert "git checkout -b" in source
+
+    def test_has_no_main_commit_warning(self):
+        source_file = PROJECT_ROOT / "src" / "daemon" / "toolchain_handler.py"
+        source = source_file.read_text()
+        assert "不要在 main 分支上直接 commit" in source
+
+    def test_issue_assigned_steps_have_git_commands(self):
+        source_file = PROJECT_ROOT / "src" / "api" / "toolchain_routes.py"
+        source = source_file.read_text()
+        assert 'git checkout main && git pull origin main' in source
+        assert 'git checkout -b fix/' in source
+        assert 'git add -A && git commit' in source
+        assert 'git push origin fix/' in source