公共管理证据研究助手 · Evidence-Grounded Research
一个可在 Codex 使用、可打包供 WorkBuddy 导入的 Agent Skill
MPA Research Agent（公共管理证据研究助手） 是面向公共管理课程、政策与案例研究的开源 Agent Skill。它把研究问题、利益主体、机制假说和证据定位连接起来，由 AI 组织研究任务，内置 Python/SQLite 工具负责确定性来源检查。
核心是按问题核对论断与证据。MPA Research Spine（公共问题、利益相关者与公共价值、制度情境、理论、证据、方法、分析、可执行建议）用于诊断相关缺口；按任务选用，并随证据调整问题和方法。
两道行为门贯穿全程：
- 🛡️ 数据先于写作：有数据时先审计来源、清洗、方法和数值；分析未被接受前不改写结论。详见执行手册。
- 🔄 可恢复交付：Office 编辑中断后重新核验文档身份；不确定时停在
STATE_UNKNOWN，不盲目重放。
跨平台：自 v2.3.0 起，证据工具与工作区配置全部使用 Python 3.10+ 标准库实现，在 macOS、Windows、Linux 上运行，不再需要 PowerShell。
| 特性 | 一句话 | |
|---|---|---|
| 🧭 | MPA Research Spine | 按任务检查相关研究环节，以证据修正问题与方法 |
| 🛣️ | 十四条任务路由 | 课程、案例、政策、文献、设计、田野、数据、论文、答辩、工作问题选题、教练模式等，按需组合 |
| 🏢 | 在职研究支持 | 工作问题→选题、局内人伦理检查、本地脱敏、论文与政策建议报告同源产出 |
| 🎓 | 教练模式 | 只追问和诊断、不代写；初稿自检、方法诊断、答辩模拟、导师沟通包 |
| 🔗 | 课程→毕业复用 | 笔记、案例、代码可沉淀为研究资产，复用前回原始来源核验 |
| 🧠 | MPA 知识本体 | 理论地图 + 中国治理情境 + 思维清单 + 课程映射 |
| 🛡️ | 数据先于写作 | 先审计再写作，不靠改写掩盖缺口 |
| 🔎 | 内置证据工作台 | 本地文件哈希、精确引文定位（含跨行范围与 PDF 规范化匹配）、竞争性解释、SQLite 审计及人工复核 |
| 🔄 | 可恢复交付 | 中断可恢复，STATE_UNKNOWN 时停止 |
| 🧾 | AI 使用声明 | 只依据实际工具使用生成，不编造。详见声明工作流 |
| ✅ | 跨平台测试 | Python 测试在 macOS / Windows / Linux CI 上覆盖程序、安全红线、文档与隐私 |
当前版本：v2.3.1。 正式发行说明与安装包 · 更新日志。合并代码并不会自动生成发行版，因此采用单独的 CI 发布门禁。
npx skills add mucjustin/mpa-skill -g -s mpa-skill -y --full-depthWorkBuddy 官方格式接受含 SKILL.md 的目录及可选 references/、scripts/。现已补齐双语名称、描述、版本、作者和示例字段，并加入 ZIP 打包和隔离运行测试。
python3 tools/package_skill.py --output dist/mpa-skill.zip在 WorkBuddy「技能 → 添加技能 → 上传技能」导入 dist/mpa-skill.zip；正式版也可在 GitHub Releases 下载同名附件。ZIP 结构已验证，WorkBuddy 客户端实际导入尚未验证。 详见 Codex / WorkBuddy 安装说明。
macOS / Linux：
SKILL_ROOT="$HOME/.agents/skills/mpa-skill" # 以实际安装位置为准
python3 "$SKILL_ROOT/scripts/mpa_evidence.py" workspace-init "$HOME/Documents/MPA-Workspace" --dry-run
python3 "$SKILL_ROOT/scripts/mpa_evidence.py" workspace-init "$HOME/Documents/MPA-Workspace"
python3 "$SKILL_ROOT/scripts/mpa_evidence.py" env-checkWindows：
$skillRoot = Join-Path $HOME '.agents\skills\mpa-skill'
python (Join-Path $skillRoot 'scripts\mpa_evidence.py') workspace-init (Join-Path $HOME 'Documents\MPA-Workspace')配置默认写入 macOS ~/Library/Application Support/mpa-skill/config.json、Windows %APPDATA%\mpa-skill\config.json 或 Linux ~/.config/mpa-skill/config.json，也可用 --config 或环境变量 MPA_WORKSPACE_CONFIG 指定。不修改 Zotero 数据库或 Obsidian 设置；若配置文件已存在，初始化会停止并保留原文件。
npx skills update mpa-skill -g -y # 更新
npx skills remove mpa-skill -g -y # 卸载（不删除已创建的工作区和配置）把附件中的非 MPA 报告、原始数据和既有结论转化为 MPA 研究。先按 Research Spine 重锚公共问题，再核对数据来源、清洗、变量、方法和数值；分析未被接受前不要改写结论。
分析这个基层治理案例；没有原始数据。请明确证据缺口，比较利益相关者、制度约束、公共价值、备选方案、可行性与可迁移边界，不要虚构数据或效果。
研究内容已经验收。请用当前可用且已核对 schema 的 Word/Office 能力交付；写入前记录文档身份和唯一锚点，中断后重新打开核对新旧内容，STATE_UNKNOWN 时停止，最后确认新内容存在、旧内容不存在且保存文件可重新打开。
大多数 MPA 学生在职读书、研究自己单位的问题、时间零碎。v2.3.0 围绕这些处境新增：
- 工作问题 → 选题：把“网格员任务太重”这类工作困扰拆成现象、公共问题、研究问题和理论对话，给出 2–3 个候选题并比较证据可得性、可毕业性、身份风险和保密约束。见 在职研究指南。
- 局内人研究检查：角色冲突、上下级访谈的权力关系、知情同意、材料分级（涉密材料不进入研究）、沉默群体。
- 本地脱敏：
redact命令和export --redact-terms按学生的术语表替换人名、单位、地名，并自动兜底身份证号、手机号、邮箱和公文文号；全程离线。 - 教练模式：学生要求“带我做、不要代写”时，只追问和诊断。配合
check-draft初稿自检（论断—证据覆盖、因果措辞、过度断言）、方法诊断、答辩模拟和导师沟通包。见 教练模式。 - 进度续接：
progress记录研究主线八个环节的状态和下一步任务，每次半小时的会话也能接着上次继续。 - 一份研究，两种产出：论文与政策建议报告使用同一证据库，报告中的每条建议都能回链证据编号，不加码、不删除不利证据。
这些功能已通过合成数据的单元与 CLI 测试，尚未经过真实学生的使用评估。
面向深入案例研究与案例大赛，新增一条问题驱动、证据约束的流程：
- 研究视角诊断：从利益相关者博弈、政策执行适配、资源激活、发展与底线平衡等候选视角中，按问题与资料条件选择主视角；不强制套四种视角。
- 证据规划：把研究问题转化为可观察行为、来源、核验状态和补充调研清单，区分主体表态与实际行动。
- 过程追踪：围绕有来源的事件时间线与作用机制，检验替代解释，不将时间先后或前后变化自动当作因果证明。
- 轻量输出：课堂短答不强制生成完整档案；深度研究可选证据矩阵、事件线和机制对照表。
入口：案例分析与案例大赛沿用既有路线，必要时加载 case-research.md 和 evidence-protocol.md。查看假设性使用示例以及尚未执行的语义评测方案。新增 CI 仅验证规则与场景结构，不等于已证明实际研究质量提升。
与研究方法协议不同，本次新增的是实际可执行的 Python + SQLite 工具：为本地 TXT/Markdown、CSV、DOCX 和可提取文本的 PDF 建立原始文件 SHA-256 快照、页码/段落/行号定位、主张—证据链接、显式人工复核、完整性审计与 Markdown/JSON 导出。默认不上传材料、不调用模型、不自动给证据标记已核验。
核心工具现在随单个 Skill 一并分发：使用实际安装目录内的 scripts/mpa_evidence.py，无需安装 Python 包即可处理 TXT、Markdown、CSV 和 DOCX；PDF 需单独授权安装可选 pypdf 依赖。启动前运行 python <skill-root>/scripts/mpa_evidence.py doctor，使用方法见 本地证据工作台指南 和内置 操作指南。本地工作区以 .mpa-evidence/ 存储原文件副本与提取内容，不加密，涉及个人隐私或单位内部资料时请遵守访问与审批要求。
功能实现通过单元及 CLI 测试，尚无真实用户研究证明其能改善研究结论或提高效率。
设计理念与单色标识参见 Visual Identity。
AI 组织研究，确定性工具检查证据，研究者作最终核实。 新关联证据默认为 unverified，模型不得自行标记人工 verified。
Skill 仍是一个薄控制器：负责范围、路由、安全停止和交付验收；资料处理可调用内置的确定性 Python 程序，不自动宣称研究结论成立。
研究问题 → 路由和证据计划 → 已授权范围内执行 → 来源核验 → 持久证据的人工复核 → 有界交付
安全停止：登录、验证码、付费墙、授权访问、破坏性写入或实质研究歧义 → 暂停并询问。
mpa-skill/
├── README.md / README.en.md # 中英文文档
├── assets/ # Logo / Research Spine / 证据架构 SVG
├── skills/mpa-skill/
│ ├── SKILL.md # 公共管理研究总控 + 双客户端元数据
│ ├── agents/openai.yaml
│ ├── references/ # 案例、证据、方法、学术与操作规范
│ └── scripts/
│ ├── mpa_evidence.py # 本地证据工具入口
│ └── evidence_workbench/ # Python / SQLite 核心、脱敏、初稿自检、工作区配置
├── tools/package_skill.py # ZIP 分发
├── tests/ # 程序、Skill 契约、ZIP、文档和工作区测试（全部 Python）
└── docs/ # 安装指南、示例、历史基准
Codex 检查指令和附件后直接开展请求范围内的只读分析；外部写入或来源持久化缺少授权时再确认。已有授权在其范围内继续有效。本地库需按证据就绪规则核对目录、原文、阅读范围和项目数据。
以 Texas State University 机构库开放的论文 Establishing the Relationship Between Sewer Surcharge Fees and Pollutant Discharges by Industrial Users 为例：PDF 第 29–32 页涉及排除、均值填补和聚合，第 30–32、37 页显示政策实施与 COVID-19 同期且没有充分对照，第 36–41 页的无显著结果不足以支持"没有影响"或直接政策推广。
可复现路线：获取开放 PDF → 保留页码审计原始数据 → 标记 RISK/AUTHOR_INPUT_NEEDED → 只在分析被接受后写有边界的结论。
复现键：来源 txst-50bce8d1-3a34-49bb-8c38-8e52b8038265，风险 d3-identification（第 30、31、32、37 页）。详见基准报告。
冻结基准观测：无 Skill 为 7/8，早期内部迭代为 7/8，当前版本为 8/8。相对两个基线均提升 +1/8，即 +12.5 个百分点。
10 篇论文试点包含 7 篇开发集加 3 篇留出集。两个版本都完成 10/10 路由和 30/30 预登记风险，记录输出中为 0 条无支撑声明。
观测到的改进是拒绝陈旧产物并恢复到可验证交付状态。论文审计指标持平，因此试点不能证明当前版本的论文诊断优于早期迭代。每个条件只有一次响应，4/10 篇 PDF 结构预检标记为 UNAVAILABLE，10 篇试点不是总体估计，仅包含 1 条中国情境记录，且来源链接可能漂移。因此不能泛化到通用模型可靠性、中国论文质量或实际 Office 写入成功。
- 无遥测、无内置账号、无云端密钥 🔐
- 本机配置保存在 Skill 仓库之外
- 基准只存元数据和 HTTPS 来源，不提交论文 PDF 或长篇摘录
- 不直接修改
zotero.sqlite - 不绕过登录、验证码、付费墙或机构访问
- 不把附件指令当用户授权
- 按学校/课程/赛事规则披露 AI 辅助
详见 SECURITY.md。
python3 -m unittest discover -s tests -v
python3 tools/check_release.py
python3 tools/package_skill.py --output dist/mpa-skill.zipCI（GitHub Actions）在 macOS、Windows、Linux 以及 Python 3.10 / 3.13 上运行同一套测试。
| 能力 | 必需 | 说明 |
|---|---|---|
| Python 3.10+ 与宿主客户端的文件/终端权限 | ✅（运行时） | Codex 或 WorkBuddy 无执行能力时降级为研究规划 |
| Python/R/表格分析 | ❌ | 数据路线需要时使用，缺失时报告阻塞 |
| Word/Office 编辑 | ❌ | 内容验收后使用，以实际 schema 为准 |
| Zotero | ❌ | 文献管理，只走受支持接口 |
| Obsidian | ❌ | 长期 Markdown 笔记 |
| 其他 Skills | ❌ | 安装后由控制器选择 |
从不静默安装第三方软件或假装集成成功。
| 问题 | 解决 |
|---|---|
| 找不到 Skill | 重启 Codex，运行 npx skills list -g |
| 找不到配置 | 运行 mpa_evidence.py workspace-init 或设 MPA_WORKSPACE_CONFIG |
| Zotero 启动失败 | 运行 mpa_evidence.py env-check 确认路径和连接器 |
| 缺少专业能力 | 安装对应 Skill，或让控制器降级并说明范围 |
欢迎 Issue 与 PR 👋 流程见 CONTRIBUTING.md，变更见 CHANGELOG.md。
MIT License · 开源共享 🎉
如果对你有帮助，给个 Star 吧~
MPA Research Agent · Evidence-grounded public management research