Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(notes): archive low-value decision records

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-26 23:06:00 +08:00
parent 7c038f275d
commit 37140bf823
281 changed files with 1033 additions and 707 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.i18n.yaml
View File

@@ -1,6 +0,0 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# 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
2026-06-20-providerless-example-base.md: 2f41476a487775e6f9da2f113efe566e44786ff3
2026-06-20-providerless-example-base.zh.md: e767d6b3a35dcfd52194f8a59edc496b86414b6e

31
.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.md
View File

@@ -1,31 +0,0 @@
# Agent Note: Make the shared example base providerless
Status: rejected — superseded by [Extract example apps into packages](../../implemented/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-spine-demo` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.
English | [中文](2026-06-20-providerless-example-base.zh.md)
## Problem
The examples had two shared base files: `examples/base-core.yml` was providerless, while `examples/base.yml` included that core plus the real `llm-deepseek` adapter. Snapshot replay needs the providerless core with `llm-replay`, because loading the real adapter without a key throws. The normal demos need the real adapter. The result was a naming inversion: the file named `base.yml` was not the reusable base for all examples, while the true base was `base-core.yml`.
The split was understandable, but it made every config explanation longer. It also led to awkward test setup like a keyless smoke test carrying a dummy API key so an adapter could boot even though the model is not called.
## Proposal
Rename the providerless core to `examples/base.yml` and make adapter selection explicit in each concrete example. The coding and ACP real configs add a tiny `llm-deepseek` include or local block; snapshot config adds `llm-replay`. Delete `examples/base-core.yml`.
The shared base should contain only provider-neutral services and tools: `llm`, sessions, system prompt, tools, agents, invariants, bash executor, and bash tool schemas. Anything that chooses a model provider belongs at the leaf config.
## Acceptance criteria
- `examples/base.yml` is providerless.
- `examples/base-core.yml` is deleted.
- Real demo configs explicitly add the DeepSeek adapter.
- Snapshot replay config includes the same providerless base and its replay adapter.
- The [examples README](../../../../examples/README.md), example-specific READMEs, and Agent Note references stop explaining "base = base-core plus adapter".
## What we give up
Real demos lose one layer of convenience: each must opt into the adapter. That is the right default for examples, because adapter choice is the variable part and providerless wiring is the shared product core.
<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->

31
.agents/notes/rejected/architecture/2026-06-20-providerless-example-base.zh.md
View File

@@ -1,31 +0,0 @@
# Agent Note: 使共享示例基础配置与提供方无关
Status: rejected — 已由[将示例应用提取到 packages 中](../../implemented/architecture/2026-06-20-extract-example-app-packages.md)取代；后者把主干移入 `dsh-agent-spine-demo` bundle 并删除 `base*.yml` 文件，因此已不存在可重命名的共享基础 YAML。
[English](2026-06-20-providerless-example-base.md) | 中文
## 问题
示例曾有两个共享基础文件：`examples/base-core.yml` 与提供方无关，而 `examples/base.yml` 在该核心基础上加入了真实的 `llm-deepseek` 适配器。快照回放需要与提供方无关的核心配合 `llm-replay` 使用，因为在没有密钥的情况下加载真实适配器会抛出异常。常规演示则需要真实适配器。结果是命名与实际含义倒挂：名为 `base.yml` 的文件并非所有示例可复用的基础，而真正的基础反倒是 `base-core.yml`。
这种拆分可以理解，但它让每次解释配置都变得更冗长。它还导致了别扭的测试搭建方式，例如无密钥冒烟测试不得不携带一个虚拟 API key，仅仅为了让适配器能启动——尽管模型根本不会被调用。
## 提案
将与提供方无关的核心重命名为 `examples/base.yml`，让适配器选择在每个具体示例中显式声明。编码和 ACP（Agent Client Protocol）真实配置添加一小段 `llm-deepseek` include 或本地块；快照配置添加 `llm-replay`。删除 `examples/base-core.yml`。
共享基础应仅包含提供方无关的服务与工具：`llm`、会话、系统提示词、工具、agent（智能体）、不变式、bash 执行器和 bash 工具 schema。任何涉及模型提供方选择的内容都应放在叶子配置中。
## 验收标准
- `examples/base.yml` 与提供方无关。
- `examples/base-core.yml` 已删除。
- 真实演示配置显式添加 DeepSeek 适配器。
- 快照回放配置 include 同一个与提供方无关的基础，并加入其回放适配器。
- [examples README](../../../../examples/README.md)、各示例 README 及 Agent Note（agent 决策记录）引用不再解释「base = base-core 加适配器」。
## 放弃了什么
真实演示失去了一层便利：每个演示都必须显式引入适配器。对于示例而言这是正确的默认行为，因为适配器选择是可变部分，而与提供方无关的接线才是共享的产品核心。
<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->