报告与文档

周报/月报由 bin/report.py 生成自动块，人工块保留；docs/ 为设计文档入口（离线渲染副本）。

周报

2026-W45 · 源文件

2026-W45 周报（2026-11-02 ~ 2026-11-08）

自动块由 bin/report.py 生成；自动块外是人工内容（本周判断 / 下周计划），重跑不会覆盖。

自动生成于 2026-11-05T16:42:39+08:00 ｜口径：data/manifests/*.jsonl 按 date 过滤；journal 按天；笔记按 frontmatter updated。

指标

指标	值
时间窗口	2026-11-02 ~ 2026-11-08
活跃天数	4
会话数	202（codex 174 / dsh 28）
tokens（Codex）	18,694,453
成本（DSH 上报）	¥0.00
新增笔记	29
更新笔记	29
新增产物	4（登记总数 15）
journal 覆盖	4 / 4 天

按天

日期	会话	codex	dsh	tokens
2026-11-02	2	2	0	30,687
2026-11-03	132	128	4	13,604,032
2026-11-04	54	44	10	5,059,734
2026-11-05	14	0	14	0

按领域

领域	更新笔记	新增产物
Agent 评测与实验	6	0
Agent Harness 架构与机制	6	3
本地基础设施与工具链	4	0
个人事务（敏感）	4	0
模型 API 与协议	4	1
知识管理与工作方法	5	0

本周新增/更新笔记

新增 kb/00-map/eval.md（growing）：Eval 领域导览：Agent 评测与实验
新增 kb/20-eval/benchmarks/benchmark-selection.md（growing）：AI Coding benchmark 选型：能力匹配与可复现前置
新增 kb/20-eval/deepswe/attribution-method.md（growing）：DSH 与 mini-swe-agent 归因方法论：先机制暴露，再单变量实验
新增 kb/20-eval/deepswe/scc-workflow-experiment.md（growing）：SCC 五步 workflow 对照实验：B1-B5 的信号与边界
新增 kb/20-eval/harbor/task-and-verifier.md（growing）：Harbor 的 Task 与 Verifier：评测单元定义权与信号质量
新增 kb/20-eval/harbor/trial-lifecycle.md（growing）：Harbor 的 Trial 生命周期：可复现性的真正边界
新增 kb/00-map/harness.md（growing）：Harness 领域导览：Agent Harness 架构与机制
新增 kb/10-harness/codex/thread-session.md（growing）：Codex 线程与会话：持久化记录不等于运行时对象
新增 kb/10-harness/dsh/context-compaction.md（growing）：DSH 上下文压缩：事务性压缩与缓存对齐摘要
新增 kb/10-harness/dsh/pi-ai-adapter.md（growing）：DSH 与 pi-ai 的边界：模型接入库不是 harness
新增 kb/10-harness/industry/harness-engineering.md（growing）：九个开源 harness 的工程投入与十一类主题
新增 kb/10-harness/shell/shell-execution.md（growing）：Coding harness 的 shell 执行：五组张力与收敛参数
新增 kb/00-map/infra.md（growing）：Infra 领域导览：本地基础设施与工具链
新增 kb/40-infra/cloud/aliyun-cdt-egress.md（growing）：阿里云 CDT 出流量归因与批量日志压缩回收
新增 kb/40-infra/dsh-setup/install-profile.md（growing）：DSH 本地安装与 profile：一个 provider-neutral 的 harness 形态
新增 kb/40-infra/gateway/litellm-observability.md（growing）：本地 LiteLLM 网关观测：从 token 记录到 Session-Turn-Step
新增 kb/00-map/personal.md（growing）：Personal 领域导览：个人事务（敏感）
新增 kb/90-personal/interview/p8-agent-interview.md（growing）：P8+ Agent 架构面试：可靠性主线与回答骨架
新增 kb/90-personal/investment/stx-valuation.md（growing）：STX 估值与 HDD 周期：有日期边界的情景分析
新增 kb/90-personal/investment/portfolio-risk.md（growing）：杠杆组合的风险诊断：集中度、覆盖率与执行边界
新增 kb/00-map/protocol.md（growing）：Protocol 领域导览：模型 API 与协议
新增 kb/30-protocol/gateway/translation-fidelity.md（growing）：协议网关的翻译保真度：哪些东西一定会丢
新增 kb/30-protocol/messages/thinking-and-tools.md（growing）：Anthropic Messages：强类型块、签名 thinking 与前缀不可变
新增 kb/30-protocol/responses/items-and-state.md（growing）：OpenAI Responses：Item 模型、状态与压缩
新增 kb/00-map/workflow.md（growing）：Workflow 领域导览：知识管理与工作方法
新增 kb/50-workflow/automation/heartbeat-skill.md（growing）：每周 Harness/RSI 综述的 heartbeat 与 skill 自动化
新增 kb/50-workflow/evidence/frozen-evaluation.md（evergreen）：冻结评测边界：不能随便改的环境与可审查的修复
新增 kb/50-workflow/evidence/evidence-grading.md（evergreen）：证据分级与结论措辞：E0-E3、S/D/T/H 与「证据不足」
新增 kb/50-workflow/reporting/multi-task-report.md（growing）：多任务评测报告的 Case/Run/Evidence 三层结构

本周新增产物

model-api-protocols-report（report，protocol）：模型 API 协议全景报告
harness-industry-report（report，harness）：Coding Harness 工程实践行业分析报告（2026-05 至 2026-11）
harness-context-handling-report（report，harness）：Coding Harness 上下文处理方案深度调研报告
shell-tools-report（report，harness）：Shell 工具横评：8 个主流 Agent Harness 的执行模型与安全设计

风险与异常

DSH 会话未上报 usage/cost（28 个），周报成本只含 Codex 侧 token 估算以外的 DSH 上报值。
本周涉及 3 篇 sensitivity: personal 笔记，发布页应带「个人」徽标。
单会话 tokens 最高 335,740（定时任务是否修改下检查时间？分析任务和修订任务是否能增加并行度？），注意上下文压缩/成本。

本周判断（人工）

下周计划（人工）

月报

2026-10-inventory · 源文件

2026-10 月度工作盘点（Codex + DSH，2026-10-06 ~ 2026-11-05）

盘点口径：全部只读源数据（~/.codex、~/.dsh、~/Documents/...），不虚构；数字由 analysis/collect_stats.py 生成到 analysis/inventory.json，复现命令与字段对照见 analysis/README.md，逐日/逐周事件见 analysis/timeline.md。 快照时间：2026-11-05T16:34:06+08:00（DSH 成本类数字是活文件快照，见 §5.2）。 一句话：这一个月的主线是「DeepSWE/Pier/IQuest 评测 + DSH×mini 归因实验」，82% 的 Codex token 花在 27 个人类发起的线程上，其中 10-22 与 11-01 两天占全月 token 的 72.9%；产出集中在 3 份 HTML 研究报告、 1 份协议选型报告、6 个实验系列与 36 个报告目录；未完成项主要是「实验结论的验收」和「成本口径」。

1. 问题

本盘点回答四个问题，而不是罗列日志：

Q1 做了什么、量级多大？ 一个月里 Codex / DSH 各有多少会话、多少 token、多少产物？哪些是人的工作，哪些是 agent 自转？
Q2 精力集中在哪里？ 6 个知识领域（harness / eval / protocol / infra / workflow / personal）各占多少？主线是什么？
Q3 成本与效率如何？ 花了多少钱、token 效率有没有异常？——这一问部分无法回答（Codex 侧无成本字段），必须标「证据不足」。
Q4 什么没做完、有什么风险？ 哪些结论只有「跑通」没有「验收」？下个月该补什么？

为什么值得盘点：这是第一次把分散在 Codex（304 threads / 419 MB 原始日志）与 DSH（55 个会话）里的一个月工作收敛成可复现、可下钻的量化盘点；它同时验证「用 agent 并行维护工作台」这条 workflow 是否成立。

2. 结论（先给答案）

结论 1（已验证）：这一个月是「评测归因月」，不是平均用力的月份。 范围内 256 个 Codex thread、 16.19 亿累计 token，其中 ChatGPT/swe 目录占 228 个 thread / 94.2% token；token 最高的 2 个线程（10-22 的 4.33 亿、11-01 的 4.15 亿）合计占全月 token 的 52.3%，10-22 与 11-01 两天合计占 72.9%。 分母：范围内 256 threads / 1,619,343,203 tokens。

结论 2（已验证）：会话数被自动化线程放大，真正的人类工作只有 27 个线程。 256 个 thread 中 guardian_review 143 个（55.9%）、子 agent 86 个（33.6%）、人类发起（vscode，含 1 个 ChatGPT handoff）27 个（10.5%）；但 token 分布相反：人类线程占 80.8%，子 agent 16.9%，guardian 仅 2.3%。「thread 数」不能当「工作量」用。

结论 3（部分已验证）：模型消耗集中在 gpt-6.1-sol 与 gpt-6.1-terra。 31 个 sol 线程消耗 8.507 亿 token（52.5%），74 个 terra 线程 6.774 亿（41.8%），其余 luna/auto-review/其他合计 5.9%。分母：范围内 256 threads。

结论 4（证据不足）：无法给出本月的准确资金成本。 Codex 的 threads 表只有 token 没有金额； DSH 成本快照在连续三次采集（16:32 / 16:34 / 16:36）从 3.31 → 4.88 → 5.18 CNY，因为 Workbench agent 在并行消耗—— 这个数只能当「快照」，不能当账。账户余额同期从 46.78 → 44.95 → 44.65 CNY 持续下降，最近 7 天有 4 天在消耗。

结论 5（已验证，产物层面）：产出是可数的，但「通过率」不可数。 可数产出：27 个显著文件、3 份 HTML 研究报告（harness industry / context handling / shell tools）、 1 份 Model API 协议报告（126,338 B）、swe/ 下 1 份 PDF + 1 份 HTML、48 个实验目录、36 个报告目录、 19 个 git 仓库、16 个记忆 task group。不可数：这些实验里有多少真正达到验收——本次没有解析实验 result 与 419 MB 原始 rollout 日志，因此本报告不给出任何通过率/得分结论。

结论 6（已验证）：DSH 从 10-24 开始进入日常使用，但使用重心是「替 Codex 做研究子任务」。 55 个 DSH 会话中 49 个有轮次，集中在 10-25（21 个，研究冲刺）与 11-03~11-05（28 个，harness 研究 + Workbench 搭建）； workdir 前三是 default-workspace（24）、harness_research（14）、swe（11）。

3. 证据

3.1 总量表（分母写清）

指标	全期（08-30 起）	本月窗口 10-06~11-05	占比
Codex threads	304	256	84.2%
Codex 累计 tokens	1,936,756,121	1,619,343,203	83.6%
Codex archived	13	4	—
DSH 会话（zstd 文件）	—	55（49 个有轮次/标题）	—
Codex 原始日志	—	294 个文件 / `du` 419 MB（203 `.jsonl` + 91 `.zst`）未逐条解析	—
codex `session_index`	—	215 行（索引，不是权威计数）	—

来源：inventory.json → codex.all_time / codex.in_range / dsh.sessions_total。

3.2 来源结构（分母 256）

来源（`source` 分类）	thread 数	占比	tokens	token 占比
guardian_review（自动审查）	143	55.9%	36,634,370	2.3%
subagent_spawn（子 agent）	86	33.6%	274,354,069	16.9%
vscode（人类发起，含 1 个 chatgpt_handoff）	27	10.5%	1,308,354,764	80.8%

按 thread_source 进一步拆人类线程：user 25 + chatgpt_handoff 1 + voice_chat 1 = 27，与 vscode 数一致（交叉验证通过）。来源：codex.by_source_class / by_thread_source。

3.3 时间分布：两个尖峰日 + 一个集中产出周

日期	threads	tokens	关键事件（证据见 timeline.md）
10-22	3	478,029,795（29.5%）	DeepSWE 评测 + 阿里云 E2B 沙箱（thread `01a16427…`，432.6 M tokens）
11-01	13	702,435,189（43.4%）	113-case Harness 审查（`01a19703…`，415.1 M）+ DSH/mini 交接（`01a19705…`，119.3 M）
11-03	92	86,971,818	线程数峰值：子 agent/guardian 批量实验
11-04	75	172,686,934	8 个 20261104 报告目录 + 2 份 harness 报告 HTML
10-06~10-10	0	0	无持久化记录（「未观察到」≠「确定没工作」）

按周（周一起）：10-05 周 2/3.94 M；10-12 周 14/73.93 M；10-19 周 39/568.26 M；10-26 周 27/706.98 M； 11-02 周（仅 4 天）174/266.24 M。来源：codex.by_day / by_week / weekly_activity。

3.4 模型与目录（分母 256）

model	threads	tokens	token 占比
gpt-6.1-sol	31	850,697,211	52.5%
gpt-6.1-terra	74	677,360,175	41.8%
gpt-6-luna	2	49,451,395	3.1%
codex-auto-review	143	36,634,370	2.3%
其他（astra / 5.6 / deepseek-flash 各 1，NULL 2）	6	5,200,052	0.3%

cwd 类别	threads	占比	tokens	占比
`Documents/ChatGPT/swe`	228	89.1%	1,524,690,564	94.2%
`Documents/Codex/<日期>/<线程>`	26	10.2%	87,657,532	5.4%
`agentcodes/*`（openai/codex 克隆）	2	0.8%	6,995,107	0.4%

3.5 DSH 侧（分母 55）

会话：55 个 zstd 文件（34 M）；49 个有轮次与标题；218 轮、732 条用户消息、8,874 条 assistant 消息、 9,837 次 tool/call。按天：10-24: 2、10-25: 21、10-29: 1、10-30: 3、11-03: 4、11-04: 10、11-05: 14。
工作目录：default-workspace 24 / harness_research 14 / swe 11 / ~/.dsh/im 3 / superagent 2 / 根 1。
模型：可识别会话中 deepseek-flash 26 个、iquest-q1 23 个（DSH 既当日常助手也用于 IQuest 评测）。
成本（快照，见 §5.2）：history 逐日合计 5.179593 CNY（10-30~11-05，其中 11-05 单日 2.47）； accounting debit 合计 6.585352 CNY（另一套账，覆盖 10-30 起且 11-04 双记，不可相加）；账户余额快照 44.65 CNY（lastBalance；盘点期间读数 46.78 → 44.95 → 44.65，随实时消耗下降）。

3.6 产物与仓库（可数产出）

工作区体积（du -sh）：default-workspace 1.6 G、harness_research 3.0 G（repos 3.0 G / 10 个 git 仓库）、 swe 1.3 G（repos 1.3 G / 6 个仓库）、llm-gateway 2.2 G、src/dsh-superagent 131 M、agentcodes/codex 771 M。 ChatGPT/swe 全量大小未测（约 306 GB 的任务提示值本次未验证，扫描超时）。
目录条目数：ChatGPT/swe/artifacts 114、experiments 48、reports 36。
显著文件 27 个（inventory.json → workspace.notable_files），代表：model-api-protocols-report.html（126,338 B，11-04）、 harness_industry_report.html（95,016 B，11-04）、harness_context_handling_report.html（75,608 B，11-04）、 shell_tools_report.html（57,890 B，11-05）、swe/deck/harbor-eval-framework.pdf（7.6 MB，10-25）、 swe/dsh-system-prompt-report.html（38,308 B，10-30）、swe/ROADMAP.md（33,757 B）、 model-api-protocol-research.md（82,510 B，10-25）。
代码仓库 19 个（inventory.json → repos，含 remote 与最近提交）：10 个在 harness_research/repos（codex、 dsh、opencode、pi、goose、gemini-cli、ZCode、Kiro、mcode、IQuestRT），6 个在 swe/repos（harbor、harbor-cookbook、 harbor-index、inspect_ai、pier、terminal-bench），另有 ChatGPT/swe、dsh-superagent、agentcodes/codex。最近提交集中在 2026-11-03~11-04（多为上游镜像拉取，不是本地开发提交）。
记忆层：MEMORY.md 106,687 B（wc -l 860 行）/ 16 个 Task Group；rollout_summaries/ 25 篇（任务提示写 26 篇，实测 25）。

3.7 6 个知识领域映射（分母 = 16 个 Task Group，粗归类，有判断成分）

domain	task group 数（/16）	对应主题（来自 `MEMORY.md` 标题）	一手产物
`eval`	4	DeepSWE/IQuest 归因、多任务评测报告、官方 artifact/trace、benchmark 下载与最小评测	`ChatGPT/swe/{experiments,reports}`、`swe/notes/*`
`harness`	3	编码 agent harness 策略对比、通用 harness 长程/验证设计、openai/codex 源码架构	3 份 harness HTML 报告、`swe/dsh-system-prompt-report.html`
`protocol`	1	本地 LiteLLM gateway、Codex prompt/token 可观测、transcript dashboard	`model-api-protocol-research.md` + 126 KB HTML
`infra`	3	Intel Mac 本地环境、macOS 文件搜索、Codex 额度/Google Pay	`llm-gateway/` 2.2 G
`workflow`	1	Agent Harness/RSI 综述自动化与 skill	`skills/agent-harness-rsi-review/`、周报自动化
`personal`	4	Pets 宠物插件、STX 估值、杠杆组合再平衡、P8+ 面试训练	投资报告（敏感，不入库明细）

口径说明：一个 task group 只归一个主领域（有重叠时按主题判断），所以是「16 个 group 的粗分布」，不是 token 级精确归因。按 cwd 的 token 分布（ChatGPT/swe 94.2%）提示 eval 是绝对主线，但 eval 目录里也混有 harness 研究，不能反推领域 token 占比。

4. 细节：这个月实际发生了什么

10-11~10-18：启动期。 Codex 源码架构分析、session vs thread 结构、支付与投资研究穿插； 18 日启动 Agent Harness/RSI 周度综述自动化。token 量小（周 3.9 M~73.9 M），是热身。
10-22~10-25：主线启动 + 研究冲刺。 10-22 一天烧掉 4.78 亿 token 做 DeepSWE 评测与阿里云 E2B 沙箱接入； 10-24 DSH 首次进入日常（2 个会话）；10-25 是 DSH 单日会话峰值（21 个），并行跑 gateway / harness / protocol 三条研究线（单会话最多 1,713 次工具调用），产出 Model API 协议调研与 v1 报告。周末（10-24/25）也在高强度工作。
10-26~11-01：归因实验体系化。 DSH 侧建 S0 埋点→S1 采样→S2 loop guard→S3 git checkpoint 四组实验与报告； Codex 侧 11-01 用 13 个线程、7.02 亿 token 完成 113-case Harness 推荐审查与 DSH/mini 完整交接 Prompt，并试图复现模型技术报告 64.6 分。这是本月 token 峰值日（占全月 43.4%）。
11-02~11-05：集中产出与工作台搭建。 11-03/11-04 共 167 个 thread（占全月 65.2%）跑批量实验与审查，生成 8 个 20261104 报告目录与 2 份 harness HTML 研究报告；11-05 转向「把一个月工作沉淀成 Workbench 仓库」—— workbench/ 于 16:26 建立，由 Lead + 5 个并行 agent（pipeline-builder / kb-architect / data-miner / industry-researcher 等）协作，本盘点即其中一环。

5. 未决 / 局限（按验证等级）

5.1 已验证（E2，可从 `inventory.json` 复现）

Codex thread 数、tokens、来源分类、模型/目录/日/周分布（读 sqlite 只读副本）。
DSH 会话数、轮次、工具调用、按天/目录分布（zstd -dc 流式解析）；成本快照的逐日明细。
文件大小/mtime、目录条目数、仓库 remote 与最近提交（stat / du / git log -1）。
人类线程 27 的交叉验证（vscode 27 = user 25 + handoff 1 + voice 1）。

5.2 证据不足（已尝试，不能下结论）

Codex 资金成本：无单价/账单/缓存折扣数据；只有 token，估算即虚构。
DSH 月成本：成本文件是活文件，三次采集（16:32/16:34/16:36）从 3.31 → 4.88 → 5.18 CNY，说明数字随并行 agent 实时变化；且 history / accounting 两套账覆盖日期不同、11-04 双记，只能分别报快照。10-30 之前的 DSH 会话无成本记录。
实验通过率 / 评测得分：本次没有解析 experiments/*/ 的 result、也没有逐条读 419 MB rollout 原始日志，所以本报告不含任何「通过率 / reward / 64.6 分复现结果」。113-case 审查的「真实浏览器验收」在记忆中记录为 blocked。
领域 token 归因：只能给 task group 粗分布（16 个）与 cwd 粗分布（256 个），没有逐线程领域标注，不能算领域 token 占比。
DSH profile 分布：~/.dsh/profiles/ 存在 headless / superagent / web 三个 profile，但 session 事件不记录会话级 profile （元数据只有 cwd），因此无法给出按 profile 的会话分布；仅能按 cwd 推断 ~/.dsh/state/superagent 下 2 个会话属 superagent，其余不可区分。
ChatGPT/swe 306 GB / artifacts 66 GB：任务提示值，本次 du 扫描超时未验证；仅确认 artifacts/experiments/reports 条目数为 114/48/36。
MEMORY.md 26 篇 vs 实测 25 篇、harness_research 11 repos vs 实测 10 个 git 仓库：提示数字与实测有小差异，以实测为准，差异原因未查（可能是不同时点快照）。

5.3 未观察到（不是「没有」）

10-06~10-10 没有 Codex/DSH 持久化记录——只能说明「没有产生记录的会话」，不能说明「没工作」。
没有观察到 token 效率的异常根因：单线程 4.33 亿 / 4.15 亿 token 很可能是长上下文反复重传，但这是假设，需要逐条 rollout 验证，本次未做。

5.4 风险

不可复现交付：如果只看「跑通/退出码 0」就下结论，无法区分「实验成功」与「只是跑完」；本盘点已拒绝把两者混为一谈。
成本失控：单日峰值 7 亿 token、Workbench 并行 agent 让成本快照快速上涨；Codex 侧完全无成本可见性。
指标失真：guardian review 占 55.9% 线程但只有 2.3% token；任何按 thread 数排的「活跃度」都会误导。
数据集中在单机：源数据只在 ~/.codex、~/.dsh、~/Documents/...，跨机器恢复尚未验证（configs/restore.sh 由 Lead 负责）。
敏感内容：personal 领域（投资/面试）产物含财务信息，只能留在 kb/90-personal/ 并标 sensitivity: personal，不进月报明细。

6. 下月建议（按投入产出排序）

补「实验验收」数据层：至少解析 experiments/*/ 的 result 文件，生成「实验数 / 完成数 / 验收通过数」三列，给分母；否则月报永远只能报产出、不能报结论。
统一成本口径：Codex 侧从 ~/.codex/usage 或网关账单导出行级成本；DSH 侧把 history 与 accounting 合并成唯一账本，并固定采集时点（例如每日 23:59 快照），避免活文件漂移。
治理超大单线程：复盘 10-22 / 11-01 两个 >4 亿 token 线程，确认是「必要长任务」还是「上下文重复重传」；若是后者，优先做上下文裁剪/分片，预期收益 > 任何模型切换。
月报自动化：把本目录的 collect_stats.py 挂进 bin/capture.sh 或 launchd，按月生成 inventory.json 草稿，人工只写「结论/未决」两节——减少现在的 25 分钟手工盘点。
继续 Workbench 沉淀：本月最后一天才开始建库，下月应验证「capture → journal → kb → site」闭环与跨机器恢复，并把 reports/monthly/ 的月报纳入 site/reports.html。

附录：交付物与复现

文件	内容
`analysis/collect_stats.py`	只读采集脚本（Codex sqlite + DSH zstd + 工作区 + 仓库 + 成本）
`analysis/inventory.json`	结构化盘点（本文所有数字的机器可读版本，含 `generated_at`）
`analysis/README.md`	数据源/口径/复现命令/数字来源表/局限
`analysis/timeline.md`	按周/按天时间线（含 thread id / session id / 文件路径证据）
`reports/monthly/2026-10-inventory.md`	本报告

cd /Users/lizhao/Documents/deepseek-harness/default-workspace/workbench
python3 analysis/collect_stats.py     # ~55s，重生成 inventory.json

设计文档

一页纸总览（给 30 秒后的自己 / 新机器 / 新 agent）

00-overview

打开源文件

全生命周期 SOP：捕获 → 脱敏 → 摘要 → 知识沉淀 → 发布 → 周报/月报 → 恢复

01-sop

打开源文件

Workbench 仓库架构与协作契约 (v1)

02-architecture

打开源文件

数据分级、脱敏与保留策略

03-data-policy

打开源文件

跨机器恢复手册（Codex + DSH）

04-restore

打开源文件

知识条目写作规范（Authoring）

05-authoring

打开源文件

公开部署（Cloudflare Pages 推荐）

05-public-publishing

打开源文件

回报闭环：周报 / 月报 / 指标与复盘

06-reporting

打开源文件

业界经验（浓缩版）：哪些做法值得抄，哪些不值得

07-industry-practices

打开源文件

路线图（v1 → v2）

08-roadmap

打开源文件

设计文档全文

一页纸总览（给 30 秒后的自己 / 新机器 / 新 agent）

这是什么

workbench 是一个私有 GitHub 仓库，用来长期保存、结构化、回顾和恢复我的 AI coding agent 工作。覆盖两条主线：Codex（会话、记忆、skills、桌面配置）与 DSH / DeepSeek Harness（会话、profile、插件、成本）。它不只是"备份"，而是把原始证据 → 摘要 → 知识 → 发布串成一条可复核的流水线。

解决什么

痛点	现状（2026-11-05 实测）	Workbench 的解法
数据散落	`~/.codex` 294 会话 419 MB；`~/.dsh` 51 会话 33 MB；`~/Documents/Codex` 7.8 GB；`~/Documents/ChatGPT` 306 GB	raw/manifest 脱敏入 git；大文件外部归档 + sha256 清单
换机即散	配置、记忆、skills、profile 都在本机	`configs/restore.sh` + 模板 + doctor 一条命令恢复
看过就忘	26 篇会话摘要 + 大量报告散落在不同目录	journal 日报 + 6 领域知识树 + 静态站点全局/下钻
无法回报	没有统一的周/月复盘	`report.py` 自动指标 + 周报/月报模板 + 复盘闭环
不可复核	结论与证据脱节	每篇笔记 `sources` 回指 session id / 文件 / URL；证据分级 E0-E3

五层与目录

raw 证据层：data/manifests/、data/samples/（脱敏、带 sha256）
silver 摘要层：journal/YYYY/MM/*.md（自动块 + 人工块）、analysis/
gold 知识层：kb/00-map/（6 领域 MOC）+ kb/10-harness 等 6 个领域目录 + artifacts/
publish 发布层：site/*.html（零依赖、file:// 可看、可 Pages）
restore 恢复层：configs/ + env/（模板、Brewfile、版本清单、检查表）

五个原则

证据优先：知识笔记必须能回到来源；E0 想法 / E1 读过 / E2 验证 / E3 可复现。
raw 只增不改：原始层 append-only，知识层可以改；两者用 hash/引用连接。
单一事实源：同一信息只写一处；kb/ 是知识唯一入口，site/ 是生成物。
agent 可维护：AGENTS.md 定义捕获/写作/汇报协议，日常由 agent 执行，人只做判断与复盘。
不过度工程：Markdown + 标准库 + 静态 HTML；不引入数据库、不引入构建框架、不把大文件塞进 git。

怎么读这个仓库

想快速看工作全貌：打开 site/index.html（或直接看 reports/monthly/）。
想找某个知识点：site/tree.html 搜索，或 grep -r "<关键词>" kb/。
想复用产出：artifacts/index.json 看清单，文件在 artifacts/。
想换机器：docs/04-restore.md。
想知道流程：docs/01-sop.md；想知道为什么这么设计：docs/02-architecture.md。

非目标（明确不做）

不做通用笔记软件/时间管理工具；不存密码、账户、私钥。
不把 66 GB 评测 artifacts、repo 克隆放进 git。
不追求"每天写长文"；自动采集为主，人只补充判断。

全生命周期 SOP：捕获 → 脱敏 → 摘要 → 知识沉淀 → 发布 → 周报/月报 → 恢复

适用范围：Workbench 仓库（workbench/）的日常运营。目标是把 2026-10 至 2026-11 的 Codex / DSH 工作持续沉淀为「可恢复、可浏览、可下钻到证据」的四层数据。所有命令都在仓库根目录执行；写作用域见 docs/02-architecture.md §2。

0. 前置条件

依赖	要求	检查命令
macOS	当前主力机	`sw_vers`
Python	3.9.6（仅标准库）	`python3 -V`
zstd	CLI 可用	`zstd --version`
node	24（生成器不依赖，仅前端工具）	`node -v`
git	已初始化仓库	`git status`

安全红线（任一命中立即停止提交）

不提交 ~/.codex/auth.json、~/.dsh/.credentials.yaml、cookie、私钥。
会话原文、manifest、kb、journal 中不得出现 sk-、ghp_、github_pat_、AKIA、 Bearer <token>、xox-、AIza*、PRIVATE KEY、Authorization: 头、邮箱、手机号。
不执行 git commit/push（由 Lead 统一提交）；不改源数据目录（~/.codex、~/.dsh、 ~/Documents/... 一律只读）。

1. 总流程

一条命令走完「增量采集 → 周报 → 重建站点 → 体检」：

bash bin/capture.sh                 # 默认近 30 天；不自动 git commit/push
bash bin/capture.sh --since 2026-10-06
bash bin/capture.sh --skip-export   # 只重建站点 + 体检

Codex/DSH 会话 ──export──▶ data/manifests + journal/YYYY/MM/
     │                              │
     │                              └──scrub──▶ 脱敏自查（grep/CI gitleaks）
     │
     ├──artifacts 选品──▶ artifacts/{reports,decks,docs} + index.json
     └──人工策展──▶ kb/**/*.md（frontmatter + 证据）
                              │
                              ▼
                    python3 bin/build_kb.py --out site
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
              site/*.html         reports/weekly|monthly
                              │
                              ▼
                    复盘 / 调整 / 恢复演练

2. 阶段 1：捕获（Capture）

# 全量增量导出：会话 -> data/manifests、journal；默认按窗口筛选
python3 bin/export_sessions.py --source all --since 2026-10-06 --out data --journal journal

# 只含 Codex / 只含 DSH
python3 bin/export_sessions.py --source codex --since 2026-10-06 --out data --journal journal
python3 bin/export_sessions.py --source dsh   --since 2026-10-06 --out data --journal journal

# 需要保留脱敏后的原始会话采样（体积敏感，默认关闭）
python3 bin/export_sessions.py --source all --out data --journal journal --include-raw --limit 10

验收（不是「跑完了」）

data/manifests/summary.json 的 totals.sessions 非零，且与 codex.jsonl/dsh.jsonl 行数一致。
journal/ 至少覆盖目标窗口内的每一天；抽查 1 天 auto 块内的时间/来源/标题/目录/轮次/成本/会话 id。
每条 manifest 都有 stored_sha256，抽样用 shasum -a 256 对得上。
被跳过的会话（归档/无 cwd/损坏）在日志中有原因，不是静默丢弃。

失败处理

症状	原因	动作	禁止
`summary.json` 缺失/sessions=0	源目录路径变了或权限不足	用 `--help` 确认参数；检查 `~/.codex/sessions`、`~/.dsh/sessions` 是否存在	不要把空结果当「最近没有会话」
导出行数与源目录文件数差异大	时间窗口/归档过滤	打印过滤条件与排除计数	不要手工改 jsonl 凑数
`stored_sha256` 与源文件不一致	导出中断/并发写	重跑该来源并保留旧文件供比对	不要覆盖唯一副本

3. 阶段 2：脱敏（Scrub）

脱敏由 bin/scrub.py 在导出时执行；提交前必须再做一次自查：

# 1) 已知密钥前缀
grep -rInE 'sk-[A-Za-z0-9]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_|AKIA[0-9A-Z]{16}|xox[abprs]-' data/ journal/ kb/ artifacts/ 2>/dev/null || echo "no key prefix"

# 2) 认证头与私钥
grep -rInE 'Authorization:|Bearer [A-Za-z0-9._-]{20,}|BEGIN .*PRIVATE KEY' data/ journal/ kb/ artifacts/ 2>/dev/null || echo "no auth header"

# 3) 邮箱/手机号（按需，注意排除示例占位符）
grep -rInE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|\b1[3-9][0-9]{9}\b' data/ journal/ 2>/dev/null | head -20

验收：以上命令除占位符/示例外无输出；CI 的 gitleaks 通过；data/samples/ 抽样人工看 2 个文件。

失败处理

命中真实密钥：先轮换该密钥（视为已泄露），再从本仓库历史中移除（由 Lead 处理），不要只做字符串替换后继续提交。
命中邮箱/手机号：确认是否已 [REDACTED:...]；若是业务示例，加 example 标记并记录在案。
scrub.py 报错：保留原始文件、不要绕过；记录未覆盖的 pattern 到 docs/03-data-policy.md 的待办。

4. 阶段 3：摘要（Journal）

导出会自动写 journal/YYYY/MM/YYYY-MM-DD.md 的 auto 块；人工只改块外内容。

# 重跑当天生成器（只更新 auto 块）
python3 bin/export_sessions.py --source all --since 2026-11-05 --until 2026-11-05 --out data --journal journal

# 自查：auto 标记成对、块外内容没被覆盖
grep -c 'auto:begin\|auto:end' journal/2026/11/2026-11-05.md

每条人工摘要的最小内容

今日要点（1–3 句，先问题后结论）。
决策（含理由与替代方案）。
未决/风险（谁负责、下一步）。
证据指针（session id / 文件路径 / 产物 id）。

验收：连续 ≥10 天有 journal；重跑生成器后人工内容逐字保留；auto 块内表格列完整。

5. 阶段 4：知识沉淀（KB）

新建一条 note 的判定：有一个明确问题、可回指证据、结论能脱离原会话被理解。否则先放 journal。

# 1) 选领域、建主题子目录（parent 用子目录名，如 dsh、codex、harbor）
mkdir -p kb/10-harness/dsh
# 2) 从模板复制并填 frontmatter
cp kb/_templates/note.md kb/10-harness/dsh/my-topic.md
# 3) 更新对应 MOC 的子主题入口表（kb/00-map/<domain>.md）
# 4) 校验 frontmatter 与链接（--check 会重建并校验；只想校验已有站点用 --no-build）
python3 bin/build_kb.py --out site --check
python3 bin/build_kb.py --no-build --check   # 不重建，仅校验 site/

frontmatter 硬规则：严格按 docs/02-architecture.md §3.2；字符串含 :/#/[ 加双引号；列表只用行内 [a, b] 或 sources 的多行 - ；title/domain/status/confidence/summary 必填。 正文结构：问题 → 结论 → 证据 → 细节/机制 → 未决问题与边界。

验收：每领域 1 篇 map + ≥3 篇 note；parser 全通过；相对链接 0 断链；sources 中 path: 指向的文件存在、artifact: id 在 artifacts/index.json 中存在。

失败处理：frontmatter 解析失败 → 按 parser 子集改（不要引入 YAML 块标量/嵌套字典）；断链 → 先改相对路径，不要用 # 占位掩盖。

6. 阶段 5：产物库（Artifacts）

# 1) 单文件 ≤10 MB，总量 ≤30 MB；复制到对应类型目录
cp /path/to/report.html artifacts/reports/
# 2) 写 index.json（格式见 §6 契约）；字段：id/title/type/domain/date/file/source_path/bytes/tags/summary
# 3) 校验 JSON 与文件一致
python3 - <<'PY'
import json, os
d=json.load(open('artifacts/index.json'))
for a in d['artifacts']:
    assert os.path.isfile(a['file']), a['file']
print('ok', len(d['artifacts']), 'total MB', round(sum(a['bytes'] for a in d['artifacts'])/2**20, 3))
PY

验收：10–15 个产物；每个有 domain 与 source_path；file 存在于仓库；单文件 ≤10 MB、总量 ≤30 MB；超过 10 MB 的只登记 source_path + sha256，不复制。

7. 阶段 6：发布（Site）

python3 bin/build_kb.py --no-build --check   # 只校验已有站点：页面/断链/内联 JSON
python3 bin/build_kb.py --out site --check   # 重建五个页面并校验（= make build + check）
make build && make check                     # 等价的 Makefile 入口

验收清单

[ ] site/index.html、tree.html、timeline.html、artifacts.html、reports.html 均生成且非空。
[ ] file:// 双击可打开，无外部请求（断网可看）；无 CDN/字体/图片外链。
[ ] 树能从领域下钻到 note 再到 sources；#<note-id> 路由可回链。
[ ] 断链 0；artifacts.html 卡片能跳到 artifacts/ 本地文件。
[ ] 明暗两套与打印样式可用；移动端不横向溢出。
[ ] 构建失败时不留下半成品（先写临时目录再替换）。

失败处理：构建报错 → 先跑 --check 定位是 frontmatter、断链还是产物索引；不要用 rm -rf site 后手工补页面；生成器修复前保留上一次的完整产物。

8. 阶段 7：周报 / 月报

python3 bin/report.py --period week  --date 2026-11-05 --out reports
python3 bin/report.py --period month --date 2026-11-05 --out reports

生成器负责从 journal/ 与 data/manifests/ 拉取计数与清单；人工补「问题→结论→证据→局限」。模板、指标定义与复盘规则见 docs/06-reporting.md。

验收：每个数字都有来源（文件/命令），分母与排除项写清；无「启动成功=完成」的表述；周报覆盖最近 7 天、月报覆盖自然月；与上一期有对比。

9. 阶段 8：恢复（Restore）

git clone <repo> workbench && cd workbench
bash configs/restore.sh codex --dry-run
bash configs/restore.sh dsh   --dry-run
bash configs/restore.sh all           # 正式执行（会写入本机配置）
make doctor                           # 环境自检

恢复验收（四层分开）

会话：能列出并打开历史会话（codex 侧边栏 / dsh session 列表）。
工作区：目标 cwd 与关键文件存在，git 状态符合预期。
运行环境：安装/升级路径、profile、网络与权限配置可用。
外部副作用：对未确认的动作使用查询/对账，状态不明写 UNKNOWN，不盲重试。

失败处理：restore.sh 干跑失败 → 先补依赖（brew/uv/node），不要跳过 dry-run；恢复后「启动成功」不等于恢复完成，按上面四层逐项记录证据。

10. 周期 Checklist

每日（下班前 10 分钟）

[ ] 当天 journal 已生成，人工块写了要点/决策/未决。
[ ] 新增/修改的 note frontmatter 可解析，链接可达。
[ ] 没有把密钥/账号/个人财务明文写进 kb。
[ ] 需要 Lead 提交的文件已在 git status 中列出（不自行 commit）。

每周（周一 15 分钟）

[ ] make report 生成周报；对比上周的会话数/note 数/产物数。
[ ] 检查本周新增 note 是否都挂到 MOC；孤立 note 合并或归档。
[ ] 跑一次 make check（构建 + 校验 + doctor）与脱敏 grep。
[ ] 更新 docs/08-roadmap.md 的进度（由 Lead）。
[ ] heartbeat/定时任务状态确认（ACTIVE/PAUSED、上次运行时间）。

每月（月末 30 分钟）

[ ] 生成月报（问题→结论→证据→局限），列出下月三个优先问题。
[ ] 复盘：哪些结论被新证据推翻？哪些 note 该升 evergreen / 该 archive？
[ ] 产物库体积与断链审计；清理重复产物。
[ ] 恢复演练一次（dry-run 至少）；记录阻塞项。
[ ] 敏感信息与访问权限审计。

11. 失败处理总表

症状	最可能原因	动作	禁止
构建/导出中途失败	输入不合契约	保留现场，跑 `--check` 定位	删旧产物掩盖
数据与源目录不一致	窗口/过滤/并发	记录过滤参数与排除数	手工改 jsonl
报告数字与上期差异大	口径变化	核对分母/窗口/来源版本	直接解释为「工作变多」
出现密钥	scrub 规则缺口	轮换 + 删样本 + 补规则	只替换字符串
恢复后行为异常	版本/凭据/网络	按四层验收，未知标 `UNKNOWN`	反复重试直到「看起来好了」
断链	移动/重命名 note	改相对链接或加别名	用绝对 `file://` 链接

12. 完成定义（Definition of Done）

不是「脚本退出码 0」「服务启动成功」「测试通过」。而是：

数据有清单与哈希；2. 摘要可读且人工块保留；3. 知识条目的结论有证据与边界；
产物索引与文件一致；5. 发布页离线可看、断链 0；6. 周报/月报数字可回查；
恢复路径经过 dry-run 并有记录；8. 无密钥、无越界写入、无未披露的冻结评测变更。

Workbench 仓库架构与协作契约 (v1)

本文件是 Workbench 仓库的唯一架构契约。所有参与者（Lead / teammates / 未来的 agent 与人类）都按本文件的目录、数据格式、CLI 和写作规范工作。修改契约必须先改本文件并在 PR 中说明。 仓库根目录：/Users/lizhao/Documents/deepseek-harness/default-workspace/workbench

0. 目标

把 2026-10 至 2026-11 一个月内的 Codex / DSH 工作（会话、记忆、产物、代码、报告）沉淀为一个 可持久化、可跨机器恢复、可全局浏览也可下钻到证据的 GitHub 仓库：

原始数据层（raw/lake）：会话、配置、记忆、清单进入 git（脱敏后），跨机器可恢复。
摘要层（journal/silver）：按日/按会话的规范化摘要，人可读、可 diff、可检索。
知识层（kb/gold）：按知识点组织的树状体系（领域 → 主题 → 原子笔记），带证据分级。
发布层（site）：零依赖静态 HTML（file:// 双击可看、可 GitHub Pages），全局仪表盘 + 树状下钻。
恢复层（configs/env）：另一台机器上 git clone + 一条命令恢复 Codex / DSH 两个环境。

1. 四层架构（对标数据湖 medallion + C4 的全局/细节分层）

原始证据 (raw)           规范化摘要 (silver)        知识体系 (gold)          发布 (site)
data/manifests/*.jsonl → journal/YYYY/MM/*.md  →   kb/**/*.md          →   site/*.html
data/samples/**            analysis/                artifacts/index.json
     ↑ 不可变、带 sha256        ↑ 自动生成为主          ↑ 人工策展、带 frontmatter   ↑ 由 build_kb.py 生成
     └────────── 证据链：每条知识结论可回指 session id / 文件路径 / URL ──────────┘

全局（site/index.html）：统计、领域地图、时间热力图、最近活动。
下钻（site/tree.html）：领域 → 主题 → 原子笔记 → 证据来源，四级可点。
业界对标：C4 model（L1 全局 / L2 容器 / L3 组件 / L4 代码）用于知识树； Diátaxis（教程/操作/reference/解释）用于笔记类型；PARA / Zettelkasten / MOC 用于组织； medallion（bronze/silver/gold）用于数据分层；BagIt / PROV 用于证据与清单。

2. 目录与职责（写作用域）

workbench/
├── README.md                     # Lead（总览 + 快速开始 + 三层入口）
├── AGENTS.md                     # Lead（给 Codex/DSH agent 的维护协议）
├── Makefile                      # Lead（统一入口，见 §7）
├── .gitignore / .gitattributes   # Lead
├── .github/workflows/ci.yml      # Lead（secret scan + 构建 + 链接检查）
├── docs/                         # 设计与 SOP
│   ├── 00-overview.md            # Lead：一页纸总览
│   ├── 01-sop.md                 # kb-architect：全生命周期 SOP（捕获→摘要→知识→发布→复盘）
│   ├── 02-architecture.md        # Lead：本契约
│   ├── 03-data-policy.md         # Lead：数据分级/脱敏/保留/LFS/外部大文件
│   ├── 04-restore.md             # Lead：跨机器恢复手册（Codex/DSH 两条线）
│   ├── 05-authoring.md           # kb-architect：知识条目写作规范
│   ├── 06-reporting.md           # kb-architect：周报/月报/回报闭环
│   ├── 07-industry-practices.md  # industry-researcher：业界经验（浓缩版）
│   └── 08-roadmap.md             # Lead：阶段路线图
├── bin/                          # pipeline-builder：所有可执行脚本（Python3.9 标准库，零第三方依赖）
├── data/                         # pipeline-builder：原始数据层（见 §4）
├── journal/                      # pipeline-builder：按日摘要层（自动生成 + 人工补充）
├── analysis/                     # data-miner：一个月的量化盘点（inventory / timeline）
├── kb/                           # kb-architect：知识层（见 §3）
├── artifacts/                    # kb-architect：精选产物的本地快照 + index.json
├── reports/                      # data-miner（monthly/）+ pipeline-builder（weekly/ 自动）
├── research/                     # industry-researcher：业界调研原始笔记 + 引用
├── configs/                      # Lead：跨机器恢复模板（codex/dsh/restore.sh）
├── env/                          # Lead：Brewfile / 版本清单 / 恢复检查表
├── automation/                   # pipeline-builder：launchd 定时 capture
└── site/                         # pipeline-builder：生成的 HTML（提交进 git，支持离线与 Pages）

纪律：任何成员只写自己作用域内的文件；不 git commit/push（由 Lead 统一提交）；不改源数据目录（~/.codex、~/.dsh、~/Documents/... 一律只读）；不删除他人文件。

3. 知识层契约（kb/）

3.1 领域（固定 6 个，`kb/index.json` 注册）

domain id	目录	中文名	说明
`harness`	`kb/10-harness/`	Agent Harness 架构与机制	DSH/Codex/Claude Code/OpenCode/Pi 等 harness 的上下文、工具、循环、安全、恢复机制
`eval`	`kb/20-eval/`	Agent 评测与实验	DeepSWE/Pier/Harbor/Inspect、mini-swe-agent、IQuest、归因实验、成本与验收
`protocol`	`kb/30-protocol/`	模型 API 与协议	OpenAI Responses/Chat、Anthropic Messages、Gemini Interactions、网关/LiteLLM/流式
`infra`	`kb/40-infra/`	本地基础设施与工具链	llm-gateway、观测、装机、版本管理、cost tracking、DSH 安装/升级
`workflow`	`kb/50-workflow/`	知识管理与工作方法	本仓库自身、capture/report 流程、agent skills、写作与复盘方法
`personal`	`kb/90-personal/`	个人事务（敏感）	投资研究、工具选型、面试准备等；frontmatter 必须标 `sensitivity: personal`

3.2 笔记 frontmatter（YAML 子集，parser 只支持下面这些形态）

---
title: "DSH 上下文压缩触发条件"
domain: harness
parent: dsh
tags: [dsh, context, compaction]
status: growing            # seed | growing | evergreen | archive
confidence: E1             # E0 想法 | E1 读过来源 | E2 实际验证 | E3 可复现实验
type: note                 # note | map | report
summary: "一句话结论，出现在树和搜索结果中"
created: 2026-10-24
updated: 2026-11-05
sources: [session:codex:01a16427-93c4-7a53-85be-07310e73f148, path:/Users/lizhao/Documents/deepseek-harness/swe/notes/03-trial-spine.md]
---

规则：字符串值含 :/#/[ 时用双引号；列表只用行内 [a, b] 或 sources 的多行 - 形式（parser 两种都支持）。title、domain、status、confidence、summary 必填。

正文结构（推荐，符合用户"先问题后结论再证据"的偏好）：

## 问题
## 结论
## 证据
## 细节 / 机制
## 未决问题与边界

3.3 树结构 = 目录结构 + `parent` 字段

kb/10-harness/dsh/context.md 的 parent: dsh 表示挂在 10-harness/dsh 主题下；主题由目录体现，领域由一级目录体现。MOC（kb/00-map/<domain>.md）是每个领域的顶层导览，type: map。最少要求：每个领域 ≥3 篇 note，每个领域 1 篇 map。不允许空领域页。

3.4 证据来源写法（`sources`）

Codex 会话：session:codex:<thread_id>
DSH 会话：session:dsh:<session_id>
本地文件：path:<绝对路径>（允许保留 /Users/lizhao/...，脱敏规则不处理路径）
链接：url:https://...（只写真实存在、可访问的 URL）
精选产物：artifact:<artifacts/index.json 中的 id>
实验/报告：report:<reports/ 下相对路径>

4. 数据层契约（data/ 与 journal/）

4.1 原始数据分级（详见 docs/03-data-policy.md）

级别	例子	是否进 git	方式
L1 小文本	会话规范摘要、manifest、配置模板、kb、journal	✅ 全量	直接提交
L2 中文本	脱敏后的原始会话（压缩）、精选产物（HTML/PDF/MD）	✅ 采样 + 按需	`data/samples/` 提交；全量用 `--include-raw`，git-lfs 管理
L3 大文件	`~/Documents/ChatGPT/swe/artifacts`（约 66 GB）、repo 克隆	❌ 不进 git	外部存档 + sha256 清单 + `external://` 引用

4.2 文件格式

data/manifests/summary.json：{generated_at, since, until, format_version, totals:{sessions, codex, dsh, bytes}, sources:{...}}
data/manifests/checksums.sha256：data/ 下所有文件的 sha256 清单 + 相对路径（BagIt RFC 8493 轻量整包校验； python3 bin/doctor.py 会逐行校验，证明数据包"没被悄悄改过"）。
data/manifests/codex.jsonl：每行一个会话。字段： `id, app, date, created_at, updated_at, cwd, title, model, provider, source, archived, tokens, original_path, original_bytes, stored_path, stored_sha256, stored_bytes, redactions`
data/manifests/dsh.jsonl：`id, app, date, created_at, cwd, title, model, turns, steps, tool_calls, cost_cny, original_path, original_bytes, stored_path, stored_sha256, stored_bytes, redactions`
data/samples/：每种来源 ≥2 个脱敏样本（*.jsonl.gz 或 .md），用于演示与 schema 校验。
journal/YYYY/MM/YYYY-MM-DD.md：自动块  ...  内是当天会话表格（时间/来源/标题/目录/轮次/成本/会话 id），块外保留人工"今日要点/决策/未决"。 重跑生成器只更新 auto 块，不覆盖人工内容。

4.3 脱敏（硬性要求）

bin/scrub.py 至少覆盖：sk-、gho_/ghp_/github_pat_、AKIA、Bearer <token>、 xox-、AIza、-----BEGIN .* PRIVATE KEY-----、api_key/secret/token/password 赋值、 Authorization: 头、邮箱与手机号（替换为 [REDACTED:<type>]）。提交前必须 grep 自查， CI 用 gitleaks 兜底。绝对禁止提交：~/.codex/auth.json、~/.dsh/.credentials.yaml、cookie、私钥。

5. 发布层契约（site/）

python3 bin/build_kb.py --out site 生成，要求：

零外部依赖、零 CDN、file:// 直接打开可用（数据内联进 HTML/JS，不 fetch）。
页面：index.html（全局仪表盘：统计卡、领域卡、60 天热力图、最近会话/笔记）、 tree.html（左树 + 中列表 + 右详情，hash 路由 #<note-id>，搜索框过滤标题/标签/摘要）、 timeline.html（热力图 + 按天/周事件流）、artifacts.html（产物卡片，可跳 artifacts/ 本地文件）、 reports.html（渲染 reports/weekly、reports/monthly 的 Markdown）。
视觉：中文优先系统字体栈、CSS 变量、明暗两套（跟随 prefers-color-scheme，可手动切换）、 domain 配色徽章、status/confidence 徽章、打印样式、移动端可用。
生成物提交进 git（site/），保证离线可看；构建失败时不得留下半成品（先写临时目录再替换）。
Markdown 渲染器需支持本仓库用到的子集：标题、段落、粗斜体、行内代码、围栏代码块、有序/无序列表、引用、链接、表格、分隔线、HTML 透传。

5.1 公开站（GitHub Pages）

python3 bin/build_kb.py --out site-public --public（或 make public）生成公开脱敏版，与私有 site/ 互不干扰。差异：排除 personal 领域与 sensitivity: personal/confidential/private 笔记；脱敏 /Users/<name> 路径为 ~；docs/reports 丢弃引用个人内容的行；不复制 artifacts 原始文件；构建后自动跑 check_public() 校验无泄漏。详见 docs/05-public-publishing.md。GitHub Pages 站点对知道 URL 的人公开可读（与仓库私有性无关），故公开内容必须经此脱敏流程。

6. 产物层契约（artifacts/）

artifacts/index.json：

{"version": 1, "artifacts": [
  {"id":"model-api-protocols-report","title":"模型 API 协议全景报告","type":"report",
   "domain":"protocol","date":"2026-10-25","file":"artifacts/reports/model-api-protocols.html",
   "source_path":"/Users/lizhao/Documents/deepseek-harness/default-workspace/model-api-protocols-report.html",
   "bytes":126338,"tags":["protocol","responses","messages"],"summary":"..."}
]}

产物复制到 artifacts/<type>/，单文件 ≤10 MB，总量 ≤30 MB；超过的只登记路径与 sha256，不复制。发布时 build_kb.py 把 artifacts/ 复制到 site/artifacts/ 并生成卡片页。

7. CLI 契约（Makefile 调用的固定接口）

python3 bin/export_sessions.py --source all --since 2026-10-06 --out data --journal journal [--include-raw] [--limit N]
python3 bin/build_kb.py --out site [--check]
python3 bin/report.py --period week --date 2026-11-05 --out reports
python3 bin/doctor.py [--json]
bash   configs/restore.sh codex|dsh|all [--dry-run]
bash   bin/capture.sh            # 增量 export + build + 提示 git 提交（不自动 push）

Makefile 目标（Lead 维护，pipeline-builder 实现被调脚本）：

export:    python3 bin/export_sessions.py --source all --out data --journal journal
build:     python3 bin/build_kb.py --out site
report:    python3 bin/report.py --period week --date $(date +%F) --out reports
doctor:    python3 bin/doctor.py
capture:   bash bin/capture.sh
restore-codex: bash configs/restore.sh codex
restore-dsh:   bash configs/restore.sh dsh
check:     python3 bin/build_kb.py --check && python3 bin/doctor.py

运行环境：macOS + Python 3.9.6（无 yaml/markdown/jinja2，只用标准库）+ zstd CLI； node 24 可用但生成器不依赖 node。脚本要 --help，失败要有清晰中文报错。

8. 验收标准（Lead 合并前逐条检查）

[ ] make export 生成非空 manifests + 至少 10 天 journal；脱敏抽查通过。
[ ] make build 生成 site 五个页面，HTML 结构合法，file:// 可打开，无外部请求。
[ ] make doctor 全绿；docs/04-restore.md 的恢复命令可 dry-run。
[ ] kb 6 个领域都有 MOC 且 ≥3 篇 note；frontmatter 全部可解析；无断链。
[ ] artifacts/index.json 与 artifacts/ 文件一致；每个产物有 domain 与 source_path。
[ ] docs 01/03/04/05/06/07 齐备；README 一分钟能看懂怎么用。
[ ] 仓库 git status 干净（Lead 提交）；无密钥（gitleaks/自查）；.gitignore 覆盖 auth/credentials。
[ ] analysis/ 有可复现的盘点脚本/命令与数字来源说明；月报有"问题→结论→证据→局限"。

9. 内容规范（所有中文产出）

用户偏好：先解释问题，再给结论；区分"已验证/证据不足/未观察到"；给分母与排除项；不把"启动成功/退出码 0/测试通过"当作验收；引用要能回到一手来源。
隐私：kb/90-personal/ 与含财务/账户信息的产物标 sensitivity: personal，发布页显示"个人"徽标；真实账户数字、持仓明细、密钥、邮箱一律不入库。
语言：知识条目、文档、报告用中文（专有名词保留英文）；代码注释英文即可。

数据分级、脱敏与保留策略

核心判断：git 适合小文本，不适合 306 GB 的评测现场。 原始数据要"进 git"的其实是清单 + 脱敏文本 + 样本；大文件用外部归档 + hash 引用。

1. 现状盘点（2026-11-05，实测）

数据源	路径	体积	形态
Codex 会话	`~/.codex/sessions`（294 个 rollout）	419 MB（未压缩 JSONL）	文本，可压缩/脱敏
Codex 归档会话	`~/.codex/archived_sessions`	3.2 MB	文本
Codex 记忆	`~/.codex/memories`（本地 git 仓库，无 remote）	~2 MB	Markdown
DSH 会话	`~/.dsh/sessions`（51 个）	33 MB（已 zstd）	JSONL + 压缩
DSH 用量	`~/.dsh/.dshw-usage.json`	13 KB	JSON
Codex 工作区	`~/Documents/Codex`	7.8 GB	混合（会话工作目录、产物）
SWE 评测工作区	`~/Documents/ChatGPT/swe`	306 GB（artifacts 66 GB）	混合，大量二进制
DSH 研究区	`~/Documents/deepseek-harness`	5.9 GB	报告 + 11 个 repo 克隆
本仓库（预计）	`workbench/`	目标 < 30 MB	Markdown/JSON/HTML

2. 分级（L1/L2/L3）

级别	定义	例子	策略
L1 小文本	人写的/结构化的、可 diff 的文本	manifests、journal、kb、docs、reports、配置模板、artifacts 索引	✅ 全量提交 git
L2 中文本	脱敏后的会话原文、精选产物	规范化会话 JSONL/样本、HTML/MD 报告、PDF deck	✅ 采样提交；全量用 `--include-raw` + Git LFS
L3 大文件/环境现场	评测 artifacts、repo 克隆、模型缓存、二进制	`swe/artifacts`（66 GB）、`repos/`、`node_modules`、`.python/`	❌ 不进 git：外部归档 + sha256 清单 + `external://` 引用

L2 全量启用的条件（不是默认）：单次提交增量 < 20 MB、仓库总量 < 500 MB、已 git lfs install。否则只保留"清单 + 样本"，原文按需从本机/外部归档恢复。

3. L3 大文件怎么办（66 GB 的现实方案）

登记：data/manifests/artifacts-external.jsonl 记录 path, bytes, sha256, mtime, category, note（由 export_sessions.py 扫描关键目录生成）。
归档：用 restic（加密、去重、增量）或 rclone 推到对象存储/外置硬盘： ```bash restic backup ~/Documents/ChatGPT/swe/artifacts --tag swe-artifacts rclone sync ~/Documents/ChatGPT/swe/artifacts remote:workbench-archive/swe --progress ```
引用：知识笔记里写 external://swe-artifacts/<sha256>，不复制文件。
保留窗口：原始会话保留 90 天（之后只留 manifest + 摘要）；评测 artifacts 保留"每个实验的最终报告 + 清单"，中间产物 30 天后可清。

判断标准：这份文件丢了，还能不能从别处重建？ 能重建的（repo、node_modules、镜像层）不存；不能重建的（实验输出、会话日志、报告）存清单，重要的存原文。

4. 脱敏规则（`bin/scrub.py`）

必须替换为 [REDACTED:<type>] 的模式：

sk-…、sk-proj-…、gho_…、ghp_…、github_pat_…、xoxb-…、xoxp-…、AIza…
AKIA[0-9A-Z]{16}、AWS secret key 形态
Bearer <token>、Authorization: ...、`api_key=[REDACTED:generic_secret]
-----BEGIN … PRIVATE KEY----- 块
邮箱、手机号（个人数据）
会话里粘贴的 .env、auth.json、credentials.yaml 内容

永不入库（.gitignore + CI gitleaks 兜底）：~/.codex/auth.json、~/.dsh/.credentials.yaml、 cookies、SSH 私钥、OAuth token、浏览器 profile。

抽查：python3 bin/scrub.py --check data journal site（提交前必跑）；

CI 用 gitleaks；人工再 git diff --cached | grep -iE 'sk-|gho_|Bearer|AKIA' 一次。

5. git 策略

单仓库（私有）：data/ 只提交 L1 + 采样 L2；data/raw/ 在 .gitignore 中。
大文件：需要时 git lfs track "data/raw/**"（配置已注释在 .gitattributes）；注意 GitHub LFS 免费额度 1 GB 存储/月流量。
仓库体积：git count-objects -vH 定期检查；> 500 MB 时拆库（workbench-data）或改用外部归档。
整包封存：每次导出后 export_sessions.py 生成 data/manifests/checksums.sha256 （data/ 下所有文件的 sha256），doctor.py 逐行校验——这是 BagIt（RFC 8493）的轻量版，用来证明"数据包没有被悄悄改动"，比只校验样本更强。
历史卫生：raw 只增不改，便于 diff；删除用 data/manifests/retired.jsonl 记录，不实际删旧提交（除非泄露需要 rewrite + 轮换密钥）。

6. 恢复数据（不是恢复配置）

另一台机器只需要：manifests + journal + kb + site（git 内已有）→ 立刻可读、可回顾。
需要原始会话原文时：从外部归档 restic restore / rclone copy，或在本机重新导出（如果源还在）。
bin/export_sessions.py 支持 --out 指向任意目录，不会改源数据，适合先导出到临时盘再归档。

7. 隐私与个人数据

kb/90-personal/ 的投资/账户主题必须标 sensitivity: personal；发布站点显示"个人"徽标。
真实持仓、账户余额、交易记录、身份证件、家庭信息不写入仓库；只写方法论与去敏案例。
若未来仓库转公开：先跑 scrub --check + gitleaks 全历史扫描，再考虑用 git filter-repo 清理历史。

跨机器恢复手册（Codex + DSH）

目标：在一台新 macOS 机器上，git clone 之后 10 分钟内恢复到"能继续工作"的状态：配置、skills、记忆、profile 结构、版本基线、验证清单。 凭证不随仓库走（安全要求）：Codex 重新登录，DSH 重新配置 API key。

0. 前置：两边的版本基线

当前基线（2026-11-05，恢复时允许升级但先记录）：

组件	版本	检查命令
macOS	26.7.1 (25G241)	`sw_vers`
Git	2.50.1 (Apple)	`git --version`
Python	3.9.6（系统自带即可；脚本零依赖）	`python3 -V`
Node	v24.21.0	`node -v`
zstd	1.5.7	`zstd --version`
GitHub CLI	2.102.0	`gh --version`
Homebrew	7.0.7	`brew --version`
Codex CLI / 桌面	codex-cli 0.166.0-alpha.6（ChatGPT.app 内置）	`codex --version`
DSH	0.2.1-rc.2（npx 安装）	`dsh --version`

版本只作记录，不强制一致；恢复后跑 python3 bin/doctor.py 会检查差异并提示。

1. 新机器恢复（推荐顺序）

# 1) 拿到仓库（私有仓库需要先 gh auth login）
gh auth login
git clone [REDACTED:email]:<you>/workbench.git
cd workbench

# 2) 安装基础工具（可选，检查缺失项）
brew bundle --file env/Brewfile        # 或按 env/versions.md 手动装

# 3) dry-run 看恢复动作
bash configs/restore.sh all --dry-run

# 4) 实际恢复（脚本会先备份现有文件）
bash configs/restore.sh all

# 5) 体检
python3 bin/doctor.py

# 6) 站点确认
python3 bin/build_kb.py --out site && open site/index.html

1.1 Codex 恢复内容

内容	仓库内模板	恢复到	说明
主配置	`configs/codex/config.toml.tmpl`	`~/.codex/config.toml`	`{{HOME}}` 占位符渲染为本机 `$HOME`；已有文件先备份
全局指令	`configs/codex/AGENTS.md`	`~/.codex/AGENTS.md`	用户级 agent 指令
skills	`configs/codex/skills/*`	`~/.codex/skills/`	同时提示：Codex 记忆内 skills 在 `~/.codex/memories/skills/`，按需复制
记忆	不直接复制	—	`~/.codex/memories` 是 Codex 自己的本地 git 仓库；新机器可由 Codex 重建，或手动 `git clone` 其 bundle
认证	不备份、不恢复	—	新机器重新登录 ChatGPT/Codex；`auth.json` 永不入库
会话历史	不默认恢复	—	历史在 `data/`；如需灌回，见 §4

1.2 DSH 恢复内容

内容	仓库内模板	恢复到	说明
profile 依赖	`configs/dsh/package.json.tmpl`	`~/.dsh/profiles/web/package.json`	bundle 列表；node_modules 不恢复，需重装
profile 覆盖层	`configs/dsh/cordis.patch.yml.tmpl`	`~/.dsh/profiles/web/cordis.patch.yml`	模型、provider、插件配置（不含 key，key 走环境变量）
凭证	不备份、不恢复	—	API key 用环境变量（如 `IQUEST_API_KEY`）或重新登录
会话	不默认恢复	—	历史在 `data/`；DSH 会话是 `*.jsonl.zstd`
安装	`npm i -g @deepseek-ai/dsh@<version>` 或 npx	—	版本记录在 `env/versions.md`

# DSH profile 依赖重装（示例，按实际版本）
cd ~/.dsh/profiles/web && pnpm install --frozen-lockfile
# 或从市场重新添加插件（bundle 列表见 configs/dsh/package.json.tmpl）

2. 现有机器（换/加第二台）怎么同步

配置：改完本机配置后，回头更新 configs/ 模板（脱敏后）→ commit。
数据：python3 bin/export_sessions.py --source all 增量导出 → commit（L1/L2）。
知识：直接改 kb/，重建站点，commit。
冲突：raw 层按日期分文件，天然少冲突；kb/ 同一篇笔记建议单机编辑（或按领域分工）。

3. 验证清单（恢复后逐条打勾）

python3 bin/doctor.py            # 环境、结构、manifest hash、密钥扫描
codex --version && dsh --version
# Codex 打开一次会话，确认能登录、模型可用、skills 被加载
# DSH 打开 web profile，确认 provider/模型/插件正常
open site/index.html             # 站点能离线打开
python3 bin/build_kb.py --check  # 链接/结构检查

[ ] git status 干净，git log 有历史
[ ] ~/.codex/config.toml 与模板差异符合预期（无硬编码旧用户名/路径）
[ ] ~/.codex/AGENTS.md、skills 已就位
[ ] ~/.dsh/profiles/web/{package.json,cordis.patch.yml} 已更新，node_modules 已装
[ ] Codex / DSH 各自能起一个最小会话
[ ] data/ 与 site/ 可读，无密钥告警

4. 可选：把会话历史灌回本机（一般不需要）

bin/export_sessions.py 是导出/归档工具，默认不会写回 ~/.codex 或 ~/.dsh。如确实需要：把 data/samples/ 或 LFS 中的原始文件复制回对应目录（保持原目录结构），再重启对应应用。先备份原目录，并确认不会与现有会话 id 冲突（用文件名/id 去重）。

5. 故障处理

现象	处理
`restore.sh` 提示找不到模板	确认在仓库根目录执行；检查 `configs/` 是否完整
Codex 启动后模型不可用	检查 `~/.codex/config.toml` 的 provider 段与 `env_key`；重新登录
DSH profile 起不来	`cd ~/.dsh/profiles/web && pnpm install`；检查 `cordis.patch.yml` 缩进/YAML
`doctor.py` 报 manifest hash 不一致	数据被改动或未完整恢复；重跑 `export_sessions.py` 或从 git 重新 checkout
站点打不开/样式丢失	确认整个 `site/` 目录一起移动；`build_kb.py --out site` 重建
疑似密钥进了 git	立即轮换该密钥；用 `git filter-repo` 清理历史；开 gitleaks push protection

6. 安全边界（务必遵守）

auth.json、.credentials.yaml、.env、SSH 私钥、cookies → 永不提交。
恢复脚本只做"模板 → 本机文件"的复制，并先备份；不联网、不安装、不登录。
公开分享前：python3 bin/scrub.py --check . + gitleaks 全历史 + 人工抽查 kb/90-personal。

知识条目写作规范（Authoring）

本文规定 workbench/kb/ 下所有 Markdown 的写作方式。解析器只支持 docs/02-architecture.md §3.2 定义的 YAML 子集，任何超出子集的写法都会被静默解析错。

1. 什么时候新建 / 合并 / 归档

新建一条 note，当且仅当同时满足：

有一个可复述的问题（不是「记录一下」）。
有能回指的一手证据（session:、path:、report:、artifact:、url:）。
结论能脱离原会话被理解（读者不看对话也能用）。
不是已有 note 的子段落；如果只是补充例子，合并进已有 note。

合并：同一问题、同一机制、同一领域；或两条 note 的结论互相依赖且总长 < 150 行。合并时保留更早的 created，更新 updated，把旧链接改为新路径（或保留别名说明）。

归档：结论被新证据推翻、机制已不存在、或只对某个已结束实验有效。把 status 改为 archive，在「未决问题与边界」写清归档原因与替代条目，不要删除文件 （历史的错误结论本身是证据）。evergreen 只给长期稳定、经过至少一次外部复核的机制类笔记。

升级证据等级：E1 → E2 需要本机可回查的输出（命令、日志、抓包）；E2 → E3 需要固定步骤与数据，使他人能复现。没有新证据不要改 confidence。

2. 目录与命名

kb/
├── index.json            # 6 个领域注册（Lead/契约维护，作者不改结构）
├── 00-map/<domain>.md    # 每领域 1 篇 MOC，type: map
├── 10-harness/
│   ├── dsh/              # 子主题目录，parent: dsh
│   ├── codex/            # parent: codex
│   └── industry/         # parent: industry
├── 20-eval/{harbor,deepswe,benchmarks}/
├── 30-protocol/{responses,messages,gateway}/
├── 40-infra/{gateway,dsh-setup,cloud}/
├── 50-workflow/{evidence,reporting,automation}/
└── 90-personal/{investment,interview}/   # 必须 sensitivity: personal

文件名：kebab-case.md，英文、名词短语、不带日期（日期在 frontmatter）。
一个子主题目录 ≥2 篇时自然成组；只有 1 篇也可以，但不要为了凑组硬拆。
parent 必须等于直接父目录名（不带路径），00-map 下为 ""。
领域由一级目录 + domain 字段共同确定，两者必须一致。

3. frontmatter 规则

---
title: "DSH 上下文压缩触发条件"     # 必填；含冒号必须加双引号
domain: harness                     # 必填；6 个 id 之一
parent: dsh                         # 子主题目录名；MOC 用 ""
tags: [dsh, context, compaction]    # 行内列表，≤6 个
status: growing                     # seed | growing | evergreen | archive
confidence: E1                      # E0 | E1 | E2 | E3
type: note                          # note | map | report
summary: "一句话结论，30 字内"      # 必填；会出现在树与搜索结果
created: 2026-11-05                # YYYY-MM-DD
updated: 2026-11-05
sources:                            # 至少 1 条；多行 - 列表
  - session:codex:01a16427-93c4-7a53-85be-07310e73f148
  - path:/Users/lizhao/Documents/deepseek-harness/swe/ROADMAP.md
  - artifact:harbor-eval-framework
---

parser 子集（必须遵守）

只支持：字符串标量、行内列表 [a, b]、多行 - 列表。不支持嵌套字典、块标量 |/>、多行字符串、引号转义外的特殊字符。
含 :、#、[、] 的值必须用双引号包裹（如 summary: "问题：结论"）。
日期只写 YYYY-MM-DD，不加引号也不用时间戳。
sources 的 path: 用绝对路径；url: 只写确定存在、可访问的链接（访问日期写进正文证据表）。

4. 正文结构（推荐但强约束）

## 问题
这篇笔记要回答什么？为什么值得记录？（1–3 句）

## 结论
直接给结论；用「已验证 / 未观察到 / 证据不足 / 未验证」标注。

## 证据
| 证据 | 类型 | 位置 | 说明 |
|---|---|---|---|
| ... | 会话/源码/实验/文档 | `session:...` / `path:...` / `url:...` | 能复现或能回查 |

## 细节 / 机制
只写支撑结论的部分；数据流、配置、步骤、对照表。

## 未决问题与边界
哪些没验证、什么条件变化会失效、下一步查什么。

正文 60–150 行；超过 150 行优先拆分，不要靠压缩字句硬塞。
每篇至少 1 个可执行/可回查的证据；没有证据的段落降级为「待验证」或删除。
表格用于对比与证据，不用来堆砌无信息量的字段。

5. 证据分级与写法

confidence

等级	标准	写作提示
E0	想法/假设	明确写「假设，未验证」
E1	读过一手来源	引用来源，不写「已验证」
E2	本机实际验证	给出命令/输出/抓包位置
E3	可复现实验	给出固定步骤、数据、版本

sources 写法

session:codex:<thread_id> / session:dsh:<session_id>：只写真实 id，不臆造。
path:<绝对路径>：文件必须存在；写进正文时可用相对仓库的短路径。
url:<https://...>：只写访问过且确定存在的；访问日期写进证据表。
artifact:<id>：必须在 artifacts/index.json 中存在。
report:<reports/ 相对路径>：必须存在。

S/D/T/H（研究类）

S = 固定 commit 源码；D = 官方文档；T = 本地/受控测量；H = 未验证假设。只有 S/D 的结论不支持排名、选型或因果判断。

6. 措辞纪律

先问题、后结论；先说明「解释了什么、排除了什么、仍不知道什么」。
小样本不写因果：用「未观察到提升」「证据不足」，给分母与排除项。
不把启动成功、退出码 0、单测通过、静态检查通过当作验收。
「配置/README/manifest 写了」≠「运行时生效」；要写清证据到哪一层。
中文优先，专有名词保留英文；代码注释英文即可。

7. 链接规范

笔记之间用相对路径：同目录 ./x.md 可省略，跨目录 ../20-eval/harbor/trial-lifecycle.md。
MOC 必须链接到本领域全部 note；新增 note 时同步更新 MOC 入口表。
正文引用证据用反引号包路径，不依赖渲染器。
不写 file:/// 绝对链接；不写仓库外的相对链接。
发布前跑 python3 bin/build_kb.py --no-build --check（只校验已有站点）或 make check，断链必须为 0。

8. 评审清单（提交前逐条打勾）

[ ] 领域与目录一致；parent 是直接父目录名。
[ ] 必填字段齐全；无 parser 子集之外的语法；含特殊字符的值已加引号。
[ ] sources 至少 1 条且可回查；artifact:/report: 指向存在对象。
[ ] 正文五段齐全；结论标注证据等级；有「未决问题与边界」。
[ ] 行数 60–150；没有空话段落。
[ ] MOC 已加入口；无断链。
[ ] 不含密钥、账号、真实财务数字；个人主题有 sensitivity: personal。
[ ] 没有写作用域外文件。

9. 反模式（出现即打回）

标题是主题词而不是问题（「关于缓存」）。
结论段抄来源摘要，没有自己的判断与边界。
证据表列了 URL 但没写访问日期，或链接是搜索页/二手转述。
用「显著提升」「明显更好」而不给分母、对照与定义。
把配置当行为、把请求字段当服务端生效、把启动当验收。
一篇 note 塞三个不相关机制。
重命名/移动后留下断链，或靠 # 占位。

公开部署（Cloudflare Pages 推荐）

状态：--public 构建与校验已就绪、实测通过。免费计划用 Cloudflare Pages（见 §5）；有 GitHub Pro 才用 GitHub Pages（见 §3）。一句话：site/ 是私有全量站（本机用）；site-public/ 是公开脱敏站（部署到 Cloudflare Pages / GitHub Pages）。两者由同一个 build_kb.py 生成，互不干扰。

1. 为什么分两套

	`site/`（私有）	`site-public/`（公开）
命令	`make build`	`make public`
领域	6 个（含 personal）	5 个（排除 personal）
笔记	29 篇	25 篇（排除 `sensitivity: personal/confidential/private`）
会话 cwd	原样	脱敏为 `~/...`
原始产物文件	复制可下载	不复制，只展示登记卡片
docs/reports	原样	脱敏 + 丢弃引用 personal 的行
适用	本机/可信环境	GitHub Pages（任何人可读 URL）

核心事实：GitHub Pages 站点对任何知道 URL 的人公开可读，与仓库是私有还是公开无关。 仓库设私有只保护源码，不保护已发布的页面。所以公开站必须独立构建、严格脱敏。

2. 公开构建做了什么（`build_kb.py --public`）

排除个人领域：kb/90-personal/（personal 领域）整体不进入公开站。
排除敏感笔记：任何 frontmatter 标 sensitivity: personal|confidential|private 的笔记都不公开。
脱敏本机路径：会话 cwd/original_path、artifacts source_path、kb 笔记正文、docs/reports 里的 /Users/<name> 全部替换为 ~。
丢弃个人引用行：docs/reports 里提到 90-personal、` personal ` 领域或被排除笔记标题的行会被删除（如月报领域统计表、周报 changelog）。
不发布原始产物：site-public/artifacts/ 不放原始 .md/.html 快照，artifacts 页只显示卡片元数据，无下载链接。
公开校验：构建后自动跑 check_public()，扫描全部页面确认无被排除标题、无 /Users/ 路径；任一条命中即构建失败、不发布。

调整排除规则：改 bin/build_kb.py 顶部的 PUBLIC_EXCLUDED_DOMAINS / PUBLIC_EXCLUDED_SENSITIVITY 两个常量即可。

3. 有 Pro 计划才用 GitHub Pages（可选）

免费计划走 §5 Cloudflare Pages（推荐）。本节仅在你是 GitHub Pro/Team/Enterprise 时适用。 .github/workflows/pages.yml 已写好，push 到 main 自动构建并部署到 Pages；仓库 Settings → Pages → Source 选 GitHub Actions 即可。

打开仓库 → Settings → Pages。
Build and deployment → Source：选 GitHub Actions（不是 "Deploy from a branch"）。
保存。.github/workflows/pages.yml 会在 push 到 main 时自动构建 site-public/ 并部署。
触发方式：push 到 main（且改动了 kb/ docs/ reports/ artifacts/index.json/ data/manifests/ bin/build_kb.py 或 workflow 本身），或手动 Actions → publish-public-site → Run workflow。
部署完成后，Pages 地址形如 https://<用户>.github.io/<仓库>/。

4. 发布前自查清单（每次新增敏感内容后过一遍）

# 本地构建公开站并校验
make public

# 全树扫描确认无个人内容/本机路径
for kw in '90-personal' 'STX' 'P8+' '杠杆' 'portfolio-risk' 'p8-agent-interview' '/Users/'; do
  echo "$kw → $(grep -rl "$kw" site-public/ 2>/dev/null | wc -l | tr -d ' ') 文件"
done

# 密钥扫描
gitleaks detect --source . --redact --no-git

任何一项非 0 就不要 push，先回到 bin/build_kb.py 的脱敏规则修。

5. 免费计划：用 Cloudflare Pages（推荐）

私有仓库开不了 GitHub Pages，但 Cloudflare Pages 免费、有 CDN、可绑自定义域名，且构建逻辑完全复用 make public（已验证不依赖 zstd，纯 Python stdlib）。

5.1 一次性对接（在 Cloudflare Dashboard 点，不改仓库）

注册/登录 Cloudflare → 左侧 Workers & Pages → Create → Pages → Connect to Git。
授权 GitHub：选择授权 Cloudflare App 访问 RoonyLi/workbench（私有仓库也可，需在授权列表里勾选它）。
项目设置填：

Production branch：main
Framework preset：None
Build command：make public
Build output directory：site-public
Root directory：留空（仓库根）

环境变量（可选）：PYTHON 设为 python3（默认即是）。不要设 PYTHONPYCACHEPREFIX，Cloudflare 构建目录可写。
保存 → Save and Deploy。首次构建约 1-2 分钟。
部署完成后得到 https://<项目名>.pages.dev/，任何知道 URL 的人可读（与仓库私有性无关，故内容必须经 --public 脱敏）。

5.2 构建为什么不会失败

Cloudflare 构建镜像没有 zstd CLI，但 make public 只跑 build_kb.py（纯 stdlib），不重新导出会话（数据已在仓库 data/manifests/）。已实测：去掉 zstd 的 PATH 下 make public 仍通过校验。
build_kb.py --public 构建后自动跑 check_public()，校验失败会让构建中止、不产出坏站——这是 Cloudflare 部署的天然闸门。
每次 push 到 main 且改动了 kb/docs/reports/artifacts/index.json/data/manifests/bin/build_kb.py 会自动重新构建部署（Cloudflare 默认全量监听，无需 workflow）。

5.3 自定义域名（可选）

项目 Custom domains → 添加域名 → 按提示在 DNS 加 CNAME。Cloudflare 自动签 HTTPS 证书。建议绑一个不暴露主域名的子域（如 notes.<你的域>）。

5.4 其它备选（不想用 CF 时）

方案	做法	代价
独立公开仓库	新建 public 仓库（如 `RoonyLi/workbench-site`），GitHub Actions 把 `site-public/` 推过去	多一个仓库；公开内容需再核一遍
本机 + cloudflared 隧道	本机 `python3 -m http.server` + `cloudflared tunnel --url http://localhost:8000`	要本机常开；隧道地址会变

Cloudflare Pages 也是「站点对知道 URL 的人公开可读」，所以 §4 发布前自查清单照样适用。

6. 回滚

公开站内容来自 main 的 kb/docs/reports。若误发了敏感内容：

立即在 GitHub 仓库 Settings → Pages 关掉 Pages（或删 workflow）。
从 main 移除/脱敏敏感源文件。
push 触发重新部署（覆盖坏内容）。
若已泄露到搜索引擎缓存/他人手中，按密钥泄露流程处理（见 docs/03-data-policy.md）。

数字边界：本仓库当前 kb/ 共 29 篇笔记、6 领域；公开站 25 篇、5 领域。任何数字以 make public 构建输出与 check_public 为准，不要凭记忆。

回报闭环：周报 / 月报 / 指标与复盘

目标：让「做了什么」变成可回查的数字与可执行的下一步，而不是流水账。数据来源固定为 journal/、data/manifests/、kb/、artifacts/、reports/；数字必须能回到文件或命令。

1. 闭环

捕获(export) → 摘要(journal) → 知识(kb) → 产物(artifacts) → 发布(site)
       │             │             │             │
       └──────┬──────┴──────┬──────┴──────┬──────┘
              ▼             ▼             ▼
          周报（7 天）   月报（自然月）   复盘与调整
              │             │
              └────► 下一周期计划 / 契约修订 / 归档

原则

先问题后结论；数字是证据，不是结论本身。
分母、排除项、缺失、未知必须写；缺失不是 0，未知成本不是免费。
报告是给「下周的自己」看的：每个结论后面要有动作。
生成器只产事实块；判断与取舍由人写。

2. 生成方式

# 周报（以 2026-11-05 为基准日）
python3 bin/report.py --period week --date 2026-11-05 --out reports
# 月报
python3 bin/report.py --period month --date 2026-11-05 --out reports

生成器读取：

输入	用途
`journal/YYYY/MM/*.md`	每日会话表（时间/来源/标题/目录/轮次/成本/会话 id）与人工要点
`data/manifests/summary.json`	totals（sessions/codex/dsh/bytes）、生成时间
`data/manifests/codex.jsonl`、`dsh.jsonl`	逐会话字段（日期、cwd、model、tokens、cost）
`kb/*/.md`	note 数、领域分布、status/confidence 分布、新增/更新
`artifacts/index.json`	产物数、类型/领域分布、总字节
`reports/` 上期文件	环比

生成后人工补写：本期结论、异常解释、下期计划、需要 Lead 决策的事项。

3. 周报模板

# 周报 W{ISO 周}（{起} ~ {止}）

## 0. 一句话
本周最重要的结论或变化（1–2 句）。

## 1. 数字
| 指标 | 本周 | 上周 | 说明 |
|---|---|---|---|
| 有效会话数 | N | N | 来源：summary.json；排除：X |
| 覆盖天数 | N/7 | N/7 | journal 有内容的日期 |
| 新增 note | N | N | kb 文件 diff；按领域列出 |
| 新增产物 | N | N | artifacts/index.json |
| 断链数 | 0 | 0 | `build_kb.py --check` |
| 脱敏命中 | 0 | 0 | scrub/grep 自查 |

## 2. 本周问题 → 结论 → 证据
| 问题 | 结论（含证据等级） | 证据 | 局限 |
|---|---|---|---|

## 3. 未观察到 / 证据不足
- （明确列出没有结论的尝试，避免下周重复）

## 4. 下周计划（≤3 项）
- [ ] ...
- [ ] ...

## 5. 需要决策 / 阻塞
- ...

4. 月报模板

# 月报 {YYYY-MM}

## 1. 概览
- 会话：{N}（Codex {N} / DSH {N}），覆盖 {D} 天，token/成本估算 {…}
- 知识：note {N} → {N}（+{N}），领域分布 {harness: N, eval: N, ...}
- 产物：{N} 个，总 {MB}
- 发布：site 构建 {次数}，断链 {0}

## 2. 本月三个关键问题
### 问题 1：…
- 结论（已验证/未观察到/证据不足）：
- 证据：
- 排除了什么：
- 仍不知道：
- 对下一步的影响：

### 问题 2 / 3：同结构

## 3. 数据质量
- 脱敏：命中与处理
- 口径变化：窗口/排除/重跑
- 异常样本：服务/传输/采集/verifier/模型 分类计数

## 4. 复盘
- 哪些结论被推翻？对应 note 的 status/confidence 改了吗？
- 哪些投入产出低？下月砍掉什么？
- 哪些契约/流程需要改？（写进 docs/02-architecture.md 变更提案）

## 5. 下月计划（≤3 项，带验收标准）

5. 指标定义

指标	定义	来源	注意
会话数	manifest 行数	`data/manifests/*.jsonl`	按 date 字段归属；跨天会话记开始日
有效会话	有原始 result/产物且非采集异常的会话	journal + 原始证据	排除项必须列出
覆盖天数	journal 中有人工内容或 auto 表的天数	`journal/`	空文件不算
新增 note	本期新建的 kb 文件	`kb/*/.md`	不含修改；修改单独计
note 总数/领域分布	按 `domain` 字段统计	frontmatter	与 MOC 数一致
evergreen 比例	`status: evergreen` / 总 note	frontmatter	不是越高越好
新增产物	index.json 增量	artifacts	单文件 ≤10MB、总量 ≤30MB
断链数	`build_kb.py --check` 报告	构建输出	必须 0
脱敏命中	scrub 替换计数 + grep 自查命中	导出日志/命令输出	真实密钥另行事件记录
token/成本	manifest 的 token 字段与价格估算	manifests	估算值 ≠ 账单；注明价格表版本
成本（环境）	沙箱/云资源费用	账单/实验记录	与模型成本分开

口径纪律

报告每张表都要有「来源 + 窗口 + 排除」三要素。
重跑/重试不重复计入会话数，但要在异常里出现。
「完成了 113 案评审」这类表述要写清是静态检查还是含真实浏览器/运行验证；不能把静态通过当语义完成。

6. 复盘与调整

每周 15 分钟

对照周报：哪些数字异常？先查口径，再解释。
检查 note：孤立、过期、该升级/归档的列出来。
检查产物：重复、超大、断链。
给下周定 ≤3 个可验收目标（写「观察到什么算完成」）。

每月 30 分钟

重读月报的「三个关键问题」：证据是否仍成立？版本是否变了？
调整知识树：合并重复主题、归档被推翻结论、补 MOC 入口。
调整流程：哪一步最耗时/最常失败？改脚本或改 SOP，并在 docs/02-architecture.md 记录契约变化。
恢复演练与安全审计各一次。
输出下月计划（≤3 项，带验收标准与分母）。

调整规则

结论被推翻 → 改 note 的 status/confidence，在「未决问题与边界」写原因；不删历史。
契约要变 → 先改 docs/02-architecture.md，再改实现与生成器。
指标要变 → 在月报里说明口径变化，并保留旧口径重算一版做对比。

7. 发布与归档

周报/月报写入 reports/weekly/、reports/monthly/，随站点 reports.html 渲染。
每季度把已稳定的月报结论合并进 kb（一条 note 一个机制），月报本身保留原文。
报告里的个人信息（账户、财务、面试）必须标 sensitivity: personal 或脱敏，不入公开页。

业界经验（浓缩版）：哪些做法值得抄，哪些不值得

作者：industry-researcher ｜日期：2026-11-05 ｜详细版：research/industry-practices.md（含完整引用与验证过程）引用访问日期均为 2026-11-05；可靠性标注：官方 / 标准 / 源码 / 二手。所有链接实测可访问。

一、五条核心判断

四层架构（raw→journal→kb→site + configs）与数据湖 medallion 同构，方向正确；关键纪律是 raw 只增不改、每层可重建、生成器幂等，没有这三条，四层就退化为四个文件夹。
知识组织不要混用 PARA：PARA 按"可行动性"分（Projects/Areas/Resources/Archives），kb 按主题领域分，两者正交。只在 journal/报告层借 PARA 的"项目推进"视角；kb 保持 6 领域树 + parent + sources。
文档工具链全部不引入：MkDocs Material / Docusaurus / VitePress / Quartz / mdBook / Pagefind 都需要 node/rust/构建服务，违背本仓库"零依赖、file:// 直接打开、Python 3.9 标准库"的硬约束。借理念（内容与呈现分离、导航由约定文件驱动、构建可复现、链接检查进 CI），不引工具。
证据可验证性的最优解是 BagIt 的轻量版：data/manifests/*.jsonl 已有 stored_sha256，再补一份整包校验清单 + doctor.py 校验即可，不需要 DVC/git-annex/区块链。
Agent 轨迹没有权威公开标准（未找到 IETF/W3C/ISO 级标准）：固定自有 JSONL schema + format_version，字段命名向 OTel GenAI 靠拢、step 类型参考 Harbor ATIF 草案；不要为了"追标准"引入依赖。

二、业界实践 → Workbench 落地映射表

#	业界做法（来源）	Workbench 落地（目录/脚本）	决策	理由
1	medallion bronze/silver/gold（Databricks 官方）	`data/`(raw) → `journal/`+`analysis/`(silver) → `kb/`(gold) → `site/`	采纳	已在架构 §1 对齐；补"raw 不可变/可重建/幂等"三纪律
2	BagIt RFC 8493 manifest（标准）	`data/manifests/*.jsonl` 的 `stored_sha256`；建议加 `checksums.sha256`	部分采纳	已有逐文件 hash，缺整包校验；补一个校验脚本即可
3	BagIt `fetch.txt` 声明外部内容（标准）	L3 `external://` 引用 + `artifacts-external.jsonl`	采纳	与 docs/03 的"外部归档 + sha256 引用"完全同构
4	W3C PROV 溯源（标准）	kb frontmatter `sources` 六种前缀；建议补 `generated_by/generated_at`	部分采纳	只借 Entity/Activity/Agent 概念，不落地 RDF
5	append-only 不可变日志（RFC 6962 CT 是工业范例）	git 历史 + raw 只增不改 + sha256 清单	部分采纳	git 本身是内容寻址 Merkle DAG，无需区块链
6	DVC / git-annex（官方）	不采用；L3 用外部归档 + 清单	不采纳	无 ML 流水线/多机大文件同步需求，依赖成本 > 收益
7	Git LFS（GitHub 官方）	仅 L2 全量原文场景，满足 docs/03 §2 三条件才启用	暂缓	默认"清单 + 样本"已够；LFS 有配额与客户端成本
8	restic 加密增量备份（官方）	`env/Brewfile` 已列 restic；L3 归档命令写进 docs/03	采纳（可选）	borg 定位重叠，单机二选一
9	Diátaxis 四类文档（官方）	`docs/01-08` 编号 + 每篇标注类型	采纳	类型分离能防"教程混参考"；成本极低
10	C4 model 四级抽象（官方）	`site/index`(L1)→`tree`(L2/3)→note(L4)→sources(证据)	采纳	架构已对标；建议补一张对照表进 docs/02
11	PARA 四分类（Forte Labs 官方）	journal/报告层的"项目推进"视角	部分采纳	kb 按领域组织，强行 PARA 会破坏 6 领域契约
12	Zettelkasten 原子笔记（社区权威）	一 note 一结论 + `parent` + `sources`	采纳（简化）	不引入 `[[wikilink]]`（渲染器不支持、断链不可校验）
13	MOC / 内容地图（LYT 官方笔记）	`kb/00-map/<domain>.md`（`type: map`）	采纳	架构已定；建议脚本生成草案，人工只策展
14	Digital Garden 生长状态（作者官方页）	`status: seed/growing/evergreen/archive` + site 徽章	采纳	已落地；注意 personal 领域默认不公开
15	Johnny.Decimal 编号分区（官方）	`journal/YYYY/MM/` + 现有 note 路径/ID	不采纳编号	已有更强唯一 ID，重复编号增加心智成本
16	chezmoi 模板/diff/dry-run（官方）	`configs/restore.sh`（已有模板/备份/dry-run）	部分采纳	借三原则；不引入 chezmoi 二进制
17	Homebrew Bundle（官方）	`env/Brewfile` + 恢复时 `brew bundle check`	采纳	已存在；cleanup 不默认跑（会删用户包）
18	mise/asdf 版本管理（官方）	`env/versions.md` + `doctor.py` 输出实际版本	暂缓	node/python 由系统提供，多一个恢复步骤不划算
19	Nix + home-manager / devcontainers（官方）	不采用	不采纳	需要先装 Nix/Docker，恢复门槛升高；与闭源 Codex 桌面不兼容
20	gitleaks + GitHub secret scanning / push protection（官方）	`.github/workflows/ci.yml` 已接 gitleaks；仓库设置开 push protection	采纳	三层防线；gitleaks 已是 CI job
21	SOPS+age / git-crypt（源码）	`configs/` 只放模板；如必须入库敏感值用 SOPS+age	暂缓 / 不采纳 git-crypt	当前无必须入库的敏感值；git-crypt 要求每个克隆者安装
22	GitHub Pages 官方 workflow（官方）	`ci.yml` build + upload-artifact；Pages publish 注释掉	暂缓	私有仓库 Pages 需 Pro/Team/Enterprise（官方文档）
23	OTel GenAI 语义约定（官方）	manifests 字段预留 `gen_ai.*` 映射；不接 SDK	部分采纳	零依赖约束；未来可低成本导出
24	ATIF / OMA trajectory v1（社区草案）	自有 JSONL + `format_version`；step 类型参考 ATIF	部分采纳	无权威标准；固定格式+版本字段最稳
25	AGENTS.md / CLAUDE.md / Cursor rules / Skills（官方）	`AGENTS.md`（Lead 已建）+ `configs/codex/skills/workbench-capture/`	采纳	已有；建议 AGENTS.md 只写协议、知识放 docs/kb
26	GTD Weekly Review（官方 PDF）	`bin/report.py --period week` + `reports/weekly/`	采纳	周报固定四问：清空/推进/下周/未决
27	OKR（What Matters 官方）	月报"2-3 个目标 + 1-2 个可验证结果"	部分采纳	不搞打分流程，借结构
28	DORA 四键 / 成对指标（官方）	四维指标：活跃度/产出/知识增量/成本（各带分母与排除项）	采纳	防单一指标异化；报告数字必须可脚本复现
29	single source of truth（Fowler CI）	manifests + git 是唯一事实源；journal/site/reports 全派生	采纳	与四层架构一致；人工只写 auto 块外
30	Conventional Commits（官方规范）	AGENTS.md §7 已约定 `feat(kb):` / `data:` / `docs:`	采纳	成本为零；无需 commitlint
31	GitHub 体积配额（官方：单文件 50MiB 警告/100MiB 阻断、push 2GB、仓库 10GB、Pages 1GB）	docs/03 数据策略 + `doctor.py` 体积检查	采纳	目标 <30MB，但 git 历史会累积，需门禁

三、比初始设想更好的 5 条建议（具体可执行）

给 raw 层加"整包校验"（BagIt 轻量版）。 新增 data/manifests/checksums.sha256（<sha256> <path>，覆盖 data/samples/、journal/ 快照、artifacts/index.json），由 bin/doctor.py 全量校验、失败即红（对应 Makefile check）。当前 manifests 只有逐文件 hash，缺少"整包没被动过"的证明；这是 BagIt RFC 8493 的最小可用子集，成本约 30 行 Python。
journal 自动块加内容指纹，做到真正幂等。 把 auto 块标记改为 ：生成器先算新块，与旧块 hash 相同则跳过写入，不同才替换；build_kb.py 解析 journal 时校验块边界。这样"重跑生成器不覆盖人工内容"从口头约定变成机器保证，也顺带满足了幂等验收。
MOC 自动生成草案 + "证据完整率"进体检。 build_kb.py --check 为每个领域生成 kb/00-map/<domain>.md 草案（列出该领域 note 的 title/summary/status，人工只删改排序），并统计"sources 非空的 note 占比"，低于 80% 时警告。MOC 手工维护是长期成本；PROV 溯源的最小实现就是"每条结论都有锚点"。
会话 schema 加 format_version，预留 OTel 映射，不追轨迹标准。 data/manifests/.jsonl 每行加 format_version: 1（未来兼容解析的依据）；在 docs/02 §4.2 附一列 workbench 字段 → gen_ai. 映射（model→gen_ai.request.model、provider→gen_ai.system、tokens→gen_ai.usage.*）。调研确认没有权威 trajectory 标准（未找到），固定自有格式 + 预留映射比自造"标准"务实。
报告四维指标 + "数字必须可脚本复现"硬规则，体积门禁并入 doctor.py。 bin/report.py 只输出四组指标：活跃度（活跃天数/统计天数）、产出（artifacts/报告/note/commit 数）、知识增量（status 迁移数、MOC 覆盖 6 领域、证据完整率）、成本（tokens、CNY、每 note 成本），每项带分母与排除项；docs/06 写死"正文数字禁止手写，必须引用脚本输出"。同时 doctor.py 增加仓库体积 <30MB、单文件 <10MB 检查（GitHub 官方单文件 100MiB 才阻断，但本仓库目标是远低于限制）。

四、风险与未验证项（写作纪律）

未找到：Agent trajectory 的 IETF/W3C/ISO 标准；Logseq 官方 git 同步文档。未验证：GitHub Free 私有仓库协作者数量、私有仓库 secret scanning 的计划范围、Git LFS 免费配额数字、OTel GenAI 的 stability 级别。以上均未作为结论使用。
隐私：kb/90-personal/ 与含财务/账户信息的内容必须 sensitivity: personal，发布页只显示"个人"徽标、不显示明细；这是 digital garden"公开笔记"倾向与本仓库冲突的地方，宁可不发布。
过度工程警戒：本仓库规模约 30MB/6 领域，上述建议都控制在"≤1 个脚本 + ≤1 个清单文件"的量级；任何需要新运行时（node/rust/nix/docker）的方案一律不采纳。

五、精选引用（完整版见 `research/industry-practices.md`）

说明：本文件是浓缩版，1-2 页；每个"决策"的证据与反例在 research/industry-practices.md 对应章节。若与初始设想冲突，以本文件第三节 5 条建议为准（已按"可执行、可验证、不过度工程"筛选）。

路线图（v1 → v2）

原则：先跑起来，再自动化，最后才做花哨的搜索/图谱。 每一阶段有明确验收，不通过不进下一阶段。

Phase 0（已完成，2026-11-05）：骨架 + 契约

[x] 四层目录与 docs/02-architecture.md 契约
[x] kb/index.json、frontmatter 模板、.gitignore/.gitattributes
[x] README / AGENTS（agent 维护协议）/ Makefile / CI
[x] 数据分级与恢复文档（03 / 04）

Phase 1（本周）：数据管线跑通 + 首次提交

[x] export_sessions.py 导出 Codex/DSH manifests + journal
[x] scrub.py 脱敏 + 自检
[x] build_kb.py 生成五页站点（离线可看）
[x] report.py / doctor.py / capture.sh
[ ] git init + 首次提交 + 推 GitHub 私有仓库
验收：make export && make build && make doctor 全绿；git count-objects -vH < 50 MB

首次推 GitHub（需要你确认仓库名/可见性）

cd workbench
git init -b main
git add -A
python3 bin/scrub.py --check data journal site   # 提交前自检
git commit -m "chore: init workbench knowledge repo"
# 二选一：
gh repo create <you>/workbench --private --source=. --remote=origin --push
# 或先建空仓库再 git remote add origin ... && git push -u origin main

建议私有仓库：会话/产物含内部研究信息。若要公开知识层，另建 workbench-public，只推 kb/、docs/、site/ 的脱敏子集（git subtree split 或单独发布会话）。

Phase 2（下周）：跨机器恢复演练 + 自动化采集

[ ] 在第二台机器完整走一遍 docs/04-restore.md，记录耗时与问题
[ ] 安装 automation/com.lizhao.workbench.capture.plist（每日 23:30 capture）
[ ] 启用 gitleaks pre-commit（brew install gitleaks + .pre-commit-config.yaml）
[ ] Codex 的 notify hook / DSH 定时任务触发 capture（可选，先手动跑稳）
验收：第二台机器 30 分钟内可读站 + 可起会话；每日 capture 连续 5 天无失败

Phase 3（本月）：知识树 v2 + 搜索 + 报告闭环

[ ] 笔记从 ~24 篇扩到 40+，补齐每个子主题的"未决问题"
[ ] 站点加客户端全文搜索（Pagefind 或自写倒排，仍保持离线）
[ ] 加知识图谱视图（笔记/领域/会话/产物的引用关系，SVG 手绘即可）
[ ] 周报自动发到 IM/邮件（可选；先本地）
验收：site/tree.html 搜索能覆盖全部笔记；每篇笔记都有 sources 且可回指

Phase 4（可选）：数据层增强

[ ] L3 artifacts 清单自动化（扫描 swe/artifacts 生成 sha256 + 分类）
[ ] restic/rclone 归档脚本 + 恢复演练（docs/03-data-policy.md §3）
[ ] 会话语义去重/主题聚类（本地 embedding 可选，注意隐私）
[ ] 若仓库 > 500 MB：拆 workbench-data 私有数据仓库 + submodule

明确"暂缓"（避免过度工程）

❌ 自建数据库/后端服务：Markdown + 静态站足够
❌ 把 66 GB artifacts 放进 git：用外部归档 + manifest
❌ 自研前端框架：零依赖单文件 HTML，够用
❌ 追求全自动知识生成：人负责判断与取舍，agent 负责采集/整理/校验
❌ 跨平台 UI（Web/桌面 App）：file:// 的静态站就是跨平台

风险与对策

风险	对策
数据量增长导致仓库膨胀	L1/L2 策略 + LFS + 定期 `git gc`；> 500 MB 拆库
密钥误提交	`.gitignore` + scrub + gitleaks + push protection + 轮换流程
笔记腐烂（写了没人看）	月报强制回顾；MOC 半年清理一次；archive 状态
自动化失败无人知	capture 失败写日志 + 下次 doctor 报错 + 周一检查
换机恢复不完整	每季度演练一次；恢复清单逐条打勾

由 bin/build_kb.py 生成 · 离线可用（无外部请求）· 2026-11-05 17:27

报告与文档

周报

2026-W45 周报（2026-11-02 ~ 2026-11-08）

指标

按天

按领域

本周新增/更新笔记

本周新增产物

风险与异常

本周判断（人工）

下周计划（人工）

月报

2026-10 月度工作盘点（Codex + DSH，2026-10-06 ~ 2026-11-05）

1. 问题

2. 结论（先给答案）

3. 证据

3.1 总量表（分母写清）

3.2 来源结构（分母 256）

3.3 时间分布：两个尖峰日 + 一个集中产出周

3.4 模型与目录（分母 256）

3.5 DSH 侧（分母 55）

3.6 产物与仓库（可数产出）

3.7 6 个知识领域映射（分母 = 16 个 Task Group，粗归类，有判断成分）

4. 细节：这个月实际发生了什么

5. 未决 / 局限（按验证等级）

5.1 已验证（E2，可从 inventory.json 复现）

5.2 证据不足（已尝试，不能下结论）

5.3 未观察到（不是「没有」）

5.4 风险

6. 下月建议（按投入产出排序）

附录：交付物与复现

设计文档

一页纸总览（给 30 秒后的自己 / 新机器 / 新 agent）

全生命周期 SOP：捕获 → 脱敏 → 摘要 → 知识沉淀 → 发布 → 周报/月报 → 恢复

Workbench 仓库架构与协作契约 (v1)

数据分级、脱敏与保留策略

跨机器恢复手册（Codex + DSH）

知识条目写作规范（Authoring）

公开部署（Cloudflare Pages 推荐）

回报闭环：周报 / 月报 / 指标与复盘

业界经验（浓缩版）：哪些做法值得抄，哪些不值得

路线图（v1 → v2）

设计文档全文

一页纸总览（给 30 秒后的自己 / 新机器 / 新 agent）

这是什么

解决什么

五层与目录

五个原则

怎么读这个仓库

非目标（明确不做）

全生命周期 SOP：捕获 → 脱敏 → 摘要 → 知识沉淀 → 发布 → 周报/月报 → 恢复

0. 前置条件

1. 总流程

2. 阶段 1：捕获（Capture）

3. 阶段 2：脱敏（Scrub）

4. 阶段 3：摘要（Journal）

5. 阶段 4：知识沉淀（KB）

6. 阶段 5：产物库（Artifacts）

7. 阶段 6：发布（Site）

8. 阶段 7：周报 / 月报

9. 阶段 8：恢复（Restore）

10. 周期 Checklist

11. 失败处理总表

12. 完成定义（Definition of Done）

Workbench 仓库架构与协作契约 (v1)

0. 目标

1. 四层架构（对标数据湖 medallion + C4 的全局/细节分层）

2. 目录与职责（写作用域）

3. 知识层契约（kb/）

3.1 领域（固定 6 个，kb/index.json 注册）

3.2 笔记 frontmatter（YAML 子集，parser 只支持下面这些形态）

3.3 树结构 = 目录结构 + parent 字段

3.4 证据来源写法（sources）

4. 数据层契约（data/ 与 journal/）

4.1 原始数据分级（详见 docs/03-data-policy.md）

4.2 文件格式

4.3 脱敏（硬性要求）

5. 发布层契约（site/）

5.1 公开站（GitHub Pages）

6. 产物层契约（artifacts/）

5.1 已验证（E2，可从 `inventory.json` 复现）

3.1 领域（固定 6 个，`kb/index.json` 注册）

3.3 树结构 = 目录结构 + `parent` 字段

3.4 证据来源写法（`sources`）

4. 脱敏规则（`bin/scrub.py`）

2. 公开构建做了什么（`build_kb.py --public`）

五、精选引用（完整版见 `research/industry-practices.md`）