TauriTavern/docs/Agent/McpSkill.md

TauriTavern Agent MCP and Skill

本文档定义 MCP 与 Skill 在 Agent 系统中的位置。

结论：

• MCP 是独立平台集成能力，不是 Agent Runtime 本体。
• Skill 是渐进披露的文本/资源包，不是自动吞入 prompt 的大文件。
• Agent 可以消费 MCP 和 Skill，但必须经过 ToolRegistry、Policy 与 Journal；不得由 prompt 直接打开旁路。

当前状态（2026-05-02）：尚未实现 window.__TAURITAVERN__.api.mcp，MCP 也未接入 Agent tool registry。Skill 已落地 window.__TAURITAVERN__.api.skill，并已通过 skill.list / skill.search / skill.read 接入 Agent tool registry。当前 Skill 细节以 docs/Agent/Skill.md 与 docs/API/Skill.md 为准。

1. MCP 边界

MCP 模块建议提供：

McpClientService
  list_servers
  connect_server
  disconnect_server
  list_tools
  call_tool
  list_resources
  read_resource
  list_prompts
  get_prompt

Agent 消费方式：

MCP Tools     -> ToolRegistry
MCP Resources -> WorkspaceResource / ContextFrame
MCP Prompts   -> PromptComponent / Preset macro / slash command

Agent Runtime 不应建在 MCP 上。MCP server 只是外部能力来源之一。

2. MCP Host ABI

非 Agent 模式下也可以提供：

window.__TAURITAVERN__.api.mcp

用途：

• 用户在设置或工具面板中查看 server。
• 用户显式调用 tool。
• 扩展读取 MCP resource/prompt。
• Agent Mode 通过同一底层服务消费 MCP。

API 草案见 docs/API/MCP.md。

3. MCP 安全底线

必须禁止：

• Agent/Preset/角色卡/世界书直接写 MCP stdio command。
• 远端配置自动创建本地 stdio server。
• prompt 修改 MCP config 后自动 reload。
• 初期允许 MCP Sampling 自动发起模型调用。
• 未经审批调用 destructive/high-cost tool。

必须要求：

• server 来自用户设置、系统内置 allowlist 或签名/可信来源。
• command/args 对用户可见。
• per-server capability allowlist。
• per-tool approval policy。
• 所有 MCP tool call 写 journal。

4. MCP Tool Result

MCP tool result 应映射为 Agent ToolResult：

Text content        -> ToolContentBlock::Text
Image/audio/file    -> ResourceRef / FileRef
Structured content  -> structured JSON
Resource link       -> WorkspaceResource ref
Error               -> is_error = true

大结果不能直接塞进 journal；应写 resource ref。

5. MCP Resources

MCP resources 默认是 application-driven：

• 宿主决定是否读取。
• ContextAssembly 决定是否纳入 prompt。
• Profile/Preset 决定预算与可见性。

Agent 不应因为 server 暴露 resource 就自动读取全文。

6. MCP Prompts

MCP prompts 可以成为：

• PromptComponent。
• Preset macro 的来源。
• 用户显式插入的片段。

它们不应自动覆盖 TauriTavern preset，也不应绕过创作者 policy。

7. Skill 定义

Skill 是本地或扩展提供的渐进式知识包。

建议结构：

skills/
  long-form-romance/
    SKILL.md
    examples/
    assets/

当前 SKILL.md frontmatter 最小示例：

---
name: long-form-romance
description: 长篇恋爱剧情写作技巧
---

工具权限、MCP server、预算与可见性不由 Skill frontmatter 直接授予；这些能力必须进入 profile/policy/approval 体系。TauriTavern 专属 metadata 可放在可选 agents/tauritavern.json，schema 无效时应 fail-fast。

8. Skill 读取策略

Agent 默认只看到 skill 索引：

name
description

读取全文必须通过：

skill.search(name, query, path?, limit?, context_lines?)
skill.read(name, path?, start_line?, line_count?, start_char?, max_chars?)

skill.search / skill.read 是 tool call，必须写 journal。当前 skill.read 默认读取 SKILL.md，只支持 UTF-8 文本文件，并支持行/字符范围；skill.search 搜索单个可见 Skill 内的 UTF-8 文本文件并返回 snippet/ref。

9. Skill 来源

Skill 可以来自：

• 用户本地目录。
• Preset 包。
• 角色卡附带资源。
• 扩展。
• 未来 marketplace。

来源不同，信任级别不同。扩展/远端 skill 默认不应获得更高工具权限。

10. Skill 与 Workspace

当前 Skill 不挂进 Agent workspace 根，而是通过 skill.read 作为 tool result 回填模型。未来如果需要统一资源视图，可以把 Skill 表现为 read-only virtual resource：

skills/<name>/SKILL.md
skills/<name>/examples/foo.md

它必须保持 read-only。Agent 不能修改原始 skill；如果需要摘录或改写，应写入 scratch/、summaries/ 或 output/。

11. Agent Context

Skill 进入模型上下文的当前路径：

skill.list / skill.search / skill.read
  -> SkillService
  -> Agent tool result
  -> ModelRequest next turn

不要把所有 Skill 全文塞进 system prompt。

12. 当前已落地与后续

Skill 已落地：

• SkillRepository / FileSkillRepository / SkillService。
• api.skill 管理入口。
• Skill zip 导入导出；历史 .ttskill 归档保持导入兼容。
• Preset / Character embedded skill 导入确认与 source ref 清理。
• skill.list。
• skill.read。
• tool result 写 journal。

Skill 后续只补：

• profile/preset/character 控制可见 skill。
• skill content 受 read budget 限制。
• recommended skill 与 embedded skill 在 profile resolver 中合流。

MCP 最小实现应晚于内置工具系统稳定之后。