merge: refresh against the advancing master
This commit is contained in:
Huanqi Cao
@@ -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/architecture/2026-07-28-launcher-owned-resume-identity.md
|
||||
2026-07-28-launcher-owned-resume-identity.md: 167c9e848a9101c9d1e93cf3af968b00279db32b
|
||||
2026-07-28-launcher-owned-resume-identity.zh.md: 218b69581e65e8566ff1047603bb71c9537d3486
|
||||
2026-07-28-launcher-owned-resume-identity.md: da9b4571d154137d34ef3690e7b4aa9bc7bb9082
|
||||
2026-07-28-launcher-owned-resume-identity.zh.md: 51ccffd7bb9c8eeda03afe2528d3cb4250e2d906
|
||||
|
||||
@@ -10,7 +10,7 @@ Two facts a launcher owns were shipped as deployment config keys on the TUI app
|
||||
|
||||
Routing them through YAML made them silently droppable. `@cordisjs/plugin-include` applies a targeted patch by replacing whole top-level keys (`target[key] = value`), so a personal `~/.dsh/config.yaml` patching the `tui-agent` entry's `config` replaces the shipped block entirely. A user overlay written to change provider and model therefore deleted every resume key it did not restate, and nothing reported it: absent `resumeCommand` legitimately means "no fallback configured".
|
||||
|
||||
Both failures were live in one real overlay. The exit hint stopped printing, because the overlay omitted `resumeCommand`. Worse, the overlay carried `resumeSessionId: !!js process.env.RESUME_SESSION_ID` — a stale line from before [the env-var bridge was removed](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md) — which overwrote the shipped `!!js "typeof resumeSessionId === 'string' ? …"` intake with a read of a variable nothing sets. `dsh --resume <valid-id>` then started a *fresh* session and said nothing, reproduced directly: the banner showed a newly minted id, not the requested one. The [`dsh experimental-meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note had recorded this silent resume as an unexplained pre-existing defect; the overlay's shallow replacement is the cause.
|
||||
Both failures were live in one real overlay. The exit hint stopped printing, because the overlay omitted `resumeCommand`. Worse, the overlay carried `resumeSessionId: !!js process.env.RESUME_SESSION_ID` — a stale line from before [the env-var bridge was removed](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md) — which overwrote the shipped `!!js "typeof resumeSessionId === 'string' ? …"` intake with a read of a variable nothing sets. `dsh --resume <valid-id>` then started a *fresh* session and said nothing, reproduced directly: the banner showed a newly minted id, not the requested one. The [`dsh meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note had recorded this silent resume as an unexplained pre-existing defect; the overlay's shallow replacement is the cause.
|
||||
|
||||
A config key cannot express these facts safely, because the deployment is not the authority on them.
|
||||
|
||||
@@ -25,7 +25,7 @@ Both sit beside the existing `tuiResumeHost` host capability, which set the prec
|
||||
|
||||
Identity belongs to `agent-loop` because that is the plugin which creates configured agents, and because a patch replaces a row's whole `config`: an overlay repointing the agent row's model route would erase a launcher-set identity key. See [the shared-base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md).
|
||||
|
||||
`apps/cli` mints or selects the id and builds the line from the invocation it is reproducing, sharing one `resumeArgs` helper with the `/resume` execve handoff so the printed command and the in-place handoff cannot diverge. The line names `--config` when one was passed. Resume always re-enters the default surface through `dsh --resume <id>`; `dsh experimental-meta` accepts no options and always starts fresh.
|
||||
`apps/cli` mints or selects the id and builds the line from the invocation it is reproducing, sharing one `resumeArgs` helper with the `/resume` execve handoff so the printed command and the in-place handoff cannot diverge. The line names `--config` when one was passed. Resume always re-enters the default surface through `dsh --resume <id>`; `dsh meta` accepts no default-surface options and always starts fresh.
|
||||
|
||||
**`ctx.provide` is the only channel from launcher argv into a Loader-mounted plugin.** Config `!!js` expressions evaluate as `with (entry.ctx) { eval(expr) }` (`vendor/loader/src/config/utils.ts`), so a bare identifier resolves against the entry's context and nothing else reaches it. The slot therefore cannot be removed while the app bundle is mounted from YAML; what changes is that it is now internal launcher↔app plumbing instead of a documented key a config author must wire correctly.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Status: implemented
|
||||
|
||||
把它们经由 YAML 传递，使其可被静默丢弃。`@cordisjs/plugin-include` 施加定向补丁的方式是替换整个顶层键（`target[key] = value`），因此一份对 `tui-agent` 条目的 `config` 打补丁的个人 `~/.dsh/config.yaml`，会把交付时的整块内容整体替换掉。于是，一份为改动 provider 和 model 而写的用户 overlay，会删掉它未重述的每一个 resume 键，且没有任何东西报告这一点：缺失 `resumeCommand` 合法地意味着「未配置回退」。
|
||||
|
||||
两处失效在同一份真实的 overlay 中同时存在。退出提示不再打印，因为该 overlay 省略了 `resumeCommand`。更糟的是，该 overlay 带着 `resumeSessionId: !!js process.env.RESUME_SESSION_ID`——一行来自 [env 变量桥被移除](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md)之前的陈旧代码——它用一次对某个无人设置的变量的读取，覆盖掉了交付时的 `!!js "typeof resumeSessionId === 'string' ? …"` 入口。此后 `dsh --resume <valid-id>` 会开启一个*全新*会话且什么都不说，并被直接复现：banner 显示的是一个新铸造的 id，而非所请求的那个。[`dsh experimental-meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note 曾把这次静默的 resume 记为一处无法解释的既有缺陷；而 overlay 的浅层替换正是其成因。
|
||||
两处失效在同一份真实的 overlay 中同时存在。退出提示不再打印，因为该 overlay 省略了 `resumeCommand`。更糟的是，该 overlay 带着 `resumeSessionId: !!js process.env.RESUME_SESSION_ID`——一行来自 [env 变量桥被移除](../../archived/architecture/2026-07-24-dsh-commander-argument-adapter.md)之前的陈旧代码——它用一次对某个无人设置的变量的读取，覆盖掉了交付时的 `!!js "typeof resumeSessionId === 'string' ? …"` 入口。此后 `dsh --resume <valid-id>` 会开启一个*全新*会话且什么都不说，并被直接复现：banner 显示的是一个新铸造的 id，而非所请求的那个。[`dsh meta`](../feature/2026-07-28-dsh-meta-source-workspace.md) note 曾把这次静默的 resume 记为一处无法解释的既有缺陷；而 overlay 的浅层替换正是其成因。
|
||||
|
||||
一个配置键无法安全地表达这些事实，因为部署方并非它们的权威。
|
||||
|
||||
@@ -25,7 +25,7 @@ Status: implemented
|
||||
|
||||
身份归属于 `agent-loop`，因为它才是创建所配置 agent 的插件；也因为 patch 会整体替换配置项的 `config`：重新指向 agent 配置项模型路由的 overlay 会抹掉启动器设置的身份键。参见[共享 base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md)。
|
||||
|
||||
`apps/cli` 铸造或选定 id，并依据它所复现的那次调用构建该行，与 `/resume` 的 execve 移交共用同一个 `resumeArgs` 助手，从而使打印出的命令与原地移交不会分歧。该行会在传入了 `--config` 时将其写入命令。恢复始终通过 `dsh --resume <id>` 重新进入默认界面；`dsh experimental-meta` 不接受任何选项，并且总是启动新会话。
|
||||
`apps/cli` 铸造或选定 id，并依据它所复现的那次调用构建该行，与 `/resume` 的 execve 移交共用同一个 `resumeArgs` 助手，从而使打印出的命令与原地移交不会分歧。该行会在传入了 `--config` 时将其写入命令。恢复始终通过 `dsh --resume <id>` 重新进入默认界面；`dsh meta` 不接受任何默认界面选项，并且总是启动新会话。
|
||||
|
||||
**`ctx.provide` 是从启动器 argv 进入被 Loader 挂载的插件的唯一通道。** 配置的 `!!js` 表达式会以 `with (entry.ctx) { eval(expr) }`（`vendor/loader/src/config/utils.ts`）求值，因此一个裸标识符会针对该条目的上下文解析，别无它物可达。于是只要应用 bundle 仍从 YAML 挂载，这个槽位就无法被移除；变化之处在于它现在是启动器↔应用之间的内部管线，而不再是一个配置作者必须正确接线的、有文档记载的键。
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# 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 .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md
|
||||
2026-07-30-source-checkout-workdir-distinction.md: ba6d9dd12b55a54d4ae8d2e91ad83ac3c1dc47fd
|
||||
2026-07-30-source-checkout-workdir-distinction.zh.md: ffc2ac7baa2b1bb8ce54607638c35869fc338825
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: Source checkout paths do not define working directories
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-30-source-checkout-workdir-distinction.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The `harness:source` prompt section follows the [source-location decision](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md), but its original wording called the checkout “your own source code” without distinguishing that path from the session workspace. In a normal TUI configuration that does not state `{{cwd}}` in its persona, this may be the only fixed absolute path near the start of the system prompt. DeepSeek V4 could therefore answer “what's the workdir?” with the harness checkout instead of determining the session's current working directory.
|
||||
|
||||
A blanket statement that the checkout is not the working directory would also be false. `dsh meta` intentionally makes the source checkout both values.
|
||||
|
||||
## Decision
|
||||
|
||||
The section identifies the path as the “DeepSeek Harness implementation checkout.” It says that the checkout location and current working directory are separate values that may differ, forbids inferring the working directory from the checkout path, directs the model to use `pwd`, and limits the checkout's purpose to inspecting or extending DSH itself.
|
||||
|
||||
The path derivation, global `harness:source` ownership, and `-99` ordering remain unchanged. Describing the values as conceptually separate rather than always unequal keeps the instruction accurate in both ordinary project sessions and `dsh meta`.
|
||||
|
||||
## Verification
|
||||
|
||||
The `dsh-app-boot` unit test pins the exact text and its ordering. The CLI keyless PTY smoke inspects the assembled request header. The TUI `source-checkout-workdir` snapshot mounts the section with `/opt/dsh-source`, asks “what's the workdir?” through a recorded DeepSeek V4 turn, and requires the replayed transcript to run `pwd` and report the generated workspace rather than the checkout.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Say that the checkout is never the working directory.** Rejected because `dsh meta` deliberately makes them the same path.
|
||||
|
||||
**Put the current working directory in the global source section.** Rejected because the source section is launcher-global while the working directory belongs to each session; combining them would duplicate the loop's `cwd` ownership and make a stable source fact vary per agent.
|
||||
|
||||
**Remove the source path from the prompt.** Rejected because self-referential DSH tools still need a reliable checkout location when the launcher starts from an unrelated project.
|
||||
|
||||
## Consequences
|
||||
|
||||
The prompt is longer and a direct working-directory question may spend one inexpensive `pwd` tool call. In exchange, the model no longer treats the harness implementation path as an implicit task workspace, while meta mode remains truthful when both values coincide.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Agent Note: 源码 checkout 路径不定义工作目录
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-30-source-checkout-workdir-distinction.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为“你自己的源代码”，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答“what's the workdir?”，而不是确定会话的当前工作目录。
|
||||
|
||||
直接断言 checkout 不是工作目录同样不准确。`dsh meta` 会有意让源码 checkout 同时充当这两个值。
|
||||
|
||||
## Decision
|
||||
|
||||
该提示词段将路径标识为“DeepSeek Harness implementation checkout”。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。
|
||||
|
||||
路径推导方式、全局 `harness:source` 所有权和 `-99` 顺序均保持不变。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。
|
||||
|
||||
## Verification
|
||||
|
||||
`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI 无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问“what's the workdir?”，并要求回放 transcript 运行 `pwd`，报告生成的 workspace 而不是 checkout。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**声明 checkout 永远不是工作目录。**拒绝：`dsh meta` 会有意让它们指向同一路径。
|
||||
|
||||
**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会重复 loop 对 `cwd` 的所有权，还会让稳定的源码事实随 agent 变化。
|
||||
|
||||
**从提示词中删除源码路径。**拒绝：launcher 从无关项目启动时，自引用 DSH 工具仍需要可靠的 checkout 位置。
|
||||
|
||||
## Consequences
|
||||
|
||||
提示词会变长，直接询问工作目录时可能多花一次廉价的 `pwd` 工具调用。作为交换，模型不再把 harness 实现路径当作隐含的任务 workspace；当 meta 模式使两个值重合时，提示词仍然准确。
|
||||
@@ -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/feature/2026-07-22-docked-web-goal-bar.md
|
||||
2026-07-22-docked-web-goal-bar.md: f014da61d2fa0bf25121c040dae99354ab15de9d
|
||||
2026-07-22-docked-web-goal-bar.zh.md: f62c6efbb2d330fb7d5ab74138eb781f1a1bc06c
|
||||
2026-07-22-docked-web-goal-bar.md: 30f1d45e80cb2759175948f5683b499720ab50f0
|
||||
2026-07-22-docked-web-goal-bar.zh.md: 4c8481e64d9e5177a962f10ab1d043e761d07545
|
||||
|
||||
@@ -12,7 +12,7 @@ The web UI had no goal surface at all: the goal stack shipped with model tools,
|
||||
|
||||
`GoalBar` (`packages/client/ui-goal/src/client/GoalBar.tsx`) is a props-driven, self-contained component registered first in the composer's input-dock list. Its standalone 752px card follows the composer's horizontal geometry, and every visible state shares one fixed 36px height so switching phases never resizes it. Loading (`goal === undefined`), absent (`goal === null`), and `phase === 'complete'` render nothing — a completed goal is history, not chrome.
|
||||
|
||||
Visibility drives the label and actions: active shows "Ongoing Goal" with pause/edit/clear; paused shows "Paused Goal" and swaps pause for a resume icon button; blocked shows "Blocked Goal" and carries `blockedReason.message` as the strip's `title` tooltip. Goal creation lives on the `/goal` command, not in the bar. The pencil swaps the strip for an inline edit form prefilled with the current objective: Enter or the check button saves through `GoalBarActions.onEdit(objective)`, Esc cancels, and an all-whitespace objective keeps save disabled. The form closes only when the edit succeeds; a failure preserves the draft and displays the error in the bar. Resume and clear failures are displayed there as well. Clear otherwise calls `onClear` directly with no confirmation — a clear keeps a durable tombstone, so nothing is unrecoverable. An effect keyed on the goal's id drops the edit form when the goal's identity changes, so a surviving draft can never be written over the goal that replaced it.
|
||||
Visibility drives the label and actions: active shows "Ongoing Goal" with pause/edit/clear; paused shows "Paused Goal" and swaps pause for a resume icon button; blocked shows "Blocked Goal" and carries `blockedReason.message` as the strip's `title` tooltip. Goal creation lives on the `/goal` command, not in the bar. The pencil swaps the strip for an inline edit form prefilled with the current objective: Enter or the check button saves through `GoalBarActions.onEdit(objective)`, Esc cancels, and an all-whitespace objective keeps save disabled. The form closes only when the edit succeeds; a failure preserves the draft and displays the error in the bar. Resume and clear failures are displayed there as well. Clear otherwise calls `onClear` directly with no confirmation — a clear keeps a durable tombstone, so nothing is unrecoverable. Every mutation first acquires a synchronous component-local single-flight latch because React's pending-state render cannot close the same-frame click window. A successful clear also suppresses that exact goal id immediately while the authoritative null projection catches up, so an acknowledged tombstone cannot leave a stale clear control that submits `GOAL_NOT_FOUND`; a failure releases the latch and remains retryable. An effect keyed on the goal's id resets this transient state and drops the edit form when the goal's identity changes, so neither a cleared marker nor a surviving draft can affect the replacement goal.
|
||||
|
||||
`GoalBarActions` lives in ui-goal's slot contract (`packages/client/ui-goal/src/client/slots.ts`) and carries exactly the rendered verbs: `onEdit`/`onPause`/`onResume`/`onClear`. Each callback asynchronously returns an explicit success/failure result so `GoalBar` owns its transitions and error display. `apply.ts` wires them to the runtime session methods; the runtime session resolves the current goal's compare-and-set ref internally, so the UI passes no ref.
|
||||
|
||||
@@ -22,7 +22,7 @@ The strip's background is `--dsw-alias-interactive-bg-hover` rather than the moc
|
||||
|
||||
## Testing
|
||||
|
||||
`packages/client/ui-goal/tests/goalbar.spec.tsx` pins the behavior through props alone: loading/absent/complete render nothing, the active strip renders label/objective and fires clear, the edit form prefills, rejects empty, saves on Enter, cancels on Esc, and resets when the goal's identity changes, the active strip fires pause, the paused strip fires resume, and the blocked strip exposes the reason tooltip. Component failure-path cases prove that a failed edit preserves its draft and that edit/resume/clear errors remain visible in the bar. The skeleton specs mount `ConversationRoot` with and without `goalActions`; the undefined case is seeded with an active goal, so the missing gate — not the missing goal — is what hides the strip. Runtime session specs pin the folded-error results, the live-only in-flight-plus-trailing refetch, and the stale-read guard. A keyless real-browser smoke boots the assembled application through `boot → RPC → runtime → GoalBar` and records an inline snapshot of the rendered label, objective, and actions.
|
||||
`packages/client/ui-goal/tests/goalbar.spec.tsx` pins the behavior through props alone: loading/absent/complete render nothing, the active strip renders label/objective and fires clear, rapid same-frame clear clicks dispatch once and a successful clear hides before projection convergence, the edit form prefills, rejects empty, saves on Enter, cancels on Esc, and resets when the goal's identity changes, the active strip fires pause, the paused strip fires resume, and the blocked strip exposes the reason tooltip. Component failure-path cases prove that a failed edit preserves its draft and that edit/resume/clear errors remain visible and retryable in the bar. The skeleton specs mount `ConversationRoot` with and without `goalActions`; the undefined case is seeded with an active goal, so the missing gate — not the missing goal — is what hides the strip. Runtime session specs pin the folded-error results, the live-only in-flight-plus-trailing refetch, and the stale-read guard. A keyless real-browser smoke boots the assembled application through `boot → RPC → runtime → GoalBar` and records an inline snapshot of the rendered label, objective, and actions.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -34,6 +34,7 @@ The strip's background is `--dsw-alias-interactive-bg-hover` rather than the moc
|
||||
## Consequences
|
||||
|
||||
- Goal presence in the web UI is a standalone composer-context strip: sparkle, phase label, truncated objective, and pause/edit/clear (resume replacing pause when paused) — the browser client's first goal surface.
|
||||
- Goal mutations are single-flight within the component; a successful clear hides its exact goal immediately while projection delivery converges, preventing duplicate CAS errors without making transient UI state authoritative.
|
||||
- The runtime session exposes the goal verbs over RPC with folded transport errors, and refreshes the snapshot's goal on open and on live goal-change meta (coalesced, guarded against stale reads).
|
||||
- Objective editing is reachable from the UI for the first time, through `goal.edit` with the runtime-owned ref; complete remains available to other surfaces (`/goal`, model tools).
|
||||
- `goal === null` renders nothing; the composer carries no persistent create affordance — creation is the `/goal` command's job.
|
||||
|
||||
@@ -12,7 +12,7 @@ Web UI 此前没有任何目标相关的界面：目标栈已随模型工具、T
|
||||
|
||||
`GoalBar`（`packages/client/ui-goal/src/client/GoalBar.tsx`）是一个由 props 驱动的自包含组件，在 composer 的 input-dock 列表中注册为第一个条目。它采用独立的 752px 卡片，遵循 composer 的水平几何；所有可见状态均使用固定的 36px 高度，切换阶段不会改变尺寸。加载中（`goal === undefined`）、无目标（`goal === null`）和 `phase === 'complete'` 时不渲染任何内容：已完成的目标是历史记录，不是常驻界面元素。
|
||||
|
||||
可见性决定标签和操作：active 状态显示 "Ongoing Goal" 并提供暂停／编辑／清除；paused 状态显示 "Paused Goal"，把暂停换成一个恢复图标按钮；blocked 状态显示 "Blocked Goal"，并把 `blockedReason.message` 作为横条的 `title` 悬浮提示。创建目标的入口在 `/goal` 命令上，不在横条里。铅笔图标把横条切换为内联编辑表单，预填当前目标内容：Enter 或勾选按钮通过 `GoalBarActions.onEdit(objective)` 保存，Esc 取消，目标内容全为空白字符时保存按钮保持禁用。编辑成功后表单才会关闭；编辑失败时保留草稿，并在横条中显示错误。恢复和清除失败也显示在横条中。除此之外，清除直接调用 `onClear`，不做确认——清除会保留 durable 墓碑，没有不可恢复的损失。一个以目标 id 为键的 effect 会在目标身份变化时丢弃编辑表单，因此存留的草稿绝不可能覆盖掉替换它的新目标。
|
||||
可见性决定标签和操作：active 状态显示 "Ongoing Goal" 并提供暂停／编辑／清除；paused 状态显示 "Paused Goal"，把暂停换成一个恢复图标按钮；blocked 状态显示 "Blocked Goal"，并把 `blockedReason.message` 作为横条的 `title` 悬浮提示。创建目标的入口在 `/goal` 命令上，不在横条里。铅笔图标把横条切换为内联编辑表单，预填当前目标内容：Enter 或勾选按钮通过 `GoalBarActions.onEdit(objective)` 保存，Esc 取消，目标内容全为空白字符时保存按钮保持禁用。编辑成功后表单才会关闭；编辑失败时保留草稿，并在横条中显示错误。恢复和清除失败也显示在横条中。除此之外，清除直接调用 `onClear`，不做确认——清除会保留 durable 墓碑，没有不可恢复的损失。每次变更都会先取得一个同步的组件内 single-flight 锁，因为 React 的 pending 状态渲染无法关闭同一帧内的点击窗口。清除成功后还会立即抑制该 goal id，直到权威的 null 投影追上，因此已确认的墓碑不会留下陈旧的清除控件并再次提交 `GOAL_NOT_FOUND`；失败则释放锁，并且仍可重试。一个以目标 id 为键的 effect 会在目标身份变化时重置瞬态状态并丢弃编辑表单，因此无论已清除标记还是存留草稿，都不会影响替换目标。
|
||||
|
||||
`GoalBarActions` 位于 ui-goal 的槽位契约（`packages/client/ui-goal/src/client/slots.ts`），只携带实际渲染的动词：`onEdit`/`onPause`/`onResume`/`onClear`。每个回调都会异步返回显式成功／失败结果，因此 `GoalBar` 自行负责界面转换和错误显示。`apply.ts` 把它们接到运行时会话方法上；运行时会话在内部解析当前目标的 compare-and-set ref，因此 UI 不传 ref。
|
||||
|
||||
@@ -22,7 +22,7 @@ Web UI 此前没有任何目标相关的界面：目标栈已随模型工具、T
|
||||
|
||||
## 测试
|
||||
|
||||
`packages/client/ui-goal/tests/goalbar.spec.tsx` 仅通过 props 固定这些行为：加载中／无目标／已完成时不渲染；active 横条渲染标签和目标内容并触发清除；编辑表单预填内容、拒绝空值、按 Enter 保存、按 Esc 取消，并在目标身份变化时重置；active 横条触发暂停；paused 横条触发恢复；blocked 横条暴露原因悬浮提示。组件失败路径用例证明编辑失败时保留草稿，并且编辑／恢复／清除错误持续显示在横条中。skeleton 规格测试分别挂载带与不带 `goalActions` 的 `ConversationRoot`；未定义的情形预置了一个 active 目标，因此隐藏横条的是缺失的挂载门，而不是缺失的目标。运行时会话规格测试固定了折叠错误结果、仅 live 的执行中读取加尾随读取，以及陈旧读取守卫。一个无密钥真实浏览器冒烟测试通过 `boot → RPC → runtime → GoalBar` 启动组装后的应用，并以内联快照记录渲染出的标签、目标内容和操作。
|
||||
`packages/client/ui-goal/tests/goalbar.spec.tsx` 仅通过 props 固定这些行为：加载中／无目标／已完成时不渲染；active 横条渲染标签和目标内容并触发清除；同一帧内快速连续点击清除只会分发一次，清除成功后横条会在投影收敛前隐藏；编辑表单预填内容、拒绝空值、按 Enter 保存、按 Esc 取消，并在目标身份变化时重置；active 横条触发暂停；paused 横条触发恢复；blocked 横条暴露原因悬浮提示。组件失败路径用例证明编辑失败时保留草稿，并且编辑／恢复／清除错误持续显示在横条中且可重试。skeleton 规格测试分别挂载带与不带 `goalActions` 的 `ConversationRoot`；未定义的情形预置了一个 active 目标，因此隐藏横条的是缺失的挂载门，而不是缺失的目标。运行时会话规格测试固定了折叠错误结果、仅 live 的执行中读取加尾随读取，以及陈旧读取守卫。一个无密钥真实浏览器冒烟测试通过 `boot → RPC → runtime → GoalBar` 启动组装后的应用，并以内联快照记录渲染出的标签、目标内容和操作。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
@@ -34,6 +34,7 @@ Web UI 此前没有任何目标相关的界面：目标栈已随模型工具、T
|
||||
## 后果
|
||||
|
||||
- Web UI 中目标的存在形式是独立的 composer 上下文横条：闪光图标、阶段标签、截断的目标内容，以及暂停／编辑／清除（暂停时恢复取代暂停）——这是浏览器客户端的第一个目标界面。
|
||||
- 目标变更在组件内走 single-flight；清除成功后会在投影投递收敛期间立即隐藏与其 id 完全匹配的目标，既防止重复 CAS 错误，又不会把瞬态 UI 状态视为权威。
|
||||
- 运行时会话通过 RPC 暴露目标动词并折叠传输层错误，且在打开时和 live 目标变更元数据到达时刷新快照中的目标（合并拉取，带陈旧读取守卫）。
|
||||
- 目标内容首次可以从 UI 编辑，经由 `goal.edit`，ref 由运行时持有；完成对其他界面（`/goal`、模型工具）照常可用。
|
||||
- `goal === null` 时不渲染任何内容；输入框不提供常驻的创建入口，创建是 `/goal` 命令的职责。
|
||||
|
||||
@@ -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/feature/2026-07-28-dsh-guided-skill-session-commands.md
|
||||
2026-07-28-dsh-guided-skill-session-commands.md: 9d5341880e92d88781278238f21380919c962820
|
||||
2026-07-28-dsh-guided-skill-session-commands.zh.md: 90c47d64173161fa4ef1f975de37b9cd42e02c99
|
||||
2026-07-28-dsh-guided-skill-session-commands.md: 8a091f7a03c85b0723d96b4fc546875a4e6c0f95
|
||||
2026-07-28-dsh-guided-skill-session-commands.zh.md: 861e6cf6cf07c41fde4f78b0833e3f8eb9508767
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: `dsh migrate`/`dsh experimental-upgrade` seed the first turn with a skill
|
||||
# Agent Note: `dsh migrate`/`dsh upgrade` seed the first turn with a skill
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -10,13 +10,13 @@ Two recurring flows begin with the user manually invoking one skill and answerin
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh migrate` and `dsh experimental-upgrade` boot the ordinary TUI as a fresh session whose first turn auto-invokes a bundled skill (`dsh-migrate`, `dsh-upgrade`), exactly as if the user typed `/skill:<name>` and pressed Enter.
|
||||
`dsh migrate` and `dsh upgrade` boot the ordinary TUI as a fresh session whose first turn auto-invokes a bundled skill (`dsh-migrate`, `dsh-upgrade`), exactly as if the user typed `/skill:<name>` and pressed Enter.
|
||||
|
||||
The seed reuses the existing TUI skill path, not a new one. `createTuiChat` already has `invokeSkill(name, instructions)` — the code a typed `/skill:<name>` runs, including the "Unknown skill" notice. The launcher passes the skill name to the TUI through a new boot-context slot `INITIAL_SKILL_KEY` (`tuiInitialSkill`), mirroring `CONFIGURED_AGENT_IDENTITIES_KEY`/`TUI_GOODBYE_MESSAGE_KEY`: `ctx.provide` is the only channel from launcher argv into a Loader-mounted plugin. The TUI's `apply()` reads the slot and folds it into `config.initialSkill`; after `ui.start()` succeeds, `createTuiChat` fires `invokeSkill(config.initialSkill, '')` once when set.
|
||||
|
||||
**Freshness is gated in the launcher, not the TUI.** `runSkillSession` always mints a fresh session and provides the slot only when `resumeSessionId === undefined`, so a later `dsh --resume <id>` of that session is an ordinary TUI session with no re-injection. The TUI stays generic: it invokes whatever skill it is handed, once, at startup.
|
||||
|
||||
**`migrate`/`upgrade` take no options.** Unlike `meta`, they carry no `--resume`, `--config`, or `-p`; a guided fresh-session entry has nothing to resume or reconfigure. Any leaked default-surface option fails loud, matching the `web`/`meta` rejection pattern in the Commander adapter. The two modes share one `SkillSessionInvocation` discriminant (`mode: 'migrate' | 'upgrade'`); `bin.ts` maps the mode to `dsh-${mode}`.
|
||||
**`migrate`/`upgrade` take no default-surface options** (`upgrade` additionally carries the [experimental gate](2026-07-31-experimental-subcommand-gate.md)'s `--experimental`). They carry no `--resume`, `--config`, or `-p`; a guided fresh-session entry has nothing to resume or reconfigure. Any leaked default-surface option fails loud, matching the `web`/`meta` rejection pattern in the Commander adapter. The two modes share one `SkillSessionInvocation` discriminant (`mode: 'migrate' | 'upgrade'`); `bin.ts` maps the mode to `dsh-${mode}`.
|
||||
|
||||
The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED_SKILL_DIR`, like `dsh-upgrade`). It asks which source agent (opencode/pi/Claude Code/Codex) if unstated, then maps each capability — workspace instructions, personal overlay, skills, hooks, MCP, API/env — to its DSH equivalent, grounded in the actual repo surfaces (the `hooks-claude`/`hooks-codex` bridges, `~/.dsh/{config.yaml,.env,AGENTS.md,skills/}`, `AGENTS.md`/`CLAUDE.md`, `mcporter`), and states plainly when a capability has no equivalent.
|
||||
|
||||
@@ -26,7 +26,7 @@ The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` gains two fake-terminal cases in the existing skill describe block: `config.initialSkill` set delivers the rendered skill body as the first turn with no user input, and an unknown initial skill reports a notice without sending. `runSkillSession` itself is composition inside the module's `v8 ignore` block, like `runTui`/`runMeta`.
|
||||
|
||||
No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh experimental-upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery.
|
||||
No keyless PTY snapshot: per the maintainer's scope call for this change, unit coverage plus interactive verification suffices, and the seed rides the already-snapshotted `/skill:` render path. Both commands were verified interactively in tmux from a scratch cwd: `dsh migrate` loaded `dsh-migrate` and asked which source agent; `dsh upgrade` loaded `dsh-upgrade`, which pulled in `dsh-customize` and began checkout discovery.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note：`dsh migrate`/`dsh experimental-upgrade` 以 skill 播种首轮
|
||||
# Agent Note：`dsh migrate`/`dsh upgrade` 以 skill 播种首轮
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -10,13 +10,13 @@ Status: implemented
|
||||
|
||||
## 决策
|
||||
|
||||
`dsh migrate` 与 `dsh experimental-upgrade` 以全新会话启动普通 TUI，其首轮自动调用一个内置 skill（`dsh-migrate`、`dsh-upgrade`），效果等同于用户键入 `/skill:<name>` 并回车。
|
||||
`dsh migrate` 与 `dsh upgrade` 以全新会话启动普通 TUI，其首轮自动调用一个内置 skill（`dsh-migrate`、`dsh-upgrade`），效果等同于用户键入 `/skill:<name>` 并回车。
|
||||
|
||||
播种复用现有的 TUI skill 路径，而非新增一条。`createTuiChat` 已有 `invokeSkill(name, instructions)`——即键入 `/skill:<name>` 所走的代码，包含“未知 skill”通知。启动器通过一个新的启动上下文槽 `INITIAL_SKILL_KEY`（`tuiInitialSkill`）把 skill 名称传给 TUI，与 `CONFIGURED_AGENT_IDENTITIES_KEY`/`TUI_GOODBYE_MESSAGE_KEY` 一致：`ctx.provide` 是从启动器 argv 进入 Loader 挂载插件的唯一通道。TUI 的 `apply()` 读取该槽并折叠进 `config.initialSkill`；`ui.start()` 成功后，`createTuiChat` 在其被设置时调用一次 `invokeSkill(config.initialSkill, '')`。
|
||||
|
||||
**新鲜性在启动器而非 TUI 中把关。** `runSkillSession` 总是创建全新会话，且仅在 `resumeSessionId === undefined` 时提供该槽，因此之后 `dsh --resume <id>` 恢复该会话时是普通 TUI 会话，不会重复注入。TUI 保持通用：它只是把接到的 skill 在启动时调用一次。
|
||||
|
||||
**`migrate`/`upgrade` 不接受任何选项。** 与 `meta` 不同，它们不带 `--resume`、`--config` 或 `-p`；引导式全新会话入口没有可恢复或可重配置的内容。任何泄漏的默认界面选项都会明确报错，与 Commander 适配器中 `web`/`meta` 的拒绝模式一致。两个 mode 共用一个 `SkillSessionInvocation` 判别式（`mode: 'migrate' | 'upgrade'`）；`bin.ts` 将 mode 映射为 `dsh-${mode}`。
|
||||
**`migrate`/`upgrade` 不接受任何默认界面选项**（`upgrade` 另带[实验性门槛](2026-07-31-experimental-subcommand-gate.md)的 `--experimental`）。它们不带 `--resume`、`--config` 或 `-p`；引导式全新会话入口没有可恢复或可重配置的内容。任何泄漏的默认界面选项都会明确报错，与 Commander 适配器中 `web`/`meta` 的拒绝模式一致。两个 mode 共用一个 `SkillSessionInvocation` 判别式（`mode: 'migrate' | 'upgrade'`）；`bin.ts` 将 mode 映射为 `dsh-${mode}`。
|
||||
|
||||
`dsh-migrate` skill 内置于 `skills/`（经 `DSH_BUNDLED_SKILL_DIR` 交付，与 `dsh-upgrade` 相同）。若未说明源 agent，它会先询问是哪个（opencode/pi/Claude Code/Codex），再把每项能力——workspace 指令、个人覆盖、skills、hooks、MCP、API/env——映射到对应的 DSH 等价物，并基于仓库实际的表面（`hooks-claude`/`hooks-codex` 桥、`~/.dsh/{config.yaml,.env,AGENTS.md,skills/}`、`AGENTS.md`/`CLAUDE.md`、`mcporter`）落地；当某能力无等价物时明确说明。
|
||||
|
||||
@@ -26,7 +26,7 @@ Status: implemented
|
||||
|
||||
`packages/ui/tui/tests/tui.spec.ts` 在既有 skill describe 块中新增两个伪终端用例：设置 `config.initialSkill` 时无需用户输入即把渲染后的 skill 正文作为首轮投递；未知的初始 skill 以通知形式报告且不发送。`runSkillSession` 本身是模块 `v8 ignore` 块内的组装，与 `runTui`/`runMeta` 相同。
|
||||
|
||||
无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh experimental-upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。
|
||||
无 keyless PTY 快照：依据维护者对本次改动的范围裁定，单元覆盖加交互式验证已足够，且播种走的是已有快照的 `/skill:` 渲染路径。两个命令均已在 tmux 中从临时 cwd 交互式验证：`dsh migrate` 加载 `dsh-migrate` 并询问源 agent；`dsh upgrade` 加载 `dsh-upgrade`，后者引入 `dsh-customize` 并开始 checkout 发现。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
|
||||
@@ -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/feature/2026-07-28-dsh-meta-source-workspace.md
|
||||
2026-07-28-dsh-meta-source-workspace.md: be414ddbf63dd95791f9ca956b2f345b1fc8c685
|
||||
2026-07-28-dsh-meta-source-workspace.zh.md: 86fc135db290766cb6fc2abefb194120416bfd9d
|
||||
2026-07-28-dsh-meta-source-workspace.md: 95270a276cd5df03ffd2dfb419a33289d7b5b901
|
||||
2026-07-28-dsh-meta-source-workspace.zh.md: 645b20705386a3501d026fb58ca224c49cc69a17
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: `dsh experimental-meta` boots the TUI over the harness checkout
|
||||
# Agent Note: `dsh meta` boots the TUI over the harness checkout
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -10,19 +10,19 @@ English | [中文](2026-07-28-dsh-meta-source-workspace.zh.md)
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh experimental-meta` boots the ordinary TUI with the harness checkout as the workspace, from any directory.
|
||||
`dsh meta` boots the ordinary TUI with the harness checkout as the workspace, from any directory.
|
||||
|
||||
The target is `SOURCE_ROOT` in `apps/cli/src/tui.ts` — `fileURLToPath(new URL('../../..', import.meta.url))`, three hops up from `apps/cli/{src,lib}` — the same constant the `harness:source` prompt section already names, so the workspace and the path advertised to the model cannot drift. It follows the launcher's real path, so a PATH symlink through `current` resolves to whichever staging worktree is active.
|
||||
|
||||
The mechanism is one `process.chdir(workspace)` inside `runTui`, guarded by an optional third parameter that only the `experimental-meta` dispatch passes. The cwd *is* the workspace seam in the shipped tree: `examples/tui-agent/cordis.yml` derives the session cwd (`!!js process.cwd()`), the `./.sessions` persistence root, and the HMR watch root (`root: ['.']`) from it, so one chdir moves all three together and meta sessions land in the checkout's gitignored `.sessions/`. It runs after both `.env` layers are loaded — the bin's invoking-directory load and the personal one — so the ambient > project > personal precedence is untouched. `DEFAULT_CONFIG` and `SOURCE_ROOT` are absolute and TUI mode passes no snapshot mode, so config resolution is chdir-independent.
|
||||
The mechanism is one `process.chdir(workspace)` inside `runTui`, guarded by an optional third parameter that only the `meta` dispatch passes. The cwd *is* the workspace seam in the shipped tree: `examples/tui-agent/cordis.yml` derives the session cwd (`!!js process.cwd()`), the `./.sessions` persistence root, and the HMR watch root (`root: ['.']`) from it, so one chdir moves all three together and meta sessions land in the checkout's gitignored `.sessions/`. It runs after both `.env` layers are loaded — the bin's invoking-directory load and the personal one — so the ambient > project > personal precedence is untouched. `DEFAULT_CONFIG` and `SOURCE_ROOT` are absolute and TUI mode passes no snapshot mode, so config resolution is chdir-independent.
|
||||
|
||||
`experimental-meta` always starts a fresh session and accepts no options. `--config` would boot a foreign tree against the harness workspace, which is the default surface's `--config` case rather than this command; `-p` is not interactive, and resume re-enters the persisted session's own workspace through `dsh --resume <id>`. Any leaked default-surface option fails loud.
|
||||
`meta` always starts a fresh session and accepts no default-surface options; its only option is the [experimental gate](2026-07-31-experimental-subcommand-gate.md)'s `--experimental`. `--config` would boot a foreign tree against the harness workspace, which is the default surface's `--config` case rather than this command; `-p` is not interactive, and resume re-enters the persisted session's own workspace through `dsh --resume <id>`. Any leaked default-surface option fails loud.
|
||||
|
||||
## Testing
|
||||
|
||||
`apps/cli/tests/args.spec.ts` pins routing for `experimental-meta`, rejection of every leaked default-surface option, and rejection of the former `meta` name. The dispatch itself is composition inside `bin.ts`'s existing `v8 ignore` block.
|
||||
`apps/cli/tests/args.spec.ts` pins routing for `meta`, rejection of every leaked default-surface option, and rejection of the former `experimental-meta` name. The dispatch itself is composition inside `bin.ts`'s existing `v8 ignore` block.
|
||||
|
||||
There is no keyless PTY smoke for this mode. The smoke harness gives each run a temp cwd, but `dsh experimental-meta` deliberately chdirs to the real checkout, so a smoke would write `.sessions/` into the live tree mid-test. Covering it properly needs an injectable target directory — a test-only seam this note declines to add for a one-line chdir.
|
||||
There is no keyless PTY smoke for this mode. The smoke harness gives each run a temp cwd, but `dsh meta` deliberately chdirs to the real checkout, so a smoke would write `.sessions/` into the live tree mid-test. Covering it properly needs an injectable target directory — a test-only seam this note declines to add for a one-line chdir.
|
||||
|
||||
The mode was verified interactively instead. Launched from `$HOME`, a `pwd` tool call reports the checkout, git resolves to its branch, the session log lands under the checkout's `.sessions/` (leaving `~/.sessions` untouched and the tree free of unignored residue), and plain `dsh` from another directory still uses the invoking one.
|
||||
|
||||
@@ -30,12 +30,12 @@ The mode was verified interactively instead. Launched from `$HOME`, a `pwd` tool
|
||||
|
||||
**Thread an explicit workspace through `boot` and the config tree.** Avoids mutating process-wide state, but the shipped config reads the cwd in three places (`!!js process.cwd()`, `persistenceRoot`, HMR `root`), so each would need its own new plumbing and config key to stay consistent. `chdir` before boot expresses "this is the workspace" once, at the seam that already means it.
|
||||
|
||||
**An `--experimental-meta` flag on the default surface.** Rejected: the default surface is option-only so that subcommands do not collide with a positional, and a flag that silently relocates the workspace reads as a modifier of the current directory rather than a different target. `experimental-meta` alongside `web` matches the existing shape.
|
||||
**An `--experimental-meta` flag on the default surface.** Rejected: the default surface is option-only so that subcommands do not collide with a positional, and a flag that silently relocates the workspace reads as a modifier of the current directory rather than a different target. `meta` alongside `web` matches the existing shape.
|
||||
|
||||
**Resolve `~/.dsh/source/current` instead of the launcher's own path.** Rejected: it would diverge from the `harness:source` prompt path whenever a non-installed checkout's `bin/dsh` is invoked directly, telling the model one source root while working in another.
|
||||
|
||||
## Consequences
|
||||
|
||||
Starting a session on dsh's own source is `dsh experimental-meta` from anywhere, and the workspace is guaranteed to be the same checkout the model is told about. The command always starts fresh; an ordinary `dsh --resume <id>` later restores the session and enters its persisted workspace.
|
||||
Starting a session on dsh's own source is `dsh meta --experimental` from anywhere (or bare `dsh meta` under `DSH_EXPERIMENTAL=1`), and the workspace is guaranteed to be the same checkout the model is told about. The command always starts fresh; an ordinary `dsh --resume <id>` later restores the session and enters its persisted workspace.
|
||||
|
||||
`runTui` gains an optional third parameter, so the workspace override is visible at the one function that owns TUI composition rather than hidden in a second copy of it.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note：`dsh experimental-meta` 以 harness 检出为 workspace 启动 TUI
|
||||
# Agent Note：`dsh meta` 以 harness 检出为 workspace 启动 TUI
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -10,19 +10,19 @@ Status: implemented
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh experimental-meta` 在任意目录下都以 harness 检出为 workspace 启动普通 TUI。
|
||||
`dsh meta` 在任意目录下都以 harness 检出为 workspace 启动普通 TUI。
|
||||
|
||||
目标是 `apps/cli/src/tui.ts` 中的 `SOURCE_ROOT`——`fileURLToPath(new URL('../../..', import.meta.url))`，从 `apps/cli/{src,lib}` 向上三级——与 `harness:source` 提示词段所用的常量完全相同，因此 workspace 与告知模型的路径不可能发生偏离。它跟随启动器的真实路径，所以经由 `current` 的 PATH 符号链接会解析到当前生效的那个 staging 工作树。
|
||||
|
||||
机制是 `runTui` 内的一次 `process.chdir(workspace)`，由一个可选第三参数把守，只有 `experimental-meta` 分派会传入。在已交付的配置树中，cwd *就是* workspace 的接缝：`examples/tui-agent/cordis.yml` 由它派生出会话 cwd（`!!js process.cwd()`）、`./.sessions` 持久化根目录以及 HMR 监视根目录（`root: ['.']`），因此一次 chdir 会让三者一并移动，meta 会话则落在检出目录中被 gitignore 的 `.sessions/` 内。它在两层 `.env` 都加载之后执行——bin 对调用目录的加载与个人层加载——因此“环境中已有的值 > 项目 > 个人”的优先级不受影响。`DEFAULT_CONFIG` 与 `SOURCE_ROOT` 都是绝对路径，且 TUI 模式不传 snapshot mode，所以配置解析与 chdir 无关。
|
||||
机制是 `runTui` 内的一次 `process.chdir(workspace)`，由一个可选第三参数把守，只有 `meta` 分派会传入。在已交付的配置树中，cwd *就是* workspace 的接缝：`examples/tui-agent/cordis.yml` 由它派生出会话 cwd（`!!js process.cwd()`）、`./.sessions` 持久化根目录以及 HMR 监视根目录（`root: ['.']`），因此一次 chdir 会让三者一并移动，meta 会话则落在检出目录中被 gitignore 的 `.sessions/` 内。它在两层 `.env` 都加载之后执行——bin 对调用目录的加载与个人层加载——因此“环境中已有的值 > 项目 > 个人”的优先级不受影响。`DEFAULT_CONFIG` 与 `SOURCE_ROOT` 都是绝对路径，且 TUI 模式不传 snapshot mode，所以配置解析与 chdir 无关。
|
||||
|
||||
`experimental-meta` 始终启动新会话，且不接受任何选项。`--config` 会针对 harness workspace 启动其他配置树，那是默认界面的 `--config` 场景，而不是该命令的场景；`-p` 并非交互式，恢复则通过 `dsh --resume <id>` 重新进入已持久化会话自身的 workspace。任何泄漏的默认界面选项都会明确报错。
|
||||
`meta` 始终启动新会话，且不接受任何默认界面选项；它唯一的选项是[实验性门槛](2026-07-31-experimental-subcommand-gate.md)的 `--experimental`。`--config` 会针对 harness workspace 启动其他配置树，那是默认界面的 `--config` 场景，而不是该命令的场景；`-p` 并非交互式，恢复则通过 `dsh --resume <id>` 重新进入已持久化会话自身的 workspace。任何泄漏的默认界面选项都会明确报错。
|
||||
|
||||
## Testing
|
||||
|
||||
`apps/cli/tests/args.spec.ts` 钉住 `experimental-meta` 的路由、对每个泄漏的默认界面选项的拒绝，以及对旧名称 `meta` 的拒绝。该分派本身是 `bin.ts` 既有 `v8 ignore` 块内的组合代码。
|
||||
`apps/cli/tests/args.spec.ts` 钉住 `meta` 的路由、对每个泄漏的默认界面选项的拒绝，以及对旧名称 `experimental-meta` 的拒绝。该分派本身是 `bin.ts` 既有 `v8 ignore` 块内的组合代码。
|
||||
|
||||
该 mode 没有 keyless PTY 冒烟测试。冒烟框架会为每次运行提供临时 cwd，但 `dsh experimental-meta` 刻意 chdir 到真实检出目录，因此冒烟测试会在测试中途把 `.sessions/` 写入实际工作树。要正确覆盖它需要一个可注入的目标目录——为了一行 chdir 而引入的测试专用 seam，本 note 不予采纳。
|
||||
该 mode 没有 keyless PTY 冒烟测试。冒烟框架会为每次运行提供临时 cwd，但 `dsh meta` 刻意 chdir 到真实检出目录，因此冒烟测试会在测试中途把 `.sessions/` 写入实际工作树。要正确覆盖它需要一个可注入的目标目录——为了一行 chdir 而引入的测试专用 seam，本 note 不予采纳。
|
||||
|
||||
取而代之的是交互式验证。从 `$HOME` 启动后，`pwd` 工具调用报告的是该检出目录，git 解析到其分支，会话日志落在该检出的 `.sessions/` 下（`~/.sessions` 未被触及，工作树也没有未被忽略的残留），并且从其他目录运行的普通 `dsh` 仍使用调用目录。
|
||||
|
||||
@@ -30,12 +30,12 @@ Status: implemented
|
||||
|
||||
**通过 `boot` 与配置树显式传递 workspace。** 这可避免修改进程级状态，但已交付的配置在三处读取 cwd（`!!js process.cwd()`、`persistenceRoot`、HMR `root`），每一处都需要各自新增管线与配置键才能保持一致。启动前 chdir 只在本就表达该含义的接缝上表达一次“这就是 workspace”。
|
||||
|
||||
**在默认界面上加一个 `--experimental-meta` 标志。** 拒绝：默认界面是纯选项形式，以免子命令与位置参数冲突；而一个会静默改变 workspace 的标志读起来像是对当前目录的修饰，而非另一个目标。`experimental-meta` 与 `web` 并列符合既有形态。
|
||||
**在默认界面上加一个 `--experimental-meta` 标志。** 拒绝：默认界面是纯选项形式，以免子命令与位置参数冲突；而一个会静默改变 workspace 的标志读起来像是对当前目录的修饰，而非另一个目标。`meta` 与 `web` 并列符合既有形态。
|
||||
|
||||
**解析 `~/.dsh/source/current` 而非启动器自身路径。** 拒绝：当直接调用某个非安装检出的 `bin/dsh` 时，它会与 `harness:source` 提示词路径产生偏离——告知模型一个源码根目录，却在另一个目录中工作。
|
||||
|
||||
## Consequences
|
||||
|
||||
在 dsh 自身源码上开启会话变成了在任意位置执行 `dsh experimental-meta`，且该 workspace 必然就是告知模型的那个检出目录。该命令始终启动新会话；之后，普通的 `dsh --resume <id>` 会恢复该会话并进入其已持久化的 workspace。
|
||||
在 dsh 自身源码上开启会话变成了在任意位置执行 `dsh meta --experimental`（在 `DSH_EXPERIMENTAL=1` 下可直接执行 `dsh meta`），且该 workspace 必然就是告知模型的那个检出目录。该命令始终启动新会话；之后，普通的 `dsh --resume <id>` 会恢复该会话并进入其已持久化的 workspace。
|
||||
|
||||
`runTui` 新增一个可选第三参数，因此 workspace 覆盖是在拥有 TUI 组合逻辑的那唯一一个函数上可见的，而不是隐藏在它的第二份副本中。
|
||||
|
||||
@@ -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/feature/2026-07-28-skill-invocation-policy.md
|
||||
2026-07-28-skill-invocation-policy.md: e639db39c0e971ea6988ef6e9801ab71f8d1337f
|
||||
2026-07-28-skill-invocation-policy.zh.md: 7e68f2cf28fbaa734dff477441fc8ab73e7367b7
|
||||
2026-07-28-skill-invocation-policy.md: f74b0bcfddb1699c48279b4d8b153cabf764b140
|
||||
2026-07-28-skill-invocation-policy.zh.md: 1a7117a382be224c5371964dd4ad3e916d4e0917
|
||||
|
||||
@@ -18,7 +18,7 @@ The local parser also exposed an internal camel-case spelling as frontmatter. Su
|
||||
|
||||
The local provider accepts the exact kebab-case frontmatter keys `disable-model-invocation` and `user-invocable`. It accepts YAML booleans plus case-insensitive `true`/`false`, `yes`/`no`, `on`/`off`, and `1`/`0`, matching the practical boolean forms accepted by Claude skills. It maps `disable-model-invocation` to the inverse positive field and fills both positive fields from their defaults even when neither key is present. A camel-case external spelling or non-boolean invocation value drops the entire skill from discovery with a targeted warning; this pre-release repository does not keep an on-disk compatibility alias. Invocation data fails closed because ignoring it would default to permission and could expose the skill on a disabled surface, while wrong-typed optional `whenToUse` and `metadata` values are omitted because they do not decide invocation.
|
||||
|
||||
The model-facing `dsh-tool-skill` catalog and loader enforce `isModelInvocable`. The TUI `/skill:` autocomplete and exact loader enforce the user field locally, so a user-only skill is visible and loadable there even when it is absent from model discovery, without turning the optional skill peer into a runtime import. The launcher-seeded initial skill used by guided `dsh migrate` and `dsh experimental-upgrade` sessions follows this same TUI path and must remain user-invocable. The browser `skill.list` RPC serves a user-selected reference that still asks the model to load the skill, so it exposes the intersection of model- and user-invocable skills; no direct browser skill-loading RPC is added.
|
||||
The model-facing `dsh-tool-skill` catalog and loader enforce `isModelInvocable`. The TUI `/skill:` autocomplete and exact loader enforce the user field locally, so a user-only skill is visible and loadable there even when it is absent from model discovery, without turning the optional skill peer into a runtime import. The launcher-seeded initial skill used by guided `dsh migrate` and `dsh upgrade` sessions follows this same TUI path and must remain user-invocable. The browser `skill.list` RPC serves a user-selected reference that still asks the model to load the skill, so it exposes the intersection of model- and user-invocable skills; no direct browser skill-loading RPC is added.
|
||||
|
||||
These rules permit all four combinations:
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ skill 注册表最初将发现操作视为模型目录：`ctx.skills.list()` 会
|
||||
|
||||
本地提供方只接受拼写完全一致的 kebab-case frontmatter 键 `disable-model-invocation` 和 `user-invocable`。它接受 YAML 布尔值，以及不区分大小写的 `true`/`false`、`yes`/`no`、`on`/`off` 和 `1`/`0`，与 Claude skills 实际支持的布尔写法一致。它将 `disable-model-invocation` 映射为相反的正向字段，即使两个键都不存在，也会根据默认值填充两个正向字段。若使用外部驼峰式拼写或提供非布尔调用值，发现流程会丢弃整个 skill，并给出有针对性的警告；本仓库尚处于发布前阶段，因此不为磁盘格式保留兼容别名。调用数据校验遵循失败时默认拒绝原则，因为忽略这类数据会默认授予权限，可能使 skill 暴露在已禁用的接口上；与之不同，类型错误的可选 `whenToUse` 和 `metadata` 值会被省略，因为它们不参与调用判定。
|
||||
|
||||
面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地执行用户字段，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill peer 变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh experimental-upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。
|
||||
面向模型的 `dsh-tool-skill` 目录和 loader 执行 `isModelInvocable`。TUI 的 `/skill:` 自动补全与精确名称 loader 在本地执行用户字段，因此仅允许用户调用的 skill 即使不出现在模型发现结果中，仍会在此处显示并可加载，同时不会将可选的 skill peer 变成运行时导入。由 launcher 预置、供引导式 `dsh migrate` 和 `dsh upgrade` 会话使用的初始 skill 沿用同一条 TUI 路径，因此必须保持允许用户调用。浏览器的 `skill.list` RPC 提供的是由用户选择、但仍要求模型加载的引用，因此只公开同时允许模型和用户调用的 skill；本次改动不新增让浏览器直接加载 skill 的 RPC。
|
||||
|
||||
这些规则允许以下四种组合：
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# 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 .agents/notes/implemented/feature/2026-07-31-experimental-subcommand-gate.md
|
||||
2026-07-31-experimental-subcommand-gate.md: 41447c2d23bc71964f990298de3c48b2fe7ef309
|
||||
2026-07-31-experimental-subcommand-gate.zh.md: 35598a61d98ff7490b34d175fc915043f5b5236a
|
||||
@@ -0,0 +1,35 @@
|
||||
# Agent Note: experimental subcommands gate behind `--experimental` or `DSH_EXPERIMENTAL=1`
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-31-experimental-subcommand-gate.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The `meta` and `upgrade` entry points carried their experimental status in their names: `dsh experimental-meta` and `dsh experimental-upgrade`. The prefix made every invocation verbose, and renaming a command at stabilization would break every reference to it — muscle memory, scripts, and docs alike. The status belongs in an opt-in gate, not in the name.
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh experimental-meta` is `dsh meta` and `dsh experimental-upgrade` is `dsh upgrade`. Each runs only when the invocation passes its `--experimental` flag or the environment carries `DSH_EXPERIMENTAL=1`; otherwise the command fails loud on stderr with exit 1, naming both opt-ins. Per the pre-release stance, the old names are gone with no aliases, and `args.spec.ts` pins their rejection.
|
||||
|
||||
The gate has two halves with one owner each. The per-invocation half is a Commander `--experimental` option on each experimental subcommand, checked inside its action after the leaked-parent-option rejection. The environment half is a boolean `parseDshArgs` parameter: `bin.ts` reads `process.env.DSH_EXPERIMENTAL === '1'` at the process boundary (after `loadEnv`, so a project `.env` can set it) and passes the result down, so the parser's environment dependency is explicit in its signature and the tests need no env mutation. `1` is the only enabling value — the variable is an explicit opt-in, not a truthiness check.
|
||||
|
||||
Stabilizing a command later means deleting its `--experimental` option and `requireExperimental` call; the name does not move.
|
||||
|
||||
## Testing
|
||||
|
||||
`args.spec.ts` pins both admit paths, bare-name rejection, old-name rejection, and leaked-option rejection under the env opt-in. `built-bin.e2e.ts` proves the assembled entry end to end: the gate diagnostic on stderr with exit 1, and that `--experimental`, `DSH_EXPERIMENTAL=1`, but not `DSH_EXPERIMENTAL=0`, reach the TUI's piped-stdio refusal — the next gate past this one. Both gated commands were also verified interactively in tmux: `dsh meta --experimental` and `DSH_EXPERIMENTAL=1 dsh meta` boot the TUI over the checkout, and `DSH_EXPERIMENTAL=1 dsh upgrade` seeds the `dsh-upgrade` skill.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the `experimental-` name prefix.** Rejected by the user's direction: the prefix taxes every invocation, and stabilization would be a breaking rename instead of deleting a gate.
|
||||
|
||||
**A parent-level `--experimental` flag (`dsh --experimental meta`).** Rejected: the default surface is deliberately option-only with `enablePositionalOptions`, so parent options that leak across the subcommand boundary are treated as mistyped invocations. A parent flag consumed only by two subcommands would be exactly the leaked-option shape the adapter rejects everywhere else.
|
||||
|
||||
**Read `process.env` inside `parseDshArgs`.** Rejected: the repo validates at the process boundary and keeps typed seams pure; tests would have to mutate and restore `process.env` around each case.
|
||||
|
||||
**Accept any non-empty `DSH_EXPERIMENTAL`.** Rejected: the telemetry switch prefers off-by-mistake for a privacy control, but an experimental gate is an acknowledgement — `DSH_EXPERIMENTAL=0` must not enable the commands it names.
|
||||
|
||||
## Consequences
|
||||
|
||||
Daily invocations shorten to `dsh meta --experimental` and `dsh upgrade --experimental`, and a developer who sets `DSH_EXPERIMENTAL=1` in their environment gets the bare `dsh meta`/`dsh upgrade`. `dsh --help` marks both commands `(experimental)`. The gate costs one extra flag or env var until a command stabilizes, at which point the gate is deleted and the name is already final.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Agent Note：实验性子命令由 `--experimental` 或 `DSH_EXPERIMENTAL=1` 把守
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-31-experimental-subcommand-gate.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
`meta` 与 `upgrade` 两个入口把实验性状态写在名字里：`dsh experimental-meta` 和 `dsh experimental-upgrade`。前缀让每次调用都变得冗长，而在稳定时重命名命令会破坏对它的所有引用——肌肉记忆、脚本与文档皆然。这种状态应当由一个显式选择加入的门槛承载，而不是由名字承载。
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh experimental-meta` 改为 `dsh meta`，`dsh experimental-upgrade` 改为 `dsh upgrade`。二者只有在调用时传入各自的 `--experimental` 标志、或环境中带有 `DSH_EXPERIMENTAL=1` 时才会运行；否则命令在 stderr 上明确报错并以退出码 1 结束，同时指明两种选择加入方式。依据发布前立场，旧名称已移除且没有别名，`args.spec.ts` 钉住了对它们的拒绝。
|
||||
|
||||
该门槛分为两半，各有其归属。按调用的一半是每个实验性子命令上的 Commander `--experimental` 选项，在其 action 内、泄漏父级选项的拒绝之后检查。环境的一半是 `parseDshArgs` 的一个布尔参数：`bin.ts` 在进程边界读取 `process.env.DSH_EXPERIMENTAL === '1'`（在 `loadEnv` 之后，因此项目 `.env` 也可以设置它）并向下传递结果，因此解析器对环境的依赖显式体现在签名中，测试也无需改动环境变量。`1` 是唯一的启用值——该变量是显式的选择加入，而不是真值判断。
|
||||
|
||||
之后要稳定某个命令，只需删除它的 `--experimental` 选项和 `requireExperimental` 调用；名字不再变动。
|
||||
|
||||
## Testing
|
||||
|
||||
`args.spec.ts` 钉住两条准入路径、裸名称拒绝、旧名称拒绝，以及在环境选择加入下对泄漏选项的拒绝。`built-bin.e2e.ts` 端到端地证明组装后的入口：stderr 上的门槛诊断与退出码 1，以及 `--experimental`、`DSH_EXPERIMENTAL=1`（而非 `DSH_EXPERIMENTAL=0`）会到达 TUI 的管道 stdio 拒绝——即此门之后的下一道关卡。两个被把守的命令还在 tmux 中做了交互式验证：`dsh meta --experimental` 与 `DSH_EXPERIMENTAL=1 dsh meta` 以检出目录为 workspace 启动 TUI，`DSH_EXPERIMENTAL=1 dsh upgrade` 播种 `dsh-upgrade` skill。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**保留 `experimental-` 名称前缀。** 按用户的指示拒绝：前缀让每次调用都付出代价，稳定时也会变成破坏性的重命名，而不是删除一个门槛。
|
||||
|
||||
**父级 `--experimental` 标志（`dsh --experimental meta`）。** 拒绝：默认界面刻意保持纯选项形式并启用 `enablePositionalOptions`，跨子命令边界泄漏的父级选项都被视为拼错的调用。一个只被两个子命令消费的父级标志，恰恰就是适配器在其他所有地方都拒绝的泄漏选项形态。
|
||||
|
||||
**在 `parseDshArgs` 内部读取 `process.env`。** 拒绝：本仓库在进程边界做验证，并保持类型化接缝的纯粹性；否则测试必须在每个用例前后修改并恢复 `process.env`。
|
||||
|
||||
**接受任何非空的 `DSH_EXPERIMENTAL`。** 拒绝：遥测开关作为隐私控制倾向于误关而非误开，但实验性门槛是一种确认——`DSH_EXPERIMENTAL=0` 绝不能启用它所指名的命令。
|
||||
|
||||
## Consequences
|
||||
|
||||
日常调用缩短为 `dsh meta --experimental` 和 `dsh upgrade --experimental`；在环境中设置了 `DSH_EXPERIMENTAL=1` 的开发者可以直接使用 `dsh meta`/`dsh upgrade`。`dsh --help` 将这两个命令标注为 `(experimental)`。在命令稳定之前，门槛的代价是一个额外的标志或环境变量；稳定时删除门槛即可，名字已是最终形态。
|
||||
Reference in New Issue
Block a user