psyclaw 0.25.2 → 0.26.0

package/scripts/build_preprint_figures.py

@@ -1,238 +0,0 @@
-#!/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

@@ -1,56 +0,0 @@
-#!/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())