Structure the tech specs directory (#836)

Tech spec some subdirectories for different languages
2026-04-25 08:26:21 +02:00 · 2026-04-21 16:06:41 +01:00 · 2026-04-21 16:06:41 +01:00 · e7efb673ef
commit e7efb673ef
parent 48da6c5f8b
423 changed files with 0 additions and 0 deletions
--- a/docs/tech-specs/zh-cn/more-config-cli.zh-cn.md
+++ b/docs/tech-specs/zh-cn/more-config-cli.zh-cn.md
@ -0,0 +1,186 @@
+---
+layout: default
+title: "更高级的 CLI 技术规格"
+parent: "Chinese (Beta)"
+---
+
+# 更高级的 CLI 技术规格
+
+> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
+
+## 概述
+
+该规范描述了 TrustGraph 的增强型命令行配置功能，允许用户通过精细的 CLI 命令来管理单个配置项。 该集成支持四个主要用例：
+
+1.  **列出配置项**: 显示特定类型的配置键
+2.  **获取配置项**: 获取特定配置值
+3.  **设置配置项**: 设置或更新单个配置项
+4.  **删除配置项**: 删除特定配置项
+
+## 目标
+
+-   **精细控制**: 能够管理单个配置项，而不是批量操作
+-   **基于类型的列出**: 允许用户按类型探索配置项
+-   **单个项操作**: 提供获取/设置/删除单个配置项的命令
+-   **API 集成**: 利用现有的 Config API 进行所有操作
+-   **一致的 CLI 模式**: 遵循 TrustGraph 的标准 CLI 约定和模式
+-   **错误处理**: 提供无效操作的清晰错误消息
+-   **JSON 输出**: 支持结构化输出，用于程序化使用
+-   **文档**: 包含全面的帮助和用法示例
+
+## 背景
+
+目前，TrustGraph 通过 Config API 和一个名为 `tg-show-config` 的单一 CLI 命令来管理配置。 该命令显示整个配置。 虽然这对于查看配置有效，但缺乏精细的管理功能。
+
+目前存在以下限制：
+-   无法从 CLI 列出按类型配置项
+-   没有 CLI 命令用于检索特定配置值
+-   没有 CLI 命令用于设置单个配置项
+-   没有 CLI 命令用于删除特定配置项
+
+该规范通过添加四个新的 CLI 命令来解决这些问题，从而提供精细的配置管理。 通过将单个 Config API 操作暴露到 CLI 命令中，TrustGraph 可以：
+-   启用脚本化的配置管理
+-   允许用户按类型探索配置结构
+-   支持有针对性的配置更新
+-   提供精细的配置控制
+
+## 技术设计
+
+### 架构
+
+增强的 CLI 配置需要以下技术组件：
+
+1.  **tg-list-config-items**
+    -   列出指定类型的配置键
+    -   调用 Config.list(type) API 方法
+    -   输出配置键列表
+
+    模块：`trustgraph.cli.list_config_items`
+
+2.  **tg-get-config-item**
+    -   检索特定配置项
+    -   调用 Config.get(keys) API 方法
+    -   以 JSON 格式输出配置值
+
+    模块：`trustgraph.cli.get_config_item`
+
+3.  **tg-put-config-item**
+    -   设置或更新配置项
+    -   调用 Config.put(values) API 方法
+    -   接受类型、键和值参数
+
+    模块：`trustgraph.cli.put_config_item`
+
+4.  **tg-delete-config-item**
+    -   删除配置项
+    -   调用 Config.delete(keys) API 方法
+    -   接受类型和键参数
+
+    模块：`trustgraph.cli.delete_config_item`
+
+### 数据模型
+
+#### ConfigKey 和 ConfigValue
+
+这些命令使用来自 `trustgraph.api.types` 的现有数据结构：
+
+```python
+@dataclasses.dataclass
+class ConfigKey:
+    type : str
+    key : str
+
+@dataclasses.dataclass
+class ConfigValue:
+    type : str
+    key : str
+    value : str
+```
+
+这种方法允许：
+-   在 CLI 和 API 中保持数据的一致性
+-   类型安全的配置操作
+-   结构化输入/输出格式
+-   与现有的 Config API 集成
+
+### CLI 命令规范
+
+#### tg-list-config-items
+```bash
+tg-list-config-items --type <config-type> [--format text|json] [--api-url <url>]
+```
+-   **目的**: 列出给定类型的所有配置键
+-   **API 调用**: `Config.list(type)`
+-   **输出**:
+    -   `text` (默认): 键按换行分隔
+    -   `json`: 键的 JSON 数组
+
+#### tg-get-config-item
+```bash
+tg-get-config-item --type <type> --key <key> [--format text|json] [--api-url <url>]
+```
+-   **目的**: 获取特定配置项
+-   **API 调用**: `Config.get([ConfigKey(type, key)])`
+-   **输出**:
+    -   `text` (默认): 原始字符串值
+    -   `json`: JSON 编码的字符串值
+
+#### tg-put-config-item
+```bash
+tg-put-config-item --type <type> --key <key> --value <value> [--api-url <url>]
+tg-put-config-item --type <type> --key <key> --stdin [--api-url <url>]
+```
+-   **目的**: 设置或更新配置项
+-   **API 调用**: `Config.put([ConfigValue(type, key, value)])`
+-   **输入选项**:
+    -   `--value <字符串>`: 直接在命令行中提供的字符串值
+    -   `--stdin`: 从标准输入读取整个输入作为配置值
+    -   标准输入读取为原始文本 (保留换行符、空格等)
+    -   支持通过文件、命令或交互式输入
+
+#### tg-delete-config-item
+```bash
+tg-delete-config-item --type <type> --key <key> [--api-url <url>]
+```
+-   **目的**: 删除配置项
+-   **API 调用**: `Config.delete([ConfigKey(type, key)])`
+-   **输出**: 成功确认
+
+### 实现细节
+
+所有命令都遵循 TrustGraph 的标准 CLI 模式：
+-   使用 `argparse` 进行命令行参数解析
+-   导入和使用 `trustgraph.api.Api` 进行后端通信
+-   遵循现有 CLI 命令的相同错误处理模式
+-   支持标准 `--api-url` 参数，用于配置 API 端点
+-   提供描述性的帮助文本和用法示例
+
+#### 输出格式处理
+
+**文本格式 (默认)**:
+-   `tg-list-config-items`: 键按新行分隔，纯文本
+-   `tg-get-config-item`: 原始字符串值，无引号或编码
+
+**JSON 格式**:
+-   `tg-list-config-items`: 字符串数组 `["key1", "key2", "key3"]`
+-   `tg-get-config-item`: JSON 编码的字符串值 `"实际字符串值"`
+
+#### 输入处理
+
+**tg-put-config-item** 支持两种互斥的输入方法：
+-   `--value <字符串>`: 命令行中的直接字符串值
+-   `--stdin`: 从标准输入读取整个输入作为配置值
+-   标准输入读取为原始文本 (保留换行符、空格等)
+-   支持通过文件、命令或交互式输入
+
+## 安全性
+
+-   如果配置项包含敏感信息，如何安全地处理这些信息？
+-   如何验证用户输入，以防止恶意攻击？
+-   如何控制对配置项的访问权限？
+
+## 开放问题
+
+-   是否应该支持命令以批量操作 (多个键) 之外的单个项？
+-   成功确认消息应该使用哪种格式？
+-   用户应该如何发现和使用配置类型？