psyclaw 0.24.0 → 0.25.1

package/scripts/build_preprint_figures.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""生成 PsyClaw 预印本的示意图（图1 架构与数据流；图2 三理念协同）。
+输出 300 dpi PNG 至 figures/。中文用 macOS 自带 Hiragino/Arial Unicode。
+重跑：UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/ \
+      uv run --python 3.12 --with matplotlib python scripts/build_preprint_figures.py
+"""
+import os
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.patches import FancyBboxPatch, FancyArrowPatch
+from matplotlib.font_manager import FontProperties
+
+# ---- 中文字体 ----
+_CANDIDATES = [
+    "/System/Library/Fonts/Hiragino Sans GB.ttc",
+    "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",
+    "/System/Library/Fonts/STHeiti Medium.ttc",
+]
+_FP = next((FontProperties(fname=p) for p in _CANDIDATES if os.path.exists(p)), FontProperties())
+def F(size, weight="normal"):
+    fp = _FP.copy(); fp.set_size(size); fp.set_weight(weight); return fp
+
+# ---- 品牌配色 ----
+TEAL      = "#0F8B8D"   # 主青
+TEAL_D    = "#0A5F61"   # 深青
+TEAL_L    = "#D8ECEC"   # 浅青底
+INK       = "#22303A"   # 墨
+GREY      = "#5B6B75"   # 次要文字
+PAPER     = "#FBFCFC"   # 底
+BAND      = "#F0F4F5"   # 层带底
+GOLD      = "#C7853B"   # 强调（核查/阻断）
+GOLD_L    = "#F6EBDA"
+
+OUT = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "figures")
+os.makedirs(OUT, exist_ok=True)
+
+
+def _box(ax, x, y, w, h, fc, ec, lw=1.4, r=0.035, z=2):
+    p = FancyBboxPatch((x, y), w, h, boxstyle=f"round,pad=0.0,rounding_size={r}",
+                       linewidth=lw, edgecolor=ec, facecolor=fc, zorder=z)
+    ax.add_patch(p)
+    return p
+
+
+def _txt(ax, x, y, s, fp, color=INK, ha="center", va="center", z=5):
+    ax.text(x, y, s, fontproperties=fp, color=color, ha=ha, va=va, zorder=z)
+
+
+def _arrow(ax, xy1, xy2, color=TEAL_D, lw=1.6, style="-|>", ms=11, ls="-", rad=0.0, z=4):
+    a = FancyArrowPatch(xy1, xy2, arrowstyle=style, mutation_scale=ms, lw=lw,
+                        color=color, linestyle=ls, zorder=z,
+                        connectionstyle=f"arc3,rad={rad}", shrinkA=2, shrinkB=2)
+    ax.add_patch(a)
+
+
+# =========================================================================
+# 图 1：四层 + 两横切架构与数据流
+# =========================================================================
+def figure1():
+    fig, ax = plt.subplots(figsize=(11.2, 7.6))
+    ax.set_xlim(0, 100); ax.set_ylim(0, 100); ax.axis("off")
+    fig.patch.set_facecolor(PAPER); ax.set_facecolor(PAPER)
+
+    _txt(ax, 50, 96.5, "图 1  PsyClaw 四层加两横切架构与数据流", F(15, "bold"), INK)
+
+    # 用户 / CLI 入口
+    _box(ax, 6, 87.5, 66, 6.6, "#FFFFFF", INK, 1.4)
+    _txt(ax, 10, 90.8, "研究者", F(11, "bold"), INK, ha="left")
+    _txt(ax, 39, 90.8, "自然语言  ·  chat / run / auto", F(10.5), GREY)
+
+    # 横切两条：Harness（左）Memory（右）—— 贯穿四层背景
+    band_top, band_bot = 84.0, 12.0
+    _box(ax, 4.0, band_bot, 6.4, band_top - band_bot, GOLD_L, GOLD, 1.3, r=0.02, z=1)
+    ax.text(7.2, (band_top+band_bot)/2, "Harness 横切\n每步前置检查（失败即阻断）\n机器可读总验收",
+            fontproperties=F(9.2, "bold"), color=GOLD, ha="center", va="center",
+            rotation=90, zorder=3)
+    _box(ax, 89.6, band_bot, 6.4, band_top - band_bot, TEAL_L, TEAL_D, 1.3, r=0.02, z=1)
+    ax.text(92.8, (band_top+band_bot)/2, "Memory 横切\n三层记忆\n方法学·期刊·教训",
+            fontproperties=F(9.2, "bold"), color=TEAL_D, ha="center", va="center",
+            rotation=90, zorder=3)
+
+    # 四层主栈（在两横切之间）
+    lx, lw = 11.6, 76.8
+    layers = [
+        ("L0  路由 Router", "三入口共享路由定义 modes.py：chat（对话）· run（声明式流程）· auto（自主）",
+         77.0, 6.4, TEAL, "#FFFFFF"),
+        ("L1  流程 Workflow", "每类研究 = 一份纯数据（步骤 + 前置检查）；引擎逐步跑 + HITL + 断点恢复 + 总验收",
+         67.6, 6.4, TEAL_L, INK),
+        ("L2  子功能 Step", "每步薄封装：可单用（多为 CLI 命令）· 可拆（纯函数）· 可拼（进任意流程）",
+         58.2, 6.4, TEAL_L, INK),
+        ("L3  实现 Skill + MCP", "既有命令 / 技能 / MCP 后端；统计计算整体落此层",
+         48.8, 6.4, TEAL_L, INK),
+    ]
+    for title, sub, y, h, fc, tc in layers:
+        _box(ax, lx, y, lw, h, fc, TEAL_D, 1.5)
+        _txt(ax, lx + 2.5, y + h*0.66, title, F(11.5, "bold"), tc, ha="left")
+        _txt(ax, lx + 2.5, y + h*0.26, sub, F(8.8), tc if tc != "#FFFFFF" else "#EAF6F6", ha="left")
+
+    # 竖向数据流箭头（逐层）与回流（上行）
+    cx = lx + lw*0.30
+    for y0, y1 in [(77.0, 74.0), (67.6, 64.6), (58.2, 55.2)]:
+        _arrow(ax, (cx, y0), (cx, y1), TEAL_D, 1.8, ms=12)
+    ux = lx + lw*0.70
+    for y0, y1 in [(55.2, 58.2), (64.6, 67.6), (74.0, 77.0)]:
+        _arrow(ax, (ux, y0), (ux, y1), GREY, 1.3, ms=10, ls=(0, (4, 2)))
+    _txt(ax, cx - 1.2, 71.0, "逐层委托", F(8.2), TEAL_D, ha="right")
+    _txt(ax, ux + 1.2, 71.0, "结果 / 证据回流", F(8.2), GREY, ha="left")
+
+    # L3 之下：外部实现（统计外移）——标题独占一行，库框在下
+    _box(ax, lx, 39.6, lw, 7.6, "#FFFFFF", INK, 1.4)
+    _txt(ax, lx + lw/2, 46.1, "统计外移 —— 本仓不实现任何统计算法", F(10.5, "bold"), GOLD)
+    ext = [("pingouin", 13.5), ("statsmodels", 27.5), ("SciPy", 41.5),
+           ("MNE-MCP", 54.5), ("SPSS/Stata/Mplus\n(MCP)", 70.5)]
+    for name, x in ext:
+        _box(ax, x, 40.4, 12.4, 4.1, TEAL_L, TEAL_D, 1.2, r=0.05)
+        _txt(ax, x + 6.2, 42.45, name, F(8.6, "bold"), TEAL_D)
+    for x in [19.7, 33.7, 47.7, 60.7, 76.7]:
+        _arrow(ax, (x, 48.6), (x, 47.5), TEAL_D, 1.2, ms=9, ls=(0, (3, 2)))
+
+    # 四类声明式流程（L1 展开示例）
+    _box(ax, lx, 27.5, lw, 9.5, BAND, GREY, 1.2, r=0.02, z=1)
+    _txt(ax, lx + lw/2, 34.7, "L1 的四类声明式研究流程", F(10, "bold"), INK)
+    flows = [
+        ("文献综述", "clarify → 检索(PRISMA) →\n筛选 → 合成 → 评审"),
+        ("元分析", "校验效应量 → 委托\nstatsmodels 随机效应"),
+        ("实证分析", "数据画像 → 推荐 →\n委托 pingouin/SciPy"),
+        ("质性分析", "转录本 → LLM 辅助\n编码/主题（HITL）"),
+    ]
+    fw = 17.6
+    for i, (nm, desc) in enumerate(flows):
+        x = lx + 2.6 + i * (fw + 1.4)
+        _box(ax, x, 28.4, fw, 4.9, "#FFFFFF", TEAL_D, 1.2, r=0.05)
+        _txt(ax, x + fw/2, 32.4, nm, F(9.3, "bold"), TEAL_D)
+        _txt(ax, x + fw/2, 30.2, desc, F(7.6), GREY)
+
+    # 产物
+    _box(ax, lx, 13.5, lw, 6.2, GOLD_L, GOLD, 1.4)
+    _txt(ax, lx + lw/2, 16.6, "可复现产物", F(10.5, "bold"), GOLD)
+    _txt(ax, lx + lw/2, 14.5,
+         "等效脚本 + 数据指纹  ·  机器可读总验收 workflow_summary.json  ·  按序号归档",
+         F(8.8), INK)
+
+    # 全局竖向主脉：入口→L0→…→产物
+    _arrow(ax, (lx + lw*0.5, 87.5), (lx + lw*0.5, 83.5), INK, 1.6, ms=11)
+    _arrow(ax, (lx + lw*0.5, 48.8), (lx + lw*0.5, 47.3), INK, 1.4, ms=10)
+    _arrow(ax, (lx + lw*0.5, 39.6), (lx + lw*0.5, 37.1), INK, 1.4, ms=10)
+    _arrow(ax, (lx + lw*0.5, 27.5), (lx + lw*0.5, 19.8), INK, 1.4, ms=10)
+
+    # gate 标记（Harness 对每层的约束）示意：右向三角，指向各层
+    for y in [80.2, 70.8, 61.4, 52.0]:
+        ax.plot(10.9, y, marker=">", markersize=9, color=GOLD,
+                markeredgecolor=GOLD, zorder=6)
+
+    fig.subplots_adjust(left=0.01, right=0.99, top=0.99, bottom=0.01)
+    path = os.path.join(OUT, "psyclaw_fig1_architecture.png")
+    fig.savefig(path, dpi=300, facecolor=PAPER)
+    plt.close(fig)
+    return path
+
+
+# =========================================================================
+# 图 2：三理念协同（声明式流程 · 失败即阻断的核查 · 统计外移）
+# =========================================================================
+def figure2():
+    fig, ax = plt.subplots(figsize=(11.2, 6.6))
+    ax.set_xlim(0, 100); ax.set_ylim(0, 100); ax.axis("off")
+    fig.patch.set_facecolor(PAPER); ax.set_facecolor(PAPER)
+
+    _txt(ax, 50, 95.5, "图 2  三项核心设计理念在一个流程步骤上的协同", F(15, "bold"), INK)
+
+    # 中央：一个「流程步骤」
+    _box(ax, 38, 44, 24, 14, TEAL, TEAL_D, 1.8, r=0.06)
+    _txt(ax, 50, 53.3, "一个流程步骤", F(12.5, "bold"), "#FFFFFF")
+    _txt(ax, 50, 49.6, "Step", F(9.5), "#EAF6F6")
+    _txt(ax, 50, 46.4, "（如「分析」「合成」）", F(8.6), "#DCEFEF")
+
+    # 理念一：声明式流程（上）——步骤的来源
+    _box(ax, 30, 78, 40, 12.5, TEAL_L, TEAL_D, 1.5, r=0.05)
+    _txt(ax, 50, 86.4, "① 声明式研究流程", F(12, "bold"), TEAL_D)
+    _txt(ax, 50, 82.7, "流程 = 纯数据（步骤 + 前置检查）；引擎逐步执行，", F(8.9), INK)
+    _txt(ax, 50, 80.2, "可重放、可改装、末尾出机器可读总验收", F(8.9), INK)
+    _arrow(ax, (50, 78), (50, 58.3), TEAL_D, 2.0, ms=13)
+    _txt(ax, 51.5, 68, "定义并驱动", F(8.6), TEAL_D, ha="left")
+
+    # 理念二：失败即阻断的核查（左）——步骤执行前的关卡
+    _box(ax, 3.5, 40, 26, 22, GOLD_L, GOLD, 1.6, r=0.05)
+    _txt(ax, 16.5, 58.0, "② 学术诚信核查", F(12, "bold"), GOLD)
+    for i, s in enumerate([
+        "效应量 + CI 必报",
+        "区分探索 / 确证",
+        "确证须预注册",
+        "相关 ≠ 因果",
+        "图件完整性",
+        "PRISMA · APA7 · 复现脚本",
+    ]):
+        _txt(ax, 6.0, 53.6 - i*2.55, "•", F(9.5, "bold"), GOLD, ha="left")
+        _txt(ax, 8.2, 53.6 - i*2.55, s, F(8.7), INK, ha="left")
+    # 核查把关箭头（阻断/放行）
+    _arrow(ax, (29.5, 51), (38, 51), GOLD, 2.0, ms=13)
+    _txt(ax, 33.5, 53.2, "PASS→放行", F(8.0), TEAL_D)
+    _arrow(ax, (35, 47.5), (31, 43), GOLD, 1.8, ms=12, style="-|>", rad=0.3)
+    _txt(ax, 36.0, 41.0, "FAIL→阻断 + 修复", F(8.0), GOLD, ha="center")
+
+    # 理念三：统计外移（右）——步骤把计算委托出去
+    _box(ax, 70.5, 40, 26, 22, TEAL_L, TEAL_D, 1.6, r=0.05)
+    _txt(ax, 83.5, 58.0, "③ 统计外移", F(12, "bold"), TEAL_D)
+    _txt(ax, 83.5, 54.6, "本仓不实现任何统计算法", F(8.9, "bold"), GOLD)
+    _txt(ax, 83.5, 51.8, "委托成熟库 / MCP 后端：", F(8.6), INK)
+    for i, s in enumerate(["pingouin · statsmodels · SciPy",
+                           "MNE-MCP · SPSS / Stata / Mplus"]):
+        _txt(ax, 83.5, 48.6 - i*2.6, s, F(8.4), TEAL_D)
+    _txt(ax, 83.5, 42.7, "数值正确性归外部库承担", F(8.2), GREY)
+    _arrow(ax, (62, 51), (70.5, 51), TEAL_D, 2.0, ms=13)
+    _txt(ax, 66.2, 53.2, "委托计算", F(8.0), TEAL_D)
+    _arrow(ax, (70.5, 47.5), (62, 45), GREY, 1.4, ms=10, ls=(0, (4, 2)), rad=-0.25)
+    _txt(ax, 66.2, 43.4, "结果回流", F(7.8), GREY)
+
+    # 底部：三者合力 → 产物
+    _box(ax, 22, 12, 56, 12, "#FFFFFF", INK, 1.5, r=0.04)
+    _txt(ax, 50, 20.6, "合力产出", F(11.5, "bold"), INK)
+    _txt(ax, 50, 17.3, "工作流可复现（等效脚本 + 指纹 + 归档）", F(9.0), TEAL_D)
+    _txt(ax, 50, 14.4, "× 内容合规（核查把关）  ×  数值可信（外部库）", F(9.0), GOLD)
+    _arrow(ax, (50, 44), (50, 24.2), INK, 1.8, ms=12)
+
+    fig.subplots_adjust(left=0.01, right=0.99, top=0.99, bottom=0.01)
+    path = os.path.join(OUT, "psyclaw_fig2_principles.png")
+    fig.savefig(path, dpi=300, facecolor=PAPER)
+    plt.close(fig)
+    return path
+
+
+if __name__ == "__main__":
+    p1 = figure1()
+    p2 = figure2()
+    print("wrote:", p1)
+    print("wrote:", p2)

package/scripts/build_three_line_table_fixture.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Build a small DOCX fixture that exercises APA three-line tables."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from psyclaw.output.apa7 import APA7Document
+from psyclaw.output.docx_contract import assert_docx_contract
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("output", nargs="?", default="outputs/three-line-table-test.docx")
+    args = parser.parse_args()
+
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    doc = APA7Document(
+        title="APA 三线表生成测试",
+        authors="PsyClaw DOCX regression fixture",
+        affiliation="Local verification",
+    )
+    doc.add_heading("结果", 1)
+    doc.add_paragraph("以下表格用于检查边框、固定列宽、中文换行与跨页稳定性。")
+    doc.add_stat_table(
+        "Table 1\n描述性统计",
+        ["变量", "n", "M", "SD", "95% CI"],
+        [
+            ["抑郁症状", "128", "14.20", "3.40", "[13.60, 14.80]"],
+            ["焦虑症状", "128", "11.10", "2.90", "[10.59, 11.61]"],
+            ["生活满意度（较长的中文变量名称，用于测试自动换行）", "128", "24.80", "5.10", "[23.90, 25.70]"],
+        ],
+    )
+    doc.add_stat_table(
+        "Table 2\n相关矩阵",
+        ["变量", "1", "2", "3"],
+        [
+            ["1. 抑郁", "—", "", ""],
+            ["2. 焦虑", ".45", "—", ""],
+            ["3. 满意度", "-.31", "-.27", "—"],
+        ],
+    )
+    doc.add_stat_table("Table 3\n仅表头边界情况", ["变量", "结果"], [])
+
+    doc.to_docx(output)
+    result = assert_docx_contract(output)
+    print(f"generated={output.resolve()}")
+    print(f"sha256={result['sha256']}")
+    print(f"tables={result['tables']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())