Pilot Shell Specifications 视图详解：规范进度、阶段追踪与内联标注完整指南-创锋一号

Pilot Shell Specifications 视图详解：规范进度、阶段追踪与内联标注完整指南

【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell

Pilot Shell 是一款面向 Claude Code 与 OpenAI Codex 的上下文工程与规范驱动开发（Spec-Driven Development）工具。它的 Console 内置Specifications 视图，让你在一个网页界面里完成三件关键事：查看规范的任务进度、追踪开发阶段、直接在文档上做内联标注并自动同步给 AI Agent。下面带你快速看懂这个视图的每个模块。

一、Specifications 视图是什么？

当你通过/spec工作流生成一份实施计划后，Pilot Shell 会自动扫描项目中的 plan 文件（普通 Markdown），并把它渲染成结构化的规范页面。核心能力包括：

头部信息卡（Header Card）：展示Status（PENDING / COMPLETE / VERIFIED）、Type（Feature / Bugfix / Build）、Approved、Iterations等元信息
进度跟踪（Progress Tracking）：把## Progress Tracking中的复选框清单变成可点击的任务卡片
任务卡片（Task Cards）：Implementation Tasks章节自动转成带折叠、可跳转的任务卡
内联标注（Annotations）：选中任意文字即可写批注，自动保存到.annotations文件，Agent 会在审批检查点读取

视图源码位于 views/Spec/，其中 index.tsx 是页面入口，SpecTaskCard.tsx 负责任务卡片渲染。

二、规范进度：任务清单如何变成可视化进度条

Pilot Shell 的 plan 文件遵循一份公开的格式契约，机器可读版本就在 plan-format.json，完整规范文档见 plan-format.md。

1. 头部字段决定状态

plan 文件开头是若干Key: value行，例如：

Created: 2026-08-24 Status: PENDING Approved: No Type: Feature Iterations: 0

Status只有三个合法值：PENDING、COMPLETE、VERIFIED。Console 的 Specifications 视图、状态栏（statusline）和分享页面都按这个字段归档计划——写错成DONE或RESOLVED会被判定为未知状态。

2. 任务卡与进度计数

## Progress Tracking里的- [ ] Task 1清单不会重复渲染，而是汇总成头部卡片上的任务计数（如 3/8）
## Implementation Tasks被渲染为可点击的任务卡片，每张卡包含Objective、Files、Key Decisions、Definition of Done四个子块
你自定义的## 标题章节同样会显示，排在已知章节之后

💡 与 Specifications 并列的Requirements标签页用于管理/prd产出的需求文档，协作方式完全一致。

三、阶段追踪：从 Plan 到 Verify 的全流程

/spec工作流把一次功能开发拆成清晰的阶段线：

Discuss → Plan → Approve → Implement → Verify → Done

各阶段在 Console 中的对应表现：

阶段	做什么	在哪里看
Plan	Agent 探索代码库、生成规范与 E2E 测试场景	Specifications 视图首屏
Approve	人工审批，可直接编辑或内联标注计划	头部卡 + 标注面板
Implement	隔离 worktree 中按任务卡严格 TDD（RED → GREEN → REFACTOR）	Worktree 面板 + 任务卡勾选
Verify	全量测试、类型检查、浏览器自动化验证，结果写回 plan	`## E2E Results`章节

几个实用机制：

暂停即停：实现中途提问，Agent 会暂停（状态显示⏸ Paused），停止"继续"催促，直到你resume
偏差记录：实现中学到的战术级差异会记入 plan 的## Deviations章节，验证阶段视这些文件为评审范围内
结果回写：E2E 场景的通过/失败结果直接写回 plan 文件，规范本身就成为"活文档"

工作流细节可参考 workflows/spec.md，各阶段编排逻辑在 spec-plan/orchestrator.md 与 spec-verify/orchestrator.md。

四、内联标注：选中文字写批注，Agent 自动读取

这是 Specifications 视图最"人机协同"的能力，源码在 annotation/PlanAnnotator.tsx：

选中文本：在规范正文中选中任意段落
输入批注：侧边标注面板立即弹出，写完自动保存，无需手动提交
Agent 读取：批注写入项目的.annotations/<spec>.json，/spec的审批检查点会自动合并你的批注，修订计划后再次请求批准

标注由 parser.ts 解析为可寻址的块（block），保证批注锚点稳定、刷新不丢失。

团队协作标注

点头部卡的Share with Teammates即可生成https://pilot-shell.com/s/<id>持久分享链接：

审阅者无需安装 Pilot，浏览器打开即可添加批注
反馈单向回流：同事的批注约 1 分钟后进入你的 Console，按作者分组折叠展示，可逐条删除
链接有效期 7 天，过期重新生成即可

完整说明见 spec-collaboration.md。

五、快速上手清单

在 Claude Code 中运行/spec "你的需求描述"
计划生成后打开 Console →Specifications标签页
选中不满意的设计，直接写批注；点Approve前 Agent 会先消化你的标注
实现阶段通过任务卡勾选与## Deviations观察进度
Verify 通过后查看## E2E Results，规范状态变为VERIFIED✅

⚡ 小贴士：plan 文件必须使用LF换行符，CRLF 会导致任务卡片全部丢失。用pilot spec validate可以一键校验格式问题。

总结

Pilot Shell 的 Specifications 视图把"规范"从静态 Markdown 变成了带进度追踪、阶段网关、双向标注的活文档：进度一目了然，阶段推进有门控，人的意见通过内联标注直达 Agent。配合持久记忆与质量门，它让 AI 编码真正走向生产级交付。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析