https://www.puppyone.ai/_next/static/chunks/5518.544b6eea353d8bf8.js

1"use strict";(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[5518],{10798:function(e,n,s){s.d(n,{a:function(){return c}});function c(e){return e}},5518:function(e,n,s){s.r(n),s.d(n,{default:function(){return r}});var c=s(57437),l=s(10798);function d(e){let n={blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,l.a)(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(n.h1,{children:"本地文件夹同步"}),"\n",(0,c.jsx)(n.p,{children:"将本地文件夹与 puppyone 云端 Context File System 同步，使用 MUT 协议进行版本控制。"}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"什么是本地文件夹同步"}),"\n",(0,c.jsx)(n.p,{children:"本地文件夹同步基于 MUT 协议（类似 Git 的版本控制协议），在你的本地目录和 puppyone 云端之间建立版本化的同步通道。"}),"\n",(0,c.jsxs)(n.ul,{children:["\n",(0,c.jsxs)(n.li,{children:["本地编辑文件后，",(0,c.jsx)(n.code,{children:"mut commit"})," + ",(0,c.jsx)(n.code,{children:"mut push"})," 推送到云端"]}),"\n",(0,c.jsxs)(n.li,{children:["云端有变更时，",(0,c.jsx)(n.code,{children:"mut pull"})," 拉取到本地"]}),"\n",(0,c.jsx)(n.li,{children:"每次推送都生成版本记录，可回溯、可回滚"}),"\n"]}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{children:"┌──────────────┐                            ┌──────────────────┐\n│              │  ── mut push ────────────→  │                  │\n│  本地文件夹   │                             │  puppyone Cloud  │\n│  ~/my-docs   │  ←── mut pull ───────────   │  Context FS      │\n│              │                             │                  │\n└──────────────┘      版本控制 (MUT)          └──────────────────┘\n"})}),"\n",(0,c.jsx)(n.p,{children:"同步完成后，Agent、MCP 客户端（Cursor / Claude Desktop）和 REST API 都可以访问这些内容。"}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"快速开始"}),"\n",(0,c.jsx)(n.h3,{children:"前置条件"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"npm install -g puppyone    # puppyone CLI\npip install mutai          # MUT CLI\n"})}),"\n",(0,c.jsx)(n.h3,{children:"第一步：创建同步连接"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:'puppyone auth login\npuppyone project use "My Project"\npuppyone access add filesystem docs\n'})}),"\n",(0,c.jsx)(n.p,{children:"命令会输出 access endpoint URL 和 Access Key，并提示两种接入方式。"}),"\n",(0,c.jsx)(n.h3,{children:"第二步：选一种接入方式"}),"\n",(0,c.jsxs)(n.p,{children:["接下来有两条路：",(0,c.jsx)(n.strong,{children:"Clone 全新文件夹"})," 还是 ",(0,c.jsx)(n.strong,{children:"接入已有文件夹"}),"。挑你的实际场景。"]}),"\n",(0,c.jsx)(n.h4,{children:"A. Clone 全新文件夹（本地还没有文件）"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"mut clone <endpoint-url> --credential <access-key>\ncd docs\n"})}),"\n",(0,c.jsxs)(n.p,{children:["会创建一个新的 ",(0,c.jsx)(n.code,{children:"./docs/"})," 文件夹，把云端 scope 的内容拉下来。"]}),"\n",(0,c.jsx)(n.h4,{children:"B. 接入已有文件夹（本地已经有内容）"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"cd /path/to/your/existing/folder\nmut connect <endpoint-url> --credential <access-key>\n"})}),"\n",(0,c.jsxs)(n.p,{children:[(0,c.jsx)(n.code,{children:"mut connect"})," 会拉云端状态、和本地文件做三路合并，然后把结果推回去。",(0,c.jsx)(n.strong,{children:"只在硬盘上的文件被上传；只在云端的文件被下载。不覆盖、不丢数据。"})]}),"\n",(0,c.jsxs)(n.blockquote,{children:["\n",(0,c.jsxs)(n.p,{children:["想让 puppyone CLI 一步到位？用 ",(0,c.jsx)(n.code,{children:"--link"}),"："]}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"puppyone access add filesystem docs --link /path/to/your/folder\n"})}),"\n",(0,c.jsxs)(n.p,{children:["等于 ",(0,c.jsx)(n.code,{children:"puppyone access add filesystem docs && cd <link> && mut connect ..."})," 一气呵成。"]}),"\n"]}),"\n",(0,c.jsx)(n.h3,{children:"第三步：编辑、提交、推送"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:'echo "# Welcome" > readme.md\nmut commit -m "init docs"\nmut push\n'})}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"Scope（路径范围）"}),"\n",(0,c.jsx)(n.p,{children:"每个同步连接绑定一个 scope——云端项目树中的路径。不同的本地文件夹可以同步到不同的 scope："}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"puppyone access add filesystem docs      # scope = /docs\npuppyone access add filesystem code      # scope = /code\npuppyone access add filesystem config    # scope = /config\n"})}),"\n",(0,c.jsx)(n.p,{children:"在云端形成统一的项目树："}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{children:"Root/\n├── docs/       ← 来自 ~/my-docs\n├── code/       ← 来自 ~/my-code\n└── config/     ← 来自 ~/my-config\n"})}),"\n",(0,c.jsx)(n.p,{children:"这允许不同的团队成员或 Agent 各自管理自己负责的部分，最终汇合到同一个项目中。"}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"同步行为"}),"\n",(0,c.jsx)(n.h3,{children:'MUT vs 老版 "Real-time" 同步'}),"\n",(0,c.jsxs)(n.table,{children:[(0,c.jsx)(n.thead,{children:(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.th,{children:"特性"}),(0,c.jsx)(n.th,{style:{textAlign:"center"},children:"MUT（当前）"}),(0,c.jsx)(n.th,{style:{textAlign:"center"},children:"Real-time（已废弃）"})]})}),(0,c.jsxs)(n.tbody,{children:[(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"同步方式"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"手动 commit + push"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"后台守护进程自动同步"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"版本历史"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"每次 push 产生版本"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"无版本概念"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"冲突处理"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"三路合并"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"last-write-wins"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"离线支持"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"支持（本地 commit）"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"不支持"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"适用场景"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"所有场景"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"仅实时编辑"})]})]})]}),"\n",(0,c.jsx)(n.h3,{children:"文件类型支持"}),"\n",(0,c.jsxs)(n.table,{children:[(0,c.jsx)(n.thead,{children:(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.th,{children:"文件类型"}),(0,c.jsx)(n.th,{style:{textAlign:"center"},children:"Push（本地→云端）"}),(0,c.jsx)(n.th,{style:{textAlign:"center"},children:"Pull（云端→本地）"})]})}),(0,c.jsxs)(n.tbody,{children:[(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"文本文件（.json / .md / .txt 等）"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"✓"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"✓"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"二进制文件（.png / .pdf 等）"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"✓"}),(0,c.jsx)(n.td,{style:{textAlign:"center"},children:"✓"})]})]})]}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"版本管理"}),"\n",(0,c.jsx)(n.p,{children:"MUT 协议为每次 push 自动创建版本记录。"}),"\n",(0,c.jsx)(n.h3,{children:"查看提交历史"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"cd ~/my-docs\nmut log\n"})}),"\n",(0,c.jsx)(n.h3,{children:"回滚"}),"\n",(0,c.jsx)(n.p,{children:"在 puppyone Dashboard 中查看版本历史并一键回滚，或通过 API 操作。"}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"配合 Claude Code 使用"}),"\n",(0,c.jsx)(n.p,{children:"本地文件夹同步是将 puppyone 数据交给 AI 编程工具处理的最佳方式："}),"\n",(0,c.jsxs)(n.ol,{children:["\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.strong,{children:"创建连接并接入本地文件夹"}),"，按场景挑一种："]}),"\n"]}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"# A) 本地文件夹已经存在 → 一站式\npuppyone access add filesystem workspace --link ~/ai-workspace\n\n# B) 本地还没有这个目录 → 先创建 AP，再 clone 一份\npuppyone access add filesystem workspace\nmut clone <url> --credential <key> --dir ~/ai-workspace\n\n# C) 本地有目录但当时忘了带 --link\ncd ~/ai-workspace\nmut connect <url> --credential <key>\n"})}),"\n",(0,c.jsxs)(n.ol,{start:"2",children:["\n",(0,c.jsxs)(n.li,{children:["\n",(0,c.jsxs)(n.p,{children:[(0,c.jsx)(n.strong,{children:"用 Claude Code 编辑"})," ",(0,c.jsx)(n.code,{children:"~/ai-workspace"})," 中的文件"]}),"\n"]}),"\n",(0,c.jsxs)(n.li,{children:["\n",(0,c.jsxs)(n.p,{children:[(0,c.jsx)(n.strong,{children:"提交推送"}),"："]}),"\n"]}),"\n"]}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:'cd ~/ai-workspace\nmut commit -m "AI updates"\nmut push\n'})}),"\n",(0,c.jsx)(n.p,{children:"所有变更都有版本历史保障，可以对比 AI 的修改、按需回滚。"}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"管理连接"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"# 列出所有连接\npuppyone access ls\n\n# 查看 Access Key（随时可查）\npuppyone access key <id>\n\n# 重新生成 Access Key\npuppyone access key <id> --regenerate\n\n# 删除连接\npuppyone access rm <id>\n"})}),"\n",(0,c.jsx)(n.hr,{}),"\n",(0,c.jsx)(n.h2,{children:"常见问题"}),"\n",(0,c.jsx)(n.h3,{children:"如何同步多个文件夹？"}),"\n",(0,c.jsx)(n.p,{children:"每个文件夹创建独立的 scope 连接："}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"puppyone access add filesystem project-a --link ~/project-a\npuppyone access add filesystem project-b --link ~/project-b\n"})}),"\n",(0,c.jsx)(n.p,{children:"或者分两步："}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"puppyone access add filesystem project-a\nmut clone   <url-a> --credential <key-a>           # 全新拉一份\n# 或\ncd ~/existing-project-b\nmut connect <url-b> --credential <key-b>

1           # 接入已有文件夹\n"})}),"\n",(0,c.jsx)(n.h3,{children:"Clone 还是 Connect？"}),"\n",(0,c.jsxs)(n.table,{children:[(0,c.jsx)(n.thead,{children:(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.th,{children:"场景"}),(0,c.jsx)(n.th,{children:"用什么"})]})}),(0,c.jsxs)(n.tbody,{children:[(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"本地还没有这个文件夹"}),(0,c.jsxs)(n.td,{children:[(0,c.jsx)(n.code,{children:"mut clone"})," — 创建新目录，拉下云端内容"]})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"本地已经有内容，想接入云端"}),(0,c.jsxs)(n.td,{children:[(0,c.jsx)(n.code,{children:"mut connect"})," — 三路合并，不覆盖"]})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"已有云端内容 + 本地内容，想合并"}),(0,c.jsxs)(n.td,{children:[(0,c.jsx)(n.code,{children:"mut connect"})," — 同上，自动 merge"]})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:"想清空云端、推本地"}),(0,c.jsxs)(n.td,{children:["先 ",(0,c.jsx)(n.code,{children:"puppyone access rm <id>"}),"，重建后用 ",(0,c.jsx)(n.code,{children:"mut connect"})]})]})]})]}),"\n",(0,c.jsx)(n.h3,{children:"推送时提示冲突怎么办？"}),"\n",(0,c.jsx)(n.p,{children:"先拉取最新版本，解决冲突后重新推送："}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:'mut pull\n# 解决冲突...\nmut commit -m "resolve conflicts"\nmut push\n'})}),"\n",(0,c.jsx)(n.h3,{children:"Access Key 丢失了？"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-bash",children:"puppyone access key <connection-id>\n"})}),"\n",(0,c.jsx)(n.p,{children:"Key 存储在数据库中，不是一次性的，随时可以再查。"})]})}function r(){let e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{},{wrapper:n}={...(0,l.a)(),...e.components};return n?(0,c.jsx)(n,{...e,children:(0,c.jsx)(d,{...e})}):d(e)}}}]);