jfox-session-to-permanent

name

jfox-session-to-permanent

description

Capture CURRENT STATE as permanent notes — project facts, file/script locations, architecture decisions (ADR), design rationale, how things stand now — plus reusable knowledge (tool usage, gotchas, debug patterns). Unlike session-summary (a log of actions: what you did) and organize (refine notes already piled in the inbox), this skill distills current-state facts from the live conversation into permanent notes, dedups against existing ones, and writes after explicit user review. Triggers on: "session to permanent", "提炼到永久笔记", "会话沉淀永久笔记", "把这次对话沉淀成永久笔记", "提炼会话知识", "distill session to permanent", "会话提炼", "沉淀永久笔记", "提炼永久笔记".

JFox 会话沉淀永久笔记（session → permanent）

从当前会话里提炼当前现状，比对已有 permanent 笔记去重，固化成新的 permanent 笔记。核心目的只有一个——让 jfox 知识库充分描述关于你当前的所有事实和现状，这样你随时能审视全局、发现潜在的待办、为后续调整和优化提供方向。

permanent 和 session 的本质要分清：session 记「行为历史」（我最近在做什么、动作序列，是过去式）；permanent 记「当前现状」（事实、设计决策、ADR、文件位置现状，是现在式）。会话里能挖出的「现状」就沉淀为 permanent——即便「后续怎么做」还不清楚，把「当前现状和已做的决策」记下来，后续才有据可依。

和现有 skill 的区别

这三个 skill 容易混淆，先对齐定位：输入和产出不同，适用场景就不同。

skill	输入	产出	区别
jfox-session-summary	当前会话	session 笔记	行为历史：记录「最近在做什么」的动作序列
jfox-organize	inbox / fleeting 笔记	permanent	整理已堆积在收件箱的笔记
jfox-session-to-permanent（本技能）	当前会话	permanent	当前现状：事实、设计决策、ADR、现状快照

一句话：session-summary 记「我最近做了哪些动作」（历史），本技能沉淀「事情当前是什么状态」（现状），organize 整理「早就堆在收件箱的笔记」。

前置条件

• 知识库已初始化（jfox init）。未初始化时，提示用户先调用 /skill:jfox-common 创建。
• pi 平台默认写入默认知识库，下文命令一律不带 --kb（与原 #365 的去重需求一致）。如需写到别的知识库，按 /skill:jfox-common §4.1 的 --kb 约定显式指定。

本技能复用 /skill:jfox-common §4.1 的共享约定（--kb / --json / --content-file），下文示例统一使用 --json 简写。

五步流程

按顺序走：提取 → 去重 → 起草 → 审阅 → 落库。其中去重和审阅是两条硬约束，跳过任何一条都算违规。

Step 1: 会话知识提取

回顾当前会话，挑出能构成当前现状的事实和决策。判断标准是「它是不是描述了当前的某个真实状态或已落定的决策」——只要是的，就值得记，哪怕看起来是项目特定的小事。

值得提炼的（构成当前现状，都要记）：

• 项目事实与现状：脚本/文件/配置的位置、端口号、路径、特定 issue 编号及其当前状态（即便后续会变动，当前这个位置就是现状，值得留底）
• 设计思路与架构决策（ADR）：为什么这么设计、当前决策现状、可能的后续方向（即便后续未定，先把「当前已做的决策」记下来）
• 业务逻辑现状：系统当前如何运作、各组件之间的关系
• 概念理解与原理：工具/机制的工作原理、术语解释
• 工具用法：命令、参数、配置的用法
• 配置坑 / 踩坑教训：为什么会出错、怎么修
• 调试思路 / 最佳实践：排查某类问题的通用路径

要排除的（确实不记）：

• 众所周知的常识（没有信息量）
• 不承载任何现状信息的纯确认（光一句「跑起来了」，若它本身不带现状信息；但「X 方案已验证可行」这种确认了现状的，仍要记）

为什么连项目特定事实都要记：充足且准确的现状描述，是你审视全局、挖掘潜在待办的基础。比如「这里加了个脚本，后续可能挪走」——当前脚本在这个位置就是一条有价值的现状，日后审视时能据此判断是否该整理。permanent 笔记越能完整描述你的所有事实和现状，jfox 就越能帮你发现「该做但还没做的事」。

把筛选结果列成候选清单给用户看一眼（这一步只是预告，草稿还没生成；候选多于 5 条时分批，规则见 Step 4）：

候选知识点（N 条，N>5 时本次将分 ⌈N/5⌉ 批过）：
1. [现状] scripts/foo.sh 当前位于 X，用途是 Y，后续可能挪到 Z
2. [ADR] 某模块为何采用方案 A 而非 B，当前决策已落定
3. [工具用法] jfox suggest-links 的阈值含义与误命中坑

Step 2: 强制去重（硬约束）

对每条候选知识点，先查知识库里有没有，没记录过的才进入起草。这一步防止重复造笔记——已有的就跳过或标记为「补充」。

每条候选跑两个命令，互补使用：

# 1. 关键词搜已有 permanent（找「讲同一件事」的笔记）
jfox search "<知识点关键词>" --type permanent --json

# 2. 语义找关联笔记（找「讲相关概念」的笔记，供起草时嵌入 wiki link）
jfox suggest-links "<知识点一句话摘要>" --json   # 阈值默认 ≥ 0.6

按搜出来的结果给每条候选分三类：

查询结果	判定	处置
已有 permanent 完整覆盖该知识点	已覆盖	跳过，不重复造
已有 permanent 讲了相关主题，但这条是新增量	可补充	标记，起草时准备用 jfox edit 追加到那条已有笔记
没找到对应 permanent	未记录	进入 Step 3 起草新笔记

别只信 suggest-links：它既会按关键词误命中，也会漏掉语义相近的笔记（参见 jfox-promote §6 的已知坑）。关键词搜（jfox search）和语义搜（suggest-links）要一起看，拿不准时手动按概念补查一次。

Step 3: 提炼 permanent 草稿

对「未记录」的候选起草新笔记，对「可补充」的候选准备追加内容。每条草稿都按下面的结构组织。

一事实一笔记：一条 permanent 笔记只讲一个知识点。如果一次会话有多个知识点，分别建多条，别塞进一条。

内容结构（稳定核 + 类型段 + 易变细节）：

<一句话结论。这条笔记最稳定、最值得未来记住的那句话，开门见山放第一句。>

## 为什么（背景与依据）
<这条知识回答的是什么问题；成立的前提/约束/假设。
 若是决策类：写当时的背景、选它的主要原因、以及认真考虑过但没选的替代方案——依据很大程度上在于"被丢弃的选项"。
 没东西可写就整段省略，别硬凑。>

## <类型段，选 0–1 个，标题写实>
<按笔记内容从下方"类型段目录"选一个标题，或整段省略。>

## 怎么用
<什么场景下用、具体步骤或命令。结合示例或命令。>

易变细节处理（写作指导，不是每条笔记的固定段）：路径、版本号、端口、文件位置归到「## 怎么用」，它们是易变的"实现决策"，核（结论 + 为什么）不写具体值、保持常青。只有当「## 怎么用」里确实出现了这类易变值时，才在该段末尾加一句具体的核对提醒（如「端口以 docker-compose.yml 为准」）；没出现就不加——固定的模板话重复进每条笔记会掩盖该条的重点。

选标题的原则：标题要写实、具体——写这条笔记实际在讲的主题，不套抽象类别名；一段一个主题，不用「A与B」复合标题（如不要「运行速度与耗电量」，要拆成两段或选其一）。

类型段目录：按笔记内容选 0–1 个标题；方法/调试类通常省略，直接并进「## 怎么用」。

笔记内容	类型段标题	这一段写什么
机制 / 原理	## 它怎么工作	系统/工具的运作机制、各部分如何配合
现状快照	## 当前现状	脚本/文件/端口/配置的当前位置与状态
自动化链路	## 链路与组件	多组件串联的链路与各组件职责
纯概念	## 概念	可复用的概念、原理、术语解释
方法 / 调试	（省略）	直接写进「## 怎么用」

链路类的提醒：一条笔记若在画多个组件的关系，本质是「迷你 structure note」——组件多了应考虑拆成一个 MOC（见 #376）+ 各组件独立笔记，而不是把所有组件塞进一条 fat note。

自检：把「## 怎么用」整段遮住，剩下的「结论 + 为什么 + 类型段」是否还独立成立、还有价值？是→分层成功；否→核里写进了易变细节，把具体路径/版本挪到「## 怎么用」。

写作规范（遵循 clear-reports 段落写作法）：草稿正文要按下面五条规则写，目的是让读者用最少的力气看懂——permanent 笔记是写给未来的自己看的，清晰比简短更重要。

1. 先给结论，再展开：第一句话就是核心事实，不要先铺背景。读者可能随时不读完，最重要的信息放最前面。
2. 每段一个主题，段首一句概要：一段只讲一件事，第一句点明本段主题。理想效果是只扫每段第一句就能串起整篇逻辑。段落 4–8 句为宜，别两句一段也别一页一段。
3. 术语第一次出现，顺手解释一句：你刚泡在某个概念里半小时（slug、grounding、cosine、MECE……），对未来的读者是生词。第一次出现带半句解释，第二次起可省。
4. 句子要完整，别过度缩写：别丢主语丢动词丢助词（「阈值放宽到 0.4」「全良性」）。写完整句子，宁可多两个字。精简是删掉不重要的信息，不是把句子压成电报。
5. 表格是对比工具，不是结论的替代品：表格适合放同类项横向对比，表上方必须有一句话总结你看完表想让读者记住的结论。逻辑主线永远用文字承载。

嵌入 wiki links：把 Step 2 查到的关联笔记用 [[精确标题]] 嵌进正文（wiki link 必须精确匹配目标笔记标题，短链会悬空——见 jfox-promote §6）。

Step 4: 用户审阅（硬约束）

严禁未经审阅直接 jfox add。 把草稿完整展示给用户，等明确确认。这是本技能和 jfox-session-summary（直接写入）最大的区别——session 笔记是存档可以存完再改，permanent 是知识沉淀，落库前必须过眼。确认环节一律用 pi 的 question 工具出选择题（见下方「审阅交互」），用户方向键选择、回车即确认，不用打字回复。

分批审阅规则：候选分批过，每批最多 5 条。会话短、候选只有 1–2 条就一批过完；候选超过 5 条时，第一批只取 5 条走完 Step 2–5，落库后再回到 Step 1–2 处理剩余候选、启动第二批……直到某一批不足 5 条（即没有额外可记的知识了）才算挖完结束。这样避免一次甩出十几条草稿把用户淹没，也让用户能逐批消化。

展示格式（每批最多 5 条，让用户一眼看到去重结论和草稿内容）：

本次拟沉淀 2 条 permanent：

【1】新笔记：jfox suggest-links 的阈值含义与误命中坑
去重：未记录（search 无命中；suggest-links 最近的相关笔记是 [[ChromaDB 索引重建]]）
草稿：
---
<完整草稿正文>
---

【2】补充到已有笔记：ChromaDB "Error finding id" 排查
去重：可补充（已有 [[ChromaDB 索引重建]]，本条补「多进程并发触发」这个新增量）
追加内容：
---
<要追加的段落>
---

（展示完毕后调用 `question` 工具确认，见下方「审阅交互」）

审阅交互：用 question 工具出选择题

展示完草稿后，调用 pi 的 question 工具（选项的 label 是展示文本，description 是提示语），四个选项覆盖主要处置路径，特殊情况走「其他」自由说明：

question(
    question="请确认如何处置本批 2 条草稿？",
    options=[
        {"label": "全部写入", "description": "本批 2 条全部落库（新笔记 jfox add / 补充 jfox edit）"},
        {"label": "跳过某条", "description": "先指定要跳过的草稿，其余写入"},
        {"label": "改某条", "description": "先修改某条草稿内容，改完重新展示后回到本选择题"},
        {"label": "其他", "description": "以上都不合适，需要自由说明（混合处置、调标题/标签、临时改主意等）"},
    ],
)

按用户选择走分支：

• 全部写入 → 直接进 Step 5 落库。
• 跳过某条 → 再调一次 question，把本批每条草稿列成选项（label 用「编号+标题」），选中即跳过该条；要跳过多条就重复此步，直到用户选「不再跳过」。其余照常写入。
• 改某条 → 同上列出草稿让用户选要改的编号，按反馈改完、重新展示该条草稿，再回到本选择题。
• 其他 → 选项覆盖不了的场景（混合处置、想调整标题/标签、临时改主意等），直接请用户说明意图（打字/语音均可），按其指示处置，处置完再回到本选择题收尾。
• 用户对某条明确说「不要了」→ 等同跳过，不写入；若本批全部被跳过/否决 → 不写入任何内容，按「错误处理」结束。

一批落库后，若仍有剩余候选，继续下一批同样用选择题确认：

question(
    question="本批 5 条已写入，还剩 3 条候选，继续下一批吗？",
    options=[
        {"label": "继续下一批", "description": "回到 Step 1–2 处理剩余候选"},
        {"label": "就此结束", "description": "剩余候选本次不处理"},
    ],
)

选「继续下一批」则回到 Step 1–2 启动下一批；选「就此结束」则本次流程结束。

Step 5: 落库

用户确认后再执行写入。新笔记用 jfox add，补充已有笔记用 jfox edit 追加。

# 新笔记：内容含 [[wiki links]]，类型 permanent
jfox add "<包含 [[links]] 的草稿>" --title "<标题>" --type permanent \
  --tag <tag1> --tag <tag2> --json

# 长内容或含特殊字符，用 --content-file
cat > /tmp/note-draft.md << 'EOF'
<草稿正文>
EOF
jfox add --content-file /tmp/note-draft.md --title "<标题>" --type permanent \
  --tag <tag1> --json

# 补充已有笔记：把追加段落拼到原内容后，整体写回
jfox show <已有笔记_id> --json | jq -r .content > /tmp/existing.md
cat >> /tmp/existing.md << 'EOF'

<追加段落>
EOF
jfox edit <已有笔记_id> --content-file /tmp/existing.md

写入后的验证（jfox show / jfox refs）详见 /skill:jfox-common §4.5。落库后可以顺手 jfox graph --stats --json 看 avg_degree、isolated_nodes 是否健康（目标见 jfox-organize Step 3）。

命令参考

本技能专属命令（通用命令见 /skill:jfox-common §4）：

jfox search "<query>" --type permanent --json   # 关键词搜已有 permanent（去重）
jfox suggest-links "<摘要>" --json              # 语义找关联笔记（去重 + 补链，阈值 ≥ 0.6）
jfox add ... --type permanent                   # 写入新 permanent 笔记
jfox edit <id> --content-file <path>            # 追加内容到已有 permanent 笔记
jfox graph --stats --json                        # 落库后看图谱健康度

错误处理

• 会话里没有可沉淀的现状（没有事实/决策/现状可记，或只剩众所周知的常识）→ 告知用户「本次会话无可沉淀的现状」，不强行造笔记。
• jfox search / suggest-links 因 daemon 未启动而失败 → 提示用户启动 daemon（见 /skill:jfox-common §6），或先用 jfox search 关键词模式（不依赖 embedding）。
• 草稿被用户全部否决 → 不写入任何内容，记录用户反馈后结束。
• suggest-links 返回低匹配度（score < 0.6）→ 不强制补链，但 jfox search 命中或手动判断相关的仍可嵌入。

关键约束

• 去重是硬约束：起草前必须先 jfox search --type permanent 查已有，已覆盖的跳过、可补充的标记。不查就写等于重复造笔记。
• 审阅是硬约束：所有草稿必须完整展示给用户确认后才能落库，严禁直接 jfox add。
• 一事实一笔记：一条 permanent 只讲一个知识点，多个知识点分多条写。
• wiki link 精确标题：[[xxx]] 必须精确匹配目标笔记标题，短链会悬空。
• 默认知识库：pi 平台默认不带 --kb，写入默认知识库；显式指定时用 /skill:jfox-common §4.1 的约定。