企业官网建设流程全解析

导读

PLANS.md是 OpenAlice 仓库中活跃多步骤实现工作的唯一索引：它回答"现在正在做什么、为什么这么做、如何验证、何时收尾"四件事，并与 docs/README.md 的 Owner Guides 体系、AGENTS.md 的启动规则、以及 Git 历史形成一套互相咬合的知识管理契约。读完本文，你将理解 OpenAlice 如何用"计划文件 + 所有者指南 + Git 归档"来组织跨子系统的复杂交付，掌握计划文件的写作契约、活跃计划的完整清单，以及通过 web-conversation-surface.md、bun-cli-distribution.md 等典型案例落地到源码的实现路径。

一、Plan Contract：计划文件的生命周期契约

PLANS.md开头即定义了计划文件的"合同条款"，这是整个体系的地基。核心规则如下：

创建条件：当一项工作横跨多个子系统（subsystems）、多个交付增量（delivery increments）或多个会话（sessions）时，就创建plans/<topic>.md。反过来说，单点小改动不应建计划文件。

内容强制项：每个计划必须声明以下字段——

• status：计划当前状态（active或进行中的阶段标记）；
• related issues：关联的 GitHub Issue（计划可协调 Issue，但不能替代 Issue）；
• owner guides：计划完成后将沉淀到的所有者指南（如[[docs/web-conversation-surface.md]]）；
• scope：目标与明确排除的边界（如"不在本计划内"清单）；
• decisions：关键决策与备选方案对比；
• ordered checklist：有序的增量检查清单（用[x]/[ ]反映仓库真实状态）；
• verification：验证手段（typecheck、测试命令、真实表面验收）；
• completion criteria：完成判定条件。

进度同步规则：进度更新必须与它所描述的工作在同一提交中完成；代码和所需验证尚不存在时，不得提前把步骤标记为完成。例如 web-conversation-surface.md 的 Work 清单中，所有已勾选项都对应已合入dev的实现，而"Credentialed live acceptance per runtime"仍保持未勾选状态，因为真实凭证环境验收尚未完成。

完成即删除（Completion is a deletion）：计划完成的标准动作是删除——在同一变更中删除plans/<topic>.md及其在PLANS.md中的 Active 条目，不保留 Completed 小节、墓碑条目或树上的plans/archive/目录。计划的"归档"由 Git 历史承担：

# 列出所有被删除的计划文件 git log --diff-filter=D --summary -- plans/ # 查看某个计划在被删除提交之前的内容 git show <deletion-commit>^:plans/<topic>.md

这条规则把"文档维护"从人工事务变成纯代码事务：计划的终点就是 Owner Guide 与代码合并后的稳态，任何留在树上的"已完成"条目都是过期的真值源。

Issue 边界：面向外部可见的缺陷和延迟发现（deferred findings）使用 GitHub Issues；计划可以协调这些 Issue，但不替代它们。这对应 AGENTS.md 中"具体延迟缺陷进 GitHub Issues，不创建仓库 TODO 文件"的规则。

二、Active 计划全景：当前正在推进的工作

截至当前仓库状态，PLANS.md登记了 17 个活跃计划，覆盖 UI 统一、CLI 分发、会话管理、连接器、产品体验五条主线。按主题分类如下：

更新与生命周期

• update-lifecycle.md：在 Runtime 启动时异步准备默认 Workspaces；在一个生命周期内扫描应用与 Workspace 的更新；在 Settings 中呈现可操作的更新指示，同时保留已审查的升级防护（operation guard、active-runtime 检查、clean merge、manifest 验证、事务恢复）。计划的四个序列步骤已全部完成。

CLI 与运行时

• bun-cli-distribution.md：用 Bun 编译的多进程 CLI 分发替换旧的 Node headless Runtime；curl/PowerShell、npm/Bun、Homebrew、AUR 四类渠道消费同一组已验收工件。该计划记录了完整的 0.91.1 发布旅程（见下文深度案例）。
• shell-first-cli-supervisor.md：交付一等公民的 Shell Supervisor TUI、Guardian 持有的持久 Runtime 生命周期、独立 headless 发布包、原子更新/回滚、真实 N-1 与 PTY 验收。增量 1–2 及 4/6/7 的大部分已在dev，剩余为 TypeScript CLI 转换、logs/Doctor/update UX、配置检查、注册表删除与发布门禁 N-1。
• tui-experience.md：以 Oh My Pi 为交互与完成度基准，把 Shell Supervisor 重建为支持鼠标的终端控制面，同时保留 Node CLI 与 Runtime 所有权边界。相关工作停留在codex/tui-usability分支等待集成验收，任何devPR 之前需完成。
• remote-project-fleet.md：增加机器感知的 Supervisor fleet、远程 AliceProject 清单/连接、安全的 local→SSH 项目迁移，刻意排除原生/OpenAlice Session 续接状态。已完成的 remote-readiness 增量让浏览器对远程身份、Agent 与 Broker Pack 能力、定时工作阻塞、重连恢复、公开 Session 标题呈现真实信息。

Web 会话与交互

• web-conversation-surface.md：把 WebPi 泛化为一个中立WebSessionHost，支持pi-rpc、acp、claude-stream-json、codex-app-server四种传输，一等权限请求与能力门控 UI（见下文深度案例）。
• unified-page-topbar.md：统一 UI 中的导航栏与内容工具栏，固定页面动作、内容拥有的侧栏恢复。目前在codex/ui-usability-followup上等待视觉验收。
• interaction-density-convergence.md：在dev基线之上，通过共享交互原语收敛字段焦点、compact-rail 展开、Connector 设置层级与高密度行情表面。

会话与产品状态

• session-presence.md：给产品 Session 增加桌内在职状态轴（active/archived/deleted），与 Workspace 的retired解耦；解除 Ask Alice 名册上限；把 Archive 变成侧栏主操作（见下文深度案例）。
• auto-prediction-harness.md：Auto Prediction Beta 对话 Harness 已进入dev；托管 AP/AQ Studio 监督、不透明路由、嵌入式产品表面已实现；共享 verified/unverified 源发布管理与跨运行时验收仍活跃。
• product-activity-journal.md：标准 append-only 产品活动日志，供 Office 与 Sonner 消费；Agent 运行时事实已上线，Inbox 与 per-item News 事实是当前增量。它始终是投影（projection），绝非分发总线（dispatch bus）。
• office-floor.md：Office 世界重建为单一连续 4:3 俯视 tilemap；Harness=功能街区、Workspace=家具舱、resumeId=员工。场景图、占位图、游戏 chrome、相机与浏览器验收仍活跃。
• issue-comment-prompt.md：可选的 per-IssuecommentPrompt模板，用于评论回复的 Input Prompts；缺省保留历史包装器，聊天桌会预填{comment}。

连接器与桌面

• connector-desk.md：桌面标本共享，每个desk适配器拥有自己的 Issue；增量 1 将telegramConnector泛化为connectorDesk: <id>，Feishu 适配器为后续增量。
• connector-inbox-commands.md：连接器声明inbox与settings能力并实现各自斜杠命令形式；Telegram 使用有界的/inbox摘要加按需文件拉取；Discord/Slack 保持占位；inboxPush可静默推送而不触碰电话桌（见下文深度案例）。
• telegram-connector-issue.md：每个 Alice Project 一个 Issue 即 Telegram 电话桌——heartbeat prompt 是提示词、评论即聊天、Connector 只负责传输；增量 1 把桌绑定进 Settings，增量 2 投影评论除非[[no-reply]]。
• desktop-companion.md：使用提供的艺术资产构建原生 Alice 伴生窗口，上游 press/drag/bubble 动效，macOS/Windows 验收。
• antigravity-adapter.md：Antigravity（agy）CliAdapter。约束明确：仅限 PATH 中的agy，绝不 spawnantigravity/gemini；从feat/agy-adapter串行出 PR，未获维护者许可不得合并。

每条 Active 条目的措辞都是"当前真值的快照"——它们会随每次提交被更新，这正是 Plan Contract 要求的"进度与工作同提交"。

三、深度案例一：从 WebPi 到统一 Web 会话面

web-conversation-surface.md 是理解"计划如何承载架构决策"的最佳范例。它的核心叙事是：

问题：WebPi 证明了浏览器内基于长连接结构化 CLI 进程的对话，在许多任务上优于 PTY。但它只是 Pi 的特例：宿主讲 Pi 的 RPC 协议、路由检查agent === 'pi'、UI 用同一个字面量门控所有能力。要让每个 Agent 运行时都能加入 Web 对话，需要新的结构。

备选方案与决策（该计划完整记录了三个方案）：

关键决策：

• 中立模型是"演示级"（presentation-grade）而非持久化存储；各运行时自己的 transcript 仍是持久对话，Alice 每个 Session 记录保持一个活进程。
• SessionRecord.surface: 'webpi'是已发布的持久值（0040 迁移）并保留，现在含义扩展为"任何 agent 的结构化 Web 对话"；HTTP 路径从/webpi/*迁移到/web/*（UI 与 server 同发，无兼容别名）。
• 适配器以capabilities.web = { wire }加composeWebCommand选择加入；UI 从/api/workspaces/agents读能力，不再用运行时 id 字面量决定 Web 按钮是否存在。
• 权限提示成为一等公民：传输层把 ACP 的session/request_permission、Claude 的can_use_tool控制请求、Codex 的item/*/requestApproval归一为带选项的中立请求；浏览器通过POST .../web/respond应答。Pi 与 omp 因 RPC 模式无 per-tool 提示，保留启动时批准（--approve/--auto-approve）。
• 新鲜 Web Session 允许带内建会话的运行时（ACPsession/new、Codexthread/start、Claude--session-id、omp fresh RPC）；传输报告原生 id，Alice 像 PTY 发现一样把它绑定到resumeId。
• agy 保持 TUI-only；Workspace Manager Quick Start 继续让 Pi 走 Web、其他运行时走 TUI。

该计划与源码严格对应：中立宿主实现在 src/workspaces/web-session-host.ts 的WebSessionHost类，四个传输、/web/*路由、权限卡片 UI 均已落地。验证部分同样扎实——用假子进程通过 stdio 驱动每种线的传输 spec；真实二进制冒烟测试使用了@earendil-works/pi-coding-agent0.85.1、opencode-ai1.18.29、@openai/codex0.153.4、@anthropic-ai/claude-code2.1.263（在一次性HOME下驱动WebSessionHost），逐条记录了握手、无凭证时的 auth 错误投影、OpenCode 免费模型的真实端到端回合，以及 Codex 请求/响应形状用codex app-server generate-json-schema校验而非凭记忆。随后的维护者运行时审计表记录了七种 Web 能力运行时（Claude、Codex、Cursor、Grok、OpenCode、OMP、Pi）各自的安装版本、实测证据与本轮修正，充分体现"进度与工作同提交"的纪律。

四、深度案例二：Bun 原生 CLI 分发与发布旅程

bun-cli-distribution.md 是仓库中最长、最详尽的计划之一，展示了计划文件如何承载跨发布周期的持续记录。核心内容：

动机与目标：OpenAlice 需要脱离桌面窗口、浏览器或终端独立存活。旧的 v0.90.1 CLI 依赖 TypeScript CLI、托管 Pi、宿主 Node launcher 和 107 MiB 压缩平台 Runtime，使 CLI 安装器同时"拥有"了 Node、Pi、构建工具检查和仓库形态的 Runtime 树。新分发要把所有权边界收缩到 OpenAlice 自身：发布的原生命令在无系统 Node.js、Bun 或 Git 的情况下运行，从任意目录启动 Guardian 持有的多进程 Runtime，启动用户自有的 Agent 可执行文件为独立 PTY 进程。

固定产品边界：CLI 分发包含openalice命令与 Supervisor TUI、Guardian/Alice/UTA Core/Connector Service 代码、编译后的 Web UI、默认资产、Workspace 模板、迁移与适配器胶水；绝不包含Pi/Codex/Claude Code/OpenCode/Cursor 等 Agent Runtime、Node/Bun/包管理器、Agent 凭证、可选 broker SDK 包或 Electron 资源。OpenAlice 只在 Session 启动后拥有 Agent 进程（进程创建、PTY 传输、环境注入、观察、停止、恢复），可执行文件的安装与版本归用户。

技术形态：每个平台构建产出一个 Bun standalone 可执行文件，通过内部角色重新执行而非复制 Bun 运行时：

openalice <user command> openalice --internal-role guardian openalice --internal-role alice openalice --internal-role uta openalice --internal-role connector

内部角色标志不是第二个公开命令 API；Guardian 用process.execPath以选定角色派生子进程，每次调用是独立的 OS 进程。进程拓扑保持现状：openalice → Guardian → Alice → 每 Agent Session 一个独立 PTY 进程，UTA 与 Connector 可选。

分发拓扑：一份已验收的版本化平台工件被所有渠道消费：

Bun compile matrix -> signed/checksummed platform archives + release.json -> Bash installer (curl ... | bash) -> PowerShell installer -> npm platform packages -> npm meta package -> Bun global install of the same meta package -> Homebrew formula -> AUR `-bin` package

渠道所有权矩阵是计划中极具操作价值的表格：哪个渠道安装的命令就由哪个渠道负责更新与卸载——Bash/PowerShell 归 OpenAlice 安装器事务，npm 归 npm，Bun 归 Bun 包管理器，Homebrew 归 Homebrew，AUR/paru 归 pacman 兼容管理器。openalice update可以为所有渠道发现并解释新版本，但只对直接安装执行自更新；包管理器安装的实例在明确同意后显示或执行管理器所属命令，绝不越过包管理器复制到自己管理的目录。

发布旅程实录：计划从可行性门禁（Bun 编译、四角色重执行、独立 PTY 隔离、broker pack 动态加载、嵌入资源读取、性能测量）一路记录到 0.91.1 稳定发布——包括 npm 全局升级时 promise-retry 依赖自解析失败的隔离修复（固定 npm 12.0.2 于RUNNER_TEMP）、npm 12 单例数组 JSON 响应的解析修复、AUR pacman 依赖下载的 Landlock 沙箱例外、Intel 签名时间戳失败不放松签名门禁等真实事故与修复。计划还包含平台包/元包拓扑、Windows x64/ARM64 独立预览增量、以及"候选构建失败后可复用已保存工件重放验收"的机制（candidate-run）。这些内容说明：一份合格的计划文件不是愿望清单，而是发布过程的完整审计日志。

五、深度案例三：Session 桌内在职状态轴

session-presence.md 展示了计划如何处理已发布持久数据形态的兼容性问题。背景是：Ask Alice/Quant 名册上的"删"不应拆掉 TUI 座位，也不应从世界上抹掉一个人。员工（resumeId）在桌内应有三档在职状态：

现有lifecycle: retired保持原意——整桌 offboard 时人跟桌子一起走，不拿它当归档。

为什么不开拓lifecycle字段：resume-identities.json已随 0.89.2+ 发布，lifecycle只有active | retired。若把archived/deleted塞进同一字段：旧解析器会把未知值当成active（=== 'retired' ? retired : active），且recallWorkspace会把归档/软删一律拉回在职。因此拆出第二轴，缺省即在职，旧文件无需 migration：

lifecycle: 'active' | 'retired' // 桌：在岗 / 跟桌走了（已发布） presence: 'active' | 'archived' | 'deleted' // 人：在职 / 归档 / 软删（新，缺省 active）

名册一行显示条件：lifecycle === 'active' && (presence ?? 'active') === 'active'。

产品规则矩阵是该计划的精华：归档后侧栏不显示但 Browse 的 Archived 筛可见、可 Restore；软删后不进 Browse、不可新指派、不可 headless/ensure；已指派的@resumeId再跑时归档仍 exact、软删则报deleted-session；正在占班（TUI 或 headless 运行中）时 Archive/Delete 均锁定；DELETE /sessions/:sid只停止实时进程并把 presence 置为deleted，只有 Workspace purge 才物理清除记录；真物理删除不存在——产物、Inbox、run 历史、resumeId署名全部保留。

API 形态：ResumeRegistry.setPresence({ resumeId, presence, now })（retired身份拒绝改 presence）；PATCH /api/workspaces/:id/resumes/:resumeId携带{ presence }，对 running/retired/非法迁移（如deleted → active必须先 undelete）返回 409。增量 1 已去掉侧栏截断（FOCUSED_CHAT_SESSION_LIMIT、CHAT_SIDEBAR_SESSION_LIMIT、ALL_WORKSPACES_SESSION_LIMIT）与行内 Browse，增量 2 落地 presence + Archive，增量 3 完成 soft-delete/undelete。对应的真实实现位于 src/workspaces/resume-registry.ts 及其 测试。

六、深度案例四：连接器 Inbox 拉取与设置表单

connector-inbox-commands.md 展示了"增量 2 进行中"的计划形态。目标：让桌主能关掉嘈杂的 Inbox 推送、想看时再看。核心决策：

• 目录能力capabilities: ['inbox', 'settings']加斜杠命令元数据，不共享回复/按钮渲染器；
• 每适配器独立inboxPush（默认开），电话桌sendOwnerText保持开启；
• Telegram：内联键盘表单，/inbox在一则消息内分页未读项，/settings是单一开关按钮；
• Discord：同命令占位回复；Slack：workspace 安装的 Socket Mode 应用、仅 owner DM，同样占位；
• Connector 直接从OPENALICE_HOME读 InboxStore 文件（Electron 下无需 Alice HTTP），Connector 永不读 Workspace 文件；
• 按需文件拉取使用有界 Connector 动作队列与 Alice 动作桥，而非电话桌的 inbound drain；定向工件投递是独立控制面调用，普通 Inboxdeliver无法重发摘要；Alice 复用projectInboxDoc与现有附件安全路径，只信任entryId+docIndex。

增量 2 的具体约束也值得注意：Telegram/inbox摘要限 5 项、字段预算、整页硬上限低于TELEGRAM_PLAIN_TEXT_MAX、不展开文档路径；"view files / confirm / cancel"流程有界且需 owner 复检。该计划明确写出"不在本计划内"：Discord/Slack 交互式文件拉取、从连接器标记 Inbox 已读、为普通 Issues 改变inbox_push。对应的服务实现位于 services/connector/src 与 src/core/inbox-files.ts。

七、计划体系与文档生态的协同

理解PLANS.md必须同时理解它与三层文档的关系：

1. PLANS.md ↔ Owner Guides（docs/README.md）：计划描述"仓库真值将如何变化"，Owner Guide 描述"变化之后的持久真值"。计划完成即删除，稳定下来的架构结论迁入对应 Owner Guide。例如 web-conversation-surface 计划的持久结论沉淀在 docs/web-conversation-surface.md（结构化协议浏览器会话：线、传输、中立快照、权限请求、路由）；session-presence 的结论指向 docs/workspace-lifecycle.md 与 docs/conversation-provenance.md；bun-cli-distribution 指向 docs/cli-installer.md、docs/cli-package-managers.md、docs/local-runtime.md、docs/managed-workspace-runtime.md。

2. PLANS.md ↔ AGENTS.md：AGENTS.md明确写道"active multi-step work lives in [[PLANS.md]]"，并规定"Substantial multi-session work uses one canonicalplans/<topic>.mdentry"。同时禁止把 Owner Guide 内容抄回AGENTS.md——那是索引与紧凑规则集，详细规则进 Owner Guide。

3. 计划 ↔ Git 历史：计划的档案就是 Git。完成删除 +git log --diff-filter=D --summary -- plans/恢复的机制，让"文档归档"零维护成本，且永远保留决策过程的审计线索。

4. 计划 ↔ 源码/测试：每个计划的可勾选项都应当能在源码中找到落点。例如 web-conversation-surface 的中立宿主对应 src/workspaces/web-session-host.ts，迁移 0040 对应 src/migrations/0040_unified_session_records；计划中的验证命令（npx tsc --noEmit、pnpm test、cd ui && npx tsc -b、演示路由pnpm -F open-alice-ui dev:demo）与 AGENTS.md 的验证阶梯完全一致。

5. 计划 ↔ 交付流程：docs/development-workflow.md 定义了dev为常规集成通道、master为发布源、serial 与 autonomous 两种交付模式；计划的 Delivery 字段（如"serial PR todev(area:workspace)"）与 PR 标签体系（theme:*、area:*、review:deep）呼应。计划文件因此成为"交付权威"决策的落点：feature-branch iteration hold、autonomous topic PR 的接受边界都在计划中显式记录。

八、读者视角：如何正确消费计划文件

对于想理解 OpenAlice 当前技术走向的读者，PLANS.md是最佳入口，建议按以下顺序阅读：

1. 读PLANS.md的 Plan Contract，理解"计划 = 可变真值、Owner Guide = 稳定真值、Git = 归档"的三层模型；
2. 扫一遍 Active 列表，按自己关心的领域（CLI 分发、Web 会话、连接器、UI、会话生命周期）定位计划；
3. 进入具体计划文件，优先看 Goal（一句话目标）、Decisions（含备选方案对比表）、Work 清单（[x]/[ ]即当前进度）、Verification（可复现的验收手段）；
4. 顺着 Owner guides 字段跳转到 docs/README.md 对应指南，那里是已经稳定下来的持久架构真相；
5. 回到源码验证：计划的每个勾选项都应有对应实现与测试，例如 web-session-host.ts、resume-registry.ts、src/migrations/0040_unified_session_records。

需要留意的是，计划文件的措辞高度精炼且状态实时变化：某个勾选项今天为[ ]，明天可能随提交变为[x]；某个计划被删除只意味着它已完成并迁入 Owner Guide，而不是工作消失。以当前仓库内容为准，是消费这类文件的基本原则。