docs: give architecture review rules a per-artifact home
Move `docs/defensive-patterns.md` into `docs/defensive-patterns/`, one page per artifact plus a README router, and state each rule as its requirement, the condition a reviewer judges it by, its boundary and approver, and a correct and a wrong example. - `general.md` (the moved page): the existing bug-class rules plus timing, value representation, shared-state ownership, decentralization, performance evidence, and migrations. - `package-surface.md`, `remote-and-api.md`, `client-components.md`, `conversation-and-session.md`: the review requirements for those artifacts, linking type definitions and semantics to `docs/subsystems/` instead of restating them. - `README.md`: the habits behind the rules and the route from artifact to page. - `dsh-code-review` reads the owning pages before judging a diff; the `dsh-architecture-discipline` routing skill is retired in favour of the directory, and every inbound reference is repaired. - Chinese counterparts, pairing records, and the documentation tier table are updated together.
This commit is contained in:
1 parent
23c29d067a
commit
73dbbb751c
53 files changed
+3045
-129
No files matched your search
@@ -16,7 +16,7 @@
|
||||
zh: 787ad4d04b79adaf
|
||||
/conversation-assembly/replayable-event-families:
|
||||
en: c216e2df128b8cb9
|
||||
zh: e61312f1f280332d
|
||||
zh: c039cf84b0d86ad8
|
||||
/conversation-assembly/definition-and-typed-chat-payload:
|
||||
en: 5f24557a050d1df0
|
||||
zh: 47735627f802b6fa
|
||||
|
||||
@@ -71,6 +71,8 @@ Group 存储在安装前校验完整提交结果:根 Group 引用与记录一
|
||||
|
||||
实时 Assistant delta 作为 Client-only `assistant/live-chunk` event 到达。重连 baseline 会把活跃的进程内紧凑 stream 展开为相同的瞬态 event,持久 `assistant/message` 与 `assistant/attempt` event 则嵌入完整紧凑 stream 供历史回放。瞬态 event 可以初始化 Context。每条工具 delta 和后续 `tool/call` 都可以按同一个 callId 匹配为 start,即使名称尚未到达;只有最早的 Match 调用 `start()`,后续 Match 调用 `update()`。准备态 Tool 节点只有在名称可用后才显示。历史分页不把已结束消息展开为实时 delta。消费 Assistant 输出的 Definition 通过同一组匹配和更新接口处理 live chunk 与持久 settlement,其他 Definition 直接返回 `null`,无需展开 stream。
|
||||
|
||||
<a id="definition-and-typed-chat-payload"></a>
|
||||
|
||||
## Definition 与类型化 Chat payload
|
||||
|
||||
为了完整展示关联关系,下面把生产方声明和 Client 贡献写在同一个代码块里。实际的包族中,branded id 与 `SessionEventMap` 声明留在事件生产方,Definition、Chat data 合并与 renderer 留在 Client 插件。
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
zh: d0f66664ac85ae64
|
||||
/core/tooldefinition:
|
||||
en: d926a9b80aada2e5
|
||||
zh: e34e6f43bdfd8920
|
||||
zh: 7e191ba5dab904df
|
||||
/core/repo-wide-type-patterns:
|
||||
en: 057db6d8bf356c0f
|
||||
zh: 1441b39e5142b0bf
|
||||
|
||||
@@ -363,6 +363,8 @@ type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
|
||||
|
||||
其完整字段、`defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` 类型化 schema DSL、`ToolExecution`/`ToolExecutionResult` waterfall 类型,以及工具展示 UI 类型都在 **[tools.md](tools.zh.md)** 中。
|
||||
|
||||
<a id="repo-wide-type-patterns"></a>
|
||||
|
||||
## 全仓通用类型模式
|
||||
|
||||
两个模式在每个子系统中反复出现,只在此处记录一次。
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
en: 182147ddf388c600
|
||||
zh: c0a7d77602c78bcd
|
||||
/ptc-runtime/captured-output-and-the-failure-taxonomy:
|
||||
en: e5431173436c00c2
|
||||
zh: 4ba58e259bbadbc8
|
||||
en: 8eb1607888ab6efc
|
||||
zh: 580c852d17b9413f
|
||||
/ptc-runtime/the-service:
|
||||
en: a82f828fa006c7e9
|
||||
zh: 2279d36867335b57
|
||||
@@ -168,12 +168,12 @@ type PtcBindingFunction = (args: unknown) => Promise<PtcJsonValue>
|
||||
|
||||
Logs are plain strings. Each source channel preserves emission order, while interleaving across independent channels is backend-dependent because channel metadata is not part of the seam. The runtime captures the program's console and stream output, and consumers render only the text. Implementations cap the serialized outer log-array plus completion-value or failure-message payload; fixed result-envelope syntax and consumer presentation whitespace are not part of that variable-payload ledger. Overflow is an explicit failure rather than in-band value substitution.
|
||||
|
||||
Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](../defensive-patterns.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
|
||||
Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](../defensive-patterns/general.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
|
||||
|
||||
```ts type-equiv
|
||||
/**
|
||||
* Why a run failed. The kinds are orthogonal outcomes reported independently
|
||||
* (per docs/defensive-patterns.md): a budget expiry is not an exception, an
|
||||
* (per docs/defensive-patterns/general.md): a budget expiry is not an exception, an
|
||||
* abort is not a timeout, and a substrate death is neither.
|
||||
*
|
||||
* - `'exception'` — the program threw or failed to parse/transform.
|
||||
|
||||
@@ -168,12 +168,12 @@ type PtcBindingFunction = (args: unknown) => Promise<PtcJsonValue>
|
||||
|
||||
日志是纯字符串。每个来源通道保留自身的发出顺序;由于通道元数据不属于 seam,相互独立的通道如何交错由后端决定。运行时捕获程序的 console 与流输出,Consumer 只渲染文本。实现会对序列化后的外层日志数组,以及完成值或失败消息的组合载荷设置上限;固定的结果封装语法与 Consumer 展示空白不计入这份可变载荷计量。超限会显式失败,而不会在值中插入替代内容。
|
||||
|
||||
失败类型是**正交的结果,独立报告**(见 [defensive-patterns](../defensive-patterns.zh.md)):预算耗尽不是异常,中止不是超时,基底崩溃(如 OOM)也不是二者中的任何一个:
|
||||
失败类型是**正交的结果,独立报告**(见 [defensive-patterns](../defensive-patterns/general.zh.md)):预算耗尽不是异常,中止不是超时,基底崩溃(如 OOM)也不是二者中的任何一个:
|
||||
|
||||
```ts type-equiv
|
||||
/**
|
||||
* Why a run failed. The kinds are orthogonal outcomes reported independently
|
||||
* (per docs/defensive-patterns.md): a budget expiry is not an exception, an
|
||||
* (per docs/defensive-patterns/general.md): a budget expiry is not an exception, an
|
||||
* abort is not a timeout, and a substrate death is neither.
|
||||
*
|
||||
* - `'exception'` — the program threw or failed to parse/transform.
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/scope.md
|
||||
/scoped-registration:
|
||||
en: b786b68190a93d3f
|
||||
zh: 8ea0fb2fac9a1529
|
||||
zh: d487dc4263d61a53
|
||||
/scoped-registration/identity-and-dispatch-carrier:
|
||||
en: f4e1bdd96c43a845
|
||||
zh: c74409f7f81bd0e0
|
||||
|
||||
@@ -6,6 +6,8 @@
|
||||
|
||||
源码:[`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts) 与 [`packages/core/scope/src/store.ts`](../../packages/core/scope/src/store.ts)。
|
||||
|
||||
<a id="identity-and-dispatch-carrier"></a>
|
||||
|
||||
## 身份标识与分发载体
|
||||
|
||||
`ScopeKey` 是一个不透明的对象身份标识。已交付的 agent loop(智能体循环)使用活跃的 `Agent` 对象作为自身的 key,但该原语从不检视该对象。
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
zh: 441ed13ff3f81d2a
|
||||
/web-client-slots/cardinality-and-scope:
|
||||
en: 5b0ada069239576b
|
||||
zh: 7e71ced7f17d78a6
|
||||
zh: 84e1e6b253d1461e
|
||||
/web-client-slots/component-inputs:
|
||||
en: 9cb70abb2e39b958
|
||||
zh: cd4b6f1705d90e17
|
||||
@@ -22,7 +22,7 @@
|
||||
zh: b961f792052b4ce5
|
||||
/web-client-slots/current-hierarchy:
|
||||
en: 8a4cc4b8608ce0f6
|
||||
zh: 21281dcf047503b2
|
||||
zh: 7dcc51b213782a40
|
||||
/web-client-slots/extension-rules:
|
||||
en: b2cce357141883ee
|
||||
zh: 278080a5fb941189
|
||||
@@ -61,6 +61,8 @@ Slot 声明固定两个相互独立的维度。
|
||||
|
||||
对于 `single`、`list` 和 `keyed` cell,`priority` 是遮蔽优先级;对于 `chain`,它是选举顺序。数值越小越先运行或渲染。普通增量贡献应选用新的 list `id` 或 keyed `key`;复用已有 cell 表示有意替换其展示。
|
||||
|
||||
<a id="component-inputs"></a>
|
||||
|
||||
## 组件输入
|
||||
|
||||
注册组件会在 binding 位置收到组装后的输入。组件应从这些类型推导 props,不要重新抄写成员。
|
||||
@@ -195,6 +197,8 @@ root
|
||||
|
||||
生成的 Client inspect catalog 是每个 key 的完整参考,包含 cardinality、scope、owner props、标准 props、当前 occupant、声明 owner 与替换风险。运行中的动态包可以用 `cordis_inspect what:"client"` 查询实时树与某个精确 key;源码 catalog 由 `pnpm run gen-client-catalog` 根据 `SlotMap` 声明和 `slots.register()` 调用点生成。
|
||||
|
||||
<a id="extension-rules"></a>
|
||||
|
||||
## 扩展规则
|
||||
|
||||
- 另一个功能包只能通过 `import type` 引入声明;绝不导入或转发它的运行时值。
|
||||
|
||||
Reference in new issue
Block a user