企业官网建设流程全解析

• 人工智能
• AI Agent
• 自主智能体
• 代码智能体
• 桌面应用
• 前端
• 开发工具

本指南讲解如何为 Aperant（Autonomous multi-session AI coding）的 auto-claude 自动构建流程接入 ccstatusline，让 Claude Code 状态栏实时展示当前构建进度。读者将掌握从安装 ccstatusline、在 TUI 或 JSON 配置中添加 Custom Command 组件，到理解状态数据契约、三种输出格式以及故障排查的完整实战方案，并深入了解该仓库中支撑进度统计的底层 TypeScript 工具实现。

适用场景与前置条件

ccstatusline 是一个可自定义的 Claude Code 状态栏扩展，通过周期执行自定义命令并把输出渲染到状态栏，就能在不打断 Agent 会话的前提下持续感知构建状态。接入前需要满足两个条件：

1. ccstatusline 已安装并完成基础配置——它是本指南中承载自定义组件、轮询刷新和渲染的宿主；
2. auto-claude 位于你的项目中——即负责执行 spec → 分阶段构建 → QA 闭环的自动构建引擎。在本仓库中，auto-claude 的自定义工具集位于 auto-claude 工具目录，以mcp__auto-claude__*命名约定注册（见 index.ts），例如mcp__auto-claude__get_build_progress、mcp__auto-claude__update_subtask_status。

第一步：安装 ccstatusline

如果尚未安装，使用npx或bunx运行最新版本即可：

# 使用 npx npx ccstatusline@latest # 使用 bunx bunx ccstatusline@latest

该命令会启动一个交互式 TUI，用于配置你的状态栏布局、组件位置与刷新策略。

第二步：在 TUI 中添加 Custom Command 组件

在 ccstatusline 的 TUI 配置界面中，新增一个Custom Command（自定义命令）组件，将命令指向 auto-claude 配套的statusline.py脚本：

Command: python /path/to/your/project/auto-claude/statusline.py --format compact

推荐的组件设置：

• Position（位置）：状态栏左侧或中间，方便一眼获取；
• Update interval（刷新间隔）：5 秒（默认值）；
• Show only when active（仅在活动时显示）：建议开启（Yes），避免空闲时占用状态栏空间。

--format compact是专为状态栏单行渲染设计的紧凑格式，具体输出结构见下文「输出格式详解」。

第三步：通过 JSON 配置（免 TUI）

如果你偏好直接编辑配置文件而非使用 TUI，可以编辑~/.config/ccstatusline/settings.json，在widgets数组中追加：

{ "type": "custom", "command": "python /path/to/your/project/auto-claude/statusline.py --format compact", "interval": 5, "showWhenEmpty": false }

各字段含义与 TUI 设置一一对应：command指定要执行的命令；interval为轮询间隔秒数（最小可设为 1，见故障排查）；showWhenEmpty为false表示输出为空（即无活动构建）时不渲染该组件。两种配置方式等价，TUI 只是配置生成器的便捷封装。

状态数据源：从状态文件契约到源码实现

statusline.py的数据来自自动构建引擎实时写入项目根目录的.auto-claude-status文件，其 JSON 结构如下：

{ "active": true, "spec": "001-feature", "state": "building", "chunks": { "completed": 3, "in_progress": 1, "pending": 8, "total": 12 }, "phase": { "current": "Setup", "id": 2, "total": 4 }, "workers": { "active": 2, "max": 3 } }

字段语义：

该文件契约在仓库中有清晰的源码对应物：进度统计的核心实现是 get-build-progress.ts 中的mcp__auto-claude__get_build_progress工具。它读取context.specDir下的implementation_plan.json，遍历各phases[].subtasks[]，依据subtask.status累加出total / completed / in_progress / pending / failed五类统计、逐阶段汇总阶段名: 已完成/总数，并计算出进度百分比：

const progressPct = stats.total > 0 ? ((stats.completed / stats.total) * 100).toFixed(0) : '0';

当所有子任务完成后会返回All subtasks completed! Build is ready for QA.，并额外指出下一个待处理子任务的 ID、阶段与描述。可见状态文件中的chunks对应源码中的 subtask（子任务）粒度。

子任务状态流转由 update-subtask-status.ts 的mcp__auto-claude__update_subtask_status工具维护，其输入状态枚举为：

['pending', 'in_progress', 'completed', 'failed']

与状态文件中的chunks计数一一对应。该工具在更新后还会写入notes（可选备注）与updated_at时间戳，并通过「先写临时文件再原子重命名」的方式（writeJsonAtomic）保证implementation_plan.json的写入一致性，避免状态栏读到半截 JSON：

function writeJsonAtomic(filePath: string, data: unknown): void { const tmp = `${filePath}.tmp`; fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8'); fs.renameSync(tmp, filePath); }

从源码结构看，workers.active / max对应 Aperant 的并行执行与恢复编排层（见 parallel-executor.ts、recovery-manager.ts），即多会话 Agent 同时推进多个子任务时，active反映当前真正在跑的 worker 数。

输出格式详解

statusline.py支持三种输出格式，分别面向不同使用场景。

Compact（推荐用于状态栏）

--format compact

输出示例：▣ 3/12 | ◆ Setup → | ⚡2 | 25%

含义依次为：已完成 chunks/总 chunks（3/12）、当前阶段（◆ Setup）、→进行中指示、活跃 worker 数（⚡2）、总进度百分比（25%）。单行紧凑，与interval: 5的轮询搭配，可在不遮挡其他状态信息的前提下持续刷新。

Full（详细多行）

--format full

输出示例：

AUTO-BUILD: my-feature State: BUILDING Chunks: 3/12 (1 in progress) Phase: 2/4 - Setup Workers: 2 active

适合在需要查看构建全貌的宽屏终端中使用，一次性呈现 spec 名、构建状态、chunk 明细、阶段位置（第 2/4 阶段，当前为 Setup）与活跃 worker 数。

JSON（面向脚本）

--format json

输出原始 JSON 状态数据，便于被其他脚本、聚合工具或自定义渲染逻辑消费，例如与.auto-claude-status文件内容做差异对比，或接入自己的监控面板。

图标说明

构建处于活动状态时，状态栏会出现以下指示符：

故障排查

状态没有显示？

1. 检查项目根目录下是否存在.auto-claude-status文件——若不存在，说明当前没有活动构建或自动构建尚未写入状态；
2. 核对statusline.py的路径是否正确；
3. 手动执行一次命令验证链路：python auto-claude/statusline.py --format compact，观察是否有输出或报错。

更新太慢？

• 调低 ccstatusline 配置中的轮询间隔，最小可设为 1 秒（"interval": 1）。注意过低的间隔会增加 I/O 与进程开销，5 秒通常是兼顾实时性与资源消耗的合理默认值。

项目目录不对？

• 使用--project-dir /path/to/project显式指定项目根目录，确保脚本定位到正确的.auto-claude-status。这对于从全局位置（如~/projects/my-app之外）调用脚本的场景尤其必要。

配置示例

最小状态栏（仅 chunks 与阶段）

python auto-claude/statusline.py --format compact

监控指定 spec

python auto-claude/statusline.py --format compact --spec 001-my-feature

--spec用于在多 spec 并行构建时聚焦某个特定 spec 的进度。

全局路径使用

python ~/projects/my-app/auto-claude/statusline.py --format compact --project-dir ~/projects/my-app

该写法将脚本与项目根目录都写为绝对路径，可在任意工作目录下稳定运行，适合放入 ccstatusline 的全局配置中。

结语

接入 ccstatusline 后，Aperant 的自动构建状态就能以「状态栏常驻、5 秒刷新、仅活动时显示」的方式透明可见。无论是compact的单行速览、full的多行详情，还是json的脚本化消费，其背后的数据都来源于本项目 auto-claude 工具集 对implementation_plan.json的实时统计与原子写入——理解这一数据契约，能帮助你在自定义状态栏、监控面板甚至 CI 集成时准确对接构建进度语义。

• 人工智能
• AI Agent
• 自主智能体
• 代码智能体
• 桌面应用
• 前端
• 开发工具