Appearance
Coding Agent 的工作环境是什么：Workspace 与 Filesystem State
前置：Side-effect / Approval；Durable Facts；Capability Model
核心问题：代码任务中的文件事实到底属于 Workspace、Runtime State 还是 Model Context，进程重启后哪些必须仍然存在？
模型 context reset 后，磁盘上的 patch 和测试报告仍存在；新 Run 通过 workspace adapter 重新读取即可继续。Agent 写 progress.md.tmp 后 fsync/rename 原子替换，避免进程中断留下半文件。
Mental Model
text
Agent decision → workspace capability → file/shell/patch → command result → diff/test/artifact → next turn/resumeCoding Agent 的连续性来自 workspace/snapshot/artifact 和结构化 progress，而不是无限 transcript。模型换 Context 后应能重新 attach 环境并验证当前状态。
Workspace Mental Model
Workspace 是模型可操作的大型外部状态。Context 只保存路径/摘要，真实文件留在 filesystem，需要时搜索/读取。Workspace 是模型可搜索、修改和执行的外部持久状态，不应该全部搬进 Context。模型通过文件路径、grep、diff、artifact ref 渐进访问，Runtime 管理权限和生命周期。
它独立于聊天 Context。
🔍 源码对照：Turn Context 同时持有 shell-watch / resource owner
完整源码与通用分析见 09-01 Run Lifecycle / State Machine。这里不重复代码；这里关注 Workspace ownership：shell-watch 与 resource owner 属于 Turn Runtime Context，独立于聊天 messages，并需要显式 cleanup。
源码说明
durable file policy 与 box/local-exec 并列存在，说明 Workspace 同时包含“文件作为外部状态”和“命令在哪个执行环境运行”两个问题。Coding Agent 的文件变化不能只存在聊天 Context 里；恢复时要重新查看 filesystem reality，而不是相信旧 Turn 中的描述。
工程边界
Grok Bot 的目录布局、mount 和 file policy 是产品实现；Shadow Harness 只吸收 workspace manifest、allowed roots、artifact identity 和 revalidation 这些通用问题。
Shadow Harness 对照
- WorkspaceAdapter 返回真实 stat/hash/diff，模型不能直接宣告文件已修改。
- Checkpoint 保存 workspace reference/manifest，不复制整棵 filesystem 到 RunState。
验证
checkpoint 后人工修改 workspace 文件再 resume；Runtime 必须检测 manifest/hash drift，并要求 revalidate，而不是继续使用旧计划。
Filesystem as External State
文件系统中的代码、配置和 artifact 可以跨 turn/session 存在，但也可能被外部进程修改。读写要带 workspace root、路径规范化、snapshot/version 与 trust boundary，不能把当前 Context 当文件真相。
文件系统可承载长任务事实和大型 artifact，但需要路径边界、版本/mtime、原子写、冲突和 provenance。不能把“文件存在”直接等于业务成功。
Read / Search / Glob / Grep
搜索工具应先定位再读取：glob 找候选、grep 找符号/文本、read 指定范围；避免一次读取整个仓库。Coding Agent 应先用 glob/list 建结构，再 grep/search 定位符号，最后只 read 相关范围；这是一种 filesystem progressive disclosure。工具必须限制 workspace root、输出大小和编码，并保留 line/path reference。
读文件能力应优先支持按路径、范围和搜索结果渐进读取，限制结果大小并保留行号。
最小实现 / 数据结构
python
workspace = await sandbox.open(manifest)
paths = await workspace.search("TODO")
patch = await agent.propose_patch(paths)
await workspace.apply_patch(patch)
result = await workspace.exec(["pytest", "-q"] )在 Shadow Harness 中怎么落地
WorkspaceAdapter 抽象 read/search/patch/exec/artifact/snapshot；skills 采用 progressive loading；session 与 workspace snapshot 分开。
Failure Modes
把整个 Workspace 一次性塞进模型 Context
症状： 递归读取整仓和生成文件。
为什么危险： token 爆炸、context 污染且模型持有陈旧快照。
处理： Workspace 是外部事实源；通过 tree/glob/grep/range read 渐进读取并保留 file version。
如何验证
| Case | 断言 |
|---|---|
| 把整个 Workspace 一次性塞进模型 Context | 大型 repo 首次 Context 不含整仓，Agent 仍能 search/read 定位目标。 |
关联源码
自测
- Context 里说“文件已修改”但 Workspace 实际没有 diff。Coding Agent 应以哪一种状态作为真实文件事实？
- 临时 scratch、工作树修改、已提交 Git 状态分别有不同生命周期，为什么不能都叫“Memory”？