ChatStyle 是从 ChatTool 实践中独立出来的 CLI 交互风格与运行时工具包。它提供 prompt、choice、output、flow、mask、interactive 策略和 CommandSchema runtime，让新的 CLI 项目可以复用统一的缺参补问、-i/-I、TTY 判断、默认值和校验流程。
当前版本仍是 0.1.0，用于本地开发和后续发版准备。
chatstyle.input：命令输入声明、缺参补问解析和 Click-i/-I接入。chatstyle.tui：文本、路径、确认、单选、多选 prompt，以及 choice/separator 适配。chatstyle.render：标题、提示、状态、建议命令、表格、列表、摘要和多步骤 flow 展示。chatstyle.security：敏感值脱敏、当前值提示和敏感输入。chatstyle.core：TTY、interactive 三态策略、共享常量和错误 helper。chatstyle.patterns：跨模块组合模式，例如多来源值解析、文本/敏感值补问。
ChatStyle 按使用职能组织代码，避免把所有 runtime 文件平铺在顶层。顶层 chatstyle 仍提供常用 API 聚合入口；需要按职能导入时，使用下面的子包。
src/chatstyle/
├── __init__.py # 常用 public API 聚合入口，例如 CommandSchema、ask_text、render_success
├── input/ # CLI 输入声明、解析和 Click 集成
│ ├── schema.py # CommandField / CommandSchema / CommandConstraint
│ ├── resolve.py # resolve_command_inputs：缺参补问、默认值、校验、TTY 策略
│ └── click.py # add_interactive_option：统一 -i/-I option
├── tui/ # 终端交互输入原语
│ ├── prompt.py # text/path/confirm/select/checkbox prompt
│ └── choice.py # choice、separator、questionary adapter
├── render/ # 业务中立的输出和流程展示
│ ├── output.py # heading、note、status、table、summary、suggested commands
│ └── flow.py # stage、plan、dry-run、config priority/source
├── security/ # 敏感值处理
│ └── mask.py # mask_secret、current secret hint、secret prompt
├── core/ # 底层策略和共享常量
│ ├── constants.py # -i/-I 文案、BACK_VALUE、checkbox indicator
│ ├── interactive.py # TTY 检测和 interactive 三态解析
│ └── errors.py # Click 友好的错误 helper
└── patterns.py # 跨模块组合模式：多来源值解析、文本/敏感值补问
推荐导入方式：
from chatstyle import CommandField, CommandSchema, resolve_command_inputs
from chatstyle.input import add_interactive_option
from chatstyle.tui import ask_select
from chatstyle.render import render_success
from chatstyle.security import mask_secretschema、resolve 和 click 组成声明式命令输入层。它负责字段声明、默认值、缺参补问、字段校验、跨字段约束和 -i/-I 接入。
prompt 和 choice 提供文本输入、路径输入、确认、单选、多选、全选控制和 choice/separator 构造。questionary、prompt_toolkit 延迟导入，不安装时 fallback 到 Click。
output 负责通用标题、提示、状态、建议命令、表格、列表、摘要和优先级链展示，Rich 可用时使用 Rich，不可用时 fallback 到 Click。flow 负责多步骤 CLI 流程的阶段、成功、警告、失败、计划和 dry-run 展示。setup 类需求通过通用 flow/output 组合实现，不单独作为核心模块。
mask 负责敏感值脱敏和敏感输入。interactive、errors、constants 负责 TTY 判断、interactive 状态、共享文案和错误展示。
本地开发：
pip install -e ".[dev]"项目依赖：
dependencies = ["chatstyle"]可选 TUI 增强依赖：
dependencies = ["chatstyle[tui]"]核心包只强依赖 Click。rich、questionary、prompt_toolkit 用于增强展示和选择体验；未安装时会 fallback 到 Click 文本交互。
import click
from chatstyle import (
CommandField,
CommandSchema,
add_interactive_option,
resolve_command_inputs,
)
DEMO_SCHEMA = CommandSchema(
name="demo",
fields=(
CommandField("name", prompt="name", required=True),
CommandField("output", prompt="output path", kind="path", default="./out.txt"),
CommandField("token", prompt="token", sensitive=True, prompt_if_missing=True),
),
)
@click.command()
@click.option("--name", required=False)
@click.option("--output", required=False)
@click.option("--token", required=False)
@add_interactive_option
def demo(name, output, token, interactive):
values = resolve_command_inputs(
schema=DEMO_SCHEMA,
provided={"name": name, "output": output, "token": token},
interactive=interactive,
usage="Usage: demo [--name TEXT] [--output PATH] [--token TEXT] [-i|-I]",
)
click.echo(f"run demo for {values['name']} -> {values['output']}")pip install -e ".[docs]"
mkdocs serve文档使用 mkdocs-static-i18n 的 suffix 模式：
- 中文默认站点使用
docs/*.md。 - 英文站点使用
docs/*.en.md，构建后位于/en/。 - Material 语言切换由 i18n plugin 生成。
更多内容：
docs/quickstart.md：添加新 CLI 和封装新交互接口的快速开始。docs/modules.md：模块板块和职责边界。docs/conventions.md：交互约定和行为规范。docs/development.md：开发规范和维护规则。docs/interaction-runtime.md：runtime 边界与下游用法。
python -m pytest -q
python -m build
mkdocs build --strict