{"id":"44b4ddd8-4417-484e-a5bc-5e5426a20729","entityType":"agent","slug":"clawhub-hehe973781230-thesis-workflow-v2","name":"Mba Thesis Workflow","canonicalUrl":"https://www.xpersona.co/agent/clawhub-hehe973781230-thesis-workflow-v2","canonicalPath":"/agent/clawhub-hehe973781230-thesis-workflow-v2","generatedAt":"2026-10-12T12:00:33.384Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:26:03.620Z","emptyReason":null},"description":"Write, review, and export MBA / academic theses end-to-end as Word / DOCX. Covers outline planning → node-by-node writing → chapter review → academic deep re...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 997 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s177cnrnh50t3jxyh7y9exta3h87sc86:thesis-workflow-v2","sourceUrl":"https://clawhub.ai/hehe973781230/thesis-workflow-v2","homepage":"https://clawhub.ai/hehe973781230/skills/thesis-workflow-v2","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/hehe973781230/thesis-workflow-v2","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/hehe973781230/skills/thesis-workflow-v2","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Mba Thesis Workflow technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:26:03.620Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:26:03.620Z","emptyReason":null},"stars":null,"forks":null,"downloads":997,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"2.1.2-beta.1","tractionLabel":"997 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:26:03.604Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T20:26:03.620Z","lastCrawledAt":"2026-10-11T20:26:03.604Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T20:26:03.604Z","lastVerifiedAt":null,"highlights":[{"version":"2.1.2-beta.1","createdAt":"2026-07-02T06:47:15.143Z","changelog":"v2.1.2-beta.1 (2026-07-02) - P0 修复: 1. Tavily MCP 平台集成 - 新增 _detect_openclaw_platform() 检测 OpenClaw runtime - 新增 _check_openclaw_tavily_bridge() 通过 openclaw skills list 验证 tavily-search 注册 - OpenClaw 走内置桥接，Hermes 降级 mcporter - Tavily install_category 改 none（truly optional） 2. HIL #1 公司映射强制采集 - confirm_phase1() 新增 user_input 参数解析 [1] vivo / [2] / [3] - 强制校验 actual_name=null 且 skip_mapping=false 则报错 - state['company_info'] 字段完整化（actual_name/skip_mapping/confirmed/confirmed_at） - HIL 总数仍 9（公司映射合并入 #1） 3. e2e 验证发现 5 个 bug 修复 - OpenClaw skill 名称匹配（tavily-search 不是 tavily-mcp） - hil_pause 加 allow_extra 参数支持 [key] extra 格式 - orchestrate() 路由 phase1_confirm 时透传 user_input - phase1_3_submit 保留 HIL #1 写入的 actual_name（修复覆盖 bug） - dict 引用问题修复 4. 隐私清理：7 处历史敏感字（龙哥/徐龙等）替换为通用描述 OpenClaw 用户安装命令：openclaw skills install thesis-workflow-v2 详见 CHANGELOG-v2.md","fileCount":73,"zipByteSize":290982},{"version":"2.1.1-beta.13","createdAt":"2026-07-02T04:02:07.981Z","changelog":"Release v2.1.1-beta.13 | - SKILL.md version: 2.1.1 | - git tag: v2.1.1-beta.13 | - ClawHub: 2.1.1-beta.13","fileCount":73,"zipByteSize":286663},{"version":"2.1.1-beta.12","createdAt":"2026-07-02T02:36:34.945Z","changelog":"feat: HIL #4 人话版（方案C）+ 消息简化 + 评审文字落盘; refactor: SKILL.md 5-principle 重构 + 拆分 thesis-docx-export 子 skill","fileCount":73,"zipByteSize":286788},{"version":"2.1.1-beta.11","createdAt":"2026-07-01T04:15:37.468Z","changelog":"v2.1.1-beta.11: P0 hotfix — paper_subject 动态化 + 主题锁定总是注入 [P0 hotfix] v2.1.1-beta.10 prompt 里硬编码了'A公司互联网分发业务竞争战略研究...'+ '终端厂商互联网业务 + AI 大模型背景'。所有 v2 用户被强制引导写 v8.0 特定主题， 朱骏的 C 公司 IP、陈汉的 R 留学论文都会跑题。 [修复 1] _llm_fill_empty_hints paper_subject 动态化 - 优先从 outline_tree.metadata.paper_title 读 - 兜底从 paper_name 去后缀 - 函数新增 paper_name 参数 [修复 2] context_builder 主题锁定总是注入（修复 v8.0 ch1 跑题事故） - 触发条件: if state（不再 if not content_hint） - prompt 高位插入'## ⚠️ 主题锁定（必读）'section - v2.0.7 B-2 行为保留（hint 空时仍叠加 outline_skeleton） [附带优化] - '你是一名 MBA 论文写作助手' → '你是一名学术论文写作助手'（兼容博士/期刊论文） - paper_subject_lock 字段独立提取（不再污染 content_hint） [实测] - v8.0: paper_subject='A公司互联网分发业务竞争战略研究'（从 paper_name 兜底） - v9.0 模拟: paper_subject='C公司IP业务竞争战略研究'（从 metadata.paper_title） - 都不含'终端厂商'/'AI 大模型'硬编码 [影响] - 全 v2 用户受益（特别是非 v8.0 论文用户） - 修复 v8.0 ch1 LLM 跑题为通用 MBA 论文的问题 - 主题锁定更精准，避免 hint 质量差时 LLM 跑题","fileCount":69,"zipByteSize":276369},{"version":"2.1.1-beta.10","createdAt":"2026-07-01T00:54:53.864Z","changelog":"v2.1.1-beta.10: outline_parser LLM 一次性兑底补全空 hint 节点 [P0 修复] hint 只从开题报告匹配段落提取，70%+ 节点没 hint，Phase 2 写作时 LLM 靠大纲骨架勉强写但容易跑题。 [新增] _llm_fill_empty_hints() (~80 行) - 收集所有空 hint 节点 - 调一次 LLM，输入节点列表 + 论文主题 - 输出 JSON 数组 hint 字典 - LLM 失败时安全降级，不阻断主流程 [实测] v8.0: 26% 覆盖 → 100% 覆盖（1 次 LLM 调用补 39 个空 hint） [安全] 全部有 hint 时不调 LLM（零额外调用） [影响范围] - 任何使用 v2 框架的论文都受益，不限于南大 MBA 模板 - 一次 LLM 调用可补全 30-50 个空 hint（token 友好） - 间接提升 Phase 2 论文写作质量（上下文约束更精准）","fileCount":69,"zipByteSize":274744},{"version":"2.1.1-beta.9","createdAt":"2026-07-01T00:43:32.805Z","changelog":"v2.1.1-beta.9: outline_parser 新增 C 路径支持 Word 自定义样式 + 修两个 Phase 1 流程 bug [P0 修复] outline_parser 走 MinerU 路径时，docx 中的 Word 自定义样式（如南大 MBA 模板的 MBA-章标题/一级节标题）被降级为普通文本，结构信息丢失，导致 Phase 1.1 大纲解析严重错位。修复后 v8.0 实测从 13 错位节点 → 55 真实节点 + 7 虚拟 summary = 62 节点。 [新增] C 路径: extract_outline_from_docx_with_custom_styles (~60 行) - 基于 python-docx 直接读 Word 段落 + 样式，不依赖 MinerU - 避免 MinerU 的隐私风险（不上传 docx 到云端）+ 速度更快 - 主入口路径顺序: C → B → A [修复] run_workflow.py 两个 P0 bug: - 缩进 r 引用到 phase 1.1 init 块内（state 存在跳过 init 时不会触发 UnboundLocalError） - Phase 1.3 submit 后重新 load state（否则 state 变量是旧值导致 phase1_3_result=None 报 AttributeError） [影响范围] - 南大 MBA 论文模板（MBA-章标题 + MBA-一级节标题）: 从完全无法解析 → 62 节点全对 - 其他使用 Word 自定义样式（非 Heading 1/2/3）的论文模板均受益 - 现有用户（v1 模板 / Heading 1/2/3 用户）行为不变（C 路径找不到锚点会降级到 B 路径）","fileCount":69,"zipByteSize":272989},{"version":"2.1.1-beta.8","createdAt":"2026-07-01T00:09:39.584Z","changelog":"fix: 修复 orchestrator_v2.py 缺少 _set_outline_nodes import 导致的 NameError","fileCount":69,"zipByteSize":270962},{"version":"2.1.1-beta.7","createdAt":"2026-06-30T13:54:59.471Z","changelog":"feat(phase_manager): 全部 6 个问题修复 + Phase 1/2/3 完整集成 - P0-1: Phase 1.3 submit vs confirm 文件分离 - P0-2: Phase 5 传入 docx_generated 参数 - P1-1: Phase 3.5 review_data 格式统一 + Phase 3 修正 - P1-2: write_single_node 追加写入 PhaseManager - P2-2: Phase 5 guardrails_passed 从 review_data 读取 - Phase 1.1/1.3/2/3 完整集成 PhaseManager","fileCount":69,"zipByteSize":270980}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177cnrnh50t3jxyh7y9exta3h87sc86:thesis-workflow-v2","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s177cnrnh50t3jxyh7y9exta3h87sc86:thesis-workflow-v2` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/hehe973781230/thesis-workflow-v2 before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T12:00:33.379Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-hehe973781230-thesis-workflow-v2/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:26:03.620Z","emptyReason":null},"readme":"Skill: Mba Thesis Workflow\n\nOwner: hehe973781230\n\nSummary: Write, review, and export MBA / academic theses end-to-end as Word / DOCX. Covers outline planning → node-by-node writing → chapter review → academic deep re...\n\nTags: beta:2.1.2-beta.1, latest:2.1.2-beta.1\n\nVersion history:\n\nv2.1.2-beta.1 | 2026-07-02T06:47:15.143Z | user\n\nv2.1.2-beta.1 (2026-07-02) - P0 修复:\n\n1. Tavily MCP 平台集成\n - 新增 _detect_openclaw_platform() 检测 OpenClaw runtime\n - 新增 _check_openclaw_tavily_bridge() 通过 openclaw skills list 验证 tavily-search 注册\n - OpenClaw 走内置桥接，Hermes 降级 mcporter\n - Tavily install_category 改 none（truly optional）\n\n2. HIL #1 公司映射强制采集\n - confirm_phase1() 新增 user_input 参数解析 [1] vivo / [2] / [3]\n - 强制校验 actual_name=null 且 skip_mapping=false 则报错\n - state['company_info'] 字段完整化（actual_name/skip_mapping/confirmed/confirmed_at）\n - HIL 总数仍 9（公司映射合并入 #1）\n\n3. e2e 验证发现 5 个 bug 修复\n - OpenClaw skill 名称匹配（tavily-search 不是 tavily-mcp）\n - hil_pause 加 allow_extra 参数支持 [key] extra 格式\n - orchestrate() 路由 phase1_confirm 时透传 user_input\n - phase1_3_submit 保留 HIL #1 写入的 actual_name（修复覆盖 bug）\n - dict 引用问题修复\n\n4. 隐私清理：7 处历史敏感字（龙哥/徐龙等）替换为通用描述\n\nOpenClaw 用户安装命令：openclaw skills install thesis-workflow-v2\n详见 CHANGELOG-v2.md\n\nv2.1.1-beta.13 | 2026-07-02T04:02:07.981Z | user\n\nRelease v2.1.1-beta.13 | - SKILL.md version: 2.1.1 | - git tag: v2.1.1-beta.13 | - ClawHub: 2.1.1-beta.13\n\nv2.1.1-beta.12 | 2026-07-02T02:36:34.945Z | user\n\nfeat: HIL #4 人话版（方案C）+ 消息简化 + 评审文字落盘; refactor: SKILL.md 5-principle 重构 + 拆分 thesis-docx-export 子 skill\n\nv2.1.1-beta.11 | 2026-07-01T04:15:37.468Z | user\n\nv2.1.1-beta.11: P0 hotfix — paper_subject 动态化 + 主题锁定总是注入\n\n[P0 hotfix] v2.1.1-beta.10 prompt 里硬编码了'A公司互联网分发业务竞争战略研究...'+\n '终端厂商互联网业务 + AI 大模型背景'。所有 v2 用户被强制引导写 v8.0 特定主题，\n 朱骏的 C 公司 IP、陈汉的 R 留学论文都会跑题。\n\n[修复 1] _llm_fill_empty_hints paper_subject 动态化\n - 优先从 outline_tree.metadata.paper_title 读\n - 兜底从 paper_name 去后缀\n - 函数新增 paper_name 参数\n\n[修复 2] context_builder 主题锁定总是注入（修复 v8.0 ch1 跑题事故）\n - 触发条件: if state（不再 if not content_hint）\n - prompt 高位插入'## ⚠️ 主题锁定（必读）'section\n - v2.0.7 B-2 行为保留（hint 空时仍叠加 outline_skeleton）\n\n[附带优化]\n - '你是一名 MBA 论文写作助手' → '你是一名学术论文写作助手'（兼容博士/期刊论文）\n - paper_subject_lock 字段独立提取（不再污染 content_hint）\n\n[实测]\n - v8.0: paper_subject='A公司互联网分发业务竞争战略研究'（从 paper_name 兜底）\n - v9.0 模拟: paper_subject='C公司IP业务竞争战略研究'（从 metadata.paper_title）\n - 都不含'终端厂商'/'AI 大模型'硬编码\n\n[影响]\n- 全 v2 用户受益（特别是非 v8.0 论文用户）\n- 修复 v8.0 ch1 LLM 跑题为通用 MBA 论文的问题\n- 主题锁定更精准，避免 hint 质量差时 LLM 跑题\n\nv2.1.1-beta.10 | 2026-07-01T00:54:53.864Z | user\n\nv2.1.1-beta.10: outline_parser LLM 一次性兑底补全空 hint 节点\n\n[P0 修复] hint 只从开题报告匹配段落提取，70%+ 节点没 hint，Phase 2 写作时 LLM 靠大纲骨架勉强写但容易跑题。\n\n[新增] _llm_fill_empty_hints() (~80 行)\n - 收集所有空 hint 节点\n - 调一次 LLM，输入节点列表 + 论文主题\n - 输出 JSON 数组 hint 字典\n - LLM 失败时安全降级，不阻断主流程\n\n[实测] v8.0: 26% 覆盖 → 100% 覆盖（1 次 LLM 调用补 39 个空 hint）\n[安全] 全部有 hint 时不调 LLM（零额外调用）\n\n[影响范围]\n- 任何使用 v2 框架的论文都受益，不限于南大 MBA 模板\n- 一次 LLM 调用可补全 30-50 个空 hint（token 友好）\n- 间接提升 Phase 2 论文写作质量（上下文约束更精准）\n\nv2.1.1-beta.9 | 2026-07-01T00:43:32.805Z | user\n\nv2.1.1-beta.9: outline_parser 新增 C 路径支持 Word 自定义样式 + 修两个 Phase 1 流程 bug\n\n[P0 修复] outline_parser 走 MinerU 路径时，docx 中的 Word 自定义样式（如南大 MBA 模板的 MBA-章标题/一级节标题）被降级为普通文本，结构信息丢失，导致 Phase 1.1 大纲解析严重错位。修复后 v8.0 实测从 13 错位节点 → 55 真实节点 + 7 虚拟 summary = 62 节点。\n\n[新增] C 路径: extract_outline_from_docx_with_custom_styles (~60 行)\n - 基于 python-docx 直接读 Word 段落 + 样式，不依赖 MinerU\n - 避免 MinerU 的隐私风险（不上传 docx 到云端）+ 速度更快\n - 主入口路径顺序: C → B → A\n\n[修复] run_workflow.py 两个 P0 bug:\n - 缩进 r 引用到 phase 1.1 init 块内（state 存在跳过 init 时不会触发 UnboundLocalError）\n - Phase 1.3 submit 后重新 load state（否则 state 变量是旧值导致 phase1_3_result=None 报 AttributeError）\n\n[影响范围]\n- 南大 MBA 论文模板（MBA-章标题 + MBA-一级节标题）: 从完全无法解析 → 62 节点全对\n- 其他使用 Word 自定义样式（非 Heading 1/2/3）的论文模板均受益\n- 现有用户（v1 模板 / Heading 1/2/3 用户）行为不变（C 路径找不到锚点会降级到 B 路径）\n\nv2.1.1-beta.8 | 2026-07-01T00:09:39.584Z | user\n\nfix: 修复 orchestrator_v2.py 缺少 _set_outline_nodes import 导致的 NameError\n\nv2.1.1-beta.7 | 2026-06-30T13:54:59.471Z | user\n\nfeat(phase_manager): 全部 6 个问题修复 + Phase 1/2/3 完整集成\n\n- P0-1: Phase 1.3 submit vs confirm 文件分离\n- P0-2: Phase 5 传入 docx_generated 参数\n- P1-1: Phase 3.5 review_data 格式统一 + Phase 3 修正\n- P1-2: write_single_node 追加写入 PhaseManager\n- P2-2: Phase 5 guardrails_passed 从 review_data 读取\n- Phase 1.1/1.3/2/3 完整集成 PhaseManager\n\nv2.1.1-beta.6 | 2026-06-30T07:17:23.809Z | user\n\nfix(P0): Phase 1.3 code_name 提取 + research_keywords LLM 生成 + 消除重复 LLM 调用\n\nv2.1.1-beta.5 | 2026-06-30T01:25:30.200Z | user\n\nrefactor(llm_func): 彻底移除外部传参，改为内部 get_session_llm_func() 固化获取\n- 修复 P1: 移除 orchestrate_phase1_1 残留 llm_func 参数\n- 修复 P3: 修复测试文件 llm_func 传参不匹配 \n- refactor(B): 删除 run_workflow.py 旧版 RuntimeLLM，统一从 research_tools 获取\n\nv2.1.0-beta.4 | 2026-06-29T16:04:42.288Z | user\n\nfix: RuntimeLLM._get_session_info 使用 --agent 精确限定 session，避免 background 场景静默失败\n\n- RuntimeLLM.__init__ 保存传入的 agent_id\n- _get_session_info：优先用 --agent ，无 agent_id 时退化到 --all-agents\n- 防御性校验：解析出的 agent_id 与期望不符则抛异常\n- get_runtime_llm() 新增 agent_id 参数，全局单例透传\n- 3处调用方（Phase1/Phase2）透传 args.agent_id\n- 解决 background/nohup/cron 场景下 sessions[0] 误取其他 agent session 的静默失败问题\n\nv2.1.0-beta.3 | 2026-06-29T00:48:53.119Z | user\n\nfix: release.py --check 正确识别 beta 包预期状态；latest 标签指向 beta\n\nv2.1.0-beta.2 | 2026-06-29T00:41:15.305Z | user\n\nfix: release.py --check 正确识别 beta 包预期状态\n\nv2.1.0 | 2026-06-29T00:35:00.711Z | user\n\nfix: release.py --check 正确识别 beta 包预期状态\n\nv2.1.0-beta.1 | 2026-06-28T14:30:28.439Z | user\n\nRelease v2.1.0-beta.1 | - SKILL.md version: 2.1.0 | - git tag: v2.1.0-beta.1 | - ClawHub: 2.1.0-beta.1\n\nv2.0.14 | 2026-06-28T14:00:16.169Z | user\n\nfix(v2): Phase 1 双HIL强制分步确认，修复归因节点被跳过问题。版本号历史已清理，v2.0.13为latest。\n\nv2.0.16 | 2026-06-28T13:48:12.261Z | user\n\nfix(v2): Phase 1 双HIL强制分步确认，修复归因节点被跳过问题。phase 初始值 phase1_1，confirm_phase1() 推进到 phase1_2，新增 elif phase == 'phase1_2' dispatch 分支，HIL#1(大纲) + HIL#2(归因) 独立两次确认。\n\nv2.0.21 | 2026-06-28T08:49:26.323Z | user\n\nfix: F1 重写死循环 / F2 failed节点排除 / F3 rewrite状态重置 / F4 异常warn / F5 冗余代码删除\n\nv2.0.20-beta | 2026-06-28T03:48:50.343Z | user\n\nP0+P1修复：outline嵌套结构兼容层（_get_outline_nodes/_set_outline_nodes）+ 19处硬编码替换 + _set_outline_nodes空dict bug修复 + outline_save防御性压平\n\nv2.0.19-beta | 2026-06-27T16:03:26.246Z | user\n\nv2.0.19-beta N1-N7 修复：N1 force=True绕过幂等；N2/N3 accept路径同步outline；N4 json.loads替代ast.literal_eval；N5 warnings.warn；N6 consecutive_clean逻辑修正；N7 GK超时明确处理\n\nv2.0.18-beta | 2026-06-27T15:17:20.511Z | user\n\nv2.0.18-beta F1-F9 审查修复：F1 Phase5 Guardrails顺序修复；F2 评审前 reviewing；F3 auto模式审核Loop；F6 连续2轮收敛；F7 prompt重复行；F8 异常吞没修复；F9 input非交互式阻塞\n\nv2.0.17-beta | 2026-06-27T08:52:28.860Z | user\n\nv2.0.17-beta: gatekeeper _paper_dir 路径统一为 WORKSPACE/paper_name（移除 papers/ 子目录，与 state_manager/_get_paper_dir 保持一致）\n\nv2.0.16-beta | 2026-06-27T08:39:19.602Z | user\n\nv2.0.16-beta: Phase 3 confirm 输出路径统一为 _get_paper_dir，修复 papers/ 硬编码相对路径（与 Phase 5 路径保持一致）\n\nv2.0.15-beta | 2026-06-27T08:19:20.907Z | user\n\nv2.0.15-beta 个人信息清理：移除所有'龙哥'引用，替换为中性表述后再发布ClawHub\n\nv2.0.14-beta | 2026-06-27T08:07:29.051Z | user\n\nv2.0.14-beta M1-M9 审查修复：\n- M1: check_info_scarcity 移除 user_hints 强制检查\n- M2: _get_paper_dir 统一路径（Phase3/5/Guardrails）\n- M3: Phase4 字数校验+备份+warnings\n- M5: Phase3.5 跨章评审上下文\n- M6: 原子写入+读取重试\n- M7: _assemble_full_content 公共函数\n- M8: except Exception → warnings.warn\n- M9: SKILL.md 引用完整性描述修正\n- md2docx_strict: emoji替换+_ensure_utf8_stdout\n\nv2.0.13 | 2026-06-27T04:52:15.483Z | user\n\nfix: 修复 v2 代码审查问题（P0-1~P0-3, P1-1~P1-4）；eval→ast.literal_eval；添加 Phase 3.5/4/5 CLI 入口；版本号同步至 v2.0.13\n\nv2.0.12-beta | 2026-06-25T16:23:41.405Z | user\n\nfix: 清理SKILL.md/README.md/README_EN.md全部v1残留(双版本/H-generator/Hermes/版本H/版本O)\n\nv2.0.11-beta | 2026-06-25T16:12:21.650Z | user\n\nfix: 清理v1残留(CHANGELOG-v1/OUTLINE_ANCHORED_TODO) + clawhubignore排除 + 路径修正\n\nv2.0.10-beta | 2026-06-25T14:24:38.252Z | user\n\nfix(v2.0.10-beta): P0-P4修复 — 惰性检测/多工具集成/Phase 3.5/4/5/requirements/install.sh\n\nv2.0.9-beta | 2026-06-25T13:02:41.944Z | user\n\nfeat(v2.0.9-beta): Layer 2 向量标题匹配(BGE-small-zh替代LLM/毫秒级/确定性/离线兜底) + outline_parser改造 + CHANGELOG/SKILL.md更新\n\nv2.0.8-beta | 2026-06-25T04:34:57.281Z | user\n\nfeat(v2.0.8-beta): multi-search并行引擎(4工具并行/去重排序/降级) + RuntimeLLM零硬编码 + SKILL.md/CHANGELOG/README 更新\n\nv2.0.6 | 2026-06-23T23:32:44.829Z | user\n\nv2.0.6 重大修复：\n\n🚨 Enforcement + 真实入口：\n- P0-1: skip_phase1_3 双层拦截（入口 + 函数层 audit log）\n- P0-2: 新增 scripts/run_workflow.py CLI 真实入口\n- P0-3: 9 个 HIL 节点 hard pause + v2.0.4 推荐调用模式\n- P1-1: B-2 幂等（outline_update_status 拒绝覆盖 completed）\n- P1-2: 独立 Reviewer（write_single_node 加 reviewer_func 参数）\n- P2: SKILL.md / README.md / CHANGELOG.md 完整更新\n\n测试：172 passed（+14 个新增 v2.0.6 回归测试）\n\n详见 CHANGELOG-v2.md\n\nArchive index:\n\nArchive v2.1.2-beta.1: 73 files, 290982 bytes\n\nFiles: CHANGELOG-v2.md (30406b), CHANGELOG.md (9135b), install.sh (3297b), LICENSE (1075b), README_EN.md (4783b), README.md (6001b), references/chapter-summary-design.md (5822b), references/content-hint-fallback.md (6287b), references/loop-design.md (11343b), requirements-optional.txt (581b), requirements.txt (338b), scripts/__init__.py (0b), scripts/context_builder.py (22528b), scripts/gatekeeper_integration.py (5805b), scripts/loop_self_check.py (23844b), scripts/md2docx_strict.py (30736b), scripts/multi_search.py (11124b), scripts/node_writer.py (10771b), scripts/orchestrator_v2.py (103888b), scripts/orchestrator.py (10344b), scripts/outline_parser.py (66359b), scripts/phase_manager/__init__.py (19556b), scripts/phase_manager/DESIGN.md (22966b), scripts/phase_manager/file_manager.py (21761b), scripts/phase_manager/gate_keeper.py (17002b), scripts/phase_manager/hil_renderer.py (13972b), scripts/phase_manager/schemas.py (8282b), scripts/phase_manager/summary_generator.py (13246b), scripts/phase_manager/tests/__init__.py (54b), scripts/phase_manager/tests/test_phase_manager.py (19831b), scripts/release.py (9907b), scripts/research_tools.py (12413b), scripts/reviewer.py (9044b), scripts/run_workflow.py (45751b), scripts/simple_embedder.py (7451b), scripts/state_manager_v2.py (23637b), scripts/state_manager.py (8528b), scripts/tests/__init__.py (396b), scripts/tests/conftest.py (676b), scripts/tests/REAL_SAMPLES_README.md (2332b), scripts/tests/test_b1_bypass_scarcity.py (7476b), scripts/tests/test_b2_state_sync.py (10904b), scripts/tests/test_bridge_p3_fallback.py (9954b), scripts/tests/test_chapter_summary.py (9887b), scripts/tests/test_context_builder.py (12330b), scripts/tests/test_full_workflow.py (36824b), scripts/tests/test_info_scarcity.py (15074b), scripts/tests/test_integration_chapter_summary.py (8091b), scripts/tests/test_loop_self_check.py (4603b), scripts/tests/test_md2docx_strict.py (2596b), scripts/tests/test_node_writer.py (7768b), scripts/tests/test_orchestrator.py (7008b), scripts/tests/test_outline_engine_fallback.py (20573b), scripts/tests/test_outline_parser.py (6525b), scripts/tests/test_phase1_3.py (19548b), scripts/tests/test_reviewer.py (7889b), scripts/tests/test_run_workflow.py (11046b), scripts/tests/test_state_manager.py (3732b), scripts/tests/test_synthesize_summary.py (11204b), skill-card.md (2792b), SKILL.md (24348b), skills/gatekeeper/gatekeeper.py (18343b), skills/gatekeeper/SKILL.md (5722b), tests/__init__.py (0b), tests/test_context_builder.py (4725b), tests/test_mcp_aware_llm.py (4295b), tests/test_pre_phase2_review.py (8669b), tests/test_research_tools.py (5355b), thesis-docx-export/CHANGELOG.md (806b), thesis-docx-export/README.md (1459b), thesis-docx-export/references/checklist.md (8379b), thesis-docx-export/SKILL.md (6344b), _meta.json (144b)\n\nFile v2.1.2-beta.1:SKILL.md\n\n---\nname: thesis-workflow-v2\ndescription: \"Write, review, and export MBA / academic theses end-to-end as Word / DOCX. Covers outline planning → node-by-node writing → chapter review → academic deep review → Word export with GB/T 7714 references and 南大-style formatting. Triggers: 论文 / thesis / dissertation / 答辩 / 开题 / MBA / 章节 / 文献综述 / 参考文献 / chapter outline. ⚠️ v2 is beta (outline-anchored + 9 HIL + BGE multi-search); install independently and do not overwrite v1. Prefer v1 (`thesis-workflow`) for production unless user explicitly asks for v2 / 新框架 / outline-anchored / 9 HIL.\"\nplatforms: [linux, macos, windows]\nmetadata:\n # ↓ OpenClaw 私有配置（仅 ClawHub 加载器识别；不影响标准 platforms 字段）\n clawdbot:\n emoji: \"📝\"\n version: \"2.1.2-beta.1\" # 单一真实来源，发布前必须先改这里。发布规则见 scripts/release.py\n requires: {}\n os: [\"linux\", \"darwin\", \"win32\"]\n---\n\n# MBA/学术论文多Agent协作工作流\n\n> 完整文档见：`references/checklist.md`（学术规范清单）、`references/loop-design.md`（Loop 设计原理）\n\n## 🔌 平台依赖（加载后必看）\n\n本 skill **不是**通用 Hermes skill，专为 OpenClaw 设计。在调用本 skill 任何 Python 入口前，先确认平台依赖：\n\n| 维度 | 依赖项 |\n|-------------------|------------------------------------------------------------------------|\n| **Agent 启动** | `sessions_spawn`（OpenClaw 子 agent 机制） |\n| **状态文件目录** | `~/.openclaw/workspace/{paper_name}/`（**非** Hermes 标准路径） |\n| **工具后端** | `web_search` / `tavily_search` / `arxiv_search`（OpenClaw MCP 工具链） |\n| **CLI 入口** | `python3 scripts/run_workflow.py {paper_name} --phase auto` |\n| **Python 路径** | `PYTHONPATH=scripts python3 ...`（CLI 内部期望 scripts 在 path 上） |\n\n**反模式：** 不要把本 skill 当作标准 Hermes skill 调用——Hermes 的 file / search / web 工具链不能驱动 v2 的状态机和 HIL 拦截。如果你需要把论文流程迁回 Hermes，先做\"状态层适配\"（用 Hermes 的 workspace 概念替代 `~/.openclaw/workspace/`，并把 `sessions_spawn` 改成 Hermes 的子任务机制），再启用本 skill。\n\n## ⚠️ 触发规则\n\n当用户请求生成 Word 文档且满足以下任一条件时，**必须**调用本 skill 的 Word 输出流程，不得使用简单 md2docx 脚本：\n- 输入文件路径匹配：`论文*.md`、`*thesis*.md`、`*dissertation*.md`\n- 上下文中存在「论文」「MBA」「答辩」「开题」等关键词\n- 用户明确要求导出 `.docx` 格式且文件性质为学术论文\n\n**正确流程：** 写作语法预检 → Review Agent 终审（`scripts/loop_self_check.py` 校验通过）→ `scripts/md2docx_strict.py` 合规转换 → Word 输出\n\n## ⚠️ v1 / v2 选择矩阵（加载后必看）\n\nv2 仍处于 beta，**生产论文默认走 v1**。仅当用户明确要求时再切 v2：\n\n| 场景 | 选择 | 触发依据 |\n|------|------|---------|\n| 用户说「稳一点 / 跑过答辩 / 已用 v1 / 默认」 | ✅ v1 (`thesis-workflow`) | 默认基线 |\n| 论文已在 `~/.openclaw/workspace/{paper}/` 下运行 v1 | ❌ 切 v2 | 状态文件不兼容 |\n| 用户说「用 v2 / 新框架 / outline-anchored / 9 HIL / BGE 多工具并行」 | ✅ 本 skill (v2) | 显式升级 |\n| 用户未明示 + 新论文 | ⚠️ 走 v1 | 避开 beta 风险 |\n\n**反模式：** 不要因为「本 skill 描述更新」就把现有 v1 论文切到 v2——v2 的 `_orchestrate_state.json` schema 与 v1 不兼容。\n\n### v2 HIL 节点一览（确定用 v2 之后再读）\n\nv2 在 9 个位置**强制 human-in-the-loop**：每到这些点状态机会 hard pause，必须用户确认才能推进。如果 agent 想绕过任何一项，v2.0.6 的拦截规则会拒绝（见 §v2.0.6 拦截规则）：\n\n| # | 触发位置 | 检查内容 | 决策 |\n|----|--------------------------------|--------------------------------|-------------------------------|\n| 1 | Phase 1.1 后 | 大纲结构 + 公司映射 | 接受(actual_name/跳过) / 修改 |\n| 2 | Phase 1.3 后 | 归因结果 | 接受 / 调整 hint |\n| 3 | 在 `write_single_node()` 写入单节点前 | info_scarcity | 提供 hint / AI 生成 / 跳过 |\n| 4 | Phase 2 评审后 | quality=medium/low | 接受 / 重写 |\n| 5 | Phase 2 完成后 | 章节内容预览 | 通过 / 修改 |\n| 6 | Phase 3 整合后 | 整合版内容 | 通过 / 修改反馈 |\n| 7 | Phase 3.5 P0 修复 | 超 3 轮未收敛 | 接受 / 继续修订 |\n| 8 | Phase 4 整合方案 | 方案是否接受 | 接受 / 修改 |\n| 9 | Phase 5.2 后 | Word 输出 | 导出 / 修改 |\n\n**HIL #1 公司映射（v2.1.2+）：** HIL #1 同时确认大纲 + 采集公司 `actual_name`：\n- 输入 `[1] vivo` → 接受大纲，`actual_name=\"vivo\"`\n- 输入 `[2]` → 接受大纲，`skip_mapping=true`（仅适用于纯理论论文）\n- 输入 `[3]` → 取消，不修改 state\n- 不提供 actual_name 且不跳过 → `confirm_phase1()` 返回错误「公司映射未填写」\n\n> **总计 9 HIL 节点**（公司映射合并入 #1，不新增节点）。\n\n**反模式：** 不要给 agent 传 `allow_skip_hil=True` 或在 prompt 里写\"自动通过所有 HIL\"——HIL 是论文质量最后一道防线，绕过它的代价是错版交付给导师。\n\n### v2.0.6 拦截规则（与 HIL 表配套必读）\n\n如果 agent 想绕过 HIL 或绕过\"独立评审\"，v2.0.6 在 orchestrator 层有 3 类硬拦截：\n\n| 拦截点 | 强制规则 | 失败场景 |\n|--------|----------|----------|\n| **拍板 #1 强制** | `phase1_3_skip` 不允许；`skip_phase1_3()` 需要 `MBA_THESIS_PRODUCTION=1` + 必填 `reason`/`operator` + audit log | 跳过 Phase 1.3 → 论文方向错位无人工把关，全文跑偏 |\n| **B-2 幂等保护** | `outline_update_status()` 默认拒绝覆盖已 completed 节点 | 误重写已通过审核的节点 → 评审历史回滚，质量倒退 |\n| **独立 Reviewer** | `write_single_node()` 默认要求 `reviewer_func ≠ llm_func` | 生成+评审用同一 LLM → 自我审核，\"我写的都对\"假阳性 |\n\n**反模式：** 不要在 prompt 里\"建议 agent 用 force=True 绕过\"或\"把 allow_skip_hil 设为 True\"——v2.0.6 的拦截规则会拒绝并返回错误。绕过拦截的代价比\"卡在 HIL 等用户确认\"高得多。\n\n## 核心架构\n\n```\nPhase 1（规划）→ Phase 2（逐节点写作）→ Phase 2.5（内容确认）\n→ Phase 3（整合）→ Phase 3.5（学术深度评审）\n→ Phase 4（修复）→ Phase 5（终审 + Word 输出）\n```\n\n⚠️ **阶段强制顺序：** 全部 Phase 必须按顺序执行，不得跳过。Phase 2.5（人工确认门槛）和 Phase 3.5（深度评审）是固定节点，不得跳过。\n\n## Agent 设计原则\n\n**每个 Agent 只做一件事。** Agent 间通过文件传递结果，不共享上下文。Orchestrator 专注调度，不执行执行性工作。\n\n| Agent | 调用方式 | 主责 |\n|-------|---------|------|\n| **Orchestrator** | 当前 session | 调度 / 推进 / 决策 |\n| **NodeWriter** | `sessions_spawn` | 逐节点内容生成 |\n| **Reviewer** | `sessions_spawn` | Phase 3/5 规则型审核 |\n| **DeepReviewer** | `sessions_spawn` | Phase 3.5 学术深度评审 |\n| **Integrator** | `sessions_spawn` | Phase 4 整合方案 |\n| **WordAgent** | `exec python3` | md2docx执行 + 格式校验 |\n\n## 关键实现说明\n\n### 公司信息处理\n\n- 用真实公司名搜索公开数据，填入正文时替换为代号（A公司/B公司）\n- 搜索 prompt 用真实名，输出 prompt 用代号\n- 映射关系不进入最终文档\n\n#### 公司映射状态字段（v2.1.2+）\n\n```json\n\"company_info\": {\n \"code_name\": \"A公司\", // 从开题报告 docx 自动提取\n \"actual_name\": \"vivo\", // HIL #1 由用户填入；空/null = 未填\n \"skip_mapping\": false, // true = 显式跳过(纯理论论文)\n \"confirmed\": true, // confirm_phase1() 校验通过\n \"confirmed_at\": \"2026-07-02T...\"\n}\n```\n\n**强制校验：** `confirm_phase1()` 在 v2.1.2+ 会拒绝 `actual_name=None && skip_mapping=false` 的 state，必须二选一。\n\n**使用场景：**\n- Phase 2 数据检索：搜 `actual_name` 公开数据\n- Phase 2 写作锚定：写文档时确保代换为 `code_name`\n- Phase 5 输出前：脱敏校验，确认 `actual_name` 不在最终 Word 正文里\n\n**安全约束：** 该字段**不会进入最终 Word 文档**，仅作为写作过程的内部状态。\n\n### 检索同步规则\n\n所有 Phase 调用数据查询工具（`web_search` / `academic-research`）时，必须：\n1. 同步输出工具名称 + 查询条件 + 结果摘要（<50字）\n2. Subagent 用 `sessions_send` 向主 session 发送同步\n3. 大型检索完成后输出结构化结果摘要\n\n### 数据查询工具（v2 多工具并行策略）\n\n> **核心原则**：4个工具并行发出，取长补短，去重排序，任意失败不阻断。\n> `web_search` 等内置工具 Agent 直接调用，无需经过 Python 层包装。\n\n**工具矩阵：**\n\n| 工具 | 来源 | 适用场景 |\n|------|------|---------|\n| `web_search` | OpenClaw 内置（头条搜索） | 行业数据、市场规模、新闻动态 |\n| `tavily_search` | Tavily MCP（OpenClaw 走内置桥接；Hermes 走 mcporter） | 结构化摘要、权威来源 |\n| `arxiv_search` | arXiv MCP（mcporter） | 前沿学术论文、技术细节 |\n| `openalex_search` | scholar-search.py（OpenAlex） | 学术文献、引用分析 |\n\n**Tavily MCP 检测（v2.1.2+）：** `_check_tavily_mcp()` 自动检测运行平台：\n- **OpenClaw runtime**：通过 `openclaw skills list --json` 检测 `tavily-mcp` 是否注册，注册即通过\n- **Hermes 兼容**：降级调 `mcporter call tavily-mcp.tavily_search`\n- **其他**：报错\n\nTavily 在 v2.1.2+ 已改为 `install_category=\"none\"`，pre-flight 不再卡 needs_ai_deps 流程。OpenClaw runtime 下 agent 可直接调用内置 `tavily-mcp__tavily_search` 工具。\n\n**Python 层调用（`research_tools.py`）：**\n```python\nfrom research_tools import quick_search, research_enrich\n\n# 快速检索（返回文本，供注入 prompt）\nresult = quick_search(\"竞争战略 市场规模 2024\")\n\n# 节点级检索（自动取 outline 中的 research_keywords）\nctx = research_enrich(node_id, paper_name)\n```\n\n**并行执行逻辑：**\n1. 四工具同时发出，不串行等待\n2. 各工具独立降级（超时/失败 → 静默忽略）\n3. 结果按 URL 去重 + score 排序\n4. 输出格式：`[来源] 标题\\n 摘要\\n URL`\n\n**Agent 视角：**\n- Agent 可继续直接使用 `web_search(query=...)` 等内置工具\n- `quick_search()` 是 Python 层的补充，用于学术/论文场景的结构化检索\n\n## Phase 详解\n\n### Phase 1：规划与定稿\n\n**🔴 红线：** Phase 1.1 / 1.3 **禁止**直接调用 Python API，必须经 `run_workflow.py`（详见 §A.6）。直接 `import orchestrator_v2` 在 Phase 1 阶段会绕过用户 HIL 确认，论文签收前的方向错误会全白做。\n\n通过问答输出确认清单，用户逐项确认后方可动笔。\n\n**红色星标项（必填）：**\n- ⭐ 实际公司名称（仅用于数据检索，正文以A公司/B公司呈现，不进入公开文档）\n- ⭐ 大纲结构（7章大纲逐章确认）\n- 论文基本信息（题目/作者/专业/学位类型/答辩年份）\n\n→ 生成「写作任务书」用户签收后进入 Phase 2。\n\n### Phase 2：逐节点写作\n\n**前置检查：** Phase 1 必填项已确认\n\n**🔴 红线：**\n- ❌ 跳过 `run_workflow.py` 直接读写 `_orchestrate_state.json`（必须经 CLI 入口）→ 失败场景：CLI 内部维护\"状态机锁 + phase 推进历史 + audit log\"，直接读写会绕过锁，导致下一 Phase 跳号或死锁\n- ❌ 手工修改状态文件的 `phase*_status` 字段（会破坏 Orchestrator Loop 的下一阶段判断）\n- ❌ 长任务不汇报进度（必须按 25% / 50% / 75% / 100% 节点主动汇报，含 `completed_nodes` 数）→ 失败场景：Phase 2 写作耗时 20+ 分钟无汇报，用户以为 session 卡死会主动打断，导致已写 30 节点的章节全部丢失、状态半成品\n\nOrchestrator 遍历 outline 树中的每个节点，调用 `write_single_node()` 逐个生成内容。\n每个节点写作前通过 `context_builder.py` 构建 prompt 包，自动注入：\n- 承接上文（auto bridge）\n- 分析维度建议（规则推导）\n- 开题报告方向参考（content_hint）\n- 行业数据参考（quick_search 多工具检索）\n\n**Phase 2 强制检索要求**（关键词中的 `{论文主题行业}` 由 Orchestrator 自动提取）：\n- 第3章 PESTEL 分析前 → 多工具并行搜索「{论文主题行业} 市场规模/趋势/政策」\n- 第3章 五力模型分析前 → 多工具并行搜索「{论文主题行业} 主要竞争对手/市场份额」\n- 战略理论部分 → 多工具并行搜索「{论文主题行业} 竞争战略 应用」\n- 每章至少 1 个引用标注来源，全文检索记录 ≥ 3 次\n- **多工具并行检索**：调用 `quick_search()` 或 `research_enrich()`，结果自动去重排序\n\n**状态文件机制：** `_orchestrate_state.json`（`scripts/state_manager_v2.py`）\n\n→ 全部节点写完且字数达标后进入 Phase 2.5（内容确认）。\n\n### Phase 3：整合\n\nReviewer 对整合版论文进行审核。审核维度：格式 / 大纲 / 内容准确性 / 查重风险 / 学术规范 / 写作语法。\n\n### Phase 3.5：深度学术评审（固定节点）\n\nDeepReviewer 对 Phase 3 报告进行二次审查，输出 P0/P1/P2 分级问题清单。P0 问题进入修订 → 重审闭环（见审核 Loop）。\n\n### Phase 4：整合\n\nIntegrator 汇总 Phase 3 + Phase 3.5 全部评审结果，制定整合方案。核心原则：取长补短，不为统一而破坏内容质量。\n\n**自动验证：** 整合版运行 `python3 scripts/loop_self_check.py` 校验，100%通过方可输出 Word。\n\n### Phase 5：终审与输出\n\n- Phase 5：Reviewer 终审\n- Phase 5.1：[可选] `humanize-chinese` skill 去AI味\n- Phase 5.2：**调用 `thesis-docx-export` skill**（Word 转换 + 10 项 Guardrails 校验）\n\n## Orchestrator 生命周期管理\n\n**🔴 红线：** Phase 1 / 5.x **必须**经 `run_workflow.py` 入口；Phase 2-4 才允许 `import orchestrator_v2` 直接调 Python API（且仅在已通过 run_workflow 进入论文状态之后）。\n- ❌ 跳过 `run_workflow.py` 直接 `from orchestrator_v2 import orchestrate` → 失败场景：CLI 内部维护\"状态机锁 + phase 推进历史 + audit log\"，直接 import 绕过锁，导致下一 Phase 跳号或死锁\n- ❌ Phase 1 任何子阶段（1.1 / 1.2 / 1.3）直接 import orchestrator_v2 调 `phase1_*` → 失败场景：绕过用户在 Phase 1.1 / 1.3 末尾的 HIL 签收，论文方向错位无人工把关\n- ❌ 把 `force=True` / `allow_skip_hil=True` 作为 prompt 默认值 → 失败场景：v2.0.6 拦截规则会拒绝并抛错；agent 越权操作进退两难\n\n### 真实入口（v2.0.6 新增）\n\n> **执行脚本**：`scripts/run_workflow.py`（v2 真实入口 CLI）\n> **状态文件**：`~/.openclaw/workspace/{paper_name}/_orchestrate_state.json`\n> **设计原则**：驱动状态机 + 9 个 HIL 节点 hard pause\n\n```bash\n# 仅查看状态\npython3 scripts/run_workflow.py --status\n\n# auto 模式：根据 state 自动判断下一步\npython3 scripts/run_workflow.py --phase auto\n\n# 指定阶段\npython3 scripts/run_workflow.py --phase phase1\npython3 scripts/run_workflow.py --phase phase2 # 需 --llm\npython3 scripts/run_workflow.py --phase phase3\n```\n\n### Python API（v2.0.9）\n\n```python\nimport sys\nsys.path.insert(0, \"scripts\")\nfrom orchestrator_v2 import orchestrate, write_single_node, apply_user_decision\n\n# Phase 1.1: 解析开题报告（docx 或文本）\nr = orchestrate(paper_name, action=\"phase1_1_init\",\n input_type=\"docx\", input_data=\"path/to/proposal.docx\")\n\n# Phase 1.2: 确认大纲（用户 HIL）\nr = orchestrate(paper_name, action=\"phase1_confirm\")\n\n# Phase 1.3: 提交开题报告归因\nr = orchestrate(paper_name, action=\"phase1_3_submit\",\n docx_path=\"path/to/proposal.docx\", llm_func=my_llm)\n\n# Phase 1.3: 确认归因（用户 HIL）\nr = orchestrate(paper_name, action=\"phase1_3_confirm\")\n\n# Phase 2: 逐节点写作（v2.0.4 推荐调用模式）\nfor node_id in next_nodes:\n r = write_single_node(paper_name, node_id,\n reviewer_func=my_reviewer) # 独立评审，llm_func 内部从 session 获取\n\n# Phase 3: 整合\nr = orchestrate(paper_name, action=\"phase3_review\")\n\n# Phase 3.5: 深度学术评审（自动进入 Phase 3.5/4/5 链）\n# Phase 3 → orchestrate_phase3_5() → P0修复 → Phase 4 → Phase 5\nr = orchestrate(paper_name, phase=\"phase3\", action=\"phase3_export\")\n\n# Phase 5: Word 输出提示\nprint(r.get(\"message\", \"\"))\n```\n\n### HIL 节点（v2.0.6 完整 9 个）\n\n> 9 个 HIL 节点的速查表已前移到 `## 核心架构` 之前（紧跟 v1/v2 选择矩阵后）。在 §\"v2 HIL 节点一览\"查看完整表。\n\n### v2.0.6 拦截规则（enforcement）\n\n> v2.0.6 拦截规则段（拍板 #1 / B-2 幂等 / 独立 Reviewer）已前移到 `## 核心架构` 之前（紧跟 9 个 HIL 节点表后）。在 §\"v2.0.6 拦截规则\"查看完整表。\n\n### 审核 Loop 自动重审\n\nPhase 3.5 完成 → orchestrator 解析 P0 计数 → 有 P0？→ 自动进入修订\n→ 修订完成 → 自动回到 Phase 3.5 重审 → 连续 2 轮无新 P0 → 通过\n→ 超过 3 轮 → HIL 暂停\n\n### Phase 内部自检\n\n每 Phase 完成后，orchestrator 自动运行 `loop_self_check.py` 校验：\n```bash\npython3 scripts/orchestrator.py 状态文件.json --validate\n```\n校验失败 → RETRY 打回 → Agent 修复 → 再次校验（最多 3 次）\n\n## ⚠️ Loop 设计原则\n\n5 个 Loop 元素的详细定义、终止条件、HIL 检查点对照、与 OpenClaw Agent Loop 的差异比较：详见 `references/loop-design.md`（302 行）。\n\n**速记：** 每个 Loop 最多重试 3 次；Phase 1 / 2.5 / 4 / 5.2 末尾为强制 HIL 节点（必须用户确认才能推进）。\n\n## Guardrails 校验（10 项）\n\n```bash\npython3 scripts/loop_self_check.py --file 论文_xxx.md # 单文件\npython3 scripts/loop_self_check.py --phase 2 --workspace ~/.openclaw/workspace/ # Phase 级别\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx # Word 校验\n```\n\n| # | 校验项 | 失败阻断 |\n|---|--------|---------|\n| 1 | 章节完整性（7章齐全） | Phase 2/4 |\n| 2 | 字数门槛（每章≥100行） | Phase 2/4 |\n| 3 | 参考文献存在 | Phase 4 |\n| 4 | 无 `## 第X章` 混合格式 | Phase 2/4 |\n| 5 | 无 `**正文加粗**` | Phase 2/4 |\n| 6 | 引用完整性（逐章≥1处，全文≥10处） | Phase 2/4 |\n| 7 | 三线表列数一致 | Phase 4 |\n| 8 | 表标题在表上方 | Phase 4 |\n| 9 | 无合并残留（`===END===`） | Phase 4 |\n| 10 | 核心章节关键词（第5章战略/第6章实施） | Phase 2.5 |\n\n## Word 输出\n\n> **本段已外移。** Word 转换、加粗过滤、三线表、分页、Guardrails 10 项校验等所有 Word 相关细节，由独立 skill `thesis-docx-export` 承载。\n>\n> 调用入口和文档：\n> - Skill：`thesis-docx-export/SKILL.md`\n> - 18 项格式规范清单：`thesis-docx-export/references/checklist.md`\n> - 10 项 Guardrails 校验：`thesis-docx-export/scripts/loop_self_check.py`（软链接 → `scripts/loop_self_check.py`）\n>\n> 主 skill 只在 Phase 5.2 阶段调用本 skill，不在 Phase 1-5 重复展开。\n\n## 附录：脚本与文档结构\n\n```\nthesis-workflow/\n├── SKILL.md ← 本文件（简版触发器 + 核心逻辑）\n├── README.md / README_EN.md ← 安装/使用说明\n├── CHANGELOG.md ← 版本日志\n├── config.template ← 配置模板\n├── install.sh ← 安装脚本\n├── .clawhubignore / .github/workflows/skill-publish.yml\n├── scripts/\n│ ├── md2docx_strict.py ← Word 合规转换（真身在主 skill；docx-export 软链接共享）\n│ ├── loop_self_check.py ← Guardrails 自动化校验（10项）（真身在主 skill；docx-export 软链接共享）\n│ ├── state_manager.py ← 状态文件管理\n│ └── tests/ ← 单元测试\n├── references/\n│ ├── checklist.md ← 软链接 → thesis-docx-export/references/checklist.md\n│ ├── content-hint-fallback.md ← 附录 B 外移版（v7.0 跑题事故修复方案）\n│ ├── chapter-summary-design.md ← 章节摘要节点设计\n│ ├── git-workflow.md ← 双版本发布策略\n│ └── loop-design.md ← Loop 设计原理说明\n└── thesis-docx-export/ ← 独立 skill（Phase 5.2 Word 输出）\n ├── SKILL.md ← docx-export 入口文档\n ├── README.md / CHANGELOG.md\n ├── scripts/ ← 软链接主 skill scripts/\n └── references/ ← checklist.md 真身在此\n```\n\n## 附录 A：论文项目运行 Checklist（agent 必遵守）\n\n> **来源**：v7.0 事故复盘 → 运营者 22:19 反馈 / 2026-06-29 \n> **适用对象**：跑 thesis-workflow-v2 的任何 agent（含 main session 和 isolated） \n> **生效日期**：2026-06-29 起\n\n### A.1 触发即汇报\n\n启动任何 thesis-workflow-v2 阶段前，先发一条汇报：\n- 论文名 / 阶段 / 启动时间 / 监考路径（如有 PID/log）\n- 5-30 字，简洁不啰嗦\n\n### A.2 阶段切换必汇报\n\n- Phase 1 → Phase 2（写作开始）\n- Phase 2 → Phase 3（整合开始）\n- Phase 3 → Phase 3.5（评审开始）\n- Phase 3.5 → Phase 4 / Phase 5（终审/导出）\n\n每切换发一条\"已到 X 阶段\"短汇报。\n\n### A.3 长跑阶段主动节拍\n\nPhase 2 写作阶段（如有 background 任务）：\n\n| 进度节点 | 必汇报 |\n|---------|--------|\n| 启动 | ✅ |\n| 完成 25% | ✅ |\n| 完成 50% | ✅ |\n| 完成 75% | ✅ |\n| 完成 100% / 失败 | ✅ |\n\n- 每次汇报含当前 `completed_nodes` 数量\n- 用 `cat _orchestrate_state.json` 拿实时数据\n\n### A.4 异常即停 + 主动汇报\n\n触发任一异常情况，**立即**停下来汇报（不等用户问）：\n- content_hint 覆盖率 < 50% → Phase 1.3 异常\n- 大量节点 failed → Phase 2 失败\n- 整合版字数异常（< 30k 或 > 200k）\n- outline_state 节点结构与 _orchestrate_state 不一致\n\n### A.5 完成必汇报（含产出清单）\n\n论文交付时，必汇报：\n- 终稿路径\n- 字数（中文字数 / 总字符数）\n- 章节完成情况\n- 异常/缺陷（如有）\n- 邮件/通知状态\n\n### A.6 红线禁止（继承自 AGENTS.md）\n\n- ❌ 跳过 run_workflow.py 操作状态文件\n- ❌ 不汇报长任务进度\n- ❌ Phase 1.3 / 1.1 直接调用 Python API\n- ❌ 状态文件手工修改 phase*_status 字段\n\n### A.7 辅助工具（可选）\n\n如需手动查看状态，可用：\n```bash\npython3 ~/.openclaw/scripts/thesis_progress_reporter.py --idle-minutes 60\n```\n\n脚本全局通用，跨 macOS/Linux/Windows，纯 stdlib。idle 60min 自动静默。\n\n## 附录 B（指针）：已批准改进方案 — content_hint fallback\n\n历史事故与代码实现已外移到 `references/content-hint-fallback.md`（139 行）。当 `node.content_hint` 为空时，`scripts/context_builder.py` 会自动注入\"大纲骨架 + 反面警示\"以防 LLM 跑题。\n\n如需查具体函数实现（`_extract_paper_subject` / `_build_outline_skeleton` / `_build_no_runoff_warning`）或验收标准，跳到 references 文件即可。\n\nFile v2.1.2-beta.1:skills/gatekeeper/SKILL.md\n\n# Gatekeeper Skill — 论文写作质量与流程门禁\n\n> 版本：1.0.0\n> 角色：所有产出给用户前的最后一道门；全程守护流程/规范/质量\n\n---\n\n## 角色定义\n\n**Gatekeeper = 质量门禁 + 流程门禁 + 结果门禁 + 出口门禁**\n\n- 独立 session 运行，不阻塞 Orchestrator 执行路径\n- 所有异常记录到 `_gk_exception_log.json`\n- 流程结束后统一汇报给用户\n- 用户选择\"修复\"则触发闭环修复流程\n\n---\n\n## 门禁层次\n\n### 1. 流程门禁（Process Gate）\n\n**触发时机**：每次 Phase 切换时\n\n```\n检查项：\n ✓ 前置 Phase 是否已完成\n ✓ 当前 Phase 的必填字段是否齐全\n ✓ 状态机是否合法跳转（phase1 → phase2 需要 phase1_3_confirmed）\n ✓ HIL 节点是否满足通过条件\n```\n\n**阻断行为**：\n- 写入 `_gk_exception_log.json`\n- 通知用户，等待决策\n- Orchestrator 暂停直到用户回复\n\n---\n\n### 2. 质量门禁（Quality Gate）\n\n**触发时机**：每个节点写作完成后、整合前、导出前\n\n```\n检查项（loop_self_check）：\n ✓ 章节完整性（7章都有）\n ✓ 无 **加粗** 残留\n ✓ 引用数量逐章检查（每章 ≥ 1 处）\n ✓ 三线表格式正确\n ✓ 无乱码/占位符残留\n ✓ 标题层级正确\n ✓ 字数达标（每章 ≥ 800 字）\n```\n\n**不达标** → 打回重写，不进入下一节点\n\n---\n\n### 3. 结果门禁（Result Gate）\n\n**触发时机**：Phase 3 整合后、Phase 5 导出前\n\n```\n检查项：\n ✓ 开题报告承诺的内容是否落地\n ✓ 关键章节（PEST/战略理论/案例分析）是否充实\n ✓ 章节之间逻辑衔接是否顺畅\n ✓ 结论与前文分析是否对应\n```\n\n---\n\n### 4. 出口门禁（Export Gate）\n\n**触发时机**：最终输出给用户前（唯一出口）\n\n```\n检查项：\n ✓ Guardrails 最终校验通过\n ✓ Word 文档生成成功\n ✓ 用户确认导出\n```\n\n---\n\n## 异常日志设计\n\n**文件路径**：`~/.openclaw/workspace/papers/{paper_name}/_gk_exception_log.json`\n\n```json\n{\n \"paper_name\": \"论文名称\",\n \"start_time\": \"2026-06-26T21:00:00+08:00\",\n \"exceptions\": [\n {\n \"id\": 1,\n \"timestamp\": \"2026-06-26T21:18:00+08:00\",\n \"phase\": \"phase2\",\n \"node_id\": \"ch3\",\n \"gate_type\": \"quality_gate\",\n \"gate_name\": \"citation_check\",\n \"description\": \"第3章引用数量不足：0处（要求≥1处）\",\n \"severity\": \"error\",\n \"status\": \"pending\",\n \"action_taken\": null,\n \"repaired_at\": null,\n \"repaired_by\": null,\n \"user_notified\": true,\n \"user_decision\": null\n }\n ],\n \"summary\": {\n \"total\": 1,\n \"pending\": 1,\n \"fixed\": 0,\n \"skipped\": 0\n }\n}\n```\n\n---\n\n## 用户交互流程\n\n### 流程守护（异常发生时）\n\n```\nGatekeeper 发现异常\n ↓\n写入 _gk_exception_log.json（status=pending）\n ↓\n通知用户（飞书）：\n━━━━━━━━━━━━━━━━━━━━━━\n🤖 [Gatekeeper] 发现异常\n\n环节：Phase 2（节点写作）\n节点：ch3 第3章\n问题：引用数量不足（0处，要求≥1处）\n━━━━━━━━━━━━━━━━━━━━━━\n请选择：\n [1] 修复后继续（打回重写）\n [2] 跳过此检查（谨慎！）\n [3] 暂停，手动介入\n━━━━━━━━━━━━━━━━━━━━━━\n ↓\n等待用户回复\n ↓\n用户选择 [1/2/3]\n ↓\n更新 exception.status + action_taken\n ↓\n[1] → 通知 Orchestrator 修复\n[2] → 继续流程（记录 skip）\n[3] → 暂停，等用户手动触发\n```\n\n### 流程结束后（统一汇报）\n\n```\n所有 session 结束后\n ↓\nGatekeeper 生成最终报告\n ↓\n发给用户：\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n🤖 [Gatekeeper] 流程结束 — 异常报告\n\n本次流程共发现 N 个异常：\n\n【异常 #1】\n时间：2026-06-26 21:18\n环节：Phase 2\n节点：ch3\n类型：质量门禁 - 引用数量不足\n处理：已修复\n\n【异常 #2】\n时间：2026-06-26 21:25\n环节：Phase 4\n节点：—\n类型：流程门禁 - HIL #8 阻断\n处理：用户确认跳过\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n建议优化项：\n 1. ...\n 2. ...\n\n请选择：\n [1] 查看异常详情\n [2] 优化 skill 配置\n [3] 结束\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n---\n\n## 巡检机制\n\nGatekeeper 启动后定期巡检（每 30 秒）：\n\n```\n巡检项：\n ✓ 当前 state 的 phase 是否合法\n ✓ completed_nodes 是否有重复\n ✓ failed_nodes 是否长时间未修复\n ✓ phase3_5 连续轮次是否异常（>5轮则告警）\n ✓ 是否有节点写作超 30 分钟未完成（疑似卡住）\n```\n\n---\n\n## 与 Orchestrator 的协作方式\n\n**通过状态文件通信，零直接函数调用：**\n\n```\nOrchestrator 写：_orchestrate_state.json\nGatekeeper 读：_orchestrate_state.json + 巡检\nGatekeeper 写：_gk_exception_log.json\nOrchestrator 读：_gk_exception_log.json（查看是否有 pending exception）\n```\n\n**关键状态字段：**\n\n```\ngk_last_check: 最后巡检时间\ngk_exception_count: 当前 pending 异常数\ngk_user_decision: 用户最新决策（由 Gatekeeper 写入）\n```\n\n---\n\n## 启动方式\n\n```python\n# Orchestrator 需要时 spawn\nsessions_spawn(\n task=\"gatekeeper\",\n taskName=\"gk_{paper_name}\",\n runtime=\"subagent\",\n context=\"isolated\",\n payload={\n \"paper_name\": \"论文名\",\n \"mode\": \"daemon\", # 常驻巡检\n }\n)\n```\n\n---\n\n## 权限要求\n\n- 读：`papers/{paper_name}/*.json`\n- 写：`papers/{paper_name}/_gk_exception_log.json`\n- 通知：飞书/微信（sessions_send）\n\nFile v2.1.2-beta.1:thesis-docx-export/SKILL.md\n\n---\nname: thesis-docx-export\ndescription: \"Convert academic thesis markdown (.md) into a Word (.docx) document that meets the MBA / 南大 / GB/T 7714 formatting spec, and run the 10-item Guardrails check before and after export. Triggers: 导出 Word / 转换为 docx / 论文格式校验 / Guardrails 校验 / md2docx / 三线表 / 分页符 / GB/T 7714 参考文献格式. Required by `thesis-workflow-v2` Phase 5.2; can also be invoked standalone after manual writing.\"\nplatforms: [linux, macos, windows]\nmetadata:\n clawdbot:\n emoji: \"📄\"\n version: \"1.0.0\" # 单一真实来源；主 skill thesis-workflow-v2 仅在 Phase 5.2 阶段引用本 skill\n requires: {}\n os: [\"linux\", \"darwin\", \"win32\"]\n---\n\n# Thesis DOCX Export\n\n把学术论文 Markdown 转换为符合学术规范的 Word 文档，并在导出前后自动跑 Guardrails 校验。\n\n本 skill 是 `thesis-workflow-v2`（主 skill）Phase 5.2 阶段的\"出口工序\"——主 skill 完成 Phase 1-5 内容生产后，调用本 skill 做 Word 转换和最终格式校验。本 skill **也可以独立调用**：用户手写完论文后，直接用本 skill 做导出。\n\n> **核心原则**：本 skill 不做内容生成（写、审、整合都是主 skill 的事）。本 skill 只做\"格式合规\"：校验 → 转换 → 再校验。\n\n## ⚠️ 调用矩阵\n\n| 触发场景 | 选择 |\n|---------|------|\n| 主 skill `thesis-workflow-v2` 跑到 Phase 5.2 | ✅ 本 skill（自动调用，无需用户手动触发） |\n| 用户手写论文后想导出 docx | ✅ 本 skill（standalone 调用） |\n| 用户只想校验 Markdown 是否符合学术规范 | ✅ `python3 scripts/loop_self_check.py --file 论文.md`（只校验、不导出） |\n| 用户想用 pandoc / python-docx 直接生成 Word | ❌ 本 skill（pandoc 不做三线表、不做 GB/T 7714 排序） |\n\n**反模式：** 不要把本 skill 用于\"内容生成\"——主 skill 的 Phase 2 写作、Phase 3 审核、Phase 4 整合都由 `thesis-workflow-v2` 负责。本 skill 只接受已完成的 Markdown 输入。\n\n## 核心能力\n\n### 1. Guardrails 10 项自动校验\n\n`scripts/loop_self_check.py` 在转换前后各跑一次：\n\n```bash\n# 转换前校验 Markdown 内容（10 项 Guardrails）\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# 转换后再校验生成的 docx（Word 格式校验）\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n**10 项校验项详见 [references/checklist.md §六](references/checklist.md)**。\n\n### 2. Word 格式转换\n\n`scripts/md2docx_strict.py` 把符合 Guardrails 的 Markdown 转为 docx，应用以下格式：\n\n| 维度 | 规则 |\n|-------------|----------------------------------------------------------|\n| 正文加粗过滤 | 正文段落内的 `**text**` 全部转为普通文字（无强调术语） |\n| 表格加粗过滤 | 表格单元格内的 `**` 同步清除 |\n| 三线表 | 顶线 1.5 磅 / 表头底线 0.75 磅 / 底线 0.5 磅，无竖线 |\n| 分页符 | 每章标题前插入分页符（首章跳过），附录/致谢前分页 |\n| 字体 | 中文宋体 / 英文 Times New Roman / 标题黑体 |\n| 行距 | 正文 20 磅 |\n\n**反模式：** 不要用 `pandoc 论文.md -o 论文.docx` 走捷径——pandoc 不做加粗过滤、不做三线表、不做 GB/T 7714 排序；出来的 docx 必须经 `loop_self_check.py --verify-docx` 二次校验才能交付。\n\n## 入口与依赖\n\n### 入口\n\n```bash\n# 校验 + 转换 + 再校验 一条龙\npython3 scripts/loop_self_check.py --file 论文_xxx.md\npython3 scripts/md2docx_strict.py --input 论文_xxx.md --output 论文_xxx.docx\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n### 依赖\n\n- `python-docx`（Word 写入）\n- `pandoc`（Markdown 预处理）\n- 标准 Python 3.9+ 库\n\n### 反向依赖\n\n本 skill **被** `thesis-workflow-v2`（主 skill）Phase 5.2 引用。如果本 skill 不可用，主 skill 的 Phase 5.2 步骤会失败。\n\n## 文件结构\n\n```\nthesis-docx-export/\n├── SKILL.md ← 本文件\n├── README.md ← 用户使用说明\n├── CHANGELOG.md ← 版本日志\n├── scripts/\n│ ├── md2docx_strict.py ← Word 转换器（软链接 → ../../scripts/md2docx_strict.py）\n│ └── loop_self_check.py ← Guardrails + Word 校验（软链接 → ../../scripts/loop_self_check.py）\n└── references/\n └── checklist.md ← 18 项格式规范 + 10 项 Guardrails 校验项 + Phase 退出门禁\n```\n\n> **单一真实来源原则**：`md2docx_strict.py` 和 `loop_self_check.py` 的真身在主 skill `scripts/` 目录，本目录用软链接共享——避免代码 drift。\n\n## 18 项格式规范（人工对照清单）\n\n完整清单在 [references/checklist.md](references/checklist.md)，核心维度：\n\n- **格式维度（18 项）**：封面 / 原创性声明 / 中英文摘要 / 目录 / 章节标题层级 / 段落 / 图号图题 / 表号表题 / 表格 / 图表编号 / 注释 / 参考文献 / 页码 / 附录 / 致谢 / 写作语法\n- **大纲维度（2 项）**：章节范围 + 章节结构\n- **内容准确性（2 项）**：引用标注 + 数据自洽\n- **查重风险（1 项）**：30 字以上连续重合\n- **学术规范（6 项）**：引用完整率 + 术语缩写 + 中英文格式\n\n## 违规等级\n\n| 等级 | 标记 | 处理 |\n|---------|------|--------------------------------------------|\n| 🔴 P0 | 致命 | **必须修复**（章节缺失、参考文献缺失、合并残留） |\n| 🟡 P1 | 严重 | **必须修复**（标题层级错误、加粗残留、字数不足） |\n| ⚠️ P2 | 一般 | 建议修复（引用缺失、图表编号不规范） |\n| 💡 建议 | 优化 | 可选（措辞、过渡句式） |\n\n## 维护与支持\n\n- 维护者：`thesis-workflow-v2` 同 owner\n- 主 skill 引用：本 skill 在 `thesis-workflow-v2/SKILL.md` 的 Phase 5.2 段被引用\n- Bug 报告：在 GitHub `mba-thesis-workflow` 仓库的 issue 列表提，标签 `thesis-docx-export`\n\nFile v2.1.2-beta.1:README.md\n\n# MBA/学术论文 多Agent协作工作流（v2 新框架）\n\n📝 多Agent协作完成MBA/学术论文写作的完整工作流，支持大纲解析、逐节点写作、深度审核、整合终审、Word输出。\n\n适用于开题报告到毕业论文的全流程。\n\n---\n\n## ⚠️ 当前项目双版本并行\n\n本仓库包含 **两条独立版本线**，互不干扰、并行发布：\n\n| 版本线 | ClawHub Slug | 当前 latest | 状态 | 文档 |\n|--------|--------------|-------------|------|------|\n| **v1.x**（稳定） | `thesis-workflow` | **v1.7.3** | 长期维护，仅兼容性修复 | [CHANGELOG-v1.md](./CHANGELOG-v1.md) |\n| **v2.x**（新框架） | `thesis-workflow-v2` | **v2.0.14** | ⚠️ 测试版，outline-anchored + 9 HIL + 多工具检索 | [CHANGELOG-v2.md](./CHANGELOG-v2.md) |\n\n### 选型指南\n\n- **生产环境 / 已有 v1 用户** → `thesis-workflow` (v1.7.3，稳定)\n- **新框架 / outline-anchored / 9 HIL 体验** → `thesis-workflow-v2` (v2.0.14，测试)\n- **同时跑多篇论文** → 两个都装，**可共存**\n\n### 怎么装两个？\n\n```bash\n# v1 稳定版（不依赖本仓库）\nopenclaw skills install thesis-workflow\n\n# v2 测试版\nopenclaw skills install thesis-workflow-v2\n```\n\n两者安装路径、状态文件、依赖互不冲突。\n\n详见 [`references/git-workflow.md`](./references/git-workflow.md) 和 [CHANGELOG.md](./CHANGELOG.md) 索引。\n\n---\n\n## 核心功能（v2 框架）\n\n- **outline-anchored 写作**：以大纲为锚点，逐节点生成内容，节点间自动承接\n- **BGE-small-zh 向量标题匹配**：Phase 1.3 开题归因加速 30-90s → 2-5s\n- **多工具并行检索**：4工具（Tavily/arXiv/OpenAlex/web_search）同时搜索，去重排序\n- **Phase 3.5 深度学术评审**：P0/P1/P2 分级问题清单，自动修复 + 重审闭环\n- **RuntimeLLM**：零硬编码，自动复用当前 session 模型配置\n- **9 个 HIL 节点**：human-in-the-loop 检查点，关键决策不跳过\n- **公司映射强制采集**（v2.1.2+）：HIL #1 同步确认大纲 + 实际公司名（`actual_name`），确保 Phase 2 数据检索锚定真实公司\n- **OpenClaw 平台适配**（v2.1.2+）：Tavily MCP 检测自动识别 OpenClaw runtime，走内置桥接；不再依赖外部 `mcporter` CLI\n- **Guardrails 自检**：10 项自动化规范检查（章节完整性/字数/引用/表格格式等）\n- **Loop 架构**：Orchestrator Loop / 内部自检 Loop / 审核 Loop / Verification Loop\n- **Phase 5 Word输出**：[thesis-docx-export](../thesis-docx-export/SKILL.md) skill（独立子 skill，三线表/分页/字体/行距）\n\n## 适用场景TODO_SPLIT\n\n- MBA毕业论文（战略管理/企业分析类）\n- 学术研究报告（竞争战略/行业分析类）\n- 需要多轮审核、多版本整合的正式长文\n\n## 工作流程\n\n```\n用户 → Phase 1（大纲确认 + 开题归因）→ Phase 2（逐节点写作）→ Phase 2.5（用户确认）\n → Phase 3（整合）→ Phase 3.5（深度学术评审 → P0修复循环）\n → Phase 4（修复）→ Phase 5（终审 + Word输出）\n```\n\n## v2.0.x 版本历史（详见 [CHANGELOG-v2.md](./CHANGELOG-v2.md)）\n\n| 版本 | 亮点 |\n|------|------|\n| 2.0.21-beta | HIL #4 消息改为人话版：【节点X 写完：质量Y】 + AI 总结 + 路径 + 动作描述 |\n| 2.0.20-beta | 评审完整文字落盘 + HIL #4 消息简化为路径+选项（避免聊天刷屏）|\n| 2.0.19-beta | context_builder 主题锁定 + 反面警示 总是注入（修复 v8.0 ch1 跑题事故）|\n| 2.0.18-beta | outline_parser 新增 LLM 一次性兑底补全空 hint 节点 |\n| 2.0.17-beta | outline_parser 新增 C 路径：Word 自定义样式（MPA-章标题/一级节标题）支持 |\n| 2.0.12-beta | Phase 3.5 大纲锚定章节拆分（替代硬编码正则）+ P0/P1 修复（F1-F6）|\n| 2.0.11-beta | 清理 v1 残留 + clawhubignore 排除 |\n| 2.0.10-beta | Phase 3.5/4/5 实现 + requirements.txt + lazy BGE |\n| 2.0.9-beta | BGE-small-zh 向量标题匹配（Layer 2） |\n| 2.0.8-beta | multi-search并行引擎 + RuntimeLLM 零硬编码 |\n| 2.0.7 | outline_parser 引擎切换 B→A 单向降级 |\n| 2.0.6 | 双版本独立发布 + enforcement + 真实入口 CLI |\n| 2.0.5 | B-2 状态同步修复 |\n| 2.0.4 | B-1 HIL 死循环修复 |\n| 2.0.3 | P2 代码清理 |\n| 2.0.2 | P0/P1 修复 |\n| 2.0.1 | 方案 C 端到端验证 |\n| 2.0.0 | outline-anchored feature complete |\n\n## Agent 角色体系\n\n| Agent | 调用方式 | 主责 |\n|-------|---------|------|\n| **Orchestrator** | 当前 session | 调度 / 推进 / 决策 |\n| **NodeWriter** | `sessions_spawn` | 逐节点内容生成 |\n| **Reviewer** | `sessions_spawn` | Phase 3/5 规则型审核 |\n| **DeepReviewer** | `sessions_spawn` | Phase 3.5 学术深度评审 |\n| **Integrator** | `sessions_spawn` | Phase 4 整合方案 |\n| **WordAgent** | `exec python3` | md2docx执行 + 格式校验 |\n\n## 版本说明\n\n| 文件命名 | 说明 |\n|---------|------|\n| `论文_xxx.md` | 论文正稿 |\n| `_orchestrate_state.json` | 流程状态（自动管理） |\n| `_outline_state.json` | 大纲状态（自动管理） |\n\n## 写作规范\n\n- **引用格式**：GB/T 7714 作者年制（作者, 年）\n- **正文字数**：≥3.5万字\n- **写作语法**：正文段落禁止 `**加粗**` 强调术语\n- **中文字体**：宋体12磅，行距20磅\n- **英文字体**：Times New Roman\n- **标题字体**：黑体16磅/14磅/13磅\n\n## 技术栈\n\n- OpenClaw subagent (sessions_spawn)\n- BGE-small-zh 中文向量模型（Layer 2 标题匹配）\n- Tavily / arXiv / OpenAlex 多工具并行检索\n- **OpenClaw 平台原生集成**（v2.1.2+）：Tavily 通过 `openclaw skills list` 检测，不再依赖 mcporter\n- **Word 输出**：见 [thesis-docx-export](../thesis-docx-export/SKILL.md) 独立 skill\n\n## License\n\nMIT-0 — Free to use, modify, and distribute without attribution\n\n## Author\n\nGitHub: [hehe973781230](https://github.com/hehe973781230)\n\n---\n\n*If this skill is helpful to you, please give it a ⭐*\n\nFile v2.1.2-beta.1:thesis-docx-export/README.md\n\n# thesis-docx-export\n\n> 学术论文 Markdown → Word (.docx) 转换 + 格式校验工具集\n\n## 这是什么\n\n把符合学术规范（MBA / 南大 / GB/T 7714）的论文 Markdown 文件转换为 Word 文档，并在转换前后自动跑 Guardrails 校验。\n\n**主要场景**：\n\n1. **主 skill 配套**：`thesis-workflow-v2` 完成 Phase 1-5 后，Phase 5.2 自动调用本 skill 做 Word 转换\n2. **独立使用**：用户手写完论文后，直接用本 skill 校验 + 转换\n\n## 三步导出\n\n```bash\n# 1. 转换前：校验 Markdown 是否符合 10 项 Guardrails\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# 2. 转换：Markdown → Word\npython3 scripts/md2docx_strict.py --input 论文_xxx.md --output 论文_xxx.docx\n\n# 3. 转换后：校验生成的 docx 格式\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n## 安装\n\n```bash\n# 本 skill 是 thesis-workflow-v2 的子模块，已在仓库中。\n# 软链接共享主 skill 的 Python 脚本，单一真实来源。\npip install python-docx pandoc\n```\n\n## 不做什么\n\n- ❌ 不做内容生成（写、审、整合属于 `thesis-workflow-v2`）\n- ❌ 不做 pandoc 直接转换（pandoc 不做三线表、不做 GB/T 7714）\n- ❌ 不做引用文献自动抓取（用 `research_tools.py` 属于主 skill）\n\n## 详细文档\n\n- 格式规范清单：[references/checklist.md](references/checklist.md)\n- 触发场景与边界：见 [SKILL.md](SKILL.md)\n\nFile v2.1.2-beta.1:_meta.json\n\n{\n \"ownerId\": \"kn79wdg0zsjv6rg2zp40xfernd87sp4x\",\n \"slug\": \"thesis-workflow-v2\",\n \"version\": \"2.1.2-beta.1\",\n \"publishedAt\": 1782974835143\n}\n\nFile v2.1.2-beta.1:references/chapter-summary-design.md\n\n# 章节摘要节点设计说明（增强项1 — 跨父节点 Bridge）\n\n> 本文档解释 MBA Thesis Workflow v2.0.0 引入的 **章节摘要节点机制**——为什么要在 L1 章节末尾插入虚拟节点，以及如何利用它解决跨章节 bridge 断裂问题。\n\n---\n\n## 一、问题背景\n\n### 1.1 Bridge 机制回顾\n\nMBA 论文工作流的章节连贯性依赖 `context_builder.generate_bridge()`：\n\n- **P1（前序节点）**：当前节点的前一个兄弟节点（L2 同级）\n- **P2（父节点）**：当前节点的父节点（L1）\n- 任意一个能拿到 `key_conclusion` → 生成承接段\n\n### 1.2 桥断裂场景\n\n考虑以下目录结构：\n\n```\n1. 绪论 (ch1)\n 1.1 研究背景 (L2)\n 1.2 研究内容 (L2)\n2. 理论基础 (ch2)\n 2.1 竞争战略理论 (L2) ← 这节点写 bridge 时\n 2.2 文献综述 (L2)\n```\n\n写 `2.1` 时：\n- **prev** = `1.2`（前序节点的「1.2」） ❌ 跨章节，不是 prev\n- **parent** = `ch2`（父节点）❌ L1 章节通常无 key_conclusion\n- **结果**：bridge = null，NodeWriter 自由发挥开头，连贯性差\n\n这就是 v1.7.3 重审 Agent 反复指出的「bridge 断裂」问题。\n\n---\n\n## 二、方案 C：虚拟章节摘要节点\n\n### 2.1 核心思路\n\n在每个 L1 章节末尾**自动插入**虚拟节点 `__ch{N}_summary__`：\n- 不实际写作（不调用 NodeWriter）\n- 自动汇总本章所有 L2/L3 子节点的 `key_conclusion`\n- LLM 合成 200-300 字章节摘要\n- 下一章节首节点的 bridge 可引用\n\n### 2.2 节点结构\n\n```json\n{\n \"id\": \"__ch1_summary__\",\n \"level\": 1,\n \"title\": \"绪论 — 本章小结\",\n \"is_virtual\": true,\n \"type\": \"chapter_summary\",\n \"synthesizes\": [\"1.1\", \"1.2\"],\n \"chapter_id\": \"ch1\",\n \"chapter_title\": \"绪论\",\n \"key_conclusion\": \"本章从 AI 时代背景出发，提出差异化战略研究问题...\",\n \"writing_status\": \"completed\",\n \"word_count\": 50\n}\n```\n\n### 2.3 数据流\n\n```\n节点 N 写作完成\n ↓\nis_last_child_of_chapter(N) 检测\n ↓ 是\nsynthesize_chapter_summary(chapter_id)\n ↓\n收集 synthesizes 子节点结论 → LLM 合成 200-300 字摘要\n ↓\n写入 __ch{N}_summary__ 节点的 key_conclusion\n ↓\n下一章节首节点 bridge 自动引用（P3 fallback）\n```\n\n---\n\n## 三、Bridge 三级降级链\n\n`generate_bridge()` 新增 P3 优先级：\n\n| 优先级 | 来源 | 函数 | 场景 |\n|--------|------|------|------|\n| P1 | 前序节点 key_conclusion | `_build_bridge_from_prev` | 同章节内连续节点 |\n| P2 | 父节点 key_conclusion | `_build_bridge_from_parent` | 章节内首节点 |\n| **P3（新）** | **上一章节虚拟摘要** | **`_build_bridge_from_chapter_summary`** | **跨章节首节点** |\n\n**降级原则**：\n- 任何上游 key_conclusion 存在 → 立即返回（不走到下一级）\n- 全部为 None → 返回 `None`，NodeWriter 自行处理开头\n\n---\n\n## 四、LLM 失败安全降级（拍板决策 #3）\n\n按2026-06-23拍板决策，**LLM 合成失败时改为询问用户**，而不是简单拼接子节点结论。\n\n```python\ntry:\n response = llm_func(prompt)\n summary = response.strip()\nexcept Exception as e:\n return {\n \"ok\": False,\n \"action\": \"ask_user\", # 关键变化\n \"error\": f\"LLM 调用失败: {str(e)}\",\n \"chapter_id\": chapter_id,\n \"chapter_title\": chapter_title,\n \"child_conclusions\": [...] # 附带子节点结论供 Orchestrator 展示\n }\n```\n\nOrchestrator 收到 `action=\"ask_user\"` 时：\n1. 展示子节点结论给用户\n2. 询问用户手写摘要 / 跳过 / 重试\n3. 用户输入 → 第二次调用 `synthesize_chapter_summary(user_input=...)` → 写入\n\n---\n\n## 五、拍板决策汇总（2026-06-23）\n\n| # | 议题 | 决策 |\n|---|------|------|\n| 1 | 方案选型 | 方案 C（虚拟摘要节点） |\n| 2 | 摘要长度 | 200-300 字 |\n| 3 | LLM 失败处理 | **询问用户**（不简单拼接） |\n| 4 | 章节摘要评审 | 不参与 Phase 3 评审，仅作内部辅助 |\n| 5 | 设计文档 | references/chapter-summary-design.md |\n\n---\n\n## 六、代码落地\n\n| 文件 | 改动 |\n|------|------|\n| `outline_parser.py` | `insert_chapter_summary_nodes()` + 2 个辅助函数 |\n| `orchestrator_v2.py` | `is_last_child_of_chapter()` + `synthesize_chapter_summary()` + `write_single_node()` Step 4.5 |\n| `context_builder.py` | `_build_bridge_from_chapter_summary()` + `generate_bridge()` P3 fallback |\n| `state_manager_v2.py` | `_get_prev_chapter_summary()` + `outline_get_context()` 自动附加 |\n\n---\n\n## 七、测试覆盖（20 个测试用例）\n\n- `test_chapter_summary.py` (6)：节点插入、L3 纳入、幂等、边界、辅助函数\n- `test_synthesize_summary.py` (6)：检测、LLM 路径、用户输入、ask_user、空子节点、超长截断\n- `test_bridge_p3_fallback.py` (6)：P1/P2 优先级、P3 跨章节、不可用降级、首章节、context 自动附加\n- `test_integration_chapter_summary.py` (2)：happy path + LLM 失败 fallback 端到端\n\n总测试数：25 (v1.7.3) + 20 (v1.7.4) = **45 个**（v2.0.0 汇总为 **72 个**）\n\n---\n\n## 八、边界条件\n\n| 场景 | 行为 |\n|------|------|\n| 首章节首节点（1.1） | prev_chapter_summary = None → bridge = None（NodeWriter 自处理） |\n| 用户跳过某些节点 | 摘要只基于 synthesizes 中**已完成**子节点 |\n| LLM 合成失败 | action = \"ask_user\"，不写入 state |\n| 超长摘要（>300 字） | 自动截断到 300 字 |\n| 重复调用 insert | 幂等，已存在虚拟节点时跳过 |\n| 章节无任何子节点 key_conclusion | action = \"ask_user\"，附空列表 |\n\n---\n\n## 九、后续优化方向（非本次范围）\n\n- 章节摘要的版本控制（多版本对比）\n- 摘要参与 Phase 3 评审（如果以后放开拍板 #4）\n- 摘要可由用户直接编辑（不依赖 LLM）\n\nFile v2.1.2-beta.1:references/content-hint-fallback.md\n\n# Content Hint Fallback 设计（v7.0 跑题事故修复）\n\n> **来源文件**：原 SKILL.md 附录 B（外移于 2026-07-02 拆分重构）\n> **生效版本**：自 v2.1.x 起，content_hint fallback 已在 `scripts/context_builder.py` 落地\n\n本文档是 SKILL.md 附录 B 的外移版本，承载具体的修复方案、代码实现、测试用例和验收标准。\nSKILL.md 内的对应位置仅保留指针，避免主文档重复维护。\n\n---\n\n## 附录 B：已批准改进方案 — 大纲约束注入（已实施 2026-06-30）\n\n> **来源**：v7.0 事故复盘 → 运营者 22:19 反馈，Q3=A / 2026-06-29 \n> **实施状态**：✅ 已实施并验收（2026-06-30）\n> **注意**：本附录不绑具体版本号。以 SKILL.md frontmatter 的 `metadata.clawdbot.version` 为当前 skill 真实版本。\n\n### B.1 背景\n\nv7.0 Phase 2 跑题事故显示：当 `node.content_hint` 为空时，LLM 写作完全依赖章节标题推断上下文，导致 LLM 写出通用 MBA 论文（\"数字经济转型\"），跑偏具体研究对象（A 公司 / vivo / 互联网分发）。\n\n### B.2 目标\n\n当 `node.content_hint` 为空时，**不**直接让 LLM 写，而是构造一个\"大纲骨架 + 反面警示\"的 prompt 约束，确保不跑题。\n\n### B.3 实施方案\n\n修改 `scripts/context_builder.py` 的 `build_prompt_package()` 函数：\n\n```python\n# 现有逻辑\ncontent_hint = current.get(\"content_hint\", \"\").strip()\n\n# v2.x.x 新增（v7.0 跑题事故修复）：当 content_hint 为空时，注入大纲骨架 + 反面警示\nif not content_hint and state:\n outline_skeleton = _build_outline_skeleton(state, node_id)\n paper_subject = _extract_paper_subject(paper_name, state)\n warning_block = _build_no_runoff_warning(paper_subject)\n content_hint = f\"{warning_block}\\n\\n{outline_skeleton}\"\n\npackage = { ..., \"content_hint\": content_hint, ... }\n```\n\n#### B.3.1 新增辅助函数\n\n```python\ndef _extract_paper_subject(paper_name: str, outline_state: Optional[Dict] = None) -> str:\n \"\"\"提取论文主题描述（用于 warning 主题锁定）\n\n 策略：\n 1. 优先从 outline_state[\"outline_tree\"][\"metadata\"][\"paper_title\"] 读\n 2. 否则从 paper_name 去掉版本号后缀\n 3. 兜底返回 paper_name\n \"\"\"\n if outline_state:\n try:\n title = outline_state.get(\"outline\", {}).get(\"outline_tree\", {}).get(\"metadata\", {}).get(\"paper_title\")\n if title and title.strip():\n return title.strip()\n except Exception:\n pass\n import re as _re\n subject = _re.sub(r'(_v\\d+(?:\\.\\d+)*|_final|_\\d{8}_\\d{6})+$', '', paper_name)\n return subject if subject else paper_name\n\n\ndef _build_outline_skeleton(outline_state: Dict, target_node_id: str) -> str:\n \"\"\"构造论文大纲骨架\"\"\"\n try:\n nodes = outline_state.get(\"outline\", {}).get(\"outline_tree\", {}).get(\"nodes\", [])\n except Exception:\n return \"\"\n lines = [\"【论文完整大纲（用于提供上下文）】\", \"\"]\n for n in nodes:\n if n.get(\"is_virtual\"):\n continue\n level = n.get(\"level\", 2)\n prefix = \"#\" * level\n lines.append(f\"{prefix} {n['id']} {n.get('title', '')}\")\n lines.append(\"\")\n lines.append(\"【你正在写的节点】\")\n target = next((n for n in nodes if n.get(\"id\") == target_node_id), None)\n if target:\n lines.append(f\"→ {target.get('title', target_node_id)}（{target_node_id}）\")\n return \"\\n\".join(lines)\n\n\ndef _build_no_runoff_warning(paper_subject: str = \"本研究主题\") -> str:\n \"\"\"反面警示：明确禁止跑题\n\n paper_subject: 论文研究对象描述（建议从 outline metadata.paper_title 取）\n \"\"\"\n return (\n f\"⚠️ 主题锁定：本论文研究对象是「{paper_subject}」。\\n\"\n \"- ✅ 围绕论文具体研究对象的真实业务场景、技术路线、客户/竞争格局等具体实体\\n\"\n \"- ✅ 引用与论文主题相关的权威数据源（行业报告 / 学术文献 / 公司财报）\\n\"\n \"- ❌ 严禁写成通用 MBA 模板论文（如「数字经济 / 企业数字化转型 / 战略管理一般性理论」）\\n\"\n \"- ❌ 严禁「党的二十大报告提出…」这类脱离论文研究主题的泛泛话语\\n\"\n \"- ❌ 严禁用「企业四要素模型 / 波特钻石模型」等通用教科书内容代替研究主题的具体业务场景\"\n )\n```\n\n#### B.3.2 关键设计要点\n\n1. **不破坏现有 `content_hint` 非空的路径**：只有当 hint 为空时才插入骨架\n2. **token 成本低**：大纲骨架 < 1 KB，比塞全文 content（100 KB+）省得多\n3. **覆盖完整**：即使 50 个节点 hint 全空，prompt 里仍有大纲骨架明确\"我在写论文 X 章节 Y\"\n4. **反面警示**：LLM 习惯正面 prompt，加\"❌ 严禁\"反向约束效果更好\n\n### B.4 测试用例\n\n```python\ndef test_content_hint_empty_should_use_skeleton():\n \"\"\"given: node.content_hint = '' when: build_prompt_package then: package['content_hint'] 含大纲骨架 + 反面警示\"\"\"\n pass\n\ndef test_content_hint_present_should_unchanged():\n \"\"\"given: node.content_hint = 'A公司2024年...' when: build_prompt_package then: package['content_hint'] == 原 hint\"\"\"\n pass\n```\n\n### B.5 验收标准\n\n- [x] `_build_outline_skeleton` 输出 < 1500 字（实测 1281 字符）\n- [x] `_build_no_runoff_warning` 输出含至少 3 个 ❌ 禁止项（实测 3 个）\n- [x] 现有非空 hint 路径 PASS（7.2 节点回归通过）\n- [x] Phase 2 跑 1 个节点，验证 prompt 含研究主题关键词（ch1 节点验证通过）\n- [x] 完整 content_hint < 2500 字（实测 1566 字符）\n- [x] 警告块参数化（_build_no_runoff_warning 接受 paper_subject 参数，不再硬编码 A 公司）\n\n### B.6 已完成行动\n\n- [x] 代码实施（context_builder.py + 3 个新函数 + 1 段 fallback 逻辑）\n- [x] 单元级验收（5+1 项 全部通过）\n- [x] 文档同步（SKILL.md 附录 B 代码块与实际代码一致）\n- [ ] CHANGELOG.md 同步（待 v2.0.7 升级时补充）\n- [ ] README.md 改进章节（待 v2.0.7 升级时补充）\n- [ ] ClawHub publish（待 v2.0.7 升级时发布）\n\n数据来源声明：本方案生成于 2026-06-29 运营者对话，2026-06-30 完成 P0 修复。\n\nFile v2.1.2-beta.1:references/loop-design.md\n\n# Loop 设计说明（v1.7）\n\n> 本文档解释 MBA Thesis Workflow v1.7 引入的 **Loop Agent 架构思想**——为什么要在传统多阶段状态机上\"加 Loop 元素\"，以及如何落地。\n\n---\n\n## 一、为什么引入 Loop 思想？\n\n### 1.1 传统多阶段工作流的问题\n\nMBA 论文写作（v1.6 及之前）是一个**线性多阶段流程**：\n```\nPhase 1 → Phase 2 → Phase 2.5 → Phase 3 → Phase 3.5 → Phase 4 → Phase 5 → Phase 5.1 → Phase 5.2\n```\n\n**痛点**：\n- ❌ 每个 Phase 之间需要**用户手动 trigger**（体验差、效率低）\n- ❌ 审核是**单向线性**（写→审→改→过），没有\"重审直到通过\"的闭环\n- ❌ 规范是写在 SKILL.md 里**靠 Agent 自觉**，没有自动化校验\n- ❌ 失败恢复是**手动打回**（\"返回 Phase 2 重写\"），没有自动重试\n\n### 1.2 Loop Agent 思想的核心价值\n\n**AI Agent Loop**（ReAct / OpenAI Agents SDK）的核心是 **\"感知 → 思考 → 行动 → 观察\"** 的循环，并具备：\n- 自我纠正（self-correction）\n- 自动化工具调用\n- 明确终止条件\n- Human-in-the-loop（关键决策点确认）\n- Guardrails（输入输出校验）\n\n**应用到 MBA 论文工作流**：\n- 现状已经是\"半 Loop 化\"（状态文件、人工门槛、审核机制）\n- 但**缺乏显式的 Loop 编排**和**自动化校验**\n- v1.7 在保留主流程的前提下，**显式声明 5 个 Loop 元素**\n\n### 1.3 不是\"完全 Loop 化\"的理由\n\n**为什么不做\"全自动 Loop Agent\"？**\n\n| 因素 | 说明 |\n|------|------|\n| **高 stakes** | MBA 论文关系到用户年底毕业，错版交付给导师代价极大 |\n| **学术质量不可妥协** | LLM 可能幻觉、跑偏，学术逻辑链需要人工把关 |\n| **决策需要人** | 题目选择、研究方向、整合方案、最终交付——都是用户决策 |\n| **监管/审计** | 导师可能问\"这章怎么来的\"，需要明确的人工审查节点 |\n\n**结论**：采用**多阶段状态机 + 内部 Loop 元素**的混合架构，而非纯 Loop Agent。\n\n---\n\n## 二、5 个 Loop 元素详解\n\n### 2.1 Orchestrator Loop（自动推进）\n\n**目标**：取代\"每步手动 trigger\"。\n\n**实现**：\n- 每 Phase 完成后，Orchestrator 读取 `*_任务状态.json`\n- 根据状态文件 + Guardrails 校验结果，**自动判断下一步**：\n - 通过 → 进入下一 Phase\n - 缺条件 → 提示用户补\n - 出错 → 自动打回当前 Phase 重做\n\n**终止条件**：全部 7 个 Phase 状态都是 `completed`。\n\n**最大重试**：3 次，超过则强制 Human-in-the-loop。\n\n**伪代码**（详见 SKILL.md）：\n```python\ndef decide_next_action(state):\n if state[\"phase\"] == \"Phase 3.5 完成\" and has_p0_issues(state):\n return \"Phase 4 修订（修订后自动重审，最多 3 轮）\"\n ...\n```\n\n### 2.2 Phase 内部自检 Loop（Observe → Think → Act → Verify）\n\n**目标**：每个 Phase 内部遵循四步循环，确保输出符合规范。\n\n**通用模板**：\n```\n1. Observe —— 读取上一阶段产出 + 状态文件\n ↓\n2. Think —— 判断本 Phase 任务清单\n ↓\n3. Act —— 执行 spawn / exec / 文件写入\n ↓\n4. Verify —— 运行 Guardrails 脚本校验\n ↓\n 通过？→ 退出 Phase，更新状态\n 不通过？→ 回到 Step 2 修订（最多 3 次）\n```\n\n**为什么不直接用 OpenClaw 的 Agent Loop？**\n\n- OpenClaw 的 Agent Loop 适合**单次任务**（写一篇文章、调一个 API）\n- MBA 论文是**多阶段长任务**，需要**持久状态**（状态文件）+ **跨 Phase 协调**（状态机）\n- Loop 元素是在每个 Phase 内部\"借用\" Agent Loop 的思想，不破坏主流程的状态边界\n\n### 2.3 审核 Loop（多轮闭环）\n\n**目标**：把审核做成\"审→改→重审→...→通过\"的闭环。\n\n**状态机**：\n```\n[Phase 3 快速审核] → 输出报告\n ↓\n[Phase 3.5 深度评审] → P0/P1/P2 分级\n ↓\n 有 P0？── 是 → [Phase 4 修订] → 重审（仅审 P0）→ ...\n ↑ │\n └──── 连续 2 轮无新 P0 ─────────┘\n │\n 无 P0（仅 P1/P2）──→ [Phase 4 整合] → [Phase 5 终审] → 退出\n```\n\n**关键设计**：\n- **仅重审 P0**：避免 LLM 上下文爆炸（不重复扫描全文）\n- **连续 2 轮无新 P0**：视为通过（容忍小波动）\n- **超过 3 轮强制人工决策**：防止死循环\n\n**重审报告命名**：`审核报告_Phase3.5_v{轮次}.md`，归档保留。\n\n### 2.4 Guardrails 校验（自动化规范检查）\n\n**目标**：把\"应该遵守的规范\"做成自动化脚本，Agent 不再靠自觉。\n\n**脚本**：`scripts/loop_self_check.py`（v1.7 新增）\n\n**10 项校验**：\n1. 章节完整性（7 章齐全）\n2. 字数门槛（每章 ≥ 100 行）\n3. 参考文献存在\n4. 无 `## 第X章` 混合格式\n5. 无 `**正文加粗**` 残留\n6. 引用完整性（作者，年份）模式\n7. 三线表无竖线\n8. 表格标题在表上方\n9. 无合并残留（`===END===`）\n10. 核心章节关键词（第5章战略/第6章实施）\n\n**使用方式**：\n```bash\n# 单文件校验\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# Phase 级别校验\npython3 scripts/loop_self_check.py --phase 2 --workspace ~/.openclaw/workspace/\n\n# JSON 报告（用于自动化）\npython3 scripts/loop_self_check.py --file 论文_xxx.md --json\n```\n\n**失败处理**：\n- 软错误（可自动修复）→ 自动修复并重试\n- 硬错误（需 Agent 决策）→ 打回当前 Phase\n- 累计 3 次失败 → 强制 Human-in-the-loop\n\n### 2.5 Verification Loop（Word 输出校验）\n\n**目标**：Word 输出后自动校验格式，避免错版交付。\n\n**实现**：\n```bash\npython3 scripts/loop_self_check.py --file 论文_xxx_v4.0_终稿.docx --verify-docx\n```\n\n**校验项**：\n- 分页符（每章后）\n- 表格数量\n- 段落数量（≥ 500 段）\n- 标题层级（字体/字号）\n- 行距 20 磅\n- 三线表样式\n\n**失败处理**：\n- 软错误（脚本可修复）→ 自动修复并重新生成\n- 硬错误（数据问题）→ 提示用户并打回 Phase 4\n\n---\n\n## 三、终止条件与边界保护\n\n### 3.1 最大重试机制\n\n每个 Loop 都有**最大重试次数**，防止\"无限循环\"：\n\n| Loop 类型 | 最大重试 | 超过后行为 |\n|----------|---------|-----------|\n| Orchestrator Loop | 3 次 | 强制 Human-in-the-loop |\n| Phase 内部自检 Loop | 3 次 | 强制 Human-in-the-loop |\n| 审核 Loop | 3 轮 | 强制 Human-in-the-loop |\n| Verification Loop | 2 次 | 强制 Human-in-the-loop |\n\n**为什么不设更多？**\n- 超过 3 次仍未通过 → 说明问题超出 Loop 自动化能力\n- 必须让用户决策（继续 / 调整方向 / 接受当前版本）\n\n### 3.2 Human-in-the-loop 检查点\n\n以下节点**必须**用户确认，不能由 Loop 自动跳：\n\n| 检查点 | 确认内容 | 不确认的后果 |\n|-------|---------|------------|\n| **Phase 1 末尾** | 写作任务书（题目/公司映射/大纲） | 方向错了全白做 |\n| **Phase 2.5 末尾** | 章节内容是否符合预期 | 跑偏了审完也白审 |\n| **Phase 4 末尾** | 整合方案是否接受 | 整合错了质量更差 |\n| **Phase 5.2 末尾** | Word 文档是否符合预期 | 错版交付给导师 |\n\n**设计哲学**：\n- 流程性、规则性、可自动化的 → Loop 处理\n- 战略性、决策性、需要人类判断的 → 人工处理\n\n### 3.3 状态文件机制（持久化）\n\n`论文_{题目}_任务状态.json` 是 Loop 之间的\"记忆\"：\n\n```json\n{\n \"paper\": \"A公司互联网分发业务竞争战略研究\",\n \"version\": \"v1.0\",\n \"phase\": \"Phase 3.5\",\n \"started_at\": \"2026-06-12 07:00\",\n \"last_updated\": \"2026-06-12 08:30\",\n \"review_loop\": {\n \"current_round\": 2,\n \"p0_fixed\": [\"P0-1\", \"P0-2\"],\n \"p0_pending\": [\"P0-3\"],\n \"max_rounds\": 3\n },\n \"chapters\": {\n \"chapter1_2_7\": {\"status\": \"completed\", \"file\": \"...\", \"lines\": 850},\n \"chapter3_4\": {\"status\": \"completed\", \"file\": \"...\", \"lines\": 1200},\n \"chapter5_6\": {\"status\": \"completed\", \"file\": \"...\", \"lines\": 1100}\n }\n}\n```\n\n**作用**：\n- Orchestrator Loop 读取状态判断下一步\n- Review Loop 读取 `current_round` 决定是否重审\n- 中断后恢复（session 重启后从状态文件继续）\n\n---\n\n## 四、与 OpenClaw Agent Loop 的对应\n\n| OpenClaw / Loop Agent 概念 | MBA Skill v1.7 实现 |\n|--------------------------|---------------------|\n| **Agent loop**（自动推进） | Orchestrator Loop |\n| **Tool invocation** | sessions_spawn / exec / hermes chat |\n| **Self-correction** | 审核 Loop（Phase 3 + 3.5 + 修订） |\n| **Guardrails** | loop_self_check.py 脚本（10 项校验） |\n| **Human-in-the-loop** | Phase 1/2.5/4 强制用户确认 |\n| **Sessions**（持久状态） | `*_任务状态.json` |\n| **Tracing**（追踪） | 各 Phase 输出文件 + 状态文件 |\n| **Verification** | Verification Loop（Word 格式校验） |\n| **MCP tools** | multi-search-engine / academic-research / arxiv-search-collector |\n| **Sandbox** | sessions_spawn 子 agent 隔离执行 |\n\n**关键差异**：\n- **OpenClaw Agent Loop**：单次任务内循环（适合写一篇文章、调一个 API）\n- **MBA Skill v1.7**：**多阶段状态机 + 每阶段内部 Loop**（适合长任务、有明确状态边界的复杂工作）\n\n---\n\n## 五、未来扩展方向\n\n### 5.1 短期（v1.8 - v1.9）\n\n- [ ] **Orchestrator Loop 完整实现**：把伪代码变成可执行的 `orchestrator.py`\n- [ ] **状态文件自动生成**：每 Phase 启动时自动创建/更新 `*_任务状态.json`\n- [ ] **Guardrails 软错误自动修复**：例如 `**正文加粗**` 自动去除、`## 第X章` 自动纠正\n- [ ] **审核 Loop 报告对比工具**：自动 diff 两轮审核报告，识别\"新增 P0\"\n\n### 5.2 中期（v2.0）\n\n- [ ] **多论文并行支持**：用状态文件隔离，同时跑多篇论文\n- [ ] **审核报告自动归档**：所有 Phase 3.5 报告统一管理，支持历史回溯\n- [ ] **导师反馈 Loop**：接入导师的批注，自动生成\"导师反馈 → 修订 → 复审\"闭环\n- [ ] **Word 模板自定义**：支持不同学校（南大、复旦、交大等）的论文模板\n\n### 5.3 长期（v3.0+）\n\n- [ ] **AI 辅助选题**：Phase 1 前置 Loop，根据用户方向自动推荐题目 + 大纲\n- [ ] **文献自动追踪**：论文写作过程中自动追踪相关领域新论文\n- [ ] **答辩 PPT 自动生成**：基于终稿自动生成答辩 PPT\n- [ ] **跨论文知识库**：所有论文的素材、参考文献、模板沉淀为可复用知识库\n\n---\n\n## 六、参考资料\n\n- **ReAct 论文**（arXiv:2210.03629）：https://arxiv.org/abs/2210.03629\n- **OpenAI Agents SDK Agent Loop 概念**：https://openai.github.io/openai-agents-python/\n- **OpenAI Operator / CUA 介绍**：https://openai.com/index/introducing-operator/\n- **Anthropic Computer Use 文档**：（抓取失败，可参考 OpenAI Operator 的设计思路）\n\n---\n\n> **维护者**：MBA Skill v1.7 引入，最后更新 2026-06-12。\n> **反馈**：发现 Loop 元素设计问题，提交 issue 或直接修订本文档。\n\nFile v2.1.2-beta.1:thesis-docx-export/references/checklist.md\n\n# MBA 论文学术规范检查清单（v1.7）\n\n> 本文档是 **Guardrails 校验项**的人工对照清单。\n> 自动化脚本：`scripts/loop_self_check.py`\n> 使用方式：每个 Phase 退出前对照本清单 + 运行脚本，确保 100% 通过。\n\n---\n\n## 一、格式维度（18 项）\n\n### 1.1 封面\n\n- [ ] 包含：学校代码\n- [ ] 包含：分类号\n- [ ] 包含：密级\n- [ ] 包含：UDC\n- [ ] 包含：论文题目\n- [ ] 包含：作者姓名\n- [ ] 包含：专业\n- [ ] 包含：研究方向\n- [ ] 包含：导师\n- [ ] 包含：答辩日期\n\n### 1.2 原创性声明\n\n- [ ] 包含声明正文\n- [ ] 包含签名栏\n- [ ] 包含日期\n- [ ] 位置：封面之后、摘要之前\n\n### 1.3 中文摘要\n\n- [ ] 标题\"摘要\"两字间空两格\n- [ ] 标题：黑体 16 磅加粗居中，单倍行距\n- [ ] 标题段前 24 磅、段后 18 磅\n- [ ] 内容：宋体 12 磅（小四）\n- [ ] 内容：行距 20 磅，段前段后 0 磅\n- [ ] **内容字数 ≥ 800 字** ⚠️\n- [ ] 关键词 3-5 个\n- [ ] 关键词格式：分号分隔，\"关键词\"三字加粗\n\n### 1.4 英文摘要\n\n- [ ] 标题\"Abstract\"（Arial 16 磅加粗居中）\n- [ ] 内容：Times New Roman 12 磅\n- [ ] 行距 20 磅\n- [ ] 关键词 3-5 个，\"Key Words\"加粗\n- [ ] 中英文关键词一一对应\n\n### 1.5 目录\n\n- [ ] 标题\"目录\"两字间空两格（黑体 16 磅加粗居中）\n- [ ] 从绪论开始列出\n- [ ] 一级节：宋体 12 磅加粗\n- [ ] 二级节：仿宋 10.5 磅\n- [ ] 页码右对齐\n- [ ] 纳入 1-3 级标题\n\n### 1.6 正文各章标题\n\n- [ ] 格式：`# 第X章 ×××`\n- [ ] 黑体 16 磅加粗居中\n- [ ] 单倍行距，段前 24 磅、段后 18 磅\n- [ ] 章序号与章名称之间空两格\n- [ ] **每章另起一页（分页符）** ⚠️\n\n### 1.7 标题层级\n\n- [ ] 一级节：`## 1.2 ×××`（黑体 14 磅）\n- [ ] 二级节：`### 1.2.1 ×××`（黑体 13 磅）\n- [ ] 三级节：`### （1）×××`（宋体 12 磅）\n- [ ] 禁止使用 `## 第X章` 混合格式 ⚠️\n- [ ] 禁止使用 `### 第X.X` 混合格式\n\n### 1.8 正文段落\n\n- [ ] 宋体 12 磅（英文 Times New Roman 12 磅）\n- [ ] 两端对齐，首行左缩进 2 个汉字符\n- [ ] 段前段后 0 磅\n- [ ] **行距 20 磅** ⚠️\n- [ ] **正文中无 `**加粗**` 强调术语** ⚠️\n\n### 1.9 图号图题\n\n- [ ] 图号 + 图题置于图**下方**\n- [ ] 宋体 10.5 磅加粗居中\n- [ ] 单倍行距，段前 6 磅、段后 12 磅\n- [ ] 图注左缩进两字\n- [ ] 图中文字宋体 10.5 磅\n\n### 1.10 表号表题\n\n- [ ] 表号 + 表题置于表**上方**\n- [ ] 宋体 10.5 磅加粗居中\n- [ ] 单倍行距，段前 6 磅、段后 6 磅\n- [ ] 表注左缩进两字\n- [ ] 表格标题不应加粗\n\n### 1.11 表格\n\n- [ ] **三线表**（顶线、表头底线、底线）⚠️\n- [ ] 无竖线\n- [ ] 表格内无 `**加粗**` 残留\n- [ ] 表头与数据行分明\n\n### 1.12 图表编号\n\n- [ ] 阿拉伯数字分章依序连续编码\n- [ ] 格式示例：\"图 1.1\"、\"表 3.2\"\n- [ ] 引用格式自然句式：\"如图 1.1 所示\"（非 `**图 1.1**` 加粗）\n\n### 1.13 注释\n\n- [ ] **页下注**（非上标形式）⚠️\n- [ ] 编号：①②③……连续\n- [ ] 不得使用上标加序号\n\n### 1.14 参考文献\n\n- [ ] 正文引用：**作者年制**（不得使用上标加序号）⚠️\n- [ ] 文后\"参考文献\"标题左对齐\n- [ ] **中英文分编** + **字母排序** ⚠️\n- [ ] 中文：宋体小四号全角标点\n- [ ] 英文：Times New Roman 小四号\n- [ ] 英文作者姓前名后缩写\n- [ ] 杂志名书名斜体\n- [ ] 同一作者同年多篇加 a/b/c 区分\n\n### 1.15 页码\n\n- [ ] 前置部分（封面/声明/摘要/目录）：罗马数字\n- [ ] 正文部分（从绪论起）：阿拉伯数字\n\n### 1.16 附录\n\n- [ ] 标题格式同章标题\n- [ ] 内容格式同正文\n- [ ] 大写字母 A/B/C 编序号（如\"附录 A\"）\n- [ ] 只有一个附录名为\"附录\"不编号\n- [ ] 图表编号与正文分开（如\"图 A.1\"）\n\n### 1.17 致谢\n\n- [ ] 标题\"致谢\"两字间空两格\n- [ ] 格式同章标题\n- [ ] 内容格式同正文\n\n### 1.18 写作语法\n\n- [ ] 正文段落中无 `**xxx**` 加粗术语 ⚠️\n- [ ] 列表项小标题用 `###` 升为正式节标题\n- [ ] 表格标题行是普通段落文字\n- [ ] 引用图表用自然句式\n- [ ] 过渡句式自然，不大量使用 `**xxx领域**` 加粗术语\n\n---\n\n## 二、大纲维度（2 项）\n\n- [ ] 每章内容不超出原定大纲范围（超出章节标★）\n- [ ] **每章 ≥ 2 节，每节 ≥ 2 点，每点 ≥ 5 行** ⚠️\n\n---\n\n## 三、内容准确性维度（2 项）\n\n- [ ] 每引用一个理论/数据必须标注来源（无来源结论标⚠️）\n- [ ] 正文数据前后无矛盾（矛盾处标⚠️）\n\n---\n\n## 四、查重风险维度（1 项）\n\n- [ ] **连续 ≥ 30 字与参考文献重合标🔴，需 paraphrase** ⚠️\n\n---\n\n## 五、学术规范维度（6 项）\n\n- [ ] **引用标注完整率必须达到 100%** ⚠️\n- [ ] 术语首次出现须全称 + 后续简称\n- [ ] 正文中文格式：1 人 / 2 人 / 3+ 人\n- [ ] 正文英文格式：1 人 / 2 人 / 3+ 人\n- [ ] 文后中文格式：期刊 / 专著 / 论文集\n- [ ] 文后英文格式：作者姓写在前名缩写在后，杂志名书名斜体\n\n---\n\n## 六、章节完整性（10 项 Guardrails 自动化校验项）\n\n> 以下 10 项由 `scripts/loop_self_check.py` 自动校验。\n\n- [ ] **章节完整性**：必须包含 `# 第1章` 到 `# 第7章` 全部 7 章\n- [ ] **字数门槛**：每章 ≥ 100 行（全文 ≥ 700 行）\n- [ ] **参考文献存在**：包含 `## 参考文献` 标题\n- [ ] **标题层级**：无非法的 `## 第X章` 混合格式\n- [ ] **正文加粗**：无 `**xxx**` 残留\n- [ ] **引用完整性**：至少 10 处 `(作者，年份)` 模式\n- [ ] **三线表**：无多余竖线\n- [ ] **表格标题**：表格标题在表上方\n- [ ] **合并残留**：无 `===END===` 等残留标识\n- [ ] **核心章节关键词**：\n - 第 5 章包含：战略选择 / 竞争战略 / 差异化 / 集中化 / 成本领先 / QSPM\n - 第 6 章包含：实施 / 保障 / 组织 / 人才 / 财务 / KPI / 考核\n\n---\n\n## 七、Word 输出校验（Verification Loop）\n\n> Word 文档输出后由 `loop_self_check.py --verify-docx` 自动校验。\n\n- [ ] **分页符**：每章后有分页符\n- [ ] **三线表**：表格为三线表样式\n- [ ] **标题层级**：黑体 16/14/13 磅\n- [ ] **正文行距**：20 磅\n- [ ] **加粗已过滤**：无 `**残留**`\n- [ ] **参考文献分编**：中文 + 英文分两块\n- [ ] **段落数量**：≥ 500 段\n- [ ] **表格数量**：> 0\n\n---\n\n## 八、Phase 退出门禁\n\n每个 Phase 退出前必须 100% 通过本清单的对应项 + Guardrails 脚本：\n\n| Phase | 必查项 | 退出条件 |\n|-------|--------|---------|\n| **Phase 1** | 一、1.18 + 二、 | 写作任务书用户签收 |\n| **Phase 2** | 一、全部 + 三、 + 六、 | 全部 7 章完成 + Guardrails 100% |\n| **Phase 2.5** | 六、第 10 项（核心章节关键词） | 用户确认章节内容 |\n| **Phase 3** | 一、全部 | 审核报告 H + O 完整 |\n| **Phase 3.5** | 一、二、三、四、五、 | P0/P1/P2 分级完整 |\n| **Phase 4** | 一、全部 + 六、 | 整合版 Guardrails 100% |\n| **Phase 5** | 一、全部 + 七、 | Word 格式 100% |\n| **Phase 5.1** | （去 AI 味） | 差异报告生成 |\n| **Phase 5.2** | 七、 | Word 文档 + 邮件发送 |\n\n---\n\n## 九、违规等级与处理\n\n| 等级 | 标记 | 处理方式 |\n|------|------|---------|\n| 🔴 P0 | 致命错误（章节缺失、参考文献缺失、合并残留） | **必须修复**，否则阻断 Phase 推进 |\n| 🟡 P1 | 严重问题（标题层级错误、加粗残留、字数不足） | **必须修复**，累计 3 项打回 Phase |\n| ⚠️ P2 | 一般问题（个别引用缺失、图表编号不规范） | **建议修复**，可在 Phase 5 终审前统一修订 |\n| 💡 建议 | 优化项（措辞、过渡句式） | **可选**，可放入 Phase 5.1 去 AI 味 |\n\n---\n\n## 十、参考规范来源\n\n- 《南京大学研究生学位论文格式规范》（最新版）\n- 《GB/T 7714-2015 文后参考文献著录规则》\n- MBA Skill v1.6 既有规范\n- Loop Self-Check Script v1.7\n\n---\n\n> **维护者**：MBA Skill v1.7 引入，最后更新 2026-06-12。\n> **使用建议**：打印此清单，每 Phase 退出前对照打勾。\n\nFile v2.1.2-beta.1:scripts/phase_manager/DESIGN.md\n\n# Phase Manager 模块设计方案\n\n> 创建时间：2026-06-30\n> 状态：已设计，待实现\n> 目录：`scripts/phase_manager/`\n\n---\n\n## 一、模块定位与目标\n\n### 1.1 解决的问题\n\n当前 HIL 节点将 Phase 产出直接渲染到 chat 窗口，存在三大问题：\n1. **信息截断** — 大论文数十KB内容无法完整返回\n2. **上下文浪费** — token 被正文消耗，核心元数据被淹没\n3. **用户无法细改** — 只能整体接受/拒绝，无法局部编辑\n\n### 1.2 模块定位\n\n每个 Phase 的**数据中枢**：\n- 管理输入/输出文件的生命周期\n- 提供门禁校验（准入/准出）\n- 生成 HIL 消息（只含路径+摘要，不塞正文）\n- 保证跨 Session 数据有效性\n\n**独立性强**：只依赖 Python stdlib，不依赖业务模块，可独立测试和移植。\n\n### 1.3 设计原则\n\n| 原则 | 说明 |\n|------|------|\n| 文件优先 | Phase 产出存入文件，不塞 chat |\n| 用户可编辑 | 用户可直接改文件，下一 Phase 读取新内容 |\n| 有效性保障 | 读写前做 freshness check + hash 校验 |\n| 幂等安全 | 已完成 Phase 的内容非 force 不可覆盖 |\n| 清理可控 | 中间态文件及时清理，重要产出持久化 |\n\n---\n\n## 二、目录结构\n\n```\nscripts/phase_manager/\n├── __init__.py ← 导出 PhaseManager 主类\n├── schemas.py ← 数据契约（PhaseSummary / PhaseFile / PhaseTransition）\n├── file_manager.py ← 文件生命周期管理\n├── gate_keeper.py ← 门禁校验\n├── summary_generator.py ← 摘要生成\n├── hil_renderer.py ← HIL 消息渲染\n└── DESIGN.md ← 本文档\n```\n\n---\n\n## 三、数据契约（schemas.py）\n\n### 3.1 PhaseSummary\n\n```python\n@dataclass\nclass PhaseSummary:\n phase: int # Phase 编号（1-5）\n status: str # pending | running | completed | failed | modified\n timestamp: str # ISO timestamp（最后修改时间）\n file_path: str # 产出文件路径\n content_hash: str # 内容哈希（MD5，用于检测用户是否改过）\n word_count: int # 中文字数\n chapter_count: int # 章节数\n key_metrics: Dict[str, Any] # 关键指标（见下方）\n user_modifications: bool # 用户是否手动修改过文件\n message: str # 一句话摘要\n\n # key_metrics 字段说明\n # Phase 2: {\"nodes_total\": N, \"nodes_completed\": N, \"nodes_failed\": N}\n # Phase 3: {\"p0_issues\": 0, \"p1_issues\": N, \"p2_issues\": N, \"guardrails_passed\": True}\n # Phase 3.5: 同 Phase 3\n # Phase 4: {\"integrated_word_count\": N, \"changes_applied\": N}\n # Phase 5: {\"word_count\": N, \"guardrails_passed\": True}\n```\n\n### 3.2 PhaseFile\n\n```python\n@dataclass\nclass PhaseFile:\n phase: int # Phase 编号\n content_type: str # integrated | review | summary\n file_path: str # 文件绝对路径\n hash: str # 内容哈希\n size_bytes: int # 文件大小\n created_at: str # ISO timestamp\n updated_at: str # ISO timestamp\n backup_path: Optional[str] # 备份文件路径（上一版本）\n```\n\n**content_type 说明**：\n- `integrated` — 整合版正文（.md）\n- `review` — 审核报告（.json）\n- `summary` — 结构化摘要（.json）\n\n### 3.3 PhaseTransition\n\n```python\n@dataclass\nclass PhaseTransition:\n from_phase: int # 来源 Phase\n to_phase: int # 目标 Phase\n triggered_by: str # auto | user_confirm | user_modify\n triggered_at: str # ISO timestamp\n triggered_session: str # 触发时的 session ID\n content_hash: str # 触发时的文件哈希\n gate_passed: bool # 门禁是否通过\n```\n\n### 3.4 GateResult\n\n```python\n@dataclass\nclass GateResult:\n passed: bool # 是否通过\n phase: int # 检查的 Phase\n checks: Dict[str, Tuple[bool, str]] # {check_name: (passed, detail)}\n blocking_issues: List[str] # 阻塞性问题列表\n\n def summary(self) -> str:\n \"\"\"生成人类可读的 gate 结果摘要\"\"\"\n```\n\n---\n\n## 四、文件命名规范\n\n| 文件名模式 | 示例 | 用途 |\n|-----------|------|------|\n| `_phase{N}_{integrated/review/summary}.md` | `_phase3_integrated.md` | Phase N 整合版正文 |\n| `_phase{N}_{integrated/review/summary}.json` | `_phase3_review.json` | Phase N 审核报告/摘要 |\n| `_phase{N}_{integrated/review/summary}.md.bak` | `_phase3_integrated.md.bak` | 上一版本备份 |\n| `_phase{N}.lock` | `_phase3.lock` | 写入锁（防并发） |\n| `_phase{N}_summary.json` | `_phase3_summary.json` | PhaseSummary 结构化摘要 |\n| `_transition.json` | `_transition.json` | Phase 流转记录 |\n\n---\n\n## 五、核心类实现规格\n\n### 5.1 PhaseFileManager\n\n**职责**：文件生命周期管理（CRUD + 版本控制 + 清理）\n\n```python\nclass PhaseFileManager:\n FRESHNESS_THRESHOLD_HOURS = 48 # 文件新鲜度阈值\n WORKSPACE_BASE = \"~/.openclaw/workspace\" # 工作区根目录\n\n def __init__(self, paper_name: str, workspace: str = None):\n self.paper_name = paper_name\n self.workspace = workspace or os.path.join(\n os.path.expanduser(WORKSPACE_BASE), paper_name\n )\n os.makedirs(self.workspace, exist_ok=True)\n\n # ---- 路径计算 ----\n def get_file_path(self, phase: int, content_type: str, ext: str = None) -> str:\n \"\"\"\n 返回指定 Phase + 类型的目标文件路径。\n ext 默认为 md（integrated）或 json（review/summary）。\n \"\"\"\n\n # ---- 生命周期：保存 ----\n def save_content(self, phase: int, content_type: str, content: str,\n create_backup: bool = True) -> Dict[str, Any]:\n \"\"\"\n 保存内容。\n\n 流程：\n 1. 计算 content_hash\n 2. 检查是否有内容变化（hash 对比）\n 3. 有变化且 create_backup=True → 自动备份旧版本到 .bak\n 4. 写入新内容（带 .lock 保护）\n 5. 更新 state 中的 hash 记录\n 6. 校验文件完整性\n\n 返回：{\n ok: bool,\n hash: str,\n backup_path: Optional[str],\n size_bytes: int,\n changed: bool,\n error: Optional[str]\n }\n \"\"\"\n\n # ---- 生命周期：读取 ----\n def load_content(self, phase: int, content_type: str) -> Optional[str]:\n \"\"\"\n 读取指定文件内容。\n 文件不存在或校验失败 → 返回 None\n \"\"\"\n\n # ---- 新鲜度校验 ----\n def is_fresh(self, phase: int, content_type: str) -> bool:\n \"\"\"\n 检查文件是否新鲜：\n 1. 文件存在\n 2. 修改时间在 FRESHNESS_THRESHOLD_HOURS 内\n 3. content_hash 与 state 中记录一致\n \"\"\"\n\n def validate_before_read(self, phase: int, content_type: str) -> Dict:\n \"\"\"\n 读取前校验：\n - 文件存在\n - 未过期\n - hash 一致\n\n 返回：{ok: bool, error: Optional[str], fresh: bool, hash_changed: bool}\n \"\"\"\n\n # ---- 用户修改检测 ----\n def detect_user_modification(self, phase: int, content_type: str) -> bool:\n \"\"\"\n 通过 content_hash 对比，检测用户是否手动修改了文件。\n 流程：\n 1. 读取当前文件的真实 hash\n 2. 对比 state 中记录的 hash\n 3. 不一致 → 用户改过\n \"\"\"\n\n # ---- 版本控制 ----\n def backup_exists(self, phase: int, content_type: str) -> bool:\n \"\"\"检查是否有 .bak 备份版本\"\"\"\n\n def restore_backup(self, phase: int, content_type: str) -> Dict:\n \"\"\"\n 恢复上一备份版本。\n 返回：{ok: bool, restored_path: str}\n \"\"\"\n\n # ---- 清理 ----\n def cleanup_intermediate(self, phase: int,\n keep_types: List[str] = None) -> Dict:\n \"\"\"\n 清理指定 Phase 的中间文件。\n\n keep_types 默认：[\"integrated.md\", \"review.json\", \"summary.json\"]\n 删除：.tmp / .bak / .lock 等临时文件\n\n 返回：{ok: bool, deleted: [file_paths]}\n \"\"\"\n\n def cleanup_all_intermediates(self) -> Dict:\n \"\"\"\n 清理所有 Phase 的中间文件（保留最终产出）。\n 用于论文完成后收尾。\n \"\"\"\n\n # ---- 写入锁（防并发）----\n def save_with_lock(self, phase: int, content_type: str,\n content: str) -> Dict:\n \"\"\"\n 写入时加锁，防止并发覆盖。\n 1. 检查 .lock 文件\n 2. 有锁 → 报错 \"文件正在被编辑，请稍后\"\n 3. 无锁 → 创建锁 → 写入 → 删除锁\n 4. finally 确保锁释放\n \"\"\"\n```\n\n### 5.2 PhaseGateKeeper\n\n**职责**：Phase 流转门禁校验（准入/准出）\n\n```python\nclass PhaseGateKeeper:\n # 通用门禁规则\n GATE_RULES = {\n \"min_word_count\": 1000, # 最小字数\n \"max_word_count\": 200000, # 最大字数（异常检测）\n \"chapter_count\": 7, # 章节数要求\n \"freshness_hours\": 48, # 文件新鲜度\n }\n\n def __init__(self, paper_name: str):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name)\n\n # ---- 准入检查（进入 Phase N 前）----\n def pre_enter_check(self, target_phase: int) -> GateResult:\n \"\"\"\n 检查是否可以进入 target_phase。\n\n 规则：\n - Phase 2 前：Phase 1.2 大纲已确认 + Phase 1.3 已提交\n - Phase 3 前：Phase 2 全部节点 completed，无 failed\n - Phase 3.5 前：Phase 3 review 已完成\n - Phase 4 前：Phase 3.5 收敛（连续 2 轮无新 P0）\n - Phase 5 前：Phase 4 guardrails 10/10 通过\n\n 返回：GateResult\n \"\"\"\n\n # ---- 准出检查（Phase N 完成前）----\n def pre_exit_check(self, current_phase: int) -> GateResult:\n \"\"\"\n 检查当前 Phase 是否满足完成条件。\n\n 规则：\n - Phase 2：节点完成率 100%，无 failed 节点\n - Phase 3：审核 loop 收敛（连续 2 轮无新 P0）\n - Phase 3.5：同 Phase 3\n - Phase 4：整合版 guardrails 10 项校验通过\n - Phase 5：Word 输出格式校验通过\n\n 返回：GateResult\n \"\"\"\n\n # ---- 通用门禁项 ----\n def check_word_count(self, phase: int, content_type: str = \"integrated\") -> Tuple[bool, str]:\n \"\"\"字数是否在合理范围\"\"\"\n\n def check_chapter_completeness(self, phase: int, content_type: str = \"integrated\") -> Tuple[bool, str]:\n \"\"\"章节是否完整（7 章）\"\"\"\n\n def check_freshness(self, phase: int, content_type: str = \"integrated\") -> Tuple[bool, str]:\n \"\"\"文件是否新鲜（48 小时内有更新）\"\"\"\n\n def check_hash_unchanged(self, phase: int, content_type: str,\n expected_hash: str) -> Tuple[bool, str]:\n \"\"\"文件 hash 是否与预期一致（检测用户修改）\"\"\"\n```\n\n### 5.3 PhaseSummaryGenerator\n\n**职责**：将 Phase 产出转化为结构化摘要\n\n```python\nclass PhaseSummaryGenerator:\n def __init__(self, paper_name: str):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name)\n\n def generate_phase_summary(self, phase: int,\n phase_result: Dict = None) -> PhaseSummary:\n \"\"\"\n 从 Phase 执行结果或文件中提取 PhaseSummary。\n\n 输入：Phase 执行结果（可能包含大量 content）\n 输出：PhaseSummary（不含正文，只有元数据）\n\n 流程：\n 1. 如果有 phase_result，直接从中提取指标\n 2. 否则，从文件读取内容并分析\n 3. 计算 word_count、chapter_count、content_hash\n 4. 组装 PhaseSummary\n \"\"\"\n\n def calculate_word_count(self, content: str) -> int:\n \"\"\"计算中文字数（不含标点、空格、英文）\"\"\"\n\n def calculate_hash(self, content: str) -> str:\n \"\"\"计算内容 MD5 哈希\"\"\"\n\n def extract_chapter_count(self, content: str) -> int:\n \"\"\"从正文中提取章节数（# 第X章 计数）\"\"\"\n\n def build_key_metrics(self, phase: int, phase_result: Dict) -> Dict:\n \"\"\"\n 根据 Phase 类型构建 key_metrics。\n\n Phase 2: {nodes_total, nodes_completed, nodes_failed, completion_rate}\n Phase 3: {p0_issues, p1_issues, p2_issues, guardrails_passed, guardrails_detail}\n Phase 3.5: 同 Phase 3\n Phase 4: {integrated_word_count, changes_applied, guardrails_passed}\n Phase 5: {word_count, guardrails_passed, docx_generated}\n \"\"\"\n```\n\n### 5.4 PhaseHILRenderer\n\n**职责**：HIL 消息渲染（只输出路径+摘要，不塞正文）\n\n```python\nclass PhaseHILRenderer:\n def __init__(self, paper_name: str):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name)\n\n def render_hil_message(self, phase: int, summary: PhaseSummary,\n next_phase: int = None,\n user_modified: bool = False) -> str:\n \"\"\"\n 渲染 HIL 消息。\n\n 输出格式（Markdown）：\n\n ✅ Phase {N} 整合完成\n\n 📄 文件：{file_path}\n 📊 字数：{word_count} 字 | 章节：{chapter_count} 章\n 🔍 审核结果：{审核摘要}\n 🛡️ Guardrails：{通过情况}\n 🕐 时间：{timestamp}\n {用户修改提示（如有）}\n\n 下一阶段：Phase {N+1}\n 操作指令：\n - [确认] → 进入 Phase {N+1}\n - [修改文件] → 直接编辑上方文件后说\"确认修改\"\n - [重新审核] → 重新跑 Phase {N} review\n \"\"\"\n\n def render_gate_failure(self, phase: int, gate_result: GateResult) -> str:\n \"\"\"\n 渲染门禁未通过的消息。\n\n 输出格式：\n\n ⚠️ Phase {N} 门禁未通过\n\n 阻塞问题：\n - {issue 1}\n - {issue 2}\n\n 请修复上述问题后重试。\n \"\"\"\n\n def render_phase_status(self, phase: int) -> str:\n \"\"\"\n 渲染 Phase 当前状态（用于 --status 查询）。\n \"\"\"\n\n def render_user_modification_warning(self, phase: int,\n old_hash: str,\n new_hash: str) -> str:\n \"\"\"\n 检测到用户修改文件时的提示。\n \"\"\"\n```\n\n### 5.5 PhaseManager（主类，Facade 模式）\n\n```python\nclass PhaseManager:\n \"\"\"\n Phase 数据管理的统一入口（Facade 模式）。\n\n 对 orchestrator 暴露简单接口，屏蔽内部复杂度。\n \"\"\"\n\n def __init__(self, paper_name: str, workspace: str = None):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name, workspace)\n self.gk = PhaseGateKeeper(paper_name)\n self.sg = PhaseSummaryGenerator(paper_name)\n self.hr = PhaseHILRenderer(paper_name)\n\n # ---- 核心流程 ----\n def save_phase_output(self, phase: int, content_type: str,\n content: str,\n key_metrics: Dict = None) -> Dict:\n \"\"\"\n 保存 Phase 产出。\n\n 1. 保存内容到文件\n 2. 生成 PhaseSummary\n 3. 保存 summary 到 _phase{N}_summary.json\n 4. 返回 {ok, file_path, summary}\n\n 用户可直接改文件，改完说\"确认\"后下一 Phase 读取。\n \"\"\"\n\n def load_phase_input(self, phase: int,\n content_type: str = \"integrated\") -> Optional[str]:\n \"\"\"\n 读取上一 Phase 的产出。\n\n 读取前做 freshness check。\n 检测到用户修改 → 在返回内容中附带 user_modified=True 标记。\n \"\"\"\n\n def pre_phase_check(self, target_phase: int) -> GateResult:\n \"\"\"\n 进入 Phase N 前的门禁检查。\n 不通过 → 返回错误，不允许进入。\n \"\"\"\n\n def pre_exit_check(self, current_phase: int) -> GateResult:\n \"\"\"\n Phase N 完成前的门禁检查。\n 不通过 → 返回错误，不允许完成。\n \"\"\"\n\n def generate_hil_message(self, phase: int,\n next_phase: int = None) -> str:\n \"\"\"\n 生成 HIL 消息（供用户确认/修改）。\n \"\"\"\n\n # ---- 状态查询 ----\n def get_phase_status(self, phase: int) -> Dict:\n \"\"\"\n 返回 Phase N 的当前状态。\n \"\"\"\n\n def get_all_phase_status(self) -> List[Dict]:\n \"\"\"\n 返回所有 Phase 的状态列表。\n \"\"\"\n\n # ---- 流转记录 ----\n def record_transition(self, from_phase: int, to_phase: int,\n triggered_by: str, session_id: str) -> Dict:\n \"\"\"\n 记录 Phase 流转。\n \"\"\"\n\n def get_last_transition(self) -> Optional[PhaseTransition]:\n \"\"\"\n 获取最近一次流转记录。\n \"\"\"\n```\n\n---\n\n## 六、orchestrator 接入方式\n\n### 6.1 Phase 3 改造示例\n\n```python\ndef orchestrate_phase3(paper_name: str) -> Dict[str, Any]:\n pm = PhaseManager(paper_name)\n\n # 1. 前置门禁检查\n gate = pm.pre_phase_check(target_phase=3)\n if not gate.passed:\n return {\n \"ok\": False,\n \"error\": \"门禁未通过\",\n \"gate_result\": asdict(gate),\n \"hil_message\": pm.hr.render_gate_failure(3, gate)\n }\n\n # 2. 执行 Phase 3 整合逻辑（原有代码不变）\n result = do_phase3_integrate_work(paper_name)\n\n # 3. 保存产出到文件\n save_result = pm.save_phase_output(\n phase=3,\n content_type=\"integrated\",\n content=result[\"content\"],\n key_metrics=result.get(\"metrics\", {})\n )\n\n # 4. 保存审核报告\n pm.save_phase_output(\n phase=3,\n content_type=\"review\",\n content=json.dumps(result[\"review_report\"], ensure_ascii=False),\n )\n\n # 5. 生成 HIL 消息（只含路径+摘要，不塞正文）\n hil_msg = pm.generate_hil_message(phase=3, next_phase=4)\n\n # 6. 记录流转\n pm.record_transition(from_phase=2, to_phase=3,\n triggered_by=\"auto\", session_id=get_current_session_id())\n\n return {\n \"ok\": True,\n \"phase\": 3,\n \"hil_message\": hil_msg, # ✅ 不塞内容\n \"file_path\": save_result[\"file_path\"],\n \"summary\": asdict(save_result[\"summary\"]),\n \"review_file_path\": \".../_phase3_review.json\",\n }\n```\n\n### 6.2 用户工作流\n\n```\nPhase 3 完成\n ↓\n用户收到 HIL 消息：\n\n✅ Phase 3 整合完成\n\n📄 文件：.../论文_xxx/_phase3_integrated.md\n📊 字数：48,320 字 | 章节：7 章\n🔍 审核结果：0 个 P0 问题，2 个 P1 问题\n🛡️ Guardrails：通过 9/10 项\n🕐 时间：2026-06-30 15:21\n\n下一阶段：Phase 4\n操作指令：\n- [确认] → 进入 Phase 4\n- [修改文件] → 直接编辑上方文件后说\"确认修改\"\n- [重新审核] → 重新跑 Phase 3 review\n\n ↓\n用户选项：\nA. 说\"确认\" → 进入 Phase 4\nB. 编辑文件 → 说\"确认修改\" → Phase 4 读取新文件\nC. 发现问题 → 编辑文件 → 触发 re-check\n```\n\n---\n\n## 七、数据有效性保障机制\n\n### 7.1 跨 Session 恢复保护\n\n每次 Phase 完成时，记录 `content_hash` + `session_id`。\n\n下一 Phase 读取时：\n- `content_hash` 变了 → 说明用户改过文件，附带 `user_modified=True`\n- `session_id` 变了 → 说明跨 session 了，需要重新确认\n\n### 7.2 文件新鲜度检查\n\n- `FRESHNESS_THRESHOLD_HOURS = 48`\n- 文件超过 48 小时未更新 → 提示用户\"文件可能过期，是否重新生成？\"\n\n### 7.3 写入锁机制\n\n写入时检查 `.lock` 文件，防止并发覆盖：\n- 有锁 → 报错\"文件正在被编辑，请稍后\"\n- 无锁 → 创建锁 → 写入 → 删除锁（finally 确保释放）\n\n### 7.4 数据清理策略\n\n| 清理时机 | 清理内容 | 保留内容 |\n|---------|---------|---------|\n| Phase N 完成，进入 N+1 | N 的 `.tmp` / `.lock` | N 的 `integrated.md` / `review.json` / `summary.json` |\n| Phase N 完成，进入 N+1 | N 的 `.bak` 备份 | N+1 的 `.bak` 保留 |\n| Phase 5 完成后 | 全部中间态 `.tmp` / `.lock` | 最终 `论文_xxx.docx` + 各 Phase summary |\n| 用户主动\"取消论文\" | 全部文件 | 无 |\n| 超期未继续（>7 天无操作） | `.tmp` / `.lock` 文件 | `integrated.md` / `review.json` |\n\n---\n\n## 八、实现优先级\n\n| 优先级 | 模块 | 依赖关系 |\n|-------|------|---------|\n| P0 | `schemas.py` | 其他所有模块的基础 |\n| P0 | `file_manager.py` | PhaseManager 依赖 |\n| P1 | `gate_keeper.py` | 依赖 schemas + file_manager |\n| P1 | `summary_generator.py` | 依赖 schemas + file_manager |\n| P2 | `hil_renderer.py` | 依赖 schemas + file_manager |\n| P2 | `__init__.py`（Facade） | 依赖以上所有 |\n| P3 | 集成到 orchestrator_v2 | PhaseManager 改造 |\n\n---\n\n## 九、待验证设计决策\n\n以下决策需要在实现过程中确认：\n\n1. **content_hash 算法**：MD5 够用还是需要 SHA256？\n2. **文件编码**：统一 UTF-8，是否需要 BOM？\n3. **大文件处理**：超过 10MB 的文件是否需要流式读写？\n4. **session_id 获取方式**：从环境变量还是 OpenClaw session 上下文？\n5. **清理策略的灵活性**：是否需要用户提供自定义 keep_types？\n\n---\n\n## 十、测试用例（实现后验证）\n\n```python\ndef test_save_and_load_roundtrip():\n \"\"\"保存后读取，内容一致\"\"\"\n pass\n\ndef test_backup_on_overwrite():\n \"\"\"覆盖写入时自动备份\"\"\"\n pass\n\ndef test_user_modification_detection():\n \"\"\"用户修改文件后，hash 变化被检测\"\"\"\n pass\n\ndef test_freshness_check():\n \"\"\"过期文件被标记为不新鲜\"\"\"\n pass\n\ndef test_concurrent_write_protection():\n \"\"\"并发写入被锁保护\"\"\"\n pass\n\ndef test_cleanup_keeps_important_files():\n \"\"\"清理只删除中间文件，保留重要产出\"\"\"\n pass\n\ndef test_pre_phase_check_blocks_invalid_transition():\n \"\"\"前置检查正确拦截非法流转\"\"\"\n pass\n\ndef test_hil_renderer_no_content_leak():\n \"\"\"HIL 消息不包含正文内容\"\"\"\n pass\n```\n\n---\n\n*文档版本：v1.0.0（2026-06-30）*\n\nFile v2.1.2-beta.1:scripts/tests/REAL_SAMPLES_README.md\n\n# 真实样本测试使用说明 (REAL_SAMPLES_README)\n\n## ⚠️ 隐私保护\n\n开题报告样本**含学生姓名 / 学号 / 研究方向 / 论文题目**，属于**敏感个人信息**。\n\n**绝对禁止**：\n- ❌ 上传任何 docx 开题报告到 GitHub 仓库\n- ❌ 在代码中硬编码样本路径或文件名（含学生姓名）\n- ❌ 在 CI/CD 公开 runner 上跑真实样本测试\n\n## 🚀 怎么跑真实样本测试\n\n`test_full_workflow.py` Part 2 在**默认情况下跳过**真实样本测试（避免误跑）。\n\n如需本地验证：\n\n### 步骤 1：准备样本目录\n\n把 docx 文件放到**本地**任意目录（不要放在 `mba-thesis-workflow` 仓库目录内）：\n\n```bash\nmkdir -p ~/private/mba-proposals\ncp /path/to/your/*.docx ~/private/mba-proposals/\n```\n\n### 步骤 2：设置环境变量\n\n```bash\nexport MBA_REAL_SAMPLES_DIR=~/private/mba-proposals\n```\n\n### 步骤 3：跑测试\n\n```bash\ncd /path/to/mba-thesis-workflow\npython3 scripts/tests/test_full_workflow.py\n```\n\n输出示例：\n\n```\n=== 真实 docx 样本批量测试 ===\n 样本目录: /Users/xxx/private/mba-proposals\n 待测试样本: 8 个（匿名展示）\n\n [测试] sample_001 (171 KB)...\n ✅ 全流程通过\n Phase 1.1: 62 真实 + 7 虚拟节点 (0.04s)\n Phase 1.3: 0 hints 写入 (0.07s)\n ch1 摘要: 18 字 (0.0s)\n ...\n```\n\n## 🔒 隐私保证\n\n代码层面：\n\n| 保护措施 | 实现 |\n|---------|------|\n| 不硬编码路径 | `MBA_REAL_SAMPLES_DIR` 环境变量，按需设置 |\n| 不硬编码文件名 | 自动发现目录下所有 `*.docx` |\n| paper_name 匿名 | `v2_real_sample_001` / `v2_real_sample_002` ... |\n| 输出匿名 | 仅显示 `sample_NNN` 索引 + 文件大小 |\n| 跳过文档元数据 | 不读取 docx 的作者、标题等元数据字段 |\n\n## 🧹 清理\n\n测试过程中会创建 `v2_real_sample_NNN` 状态的临时文件：\n\n```bash\n# 列出所有测试遗留\nls ~/.openclaw/workspace/v2_real_*\n\n# 清理（谨慎操作，会删除本地 state）\nrm -rf ~/.openclaw/workspace/v2_real_*\n```\n\n## 💡 建议\n\n- 真实样本测试**仅在本地开发时跑**，CI/CD runner 不要设这个环境变量\n- 提交 PR 时不要附带任何 docx 文件\n- 如果你想把样本提供给项目维护者，**单独发邮件 / 加密压缩包**，不要通过 GitHub Issues\n\nArchive v2.1.1-beta.13: 73 files, 286663 bytes\n\nFiles: CHANGELOG-v2.md (28387b), CHANGELOG.md (9135b), install.sh (3297b), LICENSE (1075b), README_EN.md (4332b), README.md (5583b), references/chapter-summary-design.md (5822b), references/content-hint-fallback.md (6281b), references/loop-design.md (11343b), requirements-optional.txt (581b), requirements.txt (338b), scripts/__init__.py (0b), scripts/context_builder.py (22528b), scripts/gatekeeper_integration.py (5805b), scripts/loop_self_check.py (23844b), scripts/md2docx_strict.py (30736b), scripts/multi_search.py (11124b), scripts/node_writer.py (10771b), scripts/orchestrator_v2.py (100792b), scripts/orchestrator.py (10344b), scripts/outline_parser.py (66359b), scripts/phase_manager/__init__.py (19518b), scripts/phase_manager/DESIGN.md (22966b), scripts/phase_manager/file_manager.py (21761b), scripts/phase_manager/gate_keeper.py (17002b), scripts/phase_manager/hil_renderer.py (13972b), scripts/phase_manager/schemas.py (8282b), scripts/phase_manager/summary_generator.py (13246b), scripts/phase_manager/tests/__init__.py (54b), scripts/phase_manager/tests/test_phase_manager.py (19831b), scripts/release.py (9907b), scripts/research_tools.py (12431b), scripts/reviewer.py (9044b), scripts/run_workflow.py (41991b), scripts/simple_embedder.py (7451b), scripts/state_manager_v2.py (23637b), scripts/state_manager.py (8528b), scripts/tests/__init__.py (396b), scripts/tests/conftest.py (676b), scripts/tests/REAL_SAMPLES_README.md (2332b), scripts/tests/test_b1_bypass_scarcity.py (7476b), scripts/tests/test_b2_state_sync.py (10904b), scripts/tests/test_bridge_p3_fallback.py (9954b), scripts/tests/test_chapter_summary.py (9887b), scripts/tests/test_context_builder.py (12330b), scripts/tests/test_full_workflow.py (36824b), scripts/tests/test_info_scarcity.py (15074b), scripts/tests/test_integration_chapter_summary.py (8091b), scripts/tests/test_loop_self_check.py (4603b), scripts/tests/test_md2docx_strict.py (2596b), scripts/tests/test_node_writer.py (7768b), scripts/tests/test_orchestrator.py (7008b), scripts/tests/test_outline_engine_fallback.py (20573b), scripts/tests/test_outline_parser.py (6525b), scripts/tests/test_phase1_3.py (19548b), scripts/tests/test_reviewer.py (7889b), scripts/tests/test_run_workflow.py (11046b), scripts/tests/test_state_manager.py (3732b), scripts/tests/test_synthesize_summary.py (11204b), skill-card.md (3091b), SKILL.md (22252b), skills/gatekeeper/gatekeeper.py (18343b), skills/gatekeeper/SKILL.md (5722b), tests/__init__.py (0b), tests/test_context_builder.py (4725b), tests/test_mcp_aware_llm.py (4295b), tests/test_pre_phase2_review.py (8669b), tests/test_research_tools.py (5355b), thesis-docx-export/CHANGELOG.md (806b), thesis-docx-export/README.md (1459b), thesis-docx-export/references/checklist.md (8379b), thesis-docx-export/SKILL.md (6344b), _meta.json (145b)\n\nFile v2.1.1-beta.13:SKILL.md\n\n---\nname: thesis-workflow-v2\ndescription: \"Write, review, and export MBA / academic theses end-to-end as Word / DOCX. Covers outline planning → node-by-node writing → chapter review → academic deep review → Word export with GB/T 7714 references and 南大-style formatting. Triggers: 论文 / thesis / dissertation / 答辩 / 开题 / MBA / 章节 / 文献综述 / 参考文献 / chapter outline. ⚠️ v2 is beta (outline-anchored + 9 HIL + BGE multi-search); install independently and do not overwrite v1. Prefer v1 (`thesis-workflow`) for production unless user explicitly asks for v2 / 新框架 / outline-anchored / 9 HIL.\"\nplatforms: [linux, macos, windows]\nmetadata:\n # ↓ OpenClaw 私有配置（仅 ClawHub 加载器识别；不影响标准 platforms 字段）\n clawdbot:\n emoji: \"📝\"\n version: \"2.1.1\" # 单一真实来源，发布前必须先改这里。发布规则见 scripts/release.py\n requires: {}\n os: [\"linux\", \"darwin\", \"win32\"]\n---\n\n# MBA/学术论文多Agent协作工作流\n\n> 完整文档见：`references/checklist.md`（学术规范清单）、`references/loop-design.md`（Loop 设计原理）\n\n## 🔌 平台依赖（加载后必看）\n\n本 skill **不是**通用 Hermes skill，专为 OpenClaw 设计。在调用本 skill 任何 Python 入口前，先确认平台依赖：\n\n| 维度 | 依赖项 |\n|-------------------|------------------------------------------------------------------------|\n| **Agent 启动** | `sessions_spawn`（OpenClaw 子 agent 机制） |\n| **状态文件目录** | `~/.openclaw/workspace/{paper_name}/`（**非** Hermes 标准路径） |\n| **工具后端** | `web_search` / `tavily_search` / `arxiv_search`（OpenClaw MCP 工具链） |\n| **CLI 入口** | `python3 scripts/run_workflow.py {paper_name} --phase auto` |\n| **Python 路径** | `PYTHONPATH=scripts python3 ...`（CLI 内部期望 scripts 在 path 上） |\n\n**反模式：** 不要把本 skill 当作标准 Hermes skill 调用——Hermes 的 file / search / web 工具链不能驱动 v2 的状态机和 HIL 拦截。如果你需要把论文流程迁回 Hermes，先做\"状态层适配\"（用 Hermes 的 workspace 概念替代 `~/.openclaw/workspace/`，并把 `sessions_spawn` 改成 Hermes 的子任务机制），再启用本 skill。\n\n## ⚠️ 触发规则\n\n当用户请求生成 Word 文档且满足以下任一条件时，**必须**调用本 skill 的 Word 输出流程，不得使用简单 md2docx 脚本：\n- 输入文件路径匹配：`论文*.md`、`*thesis*.md`、`*dissertation*.md`\n- 上下文中存在「论文」「MBA」「答辩」「开题」等关键词\n- 用户明确要求导出 `.docx` 格式且文件性质为学术论文\n\n**正确流程：** 写作语法预检 → Review Agent 终审（`scripts/loop_self_check.py` 校验通过）→ `scripts/md2docx_strict.py` 合规转换 → Word 输出\n\n## ⚠️ v1 / v2 选择矩阵（加载后必看）\n\nv2 仍处于 beta，**生产论文默认走 v1**。仅当用户明确要求时再切 v2：\n\n| 场景 | 选择 | 触发依据 |\n|------|------|---------|\n| 用户说「稳一点 / 跑过答辩 / 已用 v1 / 默认」 | ✅ v1 (`thesis-workflow`) | 默认基线 |\n| 论文已在 `~/.openclaw/workspace/{paper}/` 下运行 v1 | ❌ 切 v2 | 状态文件不兼容 |\n| 用户说「用 v2 / 新框架 / outline-anchored / 9 HIL / BGE 多工具并行」 | ✅ 本 skill (v2) | 显式升级 |\n| 用户未明示 + 新论文 | ⚠️ 走 v1 | 避开 beta 风险 |\n\n**反模式：** 不要因为「本 skill 描述更新」就把现有 v1 论文切到 v2——v2 的 `_orchestrate_state.json` schema 与 v1 不兼容。\n\n### v2 HIL 节点一览（确定用 v2 之后再读）\n\nv2 在 9 个位置**强制 human-in-the-loop**：每到这些点状态机会 hard pause，必须用户确认才能推进。如果 agent 想绕过任何一项，v2.0.6 的拦截规则会拒绝（见 §v2.0.6 拦截规则）：\n\n| # | 触发位置 | 检查内容 | 决策 |\n|----|--------------------------------|--------------------|-------------------|\n| 1 | Phase 1.1 后 | 大纲结构 | 接受 / 修改 |\n| 2 | Phase 1.3 后 | 归因结果 | 接受 / 调整 hint |\n| 3 | 在 `write_single_node()` 写入单节点前 | info_scarcity | 提供 hint / AI 生成 / 跳过 |\n| 4 | Phase 2 评审后 | quality=medium/low | 接受 / 重写 |\n| 5 | Phase 2 完成后 | 章节内容预览 | 通过 / 修改 |\n| 6 | Phase 3 整合后 | 整合版内容 | 通过 / 修改反馈 |\n| 7 | Phase 3.5 P0 修复 | 超 3 轮未收敛 | 接受 / 继续修订 |\n| 8 | Phase 4 整合方案 | 方案是否接受 | 接受 / 修改 |\n| 9 | Phase 5.2 后 | Word 输出 | 导出 / 修改 |\n\n**反模式：** 不要给 agent 传 `allow_skip_hil=True` 或在 prompt 里写\"自动通过所有 HIL\"——HIL 是论文质量最后一道防线，绕过它的代价是错版交付给导师。\n\n### v2.0.6 拦截规则（与 HIL 表配套必读）\n\n如果 agent 想绕过 HIL 或绕过\"独立评审\"，v2.0.6 在 orchestrator 层有 3 类硬拦截：\n\n| 拦截点 | 强制规则 | 失败场景 |\n|--------|----------|----------|\n| **拍板 #1 强制** | `phase1_3_skip` 不允许；`skip_phase1_3()` 需要 `MBA_THESIS_PRODUCTION=1` + 必填 `reason`/`operator` + audit log | 跳过 Phase 1.3 → 论文方向错位无人工把关，全文跑偏 |\n| **B-2 幂等保护** | `outline_update_status()` 默认拒绝覆盖已 completed 节点 | 误重写已通过审核的节点 → 评审历史回滚，质量倒退 |\n| **独立 Reviewer** | `write_single_node()` 默认要求 `reviewer_func ≠ llm_func` | 生成+评审用同一 LLM → 自我审核，\"我写的都对\"假阳性 |\n\n**反模式：** 不要在 prompt 里\"建议 agent 用 force=True 绕过\"或\"把 allow_skip_hil 设为 True\"——v2.0.6 的拦截规则会拒绝并返回错误。绕过拦截的代价比\"卡在 HIL 等用户确认\"高得多。\n\n## 核心架构\n\n```\nPhase 1（规划）→ Phase 2（逐节点写作）→ Phase 2.5（内容确认）\n→ Phase 3（整合）→ Phase 3.5（学术深度评审）\n→ Phase 4（修复）→ Phase 5（终审 + Word 输出）\n```\n\n⚠️ **阶段强制顺序：** 全部 Phase 必须按顺序执行，不得跳过。Phase 2.5（人工确认门槛）和 Phase 3.5（深度评审）是固定节点，不得跳过。\n\n## Agent 设计原则\n\n**每个 Agent 只做一件事。** Agent 间通过文件传递结果，不共享上下文。Orchestrator 专注调度，不执行执行性工作。\n\n| Agent | 调用方式 | 主责 |\n|-------|---------|------|\n| **Orchestrator** | 当前 session | 调度 / 推进 / 决策 |\n| **NodeWriter** | `sessions_spawn` | 逐节点内容生成 |\n| **Reviewer** | `sessions_spawn` | Phase 3/5 规则型审核 |\n| **DeepReviewer** | `sessions_spawn` | Phase 3.5 学术深度评审 |\n| **Integrator** | `sessions_spawn` | Phase 4 整合方案 |\n| **WordAgent** | `exec python3` | md2docx执行 + 格式校验 |\n\n## 关键实现说明\n\n### 公司信息处理\n\n- 用真实公司名搜索公开数据，填入正文时替换为代号（A公司/B公司）\n- 搜索 prompt 用真实名，输出 prompt 用代号\n- 映射关系不进入最终文档\n\n### 检索同步规则\n\n所有 Phase 调用数据查询工具（`web_search` / `academic-research`）时，必须：\n1. 同步输出工具名称 + 查询条件 + 结果摘要（<50字）\n2. Subagent 用 `sessions_send` 向主 session 发送同步\n3. 大型检索完成后输出结构化结果摘要\n\n### 数据查询工具（v2 多工具并行策略）\n\n> **核心原则**：4个工具并行发出，取长补短，去重排序，任意失败不阻断。\n> `web_search` 等内置工具 Agent 直接调用，无需经过 Python 层包装。\n\n**工具矩阵：**\n\n| 工具 | 来源 | 适用场景 |\n|------|------|---------|\n| `web_search` | OpenClaw 内置（头条搜索） | 行业数据、市场规模、新闻动态 |\n| `tavily_search` | Tavily MCP（mcporter） | 结构化摘要、权威来源 |\n| `arxiv_search` | arXiv MCP（mcporter） | 前沿学术论文、技术细节 |\n| `openalex_search` | scholar-search.py（OpenAlex） | 学术文献、引用分析 |\n\n**Python 层调用（`research_tools.py`）：**\n```python\nfrom research_tools import quick_search, research_enrich\n\n# 快速检索（返回文本，供注入 prompt）\nresult = quick_search(\"竞争战略 市场规模 2024\")\n\n# 节点级检索（自动取 outline 中的 research_keywords）\nctx = research_enrich(node_id, paper_name)\n```\n\n**并行执行逻辑：**\n1. 四工具同时发出，不串行等待\n2. 各工具独立降级（超时/失败 → 静默忽略）\n3. 结果按 URL 去重 + score 排序\n4. 输出格式：`[来源] 标题\\n 摘要\\n URL`\n\n**Agent 视角：**\n- Agent 可继续直接使用 `web_search(query=...)` 等内置工具\n- `quick_search()` 是 Python 层的补充，用于学术/论文场景的结构化检索\n\n## Phase 详解\n\n### Phase 1：规划与定稿\n\n**🔴 红线：** Phase 1.1 / 1.3 **禁止**直接调用 Python API，必须经 `run_workflow.py`（详见 §A.6）。直接 `import orchestrator_v2` 在 Phase 1 阶段会绕过用户 HIL 确认，论文签收前的方向错误会全白做。\n\n通过问答输出确认清单，用户逐项确认后方可动笔。\n\n**红色星标项（必填）：**\n- ⭐ 实际公司名称（仅用于数据检索，正文以A公司/B公司呈现，不进入公开文档）\n- ⭐ 大纲结构（7章大纲逐章确认）\n- 论文基本信息（题目/作者/专业/学位类型/答辩年份）\n\n→ 生成「写作任务书」用户签收后进入 Phase 2。\n\n### Phase 2：逐节点写作\n\n**前置检查：** Phase 1 必填项已确认\n\n**🔴 红线：**\n- ❌ 跳过 `run_workflow.py` 直接读写 `_orchestrate_state.json`（必须经 CLI 入口）→ 失败场景：CLI 内部维护\"状态机锁 + phase 推进历史 + audit log\"，直接读写会绕过锁，导致下一 Phase 跳号或死锁\n- ❌ 手工修改状态文件的 `phase*_status` 字段（会破坏 Orchestrator Loop 的下一阶段判断）\n- ❌ 长任务不汇报进度（必须按 25% / 50% / 75% / 100% 节点主动汇报，含 `completed_nodes` 数）→ 失败场景：Phase 2 写作耗时 20+ 分钟无汇报，用户以为 session 卡死会主动打断，导致已写 30 节点的章节全部丢失、状态半成品\n\nOrchestrator 遍历 outline 树中的每个节点，调用 `write_single_node()` 逐个生成内容。\n每个节点写作前通过 `context_builder.py` 构建 prompt 包，自动注入：\n- 承接上文（auto bridge）\n- 分析维度建议（规则推导）\n- 开题报告方向参考（content_hint）\n- 行业数据参考（quick_search 多工具检索）\n\n**Phase 2 强制检索要求**（关键词中的 `{论文主题行业}` 由 Orchestrator 自动提取）：\n- 第3章 PESTEL 分析前 → 多工具并行搜索「{论文主题行业} 市场规模/趋势/政策」\n- 第3章 五力模型分析前 → 多工具并行搜索「{论文主题行业} 主要竞争对手/市场份额」\n- 战略理论部分 → 多工具并行搜索「{论文主题行业} 竞争战略 应用」\n- 每章至少 1 个引用标注来源，全文检索记录 ≥ 3 次\n- **多工具并行检索**：调用 `quick_search()` 或 `research_enrich()`，结果自动去重排序\n\n**状态文件机制：** `_orchestrate_state.json`（`scripts/state_manager_v2.py`）\n\n→ 全部节点写完且字数达标后进入 Phase 2.5（内容确认）。\n\n### Phase 3：整合\n\nReviewer 对整合版论文进行审核。审核维度：格式 / 大纲 / 内容准确性 / 查重风险 / 学术规范 / 写作语法。\n\n### Phase 3.5：深度学术评审（固定节点）\n\nDeepReviewer 对 Phase 3 报告进行二次审查，输出 P0/P1/P2 分级问题清单。P0 问题进入修订 → 重审闭环（见审核 Loop）。\n\n### Phase 4：整合\n\nIntegrator 汇总 Phase 3 + Phase 3.5 全部评审结果，制定整合方案。核心原则：取长补短，不为统一而破坏内容质量。\n\n**自动验证：** 整合版运行 `python3 scripts/loop_self_check.py` 校验，100%通过方可输出 Word。\n\n### Phase 5：终审与输出\n\n- Phase 5：Reviewer 终审\n- Phase 5.1：[可选] `humanize-chinese` skill 去AI味\n- Phase 5.2：**调用 `thesis-docx-export` skill**（Word 转换 + 10 项 Guardrails 校验）\n\n## Orchestrator 生命周期管理\n\n**🔴 红线：** Phase 1 / 5.x **必须**经 `run_workflow.py` 入口；Phase 2-4 才允许 `import orchestrator_v2` 直接调 Python API（且仅在已通过 run_workflow 进入论文状态之后）。\n- ❌ 跳过 `run_workflow.py` 直接 `from orchestrator_v2 import orchestrate` → 失败场景：CLI 内部维护\"状态机锁 + phase 推进历史 + audit log\"，直接 import 绕过锁，导致下一 Phase 跳号或死锁\n- ❌ Phase 1 任何子阶段（1.1 / 1.2 / 1.3）直接 import orchestrator_v2 调 `phase1_*` → 失败场景：绕过用户在 Phase 1.1 / 1.3 末尾的 HIL 签收，论文方向错位无人工把关\n- ❌ 把 `force=True` / `allow_skip_hil=True` 作为 prompt 默认值 → 失败场景：v2.0.6 拦截规则会拒绝并抛错；agent 越权操作进退两难\n\n### 真实入口（v2.0.6 新增）\n\n> **执行脚本**：`scripts/run_workflow.py`（v2 真实入口 CLI）\n> **状态文件**：`~/.openclaw/workspace/{paper_name}/_orchestrate_state.json`\n> **设计原则**：驱动状态机 + 9 个 HIL 节点 hard pause\n\n```bash\n# 仅查看状态\npython3 scripts/run_workflow.py --status\n\n# auto 模式：根据 state 自动判断下一步\npython3 scripts/run_workflow.py --phase auto\n\n# 指定阶段\npython3 scripts/run_workflow.py --phase phase1\npython3 scripts/run_workflow.py --phase phase2 # 需 --llm\npython3 scripts/run_workflow.py --phase phase3\n```\n\n### Python API（v2.0.9）\n\n```python\nimport sys\nsys.path.insert(0, \"scripts\")\nfrom orchestrator_v2 import orchestrate, write_single_node, apply_user_decision\n\n# Phase 1.1: 解析开题报告（docx 或文本）\nr = orchestrate(paper_name, action=\"phase1_1_init\",\n input_type=\"docx\", input_data=\"path/to/proposal.docx\")\n\n# Phase 1.2: 确认大纲（用户 HIL）\nr = orchestrate(paper_name, action=\"phase1_confirm\")\n\n# Phase 1.3: 提交开题报告归因\nr = orchestrate(paper_name, action=\"phase1_3_submit\",\n docx_path=\"path/to/proposal.docx\", llm_func=my_llm)\n\n# Phase 1.3: 确认归因（用户 HIL）\nr = orchestrate(paper_name, action=\"phase1_3_confirm\")\n\n# Phase 2: 逐节点写作（v2.0.4 推荐调用模式）\nfor node_id in next_nodes:\n r = write_single_node(paper_name, node_id,\n reviewer_func=my_reviewer) # 独立评审，llm_func 内部从 session 获取\n\n# Phase 3: 整合\nr = orchestrate(paper_name, action=\"phase3_review\")\n\n# Phase 3.5: 深度学术评审（自动进入 Phase 3.5/4/5 链）\n# Phase 3 → orchestrate_phase3_5() → P0修复 → Phase 4 → Phase 5\nr = orchestrate(paper_name, phase=\"phase3\", action=\"phase3_export\")\n\n# Phase 5: Word 输出提示\nprint(r.get(\"message\", \"\"))\n```\n\n### HIL 节点（v2.0.6 完整 9 个）\n\n> 9 个 HIL 节点的速查表已前移到 `## 核心架构` 之前（紧跟 v1/v2 选择矩阵后）。在 §\"v2 HIL 节点一览\"查看完整表。\n\n### v2.0.6 拦截规则（enforcement）\n\n> v2.0.6 拦截规则段（拍板 #1 / B-2 幂等 / 独立 Reviewer）已前移到 `## 核心架构` 之前（紧跟 9 个 HIL 节点表后）。在 §\"v2.0.6 拦截规则\"查看完整表。\n\n### 审核 Loop 自动重审\n\nPhase 3.5 完成 → orchestrator 解析 P0 计数 → 有 P0？→ 自动进入修订\n→ 修订完成 → 自动回到 Phase 3.5 重审 → 连续 2 轮无新 P0 → 通过\n→ 超过 3 轮 → HIL 暂停\n\n### Phase 内部自检\n\n每 Phase 完成后，orchestrator 自动运行 `loop_self_check.py` 校验：\n```bash\npython3 scripts/orchestrator.py 状态文件.json --validate\n```\n校验失败 → RETRY 打回 → Agent 修复 → 再次校验（最多 3 次）\n\n## ⚠️ Loop 设计原则\n\n5 个 Loop 元素的详细定义、终止条件、HIL 检查点对照、与 OpenClaw Agent Loop 的差异比较：详见 `references/loop-design.md`（302 行）。\n\n**速记：** 每个 Loop 最多重试 3 次；Phase 1 / 2.5 / 4 / 5.2 末尾为强制 HIL 节点（必须用户确认才能推进）。\n\n## Guardrails 校验（10 项）\n\n```bash\npython3 scripts/loop_self_check.py --file 论文_xxx.md # 单文件\npython3 scripts/loop_self_check.py --phase 2 --workspace ~/.openclaw/workspace/ # Phase 级别\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx # Word 校验\n```\n\n| # | 校验项 | 失败阻断 |\n|---|--------|---------|\n| 1 | 章节完整性（7章齐全） | Phase 2/4 |\n| 2 | 字数门槛（每章≥100行） | Phase 2/4 |\n| 3 | 参考文献存在 | Phase 4 |\n| 4 | 无 `## 第X章` 混合格式 | Phase 2/4 |\n| 5 | 无 `**正文加粗**` | Phase 2/4 |\n| 6 | 引用完整性（逐章≥1处，全文≥10处） | Phase 2/4 |\n| 7 | 三线表列数一致 | Phase 4 |\n| 8 | 表标题在表上方 | Phase 4 |\n| 9 | 无合并残留（`===END===`） | Phase 4 |\n| 10 | 核心章节关键词（第5章战略/第6章实施） | Phase 2.5 |\n\n## Word 输出\n\n> **本段已外移。** Word 转换、加粗过滤、三线表、分页、Guardrails 10 项校验等所有 Word 相关细节，由独立 skill `thesis-docx-export` 承载。\n>\n> 调用入口和文档：\n> - Skill：`thesis-docx-export/SKILL.md`\n> - 18 项格式规范清单：`thesis-docx-export/references/checklist.md`\n> - 10 项 Guardrails 校验：`thesis-docx-export/scripts/loop_self_check.py`（软链接 → `scripts/loop_self_check.py`）\n>\n> 主 skill 只在 Phase 5.2 阶段调用本 skill，不在 Phase 1-5 重复展开。\n\n## 附录：脚本与文档结构\n\n```\nthesis-workflow/\n├── SKILL.md ← 本文件（简版触发器 + 核心逻辑）\n├── README.md / README_EN.md ← 安装/使用说明\n├── CHANGELOG.md ← 版本日志\n├── config.template ← 配置模板\n├── install.sh ← 安装脚本\n├── .clawhubignore / .github/workflows/skill-publish.yml\n├── scripts/\n│ ├── md2docx_strict.py ← Word 合规转换（真身在主 skill；docx-export 软链接共享）\n│ ├── loop_self_check.py ← Guardrails 自动化校验（10项）（真身在主 skill；docx-export 软链接共享）\n│ ├── state_manager.py ← 状态文件管理\n│ └── tests/ ← 单元测试\n├── references/\n│ ├── checklist.md ← 软链接 → thesis-docx-export/references/checklist.md\n│ ├── content-hint-fallback.md ← 附录 B 外移版（v7.0 跑题事故修复方案）\n│ ├── chapter-summary-design.md ← 章节摘要节点设计\n│ ├── git-workflow.md ← 双版本发布策略\n│ └── loop-design.md ← Loop 设计原理说明\n└── thesis-docx-export/ ← 独立 skill（Phase 5.2 Word 输出）\n ├── SKILL.md ← docx-export 入口文档\n ├── README.md / CHANGELOG.md\n ├── scripts/ ← 软链接主 skill scripts/\n └── references/ ← checklist.md 真身在此\n```\n\n## 附录 A：论文项目运行 Checklist（agent 必遵守）\n\n> **来源**：v7.0 事故复盘 → 龙哥 22:19 反馈 / 2026-06-29 \n> **适用对象**：跑 thesis-workflow-v2 的任何 agent（含 main session 和 isolated） \n> **生效日期**：2026-06-29 起\n\n### A.1 触发即汇报\n\n启动任何 thesis-workflow-v2 阶段前，先发一条汇报：\n- 论文名 / 阶段 / 启动时间 / 监考路径（如有 PID/log）\n- 5-30 字，简洁不啰嗦\n\n### A.2 阶段切换必汇报\n\n- Phase 1 → Phase 2（写作开始）\n- Phase 2 → Phase 3（整合开始）\n- Phase 3 → Phase 3.5（评审开始）\n- Phase 3.5 → Phase 4 / Phase 5（终审/导出）\n\n每切换发一条\"已到 X 阶段\"短汇报。\n\n### A.3 长跑阶段主动节拍\n\nPhase 2 写作阶段（如有 background 任务）：\n\n| 进度节点 | 必汇报 |\n|---------|--------|\n| 启动 | ✅ |\n| 完成 25% | ✅ |\n| 完成 50% | ✅ |\n| 完成 75% | ✅ |\n| 完成 100% / 失败 | ✅ |\n\n- 每次汇报含当前 `completed_nodes` 数量\n- 用 `cat _orchestrate_state.json` 拿实时数据\n\n### A.4 异常即停 + 主动汇报\n\n触发任一异常情况，**立即**停下来汇报（不等用户问）：\n- content_hint 覆盖率 < 50% → Phase 1.3 异常\n- 大量节点 failed → Phase 2 失败\n- 整合版字数异常（< 30k 或 > 200k）\n- outline_state 节点结构与 _orchestrate_state 不一致\n\n### A.5 完成必汇报（含产出清单）\n\n论文交付时，必汇报：\n- 终稿路径\n- 字数（中文字数 / 总字符数）\n- 章节完成情况\n- 异常/缺陷（如有）\n- 邮件/通知状态\n\n### A.6 红线禁止（继承自 AGENTS.md）\n\n- ❌ 跳过 run_workflow.py 操作状态文件\n- ❌ 不汇报长任务进度\n- ❌ Phase 1.3 / 1.1 直接调用 Python API\n- ❌ 状态文件手工修改 phase*_status 字段\n\n### A.7 辅助工具（可选）\n\n如需手动查看状态，可用：\n```bash\npython3 ~/.openclaw/scripts/thesis_progress_reporter.py --idle-minutes 60\n```\n\n脚本全局通用，跨 macOS/Linux/Windows，纯 stdlib。idle 60min 自动静默。\n\n## 附录 B（指针）：已批准改进方案 — content_hint fallback\n\n历史事故与代码实现已外移到 `references/content-hint-fallback.md`（139 行）。当 `node.content_hint` 为空时，`scripts/context_builder.py` 会自动注入\"大纲骨架 + 反面警示\"以防 LLM 跑题。\n\n如需查具体函数实现（`_extract_paper_subject` / `_build_outline_skeleton` / `_build_no_runoff_warning`）或验收标准，跳到 references 文件即可。\n\nFile v2.1.1-beta.13:skills/gatekeeper/SKILL.md\n\n# Gatekeeper Skill — 论文写作质量与流程门禁\n\n> 版本：1.0.0\n> 角色：所有产出给用户前的最后一道门；全程守护流程/规范/质量\n\n---\n\n## 角色定义\n\n**Gatekeeper = 质量门禁 + 流程门禁 + 结果门禁 + 出口门禁**\n\n- 独立 session 运行，不阻塞 Orchestrator 执行路径\n- 所有异常记录到 `_gk_exception_log.json`\n- 流程结束后统一汇报给用户\n- 用户选择\"修复\"则触发闭环修复流程\n\n---\n\n## 门禁层次\n\n### 1. 流程门禁（Process Gate）\n\n**触发时机**：每次 Phase 切换时\n\n```\n检查项：\n ✓ 前置 Phase 是否已完成\n ✓ 当前 Phase 的必填字段是否齐全\n ✓ 状态机是否合法跳转（phase1 → phase2 需要 phase1_3_confirmed）\n ✓ HIL 节点是否满足通过条件\n```\n\n**阻断行为**：\n- 写入 `_gk_exception_log.json`\n- 通知用户，等待决策\n- Orchestrator 暂停直到用户回复\n\n---\n\n### 2. 质量门禁（Quality Gate）\n\n**触发时机**：每个节点写作完成后、整合前、导出前\n\n```\n检查项（loop_self_check）：\n ✓ 章节完整性（7章都有）\n ✓ 无 **加粗** 残留\n ✓ 引用数量逐章检查（每章 ≥ 1 处）\n ✓ 三线表格式正确\n ✓ 无乱码/占位符残留\n ✓ 标题层级正确\n ✓ 字数达标（每章 ≥ 800 字）\n```\n\n**不达标** → 打回重写，不进入下一节点\n\n---\n\n### 3. 结果门禁（Result Gate）\n\n**触发时机**：Phase 3 整合后、Phase 5 导出前\n\n```\n检查项：\n ✓ 开题报告承诺的内容是否落地\n ✓ 关键章节（PEST/战略理论/案例分析）是否充实\n ✓ 章节之间逻辑衔接是否顺畅\n ✓ 结论与前文分析是否对应\n```\n\n---\n\n### 4. 出口门禁（Export Gate）\n\n**触发时机**：最终输出给用户前（唯一出口）\n\n```\n检查项：\n ✓ Guardrails 最终校验通过\n ✓ Word 文档生成成功\n ✓ 用户确认导出\n```\n\n---\n\n## 异常日志设计\n\n**文件路径**：`~/.openclaw/workspace/papers/{paper_name}/_gk_exception_log.json`\n\n```json\n{\n \"paper_name\": \"论文名称\",\n \"start_time\": \"2026-06-26T21:00:00+08:00\",\n \"exceptions\": [\n {\n \"id\": 1,\n \"timestamp\": \"2026-06-26T21:18:00+08:00\",\n \"phase\": \"phase2\",\n \"node_id\": \"ch3\",\n \"gate_type\": \"quality_gate\",\n \"gate_name\": \"citation_check\",\n \"description\": \"第3章引用数量不足：0处（要求≥1处）\",\n \"severity\": \"error\",\n \"status\": \"pending\",\n \"action_taken\": null,\n \"repaired_at\": null,\n \"repaired_by\": null,\n \"user_notified\": true,\n \"user_decision\": null\n }\n ],\n \"summary\": {\n \"total\": 1,\n \"pending\": 1,\n \"fixed\": 0,\n \"skipped\": 0\n }\n}\n```\n\n---\n\n## 用户交互流程\n\n### 流程守护（异常发生时）\n\n```\nGatekeeper 发现异常\n ↓\n写入 _gk_exception_log.json（status=pending）\n ↓\n通知用户（飞书）：\n━━━━━━━━━━━━━━━━━━━━━━\n🤖 [Gatekeeper] 发现异常\n\n环节：Phase 2（节点写作）\n节点：ch3 第3章\n问题：引用数量不足（0处，要求≥1处）\n━━━━━━━━━━━━━━━━━━━━━━\n请选择：\n [1] 修复后继续（打回重写）\n [2] 跳过此检查（谨慎！）\n [3] 暂停，手动介入\n━━━━━━━━━━━━━━━━━━━━━━\n ↓\n等待用户回复\n ↓\n用户选择 [1/2/3]\n ↓\n更新 exception.status + action_taken\n ↓\n[1] → 通知 Orchestrator 修复\n[2] → 继续流程（记录 skip）\n[3] → 暂停，等用户手动触发\n```\n\n### 流程结束后（统一汇报）\n\n```\n所有 session 结束后\n ↓\nGatekeeper 生成最终报告\n ↓\n发给用户：\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n🤖 [Gatekeeper] 流程结束 — 异常报告\n\n本次流程共发现 N 个异常：\n\n【异常 #1】\n时间：2026-06-26 21:18\n环节：Phase 2\n节点：ch3\n类型：质量门禁 - 引用数量不足\n处理：已修复\n\n【异常 #2】\n时间：2026-06-26 21:25\n环节：Phase 4\n节点：—\n类型：流程门禁 - HIL #8 阻断\n处理：用户确认跳过\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n建议优化项：\n 1. ...\n 2. ...\n\n请选择：\n [1] 查看异常详情\n [2] 优化 skill 配置\n [3] 结束\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n---\n\n## 巡检机制\n\nGatekeeper 启动后定期巡检（每 30 秒）：\n\n```\n巡检项：\n ✓ 当前 state 的 phase 是否合法\n ✓ completed_nodes 是否有重复\n ✓ failed_nodes 是否长时间未修复\n ✓ phase3_5 连续轮次是否异常（>5轮则告警）\n ✓ 是否有节点写作超 30 分钟未完成（疑似卡住）\n```\n\n---\n\n## 与 Orchestrator 的协作方式\n\n**通过状态文件通信，零直接函数调用：**\n\n```\nOrchestrator 写：_orchestrate_state.json\nGatekeeper 读：_orchestrate_state.json + 巡检\nGatekeeper 写：_gk_exception_log.json\nOrchestrator 读：_gk_exception_log.json（查看是否有 pending exception）\n```\n\n**关键状态字段：**\n\n```\ngk_last_check: 最后巡检时间\ngk_exception_count: 当前 pending 异常数\ngk_user_decision: 用户最新决策（由 Gatekeeper 写入）\n```\n\n---\n\n## 启动方式\n\n```python\n# Orchestrator 需要时 spawn\nsessions_spawn(\n task=\"gatekeeper\",\n taskName=\"gk_{paper_name}\",\n runtime=\"subagent\",\n context=\"isolated\",\n payload={\n \"paper_name\": \"论文名\",\n \"mode\": \"daemon\", # 常驻巡检\n }\n)\n```\n\n---\n\n## 权限要求\n\n- 读：`papers/{paper_name}/*.json`\n- 写：`papers/{paper_name}/_gk_exception_log.json`\n- 通知：飞书/微信（sessions_send）\n\nFile v2.1.1-beta.13:thesis-docx-export/SKILL.md\n\n---\nname: thesis-docx-export\ndescription: \"Convert academic thesis markdown (.md) into a Word (.docx) document that meets the MBA / 南大 / GB/T 7714 formatting spec, and run the 10-item Guardrails check before and after export. Triggers: 导出 Word / 转换为 docx / 论文格式校验 / Guardrails 校验 / md2docx / 三线表 / 分页符 / GB/T 7714 参考文献格式. Required by `thesis-workflow-v2` Phase 5.2; can also be invoked standalone after manual writing.\"\nplatforms: [linux, macos, windows]\nmetadata:\n clawdbot:\n emoji: \"📄\"\n version: \"1.0.0\" # 单一真实来源；主 skill thesis-workflow-v2 仅在 Phase 5.2 阶段引用本 skill\n requires: {}\n os: [\"linux\", \"darwin\", \"win32\"]\n---\n\n# Thesis DOCX Export\n\n把学术论文 Markdown 转换为符合学术规范的 Word 文档，并在导出前后自动跑 Guardrails 校验。\n\n本 skill 是 `thesis-workflow-v2`（主 skill）Phase 5.2 阶段的\"出口工序\"——主 skill 完成 Phase 1-5 内容生产后，调用本 skill 做 Word 转换和最终格式校验。本 skill **也可以独立调用**：用户手写完论文后，直接用本 skill 做导出。\n\n> **核心原则**：本 skill 不做内容生成（写、审、整合都是主 skill 的事）。本 skill 只做\"格式合规\"：校验 → 转换 → 再校验。\n\n## ⚠️ 调用矩阵\n\n| 触发场景 | 选择 |\n|---------|------|\n| 主 skill `thesis-workflow-v2` 跑到 Phase 5.2 | ✅ 本 skill（自动调用，无需用户手动触发） |\n| 用户手写论文后想导出 docx | ✅ 本 skill（standalone 调用） |\n| 用户只想校验 Markdown 是否符合学术规范 | ✅ `python3 scripts/loop_self_check.py --file 论文.md`（只校验、不导出） |\n| 用户想用 pandoc / python-docx 直接生成 Word | ❌ 本 skill（pandoc 不做三线表、不做 GB/T 7714 排序） |\n\n**反模式：** 不要把本 skill 用于\"内容生成\"——主 skill 的 Phase 2 写作、Phase 3 审核、Phase 4 整合都由 `thesis-workflow-v2` 负责。本 skill 只接受已完成的 Markdown 输入。\n\n## 核心能力\n\n### 1. Guardrails 10 项自动校验\n\n`scripts/loop_self_check.py` 在转换前后各跑一次：\n\n```bash\n# 转换前校验 Markdown 内容（10 项 Guardrails）\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# 转换后再校验生成的 docx（Word 格式校验）\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n**10 项校验项详见 [references/checklist.md §六](references/checklist.md)**。\n\n### 2. Word 格式转换\n\n`scripts/md2docx_strict.py` 把符合 Guardrails 的 Markdown 转为 docx，应用以下格式：\n\n| 维度 | 规则 |\n|-------------|----------------------------------------------------------|\n| 正文加粗过滤 | 正文段落内的 `**text**` 全部转为普通文字（无强调术语） |\n| 表格加粗过滤 | 表格单元格内的 `**` 同步清除 |\n| 三线表 | 顶线 1.5 磅 / 表头底线 0.75 磅 / 底线 0.5 磅，无竖线 |\n| 分页符 | 每章标题前插入分页符（首章跳过），附录/致谢前分页 |\n| 字体 | 中文宋体 / 英文 Times New Roman / 标题黑体 |\n| 行距 | 正文 20 磅 |\n\n**反模式：** 不要用 `pandoc 论文.md -o 论文.docx` 走捷径——pandoc 不做加粗过滤、不做三线表、不做 GB/T 7714 排序；出来的 docx 必须经 `loop_self_check.py --verify-docx` 二次校验才能交付。\n\n## 入口与依赖\n\n### 入口\n\n```bash\n# 校验 + 转换 + 再校验 一条龙\npython3 scripts/loop_self_check.py --file 论文_xxx.md\npython3 scripts/md2docx_strict.py --input 论文_xxx.md --output 论文_xxx.docx\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n### 依赖\n\n- `python-docx`（Word 写入）\n- `pandoc`（Markdown 预处理）\n- 标准 Python 3.9+ 库\n\n### 反向依赖\n\n本 skill **被** `thesis-workflow-v2`（主 skill）Phase 5.2 引用。如果本 skill 不可用，主 skill 的 Phase 5.2 步骤会失败。\n\n## 文件结构\n\n```\nthesis-docx-export/\n├── SKILL.md ← 本文件\n├── README.md ← 用户使用说明\n├── CHANGELOG.md ← 版本日志\n├── scripts/\n│ ├── md2docx_strict.py ← Word 转换器（软链接 → ../../scripts/md2docx_strict.py）\n│ └── loop_self_check.py ← Guardrails + Word 校验（软链接 → ../../scripts/loop_self_check.py）\n└── references/\n └── checklist.md ← 18 项格式规范 + 10 项 Guardrails 校验项 + Phase 退出门禁\n```\n\n> **单一真实来源原则**：`md2docx_strict.py` 和 `loop_self_check.py` 的真身在主 skill `scripts/` 目录，本目录用软链接共享——避免代码 drift。\n\n## 18 项格式规范（人工对照清单）\n\n完整清单在 [references/checklist.md](references/checklist.md)，核心维度：\n\n- **格式维度（18 项）**：封面 / 原创性声明 / 中英文摘要 / 目录 / 章节标题层级 / 段落 / 图号图题 / 表号表题 / 表格 / 图表编号 / 注释 / 参考文献 / 页码 / 附录 / 致谢 / 写作语法\n- **大纲维度（2 项）**：章节范围 + 章节结构\n- **内容准确性（2 项）**：引用标注 + 数据自洽\n- **查重风险（1 项）**：30 字以上连续重合\n- **学术规范（6 项）**：引用完整率 + 术语缩写 + 中英文格式\n\n## 违规等级\n\n| 等级 | 标记 | 处理 |\n|---------|------|--------------------------------------------|\n| 🔴 P0 | 致命 | **必须修复**（章节缺失、参考文献缺失、合并残留） |\n| 🟡 P1 | 严重 | **必须修复**（标题层级错误、加粗残留、字数不足） |\n| ⚠️ P2 | 一般 | 建议修复（引用缺失、图表编号不规范） |\n| 💡 建议 | 优化 | 可选（措辞、过渡句式） |\n\n## 维护与支持\n\n- 维护者：`thesis-workflow-v2` 同 owner\n- 主 skill 引用：本 skill 在 `thesis-workflow-v2/SKILL.md` 的 Phase 5.2 段被引用\n- Bug 报告：在 GitHub `mba-thesis-workflow` 仓库的 issue 列表提，标签 `thesis-docx-export`\n\nFile v2.1.1-beta.13:README.md\n\n# MBA/学术论文 多Agent协作工作流（v2 新框架）\n\n📝 多Agent协作完成MBA/学术论文写作的完整工作流，支持大纲解析、逐节点写作、深度审核、整合终审、Word输出。\n\n适用于开题报告到毕业论文的全流程。\n\n---\n\n## ⚠️ 当前项目双版本并行\n\n本仓库包含 **两条独立版本线**，互不干扰、并行发布：\n\n| 版本线 | ClawHub Slug | 当前 latest | 状态 | 文档 |\n|--------|--------------|-------------|------|------|\n| **v1.x**（稳定） | `thesis-workflow` | **v1.7.3** | 长期维护，仅兼容性修复 | [CHANGELOG-v1.md](./CHANGELOG-v1.md) |\n| **v2.x**（新框架） | `thesis-workflow-v2` | **v2.0.14** | ⚠️ 测试版，outline-anchored + 9 HIL + 多工具检索 | [CHANGELOG-v2.md](./CHANGELOG-v2.md) |\n\n### 选型指南\n\n- **生产环境 / 已有 v1 用户** → `thesis-workflow` (v1.7.3，稳定)\n- **新框架 / outline-anchored / 9 HIL 体验** → `thesis-workflow-v2` (v2.0.14，测试)\n- **同时跑多篇论文** → 两个都装，**可共存**\n\n### 怎么装两个？\n\n```bash\n# v1 稳定版（不依赖本仓库）\nopenclaw skills install thesis-workflow\n\n# v2 测试版\nopenclaw skills install thesis-workflow-v2\n```\n\n两者安装路径、状态文件、依赖互不冲突。\n\n详见 [`references/git-workflow.md`](./references/git-workflow.md) 和 [CHANGELOG.md](./CHANGELOG.md) 索引。\n\n---\n\n## 核心功能（v2 框架）\n\n- **outline-anchored 写作**：以大纲为锚点，逐节点生成内容，节点间自动承接\n- **BGE-small-zh 向量标题匹配**：Phase 1.3 开题归因加速 30-90s → 2-5s\n- **多工具并行检索**：4工具（Tavily/arXiv/OpenAlex/web_search）同时搜索，去重排序\n- **Phase 3.5 深度学术评审**：P0/P1/P2 分级问题清单，自动修复 + 重审闭环\n- **RuntimeLLM**：零硬编码，自动复用当前 session 模型配置\n- **9 个 HIL 节点**：human-in-the-loop 检查点，关键决策不跳过\n- **Guardrails 自检**：10 项自动化规范检查（章节完整性/字数/引用/表格格式等）\n- **Loop 架构**：Orchestrator Loop / 内部自检 Loop / 审核 Loop / Verification Loop\n- **Phase 5 Word输出**：[thesis-docx-export](../thesis-docx-export/SKILL.md) skill（独立子 skill，三线表/分页/字体/行距）\n\n## 适用场景TODO_SPLIT\n\n- MBA毕业论文（战略管理/企业分析类）\n- 学术研究报告（竞争战略/行业分析类）\n- 需要多轮审核、多版本整合的正式长文\n\n## 工作流程\n\n```\n用户 → Phase 1（大纲确认 + 开题归因）→ Phase 2（逐节点写作）→ Phase 2.5（用户确认）\n → Phase 3（整合）→ Phase 3.5（深度学术评审 → P0修复循环）\n → Phase 4（修复）→ Phase 5（终审 + Word输出）\n```\n\n## v2.0.x 版本历史（详见 [CHANGELOG-v2.md](./CHANGELOG-v2.md)）\n\n| 版本 | 亮点 |\n|------|------|\n| 2.0.21-beta | HIL #4 消息改为人话版：【节点X 写完：质量Y】 + AI 总结 + 路径 + 动作描述 |\n| 2.0.20-beta | 评审完整文字落盘 + HIL #4 消息简化为路径+选项（避免聊天刷屏）|\n| 2.0.19-beta | context_builder 主题锁定 + 反面警示 总是注入（修复 v8.0 ch1 跑题事故）|\n| 2.0.18-beta | outline_parser 新增 LLM 一次性兑底补全空 hint 节点 |\n| 2.0.17-beta | outline_parser 新增 C 路径：Word 自定义样式（MPA-章标题/一级节标题）支持 |\n| 2.0.12-beta | Phase 3.5 大纲锚定章节拆分（替代硬编码正则）+ P0/P1 修复（F1-F6）|\n| 2.0.11-beta | 清理 v1 残留 + clawhubignore 排除 |\n| 2.0.10-beta | Phase 3.5/4/5 实现 + requirements.txt + lazy BGE |\n| 2.0.9-beta | BGE-small-zh 向量标题匹配（Layer 2） |\n| 2.0.8-beta | multi-search并行引擎 + RuntimeLLM 零硬编码 |\n| 2.0.7 | outline_parser 引擎切换 B→A 单向降级 |\n| 2.0.6 | 双版本独立发布 + enforcement + 真实入口 CLI |\n| 2.0.5 | B-2 状态同步修复 |\n| 2.0.4 | B-1 HIL 死循环修复 |\n| 2.0.3 | P2 代码清理 |\n| 2.0.2 | P0/P1 修复 |\n| 2.0.1 | 方案 C 端到端验证 |\n| 2.0.0 | outline-anchored feature complete |\n\n## Agent 角色体系\n\n| Agent | 调用方式 | 主责 |\n|-------|---------|------|\n| **Orchestrator** | 当前 session | 调度 / 推进 / 决策 |\n| **NodeWriter** | `sessions_spawn` | 逐节点内容生成 |\n| **Reviewer** | `sessions_spawn` | Phase 3/5 规则型审核 |\n| **DeepReviewer** | `sessions_spawn` | Phase 3.5 学术深度评审 |\n| **Integrator** | `sessions_spawn` | Phase 4 整合方案 |\n| **WordAgent** | `exec python3` | md2docx执行 + 格式校验 |\n\n## 版本说明\n\n| 文件命名 | 说明 |\n|---------|------|\n| `论文_xxx.md` | 论文正稿 |\n| `_orchestrate_state.json` | 流程状态（自动管理） |\n| `_outline_state.json` | 大纲状态（自动管理） |\n\n## 写作规范\n\n- **引用格式**：GB/T 7714 作者年制（作者, 年）\n- **正文字数**：≥3.5万字\n- **写作语法**：正文段落禁止 `**加粗**` 强调术语\n- **中文字体**：宋体12磅，行距20磅\n- **英文字体**：Times New Roman\n- **标题字体**：黑体16磅/14磅/13磅\n\n## 技术栈\n\n- OpenClaw subagent (sessions_spawn)\n- BGE-small-zh 中文向量模型（Layer 2 标题匹配）\n- Tavily / arXiv / OpenAlex 多工具并行检索\n- **Word 输出**：见 [thesis-docx-export](../thesis-docx-export/SKILL.md) 独立 skill\n\n## License\n\nMIT-0 — Free to use, modify, and distribute without attribution\n\n## Author\n\nGitHub: [hehe973781230](https://github.com/hehe973781230)\n\n---\n\n*If this skill is helpful to you, please give it a ⭐*\n\nFile v2.1.1-beta.13:thesis-docx-export/README.md\n\n# thesis-docx-export\n\n> 学术论文 Markdown → Word (.docx) 转换 + 格式校验工具集\n\n## 这是什么\n\n把符合学术规范（MBA / 南大 / GB/T 7714）的论文 Markdown 文件转换为 Word 文档，并在转换前后自动跑 Guardrails 校验。\n\n**主要场景**：\n\n1. **主 skill 配套**：`thesis-workflow-v2` 完成 Phase 1-5 后，Phase 5.2 自动调用本 skill 做 Word 转换\n2. **独立使用**：用户手写完论文后，直接用本 skill 校验 + 转换\n\n## 三步导出\n\n```bash\n# 1. 转换前：校验 Markdown 是否符合 10 项 Guardrails\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# 2. 转换：Markdown → Word\npython3 scripts/md2docx_strict.py --input 论文_xxx.md --output 论文_xxx.docx\n\n# 3. 转换后：校验生成的 docx 格式\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n## 安装\n\n```bash\n# 本 skill 是 thesis-workflow-v2 的子模块，已在仓库中。\n# 软链接共享主 skill 的 Python 脚本，单一真实来源。\npip install python-docx pandoc\n```\n\n## 不做什么\n\n- ❌ 不做内容生成（写、审、整合属于 `thesis-workflow-v2`）\n- ❌ 不做 pandoc 直接转换（pandoc 不做三线表、不做 GB/T 7714）\n- ❌ 不做引用文献自动抓取（用 `research_tools.py` 属于主 skill）\n\n## 详细文档\n\n- 格式规范清单：[references/checklist.md](references/checklist.md)\n- 触发场景与边界：见 [SKILL.md](SKILL.md)\n\nFile v2.1.1-beta.13:_meta.json\n\n{\n \"ownerId\": \"kn79wdg0zsjv6rg2zp40xfernd87sp4x\",\n \"slug\": \"thesis-workflow-v2\",\n \"version\": \"2.1.1-beta.13\",\n \"publishedAt\": 1782964927981\n}\n\nFile v2.1.1-beta.13:references/chapter-summary-design.md\n\n# 章节摘要节点设计说明（增强项1 — 跨父节点 Bridge）\n\n> 本文档解释 MBA Thesis Workflow v2.0.0 引入的 **章节摘要节点机制**——为什么要在 L1 章节末尾插入虚拟节点，以及如何利用它解决跨章节 bridge 断裂问题。\n\n---\n\n## 一、问题背景\n\n### 1.1 Bridge 机制回顾\n\nMBA 论文工作流的章节连贯性依赖 `context_builder.generate_bridge()`：\n\n- **P1（前序节点）**：当前节点的前一个兄弟节点（L2 同级）\n- **P2（父节点）**：当前节点的父节点（L1）\n- 任意一个能拿到 `key_conclusion` → 生成承接段\n\n### 1.2 桥断裂场景\n\n考虑以下目录结构：\n\n```\n1. 绪论 (ch1)\n 1.1 研究背景 (L2)\n 1.2 研究内容 (L2)\n2. 理论基础 (ch2)\n 2.1 竞争战略理论 (L2) ← 这节点写 bridge 时\n 2.2 文献综述 (L2)\n```\n\n写 `2.1` 时：\n- **prev** = `1.2`（前序节点的「1.2」） ❌ 跨章节，不是 prev\n- **parent** = `ch2`（父节点）❌ L1 章节通常无 key_conclusion\n- **结果**：bridge = null，NodeWriter 自由发挥开头，连贯性差\n\n这就是 v1.7.3 重审 Agent 反复指出的「bridge 断裂」问题。\n\n---\n\n## 二、方案 C：虚拟章节摘要节点\n\n### 2.1 核心思路\n\n在每个 L1 章节末尾**自动插入**虚拟节点 `__ch{N}_summary__`：\n- 不实际写作（不调用 NodeWriter）\n- 自动汇总本章所有 L2/L3 子节点的 `key_conclusion`\n- LLM 合成 200-300 字章节摘要\n- 下一章节首节点的 bridge 可引用\n\n### 2.2 节点结构\n\n```json\n{\n \"id\": \"__ch1_summary__\",\n \"level\": 1,\n \"title\": \"绪论 — 本章小结\",\n \"is_virtual\": true,\n \"type\": \"chapter_summary\",\n \"synthesizes\": [\"1.1\", \"1.2\"],\n \"chapter_id\": \"ch1\",\n \"chapter_title\": \"绪论\",\n \"key_conclusion\": \"本章从 AI 时代背景出发，提出差异化战略研究问题...\",\n \"writing_status\": \"completed\",\n \"word_count\": 50\n}\n```\n\n### 2.3 数据流\n\n```\n节点 N 写作完成\n ↓\nis_last_child_of_chapter(N) 检测\n ↓ 是\nsynthesize_chapter_summary(chapter_id)\n ↓\n收集 synthesizes 子节点结论 → LLM 合成 200-300 字摘要\n ↓\n写入 __ch{N}_summary__ 节点的 key_conclusion\n ↓\n下一章节首节点 bridge 自动引用（P3 fallback）\n```\n\n---\n\n## 三、Bridge 三级降级链\n\n`generate_bridge()` 新增 P3 优先级：\n\n| 优先级 | 来源 | 函数 | 场景 |\n|--------|------|------|------|\n| P1 | 前序节点 key_conclusion | `_build_bridge_from_prev` | 同章节内连续节点 |\n| P2 | 父节点 key_conclusion | `_build_bridge_from_parent` | 章节内首节点 |\n| **P3（新）** | **上一章节虚拟摘要** | **`_build_bridge_from_chapter_summary`** | **跨章节首节点** |\n\n**降级原则**：\n- 任何上游 key_conclusion 存在 → 立即返回（不走到下一级）\n- 全部为 None → 返回 `None`，NodeWriter 自行处理开头\n\n---\n\n## 四、LLM 失败安全降级（拍板决策 #3）\n\n按2026-06-23拍板决策，**LLM 合成失败时改为询问用户**，而不是简单拼接子节点结论。\n\n```python\ntry:\n response = llm_func(prompt)\n summary = response.strip()\nexcept Exception as e:\n return {\n \"ok\": False,\n \"action\": \"ask_user\", # 关键变化\n \"error\": f\"LLM 调用失败: {str(e)}\",\n \"chapter_id\": chapter_id,\n \"chapter_title\": chapter_title,\n \"child_conclusions\": [...] # 附带子节点结论供 Orchestrator 展示\n }\n```\n\nOrchestrator 收到 `action=\"ask_user\"` 时：\n1. 展示子节点结论给用户\n2. 询问用户手写摘要 / 跳过 / 重试\n3. 用户输入 → 第二次调用 `synthesize_chapter_summary(user_input=...)` → 写入\n\n---\n\n## 五、拍板决策汇总（2026-06-23）\n\n| # | 议题 | 决策 |\n|---|------|------|\n| 1 | 方案选型 | 方案 C（虚拟摘要节点） |\n| 2 | 摘要长度 | 200-300 字 |\n| 3 | LLM 失败处理 | **询问用户**（不简单拼接） |\n| 4 | 章节摘要评审 | 不参与 Phase 3 评审，仅作内部辅助 |\n| 5 | 设计文档 | references/chapter-summary-design.md |\n\n---\n\n## 六、代码落地\n\n| 文件 | 改动 |\n|------|------|\n| `outline_parser.py` | `insert_chapter_summary_nodes()` + 2 个辅助函数 |\n| `orchestrator_v2.py` | `is_last_child_of_chapter()` + `synthesize_chapter_summary()` + `write_single_node()` Step 4.5 |\n| `context_builder.py` | `_build_bridge_from_chapter_summary()` + `generate_bridge()` P3 fallback |\n| `state_manager_v2.py` | `_get_prev_chapter_summary()` + `outline_get_context()` 自动附加 |\n\n---\n\n## 七、测试覆盖（20 个测试用例）\n\n- `test_chapter_summary.py` (6)：节点插入、L3 纳入、幂等、边界、辅助函数\n- `test_synthesize_summary.py` (6)：检测、LLM 路径、用户输入、ask_user、空子节点、超长截断\n- `test_bridge_p3_fallback.py` (6)：P1/P2 优先级、P3 跨章节、不可用降级、首章节、context 自动附加\n- `test_integration_chapter_summary.py` (2)：happy path + LLM 失败 fallback 端到端\n\n总测试数：25 (v1.7.3) + 20 (v1.7.4) = **45 个**（v2.0.0 汇总为 **72 个**）\n\n---\n\n## 八、边界条件\n\n| 场景 | 行为 |\n|------|------|\n| 首章节首节点（1.1） | prev_chapter_summary = None → bridge = None（NodeWriter 自处理） |\n| 用户跳过某些节点 | 摘要只基于 synthesizes 中**已完成**子节点 |\n| LLM 合成失败 | action = \"ask_user\"，不写入 state |\n| 超长摘要（>300 字） | 自动截断到 300 字 |\n| 重复调用 insert | 幂等，已存在虚拟节点时跳过 |\n| 章节无任何子节点 key_conclusion | action = \"ask_user\"，附空列表 |\n\n---\n\n## 九、后续优化方向（非本次范围）\n\n- 章节摘要的版本控制（多版本对比）\n- 摘要参与 Phase 3 评审（如果以后放开拍板 #4）\n- 摘要可由用户直接编辑（不依赖 LLM）\n\nFile v2.1.1-beta.13:references/content-hint-fallback.md\n\n# Content Hint Fallback 设计（v7.0 跑题事故修复）\n\n> **来源文件**：原 SKILL.md 附录 B（外移于 2026-07-02 拆分重构）\n> **生效版本**：自 v2.1.x 起，content_hint fallback 已在 `scripts/context_builder.py` 落地\n\n本文档是 SKILL.md 附录 B 的外移版本，承载具体的修复方案、代码实现、测试用例和验收标准。\nSKILL.md 内的对应位置仅保留指针，避免主文档重复维护。\n\n---\n\n## 附录 B：已批准改进方案 — 大纲约束注入（已实施 2026-06-30）\n\n> **来源**：v7.0 事故复盘 → 龙哥 22:19 反馈，Q3=A / 2026-06-29 \n> **实施状态**：✅ 已实施并验收（2026-06-30）\n> **注意**：本附录不绑具体版本号。以 SKILL.md frontmatter 的 `metadata.clawdbot.version` 为当前 skill 真实版本。\n\n### B.1 背景\n\nv7.0 Phase 2 跑题事故显示：当 `node.content_hint` 为空时，LLM 写作完全依赖章节标题推断上下文，导致 LLM 写出通用 MBA 论文（\"数字经济转型\"），跑偏具体研究对象（A 公司 / vivo / 互联网分发）。\n\n### B.2 目标\n\n当 `node.content_hint` 为空时，**不**直接让 LLM 写，而是构造一个\"大纲骨架 + 反面警示\"的 prompt 约束，确保不跑题。\n\n### B.3 实施方案\n\n修改 `scripts/context_builder.py` 的 `build_prompt_package()` 函数：\n\n```python\n# 现有逻辑\ncontent_hint = current.get(\"content_hint\", \"\").strip()\n\n# v2.x.x 新增（v7.0 跑题事故修复）：当 content_hint 为空时，注入大纲骨架 + 反面警示\nif not content_hint and state:\n outline_skeleton = _build_outline_skeleton(state, node_id)\n paper_subject = _extract_paper_subject(paper_name, state)\n warning_block = _build_no_runoff_warning(paper_subject)\n content_hint = f\"{warning_block}\\n\\n{outline_skeleton}\"\n\npackage = { ..., \"content_hint\": content_hint, ... }\n```\n\n#### B.3.1 新增辅助函数\n\n```python\ndef _extract_paper_subject(paper_name: str, outline_state: Optional[Dict] = None) -> str:\n \"\"\"提取论文主题描述（用于 warning 主题锁定）\n\n 策略：\n 1. 优先从 outline_state[\"outline_tree\"][\"metadata\"][\"paper_title\"] 读\n 2. 否则从 paper_name 去掉版本号后缀\n 3. 兜底返回 paper_name\n \"\"\"\n if outline_state:\n try:\n title = outline_state.get(\"outline\", {}).get(\"outline_tree\", {}).get(\"metadata\", {}).get(\"paper_title\")\n if title and title.strip():\n return title.strip()\n except Exception:\n pass\n import re as _re\n subject = _re.sub(r'(_v\\d+(?:\\.\\d+)*|_final|_\\d{8}_\\d{6})+$', '', paper_name)\n return subject if subject else paper_name\n\n\ndef _build_outline_skeleton(outline_state: Dict, target_node_id: str) -> str:\n \"\"\"构造论文大纲骨架\"\"\"\n try:\n nodes = outline_state.get(\"outline\", {}).get(\"outline_tree\", {}).get(\"nodes\", [])\n except Exception:\n return \"\"\n lines = [\"【论文完整大纲（用于提供上下文）】\", \"\"]\n for n in nodes:\n if n.get(\"is_virtual\"):\n continue\n level = n.get(\"level\", 2)\n prefix = \"#\" * level\n lines.append(f\"{prefix} {n['id']} {n.get('title', '')}\")\n lines.append(\"\")\n lines.append(\"【你正在写的节点】\")\n target = next((n for n in nodes if n.get(\"id\") == target_node_id), None)\n if target:\n lines.append(f\"→ {target.get('title', target_node_id)}（{target_node_id}）\")\n return \"\\n\".join(lines)\n\n\ndef _build_no_runoff_warning(paper_subject: str = \"本研究主题\") -> str:\n \"\"\"反面警示：明确禁止跑题\n\n paper_subject: 论文研究对象描述（建议从 outline metadata.paper_title 取）\n \"\"\"\n return (\n f\"⚠️ 主题锁定：本论文研究对象是「{paper_subject}」。\\n\"\n \"- ✅ 围绕论文具体研究对象的真实业务场景、技术路线、客户/竞争格局等具体实体\\n\"\n \"- ✅ 引用与论文主题相关的权威数据源（行业报告 / 学术文献 / 公司财报）\\n\"\n \"- ❌ 严禁写成通用 MBA 模板论文（如「数字经济 / 企业数字化转型 / 战略管理一般性理论」）\\n\"\n \"- ❌ 严禁「党的二十大报告提出…」这类脱离论文研究主题的泛泛话语\\n\"\n \"- ❌ 严禁用「企业四要素模型 / 波特钻石模型」等通用教科书内容代替研究主题的具体业务场景\"\n )\n```\n\n#### B.3.2 关键设计要点\n\n1. **不破坏现有 `content_hint` 非空的路径**：只有当 hint 为空时才插入骨架\n2. **token 成本低**：大纲骨架 < 1 KB，比塞全文 content（100 KB+）省得多\n3. **覆盖完整**：即使 50 个节点 hint 全空，prompt 里仍有大纲骨架明确\"我在写论文 X 章节 Y\"\n4. **反面警示**：LLM 习惯正面 prompt，加\"❌ 严禁\"反向约束效果更好\n\n### B.4 测试用例\n\n```python\ndef test_content_hint_empty_should_use_skeleton():\n \"\"\"given: node.content_hint = '' when: build_prompt_package then: package['content_hint'] 含大纲骨架 + 反面警示\"\"\"\n pass\n\ndef test_content_hint_present_should_unchanged():\n \"\"\"given: node.content_hint = 'A公司2024年...' when: build_prompt_package then: package['content_hint'] == 原 hint\"\"\"\n pass\n```\n\n### B.5 验收标准\n\n- [x] `_build_outline_skeleton` 输出 < 1500 字（实测 1281 字符）\n- [x] `_build_no_runoff_warning` 输出含至少 3 个 ❌ 禁止项（实测 3 个）\n- [x] 现有非空 hint 路径 PASS（7.2 节点回归通过）\n- [x] Phase 2 跑 1 个节点，验证 prompt 含研究主题关键词（ch1 节点验证通过）\n- [x] 完整 content_hint < 2500 字（实测 1566 字符）\n- [x] 警告块参数化（_build_no_runoff_warning 接受 paper_subject 参数，不再硬编码 A 公司）\n\n### B.6 已完成行动\n\n- [x] 代码实施（context_builder.py + 3 个新函数 + 1 段 fallback 逻辑）\n- [x] 单元级验收（5+1 项 全部通过）\n- [x] 文档同步（SKILL.md 附录 B 代码块与实际代码一致）\n- [ ] CHANGELOG.md 同步（待 v2.0.7 升级时补充）\n- [ ] README.md 改进章节（待 v2.0.7 升级时补充）\n- [ ] ClawHub publish（待 v2.0.7 升级时发布）\n\n数据来源声明：本方案生成于 2026-06-29 龙哥对话，2026-06-30 完成 P0 修复。\n\nFile v2.1.1-beta.13:references/loop-design.md\n\n# Loop 设计说明（v1.7）\n\n> 本文档解释 MBA Thesis Workflow v1.7 引入的 **Loop Agent 架构思想**——为什么要在传统多阶段状态机上\"加 Loop 元素\"，以及如何落地。\n\n---\n\n## 一、为什么引入 Loop 思想？\n\n### 1.1 传统多阶段工作流的问题\n\nMBA 论文写作（v1.6 及之前）是一个**线性多阶段流程**：\n```\nPhase 1 → Phase 2 → Phase 2.5 → Phase 3 → Phase 3.5 → Phase 4 → Phase 5 → Phase 5.1 → Phase 5.2\n```\n\n**痛点**：\n- ❌ 每个 Phase 之间需要**用户手动 trigger**（体验差、效率低）\n- ❌ 审核是**单向线性**（写→审→改→过），没有\"重审直到通过\"的闭环\n- ❌ 规范是写在 SKILL.md 里**靠 Agent 自觉**，没有自动化校验\n- ❌ 失败恢复是**手动打回**（\"返回 Phase 2 重写\"），没有自动重试\n\n### 1.2 Loop Agent 思想的核心价值\n\n**AI Agent Loop**（ReAct / OpenAI Agents SDK）的核心是 **\"感知 → 思考 → 行动 → 观察\"** 的循环，并具备：\n- 自我纠正（self-correction）\n- 自动化工具调用\n- 明确终止条件\n- Human-in-the-loop（关键决策点确认）\n- Guardrails（输入输出校验）\n\n**应用到 MBA 论文工作流**：\n- 现状已经是\"半 Loop 化\"（状态文件、人工门槛、审核机制）\n- 但**缺乏显式的 Loop 编排**和**自动化校验**\n- v1.7 在保留主流程的前提下，**显式声明 5 个 Loop 元素**\n\n### 1.3 不是\"完全 Loop 化\"的理由\n\n**为什么不做\"全自动 Loop Agent\"？**\n\n| 因素 | 说明 |\n|------|------|\n| **高 stakes** | MBA 论文关系到用户年底毕业，错版交付给导师代价极大 |\n| **学术质量不可妥协** | LLM 可能幻觉、跑偏，学术逻辑链需要人工把关 |\n| **决策需要人** | 题目选择、研究方向、整合方案、最终交付——都是用户决策 |\n| **监管/审计** | 导师可能问\"这章怎么来的\"，需要明确的人工审查节点 |\n\n**结论**：采用**多阶段状态机 + 内部 Loop 元素**的混合架构，而非纯 Loop Agent。\n\n---\n\n## 二、5 个 Loop 元素详解\n\n### 2.1 Orchestrator Loop（自动推进）\n\n**目标**：取代\"每步手动 trigger\"。\n\n**实现**：\n- 每 Phase 完成后，Orchestrator 读取 `*_任务状态.json`\n- 根据状态文件 + Guardrails 校验结果，**自动判断下一步**：\n - 通过 → 进入下一 Phase\n - 缺条件 → 提示用户补\n - 出错 → 自动打回当前 Phase 重做\n\n**终止条件**：全部 7 个 Phase 状态都是 `completed`。\n\n**最大重试**：3 次，超过则强制 Human-in-the-loop。\n\n**伪代码**（详见 SKILL.md）：\n```python\ndef decide_next_action(state):\n if state[\"phase\"] == \"Phase 3.5 完成\" and has_p0_issues(state):\n return \"Phase 4 修订（修订后自动重审，最多 3 轮）\"\n ...\n```\n\n### 2.2 Phase 内部自检 Loop（Observe → Think → Act → Verify）\n\n**目标**：每个 Phase 内部遵循四步循环，确保输出符合规范。\n\n**通用模板**：\n```\n1. Observe —— 读取上一阶段产出 + 状态文件\n ↓\n2. Think —— 判断本 Phase 任务清单\n ↓\n3. Act —— 执行 spawn / exec / 文件写入\n ↓\n4. Verify —— 运行 Guardrails 脚本校验\n ↓\n 通过？→ 退出 Phase，更新状态\n 不通过？→ 回到 Step 2 修订（最多 3 次）\n```\n\n**为什么不直接用 OpenClaw 的 Agent Loop？**\n\n- OpenClaw 的 Agent Loop 适合**单次任务**（写一篇文章、调一个 API）\n- MBA 论文是**多阶段长任务**，需要**持久状态**（状态文件）+ **跨 Phase 协调**（状态机）\n- Loop 元素是在每个 Phase 内部\"借用\" Agent Loop 的思想，不破坏主流程的状态边界\n\n### 2.3 审核 Loop（多轮闭环）\n\n**目标**：把审核做成\"审→改→重审→...→通过\"的闭环。\n\n**状态机**：\n```\n[Phase 3 快速审核] → 输出报告\n ↓\n[Phase 3.5 深度评审] → P0/P1/P2 分级\n ↓\n 有 P0？── 是 → [Phase 4 修订] → 重审（仅审 P0）→ ...\n ↑ │\n └──── 连续 2 轮无新 P0 ─────────┘\n │\n 无 P0（仅 P1/P2）──→ [Phase 4 整合] → [Phase 5 终审] → 退出\n```\n\n**关键设计**：\n- **仅重审 P0**：避免 LLM 上下文爆炸（不重复扫描全文）\n- **连续 2 轮无新 P0**：视为通过（容忍小波动）\n- **超过 3 轮强制人工决策**：防止死循环\n\n**重审报告命名**：`审核报告_Phase3.5_v{轮次}.md`，归档保留。\n\n### 2.4 Guardrails 校验（自动化规范检查）\n\n**目标**：把\"应该遵守的规范\"做成自动化脚本，Agent 不再靠自觉。\n\n**脚本**：`scripts/loop_self_check.py`（v1.7 新增）\n\n**10 项校验**：\n1. 章节完整性（7 章齐全）\n2. 字数门槛（每章 ≥ 100 行）\n3. 参考文献存在\n4. 无 `## 第X章` 混合格式\n5. 无 `**正文加粗**` 残留\n6. 引用完整性（作者，年份）模式\n7. 三线表无竖线\n8. 表格标题在表上方\n9. 无合并残留（`===END===`）\n10. 核心章节关键词（第5章战略/第6章实施）\n\n**使用方式**：\n```bash\n# 单文件校验\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# Phase 级别校验\npython3 scripts/loop_self_check.py --phase 2 --workspace ~/.openclaw/workspace/\n\n# JSON 报告（用于自动化）\npython3 scripts/loop_self_check.py --file 论文_xxx.md --json\n```\n\n**失败处理**：\n- 软错误（可自动修复）→ 自动修复并重试\n- 硬错误（需 Agent 决策）→ 打回当前 Phase\n- 累计 3 次失败 → 强制 Human-in-the-loop\n\n### 2.5 Verification Loop（Word 输出校验）\n\n**目标**：Word 输出后自动校验格式，避免错版交付。\n\n**实现**：\n```bash\npython3 scripts/loop_self_check.py --file 论文_xxx_v4.0_终稿.docx --verify-docx\n```\n\n**校验项**：\n- 分页符（每章后）\n- 表格数量\n- 段落数量（≥ 500 段）\n- 标题层级（字体/字号）\n- 行距 20 磅\n- 三线表样式\n\n**失败处理**：\n- 软错误（脚本可修复）→ 自动修复并重新生成\n- 硬错误（数据问题）→ 提示用户并打回 Phase 4\n\n---\n\n## 三、终止条件与边界保护\n\n### 3.1 最大重试机制\n\n每个 Loop 都有**最大重试次数**，防止\"无限循环\"：\n\n| Loop 类型 | 最大重试 | 超过后行为 |\n|----------|---------|-----------|\n| Orchestrator Loop | 3 次 | 强制 Human-in-the-loop |\n| Phase 内部自检 Loop | 3 次 | 强制 Human-in-the-loop |\n| 审核 Loop | 3 轮 | 强制 Human-in-the-loop |\n| Verification Loop | 2 次 | 强制 Human-in-the-loop |\n\n**为什么不设更多？**\n- 超过 3 次仍未通过 → 说明问题超出 Loop 自动化能力\n- 必须让用户决策（继续 / 调整方向 / 接受当前版本）\n\n### 3.2 Human-in-the-loop 检查点\n\n以下节点**必须**用户确认，不能由 Loop 自动跳：\n\n| 检查点 | 确认内容 | 不确认的后果 |\n|-------|---------|------------|\n| **Phase 1 末尾** | 写作任务书（题目/公司映射/大纲） | 方向错了全白做 |\n| **Phase 2.5 末尾** | 章节内容是否符合预期 | 跑偏了审完也白审 |\n| **Phase 4 末尾** | 整合方案是否接受 | 整合错了质量更差 |\n| **Phase 5.2 末尾** | Word 文档是否符合预期 | 错版交付给导师 |\n\n**设计哲学**：\n- 流程性、规则性、可自动化的 → Loop 处理\n- 战略性、决策性、需要人类判断的 → 人工处理\n\n### 3.3 状态文件机制（持久化）\n\n`论文_{题目}_任务状态.json` 是 Loop 之间的\"记忆\"：\n\n```json\n{\n \"paper\": \"A公司互联网分发业务竞争战略研究\",\n \"version\": \"v1.0\",\n \"phase\": \"Phase 3.5\",\n \"started_at\": \"2026-06-12 07:00\",\n \"last_updated\": \"2026-06-12 08:30\",\n \"review_loop\": {\n \"current_round\": 2,\n \"p0_fixed\": [\"P0-1\", \"P0-2\"],\n \"p0_pending\": [\"P0-3\"],\n \"max_rounds\": 3\n },\n \"chapters\": {\n \"chapter1_2_7\": {\"status\": \"completed\", \"file\": \"...\", \"lines\": 850},\n \"chapter3_4\": {\"status\": \"completed\", \"file\": \"...\", \"lines\": 1200},\n \"chapter5_6\": {\"status\": \"completed\", \"file\": \"...\", \"lines\": 1100}\n }\n}\n```\n\n**作用**：\n- Orchestrator Loop 读取状态判断下一步\n- Review Loop 读取 `current_round` 决定是否重审\n- 中断后恢复（session 重启后从状态文件继续）\n\n---\n\n## 四、与 OpenClaw Agent Loop 的对应\n\n| OpenClaw / Loop Agent 概念 | MBA Skill v1.7 实现 |\n|--------------------------|---------------------|\n| **Agent loop**（自动推进） | Orchestrator Loop |\n| **Tool invocation** | sessions_spawn / exec / hermes chat |\n| **Self-correction** | 审核 Loop（Phase 3 + 3.5 + 修订） |\n| **Guardrails** | loop_self_check.py 脚本（10 项校验） |\n| **Human-in-the-loop** | Phase 1/2.5/4 强制用户确认 |\n| **Sessions**（持久状态） | `*_任务状态.json` |\n| **Tracing**（追踪） | 各 Phase 输出文件 + 状态文件 |\n| **Verification** | Verification Loop（Word 格式校验） |\n| **MCP tools** | multi-search-engine / academic-research / arxiv-search-collector |\n| **Sandbox** | sessions_spawn 子 agent 隔离执行 |\n\n**关键差异**：\n- **OpenClaw Agent Loop**：单次任务内循环（适合写一篇文章、调一个 API）\n- **MBA Skill v1.7**：**多阶段状态机 + 每阶段内部 Loop**（适合长任务、有明确状态边界的复杂工作）\n\n---\n\n## 五、未来扩展方向\n\n### 5.1 短期（v1.8 - v1.9）\n\n- [ ] **Orchestrator Loop 完整实现**：把伪代码变成可执行的 `orchestrator.py`\n- [ ] **状态文件自动生成**：每 Phase 启动时自动创建/更新 `*_任务状态.json`\n- [ ] **Guardrails 软错误自动修复**：例如 `**正文加粗**` 自动去除、`## 第X章` 自动纠正\n- [ ] **审核 Loop 报告对比工具**：自动 diff 两轮审核报告，识别\"新增 P0\"\n\n### 5.2 中期（v2.0）\n\n- [ ] **多论文并行支持**：用状态文件隔离，同时跑多篇论文\n- [ ] **审核报告自动归档**：所有 Phase 3.5 报告统一管理，支持历史回溯\n- [ ] **导师反馈 Loop**：接入导师的批注，自动生成\"导师反馈 → 修订 → 复审\"闭环\n- [ ] **Word 模板自定义**：支持不同学校（南大、复旦、交大等）的论文模板\n\n### 5.3 长期（v3.0+）\n\n- [ ] **AI 辅助选题**：Phase 1 前置 Loop，根据用户方向自动推荐题目 + 大纲\n- [ ] **文献自动追踪**：论文写作过程中自动追踪相关领域新论文\n- [ ] **答辩 PPT 自动生成**：基于终稿自动生成答辩 PPT\n- [ ] **跨论文知识库**：所有论文的素材、参考文献、模板沉淀为可复用知识库\n\n---\n\n## 六、参考资料\n\n- **ReAct 论文**（arXiv:2210.03629）：https://arxiv.org/abs/2210.03629\n- **OpenAI Agents SDK Agent Loop 概念**：https://openai.github.io/openai-agents-python/\n- **OpenAI Operator / CUA 介绍**：https://openai.com/index/introducing-operator/\n- **Anthropic Computer Use 文档**：（抓取失败，可参考 OpenAI Operator 的设计思路）\n\n---\n\n> **维护者**：MBA Skill v1.7 引入，最后更新 2026-06-12。\n> **反馈**：发现 Loop 元素设计问题，提交 issue 或直接修订本文档。\n\nFile v2.1.1-beta.13:thesis-docx-export/references/checklist.md\n\n# MBA 论文学术规范检查清单（v1.7）\n\n> 本文档是 **Guardrails 校验项**的人工对照清单。\n> 自动化脚本：`scripts/loop_self_check.py`\n> 使用方式：每个 Phase 退出前对照本清单 + 运行脚本，确保 100% 通过。\n\n---\n\n## 一、格式维度（18 项）\n\n### 1.1 封面\n\n- [ ] 包含：学校代码\n- [ ] 包含：分类号\n- [ ] 包含：密级\n- [ ] 包含：UDC\n- [ ] 包含：论文题目\n- [ ] 包含：作者姓名\n- [ ] 包含：专业\n- [ ] 包含：研究方向\n- [ ] 包含：导师\n- [ ] 包含：答辩日期\n\n### 1.2 原创性声明\n\n- [ ] 包含声明正文\n- [ ] 包含签名栏\n- [ ] 包含日期\n- [ ] 位置：封面之后、摘要之前\n\n### 1.3 中文摘要\n\n- [ ] 标题\"摘要\"两字间空两格\n- [ ] 标题：黑体 16 磅加粗居中，单倍行距\n- [ ] 标题段前 24 磅、段后 18 磅\n- [ ] 内容：宋体 12 磅（小四）\n- [ ] 内容：行距 20 磅，段前段后 0 磅\n- [ ] **内容字数 ≥ 800 字** ⚠️\n- [ ] 关键词 3-5 个\n- [ ] 关键词格式：分号分隔，\"关键词\"三字加粗\n\n### 1.4 英文摘要\n\n- [ ] 标题\"Abstract\"（Arial 16 磅加粗居中）\n- [ ] 内容：Times New Roman 12 磅\n- [ ] 行距 20 磅\n- [ ] 关键词 3-5 个，\"Key Words\"加粗\n- [ ] 中英文关键词一一对应\n\n### 1.5 目录\n\n- [ ] 标题\"目录\"两字间空两格（黑体 16 磅加粗居中）\n- [ ] 从绪论开始列出\n- [ ] 一级节：宋体 12 磅加粗\n- [ ] 二级节：仿宋 10.5 磅\n- [ ] 页码右对齐\n- [ ] 纳入 1-3 级标题\n\n### 1.6 正文各章标题\n\n- [ ] 格式：`# 第X章 ×××`\n- [ ] 黑体 16 磅加粗居中\n- [ ] 单倍行距，段前 24 磅、段后 18 磅\n- [ ] 章序号与章名称之间空两格\n- [ ] **每章另起一页（分页符）** ⚠️\n\n### 1.7 标题层级\n\n- [ ] 一级节：`## 1.2 ×××`（黑体 14 磅）\n- [ ] 二级节：`### 1.2.1 ×××`（黑体 13 磅）\n- [ ] 三级节：`### （1）×××`（宋体 12 磅）\n- [ ] 禁止使用 `## 第X章` 混合格式 ⚠️\n- [ ] 禁止使用 `### 第X.X` 混合格式\n\n### 1.8 正文段落\n\n- [ ] 宋体 12 磅（英文 Times New Roman 12 磅）\n- [ ] 两端对齐，首行左缩进 2 个汉字符\n- [ ] 段前段后 0 磅\n- [ ] **行距 20 磅** ⚠️\n- [ ] **正文中无 `**加粗**` 强调术语** ⚠️\n\n### 1.9 图号图题\n\n- [ ] 图号 + 图题置于图**下方**\n- [ ] 宋体 10.5 磅加粗居中\n- [ ] 单倍行距，段前 6 磅、段后 12 磅\n- [ ] 图注左缩进两字\n- [ ] 图中文字宋体 10.5 磅\n\n### 1.10 表号表题\n\n- [ ] 表号 + 表题置于表**上方**\n- [ ] 宋体 10.5 磅加粗居中\n- [ ] 单倍行距，段前 6 磅、段后 6 磅\n- [ ] 表注左缩进两字\n- [ ] 表格标题不应加粗\n\n### 1.11 表格\n\n- [ ] **三线表**（顶线、表头底线、底线）⚠️\n- [ ] 无竖线\n- [ ] 表格内无 `**加粗**` 残留\n- [ ] 表头与数据行分明\n\n### 1.12 图表编号\n\n- [ ] 阿拉伯数字分章依序连续编码\n- [ ] 格式示例：\"图 1.1\"、\"表 3.2\"\n- [ ] 引用格式自然句式：\"如图 1.1 所示\"（非 `**图 1.1**` 加粗）\n\n### 1.13 注释\n\n- [ ] **页下注**（非上标形式）⚠️\n- [ ] 编号：①②③……连续\n- [ ] 不得使用上标加序号\n\n### 1.14 参考文献\n\n- [ ] 正文引用：**作者年制**（不得使用上标加序号）⚠️\n- [ ] 文后\"参考文献\"标题左对齐\n- [ ] **中英文分编** + **字母排序** ⚠️\n- [ ] 中文：宋体小四号全角标点\n- [ ] 英文：Times New Roman 小四号\n- [ ] 英文作者姓前名后缩写\n- [ ] 杂志名书名斜体\n- [ ] 同一作者同年多篇加 a/b/c 区分\n\n### 1.15 页码\n\n- [ ] 前置部分（封面/声明/摘要/目录）：罗马数字\n- [ ] 正文部分（从绪论起）：阿拉伯数字\n\n### 1.16 附录\n\n- [ ] 标题格式同章标题\n- [ ] 内容格式同正文\n- [ ] 大写字母 A/B/C 编序号（如\"附录 A\"）\n- [ ] 只有一个附录名为\"附录\"不编号\n- [ ] 图表编号与正文分开（如\"图 A.1\"）\n\n### 1.17 致谢\n\n- [ ] 标题\"致谢\"两字间空两格\n- [ ] 格式同章标题\n- [ ] 内容格式同正文\n\n### 1.18 写作语法\n\n- [ ] 正文段落中无 `**xxx**` 加粗术语 ⚠️\n- [ ] 列表项小标题用 `###` 升为正式节标题\n- [ ] 表格标题行是普通段落文字\n- [ ] 引用图表用自然句式\n- [ ] 过渡句式自然，不大量使用 `**xxx领域**` 加粗术语\n\n---\n\n## 二、大纲维度（2 项）\n\n- [ ] 每章内容不超出原定大纲范围（超出章节标★）\n- [ ] **每章 ≥ 2 节，每节 ≥ 2 点，每点 ≥ 5 行** ⚠️\n\n---\n\n## 三、内容准确性维度（2 项）\n\n- [ ] 每引用一个理论/数据必须标注来源（无来源结论标⚠️）\n- [ ] 正文数据前后无矛盾（矛盾处标⚠️）\n\n---\n\n## 四、查重风险维度（1 项）\n\n- [ ] **连续 ≥ 30 字与参考文献重合标🔴，需 paraphrase** ⚠️\n\n---\n\n## 五、学术规范维度（6 项）\n\n- [ ] **引用标注完整率必须达到 100%** ⚠️\n- [ ] 术语首次出现须全称 + 后续简称\n- [ ] 正文中文格式：1 人 / 2 人 / 3+ 人\n- [ ] 正文英文格式：1 人 / 2 人 / 3+ 人\n- [ ] 文后中文格式：期刊 / 专著 / 论文集\n- [ ] 文后英文格式：作者姓写在前名缩写在后，杂志名书名斜体\n\n---\n\n## 六、章节完整性（10 项 Guardrails 自动化校验项）\n\n> 以下 10 项由 `scripts/loop_self_check.py` 自动校验。\n\n- [ ] **章节完整性**：必须包含 `# 第1章` 到 `# 第7章` 全部 7 章\n- [ ] **字数门槛**：每章 ≥ 100 行（全文 ≥ 700 行）\n- [ ] **参考文献存在**：包含 `## 参考文献` 标题\n- [ ] **标题层级**：无非法的 `## 第X章` 混合格式\n- [ ] **正文加粗**：无 `**xxx**` 残留\n- [ ] **引用完整性**：至少 10 处 `(作者，年份)` 模式\n- [ ] **三线表**：无多余竖线\n- [ ] **表格标题**：表格标题在表上方\n- [ ] **合并残留**：无 `===END===` 等残留标识\n- [ ] **核心章节关键词**：\n - 第 5 章包含：战略选择 / 竞争战略 / 差异化 / 集中化 / 成本领先 / QSPM\n - 第 6 章包含：实施 / 保障 / 组织 / 人才 / 财务 / KPI / 考核\n\n---\n\n## 七、Word 输出校验（Verification Loop）\n\n> Word 文档输出后由 `loop_self_check.py --verify-docx` 自动校验。\n\n- [ ] **分页符**：每章后有分页符\n- [ ] **三线表**：表格为三线表样式\n- [ ] **标题层级**：黑体 16/14/13 磅\n- [ ] **正文行距**：20 磅\n- [ ] **加粗已过滤**：无 `**残留**`\n- [ ] **参考文献分编**：中文 + 英文分两块\n- [ ] **段落数量**：≥ 500 段\n- [ ] **表格数量**：> 0\n\n---\n\n## 八、Phase 退出门禁\n\n每个 Phase 退出前必须 100% 通过本清单的对应项 + Guardrails 脚本：\n\n| Phase | 必查项 | 退出条件 |\n|-------|--------|---------|\n| **Phase 1** | 一、1.18 + 二、 | 写作任务书用户签收 |\n| **Phase 2** | 一、全部 + 三、 + 六、 | 全部 7 章完成 + Guardrails 100% |\n| **Phase 2.5** | 六、第 10 项（核心章节关键词） | 用户确认章节内容 |\n| **Phase 3** | 一、全部 | 审核报告 H + O 完整 |\n| **Phase 3.5** | 一、二、三、四、五、 | P0/P1/P2 分级完整 |\n| **Phase 4** | 一、全部 + 六、 | 整合版 Guardrails 100% |\n| **Phase 5** | 一、全部 + 七、 | Word 格式 100% |\n| **Phase 5.1** | （去 AI 味） | 差异报告生成 |\n| **Phase 5.2** | 七、 | Word 文档 + 邮件发送 |\n\n---\n\n## 九、违规等级与处理\n\n| 等级 | 标记 | 处理方式 |\n|------|------|---------|\n| 🔴 P0 | 致命错误（章节缺失、参考文献缺失、合并残留） | **必须修复**，否则阻断 Phase 推进 |\n| 🟡 P1 | 严重问题（标题层级错误、加粗残留、字数不足） | **必须修复**，累计 3 项打回 Phase |\n| ⚠️ P2 | 一般问题（个别引用缺失、图表编号不规范） | **建议修复**，可在 Phase 5 终审前统一修订 |\n| 💡 建议 | 优化项（措辞、过渡句式） | **可选**，可放入 Phase 5.1 去 AI 味 |\n\n---\n\n## 十、参考规范来源\n\n- 《南京大学研究生学位论文格式规范》（最新版）\n- 《GB/T 7714-2015 文后参考文献著录规则》\n- MBA Skill v1.6 既有规范\n- Loop Self-Check Script v1.7\n\n---\n\n> **维护者**：MBA Skill v1.7 引入，最后更新 2026-06-12。\n> **使用建议**：打印此清单，每 Phase 退出前对照打勾。\n\nFile v2.1.1-beta.13:scripts/phase_manager/DESIGN.md\n\n# Phase Manager 模块设计方案\n\n> 创建时间：2026-06-30\n> 状态：已设计，待实现\n> 目录：`scripts/phase_manager/`\n\n---\n\n## 一、模块定位与目标\n\n### 1.1 解决的问题\n\n当前 HIL 节点将 Phase 产出直接渲染到 chat 窗口，存在三大问题：\n1. **信息截断** — 大论文数十KB内容无法完整返回\n2. **上下文浪费** — token 被正文消耗，核心元数据被淹没\n3. **用户无法细改** — 只能整体接受/拒绝，无法局部编辑\n\n### 1.2 模块定位\n\n每个 Phase 的**数据中枢**：\n- 管理输入/输出文件的生命周期\n- 提供门禁校验（准入/准出）\n- 生成 HIL 消息（只含路径+摘要，不塞正文）\n- 保证跨 Session 数据有效性\n\n**独立性强**：只依赖 Python stdlib，不依赖业务模块，可独立测试和移植。\n\n### 1.3 设计原则\n\n| 原则 | 说明 |\n|------|------|\n| 文件优先 | Phase 产出存入文件，不塞 chat |\n| 用户可编辑 | 用户可直接改文件，下一 Phase 读取新内容 |\n| 有效性保障 | 读写前做 freshness check + hash 校验 |\n| 幂等安全 | 已完成 Phase 的内容非 force 不可覆盖 |\n| 清理可控 | 中间态文件及时清理，重要产出持久化 |\n\n---\n\n## 二、目录结构\n\n```\nscripts/phase_manager/\n├── __init__.py ← 导出 PhaseManager 主类\n├── schemas.py ← 数据契约（PhaseSummary / PhaseFile / PhaseTransition）\n├── file_manager.py ← 文件生命周期管理\n├── gate_keeper.py ← 门禁校验\n├── summary_generator.py ← 摘要生成\n├── hil_renderer.py ← HIL 消息渲染\n└── DESIGN.md ← 本文档\n```\n\n---\n\n## 三、数据契约（schemas.py）\n\n### 3.1 PhaseSummary\n\n```python\n@dataclass\nclass PhaseSummary:\n phase: int # Phase 编号（1-5）\n status: str # pending | running | completed | failed | modified\n timestamp: str # ISO timestamp（最后修改时间）\n file_path: str # 产出文件路径\n content_hash: str # 内容哈希（MD5，用于检测用户是否改过）\n word_count: int # 中文字数\n chapter_count: int # 章节数\n key_metrics: Dict[str, Any] # 关键指标（见下方）\n user_modifications: bool # 用户是否手动修改过文件\n message: str # 一句话摘要\n\n # key_metrics 字段说明\n # Phase 2: {\"nodes_total\": N, \"nodes_completed\": N, \"nodes_failed\": N}\n # Phase 3: {\"p0_issues\": 0, \"p1_issues\": N, \"p2_issues\": N, \"guardrails_passed\": True}\n # Phase 3.5: 同 Phase 3\n # Phase 4: {\"integrated_word_count\": N, \"changes_applied\": N}\n # Phase 5: {\"word_count\": N, \"guardrails_passed\": True}\n```\n\n### 3.2 PhaseFile\n\n```python\n@dataclass\nclass PhaseFile:\n phase: int # Phase 编号\n content_type: str # integrated | review | summary\n file_path: str # 文件绝对路径\n hash: str # 内容哈希\n size_bytes: int # 文件大小\n created_at: str # ISO timestamp\n updated_at: str # ISO timestamp\n backup_path: Optional[str] # 备份文件路径（上一版本）\n```\n\n**content_type 说明**：\n- `integrated` — 整合版正文（.md）\n- `review` — 审核报告（.json）\n- `summary` — 结构化摘要（.json）\n\n### 3.3 PhaseTransition\n\n```python\n@dataclass\nclass PhaseTransition:\n from_phase: int # 来源 Phase\n to_phase: int # 目标 Phase\n triggered_by: str # auto | user_confirm | user_modify\n triggered_at: str # ISO timestamp\n triggered_session: str # 触发时的 session ID\n content_hash: str # 触发时的文件哈希\n gate_passed: bool # 门禁是否通过\n```\n\n### 3.4 GateResult\n\n```python\n@dataclass\nclass GateResult:\n passed: bool # 是否通过\n phase: int # 检查的 Phase\n checks: Dict[str, Tuple[bool, str]] # {check_name: (passed, detail)}\n blocking_issues: List[str] # 阻塞性问题列表\n\n def summary(self) -> str:\n \"\"\"生成人类可读的 gate 结果摘要\"\"\"\n```\n\n---\n\n## 四、文件命名规范\n\n| 文件名模式 | 示例 | 用途 |\n|-----------|------|------|\n| `_phase{N}_{integrated/review/summary}.md` | `_phase3_integrated.md` | Phase N 整合版正文 |\n| `_phase{N}_{integrated/review/summary}.json` | `_phase3_review.json` | Phase N 审核报告/摘要 |\n| `_phase{N}_{integrated/review/summary}.md.bak` | `_phase3_integrated.md.bak` | 上一版本备份 |\n| `_phase{N}.lock` | `_phase3.lock` | 写入锁（防并发） |\n| `_phase{N}_summary.json` | `_phase3_summary.json` | PhaseSummary 结构化摘要 |\n| `_transition.json` | `_transition.json` | Phase 流转记录 |\n\n---\n\n## 五、核心类实现规格\n\n### 5.1 PhaseFileManager\n\n**职责**：文件生命周期管理（CRUD + 版本控制 + 清理）\n\n```python\nclass PhaseFileManager:\n FRESHNESS_THRESHOLD_HOURS = 48 # 文件新鲜度阈值\n WORKSPACE_BASE = \"~/.openclaw/workspace\" # 工作区根目录\n\n def __init__(self, paper_name: str, workspace: str = None):\n self.paper_name = paper_name\n self.workspace = workspace or os.path.join(\n os.path.expanduser(WORKSPACE_BASE), paper_name\n )\n os.makedirs(self.workspace, exist_ok=True)\n\n # ---- 路径计算 ----\n def get_file_path(self, phase: int, content_type: str, ext: str = None) -> str:\n \"\"\"\n 返回指定 Phase + 类型的目标文件路径。\n ext 默认为 md（integrated）或 json（review/summary）。\n \"\"\"\n\n # ---- 生命周期：保存 ----\n def save_content(self, phase: int, content_type: str, content: str,\n create_backup: bool = True) -> Dict[str, Any]:\n \"\"\"\n 保存内容。\n\n 流程：\n 1. 计算 content_hash\n 2. 检查是否有内容变化（hash 对比）\n 3. 有变化且 create_backup=True → 自动备份旧版本到 .bak\n 4. 写入新内容（带 .lock 保护）\n 5. 更新 state 中的 hash 记录\n 6. 校验文件完整性\n\n 返回：{\n ok: bool,\n hash: str,\n backup_path: Optional[str],\n size_bytes: int,\n changed: bool,\n error: Optional[str]\n }\n \"\"\"\n\n # ---- 生命周期：读取 ----\n def load_content(self, phase: int, content_type: str) -> Optional[str]:\n \"\"\"\n 读取指定文件内容。\n 文件不存在或校验失败 → 返回 None\n \"\"\"\n\n # ---- 新鲜度校验 ----\n def is_fresh(self, phase: int, content_type: str) -> bool:\n \"\"\"\n 检查文件是否新鲜：\n 1. 文件存在\n 2. 修改时间在 FRESHNESS_THRESHOLD_HOURS 内\n 3. content_hash 与 state 中记录一致\n \"\"\"\n\n def validate_before_read(self, phase: int, content_type: str) -> Dict:\n \"\"\"\n 读取前校验：\n - 文件存在\n - 未过期\n - hash 一致\n\n 返回：{ok: bool, error: Optional[str], fresh: bool, hash_changed: bool}\n \"\"\"\n\n # ---- 用户修改检测 ----\n def detect_user_modification(self, phase: int, content_type: str) -> bool:\n \"\"\"\n 通过 content_hash 对比，检测用户是否手动修改了文件。\n 流程：\n 1. 读取当前文件的真实 hash\n 2. 对比 state 中记录的 hash\n 3. 不一致 → 用户改过\n \"\"\"\n\n # ---- 版本控制 ----\n def backup_exists(self, phase: int, content_type: str) -> bool:\n \"\"\"检查是否有 .bak 备份版本\"\"\"\n\n def restore_backup(self, phase: int, content_type: str) -> Dict:\n \"\"\"\n 恢复上一备份版本。\n 返回：{ok: bool, restored_path: str}\n \"\"\"\n\n # ---- 清理 ----\n def cleanup_intermediate(self, phase: int,\n keep_types: List[str] = None) -> Dict:\n \"\"\"\n 清理指定 Phase 的中间文件。\n\n keep_types 默认：[\"integrated.md\", \"review.json\", \"summary.json\"]\n 删除：.tmp / .bak / .lock 等临时文件\n\n 返回：{ok: bool, deleted: [file_paths]}\n \"\"\"\n\n def cleanup_all_intermediates(self) -> Dict:\n \"\"\"\n 清理所有 Phase 的中间文件（保留最终产出）。\n 用于论文完成后收尾。\n \"\"\"\n\n # ---- 写入锁（防并发）----\n def save_with_lock(self, phase: int, content_type: str,\n content: str) -> Dict:\n \"\"\"\n 写入时加锁，防止并发覆盖。\n 1. 检查 .lock 文件\n 2. 有锁 → 报错 \"文件正在被编辑，请稍后\"\n 3. 无锁 → 创建锁 → 写入 → 删除锁\n 4. finally 确保锁释放\n \"\"\"\n```\n\n### 5.2 PhaseGateKeeper\n\n**职责**：Phase 流转门禁校验（准入/准出）\n\n```python\nclass PhaseGateKeeper:\n # 通用门禁规则\n GATE_RULES = {\n \"min_word_count\": 1000, # 最小字数\n \"max_word_count\": 200000, # 最大字数（异常检测）\n \"chapter_count\": 7, # 章节数要求\n \"freshness_hours\": 48, # 文件新鲜度\n }\n\n def __init__(self, paper_name: str):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name)\n\n # ---- 准入检查（进入 Phase N 前）----\n def pre_enter_check(self, target_phase: int) -> GateResult:\n \"\"\"\n 检查是否可以进入 target_phase。\n\n 规则：\n - Phase 2 前：Phase 1.2 大纲已确认 + Phase 1.3 已提交\n - Phase 3 前：Phase 2 全部节点 completed，无 failed\n - Phase 3.5 前：Phase 3 review 已完成\n - Phase 4 前：Phase 3.5 收敛（连续 2 轮无新 P0）\n - Phase 5 前：Phase 4 guardrails 10/10 通过\n\n 返回：GateResult\n \"\"\"\n\n # ---- 准出检查（Phase N 完成前）----\n def pre_exit_check(self, current_phase: int) -> GateResult:\n \"\"\"\n 检查当前 Phase 是否满足完成条件。\n\n 规则：\n - Phase 2：节点完成率 100%，无 failed 节点\n - Phase 3：审核 loop 收敛（连续 2 轮无新 P0）\n - Phase 3.5：同 Phase 3\n - Phase 4：整合版 guardrails 10 项校验通过\n - Phase 5：Word 输出格式校验通过\n\n 返回：GateResult\n \"\"\"\n\n # ---- 通用门禁项 ----\n def check_word_count(self, phase: int, content_type: str = \"integrated\") -> Tuple[bool, str]:\n \"\"\"字数是否在合理范围\"\"\"\n\n def check_chapter_completeness(self, phase: int, content_type: str = \"integrated\") -> Tuple[bool, str]:\n \"\"\"章节是否完整（7 章）\"\"\"\n\n def check_freshness(self, phase: int, content_type: str = \"integrated\") -> Tuple[bool, str]:\n \"\"\"文件是否新鲜（48 小时内有更新）\"\"\"\n\n def check_hash_unchanged(self, phase: int, content_type: str,\n expected_hash: str) -> Tuple[bool, str]:\n \"\"\"文件 hash 是否与预期一致（检测用户修改）\"\"\"\n```\n\n### 5.3 PhaseSummaryGenerator\n\n**职责**：将 Phase 产出转化为结构化摘要\n\n```python\nclass PhaseSummaryGenerator:\n def __init__(self, paper_name: str):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name)\n\n def generate_phase_summary(self, phase: int,\n phase_result: Dict = None) -> PhaseSummary:\n \"\"\"\n 从 Phase 执行结果或文件中提取 PhaseSummary。\n\n 输入：Phase 执行结果（可能包含大量 content）\n 输出：PhaseSummary（不含正文，只有元数据）\n\n 流程：\n 1. 如果有 phase_result，直接从中提取指标\n 2. 否则，从文件读取内容并分析\n 3. 计算 word_count、chapter_count、content_hash\n 4. 组装 PhaseSummary\n \"\"\"\n\n def calculate_word_count(self, content: str) -> int:\n \"\"\"计算中文字数（不含标点、空格、英文）\"\"\"\n\n def calculate_hash(self, content: str) -> str:\n \"\"\"计算内容 MD5 哈希\"\"\"\n\n def extract_chapter_count(self, content: str) -> int:\n \"\"\"从正文中提取章节数（# 第X章 计数）\"\"\"\n\n def build_key_metrics(self, phase: int, phase_result: Dict) -> Dict:\n \"\"\"\n 根据 Phase 类型构建 key_metrics。\n\n Phase 2: {nodes_total, nodes_completed, nodes_failed, completion_rate}\n Phase 3: {p0_issues, p1_issues, p2_issues, guardrails_passed, guardrails_detail}\n Phase 3.5: 同 Phase 3\n Phase 4: {integrated_word_count, changes_applied, guardrails_passed}\n Phase 5: {word_count, guardrails_passed, docx_generated}\n \"\"\"\n```\n\n### 5.4 PhaseHILRenderer\n\n**职责**：HIL 消息渲染（只输出路径+摘要，不塞正文）\n\n```python\nclass PhaseHILRenderer:\n def __init__(self, paper_name: str):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name)\n\n def render_hil_message(self, phase: int, summary: PhaseSummary,\n next_phase: int = None,\n user_modified: bool = False) -> str:\n \"\"\"\n 渲染 HIL 消息。\n\n 输出格式（Markdown）：\n\n ✅ Phase {N} 整合完成\n\n 📄 文件：{file_path}\n 📊 字数：{word_count} 字 | 章节：{chapter_count} 章\n 🔍 审核结果：{审核摘要}\n 🛡️ Guardrails：{通过情况}\n 🕐 时间：{timestamp}\n {用户修改提示（如有）}\n\n 下一阶段：Phase {N+1}\n 操作指令：\n - [确认] → 进入 Phase {N+1}\n - [修改文件] → 直接编辑上方文件后说\"确认修改\"\n - [重新审核] → 重新跑 Phase {N} review\n \"\"\"\n\n def render_gate_failure(self, phase: int, gate_result: GateResult) -> str:\n \"\"\"\n 渲染门禁未通过的消息。\n\n 输出格式：\n\n ⚠️ Phase {N} 门禁未通过\n\n 阻塞问题：\n - {issue 1}\n - {issue 2}\n\n 请修复上述问题后重试。\n \"\"\"\n\n def render_phase_status(self, phase: int) -> str:\n \"\"\"\n 渲染 Phase 当前状态（用于 --status 查询）。\n \"\"\"\n\n def render_user_modification_warning(self, phase: int,\n old_hash: str,\n new_hash: str) -> str:\n \"\"\"\n 检测到用户修改文件时的提示。\n \"\"\"\n```\n\n### 5.5 PhaseManager（主类，Facade 模式）\n\n```python\nclass PhaseManager:\n \"\"\"\n Phase 数据管理的统一入口（Facade 模式）。\n\n 对 orchestrator 暴露简单接口，屏蔽内部复杂度。\n \"\"\"\n\n def __init__(self, paper_name: str, workspace: str = None):\n self.paper_name = paper_name\n self.fm = PhaseFileManager(paper_name, workspace)\n self.gk = PhaseGateKeeper(paper_name)\n self.sg = PhaseSummaryGenerator(paper_name)\n self.hr = PhaseHILRenderer(paper_name)\n\n # ---- 核心流程 ----\n def save_phase_output(self, phase: int, content_type: str,\n content: str,\n key_metrics: Dict = None) -> Dict:\n \"\"\"\n 保存 Phase 产出。\n\n 1. 保存内容到文件\n 2. 生成 PhaseSummary\n 3. 保存 summary 到 _phase{N}_summary.json\n 4. 返回 {ok, file_path, summary}\n\n 用户可直接改文件，改完说\"确认\"后下一 Phase 读取。\n \"\"\"\n\n def load_phase_input(self, phase: int,\n content_type: str = \"integrated\") -> Optional[str]:\n \"\"\"\n 读取上一 Phase 的产出。\n\n 读取前做 freshness check。\n 检测到用户修改 → 在返回内容中附带 user_modified=True 标记。\n \"\"\"\n\n def pre_phase_check(self, target_phase: int) -> GateResult:\n \"\"\"\n 进入 Phase N 前的门禁检查。\n 不通过 → 返回错误，不允许进入。\n \"\"\"\n\n def pre_exit_check(self, current_phase: int) -> GateResult:\n \"\"\"\n Phase N 完成前的门禁检查。\n 不通过 → 返回错误，不允许完成。\n \"\"\"\n\n def generate_hil_message(self, phase: int,\n next_phase: int = None) -> str:\n \"\"\"\n 生成 HIL 消息（供用户确认/修改）。\n \"\"\"\n\n # ---- 状态查询 ----\n def get_phase_status(self, phase: int) -> Dict:\n \"\"\"\n 返回 Phase N 的当前状态。\n \"\"\"\n\n def get_all_phase_status(self) -> List[Dict]:\n \"\"\"\n 返回所有 Phase 的状态列表。\n \"\"\"\n\n # ---- 流转记录 ----\n def record_transition(self, from_phase: int, to_phase: int,\n triggered_by: str, session_id: str) -> Dict:\n \"\"\"\n 记录 Phase 流转。\n \"\"\"\n\n def get_last_transition(self) -> Optional[PhaseTransition]:\n \"\"\"\n 获取最近一次流转记录。\n \"\"\"\n```\n\n---\n\n## 六、orchestrator 接入方式\n\n### 6.1 Phase 3 改造示例\n\n```python\ndef orchestrate_phase3(paper_name: str) -> Dict[str, Any]:\n pm = PhaseManager(paper_name)\n\n # 1. 前置门禁检查\n gate = pm.pre_phase_check(target_phase=3)\n if not gate.passed:\n return {\n \"ok\": False,\n \"error\": \"门禁未通过\",\n \"gate_result\": asdict(gate),\n \"hil_message\": pm.hr.render_gate_failure(3, gate)\n }\n\n # 2. 执行 Phase 3 整合逻辑（原有代码不变）\n result = do_phase3_integrate_work(paper_name)\n\n # 3. 保存产出到文件\n save_result = pm.save_phase_output(\n phase=3,\n content_type=\"integrated\",\n content=result[\"content\"],\n key_metrics=result.get(\"metrics\", {})\n )\n\n # 4. 保存审核报告\n pm.save_phase_output(\n phase=3,\n content_type=\"review\",\n content=json.dumps(result[\"review_report\"], ensure_ascii=False),\n )\n\n # 5. 生成 HIL 消息（只含路径+摘要，不塞正文）\n hil_msg = pm.generate_hil_message(phase=3, next_phase=4)\n\n # 6. 记录流转\n pm.record_transition(from_phase=2, to_phase=3,\n triggered_by=\"auto\", session_id=get_current_session_id())\n\n return {\n \"ok\": True,\n \"phase\": 3,\n \"hil_message\": hil_msg, # ✅ 不塞内容\n \"file_path\": save_result[\"file_path\"],\n \"summary\": asdict(save_result[\"summary\"]),\n \"review_file_path\": \".../_phase3_review.json\",\n }\n```\n\n### 6.2 用户工作流\n\n```\nPhase 3 完成\n ↓\n用户收到 HIL 消息：\n\n✅ Phase 3 整合完成\n\n📄 文件：.../论文_xxx/_phase3_integrated.md\n📊 字数：48,320 字 | 章节：7 章\n🔍 审核结果：0 个 P0 问题，2 个 P1 问题\n🛡️ Guardrails：通过 9/10 项\n🕐 时间：2026-06-30 15:21\n\n下一阶段：Phase 4\n操作指令：\n- [确认] → 进入 Phase 4\n- [修改文件] → 直接编辑上方文件后说\"确认修改\"\n- [重新审核] → 重新跑 Phase 3 review\n\n ↓\n用户选项：\nA. 说\"确认\" → 进入 Phase 4\nB. 编辑文件 → 说\"确认修改\" → Phase 4 读取新文件\nC. 发现问题 → 编辑文件 → 触发 re-check\n```\n\n---\n\n## 七、数据有效性保障机制\n\n### 7.1 跨 Session 恢复保护\n\n每次 Phase 完成时，记录 `content_hash` + `session_id`。\n\n下一 Phase 读取时：\n- `content_hash` 变了 → 说明用户改过文件，附带 `user_modified=True`\n- `session_id` 变了 → 说明跨 session 了，需要重新确认\n\n### 7.2 文件新鲜度检查\n\n- `FRESHNESS_THRESHOLD_HOURS = 48`\n- 文件超过 48 小时未更新 → 提示用户\"文件可能过期，是否重新生成？\"\n\n### 7.3 写入锁机制\n\n写入时检查 `.lock` 文件，防止并发覆盖：\n- 有锁 → 报错\"文件正在被编辑，请稍后\"\n- 无锁 → 创建锁 → 写入 → 删除锁（finally 确保释放）\n\n### 7.4 数据清理策略\n\n| 清理时机 | 清理内容 | 保留内容 |\n|---------|---------|---------|\n| Phase N 完成，进入 N+1 | N 的 `.tmp` / `.lock` | N 的 `integrated.md` / `review.json` / `summary.json` |\n| Phase N 完成，进入 N+1 | N 的 `.bak` 备份 | N+1 的 `.bak` 保留 |\n| Phase 5 完成后 | 全部中间态 `.tmp` / `.lock` | 最终 `论文_xxx.docx` + 各 Phase summary |\n| 用户主动\"取消论文\" | 全部文件 | 无 |\n| 超期未继续（>7 天无操作） | `.tmp` / `.lock` 文件 | `integrated.md` / `review.json` |\n\n---\n\n## 八、实现优先级\n\n| 优先级 | 模块 | 依赖关系 |\n|-------|------|---------|\n| P0 | `schemas.py` | 其他所有模块的基础 |\n| P0 | `file_manager.py` | PhaseManager 依赖 |\n| P1 | `gate_keeper.py` | 依赖 schemas + file_manager |\n| P1 | `summary_generator.py` | 依赖 schemas + file_manager |\n| P2 | `hil_renderer.py` | 依赖 schemas + file_manager |\n| P2 | `__init__.py`（Facade） | 依赖以上所有 |\n| P3 | 集成到 orchestrator_v2 | PhaseManager 改造 |\n\n---\n\n## 九、待验证设计决策\n\n以下决策需要在实现过程中确认：\n\n1. **content_hash 算法**：MD5 够用还是需要 SHA256？\n2. **文件编码**：统一 UTF-8，是否需要 BOM？\n3. **大文件处理**：超过 10MB 的文件是否需要流式读写？\n4. **session_id 获取方式**：从环境变量还是 OpenClaw session 上下文？\n5. **清理策略的灵活性**：是否需要用户提供自定义 keep_types？\n\n---\n\n## 十、测试用例（实现后验证）\n\n```python\ndef test_save_and_load_roundtrip():\n \"\"\"保存后读取，内容一致\"\"\"\n pass\n\ndef test_backup_on_overwrite():\n \"\"\"覆盖写入时自动备份\"\"\"\n pass\n\ndef test_user_modification_detection():\n \"\"\"用户修改文件后，hash 变化被检测\"\"\"\n pass\n\ndef test_freshness_check():\n \"\"\"过期文件被标记为不新鲜\"\"\"\n pass\n\ndef test_concurrent_write_protection():\n \"\"\"并发写入被锁保护\"\"\"\n pass\n\ndef test_cleanup_keeps_important_files():\n \"\"\"清理只删除中间文件，保留重要产出\"\"\"\n pass\n\ndef test_pre_phase_check_blocks_invalid_transition():\n \"\"\"前置检查正确拦截非法流转\"\"\"\n pass\n\ndef test_hil_renderer_no_content_leak():\n \"\"\"HIL 消息不包含正文内容\"\"\"\n pass\n```\n\n---\n\n*文档版本：v1.0.0（2026-06-30）*\n\nFile v2.1.1-beta.13:scripts/tests/REAL_SAMPLES_README.md\n\n# 真实样本测试使用说明 (REAL_SAMPLES_README)\n\n## ⚠️ 隐私保护\n\n开题报告样本**含学生姓名 / 学号 / 研究方向 / 论文题目**，属于**敏感个人信息**。\n\n**绝对禁止**：\n- ❌ 上传任何 docx 开题报告到 GitHub 仓库\n- ❌ 在代码中硬编码样本路径或文件名（含学生姓名）\n- ❌ 在 CI/CD 公开 runner 上跑真实样本测试\n\n## 🚀 怎么跑真实样本测试\n\n`test_full_workflow.py` Part 2 在**默认情况下跳过**真实样本测试（避免误跑）。\n\n如需本地验证：\n\n### 步骤 1：准备样本目录\n\n把 docx 文件放到**本地**任意目录（不要放在 `mba-thesis-workflow` 仓库目录内）：\n\n```bash\nmkdir -p ~/private/mba-proposals\ncp /path/to/your/*.docx ~/private/mba-proposals/\n```\n\n### 步骤 2：设置环境变量\n\n```bash\nexport MBA_REAL_SAMPLES_DIR=~/private/mba-proposals\n```\n\n### 步骤 3：跑测试\n\n```bash\ncd /path/to/mba-thesis-workflow\npython3 scripts/tests/test_full_workflow.py\n```\n\n输出示例：\n\n```\n=== 真实 docx 样本批量测试 ===\n 样本目录: /Users/xxx/private/mba-proposals\n 待测试样本: 8 个（匿名展示）\n\n [测试] sample_001 (171 KB)...\n ✅ 全流程通过\n Phase 1.1: 62 真实 + 7 虚拟节点 (0.04s)\n Phase 1.3: 0 hints 写入 (0.07s)\n ch1 摘要: 18 字 (0.0s)\n ...\n```\n\n## 🔒 隐私保证\n\n代码层面：\n\n| 保护措施 | 实现 |\n|---------|------|\n| 不硬编码路径 | `MBA_REAL_SAMPLES_DIR` 环境变量，按需设置 |\n| 不硬编码文件名 | 自动发现目录下所有 `*.docx` |\n| paper_name 匿名 | `v2_real_sample_001` / `v2_real_sample_002` ... |\n| 输出匿名 | 仅显示 `sample_NNN` 索引 + 文件大小 |\n| 跳过文档元数据 | 不读取 docx 的作者、标题等元数据字段 |\n\n## 🧹 清理\n\n测试过程中会创建 `v2_real_sample_NNN` 状态的临时文件：\n\n```bash\n# 列出所有测试遗留\nls ~/.openclaw/workspace/v2_real_*\n\n# 清理（谨慎操作，会删除本地 state）\nrm -rf ~/.openclaw/workspace/v2_real_*\n```\n\n## 💡 建议\n\n- 真实样本测试**仅在本地开发时跑**，CI/CD runner 不要设这个环境变量\n- 提交 PR 时不要附带任何 docx 文件\n- 如果你想把样本提供给项目维护者，**单独发邮件 / 加密压缩包**，不要通过 GitHub Issues\n\nArchive v2.1.1-beta.12: 73 files, 286788 bytes\n\nFiles: CHANGELOG-v2.md (28387b), CHANGELOG.md (9135b), install.sh (3297b), LICENSE (1075b), README_EN.md (4332b), README.md (5583b), references/chapter-summary-design.md (5822b), references/content-hint-fallback.md (6281b), references/loop-design.md (11343b), requirements-optional.txt (581b), requirements.txt (338b), scripts/__init__.py (0b), scripts/context_builder.py (22528b), scripts/gatekeeper_integration.py (5805b), scripts/loop_self_check.py (23844b), scripts/md2docx_strict.py (30736b), scripts/multi_search.py (11124b), scripts/node_writer.py (10771b), scripts/orchestrator_v2.py (100792b), scripts/orchestrator.py (10344b), scripts/outline_parser.py (66359b), scripts/phase_manager/__init__.py (19518b), scripts/phase_manager/DESIGN.md (22966b), scripts/phase_manager/file_manager.py (21761b), scripts/phase_manager/gate_keeper.py (17002b), scripts/phase_manager/hil_renderer.py (13972b), scripts/phase_manager/schemas.py (8282b), scripts/phase_manager/summary_generator.py (13246b), scripts/phase_manager/tests/__init__.py (54b), scripts/phase_manager/tests/test_phase_manager.py (19831b), scripts/release.py (8885b), scripts/research_tools.py (12431b), scripts/reviewer.py (9044b), scripts/run_workflow.py (43081b), scripts/simple_embedder.py (7451b), scripts/state_manager_v2.py (23637b), scripts/state_manager.py (8528b), scripts/tests/__init__.py (396b), scripts/tests/conftest.py (676b), scripts/tests/REAL_SAMPLES_README.md (2332b), scripts/tests/test_b1_bypass_scarcity.py (7516b), scripts/tests/test_b2_state_sync.py (10904b), scripts/tests/test_bridge_p3_fallback.py (9954b), scripts/tests/test_chapter_summary.py (9887b), scripts/tests/test_context_builder.py (12330b), scripts/tests/test_full_workflow.py (36824b), scripts/tests/test_info_scarcity.py (15074b), scripts/tests/test_integration_chapter_summary.py (8091b), scripts/tests/test_loop_self_check.py (4603b), scripts/tests/test_md2docx_strict.py (2596b), scripts/tests/test_node_writer.py (7768b), scripts/tests/test_orchestrator.py (7008b), scripts/tests/test_outline_engine_fallback.py (20573b), scripts/tests/test_outline_parser.py (6525b), scripts/tests/test_phase1_3.py (19548b), scripts/tests/test_reviewer.py (7889b), scripts/tests/test_run_workflow.py (11097b), scripts/tests/test_state_manager.py (3732b), scripts/tests/test_synthesize_summary.py (11204b), skill-card.md (3415b), SKILL.md (22241b), skills/gatekeeper/gatekeeper.py (18343b), skills/gatekeeper/SKILL.md (5722b), tests/__init__.py (0b), tests/test_context_builder.py (4725b), tests/test_mcp_aware_llm.py (4295b), tests/test_pre_phase2_review.py (8669b), tests/test_research_tools.py (5355b), thesis-docx-export/CHANGELOG.md (806b), thesis-docx-export/README.md (1459b), thesis-docx-export/references/checklist.md (8379b), thesis-docx-export/SKILL.md (6344b), _meta.json (145b)\n\nFile v2.1.1-beta.12:SKILL.md\n\n---\nname: thesis-workflow-v2\ndescription: \"Write, review, and export MBA / academic theses end-to-end as Word / DOCX. Covers outline planning → node-by-node writing → chapter review → academic deep review → Word export with GB/T 7714 references and 南大-style formatting. Triggers: 论文 / thesis / dissertation / 答辩 / 开题 / MBA / 章节 / 文献综述 / 参考文献 / chapter outline. ⚠️ v2 is beta (outline-anchored + 9 HIL + BGE multi-search); install independently and do not overwrite v1. Prefer v1 (`thesis-workflow`) for production unless user explicitly asks for v2 / 新框架 / outline-anchored / 9 HIL.\"\nplatforms: [linux, macos, windows]\nmetadata:\n # ↓ OpenClaw 私有配置（仅 ClawHub 加载器识别；不影响标准 platforms 字段）\n clawdbot:\n emoji: \"📝\"\n version: \"2.1.1-beta.12\" # 单一真实来源，发布前必须先改这里。发布规则见 scripts/release.py\n requires: {}\n os: [\"linux\", \"darwin\", \"win32\"]\n---\n\n# MBA/学术论文多Agent协作工作流\n\n> 完整文档见：`references/checklist.md`（学术规范清单）、`references/loop-design.md`（Loop 设计原理）\n\n## 🔌 平台依赖（加载后必看）\n\n本 skill **不是**通用 Hermes skill，专为 OpenClaw 设计。在调用本 skill 任何 Python 入口前，先确认平台依赖：\n\n| 维度 | 依赖项 |\n|-------------------|------------------------------------------------------------------------|\n| **Agent 启动** | `sessions_spawn`（OpenClaw 子 agent 机制） |\n| **状态文件目录** | `~/.openclaw/workspace/{paper_name}/`（**非** Hermes 标准路径） |\n| **工具后端** | `web_search` / `tavily_search` / `arxiv_search`（OpenClaw MCP 工具链） |\n| **CLI 入口** | `python3 scripts/run_workflow.py {paper_name} --phase auto` |\n| **Python 路径** | `PYTHONPATH=scripts python3 ...`（CLI 内部期望 scripts 在 path 上） |\n\n**反模式：** 不要把本 skill 当作标准 Hermes skill 调用——Hermes 的 file / search / web 工具链不能驱动 v2 的状态机和 HIL 拦截。如果你需要把论文流程迁回 Hermes，先做\"状态层适配\"（用 Hermes 的 workspace 概念替代 `~/.openclaw/workspace/`，并把 `sessions_spawn` 改成 Hermes 的子任务机制），再启用本 skill。\n\n## ⚠️ 触发规则\n\n当用户请求生成 Word 文档且满足以下任一条件时，**必须**调用本 skill 的 Word 输出流程，不得使用简单 md2docx 脚本：\n- 输入文件路径匹配：`论文*.md`、`*thesis*.md`、`*dissertation*.md`\n- 上下文中存在「论文」「MBA」「答辩」「开题」等关键词\n- 用户明确要求导出 `.docx` 格式且文件性质为学术论文\n\n**正确流程：** 写作语法预检 → Review Agent 终审（`scripts/loop_self_check.py` 校验通过）→ `scripts/md2docx_strict.py` 合规转换 → Word 输出\n\n## ⚠️ v1 / v2 选择矩阵（加载后必看）\n\nv2 仍处于 beta，**生产论文默认走 v1**。仅当用户明确要求时再切 v2：\n\n| 场景 | 选择 | 触发依据 |\n|------|------|---------|\n| 用户说「稳一点 / 跑过答辩 / 已用 v1 / 默认」 | ✅ v1 (`thesis-workflow`) | 默认基线 |\n| 论文已在 `~/.openclaw/workspace/{paper}/` 下运行 v1 | ❌ 切 v2 | 状态文件不兼容 |\n| 用户说「用 v2 / 新框架 / outline-anchored / 9 HIL / BGE 多工具并行」 | ✅ 本 skill (v2) | 显式升级 |\n| 用户未明示 + 新论文 | ⚠️ 走 v1 | 避开 beta 风险 |\n\n**反模式：** 不要因为「本 skill 描述更新」就把现有 v1 论文切到 v2——v2 的 `_orchestrate_state.json` schema 与 v1 不兼容。\n\n### v2 HIL 节点一览（确定用 v2 之后再读）\n\nv2 在 9 个位置**强制 human-in-the-loop**：每到这些点状态机会 hard pause，必须用户确认才能推进。如果 agent 想绕过任何一项，v2.0.6 的拦截规则会拒绝（见 §v2.0.6 拦截规则）：\n\n| # | 触发位置 | 检查内容 | 决策 |\n|----|--------------------------------|--------------------|-------------------|\n| 1 | Phase 1.1 后 | 大纲结构 | 接受 / 修改 |\n| 2 | Phase 1.3 后 | 归因结果 | 接受 / 调整 hint |\n| 3 | 在 `write_single_node()` 写入单节点前 | info_scarcity | 提供 hint / AI 生成 / 跳过 |\n| 4 | Phase 2 评审后 | quality=medium/low | 接受 / 重写 |\n| 5 | Phase 2 完成后 | 章节内容预览 | 通过 / 修改 |\n| 6 | Phase 3 整合后 | 整合版内容 | 通过 / 修改反馈 |\n| 7 | Phase 3.5 P0 修复 | 超 3 轮未收敛 | 接受 / 继续修订 |\n| 8 | Phase 4 整合方案 | 方案是否接受 | 接受 / 修改 |\n| 9 | Phase 5.2 后 | Word 输出 | 导出 / 修改 |\n\n**反模式：** 不要给 agent 传 `allow_skip_hil=True` 或在 prompt 里写\"自动通过所有 HIL\"——HIL 是论文质量最后一道防线，绕过它的代价是错版交付给导师。\n\n### v2.0.6 拦截规则（与 HIL 表配套必读）\n\n如果 agent 想绕过 HIL 或绕过\"独立评审\"，v2.0.6 在 orchestrator 层有 3 类硬拦截：\n\n| 拦截点 | 强制规则 | 失败场景 |\n|--------|----------|----------|\n| **拍板 #1 强制** | `phase1_3_skip` 不允许；`skip_phase1_3()` 需要 `MBA_THESIS_PRODUCTION=1` + 必填 `reason`/`operator` + audit log | 跳过 Phase 1.3 → 论文方向错位无人工把关，全文跑偏 |\n| **B-2 幂等保护** | `outline_update_status()` 默认拒绝覆盖已 completed 节点 | 误重写已通过审核的节点 → 评审历史回滚，质量倒退 |\n| **独立 Reviewer** | `write_single_node()` 默认要求 `reviewer_func ≠ llm_func` | 生成+评审用同一 LLM → 自我审核，\"我写的都对\"假阳性 |\n\n**反模式：** 不要在 prompt 里\"建议 agent 用 force=True \n\nArchive v2.1.1-beta.11: 69 files, 276369 bytes\n\nFiles: CHANGELOG-v2.md (28387b), CHANGELOG.md (5842b), install.sh (3297b), LICENSE (1075b), README_EN.md (4108b), README.md (5329b), references/chapter-summary-design.md (5822b), references/checklist.md (8379b), references/loop-design.md (11343b), requirements-optional.txt (581b), requirements.txt (338b), scripts/__init__.py (0b), scripts/context_builder.py (22528b), scripts/gatekeeper_integration.py (5805b), scripts/loop_self_check.py (23844b), scripts/md2docx_strict.py (30736b), scripts/multi_search.py (11124b), scripts/node_writer.py (10771b), scripts/orchestrator_v2.py (100141b), scripts/orchestrator.py (10344b), scripts/outline_parser.py (66359b), scripts/phase_manager/__init__.py (19518b), scripts/phase_manager/DESIGN.md (22966b), scripts/phase_manager/file_manager.py (21761b), scripts/phase_manager/gate_keeper.py (17002b), scripts/phase_manager/hil_renderer.py (13972b), scripts/phase_manager/schemas.py (8282b), scripts/phase_manager/summary_generator.py (13246b), scripts/phase_manager/tests/__init__.py (54b), scripts/phase_manager/tests/test_phase_manager.py (19831b), scripts/release.py (8885b), scripts/research_tools.py (12431b), scripts/reviewer.py (9044b), scripts/run_workflow.py (42511b), scripts/simple_embedder.py (7451b), scripts/state_manager_v2.py (23637b), scripts/state_manager.py (8528b), scripts/tests/__init__.py (396b), scripts/tests/conftest.py (676b), scripts/tests/REAL_SAMPLES_README.md (2332b), scripts/tests/test_b1_bypass_scarcity.py (7516b), scripts/tests/test_b2...","readmeExcerpt":"Skill: Mba Thesis Workflow Owner: hehe973781230 Summary: Write, review, and export MBA / academic theses end-to-end as Word / DOCX. Covers outline planning → node-by-node writing → chapter review → academic deep re... Tags: beta:2.1.2-beta.1, latest:2.1.2-beta.1 Version history: v2.1.2-beta.1 | 2026-07-02T06:47:15.143Z | user v2.1.2-beta.1 (2026-07-02) - P0 修复: 1. Tavily MCP 平台集成 - 新增 _detect_openclaw_platform() 检测 O","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Phase 1（规划）→ Phase 2（逐节点写作）→ Phase 2.5（内容确认）\n→ Phase 3（整合）→ Phase 3.5（学术深度评审）\n→ Phase 4（修复）→ Phase 5（终审 + Word 输出）"},{"language":"json","snippet":"\"company_info\": {\n \"code_name\": \"A公司\", // 从开题报告 docx 自动提取\n \"actual_name\": \"vivo\", // HIL #1 由用户填入；空/null = 未填\n \"skip_mapping\": false, // true = 显式跳过(纯理论论文)\n \"confirmed\": true, // confirm_phase1() 校验通过\n \"confirmed_at\": \"2026-07-02T...\"\n}"},{"language":"python","snippet":"from research_tools import quick_search, research_enrich\n\n# 快速检索（返回文本，供注入 prompt）\nresult = quick_search(\"竞争战略 市场规模 2024\")\n\n# 节点级检索（自动取 outline 中的 research_keywords）\nctx = research_enrich(node_id, paper_name)"},{"language":"bash","snippet":"# 仅查看状态\npython3 scripts/run_workflow.py --status\n\n# auto 模式：根据 state 自动判断下一步\npython3 scripts/run_workflow.py --phase auto\n\n# 指定阶段\npython3 scripts/run_workflow.py --phase phase1\npython3 scripts/run_workflow.py --phase phase2 # 需 --llm\npython3 scripts/run_workflow.py --phase phase3"},{"language":"python","snippet":"import sys\nsys.path.insert(0, \"scripts\")\nfrom orchestrator_v2 import orchestrate, write_single_node, apply_user_decision\n\n# Phase 1.1: 解析开题报告（docx 或文本）\nr = orchestrate(paper_name, action=\"phase1_1_init\",\n input_type=\"docx\", input_data=\"path/to/proposal.docx\")\n\n# Phase 1.2: 确认大纲（用户 HIL）\nr = orchestrate(paper_name, action=\"phase1_confirm\")\n\n# Phase 1.3: 提交开题报告归因\nr = orchestrate(paper_name, action=\"phase1_3_submit\",\n docx_path=\"path/to/proposal.docx\", llm_func=my_llm)\n\n# Phase 1.3: 确认归因（用户 HIL）\nr = orchestrate(paper_name, action=\"phase1_3_confirm\")\n\n# Phase 2: 逐节点写作（v2.0.4 推荐调用模式）\nfor node_id in next_nodes:\n r = write_single_node(paper_name, node_id,\n reviewer_func=my_reviewer) # 独立评审，llm_func 内部从 session 获取\n\n# Phase 3: 整合\nr = orchestrate(paper_name, action=\"phase3_review\")\n\n# Phase 3.5: 深度学术评审（自动进入 Phase 3.5/4/5 链）\n# Phase 3 → orchestrate_phase3_5() → P0修复 → Phase 4 → Phase 5\nr = orchestrate(paper_name, phase=\"phase3\", action=\"phase3_export\")\n\n# Phase 5: Word 输出提示\nprint(r.get(\"message\", \"\"))"},{"language":"bash","snippet":"python3 scripts/orchestrator.py 状态文件.json --validate"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: thesis-workflow-v2\ndescription: \"Write, review, and export MBA / academic theses end-to-end as Word / DOCX. Covers outline planning → node-by-node writing → chapter review → academic deep review → Word export with GB/T 7714 references and 南大-style formatting. Triggers: 论文 / thesis / dissertation / 答辩 / 开题 / MBA / 章节 / 文献综述 / 参考文献 / chapter outline. ⚠️ v2 is beta (outline-anchored + 9 HIL + BGE multi-search); install independently and do not overwrite v1. Prefer v1 (`thesis-workflow`) for production unless user explicitly asks for v2 / 新框架 / outline-anchored / 9 HIL.\"\nplatforms: [linux, macos, windows]\nmetadata:\n # ↓ OpenClaw 私有配置（仅 ClawHub 加载器识别；不影响标准 platforms 字段）\n clawdbot:\n emoji: \"📝\"\n version: \"2.1.2-beta.1\" # 单一真实来源，发布前必须先改这里。发布规则见 scripts/release.py\n requires: {}\n os: [\"linux\", \"darwin\", \"win32\"]\n---\n\n# MBA/学术论文多Agent协作工作流\n\n> 完整文档见：`references/checklist.md`（学术规范清单）、`references/loop-design.md`（Loop 设计原理）\n\n## 🔌 平台依赖（加载后必看）\n\n本 skill **不是**通用 Hermes skill，专为 OpenClaw 设计。在调用本 skill 任何 Python 入口前，先确认平台依赖：\n\n| 维度 | 依赖项 |\n|-------------------|------------------------------------------------------------------------|\n| **Agent 启动** | `sessions_spawn`（OpenClaw 子 agent 机制） |\n| **状态文件目录** | `~/.openclaw/workspace/{paper_name}/`（**非** Hermes 标准路径） |\n| **工具后端** | `web_search` / `tavily_search` / `arxiv_search`（OpenClaw MCP 工具链） |\n| **CLI 入口** | `python3 scripts/run_workflow.py {paper_name} --phase auto` |\n| **Python 路径** | `PYTHONPATH=scripts python3 ...`（CLI 内部期望 scripts 在 path 上） |\n\n**反模式：** 不要把本 skill 当作标准 Hermes skill 调用——Hermes 的 file / search / web 工具链不能驱动 v2 的状态机和 HIL 拦截。如果你需要把论文流程迁回 Hermes，先做\"状态层适配\"（用 Hermes 的 workspace 概念替代 `~/.openclaw/workspace/`，并把 `sessions_spawn` 改成 Hermes 的子任务机制），再启用本 skill。\n\n## ⚠️ 触发规则\n\n当用户请求生成 Word 文档且满足以下任一条件时，**必须**调用本 skill 的 Word 输出流程，不得使用简单 md2docx 脚本：\n- 输入文件路径匹配：`论文*.md`、`*thesis*.md`、`*dissertation*.md`\n- 上下文中存在「论文」「MBA」「答辩」「开题」等关键词\n- 用户明确要求导出 `.docx` 格式且文件性质为学术论文\n\n**正确流程：** 写作语法预检 → Review Agent 终审（`scripts/loop_self_check.py` 校验通过）→ `scripts/md2docx_strict.py` 合规转换 → Word 输出\n\n## ⚠️ v1 / v2 选择矩阵（加载后必看）\n\nv2 仍处于 beta，**生产论文默认走 v1**。仅当用户明确要求时再切 v2：\n\n| 场景 | 选择 | 触发依据 |\n|------|------|---------|\n| 用户说「稳一点 / 跑过答辩 / 已用 v1 / 默认」 | ✅ v1 (`thesis-workflow`) | 默认基线 |\n| 论文已在 `~/.openclaw/workspace/{paper}/` 下运行 v1 | ❌ 切 v2 | 状态文件不兼容 |\n| 用户说「用 v2 / 新框架 / outline-anchored / 9 HIL / BGE 多工具并行」 | ✅ 本 skill (v2) | 显式升级 |\n| 用户未明示 + 新论文 | ⚠️ 走 v1 | 避开 beta 风险 |\n\n**反模式：** 不要因为「本 skill 描述更新」就把现有 v1 论文切到 v2——v2 的 `_orchestrate_state.json` schema 与 v1 不兼容。\n\n### v2 HIL 节点一览（确定用 v2 之后再读）\n\nv2 在 9 个位置**强制 human-in-the-loop**：每到这些点状态机会 hard pause，必须用户确认才能推进。如果 agent 想绕过任何一项，v2.0.6 的拦截规则会拒绝（见 §v2.0.6 拦截规则）：\n\n| # | 触发位置 | 检查内容 | 决策 |\n|----|--------------------------------|--------------------------------|-----"},{"path":"skills/gatekeeper/SKILL.md","content":"# Gatekeeper Skill — 论文写作质量与流程门禁\n\n> 版本：1.0.0\n> 角色：所有产出给用户前的最后一道门；全程守护流程/规范/质量\n\n---\n\n## 角色定义\n\n**Gatekeeper = 质量门禁 + 流程门禁 + 结果门禁 + 出口门禁**\n\n- 独立 session 运行，不阻塞 Orchestrator 执行路径\n- 所有异常记录到 `_gk_exception_log.json`\n- 流程结束后统一汇报给用户\n- 用户选择\"修复\"则触发闭环修复流程\n\n---\n\n## 门禁层次\n\n### 1. 流程门禁（Process Gate）\n\n**触发时机**：每次 Phase 切换时\n\n```\n检查项：\n ✓ 前置 Phase 是否已完成\n ✓ 当前 Phase 的必填字段是否齐全\n ✓ 状态机是否合法跳转（phase1 → phase2 需要 phase1_3_confirmed）\n ✓ HIL 节点是否满足通过条件\n```\n\n**阻断行为**：\n- 写入 `_gk_exception_log.json`\n- 通知用户，等待决策\n- Orchestrator 暂停直到用户回复\n\n---\n\n### 2. 质量门禁（Quality Gate）\n\n**触发时机**：每个节点写作完成后、整合前、导出前\n\n```\n检查项（loop_self_check）：\n ✓ 章节完整性（7章都有）\n ✓ 无 **加粗** 残留\n ✓ 引用数量逐章检查（每章 ≥ 1 处）\n ✓ 三线表格式正确\n ✓ 无乱码/占位符残留\n ✓ 标题层级正确\n ✓ 字数达标（每章 ≥ 800 字）\n```\n\n**不达标** → 打回重写，不进入下一节点\n\n---\n\n### 3. 结果门禁（Result Gate）\n\n**触发时机**：Phase 3 整合后、Phase 5 导出前\n\n```\n检查项：\n ✓ 开题报告承诺的内容是否落地\n ✓ 关键章节（PEST/战略理论/案例分析）是否充实\n ✓ 章节之间逻辑衔接是否顺畅\n ✓ 结论与前文分析是否对应\n```\n\n---\n\n### 4. 出口门禁（Export Gate）\n\n**触发时机**：最终输出给用户前（唯一出口）\n\n```\n检查项：\n ✓ Guardrails 最终校验通过\n ✓ Word 文档生成成功\n ✓ 用户确认导出\n```\n\n---\n\n## 异常日志设计\n\n**文件路径**：`~/.openclaw/workspace/papers/{paper_name}/_gk_exception_log.json`\n\n```json\n{\n \"paper_name\": \"论文名称\",\n \"start_time\": \"2026-06-26T21:00:00+08:00\",\n \"exceptions\": [\n {\n \"id\": 1,\n \"timestamp\": \"2026-06-26T21:18:00+08:00\",\n \"phase\": \"phase2\",\n \"node_id\": \"ch3\",\n \"gate_type\": \"quality_gate\",\n \"gate_name\": \"citation_check\",\n \"description\": \"第3章引用数量不足：0处（要求≥1处）\",\n \"severity\": \"error\",\n \"status\": \"pending\",\n \"action_taken\": null,\n \"repaired_at\": null,\n \"repaired_by\": null,\n \"user_notified\": true,\n \"user_decision\": null\n }\n ],\n \"summary\": {\n \"total\": 1,\n \"pending\": 1,\n \"fixed\": 0,\n \"skipped\": 0\n }\n}\n```\n\n---\n\n## 用户交互流程\n\n### 流程守护（异常发生时）\n\n```\nGatekeeper 发现异常\n ↓\n写入 _gk_exception_log.json（status=pending）\n ↓\n通知用户（飞书）：\n━━━━━━━━━━━━━━━━━━━━━━\n🤖 [Gatekeeper] 发现异常\n\n环节：Phase 2（节点写作）\n节点：ch3 第3章\n问题：引用数量不足（0处，要求≥1处）\n━━━━━━━━━━━━━━━━━━━━━━\n请选择：\n [1] 修复后继续（打回重写）\n [2] 跳过此检查（谨慎！）\n [3] 暂停，手动介入\n━━━━━━━━━━━━━━━━━━━━━━\n ↓\n等待用户回复\n ↓\n用户选择 [1/2/3]\n ↓\n更新 exception.status + action_taken\n ↓\n[1] → 通知 Orchestrator 修复\n[2] → 继续流程（记录 skip）\n[3] → 暂停，等用户手动触发\n```\n\n### 流程结束后（统一汇报）\n\n```\n所有 session 结束后\n ↓\nGatekeeper 生成最终报告\n ↓\n发给用户：\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n🤖 [Gatekeeper] 流程结束 — 异常报告\n\n本次流程共发现 N 个异常：\n\n【异常 #1】\n时间：2026-06-26 21:18\n环节：Phase 2\n节点：ch3\n类型：质量门禁 - 引用数量不足\n处理：已修复\n\n【异常 #2】\n时间：2026-06-26 21:25\n环节：Phase 4\n节点：—\n类型：流程门禁 - HIL #8 阻断\n处理：用户确认跳过\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n建议优化项：\n 1. ...\n 2. ...\n\n请选择：\n [1] 查看异常详情\n [2] 优化 skill 配置\n [3] 结束\n━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n---\n\n## 巡检机制\n\nGatekeeper 启动后定期巡检（每 30 秒）：\n\n```\n巡检项：\n ✓ 当前 state 的 phase 是否合法\n ✓ completed_nodes 是否有重复\n ✓ failed_nodes 是否长时间未修复\n ✓ phase3_5 连续轮次是否异常（>5轮则告警）\n ✓ 是否有节点写作超 30 分钟未完成（疑似卡住）\n```\n\n---\n\n## 与 Orchestrator 的协作方式\n\n**通过状态文件通信，零直接函数调用：**\n\n```\nOrchestrator 写：_orchestrate_state.json\nGatekeeper 读：_orchestrate_state.json + 巡检\nGatekeeper 写：_gk_exception_log.json\nOrchestrator 读："},{"path":"thesis-docx-export/SKILL.md","content":"---\nname: thesis-docx-export\ndescription: \"Convert academic thesis markdown (.md) into a Word (.docx) document that meets the MBA / 南大 / GB/T 7714 formatting spec, and run the 10-item Guardrails check before and after export. Triggers: 导出 Word / 转换为 docx / 论文格式校验 / Guardrails 校验 / md2docx / 三线表 / 分页符 / GB/T 7714 参考文献格式. Required by `thesis-workflow-v2` Phase 5.2; can also be invoked standalone after manual writing.\"\nplatforms: [linux, macos, windows]\nmetadata:\n clawdbot:\n emoji: \"📄\"\n version: \"1.0.0\" # 单一真实来源；主 skill thesis-workflow-v2 仅在 Phase 5.2 阶段引用本 skill\n requires: {}\n os: [\"linux\", \"darwin\", \"win32\"]\n---\n\n# Thesis DOCX Export\n\n把学术论文 Markdown 转换为符合学术规范的 Word 文档，并在导出前后自动跑 Guardrails 校验。\n\n本 skill 是 `thesis-workflow-v2`（主 skill）Phase 5.2 阶段的\"出口工序\"——主 skill 完成 Phase 1-5 内容生产后，调用本 skill 做 Word 转换和最终格式校验。本 skill **也可以独立调用**：用户手写完论文后，直接用本 skill 做导出。\n\n> **核心原则**：本 skill 不做内容生成（写、审、整合都是主 skill 的事）。本 skill 只做\"格式合规\"：校验 → 转换 → 再校验。\n\n## ⚠️ 调用矩阵\n\n| 触发场景 | 选择 |\n|---------|------|\n| 主 skill `thesis-workflow-v2` 跑到 Phase 5.2 | ✅ 本 skill（自动调用，无需用户手动触发） |\n| 用户手写论文后想导出 docx | ✅ 本 skill（standalone 调用） |\n| 用户只想校验 Markdown 是否符合学术规范 | ✅ `python3 scripts/loop_self_check.py --file 论文.md`（只校验、不导出） |\n| 用户想用 pandoc / python-docx 直接生成 Word | ❌ 本 skill（pandoc 不做三线表、不做 GB/T 7714 排序） |\n\n**反模式：** 不要把本 skill 用于\"内容生成\"——主 skill 的 Phase 2 写作、Phase 3 审核、Phase 4 整合都由 `thesis-workflow-v2` 负责。本 skill 只接受已完成的 Markdown 输入。\n\n## 核心能力\n\n### 1. Guardrails 10 项自动校验\n\n`scripts/loop_self_check.py` 在转换前后各跑一次：\n\n```bash\n# 转换前校验 Markdown 内容（10 项 Guardrails）\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# 转换后再校验生成的 docx（Word 格式校验）\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n**10 项校验项详见 [references/checklist.md §六](references/checklist.md)**。\n\n### 2. Word 格式转换\n\n`scripts/md2docx_strict.py` 把符合 Guardrails 的 Markdown 转为 docx，应用以下格式：\n\n| 维度 | 规则 |\n|-------------|----------------------------------------------------------|\n| 正文加粗过滤 | 正文段落内的 `**text**` 全部转为普通文字（无强调术语） |\n| 表格加粗过滤 | 表格单元格内的 `**` 同步清除 |\n| 三线表 | 顶线 1.5 磅 / 表头底线 0.75 磅 / 底线 0.5 磅，无竖线 |\n| 分页符 | 每章标题前插入分页符（首章跳过），附录/致谢前分页 |\n| 字体 | 中文宋体 / 英文 Times New Roman / 标题黑体 |\n| 行距 | 正文 20 磅 |\n\n**反模式：** 不要用 `pandoc 论文.md -o 论文.docx` 走捷径——pandoc 不做加粗过滤、不做三线表、不做 GB/T 7714 排序；出来的 docx 必须经 `loop_self_check.py --verify-docx` 二次校验才能交付。\n\n## 入口与依赖\n\n### 入口\n\n```bash\n# 校验 + 转换 + 再校验 一条龙\npython3 scripts/loop_self_check.py --file 论文_xxx.md\npython3 scripts/md2docx_strict.py --input 论文_xxx.md --output 论文_xxx.docx\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n### 依赖\n\n- `python-docx`（Word 写入）\n- `pandoc`（Markdown 预处理）\n- 标准 Python 3.9+ 库\n\n### 反向依赖\n\n本 skill **被** `thesis-workflow-v2`（主 skill）Phase 5.2 引用。如果本 skill 不可用，主 skill 的 Phase 5.2 步骤会失败。\n\n## 文件结构\n\n```\nthesis-docx-export/\n├── SKILL.md ← 本文件\n├"},{"path":"README.md","content":"# MBA/学术论文 多Agent协作工作流（v2 新框架）\n\n📝 多Agent协作完成MBA/学术论文写作的完整工作流，支持大纲解析、逐节点写作、深度审核、整合终审、Word输出。\n\n适用于开题报告到毕业论文的全流程。\n\n---\n\n## ⚠️ 当前项目双版本并行\n\n本仓库包含 **两条独立版本线**，互不干扰、并行发布：\n\n| 版本线 | ClawHub Slug | 当前 latest | 状态 | 文档 |\n|--------|--------------|-------------|------|------|\n| **v1.x**（稳定） | `thesis-workflow` | **v1.7.3** | 长期维护，仅兼容性修复 | [CHANGELOG-v1.md](./CHANGELOG-v1.md) |\n| **v2.x**（新框架） | `thesis-workflow-v2` | **v2.0.14** | ⚠️ 测试版，outline-anchored + 9 HIL + 多工具检索 | [CHANGELOG-v2.md](./CHANGELOG-v2.md) |\n\n### 选型指南\n\n- **生产环境 / 已有 v1 用户** → `thesis-workflow` (v1.7.3，稳定)\n- **新框架 / outline-anchored / 9 HIL 体验** → `thesis-workflow-v2` (v2.0.14，测试)\n- **同时跑多篇论文** → 两个都装，**可共存**\n\n### 怎么装两个？\n\n```bash\n# v1 稳定版（不依赖本仓库）\nopenclaw skills install thesis-workflow\n\n# v2 测试版\nopenclaw skills install thesis-workflow-v2\n```\n\n两者安装路径、状态文件、依赖互不冲突。\n\n详见 [`references/git-workflow.md`](./references/git-workflow.md) 和 [CHANGELOG.md](./CHANGELOG.md) 索引。\n\n---\n\n## 核心功能（v2 框架）\n\n- **outline-anchored 写作**：以大纲为锚点，逐节点生成内容，节点间自动承接\n- **BGE-small-zh 向量标题匹配**：Phase 1.3 开题归因加速 30-90s → 2-5s\n- **多工具并行检索**：4工具（Tavily/arXiv/OpenAlex/web_search）同时搜索，去重排序\n- **Phase 3.5 深度学术评审**：P0/P1/P2 分级问题清单，自动修复 + 重审闭环\n- **RuntimeLLM**：零硬编码，自动复用当前 session 模型配置\n- **9 个 HIL 节点**：human-in-the-loop 检查点，关键决策不跳过\n- **公司映射强制采集**（v2.1.2+）：HIL #1 同步确认大纲 + 实际公司名（`actual_name`），确保 Phase 2 数据检索锚定真实公司\n- **OpenClaw 平台适配**（v2.1.2+）：Tavily MCP 检测自动识别 OpenClaw runtime，走内置桥接；不再依赖外部 `mcporter` CLI\n- **Guardrails 自检**：10 项自动化规范检查（章节完整性/字数/引用/表格格式等）\n- **Loop 架构**：Orchestrator Loop / 内部自检 Loop / 审核 Loop / Verification Loop\n- **Phase 5 Word输出**：[thesis-docx-export](../thesis-docx-export/SKILL.md) skill（独立子 skill，三线表/分页/字体/行距）\n\n## 适用场景TODO_SPLIT\n\n- MBA毕业论文（战略管理/企业分析类）\n- 学术研究报告（竞争战略/行业分析类）\n- 需要多轮审核、多版本整合的正式长文\n\n## 工作流程\n\n```\n用户 → Phase 1（大纲确认 + 开题归因）→ Phase 2（逐节点写作）→ Phase 2.5（用户确认）\n → Phase 3（整合）→ Phase 3.5（深度学术评审 → P0修复循环）\n → Phase 4（修复）→ Phase 5（终审 + Word输出）\n```\n\n## v2.0.x 版本历史（详见 [CHANGELOG-v2.md](./CHANGELOG-v2.md)）\n\n| 版本 | 亮点 |\n|------|------|\n| 2.0.21-beta | HIL #4 消息改为人话版：【节点X 写完：质量Y】 + AI 总结 + 路径 + 动作描述 |\n| 2.0.20-beta | 评审完整文字落盘 + HIL #4 消息简化为路径+选项（避免聊天刷屏）|\n| 2.0.19-beta | context_builder 主题锁定 + 反面警示 总是注入（修复 v8.0 ch1 跑题事故）|\n| 2.0.18-beta | outline_parser 新增 LLM 一次性兑底补全空 hint 节点 |\n| 2.0.17-beta | outline_parser 新增 C 路径：Word 自定义样式（MPA-章标题/一级节标题）支持 |\n| 2.0.12-beta | Phase 3.5 大纲锚定章节拆分（替代硬编码正则）+ P0/P1 修复（F1-F6）|\n| 2.0.11-beta | 清理 v1 残留 + clawhubignore 排除 |\n| 2.0.10-beta | Phase 3.5/4/5 实现 + requirements.txt + lazy BGE |\n| 2.0.9-beta | BGE-small-zh 向量标题匹配（Layer 2） |\n| 2.0.8-beta | multi-search并行引擎 + RuntimeLLM 零硬编码 |\n| 2.0.7 | outline_parser 引擎切换 B→A 单向降级 |\n| 2.0.6 | 双版本独立发布 + enforcement + 真实入口 CLI |\n| 2.0.5 | B-2 状态同步修复 |\n| 2.0.4 | B-1 HIL 死循环修复 |\n| 2.0.3 | P2 代码清理 |\n| 2.0.2 | P0/P1 修复 |\n| 2.0.1 | 方案 C 端到端验证 |\n| 2.0.0 | outline-anchored feature complete |\n\n## Agent 角色体系\n\n| Agent | 调用方式 | 主责 |\n|-------|---------|------|\n| **Orchestrator** | 当前 session | 调度 / 推进 / 决策 |\n| **NodeWriter** | `sessions_spawn` | 逐节点内容生成 |\n| **Review"},{"path":"thesis-docx-export/README.md","content":"# thesis-docx-export\n\n> 学术论文 Markdown → Word (.docx) 转换 + 格式校验工具集\n\n## 这是什么\n\n把符合学术规范（MBA / 南大 / GB/T 7714）的论文 Markdown 文件转换为 Word 文档，并在转换前后自动跑 Guardrails 校验。\n\n**主要场景**：\n\n1. **主 skill 配套**：`thesis-workflow-v2` 完成 Phase 1-5 后，Phase 5.2 自动调用本 skill 做 Word 转换\n2. **独立使用**：用户手写完论文后，直接用本 skill 校验 + 转换\n\n## 三步导出\n\n```bash\n# 1. 转换前：校验 Markdown 是否符合 10 项 Guardrails\npython3 scripts/loop_self_check.py --file 论文_xxx.md\n\n# 2. 转换：Markdown → Word\npython3 scripts/md2docx_strict.py --input 论文_xxx.md --output 论文_xxx.docx\n\n# 3. 转换后：校验生成的 docx 格式\npython3 scripts/loop_self_check.py --file 论文_xxx.docx --verify-docx\n```\n\n## 安装\n\n```bash\n# 本 skill 是 thesis-workflow-v2 的子模块，已在仓库中。\n# 软链接共享主 skill 的 Python 脚本，单一真实来源。\npip install python-docx pandoc\n```\n\n## 不做什么\n\n- ❌ 不做内容生成（写、审、整合属于 `thesis-workflow-v2`）\n- ❌ 不做 pandoc 直接转换（pandoc 不做三线表、不做 GB/T 7714）\n- ❌ 不做引用文献自动抓取（用 `research_tools.py` 属于主 skill）\n\n## 详细文档\n\n- 格式规范清单：[references/checklist.md](references/checklist.md)\n- 触发场景与边界：见 [SKILL.md](SKILL.md)"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1301,"uniquenessScore":39,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:26:03.620Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:26:03.620Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T12:00:33.384Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}