kk-session-extract

kk-session-extract

从当前会话中可见的内容提取持久项目知识，将其暂存为普通的 proposal_status: done 会话日志，然后立即运行共享的整理流程。你在宿主环境的实时上下文窗口中操作——不启动无头测试环境，也不运行守护进程。

**路由：**用户已知道节点时使用 /kk-add；当前会话刚刚产生了持久的经验要点时使用 /kk-session-extract；稍后处理累积的捕获日志时使用 /kk-curate。

**上下文不完整警告：**如果发生过上下文压缩，可见上下文可能不完整。除非运行时提供完整转录，否则请将提取描述为基于可见上下文的提取，而不是完整会话提取。

确定项目根目录

使用随附的检测器解析仓库根目录（即包含 .ai/kenkeep 的目录），然后将输出的路径视为以下所有命令的工作目录：

KK_REPO_ROOT=$(node .ai/kenkeep/scripts/kk-detect-root.mjs) || exit $?
cd "$KK_REPO_ROOT" || exit $?
pwd

1. 从实时上下文中提取候选内容

1. 加载提取提示词。 首先读取 .ai/kenkeep/.config/prompts/proposal-extract.md（仓库级覆盖文件）。如果该文件不存在，则读取随附的软件包模板 templates/prompts/proposal-extract.md（相对于已安装的 npm 软件包）。遵循提示词中的提取规则——不要在此处嵌入副本。

2. 构建实时转录替代文本。 根据本次会话中可见的对话（你仍能看到的用户和 Agent 发言）构建带角色标记的转录。使用文本前，删除所有 <kk-private>…</kk-private> 区段。

3. 替换占位符。 将已加载提示词中的 [TRANSCRIPT PLACEHOLDER, substituted at runtime] 替换为实时转录替代文本。如果提示词中没有该占位符，则报告提取失败并停止，不执行任何写入。

4. 原样应用提示词。 生成符合严格 ProposalOutputSchema 的 JSON 对象：{ "practice": [...], "map": [...] }，其中每个条目只能包含 { type, tags, title, description, body, kk_confidence }。不要输出旧版的 supports_existing_node / contradicts_existing_node 字段。

5. 处置门控。 如果本次会话仅涉及元问题、处于探索阶段、已放弃、无关，或没有持久的经验要点，则报告未发现持久知识并停止——不暂存、不整理、不写入节点。这属于成功，而非失败。

2. 暂存实时候选内容

提取出至少一个候选项时：

1. 解析会话 ID。 如有可用的测试环境实时 UUID-v4 会话 ID，优先使用。如果无法获取有效的 UUID-v4，则使用 --generate-session-id，并向用户报告幂等性降级（后续捕获可能与此日志不匹配）。

2. 将经过验证的 JSON 传入暂存原语：

   echo '<json>' | npx kenkeep@latest session-log stage-live --session-id <uuid-v4>
   # or, when no live id is available:
   echo '<json>' | npx kenkeep@latest session-log stage-live --generate-session-id
   

3. 捕获 stdout 输出的单行 JSON 摘要（path、session_id、idempotency）。如果 idempotency 为 degraded，请明确报告幂等性已降级。

暂存的日志位于 .ai/kenkeep/_sessions/ 下，包含 proposal_status: done 和 captured_by: manual。

3. 起草整理操作

你是这个单个暂存会话的整理者。阅读暂存日志中的候选内容，并为每个候选项起草一个 CuratorAction，遵循与 /kk-curate 第 2 步相同的规则（操作分类、candidate_origin 格式为 <session_id>:<practice|map>:<index>、关联并安置、考虑整个知识树的去重）。不要另行制定操作规则——遵循 /kk-curate 的整理语义。

生成一次运行 ID：

RUN_ID=$(uuidgen 2>/dev/null || date -u +"curate-%Y%m%dT%H%M%SZ")
PROPOSALS=$(mktemp -t kk-session-extract-proposals.XXXXXX.json)
SURVIVORS=$(mktemp -t kk-session-extract-survivors.XXXXXX.json)

将累积的操作数组（顶层为 JSON 数组）写入 $PROPOSALS，然后在去重前验证：npx --yes kenkeep@latest validate curator-output "$PROPOSALS"。如果退出码非零，请读取路径所指向的错误，修复有问题的操作，然后重新验证，直到验证通过。（如需查看确切结构，可运行 kk schema curator-output 打印 JSON Schema。）

4. 通过限定范围的原语去重并打上标记

仅针对暂存会话调用一次 curate-dedup：

STAGED_SESSION_ID=<session_id from stage-live output>
npx --yes kenkeep@latest curate-dedup \
  --input "$PROPOSALS" --output "$SURVIVORS" --run-id "$RUN_ID" \
  --session-id "$STAGED_SESSION_ID"

这只会为暂存的实时日志打上标记。_sessions/ 中无关的 proposal_status: done 日志仍可留待之后运行 /kk-curate 时处理。

记录 stdout JSON 摘要（kept、conflicts、stamped、runId），并报告给用户。

5. 通过 curate-persist 持久化保留的操作

严格遵循 /kk-curate 的第 5 步：通过 curate-persist 持久化 $SURVIVORS，在摘要中指出每项操作的失败情况，保留成功写入的内容，并继续重建。

6. 重建索引

npx --yes kenkeep@latest index rebuild

6b. 重新平衡（最终阶段）

严格遵循 /kk-curate 的第 6b 步：运行 rebalance trigger；如果 actions 为空则跳过，否则仅针对指定分支提出操作，并通过 rebalance move 应用操作。

7. 报告并解决冲突

遵循 /kk-curate 的第 7 步：报告关键数字、每个已写入叶节点的放置位置、结构重新平衡摘要，然后检查 .ai/kenkeep/conflicts/ 下待处理的冲突（如果有新建冲突）。

8. 交接

告知用户检查 .ai/kenkeep/nodes/ 下发生变更的节点，并通过 git commit 接受变更。暂存的会话日志现已标记为已处理；之后针对相同 session_id 运行捕获钩子时，会保留 curator_processed_at / curator_run_id。

约束

• 每次运行仅调用一次 curate-dedup，并且始终为暂存日志指定 --session-id。
• 如果提取结果为空提案，则不执行任何写入。
• 不得放宽 UUID-v4 验证；使用 --generate-session-id 时，必须报告幂等性降级。
• 不得从此技能启动无头测试框架或后台工作进程。