knowledge-workspace

知识工作区（Secondbrain）

中央知识库是 marcioaltoe/secondbrain：按项目整理的镜像、编辑笔记、共享规范，以及由 LLM 维护的知识 Wiki（第二大脑）。代码仓库以常规文件的形式管理自己的文档；Secondbrain 会自动汇总这些文档。

约定

文档（CONTEXT.md、docs/——规范、ADR、任务文件、评审材料）由代码仓库中的常规文件组成。只有一种提交流程：

• 将文档和代码一起编辑，并在同一个分支和 PR 中一起提交。task_NN.md 状态变更和 ## Result 部分都是普通的仓库提交——不需要第二个仓库，也无需单独推送文档。
• 每次推送到 main 后（无论合并方式如何，或直接推送；绝不包括功能分支），GitHub Actions 都会将 .secondbrain-export 中列出的路径镜像到 secondbrain/projects/<project>/mirror/。此过程会自动进行——切勿手动同步。
• 镜像为只读。切勿编辑 secondbrain 中的 projects/<project>/mirror/；下次同步时，这些更改会被覆盖。值得编辑的内容应放在代码仓库中（项目文档），或 secondbrain 的编辑区。
• 编辑区直接在 secondbrain 中编辑并推送到其 main：projects/<project>/notes/（不属于仓库的项目笔记——会议记录、阶段性归档、客户反馈）和 shared/（跨项目规范）。registry/projects.json 用于将可发布内容的仓库列入白名单，并指定其可发布到的项目。
• 内容只能单向流动：secondbrain 中的任何内容都不会写回代码仓库。若要在仓库中引用 shared/ 中的材料，请链接到该材料——不要复制。

导出约定

代码仓库中的文件	用途
.secondbrain-project	项目名称（仅此一项）——即 projects/ 下的名称，也是 secondbrain 注册表中的键
.secondbrain-export	仓库要发布的内容：每行一个路径，目录会递归处理，!pattern 行表示排除项（类似 rsync/gitignore），# 用于注释
.github/workflows/secondbrain-sync.yml	独立同步工作流，复制自 secondbrain 的 templates/repo/secondbrain-sync.yml——所有者和每个仓库都使用同一个文件，因为私有个人仓库无法公开可复用的工作流

只有已提交的文件才能导出（同步会读取合并后提交的检出内容），并且不接受符号链接。添加新的导出材料（例如 OpenAPI 文件）时，请在同一个 PR 中更新 .secondbrain-export。

添加新项目

遵循 templates/repo/ 和 secondbrain 中的 README：在 registry/projects.json 中注册（active: true），创建 projects/<name>/notes/，将上述三个文件添加到仓库，为其授予 SECONDBRAIN_APP_CLIENT_ID 变量和 SECONDBRAIN_APP_PRIVATE_KEY 密钥的访问权限（组织仓库使用组织级配置，个人账户仓库使用仓库级配置），然后合并到 main。

第二大脑（wiki）

除了记录之外，secondbrain 还托管了一个 Karpathy 风格的大模型 wiki。权威规范是 secondbrain 自己的 AGENTS.md（由 ~/dev/secondbrain 中的会话自动加载）；本节介绍其他会话需要了解的内容。安装了 secondbrain 的 brain/skills/ 中的 secondbrain 技能后，该技能会提供有关查阅、摄取和消息沟通的详细操作指南；文档和镜像规范也由该技能负责。

• 查阅（从任何仓库为实现或规划开展研究）：从 ~/dev/secondbrain/wiki/index.md 开始，或使用 qmd 搜索所有内容——wiki、已摄取的来源、共享标准和所有项目镜像：

  qmd query "pergunta em linguagem natural"          # hybrid + rerank, best
  qmd search "keywords" -c wiki                      # scoped: wiki|raw|shared|projects|areas|fiscal
  qmd query "..." --all --files --min-score 0.3      # agent-friendly output
  qmd query "..." -c leis                            # statutory text; opt-in, never in unscoped searches
  

• 提供业务知识：加载 ai-memory-messaging，并使用 memory_message_send 将研究发送到 default/marcioaltoe-secondbrain。请注明来源、日期、发现和局限。Marcio 已于 2026-10-25 停用文件系统收件箱；外部会话不得写入 Secondbrain。研究会在那里归档，并通过 Ingest 汇编。发送前使用 qmd 检查是否重复会很有帮助。

• 项目协调与持续性：使用 memory_message_* 在现有项目之间发送请求和回复，并按需使用 ai-memory-handoff 维持同一项目的工作连续性。静态客户端会注明发件人和收件人范围。如果邮箱不存在，请告知 Marcio；不要创建文件系统替代方案。更新过时的本地规则或自动化，并在 Roundfix Baseline 仍规定旧工作流时进行检查。

• 管理范围：wiki/、raw/、编辑备注、共享材料和各个区域由 Secondbrain 会话维护。镜像保持只读；外部会话没有任何写入例外。

反面模式

• 为 CONTEXT.md/docs 创建符号链接、挂载 .knowledge/ 检出目录或运行引导脚本——这些流程已在所有地方停用。
• 在 secondbrain 中编辑或提交 projects/<project>/mirror/ 下的任何内容。
• 为了“加快同步”而将文档变更从促成该变更的 PR 中拆分出来——镜像会在合并时更新；仅存在于分支中的进行中状态才是正确做法。
• 将 shared/ 内容复制到代码仓库中——应改为链接到该内容；副本会逐渐偏离。
• 将 .secondbrain-project 指向其他项目的文件夹。