demo-project-2026-10-15

这套结构的示范样板 —— 以后每个项目都照它建。 它同时装着整套「新项目脚手架」的源码：scaffold\ 目录里是技能 new-project-scaffold 的完整副本 （脚本 + 模板 + 手册），仓库内这份即可直接用。若本机另装了该技能 （WorkBuddy 用户一般在 %USERPROFILE%\.workbuddy\skills\new-project-scaffold\），改完要两边同步。

---

🤖 AI 助手请从这里进

第一次进这个仓库？ 按这个顺序读，约 15 分钟：

① AGENTS.md —— 文件该放哪、什么绝不能提交（30 秒上手块在最前面） ② docs/agent/README.md 的「一页速览」+「开工前自检 5 条」 —— 怎么接手、怎么判断自己有没有读错、怎么提交推送、怎么收工留记录，全在这两份小表里 ③ docs/agent/HANDOFF.md —— 上一棒做到哪、下一步做什么 （进度只看它；MEMORY.md 是长期结论，天然滞后）

本项目对任何助手通用，不绑定某一家工具。 协作材料只有一份，放在 docs/agent/： 机制 README.md ｜ 交接 HANDOFF.md ｜记忆 MEMORY.md ｜约定 CONVENTIONS.md ｜技能 skills/

没有专属入口文件的工具（自研 harness、DeepSeek 等）：读上面这块就够， 或直接读 AGENTS.md —— 内容只有这一份。

路径怎么读

下文的 E:\demo-project-2026-10-15\ 是本机的实际路径（示例）；仓库里的东西一律按 「相对仓库根」理解（data\、secrets\.env、docs\agent\ 都是相对仓库根）。 换台电脑、或 clone 到别的目录后，把那串绝对路径整体换成你的实际位置即可 （仓库根查法：git rev-parse --show-toplevel）。仓库外的路径一律写成「本机：…」。

---

项目信息

环境要求

快速开始

第一次（本机新建的项目）

# 启用提交前安全检查
git config core.hooksPath .githooks

# 跑一次示例程序（会自动补齐 data/、secrets/ 等本机目录）
python examples/app.py

# 体检：代码 / 本机目录 / 数据库结构是否一致
python scripts/sync.py

examples/app.py 是示例程序，用来演示这套结构怎么用。 你自己的项目入口按技术栈自己写，名字不必叫 app.py。

换台电脑 / 在另一台电脑上用

先分清两种需求 —— 下载方式完全不一样：

A. 只看 / 只拉 —— 公开仓库，什么都不用配

git clone https://github.com/yiming-96/demo-project-2026-10-15.git

HTTPS 读公开仓库不需要登录、不需要 SSH 钥匙。另外两条路：

• 不想装 Git：打开仓库网页 → 绿色 Code 按钮 → Download ZIP。 缺点：拿到的是没有 Git 历史的快照，看不到以前的版本，也不能提交推送。
• 用图形界面：GitHub Desktop / VS Code 的「Clone Repository」，粘贴上面的网址即可。

ℹ️ data/ 与 secrets/ 不会跟着 clone 过来（被忽略的目录不在仓库里）。 这点你不用管 —— 程序第一次运行会自己把缺的目录和 .env 建好； 换助手接手时，它也会自己判断要不要补。 想先看一眼「本机缺些什么」，跑 python scripts/bootstrap.py --check（只读，不写盘）。 详见下面 B 的 ④。

⚠️ 注意：公开仓库 = 谁都能看、谁都能拉，但只有持授权钥匙的人能推。 所以仓库里绝不能出现密码、密钥、真实业务数据 —— 本项目靠 .gitignore + .githooks/pre-commit 两道防线保证（每次提交自动扫）。改了 .gitignore 敏感规则要先问人。

B. 要改要推 —— 四步配好钥匙

推送需要 SSH 钥匙（本项目用仓库级 Deploy Key，挂在仓库上，不是账户级）。

① 那台电脑上先装 Git

Windows 装 Git for Windows（装完自带 git 命令和 Git Bash）。

② 配 SSH 钥匙（两种做法选一个）

• 做法 A（推荐）：在新电脑上生成一把新钥匙，作为「第二把 Deploy Key」加到同一个仓库 —— 私钥全程不出这台机器，旧电脑的钥匙也不用动。

  ssh-keygen -t ed25519 -C "demo-project-2026-10-15@新机器名" \
      -f ~/.ssh/id_ed25519_demo-project-2026-10-15 -N ""
  cat ~/.ssh/id_ed25519_demo-project-2026-10-15.pub     # 复制输出的这一整行
  

  然后去 GitHub → 该仓库 → Settings → Deploy keys → Add deploy key， 标题随便写（如 demo-project-2026-10-15@新机器名），粘贴公钥，勾上 Allow write access。

• 做法 B（省事）：把旧电脑的私钥拷过去 把 secrets\ssh\id_ed25519_demo-project-2026-10-15 整个文件拷到新电脑的同一路径。 缺点是一把钥匙散在多台机器上，哪台丢了你都说不清是哪把。 ⚠️ 注意：secrets\ 不进仓库，所以新克隆的 secrets\ssh\ 是空的 —— 私钥只存在原来那台机器的同名路径下；那台机器若已经不在，就只能按做法 A 重新生成并登记。

两种做法都要在新电脑的 ~/.ssh/config 里加上别名（路径换成实际私钥位置）：

Host github-demo-project-2026-10-15
    HostName github.com
    User git
    IdentityFile C:/Users//.ssh/id_ed25519_demo-project-2026-10-15
    IdentitiesOnly yes

验证：ssh -T git@github-demo-project-2026-10-15 —— 返回 Hi yiming-96/demo-project-2026-10-15! 就说明钥匙通了。

用哪把钥匙：推这个仓库一律走项目专属那把（别名 github-demo-project-2026-10-15）。 机器上可能还配了一把机器级钥匙（~/.ssh/config 里的 Host github.com）—— 那是别的用途， 不要拿它推本项目，更不要去改动它。两把钥匙互不影响，各自只对自己该管的仓库有效。

③ 拉代码（注意用 SSH 地址，不是 HTTPS）

# 最后那个路径是「拉到哪」—— 本机放在 E:\demo-project-2026-10-15，换机器换成你自己的位置即可
git clone git@github-demo-project-2026-10-15:yiming-96/demo-project-2026-10-15.git E:/demo-project-2026-10-15

④ 补齐本机目录 + 启用钩子

data/ 与 secrets/ 不进仓库，clone 后根本不存在。这一步不用刻意记 —— 程序第一次运行（python examples/app.py）就会把缺的目录自动建好，助手接手时也会自己判断、自己补。 想一次把目录说明文件、.env 模板、提交钩子都补齐，就再跑下面这条（幂等，已有的一律不动）：

cd E:/demo-project-2026-10-15        # 换成你实际的 clone 位置

python scripts/bootstrap.py --check  # 先看缺什么（只读，一个字节都不写）
python scripts/bootstrap.py          # 缺什么补什么（幂等，已有的一律不动）

# 这个配置也不随仓库传输
git config core.hooksPath .githooks

# 然后编辑 secrets/.env 填真实配置（bootstrap 已从 .env.example 复制好模板）

本地才有的东西怎么迁移（数据库、凭据、助手日志）

先记住哪些东西不在 Git 里 —— 它们不会被 clone 带过去，必须单独搬：

四种搬法，按场景选一个：

① 用迁移包（推荐：一条命令，代码 + 数据 + 凭据全带走）

# 旧电脑：打包（数据库走一致性快照，不是直接拷 .db）
python scripts/portable.py pack
# → data/exports/portable/_portable_.zip

# 新电脑：解压后一条命令还原
python portable.py restore --target D:\

包里还有完整 Git 历史（repo.bundle）、data\、secrets\，以及给新机器 AI 读的 AGENT_README.md。先 --dry-run 看计划，确认后再正式执行。 详细说明见 docs/agent/skills/project-portable-transfer/SKILL.md。

② 整个文件夹直接拷贝（最省事，但要先停掉程序）

把旧电脑的 E:\demo-project-2026-10-15\ 整个文件夹（含 .git、data、secrets）复制到新电脑 同一位置。新电脑上直接就能用，连 clone 都不用做。

• 拷完在新电脑上确认两件事：git remote -v 指向的还是对的；secrets\ssh\ 里的私钥在
• 用移动硬盘 / 内网传，别丢公共网盘（里面有真实数据和私钥）

③ clone + 单独搬数据（干净）

新电脑先按上面 A 或 B 把代码拉下来 → 跑 python scripts/bootstrap.py （或干脆先跑一次程序，目录会自愈）→ 再把旧电脑的 data\ 整个目录拷过来覆盖，secrets\ 里的 .env 按新机器实际情况改一份。

好处：代码是从仓库来的（干净、最新），只有数据是搬的。

④ 只搬数据库（数据量大 / 只想迁库）

# 旧电脑：生成一致性快照（不是直接拷 .db 文件！）
python scripts/backup.py

# 把 data/backups/ 里最新的那份快照拷到新电脑的 data/backups/
# 新电脑：停掉应用 → 当前库先另存一份（后悔药）→ 用快照覆盖 → 重启

⚠️ 三条铁律

1. 绝不要直接拷贝正在运行中的数据库文件。 SQLite 在写入中（尤其 WAL 模式）会拷到 「写了一半」的副本，等你真要用时才发现库是坏的。一律走 scripts/backup.py， 它用的是数据库原生的一致性快照机制。
2. 路径可能变：代码通过环境变量 APP_DATA 找数据目录。如果新电脑上数据放在别的位置， 改 secrets\.env 里的 APP_DATA，别去改代码。
3. 两台电脑不要同时跑同一个库。data\ 不在 Git 里 = 没有同步机制，两台各改各的 就是两份分叉的数据，而且谁也合不回来。约定一台为主（数据都在主机上改）， 另一台只读或只在主机上操作。

搬完怎么确认没搬错：启动 python examples/app.py 看数据在不在；再跑一次 python scripts/backup.py --list 看快照能正常生成。

最后让 AI 助手先读 docs/agent/HANDOFF.md，就能接上进度。

代码更新后，本地数据库怎么跟上

代码走 Git，数据留本机 —— 所以「拉到最新代码」和「本地库还是旧结构」会同时发生。 一条命令对齐：

python scripts/sync.py --all

它会依次做：git pull --rebase → 检查本机目录 → 执行 scripts/migrations/ 里待执行的迁移 （先自动备份到 data/backups/）→ 报告「代码 / 目录 / 数据库结构」是否一致。

只想看状态、不改任何东西：

python scripts/sync.py              # 体检
python scripts/migrate.py --check   # 只看有没有待执行的迁移

改表结构时：在 scripts/migrations/ 里加一份 0003_xxx.sql（序号只往后加）， 不要手工改库、也不要把 ALTER TABLE 写进业务代码 —— 换台电脑时没人知道该执行哪些。 规则见 scripts/migrations/README.md。

目录说明

项目自包含约定

一个项目 = 一个文件夹，文件夹名带立项日期（-YYYY-MM-DD）。 根目录永远只有项目文件夹，不散落任何文件。项目内部按「去向」分三类：

data\ / secrets\ 被 两道防线挡住：.gitignore（看不见）+ .githooks/pre-commit （git add -f 也拦）。各助手自己的隐藏目录（.workbuddy\、.claude\…）同理。

为什么这样分、换机器怎么走：见 docs/agent/ARCHITECTURE.md ——代码走 Git、数据留本机两条通道，靠目录约定 + 程序自愈 + 数据库迁移对齐。

跨助手协作怎么运作（本项目的重点）

根目录放了一组薄入口文件，每个几行，都指向 AGENTS.md 与 docs/agent/： AGENTS.md（跨工具标准）｜CLAUDE.md（Claude Code）｜GEMINI.md（Gemini CLI） ｜.github/copilot-instructions.md（Copilot）｜.cursor/rules/project.mdc（Cursor）。

以后用到新工具，不要改 docs/agent/ 的内容，只加一个几行的入口文件指向它即可。

测试与安全检查

不确定某个文件放哪？

对照 docs\agent\CONVENTIONS.md 里的「唯一去向表」查 —— 那张表按 「这是什么东西」列了三十多类，每一类只有一个正确答案。每个目录里也都有说明文件。

用这套结构开新项目

完整的、任何 agent 都能照做的步骤见 docs/agent/NEW-PROJECT.md。 最短路径：

python scaffold/scripts/scaffold.py  --root 
# 本机约定是放在 E 盘：--root E:

会生成 \-\，含交接层（docs/agent/ 全套）、标准目录、 两档安全检查、项目专属密钥，以及一整套运维脚本： bootstrap sync migrate backup clean portable + migrations/。

新项目不复制 scaffold\ 与 examples\app.py —— 这两样是样板自己的源码 （建仓工具、演示程序）。examples\ 目录本身照建（脚手架会给），空着即可。

数据备份与临时文件

备份固定放 data\backups\ —— 不管用哪种数据库，都在这一个地方（这样下一个人找得到）。

python scripts/backup.py            # 按 scripts/backup.json 备份全部目标
python scripts/backup.py --list     # 看现状，不动文件
python scripts/backup.py --dry-run  # 只演算，不动文件

python scripts/clean.py --dry-run   # 看会清掉哪些临时产物
python scripts/clean.py             # 清 _test 7 天前、_tmp 3 天前

数据库不止 SQLite 也没关系：脚本把「怎么导出一个库」抽象成引擎 —— 内置 sqlite（VACUUM INTO 一致性副本）/ mysql（mysqldump --single-transaction）/ postgres（pg_dump -Fc）；其它数据库（SQL Server、Oracle、MongoDB…）在 scripts/backup.json 里加一条自定义命令就能接进来，不用改脚本 （写法见 scripts/backup.example.json）。

• 命名固定 -YYYY-MM-DD_HHMMSS.，默认保留最近 7 个日期各 1 份 + 最近 4 个周各 1 份，只删自己命名的文件
• 密码不进 backup.json、不进命令行 —— 只从环境变量或 secrets\.env 读
• 别直接复制数据库文件：应用写入中可能拷到「写了一半」的库；各引擎用自己的一致性手段
• 快照只在本机：它和源库在同一块盘，硬盘坏了照样全丢 —— 关键数据还要另存一份到移动硬盘 / 另一台电脑 / 可靠的网盘

注意事项

• 数据不在远端，需自己留底（见上「数据备份与临时文件」）—— 代码丢了能重新拉回来，数据是真丢
• 备份只写 data\backups\，别换地方（换了下一个接手的人就找不到）
• 临时产物堆多了跑一次 python scripts/clean.py，它能少让项目文件夹胖几 G
• 提交前先 git status 确认清单；钩子拦截时不要用 --no-verify 绕过
• 本仓库使用独立 SSH 密钥，按仓库级 Deploy Key 登记（仓库 Settings → Deploy keys， 勾 Allow write access）；别名 github-demo-project-2026-10-15，与其他项目互不影响
• 完整流程见 docs/agent/NEW-PROJECT.md；脚手架本身的详细手册在 scaffold/references/新项目启动手册.md