Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

feat(help): 引入 Affordance 命令级调用指引

Open
  • Is something wrong?
#31 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
go, markdown
Domain
cli, developer-experience

Research direction

Start with main.go, cmd/system/register.go, internal/system/registry.go, and cmd/skills.go to trace how embedded Skills, registered command paths, and help rendering currently work. Then define the Guidance format and Resolver around the final command tree, including reference validation and shared rendering for YAML, Go, and subsystem commands. Done means the listed help behaviors and validation cases pass, first-batch JOB, CMDB, API Gateway, and subsystem guidance is covered, and the named documentation is updated.

Written by the indexing model from the issue text.

Description

背景与目标

Agent 读到命令名、参数列表和示例后，仍可能不知道何时应该用这个命令、输入 ID 从哪里获得、什么时候应该换另一个命令。希望借鉴 larksuite/cli 的 Affordance，在命令旁提供简短、可维护、可验证的调用指引，降低选错命令和猜测参数的次数。

本 Issue 是需求与实现方案，尚未实现；下面新增目录、类型及展示方式均为建议。调研日期：2026-10-18。

现有能力与缺口

基线为 bk-cli 80065f5。

  • YAML action 注册及 help 已提供 description、examples、flags；带 body_schema 的命令有自定义 help，完整 schema 通过 -h --body-schema 展示。
  • 内置 Skills 已支持 list/read 和 reference 文件。缺口是命令级指引与精确 Skill 入口，不是重新实现 Skills。
  • action 元数据 没有统一的适用场景、前置条件、替代命令及 Skill 引用。
  • 既有 YAML action、Go action、一层 subsystem 均应适用。

典型用户场景

  1. Agent 需要查 JOB 执行状态，help 告诉它 job_instance_id 来自执行作业返回值，不应填任务模板 ID。
  2. Agent 需要盘点业务全部主机，单页查询的指引提示改用 cmdb list_biz_hosts_all，避免把一页当全部。
  3. Agent 收到 API 调用失败，需要精确找到 bk-cli-shared/references/api-debug.md，而非读所有系统的 Skill。
  4. Agent 通过 bcs cluster_manager ... 访问 subsystem，指引仍能正确匹配完整命令路径。

参考机制：Affordance 为什么有用

飞书以每个 domain 一个 Markdown 文件维护指引：二级标题标识命令，正文说明适用场景，三级标题承载 Avoid when / Prerequisites / Tips / Examples / Skills。[[command]] 表达跨命令引用。运行时通过与真实命令目录绑定的 Resolver 按 domain 懒加载、解析并缓存，供 help 和 schema 输出复用。

它是一层“选择和使用命令的上下文”，不是 API 参数 Schema，也不是执行策略；文案不会自动替用户查 ID、授予权限或执行下一步。

参考：格式说明、Resolver、Markdown 解析。

建议需求与范围

1. 单一指引来源

建议采用 affordance/<system>.md，每个命令允许以下内容：

内容 回答的问题
适用场景 用户要完成什么目标时用它？
不适用场景 / 替代入口 什么情况下应换一个命令？
前置条件 需要什么身份、范围、ID？ID 从哪里获得？
注意事项 分页、异步状态、完整性、字段含义等易错点
Skills 应读哪个 Skill 或具体 reference？

第一期保留 action / Go command 内的参数和可执行示例作为权威来源，避免在 Markdown 再复制一份 examples。若后续迁移示例，需要明确覆盖与去重规则，不能两处各自维护。

建议示意，命令引用为本系统内的完整 action 路径：

# job
> skill: bk-cli-job

## get_job_instance_status
用于查询已提交作业实例的执行状态。

### Prerequisites
- job_instance_id 来自 [[fast_execute_script]] 等提交命令的响应；具体字段路径以当前接口协议为准。

### Tips
- 请求成功不代表作业执行成功；应读取明确的任务状态。

### Skills
- bk-cli-job
2. 命令匹配与引用规则
  • 使用实际注册命令的完整 token 路径作为主键，保留原有命名，不做下划线、连字符、单复数的模糊转换。
  • subsystem 命令的标题使用 cluster_manager <action> 等完整相对路径；不能仅以 action 名匹配。
  • 跨系统引用采用显式 [[bk-cli <system> [subsystem] <action>]]；本系统引用采用相对路径。解析结果必须能在最终命令树找到。
  • 系统级默认 Skill 与命令级 Skill 去重；系统级额外推荐 Skill 不自动传播到所有命令。
  • Skill reference 只允许已嵌入的相对资源，不读取任意本地路径，不联网取文档。
3. 展示规则
  • 默认 action help 保留现有 Usage、Examples、Flags 和 body schema 提示，并增加简短指引及可直接执行的 bk-cli skills read ... 入口。
  • -h --body-schema 保留现有“只展示完整 body schema”的行为，不混入大段指引。
  • 系统/subsystem help 只展示本层简短说明及 Skill 入口，不展开所有子命令的指引。
  • 没有指引的命令保持原有 help；help 不应要求 context、凭据或网络。
  • 结构化 Guidance 对象应可供未来 schema/describe 功能复用，但完整命令 Schema 平台不作为本 Issue 的前置条件或第一期范围。

实现原理与代码落点

affordance/*.md + 已嵌入 Skills
  → 有限 Markdown 解析器
  → Guidance 对象 + 引用校验
  → 与最终命令路径绑定的 Resolver
  → YAML / Go 命令共用 help 渲染
  • main.go 通过 go:embed 注入只读内容，沿用当前 Skills 的依赖注入思路。
  • internal/* 提供解析、缓存和引用校验；由 cmd/* 将最终注册命令目录传入，禁止 internal 反向依赖 cmd。
  • 仅按实际需要读取一个 system 的内容，缓存限定在当前命令树/Resolver，避免不同测试或不同 build 之间串数据。
  • 在 cmd/system/register.go 统一接入，不能只覆盖 Cobra 默认 help、漏掉 body_schema 自定义 help 或 Go action。
  • 只支持文档声明的 Markdown 子集；不引入完整 Markdown 渲染引擎、模板执行或动态插件。
  • 受版本控制的内容错误应由测试/CI 报出：未知命令、重复标题、失效 Skill/reference、错误相对路径。运行时缺少可选指引时可回退原 help；不能把错误引用静默隐藏作为唯一校验方式。

首批交付与非目标

  • 首批覆盖 JOB 提交/状态/日志、CMDB 单页/全量查询、API Gateway 发现/详情/排错，并提供至少一个 subsystem 用例。
  • 不改变请求行为、授权、风险门禁和退出码。
  • 不扩展命令层级，不新增业务 API，不替代完整任务型 Skill。
  • 关联现有 #5 的快捷层，但可以独立交付；与 #8 的执行策略保持边界，指引不是强制策略。

验收标准

  • YAML action、Go action、subsystem 三种形态都能展示正确指引。
  • 未配置 context、未登录、断网时仍可查看 help。
  • Usage / Examples / Flags / -h --body-schema 的现有行为有回归覆盖。
  • 命令同名但父路径不同不会串指引。
  • 引用删除、命令改名、Skill reference 失效、重复标题会使内容校验失败。
  • 未配置指引的命令不出现空标题或改变调用行为。
  • 有少量基于任务的对照案例，验证 Agent 能找到 ID 来源、全量查询入口和排错 Skill；不把 help 快照通过当作 Agent 效果证明。

验证与文档

实现时补充解析/引用/渲染测试、真实命令 help 集成用例，并执行仓库适用的 fmt/lint/test/build；这次需求分析未运行应用测试。同步 docs/design.md、AGENTS.md、系统扩展技能、相关使用 Skills，以及涉及使用方式的中英文 README/用户指南。明确各文档职责，避免把用户 Skill 写成解析器实现手册。

配套需求

建议先冻结结果判定和聚合输出的契约，再让分页与 jq 共用输出边界。Affordance 可独立推进；jq 不需要等待全部系统的业务适配完成，但不得越过既有结果判定。以上属于配套关系，不要求四项合并为一个实现 PR。

Dominant language
Go
Stars
7
Forks
6
Avg merge
2d 19h
Merged PRs (30d)
14

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from TencentBlueKing/bk-cli

All issues in TencentBlueKing/bk-cli

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.