dadamsuk/slipdock-work

从 Slipdock 看板中工作

看板是工作记录计划：确定下一步做什么，以及记录发生了什么的地方。 服务器会记录其自身的约定——在每次会话开始时首先阅读它们，然后再选择或更新任何内容：

slipdock guide                    # markdown，来自 GET /api/guide

如果此机器上没有 CLI——这是常见情况，因为 CLI 需要 Elixir：

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"   # 如果两者都未设置，请询问用户
curl -s -H "Authorization: Bearer $SLIPDOCK_TOKEN" "$B/api/guide"

服务器的地址来自 $SLIPDOCK_URL，否则来自 ~/.config/slipdock/url（由 slipdock url 或服务器的 /install.sh 写入）。如果两者都没有，请询问用户其 Slipdock 的地址，而不是猜测——托管的看板类似于 https://app.slipdock.us，自托管的看板则是他们访问时使用的名称。

如果有令牌（$SLIPDOCK_TOKEN，否则为 ~/.config/slipdock/token），请传递它。指南不需要令牌，但如果有令牌，它会以用户的实际看板、每个看板上的所有列表以及哪些列表是就绪列表、积压列表、进行中的工作列表和已完成工作列表结束——这正是你需要选择任务所需的信息。

指南优先于本文件。 它来自正在运行的服务器，因此是最新的：其中的端点、词汇表和看板布局是在请求时生成的。本文件仅告诉你去获取它，以及在尚未获取时该做什么。

查找无人能命名的事物

slipdock cards <board> --search Q 按子字符串过滤一个看板。其其他过滤器询问状态而非关键词，并且它们正是回答“我该选择什么”的过滤器：--deps ready 排除任何等待未完成卡片的项目，--no-assignee 排除其他人的工作，--due overdue 显示已超期的项目。因此，符合条件的列表只需要一次调用：

slipdock cards <board> --column "To Do" --open --deps ready --no-assignee

slipdock search <words...> 则不同：它按含义匹配，跨越用户可以看到的所有看板，并且涵盖评论和状态更新以及卡片。当用户描述一件事而不是命名它时（例如“关于退款舍入问题的卡片”），当你要找的东西可能出现在评论中而非标题中时，或者当你不知道要看哪个看板时，请使用它。读取它打印的匹配片段，然后在接触卡片之前通过 slipdock card <id> 获取整张卡片。

简短版本（指南会展开说明）

• 史诗和子卡片。 顶层卡片是史诗：一个成果，包含优先级、日期和讨论。工作存在于其子卡片中，每个子卡片代表一次工作会话。清单项是任务内的步骤。你发现的新工作应放在其所属的史诗下作为子卡片——而不是作为新的顶层卡片。
• 选择。 完成已经在进行中的工作；然后查看就绪列表（To Do），只有当该列表中没有任何符合条件的项时才查看积压列表。优先级最高者优先，列表中的位置用于打破平局。跳过任何已完成、已归档、已阻塞、等待中、已暂停或分配给其他人的卡片——--open --deps ready --no-assignee 已经为你完成了大部分跳过（已暂停的卡片已从 slipdock cards 中排除）——以及任何占位卡片（↪stand-in-for:#N）：它仅标记卡片进入冲刺的位置。如果看板回复 PAUSED（JSON 中的 paused），则表示某个人已暂停了其上的运行工作：不要拿取任何东西并停止。当你选中的卡片有子卡片时，深入其中并将这些子卡片处理至完成，然后再返回处理下一个顶层卡片。
• 边做边更新。 开始时将卡片移至进行中并分配给自己；在每个决策、意外或死胡同时添加评论；标记它（blocked、review）并附上评论说明你在等待什么；当只有一个人能提供你所需的东西时，打开一个等待并停止（slipdock wait <id> "what you need" [--on EMAIL] [--choice X]...，或 update_card wait；多个问题作为 --question Q --question Q / questions，每个问题单独一个，不要合并为一个块）：它会将卡片标记为 waiting，回答它（slipdock answer）会让工作继续进行——或者，当等待的事件有日期时，则改为暂停它（slipdock snooze <id> <date> --note "…"）：它会离开列表并在指定日期回来，位于列表顶部；完成后，设置 completed: true 并将其移动到已完成列表。只有当其汇总显示所有子卡片都完成时，才将史诗标记为完成。
• 已验证工作，在看板开启此功能时适用（指南中的相关行显示为 verified work: …）。在开始之前编写卡片的验收标准（slipdock edit <id> --bar "…"），并且一旦工作开始就永远不要尝试更改它。完成时附上你检查的内容（slipdock done <id> --evidence-commit <sha> --tests a,b --suite passed:38:0 --evidence "…"）。在由第二个智能体验证的看板上，done 会提交卡片并使其保持待定状态：不要自行将其移至“已完成”。被拒绝的卡片会返回，并在评论中说明原因，同时在作业的提示词和 get_card 的 rejection 中包含拒绝信息（交接信息显示为 Rework: …）：首先阅读该原因，因为它就是下一个简要说明。验证他人的卡片（永远不要验证你自己的）意味着在干净的树中检出证据的提交，运行测试套件（在拉取请求看板上，检查该提交处的 CI 已通过），根据验收标准进行判断，然后执行 slipdock accept <id> 或 slipdock reject <id> --reason "…"。在看板通过拉取请求发布的情况下（看板的文本行如此说明，声明的作业提示词和 slipdock card 也如此说明），永远不要推送到默认分支：在 card-<id> 上提交，推送它，打开一次拉取请求（gh pr create --head card-<id> --title "<title> (#<id>)" --fill；被拒绝的卡片的下一次尝试会推送相同的分支），监视其检查（完整的测试运行：在推送之前，仅运行你添加或更改的测试），并通过 slipdock done <id> --pr <url> 完成。接受卡片会合并它；不要自行合并。失败的合并会将卡片以拒绝状态送回，并附带原因：变基分支并再次提交。
• 车道，在开启此功能时适用（看板的指南行显示为 lanes: on）。在开始卡片之前，编写其工作将触及的路径：slipdock edit <id> --paths "lib/foo/**,docs/manual.md"，尽量缩小到简要说明允许的范围。因与进行中的卡片重叠而被拒绝的移动会指明该卡片：缩小路径，或者将卡片标记为被该卡片阻塞；只有人能覆盖车道。在推送看板上，等待验证的卡片会释放其车道和依赖项；在拉取请求看板上，它会同时持有两者直到合并。无论看板是否具有车道，在具有路径的卡片上，仅暂存这些路径下的文件（按名称），并且如果同一仓库中有另一个活动会话，则在你自己的 git 工作树中工作（git worktree add ../<repo>-lanes/card-<id> -b card-<id>），除非运行器已经将你置于一个工作树中（$SLIPDOCK_WORKTREE）。
• 首先阅读交接信息，提前停止时留下交接信息。 卡片的交接信息（slipdock card <id> 顶部的 Left off:；JSON 中的 handoff）是上一个处理它的人留下的内容：下一步和简短说明。当你拿起卡片时，在阅读评论之前先读它。每当你在卡片未完成时停止——会话结束、交回、阻塞、时间不足——留下一条：slipdock handoff <id> --next "<the one next step>" --body "State: … Gotchas: … Open: … Pointers: …"（在 MCP 中，使用 leave_handoff）。它会替换上一条；历史记录会被保留。评论保持不变，作为运行日志；交接信息是当下的情况。在已完成的卡片上，交接信息是为用户准备的：他们必须做什么、检查什么或知道什么（部署、重新安装、问题、注意事项），以 --next 形式呈现，并用几个要点说明情况。如果没有什么留给他们：留空，并通过 slipdock handoff <id> --clear 清除之前遗留的交接信息。
• 在推送之前重新阅读卡片，并重新阅读其评论。 工作检查完成后，再次执行 slipdock card <id>：更改的描述或比你的声明更新的评论仍然属于这张卡片——在提交之前执行此操作。在构建开始后，再读取一次评论以查看在此期间添加的任何内容。
• 事件和部署。 当看板记录部署时（slipdock dora <board> 返回结果而不是说交付指标关闭），宕机或破坏性发布是标记为 incident 的普通卡片；如果你知道导致问题的部署，则执行 slipdock incident-of <card> <deploy-id>。在修复的提交中提及卡片编号（#57），就像对待任何卡片一样：这样该部署才会被计为修复，并且卡片会获得其 Shipped 行。永远不要手动记录或完成部署——那是 CI 的工作，使用自己的令牌。
• 整理建议由用户决定。 slipdock garden <board>（在 MCP 中，使用 garden）列出看板整理工具发现的内容：已完成但未关闭的史诗、卡在“进行中”的卡片、重复项、孤立页面。当被要求整理时显示它们，并且仅处理（slipdock garden apply <id>，garden_decide）用户批准的内容；在无人值守工作时，永远不要应用或忽略任何建议——忽略操作会被记住。
• 长时间运行的工作需要中期更新。 如果任务将花费超过一次简短工作会话，则在每个里程碑处添加评论，同时任务仍在运行——已完成了什么，还剩下什么，任何改变了计划的事项——并随之更新 percent_complete。最后才写一份总结已经太晚，无法发挥作用：一张进行中的卡片上如果只有移动操作而没有更新的内容，会显得像被遗弃了。跨越多次会话执行的史诗也采用相同的处理方式，每关闭一个子卡片就写一行。
• 评论是 Markdown 格式，并且会被浏览。 以粗体行开头，说明是什么（**Picked up.**、**Built.**、**Decision:** …），然后使用简短的要点，每个要点一条事实，路径、命令和提交 ID 放在反引号中；永远不要使用一个密集的从句段落。超过一行的内容使用 slipdock comment <id> --body - <<'EOF' … EOF（引号分隔，以便反引号存活）；命令行上的文字会失去其换行符。
• 提交并链接它。 当项目是 git 仓库时，一旦卡片的工作完成——在关闭卡片之前——提交它，并在提交消息中包含卡片 ID（#42）。关闭评论链接到提交，或者如果打开了 PR 则链接到 PR（Commit: https://github.com/…/commit/abc1234）。如果没有远程可链接，则给出短哈希和分支名。
• 最终评论中的令牌成本。 卡片上关闭评论以一行结束，说明工作使用的令牌数量，例如 Token cost: ~135k tokens (context budget 15.00M → 14.86M, claim to close)。在声明卡片时和关闭卡片时记录剩余令牌计数器（系统消息中的 total_tokens left），并给出差值。如果在一次连续工作中处理了多张卡片，则从每个自己的声明开始测量。如果计数器不可见，则说 "Token cost: not measured"，而不是进行估算。将相同的数字添加到史诗的进度评论中。
• 首先阅读他们的收藏夹。 slipdock favourites 列出此人标记的看板、列表、卡片和已保存视图——他们实际工作的地方，这点仅靠看板列表无法告诉你。当“接下来我该做什么？”的问题没有指定看板时，收藏夹是你拥有的最强提示。它们是私人的：除非被要求，否则永远不要添加或删除任何内容。
• 已归档的看板是已被搁置的工作。 slipdock boards 有意将它们排除在外；--all 会显示它们并带有 archived 状态。上面的所有内容仍然可读可写，但未经询问永远不要从已归档的看板上选取工作，也永远不要在那里放置新工作。
• 写下卡片无法承载的内容。 看板说明正在做什么；它不适合记录某事如何运作、做出了什么决定以及为什么、或某物的形状。这些内容应放在看板的 wiki 上——slipdock page ls <board>、slipdock page read <page>、slipdock page new <board> <title...>。判断标准是：在此卡片关闭后它是否会被再次阅读？一个决定、运行手册、规范或调查结果会被再次阅读，并且应放在页面上（通过其代码（如 W-31）在卡片的关闭评论中链接）；进展、阻塞因素和现在发生了什么应放在卡片上的评论中。永远不要两者兼有——重复评论的页面是没人信任的页面。在编写之前搜索（slipdock page ls <board> --q <the thing>）：扩展现有页面胜于创建关于部署的第四个页面。每次编辑时传递 --message，并在对不是你刚刚自己编写的页面进行任何编辑时传递 --base-hash，以便保存操作永远不会静默地覆盖他人的内容。
• 保持标题简短。 卡片标题最多约 60 个字符，系列标题采用 <Series> <n>: <what> 格式（Agent supervision 5: Parked jobs），详细信息放在描述中。卡片的标题会成为一个文件夹，并在紧凑的列表中显示，而共享前 40 个字符的卡片序列在该列表中无法区分。
• 不要删除卡片（改为归档）、重写标题以匹配你实际所做的、整理他人的卡片、或将卡片保留在“进行中”状态而没有比移动操作更新的评论。归档或重新排序整个看板则更远超出你的职责范围：仅在明确的请求下，并指定该看板的名称。

何时适用

• “接下来我该做什么？”、“继续执行计划”、“处理积压工作”、“下一个任务”→ 获取指南，然后根据其规则选择，并说明你选取了哪张卡片以及原因。
• “将此计划放入看板”、“将其分解为任务”→ 根据指南的形状，使用带子卡片的史诗。
• 你已经处于来自看板的某个任务的中间阶段→ 卡片是记录进展、决策和阻塞因素的地方，并且应在发生时立即记录，而不是最后一次性倒出。
• 你完成了来自看板的某项工作→ 在报告完成之前在看板上关闭它。