docs(agent): describe unified workspace capabilities

Document skill mounts, prompt catalogs and migration boundaries. Retain the JavaScript capability and kit references while removing obsolete executor details.
2026-10-19 15:45:12 +00:00 · 2026-09-20 19:59:31 -04:00 · 2026-09-20 19:59:31 -04:00 · 8d12ac646c
commit 8d12ac646c
parent 44bbd2a25e
12 changed files with 75 additions and 58 deletions
--- a/docs/API/Agent.md
+++ b/docs/API/Agent.md
@ -27,6 +27,8 @@ const unsubscribe = agent.subscribe(run.runId, event => {

 两种方法返回 `{ runId, status, workspaceId, stableChatId, generationType }`。准备好的 snapshot 需要包含 `contextPolicy` 与 `chatCompletionPayload`；独立预设和后续 Invocation 组装还会使用 `frozenRunInputSnapshot`。工具由 runtime 配置，输入消息应是尚未进入工具循环的初始提示词。组装过程见 [Prompt assembly](../Agent/PromptAssembly.md)。

+自行组装 snapshot 时，`agentSystemPrompt` 消息须以字符串 `content` 保存正文，并携带 `_tauritavern_prompt_component: "agentSystemPrompt"`，供 runtime 追加目录。PromptManager 自动提供该标记，标记不会发送给模型。
+
 ## 控制与订阅

 | 方法 | 行为 |
@ -46,6 +48,8 @@ const unsubscribe = agent.subscribe(run.runId, event => {

 传入 `revisionGuidance` 时，从已完成的 checkpoint 开始新的前台 Invocation，继承上下文并使用原 Profile 的预算。聊天命令 `/fix 修改要求` 使用这一入口，原地修改最后一条 Agent 回复的当前 swipe，以当前已保存的正文为基准。

+v1 checkpoint 仅支持查看状态和修订已完成的 Run；首次修订时转换，范围见 [运行循环](../Agent/Runtime.md#checkpoint-与恢复)。
+
 ## 历史与详情

 ```js
@ -97,6 +101,8 @@ const { events, timelineProjection } = await agent.readEvents({

 Profile 的用法见 [配置指南](../Agent/ProfilesAndPreset.md)。`tools.list()` 返回稳定工具 ID、描述和参数 schema；模型调用名称属于 Invocation 快照。

+`profiles.resolveSystemPrompt` 返回 Profile 指令正文；运行时目录的追加规则见 [Prompt assembly](../Agent/PromptAssembly.md#skill-与-agent-目录)。
+
 ## 保留策略

 ```js
--- a/docs/API/Skill.md
+++ b/docs/API/Skill.md
@ -24,7 +24,7 @@ const installed = await skill.list();

 作用域有 `global`、`preset`、`profile`、`character`，省略时按全局处理。完整结构见 [src/types.d.ts](../../src/types.d.ts) 的 `TauriTavernSkillScope`。

-文件路径相对于 Skill 包。`readFile` 省略范围时读取全文，较长内容返回行预览和 `nextStartLine`，供调用方续读。`writeFile` 的 SHA 不匹配时返回错误。
+文件路径相对于 Skill 包。`readFile` 返回原文与原始 SHA，不展开宏；省略范围时读取全文，较长内容返回行预览和 `nextStartLine`。`writeFile` 的 SHA 不匹配时返回错误。

 ## 选择导入来源

@ -73,4 +73,4 @@ type SkillImportInput =

 同一宿主一次处理一批导入。单项安装不会释放来源；整批结束或取消后，调用方须等待进行中的请求完成，再调用 `discardPickedImport()`，成功或失败均需清理。

-模型在 Run 中通过 `skill.list`、`skill.read`、`skill.search` 和 `skill.run_script` 使用已安装内容，运行过程见 [Agent 工具](../Agent/ToolSystem.md)。
+Agent 通过只读 `skills/<name>/` 视图和 `workspace.shell` 使用安装包，见 [Skill](../Agent/Skill.md)。
--- a/docs/Agent/ProfilesAndPreset.md
+++ b/docs/Agent/ProfilesAndPreset.md
@ -80,11 +80,13 @@ Profile 面板中的 Model Target 会物化为 LLM Connection。连接的端点

 调用方开启 `delegation.canDelegate` 或 `canHandoff`，并允许相应工具。接收方开启 `callable`，再按用途选择 `allowAsSubagent` 或 `allowAsHandoffTarget`；`allowedCallers` 指定可调用它的 Profile，`["*"]` 表示所有调用方。

-`descriptionForAgents` 用于向其他 Agent 介绍它适合处理什么工作。并发、任务数量和交接深度也在 `delegation` 中设置。完整流程见 [多 Agent 协作](SubAgent.md)。
+`descriptionForAgents` 说明适合处理的工作，未填写时使用 `description`。并发、任务数量和交接深度也在 `delegation` 中设置。完整流程见 [多 Agent 协作](SubAgent.md)。

 ## 源码

-Profile 以 JSON 保存到 `_tauritavern/agent-profiles/profiles/`，当前 schema 版本为 3。
+Profile 以 JSON 保存到 `_tauritavern/agent-profiles/profiles/`，当前 schema 版本为 4。
+
+schema 1–3 在加载或导入时自动迁移，移除旧 `skill.*`、`agent.list` 工具配置及 Skill 读取预算；保留其余配置，不自动授予新权限或重写指令。

 - [profile.rs](../../src-tauri/crates/tt-domain/src/models/agent/profile.rs)：字段与默认值。
 - [agent_profile_service](../../src-tauri/crates/tt-application/src/services/agent_profile_service)：默认配置、解析和验证。
--- a/docs/Agent/PromptAssembly.md
+++ b/docs/Agent/PromptAssembly.md
@ -30,6 +30,12 @@ Agent 继续使用 SillyTavern 的 PromptManager 组装提示词。Rust 解析 P

 `agentSystemPrompt` 是 Profile 指令在 PromptManager 中的位置，`agentTask` 是委派或交接任务的位置。Preset 控制组件的位置和 role，runtime 消费最终组装好的消息。

+## Skill 与 Agent 目录
+
+Runtime 准备 Invocation 时，将 Skill 与可调用 Agent 目录追加到 `agentSystemPrompt` 正文末尾。默认和自定义指令使用同一流程，保留预设的位置与 role；后续轮次和恢复沿用已准备请求。
+
+Skill 目录与文件视图使用同一份有效绑定；Agent 目录由实际工具与目标调用资格决定。规则分别见 [Skill](Skill.md) 和 [多 Agent 协作](SubAgent.md)，手工 snapshot 的组件标记见 [API](../API/Agent.md)。
+
 ## 预设与连接各管什么

 Preset 提供提示词布局和生成设置。Profile 的 model binding 提供最终 source、model、endpoint、secret 和路由；这些连接字段会覆盖预设中的旧值。
--- a/docs/Agent/Runtime.md
+++ b/docs/Agent/Runtime.md
@ -6,7 +6,7 @@

 前端生成入口读取当前聊天、世界书激活结果、宏和连接设置，形成 `FrozenRunInputSnapshot`。PromptManager 根据 Profile 与预设生成初始消息，Host API 把结果交给 `AgentRuntimeService`。

-Runtime 创建 Run，初始化工作区，保存输入和解析后的 Profile，再准备根 Invocation。此时会确定该 Invocation 的模型请求、工具集合、可用 Skill 与工作区范围。后续修改 UI 设置不会改写已经准备好的 Invocation。
+Runtime 创建 Run，初始化工作区，保存输入和解析后的 Profile，再准备根 Invocation。此时会确定该 Invocation 的模型请求、工具集合、可用 Skill、可调用 Agent 目录与工作区范围。后续修改 UI 设置不会改写已经准备好的 Invocation。

 `startRunFromLegacyGenerate()` 负责从当前聊天取得输入；`startRunWithPromptSnapshot()` 接受已经组装好的输入。两者进入相同的 Rust runtime。具体参数见 [API](../API/Agent.md)，提示词的生成过程见 [Prompt assembly](PromptAssembly.md)。

@ -37,7 +37,9 @@ Shell 取消须先等待已启动的文件修改收尾，再记录结果并进

 每次执行结束时保存 checkpoint，由 runtime 的执行状态与宿主的消息呈现共同构成。中断后的续接沿用原 Run、冻结输入和工作区，保留已确认结果与累计预算。

-`/fix 修改要求` 用于修改最后一条已完成 Agent 回复的当前 swipe。当前正文保存到 `output/previous_output.md`，作为包含手工编辑的修改基准。新的前台 Invocation 继承上一前台的完整上下文，在原 Run 中获得正常预算；原提交记录与工作材料继续保留。
+当前 checkpoint schema 为 2。v1 可只读查看状态，仅已完成的 Run 在首次 `/fix` 时转换；未完成的 v1 Run 需要重新开始。转换保留原权限、Skill 绑定与执行结果，将含退役工具调用的轮次转为历史文本，并通过修订说明补入新用法与目录。原始记录不改写，旧调用不重放。
+
+`/fix 修改要求` 用于修改最后一条已完成 Agent 回复的当前 swipe。当前正文保存到 `output/previous_output.md`，作为包含手工编辑的修改基准。新的前台 Invocation 继承上一前台的上下文，在原 Run 中获得正常预算；原提交记录与工作材料继续保留。

 恢复时仅按需校验所选 Run 的本地保存材料，不依赖同步状态或其他 Run。该 Run 在本进程中仍活跃、材料缺失或不匹配、外部副作用无法确认时拒绝本次恢复；可恢复的保存错误允许重试。恢复与清理须互斥，已确认的工具和提交效果不得重放。

--- a/docs/Agent/Skill.md
+++ b/docs/Agent/Skill.md
@ -31,21 +31,19 @@ Skill Manager 可从目录或 ZIP 递归发现 Skill，逐项预览和安装；

 Skill 可以属于全局、预设、Profile 或角色。运行时按 `global → preset → profile → character` 解析，同名 Skill 由靠后的作用域覆盖，再按 Profile 的 `skills.visible` 和 `deny` 筛选。

-子 Agent 使用目标 Profile 的 Skill 配置；角色与当前预设等环境信息来自 Run 冻结的输入。这样同一名称可以在某个角色或 Profile 中提供更具体的工作方法。
+子 Agent 使用目标 Profile 的 Skill 配置，环境信息来自 Run 冻结输入。同名 Skill 可在不同 Invocation 中绑定到不同作用域。绑定在准备时确定，后续轮次与恢复沿用；读取使用安装包当前内容，缺失时失败，不改选其他同名包。

 ## 在运行中使用

-模型先通过 `skill.list` 查看索引，使用 `skill.read` 阅读正文，或用 `skill.search` 查找片段。读取支持行范围，长文返回预览和续读位置。
+有效 Skill 的名称、描述和 `SKILL.md` 路径随系统提示词提供，见 [Prompt assembly](PromptAssembly.md)。模型通过工作区文件工具读取 `skills/<name>/SKILL.md` 及支持材料；相对引用以 Skill 目录为起点，Shell 中 `/skills/<name>/` 指向同一视图。

-普通 Skill 文本会展开本次输入冻结的宏，脚本源码保持原文。已安装文件供模型读取，需要摘录或修改的内容写入工作区。模型显式调用 `skill.run_script` 时才会执行包内脚本。
+`skills/` 只读。普通 UTF-8 文本展开 Run 冻结宏，`scripts/` 下的源码和非 UTF-8 文件保持原样；读取、文件大小与复制使用同一内容视图，文本搜索报告跳过数量。需要编辑或发布的材料先复制到普通工作目录，见 [Workspace](Workspace.md)。

-宿主侧的管理接口是 `api.skill`，包括预览、安装、编辑、移动、导出与删除，见 [Skill API](../API/Skill.md)。
+安装包由 `api.skill` 管理，管理读取与编辑使用原始内容，见 [Skill API](../API/Skill.md)。

 ## 运行脚本

-本节描述现有 `skill.run_script`，暂保留快照写回协议。普通工作区 JavaScript 见 [Workspace](Workspace.md#javascript)。
-
-`scripts/` 中的 JavaScript 可以处理文件、计算或生成材料。例如 `scripts/list-scenes.js`：
+通过 `workspace.shell` 执行包内脚本。例如 `scripts/list-scenes.js`：

 ```js
 import { workspace } from '@tauritavern/runtime';
@ -58,41 +56,41 @@ export default function ({ path }) {
 }
 ```

-模型通过 `skill.run_script` 调用：
+Shell 命令：

-```json
-{
-  "skill": "scene-review",
-  "script": "list-scenes",
-  "args": { "path": "output/main.md" }
-}
+```sh
+js --call default --args-json '{"path":"output/main.md"}' /skills/scene-review/scripts/list-scenes.js
 ```

-`script` 对应 `scripts/<name>.js`，名称使用小写字母、数字和连字符。入口导出 `default(args)` 或 `main(args)`，同时存在时使用 `default`。返回值为可序列化的 JSON；没有内容时返回 `null`，较大正文写入文件并返回路径。
+导出 `main` 时使用 `--call main`。脚本遵循统一的工作区与 Shell 语义，见 [JavaScript](Workspace.md#javascript)；命令选项见 `js --help`。

 ### 可用能力

-每次调用在独立 QuickJS 环境中执行，宿主能力从 `@tauritavern/runtime` 导入。标准 JavaScript 和脚本内部可完成的 `async` / `await` 可用；环境不提供网络、进程、Node、DOM 或定时器 API。
+脚本在 QuickJS 中执行，支持 ES 模块和 `async` / `await`，不提供 Node/Deno 标准库、DOM、网络、子进程或定时器。宿主能力从统一模块导入：
+
+```js
+import { workspace, context, macros, log } from '@tauritavern/runtime';
+```

 | 接口 | 用途 |
 | --- | --- |
-| `workspace.readText(path)` | 读取 UTF-8 文件，返回字符串 |
-| `workspace.writeText(path, text)` | 写入文件，自动创建父目录 |
-| `workspace.listFiles(path?)` | 无参数时列出可见顶层条目；指定目录时返回相对于该目录的文件路径 |
-| `workspace.exists(path)` | 查询文件或目录，可见范围外返回 `false` |
+| `workspace.readText(path)` | 读取 UTF-8 文本 |
+| `workspace.writeText(path, text)` | 创建或替换文件，自动创建父目录 |
+| `workspace.listFiles(path?)` | 无参数时列出工作区根目录；指定目录时递归列出文件，返回相对于该目录的路径 |
+| `workspace.exists(path)` | 检查可访问路径是否存在 |
 | `context.worldInfo.entries` | Run 启动时激活的世界书 |
 | `context.variables.local` / `global` | 保留原始 JSON 类型的 SillyTavern 变量 |
-| `context.macro` | 冻结的名称、角色、聊天位置等宏数据 |
-| `macros.render(text)` | 使用冻结值展开模板中的宏 |
-| `log.info(text)` / `warn` / `error` / `debug` | 将字符串写入宿主日志 |
+| `context.macro` | 冻结的名称、角色和聊天位置等宏数据 |
+| `macros.render(text)` | 使用 Run 冻结值展开宏 |
+| `log.info(text)` / `warn` / `error` / `debug` | 将日志写入 stderr |

-路径相对于 Run 工作区，读写范围来自 Invocation 的 Profile。脚本在调用时的文件快照上工作，同一路径多次写入保留最后的内容；执行成功后按快照 SHA 写回。并发修改会报告冲突，多文件写入中途失败时会列出已写入的文件。
+文件 API 的路径相对于工作区根。`context` 是冻结输入的副本，修改它不会写回宿主；缺少所需上下文时，访问对应字段会报错。

-`context` 是当前执行的副本，修改它不会写回宿主。`macros.render()` 只展开一层，未知语法保持原文，`\{{char}}` 得到字面量 `{{char}}`；支持的宏与查询见 [frozen_macros](../../src-tauri/crates/tt-domain/src/frozen_macros.rs)。
+普通执行时，`console.log/info/debug` 输出到 stdout，`console.warn/error` 输出到 stderr。使用 `--call` 时，返回值以 JSON 写入 stdout，所有日志写入 stderr，便于后续命令处理结果。

 ### 模块与工具箱

-相对导入可以引用同一 Skill 的 `scripts/**/*.js`，例如 `import { format } from './helpers.js'`。常用库已随应用提供：
+相对 import 从导入模块所在目录解析，路径须写明 `.js` 或 `.mjs` 扩展名。以下库随应用内置，通过完整模块名导入：

 | 模块 | 用途 |
 | --- | --- |
@ -103,17 +101,15 @@ export default function ({ path }) {
 | `@tauritavern/kit/papaparse` | CSV 解析与生成 |
 | `@tauritavern/kit/slugify` | 生成适合路径或标识符的文本 |

-这些库保留各自的 API，功能仍受 QuickJS 环境限制。其他库可打包成 ESM 放入 `scripts/vendor/`，通过相对路径导入。
-
-脚本每次执行限时 30 秒，内存 32 MiB，返回值 256 KiB。模块和输入输出的具体预算见下方引擎源码。
+这些库保留各自 API，仍受上述运行环境限制。其他依赖可预先打包成兼容的 ESM 放入 `scripts/vendor/`，通过相对路径导入；运行时不安装 npm 包。内置模块清单见 [kit.rs](../../src-tauri/crates/tt-adapter-workspace-shell/src/kit.rs)。

 ## 源码

 Skill 保存在 `_tauritavern/skills/`，按作用域组织安装目录，索引位于 `index/skills.json`。

 - [SkillService](../../src-tauri/crates/tt-application/src/services/skill_service.rs)：管理与有效 Skill 解析。
- [file_skill_repository](../../src-tauri/crates/tt-adapter-storage-userdata/src/repositories/file_skill_repository)：包格式、安装、索引与文件读写。
+- [file_skill_repository](../../src-tauri/crates/tt-adapter-storage-userdata/src/repositories/file_skill_repository)：包格式、安装、索引与原始文件读写。
 - [skill_scope.rs](../../src-tauri/crates/tt-application/src/services/agent_runtime_service/skill_scope.rs)：Invocation 的作用域。
- [Skill 工具](../../src-tauri/crates/tt-application/src/services/agent_tools/skill)：模型读取和脚本调用。
- [script.rs](../../src-tauri/crates/tt-application/src/services/agent_tools/skill/script.rs)：脚本输入快照与工作区写回。
- [Skill QuickJS engine](../../src-tauri/crates/tt-adapter-workspace-shell/src/skill/engine.rs)：Skill 执行与资源预算。
+- [Skill 文件视图](../../src-tauri/crates/tt-application/src/services/agent_workspace_scope/skills.rs)：绑定路径、宏投影与目录查询。
+- [Workspace 工具](../../src-tauri/crates/tt-application/src/services/agent_tools/workspace)：模型文件操作与 Shell 调用。
+- [WorkspaceShell adapter](../../src-tauri/crates/tt-adapter-workspace-shell/src)：统一脚本执行与文件桥。
--- a/docs/Agent/SubAgent.md
+++ b/docs/Agent/SubAgent.md
@ -17,7 +17,7 @@

 ## 委派一个任务

-调用方用 `agent.list` 查看可用 Agent，然后交付任务：
+系统提示词提供可调用 Agent 的 ID、用途和支持操作，按本次工具权限及目标资格筛选。模型从目录选择 ID，再交付任务：

 ```json
 {
@ -42,7 +42,7 @@

 runtime 保存结构化结果，并生成 `summaries/<workspace-key>-result.md` 供其他 Agent 读取。调用方收到摘要、文件引用及结果中的其他字段，随后决定如何使用。已完成结果也会在后续轮次送入调用方上下文。

-委派任务使用后台执行和 `task.return` 结束方式，聊天提交由前台 Agent 负责。当前 return-mode 子 Agent 不再向下委派或交接。
+委派任务使用后台执行和 `task.return` 结束方式，聊天提交由前台 Agent 负责。当前 return-mode 子 Agent 没有委派和交接工具，因此也没有可调用 Agent 目录。

 ## 交给下一个 Agent

@ -65,10 +65,12 @@ runtime 保存结构化结果，并生成 `summaries/<workspace-key>-result.md`

 runtime 用目标 Profile 准备新的提示词和工具集合。初始聊天材料来自 Run 启动时冻结的输入，任务包通过 `agentTask` 进入提示词。调用方应在任务中写明目标、必要背景和文件路径。

-共享工作区意味着双方看到同一路径的内容。Profile 决定各自能读写哪些目录，handoff 后使用接收方的范围。共享 Run 锁协调单次文件操作；文本编辑和 Skill 写回另外使用内容 SHA 条件，避免陈旧编辑覆盖。多步读取、计算和写入可以交错。不同任务可以约定各自输出文件，再由调用方汇总。
+双方共享工作文件，各自按 Profile 获得读写范围；`skills/` 使用各自的有效绑定。不同任务可约定输出文件，再由调用方汇总；文件与并发语义见 [Workspace](Workspace.md)。

 Profile 的 `delegation` 配置控制是否可被调用、是否可委派或交接、调用来源与并发数量。返回式子任务由 scheduler 运行；Run 收尾或取消时，runtime 结束尚未完成的子任务。

+目录随已准备请求保留，调用时仍检查当前目标权限和预算。目标选择错误时，工具返回原因与该操作当前可用的候选。
+
 ## 查看与修改实现

 Timeline 使用 Invocation 和 Task 记录展示关系，用日志显示每个 Agent 的过程。`readTaskDetail({ runId, taskId, includeResult })` 按 ID 读取任务及按需结果。
--- a/docs/Agent/TestingStrategy.md
+++ b/docs/Agent/TestingStrategy.md
@ -6,12 +6,13 @@

 | 改动 | 现有入口 |
 | --- | --- |
-| Run、委派、交接、提交 | [host Agent contract tests](../../src-tauri/crates/tauritavern/src/app/contract_tests/agent_runtime) |
+| Run、目录、协作、提交 | [host Agent contract tests](../../src-tauri/crates/tauritavern/src/app/contract_tests/agent_runtime) |
 | 文件与持久版本 | [FileAgentRepository tests](../../src-tauri/crates/tt-adapter-storage-userdata/src/repositories/file_agent_repository/tests.rs)、[文件语义闭环](../../src-tauri/crates/tt-adapter-storage-userdata/src/repositories/file_agent_repository/tests/workspace_fs.rs) |
 | 模型协议与续接 | [gateway tests](../../src-tauri/crates/tt-application/src/services/agent_model_gateway/tests.rs) |
 | Host API | [agent-api-contract.test.mjs](../../tests/agent-api-contract.test.mjs) |
 | Profile、历史与 Timeline 界面 | [agent-system tests](../../src/scripts/extensions/agent-system/src) |
-| Skill 脚本 | [脚本工具 tests](../../src-tauri/crates/tt-application/src/services/agent_tools/skill/script/tests)、[旧 Skill 执行 tests](../../src-tauri/crates/tt-adapter-workspace-shell/src/skill/engine/tests.rs) |
+| Skill 文件、宏与脚本 | [host 执行闭环](../../src-tauri/crates/tauritavern/src/app/contract_tests/agent_runtime/execution.rs)、[Skill 仓储](../../src-tauri/crates/tt-adapter-storage-userdata/src/repositories/file_skill_repository/tests.rs) |
+| 旧数据迁移 | [Profile 导入](../../src-tauri/crates/tauritavern/src/app/contract_tests/profile_migration.rs)、[Run 修订](../../src-tauri/crates/tauritavern/src/app/contract_tests/agent_runtime/legacy_revision.rs) |
 | Shell / JS 文件与提交 | [host 集成](../../src-tauri/crates/tauritavern/src/app/contract_tests/agent_runtime/shell.rs) |
 | 执行与取消边界 | [JS tests](../../src-tauri/crates/tt-adapter-workspace-shell/src/javascript/tests.rs)、[收尾 tests](../../src-tauri/crates/tt-adapter-workspace-shell/src/tests.rs) |

--- a/docs/Agent/ToolSystem.md
+++ b/docs/Agent/ToolSystem.md
@ -10,7 +10,7 @@

 Invocation 使用的工具快照包含描述、参数、名称映射及预算上限，按工具目录、Profile 和结束方式创建；输出修订沿用原快照。每个 Invocation 的调用计数独立，由 `ToolRequestGate` 检查后进入内置工具或 MCP 的执行路径。

-新 Profile 默认启用 Shell；已有 Profile 和工具快照保持原工具集合。
+新 Profile 默认启用 Shell。

 ## 内置工具

@ -20,16 +20,17 @@ Invocation 使用的工具快照包含描述、参数、名称映射及预算上
 | --- | --- |
 | 读取聊天 | `chat.search`、`chat.read_messages` |
 | 读取激活世界书 | `worldinfo.read_activated` |
-| 查找和使用 Skill | `skill.list`、`skill.search`、`skill.read`、`skill.run_script` |
-| 读取文件 | `workspace.list_files`、`workspace.search_files`、`workspace.read_file` |
+| 读取工作文件与 Skill | `workspace.list_files`、`workspace.search_files`、`workspace.read_file` |
 | 修改文件 | `workspace.write_file`、`workspace.apply_patch` |
 | Shell 与数据处理 | `workspace.shell`，内含 jq、Python 与 JavaScript |
 | 发布与结束 | `workspace.commit`、`workspace.finish` |
-| 委派与交接 | `agent.list`、`agent.delegate`、`agent.await`、`agent.handoff`、`task.return` |
+| 委派与交接 | `agent.delegate`、`agent.await`、`agent.handoff`、`task.return` |
 | 掷骰 | `dice.roll` |

 聊天工具读取 Run 输入对应的历史范围；文件读取使用 1-based 行号，聊天消息索引使用 0-based。较长文本可以分段读取。完整工具集合会按 Profile 收窄，return-mode 子 Agent 使用 `task.return` 作为结束工具。

+可调用 Agent 目录随提示词提供，协作方式与错误反馈见 [多 Agent 协作](SubAgent.md)。
+
 ## 参数

 一次调用携带一组具名参数。线上要么是 JSON object，要么是它的 JSON 字符串编码，「没有参数」在各家实现里有多种等价写法（字段缺失、`null`、`""`、`"null"`、`"{}"`）。`ToolArguments` 是唯一的换算位置：先剥掉字符串编码，再用同一条规则判断，因此两种编码得到同一个参数集合，全可选参数的工具可以直接无参调用。
@ -52,7 +53,7 @@ Invocation 使用的工具快照包含描述、参数、名称映射及预算上

 MCP 提供外部工具。MCP Manager 管理服务器、发现目录和调用权限；Agent 使用已发现的工具目录，调用前由 MCP 服务确认权限。较长结果存为 `tool-results/` 下的可读文件，模型收到摘要和文件路径。配置与连接行为见 [MCP](../CurrentState/MCP.md)。

-Skill 提供按需读取的工作方法、材料和脚本。它沿用相同的工具调用路径，知识包本身的组织方式见 [Skill](Skill.md)。
+Skill 提供工作方法、材料和脚本，通过只读 `skills/` 视图与 `workspace.shell` 使用，组织与作用域见 [Skill](Skill.md)。

 ## 添加一个工具

--- a/docs/Agent/Workspace.md
+++ b/docs/Agent/Workspace.md
@ -1,10 +1,10 @@
 # 工作区

-工作区保存 Agent 可以反复处理的文件。一次 Run 拥有一份工作区；同一 Run 中的 Agent 共享文件，各自按 Profile 获得读写范围。
+工作区保存 Agent 可以反复处理的文件。同一 Run 中的 Agent 共享工作文件，各自按 Profile 获得读写范围；`skills/` 则按当前 Invocation 的有效 Skill 绑定提供只读文件视图。

 ## 文件放在哪里

-默认 Profile 使用下列目录：
+默认 Profile 的工作目录与自动可见只读目录：

 | 目录 | 用途 |
 | --- | --- |
@ -14,20 +14,21 @@
 | `summaries/` | 摘要与子 Agent 结果的可读版本 |
 | `persist/` | 本次运行的持久内容工作副本 |
 | `tool-results/` | 工具结果及较长结果的可读版本，只读 |
+| `skills/` | 当前 Invocation 的有效 Skill 安装包，只读；无绑定时为空目录 |

 模型用 `workspace.list_files`、`search_files`、`read_file` 寻找和读取材料，用 `write_file`、`apply_patch` 修改文本，或用 `workspace.shell` 批量处理文件。路径相对于工作区，例如 `output/main.md`；Shell 中的 `/output/main.md` 指向同一文件。

 文本工具替换已有文件和应用补丁时，使用读取记录和内容 SHA 检查冲突。Shell 不建立此读取记录；Shell 修改文件后，替换文件或应用补丁前需重新读取。

-工作区读取返回文件原文。脚本需要展开模板时，可以显式调用 `macros.render()`。聊天、世界书和 Skill 的读取由各自工具完成，保留原有数据来源。
+普通 Run 文件读取返回原文，脚本可用 `macros.render()` 展开模板；Skill 文件的宏规则见 [Skill](Skill.md)。聊天与世界书通过各自工具读取。

 ## 统一文件链路

-文本工具、Shell（含 Python、JavaScript）、Skill 写回与 runtime 材料统一通过 `WorkspaceFs` 访问 Run 的真实目录。`WorkspaceRepository` 负责初始化、manifest 与持久版本发布。
+文本工具与 Shell（含 Python、JavaScript）通过 `WorkspaceFs` 访问同一逻辑视图。普通文件和 runtime 材料保存在 Run 的真实目录，`WorkspaceRepository` 负责初始化、manifest 与持久版本发布；Skill 原始文件由 `SkillRepository` 读取，应用层负责绑定和宏投影。

-模型侧使用当前 Invocation 的 `ScopedWorkspaceFs`，按自己的 Profile 访问；业务根本身不可修改，`tool-results` 只读。宿主记录使用内部视图，两者共享同一文件实现。
+模型侧使用当前 Invocation 的 `ScopedWorkspaceFs`；业务根本身不可修改，`tool-results` 和 `skills` 只读。Skill 是外部挂载，不复制到 Run 目录。

-同一 Run 允许并行读取，按单次操作串行修改；CAS 的条件检查与写入在同一锁内完成。多步操作不构成事务，已成功的操作立即生效；Shell 失败或取消不回滚已完成的修改。追加使用原生 append，失败可能部分生效，不自动重放。
+Run 工作文件允许并行读取，按单次操作串行修改；CAS 的条件检查与写入在同一锁内完成。多步操作不构成事务，已成功的操作立即生效；Shell 失败或取消不回滚已完成的修改。追加使用原生 append，失败可能部分生效，不自动重放。

 ## JavaScript

@ -75,7 +76,7 @@ agent-workspaces/

 ## 提交到聊天

-模型调用 `workspace.commit` 时，runtime 读取指定的可访问文件并请求前端宿主保存。默认操作是替换本次输出楼层的正文；`append` 则将文件内容追加到本次输出。Host bridge 沿用 SillyTavern 的输出处理与保存流程，成功后把结果交回 runtime。
+模型调用 `workspace.commit` 时，runtime 读取指定的可访问 Run 工作文件并请求前端宿主保存。默认操作是替换本次输出楼层的正文；`append` 则将文件内容追加到本次输出。Host bridge 沿用 SillyTavern 的输出处理与保存流程，成功后把结果交回 runtime。

 首次显式提交前，前台运行还会展示写作进度：流式写入形成实时正文，符合条件的文本修改会自动提交为进度记录。首次显式提交成功后，后续聊天发布由显式 `workspace.commit` 控制。`workspace.finish` 仍要求前台至少完成一次显式提交。

--- a/docs/BackendStructure.md
+++ b/docs/BackendStructure.md
@ -234,7 +234,7 @@ adapter 是外层细节，但不是可以任意堆放的 common bucket。一个
 - `tt-adapter-storage-userdata` 承载长期用户数据仓储，例如角色卡、世界书、Agent workspace/profile、Skill package。它关心 data root / user data 语义，而不是泛泛的“文件”。
 - `tt-adapter-extension` 承载 third-party extension 发现、安装、版本检查、更新、分支查询/切换、删除与移动，以及 Git transport、repository 与 worktree 物化边界。扩展仓库不是普通 user data JSON。
 - `tt-adapter-media` 承载浏览器可见的 avatar/background/user media 资源契约。
- `tt-adapter-workspace-shell` 通过 `WorkspaceShell` 提供执行，经 `WorkspaceFs` 访问文件；权限、冻结上下文投影与发布策略由 application 拥有。旧 Skill 执行暂存于 `skill/`，见 [Skill](Agent/Skill.md)。
+- `tt-adapter-workspace-shell` 通过 `WorkspaceShell` 提供执行，经 `WorkspaceFs` 访问文件；权限、Skill 绑定、冻结宏投影与发布策略由 application 拥有。
 - `tt-adapter-provider-http`、`tt-adapter-mcp` 和 `tt-adapter-tokenization` 可以复用 `tt-adapter-http`，但协议/provider 规则不能下沉到通用 HTTP helper。
 - `tt-adapter-sync` 与 `tt-adapter-archive` 是独立运行时/执行器边界，Tauri UI glue 仍留在 host。

--- a/docs/FrontendHostContract.md
+++ b/docs/FrontendHostContract.md
@ -177,7 +177,7 @@

 - `api.llmConnections`：管理 Profile 引用的模型连接，见 [LLM Connection API](API/LlmConnections.md)。Profile 通过连接 ID 和模型 ID 绑定；Model Target 是界面的配置来源。

- `api.skill`：管理本地知识包的导入、编辑、作用域与导出，见 [Skill API](API/Skill.md)。模型在 Run 中通过 Skill 工具读取材料或执行脚本；安装与替换由管理界面处理。
+- `api.skill`：管理本地知识包的导入、编辑、作用域与导出，见 [Skill API](API/Skill.md)。模型通过只读 `skills/` 工作区视图读取材料，经 `workspace.shell` 执行脚本；安装与替换由管理界面处理。

 - `api.mcp`：MCP registration、只读 tool discovery、model-facing description override 与第一方 Manager user test call 的独立平台 API。Agent 与 Legacy generation 已通过内部 application seam 消费 MCP，但 MCP 不依附 Agent Mode，公开 API 仍不提供 raw model-call executor。
  - 当前为实验性的 Project Contract；详细签名见 `docs/API/MCP.md`。