From 096586886af57983cf8464e38d021619a3d73510 Mon Sep 17 00:00:00 2001 From: Turtle Date: Tue, 11 Aug 2026 14:04:19 +0800 Subject: [PATCH] fix(review): address terminology feedback --- .../implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml | 2 +- .../notes/implemented/testing/2026-06-19-real-api-e2e-ci.md | 2 +- docs/subsystems/README.i18n.yaml | 4 ++-- docs/subsystems/README.md | 4 ++-- docs/subsystems/README.zh.md | 4 ++-- packages/core/system-prompt/README.i18n.yaml | 2 +- packages/core/system-prompt/README.md | 2 +- packages/core/tools/tests/tools.spec.ts | 2 +- packages/plan/plan-mode/tests/plan-mode.spec.ts | 2 +- .../session/session-persistence-jsonl/tests/jsonl.spec.ts | 2 +- 10 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml index bb5886e92e..72f45e8ae3 100644 --- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.i18n.yaml @@ -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 .agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md -2026-06-19-real-api-e2e-ci.md: ffa24d8aa6eb8405c322ddd256ad33cf1d367b01 +2026-06-19-real-api-e2e-ci.md: feb5d83f087f66dfec7e1540f6b32e33656409d4 2026-06-19-real-api-e2e-ci.zh.md: c00aa6e962d9e86a9d5d5c1ccaf1001afa21ba67 diff --git a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md index ffa24d8aa6..feb5d83f08 100644 --- a/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md +++ b/.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md @@ -93,7 +93,7 @@ None of these require changing the workflow to go public; they are operational s ## Consequences -A second CI workflow and the first repo secret to maintain. The real-API suite now gates merges (pre-merge on trusted PRs, post-merge on the main branch) and runs nightly, so a real break in the agent's interaction with the external APIs in CI rather than only in a developer's local run — at the cost of real (but internally free) API calls on every trusted PR and merge. The preflight makes secret misconfiguration self-announcing instead of silently disabling the net. +A second CI workflow and the first repo secret to maintain. The real-API suite now gates merges (pre-merge on trusted PRs, post-merge on the main branch) and runs nightly, so a real break in the agent's interaction with the external API surfaces in CI rather than only in a developer's local run — at the cost of real (but internally free) API calls on every trusted PR and merge. The preflight makes secret misconfiguration self-announcing instead of silently disabling the net. The design carries a documented constraint surface: the `pull_request` trigger's key-exposure tradeoff (drop it to harden), the `if:` gate's dependence on the author-based Dependabot test, and the hard prohibition on `pull_request_target`. The going-public checklist above is the operational companion — this Agent Note is the place a future maintainer should re-read before changing the trigger set or flipping repo visibility, rather than re-deriving the fork/secret model from scratch. diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml index ebdccb923a..049d5229b0 100644 --- a/docs/subsystems/README.i18n.yaml +++ b/docs/subsystems/README.i18n.yaml @@ -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/subsystems/README.md -README.md: 560851eeda607b762456fe20c874b4497704709f -README.zh.md: 4acba4372e995b54a3bb326bec0cf9606f997773 +README.md: ee753712748d5824fd3e8b03e03616d9fa8713c7 +README.zh.md: bbddde0a494c4783744042b4b5a5f4dee7e44ffd diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md index 560851eeda..ee75371274 100644 --- a/docs/subsystems/README.md +++ b/docs/subsystems/README.md @@ -2,7 +2,7 @@ English | [中文](README.zh.md) -One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a `ctx` service or event scope backs it — a generated **Cordis surface** section carrying its service and event reference. The folder complements [architecture.md](../architecture.md), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring. +One page per subsystem of the DeepSeek Harness: what it is, the data structures it moves, and — where a `ctx` service or event scope backs it — a generated **Cordis API** section carrying its service and event reference. The folder complements [architecture.md](../architecture.md), which describes *behavior* across subsystems (the service map, the session/turn/step lifecycle, the event taxonomy); each page here is the reference for one subsystem's vocabulary and wiring. | Page | Owns | |---|---| @@ -50,4 +50,4 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures | [session-projection.md](session-projection.md) | the projection seam: `SessionProjectionMap`, the pure `ProjectionDefinition` unit, `ProjectionSnapshot`'s consistent cut, the change feed | | [telemetry.md](telemetry.md) | the outbound session-reporting capability seam: `TelemetryRecord`/`TelemetrySeverity`, the `TelemetryBackend` contract, and the `telemetry/record` redact waterfall | -> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis surface** section. +> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services and events use each page's generated **Cordis API** section. diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md index 4acba4372e..bbddde0a49 100644 --- a/docs/subsystems/README.zh.md +++ b/docs/subsystems/README.zh.md @@ -2,7 +2,7 @@ [English](README.md) | 中文 -每个子系统一页，覆盖 DeepSeek Harness 的全部子系统：它是什么、它操作哪些数据结构，以及——当它由某个 `ctx` 服务或事件作用域支撑时——一段生成的 **Cordis surface** 小节，承载其服务与事件参考。本目录与 [architecture.md](../architecture.md) 互补：后者描述跨子系统的*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；这里的每一页是单个子系统词汇与接线的参考。 +每个子系统一页，覆盖 DeepSeek Harness 的全部子系统：它是什么、它操作哪些数据结构，以及——当它由某个 `ctx` 服务或事件作用域支撑时——一段生成的 **Cordis API** 小节，承载其服务与事件参考。本目录与 [architecture.md](../architecture.md) 互补：后者描述跨子系统的*行为*（服务映射、会话/轮次/步骤生命周期、事件分类体系）；这里的每一页是单个子系统词汇与接线的参考。 | 页面 | 负责内容 | |---|---| @@ -50,4 +50,4 @@ | [session-projection.md](session-projection.md) | 投影 seam：`SessionProjectionMap`、纯函数 `ProjectionDefinition` 单元、`ProjectionSnapshot` 的一致切面、变更馈送 | | [telemetry.md](telemetry.md) | 对外会话上报能力 seam：`TelemetryRecord`/`TelemetrySeverity`、`TelemetryBackend` 约定和 `telemetry/record` 脱敏 waterfall | -> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis surface** 小节。 +> 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务与事件使用每页生成的 **Cordis API** 小节。 diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml index f9d9efd993..b1f068fa39 100644 --- a/packages/core/system-prompt/README.i18n.yaml +++ b/packages/core/system-prompt/README.i18n.yaml @@ -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 packages/core/system-prompt/README.md -README.md: e7757cda02b75f1a7a24f8f68b3c25c2f442d3d3 +README.md: cedda783d549633f5be9765a9a074e968d99500d README.zh.md: 41729cdd1cfe6ebbd86f38c15bab5c50bd6ff7d2 diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md index e7757cda02..cedda783d5 100644 --- a/packages/core/system-prompt/README.md +++ b/packages/core/system-prompt/README.md @@ -83,5 +83,5 @@ Prefix-stable while the visible schema set, rendering, and order are unchanged. - **Deployment-authored prompt text is config/composition only** — this plugin owns the global persona default, creator plugins may register agent-scoped shadows, and other sections come from the plugin that owns the fact; there is no end-user prompt-editing API. - **No escape syntax for literal `{{…}}` braces** — every complete group is interpolated against registered variables; an escape is deferred until a real prompt needs one. -- **`toolOrder` misconfiguration APIs at prompt assembly (the first turn), not at boot** — only shape violations throw at config load. +- **`toolOrder` misconfiguration surfaces at prompt assembly (the first turn), not at boot** — only shape violations throw at config load. - **Sections sharing an `order` value tie-break by registration order** — a plugin-load artifact; determinism relies on the distinct-order band convention, unlike the canonicalized tool order. diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts index 33b2a204aa..217875898d 100644 --- a/packages/core/tools/tests/tools.spec.ts +++ b/packages/core/tools/tests/tools.spec.ts @@ -2593,7 +2593,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', () expect(err.message).toBe('invalid arguments: missing required property "a"; "b" must be a number') }) - it('a schema-invalid call APIs the structured error on the result', async () => { + it('a schema-invalid call surfaces the structured error on the result', async () => { const ctx = await setup() ctx.tools.register(defineContentToolFixture({ name: 'reader', diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts index 0057eb04c2..fbc9d26f0b 100644 --- a/packages/plan/plan-mode/tests/plan-mode.spec.ts +++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts @@ -992,7 +992,7 @@ describe('exit_plan_mode', () => { expect(foldPlanMode(agent.session.events)).toBe(true) }) - it('a throwing provider APIs as the corrective isError and the mode stays plan', async () => { + it('a throwing provider surfaces as the corrective isError and the mode stays plan', async () => { const { ctx, agent } = await setupWithReview() ctx.userInteraction.registerProvider({ ask: () => { throw new Error('review aborted') } }) const result = await callExit(ctx, agent) diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts index afc6ec4131..e980006e07 100644 --- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts @@ -1465,7 +1465,7 @@ describe('SessionPersistenceJsonl: edge cases', () => { await expect(ctx.sessionPersistence.list()).rejects.toThrow(/ENOTDIR/) }) - it('per-id lookup APIs non-ENOENT storage errors', async () => { + it('per-id lookup surfaces non-ENOENT storage errors', async () => { const blocker = join(root, 'not-a-directory') await writeFile(blocker, 'x') const backend = ctx.sessionPersistence as unknown as { exists(path: string): Promise }