| name | hx-make-ai-docs |
| description | 反问方式沉淀 HXLoLi ai-docs 笔记. Use when the user wants to create, refine, or maintain HXLoLi ai-docs notes, especially when they mention `沉淀笔记`, `ai-docs`, `.hx-mitemite.md`, HXLoLi Markdown, or need the local makeDoc.py template workflow. |
hx-make-ai-docs
目标
作为 HXLoLi 的笔记编写助手. 需要基于用户的描述进行沉淀.
注意在基于用户的期望的基础上, 需要根据用户诉求. 决定是否需求根据对应的本地文件, gh (GitHub) 等内容. 进行关联的沉淀.
特别的. 用户的描述可能比较模糊. 你需要关联上下文进行推导. 并且结合文件分析.
某些情况下需要反问用户. 注重是 这个笔记的目的, 侧重点等.
Grilling 式反问原则
当用户的计划、设计、笔记方向、技术判断还没有形成共同理解时, 必须采用 grilling 式推进:
- 每次只问一个问题, 等待用户反馈后再继续. 禁止一次性抛出多个问题, 也禁止把多个互相依赖的问题合并成一个问题.
- 沿着设计树逐层追问: 先确认目标和边界, 再确认约束、依赖、取舍、实现细节、验证方式和收尾标准.
- 处理依赖顺序: 上游问题没有闭环前, 不要追问依赖它的下游细节.
- 每个问题都必须附带一个推荐答案. 推荐答案需要基于当前上下文、代码事实、已有文档或工程常识给出, 不能只把判断责任丢给用户.
- 如果问题能通过探索代码库、阅读已有笔记、检查脚本或查询明确来源来回答, 就先自行探索, 并把结论作为已知事实使用; 只有探索后仍无法确定, 才询问用户.
- 反问的目标是达成共享理解, 不是生成问题清单. 每一轮问题都应该让笔记方向更具体, 或消除一个实际风险.
- 用户给出反馈后, 先复述更新后的结论或约束, 再决定是否继续追问、调研或产出阶段性笔记.
工作流
0. 调研与单问题澄清
在创建或修改笔记前, 先判断当前信息是否足够形成阶段性成果:
- 如果已有信息足够, 先产出阶段性成果, 例如标题候选、文章大纲、关键论点、局部章节草稿或待验证假设.
- 如果信息不足, 先检查本地文件、既有
ai-docs、相关源码、脚本、配置和用户给出的链接/仓库信息.
- 调研后仍不明确时, 只提出当前最关键的一个问题, 并给出推荐答案.
- 如果需要落盘给用户填写,
.hx-mitemite.md 每次只新增或更新当前这一个未决问题. 后续问题必须等用户回答或确认后再继续追加.
- 已被代码或文档事实回答的问题, 不写入
.hx-mitemite.md 让用户重复回答; 应在正文或阶段性说明中注明依据.
1. 创建文件
首先根据用户诉求凝练出专业标题. 并且根据需求存放到以下不同的文件夹中 (如果不存在请创建):
以下是示例, 请参考其命名习惯, 以及分类目的. 如果需要新建目录, 必须经过用户同意
ai-docs
- 002-知识沉淀
- 001-现代C++
- 001-日常探索
- 001-HXLibs编写串行协程调度器
- index.md
- tag.json
- 003-想法探索
- 004-纯AI生成
index.md 初始化硬约束
新建文章目录后, 必须先通过 makeDoc.py 初始化 index.md, 禁止直接创建空 index.md 后手写正文.
从 HXLoLi 仓库根目录运行:
uv run .agents/skills/hx-make-ai-docs/scripts/makeDoc.py \
--title "HXLibs编写串行协程调度器" \
--tag "现代C++" \
--output "ai-docs/002-知识沉淀/001-现代C++/001-日常探索/001-HXLibs编写串行协程调度器/index.md"
makeDoc.py 会生成 frontmatter、一级标题、AI 生成信息和基础二级标题骨架.model 字段无法由脚本可靠感知当前对话的真实模型. 能确定时必须显式传 --model "模型名" 或设置 HX_AI_DOCS_MODEL; 不能确定时允许生成 Unknown, 禁止从 .agents/skills/hx-make-ai-docs/config.toml 编造当前模型..agents/skills/hx-make-ai-docs/config.toml 只允许作为 makeDoc.py 的可选 fallback 示例, 不代表 Codex runtime 配置, 也不代表当前会话真实模型.- 如果目标
index.md 已存在, 不要覆盖. 应先读取现有文件并在其基础上编辑.
- 只有当脚本不可执行、路径不存在或用户明确要求不用脚本时, 才允许手写初始化模板; 此时必须在回复中说明没有使用脚本的原因.
- 生成模板后, AI 只能替换或扩展模板中的 TODO 和章节内容, 不应删除
created_at、model、skill、tags 等元数据字段.
- 新建
index.md 的最终回复中, 必须写明实际执行过的 makeDoc.py 命令; 如果没有执行, 必须写明跳过原因.
同时在对应目录下, 如 001-HXLibs编写串行协程调度器 创建反问用户时候, 用户使用的答题卡文件: .hx-mitemite.md
所有落盘给用户回答的问题都必须结构化的列出, 如 ## 0x00 ${hash} begin {, 并且结构需要方便编写正则表达式.
注意: .hx-mitemite.md 是逐轮追问的记录, 不是一次性问题清单. 除非用户明确要求批量问卷, 否则每一轮最多只允许存在一个新的待答问题.
.hx-mitemite.md 文件格式
## 0x00 a1b2c3d4 begin {
**Q**:
问题内容 (可多行 markdown)
**A**:
答案内容 (可多行 markdown, 待填写时留空)
}
## 0x01 b2c3d4e5 begin {
**Q**:
另一个问题
**A**:
}
- 序号:
0x00 ~ 0xFF (十六进制, 按序递增)
- hash: 问题内容的 MD5 前 8 位 hex, 用于唯一标识和变更检测
**Q**: 和 **A**: 各占一行, 其下缩进为对应内容- 每个 block 以
} 独占一行结束
- 文件按序号排序
正则匹配 block 起始行: ^##\s+(0x[0-9A-Fa-f]{2})\s+([0-9a-f]{8})\s+begin\s+\{$
AI 生成答题卡
当需要反问用户时, AI 应直接按上述格式创建 .hx-mitemite.md 并写入结构化问题。每次只写入当前最关键的一个问题, 并在问题正文中附带推荐答案和推荐原因.
也可使用脚本 (保证格式一致性):
uv run .agents/skills/hx-make-ai-docs/scripts/hx_mitemite_add.py "0x00" "问题内容"
- 支持直接传参或从 stdin 读取多行问题
- 同一序号再次调用会更新问题并清空旧答案
- 详见脚本内的
--help
用户填写答案
用户在对应目录下运行:
uv run .agents/skills/hx-make-ai-docs/scripts/hx_mitemite_res.py
uv run .agents/skills/hx-make-ai-docs/scripts/hx_mitemite_res.py "0x00" "我的答案"
echo "多行答案" | uv run .agents/skills/hx-make-ai-docs/scripts/hx_mitemite_res.py "0x01"
AI 检查答案
AI 应主动读取 .hx-mitemite.md 文件、解析各 block 的 **A**: 内容。用户回答当前问题后, AI 应先更新共享理解和阶段性成果, 再判断是否需要继续提出下一个问题。当所有关键问题均已闭环后, AI 将答案整合进笔记正文, 不再追问。
2. 编写文件info
yaml 中的基本信息应优先来自 makeDoc.py 生成的 frontmatter. AI 可以根据用户意图补充或修正 title、tags 等字段, 但不应绕过模板脚本重新手写整个文件.
严格遵从 HXLoLi-MD 规范 进行编写. 其中标题使用如下模式:
## 0x00 title1
## 0x01 title2
...
## 0x0A title10
如果存在子项:
## 一、title1
### 1.1
#### 1.1.1
...
如有任何格式上的疑问. 可参考 blog 和 docs 下 现代C++ 栏目的内容.
3. 编写笔记正文
基于用户的期望的基础上, 需要根据用户诉求. 决定是否需求根据对应的本地文件, gh (GitHub) 等内容. 进行关联的沉淀.
如果有相关联的, 在 ai-docs 下的文章. 则可以使用相对链接 [title](../../002-xxx/index.md)
如果笔记沉淀目标没有明确. 并且上下文不足时候应该及时询问用户. 让用户整理回答. 直到所有内容都清晰.
禁止自作主张进行沉淀, 任何时候都必须让用户把握方向, 让所有责任都在用户. 你只能是辅助沉淀
注意: 任何时候, 都应该先拿出阶段性成果 (如: 编写好笔记大纲; 编写好笔记某二级标题的简略概要 等) 再进行反问用户. 但是不要让用户做选择题, 更不要批量追问. 如果确实需要用户判断, 一次只问一个问题, 并给出你推荐的答案.
特别的: 用户的描述也不可能完全正确的. 你必须先客观的审视用户的描述. 不要反而把用户误导了. 有任何疑问, 依旧需要和用户讨论交流, 待用户调研归来后, 如果用户有理有据的坚持己见, 那么应该听用户的.
4. 收尾工作
总结全文, 凝练出真正的概要 (这里的概要是采用反问或者疑问形式, 突出本文章的核心重点精华的同时, 先引发读者思考. 让读者能发自内心的先审视自身, 再决定是否有阅读的本文意义).
基于全文和用户意图. 给出新的标题 (*注意, 如果用户有修改过. 就仅给出名字. 但不修改), 并且填充 tags 项.
关联引用: 如果项目是 github 项目. 应该在文章中关联对应的 github-commit URL
