```
feat(lzwcai-agile-db): 更新版本至0.4.4并优化数据库管理技能文档 - 更新版本号从0.4.2到0.4.4 - 优化API密钥权限管理说明，明确grant_api_key_permissions仅支持追加不支持撤销 - 新增add_sql_tool_to_datasource工具，提供一键创建SQL工具功能 - 调整create_sql_tool说明，强调需技能已存在 - 强化数据写操作安全机制，插入/更新/删除前必须预览并等待用户确认 - 完善导入数据功能说明，详细解释confirm_import_data参数传递方式 - 补充技能与工具管理流程，提供更清晰的操作指引 - 新增数字员工平台数据库技能配置指南文档 ```
This commit is contained in:
@@ -13,26 +13,55 @@ pip install -e .
|
||||
|
||||
## Python API
|
||||
|
||||
### 渲染文档
|
||||
### 核心入口 `generate` / `scan_template`
|
||||
|
||||
```python
|
||||
from lzwcai_mcpskills_generate_reports import generate
|
||||
from lzwcai_mcpskills_generate_reports import generate, scan_template
|
||||
|
||||
# 扫描模板需要哪些占位符 / for / if 块
|
||||
result = scan_template("./模板.docx") # 本地路径或 http/https URL
|
||||
|
||||
# 渲染
|
||||
out_path = generate(
|
||||
data="data.json", # dict 或 JSON 文件路径
|
||||
template="./模板.docx", # 用户自己的 docx 模板路径
|
||||
template="./模板.docx", # 本地路径或 http/https URL（自动下载）
|
||||
out_path="_out/报价方案.docx",
|
||||
style_ref="./用户样式.docx", # 可选：把用户模板的 theme/字体套过来
|
||||
)
|
||||
```
|
||||
|
||||
### 扫描模板占位符
|
||||
### 便捷封装 `main` 模块
|
||||
|
||||
`main` 模块在核心入口之上做了两点增强，适合程序化调用：
|
||||
|
||||
1. `data` 除 dict / 本地 JSON 路径外，还支持 **JSON 文件 URL**（自动下载、用完即删）。
|
||||
2. `out` **可省略**；省略时落到当前目录 `_out/`，文件名按 `模板名_时间戳.docx` 自动生成。
|
||||
|
||||
```python
|
||||
from lzwcai_mcpskills_generate_reports import scan_template
|
||||
from lzwcai_mcpskills_generate_reports.main import generate_report, scan_report
|
||||
|
||||
result = scan_template("./模板.docx")
|
||||
print(result)
|
||||
# data 传 dict，out 省略 -> 默认 _out/ 下自动命名
|
||||
generate_report(template="./模板.docx", data={...})
|
||||
|
||||
# data 传本地 JSON 路径
|
||||
generate_report(template="./模板.docx", data="data.json", out="_out/a.docx")
|
||||
|
||||
# template / data 都传 URL
|
||||
generate_report(
|
||||
template="https://host/模板.docx",
|
||||
data="https://host/data.json",
|
||||
)
|
||||
|
||||
# 扫描占位符，支持本地路径或 URL
|
||||
scan_report(template="https://host/模板.docx")
|
||||
```
|
||||
|
||||
`generate_report` 返回 `{"output": 输出文件绝对路径}`。
|
||||
|
||||
### 扫描结果结构
|
||||
|
||||
```python
|
||||
# scan_template / scan_report 返回：
|
||||
# {
|
||||
# "placeholders": ["project_title", "contact_person", "equipments", ...],
|
||||
# "blocks": [
|
||||
@@ -43,30 +72,16 @@ print(result)
|
||||
# }
|
||||
```
|
||||
|
||||
## 命令行
|
||||
|
||||
```powershell
|
||||
# 渲染
|
||||
generate-report generate --template ./模板.docx --data data.json --out _out/报价方案.docx
|
||||
|
||||
# 扫描占位符
|
||||
generate-report scan --template ./模板.docx
|
||||
|
||||
# 样式迁移
|
||||
generate-report generate --template ./模板.docx --data data.json --style-ref ./用户样式.docx --out _out/报价方案_定制.docx
|
||||
```
|
||||
|
||||
## MCP Server
|
||||
|
||||
本包同时提供 MCP Server（stdio 模式），把渲染引擎暴露成 3 个 MCP 工具：
|
||||
本包同时提供 MCP Server（stdio 模式），把渲染引擎暴露成 2 个 MCP 工具：
|
||||
|
||||
| 工具 | 说明 | 必填参数 |
|
||||
|------|------|----------|
|
||||
| `generate_report` | 模板 + 数据 → 渲染输出 docx，返回输出文件绝对路径 | `template`, `data`, `out`（可选 `style_ref`） |
|
||||
| `scan_template` | 扫描模板占位符与 for/if 块结构 | `template` |
|
||||
| `validate_report_data` | 校验数据契约（不渲染） | `data` |
|
||||
| 工具 | 说明 | 参数 |
|
||||
|------|------|------|
|
||||
| `generate_report` | 模板 + 数据 → 渲染输出 docx，返回输出文件绝对路径 | 必填 `template`、`data`；可选 `out`（省略落到 `_out/` 自动命名）、`style_ref` |
|
||||
| `scan_template` | 扫描模板占位符与 for/if 块结构 | 必填 `template` |
|
||||
|
||||
其中 `data` 既可以传 JSON 对象，也可以传指向 JSON 文件的路径字符串。
|
||||
其中 `data` 既可以传 JSON 对象，也可以传指向 JSON 文件的路径或 URL 字符串；`template` 支持本地路径或 http/https URL。数据契约校验由 `generate_report` 内部自动完成（不合法会报错）。
|
||||
|
||||
### 启动
|
||||
|
||||
@@ -74,8 +89,8 @@ generate-report generate --template ./模板.docx --data data.json --style-ref .
|
||||
# 安装后用 console script 启动
|
||||
lzwcai-mcpskills-generate-reports
|
||||
|
||||
# 或直接运行入口模块
|
||||
python main.py
|
||||
# 或以模块方式运行
|
||||
python -m lzwcai_mcpskills_generate_reports.server
|
||||
```
|
||||
|
||||
### MCP 客户端配置示例
|
||||
@@ -92,6 +107,13 @@ python main.py
|
||||
|
||||
> stdio 模式下 stdout 被 MCP 协议占用，所有日志写入 `logs/` 目录与 stderr。
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `LOG_LEVEL` | `INFO` | 日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）。 |
|
||||
| `LZWCAI_INSECURE_SSL` | 关闭 | 设为 `1`/`true`/`yes` 时，下载模板/数据/图片**关闭 SSL 证书校验**。仅用于内网自签名证书等可信场景，生产慎用。 |
|
||||
|
||||
## 数据契约（QuoteData）
|
||||
|
||||
```json
|
||||
@@ -117,7 +139,11 @@ python main.py
|
||||
}
|
||||
```
|
||||
|
||||
图片字段约定：路径/URL → 真实图；`""` → 默认占位图；`None` → 不显示。
|
||||
- 必填顶层字段：`project_title`、`contact_person`、`contact_phone`、`requirements`。
|
||||
- `requirements` 传列表会自动拼成多行字符串。
|
||||
- `equipments[].index` 省略时自动从"四"起按中文数字补全（前三章固定为公司简介 / 客户要求 / 布局图）。
|
||||
- `params[].v` 允许为 `0`、空串等合法假值；仅当键缺失或值为 `null` 才算缺失。
|
||||
- 图片字段约定：路径/URL → 真实图；`""` → 默认占位图；`None` → 不显示。
|
||||
|
||||
## 目录结构
|
||||
|
||||
@@ -125,20 +151,23 @@ python main.py
|
||||
lzwcai_mcpskills_generate_reports/
|
||||
├── pyproject.toml
|
||||
├── README.md
|
||||
├── templates/ # 用户模板（示例，不在包内）
|
||||
├── main.py # 使用本包的示例脚本（仓库根，非包内）
|
||||
├── templates/ # 用户模板（示例，不在包内）
|
||||
│ └── standard/
|
||||
│ ├── template.docx
|
||||
│ └── meta.json
|
||||
├── samples/ # 示例数据（不在包内）
|
||||
├── samples/ # 示例数据（不在包内）
|
||||
│ └── sample_data.json
|
||||
└── lzwcai_mcpskills_generate_reports/ # Python 包
|
||||
├── __init__.py # 公共 API 入口
|
||||
├── cli.py # 命令行
|
||||
├── pipeline.py # 总入口
|
||||
├── schema.py # 数据契约 + 校验器
|
||||
├── render_quote.py # 渲染引擎
|
||||
├── style_transfer.py # 样式迁移
|
||||
└── template_scanner.py # 模板占位符扫描
|
||||
└── lzwcai_mcpskills_generate_reports/ # Python 包
|
||||
├── __init__.py # 公共 API 入口
|
||||
├── main.py # 程序化便捷封装（URL data / out 可省略）
|
||||
├── server.py # MCP Server (stdio)
|
||||
├── pipeline.py # 总入口
|
||||
├── schema.py # 数据契约 + 校验器
|
||||
├── render_quote.py # 渲染引擎
|
||||
├── style_transfer.py # 样式迁移
|
||||
├── template_scanner.py # 模板占位符扫描
|
||||
└── utils/ # 下载 / 日志等工具
|
||||
```
|
||||
|
||||
## 模板约定
|
||||
@@ -156,4 +185,4 @@ lzwcai_mcpskills_generate_reports/
|
||||
}
|
||||
```
|
||||
|
||||
- BUSINESS 逻辑（内置模板维护、模板市场等）交给包外的上层系统处理。
|
||||
- BUSINESS 逻辑（内置模板维护、模板市场等）交给包外的上层系统处理。
|
||||
|
||||
Reference in New Issue
Block a user