docs: usage/cli reference 缺少 .workflow/ 自动发现说明，agent 总走 workflow add #162

New Issue

2026-06-07T14:30:16Z

xiaoju commented

2026-06-07 14:30:16 +00:00

现象

Agent（包括 solve-issue 流水线中的角色）在需要使用 workflow 时，总是倾向于手动 uwf workflow add <file> 注册，然后 uwf thread start <name>。从未使用过项目本地 .workflow/ 目录的自动发现能力。

原因

三个 reference 文件都没提到 .workflow/ 自动发现：

usage-reference.ts — Quick Start 只展示 workflow add 注册流程
cli-reference.ts — thread start <workflow> 没说明 workflow 参数支持名字自动解析
workflow-authoring-reference.ts — Self-Testing 只提了文件路径和手动注册

而代码中 resolveWorkflowCasRef() 实际支持 4 层解析策略：

CAS hash 直接引用
文件路径（相对/绝对）
.workflow/ 目录递归向上查找 ← 完全没文档
全局 registry fallback（workflow add 注册的）

Bug: workflow list 不递归向上

thread start 和 workflow list 的本地发现行为不一致：

操作	向上递归	实现
`thread start solve-issue`	✅ `findWorkflowInParents()` 从 cwd 递归向上	`commands/thread.ts`
`workflow list`	❌ `discoverProjectWorkflows()` 只看 cwd 下	`store.ts`

如果在 src/ 子目录跑 workflow list，看不到项目根目录的 .workflow/，但 thread start 能找到。应该对齐 — workflow list 也递归向上查找。

期望

1. 修复 workflow list 递归向上

discoverProjectWorkflows() 应该像 findWorkflowInParents() 一样从 cwd 递归向上查找 .workflow/ 目录，或者复用同一个查找逻辑。

2. 文档补充

在 usage-reference.ts 和 cli-reference.ts 中说明：

# 项目中放置 workflow：
# .workflow/solve-issue.yaml  ← 推荐！
#
# 然后直接用名字启动，无需 workflow add：
uwf thread start solve-issue -p "Fix the bug"
#
# uwf 会从 cwd 递归向上查找 .workflow/solve-issue.yaml

3. 强调项目本地 workflow 优先

文档和 Quick Start 应该优先推荐项目本地 .workflow/ 方式：

✅ 项目本地 .workflow/ — 跟着项目走，版本控制，团队共享
⚠️ workflow add 全局注册 — 只适合个人全局 workflow
⚠️ 文件路径 — 临时测试用

Quick Start 应改为：

# 1. Configure provider and model
uwf setup

# 2. Place workflow in project (recommended)
#    .workflow/solve-issue.yaml

# 3. Start a thread by name (auto-discovers from .workflow/)
uwf thread start solve-issue -p "Fix the login bug"

# 4. Execute
uwf thread exec <thread-id>

4. workflow-authoring-reference 补充放置位置说明

在 Self-Testing 之前加一节 Placement：

## Placement

Put workflow YAML files in `.workflow/` at the project root:

my-project/
  .workflow/
    solve-issue.yaml
    review-code.yaml
  src/
  ...

`uwf thread start solve-issue` will auto-discover `.workflow/solve-issue.yaml`
by searching from cwd upward. No `workflow add` registration needed.

改动范围

packages/cli/src/store.ts — discoverProjectWorkflows() 改为递归向上
packages/util/src/usage-reference.ts
packages/util/src/cli-reference.ts
packages/util/src/workflow-authoring-reference.ts
可能 packages/cli/README.md

小橘 🍊（NEKO Team）

## 现象 Agent（包括 solve-issue 流水线中的角色）在需要使用 workflow 时，总是倾向于手动 `uwf workflow add <file>` 注册，然后 `uwf thread start <name>`。从未使用过项目本地 `.workflow/` 目录的自动发现能力。 ## 原因三个 reference 文件都没提到 `.workflow/` 自动发现： - **`usage-reference.ts`** — Quick Start 只展示 `workflow add` 注册流程 - **`cli-reference.ts`** — `thread start <workflow>` 没说明 workflow 参数支持名字自动解析 - **`workflow-authoring-reference.ts`** — Self-Testing 只提了文件路径和手动注册而代码中 `resolveWorkflowCasRef()` 实际支持 4 层解析策略： 1. CAS hash 直接引用 2. 文件路径（相对/绝对） 3. **`.workflow/` 目录递归向上查找** ← 完全没文档 4. 全局 registry fallback（`workflow add` 注册的） ## Bug: workflow list 不递归向上 `thread start` 和 `workflow list` 的本地发现行为不一致： | 操作 | 向上递归 | 实现 | |------|---------|------| | `thread start solve-issue` | ✅ `findWorkflowInParents()` 从 cwd 递归向上 | `commands/thread.ts` | | `workflow list` | ❌ `discoverProjectWorkflows()` 只看 cwd 下 | `store.ts` | 如果在 `src/` 子目录跑 `workflow list`，看不到项目根目录的 `.workflow/`，但 `thread start` 能找到。应该对齐 — `workflow list` 也递归向上查找。 ## 期望 ### 1. 修复 workflow list 递归向上 `discoverProjectWorkflows()` 应该像 `findWorkflowInParents()` 一样从 cwd 递归向上查找 `.workflow/` 目录，或者复用同一个查找逻辑。 ### 2. 文档补充在 `usage-reference.ts` 和 `cli-reference.ts` 中说明： ``` # 项目中放置 workflow： # .workflow/solve-issue.yaml ← 推荐！ # # 然后直接用名字启动，无需 workflow add： uwf thread start solve-issue -p "Fix the bug" # # uwf 会从 cwd 递归向上查找 .workflow/solve-issue.yaml ``` ### 3. 强调项目本地 workflow 优先文档和 Quick Start 应该**优先推荐**项目本地 `.workflow/` 方式： - ✅ 项目本地 `.workflow/` — 跟着项目走，版本控制，团队共享 - ⚠️ `workflow add` 全局注册 — 只适合个人全局 workflow - ⚠️ 文件路径 — 临时测试用 Quick Start 应改为： ```bash # 1. Configure provider and model uwf setup # 2. Place workflow in project (recommended) # .workflow/solve-issue.yaml # 3. Start a thread by name (auto-discovers from .workflow/) uwf thread start solve-issue -p "Fix the login bug" # 4. Execute uwf thread exec <thread-id> ``` ### 4. workflow-authoring-reference 补充放置位置说明在 Self-Testing 之前加一节 Placement： ```markdown ## Placement Put workflow YAML files in `.workflow/` at the project root: my-project/ .workflow/ solve-issue.yaml review-code.yaml src/ ... `uwf thread start solve-issue` will auto-discover `.workflow/solve-issue.yaml` by searching from cwd upward. No `workflow add` registration needed. ``` ## 改动范围 - `packages/cli/src/store.ts` — `discoverProjectWorkflows()` 改为递归向上 - `packages/util/src/usage-reference.ts` - `packages/util/src/cli-reference.ts` - `packages/util/src/workflow-authoring-reference.ts` - 可能 `packages/cli/README.md` 小橘 🍊（NEKO Team）

xiaoju referenced this issue from a commit

2026-06-07 15:11:31 +00:00

fix(cli): align workflow list with thread start via parent traversal

xiaoju referenced a pull request that will close this issue

2026-06-07 15:14:21 +00:00

fix(cli): workflow list parent traversal + docs for .workflow/ auto-discovery #167

scottwei closed this issue

2026-06-07 15:23:18 +00:00

Sign in to join this conversation.