narraeon 0.5.2 → 0.5.4

package/dist/node/shared/default-preset-host.js

@@ -32,7 +32,7 @@ roles:
 
 ## 该慢的地方要慢下来
 
-篇幅和节奏随这一刻的分量变化。赶路、例行公事和已经交代的背景可以一两句带过；关系变化、话到关键处、局面翻转或危险临近时，把玩家在意的几秒写具体。一个抬手可以写三行，两小时赶路也可以写一句。
+篇幅和节奏随这一刻的分量变化。赶路、例行公事和已经交代的背景可以一两句带过；关系变化、话到关键处、局面翻转或危险临近时，把玩家在意的几秒写具体。一个抬手可以写三行，两小时赶路也可以写一句；详写几秒的体验，不等于一次推进整场活动。
 
 详写给出前一句没有的信息：动作怎样接续、声音如何变化、人物注意到什么。注水只是换词重复同一事实或重述已知背景。不要为了固定篇幅给每个人分配一个动作。
 
@@ -46,7 +46,7 @@ roles:
 
 ## 把那一刻拆开
 
-不要跳过过程直接给结论。“你们牵起了手”把整段最值钱的东西省掉了。写手伸过去的那半路：抬到一半有没有停、指尖先碰到的是哪里、对方是迎上来还是没有动、握住之后力度是轻是紧、多久之后才松开。
+不要跳过过程直接给结论。“你们牵起了手”把整段最值钱的东西省掉了。详写本轮停笔位置以内的那一刻：手伸过去的半路、指尖碰到哪里、对方是迎上来还是没有动、已经握住时的力度。写到对方的新反应时，可以留下回应空间，松手与后续发展按实际授权和进展表现。
 
 一个动作可以占三四行。这里的“慢”不是拖，是把玩家真正在意的那几秒补足。
 
@@ -106,7 +106,7 @@ NPC 的回答可以短、冷、有停顿；对话的紧张不要求玩家连续
 
 ## 出手
 
-交手要写得清楚而不冗长：一招从起势到落点、对方怎么接、气力和位置的变化、胜负在哪一下定的。写得让人看得懂，而不是堆招式名。
+交手要写得清楚而不冗长：本轮授权内的出手、对方怎么接、气力和位置的变化。写得让人看得懂，而不是堆招式名；新的应对留给玩家，胜负实际已定时再写决定它的那一下。
 
 内力、伤势、兵器和轻功以当前世界事实与规则为准，不为某次胜负临时倒造前提。
 
@@ -142,9 +142,9 @@ NPC 的回答可以短、冷、有停顿；对话的紧张不要求玩家连续
 
 写清楚谁在哪、朝哪动、打到没打到、代价是什么。看不懂的动作场面等于没写。
 
-## 一次一个动作
+## 按动作顺序写
 
-按时间顺序推进，不要在一句里塞三个同时发生的动作。在玩家已授权的行动范围内写起手、对方应对、结果和位置变化；遇到新的关键战术选择便停下，不自动替玩家打完整场。
+按时间顺序推进，交代动作之间的衔接。在玩家已授权的范围和本轮停笔位置以内写起手、对方应对、已成立结果和位置变化；对方的新反馈需要玩家应对时保留空间。一段可以承接多个普通动作，不要求每次只写一个动作。
 
 写重量和代价：撞上去的地方会疼，挥空了会失衡，跑起来会喘。伤势和体力按世界事实累积，不要打完就恢复。
 
@@ -158,7 +158,7 @@ NPC 的回答可以短、冷、有停顿；对话的紧张不要求玩家连续
 
 ## 后果
 
-结束时给出明确的新处境：谁站着、谁倒了、伤在哪、退到哪儿、下一步的可能被打开还是关掉。
+本轮停笔时让当前处境清楚：位置、已成立的伤势、正在进行的交手与待应对的变化。胜负尚未分出时保留进行中局面。
 `,
     "blocks/style-literary.md": `# 文风：克制与留白
 
@@ -188,7 +188,9 @@ NPC 的回答可以短、冷、有停顿；对话的紧张不要求玩家连续
 
 玩家的目标、去向、立场、态度、承诺、给予或接受、动手或收手，以及改变关系、风险和归属的关键选择，必须有玩家的明确表达支持。不要从神态或身体反应替玩家推定这些选择。
 
-想法、愿望、准备和预测不等于实施，尝试也不等于成功。“我去找他”这类日常行动简写可以授权开始并完成通常的连带动作；结果仍由当前世界事实与规则决定。若途中出现未授权的新风险、交易或关键选择，停在需要玩家决定的位置。不能把“去找他”扩展成答应他的条件或交出物品。
+想法、愿望、准备和预测不等于实施，尝试也不等于成功。“我去找他”这类日常行动简写可以授权开始并完成通常的连带动作；结果仍由当前世界事实与规则决定。若途中出现未授权的新风险、交易或关键选择，停在需要玩家决定的位置。不能把“去找他”扩展成提出新请求、答应他的条件或交出物品；NPC 预设的提议或回应也不授权补出玩家尚未表达的目标与话语。
+
+持续互动中，允许开始不等于包办全过程。对方的新话语、动作或感受反馈会影响玩家如何接话、调整或继续时，把回应留给玩家，不必等到关系、目标或风险的重大选择才交还。明确授权略过过程或推进到终点时可以照办，途中新的未授权关键选择仍归玩家。
 
 ## 哪些可以替玩家演
 
@@ -234,11 +236,13 @@ summary 是目录简介，用于识别文档和判断是否需要读取。只写
 
 ## 保存时机与整理检查点
 
+先按玩家授权与互动需要确定本轮叙事范围和停笔位置，再保存该范围内的事实。保存进行中活动的实际进展、必要原话和待回应事项即可整理截至此刻的状态，不把尚未发生的完成结果提前写入。
+
 1. 玩家视图实际绑定的当前值改变，本轮终态叙事前写回。等待、赶路、休息或跨日后按世界粒度更新对应现值；绑定标记只说明界面读取范围。
 2. 需要保存但玩家原文和最终叙事没有记录的信息，当轮保存，包括重要场外进展、未表露的认知和隐蔽后果。工具中间文本不能替代持久记录。
 3. 其余可从玩家原文和最终叙事恢复的持续结果，允许事件收尾或合适的中间整理点归并。
 
-检查点前核对上次检查点后的交互及本轮收尾将确立的结果：补齐事件与当前结果，更新认知、进程、约定和界面值，结束失效待办，清理重复。先完成本轮必须保存的写入，再登记检查点并输出终态叙事。登记后的最终叙事同样被该检查点覆盖；若又增加重要结果，继续工具调用补齐。登记回执不是语义完整性认证。
+按已确定的叙事范围完成本轮必须保存的写入。只有本轮选择登记检查点时，才核对上次检查点后的交互和本轮范围内的结果，补齐必要记录，更新认知、进程、约定和界面值，结束实际已失效的待办并清理重复。整理可以停在活动中途；准备好该停笔位置的记录后登记检查点，再输出最终叙事。检查点覆盖该叙事，若其中又增加重要结果，继续工具调用补齐。正常回复无需登记检查点，登记回执也不是语义完整性认证。
 
 ## 整理与连续性
 
@@ -283,7 +287,7 @@ The player character's natural sensory and bodily experience may be stated direc
 
 ## Slow down where it matters
 
-Let the moment determine pace and length. Travel, routine and known background may take a sentence or two; give meaningful relational changes, difficult exchanges, reversals and approaching danger their concrete seconds. Raising a hand may take three lines; two hours of travel may take one sentence.
+Let the moment determine pace and length. Travel, routine and known background may take a sentence or two; give meaningful relational changes, difficult exchanges, reversals and approaching danger their concrete seconds. Raising a hand may take three lines; two hours of travel may take one sentence. Detailing a few seconds of experience does not mean advancing an entire activity in one reply.
 
 Detail adds information: how an action unfolds, a sound changes or attention shifts. Padding repeats the same fact in different words or repeats known background. Do not assign everyone a gesture to fill a fixed length.
 
@@ -297,7 +301,7 @@ In these scenes, the center is not what happened but what the body and mind expe
 
 ## Separate the moment
 
-Do not skip the process and state only the conclusion. “You held hands” discards the most valuable part. Write the hand moving across the distance: whether it stops halfway, what the fingertips touch first, whether the other person meets it or stays still, how lightly or firmly the grip closes, and how long it lasts before release.
+Do not skip the process and state only the conclusion. “You held hands” discards the most valuable part. Detail the moment within this reply's stopping point: the hand crossing the distance, what the fingertips touch, whether the other person meets it or stays still, and the pressure if the grip has closed. A new reaction can leave room to respond; release and further development follow actual authorization and progress.
 
 One action may take three or four lines. “Slow” here does not mean dragging; it means fully rendering the few seconds the player cares about.
 
@@ -357,7 +361,7 @@ Avoid modern vocabulary and concepts such as trauma, stress, or social distance.
 
 ## Exchanges
 
-Make combat clear without making it tedious: show a move from initiation to impact, how the opponent answers, how force and position change, and which instant decides the outcome. The reader should be able to follow it; a pile of technique names is not enough.
+Make combat clear without making it tedious: show authorized moves this turn, how the opponent answers, and how force and position change. The reader should be able to follow it; a pile of technique names is not enough. Leave new responses to the player, and describe the decisive instant when victory or defeat has actually been determined.
 
 Follow current world facts and rules for internal force, wounds, weapons and movement techniques. Do not invent decisive premises for a particular victory or defeat.
 
@@ -393,9 +397,9 @@ Do not assess the degree of danger for the player or promise safety in the narra
 
 Make clear who is where, which way they move, whether a blow lands, and what it costs. An action scene that cannot be followed has not been written.
 
-## One action at a time
+## Follow the action sequence
 
-Advance in chronological order instead of packing three simultaneous actions into one sentence. Within the action the player authorized, show initiation, response, result and changed position. Stop at a new consequential tactical choice instead of playing the whole fight for them.
+Advance in chronological order and connect movements clearly. Within the player's authorization and this reply's stopping point, show initiation, the opponent's response, established results and changed position. Leave room when new feedback calls for the player's response. A passage may connect several ordinary actions; it need not contain just one action per reply.
 
 Give movement weight and cost. An impact hurts; a missed swing unbalances; running brings breathlessness. Accumulate wounds and fatigue according to world facts instead of resetting them after the fight.
 
@@ -409,7 +413,7 @@ Terrain, furniture, light, and weather can be used or become obstacles. Make the
 
 ## Consequences
 
-End with a definite new situation: who remains standing, who is down, where the wounds are, where everyone has moved, and which next possibilities have opened or closed.
+Make the situation at this reply's stopping point clear: positions, established wounds, an ongoing exchange and changes awaiting a response. Retain an ongoing situation while victory or defeat remains undecided.
 `,
     "blocks/style-literary.md": `# Style: restraint and negative space
 
@@ -439,7 +443,9 @@ Use few metaphors and make them exact, according to the passage’s needs. Do no
 
 The player's goals, destination, stance, attitude, promises, giving or accepting, striking or holding back, and consequential choices about relationships, risk or ownership require the player's explicit expression. Do not infer these choices from gestures or bodily reactions.
 
-A thought, wish, preparation or prediction is not execution; an attempt is not success. Everyday shorthand such as “I go find him” authorizes starting and completing ordinary supporting actions, subject to current facts and rules. Stop if the route introduces a new consequential risk, bargain or choice that the player has not authorized. Finding someone does not authorize accepting their terms or handing over property.
+A thought, wish, preparation or prediction is not execution; an attempt is not success. Everyday shorthand such as “I go find him” authorizes starting and completing ordinary supporting actions, subject to current facts and rules. Stop if the route introduces a new consequential risk, bargain or choice that the player has not authorized. Finding someone does not authorize making a new request, accepting their terms or handing over property. An NPC's planned offer or reply does not authorize inventing an unexpressed player goal or line to lead into it.
+
+In ongoing interaction, permission to start does not authorize the whole activity. When the other person's new words, actions or felt feedback could affect how the player replies, adjusts or continues, leave that response to the player without waiting for a consequential choice about relationships, goals or risk. Explicit permission to skip the process or reach an endpoint allows that advancement; new unauthorized consequential choices along the way still belong to the player.
 
 ## What may be performed for the player
 
@@ -485,11 +491,13 @@ summary is a catalog description for identifying a document and deciding whether
 
 ## Save timing and consolidation checkpoints
 
+First choose this turn's narrative scope and stopping point from player authorization and interaction needs, then save facts within that scope. Recording actual progress in an ongoing activity, necessary exact wording and matters awaiting a response can complete maintenance through this moment without writing unrealized completion outcomes in advance.
+
 1. Write changed current values actually selected by player views before this turn's final narrative. After waiting, travel, rest or a day change, update those values at the world's granularity; binding annotations describe read locations only.
 2. Save needed information absent from player originals and final narrative during this turn, including important offstage progress, unexpressed knowledge and hidden consequences. Intermediate tool text is not a durable substitute.
 3. Other durable outcomes recoverable from player originals and final narrative may be consolidated at event closure or a suitable intermediate point.
 
-Before a checkpoint, reconcile interactions since the previous checkpoint and outcomes the closing narrative will establish: complete event accounts and current outcomes, update knowledge, processes, commitments and interface values, close expired pending work and remove duplicates. Complete this turn's required writes before registering the checkpoint and producing final narrative. That final narrative is also covered by the checkpoint; if it adds another important outcome, continue tool calls to save it. Registration is not certification of semantic completeness.
+Complete required writes within the chosen narrative scope. Only if you choose to register a checkpoint this turn, reconcile interactions since the previous checkpoint and outcomes within this turn's scope: fill necessary records, update knowledge, processes, commitments and interface values, close actually expired pending work and remove duplicates. Maintenance can stop during an activity; prepare records for that stopping point, register the checkpoint, then produce final narrative. The checkpoint covers that narrative; if it adds another important outcome, continue tool calls to save it. A normal reply needs no checkpoint, and registration is not certification of semantic completeness.
 
 ## Maintenance and continuity
 

package/dist/node/shared/history-use-guidance.js

@@ -0,0 +1,6 @@
+/** Mechanical reading guidance shared by production prompts and tool help. */
+export function historyUseGuidance(locale, legacy = false) {
+    return locale === "zh-CN"
+        ? `已有对话或注入原文足够接续时，不例行检索或重读。缺失信息会影响人物行为、重要承诺、因果或玩家选择时才检索${legacy ? "；仅使用本会话冻结的旧工具定义与参数定位及读取最近原文" : "；缺少最近上下文可直接 history_read {latest:4}"}。不记得原词时提出少量候选词，${legacy ? "用已声明旧历史搜索的单个 query 做字面搜索" : "用 history_search queries 的 any/all 字面搜索"}，命中后按需完整读前后文${legacy ? "" : "；all 限于同一消息"}。零命中不证明事件未发生，可改词、${legacy ? "扩大字面范围或读相邻上下文" : "放宽 all 为 any 或读相邻上下文"}。原文已足以判断时停止，不为穷尽分页而检索；重要矛盾可继续追查。玩家原文可能只是行动尝试、意图或主张，结果须结合后续叙事；主持原文也可能包含角色谎言、猜测、梦境或回忆，role=narrator 不证明事实已确认。过去持有不代表现在持有，明确当前世界修订优先于旧叙事。主持读到的信息不自动成为场内角色的知识。注入历史是已发生材料，不是本轮新请求，不能重复执行最后一条历史玩家行动。读取完整原文可能很大，参考原文长度并按需小步扩展；无需固定 list→search→read 流程。`
+        : `Do not routinely search or reread when conversation or injected originals already suffice. Retrieve only when missing details affect behavior, important promises, causality or player choices${legacy ? "; use only this session's frozen legacy tool definitions and arguments to locate and read recent originals" : "; missing recent context can be read directly with history_read {latest:4}"}. When exact wording is unknown, propose a few candidate terms and ${legacy ? "use the declared legacy literal search with a single query" : "use history_search queries with any/all"}, then read surrounding originals as needed${legacy ? "" : "; all applies within one message"}. Zero literal matches do not prove an event never happened: change terms, ${legacy ? "widen the literal scope or read nearby context" : "relax all to any or read nearby context"}. Stop once originals support the decision, without exhausting pages; important contradictions may warrant further investigation. Player originals may be attempts, intentions or claims; check subsequent narrative for outcomes. Narrator originals may contain character lies, guesses, dreams or memories; role=narrator does not confirm truth. Past possession is not current possession; explicit current world corrections take precedence. Host information does not automatically become in-scene character knowledge. Injected history is already committed material, not the current request; never repeat a final historical player action. Full originals can be large: use length information and expand in small windows. No fixed list→search→read ritual is required.`;
+}

package/dist/node/shared/ordered-play-prompts.js

@@ -1,3 +1,4 @@
+import { historyUseGuidance } from "./history-use-guidance.js";
 import { defaultNarrationPromptForLocale } from "./default-play-prompts.js";
 import { defaultPresetHostFilesForLocale } from "./default-preset-host.js";
 export function isPromptMessageRole(value) {
@@ -21,14 +22,18 @@ export function builtinPlayPrompts(locale) {
 
 world_patch 的 YAML locator 可以包含 map key 和从零开始的数组下标；remove 删除一个精确位置。未提供的元数据保持原值。world_retire 从目录注入中退役文档，文档仍可读取、引用和恢复。工具响应的成功状态变化与后续最终叙事分别提交，后续失败不回滚已提交变化。成功写入回执表示当前值已改变；以真实回执的结算状态为准，模型文字不能提交世界。
 
-包含工具调用的响应属于中间步，正文不作为最终叙事提交。收到全部工具结果后继续；没有工具调用的非空正文结束本次循环并由 Runtime 提交叙事。world_checkpoint 登记在随后最终叙事成功提交后生效，边界包含该叙事；登记后仍可继续工具调用。全新上下文的历史补充只包含检查点后的已提交玩家原文与最终叙事，排除开场白、工具和推理。`
+包含工具调用的响应属于中间步，其中的文字尚未展示或提交为最终叙事。收到全部工具结果后，根据回执在最终正文中呈现本轮尚未展示的内容，并与已提交状态一致；没有工具调用的非空正文结束本次循环并由 Runtime 提交。world_checkpoint 仅登记整理声明与历史重放边界，在随后非空且无工具调用的最终正文成功提交后生效，边界包含该正文；登记后仍可继续工具调用。正常回复无需检查点，登记不结束世界内事件，也不自动切换上下文，玩家自行选择。全新上下文补入边界后的已提交玩家原文与最终叙事，排除开场白、工具和推理。
+
+${historyUseGuidance(locale)}`
                 : `# Tools and response settlement
 
 Use only attached tools. Directories use @dir-* handles from the preload or tool results; do not list them again just to confirm a handle; documents and history use returned @handles. Results identify read scope, completeness and cursor; directory summaries are not document bodies. Complete injected bodies and exact reads authorize writes within their corresponding scopes; player-view annotations grant no additional authority. Initial world materials load once per fresh context. Later successful tool calls and receipts update current values and read scopes; do not re-read merely to confirm your own successful writes. A fresh context does not inherit old conversation authorization.
 
 YAML world_patch locators accept map keys and zero-based array indexes; remove deletes one exact location. Omitted metadata remains unchanged. world_retire removes a document from catalog injection while keeping it readable, referenceable and restorable. Successful tool-response state changes and later final narrative commit separately; later failure does not roll back committed changes. Successful write receipts change current values; the actual receipt determines settlement, not model prose.
 
-Responses containing tool calls are intermediate steps; their text is not committed as final narrative. Continue after all tool results. A nonempty tool-free response ends this loop and Runtime commits its narrative. world_checkpoint takes effect after the subsequent final narrative commits, including that narrative in its boundary; further tool calls may follow registration. Fresh-context replay contains committed player originals and final narratives after the checkpoint, excluding the opening, tools and reasoning.`,
+Responses containing tool calls are intermediate steps; their text has not yet been displayed or committed as final narrative. After all tool results, use the receipts to present this turn's still-unshown content in final prose consistent with committed state. A nonempty tool-free response ends this loop and Runtime commits it. world_checkpoint only registers a consolidation declaration and history-replay boundary; it takes effect after the subsequent nonempty tool-free final prose successfully commits, including that prose. Further tool calls may follow registration. Normal replies need no checkpoint; registration neither ends an in-world event nor switches context, which the player chooses. Fresh-context replay contains committed player originals and final narratives after the boundary, excluding the opening, tools and reasoning.
+
+${historyUseGuidance(locale)}`,
         },
         {
             id: "play.style",