企业官网建设流程全解析

1. 项目概述：为AI编程打造一个持久的“航海日志”

如果你和我一样，深度使用过Claude Code、Cursor这类AI编程助手，那你一定对那个“失忆症”的痛点深有体会。昨天和Claude Opus花了两个小时，从三个备选方案里敲定了一个微服务认证中间件的架构，讨论了JWT和Session的取舍，甚至写好了伪代码。今天打开新会话，一句“帮我实现用户认证”，它给出的方案可能和你昨天深思熟虑的结果南辕北辙。那些被否决的选项、中途发现的陷阱、临时的权衡决策，全都随着聊天窗口的关闭而烟消云散。我们像是在沙滩上写字，潮水（新会话）一来，痕迹全无，一切又得重头再来。

这就是shiplog要解决的核心问题。它不是一个全新的工具，而是一个“粘合剂”和“记录仪”。它的理念非常聪明：不试图取代你现有的Git、GitHub工作流，也不重新发明一个复杂的项目管理工具，而是巧妙地利用你已经在用的git和gh（GitHub CLI），将AI辅助编程过程中那些转瞬即逝的“思维过程”和“决策上下文”，固化到版本控制系统里，变成可追溯、可搜索的永久资产。你可以把它理解为给你的代码库配备了一位永不疲倦的“船长”，它负责记录每一次航行的起因、路线调整、遇到的暗礁以及最终靠岸的完整日志。

这个项目本质上是一个AI Agent Skill（技能包），主要适配Claude Code、Codex和Cursor环境。它通过一系列自动化脚本和约定，将一次完整的开发活动——从头脑风暴、创建分支、编写代码、提交，到发起拉取请求（PR）——的每一个环节，都打上丰富的元数据标签，并串联成一条完整的“决策时间线”。最终，你的Git历史不再仅仅是“做了什么”（git log --oneline看到的那些简短提交信息），而是包含了“为什么这么做”、“还考虑过什么”、“中途发现了什么”的完整知识图谱。

2. 核心设计理念与工作流拆解

2.1 从“失忆会话”到“持久化知识图谱”

传统AI编程的痛点在于其“无状态性”。每个会话都是孤岛。shiplog的破局思路是：将GitHub作为这个“状态”或“记忆”的持久化存储层。GitHub本身就是一个强大的、支持全文搜索的协作平台，Issues、PRs、Commits、Projects天然构成了一个关系网络。shiplog所做的，就是定义一套协议，让AI的工作产出能规整地存入这个网络，并建立它们之间的链接。

它的工作流可以概括为一个增强版的Git Flow，并清晰地划分为六个阶段：

1. 计划（Plan）：将一次头脑风暴或设计讨论直接转化为一个结构化的GitHub Issue。这个Issue不仅包含任务描述，还会记录讨论中的各种方案、权衡利弊、以及拆解出的具体子任务（T1, T2, T3...）。这就把“想法”变成了可追踪、可搜索的“工单”。
2. 开始（Start）：基于某个Issue（例如#42）创建一个独立的分支和对应的git worktree（工作树）。这一步的关键是“隔离”，确保每个功能开发都在独立的环境中进行，避免污染主分支。同时，它会将Issue中的计划加载为当前工作会话的上下文。
3. 执行与发现（Execute & Discover）：在编码过程中，你或AI经常会发现计划外的问题：一个隐藏的Bug、一个更好的实现方式、一个必须优先解决的依赖。shiplog的“发现协议”会对此进行分类路由：
   • 小修复（<30分钟）：直接就地解决，并在时间线中添加一条注释说明。
   • 当前工作的前置条件：为此创建一个新的“堆叠式”分支和PR，明确其阻塞关系。
   • 独立但重要的问题：创建一个新的Issue，打上标签，然后继续当前工作。
   • 重构机会：创建一个标记为refactor的Issue，留待日后处理。 这样，任何灵光一现或意外发现都不会被遗忘在聊天记录里。
4. 提交（Commit）：提交时，shiplog会强制或建议使用“ID优先”的约定式提交。例如：feat(#42/T1): 添加JWT令牌验证中间件。这行提交信息明确指出了它属于哪个Issue（#42）以及完成了哪个子任务（T1）。更重要的是，它可以为这次提交附加一个“上下文注释”，详细解释为什么选择JWT而非Session，或者实现时遇到的某个边界情况如何处理。
5. 交付（Ship）：当功能完成，发起PR时，shiplog会自动生成PR描述。这个描述不是简单的代码变更列表，而是一个“旅程时间线”，按顺序记录了从Issue创建、到分支开发、中途的所有发现和决策、以及最终的实现总结。这为审查者（无论是人还是另一个AI）提供了无与伦比的上下文。
6. 搜索（Search）：事后，你可以通过gh命令行或GitHub界面，轻松搜索所有与#42相关的内容：Issue、PR、提交，甚至是那些中途的发现注释。所有决策逻辑一目了然。

2.2 双模式运作：兼顾个人探索与团队协作

一个非常实用的设计是它的两种运行模式，这解决了“实验记录”与“整洁提交”之间的矛盾。

• 完整模式（Full Mode）：这是默认模式，所有知识（头脑风暴记录、决策原因、探索过程）都会直接写入公开的Issue和PR描述中。这非常适合个人项目或开源项目，追求极致的可追溯性和透明度。
• 安静模式（Quiet Mode）：在团队协作中，你可能不希望一个包含大量试错过程的“流水账”出现在主PR里，以免干扰队友。安静模式下，所有详细的推理和日志会被写入一个单独的--log分支（例如feature/auth-middleware--log）。主分支上的PR保持干净、专业，只包含最终的、精炼的变更描述。如果队友需要了解背后细节，只需一键切换到--log分支即可查看完整记录。这个设计体现了对工程实践和团队沟通的深刻理解。

2.3 核心特性深度解析

shiplog不仅仅是一个记录工具，它更是一套为AI协同编程设计的“治理框架”。

1. 跨模型审查（Cross-model Review）这是我认为最精髓的特性之一。它强制规定：任何PR都不能由创建它的同一个AI模型来自行审查合并。这直接杜绝了“自说自话”的无效审查。审查必须来自另一个AI模型或真人。审查意见会带有Reviewed-by:的签名行。这不仅仅是形式，它迫使不同的模型（或人）以另一种视角审视代码，能有效发现原模型可能存在的盲点或逻辑漏洞。

2. 智能体身份签名（Agent Identity Signing）每一次产出（Issue、Commit、PR评论）都会自动附上创作来源的元数据，例如Authored-by: claude/opus-4.6 (claude-code)。这带来了两个巨大好处：一是可追溯，你可以轻松搜索所有由Claude Opus创建的工件；二是为后续的模型交接提供了基础。接手工作的AI能立刻知道之前是谁在负责，风格如何。

3. 模型层级路由（Model-tier Routing）承认不同AI模型的能力差异和成本差异，并加以利用。shiplog允许你配置：

• Tier-1（推理层）：如Claude Opus，用于复杂的架构设计和方案权衡。
• Tier-2（能力层）：如Claude Sonnet，用于编写结构化文档和加载上下文。
• Tier-3（敏捷层）：如Claude Haiku，用于具体的代码实现和常规提交。 系统会在阶段转换时（如从设计转入实现）提示你切换模型，并自动生成结构化的“交接合同”，明确告知接手模型哪些是已定决策、哪些文件可以修改、预算是多少（例如“不允许做任何新决策”）。这确保了低成本模型能在严格约束下高效执行，而不是自由发挥导致偏离方向。

4. 工作树优先工作流（Worktree-first Workflow）它鼓励甚至强制为每个功能分支使用独立的git worktree。这意味着你的文件系统上会有多个并行的项目目录副本，每个对应一个分支。这样做的好处是绝对的隔离性：你可以同时打开多个IDE窗口，分别处理不同的功能，而不会遇到切换分支时文件冲突的烦恼。shiplog管理这些工作树的创建和清理，让这种强大的工作方式变得简单。

3. 实战部署与核心操作指南

3.1 环境准备与安装

shiplog的依赖极简，这体现了它的设计哲学——增强现有工具，而非替代。

1. 基础依赖：
   • Git：这个不用说，肯定是有的。
   • GitHub CLI (gh)：这是核心依赖。你需要安装并登录。在终端执行gh auth login，按照指引完成认证。shiplog底层大量调用gh命令来与GitHub交互。
2. 安装shiplog技能包： 推荐使用npx skills这个技能管理工具，这是最干净的方式。

   # 全局安装shiplog技能 npx skills add devallibus/shiplog --skill shiplog

   如果你只想为特定AI代理安装，可以指定：

   npx skills add devallibus/shiplog --skill shiplog --agent claude-code # 或 --agent codex, --agent cursor

   安装后，在Claude Code等环境中，通常可以通过输入/shiplog来激活这个技能。
3. 项目初始化： 进入你的Git项目根目录。shiplog不需要复杂的初始化命令。它会在需要时创建自己的配置目录（.shiplog/）。你可以选择性地创建配置文件来定制行为，但这不是必须的。

3.2 核心命令详解与实操

shiplog提供了一系列以/shiplog开头的命令，对应其工作流的各个阶段。我们以一个具体的场景——“为用户系统添加双因素认证（2FA）”为例，走一遍全流程。

阶段一：计划 ——/shiplog plan在AI聊天界面中，你输入：

/shiplog plan 为用户账户系统添加基于TOTP的双因素认证（2FA）功能，包括后端生成密钥、前端显示QR码、验证逻辑，并考虑备份代码机制。

AI（例如Claude Opus）会引导你进行一场结构化的头脑风暴。它会问你：目标用户是谁？优先级如何？有哪些可行的技术方案（例如使用speakeasy还是otplib库）？潜在的安全风险是什么？最终，它会生成一个格式优美的GitHub Issue草稿，其中包含：

• 清晰的标题：[Feat] 为用户系统添加TOTP 2FA认证
• 详细描述：功能概述、业务价值。
• 任务清单（Checklist）：
  • [ ] T1: 后端 - 集成TOTP库，为用户生成唯一密钥并存储
  • [ ] T2: 后端 - 创建API端点，验证用户输入的6位码
  • [ ] T3: 前端 - 新增“启用2FA”页面，展示QR码
  • [ ] T4: 后端 - 实现备份代码生成与验证逻辑
  • [ ] T5: 文档 - 更新API文档和用户帮助
• 决策记录：一个“## 决策”板块，记录了为什么选择TOTP而不是短信验证码（成本、可靠性），为什么选定了某个特定的NPM包。
• 标签：自动添加shiplog/plan等标签。 你确认后，这个Issue就会被创建到你的GitHub仓库，假设其编号为#58。

实操心得：在plan阶段，尽量让AI把备选方案和决策理由列清楚。即使你心里有倾向，也让AI客观分析一下。这些记录在未来回顾时价值连城，尤其是当某个依赖库停止维护，你需要重新评估方案时。

阶段二：开始 ——/shiplog start #58接下来，你决定开始实现这个功能。输入：

/shiplog start 58

shiplog会执行以下操作：

1. 基于main分支创建一个新分支，命名可能为feat/2fa-for-users（遵循常规分支命名）。
2. 同时，为这个分支创建一个独立的git worktree。这意味着在你的项目目录旁，会生成一个像../your-project-feat-2fa-for-users这样的新目录，这个目录直接对应新分支的内容。你可以在全新的IDE窗口中打开这个目录，完全独立地工作。
3. 将Issue #58的内容加载为当前AI会话的上下文。AI现在清楚地知道我们要做什么，以及之前定下的计划。

阶段三与四：执行、发现与提交你在worktree中开始编码。当完成T1（集成TOTP库）后，你准备提交。 你可以使用/shiplog commit命令。AI会分析暂存区的变更，并建议一个提交信息：

feat(#58/T1): 集成otplib库并实现用户密钥生成与存储

它会询问你是否要添加“上下文注释”。你选择添加，并输入：

选择otplib而非speakeasy，因为前者更新更活跃，且TypeScript支持更好。密钥以加密形式存储在`user`表的`totp_secret`字段中。注意：密钥必须在用户成功验证二维码后才标记为已启用，防止账户被锁定。

这个注释不会出现在提交信息中，但会作为一条特殊的Git时间线注释（通过git notes或关联到Commit的特定格式）被记录下来。 在实现T2时，你发现现有的用户认证中间件对速率限制的支持很弱，直接添加2FA验证可能被暴力破解。这是一个“发现”。

• 情景A（小修复）：如果调整中间件只需加几行代码，你可以直接修改，然后在下次提交时，在上下文注释中说明：“发现并修复了认证中间件速率限制漏洞，作为#58/T2的一部分。”
• 情景B（前置条件）：如果修复速率限制需要较大改动，你应该中断当前工作。在AI会话中描述这个问题，shiplog的发现协议会识别到这是一个阻塞项。它会建议你：

  /shiplog plan 加强用户认证API的速率限制机制，以支持安全的2FA验证

  这将创建一个新的Issue #59，并将其标记为#58的依赖。然后你可以/shiplog start 59去先解决这个前置问题。这就是“堆叠式PR”的雏形。

阶段五：交付 ——/shiplog pr当所有任务完成，你运行/shiplog pr。它会：

1. 推送当前分支到远程仓库。
2. 在GitHub上创建一个Pull Request。
3. 自动生成PR描述：这个描述是精华所在。它会是一个Markdown文档，结构如下：

   ## 关联问题 Addresses #58 ## 旅程时间线 1. **计划阶段 (Issue #58)**: 决定采用TOTP方案，选用otplib库，分解为5个子任务。 2. **执行T1**: 完成otplib集成。*[发现]* 原用户表结构需新增字段。 3. **执行T2**: 实现验证端点。*[发现]* 认证中间件速率限制不足，已创建#59作为前置任务并先行解决。 4. **执行T3 & T4**: 完成前端页面和备份代码逻辑。 5. **最终测试**: 对所有边缘案例进行了验证。 ## 变更摘要 - 新增 `src/auth/totp.service.ts` - 修改 `src/users/user.entity.ts` - 新增前端页面 `app/(settings)/security/two-factor/page.tsx` - ... ## 审查清单 - [ ] 代码风格符合项目规范 - [ ] 新增测试覆盖主要流程 - [ ] 文档已更新

   这个时间线就是你的“航海日志”，任何审查者都能在几分钟内理解这个PR的来龙去脉。

阶段六：搜索 ——/shiplog lookup或直接使用gh几周后，你想知道当时为什么决定用otplib。你可以在终端执行：

gh issue view 58 --comments

或者直接在GitHub上搜索Authored-by: claude/，找到所有相关的决策记录。

3.3 进阶配置与集成

shiplog的威力可以通过配置文件和外接技能（Skills）进一步增强。

1. 模型路由配置 (.shiplog/routing.md)你可以创建一个配置文件来明确指定每个阶段使用什么模型。

   # .shiplog/routing.md - phase: plan preferred_tier: tier-1 model: claude/opus-4.6 - phase: start preferred_tier: tier-2 model: claude/sonnet-3.5 - phase: commit preferred_tier: tier-3 model: claude/haiku-3.5 - phase: review required: different-model # 强制要求不同模型审查

   这样，当你运行/shiplog plan时，它会自动建议你切换到Claude Opus；而在执行具体的提交时，则建议切换到更快的Haiku。

2. 验证配置 (.shiplog/verification.md)你可以定义不同严格级别的验证策略，这些策略会在PR创建时或委托给Tier-3模型执行任务时被引用。

   # .shiplog/verification.md default_profile: red-green profiles: red-green: - run: npm test - require: all_tests_pass structural: - run: npx eslint --fix-dry-run . - run: npx tsc --noEmit behavior-spec: - ask_before_changing: true - scenarios: - "作为已登录用户，当我启用2FA时，应该看到QR码" - "当我输入正确的6位码时，应该启用成功"

3. 与配套技能集成shiplog被设计为一个“协调者”。它可以与OrchestKit、Superpowers等技能包联动，实现更强大的自动化。例如，结合ork:create-pr，可以在创建PR时自动运行一个验证Agent来检查代码质量；结合superpowers:using-git-worktrees，可以更精细地管理工作树。

4. 常见问题与避坑指南

在实际使用中，你可能会遇到一些典型问题。以下是我在深度使用后总结的经验和解决方案。

Q1:gh命令认证失败或权限不足。

• 症状：执行/shiplog命令时，提示“GitHub API error”或“Authentication failed”。
• 排查：首先在终端运行gh auth status，检查是否已登录以及登录的宿主（如github.com）和权限范围是否正确。shiplog需要repo（完全控制私有仓库）和read:org等权限。
• 解决：运行gh auth login重新登录，在选择权限时，确保勾选了repo和workflow。如果是在企业GitHub上，注意使用--hostname参数指定正确的主机名。

Q2: 创建worktree时失败，提示“already exists”或路径错误。

• 症状：/shiplog start时出错。
• 原因：shiplog默认会将worktree创建在项目父目录的一个特定命名路径下。如果该路径已存在（可能因为之前异常退出未清理），就会失败。
• 解决：手动清理旧的worktree目录。你可以使用git worktree list查看所有worktree，然后用git worktree remove <path>安全地删除它们。或者，直接去项目上级目录删除对应的文件夹。

Q3: 提交信息格式不符合“ID优先”约定，导致链接失效。

• 症状：提交后，在GitHub上点击Issue号无法自动关联到提交，或者/shiplog lookup搜不到。
• 原因：提交信息格式错误。正确的格式是<type>(#<issue-id>/T<task-number>): <description>，例如fix(#58/T2): 修复验证端点空指针异常。如果漏掉了#号或括号格式不对，GitHub的自动链接功能可能无法识别。
• 解决：养成使用/shiplog commit命令的习惯，让AI帮你生成格式正确的信息。如果已经提交，可以使用git commit --amend修改上一次提交信息，或者使用git rebase -i交互式变基来修改历史提交信息（注意：如果已推送远端，需谨慎使用--force）。

Q4: 在团队中使用“安静模式”，但队友不知道如何查看详细日志。

• 症状：PR描述很简洁，队友想了解某个决策细节时找不到。
• 解决：在简洁的PR描述末尾，添加一条标准注释：“详细设计决策和开发日志请查看feature/xxx--log分支。” 并确保团队所有成员都知道--log分支的命名约定。更好的做法是，在团队内部分享shiplog的基本工作流，让每个人都理解这种“双分支”记录模式的价值。

Q5: 跨模型审查时，审查AI不理解上下文。

• 症状：你让Claude Haiku去审查一个由Claude Opus创建的复杂PR，Haiku给出的审查意见很肤浅或跑偏。
• 原因：Tier-3模型可能无法完全消化PR描述中庞大的“旅程时间线”信息。
• 解决：这是“交接合同”的重要性所在。在从Opus交给Haiku执行任务时，合同必须极其明确。对于审查，可以配置shiplog在请求审查时，附带一个简化的“审查重点摘要”，而不是扔过去整个时间线。或者，手动提示审查AI：“请重点审查src/auth/totp.service.ts文件中的verifyToken函数的安全性和错误处理逻辑。”

Q6: 发现协议导致问题“爆炸”，创建了大量琐碎Issue。

• 症状：开发一个功能时，触发了太多“发现”，每个都被创建成新Issue，导致Issue列表膨胀。
• 经验：合理使用“小修复”路径。评估发现的问题是否真的值得一个独立的、长期跟踪的Issue。如果是一个5分钟就能改好的代码风格问题或明显的拼写错误，直接就地修复并在上下文注释中说明即可。shiplog的发现协议是一个框架，你需要运用自己的工程判断力去驾驭它，而不是被它驱使。

从“与失忆的AI结对编程”到“与拥有持久记忆的AI系统协同开发”，shiplog带来的范式转变是显著的。它强迫你（和你的AI助手）以更工程化、更可追溯的方式工作。初期可能会觉得有些繁琐，但一旦习惯，你会发现自己再也回不去了。尤其是当项目进行到三个月后，你需要回顾某个关键架构决策的上下文时，或者当新成员加入，你能直接给他一个充满“为什么”的Git历史时，这种价值就会凸显。它不仅仅是一个工具，更是一种关于如何与AI共同进行严肃软件开发的理念实践。