用模板写文档

模板就是一篇打了 template 标签的普通文档。周报该有哪几节、技术方案要不要写非目标、值班记录必填哪些字段——把骨架发成模板，之后每次（尤其是让 agent 写）都从它开始，同类文档结构才不会各写各的。

为什么是标签而不是单独一种东西

版本：模板改了就是发新版本，能回滚，历史可查
可见性：自己的模板 private，只有自己（和 agent）用；管理员 --official 上架就是全站模板
检索：站内按 template 标签一览；agent 走 MCP 的 list_templates，模板还会直接出现在 agent 的 prompts 里（见下）

站点不做任何变量替换。模板原样发出去，怎么填是写作者（或 agent）的事。

写一份模板

开头放一段元数据注释，告诉 agent 这份模板叫什么、什么时候用；正文里用 HTML 注释写「这一节填什么」。注释渲染时不可见，填完顺手删掉：

# 周报：{{周}}

<!-- jiandu-template
name: weekly
description: 周报 / 本周进展同步。触发：周报、weekly
-->

<!-- 第一段一句话总结本周，会截成列表页摘要 -->

## 进展

<!-- 已上线 / 已合入的，一条一个链接 -->

## 进行中

## 下周

## 风险

发布：

jdu template push weekly.md --title "模板：周报"
jdu template push weekly.md --title "模板：周报" --official   # 管理员：上架为全站模板

template push 等于 jdu push 再打上 template 标签；更新已有模板（--id）时会保留它原有的其它标签。没写元数据注释会提醒一句，模板照样能用：agent 侧 name 退回文档 id、description 退回摘要。

name 只能用字母、数字、-、_（它会拼进 agent 的命令名）；description 写清「什么场景用」，最好带几个触发词——agent 靠它决定要不要用这份模板。

要让 agent 开写前先问几个变量，加一行 arguments，正文里用 {{名字}} 占位：

<!-- jiandu-template
name: weekly
description: 周报 / 本周进展同步。触发：周报、weekly
arguments: week（本周编号，如 2026-W36）; owner?（负责人）
-->

# 周报：{{week}}

分号分隔，名字后面带 ? 的是可选；Claude Code 里 /mcp__jiandu__weekly 2026-W36 就把 {{week}} 换掉了，可选参数没给就是空。替换发生在 agent 这一侧，站点本身还是不做任何变量替换。

已经有一份 Claude Code / codex 的 SKILL.md？直接 jdu template push SKILL.md：文首 --- 包起来的 frontmatter 不会渲染，里面的 name / description 就当元数据用，没有一级标题时标题也取自它。

用模板

jdu template list                       # 我的 + 官方
jdu template pull <docId> --out 本周.md  # 取原文到文件，填完 jdu push 本周.md

agent 侧（Claude Code 等接了 jdu mcp 的）有两条路：

直接当 prompt 用：每份模板就是一个 MCP prompt，Claude Code 里输入 /mcp__jiandu__weekly 这样的命令，agent 拿到骨架和「填完 push_doc」的说明就开始写；对话里说「写周报」，agent 也会按 description 自己匹配
当资料查：list_templates → read_doc 拿骨架 → 按节填 → push_doc

同名模板按我的 > 官方取。agent 每取用一次，jdu template list 的 USES 列就加一，攒多了能看出哪些模板真有人用。站上已经有三份官方模板可以直接用：周报、技术方案、从已有文章提炼模板与方法论。

让 agent 从已有文章反推模板

不用从零设计模板。同类文档已经写过几篇了，就让 agent 读那几篇，把反复出现的节抽成模板，把「写得好的那篇多做了什么」抽成方法论：

/mcp__jiandu__distill 故障复盘

或者直接在对话里说「站上有几篇故障复盘，帮我提炼成模板」。agent 会按标签或关键词搜出样本、逐篇读全文、按节出现频次归并结构，最后发两篇文档：一份 template 标签的模板，一份配套方法论。站上没有这类历史文章时它会直接问你该有哪几节，不会凭空编。

样本少于三篇的提炼结论会被标注「待验证」——先照着写两三篇，再回头跑一次提炼，模板会准得多。