jackin-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

jackin-research

Produce a standalone research dossier — a multi-page deliverable published on the jackin❯ docs site — for an open question or roadmap topic. Brief-driven: author the brief, then execute it. Gathers and synthesizes evidence (web + codebase); does not make product design decisions.

Reference implementation:

docs/content/docs/research/token-optimization-research/

in the jackin❯ repo.

生成一份独立的研究报告——发布在jackin❯文档站点的多页交付成果——用于开放性问题或路线图主题。以任务简报为驱动：先撰写简报，再执行。收集并整合证据（网页+代码库）；不做产品设计决策。

参考实现：jackin❯仓库中的

docs/content/docs/research/token-optimization-research/

。

When to use

使用场景

Operator runs
```
jackin-research <slug>
```
for a substantial investigation.

运维人员运行
```
jackin-research <slug>
```
进行深度调研。

When NOT to use

不适用场景

Design decisions on a roadmap item →
```
jackin-brainstorm
```
.
Quick lookup →
```
deep-research
```
or Explore directly, no dossier.

对路线图项做设计决策 → 使用
```
jackin-brainstorm
```
。
快速查询 → 使用
```
deep-research
```
或直接探索，无需生成报告。

Arguments

参数

```
--brief-only
```
— author
```
prompt.mdx
```
(the brief) and stop; execute later via
```
/goal Follow <brief>
```
.
```
--in-roadmap
```
— store findings inline in the roadmap item instead of a separate dossier (small research only).
```
--web-only
```
/
```
--codebase-only
```
— restrict gathering to one pass.

```
--brief-only
```
— 撰写
```
prompt.mdx
```
（任务简报）后停止；后续通过
```
/goal Follow <brief>
```
执行。
```
--in-roadmap
```
— 将调研结果存储在路线图项内，而非单独的报告中（仅适用于小型调研）。
```
--web-only
```
/
```
--codebase-only
```
— 限制仅从单一渠道收集信息。

Output layout (default: separate folder)

输出结构（默认：独立文件夹）

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

Also add

<slug>

to the parent

docs/content/docs/research/meta.json

pages

. Big research → own folder (default); small →

--in-roadmap

docs/content/docs/research/<slug>/
├── meta.json     # { title, defaultOpen:false, pages:[...] } — 侧边栏顺序
├── index.mdx     # 报告首页：关键数据、阅读指南、层级列表
├── prompt.mdx    # 执行的任务简报（规格说明；包含/goal运行指令）
├── NN-*.mdx      # 编号章节（00 摘要、01..基础内容、10-20 调研领域、30+ 综合分析）
└── tools/        # 可选脚本 + 专属meta.json + index.mdx

同时将

<slug>

添加至父目录

docs/content/docs/research/meta.json

的

pages

中。大型调研→使用独立文件夹（默认）；小型调研→使用

--in-roadmap

参数。

Process

流程

Scope / brief. From the topic (or roadmap item), draft or load
```
prompt.mdx
```
: mission, chapter list, evidence rules. With
```
--brief-only
```
, stop here.
Gather. Web via the built-in
```
deep-research
```
; codebase via Explore/grep. Every external claim carries a source URL; every local number carries its method.
Write.
```
index.mdx
```
(headline numbers + how-to-read + tier list) and the numbered chapters in a fixed per-technique record schema; bundle any reproduction scripts under
```
tools/
```
.
Wire the sidebar. Create/update the dossier
```
meta.json
```
and the parent
```
research/meta.json
```
.
Docs gate + commit. Run the
```
bun
```
docs gate (
```
build
```
,
```
check:repo-links
```
,
```
tsc --noEmit
```
,
```
test
```
) from
```
docs/
```
. Commit
```
docs(research):
```
; push.

范围界定/撰写简报。根据主题（或路线图项），起草或加载
```
prompt.mdx
```
：任务目标、章节列表、证据规则。若使用
```
--brief-only
```
参数，在此步骤停止。
收集信息。通过内置的
```
deep-research
```
获取网页信息；通过Explore/grep获取代码库信息。所有外部引用需附带来源URL；所有本地数据需说明获取方法。
撰写内容。编写
```
index.mdx
```
（关键数据+阅读指南+层级列表）和固定格式的编号章节；将任何复现脚本整理至
```
tools/
```
目录下。
配置侧边栏。创建/更新报告的
```
meta.json
```
以及父目录
```
research/meta.json
```
。
文档校验与提交。在
```
docs/
```
目录下运行
```
bun
```
文档校验（
```
build
```
、
```
check:repo-links
```
、
```
tsc --noEmit
```
、
```
test
```
）。提交时使用
```
docs(research):
```
前缀；推送代码。

Common mistakes

常见错误

Forcing a Problem/Why/Design shape — a dossier is free-form, not a roadmap item.
Making design decisions — that is
```
brainstorm
```
.
An unsourced external claim, or a local number without its method.
```
meta.json
```
```
pages
```
out of sync with the files on disk.

强行套用“问题/原因/设计”结构——研究报告为自由格式，并非路线图项。
做出设计决策——这是
```
brainstorm
```
的职责。
外部引用无来源，或本地数据未说明获取方法。
```
meta.json
```
中的
```
pages
```
与磁盘上的文件不同步。

Tooling

工具支持

cargo xtask research scaffold <slug>

creates the folder +

meta.json

;

cargo xtask research check

validates

pages

against disk. Execution typically runs via the external

/goal Follow <brief>

cargo xtask research scaffold <slug>

用于创建文件夹和

meta.json

；

cargo xtask research check

用于校验

pages

与磁盘文件是否一致。执行通常通过外部的

/goal Follow <brief>

完成。