dominds 1.16.5 → 1.16.7

package/dist/docs/team_mgmt-toolset.md

@@ -55,6 +55,20 @@ Rationale:
 - The framework source tree should not be the “primary” place the team config format is explained.
   Each rtws may have different policies and defaults.
 
+### Scope Boundary of This Document (important)
+
+- This document is responsible for stable design intent, conceptual boundaries, responsibility split,
+  and why the system is designed this way.
+- This document should **not** become a home for overly detailed runtime specifications such as exact
+  injection order, current fallback rules, full topic inventories, dynamic enumeration results,
+  field-by-field rendering details, or authoring rules that are expected to evolve with the implementation.
+- For “what the runtime does today”, use:
+  - `man({ "toolsetId": "team_mgmt" })`
+  - the corresponding implementation and runtime validators
+- If the design document and the runtime handbook disagree about current behavior, the runtime handbook
+  wins and the design doc should be corrected afterward. Readers should not treat this design doc as a
+  runtime specification manual.
+
 ## Current Problem Statement
 
 In typical deployments we deny direct `.minds/` access via the general-purpose rtws tools:
@@ -166,7 +180,10 @@ reading source code.
 - `man({ "toolsetId": "team_mgmt", "topics": ["team"] })` → how to manage `.minds/team.yaml` (+ templates).
 - `man({ "toolsetId": "team_mgmt", "topics": ["team", "member-properties"] })` → list supported member fields and meanings.
 - `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` → how to manage `.minds/team/<id>/*.md` (persona/knowledge/lessons).
+- `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → how to manage `.minds/skills/*` (injection point, tone, heading levels, migration boundaries).
 - `man({ "toolsetId": "team_mgmt", "topics": ["priming"] })` → how to manage startup scripts under `.minds/priming/*`.
+- `man({ "toolsetId": "team_mgmt", "topics": ["env"] })` → how to manage `.minds/env.*.md` (runtime-environment injection point, tone, heading levels).
+- `man({ "toolsetId": "team_mgmt", "topics": ["toolsets"] })` → inspect the actually visible toolsets in the current installation/rtws and common grant patterns.
 - `man({ "toolsetId": "team_mgmt", "topics": ["permissions"] })` → how `read_dirs`/`write_dirs` and deny-lists work.
 - `man({ "toolsetId": "team_mgmt", "topics": ["troubleshooting"] })` → common failure modes and how to recover.
 
@@ -200,6 +217,20 @@ must cover (at minimum) the information that used to live there:
   - Explain tool exposure controls (whitelist/blacklist) and naming transforms (prefix/suffix).
   - Explain secret/env wiring patterns and operational troubleshooting (Problems + logs, restart,
     hot reload semantics).
+- `!skills`:
+  - Explain `.minds/skills/*` as reusable team skill assets.
+  - Explain the boundary that a skill is prompt/guidance content, not a permission system.
+  - Explain when content should remain a skill versus being elevated into an app / toolset /
+    teammate contract.
+- `!env`:
+  - Explain `.minds/env.*.md` as the place for current-rtws runtime-environment orientation, not
+    persona definition or a dump of repo-wide policy.
+  - Explain its boundary relative to `persona/knowledge/lessons`, skills, and priming.
+- `!toolsets`:
+  - Explain that the visible toolsets include built-in toolsets, toolsets exposed by installed
+    apps, and MCP toolsets dynamically registered from `.minds/mcp.yaml`.
+  - Explain why this topic must be rendered from runtime state rather than maintained as a static
+    list in the design docs.
 
 ## Dynamic Loading from the Dominds Installation (Runtime Resources)
 
@@ -220,10 +251,29 @@ Recommended sources by topic:
     `dominds/main/llm/defaults.yaml` (via `__dirname` resolution in the backend build output).
   - Prefer reusing `LlmConfig.load()` and formatting its merged view, or adding a helper that returns
     both “defaults-only” and “merged” provider maps.
-- `man({ "toolsetId": "team_mgmt", "topics": ["toolsets"] })` (if added)
+- `man({ "toolsetId": "team_mgmt", "topics": ["toolsets"] })`
   - Load from the in-memory registries at runtime (`listToolsets()` / `listTools()` in
     `dominds/main/tools/registry.ts`), rather than maintaining a separate list.
 
+### Why `toolsets` Must Stay a Dynamic Topic
+
+- `toolsets` is not a stable inventory that should be hardcoded in a design document.
+- The visible toolsets are jointly determined by:
+  - framework built-ins
+  - toolsets exposed by the currently installed Dominds apps
+  - MCP toolsets mapped at runtime from `.minds/mcp.yaml` `servers.<serverId>`
+- The MCP portion is inherently **dynamic**: teams can add/remove servers, rename exposure, and
+  constrain tool exposure per rtws, so the resulting toolset set changes with the live installation
+  and workspace state.
+- This is intentional. The design binds capability discovery to the actual runtime environment
+  instead of to a static document that will drift:
+  - it avoids maintaining a doomed-to-drift toolset list in the design docs
+  - it avoids misleading readers into treating MCP-derived toolsets as framework built-ins
+  - it ensures the team manager sees the capabilities that are truly available in this installation
+    and this rtws right now
+- Therefore the design docs should explain the mechanism and rationale only; the current toolset list
+  belongs to runtime `man(...topics:["toolsets"])`.
+
 Keep these as **static/manual text** (not dynamically loaded):
 
 - High-level explanations, best practices, and “why” sections.
@@ -240,13 +290,17 @@ Startup script directories:
 Core principles:
 
 - Startup scripts are mapped into real dialog history; they are not read-only logs.
+- Their runtime semantics are not “extra system prompt text”, but “restore reminders first, then replay records into dialog history where possible”.
+- Therefore tone must follow the chosen record type: write `human_text_record` as what a user/requester says to the agent; write `agent_words_record` as what the agent has already said; use `agent_thought_record` only sparingly for internal reasoning traces.
+- Some technical record types such as `ui_only_markdown_record` are persisted but do not become model-facing chat messages, so they should not be your main steering layer.
+- The outer file structure should be “top-level frontmatter + repeated `### record <type>` blocks”; do not wrap the file in decorative `# Startup Script` / `## History` headings.
 - Team managers should treat them as editable startup playbooks.
 - Freely add/edit assistant or user messages, and fully rewrite scripts when workflows evolve.
 
 Recommended format:
 
 - Frontmatter (optional, recommended): metadata such as `title` and `applicableMemberIds`.
-- Message blocks (required): `### user` / `### assistant`, optionally fenced markdown blocks.
+- Record blocks (required): `### record <type>` with the actual content inside the corresponding markdown/json block.
 
 Maintenance guidance:
 
@@ -488,14 +542,22 @@ Best practices:
 
 ## Managing `.minds/team/<member>/*.md` (agent minds)
 
-The runtime reads these on every dialog start:
+At dialog start, the runtime reads that member’s `persona.*.md` / `knowledge.*.md` / `lessons.*.md`
+assets.
 
-- `.minds/team/<id>/persona.md`
-- `.minds/team/<id>/knowledge.md`
-- `.minds/team/<id>/lessons.md`
+- For exact language-file selection, fallback rules, injection order, and other current authoring
+  details, use `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })`.
 
 See `dominds/main/minds/load.ts` (`readAgentMind()`).
 
+Authoring rule (important):
+
+- `persona.*.md` is spliced into that member's `role=system` prompt, so it should normally be written directly to the agent itself.
+- In practice, prefer second-person "you" when defining responsibilities, boundaries, working style, and delivery expectations.
+- Do not write `persona.*.md` as a third-person biography or as operator-facing documentation for a human/team manager.
+- `knowledge.*.md` / `lessons.*.md` also end up in the member's system prompt, specifically under `## Knowledge` / `## Lessons`. `knowledge` is better for stable facts, indexes, conventions, and decision cues; `lessons` is better for reusable heuristics such as “if X happens, do Y, avoid Z”. Both should still be written to help that member act, not to narrate the member from the outside.
+- Heading levels should follow the system-prompt wrapper too: the outer template already provides `## Persona` / `## Knowledge` / `## Lessons`, so bodies should usually start at `###` or plain bullets instead of repeating `#` / `##` or restating the wrapper title.
+
 Suggested structure:
 
 ```
@@ -513,6 +575,33 @@ Suggested structure:
       lessons.md
 ```
 
+## Managing `.minds/skills/*` (skill assets)
+
+Design-level positioning:
+
+- `.minds/skills/*` stores reusable team skill / operating-guidance assets.
+- Its job is to capture “when to use this, how to do it, and where the boundary is”, not to grant
+  permissions.
+- If a skill depends on scripts, privileged tools, MCP, external binaries, or reusable execution
+  capability, the design should usually elevate it into a Dominds app / toolset / teammate contract
+  rather than stopping at Markdown alone.
+- This design doc intentionally limits itself to boundary and migration guidance. For current file
+  naming, injection semantics, heading levels, and language-file rules, use
+  `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })`.
+
+## Managing `.minds/env.*.md` (runtime-environment notes)
+
+Design-level positioning:
+
+- `.minds/env.*.md` exists to describe stable facts about the current rtws runtime environment so
+  members can orient themselves quickly.
+- It should not take on the role of persona definition, skill tutorial, giant operating manual, or
+  repo-wide policy dump.
+- Those responsibilities belong, respectively, in `persona/knowledge/lessons`, skills, priming, or
+  the repo’s own policy files.
+- This design doc only defines that boundary. For the current injection position, fallback behavior,
+  and authoring guidance, use `man({ "toolsetId": "team_mgmt", "topics": ["env"] })`.
+
 ## Bootstrap Policy: Shadow bootstrap members
 
 Preferred behavior for initial bootstrap:

package/dist/docs/team_mgmt-toolset.zh.md

@@ -42,6 +42,15 @@
 - 该手册与工具行为版本化，因此保持准确
 - 框架源代码树不应是团队配置格式被解释的"主要"地方。每个 rtws 可能具有不同的策略和默认值
 
+### 本文档的粒度边界（重要）
+
+- 本文档只负责说明稳定的设计目标、概念边界、职责划分，以及为什么这样设计。
+- 本文档**不应**承载过细的运行时规格，例如精确的注入顺序、当前回退规则、完整 topic 列表、动态枚举结果、逐字段渲染细节、或会随实现演进而频繁变化的 authoring 细则。
+- 这类“当前实现到底怎么做”的信息，应统一以下列入口为准：
+  - `man({ "toolsetId": "team_mgmt" })`
+  - 对应实现代码与运行时校验
+- 如果设计文档与运行时手册在“当前行为”上发生冲突，应默认以运行时手册为准，并回头修正文档，而不是让读者继续把设计文档当成运行时规格书。
+
 ## 当前问题陈述
 
 在典型部署中，我们通过通用 rtws 文件工具拒绝直接的 `.minds/` 访问：
@@ -137,7 +146,10 @@
 - `man({ "toolsetId": "team_mgmt", "topics": ["team"] })` → 如何管理 `.minds/team.yaml`（+ 模板）
 - `man({ "toolsetId": "team_mgmt", "topics": ["team", "member-properties"] })` → 列出支持的成员字段及其含义
 - `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` → 如何管理 `.minds/team/<id>/*.md`（persona/knowledge/lessons）
+- `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → 如何管理 `.minds/skills/*`（skills 的注入位置、口吻、标题层级、迁移边界）
 - `man({ "toolsetId": "team_mgmt", "topics": ["priming"] })` → 如何管理 `.minds/priming/*` 启动脚本（格式、维护、复用）
+- `man({ "toolsetId": "team_mgmt", "topics": ["env"] })` → 如何管理 `.minds/env.*.md`（运行环境提示的注入位置、口吻、标题层级）
+- `man({ "toolsetId": "team_mgmt", "topics": ["toolsets"] })` → 查看当前安装/rtws 下实际可见的 toolsets 及常见授权模式
 - `man({ "toolsetId": "team_mgmt", "topics": ["permissions"] })` → `read_dirs`/`write_dirs` 和拒绝列表如何工作
 - `man({ "toolsetId": "team_mgmt", "topics": ["troubleshooting"] })` → 常见故障模式及如何恢复
 
@@ -163,6 +175,16 @@
   - 解释 MCP 服务器如何映射到工具集（`<serverId>`）以及如何通过 `.minds/team.yaml` 授予这些工具集
   - 解释工具暴露控制（白名单/黑名单）和命名转换（前缀/后缀）
   - 解释密钥/env 接线模式和问题排查（问题 + 日志、重启、热重载语义）
+- `!skills`：
+  - 解释 `.minds/skills/*` 属于可复用的团队技能资产
+  - 解释 skill 的职责边界：它是提示/指导资产，不是权限系统
+  - 解释何时应继续保留为 skill，何时应升级为 app / toolset / teammates contract
+- `!env`：
+  - 解释 `.minds/env.*.md` 用于描述当前 rtws 的运行环境，而不是定义人格或复制仓库总规范
+  - 解释它与 `persona/knowledge/lessons`、skills、priming 的分工边界
+- `!toolsets`：
+  - 解释当前可见 toolsets 包含内建 toolsets、已安装 apps 暴露的 toolsets、以及由 `.minds/mcp.yaml` 动态注册的 MCP toolsets
+  - 解释为什么该主题必须以运行时动态视图为准，而不是在设计文档里维护一份静态名单
 
 ## 从 Dominds 安装动态加载（运行时资源）
 
@@ -179,9 +201,23 @@
 - `man({ "toolsetId": "team_mgmt", "topics": ["llm", "builtin-defaults"] })`
   - 从运行时用于默认值的同一安装资源加载：`dominds/main/llm/defaults.yaml`（通过后端构建输出中的 `__dirname` 解析）
   - 优先重用 `LlmConfig.load()` 并格式化其合并视图，或添加一个返回"仅默认值"和"合并"提供商映射的助手
-- `man({ "toolsetId": "team_mgmt", "topics": ["toolsets"] })`（如果添加）
+- `man({ "toolsetId": "team_mgmt", "topics": ["toolsets"] })`
   - 在运行时从内存中注册表加载（`dominds/main/tools/registry.ts` 中的 `listToolsets()` / `listTools()`），而不是维护单独的列表
 
+### 为什么 `toolsets` 必须是动态主题
+
+- `toolsets` 不是一份稳定、可写死在设计文档里的清单。
+- 当前可见的 toolsets 由三部分共同决定：
+  - 框架内建 toolsets
+  - 当前安装的 Dominds apps 所暴露的 toolsets
+  - `.minds/mcp.yaml` 中 `servers.<serverId>` 在运行时映射出来的 MCP toolsets
+- 其中 MCP 部分天然是**动态的**：团队可以按 rtws 需要增删 server、调整命名、控制工具暴露；因此 toolset 集合会随当前安装状态与当前 rtws 配置而变化。
+- 这样设计的原因，是把“能力发现”绑定到当前实际运行环境，而不是绑定到一份很快过时的静态文档：
+  - 避免设计文档维护一份注定漂移的 toolset 名单
+  - 避免读者误以为某个 MCP toolset 是框架内建常量
+  - 让团队管理者面对的始终是“此刻这个安装与这个 rtws 真实可用的能力”
+- 因此，设计文档只需要解释机制与原因；“当前有哪些 toolsets”应由运行时 `man(...topics:[\"toolsets\"])` 动态呈现。
+
 将这些保持为**静态/手册文本**（而非动态加载）：
 
 - 高级解释、最佳实践和"为什么"部分
@@ -197,13 +233,17 @@
 核心原则：
 
 - 启动脚本会映射为真实对话历史；它不是只读日志，而是可编辑的启动引导剧本。
+- 其运行时语义不是 system prompt，而是“创建对话时先恢复 reminders，再把 records 尽可能回放成对话历史消息”。
+- 因此内容口吻必须跟着 record 类型走：`human_text_record` 写成用户/诉请者对智能体说的话；`agent_words_record` 写成智能体已经说出口的话；`agent_thought_record` 仅适合非常克制地承载内部推理痕迹。
+- `ui_only_markdown_record` 等部分技术 record 不会变成喂给模型的 chat message，因此不能拿它们充当主要行为引导。
+- 外层结构应是“顶层 frontmatter + 多个 `### record <type>` 块”；不要再包一层 `# 启动脚本` / `## 历史` 这类装饰标题。
 - 团队管理者应鼓励按业务场景维护脚本，并可直接增删改 assistant/user 消息内容。
 - 允许完全重写脚本以匹配新的协作模式、质量标准和语言风格。
 
 推荐格式：
 
 - frontmatter（可选但推荐）：`title`、`applicableMemberIds` 等元数据。
-- 消息块（必填）：使用 `### user` / `### assistant`，支持 fenced markdown 块。
+- record 块（必填）：使用 `### record <type>`；具体内容放在对应的 markdown/json block 中。
 
 维护建议：
 
@@ -421,14 +461,20 @@ members:
 
 ## 管理 `.minds/team/<member>/*.md`（智能体心智）
 
-运行时在每次对话开始时读取这些：
+运行时在每次对话开始时会读取该成员的 `persona.*.md` / `knowledge.*.md` / `lessons.*.md` 资产。
 
-- `.minds/team/<id>/persona.md`
-- `.minds/team/<id>/knowledge.md`
-- `.minds/team/<id>/lessons.md`
+- 具体语言文件选择、回退规则、注入顺序与其它 authoring 细则，请以 `man({ "toolsetId": "team_mgmt", "topics": ["minds"] })` 为准。
 
 见 `dominds/main/minds/load.ts`（`readAgentMind()`）。
 
+写法约束（重要）：
+
+- `persona.*.md` 会被拼进该成员的 `role=system` 提示，因此默认应该直接写给“这个成员智能体本人”。
+- 也就是说，`persona.*.md` 应优先使用第二人称“你”来规定职责边界、工作方式与交付标准。
+- 不要把 `persona.*.md` 写成第三人称人物简介，不要把它当成给团队管理员/人类读者的说明书，也不要使用“祂”这类旁白口吻。
+- `knowledge.*.md` / `lessons.*.md` 也同样会进入该成员的系统提示，分别落在 `## 知识` / `## 经验`。`knowledge` 更适合稳定事实、索引、约定、判断依据；`lessons` 更适合复用型经验规则（例如“遇到 X 信号先做 Y，不要做 Z”）。两者都应以“帮助该成员当下工作”为目标，而不是面向旁观者写注释。
+- 标题层级也要按 system prompt 模板来写：系统外层已经自动提供 `## 角色设定` / `## 知识` / `## 经验`，所以正文通常应从 `###` 或普通 bullet 开始，不要再写 `#` / `##`，也不要把文件名或这些章节名重复当标题。
+
 建议的结构：
 
 ```
@@ -446,6 +492,24 @@ members:
       lessons.md
 ```
 
+## 管理 `.minds/skills/*`（技能资产）
+
+设计层面的定位：
+
+- `.minds/skills/*` 用来承载可复用的团队技能/操作指导资产。
+- 它的重点是“什么时候用、怎么做、边界是什么”，而不是授予权限。
+- 如果某个 skill 需要脚本、专有工具、MCP、外部二进制、或稳定复用的执行能力，那么设计上通常更适合上升为 Dominds app / toolset / teammates contract，而不应只停留在 markdown 文案。
+- 设计文档在这里仅说明边界与迁移方向；具体文件命名、注入位置、标题层级、语言文件选择等，以运行时 `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` 为准。
+
+## 管理 `.minds/env.*.md`（运行环境说明）
+
+设计层面的定位：
+
+- `.minds/env.*.md` 用来描述“当前 rtws 运行环境”的稳定背景信息，帮助成员理解所处环境。
+- 它不应承担 persona 定义、skill 教程、团队制度大全、或仓库全局规范汇总的职责。
+- 这类内容按分工应分别落在 `persona/knowledge/lessons`、skills、priming、或仓库自己的规范文件中。
+- 设计文档在这里仅强调用途边界；具体注入位置、回退规则、标题建议等，以运行时 `man({ "toolsetId": "team_mgmt", "topics": ["env"] })` 为准。
+
 ## 引导策略：影子成员引导
 
 初始引导的首选行为：

package/dist/llm/kernel-driver/flow.js

@@ -676,7 +676,7 @@ async function executeDriveRound(args) {
                     }
                     else {
                         await (0, tellask_special_1.deliverTellaskBackReplyFromDirective)({
-                            dlg: dialog,
+                            replyingDialog: dialog,
                             directive: activeTellaskReplyDirective,
                             replyContent: driveResult.lastAssistantSayingContent,
                             callbacks: {

package/dist/llm/kernel-driver/tellask-special.d.ts

@@ -67,7 +67,7 @@ export type InvalidTellaskFunctionCall = Readonly<{
 export declare function isTellaskCallFunctionName(name: string): name is TellaskCallFunctionName;
 export declare function loadLatestActiveTellaskReplyDirective(dialog: Dialog): Promise<TellaskReplyDirective | undefined>;
 export declare function deliverTellaskBackReplyFromDirective(args: {
-    dlg: Dialog;
+    replyingDialog: Dialog;
     directive: Extract<TellaskReplyDirective, {
         expectedReplyCallName: 'replyTellaskBack';
     }>;

package/dist/llm/kernel-driver/tellask-special.js

@@ -136,39 +136,48 @@ function buildTellaskBackReplyDirective(args) {
     };
 }
 async function deliverTellaskBackReplyFromDirective(args) {
-    const rootDialog = args.dlg instanceof dialog_1.RootDialog
-        ? args.dlg
-        : args.dlg instanceof dialog_1.SubDialog
-            ? args.dlg.rootDialog
+    // Type-A ask-back is the one place where the local "caller/callee" intuition flips:
+    // the dialog running `replyTellaskBack` is the ask-back responder, while
+    // directive.targetDialogId points to the ask-back requester that must receive the canonical
+    // tellaskBack result. Keep those roles explicit, otherwise it is very easy to accidentally
+    // write the same business result once from the reply-tool path and then again from a fallback
+    // path that treats the responder's plain assistant words as if they were the canonical reply.
+    const rootDialog = args.replyingDialog instanceof dialog_1.RootDialog
+        ? args.replyingDialog
+        : args.replyingDialog instanceof dialog_1.SubDialog
+            ? args.replyingDialog.rootDialog
             : undefined;
     if (!rootDialog) {
         throw new Error('replyTellaskBack invariant violation: missing root dialog');
     }
-    const targetDialogId = new dialog_1.DialogID(args.directive.targetDialogId, rootDialog.id.rootId);
-    const targetDialog = rootDialog.lookupDialog(targetDialogId.selfId) ??
-        (await (0, dialog_instance_registry_1.ensureDialogLoaded)(rootDialog, targetDialogId, rootDialog.status));
-    if (!targetDialog) {
-        throw new Error(`replyTellaskBack invariant violation: target dialog ${targetDialogId.selfId} not found`);
+    const askBackRequesterDialogId = new dialog_1.DialogID(args.directive.targetDialogId, rootDialog.id.rootId);
+    const askBackRequesterDialog = rootDialog.lookupDialog(askBackRequesterDialogId.selfId) ??
+        (await (0, dialog_instance_registry_1.ensureDialogLoaded)(rootDialog, askBackRequesterDialogId, rootDialog.status));
+    if (!askBackRequesterDialog) {
+        throw new Error(`replyTellaskBack invariant violation: target dialog ${askBackRequesterDialogId.selfId} not found`);
     }
-    targetDialog.setSuspensionState('resumed');
     const response = (0, inter_dialog_format_1.formatTellaskResponseContent)({
         callName: 'tellaskBack',
-        responderId: args.dlg.agentId,
-        requesterId: targetDialog.agentId,
+        responderId: args.replyingDialog.agentId,
+        requesterId: askBackRequesterDialog.agentId,
         tellaskContent: args.directive.tellaskContent,
         responseBody: args.replyContent,
         status: 'completed',
         deliveryMode: args.deliveryMode,
         language: (0, work_language_1.getWorkLanguage)(),
     });
-    const replyMirror = await targetDialog.receiveTellaskResponse(args.dlg.agentId, 'tellaskBack', undefined, args.directive.tellaskContent, 'completed', args.dlg.id, {
+    const replyMirror = await askBackRequesterDialog.receiveTellaskResponse(args.replyingDialog.agentId, 'tellaskBack', undefined, args.directive.tellaskContent, 'completed', args.replyingDialog.id, {
         response,
-        agentId: args.dlg.agentId,
+        agentId: args.replyingDialog.agentId,
         callId: args.directive.targetCallId,
-        originMemberId: targetDialog.agentId,
+        originMemberId: askBackRequesterDialog.agentId,
     });
-    await targetDialog.addChatMessages(replyMirror);
-    await reviveDialogIfUnblocked(targetDialog, args.callbacks, 'reply_tellask_back_delivered');
+    await askBackRequesterDialog.addChatMessages(replyMirror);
+    // Do not mark the requester resumed until the canonical tellaskBack result has actually been
+    // persisted and mirrored locally. Otherwise a write failure here would leave suspension state
+    // claiming "resumed" while the business fact never landed.
+    askBackRequesterDialog.setSuspensionState('resumed');
+    await reviveDialogIfUnblocked(askBackRequesterDialog, args.callbacks, 'reply_tellask_back_delivered');
 }
 function isReplyTellaskCallRecord(record) {
     return isReplyTellaskCallName(record.name);
@@ -883,9 +892,29 @@ function extractLastAssistantResponse(messages, defaultMessage) {
     }
     return responseText;
 }
-async function extractSupdialogResponseForTypeA(supdialog) {
+function findDeliveredTellaskBackReplyOnAskBackRequester(args) {
+    // `replyTellaskBack` persists the canonical tellaskBack business result onto the ask-back
+    // requester dialog immediately. Type-A orchestration must check that canonical delivery first
+    // before it even considers any fallback extraction from responder plaintext, or we risk a
+    // second final result with the same target callId.
+    for (let i = args.requesterDialog.msgs.length - 1; i >= 0; i -= 1) {
+        const msg = args.requesterDialog.msgs[i];
+        if (msg.type !== 'tellask_result_msg' || msg.callName !== 'tellaskBack') {
+            continue;
+        }
+        if (msg.callId !== args.targetCallId) {
+            continue;
+        }
+        return msg;
+    }
+    return undefined;
+}
+async function extractAskBackResponderPlaintextFallback(args) {
+    // This fallback is intentionally second-class: it exists only for legacy/plain-reply flows
+    // where no explicit `replyTellaskBack` canonical result has been delivered. It must never
+    // compete with or overwrite an already delivered canonical tellaskBack result.
     try {
-        return extractLastAssistantResponse(supdialog.msgs, 'Supdialog completed without producing output.');
+        return extractLastAssistantResponse(args.responderDialog.msgs, 'Supdialog completed without producing output.');
     }
     catch (err) {
         log_1.log.warn('Failed to extract supdialog response for Type A', err);
@@ -1158,14 +1187,20 @@ async function executeTellaskCall(dlg, mentionList, body, callId, callbacks, opt
         }
         if (parseResult.type === 'A') {
             if (dlg instanceof dialog_1.SubDialog) {
-                const supdialog = dlg.supdialog;
-                dlg.setSuspensionState('suspended');
+                // Identity map for Type-A ask-back:
+                // - `askBackRequesterDialog` is the sideline dialog that asked upstream for clarification.
+                // - `askBackResponderDialog` is the upstream dialog that must answer that ask-back.
+                // The original tellask relationship is the opposite of the current ask-back relationship,
+                // so variable names like "supdialog" or "target" are too lossy here and invite bugs.
+                const askBackRequesterDialog = dlg;
+                const askBackResponderDialog = dlg.supdialog;
+                askBackRequesterDialog.setSuspensionState('suspended');
                 try {
-                    const assignment = dlg.assignmentFromSup;
+                    const assignment = askBackRequesterDialog.assignmentFromSup;
                     const supPrompt = {
                         content: (0, inter_dialog_format_1.formatSupdialogCallPrompt)({
-                            fromAgentId: dlg.agentId,
-                            toAgentId: supdialog.agentId,
+                            fromAgentId: askBackRequesterDialog.agentId,
+                            toAgentId: askBackResponderDialog.agentId,
                             subdialogRequest: {
                                 callName,
                                 mentionList,
@@ -1182,12 +1217,12 @@ async function executeTellaskCall(dlg, mentionList, body, callId, callbacks, opt
                         grammar: 'markdown',
                         origin: 'runtime',
                         tellaskReplyDirective: buildTellaskBackReplyDirective({
-                            targetDialogId: dlg.id.selfId,
+                            targetDialogId: askBackRequesterDialog.id.selfId,
                             targetCallId: callId,
                             tellaskContent: body,
                         }),
                     };
-                    await callbacks.driveDialog(supdialog, {
+                    await callbacks.driveDialog(askBackResponderDialog, {
                         humanPrompt: supPrompt,
                         waitInQue: true,
                         driveOptions: {
@@ -1195,20 +1230,34 @@ async function executeTellaskCall(dlg, mentionList, body, callId, callbacks, opt
                             reason: 'type_a_supdialog_roundtrip',
                         },
                     });
-                    const responseText = await extractSupdialogResponseForTypeA(supdialog);
+                    const explicitReplyDelivery = findDeliveredTellaskBackReplyOnAskBackRequester({
+                        requesterDialog: askBackRequesterDialog,
+                        targetCallId: callId,
+                    });
+                    if (explicitReplyDelivery) {
+                        // Important invariant: once the responder used `replyTellaskBack`, that write is the
+                        // single source of truth. Do not also synthesize another tellask result from the
+                        // responder's generic assistant words, even if those words look "compatible".
+                        askBackRequesterDialog.setSuspensionState('resumed');
+                        toolOutputs.push(explicitReplyDelivery);
+                        return toolOutputs;
+                    }
+                    const responseText = await extractAskBackResponderPlaintextFallback({
+                        responderDialog: askBackResponderDialog,
+                    });
                     const responseContent = (0, inter_dialog_format_1.formatTellaskResponseContent)({
                         callName,
                         responderId: parseResult.agentId,
-                        requesterId: dlg.agentId,
+                        requesterId: askBackRequesterDialog.agentId,
                         mentionList,
                         tellaskContent: body,
                         responseBody: responseText,
                         status: 'completed',
                         language: (0, work_language_1.getWorkLanguage)(),
                     });
-                    dlg.setSuspensionState('resumed');
+                    askBackRequesterDialog.setSuspensionState('resumed');
                     toolOutputs.push(buildTellaskResultToolOutput({
-                        genseq: dlg.activeGenSeqOrUndefined ?? 1,
+                        genseq: askBackRequesterDialog.activeGenSeqOrUndefined ?? 1,
                         callId,
                         callName,
                         content: responseContent,
@@ -1217,24 +1266,24 @@ async function executeTellaskCall(dlg, mentionList, body, callId, callbacks, opt
                         tellaskContent: body,
                         mentionList,
                         agentId: parseResult.agentId,
-                        originMemberId: dlg.agentId,
-                        calleeDialogId: supdialog.id.selfId,
+                        originMemberId: askBackRequesterDialog.agentId,
+                        calleeDialogId: askBackResponderDialog.id.selfId,
                     }));
-                    await dlg.receiveTellaskResponse(parseResult.agentId, callName, mentionList, body, 'completed', supdialog.id, {
+                    await askBackRequesterDialog.receiveTellaskResponse(parseResult.agentId, callName, mentionList, body, 'completed', askBackResponderDialog.id, {
                         response: responseContent,
                         agentId: parseResult.agentId,
                         callId,
-                        originMemberId: dlg.agentId,
+                        originMemberId: askBackRequesterDialog.agentId,
                     });
                 }
                 catch (err) {
                     log_1.log.warn('Type A supdialog processing error:', err);
-                    dlg.setSuspensionState('resumed');
+                    askBackRequesterDialog.setSuspensionState('resumed');
                     const errorText = `❌ **Error processing request to @${parseResult.agentId}:**\n\n${showErrorToAi(err)}`;
                     const errorContent = (0, inter_dialog_format_1.formatTellaskResponseContent)({
                         callName,
                         responderId: parseResult.agentId,
-                        requesterId: dlg.agentId,
+                        requesterId: askBackRequesterDialog.agentId,
                         mentionList,
                         tellaskContent: body,
                         responseBody: errorText,
@@ -1242,7 +1291,7 @@ async function executeTellaskCall(dlg, mentionList, body, callId, callbacks, opt
                         language: (0, work_language_1.getWorkLanguage)(),
                     });
                     toolOutputs.push(buildTellaskResultToolOutput({
-                        genseq: dlg.activeGenSeqOrUndefined ?? 1,
+                        genseq: askBackRequesterDialog.activeGenSeqOrUndefined ?? 1,
                         callId,
                         callName,
                         content: errorContent,
@@ -1251,14 +1300,14 @@ async function executeTellaskCall(dlg, mentionList, body, callId, callbacks, opt
                         tellaskContent: body,
                         mentionList,
                         agentId: parseResult.agentId,
-                        originMemberId: dlg.agentId,
-                        calleeDialogId: supdialog.id.selfId,
+                        originMemberId: askBackRequesterDialog.agentId,
+                        calleeDialogId: askBackResponderDialog.id.selfId,
                     }));
-                    await dlg.receiveTellaskResponse(parseResult.agentId, callName, mentionList, body, 'failed', supdialog.id, {
+                    await askBackRequesterDialog.receiveTellaskResponse(parseResult.agentId, callName, mentionList, body, 'failed', askBackResponderDialog.id, {
                         response: errorContent,
                         agentId: parseResult.agentId,
                         callId,
-                        originMemberId: dlg.agentId,
+                        originMemberId: askBackRequesterDialog.agentId,
                     });
                 }
             }
@@ -1779,7 +1828,7 @@ async function executeReplyTellaskCall(args) {
                 throw new Error('replyTellaskBack invariant violation: unexpected active reply directive');
             }
             await deliverTellaskBackReplyFromDirective({
-                dlg: args.dlg,
+                replyingDialog: args.dlg,
                 directive: activeDirective,
                 replyContent: args.call.replyContent,
                 callbacks: args.callbacks,

package/dist/persistence.d.ts

@@ -72,6 +72,9 @@ export declare class DiskFileDialogStore extends DialogStore {
      * Ensure subdialog directory exists (delegate to DialogPersistence)
      */
     private ensureSubdialogDirectory;
+    private findExistingFuncResultRecord;
+    private findExistingTellaskResultRecord;
+    private raiseDuplicateCallResultInvariantViolation;
     /**
      * Append event to course JSONL file (delegate to DialogPersistence)
      */

package/dist/persistence.js

@@ -1433,6 +1433,19 @@ class DiskFileDialogStore extends dialog_1.DialogStore {
         if (!Number.isFinite(genseq) || genseq <= 0) {
             throw new Error(`receiveFuncResult invariant violation: missing valid genseq for func result ${funcResult.id}`);
         }
+        const existingFuncResult = await this.findExistingFuncResultRecord(dialog, funcResult.id);
+        if (existingFuncResult) {
+            await this.raiseDuplicateCallResultInvariantViolation({
+                dialog,
+                kind: 'func_result',
+                callId: funcResult.id,
+                callName: funcResult.name,
+                incomingCourse: course,
+                incomingGenseq: genseq,
+                existingCourse: existingFuncResult.course,
+                existingGenseq: existingFuncResult.record.genseq,
+            });
+        }
         const funcResultRecord = buildFuncResultRecord(funcResult, genseq);
         await this.appendEvent(dialog, course, funcResultRecord);
         // Send event to frontend
@@ -1464,6 +1477,19 @@ class DiskFileDialogStore extends dialog_1.DialogStore {
                 ...result,
                 genseq,
             };
+        const existingTellaskResult = await this.findExistingTellaskResultRecord(dialog, normalizedResult.callId);
+        if (existingTellaskResult) {
+            await this.raiseDuplicateCallResultInvariantViolation({
+                dialog,
+                kind: 'tellask_result',
+                callId: normalizedResult.callId,
+                callName: normalizedResult.callName,
+                incomingCourse: course,
+                incomingGenseq: genseq,
+                existingCourse: existingTellaskResult.course,
+                existingGenseq: existingTellaskResult.record.genseq,
+            });
+        }
         const record = buildTellaskResultRecord(normalizedResult, genseq);
         await this.appendEvent(dialog, course, record);
         (0, evt_registry_1.postDialogEvent)(dialog, buildTellaskResultEvent(normalizedResult, course));
@@ -1489,6 +1515,74 @@ class DiskFileDialogStore extends dialog_1.DialogStore {
     async ensureSubdialogDirectory(dialogId) {
         return await DialogPersistence.ensureSubdialogDirectory(dialogId);
     }
+    async findExistingFuncResultRecord(dialog, callId) {
+        const latest = await DialogPersistence.loadDialogLatest(dialog.id, dialog.status);
+        const maxCourse = latest?.currentCourse ?? dialog.currentCourse;
+        for (let course = 1; course <= maxCourse; course += 1) {
+            const events = await DialogPersistence.loadCourseEvents(dialog.id, course, dialog.status);
+            for (const event of events) {
+                if (event.type !== 'func_result_record') {
+                    continue;
+                }
+                if (event.id !== callId) {
+                    continue;
+                }
+                return { course, record: event };
+            }
+        }
+        return undefined;
+    }
+    async findExistingTellaskResultRecord(dialog, callId) {
+        const latest = await DialogPersistence.loadDialogLatest(dialog.id, dialog.status);
+        const maxCourse = latest?.currentCourse ?? dialog.currentCourse;
+        for (let course = 1; course <= maxCourse; course += 1) {
+            const events = await DialogPersistence.loadCourseEvents(dialog.id, course, dialog.status);
+            for (const event of events) {
+                if (event.type !== 'tellask_result_record') {
+                    continue;
+                }
+                if (event.callId !== callId) {
+                    continue;
+                }
+                return { course, record: event };
+            }
+        }
+        return undefined;
+    }
+    async raiseDuplicateCallResultInvariantViolation(args) {
+        // Duplicate final results are not harmless transcript noise. They mean two different program
+        // paths both believed they owned the same business-level completion fact for one callId.
+        // In ask-back flows this usually points to identity confusion between requester/responder or
+        // canonical reply-tool delivery versus fallback plaintext synthesis. We fail fast here so the
+        // second writer keeps its own stack trace instead of silently corrupting the dialog transcript.
+        const err = new Error(`${args.kind} duplicate callId invariant violation: rootId=${args.dialog.id.rootId} selfId=${args.dialog.id.selfId} ` +
+            `callId=${args.callId} callName=${args.callName} existingCourse=${args.existingCourse} ` +
+            `existingGenseq=${args.existingGenseq} incomingCourse=${args.incomingCourse} incomingGenseq=${args.incomingGenseq}`);
+        log_1.log.error('Duplicate call result detected; rejecting second write', err, {
+            rootId: args.dialog.id.rootId,
+            selfId: args.dialog.id.selfId,
+            callId: args.callId,
+            callName: args.callName,
+            kind: args.kind,
+            existingCourse: args.existingCourse,
+            existingGenseq: args.existingGenseq,
+            incomingCourse: args.incomingCourse,
+            incomingGenseq: args.incomingGenseq,
+        });
+        try {
+            await this.streamError(args.dialog, err.message);
+        }
+        catch (streamErr) {
+            log_1.log.warn('Failed to emit stream_error_evt for duplicate call result', streamErr, {
+                rootId: args.dialog.id.rootId,
+                selfId: args.dialog.id.selfId,
+                callId: args.callId,
+                callName: args.callName,
+                kind: args.kind,
+            });
+        }
+        throw err;
+    }
     /**
      * Append event to course JSONL file (delegate to DialogPersistence)
      */
@@ -1953,7 +2047,7 @@ class DiskFileDialogStore extends dialog_1.DialogStore {
     async streamError(dialog, error) {
         log_1.log.error(`Dialog stream error '${error}'`, new Error(), { dialog });
         const course = dialog.activeGenCourseOrUndefined ?? dialog.currentCourse;
-        const genseq = typeof dialog.activeGenSeq === 'number' ? dialog.activeGenSeq : undefined;
+        const genseq = dialog.activeGenSeqOrUndefined;
         // Enhanced stream error event with better error classification
         const streamErrorEvent = {
             type: 'stream_error_evt',

package/dist/tools/team_mgmt.js

@@ -3429,14 +3429,15 @@ function renderMindsManual(language) {
         return (fmtHeader('.minds/team/<id>/*') +
             fmtList([
                 '推荐实践（建议默认采用）：每个 `members.<id>` 同时维护 `persona.*.md` / `knowledge.*.md` / `lessons.*.md`，把角色设定、领域知识、经验教训分层管理。',
-                '最小要求：每个 `members.<id>` 建议至少提供 `persona.*.md`（否则该成员将缺少可发现的角色设定；具体忽略/回退/报错行为以当前实现为准）。',
-                'persona.*.md：角色设定（稳定的工作方式与职责）。',
+                '共同去向（按当前实现）：这三类文件会在每次对话开始时按工作语言读取，并分别拼进 system prompt 的 `## 角色设定` / `## 知识` / `## 经验` 章节；它们是写给“当前成员智能体自己”看的长期提示，不是给团队管理者/人类旁观者读的人物简介。',
+                '最小要求：每个 `members.<id>` 建议至少提供 `persona.*.md`。当前实现中，缺失 persona 时会回退到内置默认 persona 文案；缺失或空白的 knowledge/lessons 会在系统提示中以本地化的“无”占位显示。',
+                'persona.*.md：角色设定（稳定的工作方式与职责）。它会进入该成员的 `role=system` 提示，因此默认应直接写给该智能体本人，使用第二人称“你”来规定职责、边界与工作方式；不要把它写成第三人称人物简介，更不要使用“祂”这类旁白口吻。',
+                'knowledge.*.md：领域知识。它会进入 `## 知识`，适合写“当前成员在该职责下反复要用到的稳定事实 / 索引 / 约定 / 判断依据”；口吻可用第二人称提示，或零人称资料式 bullet，但目标始终是帮助该成员立刻行动，不是对外介绍这个成员。',
+                'lessons.*.md：经验教训。它会进入 `## 经验`，适合写成可复用的行为准则，例如“遇到什么信号 -> 先做什么 / 不要做什么 -> 为什么”；不要写成任务流水账、会议纪要或第三人称成长故事。',
                 '若该成员承担团队管理职责（尤其获得 `team_mgmt`），其 `persona.*.md` 必须明确写出：执行任何团队管理操作前先查看 `man({ "toolsetId": "team_mgmt" })` 的相关章节，并按手册标准做法维护 `.minds/**` 团队心智资产。',
-                'knowledge.*.md：领域知识（可维护）。',
-                'lessons.*.md：经验教训（可维护）。',
-                '写法约束：`persona/knowledge/lessons` 文件里不要再写重复的总标题。系统提示模板会自动添加：`## 角色设定` / `## 知识` / `## 经验`（英文模板对应 `## Persona` / `## Knowledge` / `## Lessons`）。',
+                '语言选择（按当前实现）：优先读取 `persona.zh.md` / `knowledge.zh.md` / `lessons.zh.md` 这类工作语言文件，其次才回退到无语言后缀的 `persona.md` / `knowledge.md` / `lessons.md`；不会跨语言回退到另一种语言文件。',
+                '标题层级约束：`persona/knowledge/lessons` 文件里不要再写重复的总标题。系统提示模板会自动添加：`## 角色设定` / `## 知识` / `## 经验`（英文模板对应 `## Persona` / `## Knowledge` / `## Lessons`）。因此正文通常应从 `###` 小节或普通 bullet 开始，而不是再写 `#` / `##`，也不要再把文件名或“角色设定/知识/经验”重复当标题写一遍。',
                 'Codex provider 专属能力：若该成员使用 `provider: codex`，可在 `persona.*.md` 中单独写一行 `@codex-system-prompt`，把 stock Codex 内置系统提示拼接进当前 persona；需要固定某个模板版本时写 `@codex-system-prompt:<model>`。建议把这行放在文件最前面，再继续写本团队自己的角色边界与交付要求。',
-                '语言文件命名：优先按工作语言提供 `persona.zh.md` / `persona.en.md` 等；是否回退到 `persona.md`/其他语言版本，以当前实现为准。',
             ]) +
             fmtCodeBlock('text', [
                 '.minds/',
@@ -3450,12 +3451,12 @@ function renderMindsManual(language) {
                 '@codex-system-prompt',
                 '',
                 '### 核心身份',
-                '- 专业程序员，负责按规格完成代码开发。',
+                '- 你是专业程序员，负责按规格完成代码开发。',
                 '### 工作边界',
-                '- 不负责需求分析或产品策略决策。',
-                '- 只根据已确认的开发规格进行实现与重构。',
+                '- 你不负责需求分析或产品策略决策。',
+                '- 你只根据已确认的开发规格进行实现与重构。',
                 '### 交付标准',
-                '- 输出可运行代码，并附关键验证步骤。',
+                '- 你要输出可运行代码，并附关键验证步骤。',
             ]) +
             fmtCodeBlock('markdown', [
                 '- 修改前先定位调用链与数据流，避免“只改表面”。',
@@ -3466,14 +3467,15 @@ function renderMindsManual(language) {
     return (fmtHeader('.minds/team/<id>/*') +
         fmtList([
             'Recommended default practice: for each `members.<id>`, maintain `persona.*.md` / `knowledge.*.md` / `lessons.*.md` together so persona, domain knowledge, and lessons stay layered and maintainable.',
-            'Minimum: for each `members.<id>`, provide at least `persona.*.md` (otherwise the member may lack a discoverable persona; ignore/fallback/error behavior follows current implementation).',
-            'persona.*.md: persona and operating style.',
+            'Shared destination (current implementation): these three files are read at every dialog start and are spliced into the system prompt as `## Persona` / `## Knowledge` / `## Lessons`. They are long-lived prompt assets written for the current member agent itself, not operator-facing biographies for a team manager or human observer.',
+            'Minimum: for each `members.<id>`, provide at least `persona.*.md`. In the current implementation, a missing persona falls back to built-in default persona text, while missing/blank knowledge and lessons render as the localized “none” placeholder.',
+            'persona.*.md: persona and operating style. It is injected into that member\'s `role=system` prompt, so write it directly to the agent in second person ("you") when specifying responsibilities, boundaries, and working style; do not turn it into a third-person biography.',
+            'knowledge.*.md: domain knowledge. It lands in `## Knowledge`, so use it for stable facts, indexes, conventions, and decision cues that the member repeatedly needs in this responsibility. Second-person guidance or neutral reference bullets are both fine, as long as the text helps the member act now rather than describing the member from the outside.',
+            'lessons.*.md: lessons learned. It lands in `## Lessons`, so prefer reusable heuristics such as “if signal X appears -> do / avoid Y -> because Z”. Do not treat it as a task log, meeting minutes, or a third-person growth narrative.',
             'If the member carries team-management responsibility (especially with `team_mgmt`), `persona.*.md` must explicitly require reading the relevant `man({ "toolsetId": "team_mgmt" })` chapters before any team-management action, and maintaining `.minds/**` team mind assets by handbook-standard workflow.',
-            'knowledge.*.md: domain knowledge (maintainable).',
-            'lessons.*.md: lessons learned (maintainable).',
-            'Authoring rule: do not add top-level titles that duplicate the system prompt wrapper. The system prompt already adds: `## Persona` / `## Knowledge` / `## Lessons` (zh template: `## 角色设定` / `## 知识` / `## 经验`).',
+            'Language selection (current implementation): prefer work-language variants such as `persona.en.md` / `knowledge.en.md` / `lessons.en.md`, then fall back to `persona.md` / `knowledge.md` / `lessons.md`. There is no cross-language fallback to another language-specific file.',
+            'Heading rule: do not add top-level titles that duplicate the system prompt wrapper. The system prompt already adds: `## Persona` / `## Knowledge` / `## Lessons` (zh template: `## 角色设定` / `## 知识` / `## 经验`). In practice, bodies should usually start at `###` subsections or plain bullets rather than another `#` / `##`, and should not restate the filename or wrapper title as a heading.',
             'Codex-provider-specific capability: if this member uses `provider: codex`, you may place a standalone `@codex-system-prompt` line inside `persona.*.md` to splice the stock Codex built-in system prompt into the current persona. Use `@codex-system-prompt:<model>` to pin a specific bundled prompt variant. Put that line near the top, then continue with your team-specific role boundaries and delivery rules.',
-            'Language variants: prefer working-language files like `persona.en.md` / `persona.zh.md`; whether it falls back to `persona.md` or other languages follows current implementation.',
         ]) +
         fmtCodeBlock('text', [
             '.minds/',
@@ -3487,12 +3489,12 @@ function renderMindsManual(language) {
             '@codex-system-prompt',
             '',
             '### Core Identity',
-            '- Professional programmer responsible for implementing approved development specs.',
+            '- You are a professional programmer responsible for implementing approved development specs.',
             '### Work Boundaries',
-            '- Not responsible for requirement discovery or product strategy.',
-            '- Implements/refactors only against confirmed specs.',
+            '- You are not responsible for requirement discovery or product strategy.',
+            '- You implement/refactor only against confirmed specs.',
             '### Delivery Standard',
-            '- Deliver runnable code plus key verification steps.',
+            '- You deliver runnable code plus key verification steps.',
         ]) +
         fmtCodeBlock('markdown', [
             '- Trace call chain and data flow before editing; avoid patching only symptoms.',
@@ -3508,6 +3510,8 @@ function renderSkillsManual(language) {
                 '语言选择：Dominds 当前工作语言是 `zh|en`，但 skill 文件后缀采用更通行的 `cn|en`。当工作语言为 `zh` 时优先读取 `SKILL.cn.md`，当工作语言为 `en` 时优先读取 `SKILL.en.md`，两者都可回退到无语言标识的 `SKILL.md`；不会跨语言兜底到另一种语言文件。',
                 '可移植优先格式：遵循当前主流 Agent Skills 生态公共子集，使用 `SKILL.md + YAML frontmatter`。最小必备字段是 `name` 与 `description`，正文 markdown 即真正的技能提示词/操作指引。',
                 'Dominds 当前实现会把匹配到的 skill 内容直接注入 agent system prompt；因此这里的技能更接近“指导知识包”。这与部分平台的“先只加载 name/description、命中后再延迟加载正文”不同，请控制体量，把长参考资料拆到同目录其它文件并在正文里按需引用。',
+                '去向与口吻（按当前实现）：`name` 会成为 skills 小节里的标题，`description` 会作为说明文字显示，正文会原样进入 `Prompt` 区块。因此三者都属于写给“当前成员智能体”的系统提示内容。推荐把 `name` 写成稳定技能名，把 `description` 写成“何时用/何时不用”，把正文写成简洁的操作指引（多用祈使句/第二人称），不要写成 marketplace 营销文案、第三人称人物介绍，或对团队管理者的旁白说明。',
+                '标题层级约束：skills 模板已经自动包好 `### Skills（工作技能）` 和每个 skill 的 `#### <name>` 标题。正文通常应从普通 bullet、步骤列表，或至多 `#####` 小节开始；不要在正文里再写 `# <skill-name>` / `## ...` 来重复外层标题结构。',
                 '为兼容公开来源，可保留 `allowed-tools` / `user-invocable` / `disable-model-invocation` 字段；但在 Dominds 中：这些字段目前只用于迁移/文档语义，不会自动授予工具权限，也不会改变运行时调度逻辑。',
                 '最重要的边界：skill 不是权限系统。真正的工具能力仍由 `.minds/team.yaml` 的 `toolsets` / `tools` 与已安装 Dominds apps 决定。',
                 '团队管理职责的智能体可以联网搜索公开 skill 定义（优先官方文档/官方仓库/官方 marketplace 条目），也可以直接基于团队真实操作经验自行总结编写。迁移前必须核对 license、适用场景、是否依赖脚本/外部工具、是否夹带与本团队冲突的人设/权限假设。',
@@ -3526,13 +3530,11 @@ function renderSkillsManual(language) {
                 'disable-model-invocation: false',
                 '---',
                 '',
-                '# Repo Debugger',
-                '',
-                '## 入口',
+                '##### 入口',
                 '- 先确认失败信号与复现入口。',
                 '- 若需要 shell，必须使用当前团队已授权的 Dominds 工具/专员，不得把 `allowed-tools` 视为自动授权。',
                 '',
-                '## 操作步骤',
+                '##### 操作步骤',
                 '1. 收集报错与最近变更。',
                 '2. 最小化复现。',
                 '3. 定位根因并给出验证方案。',
@@ -3572,6 +3574,8 @@ function renderSkillsManual(language) {
             'Language selection: Dominds work language is currently `zh|en`, but skill filenames use the more portable `cn|en` suffixes. When work language is `zh`, Dominds prefers `SKILL.cn.md`; when it is `en`, Dominds prefers `SKILL.en.md`; both may fall back to `SKILL.md`. There is no cross-language fallback.',
             'Portable-first format: follow the common Agent Skills subset used by GitHub/Codex/Claude/skills.sh style ecosystems: `SKILL.md + YAML frontmatter`. The minimum required fields are `name` and `description`; the Markdown body is the actual skill prompt/operating guidance.',
             'Current Dominds behavior eagerly injects matched skills into the agent system prompt. That makes a Dominds skill closer to a guidance knowledge pack than to a lazily loaded marketplace artifact. Keep bodies tight, and move long references into sibling files that the body points to.',
+            'Destination and tone (current implementation): `name` is rendered as the skill heading, `description` appears as visible description text, and the body is inserted verbatim into the `Prompt` block inside system prompt. Write all three for the current member agent. Use a stable skill name, trigger-oriented description, and concise operating guidance in the body; avoid marketplace sales copy, third-person biographies, or operator-facing narration.',
+            'Heading rule: the wrapper already provides `### Skills` and `#### <name>` for each skill. Bodies should usually start with plain bullets, numbered steps, or at most `#####` subsections; do not repeat the outer structure with another `# <skill-name>` / `## ...` inside the body.',
             'For compatibility with public skill sources, Dominds accepts `allowed-tools`, `user-invocable`, and `disable-model-invocation`; however, in Dominds these fields are currently informational only. They do not grant tools and do not change runtime dispatch yet.',
             'The hard boundary: a skill is not a permission system. Real tool access still comes from `.minds/team.yaml` (`toolsets` / `tools`) and installed Dominds apps.',
             'A team-management agent may browse the web for public skill definitions (prefer official docs/repos/marketplace listings), or write skills directly by summarizing the team’s own repeatable operating guidance. Before importing, verify license, applicability, script/tool dependencies, and any hidden persona/permission assumptions.',
@@ -3591,13 +3595,11 @@ function renderSkillsManual(language) {
             'disable-model-invocation: false',
             '---',
             '',
-            '# Repo Debugger',
-            '',
-            '## Entry',
+            '##### Entry',
             '- Confirm the failure signal and reproduction path first.',
             '- If shell is required, use only the Dominds tools/specialists actually granted by the team; never treat `allowed-tools` as auto-authorization.',
             '',
-            '## Procedure',
+            '##### Procedure',
             '1. Gather the error signal and recent changes.',
             '2. Minimize reproduction.',
             '3. Isolate root cause and propose verification.',
@@ -3636,14 +3638,19 @@ function renderPrimingManual(language) {
         return (fmtHeader('.minds/priming/*（启动脚本）') +
             fmtList([
                 '目录约定：个人脚本放在 `.minds/priming/individual/<member-id>/<slug>.md`；团队共享脚本放在 `.minds/priming/team_shared/<slug>.md`。',
-                '脚本语义：启动脚本会映射成“对话历史”并在创建对话时注入；它不是只读日志，而是可编辑的行为引导层。',
+                '脚本语义（按当前实现）：创建对话时，frontmatter 里的 `reminders` 会先恢复为该对话的提醒状态；随后脚本 records 会被追加进持久化事件流，并尽可能回放成真正的对话历史消息。它不是 system prompt，也不是只读日志，而是可编辑的“起手历史/行为引导层”。',
                 '推荐格式：`frontmatter + record 块`。每个 `### record <type>` 对应一个持久化事件（去掉 `ts`），可忠实复原 tool 记录与 call-id 等技术细节。',
+                '口吻规则取决于 record 类型，而不是统一写成一种旁白：`human_text_record` 会变成 `role=user` 的 prompting message，应写成“用户/诉请者正在对这个智能体说的话”；`agent_words_record` 会变成 `role=assistant` 的可见回复，应写成“这个智能体已经说出口的话”；`agent_thought_record` 会变成 thinking message，只适合非常克制地承载内部推理痕迹，不适合拿来写通用制度说明。',
+                '`func_call_record` / `func_result_record` / tellask 相关 records 属于技术回放层：如果要保留，就应写真实调用名、参数、结果与关联 id，而不是随手写一段 prose 摘要来冒充工具历史。',
+                '`ui_only_markdown_record` 以及若干运行时技术 record 会被持久化，但不会转成喂给模型的 chat message；不要指望这类 record 去直接塑造模型行为。',
                 '严格约束：不支持 `### user` / `### assistant` 旧写法。',
                 '`func_call_record` 使用三反引号 `json`；其余 record 建议使用 6 重反引号 markdown block（避免与正文三反引号冲突）。',
                 '建议在 frontmatter 里维护 `title`、`applicableMemberIds` 等元数据；`team_shared` 脚本可用 `applicableMemberIds` 控制适用成员。',
+                'frontmatter.reminders 的写法也要遵循 reminder 语义：内容应短小、像工作集提示，不要塞成长文手册；若省略 `scope`，当前实现默认是 `dialog`；只有明确希望后续对话也继续可见时，才使用 `personal` 或 `agent_shared`。',
                 '维护原则：允许任意编辑/重写脚本内容，包括新增或改写 assistant 消息，以引导期望行为（而不是拘泥于历史实录）。',
                 '每次修改 `.minds/priming/**` 后，建议运行 `team_mgmt_validate_priming_scripts({})` 做格式/路径校验。',
                 'WebUI 支持把“当前 course 历史”直接导出为个人启动脚本；导出后应由团队管理者审阅并按团队规范再编辑。',
+                '结构层级约束：priming 文件的外层结构以“顶层 frontmatter + 多个 `### record <type>` 块”为准；不要再包一层 `# 启动脚本` / `## 历史` 之类的装饰性章节。真正喂给模型的文本结构，应写在各个 record 自己的 markdown/json block 里。',
                 'slug 规范：使用 `[A-Za-z0-9._-]` 路径段，可多级；严禁 `..`、绝对路径或非法字符。',
             ]) +
             fmtCodeBlock('markdown', [
@@ -3680,14 +3687,19 @@ function renderPrimingManual(language) {
     return (fmtHeader('.minds/priming/* (startup scripts)') +
         fmtList([
             'Directory convention: individual scripts live at `.minds/priming/individual/<member-id>/<slug>.md`; team-shared scripts live at `.minds/priming/team_shared/<slug>.md`.',
-            'Script semantics: startup scripts are mapped into dialog history at creation time. They are not read-only logs; they are editable behavior-guidance assets.',
+            'Script semantics (current implementation): at dialog creation, frontmatter `reminders` are restored into dialog reminder state first; then records are appended to the persisted event stream and replayed into dialog history when possible. A priming script is not system prompt text and not a read-only log; it is an editable “startup history / behavior-guidance” asset.',
             'Recommended format: `frontmatter + record blocks`. Each `### record <type>` maps to one persisted event (without `ts`) for faithful replay, including tool records and call-id links.',
+            'Tone depends on record type, not on one narrator voice: `human_text_record` becomes a `role=user` prompting message, so write it as what the user/requester is saying to the agent; `agent_words_record` becomes a visible `role=assistant` reply, so write it as words the agent has already said; `agent_thought_record` becomes a thinking message and should be used sparingly, not as a place for general policy prose.',
+            '`func_call_record` / `func_result_record` / tellask-related records are technical replay artifacts. Keep real call names, arguments, results, and linked ids if you include them; do not replace them with loose prose summaries.',
+            '`ui_only_markdown_record` and several runtime-only technical records persist on disk but do not become chat messages for model context. Do not rely on those record types to steer the model directly.',
             'Strict rule: legacy `### user` / `### assistant` sections are not supported.',
             '`func_call_record` uses triple-backtick `json`; other records should use six-backtick markdown blocks to avoid nested-fence collisions.',
             'Use frontmatter for metadata like `title` and `applicableMemberIds`; for `team_shared`, `applicableMemberIds` narrows applicability.',
+            'frontmatter.reminders should follow reminder semantics too: keep them short like working-set prompts rather than mini-manuals. If `scope` is omitted, the current implementation defaults it to `dialog`; use `personal` / `agent_shared` only when you intentionally want later dialogs to keep seeing the reminder.',
             'Maintenance principle: freely edit or fully rewrite scripts, including assistant messages, to shape expected behavior.',
             'After each edit under `.minds/priming/**`, run `team_mgmt_validate_priming_scripts({})` for format/path validation.',
             'WebUI can export current-course history into an individual startup script; team managers should review and refine exported scripts.',
+            'Structure rule: the outer file structure is “top-level frontmatter + repeated `### record <type>` blocks”. Do not wrap the script in decorative `# Startup Script` / `## History` headings. The model-facing structure belongs inside each record’s own markdown/json block.',
             'Slug rule: use `[A-Za-z0-9._-]` path segments (nested allowed); reject `..`, absolute paths, and illegal characters.',
         ]) +
         fmtCodeBlock('markdown', [
@@ -3725,17 +3737,19 @@ function renderEnvManual(language) {
     if (language === 'zh') {
         return (fmtHeader('.minds/env.*.md（运行环境提示）') +
             fmtList([
-                '用途：为“当前 rtws 的运行环境”提供一段稳定的介绍文案。Dominds 会将其注入到 agent 的 system prompt 中，注入位置在“团队目录（Team Directory）”之前。',
+                '用途：为“当前 rtws 的运行环境”提供一段稳定的介绍文案。Dominds 会将其注入到 agent 的 system prompt 的 `## 运行环境` 章节，注入位置在“团队目录（Team Directory）”之前。',
                 '文件位置：写在当前 rtws 的 `.minds/` 下；切换 rtws（例如 `-C ux-rtws`）时，应在对应 rtws 的 `.minds/` 下分别维护。',
                 '推荐文件名：`env.zh.md`（中文语义基准）与 `env.en.md`（英文对齐）。',
                 '回退规则：优先按工作语言读取 `env.<lang>.md`；如不存在，可回退到 `env.md`（以当前实现为准）。空文件/仅空白会被当作“无提示”。',
+                '口吻建议：它虽然进入 system prompt，但职责不是定义人设，而是给当前成员做环境定向。最合适的是简洁、可核实的事实说明，可用中性 bullet，也可用“你当前处于……”这类第二人称 briefing；核心是让成员快速知道自己身处哪个 rtws、有哪些关键路径/入口/端口/约束。',
+                '标题层级约束：系统模板已经提供 `## 运行环境` 标题，所以 `env.*.md` 正文通常应从 `###` 小节或普通 bullet 开始；不要再写一层 `# 环境说明` / `## 本 rtws ...` 来重复模板标题。',
+                '边界提醒：不要把 `env.*.md` 写成 persona、skill、工具手册或仓库总规范大杂烩；不要在这里重复团队职责边界、长篇流程制度，或凭空编造环境事实。',
                 'i18n 约定：`zh` 为语义基准。不要把 `zh` 通过翻译 `en` 来更新；应让 `en` 追随 `zh` 的语义。',
                 '管理者提醒：若发现缺失/质量不佳/与实际环境不符，应与人类用户讨论并确认措辞，然后再写入/更新对应的 `env.*.md`（避免“凭空编造”的环境描述）。',
             ]) +
             fmtCodeBlock('text', [
-                '# 示例（片段；请按你的 rtws 真实环境改写）',
-                '## 本 rtws 的 Dominds 运行环境说明',
-                '',
+                '示例（片段；请按你的 rtws 真实环境改写）',
+                '### 当前 rtws 概况',
                 '- 本 rtws 用于 Dominds 自我开发与联调。',
                 '- Dominds 程序来源：本机全局 link 的 `dominds`，由 `./dominds/` 构建产物提供。',
                 '- WebUI dev/UX：`./dev-server.sh` 使用 `ux-rtws/` 作为 rtws（避免污染根 rtws）。',
@@ -3743,17 +3757,19 @@ function renderEnvManual(language) {
     }
     return (fmtHeader('.minds/env.*.md (runtime environment intro)') +
         fmtList([
-            'Purpose: provide a stable intro note describing the “current rtws runtime environment”. Dominds injects it into the agent system prompt, positioned before “Team Directory”.',
+            'Purpose: provide a stable intro note describing the “current rtws runtime environment”. Dominds injects it into the `## Runtime Environment` section of the agent system prompt, positioned before “Team Directory”.',
             'Location: place it under the current rtws `.minds/`. If you switch rtws (e.g. `-C ux-rtws`), maintain a separate `env.*.md` under that rtws’s `.minds/`.',
             'Recommended filenames: `env.zh.md` (canonical semantics) and `env.en.md` (English aligned to zh).',
             'Fallback behavior: prefer `env.<lang>.md` by working language; if missing, it may fall back to `env.md` (per current implementation). Empty/whitespace-only content is treated as “no intro”.',
+            'Tone guidance: although it enters system prompt, its job is environmental orientation rather than persona definition. Prefer concise, verifiable facts in neutral bullets or a brief second-person orientation like “you are currently in...”; the goal is to help the member quickly understand the active rtws, key paths, entrypoints, ports, and constraints.',
+            'Heading rule: the system template already provides the `## Runtime Environment` heading, so `env.*.md` bodies should usually start at `###` subsections or plain bullets rather than another `# Environment Notes` / `## This rtws ...` wrapper.',
+            'Boundary reminder: do not turn `env.*.md` into a persona file, skill, tool manual, or giant repo-policy dump. Avoid duplicating role rules, long procedures, or speculative environment claims.',
             'i18n rule: `zh` is canonical. Do not update `zh` by translating from `en`; update `en` to match `zh` semantics.',
             'Manager reminder: if the file is missing / inaccurate / low quality, discuss wording with the human user and then write/update `env.*.md` (avoid fabricating environment details).',
         ]) +
         fmtCodeBlock('text', [
-            '# Example (snippet; tailor to your real rtws)',
-            '## Dominds runtime environment notes',
-            '',
+            'Example (snippet; tailor to your real rtws)',
+            '### Current rtws overview',
             '- This rtws is used for Dominds self-development and integration.',
             '- Program source: a globally linked `dominds` built from `./dominds/`.',
             '- WebUI dev/UX: `./dev-server.sh` uses `ux-rtws/` as rtws (keeps root rtws clean).',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dominds",
-  "version": "1.16.5",
+  "version": "1.16.7",
   "description": "Dominds CLI and aggregation shell for the LongRun AI kernel/runtime packages.",
   "type": "commonjs",
   "publishConfig": {