Skills、MCP 与编排

Sumi 将内容、能力和工作流的职责分开。这样，同一份经过审核的文档既能在浏览器中 阅读，也能被不同 MCP 客户端使用，而 MCP 服务不必依赖某个特定 Agent 运行时。

所有权边界

层	职责
Skill	判断何时应使用能力，并说明操作流程、前置条件、示例、失败处理和验证方法。
Sumi-Docs-MCP	获取有边界的本地或远程语料，并通过任一受支持传输提供四个无状态只读工具。
Agent 宿主或工作流	选择并编排工具、重试、委派、请求批准，并持有客户端会话。
Astro 与 Starlight	为人类渲染经过审核的内容，并发布显式原始语料和路由表。
经评审的 BFF 或服务	在经过设计后承载未来的浏览器凭据、授权或服务端会话。

Skill 可以告诉 Agent 何时搜索 Sumi，以及如何引用 fetch_doc 返回的页面；它不应复制 MCP 服务的解析器、路径校验、网络限制或 schema。MCP 服务不负责决定接下来运行哪个 Agent，也不保存对话状态。无状态传输不提供 Agent 记忆、checkpoint 恢复或宿主文件系统 隔离；这些能力仍由客户端宿主或经过独立评审的 controller 负责。

仓库级 Skills

仓库在 .agents/skills/ 下提供三个经过评审的项目级 Skill：

• $sumi-docs-use 选择本地、默认或已发布语料，并验证实际运行的 MCP 或 Web 进程；
• $sumi-docs-pr 分类变更、选择工程记录和验证门，并在不发布的前提下准备 Pull Request；
• $sumi-docs-audit 对仓库、架构或候选发布执行只读且绑定证据的审计，不改变本地或远程 状态。

这些 Skill 是可选的工作流路由器，不会复制 MCP 解析逻辑、保存可变状态，也不会取代 宿主的项目受信与 MCP 批准机制。

经过审阅的 docs/ 树与 catalog 是内容权威。Web 站点和 MCP 服务都是它的投影，Agent 宿主则是 MCP client。Skill 可以选择角色或工作流，但不是文档存储，也不是发现工具的 前置条件。普通文档问题应优先查询 MCP 投影；修改或核验实现行为时仍需检查源码和测试。

检索与模型训练的边界

Server 是检索基座。它的词法搜索和精确文档获取可以向 Agent host 提供上下文；当模型利用 这些上下文回答时，这属于 RAG 模式。本仓库没有 embedding 索引、向量数据库或模型权重更新。 因此微调不属于文档 freshness 路径：文档变更应发布为新的 corpus revision，并在进程重新 构建或重启后加载。

维护者 Skill

本地开发者可以在自己的全局 Agent Skill catalog 中安装可选的 $sumi-docs-maintain 角色，其触发范围必须限制在 Sumi Docs 项目家族。仓库不分发、 也不依赖这个更广泛的本地角色；Codex、Claude Code 和 VS Code 的项目 MCP adapter 提供文档查询 fallback。详见Agent 宿主集成。

修改或新增可复用集成前先建立 issue，并提供触发与明确不触发的示例、支持的宿主版本、MCP 前置配置、工作流顺序、失败行为、凭据与批准边界、确定性 eval、兼容影响和回滚方法。

如果提案改变 MCP 工具，应在服务端仓库同时更新 schema、测试、工具参考、示例和 changelog。如果它引入有状态编排、认证获取或多 Agent 控制，应先设计独立服务边界或 架构决策，而不是放进当前只读 MCP 服务。

完整仓库流程见参与贡献。