波仔
🐳 第八章 设计自己的Harness
📄 一句话概括

设计一种新能力，先定四件事：能力 id、对外提供什么、谁来提供实现、谁使用——四件事说完，接缝在哪就清楚了。

📝 本节和前面几节的关系

8.1 把需求写清了，这一节把需求里的【一种能力】展开成四个可落笔的字段。

一、四件事，一句话一件

四句都是短句，但少一句就写不出配置。

二、这三个名字对应三个角色

1.3 讲过同一能力的三个角色：定义 / 提供方 / 使用方。

三个角色分开，才是【可替换】能成立的前提——换掉提供方，定义与使用方都不用动。

三、实测：一个能力两个名字

配置树里最典型的一对：ptc-runtime 这个 id，背后的包叫 dsh-ptc-runtime-node（7.3.1）。

能力是 id，实现是包——包名后缀 -node 就是那根可以换的线。

同一种情形在 7.4.1 也出现过：四个 subagent provider，共用同一个包名，靠 provider 字段分流。

四、先定四件事的好处

四件事是设计动作，不是文档动作——写在纸上是为了写对配置。

五、动手 Demo：设计一种新能力，先定四件事

以【代码审查】为例，四件事一句话一件：

cap = {"id": "review", "provides": "只读审查 + 报告",
       "provider": "复用已有件", "consumer": "会话里的模型"}
for k, v in cap.items():
    print("  %-9s %s" % (k, v))

实跑输出：

--------------------------------------------------------------------
设计一种新能力，先定四件事
--------------------------------------------------------------------
  以【代码审查】为例，四件事一句话一件：

  要定的事         问自己             本例的答案
  ----------------------------------------------------------------
  能力 id          它叫什么名字       review（配置里的 id）
  对外提供什么     别人拿它干什么     只读看代码 + 出一份审查报告
  谁提供实现       落在哪个包         本课复用已有件，不写新包
  谁使用           被谁调用           会话里的模型，经预设装配
  ----------------------------------------------------------------

  4.2.2 讲过【一个包挂多个入口】——**四件事定完，接缝在哪就清楚了**：
  对外提供什么是契约，谁提供实现是那根可以换的线。

四件事定完，接缝在哪就清楚了：对外提供什么是契约，谁提供实现是那根可以换的线。 本课不写新包——设计一种能力不等于写一个包，复用已有件也是一种设计。 id 与包名分开，才有 7.3.1 那种【换实现不改名字】的自由。

30 秒实验

  1. 把【代码审查】换成一个你熟悉的能力，照样填四个字段。
  2. 在配置树里找一对【id 与包名不一样】的例子，说出哪根线可以换。
  3. 想想四个字段里，哪一个最容易写漏——一般是【使用方】。

常见误区

  1. 错误：设计能力就是写一个插件包。——纠正：设计能力是先定契约——本课的第五套预设只用了已有件，一行代码都没写。
  2. 错误：能力 id 随便起，反正内部用。——纠正：id 是要被人读的——它是契约的名字，将来换实现时，别的地方引用的就是这个 id。
  3. 错误：提供方和使用方是一回事。——纠正：一个是给，一个是拿——混在一起，就等于把接口和实现焊死（5.7 的 Effect／Coeffect 也是这对方向）。
自测三问（点开对答案） 1. 设计一种新能力先定哪四件事？ —— **能力 id、对外提供什么、谁来提供实现、谁使用**。 2. 为什么 id 和包名要分开？ —— 因为**能力是契约、实现是可换的线**——换掉实现，能力名一个字都不用改（7.3.1 的 `ptc-runtime` 就是例子）。 3. 设计能力一定要写新包吗？ —— 不必——**复用已有件也是一种设计**，关键是四件事说清、接缝放对层。

相关笔记