uncaged/workflow
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(cli): help --skill — 输出 agent 可消费的完整用法文档 #69

New Issue
Closed
opened 2026-05-07 14:16:05 +00:00 by xiaomo · 0 comments
xiaomo commented 2026-05-07 14:16:05 +00:00
Owner
Copy Link
Copy Source

Summary

新增 uncaged-workflow help --skill，输出当前版本 CLI 的完整用法文档（Markdown 格式），供 coding agent 直接消费。

Motivation

Workflow 大量依赖 agent 调用 uncaged-workflow 命令。目前的问题：

  • 如果把用法写在外部 SKILL 文件里，跟 CLI 版本分离，容易不一致
  • 每次改命令都要同步更新外部文档，迟早忘
  • Agent 需要一个 single source of truth，直接从 CLI 获取

Design

命令接口

# 普通 help（现有的简洁 usage）
uncaged-workflow help

# Agent 用法文档（详细 Markdown）
uncaged-workflow help --skill

输出内容（Markdown）

# uncaged-workflow CLI Reference

## Core Concepts

- **Workflow** — 注册在 registry 中的工作流定义，由 ESM bundle 实现
- **Bundle** — `.esm.js` 单文件，存储在 `~/.uncaged/workflow/bundles/`
- **Thread** — 一次 workflow 执行，ULID 标识，持久化为 JSONL
- **CAS** — Content-Addressable Storage，存储 workflow 产出物

## Commands

### workflow — 注册表管理

  workflow add <name> <file.esm.js> [--types <path>]
    注册一个 workflow bundle。name 是 kebab-case 标识符。
    --types: 可选的 .d.ts sidecar 文件路径。

  workflow list
    列出所有已注册的 workflow。

  ...(每个命令的参数、说明、示例)

### thread — 执行管理
  ...

### cas — 内容寻址存储
  ...

## Typical Workflow

1. 注册 workflow:
   uncaged-workflow workflow add solve-issue ./dist/solve-issue.esm.js

2. 启动执行:
   uncaged-workflow run solve-issue --prompt "Fix bug #123"

3. 实时查看:
   uncaged-workflow live --latest

4. 查看结果:
   uncaged-workflow thread show <thread-id>

## Exit Codes

- 0: 成功
- 1: 错误（参数错误、命令失败等）

## Environment Variables

- UNCAGED_WORKFLOW_STORAGE_ROOT: 自定义存储根目录（默认 ~/.uncaged/workflow）

维护方式

  • 文档内容作为模板字符串放在 cmd-help.ts 里
  • 命令用法部分可以从各 dispatch table 自动生成（避免手动同步）
  • 概念说明和示例部分手写
  • 每次新增/修改命令时，CI 可以校验 help --skill 输出是否覆盖所有注册命令

Agent 集成

各 agent 的提示词只需一行：

运行 `uncaged-workflow help --skill` 查看完整的 CLI 用法。

不再需要维护外部 SKILL 文件中的命令文档。

Acceptance Criteria

  • uncaged-workflow help 输出简洁 usage（现有行为）
  • uncaged-workflow help --skill 输出完整 Markdown 文档
  • 文档覆盖所���已注册命令
  • 包含核心概念、典型工作流、退出码、环境变量
  • 有测试覆盖
## Summary 新增 `uncaged-workflow help --skill`，输出当前版本 CLI 的完整用法文档（Markdown 格式），供 coding agent 直接消费。 ## Motivation Workflow 大量依赖 agent 调用 `uncaged-workflow` 命令。目前的问题： - 如果把用法写在外部 SKILL 文件里，跟 CLI 版本分离，容易不一致 - 每次改命令都要同步更新外部文档，迟早忘 - Agent 需要一个 **single source of truth**，直接从 CLI 获取 ## Design ### 命令接口 ```bash # 普通 help（现有的简洁 usage） uncaged-workflow help # Agent 用法文档（详细 Markdown） uncaged-workflow help --skill ``` ### 输出内容（Markdown） ```markdown # uncaged-workflow CLI Reference ## Core Concepts - **Workflow** — 注册在 registry 中的工作流定义，由 ESM bundle 实现 - **Bundle** — `.esm.js` 单文件，存储在 `~/.uncaged/workflow/bundles/` - **Thread** — 一次 workflow 执行，ULID 标识，持久化为 JSONL - **CAS** — Content-Addressable Storage，存储 workflow 产出物 ## Commands ### workflow — 注册表管理 workflow add <name> <file.esm.js> [--types <path>] 注册一个 workflow bundle。name 是 kebab-case 标识符。 --types: 可选的 .d.ts sidecar 文件路径。 workflow list 列出所有已注册的 workflow。 ...(每个命令的参数、说明、示例) ### thread — 执行管理 ... ### cas — 内容寻址存储 ... ## Typical Workflow 1. 注册 workflow: uncaged-workflow workflow add solve-issue ./dist/solve-issue.esm.js 2. 启动执行: uncaged-workflow run solve-issue --prompt "Fix bug #123" 3. 实时查看: uncaged-workflow live --latest 4. 查看结果: uncaged-workflow thread show <thread-id> ## Exit Codes - 0: 成功 - 1: 错误（参数错误、命令失败等） ## Environment Variables - UNCAGED_WORKFLOW_STORAGE_ROOT: 自定义存储根目录（默认 ~/.uncaged/workflow） ``` ### 维护方式 - 文档内容作为模板字符串放在 `cmd-help.ts` 里 - 命令用法部分可以从各 dispatch table 自动生成（避免手动同步） - 概念说明和示例部分手写 - 每次新增/修改命令时，CI 可以校验 help --skill 输出是否覆盖所有注册命令 ### Agent 集成 各 agent 的提示词只需一行： ``` 运行 `uncaged-workflow help --skill` 查看完整的 CLI 用法。 ``` 不再需要维护外部 SKILL 文件中的命令文档。 ## Acceptance Criteria - [ ] `uncaged-workflow help` 输出简洁 usage（现有行为） - [ ] `uncaged-workflow help --skill` 输出完整 Markdown 文档 - [ ] 文档覆盖所���已注册命令 - [ ] 包含核心概念、典型工作流、退出码、环境变量 - [ ] 有测试覆盖
xiaomo self-assigned this 2026-05-07 14:16:05 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees xiaomo
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#69
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?