Techo 是一个运行在个人服务器上的文件与协作产品。拥有者用通行密钥登录，管理服务器上的真实文件；外部人员通过有期限、可撤销的链接下载文件或投递文件。服务状态在同一界面查看。Techo 使用普通 Linux 目录、SQLite 和 systemd，文件可以继续由 SSH、脚本及其他工具直接管理。

当前版本面向单机、单拥有者。香港服务器实例已通过 Cloudflare Tunnel 开放 https://techo.kunpeng.blog，手机通行密钥和电脑扫码登录已验收。产品方向见 Techo.md，已实现的边界见 架构说明。

现在可以做什么

| 场景 | 当前能力 | | ---------- | ---------------------------------------------------------------------------------------------- | | 云端桌面 | 粘贴文字保存为便笺；桌面文件图标与便笺；右键操作；手机排版；跨设备同步 | | 管理文件 | 浏览目录；上传、下载、创建文件夹、移动、复制、删除文件；查看图片和 PDF；阅读及编辑小型文本文件 | | 安全登录 | 使用 WebAuthn 通行密钥；新设备凭服务器控制台生成的十分钟一次性登记码加入 | | 分享文件 | 为单个文件生成限时下载链接；拥有者可查看并撤销链接 | | 接收文件 | 为指定目录生成限时收件链接；访客无需账号即可投递，不能浏览目录 | | 查看服务器 | 查看 Techo 版本、磁盘空间、运行时间与数据库版本等只读状态 |

拥有者 ── 通行密钥 ── Techo ── 普通 Linux 文件
                         │
                         ├──── SQLite：登录、会话与链接授权
                         └──── systemd：服务运行与发布

访客 ─── 限时链接 ──── 下载单个文件 / 向指定目录投递

快速开始

需要 Node.js 22.18+ 和 npm。安装统一 CLI，然后选择客户端或服务端：

npm install -g @grada/techo
techo setup

Linux 服务端会准备配置、文件目录和运行依赖，安装并启动 systemd 服务；客户端通过浏览器配对，按授权目录读写文件。techo server status 查询状态，techo upgrade 更新当前角色，完整流程见 安装与升级。公网 HTTPS 通过自己的反向代理或 Cloudflare Tunnel 配置。

开发源码时，进入克隆后的仓库运行：

npm ci
npm run setup:local
npm run build
npm start

setup:local 在仓库内创建被 Git 忽略的 config.json、.local/files/ 与 .local/state/；如果配置已存在，不会覆盖。浏览器打开 http://localhost:3000。在另一个终端登记首枚通行密钥：

npm run auth:enroll

命令会输出有效期十分钟的配对链接和一次性登记码。打开链接后，登记码会自动填入，点击「登记通行密钥」并完成设备验证；也可手动输入配对码。不要把链接或登记码提交到仓库、终端日志或发给他人。生产服务器发布后可在任意目录运行 techo enroll；SSH 环境会打印链接，在图形桌面环境会尝试打开浏览器。

开发时可分别运行 npm run dev 和 npm run dev:web；提交前运行 npm run check，其中包含类型检查、格式、Shell 语法、构建和行为测试。

数据如何存放

| 内容 | 存放位置 | 约定 | | -------------------- | ---------------------------------------------------- | -------------------------------------------- | | 文件正文 | 配置指定的 files_root 普通目录 | 文件系统是内容来源；Techo 不复制正文到数据库 | | 通行密钥、会话与链接 | SQLite | 与文件分别备份；删除数据库会丢失这些授权数据 | | 运行配置 | Git 忽略的 config.json 或 /etc/techo/config.json | 明确文件根、数据库、监听地址和登录域名 |

网页只访问配置的文件根目录；dotfiles 和符号链接不会出现在文件界面。收件链接最多接收 5 个文件，每个不超过 64 MiB，同名文件不会覆盖；拥有者普通上传上限为 512 MiB。分享与收件令牌仅在创建时返回，数据库保存其哈希。当前没有多用户隔离或整机文件扫描。SSH 命令执行仅面向明确授权的主机与设备。

原有日记和文字仓库仍是独立资料，只有拥有者明确配置后才会进入 Techo 的文件范围。

原生部署

生产部署使用独立的 techo 服务账户、systemd 和按版本保存的构建产物。Node 服务只监听回环地址，香港实例通过现有 Cloudflare Tunnel 提供公网 HTTPS。deploy/release.sh 会检查、构建、切换版本并验证 /healthz；失败时回退程序和 systemd 单元。deploy/backup.sh 保存 SQLite 在线快照、文件及配置。

目录约定、首次安装、备份与恢复见 运维指南。当前域名、Tunnel 路由和验收状态见 公网入口说明。公网单次上传还受 Cloudflare 账户套餐的请求体大小限制。

项目结构

src/server/       API、文件边界、WebAuthn、SQLite 和状态
src/web/          浏览器界面
deploy/           systemd、Caddy、发布与备份脚本
scripts/          本机初始化
tests/            核心行为与接口测试
docs/             产品方向、工程边界、运维文档和 GitHub 展示图
brand/techo-11/   完整原始品牌资源与字体许可证

登录默认进入云端桌面，提供文件、收件和主机入口。桌面为空时安静显示快捷入口，首次保存时才创建 Desktop/。粘贴文字会保存为普通 .txt 文件，布局坐标存入 SQLite；「文件」中仍可编辑、下载、移动和分享它们。电脑可拖动便笺和图标、右键重命名或下载，手机自动排版。目录、页面和文件预览都支持浏览器前进后退及 URL 刷新恢复；编辑未保存时会提示，文件夹可即时筛选。页面可见时每五秒用 ETag 检查变化，回到前台立即同步；不加载外部字体、画板库或图标库。文件可靠性、权限与恢复的实现边界见各项工程说明。

当前状态

Techo 0.4.3 提供桌面、文件管理、原生回收站、音乐播放、Markdown 编辑、受控 SSH 主机管理，以及供 AI 使用的 CLI 与本地 MCP。统一安装包可以初始化 Linux 服务端或配对客户端，服务端升级保存数据库和配置快照并在失败时恢复。当前部署按单机单拥有者设计；Windows/macOS 客户端与 Safari 仍需更多实机验收。

后续能力的取舍见 个人云端桌面路线。

文件、收发件和主机可作为桌面窗口打开，支持移动、缩放、最小化和任务栏恢复。收发件内可管理收件链接和发出的分享。点击顶栏 ? 查看命令，或参阅 快捷键与窗口；例如 G F 打开文件，W M 最小化，Ctrl+S 保存编辑。

文件夹列表支持右键菜单、复选框、Ctrl/⌘ 多选、Shift 连选及全选；右键文件可直接创建分享链接，「管理分享」打开收发件中的发出列表。Markdown 支持按需加载的阅读排版和源码编辑，详见 Markdown 与 Typora。

「音乐」窗口支持文件音频播放、队列、进度拖动和循环；最小化继续播放，关闭停止。手机底栏采用等宽纯文字按钮，页面外层固定、内容独立滚动。详见 音乐与手机布局。

文件可靠性、原生回收站与备份恢复验收见 可靠性说明。

统一客户端/服务端命令见 CLI 指南；多台实验服务器的密钥、主机和任务管理见 SSH 管理。文件身份与增量查询见 文件索引。

Techo 0.3.0 支持 AI 通过 CLI 或本地 MCP 保存对话总结、搜索、读取并修改普通 Markdown 文件。更新必须带读取时的内容版本，设备只访问获准目录；配置与使用方式见 AI 接入。

品牌资源、网页使用方式和 GitHub 展示图见 品牌说明。