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>

文档操作

1. 初始化 (`init`)

创建标准文档目录结构。

~/.pi/agent/skills/workhub/lib.ts init

2. 查看结构 (`tree`)

显示文档目录树。

~/.pi/agent/skills/workhub/lib.ts tree

3. 审计规范 (`audit`)

检查 docs/ 文件夹是否遵循标准规范。

~/.pi/agent/skills/workhub/lib.ts audit

4. 读取文档 (`read`)

通过关键词或相对路径读取文档。

~/.pi/agent/skills/workhub/lib.ts read issues/20250106-添加深色模式.md

5. 创建 Issue (`create issue`)

创建新的 Issue 文件，自动使用模板。

~/.pi/agent/skills/workhub/lib.ts create issue "添加深色模式" 前端

6. 创建 PR (`create pr`)

创建新的 PR 文件，自动使用模板。

~/.pi/agent/skills/workhub/lib.ts create pr "修复登录bug" 后端

7. 列出 Issues (`list issues`)

列出所有 Issues 及其状态。

~/.pi/agent/skills/workhub/lib.ts list issues

8. 列出 PRs (`list prs`)

列出所有 PRs 及其状态。

~/.pi/agent/skills/workhub/lib.ts list prs

9. 查看状态 (`status`)

显示所有 Issues 和 PRs 的状态概览。

~/.pi/agent/skills/workhub/lib.ts status

10. 搜索内容 (`search`)

在 Issues 和 PRs 中搜索关键词。

~/.pi/agent/skills/workhub/lib.ts search "深色模式"

GitHub 风格工作流

Issue 工作流

1. 创建 Issue 文件 (使用模板)
   → docs/issues/yyyymmdd-[描述].md
   或 docs/issues/[模块分类]/yyyymmdd-[描述].md

2. 填写 Goal、Phases、Acceptance Criteria

3. 执行阶段：
   - Read Issue 文件（刷新目标）
   - 完成子任务 → 更新复选框 [x]
   - 遇到错误 → 记录到 "Errors Encountered"
   - 记录 Notes → 保存研究发现

4. 完成后创建 PR 文件
   → docs/pr/yyyymmdd-[描述].md

5. PR 文件关联 Issue 文件名
   → 包含回滚计划、测试验证

PR 工作流

1. 创建 PR 文件 (使用模板)
   → docs/pr/yyyymmdd-[描述].md
   或 docs/pr/[模块分类]/yyyymmdd-[描述].md

2. 填写背景、变更内容、测试验证、回滚计划

3. 关联 Issue 文件名
   → 在 "关联 Issue" 中填写完整路径

4. 代码审查和合并
   → 记录审查日志
   → 更新最终状态

核心原则

1. SSOT (Single Source of Truth)

每个知识领域只有一个权威文档
Issues 是任务跟踪的唯一来源
PRs 是变更记录的唯一来源

2. 文件系统即记忆

大输出内容保存到文件，而非堆砌到上下文
工作记忆中只保留文件路径
需要时通过 workhub read 读取

3. 状态管理

决策前读取 Issue：刷新目标，保持注意力
行动后更新 Issue：标记 [x]，更新 Status
错误记录：在 Issue 的 "Errors Encountered" 中记录

4. 变更可追溯

每个 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

调用命令

文档操作

1. 初始化 (init)

2. 查看结构 (tree)

3. 审计规范 (audit)

4. 读取文档 (read)

5. 创建 Issue (create issue)

6. 创建 PR (create pr)

7. 列出 Issues (list issues)

8. 列出 PRs (list prs)

9. 查看状态 (status)

10. 搜索内容 (search)

GitHub 风格工作流

Issue 工作流

PR 工作流

核心原则

1. SSOT (Single Source of Truth)

2. 文件系统即记忆

3. 状态管理

4. 变更可追溯

最佳实践

创建 Issue

执行 Issue

创建 PR

错误恢复模式

Quick Reference

扩展计划

1. 初始化 (`init`)

2. 查看结构 (`tree`)

3. 审计规范 (`audit`)

4. 读取文档 (`read`)

5. 创建 Issue (`create issue`)

6. 创建 PR (`create pr`)

7. 列出 Issues (`list issues`)

8. 列出 PRs (`list prs`)

9. 查看状态 (`status`)

10. 搜索内容 (`search`)

路径类型	路径	基准目录
技能目录	`~/.pi/agent/skills/workhub/`	固定位置
主脚本	`~/.pi/agent/skills/workhub/lib.ts`	技能目录
项目文档目录	`./docs/`	工作目录 (执行命令时的当前目录)

workhub

Workhub

执行环境

标准文档结构