Merge origin/master into xjt/proofreading-active-docs-2-apply
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/architecture/2026-07-05-reconstructable-requests.md
|
||||
2026-07-05-reconstructable-requests.md: 153d37a2faf2265134d5ff9e88f0bbfa275328e0
|
||||
2026-07-05-reconstructable-requests.zh.md: ec4f9f0fe20315b4ac73be4aa170361b91ffdd29
|
||||
2026-07-05-reconstructable-requests.zh.md: 25ce6bfdb56db80c92e8293206484a2de505d662
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 每个 LLM（大语言模型）请求都可从会话日志重建
|
||||
# Agent Note: 每个 LLM 请求都可从会话日志重建
|
||||
|
||||
Status: implemented
|
||||
|
||||
|
||||
@@ -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/architecture/2026-07-08-tool-output-spill-files.md
|
||||
2026-07-08-tool-output-spill-files.md: 7c0ca90452645d251559be25108d12883210d00e
|
||||
2026-07-08-tool-output-spill-files.zh.md: 6c25b03fe23976b9a2f50edb0c3de3cdd782a4ff
|
||||
2026-07-08-tool-output-spill-files.zh.md: a1bde1131374cd11215006b822dfc19aea707747
|
||||
|
||||
@@ -174,7 +174,7 @@ ctx.tools.register(defineTool({
|
||||
|
||||
默认策略只能看见最终格式化文本。它无法保留已经由提供方限制的内部内容，也无法保留从未成为结果一部分的运行时产物。第一版聚焦最终结果落盘而不是提前落盘，因此可以接受这一限制；由工具负责的提前落盘仍属于后续工作。
|
||||
|
||||
本地后端返回真实路径，使 v1 保持简单并符合已经验证的 agent 工具行为；seam 本身只承诺一个不透明定位符加检索提示，所以远程后端可以返回非文件定位符。
|
||||
本地后端返回真实路径，使 v1 保持简单并符合已经验证的 agent（智能体）工具行为；seam 本身只承诺一个不透明定位符加检索提示，所以远程后端可以返回非文件定位符。
|
||||
|
||||
本地后端的价值取决于现有 `read`／`grep` 工具能否检查返回的本地路径，即使落盘目录位于会话 cwd 之外。目前这一条件成立，因为文件系统策略会记录观察结果并设置写保护，但不会把读取限制在工作区内。未来的工作区限制策略必须显式允许本地落盘路径，或改用检索提示指向受支持读取器的非文件落盘后端。
|
||||
|
||||
|
||||
@@ -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/bug-fix/2026-07-22-pi-ai-transport-truncation-classification.md
|
||||
2026-07-22-pi-ai-transport-truncation-classification.md: 119200a788c0b0521f385f4cf4e6adf05a0512f9
|
||||
2026-07-22-pi-ai-transport-truncation-classification.zh.md: e8bf9efc6c131f6ce9e22c94f29d53ef85329a6f
|
||||
2026-07-22-pi-ai-transport-truncation-classification.zh.md: 0625d6041ccaeaff9d0d6f659c7b3856ab985ef6
|
||||
|
||||
@@ -8,7 +8,7 @@ Status: implemented
|
||||
|
||||
一次 TUI 运行的模型连接在流式输出中途断开，只浮现出一条 `terminated` 通知，而一个被截断的 Anthropic 响应则浮现出 `Anthropic stream ended before message_stop`。两者都是传输层截断——连接在提供方的终止 SSE（Server-Sent Events）事件之前就已断开——然而 `dsh-llm-pi-ai` 中的 `classifyPiAiError` 对两者都不匹配，最终落入兜底的 `PI_AI_ERROR`。由于 `PI_AI_ERROR` 不在 `llm-retry` 的 `DEFAULT_RETRYABLE_CODES`（`RATE_LIMIT`、`SERVER`、`TIMEOUT`、`TRANSPORT`）中，一次可恢复的断开被当作永久性失败处理，从未被重试。
|
||||
|
||||
细节丢失发生在上游，且在适配器内无法恢复：pi-ai 在推送终止 `error` 事件之前，把捕获到的错误缩减为 `error.message`（`api/anthropic-messages.js`：`errorMessage = error instanceof Error ? error.message : JSON.stringify(error)`），丢弃了原始的 `Error` 及其 `cause` 链。undici 将可用于诊断的 `SocketError` 放在 `cause` 上，却只交给 fetch 包装层一个裸的 `terminated`；pi-ai 只保留了这个词。pi-ai 的 `SimpleStreamOptions` 没有暴露任何 fetch/dispatcher/client 钩子，让我们能在细节被扁平化之前自行捕获 `cause`。
|
||||
细节丢失发生在上游，且在适配器内无法恢复：pi-ai 在推送终止 `error` 事件之前，把捕获到的错误缩减为 `error.message`（`api/anthropic-messages.js`：`errorMessage = error instanceof Error ? error.message : JSON.stringify(error)`），丢弃了原始的 `Error` 及其 `cause` 链。undici 将可据以采取行动的 `SocketError` 放在 `cause` 上，却只交给 fetch 包装层一个裸的 `terminated`；pi-ai 只保留了这个词。pi-ai 的 `SimpleStreamOptions` 没有暴露任何 fetch/dispatcher/client 钩子，让我们能在细节被扁平化之前自行捕获 `cause`。
|
||||
|
||||
## 决策
|
||||
|
||||
|
||||
@@ -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/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md
|
||||
2026-07-19-fresh-agent-ralph-workflow-tool.md: 6fe96587c49ef0316d1618fda2ee26b015b1ce87
|
||||
2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 04b7db3f8e80fe16100836e06a26c5b43ccaeaa4
|
||||
2026-07-19-fresh-agent-ralph-workflow-tool.zh.md: 03e5e4a705674b49c14cbb456b06d82fbd38f013
|
||||
|
||||
@@ -64,7 +64,7 @@ Ralph 插件的 `subagentProvider` 默认为 `spawn`。每次调用前，它要
|
||||
- 宽裕的 Round 上限允许大量自治工作，而部署配置仍会限制子 agent 数量，并且每次交接始终受大小约束。
|
||||
- 提供方路由与可降低的每次运行子 agent 上限成为显式的工作流启动关注点，但不扩展脚本或普通工作流工具表面。
|
||||
|
||||
## 已知限制与推迟工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- 完成与阻塞状态由工作者自行声明。独立 evaluator、evaluator 驱动的反馈 Round、完成证书或对抗式 verifier 被有意推迟。
|
||||
- 运行位于前台且只存在于进程内。后台收集、持久化/恢复、调度和重启恢复均不存在。
|
||||
|
||||
@@ -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/feature/2026-07-19-human-goal-command.md
|
||||
2026-07-19-human-goal-command.md: ce5c37fd28f9432d8c9a8797cac32c632617e317
|
||||
2026-07-19-human-goal-command.zh.md: fb7b5f2e5b49eb3ac713dca43a1dab72c08e10dc
|
||||
2026-07-19-human-goal-command.zh.md: 85b47f610d12d5a70a4978e2041c8b38cd2895b0
|
||||
|
||||
@@ -63,7 +63,7 @@ TUI 应用包作出相反的产品选择。它默认让 `goals` 使用所有者
|
||||
- 恢复后的会话等待人类决策；`/goal resume` 是字面命令路径，任何语言的普通提示词则可以授权模型工具路径。
|
||||
- 无头组合保持单轮行为，除非明确选择加入目标并定义自己的长时间运行结束契约。
|
||||
|
||||
## 已知限制与延期工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- 可移植命令契约没有模态编辑器或确认交互；在出现通用跨界面交互原语之前，行内编辑与明确清除是有意选择。
|
||||
- `/goal` 不接受逐命令 Round 上限。部署配置拥有默认值；得到直接人类指示后，已授权模型工具可以编辑上限。
|
||||
|
||||
@@ -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/feature/2026-07-19-model-facing-goal-tools.md
|
||||
2026-07-19-model-facing-goal-tools.md: 18235c484194f5daf10556ebfc13bdc2d672be2e
|
||||
2026-07-19-model-facing-goal-tools.zh.md: 79e1f14636ecaab4eb28c633b565e6f33f191c74
|
||||
2026-07-19-model-facing-goal-tools.zh.md: c8bc49ef907e4055960074c6a7d1e852ba77c9ad
|
||||
|
||||
@@ -8,7 +8,7 @@ Status: implemented
|
||||
|
||||
持久目标领域有意把生命周期动词提供给插件，而不直接提供给模型。模型仍然需要一个小型控制面，用于发现当前目标、根据人类意图创建目标并改变其生命周期。仅靠提示词指导无法确定是谁授权了一次变更：子智能体、注入的插件消息、陈旧的模型轮次或恢复后的会话都可能产生相同的工具参数。
|
||||
|
||||
该表面还需要保持持久状态与实时执行权限之间的分离。恢复或 fork（派生）后的会话可以回放活跃目标，但初始处于未激活状态；后续人类提出“继续”之类的请求时，模型应能重新激活目标，而无需用户使用字面命令。相反，已接纳的自主目标回合必须能够报告完成或持续阻塞，却不能因此获得编辑、暂停、恢复或替换人类目标的权限。
|
||||
该表面还需要保持持久状态与实时执行权限之间的分离。恢复或 fork（派生）后的会话可以回放活跃目标，但初始处于未激活状态；后续人类提出“继续”之类的请求时，模型应能重新激活目标，而无需用户使用字面命令。相反，已接纳的自主 Goal Round 必须能够报告完成或持续阻塞，却不能因此获得编辑、暂停、恢复或替换人类目标的权限。
|
||||
|
||||
## 决策
|
||||
|
||||
@@ -16,13 +16,13 @@ Status: implemented
|
||||
|
||||
### 工具与模型契约
|
||||
|
||||
`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大目标回合数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅对 `edit` 有效，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。执行器把值恰好为空字符串的可选字段和值为 0 的 `max_goal_rounds` 视为严格 schema 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。
|
||||
`get_goal()` 返回当前目标或 `null`。非空结果包含用于比较并交换的 id 与修订号、目标描述、持久阶段、已接纳和最大 Goal Round 数、可能存在的阻塞原因，以及进程本地激活态观察。`create_goal(objective, max_goal_rounds?)` 创建一个长时间运行的同会话目标。`update_goal(goal_id, revision, action, objective?, max_goal_rounds?, blocked_reason?)` 支持 `edit`、`pause`、`resume`、`complete` 和 `blocked`；替换字段仅对 `edit` 有效，非空的 `blocked_reason` 仅在 `blocked` 时必填，并以稳定代码 `model-reported` 持久化。执行器把值恰好为空字符串的可选字段和值为 0 的 `max_goal_rounds` 视为严格 schema 占位值：这些值等同于省略；编辑时仍必须提供至少一个有实际意义的替换字段；所有非占位值仍受对应操作的限制。
|
||||
|
||||
提示词告诉模型：它可以从任何措辞或语言的直接人类请求中推断目标意图，但不应把常规单轮工作转换为目标。更新前必须读取当前目标，并复制准确的 id 和修订号。对于恢复或派生后处于活跃但未激活状态的目标，人类在语义上要求继续即可成为执行 `resume` 的依据。只有目标已经实现时才能标记完成，困难或不确定性本身不构成阻塞；阻塞报告必须说明具体条件。
|
||||
|
||||
三个工具都采用独占执行，使模型排序的批次可以观察此前变更及其新修订号。结果为紧凑 JSON。UI 展示是参数的纯函数，使用通用读取或变更卡片；变更卡片选择输入时，先取有实际意义的操作值，再取目标 id，因此允许的占位值不会使卡片输入留空。激活态仅作为实时观察返回，绝不会写入回放状态。
|
||||
|
||||
自主目标回合成功报告完成或阻塞后，其工具结果会附带一条收尾指令，模型仍会在轮次经由常规无工具调用停止路径结束前向用户发言；原先在结果处终结轮次的做法已被[Goal Round 收尾决策](../bug-fix/2026-08-02-goal-round-wrapup-message.md)取代。直接人类发起的变更不会收到指令：agent 可以确认该变更，并且并发的人类 steering（中途引导）仍可参与普通的停止检查。
|
||||
自主 Goal Round 成功报告完成或阻塞后，其工具结果会附带一条收尾指令，模型仍会在轮次经由常规无工具调用停止路径结束前向用户发言；原先在结果处终结轮次的做法已被[Goal Round 收尾决策](../bug-fix/2026-08-02-goal-round-wrapup-message.md)取代。直接人类发起的变更不会收到指令：agent 可以确认该变更，并且并发的人类 steering（中途引导）仍可参与普通的停止检查。
|
||||
|
||||
### 执行权限
|
||||
|
||||
@@ -30,15 +30,15 @@ Status: implemented
|
||||
|
||||
创建、编辑、暂停与恢复还要求运行时根 agent 的当前轮次已经接纳一条用户消息或用户 steering 事件。根所有权来自实时 agent 图，而非持久的 fork 祖先关系：恢复后的派生会话可以接收新的直接人类权限，实时子级则仍是 subagent，不能改变这些状态。用户来源是宿主的证明：每个 `Agent.send()` 或 `steer()` 输入都必须显式提供来源，因此宿主把直接人类内容标为 `{ kind: 'user' }`，非人类生产者则标注自己的来源信息。运行时证明来源，而不判断人类措辞在语义上是否足以创建或恢复目标；该解释仍由模型完成。
|
||||
|
||||
完成与阻塞既接受直接人类权限，也接受准确的当前目标回合。目标回合权限要求存在一条来源为目标的 `user/message`，其中目标 id、修订号和回合都与折叠后的当前目标相等。它只授予这两种终止报告权限。直接人类权限可以立即停止目标。
|
||||
完成与阻塞既接受直接人类权限，也接受准确的当前 Goal Round。Goal Round 权限要求存在一条来源为目标的 `user/message`，其中目标 id、修订号和 Round 都与折叠后的当前目标相等。它只授予这两种终止报告权限。直接人类权限可以立即停止目标。
|
||||
|
||||
### 阻塞阈值
|
||||
|
||||
`blockedAfterConsecutiveRounds` 是经过校验的正安全整数配置，默认值为 `3`。自主目标回合调用 `blocked` 时，插件会机械地要求至少已经接纳该数量的回合并提供非空说明；配置值也会出现在模型指导中。运行时无法判断这些回合是否遇到了语义上相同的阻塞条件，因此语义等价性仍由模型判断。该计数特意与目标的宽裕继续执行上限分离。
|
||||
`blockedAfterConsecutiveRounds` 是经过校验的正安全整数配置，默认值为 `3`。自主 Goal Round 调用 `blocked` 时，插件会机械地要求至少已经接纳该数量的 Round 并提供非空说明；配置值也会出现在模型指导中。运行时无法判断这些 Round 是否遇到了语义上相同的阻塞条件，因此语义等价性仍由模型判断。该计数特意与目标的宽裕继续执行上限分离。
|
||||
|
||||
## 测试
|
||||
|
||||
单元测试固定注册与释放、独占调度、生成的提示词策略、可安全处理占位值的通用展示、非英语轮次中的直接人类创建、精确/陈旧/非运行中智能体与驱动检查、实时子智能体拒绝、恢复后派生根的权限、steering、发起者不匹配、读取/创建/部分字段编辑/暂停/恢复行为（包括严格 schema 占位值）、条件式阻塞说明、会话启动边沿后的重新激活、权限先于条件参数失败、准确目标回合的完成、仅自主回合触发终止、可配置阻塞阈值，以及人类立即阻塞。无密钥回放快照把目标领域和工具挂载到真实的 headless 单次运行应用中，通过随附循环与持久化栈驱动一次携带严格 schema 占位值的 `update_goal` 探测，以及对 `create_goal` 和 `get_goal` 的调用，固定 stream-json 转录，并检查外部持久化的目标变更。这里有意不把 echo-agent 测试夹具当作应用 UX 的替代品。
|
||||
单元测试固定注册与释放、独占调度、生成的提示词策略、可安全处理占位值的通用展示、非英语轮次中的直接人类创建、精确/陈旧/非运行中智能体与驱动检查、实时子智能体拒绝、恢复后派生根的权限、steering、发起者不匹配、读取/创建/部分字段编辑/暂停/恢复行为（包括严格 schema 占位值）、条件式阻塞说明、会话启动边沿后的重新激活、权限先于条件参数失败、准确 Goal Round 的完成、仅自主 Round 触发终止、可配置阻塞阈值，以及人类立即阻塞。无密钥回放快照把目标领域和工具挂载到真实的 headless 单次运行应用中，通过随附循环与持久化栈驱动一次携带严格 schema 占位值的 `update_goal` 探测，以及对 `create_goal` 和 `get_goal` 的调用，固定 stream-json 转录，并检查外部持久化的目标变更。这里有意不把 echo-agent 测试夹具当作应用 UX 的替代品。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
@@ -55,14 +55,14 @@ Status: implemented
|
||||
- 模型获得稳定而紧凑的生命周期表面，无需直接访问目标服务。
|
||||
- 改变状态的调用同时受到实时运行时来源与持久比较并交换引用的约束。
|
||||
- 人类可以通过普通自然语言请求创建和重新激活目标，而恢复后的会话在收到此类输入前保持静止。
|
||||
- 目标回合可以完成或报告重复阻塞，但不能自行扩大任务权限。
|
||||
- Goal Round 可以完成或报告重复阻塞，但不能自行扩大任务权限。
|
||||
- 部署策略选择阻塞下限；同一个解析后的值同时控制执行与提示词指导。
|
||||
- 系统可兼容采用严格 schema 的提供方所填入的占位值，同时不会放行有实际意义的跨操作更新。
|
||||
|
||||
## 已知限制与延期工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- 是否属于重大目标、是否要求继续、目标是否完成以及阻塞条件是否相同，仍由模型进行语义分类。独立评估器或完成证书予以延期。
|
||||
- 这些工具会改变目标状态，但不调度目标回合、不分类异常驱动停止，也不取消活跃轮次；这些行为由同会话驱动器负责。
|
||||
- 除非另行挂载的继续执行驱动器接纳了目标来源的用户轮次，否则目标回合权限路径处于休眠状态；本工具包本身不会制造这种权限。
|
||||
- 这些工具会改变目标状态，但不调度 Goal Round、不分类异常驱动停止，也不取消活跃轮次；这些行为由同会话驱动器负责。
|
||||
- 除非另行挂载的继续执行驱动器接纳了目标来源的用户轮次，否则 Goal Round 权限路径处于休眠状态；本工具包本身不会制造这种权限。
|
||||
- 面向人类的斜杠命令发现与渲染由独立的 [`dsh-command-goal`](../../../../packages/goal/command-goal/README.md) 插件负责。
|
||||
- 若部署没有同时设定两个注册项的作用域，某个作用域可能隐藏工具注册，却保留独立注册的提示词段。
|
||||
|
||||
@@ -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/feature/2026-07-19-persisted-same-session-goal-domain.md
|
||||
2026-07-19-persisted-same-session-goal-domain.md: 00600b2c49646ebd3b692154ef945eb79a33b032
|
||||
2026-07-19-persisted-same-session-goal-domain.zh.md: 325dfb2c301024738da8a39774af02c2a13caddc
|
||||
2026-07-19-persisted-same-session-goal-domain.zh.md: 00a75eebbad40b4551711c47fbf654684092a5e6
|
||||
|
||||
@@ -12,7 +12,7 @@ Status: implemented
|
||||
|
||||
## 决策
|
||||
|
||||
位于 `packages/goal/goal/` 的 `@deepseek-ai/dsh-goal` 通过 `ctx.goals` 管理一个当前的同会话目标。目标包含带品牌的 id、目标描述、持久化阶段、比较并交换修订号和 `maxGoalRounds`。`defaultMaxGoalRounds` 是经过校验的部署配置，默认值为 `256`；`create()` 在变更前于内部将其解析为完整值，而不会把解析过程暴露为额外的服务方法。
|
||||
位于 `packages/goal/goal/` 的 `@deepseek-ai/dsh-goal` 通过 `ctx.goals` 管理一个当前的同会话目标。目标包含带品牌的 id、目标描述、持久化阶段、比较并交换修订号和 `maxGoalRounds`。`defaultMaxGoalRounds` 是经过校验的部署配置，默认值为 `256`；`create()` 在变更前于内部将其解析为完整值，而不会把解析过程暴露为额外的服务动词。
|
||||
|
||||
持久阶段包括 `active`、`paused`、`blocked` 和 `complete`。阻塞快照包含由策略定义的全小写 kebab-case 代码和规范化自由文本消息，因此用量限制、回合上限、执行失败和等待人工输入可以共享一个生命周期状态而不丢失原因。独立的实时激活态为 `armed` 或 `disarmed`。创建与显式恢复会激活目标；暂停、完成、阻塞和清除都会解除激活。编辑保留激活态及阻塞原因；恢复和完成会清除该原因。持久快照绝不包含激活态。
|
||||
|
||||
@@ -20,7 +20,7 @@ Status: implemented
|
||||
|
||||
每次非清除变更都通过 `Agent.inject()` 追加一条模型可见的 `context/message`，其中包含带版本的完整快照；会话会将其内容原样投射给模型。清除操作追加带修订号的墓碑。上下文来源为 `{ kind: 'goal', goalId, revision, round: 0 }`；元数据必须与渲染后的 `<goal_state>...</goal_state>` 内容完全一致。这个描述性分隔符沿用了仓库已有的 `<workspace_context>` 约定，也符合 [Anthropic 关于用一致且描述明确的 XML 标签组织混合提示词内容的公开指南](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#structure-prompts-with-xml-tags)。这是公开的模型体验先例，并非对任何提供方专有训练语料的推断。会话日志是唯一的持久真源，因此持久化和 fork 会继承目标记录，而无需另设数据库或头字段。
|
||||
|
||||
回放折叠会校验 JSON 形状、来源归属、渲染内容、从未出现过的 id、修订连续性、生命周期转换、计数器以及单个目标内单调递增的时间戳。目标回合是当前活跃修订上带正数且连续编号的 `user/message` 来源，且不能超过 `maxGoalRounds`；普通会话轮次不会影响该计数器。当前格式的畸形记录会使回放失败，而不会被忽略或修复。
|
||||
回放折叠会校验 JSON 形状、来源归属、渲染内容、从未出现过的 id、修订连续性、生命周期转换、计数器以及单个目标内单调递增的时间戳。Goal Round 是当前活跃修订上带正数且连续编号的 `user/message` 来源，且不能超过 `maxGoalRounds`；普通会话轮次不会影响该计数器。当前格式的畸形记录会使回放失败，而不会被忽略或修复。
|
||||
|
||||
当 `Agent.inject()` 在活跃工具批次中延迟变更时，服务会在进程内存中以覆盖层记录已接受的载荷，使后续变更可以使用新的修订号。FIFO 追加可见后，协调过程只移除完全匹配的载荷；重入的追加观察器对每次变更只投影一次。增量回放会在每个有效事件后推进游标，并停留在首个损坏事件处，因此后续读取会报告同一个持久故障。重启后仍以持久日志为准。
|
||||
|
||||
@@ -36,14 +36,14 @@ Status: implemented
|
||||
|
||||
## 测试
|
||||
|
||||
单元测试固定创建默认值、精确实时 agent 校验、比较并交换拒绝、所有生命周期转换、阻塞原因校验与保留、恢复时的上限执行、清除与替换、种子回放和 `SessionStore.fork()` 继承、会话启动与生命周期所有者解除激活、活跃目标重新激活、FIFO 延迟变更协调、重入追加观察、注入拒绝回滚、损坏事件的稳定回放、服务与监听器销毁、监听器隔离、挂钟回拨校正、严格记录解码、生命周期连续性、来源与内容一致性，以及连续目标回合归属。无密钥 Loader/stdio 进程测试通过测试专用 `cordis.yml` 挂载服务与生命周期消费者，再从外部读取持久 JSONL，以验证模型可见快照以及不存在未经请求的目标回合。包源码受仓库逐文件 100% 覆盖率门禁约束。
|
||||
单元测试固定创建默认值、精确实时 agent 校验、比较并交换拒绝、所有生命周期转换、阻塞原因校验与保留、恢复时的上限执行、清除与替换、种子回放和 `SessionStore.fork()` 继承、会话启动与生命周期所有者解除激活、活跃目标重新激活、FIFO 延迟变更协调、重入追加观察、注入拒绝回滚、损坏事件的稳定回放、服务与监听器销毁、监听器隔离、挂钟回拨校正、严格记录解码、生命周期连续性、来源与内容一致性，以及连续 Goal Round 归属。无密钥 Loader/stdio 进程测试通过测试专用 `cordis.yml` 挂载服务与生命周期消费者，再从外部读取持久 JSONL，以验证模型可见快照以及不存在未经请求的 Goal Round。包源码受仓库逐文件 100% 覆盖率门禁约束。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
- **把目标存入独立数据库或会话头**——不予采纳，因为会话日志已经提供顺序、持久化、fork 前缀与可重建性；第二份存储会引入原子性和谱系问题。
|
||||
- **使用模型不可见的纯日志事件**——不予采纳，因为会改变后续模型行为的持久状态必须满足仓库日志不变量，保持模型可见且可重建。
|
||||
- **持久化激活态并自动重启**——不予采纳，因为打开或恢复会话时必须等待人类输入；持久阶段记录状态，而不是再次消耗资源的授权。
|
||||
- **把所有会话轮次都计为目标回合**——不予采纳，因为同一会话可以包含人类澄清、检查和无关工作；只有归属于目标的继续执行轮次才消耗该预算。
|
||||
- **把所有会话轮次都计为 Goal Round**——不予采纳，因为同一会话可以包含人类澄清、检查和无关工作；只有归属于目标的继续执行轮次才消耗该预算。
|
||||
- **向 `dsh-agent-loop` 添加目标状态或通用循环抽象**——不予采纳，因为状态与继续执行策略可以通过现有插件、`Agent` 动词和事件组合，而无需赋予默认循环实现特权。
|
||||
|
||||
## 后果
|
||||
@@ -56,7 +56,7 @@ Status: implemented
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- 本领域记录状态，但不调度目标回合、不取消活跃轮次，也不分类异常停止。
|
||||
- 本领域记录状态，但不调度 Goal Round、不取消活跃轮次，也不分类异常停止。
|
||||
- 记录 `complete` 或 `blocked` 的参与者具有最终权威；独立评估器或完成证书延期到策略消费者中实现。
|
||||
- 每个会话只有一个当前目标；不存在并行目标图和跨会话目标存储。
|
||||
- 插件共享同一个受信任的进程边界。直接写入会话的插件可以伪造目标记录；严格回放会检测不一致并在违规记录处使目标访问失败，但不会隔离插件或修复日志。
|
||||
|
||||
@@ -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/feature/2026-07-19-same-session-goal-round-driver.md
|
||||
2026-07-19-same-session-goal-round-driver.md: 0e6be9fe3109336d47867ab52c585dc267309fb4
|
||||
2026-07-19-same-session-goal-round-driver.zh.md: 7533fe968a9dd2b7a8d6ad183d1b6bf2dcda6715
|
||||
2026-07-19-same-session-goal-round-driver.zh.md: 9f535dd3b0bf49fff5ff962b04b89330d0b27a55
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 同会话目标回合驱动器
|
||||
# Agent Note: 同会话 Goal Round 驱动器
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -14,7 +14,7 @@ Status: implemented
|
||||
|
||||
位于 `packages/goal/goal-session/` 的 `@deepseek-ai/dsh-goal-session` 是构建在 `ctx.goals`、公共 `Agent` 接口和持久会话事件之上的策略插件。它不导入具体 agent-loop 实现。对于每个对应的同一个实时 `Agent` 对象，它维护进程内调度状态，并且最多保留一个自动回合预留。
|
||||
|
||||
层次关系为目标（Goal）→ 目标回合（Goal Round）→ 轮次（Turn）→ 步骤（Step）。目标回合是外层继续执行策略的一次迭代；它会成为一个归属于目标的会话轮次，而该轮次可以包含任意数量的普通模型或工具步骤。同一会话中的人类轮次不是目标回合，也绝不会增加 `roundsStarted`。
|
||||
层次关系为目标（Goal）→ Goal Round → 轮次（Turn）→ 步骤（Step）。Goal Round 是外层继续执行策略的一次迭代；它会成为一个归属于目标的会话轮次，而该轮次可以包含任意数量的普通模型或工具步骤。同一会话中的人类轮次不是 Goal Round，也绝不会增加 `roundsStarted`。
|
||||
|
||||
该插件没有配置项。`maxGoalRounds` 由 `dsh-goal` 解析并持久化；“相同阻塞条件”的门槛由 `dsh-tool-goal` 解析并写入提示词。若驱动器重复声明这些可调值，一个策略就会出现多个所有者。
|
||||
|
||||
@@ -24,11 +24,11 @@ Status: implemented
|
||||
|
||||
`agent/prompt-submit` waterfall（瀑布式事件）是接纳栅栏。正数目标来源只有在完全匹配驱动器待处理的身份和内容、实时目标仍具有相同 id 与修订号、激活态仍为 armed，并且该回合仍是下一个编号时才会获准。插件在委托下游监听器前检查一次，在下游返回后再检查一次。第二次检查防止异步钩子编辑或暂停目标后，旧提示词仍被接纳。
|
||||
|
||||
只有最终产生的 `user/message` 才是已接纳目标回合，并推进目标折叠。陈旧预留会在轮次打开前被丢弃；驱动器会把它标记为陈旧，不消耗回合数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。
|
||||
只有最终产生的 `user/message` 才是已接纳 Goal Round，并推进目标折叠。陈旧预留会在轮次打开前被丢弃；驱动器会把它标记为陈旧，不消耗 Round 数。若下游策略拒绝并非由陈旧状态导致，目标会进入 blocked，而不会绕过该策略自动重试。
|
||||
|
||||
### 人类工作与修订竞争
|
||||
|
||||
`agent/queued` 会区分驱动器自己的完整已接受记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合批次只接纳人类提示词而拒绝自动提示词。目标回合已经接纳后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。
|
||||
`agent/queued` 会区分驱动器自己的完整已接受记录与其他所有提示词。预留之前已经排队的普通工作会阻止调度；自动提示词待处理时进入的普通工作会使该预留过期，因此混合批次只接纳人类提示词而拒绝自动提示词。Goal Round 已经接纳后到达的普通工作会保留在队列中，成为下一个独立轮次；只有 agent 再次空闲后才重新考虑继续执行。
|
||||
|
||||
目标在回合内发生变更时会推进持久修订号。旧修订的结算不得覆盖该变更。驱动器会丢弃旧尝试的结果、读取新投影，并且只在新修订仍为 active 与 armed 时继续。因此，模型记录的完成、暂停、阻塞和编辑相对于物理轮次稍后的关闭原因具有最终权威。
|
||||
|
||||
@@ -39,7 +39,7 @@ Status: implemented
|
||||
| 轮次结果 | 动作 |
|
||||
|---|---|
|
||||
| 持久化的 `completed` | 目标仍 active/armed 且未到上限时继续 |
|
||||
| 取消已预留/接纳的目标回合，或该回合产生 `aborted` 结果 | 暂停并解除激活 |
|
||||
| 取消已预留/接纳的 Goal Round，或该 Round 产生 `aborted` 结果 | 暂停并解除激活 |
|
||||
| 代码为 `RATE_LIMIT` 或 `QUOTA` 的 `error` | 以 `usage-limited` 代码阻塞 |
|
||||
| 其他 `error` | 以 `turn-error` 代码阻塞 |
|
||||
| `max-tokens` | 以 `max-tokens` 代码阻塞 |
|
||||
@@ -76,7 +76,7 @@ Status: implemented
|
||||
## 考虑过的替代方案
|
||||
|
||||
- **在 `dsh-agent-loop` 内添加目标循环**——不予采纳，因为公共队列、提示词、会话、取消和状态 seam 已经足够，具体循环分支还会赋予某种策略特权。
|
||||
- **使用 `agent/turn-continuation` 把每个回合变成另一个步骤**——不予采纳，因为目标回合是外层策略迭代，必须拥有自己的持久用户提示词、轮次边界、回合计数和失败结算。
|
||||
- **使用 `agent/turn-continuation` 把每个 Round 变成另一个步骤**——不予采纳，因为 Goal Round 是外层策略迭代，必须拥有自己的持久用户提示词、轮次边界、Round 计数和失败结算。
|
||||
- **持久化待处理预留**——不予采纳，因为崩溃无法证明进程内队列已经达到接纳点；只有持久 `user/message` 才消耗回合。
|
||||
- **自动重试提供方或持久化错误**——不予采纳，因为重试会消耗资源，需要显式授权；停止阶段加之后的人类恢复更简单，也可观察。
|
||||
- **每回合 fork 对话历史或生成新 agent**——本包不采用，因为此目标明确属于同会话工作。新 agent 的 Ralph 执行仍是基于 subagent 与 workflow 原语的独立工作流插件。
|
||||
|
||||
@@ -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-27-native-workspace-directory-picker.md
|
||||
2026-07-27-native-workspace-directory-picker.md: 98f9dc9bed5358e816d4324462d5ea7657f9007f
|
||||
2026-07-27-native-workspace-directory-picker.zh.md: ca765778fae734fd47a05652aea7021328ed4ab6
|
||||
2026-07-27-native-workspace-directory-picker.md: a36f7b239a9115fe5eb33472ec5084818a66e9f2
|
||||
2026-07-27-native-workspace-directory-picker.zh.md: bb3e2fc6f7c77c8ace97e53435297326f937e4e8
|
||||
|
||||
@@ -27,10 +27,10 @@ The workspace manager must upsert the returned workspace before the selection ca
|
||||
|
||||
The native dialog RPC is accepted only from a loopback socket with same-origin browser metadata. The RPC does not use the default 30-second request timeout because a system dialog may remain open indefinitely; caller and connection aborts still propagate to the platform process.
|
||||
|
||||
Platform adapters invoke native tools without a shell:
|
||||
Platform adapters open the dialog without a shell — spawned native tools on POSIX, an in-process COM conversation on Windows:
|
||||
|
||||
- macOS: `osascript` and the system folder chooser.
|
||||
- Windows: PowerShell in STA mode and `FolderBrowserDialog`.
|
||||
- Windows: the koffi `IFileOpenDialog` child process with the best thread DPI awareness the host accepts (per-monitor-v2 when available; PMv2-less hosts cascade to per-monitor or system-aware) ([in-process dialog note](2026-08-02-win32-in-process-folder-dialog.md)); the tier has no fallback — failures surface as-is ([PowerShell chain removal](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)).
|
||||
- Linux: `zenity`, with `kdialog` as a fallback when Zenity is unavailable.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -27,10 +27,10 @@ Status: implemented
|
||||
|
||||
只有来自回环套接字、且携带同源浏览器元数据的请求才能调用原生对话框 RPC。该 RPC 不使用默认的 30 秒请求超时，因为系统对话框可能无限期保持打开；调用方中止或连接中止仍会传递至平台进程。
|
||||
|
||||
平台适配器不经 shell，直接调用原生工具：
|
||||
平台适配器不经 shell 打开对话框——POSIX 上 spawn 原生工具，Windows 上是子进程 COM 会话：
|
||||
|
||||
- macOS：`osascript` 和系统文件夹选择器。
|
||||
- Windows：采用 STA 模式的 PowerShell 和 `FolderBrowserDialog`。
|
||||
- Windows：koffi `IFileOpenDialog` 子进程，使用宿主接受的最佳线程 DPI 感知（可用时为 per-monitor-v2；不支持 PMv2 的主机级联到 per-monitor 或 system-aware）（见[进程内对话框 Note](2026-08-02-win32-in-process-folder-dialog.md)）；该层无回退——失败原样上报（见[PowerShell 链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。
|
||||
- Linux：使用 `zenity`；Zenity 不可用时回退到 `kdialog`。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
@@ -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-08-01-pwsh-tool-and-executor.md
|
||||
2026-08-01-pwsh-tool-and-executor.md: 7206f8ffe6640f8499f8453c40ab5846b23112c6
|
||||
2026-08-01-pwsh-tool-and-executor.zh.md: 5a48adb79fed209d2d2ecb9514fd51538491f04c
|
||||
@@ -0,0 +1,35 @@
|
||||
# Agent Note: PowerShell executor and pwsh tool
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-01-pwsh-tool-and-executor.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The harness spoke one shell dialect on every platform: `bash`. Windows hosts could run it only through WSL or Git-Bash shims, and the shipped `dsh-bash-local` executor is POSIX-only (`bash` hardcoded, process-group semantics POSIX). The Windows roadmap — defaulting hosts to `pwsh`, later pwsh TUI/GUI rendering — had no execution foundation: there was no PowerShell implementation of the bash executor seam and no model-facing tool that taught the PowerShell dialect. The bash tool itself is also far larger than a Windows-first profile needs: background tasks, sandbox escalation, and the persistent-PTY twin are all bash-shaped surface that a minimal `pwsh` tool should not carry.
|
||||
|
||||
## Decision
|
||||
|
||||
Two new packages under `packages/bash/`:
|
||||
|
||||
- **`@deepseek-ai/dsh-pwsh-local`** — a local implementation of the `ctx.bash` executor seam over `ctx.subprocess`, mirroring `dsh-bash-local` call-for-call: `resolve()` defaults and caps from config, `run()` fuses the config-clamped timeout with the caller's signal through one deadline, `start()` returns a consuming background handle whose processes belong to the subprocess service. The command string rides as ONE argv element to `pwsh -NoLogo -NoProfile -NonInteractive -Command`, so PowerShell parses it and no shell-quoting layer exists. Executable resolution (`resolvePwshPath`) is a pure function of `(configured, env, platform)`: explicit config first, then Windows probes PowerShell 7's install, PATH entries (quotes stripped), and Windows PowerShell 5.1, else a bare `pwsh` via PATH.
|
||||
- **`@deepseek-ai/dsh-tool-pwsh`** — the model-facing tool over `ctx.bash`, PowerShell-dialect by contract, mirroring `dsh-tool-bash` call-for-call minus the sandbox surface: foreground and `run_in_background` execution through the generic task runtime, managed `DSH_*` environment through the shared [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) registry, and the bash marker/truncation rendering story (a clean exit produces no marker). The parity decision supersedes this note's minimal-profile tool description.
|
||||
|
||||
Windows vitest coverage is deliberately NOT part of this change: the repo's Windows CI lane owns build/static gates, and unit coverage runs on Linux, where both packages' suites run against a real `pwsh` (preinstalled on the GitHub-hosted runners) or self-skip when absent. The vitest `windowsUnsupportedPackages` exclusion narrows from `packages/bash/*` to the bash-requiring packages so the pwsh suites can also run natively on Windows dev machines.
|
||||
|
||||
The roadmap beyond this decision — defaulting Windows hosts to `pwsh` (bash off), and pwsh TUI/GUI rendering — is recorded separately as [a proposal](../../proposed/feature/2026-08-01-windows-pwsh-default.md).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Extend `dsh-bash-local` with a pwsh mode.** Rejected: the executor's identity is the shell it spawns; a second dialect inside one package doubles its config surface (`shell` switches) and its test matrix, and the two dialects' quirks (signal facts on Windows, quoting domains) belong to their own packages' documentation.
|
||||
|
||||
**Extend `dsh-tool-bash` with a dialect parameter.** Rejected: the bash tool's background/sandbox surface is bash-shaped; a `pwsh` mode would either hide it (conditional schema churn) or inherit it (surface the minimal profile explicitly rejects). The minimal twin keeps the model contract honest.
|
||||
|
||||
**Wire the pwsh tool into the shipped CLI compositions now.** Rejected: mounting `tool-pwsh` + `pwsh-local` in `base.cordis.yml` would change the shipped roster before the Windows-default decision lands; this change ships the capability and its wiring points (`apps/cli` dependencies, tsconfig projects) without switching any default.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The bash executor seam gains a second, Windows-native implementation with an identical request/spec contract, so model-facing consumers beyond `tool-pwsh` (hooks bridges, in-process plugins) can run PowerShell without dialect shims.
|
||||
- `tool-pwsh` is the model-visible Windows-first shell tool: behaviorally interchangeable with the bash tool for foreground and background work (minus sandbox), with prompt guidance that states the marker contract precisely.
|
||||
- Windows semantics differ where the platform differs: forced termination reports exit 1 with no signal (so `signal`/`killed` status facts are POSIX-only), and PowerShell writes CRLF, which tests normalize.
|
||||
- The CLI gains two workspace dependencies and two tsconfig projects without mounting either plugin — the composition decision stays with the Windows-default proposal.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Agent Note: PowerShell 执行器与 pwsh 工具
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-01-pwsh-tool-and-executor.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
harness 在每个平台只说一种 shell 方言：`bash`。Windows 主机只能通过 WSL 或 Git-Bash 垫片运行它，而交付的 `dsh-bash-local` 执行器仅限 POSIX（硬编码 `bash`，进程组语义是 POSIX 的）。Windows 路线图——让主机默认 `pwsh`，之后再做 pwsh TUI/GUI 渲染——没有执行基础：既没有 bash 执行器 seam 的 PowerShell 实现，也没有教模型 PowerShell 方言的面向模型工具。bash 工具本身也远大于 Windows 优先画像所需：后台任务、沙箱升级与持久 PTY 孪生都是 bash 形状的表面，最小化的 `pwsh` 工具不该背负。
|
||||
|
||||
## 决策
|
||||
|
||||
在 `packages/bash/` 下新增两个包：
|
||||
|
||||
- **`@deepseek-ai/dsh-pwsh-local`** —— `ctx.bash` 执行器 seam 的本地实现，基于 `ctx.subprocess`，逐调用镜像 `dsh-bash-local`：`resolve()` 从配置默认化并设上限，`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号，`start()` 返回消费式后台句柄，其进程归属于 subprocess 服务。命令字符串作为 ONE argv 元素传给 `pwsh -NoLogo -NoProfile -NonInteractive -Command`，由 PowerShell 解析，不存在 shell 引号层。可执行文件解析（`resolvePwshPath`）是 `(configured, env, platform)` 的纯函数：先显式配置，再在 Windows 上探测 PowerShell 7 安装位置、PATH 条目（剥离引号）与 Windows PowerShell 5.1，否则经 PATH 解析裸 `pwsh`。
|
||||
- **`@deepseek-ai/dsh-tool-pwsh`** —— 基于 `ctx.bash` 的面向模型工具，契约是 PowerShell 方言，逐调用镜像 `dsh-tool-bash`、减去 sandbox 面：经通用任务运行时执行前台与 `run_in_background`，经共享 [`dsh-bash-env`](../feature/2026-08-02-pwsh-tool-bash-parity.md) 注册表管理 `DSH_*` 环境，以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。parity 决策取代了本 note 的最小画像工具描述。
|
||||
|
||||
Windows vitest 覆盖率刻意不属本次改动：仓库的 Windows CI 通道负责构建/静态门禁，单元覆盖在 Linux 上运行，两个包的套件在那里以真实 `pwsh` 运行（GitHub 托管 runner 预装）或缺失时自行跳过。vitest 的 `windowsUnsupportedPackages` 排除从 `packages/bash/*` 收窄为真正需要 bash 的包，使 pwsh 套件也能在 Windows 开发机上原生运行。
|
||||
|
||||
本决策之后的路线图——让 Windows 主机默认 `pwsh`（关闭 bash）与 pwsh TUI/GUI 渲染——另行记录为[提案](../../proposed/feature/2026-08-01-windows-pwsh-default.md)。
|
||||
|
||||
## 备选方案
|
||||
|
||||
**给 `dsh-bash-local` 增加 pwsh 模式。** 否决：执行器的身份就是它 spawn 的 shell；在一个包内塞第二种方言会翻倍配置面（`shell` 开关）与测试矩阵，且两种方言的怪癖（Windows 上的信号实情、引号域）应各自归入自己包的文档。
|
||||
|
||||
**给 `dsh-tool-bash` 增加方言参数。** 否决：bash 工具的后台/沙箱表面是 bash 形状的；`pwsh` 模式要么隐藏它（条件 schema 翻动），要么继承它（把最小画像明确拒绝的表面带进来）。最小孪生让模型契约保持诚实。
|
||||
|
||||
**现在就接入交付的 CLI 组合。** 否决：在 Windows 默认决策落地前把 `tool-pwsh` + `pwsh-local` 挂进 `base.cordis.yml` 会改变交付清单；本改动交付能力与接线点（`apps/cli` 依赖、tsconfig 工程），不切换任何默认。
|
||||
|
||||
## 后果
|
||||
|
||||
- bash 执行器 seam 有了第二个、Windows 原生的实现，请求/规范契约一致，因此 `tool-pwsh` 之外的面向模型消费方（hooks 桥、进程内插件）无需方言垫片即可运行 PowerShell。
|
||||
- `tool-pwsh` 是模型可见的 Windows 优先 shell 工具：在前台与后台工作（减 sandbox）上与 bash 工具行为可互换，提示词指导精确陈述 marker 契约。
|
||||
- Windows 语义在平台差异处不同：强制终止报告退出码 1 且无信号（因此 `signal`/`killed` 状态实情仅限 POSIX），PowerShell 输出 CRLF，测试做归一化。
|
||||
- CLI 增加两个 workspace 依赖与两个 tsconfig 工程，但不挂载任一插件——组合决策留给 Windows 默认提案。
|
||||
@@ -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-08-02-pwsh-tool-bash-parity.md
|
||||
2026-08-02-pwsh-tool-bash-parity.md: bf40c440b9f7f330412d8949f59c54d541152d45
|
||||
2026-08-02-pwsh-tool-bash-parity.zh.md: bc67dac29900eacf9e615e76fe947e3e642a3979
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: pwsh tool bash parity
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-02-pwsh-tool-bash-parity.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The first Windows-native foundation shipped `dsh-tool-pwsh` as a deliberately minimal profile — foreground only (a fresh process per call; no persistent PTY session), no managed-environment parity beyond three hardcoded `DSH_*` keys, and a marker story ("always `[exit code: N]`") that diverged from the bash tool's rendering without being declared. Review of that change found the model-visible contract drifting from the implementation: the description promised spill-path reporting the renderer never performed, the README claimed exports that did not exist and rendering the tool did not do, and the tool's own tests pinned the lossy behavior. The minimal profile also left the `DSH_*` contributor seam duplicated-by-absence: plugins contributing environment facts to `ctx.bashEnv` had no effect on pwsh calls.
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh-tool-pwsh` now mirrors `dsh-tool-bash` call-for-call, minus the sandbox surface, and its model-visible text describes exactly that behavior:
|
||||
|
||||
- **Rendering adopts the bash story verbatim**: stdout, a marked `[stderr]` section, truncation notices with spill paths, `(no output)` for an empty body, and exit markers only for non-zero exits — a clean exit produces no marker. The description and the `tool:pwsh` prompt section state this precisely ("Non-zero exits are reported as `[exit code: N]` markers"), deliberately not copying the bash prompt's "every result" phrasing, which its own renderer contradicts.
|
||||
- **`run_in_background` is wired through the generic task runtime** exactly like the bash tool: preflight, owner registration, `task_output`/`task_kill` control, and the same outcome mapping. `pwsh-local`'s already-mirrored `start()` handle backs it.
|
||||
- **The `DSH_*` environment is shared, not duplicated**: `BashEnvRegistry` moved out of `dsh-tool-bash` into a new tool-independent `@deepseek-ai/dsh-bash-env` package (`ctx.bashEnv` + built-ins + the session-persistence contributor), and both shell tools inject it. Contributors apply to pwsh calls exactly as they do to bash calls, resolving the bash tool's `FIXME(bash-env-ownership)`.
|
||||
- **Windows reality is pinned where bash has no analog**: every command runs under a UTF-8 output preamble so the Windows PowerShell 5.1 fallback cannot garble non-ASCII output through the UTF-8-decoding collector, and the prompts teach that Windows forced termination settles as exit 1 without a signal marker.
|
||||
- **Out of scope, unchanged**: sandbox escalation (waits for a Windows-confining executor), persistent PTY shells (backends are Linux/macOS-only; ConPTY is roadmap work), and pwsh-specific TUI/GUI presentation (generic/terminal cards stay; a PowerShell-aware terminal card with an exit pill is roadmap work).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the minimal profile and fix only the claims.** Rejected: the review's core finding was that text contracts copied from bash drift without the corresponding implementation; a minimal tool plus accurate claims still leaves pwsh calls without background execution, without contributor parity, and with a divergent marker story that must be re-justified forever.
|
||||
|
||||
**Reject a mismatched executor dialect at load.** Attempted and reverted before merge: a `ShellDialect` marker (`bash` | `powershell`) on `BashExecutor`, with both shell tools throwing when the mounted executor speaks another shell. It forced every executor implementation — including each test and example fake — to declare a dialect, adding noise to every shell-tool test for a guard with no in-repo or plausible deployment to catch (shipped compositions always pair tool-pwsh with `dsh-pwsh-local` and tool-bash with `dsh-bash-local`). The pairing contract stays documented in each tool's README instead.
|
||||
|
||||
**Extract a fully shared tool implementation base (abstract shell dialect, two thin leaves).** Considered and deferred: the bash-env extraction and the structural mirror (`render.ts`/`background.ts` twins) are the foundation it would rest on; a full base waits until a third dialect or the persistent-PTY twin makes the abstraction's shape observable.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The bash and pwsh tools are now behaviorally interchangeable for foreground and background shell work (minus sandbox), and the pwsh prompt/description sentences are each backed by the renderer — the reviewer's grep-against-code check passes.
|
||||
- Parity ran BOTH ways once: the pwsh tool's structured foreground abort (`HarnessError('tool call aborted', TOOL_ABORTED)` with name `AbortError`) was backported to the bash tool, replacing its uncoded `Error('command aborted')` — a model-visible/logged change pinned by exact-shape tests on both sides and by the cancel-tool-calls fixture.
|
||||
- `@deepseek-ai/dsh-bash-env` is a new shipped package; `dsh-tool-bash`'s `dshHome` config moved there, so compositions mounting the shell tools must also mount `bash-env` (the spine bundles do).
|
||||
- Windows-only semantics (CRLF normalization, forced-termination exit-1/signal-null, POSIX-only self-signal) remain pinned by tests as before.
|
||||
- The pwsh tool's per-file coverage gate rides on the scriptable fake-executor suite (`tests/tools.spec.ts`); the real-pwsh integration and Loader-composition suites self-skip where `pwsh` is absent, mirroring the bash suites' division of labor.
|
||||
- The roadmap proposal's parity stage is delivered; its remaining stages are the Windows default composition and pwsh TUI/GUI rendering.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Agent Note: pwsh 工具与 bash 对齐
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-02-pwsh-tool-bash-parity.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
首个 Windows 原生基础交付的 `dsh-tool-pwsh` 是刻意最小的画像——仅前台、无后台任务、受管环境只有三个硬编码 `DSH_*` 键、以及一个未声明就偏离 bash 工具的 marker 故事（"恒打 `[exit code: N]`"）。对该变更的 review 发现模型可见契约与实现脱节：描述承诺了渲染器从未执行的 spill 路径报告，README 宣称了不存在的导出与工具未做的渲染，工具自己的测试还钉死了有损行为。最小画像还让 `DSH_*` contributor seam 因缺席而重复：向 `ctx.bashEnv` 贡献环境事实的插件对 pwsh 调用毫无作用。
|
||||
|
||||
## 决策
|
||||
|
||||
`dsh-tool-pwsh` 现在逐调用镜像 `dsh-tool-bash`，减去 sandbox 面，其模型可见文本精确描述这一行为：
|
||||
|
||||
- **渲染完全采用 bash 故事**：stdout、带标记的 `[stderr]` 段、带 spill 路径的截断通知、空体渲染 `(no output)`、退出 marker 仅限非零退出——干净退出不产生 marker。描述与 `tool:pwsh` prompt section 精确陈述这一点（"Non-zero exits are reported as `[exit code: N]` markers"），刻意不复制 bash prompt 中与其自身渲染矛盾的 "every result" 措辞。
|
||||
- **`run_in_background` 经通用任务运行时接线**，与 bash 工具完全一致：预检、owner 注册、`task_output`/`task_kill` 控制与相同的结果映射。其背后是 `pwsh-local` 早已镜像好的 `start()` 句柄。
|
||||
- **`DSH_*` 环境共享而非复制**：`BashEnvRegistry` 从 `dsh-tool-bash` 迁入新的工具无关包 `@deepseek-ai/dsh-bash-env`（`ctx.bashEnv` + 内置事实 + session-persistence contributor），两个 shell 工具都注入它。contributor 对 pwsh 调用与 bash 调用一视同仁，并消化了 bash 工具的 `FIXME(bash-env-ownership)`。
|
||||
- **Windows 现实在 bash 无对应处钉死**：每条命令都在 UTF-8 输出 preamble 下运行，使 Windows PowerShell 5.1 兜底无法经 UTF-8 解码的 collector 破坏非 ASCII 输出；prompt 教授 Windows 强制终止以无 signal 的 exit 1 结算。
|
||||
- **范围外，不变**：sandbox 升级（等待 Windows-confining 执行器）、持久 PTY shell（后端仅限 Linux/macOS；ConPTY 属路线图）、pwsh 专属 TUI/GUI 呈现（维持 generic/terminal 卡；带退出 pill 的 PowerShell 感知 terminal 卡属路线图）。
|
||||
|
||||
## 备选方案
|
||||
|
||||
**保留最小画像，只修声明。** 否决：review 的核心发现是"从 bash 复制的文本契约在缺少对应实现时会漂移"；最小工具加准确声明仍让 pwsh 调用没有后台执行、没有 contributor 对等、并留下一个必须永远重新辩护的偏离 marker 故事。
|
||||
|
||||
**在加载时拒绝不匹配的执行器方言。** 合并前尝试过并撤回：在 `BashExecutor` 上加 `ShellDialect` 标记（`bash` | `powershell`），两个 shell 工具在挂载的执行器说另一种方言时抛错。它迫使每个执行器实现——包括每个测试与示例的 fake——都要声明 dialect，为一道仓内及合理部署中都没有目标可拦的护栏（交付组合总是把 tool-pwsh 配 `dsh-pwsh-local`、tool-bash 配 `dsh-bash-local`）给每个 shell 工具测试添噪。配对契约改由各工具 README 记录。
|
||||
|
||||
**提取完全共享的工具实现基座（抽象 shell 方言，两个薄叶子）。** 考虑后推迟：bash-env 提取与结构镜像（`render.ts`/`background.ts` 孪生）是它要立足的基础；在出现第三种方言或持久 PTY 孪生、让抽象的形态可观察之前，不做完整基座。
|
||||
|
||||
## 后果
|
||||
|
||||
- bash 与 pwsh 工具在前台与后台 shell 工作（减 sandbox）上行为可互换，pwsh 的 prompt/描述句每句都有渲染器背书——reviewer 的“拿代码 grep 对证”检查通过。
|
||||
- 对齐也反向发生过一次：pwsh 工具的结构化前台中止（`HarnessError('tool call aborted', TOOL_ABORTED)`，name 为 `AbortError`）被回移到 bash 工具，取代其无码的 `Error('command aborted')`——这是模型可见/入日志的变更，由两侧的精确形状测试与 cancel-tool-calls fixture 钉住。
|
||||
- `@deepseek-ai/dsh-bash-env` 成为新的交付包；`dsh-tool-bash` 的 `dshHome` 配置迁往那里，因此挂载 shell 工具的组合也必须挂载 `bash-env`（spine bundle 已如此）。
|
||||
- Windows 专属语义（CRLF 归一化、强制终止 exit-1/signal-null、仅 POSIX 的自信号）一如既往由测试钉住。
|
||||
- pwsh 工具的 per-file 覆盖门禁由可脚本化的 fake-executor 套件（`tests/tools.spec.ts`）承担；真实 pwsh 的集成与 Loader 组合套件在无 `pwsh` 的宿主自跳过，与 bash 套件的分工一致。
|
||||
- 路线图提案的 parity 阶段已交付；其余阶段是 Windows 默认组合与 pwsh TUI/GUI 渲染。
|
||||
@@ -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-08-02-win32-in-process-folder-dialog.md
|
||||
2026-08-02-win32-in-process-folder-dialog.md: 91a1ed0d7b1c1938a5e038ce36f1ca90bf3c9e82
|
||||
2026-08-02-win32-in-process-folder-dialog.zh.md: 6b90dc1c5fa0042b3e2bcbea8ed554f1f0ea2acf
|
||||
@@ -0,0 +1,27 @@
|
||||
# Agent Note: Win32 folder picker moves to koffi in a child process
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-02-win32-in-process-folder-dialog.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The Windows directory picker's primary tier was a spawned PowerShell script around WinForms `FolderBrowserDialog`: the modern dialog only where PowerShell 7 happens to be installed, a review-flagged regression where PowerShell 6 resolves but has no WinForms (exit 1 is not `ENOENT`, so the 5.1 fallback never ran), a `SetProcessDPIAware` ceiling of system DPI, and a picker whose behavior depended on which shells a machine ships rather than on Windows itself.
|
||||
|
||||
## Decision
|
||||
|
||||
`packages/host/directory-picker-native` now opens `IFileOpenDialog` (`FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_NOCHANGEDIR`) in-process through koffi — already a workspace dependency for the repo's other `win32.ts` surfaces — as the primary win32 tier. The COM conversation runs in a spawned child process so the modal `Show` never blocks the host event loop; the child posts its native thread id before blocking, and the driver services aborts by re-posting `WM_CLOSE` to that thread's windows (`EnumThreadWindows`), killing the child when the close budget is exhausted. The dialog is the child's first window, so Windows activates it without a foreground call. The child thread opts into the best thread DPI awareness the host accepts (`SetThreadDpiAwarenessContext`, cascading per-monitor-v2 → per-monitor → system-aware with the return value checked), a strict upgrade over the script's system-DPI ceiling; DPI stays a cosmetic best-effort — a host accepting none of them still gets the modern dialog rather than a downgrade. The module split keeps coverage honest on every host: `win32-dialog-logic.ts` (pure sequencing) and `win32-dialog.ts` (driver) test against fakes anywhere; `win32-dialog-bindings.ts` tests against a mocked `koffi` COM world (the `dsh-session-persistence-jsonl` technique); POSIX hosts run the real spawn plumbing to its koffi-load rejection; win32 hosts run a real open-and-abort-close smoke. The PowerShell chain that preceded this tier is gone (see the [chain removal](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)): the tier has no fallback.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **A prebuilt native helper (`native/` family like `node-addon-landlock-run`).** Rejected: a mirror repository, an npm package family, MSVC provisioning, and a release handoff — all to ship ~150 lines of C the repository cannot exercise on CI (no real-Windows lane); koffi delivers the same COM surface with zero new supply chain.
|
||||
- **An N-API in-process addon.** Rejected for the same CI/toolchain reasons plus owned C++ for STA threading and message pumping that a child process + koffi express in TypeScript.
|
||||
- **Keep PowerShell primary and probe versions.** Rejected: the picker stays hostage to shell packaging (6 vs 7, Store aliases, profiles), and 5.1's legacy dialog remains the floor wherever pwsh is absent; the fallback-trigger widening alone was accepted into the fallback tier instead.
|
||||
- **Blocking the main thread for the modal call.** Rejected outright: the web host must keep serving RPC while the dialog is open.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Every Windows machine gets the modern dialog with the best DPI awareness it supports (per-monitor-v2 on 1703+), PowerShell installed or not.
|
||||
- Real dialog rendering and the selection path stay a manual Windows check (the auto-close smoke proves open/abort/unwind).
|
||||
- The COM vtable slots and GUIDs used are frozen Windows ABI (Vista); a koffi signature mistake risks a native access violation, contained to the dialog child process — the host Node process survives and the failure surfaces as-is (no fallback tier; see the [chain removal](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)). The mocked-koffi ABI pins and the real win32 smoke exist to catch such mistakes before shipping.
|
||||
- The packaged-binary arm — the packaged executable spawning itself as the dialog entry — is not exercised by any automated test: the source plane and the built `lib/worker.cjs` under plain node are covered, and the packaged spawn remains deferred to the Windows CI roadmap.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Agent Note：Win32 文件夹选择器迁至 koffi 子进程
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-02-win32-in-process-folder-dialog.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
Windows 目录选择器的主层此前是围绕 WinForms `FolderBrowserDialog` 的外部 PowerShell 脚本：只有恰好安装了 PowerShell 7 的机器才有现代对话框；review 指出的回归——PowerShell 6 可解析却没有 WinForms（退出码 1 而非 `ENOENT`，5.1 回退永远不会触发）；`SetProcessDPIAware` 只有系统 DPI 的上限；选择器的行为取决于机器装了哪些 shell，而不是取决于 Windows 本身。
|
||||
|
||||
## 决策
|
||||
|
||||
`packages/host/directory-picker-native` 现在经 koffi——它已是仓库其他 `win32.ts` 面的工作区依赖——在进程内打开 `IFileOpenDialog`（`FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_NOCHANGEDIR`），作为 win32 主层。COM 会话运行在 spawn 出的子进程中，模态 `Show` 永不阻塞宿主事件循环；子进程在阻塞前上报其原生线程 id，driver 通过向该线程的窗口反复投递 `WM_CLOSE`（`EnumThreadWindows`）来服务中止，关闭预算耗尽时 kill 子进程。对话框是子进程的第一个窗口，Windows 会自动激活它，无需手动前台调用。子进程线程启用宿主接受的最佳线程 DPI 感知（`SetThreadDpiAwarenessContext`，按 per-monitor-v2 → per-monitor → system-aware 级联并检查返回值），严格优于脚本的系统 DPI 上限；DPI 保持为纯外观的 best-effort——全部不被接受的宿主仍得到现代对话框，而不会降级。模块切分让覆盖率在任何主机上都诚实：`win32-dialog-logic.ts`（纯时序）与 `win32-dialog.ts`（driver）在任何平台对假件测试；`win32-dialog-bindings.ts` 对 mock 的 `koffi` COM 世界测试（`dsh-session-persistence-jsonl` 的技法）；POSIX 主机把真实 spawn 管道跑到 koffi 加载失败的拒绝；win32 主机跑真实的"打开并中止关闭"冒烟。先于本层存在的 PowerShell 链已被删除（见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）：该层无回退。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
- **预编译原生助手（`native/` 家族，如 `node-addon-landlock-run`）。** 否决：镜像仓库、npm 包家族、MSVC 供给和发布交接——只为交付约 150 行 CI 无法执行的 C（没有真 Windows 通道）；koffi 以零新增供应链提供同一 COM 面。
|
||||
- **N-API 进程内插件。** 否决：同样的 CI／工具链原因，另加需要自有 C++ 处理 STA 线程与消息泵，而子进程 + koffi 用 TypeScript 就能表达。
|
||||
- **保留 PowerShell 为主层并探测版本。** 否决：选择器仍被 shell 打包形态挟持（6 与 7、Store 别名、profile），且没有 pwsh 的机器地板仍是 5.1 的旧版对话框；仅把回退触发条件的拓宽吸收进回退层。
|
||||
- **在主线程上阻塞模态调用。** 直接否决：对话框打开期间 web 宿主必须继续服务 RPC。
|
||||
|
||||
## 后果
|
||||
|
||||
- 每台 Windows 机器都得到带其所支持的最佳 DPI 感知（1703+ 为 per-monitor-v2）的现代对话框，无论是否安装 PowerShell。
|
||||
- 真实对话框渲染与选中路径仍是手动 Windows 检查（自动关闭冒烟证明打开／中止／收尾）。
|
||||
- 所用 COM vtable 槽位与 GUID 是冻结的 Windows ABI（Vista 起）；koffi 签名错误可能引发原生访问冲突，但被限制在对话框子进程内——宿主 Node 进程存活，失败原样上报（无回退层；见[链删除](../simplification/2026-08-04-drop-windows-powershell-picker-fallback.md)）。mocked-koffi 的 ABI 钉与真实 win32 冒烟正是为了在交付前捕获这类错误。
|
||||
- 打包二进制的臂——打包后的可执行文件以对话框入口形式自我 spawn——不受任何自动化测试覆盖：源码平面与普通 node 下构建出的 `lib/worker.cjs` 已被覆盖，打包 spawn 推迟到 Windows CI 路线图。
|
||||
@@ -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/process/2026-06-17-ts-build-config.md
|
||||
2026-06-17-ts-build-config.md: 20dd3d8d0a11e01397c36388903cd112a170f0bf
|
||||
2026-06-17-ts-build-config.zh.md: 90a9247bd2b942d5bf88d41989a36bfefe906787
|
||||
2026-06-17-ts-build-config.md: ec4c6a4aeb1074a69d45b2cf4b4c733b410ccceb
|
||||
2026-06-17-ts-build-config.zh.md: 8115bb2557eea967d57eb6693e2bb288188792a8
|
||||
|
||||
@@ -32,7 +32,7 @@ In-package relative imports use explicit `.ts` specifiers.
|
||||
|
||||
`pnpm run build` is a two-stage build:
|
||||
|
||||
- Stage 1: `tsc -b` over the root solution emits per-module `.js`, declarations `.d.ts`, JS sourcemaps `.js.map`, and declaration sourcemaps `.d.ts.map` into each package's `lib/types`. This is the authoritative TypeScript compilation result. For publish we keep `.d.ts` / `.d.ts.map` and ignore `.js` / `.js.map`.
|
||||
- Stage 1: `tsc -b` over the root solution emits per-module `.js`, declarations `.d.ts`, JS sourcemaps `.js.map`, and declaration sourcemaps `.d.ts.map` into each package's `lib/types`. This is the authoritative TypeScript compilation result. Publication keeps `.d.ts`; packages whose runtime exports explicitly point into the emitted tree also keep its `.js` files. `.js.map` and `.d.ts.map` remain in the local build tree.
|
||||
- The graph is the project-reference graph reachable from the root solution `tsconfig.json` through the two aggregates ([topology](2026-07-22-tsconfig-solution-root-two-aggregates.md)). It validates and emits package/vendor build results.
|
||||
- Stage 2: a bundler reads the emitted JS under `lib/types` and writes the bundled runtime entry as `lib/index.js` or `lib/index.mjs` (follow current behavior). This stage is bundling only. It must not read TypeScript source or emit declarations.
|
||||
|
||||
@@ -77,9 +77,9 @@ Build responsibilities are clearer:
|
||||
|
||||
- Each module under `packages/<group>/<pkg>` and `vendor/*` has one local tsconfig for build, typecheck, and tools that run source directly, such as the `dsh` source loader, `tsx`, and `vitest`.
|
||||
- The `build` command drives the root solution graph. `tsc -b` owns the publishable per-module `.js` and `.d.ts` output, and the bundler owns only `lib/index.*`.
|
||||
- `lib/types/*.d.ts` and `.d.ts.map` are the publish declaration output.
|
||||
- `lib/types/*.d.ts` is the publish declaration output; `.d.ts.map` remains only as a local compilation artifact.
|
||||
- `lib/types/*.d.ts` uses explicit `.ts` relative specifiers, which TypeScript's NodeNext/Node16 resolver maps to sibling `.d.ts` files.
|
||||
- `lib/types/*.js` is only a bundler input and must not be used as a runtime entry or public import target.
|
||||
- `lib/types/*.js` is normally only a bundler input. It is published only when an explicit runtime export points into the emitted tree.
|
||||
- `lib/index.*` is the publish runtime output and is generated by the bundler, currently `tsdown`.
|
||||
- `pnpm run verify-node-next-types` scans built declarations for relative specifiers without file extensions, then typechecks a temporary external ESM consumer with `moduleResolution: "NodeNext"` against the built `types`/`exports` surface, so declaration specifier regressions fail before publish.
|
||||
- The `typecheck` command uses `tsconfig.json`. Examples, tests, and scripts are checked by the root no-emit project, while packages and vendor modules keep the same emit behavior as `build`. Package and vendor source stays behind project-reference boundaries.
|
||||
|
||||
@@ -11,7 +11,7 @@ Status: implemented
|
||||
此前的 TypeScript 构建与类型检查配置存在以下问题：
|
||||
|
||||
- `build` 使用 `tsc` 将 `packages/<group>/<pkg>` 和 `vendor/*` 下的 `.ts` 转换为 `.d.ts` 文件，然后使用 `tsdown` 将 `.ts` 转换为打包后的 `.js` 文件。这导致两个工具各自执行 TypeScript 转换。
|
||||
- `typecheck` 倾向于通过一个根目录的类型检查配置来校验包、vendor 源码、示例、测试和脚本。
|
||||
- `typecheck` 倾向于通过一个根目录的类型检查配置来校验包（package）、vendor 源码、示例、测试和脚本。
|
||||
|
||||
目标是让构建与类型检查使用一致的 tsconfig 边界和 TypeScript 解析/转换行为。构建应通过单一编译器和配置生成 `.js`、`.d.ts`、`.js.map` 和 `.d.ts.map`，使发布产物与类型校验保持一致。
|
||||
|
||||
@@ -21,7 +21,7 @@ Status: implemented
|
||||
- `tsdown` 输出的打包 `.d.ts` 与 Cordis 内部的相对模块增强（module augmentation）结构冲突。
|
||||
- tsc 的输出受 `allowImportingTsExtensions` 影响，因此需要确保生成的 `.js` 文件不会导入 `.ts` 文件，且生成的 `.d.ts` 文件保留 NodeNext/Node16 接受的显式相对说明符。为此，包内相对导入在 TypeScript 源码中使用显式 `.ts` 说明符，由 `rewriteRelativeImportExtensions` 在输出的 JS 中将其重写为 `.js`。
|
||||
- `tsdown` 输出的打包 `.js` 与 `tsc -b` 逐文件输出的 `.js` 行为不同，例如装饰器转换行为。
|
||||
- `vendor/*/src`、示例、测试和脚本无法全部直接纳入一个根目录的严格程序。
|
||||
- `vendor/*/src`、示例、测试和脚本无法全部以 plain-include 方式纳入一个根目录的严格程序。
|
||||
- 在根目录严格配置下直接对 `vendor/*/src` 做类型检查，会触发大量不属于本项目所有权范围的类型错误。
|
||||
- `packages/*/*` 对 `vendor` 的包依赖解析到 `vendor/*/lib`，以适应不同的 tsconfig 严格度。
|
||||
|
||||
@@ -32,7 +32,7 @@ Status: implemented
|
||||
|
||||
`pnpm run build` 是两阶段构建：
|
||||
|
||||
- 阶段 1：在根 solution 上执行 `tsc -b`，将逐模块的 `.js`、声明文件 `.d.ts`、JS sourcemap `.js.map` 和声明 sourcemap `.d.ts.map` 输出到各包的 `lib/types`。这是权威的 TypeScript 编译结果。发布时保留 `.d.ts` / `.d.ts.map`，忽略 `.js` / `.js.map`。
|
||||
- 阶段 1：在根 solution 上执行 `tsc -b`，将逐模块的 `.js`、声明文件 `.d.ts`、JS sourcemap `.js.map` 和声明 sourcemap `.d.ts.map` 输出到各包的 `lib/types`。这是权威的 TypeScript 编译结果。发布时保留 `.d.ts`；如果包的运行时 export 显式指向该输出树，也会保留其中的 `.js` 文件。`.js.map` 和 `.d.ts.map` 留在本地构建树中。
|
||||
- 该图是从根 solution `tsconfig.json` 经两个聚合可达的 project-reference 图（[拓扑](2026-07-22-tsconfig-solution-root-two-aggregates.md)），用于校验并输出包/vendor 的构建结果。
|
||||
- 阶段 2：打包器读取 `lib/types` 下输出的 JS，将打包后的运行时入口写为 `lib/index.js` 或 `lib/index.mjs`（沿用当前行为）。此阶段仅做打包，禁止读取 TypeScript 源码或输出声明文件。
|
||||
|
||||
@@ -77,11 +77,11 @@ tsx scripts/clean.ts
|
||||
|
||||
- `packages/<group>/<pkg>` 和 `vendor/*` 下的每个模块有一份本地 tsconfig，同时服务于构建、类型检查和直接运行源码的工具（如 `dsh` 源码 loader、`tsx` 和 `vitest`）。
|
||||
- `build` 命令驱动根 solution 图。`tsc -b` 负责可发布的逐模块 `.js` 和 `.d.ts` 输出，打包器仅负责 `lib/index.*`。
|
||||
- `lib/types/*.d.ts` 和 `.d.ts.map` 是发布用的声明输出。
|
||||
- `lib/types/*.d.ts` 是发布用的声明输出；`.d.ts.map` 只作为本地编译产物保留。
|
||||
- `lib/types/*.d.ts` 使用显式 `.ts` 相对说明符，TypeScript 的 NodeNext/Node16 解析器会将其映射到同级的 `.d.ts` 文件。
|
||||
- `lib/types/*.js` 仅作为打包器输入，禁止用作运行时入口或公开导入目标。
|
||||
- `lib/types/*.js` 通常仅作为打包器输入。只有显式运行时 export 指向该输出树时，才会发布这些文件。
|
||||
- `lib/index.*` 是发布用的运行时输出，由打包器（当前为 `tsdown`）生成。
|
||||
- `pnpm run verify-node-next-types` 扫描构建出的声明文件，检查是否存在缺少文件扩展名的相对说明符，然后以 `moduleResolution: "NodeNext"` 针对构建出的 `types`/`exports` 接口，对一个临时的外部 ESM 消费方进行类型检查，确保声明说明符的回归在发布前被捕获。
|
||||
- `pnpm run verify-node-next-types` 扫描构建出的声明文件，检查是否存在缺少文件扩展名的相对说明符，然后以 `moduleResolution: "NodeNext"` 对构建出的 `types`/`exports` 接口进行临时外部 ESM 消费方的类型检查，确保声明说明符的回归在发布前被捕获。
|
||||
- `typecheck` 命令使用 `tsconfig.json`。示例、测试和脚本由根 no-emit 项目检查，包和 vendor 模块保持与 `build` 相同的输出行为。包和 vendor 源码始终处于 project-reference 边界之后。
|
||||
- 切换分支或更新工作副本后，如果其中删除了包，贡献者可在重新构建前运行 `pnpm run clean`，删除残留的包目录。不含 `package.json` 的包目录如果存在未知文件，必须手动判定其类别，不能直接删除。
|
||||
|
||||
|
||||
@@ -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/simplification/2026-07-26-eventsource-parser-for-deepseek-sse.md
|
||||
2026-07-26-eventsource-parser-for-deepseek-sse.md: e7835bc738b3dec5aefd6011848525f6604e852e
|
||||
2026-07-26-eventsource-parser-for-deepseek-sse.zh.md: 141fadd5bd43c7a945e73ce219ccd61f2bd9f332
|
||||
2026-07-26-eventsource-parser-for-deepseek-sse.zh.md: 7c746079aa7012115bea05ec0191d665c8f860d2
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 用 eventsource-parser 替换 llm-deepseek 中手写的 SSE（Server-Sent Events）解析器
|
||||
# Agent Note: 用 eventsource-parser 替换 llm-deepseek 中手写的 SSE 解析器
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -6,7 +6,7 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
`packages/llm/llm-deepseek/src/sse.ts` 曾手写实现 SSE 解析：一个流式 `TextDecoder`、按 `\r?\n\r?\n` 切分事件块、提取并拼接 `data:` 载荷、跳过注释与其他字段、`[DONE]` 哨兵、在未见哨兵即 EOF 时抛出 `STREAM_CLOSED` 错误，以及对最后一个未终结事件块的 flush。该文件约 67 行，另有约 108 行专属测试（`tests/sse.spec.ts`）重复验证 SSE 规范行为——UTF-8 字符被切分到多个分片、CRLF 处理、多条 `data:` 拼接、冒号后无空格——而这些行为，持续维护的解析器早已有保证。它唯一的消费方是 `adapter.ts`（`yield* translate(parseSse(response.body))`）。
|
||||
`packages/llm/llm-deepseek/src/sse.ts` 曾手写实现 SSE（Server-Sent Events）解析：一个流式 `TextDecoder`、按 `\r?\n\r?\n` 切分事件块、提取并拼接 `data:` 载荷、跳过注释与其他字段、`[DONE]` 哨兵、在未见哨兵即 EOF 时抛出 `STREAM_CLOSED` 错误，以及对最后一个未终结事件块的 flush。该文件约 67 行，另有约 108 行专属测试（`tests/sse.spec.ts`）重复验证 SSE 规范行为——UTF-8 字符被切分到多个分片、CRLF 处理、多条 `data:` 拼接、冒号后无空格——而这些行为，持续维护的解析器早已有保证。它唯一的消费方是 `adapter.ts`（`yield* translate(parseSse(response.body))`）。
|
||||
|
||||
这恰好是 `eventsource-parser` 负责的接口面：事实标准的 SSE 解析器（Vercel AI SDK 和 MCP SDK 都构建在它之上），零依赖，持续维护，并且已通过 `@modelcontextprotocol/sdk` 作为传递依赖出现在本仓库的 lockfile 中——因此直接采用它实际上不增加新的供应链接触面。
|
||||
|
||||
|
||||
@@ -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/simplification/2026-08-04-drop-windows-powershell-picker-fallback.md
|
||||
2026-08-04-drop-windows-powershell-picker-fallback.md: 619afd31d9ec78cdb8565e29fa942b7db8749365
|
||||
2026-08-04-drop-windows-powershell-picker-fallback.zh.md: e14904db46a955d4cf40da195a39bf62cbef96ff
|
||||
@@ -0,0 +1,38 @@
|
||||
# Agent Note: Drop the Windows PowerShell picker fallback
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-04-drop-windows-powershell-picker-fallback.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The win32 branch of the native directory picker kept a two-tier PowerShell fallback under the koffi `IFileOpenDialog` child process: `pwsh.exe` first, then `powershell.exe` (Windows PowerShell 5.1), both running the same WinForms script with a `SetProcessDPIAware` opt-in. The chain existed to keep a working chooser when the koffi tier was "unavailable", but every trigger it plausibly protected was a failure of our own packaging or deployment, not of the operating system:
|
||||
|
||||
- koffi's native binary ships as an ordinary optional dependency (`@koromix/koffi-win32-x64`, no install script); a host that installs the package at all has the binary, and a host that cannot install it fails the package install loudly — the fallback code never loads either.
|
||||
- "Ancient Windows" cannot occur: the Node versions this repo supports run on Windows generations far newer than the Vista-era `IFileOpenDialog` ABI the dialog needs.
|
||||
- A koffi/COM defect crashes only the dialog child process (crash isolation); the correct response to our own bug is a surfaced failure, not a silent downgrade to a legacy dialog.
|
||||
|
||||
The chain also cost real complexity: two spawn tiers running one identical script, a fallback trigger widened from `ENOENT` to any pwsh failure to close the PowerShell 6 (no WinForms) regression, a triple-miss `AggregateError` carrying all three causes, and per-tier abort re-checks. The seam already owns the only fallback that matters — the `browse` backend at the composition level, chosen once at boot by `directory-picker-auto`.
|
||||
|
||||
## Decision
|
||||
|
||||
The win32 tier is exactly the koffi `IFileOpenDialog` child process; any failure surfaces as-is with no fallback. The PowerShell chain — the `pwsh` → Windows PowerShell 5.1 cascade, the DPI-corrected WinForms script, the `AggregateError` aggregation — is deleted, and `pickNativeDirectory`'s win32 branch is a single call. `dsh-native-command` remains a dependency for the POSIX tiers.
|
||||
|
||||
The fallback criterion the rest of the package already followed now applies uniformly: a fallback tier exists only for tools the OS/desktop environment provides and may omit (`zenity` → `kdialog` on Linux, which the boot-time probe also samples); tools our own package ships (`koffi`) fail loud. macOS `osascript` stays fallback-free as before.
|
||||
|
||||
This change consolidates and deletes the pwsh-first DPI picker-fix note: its decision is fully reversed here, and its preserved rationale no longer guides future work on a koffi-only tier. What it kept that was real: PowerShell 7 renders the modern `IFileDialog`-based folder picker where 5.1's `FolderBrowserDialog` is hardwired to the legacy `SHBrowseForFolder` tree; the script's `SetProcessDPIAware` corrected the spawn's system-DPI ceiling; the pwsh→5.1 hop existed because a resolvable PowerShell 6 has no WinForms (exit 1, not `ENOENT`). Its rejected alternatives (requiring PowerShell 7, importing `resolvePwshPath`, setting DPI awareness in the harness process) are moot with the chain gone.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the chain but drop the pwsh quality tier (`koffi` → Windows PowerShell 5.1).** Rejected: the remaining tier still defends our own packaged dependency, still costs the script, the widened trigger, and the aggregation, and still hides our own vtable/COM defects behind a legacy dialog. The criterion "fallback only for externally provided tools" admits no Windows tier at all.
|
||||
|
||||
**Keep the chain as-is.** Rejected: it was the only two-level runtime fallback in the picker surface, its triggers were deployment-side failures that fail loud anyway, and it degraded a failed pick into an `AggregateError` whose most actionable entry was a PowerShell host.
|
||||
|
||||
**Fall back to `browse` at runtime when the native pick fails.** Rejected: the seam's flow holes are `single`-kind and the `-auto` composition already picks one backend at boot; a runtime cross-kind hop would double-mount both backends and blur the capability boundary.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The win32 picker's failure surface is one error from one tier; callers see the real cause (koffi load failure, COM refusal, dialog crash) instead of a chain-aggregated error.
|
||||
- `pwsh`/`powershell.exe` are no longer invoked by this package; the WinForms script, its `SetProcessDPIAware` correction, and the `-STA` flags are gone with them.
|
||||
- Tests shrink accordingly: the pwsh/5.1 cascade and triple-miss cases are replaced by one "failure surfaces with no fallback" case; the default-adapter test now drives the Linux tier.
|
||||
- Reintroduction condition: a future win32 mechanism outside our packaging chain (a system-provided dialog host we do not ship) would justify a single fallback tier under the same criterion.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Agent Note：删除 Windows PowerShell 选择器回退
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-04-drop-windows-powershell-picker-fallback.md) | 中文
|
||||
|
||||
## Problem
|
||||
|
||||
原生目录选择器的 win32 分支在 koffi `IFileOpenDialog` 子进程之下保留了一条两级 PowerShell 回退：先 `pwsh.exe`，再 `powershell.exe`（Windows PowerShell 5.1），两者运行同一个带 `SetProcessDPIAware` 开关的 WinForms 脚本。该链的存在是为了在 koffi 层"不可用"时仍能给出一个可用的选择器，但它可能保护的每一个触发条件都是我们自己打包或部署的失败，而不是操作系统的：
|
||||
|
||||
- koffi 的原生二进制作为普通 optional 依赖（`@koromix/koffi-win32-x64`，无 install script）分发；能装上该包的宿主就一定有二进制，装不上的宿主会在安装期大声失败——回退代码同样不会加载。
|
||||
- "上古 Windows"不可能出现：本仓库支持的 Node 版本运行在远比 Vista 时代 `IFileOpenDialog` ABI 新的 Windows 世代上。
|
||||
- koffi/COM 缺陷只崩对话框子进程（crash isolation）；对我们自己 bug 的正确反应是上报失败，而不是静默降级到旧版对话框。
|
||||
|
||||
这条链还付出了真实的复杂度：两个 spawn 层运行同一脚本、把回退触发从 `ENOENT` 拓宽为 pwsh 的任何失败以关闭 PowerShell 6（无 WinForms）回归、携带全部三个原因的三连败 `AggregateError`，以及每层的 abort 重检。seam 早已拥有唯一重要的回退——组合层面的 `browse` 后端，由 `directory-picker-auto` 在启动时选择一次。
|
||||
|
||||
## Decision
|
||||
|
||||
win32 层恰好就是 koffi `IFileOpenDialog` 子进程；任何失败原样上报，无回退。PowerShell 链——`pwsh` → Windows PowerShell 5.1 级联、DPI 修正的 WinForms 脚本、`AggregateError` 聚合——被删除，`pickNativeDirectory` 的 win32 分支成为单次调用。`dsh-native-command` 仍为 POSIX 层保留依赖。
|
||||
|
||||
本包其余部分早已遵循的回退判据现在统一适用：回退层只存在于操作系统/桌面环境提供且可能缺失的工具（Linux 的 `zenity` → `kdialog`，启动探针同样采样它们）；我们自己打包的工具（`koffi`）失败即大声报错。macOS `osascript` 与之前一样保持无回退。
|
||||
|
||||
本次变更合并并删除了 pwsh 优先的 DPI 选择器修复 Note：其决策在此被完全反转，其保留的 rationale 对只含 koffi 的层不再指导未来工作。其中真实的部分：PowerShell 7 呈现基于 `IFileDialog` 的现代文件夹选择器，而 5.1 的 `FolderBrowserDialog` 被硬连到旧版 `SHBrowseForFolder` 树；脚本的 `SetProcessDPIAware` 修正了 spawn 的系统 DPI 上限；pwsh→5.1 的跳转存在是因为可解析的 PowerShell 6 没有 WinForms（退出码 1，而非 `ENOENT`）。其被拒绝的替代方案（要求 PowerShell 7、导入 `resolvePwshPath`、在 harness 进程设置 DPI 感知）随链删除而失去意义。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**保留链但去掉 pwsh 质量层（`koffi` → Windows PowerShell 5.1）。** 拒绝：剩下的层仍在为我们自己打包的依赖辩护，仍要付出脚本、拓宽的触发与聚合的代价，仍会把我们自己的 vtable/COM 缺陷藏到旧版对话框后面。"仅对外部提供的工具回退"的判据不接受任何 Windows 层。
|
||||
|
||||
**原样保留链。** 拒绝：它是选择器面上唯一的二级运行时回退，其触发条件是本就大声失败的部署侧失败，并且它把失败的 pick 降级成一个最具可操作性的条目是 PowerShell 宿主的 `AggregateError`。
|
||||
|
||||
**原生 pick 失败时在运行时回退到 `browse`。** 拒绝：seam 的流程洞是 `single` kind，`-auto` 组合已在启动时选择一个后端；运行时跨 kind 跳转会双挂两个后端并模糊能力边界。
|
||||
|
||||
## Consequences
|
||||
|
||||
- win32 选择器的失败面是来自单一层的一个错误；调用方看到真实原因（koffi 加载失败、COM 拒绝、对话框崩溃），而不是链式聚合的错误。
|
||||
- 本包不再调用 `pwsh`/`powershell.exe`；WinForms 脚本、其 `SetProcessDPIAware` 修正与 `-STA` 标志随之消失。
|
||||
- 测试相应缩减：pwsh/5.1 级联与三连败用例被一个"失败原样上报、无回退"用例取代；默认适配器测试改驱动 Linux 层。
|
||||
- 重新引入条件：未来出现在我们打包链之外的 win32 机制（我们不随包分发的系统提供的对话框宿主）才值得在同一判据下保留一层回退。
|
||||
@@ -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/testing/2026-07-25-scriptable-llm-wire-fault-server.md
|
||||
2026-07-25-scriptable-llm-wire-fault-server.md: b8e64d92db224c199d0f8c547f0caa588d0ca65e
|
||||
2026-07-25-scriptable-llm-wire-fault-server.zh.md: 32b0608748c155253359b1fa9a18c467ff783b39
|
||||
2026-07-25-scriptable-llm-wire-fault-server.zh.md: 54604e2d8c019386d8f94d90d859bb08ce58b030
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 可脚本控制的 LLM（大语言模型）协议层故障服务器
|
||||
# Agent Note: 可脚本控制的 LLM 协议层故障服务器
|
||||
|
||||
Status: implemented
|
||||
|
||||
|
||||
Reference in New Issue
Block a user