研究索引 C：SDK、控制面、存储、人工交互与自动化¶

本记录是作者的源码阅读与章节写作证据，不是对自己四章的独立审查 PASS。作者负责 docs/14-sdk.md、15-ui-and-api.md、16-storage-and-migrations.md、17-human-and-automation.md；后续独立交叉审查由其他作者承担。

冻结版本与已实际比对的差异¶

主研究树：upstream，HEAD da00f7f5358f2949383b35c14f548bc20187d80c。
运行实验源码基线：tag dsh-v0.2.0-rc.2，commit 639ed015397290b3745d163aafe02ffee4aa3f84。
实际用 git diff 比较两个 commit 的 packages/sdk、python/sdk：SDK 源码没有变更；SDK README/i18n 删除了旧内部说明链接。不能将 README 的整理说成 SDK wire 新增功能。
SDK wire 仍只有 initialize / session/prompt / shutdown；Web cancel/resume 和 ACP cancel/resume 不适用于 SDK。
TS env 完整替换，Python env 合并继承环境；Python 必须显式 home，TS 可以依 runtime 默认。这些是两个冻结快照共同的契约。
Python源码 pyproject.toml 占位 0.0.0.dev0。父作者查询实际 PyPI 最新 SDK/runtime 均 0.1.5rc1，npm 为 0.2.0-rc.2，发布渠道不同时推进。本课程采用 rc.2 Python源码副本 + pydantic + public dsh_bin 指向 rc.2 可执行CLI，不宣称 pip 最新与本课程运行版本一致。
Session writer 两树都 SESSION_FORMAT_VERSION = 4；上游 docs/session-format-status.md 的 latestReleasedVersion3/alpha.1 发布记录落后。课程依据冻结tag代码与实际产物 V4，单独披露记录差异。
主分支 schedule 工具从 schedule/src/tools.ts 提取到 tool-schedule/src/index.ts；ScheduleService 不再 inject tools/自动挂所有root工具，而由scope/preset挂独立插件。新增 SubagentSessionError 和 delegated child拒绝，并改变某些历史 event invariant 维护方式。实际 rc.2配置不可直接引用新增独立工具包。
plan-mode/src/index.ts 的 rc.2→main差异只有文档注释链接；没有本章讨论的计划生效语义变化。
比对涉及的 browser connection源码、业务SQLite物理schema、派生搜索schema、V3→V4 codec/migration源码未改变；V3→V4 README更新不代表存储codec换代。

实际阅读范围¶

下面按调用链记录。标“完整”指读取整个所列短/中型文件并跟踪相关函数；大型文件只列实际打开与复读的区间，不宣称全仓逐行研究。区间以冻结主分支行号为准，rg 搜索/函数地图不算完整上下文阅读。阅读过程中大批工具输出有过截断；写作前对关键函数补读，未补全的部分列在末尾。

初始化要求与体系¶

文件	范围 / 作用
`AGENTS.md`	完整；ESM/Node/source launch、命名profile、Cordis effect生命周期、禁止默认全套测试
`docs/architecture.md`	完整；Host/Agent plane、会话事实、客户端投影、Desktop/Web、service/provider分离
`docs/AGENTS.md`	阅读相关文档维护段；本课程docs在上游外，用户要求详尽而非照抄README

14 SDK：过程所有权到运行结果¶

文件	已读函数 / 行段
`packages/sdk/client/src/index.ts`	1–30完整；公开导出 vs package-local seam
`packages/sdk/client/src/types.ts`	1–83完整；cwd、env、grace、RunResult
`packages/sdk/client/src/launch.ts`	1–157完整；resolveDshBinFromManifests、resolveDshNodeLaunch、resolveDshLaunch
`packages/sdk/client/src/api.ts`	1–310完整；start重试/cleanup、session惰性、HarnessSession.run、receipt判定、finalResponse、有限wire验证
`packages/sdk/client/src/client.ts`	1–491分段完整；NotificationSubscriptionImpl、spawn、stderr尾部、initialize/prompt/request、subscribeSessionTree、close
`packages/sdk/client/src/dispose.ts`	1–99完整；EOF→TERM→KILL→退出确认
`packages/sdk/protocol/src/types.ts`	1–119完整；三请求、四通知、inline image
`packages/sdk/protocol/src/transport.ts`	看过结构/方法搜索；未将完整279行parser/fuzz行为作为章节结论
`packages/sdk/server/src/server.ts`	1–299分段完整；durablePromptContent、初始化适配器fallback、全局通知、prompt准入、live身份、shutdown、getOrCreateSession/createSession
`packages/sdk/server/src/index.ts`	1–102完整；loader readiness、stdout协议、shutdown响应后的root/进程生命周期
`packages/sdk/client/tests/fake-runtime.ts`	替身实现与错误/通知/生命周期分支；实际stdin/stdout替身，而非mock run返回
`packages/sdk/client/tests/launch.spec.ts`	版本匹配、源码兼容、环境路径测试上下文
`packages/sdk/client/tests/sdk-client.spec.ts`	初始化部分及用例/辅助函数地图；未跑整个官方测试文件
`python/sdk/src/deepseek_harness/api.py`	1–248完整；配置、高层start/session、receipt/idle、final_response/finish_reason
`python/sdk/src/deepseek_harness/client.py`	1–185、request/read线程相关280–455、458–589；start、env合并、close、request timeout、lazy runtime import、通知树。没有把185–279遗漏方法宣称全读
`python/sdk/src/deepseek_harness/__init__.py`	1–19完整；import不eager载入runtime-bin
`python/sdk/src/deepseek_harness/models.py` / `errors.py`	public类型及import依赖核对；未声称逐个异常单测验证
`python/sdk/pyproject.toml`	包名、placeholder、Pydantic、runtime-bin、editable sources
`python/sdk/tests/test_client.py`	1–100和用例搜索；private _launch_args替身结构，不作为production接口

15 Web/Desktop/ACP、远端与资源¶

文件	已读函数 / 行段
`packages/host/webserver/src/index.ts`	完整；route register/精确和最长prefix、fallback、upgrade、gzip/dispose
`packages/client/connection/src/index.ts`	1–163完整；image capacity、配置、BrowserAuth、/api admission、request waterfall
`packages/client/connection/src/api-request-trust.ts`	完整；authority / Origin / sec-fetch-site围栏
`packages/client/connection/src/browser-auth.ts`	完整控制路径；launch token兑换、cookie、持久签名secret、authority/期限；没有宣称提供tenant auth
`packages/api/gateway/src/index.ts`	注册基础190–290、prepareInvocation 695–754、descriptor/receiver/lookup段756–925；1575行大型文件未全读
`packages/api/remotes/README.md`	remote facade/generated契约、explicit转发与订阅职责；只作为契约补充，不代替Gateway代码
`packages/api/session-controller/src/index.ts`	Remote方法432–490及定义搜索；prompt/follow/cancel/page；其余入口未全部逐行覆盖
`packages/api/session-controller/src/history.ts`	110–230；先订阅后baseline、缓冲、cursor/ordinal、coldsource
`packages/api/session-controller/src/assistant-stream.ts`	1–102完整；attempt/revision/index/reset、cached baseline
`packages/api/session-controller/src/control.ts`	1–121完整；host状态baseline/changed/cleanup
`packages/api/session-controller/src/agent.ts`	407–489；resume与createOrAdopt，cwd/preset/liveownership检查
`packages/api/session-controller/src/media-references.ts`	1–77完整；file Fetch路由/绝对路径/provider/大小/安全headers，认证操作员与filesystem access边界
`packages/attachment/attachment/src/admission.ts`	1–74完整；canonical base64、batch图准入
`packages/attachment/attachment-local/src/store.ts`	prepare99–123、commit/publication191–230、staging315–386、read接口搜索；并非完整所有450+行
`packages/attachment/attachment-local/src/file-store.ts`	保存/流读取91–180，path/hash/alias辅助搜索；原始文件字节内容寻址
`packages/deliverables/tool-present/src/index.ts`	1–109完整并复读；真实工具名present、max8/建议4、普通文件、pending WeakMap、成功result才日志；不复制内容
`apps/desktop/src/host-process.ts`	IPC事件/错误校验、138–230启动、288–322stop/failure；shell控件细节未全部逐行读
`apps/desktop/src/main.ts`	host/window方法地图、662–699自定义scheme/boot sender/forward；1338行大型入口未全读
`packages/acp/acp/src/index.ts`	1–413分段：permission、capabilities、new/resume/list/config/prompt/cancel、handler注册；其后quiesce辅助仅函数地图
`packages/acp/acp/src/session.ts`	334–524完整；onSessionEvent/onInboxClaimed/drainUpdates/close/cancel/settlement；prompt入口243–330相关搜索，未声称完整模型/MCP配置实现

16 Session持久化、业务数据、查询与UI store¶

文件	已读函数 / 行段
`packages/core/session/src/types.ts`	70–110版本/header、430–516surface/事件/ignorable；其余Session核心由A作者研究
`packages/session/session-persistence/src/handle.ts`	完整；access、inherited cut、append/flush/close/read契约
`packages/session/session-persistence-jsonl/src/lease.ts`	1–135完整；POSIX flock/inode验证、Windows semaphore、无TTL、release不删文件
`packages/session/session-persistence-jsonl/src/index.ts`	68–194配置和stored状态、310–332create、342–418open、1175–1238POSIX materialize、1320–1389append/rollback/repair；其他generation发现/编码/扫描仅相关调用搜索，未全读1725行
`packages/session/session-persistence-jsonl/src/storage.ts`	182–374完整append/flush/close/livebuffer/persistContiguous/chain；routing/flushAll503–557；read基础段查看，未声称所有tracker函数全读
`packages/session/session-persistence-jsonl/src/generation.ts`	817–999独占发布、EEXIST winner、source身份、prepare/publish；其前大量scanner/streamdecoder未完整覆盖
`packages/session/session-format/src/filename.ts`	1–32完整；canonical basename规则
`packages/session/session-format/src/chain.ts`	24–126；adjacent唯一完整链、future版本拒绝、createStream
`packages/session/session-format-v3-to-v4/src/codec.ts`	1–75完整；V4 native准入复用released framing
`packages/session/session-format-v3-to-v4/src/index.ts`	exports + migration version搜索；migration具体tool/source/relationship转换未全逐行覆盖，不提供全部旧格式细节承诺
`docs/session-format-status.md`	完整；发现latestReleasedVersion与发布tag writer冲突，不混用记录和事实
`packages/session/session-checkpoint-policy/src/index.ts`	完整；model adapter前、top-level tool前、pre-step前，嵌套重用；flush失败不dispatch
`packages/storage/storage-domain/src/spec.ts`	defineDomain/domainTable/descriptorOf86–163及类型声明；版本/global/null/name/layout
`packages/storage/storage-domain/src/index.ts`	DomainFacility.open85–173、closeAll176–194；逐记录schema与backup-and-skip条件
`packages/storage/storage-domain/src/domain.ts`	接口与168–357核心运行；writechain/backenddurable→memory→changed，update、close
`packages/storage/storage-sqlite/src/schema.ts`	1–119完整并复读；physicalschema1、mode/journal、stamp最后；不做升级
`packages/storage/storage-sqlite/src/index.ts`	80–168；unit保留、版本拒绝、table/close/backend注册
`packages/storage/storage-sqlite/src/unit.ts`	1–156完整；每primitive一statement、opaque JSON/坏JSON错误，无跨表事务
`packages/session-query/session-query-sqlite/src/schema.ts`	1–173完整；appid、外库拒绝、derived白名单/reset/schema8、persistent/temporary/FTS
`packages/session-query/session-query-sqlite/src/index.ts`	方法地图及407–493完整reconcile；来源revision/livefingerprint/事务/generation；observeStable/paginationcodec未完整覆盖
`packages/client/store/src/index.ts`	1–250完整；observable引擎、sync/raf、localStorage全值、错误非致命、scope key/clearPersisted

17 人工、自动化与experimental¶

文件	已读函数 / 行段
`packages/interaction/user-approval/src/index.ts`	1–310完整，215–310复读；open-turn/audit/policynever/waterfallnormalization/cancelrace
`packages/interaction/user-questions/src/index.ts`	1–342分段；assertLiveRoot、continued answer、reply ownership、askTimed/pending、ask/intent/NO_PROVIDER
`packages/plan/plan-mode/src/index.ts`	1–470分段；projection/accepted pre-step/systemsection/command/exit tool/set；277–365复读完整评审收敛
`packages/todo/tool-todo/src/index.ts`	1–207（结尾返回结构）；toTodoList69–119复读；list替换、parallel必填、projection turn reset
`packages/schedule/schedule/src/runtime.ts`	1–166完整；single timer/drive serialization/due decision/resume/followup/flush/taskcommit/drain
`packages/schedule/schedule/src/storage.ts`	schema/domain/task字段与receipt相关部分；记录version1，与Session格式分离
`packages/schedule/schedule/src/types.ts`	16–207完整公开record/delivery类型、后续错误类型diff；时区/DST/latest-only契约
`packages/schedule/schedule/src/domain.ts`	128–134occurrence、166–255标题/旧event准入，方法地图；复杂cron/DST实现未逐行穷尽
`packages/schedule/tool-schedule/src/index.ts`	1–70、198–254，schema/execute方法地图；ownercaller拒绝、internal error脱敏；完整四工具由后续交叉审查补充
`packages/webhook/webhook-github/src/handler.ts`	1–130完整；签名原body、boundedbody调用、delivery身份、202memorydispatch
`packages/webhook/webhook/src/index.ts`	1–178完整；register/snapshot/dispatch/callback/abortdrain；没有持久dedup
`packages/feedback/command-feedback/src/index.ts`	1–127完整；feedback/record、本地liveRemote、recordInputfalse
`packages/feedback/message-feedback/src/index.ts`	1–313分段完整；target/version/note、liveflushreadback、coldwritehandle、mutationqueue
`packages/credentials/credentials-local/src/index.ts`	优先级/Config1–130、provider528–611、modify/write666–786、refresh840–882及其前document解析相关阅读；909行未全部逐行覆盖
`packages/credentials/authorization/src/index.ts`	publicflow/interaction125–264、begin/attempt283–446；commit观测、独占attempt、取消/settledobserver
`packages/identity/anonymous-user-id/src/index.ts`	1–100完整并复读；homeUUID/memo/exclusivecreate/besteffort/race，不是auth
`packages/experimental/auto-review/src/index.ts`	snapshot/函数地图、562–740完整parser/classify/gate/disposal；modelprompt不进Session，deny/allow下游，卸载切dangerfull
`packages/experimental/api-speech-to-text/src/index.ts`	1–111完整；catalog/follow/configure/prepare/cancel/WAVbound/transcribe，绝不激活Agent/appendprompt
`packages/experimental/voice-input-bundle/cordis.patch.yml`	1–13完整；4模块组成、SenseVoice dataRoot

给父作者的离线验证路径¶

官方包内：TS fake-runtime是真正stdio子进程；源码api.ts的createProcessDeepSeekHarness未public export，用于测试源码client状态机。Python test_client.py用private _launch_args替身测试，无真实模型依赖。
课程实物：public npm rc.2 runtime + sdk-minimal +patch +本地HTTP Messages/SSE模型替身，能同时检验模型adapter、tool registry、自定义service、SDKreceipt/idle和关闭；比直接替换run更接近实际组合。
Python公共路径：复制rc.2 python/sdk/src/deepseek_harness五文件（__init__.py、api.py、client.py、models.py、errors.py），注明MIT/tag/commit，依赖Pydantic；显式dsh_bin执行npm .bin/dsh，lazy runtime import不会发生。不调用私有argv override。
runtime总预算与请求timeout分开。requesttimeout只清pending waiter；Root实验应测试admitted-step budget、未知工具无副作用、401正常error settlement、receiver/配置隔离、closedisklog，而不是见到idle就宣布所有事实耐久。
已将Root实际发现的idle时尚未materialize、close后才有V4日志写入14/16，避免receipt/notification注释中的“durable”用语被放大成fsync承诺。

自查与未验证范围¶

作者执行了四章所有固定GitHub链接的本地存在/行号边界扫描，纠正了初稿中的源文件长度、format-status目录、真正工具名present，补读相应函数。此项只证明引用目标真实，不是独立审查，也不证明每一句正确。随后需其他作者内容交叉审查及实验复核。

本作者没有调用付费模型，没有运行上游全套测试，没有启动真正ACP编辑器/Electron浏览器产品端到端，没有下载SenseVoice模型/访问麦克风。也没有执行POSIX断电/损坏fuzz、Windows nativeflock/semaphore/publish、全部历史V0→V4迁移、复杂cron跨时区/夏令时、OAuth网络/平台账户、Webhook真实GitHubdelivery、真正外部副作用exactlyonce测试。

未全部逐行覆盖的大文件包括JSONL主backend/scanner、Gateway所有transport/cancellation实现、Desktop main/update/native窗口、Python若干低层订阅辅助、schedule复杂cron/历史转换、所有附件/nativeimage decoder、credentials完整YAMLparser、auto-review完整snapshot来源过滤、语音nativeprovider。章节只对已追踪的路径作结论，其他功能通过链接提示扩展点，不把未验范围写成通过。

后续独立审查范围由父作者另行分配：A作者02/03/05/06/07/08/13及root examples全套自写源与测试。审查问题/FAIL/PASS将另写 research/reviews/reviewer-c-*.md，不会覆盖本作者研究记录，也不替其他审查员签字。