状态：生效更新：2026-10-06

PLAN：workspace 项目知识库

本文拆解专项 PRD，规定执行容量、任务验收、依赖与发布门槛。需求以 PRD 为准，技术约定写入PROJECT ，工程要求沿用AGENTS 。任务的派发、阻塞与完成状态只维护在BACKLOG 。计划生效不代表任务已执行，也不构成功能验收。

本期为内部开发知识库，在现有 frontend 接入 Nextra，网页编辑采用 Editor.js 与 Markdown 原文视图，不采用 GitBook。保留 Nextra 的编译、公开预览与既有工具，内部入口与公开产物分别管理；保留 Markdown、Obsidian 与校验、快照工具。Notion 是尚未采用的替代来源，不能与文件同时主写。估算仍是初值，方案任务须核对框架接入和格式适配工作量，超出容量则调整候选排期。

执行节奏与容量

本人指定全天覆盖、每隔 2 小时推进一次，每天按 12 个窗口估算；实际触发时点以当前任务的 heartbeat 配置为准。一个 Sprint 暂定 14 个自然日，从实际启动时计时，不预填上线日期。

理想小时指专注实现、审查修改和必要校验的工作量，不包含等待登录、批准或机器恢复。任务表的估算已经包含这些工程活动，不另把审查时间当作免费容量。Codex 负责实现和检查；Claude 负责规格审查与真实验收；Stephen 负责身份、环境和发布决定。后二者的可用时段未确认，不能按全天在线估算。

前 12 个窗口收集有效运行分钟、完成的验收项、返工与等待原因，校准每窗口净工作量。若仅有 6 个窗口各完成 1 小时净工作，则未来毛容量按 84 小时重算，缓冲 17 小时，任务上限 67 小时；优先保留阅读阶段，将 AI 阶段顺延。满 3 个 Sprint 后再用实际速度辅助估算，不以运行次数或生成代码行数代替完成量。

每轮如何推进

1. 从 BACKLOG 恢复当前任务，核对来源版本、未完成验收项及工作目录中的其他修改；先判断上一轮是否仍在运行。
2. 已有任务在运行时不启动第二个写入任务；上轮结果未知时先核对结果。无任务运行时，选择一个已满足准入条件的最高优先任务。
3. 本轮推进一项明确的实现或验证工作；任务超过一轮时，下轮从检查点续做，不另复制任务。
4. 在当前任务上下文留下修改文件、命令结果、验收证据、剩余事项和下一动作，BACKLOG 记录当前任务及阻塞；正式验收写入 records。工程检查与真实验收分别记录，凭据不进入记录。
5. 需要本人登录、身份配置、发布确认或解除限流时，在 BACKLOG 写明条件与负责人；只继续不依赖该条件的任务。没有可推进事项时，后续轮次等待状态变化。

周期执行应使用当前任务的 heartbeat，避免每轮创建新聊天。调度配置、主机持续可用及运行结果需在启动时核验；配置和运行状态见 BACKLOG。只在完成、失败、需要本人操作或有其他实质变化时通知，状态未变不重复通知。周期运行本身不授予提交、推送或文档发布权限。

准入与完成标准

可派发条件（Definition of Ready）：任务有明确范围、可复核的验收条件、估算、实现及验收负责人；前置产物已验收；所需配置和环境可以取得；不存在未解决的设计或外部阻塞。后续任务即使有估算，前置未完成时也只列为候选，不能计作已承诺任务。

工程完成：按改动范围通过 AGENTS 的后端、前端、契约、数据库、文档检查，完成审查。接口先由 backend 生成 OpenAPI，再生成 frontend 客户端；不手改生成文件。涉及数据库的测试只用独立测试库。

阶段可用：用真实资料、身份和目标环境通过对应 PRD KR，按验收记录模板 留下版本、环境、样本、通过项、失败项与未验证项。方案收敛任务先建立项目知识库的能力文档，验收记录的 capability 指向它；业务知识库的能力状态不受本专项替代。失败的 KR 修复并复测后才过门槛，不从样本中删除失败项。

首个 Sprint：可信阅读与 AI 检索

Sprint Goal：让本人和本机 Codex 在统一访问规则下，从工作台与授权原文入口找到同一版本的项目资料，并能核对答案依据。

• 周期：2 周，全天每 2 小时推进一轮。
• 毛容量：168 理想小时；缓冲 34 小时；选入上限 134 小时。
• 可直接派发的启动包：文档工具修复、方案收敛，共 16 小时；派发状态见 BACKLOG。
• 后续候选：112 小时，按前置完成情况滚动选入；全部选入合计 128 小时，仍留 6 小时未分配容量，另有 34 小时缓冲。
• 顺序：先完成阅读阶段并通过 KR1、KR2，再完成 AI 阶段。外部条件延迟时，保留已验收的阅读成果，AI 阶段顺延，不降低验收门槛。

文档工具修复

交付可重复运行的文档校验与构建工具。缺失脚本与测试已在工具修复中补齐，证据与审查状态见 BACKLOG；继续以当前 checkout 的复跑结果为准。保留元数据、索引、链接和路径校验，新增内部不可变快照生成，继续使用 Nextra。

验收：pnpm index、pnpm check、pnpm build 在 workspace 成功；二次生成索引无差异；plan 类型、product/prd/ 与 product/plan/ 嵌套目录、执行计划模板 及相关元数据被校验与索引正确识别，需求和计划分组显示；普通 Markdown、中文路径、根文件指针、相对链接、锚点正常；模板、看板和本机配置不发布。公开预览仍按公开清单构建，内部快照单独生成，不增加私密资料的公开产物；CI 持续执行文档校验，不依赖 Pages 发布。

方案收敛

交付真实代码核对结果与最小技术方案，写入 PROJECT：文档归属与接口位置、身份允许清单、版本标识、快照打包或挂载方式、缓存边界及后续草稿和 Git 写入的宿主位置。优先复用现有 identity、渲染器和流程，按实际使用方组织代码；不用空模块或第二套账号。

明确 Nextra 的应用内复用与公开预览隔离，保留现有校验 CI。用五类文档验证 Nextra 在现有布局内的导航、目录、主题和授权数据适配，以及 Editor.js 与 Markdown 往返；保留现有解析与清理工具，不另建 CMS。按目录区分 PRD、决策、架构、PLAN、进度与验收，决策修订沿用本人同意和旧记录保留规则。

验收：列清复用项与缺口；读写、发布权限分开；缺少身份配置默认拒绝；根文件原文与指针映射明确；目标环境与负责人明确，未配置项列回 BACKLOG，不假定已经可用。建立项目知识库能力文档，引用专项 PRD KR，避免重复复制需求。技术方案可完成，但后续真实连接仍依赖本人提供环境及身份。

来源清单与版本快照

交付登记文档及附件的清单、原文映射、正文 hash 与可复建快照。重新统计全部来源，不硬编码 PRD 中的旧候选数量；清单覆盖生效规格、进度、架构、工程规范、记录与调研。模板、看板、本机配置及未发布草稿排除，废弃资料在历史模式标明状态。

验收：BACKLOG、PROJECT、AGENTS 只有一个可编辑原文；网页指针和离线只读快照定位到正确源路径；清单、正文、附件和索引携带同一快照标识。快照保存来源 Git revision、文件 hash；源码有未提交修改时标为工作草稿，不能冒充该 revision 的已发布内容。模拟损坏链接、越界路径和缺失附件时校验失败；从清单重建得到一致内容。私密来源不经过公共静态站。

统一权限与读取接口

交付服务端目录、正文、附件与授权原文读取契约，frontend 使用同版本生成客户端。只接受登记路径，规范化和真实路径核对同时防止路径穿越与符号链接越界；详情返回类型、状态、更新时间、源路径、正文 hash 与快照标识。

验收：授权本人能读取；匿名、已登录但未允许、会话过期、缺配置、身份服务故障均按约定拒绝或暂不可用。所有出口包括标题、摘要、附件地址、下载和缓存均无受保护内容泄露；禁止以用户可猜测的静态 URL 绕过接口。保持现有业务 /llms.txt、/mcp 与公开索引边界。权限测试与 OpenAPI 生成检查通过，真实身份场景在目标环境任务复核。

工作台阅读界面

交付 /workspace/docs 列表和详情，在 BasicLayout 内组合 Nextra 编译与文档组件；显示类型、来源、状态和版本，提供分类、目录及 PRD、决策、PLAN、验收关联。将授权 API 目录组织为按类型分类的文档导航，搜索使用生成客户端；不默认开放框架的另一个搜索端点或全量静态索引。受控正文保留 Markdown，不经有损块转换。

继续保留 Nextra/theme、公开预览、Pagefind、静态导出、专用补丁与现有 Pages 工作流；不安装 Fumadocs。frontend 只引入 Nextra 编译能力，不挂载第二个全局 Layout。内部资料不进入公开静态产物，校验和内部快照测试共同保留。

验收：登记文档的正文、表格、代码、图片、注释、中文路径、链接、章节与根文件正确；相关资料来自同一快照，文档生效与实现完成分开。桌面、390px、键盘下五种状态可用；框架主题不覆盖全局布局，严格 CSP 下不执行作者脚本。适用前端检查通过，KR1、KR2 在目标环境复核。

Obsidian 离线阅读

交付独立文档工作副本与使用说明；普通相对 Markdown 链接不依赖网页才能阅读。本期完成离线阅读，双端编辑的自动汇合在后续 Sprint 验收。

验收：实际 Obsidian 打开五类文档，中文路径、附件和相关链接正确；根文件可从工作副本打开，或展示带版本、源路径且不能独立编辑的快照。工作副本不提交现有开发 checkout 中其他代码改动；断网后仍可读，更新快照后版本可核对。

目标环境读取验证

交付本机启动方式和阅读阶段验收记录。用已批准环境验证文档快照可被 backend 读取，frontend 能访问服务端接口；启动步骤通过明确的工具根、来源根和持久目录配置，也不能依赖独立文档网站或 8668 预览进程。

验收：冷启动、重启与前一版本恢复后，目录、正文、附件和版本一致；快照不存在或损坏时明确失败，不能展示混合版本。真实授权与未授权身份覆盖所有读取出口、缓存及退出后的回看；桌面、窄屏及键盘检查完成。KR1、KR2 达成并留下记录后，阅读阶段可交付；没有目标环境时仅记录本地工程结果。

中文检索

交付受相同权限约束的关键词、元数据与别名检索，先用当前资料规模可复建的本地索引。页面显示命中资料、摘要、状态与版本；默认不把草稿和废弃规则当当前依据。

验收：实现前冻结 20 条查询及预期文档，覆盖中文、代码标识符、别名、进度与权限；至少 18 条在前 5 个结果命中预期资料。查询、片段和详情属于同一快照；索引更新中不能返回另一版本正文。未授权响应无标题和片段；保留失败原因及结果，不用改题提高得分。未达到 KR3 时先修排序与别名，缓冲不自动转为向量数据库项目。

AI 原文读取与引用

交付项目命名空间中的授权目录、原始 Markdown / 章节读取和版本引用规范，供本机 Codex 按需读取。本机可直接读取文档副本；线上读取走既有访问策略，不把受保护全文挂到公共静态路径。

验收：可从问题定位文档，再取必要正文，引用能够回到同版本原文及章节；本机工作草稿显式标为草稿。目标、规则、实现与验收来源可区分，冲突保留双方依据，无依据时说明资料不足。llms.txt 或目录存在不算自动接入成功，必须用真实本机 Codex 走通；远程 MCP 客户端不作为这项前置。

阅读与 AI 验收

交付可复核样本和联合验收记录。复核阅读 KR1、KR2 与检索 KR3；冻结 20 个实际项目问题及判断依据，再用真实本机 Codex 完成 KR4。

验收：20 题至少 18 题正确，实质性规则与现状结论的引用全部可打开；至少 4 道草稿、废弃规则、资料冲突、资料不足边界题全部正确。记录每题答案、期望、来源版本及失败原因；工程模拟与真实客户端结果分别列出。完成后同步能力、BACKLOG 和记录索引。只有读取验收达成，不能宣称网页与 Obsidian 双端编辑已交付。

后续 Sprint：双端修改安全汇合

Sprint Goal：让网页与 Obsidian 的修改安全回到同一 Markdown 来源，遇到冲突或发布异常时保留可恢复内容。

阅读与 AI 阶段通过后启动，周期暂按 2 周。沿用校准后的容量和 20% 缓冲；按当前初值，候选 116 小时，低于 134 小时上限，余 18 小时未分配。本阶段当前全部是候选；写入存储、独立 Git 工作副本与发布环境在设计验收后才可成为承诺。前一阶段延期时同步顺延，不并行绕过前置。

编辑与同步设计

交付 PROJECT 中的草稿存储、文档专用 Git 工作副本、保存与发布状态、历史恢复方案。本机 API 使用受保护持久目录及独立 Git 副本，服务重启不会删除草稿；沿用现有可靠性机制，不另建无使用必要的队列或记录系统。

验收：网页、Obsidian、原文和快照的职责明确；路径、前置版本、发布与结果核对可执行。定义 Editor.js 块与原文映射、未知语法保留和视图切换；决策修订由本人同意，旧记录废弃、新记录替代及关联一起校验，不覆盖生效规则。

草稿接口

交付读取、保存和恢复 Markdown 草稿的契约，保存携带文档来源版本或 hash，写操作校验会话、允许清单和 CSRF；指针页保存定位到根文件原文。

验收：保存成功不改变发布快照；服务重启后草稿仍在，超时或失败能重新读取核对；重复保存不产生重复副作用。错误使用稳定 code 与 HTTP 状态，frontmatter 和正文按作者格式保留，损坏字段或越界路径拒绝并保留编辑内容。

Markdown 编辑界面

交付 Editor.js 富文本视图、Markdown 原文视图、元数据编辑、同策略预览、草稿和差异入口；两种视图共用草稿与源版本。块 JSON 只用于视图与草稿，发布回写 Markdown；未改区域保持原样，未知 YAML、注释及未支持语法保留为原文，根文件定位到唯一来源。

验收：五种状态、键盘、窄屏、中文输入法可用；视图切换不丢内容，未改文件字节不变，代码语言、Mermaid、表格对齐、链接与元数据保留。离开未保存页面有提示，草稿与发布状态分开；冲突和网络失败后内容可恢复，不自动重试写请求。

确认发布

交付确认后的文档校验、允许范围 Git 修改、快照生成与切换；记录操作、前置版本、结果版本和失败原因。只处理本次选中的文档与所需产物，不提交开发目录的其他变更。

验收：重复确认不重复发布；再次验证来源版本、字段、链接、附件、索引及决策替代关系，所有读取出口切到同一快照。失败保留上一版本和草稿，中断或响应丢失可查操作结果，不盲目重试。真实远端推送按本人授权执行，本机流程不等于远端验收。

版本冲突处理

交付网页与来源版本的冲突识别、双方差异和人工合并。保存与发布两个时点均检查前置版本，避免保存后来源变化仍直接发布。

验收：两个网页同时修改、Obsidian 在网页保存后修改、过期 base、重复提交、发布中崩溃与超时结果未知均保留内容；合并后的新版本再次校验。逐项保留操作与差异，静默覆盖为 0；不以强制覆盖或自动选择较新时间解决冲突。

Obsidian 双端同步

交付文档专用工作副本的更新、提交校验、确认同步和冲突说明。复用同一允许路径与快照发布流程，网页修改与本地修改最终进入同一 Git 来源。

验收：在实际 Obsidian 中，PRD、能力、决策、调研、根文件五组样本各完成网页到本地和本地到网页，共 10 条往返路径。链接、附件引用、YAML 字段及正文无非预期丢失；根文件修改回到唯一原文，生成快照不成为第二个作者来源。并发场景转入冲突处理，工作副本不夹带业务代码变更。

历史恢复

交付来源历史与指定已知版本恢复，恢复作为新的可确认修改，保留既有 Git 历史和发布操作依据。

验收：恢复前显示差异和目标版本；恢复后所有读取出口一致，可继续编辑；未确认草稿不因恢复丢失。记录恢复前后版本与原因，不通过改写共享历史实现回滚。

编辑验收

交付 KR5、KR6 的真实往返与异常验证记录。使用前述五组样本和同时修改、重复保存、过期版本、发布失败、结果未知场景复核；正常案例通过不能替代失败恢复验证。

验收：10 条往返均无非预期丢失，全部冲突与异常都有可恢复内容，静默覆盖为 0；重启后的草稿、操作结果与快照一致。网页、真实 Obsidian 与已批准发布环境证据齐备后才更新能力状态为可用；未验证的远端环境单列，不声称全部可用。

依赖与发布门槛

关键路径是“工具与方案 → 来源快照 → 统一权限及接口 → 工作台阅读 → 目标环境 KR1/KR2 → 检索和 AI 原文 → KR3/KR4 → 编辑设计与草稿 → 确认发布及冲突 → 双端与恢复 → KR5/KR6”。单执行者按顺序推进；Obsidian 离线说明等独立工作可在外部等待期间插入，但不因此解除阶段门槛。

风险与调整规则

范围调整先减少尚未准入的候选，再移动 AI 或编辑阶段，不能删权限、冲突恢复或真实验收来赶工。每个 Sprint 结束记录实际容量、任务耗时、失败与等待原因，用于下一轮估算；任务状态仍只更新 BACKLOG。

远程只读 MCP 在出现具体客户端需求后单独估算、验收认证与检索兼容，不占本次承诺容量。向量数据库、付费云模型、多人协作和业务公开分发不随本计划启动。