一句话架构：每个 Agent 在自己的子库里工作，最终产出统一放进 output/；任务完成后执行一条同步脚本，把产出镜像进主库并自动刷新总索引（产出区 + 标签区）；各库都是独立 git 仓库，全程可追溯。
📘 日常操作（同步、周回顾、找回文件、故障排查）请看 使用说明书.md。 发布仓库：https://github.com/lgb-co/knowledge-base（单仓库发布形态，只含机制与目录结构）
本仓库在 GitHub 上是单仓库发布形态：main-vault/、agent-X-vault/ 只是普通目录。
克隆后第一件事是把它恢复成多仓库结构：
cd knowledge-base
bash scripts/init-vaults.sh # 三个库各自 git init + 首次提交
bash scripts/doctor.sh # 自检，确认结构/仓库独立性/索引都正常然后强烈建议断掉上游，避免私人产出被推回公开仓库：
git -C <克隆目录> remote remove origin # 或者把它改成你自己的私有仓库地址原因（已实测）：判断「是不是 git 仓库」如果只看 git rev-parse --is-inside-work-tree，在单仓库克隆里会向上找到外层克隆的 .git 而误判——三库结构静默退化成单库，且同步脚本会把提交 push 到外层仓库（＝上游公开仓库）。
本仓库的脚本已按「该目录自身必须有 .git」来判断，并且推送默认关闭（需 KB_PUSH=1），但外层仓库本身仍需你自己决定要不要留上游。
knowledge-base/
├── README.md # 本文件：架构总说明与接入指南
├── 使用说明书.md # 日常操作手册（同步/发布/找回/FAQ）
├── .gitattributes # 换行约定：*.sh / *.md 一律 LF
├── scripts/ # 公共脚本区（位于各库之外，不入内层仓库）
│ ├── lib-kb.sh # 公共函数（仓库判定、路径转义、tags 解析、推送控制）
│ ├── init-vaults.sh # 克隆后一键恢复「主库 + 子库」多仓库结构
│ ├── sync-to-main.sh # 通用同步脚本：任一 agent 库 → 主库，参数化
│ ├── update-main-index.sh # 扫描 agents/ 刷新 index.md 的产出区与标签区
│ ├── add-agent.sh # 一条命令接入新 agent（建库 + 挂目录 + 打印指令块）
│ ├── doctor.sh # 自检：结构、仓库独立性、索引一致性、命名、备份/发布状态
│ ├── backup.sh # 一键备份：打包 + 轮转（可选 --push 推远程）
│ └── publish.sh # 把工作副本发布成单仓库形态并推送
├── main-vault/ # 主库（独立 git 仓库）：汇总中心
│ ├── agents/agent-A/ # agent-A 的产出镜像（同步脚本维护）
│ ├── agents/agent-B/ # agent-B 的产出镜像
│ ├── shared/
│ │ ├── templates/笔记模板.md
│ │ ├── templates/产出模板.md # 写产出时复制使用（含 tags 骨架）
│ │ ├── examples/ # 机制示例留档（不占产出区）
│ │ ├── glossary.md # 术语表
│ │ └── conventions.md # 命名规范 + Agent 五条约定 + 可粘贴指令块
│ ├── reviews/周回顾模板.md
│ └── index.md # 总索引（产出区 + 标签区，均可自动更新）
├── agent-A-vault/ # agent-A 子库（独立 git 仓库）
│ ├── daily/ projects/ # 过程性内容（不会镜像进主库）
│ └── output/ # 最终产出（同步脚本只镜像这个目录）
└── agent-B-vault/ # agent-B 子库（独立 git 仓库）
├── research/ notes/ # 过程性内容
└── output/
| 机制 | 落地方式 |
|---|---|
| 1. Git 脚本同步 | scripts/sync-to-main.sh <agent名> [备注]：镜像 output/ → main-vault/agents/<agent名>/，刷新 index.md，库各提交一次 |
| 2. 给 Agent 程序明确指令 | main-vault/shared/conventions.md 的五条约定 + 可粘贴指令块（add-agent.sh 会自动生成） |
| 3. 任务完成后触发 | 约定第 4 条 + 指令块里的「任务完成后的固定动作」，不靠人工提醒 |
| 4. 双维度索引 | 产出区＝agent × 时间；标签区＝主题（产出 frontmatter 的 tags:），自动生成 |
见上面「bash scripts/init-vaults.sh → bash scripts/doctor.sh → 视情况 git remote remove origin。
脚本可重复执行：已是独立仓库的目录自动跳过。
推荐（一条命令）：
cd D:/knowledge-base
bash scripts/add-agent.sh agent-C # 默认过程目录 daily、projects
bash scripts/add-agent.sh agent-D notes drafts # 自定义过程目录它会建 <名>-vault/（output/ + 过程目录 + .gitignore）、git init 并完成首次提交、在主库建 agents/<名>/.gitkeep 并提交，最后打印可直接粘贴给该 Agent 程序的指令块（身份与路径已替换好）。
手工 5 步（等价操作，脚本出问题时可用）：
- 建子库：
mkdir -p agent-C-vault/output（可自建daily/、projects/等过程目录），复制根.gitignore，然后git init并做首次提交。 - 主库挂目录：
mkdir -p main-vault/agents/agent-C，放一个.gitkeep占位。 - 更新指令块：用
add-agent.sh打印的那段，或复制下面「粘贴版 Agent 指令块」改agent-X；同步更新shared/conventions.md。 - 下发指令：把指令块粘贴进该 Agent 程序的系统提示 / 常驻记忆。
- 自测：让该 Agent 在
output/写一篇带日期前缀的文档，执行同步命令，核对主库出现文件、index.md两个区间列出、git log有提交。
| 脚本 | 用途 |
|---|---|
bash scripts/init-vaults.sh |
克隆后把三个库目录初始化为独立仓库（幂等） |
bash scripts/add-agent.sh <名> [过程目录…] |
接入新 agent（建库 + 挂目录 + 打印指令块） |
bash scripts/sync-to-main.sh <agent名> [备注] |
同步产出：镜像 → 刷新索引 → 提交 |
bash scripts/update-main-index.sh |
只刷新 index.md 的产出区与标签区 |
bash scripts/doctor.sh |
自检（结构 / 仓库独立性 / 索引一致性 / 命名 / 备份与发布状态） |
bash scripts/backup.sh [--dir <路径>] [--keep N] [--push] [--list] |
一键备份（打包含各库 .git，自动轮转保留最近 N 份；--push 推有远程的库） |
bash scripts/publish.sh [--dir <路径>] [--no-push] |
把工作副本发布成单仓库形态并推送 |
| 环境变量 | 默认 | 作用 |
|---|---|---|
KB_PUSH |
0 |
1 时同步才推送远程（默认只做本地提交，避免误推上游） |
KB_STRICT |
0 |
1 时产出文件名不合规直接拒绝同步（默认只警告） |
KB_PUBLISH_DIR |
同级 knowledge-base-publish/knowledge-base |
发布副本路径（也可用 publish.sh --dir） |
KB_BACKUP_DIR |
同级 knowledge-base-backups |
备份目录（也可用 backup.sh --dir） |
KB_BACKUP_KEEP |
10 |
备份保留份数 |
# 在任意 agent 子库目录下执行（也可用绝对路径从任何位置调用）
cd D:/knowledge-base/agent-A-vault
bash ../scripts/sync-to-main.sh agent-A "完成登录模块调研"行为清单：
- 校验：agent 名合法（字母/数字/点/下划线/连字符）；主库与子库必须「自身」是 git 仓库（在单仓库克隆里会提示先跑
init-vaults.sh）；当前目录若属于别的 agent 子库则直接拒绝（防同步错库）；目标目录按字符串与真实路径两层校验必须位于main-vault/agents/之下才允许清理（防误删）。 - 命名体检：
output/下有不符合YYYY-MM-DD-标题.md、或含空格/#/?/%等字符的文件时给出警告（索引链接已做完整转义，不阻断；KB_STRICT=1可改为拒绝）。 - 镜像：清空
main-vault/agents/<agent名>/，把子库output/全量复制过去（无 rsync 依赖）；镜像后为空则放.gitkeep占位。 - 索引：自动调用
update-main-index.sh刷新产出区与标签区（只重写标记区间，不动手写内容）。 - 提交：主库
sync(<agent名>): <备注> (<时间>)；子库分两条：先sync: <备注> (<时间>)（只含output/），再wip: 过程记录 (<时间>)（其余草稿）；无变更自动跳过。 - 推送：默认不推（只本地提交）；
KB_PUSH=1且该库仓库顶层就是自身时才 push，失败只警告。 - 兼容性：路径全部基于脚本自身位置解析并加引号，中文/空格路径可用；仅依赖 Git Bash 自带命令。
index.md= 手写区（快速导航、维护说明等）+ 两个自动区间：
<!-- KB-AUTO-OUTPUT:START ... --> 产出区：按 agent 分组列出产出
<!-- KB-AUTO-OUTPUT:END -->
<!-- KB-AUTO-TAGS:START ... --> 标签区：按 frontmatter tags 聚合（跨 agent 主题检索）
<!-- KB-AUTO-TAGS:END -->- 想按主题检索：产出文件开头写
---/tags: [主题A, 主题B]/---（模板见shared/templates/笔记模板.md），下次同步即出现在标签区。 - 标记之外的手写内容永远不会被脚本改写；标记之内手工修改会在下次同步时被覆盖。
- 生成内容是确定性的（不含时间戳）：产出没变时文件不重写，同步脚本才能正确判断「无变更、跳过提交」。
- 缺任何一个标记，脚本会拒绝执行（防止误删手写内容），报错里给出恢复命令。
- 手动刷新：在 knowledge-base/ 根目录执行
bash scripts/update-main-index.sh。
bash scripts/doctor.sh # 出问题先跑这个（含备份时效检查）
bash scripts/backup.sh # 一键备份：打包到同级 knowledge-base-backups/，自动轮转
bash scripts/backup.sh --list # 看现有备份
bash scripts/backup.sh --push # 顺带把配了远程的库推上去（异地备份）
bash scripts/publish.sh # 工作副本 → 发布副本 → 提交 → 推送
bash scripts/publish.sh --no-push # 只更新发布副本，不推doctor.sh检查：目录结构、各库是否独立仓库、core.autocrlf/quotepath、index.md两组标记与一致性、脚本行尾、产出命名、未提交变更、远程与本地备份时效、发布副本是否漂移。退出码 1 表示有致命问题。backup.sh打包含各库的.git（历史与提交都在）以及过程性目录（草稿也备份，本地不外传），默认保留最近 10 份。解包即用，不需要再跑init-vaults.sh。publish.sh把工作副本镜像成「单仓库形态」的发布副本（子库只发布output/与目录结构，过程性内容一律不外传；排除内层.git、.obsidian等），提交并推送——发布只走这一条出口，避免手工拷贝漂移。发布副本必须自带.git（是个独立克隆）。
- 独立仓库：
main-vault/、agent-A-vault/、agent-B-vault/（以及以后新增的*-vault）；scripts/、README、《使用说明书》、.gitattributes不属于任何内层仓库。 - 推送默认关闭：
git remote add origin <url>之后，同步时用KB_PUSH=1才会推；这是为了避免在「单仓库克隆」里把内容推回上游公开仓库。 - 各库
.gitignore：Thumbs.db、.DS_Store、.obsidian/。 - 各库设置
core.autocrlf=false（换行稳定，标记匹配不受影响）、core.quotepath=false（git log正常显示中文文件名）；仓库根有.gitattributes兜底（*.sh、*.md强制 LF）。 - 空目录用
.gitkeep保证结构入库。 - 工作副本的外层目录若也做了
git init用来跟踪scripts/与文档：请把三个库目录写进.git/info/exclude（局部忽略，不会跟着发布出去），例如/main-vault/、/agent-*-vault/；否则 git 会把它们记成 embedded repository（gitlink）而丢失内容。
新 agent 用
bash scripts/add-agent.sh <名>自动生成，下面两份是 agent-A / agent-B 的现成版（内容与shared/conventions.md保持一致）。
你是知识库写作 Agent（身份：agent-A），在 Windows + Git Bash 环境下工作。
环境
- 知识库根目录：D:/knowledge-base
- 你的子库（唯一工作区）：D:/knowledge-base/agent-A-vault
- 主库（只读，不要直接修改）：D:/knowledge-base/main-vault
工作约定
1. 只在你的子库里读写文件，不修改主库和其它 agent 的子库。
2. 最终产出统一放 output/；过程性记录放 daily/、projects/。
3. 产出文件命名 YYYY-MM-DD-标题.md，例：2026-08-29-登录模块调研.md。
4. 需要模板/术语表等共享资源时，先从 main-vault/shared/ 复制到自己子库再使用，不直接编辑主库 shared/。
5. 每个任务完成后立即同步，不要攒批。
任务完成后的固定动作（必须执行）
cd D:/knowledge-base/agent-A-vault
bash ../scripts/sync-to-main.sh agent-A "任务简述"
同步脚本会自动完成：output/ 镜像到主库 agents/agent-A/ → 刷新主库 index.md 产出区与标签区 → 主库与子库各提交一次。
你是知识库写作 Agent（身份：agent-B），在 Windows + Git Bash 环境下工作。
环境
- 知识库根目录：D:/knowledge-base
- 你的子库（唯一工作区）：D:/knowledge-base/agent-B-vault
- 主库（只读，不要直接修改）：D:/knowledge-base/main-vault
工作约定
1. 只在你的子库里读写文件，不修改主库和其它 agent 的子库。
2. 最终产出统一放 output/；过程性记录放 research/、notes/。
3. 产出文件命名 YYYY-MM-DD-标题.md，例：2026-08-29-竞品分析.md。
4. 需要模板/术语表等共享资源时，先从 main-vault/shared/ 复制到自己子库再使用，不直接编辑主库 shared/。
5. 每个任务完成后立即同步，不要攒批。
任务完成后的固定动作（必须执行）
cd D:/knowledge-base/agent-B-vault
bash ../scripts/sync-to-main.sh agent-B "任务简述"
同步脚本会自动完成：output/ 镜像到主库 agents/agent-B/ → 刷新主库 index.md 产出区与标签区 → 主库与子库各提交一次。
main-vault/shared/examples/2026-08-29-示例报告.md 是首条全链路验证的留档：写入产出 → bash ../scripts/sync-to-main.sh agent-A "示例同步" → 核对主库出现文件、index.md 产出区列出、git log 有同步提交。它已从产出区挪到 shared/examples/，让产出区只放真产出；新 Agent 照此流程即可完成接入自测。
第一篇真实产出见 agents/agent-A/2026-09-20-知识库机制加固记录.md——它同时也是「标签区」的示范（frontmatter 写了 tags:）。
- 脚本报「主库/子库不是独立 git 仓库」：这个副本还是单仓库形态 →
bash scripts/init-vaults.sh。 - 同步完发现内容被推到了 GitHub 上游：说明在单仓库克隆里跑了同步 → 立刻
git remote remove origin（或改成私有库），并从远端回滚；推送默认关闭后不会再发生。 - 运行报
$'\r': command not found：编辑器把脚本存成了 CRLF，请用 LF 保存（VS Code 右下角切换）；仓库.gitattributes已约定*.sh用 LF。 - 想推远程：
git -C <库> remote add origin <url>，然后同步时加KB_PUSH=1（例：KB_PUSH=1 bash ../scripts/sync-to-main.sh agent-A "任务简述"）；失败只警告，不影响本地提交。 - 不确定哪里坏了：先
bash scripts/doctor.sh，它会逐项报出问题。