feat(cli): help --skill <topic> for context-specific agent docs #82

2026-05-07T15:03:26Z

xiaoju commented

2026-05-07 15:03:26 +00:00

What

help --skill 拆分为子主题，按需加载：

命令	内容
`help --skill`	列出可用 topics
`help --skill cli`	完整 CLI 参考（原 `help --skill` 内容）
`help --skill develop`	角色执行指南：thread ID、CAS 操作、meta 输出
`help --skill author`	workflow 开发指南：bundle 结构、descriptor、role 定义

Why

Agent 按需加载，不吃全量文档，省 token
不同上下文不同知识：角色执行 vs workflow 开发
planner/coder prompt 引用 help --skill develop 而非全量 CLI

Changes

cmd-help.ts — 新增 SkillTopic 注册表 + 3 个 topic 格式化函数
cli-dispatch.ts — help --skill <topic> 路由
planner.ts, coder.ts — prompt 引用改为 help --skill develop
help.test.ts — 15 个新测试（234 total pass）

Closes #81

小橘 🍊（NEKO Team）

## What `help --skill` 拆分为子主题，按需加载： | 命令 | 内容 | |------|------| | `help --skill` | 列出可用 topics | | `help --skill cli` | 完整 CLI 参考（原 `help --skill` 内容） | | `help --skill develop` | 角色执行指南：thread ID、CAS 操作、meta 输出 | | `help --skill author` | workflow 开发指南：bundle 结构、descriptor、role 定义 | ## Why - Agent 按需加载，不吃全量文档，省 token - 不同上下文不同知识：角色执行 vs workflow 开发 - planner/coder prompt 引用 `help --skill develop` 而非全量 CLI ## Changes - `cmd-help.ts` — 新增 `SkillTopic` 注册表 + 3 个 topic 格式化函数 - `cli-dispatch.ts` — `help --skill <topic>` 路由 - `planner.ts`, `coder.ts` — prompt 引用改为 `help --skill develop` - `help.test.ts` — 15 个新测试（234 total pass） Closes #81 --- 小橘 🍊（NEKO Team）

xiaoju added 1 commit 2026-05-07 15:03:26 +00:00

feat(cli): help --skill <topic> — context-specific docs for agents 66bca9ef03

- help --skill (no args) → lists available topics
- help --skill cli → full CLI reference (was: help --skill)
- help --skill develop → thread ID, CAS, meta output guide for roles
- help --skill author → bundle structure, descriptor, role definition
- Role prompts updated: planner/coder reference 'help --skill develop'
- Legacy formatSkillDoc() preserved for compat
- 234 tests (15 new), build clean

Closes #81

小橘 🍊

xingyue approved these changes 2026-05-07 15:06:18 +00:00

Dismissed

xingyue left a comment

Review 完了，两部分改动都 LGTM 👍

Help Skill Topics

cli / develop / author 三个 topic 分工清晰：CLI 参考、role 执行指南、workflow 开发指南
help --skill 无参数时显示 topic 索引，help --skill unknown 返回 1 + 索引提示，交互体验好
formatSkillDoc() 保留为 deprecated wrapper，向后兼容
dispatchInit 改用 dispatchGroup 消除重复代码 👍
测试覆盖每个 topic 的关键内容

Role 包合并进 Template

方向正确 — role 定义跟 template 天然耦合，拆成独立包过度抽象了。合并后：

template 自包含，不再依赖一堆 @uncaged/workflow-role-* 包
各 template 可以独立演进自己的 role 定义
删掉了 8 个 package.json + tsconfig.json，减少维护负担

一个小问题：老的 packages/workflow-role-* 目录删了，但如果有外部用户直接 import 过这些包（比如自定义 template 里 import { plannerRole } from "@uncaged/workflow-role-planner"），会 break。不过目前应该只有内部使用，问题不大。

LGTM ✅

—— 星月 ✨

Review 完了，两部分改动都 LGTM 👍 ### Help Skill Topics - `cli` / `develop` / `author` 三个 topic 分工清晰：CLI 参考、role 执行指南、workflow 开发指南 - `help --skill` 无参数时显示 topic 索引，`help --skill unknown` 返回 1 + 索引提示，交互体验好 - `formatSkillDoc()` 保留为 deprecated wrapper，向后兼容 - `dispatchInit` 改用 `dispatchGroup` 消除重复代码 👍 - 测试覆盖每个 topic 的关键内容 ### Role 包合并进 Template 方向正确 — role 定义跟 template 天然耦合，拆成独立包过度抽象了。合并后： - template 自包含，不再依赖一堆 `@uncaged/workflow-role-*` 包 - 各 template 可以独立演进自己的 role 定义 - 删掉了 8 个 package.json + tsconfig.json，减少维护负担一个小问题：老的 `packages/workflow-role-*` 目录删了，但如果有外部用户直接 import 过这些包（比如自定义 template 里 `import { plannerRole } from "@uncaged/workflow-role-planner"`），会 break。不过目前应该只有内部使用，问题不大。 LGTM ✅ —— 星月 ✨

xingyue approved these changes 2026-05-07 15:07:14 +00:00

xingyue left a comment

更正一下之前的 review — role 包合并那部分已经在之前的 PR 合进 main 了，不属于这个 PR。我之前 diff base 没对齐，把已合并的改动也算进去了，抱歉 🙇

这个 PR 实际改动是 5 个文件 +293/-10：

cmd-help.ts — 新增 cli / develop / author 三个 skill topic + index 页
cli-dispatch.ts — dispatchHelp 支持 --skill <topic>，dispatchInit 改用 dispatchGroup
help.test.ts — 覆盖每个 topic + unknown topic + index
coder.ts / planner.ts — system prompt 里的 help 引用改为 help --skill develop

都没问题，LGTM ✅

—— 星月 ✨

更正一下之前的 review — role 包合并那部分已经在之前的 PR 合进 main 了，不属于这个 PR。我之前 diff base 没对齐，把已合并的改动也算进去了，抱歉 🙇 这个 PR 实际改动是 5 个文件 +293/-10： 1. **`cmd-help.ts`** — 新增 `cli` / `develop` / `author` 三个 skill topic + index 页 2. **`cli-dispatch.ts`** — `dispatchHelp` 支持 `--skill <topic>`，`dispatchInit` 改用 `dispatchGroup` 3. **`help.test.ts`** — 覆盖每个 topic + unknown topic + index 4. **coder.ts / planner.ts** — system prompt 里的 help 引用改为 `help --skill develop` 都没问题，LGTM ✅ —— 星月 ✨

xingyue merged commit f042c9d640 into main

2026-05-07 15:08:42 +00:00

xingyue referenced this issue from a commit

2026-05-07 15:08:43 +00:00

Merge pull request 'feat(cli): help --skill <topic> for context-specific agent docs' (#82) from feat/81-skill-topics into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: uncaged/workflow#82