企业官网建设流程全解析

PuppyOne（puppyone）是一款本地优先（Local-first）的 AI 编辑器，官方定位是 "Context drive for your AI agents"——为你和你的 AI Agent 打造的上下文工作空间。它内置项目模板与一套极简的Onboarding 引导流程：从全新空项目到接入 AI Agent 处理文件，全程免费、无需注册账号即可完成。本教程将带你用几分钟上手 puppyone，快速创建第一个 AI 开发项目，并了解项目模板、文件夹导入和 Agent 协作的核心玩法。

一分钟认识 PuppyOne：AI 开发项目长什么样

PuppyOne 把"项目"定义为电脑上的一个普通文件夹：你在这里编辑 Markdown、CSV、JSON、PDF、DOCX、XLSX、媒体和 3D 文件，左侧是文件列表，右侧可以打开 Agent 面板，让 Codex、Claude Code、Cursor、OpenCode 等本地或云端 Agent 直接读写你的项目文件。

核心特性一览：

快速安装：两条命令启动 puppyone

安装只需要 Node.js 环境和两条命令，完全免费：

npm install --global puppyone

然后运行：

puppyone

启动后你会看到 Onboarding 首页。整个首页的交互逻辑（按钮、拖拽、最近项目列表）都实现在这组组件里：src/components/onboarding/，中文文案见 onboarding.json。

Onboarding 首页：3 个入口决定你怎么开始

首页围绕一个问题设计——"你想从哪个项目开始？"。界面上有三个核心入口，按推荐优先级排列（源码见 OnboardingEntryActions.tsx）：

1. 🆕 新建空项目（默认推荐路径）——不需要任何已有文件，点击即建
2. 📂 打开文件夹——把已有的文件夹（包括 Obsidian 知识库）直接作为项目打开
3. ⬇️ 导入——从 Notion、Obsidian、Airtable、Google Drive 或 Git 仓库导入

💡 设计意图：新建空项目是唯一"不要求你先找到一个已有文件夹"的入口，所以它是 Onboarding 的默认路径。

下方还会列出最近打开的本地项目，点击即可回到上次的工作现场；点击移除按钮只会删除注册记录，不会删除本地文件（见 OnboardingProjectList.tsx）。

一键创建项目：内置模板如何工作

点击"新建空项目"后，会弹出新建项目对话框：

• 项目名称：已预填"我的项目 + 随机后缀"，可直接改
• 位置：已预填内置的项目文件夹，无需手动选择
• 点击"创建项目"——一次点击完成创建并自动打开

这个对话框的实现见 OnboardingProjectEntryDialog.tsx。

每个新项目都自带"Getting Started"模板

项目并不是真正"空"的：每个新项目都会自动注入一份内置的Getting Started.md引导文件（模板 ID：puppyone.project.getting-started）。它告诉新用户在项目里做第一次编辑、如何加入文件、如何调用 Agent。

• 中文模板源文件：getting-started.md
• 模板清单（含 8 种语言与内容校验摘要）：getting-started.manifest.json
• 模板解析与校验逻辑：project-catalog.mjs

模板按你选择的界面语言自动匹配：支持zh-Hans、en、ja、ko、de、es、fr、pt-BR共 8 种语言（见 local-api/templates/content/）。

项目名的 3 条规则（避免创建失败）

创建服务会校验项目名（project-entry-service.mjs）：

1. 长度不超过120 个字符
2. 不能包含/ \ : * ?等分隔符或保留字符，不能以.或空格结尾
3. 不能是 Windows 保留名（如con、nul）

实际的文件落盘由 project-initialization-service.mjs 以"暂存目录 + 提交日志"的方式原子化写入：即使中途出错，也不会留下半个项目目录。

工作区模板：30 秒生成一套 Slides 演示文件

除了项目级模板，PuppyOne 还支持工作区级模板。目前内置 Slides 模板（slides.default）：在项目内一键生成一个完整的演示文件夹，包含.puppyoneapp入口文件、index.html、样式与脚本、以及打包的 Geist 字体，可以直接在应用内翻页演示。

• 模板实例化逻辑：workspace-templates.mjs
• 文件物化（staging 与发布）：materialize.mjs

重名时会自动追加2、3等后缀，不会覆盖已有文件夹。

打开已有文件夹与多应用导入

如果你已有内容，不必从零开始。Onboarding 提供了几种"把别处的内容变成本地项目"的快捷方式（中文引导文案见 onboarding.json）：

Git 克隆走的是带临时目录 + 原子的 cloneRepository 流程，失败会自动清理临时文件；URL 只接受github.com/gitlab.com的 HTTPS 或 SSH 地址（requireGitRepository）。所有工作区的"打开/创建/克隆"统一由 workspaceOpening.ts 转发到主进程执行。

与 AI Agent 协作：项目就是 Agent 的上下文

项目建好后，在Agent 面板或设置中选择一个 Agent（Codex、Claude Code、Cursor、OpenCode 等）并配置好模型，就可以直接下达指令，例如：

"帮我把上面的项目想法整理成一份简短计划。"

Agent 会读取你的文件、提出修改，你可以在保留改动前先逐条审查——这是 puppyone 作为 "Context drive" 的核心价值：文件即上下文。

一个典型场景：把 CSV 表格交给 Agent 分析并生成报告。

⚠️ 两点提示：创建项目不会自动启动 Agent、执行命令或上传文件；如果选择云端模型，发送给 Agent 的内容会由对应模型服务商处理。

可选进阶：连接 PuppyOne Cloud

云端功能完全可选。登录后可创建云端项目、备份本地工作区并邀请队友协作；不登录则一切照常，本地体验不受影响。

云端初始化与发布的实现入口在 electron/main/cloud-initialization/ 与 cloud-api-client.mjs。

上手清单：你的第一步行动

1. ✅ 执行npm install --global puppyone并运行puppyone
2. ✅ 点击"新建空项目"，一次点击创建项目
3. ✅ 打开自带的Getting Started.md，完成第一次编辑并保存
4. ✅ 拖入你的第一个文件或 CSV
5. ✅ 配置一个 Agent，让它整理你的第一份笔记
6. ⭐ 进阶：试试 Slides 模板、导入 Notion/Obsidian 内容、连接 Cloud

更多架构与文档资料可浏览仓库中的 archive/legacy-desktop-docs/（历史文档存档）与 README.md。从第一个项目开始，让 PuppyOne 成为你和 AI Agent 共享的上下文引擎 🚀