docs(i18n): apply reviewed Chinese proofreading updates
This commit is contained in:
xjt
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md
|
||||
2026-06-20-core-data-structures-catalog.md: b793b65c7cd55a4b0fe7de97fcd8e43f7056d2ea
|
||||
2026-06-20-core-data-structures-catalog.zh.md: aec1489695f8400768c958426a9d6a8d4061db0c
|
||||
2026-06-20-core-data-structures-catalog.zh.md: 268a319b1b2779e050a88a74abcc7377b551fbca
|
||||
|
||||
@@ -40,7 +40,7 @@ Status: implemented
|
||||
|
||||
### 维护是作者的职责，门禁作为兜底
|
||||
|
||||
`verify-type-equiv` 能捕获已记录类型的*粘贴漂移*，但无法告诉你一个全新的核心类型没有被记录。因此 AGENTS.md 和 `dsh-code-review` skill（技能）已更新，要求在变更添加或重塑已记录类型时同步更新目录——门禁处理漂移，人处理新增类型。
|
||||
`verify-type-equiv` 能捕获已记录类型的*粘贴漂移*，但无法告诉你一个全新的核心类型没有被记录。因此 AGENTS.md 和 `dsh-code-review` skill（技能）已更新，要求在变更添加或重塑已记录类型时同步更新目录——门禁处理漂移，人处理新类型。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-export-jsdoc-gate.md
|
||||
2026-07-06-export-jsdoc-gate.md: 5f594cf279c07c41a96a124f1d25dbf880543718
|
||||
2026-07-06-export-jsdoc-gate.zh.md: 9d76fc494498424471c725dae68abca833ef9c45
|
||||
2026-07-06-export-jsdoc-gate.zh.md: a45c7909008a50764e5d73f6ae5943a7850e0573
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 导出接口 JSDoc 门禁
|
||||
# Agent Note: 导出 JSDoc 门禁
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -15,7 +15,7 @@ Status: implemented
|
||||
按声明类型划分的约定：
|
||||
|
||||
- 每个导出名称都需要带有非空描述文字的 JSDoc。
|
||||
- 函数类导出（函数声明；初始化器为函数或带有内联可调用标注的 const；非标识符的函数默认导出）遵循完整的函数约定，分类前会剥离包装表达式（括号、`as`/`satisfies` 类型断言、非空断言）。如果 const 声明器标注了一个具名类型（`export const f: Handler = …`），签名约定推迟到该类型自身的声明处，`@returns` 保持可选；内联的 `(x: T) => U` 标注或单调用签名字面量本身就是对外签名，适用完整约定；而混合了调用/构造签名与其他成员的字面量则直接拒绝（没有单一签名可供标签对照——请提取具名类型）。
|
||||
- 函数类导出（函数声明；初始化器为函数或带有内联可调用标注的 const；非标识符的函数默认导出）遵循完整的函数约定，分类前会剥离包装表达式（括号、`as`/`satisfies` 类型断言、非空断言）。如果 const 声明器标注了一个具名类型（`export const f: Handler = …`），签名约定推迟到该类型自身的声明处，`@returns` 保持可选；内联的 `(x: T) => U` 标注或单调用签名字面量本身就是导出签名，适用完整约定；而混合了调用/构造签名与其他成员的字面量则直接拒绝（没有单一签名可供标签对照——请提取具名类型）。
|
||||
- 导出类需要类级别的描述文字；公开方法（包括静态方法——可通过导出名称访问）遵循函数约定；公开属性和访问器需要描述文字（get/set 对由 getter 覆盖）。重载实现体免检——签名承载文档。
|
||||
- 导出接口、类型别名和枚举需要声明级别的描述文字；成员级别的强制有意推迟（承载关键成员约定的 seam 服务类已在 Cordis 门禁之下）。
|
||||
- 导出命名空间递归检查（在 ambient `declare` 命名空间内，每个成员隐式导出）；命名空间本身仅在不与同名的已文档化声明合并时才需要描述文字（Config-namespace 惯用法只需文档化插件一次）。
|
||||
@@ -24,7 +24,7 @@ Status: implemented
|
||||
|
||||
三类豁免避免门禁要求样板代码，精神与 Cordis 门禁的 `this`/`next` 豁免一致（为已豁免的名称编写文档是允许的；只有缺失才不被检查）：
|
||||
|
||||
- **继承成员。** 重写从其基类声明继承文档。新增的公开接口仍需文档：新增参数、将 protected 成员公开重写、或将基类的 void 返回改为具体类型。继承查找和推断返回值分类是门禁唯一需要类型检查器的工作；其他检查使用 AST。
|
||||
- **继承成员。** 重写从其基类声明继承文档。新增的公开 API 仍需文档：新增参数、将 protected 成员公开重写、或将基类的 void 返回改为具体类型。继承查找和推断返回值分类是门禁唯一需要类型检查器的工作；其他检查使用 AST。
|
||||
- **插件协议槽位。** 顶层的 `name`/`inject`/`reusable`/`Config` 常量和 `apply` 入口，以及插件类上的同名静态成员，属于框架协议：其形状由 Cordis 固定，模块文档注释加 `interface Config` 承载插件的真实语义。
|
||||
- **构造函数**，与 Cordis 门禁一致：插件类由框架构造，类文档承载全部说明。
|
||||
|
||||
@@ -33,8 +33,8 @@ Status: implemented
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **eslint-plugin-jsdoc**（`require-jsdoc`/`require-param`/`require-returns`）：覆盖了机械核心，但无法表达本仓库的约定。继承成员豁免需要跨包的类型解析，协议槽位和命名空间合并惯用法是 Cordis 特有的，而完整性语义（标签前描述文字、过时标签报错、汇总报告）已在 `scripts/jsdoc.ts` 中与 catalog 生成器共享。两套微妙不同的「已文档化」定义，正是本仓库「单一归属」规则所要防止的失败模式。
|
||||
- **扩展 `gen-cordis-catalog.ts`**：catalog 生成器渲染一个精选表面并守卫其新鲜度；仓库级遍历没有 catalog 可渲染。共享辅助函数、保持遍历独立，使每个门禁的职责清晰可读。
|
||||
- **强制接口/类型别名的成员文档**：推迟。这会使检查表面成倍增长，而检查对象大多只是含义直观的字段；承载关键成员约定的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
|
||||
- **扩展 `gen-cordis-catalog.ts`**：catalog 生成器渲染一个精选 API 并守卫其新鲜度；仓库级遍历没有 catalog 可渲染。共享辅助函数、保持遍历独立，使每个门禁的职责清晰可读。
|
||||
- **强制接口/类型别名的成员文档**：推迟。这会使检查范围成倍增长，而检查对象大多只是含义直观的字段；承载关键成员约定的 seam 服务类已有门禁。如果评审中出现成员文档漂移再重新考虑。
|
||||
|
||||
## 后果
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-06-node-engine-floor.md
|
||||
2026-07-06-node-engine-floor.md: 4d24a861bfa1a27b5aa4e07da1ed21452c7be566
|
||||
2026-07-06-node-engine-floor.zh.md: e2ef7a99a8c3045b00f4980953f0adbe4a788cfb
|
||||
2026-07-06-node-engine-floor.zh.md: 6d693aa43ed96c94917eca573afa7f1beca5c569
|
||||
|
||||
@@ -19,7 +19,7 @@ Status: implemented
|
||||
|
||||
这些源码特性在 22.x 线上于 **22.18** 全部就绪，但已安装的 Pi 适配器依赖将宣传的 LTS 下限进一步提高。`@deepseek-ai/dsh-llm-pi-ai` 依赖 `@earendil-works/pi-ai@0.79.3`，后者的包声明 `engines.node >=22.19.0`，因此 LTS 下限为 **22.19**。24.x 分支保持 `>=24.0.0`。该不相交范围完全排除了 Node 23：Node 23.0–23.5 至少还有一个源码特性需要标志，而 23 线是非 LTS/已 EOL 的，宣传 `>=23.6` 会增加一条已终止的发布线和一条 CI 分支，而没有任何部署应当使用它。
|
||||
|
||||
`@types/node` 继续固定在 22.x 线（`^22.20.0`），以匹配 LTS 支持线：使用 Node 23+/24+/25+ 的 API 会在所有机器和类型检查门禁中导致 `tsc` 失败，而不是先编译通过，直到下限矩阵分支运行时才暴露错误。目前整个代码树针对 Node 22 类型接口的类型检查全部通过，因此固定该版本不产生任何代价。
|
||||
`@types/node` 继续固定在 22.x 线（`^22.20.0`），以匹配 LTS 支持线：使用 Node 23+/24+/25+ 的 API 会在所有机器和类型检查门禁中导致 `tsc` 失败，而不是先编译通过，直到下限矩阵分支运行时才暴露错误。目前整个代码树针对 Node 22 类型 API 的类型检查全部通过，因此固定该版本不产生任何代价。
|
||||
|
||||
## 后果
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-12-package-model-experience-contract.md
|
||||
2026-07-12-package-model-experience-contract.md: 8462cc20e8de43927cd04b73cfdb11a0c3d77336
|
||||
2026-07-12-package-model-experience-contract.zh.md: ded8c9fd940b986d9b37ad1563060b8b96e966bb
|
||||
2026-07-12-package-model-experience-contract.zh.md: 09094dc4af28aff1c3cfc63a9619a4f61d34f591
|
||||
|
||||
@@ -12,7 +12,7 @@ Status: implemented
|
||||
|
||||
每个具有面向模型或邻近模型约定的 workspace 包 README 都以规范的[模型体验章节](../../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme)收尾，位置紧邻 `## Known Limitations and Deferred Work` 之前；位于“无已知限制”允许列表中的包则以模型体验章节本身结尾。经审计确认与模型无关的通用包通过 `NO_MODEL_EXPERIENCE_SECTION` 省略该章节。
|
||||
|
||||
具有直接、条件式、有上限、生命周期、多表面或辅助模型效应的包，为每个上下文表面使用一个 H3。每个表面包含三个有序 H4 字段——`What the model sees`、`Token effect` 和 `KV Cache effect`——每个字段都以一个正文段落开头。缓存字段区分仅追加增长、稳定重复前缀、替换先前 token，以及独立模型请求；它点明由包拥有、且能在新内容追加前改变请求的每项配置、作用域、生命周期、压缩或路由变化。“Does not invalidate”表示该包保留一个已经可复用的前缀，并非承诺提供方一定能命中缓存或将其保留特定时长。由包拥有的稳定文本按原文精确引用：系统提示词正文和其他长字面量在引入它们的字段下使用带标题的 H5 加 `markdown` 围栏，通常位于 `What the model sees`；短字面量则以内联形式保留，并点名插值占位符。工具 schema 表面链接生成的[工具目录](../../../../docs/tool-catalog.md)中带锚点的章节，并且只陈述组合或配置增量；仅运行时定义解释目录为何省略它们。依赖数据和由提供方拥有的文本采用摘要。agent 范围的可见性须显式说明；当范围可隐藏提示词与 schema 中的一者而不影响另一者时，两种表面保持分离。
|
||||
具有直接、条件式、有上限、生命周期、多表面或辅助模型效应的包，为每个上下文表面使用一个 H3。每个表面包含三个有序 H4 字段——`What the model sees`、`Token effect` 和 `KV Cache effect`——每个字段都以一个正文段落开头。缓存字段区分仅追加增长、稳定重复前缀、替换先前 token，以及独立模型请求；它点明由包拥有、且能在新内容追加前改变请求的每项配置、作用域、生命周期、压缩或路由变化。“Does not invalidate”表示该包保留一个已经可复用的前缀，并非承诺提供方一定能命中缓存或将其保留特定时长。由包拥有的稳定文本按原文精确引用：系统提示词正文和其他长字面量在引入它们的字段下使用带标题的 H5 加 `markdown` 围栏，通常位于 `What the model sees`；短字面量则以内联形式保留，并点名插值占位符。工具 schema 链接生成的[工具目录](../../../../docs/tool-catalog.md)中带锚点的章节，并且只陈述组合或配置增量；仅运行时定义解释目录为何省略它们。依赖数据和由提供方拥有的文本采用摘要。agent 范围的可见性须显式说明；当范围可隐藏提示词与 schema 中的一者而不影响另一者时，两种表面保持分离。
|
||||
|
||||
没有模型上下文效应的包，或某条路径完全由另一个包渲染的包，使用验证器审计过的短格式：一句以 `None, as ` 或 `Indirectly, through ` 开头的句子，随后是一个 `KV Cache effect` H4 和一个正文段落。纯传输包和无密钥测试支持包若不创建任何进入模型的内容，就使用 none 格式。提供方后端即使会限制或过滤数据，也使用间接格式；具名子项拥有全部效应时，接线 bundle 也使用该格式。这些章节会指出贡献所在，并声明不会直接导致 KV Cache 失效，同时不重复陈述消费方。结构化章节同样只记录由包拥有的输入、变换和增量。
|
||||
|
||||
@@ -21,7 +21,7 @@ Status: implemented
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **只记录注册提示词或工具的包**：否决。后端、策略插件、适配器、持久化、作用域和压缩都会改变 token 的内容或生命周期，却不拥有面向模型的 schema。
|
||||
- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的约定；集中副本会增加又一个漂移面。
|
||||
- **从源码生成一份集中式上下文成本目录**：否决。AST 能找到注册点，但无法推断语义条件，如历史保留、输出截断、父子可见性或辅助模型边界。包 README 是实现本地的约定；集中副本会增加又一个漂移点。
|
||||
- **要求给出精确 token 数**：否决。精确数量取决于所选模型的 tokenizer、适配器序列化方式、配置和运行时数据。稳定的约定是增长形状：每请求固定、每调用条件性、保留、替换、有上限或零直接影响。
|
||||
- **使用表格**：否决。精确源码文本和条件式结果形状会使单元格密集而难以扫读。重复的小节在保留相同字段的同时，为每个上下文表面提供易读的纵向空间。
|
||||
- **允许所有零影响包省略该章节**：否决。无约束的缺失在「经审计的零影响」和「忘记写文档」之间有歧义。省略仅限于在验证器中以理由命名的模型无关通用包；模型相邻的零影响包保留一句显式说明。
|
||||
@@ -30,4 +30,4 @@ Status: implemented
|
||||
|
||||
## 后果
|
||||
|
||||
评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起请求前缀变化的位置。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文表面块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性约定保持稳定。
|
||||
评审者可以从任何面向模型或邻近模型的包开始，看到它对对话模型、子模型和辅助调用的贡献，无需重建完整插件图。token 预算工作可以区分重复请求开销和依赖数据的历史，而 cache 敏感工作可以识别仅追加路径，以及最早由包引起请求前缀变化的位置。agent 范围变更有明确的文档检查点。每当模型可见行为发生变化时，包作者都要维护一个或多个紧凑的上下文条目块，或一种已分类的短格式；经审计的通用包不携带无关的模型样板。结构化字段不承诺由提供方给出的精确 token 数或 cache 命中；测量仍取决于具体模型、提供方和工作负载，而所记录的增长、可见性和前缀稳定性约定保持稳定。
|
||||
|
||||
Reference in New Issue
Block a user