mcpField
S
swain-status

swain-status

github.com/cristoslc生产力262 次安装25 周前更新
代码仓库

关于 swain-status

swain-status 是面向项目负责人的状态仪表板技能，汇总制品、任务、Git、GitHub 问题和会话信息。它会生成行动建议，并支持按关注方向筛选以及精简状态输出。

主要功能

  1. 01汇总五类项目状态数据
  2. 02生成优先级建议与待决事项
  3. 03按关注方向筛选建议
  4. 04提供精简模式与 JSON 输出
  5. 05缓存状态并检查路线图时效

适用场景

  1. 01查看项目进度和当前任务
  2. 02识别需要决策或拆解的事项
  3. 03聚焦单个愿景或计划
  4. 04将状态摘要接入 MOTD 面板

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cristoslc/swain --skill swain-status

安装后在 Claude Code 中输入/swain-status确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
agent-summary-template.md
status-format.md
scripts/
swain-status.sh

详细介绍

状态

跨领域的项目状态仪表板。将制品生命周期（swain chart）、任务跟踪（tk）、git、GitHub issue 和会话状态中的数据汇总为以活动为导向的视图。

路线图新鲜度

状态脚本包含过时检查：如果 ROADMAP.md 缺失或早于任何文档制品生成时间，则会重新生成该文件。此检查会自动运行，无需单独调用。

如需完整刷新路线图（无条件重新生成），请改用 swain-roadmap。

调用时

定位并运行状态脚本 skills/swain-status/scripts/swain-status.sh：

# Find the script from the project root or installed skills directories
SKILL_DIR="$(find . .claude .agents -path '*/swain-status/scripts/swain-status.sh' -print -quit 2>/dev/null)"
bash "$SKILL_DIR" --refresh

如果路径搜索失败，请使用 glob 搜索 **/swain-status/scripts/swain-status.sh。

脚本的终端输出使用 OSC 8 超链接，让制品链接可点击。让终端输出滚动即可——它是参考数据，不是主要输出。

脚本运行后，请按照 references/agent-summary-template.md 中的模板提供结构化的 Agent 摘要。 Agent 摘要是用户用于决策的内容。摘要必须先列出建议部分（见下文），然后是待定决策、可开始的工作，最后是参考数据——遵循 references/agent-summary-template.md 中的模板。

脚本从五个数据源收集信息：

  1. 制品 — swain chart 中以愿景为根的层级结构（史诗进度、就绪/受阻项目、依赖信息）。使用 bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" recommend 查看排名后的制品；会自动遵循焦点泳道。
  2. 任务 — tk（进行中、最近完成）
  3. Git — 分支、工作树状态、最近提交
  4. GitHub — 开放的 issue、分配给用户的 issue
  5. 会话 — 来自 swain-session 的书签和上下文

紧凑模式（MOTD 集成）

脚本支持 --compact，供 swain-stage 的 MOTD 面板使用：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
STATUS_SCRIPT="$(find "$REPO_ROOT" -path '*/swain-status/scripts/swain-status.sh' -print -quit 2>/dev/null)"
[ -n "$STATUS_SCRIPT" ] && bash "$STATUS_SCRIPT" --compact || echo "swain-status.sh not found"

这会输出适用于 MOTD 框的 4–5 行内容：分支、当前史诗进度、当前任务、就绪数量、分配给用户的 issue 数量。

缓存

脚本会将 JSON 缓存写入项目本地的 agents 目录：

.agents/status-cache.json
  • **TTL：**120 秒（可通过设置中的 status.cacheTTL 配置）
  • 强制刷新：--refresh 标志可绕过 TTL
  • JSON 访问：--json 标志输出原始缓存，供程序化使用

MOTD 可在完整刷新之间读取此缓存，开销很低。

**迁移：**如果 .agents/status-cache.json 不存在，但 ~/.claude/projects/<project-path-slug>/memory/status-cache.json 存在，则读取旧位置一次，并在之后写入新位置。

建议

建议使用以下评分公式：

score = unblock_count × vision_weight

其中，vision_weight 继承自制品的愿景祖先（高 = 3，中 = 2，低 = 1，默认 = 中）。从 JSON 缓存中读取 .priority.recommendations[0]，即可获取排名最高的项目。

平局时按以下顺序打破：

  1. 制品所属愿景中决策债务较高者优先
  2. 决策类制品优先于实现类制品
  3. 制品 ID（确定性回退规则）

设置焦点泳道后，建议范围将限定为该愿景/计划。外围愿景会单独汇总（参见外围关注）。

如果检测到建议项目所属愿景存在注意力漂移，请将其作为建议的上下文。

模式推断

swain-status 会根据上下文推断工作模式（采用第一个匹配项）：

  1. 规格均在审核中，且有待处理的战略决策 → 询问：“统筹还是审核？”
  2. 规格等待操作者审核（Agent 已完成，需要签字确认） → 细节模式
  3. 已设置焦点泳道，且有待处理的战略决策 → 在该泳道内进入愿景模式
  4. 没有规格在审核中，但决策积压 → 愿景模式
  5. 两种模式下都没有可采取行动的事项 → 愿景模式（显示主计划镜像）

操作者回答后，swain 会通过 swain-session 书签记住该会话的选择。

Focus Lane

操作者可以通过 swain-session 设置 focus lane，将建议限定在单个愿景或计划范围内：

bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-focus.sh' -print -quit 2>/dev/null)" set VISION-001

设置后，.priority.recommendations 仅包含该愿景下的项目。非 focus 愿景会显示在「外围关注」部分。

外围关注

设置 focus lane 后，会汇总有待决策事项的非 focus 愿景： “与此同时：[愿景] 有 N 项待决策事项（权重：W）”

这是一面镜子，而非建议——操作者自行决定何时因事项累积而需要调整方向。

所有规范均已解决的活跃史诗

当某个 Active 史诗满足 progress.done == progress.total 时：

  • 在史诗进度表的就绪状态列中显示“→ 可关闭”
  • 不要将其显示在「可开始的工作」类别中（这不是实现工作）
  • 不要将其显示为“处理子规范”

待处理决策（路线图集成）

在现有状态输出部分之后，显示路线图中的优先决策事项。本部分使用 chart.sh roadmap --json 中的 Eisenhower 分类。

数据收集
bash "$(find . -path '*/swain-design/scripts/chart.sh' -print -quit)" roadmap --json
筛选
  1. Focus lane 范围限定： 如果已设置 focus lane，则只筛选该愿景的项目。
  2. Eisenhower 象限筛选： 显示“优先处理”和“安排处理”象限中的项目。分类标准：
    • 重要： weight >= 3
    • 紧急： 状态为活跃，或 score > 0
  3. 操作者决策筛选： 显示需要操作者做出决策的项目：
    • 状态为“Proposed”——需要决定激活或放弃
    • children_total == 0——需要分解为子规范
    • children_complete == children_total 且 children_total > 0——已可完成/关闭
显示
  • 最多显示 5 项，按 weight 降序、再按 score 降序排列。
  • 将每项格式化为可执行的提示，而非被动的列表条目。例如：
    • EPIC-038 PR-Only Agent Guardrails — **需要分解**（0 项规范，优先级高）
    • EPIC-024 GitHub Issue Polling — **激活还是放弃？**（Proposed，优先级高）
    • EPIC-012 Session Atomization — **可完成**（4/4 项规范已完成）
  • 如果没有符合条件的项目，则完全省略本部分，不要显示空标题。
降级处理

如果 chart.sh roadmap --json 执行失败或返回空数据，则静默跳过「待处理决策」部分，继续输出其余状态信息。

设置

从 swain.settings.json（项目设置）和 ~/.config/swain/settings.json（用户覆盖设置）读取。

键类型默认值说明
status.cacheTTLnumber120缓存生存时间，单位为秒

会话书签

显示状态后，使用最具行动指导意义的重点更新书签：bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)" "Checked status — {key highlight}"

错误处理

  • 如果 chart.sh / specgraph 不可用：跳过制品部分，显示其他数据
  • 如果 tk 不可用：跳过任务部分
  • 如果 gh CLI 不可用或没有 GitHub 远程仓库：跳过 issue 部分
  • 如果 .agents/session.json 不存在：跳过书签更新
  • 不要彻底失败——显示所有可用数据

评论

支持 Markdown