npm - @namewta/speculo - Versions diffs - 0.1.4 → 0.1.6 - Mend

@namewta/speculo 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/speculo/workflows/doc/T-teach/T-teach.md ADDED Viewed

@@ -0,0 +1,147 @@
+---
+id: doc/teach
+category: doc
+name: Teaching Design
+description: 设计交互式学习体验：确立使命、策展资源、构建术语、制作课程、记录洞察
+keywords: [teach, lesson, learning, glossary, 教学, 课程, 术语, 学习]
+---
+# Teaching Design 工作流执行指引
+本工作流用于在项目内围绕一个学习主题，设计并交付交互式教学体验。它是 `doc/T` 入口，覆盖从使命确立到课程产出、参考文档和洞察记录的完整链路。
+## 内置指引
+### 核心理念
+深度学习需要三样东西：
+- **Knowledge（知识）** — 从高质量、高信任度资源获取
+- **Skills（技能）** — 通过你设计的高度相关交互式课程获得
+- **Wisdom（智慧）** — 来自与其他学习者和实践者的互动
+获取知识时，难度是敌人——它会吃掉理解所需的工作记忆。练习技能时，难度是工具——有努力的提取才能建立长期留存。
+### 留存设计原则
+- **Retrieval practice**：让用户从记忆中回忆，而非重新阅读
+- **Spacing**：把练习分散到多节课，不要集中轰炸
+- **Interleaving**：在技能练习中混合不同但相关的主题
+每节课应该短小精悍，在很短时间内可完成。学习者工作记忆很有限，必须控制在容量内。但每节课应该给用户一个具体的小胜利。
+### 最近发展区
+每节课用户都应该感觉被挑战得「刚好够」。判断最近发展区的方法：
+1. 读取 `learning-records/`，了解用户已知什么
+2. 基于使命判断下一个该教什么
+3. 教能放进最近发展区的最相关内容
+### Lesson 铁律
+一节 lesson 是自包含的单个 HTML 文件，保存为 `.speculo/doc/<change>/lessons/<编号>.html`。它必须：
+- **漂亮** — 干净、可读的排版和布局，用户以后会回来复习
+- **短** — 在几分钟内可完成
+- **给一个胜利** — 每节课一个具体可感知的收获
+- **直接关联使命** — 每节课都追溯回 MISSION.md
+- **链向其他资源** — 通过 HTML 锚点链向其他课程和参考文档
+- **推荐一手资料** — 每节课推荐一个最高质量、最高信任度的外部资源
+- **提示提问** — 每节课包含提醒用户向 AI 教师追问
+### 课程结构模板
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<title>课程标题</title>
+<style>
+  body { max-width: 680px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui; line-height: 1.7; color: #1a1a1a; }
+  h1 { font-size: 1.6rem; margin-top: 2.5rem; }
+  blockquote { border-left: 3px solid #ddd; margin-left: 0; padding-left: 1rem; color: #555; }
+  .cite { font-size: 0.85rem; color: #888; margin-top: 2rem; border-top: 1px solid #eee; padding-top: 0.5rem; }
+  .reminder { background: #f5f5f5; padding: 0.8rem 1rem; border-radius: 6px; margin-top: 2rem; font-size: 0.9rem; }
+</style>
+</head>
+<body>
+<!-- 课程内容 -->
+<div class="cite">📖 推荐一手资料：<a href="...">资源标题</a></div>
+<div class="reminder">💡 有疑问？直接问我——我是你的 AI 教师。</div>
+</body>
+</html>
+```
+## 阶段
+> **产物目录：** 本工作流所有产物写入 `.speculo/doc/<change>/`。下文产物路径均相对该 change 目录。
+### 1. Mission Setup — 确立学习使命
+- 规范：`teach-mission.md`
+- 模板：`../_templates/teach-mission-template.md`
+- 产物：`mission.md`
+- 完成准则：
+  - 已追问出具体、可观测的成功标准（非「想了解 X」而是「能做 Y」）
+  - Why / Success / Constraints / Out of scope 四段均已填写
+  - `mission.md` 无残留 `[TODO:]`
+### 2. Resources Curation — 策展可信资源
+- 规范：`teach-resources.md`
+- 模板：`../_templates/teach-resources-template.md`
+- 产物：`resources.md`
+- 完成准则：
+  - 已搜集高信任度知识源（优先一手资料、公认专家、同行评审）
+  - 每条资源有注解：覆盖什么、何时取用
+  - 已找到至少一个可推荐社区（除非用户选择不加入社区）
+  - `resources.md` 无残留 `[TODO:]`
+### 3. Lesson Design — 设计一节交互式课程（主循环）
+- 规范：`teach-lesson.md`
+- 模板：无（HTML 课程见内置指引的课程结构模板）
+- 产物：`lessons/<编号>.html`
+- 完成准则：
+  - 课程短小（几分钟内可完成）、有一个具体胜利、直接关联使命
+  - 课程已链向相关参考文档和其他课程
+  - 课程包含一手资料推荐和 AI 追问提示
+  - 编号从已有最高编号 +1
+### 4. Lesson Wrap — 课程收尾
+- 规范：`teach-lesson-wrap.md`
+- 模板：`../_templates/teach-glossary-template.md`、`../_templates/teach-learning-record-template.md`
+- 产物：`reference/<编号>.html`、`GLOSSARY.md`（持续更新）、`learning-records/<编号>.md`（可选）
+- 完成准则：
+  - 已为该课程创建压缩参考文档（cheat sheet / 速查）
+  - 用户在本课中真正理解的术语已收录进 GLOSSARY.md
+  - 若产生非显而易见的洞察，已写 learning record
+  - 已更新 `NOTES.md`（若用户表达了教学偏好）
+## 依赖
+- 硬依赖：Phase 1 → Phase 2，使命未确立前不得策展资源
+- 软依赖：Phase 2 → Phase 3，建议先有资源再设计课程
+- Phase 3 ↔ Phase 4 为紧密循环：每节课程完成后立即收尾
+## 状态扩展字段
+本工作流需在同 change 的 `.status.json` 追加：
+- `doc_entry` (string) — 固定为 `doc/T`
+- `mission_status` (drafting | confirmed) — 使命确认状态
+- `resource_count` (number) — 已策展资源数量
+- `lesson_count` (number) — 已创建课程数量
+- `reference_count` (number) — 已创建参考文档数量
+- `learning_record_count` (number) — 已写学习记录数量
+- `glossary_term_count` (number) — 术语表条目数
+- `current_loop` (mission | resources | lesson | wrap) — 当前循环位置
+## 完成与状态更新
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- Phase 1 完成且用户确认使命后，`mission_status` 置为 `confirmed`。
+- Phase 3-4 为循环：每次完成一节课程和收尾后，更新 `lesson_count`、`reference_count`、`glossary_term_count`。
+- 每次捕捉到学习洞察时追加 `learning_record_count`。
+- 用户声明学习目标全部达成后，可把 `change_status` 置为 `completed`。
+- 如有可沉淀教学经验，在用户允许时追加到 `.speculo/.config/LESSONS.md`。
+- NOTES.md 作为教学偏好暂存区，AI 在后续课程设计中应参考其中记录。

package/speculo/workflows/doc/T-teach/teach-lesson-wrap.md ADDED Viewed

@@ -0,0 +1,63 @@
+# Lesson Wrap Phase
+本阶段在每节课程完成后立即执行，产出该课的压缩参考文档、更新术语表，并在产生非显而易见的洞察时写学习记录。
+## 输入
+- `.speculo/doc/<change>/lessons/<编号>.html` — 刚完成的课程
+- `.speculo/doc/<change>/GLOSSARY.md` — 已有术语表（若不存在则创建）
+- `.speculo/doc/<change>/learning-records/` — 已有学习记录
+- `.speculo/doc/<change>/NOTES.md` — 用户教学偏好
+## 产物
+- `.speculo/doc/<change>/reference/<编号>.html` — 本节课程的压缩参考文档
+- `.speculo/doc/<change>/GLOSSARY.md` — 更新后的术语表
+- `.speculo/doc/<change>/learning-records/<编号>.md` — 可选，仅当产生了非显而易见的洞察
+- `.speculo/doc/<change>/NOTES.md` — 可选，仅当用户表达了新的教学偏好
+## 填写引导
+### 创建参考文档
+1. 从刚完成的课程中提取最核心的内容——语法、算法、步骤、要点。
+2. 写成紧凑的 HTML 速查文档，设计上适合打印。干净排版，易扫读。
+3. 链接回原课程 HTML 和术语表中的相关条目。
+4. 参考文档是课程被复习时的入口——课程很少被重看，参考文档会。
+### 更新术语表
+1. 仅当用户在本课中**真正理解**了某个术语时才收录——术语表是压缩知识的记录，不是字典。
+2. 每条定义 1-2 句，说清术语**是什么**，不说它做什么或怎么做。
+3. 有多个同义词时选最佳者，其余标为「避免使用」。
+4. 术语表自身术语应互相引用——一旦一个术语入库，后续定义优先使用它。
+5. 用户理解加深时在原文上修订，不留过时条目。
+### 写学习记录（可选）
+仅当以下任一条件成立时写：
+1. 用户展示了非显而易见的真正理解
+2. 用户披露了先验知识（避免后续重新教）
+3. 一个误解被纠正（高价值：预测后续相关主题的绊脚石）
+4. 使命因学习而改变（更新 mission.md 并交叉引用）
+学习记录是精简的 ADR：1-3 句写清学到了什么以及为什么这会影响后续课程。编号从已有最高 +1。
+### 更新 NOTES.md
+若用户在本课中表达了教学偏好（如「我更想要视频」「不要太多术语」「多给练习」），记录到 NOTES.md 供后续课程设计参考。
+## 边界
+- 不写入用户尚未真正理解的术语。
+- 学习记录不记「已覆盖了某内容」——覆盖不等于学会。
+- 不重复术语表中已有的内容到学习记录中。
+## 完成准则
+- 参考文档已创建在 `reference/<编号>.html`
+- 用户本课真正理解的术语已收录进 `GLOSSARY.md`（或确认无需新增）
+- 若产生符合条件的学习洞察，已写 learning record
+- 若用户表达了新偏好，已更新 `NOTES.md`
+- `.status.json` 已更新 `lesson_count`、`reference_count`、`glossary_term_count`、`learning_record_count`

package/speculo/workflows/doc/T-teach/teach-lesson.md ADDED Viewed

@@ -0,0 +1,53 @@
+# Lesson Design Phase（主循环）
+本阶段是教学设计的核心循环。每次执行只设计**一节**课程，完成后进入 Phase 4 收尾，再回到本阶段设计下一节。
+## 输入
+- `.speculo/doc/<change>/mission.md` — 教学使命
+- `.speculo/doc/<change>/resources.md` — 可信资源
+- `.speculo/doc/<change>/GLOSSARY.md` — 已有术语（若存在）
+- `.speculo/doc/<change>/learning-records/` — 已有学习记录
+- `.speculo/doc/<change>/NOTES.md` — 用户教学偏好（若存在）
+- `.speculo/doc/<change>/lessons/` — 已有课程（判断最近发展区）
+## 产物
+- `.speculo/doc/<change>/lessons/<编号>.html`，按 `T-teach.md` 内置指引中的课程结构模板创建
+- 编号规则：扫描 `lessons/` 下已有最高编号 +1，起始 `0001`
+## 填写引导
+1. **判断最近发展区**：
+   - 读取已有 learning records 和 GLOSSARY.md，了解用户已知什么
+   - 基于使命中尚未覆盖的 Success 项，选择下一个该教的内容
+   - 教能放进最近发展区的最相关内容
+2. **知识先行，技能随后**：
+   - 课程前半段：从 resources.md 中的高信任度源提取知识，用最简洁的方式呈现
+   - 课程后半段：设计交互式练习或真实世界步骤，让用户实践
+   - 知识部分引用来源，每条声明有出处
+3. **设计反馈循环**：
+   - 如果是问答题，每个选项等长（避免通过格式暗示答案）
+   - 反馈尽可能即时、自动
+   - 练习的目标是建立 storage strength，不是 fluency
+4. **保持短小**：课程应在几分钟内完成。如果知识或练习过多，拆成多节。
+5. **关联使命**：课程开头一句话说明本节如何贡献于使命中的哪个 Success 项。
+6. **链向其他材料**：通过 HTML 锚点链向已有术语表、参考文档和相关课程。
+7. **每节课程末尾**：推荐一个一手资料（从 resources.md 中选取）+ 提示用户可追问 AI 教师。
+8. **创建后**：尝试自动打开 HTML 文件供用户查看。
+## 边界
+- 每次只设计一节课程，不批量预写后续课程。
+- 不编造知识——所有事实性声明必须来自 resources.md 中的资源。
+- 不假设用户记得上一节的内容——可以引用但关键概念要简要回顾。
+- 不在课程中加入超出使命范围的话题。
+## 完成准则
+- 课程 HTML 已创建在 `lessons/<编号>.html`
+- 课程短小（几分钟内可完成）
+- 课程包含知识部分（有引用来源）+ 技能练习部分（有反馈循环）
+- 课程关联使命中的具体 Success 项
+- 课程包含一手资料推荐和 AI 追问提示
+- `T-teach.md` 内置指引的课程铁律已全部满足

package/speculo/workflows/doc/T-teach/teach-mission.md ADDED Viewed

@@ -0,0 +1,33 @@
+# Mission Setup Phase
+## 输入
+- 用户声明的学习主题或模糊兴趣
+- 用户对「为什么想学这个」的任何初始表述
+- 当前 doc change 目录：`.speculo/doc/<change>/`
+## 产物
+- `.speculo/doc/<change>/mission.md`，由 `../_templates/teach-mission-template.md` 填写
+## 填写引导
+1. 若用户未给出具体目标，追问「你学这个最终想做到什么？」，直到得到可观测的行为描述——不是「了解 X」而是「能做 Y」。
+2. 从用户的回答中提炼 Why（1-3 句）、Success（具体可观测事项）、Constraints（时间/预算/偏好）、Out of scope（明确不做的话题）。
+3. 追问时保持具体：避免抽象框架，逼向真实世界的成果。
+4. 用户说不清时，继续访谈；坏使命比没使命更糟，但模糊使命也要被推回。
+5. 使命确立后与用户逐条确认，确认后才进入 Phase 2。
+## 边界
+- 不在此阶段搜集学习资源或设计课程。
+- 不编造用户的动机或目标——一切来自用户原话。
+- 使命可以后续修订，但修订必须经用户确认并写 learning record 记录变更原因。
+## 完成准则
+- Why / Success / Constraints / Out of scope 四段均已填写
+- 每条 Success 是可观测的、可判断是否达成的
+- 用户已逐条确认使命内容
+- `mission.md` 无残留 `[TODO:]`
+- 已创建 `NOTES.md`（空文件，用于后续记录教学偏好）

package/speculo/workflows/doc/T-teach/teach-resources.md ADDED Viewed

@@ -0,0 +1,36 @@
+# Resources Curation Phase
+## 输入
+- `.speculo/doc/<change>/mission.md`（已确认的使命）
+- 用户的社区偏好（是否愿意加入线上/线下社区）
+- 当前 doc change 目录：`.speculo/doc/<change>/`
+## 产物
+- `.speculo/doc/<change>/resources.md`，由 `../_templates/teach-resources-template.md` 填写
+## 填写引导
+1. **搜罗知识源**：针对使命中的每个 Success 项，搜寻高信任度资源。
+   - 优先：一手资料、公认专家著作、同行评审、强审核社区
+   - 避开：营销伪装成教育的内容、无引用的自媒体
+2. **注解每条资源**：用一句话写清覆盖什么、何时取用。裸链接三个月后无用。
+3. **分 Knowledge / Wisdom 两组**：
+   - Knowledge：书籍、文章、课程、论文——用于获取知识
+   - Wisdom：社区、论坛、线下课——用于获取智慧
+4. **标明缺口**：若某个 Success 项找不到好资源，在 `## Gaps` 段写明。
+5. **用户选择不加入社区时**，在 Wisdom 段记录此偏好，后续课程中不再推荐社区。
+## 边界
+- 不在此阶段设计课程。
+- 不因为资源少而编造或降级标准。
+- 不在 resources.md 中写课程计划或教学大纲。
+## 完成准则
+- 已针对使命中每个 Success 项搜集至少一条高信任度知识源（或在 Gaps 中标记缺失）
+- 每条资源有注解
+- 已找到至少一个可推荐社区（或记录用户拒绝社区）
+- `resources.md` 无残留 `[TODO:]`

package/speculo/workflows/doc/_templates/mao-consultation-output-template.md ADDED Viewed

@@ -0,0 +1,54 @@
+> **服务工作流：** `../M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md`
+> **产物文件名：** `consultation-output.md`
+# 咨询输出
+> 以下为教员第一人称的整合咨询答复。由 Phase 1-4 的 problem-statement、analysis、strategy、action-plan 整合而成。
+## 问题回顾
+同志，你来找我谈的是这么一件事——
+[TODO: 从 problem-statement.md 提炼，2-3 句概括用户处境]
+## 诊断
+[TODO: 从 analysis.md 提炼主要矛盾判断，遵循五拍论证节奏——破题→切割→定向→点睛→收尾]
+谁是我们的朋友？谁是我们的敌人？[TODO: 力量格局定性]
+这件事的根本问题，不是……而是……[TODO: 剥掉表象]
+捉住了这个主要矛盾——[TODO: 明确写出]，一切问题就迎刃而解了。
+这就像 [TODO: 1 个比喻点睛]
+## 战略
+我们的方针是——[TODO: 从 strategy.md 提炼，一句话方向判断]
+分几步走：[TODO: 阶段划分与关键战役]
+在战略上我们要藐视它，在战术上我们要重视它。[TODO: 具体展开]
+## 行动
+怎么打？[TODO: 从 action-plan.md 提炼，每个阶段配方法]
+桥和船在这里：[TODO: 具体方法，2-3 步]
+打了再看。实践是检验真理的唯一标准。[TODO: 检验方式]
+## 收尾
+[TODO: 给信心，承认道路曲折，落脚到"人"和"群众"]
+道路是曲折的，前途是光明的。
+---
+## 引用索引
+| 引文 | 篇目 | 编号 |
+|------|------|------|
+[TODO: 逐条列出本文引用的毛泽东原文、篇目名、编号]

package/speculo/workflows/doc/_templates/teach-glossary-template.md ADDED Viewed

@@ -0,0 +1,25 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `GLOSSARY.md`
+# [TODO: 学习主题] Glossary
+[TODO: 1-2 句描述本术语表覆盖的主题范围。]
+## Terms
+[TODO: 每个术语 1-2 句，说清它**是什么**，不说它做什么或怎么做。术语表自身术语互相引用。]
+**[TODO: 术语名]**：
+[TODO: 定义——术语是什么。]
+_Avoid_: [TODO: 列出应避免的同义词或不当用语]
+**[TODO: 术语名]**：
+[TODO: 定义。]
+_Avoid_: [TODO: 不当用语]
+## Rules
+- 仅在用户**真正理解**术语后才收录——术语表是压缩知识的记录，不是字典。
+- 有自己的观点：当多个词指向同一概念时，选最佳者，其余标为避免使用。
+- 定义内部使用术语表自身的术语——一旦入库，后续定义优先使用它。
+- 理解加深时在原文上修订，不留过时条目。
+- 若某术语在更广领域中用法模糊，注明本 workspace 内的约定用法。

package/speculo/workflows/doc/_templates/teach-learning-record-template.md ADDED Viewed

@@ -0,0 +1,37 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `learning-records/<编号>.md`
+学习记录使用顺序编号：`0001-<slug>.md`、`0002-<slug>.md`。首次写入时创建目录。
+每一条是精简的 ADR：1-3 句写清学到了什么以及为什么这会影响后续课程。编号从已有最高 +1。
+## 模板
+```markdown
+# [TODO: 简短标题——学到了什么或建立了什么认知]
+[TODO: 1-3 句。学到了什么（或建立了什么先验知识），以及为什么这会影响后续课程。]
+```
+## 何时写
+仅在以下任一条件成立时写：
+1. **用户展示了非显而易见的真正理解** — 不是仅仅接触过，而是有证据表明能正确使用这个概念。这为后续教学设定了新底线。
+2. **用户披露了先验知识** — 「我已经知道 X」。记录下来避免后续重新教。同时记录声称的深度。
+3. **一个误解被纠正** — 用户之前相信了错误的东西，现在明白了为什么。高价值：预测后续相关主题的绊脚石。
+4. **使命因学习而改变** — 用户发现自己在意的和最初想的不同。交叉引用 [[mission.md]] 并更新它。
+### 不写的情况
+- 仅仅覆盖过的内容。覆盖 ≠ 学会。等证据。
+- 已被 GLOSSARY.md 精简收录的术语定义。不重复。
+- 逐节课的活动日志。学习记录不是流水账——是决策级的洞察。
+## 可选节
+仅在真正增值时加入：
+- **Status frontmatter**：`active | superseded by LR-NNNN` — 当早期理解被后续认知推翻时使用。
+- **Evidence**：用户如何展示理解（回答的问题、完成的练习、引用的先验经历）。
+- **Implications**：这对后续课程解锁或排除了什么。

package/speculo/workflows/doc/_templates/teach-mission-template.md ADDED Viewed

@@ -0,0 +1,18 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `mission.md`
+# Mission: [TODO: 学习主题]
+## Why
+[TODO: 1-3 句。用户追逐的具体真实世界目标。学会这个之后，他们的生活或工作中会发生什么改变？避免「想了解 X」这类抽象表述——逼向底层成果。]
+## Success looks like
+- [TODO: 一个具体的、可观测的用户将能做到的事项]
+- [TODO: 另一个具体事项]
+- [TODO: …]
+## Constraints
+- [TODO: 时间、预算、先验承诺、学习偏好——任何限定教学方式的约束]
+## Out of scope
+- [TODO: 用户明确不想现在涉及的相邻话题——保护最近发展区]

package/speculo/workflows/doc/_templates/teach-resources-template.md ADDED Viewed

@@ -0,0 +1,17 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `resources.md`
+# [TODO: 学习主题] Resources
+## Knowledge
+- [TODO: 格式：`[类型: _标题_ — 作者（出处）](链接)`，下一行缩进写用途。优先一手资料、公认专家、同行评审。]
+  [TODO: 覆盖什么、何时取用。]
+## Wisdom (Communities)
+- [TODO: 格式同 Knowledge。线上论坛、线下课、本地兴趣小组。]
+  [TODO: 用于什么场景的反馈或讨论。]
+## Gaps
+[TODO: 若某 Success 项找不到好资源，在此列出。用户选择不加入社区时也在本节记录。]