帮助中心 >
Prompt
花漾TK CLI 业务对象文档规范
1. 输出目标
每个业务对象输出一份 Markdown 文档，同时面向：
- 中文业务人员
- 英文受众
- 研发实现
- AI Agent 调用
文档要求：
- 结构清晰
- 命令无歧义
- 字段可直接转为 Schema
- 命令可直接转为 CLI / MCP / Tool Calling 接口
2. 固定文档结构
每个业务对象固定使用以下结构：
## Object: <object>
Primary Locator:
- <locator>
### 1. Schema
#### <schemaName>
| Field | 中文属性 | Type | 中文说明 | English Description |
|---|---|---|---|---|
### 2. Action Specs
Returns: <returnType>
```bash
huayangtk-cli <object> <action> --param <type>
## 3. Object 命名规则
- Object 使用英文小写
- 多单词对象使用 kebab-case
- 示例：
- `shop`
- `product`
- `creator`
- `video`
- `live`
- `sample-request`
- `order`
- `buyer`
## 4. Schema 命名规则
- Schema 使用 camelCase
- 主结构命名为：`<object>BasicInfo`
- 子结构根据业务语义命名
- 示例：
- `creatorBasicInfo`
- `creatorShopRelation`
- `creatorSellingCapability`
- `videoProduct`
- `buyerContact`
## 5. Field 命名规则
- Field 使用 camelCase
- 面向产品语义，不使用数据库风格
- 不使用下划线
- 不使用晦涩技术命名
- 能用业务字段就不用技术字段
推荐：
```md
creatorId
shopCode
productId
mediaId
orderId
updateTime
不推荐：
creator_id
shop_id
product_pk
db_id
6. Primary Locator 规则
Primary Locator 表示该对象最常用的业务定位字段。
原则：
- 优先使用用户能理解的业务字段
- 不优先使用过于晦涩的内部唯一键
- 如果官方唯一键太晦涩，可以保留在 Schema 中，但不作为 CLI 默认定位参数
示例：
Primary Locator:
- creatorId
即使 cid 是 TikTok 官方不可变唯一键，也可以只放在 Schema 中，不作为主要 CLI 参数。
7. Schema 表格规则
Schema 表格固定为：
| Field | 中文属性 | Type | 中文说明 | English Description |
|---|---|---|---|---|
字段含义：
Field：英文属性名，camelCase中文属性：中文字段名Type：字段类型中文说明：给中文业务人员看的说明English Description：给英文受众和 AI 看的说明
8. Type 规则
常用类型：
string
number
boolean
datetime
string[]
number[]
<object>
<object>[]
示例：
| products | 带货商品 | videoProduct[] | 视频关联的带货商品列表 | Products promoted in the video |
| contacts | 联系方式 | buyerContact[] | 买家的联系方式列表 | Contact methods of the buyer |
9. 子数据结构规则
当一个字段本身是复杂对象时，必须单独定义子结构。
示例：
| products | 带货商品 | videoProduct[] | 视频关联的带货商品列表 | Products promoted in the video |
则必须补充：
#### videoProduct
| Field | 中文属性 | Type | 中文说明 | English Description |
|---|---|---|---|---|
| productId | 商品ID | string | 视频关联的商品ID | Product ID linked to the video |
| productName | 商品名称 | string | 视频关联的商品名称 | Product name linked to the video |
10. 枚举值规则
枚举值写在中文说明和英文说明中。
示例：
| status | 状态 | string | 当前索样请求状态，如：待审批、待发货、已发货、已完成、已取消 | Current status of the sample request |
11. Action Specs 规则
Action Specs 是命令的唯一 source of truth。
不再单独写 Actions 表。
所有命令必须写完整：
huayangtk-cli <object> <action> --param <type>
每组命令前必须写返回值：
Returns: creator[]
返回单个对象：
Returns: creator
返回子对象：
Returns: creatorSellingCapability
12. 默认 list 规则
当 object 后未指定 action 时，默认执行 list。
示例：
huayangtk-cli shop
等价于：
huayangtk-cli shop list
因此需要同时列出：
huayangtk-cli shop
huayangtk-cli shop list
13. list 查询规则
list 只列出真实支持的查询参数。
不要为了“看起来完整”添加不存在的筛选项。
示例：
huayangtk-cli creator --tag <string>
huayangtk-cli creator --cooperation-status <string>
huayangtk-cli creator --tag <string> --cooperation-status <string>
如果系统不支持按国家、语言、昵称查询，就不要写。
14. 时间范围规则
当列表数据量可能很大时，必须增加时间范围参数。
统一使用：
--start-time <datetime> --end-time <datetime>
示例：
huayangtk-cli live list --start-time <datetime> --end-time <datetime>
huayangtk-cli creator videos --creator-id <string> --start-time <datetime> --end-time <datetime>
15. get 规则
get 用于返回单个对象。
示例：
huayangtk-cli video get --media-id <string>
如果只有一个定位符，就只写一个。
不要为了技术完整性添加不常用或晦涩定位符。
16. 子资源查询规则
当一个对象可以返回相关资源时，使用子动作。
示例：
huayangtk-cli creator videos --creator-id <string> --start-time <datetime> --end-time <datetime>
huayangtk-cli creator lives --creator-id <string> --start-time <datetime> --end-time <datetime>
huayangtk-cli sample-request videos --request-id <string>
huayangtk-cli sample-request lives --request-id <string>
17. 状态操作规则
不要使用泛化的 update。
如果真实业务只允许修改某个状态，则使用明确 action。
推荐：
huayangtk-cli creator set-status --creator-id <string> --cooperation-status <string>
不推荐：
huayangtk-cli creator update --creator-id <string> --cooperation-status <string>
18. 标签操作规则
只有对象真实支持标签时，才提供：
add-tag
remove-tag
示例：
huayangtk-cli creator add-tag --creator-id <string> --tag <string>
huayangtk-cli creator remove-tag --creator-id <string> --tag <string>
不支持标签的对象，不写标签字段，也不写标签 action。
19. 备注操作规则
只有对象真实支持备注时，才提供：
huayangtk-cli <object> note --locator <string> --note <string>
不支持备注的对象，不写 note 字段，也不写 note action。
20. 关联对象规则
和其它业务对象关联时，应同时保留显示字段和定位字段。
示例：
店铺关联：
shopName
shopCode
商品关联：
productId
productName
达人关联：
creatorId
creatorNickname
媒体关联：
mediaId
21. 作品类对象规则
达人产出的作品包括：
- video
- live
统一使用：
mediaId
作为 Primary Locator。
22. 输出格式要求
最终输出必须是完整 Markdown。
不要输出解释性文字。
不要在文档外补充说明。
不要使用额外章节。
不要写 Options 表。
不要写 Output 示例。
不要拆分多个文档块。
23. 标准模板
## Object: <object>
Primary Locator:
- <primaryLocator>
### 1. Schema
#### <schemaName>
| Field | 中文属性 | Type | 中文说明 | English Description |
|---|---|---|---|---|
| fieldName | 中文字段 | string | 中文说明 | English description |
### 2. Action Specs
Returns: <object>[]
```bash
huayangtk-cli <object>
huayangtk-cli <object> list
Returns:
huayangtk-cli <object> get --<locator> <string>
