docs: rescan rebased documentation hierarchy

2026-08-05 16:16:57 +08:00
parent 012bb0a549
commit 8af3babaea
304 changed files with 1091 additions and 1983 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/develop/practice/index.md
-index.md: e197d499d7f5bd9911ea60bebf584251cd4ed915
-index.zh.md: cacf13e8b23060ea5c309d30e51d732f09c76000
+index.md: c3306725f47993aa9d3322423261a260754c1d5f
+index.zh.md: 3609cbce21e17ce9ca0a40b69999b293dee29012
@@ -2,6 +2,10 @@

 English | [中文](index.zh.md)

+This page has two parts: a concept reference for the three-layer capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
+
+## Concept reference
+
 When a capability is general enough to need replaceable implementations, such as Bash execution, Harness splits it into three packages: an **interface**, an **implementation**, and a **consumer**. Each layer can evolve or be replaced independently.

 ## Bash example
@@ -49,17 +53,9 @@ The interface and tool remain unchanged while the implementation changes.
 - The consumer depends on the interface.
 - The implementation and consumer **do not depend on each other**.

-## Built-in three-layer capabilities
+The [capability-seam reference](../../../capability-seams.md) owns the current built-in families and package links.

-| Capability | Interface | Implementation | Consumer |
-|------|-------------|------|---------------|
-| Bash | `dsh-bash` | `dsh-bash-local` | `dsh-tool-bash` |
-| Filesystem | `dsh-fs` | `dsh-fs-local` + `dsh-fs-policy` | `dsh-tool-fs` |
-| Web | `dsh-web` | `dsh-web-fetch-local` / `dsh-web-search-*` | `dsh-tool-web` |
-| Subagent | `dsh-subagent` | `dsh-subagent-spawn` / `dsh-subagent-fork` | `dsh-tool-subagent` |
-| Compaction | `dsh-compact` | `dsh-compact-basic` | The implementation consumes agent-loop extension events |
-
-## Develop a three-layer capability
+## Tutorial: develop a three-layer capability

 ### Step 1: define the interface

@@ -2,6 +2,10 @@

 [English](index.md) | 中文

+本文分为两部分：先参考三层能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
+
+## 概念参考
+
 当一项能力足够通用，需要支持可替换的实现时（例如 Bash 执行），Harness 会将其拆成三个包：**接口**、**实现**和**消费方**。这样便可独立替换其中任何一层。

 ## 以 Bash 为例
@@ -49,17 +53,9 @@
 - 消费方依赖接口。
 - 实现和消费方**互不依赖**。

-## Harness 中内置的三件套
+当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.md)负责。

-| 能力 | 接口（seam） | 实现 | 消费方（工具） |
-|------|-------------|------|---------------|
-| Bash | `dsh-bash` | `dsh-bash-local` | `dsh-tool-bash` |
-| 文件系统 | `dsh-fs` | `dsh-fs-local` + `dsh-fs-policy` | `dsh-tool-fs` |
-| Web | `dsh-web` | `dsh-web-fetch-local` / `dsh-web-search-*` | `dsh-tool-web` |
-| 子代理 | `dsh-subagent` | `dsh-subagent-spawn` / `dsh-subagent-fork` | `dsh-tool-subagent` |
-| 压缩 | `dsh-compact` | `dsh-compact-basic` | 由实现插件消费 agent-loop 的扩展事件 |
-
-## 开发你自己的三件套
+## 教程：开发三层能力

 ### 第一步：定义接口