thesis-kit

一个把论文写作流程变成“可执行步骤 + 可追踪产物 + 可导出 Word”的本地框架。

你不需要是开发者：把它当作“论文工程化的脚手架/教练”，让你每一步都有产物、有检查、有下一步提示。

Features

• 阶段化写作流程：选题 → 大纲 → 文献综述 → 方法 → 开题 →（后续：数据/分析/成稿/导出）
• 三段式工作法：每个阶段都有 clarify → tasks → implement
  • clarify：把“需要你确认的关键问题”结构化保存
  • tasks：生成可执行的任务清单（便于你或你的 AI 助手照做）
  • implement：把产物写到固定目录（可版本化、可回放）
• 质量门禁：thesis-kit validate 生成报告；export 在存在错误/待核验时默认阻止（可强制导出并记录原因）
• Word 一键导出：使用你学校的 build/reference.docx 作为权威样式来源
• Cursor 友好：初始化后自动生成 thesis.* 命令（在 Cursor 里点一下就跑）
• 可交付草稿：thesis.data / thesis.analysis / thesis.implement 会生成可追踪的草稿与缺口清单，便于你逐步补齐到终稿

Cursor Skill (可下载复用)

仓库已提供可分发 skill 包：

• skills/thesis-kit/

给其他人使用时，直接复制到个人或项目技能目录：

mkdir -p ~/.cursor/skills
cp -R skills/thesis-kit ~/.cursor/skills/thesis-kit

该 skill 内置命令新增脚本，可在目标项目中生成 .cursor/commands/*.md：

bash ~/.cursor/skills/thesis-kit/scripts/add-command.sh thesis.custom --description "自定义命令" --sh "thesis-kit validate --json"

Quick Start

1) 一条命令初始化（推荐，最像 spec-kit 的体验）

你可以不做“先安装再 init”。直接用 uvx 一次性运行：它会拉取最新版本的 thesis-kit 并执行初始化。

• 初始化到新目录（等价于 init <PROJECT_NAME>）：

uvx --from git+https://github.com/hongzexin/thesis-kit.git thesis-kit init my-thesis --wizard --script auto

• 在当前目录初始化（等价于 init --here）：

uvx --from git+https://github.com/hongzexin/thesis-kit.git thesis-kit init --here --wizard --script auto

2) 持久安装（可选）

uv tool install thesis-kit --from git+https://github.com/hongzexin/thesis-kit.git

升级到最新版本（建议每次开始新阶段前跑一次）：

uv tool upgrade thesis-kit --reinstall

3) 初始化你的论文目录（当你选择“持久安装”时）

thesis-kit init my-thesis --wizard --script auto

然后：

• （可选）用 Cursor 打开 my-thesis/：只有你想用 Cursor 里的一键命令 thesis.* 时才需要
• 直接运行 thesis.topic / thesis.outline / thesis.literature / ... 推进流程
  （这些 Cursor 命令是 prompt-first：由 Cursor LLM 读取 .thesis/work/... 并写入产物文件；默认按“最终上交版”标准写作，脚本部分通常只做 thesis-kit validate 自检）

4) 自检（推荐新手先跑）

thesis-kit check

Project Structure

在你的论文目录（比如 my-thesis/）里，核心结构是：

• .cursor/commands/：Cursor 里的 thesis.* 命令（由 init 生成）
• .thesis/stages/<stage>/：每个阶段的过程产物（可追踪、可回放）
  • clarify.json
  • tasks.md
  • implement.json
• 固定写作产物目录（由工具补齐，不覆盖你的手写正文）：
  • .thesis/work/research/：选题与研究问题
  • .thesis/work/thesis/：大纲与论证链 + 章节草稿
  • .thesis/work/literature/：文献综述工作台
  • .thesis/work/methods/：研究方法工作台
  • .thesis/work/proposal/：开题材料
  • .thesis/work/data/、.thesis/work/analysis/
  • .thesis/work/references/、.thesis/work/reports/、.thesis/work/dist/
• build/reference.docx：你学校的 Word 模板（导出样式的“唯一权威来源”）

Usage

方式 A：在 Cursor 里（推荐）

你之所以需要“打开 Cursor”，只有一个原因：要使用 Cursor 的 thesis.* 命令（它们是写在项目目录的 .cursor/commands/ 里）。
如果你只想用命令行跑 thesis-kit ...，完全不需要打开 Cursor。

初始化后直接运行：

• thesis.constitution
• thesis.topic
• thesis.outline
• thesis.literature
• thesis.methods
• thesis.proposal
• thesis.guide
• thesis.data
• thesis.analysis
• thesis.implement
• thesis.analyze
• thesis.checklist
• thesis.export

方式 B：命令行三段式（你想更可控时）

以选题阶段为例：

thesis-kit stage topic clarify --json --set "topic=我的选题想做 XXX"
thesis-kit stage topic tasks --json
thesis-kit stage topic implement --json

说明：

• Cursor 里的 thesis.* 命令偏“写作型”：主要由 Cursor LLM 完成读写文件；CLI 的 stage 偏“可重复执行型”：用于把阶段产物落盘与回放。
• implement 会自动生成/更新本阶段的 clarify.json 与 tasks.md 再执行落盘。
• 如果某阶段定义了“必答问题”而答案缺失：交互模式会提示补答；非交互会直接报错退出（避免卡住）。
• 涉及联网/执行本地动作时需要显式开关（默认安全）：
  • 联网：--network on（非交互还需 --yes）
  • 执行：--exec on（非交互还需 --yes）

校验与导出

thesis-kit validate
thesis-kit export

补充：

• 如需机器可读校验输出：thesis-kit validate --json
• 论文导出默认只包含中文目录（不生成英文目录）。
• 论文导出会按章节文件顺序拼接 chapters/*.md，其中包含 99-references.md 与 100-appendices.md（附录在参考文献之后）。
• 当门禁阻断时，export-gate.md 会给出“学术合规的修改建议”（例如：四级标题改为正文加粗小标题、缩写用脚注解释、长句拆分保持学术语气与逻辑连贯）。

导出目标（可选）：

• thesis-kit export --target thesis：只导出论文
• thesis-kit export --target proposal：只导出开题
• thesis-kit export --target all：两者都导出（默认）

送审模式 vs 草稿模式（非常重要）

• 送审模式（默认）：导出前会运行门禁并阻断以下情况：
  • 占位符/缺口标记（如 【待补】/【待核验】/[@key]）
  • 工具噪声文本（如“自动生成/受控块/缺口清单/本章定位”）
  • 引用缺失（正文引用 key 在 sources.json 不存在）
  • 缺少 GB/T 7714 CSL（.thesis/work/references/gb-t-7714-2015-numeric.csl）
  • 样式差异（reference.docx vs 导出 docx）
  • 结构不完整（关键章节缺失）
• 草稿模式（显式选择）：如果你必须在问题未清零时给导师看版本：
  • 使用 thesis-kit export --force --reason "导师审阅草稿"
  • 系统会留痕，并生成门禁报告帮助你下一轮清零再送审。

其他常用命令（你可以照抄）

• 查看当前阶段与阻塞原因：

thesis-kit status

• 诊断（用于报错反馈/环境信息）：

thesis-kit version

如存在错误级问题但需要给导师看草稿：

thesis-kit export --force --reason "导师审阅草稿"

Configuration

你通常只需要关心三类配置：

• 学校模板：build/reference.docx
• 教学向导输出：.thesis/work/project/profile.yml（由 thesis-kit init --wizard 或 thesis-kit guide 生成）
• 导出规则（可选）：.thesis/work/project/export-rules.json（用于导出门禁）
• 阶段输入：thesis-kit stage <stage> ... --set key=value（把你的关键意图显式化）

补充说明：

• profile.yml 支持：
  • word_count_total：总字数目标（validate 按 ±15% 校验）
  • word_count_by_chapter：每章预算（key 支持 "01" / "1" / "01-introduction"，validate 按 ±15% 校验）
• 成稿阶段会输出缺口清单：.thesis/work/thesis/gaps/implement.md

更多见：tooling/docs/installation.md、tooling/docs/quickstart.md、tooling/docs/upgrade.md

Roadmap

• 接入真实的中文文献检索与更多 provider（仍需 --network on 明确授权）
• 让 data/analysis 的 executor 覆盖更多真实工作流（问卷回收、转写、数据清洗、统计分析模板等）
• 增强“必答问题”与 clarify.json schema/版本迁移
• 更完善的 Windows-first 体验（脚本/命令一致性）

Contributing

欢迎贡献：

• 提交 Issue：bug/需求/学校格式适配建议
• 提交 PR：小步修改 + 测试通过

本仓库已配置 CI（GitHub Actions），PR 会自动跑测试。

详见：CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md

License

MIT，见 LICENSE。