jackin-research

jackin-research

生成一份独立的研究档案——在 jackin❯ 文档站上发布的多页交付成果，用于探讨尚无定论的问题或路线图主题。以简报为导向：先撰写简报，再执行研究。收集并综合证据（网络 + 代码库）；不做产品设计决策。

参考实现：jackin❯ 仓库中的 docs/content/docs/research/token-optimization-research/。

适用场景

• 操作者针对一项需要深入调查的主题运行 jackin-research <slug>。

不适用场景

• 路线图条目的设计决策 → jackin-brainstorm。
• 快速查询 → 使用 deep-research 或直接探索，无需编写研究档案。

参数

• --brief-only — 撰写 prompt.mdx（简报）后停止；之后通过 /goal Follow <brief> 执行。
• --in-roadmap — 将研究发现直接存入路线图条目，而非单独的研究档案（仅适用于小型研究）。
• --web-only / --codebase-only — 将信息收集限制为其中一种方式。

输出布局（默认：单独建文件夹）

docs/content/docs/research/<slug>/
├── meta.json     # { title, defaultOpen:false, pages:[...] } — sidebar order
├── index.mdx     # dossier landing: headline numbers, how-to-read, tier list
├── prompt.mdx    # the brief that was run (the spec; carries the /goal run line)
├── NN-*.mdx      # numbered chapters (00 summary, 01.. foundations, 10-20 areas, 30+ synthesis)
└── tools/        # optional scripts + own meta.json + index.mdx

同时将 <slug> 添加到父级 docs/content/docs/research/meta.json 的 pages 中。大型研究 → 单独建文件夹（默认）；小型研究 → 使用 --in-roadmap。

流程

1. 确定范围 / 撰写简报。 根据主题（或路线图条目）起草或加载 prompt.mdx：任务、章节列表、证据规则。使用 --brief-only 时，到此为止。
2. 收集信息。 通过内置的 deep-research 搜索网络；通过 Explore/grep 探索代码库。每项外部论断都必须附带来源 URL；每个本地数据都必须说明获取方法。
3. 撰写内容。 编写 index.mdx（关键数据 + 阅读指南 + 分级列表）和按固定技术记录架构编写的编号章节；将复现脚本放在 tools/ 下。
4. 配置侧边栏。 创建或更新研究档案的 meta.json 和父级 research/meta.json。
5. 通过文档检查并提交。 从 docs/ 运行 bun 文档检查（build、check:repo-links、tsc --noEmit、test）。提交 docs(research):；推送。

常见错误

• 强行套用问题 / 原因 / 设计的结构——研究档案可以采用自由形式，不必像路线图条目一样。
• 做出设计决策——那属于 brainstorm。
• 外部论断没有来源，或本地数据没有说明获取方法。
• meta.json 中的 pages 与磁盘上的文件不一致。

工具

cargo xtask research scaffold <slug> 会创建文件夹和 meta.json；cargo xtask research check 会校验 pages 是否与磁盘上的文件一致。通常通过外部命令 /goal Follow <brief> 执行研究。