create-second-brain-prd

Second Brain PRD 生成器

根据用户填写完成的需求模板，生成个性化的 AI Second Brain 产品需求文档。

此技能附带一个空白模板，路径为 ${CLAUDE_SKILL_DIR}/my-second-brain-requirements.md。 运行此技能前，请先将其复制到工作区并填写。

参数

• $0（必填）— 已填写的需求文件路径（例如：./my-second-brain-requirements.md）
• $1（可选）— PRD 输出路径。默认为 .agent/plans/second-brain-prd.md

工作流

1. 读取需求 — 读取 $0 指定的已填写需求文件。如果未提供参数，请向用户询问文件路径。如果用户尚未填写模板，告知他们可在 ${CLAUDE_SKILL_DIR}/my-second-brain-requirements.md 获取空白模板，并请他们先将其复制到工作区并填写。

2. 加载架构参考 — 阅读 ${CLAUDE_SKILL_DIR}/references/architecture-reference.md 获取蓝图。

3. 研究所有工具和 API — 不要假定自己熟悉任何平台或库。即使是 Gmail 或 Slack 等常见 API，也有与实现相关的细节、速率限制和 SDK 专属模式。对于用户技术栈中的每种工具，都要进行网络调研，确保 PRD 提供准确、具体的指导。

   始终研究以下核心依赖项：

   • Claude Agent SDK — 如何创建对话、使用 system_prompt 预设、设置 setting_sources 和 allowed_tools、处理流式响应及凭据
   • FastEmbed — ONNX 模型加载、批量嵌入 API、模型缓存配置、支持的模型
   • Hook 系统 — Claude Code 的 Hook 类型（PreToolUse、PostToolUse 等）、回调签名、settings.json 配置

   针对用户选择的每个平台（Gmail、Slack、Linear、HubSpot 等）：

   • 身份验证方式（OAuth2 流程、API 令牌、机器人令牌等）
   • 要使用的关键 SDK/库（例如，google-api-python-client、slack_sdk 等）
   • 用户最重要任务所需的具体 API 端点
   • 平台特定的设置要求（例如，Slack Socket Mode 需要 App Token 和 Bot Token；自定义域名使用 Gmail 时，需要将 OAuth 同意屏幕发布到 Production）
   • 速率限制、分页模式和常见问题

   目标： PRD 的每个阶段都应包含足够具体的技术信息，让编码 Agent 无需猜测即可实现。不要在 PRD 中堆砌原始调研内容，而应将其提炼为各阶段可执行的实现说明。

4. 生成 PRD — 在输出路径（$1，或未指定时使用 .agent/plans/second-brain-prd.md）创建分阶段构建计划，包含以下章节：

PRD 结构

生成的 PRD 应包含：

标题信息：

• 项目名称（个性化为“[用户姓名]的 Second Brain”）
• 生成日期
• 概述：根据用户最重要的任务撰写 1–2 句话 阶段 1：基础（记忆层）
• 使用用户在“记忆库文件夹名称”中指定的名称创建记忆库文件夹（例如，MyVault/Memory/）。切勿将“Dynamous”硬编码；始终使用用户选择的名称。
• 如果用户使用 Obsidian，将其说明为查看器；如果没有，则说明该记忆库只是一个可与任何编辑器配合使用的 Markdown 文件文件夹。
• 创建 SOUL.md、USER.md、MEMORY.md、BOOTSTRAP.md 和 daily/ 结构
• BOOTSTRAP.md 是首次运行引导脚本：在用户首次启动 Claude Code 会话时，它会通过互动对话个性化 USER.md、SOUL.md 和 HEARTBEAT.md（询问姓名、时区、角色、沟通风格、集成项、主动性偏好——一次只问一个问题）。引导完成后，它会自行删除。如果会话在引导过程中结束，该文件会保留，并在下次继续。SessionStart 钩子应检测 BOOTSTRAP.md 并将其注入上下文。
• 在仓库根目录创建 CLAUDE.md——这是 Claude Code 的项目指令文件，会加载到每次对话中。初始化时加入：项目描述、关键路径（记忆库、脚本、钩子、技能、数据目录）、项目约定（时区、顾问模式、记忆库中不得存放机密、复选框语法、YAML 前置元数据），以及一个在每个阶段完成后更新的“已完成阶段”部分。还要添加一个“构建命令”部分——先放占位条目，之后每个阶段引入真实命令时再补充。该文件是 Agent 与项目交互时的参考。
• 根据用户对“关于你”和“记忆类别”的回答自定义每个文件
• 要创建的关键文件，预计复杂度：低

阶段 2：钩子（上下文持久化）

• SessionStart 钩子（将记忆注入每次对话——还应检测并注入 BOOTSTRAP.md，以支持首次运行引导）
• PreCompact 钩子（提取对话上下文 → 启动后台 memory_flush.py）
• SessionEnd 钩子（采用相同模式——提取上下文 → 启动后台刷新）
• memory_flush.py：由 PreCompact/SessionEnd 启动的后台 Agent SDK 脚本。使用 allowed_tools=[] 的 Claude（纯推理，不使用工具）智能判断对话中值得保存的决策、经验和事实。将项目符号摘要写入每日日志。具备去重和文件锁定功能。这一点至关重要——否则每日日志会包含机械的对话摘录，而非可由每日反思提炼并写入 MEMORY.md 的智能摘要。
• 防止钩子递归：每个 Agent SDK 会话（心跳、反思、聊天、记忆刷新）都必须设置 os.environ["CLAUDE_INVOKED_BY"] = "<name>"。SessionEnd 和 PreCompact 钩子会检查此环境变量，若已设置则跳过——这样可防止 Agent SDK 退出时触发额外刷新，避免产生重复日志条目或无限递归。
• 共享实用工具（shared.py）：跨平台文件锁定（在 Windows 上使用 msvcrt、在 Unix 上使用 fcntl 实现 file_lock()），确保并发写入安全；使用指数退避的重试机制（with_retry()）处理外部 API 调用；以及原子状态写入。多个进程（心跳、反思、聊天、刷新）会同时写入每日日志和状态文件——若没有文件锁定，它们会互相破坏对方的数据。
• 关键文件，预计复杂度：中

阶段 3：记忆搜索（混合 RAG）

• 设置分块 + 嵌入流程
• SQLite + sqlite-vec + FTS5（本地）或 Postgres + pgvector（VPS）
• 混合搜索：0.7 向量 + 0.3 关键词
• 关键文件，预计复杂度：中

阶段 4：集成（先做排名前三的集成项）

• 使用用户的“集成优先级”排名
• 对每项集成：身份验证设置、API 模块、注册表条目、query.py 子命令
• 参考 integration_template.py 模式
• 每项集成的关键文件，预计复杂度：中 阶段 5：技能（入门包）
• Vault 结构技能（向 Agent 介绍其文件组织方式）
• 至少一个基于其“高频任务”的自定义技能
• 技能结构：SKILL.md + scripts/ + references/
• 关键文件，预计复杂度：低至中

阶段 6：主动式系统（心跳 + 反思）

• 心跳流程必须按以下阶段执行：(1) Python 从集成中收集数据 → (2) 状态差异比对 → (3) 预检护栏 Agent（参见阶段 8 — 单独的无工具 Claude 调用，用于评估经过净化的外部数据，并在主心跳 Agent 看到数据之前返回 {verdict: "pass"|"fail"|"suspicious"}；fail 会中止运行，suspicious 则发出警告后继续）→ (4) 使用工具进行推理的主 Claude Agent SDK 调用 → (5) 通知。预检护栏步骤不可省略——它是安全栈中唯一的语义注入检查，必须直接接入心跳流水线，而不能作为单独阶段附加。
• 状态差异比对（心跳流程的第 2 阶段）：实现 build_snapshot(gmail_data, asana_data, slack_data, calendar_data, ...) 和 diff_snapshot(current, previous) 函数，以生成每个集成当前状态的可哈希快照，并计算与上次运行相比的差异。将状态持久化到 .claude/data/state/heartbeat-state.json（通过 shared.py 原子写入）。只有差异内容——新邮件、新逾期任务、新的未读 Slack 消息——会传入主 Claude 推理调用。这是解决通知疲劳问题的方法：如果没有状态差异比对，每次 30 分钟运行都会重新提示相同的未读邮件，用户会不断收到通知。没有这个机制，心跳在生产环境中将无法使用。必须将其列为具名交付项，并使用这些确切的函数名称，以便学生能在生成的 PRD 中追踪此模式。
• 根据用户的主动性级别设置计划
• 每日反思：将每日日志中的重要条目提升至 MEMORY.md。必须包含 SOUL.md 写入保护——一个 PreToolUse 钩子，用于阻止反思 Agent 编辑 SOUL.md。如果反思过程想要对 Agent 的身份或规则提出修改建议，应将这些建议写入每日日志。这可防止“灵魂漂移”，即 Agent 在未经用户批准的情况下逐渐改写自己的个性。
• 将用户选择的主动性级别映射到具体的心跳行为
• 草稿管理（Advisor/Assistant/Partner 主动性级别必需）：心跳必须实现完整的草稿生命周期系统。具体而言：(1) 扫描集成数据，查找需要回复的邮件、私信和社区帖子；(2) 使用 drafts/sent/ 上的 RAG 生成符合用户语气的草稿回复（用于匹配语气的 memory_search.py --path-prefix drafts/sent）；(3) 将草稿写为 drafts/active/ 中的 Markdown 文件，包含 YAML 前置元数据（type、source_id、recipient、subject、context、created、status）以及 Original Message + Draft Reply 部分；(4) 对超过 24 小时且未采取任何操作的草稿进行过期处理，将其移至 drafts/expired/；(5) 检测用户是否已在平台上实际回复，并将文件移至 drafts/sent/，同时记录用户的真实回复文本。心跳 Agent SDK 会话需要具备 Write/Edit 工具才能创建草稿文件——仅有只读工具是不够的。草稿生成标准应在 USER.md 中定义（要起草什么、跳过什么）。
• 习惯追踪：包含可自定义支柱的 HABITS.md、用于客观成就的自动检测规则、由心跳执行的每日重置，以及针对未勾选支柱的日末提醒
• 关键文件，预计复杂度：高

阶段 7：聊天界面（可选）

• 仅在用户选择的平台中勾选了 Chat/Messaging 时才纳入
• 具有持久化对话功能的 Slack/Discord 机器人
• 用于扩展的平台适配器模式
• 关键文件，预计复杂度：高 第 8 阶段：安全加固
• 凭据保护钩子（block-secrets.py）：PreToolUse 钩子，用于拦截所有文件访问工具（Read、Bash、Grep、Edit、Write、Glob），阻止访问 .env 文件、API 令牌、OAuth 凭据、SSH 密钥及其他机密。还会阻止可能泄露环境变量的 Bash 命令，以及会将机密泄露到标准输出的脚本写入操作。这是最关键的安全组件——没有它，大模型可能会意外读取并泄露所有 API 密钥。必须将其实现为独立的专用钩子（不能与通用命令防护合并）。
• 清理所有外部数据（3 层防御：模式检测 → Markdown 转义 → XML 信任边界）。XML 封装必须搭配系统提示词中的 TRUST_BOUNDARY_INSTRUCTION，明确告知 Claude 将 <external_data> 标签内的所有内容视为数据，而非指令——只有封装而没有指令，防御就不完整。
• 预检防护 Agent：在主心跳 Agent 处理传入的外部数据之前，使用 allowed_tools=[] 单独调用一次 Claude Agent SDK，并向其提供清理后的上下文，让它返回 {"verdict": "pass"|"fail"|"suspicious"}。遇到 fail → 中止本次心跳运行并记录被拦截的内容。遇到 suspicious → 继续执行，并在每日日志中记录警告。遇到 pass → 继续进行主推理调用。这是安全体系中唯一的语义检查（其他层全部基于模式），可捕获绕过确定性正则表达式的注入尝试。将其接入第 6 阶段的心跳流程，置于状态差异比较与主 Agent 调用之间，而不是作为独立工具。
• 根据其安全边界问题的回答设置命令防护。实现必须在 shared.py 中包含一个名为 DANGEROUS_BASH_PATTERNS 的列表，列出 30 个以上的模式，涵盖破坏性操作（rm -rf、dd、mkfs）、绕过防护窃取凭据的方式（向未知主机执行 curl、将 wget 的输出通过管道传给 shell）、软件包安装（pip install、npm install、brew install）、权限提升（sudo、chmod 777），以及向非允许列表中的域名发起的出站网络调用。检查必须递归提取子 Shell $(...) 和反引号 `...` 结构，并重新检查其中的内容（简单的字符串匹配可通过 $(echo rm\ -rf\ /) 绕过）。匹配前去除常见的二进制文件路径前缀（/usr/bin/、/bin/）。这与 block-secrets.py 不同（它用于保护凭据文件）；DANGEROUS_BASH_PATTERNS 用于防范破坏性命令和数据窃取命令，并且每次 PreToolUse Bash 调用都必须运行这两个钩子。
• API 密钥隔离（Python 命令行包装器模式）
• 关键文件，预计复杂度：中高

第 9 阶段：部署

• 根据其基础设施问题的回答
• 本地部署：设置 OS 调度程序（Windows Task Scheduler / cron / launchd）
• 如果使用 VPS：服务器设置、保险库同步、SSH 隧道
• 使用 concat-both 合并驱动进行保险库同步（用户选择“本地 + VPS”时必需）：在两台机器上使用 git-sync（simonthum/git-sync 或同等工具），每 2 分钟通过 Git 同步保险库。每日日志（Memory/daily/*.md）采用仅追加写入模式，并由两台机器上的心跳、反思、聊天和刷新进程并发写入——简单的 Git 合并会在每次同步时产生冲突。解决方案：在 .gitattributes 中注册自定义的 concat-both 合并驱动，将 Memory/daily/*.md 映射到一个脚本，由该脚本拼接两侧新增内容，而不是产生冲突。驱动脚本（git-merge-concat）接收祖先、本地和远程版本，以远程版本为基础，并追加本地添加的、尚未存在的行。没有这个驱动，保险库同步将在实际使用的第一天内中断，用户也会放弃使用该系统。必须将其作为一个具名交付项，包含脚本路径、.gitattributes 条目，以及每台机器上用于注册驱动的 git config merge.concat-both.driver 命令。
• 根据其选择估算成本 每个阶段包括：
• 要构建的内容（1–2 句话）
• 要创建的关键文件（含路径）
• 依赖项（必须先完成哪些阶段）
• 预估复杂度（低／中／高）
• 个性化说明（他们的具体回答如何影响此阶段）
• CLAUDE.md 更新提醒：每个阶段结束时，都必须更新 CLAUDE.md，加入新路径、构建命令和约定。这样可以让 Agent 的项目参考信息保持最新——如果某条命令存在但未写入 CLAUDE.md，Agent 就不会知道它。

页脚：

• 建议的构建顺序（各阶段大多按顺序进行，但部分阶段可以并行）
• “此 PRD 根据您的需求生成。请随着系统的发展重新审视并更新。”

5. 确认输出——告知用户 PRD 的保存位置（输出路径），并建议他们从阶段 1 开始。

个性化规则

• 在文件路径中始终使用他们的保险库文件夹名称（不要使用“Dynamous”，而要使用他们在“Memory vault folder name”中填写的名称）。例如，如果他们填写了“SecondBrain”，所有路径都应为 SecondBrain/Memory/、SecondBrain/Memory/daily/ 等。
• 如果他们不使用 Obsidian，就不要在 PRD 中提及 Obsidian——只需将保险库称为“记忆保险库”或“Markdown 文件夹”。如果他们使用 Obsidian，则将其作为查看器／编辑器提及。
• 始终使用他们选择的平台名称（不要泛称“电子邮件”——如果他们选择了“Gmail”，就使用“Gmail”）
• 将他们的主动性级别映射为具体行为：
  • Observer → 仅发送心跳通知，不起草内容，不跟踪习惯
  • Advisor → 心跳通知 + 起草电子邮件／消息供审核，并提供习惯跟踪建议，但不自动检查
  • Assistant → 心跳通知 + 起草内容 + 自动整理文件 + 自动记录；对客观支柱进行习惯自动检测
  • Partner → 包含以上所有功能 + 发送低风险消息 + 自动完成日常任务 + 全面自动检测习惯
• 将他们的安全边界直接映射到阶段 8 的防护规则中
• 使用他们的记忆类别来规划阶段 1 中的保险库文件夹结构
• 他们的集成优先级决定阶段 4 的顺序