dominds 1.23.10 → 1.24.2

package/dist/docs/memory-system.zh.md

@@ -2,12 +2,13 @@
 
 英文版：[English](./memory-system.md)
 
-Dominds 的“记忆系统”本质上是一套**上下文工程（context engineering）**：把不同稳定性、不同共享范围的信息放到合适的载体里，让智能体在长程任务中既能保持速度，也能保持正确率与对人类的透明度。
+Dominds 的“记忆系统”本质上是一套**上下文工程（context engineering）**：把不同稳定性、不同共享范围、不同执行语义的信息放到合适的载体里，让智能体在长程任务中既能保持速度，也能保持正确率与对人类的透明度。
 
 TL;DR：
 
 - **让对话历史可丢弃**（噪音可以随时清掉）。
 - **让关键产物可存活**（清理头脑后仍能继续推进）。
+- **让技能成为一等上下文资产**：memory 记住“事实/索引/共识”，skills 固化“何时做、怎么做、边界是什么”的可复用操作能力。
 - **实时公开宣告、公开交流（并可追溯）工作进展，达成及时强制协调**：差遣牒 / 团队记忆 / 环境提示，才是跨智能体、多主线并行推进时真正的效率来源。
 
 关键约定：**差遣牒是任务实时协调公告板**。关键决策/当前状态/下一步必须写回 `progress`；硬约束必须写回 `constraints`；不要只留在对话或提醒项里。
@@ -23,6 +24,8 @@ TL;DR：
   - [B) 中期（任务）记忆：差遣牒是单一真源](#b-中期任务记忆差遣牒是单一真源)
   - [C) 短期记忆：对话历史是工作缓冲，提醒项是工作集](#c-短期记忆对话历史是工作缓冲提醒项是工作集)
 - [日常工作流（职场健康）](#日常工作流职场健康)
+  - [写到哪里（快速规则）](#写到哪里快速规则)
+  - [Memory vs Skills：选型原则](#memory-vs-skills选型原则)
 
 ---
 
@@ -33,13 +36,17 @@ TL;DR：
 - **个体记忆（个人/对话局部）**：
   - `persona` / `knowhow` / `pitfalls`（按成员分配的角色定义）
   - 个人记忆（`personal_memory`）
+  - 个人 skills（`.minds/skills/individual/<member-id>/...`）
   - 对话历史（含工具调用与反馈）
   - 提醒项（工作集/工作日志）
 - **集体记忆（团队/任务共享）**：
   - rtws 级“环境提示”（`.minds/env*.md`）：用于写清楚“这个工作区的基本事实/运行约束/注意事项”
   - 团队记忆（`team_memory`）
+  - 团队共享 skills（`.minds/skills/team_shared/...`；`linkable` 池作为团队管理维护的可复用来源）
   - 差遣牒：同一个差遣牒正常预期会被多个主线对话（不同主理人）共同推进，因此它应被视为“集体记忆”的单一真源
 
+skills 与 memory 同属长期上下文资产，但不是同一种东西：**memory 是事实/索引/共识的存储层；skills 是可复用提示技能与操作规程的执行指导层**。系统会在启动时列出可见 skill 的摘要，模型按需通过 `read_skill` 读取正文；`allowed-tools` 这类上游元数据只作迁移提示，不会自动授予 Dominds 工具权限。团队协作 SOP 一般优先落 skill：它应描述角色协作方式、输入输出、升级条件、同步节奏和验收口径，而不是把当前工作区的具体路径写进主体。
+
 ### 权限与分工（社会化分工的要义）
 
 上述“集体记忆”并不意味着“任何智能体都能随意改”。Dominds 的一个核心原则就是**社会化分工**：连“团队治理/团队管理”本身也应被视为一种职能。
@@ -58,6 +65,7 @@ TL;DR：
   - **组织结构分配（静态定义）**：`persona` / `knowhow` / `pitfalls`
   - **动态治理维护（团队共享）**：团队记忆（team memory）
   - **个体智能体自主维护**：个人记忆（individual memory）
+  - **可复用技能资产**：个人 / 团队共享 skills（prompt guidance），以及 MCP resource skills
 - **B) 中期（任务）记忆（跨对话 course 生效）**
   - **差遣牒固定三样（自动注入）**：`goals` / `constraints` / `progress`
   - **差遣牒附加章节（按需召回）**：固化的 `bearinmind/`（`contracts` / `acceptance` / `grants` / `runbook` / `decisions` / `risks`）；其他章节按需扩展（详见 [encapsulated-taskdoc.zh.md](./encapsulated-taskdoc.zh.md)）
@@ -113,6 +121,31 @@ TL;DR：
 - 个人记忆会自动隔离到 `.minds/memory/individual/<member-id>/...`，因此 `path` 不应包含你的成员 id（不要写 `<member-id>/...`）。
 - 若你当前没有任何个人记忆条目，直接 `add_personal_memory` 即可：目录会由系统自动创建。
 
+#### 4) Skills：可复用操作能力（提示技能资产）
+
+skills 的关键词是：**程序化思路**、**可复用操作路径**、**触发条件与边界**。它回答的是“遇到某类任务时，应该怎样做”，而不是“这个工作区当前有哪些事实”。
+
+常见形态：
+
+- 个人 skill：`.minds/skills/individual/<member-id>/<skill-id>/`
+- 团队共享 skill：`.minds/skills/team_shared/<skill-id>/`
+- MCP resource skill：由 MCP resource 暴露的虚拟 skill
+
+建议写入 skill 的内容：
+
+- 跨工作区可复用的调试/审查/设计/验收套路
+- 团队协作 SOP、职责切分、交接/升级/同步流程、验收与回退口径
+- 某类任务的执行步骤、检查清单、失败恢复策略
+- 何时适用、何时不适用、需要哪些权限/工具/输入的边界说明
+
+不建议写入 skill 的内容：
+
+- 当前 rtws 的精确路径、文件索引、架构事实、临时状态：这类内容更适合 `personal_memory` / `team_memory` / `.minds/env*.md` / Taskdoc
+- 需要准实时同步的任务状态、下一步、阻塞：进入 Taskdoc `progress`
+- 需要脚本、专有工具、MCP、外部二进制或稳定执行能力的内容：应升级为 Dominds app / toolset / teammates contract，而不是只停留在 Markdown skill
+
+一个实用拆分法：**工作区关联强的事实进 memory；独立于工作区内容的操作方法进 skill**。如果一个经验同时包含二者，就拆开：把通用步骤写成 skill，把当前仓库的路径、命令入口、局部契约写进 memory 或 env notes，并在 skill 中说明需要先读取相应 memory/env 信息。若某个 SOP 看起来“写满了路径”，先尝试把它抽象成可泛指的协作概念；路径只保留为绑定信息，不要让它吞掉 SOP 主体。
+
 ### B) 中期（任务）记忆：差遣牒是单一真源
 
 差遣牒的关键词是：**任务契约**、**团队共享**、**可持续推进**。它回答三个问题：我们要达成什么、不能做什么、目前进展到哪。
@@ -218,9 +251,26 @@ TL;DR：
 - **团队记忆 `team_memory`**：稳定的团队约定与不变量（值得长期复用）
 - **环境提示 `.minds/env*.md`**：rtws 的基本事实、运行约束、注意事项（让人类与所有智能体对齐同一环境）
 - **个人记忆 `personal_memory`**：个人偏好 + 职责域 rtws 索引（保持准确）
+- **skills**：可复用操作指引、检查清单、触发条件与边界（portable procedure，不是事实仓库）
 - **提醒项**：短期高频细节（工作集/工作日志，随时可删）
 - **对话历史/工具输出**：默认可丢弃；需要留的只留“精炼摘录”，不要长期背着原始转储
 
+### Memory vs Skills：选型原则
+
+优先问四个问题：
+
+1. **它是否强依赖当前工作区内容？** 精确路径、符号、接口事实、仓库约定、当前 rtws 运行约束，优先 memory/env；跨工作区可复用的方法，优先 skill。
+2. **它是事实还是做法？** “X 文件负责 Y”是 memory；“做 X 类评审时按 A/B/C 检查”是 skill。
+3. **它需要团队共享还是个人携带？** 多人都应遵守的稳定事实进 `team_memory`；团队协作 SOP 与团队级操作规程通常进团队共享 skill。只服务某成员的入口地图进 `personal_memory`，只服务某成员的操作偏好进个人 skill。
+4. **它是否需要真正的执行能力？** 如果需要脚本、权限、MCP、外部二进制、稳定 UI/API 能力，就不要只写 skill；应设计 app/toolset/teammates contract，并在 skill 里只保留调用与判断规程。
+
+设计上的额外考量：
+
+- **上下文预算**：memory 应短小、精确、常更新；skill 可以较长，但摘要要能帮助模型决定是否 `read_skill`。
+- **过期成本**：容易随仓库变化而过期的事实不要塞进 skill；否则 skill 会成为隐蔽的陈旧知识源。
+- **可审计性**：团队共享 skill 和 team memory 都是团队资产，应由具备治理权限的角色维护；个人资产也要在发现过期时立即更新。
+- **语言与语义**：涉及用户可见语义时，遵守项目 i18n 规则；中文语义仍是基准。
+
 ### 吃紧/告急：一旦发作就先止血
 
 当上下文健康进入**吃紧/告急**（见 [context-health.zh.md](./context-health.zh.md)）时，不要继续“堆输入”：

package/dist/docs/team_mgmt-toolset.md

@@ -175,12 +175,12 @@ reading source code.
 - `man({ "toolsetId": "team_mgmt", "topics": ["llm"] })` → how to manage `.minds/llm.yaml` (+ templates).
 - `man({ "toolsetId": "team_mgmt", "topics": ["llm", "builtin-defaults"] })` → show builtin providers/models (from defaults).
 - `man({ "toolsetId": "team_mgmt", "topics": ["mcp"] })` → how to manage `.minds/mcp.yaml` (+ templates).
-- `man({ "toolsetId": "team_mgmt", "topics": ["mcp"] })` → how to manage `.minds/mcp.yaml` (transports, env/headers, tools whitelist/blacklist, naming transforms, hot reload, leasing).
+- `man({ "toolsetId": "team_mgmt", "topics": ["mcp"] })` → how to manage `.minds/mcp.yaml` (transports, env/headers, tools whitelist/blacklist, ID transforms, hot reload, leasing).
 - `man({ "toolsetId": "team_mgmt", "topics": ["mcp", "troubleshooting"] })` → common MCP failure modes and how to recover.
 - `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/knowhow/pitfalls).
-- `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → how to manage `.minds/skills/*` (injection point, tone, heading levels, migration boundaries).
+- `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → how to manage `.minds/skills/*` (Skills index / `read_skill` body loading, 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.
@@ -214,7 +214,7 @@ must cover (at minimum) the information that used to live there:
   - Explain `.minds/mcp.yaml` as the source of dynamic MCP toolsets.
   - Explain how MCP servers map to toolsets (`<serverId>`) and how those toolsets are granted via
     `.minds/team.yaml`.
-  - Explain tool exposure controls (whitelist/blacklist) and naming transforms (prefix/suffix).
+  - Explain tool exposure controls (whitelist/blacklist) and ID transforms (prefix/suffix).
   - Explain secret/env wiring patterns and operational troubleshooting (Problems + logs, restart,
     hot reload semantics).
 - `!skills`:
@@ -432,13 +432,15 @@ servers:
     # headers: {}
     # sessionId: '' # optional
 
+    # Default ID transforms for tools/prompts/resources/resource skills
+    transform: [] # optional
+
     # Tool exposure controls
     tools:
       whitelist: [] # optional
       blacklist: [] # optional
-
-    # Tool name transforms
-    transform: [] # optional
+      # Optional tool-only override; explicit [] disables the top-level transform for tools.
+      # transform: []
 
     # Optional manual information
     manual:
@@ -455,12 +457,12 @@ servers:
 
 Use `tools.whitelist` / `tools.blacklist` to reduce the exposed tool surface and avoid UI clutter.
 Patterns use `*` wildcards and apply to the **original MCP tool name** (before transforms), so
-filters remain stable even if naming transforms change later.
+filters remain stable even if ID transforms change later.
 
-### Naming transforms (prefix / suffix)
+### ID transforms (prefix / suffix)
 
-MCP servers often export short/common tool names (`open`, `search`, `list`, …). Use transforms to
-avoid global collisions and make tool names recognizable:
+MCP servers often export short/common IDs (`open`, `search`, `list`, prompt names, resource URIs,
+…). Use transforms to avoid global collisions and make Dominds IDs recognizable:
 
 ```yaml
 transform:
@@ -468,6 +470,12 @@ transform:
   - suffix: '_mcp'
 ```
 
+Top-level `servers.<serverId>.transform` is the default for all MCP-derived Dominds IDs from that
+server: tools, prompts, resources/resource templates, and resource skills. Nested
+`tools.transform`, `prompts.transform`, `resources.transform`, and `resources.skills.transform`
+override the enclosing transform for that surface; they do not stack with it. Use an explicit
+`transform: []` inside a surface to keep that surface untransformed.
+
 ### Env and headers wiring
 
 Prefer copying from the host environment for secrets:
@@ -601,6 +609,15 @@ 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.
+- Selection rule: workspace-coupled facts, paths, local contracts, and indexes belong in
+  `personal_memory` / `team_memory` / `.minds/env*.md`; workspace-independent operating methods,
+  checklists, triggers, and boundaries belong in skills.
+- Team collaboration SOPs should usually be team-shared skills: abstract responsibilities, stages,
+  inputs/outputs, escalation conditions, and synchronization cadence into portable procedures; keep
+  this workspace's concrete paths, member bindings, and tool bindings as facts in memory/env/team.yaml.
+- If an experience contains both a portable method and current-rtws facts, split it: keep the
+  reusable procedure in the skill and keep this repo's paths, command entrypoints, and local
+  contracts in memory/env so the skill does not become a hidden stale-fact warehouse.
 - 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.

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

@@ -141,12 +141,12 @@
 - `man({ "toolsetId": "team_mgmt", "topics": ["llm"] })` → 如何管理 `.minds/llm.yaml`（+ 模板）
 - `man({ "toolsetId": "team_mgmt", "topics": ["llm", "builtin-defaults"] })` → 显示内置提供商/模型（来自默认值）
 - `man({ "toolsetId": "team_mgmt", "topics": ["mcp"] })` → 如何管理 `.minds/mcp.yaml`（+ 模板）
-- `man({ "toolsetId": "team_mgmt", "topics": ["mcp"] })` → 如何管理 `.minds/mcp.yaml`（传输、env/headers、工具白名单/黑名单、命名转换、热重载、租赁）
+- `man({ "toolsetId": "team_mgmt", "topics": ["mcp"] })` → 如何管理 `.minds/mcp.yaml`（传输、env/headers、工具白名单/黑名单、ID 转换、热重载、租赁）
 - `man({ "toolsetId": "team_mgmt", "topics": ["mcp", "troubleshooting"] })` → 常见 MCP 故障模式及如何恢复
 - `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/knowhow/pitfalls）
-- `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → 如何管理 `.minds/skills/*`（skills 的注入位置、口吻、标题层级、迁移边界）
+- `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` → 如何管理 `.minds/skills/*`（Skills 索引 / `read_skill` 读取正文、口吻、标题层级、迁移边界）
 - `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 及常见授权模式
@@ -173,7 +173,7 @@
 - `!mcp`：
   - 解释 `.minds/mcp.yaml` 作为动态 MCP 工具集的来源
   - 解释 MCP 服务器如何映射到工具集（`<serverId>`）以及如何通过 `.minds/team.yaml` 授予这些工具集
-  - 解释工具暴露控制（白名单/黑名单）和命名转换（前缀/后缀）
+  - 解释工具暴露控制（白名单/黑名单）和 ID 转换（前缀/后缀）
   - 解释密钥/env 接线模式和问题排查（问题 + 日志、重启、热重载语义）
 - `!skills`：
   - 解释 `.minds/skills/*` 属于可复用的团队技能资产
@@ -357,13 +357,15 @@ servers:
     # headers: {}
     # sessionId: '' # 可选
 
+    # tools/prompts/resources/resource skills 的默认 ID 转换
+    transform: [] # 可选
+
     # 工具暴露控制
     tools:
       whitelist: [] # 可选
       blacklist: [] # 可选
-
-    # 工具名称转换
-    transform: [] # 可选
+      # 可选：仅 tools 的覆盖转换；显式 [] 表示 tools 不使用顶层 transform。
+      # transform: []
 
     # 可选：手册相关信息
     manual:
@@ -378,11 +380,11 @@ servers:
 
 ### 工具暴露控制（白名单 / 黑名单）
 
-使用 `tools.whitelist` / `tools.blacklist` 来减少暴露的工具表面并避免 UI 混乱。模式使用 `*` 通配符并应用于**原始 MCP 工具名称**（在转换之前），因此过滤器即使以后命名转换更改也保持稳定。
+使用 `tools.whitelist` / `tools.blacklist` 来减少暴露的工具表面并避免 UI 混乱。模式使用 `*` 通配符并应用于**原始 MCP 工具名称**（在转换之前），因此过滤器即使以后 ID 转换更改也保持稳定。
 
-### 命名转换（前缀 / 后缀）
+### ID 转换（前缀 / 后缀）
 
-MCP 服务器通常导出简短/常见的工具名称（`open`、`search`、`list`，……）。使用转换来避免全局冲突并使工具名称可识别：
+MCP 服务器通常导出简短/常见的 ID（`open`、`search`、`list`、prompt 名称、resource URI……）。使用转换来避免全局冲突并使 Dominds ID 可识别：
 
 ```yaml
 transform:
@@ -390,6 +392,12 @@ transform:
   - suffix: '_mcp'
 ```
 
+顶层 `servers.<serverId>.transform` 是该 server 派生出的所有 Dominds ID 的默认转换：
+tools、prompts、resources/resource templates、resource skills 默认都使用它。内层
+`tools.transform`、`prompts.transform`、`resources.transform`、`resources.skills.transform`
+会覆盖外层转换，不会与外层叠加。若某个 surface 要保持不转换，在该 surface 内显式写
+`transform: []`。
+
 ### Env 和 headers 接线
 
 对于 secrets，优先从主机环境复制：
@@ -512,6 +520,9 @@ members:
 
 - `.minds/skills/*` 用来承载可复用的团队技能/操作指导资产。
 - 它的重点是“什么时候用、怎么做、边界是什么”，而不是授予权限。
+- 选型原则：工作区关联强的事实、路径、局部契约与索引应进入 `personal_memory` / `team_memory` / `.minds/env*.md`；独立于工作区内容的操作方法、检查清单、触发条件与边界应进入 skill。
+- 团队协作 SOP 通常应优先做成团队共享 skill：把职责、阶段、输入输出、升级条件和同步节奏抽象成可迁移规程；当前工作区的具体路径、成员绑定、工具绑定只作为 memory/env/team.yaml 里的绑定事实。
+- 若某个经验同时包含通用方法与当前 rtws 事实，应拆开维护：skill 写通用步骤，memory/env 写当前仓库路径、命令入口与局部契约，避免 skill 成为隐蔽的过期事实仓库。
 - 如果某个 skill 需要脚本、专有工具、MCP、外部二进制、或稳定复用的执行能力，那么设计上通常更适合上升为 Dominds app / toolset / teammates contract，而不应只停留在 markdown 文案。
 - 设计文档在这里仅说明边界与迁移方向；具体文件命名、注入位置、标题层级、语言文件选择等，以运行时 `man({ "toolsetId": "team_mgmt", "topics": ["skills"] })` 为准。