Workhub
文档管理与任务跟踪工具，强制执行 SSOT（Single Source of Truth）原则，支持 GitHub 风格的 Issues 和 PRs 工作流。
执行环境
路径类型 路径 基准目录
技能目录 ~/.pi/agent/skills/workhub/
固定位置
主脚本 ~/.pi/agent/skills/workhub/lib.ts
技能目录
项目文档目录 ./docs/
工作目录 (执行命令时的当前目录)
标准文档结构
docs/ ├── adr/ # 架构决策记录 ├── architecture/ # 架构设计文档 ├── issues/ # 任务跟踪 │ ├── [模块分类]/ # 可选：按模块分类 │ │ └── yyyymmdd-[描述].md │ └── yyyymmdd-[描述].md ├── pr/ # 变更记录 │ ├── [模块分类]/ │ │ └── yyyymmdd-[描述].md │ └── yyyymmdd-[描述].md └── guides/ # 使用指南
调用命令
正确方式：从项目目录执行
cd /path/to/your/project ~/.pi/agent/skills/workhub/lib.ts <command>
文档操作
- 初始化 (init )
创建标准文档目录结构。
~/.pi/agent/skills/workhub/lib.ts init
- 查看结构 (tree )
显示文档目录树。
~/.pi/agent/skills/workhub/lib.ts tree
- 审计规范 (audit )
检查 docs/ 文件夹是否遵循标准规范。
~/.pi/agent/skills/workhub/lib.ts audit
- 读取文档 (read )
通过关键词或相对路径读取文档。
~/.pi/agent/skills/workhub/lib.ts read issues/20250106-添加深色模式.md
- 创建 Issue (create issue )
创建新的 Issue 文件，自动使用模板。
~/.pi/agent/skills/workhub/lib.ts create issue "添加深色模式" 前端
- 创建 PR (create pr )
创建新的 PR 文件，自动使用模板。
~/.pi/agent/skills/workhub/lib.ts create pr "修复登录bug" 后端
- 列出 Issues (list issues )
列出所有 Issues 及其状态。
~/.pi/agent/skills/workhub/lib.ts list issues
- 列出 PRs (list prs )
列出所有 PRs 及其状态。
~/.pi/agent/skills/workhub/lib.ts list prs
- 查看状态 (status )
显示所有 Issues 和 PRs 的状态概览。
~/.pi/agent/skills/workhub/lib.ts status
- 搜索内容 (search )
在 Issues 和 PRs 中搜索关键词。
~/.pi/agent/skills/workhub/lib.ts search "深色模式"
GitHub 风格工作流
Issue 工作流
-
创建 Issue 文件 (使用模板) → docs/issues/yyyymmdd-[描述].md 或 docs/issues/[模块分类]/yyyymmdd-[描述].md
-
填写 Goal、Phases、Acceptance Criteria
-
执行阶段：
- Read Issue 文件（刷新目标）
- 完成子任务 → 更新复选框 [x]
- 遇到错误 → 记录到 "Errors Encountered"
- 记录 Notes → 保存研究发现
-
完成后创建 PR 文件 → docs/pr/yyyymmdd-[描述].md
-
PR 文件关联 Issue 文件名 → 包含回滚计划、测试验证
PR 工作流
-
创建 PR 文件 (使用模板) → docs/pr/yyyymmdd-[描述].md 或 docs/pr/[模块分类]/yyyymmdd-[描述].md
-
填写背景、变更内容、测试验证、回滚计划
-
关联 Issue 文件名 → 在 "关联 Issue" 中填写完整路径
-
代码审查和合并 → 记录审查日志 → 更新最终状态
核心原则
- SSOT (Single Source of Truth)
-
每个知识领域只有一个权威文档
-
Issues 是任务跟踪的唯一来源
-
PRs 是变更记录的唯一来源
- 文件系统即记忆
-
大输出内容保存到文件，而非堆砌到上下文
-
工作记忆中只保留文件路径
-
需要时通过 workhub read 读取
- 状态管理
-
决策前读取 Issue：刷新目标，保持注意力
-
行动后更新 Issue：标记 [x]，更新 Status
-
错误记录：在 Issue 的 "Errors Encountered" 中记录
- 变更可追溯
-
每个 PR 必须关联 Issue
-
Issue 记录完整决策过程
-
PR 记录变更细节和回滚计划
最佳实践
创建 Issue
1. 初始化文档结构（首次）
~/.pi/agent/skills/workhub/lib.ts init
2. 创建 Issue 文件
~/.pi/agent/skills/workhub/lib.ts create issue "添加深色模式" 前端
3. 编辑文件，填写 Goal、Phases、Acceptance Criteria
执行 Issue
1. 读取 Issue（刷新目标）
~/.pi/agent/skills/workhub/lib.ts read issues/前端/20250106-添加深色模式.md
2. 完成子任务后更新 Issue
编辑文件，标记复选框 [x]
3. 遇到错误时记录
在 "Errors Encountered" 表格中添加记录
创建 PR
1. 创建 PR 文件
~/.pi/agent/skills/workhub/lib.ts create pr "添加深色模式" 前端
2. 编辑文件，填写变更内容、测试验证、回滚计划
3. 关联 Issue 文件名
在 "关联 Issue" 中填写完整路径
错误恢复模式
1. 读取 Issue
~/.pi/agent/skills/workhub/lib.ts read issues/20250106-添加深色模式.md
2. 在 "Errors Encountered" 中记录
| 日期 | 错误 | 解决方案 | | 2025-01-06 | FileNotFoundError | 创建默认配置 |
3. 执行解决方案
创建默认配置文件
4. 更新 Issue 的 Notes
Quick Reference
命令 功能 示例
init
初始化文档结构 ~/.pi/agent/skills/workhub/lib.ts init
tree
查看文档结构 ~/.pi/agent/skills/workhub/lib.ts tree
audit
审计文档规范 ~/.pi/agent/skills/workhub/lib.ts audit
read
读取文档 ~/.pi/agent/skills/workhub/lib.ts read issues/xxx.md
create issue
创建 Issue ~/.pi/agent/skills/workhub/lib.ts create issue "描述" [分类]
create pr
创建 PR ~/.pi/agent/skills/workhub/lib.ts create pr "描述" [分类]
list issues
列出所有 Issues ~/.pi/agent/skills/workhub/lib.ts list issues
list prs
列出所有 PRs ~/.pi/agent/skills/workhub/lib.ts list prs
status
查看整体状态 ~/.pi/agent/skills/workhub/lib.ts status
search
搜索内容 ~/.pi/agent/skills/workhub/lib.ts search "关键词"
扩展计划
未来可能添加的功能：
-
交互式创建 Issue
-
交互式创建 PR
-
关联 Issue 和 PR