docs: reserve seam for complete capabilities

docs/user/develop/practice/index.zh.md

@@ -1,25 +1,25 @@
-# 能力的三层拆分
+# 能力的三种角色设计
 
 [English](index.md) | 中文
 
-本文分为两部分：先参考三层能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
+本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
 
 ## 概念参考
 
-当一项能力足够通用，需要支持可替换的实现时（例如 Bash 执行），Harness 会将其拆成三个包：**接口**、**实现**和**消费方**。这样便可独立替换其中任何一层。
+当一项能力足够通用，需要支持可替换的提供方时（例如 Bash 执行），Harness 会区分三种角色：**Service Definition**、**Service provider** 和 **Consumer**。角色需要独立演进或替换时，将它们放入不同包；否则一个包可以承担多个角色。完整能力构成其 seam。任何单一角色都不是 seam。
 
 ## 以 Bash 为例
 
 以 Bash 执行能力为例：
 
-- **接口** (`dsh-bash`)：定义 Bash 请求和结果的结构
-- **实现** (`dsh-bash-local`)：在本地计算机上执行命令
-- **消费方** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
+- **Service Definition** (`dsh-bash`)：定义 Cordis 服务以及 Bash 请求／结果词汇
+- **Service provider** (`dsh-bash-local`)：提供本地命令执行
+- **Consumer** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
 
 ```
 ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
 │  dsh-bash   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
-│ (interface) │     │ (implementation) │     │(consumer/tool)│
+│(definition) │     │    (provider)     │     │(consumer/tool)│
 └─────────────┘     └──────────────────┘     └──────────────┘
        ▲                                            │
        └────────────────────────────────────────────┘
@@ -28,36 +28,36 @@
 
 ## 拆分的好处
 
-### 具体实现可替换
+### 提供方可替换
 
-同一个接口可以有多种实现。用户通过 `cordis.yml` 选择：
+同一个 Service Definition 可以有多个提供方。用户通过 `cordis.yml` 选择：
 
 ```yaml
 # Local execution
 - name: '@deepseek-ai/dsh-bash-local'
 
-# Replace this row with another package that implements the same service.
+# Replace this row with another package that provides the same service.
 ```
 
-更换实现时，接口和工具均保持不变。
+更换提供方时，Service Definition 和工具均保持不变。
 
 ### 独立演进
 
-- 接口定义稳定后很少改动
-- 实现可以独立优化（性能、安全）
-- 消费方可以调整能力向模型呈现的方式。
+- Service Definition 的约定稳定后很少改动
+- Service provider 可以独立优化性能和安全性
+- Consumer 可以调整能力向模型呈现的方式。
 
 ### 依赖解耦
 
-- 实现依赖接口。
-- 消费方依赖接口。
-- 实现和消费方**互不依赖**。
+- Service provider 依赖 Service Definition。
+- Consumer 依赖 Service Definition。
+- Service provider 和 Consumer **互不依赖**。
 
 当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.md)负责。
 
-## 教程：开发三层能力
+## 教程：开发三种角色的能力
 
-### 第一步：定义接口
+### 第一步：编写 Service Definition
 
 ```ts ignore-check
 // packages/my-cap/my-cap/src/index.ts
@@ -87,7 +87,7 @@ export interface MyCapResult {
 }
 ```
 
-### 第二步：编写实现
+### 第二步：编写 Service provider
 
 ```ts ignore-check
 // packages/my-cap/my-cap-local/src/index.ts
@@ -96,7 +96,7 @@ import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/
 
 class MyCapLocal extends MyCapService {
   async execute(request: MyCapRequest): Promise<MyCapResult> {
-    // Concrete implementation.
+    // Local provider behavior.
     return { output: request.input.toUpperCase() }
   }
 }
@@ -146,10 +146,10 @@ export function apply(ctx: Context) {
 
 ## 设计要点
 
-- **不要预防性拆分**：只有确实需要可替换实现时，才拆分为三个包。简单的工具插件无需拆分。
-- **接口拥有 Request/Result 类型**：实现和消费方只依赖接口包。
+- **不要预防性拆分**：只有角色需要独立演进时，才使用不同包。简单的工具插件无需拆分。
+- **Service Definition 拥有 Request/Result 类型**：Service provider 和 Consumer 只依赖 Service Definition 包。
 - **显式优于隐式**：实现应通过显式的 `resolve(request): Spec` 步骤处理默认值，而不是在 `run()` 中隐藏 `?? default`。
 
 ## 下一步
 
-- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 后端，这是一种常见的能力 seam 扩展
+- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 提供方