diff --git a/AGENTS.md b/AGENTS.md index d15c406..78e59c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,17 @@ 每份文档顶部标注四种状态之一：`AUTHORITATIVE` 当前事实或合同、`DECISION` 已批准决策、`RESEARCH` 研究结论、`ARCHIVED` 历史材料。研究结论和归档材料不能当作当前实现使用。 +权威文档的顶部至少包含： + +```markdown +> Status: AUTHORITATIVE +> Last updated: YYYY-MM-DD +> Last verified: YYYY-MM-DD（核对了哪几条；只核对了一部分就写明范围） +> Verified against: +``` + +`Last updated` 和 `Last verified` 是两件事：改过不等于核对过。`Verified against` 记录核对时代码停在哪个提交，指码已经前进很多时应当重新核对。索引汇总在 `docs/README.md`，但不能代替文档自身的标注。 + ## 硬规则 - 改变 `docs/ARCHITECTURE.md`、`docs/INTERFACES.md`、`docs/SHARED_CORE.md`、`docs/ZCODE_RUNTIME.md` 描述的行为前，先有 `DECISION` 记录。实现不能反向改写合同。 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4d74b87..cd3fbff 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,7 +1,42 @@ # 当前架构 +> Status: AUTHORITATIVE +> Last updated: 2026-10-07 +> Last verified: 2026-10-07（本轮核对 heartbeat 周期与 15 秒宽限、结果 checkpoint、事件补拉与降级；其余条款沿用此前记录，未逐条复核） +> Verified against: ed2d402 + 本文件描述当前代码，不是历史阶段的冻结设计。公共类型见 `src/interfaces.ts`，MCP schema 见 `src/mcp/schemas.ts`；共享边界见 [SHARED_CORE.md](SHARED_CORE.md)。 +## 总览 + +```text +Codex 宿主 + │ MCP（stdio） +Bridge MCP server（src/mcp） + │ +TaskManager（src/manager） + ├─ TaskStore（src/store） 任务证据持久化 + ├─ 调度队列与 worker 启动 + └─ 事件与 feedback 聚合 + │ +ZCodeAppServerAdapter（src/adapters） + │ +ZCode app-server（zcode.cjs app-server --stdio） +``` + +| 组件 | 负责 | 不负责 | +|---|---|---| +| MCP server | 对外契约面：工具名、输入 schema、输出结构 | 任务状态判定 | +| TaskManager | 生命周期所有者：排队、调度、attempt 边界、终态、续跑、清理 | ZCode 协议细节 | +| TaskStore | 任务证据持久化：status、result、events、attempt 元数据 | 业务判断 | +| Worker | 单 attempt 的执行进程，一次进入、不重跑 | 调度决策 | +| AppServerAdapter | ZCode 协议边界：session、事件、交互、清理 | 宿主策略 | +| 调用宿主 | 准备执行目录、决定是否接收改动 | 任务调度 | + +合同级定义见 [INTERFACES.md](INTERFACES.md)。 + +## 运行细节 + `src/mcp/main.ts` 仅为 Codex 入口；`src/host/stdio.ts` 组合宿主 profile、运行配置、TaskStore、DirectWorkspaceProvider、BridgeTaskManager 和 MCP server。启动不创建 ZCode session；坏的 Bridge 配置会明确阻止启动。doctor 对坏配置返回 error。 Manager 用进程内 promise 队列以及同一 data root 下的 `.tasks/.manager.lock` 序列化调度。锁记录 owner PID，活 owner 不因时间超限被驱逐；死 owner 由串行 reclaim guard 回收。未完成 owner 发布的异常锁明确报错。不同 data root 不共享调度锁，需要调用宿主避免向重叠目录提交冲突任务。PID 重用的跨进程身份强化尚未验证。 diff --git a/docs/INTERFACES.md b/docs/INTERFACES.md index 8dc75bb..965a845 100644 --- a/docs/INTERFACES.md +++ b/docs/INTERFACES.md @@ -1,5 +1,10 @@ # 当前接口与兼容边界 +> Status: AUTHORITATIVE +> Last updated: 2026-10-07 +> Last verified: 2026-10-07（本轮核对事件补拉与降级、`session/read` 未接入、默认工具数 13；其余条款沿用此前记录，未逐条复核） +> Verified against: ed2d402 + 准确类型与 schema 以 `src/interfaces.ts` 和 `src/mcp/schemas.ts` 为准。核心公共入口见 [SHARED_CORE.md](SHARED_CORE.md)。历史源码注释中的 V0.1/FROZEN 是沿革说明，不代表当前新增功能已经冻结。 默认 MCP 工具：`zcode_task`、`zcode_status`、`zcode_feedback`、`zcode_result`、`zcode_continue`、`zcode_cancel`、`zcode_events`、`zcode_interaction_reply`、`zcode_doctor`、`zcode_model_catalog`、`zcode_default_model`、`zcode_set_default_model`、`zcode_clear_default_model`。实验 progress probe 需显式启用。 @@ -19,3 +24,5 @@ zcode_interaction_reply 必须引用当前 attempt 的 interaction_requested.req 稳定错误包括 TASK_INVALID、TASK_ALREADY_EXISTS、TASK_ID_CONFLICT、CONTINUE_OPERATION_CONFLICT、BRIDGE_BUSY、REQUEST_QUEUE_TIMEOUT、TASK_NOT_FOUND、TASK_NOT_FINISHED、TASK_STATE、CANCEL_FAILED，以及 runtime/provider、timeout、invalid_agent_report 等执行错误。相同 task_id 与相同任务内容会重放首次回执；不同内容返回 TASK_ID_CONFLICT。超时后使用原 task_id 查询或重试，不要换 ID。续作可传 operation_id；相同 ID 与相同反馈会重放回执，不同反馈返回 CONTINUE_OPERATION_CONFLICT。cleanup_failed 表示运行时清理未验证，任务保持目录占用；再次 zcode_cancel 尝试清理后保留原执行结果。 公开进度 usage 仅保留数值 token/cost 字段，隐藏推理、未知 metadata 和原始 RPC error 不转发。审批需要的工具输入、任务 prompt、可见回答、私有本地日志仍属于可能含敏感内容的任务证据，使用者须按本地数据策略管理。 + +控制面、权威状态与补充观察的边界见 [decisions/ADR-004](decisions/ADR-004-separate-control-state-and-observation.md)：ZCode 本地 metadata、rollout 与日志可以进入补充观察，但不得单独决定任务状态、状态迁移或恢复结论；Desktop `tasks-index.sqlite` 是登记过的 best-effort 集成例外。 diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md index 7434fa9..eedcffe 100644 --- a/docs/PROJECT_STATE.md +++ b/docs/PROJECT_STATE.md @@ -6,6 +6,8 @@ 当前状态快照，回答"现在什么能用、什么不能用"。路线图和优先级不在这里。 +控制面、权威 Bridge 状态与补充观察的边界见 [decisions/ADR-004](decisions/ADR-004-separate-control-state-and-observation.md)：本地材料可以观察，但不能单独驱动任务状态、状态迁移与恢复结论。 + ## 版本与发布 - 当前发布：`1.2.2`（`package.json`、`plugins/codex-zcode-bridge/plugin.json`）。 diff --git a/docs/README.md b/docs/README.md index 1a7b078..2d83cba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,8 @@ # 文档索引 / Documentation +> Status: AUTHORITATIVE（仅指本索引） +> Last updated: 2026-10-07 + 英文使用者从 [README.md](../README.md) 开始。技术文档为中文。本文是文档路由：先看状态等级，再按读者路径选文档。 English readers start at [README.md](../README.md). This index is bilingual; the technical documents themselves are written in Chinese. @@ -15,7 +18,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the | `RESEARCH` | 研究结论 | 只作参考，不代表当前实现 | | `ARCHIVED` | 历史材料 | 默认不读，只用于追溯 | -现状说明：下面的现有文档在本次整理前没有状态标注，状态由本索引统一指定。文档下次被修改时补上顶部标注。 +每份文档必须在顶部自带标注；本索引只做汇总，不能代替标注。跳过本索引直接打开某份权威文档时，也应能从文件顶部看到状态与核对情况。 ## For Master Agents @@ -46,15 +49,15 @@ English readers start at [README.md](../README.md). This index is bilingual; the | [README.md](../README.md) | en | 2026-10-05 | 未记录 | | [README.zh-CN.md](../README.zh-CN.md) | zh | 2026-10-03 | 未记录 | | [PROJECT_STATE.md](PROJECT_STATE.md) | zh | 2026-10-07 | 2026-10-07 | -| [ARCHITECTURE.md](ARCHITECTURE.md) | zh | 2026-10-03 | 未记录 | -| [INTERFACES.md](INTERFACES.md) | zh | 2026-10-06 | 未记录 | +| [ARCHITECTURE.md](ARCHITECTURE.md) | zh | 2026-10-07 | 2026-10-07（部分） | +| [INTERFACES.md](INTERFACES.md) | zh | 2026-10-07 | 2026-10-07（部分） | | [SHARED_CORE.md](SHARED_CORE.md) | zh | 2026-10-06 | 未记录 | | [ZCODE_RUNTIME.md](ZCODE_RUNTIME.md) | zh | 2026-10-03 | 未记录 | | [plugins/codex-zcode-bridge/README.md](../plugins/codex-zcode-bridge/README.md) | zh | 2026-10-03 | 未记录 | | [plugins/codex-zcode-bridge/SECURITY.md](../plugins/codex-zcode-bridge/SECURITY.md) | zh + en | 2026-10-03 | 未记录 | | [plugins/codex-zcode-bridge/skills/zcode-bridge/SKILL.md](../plugins/codex-zcode-bridge/skills/zcode-bridge/SKILL.md) | zh | 2026-10-06 | 未记录 | -`最后核对` 表示上一次有人把文档内容与代码逐条对照的日期。这一列目前全部为空，说明此前没有这个习惯；新建和修改文档时必须填写，否则该文档只能算"最后更新"，不能算"已验证"。 +`最后核对` 表示上一次有人把文档内容与代码逐条对照的日期，`（部分）` 表示只核对了其中一部分条款，具体范围写在文档顶部的 `Last verified` 行。`未记录` 不等于内容有问题，只表示还没有人做过这次核对。新建和修改文档时必须填写，否则该文档只能算"最后更新"，不能算"已验证"。 ### 决策 DECISION @@ -64,7 +67,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the | [ADR-001](decisions/ADR-001-appserver-as-production-execution-path.md) | 2026-10-07 | Accepted：生产执行路径使用 app-server | | [ADR-002](decisions/ADR-002-manager-owns-task-lifecycle.md) | 2026-10-07 | Accepted：Manager 独占生命周期，worker 通过 attempt claim 入场 | | [ADR-003](decisions/ADR-003-execution-directory-prepared-by-host.md) | 2026-10-07 | Accepted：执行目录由调用宿主准备 | -| [ADR-004](decisions/ADR-004-observation-is-not-control.md) | 2026-10-07 | Proposed：本地材料只作观察面，待 Master 决策 | +| [ADR-004](decisions/ADR-004-separate-control-state-and-observation.md) | 2026-10-07 | Accepted：分离运行时控制、权威状态与补充观察 | | [decisions/roadmap-decisions-2026-09-27.md](decisions/roadmap-decisions-2026-09-27.md) | 2026-09-27 | 路线图与决策讨论 | | [decisions/reliability-repair-plan-v2-2026-10-03.md](decisions/reliability-repair-plan-v2-2026-10-03.md) | 2026-10-03 | 可靠性修复计划，含未完成项 | @@ -76,6 +79,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the | [research/desktop-task-refresh-2026-09-28.md](research/desktop-task-refresh-2026-09-28.md) | 2026-09-28 | ZCode Desktop 任务列表刷新机制 | | [research/start-plan-headless-2026-09-27.md](research/start-plan-headless-2026-09-27.md) | 2026-09-27 | Start Plan headless 认证阻塞与 Coding Plan 回归 | | [research/native-cli-vs-appserver-2026-10-05/README.md](research/native-cli-vs-appserver-2026-10-05/README.md) | 2026-10-05 | Native CLI vs app-server 研究：结论、6 篇文档、实验脚本与证据索引 | +| [research/task-feedback-v0-1-2026-10-05/README.md](research/task-feedback-v0-1-2026-10-05/README.md) | 2026-10-05 | Task Feedback v0.1 的输入：app-server 事件能力探针与两份建议 | 带日期的研究目录可以自带 README 作为该主题的文档地图；逐篇条目写在那份 README 里，不重复列在本索引。 @@ -92,7 +96,7 @@ English readers start at [README.md](../README.md). This index is bilingual; the | 文档 | 说明 | |---|---| -| [TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md](../TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md) | Task Feedback v0.1 的交付报告，一次性材料 | +| [reports/task-feedback-v0-1-implementation-2026-10-06.md](reports/task-feedback-v0-1-implementation-2026-10-06.md) | Task Feedback v0.1 的交付报告，一次性材料 | ### 自动生成 Generated diff --git a/docs/SHARED_CORE.md b/docs/SHARED_CORE.md index 0b3b04e..0b7c886 100644 --- a/docs/SHARED_CORE.md +++ b/docs/SHARED_CORE.md @@ -1,5 +1,9 @@ # 共享核心与宿主适配 +> Status: AUTHORITATIVE +> Last updated: 2026-10-06 +> Last verified: 未逐条核对 + Codex 与 dsh 连接同一个 ZCode 执行端，因此任务调度、存储、续跑、取消、结果归一化、ZCode 协议和 Desktop 索引属于共享核心。`src/adapters/` 适配 ZCode，不是调用宿主。 公共入口是 `codex-zcode-bridge/core`（源码 `src/core.ts`）。入口没有启动副作用，提供类型声明，并导出 `buildTaskFeedbackSnapshotV01` 与 `renderTaskFeedback`。`npm run build:core` 构建核心；当前仓库仍为 private，未发布独立 npm 包。可在本地构建后用 `npm pack` 生成版本化制品供 fork 锁定；发布渠道和独立核心版本策略尚未确定。 diff --git a/docs/ZCODE_RUNTIME.md b/docs/ZCODE_RUNTIME.md index 5c0a3e2..ebc89f7 100644 --- a/docs/ZCODE_RUNTIME.md +++ b/docs/ZCODE_RUNTIME.md @@ -1,5 +1,9 @@ # ZCode 运行配置边界 +> Status: AUTHORITATIVE +> Last updated: 2026-10-03 +> Last verified: 未逐条核对 + 当前生产路径是 `node zcode.cjs app-server --stdio`，不是历史 CLI `--prompt --json`。解析入口为 `NodeRuntimeResolver`，配置项与用户设置方法见仓库 README。 Bridge 只读取官方 builtin/personal provider 配置，不复制、不改写内容，也不将环境或凭据写入任务 metadata。personal 配置的 `config.providerConfigRules.providerRules` 必须为非空数组或对象；已知空 stub 被拒绝。结构验证不能证明 provider 可用或账号有权限。 diff --git a/docs/decisions/ADR-004-observation-is-not-control.md b/docs/decisions/ADR-004-observation-is-not-control.md deleted file mode 100644 index cecbb8a..0000000 --- a/docs/decisions/ADR-004-observation-is-not-control.md +++ /dev/null @@ -1,33 +0,0 @@ -# ADR-004 — 本地材料只作观察面，不作控制面 - -Status: Proposed（需要 Master 决策） -Date: 2026-10-07 - -## Context - -ZCode 在本机留下多种材料：app-server 事件、CLI 的 metadata/output/model-io/rollout 文件、日志，以及 Desktop 的 `tasks-index.sqlite`。其中一部分结构已经在研究阶段被观测过，但都属于未公开、随版本变化的内部结构。 - -在 bridge 之外的历史讨论中已经出现过方向性结论：控制面走 app-server RPC，本地文件只用于观察，且 `task-index` 的写入是需要单独治理的既有例外。这一结论目前没有在仓库文档里形成决策记录，因此本条标为 Proposed。 - -## Proposed decision - -- 控制面只使用 app-server 及其支持的 RPC。 -- 本地 metadata、rollout、日志、Desktop 索引作为观察来源，读取只读、失败可降级，不得成为任务状态的事实来源。 -- 观察来源的优先级低于 app-server 事件；本地读取必须在隐私边界内进行，不做原始 reasoning 或工具参数的转发。 -- Desktop 索引同步保持 best effort 的旁路写入，明确不是权威数据；它是当前唯一的本地写入例外。 - -## Rationale - -本地结构没有稳定性承诺。把它们当作控制面会让 Bridge 在 ZCode 升级后静默失效，也会把未验证的推断变成任务状态。 - -## Consequences - -- 恢复与状态判定必须能用原生通道解释；本地材料只能提供线索，不能单独定论。 -- 观察能力受安装版本影响，需要按版本标注并保留 NOT RUN 记录。 -- 如果将来确实需要写本地结构，必须单独走决策，并说明兼容与回滚。 - -## Evidence - -- `docs/ARCHITECTURE.md`："Desktop 索引同步是 best effort，事务内检查 schema 与 Bridge owner、更新有限状态字段，保留用户标题与额外 metadata。回归使用临时 SQLite。真实 Desktop schema/刷新/并发行为受安装版本影响，本轮未写入真实数据库。" -- `docs/INTERFACES.md`："公开进度 usage 仅保留数值 token/cost 字段，隐藏推理、未知 metadata 和原始 RPC error 不转发。" -- `docs/ZCODE_RUNTIME.md`：运行配置与发现逻辑只读官方 provider 配置，不复制、不改写、不把凭据写入任务 metadata。 diff --git a/docs/decisions/ADR-004-separate-control-state-and-observation.md b/docs/decisions/ADR-004-separate-control-state-and-observation.md new file mode 100644 index 0000000..5c472d4 --- /dev/null +++ b/docs/decisions/ADR-004-separate-control-state-and-observation.md @@ -0,0 +1,99 @@ +# ADR-004 — 分离运行时控制、权威状态与补充观察 + +Separate Runtime Control, Authoritative State, and Supplemental Observation + +Status: Accepted +Date: 2026-10-07 + +## Context + +ZCode 在本机留下多种材料：app-server 事件、CLI 的 metadata / output / model-io / rollout 文件、日志，以及 Desktop 的 `tasks-index.sqlite`。其中一部分在研究阶段被观测过，但它们都是未公开、随版本变化的内部结构。 + +这里要区分的是三件事，而不是"控制"与"观察"两件事： + +- 谁控制 ZCode —— 受支持的运行时接口。 +- 谁拥有 Bridge 生命周期的真相 —— Bridge 自己持久化的证据。 +- 谁提供额外信息 —— ZCode 本地材料，以及 Desktop 索引这类集成副作用。 + +一个命名澄清：`src/observation/` 不是本条 ADR 说的"ZCode 本地观察面"。它从 Bridge 自己拥有的 TaskStore 证据推导有界观察，属于权威 Bridge 状态模型的一部分，源码注释也写明这里不发起 OS 查询。读到该模块不构成对本 ADR 的违反。 + +本条决策来自 bridge 之外的历史设计讨论；在此之前的仓库文档只散落描述过它，从未形成记录，因此现在正式记录。 + +## Decision + +### 三类划分 + +| 类型 | 例子 | 能否写 | 能否决定 Bridge 状态 | +|---|---|---|---| +| Control | app-server 及其受支持的 RPC | 可以，走受支持语义 | 是，通过受支持语义 | +| Supplemental Observation | ZCode 本地 metadata / rollout / log | 不可以 | 不可以 | +| Integration Side Effect | `tasks-index.sqlite` | 可以，best effort | 不可以 | + +```text +Control Plane + │ +ZCode 受支持的运行时接口（app-server / supported RPC） + +Authoritative Bridge State + │ +Bridge TaskStore + TaskManager 拥有的证据 + +Supplemental Observation + │ +ZCode local metadata / rollout / logs + │ +可以观察、可以诊断、可以补充可见信息 +但不能单独改变任务状态或恢复结论 + +Desktop Integration + │ +tasks-index.sqlite + │ +允许 best-effort 写入 +但永远非权威 +失败不得影响任务生命周期 +``` + +### 补充观察的边界 + +本地材料可以进入补充观察面：帮助诊断、补足可见信息、解释"app-server 连接断开后 runtime 是否仍有活动"这类问题。 + +它们不能单独驱动 Bridge 生命周期、状态迁移或恢复结论。允许的形态是给 Codex 一条有来源、有时效的观察，例如"app-server 连接断开后，本地日志显示 session 仍在活动"；不允许的形态是据此把 TaskStore 里的 `running` 改写成 `completed`。 + +### 恢复继续依靠 Bridge 自己的证据 + +Bridge 生命周期恢复只使用自己拥有的持久化证据：TaskStore、heartbeat、attempt、`execution.claim`、outcome checkpoint、cleanup 验证。不用 ZCode 内部文件补洞。 + +### Desktop 索引是登记过的集成例外 + +`tasks-index.sqlite` 的写入保留，但它不属于补充观察面，因为它产生副作用。它是明确登记的 best-effort 集成例外，并且必须满足： + +- 不得作为任务执行的门禁 +- 不得改变 Bridge 任务状态 +- 不得参与恢复判定 +- 不得决定任务完成 +- 不得决定清理是否成功 +- 失败不得影响任务生命周期 + +### 未来若需要读写本地结构 + +必须单独走一次决策，说明兼容性、回滚方式与失败语义。 + +## Rationale + +本地结构没有稳定性承诺。把补充观察升级成权威依据，会让 Bridge 在 ZCode 升级后静默给出错误状态；反过来，完全禁止读取又会丢掉真实有价值的可观测性。三分类把"可以看"和"可以据此下结论"拆开，同时给 Desktop 集成留出一个边界清楚、可审计的例外。 + +## Consequences + +- 恢复与状态判定必须能用原生通道解释；本地材料只能提供线索，不能单独定论。 +- 观察能力受安装版本影响，需要按版本标注并保留 NOT RUN 记录。 +- 读取补充观察必须落在隐私边界内：不转发原始 reasoning 和工具参数。 +- 未来新增 `ZCodeObserver` 一类读取组件时，默认落在补充观察类，不得进入状态判定路径。 +- 如果将来确实需要写本地结构，必须单独走决策。 + +## Evidence + +- 代码核对：`src/adapters/task-index-sync.ts` 的注册与状态更新是 best effort；`src/adapters/zcode-app-server-adapter.ts` 在 session ready 后调用并捕获失败，不阻塞任务；`src/runtime/account-provider.ts` 的 `zcodeTasksIndexPath()` 从 `provider_config.json` 推出 `/tasks-index.sqlite`；`src/observation/` 只读 TaskStore 证据。 +- `docs/ARCHITECTURE.md`："Desktop 索引同步是 best effort，事务内检查 schema 与 Bridge owner、更新有限状态字段，保留用户标题与额外 metadata。回归使用临时 SQLite。真实 Desktop schema/刷新/并发行为受安装版本影响，本轮未写入真实数据库。" +- `docs/INTERFACES.md`："公开进度 usage 仅保留数值 token/cost 字段，隐藏推理、未知 metadata 和原始 RPC error 不转发。" +- `docs/ZCODE_RUNTIME.md`：运行配置与发现逻辑只读官方 provider 配置，不复制、不改写、不把凭据写入任务 metadata。 diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 79bc1b2..17f6bdf 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -12,18 +12,16 @@ | [roadmap-decisions-2026-09-27.md](roadmap-decisions-2026-09-27.md) | DECISION | 2026-09-27 的路线图与决策讨论。仍然成立的结论需要提炼进 `ARCHITECTURE.md` / `INTERFACES.md`；本文本身不是当前事实来源。 | | [reliability-repair-plan-v2-2026-10-03.md](reliability-repair-plan-v2-2026-10-03.md) | DECISION | Bridge 可靠性修复计划。A/B 主要改动已实现；C/D 与宿主启动核验仍有未完成项。 | -## 待补的 ADR - -已补写： +## ADR 索引 | ADR | 状态 | 主题 | |---|---|---| | [ADR-001](ADR-001-appserver-as-production-execution-path.md) | Accepted | 生产执行路径使用 ZCode app-server | | [ADR-002](ADR-002-manager-owns-task-lifecycle.md) | Accepted | Manager 独占任务生命周期，worker 通过 attempt claim 入场 | | [ADR-003](ADR-003-execution-directory-prepared-by-host.md) | Accepted | 执行目录由调用宿主准备，Bridge 不创建也不删除 | -| [ADR-004](ADR-004-observation-is-not-control.md) | Proposed | 本地材料只作观察面，不作控制面 | +| [ADR-004](ADR-004-separate-control-state-and-observation.md) | Accepted | 分离运行时控制、权威状态与补充观察；Desktop 索引是登记过的集成例外 | -ADR-001 到 ADR-003 只搬运权威文档里已经写明的结论。ADR-004 是唯一需要 Master 决策的一条：仓库文档里没有明文记录"观察面不等于控制面"，此前只有设计讨论，因此它保持 Proposed，不当作已批准决策使用。 +ADR-001 到 ADR-003 只搬运权威文档里已经写明的结论。ADR-004 原先没有明文记录，只有 bridge 之外的设计讨论，因此先以 Proposed 记录；2026-10-07 由 Master 明确按"强化版 A"接受，原则冻结，未因此增加任何读取 ZCode 本地材料的代码。 ## 命名 diff --git a/TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md b/docs/reports/task-feedback-v0-1-implementation-2026-10-06.md similarity index 97% rename from TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md rename to docs/reports/task-feedback-v0-1-implementation-2026-10-06.md index 992e48b..2b0f6e1 100644 --- a/TASK_FEEDBACK_V01_IMPLEMENTATION_REPORT.md +++ b/docs/reports/task-feedback-v0-1-implementation-2026-10-06.md @@ -1,5 +1,9 @@ # Task Feedback v0.1 Implementation Report +> Status: REPORT +> Date: 2026-10-06 +> 一次性交付报告，不是当前事实来源。当前行为见 [INTERFACES.md](../INTERFACES.md) 与 [PROJECT_STATE.md](../PROJECT_STATE.md)。 + ## 1. Summary Implemented a provenance-aware `TaskFeedbackSnapshotV01`, an independent plain-text renderer, and the additive `zcode_feedback` MCP tool. The tool returns the structured snapshot and renders concise Codex transcript text. `zcode_events` remains the detailed event-history API. This was integrated additively on the v1.1.0 master baseline; its existing A4 `renderFeedback` template and opt-in task ledger remain intact. diff --git a/NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md b/docs/research/task-feedback-v0-1-2026-10-05/NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md similarity index 97% rename from NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md rename to docs/research/task-feedback-v0-1-2026-10-05/NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md index a36b233..2a6adb4 100644 --- a/NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md +++ b/docs/research/task-feedback-v0-1-2026-10-05/NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md @@ -1,5 +1,9 @@ # Native Feedback Renderer Recommendation +> Status: RESEARCH +> Date: 2026-10-05 +> 研究结论，不代表当前实现。索引见 [README.md](README.md)。 + This recommendation uses the evidence in [ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md](ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md). It separates Bridge/runtime observations from Agent-reported result fields. ## Safe to render now diff --git a/docs/research/task-feedback-v0-1-2026-10-05/README.md b/docs/research/task-feedback-v0-1-2026-10-05/README.md new file mode 100644 index 0000000..9a8fd7b --- /dev/null +++ b/docs/research/task-feedback-v0-1-2026-10-05/README.md @@ -0,0 +1,20 @@ +# Task Feedback v0.1 输入（2026-10-05） + +> Status: RESEARCH +> Date: 2026-10-05 +> 研究结论，不代表当前实现。观测版本 ZCode CLI 0.16.9。 + +本目录是 Task Feedback v0.1 实施任务的输入材料：一次真实 app-server 探针，以及由它派生的两份建议。实现结果见 [Task Feedback v0.1 实施报告](../../reports/task-feedback-v0-1-implementation-2026-10-06.md)。 + +## 文档 + +| 文档 | 内容 | +|---|---| +| [ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md](ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md) | 真实 runtime 探针：环境、事件类型、能力与隐私边界 | +| [TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md](TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md) | 快照 schema 建议：冻结核心信封，未观测字段保持可空 | +| [NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md](NATIVE_FEEDBACK_RENDERER_RECOMMENDATION.md) | 原生文本渲染建议：什么可以显示、什么不能 | +| [evidence/run-001-summary.json](evidence/run-001-summary.json) | 探针的安全摘要（4 KB） | + +## 适用范围 + +探针结论只适用于记录的本机版本与实验范围。建议里标注为不支持或未观测的部分，在实现中保持 `null` 或不渲染。 diff --git a/TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md b/docs/research/task-feedback-v0-1-2026-10-05/TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md similarity index 97% rename from TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md rename to docs/research/task-feedback-v0-1-2026-10-05/TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md index 458f1b7..0c1c03d 100644 --- a/TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md +++ b/docs/research/task-feedback-v0-1-2026-10-05/TASK_FEEDBACK_SCHEMA_RECOMMENDATION.md @@ -1,8 +1,12 @@ # Task Feedback Schema Recommendation +> Status: RESEARCH +> Date: 2026-10-05 +> 研究结论，不代表当前实现。索引见 [README.md](README.md)。 + **Decision:** Do **not** freeze the full `TaskFeedbackSnapshotV01` candidate yet. Freeze the core envelope and source semantics now; keep uncertain fields nullable/deferred until their state transitions are directly observed. -Evidence: real ZCode `0.16.9` app-server probe documented in [ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md](ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md) and [run-001-summary.json](probe/evidence/run-001-summary.json). +Evidence: real ZCode `0.16.9` app-server probe documented in [ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md](ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md) and [run-001-summary.json](evidence/run-001-summary.json). ## KEEP diff --git a/ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md b/docs/research/task-feedback-v0-1-2026-10-05/ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md similarity index 98% rename from ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md rename to docs/research/task-feedback-v0-1-2026-10-05/ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md index 52c2887..3cd1e3d 100644 --- a/ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md +++ b/docs/research/task-feedback-v0-1-2026-10-05/ZCODE_APPSERVER_EVENT_CAPABILITY_PROBE.md @@ -1,5 +1,9 @@ # ZCode App-Server Event Capability Probe +> Status: RESEARCH +> Date: 2026-10-05 +> 研究结论，不代表当前实现。索引见 [README.md](README.md)。 + **Date:** 2026-10-05 (Asia/Shanghai) **Scope:** Probe-only runtime research. No production Bridge source, schema, worker, or renderer was modified. @@ -17,7 +21,7 @@ The probe spawned the installed `zcode.cjs app-server --stdio` directly, created temporary workspaces under the OS temp directory, and used the account-provider reply in memory. Probe records retained event names, sequence numbers, key names, and a small allowlist of metadata. They did **not** retain model text, reasoning text, tool input/arguments, headers, credentials, or raw RPC frames. -Sanitized evidence summary: [probe/evidence/run-001-summary.json](probe/evidence/run-001-summary.json). +Sanitized evidence summary: [evidence/run-001-summary.json](evidence/run-001-summary.json). ## Method and evidence levels diff --git a/probe/evidence/run-001-summary.json b/docs/research/task-feedback-v0-1-2026-10-05/evidence/run-001-summary.json similarity index 100% rename from probe/evidence/run-001-summary.json rename to docs/research/task-feedback-v0-1-2026-10-05/evidence/run-001-summary.json