shiplog：AI编程知识图谱化，告别会话失忆，打造可追溯的Git协作流

1. 项目概述：为AI编程打造一个永不遗忘的“航海日志”

如果你和我一样，深度使用过Claude Code、Cursor这类AI编程助手，那你一定对一种“失忆症”深恶痛绝：昨天和AI助手花了半小时头脑风暴出的架构设计，今天打开新会话，它忘得一干二净；上周为了解决一个棘手的边界情况，尝试了三种方案并最终选择了其中一个，现在想回顾为什么选它，却发现这些决策过程像水蒸气一样蒸发在无数条聊天记录里，无从追溯。我们每天都在创造大量高价值的“过程知识”——设计权衡、被否决的方案、中途发现的陷阱——但这些知识却随着聊天窗口的关闭而永久丢失。shiplog就是为了根治这个问题而生的。

简单来说，shiplog是一个AI编程辅助技能（Skill），它把你的Git和GitHub仓库，从一个单纯的代码版本控制系统，转变为一个持久化、可查询的“项目知识图谱”。它强制性地将每一次AI协作的思考过程、决策理由和发现的问题，以结构化的方式（GitHub Issue、带上下文的Commit、包含完整时间线的PR）固化下来。这不仅仅是记录“你改了哪行代码”，更是记录“你为什么改这行代码”、“你考虑过哪些其他方案”、“你在改的过程中发现了什么新问题”。它让项目的Git历史成为一份详实的“船长日志”，任何后来者（包括未来的你自己，或者另一个AI模型）都能快速理解项目的完整脉络。

2. 核心设计理念：从“会话失忆”到“持久化知识图谱”

2.1 传统AI编程工作流的根本缺陷

在没有shiplog之前，典型的AI编程流程是线性的、孤立的，并且严重依赖短期记忆：

1. 头脑风暴：在聊天界面与AI讨论一个功能（例如“设计用户认证中间件”）。
2. 实施编码：基于讨论结果，让AI生成代码片段，你进行复制粘贴或直接编辑。
3. 提交代码：使用git commit -m “feat: add auth middleware”提交。
4. 开启新会话：第二天，针对另一个功能开启新聊天，昨天的所有上下文（为什么选JWT而不是Session？中间件错误处理逻辑的权衡是什么？）全部丢失。

这个流程存在几个致命问题：

• 知识断层：决策依据和替代方案没有留下任何可搜索的记录。
• 上下文丢失：新的AI会话无法继承之前的“工作记忆”，每次都要从头解释。
• 发现即丢失：编码过程中发现的相关Bug或优化点，很容易被当作“支线任务”忽略或遗忘在聊天记录里。
• 审查流于形式：如果让同一个AI模型审查自己的代码，无异于自我确认，缺乏真正的制衡。

2.2 shiplog 的解决方案：六阶段工作流

shiplog将上述松散的工作流，规范化为一个可追溯、可搜索的六阶段闭环。每个阶段都产出结构化的、与GitHub深度集成的“工件”（Artifact）。

2.2.1 第一阶段：计划（Plan）—— 将头脑风暴固化为Issue

当你有一个新想法时，不再只是在聊天窗口里空谈。使用/shiplog plan 设计用户认证中间件命令，shiplog会引导AI（通常是你配置的“推理层”模型，如Claude Opus）进行结构化思考，并自动创建一个GitHub Issue。

这个Issue不是简单的任务描述，而是一个设计文档，它包含：

• 目标：清晰定义要解决的问题。
• 考虑过的方案：例如，方案A（JWT）、方案B（Session）、方案C（第三方OAuth）。
• 决策与理由：为什么最终选择方案A（例如，无状态、更适合微服务）。
• 任务清单（Tasks）：将大目标拆解为可执行的小任务，如 T1: 实现JWT生成与验证， T2: 编写中间件逻辑， T3: 添加单元测试。
• 预定义的验证策略：引用项目或Issue级别的测试规范（如behavior-spec）。

实操心得：这一步最关键的是“强制结构化”。它避免了AI天马行空的讨论最终落不到实处。生成的Issue成为了后续所有工作的“宪法”和唯一真相源。我习惯在计划阶段就与AI明确“哪些文件允许修改”、“决策预算是多少”（例如，不允许擅自更改数据库Schema），这为后续的委托执行打下了坚实基础。

2.2.2 第二阶段：开始（Start）—— 创建隔离的工作环境

有了计划（Issue #42），接下来是执行。使用/shiplog start 42。这个命令做了几件聪明的事：

1. 创建特性分支：例如feature/auth-middleware。
2. 创建Git工作树（Worktree）：这是一个独立的目录，将上一步的Issue内容作为“工作记忆”加载进来，为AI提供完整的上下文。工作树保证了每个功能开发环境的物理隔离，避免了切换分支的麻烦和状态污染。
3. 启动工作会话：AI模型（此时可能切换到更高效的“执行层”模型，如Claude Haiku）在这个隔离的、上下文充沛的环境中开始编码。

2.2.3 第三阶段：发现（Discover）—— 问题分类与路由

这是shiplog最精妙的设计之一。在编码过程中，AI几乎必然会发现一些计划外的问题：一个隐藏的Bug、一个可以优化的代码结构、一个缺失的依赖。传统流程中，这些“发现”要么被忽略，要么把当前工作带偏。

shiplog的发现协议（Discovery Protocol）会即时对问题进行分类和路由：

• 小修复（<30分钟）：直接在当前分支内联修复，并在时间线中添加一条注释，说明这个“发现”及其处理方式。
• 当前工作的前置条件：例如，实现认证中间件前，必须先修复一个底层库的安全漏洞。shiplog会为此创建一个新的、堆叠的（Stacked）分支和PR，并链接到主Issue。当前工作暂停，先解决前置问题。
• 独立但重要的问题：创建一个全新的GitHub Issue，打上相应标签（如bug），然后继续当前工作。这个新Issue会被记录，不会丢失。
• 重构机会：创建一个标记为refactor的Issue，留待日后处理。

注意事项：这个协议的核心是“永不丢失”。它把开发中不可避免的“意外”变成了可管理的、被记录的工作项。我强烈建议在项目配置中启用它，这能极大提升代码库的长期健康度。

2.2.4 第四阶段：提交（Commit）—— 附加上下文的提交

传统的提交信息如git commit -m “fix: validation logic”信息量极少。shiplog的提交是“ID优先”且富含上下文的。 执行/shiplog commit时，它会：

1. 分析暂存区的变更。
2. 自动关联到当前工作的Issue和具体任务（Task）。例如，生成提交信息：feat(#42/T1): add JWT validation。这直接建立了提交与工作项的链接。
3. 对于复杂的变更，它会提示你添加一个“上下文注释”，解释这个变更背后的原因、尝试过的其他方法、以及需要警惕的边界情况。这个注释会作为提交信息的一部分保存下来。

2.2.5 第五阶段：交付（Ship）—— 讲述完整故事的PR

工作完成后，使用/shiplog pr创建拉取请求（Pull Request）。这个PR的正文不是简单的代码差异列表，而是一个完整的旅程时间线，它自动汇总了：

• 原始Issue的设计目标和方案。
• 开发过程中所有的“发现”及其处理结果（内联修复、堆叠PR、新建Issue）。
• 每个关键提交的上下文注释。
• 最终的决策总结和学到的经验。

更重要的是，shiplog强制跨模型审查（Cross-model Review）。PR不能由编写它的同一个AI模型合并。必须由另一个AI模型（或人类）进行审查。审查意见会带有Reviewed-by:签名。这从根本上避免了AI“自写自审”的无效流程，引入了必要的制衡。

shiplog提供两种模式：

• 完整模式（Full Mode）：上述所有丰富上下文直接写入主PR描述。适合个人项目或开源项目，追求完整的可追溯性。
• 安静模式（Quiet Mode）：这是我认为最“聪明”的特性。主PR（feature/auth-middleware）保持干净、专业，只包含简洁的修改说明。而所有的详细讨论、决策过程和“航海日志”则被写入一个平行的--log分支（feature/auth-middleware--log）。团队成员看到的是整洁的PR，但只需一次点击，就能查看背后全部的思想历程。完美平衡了工程严谨性和团队协作体验。

2.2.6 第六阶段：搜索（Lookup）—— 全局知识检索

当未来你需要回顾“当初为什么选择JWT”或“那个缓存穿透问题是怎么解决的”时，你不再需要翻找聊天记录。使用/shiplog lookup JWT或直接使用GitHub搜索、ghCLI命令，可以跨维度搜索：

• gh issue list --search “Authored-by: claude/”：查找所有Claude参与的讨论。
• gh pr list --search “Reviewed-by:”：查找所有经过审查的PR。
• git log --all --oneline --grep=”#42”：查找所有与Issue #42相关的提交。 所有信息都通过#ID（如#42,#42/T1）和作者身份签名（如Authored-by: claude/opus-4.6 (claude-code)）紧密关联，形成了一个真正的、基于GitHub的知识图谱。

3. 核心功能深度解析与实操配置

3.1 模型分层路由（Model-Tier Routing）

不是所有任务都需要最强大（也最昂贵）的AI模型。shiplog允许你根据工作阶段，智能地分配不同层级的模型，优化成本与效率。这需要在项目根目录或用户全局配置中进行定义。

配置示例（.shiplog/routing.md）：

# 模型路由配置 - phase: plan tier: tier-1 models: [claude-3-opus, claude-3-5-sonnet] # 用于架构设计和复杂头脑风暴 - phase: start tier: tier-2 models: [claude-3-5-sonnet, gpt-4] # 用于加载复杂上下文和创建结构化文档 - phase: implement tier: tier-3 models: [claude-3-haiku, gpt-4o-mini] # 用于高效的代码实现和常规提交 - phase: review tier: tier-2 # 审查需要一定的理解能力，但不必是最顶级的 models: [claude-3-5-sonnet, gemini-1.5-pro] cross-model-required: true # 强制要求审查模型与作者模型不同

实操要点：

• 阶段（Phase）感知：当从一个阶段过渡到另一个阶段（如从Plan到Start）时，shiplog会提示你切换模型，并自动将上一个阶段的输出作为结构化上下文传递给下一个模型。
• 委托合同（Delegation Contract）：当从高 tier 模型（如 Opus）向低 tier 模型（如 Haiku）交接时，高 tier 模型必须生成一份明确的“合同”，规定：允许修改的文件列表、禁止更改的部分、停止条件（如“如果遇到X情况，立即停止并上报”）、验证要求。如果这份合同不够具体，导致执行模型仍需做主观判断，那么交接就是不成功的。

3.2 验证策略（Verification Profiles）

为了保证代码质量，尤其是当工作被委托给更快的“执行层”模型时，shiplog引入了可配置的、可继承的验证策略。这些策略像“旅行指南”一样，随着任务一起传递。

配置示例（.shiplog/verification.md）：

# 项目级默认验证策略 default: - red-green # 红绿测试：要求先写失败测试，再实现功能使其通过 - structural # 结构分析：对变更的模块进行代码复杂度、重复度检查 # 针对特定类型Issue的强化策略 profiles: security: inherits: [default] add: - behavior-spec # 行为规约：必须明确描述安全场景，任何修改需人工确认 refactor: inherits: [default] add: - mutation # 变异测试：确保重构不会改变程序行为 remove: - red-green # 重构可能不涉及新功能，移除红绿测试要求

策略说明：

• 行为规约 (behavior-spec)：用自然语言描述功能的接受场景。任何代码变更如果触及这些规约，需要明确的人工或高级AI确认。
• 红绿测试 (red-green)：经典的TDD流程，确保测试驱动开发。
• 结构分析 (structural)：使用类似CodeQL或自定义脚本，分析变更代码的圈复杂度、依赖关系等。
• 变异测试 (mutation)：在变更行注入微小错误（变异），确保测试套件能捕获这些错误。这是检测测试用例有效性的强力手段。

这些策略可以在项目、Issue甚至单个任务级别进行配置，遵循“仅收紧，不放松”的继承原则，确保质量底线。

3.3 工件信封与智能代理（Artifact Envelopes）

AI处理长文本消耗大量token和计算资源。shiplog为每个在GitHub上生成的工件（Issue、PR评论）添加了机器可读的“信封”——隐藏在HTML注释中的结构化元数据。

例如，一个Issue的HTML注释可能包含：

<!-- shiplog-envelope: type: issue id: 42 author: claude/opus-4.6 phase: plan tasks: - id: T1 status: pending verification: [red-green] - id: T2 status: pending tags: [auth, backend] -->

人类看到的是干净的Markdown正文，而AI代理在获取该Issue时，可以先快速读取这个“信封”，了解其类型、状态、关联任务和验证要求，从而决定是否需要深入阅读全文。这大大节省了上下文窗口的消耗，让AI能更高效地“浏览”和“理解”项目状态。

3.4 证据链接的闭环（Evidence-Linked Closure）

在shiplog的体系里，一个Issue不能简单地被手动关闭。它必须通过链接证据来关闭。证据可以是：

• 一个合并的PR链接。
• 一个包含相关修复的Commit URL。
• 一个记录决策的讨论链接。

当执行/shiplog pr并合并后，shiplog会自动在关联的Issue中引用该PR作为证据，并将其状态更新为已完成。如果系统检测到模糊的匹配（例如，提交信息提到了“fix #42”但变更内容不直接相关），它会将问题上报，而不是静默关闭。这确保了项目待办列表（Backlog）的准确性和可靠性。

4. 完整实操流程：从零构建一个功能

让我们通过一个完整的例子，看看如何用shiplog协作开发一个“用户个人资料头像上传”功能。

4.1 环境准备与安装

首先，确保你的环境符合要求：

1. 安装Git：这应该是开发者的标配。
2. 安装GitHub CLI (gh)：这是shiplog与GitHub交互的核心。访问 cli.github.com 安装，并通过gh auth login完成认证。
3. 初始化一个Git仓库并关联到GitHub远程仓库。
4. 安装shiplog：在你的AI编程工具中（以Claude Code为例），在项目根目录下执行：

   npx skills add devallibus/shiplog --skill shiplog --agent claude-code

   这会将shiplog技能安装到当前项目的.claude/skills/目录下。

4.2 第一阶段：计划——创建设计工单

在Claude Code的聊天框中，输入：

/shiplog plan 实现用户个人资料头像上传功能，支持裁剪和压缩

shiplog被激活，它会调用你配置的“推理层”模型（如Claude Opus）来引导一场结构化的头脑风暴。模型会询问细节，例如：

• 上传文件大小限制是多少？
• 支持哪些图片格式？（JPG, PNG, WebP）
• 是否需要客户端裁剪，还是服务端裁剪？
• 图片存储在哪里？（本地文件系统、S3、云存储）
• 如何生成缩略图？

经过几轮交互，shiplog最终会在你的GitHub仓库中创建一个新的Issue，假设编号为#58。这个Issue的正文将包含：

• 目标：允许用户上传、裁剪并压缩头像图片。
• 方案权衡：
  • 方案A：使用multer中间件 +sharp库进行服务端处理。优点：控制力强，一致性高。缺点：增加服务器负载。
  • 方案B：使用Uppy等前端库进行客户端裁剪压缩后上传。优点：减轻服务器压力，用户体验好。缺点：依赖客户端JavaScript，处理逻辑暴露。
  • 决策：采用混合方案。前端进行初步裁剪和预览，后端使用sharp进行最终格式转换、压缩和安全校验。
• 任务分解：
  • T1: 前端实现图片选择、裁剪预览组件。
  • T2: 后端创建图片上传API端点（POST /api/user/avatar）。
  • T3: 集成sharp库，实现图片压缩、格式转换和缩略图生成。
  • T4: 设计图片存储服务（本地开发用磁盘，生产环境用S3）。
  • T5: 更新用户模型，关联头像URL。
• 验证策略：继承项目默认的red-green和structural策略，并为T2、T3添加behavior-spec，明确安全边界（如文件类型、大小校验）。

4.3 第二阶段：开始——进入编码工作区

现在，基于这个完善的计划开始编码。输入：

/shiplog start 58

shiplog会执行以下操作：

1. 从远程拉取最新代码。
2. 基于main分支创建一个新分支，例如feature/user-avatar-upload。
3. 在项目目录外（或指定位置）创建一个对应的Git工作树（worktree），例如../worktrees/project-avatar-upload。
4. 将你的终端上下文切换到这个新的工作树目录。
5. 将Issue #58的全部内容作为系统提示或初始上下文，加载到AI会话中。现在，AI模型（可能根据路由配置切换到了“执行层”的Haiku）完全清楚要做什么、为什么这么做、以及具体的任务清单。

4.4 第三与第四阶段：编码、发现与提交

你在工作树中开始编码。假设在实现T2（上传API）时，AI发现现有的请求体验证中间件对文件上传支持不好。

发现与路由：AI会触发发现协议。shiplog判断这是一个“当前工作的前置条件”。它会：

1. 暂停当前头像上传功能的开发。
2. 自动创建一个新的堆叠Issue，例如#59: 增强请求验证中间件以支持multipart/form-data。
3. 将当前分支的父分支改为main，并基于#59创建一个新的堆叠分支feature/improve-validation。
4. 引导你先解决这个前置问题。在这个新分支上完成验证中间件的增强并提交。
5. 提交信息会是fix(#59): extend validation middleware to support file uploads。
6. 完成后，将头像上传功能分支的父分支重新指向这个新分支，形成堆叠关系。

继续与提交：解决前置问题后，回到头像上传功能。完成T1前端组件后，执行/shiplog commit。shiplog会分析变更，自动生成提交信息feat(#58/T1): implement frontend avatar cropper component。如果变更复杂，它会提示：“是否要添加上下文注释？例如，为什么选择这个特定的裁剪库？” 你可以让AI补充：“选择react-avatar-editor而非cropperjs，因其与现有React技术栈集成度更高，且支持触摸屏。”

4.5 第五阶段：交付——创建包含时间线的PR

所有任务完成后，执行/shiplog pr。shiplog会：

1. 推送所有分支到远程。
2. 为当前功能分支（以及任何堆叠的父分支）创建PR。
3. 生成PR描述，这是一个完整的故事：
   • 链接：Addresses #58。
   • 时间线：
     • 2023-10-27 [Plan]: 初始设计决策（混合方案）。
     • 2023-10-27 [Discovery]: 发现验证中间件限制，创建前置Issue #59。
     • 2023-10-28 [Commit]: 完成前置修复 (#59)。
     • 2023-10-28 to 29 [Commit]: 依次完成T1到T5。
     • 2023-10-29 [Discovery]: 在实现T3时，发现sharp的某版本在ARM Mac上有兼容性问题，降级到稳定版本并在时间线中记录。
   • 验证结果：自动运行配置的验证策略（如单元测试、结构分析）并将结果摘要附上。
   • 请求审查：根据配置，shiplog会要求另一个AI模型（如Claude Sonnet）或项目协作者来审查这个PR。审查意见会带有Reviewed-by: claude/3-5-sonnet的签名。

4.6 第六阶段：搜索与继承

一周后，你需要开发另一个与用户相关的功能，比如“个人资料背景图上传”。你可以：

• 使用/shiplog lookup avatar快速找到所有相关的讨论、PR和提交。
• 直接参考#58这个“知识节点”，里面已经包含了所有关于图片处理、存储方案、安全考量的决策记录。新的AI会话能立刻继承这些上下文，无需重复讨论。
• 查看#59了解验证中间件的增强细节，确保新功能与之兼容。

5. 常见问题与排查技巧实录

在实际使用shiplog的过程中，你可能会遇到一些典型问题。以下是我踩过坑后总结的排查清单：

5.1 安装与初始化问题

问题1：执行npx skills add命令失败，提示权限或网络错误。

• 排查：首先确保Node.js版本在16以上。npx可能受网络代理影响。可以尝试使用npm config set registry https://registry.npmmirror.com切换镜像源，或直接使用npm install -g @skills/cli全局安装skills CLI后再尝试。
• 备用方案：如果网络问题持续，可以采用“手动复制”安装法。直接从shiplog的GitHub仓库下载skills/shiplog目录，复制到你的项目.claude/skills/或全局目录~/.claude/skills/下。

问题2：gh命令认证失败，shiplog无法创建Issue或PR。

• 排查：运行gh auth status检查登录状态。确保你拥有目标仓库的写入权限。
• 解决：重新运行gh auth login，选择HTTPS或SSH方式，并确保授予足够的权限（repo, write:discussion等）。对于企业GitHub，可能需要使用gh auth login --hostname github.company.com。

5.2 工作流执行问题

问题3：/shiplog start <issue>失败，提示找不到Issue或分支已存在。

• 排查：
  1. 确认Issue编号正确，且存在于当前仓库。
  2. 检查本地是否已存在同名的分支或工作树。使用git branch -a和git worktree list查看。
• 解决：
  • 如果分支已存在，可以使用/shiplog resume命令来恢复该分支上的工作会话。
  • 如果工作树冲突，可以手动删除旧的工作树目录：rm -rf <worktree-path>，然后使用git worktree prune清理。

问题4：在“安静模式”下，团队成员看不到详细的决策日志。

• 误解澄清：这是设计如此，而非问题。“安静模式”下，主PR (feature/xxx) 是干净的。详细的日志在feature/xxx--log分支。
• 操作：在GitHub的PR页面上，点击“分支”下拉菜单，选择带--log后缀的分支，即可查看完整的、包含所有讨论和上下文的版本。你需要告知团队成员这一查看方式。

问题5：AI模型在提交时没有生成符合规范的提交信息（缺少#ID/Tx格式）。

• 排查：检查当前工作目录是否在一个由shiplog start创建的工作树中，并且.git目录链接正确。
• 解决：确保在执行/shiplog commit前，shiplog技能已被正确激活。有时在复杂的终端会话中，上下文可能丢失。可以尝试退出当前目录，重新进入工作树，或重新启动AI编程助手会话。

5.3 配置与高级功能问题

问题6：模型路由不生效，始终使用同一个模型。

• 排查：检查项目根目录或用户配置目录下是否存在.shiplog/routing.md文件，且格式正确。
• 解决：确保你的AI编程助手（如Claude Code）支持模型切换，并且你在其设置中已正确配置了对应模型的API密钥或访问权限。shiplog只负责发出切换指令，实际调用能力取决于宿主工具。

问题7：验证策略（如mutation测试）执行失败或找不到。

• 排查：验证策略依赖于外部工具。例如，mutation策略可能需要stryker或pitest等变异测试框架。
• 解决：在.shiplog/verification.md中，你可以为每个策略指定执行命令。例如：

  mutation: command: “npm run test:mutation”

  你需要先在项目中配置好相应的npm脚本和测试框架。

问题8：/shiplog hunt命令给出的优先级排序不符合预期。

• 原理：hunt命令会扫描开放的Issue和PR，根据多种因素（如标签、创建时间、依赖关系、评论活跃度）计算一个“就绪度”分数。
• 调整：你可以通过给Issue打上shiplog/priority-high或shiplog/blocker等shiplog预定义的标签来影响其排序。也可以根据项目情况，自定义hunt的排序算法（这需要修改技能脚本，属于高级用法）。

5.4 理念与文化适配问题

问题9：团队觉得流程太繁琐，增加了开销。

• 沟通要点：这是从“牛仔式编程”向“工程化协作”转型的阵痛。需要强调shiplog的长期价值：
  1. 降低新人上手成本：完整的知识图谱让新成员能快速理解代码背后的“为什么”。
  2. 减少重复讨论：决策被记录，避免同一个问题被反复讨论。
  3. 保障代码质量：强制审查和验证策略，减少了Bug引入。
  4. 安静模式：正是为团队协作设计，主PR保持简洁。
• 渐进式采纳：可以先在个人项目或团队的一个小项目中试点，让成员体验其搜索和追溯的便利性。

问题10：AI生成的上下文注释或PR描述过于冗长。

• 调整：你可以在与AI交互时，给出更明确的指令。例如，在计划阶段就说：“请生成简洁的设计摘要，重点记录关键决策和否决方案，省略显而易见的细节。”shiplog本身是一个框架，产出内容的质量和风格很大程度上取决于你如何引导AI。
• 善用“信封”：记住，冗长的Markdown是给人看的，AI在检索时主要看“信封”元数据。所以内容的详尽对机器检索影响不大，主要影响人类阅读体验。可以根据团队偏好调整提示词。

我个人在深度使用shiplog几个月后，最大的体会是它改变了我与AI协作的“心智模式”。我不再把AI对话看作一次性的、用完即弃的“魔法咒语”，而是将其视为一个严肃的、可积累的工程设计过程的一部分。它带来的最大回报不是当下的编码速度提升（初期甚至可能变慢），而是在项目进行到三个月、半年后，当你需要重构、排查复杂Bug或向新成员解释系统时，那份能够快速、准确追溯每一个决策来龙去脉的从容与自信。它迫使你思考得更周全，记录得更清晰，最终构建出不仅可运行，而且可理解、可维护的软件系统。